Stream Quality Monitoring

Feature Overview

When using ZEGOCLOUD Express SDK for calls, users may experience poor network conditions. You can use relevant callbacks to monitor changes in current call network quality and audio/video information.

For example, in multi-person audio/video calls or multi-person singing scenarios, if you need to display user network quality in real-time, you can refer to this document to implement the corresponding functionality.

Example Source Code Download

Please refer to Download Example Source Code to obtain the source code.

For relevant source code, please view files in the "src/Examples/AdvancedStreaming/StreamMonitoring" directory.

Prerequisites

Before monitoring stream quality, ensure that:

• A project has been created in the ZEGOCLOUD Console, and a valid AppID and Server address have been obtained. For details, please refer to Console - Project Information.
• ZEGOCLOUD Express SDK has been integrated into the project, and basic audio/video stream publishing and playing functionality has been implemented. For details, please refer to Quick Start - Integration and Quick Start - Implementation.

Basic Network Quality Report

You can listen to the networkQuality callback to receive upstream and downstream network quality for users (including yourself). This callback is triggered every two seconds. For network quality levels, please refer to QualityGrade.

networkQuality callback logic:

• You will receive your own network quality callback as long as you publish or play streams.
• You will receive other users' network quality callbacks only when you are playing audio/video streams published by other users and those users are in your room.
• When "userID" is "" (empty string), it represents your own network quality. When "userID" is not "" (empty string), it represents reports for other users in the room.
• You can estimate the network status of remote publishing users. If a remote publishing user's heartbeat is lost once, their network quality will be reported as "unknown". If the heartbeat is lost 3 times, their network quality will be reported as "die".

zg.on("networkQuality", (userID, upstreamQuality, downstreamQuality) => {
        console.log("networkQuality", userID, upstreamQuality, downstreamQuality)
})

zg.on("networkQuality", (userID, upstreamQuality, downstreamQuality) => {
        console.log("networkQuality", userID, upstreamQuality, downstreamQuality)
})

Advanced Quality Report

If the basic network quality report above does not meet your needs, ZEGOCLOUD also provides more detailed stream publishing quality reports, stream playing quality reports, and other related information.

Stream Publishing Quality Report

The stream publishing quality report describes the quality of the process where users push audio/video streams to the ZEGOCLOUD server. It includes the frame rates of audio/video streams during the capture and encoding phases, as well as the frame rate, bitrate, latency, and packet loss rate of the transmitted (sent) audio/video streams.

You can register publishQualityUpdate to receive stream publishing quality callbacks. This callback is received every three seconds after successful stream publishing. You can use the stats (ZegoPublishStats) parameter to understand the health status of published audio/video streams in real-time.

• In most cases, you only need to pay attention to the videoQuality parameter of video and the audioQuality parameter of audio. You can determine the overall quality of stream publishing through the enumeration values of these two parameters.
• If you want to focus on more detailed stream publishing quality parameters, please refer to ZegoPublishStats.

zg.on('publishQualityUpdate', (streamId, stats) => {
    console.log('publishQualityUpdate', streamId, stats);
})

zg.on('publishQualityUpdate', (streamId, stats) => {
    console.log('publishQualityUpdate', streamId, stats);
})

Stream Publishing Quality Details

Stream publishing quality includes video quality and audio quality during publishing, such as video bitrate, audio bitrate, video frame rate, etc.

Video Quality

The relevant parameters for video quality ZegoPublishVideoStats data during stream publishing are as follows:

Audio Quality

The relevant parameters for audio quality ZegoPublishAudioStats during stream publishing are as follows:

Stream Playing Quality Report

The stream playing quality report describes the quality of the process where users play audio/video streams. It includes the frame rate, bitrate, latency, and packet loss rate of received audio/video streams, as well as the frame rate during the decoding phase and the overall audio/video quality.

You can register playQualityUpdate to receive stream playing quality callbacks. This callback is received every three seconds after successful stream playing. Developers can use the stats (ZegoPlayStats) parameter to understand the health status of played audio/video streams in real-time.

• In most cases, you only need to pay attention to the videoQuality parameter of video and the audioQuality parameter of audio. You can determine the overall quality of stream playing through the enumeration values of these two parameters.
• If you want to focus on more detailed stream playing quality parameters, please refer to ZegoPlayStats.

zg.on('playQualityUpdate', (streamId, stats) => {
    console.log('publishQualityUpdate', streamId, stats);
})

zg.on('playQualityUpdate', (streamId, stats) => {
    console.log('publishQualityUpdate', streamId, stats);
})

Stream Playing Quality Details

Stream playing quality includes video quality and audio quality during playing, such as video bitrate, audio bitrate, video frame rate, etc.

Video Quality

The relevant parameters for video quality ZegoPlayVideoStats data during stream playing are as follows:

Audio Quality

The relevant parameters for audio quality ZegoPlayAudioStats during stream playing are as follows:

Other Information Monitoring

Stream Publishing/Playing Status Change Notification

Stream Publishing Status Callback

After successful stream publishing, you can use publisherStateUpdate to receive notifications of stream publishing status changes.

zg.on('publisherStateUpdate', result => {
    console.log('publisherStateUpdate: ', result.streamID, result.state, result);
});

zg.on('publisherStateUpdate', result => {
    console.log('publisherStateUpdate: ', result.streamID, result.state, result);
});

You can roughly determine the user's stream publishing network status based on whether the state parameter in the callback is in the "requesting stream publishing status". The values of the state parameter correspond to user stream publishing status as follows:

Stream Playing Status Change Callback

After successful stream playing, developers can use playerStateUpdate to receive notifications of stream playing status changes.

zg.on('playerStateUpdate', result => {
        console.warn('playerStateUpdate', result.streamID, result.state);
})

zg.on('playerStateUpdate', result => {
        console.warn('playerStateUpdate', result.streamID, result.state);
})

Developers can roughly determine the user's stream playing network status based on whether the state parameter is in the "requesting stream playing status". The values of the state parameter correspond to user stream playing status as follows:

Related Documents

• How to handle video freezing issues?
• How to handle audio freezing issues?
• How to understand and use SEI (Supplemental Enhancement Information)?