EVENT

TRTC Event List

Listen to specific events through trtc.on(TRTC.EVENT.XXX). You can use these events to manage the room user list, manage user stream state, and perceive network state. The following is a detailed introduction to the events.

Notice:

  • Events need to be listened to before they are triggered, so that you can receive the corresponding event notifications. Therefore, it is recommended to complete event listening before entering the room, so as to ensure that no event notifications are missed.
Example
// Usage:
trtc.on(TRTC.EVENT.ERROR, () => {});

Members

(static) ERROR

Default Value:
  • 'error'
See:

Error event, non-API call error, SDK throws when an unrecoverable error occurs during operation.

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'

Automatic playback failed, refer to Handle Autoplay Restriction

Example
trtc.on(TRTC.EVENT.AUTOPLAY_FAILED, event => {
  // Guide user to click the page, SDK will resume playback automatically when user click the page.
  // Since v5.1.3+, you can get userId on this event.
  console.log(event.userId);
});

(static) KICKED_OUT

Default Value:
  • 'kicked-out'

Kicked out of the room for some reason, including:

  • kick: The same user with same userId enters same room. The user who enters the room first will be kicked out of the room by the user who enters later.
    • Entering a room with the same userId is not allowed behavior, which may lead to abnormal audio/video calls between the two parties, and should be avoided on the business side.
    • Users with the same userId who enter the same room with the same audience role may not receive this event.
  • banned: kicked out by the administrator using Server API - RemoveUser.
  • room_disband: kicked out by the administrator using Server API - DismissRoom.
Example
trtc.on(TRTC.EVENT.KICKED_OUT, event => {
  console.log(event.reason)
});

(static) REMOTE_USER_ENTER

Default Value:
  • 'remote-user-enter'

Remote user enters the room event.

  • In rtc mode, all users will receive the notification of entering and exiting the room of the other user.
  • In live mode, only the anchor has the notification of entering and exiting the room, and the audience does not have the notification of entering and exiting the room. The audience can receive the notification of entering and exiting the room of the anchor.
Example
trtc.on(TRTC.EVENT.REMOTE_USER_ENTER, event => {
  const userId = event.userId;
});

(static) REMOTE_USER_EXIT

Default Value:
  • 'remote-user-exit'

Remote user exits the room event.

  • In rtc mode, all users will receive the notification of entering and exiting the room of the other user.
  • In live mode, only the anchor has the notification of entering and exiting the room, and the audience does not have the notification of entering and exiting the room. The audience can receive the notification of entering and exiting the room of the anchor.
Example
trtc.on(TRTC.EVENT.REMOTE_USER_EXIT, event => {
  const userId = event.userId;
});

(static) REMOTE_AUDIO_AVAILABLE

Default Value:
  • 'remote-audio-available'

Remote user publishes audio. You will receive this notification when the remote user turns on the microphone. Refer to: Turn on/off camera and microphone

Example
// Listen before entering the room
trtc.on(TRTC.EVENT.REMOTE_AUDIO_AVAILABLE, event => {
  const userId = event.userId;
});

(static) REMOTE_AUDIO_UNAVAILABLE

Default Value:
  • 'remote-audio-unavailable'

Remote user stops publishing audio. You will receive this notification when the remote user turns off the microphone.

Example
// Listen before entering the room
trtc.on(TRTC.EVENT.REMOTE_AUDIO_UNAVAILABLE, event => {
  const userId = event.userId;
});

(static) REMOTE_VIDEO_AVAILABLE

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

Remote user publishes video. You will receive this notification when the remote user turns on the camera. Refer to: Turn on/off camera and microphone

  • You can listen for this event and REMOTE_VIDEO_UNAVAILABLE to update the UI icon for "whether the remote camera is turned on".
Example
// Listen before entering the room
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'

Remote user stops publishing video. You will receive this notification when the remote user turns off the camera.

Example
// Listen before entering the room
trtc.on(TRTC.EVENT.REMOTE_VIDEO_UNAVAILABLE, event => {
  const userId = event.userId;
  const streamType = event.streamType;
  // At this point, the SDK will automatically stop playing, and there is no need to call stopRemoteVideo.
});

(static) AUDIO_VOLUME

Default Value:
  • 'audio-volume'

Volume event
After calling the enableAudioVolumeEvaluation interface to enable the volume callback, the SDK will throw this event regularly to notify the volume of each userId.
Note

  • The callback contains the volume of the local microphone and the volume of the remote user. The callback will be triggered regardless of whether anyone is speaking.
  • The event.result will be sorted from large to small according to the volume size.
  • When userId is an empty string, it represents the volume of the local microphone.
  • volume is a positive integer with a value of 0-100.
Example
trtc.on(TRTC.EVENT.AUDIO_VOLUME, event => {
   event.result.forEach(({ userId, volume }) => {
       const isMe = userId === ''; // When userId is an empty string, it represents the volume of the local microphone.
       if (isMe) {
           console.log(`my volume: ${volume}`);
       } else {
           console.log(`user: ${userId} volume: ${volume}`);
       }
   })
});
// Enable volume callback and trigger the event every 1000ms
trtc.enableAudioVolumeEvaluation(1000);

(static) NETWORK_QUALITY

Default Value:
  • 'network-quality'

Network quality statistics data event, which starts to be counted after entering the room and triggers every two seconds. This data reflects the network quality of your local uplink and downlink.

  • The uplink network quality (uplinkNetworkQuality) refers to the network situation of uploading local streams (uplink connection network quality from SDK to Tencent Cloud)

  • The downlink network quality (downlinkNetworkQuality) refers to the average network situation of downloading all streams (average network quality of all downlink connections from Tencent Cloud to SDK)

    The enumeration values and meanings are shown in the following table:

    Value Meaning
    0 Network state is unknown, indicating that the current trtc instance has not established an uplink/downlink connection
    1 Network state is excellent
    2 Network state is good
    3 Network state is average
    4 Network state is poor
    5 Network state is very poor
    6 Network connection is disconnected
    Note: If the downlink network quality is this value, it means that all downlink connections have been disconnected
  • uplinkRTT, uplinkLoss are the uplink RTT (ms) and uplink packet loss rate.

  • downlinkRTT, downlinkLoss are the average RTT (ms) and average packet loss rate of all downlink connections.

Note

  • If you want to know the uplink and downlink network conditions of the other party, you need to broadcast the other party's network quality through 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 and Tencent Cloud connection state change event, you can use this event to listen to the overall connection state of the SDK and Tencent Cloud.

  • 'DISCONNECTED': Connection disconnected
  • 'CONNECTING': Connecting
  • 'CONNECTED': Connected

Meanings of different state changes:

  • DISCONNECTED -> CONNECTING: Trying to establish a connection, triggered when calling the enter room interface or when the SDK automatically reconnects.
  • CONNECTING -> DISCONNECTED: Connection establishment failed, triggered when calling the exit room interface to interrupt the connection or when the connection fails after SDK retries.
  • CONNECTING -> CONNECTED: Connection established successfully, triggered when the connection is successful.
  • CONNECTED -> DISCONNECTED: Connection interrupted, triggered when calling the exit room interface or when the connection is disconnected due to network anomalies.

Suggestion: You can listen to this event and display different UIs in different states to remind users of the current connection state.

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

(static) AUDIO_PLAY_STATE_CHANGED

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

Audio playback state change event

event.userId When userId is an empty string, it represents the local user, and when it is a non-empty string, it represents a remote user.

event.state The value is as follows:

  • 'PLAYING': start playing
    • event.reason is 'playing' or 'unmute'.
  • 'PAUSED': pause playback
    • When event.reason is 'pause', it is triggered by the pause event of the <audio> element. The following situations will trigger:
      • Call the HTMLMediaElement.pause interface.
    • When event.reason is 'mute'. See event MediaStreamTrack.mute_event
      • When userId is oneself, this event is triggered, indicating that audio collection is paused, usually caused by device abnormalities, such as being preempted by other applications on the device, at this time, the user needs to be guided to recollect.
      • When userId is others, this event is triggered, indicating that the received audio data is not enough to play. Usually caused by network jitter, no processing is required on the access side. When the received data is sufficient to play, it will automatically resume.
  • 'STOPPED': stop playing
    • event.reason is 'ended'.

event.reason The reason for the state change, the value is as follows:

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'

Video playback state change event

event.userId When userId is an empty string, it represents the local user, and when it is a non-empty string, it represents a remote user.

event.streamType Stream type, value: TRTC.TYPE.STREAM_TYPE_MAIN TRTC.TYPE.STREAM_TYPE_SUB

event.state The value is as follows:

  • 'PLAYING': start playing
    • event.reason is 'playing' or 'unmute'.
  • 'PAUSED': pause playback
    • When event.reason is 'pause', it is triggered by the pause event of the <video> element. The following situations will trigger:
      • Call the HTMLMediaElement.pause interface.
      • After successful playback, the view container for playing the video is removed from the DOM.
    • When event.reason is 'mute'. See event MediaStreamTrack.mute_event
      • When userId is oneself, this event is triggered, indicating that video collection is paused, usually caused by device abnormalities, such as being preempted by other applications on the device, at this time, the user needs to be guided to recollect.
      • When userId is others, this event is triggered, indicating that the received video data is not enough to play. Usually caused by network jitter, no processing is required on the access side. When the received data is sufficient to play, it will automatically resume.
  • 'STOPPED': stop playing
    • event.reason is 'ended'.

event.reason The reason for the state change, the value is as follows:

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'

Notification event for local screen sharing stop, only valid for local screen sharing streams.

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

(static) DEVICE_CHANGED

Default Value:
  • 'device-changed'

Notification event for device changes such as camera and microphone.

  • event.device is a MediaDeviceInfo object with properties:
    • deviceId: device ID
    • label: device description information
    • groupId: device group ID
  • event.type value: 'camera'|'microphone'|'speaker'
  • event.action value:
    • 'add' device has been added.
    • 'remove' device has been removed.
    • 'active' device has been activated, for example: after startLocalVideo is successful, this event will be triggered.
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'

Publish state change event.

  • event.mediaType media type, value: 'audio'|'video'|'screen'.
  • event.state current publish state, value:
    • 'starting' trying to publish stream
    • 'started' publish stream succeeded
    • 'stopped' publish stream stopped, see event.reason field for the reason
  • event.prevState the publish state at the last event trigger, with the same type as event.state.
  • event.reason the reason for the publish state to become 'stopped', value:
    • 'timeout' publish stream timeout, usually caused by network jitter or firewall interception. The SDK will keep retrying, and the business side can guide the user to check the network or change the network at this time.
    • 'error' publish stream error, at this time, you can get the specific error information from event.error, usually caused by the browser not supporting H264 encoding.
    • 'api-call' publish stream stopped due to business side API call, for example, stopLocalVideo was called to stop the publish stream before startLocalVideo was successful, which is a normal behavior and the business side does not need to pay attention to it.
  • event.error error information when event.reason is 'error'.
Example
trtc.on(TRTC.EVENT.PUBLISH_STATE_CHANGED, (event) => {
  console.log(`${event.mediaType} ${event.state} ${event.reason}`);
});

(static) TRACK

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

a new MediaStreamTrack object received.

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

(static) STATISTICS

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

TRTC statistics.

  • SDK will fires this event once every 2s.
  • You can get the network quality, statistics of audio and video from this event. For detailed parameter description, please refer to 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 received

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

(static) CUSTOM_MESSAGE

Since:
  • v5.6.0
Default Value:
  • 'custom-message'

received a new custom message.

Example
trtc.on(TRTC.EVENT.CUSTOM_MESSAGE, event => {
   // event.userId: remote userId.
   // event.cmdId: message cmdId.
   // event.seq: message sequence number.
   // event.data: custom message data, type is ArrayBuffer.
})