Get audio component layout

📘

Only HDL410 systems support this feature.

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

What audio component layout information is available?

• 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.
  • hardwareId: The hardware identifier of the audio device.
  • 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.
• computedAudioComponentPositions: The default 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.
  • hardwareId: The hardware identifier of the audio device.
  • 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 endpoint. The origin is defined as the center back of the primary audio component.

Minimum role required: general

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

Overview

1. Use the Get Room Layout endpoint to get the current audio component layout.
2. Check that the request was successful and parse the response.

Instructions

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

Use the Get Room Layout Information endpoint to a make a request to get the audio component layout information for the room where the Nureva® audio conferencing system is connected:

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 - Parse the response

The example response below indicates that:

• The audio component positions have been verified by a user.
• The primary audio component has the audio component position identifier "AUDIO_BAR_0" and hardware identifier "AA5739B68CA3", since it is positioned at the origin.
• The secondary audio component has the audio component position identifier "AUDIO_BAR_1" and hardware identifier "AA1885B68CA3".
• The user-configured values of the secondary audio component position are as follows:
  • "x": 9100 meaning, 9100 mm from the primary audio component along the x-axis.
  • "y": 10432 meaning, 10432 mm from the primary audio component along the y-axis.
  • "z": 0 meaning, the same position as the primary audio component along the z-axis.
  • "zAngle": 180 meaning, it is rotated 180 degrees from the direction that the primary audio component is facing in the x-y plane.
• The computed values for the secondary audio component position are as follows:
  • "x": 9000 meaning, 9000 mm from the primary audio component along the x-axis.
  • "y": 10668 meaning, 10668 mm from the primary audio component along the y-axis.
  • "z": 0 meaning, the same position as the primary audio component along the z-axis.
  • "zAngle": 180 meaning, it is rotated 180 degrees from the direction that the primary audio component is facing in the x-y plane.

{
  "audioComponentPositionsVerified": true,
  "audioComponentPositions": [
    {
      "id": "AUDIO_BAR_0",
      "hardwareId": "AA5739B68CA3",
      "x": 0,
      "y": 0,
      "z": 0,
      "zAngle": 0
    },
    {
      "id": "AUDIO_BAR_1",
      "hardwareId": "AA1885B68CA3",
      "x": 9100,
      "y": 10432,
      "z": 0,
      "zAngle": 180
    }
  ],
  "computedAudioComponentPositions": [
    {
      "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": 180
    }
  ]
}

✅

Tutorial complete!

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