RTC Diagnostics SDK

The RTC Diagnostics SDK provides functions to test input and output devices (microphone, speaker, camera) as well as functionality to confirm that you meet the network bandwidth requirements required to make a voice call or join a video room.

This SDK requires the use of Twilio NTS or your own STUN/TURN servers to perform the network tests. Using Twilio NTS will mirror how Twilio uses STUN/TURN in Programmable Video when connecting to a Twilio Video Room and will incur charges as per NTS pricing.

Features

• Input audio device tests
• Input video device tests
• Output audio device tests
• Bandwidth requirements tests

Prerequisites

• Node.js v12+
• NPM v6+ (comes installed with newer Node versions)

Installation

Building the project locally

# Clone repository
git clone [email protected]:twilio/rtc-diagnostics.git
cd rtc-diagnostics

# Install dependencies
npm install

# Build the artifacts under dist folder
npm run build

In order to run integration tests, you'll need to copy over the credentials.example.json file to credentials.json in the same folder, and replace the empty fields with valid values.

NPM

You can install directly from npm.

npm install @twilio/rtc-diagnostics --save

Or install from a local directory.

npm install /local-path-to-repo/rtc-diagnostics

Using this method, you can import rtc-diagnostics like so:

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

Script tag

You can also include rtc-diagnostics.js directly in your web app using a <script> tag.

<script src="https://my-server-path/rtc-diagnostics.js"></script>

Using this method, rtc-diagnostics.js will set a browser global:

const { testMediaConnectionBitrate } = Twilio.Diagnostics;

Usage

The following are examples for running tests. For more information, please refer to the API Docs

MediaConnectionBitrateTest Example

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

const mediaConnectionBitrateTest = testMediaConnectionBitrate({
 iceServers: [{
   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);
});

setTimeout(() => {
 mediaConnectionBitrateTest.stop();
}, 10000);

See MediaConnectionBitrateTest.Options for more information for how to obtain the urls values

AudioInputTest Example

import { testAudioInputDevice, AudioInputTest } from '@twilio/rtc-diagnostics';

const audioInputDeviceTest = testAudioInputDevice({
  deviceId: ...,
});

audioInputDeviceTest.on(AudioInputTest.Events.Volume, (volume) => {
  console.log(volume);
});

audioInputDeviceTest.on(AudioInputTest.Events.Error, (error) => {
  console.error(error);
});

audioInputDeviceTest.on(AudioInputTest.Events.End, (report) => {
  console.log(report);
});

setTimeout(() => {
  audioInputDeviceTest.stop();
}, 10000);

VideoInputTest Example

import { testVideoInputDevice, VideoInputTest } from '@twilio/rtc-diagnostics';

const videoInputDeviceTest = testVideoInputDevice({ element: videoElement });

videoInputDeviceTest.on(VideoInputTest.Events.Error, (error) => {
  console.error(error);
});

videoInputDeviceTest.on(VideoInputTest.Events.End, (report) => {
  console.log(report);
});

setTimeout(() => {
  videoInputDeviceTest.stop();
}, 10000);

AudioOutputTest Example

import { testAudioOutputDevice, AudioOutputTest } from '@twilio/rtc-diagnostics';

const audioOutputDeviceTest = testAudioOutputDevice({
  deviceId: ...,
});

audioOutputDeviceTest.on(AudioOutputTest.Events.Volume, (volume) => {
  console.log(volume);
});

audioOutputDeviceTest.on(AudioOutputTest.Events.Error, (error) => {
  console.error(error);
});

audioOutputDeviceTest.on(AudioOutputTest.Events.End, (report) => {
  console.log(report);
});

setTimeout(() => {
  audioOutputDeviceTest.stop();
}, 10000);

Related

Testing Voice and Video calling readiness

• Twilio Voice Client JS Preflight Test
• Twilio Video JS Preflight Test

Applications using Diagnostics and Preflight tests

• Twilio Voice Diagnostics Tool
• Twilio Video JS React App

Voice and Video JS SDKs

• Twilio Voice Client JS SDK
• Twilio Voice Client JS Quickstart
• Twilio Video JS SDK
• Twilio Video JS Quickstart

Connectivity requirements

• Twilio Client connectivity requirements

License

See LICENSE.md