Get audio component layout

📘

This feature is supported by HDL300, Dual HDL300, HDL410, and HDX devices.

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 components of the room. 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 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 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 mic pods can have a "CEILING" mount. The "CEILING" mount applies to both ceiling and table mounted mic 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 centre 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 mic pods where the value for mount is "CEILING". Possible values for this attribute are "DOWN" and "UP". A value of "DOWN" indicates that the mic pod is mounted on the ceiling. A value of "UP" indicates that the mic pod is placed flat on a table.
• computedAudioComponentPositions: The default list of positions of the audio devices of the room. 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 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 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 mic pods can have a "CEILING" mount. The "CEILING" mount applies to both ceiling and table mounted mic 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 centre 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 mic pods where the value for mount is "CEILING". Possible values for this attribute are "DOWN" and "UP". A value of "DOWN" indicates that the mic pod is mounted on the ceiling. A value of "UP" indicates that the mic 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 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 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 is for an HDL410 device. It 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.