@twilio/rtc-diagnostics

---

The AudioInputTest class is an EventEmitter (please see AudioInputTest.on for events and their details) and helps to diagnose issues by capturing user audio and emitting the volume levels detected in that media.

import { AudioInputTest, testAudioInputDevice } from '@twilio/rtc-diagnostics';
const options: AudioInputTest.Options = { ... };
// `options` may be left `undefined` to use default option values
const audioInputTest: AudioInputTest = testAudioInputDevice(options);

Applications can use the volume events emitted by the test to update their UI to show to the user whether or not their media was captured successfully.

audioInputTest.on(AudioInputTest.Events.Volume, (volume: number) => {
  ui.updateVolume(volume); // Update your UI with the volume value here.
});

The test can be normally stopped two ways: allowing the test to time out and stopping the test manually.

To end the test manually, the application can ask the end-user to confirm that the volume levels it emits are what the end-user expects. If so, the application can call the AudioInputTest.stop method with true. Otherwise, if the audio values are not expected, the application can call AudioInputTest.stop with false.

// The UI should indicate that if the volume values are what the user
// expects, they can click this button to pass and stop the test...
const volumeCorrectButton = ...;
volumeCorrectButton.addEventListener('click', () => {
  audioInputTest.stop(true);
});

// ...otherwise, if the volume levels are not what they expect, they can
// click this.
const volumeIncorrectButton = ...;
volumeIncorrectButton.addEventListener('click', () => {
  audioInputTest.stop(false);
});

Calling AudioInputTest.stop will immediately end the test.

---

The AudioInputTest object will always emit a AudioInputTest.Report with the AudioInputTest.Events.End event, regardless of the occurrence of errors during the runtime of the test.

Fatal errors will immediately end the test and emit a report such that the value of AudioInputTest.Report.errors will contain the fatal error.

Non-fatal errors will not end the test, but will be included in the value of AudioInputTest.Report.errors upon completion of the test.

---

Note: In Firefox, deviceId will be ignored, and instead the user will get a browser pop-up where they can select the device they want to use. This is unavoidable as it is Firefox's implementation of getUserMedia().

In most browsers, such as Chrome and Safari, when getUserMedia() is called, a prompt will ask the user for broad microphone-access permissions. Then, the parameters passed to getUserMedia() will determine the device that is captured.

Firefox differs in that the prompt will ask for a specific input device. Regardless of the parameters passed to getUserMedia(), the device selected in that prompt will be captured. If the user opts to have the browser "Remember this selection" within the prompt, the device that was selected will be captured by every future getUserMedia() call as well. This selection will persist even through changes in the system OS, i.e. when default devices are changed. In order to change the device, the user has to revoke the webpage's microphone-access permissions for the prompt to show again.

Please see this link for more information on microphone access in Firefox: https://support.mozilla.org/en-US/kb/how-manage-your-camera-and-microphone-permissions

---

The function testAudioInputDevice serves as a factory function that accepts AudioInputTest.Options as its only parameter and will instantiate an AudioInputTest object with those options.

import { AudioInputTest, testAudioInputDevice } from '@twilio/rtc-diagnostics';
const options: AudioInputTest.Options = { ... };
const audioInputTest: AudioInputTest = testAudioInputDevice(options);

---

The AudioOutputTest class is an EventEmitter (please see AudioOutputTest.on for events and their details) and helps to diagnose issues by playing a sound clip (by default the sound clip is the ringing tone from the twilio-client.js SDK) and emitting volume events of the sound clip as it plays.

import { AudioOutputTest, testAudioOutputDevice } from '@twilio/rtc-diagnostics';
const options: AudioOutputTest.Options = { ... };
// `options` may be left `undefined` to use default option values
const audioOutputTest: AudioOutputTest = testAudioOutputDevice(options);

The application can use the volume events to show in its UI that audio is playing and that the end-user should be hearing something.

audioOutputTest.on(AudioOutputTest.Events.Volume, (volume: number) => {
  ui.updateVolume(volume); // Update your UI with the volume value here.
});

The application should ask the end-user to confirm that the sound being played can be heard. The application should call AudioOutputTest.stop with true if the end-user hears the sound, and false if not.

// If the user was able to hear the audio, the UI should indicate they should
// click this button...
const passButton = ...;
passButton.on('click', () => {
  audioOutputTest.stop();
  // display a confirmation dialog to the user
});

// ...conversely, if they were not able to hear the audio, they should click
// this one.
const failButton = ...;
failButton.on('click', () => {
  audioOutputTest.stop();
  // display a warning to the user
});

Caling AudioOutputTest.stop will immediately end the test.

---

The AudioOutputTest object will always emit a AudioOutputTest.Report with the AudioOutputTest.Events.End event, regardless of the occurence of errors during the runtime of the test.

Fatal errors will immediately end the test and emit a report such that the value of AudioOutputTest.Report.errors will contain the fatal error.

Non-fatal errors will not end the test, but will be included in the value of AudioOutputTest.Report.errors upon completion of the test.

If the data at testURI is unable to be loaded, meaning the error event is raised on the audio element, a fatal error has occurred.

If doLoop is set to false, then the test will run for either the option duration, or the full duration of the audio file, which ever is shorter. If doLoop is set to true, it will only run as long as the duration option.

---

The function testAudioOutputDevice serves as factory function that accepts AudioOutputTest.Options as its only parameter and will instantiate an AudioOutputTest object with those options.

import { AudioOutputTest, testAudioOutputDevice } from '@twilio/rtc-diagnostics';
const options: AudioOutputTest.Options = { ... };
const audioOutputTest: AudioOutputTest = testAudioOutputDevice(options);

Example:

  import { testMediaConnectionBitrate } from '@twilio/rtc-diagnostics';

  const mediaConnectionBitrateTest = testMediaConnectionBitrate({
    iceServers: [{
      urls: 'stun:global.stun.twilio.com:3478?transport=udp',
    }, {
      credential: 'bar',
      username: 'foo',
      urls: 'turn:global.turn.twilio.com:3478?transport=udp',
    }],
  });

  mediaConnectionBitrateTest.on('bitrate', (bitrate) => {
    console.log(bitrate);
  });

  mediaConnectionBitrateTest.on('error', (error) => {
    console.log(error);
  });

  mediaConnectionBitrateTest.on('end', (report) => {
    console.log(report);
  });

  // Run the test for 15 seconds
  setTimeout(() => {
    mediaConnectionBitrateTest.stop();
  }, 15000);

See MediaConnectionBitrateTest.Options.iceServers for details on how to obtain STUN and TURN server configurations.

---

This test will use getUserMedia to try and capture a video stream from the user. If this succeeds and an HTMLMediaElement is passed to the test within the test options, then the stream will be bound to the element and should be displayed.

---

When the test ends, all of the tracks within the captured MediaStream are ended and the srcObject of the HTMLMediaElement is set to null.