CloudHub 文档中心
下载中心 文档中心

RTC 实时音视频


CloudHubSDK Electron

频道事件

onConnectionStateChanged

网络连接状态已改变回调。

rtcEngine.on("onConnectionStateChanged",data=>{});
返回参数说明
state当前的网络连接状态,取值如下:
1:网络连接断开
2:建立网络连接中
3:网络已连接
4:重新建立网络连接中
5:网络连接失败

详情

该回调在网络连接状态发生改变的时候触发,并告知用户当前的网络连接状态。

onJoinChannel

加入频道成功。

rtcEngine.on("onJoinChannel",data=>{});
返回参数说明
channelId频道id
uid用户ID。 如果在joinChannel方法中指定了 uid,它会返回指定的 ID; 如果没有,它将返回由SDK自动分配的ID
elapsed消耗时间

详情

该回调方法表示该客户端成功加入了指定的频道。

onRejoinChannel

重新加入频道成功回调。

rtcEngine.on("onRejoinChannel",data=>{});
返回参数说明
channelId频道id
uid用户ID。 如果在 joinChannel 方法中指定了 uid,它会返回指定的 ID; 如果没有,它将返回由 SDK 自动分配的 ID

详情

有时候由于网络原因,客户端可能会和服务器失去连接,SDK 会进行自动重连,自动重连成功后触发此回调方法。

onLeaveChannel

离开频道回调。

rtcEngine.on("onLeaveChannel",data=>{});

详情

当用户调用 leaveChannel 离开频道后,SDK 会触发该回调。

onUserJoined

远端用户(通信场景)/主播(直播场景)加入当前频道回调。

rrtcEngine.on("onUserJoined",data=>{});
返回参数说明
uid加入频道的远端用户/主播 ID。如果在 JoinChannel 中指定了 uid,则此处返回该 ID;否则使用 SDK 自动分配的 ID
properties该用户的自定义属性。通过 JoinChannel 和 setProperty 接口可以指定用户自定义属性
isHistory该用户是否是在本地用户之前加入频道的
fromChannelId当有来⾃其他频道的跨频道媒体流转发到本频道时,本频道⽤户会收到 onUserJoined,此时 fromChannelId 为该转发媒体流源频道的频道号。

详情

该回调在如下情况下会被触发:

Note:

直播场景下,

onUserLeaved

远端用户(通信场景)/主播(直播场景)离开当前频道回调。

rtcEngine.on("onUserLeaved",data=>{});
返回参数说明
uid离开用户的id
reason用户离开的原因,有以下值:
1: 用户调用了 leaveChannel 主动离开频道
2: 因过长时间收不到对方数据包,超时掉线
3: 用户被踢出频道
4: 因为有相同的用户 id 进入频道而离开频道
5: 因为服务器主动关闭频道,踢出所有用户
6: 用户角色从主播切换为观众
0: 未知原因离开频道
8: 跨房间通道主动关闭
9: 跨房间通道连接断开

详情

提示有远端用户/主播离开了频道(或掉线)。用户离开频道有两个原因,即正常离开和超时掉线(超过30秒无法与服务器正常通信)。

onTokenPrivilegeWillExpire

token即将过期

rtcEngine.on("onTokenPrivilegeWillExpire",data=>{});

详情

收到该回调代表着 token 即将过期 需要重新生成 token 并调用 rtcEngine.renewToken 方法 传入新的 token

onRequestToken

token 已经过期,需要更新。

rtcEngine.on("onRequestToken",data=>{});

详情

在调用 joinChannel 时如果指定了 Token,由于 Token 具有一定的时效,在通话过程中如果 Token 已经失效,SDK 会立刻触发该回调,提醒应用程序更新 Token。 当收到该回调时,用户需要重新在服务端生成新的 Token,然后调用 renewToken 将新生成的 Token 传给 SDK。

onLocaluserPerssionChanged

用户收到此事件,返回 type(发布1/订阅2)和 hasPermission(有无权限0/1).

rtcEngine.on(onLocaluserPerssionChanged,data=>{});

Note:

onServerForceCloseChannel

频道被强制关闭

rtcEngine.on(onServerForceCloseChannel,data=>{});
返回参数说明
code频道关闭的原因,0:未知,1:因调用 ‘https://apidoc.roadofcloud.net/ChannelAPI/CloseChannel' 接口关闭的频道

音频事件

onLocalAudioStateChanged

本地音频状态改变回调。

rtcEngine.on("onLocalAudioStateChanged",data=>{});
返回参数说明
state新的本地音频状态,取值如下:
0 本地音频默认初始状态。
1 本地音频录制设备启动成功。
2 本地音频首帧编码成功。
3 本地音频启动失败。
error错误码,取值如下:
0 本地音频状态正常。
1 本地音频出错原因不明确。
2 没有权限启动本地音频录制设备。
3 本地音频录制设备已经在使用中。
4 本地音频录制失败,建议你检查录制设备是否正常工作。
5 本地音频编码失败。

详情

本地音频的状态发生改变时(包括本地麦克风录制状态和音频编码状态),SDK 会触发该回调报告当前的本地音频状态。在本地音频出现故障时,该回调可以帮助了解当前音频的状态以及出现故障的原因。

onFirstLocalAudioFrame

本地音频首帧回调。

rtcEngine.on("onFirstLocalAudioFrame",data=>{});

onRemoteAudioStateChanged

远端音频流状态已变化回调。

rtcEngine.on("onRemoteAudioStateChanged",data=>{});
返回参数说明
uid远端音频流的用户uid
state新的音频流状态,取值如下:
0: 远端音频流默认初始状态,在原因码 3、5 或 7 的情况下,会报告该状态。
1: 本地用户已接收远端音频首包。
2: 远端音频流正在解码,正常播放。在原因码 2、4 或 6 的情况下,会报告该状态。
3: 远端音频流卡顿。在原因码 1 的情况下,会报告该状态。
4: 远端音频流播放失败。在 原因码 0 的情况下,会报告该状态。
reason发生变化的原因,取值如下:
0: 内部原因。
1: 网络阻塞。
2: 网络恢复正常。
3: 本地用户停止接收远端音频流或本地用户禁用音频模块。
4: 本地用户恢复接收远端音频流或本地用户启用音频模块。
5: 远端用户停止发送音频流或远端用户禁用音频模块。
6: 用户恢复发送音频流或远端用户启用音频模块。
7: 远端用户离开频道。

详情

远端用户/主播音频状态发生改变时,SDK 会触发该回调向本地用户报告当前的远端音频流状态。

onFirstRemoteAudioFrame

已接收远端音频首帧回调。

rtcEngine.on("onFirstRemoteAudioFrame",data=>{});
返回参数说明
uid远端音频流的用户 uid

视频事件

onLocalVideoStateChanged

本地视频状态改变回调。

rtcEngine.on("onLocalVideoStateChanged",data=>{});
返回参数说明
state新的本地视频状态,取值如下:
0:本地视频默认初始状态
1:本地视频采集设备启动成功
2:本地视频首帧编码成功
3:本地视频启动失败
error错误码,取值如下:
1:出错原因不明确
2:没有权限启动本地视频采集设备
3:本地视频采集设备正在使用中
4:本地视频采集失败,建议检查采集设备是否正常工作
5:本地视频编码失败

详情

本地视频的状态发生改变时,SDK 会触发该回调报告当前的本地视频状态。在本地视频出现故障时,该回调可以帮助了解当前视频的状态以及出现故障的原因。

onFirstLocalVideoFrame

本地视频首帧回调。

rtcEngine.on("onFirstLocalVideoFrame",data=>{});
返回参数说明
width首帧视频的宽
height首帧视频的高

onRemoteVideoStateChanged

远端视频流状态已变化回调。

rtcEngine.on("onRemoteVideoStateChanged",data=>{});
返回参数说明
uid远端视频流的用户uid
mediaType流类型,取值如下:
1 音频
3 音视频
4 在线电影
5 离线电影
6桌面分享
state新的流状态,取值如下:
0 远端视频默认初始状态
1 本地用户已接收远端视频首包。
2 远端视频流卡顿。
3 远端视频流播放失败。
reason发生变化的原因,取值如下:
0 内部原因。
1 网络阻塞。
2 网络恢复正常。
3 本地用户停止接收远端视频流或本地用户禁用视频模块。
4 本地用户恢复接收远端视频流或本地用户启动视频模块。
5 远端用户停止发送视频流或远端用户禁用视频模块。
6 远端用户恢复发送视频流或远端用户启用视频模块。
7 远端用户离开频道。
8 远端视频流已回退为音频流。
9 回退的远端音频流恢复为视频流。
streamId这个流的唯一标识
streamInfotype: object, 这个流的自定义属性, 有以下key值:
sourceid: string 流的来源设备id
videofps: number 视频帧率
videoheight: number 视频高
videowidth: number 视频宽

详情

远端用户/主播视频状态发生改变时,SDK 会触发该回调向本地用户报告当前的远端视频流状态。每个用户可能有多个视频流,每路视频都有其类型(type)。

onFirstRemoteVideoFrame

已接收远端视频首帧回调。

rtcEngine.on("onFirstRemoteVideoFrame",data=>{});
返回参数说明
uid远端视频流的用户uid
mediaType视频流类型,参见 onRemoteVideoStateChanged
width首帧视频的宽
height首帧视频的高
streamId这个流的唯一标识

详情

本地收到远端第一个视频帧并解码成功后,会触发该回调。有两种情况:

数据统计事件

onRtcStats

当前通话统计。

rtcEngine.on("onRtcStats",data=>{});
返回参数说明
stats通话统计信息 具体内容如下:
duration:通话时长,单位为秒,累计值
txBytes:发送字节数(bytes),累计值
rxBytes:接收字节数(bytes),累计值
txKBitRate:发送码率(Kbps),瞬时值
rxKBitRate:接收码率(Kbps),瞬时值
rxAudioBytes:接收音频字节数(bytes),累计值
txAudioBytes:发送音频字节数(bytes),累计值
rxVideoBytes 接收视频字节数(bytes),累计值
txVideoBytes 发送视频字节数(bytes),累计值
rxAudioKBitRate 音频接收码率(Kbps),瞬时值
txAudioKBitRate 音频包的发送码率(Kbps),瞬时值
rxVideoKBitRate 视频接收码率(Kbps),瞬时值
txVideoKBitRate 视频发送码率(Kbps),瞬时值
lastmileDelay 客户端到边缘服务器的网络延迟(毫秒)
txPacketLossRate 使用抗丢包技术前,客户端到 CloudHub 边缘服务器的丢包率(%)
rxPacketLossRate 使用抗丢包技术前,CloudHub 边缘服务器到客户端的丢包率(%)
cpuTotalUsage 当前系统的 CPU 使用率 (%)。

onNetworkQuality

网络上下行质量报告回调。

rtcEngine.on("onNetworkQuality",data=>{});
返回参数说明
uid用户 uid
txQuality发送质量报告,取值如下:
0:质量未知
1:质量极好
2:主观感觉和极好差不多,但码率可能略低于极好
3:主观感受有瑕疵但不影响沟通
4:勉强能沟通但不顺畅
5:网络质量非常差,基本不能沟通
6:网络连接已断开,完全无法沟通
rxQuality接收质量报告,取值同上

onLocalVideoStats

本地视频流统计信息回调。

rtcEngine.on("onLocalVideoStats",data=>{});
返回参数说明
stats本地视频统计数据 具体内容如下
sourceId 摄像头id
sentBitrate (实际发送码率 (Kbps)。
sentFrameRate 实际发送帧率 (fps)。
targetBitrate 当前编码器的目标编码码率,单位为 Kbps,该码率为 SDK 根据当前网络状况预估的一个值
targetFrameRate 当前编码器的目标编码帧率,单位为 fps
encoderOutputFrameRate 本地编码器的输出帧率,单位为 fps
rendererOutputFrameRate 本地渲染器的输出帧率,单位为 fps
encodedBitrate 视频编码码率(Kbps)
encodedFrameWidth 视频编码宽度(px)
encodedFrameHeight 视频编码高度(px)
encodedFrameCount 视频发送的帧数,累计值
codecType 视频的编码类型 0 VP8 1 (默认)H.264

详情

该回调描述本地设备发送视频流的统计信息。SDK 每 2 秒触发该回调一次。

onRemoteVideoStats

通话中远端视频流的统计信息回调

rrtcEngine.on("onRemoteVideoStats",data=>{});
返回参数说明
stats远端视频统计数据 具体内容为下
uid 用户id
sourceId 摄像头id
mediaType 流类型
width 视频宽度 (像素)
height 视频高度 (像素)
receivedBitrate (上次统计后)接收到的码率 (Kbps)
decoderOutputFrameRate 远端视频解码器的输出帧率 (fps)
rendererOutputFrameRate 远端视频渲染器的输出帧率 (fps)
rxStreamType 视频流类型 0:大流 1:小流
totalFrozenTime 远端用户在加入频道后发生视频卡顿的累计时长 (ms)。
frozenRate 远端用户在加入频道后发生视频卡顿的累计时长占视频总有效时长的百分比 (%) 视频有效时长指远端用户加入频道后视频未被停止发送或禁用的时长。
packetLossRate 远端视频在使用抗丢包技术之前的丢包率(%)

详情

该回调描述远端用户在通话中端到端的视频流统计信息,针对每个远端用户/主播每 2 秒触发一次。
如果远端同时存在多个用户/主播,该回调每 2 秒会被触发多次。

onLocalAudioStats

本地音频流统计信息回调。

rtcEngine.on("onLocalAudioStats",data=>{});
返回参数说明
numChannels当前通话声道数(单声道或双声道)
sentSampleRate发送音频的采样率
sentBitrate发送音频的码率

详情

该回调描述本地设备发送音频流的统计信息。SDK 每 2 秒触发该回调一次。

onRemoteAudioStats

通话中远端音频流的统计信息回调

rrtcEngine.on("onRemoteAudioStats",data=>{});
参数描述备注
networkTransportDelay音频发送端到接收端的网络延迟。图中阶段 2 + 3 + 4
jitterBufferDelay接收端到网络抖动缓冲端的网络延迟。图中阶段 5
audioLossRate统计周期内,实际接收到的远端音频流丢帧率。1. 图中阶段 2 + 3 + 4 + 5
2. 一个统计周期内,音频丢帧率达到 4% 计为一次音频 卡顿
receivedSampleRate统计周期内,接收到的远端音频流的采样率。
receivedBitrate统计周期内,接收到的远端音频流的 平均 码率。
totalFrozenTime远端用户 / 主播在加入频道后发生音频 卡顿 的累计时长。1. CloudHub 定义 totalFrozenTime = 音频 卡顿 次数 × 2 × 1000 (毫秒)。
2. 累计时长是 自加入频道后 累计的时长。
frozenRate远端用户 / 主播音频卡顿累计时长占音频 总有效时长 的百分比。音频 总有效时长 指的是远端用户 / 主播加入频道后,既没有停止发送音频流,也没有禁用音频模块的通话时长。

媒体文件播放事件

onMovieProgress

本地用户的音乐文件播放进度回调。

rtcEngine.on("onMovieProgress",data=>{});
返回参数说明
mediaFile调用 startPlayMovie 时,传入的文件路径
pos播放进度(毫秒)
total文件总时长(毫秒)

onFirstLocalMovieFrame

本地媒体文件首帧回调。

rtcEngine.on("onFirstLocalMovieFrame",data=>{});
返回参数说明
uid用户uid
mediafile电影流类型
width首帧电影的宽
height首帧电影的高

localMovieStateChanged

本地媒体文件播放状态改变回调。

rtcEngine.on(localMovieStateChanged,data=>{});
返回参数说明
mediafile电影流文件路径
state新的流状态,取值如下:
0 本地电影默认初始状态
1 本地电影采集设备启动成功
2 本地电影首帧编码成功
3 本地电影启动失败
errCode错误码,取值如下:
0:本地电影状态正常
1:出错原因不明确
2:没有权限启动本地电影采集设备
3:本地电影采集设备正在使用中
4:本地电影采集失败,建议检查采集设备是否正常工作
5:本地电影编码失败

跨频道媒体流转发事件

onChannelMediaRelayStateChanged

本地媒体文件播放状态改变回调。

rtcEngine.on(onChannelMediaRelayStateChanged,(targetChannelId: string, state: number, code: number)=>{});
返回参数说明
targetChannelId目标频道id
state状态码,取值如下:
0 SDK 正在初始化
1 SDK 尝试跨频道
2 源频道主播成功加入目标频道
3 发生异常,详见code中错误码
code错误码,取值如下:
0 网络中断导致用户与服务器连接断开
1 用户与服务器建立连接
2 用户已加入源频道
3 用户已加入目标频道
4 SDK 开始向目标频道发送数据包
5 服务器收到了目标频道发送的视频流
6 服务器收到了目标频道发送的音频流
7 目标频道已更新
8 内部原因导致目标频道更新失败
9 目标频道未发生改变,即目标频道更新失败
10 目标频道名为 NULL
11 视频属性已发送至服务器

音量提示

onAudioVolumeIndication

说话者音量提示回调。

rtcEngine.on("onAudioVolumeIndication",data=>{});
返回参数说明
speakers音量数组 每一个对象代表一个用户
speakerNumber音量数量
totalVolume总音量值

详情

该回调报告频道内每个发布音频数据的用户的音量。

onActiveSpeaker

监测到远端最活跃用户回调

rtcEngine.on("onActiveSpeaker",data=>{});

参数

参数描述
uid远端最活跃用户的 ID

详情 成功调用 enableAudioVolumeIndication 后,SDK 会持续监测音量 最大的远端用户,并统计该用户被判断为音量最大者的次数。当前时间段内,该次数累积最多的远端用户为最活跃的用户。

当频道内用户数量大于或等于 2 且有活跃用户时,SDK 会触发该回调并报告最活跃用户的 uid。

通话前网络测试

onLastmileQuality

通话前网络上下行 last mile 质量报告回调。

rtcEngine.on("onLastmileQuality", data=>{});

详情

该回调描述本地用户在加入频道前的 last mile 网络探测的结果,其中 last mile 是指设备到边缘服务器的网络状态。
在调用 enableLastmileTest 之后,该回调函数每 2 秒触发一次。如果远端有多个用户/主播,该回调每 2 秒会被触发多次。

音频设备管理

onAudioDeviceStateChanged

音频设备状态变化

rtcEngine.on(onAudioDeviceStateChanged,data=>{});
返回参数说明
deviceId: string设备 ID
deviceType: number媒体设备类型:
-1:未知的设备类型
0:音频播放设备
1:音频录制设备
2:视频渲染设备
3:视频采集设备
4:应用的音频播放设备
deviceState: number设备状态
1:设备正在使用
2:设备被禁用
4:没有此设备
8:设备被拔出

视频设备管理

onVideoDeviceStateChanged

视频设备状态变化

rtcEngine.on(onVideoDeviceStateChanged,data=>{});
返回参数说明
deviceId: string设备 ID
deviceType: number媒体设备类型:
-1:未知的设备类型
0:音频播放设备
1:音频录制设备
2:视频渲染设备
3:视频采集设备
4:应用的音频播放设备
deviceState: number设备状态
1:设备正在使用
2:设备被禁用
4:没有此设备
8:设备被拔出

录制

onRecordMsg

录制状态发生改变。

rtcEngine.on("onRecordMsg",data=>{});
返回参数说明
currTs当前时间,毫秒
pauseDuration暂停总时长
recordDuration录制总时长
recordState0:停止录制
1:开始录制(正在录制)
2:暂停录制
startTs开始录制时间,毫秒

高级信令事件

onSetProperty

用户自定义属性变化回调。

rtcEngine.on("onSetProperty",data=>{});
返回参数说明
userId属性变化的用户uid
fromId发起操作的用户uid
properties发生变化的属性,json字符串

Note:

仅当本地用户在调用 setProperty 时指定的通知范围内(不指定即通知频道内所有人)时,本地用户才会收到该回调。

onChatMsg

聊天消息回调。

rtcEngine.on("onChatMsg",data=>{});
返回参数说明
fromId发起操作的用户uid
textMsg消息文本内容
extraData附加数据,可能为空

Note:

仅当本地用户在调用 sendChatMsg 时指定的通知范围内(不指定即通知频道内所有人)时,本地用户才会收到该回调。

onPubMsg

自定义消息发布回调。

rtcEngine.on("onPubMsg",data=>{});
返回参数说明
msgId消息id,是一条消息在频道内的唯一标识
msgName消息名称
fromId消息发送者的uid
toId通知的目标uid,如果为空通知频道内的所有人
data消息内容。必须是json字符串。可以为空
associatedUserId关联用户的uid,一旦一条消息和一个用户关联,则该用户退出时,此条消息自动被删除
associatedMsgId关联消息的id,一旦一条消息和另一条消息关联,则被关联的消息被删除时,此条消息自动被删除
ts服务器最后一次收到该消息时的时间戳
extraData保留参数
isHistory该消息是否是在本地用户进入频道前发送的
seq信令在服务器的顺序

Note:

仅当本地用户在调用 pubMsg 时指定的通知范围内(不指定即通知频道内所有人)时,本地用户才会收到该回调。

onDelMsg

自定义消息删除回调。

rrtcEngine.on("onDelMsg",data=>{});
返回参数说明
msgId消息id,是一条消息在频道内的唯一标识
msgName消息名称
fromId消息发送者的uid
toId通知的目标uid,如果为空通知频道内的所有人
data消息内容。必须是json字符串。可以为空
associatedUserId关联用户的uid,一旦一条消息和一个用户关联,则该用户退出时,此条消息自动被删除
associatedMsgId关联消息的id,一旦一条消息和另一条消息关联,则被关联的消息被删除时,此条消息自动被删除
ts服务器最后一次收到该消息时的时间戳
seq信令在服务器的顺序

Note:

仅当本地用户在调用 delMsg 时指定的通知范围内(不指定即通知频道内所有人)时,本地用户才会收到该回调。

onLocalUserEvicted

本地用户被踢出房间回调。

rtcEngine.on("onLocalUserEvicted",data=>{});
返回参数说明
reason被踢原因。由服务器填写,或调用 evictUser 时传入

详情

当收到该条回调时,可能有两种原因:

其他事件

onError

发生错误事件回调。

rtcEngine.on("onError",data=>{});

Note:

该回调发生表示SDK 运行时出现了(网络或媒体相关的)错误。通常情况下,SDK 上报的错误意味着 SDK 无法自动恢复,需要 App 干预或提示用户。

onServerTime

服务器当前时间通知。

rtcEngine.on(onServerTime,data=>{});
返回参数说明
serverTs服务器时间