Public Member Functions

abstract int setChannelProfile (int profile)
 
abstract int setClientRole (int role)
 
abstract int joinChannel (String token, String channelName, String optionalInfo, int optionalUid)
 
abstract int switchChannel (String token, String channelName)
 
abstract int leaveChannel ()
 
abstract int renewToken (String token)
 
abstract int registerLocalUserAccount (String appId, String userAccount)
 
abstract int joinChannelWithUserAccount (String token, String channelName, String userAccount)
 
abstract int getUserInfoByUserAccount (String userAccount, UserInfo userInfo)
 
abstract int getUserInfoByUid (int uid, UserInfo userInfo)
 
abstract int enableWebSdkInteroperability (boolean enabled)
 
abstract int getConnectionState ()
 
abstract int enableAudio ()
 
abstract int disableAudio ()
 
abstract int pauseAudio ()
 
abstract int resumeAudio ()
 
abstract int setAudioProfile (int profile, int scenario)
 
abstract int setHighQualityAudioParameters (boolean fullband, boolean stereo, boolean fullBitrate)
 
abstract int adjustRecordingSignalVolume (int volume)
 
abstract int adjustPlaybackSignalVolume (int volume)
 
abstract int enableAudioVolumeIndication (int interval, int smooth, boolean report_vad)
 
abstract int enableAudioQualityIndication (boolean enabled)
 
abstract int enableLocalAudio (boolean enabled)
 
abstract int muteLocalAudioStream (boolean muted)
 
abstract int muteRemoteAudioStream (int uid, boolean muted)
 
abstract int muteAllRemoteAudioStreams (boolean muted)
 
abstract int setDefaultMuteAllRemoteAudioStreams (boolean muted)
 
abstract int enableVideo ()
 
abstract int disableVideo ()
 
abstract int setVideoProfile (int profile, boolean swapWidthAndHeight)
 
abstract int setVideoProfile (int width, int height, int frameRate, int bitrate)
 
abstract int setVideoEncoderConfiguration (VideoEncoderConfiguration config)
 
abstract int setCameraCapturerConfiguration (CameraCapturerConfiguration config)
 
abstract int setupLocalVideo (VideoCanvas local)
 
abstract int setupRemoteVideo (VideoCanvas remote)
 
abstract int setLocalRenderMode (int mode)
 
abstract int setRemoteRenderMode (int uid, int mode)
 
abstract int startPreview ()
 
abstract int stopPreview ()
 
abstract int enableLocalVideo (boolean enabled)
 
abstract int muteLocalVideoStream (boolean muted)
 
abstract int muteRemoteVideoStream (int uid, boolean muted)
 
abstract int muteAllRemoteVideoStreams (boolean muted)
 
abstract int setDefaultMuteAllRemoteVideoStreams (boolean muted)
 
abstract int setBeautyEffectOptions (boolean enabled, BeautyOptions options)
 
abstract int setDefaultAudioRoutetoSpeakerphone (boolean defaultToSpeaker)
 
abstract int setEnableSpeakerphone (boolean enabled)
 
abstract boolean isSpeakerphoneEnabled ()
 
abstract int enableInEarMonitoring (boolean enabled)
 
abstract int setInEarMonitoringVolume (int volume)
 
abstract int useExternalAudioDevice ()
 
abstract int setLocalVoicePitch (double pitch)
 
abstract int setLocalVoiceEqualization (int bandFrequency, int bandGain)
 
abstract int setLocalVoiceReverb (int reverbKey, int value)
 
abstract int setLocalVoiceChanger (int voiceChanger)
 
abstract int setLocalVoiceReverbPreset (int preset)
 
abstract int enableSoundPositionIndication (boolean enabled)
 
abstract int setRemoteVoicePosition (int uid, double pan, double gain)
 
abstract int startAudioMixing (String filePath, boolean loopback, boolean replace, int cycle)
 
abstract int stopAudioMixing ()
 
abstract int pauseAudioMixing ()
 
abstract int resumeAudioMixing ()
 
abstract int adjustAudioMixingVolume (int volume)
 
abstract int adjustAudioMixingPlayoutVolume (int volume)
 
abstract int adjustAudioMixingPublishVolume (int volume)
 
abstract int getAudioMixingPlayoutVolume ()
 
abstract int getAudioMixingPublishVolume ()
 
abstract int getAudioMixingDuration ()
 
abstract int getAudioMixingCurrentPosition ()
 
abstract int setAudioMixingPosition (int pos)
 
abstract IAudioEffectManager getAudioEffectManager ()
 
abstract int startAudioRecording (String filePath, int quality)
 
abstract int startAudioRecording (String filePath, int sampleRate, int quality)
 
abstract int stopAudioRecording ()
 
abstract int startEchoTest ()
 
abstract int startEchoTest (int intervalInSeconds)
 
abstract int stopEchoTest ()
 
abstract int enableLastmileTest ()
 
abstract int disableLastmileTest ()
 
abstract int startLastmileProbeTest (LastmileProbeConfig config)
 
abstract int stopLastmileProbeTest ()
 
abstract int setVideoSource (IVideoSource source)
 
abstract int setLocalVideoRenderer (IVideoSink render)
 
abstract int setRemoteVideoRenderer (int uid, IVideoSink render)
 
abstract int setExternalAudioSink (boolean enabled, int sampleRate, int channels)
 
abstract int pullPlaybackAudioFrame (byte[] data, int lengthInByte)
 
abstract int setExternalAudioSource (boolean enabled, int sampleRate, int channels)
 
abstract int pushExternalAudioFrame (byte[] data, long timestamp)
 
abstract void setExternalVideoSource (boolean enable, boolean useTexture, boolean pushMode)
 
abstract boolean pushExternalVideoFrame (AgoraVideoFrame frame)
 
abstract boolean isTextureEncodeSupported ()
 
abstract int registerAudioFrameObserver (IAudioFrameObserver observer)
 
abstract int setRecordingAudioFrameParameters (int sampleRate, int channel, int mode, int samplesPerCall)
 
abstract int setPlaybackAudioFrameParameters (int sampleRate, int channel, int mode, int samplesPerCall)
 
abstract int setMixedAudioFrameParameters (int sampleRate, int samplesPerCall)
 
abstract int addVideoWatermark (AgoraImage watermark)
 
abstract int addVideoWatermark (String watermarkUrl, WatermarkOptions options)
 
abstract int clearVideoWatermarks ()
 
abstract int setRemoteUserPriority (int uid, int userPriority)
 
abstract int setLocalPublishFallbackOption (int option)
 
abstract int setRemoteSubscribeFallbackOption (int option)
 
abstract int enableDualStreamMode (boolean enabled)
 
abstract int setRemoteVideoStreamType (int uid, int streamType)
 
abstract int setRemoteDefaultVideoStreamType (int streamType)
 
abstract int setEncryptionSecret (String secret)
 
abstract int setEncryptionMode (String encryptionMode)
 
abstract int addInjectStreamUrl (String url, LiveInjectStreamConfig config)
 
abstract int removeInjectStreamUrl (String url)
 
abstract int addPublishStreamUrl (String url, boolean transcodingEnabled)
 
abstract int removePublishStreamUrl (String url)
 
abstract int setLiveTranscoding (LiveTranscoding transcoding)
 
abstract int createDataStream (boolean reliable, boolean ordered)
 
abstract int sendStreamMessage (int streamId, byte[] message)
 
abstract int setVideoQualityParameters (boolean preferFrameRateOverImageQuality)
 
abstract int setLocalVideoMirrorMode (int mode)
 
abstract int switchCamera ()
 
abstract boolean isCameraZoomSupported ()
 
abstract boolean isCameraTorchSupported ()
 
abstract boolean isCameraFocusSupported ()
 
abstract boolean isCameraExposurePositionSupported ()
 
abstract boolean isCameraAutoFocusFaceModeSupported ()
 
abstract int setCameraZoomFactor (float factor)
 
abstract float getCameraMaxZoomFactor ()
 
abstract int setCameraFocusPositionInPreview (float positionX, float positionY)
 
abstract int setCameraExposurePosition (float positionXinView, float positionYinView)
 
abstract int setCameraTorchOn (boolean isOn)
 
abstract int setCameraAutoFocusFaceModeEnabled (boolean enabled)
 
abstract String getCallId ()
 
abstract int rate (String callId, int rating, String description)
 
abstract int complain (String callId, String description)
 
abstract int setLogFile (String filePath)
 
abstract int setLogFilter (int filter)
 
abstract int setLogFileSize (int fileSizeInKBytes)
 
abstract long getNativeHandle ()
 
void addHandler (IRtcEngineEventHandler handler)
 
void removeHandler (IRtcEngineEventHandler handler)
 
abstract boolean enableHighPerfWifiMode (boolean enable)
 
abstract void monitorHeadsetEvent (boolean monitor)
 
abstract void monitorBluetoothHeadsetEvent (boolean monitor)
 
abstract void setPreferHeadset (boolean enabled)
 
abstract int setParameters (String parameters)
 
abstract String getParameter (String parameter, String args)
 
abstract int registerMediaMetadataObserver (IMetadataObserver observer, int type)
 
abstract int startChannelMediaRelay (ChannelMediaRelayConfiguration channelMediaRelayConfiguration)
 
abstract int stopChannelMediaRelay ()
 
abstract int updateChannelMediaRelay (ChannelMediaRelayConfiguration channelMediaRelayConfiguration)
 
abstract int startDumpVideoReceiveTrack (int uid)
 
abstract int stopDumpVideoReceiveTrack ()
 

Static Public Member Functions

static synchronized RtcEngine create (Context context, String appId, IRtcEngineEventHandler handler) throws Exception
 
static synchronized void destroy ()
 
static SurfaceView CreateRendererView (Context context)
 
static int getRecommendedEncoderType ()
 
static String getSdkVersion ()
 
static String getMediaEngineVersion ()
 
static String getErrorDescription (int error)
 

Detailed Description

RtcEngine is the main interface class of the Agora SDK.

Call the methods of this class to use all functionalities of the SDK. We recommend calling the RtcEngine API methods in the same thread instead of in multiple threads. In previous versions, this class was named AgoraAudio, and was renamed to RtcEngine from v1.0.

Member Function Documentation

◆ create()

static synchronized RtcEngine io.agora.rtc.RtcEngine.create ( Context  context,
String  appId,
IRtcEngineEventHandler  handler 
) throws Exception
static

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. We recommend calling the interface methods in the same thread.
  • The following rule applies to all API methods whose return values are integer types:
    • 0: The method call succeeds.
    • < 0: The method call fails.
Parameters
contextThe context of Android Activity.
appIdThe App ID issued to you by Agora. Apply for a new App ID from Agora if it is missing from your kit.
handlerIRtcEngineEventHandler is an abstract class providing default implementation. The SDK uses this class to report to the app on SDK runtime events.
Returns
RtcEngine object.
Exceptions
ExceptionFails to create an RtcEngine instance.
Note
  • Ensure that you call this method before calling any other API.
  • Only users with the same App ID can join the same channel and call each other.
  • An App ID can create only one RtcEngine object. For multiple App IDs in an app, you need to create multiple RtcEngine objects. Call destroy first to destroy the current RtcEngine instance before calling this method.

◆ destroy()

static synchronized void io.agora.rtc.RtcEngine.destroy ( )
static

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, you cannot use any method or callback in the SDK.

◆ setChannelProfile()

abstract int io.agora.rtc.RtcEngine.setChannelProfile ( int  profile)
abstract

Sets the channel profile.

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

Parameters
profileSets the channel profile:
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 RtcEngine and create a new RtcEngine using the createmethod.
  • 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.

◆ setClientRole()

abstract int io.agora.rtc.RtcEngine.setClientRole ( int  role)
abstract

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

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

This method can be used to switch the user role after a user joins a channel. In the Live Broadcast profile, when a user switches user roles after joining a channel, a successful setClientRole method call triggers the following callbacks:

Parameters
roleSets the role of a user. See ClientRole.
Returns
  • 0: Success.
  • < 0: Failure.

◆ joinChannel()

abstract int io.agora.rtc.RtcEngine.joinChannel ( String  token,
String  channelName,
String  optionalInfo,
int  optionalUid 
)
abstract

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 joining another channel.

A successful joinChannel method call triggers the following callbacks:

  • The local client: onJoinChannelSuccess.
  • The remote client: onUserJoined, if the user joining the channel is in the Communication profile, or is a BROADCASTER in the Live Broadcast profile.

When the connection between the client and Agora's server is interrupted due to poor network conditions, the SDK tries reconnecting to the server. When the local client successfully rejoins the channel, the SDK triggers the onRejoinChannelSuccess callback on the local client.

Parameters
tokenThe token generated at your server:
  • For low-security requirements: You can use the temporary token generated at Console. For details, see Get a temporary token.
  • For high-security requirements: Set it as the token generated at your server. For details, see Get a token.
channelNameUnique 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: a to z.
  • The 26 uppercase English letters: A to Z.
  • The 10 numbers: 0 to 9.
  • The space.
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
optionalInfoAdditional information about the channel. This parameter can be set as 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). optionalUid must be unique. If optionalUid is not assigned (or set to 0), the SDK assigns and returns 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 the create method for creating an RtcEngine object. Otherwise, CDN live streaming may fail.
Returns

◆ switchChannel()

abstract int io.agora.rtc.RtcEngine.switchChannel ( String  token,
String  channelName 
)
abstract

Switches to a different channel.

Since
v2.9.0.

This method allows the audience of a Live-broadcast channel to switch to a different channel.

After the user successfully switches to another channel, the onLeaveChannel and onJoinChannelSuccess callbacks are triggered to indicate that the user has left the original channel and joined a new one.

Note
This method applies to the audience role in a Live-broadcast channel only.
Parameters
tokenThe token generated at your server:
  • For low-security requirements: You can use the temporary token generated in Console. For details, see Get a temporary token.
  • For high-security requirements: Use the token generated at your server. For details, see Get a token.
channelNameUnique 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: a to z.
  • The 26 uppercase English letters: A to Z.
  • The 10 numbers: 0 to 9.
  • The space.
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
Returns
  • 0: Success.
  • < 0: Failure.

◆ leaveChannel()

abstract int io.agora.rtc.RtcEngine.leaveChannel ( )
abstract

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.

A successful leaveChannel method call triggers the following callbacks:

  • The local client: onLeaveChannel.
  • The remote client: onUserOffline, if the user leaving the channel is in the Communication channel, or is a BROADCASTER in the Live Broadcast profile.
    Note
    Returns
    • 0: Success.
    • < 0: Failure.

◆ renewToken()

abstract int io.agora.rtc.RtcEngine.renewToken ( String  token)
abstract

Renews the token when the current token expires.

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

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
tokenThe new token.
Returns
  • 0: Success.
  • < 0: Failure.

◆ registerLocalUserAccount()

abstract int io.agora.rtc.RtcEngine.registerLocalUserAccount ( String  appId,
String  userAccount 
)
abstract

Registers a user account.

Since
v2.8.0.

Once registered, the user account can be used to identify the local user when the user joins the channel. After the user successfully registers a user account, the SDK triggers the onLocalUserRegistered callback on the local client, reporting the user ID and user account of the local user.

To join a channel with a user account, you can choose either of the following:

The difference between the two is that for the former, the time elapsed between calling the joinChannelWithUserAccount method and joining the channel is shorter than the latter.

Note
  • Ensure that you set the userAccount parameter. Otherwise, this method does not take effect.
  • Ensure that the value of the userAccount parameter is unique in the channel.
  • To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the uid of the user is set to the same parameter type.
Parameters
appIdThe App ID of your project.
userAccountThe user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are:
  • The 26 lowercase English letters: a to z.
  • The 26 uppercase English letters: A to Z.
  • The 10 numbers: 0 to 9.
  • The space.
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
Returns
  • 0: Success.
  • < 0: Failure.

◆ joinChannelWithUserAccount()

abstract int io.agora.rtc.RtcEngine.joinChannelWithUserAccount ( String  token,
String  channelName,
String  userAccount 
)
abstract

Joins the channel with a user account.

Since
v2.8.0.

After the user successfully joins the channel, the SDK triggers the following callbacks:

Note
To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the uid of the user is set to the same parameter type.
Parameters
tokenThe token generated at your server:
  • For low-security requirements: You can use the temporary token generated at Console. For details, see Get a temporary token.
  • For high-security requirements: Set it as the token generated at your server. For details, see Get a token.
channelNameThe channel name. The maximum length of this parameter is 64 bytes. Supported character scopes are:
  • The 26 lowercase English letters: a to z.
  • The 26 uppercase English letters: A to Z.
  • The 10 numbers: 0 to 9.
  • The space.
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
userAccountThe user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are:
  • The 26 lowercase English letters: a to z.
  • The 26 uppercase English letters: A to Z.
  • The 10 numbers: 0 to 9.
  • The space.
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
Returns
  • 0: Success.
  • < 0: Failure.

◆ getUserInfoByUserAccount()

abstract int io.agora.rtc.RtcEngine.getUserInfoByUserAccount ( String  userAccount,
UserInfo  userInfo 
)
abstract

Gets the user information by passing in the user account.

Since
v2.8.0.

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

After receiving the onUserInfoUpdated callback, you can call this method to get the user ID of the remote user from the userInfo object by passing in the user account.

Parameters
userAccountThe user account of the user. Ensure that you set this parameter.
userInfo[in/out] A userInfo object that identifies the user. For details, see UserInfo.
  • Input: A UserInfo object.
  • Output: A UserInfo object that contains the user account and user ID of the user.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getUserInfoByUid()

abstract int io.agora.rtc.RtcEngine.getUserInfoByUid ( int  uid,
UserInfo  userInfo 
)
abstract

Gets the user information by passing in the user ID.

Since
v2.8.0.

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

After receiving the onUserInfoUpdated callback, you can call this method to get the user ID of the remote user from the userInfo object by passing in the user account.

Parameters
uidThe user ID of the user. Ensure that you set this parameter.
userInfo[in/out] A userInfo object that identifies the user. For details, see UserInfo.
  • Input: A UserInfo object.
  • Output: A UserInfo object that contains the user account and user ID of the user.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableWebSdkInteroperability()

abstract int io.agora.rtc.RtcEngine.enableWebSdkInteroperability ( boolean  enabled)
abstract

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

If the channel has Web SDK users, ensure that you call this method, or the video of the Native user will be a black screen for the Web user.

Use this method when the channel profile is Live Broadcast. Interoperability with the Agora Web SDK is enabled by default when the channel profile is Communication.

Parameters
enabledSets whether to enable/disable interoperability with the Agora Web SDK:
  • true: Enable.
  • false: (Default) Disable.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getConnectionState()

abstract int io.agora.rtc.RtcEngine.getConnectionState ( )
abstract

Gets the connection state of the SDK.

Since
v2.3.2.
Returns
The connection state:

◆ enableAudio()

abstract int io.agora.rtc.RtcEngine.enableAudio ( )
abstract

Enables the audio module.

The audio module is enabled by default.

Note
  • This method affects the internal engine and can be called after calling the leaveChannel method. 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. We recommend using the following API methods to control the audio engine modules separately:
Returns
  • 0: Success.
  • < 0: Failure.

◆ disableAudio()

abstract int io.agora.rtc.RtcEngine.disableAudio ( )
abstract

Disables the audio module.

Note
  • This method affects the internal engine and can be called after calling the leaveChannel method. You can call this method either before or after joining a channel.
  • This method resets the engine and takes some time to take effect. We recommend using the following API methods to control the audio engine modules separately:
Returns
  • 0: Success.
  • < 0: Failure.

◆ pauseAudio()

abstract int io.agora.rtc.RtcEngine.pauseAudio ( )
abstract

Disables the audio function in the channel.

Deprecated:
This method is deprecated. We recommend using the enableAudio method instead.
Returns
  • 0: Success.
  • < 0: Failure.

◆ resumeAudio()

abstract int io.agora.rtc.RtcEngine.resumeAudio ( )
abstract

Resumes the audio playback in the channel.

Deprecated:
This method is deprecated. We recommend using the disableAudio method instead.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setAudioProfile()

abstract int io.agora.rtc.RtcEngine.setAudioProfile ( int  profile,
int  scenario 
)
abstract

Sets the audio parameters and application scenarios.

Parameters
profileSets the sample rate, bitrate, encoding mode, and the number of channels. See Audio Profile.
scenarioSets the audio application scenarios. See Audio Scenario. Under different audio scenarios, the device uses different volume tracks, i.e. either the in-call volume or the media volume. For details, see What is the difference between the in-call volume and the media volume?.
Note
  • You must call this method before calling the joinChannel method.
  • In the Communication and Live Broadcast profiles, the bitrates may be different from your settings due to network self-adaptation.
  • In scenarios involving music education, We recommend setting profile as AUDIO_SCENARIO_SHOWROOM(4) and scenario as AUDIO_SCENARIO_GAME_STREAMING(3) in Audio Scenario.

◆ setHighQualityAudioParameters()

abstract int io.agora.rtc.RtcEngine.setHighQualityAudioParameters ( boolean  fullband,
boolean  stereo,
boolean  fullBitrate 
)
abstract

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 the setAudioProfile method. Call this method and set all parameters before joining a channel. Do not call this method again after joining a channel.
Parameters
fullbandSets whether to enable/disable full-band codec (48-kHz sample rate), not compatible with versions earlier than v1.7.4:
  • true: Enable full-band codec.
  • false: Disable full-band codec.
stereoSets whether to enable/disable stereo codec, not compatible with versions earlier than v1.7.4:
  • true: Enable stereo codec.
  • false: Disable stereo codec.
fullBitrateSets 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.

◆ adjustRecordingSignalVolume()

abstract int io.agora.rtc.RtcEngine.adjustRecordingSignalVolume ( int  volume)
abstract

Adjusts the recording volume.

Parameters
volumeRecording 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.

◆ adjustPlaybackSignalVolume()

abstract int io.agora.rtc.RtcEngine.adjustPlaybackSignalVolume ( int  volume)
abstract

Adjusts the playback volume of the voice.

Parameters
volumeThe playback volume of the voice. 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.

◆ enableAudioVolumeIndication()

abstract int io.agora.rtc.RtcEngine.enableAudioVolumeIndication ( int  interval,
int  smooth,
boolean  report_vad 
)
abstract

Enables the onAudioVolumeIndication callback at a set time interval to report on which users are speaking and the speakers' 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
intervalSets the time interval between two consecutive volume indications:
  • ≤ 0: Disables the volume indication.
  • > 0: Time interval (ms) between two consecutive volume indications. We recommend setting interval ≥ 200 ms.
smoothThe 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.
report_vad
  • true: Enable the voice activity detection of the local user. Once it is enabled, the vad parameter of the onAudioVolumeIndication callback reports the voice activity status of the local user.
  • false: (Default) Disable the voice activity detection of the local user. Once it is enabled, the vad parameter of the onAudioVolumeIndication callback does not report the voice activity status of the local user, except for scenarios where the engine automatically detects the voice activity of the local user.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableAudioQualityIndication()

abstract int io.agora.rtc.RtcEngine.enableAudioQualityIndication ( boolean  enabled)
abstract

Enables the audio quality callbacks.

Deprecated:
From v2.4.1.

The SDK triggers the onAudioQuality callback after this method is enabled.

Parameters
enabledSets whether to enable/disable the audio quality callback:
  • true: Enable the audio quality notification callback.
  • false: (Default) Disable the audio quality notification callback.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableLocalAudio()

abstract int io.agora.rtc.RtcEngine.enableLocalAudio ( boolean  enabled)
abstract

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 enableLocalAudio(false) 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 SDK triggers the onMicrophoneEnabled callback once the local audio function is disabled or re-enabled.

Parameters
enabledSets 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 calling the joinChannelmethod.
  • After you disable local audio recording using the enableLocalAudio(false) method, the system volume switches to the media volume. Re-enabling local audio recording using the enableLocalAudio(true) method switches the system volume back to the in-call volume.
  • This method is different from the muteLocalAudioStream method:
    • enableLocalAudio: Disables/Re-enables the local audio capture and processing. If you disable or re-enable local audio recording using the enableLocalAudio method, the local user may hear a pause in the remote audio playback.
    • muteLocalAudioStream: Stops/Continues sending the local audio streams.
Returns
  • 0: Success.
  • < 0: Failure.

◆ muteLocalAudioStream()

abstract int io.agora.rtc.RtcEngine.muteLocalAudioStream ( boolean  muted)
abstract

Stops/Resumes sending the local audio stream.

A successful muteLocalAudioStream method call triggers the onUserMuteAudio callback on the remote client.

Parameters
mutedSets 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 muted is set as true, this method does not disable the microphone and thus does not affect any ongoing recording.
  • If you call setChannelProfile after this method, the SDK resets whether or not to mute the local audio according to the channel profile and user role. Therefore, we recommend calling this method after the setChannelProfile method.
Returns
  • 0: Success.
  • < 0: Failure.

◆ muteRemoteAudioStream()

abstract int io.agora.rtc.RtcEngine.muteRemoteAudioStream ( int  uid,
boolean  muted 
)
abstract

Stops/Resumes receiving a specified audio stream.

Parameters
uidID of the specified remote user.
mutedSets 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 the muteAllRemoteAudioStreams method and set muted as true to stop receiving all remote video streams, ensure that the muteAllRemoteAudioStreams method is called and set muted as false before calling this method. The muteAllRemoteAudioStreams method sets all remote audio streams, while the muteRemoteAudioStream method sets a specified remote user's audio stream.
Returns
  • 0: Success.
  • < 0: Failure.

◆ muteAllRemoteAudioStreams()

abstract int io.agora.rtc.RtcEngine.muteAllRemoteAudioStreams ( boolean  muted)
abstract

Stops/Resumes receiving all remote audio streams.

Parameters
mutedSets whether to receive/stop receiving all remote audio streams:
  • true: Stop receiving all remote audio streams.
  • false: (Default) Receive all remote audio streams.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setDefaultMuteAllRemoteAudioStreams()

abstract int io.agora.rtc.RtcEngine.setDefaultMuteAllRemoteAudioStreams ( boolean  muted)
abstract

Sets whether to receive all remote audio streams by default.

You can call this method either before or after joining a channel. If you call this method after joining a channel, the remote audio streams of all subsequent users are not received.

Parameters
mutedSets whether or not to receive/stop receiving all remote audio streams by default:
  • true: Stop receiving all remote audio streams by default.
  • false: (Default) Receive all remote audio streams by default.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableVideo()

abstract int io.agora.rtc.RtcEngine.enableVideo ( )
abstract

Enables the video module.

You can call this method either before joining a channel or during a call. If you call this method before joining a channel, the service starts in the video mode. If you call this method during an audio call, the audio mode switches to the video mode.

A successful enableVideo method call triggers the onUserEnableVideo(true) callback on the remote client.

To disable the video, call the disableVideo method.

Note
  • This method affects the internal engine and can be called after calling the leaveChannel method. 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. We recommend using the following API methods to control the video engine modules separately:
Returns
  • 0: Success.
  • < 0: Failure.

◆ disableVideo()

abstract int io.agora.rtc.RtcEngine.disableVideo ( )
abstract

Disables the video module.

You can call this method before joining a channel or during a call. If you call this method before joining a channel, the service starts in audio mode. If you call this method during a video call, the video mode switches to the audio mode.

A successful disableVideo method call triggers the onUserEnableVideo(false) callback on the remote client.

To enable the video mode, call the enableVideo method.

Note
  • This method affects the internal engine and can be called after calling the leaveChannel method. 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. We recommend using the following API methods to control the video engine modules separately:
Returns
  • 0: Success.
  • < 0: Failure.

◆ setVideoProfile() [1/2]

abstract int io.agora.rtc.RtcEngine.setVideoProfile ( int  profile,
boolean  swapWidthAndHeight 
)
abstract

Sets the video encoding profile.

Deprecated:
From v2.3.0. We recommend using the setVideoEncoderConfiguration method to set the video profile.

If you do not need to change the video encoding profile after joining a channel, call this method before calling the enableVideo method 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 this method.

Parameters
profileSets the video encoding profile. See VideoProfile.
swapWidthAndHeightThe 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 portrait mode (width < height).
  • false: (Default) Do not swap the width and height. The video is in landscape mode (width > height).
Returns
  • 0: Success.
  • < 0: Failure.

◆ setVideoProfile() [2/2]

abstract int io.agora.rtc.RtcEngine.setVideoProfile ( int  width,
int  height,
int  frameRate,
int  bitrate 
)
abstract

Manually sets the video encoding profile.

Deprecated:
From v2.3.0. We recommend using the setVideoEncoderConfiguration method 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 this method. If the user does not set the video encoding profile after joining a channel, We recommend calling this method before calling the enableVideo method to minimize the time delay in receiving the first video frame.

Parameters
widthSets the width of the video. The maximum value of width &times height is 1280 &times 720.
heightSets the height of the video. The maximum value of width &times height is 1280 &times 720.
frameRateSets the frame rate of the video. The highest value is 30. You can set frameRate as 5, 10, 15, 24, and 30.
bitrateSets 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 you set a bitrate beyond the proper range, the SDK automatically adjusts the bitrate to a value within the proper range.

◆ setVideoEncoderConfiguration()

abstract int io.agora.rtc.RtcEngine.setVideoEncoderConfiguration ( VideoEncoderConfiguration  config)
abstract

Sets the video encoder configuration.

Since
v2.3.0. This method replaces the setVideoProfile method.

Each video encoder configuration corresponds to a set of video parameters, including the resolution, frame rate, bitrate, and video orientation. 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.

If you do not set the video encoder configuration after joining the channel, you can call this method before calling the enableVideo method to reduce the render time of the first video frame.

Parameters
configThe local video encoder configuration. See VideoEncoderConfiguration.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setCameraCapturerConfiguration()

abstract int io.agora.rtc.RtcEngine.setCameraCapturerConfiguration ( CameraCapturerConfiguration  config)
abstract

Sets the camera capturer configuration.

Since
v2.4.0.

For a video call or live broadcast, generally the SDK controls the camera output parameters. When the default camera capture settings do not meet special requirements or cause performance problems, we recommend using this method to set the camera capturer configuration:

  • If the resolution or frame rate of the captured raw video data are higher than those set by setVideoEncoderConfiguration, processing video frames requires extra CPU and RAM usage and degrades performance. We recommend setting config as CAPTURER_OUTPUT_PREFERENCE_PERFORMANCE(1) to avoid such problems.
  • If you do not need local video preview or are willing to sacrifice preview quality, we recommend setting config as CAPTURER_OUTPUT_PREFERENCE_PERFORMANCE(1) to optimize CPU and RAM usage.
  • If you want better quality for the local video preview, we recommend setting config as CAPTURER_OUTPUT_PREFERENCE_PREVIEW(2).
Parameters
configThe camera capturer configuration. For details, see CameraCapturerConfiguration.
Note
Call this method before enabling the local camera. That said, you can call this method before calling joinChannel, enableVideo, or enableLocalVideo, depending on which method you use to turn on your local camera.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setupLocalVideo()

abstract int io.agora.rtc.RtcEngine.setupLocalVideo ( VideoCanvas  local)
abstract

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

You can call this method to bind each video window (view) of the local video streams and configure the video display settings. Call this method after initialization to configure the local video display settings before joining 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 view in Video Canvas as null.

Note
Ensure that you call this method in the UI thread.
Parameters
localSets the local video view and settings. See Video Canvas.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setupRemoteVideo()

abstract int io.agora.rtc.RtcEngine.setupRemoteVideo ( VideoCanvas  remote)
abstract

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 user sending the video in the method call before the remote user joins a channel. If the uid of the remote user 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 SDK triggers the onFirstRemoteVideoDecoded callback.

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

Note
Ensure that you call this method in the UI thread.
Parameters
remoteSets the remote video view and settings. See Video Canvas.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLocalRenderMode()

abstract int io.agora.rtc.RtcEngine.setLocalRenderMode ( int  mode)
abstract

Sets the local video display mode.

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

Parameters
modeSets 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.

◆ setRemoteRenderMode()

abstract int io.agora.rtc.RtcEngine.setRemoteRenderMode ( int  uid,
int  mode 
)
abstract

Sets the remote video display mode.

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

Parameters
uidUser ID of the remote user.
modeSets 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.

◆ CreateRendererView()

static SurfaceView io.agora.rtc.RtcEngine.CreateRendererView ( Context  context)
static

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.

Note
Ensure that you call this method in the UI thread.
Parameters
contextThe context of the Android Activity.
Returns
SurfaceView.

◆ startPreview()

abstract int io.agora.rtc.RtcEngine.startPreview ( )
abstract

Starts the local video preview before joining a channel.

Before calling this method, you must:

  • Call the setupLocalVideo method to set the local preview window and configure the attributes.
  • Call the enableVideo method to enable the video.
Note
  • By default, the local preview enables the mirror mode.
  • Once you call this method to start the local video preview, if you leave the channel by calling the leaveChannel method, the local video preview remains until you call the stopPreview method to disable it.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopPreview()

abstract int io.agora.rtc.RtcEngine.stopPreview ( )
abstract

Stops the local video preview and the video.

Returns
  • 0: Success.
  • < 0: Failure.

◆ enableLocalVideo()

abstract int io.agora.rtc.RtcEngine.enableLocalVideo ( boolean  enabled)
abstract

Disables/Re-enables the local video capture.

This method disables or re-enables the local video capturer, and does not affect receiving the remote video stream.

After you call the enableVideo method, the local video capturer is enabled by default. You can call enableLocalVideo(false) to disable the local video capturer. If you want to re-enable it, call enableLocalVideo(true).

After the local video capturer is successfully disabled or re-enabled, the SDK triggers the onUserEnableLocalVideo callback on the remote client.

Parameters
enabledSets whether to 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 you set enabled as false, this method does not require a local camera.
Note
This method affects the internal engine and can be called after calling the leaveChannel method.
Returns
  • 0: Success.
  • < 0: Failure.

◆ muteLocalVideoStream()

abstract int io.agora.rtc.RtcEngine.muteLocalVideoStream ( boolean  muted)
abstract

Stops/Resumes sending the local video stream.

A successful muteLocalVideoStream method call triggers the onUserMuteVideo callback on the remote client.

Parameters
mutedSets 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 you set muted as true, this method does not disable the camera and thus does not affect the retrieval of the local video streams. This method responds faster than calling the enableLocalVideo method and set muted as false, which controls sending the local video stream.
  • If you call setChannelProfile after this method, the SDK resets whether or not to mute the local video according to the channel profile and user role. Therefore, we recommend calling this method after the setChannelProfile method.
Returns
  • 0: Success.
  • < 0: Failure.

◆ muteRemoteVideoStream()

abstract int io.agora.rtc.RtcEngine.muteRemoteVideoStream ( int  uid,
boolean  muted 
)
abstract

Stops/Resumes receiving a specified remote user's video stream.

Parameters
uidUser ID of the specified remote user.
mutedSets 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 call the muteAllRemoteVideoStreams method and set set muted as true to stop receiving all remote video streams, ensure that the muteAllRemoteVideoStreams method is called and set muted as false before calling this method. The muteAllRemoteVideoStreams method sets all remote streams, while this method sets a specified remote user's stream.
Returns
  • 0: Success.
  • < 0: Failure.

◆ muteAllRemoteVideoStreams()

abstract int io.agora.rtc.RtcEngine.muteAllRemoteVideoStreams ( boolean  muted)
abstract

Stops/Resumes receiving all remote video streams.

Parameters
mutedSets whether to receive/stop receiving all remote video streams:
  • true: Stop receiving all remote video streams.
  • false: (Default) Receive all remote video streams.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setDefaultMuteAllRemoteVideoStreams()

abstract int io.agora.rtc.RtcEngine.setDefaultMuteAllRemoteVideoStreams ( boolean  muted)
abstract

Sets whether to receive all remote video streams by default.

Parameters
mutedSets 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.

◆ setBeautyEffectOptions()

abstract int io.agora.rtc.RtcEngine.setBeautyEffectOptions ( boolean  enabled,
BeautyOptions  options 
)
abstract

Enables/Disables image enhancement and sets the options.

Since
v2.4.0.
Parameters
enabledSets whether or not to enable image enhancement:
  • enables image enhancement.
  • disables image enhancement.
optionsThe image enhancement options. See BeautyOptions.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setDefaultAudioRoutetoSpeakerphone()

abstract int io.agora.rtc.RtcEngine.setDefaultAudioRoutetoSpeakerphone ( boolean  defaultToSpeaker)
abstract

Sets the default audio playback route.

This method sets whether the received audio is routed to the earpiece or speakerphone by default before joining a channel. If a 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 a channel, call the setEnableSpeakerphone method.

The default setting for each mode:

  • Voice: Earpiece.
  • Video: Speakerphone. If a user who is in the Communication profile calls the disableVideo method or if the user calls the muteLocalVideoStream and muteAllRemoteVideoStreams methods, the default audio route switches back to the earpiece automatically.
  • Live Broadcast: Speakerphone.
  • Gaming Voice: Speakerphone.
Parameters
defaultToSpeakerSets the default audio route:
  • true: Speakerphone.
  • false: (Default) Earpiece.
Note
Call this method before calling the joinChannelmethod.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setEnableSpeakerphone()

abstract int io.agora.rtc.RtcEngine.setEnableSpeakerphone ( boolean  enabled)
abstract

Enables/Disables the audio playback route to the speakerphone.

This method sets whether the audio is routed to the speakerphone or earpiece. After calling this method, the SDK returns the onAudioRouteChanged callback to indicate the changes.

Parameters
enabledSets whether to route the audio to the speakerphone or earpiece:
  • true: Route the audio to the speakerphone.
  • false: Route the audio to the earpiece. If the headset is plugged in, the audio is routed to the headset.
Note
  • Ensure that you have successfully called the joinChannel method before calling this method.
  • This method is invalid for audience users in the Live Broadcast profile.
Returns
  • 0: Success.
  • < 0: Failure.

◆ isSpeakerphoneEnabled()

abstract boolean io.agora.rtc.RtcEngine.isSpeakerphoneEnabled ( )
abstract

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.

◆ enableInEarMonitoring()

abstract int io.agora.rtc.RtcEngine.enableInEarMonitoring ( boolean  enabled)
abstract

Enables in-ear monitoring.

Parameters
enabledSets whether to enable/disable in-ear monitoring:
  • true: Enable.
  • false: (Default) Disable.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setInEarMonitoringVolume()

abstract int io.agora.rtc.RtcEngine.setInEarMonitoringVolume ( int  volume)
abstract

Sets the volume of the in-ear monitor.

Parameters
volumeSets the volume of the in-ear monitor. The value ranges between 0 and 100 (default).
Returns
  • 0: Success.
  • < 0: Failure.

◆ useExternalAudioDevice()

abstract int io.agora.rtc.RtcEngine.useExternalAudioDevice ( )
abstract

Uses an external audio device.

Deprecated:
This method is deprecated.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLocalVoicePitch()

abstract int io.agora.rtc.RtcEngine.setLocalVoicePitch ( double  pitch)
abstract

Changes the voice pitch of the local speaker.

Parameters
pitchSets 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.

◆ setLocalVoiceEqualization()

abstract int io.agora.rtc.RtcEngine.setLocalVoiceEqualization ( int  bandFrequency,
int  bandGain 
)
abstract

Sets the local voice equalization effect.

Parameters
bandFrequencySets 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.
bandGainSets the gain of each band (dB). The value ranges between -15 and 15. The default value is 0.
Returns
  • 0: Success.
  • -1: Failure.

◆ setLocalVoiceReverb()

abstract int io.agora.rtc.RtcEngine.setLocalVoiceReverb ( int  reverbKey,
int  value 
)
abstract

Sets the local voice reverberation.

Note
v2.4.0 adds the setLocalVoiceReverbPreset method, a more user-friendly method for setting the local voice reverberation. You can use this method to set the local reverberation effect, such as Popular, R&B, Rock, Hip-hop, and more.
Parameters
reverbKeySets the reverberation key. This method contains five reverberation keys. For details, see the description of each @ value.
valueSets the local voice reverberation value:
Returns
  • 0: Success.
  • -1: Failure.

◆ setLocalVoiceChanger()

abstract int io.agora.rtc.RtcEngine.setLocalVoiceChanger ( int  voiceChanger)
abstract

Sets the local voice changer option.

Since
v2.4.0.
Note
Do not use this method together with setLocalVoiceReverbPreset, or the method called earlier does not take effect.
Parameters
voiceChangerThe local voice changer option:
Returns
  • 0: Success.
  • -1: Failure.

◆ setLocalVoiceReverbPreset()

abstract int io.agora.rtc.RtcEngine.setLocalVoiceReverbPreset ( int  preset)
abstract

Sets the preset local voice reverberation effect

Since
v2.4.0.
Note
Parameters
presetThe local voice reverberation preset:
Returns
  • 0: Success.
  • -1: Failure.

◆ enableSoundPositionIndication()

abstract int io.agora.rtc.RtcEngine.enableSoundPositionIndication ( boolean  enabled)
abstract

Enables/Disables stereo panning for remote users.

Since
v2.4.0.

Ensure that you call this method before joinChannel to enable stereo panning for remote users so that the local user can track the position of a remote user by calling setRemoteVoicePosition.

Parameters
enabledSets whether or not to enable stereo panning for remote users:
  • true: enables stereo panning.
  • false: disables stereo panning.
Returns
  • 0: Success.
  • -1: Failure.

◆ setRemoteVoicePosition()

abstract int io.agora.rtc.RtcEngine.setRemoteVoicePosition ( int  uid,
double  pan,
double  gain 
)
abstract

Sets the sound position of a remote user.

Since
v2.4.0.

When the local user calls this method to set the sound position of a remote user, the sound difference between the left and right channels allows the local user to track the real-time position of the remote user, creating a real sense of space. This method applies to massively multiplayer online games, such as Battle Royale games.

Note
  • For this method to work, enable stereo panning for remote users by calling the enableSoundPositionIndication method before joining a channel.
  • This method requires hardware support. For the best sound positioning, we recommend using a stereo headset.
Parameters
uidThe ID of the remote user.
panThe sound position of the remote user. The value ranges from -1.0 to 1.0:
  • 0.0: the remote sound comes from the front.
  • -1.0: the remote sound comes from the left.
  • 1.0: the remote sound comes from the right.
gainGain of the remote user. The value ranges from 0.0 to 100.0. The default value is 100.0 (the original gain of the remote user). The smaller the value, the less the gain.
Returns
  • 0: Success.
  • -1: Failure.

◆ startAudioMixing()

abstract int io.agora.rtc.RtcEngine.startAudioMixing ( String  filePath,
boolean  loopback,
boolean  replace,
int  cycle 
)
abstract

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 SDK triggers the onAudioMixingFinished callback.

A successful startAudioMixing method call triggers the onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY) callback on the local client.

When the audio mixing file playback finishes, the SDK triggers the onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_STOPPED) callback on the local client.

Parameters
filePathSpecifies the absolute path of the local or online audio file to be mixed. Supported audio formats: mp3, mp4, m4a, aac, 3gp, mkv and wav. 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.
loopbackSets 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.
replaceSets the audio mixing content:
  • true: Only publish 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.
cycleSets 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 or later, and the API version is v16 or later.
  • Call this method when you are in the channel, otherwise it may cause issues.
  • If you want to play an online music file, ensure that the time interval between calling this method is more than 100 ms, or the AUDIO_FILE_OPEN_TOO_FREQUENT = 702 warning occurs.
  • If you want to play an online music file, Agora does not recommend using the redirected URL address. Some Android devices may fail to open a redirected URL address.
  • If the local audio mixing file does not exist, or if the SDK does not support the file format or cannot access the music file URL, the SDK returns WARN_AUDIO_MIXING_OPEN_ERROR = 701.
  • 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 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.

◆ stopAudioMixing()

abstract int io.agora.rtc.RtcEngine.stopAudioMixing ( )
abstract

Stops playing or mixing the music file.

Call this method when you are in a channel.

Returns
  • 0: Success.
  • < 0: Failure.

◆ pauseAudioMixing()

abstract int io.agora.rtc.RtcEngine.pauseAudioMixing ( )
abstract

Pauses playing and mixing the music file.

Call this method when you are in a channel.

Returns
  • 0: Success.
  • < 0: Failure.

◆ resumeAudioMixing()

abstract int io.agora.rtc.RtcEngine.resumeAudioMixing ( )
abstract

Resumes playing and mixing the music file.

Call this method when you are in a channel.

Returns
  • 0: Success.
  • < 0: Failure.

◆ adjustAudioMixingVolume()

abstract int io.agora.rtc.RtcEngine.adjustAudioMixingVolume ( int  volume)
abstract

Adjusts the volume of audio mixing.

Call this method when you are in a channel.

Note
Calling this method does not affect the volume of the audio effect file playback invoked by the playEffect method.
Parameters
volumeAudio mixing volume. The value ranges between 0 and 100 (default).
Returns
  • 0: Success.
  • < 0: Failure.

◆ adjustAudioMixingPlayoutVolume()

abstract int io.agora.rtc.RtcEngine.adjustAudioMixingPlayoutVolume ( int  volume)
abstract

Adjusts the volume of audio mixing for local playback.

Since
v2.3.2. Call this method when you are in a channel.
Parameters
volumeAudio mixing volume for local playback. The value ranges between 0 and 100 (default).
Returns
  • 0: Success.
  • < 0: Failure.

◆ adjustAudioMixingPublishVolume()

abstract int io.agora.rtc.RtcEngine.adjustAudioMixingPublishVolume ( int  volume)
abstract

Adjusts the volume of audio mixing for publishing (sending to other users).

Since
v2.3.2. Call this method when you are in a channel.
Parameters
volumeAudio mixing volume for publishing. The value ranges between 0 and 100 (default).
Returns
  • 0: Success.
  • < 0: Failure.

◆ getAudioMixingPlayoutVolume()

abstract int io.agora.rtc.RtcEngine.getAudioMixingPlayoutVolume ( )
abstract

Gets the audio mixing volume for local playback.

Since
v2.4.1.

This method helps troubleshoot audio volume related issues.

Returns
  • Returns the audio mixing volume for local playback, if the method call is successful. The value range is [0,100].
  • < 0: Failure.

◆ getAudioMixingPublishVolume()

abstract int io.agora.rtc.RtcEngine.getAudioMixingPublishVolume ( )
abstract

Gets the audio mixing volume for publishing.

Since
v2.4.1.

This method helps troubleshoot audio volume related issues.

Returns
  • Returns the audio mixing volume for publishing, if the method call is successful. The value range is [0,100].
  • < 0: Failure.

◆ getAudioMixingDuration()

abstract int io.agora.rtc.RtcEngine.getAudioMixingDuration ( )
abstract

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.

◆ getAudioMixingCurrentPosition()

abstract int io.agora.rtc.RtcEngine.getAudioMixingCurrentPosition ( )
abstract

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

Call this method when you are in a channel.

Returns
  • Returns the current playback position of the audio mixing, if the method call is successful.
  • < 0: Failure.

◆ setAudioMixingPosition()

abstract int io.agora.rtc.RtcEngine.setAudioMixingPosition ( int  pos)
abstract

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

Parameters
posThe playback starting position (ms) of the audio mixing file.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getAudioEffectManager()

abstract IAudioEffectManager io.agora.rtc.RtcEngine.getAudioEffectManager ( )
abstract

Retrieves the IAudioEffectManager object associated with the current RtcEngine instance.

Returns
IAudioEffectManager

◆ startAudioRecording() [1/2]

abstract int io.agora.rtc.RtcEngine.startAudioRecording ( String  filePath,
int  quality 
)
abstract

Starts an audio recording on the client.

Deprecated:
From v2.9.1. Use startAudioRecording2 instead.

The SDK allows recording during a call. Supported formats of the recording file are as follows:

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

This method has a fixed sample rate of 32 kHz.

Note
  • Ensure that the directory to save the recording file exists and is writable.
  • This method is usually called after calling the joinChannel method. The recording automatically stops when you call the leaveChannel method.
Parameters
filePathFull file path of the recording file. The string of the file name is in UTF-8.
qualitySets the audio recording quality:
Returns
  • 0: Success.
  • < 0: Failure.

◆ startAudioRecording() [2/2]

abstract int io.agora.rtc.RtcEngine.startAudioRecording ( String  filePath,
int  sampleRate,
int  quality 
)
abstract

Starts an audio recording on the client.

Since
v2.9.1 to replace startAudioRecording1.

The SDK allows recording during a call. After successfully calling this method, you can record the audio of all the users in the channel and get an audio recording file.

Supported formats of the recording file are as follows:

  • .wav: Large file size with high fidelity.
  • .aac: Small file size with low fidelity.
Note
  • Ensure that the directory to save the recording file exists and is writable.
  • This method is usually called after calling the joinChannel method. The recording automatically stops when you call the leaveChannel method.
  • For better recording effects, set quality as AUDIO_RECORDING_QUALITY_MEDIUM or AUDIO_RECORDING_QUALITY_HIGH when sampleRate is 44.1 kHz or 48 kHz.
Parameters
filePathAbsolute file path of the recording file. The string of the file name is in UTF-8.
sampleRateSample rate (kHz) of the recording file. Supported values are as follows:
  • 16
  • (Default) 32
  • 44.1
  • 48
qualityThe audio recording quality:
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopAudioRecording()

abstract int io.agora.rtc.RtcEngine.stopAudioRecording ( )
abstract

Stops the audio recording on the client.

Note
You can call this method before calling the leaveChannel method; else, the recording automatically stops when you call the leaveChannel method.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startEchoTest() [1/2]

abstract int io.agora.rtc.RtcEngine.startEchoTest ( )
abstract

Starts an audio call test.

Deprecated:
Since v2.4.0. We recommend using startEchoTest to start 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 the stopEchoTest method 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 hosts can call this method. If a user switches from the Communication to Live Broadcast profile, the user must call the setClientRole method to change the user role from an audience (default) to a host before calling this method.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startEchoTest() [2/2]

abstract int io.agora.rtc.RtcEngine.startEchoTest ( int  intervalInSeconds)
abstract

Starts an audio call test.

Since
v2.4.0.

In the audio call test, you record your voice. If the recording plays back within the set time interval, the audio devices and the network connection are working properly.

Note
  • Call this method before joining a channel.
  • After calling this method, call the stopEchoTest method to end the test. Otherwise, the app cannot run the next echo test, or call the joinchannel method.
  • In the Live Broadcast profile, only a host can call this method.
Parameters
intervalInSecondsThe time interval (s) between when you speak and when the recording plays back.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopEchoTest()

abstract int io.agora.rtc.RtcEngine.stopEchoTest ( )
abstract

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.

◆ enableLastmileTest()

abstract int io.agora.rtc.RtcEngine.enableLastmileTest ( )
abstract

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 the disableLastmileTest method to disable this test after receiving the onLastmileQuality callback, and before the user joins a channel or switches the user role.

Note
  • Do not use this method with the startLastmileProbeTest method.
  • 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 after joining a channel.
  • If you call this method to test the last-mile quality, the SDK consumes the bandwidth of a video stream, whose bitrate corresponds to the bitrate you set in the setVideoEncoderConfiguration method. After you join the channel, whether you have called the disableLastmileTest method or not, the SDK automatically stops consuming the bandwidth.
Returns
  • 0: Success.
  • < 0: Failure.

◆ disableLastmileTest()

abstract int io.agora.rtc.RtcEngine.disableLastmileTest ( )
abstract

Disables the network connection quality test.

Returns
  • 0: Success.
  • < 0: Failure.

◆ startLastmileProbeTest()

abstract int io.agora.rtc.RtcEngine.startLastmileProbeTest ( LastmileProbeConfig  config)
abstract

Starts the last-mile network probe test before joining a channel to get the uplink and downlink last-mile network statistics, including the bandwidth, packet loss, jitter, and round-trip time (RTT).

Since
v2.4.0.

Once this method is enabled, the SDK returns the following callbacks:

  • onLastmileQuality: the SDK triggers this callback within two seconds depending on the network conditions. This callback rates the network conditions with a score and is more closely linked to the user experience.
  • onLastmileProbeResult: the SDK triggers this callback within 30 seconds depending on the network conditions. This callback returns the real-time statistics of the network conditions and is more objective.

Call this method to check the uplink network quality before users join a channel or before an audience switches to a host.

Note
  • This method consumes extra network traffic and may affect communication quality. We do not recommend calling this method together with enableLastmileTest.
  • Do not call other methods before receiving the onLastmileQuality and onLastmileProbeResult callbacks. Otherwise, the callbacks may be interrupted by other methods.
  • In the Live Broadcast profile, a host should not call this method after joining a channel.
Parameters
configThe configurations of the last-mile network probe test. For details, see LastmileProbeConfig.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopLastmileProbeTest()

abstract int io.agora.rtc.RtcEngine.stopLastmileProbeTest ( )
abstract

Stops the last-mile network probe test.

Since
v2.4.0.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setVideoSource()

abstract int io.agora.rtc.RtcEngine.setVideoSource ( IVideoSource  source)
abstract

Customizes the video source.

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

Parameters
sourceSets the video source. See IVideoSource.

◆ setLocalVideoRenderer()

abstract int io.agora.rtc.RtcEngine.setLocalVideoRenderer ( IVideoSink  render)
abstract

Customizes the local video renderer.

Call this method to add an external local video renderer to the SDK.

Parameters
renderSets the local video renderer. See IVideoSink.

◆ setRemoteVideoRenderer()

abstract int io.agora.rtc.RtcEngine.setRemoteVideoRenderer ( int  uid,
IVideoSink  render 
)
abstract

Customizes the remote video renderer.

Call this method to add an external remote video renderer to the SDK.

Parameters
uidThe ID of the remote user.
renderSets the remote video renderer. See IVideoSink.

◆ setExternalAudioSink()

abstract int io.agora.rtc.RtcEngine.setExternalAudioSink ( boolean  enabled,
int  sampleRate,
int  channels 
)
abstract

Sets the external audio sink.

Since
v2.9.0.

This method applies to scenarios where you want to use external audio data for playback. After enabling the external audio sink, you can call the pullPlaybackAudioFrame method to pull the remote audio data, process it, and play it with the audio effects that you want.

Note
Once you enable the external audio sink, the app will not retrieve any audio data from the onPlaybackFrame callback.
Parameters
enabledSets whether to enable or disable the external audio sink:
  • true: Enables the external audio sink.
  • false: (Default) Disables the external audio sink.
sampleRateSets the sample rate (Hz) of the external audio sink. You can set this parameter as 8000, 16000, 32000, 44100, or 48000.
channelsSets the number of audio channels of the external audio sink:
  • 1: Mono.
  • 2: Stereo.
Returns
  • 0: Success.
  • < 0: Failure.

◆ pullPlaybackAudioFrame()

abstract int io.agora.rtc.RtcEngine.pullPlaybackAudioFrame ( byte []  data,
int  lengthInByte 
)
abstract

Pulls the remote audio frame.

Since
v2.9.0.

Before calling this method, call the setExternalAudioSink(enabled: true) method to enable and set the external audio sink.

After a successful method call, the app pulls the decoded and mixed audio data for playback.

Note
  • Once you call the pullPlaybackAudioFrame method successfully, the app will not retrieve any audio data from the onPlaybackFrame callback.
  • The difference between the onPlaybackFrame callback and the pullPlaybackAudioFrame method is as follows:
    • onPlaybackFrame: The SDK sends the audio data to the app once every 10 ms. Any delay in processing the audio frames may result in audio jitter.
    • pullPlaybackAudioFrame: The app pulls the remote audio data. After setting the audio data parameters, the SDK adjusts the frame buffer and avoids problems caused by jitter in the external audio playback.
Parameters
dataThe audio data that you want to pull. The data format is in byte[].
lengthInByteThe data length (byte) of the external audio data. The value of this parameter is related to the value of the sampleRate parameter that you set in the setExternalAudioSink method: lengthInByte = sampleRate / 100 × 2 × number of channels × time (ms).
Returns
  • 0: Success.
  • < 0: Failure.

◆ setExternalAudioSource()

abstract int io.agora.rtc.RtcEngine.setExternalAudioSource ( boolean  enabled,
int  sampleRate,
int  channels 
)
abstract

Sets the external audio source.

Note
Ensure that you call this method before the joinChannel method.
Parameters
enabledSets whether to enable/disable the external audio source:
  • true: Enable the external audio source.
  • false: (Default) Disable the external audio source.
sampleRateSets the sample rate (Hz) of the external audio source, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
channelsSets the number of channels of the external audio source:
  • 1: Mono.
  • 2: Stereo.
Returns
  • 0: Success.
  • < 0: Failure.

◆ pushExternalAudioFrame()

abstract int io.agora.rtc.RtcEngine.pushExternalAudioFrame ( byte []  data,
long  timestamp 
)
abstract

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

Parameters
dataExternal audio data to be pushed.
timestampTimestamp of the external audio frame. It is mandatory. You can use this parameter for the following purposes:
  • Restore the order of the captured audio frame.
  • Synchronize audio and video frames in video-related scenarios, including scenarios where external video sources are used.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setExternalVideoSource()

abstract void io.agora.rtc.RtcEngine.setExternalVideoSource ( boolean  enable,
boolean  useTexture,
boolean  pushMode 
)
abstract

Configures the external video source.

Parameters
enableSets whether or not to use the external video source:
  • true: Use the external video source.
  • false: Do not use the external video source.
useTextureSets whether or not to use texture as an input:
  • true: Use texture as an input.
  • false: (Default) Do not use texture as an input.
pushModeSets whether or not the external video source needs to call the PushExternalVideoFrame method to send the video frame to the Agora SDK:
  • true: Use the push mode.
  • false: Use the pull mode (not supported).

◆ pushExternalVideoFrame()

abstract boolean io.agora.rtc.RtcEngine.pushExternalVideoFrame ( AgoraVideoFrame  frame)
abstract

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

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

Parameters
frameVideo frame to be pushed. See AgoraVideoFrame.
Note
In the Communication profile, the SDK does not support textured video frames.
Returns
  • true: The frame is pushed successfully.
  • false: Failed to push the frame.

◆ isTextureEncodeSupported()

abstract boolean io.agora.rtc.RtcEngine.isTextureEncodeSupported ( )
abstract

Checks whether texture encoding is supported.

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

◆ registerAudioFrameObserver()

abstract int io.agora.rtc.RtcEngine.registerAudioFrameObserver ( IAudioFrameObserver  observer)
abstract

Registers the audio observer object.

Parameters
observerAudio observer object to be registered. See IAudioFrameObserver. Set the value as null to cancel registering, if necessary.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRecordingAudioFrameParameters()

abstract int io.agora.rtc.RtcEngine.setRecordingAudioFrameParameters ( int  sampleRate,
int  channel,
int  mode,
int  samplesPerCall 
)
abstract

Sets the audio recording format for the onRecordFrame callback.

Parameters
sampleRateSets the sample rate (samplesPerSec) returned in the onRecordFrame callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
channelSets the number of audio channels (channels) returned in the onRecordFrame callback:
  • 1: Mono
  • 2: Stereo
modeSets 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.
samplesPerCallSets the sample points (samples) returned in the onRecordFrame callback. samplesPerCall is usually set as 1024 for stream pushing. samplesPerCall = (int)(samplesPerSec × sampleInterval × numChannels), where sampleInterval ≥ 0.01 in seconds.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setPlaybackAudioFrameParameters()

abstract int io.agora.rtc.RtcEngine.setPlaybackAudioFrameParameters ( int  sampleRate,
int  channel,
int  mode,
int  samplesPerCall 
)
abstract

Sets the audio playback format for the onPlaybackFrame callback.

Parameters
sampleRateSets the sample rate (samplesPerSec) returned in the onPlaybackFrame callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
channelSets the number of channels (channels) returned in the onPlaybackFrame callback:
  • 1: Mono
  • 2: Stereo
modeSets 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.
samplesPerCallSets the sample points (samples) returned in the onPlaybackFrame callback. samplesPerCall is usually set as 1024 for stream pushing. samplesPerCall = (int)(samplesPerSec × sampleInterval × numChannels), where sampleInterval ≥ 0.01 in seconds.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setMixedAudioFrameParameters()

abstract int io.agora.rtc.RtcEngine.setMixedAudioFrameParameters ( int  sampleRate,
int  samplesPerCall 
)
abstract

Sets the mixed audio format for the onMixedAudioFrame callback.

Parameters
sampleRateSets the sample rate (samplesPerSec) returned in the onMixedAudioFrame callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
samplesPerCallSets the sample points (samples) returned in the onMixedAudioFrame callback. samplesPerCall is usually set as 1024 for stream pushing. samplesPerCall = (int)(samplesPerSec × sampleInterval × numChannels), where sampleInterval ≥ 0.01 in seconds.
Returns
  • 0: Success.
  • < 0: Failure.

◆ addVideoWatermark() [1/2]

abstract int io.agora.rtc.RtcEngine.addVideoWatermark ( AgoraImage  watermark)
abstract

Adds a watermark image to the local video.

Deprecated:
From v2.9.1. We recommend using the addVideoWatermark2 method instead.

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

Parameters
watermarkWatermark 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 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.

◆ addVideoWatermark() [2/2]

abstract int io.agora.rtc.RtcEngine.addVideoWatermark ( String  watermarkUrl,
WatermarkOptions  options 
)
abstract

Adds a watermark image to the local video.

Since
v2.9.1 to replace addVideoWatermark1.

This method adds a PNG watermark image to the local video stream in a live broadcast. Once the watermark image is added, all the audience in the channel (CDN audience included), and the recording device can see and capture it.

Agora supports adding only one watermark image onto the local video, and the newly watermark image replaces the previous one.

The watermark position depends on the settings in the setVideoEncoderConfiguration method:

  • If the orientation mode of the encoding video is ORIENTATION_MODE_FIXED_LANDSCAPE, or the landscape mode in ORIENTATION_MODE_ADAPTIVE, the watermark uses the landscape orientation.
  • If the orientation mode of the encoding video is ORIENTATION_MODE_FIXED_PORTRAIT, or the portrait mode in ORIENTATION_MODE_ADAPTIVE, the watermark uses the portrait orientation.
  • When setting the watermark position, the region must be less than the dimensions set in the setVideoEncoderConfiguration method. Otherwise, the watermark image will be cropped.
Note
  • Ensure that you have called the enableVideo method to enable the video module before calling this method.
  • If you only want to add a watermark image to the local video for the audience in the CDN live broadcast channel to see and capture, you can call this method or the setLiveTranscoding method.
  • This method supports adding a watermark image in the PNG file format only. Supported pixel formats of the PNG image are RGBA, RGB, Palette, Gray, and Alpha_gray.
  • If the dimensions the PNG image differ from your settings in this method, the image will be cropped or zoomed to conform to your settings.
  • If you have enabled the local video preview by calling the startPreview method, you can use the visibleInPreview member in the WatermarkOptions class to set whether or not the watermark is visible in preview.
  • If you have mirrored the local video by calling the setLocalVideoMirrorMode method, the watermark image in preview is also mirrored.
Parameters
watermarkUrlThe local file path of the watermark image to be added. This method supports adding a watermark image from either the local file path or the assets file path. If you use the assets file path, you need to start with /assets/ when filling in this parameter.
optionsThe options of the watermark image to be added. See Watermark Options.
Returns
  • 0: Success.
  • < 0: Failure.

◆ clearVideoWatermarks()

abstract int io.agora.rtc.RtcEngine.clearVideoWatermarks ( )
abstract

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

Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteUserPriority()

abstract int io.agora.rtc.RtcEngine.setRemoteUserPriority ( int  uid,
int  userPriority 
)
abstract

Sets the priority of a remote user's media stream.

Since
v2.4.0.

Use this method with the setRemoteSubscribeFallbackOption method. If the fallback function is enabled for a subscribed stream, the SDK ensures the high-priority user gets the best possible stream quality.

Note
The Agora SDK supports setting userPriority as high for one user only.
Parameters
uidThe ID of the remote user.
userPriorityThe priority of the remote user:
Returns
  • 0: Success.
  • <0: Failure.

◆ setLocalPublishFallbackOption()

abstract int io.agora.rtc.RtcEngine.setLocalPublishFallbackOption ( int  option)
abstract

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

If option is set as 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 video stream falls back to audio only or when the audio-only stream switches back to the video, the SDK triggers the onLocalPublishFallbackToAudioOnly.

Parameters
optionSets the fallback option for the locally published video stream:
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 published video stream falls back to audio only.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteSubscribeFallbackOption()

abstract int io.agora.rtc.RtcEngine.setRemoteSubscribeFallbackOption ( int  option)
abstract

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

If option is set as STREAM_FALLBACK_OPTION_AUDIO_ONLY(2), the SDK automatically switches the video from a high-stream to a low-stream, or disables 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. When the remotely subscribed video stream falls back to audio only, or the audio-only stream switches back to the video, the SDK triggers the onRemoteSubscribeFallbackToAudioOnly callback.

Parameters
optionSets the fallback option for the remotely subscribed video stream:
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableDualStreamMode()

abstract int io.agora.rtc.RtcEngine.enableDualStreamMode ( boolean  enabled)
abstract

Enables/Disables the dual video 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) video.

Parameters
enabledSets the stream mode:
  • true: Dual-stream mode.
  • false: (Default) Single-stream mode.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteVideoStreamType()

abstract int io.agora.rtc.RtcEngine.setRemoteVideoStreamType ( int  uid,
int  streamType 
)
abstract

Sets the video stream type of the remotely subscribed video 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 enables the dual-stream mode by calling the enableDualStreamMode method, the SDK receives the high-stream video by default. You can use this method to switch to the low-stream video.
  • If dual-stream mode is not enabled, the SDK receives the high-stream video by default.

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

Parameters
uidID of the remote user sending the video stream.
streamTypeSets the video-stream type:
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteDefaultVideoStreamType()

abstract int io.agora.rtc.RtcEngine.setRemoteDefaultVideoStreamType ( int  streamType)
abstract

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

Parameters
streamTypeSets the default video-stream type:
Returns
  • 0: Success.
  • < 0: Failure.

◆ setEncryptionSecret()

abstract int io.agora.rtc.RtcEngine.setEncryptionSecret ( String  secret)
abstract

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.

Note
For optimal transmission, ensure that the encrypted data size does not exceed the original data size + 16 bytes. 16 bytes is the maximum padding size for AES encryption.
Parameters
secretEncryption password.
Note
Do not use this method for CDN live streaming.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setEncryptionMode()

abstract int io.agora.rtc.RtcEngine.setEncryptionMode ( String  encryptionMode)
abstract

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
encryptionModeSets 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 the setEncryptionSecret method before calling this method.
Returns
  • 0: Success.
  • < 0: Failure.

◆ addInjectStreamUrl()

abstract int io.agora.rtc.RtcEngine.addInjectStreamUrl ( String  url,
LiveInjectStreamConfig  config 
)
abstract

Injects an online media stream to a live broadcast.

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

Note

The addInjectStreamUrl method call triggers the following callbacks:

  • The local client:
    • onStreamInjectedStatus, with the state of the injecting the online stream.
    • onUserJoined(uid: 666), if the method call is successful and the online media stream is injected into the channel.
  • The remote client:
    • onUserJoined(uid: 666), if the method call is successful and the online media stream is injected into the channel.
Parameters
urlThe 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).
configThe LiveInjectStreamConfig object which contains the configuration information for the added voice or video stream.
Returns

◆ removeInjectStreamUrl()

abstract int io.agora.rtc.RtcEngine.removeInjectStreamUrl ( String  url)
abstract

Removes the injected online media stream from a live broadcast.

This method removes the URL address (added by addInjectStreamUrl) from a live broadcast.

If this method call is successful, the SDK triggers the onUserOffline callback and returns a stream uid of 666.

Parameters
urlHTTP/HTTPS URL address of the added stream to be removed.
Returns
  • 0: Success.
  • < 0: Failure.

◆ addPublishStreamUrl()

abstract int io.agora.rtc.RtcEngine.addPublishStreamUrl ( String  url,
boolean  transcodingEnabled 
)
abstract

Publishes the local stream to the CDN.

The addPublishStreamUrl method call triggers the onRtmpStreamingStateChanged callback on the local client to report the state of adding a local stream to the CDN.

Parameters
urlThe CDN streaming URL in the RTMP format. The maximum length of this parameter is 1024 bytes. The URL address must not contain special characters, such as Chinese language characters.
transcodingEnabledSets whether transcoding is enabled/disabled. If you set this parameter as true, ensure that you call the setLiveTranscoding method before this method.
  • 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 you enable the RTMP Converter service before using this function. See Prerequisites.
  • This method applies to Live Broadcast only.
  • Ensure that the user joins a channel before calling this method.
  • This method adds only one stream HTTP/HTTPS URL address each time it is called.
Returns

◆ removePublishStreamUrl()

abstract int io.agora.rtc.RtcEngine.removePublishStreamUrl ( String  url)
abstract

Removes an RTMP stream from the CDN.

This method removes the RTMP URL address (added by addPublishStreamUrl) from a CDN live stream. The SDK returns the result of this method call in the onStreamUnpublished callback.

The removePublishStreamUrl method call triggers the onRtmpStreamingStateChanged callback on the local client to report the state of removing an RTMP stream from the CDN.

Parameters
urlThe RTMP URL address to be removed. The maximum length of this parameter is 1024 bytes.
Note
  • Ensure that you enable the RTMP Converter service before using this function. See Prerequisites.
  • This method applies to Live Broadcast only.
  • This method removes only one stream RTMP URL address each time it is called.
  • The RTMP URL address must not contain special characters, such as Chinese language characters.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLiveTranscoding()

abstract int io.agora.rtc.RtcEngine.setLiveTranscoding ( LiveTranscoding  transcoding)
abstract

Sets the video layout and audio settings for CDN live.

The SDK triggers the onTranscodingUpdated callback when you call this method to update the LiveTranscoding class. If you call this method to set the LiveTranscoding class for the first time, the SDK does not trigger the onTranscodingUpdated callback.

Note
Before calling the methods listed in this section:
  • This method applies to Live Broadcast only.
  • Ensure that you enable the RTMP Converter service before using this function. See Prerequisites.
  • Ensure that you call the setClientRole method and set the user role as the host.
  • Ensure that you call the setLiveTranscoding method before calling the addPublishStreamUrl method.
Parameters
transcodingSets the CDN live audio/video transcoding settings. See LiveTranscoding.
Returns
  • 0: Success.
  • < 0: Failure.

◆ createDataStream()

abstract int io.agora.rtc.RtcEngine.createDataStream ( boolean  reliable,
boolean  ordered 
)
abstract

Creates a data stream.

Each user can create up to five data streams during the lifecycle of the RtcEngine.

Parameters
reliableSets 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 SDK triggers the onStreamMessageError callback and returns an error code.
  • 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.
orderedSets 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.

◆ sendStreamMessage()

abstract int io.agora.rtc.RtcEngine.sendStreamMessage ( int  streamId,
byte []  message 
)
abstract

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.

A successful sendStreamMessage method call triggers the onStreamMessage callback on the remote client, from which the remote user gets the stream message.

A failed sendStreamMessage method call triggers the onStreamMessageError callback on the remote client.

Parameters
streamIdID of the sent data stream returned by the createDataStream method.
messageSent data.
Note
This method applies only to the Communication profile or to 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.

◆ setVideoQualityParameters()

abstract int io.agora.rtc.RtcEngine.setVideoQualityParameters ( boolean  preferFrameRateOverImageQuality)
abstract

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

Deprecated:
From v2.4.0. We recommend using the degradationPrefer parameter in the VideoEncoderConfiguration Class to set the video preference.
Parameters
preferFrameRateOverImageQualitySets the video quality preference:
  • true: Frame rate over image quality.
  • false: (Default) Image quality over frame rate.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLocalVideoMirrorMode()

abstract int io.agora.rtc.RtcEngine.setLocalVideoMirrorMode ( int  mode)
abstract

Sets the local video mirror mode.

Use this method before calling the startPreview method, or the mirror mode does not take effect until you call the startPreview method again.

Note
If you use the front camera, the SDK enables the mirror mode by default; if you use the rear camera, the SDK disables the mirror mode by default.
Parameters
modeSets the local video mirror mode:
Returns
  • 0: Success.
  • < 0: Failure.

◆ getRecommendedEncoderType()

static int io.agora.rtc.RtcEngine.getRecommendedEncoderType ( )
static

Gets the recommended encoder type.

Deprecated:
This method is deprecated.
Returns
The encoder type:

◆ switchCamera()

abstract int io.agora.rtc.RtcEngine.switchCamera ( )
abstract

Switches between front and rear cameras.

Returns
  • 0: Success.
  • < 0: Failure.

◆ isCameraZoomSupported()

abstract boolean io.agora.rtc.RtcEngine.isCameraZoomSupported ( )
abstract

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.

◆ isCameraTorchSupported()

abstract boolean io.agora.rtc.RtcEngine.isCameraTorchSupported ( )
abstract

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.

◆ isCameraFocusSupported()

abstract boolean io.agora.rtc.RtcEngine.isCameraFocusSupported ( )
abstract

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.

◆ isCameraExposurePositionSupported()

abstract boolean io.agora.rtc.RtcEngine.isCameraExposurePositionSupported ( )
abstract

Checks whether the camera exposure function is supported.

Since
v2.3.2.
Returns
  • true: The device supports the camera exposure function.
  • false: The device does not support the camera exposure function.

◆ isCameraAutoFocusFaceModeSupported()

abstract boolean io.agora.rtc.RtcEngine.isCameraAutoFocusFaceModeSupported ( )
abstract

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.

◆ setCameraZoomFactor()

abstract int io.agora.rtc.RtcEngine.setCameraZoomFactor ( float  factor)
abstract

Sets the camera zoom ratio.

Parameters
factorSets 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.

◆ getCameraMaxZoomFactor()

abstract float io.agora.rtc.RtcEngine.getCameraMaxZoomFactor ( )
abstract

Gets the maximum zoom ratio supported by the camera.

Returns
The maximum camera zoom factor.

◆ setCameraFocusPositionInPreview()

abstract int io.agora.rtc.RtcEngine.setCameraFocusPositionInPreview ( float  positionX,
float  positionY 
)
abstract

Sets the camera manual focus position.

A successful setCameraFocusPositionInPreview method call triggers the onCameraFocusAreaChanged callback on the local client.

Parameters
positionXThe horizontal coordinate of the touch point in the view.
positionYThe vertical coordinate of the touch point in the view.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setCameraExposurePosition()

abstract int io.agora.rtc.RtcEngine.setCameraExposurePosition ( float  positionXinView,
float  positionYinView 
)
abstract

Sets the camera exposure position.

A successful setCameraExposurePosition method call triggers the onCameraExposureAreaChanged callback on the local client.

Since
v2.3.2.
Parameters
positionXinViewThe horizontal coordinate of the touch point in the view.
positionYinViewThe vertical coordinate of the touch point in the view.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setCameraTorchOn()

abstract int io.agora.rtc.RtcEngine.setCameraTorchOn ( boolean  isOn)
abstract

Enables the camera flash function.

Parameters
isOnSets 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.

◆ setCameraAutoFocusFaceModeEnabled()

abstract int io.agora.rtc.RtcEngine.setCameraAutoFocusFaceModeEnabled ( boolean  enabled)
abstract

Enables the camera auto-face focus function.

Parameters
enabledSets 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.

◆ getCallId()

abstract String io.agora.rtc.RtcEngine.getCallId ( )
abstract

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 the rate and complain method, 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.

◆ rate()

abstract int io.agora.rtc.RtcEngine.rate ( String  callId,
int  rating,
String  description 
)
abstract

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

Parameters
callIdID of the call retrieved from the getCallId method.
ratingRating of the call. The value is between 1 (lowest score) and 5 (highest score). If you set a value out of this range, the ERR_INVALID_ARGUMENT(-2) error occurs.
description(Optional) The description of the rating. The string length must be less than 800 bytes.
Returns

◆ complain()

abstract int io.agora.rtc.RtcEngine.complain ( String  callId,
String  description 
)
abstract

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

Parameters
callIdID 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.

◆ getSdkVersion()

static String io.agora.rtc.RtcEngine.getSdkVersion ( )
static

Gets the SDK version.

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

◆ getMediaEngineVersion()

static String io.agora.rtc.RtcEngine.getMediaEngineVersion ( )
static

Gets the media engine version.

Deprecated:
This method is deprecated.
Returns
The string of the version number in the char format.

◆ setLogFile()

abstract int io.agora.rtc.RtcEngine.setLogFile ( String  filePath)
abstract

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.

Note
Ensure that you call this method immediately after calling the create method, otherwise the output log may not be complete.
Parameters
filePathFile 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.

◆ setLogFilter()

abstract int io.agora.rtc.RtcEngine.setLogFilter ( int  filter)
abstract

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
filterSets the log filter level:
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLogFileSize()

abstract int io.agora.rtc.RtcEngine.setLogFileSize ( int  fileSizeInKBytes)
abstract

Sets the log file size (KB).

Since
v2.4.0.

The Agora SDK has two log files, each with a default size of 512 KB. If you set fileSizeInKBytes as 1024 KB, the SDK outputs log files with a total maximum size of 2 MB. If the total size of the log files exceed the set value, the new output log files overwrite the old output log files.

Parameters
fileSizeInKBytesThe SDK log file size (KB).
Returns
  • 0: Success.
  • < 0: Failure.

◆ getNativeHandle()

abstract long io.agora.rtc.RtcEngine.getNativeHandle ( )
abstract

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.

◆ addHandler()

void io.agora.rtc.RtcEngine.addHandler ( IRtcEngineEventHandler  handler)

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
handlerIRtcEngineEventHandler

◆ removeHandler()

void io.agora.rtc.RtcEngine.removeHandler ( IRtcEngineEventHandler  handler)

Removes the specified IRtcEngineEventHandler object.

For callback events that you only want to listen for once, call this method to remove subsequent IRtcEngineEventHandler objects after you have received them. This interface is used to remove the specific IRtcEngineEventHandler interface class instance.

Parameters
handlerThe IRtcEngineEventHandler object.

◆ enableHighPerfWifiMode()

abstract boolean io.agora.rtc.RtcEngine.enableHighPerfWifiMode ( boolean  enable)
abstract

Enables the Wi-Fi mode.

Deprecated:
This method is deprecated.
Parameters
enableSets 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.

◆ getErrorDescription()

static String io.agora.rtc.RtcEngine.getErrorDescription ( int  error)
static

Gets the warning or error description.

Parameters
errorDetailed warning or error description in Warning Code or Error Code.
Returns
  • 0: Success.
  • < 0: Failure.

◆ monitorHeadsetEvent()

abstract void io.agora.rtc.RtcEngine.monitorHeadsetEvent ( boolean  monitor)
abstract

Monitors external headset device events.

Deprecated:
This method is deprecated.
Parameters
monitorSets whether to enable/disable monitoring external headset device events:
  • true: Enables monitoring external headset device events.
  • false: Disables monitoring external headset device events.

◆ monitorBluetoothHeadsetEvent()

abstract void io.agora.rtc.RtcEngine.monitorBluetoothHeadsetEvent ( boolean  monitor)
abstract

Monitors Bluetooth headset device events.

Deprecated:
This method is deprecated.
Parameters
monitorSets whether to enable/disable monitoring Bluetooth headset device events:
  • true: Enables monitoring Bluetooth headset device events.
  • false: Disables monitoring Bluetooth headset device events.

◆ setPreferHeadset()

abstract void io.agora.rtc.RtcEngine.setPreferHeadset ( boolean  enabled)
abstract

Sets the default audio route to the headset.

Deprecated:
This method is deprecated.
Parameters
enabledSets 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.

◆ setParameters()

abstract int io.agora.rtc.RtcEngine.setParameters ( String  parameters)
abstract

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
parametersSets the parameter as a JSON string in the specified format.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getParameter()

abstract String io.agora.rtc.RtcEngine.getParameter ( String  parameter,
String  args 
)
abstract

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

◆ registerMediaMetadataObserver()

abstract int io.agora.rtc.RtcEngine.registerMediaMetadataObserver ( IMetadataObserver  observer,
int  type 
)
abstract

Registers the metadata observer.

Since
v2.4.1.

You need to implement the IMetadataObserver class and specify the metadata type in this method. A successful call of this method triggers the getMaxMetadataSize callback.

This method enables you to add synchronized metadata in the video stream for more diversified live broadcast interactions, such as sending shopping links, digital coupons, and online quizzes.

Note
  • Call this method before the joinChannel method.
  • This method applies to the Live Broadcast profile profile.
Parameters
observerThe IMetadataObserver class.
typeThe metadata type. Currently, the SDK supports VIDEO_METADATA(0) only.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startChannelMediaRelay()

abstract int io.agora.rtc.RtcEngine.startChannelMediaRelay ( ChannelMediaRelayConfiguration  channelMediaRelayConfiguration)
abstract

Starts to relay media streams across channels.

Since
v2.9.0.

After a successful method call, the SDK triggers the onChannelMediaRelayStateChanged and onChannelMediaRelayEvent callbacks, and these callbacks return the state and events of the media stream relay.

  • If the onChannelMediaRelayStateChanged callback returns RELAY_STATE_RUNNING(2) and RELAY_OK(0), and the onChannelMediaRelayEvent callback returns RELAY_EVENT_PACKET_SENT_TO_DEST_CHANNEL(4), the SDK starts relaying media streams between the original and the destination channel.
  • If the onChannelMediaRelayStateChanged callback returns RELAY_STATE_FAILURE(3), an exception occurs during the media stream relay.
Note
  • Call this method after the joinChannel method.
  • This method takes effect only when you are a broadcaster in a Live-broadcast channel.
  • After a successful method call, if you want to call this method again, ensure that you call the stopChannelMediaRelay method to quit the current relay.
Parameters
channelMediaRelayConfigurationThe configuration of the media stream relay: ChannelMediaRelayConfiguration.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopChannelMediaRelay()

abstract int io.agora.rtc.RtcEngine.stopChannelMediaRelay ( )
abstract

Stops the media stream relay.

Since
v2.9.0.

Once the relay stops, the broadcaster quits all the destination channels. After a successful method call, the SDK triggers the onChannelMediaRelayStateChanged callback. If the callback returns REPAY_STATE_IDLE(0) and RELAY_OK(0), the broadcaster successfully stops the relay.

Note
If the method call fails, the SDK triggers the onChannelMediaRelayStateChanged callback with the RELAY_ERROR_SERVER_NO_RESPONSE(2) or RELAY_ERROR_SERVER_CONNECTION_LOST(8) state code. You can leave the channel by calling the leaveChannel method, and the media stream relay automatically stops.
Returns
  • 0: Success. < 0: Failure.

◆ updateChannelMediaRelay()

abstract int io.agora.rtc.RtcEngine.updateChannelMediaRelay ( ChannelMediaRelayConfiguration  channelMediaRelayConfiguration)
abstract

Updates the channels for media relay.

Since
v2.9.0.

After the channel media relay starts, if you want to relay the media stream to more channels, or leave the current relay channel, you can call the updateChannelMediaRelay method.

After a successful method call, the SDK triggers the onChannelMediaRelayEvent callback with the RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL(7) state code.

Note
  • Call this method after the startChannelMediaRelay method to update the destination channel.
  • This method supports adding at most four destination channels in the relay. If there are already four destination channels in the relay, remove the unnecessary ones with the removeDestChannelInfo method in ChannelMediaRelayConfiguration before calling this method.
Parameters
channelMediaRelayConfigurationThe media stream relay configuration: ChannelMediaRelayConfiguration.
Returns
  • 0: Success.
  • < 0: Failure.