状态回调
简介
实时音视频通话对网络环境非常敏感,让用户清晰地了解网络和音视频状态,对于用户体验是非常重要的。
Pano SDK 支持回调当前网络状态、连接情况和音视频收发状态,开发者可用于做相应界面展示。
- 网络状态回调是基于音视频数据的发送情况来展示的,如果某位用户没有发送音视频,就不会回调其网络状态;音视频收发状态回调同理。
- 网络状态每 2 秒回调一次,音视频收发状态每 1 秒回调一次。
- 丢包率的取值范围是[0, 1],例如:0.0123 = 1.23%。
具体内容,请查看下列介绍。
网络状态质量回调
Windows (C++)
请参考 注册通知,实现 onNetworkQuality(uint64_t userId, QualityRating quality)
回调方法来接收网络状态质量通知,QualityRating
表示 userId
对应用户的网络状态质量。
macOS/iOS (Objective-C)
实现 PanoRtcEngineDelegate
协议的 - onNetworkQuality:withUser:
回调方法来接收网络状态质量通知,PanoQualityRating
表示 userId
对应用户的网络状态质量。
Android (Java)
实现 RtcEngineCallback
接口的 onNetworkQuality(long userId, Constants.QualityRating quality)
回调方法来接收网络状态质量通知,QualityRating
表示 userId
对应用户的网络状态质量。
Web
通过 RtcEngine
对象的 networkStatus
回调方法来接收网络状态质量通知。
示例代码:
rtcEngine.on(PanoRtc.RtcEngine.Events.networkStatus, data => {
console.log('networkStatus:', data)
// {event: 'network_status', networkRatings: [
// {userId: '10000', rating: 'Excellent'},
// {userId: '12345', rating: 'Excellent'}
// ]}
})
Electron
通过 RtcEngine
对象的 'networkQuality'
回调方法来接收网络状态质量通知。
示例代码:
rtcEngine.on('networkQuality', (userId, quality) => {
// quality 表示 userId 对应用户的网络状态质量
// 0: Unavailable 不可用
// 1: VeryBad 非常差(几乎不可用)
// 2: Bad 比较差(不稳定)
// 3: Poor 一般
// 4: Good 很好
// 5: Excellent 非常好
console.log(`onNetworkQuality: userId - ${userId}, quality - ${quality}`);
// onNetworkQuality: userId - 10000, quality - 5
})
Flutter
请参考 注册通知,通过 onNetworkQuality
回调来接收网络状态质量通知,quality
表示 userId
对应用户的网络状态质量。
示例代码:
engineKit.setEventHandler(
RtcEngineEventHandler(onNetworkQuality: (userId, quality) {
print("EventHandler onNetworkQuality: userId - $userId, quality - $quality");
// EventHandler onNetworkQuality, userId - 10000, quality - QualityRating.Excellent
})
);
React Native
请参考 注册通知,通过 onNetworkQuality
回调来接收网络状态质量通知,quality
表示 userId
对应用户的网络状态质量。
示例代码:
engine?.addListener('onNetworkQuality', (userId, quality) => {
console.log(`onNetworkQuality, userId - ${userId}, quality - ${quality}`);
// onNetworkQuality, userId - 10000, quality - 5
});
音视频收发状态回调
Windows (C++)
通过 RtcEngine::setMediaStatsObserver(MediaStatsObserver * observer)
方法设置观察者,MediaStatsObserver
包含多个类型的回调,例如:
onVideoSendStats (VideoSendStats &stats)
回调发送视频的统计,包括视频流标识、视频宽度、视频高度、发送帧率、发送比特率,等。onVideoRecvStats (VideoRecvStats &stats)
回调接收视频的统计,包括用户标识、视频流标识、视频宽度、视频高度、接收帧率、接收比特率,等。onAudioSendStats (AudioSendStats &stats)
回调发送音频的统计,包括发送比特率、音频输入强度级别、麦克风采集检测,等。onAudioRecvStats (AudioRecvStats &stats)
回调接收音频的统计,包括用户标识、接收比特率、音频输出强度级别,等。onScreenSendStats (ScreenSendStats &stats)
回调发送屏幕共享的统计,和发送视频的统计类似。onScreenRecvStats (ScreenRecvStats &stats)
回调接收屏幕共享的统计,和接收视频的统计类似。- 其他类型,请查看 SDK API 文档。
macOS/iOS (Objective-C)
实现 PanoRtcEngineDelegate
协议的以下回调来接收音视频状态:
- onVideoSendStats:
回调发送视频的统计,包括视频流标识、视频宽度、视频高度、发送帧率、发送比特率,等。- onVideoRecvStats:
回调接收视频的统计,包括用户标识、视频流标识、视频宽度、视频高度、接收帧率、接收比特率,等。- onAudioSendStats:
回调发送音频的统计,包括发送比特率、音频输入强度级别、麦克风采集检测,等。- onAudioRecvStats:
回调接收音频的统计,包括用户标识、接收比特率、音频输出强度级别,等。- onScreenSendStats:
回调发送屏幕共享的统计,和发送视频的统计类似。- onScreenRecvStats:
回调接收屏幕共享的统计,和接收视频的统计类似。
Android (Java)
通过 RtcEngine
对象的 setMediaStatsObserver(RtcMediaStatsObserver observer)
方法设置观察者,RtcMediaStatsObserver
包含多个类型的回调,例如:
onVideoSendStats(RtcVideoSendStats stats)
回调发送视频的统计,包括视频流标识、视频宽度、视频高度、发送帧率、发送比特率,等。onVideoRecvStats(RtcVideoRecvStats stats)
回调接收视频的统计,包括用户标识、视频流标识、视频宽度、视频高度、接收帧率、接收比特率,等。onAudioSendStats(RtcAudioSendStats stats)
回调发送音频的统计,包括发送比特率、音频输入强度级别、麦克风采集检测,等。onAudioRecvStats(RtcAudioRecvStats stats)
回调接收音频的统计,包括用户标识、接收比特率、音频输出强度级别,等。onScreenSendStats(RtcVideoSendStats stats)
回调发送屏幕共享的统计,和发送视频的统计类似。onScreenRecvStats(RtcVideoRecvStats stats)
回调接收屏幕共享的统计,和接收视频的统计类似。- 其他回调类型,请查看 SDK API 文档。
Web
Web SDK 暂未提供音视频收发状态相关回调。
Electron
通过 RtcEngine
对象的 setMediaStatsObserver(observer)
方法设置观察者,来接收音视频收发状态回调(每秒回调一次)。
observer
为 JS 函数,格式为 stats => { ... }
,详见下面示例代码。
observer
传入 null
,则取消回调。
示例代码:
rtcEngine.setMediaStatsObserver(stats => {
console.log('MediaStatsObserver: ', stats);
})
rtcEngine.setMediaStatsObserver(null); // 取消回调
/*
stats 内容示例:
{
localStats: { // localStats 表示自己的发送
audioStats: { // 调用 startAudio 方法后才有音频发送
active: true,
bitrate: 42072, // 音频发送比特率
bytes: 297366, // 音频发送字节数(累计)
codec: 5, // 音频编码器类型: 0 - Unknown,1 - G711,2 - G722,3 - ILBC,4 - ISAC,5 - OPUS
level: 21274, // 音频输入强度级别。取值范围:[0, 32767]
loss: 0, // 音频发送丢包率
losscnt: 0, // 音频发送丢包数
rtt: 12 // 音频往返时延
},
videoStats: [ // 调用 startVideo 方法后才有视频发送
{
bitrate: 1784104, // 视频发送比特率
bytes: 12958231, // 视频发送字节数(累计)
codec: 1, // 视频编码器类型:0 - Unknown,1 - H264,2 - AV1
fps: 30, // 视频发送帧率
height: 720, // 视频视频发送分辨率的高度值
loss: 0, // 视频发送丢包率
losscnt: 0, // 视频发送丢包数
pli: 2, // 视频发送期间接收到的PLI包数(PLI: Picture Loss Indication)
// PLI 又称为"关键帧请求":关键帧丢失无法解码时,请求发送方重新生成并发送一个关键帧
rtt: 12, // 视频往返时延
streamId: 0, // 视频流标识
width: 1280 // 视频发送分辨率的宽度值
},
...
],
bweStats: {
bandwidth: 10514286, // 发送的评估带宽(比特)
encBitrate: 1787320, // 发送的编码比特率
rtxBitrate: 0, // 发送的重传比特率
txBitrate: 1785176 // 发送的传输比特率
}
},
remoteStats: {
// remoteStats 表示自己的接收,需要有其他用户发送,自己才会有接收
// remoteStats 的 audioStats 和 videoStats 都是数组,字段和 localStats 中的相同
},
systemStats: {
cpuUsage: 26, // 总CPU负载(百分比)
totalMem: 16472892, // 总物理内存(KB)
procMem: 248052, // 当前进程使用内存(KB)
memUsage: 56 // 总内存负载(百分比)
}
}
*/
Flutter
请参考 注册通知,通过 RtcEngineEventHandler 的下列回调来接收音视频状态:
onVideoSendStats
回调发送视频的统计,包括视频流标识、视频宽度、视频高度、发送帧率、发送比特率,等。onVideoRecvStats
回调接收视频的统计,包括用户标识、视频流标识、视频宽度、视频高度、接收帧率、接收比特率,等。onAudioSendStats
回调发送音频的统计,包括发送比特率、音频输入强度级别、麦克风采集检测,等。onAudioRecvStats
回调接收音频的统计,包括用户标识、接收比特率、音频输出强度级别,等。onScreenSendStats
回调发送屏幕共享的统计,和发送视频的统计类似。onScreenRecvStats
回调接收屏幕共享的统计,和接收视频的统计类似。- 其他回调类型,请查看 SDK API 文档。
示例代码:
engineKit.setEventHandler(
RtcEngineEventHandler(
onVideoSendStats: (stats) {
print("EventHandler - onVideoSendStats");
}, onVideoRecvStats: (stats) {
print("EventHandler - onVideoRecvStats");
}, onAudioSendStats: (stats) {
print("EventHandler - onAudioSendStats");
}, onAudioRecvStats: (stats) {
print("EventHandler - onAudioRecvStats");
}, onScreenSendStats: (stats) {
print("EventHandler - onScreenSendStats");
}, onScreenRecvStats: (stats) {
print("EventHandler - onScreenRecvStats");
}
)
);
React Native
请参考 注册通知,通过 RtcEngineEventHandler
的下列回调来接收音视频状态:
onVideoSendStats
回调发送视频的统计,包括视频流标识、视频宽度、视频高度、发送帧率、发送比特率,等。onVideoRecvStats
回调接收视频的统计,包括用户标识、视频流标识、视频宽度、视频高度、接收帧率、接收比特率,等。onAudioSendStats
回调发送音频的统计,包括发送比特率、音频输入强度级别、麦克风采集检测,等。onAudioRecvStats
回调接收音频的统计,包括用户标识、接收比特率、音频输出强度级别,等。onScreenSendStats
回调发送屏幕共享的统计,和发送视频的统计类似。onScreenRecvStats
回调接收屏幕共享的统计,和接收视频的统计类似。
示例代码:
engine?.addListener('onVideoSendStats', (stats) => {
console.log(`onVideoSendStats, stats:`, stats);
});
engine?.addListener('onVideoRecvStats', (stats) => {
console.log(`onVideoRecvStats, stats:`, stats);
});
engine?.addListener('onAudioSendStats', (stats) => {
console.log(`onAudioSendStats, stats:`, stats);
});
engine?.addListener('onAudioRecvStats', (stats) => {
console.log(`onAudioRecvStats, stats:`, stats);
});
engine?.addListener('onScreenSendStats', (stats) => {
console.log(`onScreenSendStats, stats:`, stats);
});
engine?.addListener('onScreenRecvStats', (stats) => {
console.log(`onScreenRecvStats, stats:`, stats);
});
断开和重连回调
开发者需要在界面上展示断开和重连提示,以便用户清晰地了解异常状态。
- 例如,连接中断后,尝试重连期间,将无法收发音视频,自己会看不到听不到其他用户,其他用户也看不到听不到自己,如果不提示用户的话,用户将产生困惑。
- 再如,重连失败后,SDK 会自动离开频道,应用需退出音视频界面,提示用户检查或更换网络。
Windows (C++)
请参考 注册通知,实现 onChannelFailover
和 onChannelLeaveIndication
回调方法。
onChannelFailover(FailoverState state)
回调接收网络断开和重连通知,FailoverState
状态包含:Reconnecting
: 和服务器的连接中断,正在尝试自动重连Success
: 重连成功Failed
: 此状态已弃用,重连失败会触发onChannelLeaveIndication
回调
onChannelLeaveIndication(QResult result)
回调接收离开频道通知,当result
为NETWORK_ERROR
时,表示和服务器的连接彻底断开,自动离开频道。
macOS/iOS (Objective-C)
实现 PanoRtcEngineDelegate
协议的 - onChannelFailover:
和 - onChannelLeaveIndication:
回调方法。
- onChannelFailover:
回调接收网络断开和重连通知,PanoFailoverState
状态包含:kPanoFailoverReconnecting
: 和服务器的连接中断,正在尝试自动重连kPanoFailoverSuccess
: 重连成功kPanoFailoverFailed
: 此状态已弃用,重连失败会触发- onChannelLeaveIndication:
回调
- onChannelLeaveIndication:
回调接收离开频道通知,当result
为kPanoResultNetworkError
时,表示和服务器的连接彻底断开,自动离开频道。
Android (Java)
实现 RtcEngineCallback
接口的 onChannelFailover
和 onChannelLeaveIndication
回调方法。
onChannelFailover(FailoverState state)
回调接收网络断开和重连通知,FailoverState
状态包含:Reconnecting
: 和服务器的连接中断,正在尝试自动重连Success
: 重连成功Failed
: 此状态已弃用,重连失败会触发onChannelLeaveIndication
回调
onChannelLeaveIndication(QResult result)
回调接收离开频道通知,当result
为NetworkError
时,表示和服务器的连接彻底断开,自动离开频道。
Web
请参考 注册通知,通过 RtcEngine
实例的 on
方法注册 channelFailover
和 leaveChannelIndication
回调。
示例代码:
rtcEngine.on(PanoRtc.RtcEngine.Events.channelFailover, data => {
console.log('channelFailover, data: ', data)
/* 返回信息如下:
- state: "Reconnecting" 和服务器的连接中断,正在尝试自动重连:
{event: "channel_fail_over", state: "Reconnecting", msg: "Connection lost, now reconnecting"}
- state: "Success" 重连成功:
{event: "channel_fail_over", state: "Success", msg: "Channel rejoin success."}
- state: "Failed" 重连失败:
{event: "channel_fail_over", state: "Failed", msg: "Rejoin channel failed!"}
*/
})
rtcEngine.on(PanoRtc.RtcEngine.Events.leaveChannelIndication, data => {
console.log('leaveChannelIndication, data: ', data)
// 重连失败会触发 leaveChannelIndication 回调
// {event: 'leave_channel_indication', reason: 'Rejoin channel failed!', reasonCode: 5}
})
Electron
请参考 注册通知,通过 RtcEngine
实例的 on
方法注册 channelFailover
和 leaveChannelIndication
回调。
示例代码:
rtcEngine.on('channelFailover', state => {
console.log('channelFailover, state: ', state)
/* state 取值和含义
0: 和服务器的连接中断,正在尝试自动重连
1: 重连成功
*/
})
rtcEngine.on('channelLeaveIndication', result => {
// 重连失败会触发 channelLeaveIndication 回调,result 为 -301 表示 NETWORK_ERROR
console.log('channelLeaveIndication, result: ', result)
})
Flutter
请参考 注册通知,通过 onChannelFailover
回调来接收网络断开和重连通知。
FailoverState
状态包含:
Reconnecting
: 和服务器的连接中断,正在尝试自动重连Success
: 重连成功Failed
: 此状态已弃用,重连失败会触发onChannelLeaveIndication
回调
通过 onChannelLeaveIndication
回调接收离开频道通知,当 ResultCode
为 NetworkError
时,表示和服务器的连接彻底断开,自动离开频道。
示例代码:
engineKit.setEventHandler(
RtcEngineEventHandler(
onChannelFailover: (FailoverState state) {
print("EventHandler onChannelFailover, state: $state");
// EventHandler onChannelFailover, state: FailoverState.Reconnecting
// EventHandler onChannelFailover, state: FailoverState.Success
}, onChannelLeaveIndication: (ResultCode result) {
print("EventHandler onChannelLeaveIndication, result: $result");
// EventHandler onChannelLeaveIndication, result: ResultCode.NetworkError
}
)
);
React Native
请参考 注册通知,通过 onChannelFailover
回调来接收网络断开和重连通知。
FailoverState
状态包含:
Reconnecting
: 和服务器的连接中断,正在尝试自动重连Success
: 重连成功Failed
: 此状态已弃用,重连失败会触发onChannelLeaveIndication
回调
通过 onChannelLeaveIndication
回调接收离开频道通知,当 ResultCode
为 NetworkError
时,表示和服务器的连接彻底断开,自动离开频道。
示例代码:
this._engine?.addListener('onChannelFailover', (state) => {
console.log(`onChannelFailover, state:`, state);
// onChannelFailover, state: 0
// onChannelFailover, state: 1
});
this._engine?.addListener('onChannelLeaveIndication ', (result) => {
console.log(`onChannelLeaveIndication , result:`, result);
// onChannelLeaveIndication -301
});