RtcChannelEventHandler

activeSpeaker

Occurs when the most active speaker is detected.

UidCallback? activeSpeaker;

After a successful call of enableAudioVolumeIndication, the SDK continuously detects which remote user has the loudest volume. During the current period, the remote user, who is detected as the loudest for the most times, is the most active user.

When the number of users exceeds two (included) and an active speaker is detected, the SDK triggers this callback and reports the uid of the most active speaker.

If the most active speaker remains the same, the SDK triggers the activeSpeaker callback only once.
If the most active speaker changes to another user, the SDK triggers this callback again and reports the uid of the new active speaker.

Return values

A callback object that includes the following parameters:

uid: The user ID of the most active speaker.

audioPublishStateChanged

Occurs when the audio publishing state changes.

StreamPublishStateCallback? audioPublishStateChanged;

Return values

A callback object that includes the following parameters:

channel: The channel name.
oldState: For the previous publishing state, see StreamPublishState.
newState: For the current publishing state, see StreamPublishState.
elapseSinceLastState: The time elapsed (ms) from the previous state to the current state.

audioSubscribeStateChanged

Occurs when the audio subscribing state changes.

StreamSubscribeStateCallback? audioSubscribeStateChanged;

Return values

A callback object that includes the following parameters:

channel: The channel name.
oldState: The previous subscribing status, see StreamSubscribeState for details.
newState: The current subscribing status, see StreamSubscribeState for details.
elapseSinceLastState: The time elapsed (ms) from the previous state to the current state.

error

The error code RtcChannel reported.

ErrorCallback? error;

Return values

A callback object that includes the following parameters:

err: The error code. For details, see Error Codes and Warning Codes.
msg: The error message.

channelMediaRelayEvent

Reports events during the media stream relay.

MediaRelayEventCallback? channelMediaRelayEvent;

Return values

A callback object that includes the following parameters:

code: The event code of channel media relay. See ChannelMediaRelayEvent.

channelMediaRelayStateChanged

Occurs when the state of the media stream relay changes.

MediaRelayStateCallback? channelMediaRelayStateChanged;

The SDK returns the state of the current media relay with any error message.

Return values

A callback object that includes the following parameters:

state: The state code. For details, see ChannelMediaRelayState.
code: The error code of the channel media replay. For details, see ChannelMediaRelayError.

warning

Reports the warning code of RtcChannel.

WarningCallback? warning;

Return values

A callback object that includes the following parameters:

warn: Warning codes. For details, see Error Codes and Warning Codes.
msg: The warning message.

clientRoleChanged

Occurs when the user role switches in the interactive live streaming.

ClientRoleCallback? clientRoleChanged;

The SDK triggers this callback when the local user changes the user role after joining the channel.

Return values

A callback object that includes the following parameters:

oldRole: Role that the user switches from: ClientRole.
newRole: Role that the user switches to: ClientRole.

connectionLost

Occurs when the SDK cannot reconnect to Agora's edge server 10 seconds after its connection to the server is interrupted.

EmptyCallback? connectionLost;

The SDK triggers this callback when it cannot connect to the server 10 seconds after calling the joinChannel method, regardless of whether it is in the channel.

connectionStateChanged

Occurs when the network connection state changes.

ConnectionStateCallback? connectionStateChanged;

When the network connection state changes, the SDK triggers this callback and reports the current connection state and the reason for the change.

Return values

A callback object that includes the following parameters:

state: The current connection state.
reason: The reason for a connection state change.

firstRemoteVideoFrame

Occurs when the first remote video frame is rendered.

OnFirstRemoteVideoFrame? firstRemoteVideoFrame;

The SDK triggers this callback when the first local video frame is displayed/rendered on the local video view. The application can retrieve the time elapsed (the elapsed parameter) from a user joining the channel until the first video frame is displayed.

Return values

A callback object that includes the following parameters:

uid: The user ID of the remote user sending the video stream.
width: The width (px) of the video stream.
height: The height (px) of the video stream.
elapsed: Time elapsed (ms) from the local user calling joinChannel until the SDK triggers this callback.

joinChannelSuccess

Occurs when a user joins a channel.

UidWithElapsedAndChannelCallback? joinChannelSuccess;

This callback notifies the application that a user joins a specified channel.

Return values

A callback object that includes the following parameters:

uid: User ID. If you have specified a user ID in joinChannel, the ID will be returned here; otherwise, the SDK returns an ID automatically assigned by the Agora server.
elapsed: The time elapsed (in milliseconds) from the local user calling joinChannel till this event.

leaveChannel

Occurs when a user leaves a channel.

RtcStatsCallback? leaveChannel;

When a user leaves the channel by using the leaveChannel method, the SDK uses this callback to notify the app when the user leaves the channel. With this callback, the app gets the channel information, such as the call duration and quality statistics.

Return values

A callback object that includes the following parameters:

stats: The statistics of the call, see RtcStats .

localPublishFallbackToAudioOnly

Occurs when the published media stream falls back to an audio-only stream.

FallbackCallback? localPublishFallbackToAudioOnly;

If you call setLocalPublishFallbackOption and set option as AudioOnly, the SDK triggers this callback when the remote media stream falls back to audio-only mode due to poor uplink conditions, or when the remote media stream switches back to the video after the uplink network condition improves.

Attention: If the local stream falls back to the audio-only stream, the remote user receives the userMuteVideo callback.

Return values

A callback object that includes the following parameters:

isFallbackOrRecover

true: The published stream falls back to audio-only due to poor network conditions.
false: The published stream switches back to the video after the network conditions improve.

metadataReceived

Occurs when the local user receives Metadata.

MetadataCallback? metadataReceived;

Return values

A callback object that includes the following parameters:

buffer: The recevied metadata.
uid: The ID of the user who sent the metadata.
timeStampMs: The timestamp (ms) of the received metadata.

networkQuality

Reports the last mile network quality of each user in the channel.

NetworkQualityWithUidCallback? networkQuality;

This callback reports the last mile network conditions of each user in the channel. Last mile refers to the connection between the local device and Agora's edge server.

The SDK triggers this callback once every two seconds. If a channel includes multiple users, the SDK triggers this callback as many times.

Return values

A callback object that includes the following parameters:

uid

User ID. The network quality of the user with this user ID is reported.

If the uid is 0, the local network quality is reported.

txQuality

Uplink network quality rating of the user in terms of the transmission bit rate, packet loss rate, average RTT (Round-Trip Time) and jitter of the uplink network. This parameter is a quality rating helping you understand how well the current uplink network conditions can support the selected video encoder configuration. For example, a 1000 Kbps uplink network may be adequate for video frames with a resolution of 640 × 480 and a frame rate of 15 fps in the LIVE_BROADCASTING profile, but might be inadequate for resolutions higher than 1280 × 720.

rxQuality

Downlink network quality rating of the user in terms of packet loss rate, average RTT, and jitter of the downlink network.

rejoinChannelSuccess

Occurs when a user rejoins the channel.

UidWithElapsedAndChannelCallback? rejoinChannelSuccess;

When a user loses connection with the server because of network problems, the SDK automatically tries to reconnect and triggers this callback upon reconnection.

Return values

A callback object that includes the following parameters:

uid: The ID of the user who rejoins the channel.
elapsed: Time elapsed (ms) from starting to reconnect until the SDK triggers this callback.

remoteAudioStateChanged

Occurs when the remote audio state changes.

RemoteAudioStateCallback? remoteAudioStateChanged;

When the audio state of a remote user (in the voice/video call channel) or host (in the live streaming channel) changes, the SDK triggers this callback to report the current state of the remote audio stream.

Attention: This callback does not work properly when the number of users (in the voice/video call channel) or hosts (in the live streaming channel) in the channel exceeds 17.

Return values

A callback object that includes the following parameters:

uid: The ID of the remote user whose audio state changes.
state: The state of the remote audio, see AudioRemoteState.
reason: The reason of the remote audio state change, see AudioRemoteStateReason.
elapsed: Time elapsed (ms) from the local user calling the joinChannel method until the SDK triggers this callback.

remoteAudioStats

Reports the transport-layer statistics of each remote audio stream.

RemoteAudioStatsCallback? remoteAudioStats;

The SDK triggers this callback once every two seconds for each remote user who is sending audio streams. If a channel includes multiple remote users, the SDK triggers this callback as many times.

Return values

A callback object that includes the following parameters:

stats: The statistics of the received remote audio streams. See RemoteAudioStats.

remoteSubscribeFallbackToAudioOnly

Occurs when the remote media stream falls back to the audio-only stream due to poor network conditions or switches back to the video stream after the network conditions improve.

FallbackWithUidCallback? remoteSubscribeFallbackToAudioOnly;

If you call setRemoteSubscribeFallbackOption and set option as AudioOnly, the SDK triggers this callback when the remote media stream falls back to audio-only mode due to poor uplink conditions, or when the remote media stream switches back to the video after the downlink network condition improves.

Attention: Once the remote media stream switches to the low-quality stream due to poor network conditions, you can monitor the stream switch between a high-quality and low-quality stream in the remoteVideoStats callback.

Return values

A callback object that includes the following parameters:

uid

The user ID of the remote user.

isFallbackOrRecover

true: The remotely subscribed media stream falls back to audio-only due to poor network conditions.
false: The remotely subscribed media stream switches back to the video stream after the network conditions improved.

remoteVideoStateChanged

Occurs when the remote video state changes.

RemoteVideoStateCallback? remoteVideoStateChanged;

Attention: This callback does not work properly when the number of users (in the voice/video call channel) or hosts (in the live streaming channel) in the channel exceeds 17.

Return values

A callback object that includes the following parameters:

uid: The ID of the remote user whose video state changes.
state: The state of the remote video, see VideoRemoteState.
reason: The reason for the remote video state change, see VideoRemoteStateReason.
elapsed: Time elapsed (ms) from the local user calling the joinChannel method until the SDK triggers this callback.

remoteVideoStats

Reports the transport-layer statistics of each remote video stream.

RemoteVideoStatsCallback? remoteVideoStats;

Reports the statistics of the video stream from the remote users. The SDK triggers this callback once every two seconds for each remote user. If a channel has multiple users/hosts sending video streams, the SDK triggers this callback as many times.

Return values

A callback object that includes the following parameters:

stats: Statistics of the remote video stream. For details, see RemoteVideoStats.

requestToken

Occurs when the token expires.

EmptyCallback? requestToken;

When the token expires during a call, the SDK triggers this callback to remind the app to renew the token.

Once you receive this callback, generate a new token on your app server, and call joinChannel to rejoin the channel.

rtcStats

Reports the statistics of the current call.

RtcStatsCallback? rtcStats;

The SDK triggers this callback once every two seconds after the user joins the channel.

Return values

A callback object that includes the following parameters:

stats: Statistics of the RTC engine, see RtcStats for details.

rtmpStreamingEvent

Reports events during the media push.

RtmpStreamingEventCallback? rtmpStreamingEvent;

Return values

A callback object that includes the following parameters:

url: The URL for media push.
eventCode: The event code of media push. See RtmpStreamingEvent for details.

rtmpStreamingStateChanged

Occurs when the media push state changes.

RtmpStreamingStateCallback? rtmpStreamingStateChanged;

When the CDN live streaming state changes, the SDK triggers this callback to report the current state and the reason why the state has changed. When exceptions occur, you can troubleshoot issues by referring to the detailed error descriptions in the error code parameter.

Return values

A callback object that includes the following parameters:

url: The URL address where the state of the media push changes.
state: The current state of the media push. See RtmpStreamingState. When the streaming state is Failure (4), you can view the error information in the errorCode parameter.
errCode: The detailed error information for the media push. See RtmpStreamingErrorCode.

streamMessage

Occurs when the local user receives the data stream from the remote user.

StreamMessageCallback? streamMessage;

The SDK triggers this callback when the local user receives the stream message that the remote user sends by calling the sendStreamMessage method.

Return values

A callback object that includes the following parameters:

uid: The ID of the remote user sending the message.
streamId: The stream ID of the received message.
data: The data received.

streamMessageError

Occurs when the local user does not receive the data stream from the remote user.

StreamMessageErrorCallback? streamMessageError;

The SDK triggers this callback when the local user fails to receive the stream message that the remote user sends by calling the sendStreamMessage method.

Return values

A callback object that includes the following parameters:

uid: The ID of the remote user sending the message.
streamId: The stream ID of the received message.
error: The error code.
missed: The number of lost messages.
cached: Number of incoming cached messages when the data stream is interrupted.

tokenPrivilegeWillExpire

Occurs when the token expires in 30 seconds.

TokenCallback? tokenPrivilegeWillExpire;

When the token is about to expire in 30 seconds, the SDK triggers this callback to remind the app to renew the token. Upon receiving this callback, generate a new token on your server, and call renewToken to pass the new token to the SDK.

Return values

A callback object that includes the following parameters:

token: The token that expires in 30 seconds.

transcodingUpdated

Occurs when the publisher's transcoding is updated.

EmptyCallback? transcodingUpdated;

When the LiveTranscoding class in the setLiveTranscoding method updates, the SDK triggers the transcodingUpdated callback to report the update information.

Attention: If you call the setLiveTranscoding method to set the LiveTranscoding class for the first time, the SDK does not trigger this callback.

userJoined

Occurs when a remote user (COMMUNICATION)/ host (LIVE_BROADCASTING) joins the channel.

UidWithElapsedCallback? userJoined;

In a communication channel, this callback indicates that a remote user joins the channel. The SDK also triggers this callback to report the existing users in the channel when a user joins the channel.
In a live-broadcast channel, this callback indicates that a host joins the channel. The SDK also triggers this callback to report the existing hosts in the channel when a host joins the channel. Agora recommends limiting the number of hosts to 17.

The SDK triggers this callback under one of the following circumstances:

A remote user/host joins the channel by calling the joinChannel method.
A remote user switches the user role to the host after joining the channel.
A remote user/host rejoins the channel after a network interruption.

Return values

A callback object that includes the following parameters:

uid: The ID of the user or host who joins the channel.
elapsed: Time delay (ms) fromthe local user calling joinChannel until this callback is triggered.

userOffline

Occurs when a remote user (COMMUNICATION)/ host (LIVE_BROADCASTING) leaves the channel.

UserOfflineCallback? userOffline;

There are two reasons for users to become offline:

Leave the channel: When a user/host leaves the channel, the user/host sends a goodbye message. When this message is received, the SDK determines that the user/host leaves the channel.
Drop offline: When no data packet of the user or host is received for a certain period of time (20 seconds for the communication profile, and more for the live broadcast profile), the SDK assumes that the user/host drops offline. A poor network connection may lead to false detections. It's recommended to use the Agora RTM SDK for reliable offline detection.

Return values

A callback object that includes the following parameters:

uid: The ID of the user who leaves the channel or goes offline.
reason: Reasons why the user goes offline: UserOfflineReason.

userSuperResolutionEnabled

Reports whether the super resolution feature is successfully enabled.

UserSuperResolutionEnabledCallback? userSuperResolutionEnabled;

After calling enableRemoteSuperResolution, the SDK triggers the callback to report whether super resolution is successfully enabled. If it is not successfully enabled, use reason for troubleshooting.

Return values

A callback object that includes the following parameters:

uid

The ID of the remote user.

enabled

Whether super resolution is successfully enabled:

true: Super resolution is successfully enabled.
false: Super resolution is not successfully enabled.

reason

The reason why super resolution algorithm is not successfully enabled. For details, see SuperResolutionStateReason.

videoPublishStateChanged

Occurs when the video publishing state changes.

StreamPublishStateCallback? videoPublishStateChanged;

Return values

A callback object that includes the following parameters:

oldState: For the previous publishing state, see StreamPublishState.
newState: For the current publishing state, see StreamPublishState.
elapseSinceLastState: The time elapsed (ms) from the previous state to the current state.

videoSizeChanged

Occurs when the video size or rotation of a specified user changes.

VideoSizeCallback? videoSizeChanged;

Return values

A callback object that includes the following parameters:

uid: The ID of the user whose video size or rotation changes. uid is 0 for the local user.
width: The width (pixels) of the video stream.
height: The height (pixels) of the video stream.
rotation: The rotation information. The value range is [0,360).

videoSubscribeStateChanged

Occurs when the video subscribing state changes.

StreamSubscribeStateCallback? videoSubscribeStateChanged;

Return values

A callback object that includes the following parameters:

uid: The ID of the remote user.
oldState: The previous subscribing status, see StreamSubscribeState for details.
newState: The current subscribing status, see StreamSubscribeState for details.
elapseSinceLastState: The time elapsed (ms) from the previous state to the current state.