Using the Network Quality API

概要

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's The Network Quality API
• Using the Network Quality API
  • Enabling the Network Quality API
  • Receiving the Network Quality Level
• Known issues and limitations

What's the Network Quality API

In a video application, the perceptual quality experienced by a participant can be greatly influenced by the network. A degradation on the available bandwidth, the packet loss or the network jitter may devastate the usability of a videoconferencing link causing a lot of frustration on end-users. To tackle this, the Network Quality API monitors the end-user network and informs about changes that might affect the perceived quality of experience. This minimizes end-user frustration and complaints.

For this, the Network Quality API uses a complex algorithm that ingest a bunch of network metrics and computes a Network Quality Level on the following Likert scale:

Remark that the Network Quality Level is not an absolute metric but a score relative to what you are demanding to the network. Hence, 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

The Network Quality API is only available Group Rooms (including Small Group Rooms). The following table illustrates its current support:

Enabling Network Quality API

By default, the Network Quality API is disabled. For enabling it on a client you must set the property networkQuality to true when connecting to the room.

Enabling The Network Quality API using the JavaScript SDK (required v1.14.0+)

In JavaScript, you can use the following code snippet for enabling the Network Quality API:

    var Video = require('twilio-video');
    var token = getAccessToken();

    // Connect with custom names for LocalAudioTrack and LocalVideoTrack
    Video.connect(token, {
      name: 'my-cool-room',
      audio: { name: 'microphone'},
      video: { name: 'camera'},
      networkQuality: true
    }).then(function(room) {
      room.localParticipant.trackPublications.forEach(function(publication) {
        console.log('The LocalTrack "' + publication.trackName + '" was successfully published');
      });
    });

Receiving the Network Quality Level

Once the Network Quality API is enabled through the connect method as shown above, the SDK will start receiving the Network Quality Level through 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 Participant object. Note that this works both for the LocalParticipant as well as for RemoteParticipants. 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 (local and remote) Participants.

Using the Network Quality Level in the JavaScript SDK (required v1.14.0+)

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:

    //Print in console the networkQualityLevel using bars
    function printNetworkQualityLevel(networkQualityLevel) {
      console.log({
        1: '▃',
        2: '▃▄',
        3: '▃▄▅',
        4: '▃▄▅▆',
        5: '▃▄▅▆▇'
      }[networkQualityLevel] || '');
    }

    // Print the initial Network Quality Level
    printNetworkQualityLevel(participant.networkQualityLevel);

    // Print changes to Network Quality Level
    participant.on('networkQualityLevelChanged', printNetworkQualityLevel);

Known issues and limitations

• Currently, the networkQualityLevel property and the networkQualityLevelChanged event are only available at the LocalParticipant. RemoteParticipants will have them soon.
• Currently Android and iOS SDKs do not support the Network Quality API. Support for them will be coming soon.