Agora C++ API Reference for All Platforms

Initializes the Agora service.

Unless otherwise specified, all the methods provided by the IRtcEngine class are executed asynchronously. Agora recommends calling these methods in the same thread.

Note

Ensure that you call the createAgoraRtcEngine and initialize methods before calling any other APIs.

Parameters

context

Pointer to the RTC engine context. See RtcEngineContext.

Returns

• 0(ERR_OK): Success.
• < 0: Failure.
  • -1(ERR_FAILED): A general error occurs (no specified reason).
  • -2(ERR_INVALID_ARGUMENT): No IRtcEngineEventHandler object is specified.
  • -7(ERR_NOT_INITIALIZED): The SDK is not initialized. Check whether context is properly set.
  • -22(ERR_RESOURCE_LIMITED): The resource is limited. The app uses too much of the system resource and fails to allocate any resources.
  • -101(ERR_INVALID_APP_ID): The App ID is invalid.

Releases all IRtcEngine resources.

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. Once you call release to destroy the created IRtcEngine instance, you cannot use any method or callback in the SDK any more. If you want to use the real-time communication functions again, you must call createAgoraRtcEngine and initialize to create a new IRtcEngine instance.

Note

If you want to create a new IRtcEngine instance after destroying the current one, ensure that you wait till the release method completes executing.

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 execution completes. Besides, you cannot call this method in any method or callback of the SDK. Otherwise, the SDK cannot release the resources occupied by the IRtcEngine instance 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. Do not immediately uninstall the SDK's dynamic library after the call, or it may cause a crash due to the SDK clean-up thread not quitting.

Sets the channel profile of the Agora IRtcEngine.

After initialization, the SDK uses the CHANNEL_PROFILE_COMMUNICATION channel profile by default. You can call this method to set the channel profile. The Agora IRtcEngine 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 the interactive live video streaming.

Warning

• To ensure the quality of real-time communication, we recommend that all users in a channel use the same channel profile.
• Call this method before calling joinChannel . You cannot set the channel profile once you have joined the channel.
• The default audio route and video encoding bitrate are different in different channel profiles. For details, see setDefaultAudioRouteToSpeakerphone and setVideoEncoderConfiguration.

Parameters

profile

The channel profile of the Agora IRtcEngine. See CHANNEL_PROFILE_TYPE

Returns

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

Sets the role of the user in interactive live streaming.

After calling setChannelProfile (CHANNEL_PROFILE_LIVE_BROADCASTING), the SDK sets the user role as audience by default. You can call setClientRole to set the user role as host.

You can call this method either before or after joining a channel. If you call this method to switch the user role after joining a channel, the SDK automatically does the following:

• Calls muteLocalAudioStream and muteLocalVideoStream to change the publishing state.
• Triggers onClientRoleChanged or onClientRoleChangeFailed on the local client.
• Triggers onUserJoined or onUserOffline (BECOME_AUDIENCE) on the remote client.

Note

This method applies to the LIVE_BROADCASTING profile only.

Parameters

role	The role of a user in interactive live streaming. See CLIENT_ROLE_TYPE.

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. In multichannel scenarios, if you have set any of the following in one channel, the SDK returns this error code when the user switches the user role to host in another channel:
    • Call joinChannel with the options parameter and use the default settings publishLocalAudio = true or publishLocalVideo = true.
    • Call setClientRole to set the user role as host.
    • Call muteLocalAudioStream(false) or muteLocalVideoStream(false).
  • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

Sets the role of the user in interactive live streaming.

Since

v3.2.0

In the LIVE_BROADCASTING channel profile, the SDK sets the user role as audience by default. You can call setClientRole to set the user role as host.

You can call this method either before or after joining a channel. If you call this method to switch the user role after joining a channel, the SDK automatically does the following:

• Calls muteLocalAudioStream and muteLocalVideoStream to change the publishing state.
• Triggers onClientRoleChanged or onClientRoleChangeFailed on the local client.
• Triggers onUserJoined or onUserOffline (BECOME_AUDIENCE) on the remote client.

Note

• This method applies to the LIVE_BROADCASTING profile only.
• The difference between this method and setClientRole [1/2] is that this method can set the user level in addition to the user role.
  • The user role determines the permissions that the SDK grants to a user, such as permission to send local streams, receive remote streams, and push streams to a CDN address.
  • The user level determines the level of services that a user can enjoy within the permissions of the user's role. For example, an audience member can choose to receive remote streams with low latency or ultra low latency. User level affects the pricing of services.

Parameters

role	The role of a user in interactive live streaming. See CLIENT_ROLE_TYPE.
options	The detailed options of a user, including user level. See ClientRoleOptions.

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. In multichannel scenarios, if you have set any of the following in one channel, the SDK returns this error code when the user switches the user role to host in another channel:
    • Call joinChannel with the options parameter and use the default settings publishLocalAudio = true or publishLocalVideo = true.
    • Call setClientRole to set the user role as host.
    • Call muteLocalAudioStream(false) or muteLocalVideoStream(false).
  • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

Joins a channel with the user ID.

Users in the same channel can talk to each other, and multiple users in the same channel can start a group chat. Users with different App IDs cannot call each other.

You must call the leaveChannel method to exit the current call before entering another channel.

A successful joinChannel method call triggers the following callbacks:

• The local client: onJoinChannelSuccess.
• The remote client: onUserJoined , if the user joining the channel is in the COMMUNICATION profile, or is a host in the LIVE_BROADCASTING profile.

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

Once the user joins the channel (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.

Note

A channel does not accept duplicate uids, such as two users with the same uid. If you set uid as 0, the system automatically assigns a uid. If you want to join a channel from different devices, ensure that each device has a different uid.

Warning

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. Otherwise, the CDN live streaming may fail.

Parameters

token	The token generated at your server. See Authenticate Your Users with Tokens.
channelId	Pointer to the unique channel name for the Agora RTC session in the string format smaller 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. The space character. Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
info	(Optional) Pointer to additional information about the channel. This parameter can be set to NULL or contain channel related information. Other users in the channel will not receive this message.
uid	(Optional) User ID. A 32-bit unsigned integer with a value ranging from 1 to 232-1. The uid must be unique. If a uid is not assigned (or set to 0), the SDK assigns and returns a uid in the onJoinChannelSuccess callback. Your application must record and maintain the returned uid, 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 IChannel object with the same channel name.
    • You have joined and published a stream in a channel created by the IChannel object. When you join a channel created by the IRtcEngine object, the SDK publishes the local audio and video streams to that channel by default. Because the SDK does not support publishing a local stream to more than one channel simultaneously, an error occurs in this occasion.
  • -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method.
  • -17(ERR_JOIN_CHANNEL_REJECTED): The request to join the channel is rejected. The SDK supports joining only one IRtcEngine channel at a time. Therefore, the SDK returns this error code when a user who has already joined an IRtcEngine channel calls the joining channel method of the IRtcEngine class with a valid channel name.

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

Since

v3.3.0

Users in the same channel can talk to each other, and multiple users in the same channel can start a group chat. Users with different App IDs cannot call each other.

You must call the leaveChannel method to exit the current call before entering another channel.

A successful joinChannel method call triggers the following callbacks:

• The local client: onJoinChannelSuccess.
• The remote client: onUserJoined, if the user joining the channel is in the COMMUNICATION profile, or is a host in the LIVE_BROADCASTING profile.

When the connection between the client and the Agora 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.

Note

• Compared with joinChannel [1/2], this method has the options parameter, which configures whether the user publishes or automatically subscribes to the audio and video streams in the channel when joining the channel. By default, the user publishes the local audio and video streams and automatically subscribes to the audio and video streams of all the other users in the channel. Subscribing incurs all associated usage costs. To unsubscribe, set the options parameter or call the mute methods accordingly.
• Ensure that the App ID used for generating the token is the same App ID used in the initialize method for creating an IRtcEngine object.

Parameters

token	The token generated at your server. See Authenticate Your Users with Tokens.
channelId	Pointer to the unique channel name for the Agora RTC session in the string format smaller 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. The space character. Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
info	(Optional) Reserved for future use.
uid	(Optional) User ID. A 32-bit unsigned integer with a value ranging from 1 to 232-1. The uid must be unique. If a uid is not assigned (or set to 0), the SDK assigns and returns a uid in the onJoinChannelSuccess callback. Your application must record and maintain the returned uid, because the SDK does not do so. Note: The ID of each user in the channel should be unique. If you want to join the same channel from different devices, ensure that the user IDs in all devices are different.
options	The channel media options: 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 IChannel object with the same channel name.
    • You have joined and published a stream in a channel created by the IChannel object. When you join a channel created by the IRtcEngine object, the SDK publishes the local audio and video streams to that channel by default. Because the SDK does not support publishing a local stream to more than one channel simultaneously, an error occurs in this occasion.
  • -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method.
  • -17(ERR_JOIN_CHANNEL_REJECTED): The request to join the channel is rejected. The SDK supports joining only one IRtcEngine channel at a time. Therefore, the SDK returns this error code when a user who has already joined an IRtcEngine channel calls the joining channel method of the IRtcEngine class with a valid channel name.

Switches to a different 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.

Note

This method applies to the audience role in a LIVE_BROADCASTING channel only.

Parameters

token

The token generated at your server. See Authenticate Your Users with Tokens.

channelId

Unique channel name for the AgoraRTC session in the string format. 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. The space character. Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".

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, probably because the user is not an audience.
  • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.
  • -102(ERR_INVALID_CHANNEL_NAME): The channel name is invalid.
  • -113(ERR_NOT_IN_CHANNEL): The user is not in the channel.

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

Since

v3.3.0

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.

Note

• This method applies to the audience role in a LIVE_BROADCASTING channel only.
• The difference between this method and switchChannel[1/2] is that the former adds the options parameter to configure whether the user automatically subscribes to all remote audio and video streams in the target channel. By default, the user subscribes to the audio and video streams of all the other users in the target channel, thus incurring all associated usage costs. To unsubscribe, set the options parameter or call the mute methods accordingly.

Parameters

token	The token generated at your server. See Authenticate Your Users with Tokens.
channelId	Unique channel name for the AgoraRTC session in the string format. 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. The space character. Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
options	The channel media options: 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, probably because the user is not an audience.
  • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.
  • -102(ERR_INVALID_CHANNEL_NAME): The channel name is invalid.
  • -113(ERR_NOT_IN_CHANNEL): The user is not in the channel.

Allows a user to leave a channel, such as hanging up or exiting a call.

After joining a channel, the user must call the leaveChannel method to end the call before joining another channel.

This method returns 0 if the user leaves the channel and releases all resources related to the call.

This method call is asynchronous, and the user has not left the channel when the method call returns. Once the user leaves the channel, the SDK triggers the onLeaveChannel callback.

A successful leaveChannel method call triggers the following callbacks:

• The local client: onLeaveChannel
• The remote client: onUserOffline , if the user leaving the channel is in the COMMUNICATION channel, or is a host in the LIVE_BROADCASTING profile.

Note

• If you call the release method immediately after the leaveChannel method, the leaveChannel process interrupts, and the onLeaveChannel callback is not triggered.
• If you call the leaveChannel method during a CDN live streaming, the SDK triggers the removePublishStreamUrl method.

Returns

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

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

The token expires after a period of time once the token schema is enabled when:

• The SDK triggers the onTokenPrivilegeWillExpire callback, or
• The onConnectionStateChanged reports CONNECTION_CHANGED_TOKEN_EXPIRED(9).

The application should call this method to get the new token. Failure to do so will result in the SDK disconnecting from the server.

Parameters

token

The new token.

Returns

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

Gets the pointer to the device manager object.

Parameters

iid	ID of the interface.
inter	Pointer to the DeviceManager object.

Returns

• 0: Success.
• < 0: Failure.

Registers a user account.

Once registered, the user account can be used to identify the local user when the user joins 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.

To join a channel with a user account, you can choose either of the following:

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

The difference between the two is that for the former, the time elapsed between calling the joinChannelWithUserAccount method and joining the channel is shorter than the latter.

Note

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

Parameters

appId

The App ID of your project.

userAccount

The user account. The maximum length of this parameter is 255 bytes. Ensure that the user account is unique and do not set it as null. Supported character scopes are: All lowercase English letters: a to z. All uppercase English letters: A to Z. All numeric characters: 0 to 9. The space character. Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".

Returns

• 0: Success.
• < 0: Failure.

Joins the channel with a user account.

After the user successfully joins the channel, the SDK triggers the following callbacks:

• The local client: onLocalUserRegistered and onJoinChannelSuccess .
• The remote client: onUserJoined and onUserInfoUpdated , if the user joining the channel is in the COMMUNICATION profile, or is a host in the LIVE_BROADCASTING profile.

Once the user joins the channel (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.

Note

• To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the uid of the user is set to the same parameter type.
• Before using a String user name, ensure that you read How can I use string user names for getting details about the limitations and implementation steps.

Parameters

token	The token generated at your server. See Authenticate Your Users with Tokens.
channelId	The channel name. The maximum length of this parameter is 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. The space character. Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
userAccount	The user account. The maximum length of this parameter is 255 bytes. Ensure that the user account is unique and do not set it as null. Supported character scopes are: All lowercase English letters: a to z. All uppercase English letters: A to Z. All numeric characters: 0 to 9. The space character. Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".

Returns

• 0: Success.
• < 0: Failure.
  • ERR_INVALID_ARGUMENT (-2)
  • ERR_NOT_READY (-3)
  • ERR_REFUSED (-5)
  • ERR_NOT_INITIALIZED (-7)
  • -17(ERR_JOIN_CHANNEL_REJECTED): The request to join the channel is rejected. The SDK supports joining only one IRtcEngine channel at a time. Therefore, the SDK returns this error code when a user who has already joined an IRtcEngine channel calls the joining channel method of the IRtcEngine class with a valid channel name.

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

Since

v3.3.0

After the user successfully joins the channel, the SDK triggers the following callbacks:

• The local client: onLocalUserRegistered and onJoinChannelSuccess .
• The remote client: onUserJoined and onUserInfoUpdated , if the user joining the channel is in the COMMUNICATION profile, or is a host in the LIVE_BROADCASTING profile.

Note

• Compared with joinChannelWithUserAccount [1/2], this method has the options parameter, which configures whether the user publishes or automatically subscribes to the audio and video streams in the channel when joining the channel. By default, the user publishes the local audio and video streams and automatically subscribes to the audio and video streams of all the other users in the channel. Subscribing incurs all associated usage costs. To unsubscribe, set the options parameter or call the mute methods accordingly.
• To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the uid of the user is set to the same parameter type.
• Before using a String user name, ensure that you read How can I use string user names for getting details about the limitations and implementation steps.

Parameters

token	The token generated at your server. See Authenticate Your Users with Tokens.
channelId	The channel name. The maximum length of this parameter is 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. The space character. Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
userAccount	The user account. The maximum length of this parameter is 255 bytes. Ensure that the user account is unique and do not set it as null. Supported character scopes are: All lowercase English letters: a to z. All uppercase English letters: A to Z. All numeric characters: 0 to 9. The space character. Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
options	The channel media options: ChannelMediaOptions.

Returns

• 0: Success.
• < 0: Failure.
  • ERR_INVALID_ARGUMENT (-2)
  • ERR_NOT_READY (-3)
  • ERR_REFUSED (-5)
  • -17(ERR_JOIN_CHANNEL_REJECTED): The request to join the channel is rejected. The SDK supports joining only one IRtcEngine channel at a time. Therefore, the SDK returns this error code when a user who has already joined an IRtcEngine channel calls the joining channel method of the IRtcEngine class with a valid channel name.

Gets the user information by passing in the user account.

After a remote user joins the channel, the SDK gets the user ID and user account of the remote user, caches them in a mapping table object (userInfo), and triggers the onUserInfoUpdated callback on the local client.

After receiving the oonUserInfoUpdated callback, you can call this method to get the user ID of the remote user from the userInfo object by passing in the user account.

Parameters

	userAccount	The user account of the user. Ensure that you set this parameter.
[in,out]	userInfo	A userInfo object that identifies the user: Input: A userInfo object. Output: A userInfo object that contains the user account and user ID of the user.

Returns

• 0: Success.
• < 0: Failure.

Gets the user information by passing in the user ID.

After a remote user joins the channel, the SDK gets the user ID and user account of the remote user, caches them in a mapping table object (userInfo), and triggers the onUserInfoUpdated callback on the local client.

After receiving the onUserInfoUpdated 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	The user ID of the remote user. Ensure that you set this parameter.
[in,out]	userInfo	A userInfo object that identifies the user: Input: A userInfo object. Output: A userInfo object that contains the user account and user ID of the user.

Returns

• 0: Success.
• < 0: Failure.

Starts an audio call test.

Deprecated:

This method is deprecated as of v2.4.0.

This method starts an audio call test to check 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 10 seconds, the audio devices and network connection are working properly.

Note

• After calling this method, always call the stopEchoTest method to end the test. Otherwise, the application cannot run the next echo test.
• In the LIVE_BROADCASTING profile, only the hosts can call this method. If the user switches from the COMMUNICATION toLIVE_BROADCASTING profile, the user must call the setClientRole method to change the user role from the audience (default) to the host before calling this method.

Returns

• 0: Success.
• < 0: Failure.

Starts an audio call test.

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.

In the audio call test, you record your voice. If the recording plays back within the set time interval, the audio devices and the network connection are working properly.

Note

• Call this method before joining a channel.
• After calling this method, call the stopEchoTest method to end the test. Otherwise, the app cannot run the next echo test, or call the joinChannel method.
• In the LIVE_BROADCASTING profile, only a host can call this method.

Parameters

intervalInSeconds

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

Returns

• 0: Success.
• < 0: Failure.

Starts an audio and video call loop test.

Since

v3.5.2

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.

Note

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

Parameters

config

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

Returns

• 0: Success.
• < 0: Failure.

Stops call loop test.

After calling startEchoTest [2/3] or startEchoTest [3/3], call this method if you want to stop the call loop test.

Returns

• 0: Success.
• < 0: Failure.

Sets the Agora cloud proxy service.

Since

v3.3.0

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 a successfully cloud proxy connection, 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 elapsed from the user calling joinChannel until this callback is triggered.

To disable the cloud proxy that has been set, call setCloudProxy(NONE_PROXY). To change the cloud proxy type that has been set, call setCloudProxy(NONE_PROXY) first, and then call setCloudProxy with the desired proxyType.

Note

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

Parameters

proxyType

The cloud proxy type, see CLOUD_PROXY_TYPE. This parameter is required, and the SDK reports an error if you do not pass in a value.

Returns

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

Enables the video module.

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. If this method is called during an audio call, the audio mode switches to the video mode. To disable the video module, call the disableVideo method.

A successful enableVideo method call triggers the onUserEnableVideo (true) callback on the remote client.

Note

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

Returns

• 0: Success.
• < 0: Failure.

Disables the video module.

This method can be called before joining a channel or during a call. If this method is called before joining a channel, the call starts in audio mode. If this method is called during a video call, the video mode switches to the audio mode. To enable the video module, call the enableVideo method.

A successful disableVideo method call triggers the onUserEnableVideo (false) callback on the remote client.

Note

• This method affects the internal engine and can be called after the leaveChannel method.
• This method resets the internal engine and takes some time to take effect. We recommend using the following APIs to control the video engine modules separately:
  • enableLocalVideo: Whether to enable the camera to create the local video stream.
  • muteLocalVideoStream: Whether to publish the local video stream.
  • muteRemoteVideoStream: Whether to subscribe to and play the remote video stream.
  • muteAllRemoteVideoStreams: Whether to subscribe to and play all remote video streams.

Returns

• 0: Success.
• < 0: Failure.

Sets the video profile.

Deprecated:

This method is deprecated as of v2.3. Use the setVideoEncoderConfiguration method instead.

Each video profile includes a set of parameters, such as the resolution, frame rate, and bitrate. If the camera device does not support the specified resolution, the SDK automatically chooses a suitable camera resolution, keeping the encoder resolution specified by the setVideoProfile method.

Note

• You can call this method either before or after joining a channel.
• If you do not need to set the video profile after joining the channel, call this method before the enableVideo method to reduce the render time of the first video frame.
• Always set the video profile before calling the joinChannel or startPreview method.

Parameters

profile	Sets the video profile. See VIDEO_PROFILE_TYPE.
swapWidthAndHeight	Sets whether to swap the width and height of the video stream: true: Swap the width and height. false: (Default) Do not swap the width and height. The width and height of the output video are consistent with the set video profile.

Note

Since the landscape or portrait mode of the output video can be decided directly by the video profile, We recommend setting swapWidthAndHeight to false (default).

Returns

• 0: Success.
• < 0: Failure.

Sets the video encoder configuration.

Each video encoder configuration corresponds to a set of video parameters, including the resolution, frame rate, bitrate, and video orientation.

The parameters specified in this method are the maximum values under ideal network conditions. If the video engine cannot render the video using the specified parameters due to poor network conditions, the parameters further down the list are considered until a successful configuration is found.

Note

• You can call this method either before or after joining a channel.
• If you do not need to set the video encoder configuration after joining the channel, you can call this method before the enableVideo method to reduce the render time of the first video frame.

Parameters

config

Sets the local video encoder configuration. See VideoEncoderConfiguration.

Returns

• 0: Success.
• < 0: Failure.

Sets the camera capture configuration.

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

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

Note

Call this method before enabling the local camera. That said, you can call this method before calling joinChannel, enableVideo, or enableLocalVideo, depending on which method you use to turn on your local camera.

Parameters

config

Sets the camera capturer configuration. See CameraCapturerConfiguration.

Returns

• 0: Success.
• < 0: Failure.

Initializes the local video view.

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. The binding is still valid after the user leaves the channel, which means that the window still displays. To unbind the view, set the view in VideoCanvas to NULL.

Note

• You can call this method either before or after joining a channel.
• During a call, you can call this method as many times as necessary to update the display mode of the local video view.

Parameters

canvas

Pointer to the local video view and settings. See VideoCanvas.

Returns

• 0: Success.
• < 0: Failure.

Initializes the video view of a remote user.

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.

The application specifies the uid of the remote video in this method before the remote user joins the channel. If the remote uid is unknown to the application, set it after the application receives the onUserJoined callback. If the Video Recording function is enabled, the Video Recording Service joins the channel as a dummy client, causing other clients to also receive the onUserJoined callback. Do not bind the dummy client to the application view because the dummy client does not send any video streams. If your application does not recognize the dummy client, bind the remote user to the view when the SDK triggers the onFirstRemoteVideoDecoded callback. To unbind the remote user from the view, set the view in VideoCanvas to NULL. Once the remote user leaves the channel, the SDK unbinds the remote user.

Note

To update the rendering or mirror mode of the remote video view during a call, use the setRemoteRenderMode method.

Parameters

canvas

Pointer to the remote video view and settings. See VideoCanvas.

Returns

• 0: Success.
• < 0: Failure.

Starts the local video preview before joining the channel.

Before calling this method, you must:

• Call the setupLocalVideo method to set up the local preview window and configure the attributes.
• Call the enableVideo method to enable video.

Note

Once the startPreview method is called to start the local video preview, if you leave the channel by calling the leaveChannel method, the local video preview remains until you call the stopPreview method to disable it.

Returns

• 0: Success.
• < 0: Failure.

Prioritizes a remote user's stream.

The SDK ensures the high-priority user gets the best possible stream quality.

Note

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

Parameters

uid	The ID of the remote user.
userPriority	Sets the priority of the remote user. See PRIORITY_TYPE.

Returns

• 0: Success.
• < 0: Failure.

Stops the local video preview.

After calling startPreview, if you want to stop the local video preview, call stopPreview.

Note

Call this method before you join the channel or after you leave the channel.

Returns

• 0: Success.
• < 0: Failure.

Enables the audio module.

The audio mode is enabled by default.

Note

• This method affects the audio module and can be called after the leaveChannel method. You can call this method either before or after joining a channel.
• This method enables the audio module and takes some time to take effect. Agora recommends using the following API methods to control the audio module separately:
  • enableLocalAudio: Whether to enable the microphone to create the local audio stream.
  • muteLocalAudioStream: Whether to publish the local audio stream.
  • muteRemoteAudioStream: Whether to subscribe to and play the remote audio stream.
  • muteAllRemoteAudioStreams: Whether to subscribe to and play all remote audio streams.

Returns

• 0: Success.
• < 0: Failure.

Disables/Re-enables the local audio function.

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

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

Once the local audio function is disabled or re-enabled, the SDK triggers the onLocalAudioStateChanged callback, which reports LOCAL_AUDIO_STREAM_STATE_STOPPED(0) or LOCAL_AUDIO_STREAM_STATE_RECORDING(1).

Note

• This method is different from the muteLocalAudioStream method:
  • enableLocalAudio: Disables/Re-enables the local audio capturing and processing. If you disable or re-enable local audio capturing using the enableLocalAudio method, the local user may hear a pause in the remote audio playback.
  • muteLocalAudioStream: Sends/Stops sending the local audio streams.
• This method can be called either before or after you join a channel. Calling it before you join a channel can set the device state only, and it takes effect immediately after you join the channel.

Parameters

enabled

Sets whether to disable/re-enable the local audio function: 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.

Disables the audio module.

Note

• This method affects the internal engine and can be called after the leaveChannel method. You can call this method either before or after joining a channel.
• This method resets the internal engine and takes some time to take effect. We recommend using the enableLocalAudio and muteLocalAudioStream methods to capture, process, and send the local audio streams.

Returns

• 0: Success.
• < 0: Failure.

Sets the audio parameters and application scenarios.

Note

• The setAudioProfile method must be called before the joinChannel method.
• In the COMMUNICATION and LIVE_BROADCASTING profiles, the bitrate may be different from your settings due to network self-adaptation.
• In scenarios requiring high-quality audio, for example, a music teaching scenario, we recommend setting profile as AUDIO_PROFILE_MUSIC_HIGH_QUALITY (4) and scenario as AUDIO_SCENARIO_GAME_STREAMING (3).

Parameters

profile	Sets the sample rate, bitrate, encoding mode, and the number of channels. See AUDIO_PROFILE_TYPE.
scenario	Sets the audio application scenario. See AUDIO_SCENARIO_TYPE. Under different audio scenarios, the device uses different volume types. For details, see What is the difference between the in-call volume and the media volume?.

Returns

• 0: Success.
• < 0: Failure.

Stops or resumes publishing the local audio stream.

As of v3.4.5, this method only sets the publishing state of the audio stream in the channel of IRtcEngine.

A successful method call triggers the onUserMuteAudio callback on the remote client.

You can only publish the local stream in one channel at a time. If you create multiple channels, ensure that you only call muteLocalAudioStream (false) in one channel; otherwise, the method call fails, and the SDK returns -5 (ERR_REFUSED).

Note

• This method does not change the usage state of the audio-capturing device.
• Whether this method call takes effect is affected by the joinChannel [2/2] and setClientRole methods. For details, see Set the Publishing State.

Parameters

mute	Sets whether to stop publishing the local audio stream. true: Stop publishing the local audio stream. false: Resume publishing the local audio stream.

Returns

• 0: Success.
• < 0: Failure.
  • -5 (ERR_REFUSED): The request is rejected.

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

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

Note

• Call this method after joining a channel.
• As of v3.3.0, this method contains the function of setDefaultMuteAllRemoteAudioStreams. Agora recommends not calling muteAllRemoteAudioStreams and setDefaultMuteAllRemoteAudioStreams together; otherwise, the settings may not take effect. See Set the Subscribing State.

Parameters

mute	Sets whether to stop subscribing to the audio streams of all remote users. true: Stop subscribing to the audio streams of all remote users. false: (Default) Resume subscribing to the audio streams of all remote users.

Returns

• 0: Success.
• < 0: Failure.

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

Deprecated:

This method is deprecated from v3.3.0.

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.

Note

If you need to resume subscribing to the audio streams of remote users in the channel after calling setDefaultMuteAllRemoteAudioStreams (true), do the following:

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

Parameters

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

Adjusts the playback signal volume of a specified remote user.

You can call this method as many times as necessary to adjust the playback volume of different remote users, or to repeatedly adjust the playback volume of the same remote user.

Note

• Call this method after joining a channel.
• The playback volume here refers to the mixed volume of a specified remote user.
• This method can only adjust the playback volume of one specified remote user at a time. 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 volume of the specified remote user. The value ranges between 0 and 100, including the following: 0: Mute. 100: (Default) Original volume.

Returns

• 0: Success.
• < 0: Failure.

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

Note

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

Parameters

userId	The user ID of the specified remote user.
mute	Sets whether to stop subscribing to the audio stream of a specified user. true: Stop subscribing to the audio stream of a specified user. false: (Default) Resume subscribing to the audio stream of a specified user.

Returns

• 0: Success.
• < 0: Failure.

Stops or resumes publishing the local video stream.

As of v3.4.5, this method only sets the publishing state of the video stream in the channel of IRtcEngine.

A successful method call triggers the onUserMuteVideo callback on the remote client.

You can only publish the local stream in one channel at a time. If you create multiple channels, ensure that you only call muteLocalVideoStream (false) in one channel; otherwise, the method call fails, and the SDK returns -5 (ERR_REFUSED).

Note

• This method does not change the usage state of the video-capturing device.
• Whether this method call takes effect is affected by the joinChannel [2/2] and setClientRole methods. For details, see Set the Publishing State.

Parameters

mute	Sets whether to stop publishing the local video stream. true: Stop publishing the local video stream. false: Resume publishing the local video stream.

Returns

• 0: Success.
• < 0: Failure.
  • -5 (ERR_REFUSED): The request is rejected.

Enables/Disables the local video capture.

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

After you call the enableVideo method, 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 it, call enableLocalVideo(true).

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

Note

• You can call this method either before or after joining a channel.
• This method affects the internal engine and can be called after the leaveChannel method.

Parameters

enabled

Sets whether to disable/re-enable the local video, including the capturer, renderer, and sender: true: (Default) Re-enable the local video. false: Disable the local video. 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.

Returns

• 0: Success.
• < 0: Failure.

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

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

Note

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

Parameters

mute	Sets 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) Resume subscribing to the video streams of all remote users.

Returns

• 0: Success.
• < 0: Failure.

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

Deprecated:

This method is deprecated from v3.3.0.

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

Note

If you need to resume subscribing to the video streams of remote users in the channel after calling setDefaultMuteAllRemoteVideoStreams (true), do the following:

• If you need to resume subscribing to the video stream of a specified user, call muteRemoteVideoStream (false), and specify the user ID.
• If you need to resume subscribing to the video streams of multiple remote users, call muteRemoteVideoStream (false) multiple times.

Parameters

mute	Sets whether to stop subscribing to the video streams of all remote users by default. true: Stop subscribing to the video streams of all remote users by default. false: (Default) Resume subscribing to the video streams of all remote users by default.

Returns

• 0: Success.
• < 0: Failure.

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

Note

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

Parameters

userId	The user ID of the specified remote user.
mute	Sets whether to stop subscribing to the video stream of a specified user. true: Stop subscribing to the video stream of a specified user. false: (Default) Resume subscribing to the video stream of a specified user.

Returns

• 0: Success.
• < 0: Failure.

Sets the stream type of the remote video.

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-video stream (the low resolution, and low bitrate video stream).

By default, users receive the high-quality video stream. Call this method if you want to switch to the low-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-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-video stream.

The method result returns in the onApiCallExecuted callback.

Note

You can call this method either before or after joining a channel. If you call both setRemoteVideoStreamType and setRemoteDefaultVideoStreamType, the SDK applies the settings in the setRemoteVideoStreamType method.

Parameters

userId	ID of the remote user sending the video stream.
streamType	Sets the video-stream type. See REMOTE_VIDEO_STREAM_TYPE.

Returns

• 0: Success.
• < 0: Failure.

Sets the default stream type of remote videos.

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-video stream (the low resolution, and low bitrate video stream).

By default, users receive the high-quality video stream. Call this method if you want to switch to the low-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-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-video stream.

The method result returns in the onApiCallExecuted callback.

Note

• This method can only be called before joining a channel. Agora does not support you to change the default subscribed video stream type after joining a channel.
• If you call both this method and setRemoteVideoStreamType, the SDK applies the settings in the setRemoteVideoStreamType method.

Parameters

streamType

Sets the default video-stream type. See REMOTE_VIDEO_STREAM_TYPE.

Returns

• 0: Success.
• < 0: Failure.

Enables the reporting of users' volume indication.

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.

Note

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

Parameters

interval	Sets the time interval between two consecutive volume indications: ≤ 0: Disables the volume indication. > 0: Time interval (ms) between two consecutive volume indications. We recommend setting interval > 200 ms. Do not set interval < 10 ms, or the onAudioVolumeIndication callback will not be triggered.
smooth	Smoothing factor sets the sensitivity of the audio volume indicator. The value ranges between 0 and 10. The greater the value, the more sensitive the indicator. The recommended value is 3.
report_vad	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.

Enables reporting the voice pitch of the local user.

Since

v3.7.0

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

Note

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

Parameters

interval

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

Returns

• 0: Success.
• < 0: Failure.

Starts an audio recording.

Deprecated:

Deprecated from v2.9.1. Use startAudioRecording [3/3] instead.

The SDK allows recording during a call. Supported formats:

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

This method has a fixed sample rate of 32 kHz.

Ensure that the directory to save the recording file exists and is writable. This method is usually called after the joinChannel method. The recording automatically stops when the leaveChannel method is called.

Parameters

filePath	Pointer to the absolute file path of the recording file. The string of the file name is in UTF-8.
quality	Sets the audio recording quality. See AUDIO_RECORDING_QUALITY_TYPE.

Returns

• 0: Success.
• < 0: Failure.

Starts an audio recording on the client.

Deprecated:

Deprecated from v3.4.0. Use startAudioRecording [3/3] instead.

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

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

Note

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

Parameters

filePath	Pointer to the absolute file path of the recording file. The string of the file name is in UTF-8, such as c:/music/audio.aac.
sampleRate	Sample rate (Hz) of the recording file. Supported values are as follows: 16000 (Default) 32000 44100 48000
quality	Sets the audio recording quality. See AUDIO_RECORDING_QUALITY_TYPE.

Returns

• 0: Success.
• < 0: Failure.

Starts an audio recording on the client.

Since

v3.4.0

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

• WAV: High-fidelity files with typically larger file sizes. For example, if the sample rate is 32,000 Hz, the file size for a 10-minute recording is approximately 73 MB.
• AAC: Low-fidelity files with typically smaller file sizes. For example, if the sample rate is 32,000 Hz and the recording quality is AUDIO_RECORDING_QUALITY_MEDIUM, the file size for a 10-minute recording is approximately 2 MB.

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

Note

Call this method after joining a channel.

Parameters

config

Recording configuration. See AudioRecordingConfiguration.

Returns

• 0: Success.
• < 0: Failure.
  • -160(ERR_ALREADY_IN_RECORDING): The client is already recording audio. To start a new recording, call stopAudioRecording to stop the current recording first, and then call startAudioRecording.

Stops an audio recording on the client.

Returns

• 0: Success
• < 0: Failure.

Starts playing and mixing the music file.

Deprecated:

Deprecated from v3.4.0. Use startAudioMixing [2/2] instead.

This method mixes the specified local audio file with the audio stream from the microphone, or replaces the microphone's audio stream with the specified local audio file. You can choose whether the other user can hear the local audio playback and specify the number of playback loops. This method also supports online music playback.

When the audio mixing file playback finishes after calling this method, the SDK triggers the onAudioMixingFinished callback.

A successful startAudioMixing method call triggers the onAudioMixingStateChanged (PLAY) callback on the local client.

When the audio mixing file playback finishes, the SDK triggers the onAudioMixingStateChanged (STOPPED) callback on the local client.

Note

• If the local audio mixing file does not exist, or if the SDK does not support the file format or cannot access the music file URL, the SDK returns WARN_AUDIO_MIXING_OPEN_ERROR (701).
• If you want to play an online music file, ensure that the time interval between calling this method is more than 100 ms, or the AUDIO_MIXING_ERROR_TOO_FREQUENT_CALL(702) error code occurs.
• To avoid blocking, as of v3.4.5, this method changes from a synchronous call to an asynchronous call.
• For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support.
• On Android, to play an online file for which the URL address starts with http, you need to add android:usesCleartextTraffic="true" to the /app/Manifests/AndroidManifest.xml file.

Parameters

filePath	The absolute path or URL address (including the filename extensions) of the music file. For example: C:\music\audio.mp4. When you access a local file on Android, Agora recommends passing a URI address or the path starts with /assets/ in this parameter.
loopback	Sets which user can hear the audio mixing: true: Only the local user can hear the audio mixing. false: Both users can hear the audio mixing.
replace	Sets the audio mixing content: true: Only publish the specified audio file. The audio stream from the microphone is not published. false: The local audio file is mixed with the audio stream from the microphone.
cycle	Sets the number of playback loops: Positive integer: Number of playback loops. -1: Infinite playback loops.

Returns

• 0: Success.
• < 0: Failure.

Starts playing and mixing the music file.

Since

v3.4.0

This method supports mixing or replacing local or online music file and audio collected by a microphone. After successfully playing the music file, the SDK triggers onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING,AUDIO_MIXING_REASON_STARTED_BY_USER). After completing playing the music file, the SDK triggers onAudioMixingStateChanged(AUDIO_MIXING_STATE_STOPPED,AUDIO_MIXING_REASON_ALL_LOOPS_COMPLETED).

Note

• If you need to call startAudioMixing multiple times, ensure that the call interval is longer than 500 ms.
• If the local music file does not exist, or if the SDK does not support the file format or cannot access the music file URL, the SDK returns WARN_AUDIO_MIXING_OPEN_ERROR (701).
• On Android:
  • To use this method, ensure that the Android device is v4.2 or later and the API version is v16 or later.
  • If you need to play an online music file, Agora does not recommend using the redirected URL address. Some Android devices may fail to open a redirected URL address.
  • If you call this method on an emulator, ensure that the music file is in the /sdcard/ directory and the format is MP3.
  • To play an online file for which the URL address starts with http, you need to add android:usesCleartextTraffic="true" to the /app/Manifests/AndroidManifest.xml file.
• To avoid blocking, as of v3.4.5, this method changes from a synchronous call to an asynchronous call.
• For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support.

Parameters

filePath	The absolute path or URL address (including the filename extensions) of the music file. For example: C:\music\audio.mp4. When you access a local file on Android, Agora recommends passing a URI address or the path starts with /assets/ in this parameter.
loopback	Whether to only play the music file on the local client: true: Only play the music file on the local client so that only the local user can hear the music. false: Publish the music file to remote clients so that both the local user and remote users can hear the music.
replace	Whether to replace the audio collected by the microphone with a music file: true: Replace. Users can only hear music. false: Do not replace. Users can hear both music and audio collected 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 the music file once. -1: Play the music in an indefinite loop.
startPos	The playback position (ms) of the music file.

Returns

• 0: Success.
• < 0: Failure.

Sets the playback speed of the current music file.

Since

v3.5.1

Note

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.

Stops playing and mixing the music file.

Call this method when you are in a channel.

Returns

• 0: Success.
• < 0: Failure.

Pauses playing and mixing the music file.

Call this method when you are in a channel.

Returns

• 0: Success.
• < 0: Failure.

Specifies the playback track of the current music file.

Since

v3.5.1

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

Note

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

Parameters

index

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

Returns

• 0: Success.
• < 0: Failure.

Gets the number of audio tracks of the current music file.

Since

v3.5.1

Note

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

Returns

• > 0: The number of audio tracks of the current music file, if this method call succeeds.
• < 0: Failure.

Sets the channel mode of the current music file.

Since

v3.5.1

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

Note

• Call this method after calling startAudioMixing [2/2] and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.
• This method only applies to stereo audio files.

Parameters

mode	The channel mode. See AUDIO_MIXING_DUAL_MONO_MODE.

Returns

• 0: Success.
• < 0: Failure.

Resumes playing and mixing the music file.

Call this method when you are in a channel.

Returns

• 0: Success.
• < 0: Failure.

Deprecated:

Agora does not recommend using this method.

Sets the high-quality audio preferences. Call this method and set all parameters before joining a channel.

Do not call this method again after joining a channel.

Parameters

fullband	Sets whether to enable/disable 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	Sets whether to enable/disable stereo codec. Not compatible with SDK versions before v1.7.4: true: Enable stereo codec. false: Disable stereo codec.
fullBitrate	Sets whether to enable/disable high-bitrate mode. Recommended in voice-only mode: true: Enable high-bitrate mode. false: Disable high-bitrate mode.

Returns

• 0: Success.
• < 0: Failure.

Adjusts the volume during audio mixing.

Note

• Calling this method does not affect the volume of audio effect file playback invoked by the playEffect method.
• Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.

Parameters

volume

Audio mixing volume. The value ranges between 0 and 100 (default).

Returns

• 0: Success.
• < 0: Failure.

Adjusts the audio mixing volume for local playback.

Note

Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.

Parameters

volume

Audio mixing volume for local playback. The value ranges between 0 and 100 (default).

Returns

• 0: Success.
• < 0: Failure.

Gets the audio mixing volume for local playback.

This method helps troubleshoot audio volume related issues.

Note

• Call this method when you are in a channel.
• Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.

Returns

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

Adjusts the audio mixing volume for publishing (for remote users).

Note

Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.

Parameters

volume

Audio mixing volume for publishing. The value ranges between 0 and 100 (default).

Returns

• 0: Success.
• < 0: Failure.

Gets the audio mixing volume for publishing.

This method helps troubleshoot audio volume related issues.

Note

• Call this method when you are in a channel.
• Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.

Returns

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

Gets the duration (ms) of the music file.

Deprecated:

This method is deprecated as of v3.5.1. Use getAudioFileInfo instead.

Note

• Call this method when you are in a channel.
• Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.

Returns

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

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

Note

• Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.
• If you need to call getAudioMixingCurrentPosition multiple times, ensure that the call interval is longer than 500 ms.

Returns

• ≥ 0: The current playback position (ms) of the music file, if this method call succeeds. 0 represents that the current music file does not start playing.
• < 0: Failure.

Sets the playback position of the music file to a different starting position (the default plays from the beginning).

Note

Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.

Parameters

pos	The playback starting position (ms) of the music file.

Returns

• 0: Success.
• < 0: Failure.

Sets the pitch of the local music file.

Since

v3.0.1

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.

Note

Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.

Parameters

pitch

Sets the pitch of the local music file by 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.

Gets the volume of the audio effects.

The value ranges between 0.0 and 100.0.

Note

Ensure that this method is called after playEffect .

Returns

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

Sets the volume of the audio effects.

Note

Ensure that this method is called after playEffect .

Parameters

volume

Sets the volume of the audio effects. The value ranges between 0 and 100 (default).

Returns

• 0: Success.
• < 0: Failure.

Sets the volume of a specified audio effect.

Note

Ensure that this method is called after playEffect .

Parameters

soundId	ID of the audio effect. Each audio effect has a unique ID.
volume	Sets the volume of the specified audio effect. The value ranges between 0 and 100 (default).

Returns

• 0: Success.
• < 0: Failure.

Enables/Disables face detection for the local user.

Since

v3.0.1

Note

• Applies to Android and iOS only.
• You can call this method either before or after joining a channel.

Once face detection is enabled, the SDK triggers the onFacePositionChanged callback to report the face information of the local user, which includes the following aspects:

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

Parameters

enable

Determines whether to enable the face detection function for the local user: true: Enable face detection. false: (Default) Disable face detection.

Returns

• 0: Success.
• < 0: Failure.

Plays a specified local or online audio effect file.

Deprecated:

Deprecated from v3.4.0. Use playEffect [2/2] instead.

This method allows you to set the loop count, pitch, pan, and gain of the audio effect file, as well as whether the remote user can hear the audio effect.

To play multiple audio effect files simultaneously, call this method multiple times with different soundIds and filePaths. We recommend playing no more than three audio effect files at the same time.

Note

• If the audio effect is preloaded into the memory through the preloadEffect method, the value of soundID must be the same as that in the preloadEffect method.
• Playing multiple online audio effect files simultaneously is not supported on macOS and Windows.
• Ensure that you call this method after joining a channel.
• For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support.
• On Android, to play an online file for which the URL address starts with http, you need to add android:usesCleartextTraffic="true" to the /app/Manifests/AndroidManifest.xml file.
• To use playEffect to play an online audio effect file, Agora recommends that you cache the online audio effect file to your local device, call preloadEffect to preload the cached audio effect file into memory, and then call playEffect to play the audio effect. Otherwise, you can experience playback failures and silence due to online audio effect file loading timeouts or loading failures.

Parameters

soundId	ID of the specified audio effect. Each audio effect has a unique ID.
filePath	The absolute path or URL address (including the filename extensions) of the music file. For example: C:\music\audio.mp4. When you access a local file on Android, Agora recommends passing a URI address or the path starts with /assets/ in this parameter.
loopCount	Sets the number of times the audio effect loops: 0: Play the audio effect once. 1: Play the audio effect twice. -1: Play the audio effect in an indefinite loop until the stopEffect or stopAllEffects method is called.
pitch	Sets the pitch of the audio effect. The value ranges between 0.5 and 2. The default value is 1 (no change to the pitch). The lower the value, the lower the pitch.
pan	Sets the spatial position of the audio effect. The value ranges between -1.0 and 1.0: 0.0: The audio effect displays ahead. 1.0: The audio effect displays to the right. -1.0: The audio effect displays to the left.
gain	Sets the volume of the audio effect. The value ranges between 0 and 100 (default). The lower the value, the lower the volume of the audio effect.
publish	Sets whether to publish the specified audio effect to the remote stream: true: The locally played audio effect is published to the Agora Cloud and the remote users can hear it. false: The locally played audio effect is not published to the Agora Cloud and the remote users cannot hear it.

Returns

• 0: Success.
• < 0: Failure.

Plays a specified local or online audio effect file.

Since

v3.4.0

To play multiple audio effect files at the same time, call this method multiple times with different soundId and filePath values. For the best user experience, Agora recommends playing no more than three audio effect files at the same time.

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

Note

• Call this method after joining a channel.
• For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support.
• On Android, to play an online file for which the URL address starts with http, you need to add android:usesCleartextTraffic="true" to the /app/Manifests/AndroidManifest.xml file.
• To use playEffect to play an online audio effect file, Agora recommends that you cache the online audio effect file to your local device, call preloadEffect to preload the cached audio effect file into memory, and then call playEffect to play the audio effect. Otherwise, you can experience playback failures and silence due to online audio effect file loading timeouts or loading failures.

Parameters

soundId	Audio effect ID. The ID of each audio effect file is unique. If you preloaded an audio effect into memory by calling preloadEffect, ensure that this parameter is set to the same value as in preloadEffect.
filePath	The absolute path or URL address (including the filename extensions) of the music file. For example: C:\music\audio.mp4. If you preloaded an audio effect into memory by calling preloadEffect, ensure that this parameter is set to the same value as in preloadEffect. When you access a local file on Android, Agora recommends passing a URI address or the path starts with /assets/ in this parameter.
loopCount	The number of times the audio effect loops: ≥ 0: The number of loops. For example, 1 means loop one time, which means play the audio effect two times in total. -1: Play the audio effect in an indefinite loop.
pitch	The pitch of the audio effect. The 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 range is -1.0 to 1.0. For example: -1.0: The audio effect occurs on the left. 0.0: The audio effect occurs in the front. 1.0: The audio effect occurs on the right.
gain	The volume of the audio effect. The range is 0.0 to 100.0. The default value is 100.0, which means the original volume. The smaller the value, the less the gain.
publish	Whether to publish the audio effect to the remote users: true: Publish. Both the local user and remote users can hear the audio effect. false: Do not publish. Only the local user can hear the audio effect.
startPos	The playback position (ms) of the audio effect file.

Returns

• 0: Success.
• < 0: Failure.

Stops playing a specified audio effect.

Parameters

soundId

ID of the audio effect to stop playing. Each audio effect has a unique ID.

Returns

• 0: Success.
• < 0: Failure.

Stops playing all audio effects.

Returns

• 0: Success.
• < 0: Failure.

Preloads a specified audio effect file into the memory.

Note

• This method does not support online audio effect files. For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support.
• To ensure smooth communication, limit the size of the audio effect file.
• You can call this method either before or after joining a channel.

Parameters

soundId	ID of the audio effect. Each audio effect has a unique ID.
filePath	The absolute path or URL address (including the filename extensions) of the music file. For example: C:\music\audio.mp4. When you access a local file on Android, Agora recommends passing a URI address or the path starts with /assets/ in this parameter.

Returns

• 0: Success.
• < 0: Failure.

Releases a specified preloaded audio effect from the memory.

Parameters

soundId

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

Returns

• 0: Success.
• < 0: Failure.

Pauses a specified audio effect.

Parameters

soundId

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

Returns

• 0: Success.
• < 0: Failure.

Pauses all audio effects.

Returns

• 0: Success.
• < 0: Failure.

Resumes playing a specified audio effect.

Parameters

soundId

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

Returns

• 0: Success.
• < 0: Failure.

Resumes playing all audio effects.

Returns

• 0: Success.
• < 0: Failure.

Gets the information of a specified audio file.

Since

v3.4.0

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.

Note

• Call this method after joining a channel.
• For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support.
• As of v3.7.0, the behavior of getEffectDuration has changed from getting the duration of a specified audio effect file to getting the information of a specified audio file.

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

Returns

• 0: Success.
• < 0: Failure.

Sets the playback position of an audio effect file.

Since

v3.4.0

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

Note

Call this method after playEffect .

Parameters

soundId	Audio effect ID. Ensure that this parameter is set to the same value as in playEffect .
pos	The playback position (ms) of the audio effect file.

Returns

• 0: Success.
• < 0: Failure.
  • -22(ERR_RESOURCE_LIMITED): Cannot find the audio effect file. Please set a correct soundId.

Gets the playback position of the audio effect file.

Since

v3.4.0

Note

Call this method after playEffect .

Parameters

soundId

Audio effect ID. Ensure that this parameter is set to the same value as in playEffect .

Returns

• ≥ 0: A successful method call. Returns the playback position (ms) of the specified audio effect file.
• < 0: Failure.
  • -22(ERR_RESOURCE_LIMITED): Cannot find the audio effect file. Please set a correct soundId.

Gets the information of a specified audio file.

Since

v3.5.1

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.

Note

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

Parameters

filePath

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

Returns

• 0: Success.
• < 0: Failure.

Enables or disables deep-learning noise reduction.

Since

v3.3.0

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

1. Ensure that the dynamical library is integrated in your project:
   • Android: libagora_ai_denoise_extension.so
   • iOS/macOS: AgoraAIDenoiseExtension.xcframework
   • Windows: libagora_ai_denoise_extension.dll
2. Call enableDeepLearningDenoise(true).

Deep-learning noise reduction requires high-performance devices. For example, the following devices and later models are known to support deep-learning noise reduction:

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

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

If you call enableDeepLearningDenoise(false) 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).

Note

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

Parameters

enable

Sets whether to enable deep-learning noise reduction. true: Enables deep-learning noise reduction. false: Disable deep-learning noise reduction.

Returns

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

Enables/Disables stereo panning for remote users.

Ensure that you call this method before joinChannel 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

Sets whether to enable stereo panning for remote users: true: Enable stereo panning. false: Disable stereo panning.

Returns

• 0: Success.
• < 0: Failure.

Sets the sound position and gain of a remote user.

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

Note

• For this method to work, enable stereo panning for remote users by calling the enableSoundPositionIndication method before joining a channel.
• This method requires hardware support. For the best sound positioning, we recommend using a wired headset.
• Ensure that you call this method after joining a channel.

Parameters

uid	The ID of the remote user.
pan	The sound position of the remote user. The value ranges from -1.0 to 1.0: 0.0: the remote sound comes from the front. -1.0: the remote sound comes from the left. 1.0: the remote sound comes from the right.
gain	Gain of the remote user. The value ranges from 0.0 to 100.0. The default value is 100.0 (the original gain of the remote user). The smaller the value, the less the gain.

Returns

• 0: Success.
• < 0: Failure.

Changes the voice pitch of the local speaker.

Note

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

Parameters

pitch

Sets the voice pitch. The value ranges between 0.5 and 2.0. The lower the value, the lower the voice pitch. The default value is 1.0 (no change to the local voice pitch).

Returns

• 0: Success.
• < 0: Failure.

Sets the local voice equalization effect.

Note

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

Parameters

bandFrequency	Sets 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. See AUDIO_EQUALIZATION_BAND_FREQUENCY.
bandGain	Sets the gain of each band in dB. The value ranges between -15 and 15.

Returns

• 0: Success.
• < 0: Failure.

Sets the local voice reverberation.

As of v3.2.0, the SDK provides a more convenient method setAudioEffectPreset, which directly implements the popular music, R&B music, KTV and other preset reverb effects.

Note

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

Parameters

reverbKey	Sets the reverberation key. See AUDIO_REVERB_TYPE.
value	Sets the value of the reverberation key. See AUDIO_REVERB_TYPE.

Returns

• 0: Success.
• < 0: Failure.

Sets the local voice changer option.

Deprecated:

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

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

This method can be used to set the local voice effect for users in a COMMUNICATION channel or hosts in a LIVE_BROADCASTING channel. Voice changer options include the following voice effects:

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

Note

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

Parameters

voiceChanger

Sets the local voice changer option. The default value is VOICE_CHANGER_OFF, which means the original voice. See details in VOICE_CHANGER_PRESET.

Returns

• 0: Success.
• < 0: Failure. Check if the enumeration is properly set.

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

Deprecated:

Deprecated from v3.2.0. Use setAudioEffectPreset or setVoiceBeautifierPreset instead.

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.

Note

• When calling this method with enumerations that begin with AUDIO_REVERB_FX, ensure that you set profile in setAudioProfile as AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5); otherwise, this methods cannot set the corresponding voice reverberation option.
• When calling this method with AUDIO_VIRTUAL_STEREO, Agora recommends setting the profile parameter in setAudioProfile as AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5).
• This method works best with the human voice, and Agora does not recommend using it for audio containing music and a human voice.
• Do not use this method with setLocalVoiceChanger, because the method called later overrides the one called earlier. For detailed considerations, see the advanced guide Set the Voice Effect.
• You can call this method either before or after joining a channel.

Parameters

reverbPreset

The local voice reverberation option. The default value is AUDIO_REVERB_OFF, which means the original voice. 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.

Sets an SDK preset voice beautifier effect.

Since

v3.2.0

Call this method to set an SDK 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. See Set the Voice Effect.

To achieve better audio effect quality, Agora recommends calling setAudioProfile and setting the scenario parameter to AUDIO_SCENARIO_GAME_STREAMING(3) and the profile parameter to AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5) before calling this method.

Note

• You can call this method either before or after joining a channel.
• Do not set the profile parameter of setAudioProfile to AUDIO_PROFILE_SPEECH_STANDARD(1) or AUDIO_PROFILE_IOT(6); otherwise, this method call does not take effect.
• This method works best with the human voice. Agora does not recommend using this method for audio containing music.
• After calling this method, Agora recommends not calling the following methods, because they can override setAudioEffectParameters:
  • setAudioEffectPreset
  • setVoiceBeautifierPreset
  • setLocalVoiceReverbPreset
  • setLocalVoiceChanger
  • setLocalVoicePitch
  • setLocalVoiceEqualization
  • setLocalVoiceReverb
  • setVoiceBeautifierParameters
  • setVoiceConversionPreset

Parameters

preset

The options for SDK preset voice beautifier effects: VOICE_BEAUTIFIER_PRESET.

Returns

• 0: Success.
• < 0: Failure.

Sets an SDK preset audio effect.

Since

v3.2.0

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

To achieve better audio effect quality, Agora recommends calling setAudioProfile and setting the scenario parameter to AUDIO_SCENARIO_GAME_STREAMING(3) before calling this method.

Note

• You can call this method either before or after joining a channel.
• Do not set the profile parameter of setAudioProfile to AUDIO_PROFILE_SPEECH_STANDARD(1) or AUDIO_PROFILE_IOT(6); otherwise, this method call does not take effect.
• This method works best with the human voice. Agora does not recommend using this method for audio containing music.
• If you call this method and set the preset parameter to enumerators except ROOM_ACOUSTICS_3D_VOICE or PITCH_CORRECTION, do not call setAudioEffectParameters; otherwise, setAudioEffectParameters overrides this method.
• After calling this method, Agora recommends not calling the following methods, because they can override setAudioEffectPreset:
  • setVoiceBeautifierPreset
  • setLocalVoiceReverbPreset
  • setLocalVoiceChanger
  • setLocalVoicePitch
  • setLocalVoiceEqualization
  • setLocalVoiceReverb
  • setVoiceBeautifierParameters
  • setVoiceConversionPreset

Parameters

preset

The options for SDK preset audio effects. See AUDIO_EFFECT_PRESET.

Returns

• 0: Success.
• < 0: Failure.

Sets an SDK preset voice conversion effect.

Since

v3.3.1

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

You can set different voice conversion effects for different scenarios. See Set the Voice Effect.

To achieve better voice 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) and the scenario parameter to AUDIO_SCENARIO_GAME_STREAMING (3) before calling this method.

Note

• You can call this method either before or after joining a channel.
• Do not set the profile parameter of setAudioProfile to AUDIO_PROFILE_SPEECH_STANDARD (1) or AUDIO_PROFILE_IOT (6); otherwise, this method call does not take effect.
• This method works best with the human voice. Agora does not recommend using this method for audio containing music.
• After calling this method, Agora recommends not calling the following methods, because they can override setVoiceConversionPreset:
  • setAudioEffectPreset
  • setAudioEffectParameters
  • setVoiceBeautifierPreset
  • setVoiceBeautifierParameters
  • setLocalVoiceReverbPreset
  • setLocalVoiceChanger
  • setLocalVoicePitch
  • setLocalVoiceEqualization
  • setLocalVoiceReverb

Parameters

preset

The options for SDK preset voice conversion effects: VOICE_CONVERSION_PRESET.

Returns

• 0: Success.
• < 0: Failure.

Sets parameters for SDK preset audio effects.

Since

v3.2.0

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

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