IRtcEngine

The interface class IRtcEngineEventHandler is used by the SDK to send callback event notifications to the app. The app obtains SDK event notifications by inheriting the methods of this interface class. All methods of the interface class have default (empty) implementations. The app can inherit only the events it cares about as needed. In the callback methods, the app should not perform time-consuming operations or call APIs that may cause blocking (such as sendStreamMessage), otherwise it may affect the operation of the SDK.

Parameters

eventHandler

The callback event to be added. See IRtcEngineEventHandler.

Return Values

After successfully calling this method, you can listen to events of the corresponding IRtcEngine object and get data through IRtcEngineEvent. You can add multiple listeners for the same event as needed.

Parameters

eventType

The name of the target event to listen to. See IRtcEngineEvent.

listener

The callback function corresponding to eventType. For example, to add onJoinChannelSuccess:

const onJoinChannelSuccess = (connection: RtcConnection, elapsed: number) => {};
engine.addListener('onJoinChannelSuccess', onJoinChannelSuccess);

Deprecated

Deprecated: This method is deprecated. Use addVideoWatermarkWithConfig instead.

Parameters

watermarkUrl

The local path of the watermark image to be added. This method supports adding watermark images from local absolute/relative paths.

options

Settings for the watermark image to be added. See WatermarkOptions.

Return Values

Since

Available since v4.6.2.

You can use this method to overlay a watermark image on the local video stream and configure the position, size, and visibility of the watermark in the preview using WatermarkConfig.

Parameters

configs

Watermark configuration. See WatermarkConfig.

Return Values

Timing

You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged(AudioMixingStatePlaying) callback.

Parameters

volume

The volume of the music file. The range is [0,100]. 100 (default) is the original volume.

Return Values

This method adjusts the playback volume of the mixed music file on the remote side.

Timing

You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged(AudioMixingStatePlaying) callback.

Parameters

volume

The volume of the music file. The range is [0,100]. 100 (default) is the original volume.

Return Values

This method adjusts the playback volume of the mixed music file on both local and remote sides.

Timing

You need to call this method after startAudioMixing.

Parameters

volume

The volume range of the music file is 0~100. 100 (default) is the original file volume.

Return Values

After calling this method to set the local playback volume of audio, if you want to readjust the volume, you can call this method again.

Parameters

trackId

Audio track ID. Set this parameter to the custom audio track ID returned by the createCustomAudioTrack method.

volume

Playback volume of the custom captured audio, ranging from [0, 100]. 0 means mute, 100 means original volume.

Return Values

After calling this method to set the playback volume of the audio on the remote end, you can call this method again to readjust the volume.

Parameters

trackId

Audio track ID. Set this parameter to the custom audio track ID returned by the createCustomAudioTrack method.

volume

Playback volume of the custom captured audio, in the range [0,100]. 0 means mute, 100 means original volume.

Return Values

This method adjusts the signal volume of all remote users after mixing for local playback. If you need to adjust the signal volume of a specific remote user for local playback, it is recommended to call adjustUserPlaybackSignalVolume.

Timing

Can be called before or after joining a channel.

Parameters

volume

Volume, range is [0,400].

• 0: Mute.
• 100: (Default) Original volume.
• 400: 4 times the original volume, with built-in overflow protection.

Return Values

If you only want to mute the audio signal, we recommend using muteRecordingSignal.

Timing

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

Parameters

volume

The volume. The value ranges from [0,400].

• 0: Mute.
• 100: (Default) Original volume.
• 400: Four times the original volume with overflow protection.

Return Values

You can call this method during a call to adjust the playback volume of a specified remote user locally. To adjust the playback volume of multiple users locally, call this method multiple times.

Timing

You must call this method after joining a channel.

Parameters

uid

Remote user ID.

volume

Volume. The range is [0,400].

• 0: Mute.
• 100: (Default) Original volume.
• 400: Four times the original volume with built-in overflow protection.

Return Values

Return Values

This method allows users to report call quality issues. It must be called after leaving the channel.

Parameters

callId

Call ID. You can obtain this by calling getCallId.

description

Description of the call. The length should be less than 800 bytes.

Return Values

Deprecated

Deprecated since v4.6.2.

Timing

Can be called before or after joining a channel.

Related Callbacks

After this method is successfully called, the SDK triggers the onRhythmPlayerStateChanged callback locally to report the state of the virtual metronome.

Parameters

config

Metronome configuration. See AgoraRhythmPlayerConfig.

Return Values

Currently, RTC SDK v4.x only supports creating one IRtcEngine object per App.

Return Values

IRtcEngine object.

Return Values

Timing

This method can be called before or after joining a channel.

Parameters

config

Data stream configuration. See DataStreamConfig.

Return Values

Before calling other APIs under the IMediaPlayer class, you must call this method to create a media player instance. If you need multiple instances, you can call this method multiple times.

Timing

This method can be called before or after joining a channel.

Parameters

delegate

The event handler of IRtcEngine. See IRtcEngineEventHandler.

Return Values

Since

Available since v4.6.2.

Parameters

bundlePath

The path to the video effect resource bundle.

type

The media source type. See MediaSourceType.

Return Values

Parameters

videoTrackId

The video track ID returned by the createCustomVideoTrack method.

Return Values

Parameters

mediaPlayer

The IMediaPlayer object.

Return Values

Since

Available since v4.6.2.

Parameters

videoEffectObject

The video effect object to destroy. See IVideoEffectObject.

Return Values

The audio module is enabled by default. You can call this method to disable it.

Timing

Can be called before or after joining a channel. Remains effective after leaving the channel.

Return Values

Call this method to disable audio spectrum monitoring after calling enableAudioSpectrumMonitor.

Return Values

This method disables the video module.

Timing

Related Callbacks

After successfully calling this method, the remote side receives the onUserEnableVideo (false) callback.

Return Values

The audio module is enabled by default. If you have disabled it using disableAudio, you can call this method to re-enable it.

Timing

Can be called before or after joining a channel. Remains effective after leaving the channel.

Return Values

If you want to obtain the audio spectrum data of local or remote users, register an audio spectrum observer and enable audio spectrum monitoring.

Parameters

intervalInMS

The interval (ms) at which the SDK triggers the onLocalAudioSpectrum and onRemoteAudioSpectrum callbacks. Default is 100 ms. The value must not be less than 10 ms, otherwise the method call will fail.

Return Values

This method allows the SDK to periodically report the volume information of the local user who is sending a stream and up to 3 remote users with the highest instantaneous volume to the app.

Timing

Can be called before or after joining a channel.

Related Callbacks

After successfully calling this method and when there are users sending streams in the channel, the SDK triggers the onAudioVolumeIndication callback at the set time interval.

Parameters

interval

Sets the time interval for volume indication:

• ≤ 0: Disables the volume indication feature.
• > 0: The time interval (ms) for returning volume indications. It is recommended to set it to more than 100 ms. If it is less than 10 ms, the onAudioVolumeIndication callback may not be received.

smooth

Smoothness factor that specifies the sensitivity of the volume indication. The range is [0,10], and the recommended value is 3. The larger the value, the more sensitive the fluctuation; the smaller the value, the smoother the fluctuation.

reportVad

• true: Enables local voice activity detection. When enabled, the vad parameter in the onAudioVolumeIndication callback reports whether voice is detected locally.
• false: (Default) Disables local voice activity detection. Unless the engine automatically performs local voice detection, the vad parameter in the onAudioVolumeIndication callback does not report local voice detection.

Return Values

Center Stage is disabled by default. You need to call this method to enable it. To disable the feature, call this method again and set enabled to false.

Scenario

The Center Stage feature can be widely used in scenarios such as online meetings, live shows, and online education. Hosts can enable this feature to keep themselves centered in the frame whether they move or not, ensuring a better visual presentation.

Timing

This method must be called after the camera is successfully started, i.e., after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LocalVideoStreamStateCapturing (1).

Parameters

enabled

Whether to enable the Center Stage feature:

• true: Enable Center Stage.
• false: Disable Center Stage.

Return Values

After local snapshot upload is enabled, the SDK captures and uploads snapshots of the video sent by the local user based on the module type and frequency you set in ContentInspectConfig. Once the snapshot is complete, the Agora server sends a callback notification to your server via HTTPS and uploads all snapshots to your specified third-party cloud storage.

Timing

Can be called before or after joining a channel.

Parameters

enabled

Specifies whether to enable local snapshot upload:

• true: Enable local snapshot upload.
• false: Disable local snapshot upload.

config

Configuration for local snapshot upload. See ContentInspectConfig.

Return Values

After calling this method to enable local playback of externally captured audio sources, you can call this method again and set enabled to false to stop local playback. You can call adjustCustomAudioPlayoutVolume to adjust the local playback volume of the custom audio capture track.

Parameters

trackId

Audio track ID. Set this parameter to the custom audio track ID returned by the createCustomAudioTrack method.

enabled

Whether to play the external audio source locally:

• true: Play locally.
• false: (Default) Do not play locally.

Return Values

Deprecated

Deprecated: Deprecated since v4.2.0. Use setDualStreamMode instead.

Parameters

enabled

Whether to enable dual-stream mode:

• true: Enable dual-stream mode.
• false: (Default) Disable dual-stream mode.

streamConfig

Configuration for the low-quality video stream. See SimulcastStreamConfig.

Note: When mode is set to DisableSimulcastStream, setting streamConfig has no effect.

Return Values

After the user leaves the channel, the SDK automatically disables encryption. To re-enable encryption, you need to call this method before the user joins the channel again.

Scenario

Scenarios with high security requirements.

Timing

This method must be called before joining a channel.

Parameters

enabled

Whether to enable built-in encryption:

• true: Enable built-in encryption.
• false: (default) Disable built-in encryption.

config

Configure the built-in encryption mode and key. See EncryptionConfig.

Return Values

Timing

It is recommended to call this method after joining a channel.

Related Callbacks

When this method is called successfully in a channel, it triggers the onExtensionStartedWithContext callback for enabling or the onExtensionStoppedWithContext callback for disabling the extension.

Parameters

provider

The name of the extension provider.

extension

The name of the extension.

enable

Whether to enable the extension:

• true: Enable the extension.
• false: Disable the extension.

type

The media source type of the extension. See MediaSourceType.

Return Values

Timing

This method must be called after the camera is started (e.g., by calling startPreview or enableVideo).

Related Callbacks

Parameters

enabled

Whether to enable face detection:

• true: Enable face detection.
• false: (Default) Disable face detection.

Return Values

Enables or disables in-ear monitoring.

Timing

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

Parameters

enabled

Whether to enable in-ear monitoring:

• true: Enable in-ear monitoring.
• false: (Default) Disable in-ear monitoring.

includeAudioFilters

The type of audio filter for in-ear monitoring. See EarMonitoringFilterType.

Return Values

After successfully calling this method, the SDK enables accelerated rendering for both video and audio frames, which speeds up the time to first frame and first audio after a user joins a channel.

Scenario

Agora recommends enabling this mode for audience users in live streaming scenarios.

Timing

This method must be called before joining a channel.

Return Values

Scenario

This method does not affect receiving and playing remote audio streams. enableLocalAudio(false) is suitable for scenarios where you only want to receive remote audio without sending locally captured audio.

Timing

You can call this method before or after joining a channel. If you call it before joining, it only sets the device state. It takes effect immediately after joining the channel.

Related Callbacks

After the audio function is disabled or re-enabled, you will receive the onLocalAudioStateChanged callback, which reports LocalAudioStreamStateStopped (0) or LocalAudioStreamStateRecording (1).

Parameters

enabled

• true: Re-enables the local audio function, that is, starts local audio capture (default);
• false: Disables the local audio function, that is, stops local audio capture.

Return Values

This method disables or re-enables local video capture without affecting the reception of remote video. After calling enableVideo, local video capture is enabled by default. If you call enableLocalVideo(false) in a channel, it stops local video capture and also stops publishing the video stream in the channel. To re-enable it, call enableLocalVideo(true), then call updateChannelMediaOptions and set the options parameter to publish the locally captured video stream to the channel. After successfully enabling or disabling local video capture, the remote side triggers the onRemoteVideoStateChanged callback.

Parameters

enabled

Whether to enable local video capture.

• true: (Default) Enables local video capture.
• false: Disables local video capture. After disabling, remote users will not receive the local user's video stream, but the local user can still receive remote video streams. When set to false, this method does not require a local camera.

Return Values

Parameters

enabled

Whether to enable multi-camera video capture mode:

• true: Enable multi-camera capture mode. The SDK uses multiple cameras to capture video.
• false: Disable multi-camera capture mode. The SDK uses only a single camera to capture video.

config

Capture configuration for the second camera. See CameraCapturerConfiguration.

Return Values

To use setRemoteVoicePosition for spatial audio positioning, make sure to call this method before joining a channel to enable stereo sound for remote users.

Parameters

enabled

Whether to enable stereo sound for remote users:

• true: Enable stereo sound.
• false: Disable stereo sound.

Return Values

After enabling spatial audio, you can call setRemoteUserSpatialAudioParams to set spatial audio parameters for remote users.

Parameters

enabled

Whether to enable spatial audio:

• true: Enable spatial audio.
• false: Disable spatial audio.

Return Values

The video module is disabled by default and needs to be enabled by calling this method. To disable the video module later, call the disableVideo method.

Timing

Related Callbacks

After successfully calling this method, the remote side triggers the onRemoteVideoStateChanged callback.

Return Values

When publishing a video stream, you can call this method to use a custom image to replace the current video stream for streaming. After enabling this feature, you can customize the placeholder image using the ImageTrackOptions parameter. After disabling the feature, remote users will continue to see the current published video stream.

Timing

It is recommended to call this method after joining the channel.

Parameters

enable

Whether to enable image placeholder streaming:

• true: Enable image placeholder streaming.
• false: (Default) Disable image placeholder streaming.

options

Placeholder image settings. See ImageTrackOptions.

Return Values

The virtual background feature allows replacing the local user's original background with a static image, dynamic video, blur effect, or separating the portrait from the background to create a picture-in-picture effect. Once enabled successfully, all users in the channel can see the customized background. Call this method after enableVideo or startPreview.

Parameters

enabled

Whether to enable virtual background:

• true: Enable virtual background.
• false: Disable virtual background.

backgroundSource

Custom background. See VirtualBackgroundSource. To adapt the resolution of the custom background image to the SDK's video capture resolution, the SDK scales and crops the image without distortion.

segproperty

Processing properties of the background image. See SegmentationProperty.

type

Media source type for applying the effect. See MediaSourceType.

Note: This parameter only supports the following settings:

• For video captured by the camera, use the default PrimaryCameraSource.
• For custom captured video, set this parameter to CustomVideoSource.

Return Values

The AI tuner feature enhances voice quality and adjusts voice tone style.

Scenario

Social and entertainment scenarios with high audio quality requirements, such as online karaoke, online podcasts, and live shows.

Timing

Can be called before or after joining the channel.

Parameters

enabled

Whether to enable the AI tuner feature:

• true: Enable the AI tuner feature.
• false: (Default) Disable the AI tuner feature.

type

AI tuner effect type. See VoiceAiTunerType.

Return Values

Deprecated

Deprecated: This method is deprecated. The SDK automatically enables interoperability with the Web SDK, so you do not need to call this method.

This method enables or disables interoperability with the Web SDK. If there are users joining the channel via the Web SDK, make sure to call this method. Otherwise, Web users may see a black screen from the Native side. This method is applicable only in live broadcast scenarios. In communication scenarios, interoperability is enabled by default.

Parameters

enabled

Whether to enable interoperability with the Web SDK:

• true: Enable interoperability.
• false: (default) Disable interoperability.

Return Values

After calling this method, you can get whether the audio device supports ultra-low latency capture and playback.

Return Values

Return Values

An IAudioDeviceManager object.

This method gets the current playback progress of the music file, in milliseconds.

Return Values

This method gets the total duration of the music file, in milliseconds.

Timing

You need to call this method after startAudioMixing and receiving the onAudioMixingStateChanged(AudioMixingStatePlaying) callback.

Return Values

You can call this method to get the local playback volume of the mixed music file, which helps troubleshoot volume-related issues.

Timing

You need to call this method after startAudioMixing and receiving the onAudioMixingStateChanged(AudioMixingStatePlaying) callback.

Return Values

This API helps developers troubleshoot volume-related issues.

Return Values

Return Values

Each time the client joins a channel, a corresponding callId is generated to identify the call session. You can call this method to obtain the callId parameter, then pass it to methods like rate and complain.

Timing

This method must be called after joining a channel.

Return Values

Return Values

The maximum zoom factor supported by the device camera.

Timing

Can be called before and after joining a channel.

Return Values

The current network connection state. See ConnectionStateType.

Monotonic Time refers to a monotonically increasing time sequence whose value increases over time. The unit is milliseconds. In scenarios such as custom video capture and custom audio capture, to ensure audio-video synchronization, Agora recommends that you call this method to get the current Monotonic Time from the SDK and pass this value to the timestamp parameter of the captured VideoFrame or AudioFrame.

Timing

Can be called before and after joining a channel.

Return Values

Parameters

soundId

ID of the sound effect. Each sound effect has a unique ID.

Return Values

Parameters

filePath

File path:

• Android: File path, must include the file name and extension. Supports URL addresses for online files, URI addresses for local files, absolute paths, or paths starting with /assets/. Accessing local files via absolute path may cause permission issues. Using URI addresses is recommended. For example: content://com.android.providers.media.documents/document/audio%3A14441.
• iOS: Absolute path or URL of the audio file, must include the file name and extension. For example: /var/mobile/Containers/Data/audio.mp4.

Return Values

Volume range is 0~100. 100 (default) is the original file volume.

Return Values

Parameters

code

The error code reported by the SDK.

Return Values

The specific error description.

Timing

Can be called before or after joining a channel.

Parameters

provider

The name of the plugin provider.

extension

The name of the plugin.

key

The key of the plugin property.

type

The media source type of the plugin. See MediaSourceType.

bufLen

The maximum length of the plugin property JSON string. Maximum value is 512 bytes.

Return Values

Call this method to get the current parameter settings of a face shaping area.

Scenario

When users open the facial area and intensity adjustment menu in the app, you can call this method to get the current options and update the UI accordingly.

Timing

Call this method after enableVideo.

Parameters

shapeArea

The face shaping area. See FaceShapeArea.

type

The media source type to apply the effect to. See MediaSourceType.

Note: This method only supports the following two settings:

• For local video captured by the camera, keep the default value PrimaryCameraSource.
• For custom captured video, set this parameter to CustomVideoSource.

Return Values

Call this method to get the current parameter settings of the face beauty effect.

Scenario

When users open the facial beauty style and intensity menu in the app, you can call this method to get the current options and update the UI accordingly.

Timing

Call this method after enableVideo.

Parameters

type

The media source type to apply the effect to. See MediaSourceType.

Note: This method only supports the following two settings:

• For local video captured by the camera, keep the default value PrimaryCameraSource.
• For custom captured video, set this parameter to CustomVideoSource.

Return Values

Return Values

An ILocalSpatialAudioEngine object.

Return Values

IMediaEngine object.

This method gets the C++ handle of the Native SDK engine, used in special scenarios such as registering audio and video callbacks.

Return Values

The Native handle of the SDK engine.

You can call this method at any time to get the current network type in use.

Return Values

In real-time chorus scenarios, especially when downlink inconsistencies occur at different receiving ends due to network issues, you can call this method to get the current NTP time as the reference time to align lyrics and music across multiple receivers for chorus synchronization.

Return Values

The current NTP time as a Unix timestamp (milliseconds).

After a remote user joins the channel, the SDK obtains the UID and User Account of the remote user, then caches a mapping table containing the UID and User Account of the remote user, and triggers the onUserInfoUpdated callback locally. After receiving the callback, call this method and pass in the UID to get the UserInfo object containing the specified user's User Account.

Timing

Call after receiving the onUserInfoUpdated callback.

Related Callbacks

onUserInfoUpdated

Parameters

uid

User ID.

Return Values

After a remote user joins the channel, the SDK obtains the UID and User Account of the remote user, then caches a mapping table containing the UID and User Account of the remote user, and triggers the onUserInfoUpdated callback locally. After receiving the callback, call this method and pass in the User Account to get the UserInfo object containing the specified user's UID.

Timing

Call after receiving the onUserInfoUpdated callback.

Related Callbacks

onUserInfoUpdated

Parameters

userAccount

User Account.

Return Values

Return Values

SDKBuildInfo object.

Return Values

An IVideoDeviceManager object.

Parameters

soundId

The ID of the audio effect file.

Return Values

Timing

Make sure to call createAgoraRtcEngine and initialize to create and initialize IRtcEngine before calling other APIs.

Parameters

context

Configuration for the IRtcEngine instance. See RtcEngineContext.

Return Values

Return Values

Return Values

Before calling enableCameraCenterStage to enable the Center Stage feature, you are advised to call this method to check whether the current device supports Center Stage.

Timing

You must call this method after the camera is successfully started, that is, after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LocalVideoStreamStateCapturing (1).

Return Values

Return Values

Return Values

Return Values

Return Values

Return Values

Timing

You must call this method after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LocalVideoStreamStateCapturing (1).

Return Values

Checks whether the current device meets the requirements for advanced features such as virtual background and beauty effects.

Scenario

Before using advanced audio and video features, you can check whether the current device supports them to avoid performance degradation or feature unavailability on low-end devices. Based on the return value of this method, you can decide whether to show or enable the corresponding feature buttons, or prompt users with appropriate messages when the device capability is insufficient.

Parameters

type

The type of advanced feature. See FeatureType.

Return Values

Timing

This method can be called before or after joining a channel.

Return Values

This method allows you to set media options when joining a channel, such as whether to publish audio and video streams in the channel. When a user joins a channel, whether to automatically subscribe to all remote audio and video streams in the channel. By default, the user subscribes to all other users' audio and video streams in the channel, which results in usage and affects billing. If you want to unsubscribe, you can do so by setting the options parameter or using the corresponding mute methods.

Timing

You must call this method after initialize.

Related Callbacks

Parameters

token

A dynamic key generated on the server for authentication. See Token Authentication.

Note:

• (Recommended) If your project enables the security mode, i.e., uses APP ID + Token for authentication, this parameter is required.
• If your project only enables debug mode, i.e., uses only the APP ID for authentication, you can join the channel without a Token. The user will automatically leave the channel 24 hours after successfully joining.
• If you need to join multiple channels simultaneously or switch channels frequently, Agora recommends using a wildcard Token to avoid requesting a new Token from the server each time. See Use Wildcard Token.

channelId

Channel name. This parameter identifies the channel for real-time audio and video interaction. Users with the same App ID and channel name will join the same channel. This parameter is a string of up to 64 bytes. Supported character set (89 characters total):

• 26 lowercase English letters a~z
• 26 uppercase English letters A~Z
• 10 digits 0~9
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

uid

User ID. This parameter identifies the user in the real-time audio and video interaction channel. You must set and manage the user ID yourself and ensure it is unique within the same channel. This parameter is a 32-bit unsigned integer. Recommended range: 1 to 2^32-1. If not specified (i.e., set to 0), the SDK automatically assigns one and returns it in the onJoinChannelSuccess callback. The application must remember and maintain this value; the SDK does not maintain it.

options

Channel media options. See ChannelMediaOptions.

Return Values

If you have not called registerLocalUserAccount to register a User Account before calling this method, the SDK automatically creates one for you. Calling registerLocalUserAccount before this method can reduce the time it takes to join the channel. After successfully joining a channel, the user subscribes to all other users' audio and video streams by default, which results in usage and affects billing. If you want to unsubscribe, you can do so by calling the corresponding mute methods.

Timing

You must call this method after initialize.

Related Callbacks

Parameters

token

A dynamic key generated on your server for authentication. See Use Token Authentication.

Note:

• (Recommended) If your project enables the security mode, i.e., uses APP ID + Token for authentication, this parameter is required.
• If your project only enables debug mode, i.e., uses only the APP ID for authentication, you can join the channel without a Token. The user will automatically leave the channel 24 hours after successfully joining.
• If you need to join multiple channels simultaneously or switch channels frequently, Agora recommends using a wildcard Token to avoid requesting a new Token from the server each time. See Use Wildcard Token.

userAccount

User Account. This parameter identifies the user in the real-time audio and video interaction channel. You must set and manage the User Account yourself and ensure it is unique within the same channel. This parameter is required, must not exceed 255 bytes, and cannot be null. Supported character set (89 characters total):

• 26 lowercase English letters a-z
• 26 uppercase English letters A-Z
• 10 digits 0-9
• Space
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

options

Channel media options. See ChannelMediaOptions.

Return Values

Before calling this method, if you have not called registerLocalUserAccount to register a User Account, the SDK automatically creates one for you when you join the channel. Calling registerLocalUserAccount before this method shortens the time needed to join the channel. After successfully joining a channel, the user subscribes to all remote users' audio and video streams by default, which incurs usage and affects billing. To unsubscribe, you can set the options parameter or call the corresponding mute methods.

Timing

This method must be called after initialize.

Related Callbacks

Parameters

token

A dynamic key generated on your server for authentication. See Token Authentication.

Note:

• (Recommended) If your project has enabled the security mode using APP ID + Token for authentication, this parameter is required.
• If your project is in debug mode using only APP ID for authentication, you can join the channel without a Token. You will automatically leave the channel 24 hours after joining.
• If you need to join multiple channels or switch frequently, Agora recommends using a wildcard Token to avoid requesting a new Token from your server each time. See Using Wildcard Token.

userAccount

The user's User Account. This parameter identifies the user in the real-time audio and video channel. You must set and manage the User Account yourself and ensure that each user in the same channel has a unique User Account. This parameter is required and must not exceed 255 bytes or be null. Supported character set (89 characters total):

• 26 lowercase letters a-z
• 26 uppercase letters A-Z
• 10 digits 0-9
• Space
• "!" "#" "$" "%" "&" "(" ")" "+" "-" ":" ";" "<" "=" "." ">" "?" "@" "[" "]" "^" "_" "{" "}" "|" "~" ","

options

Channel media options. See ChannelMediaOptions.

Return Values

After calling this method, the SDK stops all audio and video interactions, leaves the current channel, and releases all session-related resources. You must call this method after successfully joining a channel to end the call; otherwise, you cannot start a new call. If you have joined multiple channels using joinChannelEx, calling this method leaves all joined channels.

Timing

Call this method after joining a channel.

Related Callbacks

Parameters

options

Options for leaving the channel. See LeaveChannelOptions.

Return Values

This method adds external SDK plugins (such as marketplace plugins and SDK extension plugins) to the SDK.

Timing

Call this method immediately after initializing IRtcEngine.

Parameters

path

The path and name of the plugin dynamic library. For example: /library/libagora_segmentation_extension.dll.

unloadAfterUse

Whether to automatically unload the plugin after use:

• true: Automatically unloads the plugin when IRtcEngine is destroyed.
• false: Does not automatically unload the plugin until the process exits (recommended).

Return Values

After successfully calling this method, the local user stops or resumes subscribing to all remote users' audio streams, including those who join the channel after the method is called.

Timing

This method must be called after joining a channel.

Parameters

mute

Whether to stop subscribing to all remote users' audio streams:

• true: Stop subscribing to all remote users' audio streams.
• false: (Default) Subscribe to all remote users' audio streams.

Return Values

After successfully calling this method, the local user stops or resumes subscribing to all remote users' video streams, including those who join the channel after the method is called.

Timing

This method must be called after joining a channel.

Parameters

mute

Whether to stop subscribing to all remote users' video streams.

• true: Stop subscribing to all users' video streams.
• false: (Default) Subscribe to all users' video streams.

Return Values

This method controls whether to publish the locally captured audio stream. Not publishing the local audio stream does not disable the audio capturing device, so it does not affect the audio capture status.

Timing

Can be called before or after joining a channel.

Related Callbacks

After this method is successfully called, the local user triggers the onAudioPublishStateChanged callback; the remote user triggers the onUserMuteAudio and onRemoteAudioStateChanged callbacks.

Parameters

mute

Whether to stop publishing the local audio stream.

• true: Stop publishing.
• false: (Default) Publish.

Return Values

This method controls whether to publish the locally captured video stream. Not publishing the local video stream does not disable the video capturing device, so it does not affect the video capture status. Compared to calling enableLocalVideo(false) to disable video capture and thus stop publishing the local video stream, this method responds faster.

Timing

Can be called before or after joining a channel.

Related Callbacks

After this method is successfully called, the local user triggers the onVideoPublishStateChanged callback; the remote user triggers the onUserMuteVideo and onRemoteVideoStateChanged callbacks.

Parameters

mute

Whether to stop sending the local video stream.

• true: Stop sending the local video stream.
• false: (Default) Send the local video stream.

Return Values

Timing

Can be called before or after joining the channel.

Parameters

mute

• true: Mute.
• false: (Default) Original volume.

Return Values

Timing

This method must be called after joining a channel.

Related Callbacks

After this method is successfully called, the local user triggers the onAudioSubscribeStateChanged callback.

Parameters

uid

The user ID of the specified user.

mute

Whether to stop subscribing to the specified remote user's audio stream.

• true: Stop subscribing to the specified user's audio stream.
• false: (Default) Subscribe to the specified user's audio stream.

Return Values

Timing

You must call this method after joining a channel.

Related Callbacks

After this method is successfully called, the local user receives the onVideoSubscribeStateChanged callback.

Parameters

uid

The user ID of the specified remote user.

mute

Whether to stop subscribing to the video stream of the specified remote user.

• true: Stop subscribing to the video stream of the specified user.
• false: (Default) Subscribe to the video stream of the specified user.

Return Values

After starting media stream forwarding across channels, you can call this method to pause forwarding to all channels. To resume forwarding, call the resumeAllChannelMediaRelay method.

Return Values

Return Values

After you call the startAudioMixing method to play a music file, call this method to pause the playback. To stop the playback, call stopAudioMixing.

Timing

You must call this method after joining a channel.

Return Values

Parameters

soundId

The ID of the audio effect. Each audio effect has a unique ID.

Return Values

After calling preloadEffect multiple times to preload multiple audio effect files, you can call this method to play all preloaded audio effect files.

Parameters

loopCount

The number of times the audio effect loops:

• -1: Loops indefinitely until stopEffect or stopAllEffects is called.
• 0: Plays the audio effect once.
• 1: Plays the audio effect twice.

pitch

The pitch of the audio effect. The range is [0.5,2.0]. The default value is 1.0, which represents the original pitch. The smaller the value, the lower the pitch.

pan

The spatial position of the audio effect. The range is [-1.0,1.0]:

• -1.0: The audio effect appears on the left.
• 0: The audio effect appears in the center.
• 1.0: The audio effect appears on the right.

gain

The volume of the audio effect. The range is [0,100]. 100 is the default value, representing the original volume. The smaller the value, the lower the volume.

publish

Whether to publish the audio effect to remote users:

• true: Publishes the audio effect to remote users. Both local and remote users can hear it.
• false: (Default) Does not publish the audio effect to remote users. Only local users can hear it.

Return Values

You can call this method multiple times with different soundID and filePath to play multiple audio effect files simultaneously. For optimal user experience, it is recommended not to play more than 3 audio effects at the same time.

Timing

This method can be called before or after joining a channel.

Related Callbacks

After the audio effect finishes playing, the SDK triggers the onAudioEffectFinished callback.

Parameters

soundId

The ID of the audio effect. Each audio effect has a unique ID.

Note: If you have preloaded the audio effect using preloadEffect, make sure this parameter matches the soundId set in preloadEffect.

filePath

The path of the file to play. Supports URL of online files and absolute path of local files. Must include the file name and extension. Supported audio formats include MP3, AAC, M4A, MP4, WAV, 3GP, etc.

Note: If you have preloaded the audio effect using preloadEffect, make sure this parameter matches the filePath set in preloadEffect.

loopCount

The number of times the audio effect loops.

• ≥ 0: Number of loops. For example, 1 means loop once, i.e., play twice in total.
• -1: Loop indefinitely.

pitch

The pitch of the audio effect. The range is [0.5,2.0]. The default value is 1.0, which represents the original pitch. The smaller the value, the lower the pitch.

pan

The spatial position of the audio effect. The range is [-1.0,1.0], for example:

• -1.0: The audio effect appears on the left
• 0.0: The audio effect appears in the center
• 1.0: The audio effect appears on the right

gain

The volume of the audio effect. The range is [0.0,100.0]. The default value is 100.0, which represents the original volume. The smaller the value, the lower the volume.

publish

Whether to publish the audio effect to remote users:

• true: Publishes the audio effect to remote users. Both local and remote users can hear it.
• false: Does not publish the audio effect to remote users. Only local users can hear it.

startPos

The playback position of the audio effect file in milliseconds.

Return Values

Calling this method reduces the time it takes for a viewer to join a channel when frequently switching channels, thereby shortening the time to hear the host's first audio frame and see the first video frame, improving the viewer's video experience. If the channel has already been preloaded successfully, and the viewer leaves and rejoins the channel, as long as the Token used during preload is still valid, there is no need to preload again.

Timing

To improve the user experience of preloading channels, Agora recommends calling this method as early as possible after confirming the channel name and user information, and before joining the channel.

Parameters

token

A dynamic key generated on your server for authentication. See Token Authentication. When the Token expires, depending on the number of preloaded channels, you can provide a new Token in different ways:

• For one preloaded channel: call this method again with the new Token.
• For multiple preloaded channels:
  • If using a wildcard Token, call updatePreloadChannelToken to update the Token for all preloaded channels. When generating a wildcard Token, the user ID must not be 0. See Using Wildcard Token.
  • If using different Tokens: call this method with the user ID, channel name, and the updated Token.

channelId

The name of the channel to preload. This parameter identifies the channel for real-time audio and video interaction. Users with the same App ID and channel name join the same channel. This parameter must be a string no longer than 64 bytes. Supported character set (89 characters total):

• 26 lowercase letters a~z
• 26 uppercase letters A~Z
• 10 digits 0~9
• "!" "#" "$" "%" "&" "(" ")" "+" "-" ":" ";" "<" "=" "." ">" "?" "@" "[" "]" "^" "_" "{" "}" "|" "~" ","

uid

User ID. This parameter identifies the user in the real-time audio and video channel. You must set and manage the user ID yourself and ensure uniqueness within the channel. This parameter is a 32-bit unsigned integer. Recommended range: 1 to 2^32-1. If not specified (i.e., set to 0), the SDK automatically assigns one and returns it in the onJoinChannelSuccess callback. The application must store and manage this value; the SDK does not manage it.

Return Values

Calling this method can reduce the time it takes for a viewer to join a channel when frequently switching channels, thereby shortening the time to hear the first audio frame and see the first video frame from the host, and improving the video experience for viewers. If the channel has already been successfully preloaded, and the viewer leaves and rejoins the channel, as long as the token used during preloading is still valid, there is no need to preload it again.

Timing

To enhance the user experience of preloading channels, Agora recommends that you call this method as early as possible after confirming the channel name and user information, and before joining the channel.

Parameters

token

A dynamic key generated on your server for authentication. See Use Token Authentication. When the token expires, depending on the number of preloaded channels, you can pass a new token in different ways:

• For a single preloaded channel: call this method to pass the new token.
• For multiple preloaded channels:
  • If you use a wildcard token, call updatePreloadChannelToken to update the token for all preloaded channels. When generating a wildcard token, the user ID must not be 0. See Use Wildcard Token.
  • If you use different tokens: call this method and pass your user ID, corresponding channel name, and the updated token.

channelId

The name of the channel to preload. This parameter identifies the channel for real-time audio and video interaction. Under the same App ID, users with the same channel name will join the same channel for interaction. This parameter must be a string within 64 bytes. The supported character set includes 89 characters:

• 26 lowercase English letters a~z
• 26 uppercase English letters A~Z
• 10 digits 0~9
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

userAccount

The user's User Account. This parameter identifies the user in the real-time audio and video interaction channel. You need to set and manage the User Account yourself and ensure that each user in the same channel has a unique User Account. This parameter is required, must not exceed 255 bytes, and cannot be null. The supported character set includes 89 characters:

• 26 lowercase English letters a-z
• 26 uppercase English letters A-Z
• 10 digits 0-9
• space
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

Return Values

To ensure smooth communication, pay attention to the size of the audio effect files you preload. Supported audio formats for preloading are listed in Supported Audio Formats.

Timing

Agora recommends calling this method before joining a channel.

Parameters

soundId

The ID of the audio effect. Each audio effect has a unique ID.

filePath

File path:

• Android: The file path must include the file name and extension. Supports URL of online files, URI of local files, absolute path, or paths starting with /assets/. Accessing local files via absolute path may require permissions. It is recommended to use URI to access local files. For example: content://com.android.providers.media.documents/document/audio%3A14441.
• iOS: The absolute path or URL of the audio file. Must include the file name and extension. For example: /var/mobile/Containers/Data/audio.mp4.

startPos

The start position for loading the audio effect file, in milliseconds.

Return Values

To enable wide-angle or ultra-wide-angle camera modes, it is recommended to call this method first to check whether the device supports the corresponding focal length capabilities. Then, based on the query result, call setCameraCapturerConfiguration to adjust the camera's focal length configuration for optimal capture performance.

Return Values

Return Values

Scenario

In high-definition or ultra-high-definition video scenarios, you can first call this method to query the device score. If the returned score is low (e.g., below 60), you should lower the video resolution accordingly to avoid affecting the video experience. The minimum device score requirement varies by business scenario. For specific recommendations, please contact technical support.

Return Values

Scenario

In screen sharing scenarios, if you want to enable high frame rates (e.g., 60 fps) but are unsure whether the device supports it, you can call this method to query the maximum frame rate supported by the device. If high frame rates are not supported, you can lower the frame rate of the screen sharing stream accordingly to ensure the expected sharing experience.

Return Values

Parameters

callId

Call ID. You can get this parameter by calling getCallId.

rating

Rating for the call, from 1 (lowest) to 5 (highest).

description

Description of the call. The length must be less than 800 bytes.

Return Values

Parameters

config

Configuration for the encoded audio observer. See AudioEncodedFrameObserverConfig.

Return Values

An IAudioEncodedFrameObserver object.

After successfully registering an audio spectrum observer and calling enableAudioSpectrumMonitor to enable audio spectrum monitoring, the SDK reports callbacks implemented in the IAudioSpectrumObserver class at the interval you set.

Parameters

observer

The audio spectrum observer. See IAudioSpectrumObserver.

Return Values

The IAudioSpectrumObserver object.

For external SDK extensions (such as marketplace plugins and SDK extension plugins), after loading the plugin, you need to call this method to register it. Internal SDK plugins (included in the SDK package) are automatically loaded and registered after initializing IRtcEngine, so you don't need to call this method.

Timing

Parameters

provider

The name of the plugin provider.

extension

The name of the plugin.

type

The media source type of the plugin. See MediaSourceType.

Related Callbacks

After successfully calling this method, the local onLocalUserRegistered callback is triggered to report the local user's UID and User Account.

Parameters

appId

The App ID of your project registered in the console.

userAccount

The user's User Account. This parameter identifies the user in the real-time audio and video interaction channel. You need to set and manage the User Account yourself and ensure that each user in the same channel has a unique User Account. This parameter is required, must not exceed 255 bytes, and cannot be null. The supported character set includes 89 characters:

• 26 lowercase English letters a-z
• 26 uppercase English letters A-Z
• 10 digits 0-9
• space
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

Return Values

You need to implement the IMetadataObserver class yourself and specify the metadata type in this method. This method allows you to add synchronized metadata to the video stream for interactive live streaming, such as sending shopping links, e-coupons, and online quizzes.

Parameters

observer

The metadata observer. See IMetadataObserver.

type

The metadata type. Currently, only VideoMetadata is supported. See MetadataType.

Return Values

This method releases all resources used by the SDK. Some apps only use real-time audio and video communication when needed, and release the resources when not in use for other operations. This method is suitable for such cases. After calling this method, you can no longer use other methods and callbacks of the SDK. To use the real-time audio and video communication function again, you must call createAgoraRtcEngine and initialize in sequence to create a new IRtcEngine object.

Parameters

sync

Whether the method is a synchronous call:

• true: The method is synchronous.
• false: The method is asynchronous. Currently, only synchronous calls are supported. Do not set this parameter to this value.

Parameters

eventType

The name of the target event to listen to. See IRtcEngineEvent.

This method removes all previously added callback events.

Parameters

eventHandler

The callback event to be removed. See IRtcEngineEventHandler.

Return Values

For some callback functions that have been listened to, if you no longer need to receive callback messages after receiving the corresponding event, you can call this method to remove the corresponding listener.

Parameters

eventType

The name of the target event to listen to. See IRtcEngineEvent.

listener

The callback function corresponding to eventType. You must pass in the same function object that was passed to addListener. For example, to stop listening to onJoinChannelSuccess:

const onJoinChannelSuccess = (connection: RtcConnection, elapsed: number) => {};
engine.addListener('onJoinChannelSuccess', onJoinChannelSuccess);
engine.removeListener('onJoinChannelSuccess', onJoinChannelSuccess);

Since

Available since v4.6.2.

This method removes a previously added watermark image from the local video stream based on the specified unique ID.

Parameters

id

The ID of the watermark to be removed. This value must match the ID used when adding the watermark.

Return Values

This method is used to renew the token. The token will expire after a certain period, after which the SDK will not be able to connect to the server.

Timing

Parameters

token

The newly generated token.

Return Values

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

Return Values

After calling pauseAllEffects to pause all audio effect files, you can call this method to resume playback.

Timing

This method must be called after pauseAllEffects.

Return Values

After you call pauseAudioMixing to pause the playback of a music file, call this method to resume playback.

Timing

You must call this method after joining a channel.

Return Values

Parameters

soundId

The ID of the audio effect. Each audio effect has a unique ID.

Return Values

After retrieving the number of audio tracks in a music file, you can call this method to specify any track for playback. For example, if different tracks in a multi-track file contain songs in different languages, you can use this method to set the playback language.

Parameters

index

The specified audio track to play. The value must be greater than or equal to 0 and less than the return value of getAudioTrackCount.

Return Values

Agora provides custom data reporting and analytics services. This service is currently in a free beta period. During the beta, you can send up to 10 custom data messages within 6 seconds. Each message must not exceed 256 bytes, and each string must not exceed 100 bytes. To try this service, please [contact sales](mailto:support@agora.io) to enable it and agree on the custom data format.

If the media metadata is sent successfully, the receiver will receive the onMetadataReceived callback.

Parameters

metadata

The media metadata. See Metadata.

sourceType

The type of video source. See VideoSourceType.

Return Values

Parameters

streamId

Data stream ID. Obtained via createDataStream.

data

Data to be sent.

length

Length of the data.

Return Values

Scenario

In scenarios such as voice chat, online education, and online meetings, if the surrounding environment is noisy, the AI noise reduction feature can identify and reduce both steady and non-steady noises while preserving voice quality, thereby improving audio quality and user experience.

Timing

This method can be called before or after joining the channel.

Parameters

enabled

Whether to enable AI noise reduction:

• true: Enable AI noise reduction.
• false: (Default) Disable AI noise reduction.

mode

Noise reduction mode. See AudioAinsMode.

Return Values

If you have advanced requirements for audio processing, such as capturing and sending stereo sound, you can call this method to set advanced audio options.

Parameters

options

Advanced audio options. See AdvancedAudioOptions.

Return Values

Parameters

preset

SDK preset audio effects. The following are supported:

• RoomAcoustics3dVoice: 3D voice effect.
  • Before using this enum, you need to set the profile parameter of setAudioProfile to AudioProfileMusicStandardStereo(3) or AudioProfileMusicHighQualityStereo(5), otherwise the enum setting is invalid.
  • After enabling 3D voice, users must use audio playback devices that support stereo to hear the expected effect.
• PitchCorrection: Pitch correction effect.

param1

• If preset is set to RoomAcoustics3dVoice, then param1 represents the surround cycle of the 3D voice effect. Value range: [1,60] seconds. Default is 10, which means the voice surrounds 360 degrees in 10 seconds.
• If preset is set to PitchCorrection, then param1 represents the base scale:
  • 1: (Default) Major natural scale.
  • 2: Minor natural scale.
  • 3: Minor pentatonic scale.

param2

• If preset is set to RoomAcoustics3dVoice, set param2 to 0.
• If preset is set to PitchCorrection, then param2 represents the tonic pitch:
  • 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#

Return Values

Call this method to set the SDK's preset voice effects for the local user who is sending the stream. This does not change the gender characteristics of the original voice. After setting the effect, all users in the channel can hear it.

Timing

Parameters

preset

Preset audio effect option. See AudioEffectPreset.

Return Values

In stereo audio files, the left and right channels can store different audio data. Depending on your needs, you can set the channel mode to original, left channel, right channel, or mixed mode.

Scenario

Timing

You must call this method after startAudioMixing and after receiving the onAudioMixingStateChanged(AudioMixingStatePlaying) callback.

Parameters

mode

The channel mode. See AudioMixingDualMonoMode.

Return Values

When mixing local vocals with a music file, you can call this method to adjust only the pitch of the music file.

Timing

You must call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged(AudioMixingStatePlaying) callback.

Parameters

pitch

Adjusts the pitch of the music file played locally in semitone steps. The default value is 0, which means no pitch adjustment. The valid range is [-12,12]. Each adjacent value differs by one semitone. The greater the absolute value, the more the pitch is raised or lowered.

Return Values

You must call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged callback reporting the playback state as AudioMixingStatePlaying.

Parameters

speed

The playback speed of the music file. The recommended range is [50,400], where:

• 50: 0.5x speed.
• 100: Original speed.
• 400: 4x speed.

Return Values

This method sets the playback position of an audio file, allowing you to play from a specific point instead of from the beginning.

Timing

You must call this method after startAudioMixing and after receiving the onAudioMixingStateChanged(AudioMixingStatePlaying) callback.

Parameters

pos

An integer. The position in the progress bar, in milliseconds.

Return Values

Scenario

This method applies to various audio scenarios. You can choose as needed. For example, in scenarios that require high audio quality such as music education, it is recommended to set profile to AudioProfileMusicHighQuality (4) and scenario to AudioScenarioGameStreaming (3).

Timing

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

Parameters

profile

The audio encoding profile, including sample rate, bitrate, encoding mode, and the number of channels. See AudioProfileType.

scenario

The audio scenario. The volume type of the device varies depending on the audio scenario. See AudioScenarioType.

Return Values

Scenario

This method applies to various audio scenarios. You can choose as needed. For example, in scenarios that require high audio quality such as music education, it is recommended to set scenario to AudioScenarioGameStreaming (3).

Timing

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

Parameters

scenario

The audio scenario. The volume type of the device varies depending on the audio scenario. See AudioScenarioType.

Return Values

By default, both the SDK and the app have permission to operate the Audio Session. If you want only the app to operate the Audio Session, you can call this method to restrict the SDK’s permission. You can call this method before or after joining a channel. Once this method is called to restrict the SDK’s operation permission, the restriction takes effect when the SDK attempts to change the Audio Session.

Parameters

restriction

The SDK’s operation permission on the Audio Session. See AudioSessionOperationRestriction. This parameter is a bit mask, and each bit corresponds to a permission.

Return Values

Enables the local beauty effect and sets the beauty effect options.

Timing

Call this method after enableVideo or startPreview.

Parameters

enabled

Whether to enable the beauty effect:

• true: Enable the beauty effect.
• false: (default) Disable the beauty effect.

options

Beauty options. See BeautyOptions for details.

type

The media source type to apply the effect to. See MediaSourceType.

Note: This method only supports the following two settings:

• For local video captured by the camera, keep the default value PrimaryCameraSource.
• For custom captured video, set this parameter to CustomVideoSource.

Return Values

Parameters

enabled

Whether to enable auto exposure:

• true: Enable auto exposure.
• false: Disable auto exposure.

Return Values

By default, the SDK disables face auto focus on Android and enables it on iOS. To configure face auto focus manually, call this method.

Timing

You must call this method after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LocalVideoStreamStateCapturing (1).

Parameters

enabled

Whether to enable face auto focus:

• true: Enable face auto focus.
• false: Disable face auto focus.

Return Values

Timing

You must call this method before enabling local camera capture, such as before calling startPreview or joinChannel.

Parameters

config

Camera capture configuration. See CameraCapturerConfiguration.

Note: You do not need to set the deviceId parameter in this method.

Return Values

Parameters

type

The type of video source. See VideoSourceType.

Return Values

When the lighting in the shooting environment is insufficient or too bright, it can affect the quality of the captured video. To achieve better video effects, you can use this method to adjust the exposure factor of the camera.

Parameters

factor

The exposure factor of the camera. The default value is 0, which means using the camera's default exposure. The larger the value, the greater the exposure. If the video image is overexposed, you can lower the exposure factor; if the video image is underexposed and dark details are lost, you can increase the exposure factor. If the specified exposure factor exceeds the supported range of the device, the SDK automatically adjusts it to the supported range. On Android, the range is [-20.0,20.0]; on iOS, the range is [-8.0,8.0].

Return Values

Parameters

positionXinView

The X coordinate of the touch point relative to the view.

positionYinView

The Y coordinate of the touch point relative to the view.

Return Values

Parameters

positionX

The X coordinate of the touch point relative to the view.

positionY

The Y coordinate of the touch point relative to the view.

Return Values

Camera stabilization is disabled by default. You need to call this method to enable and set an appropriate stabilization mode.

Scenario

In scenarios such as mobile shooting, low-light environments, or handheld shooting, you can set the camera stabilization mode to reduce the impact of camera shake and obtain more stable and clearer images.

Timing

You must call this method after the camera is successfully started, that is, after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LocalVideoStreamStateCapturing (1).

Parameters

mode

Camera stabilization mode. See CameraStabilizationMode.

Return Values

Parameters

isOn

Whether to turn on the flashlight:

• true: Turn on the flashlight.
• false: (default) Turn off the flashlight.

Return Values

Some iOS devices have rear cameras composed of multiple lenses, such as dual cameras (wide-angle and ultra-wide-angle) or triple cameras (wide-angle, ultra-wide-angle, and telephoto). For such composite lenses with ultra-wide-angle capabilities, you can call setCameraCapturerConfiguration and set cameraFocalLengthType to CameraFocalLengthDefault (0) (standard lens), then call this method to set the camera zoom factor to a value less than 1.0 to achieve an ultra-wide-angle shooting effect.

Parameters

factor

The zoom factor of the camera. For devices that do not support ultra-wide-angle, the range is from 1.0 to the maximum zoom factor; for devices that support ultra-wide-angle, the range is from 0.5 to the maximum zoom factor. You can use getCameraMaxZoomFactor to get the maximum zoom factor supported by the device.

Return Values

You can call this method to set the channel profile. The SDK uses different optimization strategies for different scenarios. For example, in the live streaming scenario, it prioritizes video quality. The default channel profile after SDK initialization is live streaming.

Timing

You must call this method before joining a channel.

Parameters

profile

The channel profile. See ChannelProfileType.

Return Values

By default, the SDK sets the user role to audience. You can call this method to set the user role to broadcaster. The user role (role) determines the user's permissions at the SDK level, such as whether they can publish streams.

Timing

You can call this method either before or after joining a channel. If you call this method after joining the channel to switch user roles and the call succeeds, the SDK automatically calls muteLocalAudioStream and muteLocalVideoStream to update the publishing state of audio and video streams.

Related Callbacks

Parameters

role

The user role. See ClientRoleType.

Note: Users with the audience role cannot publish audio or video streams in the channel. When publishing in a live streaming scenario, ensure the user role is switched to broadcaster.

options

User-specific settings, including user level. See ClientRoleOptions.

Return Values

When a user's network is restricted by a firewall, you need to add the IP addresses and port numbers provided by Agora to the firewall whitelist, then call this method to enable the cloud proxy and set the proxy type via the proxyType parameter. After successfully connecting to the cloud proxy, the SDK triggers the onConnectionStateChanged (ConnectionStateConnecting, ConnectionChangedSettingProxyServer) callback. To disable a configured Force UDP or Force TCP cloud proxy, call setCloudProxy(NoneProxy). To change the configured cloud proxy type, first call setCloudProxy(NoneProxy), then call setCloudProxy again with the desired proxyType.

Parameters

proxyType

Cloud proxy type. See CloudProxyType. This parameter is required. If not set, the SDK returns an error.

Return Values

Video captured by the camera may have color distortion. The color enhancement feature intelligently adjusts video characteristics such as saturation and contrast to improve color richness and accuracy, resulting in more vivid video. You can call this method to enable the color enhancement feature and set its effect.

Parameters

enabled

Whether to enable the color enhancement feature:

• true: Enable color enhancement.
• false: (default) Disable color enhancement.

options

Color enhancement options used to set the enhancement effect. See ColorEnhanceOptions.

type

The media source type to apply the effect to. See MediaSourceType.

Note: This method only supports the following two settings:

• For local video captured by the camera, keep the default value PrimaryCameraSource.
• For custom captured video, set this parameter to CustomVideoSource.

Return Values

Timing

Call this method before joining a channel. To switch the audio route after joining a channel, call setEnableSpeakerphone.

Related Callbacks

After successfully changing the audio route, the SDK triggers the onAudioRoutingChanged callback to report the current audio route.

Parameters

defaultToSpeaker

Whether to use the speaker as the default audio route:

• true: Set the default audio route to speaker.
• false: Set the default audio route to earpiece.

Return Values

Deprecated

Deprecated since v4.6.2.

This method is only effective for audio collected from the microphone or custom audio sources, i.e., when publishMicrophoneTrack or publishCustomAudioTrack is set to true in DirectCdnStreamingMediaOptions.

Return Values

Deprecated

Deprecated since v4.6.2.

This method is only effective for video collected from the camera, screen sharing, or custom video sources, i.e., when publishCameraTrack or publishCustomVideoTrack is set to true in DirectCdnStreamingMediaOptions. If the resolution you set exceeds the capabilities of your camera device, the SDK adapts the resolution to the closest supported value with the same aspect ratio for capturing, encoding, and streaming. You can use the onDirectCdnStreamingStats callback to get the actual resolution of the pushed video stream.

Parameters

config

Video encoding configuration. See VideoEncoderConfiguration.

Note: When streaming directly to CDN, the SDK currently only supports setting OrientationMode to landscape (OrientationFixedLandscape) or portrait (OrientationFixedPortrait).

Return Values

Parameters

mode

The mode for sending video streams. See SimulcastStreamMode.

streamConfig

Configuration for the low-quality video stream. See SimulcastStreamConfig.

Note: When mode is set to DisableSimulcastStream, streamConfig has no effect.

Return Values

This method sets the audio data format for the onEarMonitoringAudioFrame callback.

Parameters

sampleRate

The sample rate (Hz) of the audio reported in onEarMonitoringAudioFrame, can be set to 8000, 16000, 32000, 44100, or 48000.

channel

The number of audio channels reported in onEarMonitoringAudioFrame, can be set to 1 or 2:

• 1: Mono.
• 2: Stereo.

mode

The usage mode of the audio frame. See RawAudioFrameOpModeType.

samplesPerCall

The number of audio samples reported in onEarMonitoringAudioFrame, typically 1024 in scenarios like CDN streaming.

Return Values

After the setting is successful, the local audio effect file starts playing from the specified position.

Parameters

soundId

The ID of the audio effect. Each audio effect has a unique ID.

pos

The playback position of the audio effect file, in milliseconds.

Return Values

Timing

You need to call this method after playEffect.

Parameters

volume

Playback volume. The range is [0,100]. The default value is 100, which means the original volume.

Return Values

For default audio routes in different scenarios,.

Scenario

If the SDK's default audio route or the setting of setDefaultAudioRouteToSpeakerphone does not meet your needs, you can call this method to switch the current audio route.

Timing

Call this method after joining a channel.

Related Callbacks

After successfully changing the audio route, the SDK triggers the onAudioRoutingChanged callback to report the current audio route.

Parameters

speakerOn

Whether to enable speakerphone playback:

• true: Enable. Audio route is speaker.
• false: Disable. Audio route is earpiece.

Return Values

After enabling a plugin, you can call this method to set its properties.

Timing

Call this method after calling enableExtension to enable the plugin.

Related Callbacks

After calling this method, the plugin event callback onExtensionEventWithContext may be triggered. The specific trigger logic depends on the plugin itself.

Parameters

provider

The name of the plugin provider.

extension

The name of the plugin.

key

The key of the plugin property.

value

The value corresponding to the plugin property key.

type

The media source type of the plugin. See MediaSourceType.

Return Values

You can call this method to set properties for the plugin provider and initialize related parameters based on the provider type.

Timing

Call this method after registerExtension and before enableExtension.

Parameters

provider

The name of the plugin provider.

key

The key of the plugin property.

value

The value corresponding to the plugin property key.

Return Values

After successfully calling this method, the external MediaProjection you set will replace the MediaProjection obtained by the SDK to capture screen video streams. When screen sharing stops or IRtcEngine is destroyed, the SDK automatically releases the MediaProjection.

Scenario

Timing

This method must be called before startScreenCapture.

Parameters

mediaProjection

A MediaProjection object used to capture screen video streams.

Return Values

By setting this method, developers can replace the SDK's default remote EGL context, facilitating unified EGL context management. When the engine is destroyed, the SDK automatically releases the EGL context.

Scenario

This method is applicable in scenarios where remote video rendering is done using video data in Texture format.

Timing

This method must be called before joining a channel.

Parameters

eglContext

The EGL context object used for rendering remote video streams.

Return Values

If the preset face shaping effects implemented in the setFaceShapeBeautyOptions method do not meet your expectations, you can use this method to set face shape area options to fine-tune individual facial features for more refined face shaping effects.

Timing

Call this method after setFaceShapeBeautyOptions.

Parameters

options

Face shape area options. See FaceShapeAreaOptions.

type

The media source type to which the effect is applied. See MediaSourceType.

Note: In this method, only the following two settings are supported:

• When using the camera to capture local video, keep the default value PrimaryCameraSource.
• To use custom captured video, set this parameter to CustomVideoSource.

Return Values

Call this method to apply preset parameters for facial modifications such as face slimming, eye enlargement, and nose slimming in one go, and to adjust the overall intensity of the effects.

Timing

Call this method after enableVideo.

Parameters

enabled

Whether to enable face shaping effects:

• true: Enable face shaping.
• false: (Default) Disable face shaping.

options

Face shaping style options. See FaceShapeBeautyOptions.

type

The media source type to which the effect is applied. See MediaSourceType.

Note: In this method, only the following two settings are supported:

• When using the camera to capture local video, keep the default value PrimaryCameraSource.
• To use custom captured video, set this parameter to CustomVideoSource.

Return Values

Timing

Call this method after enableVideo.

Parameters

enabled

Whether to enable filter effects:

• true: Enable filter effects.
• false: (Default) Disable filter effects.

options

Filter options. See FilterEffectOptions.

type

The media source type to which the effect is applied. See MediaSourceType.

Note: In this method, only the following two settings are supported:

• When using the camera to capture local video, keep the default value PrimaryCameraSource.
• To use custom captured video, set this parameter to CustomVideoSource.

Return Values

In spatial audio scenarios, if the expected effect is not achieved after calling setHeadphoneEQPreset to use a preset headphone equalizer effect, you can call this method to further adjust the headphone equalizer.

Parameters

lowGain

Low frequency parameter of the headphone equalizer. Range: [-10, 10]. The higher the value, the deeper the sound.

highGain

High frequency parameter of the headphone equalizer. Range: [-10, 10]. The higher the value, the sharper the sound.

Return Values

This method is mainly used in spatial audio scenarios. You can select a preset headphone equalizer to listen to audio and achieve the desired audio experience.

Parameters

preset

Preset headphone equalizer effect. See HeadphoneEqualizerPreset.

Return Values

Timing

Can be called before or after joining the channel.

Parameters

volume

Volume, range: [0,400].

• 0: Mute.
• 100: (Default) Original volume.
• 400: 4 times the original volume, with built-in overflow protection.

Return Values

After initializing the local user view, you can call this method to update the rendering and mirror mode of the local user view. This method only affects the video image seen by the local user and does not affect the publishing of the local video.

Timing

Parameters

renderMode

The display mode of the local view. See RenderModeType.

mirrorMode

The mirror mode of the local view. See VideoMirrorModeType.

Note: If you use the front camera, the mirror mode of the local user view is enabled by default; if you use the rear camera, the mirror mode is disabled by default.

Return Values

Scenario

In scenarios with low frame rate requirements for video rendering (e.g., screen sharing, online education), you can call this method to set the maximum frame rate for local video rendering. The SDK will try to match the actual rendering frame rate to this value to reduce CPU usage and improve system performance.

Timing

This method can be called before or after joining a channel.

Parameters

sourceType

The type of video source. See VideoSourceType.

targetFps

Maximum rendering frame rate (fps). Supported values: 1, 7, 10, 15, 24, 30, 60.

Note: Set this parameter to a value lower than the actual frame rate of the video, otherwise the setting will not take effect.

Return Values

Deprecated

Deprecated: This method is deprecated.

Parameters

mirrorMode

The mirror mode of the local video. See VideoMirrorModeType.

Return Values

Timing

Can be called before or after joining a channel.

Parameters

bandFrequency

Index of the frequency band. The value range is [0,9], representing 10 frequency bands. The corresponding center frequencies are [31, 62, 125, 250, 500, 1k, 2k, 4k, 8k, 16k] Hz. See AudioEqualizationBandFrequency.

bandGain

Gain of each band in dB. The value range is [-15,15], and the default is 0.

Return Values

Formant ratio is a parameter that affects the timbre of the voice. A smaller value results in a deeper voice, while a larger value results in a sharper voice. After setting the formant ratio, all users in the channel can hear the effect. If you want to change both timbre and pitch, Agora recommends using it together with setLocalVoicePitch.

Scenario

In scenarios like voice live streaming, voice chat rooms, and karaoke rooms, you can call this method to set the local voice's formant ratio to change the timbre.

Timing

Can be called before or after joining a channel.

Parameters

formantRatio

Formant ratio. The value range is [-1.0, 1.0]. The default is 0.0, which means no change to the original timbre.

Note: Agora recommends a value range of [-0.4, 0.6]. Effects outside this range may sound suboptimal.

Return Values

Timing

Can be called before or after joining a channel.

Parameters

pitch

Voice frequency. Can be set within the range [0.5, 2.0]. The smaller the value, the lower the pitch. The default is 1.0, meaning no pitch change.

Return Values

The SDK provides a simpler method setAudioEffectPreset to directly achieve preset reverb effects such as Pop, R&B, and KTV.

Parameters

reverbKey

Reverb effect key. There are 5 reverb effect keys in total. See AudioReverbType.

value

Value corresponding to each reverb effect key.

Return Values

Deprecated

Deprecated: This method is deprecated. Please set the log file path via the context parameter when calling initialize.

Sets the SDK's output log file. All logs generated during SDK runtime will be written to this file.

Timing

This method must be called immediately after initialize, otherwise the log output may be incomplete.

Parameters

filePath

Full path of the log file. The log file is UTF-8 encoded.

Return Values

Deprecated

Deprecated: This method is deprecated. Use the logConfig parameter in initialize instead to set the log file size.

Parameters

fileSizeInKBytes

The size of a single agorasdk.log log file in KB. The valid range is [128,20480], and the default is 2,048 KB. If you set fileSizeInKByte to less than 128 KB, the SDK automatically adjusts it to 128 KB. If you set it to more than 20,480 KB, the SDK automatically adjusts it to 20,480 KB.

Return Values

Deprecated

Deprecated: Use logConfig in initialize instead.

This method sets the log output level of the SDK. Different output levels can be used individually or in combination. The log levels in order are: LogFilterOff, LogFilterCritical, LogFilterError, LogFilterWarn, LogFilterInfo, and LogFilterDebug. When you select a level, you will see logs for that level and all levels before it. For example, if you select LogFilterWarn, you will see logs for LogFilterCritical, LogFilterError, and LogFilterWarn.

Parameters

filter

Log filter level. See LogFilterType.

Return Values

Deprecated

Deprecated: This method is deprecated. Set the log output level via the context parameter when calling initialize.

When you select a level, you will see log information for that level.

Parameters

level

Log level. See LogLevel.

Return Values

You can call this method to enable low-light enhancement and configure its effect.

Scenario

Low-light enhancement can adaptively adjust the video brightness in low-light conditions (such as backlight, cloudy days, or dark scenes) and uneven lighting environments to restore or highlight image details and improve the overall visual quality.

Timing

Call this method after enableVideo.

Parameters

enabled

Whether to enable low-light enhancement:

• true: Enable low-light enhancement.
• false: (Default) Disable low-light enhancement.

options

Low-light enhancement options to configure the effect. See LowlightEnhanceOptions.

type

The media source type to which the effect is applied. See MediaSourceType.

Note: In this method, only the following two settings are supported:

• When using the camera to capture local video, keep the default value PrimaryCameraSource.
• To use custom captured video, set this parameter to CustomVideoSource.

Return Values

After calling registerMediaMetadataObserver, you can call this method to set the maximum size of media metadata.

Parameters

size

The maximum size of media metadata.

Return Values

The SDK calculates the sampling interval using the samplesPerCall, sampleRate, and channel parameters in this method. The formula is: sampling interval = samplesPerCall / (sampleRate × channel). Ensure the interval is no less than 0.01 seconds. The SDK triggers the onMixedAudioFrame callback based on this interval.

Timing

This method must be called before joining a channel.

Parameters

sampleRate

The sample rate (Hz) of the audio data, can be set to 8000, 16000, 32000, 44100, or 48000.

channel

The number of audio channels, can be set to 1 or 2:

• 1: Mono.
• 2: Stereo.

samplesPerCall

The number of audio samples, typically 1024 in scenarios like CDN streaming.

Return Values

Parameters

parameters

Parameters in JSON string format.

Return Values

The SDK triggers the onPlaybackAudioFrameBeforeMixing callback based on this sampling interval.

Timing

This method must be called before joining a channel.

Parameters

sampleRate

The sample rate (Hz) of the audio data, can be set to 8000, 16000, 32000, 44100, or 48000.

channel

The number of audio channels, can be set to 1 or 2:

• 1: Mono.
• 2: Stereo.

samplesPerCall

Sets the number of audio samples returned in the onPlaybackAudioFrameBeforeMixing callback. In RTMP streaming scenarios, it is recommended to set this to 1024.

Return Values

The SDK calculates the sampling interval using the samplesPerCall, sampleRate, and channel parameters in this method. The formula is: sampling interval = samplesPerCall / (sampleRate × channel). Ensure that the sampling interval is no less than 0.01 seconds. The SDK triggers the onPlaybackAudioFrame callback based on this interval.

Timing

You must call this method before joining a channel.

Parameters

sampleRate

The sample rate (Hz) of the audio data. You can set it to 8000, 16000, 24000, 32000, 44100, or 48000.

channel

The number of audio channels. You can set it to 1 or 2:

• 1: Mono.
• 2: Stereo.

mode

The operation mode of the audio frame. See RawAudioFrameOpModeType.

samplesPerCall

The number of audio samples per call. Typically set to 1024 in scenarios such as CDN streaming.

Return Values

The SDK calculates the sampling interval using the samplesPerCall, sampleRate, and channel parameters in this method. The formula is: sampling interval = samplesPerCall / (sampleRate × channel). Ensure that the sampling interval is no less than 0.01 seconds. The SDK triggers the onRecordAudioFrame callback based on this interval.

Timing

You must call this method before joining a channel.

Parameters

sampleRate

The sample rate (Hz) of the audio data. You can set it to 8000, 16000, 32000, 44100, or 48000.

channel

The number of audio channels. You can set it to 1 or 2:

• 1: Mono.
• 2: Stereo.

mode

The operation mode of the audio frame. See RawAudioFrameOpModeType.

samplesPerCall

The number of audio samples per call. Typically set to 1024 in scenarios such as CDN streaming.

Return Values

Timing

You must call this method before joining a channel. The SDK does not support changing the default video stream type after joining a channel.

Parameters

streamType

The default video stream type to subscribe to: VideoStreamType.

Return Values

After initializing the remote user view, you can call this method to update the rendering and mirror mode of the remote user view as displayed locally. This method only affects the video image seen by the local user.

Parameters

uid

Remote user ID.

renderMode

The rendering mode of the remote user view. See RenderModeType.

mirrorMode

The mirror mode of the remote user view. See VideoMirrorModeType.

Return Values

Scenario

In scenarios where high video rendering frame rate is not required (e.g., screen sharing, online education), or when the remote user is using mid- to low-end devices, you can call this method to set the maximum frame rate for remote video rendering. The SDK will try to match the actual rendering frame rate to this value to reduce CPU usage and improve system performance.

Timing

This method can be called before or after joining a channel.

Parameters

targetFps

Maximum rendering frame rate (fps). Supported values: 1, 7, 10, 15, 24, 30, 60.

Note: Set this parameter to a value lower than the actual frame rate of the video, otherwise the setting will not take effect.

Return Values

Under poor network conditions, the quality of real-time audio and video may degrade. You can call this method and set option to StreamFallbackOptionVideoStreamLow or StreamFallbackOptionAudioOnly. When the downlink network is weak and audio/video quality is severely affected, the SDK will switch the video stream to a lower stream or disable the video stream to ensure audio quality. The SDK continuously monitors network quality and resumes audio and video subscription when conditions improve. When the subscribed stream falls back to audio or recovers to audio and video, the SDK triggers the onRemoteSubscribeFallbackToAudioOnly callback.

Parameters

option

Fallback option for the subscribed stream. See STREAM_FALLBACK_OPTIONS.

Return Values

You need to call this method after enableSpatialAudio. After successfully setting the spatial audio parameters for the remote user, the local user will hear spatial audio effects from the remote user.

Parameters

uid

User ID. Must be the same as the user ID used when joining the channel.

Return Values

Parameters

uid

The user ID.

streamType

The video stream type: VideoStreamType.

Return Values

Parameters

uid

Remote user ID.

options

Subscription settings for the video stream. See VideoSubscriptionOptions.

Return Values

Sets the 2D position and volume of a remote user's voice to help the local user locate the sound source. By calling this method, you can set the position where the remote user's voice appears. The difference between the left and right channels creates a sense of direction, allowing the user to determine the real-time position of the remote user. In multiplayer online games such as battle royale, this method can effectively enhance the sense of direction of game characters and simulate a real environment.

Parameters

uid

The ID of the remote user

pan

Sets the 2D position of the remote user's voice. The range is [-1.0, 1.0]:

• (Default) 0.0: Voice appears in the center.
• -1.0: Voice appears on the left.
• 1.0: Voice appears on the right.

gain

Sets the volume of the remote user's voice. The range is [0.0, 100.0], with a default of 100.0, representing the original volume. The smaller the value, the lower the volume.

Return Values

This method is used to switch the audio route from a Bluetooth headset to the earpiece, wired headset, or speaker in communication volume mode (MODE_IN_COMMUNICATION).

Timing

Can be called before or after joining a channel.

Related Callbacks

After this method is successfully called, the SDK triggers the onAudioRoutingChanged callback to report the current audio route.

Parameters

route

The desired audio route:

• -1: The system default audio route.
• 0: Headset with microphone.
• 1: Earpiece.
• 2: Headset without microphone.
• 3: Built-in speaker.
• 4: (Not supported) External speaker.
• 5: Bluetooth headset.
• 6: USB device.

Return Values

No practical meaning.

The SDK optimizes the sharing experience using different algorithms based on the content type. If you do not call this method, the SDK defaults the screen sharing content type to ContentHintNone, meaning no specific content type.

Parameters

contentHint

The content type of screen sharing. See VideoContentHint.

Return Values