通话质量监测

功能简介

在使用 ZEGO Express SDK 进行通话中，用户有时会出现网络不好的情况，此时您可以通过相关回调了解当前通话的网络质量和音频/视频信息的变化。

例如，在进行多人音视频通话或者多人唱歌时，我们需要实时显示用户的网络质量，就可以参考本文档实现相应功能。

示例源码

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

相关源码请查看 “lib\topics\StreamAdvanced\stream_monitoring” 目录下的文件。

前提条件

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

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

基础网络质量报告

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

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

ZegoExpressEngine.onNetworkQuality = (String userID, ZegoStreamQualityLevel upstreamQuality, ZegoStreamQualityLevel downstreamQuality) {
    if (userID.isEmpty) {
        // 代表本地用户（本端）的网络质量
        // ("我的上行网络质量是 $upstreamQuality");
        // ("我的下行网络质量是 $downstreamQuality");
    } else {
        //代表房间内其他用户的网络质量
        //("用户 $userID 的上行网络质量是 $upstreamQuality");
        //("用户 $userID 的下行网络质量是 $downstreamQuality");
    }

    /*
    ZegoStreamQualityLevel.Excellent, 网络质量极好
    ZegoStreamQualityLevel.Good, 网络质量好
    ZegoStreamQualityLevel.Medium, 网络质量正常
    ZegoStreamQualityLevel.Bad, 网络质量差
    ZegoStreamQualityLevel.Die, 网络异常
    ZegoStreamQualityLevel.Unknown, 网络质量未知
    */         
};

进阶质量报告

如果上述的基础网络质量报告不能满足您的需求，ZEGO 还提供了更详细的推流质量报告、拉流质量报告以及其他相关信息供您参考。

推流质量报告

推流质量报告是指描述用户把音视频推送到 ZEGO 服务端这个过程的质量报告，包含了采集、编码阶段音视频流的帧率，传输（发送）的音视频流的帧率、码率、延时及丢包率。

您可以通过注册 onPublisherQualityUpdate 接收推流质量回调，推流成功后，每隔三秒会收到此回调。您可根据 quality（ZegoPublishStreamQuality) 参数实时了解推送的音视频流的健康情况。

• 大多数情况下，您只需关注 “quality” 的 “level” 参数，以 “level” 枚举值来判断推流的综合质量，详情可参考 ZegoStreamQualityLevel。
• 如果您想关注更详细的推流质量参数，可以参考 ZegoPublishStreamQuality。

// 开发者可以在此回调中监控具体的质量以上报到业务服务器做监控，或者监控质量对象的某个字段以给用户友好的提示
ZegoExpressEngine.onPublisherQualityUpdate = (String streamID, ZegoPublishStreamQuality quality) {
    String networkQuality = "";
    // level 代表了推流质量的综合分数，大部分情况下，开发者可以参考此分数展示上行网络的质量

    switch (quality.level) {
        case ZegoStreamQualityLevel.Excellent:
           networkQuality = "非常好";
           break;
        case ZegoStreamQualityLevel.Good:
           networkQuality = "好";
           break;
        case ZegoStreamQualityLevel.Medium:
           networkQuality = "一般";
           break;
        case ZegoStreamQualityLevel.Bad:
           networkQuality = "差";
           break;
        case ZegoStreamQualityLevel.Die:
           networkQuality = "失败";
           break;
        case ZegoStreamQualityLevel.Unknown:
           networkQuality = "未知";
           break;
        default:
           break;
    }
    //("网络质量是：$networkQuality");
};

拉流质量报告

拉流质量报告指用户拉取播放音视频流这个过程的质量报告，包含了接收的音视频流的帧率、码率、延时和丢包率，解码阶段音视频流的帧率，以及渲染阶段的帧率、卡顿率、音视频整体质量。

您可以通过注册 onPlayerQualityUpdate 接收拉流质量回调，拉流成功后，每隔三秒会收到此回调。您可根据 quality（ZegoPlayStreamQuality) 参数实时了解拉取的音视频流的健康情况。

• 大多数情况下，您只需关注 “quality” 的 “level” 参数，以 “level” 枚举值来判断拉流的综合质量，详情可参考 ZegoStreamQualityLevel。
• 如果您想关注更详细的拉流质量参数，详情可参考 ZegoPlayStreamQuality。

// 开发者可以在此回调中监控具体的质量以上报到业务服务器做监控，或者监控质量对象的某个字段以给用户友好的提示
ZegoExpressEngine.onPlayerQualityUpdate = (String streamID, ZegoPlayStreamQuality quality) {
    String networkQuality = "";
    // level 代表了拉流质量的综合分数，大部分情况下，开发者可以参考此分数展示下行网络的质量

    switch (quality.level) {
        case ZegoStreamQualityLevel.Excellent:
           networkQuality = "非常好";
           break;
        case ZegoStreamQualityLevel.Good:
           networkQuality = "好";
           break;
        case ZegoStreamQualityLevel.Medium:
           networkQuality = "一般";
           break;
        case ZegoStreamQualityLevel.Bad:
           networkQuality = "差";
           break;
        case ZegoStreamQualityLevel.Die:
           networkQuality = "失败";
           break;
        case ZegoStreamQualityLevel.Unknown:
           networkQuality = "未知";
           break;
        default:
           break;
    }
    //("网络质量是：%s", networkQuality);
};

MOS 音质评分

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

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

其他信息监测

推流/拉流状态变化通知

推流状态回调

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

ZegoExpressEngine.onPublisherStateUpdate = (String streamID, ZegoPublisherState state, int errorCode, Map<String, dynamic> extendedData) {
    // 当 state 为 ZegoPublisherState.NoPublish,且 errcode 非 0 时,表示推流失败，同时不会再进行重试推流,此时可在界面作出推流失败提示    
    // 当 state 为 ZegoPublisherState.PublishRequesting ,且 errcode 非 0 时,表示在重试推流,此时如果超出重试时间未成功推流会抛出推流失败通知
};

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

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

拉流状态变更回调

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

ZegoExpressEngine.onPlayerStateUpdate = (String streamID, ZegoPlayerState state, int errorCode, Map<String, dynamic>extendedData) {
    // 当 state 为 ZegoPlayerState.NoPlay,且 errcode 非 0 时,表示拉流失败,同时不会再进行重试拉流了,此时可在界面作出拉流失败提示
    // 当 state 为 ZegoPlayerState.PlayRequesting,且 errcode 非 0 时,表示重试拉流,此时如果超出重试时间未成功拉到流会抛出拉流失败通知
};

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

接收到音频/视频首帧的通知

推流端音频采集首帧回调

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

ZegoExpressEngine.onPublisherCapturedAudioFirstFrame = () {
};

推流端视频采集首帧回调

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

ZegoExpressEngine.onPublisherCapturedVideoFirstFrame = (ZegoPublishChannel channel) {
};

拉流端音频接收首帧回调

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

ZegoExpressEngine.onPlayerRecvAudioFirstFrame = (String streamID) {
    print("onPlayerRecvAudioFirstFrame streamID:$streamID");
};

拉流端视频接收首帧回调

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

ZegoExpressEngine.onPlayerRecvVideoFirstFrame = (String streamID) {
};

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

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

ZegoExpressEngine.onPlayerRenderVideoFirstFrame = (String streamID) {
};

视频分辨率变化的回调

采集视频分辨率变更回调

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

ZegoExpressEngine.onPublisherVideoSizeChanged = (int width, int height, ZegoPublishChannel channel) {
};

拉流分辨率变更通知

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

ZegoExpressEngine.onPlayerVideoSizeChanged = (String streamID, int width, int height) {
};

相关文档

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