Audio Programming Guide

Table of Contents

  1. Introduction
    1.1 Device names
    1.2 Programming concept
    1.3 Demo application
    1.4 Feature limitations
  2. Application notes
    2.1 Disable audio processing for HDMI input
    2.2 Hot audio input switching
    2.3 Closing the stream
    2.4 Stereo microphone
    2.5 HDMI input audio
    2.6 Audio glitches

1. Introduction

This article outlines the concept of accessing standard audio devices in the Dolby Voice Room system. Starting with the version 2.0 release, the Hub app can access standard audio devices in the system; these include:

  • HDMI input audio device
  • HDMI output audio devices (for both HDMI1 and HDMI2)
  • Stereo microphones in the Dolby Voice Camera
  • Microphones in 3rd party cameras

The app may access these audio devices for various use cases. For example, the app can route HDMI input audio to the TV when the user connects a computer to the HDMI input port of the Dolby Voice Hub.

1.1. Device names

Device name Type Description
AverMedia C353-Input Audio Audio capture HDMI input audio capture device
Microphones - Dolby Voice Camera Audio capture Stereo microphones from the Dolby Voice Camera
HDMI-Output Audio Monitor 1 Audio output HDMI 1 output for audio
HDMI-Output Audio Monitor 2 Audio output HDMI 2 output for audio
3rd-party names Audio capture 3rd party camera microphones, for example, the Logitech Brio has a stereo microphone

To list all media devices in the Dolby Voice Room, go to the devtools console and enter "navigator.mediaDevices.enumerateDevices()". Open the returned promise and examine the device names.

image

1.2. Programming concept

The audio devices can be accessed through standard WebRTC getUserMedia APIs. The app can use Web Audio APIs to process audio to enrich the experience. For an overview of Web Audio API compatibility with the Dolby Voice Room, refer to this page.

1.3. Demo application

The Dolby Voice Room demo application shows how an application can direct HDMI input audio to TV audio programmatically. To configure the Dolby Voice Room system to load the demo application, refer to this page.

1.4 Feature limitations

As of the Dolby Voice Room 2.0 release, the system does not support multiple peerconnections with audio streams.

2. Application notes

2.1 Disable audio processing for HDMI input

Audio processing must be turned off for AverMedia C353-Input Audio to ensure a good audio experience. For other devices, audio processing should be turned on (default); this can be done by setting additional media constraints during the getUserMedia call.

Get user stream for HDMI input

let audioId = 'default';  // e.g. use default audio input
Promise.resolve()
   .then(() =>
   {
      return navigator.mediaDevices.enumerateDevices();
   })
   .then((devices) =>
   {
      console.log('Devices', devices);

      let audioConstraints;

      audioConstraints = {deviceId: {exact : audioId } };
      if (audioId)
            {
         // For Avermedia: without applying any audio processing for echo cancellation,
         // hpf, noise suppression, etc.
         const wcarray = Object.values(devices);
         const avermediaaudio = wcarray.filter((audio) =>
            audio.label.indexOf('Avermedia') !== -1 && audio.kind == 'audioinput'
         );

         if ((avermediaaudio && avermediaaudio.length
            && avermediaaudio.find((audio) => audioId == audio.deviceId))
         )
         {
            console.log('Remove audio processing');
            // Constraints for avermedia & hdmi
            audioConstraints.echoCancellation = false;
            audioConstraints.noiseSuppression = false;
            audioConstraints.autoGainControl = false;
         }
         let constraints = {
           audio: audioConstraints,
           video: false
         };
         console.log('Constraints', constraints);
         return navigator.mediaDevices.getUserMedia(constraints);
      }
      else
      {
        return Promise.reject();
      }
      })
      .then((stream) =>
      {
        console.log('Stream:', stream)
        return stream;
      })

2.2 Hot audio input switching

In case the app needs to support switching audio input devices while the active input is being routed to the local playback device, the following application notes apply.

  • An issue can occur when trying to switch the audio input stream while performing local playback, where one stream is to be audio processed and the other is not to be audio processed.
  • Switching the audio input stream without closing and re-opening playback device can result in no sound being heard.
  • To enable switching between audio input streams (processed & non-processed audio), the app can implement the following logic:
    • If the Audio Input is switched, then set the Audio Output Device_id to an empty string.
    • Then set the Audio Output Device_id to the id of the selected device.
    • This effectively closes and re-opens the playback device.

2.3 Closing the stream

Stopping all audio tracks (in a stream that has only audio tracks) is not enough for the Web App Engine to close the stream (e.g., before reloading the page). The next getUserMedia request from the same device will result in a "device busy" error, so the app must force close the audio stream. This can be done by setting the HTMLMediaElement src property to an empty string as shown in the following sample code.

/**
 * Stopping tracks and closing stream
 * @param element HTMLMediaElement audio/video element stream is attached to
 */
let closeMediaStream = (element) =>
{
    try {
        let stream = element.srcObject;

        if (!stream)
            return;

        console.log('Stopping stracks');
        let tracks = stream.getTracks();

        for (let i=0, len=tracks.length; i < len; i++)
        {
            tracks[i].stop();
        }

        console.log('Closing stream');
        element.src = '';
    }
    catch(exc)
    {
        console.error('Could not end tracks', exc.message);
    }

}

2.4 Stereo microphone

If the app tries to access stereo tracks from a stereo microphone it needs to turn off echoCancellation in the mediaConstraints. If echoCancellation is turned on, then both channels will have downmixed mono audio.

2.5 HDMI input audio

When the HDMI input port's state changes, the system will not trigger a devicechange event. The app is expected to rely on a configuration change event for Device.Status.HDMIInputDetected and enumerate devices to obtain access to the HDMI input audio device.

2.6 Audio glitches

A call to navigator.mediaDevices.enumerateDevices() can cause interruptions during audio playback; therefore, the app shall avoid calling this API too frequently.