通话质量监测

---

功能简介

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

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

相关概念解释:

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

示例源码下载

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

相关源码请查看 “/page/example/advance-stream/stream-monitor.nvue” 目录下的文件。

前提条件

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

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

使用步骤

监测推流质量

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

ZegoExpressEngine.instance().on("publisherQualityUpdate", (streamID, quality) => {
    console.info(`publisherQualityUpdate:width:streamID:${streamID}, quality:${JSON.stringify(quality)}`);
    // 开发者可以在此回调中监控具体的质量以上报到业务服务器做监控，或者监控质量对象的某个字段以给用户友好的提示
    // 若开发者不知道监控质量哪个字段可以关注 level 字段，这个字段是质量对象的综合值
})

推流质量详解

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

推流采集质量

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

• audioCaptureFPS：音频采集帧率（fps，仅 App 有返回）
• videoCaptureFPS：视频采集帧率（fps，Web 不支持该参数）

推流编码质量

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

• videoEncodeFPS：当前编码器的目标视频编码帧率（fps，Web 不支持该参数）

推流发送质量

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

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

字节数统计

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

• totalSendBytes：已发送的总字节数（Web 不支持该参数）
• audioSendBytes：已发送的音频字节数（Web 不支持该参数）
• videoSendBytes：已发送的视频字节数（Web 不支持该参数）

编码信息

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

• videoCodecID：视频编码格式（Web 不支持该参数）
• isHardwareEncoder：是否开启硬件编码（Web 不支持该参数）

上行网络综合质量

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

level 字段的说明如下：

在 Web 平台，开发者可以关注 videoQuality 和 audioQuality

检测拉流质量

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

ZegoExpressEngine.instance().on("playerQualityUpdate", (streamID, quality) => {
    console.info(`playerQualityUpdate:streamID:${streamID}, quality:${JSON.stringify(quality)}`);
    // 开发者可以在此回调中监控具体的质量以上报到业务服务器做监控，或者监控质量对象的某个字段以给用户友好的提示
    // 若开发者不知道监控质量哪个字段可以关注 level 字段，这个字段是质量对象的综合值
})

拉流质量详解

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

拉流接收质量

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

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

拉流渲染质量

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

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

字节数统计

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

• totalRecvBytes：已接收的总字节数，包括音频、视频和 SEI 等（Web 不支持该参数）
• audioRecvBytes：已接收的音频字节数（Web 不支持该参数）
• videoRecvBytes：已接收的视频字节数（Web 不支持该参数）

解码信息

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

• videoCodecID：视频解码格式（Web 不支持该参数）
• isHardwareDecode：是否开启硬件解码（Web 不支持该参数）

监控推流/拉流状态

推流状态回调

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

ZegoExpressEngine.instance().on("publisherStateUpdate", (streamID, state, errorCode, extendedData) => {
    console.info(`publisherStateUpdate:streamID:${streamID}, state:${state}, errorCode:${errorCode}, extendedData:${JSON.stringify(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。

拉流状态变更回调

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

ZegoExpressEngine.instance().on("playerStateUpdate", (streamID, state, errorCode, extendedData) => {
    console.info(`playerStateUpdate:streamID:${streamID}, state:${state}, errorCode:${errorCode}, extendedData:${JSON.stringify(extendedData)}`);
    // 当 state 为 ZegoPlayerState.NoPlay 时，且 errcode 非 0，表示推流失败，同时不会再进行重试推流了，此时可在界面作出推流失败提示；    
    // 当 state 为 ZegoPlayerState.PlayRequesting 时，且 errcode 非 0，表示在重试推流，此时如果超出重试时间未成功推流会抛出推流失败通知。
})

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

音视频首帧回调

推流端音频采集首帧回调

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

ZegoExpressEngine.instance().on("publisherCapturedAudioFirstFrame", () => {
    console.info(`publisherCapturedAudioFirstFrame`);
})

推流端视频采集首帧回调

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

ZegoExpressEngine.instance().on("publisherCapturedVideoFirstFrame", (channel) => {
    console.info(`publisherCapturedVideoFirstFrame:width:channel:${channel}`);
})

拉流端音频接收首帧回调

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

ZegoExpressEngine.instance().on("playerRecvAudioFirstFrame", (streamID) => {
    console.info(`playerRecvAudioFirstFrame:streamID:${streamID}`);
})

拉流端视频接收首帧回调

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

ZegoExpressEngine.instance().on("playerRecvVideoFirstFrame", (streamID) => {
    console.info(`playerRecvVideoFirstFrame:streamID:${streamID}`);
})

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

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

ZegoExpressEngine.instance().on("playerRenderVideoFirstFrame", (streamID) => {
    console.info(`playerRenderVideoFirstFrame:streamID:${streamID}`);
})

监控视频分辨率变化

采集视频分辨率变更回调

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

ZegoExpressEngine.instance().on("publisherVideoSizeChanged", (width, height, channel) => {
    console.info(`publisherVideoSizeChanged:width:${width}, height:${height}, channel:${channel}`);
})

拉流分辨率变更通知

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

ZegoExpressEngine.instance().on("playerVideoSizeChanged", (streamID, width, height) => {
    console.info(`playerVideoSizeChanged:streamID:${streamID},width:${width},height:${height}`);
})