文档首页/ 实时音视频 SparkRTC/ 客户端SDK参考/ Web SDK/ 接口参考/ 客户端事件通知(ClientEvent)
更新时间:2024-09-13 GMT+08:00

客户端事件通知(ClientEvent)

本章节介绍了Web SDK的ClientEvent事件。

表1 ClientEvent事件

接口

描述

peer-join

远端用户进入房间事件。

peer-leave

远端用户退出房间事件。

stream-added

远端流添加事件。

stream-removed

远端流删除事件。

stream-updated

远端流更新事件。

stream-subscribed

远端流订阅成功事件。

client-banned

用户被踢,离开房间事件。

kick-room

解散房间

Error

客户端出现错误事件。

connection-state-changed

Client连接状态变更事件。

mute-audio

远端流禁用音频事件。

unmute-audio

远端流启用音频事件。

mute-video

远端流禁用视频事件。

unmute-video

远端流启用视频事件。

log-upload-result

日志上传结果事件。

signature-expired

签名过期事件。该事件为2.0.8版本新增。

camera-changed

摄像头设备变更事件。

recording-device-changed

录音设备变更事件。

playback-device-changed

播放设备变更事件。

network-quality

网络上下行质量报告事件。

stream-interrupted

远端流处于无码流状态事件。该事件为1.4.0版本新增。

stream-recovered

远端流码流恢复事件。该事件为1.4.0版本新增。

volume-indicator

音频TopN(即最大三方)模式下,当前音量最大的用户提示事件。该事件为1.5.0版本新增。

remote-user-name-changed

远端用户昵称变更事件。该事件为1.5.0版本新增。

live-streaming-updated

更新旁路推流的事件。该事件为2.0.0版本新增。

rtc-stats

音视频流数据统计事件。该事件为2.0.3版本新增。

事件注册监听应在业务结束时取消注册,否则注册监听事件累积会有内存泄漏风险。

peer-join

【事件说明】

远端用户加入房间事件,远端用户加入房间后会收到该事件通知。

【回调参数】

peerJoinEvent:必选,PeerJoin类型,用户信息。

PeerJoin定义为:{

  • userId:必选,string[64]类型,用户标识。
  • userName:可选,string[256]类型,用户昵称。

}

peer-leave

事件说明

远端用户离开房间事件,远端用户离开房间后会收到该事件通知。

【回调参数

peerLeaveEvent:必选,PeerLeaveInfo 类型,用户离开信息。

PeerLeaveInfo 定义为:{

  • userId:必选,string[64]类型,用户标识。
  • userName:可选,string[256]类型,用户昵称。
  • reason:可选,HRTCLeaveReason类型。

}

HRTCLeaveReason定义为:{

  • code:number类型, 离开原因枚举,取值如表2 离开房间原因所示。
  • msg:string类型,原因描述。
}
表2 离开房间原因

枚举值

描述

0

用户主动离开

1

服务器异常

2

sfu服务故障

3

服务不可达503

4

内部错误

5

被踢出房间

6

签名过期

7

重连超时

8

网络检测,UI不需要关注该错误码,不对外体现

9

用户移除

10

房间解散

stream-added

事件说明

远端流添加事件,当远端用户发流成功后会收到该事件通知。

【回调参数

stream:必选,RemoteStream类型,远端流对象。

stream-removed

事件说明

远端流移除事件,当远端用户取消发流或者原来已经发布的远端用户退出房间后会收到该事件通知。

【回调参数

stream:必选,RemoteStream类型,远端流对象。

stream-updated

事件说明

远端流更新事件,当远端用户的流发生变化,例如添加或者移除音视频轨,视频轨规格变化时会收到该事件通知。

【回调参数

stream:必选,RemoteStream类型,远端流对象。

stream-subscribed

事件说明

远端流订阅成功事件,当订阅远端流成功后会收到该事件通知。

【回调参数

stream:必选,RemoteStream类型,远端流对象。

client-banned

事件说明

用户被踢下线事件,当用户以相同的userId 在其他Client加入相同的房间后,被踢的Client会收到该事件通知。

【回调参数

clientBannedEvent:必选,ClientBanInfo类型,

ClientBanInfo定义为:{
  • userId:必选,string[64]类型,被踢用户标识。
  • reason:必选,string类型,原因描述。

}

kick-room

事件说明

解散房间,由调用的服务端接口触发。

【回调参数

roomId:必选,string[64]类型,房间Id。

Error

事件说明

客户端错误事件,当出现不可恢复的错误后,Client会上报该事件通知。

【回调参数

errorInfo:必选,ErrorInfo类型,错误信息。

ErrorInfo 定义为:{
  • errorCode:必选,string类型,错误码。
  • errorMsg:必选,string类型,错误描述。

}

connection-state-changed

事件说明

Client连接状态变更事件,Client连接状态变更会收到该事件通知。

【回调参数

  • ConnectionStateInfoEvent:{
    • prevState:必选,ConnectionState类型,变更前状态。
    • curState:必选,ConnectionState类型,变更后状态。

}

连接状态ConnectionState的取值如下所示:
  • CONNECTING:连接建立中。
  • CONNECTED:连接已连接。
  • RECONNECTING:重新连接中。
  • DISCONNECTED:连接已断开。

mute-audio

事件说明

远端用户禁用音频通知事件,当远端用户禁用音频后,流接收端会收到该事件通知。

【回调参数

mediaStatus:必选,MediaStatusNotifyInfo类型。

MediaStatusNotifyInfo包含如下属性:

  • roomId:必选,string[64]类型。
  • userId:必选,string[64]类型。
  • status:必选,MediaStatusAction类型。MediaStatusAction枚举值定义如下所示:
    • 1:媒资状态可用。
    • 2:媒资状态不可用。
  • reason:必选,MediaStatusReason类型。MediaStatusReason枚举值定义如下所示:
    • 0:媒体离线。
    • 1:媒体静音。
    • 2:媒体不静音。

unmute-audio

事件说明

远端用户启用音频通知事件,当远端用户启用音频后,流接收端会收到该事件通知。

【回调参数

mediaStatus:必选,MediaStatusNotifyInfo类型。

mute-video

事件说明

远端用户禁用视频通知事件,当远端用户禁用视频后,流接收端会收到该事件通知。

【回调参数

mediaStatus:必选,MediaStatusNotifyInfo类型。

unmute-video

事件说明

远端用户启用视频通知事件,当远端用户启用视频后,流接收端会收到该事件通知。

【回调参数

mediaStatus:必选,MediaStatusNotifyInfo类型。

log-upload-result

事件说明

日志上传结果事件。

【回调参数

status:必选,number类型,日志上传结果,200表示成功,其余表示失败。

signature-expired

事件说明

签名过期事件。

回调参数

errorInfo:错误信息。必选,ErrorInfo类型。

ErrorInfo 定义为:{
  • errorCode:错误码。必选,string类型。
  • errorMsg:必选,string类型。取值如下面的取值示例中所示。

}

取值示例,如下所示:

  • 签名过期:{

    errorCode: '90100030'

    errorMsg: 'signature expired'

    }

  • 签名无效:{

    errorCode: '90100031'

    errorMsg: 'signature invalid'

    }

监听到签名过期事件后可通过错误码区分是签名无效还是签名过期,签名过期后可通过renewSignature接口更新签名。

camera-changed

事件说明

本地摄像头设备变更事件,当插、拔本地摄像头时触发。

【回调参数

DeviceChangedEvent:必选,DeviceChangedInfo类型,设备变更详情。

DeviceChangedInfo 定义为:{
  • deviceId:必选,string类型,设备deviceId。
  • state:必选,DeviceChangeMode类型,DeviceChangeMode枚举值定义如下:
    • ADD:设备添加。
    • REMOVE:设备移除。

}

视频采集设备,拔插后需要应用层进行相应的处理,如:拔除摄像头的时候是否切换其他视频采集设备重新采集;插入摄像头的时候是否使用新插入设备进行重新采集。

recording-device-changed

事件说明

本地录音设备变更事件,当本地录音设备变更时触发。

【回调参数

DeviceChangedEvent:必选,DeviceChangedInfo类型,设备变更详情。DeviceChangedInfo定义参考camera-changed中的说明。

麦克风采集设备,拔插后需要应用层进行相应的处理,如:拔除麦克风的时候是否切换其他麦克风采集设备重新采集;插入麦克风的时候是否使用新插入设备进行重新采集。

playback-device-changed

事件说明

本地音频播放设备变更事件,当本地音频播放设备变更时触发。

【回调参数

DeviceChangedEvent:必选,DeviceChangedInfo类型,设备变更详情。DeviceChangedInfo定义参考camera-changed中的说明。

network-quality

事件说明

网络上下行质量报告事件,用户加入房间后,SDK在网络质量变化的时候会触发一次该事件,报告用户的本地网络上下行质量情况。

【回调参数

NetworkQualityEvent:必选, NetworkQualityInfo类型,网络上下行质量详情。

NetworkQualityInfo定义为:{
  • uplinkNetworkQuality:必选,number类型,上行网络质量。枚举值如下:
    • 0:质量未知。
    • 1:质量极好。
    • 2:质量较好。
    • 3:质量一般。
    • 4:质量差。
    • 5:质量极差。
    • 6:网络连接断开。
  • downlinkNetworkQuality:必选,number类型,下行网络质量。枚举值如下:
    • 0:质量未知。
    • 1:质量极好。
    • 2:质量较好。
    • 3:质量一般。
    • 4:质量差。
    • 5:质量极差。
    • 6:网络连接断开。

}

stream-interrupted

事件说明

远端流的码流中断事件。中断表示在 enableStreamStateDetection 接口参数 interval 设置的统计周期内未接收到有效视频帧。该事件为 1.4.0 版本新增。

【回调参数

streamInterruptedEvent:必选,UserList[]类型,已订阅且无视频码流的用户列表。

UserList定义为:{
  • userId:必选,string类型,用户Id。
  • isScreen:必选,boolean类型,true表示对应用户的辅流,false表示对应用户的主流。

}

stream-recovered

事件说明

远端流的码流恢复事件。

【回调参数

streamRecoveredEvent:必选,UserList[]类型,已订阅且视频码流恢复的用户列表。UserList参考stream-interrupted中的定义。该事件为1.4.0版本新增。

volume-indicator

事件说明

音频TopN模式下,房间中当前音量最大的用户提示事件。

【回调参数

userVolumeInfos:必选, UserVolumeInfo[]类型。

UserVolumeInfo定义为:{
  • user_id:必选,string类型,用户Id。
  • volume:可选,number类型,取值范围为[0,100]。

}

该事件仅在音频TopN模式下生效,1.5.0版本新增。

remote-user-name-changed

事件说明

远端用户昵称变更事件。该事件为1.5.0版本新增。

【回调参数

userNameChangedEvent:必选, UserNameInfo类型。

UserNameInfo定义为:{
  • roomId:必选,string[64]类型,房间Id。
  • userId:必选,string[64]类型,用户Id。
  • userName:必选, string[256]类型,修改后的用户昵称。

}

live-streaming-updated

事件说明

旁路推流状态更新事件。该事件为2.0.1版本新增。

回调参数

urlStatus:UrlStatus[]类型,所有CDN推流状态更新。UrlStatus定义如下:

  • url:必选,string类型,表示CDN推流URL
  • status:必选,number类型,表示当前推流状态。
    • 0:初始化。
    • 1:链接正常且有流。
    • 2:链接正常但无流。
    • 3:异常重试。
    • 4:处理失败。
  • errorCode:可选,number类型,表示详细的失败原因,支持的枚举值如下:
    • 0: 正常。
    • 1: 内部错误。
    • 2: 地址解析失败。
    • 3: 连接失败。
    • 4: RTMP握手失败。
    • 5: 内存错误。
    • 6: 参数错误。
    • 7: 重试失败。
    • 8: 响应超时失败。

rtc-stats

事件说明

音视频流数据统计事件。该事件为2.0.3版本新增。

【回调参数

rtcStatsInfo:必选, rtcStatsInfo[]类型。

rtcStatsInfo定义为:{
  • userName:必选,string类型,用户昵称。
  • isRemote:必选,boolean类型,是否为远端流,true表示远端流,false表示本地流。
  • streamType:必选,ContentType类型,流类型。ContentType类型的枚举值如下:{
    • main:string类型,表示主流。
    • middle1:string类型,表示主流,middle1~middle4码流依次降低。
    • middle2:string类型,表示主流,middle1~middle4码流依次降低。
    • middle3:string类型,表示主流,middle1~middle4码流依次降低。
    • middle4:string类型,表示主流,middle1~middle4码流依次降低。
    • slides:string类型,表示主流视频分辨率最小的流。
    • desktop:string类型,表示共享流。

      }

  • mediaType:必选,MediaType类型,媒体类型,音频或视频。
  • bitrate:必选,number类型,音视频流码率,单位为kbps。
  • frameRate:必选,number类型,视频帧率,单位为帧/秒。
  • rtt:必选,number类型,表示SDK到边缘服务器的RTT (Round-Trip Time),单位毫秒。只有本地流才有rtt 值。
  • jitter:必选,number类型,音视频流抖动值。
  • pktLossRate:必选,number类型,音视频流丢包率。

}