通话中质量监测

功能描述

在通话场景中，开发者经常需要了解当前通话的通话质量、设备状态等信息，以监测通话的整体体验，也可将部分质量数据在UI层面展示给用户，使用户能够及时了解当前通话的整体质量。

NERTC SDK能够将关键的音视频状况、网络状况、设备状态的相关指标实时回调给APP应用层，应用层可将收到的数据执行展示、统计等操作。

Android

实现方法

如果需要使用质量透明的功能，需要通过NERtc.getInstance().setStatsObserver(NERtcStatsObserver)主动设置相应的回调，取消设置成null 即可。

示例代码

NERtc.getInstance().setStatsObserver(NERtcStatsObserver)

API参考

iOS

实现方法

1. 开始前请确保你已完成环境准备、安装包获取等步骤;
2. 使用接口 addEngineMediaStatsObserver: 添加添加 media 统计信息观测者;

3. 实现代理方法中相应的接口, 可以对media 统计信息进行处理:

4. -(void)onRtcStats:(NERtcStats *)stat 当前通话统计回调, SDK 定期向 App 报告当前通话的统计信息，每 2 秒触发一次;

5. - (void)onLocalAudioStat:(NERtcAudioSendStats *)stat 本地音频流统计信息回调, 该回调描述本地设备发送音频流的统计信息，每 2 秒触发一次。
6. - (void)onRemoteAudioStats:(NSArray<NERtcAudioRecvStats*> *)stats 通话中远端音频流的统计信息回调, 该回调描述远端用户在通话中端到端的音频流统计信息，每 2 秒触发一次。
7. -(void)onLocalVideoStat:(NERtcVideoSendStats *)stat 本地视频流统计信息回调, 该回调描述本地设备发送视频流的统计信息，每 2 秒触发一次。
8. - (void)onRemoteVideoStats:(NSArray<NERtcVideoRecvStats*> *)stats 通话中远端视频流的统计信息回调, 该回调描述远端用户在通话中端到端的视频流统计信息，每 2 秒触发一次。

9. - (void)onNetworkQuality:(NSArray<NERtcNetworkQualityStats *> *)stats 通话中每个用户的网络上下行质量报告回调, 该回调描述每个用户在通话中的网络状态，每 2 秒触发一次。

10. 调用 - (int)removeEngineMediaStatsObserver:(id<NERtcEngineMediaStatsObserver>)observer 可以删除相关 media 统计信息观测器;

11. 调用 - (int)cleanupEngineMediaStatsObserver 可以清空所有 media 统计信息观测器;

示例代码

// 添加添加 media 统计信息观测者
NERtcEngine *coreEngine = [NERtcEngine sharedEngine];
[coreEngine addEngineMediaStatsObserver:<#observer#>];

//////

/**
observer.m 信息观测者实现代理方法
*/

- (void)onRtcStats:(NERtcStats *)stat {
    // 当前通话统计回调
}

- (void)onLocalAudioStat:(NERtcAudioSendStats *)stat {
    // 本地音频流统计信息回调
}

- (void)onRemoteAudioStats:(NSArray<NERtcAudioRecvStats*> *)stats {
    // 本地音频流统计信息回调
}

- (void)onLocalVideoStat:(NERtcVideoSendStats *)stat {
    // 本地视频流统计信息回调
}

- (void)onRemoteVideoStats:(NSArray<NERtcVideoRecvStats*> *)stats {
    // 通话中远端视频流的统计信息回调
}

- (void)onNetworkQuality:(NSArray<NERtcNetworkQualityStats *> *)stats {
    // 通话中每个用户的网络上下行质量报告回调
}

API参考

Windows/macOS

实现方法

如果需要使用质量透明的功能，需要通过setStatsObserver主动设置相应的回调，取消设置成null 即可。

示例代码

class StatsObserver : IRtcMediaStatsObserver
{

};

StatsObserver *observer = nullptr;

rtc_engine_->setStatsObserver(observer);

API参考

Web

实现方法

1. 监听'network-quality'事件，获取本地用户的上下行网络质量相关的统计数据
2. 监听'connection-state-change'事件，获取SDK与服务器的连接状态
3. 监听'exception'事件，获取应用频道内的异常事件
4. 调用'getTransportStats'方法，获取获取网络相关数据
5. 调用'getSessionStats'方法，获取当前会话的统计数据
6. 调用'getLocalAudioStats'方法，获取本地发布流的统计数据
7. 调用'getLocalVideoStats'方法，本地发布流的视频统计数据
8. 调用'getRemoteAudioStats'方法，获取远端订阅流的统计数据
9. 调用'getRemoteVideoStats'方法，获取远端订阅流的视频统计数据

示例代码

获取本地用户的上下行网络质量相关的统计数据

云信 Web SDK 通过 client.on 中的 network-quality 回调向 App 报告房间里所有成员的上下行网络质量。该回调每当发生变化的时候触发，返回的参数（数组格式），其中的元素包括：

• downlinkNetworkQuality：下行网络质量打分。
• uplinkNetworkQuality：上行网络质量打分。
• uid: 房间里具体那位成员的网络情况

client.on('network-quality', stats => {
  console.log('=====房间里所有成员的网络状况：', stats)
  let status = null
  stats.forEach(item => {
    status = 'uid: ' + item.uid + ',上行： ' + item.uplinkNetworkQuality + ',下行： ' + item.downlinkNetworkQuality
    console.log(status)
  })
})

• 参数说明

SDK与服务器的连接状态

云信 Web SDK 通过 Client.on 中的 connection-state-change 回调向 App 报告sdk与服务器之间的连接状态发生改变。该回调每当发生变化的时候触发，返回的参数（对象格式），其中的元素包括：

• prevState：上一次的状态。
• curState：当前状态。

client.on('connection-state-change', evt => {
  console.log(evt.prevState, evt.curState);
})

• SDK与服务器的连接状态参数说明：

通知应用频道内的异常事件

该回调通知应用频道内的异常事件。 异常事件不是错误，但是往往会引起通话质量问题。 发生异常事件后，如果恢复正常，也会收到该回调通知。

client.on("exception", function(evt) {
  console.log(evt.code, evt.msg, evt.uid);
});

• 异常事件说明：

获取系统信息

调用 client.getSystemStats 方法获取系统信息。目前只能获取系统电量信息。

client.getSystemStats((stats) => {
    console.log(`Current battery level: ${stats.BatteryLevel}`);
});

该功能处于实验阶段，浏览器兼容信息请参考 Battery Status API。

获取网络相关数据

调用 client.getTransportStats 方法获取网络类型和网络连接状况统计数据。具体参数如下：

• NetworkType：网络类型，如 Wi-Fi、蜂窝移动数据网络、蓝牙网络等。
• OutgoingAvailableBandwidth：上行可用带宽估计（Kbps）。
• txRtt：云信SDK到云信SDK接入节点的平均往返延时（ RTT，Round-Trip Time），单位 ms。

setInterval(() => {
  client.getTransportStats((stats) => {
    console.log(`Current Transport txRtt: ${stats.txRtt}`);
    console.log(`Current Network Type: ${stats.networkType}`);
    console.log(`Current Transport OutgoingAvailableBandwidth: ${stats.OutgoingAvailableBandwidth}`);
  });
}, 1000)    

获取当前会话的统计数据

调用 client.getSessionStats 方法获取与当前会话相关的统计数据，包括：

• Duration：在当前频道内的时长（秒）。
• RecvBitrate：音视频总接收码率（Kbps），瞬间值。
• RecvBytes：接收字节数，累计值。
• SendBitrate：音视频总发送码率（Kbps），瞬间值。
• SendBytes：发送字节数，累计值。
• UserCount：通信场景下，该值为当前频道内的用户人数。直播场景下，如果本地用户为主播，该值为当前频道内的主播人数；如果本地用户为观众，该值为当前频道内的主播人数 + 1。

  setInterval(() => {
  client.getSessionStats((stats) => {
    console.log(`Current Session Duration: ${stats.Duration}`);
    console.log(`Current Session UserCount: ${stats.UserCount}`);
    console.log(`Current Session SendBytes: ${stats.SendBytes}`);
    console.log(`Current Session RecvBytes: ${stats.RecvBytes}`);
    console.log(`Current Session SendBitrate: ${stats.SendBitrate}`);
    console.log(`Current Session RecvBitrate: ${stats.RecvBitrate}`);
  });
  }, 1000)

本方法仅支持 Chrome 浏览器。

获取本地发布流的统计数据

调用以下方法获取本地发布流的音频和视频统计数据。

本地发布流的音频统计数据

client.getLocalAudioStats 方法提供本地发布流的音频统计数据，包括：

• CodecType：音频编码类型。
• MuteState：音频是否静音。
• RecordingLevel：音频采集能量。
• SamplingRate：音频采样率（kHz）。
• SendBitrate：音频发送码率（Kbps）。
• SendLevel：音频发送能量。

setInterval(() => {
  client.getLocalAudioStats((localAudioStats) => {
    for(var uid in localAudioStats){
      console.log(`Audio CodecType from ${uid}: ${localAudioStats[uid].CodecType}`);
      console.log(`Audio MuteState from ${uid}: ${localAudioStats[uid].MuteState}`);
      console.log(`Audio RecordingLevel from ${uid}: ${localAudioStats[uid].RecordingLevel}`);
      console.log(`Audio SamplingRate from ${uid}: ${localAudioStats[uid].SamplingRate}`);
      console.log(`Audio SendBitrate from ${uid}: ${localAudioStats[uid].SendBitrate}`);
      console.log(`Audio SendLevel from ${uid}: ${localAudioStats[uid].SendLevel}`);
    }
  });
}, 1000)

本方法仅支持 Chrome 浏览器。

本地发布流的视频统计数据

client.getLocalVideoStats 方法提供本地发布流的视频统计数据，一个 uid 对应一组数据，包括：

• CaptureFrameRate：视频采集帧率（fps）。
• CaptureResolutionHeight：视频采集分辨率高度，单位为像素。
• CaptureResolutionWidth：视频采集分辨率宽度，单位为像素。
• EncodeDelay：本地视频从采集到编码的延时（ms）。
• MuteState：视频画面是否开启。
• SendBitrate：视频发送码率（Kbps）。
• SendFrameRate：视频发送帧率（fps）。
• SendResolutionHeight：视频发送分辨率高度，单位为像素。
• SendResolutionWidth：视频发送分辨率宽度，单位为像素。
• TargetSendBitrate：setVideoProfile 中设置的目标发送码率（Kbps）。
• TotalDuration：从视频流发布到当前时间的总时长，单位为秒。
• TotalFreezeTime：视频编码卡顿总时间，单位为秒。

setInterval(() => {
  client.getLocalVideoStats((localVideoStats) => {
    for(var uid in localVideoStats){
      console.log(`Video CaptureFrameRate from ${uid}: ${localVideoStats[uid].CaptureFrameRate}`);
      console.log(`Video CaptureResolutionHeight from ${uid}: ${localVideoStats[uid].CaptureResolutionHeight}`);
      console.log(`Video CaptureResolutionWidth from ${uid}: ${localVideoStats[uid].CaptureResolutionWidth}`);
      console.log(`Video EncodeDelay from ${uid}: ${localVideoStats[uid].EncodeDelay}`);
      console.log(`Video MuteState from ${uid}: ${localVideoStats[uid].MuteState}`);
      console.log(`Video SendBitrate from ${uid}: ${localVideoStats[uid].SendBitrate}`);
      console.log(`Video SendFrameRate from ${uid}: ${localVideoStats[uid].SendFrameRate}`);
      console.log(`Video SendResolutionHeight from ${uid}: ${localVideoStats[uid].SendResolutionHeight}`);
      console.log(`Video SendResolutionWidth from ${uid}: ${localVideoStats[uid].SendResolutionWidth}`);
      console.log(`Video TargetSendBitrate from ${uid}: ${localVideoStats[uid].TargetSendBitrate}`);
      console.log(`Video TotalDuration from ${uid}: ${localVideoStats[uid].TotalDuration}`);
      console.log(`Video TotalFreezeTime from ${uid}: ${localVideoStats[uid].TotalFreezeTime}`);
    }
  });
}, 1000)

本方法仅支持 Chrome 浏览器。

获取远端订阅流的统计数据

调用以下方法获取本地订阅流的音频和视频统计数据。

获取远端订阅流的音频统计数据

Client.getRemoteAudioStats 方法提供远端订阅流的音频统计数据，一个 uid 对应一组数据，包括：

• CodecType：音频编码类型。
• End2EndDelay：端到端延时（ms），从远端采集音频到本地播放音频的延时。
• MuteState：音频是否静音。
• PacketLossRate：远端音频的丢包率（%）。
• RecvBitrate：音频接收码率（Kbps）。
• RecvLevel：接收音频的音量。
• TotalFreezeTime：音频卡顿总时间（s）。
• TotalPlayDuration：音频播放总时长（s）。
• TransportDelay：传输延时（ms），从远端发送音频到本地接收音频的延时。

setInterval(() => {
  client.getRemoteAudioStats((remoteAudioStatsMap) => {
    for(var uid in remoteAudioStatsMap){
      console.log(`Audio CodecType from ${uid}: ${remoteAudioStatsMap[uid].CodecType}`);
      console.log(`Audio End2EndDelay from ${uid}: ${remoteAudioStatsMap[uid].End2EndDelay}`);
      console.log(`Audio MuteState from ${uid}: ${remoteAudioStatsMap[uid].MuteState}`);
      console.log(`Audio PacketLossRate from ${uid}: ${remoteAudioStatsMap[uid].PacketLossRate}`);
      console.log(`Audio RecvBitrate from ${uid}: ${remoteAudioStatsMap[uid].RecvBitrate}`);
      console.log(`Audio RecvLevel from ${uid}: ${remoteAudioStatsMap[uid].RecvLevel}`);
      console.log(`Audio TotalFreezeTime from ${uid}: ${remoteAudioStatsMap[uid].TotalFreezeTime}`);
      console.log(`Audio TotalPlayDuration from ${uid}: ${remoteAudioStatsMap[uid].TotalPlayDuration}`);
      console.log(`Audio TransportDelay from ${uid}: ${remoteAudioStatsMap[uid].TransportDelay}`);
    }
  });
}, 1000)

本方法仅支持 Chrome 浏览器。

获取远端订阅流的视频统计数据

client.getRemoteVideoStats 方法提供远端订阅流的视频统计数据，一个 uid 对应一组数据，包括：

• End2EndDelay：端到端延时（ms），从远端采集视频到本地播放视频的延时。
• MuteState：视频画面是否开启。
• PacketLossRate：远端视频的丢包率（%）。
• RecvBitrate：视频接收码率（Kbps）。
• RecvResolutionHeight：视频接收分辨率高度，单位为像素。
• RecvResolutionWidth：视频接收分辨率宽度，单位为像素。
• RenderFrameRate：渲染帧率（fps），视频解码输出帧率。
• RenderResolutionHeight：视频渲染分辨率高度，单位为像素。
• RenderResolutionWidth：视频渲染分辨率宽度，单位为像素。
• TotalFreezeTime：视频卡顿总时间，单位为秒。
• TotalPlayDuration：视频播放总时间，单位为秒。
• TransportDelay：传输延时（ms），从远端发送视频到本地接收视频的延时。

setInterval(() => {
  client.getRemoteVideoStats((remoteVideoStatsMap) => {
    for(var uid in remoteVideoStatsMap){
      console.log(`Video End2EndDelay from ${uid}: ${remoteVideoStatsMap[uid].End2EndDelay}`);
      console.log(`Video MuteState from ${uid}: ${remoteVideoStatsMap[uid].MuteState}`);
      console.log(`Video PacketLossRate from ${uid}: ${remoteVideoStatsMap[uid].PacketLossRate}`);
      console.log(`Video RecvBitrate from ${uid}: ${remoteVideoStatsMap[uid].RecvBitrate}`);
      console.log(`Video RecvResolutionHeight from ${uid}: ${remoteVideoStatsMap[uid].RecvResolutionHeight}`);
      console.log(`Video RecvResolutionWidth from ${uid}: ${remoteVideoStatsMap[uid].RecvResolutionWidth}`);
      console.log(`Video RenderFrameRate from ${uid}: ${remoteVideoStatsMap[uid].RenderFrameRate}`);
      console.log(`Video RenderResolutionHeight from ${uid}: ${remoteVideoStatsMap[uid].RenderResolutionHeight}`);
      console.log(`Video RenderResolutionWidth from ${uid}: ${remoteVideoStatsMap[uid].RenderResolutionWidth}`);
      console.log(`Video TotalFreezeTime from ${uid}: ${remoteVideoStatsMap[uid].TotalFreezeTime}`);
      console.log(`Video TotalPlayDuration from ${uid}: ${remoteVideoStatsMap[uid].TotalPlayDuration}`);
      console.log(`Video TransportDelay from ${uid}: ${remoteVideoStatsMap[uid].TransportDelay}`);
    }
  });
}, 1000)

本方法仅支持 Chrome 浏览器。

API参考