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.
- Error code (error.code): ErrorCode.OPERATION_FAILED
- Possible extended error codes (error.extraCode): 5501, 5502
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
- By default, the SDK automatically plays remote audio, and you do not need to call the API to play remote audio. You can listen for this event and REMOTE_AUDIO_UNAVAILABLE to update the UI icon for "whether the remote microphone is turned on".
- Note: If the user has not interacted with the page before entering the room, automatic audio playback may fail due to the browser's automatic playback policy restrictions. You need to refer to the suggestions for handling automatic playback restrictions for processing.
- If you do not want the SDK to automatically play audio, you can set
autoReceiveAudio
tofalse
to turn off automatic audio playback when calling trtc.enterRoom(). - Listen for the TRTC.EVENT.REMOTE_AUDIO_AVAILABLE event, record the userId with remote audio, and call the trtc.muteRemoteAudio(userId, false) method when you need to play audio.
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.
- When event.reason is 'pause', it is triggered by the pause event of the <audio> element. The following situations will trigger:
- 'STOPPED': stop playing
- event.reason is 'ended'.
event.reason The reason for the state change, the value is as follows:
- 'playing': start playing, see event HTMLMediaElement.playing_event
- 'mute': The audio track cannot provide data temporarily, see event MediaStreamTrack.mute_event
- 'unmute': The audio track resumes providing data, see event MediaStreamTrack.unmute_event
- 'ended': The audio track has been closed
- 'pause': Playback paused
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.
- When event.reason is 'pause', it is triggered by the pause event of the <video> element. The following situations will trigger:
- 'STOPPED': stop playing
- event.reason is 'ended'.
event.reason The reason for the state change, the value is as follows:
- 'playing': start playing, see event HTMLMediaElement.playing_event
- 'mute': The video track cannot provide data temporarily, see event MediaStreamTrack.mute_event
- 'unmute': The video track resumes providing data, see event MediaStreamTrack.unmute_event
- 'ended': The video track has been closed
- 'pause': Playback paused
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.
})