Change speaker volume

This tutorial shows how to change the speaker volume for Nureva® devices over the local network.

What can be controlled with the API?

The local control API offers the ability to increase or decrease the speaker volume for a Nureva audio device. The API mirrors the behavior of the volume up and down buttons on the remote control.

📘

The minimum volume is 0 and the maximum volume is 100. Trying to increase the speaker volume to beyond 100 or decrease it to below 0 will not change the volume.

Minimum role required: general

The Change Speaker Volume endpoint can be accessed with the general role or any role of a higher level.

Overview

1. Use Get Audio Settings to make a request to get the current speaker volume setting on the audio device.

2. Use Change Speaker Volume to a make a request to change the speaker volume on the audio device.

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

Instructions

Step 1 - Make a request to get the current speaker volume setting

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 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. Check the value of the speakerVolume attribute. The speakerVolume attribute is a property of the Nureva audio device, with the minimum value of 0 (no sound) and the maximum value of 20 (loudest sound). Since the operating system volume setting has a range of 0 to 100, each speakerVolume increment (or decrement) can be roughly (not exactly) translated to 5% operating system increment (or decrement).

The example response below indicates that the speaker volume is currently set to 14.

{
  "microphoneMute": false,
  "microphonePickupState": "Mono",
  "microphoneGain": 3,
  "speakerTrebleLevel": 90,
  "speakerBassLevel": 16,
  "speakerVolume": 14,
  "echoReductionLevel": "Medium",
  "noiseReductionLevel": "Medium",
  "auxiliaryOutputState": "LineLevel",
  "voiceAmplificationEnabled": false,
  "voiceAmplificationLevel": 25,
  "voiceAmplificationAuxInLevel": "Line",
  "dynamicBoostEnabled": false,
  "microphoneDuckingEnabled": false
}

Step 2 - Make a request to change the speaker volume

Use the Change Speaker Volume endpoint:

1. Set the path with the IP address of the Nureva device followed by /api/v1/audio/volume/change.
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. Add the property "operation" to the body property.
7. Give "operation" a value of either "increment" or "decrement" (case sensitive). This is a required property. The code sample below is a request to increment the speaker volume.
   • "increment" increments the volume by one step of 4-6 volume points (to a maximum of 100), as seen from the operating system
   • "decrement" decrements the volume by one step of 4-6 volume points (to a minimum of 0), as seen from the operating system

curl --request PUT \
     --url https://10.0.0.1/api/v1/audio/volume/change \
     --header 'Authorization: Nureva Z2VuZXJhbDo=' \
     --header 'Nureva-Client-Id: integration_app_name' \
     --header 'Nureva-Client-Version: 0.0.1'\
     --header 'Content-type: application/json' \
     --data '{"operation":"increment"}'

8. Send the PUT request.
9. 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 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. Check the value of the speakerVolume attribute.

The example below indicates that the change (to adjust speaker volume) was successfully applied.

{
  "microphoneMute": false,
  "microphonePickupState": "Mono",
  "microphoneGain": 3,
  "speakerTrebleLevel": 90,
  "speakerBassLevel": 16,
  "speakerVolume": 15,
  "echoReductionLevel": "Medium",
  "noiseReductionLevel": "Medium",
  "auxiliaryOutputState": "LineLevel",
  "voiceAmplificationEnabled": false,
  "voiceAmplificationLevel": 25,
  "voiceAmplificationAuxInLevel": "Line",
  "dynamicBoostEnabled": false,
  "microphoneDuckingEnabled": false
}

✅

Tutorial complete!

You now know how to get, increase and decrease the speaker volume.