Agora Java API Reference for Android
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.

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.

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 Video Stream Fallback.

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 noise suppression.
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.