Set audio component layout
Only HDL410 systems support this feature.
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 azAngle
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.
Validations
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
integrator
The Set Room Layout endpoint can be accessed with the integrator
role or any role of a higher level.
Overview
- Use the Get Room Layout endpoint to get the current audio component layout.
- Use the Set Room Layout endpoint to make a request to change the audio component layout.
- 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 Information endpoint:
- Set the path with the IP address of the Nureva® device followed by
/api/v1/room/layout
. - Update the headers to include
Authorization
as key and the value beingNureva
followed by theauthParameters
received from the login endpoint. - Update the headers to include
Nureva-Client-Id
as key andintegration_app_name
as the value. - Update the headers to include
Nureva-Client-Version
as key and0.0.1
as the value. - 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'
- 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 Information endpoint:
- Set the path with the IP address of the Nureva® device followed by
/api/v1/room/layout
. - Update the headers to include
Authorization
as key and the value beingNureva
followed by theauthParameters
received from the login endpoint. - Update the headers to include
Nureva-Client-Id
as key andintegration_app_name
as the value. - Update the headers to include
Nureva-Client-Version
as key and0.0.1
as the value. - Update the headers to include
Content-type
as key andapplication/json
as value. - 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}]}'
- Send the PATCH request.
- 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 Information endpoint:
- Set the path with the IP address of the Nureva® device followed by
/api/v1/room/layout
. - Update the headers to include
Authorization
as key and the value beingNureva
followed by theauthParameters
received from the login endpoint. - Update the headers to include
Nureva-Client-Id
as key andintegration_app_name
as the value. - Update the headers to include
Nureva-Client-Version
as key and0.0.1
as the value. - 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'
- If the call is successful, an HTTP status code of 200 OK will be returned.
- Check that the value of
audioComponentPositions
matches theaudioComponentPositions
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.
Updated 4 days ago