Change balance control volume levels

📘

Only HDX systems support this feature.

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

What are the balance control volume levels?

The volume levels allow users to control the volume of the individual audio bars. This is different from overall system volume because each audio bar can have its own configuration.

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 volume levels of the audio bars, one for "Conference" mode and one for "Music" mode. Currently, only the volume levels 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 volume levels. Each element consists of a port and a corresponding volume level:

• port: The port the audio bar is plugged into on the system hub. This is a number between 1 and 6 inclusive.
• volumeLevel: The volume level of the audio bar. This is a number between 0 and 100 inclusive. The default value is 100.

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 channels 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 volume levels.

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

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

Set the volume levels for the audio bars

Step 1 - Make a request to get the current volume levels

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'

6. If the call is successful, an HTTP status code of 200 OK will be returned.
7. 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 "Conference" mode:
  • The audio bar plugged into port 1 has a volume level of 100.
  • The audio bars plugged into ports 2 and 5 have a volume level of 80.
  • The audio bar plugged into port 6 has a volume level of 90.
• The "Music" mode configuration is the same as the "Conference" mode configuration.
  • Note that the "Music" mode volume levels are not currently used.

{
  "adaptiveSoundModes": [
    {
      "mode": "Conference",
      "balance": [
        {
          "port": 1,
          "volumeLevel": 100
        },
        {
          "port": 2,
          "volumeLevel": 80
        },
        {
          "port": 5,
          "volumeLevel": 80
        },
        {
          "port": 6,
          "volumeLevel": 90
        }
      ]
    },
    {
      "mode": "Music",
      "balance": [
        {
          "port": 1,
          "volumeLevel": 100
        },
        {
          "port": 2,
          "volumeLevel": 80
        },
        {
          "port": 5,
          "volumeLevel": 80
        },
        {
          "port": 6,
          "volumeLevel": 90
        }
      ]
    }
  ]
}

Step 2 - Make a request to update the volume levels

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 volume levels.

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": "Mono"},{"port": 2,"channel": "Mono"},{"port": 5,"channel": "Mono"},{"port": 6,"channel": "Mono"}]},{"mode": "Music","balance": [{"port": 1,"volumeLevel": 100},{"port": 2,"volumeLevel": 90},{"port": 5,"volumeLevel": 90},{"port": 6,"volumeLevel": 80}],"channels": [{"port": 1,"channel": "Mono"},{"port": 2,"channel": "Mono"},{"port": 5,"channel": "Mono"},{"port": 6,"channel": "Mono"}]}]}'

7. Send the PATCH request.
8. 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 settings for the audio bars 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'

6. If the call is successful, an HTTP status code of 200 OK will be returned.
7. 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",
      "balance": [
        {
          "port": 1,
          "volumeLevel": 100
        },
        {
          "port": 2,
          "volumeLevel": 90
        },
        {
          "port": 5,
          "volumeLevel": 90
        },
        {
          "port": 6,
          "volumeLevel": 80
        }
      ]
    },
    {
      "mode": "Music",
      "balance": [
        {
          "port": 1,
          "volumeLevel": 100
        },
        {
          "port": 2,
          "volumeLevel": 90
        },
        {
          "port": 5,
          "volumeLevel": 90
        },
        {
          "port": 6,
          "volumeLevel": 80
        }
      ]
    }
  ]
}

✅

Tutorial complete!

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