Cloud APIsLocal APIs
Local Documentation
nureva.com
Start typing to search…

Change balance control channels

📘

Only HDX systems support this feature.

This tutorial shows how to change the balance control channels for the audio bars of a Nureva® HDX system over the local network.

What are the balance control channels?

Audio bars can be configured to play sound from specific channels. By default, they output audio from both the left and right channels (mono), but each audio bar can be individually set to play exclusively from either the left or right channel. This audio bar channel configuration is set via input number.

For more information about balance controls, see HDX Balance Controls↗


What can be controlled with the API?

The "adaptiveSoundModes" property consists of two lists configuring the channels of the audio bars, one for "Conference" mode and one for "Music" mode. Currently, only the channels for "Conference" mode are used.

Each list has one element for each connected audio bar, resulting in a maximum of four elements per list. Mic pods do not have balance control channels. Each element consists of a port and a corresponding channel:

  • port: The port the audio bar is plugged into on the system hub. This is a number between 1 and 6 inclusive.
  • channel: The channels that play audio for the audio bar. A value of Mono means that audio is played on both the left and right channels. Possible values are:
    • "Mono" (default)
    • "Left"
    • "Right"

To update the volume levels, all "adaptiveSoundModes" settings must be sent in the request payload. This includes:

  • The volume levels of all the audio bars for both "Conference" mode and "Music" mode
  • The channels of all the audio bars for both "Conference" mode and "Music" mode

Since "Music" mode is currently unused, use the same values for the channels and volume levels as provided for "Conference" mode.

Please refer to step 2 below for an example request payload and the Change balance control volume levels tutorial.


Minimum role required: general

The Get Audio Settings endpoint and Set Audio Settings endpoint can be accessed with the general role or any role of a higher level.

Overview

  1. Use the Get Audio Settings endpoint to get the channels.

  2. Use the Set Audio Settings endpoint to make a request to change the channels.

  3. Use the Get Audio Settings endpoint to check that the change has been applied successfully.


Set the channels for the audio bars

Step 1 - Make a request to get the channels

Use the Get Audio Settings endpoint:

  1. Set the path with the IP address of the Nureva device followed by /api/v1/audio.
  2. Update the headers to include Authorization as key and the value being Nureva followed by the authParameters received from the login endpoint.
  3. Update the headers to include Nureva-Client-Id as key and integration_app_name as the value.
  4. Update the headers to include Nureva-Client-Version as key and 0.0.1 as the value.
  5. Send the GET request. The code sample below is a request to retrieve the audio settings for the device with the IP address of 10.0.0.1.
curl --request GET \
     --url https://10.0.0.1/api/v1/audio \
     --header 'Authorization: Nureva Z2VuZXJhbDo=' \
     --header 'Nureva-Client-Id: integration_app_name' \
     --header 'Nureva-Client-Version: 0.0.1'
  1. If the call is successful, an HTTP status code of 200 OK will be returned.
  2. Look for "adaptiveSoundModes" in the response payload. The example response below indicates that:
  • There are four audio bars in the HDX system. They are plugged into ports 1, 2, 5, and 6 of the system hub.
  • In the "Conference" mode configuration:
    • The audio bar plugged into port 2 will play audio from the left channel.
    • The audio bar plugged into port 5 will play audio from the right channel.
    • The audio bars plugged into ports 1 and 6 will play audio from both channels.
  • The "Music" mode configuration is the same as the "Conference" mode configuration.
    • Note that "Music" mode channels are not currently used.
{
  "adaptiveSoundModes": [
    {
      "mode": "Conference",
      "channels": [
        {
          "port": 1,
          "channel": "Mono"
        },
        {
          "port": 2,
          "channel": "Left"
        },
        {
          "port": 5,
          "channel": "Right"
        },
        {
          "port": 6,
          "channel": "Mono"
        }
      ]
    },
    {
      "mode": "Music",
      "channels": [
        {
          "port": 1,
          "channel": "Mono"
        },
        {
          "port": 2,
          "channel": "Left"
        },
        {
          "port": 5,
          "channel": "Right"
        },
        {
          "port": 6,
          "channel": "Mono"
        }
      ]
    }
  ]
}

Step 2 - Make a request to update the balance control channels

Use the Set Audio Settings endpoint:

  1. Set the path with the IP address of the Nureva® device followed by /api/v1/audio.
  2. Update the headers to include Authorization as key and the value being Nureva followed by the authParameters received from the login endpoint.
  3. Update the headers to include Nureva-Client-Id as key and integration_app_name as the value.
  4. Update the headers to include Nureva-Client-Version as key and 0.0.1 as the value.
  5. Update the headers to include Content-type as key and application/json as value.
  6. Update the request body to send a JSON object with updated channels.
curl --request PATCH \
     --url https://10.0.0.1/api/v1/audio \
     --header 'Authorization: Nureva Z2VuZXJhbDo=' \
     --header 'Nureva-Client-Id: integration_app_name' \
     --header 'Nureva-Client-Version: 0.0.1'\
     --header 'Content-type: application/json' \
     --data '{"adaptiveSoundModes": [{"mode": "Conference","balance": [{"port": 1,"volumeLevel": 100},{"port": 2,"volumeLevel": 90},{"port": 5,"volumeLevel": 90},{"port": 6,"volumeLevel": 80}],"channels": [{"port": 1,"channel": "Left"},{"port": 2,"channel": "Right"},{"port": 5,"channel": "Left"},{"port": 6,"channel": "Right"}]},{"mode": "Music","balance": [{"port": 1,"volumeLevel": 100},{"port": 2,"volumeLevel": 90},{"port": 5,"volumeLevel": 90},{"port": 6,"volumeLevel": 80}],"channels": [{"port": 1,"channel": "Left"},{"port": 2,"channel": "Right"},{"port": 5,"channel": "Left"},{"port": 6,"channel": "Right"}]}]}'
  1. Send the PATCH request.
  2. If the call is successful, an HTTP status code of 200 OK will be returned.

Step 3 - Check that the change has been applied successfully

Use the Get Audio Settings endpoint:

  1. Set the path with the IP address of the Nureva® device followed by /api/v1/audio.
  2. Update the headers to include Authorization as key and the value being Nureva followed by the authParameters received from the login endpoint.
  3. Update the headers to include Nureva-Client-Id as key and integration_app_name as the value.
  4. Update the headers to include Nureva-Client-Version as key and 0.0.1 as the value.
  5. Send the GET request. The code sample below is a request to retrieve the audio component layout of the room of the device with the IP address of 10.0.0.1.
curl --request GET \
     --url https://10.0.0.1/api/v1/audio \
     --header 'Authorization: Nureva Z2VuZXJhbDo=' \
     --header 'Nureva-Client-Id: integration_app_name' \
     --header 'Nureva-Client-Version: 0.0.1'
  1. If the call is successful, an HTTP status code of 200 OK will be returned.
  2. Check that the value of adaptiveSoundModes matches the adaptiveSoundModes sent in step 2.

The example below indicates that the change was successfully applied, for the PATCH call in step 2.

{
  "adaptiveSoundModes": [
    {
      "mode": "Conference",
      "channels": [
        {
          "port": 1,
          "channel": "Left"
        },
        {
          "port": 2,
          "channel": "Right"
        },
        {
          "port": 5,
          "channel": "Left"
        },
        {
          "port": 6,
          "channel": "Right"
        }
      ]
    },
    {
      "mode": "Music",
      "channels": [
        {
          "port": 1,
          "channel": "Left"
        },
        {
          "port": 2,
          "channel": "Right"
        },
        {
          "port": 5,
          "channel": "Left"
        },
        {
          "port": 6,
          "channel": "Right"
        }
      ]
    }
  ]
}
✅

Tutorial complete!

You now know how to set the balance control channels of the audio bars.

Updated 4 days ago