Start sound location data stream

This tutorial shows how to retrieve sound location data from Nureva® audio devices over the local network. Sound location data returns information about the loudest sound detected in the room at a given time. Once an initial request is made, sound location data registered by the audio device will start streaming at a regular interval.

What sound location data is available for HDL300, HDL310 and Dual HDL300 devices?

The sound location data provided for these devices consists of:

• azimuth: The audio direction angle, measured in degrees
• powerLevel: The sound power level, measured in decibels
• time: The timestamp when the location information was detected

Azimuth measurement

The audio direction angle is measured in degrees. The range is -70 to 70 degrees.

For HDL300 and HDL310 devices, this angle is relative to the center of the microphone and speaker bar.

For Dual HDL300 devices, this angle is relative to the center of the microphone and speaker bar that is connected to the port labeled “1” on the connect module.

Sound level

The sound level is measured in decibels (dB).

• Normal voice levels are typically above 40 dB
• Sound levels below 40 dB are typically background noises

📘

Note: A sound level of 0 dB means that no meaningful sound has been detected in the room. Location data (azimuth) when sound level is 0 dB can be ignored.

What sound location data is available for HDL410 devices?

For HDL410 devices, sound location data consists of:

• version: The version of the sound location data body (version: 2 includes extra data under the flags property)
• azimuth: The audio direction angle, measured in degrees
• powerLevel: The sound power level, measured in decibels
• coordinates: The x, y coordinates of the location of the sound, in millimeters from the origin
• time: The timestamp when the location information was detected
• triggeredZones: The zone triggered by this sound location data event (if one exists). Returns an array that will contain either 0 or 1 elements. Contains the following fields:
  • type: The type of zone that was triggered. Currently, the only possible value of this string is "Switching"
  • label: The label associated with the triggered zone
  • id: A unique identifier
• flags: The flags included alongside the sound location data to assist in differentiating the type of source the data originated from. NOTE: These flags are for debugging purposes only and are not needed for normal integration operation. They are also subject to change and should not be counted on to exist in future versions.
  • powerZeroedReason: The reason for emitting a sound power level of 0. Possible values are:
    • 0: Power level is not zeroed
    • 1: The room speaker is making sound because a remote participant is speaking
    • 2: The meeting participant in the room using the microphone plugged into the aux in is speaking
    • 3: No human speech was detected
  • speakerActive: Indicates if the room speaker was making sound due to a remote participant speaking. Possible values are:
    • true
    • false
  • voiceAmpModeActive: Indicates if there is a meeting participant in the room actively using the microphone plugged into the aux in. Possible values are:
    • true
    • false
  • voiceDetected: Indicates if human speech was detected. Possible values are:
    • true
    • false

⚠️

Do not use azimuth data with HDL410

Although the azimuth field is provided for HDL410 devices, it should not be used. Use the coordinates field for HDL410 devices as it supports a wider variety of room configurations.

For forward compatibility, clients should use the coordinates field when available and fall back to use the azimuth field only when the coordinates field is unavailable.

Coordinate system

The location of the sound data is returned via x and y coordinates.

Position (0,0) represents the center of the microphone and speaker bar that is connected to the port labeled “1” on the connect module.

Actual maximum x and y values will vary by room, depending on the arrangement of the two microphone and speaker bars. However, the range of possible values is as follows:

• The x-coordinate values can be anywhere between -8,382 and 8,382 (8,382 mm to the left and to the right of the microphone and speaker bar plugged into port 1)
• The y-coordinate values can be anywhere between 1 and 16,764 (16,764 mm from the front of the microphone and speaker bar plugged into port 1)

The range of possible values is illustrated in the following diagram. Note that these values may not correlate to the size and shape of the actual room.

Sound level

The sound level is measured in decibels (dB).

• Normal voice levels are typically above 40 dB
• Sound levels below 40 dB are typically background noises

📘

Note: A sound level of 0 dB means that no meaningful sound has been detected in the room. Location data (azimuth and coordinates) when sound level is 0 dB can be ignored.

Triggered zones

Defining zones allows you to trigger events when sound is detected within a zone. For example, you can set up a meeting room system to select a particular camera angle when a particular zone is triggered.

If the detected sound is located within a defined zone, the triggeredZones field will return the information for that zone.

Triggered zone information includes:

• type: The zone type
  • There is currently only one zone type available: "Switching"
  • Future releases will include other zone types
• label: The label given to the zone, defined by end users in Nureva Console
• id: A unique identifier

This data is returned as an array. When there are no elements in the array, it means that no zone was triggered. There can be at most one zone of each type. Since there is currently only one defined zone type, the array will contain either zero or one zones. This will change when more zone types are defined in future releases.

Learn more about zones

Minimum role required: general

The Start Sound Location Data Stream endpoint can be accessed with the general role or any role of a higher level.

Overview

1. Use Start Sound Location Data Stream endpoint to start streaming sound location data.
2. Check that the request was successful.

Instructions

Step 1 - Send a request to open an SSE connection

Use Start Sound Location Data Stream endpoint to open an SSE connection to start streaming sound location data:

1. Set the path with the IP address of the Nureva device followed by /api/v1/data.
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 connect to the SSE data endpoint for the device with the IP address of 10.0.0.1.

curl --request GET \
     --url https://10.0.0.1/api/v1/data \
     --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 stream events

Once the SSE connection is established, events tagged with the soundLocation tag will be emitted on intervals of 200 ms.

The example response below indicates that:

1. "azimuth": 50 - The audio direction angle is 50 degrees
2. "powerLevel": 40 - The sound power level is 40 decibels
3. "time": "2024-10-15T17:44:13.329Z" - The location information was generated on October 15, 2024 at 5:44 p.m.
4. "coordinates": { "x": 2324, "y": 1893 } - The location of the sound is 2,324 millimeters left of the bar 0 (i.e. port 1) and 1,893 millimeters in front of the bar
5. "triggeredZones": [ { "type": "Switching", "label": "Zone 1", "id": "b60a6ff0-e79d-4fe9-b7e0-cc0cd3dd3fe0" } ] - There was one camera switching zone triggered as a result of this sound location event. The zone was labeled "Zone 1" and has a unique id of "b60a6ff0-e79d-4fe9-b7e0-cc0cd3dd3fe0"
6. "version": 2 - The response body has a version 2 tag, meaning it includes flags for far end energy detection.
7. "flags": { "powerZeroedReason": 0, "speakerActive": false, "voiceAmpModeActive": false, "voiceDetected": true } - The sound power level was a non-zero value. The room speaker bar was not making sound, there was not a meeting room participant in the room using the microphone plugged into the aux in, and the detected sound location data was detected to be human speech.

{
  "azimuth": 50,
  "powerLevel": 44,
  "time": "2024-10-15T17:44:13.329Z",
  "coordinates": {
    "x": 2324,
    "y": 1893
  },
  "triggeredZones": [
    {
      "type": "Switching",
      "label": "Zone 1",
      "id": "b60a6ff0-e79d-4fe9-b7e0-cc0cd3dd3fe0"
    }
  ],
  "version": 2,
  "flags": {
    "powerZeroedReason": 0,
    "speakerActive": false,
    "voiceAmpModeActive": false,
    "voiceDetected": true
  }
}

The sound location events will continue streaming until the connection is closed.
If an error occurs, the SSE connection will respond with an appropriate error code. If a Nureva device firmware update is in progress, an error 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.

✅

Tutorial complete!

You now know how to get sound location data.