Configure audio component layout

📘

This feature is supported by HDL300, Dual HDL300, HDL310, HDL410, and HDX systems for retrieving audio component layout information. However, updating audio component positions is currently only supported for Dual HDL300 and HDL410 systems.

This tutorial shows how to configure 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 an 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.
• computedAudioComponentPositions: The default list of positions of the audio devices of the room (NOTE: these values cannot be set and are to only be used for reference). All coordinate values are in millimeters and all angles are in degrees. Each audio component position is defined by the following attributes:
  • id: The audio component position identifier.
  • hardwareId: The hardware identifier of the audio component.
  • x: The x-coordinate of the center back of the audio component, relative to the origin. The primary audio component will always have an 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 component in the x-y plane in degrees. The primary audio component will always have a zAngle of value zero. Only values of 0, 90, 180, and 270 degrees are possible.
  • mount: This attribute is only available for HDX devices. This value describes how the audio component is mounted. Possible values for this attribute are "WALL", "STAND", and "CEILING". Only microphone pods can have a "CEILING" mount. The "CEILING" mount applies to both ceiling and table mounted microphone pods.
  • mountAngle: This attribute is only available for HDX devices. This attribute only applies to audio components with a mount of "WALL" or "STAND". This value describes the angle of rotation of the audio component about its center in degrees. Only values of 0, 90, and 270 degrees are possible since the audio component cannot be mounted upside down.
  • ceilingMount: This attribute is only available for HDX devices. This attribute is only available for microphone pods where the value for mount is "CEILING". Possible values for this attribute are "DOWN" and "UP". A value of "DOWN" indicates that the microphone pod is mounted on the ceiling. A value of UP indicates that the microphone pod is placed flat on a table.

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 Configure room dimensions tutorial to get the room layout information.
• Only 90 degree increments for zAngle are permitted. Ex. 0, 90, 180, 270

admin role required

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

The Set room layout endpoint is restricted to the admin role. To access this endpoint, follow the Authorization tutorial to authenticate with an admin role and obtain YOUR_ADMIN_AUTHPARAMETERS which is required for the requests below.

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 <YOUR_ADMIN_AUTHPARAMETERS>' \
     --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 <YOUR_ADMIN_AUTHPARAMETERS>' \
     --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 <YOUR_ADMIN_AUTHPARAMETERS>' \
     --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 configure the audio component layout information.