Audio mixer API

Description

The AXIS Audio mixer API contains the information on how to support a plugin framework capable of adding audio plugins to an audio chain. In this API, a plugin is something that can alter the audio stream in some way.

Model

The API uses audiomixer.cgi as its communications interface and supports the following methods:

Method	Description
getPluginSchema	Retrieves a JSON schema for a plugin setting.
getPluginsSettings	Retrieves the plugin settings for all plugin instances.
setPluginsSettings	Sets the plugin settings for all plugin instances.
getSupportedVersions	Retrieve a list of supported API versions.

Identification

• API Discovery: API Discovery service

Common examples

Audio plugins

The following examples are used when you want to modify the audio plugin settings.

Retrieve the plugin schema

Use this example to retrieve a unique set of properties for each plugin. The method in this example returns the plugin schema for each unique setting, containing a JSON schema for the settings object for a particular plugin.

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

JSON input parameters

{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getPluginSchema",
  "params": {
    "plugin": "automaticGainControl"
  }
}

Successful response

{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getPluginSchema",
  "data": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "automaticGainControl",
    "type": "object",
    "properties": {
      "target": {
        "type": "number",
        "description": "Desired output level",
        "minimum": -180,
        "maximum": 0
      },
      "dynamic_range": {
        "type": "number",
        "description": "Allowed dynamic range",
        "minimum": 0
      }
    }
  }
}

Error response

{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getPluginSchema",
  "error": {
    "code": 1100,
    "message": "Internal error"
  }
}

API references

• getPluginSchema

Retrieve plugin settings

Use this example to retrieve every added audio plugin setting for all available audio sources (devices, connection, busses).

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

JSON input parameters

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

Successful response

{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getPluginsSettings",
  "data": {
    "devices": [
      {
        "id": "0",
        "inputs": [
          {
            "id": "0",
            "plugins": [
              {
                "id": "automaticGainControl",
                "settings": {
                  "enabled": true,
                  "target": -6,
                  "dynamicRange": 3
                }
              },
              {
                "id": "voiceEnhancer",
                "settings": {
                  "enabled": true,
                  "noiseSuppression": -6
                }
              }
            ]
          }
        ]
        "outputs": [
          {
            "id": "0",
            "plugins": [
              {
                "id": "simpleEq",
                "settings": {
                  "enabled": true,
                  "band0": -16,
                  "band1": -12
                }
              }
            ]
          }
        ]
      }
    ]
  }
}

Error response

{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getPluginsSettings",
  "error": {
    "code": 1100,
    "message": "Internal error"
  }
}

API references

• getPluginsSettings

Set plugin settings

Use this example to implement the settings structure retrieved from the previous example. Please note that only parameters that are changed needs to be specified in the request, as non-specified parameters will retain their existing values.

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

JSON input parameters

{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "setPluginsSettings",
  "params": {
    "devices": [
      {
        "id": "0",
        "inputs": [
          {
            "id": "0",
            "plugins": [
              {
                "id": "automaticGainControl",
                "settings": {
                  "enabled": true,
                  "target": -2,
                  "dynamicRange": 4
                }
              },
              {
                "id": "voiceEnhancer",
                "settings": {
                  "enabled": false,
                  "noiseSuppression": -6
                }
              }
            ]
          }
        ],
        "outputs": [
          {
            "id": "0",
            "plugins": [
              {
                "id": "simpleEq",
                "settings": {
                  "enabled": true,
                  "band0": -16,
                  "band1": -12
                }
              }
            ]
          }
        ]
      }
    ]
  }
}

Successful response

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

Error response

{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "setPluginsSettings",
  "error": {
    "code": 1100,
    "message": "Internal error"
  }
}

API references

• setPluginsSettings

Retrieve available API versions

Use this example to retrieve a list containing available API versions on your connected devices and available plugins.

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

JSON input parameters

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

Successful response

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

Error response

{
  "apiVersion": "2.1",
  "context": "abc",
  "method": "getSupportedVersions",
  "error": {
    "code": 1100,
    "message": "Internal error"
  }
}

API references

• getSupportedVersions

API specifications

getPluginSchema

This method can be used when you want to retrieve the JSON schema for a settings object used in the response from the methods getPluginsSettings and setPluginsSettings.

Request

• Security level: Operator
• Method: POST

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

Request body syntax

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

Parameter	Description
apiVersion=<string>	The API version that should be used.
context=<string>	A text string echoed back in the corresponding response (optional).
method="getPluginSchema"	Specifies the API method.
plugin=<string>	The name of the plugin that retrieves the settings object JSON schema.

Return value - Success

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

Response body syntax

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

Parameter	Description
apiVersion=<string>	The API version that should be used.
context=<string>	The context string provided by the request (optional).
method="getPluginSchema"	Specifies the API method.
data.$schema=<string>	The URL to the core schema meta-schema.
data.title=<string>	The schema title.
data.type=<string>	The type of settings, most likely an object.
data.properties=<object>	A unique JSON schema describing the properties for the settings object returned in the response from getPluginsSettings and sent in the request to setPluginsSettings.

Return value - Error

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

Response body syntax

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

Error codes

See General error codes for a complete list of API specific errors.

getPluginsSettings

This method can be used when you want to retrieve the settings for all available plugins. Each plugin has a unique method for retrieving the current settings added to a specific device, as described in getPluginSchema.

Request

• Security level: Operator
• Method: POST

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

Request body syntax

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

Parameter	Description
apiVersion=<string>	The API version that should be used.
context=<string>	A text string echoed back in the corresponding response (optional).
method="getPluginsSettings"	Specifies the API method.

Return value - Success

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

Response body syntax

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": "getPluginsSettings",
  "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 should be used.
context=<string>	The context string provided by the request (optional).
method="getPluginsSettings"	Specifies the API method.
data=<object>	Container for method specific parameters.
data.devices[]=<list of audio devices>	List of available audio devices.
<audio device>.id	The audio device ID.
<audio device>.inputs[]=<list of inputs>	List of device inputs.
inputs.id	The input ID.
input.plugins[]=<list of plugin settings>	List of plugin settings.
plugins.id	The plugin instance identification.
plugins.settings=<object>	An object containing the settings parameters described in the response from getPluginSchema.
<audio device>.outputs[]=<list of outputs>	List of outputs in a device.
outputs.id	The output ID.
output.plugins[]=<list of plugin settings>	List of plugin settings.
plugins.id	The plugin instance identification.
plugins.settings=<object>	Object containing the settings parameters described by the response from getPluginSchema.

Return value - Error

• 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>
  }
}

Error codes

See General error codes for a complete list of API specific errors.

setPluginsSettings

This method can be used when you want to configure a plugin instance retrieved from using the getPluginsSettings method.

Request

• Security level: Operator
• Method: POST

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

Request body syntax

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": "setPluginsSettings",
  "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 should be used.
context=<string>	The context string provided by the request (optional).
method="setPluginsSettings"	Specifies the API method.
params=<object>	Container for the method specific parameters listed below.
data.devices[]=<list of audio devices>	List of available audio devices.
<audio device>.id	The audio device ID.
<audio device>.inputs[]=<list of inputs>	List of device inputs.
inputs.id	The input ID.
input.plugins[]=<list of plugin settings>	List of plugin settings.
plugins.id	The plugin instance identification.
plugins.settings=<object>	An object containing the settings parameters described in the response from getPluginSchema.
<audio device>.outputs[]=<list of outputs>	List of outputs in a device.
outputs.id	The output ID.
output.plugins[]=<list of plugin settings>	List of plugin settings.
plugins.id	The plugin instance identification.
plugins.settings=<object>	Object containing the settings parameters described by the response from getPluginSchema.

Return value - Success

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

Response body syntax

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

Parameter	Description
apiVersion=<string>	The API version that should be used.
context=string	A text string echoed back from the corresponding request.
method="setPluginsSettings"	Specifies the API method.

Return value - Error

• 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>
  }
}

Error codes

See General error codes for a complete list of API specific errors.

getSupportedVersions

This method can be used when you want to retrieve a list of API versions supported by your device. The list will consist of the supported major versions along with their highest supported minor version.

Request

• Security level: Operator
• Method: POST

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

Request body syntax

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

Parameter	Description
context=<string>	A text string echoed back in the corresponding response (optional).
method="getSupportedVersions"	Specifies the API method.

Return value - Success

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

Response body syntax

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

Parameter	Description
context=<string>	The context string provided by the request (optional).
method="getSupportedVersions"	Specifies the API method.
data.apiVersions[]=<list of versions>	Lists the supported major versions along with their highest supported minor version.
<list of versions>	Lists the <Major>.<Minor> versions, e.g. ["1.2", "3.4"]

Return value - Error

• 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>
  }
}

Error codes

See General error codes for a complete list of API specific errors.

General error codes

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.