IRtcEngineEventHandler

onActiveSpeaker

Callback 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 how many times this user is identified as the loudest. The remote user with the highest count during a period is considered the most active speaker. When there are two or more users in the channel and there is an active remote speaker, the SDK triggers this callback and reports the uid of the most active remote user.

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

Parameters

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

onAudioDeviceStateChanged

Callback for changes in audio device state.

onAudioDeviceStateChanged?(
    deviceId: string,
    deviceType: MediaDeviceType,
    deviceState: number
  ): void;

Indicates that the system audio device state has changed, such as when a headset is unplugged.

Parameters

deviceId: Device ID.
deviceType: Device type definition. See MediaDeviceType.
deviceState: Device state. See MediaDeviceStateType.

onAudioDeviceVolumeChanged

Callback when the volume of an audio device or app changes.

onAudioDeviceVolumeChanged?(
    deviceType: MediaDeviceType,
    volume: number,
    muted: boolean
  ): void;

This callback is triggered when the volume of an audio playback or recording device, or the app, changes.

Parameters

deviceType

Device type definition. See MediaDeviceType.

volume

Volume. Range: [0,255].

muted

Whether the audio device is muted:

true: The audio device is muted.
false: The audio device is not muted.

onAudioEffectFinished

Callback when a local audio effect file finishes playing.

onAudioEffectFinished?(soundId: number): void;

This callback is triggered when the playback of an audio effect finishes.

Parameters

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

onAudioMixingFinished

Callback when local music file playback is finished.

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

Callback for music file playback progress.

onAudioMixingPositionChanged?(position: number): void;

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

Parameters

position: The current playback progress of the music file in ms.

Return Values

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

onAudioMixingStateChanged

Callback when the music file playback state 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: The 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 the two state changes (ms).

onAudioQuality

Callback for remote audio quality.

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

Deprecated: Deprecated: Use onRemoteAudioStats instead.

This callback describes the audio quality of remote users during a call. It is triggered once 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.
remoteUid: The user ID of the sender of the audio stream.
quality: Audio quality. See QualityType.
delay: The delay (ms) from the sender to the receiver, including delays caused by audio pre-processing, network transmission, and jitter buffering.
lost: The packet loss rate (%) from the sender to the receiver.

onAudioRoutingChanged

Callback triggered when the audio routing changes.

onAudioRoutingChanged?(routing: number): void;

Note: This callback is applicable to macOS only.

Parameters

routing

The current audio routing:

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

onAudioSubscribeStateChanged

Callback for 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 the two state changes (ms).

onAudioVolumeIndication

Callback for user audio volume indication.

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 interval set in enableAudioVolumeIndication after joining the channel. Two onAudioVolumeIndication callbacks are triggered each time: one reporting volume information of the local user, and the other reporting volume information of up to 3 remote users with the highest instantaneous volume.

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

Parameters

connection

Connection information. See RtcConnection.

speakers

User volume information. See 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, speakerNumber ranges from [0,3]. If the number of remote users publishing is greater than 3, the value of speakerNumber in this callback is 3.

totalVolume

Total mixed volume, ranging from [0,255].

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

onCameraReady

Camera ready callback.

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 and reports the current relay state and any associated error information.

Parameters

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

onClientRoleChangeFailed

Callback 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

After the local user joins the channel, if setClientRole fails to set the user role, the SDK triggers this callback.

Parameters

reason: The reason for the failure to switch user roles. See ClientRoleChangeFailedReason.
currentRole: The current user role. See ClientRoleType.
connection: 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 before joining a channel and set the user role to BROADCASTER.

Trigger Timing

This callback is triggered in 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: Connection information. See RtcConnection.
oldRole: The previous role: ClientRoleType.
newRole: The new role: ClientRoleType.
newRoleOptions: The properties of the new role. See ClientRoleOptions.

onConnectionBanned

Occurs 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

Occurs when the network connection is interrupted.

onConnectionInterrupted?(connection: RtcConnection): void;

Deprecated: Deprecated: Use the onConnectionStateChanged callback instead.

After the SDK establishes a connection with the server, if the network connection is lost for more than 4 seconds, this callback is triggered. 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 triggered only 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 still fails to rejoin the channel within 20 minutes after disconnection, it will stop trying to reconnect.

Parameters

connection: Connection information. See RtcConnection.

onConnectionLost

Occurs when the network connection is lost and the SDK fails to reconnect to the server within 10 seconds.

onConnectionLost?(connection: RtcConnection): void;

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

Parameters

connection: Connection information. See RtcConnection.

onConnectionStateChanged

Occurs 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 connection 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

Occurs when an error occurs in built-in encryption.

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

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

Parameters

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

onError

Callback when an error occurs.

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

This callback indicates that a network or media-related error occurred during SDK runtime. Typically, errors reported by the SDK mean that the SDK cannot recover automatically and require intervention from the app or user notification.

Parameters

err: Error code. See ErrorCodeType.
msg: Error description.

onExtensionErrorWithContext

Callback when an extension error occurs.

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

When enabling the extension fails or the extension runs into an error, this callback is triggered and reports the error code and reason.

Parameters

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

onExtensionEventWithContext

Callback for extension events.

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

To listen to extension events, you need to register this callback.

Parameters

context: Extension context information. See ExtensionContext.
key: The key of the extension property.
value: The value corresponding to the extension property key.

onExtensionStartedWithContext

Callback when an 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 an extension is disabled.

onExtensionStoppedWithContext?(context: ExtensionContext): void;

This callback is triggered after the extension is successfully disabled.

Parameters

context: Extension context information. See ExtensionContext.

onFirstLocalAudioFramePublished

Callback when the first local audio frame is published.

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

The SDK triggers this callback in the following situations:

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

Parameters

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

onFirstLocalVideoFrame

Occurs when the first local video frame is displayed.

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: The width (px) of the locally rendered video.
height: The height (px) of the locally rendered video.
elapsed: Time elapsed (ms) from calling joinChannel to the occurrence of this event. If startPreviewWithoutSourceType/startPreview was called before joining the channel, this parameter indicates the time elapsed from calling startPreviewWithoutSourceType or startPreview to the occurrence of this event.

onFirstLocalVideoFramePublished

Occurs 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 by calling joinChannel with the local video module enabled.
After calling muteLocalVideoStream(true) followed by muteLocalVideoStream(false).
After calling disableVideo followed by enableVideo.

Parameters

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

onFirstRemoteAudioDecoded

Occurs when the first frame of remote audio is decoded.

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

Deprecated: Deprecated: Use onRemoteAudioStateChanged instead.

The SDK triggers this callback when:

The remote user sends audio after joining the channel for the first time.
The remote user sends audio again after going offline. Offline means that no audio packet is received locally within 15 seconds, which may be caused by:
- The remote user leaves the channel
- The remote user drops offline
- The remote user calls the muteLocalAudioStream method to stop sending the audio stream
- The remote user calls the disableAudio method to disable audio

Parameters

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

onFirstRemoteAudioFrame

Occurs when the first frame of remote audio 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 sends the audio frame.
elapsed: Time elapsed (ms) from the local user calling joinChannel to this callback being triggered.

onFirstRemoteVideoDecoded

Occurs when the remote video is received and decoded.

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

The SDK triggers this callback under the following circumstances:

The remote user sends video after joining the channel for the first time.
The remote user sends video after going offline and coming back online. Possible causes of such interruptions include:
- The remote user leaves the channel.
- The remote user gets disconnected.
- The remote user calls the disableVideo method to disable the video module.

Parameters

connection: Connection information. See RtcConnection.
remoteUid: The user ID that identifies the video stream.
width: Width of the video stream (px).
height: Height of the video stream (px).
elapsed: The time elapsed (ms) from calling joinChannel until this callback is triggered.

onFirstRemoteVideoFrame

Occurs when the renderer receives the first frame of remote video.

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

Note: This callback is triggered only when the SDK handles rendering. If you use custom video rendering, this callback is not triggered and you need to implement it yourself outside the SDK.

Parameters

remoteUid: The user ID that identifies the video stream.
connection: Connection information. See RtcConnection.
width: Width of the video stream (px).
height: Height of the video stream (px).
elapsed: The time elapsed (ms) from calling joinChannel until this event occurs.

onJoinChannelSuccess

Callback when successfully joining a channel.

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

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

Trigger Timing

After you successfully call joinChannel, joinChannelWithUserAccount, joinChannelEx, or joinChannelWithUserAccountEx to join a channel, the SDK triggers this callback.

Parameters

connection: Connection information. See RtcConnection.
elapsed: Time elapsed (in milliseconds) from the local call to joinChannel until this event occurs.

onLastmileProbeResult

Reports the last-mile network probe result before a call.

onLastmileProbeResult?(result: LastmileProbeResult): void;

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

Parameters

result: Result of the last-mile uplink and downlink network probe. See LastmileProbeResult.

onLastmileQuality

Reports the last-mile network quality before a call.

onLastmileQuality?(quality: QualityType): void;

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

Parameters

quality: Last-mile network quality. See QualityType.

onLeaveChannel

Callback when leaving a channel.

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

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

Trigger Timing

After you successfully call leaveChannel or leaveChannelEx to leave the channel, the SDK triggers this callback.

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;

The SDK triggers this callback to report the current local audio state when it changes, including the microphone capture state and audio encoding state. When a local audio issue occurs, this callback helps you understand the current state and the reason for the issue, facilitating troubleshooting.

Note: When the state is LocalAudioStreamStateFailed (3), you can check the returned 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

Callback 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 UID and User Account of the local user.

Parameters

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

onLocalVideoStateChanged

Occurs when the local video state changes.

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

The SDK triggers this callback when the local video state 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 < 20 Kbps.
If an exception occurs during video capture, you can usually troubleshoot it using the reason parameter in this callback. However, on some devices, when a capture issue occurs (e.g., freeze), Android may not throw any error callback, so the SDK cannot report the reason for the local video state change. In this case, you can determine whether the capture has no frames by checking: this callback reports state as LocalVideoStreamStateCapturing or LocalVideoStreamStateEncoding, and the captureFrameRate in the onLocalVideoStats callback is 0.

Trigger Timing

The SDK triggers this callback in the following situations, with state as LocalVideoStreamStateFailed and reason as LocalVideoStreamReasonCaptureFailure:
- The app goes to the background and the system reclaims the camera.
- 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: The type of video source. See VideoSourceType.
state: The local video state. See LocalVideoStreamState.
reason: The reason for the local video state change. See LocalVideoStreamReason.

onLocalVideoStats

Reports the statistics of the local video stream.

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

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

Parameters

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

onLocalVideoTranscoderError

Callback when a local video mixing error occurs.

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

When startLocalVideoTranscoder or updateLocalTranscoderConfiguration fails, the SDK triggers this callback to report the reason for the mixing failure.

Parameters

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

onMultipathStats

Callback for multipath transmission statistics.

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

Since: Available 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

Reports the last-mile network quality 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. Last mile refers to the network status between the device and the Agora edge server. This callback is triggered every 2 seconds. If there are multiple remote users, it is triggered multiple times every 2 seconds. The callback reports network quality using broadcast packets within the channel. Excessive broadcast packets may cause a broadcast storm. To prevent this from causing a large amount of data transmission in the channel, this callback by default supports reporting the network quality of up to 4 remote hosts simultaneously.

Note: When the user is not sending streams, txQuality is Unknown; when not receiving streams, rxQuality is Unknown.

Parameters

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

onNetworkTypeChanged

Callback when the local network type changes.

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

When the type of local network connection changes, the SDK triggers this callback and specifies the current network connection type. You can use this callback to get the type of network currently in use. When the connection is interrupted, this callback helps determine whether the cause is a network switch or poor network conditions.

Parameters

connection: Connection information. See RtcConnection.
type: Type of local network connection. See NetworkType.

onPermissionError

Callback when failing to obtain device permission.

onPermissionError?(permissionType: PermissionType): void;

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

Parameters

permissionType: Type of device 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 monitor 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, the 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, currently not supported.
elapsed: Time elapsed (in milliseconds) from calling joinChannel to the SDK triggering this callback.

onRejoinChannelSuccess

Callback when successfully rejoining a channel.

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

Trigger Timing

Sometimes due to network issues, the client may lose connection with the server. The SDK automatically reconnects, and this callback is triggered upon successful reconnection.

Parameters

uid: The user ID of the user who rejoined the channel.
connection: Connection information. See RtcConnection.
elapsed: The time interval (in milliseconds) from calling the joinChannel method to the triggering of this callback.

onRemoteAudioStateChanged

Occurs when the remote audio stream state changes.

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

The SDK triggers this callback to report the current remote audio stream state when the audio state of a remote user (in a communication scenario) or host (in a live streaming scenario) changes.

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

Parameters

connection: Connection information. See RtcConnection.
remoteUid: User ID of the remote user whose audio state changed.
state: Remote audio stream state. See RemoteAudioState.
reason: Reason for the remote audio stream state change. See RemoteAudioStateReason.
elapsed: Time elapsed (ms) from the local user calling joinChannel to the occurrence of this event.

onRemoteAudioStats

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

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

The SDK triggers this callback every 2 seconds for each remote user/host 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: Received remote audio statistics. See RemoteAudioStats.

onRemoteAudioTransportStats

Reports the transport statistics of the remote audio stream during a call.

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

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

Parameters

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

onRemoteSubscribeFallbackToAudioOnly

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

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

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

The subscribed audio-video stream falls back to audio-only due to poor downlink network conditions
The subscribed audio stream recovers to audio-video as the network improves

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

Parameters

uid

User ID of the remote user.

isFallbackOrRecover

true: The subscribed stream has fallen back to audio-only due to poor network conditions.
false: The subscribed stream has recovered to audio-video due to improved network conditions.

onRemoteVideoStateChanged

Occurs 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 streaming) in the channel exceeds 32, this callback may be inaccurate.

Parameters

connection: Connection information. See RtcConnection.
remoteUid: The remote user ID whose video state has changed.
state: The remote video stream state. See RemoteVideoState.
reason: The reason for the remote video stream state change. See RemoteVideoStateReason.
elapsed: Time elapsed in milliseconds from the local user calling joinChannel to the occurrence of this event.

onRemoteVideoStats

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

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

This callback reports 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

Reports the statistics of the video stream sent by each remote users.

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

Deprecated: Deprecated: This callback is deprecated. Use onRemoteVideoStats instead.

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

Parameters

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

onRenewTokenResult

Callback for the result of the renewToken method call.

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

Since: Available since v4.6.2.

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

Parameters

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

onRequestToken

Callback when the Token has expired.

onRequestToken?(connection: RtcConnection): void;

During audio and video interaction, 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 pass in the new Token when calling joinChannel to rejoin the channel.
Multi-channel scenario: Call updateChannelMediaOptionsEx to pass in the new Token.

Parameters

connection: Connection information. See RtcConnection.

onRhythmPlayerStateChanged

Callback when the virtual metronome state changes.

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

Deprecated: Deprecated since v4.6.2.

When the virtual metronome state changes, the SDK triggers this callback to report the current state. If the metronome encounters an issue, this callback helps you identify the current state and the cause of the issue for troubleshooting.

Parameters

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

onRtcStats

Callback for current call-related statistics.

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

Trigger Timing

The SDK periodically reports the current call statistics to the app, triggering this callback 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 reports the URL whose state has changed and the current streaming state. This callback helps streaming users understand the current streaming state. If an error occurs, you can determine the cause from the returned error code to facilitate troubleshooting.

Parameters

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

onSnapshotTaken

Callback for video snapshot result.

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

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

Parameters

uid

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

connection

Connection information. See RtcConnection.

filePath

The local path where the snapshot is saved.

width

Width of the image (px).

height

Height of the image (px).

errCode

Indicates success or reason for failure:

0: Snapshot successful.
< 0: Snapshot failed.
- -1: Failed to write file or JPEG encoding failed.
- -2: No video frame received from the specified user within 1 second after calling takeSnapshot. Possible reasons: local capture stopped, remote user stopped publishing, or video data processing is blocked.
- -3: takeSnapshot was 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 data stream message sent by the 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: The received data.
length: Length of the data in bytes.
sentTs: Timestamp when the data stream was sent.

onStreamMessageError

Callback when an error occurs in 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 the data stream message sent by the remote user using the sendStreamMessage method.

Parameters

connection: Connection information. See RtcConnection.
uid: 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 cached messages after data stream interruption.

onTokenPrivilegeWillExpire

Callback 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.
Multi-channel scenario: Call updateChannelMediaOptionsEx with the new token.

Trigger Timing

During audio and video interaction, 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.

onTranscodingUpdated

Callback when the RTMP transcoding settings are updated.

onTranscodingUpdated?(): void;

When the live streaming parameters LiveTranscoding in the startRtmpStreamWithTranscoding method are updated, the onTranscodingUpdated callback is triggered and reports the update to the host.

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

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 applies only when pushing externally encoded video data in H.264 format to the SDK.

Parameters

info: Uplink network information. See UplinkNetworkInfo.

onUserEnableLocalVideo

Occurs when a remote user enables or disables the local video capture.

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

Deprecated

Deprecated: This callback is deprecated. Use the following enumerations of the onRemoteVideoStateChanged callback instead:

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

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

Parameters

connection

Connection information. See RtcConnection.

remoteUid

The user ID indicating whose video stream it is.

enabled

Whether the remote user enables 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 module means the user can only make voice calls, and cannot display or send their own video, nor receive or display others’ video. This callback is triggered when the 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 it is.

enabled

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

onUserInfoUpdated

Callback when remote user information is updated.

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

After a remote user joins the channel, the SDK obtains the UID and User Account of the remote user, then 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 information, including the UID and User Account. See the UserInfo class.

onUserJoined

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

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

In communication scenarios, this callback indicates that a remote user has joined the channel. If there are already other users in the channel before the new user joins, the new user also receives callbacks for those existing users.
In live broadcast scenarios, this callback indicates that a host has joined the channel. If there are already hosts in the channel before the new one joins, the new user also receives callbacks for those existing hosts. It is recommended to have no more than 32 co-hosts (including no more than 17 video co-hosts).

Trigger Timing

This callback is triggered in the following situations:

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 newly joined remote user/host.
elapsed: The time elapsed (ms) from the local user calling joinChannel to the triggering of this callback.

onUserMuteAudio

Callback when a remote user (in communication) or host (in live streaming) stops or resumes sending audio streams.

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

This callback is triggered when the remote user calls the muteLocalAudioStream method to disable or enable audio sending.

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

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;

When a remote user calls muteLocalVideoStream to stop or resume publishing the video stream, the SDK triggers this callback to inform the local user of the remote user’s publishing status.

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

Parameters

connection

Connection information. See RtcConnection.

remoteUid

The 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 broadcast) leaves the current channel.

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

Users leave the channel generally due to the following reasons:

Normal departure: The remote user or host sends a 'goodbye' message and leaves the channel voluntarily.
Timeout disconnection: If no data packets are received from the peer within a certain time (20 seconds for communication, slightly longer for live broadcast), the user is considered offline. In poor network conditions, false positives may occur. It is recommended to use the RTM SDK for reliable offline detection.

Trigger Timing

During audio and video interaction, this callback is triggered when a remote user or host leaves the current channel.

Parameters

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

onVideoDeviceStateChanged

Video device state change callback.

onVideoDeviceStateChanged?(
    deviceId: string,
    deviceType: MediaDeviceType,
    deviceState: number
  ): void;

This callback indicates that the system video device state has changed, such as being unplugged or removed. If an external camera is being used for capture and it is unplugged, video will be interrupted.

Parameters

deviceId: Device ID.
deviceType: Device type. See MediaDeviceType.
deviceState: Device state. See MediaDeviceStateType.

onVideoPublishStateChanged

Occurs when the video publishing state changes.

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

Parameters

channel: The channel name.
source: The type of video source. See VideoSourceType.
oldState: The previous publishing state. See StreamPublishState.
newState: The current publishing state. See StreamPublishState.
elapseSinceLastState: The time interval (ms) between the two state changes.

onVideoRenderingTracingResult

Video frame rendering event callback.

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

After calling startMediaRenderingTracing or joining a channel, the SDK triggers this callback to report events and metrics during the video frame 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 video frame rendering. Developers should minimize these values to improve rendering efficiency. See VideoRenderingTracingInfo.

onVideoSizeChanged

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

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

Parameters

connection: Connection information. See RtcConnection.
sourceType: The type of video source. See VideoSourceType.
uid: The user ID whose video size or rotation changed (uid is 0 for the local user, indicating the video is from the local preview).
width: The width (pixels) of the video stream.
height: The height (pixels) of the video stream.
rotation: The rotation information, in the range [0, 360).

onVideoStopped

Occurs when the video function is stopped.

onVideoStopped?(): void;

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

If the app needs to perform other operations on the view after stopping the video (e.g., displaying another image), it can be done in this callback.

onVideoSubscribeStateChanged

Callback for 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 the two state changes (ms).