在网络会议、重要直播等对音视频通话质量等要求较高的场景下，需要在通话前进行调试，例如检测上下行网络质量，以提前识别网络问题或判断当前网络环境下适合的音视频流码率。NERTC SDK 支持网络测速功能，帮助您保证高质量的音视频通话体验。

文中部分 API 在 1.0.0 Beta 版本中暂未开放，如果您有相关需求，请联系网易云信技术支持工程师。

功能介绍

NERTC SDK 提供通话前网络探测相关接口与回调方法，用户在加入房间前可以探测当前设备到网易云信边缘服务器的网络状态，即上下行 last mile 的网络质量，包括带宽、丢包率、网络抖动和往返时延等数据，以判断或预测本端当前的网络状况。

网络质量探测的基本原理是 NERTC SDK 向网易云信边缘服务器节点发送一批网络探测数据包，然后分析返回数据包的质量，通过回调以数据报告的形式返回给客户端。

基本原理图 如下：

• 当上行测速结果显示丢包率较高时，推荐使用降低分辨率或降低帧率等方法降低发流码率，以保证正常发流。
• 当下行测速结果显示丢包率较高时，推荐使用视频流回退功能指定订阅远端低码率的流，以保证正常接收。

注意事项

• 请在 加入房间前 使用网络质量探测功能，即 startLastmileProbeTest 需要在 joinChannel 之前调用。
• 调用 startLastmileProbeTest 进行通话前网络质量探测时，会消耗一定的网络流量。因此调用方法后，建议在收到 onLastmileProbeResult 回调之前不要调用其他方法，避免因 API 操作过于频繁导致其他方法无法执行。
• 开启网络测试后，NERTC SDK 会根据当前设置的视频分辨率自动调整探测码率。
• 视频通话期间请勿测试，以免影响通话质量。

示例项目源码

网易云信提供 通话前网络质量检测的示例项目源码 NetworkTest，您可以参考该源码实现通话前网络质量检测。

API 调用时序

sequenceDiagram
    participant 应用层
    participant NERtcSDK
    应用层 ->> NERtcSDK: init 初始化 NERtcEngine
    Note over 应用层, 云信服务器: 通话前网络质量探测
    应用层 ->> NERtcSDK: startLastmileProbeTest
    NERtcSDK-->>应用层: onLastmileQuality
    Note right of NERtcSDK: 通知网络质量状态，约 5 秒内返回。
    NERtcSDK-->>应用层: onLastmileProbeResult
    Note right of NERtcSDK: 报告网络质量详细数据，约 30 秒内返回。
    应用层 ->> NERtcSDK: stopLastmileProbeTest
    Note over 应用层, 云信服务器: 加入房间、离开房间
    应用层 ->> NERtcSDK: joinChannel
    NERtcSDK ->> 云信服务器: 请求加入房间
    NERtcSDK-->>应用层: onJoinChannel
    应用层 ->> NERtcSDK: leaveChannel
    NERtcSDK-->>应用层: onLeaveChannel
    应用层 ->> NERtcSDK: release 销毁 NERtcEngine

实现方法

1. 注册探测回调监听。

   • onLastmileQuality：描述本端用户在加入频道前的 last mile 网络探测的结果，以打分形式描述上下行网络质量的主观体验，您可以通过该回调预估本地用户在音视频通话中的网络体验。该回调视网络情况在约 5 秒内返回。
   • onLastmileProbeResult：描述本地用户在加入频道前的 last mile 网络探测详细报告，报告中通过客观数据反馈上下行网络质量，包括网络抖动、丢包率等数据。您可以通过该回调客观预测本地用户在音视频通话中的网络状态。该回调视网络情况在约 30 秒内返回。

   示例代码如下：

   typescriptclass NERtcEventCallback extends NERtcCallbackEx {
       ...
       onLastmileQuality(quality: number): void {
           //根据实际的业务场景向用户展示以打分的主观形式评估的网络上下行质量
       }
   
       onLastmileProbeResult(result: NERtcConstants.LiteSDKProbeResult): void {
           //根据实际的业务场景向用户展示上下行网络质量的实际探测数据
       }
       ...
   }
   
   let option: NERtcConstants.NERtcOption = { logLevel: NERtcConstants.LogLevel.INFO }
   NERtcSDK.getInstance().init(context, Config.APP_KEY, new NERtcEventCallback(), option)
   
   

2. 在加入房间前，调用 startLastmileProbeTest 方法进行网络质量探测，并通过 LastmileProbeConfig 结构体设置是否探测上行或下行网络以及对应的期望码率，相关参数的说明如下表所示。

   参数	参数说明
   expectedUplinkBitrate	本端期望的最高发送码率。单位为 bps，取值范围为 100000 ~ 5000000。推荐参考 setLocalVideoConfig 中的视频编码码率设置该参数的值。
   expectedDownlinkBitrate	本端期望的最高接收码率。单位为 bps，取值范围为 100000 ~ 5000000。
   probeUplink	是否探测上行网络。 true：探测上行网络。 false：不探测上行网络。不发流的用户，例如直播房间中的普通观众，无需进行上行网络探测。
   probeDownlink	是否探测下行网络。 true：探测下行网络。 false：不探测下行网络。

   示例代码 如下：

   typescriptlet probeConfig: NERtcConstants.LastmileProbeConfig = {
     probeUplink: //是否开启上行探速度,
     probeDownlink: //是否开启下行探速,
     expectedUplinkBitrate: //预期最高发送探测码率,
     expectedDownlinkBitrate: //预期最高接收码率
   }
   NERtcSDK.getInstance().startLastmileProbeTest(probeConfig)
   

3. 成功调用探测方法后，测速结果将在 onLastmileQuality 和 onLastmileProbeResult 回调中返回。

   • onLastmileQuality 的 quality 参数 以打分的主观形式 评估网络上下行质量，具体枚举值说明如下表所示。

     枚举值	说明
     QUALITY_UNKNOWN（0）	质量未知
     QUALITY_EXCELLENT（1）	质量极好
     QUALITY_GOOD（2）	用户主观体验相当于极好，但码率可能略低。
     QUALITY_POOR（3）	用户主观体验有瑕疵，但不影响沟通。
     QUALITY_BAD（4）	勉强能沟通，但不顺畅。
     QUALITY_VBAD（5）	网络质量非常差，基本不能沟通。
     QUALITY_DOWN（6）	完全无法沟通。

   • onLastmileProbeResult 通过 LiteSDKProbeResult 提供客观数据 反馈上下行网络质量，具体参数说明如下表所示。

     参数	参数说明
     state	反映本次网络质量探测结果的状态： LASTMILE_PROBE_RESULT_COMPLETE（1）：本次进行了完整的网络质量探测。 LASTMILE_PROBE_RESULT_INCOMPLETE_NO_BWE（2）：本次未进行完整的网络质量探测，缺少带宽预测，通常因为测试资源暂时受限。 LASTMILE_PROBE_RESULT_UNAVAILABLE（3）：本次未进行网络质量探测，通常因为网络连接中断。
     rtt	网络延时，单位为毫秒（ms）。
     uplinkReport	上行网络质量报告。
     downlinkReport	下行网络质量报告。

     其中网络质量探测结果报告中包括以下数据：

     参数	参数说明
     availableBandwidth	可用网络带宽预估，单位为 Kbps。
     jitter	网络抖动，单位为毫秒 (ms)。
     packetLossRate	丢包率。

4. 停止探测。

   探测过程中，若您需要停止探测，可以随时调用 stopLastmileProbeTest 方法停止通话前网络质量探测。

   示例代码 如下：

   typescriptNERtcSDK.getInstance().stopLastmileProbeTest();
   

API 列表

方法	功能描述
startLastmileProbeTest	开始网络质量探测。
stopLastmileProbeTest	停止网络质量探测。

事件回调

事件	事件描述
onLastmileQuality	网络质量探测打分结果。
onLastmileProbeResult	网络质量探测报告。