Agora Java API Reference for Android

Creates an RtcEngine instance.

The Agora SDK only supports one RtcEngine instance at a time, therefore the app should create one RtcEngine object only. Unless otherwise specified:

• All called methods provided by the RtcEngine class are executed asynchronously. Agora recommends calling the interface methods in the same thread.
• The following rule applies to all APIs whose return values are integer types:
  • 0: The method call was successful.
  • < 0: The method call failed.

Parameters

context	The context of Android Activity.
appId	The App ID issued by Agora to the developers. Apply for a new App ID from Agora if it is missing from your kit.
handler	IRtcEngineEventHandler is an abstract class providing default implementations. The SDK uses this class to report to the app on the SDK runtime events.

Returns

RtcEngine object.

Exceptions

Exception

Descriptions of possible exceptions when calling this method.

Note

• Only users with the same App ID can join the same channel and call each other.
• An App ID can create only one Engine. For multiple App IDs in an App, you need to create multiple Engines. Call destroy first to destroy the current Engine before calling this method.

Destroys the RtcEngine instance and releases all resources used by the Agora SDK.

This method is useful for apps that occasionally make voice or video calls, to free up resources for other operations when not making calls.

Note

• Call this method in the subthread.
• Once the app calls destroy to destroy the created RtcEngine instance, no other methods in the SDK can be used and no callbacks can occur.

Sets the channel profile.

The Agora RtcEngine needs to know the application scenario to set the appropriate channel profile to apply different optimization methods.

Parameters

profile

Sets the channel profile: Communication(0): The Communication profile. Live Broadcast(1): The Live Broadcast profile. Gaming(2): Applicable to the Agora Gaming SDK only.

Returns

• 0: Success.
• < 0: Failure.

Note

• Users in the same channel must use the same channel profile.
• Before calling this method to set a new channel profile, destroy the current engine and create a new engine using create.
• Call this method before a user joins a channel you cannot configure the channel profile when the channel is in use.
• In the communication profile, the Agora SDK supports encoding only in raw data, not in texture.

Sets the role of the user (Live Broadcast only).

This method sets the role of the user, such as a host or an audience (default), before joining a channel.

This method can be used to switch the user role after the user joins a channel.

Parameters

role	Sets the role of the client. See ClientRole.

Returns

• 0: Success.
• < 0: Failure.

Allows a user to join a channel.

Users in the same channel can talk to each other, and multiple users in the same channel can start a group chat. Users with different App IDs cannot call each other.

You must call the leaveChannel method to exit the current call before entering another channel.

Parameters

token	A token generated by the server. In most circumstances, the static App ID suffices. For added security, use a token. If the user uses a static App ID, token is optional and can be set as null. If the user uses a token, Agora issues an additional App Certificate for developers to generate a token based on the algorithm and App Certificate for user authentication on the server.
channelName	Unique channel name for the AgoraRTC session in the string format. The string length must be less than 64 bytes. Supported character scopes are: The 26 lowercase English letters from a to z The 26 uppercase English letters from A to Z The 10 numbers from 0 to 9 The space "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
optionalInfo	Additional information about the channel. This parameter can be set to null or contain channel related information. Other users in the channel do not receive this message.
optionalUid	(Optional) User ID. A 32-bit unsigned integer with a value ranging from 1 to (2^32-1). The uid must be unique. If a uid is not assigned (or set to 0), the SDK assigns and returns a uid in the onJoinChannelSuccess callback. Your app must record and maintain the returned uid since the SDK does not do so.

The uid is represented as a 32-bit unsigned integer in the SDK. Since unsigned integers are not supported by Java, the uid is handled as a 32-bit signed integer and larger numbers are interpreted as negative numbers in Java. If necessary, the uid can be converted to a 64-bit integer through “uid&0xffffffffL”.

Note

A channel does not accept duplicate uids, such as two users with the same uid. If you set uid as 0, the system automatically assigns a uid.

Warning

Ensure that the App ID used for creating the token is the same App ID used in create for creating an RtcEngine object. Otherwise, the CDN live streaming may fail.

Returns

• 0: Success.
• < 0: Failure.
  • ERR_INVALID_ARGUMENT(-2)
  • ERR_NOT_READY(-3)
  • ERR_REFUSED(-5)

Allows a user to leave a channel.

After joining a channel, the user must call the leaveChannel method to end the call before joining another channel. This method returns 0 if the user leaves the channel and releases all resources related to the call. This method call is asynchronous, and the user has not exited the channel when the method call returns. Once the user leaves the channel, the SDK triggers the onLeaveChannel callback.

Note

• If you call destroy immediately after leaveChannel, the leaveChannel process interrupts, and the SDK does not trigger the onLeaveChannel callback.
• If you call leaveChannel during a CDN live streaming, the SDK triggers the removeInjectStreamUrl method.

Returns

• 0: Success.
• < 0: Failure.

Renews the token when the current token expires.

The token expires after a period of time once the token schema is enabled when:

• The onTokenPrivilegeWillExpire callback is triggered, or
• The onError callback reports the ERR_TOKEN_EXPIRED(-109) error, or
• The onRequestToken callback reports the ERR_TOKEN_EXPIRED(-109) error.

The app should retrieve a new token from the server and call this method to renew it. Failure to do so results in the SDK disconnecting from the server.

Parameters

token

The new token.

Returns

• 0: Success.
• < 0: Failure.

Enables interoperability with the Agora Web SDK (Live Broadcast only).

Use this method when the channel profile is live broadcast. The interoperability with Web SDK is enabled by default when the channel profile is communication.

Parameters

enabled

Sets whether to enable/disable interoperability with the Agora Web SDK: true: Enable. false: (Default) Disable.

Returns

• 0: Success.
• < 0: Failure.

Enables the audio module.

The audio module is enabled by default.

Note

• This method affects the internal engine and can be called after leaveChannel. You can call this method either before or after joining a channel.
• This method resets the internal engine and takes some time to take effect. Agora recommends using the following API methods to control the audio engine modules separately:
  • enableLocalAudio: Whether to enable the microphone to create the local audio stream.
  • muteLocalAudioStream: Whether to publish the local audio stream.
  • muteRemoteAudioStream: Whether to subscribe to and play the remote audio stream.
  • muteAllRemoteAudioStreams: Whether to subscribe to and play all remote audio streams.

Returns

• 0: Success.
• < 0: Failure.

Disables the audio module.

Note

• This method affects the internal engine and can be called after leaveChannel. You can call this method either before or after joining a channel.
• This method resets the engine and takes some time to take effect. Agora recommends using the following API methods to control the audio engine modules separately:
  • enableLocalAudio: Whether to enable the microphone to create the local audio stream.
  • muteLocalAudioStream: Whether to publish the local audio stream.
  • muteRemoteAudioStream: Whether to subscribe to and play the remote audio stream.
  • muteAllRemoteAudioStreams: Whether to subscribe to and play all remote audio streams.

Returns

• 0: Success.
• < 0: Failure.

Disables the audio function in the channel.

Deprecated:

This method is deprecated. Agora recommends using enableAudio instead.

Returns

• 0: Success.
• < 0: Failure.

Resumes the audio in the channel.

Deprecated:

This method is deprecated. Agora recommends using disableAudio instead.

Returns

• 0: Success.
• < 0: Failure.

Sets the audio parameters and application scenarios.

Parameters

profile	Sets the sampling rate, bitrate, encoding mode, and the number of channels. See Audio Profile.
scenario	Sets the audio application scenarios. See Audio Scenario.

Note

• You must call setAudioProfile before joinChannel.
• In the communication profile, you can set the profile but not the scenario.
• In the communication and live-broadcast profiles, the bitrate may be different from your settings due to network self-adaptation.
• In scenarios involving music education, Agora recommends setting profile as AUDIO_SCENARIO_SHOWROOM(4) and scenario as AUDIO_SCENARIO_GAME_STREAMING(3) in Audio Scenario.

Sets the high-quality audio preferences.

Deprecated:

This method is deprecated. Agora does not recommend using this method. If you want to set the audio profile, use setAudioProfile. Call this method and set all parameters before joining a channel. Do not call this method again after joining a channel.

Parameters

fullband	Sets whether to enable/disable full-band codec (48-kHz sampling rate), not compatible with versions before v1.7.4: true: Enable full-band codec. false: Disable full-band codec.
stereo	Sets whether to enable/disable stereo codec, not compatible with versions before v1.7.4: true: Enable stereo codec. false: Disable stereo codec.
fullBitrate	Sets whether to enable/disable high-bitrate mode. Recommended in voice-only mode: true: Enable high-bitrate mode. false: Disable high-bitrate mode.

Returns

• 0: Success.
• < 0: Failure.

Adjusts the recording volume.

Parameters

volume

Recording volume. The value ranges between 0 and 400: 0: Mute 100: Original volume 400: (Maximum) Four times the original volume with signal clipping protection

Returns

• 0: Success.
• < 0: Failure.

Adjusts the playback volume.

Parameters

volume

Playback volume. The value ranges between 0 and 400: 0: Mute 100: Original volume 400: (Maximum) Four times the original volume with signal clipping protection

Returns

• 0: Success.
• < 0: Failure.

Enables the onAudioVolumeIndication callback at a set time interval to report on which user is speaking and the speaker's volume.

Once this method is enabled, the SDK returns the volume indication in the onAudioVolumeIndication callback at the set time interval, regardless of whether any user is speaking in the channel.

Parameters

interval	Sets the time interval between two consecutive volume indications: ≤ 0: Disables the volume indication. > 0: Time interval (ms) between two consecutive volume indications. Agora recommends setting interval ≥ 200 ms.
smooth	The smoothing factor sets the sensitivity of the audio volume indicator. The value ranges between 0 and 10. The greater the value, the more sensitive the indicator. The recommended value is 3.

Returns

• 0: Success.
• < 0: Failure.

Enables the audio quality notification callbacks.

The onAudioQuality callback triggers periodically after this method is enabled.

Parameters

enabled

Sets whether to enable/disable the audio quality notification callbacks: true: Enable the audio quality notification callbacks. false: (Default) Disable the audio quality notification callbacks.

Returns

• 0: Success.
• < 0: Failure.

Enables/Disables the local audio capture.

The audio function is enabled by default. This method disables/re-enables the local audio function, that is, to stop or restart local audio capture and processing.

This method does not affect receiving or playing the remote audio streams, and is applicable to scenarios where the user wants to receive remote audio streams without sending any audio stream to other users in the channel.

The onMicrophoneEnabled callback is triggered once the local audio function is disabled or re-enabled.

Parameters

enabled

Sets whether to disable/re-enable the local audio function: true: (Default) Re-enable the local audio function, that is, to start local audio capture and processing. false: Disable the local audio function, that is, to stop local audio capture and processing.

Note

• Call this method after joinChannel.
• This method is different from muteLocalAudioStream:
  • enableLocalAudio: Disables/Re-enables the local audio capture and processing.
  • muteLocalAudioStream: Stops/Continues sending the local audio streams.

Returns

• 0: Success.
• < 0: Failure.

Sends/Stops sending the local audio stream.

Parameters

muted

Sets whether to send/stop sending the local audio stream: true: Stop sending the local audio stream. false: (Default) Send the local audio stream.

Note

When set to true, this method does not disable the microphone and thus does not affect any ongoing recording.

Returns

• 0: Success.
• < 0: Failure.

Receives/Stops receiving a specified audio stream.

Parameters

uid	ID of the specified remote user.
muted	Sets whether to receive/stop receiving the specified remote user's audio stream: true: Stop receiving the specified remote user’s audio stream. false: (Default) Receive the specified remote user’s audio stream.

Note

If you called muteAllRemoteAudioStreams and set to true to stop receiving all remote video streams, ensure that muteAllRemoteAudioStreams is called and set to false before calling this method. muteAllRemoteAudioStreams sets all remote audio streams, while muteRemoteAudioStream sets a specified remote user's audio stream.

Returns

• 0: Success.
• < 0: Failure.

Receives/Stops receiving all the audio streams.

Parameters

muted

Sets whether to receive/stop receiving all remote users' audio streams: true: Stop receiving all remote users’ audio streams. false: (Default) Receive all remote users’ audio streams.

Returns

• 0: Success.
• < 0: Failure.

Sets whether to receive the audio streams by default.

Call this method either before or after joining a channel. If you call this method after joining the channel, the audio streams of any subsequent user are not received.

Parameters

muted

Sets whether or not to receive/stop receiving all remote users' audio streams by default: true: Stop receiving all remote users' audio streams by default. false: (Default) Receive all remote users' audio streams by default.

Returns

• 0: Success.
• < 0: Failure.

Enables the video module.

The app can call this method either before entering a channel or during a call. If the method is called before entering a channel, the service starts in the video mode. If this method is called during an audio call, the audio mode switches to the video mode. To disable the video, call the disableVideo method.

Note

• This method affects the internal engine and can be called after leaveChannel. You can call this method either before or after joining a channel.
• This method resets the internal engine and takes some time to take effect. Agora recommends using the following API methods to control the video engine modules separately:
  • enableLocalVideo: Whether to enable the camera to create the local video stream.
  • muteLocalVideoStream: Whether to publish the local video stream.
  • muteRemoteVideoStream: Whether to subscribe to and play the remote video stream.
  • muteAllRemoteVideoStreams: Whether to subscribe to and play all remote video streams.

Returns

• 0: Success.
• < 0: Failure.

Disables the video module.

The app may call this method before entering a channel or during a call. If the method is called before entering a channel, the service starts in audio mode. If this method is called during a video call, the video mode switches to the audio mode. To enable the video mode, call the enableVideo method.

Note

• This method affects the internal engine and can be called after leaveChannel. You can call this method either before or after joining a channel.
• This method resets the internal engine and takes some time to take effect. Agora recommends using the following API methods to control the video engine modules separately:
  • enableLocalVideo: Whether to enable the camera to create the local video stream.
  • muteLocalVideoStream: Whether to publish the local video stream.
  • muteRemoteVideoStream: Whether to subscribe to and play the remote video stream.
  • muteAllRemoteVideoStreams: Whether to subscribe to and play all remote video streams.

Returns

• 0: Success.
• < 0: Failure.

Sets the video encoding profile.

Deprecated:

From v2.3. This method is deprecated. Agora recommends using setVideoEncoderConfiguration to set the video profile.

If you do not need to change the video encoding profile after joining the channel, call this method before enableVideo to reduce the render time of the first video frame.

Each video encoding profile includes a set of parameters, such as the resolution, frame rate, and bitrate. When the camera does not support the specified resolution, the SDK chooses a suitable camera resolution, while the encoder resolution is specified by setVideoProfile.

Parameters

profile	Sets the video encoding profile. See VideoProfile.
swapWidthAndHeight	The width and height of the output video is consistent with the set video profile. swapWidthAndHeight sets whether or not to swap the width and height of the stream: true: Swap the width and height. The video is in the portrait mode (width < height). false: (Default) Do not swap the width and height. The video is in the landscape mode (width > height).

Returns

• 0: Success.
• < 0: Failure.

Manually sets the video encoding profile.

Deprecated:

From v2.3. This method is deprecated. Agora recommends using setVideoEncoderConfiguration to set the video profile.

Each video encoding profile includes a set of parameters, such as the resolution, frame rate, and bitrate. If the camera device does not support the specified resolution, the SDK automatically chooses a suitable camera resolution, keeping the encoder resolution specified by setVideoProfile. If the user does not set the video encoding profile after joining the channel, Agora recommends calling this method before enableVideo to minimize the time delay in receiving the first video frame.

Parameters

width	Sets the width of the video. The maximum value of width &times height is 1280 &times 720.
height	Sets the height of the video. The maximum value of width &times height is 1280 &times 720.
frameRate	Sets the frame rate of the video. The highest value is 30. You can set frameRate as 5, 10, 15, 24, and 30.
bitrate	Sets the bitrate of the video. You need to manually work out the bitrate according to the width, height, and frame rate. For the correlation between the width, height, and frame rate. See the table in Bitrate.

With the same width and height, the bitrate varies with the frame rate:

• If the frame rate is 5 fps, divide the recommended bitrate by 2.
• If the frame rate is 15 fps, use the recommended bitrate.
• If the frame rate is 30 fps, multiply the recommended bitrate by 1.5.
• Calculate the bitrate according to the ratio if you choose other frame rates.

If the bitrate you set is beyond the proper range, the SDK automatically adjusts the bitrate to a value within the proper range.

Sets the video encoder configuration.

Each video encoder configuration corresponds to a set of video parameters, including the resolution, frame rate, bitrate, and video orientation. If you do not set the video encoder configuration after joining the channel, you can call this method before enableVideo to reduce the render time of the first video frame.

Parameters

config

Sets the video encoder configuration. See VideoEncoderConfiguration.

Note

The parameters specified in this method are the maximum values under ideal network conditions. If the video engine cannot render the video using the specified parameters due to poor network conditions, the parameters further down the list are considered until a successful configuration is found.

Returns

• 0: Success.
• < 0: Failure.

Sets the local video view and configures the video display settings on the local device.

The app calls this method to bind each video window (view) of the local video streams and configures the video display settings. Call this method after initialization to configure the local video display settings before entering a channel. The binding is still valid after the user leaves the channel, which means that the window still displays. To unbind the view, set the view in Video Canvas to null.

Parameters

local

Sets the local video view and settings. See Video Canvas.

Returns

• 0: Success.
• < 0: Failure.

Sets the remote user's video view.

This method binds the remote user to the video display window (sets the view for the remote user of the specified uid).

Typically, the app specifies the uid of the remote video in the method call before the user joins a channel. If the remote uid is unknown to the app, set the uid when the app receives the onUserJoined callback. If the Video Recording function is enabled, the Video Recording Service joins the channel as a dummy client, causing other clients to also receive the onUserJoined callback. Do not bind the dummy client to the app view because the dummy client does not send any video streams. If your app does not recognize the dummy client, bind the remote user to the view when the onFirstRemoteVideoDecoded callback is triggered.

To unbind the remote user from the view, set the view as null. Once the user leaves the channel, the SDK unbinds the remote user.

Parameters

remote

Sets the remote video view and settings. See Video Canvas.

Returns

• 0: Success.
• < 0: Failure.

Sets the local video display mode.

This method may be invoked multiple times during a call to change the display mode.

Parameters

mode

Sets the local video display mode: RENDER_MODE_HIDDEN(1): Uniformly scale the video until it fills the visible boundaries (cropped). One dimension of the video may have clipped contents. RENDER_MODE_FIT(2): Uniformly scale the video until one of its dimension fits the boundary (zoomed to fit). Areas that are not filled due to the disparity in the aspect ratio are filled with black. RENDER_MODE_ADAPTIVE(3): This mode is deprecated and Agora does not recommend using this mode.

Returns

• 0: Success.
• < 0: Failure.

Sets the remote video display mode.

This method can be invoked multiple times during a call to change the display mode.

Parameters

uid

User ID of the remote user.

mode

Sets the remote video display mode: RENDER_MODE_HIDDEN(1): Uniformly scale the video until it fills the visible boundaries (cropped). One dimension of the video may have clipped contents. RENDER_MODE_FIT(2): Uniformly scale the video until one of its dimension fits the boundary (zoomed to fit). Areas that are not filled due to the disparity in the aspect ratio are filled with black. RENDER_MODE_ADAPTIVE(3): This mode is deprecated and Agora does not recommend using this mode.

Returns

• 0: Success.
• < 0: Failure.

Creates the video renderer view.

CreateRendererView returns the SurfaceView type. The operation and layout of the view are managed by the app, and the Agora SDK renders the view provided by the app. The video display view must be created using this method instead of directly calling SurfaceView.

Returns

SurfaceView

Starts the local video preview before joining the channel.

Before calling this method, you must:

• Call setupLocalVideo to set the local preview window and configure the attributes.
• Call enableVideo to enable the video.

Note

Once startPreview is called to start the local video preview, if you leave the channel by calling leaveChannel, the local video preview remains until you call stopPreview to disable it.

Returns

• 0: Success.
• < 0: Failure.

Stops the local video preview and the video.

Returns

• 0: Success.
• < 0: Failure.

Disables/Re-enables the local video capture.

The local video is enabled by default. This method disables/re-enables the local video and is only applicable when the user wants to watch the remote video without sending any video stream to the other user. Call this method after enableVideo, otherwise this method may not work properly. After enableVideo is called, the local video enables by default. This method is used to disable/re-enable the local video while the remote video remains unaffected.

Parameters

enabled

Sets whether disable/re-enable the local video, including the capturer, renderer, and sender: true: (Default) Re-enable the local video. false: Disable the local video. Once the local video is disabled, the remote users can no longer receive the video stream of this user, while this user can still receive the video streams of other remote users. When set to false, this method does not require a local camera.

Note

This method affects the internal engine and can be called after leaveChannel.

Returns

• 0: Success.
• < 0: Failure.

Sends/Stops sending the local video stream.

Parameters

muted

Sets whether to send/stop sending the local video stream: true: Stop sending the local video stream. false: (Default) Send the local video stream.

Note

When set to true, this method does not disable the camera and thus does not affect the retrieval of the local video streams. This method responds faster compared to enableLocalVideo (false) which controls the sending of local video streams.

Returns

• 0: Success.
• < 0: Failure.

Receives/Stops receiving a specified remote video stream.

Parameters

uid	User ID of the specified remote user.
muted	Sets whether to receive/stop receiving a specified remote user's video stream: true: Stop receiving a specified remote user’s video stream. false: (Default) Receive a specified remote user’s video stream.

Note

If you called muteAllRemoteVideoStreams and set to true to stop receiving all remote video streams, ensure that muteAllRemoteVideoStreams is called and set to false before calling this method. muteAllRemoteVideoStreams sets all the remote streams, while muteRemoteVideoStream sets a specified stream.

Returns

• 0: Success.
• < 0: Failure.

Receives/Stops receiving all the video streams.

Parameters

muted

Sets whether to receive/stop receiving all remote users' video streams: true: Stop receiving all remote users' video streams. false: (Default) Receive all remote users' video streams.

Returns

• 0: Success.
• < 0: Failure.

Sets whether to receive the video streams by default.

Parameters

muted

Sets whether to receive/stop receiving all remote video streams by default: true: Stop receiving all remote video streams by default. false: (Default) Receive all remote video streams by default.

Returns

• 0: Success.
• < 0: Failure.

Sets the default audio playback route.

This method sets whether the received audio is routed to the earpiece or speakerphone by default before joining the channel. If the user does not call this method, the audio is routed to the earpiece by default. If you need to change the default audio route after joining the channel, call setEnableSpeakerphone.

The default settings for each mode:

• Voice: Earpiece
• Video: Speakerphone If the user in a communication channel calls disableVideo or if the user calls muteLocalVideoStream and muteAllRemoteVideoStreams, the default audio route switches back to the earpiece automatically.
• Live Broadcast: Speakerphone
• Gaming Voice: Speakerphone

Parameters

defaultToSpeaker

Sets the default audio route: true: Speakerphone false: (Default) Earpiece

Note

• This method only works in audio mode.
• Call this method before calling joinChannel.
• Regardless of whether the audio is routed to the speakerphone or earpiece by default, once a headset is plugged in or Bluetooth is connected, the default audio route changes. The default audio route switches to the earpiece once removing the headset or disconnecting Bluetooth.

Returns

• 0: Success.
• < 0: Failure.

Enables/Disables the audio playback routing to the speakerphone.

This method sets whether the audio is routed to the speakerphone or earpiece.

See the default audio route explanation in setDefaultAudioRouteToSpeakerphone and check whether it is necessary to call this method.

Parameters

enabled

Sets whether to route the audio to the speakerphone or earpiece: true: Route the audio to the speakerphone. false: Route the audio to the earpiece.

Note

• Ensure that you have successfully called the joinChannel method before calling this method.
• After calling this method, the SDK returns the onAudioRouteChanged callback to indicate the changes.
• This method does not take effect if a headset is used.

Returns

• 0: Success.
• < 0: Failure.

Checks whether the speakerphone is enabled.

Returns

• true: The speakerphone is enabled, and the audio plays from the speakerphone.
• false: The speakerphone is not enabled, and the audio plays from devices other than the speakerphone. For example, the headset or earpiece.

Enables in-ear monitoring.

Parameters

enabled

Sets whether to enable/disable the in-ear monitoring function: true: Enable. false: (Default) Disable.

Returns

• 0: Success.
• < 0: Failure.

Sets the volume of the in-ear monitor.

Parameters

volume

Sets the volume of the in-ear monitor. The value ranges between 0 and 100 (default).

Returns

• 0: Success.
• < 0: Failure.

Uses the external audio device.

Deprecated:

This method is deprecated.

Returns

• 0: Success.
• < 0: Failure.

Changes the voice pitch of the local speaker.

Parameters

pitch

Sets the voice pitch. The value ranges between 0.5 and 2.0. The lower the value, the lower the voice pitch. The default value is 1.0 (no change to the local voice pitch).

Returns

• 0: Success.
• -1: Failure.

Sets the local voice equalization effect.

Parameters

bandFrequency	Sets the band frequency. The value ranges between 0 and 9; representing the respective 10-band center frequencies of the voice effects, including 31, 62, 125, 500, 1k, 2k, 4k, 8k, and 16k Hz.
bandGain	Sets the gain of each band in dB. The value ranges between -15 and 15. The default value is 0.

Returns

• 0: Success.
• -1: Failure.

Sets the local voice reverberation.

Parameters

reverbKey

Sets the reverberation key. This method contains five reverberation keys. For details, see the description of each value.

value

Sets the local voice reverberation value: AUDIO_REVERB_DRY_LEVEL(0): Level of the dry signal (-20 to 10 dB). AUDIO_REVERB_WET_LEVEL(1): Level of the early reflection signal (wet signal) (-20 to 10 dB). AUDIO_REVERB_ROOM_SIZE(2): Room size of the reflection (0 to 100 dB). AUDIO_REVERB_WET_DELAY(3): Length of the initial delay of the wet signal (0 to 200 ms). AUDIO_REVERB_STRENGTH(4): Strength of the late reverberation (0 to 100).

Returns

• 0: Success.
• -1: Failure.

Starts playing and mixing the music file.

This method mixes the specified local or online audio file with the audio stream from the microphone, or replaces the microphone’s audio stream with the specified local or remote audio file. You can choose whether the other user can hear the local audio playback and specify the number of playback loops. When the audio mixing file playback finishes after calling this method, the onAudioMixingFinished callback is triggered.

Parameters

filePath	Specifies the absolute path of the local or online audio file to be mixed. Supported audio formats include mp3, mp4, m4a, aac, 3gp, mkv, wav, and flac. See Supported Media Formats for details. If the path begins with /assets/, the audio file is in the /assets/ directory. Otherwise, the audio file is in the absolute path.
loopback	Sets which user can hear the audio mixing: true: Only the local user can hear the audio mixing. false: Both users can hear the audio mixing.
replace	Sets the audio mixing content: true: Only publishes the specified audio file; the audio stream from the microphone is not published. false: The local audio file is mixed with the audio stream from the microphone.
cycle	Sets the number of playback loops: Positive integer: Number of playback loops -1: Infinite playback loops

Note

• To use this method, ensure that the Android device is v4.2+, and the API is v16+.
• Call this method when you are in the channel, otherwise it may cause issues.
• If you want to play an online music file, Agora recommends not using the redirected URL address. Some Android devices may fail to open a redirected URL address.
• If you call this method on an emulator, only the MP3 file format is supported.

Returns

• 0: Success.
• < 0: Failure.
  • WARN_AUDIO_MIXING_OPEN_ERROR (701): If the local audio file does not exist, or the online audio data packet is not received within five seconds after it is opened, the SDK assumes that the media file cannot be used and returns this warning.

Stops playing or mixing the music file.

Call this method when you are in a channel.

Returns

• 0: Success.
• < 0: Failure.

Pauses playing and mixing the music file.

Call this method when you are in a channel.

Returns

• 0: Success.
• < 0: Failure.

Resumes playing and mixing the music file.

Call this method when you are in a channel.

Returns

• 0: Success.
• < 0: Failure.

Adjusts the volume during audio mixing.

Call this method when you are in a channel.

Parameters

volume

Audio mixing volume. The value ranges between 0 and 100 (default).

Returns

• 0: Success.
• < 0: Failure.

Gets the duration (ms) of the music file.

Call this method when you are in a channel.

Returns

• Returns the audio mixing duration, if the method call is successful.

• < 0: Failure.

Gets the playback position (ms) of the music file.

Call this method when you are in a channel.

Returns

• Returns the current position of the audio mixing, if the method call is successful.

• < 0: Failure.

Sets the playback position (ms) of the music file to a different start position (the default plays from the beginning).

Parameters

pos	The starting playback position (ms) of the audio mixing file.

Returns

• 0: Success.
• < 0: Failure.

Retrieves the IAudioEffectManager object associated with the current RtcEngine.

Returns

IAudioEffectManager

Starts an audio recording on the client.

The SDK allows recording during a call. Supported formats:

• .wav: Large file size with high fidelity.
• .aac: Small file size with low fidelity.

Ensure that the directory to save the recording file exists and is writable. This method is usually called after the joinChannel method. The recording automatically stops when the leaveChannel method is called.

Parameters

filePath	Full file path of the recording file. The string of the file name is in UTF-8.
quality	Sets the audio recording quality: AUDIO_RECORDING_QUALITY_LOW(0): Low audio recording quality. AUDIO_RECORDING_QUALITY_MEDIUM(1): Medium audio recording quality. AUDIO_RECORDING_QUALITY_HIGH(2): High audio recording quality.

Returns

• 0: Success.
• < 0: Failure.

Stops the audio recording on the client.

Note

You can call this method before calling leaveChannel; else, the recording automatically stops when the leaveChannel method is called.

Returns

• 0: Success.
• < 0: Failure.

Starts an audio call test.

This method launches an audio call test to determine whether the audio devices (for example, headset and speaker) and the network connection are working properly.

To conduct the test:

• The user speaks, and the recording is played back within 10 seconds.
• If the user can hear the recording within 10 seconds, the audio devices and network connection are working properly.

Note

• After calling this method, call stopEchoTest to end the test. Otherwise, the app cannot run the next echo test, nor can it call the joinChannel method to start a new call.
• In the live broadcast profile, only the hosts can call this method. If the user switches from a communication to live broadcast channel, the user must call setClientRole to change the user role from the audience (default) to the host before calling this method.

Returns

• 0: Success.
• < 0: Failure.

Stops the audio call test.

Returns

• 0: Success.
• < 0: Failure.
  • ERR_REFUSED(-5). Failed to stop the echo test. The echo test may not be running.

Enables the network connection quality test.

This method tests the quality of the users network connections and is disabled by default.

Before users join a channel or before an audience switches to a host, call this method to check the uplink network quality. This method consumes additional network traffic, which may affect the communication quality. Call disableLastmileTest to disable the test immediately after receiving the onLastmileQuality callback, and before the user joins the channel or switches the user role.

Note

• Do not call any other methods before receiving the onLastmileQuality callback. Otherwise, the callback may be interrupted by other methods and may not execute.
• In the Live Broadcast profile, a host should not call this method.

Returns

• 0: Success.
• < 0: Failure.

Disables the network connection quality test.

Returns

• 0: Success.
• < 0: Failure.

Customizes the video source.

Call this method to add an external video source into the SDK.

Parameters

source

Sets the video source. See IVideoSource.

Customizes the local video renderer.

Call this method to add an external renderer into the SDK.

Parameters

render

Sets the local video renderer. See IVideoSink.

Customizes the remote video renderer.

Call this method to add an external renderer into the SDK.

Parameters

render

Sets the remote video renderer. See IVideoSink.

Sets the external audio source.

Parameters

enabled	Sets whether to enable/disable the external audio source: true: Enable the external audio source. false: (Default) Disable the external audio source.
sampleRate	Sets the sampling rate of the external audio source, which can set be as 8000, 16000, 32000, 44100, or 48000.
channels	Sets the number of external audio source channels (two channels maximum).

Returns

• 0: Success.
• < 0: Failure.

Pushes the external audio frame to the Agora SDK for encoding.

Parameters

data	External audio data to be pushed.
timestamp	Timestamp of the external audio frame to be synchronized with the external video source.

Returns

• 0: Success.
• < 0: Failure.

Configures the external video source.

Parameters

enable	Sets whether or not to use the external video source: true: Use the external video source. false: Do not use the external video source.
useTexture	Sets whether or not to use texture as an input: true: Use texture as an input. false: (Default) Do not use texture as an input.
pushMode	Sets whether or not the external video source needs to call PushExternalVideoFrame to send the video frame to the Agora SDK: true: Use the push mode. false: Use the pull mode (not supported).

Pushes the video frame using the AgoraVideoFrame class and passes the video frame to the Agora SDK.

Call setExternalVideoSource and set the pushMode parameter as true before calling this method. Otherwise, a failure returns after calling this method.

Parameters

frame

Video frame to be pushed. See AgoraVideoFrame.

Note

This method supports pushing textured video frames in the live-broadcast profile only, not in the communication profile.

Returns

• true: The frame is pushed successfully.
• false: Failed to push the frame.

Checks whether texture encoding is supported.

Returns

• true: Texture encoding is supported.
• false: Texture encoding is not supported.

Registers the audio observer object.

Parameters

observer

Audio observer object to be registered. See IAudioFrameObserver. Set the value to null to cancel registering, if necessary.

Returns

• 0: Success.
• < 0: Failure.

Sets the audio recording format for the onRecordFrame callback.

Parameters

sampleRate	Sets the sampling rate (samplesPerSec) returned in onRecordFrame, which can set be as 8000, 16000, 32000, 44100, or 48000.
channel	Sets the number of audio channels (channels) returned in onRecordFrame: 1: Mono 2: Stereo
mode	Sets the use mode of the onRecordFrame callback: RAW_AUDIO_FRAME_OP_MODE_READ_ONLY(0): Read-only mode: Users only read the AudioFrame data without modifying anything. For example, when users acquire the data with the Agora SDK then push the RTMP streams. RAW_AUDIO_FRAME_OP_MODE_WRITE_ONLY(1): Write-only mode: Users replace the AudioFrame data with their own data and pass the data to the SDK for encoding. For example, when users acquire the data. RAW_AUDIO_FRAME_OP_MODE_READ_WRITE(2): Read and write mode: Users read the data from AudioFrame, modify it, and then play it. For example, when users have their own sound-effect processing module and perform some voice pre-processing, such as a voice change.
samplesPerCall	Sets the sample points (samples) returned in onRecordFrame. samplesPerCall is usually set as 1024 for stream pushing. SamplesPerCall = (int)(SampleRate × sampleInterval), where sampleInterval ≥ 0.01 in seconds.

Returns

• 0: Success.
• < 0: Failure.

Sets the audio playback format for the onPlaybackFrame callback.

Parameters

sampleRate	Sets the sampling rate (samplesPerSec) returned in onPlaybackFrame, which can set be as 8000, 16000, 32000, 44100, or 48000.
channel	Sets the number of channels (channels) returned in onPlaybackFrame: 1: Mono 2: Stereo
mode	Sets the use mode of the onPlaybackFrame callback: RAW_AUDIO_FRAME_OP_MODE_READ_ONLY(0): Read-only mode: Users only read the AudioFrame data without modifying anything. For example, when users acquire the data with the Agora SDK then push the RTMP streams. RAW_AUDIO_FRAME_OP_MODE_WRITE_ONLY(1): Write-only mode: Users replace the AudioFrame data with their own data. For example, users can use this mode when they acquire data by themselves. RAW_AUDIO_FRAME_OP_MODE_READ_WRITE(2): Read and write mode: Users read the data from AudioFrame, modify it, and then play it. For example, users can use this mode when they have their own sound-effect processing module, and want to do some voice post-processing, such as a voice change.
samplesPerCall	Sets the sample points (samples) returned in onPlaybackFrame. samplesPerCall is usually set as 1024 for stream pushing. SamplesPerCall = (int)(SampleRate × sampleInterval), where sampleInterval ≥ 0.01 in seconds.

Returns

• 0: Success.
• < 0: Failure.

Sets the mixed audio format for the onMixedAudioFrame callback.

Parameters

sampleRate	Sets the sampling rate (samplesPerSec) returned in onMixedAudioFrame, which can set be as 8000, 16000, 32000, 44100, or 48000.
samplesPerCall	Sets the sample points (samples) returned in onMixedAudioFrame. samplesPerCall is usually set as 1024 for stream pushing. SamplesPerCall = (int)(SampleRate × sampleInterval), where sampleInterval ≥ 0.01 in seconds.

Returns

• 0: Success.
• < 0: Failure.

Adds a watermark image to the local video.

This method adds a PNG watermark image to the local video stream for the recording device, channel audience, and CDN live audience to see and capture. To add the PNG file to a CDN live publishing stream, see the setLiveTranscoding method.

Parameters

watermark

Watermark image to be added to the local video stream. See Agora Image.

Note

• The URL descriptions are different for the local video and CDN live streams:
  • In a local video stream, url in Agora Image refers to the absolute path of the added watermark image file in the local video stream.
  • In a CDN live stream, url in Agora Image refers to the HTTP/HTTPS URL address of the added watermark image in the CDN live broadcast.
• The source file of the watermark image must be in the PNG file format. If the width and height of the PNG file differ from your settings in this method, the PNG file is cropped to conform to your settings.
• The Agora SDK supports adding only one watermark image onto a local video or CDN live stream. The newly added watermark image replaces the previous one.
• If you set orientationMode as Adaptive in the setVideoEncoderConfiguration method, the watermark image rotates with the video frame around the upper left corner of the watermark image.

Returns

• 0: Success.
• < 0: Failure.

Removes the watermark image from the video stream added by addVideoWatermark.

Returns

• 0: Success.
• < 0: Failure.

Sets the fallback option for the published video stream based on the network conditions.

If option is set to STREAM_FALLBACK_OPTION_AUDIO_ONLY(2), the SDK will:

• Disable the upstream video but enable audio only when the network conditions deteriorate and cannot support both video and audio.
• Re-enable the video when the network conditions improve.

When the locally published stream falls back to audio-only or when the audio stream switches back to the video, the onLocalPublishFallbackToAudioOnly callback is triggered.

Parameters

option

Sets the fallback option for the locally published stream: STREAM_FALLBACK_OPTION_DISABLED(0): (Default) No fallback operation for the locally published stream when the uplink network condition is poor. The stream quality cannot be guaranteed. STREAM_FALLBACK_OPTION_AUDIO_ONLY(2): The locally published stream falls back to audio only when the uplink network condition is poor.

Note

Agora does not recommend using this method for CDN live streaming, because the remote CDN live user will have a noticeable lag when the locally publish stream falls back to audio-only.

Returns

• 0: Success.
• < 0: Failure.

Sets the fallback option for the remote stream based on the network conditions.

If option is set to STREAM_FALLBACK_OPTION_AUDIO_ONLY(2), the SDK automatically switches the video from a high-stream to a low-stream, or disable the video when the downlink network condition cannot support both audio and video to guarantee the quality of the audio. The SDK monitors the network quality and restores the video stream when the network conditions improve. Once the locally published stream falls back to audio only, or the audio stream switches back to the video stream, the onRemoteSubscribeFallbackToAudioOnly callback is triggered.

Parameters

option

Sets the fallback option for the remotely subscribed stream: STREAM_FALLBACK_OPTION_DISABLED(0): No fallback operation for the remotely subscribed stream when the downlink condition is poor. The quality of the stream cannot be guaranteed. STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW(1): (Default) The remotely subscribed stream falls back to the low stream when the downlink network condition worsens. This option works only for setRemoteSubscribeFallbackOption and not for setLocalPublishFallbackOption. STREAM_FALLBACK_OPTION_AUDIO_ONLY(2): Under poor downlink network conditions, the remotely subscribed video stream first falls back to the low video stream; and then to an audio-only stream if the network condition worsens.

Returns

• 0: Success.
• < 0: Failure.

Enables/Disables the dual-stream mode.

If dual-stream mode is enabled, the receiver can choose to receive the high stream (high-resolution high-bitrate video stream), or low stream (low-resolution low-bitrate video stream).

Parameters

enabled

Sets the stream mode: true: Dual-stream mode. false: (Default) Single-stream mode.

Returns

• 0: Success.
• < 0: Failure.

Sets the video stream type of the subscribed stream when the remote user sends dual streams. This method allows the app to adjust the corresponding video-stream type based on the size of the video window to reduce the bandwidth and resources.

• If the remote user enabled the dual-stream mode by calling enableDualStreamMode, the SDK receives the high-video stream by default. You can use this method to switch to the low-video stream type.
• If the dual-stream mode is not enabled, the SDK receives the high-video stream by default.

The method result returns in the onApiCallExecuted callback. The Agora SDK receives the high-video stream by default to save the bandwidth. If needed, users may use this method to switch to the low-video stream. By default, the aspect ratio of the low-video stream is the same as the high-video stream. Once the resolution of the high-video stream is set, the system automatically sets the resolution, frame rate, and bitrate of the low-video stream.

Parameters

uid	ID of the remote user sending the video stream.
streamType	Sets the video-stream type: High-resolution, high-bitrate video stream: High-video stream(0) Low-resolution, low-bitrate video stream: Low-video stream(1)

Returns

• 0: Success.
• < 0: Failure.

Sets the default video-stream type for the video type of the subscribed stream when the remote user sends dual streams.

Parameters

streamType

Sets the default video-stream type: High-resolution, high-bitrate video stream: High-video stream(0) Low-resolution, low-bitrate video stream: Low-video stream(1)

Returns

• 0: Success.
• < 0: Failure.

Enables built-in encryption with an encryption password before joining a channel.

All users in a channel must set the same encryption password. The encryption password is automatically cleared once a user leaves the channel. If the encryption password is not specified or set to empty, the encryption functionality is disabled.

Parameters

secret

Encryption password.

Note

Do not use this method for CDN live streaming.

Returns

• 0: Success.
• < 0: Failure.

Sets the built-in encryption mode.

The Agora SDK supports built-in encryption, which is set to aes-128-xts mode by default. Call this method to set the encryption mode to use other encryption modes. All users in the same channel must use the same encryption mode and password.

Refer to the information related to the AES encryption algorithm on the differences between the encryption modes.

Parameters

encryptionMode

Sets the encryption mode: "aes-128-xts": 128-bit AES encryption, XTS mode. "aes-128-ecb": 128-bit AES encryption, ECB mode. "aes-256-xts": 256-bit AES encryption, XTS mode. "": When encryptionMode is set as null, the encryption is in “aes-128-xts” by default.

Note

Call setEncryptionSecret before calling this method.

Returns

• 0: Success.
• < 0: Failure.

Injects an online media stream to a live broadcast.

The onStreamPublished callback returns the inject status. If this method is called successfully, the server pulls the voice or video stream and injects it into a live channel. This is applicable to scenarios where all of the audience members in the channel can watch a live show and interact with each other.

The onUserJoined and onFirstRemoteVideoDecoded callbacks are triggered and a stream uid of 666 is returned.

Parameters

url	HTTP/HTTPS URL address to be added to the ongoing live broadcast. Valid protocols are RTMP, HLS, and FLV. Supported FLV audio codec type: AAC. Supported FLV video codec type: H264(AVC).
config	The LiveInjectStreamConfig object which contains the configuration information for the added voice or video stream.

Returns

• 0: Success.
• < 0: Failure.
  • ERR_INVALID_ARGUMENT(2): The injected URL does not exist. Call this method again to inject the stream and ensure that the URL is valid.
  • ERR_NOT_READY(3): The user is not in the channel.
  • ERR_NOT_SUPPORTED(4): The channel profile is not live broadcast. Call setChannelProfile and set the channel profile to live broadcast before calling this method.
  • ERR_NOT_INITIALIZED(7): The SDK is not initialized. Ensure that the RtcEngine object is initialized before using this method.

Removes the injected online media stream from a live broadcast.

This method removes the HTTP/HTTPS URL address (added by addInjectStreamUrl) from the live broadcast.

If successful, the onUserOffline callback is triggered and a stream uid of 666 is returned.

Parameters

url	HTTP/HTTPS URL address of the added stream to be removed.

Returns

• 0: Success.
• < 0: Failure.

Adds a CDN stream address.

The host publishes the stream to the specified CDN live HTTP/HTTPS URL address. This method triggers the onStreamPublished callback.

Parameters

url	RTMP address, to which the host publishes the stream.
transcodingEnabled	Sets whether transcoding is enabled/disabled: true: Enable transcoding. To transcode the audio or video streams when publishing them to CDN live, often used for combining the audio and video streams of multiple hosts in CDN live. false: Disable transcoding.

Note

• Ensure that the user joins the channel before calling this method.
• This method adds only one stream HTTP/HTTPS URL address each time it is called.
• The HTTP/HTTPS URL address must not contain special characters such as Chinese language characters.
• Ensure that this method is called after setLiveTranscoding.

Returns

• 0: Success.
• < 0: Failure.
  • ERR_INVALID_ARGUMENT(2): Invalid parameter, usually because the URL address is null or the string length is 0.
  • ERR_NOT_INITIALIZED(7): You have not initialized the RTC engine when publishing the stream.

Removes a CDN stream address.

This method removes the HTTP/HTTPS URL address (added by addPublishStreamUrl) from a CDN live stream.

Parameters

url	HTTP/HTTPS URL address to be removed.

Note

• This method removes only one stream HTTP/HTTPS URL address each time it is called.
• The HTTP/HTTPS URL address must not contain special characters such as Chinese language characters.

Returns

• 0: Success.
• < 0: Failure.

Sets the video layout and audio settings for CDN live.

Note

Before calling the methods listed in this section:

• Ensure that the CDN push-stream function is enabled by contacting sales.nosp@m.@ago.nosp@m.ra.io.
• Ensure that setClientRole is called and the user role is set as the host.
• Ensure that setLiveTranscoding is called before addPublishStreamUrl.

Parameters

transcoding

Sets the CDN live audio/video transcoding settings. See LiveTranscoding.

Returns

• 0: Success.
• < 0: Failure.

Configures the CDN live streaming before joining a channel.

Deprecated:

This method is deprecated. Agora recommends using the following methods instead:

• addPublishStreamUrl
• removePublishStreamUrl
• setLiveTranscoding

Builder class to configure the push-stream for CDN live: Builder Class.

Parameters

config

Sets the CDN live streaming settings. See PublisherConfiguration.

Note

• Check the Builder Class on how to call each method included for the push-stream settings configuration.
• Set the resolution, frame rate, and bitrate to the same as those of the uplink host to avoid video quality degradation.

Returns

• 0: Success.
• < 0: Failure.

Sets the picture-in-picture layout for the CDN live broadcast. (CDN live only.)

Deprecated:

This method is deprecated. Agora recommends using setLiveTranscoding for CDN live streaming configurations.

This method sets the picture-in-picture layouts for live broadcasts. This method is only applicable when you want to push streams to the Agora server. When you push the stream to the Agora server:

1. Define a canvas, the width and height (video resolution), background color, and the total number of video streams you want to display.
2. Define the position and size for each video stream on the canvas, and indicate whether the view is cropped or zoomed to fit.

The push stream app formats the information of the customized layouts as JSON and packages it in the Supplemental Enhancement Information (SEI) of each keyframe when generating the H.264 video stream and pushing it to the CDN live vendors through the RTMP protocol.

Note

• Call this method after joining a channel.
• The app should only allow one user to call this method in the same channel. If more than one user calls this method, the other users must call clearVideoCompositingLayout to remove the settings.

Parameters

layout

Sets the picture-in-picture layout. See VideoCompositingLayout.

Removes the picture-in-picture layout settings created by setVideoCompositingLayout. (CDN live only.)

Deprecated:

This method is deprecated.

Creates a data stream.

Each user can have up to five simultaneous data channels.

Parameters

reliable

Sets whether or not the recipients are guaranteed to receive the data stream from the sender within five seconds: true: The recipients receive the data from the sender within five seconds. If the recipient does not receive the data within five seconds, the onStreamMessageError callback is triggered and an error code is reported. false: There is no guarantee that the recipients receive the data stream within five seconds and no error message is reported for any delay or missing data stream.

ordered

Sets whether or not the recipients receive the data stream in the sent order: true: The recipients receive the data in the sent order. false: The recipients do not receive the data in the sent order.

Note

Set both the reliable and ordered parameters to true or false. Do not set one as true and the other as false.

Returns

• Returns the stream ID, if the method call is successful.
• < 0: Failure.

The error code is related to the integer displayed in Error Codes. For example, if it returns -2, then it indicates ERR_INVALID_ARGUMENT(-2) in Error Codes.

Sends data stream messages.

The SDK has the following restrictions on this method:

• Up to 30 packets can be sent per second in a channel with each packet having a maximum size of 1 kB.
• Each client can send up to 6 kB of data per second.
• Each user can have up to five data channels simultaneously.

Parameters

streamId	ID of the sent data stream returned by createDataStream.
message	Sent data.

Note

This method applies only to the communication profile or to the hosts in the live broadcast profile. If an audience in the live broadcast profile calls this method, the audience role may be changed to a host.

Returns

• 0: Success.
• < 0: Failure.

Sets the preference option for the video quality (Live Broadcast only).

Parameters

preferFrameRateOverImageQuality

Sets the video quality preference: true: Frame rate over image quality. false: (Default) Image quality over frame rate.

Returns

• 0: Success.
• < 0: Failure.

Sets the local video mirror mode.

Use this method before startPreview, or the mirror mode does not take effect until you re-enable startPreview.

Parameters

mode	Sets the local video mirror mode: VIDEO_MIRROR_MODE_AUTO(0): (Default) The mirror mode determined by the SDK. VIDEO_MIRROR_MODE_ENABLED(1): Enable the mirror mode. VIDEO_MIRROR_MODE_DISABLED(2): Disable the mirror mode.

Returns

• 0: Success.
• < 0: Failure.

Gets the recommended encoder type.

Deprecated:

This method is deprecated.

Returns

The encoder type:

• HARDWARE ENCODER(1): The hardware encoder.
• SOFTWARE ENCODER(2): The software encoder.

Switches between the front and rear cameras.

Returns

• 0: Success.
• < 0: Failure.

Checks whether the camera zoom function is supported.

Returns

• true: The device supports the camera zoom function.
• false: The device does not support the camera zoom function.

Checks whether the camera flash function is supported.

Returns

• true: The device supports the camera flash function.
• false: The device does not the support camera flash function.

Checks whether the camera manual focus function is supported.

Returns

• true: The device supports the camera manual focus function.
• false: The device does not support the camera manual focus function.

Checks whether the camera auto-face focus function is supported.

Returns

• true: The device supports the camera auto-face focus function.
• false: The device does not support the camera auto-face focus function.

Sets the camera zoom ratio.

Parameters

factor

Sets the camera zoom factor. The value ranges between 1.0 and the maximum zoom supported by the device.

Returns

• The set camera zoom factor, if this method call is successful.
• < 0: Failure.

Gets the maximum zoom ratio supported by the camera.

Returns

The maximum camera zoom factor.

Sets the camera manual focus position.

Parameters

positionX	Sets the horizontal coordinate of the touch point in the view.
positionY	Sets the vertical coordinate of the touch point in the view.

Returns

• 0: Success.
• < 0: Failure.

Enables the camera flash function.

Parameters

isOn	Sets whether to enable/disable the camera flash function: true: Enable the camera flash function. false: Disable the camera flash function.

Returns

• 0: Success.
• < 0: Failure.

Enables the camera auto-face focus function.

Parameters

enabled

Sets whether to enable/disable the camera auto-face focus function: true: Enable the camera auto-face focus function. false: (Default) Disable the camera auto-face focus function.

Gets the current call ID.

When a user joins a channel on a client, a call ID is generated to identify the call from the client. Feedback methods, such as rate and complain, must be called after the call ends to submit feedback to the SDK.

The rate and complain methods require the callId parameter retrieved from the getCallId method during a call. callId is passed as an argument into the rate and complain methods after the call ends.

Returns

Current call ID.

Allows the user to rate the call after the call ends.

Parameters

callId	ID of the call retrieved from the getCallId method.
rating	The rating of the call. The value is between 1 (lowest score) and 10 (highest score).
description	(Optional) The description of the rating. The string length must be less than 800 bytes.

Returns

• 0: Success.
• < 0: Failure.
  • ERR_INVALID_ARGUMENT(-2)
  • ERR_NOT_READY(-3)

Allows a user to complain about the call quality after a call ends.

Parameters

callId	ID of the call retrieved from the getCallId method.
description	(Optional) The description of the complaint. The string length must be less than 800 bytes.

Returns

• 0: Success.
• < 0: Failure.

Gets the SDK version.

Returns

The version of the current SDK in the string format. For example, 2.3.0.

Gets the media engine version.

Deprecated:

This method is deprecated.

Returns

The string of the version number in the char format.

Specifies an SDK output log file.

The log file records all log data for the SDK’s operation. Ensure that the directory for the log file exists and is writable.

Parameters

filePath

File path of the log file. The string of the log file is in UTF-8. The default file path is /sdcard/{Package name of the App}/agorasdk.log.

Returns

• 0: Success.
• < 0: Failure.

Sets the output log level of the SDK.

You can use one or a combination of the filters. The log level follows the sequence of OFF, CRITICAL, ERROR, WARNING, INFO, and DEBUG. Choose a level to see the logs preceding that level. For example, if you set the log level to WARNING, you see the logs within levels CRITICAL, ERROR, and WARNING.

Parameters

filter

Sets the log filter level: LOG_FILTER_OFF(0): Do not output any log. LOG_FILTER_DEBUG(0x80f): Output all the API logs. LOG_FILTER_INFO(0x0f): Output logs of the CRITICAL, ERROR, WARNING, and INFO level. LOG_FILTER_WARNING(0x0e): Output logs of the CRITICAL, ERROR, and WARNING level. LOG_FILTER_ERROR(0x0c): Output logs of the CRITICAL and ERROR level. LOG_FILTER_CRITICAL(0x08): Output logs of the CRITICAL level.

Returns

• 0: Success.
• < 0: Failure.

Gets the native handle of the SDK engine.

This interface is used to retrieve the native C++ handle of the SDK engine used in special scenarios, such as registering the audio and video frame observer.

Returns

The native handler of the SDK engine.

Adds the IRtcEngineEventHandler class.

The SDK uses the IRtcEngineEventHandler interface class to send callbacks to the app, and the app inherits the methods of the IRtcEngineEventHandler interface class to retrieve the callbacks.

Parameters

handler

IRtcEngineEventHandler

Enables the Wi-Fi mode.

Deprecated:

This method is deprecated.

Parameters

enable

Sets whether to enable/disable the Wi-Fi mode: true: Enable the Wi-Fi mode. false: Disable the Wi-Fi mode.

Returns

• 0: Success.
• < 0: Failure.

Gets the warning or error description.

Parameters

error

Detailed warning or error description in Warning Code or Error Code

Returns

• 0: Success.
• < 0: Failure.

Monitors the external headset device events.

Deprecated:

This method is deprecated.

Parameters

monitor

Sets whether to enable/disable monitoring the external headset device events: true: Enables monitoring the external headset device events. false: Disables monitoring the external headset device events.

Monitors the Bluetooth headset device events.

Deprecated:

This method is deprecated.

Parameters

monitor

Sets whether to enable/disable monitoring the Bluetooth headset device events: true: Enables monitoring the Bluetooth headset device events. false: Disables monitoring the Bluetooth headset device events.

Sets the default audio route to the headset.

Deprecated:

This method is deprecated.

Parameters

enabled

Sets whether or not the default audio route is to the headset: true: Set the default audio route to the headset. false: Do not set the default audio route to the headset.

Provides technical preview functionalities or special customizations by configuring the SDK with JSON options.

The JSON options are not public by default. Agora is working on making commonly used JSON options public in a standard way.

Parameters

parameters

Sets the parameter as a JSON string in the specified format.

Returns

• 0: Success.
• < 0: Failure.

Gets the Agora SDK’s parameters for customization purposes. This method is not disclosed yet. Contact support@agora.io for more information.