腾讯云 RTC SDK - ClientEvent

客户端事件列表

通过 client.on('eventName') 监听指定的事件。您可以通过这些事件实现管理房间用户列表，以及管理用户的流状态，感知网络状态等功能，下面是事件的详细介绍。

注意：

事件需要在事件触发之前监听，这样才能收到相应的事件通知，因此建议在 client 进房前完成事件监听，这样才能确保不会漏掉事件通知。

Members

(static) STREAM_ADDED

Default Value:

'stream-added'

远端流添加事件，当远端的 client 调用 publish() 发布流后，您会收到该通知。通过该事件您可以订阅指定的远端流。完整订阅播放流程参考文档开始集成音视频通话。

Example

// 进房前监听事件才可以收到已在房间内的远端已发布流的事件
client.on('stream-added', event => {
  const remoteStream = event.stream;
});

(static) STREAM_REMOVED

Default Value:

'stream-removed'

远端流移除事件，当远端的 client 调用 unpublish() 取消发布流后，您会收到该通知。通过该事件您可以知道哪一个远端流被移除了。SDK 收到该通知时，会自动取消订阅，您不需要取消订阅。

Example

client.on('stream-removed', event => {
  const remoteStream = event.stream;
});

(static) STREAM_UPDATED

Default Value:

'stream-updated'

远端流更新事件，当远端的 client 添加、移除或更换音视频轨道后会收到该通知。通过该事件您可以知道远端流是否有音频、视频推送过来。

Example

client.on('stream-updated', event => {
  const remoteStream = event.stream;
});
// 例如远端新增了视频流，您可以从只订阅音频变成同时订阅音频和视频
client.on('stream-updated', event => {
  const remoteStream = event.stream;
  if(remoteStream.hasVideo()) {
     client.subscribe(remoteStream, { audio: true, video: true }).catch(error => {
       console.error('failed to subscribe remoteStream');
     });
  }
  // 4.15.7+ 版本支持拉取云端混流回推 TRTC 房间的流，mixUserList 是参与混流的 userList
  if (event.mixUserList) {
    console.log(event.mixUserList);
    // [{ userId, hasAudio, hasVideo, hasAuxiliary }]
  }
});

(static) STREAM_SUBSCRIBED

Default Value:

'stream-subscribed'

远端流订阅成功事件，调用 subscribe() 成功后会触发该事件。完整订阅播放流程参考文档开始集成音视频通话。

Example

client.on('stream-subscribed', event => {
  const remoteStream = event.stream;
});

(static) CONNECTION_STATE_CHANGED

Default Value:

'connection-state-changed'

SDK 和腾讯云的连接状态变更事件，您可以利用该事件从总体上监听 SDK 与腾讯云的连接状态。
若您需要细分监听每一条 Stream 的连接状态，可以监听 StreamEvent.CONNECTION_STATE_CHANGED 事件处理。

'DISCONNECTED'：连接断开
'CONNECTING'：正在连接中
'CONNECTED'：已连接
'RECONNECTING'：自动重连中

不同状态变更的含义：

DISCONNECTED -> CONNECTING: 正在尝试建立连接，调用进房接口时触发。
CONNECTING -> CONNECTED: 连接建立成功，调用进房接口， Websocket 连接成功时触发
CONNECTED -> DISCONNECTED: 连接中断，当网络异常导致连接断开时触发。
DISCONNECTED -> RECONNECTING: 正在重连，当连接异常断开时，SDK 尝试自动重连时触发。
RECONNECTING -> CONNECTED: SDK 自动重连成功。
RECONNECTING -> DISCONNECTED: SDK 自动重连失败。同时会抛出 client.on('error') 事件，错误码为 SIGNAL_CHANNEL_RECONNECTION_FAILED。

处理建议：可以监听该事件，在不同状态显示不同的 UI，提醒用户当前的连接状态。

Example

client.on('connection-state-changed', event => {
  const prevState = event.prevState;
  const curState = event.state;
});

(static) PEER_JOIN

Default Value:

'peer-join'

远端用户进房事件，通过该事件可以实现用户列表的新增操作。

注意：

live 模式下，不支持观众进退房事件
v4.8.2 之前版本，远端用户进房推流后，才会收到进房事件
v4.8.2 及其之后版本，远端用户进房，就能收到进房事件

Example

client.on('peer-join', event => {
  const userId = event.userId;
});

(static) PEER_LEAVE

Default Value:

'peer-leave'

远端用户退房事件，通过该事件可以实现用户列表的删除操作。

注意：

live 模式下，不支持观众进退房事件
v4.8.2 之前版本，当远端用户取消推流或退房时，都会收到退房事件
v4.8.2 及其之后版本，只有远端用户退房时，才会收到退房事件

Example

client.on('peer-leave', event => {
  const userId = event.userId;
});

(static) MUTE_AUDIO

Default Value:

'mute-audio'

远端用户禁用音频事件，通过该事件可以实现用的音频状态管理，例如显示开关麦的图标。

Example

client.on('mute-audio', event => {
  const userId = event.userId;
});

(static) MUTE_VIDEO

Default Value:

'mute-video'

远端用户禁用视频事件。

Example

client.on('mute-video', event => {
  const userId = event.userId;
});

(static) UNMUTE_AUDIO

Default Value:

'unmute-audio'

远端用户启用音频事件。

Example

client.on('unmute-audio', event => {
  const userId = event.userId;
});

(static) UNMUTE_VIDEO

Default Value:

'unmute-video'

远端用户启用视频通知。

Example

client.on('unmute-video', event => {
  const userId = event.userId;
});

(static) CLIENT_BANNED

Default Value:

'client-banned'

被动退出房间事件。从 v4.14.0 版本开始，事件回调返回退房原因（reason）和对应的原因描述（message），reason 枚举值及含义如下：

值	含义
kick	相同 userId 的用户进入同一个房间导致互踢。后进入的用户把先进入房间的用户踢出；或者先推流的用户把未推流的用户踢出。
banned	系统管理员通过服务端 API 将该用户踢出房间
room_disband	系统管理员通过服务端 API 解散房间

注意：

同 userId 用户同时登录同一房间是不允许的行为，可能会导致双方音视频通话异常，业务侧应避免出现这种情况。
live 模式下，只有主播用户才会有 kick 互踢。观众角色不会互踢。

Example

// v4.14.0 及其之后的版本
client.on('client-banned', event => {
  console.log(`reason: ${event.reason}, message: ${event.message}`);
  // 根据对应的 reason 提示用户
});
// v4.14.0 之前的版本
client.on('client-banned', error => {
  console.error('client-banned observed: ' + error);
  // 提示退房
});

(static) NETWORK_QUALITY

Since:

v4.6.0

Default Value:

'network-quality'

网络质量统计数据事件，进房后开始统计，每两秒触发一次，该数据反映的是您本地的上、下行的网络质量。

上行网络质量（uplinkNetworkQuality）指的是您上传本地流的网络情况（SDK 到腾讯云的上行连接网络质量）

下行网络质量（downlinkNetworkQuality）指的是您下载所有流的平均网络情况（腾讯云到 SDK 的所有下行连接的平均网络质量）

其枚举值及含义如下表所示：

数值	含义
0	网络状况未知，表示当前 client 实例还没有建立上行/下行连接
1	网络状况极佳
2	网络状况较好
3	网络状况一般
4	网络状况差
5	网络状况极差
6	网络连接已断开注意：若下行网络质量为此值，则表示所有下行连接都断开了

自 v4.10.3 版本开始，支持获取上、下行的 RTT 及丢包率

uplinkRTT，uplinkLoss 为上行 RTT(ms) 及上行丢包率。
downlinkRTT，downlinkLoss 为所有下行连接的平均 RTT(ms) 及平均丢包率。

Note

如果您想知道对方的上下行网络情况，需要把对方的网络质量情况通过 IM 广播出去。

Example

client.on('network-quality', event => {
   console.log(`network-quality, uplinkNetworkQuality:${event.uplinkNetworkQuality}, downlinkNetworkQuality: ${event.downlinkNetworkQuality}`)
   // 自 v4.10.3 支持获取上、下行的 RTT 及丢包率
   console.log(`uplink rtt:${event.uplinkRTT} loss:${event.uplinkLoss}`)
   console.log(`downlink rtt:${event.downlinkRTT} loss:${event.downlinkLoss}`)
})

(static) AUDIO_VOLUME

Since:

v4.9.0

Default Value:

'audio-volume'

音量大小事件
调用 enableAudioVolumeEvaluation 接口开启音量大小回调后，SDK 会定时抛出该事件，通知每个 userId 的音量大小。
Note

回调中包含推流的本地流及已订阅的远端流的音量大小，无论是否有人说话，都会触发该回调。
audioVolume 取值为0-100的正整数，通常认为 audioVolume > 10 的用户正在说话

Example

client.on('audio-volume', event => {
    event.result.forEach(({ userId, audioVolume, stream }) => {
        if (audioVolume > 10) {
           console.log(`user: ${userId} is speaking, audioVolume: ${audioVolume}`);
        }
    })
})
// 开启音量回调，并设置每 1000ms 触发一次事件
client.enableAudioVolumeEvaluation(1000);

(static) SEI_MESSAGE

Since:

v4.14.1

Default Value:

'sei-message'

收到 SEI message

Example

client.on('sei-message', event => {
   console.log(`收到 ${event.userId} 的 sei message: ${event.data}`)
   // 从 4.15.11+ 支持
   console.log(`是否是从辅流接收到的 SEI：${event.isFromAuxiliary}`)
})

(static) ERROR

Default Value:

'error'

错误事件，当出现不可恢复错误后，会抛出此事件

Example

client.on('error', error => {
  console.error('client error observed: ' + error);
  const errorCode = error.getCode();
  // 请根据错误码列表(https://cloud.tencent.com/document/product/647/34342)查看错误类型。
  // 当出现客户端错误后，请调用 Client.leave() 退房并尝试通过 Client.join() 重新进房恢复通话。
});
stream.on('error', error => {
  const errorCode = error.getCode();
  if (errorCode === 0x4043) {
    // 自动播放受限，引导用户手势操作并调用 stream.resume 恢复音视频播放
    // 参考：https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/module-ErrorCode.html#.PLAY_NOT_ALLOWED
  } else if (errorCode === 0x4044) {
    // 媒体设备被拔出后自动恢复失败，参考：https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/module-ErrorCode.html#.DEVICE_AUTO_RECOVER_FAILED
  }
});