Audio Analytics

The VAPIX® Audio Analytics API provides the information that makes it possible to manage the settings for an audio plugin framework.

Overview

The API implements audioanalytics.cgi as its communications interface and supports the following methods:

Method	Description
getPluginsSchemas	Lists the JSON schema for all settings related to an analytics plugin.
getPluginsSettings	Lists the plugin settings for all plugin instances.
setPluginsSettings	Applies the plugin settings for all plugin instances.
getSupportedVersions	Lists all API versions supported by your device.

This API works with the Audio Device Control API, which can be used to configure hardware devices. The Audio Analytics API can then be used to configure the audio analytics features on the devices.

Identification

• API Discovery: id=audio-analytics

Common examples

Audio analytics plugin

These examples will show you how to configure an existing audio analytics plugin. A plugin is made to analyze and react to an audio signal received from an audio source. Each plugin has its own unique settings object that can be used by the set/get methods detailed below.

getPluginsSchemas

Each plugin has its own individual settings object. This means that the method getPluginsSchemas will return the JSON schema for all analytics plugins.

http://<servername>/axis-cgi/audioanalytics.cgi

JSON input parameters

{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getPluginsSchemas",
  "params": {}
}

Parse the JSON response.

Successful response example

{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getPluginsSchemas",
  "data": {
    "schemas": [
      {
        "$schema": "http://json-schema.org/draft/2020-12/schema#",
        "title": Adaptive Audio Detection",
        "type": "object",
        "properties": {
          "threshold": {
            "type": "number",
            "description": "Required threshold (dBFs) for detection",
            "minimum": -180,
            "maximum": 0
          },
          "enable": {
            "type": "boolean",
            "description": "Enable detection"
          }
        }
      },
      {
        "$schema": "http://json-schema.org/draft/2020-12/schema#",
        "title": "Classification",
        "id": "Classification",
        "type": "object",
        "properties": {
          "enable": {
            "title": "Enable",
            "type": "boolean",
            "description": "Enable classification"
          }
        }
      }
    ]
  }
}

Error response example

{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getPluginsSchemas",
  "error": {
    "code": 2104,
    "message": "Invalid parameter value specified."
  }
}

See getPluginsSchemas for additional details.

getPluginsSettings

Return added audio plugin settings for all audio sources. The properties in the settings object are unique to the plugin and are described by the JSON schema returned with getPluginsSchemas.

http://<servername>/axis-cgi/audioanalytics.cgi

JSON input parameters

{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getPluginsSettings",
  "params": {}
}

Parse the JSON response.

Successful response example

{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getPluginsSettings",
  "data": {
    "devices": [{
      "id": "0",
      "inputs": [{
        "id": "0",
        "plugins": [{
          "id": "AdaptiveAudioDetection",
          "settings": {
            "enabled": true,
            "threshold": -6
          }
        },
        {
          "id": "DirectionOfArrival",
          "settings": {
            "enable": true
          }
        }]
      }],
      "outputs": [{
        "id": "0",
        "plugins": [{
          "id": "AggressionDetection",
          "settings": {
            "enable": true,
            "level": 0
          }
        }]
      }]
    }]
  }
}

Error response example

{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getPluginsSettings",
  "error": {
    "code": 2100,
    "message": "The requested API version is not supported."
  }
}

See getPluginsSettings for additional details.

setPluginsSettings

The settings returned by getPluginsSettings can be used to configure the plugins with the following request. Descriptions for the settings can be requested with the method getPluginsSchemas.

http://<servername>/axis-cgi/audioanalytics.cgi

JSON input parameters

{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "setPluginsSettings",
  "params": {
    "devices": [{
      "id": "0",
      "inputs": [{
        "id": "0",
        "plugins": [{
          "id": "AdaptiveAudioDetection",
          "settings": {
            "enable": false,
            "threshold": -3
          }
        },
        {
          "id": "DirectionOfArrival",
          "settings": {
            "enable": false
          }
        }]
      }],
      "outputs": [{
        "id": "0",
        "plugins": [{
          "id": "AggressionDetection",
          "settings": {
            "enable": true,
            "level": 2
          }
        }]
      }]
    }]
  }
}

Parse the JSON response.

Successful response example

{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "setPluginsSettings"
}

Error response example

{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "setPluginsSettings",
  "error": {
    "code": 2104,
    "message": "Invalid parameter value specified."
  }
}

See setPluginsSettings for additional details.

Retrieve supported API versions

This example will show you how to list all API versions supported by your device.

http://<servername>/axis-cgi/audioanalytics.cgi

JSON input parameters

{
  "context": "abc",
  "method": "getSupportedVersions"
}

Successful response example

{
  "apiVersion": "2.1",
  "context": "abc",
  "method": "getSupportedVersions",
  "data": {
    "apiVersions": ["1.3","2.1"]
  }
}

Error response example

{
  "apiVersion": "2.1",
  "context": "abc",
  "method": "getSupportedVersions",
  "error": {
    "code": 2100,
    "message": "The requested API version is not supported."
  }
}

See getSupportedVersions for additional details.

API specifications

getPluginsSchemas

This method should be used when you want to retrieve the JSON schema for a settings object originating from the getPluginsSettings response, or in the request set by setPluginsSettings.

Request

• Security level: Operator
• Method: POST

http://myserver/axis-cgi/audioanalytics.cgi

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": "getPluginsSchema",
  "params": {
    "plugin": <string>
  }
}

Parameter	Description
apiVersion=<string>	The API version that should be used.
context=<string> Optional	The user sets this value and the server echoes it back in the response.
method="getPluginsSchemas"	The method that should be used.
plugin=<string>	The plugin name.

Return value - Success

• HTTP Code: 200 OK
• Content-Type: application/json

Response body syntax

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": "getPluginsSchemas",
  "data": {
    "schemas": [
      {
        "$schema": <string>,
        "title": <string>,
        "id": <string>,
        "type": <string>,
        "properties": <object>
  }
}

Parameter	Description
apiVersion=<string>	The API version that was used in the request.
context=<string> Optional	The context set by the user in the request.
method="getPluginsSchemas"	The requested method.
data=<object>	Container for method specific parameters.
data.schemas[]=<list of plugin schemas>	List of available plugin schemas.
<plugin schema>.$schema=<string>	The URL for the core schema meta-schema.
<plugin schema>.title=<string>	The schema title.
<plugin schema>.id=<string>	Identification of the plugin.
<plugin schema>.type=<string>	The settings type, usually an object.
<plugin schema>.properties=<object>	A unique JSON schema describing the properties of the settings objects returned by getPluginsSettings and sent in the request by setPluginsSettings. All JSON schemas has a link to the version used in the node property $schema. The plugin uses draft/2020-12 to describe the properties. This means that a deviation will be explained if it occur from draft/2020-12. Example of a schema version:"$schema": "http://json-schema.org/draft/2020-12/schema#"

Return value - Failure

• HTTP Code: 200 OK
• Content-Type: application/json

Response body syntax

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": "getPluginsSchemas",
  "error": {
    "code": <integer error code>,
    "message". <string>
  }
}

Parameter	Description
apiVersion=<string>	The API version that was used in the request.
context=<string> Optional	The context set by the user in the request.
method="getPluginsSchemas"	The requested method.
error.code=<integer error code>	The error code.
error.message=<string>	The error message for the corresponding error code.

Error codes

See General error codes for a complete list of potential errors.

getPluginsSettings

This method should be used when you want to retrieve the settings for all plugins. The plugins all have their own settings object, detailed by the response from getPluginsSchemas.

Request

• Security level: Operator
• Method: POST

http://myserver/axis-cgi/audioanalytics.cgi

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": "getPluginsSettings"
}

Parameter	Description
apiVersion=<string>	The API version that should be used.
context=<string> Optional	The user sets this value and the server echoes it back in the response.
method="getPluginsSetting"	The method that should be used.

Return value - Success

• HTTP Code: 200 OK
• Content-Type: application/json

Response body syntax

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": "getPluginsSetting",
  "data": {
    "devices": [{
      "id": <string>,
      "inputs": [{
        "id": <string>,
        "plugins": [{
          "id": <string>,
          "settings": <object>
        }]
      }],
      "outputs": [{
        "id": <string>,
        "plugins": [{
          "id": <string>,
          "settings": <object>
        }]
      }]
    }]
  }
}

Parameter	Description
apiVersion=<string>	The API version that was used in the request.
context=<string> Optional	The context set by the user in the request.
method="getPluginsSettings"	The requested method.
data=<object>	Container for the parameters listed below.
data.devices[]=<list of audio devices>	Lists all available audio devices.
<audio device>.id	The audio device id.
<audio device>.inputs[]=<list of inputs>	Lists the device inputs.
inputs.id	The input id.
input.plugins[]=<list of plugin settings>	Lists the plugin settings.
plugins.id	The plugin instance id.
plugins.settings=<object>	An object containing settings parameters detailed by the response from getPluginsSchemas.
<audio device>.outputs[]=<list of outputs>	Lists the device outputs.
outputs.id	The output id.
output.plugins[]=<list of plugin settings>	Lists the plugin settings.
plugins.id	The plugin instance id.
plugins.settings=<object>	An object containing the settings parameters detailed in the response from getPluginsSchemas.

Return value - Failure

• HTTP Code: 200 OK
• Content-Type: application/json

Response body syntax

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": "getPluginsSettings",
  "error": {
    "code": <integer error code>,
    "message". <string>
  }
}

Parameter	Description
apiVersion=<string>	The API version that was used in the request.
context=<string> Optional	The context set by the user in the request.
method="getPluginsSettings"	The requested method.
error.code=<integer error code>	The error code.
error.message=<string>	The error message for the corresponding error code.

Error codes

See General error codes for a complete list of potential errors.

setPluginsSettings

This method should be used when you want to configure a plugin to work with the response from getPluginsSettings.

Request

• Security level: Operator
• Method: POST

http://myserver/axis-cgi/audioanalytics.cgi

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": "setPluginsSetting",
  "params": {
    "devices": [{
      "id": <string>,
      "inputs": [{
        "id": <string>,
        "plugins": [{
          "id": <string>,
          "settings": <object>
        }]
      }],
      "outputs": [{
        "id": <string>,
        "plugins": [{
          "id": <string>,
          "settings": <object>
        }]
      }]
    }]
  }
}

Parameter	Description
apiVersion=<string>	The API version that was used in the request.
context=<string> Optional	The context set by the user in the request.
method="setPluginsSettings"	The requested method.
params=<object>	Container for method specific parameters listed below.
data.devices[]=<list of audio devices>	List containing all available audio devices.
<audio device>.id	The audio device id.
<audio device>.inputs[]=<list of inputs>	Lists the device inputs.
inputs.id	The input id.
input.plugins[]=<list of plugin settings>	Lists the plugin settings.
plugins.id	The plugin instance id.
plugins.settings=<object>	An object containing settings parameters detailed by the response from getPluginsSchemas.
<audio device>.outputs[]=<list of outputs>	Lists the device outputs.
outputs.id	The output id.
output.plugins[]=<list of plugin settings>	Lists the plugin settings.
plugins.id	The plugin instance id.
plugins.settings=<object>	An object containing settings parameters detailed by the response from getPluginsSchemas.

Return value - Success

• HTTP Code: 200 OK
• Content-Type: application/json

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": "setPluginsSettings"
}

Parameter	Description
apiVersion=<string>	The API version that should be used.
context=<string> Optional.	The user sets this value and the server echoes it back in the response.
method="setPluginsSettings"	The method that should be used.

Return value - Failure

• HTTP Code: 200 OK
• Content-Type: application/json

Response body syntax

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": "setPluginsSettings",
  "error": {
    "code": <integer error code>,
    "message". <string>
  }
}

Parameter	Description
apiVersion=<string>	The API version that was used in the request.
context=<string> Optional.	The context set by the user in the request.
method="setPluginsSettings"	The requested method.
error.code=<integer error code>	The error code.
error.message=<string>	The error message for the corresponding error code.

Error codes

See General error codes for a complete list of potential errors.

getSupportedVersions

This method should be used when you want to request a list of all API versions supported by your device.

Request

• Security level: Operator
• Method: POST

http://myserver/axis-cgi/audioanalytics.cgi

{
  "context": <string>,
  "method": "getSupportedVersions",
}

Parameter	Description
context=<string> Optional	The context set by the user in the request.
method="getSupportedVersions"	The requested method.

Return value - Success

• HTTP Code: 200 OK
• Content-Type: application/json

{
  "context": <string>,
  "method": "getSupportedVersions",
  "data": {
    "apiVersions": ["<Major1>.<Minor1>", "<Major2>.<minor2>"]
  }
}

Parameter	Description
context=<string> Optional	The user sets this value and the server echoes it back in the response.
method="getSupportedVersions"	The method that should be used.
data.apiVersions[]=<list of versions>	A list containing all supported major versions along with their highest minor version, e.g. ["1.2", "3.4"].

Return value - Failure

• HTTP Code: 200 OK
• Content-Type: application/json

Response body syntax

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": "getSupportedVersions",
  "error": {
    "code": <integer error code>,
    "message". <string>
  }
}

Parameter	Description
apiVersion=<string>	The API version that was used in the request.
context=<string> Optional	The context set by the user in the request.
method="getSupportedVersions"	The requested method.
error.code=<integer error code>	The error code.
error.message=<string>	The error message for the corresponding error code.

Error codes

See General error codes for a complete list of potential errors.

General error codes

The following table consist of errors that may occur for any method. Errors specific to a method are listed under their separate API description.

Code	Definition	Description
1100	INTERNAL_ERROR	Internal error.
2100	UNSUPPORTED_API_VERSION	The requested API version is not supported.
2101	JSON_INVALID_ERROR	The provided JSON input was invalid.
2102	METHOD_NOT_SUPPORTED	Method not supported.
2103	JSON_KEY_NOT_FOUND	A mandatory input parameter was not found in the input.
2104	PARAM_INVALID_VALUE_ERROR	Invalid parameter value specified.
2105	AUTHORIZATION_ERROR	Authorization failed.
2106	AUTHENTICATION_ERROR	Authentication failed.
2107	TRANSPORT_LEVEL_ERROR	Transport Level Error.