RtcEngineEventHandler

onActiveSpeaker

Callback when the most active remote speaker is detected.

final void Function(RtcConnection connection, int uid)? onActiveSpeaker;

After successfully calling enableAudioVolumeIndication, the SDK continuously monitors the remote user with the highest volume and counts how often the user is detected as having the highest volume. The remote user with the highest count during the current period is considered the most active speaker. When there are two or more users in the channel and a remote active speaker exists, 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 onActiveSpeaker again.
If the most active speaker changes, the SDK triggers the callback again and reports the new uid.

Parameters

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

onAudioDeviceStateChanged

Occurs when the audio device state changes.

final void Function(String deviceId, MediaDeviceType deviceType,
      MediaDeviceStateType deviceState)? onAudioDeviceStateChanged;

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

Note: This method is only applicable to Windows and macOS.

Parameters

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

onAudioDeviceVolumeChanged

Occurs when the volume of the audio device or app changes.

final void Function(MediaDeviceType deviceType, int volume, bool muted)?
      onAudioDeviceVolumeChanged;

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

Note: This callback is only applicable to Windows and macOS.

Parameters

deviceType

The device type definition. See MediaDeviceType.

volume

The volume, ranging from [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.

final void Function(int soundId)? onAudioEffectFinished;

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 local music file playback ends.

final void Function()? onAudioMixingFinished;

Deprecated: Deprecated: Use onAudioMixingStateChanged instead.

This callback is triggered when the local music file finishes playing after calling startAudioMixing. If startAudioMixing fails, it returns the error code WARN_AUDIO_MIXING_OPEN_ERROR.

onAudioMixingPositionChanged

Reports the playback progress of the music file.

final void Function(int position)? onAudioMixingPositionChanged;

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

Parameters

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

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

onAudioMixingStateChanged

Occurs when the playback state of the music file changes.

final void Function(AudioMixingStateType state, AudioMixingReasonType reason)?
      onAudioMixingStateChanged;

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: The error code. See AudioMixingReasonType.

onAudioPublishStateChanged

Callback for audio publish state changes.

final void Function(
      String channel,
      StreamPublishState oldState,
      StreamPublishState newState,
      int elapseSinceLastState)? onAudioPublishStateChanged;

Parameters

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

onAudioQuality

Callback for remote audio quality.

final void Function(RtcConnection connection, int remoteUid,
      QualityType quality, int delay, int lost)? onAudioQuality;

Deprecated: Deprecated: Use onRemoteAudioStats instead.

This callback describes the audio quality of a remote user during a call and 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: User ID of the sender of the audio stream.
quality: Audio quality. See QualityType.
delay: Delay (ms) from the sender to the receiver, including preprocessing, network transmission, and jitter buffer delay.
lost: Packet loss rate (%) from the sender to the receiver.

onAudioRoutingChanged

Callback when the audio routing changes.

final void Function(int routing)? onAudioRoutingChanged;

Note: This callback is applicable only on Android, iOS, and macOS platforms.

Parameters

routing: The current audio route. See AudioRoute.

onAudioSubscribeStateChanged

Callback for audio subscription state changes.

final void Function(
      String channel,
      int uid,
      StreamSubscribeState oldState,
      StreamSubscribeState newState,
      int elapseSinceLastState)? onAudioSubscribeStateChanged;

Parameters

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

onAudioVolumeIndication

Callback for user audio volume indication.

final void Function(RtcConnection connection, List<AudioVolumeInfo> speakers,
      int speakerNumber, int totalVolume)? onAudioVolumeIndication;

This callback is disabled by default. You can enable it using 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. Each time, two onAudioVolumeIndication callbacks are triggered: one reports the local user's volume information, and the other reports the volume information of the remote users (up to 3) 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 for 20 seconds, they will no longer be included in the remote volume indication callback. 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, speakerNumber ranges from [0,3]. If there are more than 3 remote users publishing, speakerNumber is 3.

totalVolume

Total mixed volume, range [0,255].

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

onCameraExposureAreaChanged

Callback when the camera exposure area changes.

final void Function(int x, int y, int width, int height)?
      onCameraExposureAreaChanged;

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

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

onCameraFocusAreaChanged

Callback when the camera focus area changes.

final void Function(int x, int y, int width, int height)?
      onCameraFocusAreaChanged;

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

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

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.

final void Function()? onCameraReady;

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

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

onChannelMediaRelayStateChanged

Callback when the state of the channel media relay changes.

final void Function(
          ChannelMediaRelayState state, ChannelMediaRelayError code)?
      onChannelMediaRelayStateChanged;

This callback is triggered by the SDK when the state of the channel media relay changes, reporting the current relay state and related error information.

Parameters

state: The channel media relay state. See ChannelMediaRelayState.
code: The error code of the channel media relay. See ChannelMediaRelayError.

onClientRoleChangeFailed

Callback when user role change fails.

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

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

Trigger Timing

This callback is triggered when the local user fails to set the user role using setClientRole after joining the channel.

Parameters

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

onClientRoleChanged

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

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

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

Trigger Timing

This callback is triggered in the following situations:

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 role to AUDIENCE.

Parameters

connection: Connection information. See RtcConnection.
oldRole: Role before switching: ClientRoleType.
newRole: Role after switching: ClientRoleType.
newRoleOptions: Properties of the new role. See ClientRoleOptions.

onConnectionBanned

Callback when the network connection is banned by the server.

final void Function(RtcConnection connection)? onConnectionBanned;

Deprecated: Deprecated: Use onConnectionStateChanged instead.

Parameters

connection: Connection information. See RtcConnection.

onConnectionInterrupted

Callback when the network connection is interrupted.

final void Function(RtcConnection connection)? onConnectionInterrupted;

Deprecated: Deprecated: Use onConnectionStateChanged callback instead.

This callback is triggered when the SDK loses connection to the server for more than 4 seconds after establishing a connection. After this event is triggered, the SDK will try to reconnect to the server. You can use this event to prompt the UI. The difference between this callback and onConnectionLost is:

onConnectionInterrupted is triggered only after successfully joining a channel and when the SDK loses connection to the server for more than 4 seconds.
onConnectionLost is triggered regardless of whether the user has joined a channel, 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 stops trying to reconnect.

Parameters

connection: Connection information. See RtcConnection.

onConnectionLost

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

final void Function(RtcConnection connection)? onConnectionLost;

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

Parameters

connection: Connection information. See RtcConnection.

onConnectionStateChanged

Callback when the network connection state changes.

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

This callback is triggered when the network connection state changes and informs the user 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 change in network connection state. See ConnectionChangedReasonType.

onEncryptionError

Callback when an error occurs with built-in encryption.

final void Function(RtcConnection connection, EncryptionErrorType errorType)?
      onEncryptionError;

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.

final void Function(ErrorCodeType err, String msg)? onError;

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: Error code. See ErrorCodeType.
msg: Error description.

onExtensionErrorWithContext

Callback for extension errors.

final void Function(ExtensionContext context, int error, String message)?
    onExtensionErrorWithContext;

If enabling the extension fails or the extension encounters a runtime error, it triggers this callback to report 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

Plugin event callback.

final void Function(ExtensionContext context, String key, String value)?
    onExtensionEventWithContext;

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

Parameters

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

onExtensionStartedWithContext

Callback when the plugin is successfully enabled.

final void Function(ExtensionContext context)? onExtensionStartedWithContext;

This callback is triggered after the plugin is successfully enabled.

Parameters

context: Plugin context information. See ExtensionContext.

onExtensionStoppedWithContext

Callback when the plugin is disabled.

final void Function(ExtensionContext context)? onExtensionStoppedWithContext;

This callback is triggered after the plugin is successfully disabled.

Parameters

context: Plugin context information. See ExtensionContext.

onFacePositionChanged

Reports local face detection results.

final void Function(int imageWidth, int imageHeight, Rectangle vecRectangle,
      int vecDistance, int numFaces)? onFacePositionChanged;

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 image captured by the camera
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:

This callback is only available on Android and iOS platforms.
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 device power.
When the face is too close to the screen, the SDK does not trigger this callback.
On Android, the distance value has some error margin. Do not use it for precise calculations.

Parameters

imageWidth: Width of the image captured by the camera (px).
imageHeight: Height of the image captured by the camera (px).
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

Callback when the first local audio frame is published.

final void Function(RtcConnection connection, int elapsed)?
      onFirstLocalAudioFramePublished;

The SDK triggers this callback under the following circumstances:

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 (in milliseconds) from calling the joinChannel method to triggering this callback.

onFirstLocalVideoFrame

Callback when the first local video frame is displayed.

final void Function(
          VideoSourceType source, int width, int height, int elapsed)?
      onFirstLocalVideoFrame;

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

Parameters

source: 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 (ms) from calling joinChannel to the occurrence of this event. If startPreviewWithoutSourceType/startPreview is called before joining the channel, this parameter indicates the time from starting the local video preview to the occurrence of this event.

onFirstLocalVideoFramePublished

Callback when the first local video frame is published.

final void Function(RtcConnection connection, int elapsed)?
      onFirstLocalVideoFramePublished;

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 (ms) from calling joinChannel to triggering this callback.

onFirstRemoteAudioDecoded

Callback when the first remote audio frame is decoded.

final void Function(RtcConnection connection, int uid, int elapsed)?
      onFirstRemoteAudioDecoded;

Deprecated: Deprecated: Please use onRemoteAudioStateChanged instead.

The SDK triggers this callback under the following circumstances:

When a remote user sends audio after joining the channel for the first time.
When a remote user resumes sending audio after going offline. Offline means no audio packets are received within 15 seconds, which may be caused by:
- The remote user leaving the channel
- The remote user going offline
- The remote user calling muteLocalAudioStream to stop sending audio streams
- The remote user calling disableAudio to disable audio

Parameters

connection: Connection information. See RtcConnection.
uid: Remote user ID.
elapsed: The delay (in milliseconds) from the local user calling joinChannel to the triggering of this callback.

onFirstRemoteAudioFrame

Callback when the first remote audio frame is received.

final void Function(RtcConnection connection, int userId, int elapsed)?
      onFirstRemoteAudioFrame;

Deprecated: Deprecated: Please use onRemoteAudioStateChanged instead.

Parameters

connection: Connection information. See RtcConnection.
userId: User ID of the remote user sending the audio frame.
elapsed: The delay (in milliseconds) from the local user calling joinChannel to the triggering of this callback.

onFirstRemoteVideoDecoded

Callback when the first remote video is received and decoded.

final void Function(RtcConnection connection, int remoteUid, int width,
      int height, int elapsed)? onFirstRemoteVideoDecoded;

The SDK triggers this callback in the following scenarios:

When the remote user sends video after coming online for the first time.
When the remote user sends video after going offline and then 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: User ID that specifies whose video stream it is.
width: Width (px) of the video stream.
height: Height (px) of the video stream.
elapsed: Delay (ms) from the local call to joinChannel to the triggering of this callback.

onFirstRemoteVideoFrame

Callback when the renderer receives the first remote video frame.

final void Function(RtcConnection connection, int remoteUid, int width,
      int height, int elapsed)? onFirstRemoteVideoFrame;

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

Parameters

uid: User ID that specifies whose 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 (ms) from the local call to joinChannel to the occurrence of this event.

onJoinChannelSuccess

Callback when successfully joined a channel.

final void Function(RtcConnection connection, int elapsed)?
      onJoinChannelSuccess;

This callback indicates that the client has 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: Connection information. See RtcConnection.
elapsed: Time elapsed (ms) from calling joinChannel until this event occurs.

onLastmileProbeResult

Callback for the last mile uplink and downlink network quality probe report before the call.

final void Function(LastmileProbeResult result)? onLastmileProbeResult;

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

Parameters

result: Uplink and downlink last mile quality probe result. See LastmileProbeResult.

onLastmileQuality

Callback for the last mile uplink and downlink network quality report.

final void Function(QualityType quality)? onLastmileQuality;

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

Parameters

quality: Last mile network quality. See QualityType.

onLeaveChannel

Callback when leaving a channel.

final void Function(RtcConnection connection, RtcStats stats)? onLeaveChannel;

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.

Trigger Timing

This callback is triggered when you successfully leave a channel by calling leaveChannel or leaveChannelEx.

Parameters

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

onLocalAudioStateChanged

Callback when the local audio state changes.

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

When the local audio state changes (including microphone capture and audio encoding states), the SDK triggers this callback to report the current local audio state. This callback helps you diagnose issues by providing the current state and reason when a local audio failure occurs.

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

Callback with statistics of the local audio stream during a call.

final void Function(RtcConnection connection, LocalAudioStats stats)?
      onLocalAudioStats;

The SDK triggers this callback once 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.

final void Function(int uid, String userAccount)? onLocalUserRegistered;

When the local user successfully registers a User Account by calling registerLocalUserAccount, or joins a channel using joinChannelWithUserAccount, the SDK triggers this callback and reports the local user's UID and User Account.

Parameters

uid: The local user's ID.
userAccount: The local user's User Account.

onLocalVideoEvent

Callback triggered when a local video event occurs.

  final void Function(VideoSourceType source, LocalVideoEventType event)?
      onLocalVideoEvent;

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.

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

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, in most cases you can troubleshoot it using the reason parameter in this callback. However, on some devices, when capture issues occur (e.g., freezing), the Android system does 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 no frames are being captured 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 cases:
- The app moves to the background and the system reclaims the camera.
- On Android 9 and above, the system revokes camera permission after the app stays in the background for a while.
- 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 video is captured for 4 consecutive seconds.
When the camera outputs 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 with local video stream statistics.

final void Function(RtcConnection connection, LocalVideoStats stats)?
      onLocalVideoStats;

This callback provides statistics about the local device's video stream every 2 seconds.

Parameters

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

onLocalVideoTranscoderError

Callback for local video mixing error.

final void Function(
          TranscodingVideoStream stream, VideoTranscoderError error)?
      onLocalVideoTranscoderError;

When calling 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.

  final void Function(RtcConnection connection, MultipathStats stats)?
      onMultipathStats;

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 for each user during the call.

final void Function(RtcConnection connection, int remoteUid,
      QualityType txQuality, QualityType rxQuality)? onNetworkQuality;

This callback describes the last mile network status of each user during the call. 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 is triggered multiple times every 2 seconds. This callback reports network quality via broadcast packets within the channel. Excessive broadcast packets may cause a broadcast storm. To avoid excessive data transmission due to broadcast storms, this callback supports reporting the network quality of up to 4 remote hosts simultaneously by default.

Note: If the user is not sending streams, txQuality is Unknown; if the user is not receiving streams, rxQuality is Unknown.

Parameters

connection: Connection information. See RtcConnection.
remoteUid: User ID. Indicates the network quality report for the user with this ID. If the uid is 0, it reports the local user's network quality.
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 are sustainable. For example, if the uplink bitrate is 1000 Kbps, it can support 640 × 480 resolution at 15 fps in a live broadcast scenario, but may struggle to support 1280 × 720 resolution. See QualityType.
rxQuality: The user's downlink network quality, calculated based on the downlink packet loss rate, average round-trip time, and network jitter. See QualityType.

onNetworkTypeChanged

Callback when the local network type changes.

final void Function(RtcConnection connection, NetworkType type)?
      onNetworkTypeChanged;

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 obtain the network type 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: Local network connection type. See NetworkType.

onPermissionError

Callback when failing to obtain device permission.

final void Function(PermissionType permissionType)? onPermissionError;

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

Parameters

permissionType: Device permission type. See PermissionType.

onPermissionGranted

Callback triggered when a permission is granted.

  final void Function(PermissionType permissionType)?
      onPermissionGranted;

Parameters

permissionType: Type of permission. See PermissionType.

onProxyConnected

Callback for proxy connection status.

final void Function(String channel, int uid, ProxyType proxyType,
      String localProxyIp, int elapsed)? onProxyConnected;

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

Parameters

channel: Channel name.
uid: User ID
localProxyIp: Reserved parameter, currently not supported.
elapsed: Time elapsed (in milliseconds) from calling joinChannel to the SDK triggering this callback.

onRejoinChannelSuccess

Callback when successfully rejoined a channel.

final void Function(RtcConnection connection, int elapsed)?
      onRejoinChannelSuccess;

Trigger Timing

Sometimes, due to network issues, the client may lose connection with the server. The SDK will automatically reconnect and trigger this callback upon successful reconnection.

Parameters

elapsed: Time interval (ms) from calling joinChannel to triggering this callback.

onRemoteAudioStateChanged

Callback when the remote audio stream state changes.

final void Function(
      RtcConnection connection,
      int remoteUid,
      RemoteAudioState state,
      RemoteAudioStateReason reason,
      int elapsed)? onRemoteAudioStateChanged;

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

Note: When there are more than 32 users (in communication) or hosts (in live streaming) in the channel, 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: Specific reason for the remote audio stream state change. See RemoteAudioStateReason.
elapsed: Time elapsed (in milliseconds) from the local user calling the joinChannel method to the occurrence of this event.

onRemoteAudioStats

Callback with statistics of the remote audio stream during a call.

final void Function(RtcConnection connection, RemoteAudioStats stats)?
      onRemoteAudioStats;

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: Received remote audio statistics. See RemoteAudioStats.

onRemoteAudioTransportStats

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

final void Function(RtcConnection connection, int remoteUid, int delay,
      int lost, int rxKBitRate)? onRemoteAudioTransportStats;

Deprecated: Use onRemoteAudioStats instead. This callback reports end-to-end network statistics of the remote user during a call. It calculates metrics based on audio packets and objectively reflects the current network status using 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 specifying which user/host the audio packet belongs to.
delay: The delay (ms) from the sender to the receiver for the audio packet.
lost: The packet loss rate (%) from the sender to the receiver for 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.

final void Function(int uid, bool isFallbackOrRecover)?
      onRemoteSubscribeFallbackToAudioOnly;

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

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

Note: When the subscribed stream falls back to a low-quality video stream due to poor network conditions, you can monitor the switching of remote video stream quality through the onRemoteVideoStats callback.

Parameters

uid

User ID of the remote user.

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.

final void Function(
      RtcConnection connection,
      int remoteUid,
      RemoteVideoState state,
      RemoteVideoStateReason reason,
      int elapsed)? onRemoteVideoStateChanged;

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

Parameters

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

onRemoteVideoStats

Callback for statistics of the remote video stream during a call.

final void Function(RtcConnection connection, RemoteVideoStats stats)?
      onRemoteVideoStats;

This callback reports end-to-end statistics of the remote video stream 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: Statistics of the remote video. See RemoteVideoStats.

onRemoteVideoTransportStats

Callback for transport statistics of the remote video stream during a call.

final void Function(RtcConnection connection, int remoteUid, int delay,
      int lost, int rxKBitRate)? onRemoteVideoTransportStats;

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

This callback reports end-to-end network statistics of the remote user during a call, calculated based on video packets. It objectively shows the current network status through data such as packet loss and network delay. During a call, this callback is triggered every 2 seconds after the user receives video packets sent by the remote user/host.

Parameters

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

onRenewTokenResult

Callback for the result of the renewToken method call.

  final void Function(
          RtcConnection connection, String token, RenewTokenErrorCode code)?
      onRenewTokenResult;

Since: Available since v4.6.2.

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

Parameters

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

onRequestToken

Callback when the token has expired.

final void Function(RtcConnection connection)? onRequestToken;

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 call joinChannel with the new token to rejoin.
Multi-channel scenario: Call updateChannelMediaOptionsEx with the new token.

Parameters

connection: Connection information. See RtcConnection.

onRhythmPlayerStateChanged

Callback when the state of the virtual metronome changes.

final void Function(RhythmPlayerStateType state, RhythmPlayerReason reason)?
    onRhythmPlayerStateChanged;

Deprecated: Deprecated since v4.6.2.

When the state of the virtual metronome changes, the SDK triggers this callback to report the current state. If a fault occurs with the virtual metronome, this callback helps you understand the current state and the reason for the fault, allowing you to troubleshoot.

Note: This callback applies to Android and iOS only.

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

Callback for current call statistics.

final void Function(RtcConnection connection, RtcStats stats)? onRtcStats;

Trigger Timing

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

Parameters

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

onRtmpStreamingEvent

Callback for RTMP streaming events.

final void Function(String url, RtmpStreamingEvent eventCode)?
      onRtmpStreamingEvent;

Parameters

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

onRtmpStreamingStateChanged

Callback when the RTMP streaming state changes.

final void Function(String url, RtmpStreamPublishState state,
    RtmpStreamPublishReason reason)? onRtmpStreamingStateChanged;

When the RTMP streaming state changes, the SDK triggers this callback and reports the URL and current streaming state. This callback helps streaming users understand the current streaming state. If an error occurs, you can use the returned error code to identify the cause and troubleshoot the issue.

Parameters

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

onSnapshotTaken

Callback for video snapshot result.

final void Function(RtcConnection connection, int uid, String filePath,
      int width, int height, int errCode)? onSnapshotTaken;

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

Parameters

uid

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

connection

Connection information. See RtcConnection.

filePath

The local path where the snapshot is saved.

width

Image width (px).

height

Image height (px).

errCode

Indicates whether the snapshot was successful or the 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 include local capture stopped, remote user stopped publishing, or video data processing is blocked.
- -3: takeSnapshot was called too frequently.

onStreamMessage

Occurs when a stream message is received from a remote user.

final void Function(RtcConnection connection, int remoteUid, int streamId,
      Uint8List data, int length, int sentTs)? onStreamMessage;

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

Note: If you need a more comprehensive solution for low-latency, high-concurrency, and scalable real-time messaging and state synchronization, we recommend using Real-time Messaging.

Parameters

connection: Connection information. See RtcConnection.
remoteUid: The ID of the user who sent the message.
streamId: The stream ID of the received message.
data: The received data.
length: The length of the data in bytes.
sentTs: The timestamp when the data stream was sent.

onStreamMessageError

Occurs when an error occurs in receiving a stream message from a remote user.

final void Function(RtcConnection connection, int remoteUid, int streamId,
      ErrorCodeType code, int missed, int cached)? onStreamMessageError;

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

Note: If you need a more comprehensive solution for low-latency, high-concurrency, and scalable real-time messaging and state synchronization, we recommend using Real-time Messaging.

Parameters

connection: Connection information. See RtcConnection.
remoteUid: The ID of the user who sent the message.
streamId: The stream ID of the received message.
code: The error code. See ErrorCodeType.
missed: The number of lost messages.
cached: The number of messages cached after the data stream was interrupted.

onTokenPrivilegeWillExpire

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

final void Function(RtcConnection connection, String token)?
      onTokenPrivilegeWillExpire;

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.

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

token: The token that is about to expire.

onTranscodedStreamLayoutInfo

Callback for received mixed stream with layout information.

final void Function(
    RtcConnection connection,
    int uid,
    int width,
    int height,
    int layoutCount,
    List<VideoLayout> layoutlist)? onTranscodedStreamLayoutInfo;

When the local client first receives a mixed video stream from the mixing server, or when the layout information of the mixed stream changes, the SDK triggers this callback to report the layout information of each sub-video stream in the mixed stream.

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

Parameters

connection: Connection information. See RtcConnection.
uid: User ID of the mixed video stream publisher.
width: Width (px) of the mixed video stream.
height: Height (px) of the mixed video stream.
layoutCount: Number of layout information 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.

final void Function()? onTranscodingUpdated;

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

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

onUplinkNetworkInfoUpdated

Callback for uplink network information changes.

final void Function(UplinkNetworkInfo info)? onUplinkNetworkInfoUpdated;

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

Note: This callback is applicable only when pushing externally encoded video data in H.264 format to the SDK.

Parameters

info: Uplink network information. See UplinkNetworkInfo.

onUserEnableLocalVideo

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

final void Function(RtcConnection connection, int remoteUid, bool enabled)?
      onUserEnableLocalVideo;

Deprecated

Deprecated: This callback is deprecated. Use the following enums 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 which user's video stream it is.

enabled

Whether the remote user enables video capture:

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

onUserEnableVideo

Callback when a remote user enables/disables the video module.

final void Function(RtcConnection connection, int remoteUid, bool enabled)?
      onUserEnableVideo;

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

User ID indicating which user's video stream it is.

enabled

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

onUserInfoUpdated

Callback when remote user information is updated.

final void Function(int uid, UserInfo info)? onUserInfoUpdated;

After a remote user joins the channel, the SDK obtains the user's UID and User Account, then caches a mapping table that includes the remote user's 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 user's UID and User Account. See UserInfo class.

onUserJoined

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

final void Function(RtcConnection connection, int remoteUid, int elapsed)?
      onUserJoined;

In communication scenarios, this callback indicates that a remote user has joined the channel. If other users are already in the channel, the newly joined user also receives callbacks for those existing users.
In live streaming scenarios, this callback indicates that a host has joined the channel. If other hosts are already in the channel, the newly joined user also receives callbacks for those existing hosts. It is recommended that the number of co-hosts does not exceed 32 (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 disconnection.

Parameters

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

onUserMuteAudio

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

final void Function(RtcConnection connection, int remoteUid, bool muted)?
      onUserMuteAudio;

This callback is triggered when a 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

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

final void Function(RtcConnection connection, int remoteUid, bool muted)?
      onUserMuteVideo;

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

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

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.

final void Function(RtcConnection connection, int remoteUid,
      UserOfflineReasonType reason)? onUserOffline;

Users leave the channel for the following reasons:

Normal departure: The remote user or host sends a 'goodbye' message and leaves the channel voluntarily.
Timeout disconnection: No data packets are received from the user within a certain time (20 seconds in communication scenarios, slightly longer in live streaming), and 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 streaming) went offline. See UserOfflineReasonType.

onVideoDeviceStateChanged

Callback when a video device changes.

final void Function(String deviceId, MediaDeviceType deviceType,
      MediaDeviceStateType deviceState)? onVideoDeviceStateChanged;

This callback indicates that the system video device state has changed, such as being unplugged or removed. If you are using an external camera for capture, unplugging it will interrupt the video.

Note: This callback is applicable only to Windows and macOS.

Parameters

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

onVideoPublishStateChanged

Callback for video publishing state change.

final void Function(
      VideoSourceType source,
      String channel,
      StreamPublishState oldState,
      StreamPublishState newState,
      int elapseSinceLastState)? onVideoPublishStateChanged;

Parameters

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

onVideoRenderingTracingResult

Callback for video frame rendering events.

final void Function(
      RtcConnection connection,
      int uid,
      MediaTraceEvent currentEvent,
      VideoRenderingTracingInfo tracingInfo)? onVideoRenderingTracingResult;

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 video frame rendering. Developers should minimize the metric values to improve rendering efficiency. See VideoRenderingTracingInfo.

onVideoSizeChanged

Callback when the size and rotation of local or remote video changes.

final void Function(RtcConnection connection, VideoSourceType sourceType,
      int uid, int width, int height, int rotation)? onVideoSizeChanged;

Parameters

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

onVideoStopped

Callback when video function is stopped.

final void Function()? onVideoStopped;

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

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

onVideoSubscribeStateChanged

Callback for video subscription state changes.

final void Function(
      String channel,
      int uid,
      StreamSubscribeState oldState,
      StreamSubscribeState newState,
      int elapseSinceLastState)? onVideoSubscribeStateChanged;

Parameters

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