TRTCCloudCallback @ TXLiteAVSDK.
Feature
Callback API class for TRTC video call feature.
Callback for error: SDK encountered an irrecoverable error and must be listened on. Corresponding UI reminders should be displayed based on the actual conditions.
void onError(TXLiteAVError errCode, const char * errMsg, void * extraInfo)
Parameters
Parameter | Type | Description |
---|---|---|
errCode | TXLiteAVError | Error code. |
errMsg | const char * | Error message. |
extraInfo | void * | Extended field. Certain error codes may carry extra information for troubleshooting. |
Callback for warning: this callback is used to alert to some non-serious problems such as lag or recoverable decoding failure.
void onWarning(TXLiteAVWarning warningCode, const char * warningMsg, void * extraInfo)
Parameters
Parameter | Type | Description |
---|---|---|
warningCode | TXLiteAVWarning | Warning code. |
warningMsg | const char * | Warning message. |
extraInfo | void * | Extended field. Certain warning codes may carry extra information for troubleshooting. |
Callback of room entry.
void onEnterRoom(int result)
Parameters
Parameter | Type | Description |
---|---|---|
result | int | If result is greater than 0, it will be the time used for room entry in ms; if result is smaller than 0, it will be room entry error code. |
Overview
After the enterRoom()
API in TRTCCloud
is called to enter a room, the onEnterRoom(result)
callback will be received from the SDK.
result
will be a positive number (result
> 0), indicating the time in milliseconds (ms) used for entering the room.result
will be a negative number (result
< 0), indicating the error code for room entry failure. For more information, please see Error Codes.In TRTC versions below 6.6, the
onEnterRoom(result)
callback will be returned only for successful room entry, and onError() will be returned for room entry failure. In TRTC v6.6 and above, a positiveresult
will be returned for successful room entry, and a negativeresult
together with the onError() callback will be returned for room entry failure.
Callback of room exit.
void onExitRoom(int reason)
Parameters
Parameter | Type | Description |
---|---|---|
reason | int | Reason for exiting the room. 0: the user actively called exitRoom to exit the room; 1: the user was kicked out of the room by the server; 2: the room was dismissed. |
Overview
When the exitRoom()
API in TRTCCloud
is called, the logic related to room exit will be executed, such as releasing resources of audio/video devices and codecs. After resources are released, the SDK will use the onExitRoom() callback to notify you.
If you need to call enterRoom()
again or switch to another audio/video SDK, please wait until you receive the onExitRoom() callback; otherwise, exceptions such as occupied camera or mic may occur.
Callback of role switching.
void onSwitchRole(TXLiteAVError errCode, const char * errMsg)
Parameters
Parameter | Type | Description |
---|---|---|
errCode | TXLiteAVError | Error code. ERR_NULL indicates a successful switch. For more information, please see Error Codes. |
errMsg | const char * | Error message. |
Overview
Calling the switchRole()
API in TRTCCloud
will switch between the anchor and viewer roles, which will be accompanied by a line switch process. After the SDK switches the roles, the onSwitchRole() event callback will be returned.
Callback of the result of requesting cross-room call (anchor competition).
void onConnectOtherRoom(const char * userId, TXLiteAVError errCode, const char * errMsg)
Parameters
Parameter | Type | Description |
---|---|---|
userId | const char * | userId of the target anchor to compete with |
errCode | TXLiteAVError | Error code. ERR_NULL indicates a successful switch. For more information, please see Error Codes. |
errMsg | const char * | Error message. |
Overview
Calling the connectOtherRoom()
API in TRTCCloud
will establish a video call between two anchors in two different rooms, i.e., the "anchor competition" feature. The caller will receive the onConnectOtherRoom() callback to see whether the cross-room call is successful; and if yes, all users in both rooms will receive the onUserVideoAvailable() callback of anchor competition.
Callback of the result of ending cross-room call (anchor competition).
void onDisconnectOtherRoom(TXLiteAVError errCode, const char * errMsg)
A user enters the current room.
void onRemoteUserEnterRoom(const char * userId)
Parameters
Parameter | Type | Description |
---|---|---|
userId | const char * | User ID. |
Overview
For the sake of performance, the behaviors of this notification will be different in two different application scenarios:
TRTCAppSceneVideoCall
): users in this scenario do not have different roles, and this notification will be triggered whenever a user enters the room.TRTCAppSceneLIVE
): this scenario does not limit the number of viewers. If any user entering or exiting the room could trigger the callback, it would cause great performance loss. Therefore, this notification will be triggered only when an anchor but not a viewer enters the room.Note:
onRemoteUserEnterRoom
andonRemoteUserLeaveRoom
apply only to maintaining the "member list" of the current room. To display the remote image, it is recommended to listen on the onUserVideoAvailable() event callback.
A user exits the current room, which corresponds to onuserEnterRoom
.
void onRemoteUserLeaveRoom(const char * userId, int reason)
Parameters
Parameter | Type | Description |
---|---|---|
userId | const char * | User ID. |
reason | int | Reason for exiting the room. 0: the user proactively exited the room; 1: the user exited the room due to timeout; 2: the user was kicked out of the room. |
Overview
Similar to onRemoteUserEnterRoom
, the behaviors of this notification will be different in two different application scenarios:
TRTCAppSceneVideoCall
): users in this scenario do not have different roles, and this notification will be triggered whenever a user exits the room.TRTCAppSceneLIVE
): this notification will be triggered only when an anchor but not a viewer exits the room.Whether camera is enabled for video.
void onUserVideoAvailable(const char * userId, bool available)
Parameters
Parameter | Type | Description |
---|---|---|
userId | const char * | User ID. |
available | bool | Whether image is enabled. |
Overview
When the onUserVideoAvailable(userId, YES)
notification is received, it indicates that available video data frames of the specified image channel have arrived. In this case, the startRemoteView(userId)
API needs to be called to load the image of the remote user. Then, the callback of rendering the first video frame, i.e., onFirstVideoFrame(userId)
, will be received.
When the onUserVideoAvailable(userId, NO)
notification is received, it indicates that the specified channel of remote image has been disabled, which may be because the user called muteLocalVideo()
or stopLocalPreview()
.
Whether screen sharing is enabled.
void onUserSubStreamAvailable(const char * userId, bool available)
Parameters
Parameter | Type | Description |
---|---|---|
userId | const char * | User ID. |
available | bool | Whether screen sharing is enabled. |
The function to display the secondary channel image is
startRemoteSubStreamView()
instead ofstartRemoteView()
.
Whether audio upstreaming is enabled.
void onUserAudioAvailable(const char * userId, bool available)
Parameters
Parameter | Type | Description |
---|---|---|
userId | const char * | User ID. |
available | bool | Whether audio is enabled. |
Rendering of the first frame of a local or remote user starts.
void onFirstVideoFrame(const char * userId, const TRTCVideoStreamType streamType, const int width, const int height)
Parameters
Parameter | Type | Description |
---|---|---|
userId | const char * | ID of the local or remote user. userId == null indicates the ID of the local user, while userId != null indicates the ID of a remote user. |
streamType | const TRTCVideoStreamType | Video stream type: camera or screen sharing. |
width | const int | Image width. |
height | const int | Image height. |
Overview
If userId
is null
, it indicates that the captured local camera image starts to be rendered, which needs to be triggered by calling startLocalPreview
first. If userId
is not null
, it indicates that the first video frame of the remote user starts to be rendered, which needs to be triggered by calling startRemoteView
first.
This callback will be triggered only after
startLocalPreview()
,startRemoteView()
, orstartRemoteSubStreamView()
is called.
Playback of the first audio frame of a remote user starts (local audio is not supported for notification currently).
void onFirstAudioFrame(const char * userId)
Parameters
Parameter | Type | Description |
---|---|---|
userId | const char * | Remote user ID. |
The first local video frame data has been sent.
void onSendFirstLocalVideoFrame(const TRTCVideoStreamType streamType)
Parameters
Parameter | Type | Description |
---|---|---|
streamType | const TRTCVideoStreamType | Video stream type: primary image, small image, or secondary stream image (screen sharing). |
Overview
The SDK will start capturing the camera and encode the captured image after successful call of enterRoom()
and startLocalPreview()
. This callback event will be returned after the SDK successfully sends the first video frame data to the cloud.
The first local audio frame data has been sent.
void onSendFirstLocalAudioFrame()
Overview
The SDK will start capturing the mic and encoding the captured audio after successful call of enterRoom()
and startLocalAudio()
. This callback event will be returned after the SDK successfully sends the first audio frame data to the cloud.
Disused API: an anchor enters the current room.
void onUserEnter(const char * userId)
Parameters
Parameter | Type | Description |
---|---|---|
userId | const char * | User ID. |
Overview
This callback API can be considered as the disused version of onRemoteUserEnterRoom
and is not recommended. Please use onUserVideoAvailable
or onRemoteUserEnterRoom
for substitution.
This API is disused and not recommended.
Disused API: an anchor exits the current room.
void onUserExit(const char * userId, int reason)
Parameters
Parameter | Type | Description |
---|---|---|
userId | const char * | User ID. |
reason | int | Reason for exit. |
Overview
This callback API can be considered as the disused version of onRemoteUserLeaveRoom
and is not recommended. Please use onUserVideoAvailable
or onRemoteUserEnterRoom
for substitution.
This API is disused and not recommended.
Network quality: this callback is triggered once every 2 seconds to collect statistics of the current network upstreaming and downstreaming quality.
void onNetworkQuality(TRTCQualityInfo localQuality, TRTCQualityInfo * remoteQuality, uint32_t remoteQualityCount)
Parameters
Parameter | Type | Description |
---|---|---|
localQuality | TRTCQualityInfo | Upstream network quality. |
remoteQuality | TRTCQualityInfo * | Downstream network quality. |
remoteQualityCount | uint32_t | Array size of the downstream network quality. |
userId == null
indicates the current local video quality.
Callback of technical metric statistics.
void onStatistics(const TRTCStatistics & statis)
Parameters
Parameter | Type | Description |
---|---|---|
statis | const TRTCStatistics & | Statistics of local and remote users. |
Overview
If you are familiar with audio/video terms, you can use this callback to get all technical metrics of the SDK. If you are developing an audio/video project for the first time, you can focus only on the onNetworkQuality
callback.
The callback is triggered once every 2 seconds.
The connection between SDK and server is closed.
void onConnectionLost()
The SDK tries to connect to the server again.
void onTryToReconnect()
The connection between SDK and server has been restored.
void onConnectionRecovery()
Callback of server speed test. SDK tests the speed of multiple server IPs, and the test result of each IP is returned through this callback notification.
void onSpeedTest(const TRTCSpeedTestResult & currentResult, uint32_t finishedCount, uint32_t totalCount)
Parameters
Parameter | Type | Description |
---|---|---|
currentResult | const TRTCSpeedTestResult & | Current speed test result. |
finishedCount | uint32_t | Number of servers on which speed test has been performed. |
totalCount | uint32_t | Total number of servers on which speed test needs to be performed. |
Camera is ready.
void onCameraDidReady()
Mic is ready.
void onMicDidReady()
Callback of volume level, including the volume level of each userId
and total remote volume level.
void onUserVoiceVolume(TRTCVolumeInfo * userVolumes, uint32_t userVolumesCount, uint32_t totalVolume)
Parameters
Parameter | Type | Description |
---|---|---|
userVolumes | TRTCVolumeInfo * | Volume level of all members who are speaking in the room. Value range: 0–100. |
userVolumesCount | uint32_t | Number of members in the room. |
totalVolume | uint32_t | Total volume level of all remote members. Value range: 0–100. |
Overview
The enableAudioVolumeEvaluation
API in TRTCCloud
can be used to enable this callback or set its triggering interval. It should be noted that after enableAudioVolumeEvaluation
is called to enable the volume level callback, no matter whether there is a user speaking in the channel, the callback will be called at the set time interval. If there is no one speaking, userVolumes
will be empty, and totalVolume
will be 0
.
If
userId
isnull
, it indicates the volume level of the local user.userVolumes
only includes the volume information of users who are speaking (i.e., volume level is not 0).
Callback of local device connection and disconnection.
void onDeviceChange(const char * deviceId, TRTCDeviceType type, TRTCDeviceState state)
Parameters
Parameter | Type | Description |
---|---|---|
deviceId | const char * | Device ID. |
type | TRTCDeviceType | Device type. |
state | TRTCDeviceState | Event type. |
Callback of mic volume level in test.
void onTestMicVolume(uint32_t volume)
Parameters
Parameter | Type | Description |
---|---|---|
volume | uint32_t | Volume level. Value range: 0–100. |
Overview
The mic test API startMicDeviceTest
will trigger this callback.
Callback of speaker volume level in test.
void onTestSpeakerVolume(uint32_t volume)
Parameters
Parameter | Type | Description |
---|---|---|
volume | uint32_t | Volume level. Value range: 0–100. |
Overview
The speaker test API startSpeakerDeviceTest
will trigger this callback.
Callback of receipt of a custom message.
void onRecvCustomCmdMsg(const char * userId, int32_t cmdID, uint32_t seq, const uint8_t * message, uint32_t messageSize)
Parameters
Parameter | Type | Description |
---|---|---|
userId | const char * | User ID. |
cmdID | int32_t | Command ID. |
seq | uint32_t | Message number. |
message | const uint8_t * | Message data. |
messageSize | uint32_t | Message data size. |
Overview
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
API.
Callback of loss of a custom message.
void onMissCustomCmdMsg(const char * userId, int32_t cmdID, int32_t errCode, int32_t missed)
Parameters
Parameter | Type | Description |
---|---|---|
userId | const char * | User ID. |
cmdID | int32_t | Command ID. |
errCode | int32_t | Error code. |
missed | int32_t | Number of lost messages. |
Overview
TRTC uses the UDP channel; therefore, even if reliable transmission is set, it cannot guarantee that no message will be lost; instead, it can only reduce the message loss rate to a very small value and meet general reliability requirements. After reliable transmission is set on the sender, the SDK will use this callback to notify of the number of custom messages lost during transmission in the specified past time period (usually 5s).
Only when reliable transmission is set on the sender can the receiver receive the callback of message loss.
Callback of receipt of an SEI message.
void onRecvSEIMsg(const char * userId, const uint8_t * message, uint32_t messageSize)
Parameters
Parameter | Type | Description |
---|---|---|
userId | const char * | User ID. |
message | const uint8_t * | Data. |
messageSize | uint32_t | Data size. |
Overview
When a user in a room uses sendSEIMsg
to send data, other users in the room can receive the data through the onRecvSEIMsg
API.
Callback of completion of starting relayed push to CDN.
void onStartPublishCDNStream(int errCode, const char * errMsg)
Overview
This callback corresponds to the startPublishCDNStream()
API in TRTCCloud
.
If
Start
callback is successful, the relayed push request has been successfully sent to Tencent Cloud. If the target CDN is exceptional, relayed push may fail.
Callback of completion of stopping relayed push to CDN.
void onStopPublishCDNStream(int errCode, const char * errMsg)
Overview
This callback corresponds to the stopPublishCDNStream()
API in TRTCCloud
.
Callback of setting On-Cloud MixTranscoding parameters. This callback corresponds to the setMixTranscodingConfig()
API in TRTCCloud
.
void onSetMixTranscodingConfig(int errCode, const char * errMsg)
Parameters
Parameter | Type | Description |
---|---|---|
errCode | int | 0: success; other values: failure. |
errMsg | const char * | Specific cause of error. |
Callback of ending an audio effect.
void onAudioEffectFinished(int effectId, int code)
Parameters
Parameter | Type | Description |
---|---|---|
effectId | int | - |
code | int | 0 indicates that the audio effect ended normally; other values indicate that the audio effect ended due to exceptions. |
This callback will be returned by the SDK when a window for screen sharing is covered and cannot be properly captured. It can be used to ask the user to move the covering window away.
void onScreenCaptureCovered()
This callback will be returned by the SDK when screen sharing is started.
void onScreenCaptureStarted()
This callback will be returned by the SDK when screen sharing is paused.
void onScreenCapturePaused(int reason)
Parameters
Parameter | Type | Description |
---|---|---|
reason | int | Reason for pause. 0: the user proactively paused screen sharing; 1: screen sharing parameters were being set; 2: the shared window was minimized; 3: the shared window was hidden. |
This callback will be returned by the SDK when screen sharing is resumed.
void onScreenCaptureResumed(int reason)
Parameters
Parameter | Type | Description |
---|---|---|
reason | int | Reason for resumption. 0: the user proactively resumed screen sharing; 1: screen sharing automatically resumed after the parameters were set; 2: the minimized shared window was restored; 3: the hidden shared window was restored. |
This callback will be returned by the SDK when screen sharing is stopped.
void onScreenCaptureStoped(int reason)
Parameters
Parameter | Type | Description |
---|---|---|
reason | int | Reason for stop. 0: the user proactively stopped screen sharing; 1: the shared window was closed. |
Playback of background music starts.
void onPlayBGMBegin(TXLiteAVError errCode)
Parameters
Parameter | Type | Description |
---|---|---|
errCode | TXLiteAVError | Error code. |
Progress of background music playback.
void onPlayBGMProgress(uint32_t progressMS, uint32_t durationMS)
Parameters
Parameter | Type | Description |
---|---|---|
progressMS | uint32_t | Elapsed time of the playback. |
durationMS | uint32_t | Total time. |
Playback of background music ends.
void onPlayBGMComplete(TXLiteAVError errCode)
Parameters
Parameter | Type | Description |
---|---|---|
errCode | TXLiteAVError | Error code. |
Feature
Callback of custom video rendering.
Callback of custom video rendering.
void onRenderVideoFrame(const char * userId, TRTCVideoStreamType streamType, TRTCVideoFrame * frame)
Parameters
Parameter | Type | Description |
---|---|---|
userId | const char * | User ID. |
streamType | TRTCVideoStreamType | Stream type, i.e., camera or screen sharing. |
frame | TRTCVideoFrame * | Video frame data. |
Overview
The setLocalVideoRenderCallback
and setRemoteVideoRenderCallback
APIs can be used to set the custom rendering callback.
Feature
Audio data callback.
Callback of audio data captured by local mic.
void onCapturedAudioFrame(TRTCAudioFrame * frame)
Parameters
Parameter | Type | Description |
---|---|---|
frame | TRTCAudioFrame * | Audio data. |
- Do not perform any time-consuming operation in this callback function. It is recommended to directly copy the data to another thread for processing; otherwise, various audio exceptions will occur.
- Audio data called back by this API can be modified.
- The frame time length of audio called back by this API is always 0.02s. The formula to convert the frame time length to frame byte length is sample rate * frame time length * number of audio channels * sampling point bit width. For example, the default audio recording format of the SDK has a sample rate of 48,000, mono channel, and sampling point bit width of 16, so its frame byte length will be 48,000 * 0.02s * 1 * 16 bit = 15,360 bit = 1,920 bytes.
- The audio data called back by this API includes pre-processing effects such as background music, audio effects, and audio reverb.
Audio data from each remote user before audio mixing (for example, if you want to convert the audio of a channel to text, you need to use the source data instead of the data after audio mixing).
void onPlayAudioFrame(TRTCAudioFrame * frame, const char * userId)
Parameters
Parameter | Type | Description |
---|---|---|
frame | TRTCAudioFrame * | Audio data. |
userId | const char * | User ID. |
- Do not perform any time-consuming operation in this callback function. It is recommended to directly copy the data to another thread for processing; otherwise, various audio exceptions will occur.
- Audio data called back by this API is read only and cannot be modified.
Audio data to be played back by speaker after audio data from each channel is mixed.
void onMixedPlayAudioFrame(TRTCAudioFrame * frame)
Parameters
Parameter | Type | Description |
---|---|---|
frame | TRTCAudioFrame * | Audio data. |
- Do not perform any time-consuming operation in this callback function. It is recommended to directly copy the data to another thread for processing; otherwise, various audio exceptions will occur.
- Audio data called back by this API can be modified.
- The frame time length of audio called back by this API is always 0.02s. The formula to convert the frame time length to frame byte length is sample rate * frame time length * number of audio channels * sampling point bit width. For example, the default audio playback format of the SDK has a sample rate of 48,000, dual channel, and sampling point bit width of 16, so its frame byte length will be 48,000 * 0.02s * 2 * 16 bit = 30,720 bit = 3,840 bytes.
- The audio data called back by this API is the mix of each channel's audio playback data and does not contain the audio data from in-ear monitoring.
Feature
Log callback.
Callback of log printing.
void onLog(const char * log, TRTCLogLevel level, const char * module)
Parameters
Parameter | Type | Description |
---|---|---|
log | const char * | Log content. |
level | TRTCLogLevel | Log level. For more information, please see TRTCLogLevel . |
module | const char * | Currently, this parameter has no meaning, and its value is always TXLiteAVSDK . |
Was this page helpful?