IRtcEngine

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

Parameters

engineEventHandler

The callback event to be added. See IRtcEngineEventHandler.

Return Values

Deprecated

Deprecated: This method is deprecated. Use AddVideoWatermark [3/3] instead.

This method adds a PNG image as a watermark to the local published live video stream. Users in the same live channel, CDN audience, and even capture devices can see or capture the watermark image. If you only want to add a watermark in CDN streaming, refer to the usage described in StartRtmpStreamWithTranscoding.

Parameters

watermark

The watermark image to be added to the local live stream: RtcImage.

Return Values

Deprecated

Deprecated: This method is deprecated. Use addVideoWatermark [3/3] instead.

Parameters

watermarkUrl

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

options

Settings for the watermark image. See WatermarkOptions.

Return Values

Since

Available since v4.6.2.

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

Parameters

configs

Watermark configuration. See WatermarkConfig.

Return Values

Timing

You need to call this method after calling StartAudioMixing [2/2] and receiving the OnAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING) callback.

Parameters

volume

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

Return Values

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

Timing

You need to call this method after calling StartAudioMixing [2/2] and receiving the OnAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING) callback.

Parameters

volume

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

Return Values

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

Timing

You need to call this method after StartAudioMixing [2/2].

Parameters

volume

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

Return Values

After calling this method to set the local playback volume of the 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 it again to readjust the volume.

Parameters

trackId

The audio track ID. Set this parameter to the custom audio track ID returned by the CreateCustomAudioTrack method.

volume

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

Return Values

After calling EnableLoopbackRecording to enable sound card capture, you can call this method to adjust the volume of the captured signal.

Parameters

volume

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

Return Values

This method adjusts the signal volume of all remote users after mixing, as played locally. If you want to adjust the volume of a specific remote user locally, you are advised 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 need to mute the audio signal, it is recommended to use MuteRecordingSignal.

Timing

Can be called before or after joining a channel.

Parameters

volume

Volume, range is [0,400].

• 0: Mute.
• 100: (Default) Original volume.
• 400: Four times the original volume, with built-in 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 volume for multiple users, call this method multiple times.

Timing

Call this method after joining a channel.

Parameters

uid

Remote user ID.

volume

Volume, ranging from [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 issues with call quality. It must be called after leaving the channel.

Parameters

callId

Call ID. You can obtain this parameter by calling GetCallId.

description

(Optional) 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 status of the virtual metronome.

Parameters

config

Metronome configuration. See AgoraRhythmPlayerConfig.

Return Values

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

Return Values

IRtcEngine object.

Return Values

You can call this method to create a data stream and improve the reliability and ordering of data transmission.

Timing

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

Related Callbacks

After setting reliable to true, if the receiver does not receive the data sent by the sender within 5 seconds, the OnStreamMessageError callback is triggered with the corresponding error information.

Parameters

streamId

An output parameter. ID of the created data stream.

reliable

Note: Make sure to set both reliable and ordered to true or both to false.

Whether to ensure data reliability, i.e., whether the receiver must receive the data within 5 seconds after it is sent:

• true: The receiver will receive the data within 5 seconds, otherwise the OnStreamMessageError callback is triggered with the corresponding error information.
• false: The receiver is not guaranteed to receive the data, and no error is reported even if the data is lost.

ordered

Whether to ensure data ordering, i.e., whether the receiver must receive data in the order sent:

• true: The receiver receives data packets in the order sent by the sender.
• false: The receiver is not guaranteed to receive data packets in the order sent by the sender.

Return Values

Compared with CreateDataStream [1/2], this method does not guarantee the reliability of data transmission. The receiver discards packets that are received more than 5 seconds after being sent.

Timing

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

Parameters

streamId

Output parameter. The ID of the created data stream.

config

Data stream configuration. See DataStreamConfig.

Return Values

Before calling other APIs under the IMediaPlayer class, you must first 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

Event handler for 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 MEDIA_SOURCE_TYPE.

Return Values

Parameters

video_track_id

The video track ID returned by the CreateCustomVideoTrack method.

Return Values

Parameters

mediaPlayer

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. Still effective after leaving the channel.

Return Values

After calling EnableAudioSpectrumMonitor, if you want to disable audio spectrum monitoring, call this method.

Return Values

This method disables the video module.

Timing

Related Callbacks

After this method is called successfully, the remote side triggers 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. Still effective after leaving the channel.

Return Values

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

Parameters

intervalInMS

The interval (in milliseconds) 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 volume information of the local user and up to three remote users with the highest instantaneous volume to the app.

Timing

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

Related Callbacks

After you successfully call this method and there are users publishing streams in the channel, the SDK triggers the OnAudioVolumeIndication callback at the set time interval.

Parameters

interval

Sets the time interval of the volume indication:

• ≤ 0: Disables the volume indication.
• > 0: The interval (ms) at which the volume indication is returned. We recommend setting it to greater than 100 ms. The minimum value is 10 ms. If the value is less than 10 ms, you may not receive the OnAudioVolumeIndication callback.

smooth

The smoothing factor that sets the sensitivity of the volume indication. The value range is [0,10], and the recommended value is 3. The greater the value, the more sensitive the indication; the smaller the value, the smoother the indication.

reportVad

• true: Enables the local voice activity detection (VAD). After it is enabled, the vad parameter in the OnAudioVolumeIndication callback reports whether voice is detected locally.
• false: (Default) Disables the local VAD. Except for scenarios where the engine automatically performs local VAD, the vad parameter in the OnAudioVolumeIndication callback does not report whether voice is detected locally.

Return Values

The Center Stage feature 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 LOCAL_VIDEO_STREAM_STATE_CAPTURING (1).

Parameters

enabled

Whether to enable the Center Stage feature:

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

Return Values

After enabling local snapshot upload, the SDK captures and uploads snapshots of the local user's video based on the module type and frequency you set in ContentInspectConfig. Once the snapshots are captured, Agora's server sends a callback notification to your server via an HTTPS request and uploads all snapshots to your designated third-party cloud storage.

Timing

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

Parameters

enabled

Sets whether to enable local snapshot upload:

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

config

Local snapshot upload configuration. See ContentInspectConfig.

Return Values

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

Parameters

trackId

The 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 [1/2] instead.

Parameters

enabled

Whether to enable dual-stream mode.

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

Return Values

Deprecated

Deprecated: Deprecated since v4.2.0. Use SetDualStreamMode [2/2] instead.

Parameters

enabled

Whether to enable dual-stream mode:

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

streamConfig

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

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

Return Values

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

Scenario

Scenarios with high security requirements.

Timing

This method must be called before joining the 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 successfully called in a channel, the extension enabled callback OnExtensionStartedWithContext or extension disabled callback OnExtensionStoppedWithContext is triggered.

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

Return Values

Timing

This method must be called after the camera starts (e.g., by calling StartPreview [2/2] or EnableVideo).

Related Callbacks

Parameters

enabled

Whether to enable face detection:

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

Return Values

This method enables or disables in-ear monitoring.

Timing

Can be called before or after joining a channel.

Parameters

enabled

Enable/disable 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 EAR_MONITORING_FILTER_TYPE.

Return Values

After successfully calling this method, the SDK enables accelerated rendering for both video and audio, which speeds up the first frame rendering and audio output after a user joins the 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

Can be called before or after joining a channel. If called before joining, it only sets the device state; it takes effect immediately after joining the channel.

Related Callbacks

After disabling or re-enabling audio, you will receive the OnLocalAudioStateChanged callback, reporting LOCAL_AUDIO_STREAM_STATE_STOPPED(0) or LOCAL_AUDIO_STREAM_STATE_RECORDING(1).

Parameters

enabled

• true: Re-enable local audio, i.e., start local audio capture (default);
• false: Disable local audio, i.e., stop 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 the channel to disable local video capture, it 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) Enable local video capture.
• false: Disable local video capture. After disabling, the remote user will not receive the local user's video stream; however, the local user can still receive the remote user's video stream. When set to false, this method does not require the local device to have a camera.

Return Values

After enabling loopback recording, the sound played by the sound card will be mixed into the local audio stream and can be sent to the remote end.

Parameters

enabled

Whether to enable loopback recording:

• true: Enable loopback recording; the system sound > output interface displays the virtual sound card name.
• false: (Default) Disable loopback recording; the system sound > output interface does not display the virtual sound card name.

deviceName

• macOS: The device name of the virtual sound card. Default is empty, which means using the AgoraALD virtual sound card for recording.
• Windows: The device name of the sound card. Default is empty, which means using the built-in sound card of the device for recording.

Return Values

Parameters

enabled

Whether to enable multi-camera video capture mode:

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

config

Capture configuration for the second camera. See CameraCapturerConfiguration.

Return Values

To use SetRemoteVoicePosition to implement spatial audio positioning, make sure to call this method before joining the 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 must be enabled by calling this method. To disable the video module later, call the DisableVideo method.

Timing

Related Callbacks

After this method is called successfully, 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. When you disable the placeholder feature, remote users will continue to see your current video stream.

Timing

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

Parameters

enable

Whether to enable placeholder image streaming:

• true: Enable placeholder streaming.
• false: (default) Disable placeholder streaming.

options

Placeholder image settings. See ImageTrackOptions.

Return Values

The virtual background feature allows replacing the original background of the local user with a static image, dynamic video, blurred background, or segmenting the portrait from the background to achieve picture-in-picture. Once enabled successfully, all users in the channel can see the customized background. Call this method after EnableVideo or StartPreview [2/2].

Parameters

enabled

Whether to enable virtual background:

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

backgroundSource

Customized 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 while maintaining its aspect ratio.

segproperty

Processing properties for the background image. See SegmentationProperty.

type

Media source type to which the effect is applied. See MEDIA_SOURCE_TYPE.

Note: In this method, this parameter only supports the following two settings:

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

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 a 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 VOICE_AI_TUNER_TYPE.

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 a user joins the channel using the Web SDK, make sure to call this method; otherwise, the Web user will see a black screen for the Native user's video. This method is only applicable 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 check whether the audio device supports ultra-low latency capture and playback.

Parameters

deviceInfo

Audio device information. See DeviceInfoMobile.

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 [2/2] and receiving the OnAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING) 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 [2/2] and receiving the OnAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING) callback.

Return Values

This API helps developers troubleshoot volume-related issues.

Return Values

Return Values

Each time the client joins a channel, it generates a corresponding callId to identify the current call. You can call this method to get the callId parameter, and then pass it in when calling methods such as Rate and Complain.

Timing

You need to call this method after joining a channel.

Parameters

callId

An output parameter. The current call ID.

Return Values

Return Values

The maximum zoom factor supported by the device camera.

Timing

Can be called before or after joining a channel.

Return Values

The current network connection state. See CONNECTION_STATE_TYPE.

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

Timing

Can be called before or after joining a channel.

Return Values

Parameters

soundId

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

Return Values

Parameters

filePath

File path:

• Android: File path, including the file name and extension. Supports URL of online files, URI of local files, absolute path, or path starting with /assets/. Accessing local files via absolute path may cause permission issues. It is recommended to use URI to access local files. For example: content://com.android.providers.media.documents/document/audio%3A14441.
• Windows: Absolute path or URL of the audio file, including the file name and extension. For example: C:\music\audio.mp4.
• iOS or macOS: Absolute path or URL of the audio file, including the file name and extension. For example: /var/mobile/Containers/Data/audio.mp4.

Return Values

The volume range is 0~100. 100 (default) represents 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

Output parameter. The name of the extension provider.

extension

Output parameter. The name of the extension.

key

Output parameter. The key of the extension property.

value

Output parameter. The value corresponding to the extension property key.

type

The media source type of the extension. See MEDIA_SOURCE_TYPE.

buf_len

The maximum length of the extension property JSON string. Maximum value: 512 bytes.

Return Values

Call this method to get the current parameter settings for the 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

Face shaping area. See FACE_SHAPE_AREA.

options

Face shaping area options. See FaceShapeAreaOptions.

type

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

Note: In this method, this parameter only supports the following two settings:

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

Return Values

Call this method to get the current parameter settings for face shaping effects.

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

options

Face shaping style options. See FaceShapeBeautyOptions.

type

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

Note: In this method, this parameter only supports the following two settings:

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

Return Values

Return Values

An ILocalSpatialAudioEngine object.

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

Parameters

nativeHandler

An output parameter. The native handle of the SDK engine.

Return Values

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 the downlink is inconsistent across 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, enabling chorus synchronization.

Return Values

The Unix timestamp (in milliseconds) of the current NTP time.

Before screen or window sharing, you can call this method to get a list of shareable screen and window objects. This allows users to select a display or window to share based on the thumbnails in the list. The list includes important information such as window ID and screen ID. After obtaining the ID, you can call StartScreenCaptureByWindowId or StartScreenCaptureByDisplayId to start sharing.

Parameters

thumbSize

Target size (in pixels) of the screen or window thumbnail. The SDK scales the original image to match the longest side of the target size while maintaining the aspect ratio. For example, if the original image is 400 × 300 and thumbSize is 100 × 100, the thumbnail size will be 100 × 75. If the target size is larger than the original image, the SDK returns the original image without scaling.

iconSize

Target size (in pixels) of the application icon. The SDK scales the original image to match the longest side of the target size while maintaining the aspect ratio. For example, if the original image is 400 × 300 and iconSize is 100 × 100, the icon size will be 100 × 75. If the target size is larger than the original image, the SDK returns the original image without scaling.

includeScreen

Whether the SDK returns screen information in addition to window information:

• true: Returns both screen and window information.
• false: Returns only window information.

Return Values

ScreenCaptureSourceInfo array.

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

Timing

Call this method after receiving the OnUserInfoUpdated callback.

Related Callbacks

OnUserInfoUpdated

Parameters

uid

User ID.

userInfo

Input and output parameter. The UserInfo object identifying the user:

• Input: A UserInfo object.
• Output: A UserInfo object containing the user's User Account and UID.

Return Values

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

Timing

Call this method after receiving the OnUserInfoUpdated callback.

Related Callbacks

OnUserInfoUpdated

Parameters

userAccount

User Account.

userInfo

Input and output parameter. The UserInfo object identifying the user:

• Input: A UserInfo object.
• Output: A UserInfo object containing the user's User Account and UID.

Return Values

Parameters

build

Build number.

Return Values

The current SDK version number in string format.

Return Values

An IVideoDeviceManager object.

Parameters

soundId

The ID of the audio effect.

Return Values

Parameters

context

Configuration for the IRtcEngine instance. See RtcEngineContext.

Return Values

Return Values

Return Values

Before calling EnableCameraCenterStage to enable Center Stage, it is recommended to call this method to check whether the current device supports this feature.

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 LOCAL_VIDEO_STREAM_STATE_CAPTURING (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 the local video state returns LOCAL_VIDEO_STREAM_STATE_CAPTURING (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

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

Return Values

After joining a channel, by default users subscribe to all other users' audio and video streams in the channel, which generates usage and affects billing. To unsubscribe, use the corresponding mute methods.

Timing

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 security mode (i.e., uses APP ID + Token for authentication), this parameter is required.
• If your project only enables debug mode (i.e., uses APP ID for authentication), you can join the channel without providing a Token. You will be automatically disconnected after 24 hours.
• If you need to join multiple channels or frequently switch between channels, Agora recommends using a wildcard Token to avoid requesting a new Token from the server for each new channel. See 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. The parameter must be a string of up to 64 bytes. Supported character set (89 characters total):

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

info

(Optional) Reserved parameter.

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 that each user ID is unique within the same channel. The 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 layer must store and maintain this value as the SDK does not.

Return Values

Compared to JoinChannel [1/2], this method adds the options parameter to set media options, such as whether to publish audio and video streams in the channel. Whether a user automatically subscribes to all remote audio and video streams in the channel upon joining. By default, the user subscribes to all other users' audio and video streams in the channel, which incurs 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

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 secure mode (i.e., using APP ID + Token for authentication), this parameter is required.
• If your project is in debug mode only (i.e., using APP ID for authentication), you can join the channel without providing a Token. The user will automatically leave the channel after 24 hours.
• 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 your server each time you join a new channel. See Using 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. The parameter must be 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 that each user ID 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 layer must remember and manage this return value; the SDK does not maintain it.

options

Channel media configuration options. See ChannelMediaOptions.

Return Values

Before calling this method, if you have not called RegisterLocalUserAccount to register a User Account, the SDK will automatically create one for you when you call this method to join a channel. Calling RegisterLocalUserAccount before joining can reduce the time required to enter the channel. After successfully joining a channel, the user subscribes to all other users' audio and video streams by default, which incurs usage and affects billing. If you want to unsubscribe, you can do so by calling 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 secure mode (i.e., using APP ID + Token for authentication), this parameter is required.
• If your project is in debug mode only (i.e., using APP ID for authentication), you can join the channel without providing a Token. The user will automatically leave the channel after 24 hours.
• 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 your server each time you join a new channel. See Using 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 that each User Account 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
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

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 joining the channel. Calling RegisterLocalUserAccount before this method can shorten the time to join the channel. Compared with JoinChannelWithUserAccount [1/2], this method adds the options parameter, which allows you to set media options when joining the channel, such as whether to publish audio and video streams. By default, a user subscribes to all other users' audio and video streams in the channel, which incurs usage and affects billing. If you want to unsubscribe, you can do so via the options parameter or 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 enables security mode (i.e., uses APP ID + Token for authentication), this parameter is required.
• If your project is in debug mode only (i.e., uses APP ID for authentication), you can join the channel without a Token. You will automatically leave the channel after 24 hours.
• If you need to join multiple channels or switch between them 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 Account of the user. 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 each user in the same channel has a unique User Account. This parameter is required. Maximum length is 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 configuration options. See ChannelMediaOptions.

Return Values

After calling this method, the SDK stops 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 one.

Timing

Call this method after joining a channel.

Related Callbacks

Parameters

leaveChannelBlock

Callback after successfully leaving the channel, providing call statistics. See RtcStats.

Return Values

After calling this method, the SDK stops audio and video interactions, leaves the current channel, and releases all session-related resources. You must call this method or LeaveChannel [1/2] after successfully joining a channel to end the call, otherwise you cannot start a new one. 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 extensions (such as Marketplace extensions and SDK extension plugins) to the SDK.

Timing

Call this method immediately after initializing IRtcEngine.

Parameters

path

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

unload_after_use

Whether to automatically unload the extension after use:

• true: Automatically unloads the extension when IRtcEngine is destroyed.
• false: Does not automatically unload the extension 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 this 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 this 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 capture device, so it does not affect the audio capture status.

Timing

Can be called before or after joining the channel.

Related Callbacks

After this method is successfully called, the local user triggers the OnAudioPublishStateChanged callback; remote users trigger 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 capture device, so it does not affect the video capture status. Compared to calling EnableLocalVideo(false) to stop local video capture and thus stop publishing, this method responds faster.

Timing

Can be called before or after joining the channel.

Related Callbacks

After this method is successfully called, the local user triggers the OnVideoPublishStateChanged callback; remote users trigger 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 a channel.

Parameters

mute

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

Return Values

Timing

This method must be called after joining the 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 the channel.

Related Callbacks

After this method is successfully called, the local client triggers the OnVideoSubscribeStateChanged callback.

Parameters

uid

The user ID of the specified 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 to forward media streams across channels, if you need to pause forwarding to all channels, you can call this method. To resume forwarding, call the ResumeAllChannelMediaRelay method.

Return Values

Return Values

After calling the StartAudioMixing [2/2] method to play a music file, if you want to pause playback, call this method. If you want to stop playback, call StopAudioMixing.

Timing

You need to 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 several audio effects, you can call this method to play all preloaded audio effects.

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]. Default 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: Audio appears on the left.
• 0: Audio appears in the center.
• 1.0: Audio appears on the right.

gain

The volume of the audio effect. The range is [0,100]. 100 is the default and 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: (Default) Does not publish the audio effect to remote users. Only the local user can hear it.

Return Values

You can call this method multiple times with different soundID and filePath values to play multiple audio effects 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 loaded the audio effect into memory using PreloadEffect, ensure this parameter matches the soundId set in PreloadEffect.

filePath

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

Note: If you have loaded the audio effect into memory using PreloadEffect, ensure 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]. Default 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: Audio appears on the left
• 0.0: Audio appears in the center
• 1.0: Audio appears on the right

gain

The volume of the audio effect. The range is [0.0,100.0]. Default 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 the local user can hear it.

startPos

The playback position of the audio effect in milliseconds.

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 frame of audio or see the first frame of video from the host and improving the viewer's video experience. If the channel has already been successfully preloaded, and the viewer leaves and rejoins the same channel, as long as the Token used during preloading is still valid, preloading does not need to be performed again.

Timing

To enhance 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:

• Preloading a single channel: call this method with the new Token.
• Preloading multiple 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 Using Wildcard Tokens.
  • If you use different Tokens: call this method with 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. Users with the same App ID and channel name will enter the same channel for interaction. This parameter is a string up to 64 bytes in length. The supported character set (89 characters total) includes:

• 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 interaction channel. You need to set and manage the user ID yourself and ensure that each user ID in the same channel is unique. 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 will automatically assign one and return it in the OnJoinChannelSuccess callback. The application must store and maintain this return value, as 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 frame of audio or see the first frame of video from the host and improving the viewer's video experience. If the channel has already been successfully preloaded, and the viewer leaves and rejoins the same channel, as long as the Token used during preloading is still valid, preloading does not need to be performed again.

Timing

To enhance 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:

• Preloading a single channel: call this method with the new Token.
• Preloading multiple 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 Using Wildcard Tokens.
  • If you use different Tokens: call this method with 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. Users with the same App ID and channel name will enter the same channel for interaction. This parameter is a string up to 64 bytes in length. The supported character set (89 characters total) includes:

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

userAccount

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

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

Return Values

To ensure smooth communication, pay attention to the size of the preloaded audio effect file. Supported audio formats for preloading can be found in What audio formats does the RTC SDK support for playback.

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: File path including file name and extension. Supports online URLs, local file URI, absolute paths, or paths starting with /assets/. Accessing local files via absolute paths may cause permission issues. It is recommended to use URI, e.g., content://com.android.providers.media.documents/document/audio%3A14441.
• Windows: Absolute path or URL of the audio file, including file name and extension. For example, C:\music\audio.mp4.
• iOS or macOS: Absolute path or URL of the audio file, including file name and extension. For example, /var/mobile/Containers/Data/audio.mp4.

startPos

The start position for loading the audio effect, 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 result, call SetCameraCapturerConfiguration to adjust the focal length configuration for optimal camera capture performance.

Parameters

focalLengthInfos

Output parameter. After execution, returns an array of FocalLengthInfo objects containing the camera focal length information.

size

Output parameter. After execution, returns the number of focal length entries found.

Return Values

Parameters

codecInfo

Input and output parameter, representing the array of video codec capabilities supported by the SDK. See CodecCapInfo.

• Input: The CodecCapInfo defined by the user when calling this method, indicating the video codec capabilities to query.
• Output: The CodecCapInfo returned after the method execution, indicating the actual video codec capabilities supported by the SDK.

size

Input and output parameter, indicating the size of the CodecCapInfo array.

• Input: The size of CodecCapInfo defined by the user when calling this method.
• Output: The size of CodecCapInfo returned after the method execution.

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, ranging from 1 (lowest) to 5 (highest).

description

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

Return Values

Parameters

config

Observer configuration for encoded audio. See AudioEncodedFrameObserverConfig.

observer

Observer for encoded audio. See IAudioEncodedFrameObserver.

Return Values

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

Parameters

observer

Audio spectrum observer. See IAudioSpectrumObserver.

Return Values

For external SDK extensions (such as Marketplace extensions and SDK extension plugins), after loading the extension, you need to call this method to register it. Internal SDK extensions (included in the SDK package) are automatically loaded and registered after IRtcEngine is initialized, and do not require this method.

Timing

Parameters

provider

The name of the extension provider.

extension

The name of the extension.

type

The media source type of the extension. See MEDIA_SOURCE_TYPE.

Return Values

Related Callbacks

After successfully calling this method, the local OnLocalUserRegistered callback is triggered to report the UID and userAccount of the local user.

Parameters

appId

The App ID of your project registered in the console.

userAccount

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

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

Return Values

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

Parameters

observer

The metadata observer. See IMetadataObserver.

type

The metadata type. Currently only VIDEO_METADATA is supported. See METADATA_TYPE.

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 resources when not needed. This method is suitable for such scenarios. After calling this method, you can no longer use other SDK methods or callbacks. To use real-time audio and video communication again, you must call CreateAgoraRtcEngine and Initialize in sequence to create a new IRtcEngine object.

Parameters

sync

Whether this method is called synchronously:

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

Since

Available since v4.6.2.

This method removes the 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 be the same as the ID used when the watermark was added.

Return Values

This method is used to renew the Token. The Token will expire after a certain period, at which point the SDK will be unable to connect to the server.

Timing

Parameters

token

The newly generated Token.

Return Values

After calling the PauseAllChannelMediaRelay method, if you need to resume forwarding to all destination channels, you can call this method.

Return Values

After you call 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 calling PauseAudioMixing to pause the playback of a music file, call this method to resume playback.

Timing

You need to 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 the 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 call this method to set the playback language of the music file.

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 report up to 10 data entries within 6 seconds. Each custom data entry 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 successfully sent, the receiver receives the OnMetadataReceived callback.

Parameters

metadata

Media metadata. See Metadata.

source_type

Type of the video source. See VIDEO_SOURCE_TYPE.

Return Values

Parameters

streamId

Data stream ID. You can obtain it through CreateDataStream [2/2].

data

The 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 a channel.

Parameters

enabled

Whether to enable the AI noise reduction feature:

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

mode

Noise reduction mode. See AUDIO_AINS_MODE.

Return Values

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

Parameters

options

Advanced audio options. See AdvancedAudioOptions.

Return Values

Parameters

preset

SDK preset effects. Supported values:

• ROOM_ACOUSTICS_3D_VOICE: 3D voice effect.
  • Before using this enum, you must set the profile parameter of SetAudioProfile [2/2] to AUDIO_PROFILE_MUSIC_STANDARD_STEREO(3) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5), otherwise the setting is invalid.
  • To hear the expected effect, users must use audio playback devices that support stereo.
• PITCH_CORRECTION: Pitch correction effect.

param1

• If preset is set to ROOM_ACOUSTICS_3D_VOICE, then param1 specifies the surround cycle in seconds. Value range: [1,60]. Default is 10, meaning the voice surrounds 360 degrees in 10 seconds.
• If preset is set to PITCH_CORRECTION, then param1 specifies the base scale:
  • 1: (Default) Major scale.
  • 2: Minor scale.
  • 3: Japanese scale.

param2

• If preset is set to ROOM_ACOUSTICS_3D_VOICE, set param2 to 0.
• If preset is set to PITCH_CORRECTION, then param2 specifies the main 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 SDK preset voice effects for local sending users without altering the gender characteristics of the original voice. Once set, all users in the channel can hear the effect.

Timing

Parameters

preset

Preset effect options. See AUDIO_EFFECT_PRESET.

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 need to call this method after StartAudioMixing [2/2] and after receiving the OnAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING) callback.

Parameters

mode

The channel mode. See AUDIO_MIXING_DUAL_MONO_MODE.

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 need to call this method after StartAudioMixing [2/2] and after receiving the OnAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING) callback.

Parameters

pitch

Adjusts the pitch of the music file played locally in semitone steps. The default value is 0, meaning no adjustment. The 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 need to call this method after calling StartAudioMixing [2/2] and receiving the OnAudioMixingStateChanged callback reporting AUDIO_MIXING_STATE_PLAYING.

Parameters

speed

The playback speed of the music file. 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 the audio file so that you can play it from a specific point instead of from the beginning.

Timing

You need to call this method after StartAudioMixing [2/2] and after receiving the OnAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING) callback.

Parameters

pos

Integer. The position on the progress bar in milliseconds.

Return Values

Deprecated

Deprecated: This method is deprecated. To set the audio encoding profile, use SetAudioProfile [2/2]; to set the audio scenario, use SetAudioScenario.

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 number of channels. See AUDIO_PROFILE_TYPE.

scenario

The audio scenario. The volume type of the device varies by scenario. See AUDIO_SCENARIO_TYPE.

Return Values

If you want to set the audio scenario, you can call the SetAudioScenario method directly, or call Initialize and set the audioScenario field in the RtcEngineContext structure.

Scenario

This method applies to various audio scenarios. You can choose as needed. For example, in scenarios requiring high audio quality such as music teaching, set profile to AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4).

Timing

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

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 by scenario. See AUDIO_SCENARIO_TYPE.

Return Values

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

Parameters

restriction

The SDK's operation permissions for the Audio Session. See AUDIO_SESSION_OPERATION_RESTRICTION. This parameter is a bit mask, with each bit representing a permission.

Return Values

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

Timing

Call this method after EnableVideo or StartPreview [2/2].

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 which the effect is applied. See MEDIA_SOURCE_TYPE.

Note: In this method, this parameter only supports the following two settings:

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

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 manually configure face auto focus, call this method.

Timing

You must call this method after the SDK triggers the OnLocalVideoStateChanged callback and returns the local video state as LOCAL_VIDEO_STREAM_STATE_CAPTURING (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 starting local camera capture, such as before calling StartPreview [2/2] and JoinChannel [2/2].

Parameters

config

Camera capture configuration. See CameraCapturerConfiguration.

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

Return Values

Parameters

type

Video source type. See VIDEO_SOURCE_TYPE.

Return Values

Poor or overly bright lighting conditions affect the quality of video capture. To achieve better video results, you can use this method to adjust the camera's exposure factor.

Parameters

factor

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 is overexposed, you can reduce the exposure factor; if the video is underexposed and lacks detail in dark areas, you can increase the exposure factor. If the specified value exceeds the device's supported range, the SDK automatically adjusts it to a supported value. 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 it and set the 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

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 LOCAL_VIDEO_STREAM_STATE_CAPTURING (1).

Parameters

mode

Camera stabilization mode. See CAMERA_STABILIZATION_MODE.

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 composite rear cameras consisting of multiple lenses, such as dual-camera (wide and ultra-wide) or triple-camera (wide, ultra-wide, and telephoto). For such composite lenses with ultra-wide capability, you can call SetCameraCapturerConfiguration to set cameraFocalLengthType to CAMERA_FOCAL_LENGTH_DEFAULT (0) (standard lens), and then call this method to set the zoom factor to a value less than 1.0 to achieve an ultra-wide-angle effect.

Parameters

factor

Camera zoom factor. 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 call GetCameraMaxZoomFactor to get the maximum supported zoom factor.

Return Values

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

Timing

This method must be called before joining a channel.

Parameters

profile

The channel profile. See CHANNEL_PROFILE_TYPE.

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 permissions at the SDK level, including whether the user can publish streams.

Timing

This method can be called before or after joining a channel. If you call this method before joining the channel to set the user role to broadcaster and call SetEnable to enable video rendering, local video preview will automatically start upon joining the 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 CLIENT_ROLE_TYPE.

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

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 the user can publish streams. Compared to SetClientRole [1/2], this method also supports setting the audience latency level (audienceLatencyLevel). audienceLatencyLevel must be used together with role to determine the level of service a user can enjoy within their permission scope. For example, for audience users, whether to receive low-latency or ultra-low-latency video streams. Different latency levels affect billing. See Billing Strategy.

Timing

This method can be called before or after joining a channel. If you call this method before joining the channel to set the user role to broadcaster and call SetEnable to enable video rendering, local video preview will automatically start upon joining the 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 CLIENT_ROLE_TYPE.

Note: Users with the audience role cannot publish audio or video streams in the channel. To publish streams 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 the user's network access is restricted by a firewall, you need to add the IP 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 (CONNECTION_STATE_CONNECTING, CONNECTION_CHANGED_SETTING_PROXY_SERVER) callback. If you want to disable the currently set Force UDP or Force TCP cloud proxy, call SetCloudProxy(NONE_PROXY). If you want to change the currently set cloud proxy type, call SetCloudProxy(NONE_PROXY) first, then call SetCloudProxy again and pass in your desired proxyType value.

Parameters

proxyType

Cloud proxy type. See CLOUD_PROXY_TYPE. This parameter is required. If you do not assign a value, the SDK will report an error.

Return Values

Video captured by the camera may suffer from color distortion. The color enhancement feature can improve the richness and fidelity of video colors by intelligently adjusting video attributes such as saturation and contrast, making the video more vivid. You can call this method to enable the color enhancement feature and set the color enhancement 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 configure the effect. See ColorEnhanceOptions.

type

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

Note: In this method, this parameter only supports the following two settings:

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

Return Values

Timing

You must call this method before joining a channel. To switch audio routes after joining a channel, call SetEnableSpeakerphone.

Related Callbacks

After the audio route is successfully changed, 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.

Return Values

Deprecated

Deprecated since v4.6.2.

This method is only effective for video captured by the camera, screen sharing, or custom video sources. That is, it applies to video captured when publishCameraTrack or publishCustomVideoTrack is set to true in DirectCdnStreamingMediaOptions. If the resolution you set exceeds the range supported by your camera device, the SDK adapts based on your settings and captures, encodes, and pushes the stream using the closest resolution with the same aspect ratio as your setting. You can get the actual resolution of the pushed video stream via the OnDirectCdnStreamingStats callback.

Parameters

config

Video encoding configuration. See VideoEncoderConfiguration.

Note: When pushing the stream directly to the CDN, the SDK currently only supports setting ORIENTATION_MODE to landscape (ORIENTATION_MODE_FIXED_LANDSCAPE) or portrait (ORIENTATION_MODE_FIXED_PORTRAIT) mode.

Return Values

Parameters

mode

The mode for sending video streams. See SIMULCAST_STREAM_MODE.

Return Values

Parameters

mode

The mode for sending video streams. See SIMULCAST_STREAM_MODE.

streamConfig

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

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

Return Values

This method sets the data format for the OnEarMonitoringAudioFrame callback.

Parameters

sampleRate

The sampling rate (Hz) of the audio reported in OnEarMonitoringAudioFrame. Can be set to 8000, 16000, 32000, 44100, or 48000.

channel

The number of channels of the audio reported in OnEarMonitoringAudioFrame. Can be set to 1 or 2:

• 1: Mono.
• 2: Stereo.

mode

The operation mode of the audio frame. See RAW_AUDIO_FRAME_OP_MODE_TYPE.

samplesPerCall

The number of audio samples reported in OnEarMonitoringAudioFrame, typically 1024 in RTMP streaming scenarios.

Return Values

After successful setting, the local audio effect file will start 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

This method must be called after PlayEffect.

Parameters

volume

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

Return Values

For the SDK's 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

You must call this method after joining a channel.

Related Callbacks

After the audio route is successfully changed, 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 an extension, you can call this method to set its properties.

Timing

Call this method after calling EnableExtension to enable the extension.

Related Callbacks

After calling this method, the extension event callback OnExtensionEventWithContext may be triggered depending on the extension's logic.

Parameters

provider

The name of the extension provider.

extension

The name of the extension.

key

The key of the extension property.

value

The value corresponding to the extension property key.

type

The media source type of the extension. See MEDIA_SOURCE_TYPE.

Return Values

You can call this method to set the properties of the extension 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 extension provider.

key

The key of the extension property.

value

The value corresponding to the extension property key.

Return Values

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

Scenario

Timing

This method must be called before StartScreenCapture [1/2].

Parameters

mediaProjection

A MediaProjection object used to capture the screen video stream.

Return Values

By calling this method, developers can replace the SDK's default internal remote EGL context, making it easier to manage a unified EGL context. 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

You need to call this method before joining the channel.

Parameters

eglContext

The EGL context object used for rendering remote video streams.

Return Values

If the preset face shaping effect implemented in the SetFaceShapeBeautyOptions method does not meet expectations, you can use this method to set the face shaping area options and fine-tune each part of the face individually for more refined effects.

Timing

Call this method after SetFaceShapeBeautyOptions.

Parameters

options

Face shaping area options. See FaceShapeAreaOptions.

type

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

Note: In this method, this parameter only supports the following two settings:

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