如何基于 ZEGO SDK 实现 Android 通话质量监测

功能简介

在进行视频通话过程当中，用户有时候会出现网络很差的状况，好比在进行多人视频通话或者多人唱歌时，咱们须要实时显示用户的网络质量。 java

示例源码

参考 下载示例源码 获取源码。服务器

相关源码请查看 “/ZegoExpressExample/AdvancedStreaming/src/main/java/im/zego/streammonitoring” 目录下的文件。网络

前提条件

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

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

基础网络质量报告

能够经过监听 onNetworkQuality 回调，收到房间内用户（包括本身）的上下行网络质量。此回调每隔两秒会收到一次，网络质量等级请参考 ZegoStreamQualityLevel。编码

不一样版本的 onNetworkQuality 回调逻辑有所不一样：url

• 对于使用 2.14.0 及以上版本 ZEGO Express SDK 的用户，onNetworkQuality 回调的逻辑为：.net

  • 只要推流或者拉流，就能收到本身的网络质量回调。
  • 当拉取了其余用户推送的音视频流而且该用户在房间内时，才会收到该用户的网络质量回调。
  • 当 “userID” 为 “null” 时，表明本次是本身的网络质量，当 “userID” 不为 “null” 时，表明是房间内其余用户的报告。

• 对于使用 2.10.0 至 2.13.1 版本 ZEGO Express SDK 的用户，onNetworkQuality 回调的逻辑为：code

  • 必须既推流又拉流，才会收到自身的网络质量回调。
  • 当拉取一条流时，推送该条流的用户必须在同一房间内，且他也进行了拉流，才会收到该用户的网络质量回调。
  • 当 “userID” 为 “null” 时，表明本次是本身的网络质量，当 “userID” 不为 “null” 时，表明是房间内其余用户的报告。

<div class="mk-warning">视频

onNetworkQuality 不适用于使用 CDN 进行直播的场景，能够参考 进阶质量报告 - 推流质量报告 监测 CDN 的推流质量。对象

</div>

public void setEngineEventHandler(){
        engine.setEventHandler(new IZegoEventHandler() {
            @Override
            public void onNetworkQuality(String userID, ZegoStreamQualityLevel upstreamQuality, ZegoStreamQualityLevel downstreamQuality) {
                super.onNetworkQuality(userID, upstreamQuality, downstreamQuality);
                if (userID == null) {
                    // 表明本地用户（我）的网络质量
                    //("个人上行网络质量是 %lu", (unsigned long)upstreamQuality);
                    //("个人下行网络质量是 %lu", (unsigned long)downstreamQuality);
                } else {
                    //表明房间内其余用户的网络质量
                    //("用户 %s 的上行网络质量是 %lu", userID, (unsigned long)upstreamQuality);
                    //("用户 %s 的下行网络质量是 %lu", userID, (unsigned long)downstreamQuality);
                }

                /*
                ZegoStreamQualityLevel.EXCELLENT, 网络质量极好
                ZegoStreamQualityLevel.GOOD, 网络质量好
                ZegoStreamQualityLevel.MEDIUM, 网络质量正常
                ZegoStreamQualityLevel.BAD, 网络质量差
                ZegoStreamQualityLevel.DIE, 网络异常
                ZegoStreamQualityLevel.UNKNOWN, 网络质量未知
                */

            }
        });
           
    }

进阶质量报告

若是上述的基础网络质量报告不能知足需求，ZEGO 还提供了更详细的推流质量报告、拉流质量报告以及其余相关信息。

推流质量报告

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

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

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

    engine.setEventHandler(new IZegoEventHandler() {

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

                switch (quality.level) {
                    case EXCELLENT:
                        networkQuality = "很是好";
                        break;
                    case GOOD:
                        networkQuality = "好";
                        break;
                    case MEDIUM:
                        networkQuality = "通常";
                        break;
                    case BAD:
                        networkQuality = "差";
                        break;
                    case DIE:
                        networkQuality = "失败";
                        break;
                    case UNKNOWN:
                        networkQuality = "未知";
                        break;
                    default:
                        break;
                }
                //("网络质量是：%s", networkQuality);
            }
        });

拉流质量报告

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

能够经过注册 onPlayerQualityUpdate 接收拉流质量回调，拉流成功后每隔三秒会收到此回调。开发者可根据 quality(ZegoPlayStreamQuality) 参数实时了解拉取的音视频流的健康状况。

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

    engine.setEventHandler(new IZegoEventHandler() {
            // 开发者能够在此回调中监控具体的质量以上报到业务服务器作监控，或者监控质量对象的某个字段以给用户友好的提示
            @Override
            public void onPlayerQualityUpdate(String streamID, ZegoPlayStreamQuality quality) {
                String networkQuality = "";
                // level 表明了拉流质量的综合分数，大部分状况下，开发者能够参考此分数展现下行网络的质量

                switch (quality.level) {
                    case EXCELLENT:
                        networkQuality = "很是好";
                        break;
                    case GOOD:
                        networkQuality = "好";
                        break;
                    case MEDIUM:
                        networkQuality = "通常";
                        break;
                    case BAD:
                        networkQuality = "差";
                        break;
                    case DIE:
                        networkQuality = "失败";
                        break;
                    case UNKNOWN:
                        networkQuality = "未知";
                        break;
                    default:
                        break;
                }
                //("网络质量是：%s", networkQuality);
            }
        });
}

MOS 音质评分

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

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

<table> <colgroup> <col> <col> </colgroup> <tbody><tr> <th>MOS 值</th> <th>评价标准</th> </tr> <tr> <td>4.0～5.0</td> <td>音质很好，清晰流畅，听的清楚。</td> </tr> <tr> <td>3.5～4.0</td> <td>音质较好，偶有音质损伤，但依然清晰流畅，听的清楚。</td> </tr> <tr> <td>3.0～3.5</td> <td>音质通常，偶有卡顿，须要一点注意力才能听清。</td> </tr> <tr> <td>2.5～3.0</td> <td>音质较差，卡顿频繁，须要集中注意力才能听清。</td> </tr> <tr> <td>2.0～2.5</td> <td>音质不好，部分语义丢失，难以交流。</td> </tr> <tr> <td>小于 2.0</td> <td>音质极差，大量语义丢失，没法交流。</td> </tr> <tr> <td>-1</td> <td>未知。</td> </tr> </tbody></table>

其余信息监测

推流/拉流状态变化通知

1. 推流状态回调

在推流成功后，能够经过 onPublisherStateUpdate 获取推流状态变动的通知。

engine.setEventHandler(new IZegoEventHandler() {
    @Override
    public void onPublisherStateUpdate(String streamID, ZegoPublisherState state, int errorCode, JSONObject extendedData) {
        super.onPublisherStateUpdate(streamID, state, errorCode, extendedData);
        // 当 state 为 PUBLISHER_STATE_NO_PUBLISH 时，且 errcode 非 0，表示推流失败，同时不会再进行重试推流了，此时可在界面做出推流失败提示；    
        // 当 state 为 PUBLISHER_STATE_PUBLISH_REQUESTING 时，且 errcode 非 0，表示在重试推流，此时若是超出重试时间未成功推流会抛出推流失败通知。
    }
}

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

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

2. 拉流状态变动回调

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

engine.setEventHandler(new IZegoEventHandler() {
    @Override
    public void onPlayerStateUpdate(String streamID, ZegoPlayerState state, int errorCode, JSONObject extendedData) {
        super.onPlayerStateUpdate(streamID, state, errorCode, extendedData);
        // 当 state 为 PLAYER_STATE_NO_PLAY 时，且 errcode 非 0，表示拉流失败，同时不会再进行重试拉流了，此时可在界面做出拉流失败提示；
        // 当 state 为 PLAYER_STATE_PLAY_REQUESTING 时，且 errcode 非 0，表示重试拉流，此时若是超出重试时间未成功拉到流会抛出拉流失败通知。
    }
}

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

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

1. 推流端音频采集首帧回调

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

<div class='mk-hint'>

在未推流或未预览的状况下，首次推流或首次预览，即 SDK 内部的音视频模块的引擎启动时，会去采集本机设备的音频数据，会收到该回调。开发者可根据该回调判断 SDK 是否真的采集到音频数据，若未收到该回调，说明音频采集设备被占用或异常。

</div>

engine.setEventHandler(new IZegoEventHandler() {
    @Override
    public void onPublisherCapturedAudioFirstFrame() {
        super.onPublisherCapturedAudioFirstFrame();
    }
}

2. 推流端视频采集首帧回调

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

<div class='mk-hint'>

在未推流或未预览的状况下，首次推流或首次预览，即 SDK 内部的音视频模块的引擎启动时，会去采集本机设备的视频数据，会收到该回调。能够根据该回调判断 SDK 是否真的采集到视频数据，若未收到该回调，说明视频采集设备被占用或异常。

</div>

engine.setEventHandler(new IZegoEventHandler() {
    @Override
    public void onPublisherCapturedVideoFirstFrame(ZegoPublishChannel channel) {
    super.onPublisherCapturedVideoFirstFrame(channel);
    }
}

3. 拉流端音频接收首帧回调

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

engine.setEventHandler(new IZegoEventHandler() {
    @Override
    public void onPlayerRecvAudioFirstFrame(String streamID) {
        super.onPlayerRecvAudioFirstFrame(streamID);
        AppLogger.getInstance().receiveCallback("onPlayerRecvAudioFirstFrame streamID:%s",streamID);
    }
}

4. 拉流端视频接收首帧回调

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

engine.setEventHandler(new IZegoEventHandler() {
    @Override
    public void onPlayerRecvVideoFirstFrame(String streamID) {
        super.onPlayerRecvVideoFirstFrame(streamID);
    }
}

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

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

<div class='mk-hint'>

能够用该回调来统计首帧耗时或更新播放流的 UI 组件。

</div>

engine.setEventHandler(new IZegoEventHandler() {
    @Override
    public void onPlayerRenderVideoFirstFrame(String streamID){
        super.onPlayerRenderVideoFirstFrame(streamID);
    }
}

视频分辨率变化的回调

1. 采集视频分辨率变动回调

能够经过注册 onPublisherVideoSizeChanged 监听采集视频大小变动回调。推流成功后，在推流中途若是视频采集分辨率发生变化将会收到此回调。

<div class='mk-hint'>

当在未推流或未预览的状况下，首次推流或首次预览，即 SDK 内部的音视频模块的引擎启动时，会去采集本机设备的视频数据，此时采集分辨率会改变。

能够根据此回调来去除本地预览的 UI 的遮盖等相似操做。也能够根据该回调的分辨率来动态调整预览视图的比例等。

</div>

engine.setEventHandler(new IZegoEventHandler() {
    @Override
    public void onPublisherVideoSizeChanged(int width, int height, ZegoPublishChannel channel) {
        super.onPublisherVideoSizeChanged(width, height, channel);
    }
}

2. 拉流分辨率变动通知

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

<div class='mk-hint'>

• 若拉的流只有音频数据，会收不到该回调。
• 若推流端因为网络问题触发 SDK 内部的流量控制时，可能会动态减少推流端的编码分辨率，此时也会收到此回调。所拉的音视频流真正渲染到所设置 UI 播放界面时会触发此回调。开发者可利用该回调通知来更新或切换真正播放流的 UI 组件。

</div>

engine.setEventHandler(new IZegoEventHandler() {
    @Override
    public void onPlayerVideoSizeChanged(String streamID, int width, int height) {
    }
}

API 参考列表

获取Demo

获取本文的Demo、开发文档、技术支持。

获取SDK的商务活动、热门产品。

注册即构ZEGO开发者账号，快速开始。