Skip to contentSkip to navigationSkip to topbar
On this page

Using the Network Quality API


(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.


Overview

overview page anchor

This guide introduces the Network Quality API and provides guidance on how to use it effectively in your Twilio Video applications. The Network Quality API is only available in Group Rooms.


What is the Network Quality API

what-is-the-network-quality-api page anchor

In a video application, the perceptual quality experienced by a Participant can be greatly influenced by the network. Degradation of available bandwidth, packet loss, or network jitter may reduce the usability of a video conferencing link causing end-user frustration. To tackle this, the Network Quality API monitors the Participant's network and provides quality metrics. Displaying quality scores in your UI can aid users in diagnosing problems as their network environment changes (such as due to a Wifi to Cellular handoff).

How the Network Quality API works.

For this, the Network Quality API uses an algorithm that ingests both Client and Server metrics and computes a Network Quality Level on the following scale:

Network Quality LevelMeaning
5Excellent network
4Good network
3Average network
2Below average network
1Bad network
0Network broken (reconnecting)

Remark that the Network Quality Level is not an absolute metric, but a score relative to what you are demanding from the network. For example, it may happen that your Quality Level is 5 while you are communicating low quality video, but it drops to 1 as soon as you change the video to be HD even if the network does not change at all in the process.

This also means that when you are not using the network at all (i.e. you are neither publishing nor subscribing to any Tracks) your quality level will be always 5 given that any network will be capable of complying with a zero communications demand.


Using the Network Quality API

using-the-network-quality-api page anchor

Enabling Network Quality Reporting

enabling-network-quality-reporting page anchor

The Network Quality API is disabled by default, and is requested at connect time. The following table illustrates the currently supported platforms:

Twilio Video SDKNQ Levels for LocalParticipantNQ Levels for RemoteParticipantsNQ Statistics
AndroidYes (v4.4.0+)Yes (v5.2.0+)Not Available
iOSYes (v2.9.0+)Yes (v3.2.0+)Not Available
JavaScriptYes (v1.14.0+)Yes (v1.18.0+)Yes (v1.18.0+)

The Network Quality API is only available Group Rooms (including Small Group Rooms).

Android

enabling-on-android page anchor

When building ConnectOptions.Builder, invoke the enableNetworkQuality method and pass true as a parameter. By default this enables network quality level changes to be reported for the Local Participant. To also receive network quality level changes for the Remote Participants, a configured NetworkQualityConfiguration object needs to be supplied to the ConnectOptions.Builder.networkQualityConfiguration method.

1
NetworkQualityConfiguration configuration =
2
new NetworkQualityConfiguration(
3
NetworkQualityVerbosity.NETWORK_QUALITY_VERBOSITY_MINIMAL,
4
NetworkQualityVerbosity.NETWORK_QUALITY_VERBOSITY_MINIMAL);
5
6
ConnectOptions connectOptions =
7
new ConnectOptions.Builder(token)
8
.roomName(roomName)
9
.enableNetworkQuality(true)
10
.networkQualityConfiguration(configuration)
11
.build();

When building TVIConnectOptions, set the property networkQualityEnabled to true. By default this enables network quality level changes to be reported for the Local Participant. To also receive network quality level changes for the Remote Participants, a configured TVINetworkQualityConfiguration object needs to be supplied to the TVIConnectOptions.networkQualityConfiguration property.

1
let connectOptions = ConnectOptions(token: accessToken) { (builder) in
2
builder.isNetworkQualityEnabled = true
3
builder.networkQualityConfiguration = NetworkQualityConfiguration(localVerbosity: .minimal,
4
remoteVerbosity: .minimal)
5
builder.roomName = "my-room"
6
}
7
8
room = TwilioVideoSDK.connect(options: connectOptions, delegate: self)

In JavaScript (v1.18.0+), you can use the following code snippet for configuring(link takes you to an external page) the Network Quality API:

1
var Video = require('twilio-video');
2
var token = getAccessToken();
3
4
Video.connect(token, {
5
name: 'my-room',
6
audio: { name: 'microphone' },
7
video: { name: 'camera' },
8
networkQuality: {
9
local: 1, // LocalParticipant's Network Quality verbosity [1 - 3]
10
remote: 2 // RemoteParticipants' Network Quality verbosity [0 - 3]
11
}
12
}).then(function(room) {
13
// Change Network Quality verbosity levels after joining the Room
14
room.localParticipant.setNetworkQualityConfiguration({
15
local: 2,
16
remote: 1
17
});
18
});
Setting Network Quality Verbosity
setting-network-quality-verbosity page anchor

Network Quality Levels are derived from the following metrics:

  • Bandwidth: Ranks the estimated available bandwidth in comparison with the one required by the service.
  • Latency: Ranks the transfer delay (round trip time) and jitter between the client and server.
  • Fraction Lost: Ranks network losses between the client and the server.

The above metrics are used to calculate a Network Quality Level for each direction (Send and Receive) and media type (Audio and Video), with the exception that bandwidth is not used for audio. The overall Network Quality Level is the minimum of all partial levels.

You can access the partial levels and associated metrics using the networkQuality verbosity(link takes you to an external page) levels for the LocalParticipant and RemoteParticipants. The following table describes the different verbosity levels:

VerbosityValueDescription
none0Nothing is reported for the Participant. This has no effect and defaults to minimal for the LocalParticipant.
minimal1Reports NQ Level for the Participant.
moderate2Reports NQ Level and NetworkQualityStats for the Participant. NetworkQualityStats is populated with the audio and video NQ Levels for both send and receive.
detailed3Reports NQ Level and NetworkQualityStats for the Participant. NetworkQualityStats is populated with the audio and video NQ Levels for both send and receive and their corresponding NetworkQualityMediaStats. NetworkQualityMediaStats is populated with bandwidth, latency, and fraction lost metrics in the form of NetworkQualitySendOrRecvStats.

Setting networkQuality to true is equivalent to setting the Network Quality verbosity for the LocalParticipant to 1 (minimal) and the Network Quality verbosity for RemoteParticipants to 0 (none).

Receiving the Network Quality Level

receiving-the-network-quality-level page anchor

Once the Network Quality API is enabled through the connect method as shown above, the SDK will start receiving Network Quality Level events. That Network Quality Level is a value from 0-5, inclusive, representing the quality of the network connection of the Participant, as illustrated in the table above. Note that while a Room is in the reconnecting state, a LocalParticipant's Network Quality Level is set to 0.

The specific value of the Network Quality Level can be obtained at any time using the networkQualityLevel property of the LocalParticipant object. Also note that while a Room is in reconnecting state, the LocalParticipant's Network Quality Level is 0.

In addition, applications can get notified of changes on the networkQualityLevel by subscribing to the networkQualityLevelChanged event that is published by the LocalParticipant.

Implementing the onNetworkQualityLevelChanged method on the LocalParticipant.Listener interface will allow you to receive network quality level changes for the local participant.

1
LocalParticipant.Listener localParticipantListener = new LocalParticipant.Listener() {
2
3
@Override
4
public void onNetworkQualityLevelChanged(
5
@NonNull LocalParticipant localParticipant,
6
@NonNull NetworkQualityLevel networkQualityLevel) {}
7
}

Implementing the onNetworkQualityLevelChanged method on the RemoteParticipant.Listener interface will allow you to receive network quality level changes for the remote participant.

1
RemoteParticipant.Listener remoteParticipantListener = new RemoteParticipant.Listener() {
2
3
@Override
4
public void onNetworkQualityLevelChanged(
5
@NonNull RemoteParticipant remoteParticipant,
6
@NonNull NetworkQualityLevel networkQualityLevel) {}
7
}

Implement -[TVILocalParticipantDelegate localParticipant:networkQualityLevelDidChange:](link takes you to an external page) in order to respond to network quality level changes for the local participant. Be sure that you have set the delegate of the LocalParticipant to ensure the callbacks are received.

1
// MARK: LocalParticipantDelegate
2
func localParticipantNetworkQualityLevelDidChange(participant: LocalParticipant, networkQualityLevel: NetworkQualityLevel) {
3
print("Local Participant Network Quality Level Changed: \(networkQualityLevel)")
4
}

Implement -[TVIRemoteParticipantDelegate remoteParticipant:networkQualityLevelDidChange:](link takes you to an external page) in order to respond to network quality level changes for remote participants. Be sure that you have set the delegate of each RemoteParticipant to ensure the callbacks are received.

1
// MARK: RemoteParticipantDelegate
2
func remoteParticipantNetworkQualityLevelDidChange(participant: RemoteParticipant, networkQualityLevel: NetworkQualityLevel) {
3
print("Remote Participant (\(participant.identity)) Network Quality Level Changed: \(networkQualityLevel)")
4
}

A typical way of using the Network Quality Level is to represent a Participant's Network Quality as cell phone-style signal-strength bars. The following snippet shows how to do it in JavaScript:

1
function printNetworkQualityStats(networkQualityLevel, networkQualityStats) {
2
// Print in console the networkQualityLevel using bars
3
console.log({
4
1: '▃',
5
2: '▃▄',
6
3: '▃▄▅',
7
4: '▃▄▅▆',
8
5: '▃▄▅▆▇'
9
}[networkQualityLevel] || '');
10
11
if (networkQualityStats) {
12
// Print in console the networkQualityStats, which is non-null only if Network Quality
13
// verbosity is 2 (moderate) or greater
14
console.log('Network Quality statistics:', networkQualityStats);
15
}
16
}
17
18
// Print the initial Network Quality Level and statistics
19
printNetworkQualityStats(participant.networkQualityLevel, participant.networkQualityStats);
20
21
// Print changes to Network Quality Level and statistics
22
participant.on('networkQualityLevelChanged', printNetworkQualityStats);

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.