Network quality 🔗

This feature is part of OpenViduPRO tier.

OpenVidu is able to estimate a quality rating of the client-side network connection, allowing you to monitor it through a very easy to use API. You can then use this information to tell users about how good or bad their own connection is, helping you manage user expectations around perceived drops in the quality of the service when their devices have a weak network link.

Having a strong network link is one of the most important aspects of a successful WebRTC connection. The problem is that modern networks are very complex systems, and can suffer from a myriad of issues that will have a huge impact in the quality of the media streams being transmitted. While you will typically be in control of your own server's network resources, and will make sure your connection is of a high enough quality, that won't be the case for end users using your application. For that reason, it is especially important to monitor and to be able to warn users about any network issues on their end.




Enabling the network quality API 🔗

OpenVidu network quality is only available for PUBLISHERS. You can only receive the network quality level for participants publishing a media stream. Participants that only receive remote streams will not generate network quality events.

To be able to receive the network quality events in your application's client-side, you must enable OpenVidu Pro configuration property OPENVIDU_PRO_NETWORK_QUALITY. You can also set the frequency with which OpenVidu Server Pro will check the network quality of each participant with property OPENVIDU_PRO_NETWORK_QUALITY_INTERVAL.

OPENVIDU_PRO_NETWORK_QUALITY=true
OPENVIDU_PRO_NETWORK_QUALITY_INTERVAL=5

After that, you can start receiving network quality events in the application's client side by adding listener networkQualityLevelChanged to the Session object. This listener is able to receive events of type NetworkQualityLevelChangedEvent.

session.on('networkQualityLevelChanged', event => {

    if (event.connection.connectionId === session.connection.connectionId) {
        console.log("Now my network quality level is " + event.newValue + ". Before was " + event.oldValue);

        // Do stuff

    } else {
        console.log("Network quality level of connection " + event.connection.connectionId
            + " is " + event.newValue + ". Previous one was " + event.oldValue);

        // Do stuff

    }
});



Understanding the network quality level 🔗

The NetworkQualityLevelChangedEvent provides a number between 0 and 5 in properties newValue and oldValue with the newest and previous value of the network quality level, respectively.

The network quality level measures the strength of the network link, not the actual perception users will have of the video or audio. This distinction is important to keep in mind: even in the face of a very bad network link, WebRTC contains very advanced mechanisms to try and adapt transmissions, but there is no guarantee that these mechanisms will be enough to provide a seamless experience. In the best case, nobody will notice and the video or audio streams will proceed with good quality as if nothing happened; otherwise, video and audio might suffer from choppiness, and overall quality degradation.

Because it is not possible to know ahead of time if the WebRTC adaptation mechanisms are going to overcome all the issues introduced by network hiccups or congestion, applications usually resort to showing an indicator that informs users about quality of their own network. Here are a couple ideas of how to deal with this:

  • Displaying a "WiFi signal" style icon, that fills or empties according to the network quality level.
  • Displaying a color-coded badge to match the network quality: green for a good network, yellow for a poor network, and red for a very bad network.

Here we provide a description of each network quality level, and suggestions about how an application might want to present this information to the user:

Network quality level Meaning
5

Excellent network.

This level is only shown under the very best conditions, typically over LAN or other networks where there is virtually no packet loss or jitter issues.

User Interface: Green status badge, or no status at all.

4

Good network.

A good network link with low amount of packet loss. Perfect conditions for WebRTC.

User Interface: Green status badge, or no status at all.

3

Non Optimal network.

Not ideal, with not too frequent bursts of packet loss. These occasional network issues will be avoided by the WebRTC adaptation mechanisms.

User Interface: Yellow status badge, or no status at all.

2

Poor network.

There is a lot of packet loss, and the WebRTC adaptation mechanisms might not be enough to avoid all problems. As a result, media quality could be degraded.

User Interface: Orange status badge, suggesting to move to a better signal coverage area.

1

Bad network.

The media will most probably suffer from very low quality and show interruptions or choppiness.

User Interface: Red status badge, warning the user that other participants could have difficulties seeing or hearing them.

0

Broken network.

The user has been outright disconnected from OpenVidu. Note however that OpenVidu will try to reconnect, so it might still be possible that the user is able to join the session, if the network conditions improve.

User Interface: Red status badge, informing the user that their connection got temporarily interrupted.