Agora Java API Reference for Android

Creates an RtcEngine instance.

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

Note

• You must create an RtcEngine instance before calling any other method.
• You can create an RtcEngine instance either by calling this method or by calling create2. The difference between create2 and this method is that create2 enables you to specify the region for connection.
• The Agora RTC Native SDK supports creating only one RtcEngine instance for an app for now.

Parameters

context	The context of Android Activity.
appId	The App ID issued to you by Agora. See How to get the App ID. Only users in apps with the same App ID can join the same channel and communicate with each other. Use an App ID to create only one RtcEngine instance. To change your App ID, call destroy to destroy the current RtcEngine instance, and after destroy returns 0, call create to create an RtcEngine instance with the new App ID.
handler	IRtcEngineEventHandler is an abstract class providing default implementation. The SDK uses this class to report to the app on SDK runtime events.

Returns

• The RtcEngine instance, if the method call succeeds.
• < 0, if the method call fails.
  • ERR_INVALID_APP_ID(101): The app ID is invalid. Check if it is in the correct format.

Exceptions

Exception

Fails to create an RtcEngine instance.

Creates an RtcEngine instance.

Since

3.0.0.2

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

Note

• You must create an RtcEngine instance before calling any other method.
• You can create an RtcEngine instance either by calling this method or by calling create1. The difference between create1 and this method is that this method enables you to specify the region for connection.
• The Agora RTC Native SDK supports creating only one RtcEngine instance for an app for now.

Parameters

config

Configurations for the RtcEngine instance. For details, see RtcEngineConfig.

Returns

• The RtcEngine instance, if the method call succeeds.
• < 0, if the method call fails.
  • ERR_INVALID_APP_ID(101): The app ID is invalid. Check if it is in the correct format.

Exceptions

Exception

Fails to create an RtcEngine instance.

Destroys the RtcEngine instance and releases all resources used by the Agora SDK.

Use this method for apps in which users occasionally make voice or video calls. When users do not make calls, you can free up resources for other operations. Once you call destroy to destroy the created RtcEngine 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 create to create a new RtcEngine instance.

Note

• Because destroy is a synchronous method and the app cannot move on to another task until the execution completes, Agora suggests calling this method in a sub-thread to avoid congestion in the main thread. Besides, you cannot call destroy 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.
• If you want to create a new RtcEngine instance after destroying the current one, ensure that you wait till the destroy method completes executing.

Sets the channel profile of the Agora RtcEngine.

After initialization, the SDK uses the CHANNEL_PROFILE_COMMUNICATION channel profile by default. You can call setChannelProfile to set the channel profile. The Agora RtcEngine differentiates channel profiles and applies different optimization algorithms accordingly. For example, it prioritizes smoothness and low latency for a video call, and prioritizes video quality for a video live interactive streaming.

Parameters

profile

The channel profile of the Agora RtcEngine: CHANNEL_PROFILE_COMMUNICATION(0): Communication. This profile applies to scenarios such as an audio call or video call, where all users can publish and subscribe to streams. CHANNEL_PROFILE_LIVE_BROADCASTING(1): Live interactive steaming. In this profile, uses have roles, namely, host and audience (default). A host can both publish and subscribe to streams, while an audience can only subscribe to streams. This profile applies to scenarios such as a chat room or interactive video streaming. CHANNEL_PROFILE_GAME(2): The Gaming profile. Agora does not recommend using this profile.

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(USER_OFFLINE_BECOME_AUDIENCE) on the remote client.

Note

This method applies to the LIVE_BROADCASTING profile only (when the profile parameter in setChannelProfile is set as CHANNEL_PROFILE_LIVE_BROADCASTING).

Parameters

role

The role of a user in interactive live streaming: CLIENT_ROLE_BROADCASTER(1): Host. A host can both send and receive streams. If you set this user role in the channel, the SDK automatically calls muteLocalAudioStream(false) and muteLocalVideoStream(false). CLIENT_ROLE_AUDIENCE(2): Audience. An audience member can only receive streams. If you set this user role in the channel, the SDK automatically calls muteLocalAudioStream(true) and muteLocalVideoStream(true).

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 a user in a live interactive streaming.

Since

v3.2.0

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(USER_OFFLINE_BECOME_AUDIENCE) on the remote client.

Note

• This method applies to the LIVE_BROADCASTING profile only (when the profile parameter in setChannelProfile is set as CHANNEL_PROFILE_LIVE_BROADCASTING).
• The difference between this method and setClientRole1 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 can choose to receive remote streams with low latency or ultra low latency. User level affects the pricing of services.

Sample code

Parameters

role

The role of a user in a live interactive streaming: CLIENT_ROLE_BROADCASTER(1): Host. A host can both send and receive streams. If you set this user role in the channel, the SDK automatically calls muteLocalAudioStream(false) and muteLocalVideoStream(false). CLIENT_ROLE_AUDIENCE(2): Audience. An audience member can only receive streams. If you set this user role in the channel, the SDK automatically calls muteLocalAudioStream(true) and muteLocalVideoStream(true).

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.

Agora supports reporting and analyzing customized messages.

Since

3.1.0

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

Allows a user to join a channel.

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 joining another channel.

A successful method call of joinChannel 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 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.

Warning

• 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.
• Ensure that the App ID used for creating the token is the same App ID used in the create method for creating an RtcEngine object.

Parameters

token	The token generated at your server. For details, see Authenticate Your Users with Tokens.
channelName	The 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
optionalInfo	Reserved for future use.
optionalUid	(Optional) User ID. A 32-bit unsigned integer with a value ranging from 1 to (2^32-1). optionalUid must be unique. If optionalUid is not assigned (or set to 0), the SDK assigns and returns uid in the onJoinChannelSuccess callback. Your app must record and maintain the returned uid since the SDK does not do so. The uid is represented as a 32-bit unsigned integer in the SDK. Since unsigned integers are not supported by Java, the uid is handled as a 32-bit signed integer and larger numbers are interpreted as negative numbers in Java. If necessary, the uid can be converted to a 64-bit integer through “uid&0xffffffffL”.

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. Possible reasons:
    • You have created an RtcChannel object with the same channel name.
    • You have joined and published a stream in a channel created by the RtcChannel object. When you join a channel created by the RtcEngine 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 RtcEngine channel at a time. Therefore, the SDK returns this error code when a user who has already joined an RtcEngine channel calls the joining channel method of the RtcEngine 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.

Warning

• Compared with joinChannel[1/2], this method has the options parameter, which configures whether the user publish 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 create method for creating an RtcEngine object.

Parameters

token	The token generated at your server. For details, see Authenticate Your Users with Tokens.
channelName	The 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
optionalInfo	Reserved for future use.
optionalUid	(Optional) User ID. A 32-bit unsigned integer with a value ranging from 1 to (2^32-1). optionalUid must be unique. If optionalUid is not assigned (or set to 0), the SDK assigns and returns uid in the onJoinChannelSuccess callback. Your app must record and maintain the returned uid, because the SDK does not do so. The uid is represented as a 32-bit unsigned integer in the SDK. Since unsigned integers are not supported by Java, the uid is handled as a 32-bit signed integer and larger numbers are interpreted as negative numbers in Java. If necessary, the uid can be converted to a 64-bit integer through “uid&0xffffffffL”.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. Possible reasons:
    • You have created an RtcChannel object with the same channel name.
    • You have joined and published a stream in a channel created by the RtcChannel object.
  • -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 RtcEngine channel at a time. Therefore, the SDK returns this error code when a user who has already joined an RtcEngine channel calls the joining channel method of the RtcEngine class with a valid channel name.

Switches to a different channel.

Since

v2.9.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.

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

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

Parameters

token

The token generated at your server. For details, see Authenticate Your Users with Tokens.

channelName

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 end 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. For details, see Authenticate Your Users with Tokens.
channelName	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.

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 exited the channel when the method call returns. Once the user leaves the channel, the SDK triggers the onLeaveChannel callback.

A successful method call of leaveChannel 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 destroy method immediately after calling the leaveChannel method, the leaveChannel process interrupts, and the SDK does not trigger the onLeaveChannel callback.
• If you call the leaveChannel method during 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.

Renews the token when the current token expires.

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

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

The app should retrieve a new token from the server and call this method to renew it. Failure to do so results 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.

Registers a user account.

Since

v2.8.0.

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 you set this parameter 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.

Since

v2.8.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.

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. For details, see Authenticate Your Users with Tokens.
channelName	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. 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_JOIN_CHANNEL_REJECTED(-17): The request to join the channel is rejected. The SDK supports joining only one RtcEngine channel at a time. Therefore, the SDK returns this error code when a user who has already joined an RtcEngine channel calls the joining channel method of the RtcEngine class with a valid channel name.

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

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. For details, see Authenticate Your Users with Tokens.
channelName	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 you set this parameter and do not set it as null. 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)
  • ERR_JOIN_CHANNEL_REJECTED(-17): The request to join the channel is rejected. The SDK supports joining only one RtcEngine channel at a time. Therefore, the SDK returns this error code when a user who has already joined an RtcEngine channel calls the joining channel method of the RtcEngine class with a valid channel name.

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(TRANSPORT_TYPE_NONE_PROXY). To change the cloud proxy type that has been set, call setCloudProxy(TRANSPORT_TYPE_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. This parameter is required, and the SDK reports an error if you do not pass in a value. The cloud proxy types include: TRANSPORT_TYPE_NONE_PROXY(0): The automatic mode. In this mode, the SDK attempts a direct connection to SD-RTN™ and automatically switches to TLS 443 if the attempt fails. As of v3.6.2, the SDK has this mode enabled by default. TRANSPORT_TYPE_UDP_PROXY(1): The cloud proxy for the UDP protocol, that is, the Force UDP cloud proxy mode. In this mode, the SDK always transmits data over UDP. TRANSPORT_TYPE_TCP_PROXY(2): Since v3.6.2 The cloud proxy for the TCP (encryption) protocol, that is, the Force TCP cloud proxy mode. In this mode, the SDK always transmits data over TLS 443.

Returns

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

Gets the user information by passing in the user account.

Since

v2.8.0.

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 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.
userInfo	[in/out] A userInfo object that identifies the user. For details, see UserInfo. 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.

Since

v2.8.0.

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 ID of the remote user from the userInfo object by passing in the user account.

Parameters

uid	The user ID of the user. Ensure that you set this parameter.
userInfo	[in/out] A userInfo object that identifies the user. For details, see UserInfo. Input: A UserInfo object. Output: A UserInfo object that contains the user account and user ID of the user.

Returns

• 0: Success.
• < 0: Failure.

Enables interoperability with the Agora Web SDK (LIVE_BROADCASTING profile only).

Deprecated:

v3.0.0. As of v3.0.0, the Native SDK automatically enables interoperability with the Web SDK, so you no longer need to call this method.

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

Use this method when the channel profile is LIVE_BROADCASTING. Interoperability with the Agora Web SDK is enabled by default when the channel profile is Communication.

Parameters

enabled

Whether to enable/disable interoperability with the Agora Web SDK: true: Enable. false: (Default) Disable.

Returns

• 0: Success.
• < 0: Failure.

Gets the connection state of the SDK.

Since

v2.3.2.

Returns

The connection state:

• CONNECTION_STATE_DISCONNECTED(1): The SDK is disconnected from Agora edge server.
• CONNECTION_STATE_CONNECTING(2): The SDK is connecting to Agora edge server.
• CONNECTION_STATE_CONNECTED(3): The SDK joined a channel and is connected to Agora edge server. You can now publish or subscribe to a media stream in the channel.
• CONNECTION_STATE_RECONNECTING(4): The SDK keeps rejoining the channel after being disconnected from a joined channel because of network issues.
• CONNECTION_STATE_FAILED(5): The SDK fails to join the channel.

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

Since

v3.5.1

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

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

Warning

The super resolution feature requires extra system resources. To balance the visual experience and system consumption, the SDK poses the following restrictions:

• This feature can only be enabled for a single remote user.
• The original resolution of the remote user's video cannot exceed 640 × 360 pixels.

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

• WARN_SUPER_RESOLUTION_STREAM_OVER_LIMITATION(1610): The original resolution of the remote user's video is beyond the range where super resolution can be applied.
• WARN_SUPER_RESOLUTION_USER_COUNT_OVER_LIMITATION(1611): Super resolution is already being used to boost another remote user's video.
• WARN_SUPER_RESOLUTION_DEVICE_NOT_SUPPORTED(1612): The device does not support using super resolution.

Note

• Before calling this method, ensure that you have integrated the libagora_super_resolution_extension.so dynamic library into your project.
• Because this method has certain system performance requirements, Agora recommends that you use the following devices or better:
  • VIVO: V1821A, NEX S, 1914A, 1916A, 1962A, 1824BA, X60, X60 Pro
  • OPPO: PCCM00, Find X3
  • OnePlus: A6000
  • Xiaomi: Mi 8, Mi 9, Mi 10, Mi 11, MIX3, Redmi K20 Pro
  • SAMSUNG: SM-G9600, SM-G9650, SM-N9600, SM-G9708, SM-G960U, SM-G9750, S20, S21
  • HUAWEI: SEA-AL00, ELE-AL00, VOG-AL00, YAL-AL10, HMA-AL00, EVR-AN00, nova 4, nova 5 Pro, nova 6 5G, nova 7 5G, Mate 30, Mate 30 Pro, Mate 40, Mate 40 Pro, P40 P40 Pro, HUAWEI MediaPad M6, MatePad 10.8

Parameters

uid	The user ID of the remote user.
enable	Determines whether to enable super resolution for the remote user's video: true: Enable super resolution. false: Do not enable super resolution.

Returns

• 0: Success.
• < 0: Failure.
  • -157 (ERR_MODULE_NOT_FOUND): The dynamic library for super resolution is not integrated.

Enables the audio module.

The audio module is enabled by default.

Note

• This method affects the internal engine and can be called after calling 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 following API methods to control the audio engine modules separately:
  • enableLocalAudio: Whether to enable the microphone to create the local audio stream.
  • muteLocalAudioStream: Whether to publish the local audio stream.
  • muteRemoteAudioStream: Whether to subscribe to and play the remote audio stream.
  • muteAllRemoteAudioStreams: Whether to subscribe to and play all remote audio streams.

Returns

• 0: Success.
• < 0: Failure.

Disables the audio module.

Note

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

Returns

• 0: Success.
• < 0: Failure.

Disables the audio function in the channel.

Deprecated:

This method is deprecated. We recommend using the enableAudio method instead.

Returns

• 0: Success.
• < 0: Failure.

Resumes the audio playback in the channel.

Deprecated:

This method is deprecated. We recommend using the disableAudio method instead.

Returns

• 0: Success.
• < 0: Failure.

Sets the audio parameters and application scenarios.

Note

• You must call this method before calling 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, we recommend setting profile as MUSIC_HIGH_QUALITY (4) and scenario as GAME_STREAMING (3). For example, for music education scenarios.

Parameters

profile	Sets the sample rate, bitrate, encoding mode, and the number of channels. See Audio Profile.
scenario	Sets the audio application scenario. See AudioScenario. 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?.

Sets the high-quality audio preferences.

Deprecated:

This method is deprecated. Agora does not recommend using this method. If you want to set the audio profile, use the setAudioProfile method. Call this method and set all parameters before joining a channel. Do not call this method again after joining a channel.

Parameters

fullband	Whether to enable full-band codec (48-kHz sample rate), not compatible with versions earlier than v1.7.4: true: Enable full-band codec. false: Disable full-band codec.
stereo	Whether to enable stereo codec, not compatible with versions earlier than v1.7.4: true: Enable stereo codec. false: Disable stereo codec.
fullBitrate	Whether to enable 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 of the signal captured by the microphone.

Parameters

volume

The volume of the signal captured by the microphone. The value ranges between 0 and 400, including the following: 0: Mute. 100: (Default) Original volume. 400: Four times the original volume with signal-clipping protection.

Returns

• 0: Success.
• < 0: Failure.

Adjusts the playback signal volume of all remote users.

Note

• This method adjusts the playback volume which is mixed volume of all remote users.
• Since v2.3.2, to mute the local audio playback, call both adjustPlaybackSignalVolume and adjustAudioMixingVolume, and set volume as 0.

Parameters

volume

The playback volume. The value ranges between 0 and 400, including the following: 0: Mute. 100: (Default) Original volume. 400: Four times the original volume with signal-clipping protection.

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.

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.
smooth	The 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 scenarios 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.

Enables the audio quality callbacks.

Deprecated:

From v2.4.1.

The SDK triggers the onAudioQuality callback after this method is enabled.

Parameters

enabled

Whether to enable/disable the audio quality callback: true: Enable the audio quality notification callback. false: (Default) Disable the audio quality notification callback.

Returns

• 0: Success.
• < 0: Failure.

Enables/Disables the local audio capture.

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

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

Note

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

Parameters

enabled

Whether to disable/re-enable the local audio function: true: (Default) Re-enable the local audio function, that is, to start local audio capture and processing. false: Disable the local audio function, that is, to stop local audio capture and processing.

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

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

muted

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 stream of a specified user.

Note

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

Parameters

uid	The user ID of the specified remote user.
muted	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.

Adjusts the playback signal volume of a specified remote user.

Since

v3.0.0.

You can all 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	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 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 recommend not calling muteAllRemoteAudioStreams and setDefaultMuteAllRemoteAudioStreams together; otherwise, the settings may not take effect. See Set the Subscribing State.

Parameters

muted

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.

Sets whether to receive all remote audio streams by default.

Deprecated:

This method is deprecated from v3.3.0.

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

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

muted

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.

Enables the video module.

You can call this method either before joining a channel or during a call. If you call this method before joining a channel, the service starts in the video mode. If you call this method during an audio call, the audio mode switches to the video mode.

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

To disable the video, call the disableVideo method.

Note

• This method affects the internal engine and can be called after calling 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 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.

You can call this method before joining a channel or during a call. If you call this method before joining a channel, the service starts in audio mode. If you call this method during a video call, the video mode switches to the audio mode.

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

To enable the video mode, call the enableVideo method.

Note

• This method affects the internal engine and can be called after calling 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 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.

Sets the video encoding profile.

Deprecated:

From v2.3.0. We recommend using the setVideoEncoderConfiguration method to set the video profile.

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

If you do not need to change the video encoding profile after joining a channel, call this method before calling the enableVideo method to reduce the render time of the first video frame.

Each video encoding profile includes a set of parameters, such as the resolution, frame rate, and bitrate. When the camera does not support the specified resolution, the SDK chooses a suitable camera resolution, while the encoder resolution is specified by this method.

Parameters

profile	Sets the video encoding profile. See VideoProfile.
swapWidthAndHeight	The width and height of the output video is consistent with the set video profile. swapWidthAndHeight sets whether to swap the width and height of the stream: true: Swap the width and height. The video is in portrait mode (width < height). false: (Default) Do not swap the width and height. The video is in landscape mode (width > height).

Returns

• 0: Success.
• < 0: Failure.

Manually sets the video encoding profile.

Deprecated:

From v2.3.0. We recommend using the setVideoEncoderConfiguration method to set the video profile.

Each video encoding 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 this method. If the user does not set the video encoding profile after joining a channel, We recommend calling this method before calling the enableVideo method to minimize the time delay in receiving the first video frame.

Parameters

width	Sets the width of the video. The maximum value of width × height is 1280 × 720.
height	Sets the height of the video. The maximum value of width × height is 1280 × 720.
frameRate	Sets the frame rate of the video. The highest value is 30. You can set frameRate as 5, 10, 15, 24, and 30.
bitrate	Sets the bitrate of the video. You need to manually work out the bitrate according to the width, height, and frame rate. For the correlation between the width, height, and frame rate. See the table in Bitrate.

With the same width and height, the bitrate varies with the frame rate:

• If the frame rate is 5 fps, divide the recommended bitrate by 2.
• If the frame rate is 15 fps, use the recommended bitrate.
• If the frame rate is 30 fps, multiply the recommended bitrate by 1.5.
• Calculate the bitrate according to the ratio if you choose other frame rates.

If you set a bitrate beyond the proper range, the SDK automatically adjusts the bitrate to a value within the proper range.

Sets the video encoder configuration.

Since

v2.3.0. This method replaces the setVideoProfile method.

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.

If you do not set the video encoder configuration after joining the channel, you can call this method before calling the enableVideo method to reduce the render time of the first video frame.

Parameters

config

The local video encoder configuration. See VideoEncoderConfiguration.

Returns

• 0: Success.
• < 0: Failure.

Sets the camera capturer configuration.

Since

v2.4.0.

For a video call or live streaming, generally the SDK controls the camera output parameters. When the default camera capture 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).

Parameters

config

The camera capturer configuration. For details, see CameraCapturerConfiguration.

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.

Returns

• 0: Success.
• < 0: Failure.

Initializes the local video view.

This method initializes the video view of the 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 loca video stream to a video view and to set the rendering and mirror modes of the video view.

Note

• Call this method in the main thread.
• To update the rendering or mirror mode of the local video view during a call, use setLocalRenderMode.

Parameters

local

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

Typically, the app specifies the uid of the remote user sending the video in the method call before the remote user joins a channel. If the uid of the remote user is unknown to the app, set the uid when the app 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 app view because the dummy client does not send any video streams. If your app does not recognize the dummy client, bind the remote user to the view when the SDK triggers the onFirstRemoteVideoDecoded callback.

To unbind the remote user from the view, set view in Video Canvas as null. Once the remote user leaves the channel, the SDK unbinds the remote user.

Note

• Ensure that you call this method in the UI thread.
• To update the rendering or mirror mode of the remote video view during a call, use setRemoteRenderMode.

Parameters

remote

Sets the remote video view and settings. See Video Canvas.

Returns

• 0: Success.
• < 0: Failure.

Sets the local video display mode.

Deprecated:

v3.0.0. Use setLocalRenderMode2 instead.

Parameters

renderMode

Sets the local video display mode: RENDER_MODE_HIDDEN(1): Uniformly scale the video until it fills the visible boundaries (cropped). One dimension of the video may have clipped contents. RENDER_MODE_FIT(2): Uniformly scale the video until one of its dimension fits the boundary (zoomed to fit). Areas that are not filled due to the disparity in the aspect ratio are filled with black. RENDER_MODE_ADAPTIVE(3): This mode is deprecated and Agora does not recommend using this mode.

Returns

• 0: Success.
• < 0: Failure.

Updates the display mode of the local video view.

Since

v3.0.0.

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

Note

• Ensure that you have called the setupLocalVideo method to initialize the local video view before calling this method.
• During a call, you can call this method as many times as necessary to update

Parameters

renderMode

Sets the local video display mode: RENDER_MODE_HIDDEN(1): Uniformly scale the video until it fills the visible boundaries (cropped). One dimension of the video may have clipped contents. RENDER_MODE_FIT(2): Uniformly scale the video until one of its dimension fits the boundary (zoomed to fit). Areas that are not filled due to the disparity in the aspect ratio are filled with black. RENDER_MODE_ADAPTIVE(3): This mode is deprecated and Agora does not recommend using this mode. RENDER_MODE_FILL(4): The fill mode. In this mode, the SDK stretches or zooms the video to fill the display window.

mirrorMode

Sets the local video mirror mode: VIDEO_MIRROR_MODE_AUTO(0): (Default) The mirror mode determined by the SDK. If you use a front camera, the SDK enables the mirror mode by default; if you use a rear camera, the SDK disables the mirror mode by default. VIDEO_MIRROR_MODE_ENABLED(1): Enable the mirror mode. VIDEO_MIRROR_MODE_DISABLED(2): Disable the mirror mode.

Returns

• 0: Success.
• < 0: Failure.

Sets the remote video display mode.

Deprecated:

v3.0.0. Use setRemoteRenderMode2 instead.

This method can be invoked multiple times during a call to change the display mode.

Parameters

uid

User ID of the remote user.

renderMode

Sets the remote video display mode: RENDER_MODE_HIDDEN(1): Uniformly scale the video until it fills the visible boundaries (cropped). One dimension of the video may have clipped contents. RENDER_MODE_FIT(2): Uniformly scale the video until one of its dimension fits the boundary (zoomed to fit). Areas that are not filled due to the disparity in the aspect ratio are filled with black. RENDER_MODE_ADAPTIVE(3): This mode is deprecated and Agora does not recommend using this mode.

Returns

• 0: Success.
• < 0: Failure.

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

Since

v3.0.0.

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

Note

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

Parameters

uid	User ID of the remote user.
renderMode	Sets the remote video display mode: RENDER_MODE_HIDDEN(1): Uniformly scale the video until it fills the visible boundaries (cropped). One dimension of the video may have clipped contents. RENDER_MODE_FIT(2): Uniformly scale the video until one of its dimension fits the boundary (zoomed to fit). Areas that are not filled due to the disparity in the aspect ratio are filled with black. RENDER_MODE_ADAPTIVE(3): This mode is deprecated and Agora does not recommend using this mode. RENDER_MODE_FILL(4): The fill mode. In this mode, the SDK stretches or zooms the video to fill the display window.
mirrorMode	Sets the remote video mirror mode: VIDEO_MIRROR_MODE_AUTO(0): (Default) The mirror mode determined by the SDK. By default, the SDK disables the mirror mode for the remote video. VIDEO_MIRROR_MODE_ENABLED(1): Enable the mirror mode. VIDEO_MIRROR_MODE_DISABLED(2): Disable the mirror mode.

Returns

• 0: Success.
• < 0: Failure.

Creates a RendererView.

This method returns the SurfaceView type. The operation and layout of the view are managed by the app, and the Agora SDK renders the view provided by the app. The video display view must be created using this method instead of directly calling SurfaceView.

To use a SurfaceView, call this method; to use a TextureView, call CreateTextureView.

Note

Ensure that you call this method in the UI thread.

Parameters

context

The context of the Android Activity.

Returns

SurfaceView.

Creates a TextureView.

Since

v3.1.0.

You can call this method to create a TextureView, which is suitable for scenarios that require scaling, rotation, and parallel coordinate translation of video images, such as screen sharing. The operation and layout of the view are managed by the app, and the Agora SDK renders the view provided by the app.

To use a TextureView, call this method; to use a SurfaceView, call CreateRendererView.

Note

Ensure that you call this method in the UI thread.

Parameters

context

The context of the Android Activity.

Returns

TextureView

Starts the local video preview before joining a channel.

Before calling this method, you must:

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

Note

• By default, the local preview enables the mirror mode.
• Once you call this method 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.

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.

Disables/Re-enables 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

This method affects the internal engine and can be called after calling the leaveChannel method.

Parameters

enabled

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 other remote users. When you set enabled as false, this method does not require a local camera.

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

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

muted

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

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

uid	The user ID of the specified remote user.
muted	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.

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.
• As of v3.3.0, this method contains the function of setDefaultMuteAllRemoteVideoStreams. Agora recommend not calling muteAllRemoteVideoStreams and setDefaultMuteAllRemoteVideoStreams together; otherwise, the settings may not take effect. See Set the Subscribing State.

Parameters

muted

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.

Sets whether to receive all remote video streams by default.

Deprecated:

This method is deprecated from v3.3.0.

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

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

muted

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.

Enables/Disables image enhancement and sets the options.

Since

v2.4.0.

Note

• Call this method after calling enableVideo.
• This method applies to Android 5.0 or later.
• Agora has updated the Agora image enhancement algorithm from v3.6.0 to enhance image enhancement effects and support sharpness adjustment. If you want to experience optimized image enhancement effects or set the sharpness, integrate the libagora_video_process_extension.so dynamic library into the project before calling this method.

Parameters

enabled	Whether to enable image enhancement: true: Enables image enhancement. false: (Default) Disables image enhancement.
options	The image enhancement options. See BeautyOptions.

Returns

• 0: Success.
• < 0: Failure.
  • ERR_NOT_SUPPORTED(4): The system version is earlier than Android 5.0, which does not support this function.

Sets low-light enhancement.

Since

v3.6.2

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

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

Note

• Before calling this method, ensure that you have integrated the libagora_video_process_extension.so dynamic library.
• Call this method after enableVideo.
• The low-light enhancement feature has certain performance requirements on devices. If your device overheats after you enable low-light enhancement, Agora recommends modifying the low-light enhancement options to a less performance-consuming level or disabling low-light enhancement entirely.

Parameters

enabled	Sets whether to enable low-light enhancement: true: Enable. false: (Default) Disable.
options	The low-light enhancement options. See LowLightEnhanceOptions.

Returns

• 0: Success.
• < 0: Failure.

Sets video noise reduction.

Since

v3.6.2

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

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

Note

• Before calling this method, ensure that you have integrated the libagora_video_process_extension.so dynamic library.
• Call this method after enableVideo.
• The video noise reduction feature has certain performance requirements on devices. If your device overheats after you enable video noise reduction, Agora recommends modifying the video noise reduction options to a less performance-consuming level or disabling video noise reduction entirely.

Parameters

enabled	Sets whether to enable video noise reduction: true: Enable. false: (Default) Disable.
options	The video noise reduction options. See VideoDenoiserOptions.

Returns

• 0: Success.
• < 0: Failure.

Sets color enhancement.

Since

v3.6.2

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

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

Note

• Before calling this method, ensure that you have integrated the libagora_video_process_extension.so dynamic library.
• Call this method after enableVideo.
• The color enhancement feature has certain performance requirements on devices. If your device overheats after you enable color enhancement, Agora recommends modifying the color enhancement options to a less performance-consuming level or disabling color enhancement entirely.

Parameters

enabled	Sets whether to enable color enhancement: true: Enable. false: (Default) Disable.
options	The color enhancement options. See ColorEnhanceOptions.

Returns

• 0: Success.
• < 0: Failure.

Enables/Disables the virtual background.

Since

v3.5.0

After enabling the virtual background feature, you can replace the original background image of the local user with a custom background image. After the replacement, all users in the channel can see the custom background image. You can find out from the onVirtualBackgroundSourceEnabled callback whether the virtual background is successfully enabled or the cause of any errors.

Note

• Before calling this method, ensure that you have integrated the libagora_segmentation_extension.so dynamic library into the project folder.
• Call this method after enableVideo.
• This function requires a high-performance device. Agora recommends that you use this function on devices with the following chips:
  • Snapdragon 700 series 750G and later
  • Snapdragon 800 series 835 and later
  • Dimensity 700 series 720 and later
  • Kirin 800 series 810 and later
  • Kirin 900 series 980 and later
• Agora recommends that you use this function in scenarios that meet the following conditions:
  • A high-definition camera device is used, and the environment is uniformly lit.
  • The captured video image is uncluttered, the user's portrait is half-length and largely unobstructed, and the background is a single color that differs from the color of the user's clothing.
• For versions earlier than v3.6.1, the virtual background feature does not support video in the Texture format or video obtained from custom video capture by the Push method.

Parameters

enabled	Sets whether to enable the virtual background: true: Enable. false: Disable.
backgroundSource	The custom background image. See VirtualBackgroundSource. Note: To adapt the resolution of the custom background image to the resolution of the SDK capturing video, the SDK scales and crops the custom background image while ensuring that the content of the custom background image is not distorted.

Returns

• 0: Success.
• < 0: Failure.

Sets the default audio route.

If the default audio route of the SDK (see Set the Audio Route) cannot meet your requirements, you can call this method to switch the default audio route. After successfully switching the audio route, the SDK triggers the onAudioRouteChanged callback to indicate the changes.

Note

• Call this method before calling joinChannel. If you need to switch the audio route after joining a channel, call setEnableSpeakerphone.
• If the user uses an external audio playback device such as a Bluetooth or wired headset, this method does not take effect, and the SDK plays audio through the external device. When the user uses multiple external devices, the SDK plays audio through the last connected device.

Parameters

defaultToSpeaker

Sets the default audio route as follows: true: Set to the speakerphone. false: Set to the earpiece.

Returns

• 0: Success.
• < 0: Failure.

Enables/Disables the audio route to the speakerphone.

If the default audio route of the SDK (see Set the Audio Route) or the setting in setDefaultAudioRoutetoSpeakerphone cannot meet your requirements, you can call this method to switch the current audio route. After successfully switching the audio route, the SDK triggers the onAudioRouteChanged callback to indicate the changes.

This method only sets the audio route in the current channel and does not influence the default audio route. If the user leaves the current channel and joins another channel, the default audio route is used.

Note

• Call this method after calling joinChannel.
• If the user uses an external audio playback device such as a Bluetooth or wired headset, this method does not take effect, and the SDK plays audio through the external device. When the user uses multiple external devices, the SDK plays audio through the last connected device.

Parameters

enabled

Sets whether to enable the speakerphone or earpiece: true: Enable the speakerphone. The audio route is the speakerphone. false: Disable the speakerphone. The audio route is the earpiece.

Returns

• 0: Success.
• < 0: Failure.

Checks whether the speakerphone is enabled.

Note

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

Returns

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

Enables in-ear monitoring.

Note

Users must use wired earphones to hear their own voices.

Parameters

enabled

Sets whether to enable/disable in-ear monitoring: true: Enable. false: (Default) Disable.

Returns

• 0: Success.
• < 0: Failure.

Sets the volume of the in-ear monitor.

Note

Users must use wired earphones to hear their own voices.

Parameters

volume

Sets the volume of the in-ear monitor. The value ranges between 0 and 100 (default).

Returns

• 0: Success.
• < 0: Failure.

Uses an external audio device.

Deprecated:

This method is deprecated.

Returns

• 0: Success.
• < 0: Failure.

Changes the voice pitch of the local speaker.

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.
• -1: Failure.

Sets the local voice equalization effect.

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.
bandGain	Sets the gain of each band (dB). The value ranges between -15 and 15. The default value is 0.

Returns

• 0: Success.
• -1: Failure.

Sets the local voice reverberation.

Note

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.

Parameters

reverbKey

The reverberation key. This method contains five reverberation keys. For details, see the description of each @ value.

value

The local voice reverberation value: AUDIO_REVERB_DRY_LEVEL(0): Level of the dry signal (-20 to 10 dB). AUDIO_REVERB_WET_LEVEL(1): Level of the early reflection signal (wet signal) (-20 to 10 dB). AUDIO_REVERB_ROOM_SIZE(2): Room size of the reflection (0 to 100 dB). AUDIO_REVERB_WET_DELAY(3): Length of the initial delay of the wet signal (0 to 200 ms). AUDIO_REVERB_STRENGTH(4): Strength of the late reverberation (0 to 100).

Returns

• 0: Success.
• -1: 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.

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

Since

v2.4.0.

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 or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO.
• 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.

Parameters

voiceChanger

The local voice changer option: VOICE_CHANGER_OFF: (Default) Turn off the local voice changer, that is, to use the original voice. VOICE_CHANGER_OLDMAN: The voice of an old man. VOICE_CHANGER_BABYBOY: The voice of a little boy. VOICE_CHANGER_BABYGIRL: The voice of a little girl. VOICE_CHANGER_ZHUBAJIE: The voice of Zhu Bajie, a character in Journey to the West who has a voice like that of a growling bear. VOICE_CHANGER_ETHEREAL: The ethereal voice. VOICE_CHANGER_HULK: The voice of Hulk. VOICE_BEAUTY_VIGOROUS: A more vigorous voice. VOICE_BEAUTY_DEEP: A deeper voice. VOICE_BEAUTY_MELLOW: A mellower voice. VOICE_BEAUTY_FALSETTO: Falsetto. VOICE_BEAUTY_FULL: A fuller voice. VOICE_BEAUTY_CLEAR: A clearer voice. VOICE_BEAUTY_RESOUNDING: A more resounding voice. VOICE_BEAUTY_RINGING: A more ringing voice. VOICE_BEAUTY_SPACIAL: A more spatially resonant voice. GENERAL_BEAUTY_VOICE_MALE_MAGNETIC: (For male only) A more magnetic voice. Do not use it when the speaker is a female; otherwise, voice distortion occurs. GENERAL_BEAUTY_VOICE_FEMALE_FRESH: (For female only) A fresher voice. Do not use it when the speaker is a male; otherwise, voice distortion occurs. GENERAL_BEAUTY_VOICE_FEMALE_VITALITY: (For female only) A more vital voice. Do not use it when the speaker is a male; otherwise, voice distortion occurs.

Returns

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

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

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

Deprecated:

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

Since

v2.4.0.

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 or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO, otherwise, this methods cannot set the corresponding voice reverb.
• When calling this method with AUDIO_VIRTUAL_STEREO, Agora recommends setting the profile parameter in setAudioProfile as AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO.
• 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.

Parameters

preset

The local voice reverberation option. To achieve better voice effects, Agora recommends the enumeration whose name begins with AUDIO_REVERB_FX. AUDIO_REVERB_OFF: (Default) Turn off local voice reverberation, that is, to use the original voice. AUDIO_REVERB_POPULAR: The reverberation style typical of popular music. AUDIO_REVERB_RNB: The reverberation style typical of R&B music. AUDIO_REVERB_ROCK: The reverberation style typical of rock music. AUDIO_REVERB_HIPHOP: The reverberation style typical of hip-hop music. AUDIO_REVERB_VOCAL_CONCERT: The reverberation style typical of a concert hall. AUDIO_REVERB_KTV: The reverberation style typical of a KTV venue. AUDIO_REVERB_STUDIO: The reverberation style typical of a recording studio. AUDIO_REVERB_FX_KTV: The reverberation style typical of a KTV venue (enhanced). AUDIO_REVERB_FX_VOCAL_CONCERT: The reverberation style typical of a concert hall (enhanced). AUDIO_REVERB_FX_UNCLE: The reverberation style typical of an uncle's voice. AUDIO_REVERB_FX_SISTER: The reverberation style typical of a little sister's voice. AUDIO_REVERB_FX_STUDIO: The reverberation style typical of a recording studio (enhanced). AUDIO_REVERB_FX_POPULAR: The reverberation style typical of popular music (enhanced). AUDIO_REVERB_FX_RNB: The reverberation style typical of R&B music (enhanced). AUDIO_REVERB_FX_PHONOGRAPH: The reverberation style typical of the vintage phonograph. AUDIO_VIRTUAL_STEREO: The reverberation of the virtual stereo. The virtual stereo is an effect that renders the monophonic audio as the stereo audio, so that all users in the channel can hear the stereo voice effect. To achieve better virtual stereo reverberation, Agora recommends setting profile in setAudioProfile as AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO.

Returns

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

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

Parameters

preset

The options for SDK preset audio effects AUDIO_EFFECT_OFF ROOM_ACOUSTICS_KTV ROOM_ACOUSTICS_VOCAL_CONCERT ROOM_ACOUSTICS_STUDIO ROOM_ACOUSTICS_PHONOGRAPH ROOM_ACOUSTICS_VIRTUAL_STEREO ROOM_ACOUSTICS_SPACIAL ROOM_ACOUSTICS_ETHEREAL ROOM_ACOUSTICS_3D_VOICE VOICE_CHANGER_EFFECT_UNCLE VOICE_CHANGER_EFFECT_OLDMAN VOICE_CHANGER_EFFECT_BOY VOICE_CHANGER_EFFECT_SISTER VOICE_CHANGER_EFFECT_GIRL VOICE_CHANGER_EFFECT_PIGKING VOICE_CHANGER_EFFECT_HULK STYLE_TRANSFORMATION_RNB STYLE_TRANSFORMATION_POPULAR PITCH_CORRECTION

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); 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 setVoiceBeautifierPreset:
  • setAudioEffectPreset
  • setAudioEffectParameters
  • setLocalVoiceReverbPreset
  • setLocalVoiceChanger
  • setLocalVoicePitch
  • setLocalVoiceEqualization
  • setLocalVoiceReverb
  • setVoiceBeautifierParameters
  • setVoiceConversionPreset

Parameters

preset

The options for SDK preset voice beautifier effects: VOICE_BEAUTIFIER_OFF CHAT_BEAUTIFIER_MAGNETIC CHAT_BEAUTIFIER_FRESH CHAT_BEAUTIFIER_VITALITY TIMBRE_TRANSFORMATION_VIGOROUS TIMBRE_TRANSFORMATION_DEEP TIMBRE_TRANSFORMATION_MELLOW TIMBRE_TRANSFORMATION_FALSETTO TIMBRE_TRANSFORMATION_FULL TIMBRE_TRANSFORMATION_CLEAR TIMBRE_TRANSFORMATION_RESOUNDING TIMBRE_TRANSFORMATION_RINGING

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 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); 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_OFF VOICE_CHANGER_NEUTRAL VOICE_CHANGER_SWEET VOICE_CHANGER_SOLID VOICE_CHANGER_BASS

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.

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

Note

• You can call this method either before or after joining a channel.
• 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.
• Do not set the profile parameter of setAudioProfile to AUDIO_PROFILE_SPEECH_STANDARD(1); 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 audio effects: 3D voice effect: ROOM_ACOUSTICS_3D_VOICE Call setAudioProfile and set the profile parameter to AUDIO_PROFILE_MUSIC_STANDARD_STEREO(3) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5) before setting this enumerator; otherwise, the enumerator setting does not take effect. If the 3D voice effect is enabled, users need to use stereo audio playback devices to hear the anticipated voice effect. Pitch correction effect: PITCH_CORRECTION. To achieve better audio effect quality, Agora recommends calling setAudioProfile and setting the profile parameter to AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5) before setting this enumerator.
param1	If you set preset to ROOM_ACOUSTICS_3D_VOICE, the param1 sets the cycle period of the 3D voice effect. The value range is [1, 60] and the unit is a second. The default value is 10 seconds, indicating that the voice moves around you every 10 seconds. If you set preset to PITCH_CORRECTION, param1 sets the basic mode of the pitch correction effect: 1: (Default) Natural major scale. 2: Natural minor scale. 3: Japanese pentatonic scale.
param2	You need to set param2 to 0. If you set preset to PITCH_CORRECTION, param2 sets the tonic pitch of the pitch correction effect: 1: A 2: A# 3: B 4: (Default) C 5: C# 6: D 7: D# 8: E 9: F 10: F# 11: G 12: G#

Returns

• 0: Success.
• < 0: Failure.

Sets parameters for SDK preset voice beautifier effects.

Since

3.3.0.

Call this method to set a gender characteristic and a reverberation effect for the singing beautifier effect. This method sets parameters for the local user who sends an audio stream.

After you call this method successfully, all users in the channel can hear the relevant effect.

To achieve better audio effect quality, before you call this method, 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).

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); 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 you call this method, Agora recommends not calling the following methods, because they can override setVoiceBeautifierParameters:
  • setAudioEffectPreset
  • setAudioEffectParameters
  • setVoiceBeautifierPreset
  • setLocalVoiceReverbPreset
  • setLocalVoiceChanger
  • setLocalVoicePitch
  • setLocalVoiceEqualization
  • setLocalVoiceReverb
  • setVoiceConversionPreset

Parameters

preset	The options for SDK preset voice beautifier effects: SINGING_BEAUTIFIER: Singing beautifier effect.
param1	The gender characteristics options for the singing voice: 1: A male-sounding voice. 2: A female-sounding voice.
param2	The reverberation effects options: 1: The reverberation effect sounds like singing in a small room. 2: The reverberation effect sounds like singing in a large room. 3: The reverberation effect sounds like singing in a hall.

Returns

• 0: Success.
• < 0: Failure.

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 libagora_ai_denoise_extension.so library is integrated in your project.
• 2. Call enableDeepLearningDenoise(true).

Deep-learning noise reduction requires high-performance devices.

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 libagora_ai_denoise_extension.so, 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

enabled

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

Returns

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

Enables/Disables stereo panning for remote users.

Since

v2.4.0.

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

Whether to enable stereo panning for remote users: true: Enables stereo panning. false: Disables stereo panning.

Returns

• 0: Success.
• -1: Failure.

Sets the sound position of a remote user.

Since

v2.4.0.

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

• Ensure that you call this method after joining a channel.
• 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.

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.
• -1: 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 or online audio file with the audio stream from the microphone, or replaces the microphone’s audio stream with the specified local or remote audio file. You can choose whether the other user can hear the local audio playback and specify the number of playback loops. 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(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY) callback on the local client.

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

Note

• To use this method, ensure that the Android device is v4.2 or later, and the API version is v16 or later.
• 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 MEDIA_ENGINE_AUDIO_ERROR_MIXING_TOO_FREQUENT = 702 warning occurs.
• If you want 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 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 call this method on an emulator, only the MP3 file format is supported.
• 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 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/. Note: 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".
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.
  • WARN_AUDIO_MIXING_OPEN_ERROR (701): If the local audio file does not exist, or the online audio packet is not received within five seconds after it is opened, the SDK assumes that the media file cannot be used and returns this warning.

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

• Call this method after calling startAudioMixing[2/2] and receiving the onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY) callback.
• For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support.

Parameters

audioIndex

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

• Call this method after calling startAudioMixing[2/2] and receiving the onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY) 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(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY) callback.
• This method only applies to stereo audio files.

Parameters

mode	The channel mode. See AudioMixingDualMonoMode.

Returns

• 0: Success.
• < 0: Failure.

Starts playing and mixing the music file.

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

• 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.
• 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).
• 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 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/. Note 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".
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(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY) 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 or 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.

Resumes playing and mixing the music file.

Call this method when you are in a channel.

Returns

• 0: Success.
• < 0: Failure.

Adjusts the volume of audio mixing.

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

Note

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

Parameters

volume

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

Returns

• 0: Success.
• < 0: Failure.

Adjusts the volume of audio mixing for local playback.

Since

v2.3.2.

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

Parameters

volume

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

Returns

• 0: Success.
• < 0: Failure.

Adjusts the volume of audio mixing for publishing (sending to other users).

Since

v2.3.2.

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

Parameters

volume

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

Returns

• 0: Success.
• < 0: Failure.