Cloud APIsLocal APIs
Local Documentation
Supportnureva.com

External microphone

This tutorial provides a step-by-step guide to managing external microphone in a Nureva® audio system using the available API.

Supported devices

  • HDL300, Dual HDL300
  • HDL310, HDL410
  • HDX

What can be controlled with the API?

  • Add an external microphone to a Nureva system
  • Set (update) properties of an external microphone
  • Get information about configured external microphone
  • Remove an external microphone from the system

Minimum role required: general

The Get devices, Get device, Post devices, Update device and Delete device endpoints can be accessed with the general role (recommended) or any role of a higher level. Follow the Authorization tutorial to authenticate with a general role and obtain YOUR_GENERAL_AUTHPARAMETERS which is required for the requests below.

Overview

  1. Use Post devices to register new external microphone to the Nureva system.

  2. Use Get devices to make a request to get all peripheral configurations.

  3. Use Get device to get a specific peripheral configuration.

  4. Use Update device to update the peripheral configuration.

  5. Use Delete device to remove the peripheral from Nureva system.


Instructions

Step 1 - Make a request to register new peripheral to Nureva system

To add (register) a new external microphone, use the Post devices endpoint

  1. Set the path with the IP address of the Nureva device followed by /api/v1/room/devices.
  2. Update the headers to include Authorization as key and the value being Nureva followed by the authParameters received from the login endpoint using the general account.
  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 POST request with "deviceType": "adaptive-voice-amplification" and customName (optional). The code sample below is a request to add the external microphone for the Nureva device with the IP address of 10.0.0.1.

Example of request

HDL410, HDL310, Dual HDL300, HDL300
curl --request POST \
    --url https://10.0.0.1/api/v1/room/devices \
    --header 'Authorization: Nureva <YOUR_GENERAL_AUTHPARAMETERS>' \
    --header 'Nureva-Client-Id: integration_app_name' \
    --header 'Nureva-Client-Version: 0.0.1' \
    --header 'Content-Type: application/json' \
    --data '{
        "deviceType": "adaptive-voice-amplification",
        "customName": "External microphone"
    }'
HDX
curl --request POST \
    --url https://10.0.0.1/api/v1/room/devices \
    --header 'Authorization: Nureva <YOUR_GENERAL_AUTHPARAMETERS>' \
    --header 'Nureva-Client-Id: integration_app_name' \
    --header 'Nureva-Client-Version: 0.0.1' \
    --header 'Content-Type: application/json' \
    --data '{
        "deviceType": "adaptive-voice-amplification",
        "channelNumber": 1,
        "customName": "External microphone"
    }'
  1. If the call is successful, an HTTP status code of 200 OK and a generated device ID (UUID v4) will be returned.
{
  "deviceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Step 2 - Make a request to get all peripheral configurations

To get all peripheral configurations, use the Get devices endpoint

  1. Set the path with the IP address of the Nureva device followed by /api/v1/room/devices.
  2. Update the headers to include Authorization as key and the value being Nureva followed by the authParameters received from the login endpoint using the general account.
  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 peripherals for the Nureva device with the IP address of 10.0.0.1.

Example of request

curl --request GET \
    --url https://10.0.0.1/api/v1/room/devices \
    --header 'Authorization: Nureva <YOUR_GENERAL_AUTHPARAMETERS>' \
    --header 'Nureva-Client-Id: integration_app_name' \
    --header 'Nureva-Client-Version: 0.0.1' \
  1. If the call is successful, an HTTP status code of 200 OK and the Nureva device details together with all its peripherals will be returned.

Example of response

HDL410, HDL310, Dual HDL300, HDL300
{
  "devices": [
    {
      "deviceId": "MK072S69M025060",
      "deviceType": "nu-audio-device",
      "audioDeviceType": "hdl410",
      "deviceStatusColor": "green",
      "hardwareComponents": [
        {
          "portNumber": 1,
          "hardwareId": "AAFDE9C1E2E7",
          "connectionStatus": "Connected",
          "model": "Bar"
        },
        {
          "portNumber": 2,
          "hardwareId": "AAD7F5C1E2E7",
          "connectionStatus": "Connected",
          "model": "Bar"
        }
      ]
    },
    {
      "deviceType": "adaptive-voice-amplification",
      "deviceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "customName": "External microphone",
      "voiceAmplificationEnabled": true,
      "voiceAmplificationLevel": 30,
      "voiceAmplificationAuxInLevel": "Line",
      "microphoneDuckingEnabled": false,
      "voiceAmplificationGateThreshold": 64,
      "voiceAmplificationUsbOutputGainLevel": 10
    }
  ]
}
HDX
{
  "devices": [
    {
      "deviceId": "MK072S69M025060",
      "deviceType": "nu-audio-device",
      "audioDeviceType": "HDX",
      "deviceStatusColor": "green",
      "hardwareComponents": [
        {
          "portNumber": 1,
          "connectionStatus": "Connected",
          "hardwareId": "AAFDE9C1E2E7",
          "model": "HDX_AudioBar"
        },
        {
          "portNumber": 5,
          "connectionStatus": "Connected",
          "hardwareId": "XXXXX0X0X0X5",
          "model": "HDX_MicPod"
        }
      ]
    },
    {
      "deviceType": "adaptive-voice-amplification",
      "deviceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "customName": "External microphone",
      "channelNumber": 1,
      "signalLevelGain": 0,
      "voiceAmplificationLevelInPercentage": 0,
      "microphoneDuckingEnabled": false,
      "voiceAmplificationGateThreshold": 0,
      "voiceAmplificationUsbOutputGainLevel": 0,
      "isMuted": false
    }
  ]
}

Step 3 - Make a request to get external microphone configuration

To get the external microphone configuration of a single peripheral, use the Get device endpoint

  1. Set the path with the IP address of the Nureva device followed by /api/v1/room/devices/<deviceId>, where deviceId is the ID of the peripheral.
  2. Update the headers to include Authorization as key and the value being Nureva followed by the authParameters received from the login endpoint using the general account.
  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 external microphone settings for the Nureva device with the IP address of 10.0.0.1 and device ID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Example of request

curl --request GET \
    --url https://10.0.0.1/api/v1/room/devices/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
    --header 'Authorization: Nureva <YOUR_GENERAL_AUTHPARAMETERS>' \
    --header 'Nureva-Client-Id: integration_app_name' \
    --header 'Nureva-Client-Version: 0.0.1' \
  1. If the call is successful, an HTTP status code of 200 OK and the specified peripheral configuration will be returned.

Example of response

HDL410, HDL310, Dual HDL300, HDL300
{
  "deviceType": "adaptive-voice-amplification",
  "deviceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "customName": "External microphone",
  "voiceAmplificationEnabled": true,
  "voiceAmplificationLevel": 30,
  "voiceAmplificationAuxInLevel": "Line",
  "microphoneDuckingEnabled": false,
  "voiceAmplificationGateThreshold": 64,
  "voiceAmplificationUsbOutputGainLevel": 10
}
HDX
{
  "deviceType": "adaptive-voice-amplification",
  "deviceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "customName": "External microphone",
  "channelNumber": 1,
  "signalLevelGain": 0,
  "voiceAmplificationLevel": 0,
  "microphoneDuckingEnabled": false,
  "voiceAmplificationGateThreshold": 0,
  "voiceAmplificationUsbOutputGainLevel": 0,
  "isMuted": false
}

Step 4 - Make a request to update external microphone configuration

To set (update) an external microphone configuration, use the Update device endpoint

  1. Set the path with the IP address of the Nureva device followed by /api/v1/room/devices/<deviceId>, where deviceId is the ID of the peripheral.
  2. Update the headers to include Authorization as key and the value being Nureva followed by the authParameters received from the login endpoint using the general account.
  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 PATCH request to update the peripheral settings. The code sample below is a request to update the peripheral settings for the Nureva device with the IP address of 10.0.0.1 and device ID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. The example includes all the optional properties. At least one property must be specified.

Example of request

HDL410, HDL310, Dual HDL300, HDL300
curl --request PATCH \
    --url https://10.0.0.1/api/v1/room/devices/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
    --header 'Authorization: Nureva <YOUR_GENERAL_AUTHPARAMETERS>' \
    --header 'Nureva-Client-Id: integration_app_name' \
    --header 'Nureva-Client-Version: 0.0.1' \
    --header 'Content-Type: application/json' \
    --data '{
        "customName": "new name",
        "voiceAmplificationEnabled": true,
        "voiceAmplificationLevel": 10,
        "voiceAmplificationAuxInLevel": "Mic",
        "microphoneDuckingEnabled": true,
        "voiceAmplificationGateThreshold": 10,
        "voiceAmplificationUsbOutputGainLevel": 10
    }'
HDX
curl --request PATCH \
    --url https://10.0.0.1/api/v1/room/devices/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
    --header 'Authorization: Nureva <YOUR_GENERAL_AUTHPARAMETERS>' \
    --header 'Nureva-Client-Id: integration_app_name' \
    --header 'Nureva-Client-Version: 0.0.1' \
    --header 'Content-Type: application/json' \
    --data '{
        "customName": "new name",
        "signalLevelGain": 5,
        "voiceAmplificationLevel": 10,
        "microphoneDuckingEnabled": true,
        "voiceAmplificationGateThreshold": 10,
        "voiceAmplificationUsbOutputGainLevel": 10,
        "isMuted": false
    }'
  1. If the call is successful, an HTTP status code of 200 OK and the peripheral device ID will be returned.

Example of response

{
  "deviceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Step 5 - Make a request to remove external microphone configuration

To remove an external microphone from the Nureva system, use the Delete device endpoint

  1. Set the path with the IP address of the Nureva device followed by /api/v1/room/devices/<deviceId>, where deviceId is the ID of the peripheral.
  2. Update the headers to include Authorization as key and the value being Nureva followed by the authParameters received from the login endpoint using the general account.
  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 DELETE request. The code sample below is a request to delete the external microphone from the Nureva device with the IP address of 10.0.0.1 and device ID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Example of request

curl --request DELETE \
    --url https://10.0.0.1/api/v1/room/devices/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
    --header 'Authorization: Nureva <YOUR_GENERAL_AUTHPARAMETERS>' \
    --header 'Nureva-Client-Id: integration_app_name' \
    --header 'Nureva-Client-Version: 0.0.1'
  1. If the call is successful, an HTTP status code of 200 OK will be returned.

✅

Tutorial complete!

You now understand how to add, retrieve, configure, and remove external microphone.

Updated 7 days ago

Did this page help you?