Skip to contentSkip to navigationSkip to topbar
On this page

JavaScript Room Monitor


(warning)

Warning

This documentation is for reference only. We are no longer onboarding new customers to Programmable Video. Existing customers can continue to use the product until December 5, 2026(link takes you to an external page).

We recommend migrating your application to the API provided by our preferred video partner, Zoom. We've prepared this migration guide(link takes you to an external page) to assist you in minimizing any service disruption.

Twilio's JavaScript Room Monitor(link takes you to an external page) is a browser-based tool that displays real-time information and metrics about a Twilio Video Room. It gathers and processes information from the Room(link takes you to an external page) object, including information about Participants' bandwidth, jitter, and packet loss, and displays the information in a modal window in the video application.

Below is as an example of interacting with the Video Room Monitor in a running application:

Example output from the Twilio Video Room Monitor.

The JavaScript Room Monitor can be added to any Twilio Video JavaScript application to help during all stages of development and for debugging in-progress calls. The Video Room Monitor is an open-source project, so you may also fork and customize the application to fit your specific use case.


Browser support

browser-support page anchor
ChromeEdge (Chromium)FirefoxSafari
Android--
iOS--
Linux--
macOS
Windows-

Add the Room Monitor to your application

add-the-room-monitor-to-your-application page anchor

NPM

npm page anchor

You can install the Video Room Monitor directly from npm(link takes you to an external page).

npm install @twilio/video-room-monitor --save

After installing, you can import @twilio/video-room-monitor and open the Monitor like so:

1
import Video from 'twilio-video';
2
import { VideoRoomMonitor } from '@twilio/video-room-monitor';
3
4
Video.connect('token').then((room) => {
5
VideoRoomMonitor.registerVideoRoom(room);
6
VideoRoomMonitor.openMonitor();
7
});

You can also copy twilio-video-room-monitor.min.js from the dist/browser folder after npm installing it and include it directly in your web app using a <script> tag.

<script src="https://my-server-path/twilio-video-room-monitor.min.js"></script>

Using this method, you can register a room and open the Monitor like so:

1
window.Twilio.VideoRoomMonitor.registerVideoRoom(room);
2
window.Twilio.VideoRoomMonitor.openMonitor();

Console script quickstart (not for production use)

console-script-quickstart-not-for-production-use page anchor

To quickly use the Video Room Monitor in any Twilio Video JavaScript application, you can run the following snippet in the browser console to load and open the Monitor. Note that the Room object(link takes you to an external page) must be exposed as a global variable (the sample below assumes the global variable is called twilioRoom) so that it can be registered with the Monitor.

1
(() => {
2
const script = document.createElement('script');
3
script.src = 'https://cdn.jsdelivr.net/npm/@twilio/video-room-monitor/dist/browser/twilio-video-room-monitor.min.js';
4
script.onload = () => {
5
// Register your Twilio Video Room here
6
window.Twilio.VideoRoomMonitor.registerVideoRoom(twilioRoom);
7
window.Twilio.VideoRoomMonitor.openMonitor();
8
};
9
document.body.appendChild(script);
10
})();

The script above opens the Monitor. You can then interact with the Monitor in your browser's console like so:

VideoRoomMonitor.toggleMonitor(); // toggle the monitor open or closed

We do not recommend this method for production use, because we do not control the availability of the jsDelivr CDN.


Below are the methods that are available on the Video Room Monitor. You can use these in your application's code, or call them in the browser's console to interact with the Monitor while your application is running.

Register the Video Room with the Monitor

register-the-video-room-with-the-monitor page anchor

This is a required step to be able to use the Video Room Monitor. This registers a Twilio Video Room with the Monitor.

To register a Room, you can run the following line of code, passing in the Room(link takes you to an external page) object that's returned when you connect to a Video Room with the Twilio Video JavaScript SDK(link takes you to an external page).

VideoRoomMonitor.registerVideoRoom(newRoom);

To open the Room Monitor after you have registered it, you can use the openMonitor method.

VideoRoomMonitor.openMonitor();

Opening the Video Room Monitor emits an opened event. You can listen for this opened event with the following code:

VideoRoomMonitor.on('opened', () => console.log('the monitor has been opened'));

You can close the Monitor with the closeMonitor method:

VideoRoomMonitor.closeMonitor();

Closing the Monitor emits a closed event. You can listen for the closed event with the following code:

VideoRoomMonitor.on('closed', () => console.log('the monitor has been closed'));

Toggle the Monitor open or closed

toggle-the-monitor-open-or-closed page anchor

You can use the toggleMonitor method to toggle the Monitor open or closed. If the Monitor is closed when you call this method, the Monitor will open and emit the opened event. If the Monitor is open when you call toggleMonitor, it will close the Monitor and emit the closed event.

VideoRoomMonitor.toggleMonitor();

Check if the Monitor is open

check-if-the-monitor-is-open page anchor

The Monitor has an isOpen property, which is a Boolean indicating whether or not the Monitor is open.

VideoRoomMonitor.isOpen;

Available metrics and information

available-metrics-and-information page anchor

The Room Monitor has two tabs: Info and Stats. Under the Info tab, you will find information about the Room and all of its Participants and their tracks. The Stats tab contains graphs of the bitrate sent and received over the course of the video call for the local Participant.

In the Info tab, you will find metrics for both the local and remote Participants. For each Participant and each track, you can view properties and metrics that are helpful for making optimizations or assessing media quality, such as packet loss percentage and jitter. The Info tab also includes relevant metadata about the Room and its Participants, such as the media region selected or the ConnectOptions(link takes you to an external page) of the local Participant.

Room

room page anchor

Displays information about the Room(link takes you to an external page) object.

NameDescription
Room NameThe Room's unique name
SIDThe Room's SID
StateThe state of this client's connection to the Room. Can be connected, reconnecting, or disconnected.
Dominant SpeakerWhich Participant is currently the dominant speaker. If dominant speaker detection is not enabled, this will be null.
Media RegionFor group rooms, which media server region the room is connected to. Will be null for Peer-to-Peer and WebRTC Go rooms.
Is RecordingWhether the room is being recorded
Total Sent BandwidthThis client's aggregate outgoing bandwidth, in kbps
Total Received BandwidthThis client's aggregate incoming bandwidth, in kbps

The Room information will also display the Room's ConnectOptions(link takes you to an external page) that were configured when connecting to the Room.

Displays information about remote and local Participants(link takes you to an external page), as well as the Participants' tracks.

NameDescription
SIDThe Participant's SID
isReconnectingWhether this Participant is reconnecting to the Room after a signaling connection disruption
networkQualityLevelThe Participant's current NetworkQualityLevel, if the Network Quality API is enabled. The NetworkQualityLevel is a value from 0-5, inclusive, representing the quality of a network connection. 5 indicates excellent network quality, and 0 represents a broken or reconnecting network connection.

Displays information about a Participant's published data tracks(link takes you to an external page).

NameDescription
Kinddata, indicating that this is a data track
idThe data track's id
maxPacketLifeTimeIf non-null, this represents a time limit (in milliseconds) during which data will be transmitted or retransmitted if not acknowledged on the underlying RTCDataChannel(link takes you to an external page)
maxRetransmitsIf non-null, this represents the number of times the data will be retransmitted if not successfully received on the underlying RTCDataChannel(link takes you to an external page)
Orderedtrue if data on the RemoteDataTrack can be received out-of-order
ReliableThis is true if both maxPacketLifeTime and maxRetransmits are set to null. If this is true, there is no bound on packet lifetime or the number of retransmits that will be attempted, ensuring "reliable" transmission.
isEnabledWill always be true for published data tracks
isSwitchedOffWhether the RemoteDataTrack is switched off. See Network Bandwidth Profile for more information about switching tracks on and off.
PriorityThe subscribe priority of the RemoteDataTrack

Displays information about a Participant's published audio tracks(link takes you to an external page).

NameDescription
NameThe track's name
SIDThe track's SID
isSubscribedWhether the local Participant is subscribed to this track
isEnabledWhether or not the audio track is enabled. If the audio track is not enabled, it is "muted".
BandwidthKilobits sent per second if this is a local track, or kilobits received per second if this is a remote track
CodecThe codec used for encoding and decoding this audio track
JitterAudio jitter (the fluctuation of latency over time) in milliseconds.
Packets LostThe number of packets lost over the life of the call
Packet Loss PercentageThe percentage of packets lost to total packets sent

Displays information about a Participant's published video tracks(link takes you to an external page).

NameDescription
NameThe track's name
SIDThe track's SID
isSubscribedWhether the local Participant is subscribed to this track
DimensionsThe video's width and height
isSwitchedOffWhether the video track is switched off. See Network Bandwidth Profile for more information about switching tracks on and off.
isEnabledWhether or not the video track is enabled. If the video track is not enabled, it is "paused".
BandwidthKilobits sent per second if this is a local track, or kilobits received per second if this is a remote track
CodecThe codec used for encoding and decoding this video track
FramerateThe video track's frame rate
Packets LostThe number of packets lost over the life of the call
Packet Loss PercentageThe percentage of packets lost to total packets sent

Displays information about the Media Stream Tracks(link takes you to an external page) attached to either a video or audio track.

NameDescription
mutedWhether this track is muted
readyStateThe track's readyState(link takes you to an external page). Can be live or ended.
idThe track's id
labelThe track's label identifying the track's source, such as internal microphone
kindThe type of track. Can be audio or video.

The Stats tab displays a graph of the sent and received bitrate summed across all tracks (audio, video, and data) during the video chat, reported in kbps. The x-axis displays the local time.

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.