RtcEngine

setEventHandler

Adds event handlers.

void setEventHandler(RtcEngineEventHandler handler)

The SDK uses the RtcEngineEventHandler class to send callbacks to the app. The app inherits the methods of this class to receive these callbacks. All methods in this interface class have default (empty) implementations. Therefore, the application can only inherit some required events. In the callbacks, avoid time-consuming tasks or calling APIs that can block the thread, such as the sendStreamMessage method. Otherwise, the SDK may not work properly.

Parameters

handler: Callback events to be added. For details, see RtcEngineEventHandler.

addPublishStreamUrl

Publishes the local stream to a specified CDN live streaming URL.

Future<void> addPublishStreamUrl(String url, bool transcodingEnabled);

Deprecated:: This method is deprecated. See Release Notes for an alternative solution.

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

Attention:

Call this method after joining a channel.
Ensure that the media push function is enabled. For details, see the prerequisites in Media Push.
This method takes effect only when you are a host in live interactive streaming.
This method adds only one streaming URL to the CDN each time it is called. To push multiple URLs, call this method multiple times.
Agora only supports pushing media streams to the CDN in RTMPS protocol when you enable transcoding.

Parameters

url

The media push URL in the RTMP or RTMPS format. The maximum length of this parameter is 1024 bytes. The URL address must not contain special characters, such as Chinese language characters.

transcodingEnabled

Whether to enable transcoding. Transcoding in a CDN live streaming converts the audio and video streams before pushing them to the CDN server. It applies to scenarios where a channel has multiple broadcasters and composite layout is needed.

true: Enable transcoding.
false: Disable transcoding.

Attention: If you set this parameter as true, ensure that you call the setLiveTranscoding method before calling this method.

addVideoWatermark

Adds a watermark image to the local video.

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

This method adds a PNG watermark image to the local video in the live streaming. Once the watermark image is added, all the audience in the channel (CDN audience included), and the capturing device can see and capture it. Agora supports adding only one watermark image onto the local video, and the newly watermark image replaces the previous one.

The watermark coordinates are dependent on the settings in the setVideoEncoderConfiguration method:

If the orientation mode of the encoding video (VideoOutputOrientationMode) is fixed landscape mode or the adaptive landscape mode, the watermark uses the landscape orientation.
If the orientation mode of the encoding video (VideoOutputOrientationMode) is fixed portrait mode or the adaptive portrait mode, the watermark uses the portrait orientation.
When setting the watermark position, the region must be less than the dimensions set in the setVideoEncoderConfiguration method; otherwise, the watermark image will be cropped.

Attention:

Ensure that call this method after enableVideo.
If you only want to add a watermark to the media push, you can call this method or the setLiveTranscoding method.
This method supports adding a watermark image in the PNG file format only. Supported pixel formats of the PNG image are RGBA, RGB, Palette, Gray, and Alpha_gray.
If the dimensions of the PNG image differ from your settings in this method, the image will be cropped or zoomed to conform to your settings.
If you have enabled the local video preview by calling the startPreview method, you can use the visibleInPreview member to set whether or not the watermark is visible in the preview.
If you have enabled the mirror mode for the local video, the watermark on the local video is also mirrored. To avoid mirroring the watermark, Agora recommends that you do not use the mirror and watermark functions for the local video at the same time. You can implement the watermark function in your application layer.

Parameters

watermarkUrl: The local file path of the watermark image to be added. This method supports adding a watermark image from the local absolute or relative file path.
options: The options of the watermark image to be added. For details, see WatermarkOptions.

adjustAudioMixingPlayoutVolume

Adjusts the volume of audio mixing for local playback.

Future<void> adjustAudioMixingPlayoutVolume(int volume);

Attention: You need to call this method after calling startAudioMixing and receiving the audioMixingStateChanged(PLAY) callback.

Parameters

volume: Audio mixing volume for local playback. The value range is [0,100]. The default value is 100, the original volume.

adjustAudioMixingPublishVolume

Adjusts the volume of audio mixing for publishing.

Future<void> adjustAudioMixingPublishVolume(int volume);

This method adjusts the volume of audio mixing for publishing (sending to other users).

Attention: You need to call this method after calling startAudioMixing and receiving the audioMixingStateChanged(PLAY) callback.

Parameters

volume: Audio mixing volume. The value range is [0,100]. The default value is 100, the original volume.

adjustAudioMixingVolume

Adjusts the volume during audio mixing.

Future<void> adjustAudioMixingVolume(int volume);

This method adjusts the audio mixing volume on both the local client and remote clients.

Attention:

Call this method after startAudioMixing.
Calling this method does not affect the volume of audio effect file playback invoked by the playEffect method.

Parameters

volume: Audio mixing volume. The value ranges between 0 and 100. The default value is 100, the original volume.

adjustPlaybackSignalVolume

Adjusts the playback signal volume of all remote users.

Future<void> adjustPlaybackSignalVolume(int volume);

Attention:

This method adjusts the playback volume that is the mixed volume of all remote users.
As of v2.3.2, to mute the local audio, you need to call the adjustPlaybackSignalVolume andadjustAudioMixingPlayoutVolume methods at the same time, and set volume to 0.
You can call this method either before or after joining a channel.

Parameters

volume

The playback signal volume of all remote users. Integer only. The value range is [0,400].

0: Mute.
100: (Default) The original volume.
400: Four times the original volume (amplifying the audio signals by four times).

adjustRecordingSignalVolume

Adjusts the capturing signal volume.

Future<void> adjustRecordingSignalVolume(int volume);

Attention:

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

Parameters

volume

The playback signal volume of all remote users. Integer only. The value range is [0,400].

0: Mute.
100: (Default) The original volume.
400: Four times the original volume (amplifying the audio signals by four times).

adjustUserPlaybackSignalVolume

Adjusts the playback signal volume of a specified remote user.

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

You can call this method to adjust the playback volume of a specified remote user. To adjust the playback volume of different remote users, call the method as many times, once for each remote user.

Attention:

Call this method after joining a channel.
The playback volume here refers to the mixed volume of a specified remote user.

Parameters

uid: The ID of the remote user.
volume: The playback signal volume of a specified remote user.

clearVideoWatermarks

Removes the watermark image from the video stream.

Future<void> clearVideoWatermarks();

complain

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

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

This method allows users to complain about the quality of the call. Call this method after the user leaves the channel.

Parameters

callId: The current call ID. You can get the call ID by calling getCallId.
description: (Optional) A description of the call. The string length should be less than 800 bytes.

createWithContext

Initializes RtcEngine.

static Future<RtcEngine> createWithContext(RtcEngineContext config) async {
                return RtcEngineImpl.createWithContext(config);
              }

All called methods provided by the RtcEngine class are executed asynchronously. Agora recommends calling these methods in the same thread.

Attention:

Before calling other APIs, you must call create and createWithContext to create and initialize the RtcEngine object.
The SDK supports creating only one RtcEngine instance for an app.

Parameters

config: Configurations for the RtcEngine instance. See RtcEngineContext.

createDataStream

Creates a data stream.

Future<int?> createDataStream(bool reliable, bool ordered);

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

Attention:

Call this method after joining a channel.
Agora does not support setting reliable as true and ordered as true.

Parameters

reliable

Whether or not the data stream is reliable:

true: The recipients receive the data from the sender within five seconds. If the recipient does not receive the data within five seconds, the SDK triggers the streamMessageError callback and returns an error code.
false: There is no guarantee that the recipients receive the data stream within five seconds and no error message is reported for any delay or missing data stream.

ordered

Whether or not the recipients receive the data stream in the sent order:

true: The recipients receive the data in the sent order.
false: The recipients do not receive the data in the sent order.

Returns

ID of the created data stream, if the method call succeeds.
< 0: Failure. You can refer to Error Codes and Warning Codes for troubleshooting.

createDataStreamWithConfig

Creates a data stream.

Future<int?> createDataStreamWithConfig(DataStreamConfig config);

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

Compared with createDataStream[1/2], this method does not support data reliability. If a data packet is not received five seconds after it was sent, the SDK directly discards the data.

Parameters

config: The configurations for the data stream. For details, see DataStreamConfig.

Returns

ID of the created data stream, if the method call succeeds.
< 0: Failure. You can refer to Error Codes and Warning Codes for troubleshooting.

deviceManager

Gets the RtcDeviceManager class.

RtcDeviceManager get deviceManager

Returns

The RtcDeviceManager class.

disableAudio

Disables the audio module.

Future<void> disableAudio();

Attention:

This method disables the internal engine and can be called anytime after initialization. It is still valid after one leaves channel.
This method resets the internal engine and takes some time to take effect. Agora recommends using the following API methods to control the audio modules separately:
- enableLocalAudio: Whether to enable the microphone to create the local audio stream.
- muteLocalAudioStream: Whether to publish the local audio stream.
- muteRemoteAudioStream: Whether to subscribe and play the remote audio stream.
- muteAllRemoteAudioStreams: Whether to subscribe to and play all remote audio streams.

disableLastmileTest

Disables the network connection quality test.

Future<void> disableLastmileTest();

disableVideo

Disables the video module.

Future<void> disableVideo();

This method disables video. You can call this method either before or after joining a channel. If you call it before joining a channel, an audio call starts when you join the channel. If you call it after joining a channel, a video call switches to an audio call. Call enableVideo to enable video.

A successful call of this method triggers the userEnableVideo(false) callback on the remote client.

Attention:

This method affects the internal engine and can be called after leaving the channel.
This method resets the internal engine and takes some time to take effect. Agora recommends using the following API methods to control the video engine modules separately:
- enableLocalVideo: Whether to enable the camera to create the local video stream.
- muteLocalVideoStream: Whether to publish the local video stream.
- muteRemoteVideoStream: Whether to subscribe to and play the remote video stream.
- muteAllRemoteVideoStreams: Whether to subscribe to and play all remote video streams.

enableAudio

Enables the audio module.

Future<void> enableAudio();

The audio mode is enabled by default.

Attention:

This method enables the internal engine and can be called anytime after initialization. It is still valid after one leaves channel.
This method enables the audio module and takes some time to take effect. Agora recommends using the following API methods to control the audio module separately:
- enableLocalAudio: Whether to enable the microphone to create the local audio stream.
- muteLocalAudioStream: Whether to publish the local audio stream.
- muteRemoteAudioStream: Whether to subscribe and play the remote audio stream.
- muteAllRemoteAudioStreams: Whether to subscribe to and play all remote audio streams.

enableAudioVolumeIndication

Enables the reporting of users' volume indication.

Future<void> enableAudioVolumeIndication(int interval, int smooth, bool report_vad);

This method enables the SDK to regularly report the volume information of the local user who sends a stream and remote users (up to three) whose instantaneous volumes are the highest to the app. Once you call this method and users send streams in the channel, the SDK triggers the audioVolumeIndication callback at the time interval set in this method.

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

Parameters

interval

Sets the time interval between two consecutive volume indications:

≤ 0: Disables the volume indication.
> 0: Time interval (ms) between two consecutive volume indications. We recommend a setting greater than 200 ms. Do not set this parameter to less than 10 milliseconds, otherwise the audioVolumeIndication callback will not be triggered.

smooth

The smoothing factor sets the sensitivity of the audio volume indicator. The value ranges between 0 and 10. The recommended value is 3. The greater the value, the more sensitive the indicator.

report_vad

true: Enable the voice activity detection of the local user. Once it is enabled, the vad parameter of the audioVolumeIndication callback reports the voice activity status of the local user.
false: (Default) Disable the voice activity detection of the local user. Once it is disabled, the vad parameter of the audioVolumeIndication callback does not report the voice activity status of the local user, except for the scenario where the engine automatically detects the voice activity of the local user.

enableDeepLearningDenoise

Enables/Disables deep-learning noise reduction.

Future<void> enableDeepLearningDenoise(bool enable);

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

Ensure that the dynamic library is integrated in your project: libagora_ai_denoise_extension.dll
Call enableDeepLearningDenoise(true).

Deep-learning noise reduction requires high-performance devices. The deep-learning noise reduction is enabled only when the device supports this function.

For example, the following devices and later models are known to support deep-learning noise reduction:

iPhone 6S
MacBook Pro 2015
iPad Pro (2nd generation)
iPad mini (5th generation)
iPad Air (3rd generation)

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

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

Attention:

This method dynamically loads the library, so Agora recommends calling this method before joining a channel.
This method works best with the human voice. Agora does not recommend using this method for audio containing music.

Parameters

enable

Whether to enable deep-learning noise reduction.

true: (Default) Enable deep-learning noise reduction.
false: Disable deep-learning noise reduction.

enableDualStreamMode

Enables/Disables dual-stream mode.

Future<void> enableDualStreamMode(bool enabled);

You can call this method to enable or disable the dual-stream mode on the publisher side. Dual streams are a hybrid of a high-quality video stream and a low-quality video stream:

High-quality video stream: High bitrate, high resolution.
Low-quality video stream: Low bitrate, low resolution.

After you enable the dual-stream mode, you can call setRemoteVideoStreamType to choose to receive the high-quality video stream or low-quality video stream on the subscriber side.

Parameters

enabled

Whether to enable dual-stream mode.

true: Enable dual-stream mode.
false: Disable dual-stream mode.

enableEncryption

Enables/Disables the built-in encryption.

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

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

All users in the same channel must use the same encryption mode and encryption key. After the user leaves the channel, the SDK automatically disables the built-in encryption. To enable the built-in encryption, call this method before the user joins the channel again.

Attention: If you enable the built-in encryption, you cannot use the media push function.

Parameters

enabled

Whether to enable built-in encryption:

true: Enable the built-in encryption.
false: Disable the built-in encryption.

config

Built-in encryption configurations. See EncryptionConfig for details.

enableFaceDetection

Enables/Disables face detection for the local user.

Future<void> enableFaceDetection(bool enable);

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

Attention: This method is for Android and iOS only.

Once face detection is enabled, the SDK triggers the facePositionChanged callback to report the face information of the local user:

The width and height of the local video.
The position of the human face in the local video.
The distance between the human face and the screen.

This method needs to be called after the camera is started (for example, by calling startPreview or joinChannel).

Parameters

enable

Whether to enable face detection:

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

enableInEarMonitoring

Enables in-ear monitoring.

Future<void> enableInEarMonitoring(bool enabled);

This method enables or disables in-ear monitoring.

Attention:

This method is for Android and iOS only.
Users must use wired earphones to hear their own voices.
You can call this method either before or after joining a channel.

Parameters

enabled

Enables in-ear monitoring.

true: Enables in-ear monitoring.
false: (Default) Disables in-ear monitoring.

enableLastmileTest

Enables the network connection quality test.

Future<void> enableLastmileTest();

This method tests the quality of the users' network connections. By default, this function is disabled. This method applies to the following scenarios:

Before a user joins a channel, call this method to check the uplink network quality.
Before an audience switches to a host, call this method to check the uplink network quality.

Regardless of the scenario, enabling this method consumes extra network traffic and affects the call quality. After receiving the lastmileQuality callback, call disableLastmileTest to stop the test, and then join the channel or switch to the host.

Attention:

Do not use this method together with startLastmileProbeTest.
Do not call any other methods before receiving the lastmileQuality callback. Otherwise, the callback may be interrupted by other methods, and hence may not be triggered.
A host should not call this method after joining a channel (when in a call).
If you call this method to test the last mile network quality, the SDK consumes the bandwidth of a video stream, whose bitrate corresponds to the bitrate you set in setVideoEncoderConfiguration. After joining a channel, whether you have called disableLastmileTest or not, the SDK automatically stops consuming the bandwidth.

enableLocalAudio

Enables/Disables the local audio capture.

Future<void> enableLocalAudio(bool enabled);

The audio function is enabled by default. This method disables or re-enables the local audio function to stop or restart local audio capturing.

This method does not affect receiving or playing the remote audio streams, and enableLocalAudio(false) applies to scenarios where the user wants to receive remote audio streams without sending any audio stream to other users in the channel.

Once the local audio function is disabled or re-enabled, the SDK triggers the localAudioStateChanged callback, which reports Stopped(0) or Recording(1).

Attention:

This method is different from the muteLocalAudioStream method:
- enableLocalVideo: Disables/Re-enables the local audio capturing and processing. If you disable or re-enable local audio capturing using the enableLocalAudio method, the local user might hear a pause in the remote audio playback.
- muteLocalAudioStream: Sends/Stops sending the local audio streams.
You can call this method either before or after joining a channel.

Parameters

enabled

true: (Default) Re-enable the local audio function, that is, to start the local audio capturing device (for example, the microphone).
false: Disable the local audio function, that is, to stop local audio capturing.

enableLocalVideo

Enables/Disables the local video capture.

Future<void> enableLocalVideo(bool enabled);

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

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

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

Attention:

You can call this method either before or after joining a channel.
This method enables the internal engine and is valid after .

Parameters

enabled

Whether to enable the local video capture.

true: (Default) Enable the local video capture.
false: Disables the local video capture. Once the local video is disabled, the remote users can no longer receive the video stream of this user, while this user can still receive the video streams of the other remote users. When set to false, this method does not require a local camera.

enableLocalVoicePitchCallback

Enables reporting the voice pitch of the local user.

Future<void> enableLocalVoicePitchCallback(int interval);

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

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

Parameters

interval

Sets the time interval at which the SDK triggers the localVoicePitchInHz callback:

≤ 0: Disables the localVoicePitchInHz callback.
> 0: The time interval (ms) at which the SDK triggers the localVoicePitchInHz callback. The value must be greater than or equal to 10. If the value is less than 10, the SDK automatically changes it to 10.

enableLoopbackRecording

Enables loopback audio capturing.

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

If you enable loopback audio capturing, the output of the sound card is mixed into the audio stream sent to the other end.

Attention:

This method applies to macOS and Windows only.
macOS does not support loopback capturing of the default sound card. To use this method, use a virtual sound card and pass its name to the SDK as the value of thedeviceName parameter. Based on tests, Agora recommends using soundflower as the virtual sound card.
You can call this method either before or after joining a channel.

Parameters

enabled

Sets whether to enable loopback capturing.

true: Enable loopback audio capturing.
false: (Default) Disable loopback capturing.

deviceName

The device name of the sound card. The default value is null (the default sound card). If you use a virtual sound card like "Soundflower", set this parameter as the name of the sound card, "Soundflower". The SDK will find the corresponding sound card and start capturing.

enableRemoteSuperResolution

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

Future<void> enableRemoteSuperResolution(int userId, bool enable);

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

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

CAUTION:

The super resolution feature requires extra system resources. To balance the visual experience and system consumption, this feature can only be enabled for a single remote user. If the local user uses super resolution on Android, the original resolution of the remote user's video cannot exceed 640 × 360 pixels; if the local user uses super resolution on iOS, the original resolution of the remote user's video cannot exceed 640 × 480 pixels.

If you exceed these limitations, the SDK triggers the warning callback and returns all corresponding warning codes:

SuperResolutionStreamOverLimitation: 1610. The origin resolution of the remote video is beyond the range where super resolution can be applied.
SuperResolutionUserCountOverLimitation: 1611. Super resolution is already being used on another remote user's video.
SuperResolutionDeviceNotSupported: 1612. The device does not support using super resolution.

Attention:

This method applies to Android and iOS only.
Before calling this method, ensure that you have integrated the following dynamic libraries:
- Android: libagora_super_resolution_extension.so
- iOS: AgoraSuperResolutionExtension.xcframework
Because this method has certain system performance requirements, Agora recommends that you use the following devices or better:
- Android:
  - VIVO: V1821A, NEX S, 1914A, 1916A, 1962A, 1824BA, X60, X60 Pro
  - OPPO: PCCM00, Find X3
  - OnePlus: A6000
  - Xiaomi: Mi 8, Mi 9, Mi 10, Mi 11, MIX3, Redmi K20 Pro
  - SAMSUNG: SM-G9600, SM-G9650, SM-N9600, SM-G9708, SM-G960U, SM-G9750, S20, S21
  - HUAWEI: SEA-AL00, ELE-AL00, VOG-AL00, YAL-AL10, HMA-AL00, EVR-AN00, nova 4, nova 5 Pro, nova 6 5G, nova 7 5G, Mate 30, Mate 30 Pro, Mate 40, Mate 40 Pro, P40, P40 Pro, Huawei M6, MatePad 10.8
- iOS:
  - iPhone XR
  - iPhone XS
  - iPhone XS Max
  - iPhone 11
  - iPhone 11 Pro
  - iPhone 11 Pro Max
  - iPhone 12
  - iPhone 12 mini
  - iPhone 12 Pro
  - iPhone 12 Pro Max
  - iPhone 12 SE (2nd generation)
  - iPad Pro 11-inch (3rd generation)
  - iPad Pro 12.9-inch (3rd generation)
  - iPad Air 3 (3rd generation)
  - iPad Air 3 (4th generation)

Parameters

userId

The user ID of the remote user.

enable

Whether to enable super resolution for the remote user’s video:

true: Enable super resolution.
false: Disable super resolution.

enableSoundPositionIndication

Enables/Disables stereo panning for remote users.

Future<void> enableSoundPositionIndication(bool enabled);

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

Parameters

enabled

Whether to enable stereo panning for remote users:

true: Enable stereo panning.
false: Disable stereo panning.

enableVideo

Enables the video module.

Future<void> enableVideo();

Call this method either before joining a channel or during a call. If this method is called before joining a channel, the call starts in the video mode. Call disableVideo to disable the video mode.

A successful call of this method triggers the remoteVideoStateChanged callback on the remote client.

Attention:

This method enables the internal engine and is valid after leaving the channel.
This method resets the internal engine and takes some time to take effect. Agora recommends using the following API methods to control the video engine modules separately:
- enableLocalVideo: Whether to enable the camera to create the local video stream.
- muteLocalVideoStream: Whether to publish the local video stream.
- muteRemoteVideoStream: Whether to subscribe to and play the remote video stream.
- muteAllRemoteVideoStreams: Whether to subscribe to and play all remote video streams.

enableVirtualBackground

Enables/Disables the virtual background. (beta feature)

Future<void> enableVirtualBackground(
      bool enabled, VirtualBackgroundSource backgroundSource);

The virtual background function allows you to replace the original background image of the local user or to blur the background. After successfully enabling the virtual background function, all users in the channel can see the customized background.

You can find out from the virtualBackgroundSourceEnabled callback whether the virtual background is successfully enabled or the cause of any errors.

Attention:

Before calling this method, ensure that you have integrated the dynamic library.
- Android: libagora_segmentation_extension.so
- iOS: AgoraVideoSegmentationExtension.xcframework
Call this method after enableVideo.
This function requires a high-performance device. Agora recommends that you use this function on devices with the following chips:
- Snapdragon 700 series 750G and later
- Snapdragon 800 series 835 and later
- Dimensity 700 series 720 and later
- Kirin 800 series 810 and later
- Kirin 900 series 980 and later
- Devices with an A9 chip and better, as follows:
  - iPhone 6S and later
  - iPad Air 3rd generation and later
  - iPad 5th generation and later
  - iPad Pro 2nd generation and later
  - iPad mini 5th generation and later
Agora recommends that you use this function in scenarios that meet the following conditions:
- A high-definition camera device is used, and the environment is uniformly lit.
- There are few objects in the captured video. Portraits are half-length and unobstructed. Ensure that the background is a solid color that is different from the color of the user's clothing.

Parameters

enabled

Whether to enable virtual background:

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

backgroundSource

The custom background image. See VirtualBackgroundSource for details. To adapt the resolution of the custom background image to that of the video captured by the SDK, the SDK scales and crops the custom background image while ensuring that the content of the custom background image is not distorted.

enableWebSdkInteroperability

Enables interoperability with the Agora Web SDK (applicable only in the live streaming scenarios).

Future<void> enableWebSdkInteroperability(bool enabled);

Deprecated:: The SDK automatically enables interoperability with the Web SDK, so you no longer need to call this method.

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

This method is only applicable in live streaming scenarios, and interoperability is enabled by default in communication scenarios.

Parameters

enabled

Whether to enable interoperability with the Agora Web SDK.

true: Enable interoperability.
false: (Default) Disable interoperability.

getAudioFileInfo

Gets the information of a specified audio file.

Future<int?> getAudioFileInfo(String filePath);

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

Attention:

Call this method after joining a channel.
For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support.

Parameters

filePath

The file path:

Android: The file path, including the filename extensions. To access an online file, Agora supports using a URL address; to access a local file, Agora supports using a URI address, an absolute path, or a path that starts with /assets/. You might encounter permission issues if you use an absolute path to access a local file, so Agora recommends using a URI address instead. For example: content://com.android.providers.media.documents/document/audio%3A14441.
Windows: The absolute path or URL address (including the filename extensions) of the audio file. For example: C:\music\audio.mp4.
iOS or macOS: The absolute path or URL address (including the filename extensions) of the audio file. For example: /var/mobile/Containers/Data/audio.mp4.

Returns

0: Success.
< 0: Failure.

getAudioMixingCurrentPosition

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

Future<int?> getAudioMixingCurrentPosition();

Retrieves the playback position (ms) of the audio.

Attention: You need to call this method after calling startAudioMixing and receiving the audioMixingStateChanged(PLAY) callback.

Returns

≥ 0: The current playback position of the audio mixing, if this method call succeeds.
< 0: Failure.

getAudioMixingDuration

Retrieves the duration (ms) of the music file.

Future<int?> getAudioMixingDuration([String? filePath]);

Attention: Call this method after joining a channel.

Parameters

filePath: The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example: Android: /sdcard/emulated/0/audio.mp4, iOS: /var/mobile/Containers/Data/audio.mp4. Supported audio formats include MP3, AAC, M4A, MP4, WAV, and 3GP. See supported audio formats.

Returns

≥ 0: A successful method call. Returns the total duration (ms) of the specified music file.
< 0: Failure.

getAudioMixingPlayoutVolume

Retrieves the audio mixing volume for local playback.

Future<int?> getAudioMixingPlayoutVolume();

This method helps troubleshoot audio volume‑related issues.

Attention: You need to call this method after calling startAudioMixing and receiving the audioMixingStateChanged(PLAY) callback.

Returns

≥ 0: The audio mixing volume, if this method call succeeds. The value range is [0,100].
< 0: Failure.

getAudioMixingPublishVolume

Retrieves the audio mixing volume for publishing.

Future<int?> getAudioMixingPublishVolume();

This method helps troubleshoot audio volume‑related issues.

Attention: You need to call this method after calling startAudioMixing and receiving the audioMixingStateChanged(PLAY) callback.

Returns

≥ 0: The audio mixing volume, if this method call succeeds. The value range is [0,100].
< 0: Failure.

getAudioTrackCount

Gets the audio track index of the current music file.

Future<int?> getAudioTrackCount();

Note:

This method is for Android, iOS, and Windows only.
Call this method after calling startAudioMixing and receiving the audioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING) callback.
For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support.

Returns

≥ 0: The audio track index of the current music file, if this method call succeeds.
< 0: Failure.

getCameraMaxZoomFactor

Gets the maximum zoom ratio supported by the camera.

Future<double?> getCameraMaxZoomFactor();

Attention:

Call this method before calling joinChannel, enableVideo, or enableLocalVideo, depending on which method you use to turn on your local camera.

Returns

The maximum zoom factor.

getCallId

Retrieves the call ID.

Future<String?> getCallId();

When a user joins a channel on a client, a callId is generated to identify the call from the client. Some methods, such as rate and complain, must be called after the call ends to submit feedback to the SDK. These methods require the callId parameter.

Attention: Call this method after joining a channel.

Returns

The current call ID.

getConnectionState

Gets the current connection state of the SDK.

Future<ConnectionStateType> getConnectionState();

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

Returns

The current connection state.

getEffectCurrentPosition

Retrieves the playback position of the audio effect file.

Future<int?> getEffectCurrentPosition(int soundId);

Attention: Call this method after playEffect.

Parameters

soundId: The audio effect ID. The ID of each audio effect file is unique.

Returns

≥ 0: A successful method call. Returns the playback position (ms) of the specified audio effect file.
< 0: Failure.

getEffectDuration

Retrieves the duration of the audio effect file.

Future<int?> getEffectDuration(String filePath);

Attention: Call this method after joining a channel.

Parameters

filePath: The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example: Android: /sdcard/emulated/0/audio.mp4, iOS: /var/mobile/Containers/Data/audio.mp4. Supported audio formats include MP3, AAC, M4A, MP4, WAV, and 3GP. See supported audio formats.

Returns

≥ 0: A successful method call. Returns the total duration (ms) of the specified audio effect file.
< 0: Failure.

getEffectsVolume

Retrieves the volume of the audio effects.

Future<double?> getEffectsVolume();

The volume is an integer ranging from 0 to 100. The default value is 100, the original volume.

Attention: Call this method after playEffect.

Returns

Volume of the audio effects, if this method call succeeds.
< 0: Failure.

getErrorDescription

Gets the warning or error description.

Future<String?> getErrorDescription(int error)

Parameters

error: The error code or warning code reported by the SDK.

Returns

The specific error or warning description.

getScreenShareHelper

Gets a child process object.

Future<RtcEngine> getScreenShareHelper({String? appGroup})

Parameters

appGroup: The app group.

Returns

A child process object, which can be used in scenarios such as screen sharing.

getUserInfoByUid

Gets the user information by passing in the user ID.

Future<UserInfo> getUserInfoByUid(int uid);

After a remote user joins the channel, the SDK gets the UID and user account of the remote user, caches them in a mapping table object, and triggers the userInfoUpdated callback on the local client. After receiving the callback, you can call this method to get the user account of the remote user from the UserInfo object by passing in the user ID.

Parameters

uid: User ID.

Returns

The UserInfo object that identifies the user information.

Not null: Success.
Null: Failure.

getUserInfoByUserAccount

Gets the user information by passing in the user account.

Future<UserInfo> getUserInfoByUserAccount(String userAccount);

After a remote user joins the channel, the SDK gets the UID and user account of the remote user, caches them in a mapping table object, and triggers the userInfoUpdated callback on the local client. After receiving the callback, you can call this method to get the user account of the remote user from the UserInfo object by passing in the user ID.

Parameters

userAccount: The user account.

Returns

The UserInfo object that identifies the user information.

Not null: Success.
Null: Failure.

getSdkVersion

Gets the SDK version.

Future<String?> getSdkVersion()

Returns

The SDK version number. The format is a string.

isCameraZoomSupported

Checks whether the device supports camera zoom.

Future<bool?> isCameraZoomSupported();

Attention:

Call this method before calling joinChannel, enableVideo, or enableLocalVideo, depending on which method you use to turn on your local camera.

Returns

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

isCameraTorchSupported

Checks whether the device supports camera flash.

Future<bool?> isCameraTorchSupported();

This method needs to be called after the camera is started (for example, by calling startPreview or joinChannel).

Attention:

The app enables the front camera by default. If your front camera does not support flash, this method returns false. If you want to check whether the rear camera supports flash, call switchCamera before this method.

Returns

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

isCameraFocusSupported

Check whether the device supports the manual focus function.

Future<bool?> isCameraFocusSupported();

Attention:

Call this method before calling joinChannel, enableVideo, or enableLocalVideo, depending on which method you use to turn on your local camera.

Returns

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

isCameraExposurePositionSupported

Checks whether the device supports manual exposure.

Future<bool?> isCameraExposurePositionSupported();

Attention:

Call this method before calling joinChannel, enableVideo, or enableLocalVideo, depending on which method you use to turn on your local camera.

Returns

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

isCameraAutoFocusFaceModeSupported

Checks whether the device supports the face auto-focus function.

Future<bool?> isCameraAutoFocusFaceModeSupported();

This method needs to be called after the camera is started (for example, by calling startPreview or joinChannel).

Returns

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

isSpeakerphoneEnabled

Checks whether the speakerphone is enabled.

Future<bool?> isSpeakerphoneEnabled();

Note: This method is for Android and iOS only.

Returns

true: The speakerphone is enabled, and the audio plays from the speakerphone.
false: The speakerphone is not enabled, and the audio plays from devices other than the speakerphone. For example, the headset or earpiece.

joinChannel

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

Future<void> joinChannel(
      String? token, String channelName, String? optionalInfo, int optionalUid,
      [ChannelMediaOptions? options]);

This method enables the local user to join a real-time audio and video interaction channel. With the same App ID, users in the same channel can talk to each other, and multiple users in the same channel can start a group chat.

A successful call of this method triggers the following callbacks:

The local client: The joinChannelSuccess and connectionStateChanged callbacks.
The remote client: userJoined, if the user joining the channel is in the Communication profile or is a host in the Live-broadcasting profile.

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

Parameters

token

The token generated on your server for authentication. See Authenticate Your Users with Token.

CAUTION: Ensure that the App ID used for creating the token is the same App ID used by the createWithContext method for initializing the RTC engine.

channelName

The channel name. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported characters:

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

optionalInfo

Reserved for future use.

optionalUid

User ID This parameter is used to identify the user in the channel for real-time audio and video interaction. You need to set and manage user IDs yourself, and ensure that each user ID in the same channel is unique. This parameter is a 32-bit unsigned integer. The value range is 1 to 2³²-1. If the user ID is not assigned (or set to 0), the SDK assigns a random user ID and returns it in the joinChannelSuccess callback. Your app must maintain the returned user ID, because the SDK does not do so.

options

The channel media options. For details, see ChannelMediaOptions.

joinChannelWithUserAccount

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

Future<void> joinChannelWithUserAccount(
      String? token, String channelName, String userAccount,
      [ChannelMediaOptions? options]);

This method allows a user to join the channel with the user account. After the user successfully joins the channel, the SDK triggers the following callbacks:

The local client: localUserRegistered, joinChannelSuccess and connectionStateChanged callbacks.
The remote client: The userJoined callback if the user is in the COMMUNICATION profile, and the userInfoUpdated callback if the user is a host in the LIVE_BROADCASTING profile.

Once a user joins the channel, the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. To stop subscribing to a specified stream or all remote streams, call the corresponding mute methods.

Attention: To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the ID of the user is set to the same parameter type.

Parameters

token

The token generated on your server for authentication. See Authenticate Your Users with Token.

CAUTION: Ensure that the App ID used for creating the token is the same App ID used by the createWithContext method for initializing the RTC engine.

The channel name. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported characters:

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

userAccount

The user account. This parameter is used to identify the user in the channel for real-time audio and video engagement. You need to set and manage user accounts yourself and ensure that each user account in the same channel is unique. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported characters are (89 in total):

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

options

The channel media options. For details, see ChannelMediaOptions.

leaveChannel

Leaves a channel.

Future<void> leaveChannel();

This method releases all resources related to the session. This method call is asynchronous. When this method returns, it does not necessarily mean that the user has left the channel.

After joining the channel, you must call this method to end the call; otherwise, you cannot join the next call.

A successful call of this method triggers the following callbacks:

The local client: leaveChannel.
The remote client: userOffline, if the user joining the channel is in the Communication profile, or is a host in the Live-broadcasting profile.

Attention:

If you call destroy immediately after calling this method, the SDK does not trigger the leaveChannel callback.
If you call this method during a CDN live streaming, the SDK automatically calls the removePublishStreamUrl method.

muteAllRemoteAudioStreams

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

Future<void> muteAllRemoteAudioStreams(bool muted);

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

Attention:

Call this method after joining a channel.

Parameters

muted

Whether to subscribe to the audio streams of all remote users:

true: Do not subscribe to the audio streams of all remote users.
false: (Default) Subscribe to the audio streams of all remote users by default.

muteAllRemoteVideoStreams

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

Future<void> muteAllRemoteVideoStreams(bool muted);

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

Attention:

Call this method after joining a channel.
See recommended settings in Set the Subscribing State.

Parameters

muted

Whether to stop subscribing to the video streams of all remote users.

true: Stop subscribing to the video streams of all remote users.
false: (Default) Subscribe to the audio streams of all remote users by default.

muteLocalAudioStream

Stops or resumes publishing the local audio stream.

Future<void> muteLocalAudioStream(bool muted);

A successful call of this method triggers the userMuteAudio callback on the remote client.

Attention:

This method does not affect any ongoing audio recording, because it does not disable the microphone.
You can call this method either before or after joining a channel. If you call the setChannelProfile method after this method, the SDK resets whether or not to stop publishing the local audio according to the channel profile and user role. Therefore, Agora recommends calling this method after the setChannelProfile method.

Parameters

muted

Whether to stop publishing the local audio stream.

true: Stop publishing the local audio stream.
false: (Default) Resumes publishing the local audio stream.

muteLocalVideoStream

Stops or resumes publishing the local video stream.

Future<void> muteLocalVideoStream(bool muted);

A successful call of this method triggers the userMuteVideo callback on the remote client.

Attention:

This method executes faster than the enableLocalVideo(false) method, which controls the sending of the local video stream.
This method does not affect any ongoing video recording, because it does not disable the camera.
You can call this method either before or after joining a channel. If you call setChannelProfile after this method, the SDK resets whether or not to stop publishing the local video according to the channel profile and user role. Therefore, Agora recommends calling this method after the setChannelProfile method.

Parameters

muted

Whether to stop publishing the local video stream.

true: Stop publishing the local video stream.
false: (Default) Publish the local video stream.

muteRemoteAudioStream

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

Future<void> muteRemoteAudioStream(int uid, bool muted);

Attention:

Call this method after joining a channel.
See recommended settings in Set the Subscribing State.

Parameters

uid

The user ID of the specified user.

muted

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

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

muteRemoteVideoStream

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

Future<void> muteRemoteVideoStream(int userId, bool muted);

Attention:

Call this method after joining a channel.
See recommended settings in Set the Subscribing State.

Parameters

userId

The ID of the specified user.

muted

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

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

pauseAllChannelMediaRelay

Pauses the media stream relay to all destination channels.

Future<void> pauseAllChannelMediaRelay();

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

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

Attention: Call this method after startChannelMediaRelay.

pauseAllEffects

Pauses all audio effects.

Future<void> pauseAllEffects();

pauseAudioMixing

Pauses playing and mixing the music file.

Future<void> pauseAudioMixing();

Call this method when you are in a channel.

pauseEffect

Pauses a specified audio effect.

Future<void> pauseEffect(int soundId);

Parameters

soundId: The audio effect ID. The ID of each audio effect file is unique.

playEffect

Plays the specified local or online audio effect file.

Future<void> playEffect(int soundId, String filePath, int loopCount,
      double pitch, double pan, int gain, bool publish,
      [int? startPos]);

To play multiple audio effect files at the same time, call this method multiple times with different soundId and filePath. For the best user experience, Agora recommends playing no more than three audio effect files at the same time. After the playback of an audio effect file completes, the SDK triggers the audioEffectFinished callback.

Attention: Call this method after joining a channel.

Parameters

soundId

The audio effect ID. The ID of each audio effect file is unique.

Attention: If you have preloaded an audio effect into memory by calling preloadEffect, ensure that this parameter is set to the same value as soundId in preloadEffect.

filePath

The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example: Android: /sdcard/emulated/0/audio.mp4, iOS: /var/mobile/Containers/Data/audio.mp4. Supported audio formats include MP3, AAC, M4A, MP4, WAV, and 3GP. See supported audio formats.

Attention: If you have preloaded an audio effect into memory by calling preloadEffect, ensure that this parameter is set to the same value as filePath in preloadEffect.

loopCount

The number of times the audio effect loops:

≥ 0: The number of playback times. For example, 1 means loop one time, which means play the audio effect two times in total.
-1: Play the music effect in an infinite loop.

pitch

The pitch of the audio effect. The value range is 0.5 to 2.0. The default value is 1.0, which means the original pitch. The lower the value, the lower the pitch.

pan

The spatial position of the audio effect. The value range is 1 to10000.

-1.0: The audio effect displays to the left.
0.0: The audio effect displays ahead.
1.0: The audio effect displays to the right.

gain

The volume of the audio effect. The value range is 1 to10000. The default value is 100.0, which means the original volume. The smaller the value, the lower the volume.

publish

Whether to publish the audio effect to the remote users.

true: Publish the audio effect to the remote users. Both the local user and remote users can hear the audio effect.
false: Do not publish the audio effect to the remote users. Only the local user can hear the audio effect.

startPos

The playback position (ms) of the audio effect file.

preloadEffect

Preloads a specified audio effect file into the memory.

Future<void> preloadEffect(int soundId, String filePath);

To ensure smooth communication, limit the size of the audio effect file. We recommend using this method to preload the audio effect before calling joinChannel.

Attention:

This method does not support online audio effect files.
For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support.

Parameters

soundId

The audio effect ID. The ID of each audio effect file is unique.

filePath

File path:

Android: The file path, which needs to be accurate to the file name and suffix. Agora supports using a URI address, an absolute path, or a path that starts with /assets/. You might encounter permission issues if you use an absolute path to access a local file, so Agora recommends using a URI address instead. For example: content://com.android.providers.media.documents/document/audio%203A14441
Windows: The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example: C:\music\audio.mp4.
iOS or macOS: The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example: /var/mobile/Containers/Data/audio.mp4.

rate

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

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

Attention: Ensure that you call this method after leaving a channel.

Parameters

callId: The current call ID. You can get the call ID by calling getCallId.
rating: The rating of the call. The value is between 1 (lowest score) and 5 (highest score). If you set a value out of this range, the SDK returns the -2 (ERR_INVALID_ARGUMENT) error.
description: (Optional) A description of the call. The string length should be less than 800 bytes.

registerLocalUserAccount

Registers a user account.

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

Once registered, the user account can be used to identify the local user when the user joins the channel. After the registration is successful, the user account can identify the identity of the local user, and the user can use it to join the channel.

After the user successfully registers a user account, the SDK triggers the localUserRegistered callback on the local client, reporting the user ID and user account of the local user.

This method is optional. To join a channel with a user account, you can choose either of the following ways:

Call registerLocalUserAccount to to create a user account, and then call joinChannelWithUserAccount to join the channel.
Call the joinChannelWithUserAccount method to join the channel.

The difference between the two ways is that the time elapsed between calling the registerLocalUserAccount method and joining the channel is shorter than directly calling joinChannelWithUserAccount.

Attention:

Ensure that you set the userAccount parameter; otherwise, this method does not take effect.
Ensure that the userAccount is unique in the channel.
To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the ID of the user is set to the same parameter type.

Parameters

appId

The App ID of your project on Agora Console.

userAccount

The user account. This parameter is used to identify the user in the channel for real-time audio and video engagement. You need to set and manage user accounts yourself and ensure that each user account in the same channel is unique. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported characters are (89 in total):

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

registerMediaMetadataObserver

Registers the metadata observer.

Future<void> registerMediaMetadataObserver();

Attention:

Call this method before joinChannel.
This method applies only to interactive live streaming.

destroy

Releases the RtcEngine instance.

Future<void> destroy();

This method releases all resources used by the Agora SDK. Use this method for apps in which users occasionally make voice or video calls. When users do not make calls, you can free up resources for other operations.

Attention: If you want to create a new RtcEngine instance after destroying the current one, ensure that you wait till the destroy method execution to complete.

removePublishStreamUrl

Removes an RTMP or RTMPS stream from the CDN.

Future<void> removePublishStreamUrl(String url);

Deprecated:: This method is deprecated.

After a successful method call, the SDK triggers rtmpStreamingStateChanged on the local client to report the result of deleting the URL.

Attention:

Before calling this method, make sure that the media push function has been enabled. .
This method takes effect only when you are a host in live interactive streaming.
Call this method after joining a channel.
This method removes only one media push URL each time it is called. To remove multiple URLs, call this method multiple times.

Parameters

url: The media push URL to be removed. The maximum length of this parameter is 1024 bytes. The media push URL must not contain special characters, such as Chinese characters.

renewToken

Gets a new token when the current token expires after a period of time.

Future<void> renewToken(String token);

Passes a new token to the SDK. A token expires after a certain period of time. In the following two cases, the app should call this method to pass in a new token. Failure to do so will result in the SDK disconnecting from the server.

The SDK triggers the tokenPrivilegeWillExpire callback.
The connectionStateChanged callback reports TokenExpired(9).

Parameters

token: The new token.

resumeAllChannelMediaRelay

Resumes the media stream relay to all destination channels.

Future<void> resumeAllChannelMediaRelay();

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

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

Note: Call this method after the pauseAllChannelMediaRelay method.

resumeAllEffects

Resumes playing all audio effects.

Future<void> resumeAllEffects();

resumeAudioMixing

Resumes playing and mixing the music file.

Future<void> resumeAudioMixing();

This method resumes playing and mixing the music file. Call this method when you are in a channel.

resumeEffect

Resumes playing a specified audio effect.

Future<void> resumeEffect(int soundId);

Parameters

soundId: The audio effect ID. The ID of each audio effect file is unique.

selectAudioTrack

Specified the playback track of the current music file.

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

Note:

This method is for Android, iOS, and Windows only.
Call this method after calling startAudioMixing and receive the audioMixingStateChanged(Playing) callback.
For the audio file formats supported by this method, see https://docs.agora.io/en/Video/faq/audio_format.

Parameters

index: The specified playback track. The value range is [0, getAudioTrackCount()].

Returns

0: Success.
< 0: Failure.

setAudioMixingPlaybackSpeed

Sets the channel mode of the current music file.

Future<void> setAudioMixingPlaybackSpeed(int speed);

Call this method after calling startAudioMixing and receiving the audioMixingStateChanged(Playing) callback.

Parameters

speed

The playback speed. Agora recommends that you limit this value to between 50 and 400, defined as follows:

50: Half the original speed.
100: The original speed.
400: 4 times the original speed.

setAudioMixingDualMonoMode

Sets the channel mode of the current music file.

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

Note:

Call this method after calling startAudioMixing and receive the audioMixingStateChanged(Playing) callback.
This method only applies to stereo audio files.

Parameters

mode: The channel mode. See AudioMixingDualMonoMode.

Returns

0: Success.
< 0: Failure.

startRhythmPlayer

Enables the virtual metronome.

Future<void> startRhythmPlayer(
      String sound1, String sound2, RhythmPlayerConfig config);

In music education, physical education and other scenarios, teachers usually need to use a metronome so that students can practice with the correct beat. The meter is composed of a downbeat and upbeats. The first beat of each measure is called a downbeat, and the rest are called upbeats.

In this method, you need to set the paths of the upbeat and downbeat files, the number of beats per measure, the tempo, and whether to send the sound of the metronome to remote users.

Attention:

After enabling the virtual metronome, the SDK plays the specified audio effect file from the beginning, and controls the playback duration of each file according to beatsPerMinute you set in RhythmPlayerConfig. For example, if you set beatsPerMinute as 60, the SDK plays one beat every second. If the file duration exceeds the beat duration, the SDK only plays the audio within the beat duration.

Parameters

sound1: The absolute path or URL address (including the filename extensions) of the file for the downbeat. For example: Android: /sdcard/emulated/0/audio.mp4, iOS: /var/mobile/Containers/Data/audio.mp4. For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support.
sound2: The absolute path or URL address (including the filename extensions) of the file for the upbeats. For example: Android: /sdcard/emulated/0/audio.mp4, iOS: /var/mobile/Containers/Data/audio.mp4. For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support.
config: The metronome configuration. See RhythmPlayerConfig.

stopRhythmPlayer

Disables the virtual metronome.

Future<void> stopRhythmPlayer();

After calling startRhythmPlayer, you can call this method to disable the virtual metronome.

configRhythmPlayer

Configures the virtual metronome.

Future<void> configRhythmPlayer(RhythmPlayerConfig config);

After calling startRhythmPlayer, you can call this method to reconfigure the virtual metronome.

Attention:

After enabling the virtual metronome, the SDK plays the specified audio effect file from the beginning, and controls the playback duration of each file according to beatsPerMinute you set in RhythmPlayerConfig. For example, if you set beatsPerMinute as 60, the SDK plays one beat every second. If the file duration exceeds the beat duration, the SDK only plays the audio within the beat duration.

Parameters

config: The metronome configuration. See RhythmPlayerConfig.

sendCustomReportMessage

Reports customized messages.

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

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

sendMetadata

Sends media metadata.

Future<void> sendMetadata(Uint8List metadata);

If the metadata is sent successfully, the SDK triggers the metadataReceived callback on the receiver.

Parameters

metadata: Media metadata See Metadata.

sendStreamMessage

Sends data stream messages.

Future<void> sendStreamMessage(int streamId, Uint8List message);

Sends data stream messages to all users in a channel. The SDK has the following restrictions on this method:

Up to 30 packets can be sent per second in a channel with each packet having a maximum size of 1 KB.
Each client can send up to 6 KB of data per second.
Each user can have up to five data streams simultaneously.

A successful method call triggers the streamMessage callback on the remote client, from which the remote user gets the stream message. A failed method call triggers the streamMessageError callback on the remote client.

Attention:

Ensure that you call createDataStreamWithConfig to create a data channel before calling this method.
In live streaming scenarios, this method only applies to hosts.

Parameters

streamId: The data stream ID. You can get the data stream ID by calling createDataStreamWithConfig.
message: The message to be sent.

setAudioEffectParameters

Sets parameters for SDK preset audio effects.

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

Detailed Description

Since: v3.2.0

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

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

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

Attention:

You can call this method either before or after joining a channel.
To get better audio effect quality, Agora recommends calling and setting scenario in setAudioProfile as GameStreaming(3) before calling this method.
Do not set the profile parameter in setAudioProfile to SpeechStandard (1), or the method does not take effect.
This method works best with the human voice. Agora does not recommend using this method for audio containing music.
After calling setAudioEffectParameters, Agora recommends not calling the following methods, or the settings in setAudioEffectParameters are overridden :

Parameters

preset

The options for SDK preset audio effects:

RoomAcoustics3DVoice, 3D voice effect:
- Call and set the profile parameter in setAudioProfile to MusicStandardStereo (3) or MusicHighQualityStereo(5) before setting this enumerator; otherwise, the enumerator setting does not take effect.
- If the 3D voice effect is enabled, users need to use stereo audio playback devices to hear the anticipated voice effect.
PitchCorrection, Pitch correction effect: To achieve better audio effect quality, Agora recommends calling setAudioProfile and setting the profile parameter to MusicHighQuality (4) or MusicHighQualityStereo(5) before setting this enumerator.

param1

If you set preset to RoomAcoustics3DVoice , param1 sets the cycle period of the 3D voice effect. The value range is [1,60] and the unit is seconds. The default value is 10, indicating that the voice moves around you every 10 seconds.
If you set preset to PitchCorrection , param1 sets the basic mode of the pitch correction effect:
- 1: (Default) Natural major scale.
- 2: Natural minor scale.
- 3: Japanese pentatonic scale.

param2

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

setAudioEffectPreset

Sets an SDK preset audio effect.

Future<void> setAudioEffectPreset(AudioEffectPreset preset);

Detailed Description

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

You can set different audio effects for different scenarios. See Set the Voice Beautifier and Audio Effects.

To get better audio effect quality, Agora recommends calling setAudioProfile and setting the scenario parameter as GameStreaming (3) before calling this method.

Attention:

You can call this method either before or after joining a channel.
Do not set the profile parameter in setAudioProfile to SpeechStandard (1), or the method does not take effect.
This method works best with the human voice. Agora does not recommend using this method for audio containing music.
If you call setAudioEffectPreset and set enumerators except for RoomAcoustics3DVoice or PitchCorrection, do not call setAudioEffectParameters; otherwise, setAudioEffectPreset is overridden.
After calling setAudioEffectPreset, Agora recommends not calling the following methods, because they can override setAudioEffectPreset:

Parameters

preset: The options for SDK preset audio effects. See AudioEffectPreset.

setAudioMixingPitch

Sets the pitch of the local music file.

Future<void> setAudioMixingPitch(int pitch);

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

Attention: You need to call this method after calling startAudioMixing and receiving the audioMixingStateChanged(Playing) callback.

Parameters

pitch: Sets the pitch of the local music file by the chromatic scale. The default value is 0, which means keeping the original pitch. The value ranges from -12 to 12, and the pitch value between consecutive values is a chromatic value. The greater the absolute value of this parameter, the higher or lower the pitch of the local music file.

setAudioMixingPosition

Sets the audio mixing position.

Future<void> setAudioMixingPosition(int pos);

Call this method to set the playback position of the music file to a different starting position (the default plays from the beginning).

Attention: You need to call this method after calling startAudioMixing and receiving the audioMixingStateChanged(PLAY) callback.

Parameters

pos: Integer. The playback position (ms).

setAudioProfile

Sets the audio profile and audio scenario.

Future<void> setAudioProfile(AudioProfile profile, AudioScenario scenario);

Attention:

Ensure that you call this method before joining a channel.
In scenarios requiring high-quality audio, such as online music tutoring, Agora recommends you set profile as MusicHighQuality (4), and scenario as GameStreaming (3).

Parameters

profile: The audio profile, including the sampling rate, bitrate, encoding mode, and the number of channels. See AudioProfile.
scenario: The audio scenario. See AudioScenario. Under different audio scenarios, the device uses different volume types.

setAudioSessionOperationRestriction

Sets the operational permission of the SDK on the audio session.

Future<void> setAudioSessionOperationRestriction(
      AudioSessionOperationRestriction restriction);

The SDK and the app can both configure the audio session by default. If you need to only use the app to configure the audio session, this method restricts the operational permission of the SDK on the audio session.

You can call this method either before or after joining a channel. Once you call this method to restrict the operational permission of the SDK on the audio session, the restriction takes effect when the SDK needs to change the audio session.

Attention:

This method is for iOS only.
This method does not restrict the operational permission of the app on the audio session.

Parameters

restriction: The operational permission of the SDK on the audio session. See AudioSessionOperationRestriction. This parameter is in bit mask format, and each bit corresponds to a permission.

setBeautyEffectOptions

Sets the image enhancement options.

Future<void> setBeautyEffectOptions(bool enabled, BeautyOptions options);

Enables or disables image enhancement, and sets the options.

Attention:

Call this method after enableVideo.

Parameters

enabled

Whether to enable the image enhancement function:

true: Enable the image enhancement function.
false: (Default) Disable the image enhancement function.

options

The image enhancement options. See BeautyOptions.

setCameraAutoFocusFaceModeEnabled

Enables the camera auto-face focus function.

Attention:

Call this method before calling joinChannel, enableVideo, or enableLocalVideo, depending on which method you use to turn on your local camera.

Parameters

enabled

Whether to enable the camera auto-face focus function:

true: Enable the camera auto-face focus function.
false: (Default) Disable the camera auto-face focus function.

Returns

0: Success.
< 0: Failure.

setCameraCapturerConfiguration

Sets the camera capture configuration.

Future<void> setCameraCapturerConfiguration(
      CameraCapturerConfiguration config);

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

If the resolution or frame rate of the captured raw video data are higher than those set by setVideoEncoderConfiguration, processing video frames requires extra CPU and RAM usage and degrades performance. Agora recommends setting the camera capture configuration to Performance(1) to avoid such problems.
If you do not need a local video preview or are willing to sacrifice preview quality, we recommend setting the preference as Performance(1) to optimize CPU and RAM usage.
If you want better quality for the local video preview, we recommend setting config as Preview(2).
To customize the width and height of the video image captured by the local camera, set the camera capture configuration as Manual(3).

Attention:

Call this method before calling joinChannel, enableVideo, or enableLocalVideo, depending on which method you use to turn on your local camera.

Parameters

config: The camera capturer configuration. See CameraCapturerConfiguration.

setCameraExposurePosition

Sets the camera exposure position.

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

This method needs to be called after the camera is started (for example, by calling startPreview or joinChannel).

After a successful method call, the SDK triggers the cameraExposureAreaChanged callback.

Attention: This method is for Android and iOS only.

Parameters

positionXinView: The horizontal coordinate of the touchpoint in the view.
positionYinView: The vertical coordinate of the touchpoint in the view.

setCameraFocusPositionInPreview

Sets the camera manual focus position.

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

This method needs to be called after the camera is started (for example, by calling startPreview or joinChannel). After a successful method call, the SDK triggers the cameraFocusAreaChanged callback.

Attention: This method is for Android and iOS only.

Parameters

positionX: The horizontal coordinate of the touchpoint in the view.
positionY: The vertical coordinate of the touchpoint in the view.

setCameraTorchOn

Enables the camera flash.

Future<void> setCameraTorchOn(bool isOn);

Attention:

Call this method before calling joinChannel, enableVideo, or enableLocalVideo, depending on which method you use to turn on your local camera.

Parameters

isOn

Whether to turn on the camera flash:

true: Turn on the flash.
false: (Default) Turn off the flash.

Returns

0: Success.
< 0: Failure.

setCameraZoomFactor

Sets the camera zoom ratio.

Future<void> setCameraZoomFactor(double factor);

Attention:

Call this method before calling joinChannel, enableVideo, or enableLocalVideo, depending on which method you use to turn on your local camera.

Parameters

factor: The camera zoom ratio. The value ranges between 1.0 and the maximum zoom supported by the device. You can get the maximum zoom ratio supported by the device by calling the getCameraMaxZoomFactor method.

setChannelProfile

Sets the channel profile.

Future<void> setChannelProfile(ChannelProfile profile);

After initializing the SDK, the default channel profile is the communication profile. You can call this method to set the usage scenario of Agora channel. The Agora SDK differentiates channel profiles and applies optimization algorithms accordingly. For example, it prioritizes smoothness and low latency for a video call and prioritizes video quality for interactive live video streaming.

Attention:

To ensure the quality of real-time communication, Agora recommends that all users in a channel use the same channel profile.
This method must be called and set before joinChannel, and cannot be set again after joining the channel.

Parameters

profile: The channel profile. See ChannelProfile for details.

setClientRole

Sets the user role and level in an interactive live streaming channel.

Future<void> setClientRole(ClientRole role, [ClientRoleOptions? options]);

In the interactive live streaming profile, the SDK sets the user role as audience by default. You can call this method to set the user role as host.

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

If you call this method to switch the user role after joining a channel, the SDK automatically does the following:

Calls muteLocalAudioStream and muteLocalVideoStream to change the publishing state.
Triggers clientRoleChanged on the local client.
Triggers userJoined or userOffline on the remote client.

Attention: This method applies to the interactive live streaming profile (the profile parameter of setChannelProfile is LiveBroadcasting) only.

Parameters

role: The user role in the interactive live streaming. For details, see ClientRole.
options: The detailed options of a user, including the user level. See ClientRoleOptions for details.

setCloudProxy

Sets the Agora cloud proxy service.

Future<void> setCloudProxy(CloudProxyType proxyType);

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

After successfully connecting to the cloud proxy, the SDK triggers the connectionStateChanged (Connecting, SettingProxyServer) callback.

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

To disable the cloud proxy that has been set, call the setCloudProxy(None).

To change the cloud proxy type that has been set, call the setCloudProxy(None) first, and then call the setCloudProxy to set the proxyType you want.

Attention:

Agora recommends that you call this method before joining the channel or after leaving the channel.
For the SDK v3.3.x, when users use the Force UDP cloud proxy, the services for Media Push and cohosting across channels are not available; for the SDK v3.4.0 or later, when users behind a firewall use the Force UDP cloud proxy, the services for Media Push and cohosting across channels are not available.
When you use the Force UDP cloud proxy, note that an error would occur when calling the startAudioMixing method to play online music files in the HTTP protocol. The services for Media Push and cohosting across channels use the cloud proxy with the TCP protocol.

Parameters

proxyType

The type of the cloud proxy. See CloudProxyType.

This parameter is mandatory. The SDK reports an error if you do not pass in a value.

setColorEnhanceOptions

Sets color enhancement.

Future<void> setColorEnhanceOptions(bool enabled, ColorEnhanceOptions option);

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

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

Attention:

Call this method after calling enableVideo.
The color enhancement feature has certain performance requirements on devices. With Color Enhancement turned on, Agora recommends that you change the Color Enhancement Level to one that consumes less performance or turn off Color Enhancement if your device is experiencing severe heat problems.

Parameters

enabled

Whether to turn on color enhancement:

true: Enable.
false: (Default) Disable.

option

The color enhancement options. For more details, see ColorEnhanceOptions.

setDefaultAudioRouteToSpeakerphone

Sets the default audio playback route.

Future<void> setDefaultAudioRouteToSpeakerphone(bool defaultToSpeaker);

This method sets whether the received audio is routed to the earpiece or speakerphone by default before joining a channel. If a user does not call this method, the audio is routed to the earpiece by default.

The default settings for each profile:

For the communication profile:
- In a voice call, the default audio route is the earpiece.
- In a video call, the default audio route is the speakerphone. If a user calls the disableVideo, muteLocalVideoStream, or muteAllRemoteVideoStreams method, the default audio route switches back to the earpiece automatically.
For the live broadcasting profile: Speakerphone.

Attention:

This method applies to Android and iOS only.
This method needs to be set before , otherwise, it will not take effect.

Parameters

defaultToSpeaker

The default audio playback route.

true: The audio routing is speakerphone. If the device connects to the earpiece or Bluetooth, the audio cannot be routed to the speakerphone.
false: (Default) Route the audio to the earpiece. If a headset is plugged in, the audio is routed to the headset.

setDefaultMuteAllRemoteAudioStreams

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

Future<void> setDefaultMuteAllRemoteAudioStreams(bool muted);

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

Attention:

If you need to resume subscribing to the audio streams of remote users in the channel after calling this method, do the following:

To resume subscribing to the audio stream of a specified user, call muteRemoteAudioStream(false), and specify the user ID.
To resume subscribing to the audio streams of multiple remote users, call muteRemoteAudioStream (false)multiple times.

Parameters

muted

Whether to stop subscribing to the audio streams of all remote users by default.

true: Stop subscribing to the audio streams of all remote users by default.
false: (Default) Subscribe to the audio streams of all remote users by default.

setDefaultMuteAllRemoteVideoStreams

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

Future<void> setDefaultMuteAllRemoteVideoStreams(bool muted);

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

Attention:

If you need to resume subscribing to the audio streams of remote users in the channel after calling this method, do the following:

To resume subscribing to the audio stream of a specified user, call muteRemoteVideoStream(false), and specify the user ID.
To resume subscribing to the audio streams of multiple remote users, call muteRemoteVideoStream(false)multiple times.

Parameters

muted

Whether to stop subscribing to the audio streams of all remote users by default.

true: Stop subscribing to the audio streams of all remote users by default.
false: (Default) Resume subscribing to the audio streams of all remote users by default.

setEffectPosition

Sets the playback position of an audio effect file.

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

After a successful setting, the local audio effect file starts playing at the specified position.

Attention: Call this method after playEffect.

Parameters

soundId: The audio effect ID. The ID of each audio effect file is unique.
pos: The playback position (ms) of the audio effect file.

setEffectsVolume

Sets the volume of the audio effects.

Future<void> setEffectsVolume(int volume);

Attention: Call this method after playEffect.

Parameters

volume: The playback volume. The value ranges from 0 to 100. The default value is 100, which represents the original volume.

setEnableSpeakerphone

Enables/Disables the audio playback route to the speakerphone.

Future<void> setEnableSpeakerphone(bool speakerOn);

This method sets whether the audio is routed to the speakerphone or earpiece. After a successful method call, the SDK triggers the audioRouteChanged callback.

Attention:

Ensure that you have joined a channel before calling this method.

Parameters

speakerOn

Whether the audio is routed to the speakerphone or earpiece.

true: Route the audio to the speakerphone. If the device connects to the earpiece or Bluetooth, the audio cannot be routed to the speakerphone.
false: Route the audio to the earpiece. If a headset is plugged in, the audio is routed to the headset.

setEncryptionMode

Sets the built-in encryption mode.

Future<void> setEncryptionMode(EncryptionMode encryptionMode);

Deprecated:: Use enableEncryption instead.

The Agora SDK supports built-in encryption, which is set to the AES-128-XTS mode by default. Call this method to use other encryption modes. All users in the same channel must use the same encryption mode and secret. Refer to the information related to the AES encryption algorithm on the differences between the encryption modes.

Attention: Before calling this method, please call setEncryptionSecret to enable the built-in encryption function.

Parameters

encryptionMode

Encryption mode.

"aes-128-xts": 128-bit AES encryption, XTS mode.
"aes-128-ecb": 128-bit AES encryption, ECB mode.
"aes-256-xts": 256-bit AES encryption, XTS mode.
"sm4-128-ecb": 128-bit SM4 encryption, ECB mode.
"aes-128-gcm": 128-bit AES encryption, GCM mode.
"aes-256-gcm": 256-bit AES encryption, GCM mode.
"": When setting as NULL, the encryption mode is set as "aes-128-xts" by default.

setEncryptionSecret

Enables built-in encryption with an encryption password before users join a channel.

Future<void> setEncryptionSecret(String secret);

Deprecated:: This method is deprecated from v3.2.0. Please use enableEncryption instead.

Before joining the channel, you need to call this method to set the secret parameter to enable the built-in encryption. All users in the same channel should use the same secret. The secret is automatically cleared once a user leaves the channel. If you do not specify the secret or secret is set as null, the built-in encryption is disabled.

Attention:

Do not use this method for CDN live streaming.
For optimal transmission, ensure that the encrypted data size does not exceed the original data size + 16 bytes. 16 bytes is the maximum padding size for AES encryption.

Parameters

secret: The encryption password.

setInEarMonitoringVolume

Sets the volume of the in-ear monitor.

Future<void> setInEarMonitoringVolume(int volume);

Attention:

This method is for Android and iOS only.
Users must use wired earphones to hear their own voices.
You can call this method either before or after joining a channel.

Parameters

volume: The volume of the in-ear monitor. The value ranges between 0 and 100. The default value is 100.

setLocalPublishFallbackOption

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

Future<void> setLocalPublishFallbackOption(StreamFallbackOptions option);

An unstable network affects the audio and video quality in a video call or interactive live video streaming. If option is set as AudioOnly(2), the SDK disables the upstream video but enables audio only when the network conditions deteriorate and cannot support both video and audio. The SDK monitors the network quality and restores the video stream when the network conditions improve. When the published video stream falls back to audio-only or when the audio-only stream switches back to the video, the SDK triggers the localPublishFallbackToAudioOnly callback.

Attention:

Agora does not recommend using this method for CDN live streaming, because the remote CDN live user will have a noticeable lag when the published video stream falls back to AudioOnly(2).
Ensure that you call this method before joining a channel.

Parameters

option: The stream fallback option. For details, see StreamFallbackOptions.

setLocalVoiceChanger

Sets the local voice changer option.

Future<void> setLocalVoiceChanger(AudioVoiceChanger voiceChanger);

Deprecated:

Deprecated from v3.2.0. Use the following methods instead:

setAudioEffectPreset : Audio effects.
setVoiceBeautifierPreset : Voice beautifier effects.
setVoiceConversionPreset : Voice conversion effects.

This method can be used to set the local voice effect for users in a COMMUNICATION channel or hosts in a LIVE_BROADCASTING channel. After successfully calling this method, all users in the channel can hear the voice with reverberation.

VOICE_CHANGER_XXX: Changes the local voice to an old man, a little boy, or the Hulk. Applies to the voice talk scenario.
VOICE_BEAUTY_XXX: Beautifies the local voice by making it sound more vigorous, resounding, or adding spacial resonance. Applies to the voice talk and singing scenario.
GENERAL_VOICE_BEAUTY_XXX: Adds gender-based beautification effect to the local voice. Applies to the voice talk scenario. For a male voice: Adds magnetism to the voice. For a male voice: Adds magnetism to the voice. For a female voice: Adds freshness or vitality to the voice.

Attention:

To achieve better voice effect quality, Agora recommends setting the setAudioProfileprofile parameter in asMusicHighQuality (4) orMusicHighQualityStereo (5).
This method works best with the human voice, and Agora does not recommend using it for audio containing music and a human voice.
Do not use this method with setLocalVoiceReverbPreset, because the method called later overrides the one called earlier. For detailed considerations, see the advanced guide Set the Voice Effect.
You can call this method either before or after joining a channel.

Parameters

voiceChanger: The local voice changer option. The default value is Off , which means the original voice. For more details, see AudioVoiceChanger. The gender-based beatification effect works best only when assigned a proper gender. Use GENERAL_BEAUTY_VOICE_MALE_MAGNETIC for male and use GENERAL_BEAUTY_VOICE_FEMALE_FRESH and GENERAL_BEAUTY_VOICE_FEMALE_VITALITY for female. Failure to do so can lead to voice distortion.

setLocalVoiceEqualization

Sets the local voice equalization effect.

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

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

Parameters

bandFrequency: The band frequency. The value ranges between 0 and 9; representing the respective 10-band center frequencies of the voice effects, including 31, 62, 125, 250, 500, 1k, 2k, 4k, 8k, and 16k Hz. For more details, see AudioEqualizationBandFrequency.
bandGain: The gain of each band in dB. The value ranges between -15 and 15. The default value is 0.

setLocalVoicePitch

Changes the voice pitch of the local speaker.

Future<void> setLocalVoicePitch(double pitch);

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

Parameters

pitch: The local voice pitch. The value range is [0.5,2.0]. The lower the value, the lower the pitch. The default value is 1 (no change to the pitch).

setLocalVoiceReverb

Sets the local voice reverberation.

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

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

Parameters

reverbKey: The reverberation key. Agora provides 5 reverberation keys: AudioReverbType.
value: The value of the reverberation key.

setLocalVoiceReverbPreset

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

Future<void> setLocalVoiceReverbPreset(AudioReverbPreset preset);

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

Attention:

When using the enumeration value prefixed with AUDIO_REVERB_FX, ensure that you set the profile parameter in setAudioProfile toMusicHighQuality(4) or MusicHighQualityStereo(5) before calling this method. Otherwise, the method setting is invalid.
When calling the VIRTUAL_STEREO method, Agora recommends setting the profile parameter in setAudioProfile as MusicHighQualityStereo(5).
This method works best with the human voice, and Agora does not recommend using it for audio containing music and a human voice.
Do not use this method with setLocalVoiceChanger, because the method called later overrides the one called earlier. For detailed considerations, see the advanced guide Set the Voice Effect.
You can call this method either before or after joining a channel.

Parameters

preset: The local voice reverberation option. The default value is Off, which means the original voice. For more details, see AudioReverbPreset. To achieve better voice effects, Agora recommends the enumeration whose name begins with AUDIO_REVERB_FX.

setLogFile

Sets the log files that the SDK outputs.

Future<void> setLogFile(String filePath);

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

Attention: Ensure that you call this method immediately after initializing RtcEngine, otherwise, the output log may not be complete.

Parameters

filePath: The absolute path of the log files. The default file path is C: \Users\<user_name>\AppData\Local\Agora\<process_name>\agorasdk.log. Ensure that the directory for the log files exists and is writable. You can use this parameter to rename the log files.

setLogFileSize

Sets the size of a log file that the SDK outputs.

Future<void> setLogFileSize(int fileSizeInKBytes);

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

Attention: If you want to set the size of the log file, you need to call this method before setLogFile, otherwise, the log will be cleared.

Parameters

fileSizeInKBytes: The size (KB) of a log file. The default value is 1024 KB. If you set fileSizeInKByte to 1024 KB, the maximum aggregate size of the log files output by the SDK is 5 MB. if you set fileSizeInKByte to less than 1024 KB, the setting is invalid, and the maximum size of a log file is still 1024 KB.

setLogFilter

Sets the log output level of the SDK.

Future<void> setLogFilter(LogFilter filter);

This method sets the output log level of the SDK. You can use one or a combination of the log filter levels. The log level follows the sequence of OFF, CRITICAL, ERROR, WARNING, INFO, and DEBUG. Choose a level to see the logs preceding that level.

If, for example, you set the log level to WARNING, you see the logs within levels CRITICAL, ERROR, and WARNING.

Parameters

filter: The output log level of the SDK. For details, see LogFilter.

setLowlightEnhanceOptions

Sets low-light enhancement.

Future<void> setLowlightEnhanceOptions(
                bool enabled, LowLightEnhanceOptions option);

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

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

Attention:

Call this method after calling enableVideo.
Dark light enhancement has certain requirements for equipment performance. The low-light enhancement feature has certain performance requirements on devices. If your device overheats after you enable low-light enhancement, Agora recommends modifying the low-light enhancement options to a less performance-consuming level or disabling low-light enhancement entirely.

Parameters

enabled

Sets whether to enable low-light enhancement:

true: Enable.
false: (Default) Disable.

option

The low-light enhancement options. For more details, see LowLightEnhanceOptions.

setMaxMetadataSize

Sets the maximum size of the media metadata.

Future<void> setMaxMetadataSize(int size);

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

Parameters

size: The maximum size of media metadata.

setParameters

Provides technical preview functionalities or special customizations by configuring the SDK with JSON options.

Future<void> setParameters(String parameters);

The JSON options are not public by default. Agora is working on making commonly used JSON options public in a standard way.

Parameters

parameters: Sets the parameter as a JSON string in the specified format.

setRemoteDefaultVideoStreamType

Sets the default stream type of remote video streams.

Future<void> setRemoteVideoStreamType(int userId, VideoStreamType streamType);

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

By default, users receive the high-quality video stream. Call this method if you want to switch to the low-quality video stream. This method allows the app to adjust the corresponding video stream type based on the size of the video window to reduce the bandwidth and resources. The aspect ratio of the low-quality video stream is the same as the high-quality video stream. Once the resolution of the high-quality video stream is set, the system automatically sets the resolution, frame rate, and bitrate of the low-quality video stream.

The result of this method returns in the apiCallExecuted callback.

Attention: You can call this method either before or after joining a channel. If you call both setRemoteVideoStreamType and setRemoteDefaultVideoStreamType, the settings in setRemoteVideoStreamType take effect.

Parameters

streamType: The default stream type of the remote video, see VideoStreamType.

setRemoteSubscribeFallbackOption

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

Future<void> setRemoteSubscribeFallbackOption(StreamFallbackOptions option);

Unreliable network conditions affect the overall quality of the interactive live streaming. If option is set as VideoStreamLow(1) or AudioOnly(2), the SDK automatically switches the video from a high-quality stream to a low-quality stream or disables the video when the downlink network conditions cannot support both audio and video to guarantee the quality of the audio. The SDK monitors the network quality and restores the video stream when the network conditions improve. When the remote video stream falls back to audio-only or when the audio-only stream switches back to the video, the SDK triggers the remoteSubscribeFallbackToAudioOnly callback.

Attention: Ensure that you call this method before joining a channel.

Parameters

option: The fallback option for the remotely subscribed video stream. The default value is VideoStreamLow(1). See StreamFallbackOptions.

setRemoteUserPriority

Prioritizes a remote user's stream.

Future<void> setRemoteUserPriority(int uid, UserPriority userPriority);

Prioritizes a remote user's stream. The SDK ensures the high-priority user gets the best possible stream quality. The SDK ensures the high-priority user gets the best possible stream quality.

Attention:

The SDK supports setting only one user as high priority.
Ensure that you call this method before joining a channel.

Parameters

uid: The ID of the remote user.
userPriority: The priority of the remote user. See UserPriority.

setRemoteVideoStreamType

Sets the stream type of the remote video.

Future<void> setRemoteVideoStreamType(int userId, VideoStreamType streamType);

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

By default, users receive the high-quality video stream. Call this method if you want to switch to the low-quality video stream. This method allows the app to adjust the corresponding video stream type based on the size of the video window to reduce the bandwidth and resources. The aspect ratio of the low-quality video stream is the same as the high-quality video stream. Once the resolution of the high-quality video stream is set, the system automatically sets the resolution, frame rate, and bitrate of the low-quality video stream.

The method result returns in the apiCallExecuted callback.

Attention: You can call this method either before or after joining a channel. If you call both setRemoteVideoStreamType and setRemoteDefaultVideoStreamType, the setting of setRemoteVideoStreamType takes effect.

Parameters

userId: User ID.
streamType: The video stream type: VideoStreamType.

setRemoteVoicePosition

Sets the 2D position (the position on the horizontal plane) of the remote user's voice.

Future<void> setRemoteVoicePosition(int uid, double pan, double gain);

This method sets the 2D position and volume of a remote user, so that the local user can easily hear and identify the remote user's position.

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

Attention:

For this method to work, enable stereo panning for remote users by calling the enableSoundPositionIndication method before joining a channel.
For the best voice positioning, Agora recommends using a wired headset.
Call this method after joining a channel.

Parameters

uid

The user ID of the remote user.

pan

The voice position of the remote user. The value ranges from -1.0 to 1.0:

0.0: (Default) The remote voice comes from the front.
-1.0: The remote voice comes from the left.
1.0: The remote voice comes from the right.

gain

The volume of the remote user. The value ranges from 0.0 to 100.0. The default value is 100.0 (the original volume of the remote user). The smaller the value, the lower the volume.

setScreenCaptureContentHint

Sets the content hint for screen sharing.

Future<void> setScreenCaptureContentHint(VideoContentHint contentHint);

A content hint suggests the type of the content being shared, so that the SDK applies different optimization algorithms to different types of content. If you don't call this method, the default content hint is None.

Attention: You can call this method either before or after you start screen sharing.

Parameters

contentHint: The content hint for screen sharing. For details, see VideoContentHint.

setScreenCaptureScenario

Sets the screen sharing scenario.

Future<void> setScreenCaptureScenario(ScreenScenarioType screenScenario);

When you start screen sharing or window sharing, you can call this method to set the screen sharing scenario. The SDK adjusts the video quality and experience of the sharing according to the scenario.

Parameters

screenScenario: The screen sharing scenario. See ScreenScenarioType.

setVideoDenoiserOptions

Sets video noise reduction.

Future<void> setVideoDenoiserOptions(
                bool enabled, VideoDenoiserOptions option);

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

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

Attention:

Call this method after calling enableVideo.
Video noise reduction has certain requirements for equipment performance. If your device overheats after you enable video noise reduction, Agora recommends modifying the video noise reduction options to a less performance-consuming level or disabling video noise reduction entirely.

Parameters

enabled

Sets whether to enable video noise reduction:

true: Enable.
false: (Default) Disable.

options

The video noise reduction options. For more details, see VideoDenoiserOptions.

setVideoEncoderConfiguration

Sets the video encoder configuration.

Future<void> setVideoEncoderConfiguration(VideoEncoderConfiguration config);

Sets the encoder configuration for the local video.

Attention: You can call this method either before or after joining a channel. If you don't need to set the video encoder configuration after joining a channel, Agora recommends you calling this method before the enableVideo method to reduce the rendering time of the first video frame.

Parameters

config: Video profile. See VideoEncoderConfiguration.

setVoiceBeautifierParameters

Sets parameters for the preset voice beautifier effects.

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

Since: v3.3.0

Call this method to set a gender characteristic and a reverberation effect for the singing beautifier effect. This method sets parameters for the local user who sends an audio stream. After setting the audio parameters, all users in the channel can hear the effect.

For better voice effects, Agora recommends that you call setAudioProfile and setscenario to GameStreaming(3) and profile to MusicHighQuality(4) or MusicHighQualityStereo(5) before calling this method.

Attention:

You can call this method either before or after joining a channel.
Do not set the profile parameter of setAudioProfile to SpeechStandard(1). Otherwise, the method does not take effect.
This method works best with the human voice. Agora does not recommend using this method for audio containing music.
After calling setVoiceBeautifierParameters, Agora recommends not calling the following methods, because they can override settings in setVoiceBeautifierParameters:

Parameters

preset

The option for the preset audio effect:

SINGING_BEAUTIFIER: The singing beautifier effect.

param1

The gender characteristics options for the singing voice:

1: A male-sounding voice.
2: A female-sounding voice.

param2

The reverberation effect options for the singing voice:

1: The reverberation effect sounds like singing in a small room.
2: The reverberation effect sounds like singing in a large room.
3: The reverberation effect sounds like singing in a hall.

setVoiceBeautifierPreset

Sets a preset voice beautifier effect.

Future<void> setVoiceBeautifierPreset(VoiceBeautifierPreset preset);

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

For better voice effects, Agora recommends that you call setAudioProfile and set scenario to GameStreaming (3) and profile to MusicHighQuality (4) or MusicHighQualityStereo (5) before calling this method.

Attention:

You can call this method either before or after joining a channel.
Do not set the profile parameter in setAudioProfile to SpeechStandard(1), or the method does not take effect.
This method works best with the human voice. Agora does not recommend using this method for audio containing music.
After calling setVoiceBeautifierPreset, Agora recommends not calling the following methods, because they can override setVoiceBeautifierPreset:

Parameters

preset: The preset voice beautifier effect options: VoiceBeautifierPreset.

setVoiceConversionPreset

Sets a preset voice beautifier effect.

Future<void> setVoiceConversionPreset(VoiceConversionPreset preset);

Call this method to set a preset voice beautifier effect for the local user who sends an audio stream. After setting an audio effect, all users in the channel can hear the effect. You can set different audio effects for different scenarios. See Set the Voice Beautifier and Audio Effects.

To achieve better audio effect quality, Agora recommends that you call setAudioProfile and set the profile to MusicHighQuality(4) or MusicHighQualityStereo(5) and scenario to GameStreaming(3) before calling this method.

Attention:

You can call this method either before or after joining a channel.
Do not setsetAudioProfile the profile parameter in to SpeechStandard(1), or the method does not take effect.
This method works best with the human voice. Agora does not recommend using this method for audio containing music.
After calling setVoiceConversionPreset, Agora recommends not calling the following methods, or the settings in setVoiceConversionPreset are overridden :

Parameters

preset: The options for the preset voice beautifier effects: VoiceConversionPreset.

setVolumeOfEffect

Sets the volume of a specified audio effect.

Future<void> setVolumeOfEffect(int soundId, int volume);

Attention: Call this method after playEffect.

Parameters

soundId: The audio effect ID. The ID of each audio effect file is unique.
volume: The playback volume. The value ranges from 0 to 100. The default value is 100, which represents the original volume.

startAudioMixing

Starts playing the music file.

Future<void> startAudioMixing(
      String filePath, bool loopback, bool replace, int cycle,
      [int? startPos]);

This method mixes the specified local or online audio file with the audio from the microphone, or replaces the microphone's audio with the specified local or remote audio file. A successful method call triggers the audioMixingStateChanged (PLAY) callback. When the audio mixing file playback finishes, the SDK triggers the audioMixingStateChanged (STOPPED) callback on the local client.

Attention:

Call this method after joining a channel. If you need to call startAudioMixing multiple times, ensure that the time interval between calling this method is more than 500 ms.
If the local audio mixing file does not exist, or if the SDK does not support the file format or cannot access the music file URL, the SDK returns WARN_AUDIO_MIXING_OPEN_ERROR (701).

Parameters

filePath

The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example:

Android: /sdcard/emulated/0/audio.mp4, iOS:
                        /var/mobile/Containers/Data/audio.mp4

. Supported audio formats include MP3, AAC, M4A, MP4, WAV, and 3GP. See supported audio formats.

loopback

Whether to only play music files on the local client:

true: Only play music files on the local client so that only the local user can hear the music.
false: Publish music files to remote clients so that both the local user and remote users can hear the music.

replace

Whether to replace the audio captured by the microphone with a music file:

true: Replace the audio captured by the microphone with a music file. Users can only hear the music.
false: Do not replace the audio captured by the microphone with a music file. Users can hear both music and audio captured by the microphone.

cycle

The number of times the music file plays.

≥ 0: The number of playback times. For example, 0 means that the SDK does not play the music file while 1 means that the SDK plays once.
-1: Play the music effect in an infinite loop.

startPos

The playback position (ms) of the music file.

startAudioRecording

Starts audio recording on the client.

Future<void> startAudioRecording(String filePath,
      AudioSampleRateType sampleRate, AudioRecordingQuality quality);

Deprecated:: This method is deprecated as of v3.4.0. Please use startAudioRecordingWithConfig instead.

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

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

Attention:

Ensure that the directory you use to save the recording file exists and is writable.
This method should be called after the joinChannel method. The recording automatically stops when you call the leaveChannel method.
For better recording effects, set quality to Medium or High when sampleRate is 44.1 kHz or 48 kHz.

Parameters

filePath

The absolute path (including the filename extensions) of the recording file. For example: C:\music\audio.aac .

Attention: Ensure that the directory for the log files exists and is writable.

sampleRate

The sample rate (kHz) of the recording file. Supported values are as follows:

16000
(Default) 32000
44100
48000

quality

Recording quality. For more details, see AudioRecordingQuality.

startAudioRecordingWithConfig

Starts audio recording on the client.

Future<void> startAudioRecordingWithConfig(
      AudioRecordingConfiguration config);

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

WAV: Large file size with high fidelity. For example, if the sample rate is 32,000 Hz, the file size for a recording duration of 10 minutes is around 73 M.
AAC: Small file size with low fidelity. For example, if the sample rate is 32,000 Hz and the recording quality is Medium, the file size for a recording duration of 10 minutes is around 2 M.

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

Attention: Call this method after joining a channel.

Parameters

config: Recording configuration. See AudioRecordingConfiguration.

startChannelMediaRelay

Starts relaying media streams across channels. This method can be used to implement scenarios such as co-host across channels.

Future<void> startChannelMediaRelay(
      ChannelMediaRelayConfiguration channelMediaRelayConfiguration);

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

If the channelMediaRelayStateChanged callback returns Running (2) and None (0), and the channelMediaRelayEvent callback returns SentToDestinationChannel (4), it means that the SDK starts relaying media streams between the source channel and the destination channel.
If the channelMediaRelayStateChanged callback returns Failure (3), an exception occurs during the media stream relay.

Attention:

Call this method after joining the channel.
This method takes effect only when you are a host in a live streaming channel.
After a successful method call, if you want to call this method again, ensure that you call the stopChannelMediaRelay method to quit the current relay.
You need to mailto:support@agora.io before implementing this function.
We do not support string user accounts in this API.

Parameters

channelMediaRelayConfiguration: The configuration of the media stream relay. See ChannelMediaRelayConfiguration for details.

startEchoTest

Starts an audio call test.

  Future<void> startEchoTest(
      {int? intervalInSeconds, EchoTestConfiguration? config});

This method starts an audio call test to determine whether the audio devices (for example, headset and speaker) and the network connection are working properly. To conduct the test, let the user speak for a while, and the recording is played back within the set interval. If the user can hear the recording within the interval, the audio devices and network connection are working properly.

Attention:

Call this method before joining a channel.
After calling stopEchoTest, you must call startEchoTest to end the test. Otherwise, the app cannot perform the next echo test, and you cannot join the channel.
In the live streaming channels, only a host can call this method.

Parameters

intervalInSeconds: The time interval (s) between when you speak and when the recording plays back.

startLastmileProbeTest

Starts the last mile network probe test.

Future<void> startLastmileProbeTest(LastmileProbeConfig config);

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

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

lastmileQuality: The SDK triggers this callback within two seconds depending on the network conditions. This callback rates the network conditions and is more closely linked to the user experience.
lastmileProbeResult: The SDK triggers this callback within 30 seconds depending on the network conditions. This callback returns the real-time statistics of the network conditions and is more objective.

This method applies to the following scenarios:

Before a user joins a channel, call this method to check the uplink network quality.
In a live streaming channel, call this method to check the uplink network quality before an audience member switches to a host.

Attention:

This method consumes extra network traffic and may affect communication quality. We do not recommend calling this method and enableLastmileTest at the same time.
Do not call other methods before receiving the lastmileQuality and lastmileProbeResult callbacks. Otherwise, the callbacks may be interrupted.
A host should not call this method after joining a channel (when in a call).

Parameters

config: The configurations of the last-mile network probe test. See LastmileProbeConfig.

startPreview

Enables the local video preview.

Future<void> startPreview();

This method starts the local video preview before joining the channel. Before calling this method, ensure that you do the following:

Call enableVideo to enable the video.

Attention:

The local preview enables the mirror mode by default.
After the local video preview is enabled, if you call leaveChannel to exit the channel, the local preview remains until you call stopPreview to disable it.

startScreenCaptureMobile

Starts screen sharing. This method is only available on Android and iOS.

Future<void> startScreenCaptureMobile(ScreenCaptureParameters2 parameters);

On Android, during screen sharing, make sure the following:

The user has granted screen capture permission to the application; otherwise, the SDK triggers the localVideoStateChanged callback and reports ScreenCapturePermissionDenied(16).
The Android API level is not earlier than 21; otherwise, the method call fails and returns ScreenCaptureSystemNotSupported(2).
To capture system audio during screen sharing, ensure that the Android API level is not earlier than 29 as well; otherwise, the method call fails and returns ScreenCaptureSystemAudioNotSupported(3).

On iOS, when the screen sharing extension process starts, ends, or quits unexpectedly, the SDK triggers the localVideoStateChanged callback and reports ExtensionCaptureStarted(13), ExtensionCaptureStoped(14), and ExtensionCaptureDisconnected(15) respectively.

Attention:

Call this method after joining a channel.
The billing of the screen sharing stream is based on the value of dimensions in ScreenVideoParameters When you do not pass in a value, Agora bills you at 1280 × 720; when you pass a value in, Agora bills you at that value. For details, see Pricing for Real-time Communication.
On Android, note the following:
- On Android 9 and later, to avoid the application being killed by the system after going to the background, Agora recommends you add the foreground service permission android.permission.FOREGROUND_SERVICE to the /app/Manifests/AndroidManifest.xml file.
- Due to performance limitations, screen sharing is not supported on Android TV.
- Due to system limitations, if you are using Huawei phones, do not adjust the video encoding resolution of the screen sharing stream during the screen sharing, or you could experience crashes.
On iOS, note the following:
- This feature is only available for iOS 11 or later.
- This feature requires a high-performance device. Agora recommends that you use this feature on iPhone X or later models.
- If you are using the custom audio source instead of the SDK to capture audio, Agora recommends you add the keep-alive processing logic to your application to avoid screen sharing stopping when the application goes to the background.

Parameters

parameters: The configuration of the screen sharing. See ScreenCaptureParameters2.

startScreenCaptureByDisplayId

Shares the screen by specifying the display ID.

Future<void> startScreenCaptureByDisplayId(int displayId,
      [Rectangle? regionRect, ScreenCaptureParameters? captureParams]);

This method shares a screen or part of the screen. You need to specify the ID of the screen to be shared in this method.

Attention:

This method applies to macOS and Windows only.
Call this method after joining a channel.
On the Windows platform, if the user device is connected to another display, to avoid screen sharing issues, use this method to start sharing instead of using startScreenCaptureByScreenRect.

Parameters

displayId: The display ID of the screen to be shared. This parameter specifies which screen you want to share.
regionRect: (Optional) Sets the relative location of the region to the screen. If you do not set this parameter, the SDK shares the whole screen. See Rectangle for details. If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen.
captureParams: Screen sharing configurations. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges. See ScreenCaptureParameters for details.

startScreenCaptureByScreenRect

Shares the whole or part of a screen by specifying the screen rect.

Future<void> startScreenCaptureByScreenRect(Rectangle screenRect,
      [Rectangle? regionRect, ScreenCaptureParameters? captureParams]);

This method shares a screen or part of the screen. You need to specify the area of the screen to be shared.

Attention:

This method applies to the Windows platform only.
Call this method after joining a channel.

Parameters

screenRect: Sets the relative location of the screen to the virtual screen.
regionRect: (Optional) Sets the relative location of the region to the screen. If you do not set this parameter, the SDK shares the whole screen. See Rectangle. If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen.
captureParams: The screen sharing encoding parameters. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges. See ScreenCaptureParameters.

startScreenCaptureByWindowId

Shares the whole or part of a window by specifying the window ID.

Future<void> startScreenCaptureByWindowId(int windowId,
      [Rectangle? regionRect, ScreenCaptureParameters? captureParams]);

This method shares a window or part of the window. You need to specify the ID of the window to be shared.

Attention:

Call this method after joining a channel.
This method applies to macOS and Windows only.

Parameters

windowId: The ID of the window to be shared.
regionRect: (Optional) Sets the relative location of the region to the screen. If you do not set this parameter, the SDK shares the whole screen. For details, see Rectangle. If the specified region overruns the window, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole window.
captureParams: Screen sharing configurations. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges. For details, see ScreenCaptureParameters.

startRtmpStreamWithoutTranscoding

Starts pushing media streams to a CDN without transcoding.

Future<void> startRtmpStreamWithoutTranscoding(String url);

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

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

Attention:

Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in Push Streams to CDN.
Call this method after joining a channel.
Only hosts in the LIVE_BROADCASTING profile can call this method.
If you want to retry pushing streams after a failed push, make sure to call stopRtmpStream first, then call this method to retry pushing streams; otherwise, the SDK returns the same error code as the last failed push.

Parameters

url: The address of Media Push. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported.

startRtmpStreamWithTranscoding

Starts Media Push and sets the transcoding configuration.

Future<void> startRtmpStreamWithTranscoding(LiveTranscoding transcoding);

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

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

Attention:

Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in Push Streams to CDN.
Call this method after joining a channel.
Only hosts in the LIVE_BROADCASTING profile can call this method.
If you want to retry pushing streams after a failed push, make sure to call stopRtmpStream first, then call this method to retry pushing streams; otherwise, the SDK returns the same error code as the last failed push.

Parameters

url: The address of Media Push. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported.
transcoding: The transcoding configuration for Media Push. See LiveTranscoding.

stopAllEffects

Stops playing all audio effects.

Future<void> stopAllEffects();

stopAudioMixing

Stops playing and mixing the music file.

Future<void> stopAudioMixing();

This method stops the audio mixing. Call this method when you are in a channel.

stopAudioRecording

Stops the audio recording on the client.

Future<void> stopAudioRecording();

If you call startAudioRecordingWithConfig to start recording, you can call this method to stop the recording.

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

stopChannelMediaRelay

Stops the media stream relay. Once the relay stops, the host quits all the destination channels.

Future<void> stopChannelMediaRelay();

After a successful method call, the SDK triggers the channelMediaRelayStateChanged callback. If the callback reports Idle (0) and None (0), the host successfully stops the relay.

Attention: If the method call fails, the SDK triggers the channelMediaRelayStateChanged callback with the ServerNoResponse (2) or ServerConnectionLost (8) status code. You can call the leaveChannel method to leave the channel, and the media stream relay automatically stops.

stopEchoTest

Stops the audio call test.

Future<void> stopEchoTest();

stopEffect

Stops playing a specified audio effect.

Future<void> stopEffect(int soundId);

Parameters

soundId: The audio effect ID. The ID of each audio effect file is unique.

stopLastmileProbeTest

Stops the last mile network probe test.

Future<void> stopLastmileProbeTest();

stopPreview

Stops the local video preview.

Future<void> stopPreview();

stopRtmpStream

Stops pushing media streams to a CDN.

Future<void> stopRtmpStream(String url);

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

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

Parameters

url: The address of Media Push. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported.

stopScreenCapture

Stops screen sharing.

Future<void> stopScreenCapture();

switchCamera

Switches between front and rear cameras.

Future<void> switchCamera();

This method needs to be called after the camera is started (for example, by calling startPreview or joinChannel).

switchChannel

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

Future<void> switchChannel(String? token, String channelName,
      [ChannelMediaOptions? options]);

This method allows the audience of a LIVE_BROADCASTING channel to switch to a different channel.

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

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

Parameters

token

The token generated at your server.

In scenarios with low security requirements, token is optional and can be set as null.
In scenarios with high security requirements, set the value to the token generated from your server. If you enable the App Certificate, you must use a token to join the channel.

CAUTION: Ensure that the App ID used for creating the token is the same App ID used by the createWithContext method for initializing the RTC engine.

channelName

The name of the channel. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channelId enter the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported characters:

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

options

The channel media options. See ChannelMediaOptions.

takeSnapshot

Takes a snapshot of a video stream.

Future<void> takeSnapshot(String channel, int uid, String filePath);

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

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

Attention:

Call this method after joining a channel.
If the video of the specified user is pre-processed, for example, added with watermarks or image enhancement effects, the generated snapshot also includes the pre-processing effects.

Parameters

channel

The channel name.

uid

The user ID. Set uid as 0 if you want to take a snapshot of the local user's video.

filePath

The local path (including the filename extensions) of the snapshot. 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

Ensure that the path you specify exists and is writable.

unloadEffect

Releases a specified preloaded audio effect from the memory.

Future<void> unloadEffect(int soundId);

Parameters

soundId: The audio effect ID. The ID of each audio effect file is unique.

unregisterMediaMetadataObserver

Unregisters the specified metadata observer.

Future<void> unregisterMediaMetadataObserver();

updateChannelMediaRelay

Updates the channels for media stream relay.

Future<void> updateChannelMediaRelay(
      ChannelMediaRelayConfiguration channelMediaRelayConfiguration);

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

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

Attention: Call this method after the startChannelMediaRelay method to update the destination channel.

Parameters

channelMediaRelayConfiguration: The configuration of the media stream relay. For more details, see ChannelMediaRelayConfiguration.

updateRtmpTranscoding

Updates the transcoding configuration.

Future<void> updateRtmpTranscoding(LiveTranscoding transcoding);

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

Parameters

transcoding: The transcoding configuration for Media Push. See LiveTranscoding.

updateScreenCaptureParameters

Updates the screen sharing parameters.

Future<void> updateScreenCaptureParameters(
      ScreenCaptureParameters captureParams);

Parameters

captureParams: The screen sharing encoding parameters. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges. For details, see ScreenCaptureParameters.

updateScreenCaptureParametersMobile

Updates the screen sharing configuration. This method is only available on Android and iOS.

  Future<void> updateScreenCaptureParametersMobile(
      ScreenCaptureParameters2 parameters);

Parameters

parameters: The configuration of the screen sharing. See ScreenCaptureParameters2.

updateScreenCaptureRegion

Updates the screen sharing region.

Future<void> updateScreenCaptureRegion(Rectangle regionRect);

Parameters

regionRect: The relative location of the screen-shared area to the screen or window. If you do not set this parameter, the SDK shares the whole screen or window. See Rectangle. If the specified region overruns the screen or window, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen or window.

uploadLogFile

Uploads all SDK log files.

Future<String?> uploadLogFile();

Since: v3.3.0

Uploads all SDK log files from the client to the Agora server. After calling this method successfully, the SDK triggers the uploadLogResult callback to report whether the log file is successfully uploaded to the Agora server.

For easier debugging, Agora recommends that you bind the uploadLogFile method to the UI element of your app, to instruct the user to upload a log file when a quality issue occurs.

Parameters

Returns

The method call succeeds: Return the request ID. The request ID is the same as the requestId in the uploadLogResult callback. You can use the requestId to match a specific upload with a callback.
The method callI fails: Returns null. Probably because the method call frequency exceeds the limit.