Set audio component layout

📘

This feature is supported by Dual HDL300 and HDL410 systems.

This tutorial shows how to set the audio component layout of the room where Nureva® audio devices are located.

What can be controlled with the API?

• audioComponentPositionsVerified: Whether or not a user has verified the audio component positions. Possible values are:
  • true
  • false
• audioComponentPositions: The user-configured list of positions of the audio devices of the room. All numeric values are in millimeters. Each audio component position is defined by the following attributes:
  • id: The audio component position identifier.
  • x: The x-coordinate of the center back of the audio component, relative to the origin. The primary audio component will always have a x-coordinate value of zero.
  • y: The y-coordinate of the center back of the audio component, relative to the origin. The primary audio component will always have a y-coordinate value of zero.
  • z: The z-coordinate of the center back of the audio component, relative to the origin. The primary audio component will always have a z-coordinate value of zero.
  • zAngle: The angle of the audio device in the x-y plane in degrees. The primary audio component will always have a zAngle of value zero. For HDL410 devices, only values of 0, 90, 180, and 270 degrees are possible.

The same coordinate system is used for audio component positions, zone positions and sound location data. Refer to the coordinate system diagram in the Start Device Data Stream tutorial. The origin is defined as the center back of the primary audio component.

Validations

Dual HDL300 & HDL410

• The audio component positions cannot be modified such that one or more audio components would be partially or fully outside of the room. Refer to the Get room dimensions endpoint to get the room layout information.
• Only 90 degree increments for zAngle are permitted. Ex. 0, 90, 180, 270

Minimum role required: integrator

The Set room layout endpoint can be accessed with the integrator role or any role of a higher level.

Overview

1. Use the Get room layout endpoint to get the current audio component layout.
2. Use the Set room layout endpoint to make a request to change the audio component layout.
3. Use the Get room layout endpoint to check that the change has been applied successfully.

Instructions

Step 1 - Make a request to get the current audio component layout

Use the Get room layout endpoint:

1. Set the path with the IP address of the Nureva® device followed by /api/v1/room/layout.
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/room/layout \
     --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.

Step 2 - Make a request to update the audio component layout

Use the Set room layout endpoint:

1. Set the path with the IP address of the Nureva® device followed by /api/v1/room/layout.
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 audio component layout

curl --request PATCH \
     --url https://10.0.0.1/api/v1/room/layout \
     --header 'Authorization: Nureva Z2VuZXJhbDo=' \
     --header 'Nureva-Client-Id: integration_app_name' \
     --header 'Nureva-Client-Version: 0.0.1'\
     --header 'Content-type: application/json' \
     --data '{"audioComponentPositionsVerified":true,"audioComponentPositions":[{"id":"AUDIO_BAR_0","x":0,"y":0,"z":0,"zAngle":0},{"id":"AUDIO_BAR_1","x":9000,"y":10668,"z":0,"zAngle":90}]}'

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 room layout endpoint:

1. Set the path with the IP address of the Nureva® device followed by /api/v1/room/layout.
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/room/layout \
     --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 audioComponentPositions matches the audioComponentPositions sent in step 2.

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

{
  "audioComponentPositionsVerified": true,
  "audioComponentPositions": [
    {
      "id": "AUDIO_BAR_0",
      "hardwareId": "AA5739B68CA3",
      "x": 0,
      "y": 0,
      "z": 0,
      "zAngle": 0
    },
    {
      "id": "AUDIO_BAR_1",
      "hardwareId": "AA1885B68CA3",
      "x": 9000,
      "y": 10668,
      "z": 0,
      "zAngle": 90
    }
  ]
}

✅

Tutorial complete!

You now know how to set the audio component layout information.