EVENT

TRTC事件列表

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

注意:

  • 事件需要在事件触发之前监听,这样才能收到相应的事件通知,因此建议在 trtc 进房前完成事件监听,这样才能确保不会漏掉事件通知。
Example
// 使用方式:
trtc.on(TRTC.EVENT.ERROR, () => {});

Members

(static) ERROR

Default Value:
  • 'error'
See:

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

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

(static) AUTOPLAY_FAILED

Default Value:
  • 'autoplay-failed'

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

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

(static) KICKED_OUT

Default Value:
  • 'kicked-out'

被踢出房间,原因如下:

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

(static) REMOTE_USER_ENTER

Default Value:
  • 'remote-user-enter'

远端用户进房事件。

  • live 模式下,只有主播才有进退房通知,观众没有进退房通知,观众可以收到主播的进退房通知。
Example
trtc.on(TRTC.EVENT.REMOTE_USER_ENTER, event => {
  const userId = event.userId;
});

(static) REMOTE_USER_EXIT

Default Value:
  • 'remote-user-exit'

远端用户退房事件。

  • live 模式下,只有主播才有进退房通知,观众没有进退房通知,观众可以收到主播的进退房通知。
Example
trtc.on(TRTC.EVENT.REMOTE_USER_EXIT, event => {
  const userId = event.userId;
});

(static) REMOTE_AUDIO_AVAILABLE

Default Value:
  • 'remote-audio-available'

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

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

(static) REMOTE_AUDIO_UNAVAILABLE

Default Value:
  • 'remote-audio-unavailable'

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

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

(static) REMOTE_VIDEO_AVAILABLE

Default Value:
  • 'remote-video-available'
See:

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

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

(static) REMOTE_VIDEO_UNAVAILABLE

Default Value:
  • 'remote-video-unavailable'

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

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

(static) AUDIO_VOLUME

Default Value:
  • 'audio-volume'

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

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

(static) NETWORK_QUALITY

Default Value:
  • 'network-quality'

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

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

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

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

    数值 含义
    0 网络状况未知,表示当前 trtc 实例还没有建立上行/下行连接
    1 网络状况极佳
    2 网络状况较好
    3 网络状况一般
    4 网络状况差
    5 网络状况极差
    6 网络连接已断开
    注意:若下行网络质量为此值,则表示所有下行连接都断开了
  • uplinkRTT,uplinkLoss 为上行 RTT(ms) 及上行丢包率。

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

Note

  • 如果您想知道对方的上下行网络情况,需要把对方的网络质量情况通过 IM 广播出去。
Example
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}`)
})

(static) CONNECTION_STATE_CHANGED

Default Value:
  • 'connection-state-changed'

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

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

不同状态变更的含义:

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

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

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

(static) AUDIO_PLAY_STATE_CHANGED

Default Value:
  • 'audio-play-state-changed'

音频播放状态变更事件

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 状态变化的原因,取值如下:

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

(static) VIDEO_PLAY_STATE_CHANGED

Default Value:
  • 'video-play-state-changed'

视频播放状态变更事件

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 状态变化的原因,取值如下:

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

(static) SCREEN_SHARE_STOPPED

Default Value:
  • 'screen-share-stopped'

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

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

(static) DEVICE_CHANGED

Default Value:
  • 'device-changed'

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

  • event.device 是一个 MediaDeviceInfo 对象,属性:
    • deviceId:设备 Id
    • label:设备描述信息
    • groupId:设备 groupId
  • event.type 值:'camera'|'microphone'|'speaker'
  • event.action 值:
    • 'add' 设备已添加。
    • 'remove' 设备已被移除。
    • 'active' 设备已启动,例如:startLocalVideo 成功后,会触发该事件。
Example
trtc.on(TRTC.EVENT.DEVICE_CHANGED, (event) => {
  console.log(`${event.type}(${event.device.label}) ${event.action}`);
});

(static) PUBLISH_STATE_CHANGED

Default Value:
  • 'publish-state-changed'

推流状态变更事件。

  • 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' 时的错误信息。
Example
trtc.on(TRTC.EVENT.PUBLISH_STATE_CHANGED, (event) => {
  console.log(`${event.mediaType} ${event.state} ${event.reason}`);
});

(static) STATISTICS

Since:
  • v5.2.0
Default Value:
  • 'statistics'

通话相关数据指标。

  • 监听该事件后,SDK 会以 2s 一次的频率定时抛出该事件。
  • 您可以从该事件中可以获取通话的网络质量(rtt、丢包率)、上行和下行的音视频统计信息(音量大小、宽高、帧率、码率)等信息。详细参数说明请参考:TRTCStatistics
Example
trtc.on(TRTC.EVENT.STATISTICS, statistics => {
   console.warn(statistics.rtt, statistics.upLoss, statistics.downLoss);
})

(static) SEI_MESSAGE

Since:
  • v5.3.0
Default Value:
  • 'sei-message'

收到 SEI message

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

(static) TRACK

Since:
  • v5.3.0
Default Value:
  • 'track'

收到新的 MediaStreamTrack 对象

Example
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
})