Audio relay service API

The Audio Relay service provides configuration mechanisms for connecting audio peers to each other. An audio relay network can be altered by adding and removing audio peers. Status monitoring of the audio peers is provided.

An audio relay network is based on one audio peer being a leader, and the rest of the peers being followers. The audio content intended for the audio relay network shall be provided by the leader, which will stream the audio content to its followers.

The Audio Relay service also provides sound configuration, for adjusting the master volume of an audio relay network. The audio peers' output gain is also provided via the audio peer configuration. The master volume applies to all peers in the audio relay network, while output gain is separate for each audio peer.

Please note that this API has been deprecated as of firmware version 10.12 and will no longer receive any updates.

Identification

Terminology and abbreviations

This section will show common use cases for this service. General concepts are discussed, and details are provided in the detailed specification.

Most examples use pseudocode to illustrate the intended flow of requests to the Audio Relay service and data will be shown in JavaScript Object Notation (JSON).

API calls can be encoded in either JSON format or in a key-value format referred to as "simple", which flattens out a structure to key=value strings, where each level in a structure is separated by underscore ('_') when encoding the key.

Boolean values are encoded as true or false, and the NULL value is encoded as null.

String values are URL-encoded and may start and end with quotation marks, e.g. "a+string%0A".

Character sets are not converted or validated by the service, but UTF-8 is recommended.

Simple cURL examples

$ curl --anyauth -s "http://root:pass@192.168.0.90/vapix/audiorelay"
   -d'{"axar:SetAudioPeerConfigurations": {"Configuration": [
      {"Id":"1",
       "Address": {"IPAddress":"192.168.0.90"},
       "Leader":true},
      {"Id":"2",
       "Address": {"MAC": "00:40:8C:18:00:01"},
       "Leader":false} ]}}'
{
  "AudioPeerId":
    [
      "1",
      "2"
    ]
}

$ curl --anyauth -s "http://root:pass@192.168.0.90/vapix/audiorelay? ...
  format=simple&action=axar:SetAudioPeerConfigurations& ...
  Configuration_0_Id=1&Configuration_0_Address_IPAddress=192.168.0.1&Configuration_0_Leader=true& ...
  Configuration_1_Id=2&Configuration_1_Address_MAC=00:40:8C:18:00:00&Configuration_1_Leader=false"


AudioPeerId_0="1"
AudioPeerId_1="2"

$ curl --anyauth -s "http://root:pass@192.168.0.90/vapix/audiorelay"
   -d'{"axar:GetAudioPeers":{}}'
{
  "Peer":
    [
      {
        "Configuration": {
          "Id": "1",
          "Address": {
            "IPAddress": "192.168.0.90",
            "MAC": "00:40:8C:18:00:00"
          },
          "Leader": true,
          "Credentials": {
            "User": "root",
            "Password": null
          },
          "OutputGain":
            [
              {
                "Name": "AudioSource.A0.OutputGain",
                "Value": "0"
              }
            ]
        },
        "MetaData": {
          "Type": "C2005"
        },
        "ConnectionStatus": "Online",
        "OutputGainDefinitions":
          [
            {
              "Name": "AudioSource.A0.OutputGain",
              "Range":
                [
                  "Mute",
                  "-57",
                  ... ,
                  "6"
                ]
            }
          ]
      },
      {
        "Configuration": {
          "Id": "2",
          "Address": {
            "IPAddress": "192.168.0.91",
            "MAC": "00:40:8C:18:00:01"
          },
          "Leader": false,
          "Credentials": {
            "User": "root",
            "Password": null
          },
          "OutputGain":
            [
              {
                "Name": "AudioSource.A0.OutputGain",
                "Value": "0"
              }
            ]
        },
        "MetaData": {
          "Type": "C1004-E"
        },
        "ConnectionStatus": "Online",
        "OutputGainDefinitions":
          [
            {
              "Name": "AudioSource.A0.OutputGain",
              "Range":
                [
                  "Mute",
                  "-57",
                  ... ,
                  "6"
                ]
            }
          ]
      }
    ]
}

$ curl --anyauth -s "http://root:pass@192.168.0.90/vapix/audiorelay? ...
  format=simple&action=axar:GetAudioPeers"


Peer_0_Configuration_Id="2"
Peer_0_Configuration_Address_IPAddress="192.168.0.91"
Peer_0_Configuration_Address_MAC="00:40:8C:18:00:01"
Peer_0_Configuration_Leader=false
Peer_0_Configuration_Credentials_User="root"
Peer_0_Configuration_Credentials_Password=null
Peer_0_Configuration_OutputGain_0_Name="AudioSource.A0.OutputGain"
Peer_0_Configuration_OutputGain_0_Value="0"
Peer_0_MetaData_Type="C1004-E"
Peer_0_ConnectionStatus="Online"
Peer_0_OutputGainDefinitions_0_Name="AudioSource.A0.OutputGain"
Peer_0_OutputGainDefinitions_0_Range_0="Mute"
Peer_0_OutputGainDefinitions_0_Range_1="-57"
...
Peer_0_OutputGainDefinitions_0_Range_64="6"
Peer_1_Configuration_Id="1"
Peer_1_Configuration_Address_IPAddress="192.168.0.90"
Peer_1_Configuration_Address_MAC="00:40:8C:18:00:00"
Peer_1_Configuration_Leader=true
Peer_1_Configuration_Credentials_User="root"
Peer_1_Configuration_Credentials_Password=null
Peer_1_Configuration_OutputGain_0_Name="AudioSource.A0.OutputGain"
Peer_1_Configuration_OutputGain_0_Value="0"
Peer_1_MetaData_Type="C2005"
Peer_1_ConnectionStatus="Online"
Peer_1_OutputGainDefinitions_0_Name="AudioSource.A0.OutputGain"
Peer_1_OutputGainDefinitions_0_Range_0="Mute"
Peer_1_OutputGainDefinitions_0_Range_1="-57"
...
Peer_1_OutputGainDefinitions_0_Range_64="6"

Add audio peer

{
  "axar:SetAudioPeerConfiguration": {
    "Configuration": {
      "Name":"lobby speaker left",
      "Address": {"IPAddress":"192.168.0.92"}
    }
  }
}

{
  "AudioPeerId": "AudioPeer_03"
}

format=simple&action=axar:SetAudioPeerConfiguration& ...
Configuration_Name=lobby%20speaker%20left&Configuration_Address_IPAddress=192.168.0.92

AudioPeerId="AudioPeer_03"

Remove audio peer

{
  "axar:RemoveAudioPeer": {
    "AudioPeerId": "AudioPeer_03"
  }
}

{}

format=simple&action=axar:RemoveAudioPeer&AudioPeerId=AudioPeer03

Rename audio peer and change its output gain

{
  "Configuration": {
    "Id": "AudioPeer_01",
    "Name": "SpeakerX",
    "Address": {
      "IPAddress": "192.168.0.90",
      "MAC": "00:40:8C:18:00:00"
    },
    "Leader": true,
    "Credentials": {
      "User": "root",
      "Password": null
    },
    "OutputGain":
      [
        {
          "Name": "AudioSource.A0.OutputGain",
          "Value": "0"
        }
      ]
  }
}

{
  "axar:SetAudioPeerConfiguration": {
    "Configuration": {
      "Id": "AudioPeer_01"
      "Name": "lobby speaker left",
      "OutputGain": [ {
        "Name": "AudioSource.A0.OutputGain",
        "Value": "-6"
      } ],
      "Address":{}
    }
  }
}

{
  "AudioPeerId": "AudioPeer_01"
}

format=simple&action=axar:SetAudioPeerConfiguration& ...
Configuration_Id=AudioPeer_01&Configuration_Name=lobby%20speaker%20left& ...
Configuration_OutputGain_0_Name=AudioSource.A0.OutputGain& ...
Configuration_OutputGain_0_Value=-6

AudioPeerId="AudioPeer_01"

Setup audio relay network using multicast

{
  "axar:SetAudioPeerConfigurations": {
    "Configuration": [ {
      "Id":"1",
      "Address": {"IPAddress":"192.168.0.90"},
      "Leader":true
    }, {
      "Id":"2",
      "Address": {"IPAddress":"192.168.0.91"}
    } ],
    "AudioNetworkConfiguration": {
      "MulticastEnabled": true
    }
  }
}

{
  "AudioPeerId": [
    "1",
    "2"
  ]
}

format=simple&action=axar:SetAudioPeerConfigurations& ...
  Configuration_0_Id=1&Configuration_0_Address_IPAddress=192.168.0.90&Configuration_0_Leader=true& ...
  Configuration_1_Id=2&Configuration_0_Address_IPAddress=192.168.0.91& ...
  AudioNetworkConfiguration_MulticastEnabled=true"

AudioPeerId_0="1"
AudioPeerId_1="2"

Change multicast settings in existing audio relay network

{
  "axar:SetAudioNetworkConfiguration": {
    "AudioNetworkConfiguration": {
      "MulticastEnabled": true
    }
  }
}

{
  "MulticastGroup": "239.168.0.90"
}

format=simple&action=axar:"SetAudioNetworkConfiguration&AudioNetworkConfiguration_MulticastEnabled=true"

"MulticastGroup": "239.168.0.90"

Adjust the master volume

{
  "axar:SetSoundConfiguration": {
    "Configuration": {
      "MasterVolume":0,
      "MasterVolumeUnit":"dB"
    }
  }
}

{}

format=simple&action=axar:SetSoundConfiguration& ...
Configuration_MasterVolume=0&Configuration_MasterVolumeUnit="dB"

Monitor audio relay peers status

{
  "axar:GetAudioPeerStatus": {}
}

{
  "PeerStatus": [ {
    "Id": "AudioPeer_02",
    "ConnectionStatus": "Offline"
  }, {
    "Id": "AudioPeer_01",
    "ConnectionStatus": "Online"
  } ]
}

format=simple&action=axar:GetAudioPeerStatus

PeerStatus_0_Id="AudioPeer_02"
PeerStatus_0_ConnectionStatus="Offline"
PeerStatus_1_Id="AudioPeer_01"
PeerStatus_1_ConnectionStatus="Online"

Common data types

The GetServices call can be used to retrieve the capabilities of the service, to handle future extensions.

Range

Describes a range of valid values and the unit. The following fields are available:

ServiceCapabilities

The structure of ServiceCapabilities reflects the optional functionality of a service. The information is static and does not change during device operation. The following capabilities are available:

GetServiceCapabilities command

This operation returns the capabilities of the service.

{}

The request is empty.

{
  "Capabilities": {
    "ServiceCapabilities"
  }
}

AudioPeerCredentials

The credentials for accessing an audio peer at the time of setup. The following fields are available:

AudioPeerAddress

The address of an audio peer. The following fields are available and each is optional:

Gain definition

A definition for the gain controls of a device.

The following fields are available:

AudioPeerMetaData

Metadata information for an audio peer.

The following fields are available:

Gain

A gain control for a device.

The following fields are available:

AudioPeerConfiguration

The configuration of a peer in the audio relay network.

the IP address or the MAC address is used to identify a peer. If the MAC address is given, it will be matched against discovered peers. The IP Address will be ignored if the MAC address is found via discovery, and a discovered IP address takes precedence over any current IP address.

If only the IP address is given (MAC is left empty), then a connection to this specific IP address will be used. Once a connection is established, the MAC address will be known and used in the configuration.

Credentials must be supplied when setting the audio peer configurations, if the devices are not accessible using default credentials. The supplied credential password will never be returned to a client upon a GetAudioPeers-call.

The following fields are available:

The following fields are optional:

AudioPeer

The Audio peer information of a peer in the audio relay network.

The following fields are available:

DiscoveredAudioPeer

The audio peer information as discovered on the current network.

The following fields are available:

AudioNetworkConfiguration

The configuration of parameters affecting the audio relay network as an entity.

The following fields are available but optional:

SetAudioPeerConfigurations command

Requests that a list of audio peers shall be set as the Audio Relay network.

The list of audio peer configurations must not contain more than one peer set as leader. The list must also always contain the address of the device that receives this request. The request will fail if these rules are violated.

This call replaces all of the existing AudioPeerConfigurations on the receiving device with the content of the Configuration parameter.

The optional parameter AudioNetworkConfiguration contain two members. MulticastEnabled may be set to true or false in order to enable/disable multicast support for the audio network. If this parameter is not set, unicast will be used. MulticastGroup may be set to a desired multicast group. If the parameter is not set, a default multicast group will be used.

{
  "Configuration": [{
    "AudioPeerConfiguration"
  },
  ...
  ]
}

{
  "AudioPeerId":
  "<AudioPeerId>"
}

SetAudioPeerConfiguration command

Requests that an audio peer be added or modified in the Audio Relay network.

The new AudioPeerConfiguration must not modify the Audio Relay network so that it would have more or less than one peer set as the leader.

The new AudioPeerConfiguration may have the ID field set or empty. If not set, or set to a non-existing ID, the call will be considered an 'add operation' of a new AudioPeerConfiguration. If set to an existing ID, the call will be considered to be a modify operation for an existing AudioPeerConfiguration.

{
  "Configuration": {
    "AudioPeerConfiguration"
  }
}

{
  "AudioPeerId":
  "<AudioPeerId>"
}

GetAudioPeers command

Returns the current Audio Relay network configuration of the device that receives this request.

AudioPeerIds that cannot be resolved will be ignored and an empty set may be returned if there are no audio peers matching specified IDs.

If no AudioPeerId is supplied, a list of all audio peers will be returned.

{
  "AudioPeerId": [
    "<AudioPeerId>",
  ...
  ]
}

{
  "Peer": [
    {
      "AudioPeer"
    },
    ...
  ]
}

GetDiscoveredAudioPeers command

Returns the Audio Relay peers discovered by the device that receives this request. The returned list is a snapshot and Audio Relay peers may both be added and removed in subsequent requests.

{}

The request is empty.

{
  "Peer": [
    {
      "DiscoveredAudioPeer"
    },
    ...
  ]
}

RemoveAudioPeer command

Removes an audio peer from the audio relay network. The ID must be for an audio peer other than the recipient of this request.

{
  "AudioPeerId":
  "<AudioPeerId>"
}

{}

The response is empty.

SetAudioNetworkConfiguration command

Modifies the audio network configuration for the Audio Relay Network.

The configuration for multicasting two parameters. MulticastEnabled may be set to “true” or “false” in order to enable/disable multicast support for the audio network, and if not set, unicast will be used. MulticastGroup may be set to a desired multicast group and if not set, a default multicast group will be generated.

{
  "AudioNetworkConfiguration": {
    "AudioNetworkConfiguration"
  }
}

{
  "MulticastGroup": "<string>" (optional)
}

AudioPeerStatus

The Audio Peer status. The following fields are available:

GetAudioPeerStatus command

Returns the current status of the link between the leader and its followers in the configured Audio Peer network. It is the leader that tracks the status.

AudioPeerIds that cannot be resolved will be ignored and an empty set may be returned if there are no audio peers matching specified IDs.

If no AudioPeerIds are supplied, a list of all audio peers will be returned.

{
  "AudioPeerId": [
    "<AudioPeerId>",
    ...
  ]
}

{
  "PeerStatus": [{
    "AudioPeerStatus"
  },
  ...
  ]
}

SoundConfiguration

The configuration of parameters affecting the sound in the audio relay network.

Valid parameter values may be defined by the service capabilities.

The following fields are available, and all are optional:

SetSoundConfiguration command

Requests that a SoundConfiguration should be set on all the peers in the AudioPeerConfiguration.

All members of the SoundConfiguration are optional, thus a SoundConfiguration with all members empty will be accepted, but will change nothing.

{
  "Configuration": {
    "SoundConfiguration"
  }
}

{}

The response is empty.

GetSoundConfiguration command

Returns the SoundConfiguration of an Audio Relay network.

{}

The request is empty.

{
  "Configuration": {
    "SoundConfiguration"
  }
}