EVENT

// 使用方式：
trtc.on(TRTC.EVENT.ERROR, () => {});

错误事件，非 API 调用错误，SDK 在运行过程中出现了不可恢复的错误时抛出。

• 错误码(error.code)为：ErrorCode.OPERATION_FAILED
• 可能的扩展错误码(error.extraCode)：5501, 5502

trtc.on(TRTC.EVENT.ERROR, error => {
  console.error('trtc error observed: ' + error);
  const errorCode = error.code;
  const extraCode = error.extraCode;
});

自动播放失败，参考 自动播放处理建议

trtc.on(TRTC.EVENT.AUTOPLAY_FAILED, event => {
  // 引导用户点击页面，当用户点击页面时，SDK 会自动恢复播放。
  // 自 v5.1.3+ 新增 userId 参数，表示哪个用户出现自动播放失败。
  console.log(event.userId);
});

被踢出房间，原因如下：

• kick: 相同 userId 的用户同时进入同一个房间（以下简称为同名进房），先进入房间的用户会被后进入的用户踢出房间。
  
  • 同名进房是不允许的行为，可能会导致双方音视频通话异常，业务侧应避免出现这种情况。
  • TRTC 后台不保证观众角色同名进房互踢。即观众角色的用户，使用同 userId 进同一个房间，可能不会收到该事件。
• banned: 系统管理员通过服务端 API 将该用户踢出房间。
• room-disband: 系统管理员通过服务端 API 解散房间。

trtc.on(TRTC.EVENT.KICKED_OUT, event => {
  console.log(event.reason)
});

远端用户进房事件。

• live 模式下，只有主播才有进退房通知，观众没有进退房通知，观众可以收到主播的进退房通知。

trtc.on(TRTC.EVENT.REMOTE_USER_ENTER, event => {
  const userId = event.userId;
});

远端用户退房事件。

• live 模式下，只有主播才有进退房通知，观众没有进退房通知，观众可以收到主播的进退房通知。

trtc.on(TRTC.EVENT.REMOTE_USER_EXIT, event => {
  const userId = event.userId;
});

远端用户发布了音频。当远端用户打开麦克风后，您会收到该通知。参考：开关摄像头、麦克风

• 默认情况下，SDK 会自动播放远端音频，您无需调用 API 来播放远端音频。可以监听该事件及 REMOTE_AUDIO_UNAVAILABLE 来更新“远端是否开启麦克风”的 UI icon。
• 需要注意的是：如果用户在进房前没有与页面产生过交互，自动播放音频可能会因为【浏览器的自动播放策略限制】而失败，您需参考自动播放受限处理建议进行处理。
• 若您不希望 SDK 自动播放音频，您可以在 trtc.enterRoom() 时设置 autoReceiveAudio 为 false 关闭自动播放音频。
• 监听 TRTC.EVENT.REMOTE_AUDIO_AVAILABLE 事件，记录有远端音频的 userId，在需要播放音频时，调用 trtc.muteRemoteAudio(userId, false) 方法。

// 在进房前监听
trtc.on(TRTC.EVENT.REMOTE_AUDIO_AVAILABLE, event => {
  const userId = event.userId;
});

远端停止发布了音频。当远端用户关闭麦克风后，您会收到该通知。

// 在进房前监听
trtc.on(TRTC.EVENT.REMOTE_AUDIO_UNAVAILABLE, event => {
  const userId = event.userId;
});

远端用户发布了视频，当远端用户开启摄像头后，您会收到该通知。参考：开关摄像头、麦克风

• 可以监听该事件及 REMOTE_VIDEO_UNAVAILABLE 来更新“远端是否开启摄像头”的 UI icon。

// 在进房前监听
trtc.on(TRTC.EVENT.REMOTE_VIDEO_AVAILABLE, event => {
  const userId = event.userId;
  const streamType = event.streamType;
  trtc.startRemoteVideo({userId, streamType, view});
});

远端用户停止发布视频，当远端用户关闭摄像头后，您会收到该通知。

// 在进房前监听
trtc.on(TRTC.EVENT.REMOTE_VIDEO_UNAVAILABLE, event => {
  const userId = event.userId;
  const streamType = event.streamType;
  // 此时 SDK 会自动停止播放，无需调用 stopRemoteVideo。
});

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

• 回调中包含本地麦克风音量及远端用户的音量，无论是否有人说话，都会触发该回调。
• 回调 event.result 会根据音量大小，按大到小进行排序。
• 当 userId 为空串时，代表本地麦克风音量。
• volume 取值为0-100的正整数

trtc.on(TRTC.EVENT.AUDIO_VOLUME, event => {
   event.result.forEach(({ userId, volume }) => {
       const isMe = userId === ''; // 当 userId 为空串时，代表本地麦克风音量。
       if (isMe) {
           console.log(`my volume: ${volume}`);
       } else {
           console.log(`user: ${userId} volume: ${volume}`);
       }
   })
});
// 开启音量回调，并设置每 1000ms 触发一次事件
trtc.enableAudioVolumeEvaluation(1000);

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

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

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

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

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

• uplinkRTT，uplinkLoss 为上行 RTT(ms) 及上行丢包率。

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

Note

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

trtc.on(TRTC.EVENT.NETWORK_QUALITY, event => {
   console.log(`network-quality, uplinkNetworkQuality:${event.uplinkNetworkQuality}, downlinkNetworkQuality: ${event.downlinkNetworkQuality}`)
   console.log(`uplink rtt:${event.uplinkRTT} loss:${event.uplinkLoss}`)
   console.log(`downlink rtt:${event.downlinkRTT} loss:${event.downlinkLoss}`)
})

SDK 和腾讯云的连接状态变更事件，您可以利用该事件从总体上监听 SDK 与腾讯云的连接状态。

• 'DISCONNECTED'：连接断开
• 'CONNECTING'：正在连接中
• 'CONNECTED'：已连接

不同状态变更的含义：

• DISCONNECTED -> CONNECTING: 正在尝试建立连接，调用进房接口或者 SDK 自动重连时触发。
• CONNECTING -> DISCONNECTED: 连接建立失败，当正在连接时调用退房接口中断连接或者经过 SDK 重试后任然连接失败时触发。
• CONNECTING -> CONNECTED: 连接建立成功，连接成功时触发。
• CONNECTED -> DISCONNECTED: 连接中断，调用退房接口或者当网络异常导致连接断开时触发。

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

trtc.on(TRTC.CONNECTION_STATE_CHANGED, event => {
  const prevState = event.prevState;
  const curState = event.state;
});

音频播放状态变更事件

event.userId 当 userId 为空串时，代表本地用户，非空串代表远端用户。

event.state 取值如下：

• 'PLAYING'：开始播放
  • event.reason 为 'playing' 或者 'unmute'。
• 'PAUSED'：暂停播放
  • event.reason 为 'pause' 时，由 <audio> element 的 pause 事件触发，如下几种情况会触发：
    • 调用 HTMLMediaElement.pause 接口。
  • event.reason 为 'mute' 时。详见事件 MediaStreamTrack.mute_event
    • 若 userId 为自己时 触发该事件，表明音频采集暂停，通常是设备异常引起，如设备被其他应用抢占，此时需引导用户重新采集。
    • 若 userId 为他人时 触发该事件，表明收到的音频数据不足以播放。通常是网络抖动引起，接入侧无需做任何处理。当收到的数据足以播放时，会自动恢复。
• 'STOPPED'：停止播放
  • event.reason 为 'ended'。

event.reason 状态变化的原因，取值如下：

• 'playing'：开始播放，详见事件 HTMLMediaElement.playing_event
• 'mute'：音频轨道暂时未能提供数据，详见事件 MediaStreamTrack.mute_event
• 'unmute'：音频轨道恢复提供数据，详见事件 MediaStreamTrack.unmute_event
• 'ended'：音频轨道已被关闭
• 'pause'：播放暂停

trtc.on(TRTC.EVENT.AUDIO_PLAY_STATE_CHANGED, event => {
  console.log(`${event.userId} player is ${event.state} because of ${event.reason}`);
});

视频播放状态变更事件

event.userId 当 userId 为空串时，代表本地用户，非空串代表远端用户。

event.streamType 流类型，取值：TRTC.TYPE.STREAM_TYPE_MAIN TRTC.TYPE.STREAM_TYPE_SUB

event.state 取值如下：

• 'PLAYING'：开始播放
  • event.reason 为 'playing' 或者 'unmute'。
• 'PAUSED'：暂停播放
  • event.reason 为 'pause' 时，由 <video> element 的 pause 事件触发，如下几种情况会触发：
    • 调用 HTMLMediaElement.pause 接口。
    • 在播放成功后，从 DOM 中移除了播放视频的 view 容器。
  • event.reason 为 'mute' 时。详见事件 MediaStreamTrack.mute_event
    • 若 userId 为自己时 触发该事件，表明视频采集暂停，通常是设备异常引起，如设备被其他应用抢占，此时需引导用户重新采集。
    • 若 userId 为他人时 触发该事件，表明收到的视频数据不足以播放。通常是网络抖动引起，接入侧无需做任何处理。当收到的数据足以播放时，会自动恢复。
• 'STOPPED'：停止播放
  • event.reason 为 'ended'。

event.reason 状态变化的原因，取值如下：

• 'playing'：开始播放，详见事件 HTMLMediaElement.playing_event
• 'mute'：视频轨道暂时未能提供数据，详见事件 MediaStreamTrack.mute_event
• 'unmute'：视频轨道恢复提供数据，详见事件 MediaStreamTrack.unmute_event
• 'ended'：视频轨道已被关闭
• 'pause'：播放暂停

trtc.on(TRTC.EVENT.VIDEO_PLAY_STATE_CHANGED, event => {
  console.log(`${event.userId} ${event.streamType} video player is ${event.state} because of ${event.reason}`);
});

本地屏幕分享停止事件通知，仅对本地屏幕分享流有效。

trtc.on(TRTC.EVENT.SCREEN_SHARE_STOPPED, () => {
  console.log('screen sharing was stopped');
});

摄像头、麦克风等设备变化的通知事件。

• event.device 是一个 MediaDeviceInfo 对象，属性：
  • deviceId：设备 Id
  • label：设备描述信息
  • groupId：设备 groupId
• event.type 值：'camera'|'microphone'|'speaker'
• event.action 值：
  • 'add' 设备已添加。
  • 'remove' 设备已被移除。
  • 'active' 设备已启动，例如：startLocalVideo 成功后，会触发该事件。

trtc.on(TRTC.EVENT.DEVICE_CHANGED, (event) => {
  console.log(`${event.type}(${event.device.label}) ${event.action}`);
});

推流状态变更事件。

• event.mediaType 媒体类型，值：'audio'|'video'|'screen'。
• event.state 当前的推流状态，值：
  • 'starting' 正在尝试推流
  • 'started' 推流成功
  • 'stopped' 推流停止，原因见 event.reason 字段
• event.prevState 上一次事件触发时的推流状态，值和 event.state 相同。
• event.reason 推流状态变为 'stopped' 的原因，值：
  • 'timeout' 推流超时，一般是由于网络抖动、防火墙拦截导致。SDK 会不断进行重试，业务侧可以在此时引导用户检查网络、更换网络。
  • 'error' 推流出错，此时可从 event.error 中获取到具体错误信息，一般是由于浏览器不支持 H264 编码导致。
  • 'api-call' 业务侧 api 调用导致推流停止，例如在 startLocalVideo 推流成功前，调用了 stopLocalVideo 停止了推流，属于正常行为，业务侧无需关注。
• event.error event.reason 为 'error' 时的错误信息。

trtc.on(TRTC.EVENT.PUBLISH_STATE_CHANGED, (event) => {
  console.log(`${event.mediaType} ${event.state} ${event.reason}`);
});

通话相关数据指标。

• 监听该事件后，SDK 会以 2s 一次的频率定时抛出该事件。
• 您可以从该事件中可以获取通话的网络质量（rtt、丢包率）、上行和下行的音视频统计信息（音量大小、宽高、帧率、码率）等信息。详细参数说明请参考：TRTCStatistics

trtc.on(TRTC.EVENT.STATISTICS, statistics => {
   console.warn(statistics.rtt, statistics.upLoss, statistics.downLoss);
})

收到 SEI message

trtc.on(TRTC.EVENT.SEI_MESSAGE, event => {
   console.log(`收到 ${event.userId} 的 sei message: ${event.data}`)
})

收到新的 MediaStreamTrack 对象

trtc.on(TRTC.EVENT.TRACK, event => {
  const isLocal = event.userId === ''; // userId === '' means event.track is a local track, otherwise it's a remote track
  const isSubStream = event.streamType === TRTC.TYPE.STREAM_TYPE_SUB; // Usually the sub stream is a screen-sharing video stream.
  const mediaStreamTrack = event.track;
  const kind = event.track.kind; // audio or video
})