IAgoraRtcEngine

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.

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.

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.

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.

Parameters

watermark

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

Returns

• 0: Success.
• < 0: Failure.

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.

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.

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.

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

Parameters

volume

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

Returns

• 0: Success.
• < 0: Failure.

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

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.

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.

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.

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.

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.

Parameters

uid

The ID of the remote user.

volume

The playback signal volume of a specified remote user.

Returns

• 0: Success.
• < 0: Failure.

Returns

• 0: Success.
• < 0: Failure.

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.

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)。

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.

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

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.

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

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

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

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

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

Returns

• 0: Success.
• < 0: Failure.

Returns

• 0: Success.
• < 0: Failure.

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.

Returns

• 0: Success.
• < 0: Failure.

The audio mode is enabled by default.

Returns

• 0: Success.
• < 0: Failure.

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.

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.

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

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.

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.

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.

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.

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.

Returns

• 0: Success.
• < 0: Failure.

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.

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.

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.

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.

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

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.

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.

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.

Returns

• 0: Success.
• < 0: Failure.

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.

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.

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.

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.

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.

Retrieves the playback position (ms) of the audio.

Returns

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

Deprecated:

Deprecated as of v3.4.0. Please use GetAudioFileInfo instead.

Retrieves the total duration (ms) of the audio.

Returns

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

This method helps troubleshoot audio volume‑related issues.

Returns

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

This method helps troubleshoot audio volume‑related issues.

Returns

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

Returns

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

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.

Returns

The current call ID.

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

Returns

The current connection state. For details, see CONNECTION_STATE_TYPE.

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.

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.

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

Returns

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

Parameters

code

The error code or warning code reported by the SDK.

Returns

The specific error or warning description.

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.

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.

Returns

The SDK version number. The format is a string.

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.

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

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

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.

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

Since

v2.8.0

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

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.

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

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.

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.

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.

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.

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.

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.

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.

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

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.

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

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.

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.

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.

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.

Returns

• 0: Success.
• < 0: Failure.

Returns

• 0: Success.
• < 0: Failure.

Call this method when you are in a channel.

Returns

• 0: Success.
• < 0: Failure.

Parameters

soundId

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

Returns

• 0: Success.
• < 0: Failure.

Deprecated:

This method is deprecated as of v3.4.0. Please use PlayEffect [2/2] instead.

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.

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.

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.

Parameters

frame

The audio frame: AudioFrame.

Returns

• 0: Success.
• < 0: Failure.

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.

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.

Parameters

frame

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

Returns

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

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.

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)。

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.

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.

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.

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

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.

Parameters

type

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

Returns

• 0: Success.
• < 0: Failure.

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.

Parameters

observer

IPacketObserver.

Returns

• 0: Success.
• < 0: Failure.

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.

Parameters

videoFrameObserver

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

Returns

• 0: Success.
• < 0: Failure.

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.

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.

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.

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.

• The SDK triggers the OnTokenPrivilegeWillExpire callback.
• The OnConnectionStateChanged callback reports CONNECTION_CHANGED_TOKEN_EXPIRED(9).

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.

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.

Returns

• 0: Success.
• < 0: Failure.

Returns

• 0: Success.
• < 0: Failure.

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

Returns

• 0: Success.
• < 0: Failure.

Parameters

soundId

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

Returns

• 0: Success.
• < 0: Failure.

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.

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.

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.

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.

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.

Parameters

index

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

Returns

• 0: Success.
• < 0: Failure.

Detailed Description

Since

v3.2.0

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

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.

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.

Parameters

preset

The options for SDK preset audio effects. See AUDIO_EFFECT_PRESET.

Returns

• 0: Success.
• < 0: Failure.

Parameters

mode

The channel mode. See AUDIO_MIXING_DUAL_MONO_MODE.

Returns

• 0: Success.
• < 0: Failure.

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.

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.

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.

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

Parameters

pos

Integer. The playback position (ms).

Returns

• 0: Success.
• < 0: Failure.

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.

Enables or disables image enhancement, and sets the options.

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.

Parameters

config

The camera capturer configuration. See CameraCapturerConfiguration.

Returns

• 0: Success.
• < 0: Failure.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Parameters

enabled

Whether to turn on color enhancement:

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

options

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

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

Parameters

secret

The encryption password.

Returns

• 0: Success.
• < 0: Failure.

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.

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.

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.

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.

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.

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.

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.

Parameters

transcoding

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

Returns

• 0: Success.
• < 0: Failure.

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.

Parameters

option

The stream fallback option. For details, see STREAM_FALLBACK_OPTIONS.

Returns

• 0: Success.
• < 0: Failure.

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.

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.

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.

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.

Deprecated:

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

• SetAudioEffectPreset : Audio effects.
• SetVoiceBeautifierPreset : Voice beautifier effects.
• SetVoiceConversionPreset : Voice conversion effects.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Sets the data format for the OnMixedAudioFrame callback.

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.

Sets the data format for the OnPlaybackAudioFrame callback.

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.

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.

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.

Parameters

streamType

The default stream type of the remote video, see REMOTE_VIDEO_STREAM_TYPE.

Returns

• 0: Success.
• < 0: Failure.

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.

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.

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.

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.

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.

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.

Parameters

uid

The ID of the remote user.

userPriority

The priority of the remote user. See PRIORITY_TYPE.

Returns

• 0: Success.
• < 0: Failure.

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.

Parameters

userId

User ID.

streamType

The video stream type: REMOTE_VIDEO_STREAM_TYPE.

Returns

• 0: Success.
• < 0: Failure.

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.

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.

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.

Parameters

contentHint

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

Returns

• 0: Success.
• < 0: Failure.

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.

Parameters

canvas

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

Returns

• 0: Success.
• < 0: Failure.

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.

Parameters

canvas

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

Returns

• 0: Success.
• < 0: Failure.

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.

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.

Sets the encoder configuration for the local video.

Parameters

config

Video profile. See VideoEncoderConfiguration.

Returns

• 0: Success.
• < 0: Failure.

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.

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.

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.

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.

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.

Parameters

preset

The preset voice beautifier effect options: VOICE_BEAUTIFIER_PRESET.

Returns

• 0: Success.
• < 0: Failure.

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.

Parameters

preset

The options for the preset voice beautifier effects: VOICE_CONVERSION_PRESET.

Returns

• 0: Success.
• < 0: Failure.

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.

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.

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.

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.

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.

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.

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.

Deprecated:

This method is deprecated as of v3.4.0. Please use StartAudioRecording [3/3] instead.

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.

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

Parameters

config

Recording configuration. See AudioRecordingConfiguration.

Returns

• 0: Success.
• < 0: Failure.

Parameters

configuration

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

Returns

• Success.
• <Failure.

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.

Returns

• 0: Success.
• < 0: Failure.

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.

Parameters

intervalInSeconds

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

Returns

• 0: Success.
• < 0: Failure.

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.

Parameters

config

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

Returns

• 0: Success.
• < 0: Failure.

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

Parameters

config

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

Returns

• 0: Success.
• < 0: Failure.

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

• Call EnableVideo to enable the video.

Returns

• 0: Success.
• < 0: Failure.

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

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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

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.

Returns

• 0: Success.
• < 0: Failure.

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

Returns

• 0: Success.
• < 0: Failure.

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

Returns

• 0: Success.
• < 0: Failure.

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.

Returns

• 0: Success.
• < 0: Failure.

Returns

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

Parameters

soundId

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

Returns

• 0: Success.
• < 0: Failure.

Returns

• 0: Success.
• < 0: Failure.

Returns

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

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.

Returns

• 0: Success.
• < 0: Failure.

Returns

• 0: Success.
• < 0: Failure.

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.

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.

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

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.

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.

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

Parameters

soundId

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

Returns

• 0: Success.
• < 0: Failure.

Returns

• 0: Success.
• < 0: Failure.

Parameters

type

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

Returns

• 0: Success.
• < 0: Failure.

Returns

• 0: Success.
• < 0: Failure.

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.

Parameters

configuration

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

Returns

• 0: Success.
• < 0: Failure.

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.

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.