Agora Java API Reference for Android

Agora provides ensured quality of experience (QoE) for worldwide Internet-based voice and video communications through a virtual global network optimized for real-time web and mobile-to-mobile applications.

• The RtcEngine class provides the main methods that can be invoked by your application.
• The IRtcEngineEventHandler class enables callbacks to your application.
• The RtcChannel class provides methods that enable real-time communications in a specified channel. By creating multiple RtcChannel instances, users can join multiple channels.
• The IRtcChannelEventHandler class provides callbacks that report events and statistics of a specified channel.
• The IAudioEffectManager class includes methods to manage the audio effect files.
• The AgoraMediaRecorder class provides methods and callbacks for recording the local audio and video.

During API calls, the SDK may returns error codes and warning codes. See Error Codes and Warning Codes.

‍As of v2.3.3, Agora Java API Reference for Android can be downloaded from Dash. See FAQ for details.

Core methods

Method	Description
create[1/2]	Creates an RtcEngine instance.
create[2/2]	Creates an RtcEngine instance and specifies the region for connection.
destroy	Destroys the RtcEngine instance.
setChannelProfile	Sets the channel profile of the Agora RtcEngine.
setClientRole[1/2]	Sets the role of the user (Interactive live streaming only).
setClientRole[2/2]	Sets the role and level of the user (Interactive live streaming only).
joinChannel[1/2]	Allows a user to join a channel.
joinChannel[2/2]	Joins a channel with the user ID, and configures whether to publish or automatically subscribe to the audio or video streams.
switchChannel[1/2]	Switches to a different channel (LIVE_BROADCASTING profile only).
switchChannel[2/2]	Switches to a different channel and sets the subscribing state.
leaveChannel	Allows a user to leave a channel.
renewToken	Renews the token.
getConnectionState	Gets the connection state of the app.

Core events

Event	Description
onConnectionStateChanged	Occurs when the network connection state changes.
onJoinChannelSuccess	Occurs when a user joins a channel.
onRejoinChannelSuccess	Occurs when a user rejoins a channel.
onLeaveChannel	Occurs when a user leaves a channel.
onClientRoleChanged	Occurs when the user role switches successfully in the interactive live streaming.
onClientRoleChangeFailed	Occurs when the user role switch fails in the interactive live streaming.
onUserJoined	Occurs when a remote user joins a channel.
onUserOffline	Occurs when a remote user leaves a channel or goes offline.
onNetworkTypeChanged	Occurs when the network type changes.
onConnectionLost	Occurs when the SDK loses connection to the server.
onTokenPrivilegeWillExpire	Occurs when the token expires in 30 seconds.
onRequestToken	Occurs when the token expires.

Audio management

Method	Description
enableAudio	Enables the audio module.
disableAudio	Disables the audio module.
setAudioProfile	Sets the audio parameters and application scenarios.
adjustRecordingSignalVolume	Adjusts the sampling signal volume.
adjustUserPlaybackSignalVolume	Adjusts the playback signal volume of a specified remote user.
adjustPlaybackSignalVolume	Adjusts the playback signal volume of all remote users.
enableLocalAudio	Enables/disables the local audio capture.
muteLocalAudioStream	Stops/Resumes sending the local audio stream.
muteRemoteAudioStream	Stops/Resumes receiving a specified remote audio stream.
muteAllRemoteAudioStreams	Stops/Resumes receiving all remote audio streams.
setDefaultMuteAllRemoteAudioStreams	Sets whether to receive all remote audio streams by default.

Video management

Method	Description
enableVideo	Enables the video module.
disableVideo	Disables the video module.
setVideoEncoderConfiguration	Sets the video encoder configuration.
setupLocalVideo	Initializes the local video view.
setupRemoteVideo	Initializes the video view of a remote user.
setLocalRenderMode	Updates the display mode of the local video view.
setRemoteRenderMode	Updates the display mode of the remote video view.
CreateRendererView	Creates the video renderer view.
CreateTextureView	Creates the video texture view.
startPreview	Starts the local video preview.
stopPreview	Stops the local video preview.
enableLocalVideo	Enables/Disables the local video capture.
muteLocalVideoStream	Stops/Resumes sending the local video stream.
muteRemoteVideoStream	Stops/Resumes receiving a specified remote video stream.
muteAllRemoteVideoStreams	Stops/Resumes receiving all remote video streams.
setDefaultMuteAllRemoteVideoStreams	Sets whether to receive all remote video streams by default.

Local media events

Event	Description
onLocalAudioStateChanged	Occurs when the local audio state changes.
onLocalVideoStateChanged	Occurs when the local video state changes.
onFirstLocalAudioFramePublished	Occurs when the first audio frame is published.
onFirstLocalVideoFramePublished	Occurs when the first video frame is published.
onFirstLocalVideoFrame	Occurs when the first local video frame is rendered.
onAudioPublishStateChanged	Occurs when the audio publishing state changes.
onVideoPublishStateChanged	Occurs when the video publishing state changes.

Remote media events

Event	Description
onRemoteAudioStateChanged	Occurs when the remote audio state changes.
onRemoteVideoStateChanged	Occurs when the remote video state changes.
onFirstRemoteVideoFrame	Occurs when the first remote video frame is rendered.
onFirstRemoteVideoDecoded	Occurs when the first remote video frame is received and decoded.
onAudioSubscribeStateChanged	Occurs when the audio subscribing state changes.
onVideoSubscribeStateChanged	Occurs when the audio subscribing state changes.
onUserMuteAudio	Occurs when a remote user stops/resumes sending the audio stream.
onUserMuteVideo	Occurs when a remote user stops/resumes sending the video stream
onUserEnableLocalVideo	Occurs when a remote user enables/disables the local video capture function.
onUserEnableVideo	Occurs when a remote user enables/disables the video module.

Statistics events

‍- After joining a channel, SDK triggers this group of callbacks once every two seconds.

• We provide an advanced guide for these callbacks. For details, see Report In-call Statistics.

Event	Description
onRtcStats	Reports the statistics of RtcEngine.
onNetworkQuality	Reports the network quality of each user.
onLocalAudioStats	Reports the statistics of the local audio stream.
onLocalVideoStats	Reports the statistics of the uploading local video stream.
onRemoteAudioStats	Reports the statistics of the audio stream from each remote user/host.
onRemoteVideoStats	Reports the statistics of the video stream from each remote user/host.

Video pre-process and post-process

Method	Description
setBeautyEffectOptions	Sets the image enhancement options.
enableVirtualBackground	Enables/Disables the virtual background.
enableRemoteSuperResolution	Enables/Disables the super resolution feature for a remote user's video. (beta feature)
setVideoDenoiserOptions	Sets video noise reduction.
setLowlightEnhanceOptions	Sets low-light enhancement.
setColorEnhanceOptions	Sets color enhancement.

Event	Description
onVirtualBackgroundSourceEnabled	Reports whether the virtual background is successfully enabled.
onUserSuperResolutionEnabled	Reports whether the super resolution feature is successfully enabled. (beta feature)

Multi-channel management

‍We provide an advanced guide on the applicable scenarios, implementation and considerations for this group of methods. For details, see Join multiple channels.

Method	Description
createRtcChannel	Initializes and gets an RtcChannel instance. To join multiple channels, create multiple RtcChannel objects.
RtcChannel	Provides methods that enable real-time communications in a specified channel.
IRtcChannelEventHandler	Provides callbacks that report events and statistics in a specified channel.

Screen capture

‍We provide an advanced guide on the applicable scenarios, implementation and considerations for this group of methods. For details, see Share the Screen.

Method	Description
startScreenCapture	Starts screen sharing.
stopScreenCapture	Stops screen sharing.
updateScreenCaptureParameters	Updates the screen sharing configuration.

Music file playback and mixing

Method	Description
startAudioMixing	Starts playing and mixing the music file.
stopAudioMixing	Stops playing or mixing the music file.
pauseAudioMixing	Pauses playing and mixing the music file.
resumeAudioMixing	Resumes playing and mixing the music file.
adjustAudioMixingVolume	Adjusts the volume of audio mixing.
adjustAudioMixingPlayoutVolume	Adjusts the volume of audio mixing for local playback.
adjustAudioMixingPublishVolume	Adjusts the volume of audio mixing for remote playback.
setAudioMixingPitch	Sets the pitch of the local music file.
getAudioMixingPlayoutVolume	Gets the volume of audio mixing for local playback.
getAudioMixingPublishVolume	Gets the volume of audio mixing for remote playback.
getAudioMixingCurrentPosition	Gets the playback position (ms) of the music file.
setAudioMixingPosition	Sets the playback starting position (ms) of the music file.
getAudioTrackCount	Gets the number of audio tracks of the current music file.
selectAudioTrack	Specifies the playback track of the current music file.
setAudioMixingPlaybackSpeed	Sets the playback speed of the current music file.
setAudioMixingDualMonoMode	Sets the channel mode of the current music file.

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

Audio effect playback

Method	Description
getAudioEffectManager	Gets the IAudioEffectManager class to manage the audio effect files.
getEffectsVolume	Gets the volume of the audio effects.
setEffectsVolume	Sets the volume of the audio effects.
setVolumeOfEffect	Sets the volume of a specified audio effect.
playEffect	Plays a specified audio effect.
stopEffect	Stops playing a specified audio effect.
stopAllEffects	Stops playing all audio effects.
preloadEffect	Preloads a specified audio effect file into the memory.
unloadEffect	Releases a specified preloaded audio effect from the memory.
pauseEffect	Pauses a specified audio effect.
pauseAllEffects	Pauses all audio effects.
resumeEffect	Resumes playing a specified audio effect.
resumeAllEffects	Resumes playing all audio effects.
getEffectCurrentPosition	Gets the playback position of the audio effect file.
setEffectPosition	Sets the playback position of an audio effect file.

Event	Description
onAudioEffectFinished	Occurs when the audio effect file playback finishes.

Audio file information

Method	Description
getAudioFileInfo	Gets the information of a specified audio file.
getEffectDuration	Gets the information of a specified audio file.

Event	Description
onRequestAudioFileInfo	Reports the information of an audio file.

Virtual metronome

Method	Description
startRhythmPlayer	Enables the virtual metronome.
configRhythmPlayer	Configures the virtual metronome.
stopRhythmPlayer	Disables the virtual metronome.

Voice effect

Method	Description
setAudioEffectPreset	Sets an SDK preset audio effect
setVoiceBeautifierPreset	Sets an SDK preset voice beautifier effect
setVoiceBeautifierParameters	Sets parameters for SDK preset voice beautifier effects.
setAudioEffectParameters	Sets parameters for SDK preset audio effects
setLocalVoicePitch	Sets the voice pitch of the local speaker.
enableLocalVoicePitchCallback	Enables reporting the voice pitch of the local user.
setLocalVoiceEqualization	Sets the local voice equalization effect.
setLocalVoiceReverb	Sets the local voice reverberation.
setVoiceConversionPreset	Sets an SDK preset voice conversion effect.

Event	Description
onLocalVoicePitchInHz	Reports the voice pitch of the local user.

Sound localization

Method	Description
enableSoundPositionIndication	Enables/Disables stereo panning for remote users.
setRemoteVoicePosition	Sets the sound position and gain of a remote user.

Media push

‍This group of methods apply to LIVE_BROADCASTING profile only.

Method	Description
startRtmpStreamWithoutTranscoding	Starts pushing media streams to a CDN without transcoding.
startRtmpStreamWithTranscoding	Starts pushing media streams to a CDN and sets the transcoding configuration.
updateRtmpTranscoding	Updates the transcoding configuration.
stopRtmpStream	Stops pushing media streams to a CDN.

Event	Description
onRtmpStreamingStateChanged	Occurs when the state of the RTMP or RTMPS streaming changes.
onRtmpStreamingEvent	Reports events during the RTMP or RTMPS streaming.
onTranscodingUpdated	Occurs when the publisher's transcoding settings are updated.

Channel Media Relay

Method	Description
startChannelMediaRelay	Starts to relay media streams across channels.
updateChannelMediaRelay	Updates the channels for media stream relay.
pauseAllChannelMediaRelay	Pauses the media stream relay to all destination channels.
resumeAllChannelMediaRelay	Resumes the media stream relay to all destination channels.
stopChannelMediaRelay	Stops the media stream relay.

Event	Description
onChannelMediaRelayStateChanged	Occurs when the state of the media stream relay changes.
onChannelMediaRelayEvent	Reports events during the media stream relay.

Audio volume indication

Method	Description
enableAudioVolumeIndication	Enables the onAudioVolumeIndication callback at a set time interval to report on which users are speaking and the speakers' volume.

Event	Description
onAudioVolumeIndication	Reports which users are speaking and the speakers' volume, and whether the local user is speaking.
onActiveSpeaker	Occurs when the most active remote speaker is detected.

Face detection

Method	Description
enableFaceDetection	Enables/Disables face detection for the local user.

Event	Description
onFacePositionChanged	Reports the face detection result of the local user.

Audio routing control

Method	Description
setDefaultAudioRoutetoSpeakerphone	Sets the default audio route.
setEnableSpeakerphone	Enables/Disables the audio route to the speakerphone.
isSpeakerphoneEnabled	Checks whether the speakerphone is enabled.

Event	Description
onAudioRouteChanged	Occurs when the local audio playback route changes.

In-ear monitoring

Method	Description
enableInEarMonitoring	Enables in-ear monitoring.
setInEarMonitoringVolume	Sets the volume of the in-ear monitor.

Dual video stream mode

Method	Description
enableDualStreamMode	Enables/disables dual video stream mode.
setRemoteVideoStreamType	Sets the video stream type of the remotely subscribed video stream.
setRemoteDefaultVideoStreamType	Sets the default video stream type of the remotely subscribed video stream.

Stream fallback

‍We provide an advanced guide on the applicable scenarios, implementation and considerations for this group of methods. For details, see Improve Experience Under Poor Network conditions.

Method	Description
setLocalPublishFallbackOption	Sets the fallback option for the locally published video stream under unreliable network conditions.
setRemoteSubscribeFallbackOption	Sets the fallback option for the remotely subscribed video stream under unreliable network conditions.
setRemoteUserPriority	Sets the priority of a remote user's stream.

Event	Description
onLocalPublishFallbackToAudioOnly	Occurs when the locally published video stream falls back to audio only due to poor network conditions or switches back to the video stream after the network conditions improve.
onRemoteSubscribeFallbackToAudioOnly	Occurs when the remotely subscribed video stream falls back to audio only due to poor network conditions or switches back to the video stream after the network conditions improve.

Pre-call network test

‍We provide an advanced guide on the applicable scenarios, implementation and considerations for this group of methods. For details, see Pre-call Tests.

Method	Description
startEchoTest[2/3]	Starts an audio call loop test.
startEchoTest[3/3]	Starts an audio and video call loop test.
stopEchoTest	Stops call loop test.
enableLastmileTest	Enables the network connection quality test.
disableLastmileTest	Disables the network connection quality test.
startLastmileProbeTest	Starts the last-mile probe test.
stopLastmileProbeTest	Stops the last-mile probe test.

Event	Description
onLastmileQuality	Reports the last-mile network quality of the local user before the user joins a channel.
onLastmileProbeResult	Reports the last-mile network probe result.

Custom video module

Method	Description
setVideoSource	Customizes the video source.
setLocalVideoRenderer	Customizes the local video renderer.
setRemoteVideoRenderer	Customizes the remote video renderer.

External video data (push-mode only)

Method	Description
setExternalVideoSource	Configures the external video source.
pushExternalVideoFrame	Pushes the external video frame.
isTextureEncodeSupported	Checks if textured video frame is supported.

External audio data (push-mode only)

Method	Description
setExternalAudioSource	Configures the external audio source.
pushExternalAudioFrame	Pushes the external audio frame to a specified position.
setExternalAudioSourceVolume	Sets the volume of the external audio frame in the specified position.

External audio sink

Method	Description
setExternalAudioSink	Sets the external audio sink.
pullPlaybackAudioFrame	Pulls the remote audio frame.

Raw audio data

Method	Description
registerAudioFrameObserver	Registers an audio frame observer object.
setRecordingAudioFrameParameters	Sets the audio recording format for the onRecordFrame callback.
setPlaybackAudioFrameParameters	Sets the audio playback format for the onPlaybackFrame callback.
setMixedAudioFrameParameters	Sets the mixed audio format.

Event	Description
onRecordFrame	Occurs when the recorded audio frame is received.
onPlaybackFrame	Occurs when the playback audio frame is received.
onPlaybackFrameBeforeMixing	Gets the audio data of a remote user before mixing.
onMixedFrame	Receives the mixed raw audio data of the local user and all remote users.
isMultipleChannelFrameWanted	Determines whether to receive raw audio data from multiple channels.
onPlaybackFrameBeforeMixingEx	Gets the audio frame of a remote user before mixing.
getObservedAudioFramePosition	Sets the audio observation positions.
getRecordAudioParams	Sets the audio recording format for the onRecordFrame callback.
getPlaybackAudioParams	Sets the audio playback format for the onPlaybackFrame callback.
getMixedAudioParams	Sets the audio mixing format for the onMixedFrame callback.

Raw video data

Method	Description
registerVideoFrameObserver	Registers a raw video frame observer.

Event	Description
getObservedFramePosition	Sets the video observation positions.
onCaptureVideoFrame	Gets the video data captured by the local camera.
onPreEncodeVideoFrame	Gets the local pre-encoded video data.
onRenderVideoFrame	Gets the incoming remote video data.
getVideoFormatPreference	Sets the format of the raw video data output by the SDK.
getRotationApplied	Sets whether to rotate the raw video data output by the SDK.
getMirrorApplied	Sets whether to mirror the raw video data output by the SDK.
isMultipleChannelFrameWanted	Sets whether the SDK outputs remote video data received in multiple channels.
onRenderVideoFrameEx	Gets the remote video data received in multiple channels.

Encoded video frame

‍You can also use the C++ methods for encoded video frame.

Method	Description
registerVideoEncodedFrameObserver	Registers a local encoded video frame observer.

Event	Description
onVideoEncodedFrame	Gets the local encoded video frame.

Media metadata

‍Do not implement getMaxMetadataSize, onReadyToSendMetadata, and onMetadataReceived in the IRtcEngineEventHandler class.

Method	Description
registerMediaMetadataObserver	Registers a media metadata observer object.

Event	Description
getMaxMetadataSize	Occurs when the SDK requests the maximum size of the metadata.
onReadyToSendMetadata	Occurs when the SDK is ready to receive and send metadata.
onMetadataReceived	Occurs when the local user receives the metadata.

Watermark

‍This group of methods apply to LIVE_BROADCASTING profile only.

Method	Description
addVideoWatermark	Adds a watermark image to the local video.
clearVideoWatermarks	Removes the added watermark image from the video stream.

Video snapshot

Method	Description
takeSnapshot	Takes a snapshot of a video stream.

Event	Description
onSnapshotTaken	Reports the result of taking a video snapshot.

Encryption

Method	Description
enableEncryption	Enables/Disables the built-in encryption.

Audio recorder

Method	Description
startAudioRecording	Starts an audio recording on the client.
stopAudioRecording	Stops the audio recording on the client.

Media recorder

Method	Description
getMediaRecorder	Gets the AgoraMediaRecorder object.
startRecording	Starts recording the local audio and video.
stopRecording	Stops recording the local audio and video.
release	Releases the AgoraMediaRecorder object.

Event	Description
onRecorderStateChanged	Occurs when the recording state changes.
onRecorderInfoUpdated	Occurs when the recording information is updated.

Camera control

Method	Description
switchCamera	Switches between front and rear cameras.
isCameraZoomSupported	Checks whether the camera zoom function is supported.
isCameraTorchSupported	Checks whether the device supports enabling the flash.
isCameraFocusSupported	Checks whether the camera manual focus function is supported.
isCameraExposurePositionSupported	Checks whether the camera exposure function is supported.
isCameraAutoFocusFaceModeSupported	Checks whether the camera face auto-focus function is supported.
setCameraZoomFactor	Sets the camera zoom ratio.
getCameraMaxZoomFactor	Gets the maximum zoom ratio of the camera.
setCameraFocusPositionInPreview	Sets the camera manual focus position.
setCameraExposurePosition	Sets the camera exposure position.
setCameraTorchOn	Sets whether to enable the flash.
setCameraAutoFocusFaceModeEnabled	Enables the camera auto-face focus function.

Event	Description
onCameraFocusAreaChanged	Occurs when the camera focus area changes.
onCameraExposureAreaChanged	Occurs when the camera exposure area changes.

Device management

• N/A

Stream message

Method	Description
createDataStream	Creates a data stream.
sendStreamMessage	Sends data stream messages.

Event	Description
onStreamMessage	Occurs when the local user receives a remote data stream within five seconds.
onStreamMessageError	Occurs when the local user fails to receive the remote data stream.

Miscellaneous video control

Method	Description
setCameraCapturerConfiguration	Sets the camera capturer configuration.

Miscellaneous audio control

• N/A

Miscellaneous methods

Method	Description
setCloudProxy	Sets the Agora cloud proxy service.
enableDeepLearningDenoise	Enables or disables deep-learning noise reduction.
sendCustomReportMessage	Reports customized messages.
getCallId	Gets the current call ID.
rate	Allows a user to rate a call after the call ends.
complain	Allows a user to complain about the call quality after a call ends.
getSdkVersion	Gets the SDK version number.
getErrorDescription	Gets the warning or error description.
getNativeHandle	Gets the native handle of the SDK engine.
addHandler	Adds the IRtcEngineEventHandler class.
removeHandler	Removes the specified IRtcEngineEventHandler object.
setAgoraLibPath	Sets the storage directory of .so files.

Miscellaneous events

Event	Description
onWarning	Occurs when a warning occurs.
onError	Occurs when an error occurs.
onApiCallExecuted	Occurs when an API method is executed.
onProxyConnected	Reports the proxy connection state.