Agora Java API Reference for Android
io.agora.rtc.IRtcEngineEventHandler Class Referenceabstract

Classes

class  AgoraFacePositionInfo
 
class  AudioFileInfo
 
class  AudioVolumeInfo
 
class  ClientRole
 
class  ErrorCode
 
class  ExperiencePoorReason
 
class  ExperienceQuality
 
class  LastmileProbeResult
 
class  LocalAudioStats
 
class  LocalVideoStats
 
class  Quality
 
class  RemoteAudioStats
 
class  RemoteVideoStats
 
class  RtcStats
 
class  UserOfflineReason
 
class  VideoProfile
 
class  WarnCode
 

Public Member Functions

void onWarning (int warn)
 
void onError (int err)
 
void onJoinChannelSuccess (String channel, int uid, int elapsed)
 
void onRejoinChannelSuccess (String channel, int uid, int elapsed)
 
void onLeaveChannel (RtcStats stats)
 
void onClientRoleChanged (int oldRole, int newRole)
 
void onLocalUserRegistered (int uid, String userAccount)
 
void onUserInfoUpdated (int uid, UserInfo userInfo)
 
void onUserJoined (int uid, int elapsed)
 
void onUserOffline (int uid, int reason)
 
void onProxyConnected (String channel, int uid, int proxyType, String localProxyIp, int elapsed)
 
void onConnectionStateChanged (int state, int reason)
 
void onConnectionInterrupted ()
 
void onConnectionLost ()
 
void onConnectionBanned ()
 
void onApiCallExecuted (int error, String api, String result)
 
void onTokenPrivilegeWillExpire (String token)
 
void onRequestToken ()
 
void onMicrophoneEnabled (boolean enabled)
 
void onAudioVolumeIndication (AudioVolumeInfo[] speakers, int totalVolume)
 
void onLocalVoicePitchInHz (int pitchInHz)
 
void onActiveSpeaker (int uid)
 
void onFirstLocalAudioFrame (int elapsed)
 
void onFirstLocalAudioFramePublished (int elapsed)
 
void onFirstRemoteAudioFrame (int uid, int elapsed)
 
void onVideoStopped ()
 
void onFirstLocalVideoFrame (int width, int height, int elapsed)
 
void onFirstLocalVideoFramePublished (int elapsed)
 
void onFirstRemoteVideoDecoded (int uid, int width, int height, int elapsed)
 
void onFirstRemoteVideoFrame (int uid, int width, int height, int elapsed)
 
void onUserMuteAudio (int uid, boolean muted)
 
void onUserMuteVideo (int uid, boolean muted)
 
void onUserEnableVideo (int uid, boolean enabled)
 
void onUserEnableLocalVideo (int uid, boolean enabled)
 
void onVideoSizeChanged (int uid, int width, int height, int rotation)
 
void onRemoteAudioStateChanged (int uid, int state, int reason, int elapsed)
 
void onAudioPublishStateChanged (String channel, int oldState, int newState, int elapseSinceLastState)
 
void onVideoPublishStateChanged (String channel, int oldState, int newState, int elapseSinceLastState)
 
void onAudioSubscribeStateChanged (String channel, int uid, int oldState, int newState, int elapseSinceLastState)
 
void onVideoSubscribeStateChanged (String channel, int uid, int oldState, int newState, int elapseSinceLastState)
 
void onRemoteVideoStateChanged (int uid, int state, int reason, int elapsed)
 
void onUserSuperResolutionEnabled (int uid, boolean enabled, int reason)
 
void onVirtualBackgroundSourceEnabled (boolean enabled, int reason)
 
void onSnapshotTaken (String channel, int uid, String filePath, int width, int height, int errCode)
 
void onChannelMediaRelayStateChanged (int state, int code)
 
void onChannelMediaRelayEvent (int code)
 
void onLocalPublishFallbackToAudioOnly (boolean isFallbackOrRecover)
 
void onRemoteSubscribeFallbackToAudioOnly (int uid, boolean isFallbackOrRecover)
 
void onAudioRouteChanged (int routing)
 
void onCameraReady ()
 
void onCameraFocusAreaChanged (Rect rect)
 
void onCameraExposureAreaChanged (Rect rect)
 
void onFacePositionChanged (int imageWidth, int imageHeight, AgoraFacePositionInfo[] faces)
 
void onAudioQuality (int uid, int quality, short delay, short lost)
 
void onRtcStats (RtcStats stats)
 
void onLastmileQuality (int quality)
 
void onLastmileProbeResult (LastmileProbeResult result)
 
void onNetworkQuality (int uid, int txQuality, int rxQuality)
 
void onLocalVideoStats (LocalVideoStats stats)
 
void onRemoteVideoStats (RemoteVideoStats stats)
 
void onLocalAudioStats (LocalAudioStats stats)
 
void onRemoteAudioStats (RemoteAudioStats stats)
 
void onLocalVideoStat (int sentBitrate, int sentFrameRate)
 
void onRemoteVideoStat (int uid, int delay, int receivedBitrate, int receivedFrameRate)
 
void onRemoteAudioTransportStats (int uid, int delay, int lost, int rxKBitRate)
 
void onRemoteVideoTransportStats (int uid, int delay, int lost, int rxKBitRate)
 
void onAudioMixingStateChanged (int state, int reason)
 
void onAudioMixingFinished ()
 
void onAudioEffectFinished (int soundId)
 
void onFirstRemoteAudioDecoded (int uid, int elapsed)
 
void onLocalAudioStateChanged (int state, int error)
 
void onRequestAudioFileInfo (AudioFileInfo info, int error)
 
void onLocalVideoStateChanged (int localVideoState, int error)
 
void onRtmpStreamingStateChanged (String url, int state, int errCode)
 
void onStreamPublished (String url, int error)
 
void onStreamUnpublished (String url)
 
void onTranscodingUpdated ()
 
void onRtmpStreamingEvent (String url, int error)
 
void onStreamMessage (int uid, int streamId, byte[] data)
 
void onStreamMessageError (int uid, int streamId, int error, int missed, int cached)
 
void onMediaEngineLoadSuccess ()
 
void onMediaEngineStartCallSuccess ()
 
void onNetworkTypeChanged (int type)
 
void onClientRoleChangeFailed (int reason, int currentRole)
 

Detailed Description

Callbacks.

The SDK uses the IRtcEngineEventHandler interface class to send callbacks to the application, and the application inherits the methods of this interface class to retrieve these callbacks. All methods in this interface class have their (empty) default implementations, and the application can inherit only some of the required events instead of all of them. In the callbacks, the application should avoid time-consuming tasks or call blocking APIs (such as SendMessage), otherwise, the SDK may not work properly.

Warning
To facilitate troubleshooting, as of this release, the SDK no longer catches exceptions that are thrown by your own code implementation when triggering callbacks in the IRtcEngineEventHandler class. You need to catch and handle the exceptions yourself; otherwise, it can cause a crash.

Member Function Documentation

◆ onWarning()

void io.agora.rtc.IRtcEngineEventHandler.onWarning ( int  warn)

Reports a warning during SDK runtime.

In most cases, the app can ignore the warning reported by the SDK because the SDK can usually fix the issue and resume running.

For instance, the SDK may report a WARN_LOOKUP_CHANNEL_TIMEOUT warning upon disconnection with the server and tries to reconnect. For detailed warning codes, see Warning Codes.

Parameters
warnWarning code

◆ onError()

void io.agora.rtc.IRtcEngineEventHandler.onError ( int  err)

Reports an error during SDK runtime.

In most cases, the SDK cannot fix the issue and resume running. The SDK requires the app to take action or informs the user about the issue.

For example, the SDK reports an ERR_START_CALL error when failing to initialize a call. The app informs the user that the call initialization failed and invokes the leaveChannel method to leave the channel. For detailed error codes, see Error Codes.

Parameters
errError code

◆ onJoinChannelSuccess()

void io.agora.rtc.IRtcEngineEventHandler.onJoinChannelSuccess ( String  channel,
int  uid,
int  elapsed 
)

Occurs when the local user joins a specified channel.

The channel name assignment is based on channelName specified in the joinChannel method.

If the uid is not specified when joinChannel is called, the server automatically assigns a uid.

Parameters
channelChannel name.
uidUser ID.
elapsedTime elapsed (ms) from the user calling joinChannel until this callback is triggered.

◆ onRejoinChannelSuccess()

void io.agora.rtc.IRtcEngineEventHandler.onRejoinChannelSuccess ( String  channel,
int  uid,
int  elapsed 
)

Occurs when a user rejoins the channel after being disconnected due to network problems.

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

Parameters
channelChannel name.
uidUser ID.
elapsedTime elapsed (ms) from the user calling joinChannel until the SDK triggers this callback.

◆ onLeaveChannel()

void io.agora.rtc.IRtcEngineEventHandler.onLeaveChannel ( RtcStats  stats)

Occurs when a user leaves the channel.

When the app calls the leaveChannel method, the SDK uses this callback to notify the app when the user leaves the channel.

With this callback, the application gets the channel information, such as the call duration and statistics.

Parameters
statsStatistics of the call: RtcStats

◆ onClientRoleChanged()

void io.agora.rtc.IRtcEngineEventHandler.onClientRoleChanged ( int  oldRole,
int  newRole 
)

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

In the LIVE_BROADCASTING channel profile, when the local user successfully calls setClientRole to switch their user role after joining the channel, for example, from a host to an audience member or vice versa, the SDK triggers this callback to report the user role before and after the switch.

Parameters
oldRoleRole that the user switches from:
  • CLIENT_ROLE_BROADCASTER(1): Host.
  • CLIENT_ROLE_AUDIENCE(2): Audience.
newRoleRole that the user switches to:
  • CLIENT_ROLE_BROADCASTER(1): Host.
  • CLIENT_ROLE_AUDIENCE(2): Audience.

◆ onLocalUserRegistered()

void io.agora.rtc.IRtcEngineEventHandler.onLocalUserRegistered ( int  uid,
String  userAccount 
)

Occurs when the local user registers a user account.

Since
v2.8.0.

This callback is triggered when the local user successfully registers a user account by calling the registerLocalUserAccount method, or joins a channel by calling the joinChannelWithUserAccount method. This callback reports the user ID and user account of the local user.

Parameters
uidThe ID of the local user.
userAccountThe user account of the local user.

◆ onUserInfoUpdated()

void io.agora.rtc.IRtcEngineEventHandler.onUserInfoUpdated ( int  uid,
UserInfo  userInfo 
)

Occurs when the SDK gets the user ID and user account of the remote user.

Since
v2.8.0.

After a remote user joins the channel, the SDK gets the UID and user account of the remote user, caches them in a mapping table object (UserInfo), and triggers this callback on the local client.

Parameters
uidThe ID of the remote user.
userInfoThe UserInfo object that contains the user ID and user account of the remote user.

◆ onUserJoined()

void io.agora.rtc.IRtcEngineEventHandler.onUserJoined ( int  uid,
int  elapsed 
)

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

  • COMMUNICATION profile: This callback notifies the app when another user joins the channel. If other users are already in the channel, the SDK also reports to the app on the existing users.
  • LIVE_BROADCASTING profile: This callback notifies the app when the host joins the channel. If other hosts are already in the channel, the SDK also reports to the app on the existing hosts. We recommend having at most 17 hosts in a channel.

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 by calling the setClientRole method after joining the channel.
  • A remote user/host rejoins the channel after a network interruption.
Parameters
uidID of the user or host who joins the channel.
elapsedTime delay (ms) from the local user calling joinChannel/setClientRole until this callback is triggered.
Note
In the LIVE_BROADCASTING profile:
  • The host receives the onUserJoined callback when another host joins the channel.
  • The audience in the channel receives the onUserJoined callback when a new host joins the channel.
  • When a web application joins the channel, the onUserJoined callback is triggered as long as the web application publishes streams.

◆ onUserOffline()

void io.agora.rtc.IRtcEngineEventHandler.onUserOffline ( int  uid,
int  reason 
)

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

There are two reasons for users to become offline:

  • Leave the channel: When the 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, so we recommend using the signaling system for reliable offline detection.
Parameters
uidID of the user or host who leaves the channel or goes offline.
reasonReason why the user goes offline:
  • USER_OFFLINE_QUIT(0): The user left the current channel.
  • USER_OFFLINE_DROPPED(1): The SDK timed out and the user dropped offline because no data packet was received within a certain period of time. Note: If a user quits the call and the message is not passed to the SDK (due to an unreliable channel), the SDK assumes the user dropped offline. After the user kills the app with a gesture swipe, the SDK reports USER_OFFLINE_DROPPED(1) instead of USER_OFFLINE_QUIT(0) due to system limitations.
  • USER_OFFLINE_BECOME_AUDIENCE(2): (LIVE_BROADCASTING only.) The client role switched from the host to the audience.

◆ onProxyConnected()

void io.agora.rtc.IRtcEngineEventHandler.onProxyConnected ( String  channel,
int  uid,
int  proxyType,
String  localProxyIp,
int  elapsed 
)

Reports the proxy connection state.

Since
v3.6.2

You can use this callback to listen for the state of the SDK connecting to a proxy. For example, when a user calls setCloudProxy and joins a channel successfully, the SDK triggers this callback to report the user ID, the proxy type connected, and the time elapsed from the user calling joinChannel until this callback is triggered.

Parameters
channelThe channel name.
uidThe user ID.
proxyTypeThe proxy type connected:
localProxyIpReserved for future use.
elapsedThe time elapsed (ms) from the user calling joinChannel until this callback is triggered.

◆ onConnectionStateChanged()

void io.agora.rtc.IRtcEngineEventHandler.onConnectionStateChanged ( int  state,
int  reason 
)

Occurs when the network connection state changes.

Since
v2.3.2.

The Agora SDK returns this callback to report on the current network connection state when it changes, and the reason to such change.

Parameters
stateThe current network connection state:
reasonThe reason causing the change of the connection state:

◆ onConnectionInterrupted()

void io.agora.rtc.IRtcEngineEventHandler.onConnectionInterrupted ( )

Occurs when the connection between the SDK and the server is interrupted.

Deprecated:
From v2.3.2. Use onConnectionStateChanged instead.

The SDK triggers this callback when it loses connection to the server for more than four seconds after the connection is established. After triggering this callback, the SDK tries to reconnect to the server. You can use this callback to implement pop-up reminders. This callback is different from onConnectionLost:

  • The SDK triggers the onConnectionInterrupted callback when the SDK loses connection with the server for more than four seconds after it joins the channel.
  • The SDK triggers the onConnectionLost callback when it loses connection with the server for more than 10 seconds, regardless of whether it joins the channel or not.

If the SDK fails to rejoin the channel 20 minutes after being disconnected from Agora edge server, the SDK stops rejoining the channel.

◆ onConnectionLost()

void io.agora.rtc.IRtcEngineEventHandler.onConnectionLost ( )

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

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

If the SDK fails to rejoin the channel 20 minutes after being disconnected from Agora edge server, the SDK stops rejoining the channel.

◆ onConnectionBanned()

void io.agora.rtc.IRtcEngineEventHandler.onConnectionBanned ( )

Occurs when your connection is banned by the Agora Server.

Deprecated:
From v2.3.2. Use onConnectionStateChanged instead.

◆ onApiCallExecuted()

void io.agora.rtc.IRtcEngineEventHandler.onApiCallExecuted ( int  error,
String  api,
String  result 
)

Occurs when an API method is executed.

Parameters
errorError Code that the SDK returns when the method call fails. If the SDK returns 0, then the method call was successful.
apiThe method executed by the SDK.
resultThe result of the method call.

◆ onTokenPrivilegeWillExpire()

void io.agora.rtc.IRtcEngineEventHandler.onTokenPrivilegeWillExpire ( String  token)

Occurs when the token expires in 30 seconds.

The user becomes offline if the token used when joining the channel expires. This callback is triggered 30 seconds before the token expires to remind the app to get a new token. Upon receiving this callback, you need to generate a new token on the server and call renewToken to pass the new token to the SDK.

Parameters
tokenThe token that will expire in 30 seconds.

◆ onRequestToken()

void io.agora.rtc.IRtcEngineEventHandler.onRequestToken ( )

Occurs when the token has expired.

After a token is specified when joining the channel, the token expires after a certain period of time, and a new token is required to reconnect to the server.

Once you receive this callback, generate a new token on your app server, and call renewToken to pass the new token to the SDK.

◆ onMicrophoneEnabled()

void io.agora.rtc.IRtcEngineEventHandler.onMicrophoneEnabled ( boolean  enabled)

Occurs when the microphone is enabled/disabled.

Deprecated:
v2.9.0. This callback is deprecated. Use LOCAL_AUDIO_STREAM_STATE_STOPPED(0) or LOCAL_AUDIO_STREAM_STATE_CAPTURING(1) in the onLocalAudioStateChanged callback instead.

The SDK triggers this callback when the local user resumes or stops capturing the local audio stream by calling the enableLocalAudio method.

Parameters
enabledWhether the microphone is enabled/disabled:
  • true: Enabled.
  • false: Disabled.

◆ onAudioVolumeIndication()

void io.agora.rtc.IRtcEngineEventHandler.onAudioVolumeIndication ( AudioVolumeInfo[]  speakers,
int  totalVolume 
)

Reports the volume information of users.

By default, this callback is disabled. You can enable it by calling enableAudioVolumeIndication. Once this callback is enabled and users send streams in the channel, the SDK triggers the onAudioVolumeIndication callback at the time interval set in enableAudioVolumeIndication.

The SDK triggers two independent onAudioVolumeIndication callbacks simultaneously, which separately report the volume information of the local user who sends a stream and the remote users (up to three) whose instantaneous volumes are the highest.

Note
After you enable this callback, calling muteLocalAudioStream affects the SDK's behavior as follows:
  • If the local user calls muteLocalAudioStream, the SDK stops triggering the local user's callback.
  • 20 seconds after a remote user whose volume is one of the three highest calls muteLocalAudioStream, the remote users' callback excludes this remote user's information; 20 seconds after all remote users call muteLocalAudioStream, the SDK stops triggering the remote users' callback.
Parameters
speakersThe volume information of users. See AudioVolumeInfo. An empty speakers array in the callback indicates that no remote user is in the channel or sending a stream at the moment.
totalVolumeTotal volume after audio mixing. The value ranges between 0 (lowest volume) and 255 (highest volume).
  • In the local user's callback, totalVolume is the volume of the local user who sends a stream.
  • In the remote users' callback, totalVolume is the sum of the volume of all remote users (up to three) whose instantaneous volumes are the highest. If the user calls startAudioMixing, totalVolume is the sum of the voice volume and audio-mixing volume.

◆ onLocalVoicePitchInHz()

void io.agora.rtc.IRtcEngineEventHandler.onLocalVoicePitchInHz ( int  pitchInHz)

Reports the voice pitch of the local user.

Since
v3.7.0

After the local audio capture is enabled and you call enableLocalVoicePitchCallback, the SDK triggers the onLocalVoicePitchInHz callback at the time interval set in enableLocalVoicePitchCallback.

Note
After this callback is enabled, if the user disables the local audio capture, for example, by calling enableLocalAudio(false), the SDK immediately stops sending the onLocalVoicePitchInHz callback.
Parameters
pitchInHzThe voice pitch (Hz) of the local user.

◆ onActiveSpeaker()

void io.agora.rtc.IRtcEngineEventHandler.onActiveSpeaker ( int  uid)

Occurs when the most active remote speaker is detected.

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 user is no less than two and an active speaker exists, the SDK triggers this callback and reports the uid of the most active speaker.

  • If the most active speaker is always the same user, the SDK triggers this 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.
Parameters
uidThe user ID of the most active remote speaker.

◆ onFirstLocalAudioFrame()

void io.agora.rtc.IRtcEngineEventHandler.onFirstLocalAudioFrame ( int  elapsed)

Occurs when the first local audio frame is sent.

Deprecated:
Deprecated as of v3.1.0. Use IRtcEngineEventHandler#onFirstLocalAudioFramePublished() instead.
Parameters
elapsedTime elapsed (ms) from the local user calling the joinChannel until this callback is triggered.

◆ onFirstLocalAudioFramePublished()

void io.agora.rtc.IRtcEngineEventHandler.onFirstLocalAudioFramePublished ( int  elapsed)

Occurs when the first audio frame is published.

Since
v3.1.0.

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

Parameters
elapsedThe time elapsed (ms) from the local client calling joinChannel until the SDK triggers this callback.

◆ onFirstRemoteAudioFrame()

void io.agora.rtc.IRtcEngineEventHandler.onFirstRemoteAudioFrame ( int  uid,
int  elapsed 
)

Occurs when the first remote audio frame is received.

Deprecated:
v3.0.0. Use REMOTE_AUDIO_STATE_STARTING(1) in onRemoteAudioStateChanged instead.
Parameters
uidUser ID of the remote user.
elapsedTime elapsed (ms) from the local user calling the joinChannel method until this callback is triggered.

◆ onVideoStopped()

void io.agora.rtc.IRtcEngineEventHandler.onVideoStopped ( )

Occurs when the video stops playing.

Deprecated:
From v2.4.1. Use LOCAL_VIDEO_STREAM_STATE_STOPPED(0) in the onLocalVideoStateChanged callback instead. The application can use this callback to change the configuration of the view (for example, displaying other pictures in the view) after the video stops playing.

◆ onFirstLocalVideoFrame()

void io.agora.rtc.IRtcEngineEventHandler.onFirstLocalVideoFrame ( int  width,
int  height,
int  elapsed 
)

Occurs when the first local video frame is rendered.

This callback is triggered after the first local video frame is rendered on the local video window.

Parameters
widthWidth (pixels) of the first local video frame.
heightHeight (pixels) of the first local video frame.
elapsedTime elapsed (ms) from the local user calling joinChannel until this callback is triggered. If startPreview is called before joinChannel, elapsed is the time elapsed (ms) from the local user calling startPreview until this callback is triggered.

◆ onFirstLocalVideoFramePublished()

void io.agora.rtc.IRtcEngineEventHandler.onFirstLocalVideoFramePublished ( int  elapsed)

Occurs when the first video frame is published.

Since
v3.1.0.

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

Parameters
elapsedThe time elapsed (ms) from the local client calling joinChannel until the SDK triggers this callback.

◆ onFirstRemoteVideoDecoded()

void io.agora.rtc.IRtcEngineEventHandler.onFirstRemoteVideoDecoded ( int  uid,
int  width,
int  height,
int  elapsed 
)

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

You can also use REMOTE_VIDEO_STATE_STARTING(1) or REMOTE_VIDEO_STATE_DECODING(2) in the onRemoteVideoStateChanged callback instead.

This callback is triggered in either of the following scenarios:

  • The remote user joins the channel and sends the video stream.
  • The remote user stops sending the video stream and re-sends it after 15 seconds. Possible reasons include:
    • The remote user leaves channel.
    • The remote user drops offline.
    • The remote user calls the muteLocalVideoStream method.
    • The remote user calls the disableVideo method.
Parameters
uidUser ID of the remote user sending the video streams.
widthWidth (pixels) of the video stream.
heightHeight (pixels) of the video stream.
elapsedTime elapsed (ms) from the local user calling the joinChannel method until this callback is triggered.

◆ onFirstRemoteVideoFrame()

void io.agora.rtc.IRtcEngineEventHandler.onFirstRemoteVideoFrame ( int  uid,
int  width,
int  height,
int  elapsed 
)

Occurs when the first remote video frame is rendered.

This callback is triggered after the first frame of the remote video is rendered on the video window. The application can get the data of the time elapsed from the user joining the channel until the first video frame is displayed.

Parameters
uidUser ID of the remote user sending the video streams.
widthWidth (pixels) of the video stream.
heightHeight (pixels) of the video stream.
elapsedTime elapsed (ms) from the local user calling the joinChannel method until this callback is triggered.

◆ onUserMuteAudio()

void io.agora.rtc.IRtcEngineEventHandler.onUserMuteAudio ( int  uid,
boolean  muted 
)

Occurs when a remote user stops/resumes sending the audio stream.

The SDK triggers this callback when the remote user stops or resumes sending the audio stream by calling the muteLocalAudioStream method.

Note
This callback can be inaccurate when the number of users (in the COMMUNICATION profile) or hosts (in the LIVE_BROADCASTING profile) in a channel exceeds 17.
Parameters
uidID of the remote user.
mutedWhether the remote user's audio stream is muted/unmuted:
  • true: Muted.
  • false: Unmuted.

◆ onUserMuteVideo()

void io.agora.rtc.IRtcEngineEventHandler.onUserMuteVideo ( int  uid,
boolean  muted 
)

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

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

Note
This callback can be inaccurate when the number of users (in the COMMUNICATION profile) or hosts (in the LIVE_BROADCASTING profile) in a channel exceeds 17.
Parameters
uidThe user ID of the remote user.
mutedWhether the remote user stops publishing the video stream
  • true: Stop publishing the video stream.
  • false: Publish the video stream.

◆ onUserEnableVideo()

void io.agora.rtc.IRtcEngineEventHandler.onUserEnableVideo ( int  uid,
boolean  enabled 
)

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

Once the video module is disabled, the remote user can only use a voice call. The remote user cannot send or receive any video from other users.

The SDK triggers this callback when the remote user enables or disables the video module by calling the enableVideo or disableVideo method.

Note
This callback is invalid when the number of users or hosts in the channel exceeds 20.
Parameters
uidUser ID of the remote user.
enabledWhether the specific remote user enables/disables the video module:
  • true: Enable. The remote user can enter a video session.
  • false: Disable. The remote user can only enter a voice session, and cannot send or receive any video stream.

◆ onUserEnableLocalVideo()

void io.agora.rtc.IRtcEngineEventHandler.onUserEnableLocalVideo ( int  uid,
boolean  enabled 
)

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

The SDK triggers this callback when the remote user resumes or stops capturing the video stream by calling the enableLocalVideo method.

This callback is only applicable to the scenario when the remote user only wants to watch the remote video without sending any video stream to the other user.

Parameters
uidUser ID of the remote user.
enabledWhether the specific remote user enables/disables the local video capturing function:
  • true: Enabled. Other users in the channel can see the video of this remote user.
  • false: Disabled. Other users in the channel can no longer receive the video stream from this remote user, while this remote user can still receive the video streams from other users.

◆ onVideoSizeChanged()

void io.agora.rtc.IRtcEngineEventHandler.onVideoSizeChanged ( int  uid,
int  width,
int  height,
int  rotation 
)

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

Parameters
uidUser ID of the remote user or local user (0) whose video size or rotation changes.
widthNew width (pixels) of the video.
heightNew height (pixels) of the video.
rotationNew rotation of the video [0 to 360).

◆ onRemoteAudioStateChanged()

void io.agora.rtc.IRtcEngineEventHandler.onRemoteAudioStateChanged ( int  uid,
int  state,
int  reason,
int  elapsed 
)

Occurs when the remote audio state changes.

Since
v2.9.0.

This callback indicates the state change of the remote audio stream.

Note
This callback can be inaccurate when the number of users (in the COMMUNICATION profile) or hosts (in the LIVE_BROADCASTING profile) in a channel exceeds 17.
Parameters
uidID of the user whose audio state changes.
stateState of the remote audio:
  • REMOTE_AUDIO_STATE_STOPPED(0): The remote audio is in the default state, probably due to REMOTE_AUDIO_REASON_LOCAL_MUTED(3), REMOTE_AUDIO_REASON_REMOTE_MUTED(5), or REMOTE_AUDIO_REASON_REMOTE_OFFLINE(7).
  • REMOTE_AUDIO_STATE_STARTING(1): The first remote audio packet is received.
  • REMOTE_AUDIO_STATE_DECODING(2): The remote audio stream is decoded and plays normally, probably due to REMOTE_AUDIO_REASON_NETWORK_RECOVERY(2), REMOTE_AUDIO_REASON_LOCAL_UNMUTED(4) or REMOTE_AUDIO_REASON_REMOTE_UNMUTED(6).
  • REMOTE_AUDIO_STATE_FROZEN(3): The remote audio is frozen, probably due to REMOTE_AUDIO_REASON_NETWORK_CONGESTION(1).
  • REMOTE_AUDIO_STATE_FAILED(4): The remote audio fails to start, probably due to REMOTE_AUDIO_REASON_INTERNAL(0).
reasonThe reason of the remote audio state change.
  • REMOTE_AUDIO_REASON_INTERNAL(0): The SDK reports this reason when the audio state changes.
  • REMOTE_AUDIO_REASON_NETWORK_CONGESTION(1): The remote user's network is congested. If the network conditions are persistently poor, display a pop-up box in the application that says "The remote user's network conditions are poor".
  • REMOTE_AUDIO_REASON_NETWORK_RECOVERY(2): The remote user's network conditions are restored from congested to normal. You can display a pop-up box in the application that says "The remote user's network conditions have improved".
  • REMOTE_AUDIO_REASON_LOCAL_MUTED(3): The local user stops receiving the remote audio stream or disables the audio module. You can display a pop-up box in the application that says "You have muted the remote user".
  • REMOTE_AUDIO_REASON_LOCAL_UNMUTED(4): The local user resumes receiving the remote audio stream or enables the audio module. You can display a pop-up box in the application that says "You have unmuted the remote user".
  • REMOTE_AUDIO_REASON_REMOTE_MUTED(5): The remote user stops sending the audio stream or disables the audio module. You can use an icon in the list of users in the application user interface to show that the remote user is muted and display a pop-up box in the application that says "The remote user has muted themselves".
  • REMOTE_AUDIO_REASON_REMOTE_UNMUTED(6): The remote user resumes sending the audio stream or enables the audio module. You can use an icon in the list of users in the application user interface to show that the remote user is unmuted and display a pop-up box in the application that says "The remote user has unmuted themselves".
  • REMOTE_AUDIO_REASON_REMOTE_OFFLINE(7): The remote user leaves the channel. You can remove the remote user from the user list in the application user interface.
elapsedTime elapsed (ms) from the local user calling the joinChannel method until the SDK triggers this callback.

◆ onAudioPublishStateChanged()

void io.agora.rtc.IRtcEngineEventHandler.onAudioPublishStateChanged ( String  channel,
int  oldState,
int  newState,
int  elapseSinceLastState 
)

Occurs when the audio publishing state changes.

Since
v3.1.0.

This callback indicates the publishing state change of the local audio stream.

The publishing states include:

Parameters
channelThe channel name.
oldStateThe previous publishing state.
newStateThe current publishing state.
elapseSinceLastStateThe time elapsed (ms) from the previous state to the current state.

◆ onVideoPublishStateChanged()

void io.agora.rtc.IRtcEngineEventHandler.onVideoPublishStateChanged ( String  channel,
int  oldState,
int  newState,
int  elapseSinceLastState 
)

Occurs when the local video publishing state changes.

Since
v3.1.0.

This callback indicates the publishing state change of the local video stream.

The publishing states include:

Parameters
channelThe channel name.
oldStateThe previous publishing state.
newStateThe current publishing state.
elapseSinceLastStateThe time elapsed (ms) from the previous state to the current state.

◆ onAudioSubscribeStateChanged()

void io.agora.rtc.IRtcEngineEventHandler.onAudioSubscribeStateChanged ( String  channel,
int  uid,
int  oldState,
int  newState,
int  elapseSinceLastState 
)

Occurs when the remote audio subscribing state changes.

Since
v3.1.0.

This callback indicates the subscribing state change of the remote audio stream.

The subscribing states include:

Parameters
channelThe channel name.
uidThe ID of the remote user whose audio subscribing state changes.
oldStateThe previous subscribing state.
newStateThe current subscribing state.
elapseSinceLastStateThe time elapsed (ms) from the previous state to the current state.

◆ onVideoSubscribeStateChanged()

void io.agora.rtc.IRtcEngineEventHandler.onVideoSubscribeStateChanged ( String  channel,
int  uid,
int  oldState,
int  newState,
int  elapseSinceLastState 
)

Occurs when the remote video subscribe state changes.

Since
v3.1.0.

This callback indicates the subscribe state change of the remote video stream.

The subscribing states include:

Parameters
channelThe channel name.
uidThe ID of the remote user whose video subscribe state changes.
oldStateThe previous subscribing state.
newStateThe current subscribing state.
elapseSinceLastStateThe time elapsed (ms) from the previous state to the current state.

◆ onRemoteVideoStateChanged()

void io.agora.rtc.IRtcEngineEventHandler.onRemoteVideoStateChanged ( int  uid,
int  state,
int  reason,
int  elapsed 
)

Occurs when the remote video state changes.

Since
v2.9.0.
Note
This callback can be inaccurate when the number of users (in the COMMUNICATION profile) or hosts (in the LIVE_BROADCASTING profile) in a channel exceeds 17.
Parameters
uidID of the remote user whose video state changes.
stateState of the remote video:
  • REMOTE_VIDEO_STATE_STOPPED(0): The remote video is in the default state, probably due to REMOTE_VIDEO_STATE_REASON_LOCAL_MUTED(3), REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED(5), or REMOTE_VIDEO_STATE_REASON_REMOTE_OFFLINE(7).
  • REMOTE_VIDEO_STATE_STARTING(1): The first remote video packet is received.
  • REMOTE_VIDEO_STATE_DECODING(2): The remote video stream is decoded and plays normally, probably due to REMOTE_VIDEO_STATE_REASON_NETWORK_RECOVERY (2), REMOTE_VIDEO_STATE_REASON_LOCAL_UNMUTED(4), REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED(6), or REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK_RECOVERY(9).
  • REMOTE_VIDEO_STATE_FROZEN(3): The remote video is frozen, probably due to REMOTE_VIDEO_STATE_REASON_NETWORK_CONGESTION(1) or REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK(8).
  • REMOTE_VIDEO_STATE_FAILED(4): The remote video fails to start, probably due to REMOTE_VIDEO_STATE_REASON_INTERNAL(0).
reasonThe reason of the remote video state change:
  • REMOTE_VIDEO_STATE_REASON_INTERNAL(0): The SDK reports this reason when the video state changes.
  • REMOTE_VIDEO_STATE_REASON_NETWORK_CONGESTION(1): The remote user's network is congested. If the network conditions are persistently poor, display a pop-up box in the application that says "The remote user's network conditions are poor".
  • REMOTE_VIDEO_STATE_REASON_NETWORK_RECOVERY(2): The remote user's network conditions are restored from congested to normal. You can display a pop-up box in the application that says "The remote user's network conditions have improved".
  • REMOTE_VIDEO_STATE_REASON_LOCAL_MUTED(3): The local user stops receiving the remote video stream or disables the video module. You can close the window to render the remote user's video and display a pop-up box in the application that says "You have stopped receiving video from the remote user".
  • REMOTE_VIDEO_STATE_REASON_LOCAL_UNMUTED(4): The local user resumes receiving the remote video stream or enables the video module. You can restore the window to render the remote user's video and display a pop-up box in the application that says "You have resumed receiving video from the remote user".
  • REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED(5): The remote user stops sending the video stream or disables the video module. You can close the window to render the remote user's video, use an icon in the list of users in the application user interface to show that the remote user has stopped sending video, and display a pop-up box in the application that says "The remote user has disabled the camera".
  • REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED(6): The remote user resumes sending the video stream or enables the video module. You can restore the window to render the remote user's video, use an icon in the list of users in the application user interface to show that the remote user has resumed sending video, and display a pop-up box in the application that says "The remote user has enabled the camera".
  • REMOTE_VIDEO_STATE_REASON_REMOTE_OFFLINE(7): The remote user leaves the channel. You can close the window to render the remote user's video and remove the remote user from the user list in the application user interface.
  • REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK(8): The remote audio-and-video stream falls back to the audio-only stream due to poor network conditions. You can close the window to render the remote user's video and display a pop-up box in the application that says "The remote user's network conditions are poor".
  • REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK_RECOVERY(9): The remote audio-only stream switches back to the audio-and-video stream after the network conditions improve. You can restore the window to render the remote user's video and display a pop-up box in the application that says "The remote user's network conditions are poor".
  • REMOTE_VIDEO_STATE_REASON_SDK_IN_BACKGROUND(10): The SDK reports this error code to the local user when a remote user is using the iOS app and the app is in the background. In this case, the local user sees the remote user's video stuck.
elapsedTime elapsed (ms) from the local user calling the joinChannel method until the SDK triggers this callback.

◆ onUserSuperResolutionEnabled()

void io.agora.rtc.IRtcEngineEventHandler.onUserSuperResolutionEnabled ( int  uid,
boolean  enabled,
int  reason 
)

Reports whether the super resolution feature is successfully enabled. (beta feature)

Since
v3.5.1

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

Parameters
uidThe user ID of the remote user.
enabledWhether super resolution is successfully enabled:
  • true: Super resolution is successfully enabled.
  • false: Super resolution is not successfully enabled.
reasonThe reason why super resolution is not successfully enabled or the message that confirms success.

◆ onVirtualBackgroundSourceEnabled()

void io.agora.rtc.IRtcEngineEventHandler.onVirtualBackgroundSourceEnabled ( boolean  enabled,
int  reason 
)

Reports whether the virtual background is successfully enabled.

Since
v3.5.0

After you call enableVirtualBackground, the SDK triggers this callback to report whether the virtual background is successfully enabled.

Note
If the background image customized in the virtual background is in PNG or JPG format, the triggering of this callback is delayed until the image is read.
Parameters
enabledWhether the virtual background is successfully enabled:
  • true: The virtual background is successfully enabled.
  • false: The virtual background is not successfully enabled.
reasonThe reason why the virtual background is not successfully enabled or the message that confirms success:

◆ onSnapshotTaken()

void io.agora.rtc.IRtcEngineEventHandler.onSnapshotTaken ( String  channel,
int  uid,
String  filePath,
int  width,
int  height,
int  errCode 
)

Reports the result of taking a video snapshot.

Since
v3.5.2

After a successful takeSnapshot method call, the SDK triggers this callback to report whether the snapshot is successfully taken as well as the details for the snapshot taken.

Parameters
channelThe channel name.
uidThe user ID of the user. A uid of 0 indicates the local user.
filePathThe local path of the snapshot.
widthThe width (px) of the snapshot.
heightThe height (px) of the snapshot.
errCodeThe message that confirms success or the reason why the snapshot is not successfully taken:
  • 0: Success.
  • < 0: Failure.
    • -1: The SDK fails to write data to a file or encode a JPEG image.
    • -2: The SDK does not find the video stream of the specified user within one second after the takeSnapshot method call succeeds.

◆ onChannelMediaRelayStateChanged()

void io.agora.rtc.IRtcEngineEventHandler.onChannelMediaRelayStateChanged ( int  state,
int  code 
)

Occurs when the state of the media stream relay changes.

Since
v2.9.0.

The SDK reports the state of the current media relay and possible error messages in this callback.

Parameters
stateThe state code:
codeThe error code:

◆ onChannelMediaRelayEvent()

void io.agora.rtc.IRtcEngineEventHandler.onChannelMediaRelayEvent ( int  code)

Reports events during the media stream relay.

Since
v2.9.0.
Parameters
codeThe event code for media stream relay:

◆ onLocalPublishFallbackToAudioOnly()

void io.agora.rtc.IRtcEngineEventHandler.onLocalPublishFallbackToAudioOnly ( boolean  isFallbackOrRecover)

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

If you call setLocalPublishFallbackOption and set option as STREAM_FALLBACK_OPTION_AUDIO_ONLY(2), this callback is triggered when the locally published stream falls back to audio-only mode due to poor uplink conditions, or when the audio stream switches back to the video after the uplink network condition improves. Once the published stream falls back to audio only, the remote app receives the onRemoteVideoStateChanged callback.

Parameters
isFallbackOrRecoverWhether the published stream fell back to audio-only or switched back to the video:
  • true: The published stream fell back to audio-only due to poor network conditions.
  • false: The published stream switched back to the video after the network conditions improved.

◆ onRemoteSubscribeFallbackToAudioOnly()

void io.agora.rtc.IRtcEngineEventHandler.onRemoteSubscribeFallbackToAudioOnly ( int  uid,
boolean  isFallbackOrRecover 
)

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

If you call setRemoteSubscribeFallbackOption and set option as STREAM_FALLBACK_OPTION_AUDIO_ONLY(2), this callback is triggered when the remotely subscribed media stream falls back to audio-only mode due to poor downlink conditions, or when the remotely subscribed media stream switches back to the video after the downlink network condition improves.

Parameters
uidID of the remote user sending the stream.
isFallbackOrRecoverWhether the remote media stream fell back to audio-only or switched back to the video:
  • true: The remote media stream fell back to audio-only due to poor network conditions.
  • false: The remote media stream switched back to the video stream after the network conditions improved.
Note
Once the remote media stream is switched to the low stream due to poor network conditions, you can monitor the stream switch between a high and low stream in the onRemoteVideoStats callback.

◆ onAudioRouteChanged()

void io.agora.rtc.IRtcEngineEventHandler.onAudioRouteChanged ( int  routing)

Occurs when the local audio playback route changes.

Parameters
routingThe current audio routing:

◆ onCameraReady()

void io.agora.rtc.IRtcEngineEventHandler.onCameraReady ( )

Occurs when the camera is turned on and ready to capture video.

Deprecated:
From v2.4.1. Use LOCAL_VIDEO_STREAM_STATE_CAPTURING(1) in the onLocalVideoStateChanged callback instead. If the camera fails to turn on, fix the error reported in the onError callback.

◆ onCameraFocusAreaChanged()

void io.agora.rtc.IRtcEngineEventHandler.onCameraFocusAreaChanged ( Rect  rect)

Occurs when the camera focus area is changed.

The SDK triggers this callback when the local user changes the camera focus position by calling the setCameraFocusPositionInPreview method.

Parameters
rectRectangular area in the camera zoom specifying the focus area.

◆ onCameraExposureAreaChanged()

void io.agora.rtc.IRtcEngineEventHandler.onCameraExposureAreaChanged ( Rect  rect)

The camera exposure area has changed.

The SDK triggers this callback when the local user changes the camera exposure position by calling the setCameraExposurePosition method.

Since
v2.3.2.
Parameters
rectRectangular area in the camera zoom specifying the exposure area.

◆ onFacePositionChanged()

void io.agora.rtc.IRtcEngineEventHandler.onFacePositionChanged ( int  imageWidth,
int  imageHeight,
AgoraFacePositionInfo[]  faces 
)

Reports the face detection result of the local user.

Since
3.0.1

Once you enable face detection by calling enableFaceDetection, you can get the following information on the local user in real-time:

  • The width and height of the local video.
  • The position of the human face in the local view.
  • The distance between the human face and the device screen. This value is based on the fitting calculation of the local video size and the position of the human face.
Note
  • If the SDK does not detect a face, it reduces the frequency of this callback to reduce power consumption on the local device.
  • The SDK stops triggering this callback when a human face is in close proximity to the screen.
  • The distance value reported in this callback may be slightly different from the actual distance. Therefore, Agora does not recommend using it for accurate calculation.
Parameters
imageWidthThe width (px) of the local video.
imageHeightThe height (px) of the local video.
facesThe information of the detected human face. For details, see AgoraFacePositionInfo. The number of the AgoraFacePositionInfo array depends on the number of human faces detected. If the array length is 0, it means that no human face is detected.

◆ onAudioQuality()

void io.agora.rtc.IRtcEngineEventHandler.onAudioQuality ( int  uid,
int  quality,
short  delay,
short  lost 
)

Reports the statistics of the audio stream from each remote user/host.

Deprecated:
From v2.3.2. Use onRemoteAudioStats instead.

The SDK triggers this callback once every two seconds to report the audio quality of each remote user/host sending an audio stream. If a channel has multiple remote users/hosts sending audio streams, the SDK triggers this callback as many times.

Parameters
uidUser ID of the speaker.
qualityAudio quality of the user:
delayTime delay (ms) of the audio packet from the sender to the receiver, including the time delay from audio sampling pre-processing, transmission, and the jitter buffer.
lostPacket loss rate (%) of the audio packet sent from the sender to the receiver.

◆ onRtcStats()

void io.agora.rtc.IRtcEngineEventHandler.onRtcStats ( RtcStats  stats)

Reports the statistics of the RtcEngine once every two seconds.

Parameters
statsRTC engine statistics: RtcStats.

◆ onLastmileQuality()

void io.agora.rtc.IRtcEngineEventHandler.onLastmileQuality ( int  quality)

Reports the last mile network quality of the local user once every two seconds before the user joins the channel. Last mile refers to the connection between the local device and Agora edge server. After the application calls the enableLastmileTest method, this callback reports once every two seconds the uplink and downlink last mile network conditions of the local user before the user joins the channel.

Parameters
qualityThe last mile network quality based on the uplink and downlink packet loss rate and jitter:

◆ onLastmileProbeResult()

void io.agora.rtc.IRtcEngineEventHandler.onLastmileProbeResult ( LastmileProbeResult  result)

Reports the last-mile network probe result.

Since
v2.4.0.

The SDK triggers this callback within 30 seconds after the app calls the startLastmileProbeTest method.

Parameters
resultThe uplink and downlink last-mile network probe test result. For details, see LastmileProbeResult.

◆ onNetworkQuality()

void io.agora.rtc.IRtcEngineEventHandler.onNetworkQuality ( int  uid,
int  txQuality,
int  rxQuality 
)

Reports the last mile network quality of each user in the channel once every two seconds.

Last mile refers to the connection between the local device and Agora edge server. This callback reports once every two seconds the last mile network conditions of each user in the channel. If a channel includes multiple users, then this callback will be triggered as many times.

Note
txQuality is UNKNOWN when the user is not sending a stream; rxQuality is UNKNOWN when the user is not receiving a stream.
Parameters
uidUser ID. The network quality of the user with this uid is reported. If uid is 0, the local network quality is reported.
txQualityUplink transmission quality of the user in terms of the transmission bitrate, packet loss rate, average RTT (Round-Trip Time) and jitter of the uplink network. txQuality is a quality rating helping you understand how well the current uplink network conditions can support the selected VideoEncoderConfiguration. For example, a 1000 Kbps uplink network may be adequate for video frames with a resolution of 680 × 480 and a frame rate of 30 fps, but may be inadequate for resolutions higher than 1280 × 720.
rxQualityDownlink network quality rating of the user in terms of packet loss rate, average RTT, and jitter of the downlink network.

◆ onLocalVideoStats()

void io.agora.rtc.IRtcEngineEventHandler.onLocalVideoStats ( LocalVideoStats  stats)

Reports the statistics of the local video streams.

The SDK triggers this callback once every two seconds for each user/host. If there are multiple users/hosts in the channel, the SDK triggers this callback as many times.

Parameters
statsThe statistics of the local video stream. See LocalVideoStats.

◆ onRemoteVideoStats()

void io.agora.rtc.IRtcEngineEventHandler.onRemoteVideoStats ( RemoteVideoStats  stats)

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

Parameters
statsStatistics of the received remote video streams: RemoteVideoStats.

◆ onLocalAudioStats()

void io.agora.rtc.IRtcEngineEventHandler.onLocalAudioStats ( LocalAudioStats  stats)

Reports the statistics of the local audio stream.

Since
v2.9.0. The SDK triggers this callback once every two seconds.
Parameters
statsThe statistics of the local audio stream. See LocalAudioStats.

◆ onRemoteAudioStats()

void io.agora.rtc.IRtcEngineEventHandler.onRemoteAudioStats ( RemoteAudioStats  stats)

Reports the statistics of the audio stream from each remote user/host.

Since
v2.3.2. This method replaces the onAudioQuality callback.

The SDK triggers this callback once every two seconds for each remote user/host. If a channel includes multiple remote users, the SDK triggers this callback as many times.

Schemes such as FEC (Forward Error Correction) or retransmission counter the frame loss rate. Hence, users may find the overall audio quality acceptable even when the packet loss rate is high.

Parameters
statsStatistics of the received remote audio streams: RemoteAudioStats.

◆ onLocalVideoStat()

void io.agora.rtc.IRtcEngineEventHandler.onLocalVideoStat ( int  sentBitrate,
int  sentFrameRate 
)

Reports the statistics of the uploading local video streams.

Deprecated:
This method is deprecated. We recommend using onLocalVideoStats to get the local video statistics.
Parameters
sentBitrateData transmission bitrate (Kbps) since last count.
sentFrameRateData transmission frame rate (fps) since last count.

◆ onRemoteVideoStat()

void io.agora.rtc.IRtcEngineEventHandler.onRemoteVideoStat ( int  uid,
int  delay,
int  receivedBitrate,
int  receivedFrameRate 
)

Reports the statistics of the video stream from each remote user/host.

Deprecated:
This method is deprecated. We recommend using onRemoteVideoStats to get the remote video statistics.
Parameters
uidUser ID of the remote user sending the video streams.
delayTime delay (ms).
receivedBitrateData receiving bitrate (Kbps).
receivedFrameRateData receiving frame rate (fps).

◆ onRemoteAudioTransportStats()

void io.agora.rtc.IRtcEngineEventHandler.onRemoteAudioTransportStats ( int  uid,
int  delay,
int  lost,
int  rxKBitRate 
)

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

Deprecated:
This callback is deprecated. Use onRemoteAudioStats instead.

This callback reports the transport-layer statistics, such as the packet loss rate and time delay, once every two seconds after the local user receives an audio packet from a remote user.

Parameters
uidUser ID of the remote user sending the audio packet.
delayNetwork time delay (ms) from the remote user sending the audio packet to the local user.
lostPacket loss rate (%) of the audio packet sent from the remote user.
rxKBitRateReceived bitrate (Kbps) of the audio packet sent from the remote user.

◆ onRemoteVideoTransportStats()

void io.agora.rtc.IRtcEngineEventHandler.onRemoteVideoTransportStats ( int  uid,
int  delay,
int  lost,
int  rxKBitRate 
)

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

Deprecated:
This callback is deprecated. Use onRemoteVideoStats instead.

This callback reports the transport-layer statistics, such as the packet loss rate and time delay, once every two seconds after the local user receives the video packet from a remote user.

Parameters
uidUser ID of the remote user sending the video packet.
delayNetwork time delay (ms) from the remote user sending the video packet to the local user.
lostPacket loss rate (%) of the video packet sent from the remote user.
rxKBitRateReceived bitrate (Kbps) of the video packet sent from the remote user.

◆ onAudioMixingStateChanged()

void io.agora.rtc.IRtcEngineEventHandler.onAudioMixingStateChanged ( int  state,
int  reason 
)

Occurs when the playback state of the local user's music file changes.

Since
v3.4.0

When the playback state of the local user's music file changes, the SDK triggers this callback and reports the current playback state and the reason for the change.

Note
When you use startAudioMixing to play an online music file, the moment when the onAudioMixingStateChanged callback reports AUDIO_MIXING_STATE_PLAYING can be different from the moment when the user hears the music if network conditions are poor. Because the SDK triggers this callback to report the PLAYING state after decoding the first audio frame, but the SDK cannot receive online audio packets stably under poor network conditions, the music playback is unstable; and the moment when the user subjectively experiences the audio start playing can be later than the moment when the first audio frame is decoded.
Parameters
stateThe current music file playback state:
reasonThe reason for the change of the music file playback state:

◆ onAudioMixingFinished()

void io.agora.rtc.IRtcEngineEventHandler.onAudioMixingFinished ( )

Occurs when the audio mixing file playback finishes.

You can start an audio mixing file playback by calling the startAudioMixing method. This callback is triggered when the audio mixing file playback finishes.

If the startAudioMixing method call fails, an WARN_AUDIO_MIXING_OPEN_ERROR warning returns in the onWarning callback.

◆ onAudioEffectFinished()

void io.agora.rtc.IRtcEngineEventHandler.onAudioEffectFinished ( int  soundId)

Occurs when the audio effect file playback finishes.

You can start a local audio effect playback by calling the playEffect method. This callback is triggered when the local audio effect file playback finishes.

Parameters
soundIdID of the local audio effect. Each local audio effect has a unique ID.

◆ onFirstRemoteAudioDecoded()

void io.agora.rtc.IRtcEngineEventHandler.onFirstRemoteAudioDecoded ( int  uid,
int  elapsed 
)

Occurs when the engine receives the first audio frame from a specified remote user.

Deprecated:
v3.0.0. Use REMOTE_AUDIO_STATE_DECODING(2) in onRemoteAudioStateChanged instead.

This callback is triggered in either of the following scenarios:

  • The remote user joins the channel and sends the audio stream.
  • The remote user stops sending the audio stream and re-sends it after 15 seconds. Possible reasons include:
    • The remote user leaves channel.
    • The remote user drops offline.
    • The remote user calls the muteLocalAudioStream method.
    • The remote user calls the disableAudio method.
Parameters
uidUser ID of the remote user sending the audio stream.
elapsedThe time elapsed (ms) from the local user calling the joinChannel method until the SDK triggers this callback.

◆ onLocalAudioStateChanged()

void io.agora.rtc.IRtcEngineEventHandler.onLocalAudioStateChanged ( int  state,
int  error 
)

Occurs when the local audio stream state changes.

Since
v2.9.0.

This callback indicates the state change of the local audio stream, including the state of the audio sampling and encoding, and allows you to troubleshoot issues when exceptions occur.

Parameters
stateState of the local audio:
errorThe error information of the local audio:

◆ onRequestAudioFileInfo()

void io.agora.rtc.IRtcEngineEventHandler.onRequestAudioFileInfo ( AudioFileInfo  info,
int  error 
)

Reports the information of an audio file.

Since
v3.5.1

After successfully calling getAudioFileInfo, the SDK triggers this callback to report the information of the audio file, such as the file path and duration.

Parameters
infoThe information of an audio file. See AudioFileInfo.
errorThe information acquisition state:

◆ onLocalVideoStateChanged()

void io.agora.rtc.IRtcEngineEventHandler.onLocalVideoStateChanged ( int  localVideoState,
int  error 
)

Occurs when the local video state changes.

Since
v2.4.1.

The SDK returns the current video state in this callback.

The SDK triggers the onLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_FAILED,LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE) callback in the following situations:

  • (Android 9 or later) The application exits to the background, and the system recycles the camera.
  • (Android 6 or later) The camera is occupied by a third-party application.

    ‍When the third-party application releases the camera, the SDK triggers the onLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_CAPTURING,LOCAL_VIDEO_STREAM_ERROR_OK) callback.

    - The camera starts normally, but the captured video is not output for four seconds.

When the camera outputs the captured video frames, if all the video frames are the same for 15 consecutive frames, the SDK triggers the onLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_CAPTURING,LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE) callback. Note that the video frame duplication detection is only available for video frames with a resolution greater than 200 × 200, a frame rate greater than or equal to 10 fps, and a bitrate less than 20 Kbps.

During screen sharing, if the user doesn't grant screen capture permission to the application, the SDK triggers the onLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_FAILED,ERR_SCREEN_CAPTURE_PERMISSION_DENIED) callback.

Parameters
localVideoStateThe local video state:
errorThe detailed error information of the local video:

◆ onRtmpStreamingStateChanged()

void io.agora.rtc.IRtcEngineEventHandler.onRtmpStreamingStateChanged ( String  url,
int  state,
int  errCode 
)

Occurs when the state of the RTMP or RTMPS streaming changes.

Since
v2.4.1.

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.

This callback indicates the state of the RTMP or RTMPS streaming. When exceptions occur, you can troubleshoot issues by referring to the detailed error descriptions in the errCode parameter.

Parameters
urlThe CDN streaming URL.
stateThe RTMP or RTMPS streaming state:
errCodeThe detailed error information for streaming:

◆ onStreamPublished()

void io.agora.rtc.IRtcEngineEventHandler.onStreamPublished ( String  url,
int  error 
)

Reports the result of calling the addPublishStreamUrl method.

Deprecated:
v3.0.0. Use onRtmpStreamingStateChanged instead.

This callback indicates whether you have successfully added an RTMP or RTMPS stream to the CDN.

Parameters
urlThe CDN streaming URL.
errorThe detailed error information:

◆ onStreamUnpublished()

void io.agora.rtc.IRtcEngineEventHandler.onStreamUnpublished ( String  url)

Reports the result of calling the removePublishStreamUrl method.

Deprecated:
v3.0.0. Use onRtmpStreamingStateChanged instead.

This callback indicates whether you have successfully removed an RTMP or RTMPS stream from the CDN.

Parameters
urlThe CDN streaming URL.

◆ onTranscodingUpdated()

void io.agora.rtc.IRtcEngineEventHandler.onTranscodingUpdated ( )

Occurs when the publisher's transcoding settings are updated.

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

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

◆ onRtmpStreamingEvent()

void io.agora.rtc.IRtcEngineEventHandler.onRtmpStreamingEvent ( String  url,
int  error 
)

Reports events during the RTMP or RTMPS streaming.

Since
v3.1.0.
Parameters
urlThe CDN streaming URL.
errorThe event code.

◆ onStreamMessage()

void io.agora.rtc.IRtcEngineEventHandler.onStreamMessage ( int  uid,
int  streamId,
byte[]  data 
)

Occurs when the local user receives a remote data stream.

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

Parameters
uidUser ID of the remote user sending the data stream.
streamIdStream ID.
dataData received by the local user.

◆ onStreamMessageError()

void io.agora.rtc.IRtcEngineEventHandler.onStreamMessageError ( int  uid,
int  streamId,
int  error,
int  missed,
int  cached 
)

Occurs when the local user fails to receive a remote data stream.

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.

Parameters
uidUser ID of the remote user sending the data stream.
streamIdStream ID.
errorError code.
missedThe number of lost messages.
cachedThe number of incoming cached messages when the data stream is interrupted.

◆ onMediaEngineLoadSuccess()

void io.agora.rtc.IRtcEngineEventHandler.onMediaEngineLoadSuccess ( )

Occurs when the media engine is loaded.

◆ onMediaEngineStartCallSuccess()

void io.agora.rtc.IRtcEngineEventHandler.onMediaEngineStartCallSuccess ( )

Occurs when the media engine starts.

◆ onNetworkTypeChanged()

void io.agora.rtc.IRtcEngineEventHandler.onNetworkTypeChanged ( int  type)

Occurs when the network type changes.

Since
v2.4.1.

The SDK returns the current network type in this callback. When the network connection is interrupted, this callback indicates whether the interruption is caused by a network type change or poor network conditions.

Parameters
typeThe network type:

◆ onClientRoleChangeFailed()

void io.agora.rtc.IRtcEngineEventHandler.onClientRoleChangeFailed ( int  reason,
int  currentRole 
)

Occurs when the user role switch fails in the interactive live streaming.

Since
v3.7.0

In the LIVE_BROADCASTING channel profile, when the local user calls setClientRole to switch their user role after joining the channel but the switch fails, the SDK triggers this callback to report the reason for the failure and the current user role.

Parameters
reasonThe reason for the user role switch failure:
currentRoleThe current user role: