Agora Java API Reference for Android

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

warn	Warning code

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

err	Error code

Occurs when a 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

channel	Channel name.
uid	User ID.
elapsed	Time elapsed (ms) from the user calling joinChannel until this callback is triggered.

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

channel	Channel name.
uid	User ID.
elapsed	Time elapsed (ms) from starting to reconnect until this callback is triggered.

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 retrieves the channel information, such as the call duration and statistics.

Parameters

stats

Statistics of the call: RtcStats

Occurs when the user role switches in a live broadcast. For example, from a host to an audience or vice versa.

Parameters

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

Occurs when a remote user (Communication)/host (Live Broadcast) 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-broadcast 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. Agora recommends having at most 17 hosts in a channel

Parameters

uid	ID of the user or host who joins the channel.
elapsed	Time delay (ms) from the user calling joinChannel/setClientRole until this callback is triggered.

Note

In the live-broadcast 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.

Occurs when a remote user (Communication)/host (Live Broadcast) 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 Agora recommends using the signaling system for reliable offline detection.

Parameters

uid

ID of the user or host who leaves the channel or goes offline.

reason

Reason 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. 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. USER_OFFLINE_BECOME_AUDIENCE(2): (Live broadcast only.) The client role switched from the host to the audience.

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

This callback is triggered when the SDK loses connection with the server for more than four seconds after the connection is established. After triggering this callback, the SDK tries to reconnect with the server. Developers can use this callback as a UI reminder. This callback is different from onConnectionLost:

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

For both callbacks, the SDK tries to reconnect with the server until the app calls leaveChannel.

Occurs when the connection between the SDK and the server is interrupted and the SDK cannot reconnect to the server in 10 seconds.

This callback is triggered when the SDK cannot connect with the server for 10 seconds after calling joinChannel(), regardless of whether the SDK is in the channel or not.

This callback is different from onConnectionInterrupted:

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

For both callbacks, the SDK tries to reconnect with the server until the application calls leaveChannel.

Occurs when your connection is banned by the Agora Server.

Occurs when an API method is executed.

Parameters

error	Error Code that the SDK returns when the method call fails. If the SDK returns 0, then the method call was successful.
api	The method executed by the SDK.
result	The result of the method call.

Occurs when the token expires in 30 seconds.

The user becomes offline if the token used in joinChannel 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

token

The token that expires in 30 seconds.

Occurs when the token expires.

After a token is specified by calling joinChannel, if the SDK losses connection with the Agora server due to network issues, the token may expire after a certain period of time and a new token may be required to reconnect to the server. This callback notifies the app to generate a new token. Call renewToken to renew the token. In previous SDKs, this notification was provided in the onError callback as the ERR_TOKEN_EXPIRED(109) and ERR_INVALID_TOKEN(110) errors. Starting from v1.7.3 of the SDK, the old method is still valid, but it is recommended to use the onRequestToken() callback.

Occurs when the microphone is enabled/disabled.

Parameters

enabled

Whether the microphone is enabled/disabled: true: Enabled. false: Disabled.

Reports which users are speaking and the speakers' volume.

This callback reports the ID and volume of the loudest speakers at the moment in the channel. This callback is disabled by default and can be enabled by the enableAudioVolumeIndication method.

The local user has a dedicated onAudioVolumeIndication callback; all remote speakers share a separate onAudioVolumeIndication callback.

• For the local user's callback, the speakers array has uid = 0 and volume = totalVolume, and speakerNumber = 1 regardless of whether the local user speaks or not.
• For the remote speakers' callback, the speakers array includes the user ID and volume of the loudest speakers in the channel.

Parameters

speakers	An array containing the user ID and volume information for each speaker: AudioVolumeInfo
totalVolume	Total volume after audio mixing. The value ranges between 0 (lowest volume) and 255 (highest volume).

Note

• Calling the muteLocalAudioStream method affects the SDK's behavior.
  • If the local user calls the muteLocalAudioStream method, the SDK stops triggering the local user's callback.
  • 15 seconds after a remote speaker calls the muteLocalAudioStream method, the remote speakers' callback does not include information of this remote user; 15 seconds after all remote users call the the muteLocalAudioStream method, the SDK stops triggering the remote speakers' callback.
• An empty speakers array in the onAudioVolumeIndication callback suggests that no remote user is speaking at the moment.

Reports which user is the loudest speaker.

If the user enables the audio volume indication by calling enableAudioVolumeIndication, this callback returns the uid of the active speaker whose voice is detected by the audio volume detection module of the SDK.

Parameters

uid	User ID of the active speaker. A uid of 0 represents the local user.

Note

• To receive this callback, you need to call enableAudioVolumeIndication.
• This callback returns the user ID of the user with the highest voice volume during a period of time, instead of at the moment.

Occurs when the first local audio frame is sent.

Parameters

elapsed

Time elapsed (ms) from the local user calling joinChannel until this callback is triggered.

Occurs when the first remote audio frame is received.

Parameters

uid	User ID of the remote user.
elapsed	Time elapsed (ms) from the remote user calling joinChannel until this callback is triggered.

Occurs when the video stops playing.

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.

Occurs when the first local video frame is sent.

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

Parameters

width	Width (pixels) of the first local video frame.
height	Height (pixels) of the first local video frame.
elapsed	Time 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.

Occurs when the first remote video frame is decoded.

This callback is triggered after the first frame of the remote video is received and decoded. The app can configure the user view settings with this callback.

Parameters

uid	User ID of the remote user sending the video streams.
width	Width (pixels) of the video stream.
height	Height (pixels) of the video stream.
elapsed	Time elapsed (ms) from the remote user calling joinChannel until this callback is triggered.

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

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

Parameters

uid	User ID of the remote user sending the video streams.
width	Width (pixels) of the video stream.
height	Height (pixels) of the video stream.
elapsed	Time elapsed (ms) from calling joinChannel until this callback is triggered.

Occurs when a remote user's audio stream is muted/unmuted.

Parameters

uid	ID of the remote user.
muted	Whether the remote user's audio stream is muted/unmuted: true: Muted. false: Unmuted.

Occurs when a remote user's video stream playback pauses/resumes.

Parameters

uid	ID of the remote user.
muted	Whether the remote user's video stream playback pauses/resumes: true: Pause. false: Resume.

Note

This callback returns invalid when the number of users in a channel exceeds 20.

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.

Parameters

uid	User ID of the remote user.
enabled	Whether 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.

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

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

uid	User ID of the remote user.
enabled	Whether 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.

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

Parameters

uid	User ID of the remote user or local user (0) whose video size or rotation changes.
width	New width (pixels) of the video.
height	New height (pixels) of the video.
rotation	New rotation of the video [0 to 360).

Occurs when the remote video stream state changes.

Parameters

uid	ID of the user whose remote video state changes.
state	State of the remote video: 1: The remote video is playing normally. 2: The remote video is frozen.

Note

This callback is triggered when the time interval between two video frames exceeds 600 ms (600 ms included).

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.

Parameters

isFallbackOrRecover

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

Occurs when the subscribed 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 uplink conditions, or when the remotely subscribed media stream switches back to the video after the uplink network condition improves.

Parameters

uid	ID of the remote user sending the stream.
isFallbackOrRecover	Whether the remotely subscribed media stream fell back to audio-only or switched back to the video: true: The remotely subscribed media stream fell back to audio-only due to poor network conditions. false: The remotely subscribed media stream switched back to the video stream after the network conditions improved.

Note

Once the remotely subscribed 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.

Occurs when the local audio pkayout route changes.

This callback returns that the audio route switched to an earpiece, speakerphone, headset, or Bluetooth device.

The definition of the routing is listed as follows:

• AUDIO_ROUTE_DEFAULT(-1): Default audio route.
• AUDIO_ROUTE_HEADSET(0): Headset.
• AUDIO_ROUTE_EARPIECE(1): Earpiece.
• AUDIO_ROUTE_HEADSETNOMIC(2): Headset with no microphone.
• AUDIO_ROUTE_SPEAKERPHONE(3): Speakerphone.
• AUDIO_ROUTE_LOUDSPEAKER(4): Loudspeaker.
• AUDIO_ROUTE_HEADSETBLUETOOTH(5): Bluetooth headset.

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

If the camera fails to turn on, fix the error reported in the onError callback.

Occurs when the camera focus area is changed.

Parameters

rect	Rectangular area in the camera zoom specifying the focus area.

Reports the audio quality of the current call once every two seconds.

This callback is enabled by default.

Parameters

uid	User ID of the speaker.
quality	Audio quality of the user: QUALITY_UNKNOWN(0): The quality is unknown. QUALITY_EXCELLENT(1): The quality is excellent. QUALITY_GOOD(2): The quality is quite good, but the bitrate may be slightly lower than excellent. QUALITY_POOR(3): Users can feel the communication slightly impaired. QUALITY_BAD(4): Users can communicate not very smoothly. QUALITY_VBAD(5): The quality is so bad that users can barely communicate. QUALITY_DOWN(6): Users cannot communicate at all.
delay	Time delay (ms).
lost	Audio packet loss rate (%).

Reports the statistics of the RtcEngine once every two seconds.

Parameters

stats

RTC engine statistics: RtcStats

Reports the last mile network quality of the local user after enableLastmileTest is called.

Parameters

quality

Network quality: QUALITY_UNKNOWN(0): The quality is unknown. QUALITY_EXCELLENT(1): The quality is excellent. QUALITY_GOOD(2): The quality is quite good, but the bitrate may be slightly lower than excellent. QUALITY_POOR(3): Users can feel the communication slightly impaired. QUALITY_BAD(4): Users can communicate not very smoothly. QUALITY_VBAD(5): The quality is so bad that users can barely communicate. QUALITY_DOWN(6): Users cannot communicate at all.

Reports the network quality of each user once every two seconds.

The Agora SDK returns this callback to report on the uplink and downlink network conditions of each user in the channel once every two seconds.

Parameters

uid	User ID. The network quality of the user with this uid is reported. If uid is 0, the local network quality is reported.
txQuality	Transmission quality of the user: QUALITY_UNKNOWN(0): The quality is unknown. QUALITY_EXCELLENT(1): The quality is excellent. QUALITY_GOOD(2): The quality is quite good, but the bitrate may be slightly lower than excellent. QUALITY_POOR(3): Users can feel the communication slightly impaired. QUALITY_BAD(4): Users can communicate not very smoothly. QUALITY_VBAD(5): The quality is so bad that users can barely communicate. QUALITY_DOWN(6): Users cannot communicate at all.
rxQuality	Receiving quality of the user: QUALITY_UNKNOWN(0): The quality is unknown. QUALITY_EXCELLENT(1): The quality is excellent. QUALITY_GOOD(2): The quality is quite good, but the bitrate may be slightly lower than excellent. QUALITY_POOR(3): Users can feel the communication slightly impaired. QUALITY_BAD(4): Users can communicate not very smoothly. QUALITY_VBAD(5): The quality is so bad that users can barely communicate. QUALITY_DOWN(6): Users cannot communicate at all.

Reports the statistics of the uploading local video streams once every two seconds.

Parameters

stats

Statistics of the uploading local video streams: LocalVideoStats.

Reports the statistics of the receiving remote video streams once every two seconds.

If there are multiple remote users/hosts, this callback is triggered multiple times once every two seconds.

Parameters

stats

Statistics of the receiving remote video streams: RemoteVideoStats.

Reports the statistics of the uploading local video streams.

Deprecated:

This method is deprecated. Agora recommends using onLocalVideoStats to get the local video statistics.

Parameters

sentBitrate	Data transmission bitrate (Kbps) since last count.
sentFrameRate	Data transmission frame rate (fps) since last count.

Reports the statistics of the receiving remote video streams.

Deprecated:

This method is deprecated. Agora recommends using onRemoteVideoStats to get the remote video statistics.

Parameters

uid	User ID of the remote user sending the video streams.
delay	Time delay (ms).
receivedBitrate	Data receiving bitrate (Kbps).
receivedFrameRate	Data receiving frame rate (fps).

Reports the statistics of the remote audio transmission once every two seconds after the user receives the audio data packet from a remote user.

Parameters

uid	User ID of the remote user sending the audio data packet.
delay	Time delay (ms) from the remote user to the local client.
lost	Packet loss rate (%).
rxKBitRate	Received audio bitrate (Kbps) of the data packet from the remote user.

Reports the statistics of the remote video transmission once every two seconds after the user receives the video data packet from a remote user.

Parameters

uid	User ID of the remote user sending the video data packet.
delay	Time delay (ms) from the remote user to the local client.
lost	Packet loss rate (%).
rxKBitRate	Received video bitrate (Kbps) of the data packet from the remote user.

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.

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

soundId

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

Occurs when a CDN live stream is published.

Parameters

url

HTTP/HTTPS URL address, to which the publisher publishes the stream.

error

Error code ERR_OK(0): The publishing succeeded. ERR_FAILED(1): The publishing failed. ERR_INVALID_ARGUMENT(2): Invalid argument used. If, for example, you have not called setLiveTranscoding to configure LiveTranscoding before calling addPublishStreamUrl, the SDK will report this error. ERR_TIMEOUT(10): The publishing timed out. ERR_ALREADY_IN_USE(19): The chosen HTTP/HTTPS URL address is already in use for CDN live streaming. ERR_ENCRYPTED_STREAM_NOT_ALLOWED_PUBLISHED(130): You cannot publish an encrypted stream.

Occurs when a CDN live stream stops.

This callback notifies the host that the CDN live stream is unpublished.

Parameters

url	HTTP/HTTPS URL address, from which the publisher unpublished the stream.

Occurs when the publisher's transcoding settings are updated.

Reports the status of the injected online media stream.

Parameters

url	HTTP/HTTPS URL address of the externally injected stream.
uid	User ID.
status	State of the externally injected stream: INJECT_STREAM_STATUS_START_SUCCESS(0): The external video stream imported successfully. INJECT_STREAM_STATUS_START_ALREADY_EXIST(1): The external video stream already exists. INJECT_STREAM_STATUS_START_UNAUTHORIZED(2): The external video stream import is unauthorized. INJECT_STREAM_STATUS_START_TIMEDOUT(3): Timeout when importing the external video stream. INJECT_STREAM_STATUS_START_FAILED(4): The external video stream failed to import. INJECT_STREAM_STATUS_STOP_SUCCESS(5): The external video stream stopped importing successfully. INJECT_STREAM_STATUS_STOP_NOT_FOUND(6): No external video stream is found. INJECT_STREAM_STATUS_STOP_UNAUTHORIZED(7): The external video stream is stopped from being unauthorized. INJECT_STREAM_STATUS_STOP_TIMEDOUT(8): Timeout when stopping the import of the external video stream. INJECT_STREAM_STATUS_STOP_FAILED(9): Failed to stop importing the external video stream. INJECT_STREAM_STATUS_BROKEN(10): The external video stream import is interrupted.

Occurs when the local user receives a remote data stream within five seconds.

Parameters

uid	User ID of the remote user sending the message.
streamId	Stream ID.
data	Data received by the local user.

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

Parameters

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

Occurs when the media engine is loaded.

Occurs when the media engine starts.