通话质量监测

---

功能简介

在通话或直播的过程中，用户可通过注册相关的回调以获得通话相关的信息，包括推流和拉流的质量报告、接收到音视频首帧的回调、分辨率变化、CDN（Content Delivery Network, 内容分发网络）相关信息和接收 SEI（Supplemental Enhancement Information，媒体补充增强信息）。本文将介绍以下功能：

通过获取以上信息，开发者可以根据推流/拉流状态执行相关操作。例如在推流质量不佳时做出相应处理、判断推拉流是否成功、判断转推 CDN 的音视频流是否正常或接收 SEI 信息等。

相关概念解释:

• 推流：指把采集阶段封包好的内容传输到服务器的过程。
• 拉流：指服务器将已有直播内容用指定地址进行拉取的过程。

示例源码下载

请参考 下载示例源码 获取源码。

相关源码请查看 “/ZegoExpressExample/Examples/AdvancedStreaming/StreamMonitoring” 目录下的文件。

前提条件

在进行通话质量监测之前，请确保：

• 已在 ZEGO 控制台 创建项目，并申请有效的 AppID 和 AppSign，详情请参考 控制台 - 项目信息。
• 已在项目中集成 ZEGO Express SDK，并实现了基本的音视频推拉流功能，详情请参考 快速开始 - 集成 和 快速开始 - 实现流程。

实现方法

用户网络质量

您可以通过监听 onNetworkQuality 回调，收到用户（包括您自己）的上下行网络质量。此回调每隔两秒会收到一次，网络质量等级请参考 ZegoStreamQualityLevel。

不同版本的 onNetworkQuality 回调逻辑有所不同：

class MyEventHandler : public IZegoEventHandler{
public:
    void onNetworkQuality(const std::string& userID, ZegoStreamQualityLevel upstreamQuality, ZegoStreamQualityLevel downstreamQuality){
        // 开发者可以在此回调中监控用户的上下行网络质量以上报到业务服务器做监控，或者给用户友好的提示
    }
}
auto eventhandler = std::make_shared<MyEventHandler>();
engine->setEventHandler(eventhandler);

监测推流质量

开发者可通过注册 onPublisherQualityUpdate 接收推流质量回调。推流成功后每隔三秒会收到此回调。开发者可根据回调返回的质量参数实时监控推送的音视频流的健康情况，以便在设备 UI 界面上实时展示上行网络状况。

class MyEventHandler : public IZegoEventHandler{
public:
    void onPublisherQualityUpdate(String streamID, ZegoPublishStreamQuality quality){
        // 开发者可以在此回调中监控具体的质量以上报到业务服务器做监控，或者监控质量对象的某个字段以给用户友好的提示
        // 若开发者不知道监控质量哪个字段可以关注 level 字段，这个字段是质量对象的综合值
    }
}
auto eventhandler = std::make_shared<MyEventHandler>();
engine->setEventHandler(eventhandler);

推流质量详解

推流质量包含了采集、编码阶段音视频流的帧率，传输（发送）的音视频流的帧率、码率、延时及丢包率。本节将介绍推流质量 ZegoPublishStreamQuality 内的参数。

推流采集质量

推流采集质量贴近用户预览时的主观感受，推流时 SDK 在采集阶段的音视频质量的相关参数如下：

• audioCaptureFPS：音频采集帧率（fps）
• videoCaptureFPS：视频采集帧率（fps）

推流编码质量

推流时 SDK 在编码阶段的音视频质量的相关参数如下：

• videoEncodeFPS：当前编码器的目标视频编码帧率（fps）

推流发送质量

推流发送质量是实际推流的质量，与实际的网络质量有关，相关参数如下：

• audioSendFPS：实际的音频发送帧率（fps）
• audioKBPS：实际的音频发送码率（kbps）
• videoSendFPS：实际的视频发送帧率（fps）
• videoKBPS：实际的视频发送码率（kbps）
• rtt：设备到 ZEGO Server 的往返延时（ms）
• packetLostRate：设备上行丢包率

字节数统计

开发者可统计已发送的视频、音频和总字节数，相关参数如下：

• totalSendBytes：已发送的总字节数
• audioSendBytes：已发送的音频字节数
• videoSendBytes：已发送的视频字节数

编码信息

开发者可获得所推流的编码信息，相关参数如下：

• videoCodecID：视频编码格式
• isHardwareEncode：是否开启硬件编码

上行网络综合质量

若开发者不清楚该回调接口的各个参数应该如何使用，可只关注 level 参数，这是 ZegoExpressEngine 内部根据质量参数计算的一个描述上行网络的综合值。

level 字段的说明如下：

监测拉流质量

开发者可通过注册 onPlayerQualityUpdate 接收拉流质量回调。拉流成功后每隔三秒会收到此回调。开发者可根据回调返回的质量参数实时监控拉取的音视频流的健康情况，以便在设备 UI 界面上实时展示下行网络状况。

class MyEventHandler : public IZegoEventHandler{
public:
    void onPlayerQualityUpdate(String streamID, ZegoPlayStreamQuality quality){
        // 开发者可以在此回调中监控具体的质量以上报到业务服务器做监控，或者监控质量对象的某个字段以给用户友好的提示
        // 若开发者不知道监控质量哪个字段可以关注 level 字段，这个字段是质量对象的综合值
    }
}
auto eventhandler = std::make_shared<MyEventHandler>();
engine->setEventHandler(eventhandler);

拉流质量详解

拉流质量包含了接收的音视频流的帧率、码率、延时和丢包率，解码阶段音视频流的帧率，以及渲染阶段的帧率、卡顿率、音视频整体质量。本节将介绍拉流质量 ZegoPlayStreamQuality 内的参数。

拉流接收质量

拉流接收质量是实际的拉流质量，与实际的推流质量和当前的网络质量相关。相关参数如下：

• audioRecvFPS：实际接收的音频帧率（fps）
• audioDejitterFPS：音频抗抖动帧率（f/s）
• audioKBPS：实际接收的音频码率（kbps）
• audioBreakRate：实际接收的音频卡顿率（卡顿次数/每 10 秒）
• videoRecvFPS：实际接收的视频帧率（fps）
• videoDejitterFPS：视频抗抖动帧率（f/s）
• videoKBPS：实际接收的视频码率（kbps）
• videoBreakRate：实际接收的视频卡顿率（卡顿次数/每 10 秒）
• packetLostRate：设备下行丢包率
• rtt：设备到 ZEGO Server 的往返延时（ms）
• avTimestampDiff：视频时间戳相对于音频时间戳的差值，用于反映音画同步情况，单位为毫秒。此值小于 0 表示视频超前音频的毫秒数，大于 0 表示视频滞后音频的毫秒数，等于0表示无差别。当绝对值小于200，可基本认为音画同步，当绝对值连续 10 秒大于 200 可以认为异常
• packetLostRate：丢包率，单位为百分比，取值范围为 0.0 ~ 1.0
• peerToPeerDelay： 端到端延迟，单位为毫秒
• peerToPeerPacketLostRate：端到端丢包率，单位为百分比，取值范围为 0.0 ~ 1.0

拉流渲染质量

拉流渲染质量贴近用户观看音视频的主观感受，该质量受解码器影响可能低于实际接收的拉流质量值。相关参数如下：

• audioRenderFPS：实际的音频渲染帧率
• videoRenderFPS：实际的视频渲染帧率
• delay：本端接收到数据后到播放的延迟，单位为毫秒

字节数统计

开发者可统计已接收的视频、音频和总字节数，相关参数如下：

• totalRecvBytes：已接收的总字节数，包括音频、视频和 SEI 等
• audioRecvBytes：已接收的音频字节数
• videoRecvBytes：已接收的视频字节数

解码信息

开发者可获得所拉流的解码信息，相关参数如下：

• videoCodecID：视频解码格式
• isHardwareDecode：是否开启硬件解码

MOS 音质评分

ZEGO Express SDK 2.16.0 版本开始，拉流质量回调 onPlayerQualityUpdate 中新增 mos 字段，表示对拉流音质的评分。开发者对音频质量比较关注时，可通过该字段了解当前音频的质量情况。

mos 字段的取值范围为 [-1, 5]，其中 -1 表示未知（例如异常拉流时无法评分），[0, 5] 表示正常评分区间。实时音频 MOS 评分对应的主观音质感受如下：

监控推流/拉流状态

推流状态回调

在推流成功后，开发者可通过 onPublisherStateUpdate 获取推流状态变更的通知。

class MyEventHandler : public IZegoEventHandler{
public:
    void onPublisherStateUpdate(String streamID, ZegoPublisherState state, int errorCode, JSONObject extendedData){
    // 当 state 为 PUBLISHER_STATE_NO_PUBLISH 时，且 errcode 非 0，表示推流失败，同时不会再进行重试推流了，此时可在界面作出推流失败提示；    
    // 当 state 为 PUBLISHER_STATE_PUBLISH_REQUESTING 时，且 errcode 非 0，表示在重试推流，此时如果超出重试时间未成功推流会抛出推流失败通知。
    }
}
auto eventhandler = std::make_shared<MyEventHandler>();
engine->setEventHandler(eventhandler);

开发者可根据回调内的 “state” 参数是否在 “正在请求推流状态” 来大体判断用户的推流网络情况。“state” 参数的取值与用户推流状态对应如下:

参数 “extendedData” 为状态更新附带的扩展信息。若使用 ZEGO 的 CDN 内容分发网络，在推流成功后，该参数的内容的键为 “flv_url_list”、“rtmp_url_list”、“hls_url_list”，分别对应 flv、rtmp、hls 协议的拉流 URL。

拉流状态变更回调

在拉流成功后，开发者可通过 onPlayerStateUpdate 获取拉流状态变更的通知。

class MyEventHandler : public IZegoEventHandler{
public:
    void onPlayerStateUpdate(String streamID, ZegoPlayerState state, int errorCode, JSONObject extendedData){
        // 当 state 为 PLAYER_STATE_NO_PLAY 时，且 errcode 非 0，表示拉流失败，同时不会再进行重试拉流了，此时可在界面作出拉流失败提示；
        // 当 state 为 PLAYER_STATE_PLAY_REQUESTING 时，且 errcode 非 0，表示重试拉流，此时如果超出重试时间未成功拉到流会抛出拉流失败通知。
    }
}
auto eventhandler = std::make_shared<MyEventHandler>();
engine->setEventHandler(eventhandler);

开发者可根据 “state” 参数是否在 “正在请求拉流状态” 来大体判断用户的拉流网络情况。“state” 参数的取值与用户拉流状态对应如下:

音视频首帧回调

推流端音频采集首帧回调

开发者可通过注册 onPublisherCapturedAudioFirstFrame 接收音频首帧回调。调用推流接口成功后，SDK 采集到第一帧音频数据时会收到此回调。

class MyEventHandler : public IZegoEventHandler{
public:
    void onPublisherCapturedAudioFirstFrame(){

    }
}
auto eventhandler = std::make_shared<MyEventHandler>();
engine->setEventHandler(eventhandler);

推流端视频采集首帧回调

开发者可通过注册 onPublisherCapturedVideoFirstFrame 接收视频首帧回调。调用推流接口成功后，SDK 采集到第一帧视频数据时会收到此回调。

class MyEventHandler : public IZegoEventHandler{
public:
    void onPublisherCapturedVideoFirstFrame(ZegoPublishChannel channel){

    }
}
auto eventhandler = std::make_shared<MyEventHandler>();
engine->setEventHandler(eventhandler);

拉流端音频接收首帧回调

开发者可通过注册 onPlayerRecvAudioFirstFrame 监听拉流端音频接收首帧回调。调用拉流接口成功后，SDK 拉流拉到第一帧音频数据时会收到此回调。

class MyEventHandler : public IZegoEventHandler{
public:
    void onPlayerRecvAudioFirstFrame(String streamID){

    }
}
auto eventhandler = std::make_shared<MyEventHandler>();
engine->setEventHandler(eventhandler);

拉流端视频接收首帧回调

开发者可通过注册 onPlayerRecvVideoFirstFrame 监听拉流端接收视频首帧回调。调用拉流接口成功后，SDK 拉流拉到第一帧视频数据时会收到此回调。

class MyEventHandler : public IZegoEventHandler{
public:
    void onPlayerRecvVideoFirstFrame(String streamID)(ZegoPublishChannel channel){

    }
}
auto eventhandler = std::make_shared<MyEventHandler>();
engine->setEventHandler(eventhandler);

拉流端渲染完视频首帧回调

开发者可通过注册 onPlayerRenderVideoFirstFrame 监听拉流端渲染完视频首帧回调。调用拉流接口成功后，SDK 拉流并渲染完第一帧视频数据后会收到此回调。

class MyEventHandler : public IZegoEventHandler{
public:
    void onPlayerRenderVideoFirstFrame{

    }
}
auto eventhandler = std::make_shared<MyEventHandler>();
engine->setEventHandler(eventhandler);

监控视频分辨率变化

采集视频分辨率变更回调

开发者可通过注册 onPublisherVideoSizeChanged 监听采集视频大小变更回调。推流成功后，在推流中途如果有改变视频采集分辨率发生变化将会收到此回调。

class MyEventHandler : public IZegoEventHandler{
public:
    void onPublisherVideoSizeChanged(int width, int height, ZegoPublishChannel channel){

    }
}
auto eventhandler = std::make_shared<MyEventHandler>();
engine->setEventHandler(eventhandler);

拉流分辨率变更通知

开发者可通过注册 onPlayerVideoSizeChanged 获取拉流分辨率变更通知。拉流成功后，在拉流中途如果有视频分辨率发生变化将会收到此回调，用户可根据流的最终分辨率调整显示。

class MyEventHandler : public IZegoEventHandler{
public:
    void onPlayerVideoSizeChanged(String streamID, int width, int height){

    }
}
auto eventhandler = std::make_shared<MyEventHandler>();
engine->setEventHandler(eventhandler);

监控 CDN 转推状态

添加/删除转推 CDN 地址状态回调

开发者可通过注册 onPublisherRelayCDNStateUpdate 获取添加/删除转推 CDN 地址状态回调。在 ZEGO RTC 服务器将音视频流转推到 CDN 后，如果 CDN 转推状态发生变化，例如出现转推停止或转推重试，将会收到此回调。

class MyEventHandler : public IZegoEventHandler{
public:
    void onPublisherRelayCDNStateUpdate(String streamID, ArrayList<ZegoStreamRelayCDNInfo> infoList){

    }
}
auto eventhandler = std::make_shared<MyEventHandler>();
engine->setEventHandler(eventhandler);

转推 CDN 信息详解

转推 CDN 信息 ZegoStreamRelayCDNInfo 包含了 CDN 推流的 URL，转推状态，转推状态变更的原因状态发生的时间。ZegoStreamRelayCDNInfo内所有参数如下：

其中，state取值如下：

updateReason 取值如下：

相关文档

• 怎么处理视频卡顿问题？
• 怎么处理音频卡顿问题？
• 如何理解和使用 SEI（媒体补充增强信息）？