IRtcEngineEventHandler

onActiveSpeaker

Occurs when the most active remote speaker is detected.

onActiveSpeaker?(connection: RtcConnection, uid: number): void;

After successfully calling enableAudioVolumeIndication, the SDK continuously monitors the remote user with the highest volume and counts the number of times the user is identified as the loudest. The remote user with the highest count during a given period is considered the most active speaker. When there are two or more users in the channel and there is an active remote user, the SDK triggers this callback and reports the uid of the most active remote speaker.

If the most active speaker remains the same, the SDK does not trigger the onActiveSpeaker callback again.
If the most active speaker changes, the SDK triggers this callback again and reports the new uid.

Parameters

connection: Connection information. See RtcConnection.
uid: The ID of the most active remote speaker.

onAudioEffectFinished

Callback when the local audio effect file finishes playing.

onAudioEffectFinished?(soundId: number): void;

This callback is triggered when the audio effect finishes playing.

Parameters

soundId: The ID of the specified audio effect. Each audio effect has a unique ID.

onAudioMixingFinished

Occurs when the local music file playback ends.

onAudioMixingFinished?(): void;

Deprecated: Deprecated: Use onAudioMixingStateChanged instead.

This callback is triggered when playback of the local music file started by startAudioMixing ends. If startAudioMixing fails, it returns the error code WARN_AUDIO_MIXING_OPEN_ERROR.

onAudioMixingPositionChanged

Reports the playback progress of the music file.

onAudioMixingPositionChanged?(position: number): void;

After you call the startAudioMixing method to play a music file, the SDK triggers this callback every second to report the current playback progress.

Parameters

position: Current playback progress of the music file in ms.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

onAudioMixingStateChanged

Occurs when the playback state of the music file changes.

onAudioMixingStateChanged?(
    state: AudioMixingStateType,
    reason: AudioMixingReasonType
  ): void;

This callback is triggered when the playback state of the music file changes and reports the current playback state and error code.

Parameters

state: Playback state of the music file. See AudioMixingStateType.
reason: Error code. See AudioMixingReasonType.

onAudioPublishStateChanged

Callback for audio publish state changes.

onAudioPublishStateChanged?(
    channel: string,
    oldState: StreamPublishState,
    newState: StreamPublishState,
    elapseSinceLastState: number
  ): void;

Parameters

channel: Channel name.
oldState: Previous publish state. See StreamPublishState.
newState: Current publish state. See StreamPublishState.
elapseSinceLastState: Time interval between state changes (ms).

onAudioQuality

Reports the audio quality of a remote user.

onAudioQuality?(
    connection: RtcConnection,
    remoteUid: number,
    quality: QualityType,
    delay: number,
    lost: number
  ): void;

Deprecated: Deprecated: Use onRemoteAudioStats instead.

This callback reports the audio quality of a remote user during a call. It is triggered every 2 seconds for each remote user/host. If there are multiple remote users/hosts, the callback is triggered multiple times every 2 seconds.

Parameters

connection: Connection information. See RtcConnection.
remoteUid: The user ID of the sender of the audio stream.
quality: The audio quality. See QualityType.
delay: The delay (ms) from the sender to the receiver, including pre-processing, network transmission, and jitter buffer delay.
lost: The packet loss rate (%) from the sender to the receiver.

onAudioRoutingChanged

Callback when the audio route changes.

onAudioRoutingChanged?(routing: number): void;

Parameters

routing

The current audio route:

-1: Default audio route.
0: Headset with microphone.
1: Earpiece.
2: Headset without microphone.
3: Built-in speaker.
4: External speaker. (iOS and macOS only)
5: Bluetooth headset.

onAudioSubscribeStateChanged

Callback when the audio subscription state changes.

onAudioSubscribeStateChanged?(
    channel: string,
    uid: number,
    oldState: StreamSubscribeState,
    newState: StreamSubscribeState,
    elapseSinceLastState: number
  ): void;

Parameters

channel: Channel name.
uid: Remote user ID.
oldState: Previous subscription state. See StreamSubscribeState.
newState: Current subscription state. See StreamSubscribeState.
elapseSinceLastState: Time interval between two state changes (ms).

onAudioVolumeIndication

Occurs when the SDK reports the volume of users.

onAudioVolumeIndication?(
  connection: RtcConnection,
  speakers: AudioVolumeInfo[],
  speakerNumber: number,
  totalVolume: number
): void;

This callback is disabled by default. You can enable it by calling enableAudioVolumeIndication. Once enabled, as long as there are users publishing streams in the channel, the SDK triggers the onAudioVolumeIndication callback at the time interval set in enableAudioVolumeIndication after joining the channel. Two onAudioVolumeIndication callbacks are triggered each time: one reports the volume information of the local publishing user, and the other reports the volume information of the remote users (up to 3) with the highest instantaneous volume.

Note: After this feature is enabled, if a user mutes themselves (by calling muteLocalAudioStream), the SDK continues to report the local user's volume indication callback. If a remote user with the highest instantaneous volume mutes themselves, they will no longer be included in the remote volume indication callback after 20 seconds. If all remote users mute themselves, the SDK stops reporting remote volume indication callbacks after 20 seconds.

Parameters

connection

Connection information. See RtcConnection.

speakers

User volume information. See the AudioVolumeInfo array. If speakers is empty, it means no remote users are publishing streams or there are no remote users.

speakerNumber

Number of users.

In the local user's callback, as long as the local user is publishing, speakerNumber is always 1.
In the remote users' callback, the value range of speakerNumber is [0,3]. If there are more than 3 remote publishing users, speakerNumber is 3 in this callback.

totalVolume

Total mixed volume, range [0,255].

In the local user's callback, totalVolume is the volume of the local publishing user.
In the remote users' callback, totalVolume is the total mixed volume of the remote users (up to 3) with the highest instantaneous volume.

onCameraExposureAreaChanged

Callback when the camera exposure area changes.

onCameraExposureAreaChanged?(
    x: number,
    y: number,
    width: number,
    height: number
  ): void;

This callback is triggered when the local user calls the setCameraExposurePosition method to change the exposure position.

Note: This callback is applicable to Android and iOS only.

Parameters

x: The x-coordinate of the changed exposure area.
y: The y-coordinate of the changed exposure area.
width: The width of the changed exposure area.
height: The height of the changed exposure area.

onCameraFocusAreaChanged

Callback when the camera focus area changes.

onCameraFocusAreaChanged?(
    x: number,
    y: number,
    width: number,
    height: number
  ): void;

This callback is triggered when the local user calls the setCameraFocusPositionInPreview method to change the focus position.

Note: This callback is applicable to Android and iOS only.

Parameters

x: The x-coordinate of the changed focus area.
y: The y-coordinate of the changed focus area.
width: The width of the changed focus area.
height: The height of the changed focus area.

onCameraReady

Callback when the camera is ready.

onCameraReady?(): void;

Deprecated: Deprecated: Use onLocalVideoStateChanged with LocalVideoStreamStateCapturing(1) instead.

This callback indicates that the camera has been successfully opened and video capture can begin.

onChannelMediaRelayStateChanged

Occurs when the state of media stream relay across channels changes.

onChannelMediaRelayStateChanged?(
    state: ChannelMediaRelayState,
    code: ChannelMediaRelayError
  ): void;

Occurs when the state of media stream relay across channels changes. The SDK triggers this callback to report the current relay state and error information.

Parameters

state: The state of media stream relay across channels. See ChannelMediaRelayState.
code: The error code of the media stream relay across channels. See ChannelMediaRelayError.

onClientRoleChangeFailed

Occurs when the user role switch fails.

onClientRoleChangeFailed?(
    connection: RtcConnection,
    reason: ClientRoleChangeFailedReason,
    currentRole: ClientRoleType
  ): void;

When the user role switch fails, you can use this callback to learn the reason for the failure and the current user role.

Trigger Timing

This callback is triggered when the local user fails to switch roles by calling setClientRole after joining a channel.

Parameters

reason: The reason for the user role switch failure. See ClientRoleChangeFailedReason.
currentRole: The current user role. See ClientRoleType.
connection: The connection information. See RtcConnection.

onClientRoleChanged

Occurs when the user role or audience latency level is switched.

onClientRoleChanged?(
    connection: RtcConnection,
    oldRole: ClientRoleType,
    newRole: ClientRoleType
    newRoleOptions: ClientRoleOptions
  ): void;

Note: This callback is not triggered if you call setClientRole and set the user role to BROADCASTER before joining a channel.

Trigger Timing

This callback is triggered in either of the following cases:

After joining a channel, you call setClientRole to set the user role or audience latency level.
Before joining a channel, you call setClientRole and set the user role to AUDIENCE.

Parameters

connection: The connection information. See RtcConnection.
oldRole: The previous role: ClientRoleType.
newRole: The new role: ClientRoleType.
newRoleOptions: The properties of the new role. See ClientRoleOptions.

onConnectionBanned

Callback when the network connection is banned by the server.

onConnectionBanned?(connection: RtcConnection): void;

Deprecated: Deprecated: Use onConnectionStateChanged instead.

Parameters

connection: Connection information. See RtcConnection.

onConnectionInterrupted

Callback when the network connection is interrupted.

onConnectionInterrupted?(connection: RtcConnection): void;

Deprecated: Deprecated: Use onConnectionStateChanged instead.

This callback is triggered when the SDK loses connection to the server for more than 4 seconds after a connection has been established. After the event is triggered, the SDK will attempt to reconnect to the server, so this event can be used for UI prompts. The difference between this callback and onConnectionLost is:

onConnectionInterrupted is always triggered after successfully joining a channel and when the SDK has just lost connection to the server for more than 4 seconds.
onConnectionLost is triggered regardless of whether the channel is joined successfully, as long as the SDK cannot connect to the server within 10 seconds.

If the SDK fails to rejoin the channel within 20 minutes after disconnection, it will stop trying to reconnect.

Parameters

connection: Connection information. See RtcConnection.

onConnectionLost

Callback when the network connection is lost and the SDK cannot reconnect to the server within 10 seconds.

onConnectionLost?(connection: RtcConnection): void;

After calling joinChannel, this callback is triggered if the SDK fails to connect to the server within 10 seconds, regardless of whether the channel is joined successfully. If the SDK fails to rejoin the channel within 20 minutes after disconnection, it will stop trying to reconnect.

Parameters

connection: Connection information. See RtcConnection.

onConnectionStateChanged

Callback when the network connection state changes.

onConnectionStateChanged?(
    connection: RtcConnection,
    state: ConnectionStateType,
    reason: ConnectionChangedReasonType
  ): void;

This callback is triggered when the network connection state changes, informing you of the current state and the reason for the change.

Parameters

connection: Connection information. See RtcConnection.
state: Current network connection state. See ConnectionStateType.
reason: Reason for the current connection state change. See ConnectionChangedReasonType.

onEncryptionError

Callback when an error occurs with built-in encryption.

onEncryptionError?(
    connection: RtcConnection,
    errorType: EncryptionErrorType
  ): void;

After calling enableEncryption to enable encryption, if an error occurs in encryption or decryption on the sender or receiver side, the SDK triggers this callback.

Parameters

connection: Connection information. See RtcConnection.
errorType: Error type. See EncryptionErrorType.

onError

Occurs when an error is reported.

onError?(err: ErrorCodeType, msg: string): void;

This callback indicates that a network or media-related error occurred during SDK runtime. In most cases, errors reported by the SDK mean it cannot recover automatically and requires app intervention or user notification.

Parameters

err: The error code. See ErrorCodeType.
msg: The error description.

onExtensionErrorWithContext

Plugin error callback.

onExtensionErrorWithContext?(
    context: ExtensionContext,
    error: number,
    message: string
  ): void;

When plugin enabling fails or the plugin encounters a runtime error, the plugin triggers this callback and reports the error code and reason.

Parameters

context: Plugin context information. See ExtensionContext.
error: Error code. See the plugin documentation provided by the plugin provider.
message: Error reason. See the plugin documentation provided by the plugin provider.

onExtensionEventWithContext

Plugin event callback.

onExtensionEventWithContext?(
    context: ExtensionContext,
    key: string,
    value: string
  ): void;

To listen for plugin events, you need to register this callback.

Parameters

context: Plugin context information. See ExtensionContext.
key: The key of the plugin property.
value: The value corresponding to the plugin property key.

onExtensionStartedWithContext

Callback when the extension is successfully enabled.

onExtensionStartedWithContext?(context: ExtensionContext): void;

This callback is triggered after the extension is successfully enabled.

Parameters

context: Extension context information. See ExtensionContext.

onExtensionStoppedWithContext

Callback when the extension is disabled.

onExtensionStoppedWithContext?(context: ExtensionContext): void;

This callback is triggered after the extension is successfully disabled.

Parameters

context: Extension context information. See ExtensionContext.

onFacePositionChanged

Reports local face detection results.

onFacePositionChanged?(
    imageWidth: number,
    imageHeight: number,
    vecRectangle: Rectangle,
    vecDistance: number,
    numFaces: number
  ): void;

After calling enableFaceDetection(true) to enable local face detection, you can use this callback to get the following face detection information in real time:

Size of the captured image
Position of the face in the view
Distance of the face from the device screen

The distance of the face from the screen is estimated by the SDK based on the image size and face position in the view.

Note:

When the face in front of the camera disappears, this callback is triggered immediately; when no face is detected, the callback frequency is reduced to save power.
This callback is not triggered when the face is too close to the screen.

Parameters

imageWidth: Width (px) of the captured image.
imageHeight: Height (px) of the captured image.
vecRectangle: Detected face information. See Rectangle.
vecDistance: Distance between the face and the device screen (cm).
numFaces: Number of faces detected. If 0, no face is detected.

onFirstLocalAudioFramePublished

Occurs when the first local audio frame is published.

onFirstLocalAudioFramePublished?(
    connection: RtcConnection,
    elapsed: number
  ): void;

The SDK triggers this callback in the following scenarios:

After successfully joining a channel by calling joinChannel with local audio enabled.
After calling muteLocalAudioStream(true) and then muteLocalAudioStream(false).
After calling disableAudio and then enableAudio.

Parameters

connection: Connection information. See RtcConnection.
elapsed: Time elapsed (ms) from calling joinChannel until this callback is triggered.

onFirstLocalVideoFrame

Callback when the first local video frame is rendered.

onFirstLocalVideoFrame?(
    source: VideoSourceType,
    width: number,
    height: number,
    elapsed: number
  ): void;

This callback is triggered when the first local video frame is displayed in the local view.

Parameters

source: The type of video source. See VideoSourceType.
width: Width (px) of the locally rendered video.
height: Height (px) of the locally rendered video.
elapsed: Time elapsed in milliseconds from calling joinChannel to this event. If startPreviewWithoutSourceType/startPreview was called before joining the channel, this parameter indicates the time from calling startPreviewWithoutSourceType or startPreview to this event.

onFirstLocalVideoFramePublished

Callback when the first local video frame is published.

onFirstLocalVideoFramePublished?(
    connection: RtcConnection,
    elapsed: number
  ): void;

The SDK triggers this callback in the following scenarios:

After successfully joining a channel with the local video module enabled.
After calling muteLocalVideoStream(true) and then muteLocalVideoStream(false).
After calling disableVideo and then enableVideo.

Parameters

connection: Connection information. See RtcConnection.
elapsed: Time interval in milliseconds from calling joinChannel to triggering this callback.

onFirstRemoteAudioDecoded

Occurs when the first remote audio frame is decoded.

onFirstRemoteAudioDecoded?(
    connection: RtcConnection,
    uid: number,
    elapsed: number
  ): void;

Deprecated: Deprecated: Use onRemoteAudioStateChanged instead.

The SDK triggers this callback in the following scenarios:

When the remote user sends audio after joining the channel for the first time.
When the remote user goes offline and then comes back online to send audio. Offline means no audio packet is received locally within 15 seconds, which may be due to:
- The remote user leaving the channel
- The remote user disconnecting
- The remote user calling muteLocalAudioStream to stop sending audio
- The remote user calling disableAudio to disable audio

Parameters

connection: Connection information. See RtcConnection.
uid: Remote user ID.
elapsed: Time elapsed (ms) from the local user calling joinChannel until this callback is triggered.

onFirstRemoteAudioFrame

Occurs when the first remote audio frame is received.

onFirstRemoteAudioFrame?(
    connection: RtcConnection,
    userId: number,
    elapsed: number
  ): void;

Deprecated: Deprecated: Use onRemoteAudioStateChanged instead.

Parameters

connection: Connection information. See RtcConnection.
userId: User ID of the remote user who sent the audio frame.
elapsed: Time elapsed (ms) from the local user calling joinChannel until this callback is triggered.

onFirstRemoteVideoDecoded

Callback when the first remote video frame is received and decoded.

onFirstRemoteVideoDecoded?(
    connection: RtcConnection,
    remoteUid: number,
    width: number,
    height: number,
    elapsed: number
  ): void;

The SDK triggers this callback in the following scenarios:

When the remote user sends video after joining the channel for the first time.
When the remote user sends video again after going offline and coming back online. Possible reasons for interruption include:
- The remote user leaves the channel.
- The remote user is disconnected.
- The remote user calls disableVideo to turn off the video module.

Parameters

connection: Connection information. See RtcConnection.
remoteUid: User ID specifying which user's video stream it is.
width: Width (px) of the video stream.
height: Height (px) of the video stream.
elapsed: Delay in milliseconds from calling joinChannel locally to triggering this callback.

onFirstRemoteVideoFrame

Callback when the renderer receives the first remote video frame.

onFirstRemoteVideoFrame?(
    connection: RtcConnection,
    remoteUid: number,
    width: number,
    height: number,
    elapsed: number
  ): void;

Note: This callback is only triggered when SDK rendering is used; if custom video rendering is used, this callback will not be triggered and you need to implement it outside the SDK.

Parameters

remoteUid: User ID specifying which user's video stream it is.
connection: Connection information. See RtcConnection.
width: Width (px) of the video stream.
height: Height (px) of the video stream.
elapsed: Time elapsed in milliseconds from calling joinChannel locally to this event.

onJoinChannelSuccess

Occurs when a user joins a channel successfully.

onJoinChannelSuccess?(connection: RtcConnection, elapsed: number): void;

This callback indicates that the client successfully joined the specified channel.

Trigger Timing

This callback is triggered when you successfully join a channel by calling joinChannel, joinChannelWithUserAccount, joinChannelEx, or joinChannelWithUserAccountEx.

Parameters

connection: The connection information. See RtcConnection.
elapsed: The time elapsed (ms) from calling joinChannel until this event occurs.

onLastmileProbeResult

Callback for the last mile uplink and downlink quality probe result before a call.

onLastmileProbeResult?(result: LastmileProbeResult): void;

After calling startLastmileProbeTest, the SDK returns this callback within approximately 30 seconds.

Parameters

result: Last mile uplink and downlink quality probe result. See LastmileProbeResult.

onLastmileQuality

Callback for the last mile network quality report.

onLastmileQuality?(quality: QualityType): void;

This callback describes the result of the last mile network probe for the local user before joining a channel. Last mile refers to the network status from the device to the Agora edge server. Before joining a channel, after calling startLastmileProbeTest, the SDK triggers this callback to report the result of the local user's last mile network probe.

Parameters

quality: Last mile network quality. See QualityType.

onLeaveChannel

Occurs when a user leaves the channel.

onLeaveChannel?(connection: RtcConnection, stats: RtcStats): void;

You can use this callback to get information such as the total call duration and the amount of data sent and received by the SDK during the call.

Trigger Timing

This callback is triggered after you successfully call leaveChannel or leaveChannelEx to leave the channel.

Parameters

connection: Connection information. See RtcConnection.
stats: Call statistics. See RtcStats.

onLocalAudioStateChanged

Occurs when the local audio state changes.

onLocalAudioStateChanged?(
    connection: RtcConnection,
    state: LocalAudioStreamState,
    reason: LocalAudioStreamReason
  ): void;

This callback is triggered when the local audio state changes, including changes in microphone capture and audio encoding. When local audio experiences issues, this callback helps you understand the current audio state and the cause of the issue, making it easier to troubleshoot.

Note: When the state is LocalAudioStreamStateFailed (3), you can check the error information in the error parameter.

Parameters

connection: Connection information. See RtcConnection.
state: Current local audio state. See LocalAudioStreamState.
reason: Reason for the local audio state change. See LocalAudioStreamReason.

onLocalAudioStats

Reports the statistics of the local audio stream during a call.

onLocalAudioStats?(connection: RtcConnection, stats: LocalAudioStats): void;

The SDK triggers this callback every 2 seconds.

Parameters

connection: Connection information. See RtcConnection.
stats: Local audio statistics. See LocalAudioStats.

onLocalUserRegistered

Occurs when the local user successfully registers a User Account.

onLocalUserRegistered?(uid: number, userAccount: string): void;

After the local user successfully calls registerLocalUserAccount to register a User Account or calls joinChannelWithUserAccount to join a channel, the SDK triggers this callback and reports the local user's UID and User Account.

Parameters

uid: The ID of the local user.
userAccount: The User Account of the local user.

onLocalVideoEvent

Callback triggered when a local video event occurs.

onLocalVideoEvent?(source: VideoSourceType, event: LocalVideoEventType): void;

Since: Available since v4.6.1.

You can use this callback to get the reason for the local video event.

Parameters

source: Type of video source. See VideoSourceType.
event: Type of local video event. See LocalVideoEventType.

onLocalVideoStateChanged

Callback when the local video state changes.

onLocalVideoStateChanged?(
    source: VideoSourceType,
    state: LocalVideoStreamState,
    reason: LocalVideoStreamReason
  ): void;

This callback is triggered by the SDK when the state of the local video changes, reporting the current state and the reason for the change.

Note:

Frame duplication detection only applies to video frames with resolution greater than 200 × 200, frame rate ≥ 10 fps, and bitrate less than 20 Kbps.
If an exception occurs during video capture, you can usually troubleshoot the issue using the reason parameter in this callback. However, on some devices, when capture issues occur (e.g., freezing), Android may not throw any error callbacks, so the SDK cannot report the reason for the local video state change. In this case, you can determine whether there are no captured frames by checking if this callback reports state as LocalVideoStreamStateCapturing or LocalVideoStreamStateEncoding, and the captureFrameRate in the onLocalVideoStats callback is 0.

Trigger Timing

The SDK triggers this callback with state as LocalVideoStreamStateFailed and reason as LocalVideoStreamReasonCaptureFailure in the following situations:
- The app goes to the background and the system reclaims the camera.
- On Android 9 and above, when the app stays in the background for a while, the system revokes camera permission.
- On Android 6 and above, if the camera is occupied by a third-party app for a while and then released, the SDK triggers this callback and reports onLocalVideoStateChanged(LocalVideoStreamStateCapturing, LocalVideoStreamReasonOk).
- The camera starts normally, but no captured video is output for 4 consecutive seconds.
When the camera outputs captured video frames, if the SDK detects 15 consecutive duplicate frames, it triggers this callback with state as LocalVideoStreamStateCapturing and reason as LocalVideoStreamReasonCaptureFailure.

Parameters

source: Type of video source. See VideoSourceType.
state: Local video state. See LocalVideoStreamState.
reason: Reason for the local video state change. See LocalVideoStreamReason.

onLocalVideoStats

Callback for local video stream statistics.

onLocalVideoStats?(connection: RtcConnection, stats: LocalVideoStats): void;

This callback describes statistics of the video stream sent by the local device. It is triggered every 2 seconds.

Parameters

connection: Connection information. See RtcConnection.
stats: Local video stream statistics. See LocalVideoStats.

onLocalVideoTranscoderError

Callback when a local video compositing error occurs.

onLocalVideoTranscoderError?(
    stream: TranscodingVideoStream,
    error: VideoTranscoderError
  ): void;

This callback is triggered by the SDK when startLocalVideoTranscoder or updateLocalTranscoderConfiguration fails, reporting the reason for the compositing failure.

Parameters

stream: The video stream that failed to composite. See TranscodingVideoStream.
error: The reason for the local video compositing error. See VideoTranscoderError.

onMultipathStats

Callback for multipath transmission statistics.

onMultipathStats?(connection: RtcConnection, stats: MultipathStats): void;

Since: Added since v4.6.2.

Trigger Timing

This callback is triggered after you set enableMultipath to true to enable multipath transmission.

Parameters

stats: Multipath transmission statistics. See MultipathStats.

onNetworkQuality

Callback for the last mile uplink and downlink network quality report of each user during a call.

onNetworkQuality?(
    connection: RtcConnection,
    remoteUid: number,
    txQuality: QualityType,
    rxQuality: QualityType
  ): void;

This callback describes the last mile network status of each user during a call, where the last mile refers to the network status from the device to the Agora edge server. This callback is triggered every 2 seconds. If there are multiple remote users, it will be triggered multiple times every 2 seconds. This callback reports network quality through broadcast packets in the channel. Excessive broadcast packets may cause a broadcast storm. To prevent a broadcast storm from causing large data transmission in the channel, this callback supports reporting the network quality of up to 4 remote hosts simultaneously by default.

Note: When the user does not send streams, txQuality is Unknown; when the user does not receive streams, rxQuality is Unknown.

Parameters

connection: Connection information. See RtcConnection.
remoteUid: User ID. Indicates the network quality of the user with this ID reported by the callback. If the uid is 0, it returns the network quality of the local user.
txQuality: The user's uplink network quality, calculated based on the sending bitrate, uplink packet loss rate, average round-trip time, and network jitter. This value represents the current uplink network quality and helps determine whether the current video encoding settings can be supported. For example, if the uplink bitrate is 1000 Kbps, it can support a resolution of 640 × 480 and frame rate of 15 fps in a live broadcast scenario, but may struggle to support 1280 × 720 resolution.
rxQuality: The user's downlink network quality, calculated based on the downlink packet loss rate, average round-trip time, and network jitter.

onNetworkTypeChanged

Callback when the local network type changes.

onNetworkTypeChanged?(connection: RtcConnection, type: NetworkType): void;

When the local network connection type changes, the SDK triggers this callback and specifies the current network connection type in the callback. You can use this callback to get the network type being used. When the connection is interrupted, this callback can help identify whether the interruption is due to a network switch or poor network conditions.

Parameters

connection: Connection information. See RtcConnection.
type: Local network connection type. See NetworkType.

onPermissionError

Callback when failing to obtain device permissions.

onPermissionError?(permissionType: PermissionType): void;

When the SDK fails to obtain device permissions, it triggers this callback to report which device permission could not be obtained.

Parameters

permissionType: Device permission type. See PermissionType.

onPermissionGranted

Callback when permission is granted.

onPermissionGranted?(permissionType: PermissionType): void;

Parameters

permissionType: Type of permission. See PermissionType.

onProxyConnected

Callback for proxy connection status.

onProxyConnected?(
    channel: string,
    uid: number,
    proxyType: ProxyType,
    localProxyIp: string,
    elapsed: number
  ): void;

You can use this callback to listen for the SDK's proxy connection status. For example, when a user calls setCloudProxy to set a proxy and successfully joins a channel, the SDK triggers this callback to report the user ID, type of connected proxy, and the time elapsed from calling joinChannel to triggering this callback.

Parameters

channel: Channel name.
uid: User ID
proxyType: Type of connected proxy. See ProxyType.
localProxyIp: Reserved parameter, not supported yet.
elapsed: Time elapsed (in milliseconds) from calling joinChannel to the SDK triggering this callback.

onRejoinChannelSuccess

Occurs when the user successfully rejoins the channel.

onRejoinChannelSuccess?(connection: RtcConnection, elapsed: number): void;

Trigger Timing

Due to network issues, the client may lose connection with the server. The SDK will attempt to reconnect automatically. This callback is triggered when the reconnection succeeds.

Parameters

connection: Connection information. See RtcConnection.
elapsed: Time elapsed (ms) from calling joinChannel to the triggering of this callback.

onRemoteAudioStateChanged

Occurs when the state of the remote audio stream changes.

onRemoteAudioStateChanged?(
    connection: RtcConnection,
    remoteUid: number,
    state: RemoteAudioState,
    reason: RemoteAudioStateReason,
    elapsed: number
  ): void;

Occurs when the audio state of a remote user (in the Communication profile) or host (in the Live Broadcast profile) changes. The SDK reports the current state of the remote audio stream to the local user through this callback.

Note: This callback may be inaccurate when the number of users (in the Communication profile) or hosts (in the Live Broadcast profile) in the channel exceeds 32.

Parameters

connection: Connection information. See RtcConnection.
remoteUid: The ID of the remote user whose audio state has changed.
state: The state of the remote audio stream. See RemoteAudioState.
reason: The reason for the remote audio state change. See RemoteAudioStateReason.
elapsed: The time elapsed (ms) from the local user calling joinChannel until this event occurs.

onRemoteAudioStats

Reports the statistics of the audio stream sent by each remote user during a call.

onRemoteAudioStats?(connection: RtcConnection, stats: RemoteAudioStats): void;

This callback is triggered every 2 seconds for each remote user/host who is sending an audio stream. If multiple remote users/hosts are sending audio streams, this callback is triggered multiple times every 2 seconds.

Parameters

connection: Connection information. See RtcConnection.
stats: The statistics of the received remote audio stream. See RemoteAudioStats.

onRemoteAudioTransportStats

Reports the transport statistics of the audio stream sent by each remote user during a call.

onRemoteAudioTransportStats?(
    connection: RtcConnection,
    remoteUid: number,
    delay: number,
    lost: number,
    rxKBitRate: number
  ): void;

Deprecated: Use onRemoteAudioStats instead. This callback reports the end-to-end network statistics of the remote user during a call, calculated based on audio packets. It reflects the current network status using objective data such as packet loss and network delay. During a call, when a user receives audio packets sent by a remote user/host, this callback is triggered every 2 seconds.

Parameters

connection: Connection information. See RtcConnection.
remoteUid: The user ID that identifies which user/host's audio packet it is.
delay: The delay (ms) from the sender to the receiver of the audio packet.
lost: The packet loss rate (%) from sender to receiver of the audio packet.
rxKBitrate: The received bitrate (Kbps) of the remote audio packet.

onRemoteSubscribeFallbackToAudioOnly

Callback when the subscribed stream falls back to audio-only or recovers to audio and video.

onRemoteSubscribeFallbackToAudioOnly?(
    uid: number,
    isFallbackOrRecover: boolean
  ): void;

When you call setRemoteSubscribeFallbackOption and set option to StreamFallbackOptionAudioOnly, this callback is triggered in the following situations:

The downlink network condition is poor, and the subscribed audio and video stream falls back to audio-only.
The downlink network condition improves, and the subscribed audio-only stream recovers to audio and video.

Note: When the subscribed stream falls back to a lower-quality video stream due to poor network conditions, you can monitor the switch between high and low video streams through the onRemoteVideoStats callback.

Parameters

uid

Remote user's user ID.

isFallbackOrRecover

true: Due to poor network conditions, the subscribed stream has fallen back to audio-only.
false: Due to improved network conditions, the subscribed stream has recovered to audio and video.

onRemoteVideoStateChanged

Callback when the remote video state changes.

onRemoteVideoStateChanged?(
    connection: RtcConnection,
    remoteUid: number,
    state: RemoteVideoState,
    reason: RemoteVideoStateReason,
    elapsed: number
  ): void;

Note: When the number of users (in communication) or hosts (in live broadcast) in the channel exceeds 32, this callback may be inaccurate.

Parameters

connection: Connection information. See RtcConnection.
remoteUid: Remote user ID whose video state changed.
state: Remote video stream state. See RemoteVideoState.
reason: Specific reason for the remote video stream state change. See RemoteVideoStateReason.
elapsed: Time elapsed (in ms) from the local user calling joinChannel to this event.

onRemoteVideoStats

Callback for remote video stream statistics during a call.

onRemoteVideoStats?(connection: RtcConnection, stats: RemoteVideoStats): void;

This callback describes end-to-end video stream statistics of remote users during a call. It is triggered every 2 seconds for each remote user/host. If there are multiple remote users/hosts, this callback is triggered multiple times every 2 seconds.

Parameters

connection: Connection information. See RtcConnection.
stats: Remote video statistics. See RemoteVideoStats.

onRemoteVideoTransportStats

Callback for remote video stream transport statistics during a call.

onRemoteVideoTransportStats?(
    connection: RtcConnection,
    remoteUid: number,
    delay: number,
    lost: number,
    rxKBitRate: number
  ): void;

Deprecated: Deprecated: This callback has been deprecated. Use onRemoteVideoStats instead.

This callback describes end-to-end network statistics of remote users during a call based on video packets. It uses objective data such as packet loss and network delay to reflect the current network status. During a call, once the user receives video data packets from a remote user/host, this callback is triggered every 2 seconds.

Parameters

connection: Connection information. See RtcConnection.
remoteUid: User ID indicating which user/host the video packet belongs to.
delay: Delay (ms) from sender to receiver for the video packet.
lost: Packet loss rate (%) from sender to receiver for the video packet.
rxKBitRate: Receiving bitrate (Kbps) of the remote video packet.

onRenewTokenResult

Callback for the result of calling the renewToken method.

onRenewTokenResult?(connection: RtcConnection, token: string, code: RenewTokenErrorCode): void;

Since: Added since v4.6.2.

This callback is triggered after you call the renewToken method to update the token, to notify the update result.

Parameters

token: The updated token.
code: Error code. See RenewTokenErrorCode.

onRequestToken

Occurs when the token has expired.

onRequestToken?(connection: RtcConnection): void;

During an audio or video call, if the token becomes invalid, the SDK triggers this callback to report that the token has expired. When you receive this callback, you need to generate a new token on your server and update it using one of the following methods:

Single-channel scenario:
- Call renewToken to pass in the new token.
- Call leaveChannel to leave the current channel, then call joinChannel with the new token to rejoin the channel.
Multi-channel scenario: Call updateChannelMediaOptionsEx with the new token.

Parameters

connection: Connection information. See RtcConnection.

onRhythmPlayerStateChanged

Occurs when the state of the virtual metronome changes.

onRhythmPlayerStateChanged?(
    state: RhythmPlayerStateType,
    reason: RhythmPlayerReason
  ): void;

Deprecated: Deprecated since v4.6.2.

This callback is triggered when the state of the virtual metronome changes. When the virtual metronome encounters an issue, this callback helps you understand its current state and the reason for the failure, which facilitates troubleshooting.

Parameters

state: The current state of the virtual metronome. See RhythmPlayerStateType.
reason: The error code and message when the virtual metronome encounters an error. See RhythmPlayerReason.

onRtcStats

Reports the statistics of the current call.

onRtcStats?(connection: RtcConnection, stats: RtcStats): void;

Trigger Timing

The SDK periodically reports the statistics of the current call to the app, triggered every two seconds.

Parameters

connection: Connection information. See RtcConnection.
stats: RTC engine statistics. See RtcStats.

onRtmpStreamingEvent

Callback for CDN streaming events.

onRtmpStreamingEvent?(url: string, eventCode: RtmpStreamingEvent): void;

Parameters

url: The CDN streaming URL.
eventCode: The CDN streaming event code. See RtmpStreamingEvent.

onRtmpStreamingStateChanged

Callback when the RTMP streaming state changes.

onRtmpStreamingStateChanged?(
    url: string,
    state: RtmpStreamPublishState,
    reason: RtmpStreamPublishReason
  ): void;

When the RTMP streaming state changes, the SDK triggers this callback and provides the URL where the change occurred and the current streaming state. This callback helps streaming users understand the current streaming status. If an error occurs during streaming, you can use the returned error code to identify the cause and troubleshoot accordingly.

Parameters

url: The URL where the streaming state changed.
state: The current streaming state. See RtmpStreamPublishState.
reason: The reason for the change in streaming state. See RtmpStreamPublishReason.

onSnapshotTaken

Callback for snapshot result.

onSnapshotTaken?(
    connection: RtcConnection,
    uid: number,
    filePath: string,
    width: number,
    height: number,
    errCode: number
  ): void;

After calling takeSnapshot successfully, the SDK triggers this callback to report whether the snapshot was successful and provide details.

Parameters

uid

User ID. If uid is 0, it indicates the local user.

connection

Connection information. See RtcConnection.

filePath

Local path where the snapshot is saved.

width

Image width (px).

height

Image height (px).

errCode

Indicates success or reason for failure.

0: Snapshot succeeded.
< 0: Snapshot failed.
- -1: Failed to write file or JPEG encoding failed.
- -2: No video frame from the specified user within 1 second after calling takeSnapshot. Possible causes: local capture stopped, remote user stopped publishing, or video processing is blocked.
- -3: takeSnapshot is called too frequently.

onStreamMessage

Callback when receiving a data stream message from a remote user.

onStreamMessage?(
    connection: RtcConnection,
    remoteUid: number,
    streamId: number,
    data: Uint8Array,
    length: number,
    sentTs: number
  ): void;

This callback indicates that the local user has received a stream message sent by a remote user using the sendStreamMessage method.

Parameters

connection: Connection information. See RtcConnection.
remoteUid: User ID of the sender.
streamId: Stream ID of the received message.
data: Received data.
length: Length of the data in bytes.
sentTs: Timestamp when the data stream was sent.

onStreamMessageError

Callback when an error occurs while receiving a data stream message from a remote user.

onStreamMessageError?(
    connection: RtcConnection,
    remoteUid: number,
    streamId: number,
    code: ErrorCodeType,
    missed: number,
    cached: number
  ): void;

This callback indicates that the local user failed to receive a stream message sent by a remote user using the sendStreamMessage method.

Parameters

connection: Connection information. See RtcConnection.
remoteUid: User ID of the sender.
streamId: Stream ID of the received message.
code: Error code. See ErrorCodeType.
missed: Number of missed messages.
cached: Number of messages cached after the data stream was interrupted.

onTokenPrivilegeWillExpire

Occurs when the token is about to expire in 30 seconds.

onTokenPrivilegeWillExpire?(connection: RtcConnection, token: string): void;

When you receive this callback, you need to generate a new token on your server and update it using one of the following methods:

Single-channel scenario:
- Call renewToken to pass in the new token.
- Call leaveChannel to leave the current channel, then call joinChannel with the new token to rejoin the channel.
Multi-channel scenario: Call updateChannelMediaOptionsEx with the new token.

Trigger Timing

During an audio or video call, the SDK triggers this callback 30 seconds before the token expires to remind the app to update the token.

Parameters

connection: Connection information. See RtcConnection.
token: The token that is about to expire.

onTranscodedStreamLayoutInfo

Callback for received mixed video stream with layout information.

onTranscodedStreamLayoutInfo?(
    connection: RtcConnection,
    uid: number,
    width: number,
    height: number,
    layoutCount: number,
    layoutlist: VideoLayout[]
  ): void;

When the mixed video stream is received from the mixing server for the first time, or when the layout information of the mixed stream changes, the SDK triggers this callback to report the layout information of each sub-stream in the mixed video stream.

Parameters

connection: Connection information. See RtcConnection.
uid: User ID of the publisher of the mixed video stream.
width: Width (px) of the mixed video stream.
height: Height (px) of the mixed video stream.
layoutCount: Number of layout entries in the mixed video stream.
layoutlist: Detailed layout information of a mixed video stream. See VideoLayout.

onTranscodingUpdated

Callback when the RTMP transcoding settings are updated.

onTranscodingUpdated?(): void;

When the LiveTranscoding parameters in the startRtmpStreamWithTranscoding method are updated, the onTranscodingUpdated callback is triggered to notify the host of the update.

Note: This callback is not triggered the first time you set the transcoding parameters LiveTranscoding using the startRtmpStreamWithTranscoding method.

onUplinkNetworkInfoUpdated

Callback when uplink network information changes.

onUplinkNetworkInfoUpdated?(info: UplinkNetworkInfo): void;

The SDK triggers this callback only when uplink network information changes.

Note: This callback is applicable only in scenarios where H.264 format external encoded video data is pushed to the SDK.

Parameters

info: Uplink network information. See UplinkNetworkInfo.

onUserEnableLocalVideo

Callback when a remote user enables/disables local video capture.

onUserEnableLocalVideo?(
    connection: RtcConnection,
    remoteUid: number,
    enabled: boolean
  ): void;

Deprecated

Deprecated: This callback has been deprecated. Use the following enumerations in the onRemoteVideoStateChanged callback instead:

RemoteVideoStateStopped(0) and RemoteVideoStateReasonRemoteMuted(5).
RemoteVideoStateDecoding (2) and RemoteVideoStateReasonRemoteUnmuted(6).

This callback is triggered when a remote user calls the enableLocalVideo method to enable or disable video capture.

Parameters

connection

Connection information. See RtcConnection.

remoteUid

User ID indicating whose video stream it is.

enabled

Whether the remote user has enabled video capture:

true: The user has enabled video. Other users can receive this user's video stream.
false: The user has disabled video. The user can still receive video streams from others, but others cannot receive this user's video stream.

onUserEnableVideo

Occurs when a remote user enables or disables the video module.

onUserEnableVideo?(
    connection: RtcConnection,
    remoteUid: number,
    enabled: boolean
  ): void;

Disabling the video function means the user can only make voice calls, cannot display or send their own video, and cannot receive or display others' video. This callback is triggered when a remote user calls the enableVideo or disableVideo method to enable or disable the video module.

Parameters

connection

Connection information. See RtcConnection.

remoteUid

The user ID indicating whose video stream is affected.

enabled

true: The user has enabled the video function.
false: The user has disabled the video function.

onUserInfoUpdated

Occurs when the remote user's information is updated.

onUserInfoUpdated?(uid: number, info: UserInfo): void;

After a remote user joins the channel, the SDK obtains the user's UID and User Account, caches a mapping table containing the UID and User Account, and triggers this callback locally.

Parameters

uid: The ID of the remote user.
info: The UserInfo object that identifies the user's information, including the UID and User Account. See the UserInfo class.

onUserJoined

Occurs when a remote user (in Communication) or host (in Live Broadcast) joins the current channel.

onUserJoined?(
    connection: RtcConnection,
    remoteUid: number,
    elapsed: number
  ): void;

In the Communication profile, this callback indicates that a remote user has joined the channel. If other users are already in the channel when the user joins, the new user also receives callbacks for those existing users.
In the Live Broadcast profile, this callback indicates that a host has joined the channel. If other hosts are already in the channel, the new host also receives callbacks for those existing hosts. It is recommended to limit the number of hosts in a call to 32 (no more than 17 with video).

Trigger Timing

This callback is triggered in the following scenarios:

A remote user/host joins the channel.
A remote user changes their role to host after joining the channel.
A remote user/host rejoins the channel after a network interruption.

Parameters

connection: Connection information. See RtcConnection.
remoteUid: The ID of the remote user/host who just joined the channel.
elapsed: The time delay (ms) from the local user calling joinChannel to the triggering of this callback.

onUserMuteAudio

Occurs when a remote user (in the Communication profile) or host (in the Live Broadcast profile) stops or resumes sending audio streams.

onUserMuteAudio?(
    connection: RtcConnection,
    remoteUid: number,
    muted: boolean
  ): void;

This callback is triggered when a remote user calls muteLocalAudioStream to stop or resume sending audio.

Note: This callback may be inaccurate when the number of users (in the Communication profile) or hosts (in the Live Broadcast profile) in the channel exceeds 32.

Parameters

connection

Connection information. See RtcConnection.

remoteUid

User ID.

muted

Whether the user is muted:

true: The user has muted the audio.
false: The user has unmuted the audio.

onUserMuteVideo

Occurs when a remote user stops or resumes publishing the video stream.

onUserMuteVideo?(
    connection: RtcConnection,
    remoteUid: number,
    muted: boolean
  ): void;

This callback is triggered when a remote user calls muteLocalVideoStream to stop or resume publishing the video stream. The SDK reports the remote user's stream publishing status to the local user.

Note: When the number of users (in communication scenario) or hosts (in live streaming scenario) in the channel exceeds 32, this callback may be inaccurate.

Parameters

connection

Connection information. See RtcConnection.

remoteUid

Remote user ID.

muted

Whether the remote user stops publishing the video stream:

true: Stops publishing the video stream.
false: Publishes the video stream.

onUserOffline

Callback when a remote user (in communication) or host (in live streaming) leaves the current channel.

onUserOffline?(
    connection: RtcConnection,
    remoteUid: number,
    reason: UserOfflineReasonType
  ): void;

Users may leave the channel for the following reasons:

Normal leave: The remote user or host sends a 'goodbye'-like message and actively leaves the channel.
Timeout disconnection: If no data packet is received from the other party within a certain period (20 seconds in communication, slightly delayed in live streaming), the user is considered disconnected. In poor network conditions, false reports may occur. It is recommended to use the RTM SDK for reliable disconnection detection.

Trigger Timing

This callback is triggered when a remote user or host leaves the current channel during an audio/video interaction.

Parameters

connection: Connection information. See RtcConnection.
remoteUid: ID of the remote user or host who went offline.
reason: Reason why the remote user (in communication) or host (in live streaming) went offline. See UserOfflineReasonType.

onVideoPublishStateChanged

Occurs when the video publishing state changes.

onVideoPublishStateChanged?(
    source: VideoSourceType,
    channel: string,
    oldState: StreamPublishState,
    newState: StreamPublishState,
    elapseSinceLastState: number
  ): void;

Parameters

channel: Channel name.
source: Type of video source. See VideoSourceType.
oldState: Previous publishing state. See StreamPublishState.
newState: Current publishing state. See StreamPublishState.
elapseSinceLastState: Time interval between the two state changes (ms).

onVideoRenderingTracingResult

Callback for video frame rendering events.

onVideoRenderingTracingResult?(
    connection: RtcConnection,
    uid: number,
    currentEvent: MediaTraceEvent,
    tracingInfo: VideoRenderingTracingInfo
  ): void;

After calling the startMediaRenderingTracing method or joining a channel, the SDK triggers this callback to report video frame rendering events and metrics during the rendering process. Developers can optimize based on these metrics to improve rendering efficiency.

Parameters

connection: Connection information. See RtcConnection.
uid: User ID.
currentEvent: Current video frame rendering event. See MediaTraceEvent.
tracingInfo: Metrics during the video frame rendering process. Developers should minimize the metric values to improve rendering efficiency. See VideoRenderingTracingInfo.

onVideoSizeChanged

Occurs when the size or rotation of the local or remote video changes.

onVideoSizeChanged?(
    connection: RtcConnection,
    sourceType: VideoSourceType,
    uid: number,
    width: number,
    height: number,
    rotation: number
  ): void;

Parameters

connection: Connection information. See RtcConnection.
sourceType: Type of video source. See VideoSourceType.
uid: User ID whose video size or rotation has changed (the uid of the local user is 0, indicating this is a local video preview).
width: Width of the video stream (pixels).
height: Height of the video stream (pixels).
rotation: Rotation information, range [0, 360).
Note: On iOS, this value is always 0.

onVideoStopped

Occurs when the video function is stopped.

onVideoStopped?(): void;

Deprecated: Deprecated: Use the onLocalVideoStateChanged callback with LocalVideoStreamStateStopped (0) instead.

If the app needs to perform other operations on the view after stopping the video (such as displaying other content), you can do so in this callback.

onVideoSubscribeStateChanged

Callback when the video subscription state changes.

onVideoSubscribeStateChanged?(
    channel: string,
    uid: number,
    oldState: StreamSubscribeState,
    newState: StreamSubscribeState,
    elapseSinceLastState: number
  ): void;

Parameters

channel: Channel name.
uid: Remote user ID.
oldState: Previous subscription state. See StreamSubscribeState.
newState: Current subscription state. See StreamSubscribeState.
elapseSinceLastState: Time interval between two state changes (ms).