IAgoraRtcEngine

The basic interface of the Agora SDK that implements the core functions of real-time communication.

IAgoraRtcEngine provides the main methods that your app can call.

InitEventHandler

Adds event handlers.

public abstract void InitEventHandler(IAgoraRtcEngineEventHandler engineEventHandler);

The SDK uses the IAgoraRtcEngineEventHandler 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

engineEventHandler
Callback events to be added. For details, see IAgoraRtcEngineEventHandler.

AddPublishStreamUrl

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

public abstract int AddPublishStreamUrl(string url, bool transcodingEnabled);
Deprecated:
This method is deprecated.

After calling this method, you can push media streams in RTMP or RTMPS protocol to the CDN. The SDK triggers theOnRtmpStreamingStateChanged 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.

Returns

  • 0: Success.
  • < 0: Failure.
    • ERR_INVALID_ARGUMENT (-2): Invalid argument, usually because the URL address is null or the string length is 0.
    • ERR_NOT_INITIALIZED (-7): You have not initialized the RTC engine when publishing the stream.

AddVideoWatermark [1/2]

Adds a watermark image to the local video.

public abstract int AddVideoWatermark(RtcImage watermark);
Deprecated:
This method is deprecated. Use AddVideoWatermark [2/2] instead.

This method adds a PNG watermark image to the local video stream in a live streaming session. Once the watermark image is added, all the users in the channel (CDN audience included) and the video capturing device can see and capture it. If you only want to add a watermark to the CDN live streaming, see descriptions in SetLiveTranscoding.

Attention:
  • The URL descriptions are different for the local video and CDN live streaming: In a local video stream, URL refers to the absolute path of the added watermark image file in the local video stream. In a CDN live stream, URL refers to the URL address of the added watermark image in the CDN live streaming.
  • The source file of the watermark image must be in the PNG file format. If the width and height of the PNG file differ from your settings in this method, the PNG file will be cropped to conform to your settings.
  • The Agora SDK supports adding only one watermark image onto a local video or CDN live stream. The newly added watermark image replaces the previous one.

Parameters

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

Returns

  • 0: Success.
  • < 0: Failure.

AddVideoWatermark [2/2]

Adds a watermark image to the local video.

public abstract int 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 (ORIENTATION_MODE) is fixed landscape mode or the adaptive landscape mode, the watermark uses the landscape orientation.
  • If the orientation mode of the encoding video (ORIENTATION_MODE) 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.

Returns

  • 0: Success.
  • < 0: Failure.

AdjustAudioMixingPlayoutVolume

Adjusts the volume of audio mixing for local playback.

public abstract int AdjustAudioMixingPlayoutVolume(int volume);
Attention: You need to call this method after calling StartAudioMixing [2/2] and receiving the OnAudioMixingStateChanged(PLAY) callback.

Parameters

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

Returns

  • 0: Success.
  • < 0: Failure.

AdjustAudioMixingPublishVolume

Adjusts the volume of audio mixing for publishing.

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

Parameters

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

Returns

  • 0: Success.
  • < 0: Failure.

AdjustAudioMixingVolume

Adjusts the volume during audio mixing.

public abstract int AdjustAudioMixingVolume(int volume);

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

Attention:

Parameters

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

Returns

  • 0: Success.
  • < 0: Failure.

AdjustPlaybackSignalVolume

Adjusts the playback signal volume of all remote users.

public abstract int 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).

Returns

  • 0: Success.
  • < 0: Failure.

AdjustLoopbackRecordingSignalVolume

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

public abstract int AdjustLoopbackRecordingSignalVolume(int volume);

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

Parameters

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

Returns

  • 0: Success.
  • < 0: Failure.

AdjustRecordingSignalVolume

Adjusts the capturing signal volume.

public abstract int 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).

Returns

  • 0: Success.
  • < 0: Failure.

AdjustUserPlaybackSignalVolume

Adjusts the playback signal volume of a specified remote user.

public abstract int AdjustUserPlaybackSignalVolume(uint 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.

Returns

  • 0: Success.
  • < 0: Failure.

ClearVideoWatermarks

Removes the watermark image from the video stream.

public abstract int ClearVideoWatermarks();

Returns

  • 0: Success.
  • < 0: Failure.

CreateChannel

Creates and gets an IAgoraRtcChannel object.

public abstract IAgoraRtcChannel CreateChannel(string channelId);

You can call this method multiple times to create multiple IAgoraRtcChannel objects, and then call the JoinChannel methods in of each IAgoraRtcChannel to join multiple channels at the same time.

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

Parameters

channelId
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
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
Attention:
  • The parameter does not have a default value. You must set it.
  • Do not set this parameter as the empty string "". Otherwise, the SDK returns ERR_REFUSED(5).

Returns

  • A pointer to the IAgoraRtcChannel instance, if the method call succeeds.
  • If the call fails, returns NULL.

Complain

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

public abstract int 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.

Returns

  • 0: Success.
  • < 0: Failure.
    • -2 (ERR_INVALID_ARGUMENT).
    • -3 (ERR_NOT_READY)。

CreateAgoraRtcEngine

Creates the IAgoraRtcEngine object.

public static IAgoraRtcEngine CreateAgoraRtcEngine(AgoraEngineType engineType = AgoraEngineType.MainProcess)

By default, the SDK uses the main thread to create the IAgoraRtcEngine object. In use cases with both the screen-captured and camera-captured streams, call this method to create two IAgoraRtcEngine objects using MainProcess and SubProcess respectively. The main process initializes IAgoraRtcEngine and the sub process initializes AgoraRtcScreenSharing.exe.

Parameters

engineType
The process type of the engine. For details, see AgoraEngineType.

Returns

  • The IAgoraRtcEngine instance, if the method call succeeds.
  • An error code, if the call fails.

Initialize

Initializes IAgoraRtcEngine.

public abstract int Initialize(RtcEngineContext context);

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

Attention:
  • Before calling other APIs, you must call CreateAgoraRtcEngine and Initialize to create and initialize the IAgoraRtcEngine object.
  • The SDK supports creating only one IAgoraRtcEngine instance for an app.

Parameters

context

Configurations for the IAgoraRtcEngine instance. See RtcEngineContext.

Returns

  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2(ERR_INVALID_ARGUMENT): An invalid parameter is used.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.
    • -22(ERR_RESOURCE_LIMITED): The resource is limited. The SDK fails to allocate resources because your app consumes too much system resource or the system resources are insufficient.
    • -101(ERR_INVALID_APP_ID): The App ID is invalid.

CreateDataStream [1/2]

Creates a data stream.

public abstract int CreateDataStream(bool reliable, bool ordered);

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

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 OnStreamMessageError callback and returns an error code.
  • false: There is no guarantee that the recipients receive the data stream within five seconds and no error message is reported for any delay or missing data stream.
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

CreateDataStream [2/2]

Creates a data stream.

public abstract int CreateDataStream(DataStreamConfig config);

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

Compared with CreateDataStream [1/2][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

DisableAudio

Disables the audio module.

public abstract int 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:

Returns

  • 0: Success.
  • < 0: Failure.

DisableLastmileTest

Disables the network connection quality test.

public abstract int DisableLastmileTest();

Returns

  • 0: Success.
  • < 0: Failure.

DisableVideo

Disables the video module.

public abstract int 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 OnUserEnableVideo(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:

Returns

  • 0: Success.
  • < 0: Failure.

EnableAudio

Enables the audio module.

public abstract int 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:

Returns

  • 0: Success.
  • < 0: Failure.

EnableAudioVolumeIndication

Enables the reporting of users' volume indication.

public abstract int EnableAudioVolumeIndication(int interval, int smooth, bool reportVad);

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

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 OnAudioVolumeIndication 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.
reportVad
  • true: Enable the voice activity detection of the local user. Once it is enabled, the vad parameter of the OnAudioVolumeIndication callback reports the voice activity status of the local user.
  • false: (Default) Disable the voice activity detection of the local user. Once it is disabled, the vad parameter of the OnAudioVolumeIndication callback does not report the voice activity status of the local user, except for the scenario where the engine automatically detects the voice activity of the local user.

Returns

  • 0: Success.
  • < 0: Failure.

EnableDeepLearningDenoise

Enables/Disables deep-learning noise reduction.

public abstract int 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:
  1. Ensure that the dynamic library is integrated in your project: libagora_ai_denoise_extension.dll
  2. 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.

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.

Returns

  • 0: Success.
  • < 0: Failure.
    • -157 (ERR_MODULE_NOT_FOUND): The dynamic library for enabling deep-learning noise reduction is not integrated.

EnableDualStreamMode

Enables/Disables dual-stream mode.

public abstract int 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.

Returns

  • 0: Success.
  • < 0: Failure.

EnableEncryption

Enables/Disables the built-in encryption.

public abstract int 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.

Returns

  • 0: Success.
  • < 0: Failure.
    • -2: An invalid parameter is used. Set the parameter with a valid value.
    • -4: The encryption mode is incorrect or the SDK fails to load the external encryption library. Check the enumeration or reload the external encryption library.
    • -7: The SDK is not initialized. Initialize the IAgoraRtcEngine instance before calling this method.

EnableLastmileTest

Enables the network connection quality test.

public abstract int 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 OnLastmileQuality 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 OnLastmileQuality 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.

Returns

  • 0: Success.
  • < 0: Failure.

EnableLocalAudio

Enables/Disables the local audio capture.

public abstract int 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 OnLocalAudioStateChanged callback, which reports LOCAL_AUDIO_STREAM_STATE_STOPPED(0) or LOCAL_AUDIO_STREAM_STATE_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.

Returns

  • 0: Success.
  • < 0: Failure.

EnableLocalVideo

Enables/Disables the local video capture.

public abstract int 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 clientOnRemoteVideoStateChanged.

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.

Returns

  • 0: Success.
  • < 0: Failure.

EnableLoopbackRecording

Enables loopback audio capturing.

public abstract int 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:
  • 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.

Returns

  • 0: Success.
  • < 0: Failure.

EnableSoundPositionIndication

Enables/Disables stereo panning for remote users.

public abstract int 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.

Returns

  • 0: Success.
  • < 0: Failure.

EnableVideo

Enables the video module.

public abstract int 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 OnRemoteVideoStateChanged 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:

Returns

  • 0: Success.
  • < 0: Failure.

EnableVirtualBackground

Enables/Disables the virtual background. (beta feature)

public abstract int 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 OnVirtualBackgroundSourceEnabled callback whether the virtual background is successfully enabled or the cause of any errors.

Attention:
  • 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:
    • Devices with an i5 CPU and better
  • 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.

Returns

  • 0: Success.
  • < 0: Failure.

EnableWebSdkInteroperability

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

public abstract int 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.

Returns

  • 0: Success.
  • < 0: Failure.

GetAudioFileInfo

Gets the information of a specified audio file.

public abstract int GetAudioFileInfo(string filePath);

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

Attention:

Parameters

filePath
The file path:
  • Windows: The absolute path or URL address (including the filename extensions) of the audio file. For example: C:\music\audio.mp4.

Returns

  • 0: Success.
  • < 0: Failure.

GetAudioMixingCurrentPosition

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

public abstract int GetAudioMixingCurrentPosition();

Retrieves the playback position (ms) of the audio.

Attention: You need to call this method after calling StartAudioMixing [2/2] and receiving the OnAudioMixingStateChanged(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.

public abstract int GetAudioMixingDuration();
Deprecated:
Deprecated as of v3.4.0. Please use GetAudioFileInfo instead.

Retrieves the total duration (ms) of the audio.

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

Returns

  • ≥ 0: The audio mixing duration, if this method call succeeds.
  • < 0: Failure.

GetAudioMixingPlayoutVolume

Retrieves the audio mixing volume for local playback.

public abstract int GetAudioMixingPlayoutVolume();

This method helps troubleshoot audio volume‑related issues.

Attention: You need to call this method after calling StartAudioMixing [2/2] and receiving the OnAudioMixingStateChanged(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.

public abstract int GetAudioMixingPublishVolume();

This method helps troubleshoot audio volume‑related issues.

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

Returns

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

GetCallId

Retrieves the call ID.

public abstract 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.

public abstract CONNECTION_STATE_TYPE GetConnectionState();

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

Returns

The current connection state. For details, see CONNECTION_STATE_TYPE.

GetEffectCurrentPosition

Retrieves the playback position of the audio effect file.

public abstract int GetEffectCurrentPosition(int soundId);
Attention: Call this method after PlayEffect [2/2].

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.

public abstract 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: C:\music\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.

public abstract int 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 [2/2].

Returns

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

GetErrorDescription

Gets the warning or error description.

public abstract string GetErrorDescription(int code);

Parameters

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

Returns

The specific error or warning description.

GetUserInfoByUid

Gets the user information by passing in the user ID.

public abstract int GetUserInfoByUid(uint uid, out UserInfo userInfo);

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 OnUserInfoUpdated 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.
userInfo
The UserInfo object that identifies the user information.

Returns

  • 0: Success.
  • < 0: Failure.

GetUserInfoByUserAccount

Gets the user information by passing in the user account.

public abstract int GetUserInfoByUserAccount(string userAccount, out UserInfo userInfo);

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 OnUserInfoUpdated 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.
userInfo
The UserInfo object that identifies the user information.

Returns

  • 0: Success.
  • < 0: Failure.

GetVersion

Gets the SDK version.

public abstract string GetVersion();

Returns

The SDK version number. The format is a string.

JoinChannel [1/2]

Joins a channel.

public abstract int JoinChannel(string token, string channelId, string info = "", uint uid = 0);

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:

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 OnRejoinChannelSuccess callback on the local client.

Attention: 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.

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 Initialize method for initializing the RTC engine.
channelId
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
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
info
(Optional) Reserved for future use.
uid
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 232-1. If the user ID is not assigned (or set to 0), the SDK assigns a random user ID and returns it in the OnJoinChannelSuccess callback. Your app must maintain the returned user ID, because the SDK does not do so.

Returns

  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -2 (ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -3(ERR_NOT_READY): The SDK fails to be initialized. You can try re-initializing the SDK.
    • -5(ERR_REFUSED): The request is rejected. This may be caused by the following:
      • You have created an IAgoraRtcChannel object with the same channel name.
      • You have joined a channel by using IAgoraRtcChannel and published a stream in the IAgoraRtcChannel channel.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method. Initialize the IAgoraRtcEngine instance before calling this method.
    • -17(ERR_JOIN_CHANNEL_REJECTED): The request to join the channel is rejected. The SDK supports joining only one IAgoraRtcEngine channel at a time. Therefore, the SDK returns this error code when a user who has already joined an IAgoraRtcEngine channel calls the joining channel method of the IAgoraRtcEngine class with a valid channel name.

JoinChannel [2/2]

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

public abstract int JoinChannel(string token, string channelId, string info, uint uid,
            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:

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 OnRejoinChannelSuccess 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 Initialize method for initializing the RTC engine.
channelId
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
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
info

Reserved for future use.

uid
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 232-1. If the user ID is not assigned (or set to 0), the SDK assigns a random user ID and returns it in the OnJoinChannelSuccess 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.

Returns

  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -2 (ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -3(ERR_NOT_READY): The SDK fails to be initialized. You can try re-initializing the SDK.
    • -5(ERR_REFUSED): The request is rejected. This may be caused by the following:
      • You have created an IAgoraRtcChannel object with the same channel name.
      • You have joined a channel by using IAgoraRtcChannel and published a stream in the IAgoraRtcChannel channel.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method. Initialize the IAgoraRtcEngine instance before calling this method.
    • -17(ERR_JOIN_CHANNEL_REJECTED): The request to join the channel is rejected. The SDK supports joining only one IAgoraRtcEngine channel at a time. Therefore, the SDK returns this error code when a user who has already joined an IAgoraRtcEngine channel calls the joining channel method of the IAgoraRtcEngine class with a valid channel name.

JoinChannelWithUserAccount [1/2]

Joins the channel with a user account.

public abstract int JoinChannelWithUserAccount(string token, string channelId, string userAccount);
Since
v2.8.0
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:

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 Initialize method for initializing the RTC engine.
channelId
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
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

Returns

  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -2 (ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -3(ERR_NOT_READY): The SDK fails to be initialized. You can try re-initializing the SDK.
    • -5(ERR_REFUSED): The request is rejected. This may be caused by the following:
      • You have created an IAgoraRtcChannel object with the same channel name.
      • You have joined a channel by using IAgoraRtcChannel and published a stream in the IAgoraRtcChannel channel.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method. Initialize the IAgoraRtcEngine instance before calling this method.
    • -17(ERR_JOIN_CHANNEL_REJECTED): The request to join the channel is rejected. The SDK supports joining only one IAgoraRtcEngine channel at a time. Therefore, the SDK returns this error code when a user who has already joined an IAgoraRtcEngine channel calls the joining channel method of the IAgoraRtcEngine class with a valid channel name.

JoinChannelWithUserAccount [2/2]

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

public abstract int JoinChannelWithUserAccount(string token, string channelId, 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:

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 Initialize method for initializing the RTC engine.
channelId
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.

Returns

  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -2 (ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -3(ERR_NOT_READY): The SDK fails to be initialized. You can try re-initializing the SDK.
    • -5(ERR_REFUSED): The request is rejected. This may be caused by the following:
      • You have created an IAgoraRtcChannel object with the same channel name.
      • You have joined a channel by using IAgoraRtcChannel and published a stream in the IAgoraRtcChannel channel.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method. Initialize the IAgoraRtcEngine instance before calling this method.
    • -17(ERR_JOIN_CHANNEL_REJECTED): The request to join the channel is rejected. The SDK supports joining only one IAgoraRtcEngine channel at a time. Therefore, the SDK returns this error code when a user who has already joined an IAgoraRtcEngine channel calls the joining channel method of the IAgoraRtcEngine class with a valid channel name.

LeaveChannel

Leaves a channel.

public abstract int 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: OnLeaveChannel.
  • The remote client: OnUserOffline, if the user joining the channel is in the Communication profile, or is a host in the Live-broadcasting profile.
Attention:
  • If you call Dispose immediately after calling this method, the SDK does not trigger the OnLeaveChannel callback.
  • If you call this method during a CDN live streaming, the SDK automatically calls the RemovePublishStreamUrl method.

Returns

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

MuteAllRemoteAudioStreams

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

public abstract int MuteAllRemoteAudioStreams(bool mute);

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

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

Returns

  • 0: Success.
  • < 0: Failure.

MuteAllRemoteVideoStreams

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

public abstract int MuteAllRemoteVideoStreams(bool mute);

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:

Parameters

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

Returns

  • 0: Success.
  • < 0: Failure.

MuteLocalAudioStream

Stops or resumes publishing the local audio stream.

public abstract int MuteLocalAudioStream(bool mute);

A successful call of this method triggers the OnUserMuteAudio 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

mute
Whether to stop publishing the local audio stream.
  • true: Stop publishing the local audio stream.
  • false: (Default) Resumes publishing the local audio stream.

Returns

  • 0: Success.
  • < 0: Failure.

MuteLocalVideoStream

Stops or resumes publishing the local video stream.

public abstract int MuteLocalVideoStream(bool mute);

A successful call of this method triggers the OnUserMuteVideo 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

mute
Whether to stop publishing the local video stream.
  • true: Stop publishing the local video stream.
  • false: (Default) Publish the local video stream.

Returns

  • 0: Success.
  • < 0: Failure.

MuteRemoteAudioStream

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

public abstract int MuteRemoteAudioStream(uint userId, bool mute);

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

Parameters

userId
The user ID of the specified user.
mute
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.

Returns

  • 0: Success.
  • < 0: Failure.

MuteRemoteVideoStream

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

public abstract int MuteRemoteVideoStream(uint userId, bool mute);

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

Parameters

userId
The ID of the specified user.
mute
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.

Returns

  • 0: Success.
  • < 0: Failure.

PauseAllChannelMediaRelay

Pauses the media stream relay to all destination channels.

public abstract int 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 OnChannelMediaRelayEvent callback to report whether the media stream relay is successfully paused.

Attention: Call this method after StartChannelMediaRelay.

Returns

  • 0: Success.
  • < 0: Failure.

PauseAllEffects

Pauses all audio effects.

public abstract int PauseAllEffects();

Returns

  • 0: Success.
  • < 0: Failure.

PauseAudioMixing

Pauses playing and mixing the music file.

public abstract int PauseAudioMixing();

Call this method when you are in a channel.

Returns

  • 0: Success.
  • < 0: Failure.

PauseEffect

Pauses a specified audio effect.

public abstract int PauseEffect(int soundId);

Parameters

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

Returns

  • 0: Success.
  • < 0: Failure.

PlayEffect [1/2]

Plays the specified local or online audio effect file.

public abstract int PlayEffect(int soundId, string filePath, int loopCount, double pitch = 1.0,
            double pan = 0.0, int gain = 100, bool publish = false);

Deprecated:
This method is deprecated as of v3.4.0. Please use PlayEffect [2/2] instead.
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 OnAudioEffectFinished callback.
Attention:
  • Call this method after joining a channel.
  • Supported audio formats include MP3, AAC, M4A, MP4, WAV, and 3GP. See supported audio formats.

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
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 audio 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 smaller the value, the lower the pitch.
pan
The spatial position of the audio effect. The value ranges between -1.0 and 1.0, where:
  • -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 0.0 to 100.0. 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.

Returns

  • 0: Success.
  • < 0: Failure.

PlayEffect [2/2]

Plays the specified local or online audio effect file.

public abstract int PlayEffect(int soundId, string filePath, int loopCount, int startPos,
    double pitch = 1.0, double pan = 0.0, int gain = 100, bool publish = false);

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 OnAudioEffectFinished 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: C:\music\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.

Returns

  • 0: Success.
  • < 0: Failure.

PullAudioFrame

Pulls the remote audio data.

public abstract int PullAudioFrame(AudioFrame frame);

Before calling this method, you need to call SetExternalAudioSink to notify the app to enable and set the external rendering.

After a successful method call, the app pulls the decoded and mixed audio data for playback.

Attention:
  • Call this method after joining a channel.
  • Once you enable the external audio sink, the app will not retrieve any audio data from the OnPlaybackAudioFrame callback.
  • The difference between this method and the OnPlaybackAudioFrame callback is as follows:
    • The SDK sends the audio data to the app through the OnPlaybackAudioFrame callback. Any delay in processing the audio frames may result in audio jitter.
    • After a successful method call, the app automatically pulls the audio data from the SDK. After setting the audio data parameters, the SDK adjusts the frame buffer and avoids problems caused by jitter in the external audio playback.

Parameters

frame
The audio frame: AudioFrame.

Returns

  • 0: Success.
  • < 0: Failure.

PushAudioFrame

Pushes the external audio frame.

public abstract int PushAudioFrame(MEDIA_SOURCE_TYPE type, AudioFrame frame, bool wrap);

Parameters

type
The type of the audio recording device. See MEDIA_SOURCE_TYPE for details.
frame
The external audio frame. See AudioFrame for details.
wrap
Whether to use the placeholder. Agora recommends using the default value.
  • true: Use the placeholder.
  • false: (Default) Do not use the placeholder.

Returns

  • 0: Success.
  • < 0: Failure.

PushVideoFrame

Pushes the external raw video frame to the SDK.

public abstract int PushVideoFrame(ExternalVideoFrame frame);

If you call SetExternalVideoSource and set the enabled parameter as true and the encodedFrame parameter as false, you can call this method to push the external raw video frame to the SDK.

Attention: Video data in Texture format is not supported in the communication scenario.

Parameters

frame

The external raw video frame to be pushed. See ExternalVideoFrame for details.

Returns

PreloadEffect

Preloads a specified audio effect file into the memory.

public abstract int 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 [2/2].

Attention:

Parameters

soundId
The audio effect ID. The ID of each audio effect file is unique.
filePath
File path:
  • Windows: The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example: C:\music\audio.mp4.

Returns

  • 0: Success.
  • < 0: Failure.

Rate

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

public abstract int 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.

Returns

  • 0: Success.
  • < 0: Failure.
    • -2 (ERR_INVALID_ARGUMENT).
    • -3 (ERR_NOT_READY)。

RegisterAudioFrameObserver

Registers an audio frame observer object.

public abstract void RegisterAudioFrameObserver(IAgoraRtcAudioFrameObserver audioFrameObserver);

Call this method to register an audio frame observer object (register a callback). When you need the SDK to trigger OnRecordAudioFrame or OnPlaybackAudioFrame callback, you need to use this method to register the callbacks.

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

Parameters

audioFrameObserver

The observer object instance. For details, see IAgoraRtcAudioFrameObserver. Set the value as NULL to release the observer object. Agora recommends releasing the observer object after receiving the OnLeaveChannel callback.

Returns

  • 0: Success.
  • < 0: Failure.

RegisterLocalUserAccount

Registers a user account.

public abstract int 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 OnLocalUserRegistered 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 [2/2] to join the channel.
  • Call the JoinChannelWithUserAccount [2/2] 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 [2/2].

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
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

Returns

  • 0: Success.
  • < 0: Failure.

RegisterMediaMetadataObserver

Registers the metadata observer.

public abstract int RegisterMediaMetadataObserver(METADATA_TYPE type);
Attention:
  • Call this method before JoinChannel [2/2].
  • This method applies only to interactive live streaming.

Parameters

type
The metadata type. The SDK currently only supports VIDEO_METADATA. See METADATA_TYPE.

Returns

  • 0: Success.
  • < 0: Failure.

RegisterPacketObserver

Registers a packet observer.

public abstract int RegisterPacketObserver(IPacketObserver observer);

Call this method registers a packet observer. When the Agora SDK triggers callbacks registered by IPacketObserver for voice or video packet transmission, you can call this method to process the packets, such as encryption and decryption.

Attention:
  • The size of the packet sent to the network after processing should not exceed 1200 bytes, otherwise, the SDK may fail to send the packet.
  • Ensure that both receivers and senders call this method; otherwise, you may meet undefined behaviors such as no voice and black screen.
  • When you use media push, recording, or storage functions, Agora doesn't recommend calling this method.
  • Call this method before joining a channel.

Parameters

observer
IPacketObserver.

Returns

  • 0: Success.
  • < 0: Failure.

RegisterVideoFrameObserver

Registers a video frame observer object.

public abstract void RegisterVideoFrameObserver(IAgoraRtcVideoFrameObserver videoFrameObserver);

You need to implement the class in this method IAgoraRtcVideoFrameObserver and register callbacks according to your scenarios. After you successfully register the video frame observer, the SDK triggers the registered callbacks each time a video frame is received.

Attention:
  • When handling the video data returned in the callbacks, pay attention to the changes in the width and height parameters, which may be adapted under the following circumstances:
    • When the network condition deteriorates, the video resolution decreases incrementally.
    • If the user adjusts the video profile, the resolution of the video returned in the callbacks also changes.
  • Ensure that you call this method before joining a channel.

Parameters

videoFrameObserver

The observer object instance. To release the instance, set the value as NULL. For details, see IAgoraRtcVideoFrameObserver.

Returns

  • 0: Success.
  • < 0: Failure.

Dispose

Releases the IAgoraRtcEngine, IAgoraRtcAudioPlaybackDeviceManager, IAgoraRtcAudioRecordingDeviceManager and IAgoraRtcVideoDeviceManager instance.

public abstract void Dispose(bool sync = false);

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.

After a successful method call, you can no longer use any method or callback in the SDK anymore. If you want to use the real-time communication functions again, you must call Initialize to create a new IAgoraRtcEngine instance.

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

Parameters

sync
  • true: Synchronous call. Agora suggests calling this method in a sub-thread to avoid congestion in the main thread because the synchronous call and the app cannot move on to another task until the resources used by IAgoraRtcEngine are released. Besides, you cannot call Dispose in any method or callback of the SDK. Otherwise, the SDK cannot release the resources until the callbacks return results, which may result in a deadlock. The SDK automatically detects the deadlock and converts this method into an asynchronous call, causing the test to take additional time.
  • false: Asynchronous call. The app can move on to another task, no matter the resources used by IAgoraRtcEngine are released or not. Do not immediately uninstall the SDK's dynamic library after the call; otherwise, it may cause a crash due to the SDK clean-up thread not quitting.

RemovePublishStreamUrl

Removes an RTMP or RTMPS stream from the CDN.

public abstract int RemovePublishStreamUrl(string url);
Deprecated:
This method is deprecated.

After a successful method call, the SDK triggers OnRtmpStreamingStateChanged 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.

Returns

  • 0: Success.
  • < 0: Failure.

RenewToken

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

public abstract int 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.

Parameters

token
The new token.

Returns

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

ResumeAllChannelMediaRelay

Resumes the media stream relay to all destination channels.

public abstract int 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 OnChannelMediaRelayEvent callback to report whether the media stream relay is successfully resumed.

Note: Call this method after the PauseAllChannelMediaRelay method.

Returns

  • 0: Success.
  • < 0: Failure.

ResumeAllEffects

Resumes playing all audio effects.

public abstract int ResumeAllEffects();

Returns

  • 0: Success.
  • < 0: Failure.

ResumeAudioMixing

Resumes playing and mixing the music file.

public abstract int ResumeAudioMixing();

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

Returns

  • 0: Success.
  • < 0: Failure.

ResumeEffect

Resumes playing a specified audio effect.

public abstract int ResumeEffect(int soundId);

Parameters

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

Returns

  • 0: Success.
  • < 0: Failure.

SendCustomReportMessage

Reports customized messages.

public abstract int SendCustomReportMessage(string id, string category, string events, 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 support@agora.io and discuss the format of customized messages with us.

SendMetadata

Sends media metadata.

public abstract int SendMetadata(Metadata metadata);

After a successful method call of RegisterMediaMetadataObserver, the SDK triggers the OnReadyToSendMetadata callback, and then you can call this method to send media metadata.

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

Parameters

metadata
Media metadata See Metadata.

Returns

  • 0: Success.
  • < 0: Failure.

SendStreamMessage

Sends data stream messages.

public abstract int SendStreamMessage(int streamId, byte[] data);

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 OnStreamMessage callback on the remote client, from which the remote user gets the stream message. A failed method call triggers the OnStreamMessageError callback on the remote client.

Attention:
  • Ensure that you call CreateDataStream [2/2] 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 CreateDataStream [2/2].
data
The message to be sent.

Returns

  • 0: Success.
  • < 0: Failure.

SelectAudioTrack

Specified the playback track of the current music file.

public abstract int SelectAudioTrack(int index);

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

Note:

Parameters

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

Returns

  • 0: Success.
  • < 0: Failure.

SetAudioEffectParameters

Sets parameters for SDK preset audio effects.

public abstract int SetAudioEffectParameters(AUDIO_EFFECT_PRESET 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:

Parameters

preset
The options for SDK preset audio effects:
  • ROOM_ACOUSTICS_3D_VOICE, 3D voice effect:
    • Call and set the profile parameter in SetAudioProfile to AUDIO_PROFILE_MUSIC_STANDARD_STEREO (3) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5) before setting this enumerator; otherwise, the enumerator setting does not take effect.
    • If the 3D voice effect is enabled, users need to use stereo audio playback devices to hear the anticipated voice effect.
  • PITCH_CORRECTION, Pitch correction effect: To achieve better audio effect quality, Agora recommends calling SetAudioProfile and setting the profile parameter to AUDIO_PROFILE_MUSIC_HIGH_QUALITY (4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5) before setting this enumerator.
param1
  • If you set preset to ROOM_ACOUSTICS_3D_VOICE , 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 PITCH_CORRECTION , param1 sets the basic mode of the pitch correction effect:
    • 1: (Default) Natural major scale.
    • 2: Natural minor scale.
    • 3: Japanese pentatonic scale.
param2
  • If you set preset to ROOM_ACOUSTICS_3D_VOICE, you need to set param2 to 0.
  • If you set preset to PITCH_CORRECTION, param2 sets the tonic pitch of the pitch correction effect:
    • 1: A
    • 2: A#
    • 3: B
    • 4: (Default) C
    • 5: C#
    • 6: D
    • 7: D#
    • 8: E
    • 9: F
    • 10: F#
    • 11: G
    • 12: G#

Returns

  • 0: Success.
  • < 0: Failure.

SetAudioEffectPreset

Sets an SDK preset audio effect.

public abstract int SetAudioEffectPreset(AUDIO_EFFECT_PRESET 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 AUDIO_SCENARIO_GAME_STREAMING (3) before calling this method.

Attention:

Parameters

preset
The options for SDK preset audio effects. See AUDIO_EFFECT_PRESET.

Returns

  • 0: Success.
  • < 0: Failure.

SetAudioMixingDualMonoMode

Sets the channel mode of the current music file.

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

Parameters

mode
The channel mode. See AUDIO_MIXING_DUAL_MONO_MODE.

Returns

  • 0: Success.
  • < 0: Failure.

SetAudioMixingPitch

Sets the pitch of the local music file.

public abstract int 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 [2/2] and receiving the OnAudioMixingStateChanged( AUDIO_MIXING_STATE_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.

Returns

  • 0: Success.
  • < 0: Failure.

SetAudioMixingPlaybackSpeed

Sets the channel mode of the current music file.

public abstract int SetAudioMixingPlaybackSpeed(int speed);

Call this method after calling StartAudioMixing [2/2] and receiving the OnAudioMixingStateChanged( AUDIO_MIXING_STATE_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.

Returns

  • 0: Success.
  • < 0: Failure.

SetAudioMixingPosition

Sets the audio mixing position.

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

Parameters

pos
Integer. The playback position (ms).

Returns

  • 0: Success.
  • < 0: Failure.

SetAudioProfile

Sets the audio profile and audio scenario.

public abstract int SetAudioProfile(AUDIO_PROFILE_TYPE profile, AUDIO_SCENARIO_TYPE 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 AUDIO_PROFILE_MUSIC_HIGH_QUALITY (4), and scenario as AUDIO_SCENARIO_GAME_STREAMING (3).

Parameters

profile

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

scenario
The audio scenario. See AUDIO_SCENARIO_TYPE. Under different audio scenarios, the device uses different volume types.

Returns

  • 0: Success.
  • < 0: Failure.

SetBeautyEffectOptions

Sets the image enhancement options.

public abstract int SetBeautyEffectOptions(bool enabled, BeautyOptions options);

Enables or disables image enhancement, and sets the options.

Attention:

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.

Returns

  • 0: Success.
  • < 0: Failure.

SetCameraCapturerConfiguration

Sets the camera capture configuration.

public abstract int 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 CAPTURER_OUTPUT_PREFERENCE_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 CAPTURER_OUTPUT_PREFERENCE_PERFORMANCE(1) to optimize CPU and RAM usage.
  • If you want better quality for the local video preview, we recommend setting config as CAPTURER_OUTPUT_PREFERENCE_PREVIEW(2).
  • To customize the width and height of the video image captured by the local camera, set the camera capture configuration as CAPTURER_OUTPUT_PREFERENCE_MANUAL(3).
Attention:

Parameters

config
The camera capturer configuration. See CameraCapturerConfiguration.

Returns

  • 0: Success.
  • < 0: Failure.

SetChannelProfile

Sets the channel profile.

public abstract int SetChannelProfile(CHANNEL_PROFILE_TYPE 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 [2/2], and cannot be set again after joining the channel.

Parameters

profile

The channel profile. See CHANNEL_PROFILE_TYPE for details.

Returns

  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

SetClientRole [1/2]

Sets the client role.

public abstract int SetClientRole(CLIENT_ROLE_TYPE role);

You can call this method either before or after joining the channel to set the user role as audience or host.

If you call this method to set the user's role as the host before joining the channel and set the local video property through the SetupLocalVideo method, the local video preview is automatically enabled when the user joins the channel.

If you call this method to switch the user role after joining the channel, the SDK triggers the following callbacks:
Attention: This method only takes effect when the channel profile is live interactive streaming (when the profile parameter in SetChannelProfile set as CHANNEL_PROFILE_LIVE_BROADCASTING).

Parameters

role

The user role. See CLIENT_ROLE_TYPE for details.

Returns

  • 0: Success.
  • < 0: Failure.
    • -1: A general error occurs (no specified reason).
    • -2: The parameter is invalid.
    • -7: The SDK is not initialized.

SetClientRole [2/2]

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

public abstract int SetClientRole(CLIENT_ROLE_TYPE 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 set the user's role as the host before joining the channel and set the local video property through the SetupLocalVideo method, the local video preview is automatically enabled when the user joins the channel.

If you call this method to switch the user role after joining a channel, the SDK automatically does the following:
Attention: This method applies to the interactive live streaming profile (the profile parameter of SetChannelProfile is CHANNEL_PROFILE_LIVE_BROADCASTING) only.

Parameters

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

Returns

  • 0: Success.
  • < 0: Failure.
    • -1: A general error occurs (no specified reason).
    • -2: The parameter is invalid.
    • -5: The request is rejected.
    • -7: The SDK is not initialized.

SetCloudProxy

Sets the Agora cloud proxy service.

public abstract int SetCloudProxy(CLOUD_PROXY_TYPE 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 OnConnectionStateChanged (CONNECTION_STATE_CONNECTING, CONNECTION_CHANGED_SETTING_PROXY_SERVER) callback.

As of v3.6.2, when a user calls this method and then joins a channel successfully, the SDK triggers the OnProxyConnected callback to report the user ID, the proxy type connected, and the time calculated from when the user calling the JoinChannel [1/2] method to the callback is triggered.

To disable the cloud proxy that has been set, call the SetCloudProxy(NONE_PROXY).

To change the cloud proxy type that has been set, call the SetCloudProxy(NONE_PROXY) 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 [2/2] 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 CLOUD_PROXY_TYPE.

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

Returns

  • 0: Success.
  • < 0: Failure.
    • -2: The parameter is invalid.
    • -7: The SDK is not initialized.

SetColorEnhanceOptions

Sets color enhancement.

public abstract int SetColorEnhanceOptions(bool enabled, ColorEnhanceOptions options);

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.
options
The color enhancement options. For more details, see ColorEnhanceOptions.

SetDefaultMuteAllRemoteAudioStreams

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

public abstract int SetDefaultMuteAllRemoteAudioStreams(bool mute);

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

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

Returns

  • 0: Success.
  • < 0: Failure.

SetDefaultMuteAllRemoteVideoStreams

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

public abstract int SetDefaultMuteAllRemoteVideoStreams(bool mute);

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

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

Returns

  • 0: Success.
  • < 0: Failure.

SetEffectPosition

Sets the playback position of an audio effect file.

public abstract int 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.

Returns

  • 0: Success.
  • < 0: Failure.

SetEffectsVolume

Sets the volume of the audio effects.

public abstract int SetEffectsVolume(int volume);
Attention: Call this method after PlayEffect [2/2].

Parameters

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

Returns

  • 0: Success.
  • < 0: Failure.

SetEncryptionMode

Sets the built-in encryption mode.

public abstract int SetEncryptionMode(string 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.

Returns

  • 0: Success.
  • < 0: Failure.

SetEncryptionSecret

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

public abstract int 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.

Returns

  • 0: Success.
  • < 0: Failure.

SetExternalAudioSink

Sets the external audio sink.

public abstract int SetExternalAudioSink(bool enabled, int sampleRate, int channels);

This method applies to scenarios where you want to use external audio data for playback. After enabling the external audio sink, you can call the PullAudioFrame method to pull the remote audio data, process it, and play it with the audio effects that you want.

Attention:
  • Once you enable the external audio sink, the app will not retrieve any audio data from the OnPlaybackAudioFrame callback.
  • Ensure that you call this method before joining a channel.

Parameters

enabled
  • true: Enables the external audio sink.
  • false: (Default) Disables the external audio sink.
sampleRate
The sample rate (Hz) of the external audio sink, which can be set as 16000, 32000, 44100, or 48000.
channels
The number of audio channels of the external audio sink:
  • 1: Mono.
  • 2: Stereo.

Returns

  • 0: Success.
  • < 0: Failure.

SetExternalAudioSource

Sets the external audio source.

public abstract int SetExternalAudioSource(bool enabled, int sampleRate, int channels);

Call this method before calling JoinChannel [1/2] and StartPreview.

Parameters

enabled
  • true: Enable the external audio source.
  • false: (Default) Disable the external audio source.
sampleRate
The sample rate (Hz) of the external audio source, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
channels
The number of audio channels of the external audio source:
  • 1: Mono.
  • 2: Stereo.

Returns

  • 0: Success.
  • < 0: Failure.

SetExternalAudioSourceVolume

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

public abstract int SetExternalAudioSourceVolume(int sourcePos, int volume);
You can call this method multiple times to set the volume of external audio frames in different positions. The volume setting takes effect for all external audio frames that are pushed to the specified position.
Attention: Call this method after joining a channel

Parameters

sourcePos
The push position of the external audio frame.
  • 0: The position before local playback. If you need to play the external audio frame on the local client, set this position.
  • 1: The position after audio capture and before audio pre-processing. If you need the audio module of the SDK to process the external audio frame, set this position.
  • 2: The position after audio pre-processing and before audio encoding. If you do not need the audio module of the SDK to process the external audio frame, set this position.
volume
The volume of the external audio frame. The value range is [0,100]. The default value is 100, which represents the original value.

Returns

  • 0: Success.
  • < 0: Failure.
    • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.

SetExternalVideoSource

Configures the external video source.

public abstract int SetExternalVideoSource(bool enable, bool useTexture = false);
Attention: Ensure that you call this method before joining a channel.

Parameters

enable
Whether to use the external video source:
  • true: Use the external video source.
  • false: (Default) Do not use the external video source.
useTexture
Whether to use texture as an input:
  • true: Use texture as an input.
  • false: (Default) Do not use texture as an input.

Returns

  • 0: Success.
  • < 0: Failure.

SetHighQualityAudioParameters

Set audio high quality options.

public abstract int SetHighQualityAudioParameters(bool fullband, bool stereo, bool fullBitrate);
Deprecated:
This method is deprecated. Agora does not recommend using this method. If you want to set the audio high-quality options, use the SetAudioProfile method instead.

Parameters

fullband

Whether to enable full-band codec (48-kHz sample rate). Not compatible with SDK versions before v1.7.4.

  • true: Enable full-band codec.
  • false: Disable full-band codec.
stereo

Whether to enable stereo codec. Not compatible with SDK versions before v1.7.4.

  • true: Enable stereo codec.
  • false: Disable stereo codec.
fullBitrate

High bitrate mode. Recommended in voice-only mode.

  • true: Enable high-bitrate mode.
  • false: Disable high-bitrate mode.

Returns

  • 0: Success.
  • < 0: Failure.

SetLiveTranscoding

Sets the transcoding configurations for media push.

public abstract int SetLiveTranscoding(LiveTranscoding transcoding);
Deprecated:
This method is deprecated.

This method sets the video layout and audio settings for media push. The SDK triggers the OnTranscodingUpdated callback when you call this method to update the transcoding settings.

Attention:
  • This method takes effect only when you are a host in live interactive streaming.
  • Ensure that you enable the Media Push service before using this function. See Prerequisites in the advanced guide Media Push.
  • If you call this method to set the transcoding configuration for the first time, the SDK does not trigger the OnTranscodingUpdated callback.
  • Call this method after joining a channel.
  • Agora only supports pushing media streams to the CDN in RTMPS protocol when you enable transcoding.

Parameters

transcoding

The transcoding configurations for the media push. See LiveTranscoding for details.

Returns

  • 0: Success.
  • < 0: Failure.

SetLocalPublishFallbackOption

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

public abstract int SetLocalPublishFallbackOption(STREAM_FALLBACK_OPTIONS option);

An unstable network affects the audio and video quality in a video call or interactive live video streaming. If option is set as STREAM_FALLBACK_OPTION_AUDIO_ONLY(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 OnLocalPublishFallbackToAudioOnly 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 STREAM_FALLBACK_OPTION_AUDIO_ONLY(2).
  • Ensure that you call this method before joining a channel.

Parameters

option
The stream fallback option. For details, see STREAM_FALLBACK_OPTIONS.

Returns

  • 0: Success.
  • < 0: Failure.

SetLocalRenderMode [1/2]

Sets the local video display mode.

public abstract int SetLocalRenderMode(RENDER_MODE_TYPE renderMode);
Deprecated:
This method is deprecated. Use SetLocalRenderMode [2/2] instead.

Call this method to set the local video display mode. This method can be called multiple times during a call to change the display mode.

Parameters

renderMode

The local video display mode. For details, see RENDER_MODE_TYPE.

Returns

  • 0: Success.
  • < 0: Failure.

SetLocalRenderMode [2/2]

Updates the display mode of the local video view.

public abstract int SetLocalRenderMode(RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode);
Since
v3.3.0

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

Attention:
  • Ensure that you have called the SetupLocalVideo method to initialize the local video view before calling this method.
  • During a call, you can call this method as many times as necessary to update the display mode of the local video view.

Parameters

renderMode

The local video display mode. For details, see RENDER_MODE_TYPE.

mirrorMode

The rendering mode of the local video view. See VIDEO_MIRROR_MODE_TYPE.

Attention: If you use a front camera, the SDK enables the mirror mode by default; if you use a rear camera, the SDK disables the mirror mode by default.

Returns

  • 0: Success.
  • < 0: Failure.

SetLocalVideoMirrorMode

Sets the local video mirror mode.

public abstract int SetLocalVideoMirrorMode(VIDEO_MIRROR_MODE_TYPE mirrorMode);
Deprecated:
Deprecated as of v3.0.0.

Parameters

mirrorMode

The local video mirror mode. For details, see VIDEO_MIRROR_MODE_TYPE.

Returns

  • 0: Success.
  • < 0: Failure.

SetLocalVoiceChanger

Sets the local voice changer option.

public abstract int SetLocalVoiceChanger(VOICE_CHANGER_PRESET voiceChanger);
Deprecated:
Deprecated from v3.2.0. Use the following methods instead:
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 asAUDIO_PROFILE_MUSIC_HIGH_QUALITY (4) orAUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO (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 VOICE_CHANGER_OFF , which means the original voice. For more details, see VOICE_CHANGER_PRESET. 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.

Returns

  • 0: Success.
  • < 0: Failure.

SetLocalVoiceEqualization

Sets the local voice equalization effect.

public abstract int SetLocalVoiceEqualization(AUDIO_EQUALIZATION_BAND_FREQUENCY 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 AUDIO_EQUALIZATION_BAND_FREQUENCY.
bandGain
The gain of each band in dB. The value ranges between -15 and 15. The default value is 0.

Returns

  • 0: Success.
  • < 0: Failure.

SetLocalVoicePitch

Changes the voice pitch of the local speaker.

public abstract int 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).

Returns

  • 0: Success.
  • < 0: Failure.

SetLocalVoiceReverb

Sets the local voice reverberation.

public abstract int SetLocalVoiceReverb(AUDIO_REVERB_TYPE 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: AUDIO_REVERB_TYPE.
value
The value of the reverberation key.

Returns

  • 0: Success.
  • < 0: Failure.

SetLocalVoiceReverbPreset

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

public abstract int SetLocalVoiceReverbPreset(AUDIO_REVERB_PRESET reverbPreset);

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 toAUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5) before calling this method. Otherwise, the method setting is invalid.
  • When calling the AUDIO_VIRTUAL_STEREO method, Agora recommends setting the profile parameter in SetAudioProfile as AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(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

reverbPreset

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

Returns

  • 0: Success.
  • < 0: Failure.

SetLogFile

Sets the log files that the SDK outputs.

public abstract int 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 IAgoraRtcEngine, 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.

Returns

  • 0: Success.
  • < 0: Failure.

SetLogFileSize

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

public abstract int SetLogFileSize(uint 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.

Returns

  • 0: Success.
  • < 0: Failure.

SetLogFilter

Sets the log output level of the SDK.

public abstract int SetLogFilter(uint 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 LOG_FILTER_TYPE.

Returns

  • 0: Success.
  • < 0: Failure.

SetLowlightEnhanceOptions

Sets low-light enhancement.

public abstract int SetLowlightEnhanceOptions(bool enabled, LowLightEnhanceOptions options);

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.
options
The low-light enhancement options. For more details, see LowLightEnhanceOptions.

SetMaxMetadataSize

Sets the maximum size of the media metadata.

public abstract int 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.

Returns

  • 0: Success.
  • < 0: Failure.

SetMixedAudioFrameParameters

Sets the format of mixed audio.

public abstract int SetMixedAudioFrameParameters(int sampleRate, int samplesPerCall);

Sets the data format for the OnMixedAudioFrame callback.

Attention:
  • Ensure that you call this method before joining a channel.
  • The SDK calculates the sampling interval based on the samplesPerCall, sampleRate and channel parameters set in this method.Sample interval (sec) = samplePerCall/(sampleRate × channel). Ensure that the sample interval ≥ 0.01 (s). The SDK triggers the OnMixedAudioFrame callback according to the sampling interval.

Parameters

sampleRate
The sample rate returned in the OnMixedAudioFrame callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
samplesPerCall
The number of data samples returned in the OnMixedAudioFrame callback, such as 1024 for the media push.

Returns

  • 0: Success.
  • < 0: Failure.

SetPlaybackAudioFrameParameters

Sets the audio data format for playback.

public abstract int SetPlaybackAudioFrameParameters(int sampleRate, int channel,
            RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall);

Sets the data format for the OnPlaybackAudioFrame callback.

Attention:
  • Ensure that you call this method before joining a channel.
  • The SDK calculates the sampling interval based on the samplesPerCall, sampleRate and channel parameters set in this method.Sample interval (sec) = samplePerCall/(sampleRate × channel). Ensure that the sample interval ≥ 0.01 (s). The SDK triggers the OnPlaybackAudioFrame callback according to the sampling interval.

Parameters

sampleRate
The sample rate returned in the OnPlaybackAudioFrame callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
channel
The number of channels returned in the OnPlaybackAudioFrame callback:
  • 1: Mono.
  • 2: Stereo.
mode

The use mode of the audio frame. See RAW_AUDIO_FRAME_OP_MODE_TYPE.

samplesPerCall
The number of data samples returned in the OnPlaybackAudioFrame callback, such as 1024 for the media push.

Returns

  • 0: Success.
  • < 0: Failure.

SetRecordingAudioFrameParameters

Sets the format of the captured raw audio data.

public abstract int SetRecordingAudioFrameParameters(int sampleRate, int channel,
            RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall);
Attention:
  • Ensure that you call this method before joining a channel.
  • The SDK calculates the sampling interval based on the samplesPerCall, sampleRate and channel parameters set in this method.Sample interval (sec) = samplePerCall/(sampleRate × channel). Ensure that the sample interval ≥ 0.01 (s).

Parameters

sampleRate
The sample rate returned in the OnRecordAudioFrame callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
channel
The number of channels returned in the OnRecordAudioFrame callback:
  • 1: Mono.
  • 2: Stereo.
mode

The use mode of the audio frame. See RAW_AUDIO_FRAME_OP_MODE_TYPE.

samplesPerCall
The number of data samples returned in the OnRecordAudioFrame callback, such as 1024 for the media push.

Returns

  • 0: Success.
  • < 0: Failure.

SetRemoteDefaultVideoStreamType

Sets the default stream type of remote video streams.

public abstract int SetRemoteDefaultVideoStreamType(REMOTE_VIDEO_STREAM_TYPE 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 OnApiCallExecuted 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 REMOTE_VIDEO_STREAM_TYPE.

Returns

  • 0: Success.
  • < 0: Failure.

SetRemoteRenderMode [1/2]

Sets the video display mode of a specified remote user.

public abstract int SetRemoteRenderMode(uint userId, RENDER_MODE_TYPE renderMode);
Deprecated:
This method is deprecated. Use SetRemoteRenderMode [2/2] instead.

Call this method to set the video display mode of a specified remote user. This method can be called multiple times during a call to change the display mode.

Parameters

userId
The ID of the remote user.
renderMode

The rendering mode of the remote user view. For details, see RENDER_MODE_TYPE.

Returns

  • 0: Success.
  • < 0: Failure.

SetRemoteRenderMode [2/2]

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

public abstract int SetRemoteRenderMode(uint userId, RENDER_MODE_TYPE renderMode,
            VIDEO_MIRROR_MODE_TYPE mirrorMode);

Since
v3.0.0

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

Attention:
  • Please call this method after initializing the remote view by calling the SetupRemoteVideo method.
  • During a call, you can call this method as many times as necessary to update the display mode of the video view of a remote user.

Parameters

userId

The ID of the remote user.

renderMode

The rendering mode of the remote user view. For details, see RENDER_MODE_TYPE.

mirrorMode

The mirror mode of the remote user view. For details, see VIDEO_MIRROR_MODE_TYPE.

Returns

  • 0: Success.
  • < 0: Failure.

SetRemoteSubscribeFallbackOption

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

public abstract int SetRemoteSubscribeFallbackOption(STREAM_FALLBACK_OPTIONS option);

Unreliable network conditions affect the overall quality of the interactive live streaming. If option is set as STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW(1) or STREAM_FALLBACK_OPTION_AUDIO_ONLY(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 OnRemoteSubscribeFallbackToAudioOnly 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 STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW(1). See STREAM_FALLBACK_OPTIONS.

Returns

  • 0: Success.
  • < 0: Failure.

SetRemoteUserPriority

Prioritizes a remote user's stream.

public abstract int SetRemoteUserPriority(uint uid, PRIORITY_TYPE 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 PRIORITY_TYPE.

Returns

  • 0: Success.
  • < 0: Failure.

SetRemoteVideoStreamType

Sets the stream type of the remote video.

public abstract int SetRemoteVideoStreamType(uint userId, REMOTE_VIDEO_STREAM_TYPE 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 OnApiCallExecuted 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: REMOTE_VIDEO_STREAM_TYPE.

Returns

  • 0: Success.
  • < 0: Failure.

SetRemoteVoicePosition

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

public abstract int SetRemoteVoicePosition(uint 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.

Returns

  • 0: Success.
  • < 0: Failure.

SetScreenCaptureContentHint

Sets the content hint for screen sharing.

public abstract int 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 CONTENT_HINT_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.

Returns

  • 0: Success.
  • < 0: Failure.

SetupLocalVideo

Initializes the local video view.

public abstract int SetupLocalVideo(VideoCanvas canvas);

This method initializes the video view of a local stream on the local device. It affects only the video view that the local user sees, not the published local video stream. Call this method to bind the local video stream to a video view and to set the rendering and mirror modes of the video view.

After initialization, call this method to set the local video and then join the channel. The local video still binds to the view after you leave the channel. To unbind the local video from the view, set the view parameter as NULL.

Attention:
  • You can call this method either before or after joining a channel.
  • To update the rendering or mirror mode of the local video view during a call, use the SetLocalRenderMode [2/2] method.

Parameters

canvas
The local video view and settings. For details, see VideoCanvas.

Returns

  • 0: Success.
  • < 0: Failure.

SetupRemoteVideo

Initializes the video view of a remote user.

public abstract int SetupRemoteVideo(VideoCanvas canvas);

This method initializes the video view of a remote stream on the local device. It affects only the video view that the local user sees. Call this method to bind the remote video stream to a video view and to set the rendering and mirror modes of the video view.

You need to specify the ID of the remote user in this method. If the remote user ID is unknown to the application, set it after the app receives the OnUserJoined callback.

To unbind the remote user from the view, set the view parameter to NULL.

Once the remote user leaves the channel, the SDK unbinds the remote user.

Attention:
  • To update the rendering or mirror mode of the remote video view during a call, use the SetRemoteRenderMode [2/2] method.
  • If you use the Agora recording feature, the recording client joins the channel as a dummy client, triggering the OnUserJoined callback. Do not bind the dummy client to the app view because the dummy client does not send any video streams. If your app does not recognize the dummy client, bind the remote user to the view when the SDK triggers the OnFirstRemoteVideoDecoded callback.

Parameters

canvas

The remote video view and settings. For details, see VideoCanvas.

Returns

  • 0: Success.
  • < 0: Failure.

SetVideoDenoiserOptions

Sets video noise reduction.

public abstract int SetVideoDenoiserOptions(bool enabled, VideoDenoiserOptions options);

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.

public abstract int 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.

Returns

  • 0: Success.
  • < 0: Failure.

SetVideoProfile

Sets the video encoder configuration.

public abstract int SetVideoProfile(VIDEO_PROFILE_TYPE profile, bool swapWidthAndHeight = false);
Deprecated:
This method is deprecated as of v2.3. Please use SetVideoEncoderConfiguration instead.

This method sets the video encoder configuration. You can call this method either before or after joining a channel. If the user does not need to reset the video encoding properties after joining the channel, Agora recommends calling this method before EnableVideo to reduce the time to render the first video frame.

Parameters

profile
Video profile. For details, see VIDEO_PROFILE_TYPE.
swapWidthAndHeight

The SDK outputs video with a fixed width and height according to the video profile (profile) you selected. This parameter sets whether to swap width and height of the video:

  • true: Swap the width and height.
  • false: (Default) Do not swap the width and height.

Returns

  • 0: Success.
  • < 0: Failure.

SetVideoQualityParameters

Sets the preferences for high-quality video. (LIVE_BROADCASTING only).

public abstract int SetVideoQualityParameters(bool preferFrameRateOverImageQuality);
Deprecated:
Deprecated as of v2.4.0. Agora recommends using the degradationPreference parameter in the VideoEncoderConfiguration class to set the video quality preference.

Parameters

preferFrameRateOverImageQuality
Whether to prioritize smoothness or image quality.
  • true: Prioritizes smoothness.
  • false: (Default) Prioritizes the image quality.

Returns

  • 0: Success.
  • < 0: Failure.

SetVoiceBeautifierParameters

Sets parameters for the preset voice beautifier effects.

public abstract int SetVoiceBeautifierParameters(VOICE_BEAUTIFIER_PRESET 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 AUDIO_SCENARIO_GAME_STREAMING(3) and profile to AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5) before calling this method.

Attention:

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.

Returns

  • 0: Success.
  • < 0: Failure.

SetVoiceBeautifierPreset

Sets a preset voice beautifier effect.

public abstract int SetVoiceBeautifierPreset(VOICE_BEAUTIFIER_PRESET 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 AUDIO_SCENARIO_GAME_STREAMING (3) and profile to AUDIO_PROFILE_MUSIC_HIGH_QUALITY (4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO (5) before calling this method.

Attention:

Parameters

preset

The preset voice beautifier effect options: VOICE_BEAUTIFIER_PRESET.

Returns

  • 0: Success.
  • < 0: Failure.

SetVoiceConversionPreset

Sets a preset voice beautifier effect.

public abstract int SetVoiceConversionPreset(VOICE_CONVERSION_PRESET 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 AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5) and scenario to AUDIO_SCENARIO_GAME_STREAMING(3) before calling this method.

Attention:

Parameters

preset

The options for the preset voice beautifier effects: VOICE_CONVERSION_PRESET.

Returns

  • 0: Success.
  • < 0: Failure.

SetVolumeOfEffect

Sets the volume of a specified audio effect.

public abstract int SetVolumeOfEffect(int soundId, int volume);
Attention: Call this method after PlayEffect [2/2].

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.

Returns

  • 0: Success.
  • < 0: Failure.

StartAudioMixing [1/2]

Starts playing the music file.

public abstract int StartAudioMixing(string filePath, bool loopback, bool replace, int cycle);
Deprecated:
Please use StartAudioMixing [2/2] instead.

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 OnAudioMixingStateChanged ( AUDIO_MIXING_STATE_PLAYING) callback. When the audio mixing file playback finishes, the SDK triggers the OnAudioMixingStateChanged ( AUDIO_MIXING_STATE_STOPPED) callback on the local client.

Attention:
  • Call this method after joining a channel. If you need to call StartAudioMixing [1/2] 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: C:\music\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 audio effect in an infinite loop.

Returns

  • 0: Success.
  • < 0: Failure.

StartAudioMixing [2/2]

Starts playing the music file.

public abstract int 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 OnAudioMixingStateChanged (PLAY) callback. When the audio mixing file playback finishes, the SDK triggers the OnAudioMixingStateChanged (STOPPED) callback on the local client.

Attention:
  • Call this method after joining a channel. If you need to call StartAudioMixing [2/2] 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: C:\music\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.

Returns

  • 0: Success.
  • < 0: Failure.

StartAudioRecording [1/3]

Starts audio recording on the client.

public abstract int StartAudioRecording(string filePath, AUDIO_RECORDING_QUALITY_TYPE quality);
Deprecated:
This method is deprecated as of v2.9.1. It has a fixed recording sample rate of 32 kHz. Please use the StartAudioRecording [3/3] method instead.
The Agora SDK allows recording during a call. This method records the audio of all the users in the channel and generates 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.

Ensure that the directory for the recording file exists and is writable. This method should be called after the JoinChannel [1/2] method. The recording automatically stops when you call the LeaveChannel method.

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.
quality
Audio recording quality. See AUDIO_RECORDING_QUALITY_TYPE.

Returns

  • 0: Success.
  • < 0: Failure.

StartAudioRecording [2/3]

Starts audio recording on the client.

public abstract int StartAudioRecording(string filePath, int sampleRate, AUDIO_RECORDING_QUALITY_TYPE quality);
Deprecated:
This method is deprecated as of v3.4.0. Please use StartAudioRecording [3/3] 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 [2/2] method. The recording automatically stops when you call the LeaveChannel method.
  • For better recording effects, set quality to AUDIO_RECORDING_QUALITY_MEDIUM or AUDIO_RECORDING_QUALITY_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 AUDIO_RECORDING_QUALITY_TYPE.

Returns

  • 0: Success.
  • < 0: Failure.

StartAudioRecording [3/3]

Starts audio recording on the client.

public abstract int StartAudioRecording(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 AUDIO_RECORDING_QUALITY_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.

Returns

  • 0: Success.
  • < 0: Failure.

StartChannelMediaRelay

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

public abstract int StartChannelMediaRelay(ChannelMediaRelayConfiguration configuration);
After a successful method call, the SDK triggers OnChannelMediaRelayStateChanged the and OnChannelMediaRelayEvent callbacks, and these callbacks return the state and events of the media stream relay.
  • If the OnChannelMediaRelayStateChanged callback returns RELAY_STATE_RUNNING (2) and RELAY_OK (0), and the OnChannelMediaRelayEvent callback returns RELAY_EVENT_PACKET_SENT_TO_DEST_CHANNEL (4), it means that the SDK starts relaying media streams between the source channel and the destination channel.
  • If the OnChannelMediaRelayStateChanged callback returns RELAY_STATE_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 support@agora.io before implementing this function.
  • We do not support string user accounts in this API.

Parameters

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

Returns

  • Success.
  • <Failure.

StartEchoTest [1/3]

Starts an audio call test.

public abstract int StartEchoTest();
Deprecated:
This method is deprecated as of v2.4.0. Use StartEchoTest [2/3] instead.

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, the user speaks, and the recording is played back within 10 seconds. 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 [1/3] 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.

Returns

  • 0: Success.
  • < 0: Failure.

StartEchoTest [2/3]

Starts an audio call test.

public abstract int StartEchoTest(int intervalInSeconds);

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 [2/3] 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.

Returns

  • 0: Success.
  • < 0: Failure.

StartEchoTest [3/3]

Starts an audio and video call loop test.

public abstract int StartEchoTest(EchoTestConfiguration config);

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

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

Attention:
  • Call his method before joining a channel.
  • After calling this method, call StopEchoTest to end the test; otherwise, the user cannot perform the next audio and video call loop test and cannot join the channel.
  • In the LIVE_BROADCASTING profile, only a host can call this method.

Parameters

config
The configuration of the audio and video call loop test. See EchoTestConfiguration.

Returns

  • 0: Success.
  • < 0: Failure.

StartLastmileProbeTest

Starts the last mile network probe test.

public abstract int 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:
  • OnLastmileQuality: 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.
  • OnLastmileProbeResult: The SDK triggers this callback within 30 seconds depending on the network conditions. This callback returns the real-time statistics of the network conditions and is more objective.
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 OnLastmileQuality and OnLastmileProbeResult 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.

Returns

  • 0: Success.
  • < 0: Failure.

StartPreview

Enables the local video preview.

public abstract int StartPreview();

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

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.

Returns

  • 0: Success.
  • < 0: Failure.

StartRecording

Starts recording the local audio and video.

public abstract int StartRecording(MediaRecorderConfiguration config);

After successfully getting the object, you can all this method to enable the recoridng of the local audio and video.

This method can record the following content:
  • The audio captured by the local microphone and encoded in AAC format.
  • The video captured by the local camera and encoded by the SDK.

The SDK can generate a recording file only when it detects the recordable audio and video streams; when there are no audio and video streams to be recorded or the audio and video streams are interrupted for more than five seconds, the SDK stops recording and triggers the OnRecorderStateChanged(RECORDER_STATE_ERROR, RECORDER_ERROR_NO_STREAM) callback.

Attention: Call this method after joining the channel.

Parameters

config
The recording configuration. See MediaRecorderConfiguration.

Returns

  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -2(ERR_INVALID_ARGUMANT): The parameter is invalid. Ensure the following:
      • The specified path of the recording file exists and is writable.
      • The specified format of the recording file is supported.
      • The maximum recording duration is correctly set.
    • -4(ERR_NOT_SUPPORTED): IAgoraRtcEngine does not support the request due to one of the following reasons:
      • The recording is ongoing.
      • The recording stops because an error occurs.
    • -7(ERR_NOT_INITIALIZED): This method is called before the initialization of IAgoraRtcEngine.

StartRtmpStreamWithTranscoding

Starts Media Push and sets the transcoding configuration.

public abstract int StartRtmpStreamWithTranscoding(string url, 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 OnRtmpStreamingStateChanged 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.

Returns

  • 0: Success.
  • < 0: Failure.

StartRtmpStreamWithoutTranscoding

Starts pushing media streams to a CDN without transcoding.

public abstract int 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 OnRtmpStreamingStateChanged 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.

Returns

  • 0: Success.
  • < 0: Failure.

StartScreenCaptureByDisplayId

Shares the screen by specifying the display ID.

public abstract int StartScreenCaptureByDisplayId(uint 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:

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.

Returns

  • 0: Success.
  • < 0: Failure.

StartScreenCaptureByScreenRect

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

public abstract int 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.

Returns

  • 0: Success.
  • < 0: Failure.

StartScreenCaptureByWindowId

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

public abstract int StartScreenCaptureByWindowId(view_t 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.

Returns

  • 0: Success.
  • < 0: Failure.

StopAllEffects

Stops playing all audio effects.

public abstract int StopAllEffects();

Returns

  • 0: Success.
  • < 0: Failure.

StopAudioMixing

Stops playing and mixing the music file.

public abstract int StopAudioMixing();

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

Returns

  • 0: Success.
  • < 0: Failure.

StopAudioRecording

Stops the audio recording on the client.

public abstract int StopAudioRecording();

If you call StartAudioRecording [3/3] to start recording, you can call this method to stop the recording.

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

Returns

  • 0: Success.
  • < 0: Failure.

StopChannelMediaRelay

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

public abstract int StopChannelMediaRelay();

After a successful method call, the SDK triggers the OnChannelMediaRelayStateChanged callback. If the callback reports RELAY_STATE_IDLE (0) and RELAY_OK (0), the host successfully stops the relay.

Attention: If the method call fails, the SDK triggers the OnChannelMediaRelayStateChanged callback with the RELAY_ERROR_SERVER_NO_RESPONSE (2) or RELAY_ERROR_SERVER_CONNECTION_LOST (8) status code. You can call the LeaveChannel method to leave the channel, and the media stream relay automatically stops.

Returns

  • 0: Success.
  • < 0: Failure.

StopEchoTest

Stops the audio call test.

public abstract int StopEchoTest();

Returns

  • 0: Success.
  • < 0: Failure.
    • -5(ERR_REFUSED): Failed to stop the echo test. The echo test may not be running.

StopEffect

Stops playing a specified audio effect.

public abstract int StopEffect(int soundId);

Parameters

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

Returns

  • 0: Success.
  • < 0: Failure.

StopLastmileProbeTest

Stops the last mile network probe test.

public abstract int StopLastmileProbeTest();

Returns

  • 0: Success.
  • < 0: Failure.

StopRecording

Stops recording the local audio and video

public abstract int StopRecording();
Attention: After calling StartRecording, if you want to stop the recording, you must call this method; otherwise, the generated recording files may not be playable.

Returns

  • 0(ERR_OK): Success.
  • < 0: Failure:
    • -7(ERR_NOT_INITIALIZED): This method is called before the initialization of IAgoraRtcEngine.

StopRtmpStream

Stops pushing media streams to a CDN.

public abstract int 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 OnRtmpStreamingStateChanged 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.

Returns

  • 0: Success.
  • < 0: Failure.

StopPreview

Stops the local video preview.

public abstract int StopPreview();

Returns

  • 0: Success.
  • < 0: Failure.

StopScreenCapture

Stops screen sharing.

public abstract int StopScreenCapture();

Returns

  • 0: Success.
  • < 0: Failure.

SwitchChannel [1/2]

Switches to a different channel.

public abstract int SwitchChannel(string token, string channelId);

This method allows the audience of an interactive live streaming channel to switch to a different channel.

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

Once the user 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. To stop subscribing to a specified stream or all remote streams, call the corresponding mute methods.

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 Initialize method for initializing the RTC engine.
channelId
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 character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • Space
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "= ", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

Returns

  • 0: Success.
  • < 0: Failure.
    • -1: A general error occurs (no specified reason).
    • -2: The parameter is invalid.
    • -5: The request is rejected. Probably because the user is not an audience member.
    • -7: The SDK is not initialized.
    • -102: The channel name is invalid. Please use a valid channel name.
    • -113: The user is not in the channel.

SwitchChannel [2/2]

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

public abstract int SwitchChannel(string token, string channelId, 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 OnLeaveChannel and OnJoinChannelSuccess 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 Initialize method for initializing the RTC engine.
channelId
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.

Returns

  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2 (ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -5(ERR_REFUSED): The request is rejected. The role of the remote user is not AUDIENCE.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.
    • -102(ERR_INVALID CHANNEL_NAME): The channel name is invalid. Please use a valid channel name.
    • -113(ERR_NOT_IN_CHANNEL): The user is not in the channel.

TakeSnapshot

Takes a snapshot of a video stream.

public abstract int TakeSnapshot(string channel, uint 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 OnSnapshotTaken 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
Ensure that the path you specify exists and is writable.

Returns

  • 0: Success.
  • < 0: Failure.

UpdateRtmpTranscoding

Updates the transcoding configuration.

public abstract int 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 OnTranscodingUpdated callback after the transcoding configuration is updated.

Parameters

transcoding

The transcoding configuration for Media Push. See LiveTranscoding.

Returns

  • 0: Success.
  • < 0: Failure.

UploadLogFile

Uploads all SDK log files.

public abstract 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 OnUploadLogResult 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

UnloadEffect

Releases a specified preloaded audio effect from the memory.

public abstract int UnloadEffect(int soundId);

Parameters

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

Returns

  • 0: Success.
  • < 0: Failure.

UnRegisterAudioFrameObserver

Unregisters an audio observer.

public abstract void UnRegisterAudioFrameObserver();

Returns

  • 0: Success.
  • < 0: Failure.

UnRegisterMediaMetadataObserver

Unregisters the specified metadata observer.

public abstract int UnRegisterMediaMetadataObserver(METADATA_TYPE type);

Parameters

type
The metadata type. The SDK currently only supports VIDEO_METADATA. For details, see METADATA_TYPE.

Returns

  • 0: Success.
  • < 0: Failure.

UnRegisterVideoFrameObserver

Unregisters the video frame observer.

public abstract void UnRegisterVideoFrameObserver();

Returns

  • 0: Success.
  • < 0: Failure.

UpdateChannelMediaRelay

Updates the channels for media stream relay.

public abstract int UpdateChannelMediaRelay(ChannelMediaRelayConfiguration configuration);

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 OnChannelMediaRelayEvent callback with the RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL (7) state code.

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

Parameters

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

Returns

  • 0: Success.
  • < 0: Failure.

UpdateScreenCaptureParameters

Updates the screen sharing parameters.

public abstract int 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.

Returns

  • 0: Success.
  • < 0: Failure.
    • -3: If no screen or window is being shared, the SDK returns this error code.

UpdateScreenCaptureRegion

Updates the screen sharing region.

public abstract int 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.

Returns

  • 0: Success.
  • < 0: Failure.
    • -3(ERR_NOT_READY): No screen or window is being shared.