通话中质量监测

功能描述

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

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

Android

实现方法

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

示例代码

NERtc.getInstance().setStatsObserver(NERtcStatsObserver)

API参考

Class 功能描述
NERtcStatsObserver 统计信息回调类
事件 功能描述
onRtcStats 当前通话统计回调
onLocalAudioStats 本地音频流统计信息回调
onRemoteAudioStats 远端音频流的统计信息回调
onLocalVideoStats 本地视频流统计信息回调
onRemoteVideoStats 远端视频流的统计信息回调
onNetworkQuality 所有用户的网络状态回调

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参考

方法 事件描述
addEngineMediaStatsObserver 添加 media 统计信息观测器
removeEngineMediaStatsObserver 删除 media 统计信息观测器
cleanupEngineMediaStatsObserver 清空 media 统计信息观测器
事件 事件描述
onRemoteAudioStats 通话中远端音频流的统计信息回调
onRtcStats 当前通话统计回调
onNetworkQuality 通话中每个用户的网络上下行质量报告回调
onLocalAudioStat 本地音频流统计信息回调
onLocalVideoStat 本地视频流统计信息回调
onRemoteVideoStats 通话中远端视频流的统计信息回调

Windows/macOS

实现方法

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

示例代码


class StatsObserver : IRtcMediaStatsObserver
{

};

StatsObserver *observer = nullptr;

rtc_engine_->setStatsObserver(observer);

API参考

API 功能描述
setStatsObserver 设置当前通话统计回调
事件 功能描述
onRtcStats 当前通话全局统计回调
onLocalAudioStats 本地音频流统计信息回调
onRemoteAudioStats 通话中远端音频流的统计信息回调
onLocalVideoStats 本地视频流统计信息回调
onRemoteVideoStats 通话中远端音频流的统计信息回调
onNetworkQuality 通话中每个用户的网络上下行质量报告回调

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 报告房间里所有成员的上下行网络质量。该回调每当发生变化的时候触发,返回的参数(数组格式),其中的元素包括:

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)
  })
})
质量打分数值 说明
0 网络质量未知
1 网络质量极好
2 用户主观感觉和极好差不多,但码率可能略低于极好
3 能沟通但不顺畅
4 网络质量差
5 完全无法沟通

SDK与服务器的连接状态

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

client.on('connection-state-change', evt => {
  console.log(evt.prevState, evt.curState);
})
类型 说明
DISCONNECTED 连接断开
CONNECTING 正在连接中
CONNECTED 已连接
DISCONNECTING 正在断开连接

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

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

client.on("exception", function(evt) {
  console.log(evt.code, evt.msg, evt.uid);
});
msg code 说明
FRAMERATE_SENT_TOO_LOW 1002 视频发送帧率过低
FRAMERATE_VIDEO_BITRATE_TOO_LOW 1003 视频发送码率过低
RECV_VIDEO_DECODE_FAILED 1005 接收视频解码失败
AUDIO_INPUT_LEVEL_TOO_LOW 2001 发送音量过低
AUDIO_OUTPUT_LEVEL_TOO_LOW 2002 接收音量过低
SEND_AUDIO_BITRATE_TOO_LOW 2003 音频发送码率过低
RECV_AUDIO_DECODE_FAILED 2005 接收音频解码失败

获取系统信息

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

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

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

获取网络相关数据

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

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 方法获取与当前会话相关的统计数据,包括:

本方法仅支持 Chrome 浏览器。

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

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

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

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

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 对应一组数据,包括:

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 对应一组数据,包括:

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 对应一组数据,包括:

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参考

方法 功能描述
getLocalAudioStats 获取本地发布流的音频统计数据
getLocalVideoStats 获取本地发布流的视频统计数据
getRemoteAudioStats 获取远端订阅流的音频统计数据
getRemoteVideoStats 获取远端订阅流的视频统计数据
getSessionStats 获取会话的连接状况统计数据