RtcEngine

registerEventHandler

Adds the main callback event.

void registerEventHandler(RtcEngineEventHandler eventHandler);

The interface class RtcEngineEventHandler is used by the SDK to send callback event notifications to the App. The App receives SDK event notifications by inheriting methods from this interface class. All methods in the interface class have default (empty) implementations. The App can choose to inherit only the events it cares about. In callback methods, the App should not perform time-consuming tasks or call APIs that may block (e.g., sendStreamMessage), otherwise it may affect the operation of the SDK.

Parameters

eventHandler: The callback event to be added. See RtcEngineEventHandler.

Return Values

No return value if the method call succeeds; if the method call fails, an AgoraRtcException is thrown, which you need to catch and handle. See Error Codes for details and troubleshooting suggestions.

addVideoWatermark

Adds a local video watermark.

Future<void> addVideoWatermark(
    {required String watermarkUrl, required WatermarkOptions options});

Deprecated: Deprecated: This method is deprecated. Use addVideoWatermarkWithConfig instead.

This method adds a PNG image as a watermark to the local published live video stream. Users in the same live channel, audience of the CDN live stream, and capture devices can all see or capture the watermark image. Currently, only one watermark can be added to the live video stream. Adding a new watermark replaces the previous one. The watermark coordinates depend on the settings in the setVideoEncoderConfiguration method:

If the video orientation (OrientationMode) is fixed to landscape or adaptive landscape mode, landscape coordinates are used.
If the video orientation (OrientationMode) is fixed to portrait or adaptive portrait mode, portrait coordinates are used.
When setting the watermark coordinates, the image area of the watermark must not exceed the video dimensions set in the setVideoEncoderConfiguration method. Otherwise, the exceeding part will be cropped.

Note:

You must call this method after calling enableVideo.
If you only want to add a watermark during CDN streaming, you can use this method or startRtmpStreamWithTranscoding to set the watermark.
The watermark image must be in PNG format. This method supports all pixel formats of PNG images: RGBA, RGB, Palette, Gray, and Alpha_gray.
If the size of the PNG image to be added does not match the size set in this method, the SDK scales or crops the PNG image to match the settings.
If you have set the local video to mirror mode, the local watermark will also be mirrored. To avoid mirrored watermark when local users view their own video, it is recommended not to use both mirror and watermark features on local video. Implement the local watermark feature at the application layer.

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

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

addVideoWatermarkWithConfig

Adds a watermark image to the local video stream.

Future<void> addVideoWatermarkWithConfig(WatermarkConfig configs);

Since: Available since v4.6.2.

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

Parameters

configs: Watermark configuration. See WatermarkConfig.

Return Values

0: The method call succeeds.
< 0: The method call fails.

adjustAudioMixingPlayoutVolume

Adjusts the local playback volume of the music file.

Future<void> adjustAudioMixingPlayoutVolume(int volume);

Timing

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

Parameters

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

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

adjustAudioMixingPublishVolume

Adjusts the remote playback volume of the music file.

Future<void> adjustAudioMixingPublishVolume(int volume);

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

Timing

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

Parameters

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

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

adjustAudioMixingVolume

Adjusts the playback volume of the music file.

Future<void> adjustAudioMixingVolume(int volume);

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

Note: Calling this method does not affect the playback volume of sound effects set via the playEffect method.

Timing

This method must be called after startAudioMixing.

Parameters

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

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

adjustCustomAudioPlayoutVolume

Adjusts the local playback volume of a custom audio track.

Future<void> adjustCustomAudioPlayoutVolume(
      {required int trackId, required int volume});

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

Note: Before calling this method, make sure you have already called createCustomAudioTrack to create a custom audio track.

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 audio capture. Range: [0,100]. 0 means mute, 100 means original volume.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

< 0: Method call failed. See Error Codes for details and resolution suggestions.

adjustCustomAudioPublishVolume

Adjusts the remote playback volume of a custom audio track.

Future<void> adjustCustomAudioPublishVolume(
      {required int trackId, required int volume});

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

Note: Before calling this method, make sure you have already called createCustomAudioTrack to create a custom audio track.

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 audio capture. Range: [0,100]. 0 means mute, 100 means original volume.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

< 0: Method call failed. See Error Codes for details and resolution suggestions.

adjustLoopbackSignalVolume

Adjusts the volume of the signal captured by the sound card.

Future<void> adjustLoopbackSignalVolume(int volume);

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

Parameters

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

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

< 0: The method call fails. See Error Codes for details and resolution suggestions.

adjustPlaybackSignalVolume

Adjusts the signal volume of all remote users for local playback.

Future<void> adjustPlaybackSignalVolume(int volume);

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

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

adjustRecordingSignalVolume

Adjusts the volume of the audio recording signal.

Future<void> adjustRecordingSignalVolume(int volume);

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. The range is [0,400].

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

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

adjustUserPlaybackSignalVolume

Adjusts the playback volume of a specified remote user locally.

Future<void> adjustUserPlaybackSignalVolume(
    {required int uid, required int volume});

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, call this method multiple times.

Timing

You must call this method after joining a channel.

Parameters

uid

The ID of the remote user.

volume

The volume, with a range of [0,400].

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

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

clearVideoWatermarks

Removes added video watermarks.

Future<void> clearVideoWatermarks();

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

complain

Report call quality issues.

Future<void> complain({required String callId, required String description});

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 parameter by calling getCallId.
description: Description of the call. The length should be less than 800 bytes.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

configRhythmPlayer

Configures the virtual metronome.

Future<void> configRhythmPlayer(AgoraRhythmPlayerConfig config);

Deprecated: Deprecated since v4.6.2.

After calling startRhythmPlayer, you can call this method to reconfigure the virtual metronome.
After enabling the virtual metronome, the SDK starts playing the specified audio files from the beginning and controls the duration of each file based on the beatsPerMinute you set in AgoraRhythmPlayerConfig. For example, if beatsPerMinute is set to 60, the SDK plays 1 beat per second. If the file duration exceeds the beat duration, the SDK only plays the portion that fits the beat duration.
By default, the sound of the virtual metronome is not published to remote users. If you want remote users to hear it, set publishRhythmPlayerTrack in ChannelMediaOptions to true after calling this method.

Timing

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

Related Callbacks

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

Parameters

config: Metronome configuration. See AgoraRhythmPlayerConfig.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

createAgoraRtcEngine

Creates a RtcEngine object.

RtcEngine createAgoraRtcEngine() {
  return impl.RtcEngineImpl.create();
}

Currently, RTC SDK v6.x only supports creating one RtcEngine object per App.

Return Values

RtcEngine object.

createCustomVideoTrack

Creates a custom video track.

Future<int> createCustomVideoTrack();

When you need to publish custom captured video in a channel, follow these steps:

Call this method to create a video track and get the video track ID.
When calling joinChannel to join a channel, set customVideoTrackId in ChannelMediaOptions to the video track ID you want to publish and set publishCustomVideoTrack to true.
Call pushVideoFrame and specify videoTrackId as the video track ID from step 2 to publish the corresponding custom video source in the channel.

Return Values

If the method call succeeds, returns the video track ID as the unique identifier of the video track.
If the method call fails, returns 0xffffffff. See Error Codes for details and resolution suggestions.

createDataStream

Creates a data stream.

Future<int> createDataStream(DataStreamConfig config);

Note: If you need a more comprehensive, low-latency, high-concurrency, and scalable real-time messaging and state synchronization solution, we recommend using Real-time Messaging. During the lifecycle of RtcEngine, each user can create up to 5 data streams. The data streams are destroyed when leaving the channel. If needed again, you must recreate them.

Timing

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

Parameters

config: Data stream configuration. See DataStreamConfig.

Return Values

ID of the created data stream: method call succeeded.
< 0: method call failed. See Error Codes for details and resolution suggestions.

createMediaPlayer

Creates a media player object.

Future<MediaPlayer> createMediaPlayer();

Before calling other APIs under the MediaPlayer class, you need to 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 for RtcEngine. See RtcEngineEventHandler.

Return Values

If the method call succeeds: returns a MediaPlayer object.
If the method call fails: returns a null pointer.

createVideoEffectObject

Creates an IVideoEffectObject video effect object.

Future<VideoEffectObject?> createVideoEffectObject(
      {required String bundlePath,
      MediaSourceType type = MediaSourceType.primaryCameraSource});

Since: Available since v4.6.2.

Parameters

bundlePath: Path to the video effect resource package.
type: Media source type. See MediaSourceType.

Return Values

If the method call succeeds, returns a pointer to the IVideoEffectObject object. See IVideoEffectObject.
If the method call fails, returns NULL.

destroyCustomVideoTrack

Destroys the specified video track.

Future<void> destroyCustomVideoTrack(int videoTrackId);

Parameters

videoTrackId: The video track ID returned by the createCustomVideoTrack method.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

destroyMediaPlayer

Destroys the media player.

Future<void> destroyMediaPlayer(MediaPlayer mediaPlayer);

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

< 0: Failure. See Error Codes for details and resolution suggestions.

destroyVideoEffectObject

Destroys the video effect object.

Future<void> destroyVideoEffectObject(VideoEffectObject videoEffectObject);

Since: Available since v4.6.2.

Parameters

videoEffectObject: The video effect object to destroy. See VideoEffectObject.

Return Values

0: The method call succeeds.
< 0: The method call fails.

disableAudio

Disables the audio module.

Future<void> disableAudio();

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

Note: This method resets the entire engine and has a relatively slow response time. Therefore, Agora recommends using the following methods to control the audio module:

enableLocalAudio: Whether to enable microphone capture and create a local audio stream.
enableLoopbackRecording: Whether to enable sound card capture.
muteLocalAudioStream: Whether to publish the local audio stream.
muteRemoteAudioStream: Whether to receive and play the remote audio stream.
muteAllRemoteAudioStreams: Whether to receive and play all remote audio streams.

Timing

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

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

disableAudioSpectrumMonitor

Disables audio spectrum monitoring.

Future<void> disableAudioSpectrumMonitor();

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

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

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

disableVideo

Disables the video module.

Future<void> disableVideo();

This method disables the video module.

Note:

This method sets the internal engine to a disabled state and remains effective after leaving the channel.
Calling this method resets the entire engine and may take longer to respond. You can use the following methods to control specific video functions as needed:
- enableLocalVideo: Whether to enable camera capture and create the local video stream.
- muteLocalVideoStream: Whether to publish the local video stream.
- muteRemoteVideoStream: Whether to receive and play the remote video stream.
- muteAllRemoteVideoStreams: Whether to receive and play all remote video streams.

Timing

Can be called before or after joining a channel:

If called before joining, audio-only mode is enabled.
If called after joining, switches from video mode to audio-only mode. You can call enableVideo to switch back to video mode.

Related Callbacks

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

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

enableAudio

Enables the audio module.

Future<void> enableAudio();

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

Note:

Calling this method resets the entire engine and has a relatively slow response time. You can use the following methods to control specific audio module features based on your needs:
- enableLocalAudio: Whether to enable microphone capture and create a local audio stream.
- muteLocalAudioStream: Whether to publish the local audio stream.
- muteRemoteAudioStream: Whether to receive and play the remote audio stream.
- muteAllRemoteAudioStreams: Whether to receive and play all remote audio streams.
When calling this method in a channel, it resets the settings of enableLocalAudio, muteRemoteAudioStream, and muteAllRemoteAudioStreams. Use with caution.

Timing

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

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

enableAudioSpectrumMonitor

Enables audio spectrum monitoring.

Future<void> enableAudioSpectrumMonitor({int intervalInMS = 100});

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

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

Parameters

intervalInMS: The time interval (in milliseconds) at which the SDK triggers the onLocalAudioSpectrum and onRemoteAudioSpectrum callbacks. The default value is 100 ms. The value must not be less than 10 ms, otherwise the method call fails.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

enableAudioVolumeIndication

Enables audio volume indication.

Future<void> enableAudioVolumeIndication(
    {required int interval, required int smooth, required bool reportVad});

This method allows the SDK to periodically report 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 interval.

Parameters

interval

The time interval for volume indication:

≤ 0: Disables the volume indication.
> 0: The interval in milliseconds for volume indication. It is recommended to set it greater than 100 ms. Must not be less than 10 ms, otherwise the onAudioVolumeIndication callback will not be received.

smooth

The smoothing 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 detects local voice, the vad parameter in the onAudioVolumeIndication callback does not report local voice detection.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

enableCameraCenterStage

Enables or disables the Center Stage feature.

Future<void> enableCameraCenterStage(bool enabled);

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.

Note: This method is applicable to iOS and macOS only. As this feature requires high device performance, you need to use it on the following or higher-end devices:

iPad:
- 12.9-inch iPad Pro (5th generation)
- 11-inch iPad Pro (3rd generation)
- iPad (9th generation)
- iPad mini (6th generation)
- iPad Air (5th generation)
2020 M1 MacBook Pro 13-inch + iPhone 11 (using iPhone as an external camera for MacBook)

Agora recommends that you call isCameraCenterStageSupported to check whether the current device supports Center Stage before enabling this feature.

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

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

enabled

Whether to enable the Center Stage feature:

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

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly.

enableContentInspect

Enables/disables local snapshot upload.

Future<void> enableContentInspect(
      {required bool enabled, required ContentInspectConfig config});

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

Note:

Before calling this method, ensure that the local snapshot upload service has been enabled in the Agora Console.
When using the Agora-developed plugin for snapshot upload (contentInspectSupervision) in the video moderation module, you must integrate the local snapshot upload dynamic library libagora_content_inspect_extension.dll. Deleting this library will prevent the local snapshot upload feature from working properly.

Timing

Can be called 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

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

enableCustomAudioLocalPlayback

Sets whether to play the external audio source locally.

Future<void> enableCustomAudioLocalPlayback(
      {required int trackId, required bool enabled});

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

Note: Before calling this method, make sure you have already called createCustomAudioTrack to create a custom audio 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

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

enableDualStreamMode

Enables or disables dual-stream mode on the sending end and configures the low-quality stream.

Future<void> enableDualStreamMode(
      {required bool enabled, SimulcastStreamConfig? streamConfig});

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

You can call this method on the sending end to enable or disable dual-stream mode. Dual-stream refers to high-quality and low-quality video streams:

High-quality stream: High resolution and high frame rate video stream.
Low-quality stream: Low resolution and low frame rate video stream.

After enabling dual-stream mode, you can call setRemoteVideoStreamType on the receiving end to choose whether to receive the high-quality or low-quality stream.

Note:

This method applies to all types of streams sent by the sender, including but not limited to camera-captured video, screen sharing, and custom-captured video.
To enable dual-stream mode in multi-channel scenarios, call enableDualStreamModeEx.
This method can be called before or after joining a channel.

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 stream. See SimulcastStreamConfig.

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

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

enableEncryption

Enable or disable built-in encryption.

Future<void> enableEncryption(
    {required bool enabled, required EncryptionConfig config});

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

Note:

All users in the same channel must set the same encryption mode and key when calling this method.
If built-in encryption is enabled, the CDN live streaming feature cannot be used.

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

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

enableExtension

Enables or disables an extension.

Future<void> enableExtension(
    {required String provider,
    required String extension,
    bool enable = true,
    MediaSourceType type = MediaSourceType.unknownMediaSource});

Note:

To enable multiple extensions, you need to call this method multiple times.
After this method is called successfully, no other extensions can be loaded.

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

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

enableFaceDetection

Enables/disables local face detection.

Future<void> enableFaceDetection(bool enabled);

Timing

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

Related Callbacks

After calling this method successfully, the SDK triggers the onFacePositionChanged callback to report face detection information:

Size of the image captured by the camera
Position of the face in the view
Distance of the face from the device screen

Parameters

enabled

Whether to enable face detection:

true: Enables face detection.
false: (Default) Disables face detection.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

enableInEarMonitoring

Enables in-ear monitoring.

Future<void> enableInEarMonitoring(
      {required bool enabled,
      required EarMonitoringFilterType includeAudioFilters});

This method enables or disables in-ear monitoring.

Note: The user must use headphones (wired or Bluetooth) to hear the in-ear monitoring effect.

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 audio filter type for in-ear monitoring. See EarMonitoringFilterType.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

enableInstantMediaRendering

Enables accelerated rendering of audio and video frames.

Future<void> enableInstantMediaRendering();

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

Note: Both the host and audience need to call this method to enable accelerated rendering of audio and video frames to experience this feature. Once this method is successfully called, you can only disable accelerated rendering by calling the release method to destroy the RtcEngine object.

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

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

enableLocalAudio

Enables or disables local audio capture.

Future<void> enableLocalAudio(bool enabled);

When a user joins a channel, the audio function is enabled by default. This method can disable or re-enable the local audio function, that is, stop or restart local audio capture. The difference between this method and muteLocalAudioStream is:

enableLocalAudio: Enables or disables local audio capture and processing. Using enableLocalAudio to disable or enable local capture will cause a brief interruption in hearing remote playback locally.
muteLocalAudioStream: Stops or resumes sending the local audio stream without affecting the capture status.

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

This method can be called before or after joining a channel. When called before joining, it only sets the device state and takes effect immediately after joining.

Related Callbacks

After the audio function is disabled or re-enabled, the onLocalAudioStateChanged callback is triggered, reporting localAudioStreamStateStopped(0) or localAudioStreamStateRecording(1).

Parameters

enabled

true: Re-enables the local audio function, i.e., enables local audio capture (default);
false: Disables the local audio function, i.e., stops local audio capture.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

enableLocalVideo

Enables or disables local video capture.

Future<void> enableLocalVideo(bool enabled);

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

Note:

This method can be called before or after joining a channel. However, settings made before joining only take effect after joining.
This method sets the internal engine to an enabled state and remains effective after leaving the channel.

Parameters

enabled

Whether to enable local video capture.

true: (Default) Enable local video capture.
false: Disable local video capture. After disabling, the remote user cannot receive the local video stream, but the local user can still receive the remote video stream. When set to false, this method does not require a local camera.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

enableLoopbackRecording

Enables sound card capture.

Future<void> enableLoopbackRecording(
    {required bool enabled, String? deviceName});

After enabling the sound card capture function, the sound played by the sound card is mixed into the local audio stream and can be sent to the remote side.

Note:

This method is only applicable to macOS and Windows platforms.
This method can be called before or after joining a channel.
If you call disableAudio to disable the audio module, the sound card capture function will also be disabled. To re-enable it, you must call enableAudio to enable the audio module, and then call enableLoopbackRecording again.

Parameters

enabled

Whether to enable sound card capture:

true: Enable sound card capture; the virtual sound card name is displayed in System Sound > Output.
false: (Default) Disable sound card capture; the virtual sound card name is not displayed in System Sound > Output.

deviceName

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

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

enableMultiCamera

Enables or disables multi-camera capture.

Future<void> enableMultiCamera(
      {required bool enabled, required CameraCapturerConfiguration config});

In scenarios where a video is already being captured using a camera, Agora recommends the following steps to achieve multi-camera capture and publish video:

Call this method to enable multi-camera capture.
Call startPreview to start local video preview.
Call startCameraCapture and set sourceType to specify the second camera for capture.
Call joinChannelEx and set publishSecondaryCameraTrack to true to publish the second camera's video stream in the channel.

To disable multi-camera capture, refer to the following steps:

Call stopCameraCapture.
Call this method and set enabled to false.

This method is only applicable to iOS.When using multi-camera capture, ensure the system version is 13.0 or above.The minimum supported iOS device models for multi-camera capture are as follows:

iPhone XR
iPhone XS
iPhone XS Max
iPad Pro (3rd generation and later)

Note: You can call this method to enable multi-camera capture either before or after startPreview:

If called before startPreview, the local video preview will display feeds from both cameras simultaneously.
If called after startPreview, the SDK will stop the current camera capture first, then start both the original and the second camera. The local video preview may briefly go black before automatically recovering.

Parameters

enabled

Whether to enable multi-camera video capture mode:

true: Enables multi-camera capture mode. The SDK uses multiple cameras to capture video.
false: Disables multi-camera capture mode. The SDK uses only a single camera to capture video.

config

Configuration for the second camera. See CameraCapturerConfiguration.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

enableSoundPositionIndication

Enables/disables stereo sound for remote users.

Future<void> enableSoundPositionIndication(bool enabled);

To enable spatial audio positioning using setRemoteVoicePosition, 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

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

enableSpatialAudio

Enables or disables spatial audio.

Future<void> enableSpatialAudio(bool enabled);

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

Note:

This method can be called before or after joining a channel.
This method depends on the spatial audio dynamic library libagora_spatial_audio_extension.dll. Deleting this library will cause the feature to fail to enable properly.

Parameters

enabled

Whether to enable spatial audio:

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

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

enableVideo

Enables the video module.

Future<void> enableVideo();

The video module is disabled by default. You need to call this method to enable it. To disable the video module later, call the disableVideo method.

Note:

This method sets the internal engine to an enabled state and remains effective after leaving the channel.
Calling this method resets the entire engine and may take longer to respond. You can use the following methods to control specific video functions as needed:
- enableLocalVideo: Whether to enable camera capture and create the local video stream.
- muteLocalVideoStream: Whether to publish the local video stream.
- muteRemoteVideoStream: Whether to receive and play the remote video stream.
- muteAllRemoteVideoStreams: Whether to receive and play all remote video streams.
When called in a channel, this method resets the settings of enableLocalVideo, muteRemoteVideoStream, and muteAllRemoteVideoStreams. Use with caution.

Timing

This method can be called before or during a channel:

If called before joining, the video module is enabled.
If called during an audio-only call, the call automatically switches to a video call.

Related Callbacks

After this method is successfully called, the remote side receives the onRemoteVideoStateChanged callback.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

enableVideoImageSource

Enables or disables the placeholder image streaming feature.

Future<void> enableVideoImageSource(
      {required bool enable, required ImageTrackOptions options});

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 placeholder feature, remote users will still see the video stream you are currently publishing.

Timing

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

Parameters

enable

Whether to enable placeholder image streaming:

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

options

Placeholder image settings. See ImageTrackOptions.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

< 0: The method call fails. See Error Codes for details and resolution suggestions.

enableVirtualBackground

Enables/disables virtual background.

Future<void> enableVirtualBackground(
      {required bool enabled,
      required VirtualBackgroundSource backgroundSource,
      required SegmentationProperty segproperty,
      MediaSourceType type = MediaSourceType.primaryCameraSource});

The virtual background feature allows replacing the original background of the local user with a static image, dynamic video, blurring the background, or segmenting the portrait from the background to achieve picture-in-picture effects. After successfully enabling the virtual background feature, all users in the channel can see the customized background. Call this method after enableVideo or startPreview.

Note:

Using video as a virtual background may cause continuous memory usage growth, which can lead to app crashes. Therefore, try to reduce the resolution and frame rate of the video when using it.
This feature has high performance requirements. The SDK automatically checks the current device capability when calling this method. It is recommended to use it on devices with the following chipsets:
- Snapdragon 700 series 750G and above
- Snapdragon 800 series 835 and above
- Dimensity 700 series 720 and above
- Kirin 800 series 810 and above
- Kirin 900 series 980 and above
- Devices with A9 and above chips:
  - iPhone 6S and above
  - iPad Air 3rd generation and above
  - iPad 5th generation and above
  - iPad Pro 1st generation and above
  - iPad mini 5th generation and above
It is recommended to use this feature under the following conditions:
- Using a high-definition camera and evenly lit environment.
- The scene contains few objects, the user's portrait is half-body and mostly unobstructed, and the background color is relatively uniform and different from the user's clothing color.
This method depends on the virtual background dynamic library libagora_segmentation_extension.dll. Deleting this library will cause the feature to fail to start properly.

Parameters

enabled

Whether to enable virtual background:

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

backgroundSource

The 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 custom background image while preserving its aspect ratio.

segproperty

Processing properties of the background image. See SegmentationProperty.

type

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

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

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

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

enableVoiceAITuner

Enables or disables the AI tuner feature.

Future<void> enableVoiceAITuner(
    {required bool enabled, required VoiceAiTunerType type});

The AI tuner feature enhances audio 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 VoiceAiTunerType.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

enableWebSdkInteroperability

Enable interoperability with Web SDK (applicable only in live broadcast scenarios).

Future<void> enableWebSdkInteroperability(bool enabled);

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 users join the channel via Web SDK, make sure to call this method; otherwise, Web users may see a black screen when viewing the Native side. 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

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

getAudioDeviceInfo

Gets audio device information.

Future<DeviceInfo> getAudioDeviceInfo();

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

Note:

This method is applicable to Android only.
This method can be called before or after joining a channel.

Return Values

A DeviceInfo object containing audio device information.

Non-null: The method call succeeds.
Null: The method call fails. See Error Codes for details and resolution suggestions.

getAudioDeviceManager

Gets the AudioDeviceManager object to manage audio devices.

AudioDeviceManager getAudioDeviceManager();

Return Values

An AudioDeviceManager object.

getAudioMixingCurrentPosition

Gets the playback progress of the music file.

Future<int> getAudioMixingCurrentPosition();

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

Note:

You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged(audioMixingStatePlaying) callback.
If you need to call getAudioMixingCurrentPosition multiple times, ensure the interval between calls is greater than 500 ms.

Return Values

≥ 0: The method call succeeds and returns the current playback progress of the music file (ms). 0 indicates the music file has not started playing.
< 0: The method call fails. See Error Codes for details and resolution suggestions.

getAudioMixingDuration

Gets the total duration of the music file.

Future<int> getAudioMixingDuration();

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

≥ 0: The method call succeeds and returns the duration of the music file.
< 0: The method call fails. See Error Codes for details and resolution suggestions.

getAudioMixingPlayoutVolume

Gets the local playback volume of the music file.

Future<int> getAudioMixingPlayoutVolume();

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

≥ 0: The method call succeeds and returns the volume value, range is [0,100].
< 0: The method call fails. See Error Codes for details and resolution suggestions.

getAudioMixingPublishVolume

Gets the remote playback volume of the music file.

Future<int> getAudioMixingPublishVolume();

This interface helps developers troubleshoot volume-related issues.

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

Return Values

≥ 0: The method call succeeds and returns the volume value, range is [0,100].
< 0: The method call fails. See Error Codes for details and resolution suggestions.

getAudioTrackCount

Gets the audio track index of the current music file.

Future<int> getAudioTrackCount();

Note:

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

Return Values

When the method call succeeds, returns the audio track index of the current music file.
< 0: The method call fails. See Error Codes for details and resolution suggestions.

getCallId

Gets the call ID.

Future<String> getCallId();

Each time the client joins a channel, a corresponding callId is generated 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

This method must be called after joining a channel.

Return Values

Call ID.

getCameraMaxZoomFactor

Gets the maximum zoom factor supported by the camera.

Future<double> getCameraMaxZoomFactor();

Note:

This method is only applicable to Android and iOS.
Call this method after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as localVideoStreamStateCapturing (1).

Return Values

The maximum zoom factor supported by the device camera.

getConnectionState

Gets the current network connection state.

Future<ConnectionStateType> getConnectionState();

Timing

Can be called before or after joining a channel.

Return Values

Current network connection state. See ConnectionStateType.

getCurrentMonotonicTimeInMs

Gets the SDK's current monotonic time.

Future<int> getCurrentMonotonicTimeInMs();

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

Timing

Can be called before or after joining a channel.

Return Values

≥ 0: The method call succeeds and returns the SDK's current monotonic time (milliseconds).
< 0: The method call fails. See Error Codes for details and resolution suggestions.

getEffectCurrentPosition

Gets the playback progress of the specified sound effect file.

Future<int> getEffectCurrentPosition(int soundId);

Note: This method must be called after playEffect.

Parameters

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

Return Values

If the method call succeeds, returns the playback progress of the specified sound effect file (milliseconds).
< 0: The method call fails. See Error Codes for details and resolution suggestions.

getEffectDuration

Gets the total duration of the specified sound effect file.

Future<int> getEffectDuration(String filePath);

Note: This method must be called after joining a channel.

Parameters

filePath

File path:

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

Return Values

If the method call succeeds, returns the duration of the specified sound effect file (milliseconds).
< 0: The method call fails. See Error Codes for details and resolution suggestions.

getEffectsVolume

Gets the playback volume of audio effect files.

Future<int> getEffectsVolume();

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

Note: You need to call this method after playEffect.

Return Values

The volume of the audio effect file.
< 0: The method call fails. See Error Codes for details and resolution suggestions.

getErrorDescription

Gets the warning or error description.

Future<String> getErrorDescription(int code);

Parameters

code: Error code reported by the SDK.

Return Values

Specific error description.

getExtensionProperty

Retrieves detailed information about the extension.

Future<String> getExtensionProperty(
      {required String provider,
      required String extension,
      required String key,
      required int bufLen,
      MediaSourceType type = MediaSourceType.unknownMediaSource});

Timing

Can be called before or after joining a channel.

Parameters

provider: The name of the extension provider.
extension: The name of the extension.
key: The key of the extension property.
type: The media source type of the extension. See MediaSourceType.
bufLen: The maximum length of the extension property JSON string. The maximum value is 512 bytes.

Return Values

If the method call succeeds, returns the extension information.
If the method call fails, returns an empty string.

getFaceShapeAreaOptions

Gets face shaping area options.

Future<FaceShapeAreaOptions> getFaceShapeAreaOptions(
      {required FaceShapeArea shapeArea,
      MediaSourceType type = MediaSourceType.primaryCameraSource});

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

The face shaping area. See FaceShapeArea.

type

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

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

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

If the method call succeeds, returns a FaceShapeAreaOptions object; if it fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

getFaceShapeBeautyOptions

Gets face shaping effect options.

Future<FaceShapeBeautyOptions> getFaceShapeBeautyOptions(
      {MediaSourceType type = MediaSourceType.primaryCameraSource});

Call this method to get the current parameter settings of the face shaping 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 which the effect is applied. See MediaSourceType.

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

When capturing local video using the camera, keep the default value primaryCameraSource.
To use custom captured video, set this parameter to customVideoSource.

Return Values

Returns a FaceShapeBeautyOptions object if the method call succeeds; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

getLocalSpatialAudioEngine

Gets the LocalSpatialAudioEngine object.

LocalSpatialAudioEngine getLocalSpatialAudioEngine();

Note: You must call this method after initializing the RtcEngine object.

Return Values

The LocalSpatialAudioEngine object.

getMediaEngine

Gets the MediaEngine object.

MediaEngine getMediaEngine();

Note: This method must be called after initializing the RtcEngine object.

Return Values

MediaEngine object.

getNativeHandle

Gets the C++ handle of the Native SDK.

Future<int> getNativeHandle();

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

Return Values

Native handle of the SDK engine.

getNetworkType

Gets the local network connection type.

Future<int> getNetworkType();

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

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

Return Values

≥ 0: The method call succeeds and returns the local network connection type.
- 0: Network disconnected.
- 1: Network type is LAN.
- 2: Network type is Wi-Fi (including hotspot).
- 3: Network type is 2G mobile network.
- 4: Network type is 3G mobile network.
- 5: Network type is 4G mobile network.
- 6: Network type is 5G mobile network.
< 0: The method call fails and returns an error code.
- -1: Unknown network connection type.

getNtpWallTimeInMs

Gets the current NTP (Network Time Protocol) time.

Future<int> getNtpWallTimeInMs();

In real-time chorus scenarios, especially when downlink inconsistency occurs 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 and achieve chorus synchronization.

Return Values

Unix timestamp (milliseconds) of the current NTP time.

getScreenCaptureSources

Gets the list of shareable screen and window objects.

Future<List<ScreenCaptureSourceInfo>> getScreenCaptureSources(
    {required Size thumbSize,
    required Size iconSize,
    required bool includeScreen});

Before screen or window sharing, you can call this method to get a list of shareable screen and window objects, allowing users to select a screen or window to share via thumbnails in the list. The list contains important information such as window ID and screen ID. After obtaining the ID, you can call startScreenCaptureByWindowId or startScreenCaptureByDisplayId to start sharing.

Note: This method is only applicable to macOS and Windows.

Parameters

thumbSize

The target size (in pixels) of the thumbnail for the screen or window. 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 size is 400 × 300 and thumbSize is 100 × 100, the actual thumbnail size is 100 × 75. If the target size is larger than the original, the thumbnail is the original image and no scaling is applied.

iconSize

The target size (in pixels) of the icon corresponding to the application. 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 size is 400 × 300 and iconSize is 100 × 100, the actual icon size is 100 × 75. If the target size is larger than the original, the icon is the original image and no scaling is applied.

includeScreen

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

true: SDK returns both screen and window information.
false: SDK returns only window information.

Return Values

An array of ScreenCaptureSourceInfo.

getUserInfoByUid

Gets user information by UID.

Future<UserInfo> getUserInfoByUid(int uid);

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

Timing

Call this method after receiving the onUserInfoUpdated callback.

Related Callbacks

onUserInfoUpdated

Parameters

uid: User ID.

Return Values

The UserInfo object, if the method call succeeds.
null, if the method call fails.

getUserInfoByUserAccount

Gets user information by User Account.

Future<UserInfo> getUserInfoByUserAccount(String userAccount);

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

Timing

Call this method after receiving the onUserInfoUpdated callback.

Related Callbacks

onUserInfoUpdated

Parameters

userAccount: User Account of the user.

Return Values

The UserInfo object, if the method call succeeds.
null, if the method call fails.

getVersion

Gets the SDK version.

Future<SDKBuildInfo> getVersion();

Return Values

SDKBuildInfo object.

getVideoDeviceManager

Gets a VideoDeviceManager object to manage video devices.

VideoDeviceManager getVideoDeviceManager();

Return Values

A VideoDeviceManager object.

getVolumeOfEffect

Gets the playback volume of the specified audio effect file.

Future<int> getVolumeOfEffect(int soundId);

Parameters

soundId: ID of the audio effect file.

Return Values

≥ 0: The method call succeeds and returns the playback volume. The volume range is [0,100]. 100 is the original volume.
< 0: The method call fails. See Error Codes for details and resolution suggestions.

initialize

Initializes the RtcEngine.

Future<void> initialize(RtcEngineContext context);

Note: All interface functions of the RtcEngine class are asynchronous unless otherwise specified. It is recommended to call the interfaces in the same thread. The SDK only supports creating one RtcEngine instance per App.

Timing

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

Parameters

context: Configuration for the RtcEngine instance. See RtcEngineContext.

Return Values

No return value if the method call succeeds; if the method call fails, an AgoraRtcException is thrown, which you need to catch and handle. See Error Codes for details and troubleshooting suggestions.

< 0: Failure.
- -1: General error (not specifically categorized).
- -2: Invalid parameter.
- -7: SDK initialization failed.
- -22: Resource allocation failed. This occurs when the App uses too many resources or system resources are exhausted.
- -101: Invalid App ID.

isCameraAutoExposureFaceModeSupported

Checks whether the device supports auto exposure.

Future<bool> isCameraAutoExposureFaceModeSupported();

Return Values

true: The device supports auto exposure.
false: The device does not support auto exposure.

isCameraAutoFocusFaceModeSupported

Checks whether the device supports face auto-focus.

Future<bool> isCameraAutoFocusFaceModeSupported();

Note:

This method is only applicable to Android and iOS.
Call this method after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as localVideoStreamStateCapturing (1).

Return Values

true: The device supports face auto-focus.
false: The device does not support face auto-focus.

isCameraCenterStageSupported

Checks whether the camera supports Center Stage.

Future<bool> isCameraCenterStageSupported();

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

Note: This method is applicable to iOS and macOS only.

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

true: The current camera supports Center Stage.
false: The current camera does not support Center Stage.

isCameraExposurePositionSupported

Checks whether the device supports manual exposure.

Future<bool> isCameraExposurePositionSupported();

Note:

This method is only applicable to Android and iOS.
Call this method after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as localVideoStreamStateCapturing (1).

Return Values

true: The device supports manual exposure.
false: The device does not support manual exposure.

isCameraExposureSupported

Checks whether the current camera supports exposure adjustment.

Future<bool> isCameraExposureSupported();

Note:

This method is only applicable to Android and iOS.
You must call this method after the SDK triggers the onLocalVideoStateChanged callback and the local video state returns localVideoStreamStateCapturing (1).
It is recommended to call this method to check whether the current camera supports exposure adjustment before calling setCameraExposureFactor to adjust the exposure factor.
This method checks whether the currently used camera supports exposure adjustment, i.e., the camera specified when calling setCameraCapturerConfiguration.

Return Values

true: The method call succeeds.
false: The method call fails. See Error Codes for details and resolution suggestions.

isCameraFaceDetectSupported

Checks whether the device camera supports face detection.

Future<bool> isCameraFaceDetectSupported();

Note:

This method is only applicable to Android and iOS.
You must call this method after the SDK triggers the onLocalVideoStateChanged callback and the local video state returns localVideoStreamStateCapturing (1).

Return Values

true: The device camera supports face detection.
false: The device camera does not support face detection.

isCameraFocusSupported

Checks whether the device supports manual focus.

Future<bool> isCameraFocusSupported();

Note:

This method is only applicable to Android and iOS.
You must call this method after the SDK triggers the onLocalVideoStateChanged callback and the local video state returns localVideoStreamStateCapturing (1).

Return Values

true: The device supports manual focus.
false: The device does not support manual focus.

isCameraTorchSupported

Checks whether the device supports keeping the flashlight on.

Future<bool> isCameraTorchSupported();

Note:

This method is only applicable to Android and iOS.
You must call this method after the SDK triggers the onLocalVideoStateChanged callback and the local video state returns localVideoStreamStateCapturing (1).
Typically, the app enables the front camera by default. If your front camera does not support keeping the flashlight on, this method returns false. If you want to check whether the rear camera supports keeping the flashlight on, you need to call switchCamera to switch the camera before using this method.
On iPads with system version 15, even if isCameraTorchSupported returns true, due to system issues, you may still fail to turn on the flashlight using setCameraTorchOn.

Return Values

true: The device supports keeping the flashlight on.
false: The device does not support keeping the flashlight on.

isCameraZoomSupported

Checks whether the device supports camera zoom.

Future<bool> isCameraZoomSupported();

Note: This method is only applicable to Android and iOS.

Timing

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

Return Values

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

isFeatureAvailableOnDevice

Checks whether the device supports the specified advanced feature.

Future<bool> isFeatureAvailableOnDevice(FeatureType type);

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

true: The device supports the specified advanced feature.
false: The device does not support the specified advanced feature.

isSpeakerphoneEnabled

Checks whether the speakerphone is enabled.

Future<bool> isSpeakerphoneEnabled();

Note: This method is applicable only on Android and iOS.

Timing

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

Return Values

true: The speakerphone is enabled, and audio is routed to the speaker.
false: The speakerphone is not enabled, and audio is routed to a non-speaker device (earpiece, headset, etc.).

joinChannel

Sets media options and joins a channel.

Future<void> joinChannel(
      {required String token,
      required String channelId,
      required int uid,
      required ChannelMediaOptions options});

This method allows you to set media options when joining a channel, such as whether to publish audio and video streams in the channel. By default, users subscribe to all remote audio and video streams in the channel, which may incur usage and affect billing. If you want to unsubscribe, you can do so by setting the options parameter or using the corresponding mute methods.

Note:

This method only supports joining one channel at a time.
Apps with different App IDs cannot communicate with each other.
Before joining a channel, ensure that the App ID used to generate the Token is the same as the one used in the initialize method to initialize the engine. Otherwise, joining the channel using the Token will fail.

Timing

Call this method after initialize.

Related Callbacks

After successfully calling this method to join a channel, the following callbacks are triggered:

Locally: onJoinChannelSuccess and onConnectionStateChanged.
Remotely: In communication scenarios and for hosts in live streaming scenarios, onUserJoined is triggered.

If the network connection is poor and the client loses connection with the Agora server, the SDK automatically attempts to reconnect. Upon successful reconnection, the onRejoinChannelSuccess callback is triggered locally.

Parameters

token

The 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 only enables debug mode (i.e., uses APP ID for authentication), you can join a channel without providing a Token. You will automatically leave the channel after 24 hours.
If you need to join multiple channels at once or frequently switch between channels, Agora recommends using a wildcard Token to avoid requesting a new Token from your server for each new channel. See Wildcard Token.

channelId

The 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 must be a string of up to 64 bytes. Supported character set (89 characters):

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 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 must remember and maintain this return value; the SDK does not maintain it.

options

Channel media options. See ChannelMediaOptions.

Return Values

When the method call succeeds, there is no return value; when it fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

< 0: Method call failed. See Error Codes for details and resolution suggestions.
- -2: Invalid parameters. For example, an invalid Token, uid is not an integer, or ChannelMediaOptions contains invalid values. Provide valid parameters and rejoin the channel.
- -3: RtcEngine initialization failed. Reinitialize the RtcEngine object.
- -7: RtcEngine not initialized. Initialize the RtcEngine object before calling this method.
- -8: Internal state error in RtcEngine. Possible cause: startEchoTest was called but stopEchoTest was not called before joining the channel. Call stopEchoTest before this method.
- -17: Join channel rejected. Possible cause: user is already in the channel. Use onConnectionStateChanged to check if the user is in the channel. Do not call this method again unless you receive connectionStateDisconnected(1).
- -102: Invalid channel name. Provide a valid channelId and rejoin the channel.
- -121: Invalid user ID. Provide a valid uid and rejoin the channel.

joinChannelWithUserAccount

Joins a channel using a User Account and token, and sets channel media options.

Future<void> joinChannelWithUserAccount(
    {required String token,
    required String channelId,
    required String userAccount,
    ChannelMediaOptions? options});

Before calling this method, if you have not registered a User Account using registerLocalUserAccount, the SDK automatically creates one for you when you join a channel using this method. To reduce the time it takes to join a channel, register the account first using registerLocalUserAccount, then call this method. After a user successfully joins a channel, they automatically subscribe to all audio and video streams from other users in the channel, which incurs usage and affects billing. To unsubscribe, call the corresponding mute methods.

Note: To ensure communication quality, make sure that all users in the channel use the same type of identifier, either UID or User Account. If users join the channel via the Web SDK, ensure they use the same identifier type.

This method only supports joining one channel at a time.
Apps with different App IDs cannot communicate with each other.
Before joining a channel, make sure the App ID used to generate the token is the same as the one used in the initialize method. Otherwise, joining the channel with the token will fail.

Timing

This method must be called after initialize.

Related Callbacks

After successfully joining a channel, the following callbacks are triggered:

Local: onLocalUserRegistered, onJoinChannelSuccess, and onConnectionStateChanged.
Remote: In communication scenarios, when a user joins, onUserJoined and onUserInfoUpdated are triggered on the remote end.

Parameters

token

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

Note:

(Recommended) If your project has enabled secure mode (using APP ID + Token for authentication), this parameter is required.
If your project is in debug mode only (using APP ID for authentication), you can join the channel without a token. The user will automatically leave the channel 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 your server every time. See Use Wildcard Token.

userAccount

The User Account of the user. This parameter identifies the user in the real-time audio/video interaction channel. You must manage and ensure the uniqueness of each User Account 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 letters a–z
26 uppercase letters A–Z
10 digits 0–9
Space
"!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

options

Channel media configuration options. See ChannelMediaOptions.

Return Values

When the method call succeeds, there is no return value; when it fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

< 0: The method call fails. See Error Codes for details and resolution suggestions.
- -2: Invalid parameter. For example, an illegal token is used, the uid parameter is not an integer, or a member value of ChannelMediaOptions is invalid. Provide valid parameters and rejoin the channel.
- -3: RtcEngine initialization failed. Reinitialize the RtcEngine object.
- -7: RtcEngine not initialized. Initialize RtcEngine before calling this method.
- -8: Internal state error of RtcEngine. This may occur if you call this method after starting an echo test with startEchoTest but before stopping it with stopEchoTest. Call stopEchoTest before this method.
- -17: Join channel rejected. Possibly because the user is already in the channel. Use the onConnectionStateChanged callback to check if the user is in the channel. Do not call this method again unless the state is connectionStateDisconnected (1).
- -102: Invalid channel name. Provide a valid channelId and rejoin the channel.
- -121: Invalid user ID. Provide a valid uid and rejoin the channel.

joinChannelWithUserAccountEx

Joins a channel using a User Account and token, and sets channel media options.

Future<void> joinChannelWithUserAccountEx(
    {required String token,
    required String channelId,
    required String userAccount,
    required ChannelMediaOptions options});

Before calling this method, if you have not registered a User Account using registerLocalUserAccount, the SDK automatically creates one for you when you join a channel using this method. To reduce the time it takes to join a channel, register the account first using registerLocalUserAccount, then call this method. After a user successfully joins a channel, they automatically subscribe to all audio and video streams from other users in the channel, which incurs usage and affects billing. To unsubscribe, set the options parameter or call the corresponding mute methods.

Note: To ensure communication quality, make sure that all users in the channel use the same type of identifier, either UID or User Account. If users join the channel via the Web SDK, ensure they use the same identifier type.

This method only supports joining one channel at a time.
Apps with different App IDs cannot communicate with each other.
Before joining a channel, make sure the App ID used to generate the token is the same as the one used in the initialize method. Otherwise, joining the channel with the token will fail.

Timing

This method must be called after initialize.

Related Callbacks

After successfully joining a channel, the following callbacks are triggered:

Local: onLocalUserRegistered, onJoinChannelSuccess, and onConnectionStateChanged.
Remote: In communication scenarios, when a user joins, onUserJoined and onUserInfoUpdated are triggered on the remote end.

Parameters

token

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

Note:

(Recommended) If your project has enabled secure mode (using APP ID + Token for authentication), this parameter is required.
If your project is in debug mode only (using APP ID for authentication), you can join the channel without a token. The user will automatically leave the channel 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 your server every time. See Use Wildcard Token.

userAccount

The User Account of the user. This parameter identifies the user in the real-time audio/video interaction channel. You must manage and ensure the uniqueness of each User Account 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 letters a–z
26 uppercase letters A–Z
10 digits 0–9
Space
"!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

options

Channel media configuration options. See ChannelMediaOptions.

Return Values

When the method call succeeds, there is no return value; when it fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

< 0: The method call fails. See Error Codes for details and resolution suggestions.
- -2: Invalid parameter. For example, an illegal token is used, the uid parameter is not an integer, or a member value of ChannelMediaOptions is invalid. Provide valid parameters and rejoin the channel.
- -3: RtcEngine initialization failed. Reinitialize the RtcEngine object.
- -7: RtcEngine not initialized. Initialize RtcEngine before calling this method.
- -8: Internal state error of RtcEngine. This may occur if you call this method after starting an echo test with startEchoTest but before stopping it with stopEchoTest. Call stopEchoTest before this method.
- -17: Join channel rejected. Possibly because the user is already in the channel. Use the onConnectionStateChanged callback to check if the user is in the channel. Do not call this method again unless the state is connectionStateDisconnected (1).
- -102: Invalid channel name. Provide a valid channelId and rejoin the channel.
- -121: Invalid user ID. Provide a valid uid and rejoin the channel.

leaveChannel

Sets channel options and leaves the channel.

Future<void> leaveChannel({LeaveChannelOptions? options});

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

Note: This method is asynchronous. When the method returns, the user has not actually left the channel yet. If you call the release method immediately after this method, the SDK will not trigger the onLeaveChannel callback.

Timing

This method must be called after joining a channel.

Related Callbacks

After successfully calling this method to leave the channel, the following callbacks are triggered:

Local: onLeaveChannel.
Remote: When a host leaves the channel, the remote end triggers the onUserOffline callback.

Parameters

options: Options for leaving the channel. See LeaveChannelOptions.

Return Values

When the method call succeeds, there is no return value; when it fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

loadExtensionProvider

Loads an extension.

Future<void> loadExtensionProvider(
      {required String path, bool unloadAfterUse = false});

This method adds external SDK extensions (such as marketplace or SDK extension plugins) into the SDK.

Note: To load multiple extensions, call this method multiple times. This method is available only on Windows and Android.

Timing

Call this method immediately after initializing RtcEngine.

Parameters

path

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

unloadAfterUse

Whether to automatically unload the extension after use:

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

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

muteAllRemoteAudioStreams

Stops or resumes subscribing to all remote users' audio streams.

Future<void> muteAllRemoteAudioStreams(bool mute);

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

Note: By default, the SDK subscribes to all remote users' audio streams when joining a channel. To change this behavior, you can set autoSubscribeAudio to false when calling joinChannel, so that no audio streams are subscribed to upon joining. If you call enableAudio or disableAudio after this method, the later call takes effect.

Timing

You must call this method 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

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

muteAllRemoteVideoStreams

Stops or resumes subscribing to all remote users' video streams.

Future<void> muteAllRemoteVideoStreams(bool mute);

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

Note: By default, the SDK subscribes to all remote users' video streams when joining a channel. To change this behavior, you can set autoSubscribeVideo to false when calling joinChannel, so that no video streams are subscribed to upon joining. If you call enableVideo or disableVideo after this method, the later call takes effect.

Timing

You must call this method 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

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

muteLocalAudioStream

Stops or resumes publishing the local audio stream.

Future<void> muteLocalAudioStream(bool mute);

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

Related Callbacks

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

Parameters

mute

Whether to stop publishing the local audio stream.

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

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

muteLocalVideoStream

Stops or resumes publishing the local video stream.

Future<void> muteLocalVideoStream(bool mute);

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 video capture and thus stop publishing, this method responds faster.

Timing

Can be called before or after joining a channel.

Related Callbacks

After this method is called successfully, the local user receives the onVideoPublishStateChanged callback; remote users receive 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

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

muteRecordingSignal

Mutes the recording signal.

Future<void> muteRecordingSignal(bool mute);

If you have already called adjustRecordingSignalVolume to adjust the volume of the recorded audio signal, calling this method and setting it to true will cause the SDK to:

Record the adjusted volume.
Mute the recording signal.

When you call this method again with false, the recording signal will be restored to the volume recorded by the SDK before muting.

Timing

Can be called before or after joining a channel.

Parameters

mute

true: Mute.
false: (default) Original volume.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

muteRemoteAudioStream

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

Future<void> muteRemoteAudioStream({required int uid, required bool mute});

Timing

You need to call this method after joining a channel.

Related Callbacks

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

Parameters

uid

The user ID of the specified user.

mute

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

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

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

muteRemoteVideoStream

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

Future<void> muteRemoteVideoStream({required int uid, required bool mute});

Timing

You need to 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 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

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

< 0: Method call failed. See Error Codes for details and resolution suggestions.

pauseAllChannelMediaRelay

Pauses media stream relay to all destination channels.

Future<void> pauseAllChannelMediaRelay();

After starting media stream relay across channels, if you want to pause relaying to all destination channels, you can call this method. To resume relaying, call resumeAllChannelMediaRelay.

Note: You must call this method after calling startOrUpdateChannelMediaRelay to start media stream relay across channels.

Return Values

When the method call succeeds, there is no return value; when it fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

pauseAllEffects

Pauses playback of all audio effect files.

Future<void> pauseAllEffects();

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

pauseAudioMixing

Pauses the playback of the music file.

Future<void> pauseAudioMixing();

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

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

pauseEffect

Pauses playback of the audio effect file.

Future<void> pauseEffect(int soundId);

Parameters

soundId: ID of the audio effect. Each audio effect has a unique ID.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

playAllEffects

Plays all audio effect files.

Future<void> playAllEffects(
    {required int loopCount,
    required double pitch,
    required double pan,
    required int gain,
    bool publish = false});

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

Number of times the audio effect file is looped:

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

pitch

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

pan

Spatial position of the audio effect. Value range is [-1.0,1.0]:

-1.0: Audio effect appears on the left.
0: Audio effect appears in the center.
1.0: Audio effect appears on the right.

gain

Volume of the audio effect. Value 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 local users can hear it.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

playEffect

Plays the specified local or online audio effect file.

Future<void> playEffect(
    {required int soundId,
    required String filePath,
    required int loopCount,
    required double pitch,
    required double pan,
    required int gain,
    bool publish = false,
    int startPos = 0});

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 to play no more than 3 audio effect files at the same time.

Note: If you need to play an online audio effect file, Agora recommends caching the file to the local device first, then calling preloadEffect to preload the cached file into memory, and finally calling this method to play the effect. Otherwise, playback failure or no sound may occur due to timeout or failure in loading the online file.

Timing

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

Related Callbacks

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

Parameters

soundId

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

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

filePath

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

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

loopCount

Number of times the audio effect is looped.

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

pitch

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

pan

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

-1.0: Audio effect appears on the left
0.0: Audio effect appears in the center
1.0: Audio effect appears on the right

gain

Volume of the audio effect. Value 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 local users can hear it.

startPos

Playback position of the audio effect file in milliseconds.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

< 0: The method call fails. See Error Codes for details and resolution suggestions.

preloadChannel

Preloads a channel using token, channelId, and uid.

Future<void> preloadChannel(
      {required String token, required String channelId, required int uid});

Calling this method reduces the time it takes for an audience member to join a channel when switching channels frequently, thereby shortening the time to hear the first audio frame and see the first video frame from the host, and improving the audience's video experience. If the current channel has already been successfully preloaded, and the audience leaves and rejoins the channel, as long as the Token passed during preloading is still valid, re-preloading is not required.

Note: Preloading failure does not affect normal channel joining later, nor does it increase the time to join the channel.

When calling this method, ensure the user role is set to audience and the audio scenario is not chorus (audioScenarioChorus), otherwise preloading will not take effect.
Ensure the channel name, user ID, and Token passed during preloading are the same as those used when joining the channel later; otherwise, preloading will not take effect.
Currently, a single RtcEngine instance supports preloading up to 20 channels. If this limit is exceeded, only the latest 20 preloaded channels take effect.

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 pass in a new Token for preloading in different ways:

For a single channel: call this method again with the new Token.
For 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 set to 0. See Wildcard Token.
- If you use different Tokens: call this method and pass in 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 communication. Under the same App ID, users who enter the same channel name will join the same channel for audio and video interaction. 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 need to 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 store and manage this return value, as the SDK does not maintain it.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

< 0: The method call fails. See Error Codes for details and resolution suggestions.
- -7: The RtcEngine object is not initialized. You need to initialize the RtcEngine object before calling this method.
- -102: Invalid channel name. You need to enter a valid channel name and rejoin the channel.

preloadChannelWithUserAccount

Preloads a channel using token, channelId, and userAccount.

Future<void> preloadChannelWithUserAccount(
      {required String token,
      required String channelId,
      required String userAccount});

Calling this method reduces the time it takes for an audience member to join a channel when switching channels frequently, thereby shortening the time to hear the first audio frame and see the first video frame from the host, and improving the audience's video experience. If the current channel has already been successfully preloaded, and the audience leaves and rejoins the channel, as long as the Token passed during preloading is still valid, re-preloading is not required.

Note: Preloading failure does not affect normal channel joining later, nor does it increase the time to join the channel.

When calling this method, ensure the user role is set to audience and the audio scenario is not chorus (audioScenarioChorus), otherwise preloading will not take effect.
Ensure the channel name, user account, and Token passed during preloading are the same as those used when joining the channel later; otherwise, preloading will not take effect.
Currently, a single RtcEngine instance supports preloading up to 20 channels. If this limit is exceeded, only the latest 20 preloaded channels take effect.

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 pass in a new Token for preloading in different ways:

For a single channel: call this method again with the new Token.
For 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 set to 0. See Wildcard Token.
- If you use different Tokens: call this method and pass in 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 communication. Under the same App ID, users who enter the same channel name will join the same channel for audio and video interaction. 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
"!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

userAccount

User account. This parameter identifies the user in the real-time audio and video channel. You need to 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 letters a-z
26 uppercase letters A-Z
10 digits 0-9
Space
"!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

< 0: The method call fails. See Error Codes for details and resolution suggestions.
- -2: Invalid parameter. For example, the user account is empty. You need to enter a valid parameter and rejoin the channel.
- -7: The RtcEngine object is not initialized. You need to initialize the RtcEngine object before calling this method.
- -102: Invalid channel name. You need to enter a valid channel name and rejoin the channel.

preloadEffect

Loads the audio effect file into memory.

Future<void> preloadEffect(
    {required int soundId, required String filePath, int startPos = 0});

To ensure smooth communication, pay attention to the size of the preloaded audio effect file. Supported formats for preloading audio files are listed in What audio formats are supported by the RTC SDK.

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 URL of online files, URI of local files, absolute paths, or paths 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 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 file, in milliseconds.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

queryCameraFocalLengthCapability

Queries the focal length capabilities supported by the camera.

Future<List<FocalLengthInfo>> queryCameraFocalLengthCapability();

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 camera's focal length configuration to achieve the best capturing effect.

Note: This method is only applicable to Android and iOS.

Return Values

Returns an array of FocalLengthInfo objects, which contain the camera's orientation and focal length type.

queryCodecCapability

Queries the video codec capabilities supported by the SDK.

Future<List<CodecCapInfo>> queryCodecCapability(int size);

Parameters

size: The size of CodecCapInfo.

Return Values

If the call succeeds, returns an array of CodecCapInfo, indicating the SDK's video encoding capabilities.
If the call times out, modify your call logic and avoid calling this method on the main thread.

queryDeviceScore

Queries the device score level.

Future<int> queryDeviceScore();

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

When the method call succeeds, it returns a value in the range [0,100], indicating the score level of the current device. A higher value indicates better device capability. Most devices score between 60 and 100. When the method call fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly.

< 0: The method call fails.

queryScreenCaptureCapability

Queries the maximum frame rate supported by the device during screen sharing.

Future<int> queryScreenCaptureCapability();

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

If the method call succeeds, returns the maximum frame rate supported by the device. See ScreenCaptureFramerateCapability.
<0: The method call fails. See Error Codes for details and resolution suggestions.

rate

Rates a call.

Future<void> rate(
    {required String callId,
    required int rating,
    required String description});

Note: This method must be called after the user leaves the channel.

Parameters

callId: The call ID. You can obtain this parameter by calling getCallId.
rating: The rating for the call, from 1 (lowest) to 5 (highest).
description: A description of the call. The length must be less than 800 bytes.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

registerAudioEncodedFrameObserver

Registers the audio encoded frame observer.

void registerAudioEncodedFrameObserver(
      {required AudioEncodedFrameObserverConfig config,
      required AudioEncodedFrameObserver observer});

Note:

Call this method after joining a channel.
Since this method and startAudioRecording both configure audio content and quality, it is not recommended to use them together. Otherwise, only the one called later takes effect.

Parameters

config: Configuration for the encoded audio observer. See AudioEncodedFrameObserverConfig.
observer: Observer for encoded audio. See AudioEncodedFrameObserver.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

registerAudioSpectrumObserver

Registers an audio spectrum observer.

void registerAudioSpectrumObserver(AudioSpectrumObserver observer);

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

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

Parameters

observer: Audio spectrum observer. See AudioSpectrumObserver.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

registerExtension

Registers an extension.

Future<void> registerExtension(
      {required String provider,
      required String extension,
      MediaSourceType type = MediaSourceType.unknownMediaSource});

For external SDK extensions (such as marketplace or SDK extension plugins), after loading the extension, you need to call this method to register it. Internal SDK extensions (those included in the SDK package) are automatically loaded and registered after initializing RtcEngine, so you do not need to call this method.

Note:

To register multiple extensions, call this method multiple times.
The order in which different extensions process data in the SDK is determined by the registration order. That is, extensions registered earlier process data first.

Timing

It is recommended to call this method after initializing RtcEngine and before joining a channel.
For video-related extensions (such as beauty filters), you need to call this method before enabling the video module (enableVideo/enableLocalVideo).
Before calling this method, you must call loadExtensionProvider to load the extension.

Parameters

provider: The name of the extension provider.
extension: The name of the extension.
type: The media source type of the extension. See MediaSourceType.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

registerLocalUserAccount

Registers the local user account.

Future<void> registerLocalUserAccount(
    {required String appId, required String userAccount});

This method registers a user account for the local user. After successful registration, the user account can be used to identify the local user, who can then join a channel using it. This method is optional. If you want users to join a channel using a user account, you can implement it in either of the following ways:

Call registerLocalUserAccount to register the account first, then call joinChannelWithUserAccount to join the channel. This can reduce the time to join the channel.
Directly call joinChannelWithUserAccount to join the channel.

Note:

Ensure the userAccount set in this method is unique within the channel.
To ensure communication quality, make sure to use the same type of user identifier within a channel. That is, use either UID or user account consistently within the same channel. If users join the channel via Web SDK, ensure they use the same identifier type.

Related Callbacks

After successfully calling this method, the local onLocalUserRegistered callback is triggered, reporting the local user's UID and user account.

Parameters

appId

The App ID of your project registered in the console.

userAccount

User account. This parameter identifies the user in the real-time audio and video channel. You need to 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 letters a-z
26 uppercase letters A-Z
10 digits 0-9
Space
"!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

registerMediaMetadataObserver

Registers a media metadata observer to receive or send metadata.

void registerMediaMetadataObserver(
      {required MetadataObserver observer, required MetadataType type});

You need to implement the MetadataObserver 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 scenarios such as sending shopping links, e-coupons, and online quizzes.

Note: Call this method before joinChannel.

Parameters

observer: The metadata observer. See MetadataObserver.
type: The metadata type. Currently only videoMetadata is supported.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

< 0: The method call fails. See Error Codes for details and resolution suggestions.

release

Destroys the RtcEngine object.

Future<void> release({bool sync = false});

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 for other operations. This method is suitable for such cases. After calling this method, you can no longer use other SDK methods and callbacks. To use real-time audio and video communication again, you must call createAgoraRtcEngine and initialize again to create a new RtcEngine object.

Note:

This method is a synchronous call. You must wait for the RtcEngine resources to be released before performing other operations (e.g., creating a new RtcEngine object), so it is recommended to call this method in a sub-thread to avoid blocking the main thread.
It is not recommended to call release within SDK callbacks, as the SDK must wait for the callback to return before recycling related object resources, which may cause a deadlock.

Parameters

sync

Whether this method is a synchronous call:

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

unregisterEventHandler

Removes the specified callback event.

void unregisterEventHandler(RtcEngineEventHandler eventHandler);

This method removes all previously added callback events.

Parameters

eventHandler: The callback event to be removed. See RtcEngineEventHandler.

Return Values

When the method call succeeds, there is no return value; when it fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

removeVideoWatermark

Removes the watermark image from the local video.

Future<void> removeVideoWatermark(String id);

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: ID of the watermark to remove. This value must match the ID used when adding the watermark.

Return Values

0: The method call succeeds.
< 0: The method call fails.

renewToken

Updates the token.

Future<void> renewToken(String token);

This method is used to update the token. The token expires after a certain period, at which point the SDK cannot establish a connection with the server.

Timing

In any of the following situations, Agora recommends that you regenerate a token on your server and call this method to pass in the new token:

When you receive the onTokenPrivilegeWillExpire callback indicating the token is about to expire;
When you receive the onRequestToken callback indicating the token has expired;
When you receive the onConnectionStateChanged callback reporting connectionChangedTokenExpired (9);

Parameters

token: The newly generated token.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

resumeAllChannelMediaRelay

Resumes media stream relay to all destination channels.

Future<void> resumeAllChannelMediaRelay();

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

Note: This method must be called after pauseAllChannelMediaRelay.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

< 0: Method call failed. See Error Codes for details and resolution suggestions.
- -5: This method call was rejected. There is no paused cross-channel media stream relay.

resumeAllEffects

Resumes playback of all audio effect files.

Future<void> resumeAllEffects();

After you call pauseAllEffects to pause all audio effects, you can call this method to resume playback.

Timing

This method must be called after pauseAllEffects.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

resumeAudioMixing

Resumes the playback of the music file.

Future<void> resumeAudioMixing();

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

Timing

You must call this method after joining a channel.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

resumeEffect

Resumes playback of the specified audio effect file.

Future<void> resumeEffect(int soundId);

Parameters

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

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

selectAudioTrack

Specifies the playback audio track of the current music file.

Future<void> selectAudioTrack(int index);

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

Note:

For supported audio file formats, see What audio formats does the RTC SDK support?.
You must call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged(audioMixingStatePlaying) callback.

Parameters

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

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

sendCustomReportMessage

Sends a custom report message.

Future<void> sendCustomReportMessage(
    {required String id,
    required String category,
    required String event,
    required String label,
    required int value});

Agora provides a custom data reporting and analytics service. 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.

sendMetaData

Sends media metadata.

Future<void> sendMetaData(
    {required Metadata metadata, required VideoSourceType sourceType});

If the metadata is sent successfully, the receiver receives the onMetadataReceived callback.

Parameters

metadata: The media metadata. See Metadata.
sourceType: The type of video source. See VideoSourceType.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

< 0: The method call fails. See Error Codes for details and resolution suggestions.

sendStreamMessage

Sends a data stream.

Future<void> sendStreamMessage(
    {required int streamId, required Uint8List data, required int length});

After calling createDataStream, you can call this method to send data stream messages to all users in the channel. The SDK imposes the following restrictions on this method:

Each client in the channel can have up to 5 data channels simultaneously, with a total sending bitrate limit of 30 KB/s shared among all channels.
Each data channel can send up to 60 packets per second, with each packet limited to 1 KB.

After this method is successfully called, the remote side triggers the onStreamMessage callback, through which remote users can receive the stream message. If the call fails, the remote side triggers the onStreamMessageError callback.

Note: If you need a more comprehensive solution for low-latency, high-concurrency, and scalable real-time messaging and state synchronization, we recommend using Real-time Messaging.

This method must be called after joining the channel and after calling createDataStream to create the data channel.
This method is only applicable to broadcaster users.

Parameters

streamId: The data stream ID. You can get it through createDataStream.
data: The data to be sent.
length: The length of the data.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setAINSMode

Enables or disables AI noise reduction and sets the noise reduction mode.

Future<void> setAINSMode(
      {required bool enabled, required AudioAinsMode mode});

You can call this method to enable the AI noise reduction feature. This feature intelligently detects and reduces various stationary and non-stationary background noises while maintaining voice quality, making human voices clearer. Stationary noise refers to noise with consistent frequency over time, such as:

TV noise
Air conditioner noise
Factory machine noise

Non-stationary noise refers to noise that changes rapidly over time, such as:

Thunder
Explosions
Cracking sounds

Note:

This method depends on the AI noise reduction dynamic library. Deleting this library will prevent the feature from working properly. For the name of the AI noise reduction library, see Plugin List.
Currently, it is not recommended to enable this feature on devices running Android 6.0 or lower.

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 AI noise reduction:

true: Enable AI noise reduction.
false: (default) Disable AI noise reduction.

mode

Noise reduction mode. See AudioAinsMode.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setAdvancedAudioOptions

Sets advanced audio options.

Future<void> setAdvancedAudioOptions(AdvancedAudioOptions options);

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

Note: You need to call this method before joinChannel, enableAudio, and enableLocalAudio.

Parameters

options: Advanced audio options. See AdvancedAudioOptions.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setAudioEffectParameters

Sets the parameters for SDK preset voice effects.

Future<void> setAudioEffectParameters(
  {required AudioEffectPreset preset,
  required int param1,
  required int param2});

You can call this method to configure the following settings for the local user who is sending the stream:

3D voice effect: Set the surround cycle of the 3D voice effect.
Pitch correction effect: Set the base scale and main pitch of the pitch correction effect. To allow users to adjust the pitch correction effect themselves, it is recommended to bind the base scale and main pitch configuration options to the UI elements of your app.

After setting, all users in the channel can hear the effect.To achieve better voice effects, it is recommended that you perform the following operations before calling this method:

Call setAudioScenario to set the audio scenario to high-quality, i.e., audioScenarioGameStreaming(3).
Call setAudioProfile to set the profile to audioProfileMusicHighQuality(4) or audioProfileMusicHighQualityStereo(5).

Note:

This method can be called before and after joining a channel.
Do not set the profile parameter of setAudioProfile to audioProfileSpeechStandard(1) or audioProfileIot(6), otherwise this method will not take effect.
This method provides the best processing effect for voice. It is not recommended to use this method to process audio data that contains music.
After calling setAudioEffectParameters, it is not recommended to call the following methods, otherwise the effect set by setAudioEffectParameters will be overridden:
This method depends on the voice beautifier dynamic library libagora_audio_beauty_extension.dll. Deleting this library will cause the feature to not function properly.

Parameters

preset

SDK preset effects. The following settings 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 this enum setting is invalid.
- After enabling 3D voice, users need to 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 indicates the surround cycle of the 3D voice effect. The range is [1,60] in seconds. The default value is 10, meaning the voice surrounds 360 degrees in 10 seconds.
If preset is set to pitchCorrection, then param1 indicates the base scale of the pitch correction effect:
- 1: (Default) Natural major.
- 2: Natural minor.
- 3: Japanese scale.

param2

If preset is set to roomAcoustics3dVoice, you need to set param2 to 0.
If preset is set to pitchCorrection, then param2 indicates the main pitch of the pitch correction effect:
- 1: A
- 2: A#
- 3: B
- 4: (Default) C
- 5: C#
- 6: D
- 7: D#
- 8: E
- 9: F
- 10: F#
- 11: G
- 12: G#

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setAudioEffectPreset

Sets the SDK preset voice effect.

Future<void> setAudioEffectPreset(AudioEffectPreset preset);

You can call this method to set the SDK preset voice effect for the local user who is sending the stream, without changing the gender characteristics of the original voice. After setting the effect, all users in the channel can hear it.

Note:

Do not set the profile parameter of setAudioProfile to audioProfileSpeechStandard(1) or audioProfileIot(6), otherwise this method will not take effect.
If you call setAudioEffectPreset and set an enum other than roomAcoustics3dVoice or pitchCorrection, do not call setAudioEffectParameters, otherwise the effect set by setAudioEffectPreset will be overridden.
After calling setAudioEffectPreset, it is not recommended to call the following methods, otherwise the effect set by setAudioEffectPreset will be overridden:
This method depends on the voice beautifier dynamic library libagora_audio_beauty_extension.dll. Deleting this library will cause the feature to not function properly.

Timing

Can be called before and after joining a channel. To achieve better voice effects, it is recommended that you perform the following operations before calling this method:

Call setAudioScenario to set the audio scenario to high-quality, i.e., audioScenarioGameStreaming(3).
Call setAudioProfile to set the profile to audioProfileMusicHighQuality(4) or audioProfileMusicHighQualityStereo(5).

Parameters

preset: Preset effect options. See AudioEffectPreset.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setAudioMixingDualMonoMode

Sets the channel mode of the current audio file.

Future<void> setAudioMixingDualMonoMode(AudioMixingDualMonoMode mode);

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.

Note: This method applies to stereo audio files only.

Scenario

In KTV scenarios, the left channel of an audio file stores the accompaniment, and the right channel stores the original vocals. You can configure as follows:

To hear only the accompaniment, set the channel mode to left.
To hear both accompaniment and vocals, set the channel mode to mixed.

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 the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setAudioMixingPitch

Adjusts the pitch of the locally played music file.

Future<void> setAudioMixingPitch(int pitch);

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

Timing

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

Parameters

pitch: Adjusts the pitch of the locally played music file in semitone steps. The default value is 0, which means no pitch adjustment. The valid range is [-12, 12]. Each step represents a semitone difference. The greater the absolute value, the more the pitch is raised or lowered.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setAudioMixingPlaybackSpeed

Sets the playback speed of the current music file.

Future<void> setAudioMixingPlaybackSpeed(int speed);

You must call this method after startAudioMixing and after 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

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly.

setAudioMixingPosition

Sets the playback position of the music file.

Future<void> setAudioMixingPosition(int pos);

This method sets the playback position of the audio file, allowing you to play the file based on actual needs instead of playing it from start to finish.

Timing

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

Parameters

pos: Integer. The position on the progress bar, in milliseconds.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setAudioProfile

Sets the audio encoding profile and audio scenario.

Future<void> setAudioProfile(
    {required AudioProfileType profile,
    AudioScenarioType scenario = AudioScenarioType.audioScenarioDefault});

Note: Due to iOS system limitations, some audio routes cannot be recognized in communication volume mode. Therefore, if you need to use an external sound card, it is recommended to set the audio scenario to the high-quality scenario audioScenarioGameStreaming(3). In this scenario, the SDK switches to media volume to avoid the issue.

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

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

Parameters

profile: Audio encoding profile, including sample rate, bitrate, encoding mode, and number of channels. See AudioProfileType.
scenario: Audio scenario. The device volume type varies under different audio scenarios. See AudioScenarioType.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setAudioScenario

Sets the audio scenario.

Future<void> setAudioScenario(AudioScenarioType scenario);

Note: Due to iOS system limitations, some audio routes cannot be recognized in communication volume mode. Therefore, if you need to use an external sound card, it is recommended to set the audio scenario to the high-quality scenario audioScenarioGameStreaming(3). In this scenario, the SDK switches to media volume to avoid the issue.

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

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

Parameters

scenario: Audio scenario. The device volume type varies under different audio scenarios. See AudioScenarioType.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setAudioSessionOperationRestriction

Sets the SDK's permission to operate the Audio Session.

Future<void> setAudioSessionOperationRestriction(
      AudioSessionOperationRestriction restriction);

By default, both the SDK and the App have permission 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 permission. This method can be called before or after joining a channel. Once called, the restriction takes effect when the SDK needs to modify the Audio Session.

Note:

This method is applicable to iOS only.
This method does not restrict the App's permission to operate the Audio Session.

Parameters

restriction: SDK's permission to operate the Audio Session. See AudioSessionOperationRestriction. This parameter is a bit mask, where each bit corresponds to a permission.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setBeautyEffectOptions

Sets beauty effect options.

Future<void> setBeautyEffectOptions(
    {required bool enabled,
    required BeautyOptions options,
    MediaSourceType type = MediaSourceType.primaryCameraSource});

Enables local beauty effects and sets the beauty effect options.

Note:

This method depends on the video enhancement dynamic library libagora_clear_vision_extension.dll. Deleting this library will cause the feature to fail to start.
This feature requires high device performance. When calling this method, the SDK automatically checks the current device capabilities.

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

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

When capturing local video using the camera, keep the default value primaryCameraSource.
To use custom captured video, set this parameter to customVideoSource.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setCameraAutoExposureFaceModeEnabled

Enables or disables the auto exposure feature.

Future<void> setCameraAutoExposureFaceModeEnabled(bool enabled);

Parameters

enabled

Whether to enable auto exposure:

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

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setCameraAutoFocusFaceModeEnabled

Sets whether to enable face auto-focus.

Future<void> setCameraAutoFocusFaceModeEnabled(bool enabled);

By default, the SDK disables face auto-focus on Android and enables it on iOS. If you want to manually set face auto-focus, call this method.

Note: This method is applicable to Android and iOS only.

Timing

You must call this method after the SDK triggers the onLocalVideoStateChanged callback and the local video state is localVideoStreamStateCapturing (1).

Parameters

enabled

Whether to enable face auto-focus:

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

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setCameraCapturerConfiguration

Sets the camera capture configuration.

Future<void> setCameraCapturerConfiguration(
      CameraCapturerConfiguration config);

Note: Before adjusting the camera focal length configuration, it is recommended to call queryCameraFocalLengthCapability to check the supported focal length capabilities of the device, and then configure accordingly. Due to limitations of some Android devices, the configuration may not take effect even if you set the focal length type based on the result of queryCameraFocalLengthCapability.

Timing

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

Parameters

config: Camera capture configuration. See CameraCapturerConfiguration.
Note: You do not need to set the deviceId parameter in this method.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

< 0: Method call failed. See Error Codes for details and resolution suggestions.

setCameraDeviceOrientation

Sets the rotation angle of the captured video.

Future<void> setCameraDeviceOrientation(
    {required VideoSourceType type, required VideoOrientation orientation});

Note:

This method is applicable to Windows only.
You must call this method after enableVideo. The setting takes effect after the camera is successfully turned on, i.e., after the SDK triggers the onLocalVideoStateChanged callback and the local video state is localVideoStreamStateCapturing (1).
When the video capture device does not have a gravity sensor, you can call this method to manually adjust the rotation angle of the captured video frame.

Parameters

type: Video source type. See VideoSourceType.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setCameraExposureFactor

Sets the exposure factor of the current camera.

Future<void> setCameraExposureFactor(double factor);

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

Note:

This method is applicable to Android and iOS only.
You must call this method after enableVideo. The setting takes effect after the camera is successfully turned on, i.e., after the SDK triggers the onLocalVideoStateChanged callback and the local video state is localVideoStreamStateCapturing (1).
It is recommended to call isCameraExposureSupported before using this method to check whether the current camera supports adjusting the exposure factor.
When you call this method, it sets the exposure factor for the currently used camera, which is the one specified in setCameraCapturerConfiguration.

Parameters

factor: Exposure factor of the camera. The default value is 0, which means using the camera's default exposure level. The larger the value, the higher the exposure. When the video image is overexposed, you can reduce the exposure factor; when the 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

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setCameraExposurePosition

Sets the manual exposure position.

Future<void> setCameraExposurePosition(
    {required double positionXinView, required double positionYinView});

Note:

This method is applicable to Android and iOS only.
You must call this method after enableVideo. The setting takes effect after the camera is successfully turned on, i.e., after the SDK triggers the onLocalVideoStateChanged callback and the local video state is localVideoStreamStateCapturing (1).
After this method is successfully called, the local client triggers the onCameraExposureAreaChanged callback.

Parameters

positionXinView: The horizontal coordinate of the touch point relative to the view.
positionYinView: The vertical coordinate of the touch point relative to the view.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setCameraFocusPositionInPreview

Sets the manual focus position and triggers focusing.

Future<void> setCameraFocusPositionInPreview(
    {required double positionX, required double positionY});

Note:

This method is applicable to Android and iOS only.
You must call this method after enableVideo. The setting takes effect after the camera is successfully turned on, i.e., after the SDK triggers the onLocalVideoStateChanged callback and the local video state is localVideoStreamStateCapturing (1).
After this method is successfully called, the local client triggers the onCameraFocusAreaChanged callback.

Parameters

positionX: The horizontal coordinate of the touch point relative to the view.
positionY: The vertical coordinate of the touch point relative to the view.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setCameraStabilizationMode

Sets the camera stabilization mode.

Future<void> setCameraStabilizationMode(CameraStabilizationMode mode);

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

Note: This method is for iOS only.

Camera stabilization only takes effect when the video resolution is greater than 1280 × 720.
The higher the stabilization level, the narrower the camera's field of view and the greater the camera delay. To ensure user experience, it is recommended to set the mode parameter to cameraStabilizationModeLevel1.

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

Parameters

mode: Camera stabilization mode. See CameraStabilizationMode.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly.

setCameraTorchOn

Sets whether to turn on the flashlight.

Future<void> setCameraTorchOn(bool isOn);

Note:

This method is applicable to Android and iOS only.
You must call this method after enableVideo. The setting takes effect after the camera is successfully turned on, i.e., after the SDK triggers the onLocalVideoStateChanged callback and the local video state is localVideoStreamStateCapturing (1).

Parameters

isOn

Whether to turn on the flashlight:

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

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setCameraZoomFactor

Sets the camera zoom factor.

Future<void> setCameraZoomFactor(double factor);

Some iOS devices use a composite rear camera consisting 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 capability, you can call setCameraCapturerConfiguration to set cameraFocalLengthType to cameraFocalLengthDefault (0) (standard lens), and 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.

Note:

This method is applicable only to Android and iOS.
You must call this method after enableVideo. The setting takes effect after the camera is successfully started, that is, when the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as localVideoStreamStateCapturing (1).

Parameters

factor: Camera zoom factor. For devices that do not support ultra-wide-angle, the value ranges from 1.0 to the maximum zoom factor; for devices that support ultra-wide-angle, the value ranges from 0.5 to the maximum zoom factor. You can call getCameraMaxZoomFactor to get the maximum zoom factor supported by the device.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

Failure: return value < 0.

setChannelProfile

Sets the channel profile.

Future<void> setChannelProfile(ChannelProfileType profile);

You can call this method to set the channel profile. The SDK adopts different optimization strategies for different use cases, such as prioritizing video quality in live streaming scenarios. The default channel profile after SDK initialization is live streaming.

Note: To ensure real-time audio and video quality, all users in the same channel must use the same channel profile.

Timing

This method must be called before joining a channel.

Parameters

profile: Channel profile. See ChannelProfileType.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

< 0: Failure. See Error Codes for details and resolution suggestions.
- -2: Invalid parameter.
- -7: SDK not initialized.

setClientRole

Sets the user role and audience latency level in live streaming.

Future<void> setClientRole(
    {required ClientRoleType role, ClientRoleOptions? options});

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 privileges at the SDK level, such as whether they can publish streams.

Note: When the user role is set to broadcaster, the audience latency level only supports audienceLatencyLevelUltraLowLatency (ultra-low latency). If you call this method before joining a channel and set role to BROADCASTER, the local user will not receive the onClientRoleChanged callback.

Timing

This method can be called either before or after joining a channel. If you call this method before joining a channel to set the user role to broadcaster and set local video properties using setupLocalVideo, the local video preview will start automatically when the user joins the channel. If you call this method after joining a channel to switch user roles, upon success, the SDK automatically calls muteLocalAudioStream and muteLocalVideoStream to update the publishing state of audio and video streams.

Related Callbacks

If you successfully call this method to switch user roles after joining a channel, the SDK triggers the following callbacks:

Locally triggers the onClientRoleChanged callback. This callback is also triggered if you call this method before joining a channel and set role to AUDIENCE.
Remotely triggers the onUserJoined or onUserOffline callback.

If you fail to switch user roles after joining a channel, the SDK triggers onClientRoleChangeFailed to report the reason for the failure and the current user role.

Parameters

role: User role. See ClientRoleType.
Note: Users with the audience role cannot publish audio or video streams in the channel. When publishing in live streaming, make sure the user role is switched to broadcaster.
options: User-specific settings, including user level. See ClientRoleOptions.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setCloudProxy

Sets the cloud proxy service.

Future<void> setCloudProxy(CloudProxyType proxyType);

When the user's network is restricted by a firewall, you need to add the IP and port 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 an already set Force UDP or Force TCP cloud proxy, call setCloudProxy(noneProxy). To change the cloud proxy type, first call setCloudProxy(noneProxy), then call setCloudProxy with the desired proxyType value.

Note:

It is recommended to call this method outside the channel.
If the user is in an intranet firewall environment, the features of CDN streaming and cross-channel media relay are not available when using Force UDP cloud proxy.
When using Force UDP cloud proxy, the startAudioMixing method cannot play online audio files via HTTP. CDN streaming and cross-channel media relay use cloud proxy over TCP.

Parameters

proxyType: The cloud proxy type. See CloudProxyType. This parameter is required. If you do not assign a value, the SDK will report an error.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setColorEnhanceOptions

Sets the color enhancement feature.

Future<void> setColorEnhanceOptions(
      {required bool enabled,
      required ColorEnhanceOptions options,
      MediaSourceType type = MediaSourceType.primaryCameraSource});

The video captured by the camera may suffer from color distortion. The color enhancement feature can intelligently adjust video characteristics such as saturation and contrast to improve color richness and accuracy, making the video more vivid. You can call this method to enable color enhancement and set the enhancement effect.

Note:

Call this method after enableVideo.
Color enhancement requires a certain level of device performance. After enabling it, if the device overheats or encounters other issues, it is recommended to lower the enhancement level or disable the feature.
This method depends on the video enhancement dynamic library libagora_clear_vision_extension.dll. Deleting this library will cause the feature to fail to start.

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 enhancement effect. See ColorEnhanceOptions.

type

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

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

When capturing local video using the camera, keep the default value primaryCameraSource.
To use custom captured video, set this parameter to customVideoSource.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setDefaultAudioRouteToSpeakerphone

Sets the default audio route.

Future<void> setDefaultAudioRouteToSpeakerphone(bool defaultToSpeaker);

Mobile devices typically have two audio routes: the earpiece at the top, which has lower volume, and the speaker at the bottom, which has higher volume. Setting the default audio route determines whether the system uses the earpiece or speaker to play audio when no external device is connected. The system default audio route varies by scenario:

Voice call: Earpiece
Voice live broadcast: Speaker
Video call: Speaker
Video live broadcast: Speaker

Calling this API allows you to change the default audio route described above.

Note: This method is applicable only on Android and iOS platforms. After setting the default audio route using this method, the actual audio route may change depending on the connection of external audio devices (wired or Bluetooth headsets).

Timing

This method must be called before joining a channel. To switch the audio route 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

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setDirectCdnStreamingAudioConfiguration

Sets the audio encoding configuration when the host pushes the stream directly to the CDN.

Future<void> setDirectCdnStreamingAudioConfiguration(
      AudioProfileType profile);

Deprecated: Deprecated since v4.6.2.

This method only takes effect for audio captured by the microphone or custom audio sources, that is, when publishMicrophoneTrack or publishCustomAudioTrack is set to true in DirectCdnStreamingMediaOptions.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setDirectCdnStreamingVideoConfiguration

Sets the video encoding properties when the host pushes streams directly to the CDN.

Future<void> setDirectCdnStreamingVideoConfiguration(
      VideoEncoderConfiguration config);

Deprecated: Deprecated since v4.6.2.

This method only applies to 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 video resolution you set exceeds the range supported by your camera device, the SDK adapts based on your settings and captures, encodes, and streams using the closest resolution with the same aspect ratio as your setting. You can get the actual resolution of the pushed video stream through the onDirectCdnStreamingStats callback.

Parameters

config: Video encoding configuration. See VideoEncoderConfiguration.
Note: When pushing streams directly to the CDN, the SDK currently only supports setting OrientationMode to landscape mode (orientationModeFixedLandscape) or portrait mode (orientationModeFixedPortrait).

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setDualStreamMode

Sets the dual-stream mode on the sender and configures the low-quality video stream.

Future<void> setDualStreamMode(
      {required SimulcastStreamMode mode, SimulcastStreamConfig? streamConfig});

The SDK enables the adaptive low-quality stream mode (autoSimulcastStream) by default on the sender, meaning the sender does not actively send low-quality streams. Receivers with host roles can call setRemoteVideoStreamType to request low-quality streams. After receiving the request, the sender automatically starts sending low-quality streams.

If you want to change this behavior, you can call this method and set mode to disableSimulcastStream (never send low-quality streams) or enableSimulcastStream (always send low-quality streams).
If you want to revert to the default behavior after modification, call this method again and set mode to autoSimulcastStream.

Note: The differences and relationships between this method and enableDualStreamMode are as follows:

Calling this method and setting mode to disableSimulcastStream has the same effect as calling enableDualStreamMode with enabled set to false.
Calling this method and setting mode to enableSimulcastStream has the same effect as calling enableDualStreamMode with enabled set to true.
Both methods can be called before or after joining a channel. If both are used, the settings in the later call take effect.

Parameters

mode: The mode for sending video streams. See SimulcastStreamMode.
streamConfig: The configuration of the low-quality video stream. See SimulcastStreamConfig.
Note: When mode is set to disableSimulcastStream, setting streamConfig has no effect.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setEarMonitoringAudioFrameParameters

Sets the data format for the onEarMonitoringAudioFrame callback.

Future<void> setEarMonitoringAudioFrameParameters(
      {required int sampleRate,
      required int channel,
      required RawAudioFrameOpModeType mode,
      required int samplesPerCall});

This method sets the data format for the onEarMonitoringAudioFrame callback.

Note:

Before calling this method, you need to call enableInEarMonitoring and set includeAudioFilters to earMonitoringFilterBuiltInAudioFilters or earMonitoringFilterNoiseSuppression.
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 sampling interval is no less than 0.01 seconds. The SDK triggers the onEarMonitoringAudioFrame callback based on this interval.

Parameters

sampleRate

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

channel

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

1: Mono.
2: Stereo.

mode

Usage mode of the audio frame. See RawAudioFrameOpModeType.

samplesPerCall

Number of audio samples reported in onEarMonitoringAudioFrame, typically 1024 in applications like push streaming.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

< 0: The method call fails. See Error Codes for details and resolution suggestions.

setEffectPosition

Sets the playback position of the specified audio effect file.

Future<void> setEffectPosition({required int soundId, required int pos});

After successful setting, the local audio effect file will start playing from the specified position.

Note: This method must be called after playEffect.

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

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setEffectsVolume

Sets the playback volume of audio effect files.

Future<void> setEffectsVolume(int volume);

Timing

This method must be called after playEffect.

Parameters

volume: Playback volume. The range is [0,100]. The default value is 100, representing the original volume.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setEnableSpeakerphone

Enables or disables speakerphone playback.

Future<void> setEnableSpeakerphone(bool speakerOn);

For the SDK's default audio routes in different scenarios.

Note: This method is applicable only on Android and iOS platforms.

This method only sets the audio route used by the user in the current channel and does not affect the SDK's default audio route. If the user leaves the current channel and joins a new one, the SDK's default audio route will still be used.
If the user uses external audio playback devices such as Bluetooth or wired headsets, this method has no effect. Audio will only be played through external devices. If multiple external devices are connected, audio is played through the last connected device.

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

This method must be called 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 is routed to the speaker.
false: Disable. Audio is routed to the earpiece.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setExtensionProperty

Sets an extension property.

Future<void> setExtensionProperty(
    {required String provider,
    required String extension,
    required String key,
    required String value,
    MediaSourceType type = MediaSourceType.unknownMediaSource});

After enabling the extension, you can call this method to set its properties.

Note: To set properties for multiple extensions, call this method multiple times.

Timing

Call this method after calling enableExtension to enable the extension.

Related Callbacks

After calling this method, the extension may trigger the onExtensionEventWithContext callback. The specific trigger logic depends on the extension itself.

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

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setExtensionProviderProperty

Sets a property for the extension provider.

Future<void> setExtensionProviderProperty(
    {required String provider, required String key, required String value});

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

Note: To set properties for multiple extension providers, call this method multiple times.

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

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setExternalMediaProjection

Sets an external MediaProjection to capture screen video stream.

Future<void> setExternalMediaProjection(int mediaProjection);

After this method is successfully called, the external MediaProjection you set will replace the one applied by the SDK to capture the screen video stream. When screen sharing is stopped or RtcEngine is destroyed, the SDK automatically releases the MediaProjection.

Note: This method is applicable to Android only. You must obtain MediaProjection permission before calling this method.

Scenario

If you are capable of obtaining MediaProjection yourself, you can use your own MediaProjection to replace the one obtained by the SDK. Here are two usage scenarios:

On customized system devices, you can avoid system pop-ups (which require user permission for screen capture) and directly start screen capture.
In a screen sharing process with one or more subprocesses, this avoids errors caused by creating objects in subprocesses that may lead to capture failure.

Timing

This method must be called before startScreenCapture.

Parameters

mediaProjection: A MediaProjection object used to capture screen video stream.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setExternalRemoteEglContext

Sets the EGL context for rendering remote video streams.

Future<void> setExternalRemoteEglContext(int eglContext);

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

Note: This method is for Android only.

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 the channel.

Parameters

eglContext: The EGL context object used for rendering remote video streams.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setFaceShapeAreaOptions

Sets face shaping area options and specifies the media source.

Future<void> setFaceShapeAreaOptions(
      {required FaceShapeAreaOptions options,
      MediaSourceType type = MediaSourceType.primaryCameraSource});

If the preset face shaping effects set with setFaceShapeBeautyOptions do not meet expectations, you can use this method to configure face shaping area options and fine-tune individual facial areas for more refined results.

Note: Face shaping is a value-added service. See Billing Strategy for pricing details.

On Android, this method is only supported on Android 4.4 and above.
This method depends on the video enhancement dynamic library libagora_clear_vision_extension.dll. Deleting this library will cause the feature to fail to start.
This feature requires high device performance. When calling this method, the SDK automatically checks the current device capabilities.

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

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

When capturing local video using the camera, keep the default value primaryCameraSource.
To use custom captured video, set this parameter to customVideoSource.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setFaceShapeBeautyOptions

Sets face shaping effect options and specifies the media source.

Future<void> setFaceShapeBeautyOptions(
      {required bool enabled,
      required FaceShapeBeautyOptions options,
      MediaSourceType type = MediaSourceType.primaryCameraSource});

Call this method to enhance facial features such as slimming the face, enlarging eyes, slimming the nose, etc., using preset parameters in one go. You can also adjust the overall intensity of the effect.

Note: Face shaping is a value-added service. See Billing Strategy for pricing details.

On Android, this method is only supported on Android 4.4 and above.
This method depends on the video enhancement dynamic library libagora_clear_vision_extension.dll. Deleting this library will cause the feature to fail to start.
This feature requires high device performance. When calling this method, the SDK automatically checks the current device capabilities.

Timing

Call this method after enableVideo.

Parameters

enabled

Whether to enable the face shaping effect:

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, this parameter only supports the following two settings:

When capturing local video using the camera, keep the default value primaryCameraSource.
To use custom captured video, set this parameter to customVideoSource.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setFilterEffectOptions

Sets filter effect options and specifies the media source.

Future<void> setFilterEffectOptions(
      {required bool enabled,
      required FilterEffectOptions options,
      MediaSourceType type = MediaSourceType.primaryCameraSource});

Note:

This method depends on the video enhancement dynamic library libagora_clear_vision_extension.dll. If this library is removed, the feature cannot be enabled properly.
This feature has high performance requirements. When this method is called, the SDK automatically checks the current device capabilities.

Timing

Call this method after enableVideo.

Parameters

enabled

Whether to enable the filter effect:

true: Enables the filter feature.
false: (Default) Disables the filter feature.

options

Filter options. See FilterEffectOptions.

type

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

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

When using the camera to capture local video, keep the default value primaryCameraSource.
If you want to use custom captured video, set this parameter to customVideoSource.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setHeadphoneEQParameters

Sets the low-frequency and high-frequency parameters of the headphone equalizer.

Future<void> setHeadphoneEQParameters(
      {required int lowGain, required int highGain});

In spatial audio scenarios, if the preset headphone equalizer effect set by calling setHeadphoneEQPreset does not meet expectations, you can call this method to further adjust the headphone equalizer effect.

Parameters

lowGain: Low-frequency parameter of the headphone equalizer. Value range is [-10,10]. The higher the value, the deeper the sound.
highGain: High-frequency parameter of the headphone equalizer. Value range is [-10,10]. The higher the value, the sharper the sound.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setHeadphoneEQPreset

Sets the preset headphone equalizer effect.

Future<void> setHeadphoneEQPreset(HeadphoneEqualizerPreset preset);

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.

Note: If your headphones already provide a good equalizing effect, calling this method may not significantly improve the experience and may even degrade it.

Parameters

preset: Preset headphone equalizer effect. See HeadphoneEqualizerPreset.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setInEarMonitoringVolume

Sets the in-ear monitoring volume.

Future<void> setInEarMonitoringVolume(int volume);

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 overflow protection.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setLocalRenderMode

Updates the local view display mode.

Future<void> setLocalRenderMode(
    {required RenderModeType renderMode,
    VideoMirrorModeType mirrorMode =
        VideoMirrorModeType.videoMirrorModeAuto});

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 seen by the local user and does not affect the published video.

Note: This method only takes effect for the first camera (primaryCameraSource). In scenarios with custom video capture or other types of video sources, you need to use the setupLocalVideo method instead.

Timing

Call this method after initializing the local view using the setupLocalVideo method.
You can call this method multiple times during a call to update the display mode of the local user view.

Parameters

renderMode: Local view display mode. See RenderModeType.
mirrorMode: Mirror mode for the local view. See VideoMirrorModeType.
Note: If you use the front camera, the local user view mirror mode is enabled by default; if you use the rear camera, the mirror mode is disabled by default.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setLocalRenderTargetFps

Sets the maximum frame rate for local video rendering.

Future<void> setLocalRenderTargetFps(
      {required VideoSourceType sourceType, required int targetFps});

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: Type of video source. See VideoSourceType.
targetFps: Maximum rendering frame rate (fps). Supported values: 1, 7, 10, 15, 24, 30, 60.
Note: You should set this parameter to a rendering frame rate lower than the actual video frame rate; otherwise, the setting will not take effect.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setLocalVideoMirrorMode

Sets the local video mirror mode.

Future<void> setLocalVideoMirrorMode(VideoMirrorModeType mirrorMode);

Deprecated: Deprecated: This method is deprecated.

Parameters

mirrorMode: Local video mirror mode. See VideoMirrorModeType.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setLocalVoiceEqualization

Sets the local voice equalization.

Future<void> setLocalVoiceEqualization(
  {required AudioEqualizationBandFrequency bandFrequency,
  required int bandGain});

Timing

Can be called before and after joining a channel.

Parameters

bandFrequency: Index of the frequency band. The 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 range for each value is [-15,15], with a default value of 0.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setLocalVoiceFormant

Sets the formant ratio to change the voice timbre.

Future<void> setLocalVoiceFormant(double formantRatio);

Formant ratio is a parameter that affects the timbre of the voice. The smaller the formant ratio, the deeper the voice; the larger the value, the sharper the 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 and after joining a channel.

Parameters

formantRatio: Formant ratio. The range is [-1.0, 1.0]. The default value is 0.0, meaning the original timbre is not changed.
Note: Agora recommends using values in the range [-0.4, 0.6]. Effects outside this range may not sound ideal.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setLocalVoicePitch

Sets the local voice pitch.

Future<void> setLocalVoicePitch(double pitch);

Timing

Can be called before and after joining a channel.

Parameters

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

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setLocalVoiceReverb

Sets the local voice reverb effect.

Future<void> setLocalVoiceReverb(
  {required AudioReverbType reverbKey, required int value});

The SDK provides an easier method setAudioEffectPreset to directly apply preset reverb effects such as pop, R&B, KTV, etc.

Note: This method can be called before and after joining a channel.

Parameters

reverbKey: Reverb effect key. This method supports 5 reverb effect keys. See AudioReverbType.
value: The value corresponding to each reverb effect key.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setLogFile

Sets the log file.

Future<void> setLogFile(String filePath);

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

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

Note: The app must ensure that the specified directory exists and is writable.

Timing

You need to call this method immediately after initialize, otherwise the output logs may be incomplete.

Parameters

filePath: The full path of the log file. The log file is encoded in UTF-8.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setLogFileSize

Sets the size of the SDK log file output.

Future<void> setLogFileSize(int fileSizeInKBytes);

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

By default, the SDK generates 5 SDK log files and 5 API call log files with the following rules:

SDK log file names: agorasdk.log, agorasdk.1.log, agorasdk.2.log, agorasdk.3.log, agorasdk.4.log.
API call log file names: agoraapi.log, agoraapi.1.log, agoraapi.2.log, agoraapi.3.log, agoraapi.4.log.
Each SDK log file has a default size of 2,048 KB; API call log files also have a default size of 2,048 KB. All log files are UTF-8 encoded.
The latest logs are always written to agorasdk.log and agoraapi.log.
When agorasdk.log is full, the SDK performs the following operations:
1. Deletes agorasdk.4.log (if exists).
2. Renames agorasdk.3.log to agorasdk.4.log.
3. Renames agorasdk.2.log to agorasdk.3.log.
4. Renames agorasdk.1.log to agorasdk.2.log.
5. Creates a new agorasdk.log file.
The overwrite rule for agoraapi.log is the same as that of agorasdk.log.

Note: This method only sets the size of the agorasdk.log file and does not affect agoraapi.log.

Parameters

fileSizeInKBytes: The size of a single agorasdk.log file in KB. The valid range is [128, 20480], and the default value 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

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setLogFilter

Sets the log output level.

Future<void> setLogFilter(LogFilterType filter);

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. By selecting a level, you can see all logs at that level and above. For example, if you choose logFilterWarn, you will see logs at logFilterCritical, logFilterError, and logFilterWarn levels.

Parameters

filter: Log filter level. See LogFilterType.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setLogLevel

Sets the SDK log output level.

Future<void> setLogLevel(LogLevel level);

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

By selecting a level, you can see the logs at that level.

Parameters

level: Log level. See LogLevel.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setLowlightEnhanceOptions

Sets the low-light enhancement feature.

Future<void> setLowlightEnhanceOptions(
      {required bool enabled,
      required LowlightEnhanceOptions options,
      MediaSourceType type = MediaSourceType.primaryCameraSource});

You can call this method to enable the low-light enhancement feature and configure its effects.

Note:

This method depends on the video enhancement dynamic library libagora_clear_vision_extension.dll. If this library is removed, the feature cannot be enabled properly.
Low-light enhancement has certain performance requirements. After enabling it, if the device experiences severe overheating, it is recommended to lower the enhancement level to a less performance-intensive one or disable the feature.
To achieve high-quality low-light enhancement (lowLightEnhanceLevelHighQuality), you must first call setVideoDenoiserOptions to enable video denoising. The corresponding settings are:
- For automatic mode (LowLightEnhanceAuto), video denoising must be set to high quality (videoDenoiserLevelHighQuality) and automatic mode (videoDenoiserAuto).
- For manual mode (LowLightEnhanceManual), video denoising must be set to high quality (videoDenoiserLevelHighQuality) and manual mode (videoDenoiserManual).

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 the low-light enhancement feature:

true: Enables low-light enhancement.
false: (Default) Disables low-light enhancement.

options

Low-light enhancement options for configuring the effect. See LowlightEnhanceOptions.

type

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

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

When using the camera to capture local video, keep the default value primaryCameraSource.
If you want to use custom captured video, set this parameter to customVideoSource.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setMaxMetadataSize

Sets the maximum size of media metadata.

Future<void> setMaxMetadataSize(int size);

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

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

< 0: Failure. See Error Codes for details and resolution suggestions.

setMixedAudioFrameParameters

Sets the format of the raw audio data after audio mixing for capture and playback.

Future<void> setMixedAudioFrameParameters(
    {required int sampleRate,
    required int channel,
    required int samplesPerCall});

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 sampling interval is no less than 0.01 seconds. The SDK triggers the onMixedAudioFrame 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.

samplesPerCall

The number of audio samples per call. Typically 1024 in scenarios like RTMP streaming.

Return Values

This method returns no value if the call succeeds. If the method call fails, it throws an AgoraRtcException, which you need to catch and handle. See Error Codes for details and troubleshooting suggestions.

setParameters

JSON configuration information for the SDK, used to provide technical preview or customized features.

Future<void> setParameters(String parameters);

Parameters

parameters: Parameters in JSON string format.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setPlaybackAudioFrameBeforeMixingParameters

Sets the format of the raw audio playback data before mixing.

Future<void> setPlaybackAudioFrameBeforeMixingParameters(
      {required int sampleRate, required int channel
      {required int sampleRate, required int samplesPerCall});

The SDK triggers the onPlaybackAudioFrameBeforeMixing callback based on the sampling 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.

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

This method returns no value if the call succeeds. If the method call fails, it throws an AgoraRtcException, which you need to catch and handle. See Error Codes for details and troubleshooting suggestions.

setPlaybackAudioFrameParameters

Sets the format of the raw audio data for playback.

Future<void> setPlaybackAudioFrameParameters(
    {required int sampleRate,
    required int channel,
    required RawAudioFrameOpModeType mode,
    required int samplesPerCall});

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 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 usage mode of the audio frame. See RawAudioFrameOpModeType.

samplesPerCall

The number of audio samples per call. Typically 1024 in scenarios like RTMP streaming.

Return Values

This method returns no value if the call succeeds. If the method call fails, it throws an AgoraRtcException, which you need to catch and handle. See Error Codes for details and troubleshooting suggestions.

< 0: Failure. See Error Codes for details and troubleshooting suggestions.

setRecordingAudioFrameParameters

Sets the format of the raw audio data for capture.

Future<void> setRecordingAudioFrameParameters(
    {required int sampleRate,
    required int channel,
    required RawAudioFrameOpModeType mode,
    required int samplesPerCall});

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 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 usage mode of the audio frame. See RawAudioFrameOpModeType.

samplesPerCall

The number of audio samples per call. Typically 1024 in scenarios like RTMP streaming.

Return Values

This method returns no value if the call succeeds. If the method call fails, it throws an AgoraRtcException, which you need to catch and handle. See Error Codes for details and troubleshooting suggestions.

< 0: Failure. See Error Codes for details and troubleshooting suggestions.

setRemoteDefaultVideoStreamType

Sets the default video stream type to subscribe to.

Future<void> setRemoteDefaultVideoStreamType(VideoStreamType streamType);

Depending on the sender's default behavior and the specific settings of setDualStreamMode, the receiver's call to this method falls into the following cases:

By default, the SDK enables the small stream adaptive mode (autoSimulcastStream) on the sender side, meaning the sender only sends the high-quality stream. Only receivers with host role can call this method to request the low-quality stream. Once the sender receives the request, it starts sending the low-quality stream. All users in the channel can then call this method to switch to low-quality stream subscription mode.
If the sender calls setDualStreamMode and sets mode to disableSimulcastStream (never send low-quality stream), this method has no effect.
If the sender calls setDualStreamMode and sets mode to enableSimulcastStream (always send low-quality stream), both hosts and audience can call this method to switch to low-quality stream subscription mode.

When receiving the low-quality stream, the SDK dynamically adjusts the video stream size according to the video window size to save bandwidth and computing resources. The default aspect ratio of the low-quality stream is consistent with the high-quality stream. Based on the current high-quality stream's aspect ratio, the system automatically assigns resolution, frame rate, and bitrate to the low-quality stream.

Note: If you call both this method and setRemoteVideoStreamType, the SDK uses the settings in setRemoteVideoStreamType.

Timing

This method can only be called before joining a channel. The SDK does not support modifying the default video stream type after joining a channel.

Parameters

streamType: The default video stream type to subscribe to: VideoStreamType.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setRemoteRenderMode

Updates the display mode of the remote view.

Future<void> setRemoteRenderMode(
    {required int uid,
    required RenderModeType renderMode,
    required VideoMirrorModeType mirrorMode});

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

Note:

Call this method after initializing the remote view using the setupRemoteVideo method.
You can call this method multiple times during a call to update the display mode of the remote user view.

Parameters

uid: Remote user ID.
renderMode: Rendering mode of the remote user view. See RenderModeType.
mirrorMode: Mirror mode of the remote user view. See VideoMirrorModeType.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

< 0: Failure. See Error Codes for details and resolution suggestions.

setRemoteRenderTargetFps

Sets the maximum frame rate for remote video rendering.

Future<void> setRemoteRenderTargetFps(int targetFps);

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: You should set this parameter to a rendering frame rate lower than the actual video frame rate; otherwise, the setting will not take effect.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setRemoteSubscribeFallbackOption

Sets the fallback option for subscribed audio and video streams under poor network conditions.

Future<void> setRemoteSubscribeFallbackOption(StreamFallbackOptions option);

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

Parameters

option: Fallback option for the subscribed stream. See StreamFallbackOptions.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setRemoteUserSpatialAudioParams

Sets the spatial audio parameters for a remote user.

Future<void> setRemoteUserSpatialAudioParams(
    {required int uid, required SpatialAudioParams params});

This method must be called after enableSpatialAudio. After successfully setting the spatial audio parameters for the remote user, the local user will perceive spatial sound from the remote user.

Parameters

uid: User ID. Must match the user ID used when joining the channel.
params: Spatial audio parameters. See SpatialAudioParams.

Return Values

When the method call succeeds, there is no return value; when it fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setRemoteVideoStreamType

Sets the video stream type to subscribe to.

Future<void> setRemoteVideoStreamType(
    {required int uid, required VideoStreamType streamType});

Depending on the sender's default behavior and the specific settings of setDualStreamMode, the receiver's call to this method falls into the following cases:

By default, the SDK enables the small stream adaptive mode (autoSimulcastStream) on the sender side, meaning the sender only sends the high-quality stream. Only receivers with host role can call this method to request the low-quality stream. Once the sender receives the request, it starts sending the low-quality stream. All users in the channel can then call this method to switch to low-quality stream subscription mode.
If the sender calls setDualStreamMode and sets mode to disableSimulcastStream (never send low-quality stream), this method has no effect.
If the sender calls setDualStreamMode and sets mode to enableSimulcastStream (always send low-quality stream), both hosts and audience can call this method to switch to low-quality stream subscription mode.

When receiving the low-quality stream, the SDK dynamically adjusts the video stream size according to the video window size to save bandwidth and computing resources. The default aspect ratio of the low-quality stream is consistent with the high-quality stream. Based on the current high-quality stream's aspect ratio, the system automatically assigns resolution, frame rate, and bitrate to the low-quality stream.

Note:

This method can be called before or after joining a channel.
If you call both this method and setRemoteDefaultVideoStreamType, the SDK uses the settings in this method.

Parameters

uid: User ID.
streamType: Video stream type: VideoStreamType.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setRemoteVideoSubscriptionOptions

Sets the subscription options for the remote video stream.

Future<void> setRemoteVideoSubscriptionOptions(
      {required int uid, required VideoSubscriptionOptions options});

When the remote side sends dual streams, you can call this method to set the subscription options for the remote video stream. The SDK's default subscription behavior for remote video streams depends on the type of registered video observer:

If VideoFrameObserver is registered, the SDK subscribes to both raw and encoded data by default.
If VideoEncodedFrameObserver is registered, the SDK subscribes to encoded data only by default.
If both observers are registered, the SDK follows the most recently registered one. For example, if VideoFrameObserver is registered later, the SDK subscribes to both raw and encoded data by default.

If you want to change the above default behavior or set different subscription options for different uids, you can call this method.

Parameters

uid: Remote user ID.
options: Video stream subscription settings. See VideoSubscriptionOptions.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setRemoteVoicePosition

Sets the 2D position of a remote user's voice on the horizontal plane.

Future<void> setRemoteVoicePosition(
    {required int uid, required double pan, required double gain});

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

Note:

You must call enableSoundPositionIndication to enable remote voice stereo before joining the channel.
For the best audio experience, it is recommended to use wired headphones when using this method.
This method must be called after joining the channel.

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 front.
-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 value of 100.0, representing the original volume of the user. The smaller the value, the lower the volume.

Return Values

When the method call succeeds, there is no return value; when it fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setRouteInCommunicationMode

Selects the audio route in communication volume mode.

Future<void> setRouteInCommunicationMode(int route);

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

Note: This method is applicable only on Android. Using this method together with setEnableSpeakerphone may cause conflicts. Agora recommends using setRouteInCommunicationMode alone.

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

setScreenCaptureContentHint

Sets the content type for screen sharing.

Future<void> setScreenCaptureContentHint(VideoContentHint contentHint);

The SDK uses different algorithms to optimize the sharing effect 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 is set.

Note: This method can be called before or after starting screen sharing.

Parameters

contentHint: The content type of the screen sharing. See VideoContentHint.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setScreenCaptureScenario

Sets the screen sharing scenario.

Future<void> setScreenCaptureScenario(ScreenScenarioType screenScenario);

When starting screen or window sharing, you can call this method to set the screen sharing scenario. The SDK adjusts the quality of the shared screen based on the scenario you set.

Note: Agora recommends calling this method before joining a channel.

Parameters

screenScenario: The screen sharing scenario. See ScreenScenarioType.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setSubscribeAudioAllowlist

Sets the audio subscription allowlist.

Future<void> setSubscribeAudioAllowlist(
      {required List<int> uidList, required int uidNumber});

You can call this method to specify the audio streams you want to subscribe to.

Note:

This method can be called before or after joining a channel.
The audio subscription allowlist is not affected by muteRemoteAudioStream, muteAllRemoteAudioStreams, or autoSubscribeAudio in ChannelMediaOptions.
After setting the allowlist, if you leave and rejoin the channel, the allowlist remains effective.
If a user appears in both the audio subscription allowlist and blocklist, only the blocklist takes effect.

Parameters

uidList: The list of user IDs in the audio subscription allowlist. If you want to subscribe to a specific user's audio stream, add that user's ID to this list. If you want to remove a user from the allowlist, call the setSubscribeAudioAllowlist method again and update the list of user IDs so that it no longer contains the uid of the user you want to remove.
uidNumber: The number of users in the allowlist.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setSubscribeAudioBlocklist

Sets the audio subscription blocklist.

Future<void> setSubscribeAudioBlocklist(
      {required List<int> uidList, required int uidNumber});

You can call this method to specify the audio streams you do not want to subscribe to.

Note:

This method can be called before or after joining a channel.
The audio subscription blocklist is not affected by muteRemoteAudioStream, muteAllRemoteAudioStreams, or autoSubscribeAudio in ChannelMediaOptions.
After setting the blocklist, if you leave and rejoin the channel, the blocklist remains effective.
If a user appears in both the audio subscription allowlist and blocklist, only the blocklist takes effect.

Parameters

uidList: The list of user IDs in the audio subscription blocklist. If you want to exclude a specific user's audio stream from being subscribed to, add that user's ID to this list. If you want to remove a user from the blocklist, call the setSubscribeAudioBlocklist method again and update the list of user IDs so that it no longer contains the uid of the user you want to remove.
uidNumber: The number of users in the blocklist.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setSubscribeVideoAllowlist

Sets the video subscription allowlist.

Future<void> setSubscribeVideoAllowlist(
      {required List<int> uidList, required int uidNumber});

You can call this method to specify the video streams you want to subscribe to.

Note:

This method can be called before or after joining a channel.
The video subscription allowlist is not affected by muteRemoteVideoStream, muteAllRemoteVideoStreams, or autoSubscribeVideo in ChannelMediaOptions.
After setting the allowlist, if you leave and rejoin the channel, the allowlist remains effective.
If a user appears in both the audio subscription allowlist and blocklist, only the blocklist takes effect.

Parameters

uidList: The list of user IDs in the video subscription allowlist. If you want to subscribe only to a specific user's video stream, add that user's ID to this list. If you want to remove a user from the allowlist, call the setSubscribeVideoAllowlist method again and update the list of user IDs so that it no longer contains the uid of the user you want to remove.
uidNumber: The number of users in the allowlist.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setSubscribeVideoBlocklist

Sets the video subscription blocklist.

Future<void> setSubscribeVideoBlocklist(
      {required List<int> uidList, required int uidNumber});

You can call this method to specify the video streams you do not want to subscribe to.

Note:

You can call this method either before or after joining a channel.
The video subscription blocklist is not affected by muteRemoteVideoStream, muteAllRemoteVideoStreams, or the autoSubscribeVideo setting in ChannelMediaOptions.
After setting the blocklist, it remains effective even if you leave and rejoin the channel.
If a user is in both the audio subscription blocklist and allowlist, only the blocklist takes effect.

Parameters

uidList: The user ID list of the video subscription blocklist. If you want to unsubscribe from the video stream of a specific publishing user, add that user's ID to this list. If you want to remove a user from the blocklist, you need to call the setSubscribeVideoBlocklist method again to update the user ID list of the subscription blocklist so that it no longer contains the uid of the user you want to remove.
uidNumber: The number of users in the blocklist.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setVideoDenoiserOptions

Sets the video denoising feature.

Future<void> setVideoDenoiserOptions(
      {required bool enabled,
      required VideoDenoiserOptions options,
      MediaSourceType type = MediaSourceType.primaryCameraSource});

You can call this method to enable the video denoising feature and configure its effects.

Note: If the denoising strength provided by this method does not meet your needs, Agora recommends calling the setBeautyEffectOptions method to enable the skin smoothing feature for better video denoising. Recommended BeautyOptions settings for strong denoising:

lighteningContrastLevel: lighteningContrastNormal
lighteningLevel: 0.0
smoothnessLevel: 0.5
rednessLevel: 0.0
sharpnessLevel: 0.1
This method depends on the video enhancement dynamic library libagora_clear_vision_extension.dll. If this library is removed, the feature cannot be enabled properly.
Video denoising has certain performance requirements. After enabling it, if the device experiences severe overheating, it is recommended to lower the denoising level to a less performance-intensive one or disable the feature.

Scenario

Poor lighting and low-end video capture devices can cause noticeable noise in video images, affecting video quality. In real-time interactive scenarios, video noise can also consume bitrate resources during encoding and reduce encoding efficiency.

Timing

Call this method after enableVideo.

Parameters

enabled

Whether to enable the video denoising feature:

true: Enables video denoising.
false: (Default) Disables video denoising.

options

Video denoising options for configuring the effect. See VideoDenoiserOptions.

type

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

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

When using the camera to capture local video, keep the default value primaryCameraSource.
If you want to use custom captured video, set this parameter to customVideoSource.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setVideoEncoderConfiguration

Sets the video encoding attributes.

Future<void> setVideoEncoderConfiguration(VideoEncoderConfiguration config);

Sets the encoding attributes for the local video. Each video encoding profile corresponds to a set of video parameters, including resolution, frame rate, and bitrate.

Note:

The config parameter of this method defines the maximum values achievable under ideal network conditions. If the network condition is poor, the video engine will not use this config to render the local video and will automatically downgrade to a more appropriate video configuration.

Timing

This method can be called before or after joining a channel. If you do not need to reset the video encoding configuration after joining the channel, it is recommended to call this method before enableVideo to speed up the time to render the first frame.

Parameters

config: Video encoding configuration. See VideoEncoderConfiguration.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setVideoScenario

Sets the video application scenario.

Future<void> setVideoScenario(VideoApplicationScenarioType scenarioType);

After successfully calling this method to set the video application scenario, the SDK enables best practice strategies based on the specified scenario, automatically adjusting key performance indicators to optimize video experience quality.

Note: This method must be called before joining a channel.

Parameters

scenarioType

Video application scenario. See VideoApplicationScenarioType. applicationScenarioMeeting (1) is for meeting scenarios. If you have called setDualStreamMode to set the low stream to always off (disableSimulcastStream), the dynamic switching of the low stream does not take effect in meeting scenarios. This enum value applies only to broadcaster vs. broadcaster scenarios. The SDK enables the following strategies for this scenario:

For meeting scenarios that require higher bitrate for the low stream, multiple anti-weak network technologies are automatically enabled to enhance the low stream's resistance to poor networks and ensure smoothness when multiple streams are subscribed.
Real-time monitoring of the number of subscribers to the high stream on the receiving end, and dynamically adjusting the high stream configuration accordingly:
- When no one subscribes to the high stream, the bitrate and frame rate of the high stream are automatically reduced to save uplink bandwidth and consumption.
- When someone subscribes to the high stream, the high stream is reset to the VideoEncoderConfiguration set in the most recent call to setVideoEncoderConfiguration. If no configuration was previously set, the following values are used:
  - Video resolution: 1280 × 720 for desktop; 960 × 540 for mobile
  - Frame rate: 15 fps
  - Bitrate: 1600 Kbps for desktop; 1000 Kbps for mobile
Real-time monitoring of the number of subscribers to the low stream on the receiving end, and dynamically enabling or disabling the low stream:
- When no one subscribes to the low stream, the low stream is automatically disabled to save uplink bandwidth and consumption.
- When someone subscribes to the low stream, it is enabled and reset to the SimulcastStreamConfig set in the most recent call to setDualStreamMode. If no configuration was previously set, the following values are used:
  - Video resolution: 480 × 272
  - Frame rate: 15 fps
  - Bitrate: 500 Kbps

applicationScenario1v1 (2) is for 1v1 video call scenarios. The SDK optimizes strategies for low latency and high-quality experience in this scenario, improving performance such as image quality, first frame rendering time, latency on mid- to low-end devices, and smoothness under poor network conditions.applicationScenarioLiveshow (3) is for showroom live streaming scenarios. The SDK optimizes strategies for fast first frame rendering and high image clarity, such as enabling audio/video frame accelerated rendering by default to improve first frame experience (no need to call enableInstantMediaRendering separately), and enabling B-frames by default to ensure high image quality and transmission efficiency. It also enhances image quality and smoothness under poor network and low-end device conditions.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setVoiceBeautifierParameters

Sets the parameters for the preset voice beautifier effect.

Future<void> setVoiceBeautifierParameters(
  {required VoiceBeautifierPreset preset,
  required int param1,
  required int param2});

Call this method to set the gender characteristics and reverb effect for the singing beautifier. This method applies to the local user who is sending the stream. After setting, all users in the channel can hear the effect. To achieve better vocal quality, it is recommended to do the following before calling this method:

Call setAudioScenario to set the audio scenario to high-quality, i.e., audioScenarioGameStreaming(3).
Call setAudioProfile to set the profile to audioProfileMusicHighQuality(4) or audioProfileMusicHighQualityStereo(5).

Note:

This method can be called before or after joining a channel.
Do not set the profile parameter of setAudioProfile to audioProfileSpeechStandard(1) or audioProfileIot(6), otherwise this method will not take effect.
This method provides optimal processing for vocals and is not recommended for audio data containing music.
After calling setVoiceBeautifierParameters, do not call the following methods, or the effect set by setVoiceBeautifierParameters will be overridden:
This method depends on the voice beautifier dynamic library libagora_audio_beauty_extension.dll. If this library is deleted, the feature will not work properly.

Parameters

preset

The preset audio effect:

SINGING_BEAUTIFIER: Singing beautifier.

param1

Gender characteristics of the singing voice:

1: Male voice.
2: Female voice.

param2

Reverb effect of the singing voice:

1: Reverb effect in a small room.
2: Reverb effect in a large room.
3: Reverb effect in a hall.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setVoiceBeautifierPreset

Sets the preset voice beautifier effect.

Future<void> setVoiceBeautifierPreset(VoiceBeautifierPreset preset);

Call this method to set a preset voice beautifier effect for the local user who is sending the stream. After setting the beautifier effect, all users in the channel can hear it. You can set different beautifier effects for users depending on the scenario.

Note:

Do not set the profile parameter of setAudioProfile to audioProfileSpeechStandard(1) or audioProfileIot(6), otherwise this method will not take effect.
This method provides optimal processing for vocals and is not recommended for audio data containing music.
After calling setVoiceBeautifierPreset, do not call the following methods, or the effect set by setVoiceBeautifierPreset will be overridden:
This method depends on the voice beautifier dynamic library libagora_audio_beauty_extension.dll. If this library is deleted, the feature will not work properly.

Timing

Can be called before or after joining a channel. To achieve better vocal quality, it is recommended to do the following before calling this method:

Call setAudioScenario to set the audio scenario to high-quality, i.e., audioScenarioGameStreaming(3).
Call setAudioProfile to set the profile to audioProfileMusicHighQuality(4) or audioProfileMusicHighQualityStereo(5).

Parameters

preset: The preset voice beautifier option. See VoiceBeautifierPreset.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setVoiceConversionPreset

Sets the preset voice conversion effect.

Future<void> setVoiceConversionPreset(VoiceConversionPreset preset);

Call this method to set a preset voice conversion effect provided by the SDK for the local user who is sending the stream. After setting the effect, all users in the channel can hear it. You can set different voice conversion effects for users depending on the scenario.

Note:

Do not set the profile parameter of setAudioProfile to audioProfileSpeechStandard(1) or audioProfileIot(6), otherwise this method will not take effect.
This method provides optimal processing for vocals and is not recommended for audio data containing music.
After calling setVoiceConversionPreset, do not call the following methods, or the effect set by setVoiceConversionPreset will be overridden:
This method depends on the voice beautifier dynamic library libagora_audio_beauty_extension.dll. If this library is deleted, the feature will not work properly.

Timing

Can be called before or after joining a channel. To achieve better vocal quality, it is recommended to do the following before calling this method:

Call setAudioScenario to set the audio scenario to high-quality, i.e., audioScenarioGameStreaming(3).
Call setAudioProfile to set the profile to audioProfileMusicHighQuality(4) or audioProfileMusicHighQualityStereo(5).

Parameters

preset: The preset voice conversion option: VoiceConversionPreset.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

< 0: Failure. See Error Codes for details and resolution suggestions.

setVolumeOfEffect

Sets the playback volume of the specified audio effect file.

Future<void> setVolumeOfEffect({required int soundId, required int volume});

Timing

This method must be called after playEffect.

Parameters

soundId: The ID of the specified audio effect. Each audio effect has a unique ID.
volume: Playback volume. The range is [0,100]. The default value is 100, representing the original volume.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setupLocalVideo

Initializes the local view.

Future<void> setupLocalVideo(VideoCanvas canvas);

This method initializes the local view and sets the display properties of the local user's video. It only affects the video seen by the local user and does not affect the publishing of the local video. Call this method to bind the display window (view) of the local video stream and set the rendering and mirror mode of the local user view. The binding remains effective after leaving the channel. To stop rendering or unbind, you can call this method and set the view parameter to NULL to stop rendering and clear the rendering cache.

Note:

In Flutter, you do not need to call this method manually. Use AgoraVideoView to render local and remote views.
If you only want to update the rendering or mirror mode of the local user view during a call, use the setLocalRenderMode method.

Scenario

In app development, this method is typically called after initialization to configure local video, and then join the channel. If you want to display multiple preview views in the local video preview, each showing different observation points in the video pipeline, you can call this method multiple times with different view values and set different observation positions for each. For example, set the video source to camera and assign two view values with position set to PositionPostCapturerOrigin and PositionPostCapturer respectively, to simultaneously preview the raw video and the processed video (beauty effects, virtual background, watermark) locally.

Timing

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

Parameters

canvas: Display properties of the local video. See VideoCanvas.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

< 0: Failure. See Error Codes for details and resolution suggestions.

setupRemoteVideo

Initializes the remote user view.

Future<void> setupRemoteVideo(VideoCanvas canvas);

This method binds a remote user to a display view and sets the rendering and mirror mode of the remote user view displayed locally. It only affects the video seen by the local user. You need to specify the remote user's ID when calling this method. Typically, you can set this before joining the channel. If the remote user ID is not available before joining, call this method upon receiving the onUserJoined callback. To unbind a view from a remote user, call this method and set view to null. After leaving the channel, the SDK clears the binding of the remote user view. In mobile custom composite layout scenarios, you can call this method to set a separate view for each sub-video stream of the composite video stream for rendering.

Note:

In Flutter, you do not need to call this method manually. Use AgoraVideoView to render local and remote views.
If you want to update the rendering or mirror mode of the remote user view during a call, use the setRemoteRenderMode method.
When using the recording service, since it does not send video streams, the app does not need to bind a view for it. If the app cannot identify the recording service, bind the remote user view upon receiving the onFirstRemoteVideoDecoded callback.

Parameters

canvas: Display properties of the remote video. See VideoCanvas.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

< 0: Failure. See Error Codes for details and resolution suggestions.

startAudioMixing

Starts playing a music file.

Future<void> startAudioMixing(
      {required String filePath,
      required bool loopback,
      required int cycle,
      int startPos = 0});

See Supported audio file formats for the audio formats supported by this method. If the local music file does not exist, the file format is not supported, or the online music file URL cannot be accessed, the SDK reports audioMixingReasonCanNotOpen.

Note:

Using this method to play short sound effects may cause playback failure. To play sound effects, use playEffect instead.
If you need to call this method multiple times, make sure the interval between calls is more than 500 ms.
When calling this method on Android, note the following:
- Make sure to use a device with Android 4.2 or above and API level no lower than 16.
- If playing online music files, avoid using redirect URLs. Redirect URLs may not work on some devices.
- If calling this method on an emulator, make sure the music file is under the /sdcard/ directory and in MP3 format.

Timing

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

Related Callbacks

After successfully calling this method to play a music file, the local client triggers the onAudioMixingStateChanged(audioMixingStatePlaying) callback. When playback ends, the local client triggers the onAudioMixingStateChanged(audioMixingStateStopped) callback.

Parameters

filePath

File path:

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

loopback

Whether to play the music file locally only:

true: Play the music file locally only. Only the local user can hear the music.
false: Publish the locally played music file to remote users. Both local and remote users can hear the music.

cycle

Number of times to play the music file.

> 0: Number of times to play. For example, 1 means play once.
-1: Play in an infinite loop.

startPos

The playback position of the music file, in milliseconds.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

startCameraCapture

Starts video capture using the camera.

Future<void> startCameraCapture(
      {required VideoSourceType sourceType,
      required CameraCapturerConfiguration config});

Call this method to start multiple camera captures simultaneously by specifying sourceType.

Note: On iOS, to enable multiple camera captures, you must call enableMultiCamera and set enabled to true before calling this method.

Parameters

sourceType

Type of video source. See VideoSourceType.

Note:

iOS devices support up to 2 video streams from camera capture (requires multi-camera or external camera support).
Android devices support up to 4 video streams from camera capture (requires multi-camera or external camera support).
Desktop supports up to 4 video streams from camera capture.

config

Video capture configuration. See CameraCapturerConfiguration.

Note: On iOS, this parameter has no effect. Use the config parameter in enableMultiCamera to configure video capture settings.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

startDirectCdnStreaming

Starts pushing streams directly from the host to the CDN.

Future<void> startDirectCdnStreaming(
      {required DirectCdnStreamingEventHandler eventHandler,
      required String publishUrl,
      required DirectCdnStreamingMediaOptions options});

Deprecated: Deprecated since v4.6.2.

The SDK does not support pushing to the same URL multiple times simultaneously. Media options: The SDK does not support publishCameraTrack and publishCustomVideoTrack being true at the same time, nor does it support publishMicrophoneTrack and publishCustomAudioTrack being true at the same time. You can set the media options (DirectCdnStreamingMediaOptions) based on your scenario. For example: If you want to push custom audio and video streams from the host:

Set publishCustomAudioTrack to true and call pushAudioFrame
Set publishCustomVideoTrack to true and call pushVideoFrame
Ensure publishCameraTrack is false (default)
Ensure publishMicrophoneTrack is false (default)

Since v4.2.0, the SDK supports pushing audio-only streams. You can set publishCustomAudioTrack or publishMicrophoneTrack to true in DirectCdnStreamingMediaOptions, and call pushAudioFrame to push audio-only streams.

Parameters

eventHandler: See onDirectCdnStreamingStateChanged and onDirectCdnStreamingStats.
publishUrl: CDN streaming URL.
options: Media options for the host. See DirectCdnStreamingMediaOptions.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

startEchoTest

Starts an audio and video call loop test.

Future<void> startEchoTest(EchoTestConfiguration config);

To test whether the user's local stream sending and receiving works properly, you can call this method to perform an audio and video call loop test, which checks whether the system's audio and video devices and the user's uplink and downlink networks are functioning correctly. After the test starts, the user needs to speak or face the camera. The audio or video will play back after about 2 seconds. If audio plays back correctly, it indicates that the system audio devices and the user's uplink and downlink networks are working properly; if video plays back correctly, it indicates that the system video devices and the user's uplink and downlink networks are working properly.

Note:

When calling this method in a channel, ensure that no audio or video stream is being published.
After calling this method, you must call stopEchoTest to end the test. Otherwise, the user cannot perform another loop test or join a channel.
In a live broadcast scenario, only hosts can call this method.

Timing

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

Parameters

config: Configuration for the audio and video call loop test. See EchoTestConfiguration.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

startLastmileProbeTest

Starts the last-mile network probe test before a call.

Future<void> startLastmileProbeTest(LastmileProbeConfig config);

Starts the last-mile network probe test to report the uplink and downlink bandwidth, packet loss, jitter, and round-trip time to the user.

Timing

You must call this method before joining a channel, and do not call other methods before receiving the onLastmileQuality and onLastmileProbeResult callbacks. Otherwise, this method may fail due to frequent API calls.

Related Callbacks

After this method is successfully called, the SDK triggers the following two callbacks:

onLastmileQuality, which returns within about 2 seconds depending on the network conditions. This callback provides a score-based assessment of the uplink and downlink network quality, reflecting the user’s subjective experience.
onLastmileProbeResult, which returns within about 30 seconds depending on the network conditions. This callback provides detailed metrics for a more objective evaluation of the uplink and downlink network quality.

Parameters

config: Configuration for the last-mile network probe. See LastmileProbeConfig.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

startLocalAudioMixer

Starts local audio mixing.

Future<void> startLocalAudioMixer(LocalAudioMixerConfiguration config);

This method supports merging multiple local audio streams into a single audio stream. For example: merge audio from the local microphone, media player, sound card, remote audio streams, etc., into one stream and publish it to the channel.

If you want to mix local captured audio, you can set publishMixedAudioTrack in ChannelMediaOptions to true to publish the mixed audio stream to the channel.
If you want to mix remote audio streams, make sure the remote audio streams are published in the channel and subscribed.

Note: To ensure audio quality, it is recommended that no more than 10 audio streams participate in local mixing.

Scenario

You can enable this feature in the following scenarios:

Used with local video compositing, to synchronize and publish the audio streams related to the composed video.
In live streaming, users receive audio streams from the channel, mix them locally, and forward them to another channel.
In education, teachers can mix audio from interactions with students locally and forward the mixed stream to another channel.

Timing

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

Parameters

config: Configuration for local audio mixing. See LocalAudioMixerConfiguration.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

startLocalVideoTranscoder

Starts local video mixing.

Future<void> startLocalVideoTranscoder(LocalTranscoderConfiguration config);

After calling this method, you can merge multiple video streams locally into one stream. For example: merge video streams from camera capture, screen sharing, media player, remote video, video files, images, etc., into one stream, and then publish the mixed video stream to the channel.

Note:

Local video mixing consumes high CPU resources. Agora recommends enabling this feature on high-performance devices.
If you need to mix locally captured video streams, the SDK supports the following combinations:
- On Windows, up to 4 camera video streams + 4 screen sharing streams can be mixed.
- On macOS, up to 4 camera video streams + 1 screen sharing stream can be mixed.
- On Android and iOS, up to 2 camera video streams (requires dual camera support or external camera support) + 1 screen sharing stream can be mixed.
When configuring mixing, ensure that the layer index of the camera video stream capturing the portrait is higher than that of the screen sharing stream, otherwise the portrait will be covered and not appear in the final mixed video stream.

Scenario

You can enable local video mixing in scenarios such as remote meetings, live streaming, and online education. This allows users to conveniently view and manage multiple video feeds, and supports features like picture-in-picture. Here is a typical scenario for implementing picture-in-picture:

Call enableVirtualBackground and set the custom background to BackgroundNone, i.e., separate the portrait from the background in the camera-captured video.
Call startScreenCaptureBySourceType to start capturing the screen sharing video stream.
Call this method and set the portrait video source as one of the sources in the local mixing configuration to achieve picture-in-picture in the final mixed video.

Timing

If you need to mix locally captured video streams, call this method after startCameraCapture or startScreenCaptureBySourceType.
If you want to publish the mixed video stream to the channel, set publishTranscodedVideoTrack to true in ChannelMediaOptions when calling joinChannel or updateChannelMediaOptions.

Related Callbacks

When this method call fails, the SDK triggers the onLocalVideoTranscoderError callback to report the reason for the mixing failure.

Parameters

config

The configuration for local video mixing. See LocalTranscoderConfiguration.

Note:

The maximum resolution for each video stream involved in local mixing is 4096 × 2160. Exceeding this limit will cause mixing to fail.
The maximum resolution of the mixed video stream is 4096 × 2160.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

startMediaRenderingTracing

Starts video frame rendering tracing.

Future<void> startMediaRenderingTracing();

After this method is successfully called, the SDK uses the time of the call as the starting point and reports information related to video frame rendering through the onVideoRenderingTracingResult callback.

Note:

If you do not call this method, the SDK uses the time of calling joinChannel to join the channel as the starting point to begin tracing video rendering events automatically. You can call this method at an appropriate time based on your actual business scenario to customize the tracing.
After leaving the current channel, the SDK automatically resets the starting point to the time of the next channel join.

Scenario

Agora recommends using this method together with UI elements in your app (such as buttons or sliders) to measure the time to first frame rendering from the user's perspective. For example, call this method when the user clicks the Join Channel button, and then use the onVideoRenderingTracingResult callback to obtain the duration of each stage in the video rendering process, allowing you to optimize each stage accordingly.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

startOrUpdateChannelMediaRelay

Starts or updates cross-channel media stream relay.

Future<void> startOrUpdateChannelMediaRelay(
      ChannelMediaRelayConfiguration configuration);

The first successful call to this method starts the cross-channel media stream relay. To relay the stream to multiple destination channels or exit the current relay channels, you can call this method again to add or remove destination channels. This feature supports relaying media streams to up to 6 destination channels. After the method is successfully called, the SDK triggers the onChannelMediaRelayStateChanged callback to report the current state of the cross-channel media stream relay. Common states include:

If the onChannelMediaRelayStateChanged callback reports relayStateRunning (2) and relayOk (0), it indicates that the SDK has started relaying media streams between the source and destination channels.
If the onChannelMediaRelayStateChanged callback reports relayStateFailure (3), it indicates an exception occurred in the cross-channel media stream relay.

Note:

Call this method after successfully joining a channel.
In a live broadcast scenario, only users with the broadcaster role can call this method.
The cross-channel media stream relay feature requires contacting technical support to enable.
This feature does not support String-type UIDs.

Parameters

configuration: Configuration for cross-channel media stream relay. See ChannelMediaRelayConfiguration.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

< 0: Method call failed. See Error Codes for details and resolution suggestions.
- -1: General error (not specifically classified).
- -2: Invalid parameter.
- -8: Internal state error. Possibly because the user role is not broadcaster.

startPreviewWithoutSourceType

Starts video preview.

Future<void> startPreviewWithoutSourceType();

This method starts the local video preview.

Note:

Local preview enables mirror mode by default.
After leaving the channel, local preview remains active. You need to call stopPreview to stop the local preview.

Timing

This method must be called after enableVideo.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

startPreview

Starts video preview and specifies the video source.

Future<void> startPreview(
            {VideoSourceType sourceType = VideoSourceType.videoSourceCameraPrimary});

This method starts the local video preview and specifies the video source to appear in the preview.

Note:

Local preview enables mirror mode by default.
After leaving the channel, local preview remains active. You need to call stopPreview to stop the local preview.

Timing

This method must be called after enableVideo.

Parameters

sourceType: Type of the video source. See VideoSourceType.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

startRhythmPlayer

Starts the virtual metronome.

Future<void> startRhythmPlayer(
      {required String sound1,
      required String sound2,
      required AgoraRhythmPlayerConfig config});

Deprecated: Deprecated since v4.6.2.

After enabling the virtual metronome, the SDK starts playing the specified audio files from the beginning and controls the duration of each file based on the beatsPerMinute you set in AgoraRhythmPlayerConfig. For example, if beatsPerMinute is set to 60, the SDK plays 1 beat per second. If the file duration exceeds the beat duration, the SDK only plays the portion that fits the beat duration.
By default, the sound of the virtual metronome is not published to remote users. If you want remote users to hear it, set publishRhythmPlayerTrack in ChannelMediaOptions to true after calling this method.

Scenario

In music or physical education scenarios, instructors often use a metronome to help students practice with the correct rhythm. A measure consists of strong and weak beats, with the first beat of each measure being the strong beat and the rest being weak beats.

Timing

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

Related Callbacks

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

Parameters

sound1: The absolute path or URL of the strong beat file, including the file name and extension. For example, C:\music\audio.mp4. Supported audio formats: see Supported audio formats for RTC SDK.
sound2: The absolute path or URL of the weak beat file, including the file name and extension. For example, C:\music\audio.mp4. Supported audio formats: see Supported audio formats for RTC SDK.
config: Metronome configuration. See AgoraRhythmPlayerConfig.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

startRtmpStreamWithTranscoding

Starts pushing streams with transcoding settings.

Future<void> startRtmpStreamWithTranscoding(
    {required String url, required LiveTranscoding transcoding});

Agora recommends using the more comprehensive server-side streaming feature. See Implement Server-Side Streaming. You can call this method to push live audio and video streams to a specified CDN streaming URL with transcoding settings. This method can only push to one URL at a time. To push to multiple URLs, you must call this method multiple times. Each stream push represents a streaming task. The default maximum number of concurrent tasks is 200, meaning you can run up to 200 streaming tasks simultaneously under one Agora project. For higher quotas, please contact technical support. After calling this method, the SDK triggers the onRtmpStreamingStateChanged callback locally to report the streaming status.

Note:

Call this method after joining a channel.
Only hosts in live streaming scenarios can call this method.
If the stream fails to start and you want to restart it, you must call stopRtmpStream before calling this method again. Otherwise, the SDK returns the same error code as the previous failure.

Parameters

url: The CDN streaming URL. The format must be RTMP or RTMPS. The character length must not exceed 1024 bytes. Special characters such as Chinese are not supported.
transcoding: The transcoding settings for the CDN stream. See LiveTranscoding.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

startRtmpStreamWithoutTranscoding

Starts pushing streams without transcoding.

Future<void> startRtmpStreamWithoutTranscoding(String url);

Agora recommends using the more comprehensive server-side streaming feature. See Implement Server-Side Streaming. You can call this method to push live audio and video streams to a specified CDN streaming URL. This method can only push to one URL at a time. To push to multiple URLs, you must call this method multiple times. After calling this method, the SDK triggers the onRtmpStreamingStateChanged callback locally to report the streaming status.

Note:

Call this method after joining a channel.
Only hosts in live streaming scenarios can call this method.
If the stream fails to start and you want to restart it, you must call stopRtmpStream before calling this method again. Otherwise, the SDK returns the same error code as the previous failure.

Parameters

url: The CDN streaming URL. The format must be RTMP or RTMPS. The character length must not exceed 1024 bytes. Special characters such as Chinese are not supported.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

startScreenCapture

Starts screen capture.

Future<void> startScreenCapture(ScreenCaptureParameters2 captureParams);

Note:

This method is only applicable to Android and iOS platforms.
Screen sharing stream billing is based on the dimensions value in ScreenVideoParameters:
- If not specified, billing is based on 1280 × 720.
- If specified, billing is based on the provided value.
On iOS, screen sharing is only supported on iOS 12.0 and above.
On iOS, if you use external audio capture instead of SDK audio capture, to prevent screen sharing from stopping when the app goes to the background, it is recommended to implement keep-alive logic.
On iOS, this feature requires high device performance. It is recommended to use it on iPhone X or later.
On iOS, this method depends on the screen sharing dynamic library AgoraReplayKitExtension.xcframework. Removing this library will cause screen sharing to fail.
On Android, if the user does not grant screen capture permission to the app, the SDK reports the onPermissionError(2) callback.
On Android 9 and above, to prevent the app from being killed when it goes to the background, add the foreground service permission android.permission.FOREGROUND_SERVICE in /app/Manifests/AndroidManifest.xml.
Due to Android performance limitations, screen sharing is not supported on Android TV.
Due to Android system limitations, avoid changing the screen sharing stream's video encoding resolution during sharing on Huawei devices to prevent crashes.
Due to Android system limitations, some Xiaomi devices do not support capturing system audio during screen sharing.
To improve the success rate of capturing system audio during screen sharing, it is recommended to call setAudioScenario and set the audio scenario to audioScenarioGameStreaming before joining the channel.

Scenario

In screen sharing scenarios, you need to call this method to start capturing screen video streams. For implementation details, see Screen Sharing.

Timing

This method can be called before or after joining a channel, with the following differences:

If called before joining a channel, then call joinChannel and set publishScreenCaptureVideo to true, screen sharing starts.
If called after joining a channel, then call updateChannelMediaOptions and set publishScreenCaptureVideo to true, screen sharing starts.

Parameters

captureParams: Encoding parameter configuration for screen sharing. See ScreenCaptureParameters2.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

startScreenCaptureBySourceType

Starts screen capture and specifies the video source.

Future<void> startScreenCaptureBySourceType(
      {required VideoSourceType sourceType,
      required ScreenCaptureConfiguration config});

Note: This method is only applicable to macOS and Windows platforms.

If you use this method to start screen capture, you must call stopScreenCaptureBySourceType to stop it.
On Windows, up to 4 screen capture video streams are supported.
On macOS, only 1 screen capture video stream is supported.

Scenario

In screen sharing scenarios, you need to call this method to start capturing screen video streams. The SDK provides several methods to start screen capture. Choose based on your use case:

startScreenCaptureByDisplayId/startScreenCaptureByWindowId: Supports capturing a single screen or window, suitable for sharing a single screen.
startScreenCaptureBySourceType: Supports specifying multiple video sources to capture multiple screen sharing streams, used for local compositing or multi-channel publishing scenarios.

Timing

This method can be called before or after joining a channel, with the following differences:

If called before joining a channel, then call joinChannel and set publishScreenCaptureVideo to true, screen sharing starts.
If called after joining a channel, then call updateChannelMediaOptions and set publishScreenCaptureVideo to true, screen sharing starts.

Parameters

sourceType: The type of video source. See VideoSourceType.
Note: On macOS, only videoSourceScreen (2) is supported for this parameter.
config: Screen capture configuration. See ScreenCaptureConfiguration.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

startScreenCaptureByDisplayId

Starts capturing the video stream of the specified screen.

Future<void> startScreenCaptureByDisplayId(
    {required int displayId,
    required Rectangle regionRect,
    required ScreenCaptureParameters captureParams});

Captures the video stream of a screen or a specific region of the screen.

Note: This method is only applicable to Windows and macOS.

Scenario

In screen sharing scenarios, you need to call this method to start capturing screen video streams. For implementation details, see Screen Sharing.

Timing

This method can be called before or after joining a channel, with the following differences:

If you call this method before joining a channel, then call joinChannel to join the channel and set publishScreenTrack or publishSecondaryScreenTrack to true, screen sharing will start.
If you call this method after joining a channel, then call updateChannelMediaOptions to update the channel media options and set publishScreenTrack or publishSecondaryScreenTrack to true, screen sharing will start.

Parameters

displayId: Specifies the ID of the screen to be shared.
Note: On Windows, if you want to share two screens (primary + secondary) simultaneously, you can set displayId to -1 when calling this method.
regionRect: (Optional) Specifies the position of the region to be shared relative to the entire screen. To share the entire screen, set to nil. See Rectangle.
captureParams: Configuration parameters for screen sharing. The default video encoding resolution is 1920 × 1080, i.e., 2,073,600 pixels. This pixel count is used for billing. See ScreenCaptureParameters.
Note: The video properties of the screen sharing stream only need to be configured through this parameter and are unrelated to setVideoEncoderConfiguration.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

startScreenCaptureByScreenRect

Starts capturing the video stream of a specified screen region.

Future<void> startScreenCaptureByScreenRect(
    {required Rectangle screenRect,
    required Rectangle regionRect,
    required ScreenCaptureParameters captureParams});

Deprecated: Deprecated: This method is deprecated. Use startScreenCaptureByDisplayId instead. If you need to enable screen sharing with external displays, it is strongly recommended to use startScreenCaptureByDisplayId.

Shares a screen or a specific region of the screen. You need to specify the screen region to be shared in this method. This method can be called before or after joining a channel, with the following differences:

If you call this method before joining a channel, then call joinChannel to join the channel and set publishScreenTrack or publishSecondaryScreenTrack to true, screen sharing will start.
If you call this method after joining a channel, then call updateChannelMediaOptions to update the channel media options and set publishScreenTrack or publishSecondaryScreenTrack to true, screen sharing will start.

Note: This method is only applicable to Windows.

Parameters

screenRect: Specifies the position of the screen to be shared relative to the virtual screen.
regionRect: Specifies the position of the region to be shared relative to the entire screen. If not set, the entire screen is shared. See Rectangle. If the specified region exceeds the screen boundary, only the content within the screen is shared. If width or height is set to 0, the entire screen is shared.
captureParams: Configuration parameters for screen sharing encoding. The default resolution is 1920 x 1080, i.e., 2,073,600 pixels. This pixel count is used for billing. See ScreenCaptureParameters.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

startScreenCaptureByWindowId

Starts capturing the video stream of a specified window.

Future<void> startScreenCaptureByWindowId(
    {required int windowId,
    required Rectangle regionRect,
    required ScreenCaptureParameters captureParams});

Shares a window or a specific region of the window. You need to specify the window ID to be shared in this method. This method supports sharing Universal Windows Platform (UWP) application windows. Agora has tested mainstream UWP applications using the latest SDK, with the following results:

OS Version	Application	Compatible Version	Supported
Windows 10	Chrome	76.0.3809.100	No
	Office Word	18.1903.1152.0	Yes
	Office Excel	18.1903.1152.0	No
	Office PPT	18.1903.1152.0	Yes
	WPS Word	11.1.0.9145	Yes
	WPS Excel	11.1.0.9145	Yes
	WPS PPT	11.1.0.9145	Yes
	Built-in Media Player	All versions	Yes
Windows 8	Chrome	All versions	Yes
	Office Word	All versions	Yes
	Office Excel	All versions	Yes
	Office PPT	All versions	Yes
	WPS Word	11.1.0.9098	Yes
	WPS Excel	11.1.0.9098	Yes
	WPS PPT	11.1.0.9098	Yes
	Built-in Media Player	All versions	Yes
Windows 7	Chrome	73.0.3683.103	No
	Office Word	All versions	Yes
	Office Excel	All versions	Yes
	Office PPT	All versions	Yes
	WPS Word	11.1.0.9098	No
	WPS Excel	11.1.0.9098	No
	WPS PPT	11.1.0.9098	Yes
	Built-in Media Player	All versions	No

Note: This method is only applicable to macOS and Windows. The SDK's window sharing feature depends on WGC (Windows Graphics Capture) or GDI (Graphics Device Interface). On systems earlier than Windows 10 2004, WGC cannot disable mouse capture. Therefore, when sharing windows on such systems, captureMouseCursor(false) may not work as expected. See ScreenCaptureParameters.

Scenario

In screen sharing scenarios, you need to call this method to start capturing the screen video stream. For implementation details, see Screen Sharing.

Timing

This method can be called before or after joining a channel, with the following differences:

If you call this method before joining a channel, then call joinChannel to join the channel and set publishScreenTrack or publishSecondaryScreenTrack to true, screen sharing will start.
If you call this method after joining a channel, then call updateChannelMediaOptions to update the channel media options and set publishScreenTrack or publishSecondaryScreenTrack to true, screen sharing will start.

Parameters

windowId: Specifies the ID of the window to be shared.
regionRect: (Optional) Specifies the position of the region to be shared relative to the entire screen. If not set, the entire screen is shared. See Rectangle. If the specified region exceeds the window boundary, only the content within the window is shared. If width or height is 0, the entire window is shared.
captureParams: Configuration parameters for screen sharing. The default resolution is 1920 x 1080, i.e., 2,073,600 pixels. This pixel count is used for billing. See ScreenCaptureParameters.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

stopAllEffects

Stops playback of all audio effect files.

Future<void> stopAllEffects();

If you no longer need to play audio effect files, you can call this method to stop playback. If you only need to pause playback, call pauseAllEffects.

Timing

This method must be called after playEffect.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

stopAudioMixing

Stops playing the music file.

Future<void> stopAudioMixing();

After calling startAudioMixing to play a music file, you can call this method to stop playback. If you only want to pause playback, call pauseAudioMixing instead.

Timing

This method must be called after joining a channel.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

stopCameraCapture

Stops video capture using the camera.

Future<void> stopCameraCapture(VideoSourceType sourceType);

After calling startCameraCapture to start one or more camera capture streams, you can call this method with sourceType to stop one or more camera video captures.

Note: On iOS, to disable multiple camera captures, you must call enableMultiCamera and set enabled to false after calling this method. If you are using local video mixing, stopping video capture from the first camera using this method will interrupt the local video mixing.

Parameters

sourceType: Type of video source. See VideoSourceType.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

stopChannelMediaRelay

Stops cross-channel media stream relay. Once stopped, the broadcaster leaves all destination channels.

Future<void> stopChannelMediaRelay();

After the method is successfully called, the SDK triggers the onChannelMediaRelayStateChanged callback. If it reports relayStateIdle (0) and relayOk (0), it indicates that media stream relay has been stopped.

Note: If the method call fails, the SDK triggers the onChannelMediaRelayStateChanged callback and reports the status code relayErrorServerNoResponse (2) or relayErrorServerConnectionLost (8). You can call the leaveChannel method to leave the channel, and the cross-channel media stream relay will stop automatically.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

< 0: Method call failed. See Error Codes for details and resolution suggestions.
- -5: This method call was rejected. There is no ongoing cross-channel media stream relay.

stopDirectCdnStreaming

Stops pushing streams directly from the host to the CDN.

Future<void> stopDirectCdnStreaming();

Deprecated: Deprecated since v4.6.2.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

stopEchoTest

Stops the audio call loopback test.

Future<void> stopEchoTest();

After calling startEchoTest, you must call this method to end the test. Otherwise, the user cannot perform another audio/video loopback test or join a channel.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

stopEffect

Stops playback of the specified audio effect file.

Future<void> stopEffect(int soundId);

If you no longer need to play a specific audio effect file, you can call this method to stop playback. If you only need to pause playback, call pauseEffect.

Timing

This method must be called after playEffect.

Parameters

soundId: The ID of the specified audio effect file. Each audio effect file has a unique ID.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

stopLastmileProbeTest

Stops the last-mile network probe test before a call.

Future<void> stopLastmileProbeTest();

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

stopLocalAudioMixer

Stops local audio mixing.

Future<void> stopLocalAudioMixer();

After calling startLocalAudioMixer, if you want to stop local audio mixing, call this method.

Timing

This method must be called after startLocalAudioMixer.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

stopLocalVideoTranscoder

Stops local video mixing.

Future<void> stopLocalVideoTranscoder();

After calling startLocalVideoTranscoder, call this method if you want to stop local video mixing.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

stopPreview

Stops video preview.

Future<void> stopPreview(
    {VideoSourceType sourceType = VideoSourceType.videoSourceCameraPrimary});

Scenario

After calling startPreview to start preview, if you want to stop the local video preview, call this method.

Timing

Call this method before joining or after leaving a channel.

Parameters

sourceType: Type of the video source. See VideoSourceType.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

< 0: Failure. See Error Codes for details and resolution suggestions.

stopRhythmPlayer

Stops the virtual metronome.

Future<void> stopRhythmPlayer();

After calling startRhythmPlayer, you can call this method to stop the virtual metronome.

Note: This method applies to Android and iOS only.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

stopRtmpStream

Stops the CDN stream.

Future<void> stopRtmpStream(String url);

Agora recommends using the more comprehensive server-side streaming feature. See Implement Server-Side Streaming. You can call this method to stop live streaming to a specified CDN streaming URL. This method can only stop one stream at a time. To stop multiple streams, you must call this method multiple times. After calling this method, the SDK triggers the onRtmpStreamingStateChanged callback locally to report the streaming status.

Parameters

url: The CDN streaming URL. The format must be RTMP or RTMPS. The character length must not exceed 1024 bytes. Special characters such as Chinese are not supported.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

stopScreenCapture

Stops screen capture.

Future<void> stopScreenCapture();

Scenario

If you call startScreenCaptureBySourceType, startScreenCaptureByWindowId, or startScreenCaptureByDisplayId to start screen capture, you need to call this method to stop it.

Timing

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

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

stopScreenCaptureBySourceType

Stops screen capture for the specified video source.

Future<void> stopScreenCaptureBySourceType(VideoSourceType sourceType);

Note: This method is only applicable to macOS and Windows.

Scenario

If you call startScreenCaptureBySourceType to start one or more screen captures, you need to call this method to stop screen capture and specify the screen via the sourceType parameter.

Timing

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

Parameters

sourceType: The type of video source. See VideoSourceType.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

switchCamera

Switches between front and rear cameras.

Future<void> switchCamera();

You can call this method during app runtime to dynamically switch cameras based on the actual availability of cameras, without restarting the video stream or reconfiguring the video source.

Note: This method is applicable only to Android and iOS. This method only switches the camera for the first video stream captured by the camera, that is, the video source set to videoSourceCamera (0) when calling startCameraCapture.

Timing

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

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

takeSnapshot

Takes a snapshot of the video.

Future<void> takeSnapshot({required int uid, required String filePath});

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

Note:

This method is asynchronous. When the call returns, the SDK has not actually captured the snapshot.
When used for local video snapshot, it captures the video stream specified in ChannelMediaOptions.
If the user's video has undergone preprocessing, such as watermarking or beautification, the snapshot will include these effects.

Timing

You must call this method after joining a channel.

Related Callbacks

After this method is successfully called, the SDK triggers the onSnapshotTaken callback to report whether the snapshot was successful and provide the snapshot details.

Parameters

uid

User ID. Set to 0 to capture the local user's video.

filePath

Note: Make sure the directory exists and is writable.

The local path to save the snapshot. The path must include the file name and format, for example:

Windows: C:\Users\<user_name>\AppData\Local\Agora\<process_name>\example.jpg
iOS: /App Sandbox/Library/Caches/example.jpg
macOS: ～/Library/Logs/example.jpg
Android: /storage/emulated/0/Android/data/<package name>/files/example.jpg

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

takeSnapshotWithConfig

Takes a video snapshot at the specified observation point.

Future<void> takeSnapshotWithConfig(
      {required int uid, required SnapshotConfig config});

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

Note:

This method is asynchronous. When the call returns, the SDK has not actually captured the snapshot.
When used for local video snapshot, it captures the video stream specified in ChannelMediaOptions.

Timing

You must call this method after joining a channel.

Related Callbacks

After this method is successfully called, the SDK triggers the onSnapshotTaken callback to report whether the snapshot was successful and provide the snapshot details.

Parameters

uid: User ID. Set to 0 to capture the local user's video.
config: Snapshot configuration. See SnapshotConfig.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

unloadAllEffects

Releases all preloaded audio effect files from memory.

Future<void> unloadAllEffects();

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

unloadEffect

Releases a specific preloaded audio effect file from memory.

Future<void> unloadEffect(int soundId);

After loading the audio effect file into memory using preloadEffect, call this method to release the audio effect file.

Timing

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

Parameters

soundId: The ID of the specified audio effect file. Each audio effect file has a unique ID.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

unregisterAudioEncodedFrameObserver

Unregisters the audio encoded frame observer.

void unregisterAudioEncodedFrameObserver(AudioEncodedFrameObserver observer);

Parameters

observer: Audio encoded frame observer. See AudioEncodedFrameObserver.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

unregisterAudioSpectrumObserver

Unregisters the audio spectrum observer.

void unregisterAudioSpectrumObserver(AudioSpectrumObserver observer);

After calling registerAudioSpectrumObserver, if you want to unregister the audio spectrum observer, call this method.

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

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

unregisterMediaMetadataObserver

Unregisters the media metadata observer.

void unregisterMediaMetadataObserver(
    {required MetadataObserver observer, required MetadataType type});

Parameters

observer: The metadata observer. See MetadataObserver.
type: The metadata type. Currently, only videoMetadata is supported.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

< 0: Failure. See Error Codes for details and resolution suggestions.

updateChannelMediaOptions

Updates channel media options after joining the channel.

Future<void> updateChannelMediaOptions(ChannelMediaOptions options);

Parameters

options: Channel media options. See ChannelMediaOptions.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

updateLocalAudioMixerConfiguration

Updates the configuration of local audio mixing.

Future<void> updateLocalAudioMixerConfiguration(
      LocalAudioMixerConfiguration config);

After calling startLocalAudioMixer, if you want to update the configuration of local audio mixing, call this method.

Note: To ensure audio quality, it is recommended that no more than 10 audio streams participate in local mixing.

Timing

This method must be called after startLocalAudioMixer.

Parameters

config: Configuration for local audio mixing. See LocalAudioMixerConfiguration.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

updateLocalTranscoderConfiguration

Updates local video mixing configuration.

Future<void> updateLocalTranscoderConfiguration(
      LocalTranscoderConfiguration config);

After calling startLocalVideoTranscoder, call this method if you want to update the local video mixing configuration.

Note: If you want to update the type of local video source used in mixing, such as adding a second camera or screen capture video, call this method after startCameraCapture or startScreenCaptureBySourceType.

Parameters

config: The configuration for local video mixing. See LocalTranscoderConfiguration.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

updatePreloadChannelToken

Updates the wildcard token for the preloaded channel.

Future<void> updatePreloadChannelToken(String token);

You need to manage the lifecycle of the wildcard token yourself. When the wildcard token expires, you need to generate a new one on your server and pass it in using this method.

Scenario

In scenarios where frequent channel switching or multiple channels are needed, using a wildcard token avoids repeated token requests when switching channels, which speeds up the switching process and reduces the load on your token server.

Parameters

token: The new token.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

updateRtmpTranscoding

Updates the RTMP transcoding configuration.

Future<void> updateRtmpTranscoding(LiveTranscoding transcoding);

Agora recommends using the more comprehensive server-side streaming feature. See Implement Server-Side RTMP Streaming. After enabling transcoding streaming, you can dynamically update the transcoding configuration based on your scenario needs. After the transcoding configuration is updated, the SDK triggers the onTranscodingUpdated callback.

Parameters

transcoding: The transcoding configuration for RTMP streaming. See LiveTranscoding.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

updateScreenCapture

Updates the parameter configuration for screen capture.

Future<void> updateScreenCapture(ScreenCaptureParameters2 captureParams);

If system audio is not captured when screen sharing is enabled and you want to update the configuration and publish system audio, follow these steps:

Call this method and set captureAudio to true.
Call updateChannelMediaOptions and set publishScreenCaptureAudio to true to publish the screen capture audio.

Note:

This method is applicable to Android and iOS only.
On iOS, screen sharing is supported only on iOS 12.0 and later.

Parameters

captureParams: Encoding parameter configuration for screen sharing. See ScreenCaptureParameters2.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

updateScreenCaptureParameters

Updates the parameter configuration for screen capture.

Future<void> updateScreenCaptureParameters(
      ScreenCaptureParameters captureParams);

Note:

This method is applicable to Windows and macOS only.
Call this method after screen or window sharing is enabled.

Parameters

captureParams: Encoding parameter configuration for screen sharing. See ScreenCaptureParameters.
Note: The video properties of the screen sharing stream should be set only through this parameter and are not related to setVideoEncoderConfiguration.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

updateScreenCaptureRegion

Updates the region for screen capture.

Future<void> updateScreenCaptureRegion(Rectangle regionRect);

Note: Call this method after screen or window sharing is enabled.

Parameters

regionRect: The position of the region to be shared relative to the entire screen or window. If not specified, the entire screen or window is shared. See Rectangle. If the set region exceeds the screen or window boundary, only the content within the screen or window is shared; if width or height is set to 0, the entire screen or window is shared.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.