Agora Java API Reference for Android
Public Member Functions | Static Public Member Functions | Static Protected Attributes | List of all members
io.agora.rtc.RtcEngine Class Referenceabstract

Public Member Functions

abstract int setChannelProfile (int profile)
 
abstract int setClientRole (int role)
 
abstract int setClientRole (int role, ClientRoleOptions options)
 
abstract int sendCustomReportMessage (String id, String category, String event, String label, int value)
 
abstract int joinChannel (String token, String channelName, String optionalInfo, int optionalUid)
 
abstract int joinChannel (String token, String channelName, String optionalInfo, int optionalUid, ChannelMediaOptions options)
 
abstract int switchChannel (String token, String channelName)
 
abstract int switchChannel (String token, String channelName, ChannelMediaOptions options)
 
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 joinChannelWithUserAccount (String token, String channelName, String userAccount, ChannelMediaOptions options)
 
abstract int setCloudProxy (int proxyType)
 
abstract int getUserInfoByUserAccount (String userAccount, UserInfo userInfo)
 
abstract int getUserInfoByUid (int uid, UserInfo userInfo)
 
abstract int enableWebSdkInteroperability (boolean enabled)
 
abstract int getConnectionState ()
 
abstract int enableRemoteSuperResolution (int uid, boolean enable)
 
abstract int enableRemoteSuperResolution (boolean enable, int mode, int uid)
 
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 enableLocalVoicePitchCallback (int interval)
 
abstract int enableAudioQualityIndication (boolean enabled)
 
abstract int enableLocalAudio (boolean enabled)
 
abstract int muteLocalAudioStream (boolean muted)
 
abstract int muteRemoteAudioStream (int uid, boolean muted)
 
abstract int adjustUserPlaybackSignalVolume (int uid, int volume)
 
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 renderMode)
 
abstract int setLocalRenderMode (int renderMode, int mirrorMode)
 
abstract int setRemoteRenderMode (int uid, int renderMode)
 
abstract int setRemoteRenderMode (int uid, int renderMode, int mirrorMode)
 
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 setLowlightEnhanceOptions (boolean enabled, LowLightEnhanceOptions options)
 
abstract int setVideoDenoiserOptions (boolean enabled, VideoDenoiserOptions options)
 
abstract int setColorEnhanceOptions (boolean enabled, ColorEnhanceOptions options)
 
abstract int enableVirtualBackground (boolean enabled, VirtualBackgroundSource backgroundSource)
 
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 setAudioEffectPreset (int preset)
 
abstract int setVoiceBeautifierPreset (int preset)
 
abstract int setVoiceConversionPreset (int preset)
 
abstract int setAudioEffectParameters (int preset, int param1, int param2)
 
abstract int setVoiceBeautifierParameters (int preset, int param1, int param2)
 
abstract int enableDeepLearningDenoise (boolean enabled)
 
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 selectAudioTrack (int audioIndex)
 
abstract int getAudioTrackCount ()
 
abstract int setAudioMixingDualMonoMode (int mode)
 
abstract int startAudioMixing (String filePath, boolean loopback, boolean replace, int cycle, int startPos)
 
abstract int setAudioMixingPlaybackSpeed (int speed)
 
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 int setAudioMixingPitch (int pitch)
 
abstract IAudioEffectManager getAudioEffectManager ()
 
abstract int getAudioFileInfo (String filePath)
 
abstract int startAudioRecording (String filePath, int quality)
 
abstract int startAudioRecording (String filePath, int sampleRate, int quality)
 
abstract int startAudioRecording (AudioRecordingConfiguration config)
 
abstract int stopAudioRecording ()
 
abstract int startEchoTest ()
 
abstract int startEchoTest (int intervalInSeconds)
 
abstract int startEchoTest (EchoTestConfiguration config)
 
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 int pushExternalAudioFrame (byte[] data, long timestamp, int sampleRate, int channels, int bytesPerSample, int sourcePos)
 
abstract int setExternalAudioSourceVolume (int sourcePos, int volume)
 
abstract void setExternalVideoSource (boolean enable, boolean useTexture, boolean pushMode)
 
abstract boolean pushExternalVideoFrame (AgoraVideoFrame frame)
 
abstract boolean isTextureEncodeSupported ()
 
abstract int registerAudioFrameObserver (IAudioFrameObserver observer)
 
abstract int registerVideoEncodedFrameObserver (IVideoEncodedFrameObserver observer)
 
abstract int registerVideoFrameObserver (IVideoFrameObserver 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 enableEncryption (boolean enabled, EncryptionConfig config)
 
abstract int addPublishStreamUrl (String url, boolean transcodingEnabled)
 
abstract int removePublishStreamUrl (String url)
 
abstract int setLiveTranscoding (LiveTranscoding transcoding)
 
abstract int startRtmpStreamWithoutTranscoding (String url)
 
abstract int startRtmpStreamWithTranscoding (String url, LiveTranscoding transcoding)
 
abstract int updateRtmpTranscoding (LiveTranscoding transcoding)
 
abstract int stopRtmpStream (String url)
 
abstract int createDataStream (boolean reliable, boolean ordered)
 
abstract int createDataStream (DataStreamConfig config)
 
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 enableFaceDetection (boolean enable)
 
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 pauseAllChannelMediaRelay ()
 
abstract int resumeAllChannelMediaRelay ()
 
abstract RtcChannel createRtcChannel (String channelId)
 
abstract int takeSnapshot (String channel, int uid, String filePath)
 
abstract int startScreenCapture (ScreenCaptureParameters screenCaptureParameters)
 
abstract int stopScreenCapture ()
 
abstract int updateScreenCaptureParameters (boolean captureVideo, boolean captureAudio, ScreenCaptureParameters.VideoCaptureParameters videoCaptureParameters)
 

Static Public Member Functions

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

Static Protected Attributes

static String externalLibPath = null
 

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() [1/2]

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

Creates an RtcEngine instance.

Unless otherwise specified, all the methods provided by the RtcEngine class are executed asynchronously. Agora recommends calling these methods in the same thread.

Note
  • You must create an RtcEngine instance before calling any other method.
  • You can create an RtcEngine instance either by calling this method or by calling create2. The difference between create2 and this method is that create2 enables you to specify the region for connection.
  • The Agora RTC Native SDK supports creating only one RtcEngine instance for an app for now.
Parameters
contextThe context of Android Activity.
appIdThe App ID issued to you by Agora. See How to get the App ID. Only users in apps with the same App ID can join the same channel and communicate with each other. Use an App ID to create only one RtcEngine instance. To change your App ID, call destroy to destroy the current RtcEngine instance, and after destroy returns 0, call create to create an RtcEngine instance with the new App ID.
handlerIRtcEngineEventHandler is an abstract class providing default implementation. The SDK uses this class to report to the app on SDK runtime events.
Returns
  • The RtcEngine instance, if the method call succeeds.
  • < 0, if the method call fails.
    • ERR_INVALID_APP_ID(101): The app ID is invalid. Check if it is in the correct format.
Exceptions
ExceptionFails to create an RtcEngine instance.

◆ create() [2/2]

static synchronized RtcEngine io.agora.rtc.RtcEngine.create ( RtcEngineConfig  config) throws Exception
static

Creates an RtcEngine instance.

Since
3.0.0.2

Unless otherwise specified, all the methods provided by the RtcEngine class are executed asynchronously. Agora recommends calling these methods in the same thread.

Note
  • You must create an RtcEngine instance before calling any other method.
  • You can create an RtcEngine instance either by calling this method or by calling create1. The difference between create1 and this method is that this method enables you to specify the region for connection.
  • The Agora RTC Native SDK supports creating only one RtcEngine instance for an app for now.
Parameters
configConfigurations for the RtcEngine instance. For details, see RtcEngineConfig.
Returns
  • The RtcEngine instance, if the method call succeeds.
  • < 0, if the method call fails.
    • ERR_INVALID_APP_ID(101): The app ID is invalid. Check if it is in the correct format.
Exceptions
ExceptionFails to create an RtcEngine instance.

◆ destroy()

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

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

Use this method for apps in which users occasionally make voice or video calls. When users do not make calls, you can free up resources for other operations. Once you call destroy to destroy the created RtcEngine instance, you cannot use any method or callback in the SDK any more. If you want to use the real-time communication functions again, you must call create to create a new RtcEngine instance.

Note
  • Because destroy is a synchronous method and the app cannot move on to another task until the execution completes, Agora suggests calling this method in a sub-thread to avoid congestion in the main thread. Besides, you cannot call destroy in any method or callback of the SDK. Otherwise, the SDK cannot release the resources occupied by the IRtcEngine instance until the callbacks return results, which may result in a deadlock.
  • If you want to create a new RtcEngine instance after destroying the current one, ensure that you wait till the destroy method completes executing.

◆ setChannelProfile()

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

Sets the channel profile of the Agora RtcEngine.

After initialization, the SDK uses the CHANNEL_PROFILE_COMMUNICATION channel profile by default. You can call setChannelProfile to set the channel profile. The Agora RtcEngine differentiates channel profiles and applies different optimization algorithms accordingly. For example, it prioritizes smoothness and low latency for a video call, and prioritizes video quality for a video live interactive streaming.

Parameters
profileThe channel profile of the Agora RtcEngine:
  • CHANNEL_PROFILE_COMMUNICATION(0): Communication. This profile applies to scenarios such as an audio call or video call, where all users can publish and subscribe to streams.
  • CHANNEL_PROFILE_LIVE_BROADCASTING(1): Live interactive steaming. In this profile, uses have roles, namely, host and audience (default). A host can both publish and subscribe to streams, while an audience can only subscribe to streams. This profile applies to scenarios such as a chat room or interactive video streaming.
  • CHANNEL_PROFILE_GAME(2): The Gaming profile. Agora does not recommend using this profile.
Returns
  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

◆ setClientRole() [1/2]

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

Sets the role of the user in interactive live streaming.

After calling setChannelProfile(CHANNEL_PROFILE_LIVE_BROADCASTING), the SDK sets the user role as audience by default. You can call setClientRole to set the user role as host.

You can call this method either before or after joining a channel. If you call this method to switch the user role after joining a channel, the SDK automatically does the following:

Note
This method applies to the LIVE_BROADCASTING profile only (when the profile parameter in setChannelProfile is set as CHANNEL_PROFILE_LIVE_BROADCASTING).
Parameters
roleThe role of a user in interactive live streaming:
  • CLIENT_ROLE_BROADCASTER(1): Host. A host can both send and receive streams. If you set this user role in the channel, the SDK automatically calls muteLocalAudioStream(false) and muteLocalVideoStream(false).
  • CLIENT_ROLE_AUDIENCE(2): Audience. An audience member can only receive streams. If you set this user role in the channel, the SDK automatically calls muteLocalAudioStream(true) and muteLocalVideoStream(true).
Returns
  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -5(ERR_REFUSED): The request is rejected. In multichannel scenarios, if you have set any of the following in one channel, the SDK returns this error code when the user switches the user role to host in another channel:
      • Call joinChannel with the options parameter and use the default settings publishLocalAudio = true or publishLocalVideo = true.
      • Call setClientRole to set the user role as host.
      • Call muteLocalAudioStream(false) or muteLocalVideoStream(false).
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

◆ setClientRole() [2/2]

abstract int io.agora.rtc.RtcEngine.setClientRole ( int  role,
ClientRoleOptions  options 
)
abstract

Sets the role of a user in a live interactive streaming.

Since
v3.2.0

After calling setChannelProfile(CHANNEL_PROFILE_LIVE_BROADCASTING), the SDK sets the user role as audience by default. You can call setClientRole to set the user role as host.

You can call this method either before or after joining a channel. If you call this method to switch the user role after joining a channel, the SDK automatically does the following:

Note
  • This method applies to the LIVE_BROADCASTING profile only (when the profile parameter in setChannelProfile is set as CHANNEL_PROFILE_LIVE_BROADCASTING).
  • The difference between this method and setClientRole1 is that this method can set the user level in addition to the user role.
    • The user role determines the permissions that the SDK grants to a user, such as permission to send local streams, receive remote streams, and push streams to a CDN address.
    • The user level determines the level of services that a user can enjoy within the permissions of the user's role. For example, an audience can choose to receive remote streams with low latency or ultra low latency. User level affects the pricing of services.

Sample code

ClientRoleOptions options = new ClientRoleOptions();
options.audienceLatencyLevel = AUDIENCE_LATENCY_LEVEL_LOW_LATENCY;
options.audienceLatencyLevel = AUDIENCE_LATENCY_LEVEL_ULTRA_LOW_LATENCY;
mRtcEngine.setClientRole(cRole, options);
io.agora.rtc.models.ClientRoleOptions
Definition: ClientRoleOptions.java:6
Parameters
roleThe role of a user in a live interactive streaming:
  • CLIENT_ROLE_BROADCASTER(1): Host. A host can both send and receive streams. If you set this user role in the channel, the SDK automatically calls muteLocalAudioStream(false) and muteLocalVideoStream(false).
  • CLIENT_ROLE_AUDIENCE(2): Audience. An audience member can only receive streams. If you set this user role in the channel, the SDK automatically calls muteLocalAudioStream(true) and muteLocalVideoStream(true).
optionsThe detailed options of a user, including user level. See ClientRoleOptions.
Returns
  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -5(ERR_REFUSED): The request is rejected. In multichannel scenarios, if you have set any of the following in one channel, the SDK returns this error code when the user switches the user role to host in another channel:
      • Call joinChannel with the options parameter and use the default settings publishLocalAudio = true or publishLocalVideo = true.
      • Call setClientRole to set the user role as host.
      • Call muteLocalAudioStream(false) or muteLocalVideoStream(false).
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

◆ sendCustomReportMessage()

abstract int io.agora.rtc.RtcEngine.sendCustomReportMessage ( String  id,
String  category,
String  event,
String  label,
int  value 
)
abstract

Agora supports reporting and analyzing customized messages.

Since
3.1.0

This function is in the beta stage with a free trial. The ability provided in its beta test version is reporting a maximum of 10 message pieces within 6 seconds, with each message piece not exceeding 256 bytes and each string not exceeding 100 bytes. To try out this function, contact support@agora.io and discuss the format of customized messages with us.

◆ joinChannel() [1/2]

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 method call of joinChannel 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 host in the LIVE_BROADCASTING profile.

When the connection between the client and Agora 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.

Once the user joins the channel (switches to another channel), the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. If you do not want to subscribe to a specified stream or all remote streams, call the mute methods accordingly.

Warning
  • 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.
  • 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.
Parameters
tokenThe token generated at your server. For details, see Authenticate Your Users with Tokens.
channelNameThe unique channel name for the AgoraRTC session in the string format. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
optionalInfoReserved for future use.
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”.
Returns
  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -3(ERR_NOT_READY): The SDK fails to be initialized. You can try re-initializing the SDK.
    • -5(ERR_REFUSED): The request is rejected. Possible reasons:
      • You have created an RtcChannel object with the same channel name.
      • You have joined and published a stream in a channel created by the RtcChannel object. When you join a channel created by the RtcEngine object, the SDK publishes the local audio and video streams to that channel by default. Because the SDK does not support publishing a local stream to more than one channel simultaneously, an error occurs in this occasion.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method.
    • -17(ERR_JOIN_CHANNEL_REJECTED): The request to join the channel is rejected. The SDK supports joining only one RtcEngine channel at a time. Therefore, the SDK returns this error code when a user who has already joined an RtcEngine channel calls the joining channel method of the RtcEngine class with a valid channel name.

◆ joinChannel() [2/2]

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

Joins a channel with the user ID, and configures whether to publish or automatically subscribe to the audio or video streams.

Since
v3.3.0.

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

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

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 host in the LIVE_BROADCASTING profile.

When the connection between the client and the Agora 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.

Warning
  • Compared with joinChannel[1/2], this method has the options parameter, which configures whether the user publish or automatically subscribes to the audio and video streams in the channel when joining the channel. By default, the user publishes the local audio and video streams and automatically subscribes to the audio and video streams of all the other users in the channel. Subscribing incurs all associated usage costs. To unsubscribe, set the options parameter or call the mute methods accordingly.
  • Ensure that the App ID used for generating the token is the same App ID used in the create method for creating an RtcEngine object.
Parameters
tokenThe token generated at your server. For details, see Authenticate Your Users with Tokens.
channelNameThe unique channel name for the AgoraRTC session in the string format. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
optionalInfoReserved for future use.
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, because 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”.The ID of each user in the channel should be unique. If you want to join the same channel from different devices, ensure that the user IDs in all devices are different.
optionsThe channel media options: ChannelMediaOptions.
Returns
  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -3(ERR_NOT_READY): The SDK fails to be initialized. You can try re-initializing the SDK.
    • -5(ERR_REFUSED): The request is rejected. Possible reasons:
      • You have created an RtcChannel object with the same channel name.
      • You have joined and published a stream in a channel created by the RtcChannel object.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method.
    • -17(ERR_JOIN_CHANNEL_REJECTED): The request to join the channel is rejected. The SDK supports joining only one RtcEngine channel at a time. Therefore, the SDK returns this error code when a user who has already joined an RtcEngine channel calls the joining channel method of the RtcEngine class with a valid channel name.

◆ switchChannel() [1/2]

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_BROADCASTING 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.

Once the user joins the channel (switches to another channel), the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. If you do not want to subscribe to a specified stream or all remote streams, call the mute methods accordingly.

Note
This method applies to the audience role in a LIVE_BROADCASTING channel only.
Parameters
tokenThe token generated at your server. For details, see Authenticate Your Users with Tokens.
channelNameUnique channel name for the AgoraRTC session in the string format. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
Returns
  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -5(ERR_REFUSED): The request is rejected, probably because the user is not an audience.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.
    • -102(ERR_INVALID_CHANNEL_NAME): The channel name is invalid.
    • -113(ERR_NOT_IN_CHANNEL): The user is not in the channel.

◆ switchChannel() [2/2]

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

Switches to a different channel, and configures whether to automatically subscribe to audio or video streams in the target channel.

Since
v3.3.0.

This method allows the audience of a LIVE_BROADCASTING 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_BROADCASTING channel only.
  • The difference between this method and switchChannel[1/2] is that the former adds the options parameter to configure whether the end user automatically subscribes to all remote audio and video streams in the target channel. By default, the user subscribes to the audio and video streams of all the other users in the target channel, thus incurring all associated usage costs. To unsubscribe, set the options parameter or call the mute methods accordingly.
Parameters
tokenThe token generated at your server. For details, see Authenticate Your Users with Tokens.
channelNameUnique channel name for the AgoraRTC session in the string format. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
optionsThe channel media options: ChannelMediaOptions.
Returns
  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -5(ERR_REFUSED): The request is rejected, probably because the user is not an audience.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.
    • -102(ERR_INVALID_CHANNEL_NAME): The channel name is invalid.
    • -113(ERR_NOT_IN_CHANNEL): The user is not in the channel.

◆ 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 method call of leaveChannel 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 host in the LIVE_BROADCASTING profile.
Note
  • If you call the destroy method immediately after calling the leaveChannel method, the leaveChannel process interrupts, and the SDK does not trigger the onLeaveChannel callback.
  • If you call the leaveChannel method during CDN live streaming, the SDK triggers the removePublishStreamUrl method.
Returns
  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

◆ 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(ERR_OK): Success.
  • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

◆ 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:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
Returns
  • 0: Success.
  • < 0: Failure.

◆ joinChannelWithUserAccount() [1/2]

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:

Once the user joins the channel (switches to another channel), the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. If you do not want to subscribe to a specified stream or all remote streams, call the mute methods accordingly.

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.
  • Before using a String user name, ensure that you read How can I use string user names for getting details about the limitations and implementation steps.
Parameters
tokenThe token generated at your server. For details, see Authenticate Your Users with Tokens.
channelNameThe channel name. The maximum length of this parameter is 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
userAccountThe user account. The maximum length of this parameter is 255 bytes. Ensure that the user account is unique and do not set it as null.
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
Returns

◆ joinChannelWithUserAccount() [2/2]

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

Joins the channel with a user account, and configures whether to publish or automatically subscribe to audio or video streams after joining the channel.

Since
v3.3.0.

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

Note
  • Compared with joinChannelWithUserAccount[1/2], this method has the options parameter, which configures whether the user publishes or automatically subscribes to the audio and video streams in the channel when joining the channel. By default, the user publishes the local audio and video streams and automatically subscribes to the audio and video streams of all the other users in the channel. Subscribing incurs all associated usage costs. To unsubscribe, set the options parameter or call the mute methods accordingly.
  • 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.
  • Before using a String user name, ensure that you read How can I use string user names for getting details about the limitations and implementation steps.
Parameters
tokenThe token generated at your server. For details, see Authenticate Your Users with Tokens.
channelNameThe channel name. The maximum length of this parameter is 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
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.
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
optionsThe channel media options: ChannelMediaOptions.
Returns

◆ setCloudProxy()

abstract int io.agora.rtc.RtcEngine.setCloudProxy ( int  proxyType)
abstract

Sets the Agora cloud proxy service.

Since
v3.3.0

When users' network access is restricted by a firewall, configure the firewall to allow specific IP addresses and ports provided by Agora; then, call this method to enable the cloud proxy and set the cloud proxy type with the proxyType parameter.

After a successfully cloud proxy connection, the SDK triggers the onConnectionStateChanged(CONNECTION_STATE_CONNECTING, CONNECTION_CHANGED_SETTING_PROXY_SERVER) callback.

As of v3.6.2, when a user calls this method and then joins a channel successfully, the SDK triggers the onProxyConnected callback to report the user ID, the proxy type connected, and the time elapsed from the user calling joinChannel until this callback is triggered.

To disable the cloud proxy that has been set, call setCloudProxy(TRANSPORT_TYPE_NONE_PROXY). To change the cloud proxy type that has been set, call setCloudProxy(TRANSPORT_TYPE_NONE_PROXY) first, and then call setCloudProxy with the desired proxyType.

Note
  • Agora recommends that you call this method before joining the channel or after leaving the channel.
  • For the SDK v3.3.x, when users use the Force UDP cloud proxy, the services for Media Push and cohosting across channels are not available; for the SDK v3.4.0 or later, when users behind a firewall use the Force UDP cloud proxy, the services for Media Push and cohosting across channels are not available.
  • When you use the Force TCP cloud proxy, note the following:
    • An error occurs when calling startAudioMixing to play online music files in the HTTP protocol.
    • The services for Media Push and cohosting across channels use the cloud proxy with the TCP protocol.
Parameters
proxyTypeThe cloud proxy type. This parameter is required, and the SDK reports an error if you do not pass in a value. The cloud proxy types include:
  • TRANSPORT_TYPE_NONE_PROXY(0): The automatic mode. In this mode, the SDK attempts a direct connection to SD-RTN™ and automatically switches to TLS 443 if the attempt fails. As of v3.6.2, the SDK has this mode enabled by default.
  • TRANSPORT_TYPE_UDP_PROXY(1): The cloud proxy for the UDP protocol, that is, the Force UDP cloud proxy mode. In this mode, the SDK always transmits data over UDP.
  • TRANSPORT_TYPE_TCP_PROXY(2): Since v3.6.2 The cloud proxy for the TCP (encryption) protocol, that is, the Force TCP cloud proxy mode. In this mode, the SDK always transmits data over TLS 443.
Returns
  • 0: Success.
  • < 0: Failure.
    • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

◆ 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_BROADCASTING profile only).

Deprecated:
v3.0.0. As of v3.0.0, the Native SDK automatically enables interoperability with the Web SDK, so you no longer need to call this method.

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_BROADCASTING. Interoperability with the Agora Web SDK is enabled by default when the channel profile is Communication.

Parameters
enabledWhether 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:

◆ enableRemoteSuperResolution() [1/2]

abstract int io.agora.rtc.RtcEngine.enableRemoteSuperResolution ( int  uid,
boolean  enable 
)
abstract

Enables/Disables the super-resolution algorithm for a remote user's video stream.

Deprecated:
This method is deprecated as of v3.7.1. Use enableRemoteSuperResolution[2/2] instead.
Since
v3.5.1

This feature effectively boosts the resolution of a remote user's video seen by the local user. If the original resolution of a remote user's video is a × b, the local user's device can render the remote video at a resolution of 2a × 2b after you enable this feature.

After calling this method, the SDK triggers the onUserSuperResolutionEnabled callback to report whether you have successfully enabled super resolution.

Note
  • Before calling this method, ensure that you have integrated the libagora_super_resolution_extension.so dynamic library into your project.
  • Because this method has certain system performance requirements, Agora recommends that you use the following devices or better:
    • VIVO: V1821A, NEX S, 1914A, 1916A, 1962A, 1824BA, X60, X60 Pro
    • OPPO: PCCM00, Find X3
    • OnePlus: A6000
    • Xiaomi: Mi 8, Mi 9, Mi 10, Mi 11, MIX3, Redmi K20 Pro
    • SAMSUNG: SM-G9600, SM-G9650, SM-N9600, SM-G9708, SM-G960U, SM-G9750, S20, S21
    • HUAWEI: SEA-AL00, ELE-AL00, VOG-AL00, YAL-AL10, HMA-AL00, EVR-AN00, nova 4, nova 5 Pro, nova 6 5G, nova 7 5G, Mate 30, Mate 30 Pro, Mate 40, Mate 40 Pro, P40 P40 Pro, HUAWEI MediaPad M6, MatePad 10.8
Parameters
uidThe user ID of the remote user.
enableDetermines whether to enable super resolution for the remote user's video:
  • true: Enable super resolution.
  • false: Do not enable super resolution.
Returns
  • 0: Success.
  • < 0: Failure.
    • -157 (ERR_MODULE_NOT_FOUND): The dynamic library for super resolution is not integrated.

◆ enableRemoteSuperResolution() [2/2]

abstract int io.agora.rtc.RtcEngine.enableRemoteSuperResolution ( boolean  enable,
int  mode,
int  uid 
)
abstract

Enables/Disables the super-resolution algorithm for a remote user's video stream. This is a beta feature.

Since
v3.7.1

This feature effectively boosts the resolution of a remote user's video seen by the local user. If the original resolution of a remote user's video is a × b, the local user's device can render the remote video at a resolution of 2a × 2b after you enable this feature.

After calling this method, the SDK triggers the onUserSuperResolutionEnabled callback to report whether you have successfully enabled super resolution.

Note
Before calling this method, ensure that you have integrated the libagora_super_resolution_extension.so dynamic libraries into your project.
Warning
The super resolution feature requires extra system resources. To balance the visual experience and system consumption, the SDK poses the following restrictions:
  • This feature can only be enabled for a single remote user.
  • The original resolution of the remote user's video cannot exceed 640 × 360 pixels.
  • The feature cannot be enabled in certain specific devices.
Parameters
enableDetermines whether to enable super resolution for the remote user's video:
  • true: Enable super resolution.
  • false: Do not enable super resolution.
modeThe mode of super resolution:
  • SR_MODE_MANUAL(0): Enables super resolution for the remote user you specify.
  • SR_MODE_AUTO(1): Enables super resolution for the remote user corresponding to the largest rendering window in the channel.
uidThe user ID of the remote user. This parameter only applies when mode is set as SR_MODE_MANUAL(0).
Returns
  • 0: Success.
  • < 0: Failure.
    • -157 (ERR_MODULE_NOT_FOUND): The dynamic library for super resolution is not integrated.

◆ 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.

Note
  • You must call this method before calling the joinChannel method.
  • In the COMMUNICATION and LIVE_BROADCASTING profiles, the bitrate may be different from your settings due to network self-adaptation.
  • In scenarios requiring high-quality audio, we recommend setting profile as MUSIC_HIGH_QUALITY (4) and scenario as GAME_STREAMING (3). For example, for music education scenarios.
Parameters
profileSets the sample rate, bitrate, encoding mode, and the number of channels. See Audio Profile.
scenarioSets the audio application scenario. See AudioScenario. Under different audio scenarios, the device uses different volume types. For details, see What is the difference between the in-call volume and the media volume?.

◆ 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
fullbandWhether to enable 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.
stereoWhether to enable stereo codec, not compatible with versions earlier than v1.7.4:
  • true: Enable stereo codec.
  • false: Disable stereo codec.
fullBitrateWhether to enable 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 volume of the signal captured by the microphone.

Parameters
volumeThe volume of the signal captured by the microphone. The value ranges between 0 and 400, including the following:
  • 0: Mute.
  • 100: (Default) Original volume.
  • 400: 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 signal volume of all remote users.

Note
  • This method adjusts the playback volume which is mixed volume of all remote users.
  • Since v2.3.2, to mute the local audio playback, call both adjustPlaybackSignalVolume and adjustAudioMixingVolume, and set volume as 0.
Parameters
volumeThe playback volume. The value ranges between 0 and 400, including the following:
  • 0: Mute.
  • 100: (Default) Original volume.
  • 400: 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 reporting of users' volume indication. This method enables the SDK to regularly report the volume information of the local user who sends a stream and remote users (up to three) whose instantaneous volumes are the highest to the app. Once you call this method and users send streams in the channel, the SDK triggers the onAudioVolumeIndication callback at the time interval set in this method.

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 disabled, 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.

◆ enableLocalVoicePitchCallback()

abstract int io.agora.rtc.RtcEngine.enableLocalVoicePitchCallback ( int  interval)
abstract

Enables reporting the voice pitch of the local user.

Since
v3.7.0

This method enables the SDK to regularly report the voice pitch of the local user. After the local audio capture is enabled, and you call this method, the SDK triggers the onLocalVoicePitchInHz callback at the time interval set in this method.

Note
You can call this method either before or after joining a channel.
Parameters
intervalSets the time interval at which the SDK triggers the onLocalVoicePitchInHz callback:
  • ≤ 0: Disables the onLocalVoicePitchInHz callback.
  • > 0: The time interval (ms) at which the SDK triggers the onLocalVoicePitchInHz callback. The value must be greater than or equal to 10. If the value is less than 10, the SDK automatically changes it to 10.
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
enabledWhether 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 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.

Once the local audio function is disabled or re-enabled, the SDK triggers the onLocalAudioStateChanged callback, which reports LOCAL_AUDIO_STREAM_STATE_STOPPED(0) or LOCAL_AUDIO_STREAM_STATE_CAPTURING(1).

Note
  • You can call this method either before or after joining a channel. Calling it before joining a channel only sets the device state, and it takes effect immediately after you join the channel.
  • 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 sampling using the enableLocalAudio method, the local user may hear a pause in the remote audio playback.
    • muteLocalAudioStream: Stops/Continues sending the local audio streams.
Parameters
enabledWhether 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.
Returns
  • 0: Success.
  • < 0: Failure.

◆ muteLocalAudioStream()

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

Stops or resumes publishing the local audio stream.

As of v3.4.5, this method only sets the publishing state of the audio stream in the channel of RtcEngine.

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

You can only publish the local stream in one channel at a time. If you create multiple channels, ensure that you only call muteLocalAudioStream(false) in one channel; otherwise, the method call fails, and the SDK returns -5 (ERR_REFUSED).

Note
  • This method does not change the usage state of the audio-capturing device.
  • Whether this method call takes effect is affected by the joinChannel[2/2] and setClientRole methods. For details, see Set the Publishing State.
Parameters
mutedSets whether to stop publishing the local audio stream.
  • true: Stop publishing the local audio stream.
  • false: Resume publishing the local audio stream.
Returns
  • 0: Success.
  • < 0: Failure.
    • -5 (ERR_REFUSED): The request is rejected.

◆ muteRemoteAudioStream()

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

Stops or resumes subscribing to the audio stream of a specified user.

Note
  • Call this method after joining a channel.
  • See recommended settings in Set the Subscribing State.
Parameters
uidThe user ID of the specified remote user.
mutedSets whether to stop subscribing to the audio stream of a specified user.
  • true: Stop subscribing to the audio stream of a specified user.
  • false: (Default) Resume subscribing to the audio stream of a specified user.
Returns
  • 0: Success.
  • < 0: Failure.

◆ adjustUserPlaybackSignalVolume()

abstract int io.agora.rtc.RtcEngine.adjustUserPlaybackSignalVolume ( int  uid,
int  volume 
)
abstract

Adjusts the playback signal volume of a specified remote user.

Since
v3.0.0.

You can all this method as many times as necessary to adjust the playback volume of different remote users, or to repeatedly adjust the playback volume of the same remote user.

Note
  • Call this method after joining a channel.
  • The playback volume here refers to the mixed volume of a specified remote user.
  • This method can only adjust the playback volume of one specified remote user at a time. To adjust the playback volume of different remote users, call the method as many times, once for each remote user.
Parameters
uidID of the remote user.
volumeThe playback volume of the specified remote user. The value ranges between 0 and 100, including the following:
  • 0: Mute.
  • 100: (Default) Original volume.
Returns
  • 0: Success.
  • < 0: Failure.

◆ muteAllRemoteAudioStreams()

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

Stops or resumes subscribing to the audio streams of all remote users.

After successfully calling this method, the local user stops or resumes subscribing to the audio streams of all remote users, including all subsequent users.

Note
  • Call this method after joining a channel.
  • As of v3.3.0, this method contains the function of setDefaultMuteAllRemoteAudioStreams. Agora recommend not calling muteAllRemoteAudioStreams and setDefaultMuteAllRemoteAudioStreams together; otherwise, the settings may not take effect. See Set the Subscribing State.
Parameters
mutedSets whether to stop subscribing to the audio streams of all remote users.
  • true: Stop subscribing to the audio streams of all remote users.
  • false: (Default) Resume subscribing to the audio streams of all remote users.
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.

Deprecated:
This method is deprecated from v3.3.0.

Stops or resumes subscribing to the audio streams of all remote users by default.

Call this method after joining a channel. After successfully calling this method, the local user stops or resumes subscribing to the audio streams of all subsequent users.

Note
If you need to resume subscribing to the audio streams of remote users in the channel after calling setDefaultMuteAllRemoteAudioStreams(true), do the following:
  • If you need to resume subscribing to the audio stream of a specified user, call muteRemoteAudioStream(false), and specify the user ID.
  • If you need to resume subscribing to the audio streams of multiple remote users, call muteRemoteAudioStream(false) multiple times.
Parameters
mutedSets whether to stop subscribing to the audio streams of all remote users by default.
  • true: Stop subscribing to the audio streams of all remote users by default.
  • false: (Default) Resume subscribing to the audio streams of all remote users 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.

You can call this method either before or after joining a channel.

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 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 × height is 1280 × 720.
heightSets the height of the video. The maximum value of width × height is 1280 × 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 streaming, 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).
  • To customize the width and height of the video image captured by the local camera, set the camera capture configuration as CAPTURER_OUTPUT_PREFERENCE_MANUAL(3).
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

Initializes the local video view.

This method initializes the video view of the local stream on the local device. It affects only the video view that the local user sees, not the published local video stream.

Call this method to bind the loca video stream to a video view and to set the rendering and mirror modes of the video view.

Note
  • Call this method in the main thread.
  • To update the rendering or mirror mode of the local video view during a call, use setLocalRenderMode.
Parameters
localSets the local video view and settings. See VideoCanvas.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setupRemoteVideo()

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

Initializes the video view of a remote user.

This method initializes the video view of a remote stream on the local device. It affects only the video view that the local user sees.

Call this method to bind the remote video stream to a video view and to set the rendering and mirror modes of the video view.

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.
  • To update the rendering or mirror mode of the remote video view during a call, use setRemoteRenderMode.
Parameters
remoteSets the remote video view and settings. See Video Canvas.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLocalRenderMode() [1/2]

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

Sets the local video display mode.

Deprecated:
v3.0.0. Use setLocalRenderMode2 instead.
Parameters
renderModeSets 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.

◆ setLocalRenderMode() [2/2]

abstract int io.agora.rtc.RtcEngine.setLocalRenderMode ( int  renderMode,
int  mirrorMode 
)
abstract

Updates the display mode of the local video view.

Since
v3.0.0.

After initializing the local video view, you can call this method to update its rendering and mirror modes. It affects only the video view that the local user sees, not the published local video stream.

Note
  • Ensure that you have called the setupLocalVideo method to initialize the local video view before calling this method.
  • During a call, you can call this method as many times as necessary to update
Parameters
renderModeSets 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.
  • RENDER_MODE_FILL(4): The fill mode. In this mode, the SDK stretches or zooms the video to fill the display window.
mirrorModeSets the local video mirror mode:
  • VIDEO_MIRROR_MODE_AUTO(0): (Default) The mirror mode determined by the SDK. If you use a front camera, the SDK enables the mirror mode by default; if you use a rear camera, the SDK disables the mirror mode by default.
  • VIDEO_MIRROR_MODE_ENABLED(1): Enable the mirror mode.
  • VIDEO_MIRROR_MODE_DISABLED(2): Disable the mirror mode.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteRenderMode() [1/2]

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

Sets the remote video display mode.

Deprecated:
v3.0.0. Use setRemoteRenderMode2 instead.

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

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

◆ setRemoteRenderMode() [2/2]

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

Updates the display mode of the video view of a remote user.

Since
v3.0.0.

After initializing the video view of a remote user, you can call this method to update its rendering and mirror modes. This method affects only the video view that the local user sees.

Note
  • Ensure that you have called the setupRemoteVideo setupRemoteVideo method to initialize the remote video view before calling this method.
  • During a call, you can call this method as many times as necessary to update the display mode of the video view of a remote user.
Parameters
uidUser ID of the remote user.
renderModeSets 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.
  • RENDER_MODE_FILL(4): The fill mode. In this mode, the SDK stretches or zooms the video to fill the display window.
mirrorModeSets the remote video mirror mode:
  • VIDEO_MIRROR_MODE_AUTO(0): (Default) The mirror mode determined by the SDK. By default, the SDK disables the mirror mode for the remote video.
  • VIDEO_MIRROR_MODE_ENABLED(1): Enable the mirror mode.
  • VIDEO_MIRROR_MODE_DISABLED(2): Disable the mirror mode.
Returns
  • 0: Success.
  • < 0: Failure.

◆ CreateRendererView()

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

Creates a RendererView.

This method 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.

To use a SurfaceView, call this method; to use a TextureView, call CreateTextureView.

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

◆ CreateTextureView()

static TextureView io.agora.rtc.RtcEngine.CreateTextureView ( Context  context)
static

Creates a TextureView.

Since
v3.1.0.

You can call this method to create a TextureView, which is suitable for scenarios that require scaling, rotation, and parallel coordinate translation of video images, such as screen sharing. The operation and layout of the view are managed by the app, and the Agora SDK renders the view provided by the app.

To use a TextureView, call this method; to use a SurfaceView, call CreateRendererView.

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

◆ 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.

After calling startPreview, if you want to stop the local video preview, call stopPreview.

Note
Call this method before you join the channel or after you leave the channel.
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.

Note
This method affects the internal engine and can be called after calling the leaveChannel method.
Parameters
enabledWhether 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.
Returns
  • 0: Success.
  • < 0: Failure.

◆ muteLocalVideoStream()

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

Stops or resumes publishing the local video stream.

As of v3.4.5, this method only sets the publishing state of the video stream in the channel of RtcEngine.

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

You can only publish the local stream in one channel at a time. If you create multiple channels, ensure that you only call muteLocalVideoStream(false) in one channel; otherwise, the method call fails, and the SDK returns -5 (ERR_REFUSED).

Note
  • This method does not change the usage state of the video-capturing device.
  • Whether this method call takes effect is affected by the joinChannel[2/2] and setClientRole methods. For details, see Set the Publishing State.
Parameters
mutedSets whether to stop publishing the local video stream.
  • true: Stop publishing the local video stream.
  • false: Resume publishing the local video stream.
Returns
  • 0: Success.
  • < 0: Failure. -5 (ERR_REFUSED): The request is rejected

◆ muteRemoteVideoStream()

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

Stops or resumes subscribing to the video stream of a specified user.

Note
  • Call this method after joining a channel.
  • See recommended settings in Set the Subscribing State.
Parameters
uidThe user ID of the specified remote user.
mutedSets whether to stop subscribing to the video stream of a specified user.
  • true: Stop subscribing to the video stream of a specified user.
  • false: (Default) Resume subscribing to the video stream of a specified user.
Returns
  • 0: Success.
  • < 0: Failure.

◆ muteAllRemoteVideoStreams()

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

Stops or resumes subscribing to the video streams of all remote users.

After successfully calling this method, the local user stops or resumes subscribing to the video streams of all remote users, including all subsequent users.

Note
  • Call this method after joining a channel.
  • As of v3.3.0, this method contains the function of setDefaultMuteAllRemoteVideoStreams. Agora recommend not calling muteAllRemoteVideoStreams and setDefaultMuteAllRemoteVideoStreams together; otherwise, the settings may not take effect. See Set the Subscribing State.
Parameters
mutedSets whether to stop subscribing to the video streams of all remote users.
  • true: Stop subscribing to the video streams of all remote users.
  • false: (Default) Resume subscribing to the video streams of all remote users.
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.

Deprecated:
This method is deprecated from v3.3.0.

Stops or resumes subscribing to the video streams of all remote users by default.

Call this method after joining a channel. After successfully calling this method, the local user stops or resumes subscribing to the video streams of all subsequent users.

Note
If you need to resume subscribing to the video streams of remote users in the channel after calling setDefaultMuteAllRemoteVideoStreams(true), do the following:
  • If you need to resume subscribing to the video stream of a specified user, call muteRemoteVideoStream(false), and specify the user ID.
  • If you need to resume subscribing to the video streams of multiple remote users, call muteRemoteVideoStream(false) multiple times.
Parameters
mutedSets whether to stop subscribing to the video streams of all remote users by default.
  • true: Stop subscribing to the video streams of all remote users by default.
  • false: (Default) Resume subscribing to the video streams of all remote users 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.
Note
  • Call this method after calling enableVideo.
  • This method applies to Android 5.0 or later.
  • Agora has updated the Agora image enhancement algorithm from v3.6.0 to enhance image enhancement effects and support sharpness adjustment. If you want to experience optimized image enhancement effects or set the sharpness, integrate the libagora_video_process_extension.so dynamic library into the project before calling this method.
Parameters
enabledWhether to enable image enhancement:
  • true: Enables image enhancement.
  • false: (Default) Disables image enhancement.
optionsThe image enhancement options. See BeautyOptions.
Returns
  • 0: Success.
  • < 0: Failure.
    • ERR_NOT_SUPPORTED(4): The system version is earlier than Android 5.0, which does not support this function.

◆ setLowlightEnhanceOptions()

abstract int io.agora.rtc.RtcEngine.setLowlightEnhanceOptions ( boolean  enabled,
LowLightEnhanceOptions  options 
)
abstract

Sets low-light enhancement.

Since
v3.6.2

The low-light enhancement feature can adaptively adjust the brightness value of the video captured in situations with low or uneven lighting, such as backlit, cloudy, or dark scenes. It restores or highlights the image details and improves the overall visual effect of the video.

You can call this method to enable the low-light enhancement feature and set the options of the low-light enhancement effect.

Note
  • Before calling this method, ensure that you have integrated the libagora_video_process_extension.so dynamic library.
  • Call this method after enableVideo.
  • The low-light enhancement feature has certain performance requirements on devices. If your device overheats after you enable low-light enhancement, Agora recommends modifying the low-light enhancement options to a less performance-consuming level or disabling low-light enhancement entirely.
Parameters
enabledSets whether to enable low-light enhancement:
  • true: Enable.
  • false: (Default) Disable.
optionsThe low-light enhancement options. See LowLightEnhanceOptions.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setVideoDenoiserOptions()

abstract int io.agora.rtc.RtcEngine.setVideoDenoiserOptions ( boolean  enabled,
VideoDenoiserOptions  options 
)
abstract

Sets video noise reduction.

Since
v3.6.2

Underlit environments and low-end video capture devices can cause video images to contain significant noise, which affects video quality. In real-time interactive scenarios, video noise also consumes bitstream resources and reduces encoding efficiency during encoding.

You can call this method to enable the video noise reduction feature and set the options of the video noise reduction effect.

Note
  • Before calling this method, ensure that you have integrated the libagora_video_process_extension.so dynamic library.
  • Call this method after enableVideo.
  • The video noise reduction feature has certain performance requirements on devices. If your device overheats after you enable video noise reduction, Agora recommends modifying the video noise reduction options to a less performance-consuming level or disabling video noise reduction entirely.
Parameters
enabledSets whether to enable video noise reduction:
  • true: Enable.
  • false: (Default) Disable.
optionsThe video noise reduction options. See VideoDenoiserOptions.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setColorEnhanceOptions()

abstract int io.agora.rtc.RtcEngine.setColorEnhanceOptions ( boolean  enabled,
ColorEnhanceOptions  options 
)
abstract

Sets color enhancement.

Since
v3.6.2

The video images captured by the camera can have color distortion. The color enhancement feature intelligently adjusts video characteristics such as saturation and contrast to enhance the video color richness and color reproduction, making the video more vivid.

You can call this method to enable the color enhancement feature and set the options of the color enhancement effect.

Note
  • Before calling this method, ensure that you have integrated the libagora_video_process_extension.so dynamic library.
  • Call this method after enableVideo.
  • The color enhancement feature has certain performance requirements on devices. If your device overheats after you enable color enhancement, Agora recommends modifying the color enhancement options to a less performance-consuming level or disabling color enhancement entirely.
Parameters
enabledSets whether to enable color enhancement:
  • true: Enable.
  • false: (Default) Disable.
optionsThe color enhancement options. See ColorEnhanceOptions.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableVirtualBackground()

abstract int io.agora.rtc.RtcEngine.enableVirtualBackground ( boolean  enabled,
VirtualBackgroundSource  backgroundSource 
)
abstract

Enables/Disables the virtual background.

Since
v3.5.0

After enabling the virtual background feature, you can replace the original background image of the local user with a custom background image. After the replacement, all users in the channel can see the custom background image. You can find out from the onVirtualBackgroundSourceEnabled callback whether the virtual background is successfully enabled or the cause of any errors.

Note
  • Before calling this method, ensure that you have integrated the libagora_segmentation_extension.so dynamic library into the project folder.
  • Call this method after enableVideo.
  • This function requires a high-performance device. Agora recommends that you use this function on devices with the following chips:
    • Snapdragon 700 series 750G and later
    • Snapdragon 800 series 835 and later
    • Dimensity 700 series 720 and later
    • Kirin 800 series 810 and later
    • Kirin 900 series 980 and later
  • Agora recommends that you use this function in scenarios that meet the following conditions:
    • A high-definition camera device is used, and the environment is uniformly lit.
    • The captured video image is uncluttered, the user's portrait is half-length and largely unobstructed, and the background is a single color that differs from the color of the user's clothing.
  • For versions earlier than v3.6.1, the virtual background feature does not support video in the Texture format or video obtained from custom video capture by the Push method.
Parameters
enabledSets whether to enable the virtual background:
  • true: Enable.
  • false: Disable.
backgroundSourceThe custom background image. See VirtualBackgroundSource. Note: To adapt the resolution of the custom background image to the resolution of the SDK capturing video, the SDK scales and crops the custom background image while ensuring that the content of the custom background image is not distorted.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setDefaultAudioRoutetoSpeakerphone()

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

Sets the default audio route.

If the default audio route of the SDK (see Set the Audio Route) cannot meet your requirements, you can call this method to switch the default audio route. After successfully switching the audio route, the SDK triggers the onAudioRouteChanged callback to indicate the changes.

Note
  • Call this method before calling joinChannel. If you need to switch the audio route after joining a channel, call setEnableSpeakerphone.
  • If the user uses an external audio playback device such as a Bluetooth or wired headset, this method does not take effect, and the SDK plays audio through the external device. When the user uses multiple external devices, the SDK plays audio through the last connected device.
Parameters
defaultToSpeakerSets the default audio route as follows:
  • true: Set to the speakerphone.
  • false: Set to the earpiece.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setEnableSpeakerphone()

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

Enables/Disables the audio route to the speakerphone.

If the default audio route of the SDK (see Set the Audio Route) or the setting in setDefaultAudioRoutetoSpeakerphone cannot meet your requirements, you can call this method to switch the current audio route. After successfully switching the audio route, the SDK triggers the onAudioRouteChanged callback to indicate the changes.

This method only sets the audio route in the current channel and does not influence the default audio route. If the user leaves the current channel and joins another channel, the default audio route is used.

Note
  • Call this method after calling joinChannel.
  • If the user uses an external audio playback device such as a Bluetooth or wired headset, this method does not take effect, and the SDK plays audio through the external device. When the user uses multiple external devices, the SDK plays audio through the last connected device.
Parameters
enabledSets whether to enable the speakerphone or earpiece:
  • true: Enable the speakerphone. The audio route is the speakerphone.
  • false: Disable the speakerphone. The audio route is the earpiece.
Returns
  • 0: Success.
  • < 0: Failure.

◆ isSpeakerphoneEnabled()

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

Checks whether the speakerphone is enabled.

Note
You can call this method either before or after joining a channel.
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.

Note
Users must use earphones (either wired or Bluetooth) to hear the in-ear effect of their own voices.
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.

Note
Users must use earphones (either wired or Bluetooth) to hear the in-ear effect of their own voices.
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, 250, 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
As of v3.2.0, the SDK provides a more convenient method setAudioEffectPreset, which directly implements the popular music, R&B music, KTV and other preset reverb effects.
Parameters
reverbKeyThe reverberation key. This method contains five reverberation keys. For details, see the description of each @ value.
valueThe 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.

Deprecated:
Deprecated from v3.2.0. Use the following methods instead:
  • setAudioEffectPreset: Audio effects.
  • setVoiceBeautifierPreset: Voice beautifier effects.
  • setVoiceConversionPreset: Voice conversion effects.

You can call this method either before or after joining a channel.

Since
v2.4.0.

This method can be used to set the local voice effect for users in a communication channel or hosts in a LIVE_BROADCASTING channel. Voice changer options include the following voice effects:

  • VOICE_CHANGER_XXX: Changes the local voice to an old man, a little boy, or the Hulk. Applies to the voice talk scenario.
  • VOICE_BEAUTY_XXX: Beautifies the local voice by making it sound more vigorous, resounding, or adding spacial resonance. Applies to the voice talk and singing scenario.
  • GENERAL_VOICE_BEAUTY_XXX: Adds gender-based beautification effect to the local voice. Applies to the voice talk scenario.
    • For a male voice: Adds magnetism to the voice.
    • For a female voice: Adds freshness or vitality to the voice.
Note
  • To achieve better voice effect quality, Agora recommends setting the profile parameter in setAudioProfile as AUDIO_PROFILE_MUSIC_HIGH_QUALITY or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO.
  • This method works best with the human voice, and Agora does not recommend using it for audio containing music and a human voice.
  • Do not use this method with setLocalVoiceReverbPreset, because the method called later overrides the one called earlier. For detailed considerations, see the advanced guide Set the Voice Effect.
Parameters
voiceChangerThe local voice changer option:
Returns
  • 0: Success.
  • < 0: Failure. Check if the enumeration is properly set.

◆ setLocalVoiceReverbPreset()

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

Sets the local voice reverberation option, including the virtual stereo.

You can call this method either before or after joining a channel.

Deprecated:
Deprecated from v3.2.0. Use setAudioEffectPreset or setVoiceBeautifierPreset instead.
Since
v2.4.0.

This method sets the local voice reverberation for users in a communication channel or hosts in a LIVE_BROADCASTING channel. After successfully calling this method, all users in the channel can hear the voice with reverberation.

Note
  • When calling this method with enumerations that begin with AUDIO_REVERB_FX, ensure that you set profile in setAudioProfile as AUDIO_PROFILE_MUSIC_HIGH_QUALITY or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO, otherwise, this methods cannot set the corresponding voice reverb.
  • When calling this method with AUDIO_VIRTUAL_STEREO, Agora recommends setting the profile parameter in setAudioProfile as AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO.
  • This method works best with the human voice, and Agora does not recommend using it for audio containing music and a human voice.
  • Do not use this method with setLocalVoiceChanger, because the method called later overrides the one called earlier. For detailed considerations, see the advanced guide Set the Voice Effect.
Parameters
presetThe local voice reverberation option. To achieve better voice effects, Agora recommends the enumeration whose name begins with AUDIO_REVERB_FX.
Returns
  • 0: Success.
  • < 0: Failure. Check if the enumeration is properly set.

◆ setAudioEffectPreset()

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

Sets an SDK preset audio effect.

Since
v3.2.0

Call this method to set an SDK preset audio effect for the local user who sends an audio stream. This audio effect does not change the gender characteristics of the original voice. After setting an audio effect, all users in the channel can hear the effect.

You can set different audio effects for different scenarios. See Set the Voice Effect.

To achieve better audio effect quality, Agora recommends calling setAudioProfile and setting the scenario parameter to AUDIO_SCENARIO_GAME_STREAMING(3) before calling this method.

Note
Parameters
presetThe options for SDK preset audio effects
Returns
  • 0: Success.
  • < 0: Failure.

◆ setVoiceBeautifierPreset()

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

Sets an SDK preset voice beautifier effect.

Since
v3.2.0

Call this method to set an SDK preset voice beautifier effect for the local user who sends an audio stream. After setting a voice beautifier effect, all users in the channel can hear the effect.

You can set different voice beautifier effects for different scenarios. See Set the Voice Effect.

To achieve better audio effect quality, Agora recommends calling setAudioProfile and setting the scenario parameter to AUDIO_SCENARIO_GAME_STREAMING(3) and the profile parameter to AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5) before calling this method.

Note
Parameters
presetThe options for SDK preset voice beautifier effects:
Returns
  • 0: Success.
  • < 0: Failure.

◆ setVoiceConversionPreset()

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

Sets an SDK preset voice conversion effect.

Since
v3.3.1

Call this method to set an SDK preset voice conversion effect for the local user who sends an audio stream. After setting a voice conversion effect, all users in the channel can hear the effect.

You can set different voice conversion effects for different scenarios. See Set the Voice Effect.

To achieve better audio effect quality, Agora recommends calling setAudioProfile and setting the scenario parameter to AUDIO_SCENARIO_GAME_STREAMING(3) and the profile parameter to AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5) before calling this method.

Note
Parameters
presetThe options for SDK preset voice conversion effects:
Returns
  • 0: Success.
  • < 0: Failure.

◆ setAudioEffectParameters()

abstract int io.agora.rtc.RtcEngine.setAudioEffectParameters ( int  preset,
int  param1,
int  param2 
)
abstract

Sets parameters for SDK preset audio effects.

Since
v3.2.0

Call this method to set the following parameters for the local user who sends an audio stream:

  • 3D voice effect: Sets the cycle period of the 3D voice effect.
  • Pitch correction effect: Sets the basic mode and tonic pitch of the pitch correction effect. Different songs have different modes and tonic pitches. Agora recommends bounding this method with interface elements to enable users to adjust the pitch correction interactively.

After setting parameters, all users in the channel can hear the relevant effect.

Note
Parameters
presetThe options for SDK preset audio effects:
  • 3D voice effect: ROOM_ACOUSTICS_3D_VOICE
    • Call setAudioProfile and set the profile parameter to AUDIO_PROFILE_MUSIC_STANDARD_STEREO(3) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5) before setting this enumerator; otherwise, the enumerator setting does not take effect.
    • If the 3D voice effect is enabled, users need to use stereo audio playback devices to hear the anticipated voice effect.
  • Pitch correction effect: PITCH_CORRECTION. To achieve better audio effect quality, Agora recommends calling setAudioProfile and setting the profile parameter to AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5) before setting this enumerator.
param1
  • If you set preset to ROOM_ACOUSTICS_3D_VOICE, the param1 sets the cycle period of the 3D voice effect. The value range is [1, 60] and the unit is a second. The default value is 10 seconds, indicating that the voice moves around you every 10 seconds.
  • If you set preset to PITCH_CORRECTION, param1 sets the basic mode of the pitch correction effect:
    • 1: (Default) Natural major scale.
    • 2: Natural minor scale.
    • 3: Japanese pentatonic scale.
param2
  • You need to set param2 to 0.
  • If you set preset to PITCH_CORRECTION, param2 sets the tonic pitch of the pitch correction effect:
    • 1: A
    • 2: A#
    • 3: B
    • 4: (Default) C
    • 5: C#
    • 6: D
    • 7: D#
    • 8: E
    • 9: F
    • 10: F#
    • 11: G
    • 12: G#
Returns
  • 0: Success.
  • < 0: Failure.

◆ setVoiceBeautifierParameters()

abstract int io.agora.rtc.RtcEngine.setVoiceBeautifierParameters ( int  preset,
int  param1,
int  param2 
)
abstract

Sets parameters for SDK preset voice beautifier effects.

Since
3.3.0.

Call this method to set a gender characteristic and a reverberation effect for the singing beautifier effect. This method sets parameters for the local user who sends an audio stream.

After you call this method successfully, all users in the channel can hear the relevant effect.

To achieve better audio effect quality, before you call this method, Agora recommends calling setAudioProfile, and setting the scenario parameter to AUDIO_SCENARIO_GAME_STREAMING(3) and the profile parameter to AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5).

Note
Parameters
presetThe options for SDK preset voice beautifier effects:
  • SINGING_BEAUTIFIER: Singing beautifier effect.
param1The gender characteristics options for the singing voice:
  • 1: A male-sounding voice.
  • 2: A female-sounding voice.
param2The reverberation effects options:
  • 1: The reverberation effect sounds like singing in a small room.
  • 2: The reverberation effect sounds like singing in a large room.
  • 3: The reverberation effect sounds like singing in a hall.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableDeepLearningDenoise()

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

Enables or disables noise suppression.

Since
v3.3.0.

The SDK enables traditional noise reduction mode by default to reduce most of the stationary background noise. If you need to reduce most of the non-stationary background noise, Agora recommends enabling noise suppression as follows:

  • 1. Ensure that the libagora_ai_denoise_extension.so library is integrated in your project.
  • 2. Call enableDeepLearningDenoise(true).

Noise suppression requires high-performance devices.

After successfully enabling noise suppression, if the SDK detects that the device performance is not sufficient, it automatically disables noise suppression and enables traditional noise reduction.

If you call enableDeepLearningDenoise(false) or the SDK automatically disables noise suppression in the channel, when you need to re-enable noise suppression, you need to call leaveChannel first, and then call enableDeepLearningDenoise(true).

Note
  • This method dynamically loads libagora_ai_denoise_extension.so, so Agora recommends calling this method before joining a channel.
  • This method works best with the human voice. Agora does not recommend using this method for audio containing music.
Parameters
enabledSets whether to enable noise suppression.
  • true: Enables noise suppression.
  • false: Disables noise suppression.
Returns
  • 0: Success.
  • < 0: Failure.
    • -157 (ERR_MODULE_NOT_FOUND): The library for enabling noise suppression is not integrated.

◆ 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
enabledWhether 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
  • Ensure that you call this method after joining a channel.
  • 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 wired 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() [1/2]

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

Starts playing and mixing the music file.

Deprecated:
Deprecated from v3.4.0. Use startAudioMixing[2/2] instead.

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.

Note
  • To use this method, ensure that the Android device is v4.2 or later, and the API version is v16 or later.
  • 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 MEDIA_ENGINE_AUDIO_ERROR_MIXING_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.
  • To avoid blocking, as of v3.4.5, this method changes from a synchronous call to an asynchronous call.
  • For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support.
  • To play an online file for which the URL address starts with http, you need to add android:usesCleartextTraffic="true" to the /app/Manifests/AndroidManifest.xml file.
Parameters
filePathThe file path, including the filename extensions. To access an online file, Agora supports using a URL address; to access a local file, Agora supports using a URI address, an absolute path, or a path that starts with /assets/. Note: You might encounter permission issues if you use an absolute path to access a local file, so Agora recommends using a URI address instead. For example: "content://com.android.providers.media.documents/document/audio%3A14441".
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
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.

◆ selectAudioTrack()

abstract int io.agora.rtc.RtcEngine.selectAudioTrack ( int  audioIndex)
abstract

Specifies the playback track of the current music file.

Since
v3.5.1

After getting the number of audio tracks of the current music file, call this method to specify any audio track to play. For example, if different tracks of a multitrack file store songs in different languages, you can call this method to set the language of the music file to play.

Note
Parameters
audioIndexThe specified playback track. The value range is [0, getAudioTrackCount()).
Returns
  • 0: Success.
  • < 0: Failure.

◆ getAudioTrackCount()

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

Gets the number of audio tracks of the current music file.

Since
v3.5.1
Note
Returns
  • > 0: The number of audio tracks of the current music file, if this method call succeeds.
  • < 0: Failure.

◆ setAudioMixingDualMonoMode()

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

Sets the channel mode of the current music file.

Since
v3.5.1

In a stereo music file, the left and right channels can store different audio data. According to your needs, you can set the channel mode to original mode, left channel mode, right channel mode, or mixed channel mode. For example, in the KTV scenario, the left channel of the music file stores the musical accompaniment, and the right channel stores the singing voice. If you only need to listen to the accompaniment, call this method to set the channel mode of the music file to left channel mode; if you need to listen to the accompaniment and the singing voice at the same time, call this method to set the channel mode to mixed channel mode.

Note
Parameters
modeThe channel mode. See AudioMixingDualMonoMode.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startAudioMixing() [2/2]

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

Starts playing and mixing the music file.

This method supports mixing or replacing local or online music file and audio collected by a microphone. After successfully playing the music file, the SDK triggers onAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING, AUDIO_MIXING_REASON_STARTED_BY_USER). After completing playing the music file, the SDK triggers onAudioMixingStateChanged(AUDIO_MIXING_STATE_STOPPED, AUDIO_MIXING_REASON_ALL_LOOPS_COMPLETED).

Note
  • To use this method, ensure that the Android device is v4.2 or later and the API version is v16 or later.
  • If you need 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 you call this method on an emulator, ensure that the music file is in the /sdcard/ directory and the format is MP3.
  • If you need to call startAudioMixing multiple times, ensure that the call interval is longer than 500 ms.
  • If the local music 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).
  • To avoid blocking, as of v3.4.5, this method changes from a synchronous call to an asynchronous call.
  • For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support.
  • To play an online file for which the URL address starts with http, you need to add android:usesCleartextTraffic="true" to the /app/Manifests/AndroidManifest.xml file.
Parameters
filePathThe file path, including the filename extensions. To access an online file, Agora supports using a URL address; to access a local file, Agora supports using a URI address, an absolute path, or a path that starts with /assets/. Note You might encounter permission issues if you use an absolute path to access a local file, so Agora recommends using a URI address instead. For example: "content://com.android.providers.media.documents/document/audio%3A14441".
loopbackWhether to only play the music file on the local client:
  • true: Only play the music file on the local client so that only the local user can hear the music.
  • false: Publish the music file to remote clients so that both the local user and remote users can hear the music.
replaceWhether to replace the audio collected by the microphone with a music file:
  • true: Replace. Users can only hear music.
  • false: Do not replace. Users can hear both music and audio collected by the microphone.
cycleThe number of times the music file plays.
  • ≥ 0: The number of playback times. For example, 0 means that the SDK does not play the music file, while 1 means that the SDK plays the music file once.
  • -1: Play the music in an indefinite loop.
startPosThe playback position (ms) of the music file.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setAudioMixingPlaybackSpeed()

abstract int io.agora.rtc.RtcEngine.setAudioMixingPlaybackSpeed ( int  speed)
abstract

Sets the playback speed of the current music file.

Since
v3.5.1
Note

Call this method after calling startAudioMixing[2/2] and receiving the onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY) callback.

Parameters
speedThe playback speed. Agora recommends that you limit this value to between 50 and 400, defined as follows:
  • 50: Half the original speed.
  • 100: The original speed.
  • 400: 4 times the original speed.
Returns
  • 0: Success.
  • < 0: Failure.

◆ 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 after calling startAudioMixing and receiving the onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY) callback.

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 after calling startAudioMixing and receiving the onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY) callback.

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 after calling startAudioMixing and receiving the onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY) callback.

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.

Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY) callback.

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.

Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY) callback.

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 which is played by startAudioMixing.

Deprecated:
This method is deprecated as of v3.5.1. Use getAudioFileInfo instead.

Call this method when you are in a channel.

Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY) callback.

Returns
  • ≥ 0: 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 after calling startAudioMixing and receiving the onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY) callback.

Note
If you need to call getAudioMixingCurrentPosition multiple times, ensure that the call interval is longer than 500 ms.
Returns
  • ≥ 0: The current playback position (ms) of the music file, if this method call succeeds. 0 represents that the current music file does not start playing.
  • < 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).

Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY) callback.

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

◆ setAudioMixingPitch()

abstract int io.agora.rtc.RtcEngine.setAudioMixingPitch ( int  pitch)
abstract

Sets the pitch of the local music file.

Since
3.0.1

When a local music file is mixed with a local human voice, call this method to set the pitch of the local music file only.

Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY) callback.

Parameters
pitchSets the pitch of the local music file by chromatic scale. The default value is 0, which means keep the original pitch. The value ranges from -12 to 12, and the pitch value between consecutive values is a chromatic value. The greater the absolute value of this parameter, the higher or lower the pitch of the local music file.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getAudioEffectManager()

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

Gets the IAudioEffectManager object associated with the current RtcEngine instance.

Returns
IAudioEffectManager

◆ getAudioFileInfo()

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

Gets the information of a specified audio file.

Since
v3.5.1

After calling this method successfully, the SDK triggers the onRequestAudioFileInfo callback to report the information of an audio file, such as audio duration. You can call this method multiple times to get the information of multiple audio files.

Note
Parameters
filePathThe file path, including the filename extensions. To access an online file, Agora supports using a URL address; to access a local file, Agora supports using a URI address, an absolute path, or a path that starts with /assets/. You might encounter permission issues if you use an absolute path to access a local file, so Agora recommends using a URI address instead. For example: content://com.android.providers.media.documents/document/audio%3A14441.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startAudioRecording() [1/3]

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

Starts an audio recording on the client.

Deprecated:
Deprecated from v2.9.1. Use startAudioRecording[3/3] 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. For example, /sdcard/emulated/0/audio/aac.
qualityThe audio recording quality:
Returns
  • 0: Success.
  • < 0: Failure.

◆ startAudioRecording() [2/3]

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

Starts an audio recording on the client.

Deprecated:
Deprecated from v2.9.1. Use startAudioRecording[3/3] instead.

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. For example, /sdcard/emulated/0/audio/aac.
sampleRateSample rate (Hz) of the recording file. Supported values are as follows:
  • 16000
  • (Default) 32000
  • 44100
  • 48000
qualityThe audio recording quality:
Returns
  • 0: Success.
  • < 0: Failure.

◆ startAudioRecording() [3/3]

abstract int io.agora.rtc.RtcEngine.startAudioRecording ( AudioRecordingConfiguration  config)
abstract

Starts an audio recording on the client.

Since
v3.4.0

The SDK allows recording audio during a call. After successfully calling this method, you can record the audio of users in the channel and get an audio recording file. Supported file formats are as follows:

  • WAV: High-fidelity files with typically larger file sizes. For example, if the sample rate is 32,000 Hz, the file size for 10-minute recording is approximately 73 MB.
  • AAC: Low-fidelity files with typically smaller file sizes. For example, if the sample rate is 32,000 Hz and the recording quality is AUDIO_RECORDING_QUALITY_MEDIUM, the file size for 10-minute recording is approximately 2 MB.

Once the user leaves the channel, the recording automatically stops.

Note
Call this method after joining a channel.
Parameters
configRecording configuration. See AudioRecordingConfiguration.
Returns

◆ stopAudioRecording()

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

Stops the audio recording on the client.

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

◆ startEchoTest() [1/3]

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_BROADCASTING profile, only hosts can call this method. If a user switches from the COMMUNICATION to LIVE_BROADCASTING 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/3]

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_BROADCASTING 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.

◆ startEchoTest() [3/3]

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

Starts an audio and video call loop test.

Since
v3.5.2

Before joining a channel, to test whether the user's local sending and receiving streams are normal, you can call this method to perform an audio and video call loop test, which tests whether the audio and video devices and the user's upstream and downstream networks are working properly.

After starting the test, the user needs to make a sound or face the camera. The audio or video is output after about two seconds. If the audio playback is normal, the audio device and the user's upstream and downstream networks are working properly; if the video playback is normal, the video device and the user's upstream and downstream networks are working properly.

Note
  • Call this method before joining a channel.
  • After calling this method, call stopEchoTest to end the test; otherwise, the user cannot perform the next audio and video call loop test and cannot join the channel.
  • In the LIVE_BROADCASTING profile, only a host can call this method.
Parameters
configThe configuration of the audio and video call loop test. See EchoTestConfiguration.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopEchoTest()

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

Stops call loop test.

After calling startEchoTest[2/3] or startEchoTest [3/3], call this method if you want to stop the call loop 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_BROADCASTING 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_BROADCASTING 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

Sets a custom video source.

During real-time communication, the Agora SDK enables the default video input device, that is, the built-in camera to capture video. If you need a custom video source, implement the IVideoSource class first, and call this method to add the custom video source to the SDK.

You can call this method either before or after joining a channel.

Parameters
sourceThe custom video source. See IVideoSource.
Returns
  • 0: Success.
  • < 0: Failure.

◆ 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.

You can call this method either before or after joining a channel.

Parameters
renderSets the local video renderer. See IVideoSink.
Returns
  • 0: Success.
  • < 0: Failure.

◆ 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.

You can call this method either before or after joining a channel. If you call it before joining a channel, you need to maintain the uid of the remote user on your app level.

Parameters
uidThe ID of the remote user.
renderSets the remote video renderer. See IVideoSink.
Returns
  • 0: Success.
  • < 0: Failure.

◆ 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.

Ensure that you call this method before joining a channel.

Note
When using the SDK with versions earlier than v3.5.0, you will not receive the onPlaybackFrame callback after using the Pull method to set the external audio sink.
Parameters
enabledWhether to enable or disable the external audio sink:
  • true: Enables the external audio sink.
  • false: (Default) Disables the external audio sink.
sampleRateThe sample rate (Hz) of the external audio sink. You can set this parameter as 16000, 32000, 44100, or 48000.
channelsThe 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
  • When using the SDK with versions earlier than v3.5.0, you will not receive the onPlaybackFrame callback after using the Pull method to set the external audio sink.
  • 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 through this callback. 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.
  • Ensure that you call this method after joining a channel.
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 audio duration, and the values of the sampleRate and channels parameters that you set in setExternalAudioSink. Agora recommends setting the audio duration no shorter than 10 ms. The formula for lengthInByte is:
lengthInByte = sampleRate/1000 × 2 × channels × audio duration (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 and startPreview methods.
Parameters
enabledWhether to enable/disable the external audio source:
  • true: Enable the external audio source.
  • false: (Default) Disable the external audio source.
sampleRateThe sample rate (Hz) of the external audio source, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
channelsThe number of channels of the external audio source:
  • 1: Mono.
  • 2: Stereo.
Returns
  • 0: Success.
  • < 0: Failure.

◆ pushExternalAudioFrame() [1/2]

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

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

Deprecated:
This method is deprecated as of v3.5.1. Use pushExternalAudioFrame [2/2] instead.
Note
Ensure that you call this method after joining a channel.
Parameters
dataThe external audio frame. The value range of the audio frame length (ms) is [10,60].
timestampTimestamp (ms) 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.

◆ pushExternalAudioFrame() [2/2]

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

Pushes the external audio frame to a specified position.

Since
v3.5.1

According to your needs, you can push the external audio frame to one of three positions: after audio capture, before audio encoding, or before local playback. You can call this method multiple times to push one audio frame to multiple positions or multiple audio frames to different positions. For example, in the KTV scenario, you can push the singing voice to after audio capture, so that the singing voice can be processed by the SDK audio module and you can obtain a high-quality audio experience; you can also push the accompaniment to before audio encoding, so that the accompaniment is not affected by the audio module of the SDK.

Note
Call this method after joining a channel.
Parameters
dataThe external audio frame.
timestampThe timestamp (ms) of the external audio frame. 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 where external video sources are used.
sampleRateThe sample rate of the external audio source, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
channelsThe number of audio channels:
  • 1: Mono
  • 2: Stereo (the data is interleaved)
bytesPerSampleThe number of bytes per audio sample, which is usually 16-bit (2-byte).
sourcePosThe push position of the external audio frame. See AudioExternalSourcePos.
Returns
  • 0: Success.
  • < 0: Failure.
    • -2 (ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -12 (ERR_TOO_OFTEN): The call frequency is too high, causing the internal buffer to overflow. Call this method again after 30-50 ms.

◆ setExternalAudioSourceVolume()

abstract int io.agora.rtc.RtcEngine.setExternalAudioSourceVolume ( int  sourcePos,
int  volume 
)
abstract

Sets the volume of the external audio frame in the specified position.

Since
v3.5.1

You can call this method multiple times to set the volume of external audio frames in different positions. The volume setting takes effect for all external audio frames that are pushed to the specified position.

Note
Call this method after joining a channel.
Parameters
sourcePosThe push position of the external audio frame. See AudioExternalSourcePos.
volumeThe volume of the external audio frame. The value range is [0,100]. The default value is 100, which represents the original value.
Returns
  • 0: Success.
  • < 0: Failure.
    • -2 (ERR_INVALID_ARGUMENT): The parameter is invalid.

◆ setExternalVideoSource()

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

Configures the external video source.

Ensure that you call this method before joining a channel.

Parameters
enableWhether to use the external video source:
  • true: Use the external video source.
  • false: Do not use the external video source.
useTextureWhether to use texture as an input:
  • true: Use texture as an input.
  • false: (Default) Do not use texture as an input.
pushModeWhether 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. Ensure that you call this method after joining a channel.

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.

Ensure that you call this method before joining a channel.

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

◆ registerVideoEncodedFrameObserver()

abstract int io.agora.rtc.RtcEngine.registerVideoEncodedFrameObserver ( IVideoEncodedFrameObserver  observer)
abstract

Registers a local encoded video frame observer.

Since
v3.4.5

After you successfully register the local encoded video frame observer, the SDK triggers the callbacks that you have implemented in the IVideoEncodedFrameObserver class each time a video frame is received.

Note
  • Ensure that you call this method before joining a channel.
  • The width and height of the video obtained through the observer may change due to poor network conditions and user-adjusted resolution.
Parameters
observerThe local encoded video frame observer. See IVideoEncodedFrameObserver. If null is passed, the observer registration is canceled.
Returns
  • 0: Success.
  • < 0: Failure.

◆ registerVideoFrameObserver()

abstract int io.agora.rtc.RtcEngine.registerVideoFrameObserver ( IVideoFrameObserver  observer)
abstract

Registers a raw video frame observer.

Since
v3.4.5

After you successfully register the raw video frame observer, the SDK triggers the callbacks that you have implemented in the IVideoFrameObserver class each time a video frame is received.

Note
  • Ensure that you call this method before joining a channel.
  • The width and height of the video obtained through the observer may change due to poor network conditions and user-adjusted resolution.
  • When you use the SDK v3.0.1 or later, note the following:
    • The SDK no longer guarantees that callback functions in IVideoFrameObserver are reported in the same thread. The SDK only guarantees the sequence of these callbacks.
    • If you are using OpenGL to perform image enhancement on the raw video data, you need to actively switch the OpenGL context in the callback function in IVideoFrameObserver to adapt to a multi-threaded scenario; otherwise, the image enhancement cannot work.
Parameters
observerThe raw video frame observer. See IVideoFrameObserver. If null is passed, the observer registration is canceled.
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 sampling format for the onRecordFrame callback.

Ensure that you call this method before joining a channel.

Note
The SDK calculates the sample interval according to the value of the sampleRate, channel, and samplesPerCall parameters you set in this method. Sample interval (s) = samplePerCall/(sampleRate × channel). Ensure that the value of sample interval ≥ 0.01. The SDK triggers the onRecordFrame callback according to the sample interval.
Parameters
sampleRateThe sample rate (samplesPerSec) returned in the onRecordFrame callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
channelThe number of audio channels (channels) returned in the onRecordFrame callback:
  • 1: Mono
  • 2: Stereo
modeThe use mode of the onRecordFrame callback:
samplesPerCallThe number of samples the onRecordFrame callback returns. In RTMP or RTMPS streaming scenarios, set it as 1024.
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.

Ensure that you call this method before joining a channel.

Parameters
sampleRateThe sample rate (samplesPerSec) returned in the onPlaybackFrame callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
channelThe number of channels (channels) returned in the onPlaybackFrame callback:
  • 1: Mono
  • 2: Stereo
modeThe use mode of the onPlaybackFrame callback:
samplesPerCallThe number of samples the onPlaybackFrame callback returns. In RTMP or RTMPS streaming scenarios, set it as 1024.
Returns
  • 0: Success.
  • < 0: Failure.
Note
The SDK calculates the sample interval according to the value of the sampleRate, channel, and samplesPerCall parameters you set in this method. Sample interval (s) = samplePerCall/(sampleRate × channel). Ensure that the value of sample interval ≥ 0.01. The SDK triggers the onPlaybackFrame callback according to the sample interval.

◆ setMixedAudioFrameParameters()

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

Sets the mixed audio format for the onMixedAudioFrame callback.

Ensure that you call this method before joining a channel.

Parameters
sampleRateThe sample rate (samplesPerSec) returned in the onMixedAudioFrame callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
samplesPerCallThe number of samples the onMixedAudioFrame callback returns. In RTMP or RTMPS streaming scenarios, set it as 1024.
Returns
  • 0: Success.
  • < 0: Failure.
Note
The SDK calculates the sample interval according to the value of the sampleRate and samplesPerCall parameters you set in this method， and channels in AudioFrame. Sample interval (s) = samplePerCall/(sampleRate × channel). Ensure that the value of sample interval ≥ 0.01. The SDK triggers the onMixedAudioFrame callback according to the sample interval.

◆ 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 sampling 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 streaming.
  • 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 streaming. Once the watermark image is added, all the audience in the channel (CDN audience included), and the sampling 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 streaming 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 enabled the mirror mode for the local video, the watermark on the local video is also mirrored. To avoid mirroring the watermark, Agora recommends that you do not use the mirror and watermark functions for the local video at the same time. You can implement the watermark function in your application layer.
Parameters
watermarkUrlThe local file path of the watermark image to be added. Agora supports using a URI address, an absolute path, or a path that starts with /assets/ to access a local file. Note You might encounter permission issues if you use an absolute path to access a local file, so Agora recommends using a URI address instead. For example: "content://com.android.providers.media.documents/document/image%3A1384".
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.

The SDK ensures the high-priority user gets the best possible stream quality.

Ensure that you call this method before joining a channel.

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.

Ensure that you call this method before joining a channel.

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

Ensure that you call this method before joining a channel.

Parameters
optionThe 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. You can call this method either before or after joining a channel.

Parameters
enabledWhether to enable dual-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 stream type of the remote video.

Under limited network conditions, if the publisher has not disabled the dual-stream mode using enableDualStreamMode(false), the receiver can choose to receive either the high-quality video stream (the high resolution, and high bitrate video stream) or the low-quality video stream (the low resolution, and low bitrate video stream).

By default, users receive the high-quality video stream. Call this method if you want to switch the remote stream type to reduce the bandwidth and resources.

The aspect ratio of the low-quality video stream is the same as the high-quality video stream. Once the resolution of the high-quality video stream is set, the system automatically sets the resolution, frame rate, and bitrate of the low-quality video stream.

The SDK reports the result of calling this method in the onApiCallExecuted callback.

You can call this method either before or after joining a channel. If you call both setRemoteVideoStreamType and setRemoteDefaultVideoStreamType, the SDK applies the settings in the setRemoteVideoStreamType method.

Parameters
uidID of the remote user sending the video stream.
streamTypeThe 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.

Note
  • This method can only be called before joining a channel. Agora does not support you to change the default subscribed video stream type after joining a channel.
  • If you call both this method and setRemoteVideoStreamType , the SDK applies the settings in the setRemoteVideoStreamType method.
Parameters
streamTypeThe 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.

Deprecated:
Deprecated as of v3.1.0. Use enableEncryption instead.

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.
  • Do not use this method for CDN live streaming.
Parameters
secretEncryption password.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setEncryptionMode()

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

Sets the built-in encryption mode.

Deprecated:
Deprecated as of v3.1.0. Use enableEncryption instead.

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.

Note
Call setEncryptionSecret before calling this method.
Parameters
encryptionModeThe 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.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableEncryption()

abstract int io.agora.rtc.RtcEngine.enableEncryption ( boolean  enabled,
EncryptionConfig  config 
)
abstract

Enables/Disables the built-in encryption.

Since
v3.1.0.

In scenarios requiring high security, Agora recommends calling enableEncryption to enable the built-in encryption before joining a channel.

After a user leaves the channel, the SDK automatically disables the built-in encryption. To re-enable the built-in encryption, call this method before the user joins the channel again.

As of v3.4.5, Agora recommends using either the AES_128_GCM2 or AES_256_GCM2 encryption mode, both of which support adding a salt and are more secure. For details, see Media Stream Encryption.

Warning
All users in the same channel must use the same encryption mode, encryption key, and salt; otherwise, users cannot communicate with each other.
Note
  • If you enable the built-in encryption, you cannot use the RTMP or RTMPS streaming function.
  • To enhance security, Agora recommends using a new key and salt every time you enable the media stream encryption.
Parameters
enabledWhether to enable the built-in encryption.
  • true: Enable the built-in encryption.
  • false: Disable the built-in encryption.
configConfigurations of built-in encryption schemas. See EncryptionConfig.
Returns
  • 0: Success.
  • < 0: Failure.
    • -2(ERR_INVALID_ARGUMENT): An invalid parameter is used. Set the parameter with a valid value.
    • -7(ERR_NOT_INITIALIZED: The SDK is not initialized. Initialize the IRtcEngine instance before calling this method.
    • -4(ERR_NOT_SUPPORTED): The encryption mode is incorrect or the SDK fails to load the external encryption library. Check the enumeration or reload the external encryption library.

◆ addPublishStreamUrl()

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

Publishes the local stream to a specified CDN streaming URL.

Deprecated:
This method is deprecated as of v3.6.0. See Release Notes for an alternative solution.

After calling this method, you can push media streams in RTMP or RTMPS protocol to the CDN. The SDK triggers the onRtmpStreamingStateChanged callback on the local client to report the state of adding a local stream to the CDN.

Note
  • Ensure that you enable the Media Push service before using this function. See Prerequisites in Media Push.
  • This method applies to LIVE_BROADCASTING only.
  • Ensure that the user joins a channel before calling this method.
  • This method adds only one CDN streaming URL each time it is called.
  • Agora supports pushing media streams in RTMPS protocol to the CDN only when you enable transcoding.
Parameters
urlThe CDN streaming URL in the RTMP or RTMPS format. The maximum length of this parameter is 1024 bytes. The URL address must not contain special characters, such as Chinese language characters.
transcodingEnabledWhether to enable transcoding. 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.
Returns

◆ removePublishStreamUrl()

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

Removes an RTMP or RTMPS stream from the CDN.

Deprecated:
This method is deprecated as of v3.6.0. See Release Notes for an alternative solution.

This method removes the CDN streaming URL (added by addPublishStreamUrl) from a CDN live stream. The SDK reports the result of this method call in the onRtmpStreamingStateChanged callback.

Note
  • Ensure that you enable the Media Push service before using this function. See Prerequisites in Media Push.
  • Ensure that the user joins a channel before calling this method.
  • This method applies to LIVE_BROADCASTING only.
  • This method removes only one stream CDN streaming URL each time it is called.
Parameters
urlThe CDN streaming URL to be removed. The maximum length of this parameter is 1024 bytes. The 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.

Deprecated:
This method is deprecated as of v3.6.0. See Release Notes for an alternative solution.

The SDK triggers the onTranscodingUpdated callback when you call this method to update the LiveTranscodingclass. 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_BROADCASTING only.
  • Ensure that you enable the Media Push service before using this function. See Prerequisites in Media Push.
  • 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.
  • Agora supports pushing media streams in RTMPS protocol to the CDN only when you enable transcoding.
Parameters
transcodingThe CDN live audio/video transcoding settings. See LiveTranscoding.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startRtmpStreamWithoutTranscoding()

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

Starts pushing media streams to a CDN without transcoding.

Since
v3.6.0

You can call this method to push a live audio-and-video stream to the specified CDN address. This method can push media streams to only one CDN address at a time, so if you need to push streams to multiple addresses, call this method multiple times.

After you call this method, the SDK triggers the onRtmpStreamingStateChanged callback on the local client to report the state of the streaming.

Note
  • Ensure that you enable the Media Push service before using this function. See Prerequisites in Media Push.
  • Call this method after joining a channel.
  • Only hosts in the LIVE_BROADCASTING profile can call this method.
  • If you want to retry pushing streams after a failed push, make sure to call stopRtmpStream first, then call this method to retry pushing streams; otherwise, the SDK returns the same error code as the last failed push.
Parameters
urlThe address of the CDN live streaming. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported.
Returns

◆ startRtmpStreamWithTranscoding()

abstract int io.agora.rtc.RtcEngine.startRtmpStreamWithTranscoding ( String  url,
LiveTranscoding  transcoding 
)
abstract

Starts pushing media streams to a CDN and sets the transcoding configuration.

Since
v3.6.0

You can call this method to push a live audio-and-video stream to the specified CDN address and set the transcoding configuration. This method can push media streams to only one CDN address at a time, so if you need to push streams to multiple addresses, call this method multiple times.

After you call this method, the SDK triggers the onRtmpStreamingStateChanged callback on the local client to report the state of the streaming.

Note
  • Ensure that you enable the Media Push service before using this function. See Prerequisites in Media Push.
  • Call this method after joining a channel.
  • Only hosts in the LIVE_BROADCASTING profile can call this method.
  • If you want to retry pushing streams after a failed push, make sure to call stopRtmpStream first, then call this method to retry pushing streams; otherwise, the SDK returns the same error code as the last failed push.
Parameters
urlThe address of the CDN live streaming. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported.
transcodingThe transcoding configuration for CDN live streaming. LiveTranscoding.
Returns

◆ updateRtmpTranscoding()

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

Updates the transcoding configuration.

Since
v3.6.0

After you start pushing media streams to CDN with transcoding, you can dynamically update the transcoding configuration according to the scenario. The SDK triggers the onTranscodingUpdated callback after the transcoding configuration is updated.

Parameters
transcodingThe transcoding configuration for CDN live streaming. LiveTranscoding.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopRtmpStream()

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

Stops pushing media streams to a CDN.

Since
v3.6.0

You can call this method to stop the live stream on the specified CDN address. This method can stop pushing media streams to only one CDN address at a time, so if you need to stop pushing streams to multiple addresses, call this method multiple times.

After you call this method, the SDK triggers the onRtmpStreamingStateChanged callback on the local client to report the state of the streaming.

Parameters
urlThe address of the CDN live streaming. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported.
Returns
  • 0: Success.
  • < 0: Failure.

◆ createDataStream() [1/2]

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

Creates a data stream.

Deprecated:
This method is deprecated from v3.3.0. Use the createDataStream[2/2] method instead.

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

Ensure that you call this method after joining a channel.

Note
Do not set reliable as true while setting ordered as false.
Parameters
reliableWhether 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.
Returns

◆ createDataStream() [2/2]

abstract int io.agora.rtc.RtcEngine.createDataStream ( DataStreamConfig  config)
abstract

Creates a data stream.

Since
v3.3.0.

Each user can create up to five data streams in a single channel.

This method does not support data reliability. If the receiver receives a data packet five seconds or more after it was sent, the SDK directly discards the data.

Parameters
configThe configurations for the data stream: DataStreamConfig.
Returns
  • Returns the stream ID if you successfully create the data stream.
  • < 0: Fails to create the data stream.

◆ 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.

Note
  • Ensure that you have created the data stream using createDateStream before calling this method.
  • This method applies only to the COMMUNICATION profile or to hosts in the LIVE_BROADCASTING profile.
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_BROADCASTING profile. If an audience in the LIVE_BROADCASTING 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_BROADCASTING 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.

Deprecated:
From v3.0.0. Use setupLocalVideo or setLocalRenderMode instead.
Note
Call this method after initializing the local video view by calling setupLocalVideo.
Parameters
modeThe 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.

Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannel.

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

◆ isCameraZoomSupported()

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

Checks whether the camera zoom function is supported.

Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannel.

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 device supports enabling the flash.

The SDK uses the front camera by default, so if you call isCameraTorchSupported directly, you can find out from the return value whether the device supports enabling the flash when using the front camera. If you want to check whether the device supports enabling the flash when using the rear camera, call switchCamera to switch the camera used by the SDK to the rear camera, and then call isCameraTorchSupported.

Note
Call this method after the camera is started.
Returns
  • true: The device supports enabling the flash.
  • false: The device does not support enabling the flash.

◆ isCameraFocusSupported()

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

Checks whether the camera manual focus function is supported.

Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannel.

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.

Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannel.

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.

Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannel.

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.

Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannel.

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.

Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannel.

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.

Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannel.

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.

Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannel.

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.

◆ enableFaceDetection()

abstract int io.agora.rtc.RtcEngine.enableFaceDetection ( boolean  enable)
abstract

Enables/Disables face detection for the local user.

Since
3.0.1

Once face detection is enabled, the SDK triggers the onFacePositionChanged callback to report the face information of the local user, which includes the following aspects:

  • The width and height of the local video.
  • The position of the human face in the local view.
  • The distance between the human face and the device screen.
Note
You can call this method either before or after joining a channel.
Parameters
enableWhether to enable the face detection function for the local user:
  • true: Enable face detection.
  • false: (Default) Disable face detection.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setCameraTorchOn()

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

Sets whether to enable the flash.

Note
Call this method after the camera is started.
Parameters
isOnDetermines whether to enable the flash:
  • true: Enable the flash.
  • false: Do not enable the flash.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setCameraAutoFocusFaceModeEnabled()

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

Sets whether to enable face autofocus.

The SDK disables face autofocus by default. To set face autofocus, call this method.

Note
Call this method after the camera is started.
Parameters
enabledDetermines whether to enable face autofocus:
  • true: Enable face autofocus.
  • false: Disable face autofocus.
Returns
  • 0: Success.
  • < 0: Failure.

◆ 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.

Ensure that you call this method after joining a channel.

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.

Ensure that you call this method after leaving a channel.

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.

Ensure that you call this method after leaving a channel.

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.

You can call this method either before or after joining a channel.

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

Sets the log files that the SDK outputs.

Deprecated:
This method is deprecated from v3.3.0. Use the mLogConfig parameter in create[2/2] to set the log file path instead.

By default, the SDK outputs five log files, agorasdk.log, agorasdk_1.log, agorasdk_2.log, agorasdk_3.log, agorasdk_4.log, each with a default size of 1024 KB. These log files are encoded in UTF-8. The SDK writes the latest logs in agorasdk.log. When agorasdk.log is full, the SDK deletes the log file with the earliest modification time among the other four, renames agorasdk.log to the name of the deleted log file, and creates a new agorasdk.log to record latest logs.

Note
Ensure that you call this method immediately after calling the create method, otherwise the output log may not be complete.
See also
setLogFileSize
setLogFilter
Parameters
filePathThe absolute path of log files. The default file path is /storage/emulated/0/Android/data/<package_name>/files/agorasdk.log. Ensure that the directory for the log files exists and is writable. You can use this parameter to rename the log files.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLogFilter()

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

Sets the output log level of the SDK.

Deprecated:
This method is deprecated from v3.3.0. Use the mLogConfig parameter in the create[2/2] method instead.

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.

See also
setLogFile
setLogFileSize
Parameters
filterThe log output level:
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLogFileSize()

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

Sets the log file size (KB).

Deprecated:
This method is deprecated from v3.3.0. Use the mLogConfig parameter in the create[2/2] method instead.
Since
v2.4.0.

By default, the SDK outputs five log files, agorasdk.log, agorasdk_1.log, agorasdk_2.log, agorasdk_3.log, agorasdk_4.log, each with a default size of 1024 KB. These log files are encoded in UTF-8. The SDK writes the latest logs in agorasdk.log. When agorasdk.log is full, the SDK deletes the log file with the earliest modification time among the other four, renames agorasdk.log to the name of the deleted log file, and creates a new agorasdk.log to record latest logs.

If you want to set the log file size, ensure that you call setLogFileSize before setLogFile, or the logs are cleared.

See also
setLogFile
setLogFilter
Parameters
fileSizeInKBytesThe size (KB) of a log file. The default value is 1024 KB. If you set fileSizeInKByte to 1024 KB, the SDK outputs at most 5 MB log files; if you set it to less than 1024 KB, the maximum size of a log file is still 1024 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
enableWhether 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
errorThe warning or error code in Warning Code or Error Code.
Returns
The detailed warning or error description.

◆ monitorHeadsetEvent()

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

Monitors external headset device events.

Deprecated:
This method is deprecated.
Parameters
monitorWhether 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
monitorWhether 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 interactions, such as sending shopping links, digital coupons, and online quizzes.

Note
Call this method before the joinChannel method.
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
  • Contact support@agora.io before implementing this function.
  • We do not support string user accounts in this API.
  • Call this method after the joinChannel method.
  • This method takes effect only when you are a host in a LIVE_BROADCASTING 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 host quits all the destination channels. After a successful method call, the SDK triggers the onChannelMediaRelayStateChanged callback. If the callback returns RELAY_STATE_IDLE(0) and RELAY_OK(0), the host 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) error 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
  • You can call this method either before or after you start screen sharing.
  • Call this method after successfully calling the startChannelMediaRelay method and receiving the onChannelMediaRelayStateChanged(RELAY_STATE_RUNNING, RELAY_OK) callback; otherwise, this method call fails.
  • 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.

◆ pauseAllChannelMediaRelay()

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

Pauses the media stream relay to all destination channels.

Since
v3.5.1

After the cross-channel media stream relay starts, you can call this method to pause relaying media streams to all destination channels; after the pause, if you want to resume the relay, call resumeAllChannelMediaRelay.

After a successful method call, the SDK triggers the onChannelMediaRelayEvent callback to report whether the media stream relay is successfully paused.

Note
Call this method after the startChannelMediaRelay method.
Returns
  • 0: Success.
  • < 0: Failure.

◆ resumeAllChannelMediaRelay()

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

Resumes the media stream relay to all destination channels.

Since
v3.5.1

After calling the pauseAllChannelMediaRelay method, you can call this method to resume relaying media streams to all destination channels.

After a successful method call, the SDK triggers the onChannelMediaRelayEvent callback to report whether the media stream relay is successfully resumed.

Note
Call this method after the pauseAllChannelMediaRelay method.
Returns
  • 0: Success.
  • < 0: Failure.

◆ createRtcChannel()

abstract RtcChannel io.agora.rtc.RtcEngine.createRtcChannel ( String  channelId)
abstract

Creates and gets an RtcChannel instance.

Since
v3.0.0.

To join more than one channel, call this method multiple times to create as many RtcChannel instances as needed, and call the joinChannel method of each created RtcChannel object.

After joining multiple channels, you can simultaneously subscribe to streams of all the channels, but publish a stream in only one channel at one time.

Parameters
channelIdThe unique channel name for the AgoraRTC session in the string format. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
Note
  • This parameter does not have a default value. You must set it.
  • Do not set it as the empty string "". Otherwise, the SDK returns ERR_REFUSED(-5).
Returns
  • An RtcChannel instance, if the method call succeeds.
  • Null, if the method call fails.
  • ERR_REFUSED(-5), if you set channelId as the empty string "".

◆ takeSnapshot()

abstract int io.agora.rtc.RtcEngine.takeSnapshot ( String  channel,
int  uid,
String  filePath 
)
abstract

Takes a snapshot of a video stream.

Since
v3.5.2

This method takes a snapshot of a video stream from the specified user, generates a JPG image, and saves it to the specified path.

The method is asynchronous, and the SDK has not taken the snapshot when the method call returns. After a successful method call, the SDK triggers the onSnapshotTaken callback to report whether the snapshot is successfully taken as well as the details of the snapshot taken.

Note
  • Call this method after joining a channel.
  • If the video of the specified user is pre-processed, for example, added with watermarks or image enhancement effects, the generated snapshot also includes the pre-processing effects.
Parameters
channelThe channel name.
uidThe user ID of the user. Set uid as 0 if you want to take a snapshot of the local user's video.
filePathThe local path (including the filename extensions) for the snapshot. For example, /storage/emulated/0/Android/data/<package name>/files/example.jpg. Ensure that the path you specify exists and is writable.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setAgoraLibPath()

static void io.agora.rtc.RtcEngine.setAgoraLibPath ( String  path)
static

Sets the storage directory of .so files.

Since
v3.6.2

By default, the SDK loads .so files from the app's nativeLibraryPath. You can call this method to specify the directory where you store .so files. After a successful method call, the SDK automatically loads .so files based on your specified directory when initializing the RtcEngine instance.

Normally, you need to package required .so files when compiling the app, but this can increase the app package size. To reduce the app package size, you can call this method to enable the app to load required .so files dynamically when the app runs. For detailed instructions, see Reduce App Size.

Note
  • Call this method before calling create to create an RtcEngine instance.
  • This method is applicable when you integrate the SDK manually but not when you integrate the SDK with Maven Central or JitPack.
Parameters
pathThe directory where you store .so files, which must be a private directory of the app and can be obtained using Context.getDir(). Ensure the specified directory exists; otherwise, the SDK reports the InvalidParameterException error.

◆ startScreenCapture()

abstract int io.agora.rtc.RtcEngine.startScreenCapture ( ScreenCaptureParameters  screenCaptureParameters)
abstract

Starts screen sharing.

Since
v3.7.0

During screen sharing, make sure the user has granted screen capture permission to the application and the Android API level is not earlier than 21; otherwise, the SDK reports error codes ERR_SCREEN_CAPTURE_PERMISSION_DENIED(16) and ERR_SCREEN_CAPTURE_SYSTEM_NOT_SUPPORTED(2). To capture system audio during screen sharing, ensure that the Android API level is not earlier than 29 as well; otherwise, the SDK reports the error code ERR_SCREEN_CAPTURE_SYSTEM_AUDIO_NOT_SUPPORTED(3).

Note
  • Call this method after joining a channel.
  • On Android 9 and later, to avoid the application being killed by the system after going to the background, Agora recommends you add the foreground service permission (android.permission.FOREGROUND_SERVICE) to the /app/Manifests/AndroidManifest.xml file.
  • The billing of the screen sharing stream is based on the values of width and height in ScreenCaptureParameters. When you do not pass in these value, Agora bills you at 1280 × 720; when you pass in these values, Agora bills you at those value. For details, see Pricing for Real-time Communication.
  • Due to performance limitations, screen sharing is not supported on Android TV.
  • Due to system limitations, if you are using Huawei phones, do not adjust the video encoding resolution of the screen sharing stream during the screen sharing, or you could experience crashes.
  • Due to system limitations, some Xiaomi devices do not support capturing system audio during screen sharing.
  • To avoid system audio capture failure when screen sharing, Agora recommends that you set the audio application scenario to GAME_STREAMING by using the setAudioProfile method before joining the channel. For example, call setAudioProfile(Constants.AUDIO_PROFILE_DEFAULT,Constants.AUDIO_SCENARIO_GAME_STREAMING).
Parameters
screenCaptureParametersThe configuration of the screen sharing. See ScreenCaptureParameters.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopScreenCapture()

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

Stops screen sharing.

Since
v3.7.0

After calling this method to stop screen sharing, call setVideoSource(new AgoraDefaultSource()) if you want to switch to the camera to capture user video or call startScreenCapture if you want to restart screen sharing.

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

◆ updateScreenCaptureParameters()

abstract int io.agora.rtc.RtcEngine.updateScreenCaptureParameters ( boolean  captureVideo,
boolean  captureAudio,
ScreenCaptureParameters.VideoCaptureParameters  videoCaptureParameters 
)
abstract

Updates the screen sharing configuration.

Since
v3.7.0
Note
Call this method after startScreenCapture.
Parameters
captureVideoDetermines whether to capture the screen during screen sharing:
  • true: (Default) Capture.
  • false: Do not capture.

Note: Due to system limitations, screen capture is only available for Android API level 21 and later (that is, Android 5 and later).

Parameters
captureAudioDetermines whether to capture system audio during screen sharing:
  • true: Capture.
  • false: (Default) Do not capture.

Note: Due to system limitations, capturing system audio is only available for Android API level 29 and later (that is, Android 10 and later).

Parameters
videoCaptureParametersThe video configuration for the shared screen stream. See VideoCaptureParameters.

Note: This parameter is only available for scenarios where captureVideo is true.

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