Allows clients to retrieve sound location data, including audio direction angle, sound power level and (in some cases) the coordinates of the location.
Once the initial request is made, sound location data registered by the connected audio device will start streaming at a regular interval. The data will be streamed provided the WebSocket connection is open and the data can be retrieved.
If an error occurs, the WebSocket will respond with the appropriate status code. If a Nureva® device firmware update is in progress, a status code will be returned and sound location data streaming will be paused. Once the firmware update is complete, sound location data streaming will resume automatically.
Request
{
"request": "v1/devices/audioLocation",
"requestId": string,
"clientId": string
}
Response
{
"request": "v1/devices/audioLocation",
"requestId": string,
"clientId": string,
"body": {
"azimuth": number,
"powerLevel": number,
"coordinates": { "x": number, "y": number } | undefined,
"time": string,
"triggeredZones": [{
"type": "Switching",
"label": string,
"id": string,
}[] | undefined
}
}
Use the azimuth field only for HDL300, HDL310 and Dual HDL300 systems.
Use the coordinates field instead of the azimuth field for HDL410 systems.
| azimuth | Only for use with HDL300, HDL310 and Dual HDL300 systems. Audio direction angle in degrees. Range -70 to 70, e.g., 65. |
| powerLevel | Sound power level in decibels, e.g., 30. |
| coordinates | Available for HDL410 systems only. The x, y coordinates of the location in millimeters. Bar 0’s (i.e., Port 1) location is taken as the origin (0, 0) of the coordinate system, where positive y values are positioned in front of the bar. Negative and positive x values are to the left and right of the bar, respectively, when facing in the same direction as the bar. |
| time | ISO 8601 time string for the time the location information was generated, e.g., "2022-06-07T09:01:23.486Z". |
| triggeredZones | Available for HDL410 systems only. An array of 0 or more zones that have been triggered by this sound location data event. The array will only ever have elements for HDL410 devices that have zones configured by an end user through Nureva Console and there will be at most 1 zone of a given type.
|
Errors
| Status code | Description |
|---|---|
| 10000 – Bad request | Request does not conform to the specification. The message field will include detailed information about which part of the request is incorrect. |
| 11000 – Unsupported device | Connected hardware device does not support audio location streaming. |
| 11001 – Device not connected | No audio device is connected. |
| 11002 – Interrupted by firmware update | If a firmware update is being applied to a connected Nureva device, audio location information will be unavailable until that update is complete. An error code will be supplied. |
| 11003 – Audio location unavailable | Audio location information is not available. A general use error in the event we cannot retrieve and send audio location. |
| 11004 – Microphone is muted | Microphone is muted. |
| 11005 – Speaker bar is disconnected | Speaker bar is disconnected. |
Sample requests
1. Valid request/response
Request
{
"request": "v1/devices/audioLocation",
"requestId": "3abe203s-42b7-4b0b-9awaf-5c381793a192",
"clientId": "test"
}
Response
{
"request": "v1/devices/audioLocation",
"requestId": "3abe203s-42b7-4b0b-9awaf-5c381793a192",
"clientId": "test",
"body": {
"azimuth": -35,
"powerLevel": 0,
"coordinates": {
"x": -2890,
"y": 2936
},
"time": "2022-07-15T15:07:23.375Z",
"triggeredZones": [{
"type": "Switching",
"label": "Zone 1",
"id": "unique identifier"
}]
}
}
2. Invalid request - no requestId or clientId
Request
{
"request": "v1/devices/audioLocation",
"requestId": "",
"clientId": ""
}
Response
{
"request": "v1/devices/audioLocation",
"requestId": "",
"clientId": "",
"errors": [
{
"statusCode": 10000,
"message": "clientId: String can't be empty or whitespace"
},
{
"statusCode": 10000,
"message": "requestId: String can't be empty or whitespace"
}
]
}
3. Unsupported device
This is a valid request, but returns an error because an unsupported audio device is connected.
Request
{
"request": "v1/devices/audioLocation",
"requestId": "3abe203s-42b7-4b0b-9awaf-5c381793a192",
"clientId": "test"
}
Response
{
"request": "v1/devices/audioLocation",
"requestId": "3abe203s-42b7-4b0b-9awaf-5c381793a192",
"clientId": "test",
"errors": [
{
"statusCode": 11000,
"message": "Unsupported device"
}
]
}