Call Quality Monitoring
Feature Overview
During a call or live streaming, users can listen to the quality of specific publishing and playing by registering related callbacks.
Usage Steps
Monitor Publishing Stream Quality
Developers can receive publishing stream quality callbacks by registering onPublisherQualityUpdate. After successful publishing, this callback will be received every three seconds. Developers can monitor the health status of published audio/video streams in real-time based on quality parameters returned by the callback, so as to display uplink network status on the device UI in real-time.
- Interface prototype:
/**
* Publishing stream quality callback
* This callback will be received every 3 seconds after successful publishing
* @param streamID Stream ID
* @param quality Publishing stream quality
*/
virtual void onPublisherQualityUpdate(const std::string& streamID, const ZegoPublishStreamQuality& quality) {
// Please note, do not call any SDK interfaces in the SDK callback thread, you need to manually switch to another thread, otherwise a deadlock will occur
}- Call example:
class MyEventHandler: public IZegoEventHandler
{
void onPublisherQualityUpdate(const std::string& streamID, const ZegoPublishStreamQuality& quality) {
printf("onPublisherQualityUpdate: streamID=%s", streamID.c_str());
}
};Publishing Stream Quality Details
Publishing stream quality ZegoPublishStreamQuality includes the frame rate of audio/video streams in the capture and encoding stages, and the frame rate, bitrate, latency, and packet loss rate of audio/video streams in transmission (sending). The specific definition is as follows:
struct ZegoPublishStreamQuality
{
// Video capture frame rate, unit is f/s
double videoCaptureFPS;
// Video encoding frame rate, unit is f/s
double videoEncodeFPS;
// Video sending frame rate, unit is f/s
double videoSendFPS;
// Video bitrate, unit is kbps
double videoKBPS;
// Audio capture frame rate, unit is f/s
double audioCaptureFPS;
// Audio sending frame rate, unit is f/s
double audioSendFPS;
// Audio bitrate, unit is kbps
double audioKBPS;
// Latency from local to server, unit is milliseconds
int rtt;
// Packet loss rate, unit is percentage, 0.0 ~ 1.0
double packetLostRate;
// Publishing stream quality level
ZegoStreamQualityLevel level;
// Whether hardware encoding is enabled
bool isHardwareEncode;
// Video encoding format
ZegoVideoCodecID videoCodecID;
// Total bytes sent, including audio, video, and SEI, etc.
double totalSendBytes;
// Audio bytes sent
double audioSendBytes;
// Video bytes sent
double videoSendBytes;
};Publishing Capture Quality
Publishing capture quality is close to the user's subjective feeling during preview. The related parameters of audio/video quality in the capture stage during publishing are as follows:
- audioCaptureFPS: Audio capture frame rate (fps)
- videoCaptureFPS: Video capture frame rate (fps)
Publishing Encoding Quality
The related parameters of audio/video quality in the encoding stage during publishing are as follows:
- videoEncodeFPS: Target video encoding frame rate of current encoder (fps)
Publishing Sending Quality
Publishing sending quality is the actual publishing quality, related to actual network quality. Related members are as follows:
- audioSendFPS: Actual audio sending frame rate (fps)
- audioKBPS: Actual audio sending bitrate (Kbps)
- videoSendFPS: Actual video sending frame rate (fps)
- videoKBPS: Actual video sending bitrate (Kbps)
- rtt: Round-trip latency from device to ZEGO Server (ms)
- packetLostRate: Device uplink packet loss rate
Monitor Playing Stream Quality
Developers can receive playing stream quality callbacks by registering onPlayerQualityUpdate. After successful playing, this callback will be received every three seconds. Developers can monitor the health status of played audio/video streams in real-time based on quality parameters returned by the callback, so as to display downlink network status on the device UI in real-time.
- Interface prototype:
/**
* Playing stream quality callback
* This callback will be received every 3 seconds after successful playing
* @param streamID Stream ID
* @param quality Playing stream quality
*/
virtual void onPlayerQualityUpdate(const std::string& streamID, const ZegoPlayStreamQuality& quality) {
// Please note, do not call any SDK interfaces in the SDK callback thread, you need to manually switch to another thread, otherwise a deadlock will occur
}- Call example:
class MyEventHandler: public IZegoEventHandler
{
void onPlayerQualityUpdate(const std::string& streamID, const ZegoPlayStreamQuality& quality) {
printf("onPlayerQualityUpdate: streamID=%s", streamID.c_str());
}
};Playing Stream Quality Details
Playing stream quality ZegoPlayStreamQuality includes the frame rate, bitrate, latency, and packet loss rate of received audio/video streams, the frame rate of audio/video streams in the decoding stage, and the frame rate, freeze rate, and overall audio/video quality in the rendering stage. The specific definition is as follows:
struct ZegoPlayStreamQuality
{
// Video reception frame rate, unit is f/s
double videoRecvFPS;
// Video dejitter frame rate, unit is f/s
double videoDejitterFPS;
// Video decoding frame rate, unit is f/s
double videoDecodeFPS;
// Video rendering frame rate, unit is f/s
double videoRenderFPS;
// Video bitrate, unit is kbps
double videoKBPS;
// Video freeze rate, unit is (freeze counts/every 10 seconds)
// No data playback for more than 500 ms is considered one video freeze
double videoBreakRate;
// Audio reception frame rate, unit is f/s
double audioRecvFPS;
// Audio dejitter frame rate, unit is f/s
double audioDejitterFPS;
// Audio decoding frame rate, unit is f/s
double audioDecodeFPS;
// Audio rendering frame rate, unit is f/s
double audioRenderFPS;
// Audio bitrate, unit is kbps
double audioKBPS;
// Audio freeze rate, unit is (freeze counts/every 10 seconds)
// Continuously losing 3 frames and no audio data rendering within given freeze threshold is considered one audio freeze
double audioBreakRate;
// Latency from server to local, unit is milliseconds
int rtt;
// Packet loss rate, unit is percentage, 0.0 ~ 1.0
double packetLostRate;
// End-to-end latency, unit is milliseconds
int peerToPeerDelay;
// End-to-end packet loss rate, unit is percentage, 0.0 ~ 1.0
double peerToPeerPacketLostRate;
// Playing stream quality level
ZegoStreamQualityLevel level;
// Latency from local receiving data to playing, unit is milliseconds
int delay;
// Difference between video timestamp and audio timestamp, used to reflect audio-video synchronization status, unit is milliseconds. This value less than 0 means the number of milliseconds video is ahead of audio, greater than 0 means the number of milliseconds video lags behind audio, equal to 0 means no difference. When the absolute value is less than 200, it can be basically considered audio-video synchronized. When the absolute value is continuously greater than 200 for 10 seconds, it can be considered abnormal
int avTimestampDiff;
// Whether hardware decoding is enabled
bool isHardwareDecode;
// Video encoding format
ZegoVideoCodecID videoCodecID;
// Total bytes received, including audio, video, and SEI, etc.
double totalRecvBytes;
// Audio bytes received
double audioRecvBytes;
// Video bytes received
double videoRecvBytes;
};Playing Reception Quality
Playing reception quality is the actual playing quality, related to actual publishing quality and current network quality. Related parameters are as follows:
- audioRecvFPS: Actual received audio frame rate (fps)
- audioKBPS: Actual received audio bitrate (Kbps)
- audioBreakRate: Actual received audio freeze rate (freeze counts/every 10 seconds)
- videoKBPS: Actual received video frame rate (fps)
- videoRecvFPS: Actual received video bitrate (Kbps)
- videoBreakRate: Actual received video freeze rate (freeze counts/every 10 seconds)
- packetLostRate: Device downlink packet loss rate
- rtt: Round-trip latency from device to ZEGO Server (ms)
Playing Rendering Quality
Playing rendering quality is close to the user's subjective feeling of watching audio/video. This quality may be lower than the actual received playing quality value due to the influence of the decoder. Related parameters are as follows:
- audioRenderFPS: Actual audio rendering frame rate
- videoRenderFPS: Actual video rendering frame rate