TRTCCallback

Error event

Error event, which indicates that the SDK threw an irrecoverable error such as room entry failure or failure to start device. It is better to show a notice to user when irrecoverable error occurred.

For more information, see Error Codes.

Warning event

Warning event, which indicates that the SDK threw an error requiring attention, such as video lag or high CPU usage.

For more information, see Error Codes.

Whether room entry succeed event

After calling the enterRoom() API in TRTCCloud to enter a room, you will receive the onEnterRoom(result) event from TRTCCloudDelegate.

• If room entry succeeded, result will be a positive number (result > 0), indicating the time in milliseconds (ms) the room entry takes.
• If room entry failed, result will be a negative number (result < 0), indicating the error code for the failure. For more information on the error codes for room entry failure, see Error Codes.

Notice

1. In TRTC SDK versions earlier than 6.6, the onEnterRoom(result) event is emitted only if room entry succeeds, and the onError() event is emitted if room entry fails.
2. In TRTC SDK 6.6 and later, the onEnterRoom(result) event is emitted regardless of whether room entry succeeds or fails, and the onError() event is also emitted if room entry fails.

Room exit event

Calling the exitRoom() API in TRTCCloud will trigger the execution of room exit-related logic, such as releasing resources of audio/video devices and codecs. After all resources occupied by the SDK are released, the SDK will emit the onExitRoom() event.

If you need to call enterRoom() again or switch to another audio/video SDK, please wait until you receive the onExitRoom() event. Otherwise, you may encounter problems such as the camera or mic being occupied.

Room switching event

You can call the switchRole() API in TRTCCloud to switch between the anchor and audience roles. This is accompanied by a line switching process. After the switching, the SDK will emit the onSwitchRole() event.

Role switching event

You can call the switchRole() API in TRTCCloud to switch between the anchor and audience roles. This is accompanied by a line switching process. After the switching, the SDK will emit the onSwitchRole() event.

Result of requesting cross-room call event

You can call the connectOtherRoom() API in TRTCCloud to establish a video call with the anchor of another room. This is the “anchor competition” feature. The caller will receive the onConnectOtherRoom() event, which can be used to determine whether the cross-room call is successful. If it is successful, all users in either room will receive the onUserVideoAvailable() event from the anchor of the other room.

Result of ending cross-room call event

A user entered the room event

Due to performance concerns, this event works differently in different scenarios (i.e., AppScene, which you can specify by setting the second parameter when calling enterRoom).

• Live streaming scenarios (TRTCAppSceneLIVE or TRTCAppSceneVoiceChatRoom): in live streaming scenarios, a user is either in the role of an anchor or audience. The event is emitted only when an anchor enters the room.
• Call scenarios (TRTCAppSceneVideoCall or TRTCAppSceneAudioCall): in call scenarios, the concept of roles does not apply (all users can be considered as anchors), and the event is emitted when any user enters the room.

Notice:

1. The onRemoteUserEnterRoom event indicates that a user entered the room, but it does not necessarily mean that the user enabled audio or video.
2. If you want to know whether a user enabled video, we recommend you use the onUserVideoAvailable() and onUserAudioAvailable event.

A user exited the room event

As with onRemoteUserEnterRoom, this event works differently in different scenarios (i.e., AppScene, which you can specify by setting the second parameter when calling enterRoom).

• Live streaming scenarios (TRTCAppSceneLIVE or TRTCAppSceneVoiceChatRoom): the event is emitted only when an anchor exits the room.
• Call scenarios (TRTCAppSceneVideoCall or TRTCAppSceneAudioCall): in call scenarios, the concept of roles does not apply, and the event is emitted when any user exits the room.

A remote user published/unpublished primary stream video

The primary stream is usually used for camera images. If you receive the onUserVideoAvailable(userId, 1) event, it indicates that the user has available primary stream video. You can then call startRemoteView to subscribe to the remote user’s video. If the subscription is successful, you will receive the onFirstVideoFrame(userId) event, which indicates that the first video frame of the user is rendered.

If you receive the onUserVideoAvailable(userId, 0) event, it indicates that the video of the remote user is disabled, which may be because the user called muteLocalVideo or stopLocalPreview.

A remote user published/unpublished substream video

The substream is usually used for screen sharing images. If you receive the onUserSubStreamAvailable(userId, 1) event, it indicates that the user has available substream video. You can then call startRemoteView to subscribe to the remote user’s video. If the subscription is successful, you will receive the onFirstVideoFrame(userId) event, which indicates that the first frame of the user is rendered.

Notice: From SDK version 8.0 and above, you should not use startRemoteSubStreamView, which has been deprecated.

A remote user published/unpublished audio event

If you receive the onUserAudioAvailable(userId, 1) event, it indicates that the user published audio.

• In auto-subscription mode, the SDK will play the user’s audio automatically.
• In manual subscription mode, you can call muteRemoteAudio(userId, 0) to play the user’s audio.

The SDK started rendering the first video frame of the local or a remote user evnet

The SDK emits this event when it starts rendering your first video frame or that of a remote user. The userId in the event arguments can help you determine whether the frame is yours or a remote user’s.

• If userId is empty string, it indicates that the SDK has started rendering your first video frame. The precondition is that you have called startLocalPreview or startScreenCapture.
• If userId is not empty, it indicates that the SDK has started rendering the first video frame of a remote user. The precondition is that you have called startRemoteView to subscribe to the user’s video.

Notice

1. The event of the first local video frame being rendered is triggered only after you call startLocalPreview or startScreenCapture.
2. The event of the first video frame of a remote user being rendered is triggered only after you call startRemoteView.

The SDK started playing the first audio frame of a remote user event (local user not supported)

The SDK emits this event when it plays the first audio frame of a remote user. The event is not emitted for the playing of the first audio frame of the local user.

The first local video frame was published event

After you enter a room and call startLocalPreview or startScreenCapture to enable local video capturing (whichever happens first), the SDK will start video encoding and publish the local video data via its network module to the cloud. It emits the onSendFirstLocalVideoFrame event after publishing the first local video frame.

The first local audio frame was published event

After you enter a room and call startLocalAudio to enable audio capturing (whichever happens first), the SDK will start audio encoding and publish the local audio data via its network module to the cloud. The SDK emits the onSendFirstLocalAudioFrame event after sending the first local audio frame.

An anchor entered the room event (deprecated)

This event is not recommended in the new version. Please use onRemoteUserEnterRoom instead.

An anchor left the room event (deprecated)

This event is not recommended in the new version. Please use onRemoteUserLeaveRoom instead.

Real-time network quality statistics event

This event is emitted every 2 seconds and notifies you of the upstream and downstream network quality detected by the SDK. The SDK uses a built-in proprietary algorithm to assess the current latency, bandwidth, and stability of the network and returns a result. If the result is 1 (excellent), it means that the current network conditions are excellent; if it is 6 (down), it means that the current network conditions are too bad to support TRTC calls.

Notice: In the returned parameters localQuality and remoteQuality, if userId is empty string, it indicates that the network quality statistics of the local user are returned. Otherwise, the network quality statistics of a remote user are returned.

Real-time statistics on technical metrics event

This event is emitted every 2 seconds and notifies you of the statistics on technical metrics related to video, audio, and network. The metrics are listed in TRTCStatistics:

• Video statistics: video resolution (resolution), frame rate (FPS), bitrate (bitrate), etc.
• Audio statistics: audio sample rate (samplerate), number of audio channels (channel), bitrate (bitrate), etc.
• Network statistics: the round trip time (rtt) between the SDK and the cloud (SDK -> Cloud -> SDK), package loss rate (loss), upstream traffic (sentBytes), downstream traffic (receivedBytes), etc.

Notice: If you want to learn about only the current network quality and do not want to spend much time analyzing the statistics returned by this event notification, we recommend you use onNetworkQuality.

SDK was disconnected from the cloud event

SDK emits this event when it is disconnected from the cloud, which may be caused by network unavailability or change of network, for example, when the user walks into an elevator. After emitting this event, SDK will attempt to reconnect to the cloud, and will emit the onTryToReconnect event. When it is reconnected, it will emit the onConnectionRecovery event. In other words, the SDK proceeds from one event to the next in the following order:

         =====>  =====> 
              /|\                                                     |
               |------------------------------------------------------|

SDK is reconnecting to the cloud event

When the SDK is disconnected from the cloud, it emits the onConnectionLost event. It then attempts to reconnect and emits this event(onTryToReconnect). After it is reconnected, it emits the onConnectionRecovery event.

SDK is reconnected to the cloud event

When the SDK is disconnected from the cloud, it emits the [onConnectionLost]onConnectionLost event. It then attempts to reconnect and emits the [onTryToReconnect]onTryToReconnect event. After it is reconnected, it emits this event([onConnectionRecovery]onConnectionRecovery).

Result of server speed testing event (deprecated)

Result of server speed testing event

After you call startSpeedTest() to start server speed testing, the SDK will return the testing results multiple times with multiple server. The SDK tests the speed of multiple servers and returns the result for each IP via this event.

The camera is ready event

After you call startLocalPreivew, the SDK will try to start the camera and emit this event if the camera is started. If it fails to start the camera, it’s probably because the application does not have access to the camera or the camera is being used. You can listen the onError event to learn about the exception and let users know via UI notification.

The microphone is ready event

After you call startLocalAudio, the SDK will try to start the microphone and emit this event if the mic is started. If it fails to start the mic, it’s probably because the application does not have access to the mic or the mic is being used. You can listen the onError event to learn about the exception and let users know via UI notification.

User volume statistics notification event

The SDK can assess the volume of each channel and emit this event on a regular basis. You can display, for example, a waveform or volume bar on the UI based on the statistics returned. You need to call enableAudioVolumeEvaluation to enable this feature and set the interval for the event notification. Note that the SDK emits this event at the specified interval regardless of whether someone is speaking in the room. When no one is speaking in the room, userVolumes is empty, and totalVolume is 0.

The status of a local device changed event

The SDK emits this event when a local device (camera, microphone, or speaker) is connected or disconnected.

Volume notification event during microphone test

When you call startMicDeviceTest to test the microphone, the SDK will keep emitting this event. The volume parameter represents the volume of the audio captured by the microphone. If the value of the volume parameter fluctuates, the microphone works properly. If it is 0 throughout the test, it indicates that there is a problem with the microphone, and users should be prompted to switch to a different microphone.

Volume notification event during speaker test

When you call startSpeakerDeviceTest to test the speaker, the SDK will keep emitting this event. The volume parameter in the event arguments represents the volume of audio sent by the SDK to the speaker for playback. If its value fluctuates but users cannot hear any sound, the speaker is not working properly.

Capturing volume of the mic changed event

On desktop OS such as macOS and Windows, users can set the capturing volume of the microphone in the audio control panel. The higher volume a user sets, the higher the volume of raw audio captured by the microphone. On some keyboards and laptops, users can also mute the mic by pressing a key (whose icon is a crossed out microphone).

When users set the microphone capturing volume via the UI or a keyboard shortcut, the SDK will emit this event.

You need to call enableAudioVolumeEvaluation and set the interval (interval > 0) to enable the event notification. To disable the event notification, set interval to 0.

Playback volume changed event

On desktop OS such as macOS and Windows, users can set the system’s playback volume in the audio control panel. On some keyboards and laptops, users can also mute the speaker by pressing a key (whose icon is a crossed out speaker).

When users set the system’s playback volume via the UI or a keyboard shortcut, the SDK will emit this event.

You need to call enableAudioVolumeEvaluation and set the interval (interval > 0) to enable the event notification. To disable the event notification, set interval to 0.

Receipt of custom message event

When a user in a room uses sendCustomCmdMsg to send a custom message, other users in the room can receive the message through the onRecvCustomCmdMsg event.

Loss of custom message event

When you use sendCustomCmdMsg to send a custom UDP message, even if you enable reliable transfer (by setting reliable to true), there is still a chance of message loss. Reliable transfer only helps maintain a low probability of message loss, which meets the reliability requirements in most cases. If the sender sets reliable to true, the SDK will emit this event to notify the recipient of the number of custom messages lost during a specified time period (usually 5s) in the past.

Notice: The recipient receives this event only if the sender sets reliable to true.

Receipt of SEI message event

If a user in the room uses sendSEIMsg to send an SEI message via video frames, other users in the room can receive the message through the onRecvSEIMsg event.

Starting publishing media stream event

When you call startPublishMediaStream to start publishing media streams to the TRTC backend service, the SDK will immediately synchronize this instruction with the cloud server. Subsequently, the SDK will receive the processing result from the cloud server and notify you of the execution result of the instruction through this event callback.

Update publishing media stream event

When you call the media stream publishing interface (updatePublishMediaStream) to start updating the media stream to the TRTC backend service, the SDK will immediately synchronize this instruction with the cloud server. Subsequently, the SDK will receive the processing result from the cloud server and notify you of the execution result of the instruction through this event callback.

Stop publishing media stream event

When you call the stop publishing media stream (stopPublishMediaStream) to start stopping the media stream to the TRTC backend service, the SDK will immediately synchronize this instruction with the cloud server. Subsequently, the SDK will receive the processing result from the cloud server and notify you of the execution result of the instruction through this event callback.

Changes in RTMP/RTMPS streaming status event

When you call startPublishMediaStream to start publishing media streams to the TRTC backend service, the SDK will immediately synchronize this instruction with the cloud service. If you have set the URL configuration for publishing audio and video streams to Tencent or third-party CDN in the target streaming configuration (TRTCPublishTarget), the specific RTMP or RTMPS streaming status will be synchronized to you through this callback.

Started publishing to Tencent Cloud CSS CDN event

When you call startPublishing to publish streams to Tencent Cloud CSS CDN, the SDK will sync the command to the CVM immediately. The SDK will then receive the execution result from the CVM and return the result to you via this event.

Stopped publishing to Tencent Cloud CSS CDN event

When you call stopPublishing to stop publishing streams to Tencent Cloud CSS CDN, the SDK will sync the command to the CVM immediately. The SDK will then receive the execution result from the CVM and return the result to you via this event.

Started publishing to non-Tencent Cloud’s live streaming CDN event

When you call startPublishCDNStream to start publishing streams to a non-Tencent Cloud’s live streaming CDN, the SDK will sync the command to the CVM immediately. The SDK will then receive the execution result from the CVM and return the result to you via this event.

Notice: If you receive a event that the command is executed successfully, it only means that your command was sent to Tencent Cloud’s backend server. If the CDN vendor does not accept your streams, the publishing will still fail.

Stopped publishing to non-Tencent Cloud’s live streaming CDN event

When you call stopPublishCDNStream to stop publishing to a non-Tencent Cloud’s live streaming CDN, the SDK will sync the command to the CVM immediately. The SDK will then receive the execution result from the CVM and return the result to you via this event.

Set the layout and transcoding parameters for On-Cloud MixTranscoding event

When you call setMixTranscodingConfig to modify the layout and transcoding parameters for On-Cloud MixTranscoding, the SDK will sync the command to the CVM immediately. The SDK will then receive the execution result from the CVM and return the result to you via this event.

Audio effects ended event (deprecated)

Shared window was covered event

The SDK emits this event when the shared window is covered and cannot be captured. Upon receiving this event, you can prompt users via the UI to move and expose the window.

Screen sharing started event

The SDK emits this event when you call startScreenCapture and other APIs to start screen sharing.

Screen sharing paused event

The SDK emits this event when you call pauseScreenCapture to pause screen sharing.

Screen sharing resumed event

The SDK emits this event when you call resumeScreenCapture to resume screen sharing.

Screen sharing stopped event

The SDK emits this event when you call stopScreenCapture to stop screen sharing.

Finished taking a local screenshot event

Local recording started

When you call startLocalRecording to start local recording, the SDK will emit this event to notify you whether recording is started successfully.

Local media is being recording

The SDK will emit this event regularly after local recording is started successfully via the calling of startLocalRecording. You can listen to this event to stay up to date with the status of the recording task. You can set the event notification interval when calling startLocalRecording.

Local recording completed

When you call stopLocalRecording to stop local recording, the SDK will emit event to notify you of the recording result.

system audio capturing failed event

You can call startSystemAudioLoopback to have the SDK capture the audio played back by the system. In cases such as video teaching and music live streaming, the teacher can use this feature to let the SDK capture the sound of the video played by his or her computer, so that students in the room can hear the sound too. The SDK will emit this event after an attempt to enable system audio capture fails. Please note the error parameter in the event.