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 40dB
• Sound levels below 40dB 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:

• 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

⚠️

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 2 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 40dB
• 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 1 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 1 zone of a each type. Since there is currently only 1 defined zone type, the array will contain either 0 or 1 zones. This will change when more zone types are defined in future releases.

Learn more about zones

Overview

Use Get sound location data stream to start the sound location data stream.

Instructions

⚠️

Before you begin

Learn how to add your IP address or hostname and make a WebSocket connection to the configured IP and port of the server.

Step 1 - Send the request

1. Use the Get sound location data stream command to a make a request to get the sound location data:
2. Pass "v1/devices/audioLocation" in to the request property
3. Fill in requestId and clientId according to the request format guide
4. Send the request

The example request below will get the sound location data.

{
  "request": "v1/devices/audioLocation",
  "requestId": "94486c98-fd25-458e-84ae-df5376fab2a2",
  "clientId": "test"
}

Step 2 - Parse the response

The example response below indicates that:

1. The audio direction angle is 40 degrees
2. The sound power level is 10 decibels
3. The location of the sound is 2,999 millimeters left of the bar 0 (i.e. port 1) and 28,458 millimeters in front of the bar
4. The location information was generated on July 19, 2023 at 6:08 p.m.
5. There was 1 camera switching zone triggered as a result of this sound location event. The zone was labeled "Zone 1" and has a unique id of "48c83112-8f24-4417-acb1-0eef6da78244"

{
  "request": "v1/devices/audioLocation",
  "requestId": "94486c98-fd25-458e-84ae-df5376fab2a2",
  "clientId": "test",
  "body": {
    "azimuth": 40,
    "powerLevel": 10,
    "coordinates": { "x": -2999, "y": 2845 },
    "time": "2023-07-19T18:08:18.374Z",
    "triggeredZones": [{
      "type": "Switching",
      "label": "Zone 1",
      "id": "48c83112-8f24-4417-acb1-0eef6da78244"
    }]
  }
}

Once the initial request is made, sound location data registered by the 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 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.