Agora C++ API Reference for All Platforms

Initializes the Agora service.

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

Parameters

context

Pointer to the RTC engine context. See RtcEngineContext.

Returns

• 0: Success.
• < 0: Failure.
  • ERR_INVALID_APP_ID (101): The app ID is invalid. Check if it is in the correct format.

Releases all IRtcEngine resources.

Parameters

sync

true: (Synchronous call) The result returns after the IRtcEngine resources are released. The application should not call this method in the SDK generated callbacks. Otherwise, the SDK must wait for the callbacks to return to recover the associated IRtcEngine resources, resulting in a deadlock. The SDK automatically detects the deadlock and converts this method into an asynchronous call, causing the test to take additional time. false: (Asynchronous call) The result returns immediately, even when the IRtcEngine resources have not been released. The SDK releases all resources.

Note

Do not immediately uninstall the SDK's dynamic library after the call, or it may cause a crash due to the SDK clean-up thread not quitting.

Sets the channel profile of the Agora RtcEngine.

The Agora RtcEngine differentiates channel profiles and applies optimization algorithms accordingly. For example, it prioritizes smoothness and low latency for a video call, and prioritizes video quality for a video broadcast.

Warning

• To ensure the quality of real-time communication, we recommend that all users in a channel use the same channel profile.
• Call this method before calling joinChannel . You cannot set the channel profile once you have joined the channel.

Parameters

profile

The channel profile of the Agora RtcEngine. See CHANNEL_PROFILE_TYPE

Returns

• 0: Success.
• < 0: Failure.

Sets the role of the user, such as a host or an audience (default), before joining a channel in a live broadcast.

This method can be used to switch the user role in a live broadcast after the user joins a channel.

In the Live Broadcast profile, when a user switches user roles after joining a channel, a successful setClientRole method call triggers the following callbacks:

• The local client: onClientRoleChanged
• The remote client: onUserJoined or onUserOffline (BECOME_AUDIENCE)

Note

This method applies only to the Live-broadcast profile.

Parameters

role	Sets the role of the user. See CLIENT_ROLE_TYPE.

Returns

• 0: Success.
• < 0: Failure.

Joins a channel with the user ID.

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

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

A successful joinChannel method call triggers the following callbacks:

• The local client: onJoinChannelSuccess
• The remote client: onUserJoined , if the user joining the channel is in the Communication profile, or is a BROADCASTER in the Live Broadcast profile.

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

Note

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

Warning

Ensure that the App ID used for creating the token is the same App ID used by the initialize method for initializing the RTC engine. Otherwise, the CDN live streaming may fail.

Parameters

token	Pointer to the token generated by the application server. In most circumstances, a static App ID suffices. For added security, use a Channel Key. If the user uses a static App ID, token is optional and can be set as NULL. If the user uses a Channel Key, Agora issues an additional App Certificate for you to generate a user key based on the algorithm and App Certificate for user authentication on the server.
channelId	Pointer to the unique channel name for the Agora RTC session in the string format smaller than 64 bytes. Supported characters: All lowercase English letters: a to z. All uppercase English letters: A to Z. All numeric characters: 0 to 9. The space character. Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
info	(Optional) Pointer to additional information about the channel. This parameter can be set to NULL or contain channel related information. Other users in the channel will not receive this message.
uid	(Optional) User ID. A 32-bit unsigned integer with a value ranging from 1 to 232-1. The uid must be unique. If a uid is not assigned (or set to 0), the SDK assigns and returns a uid in the onJoinChannelSuccess callback. Your application must record and maintain the returned uid since the SDK does not do so.

Returns

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

Switches to a different channel.

This method allows the audience of a Live-broadcast 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-broadcast channel only.

Parameters

token

The token generated at your server: For low-security requirements: You can use the temporary token generated in Console. For details, see Get a temporary token. For high-security requirements: Use the token generated at your server. For details, see Get a token.

channelId

Unique channel name for the AgoraRTC session in the string format. The string length must be less than 64 bytes. Supported character scopes are: All lowercase English letters: a to z. All uppercase English letters: A to Z. All numeric characters: 0 to 9. The space character. Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".

Returns

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

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

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

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

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

A successful leaveChannel method call triggers the following callbacks:

• The local client: onLeaveChannel
• The remote client: onUserOffline , if the user leaving the channel is in the Communication channel, or is a BROADCASTER in the Live Broadcast profile.

Note

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

Returns

• 0: Success.
• < 0: Failure.

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

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

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

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

Parameters

token

Pointer to the new token.

Returns

• 0: Success.
• < 0: Failure.

Retrieves the pointer to the device manager object.

Parameters

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

Returns

• 0: Success.
• < 0: Failure.

Registers a user account.

Once registered, the user account can be used to identify the local user when the user joins the channel. After the user successfully registers a user account, the SDK triggers the onLocalUserRegistered callback on the local client, reporting the user ID and user account of the local user.

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

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

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

Note

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

Parameters

appId

The App ID of your project.

userAccount

The user account. The maximum length of this parameter is 255 bytes. Ensure that 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.

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 BROADCASTER in the Live Broadcast profile.

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.

Parameters

token	The token generated at your server: For low-security requirements: You can use the temporary token generated at Console. For details, see Get a temporary toke. For high-security requirements: Set it as the token generated at your server. For details, see Get a token.
channelId	The channel name. The maximum length of this parameter is 64 bytes. Supported character scopes are: All lowercase English letters: a to z. All uppercase English letters: A to Z. All numeric characters: 0 to 9. The space character. Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
userAccount	The user account. The maximum length of this parameter is 255 bytes. Ensure that 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.
  • ERR_INVALID_ARGUMENT (-2)
  • ERR_NOT_READY (-3)
  • ERR_REFUSED (-5)

Gets the user information by passing in the user account.

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

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

Parameters

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

Returns

• 0: Success.
• < 0: Failure.

Gets the user information by passing in the user ID.

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

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

Parameters

uid	The user ID of the remote user. Ensure that you set this parameter.
userInfo	A userInfo object that identifies the user: Input: A userInfo object. Output: A userInfo object that contains the user account and user ID of the user.

Returns

• 0: Success.
• < 0: Failure.

DEPRECATED Starts an audio call test.

This method is deprecated as of v2.4.0.

This method starts an audio call test to check whether the audio devices (for example, headset and speaker) and the network connection are working properly.

To conduct the test:

• The user speaks and the recording is played back within 10 seconds.
• If the user can hear the recording within 10 seconds, the audio devices and network connection are working properly.

Note

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

Returns

• 0: Success.
• < 0: Failure.

Starts an audio call test.

This method starts an audio call test to determine whether the audio devices (for example, headset and speaker) and the network connection are working properly.

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

Note

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

Parameters

intervalInSeconds

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

Returns

• 0: Success.
• < 0: Failure.

Stops the audio call test.

Returns

• 0: Success.
• < 0: Failure.

Enables the video module.

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

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

Note

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

Returns

• 0: Success.
• < 0: Failure.

Disables the video module.

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

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

Note

• This method affects the internal engine and can be called after the leaveChannel method.
• This method resets the internal engine and takes some time to take effect. We recommend using the following 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.

DEPRECATED Sets the video profile.

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

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

Note

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

Parameters

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

Note

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

Returns

• 0: Success.
• < 0: Failure.

Sets the video encoder configuration.

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

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

Note

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

Parameters

config

Sets the local video encoder configuration. See VideoEncoderConfiguration.

Returns

• 0: Success.
• < 0: Failure.

Sets the camera capture configuration.

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

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

Note

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

Parameters

config

Sets the camera capturer configuration. See CameraCapturerConfiguration.

Returns

• 0: Success.
• < 0: Failure.

Initializes the local video view.

This method initializes the video view of a local stream on the local device. It affects only the video view that the local user sees, not the published local video stream.

Call this method to bind the local video stream to a video view and to set the rendering and mirror modes of the video view. The binding is still valid after the user leaves the channel, which means that the window still displays. To unbind the view, set the view in VideoCanvas to NULL.

Note

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

Parameters

canvas

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

Returns

• 0: Success.
• < 0: Failure.

Initializes the video view of a remote user.

This method initializes the video view of a remote stream on the local device. It affects only the video view that the local user sees.

Call this method to bind the remote video stream to a video view and to set the rendering and mirror modes of the video view.

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

Note

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

Parameters

canvas

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

Returns

• 0: Success.
• < 0: Failure.

Starts the local video preview before joining the channel.

Before calling this method, you must:

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

Note

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

Returns

• 0: Success.
• < 0: Failure.

Prioritizes a remote user's stream.

Use this method with the setRemoteSubscribeFallbackOption method. If the fallback function is enabled for a subscribed stream, the SDK ensures the high-priority user gets the best possible stream quality.

Note

The Agora SDK supports setting userPriority as high for one user only.

Parameters

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

Returns

• 0: Success.
• < 0: Failure.

Stops the local video preview and disables video.

Returns

• 0: Success.
• < 0: Failure.

Enables the audio module.

The audio mode is enabled by default.

Note

• This method affects the internal engine and can be called after the leaveChannel method. You can call this method either before or after joining a channel.
• This method resets the internal engine and takes some time to take effect. We recommend using the 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/Re-enables the local audio function.

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

This method does not affect receiving or playing 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.

The SDK triggers the onMicrophoneEnabled callback once the local audio function is disabled or enabled.

Note

This method is different from the muteLocalAudioStream method:

• enableLocalAudio: Disables/Re-enables the local audio capturing and processing. If you disable or re-enable local audio recording using the enableLocalAudio method, the local user may hear a pause in the remote audio playback.
• muteLocalAudioStream: Sends/Stops sending the local audio streams.

Parameters

enabled

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

Returns

• 0: Success.
• < 0: Failure.

Disables the audio module.

Note

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

Returns

• 0: Success.
• < 0: Failure.

Sets the audio parameters and application scenarios.

Note

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

Parameters

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

Returns

• 0: Success.
• < 0: Failure.

Stops/Resumes sending the local audio stream.

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

Note

• When mute is set as true, this method does not disable the microphone, which does not affect any ongoing recording.
• If you call setChannelProfile after this method, the SDK resets whether or not to mute the local audio according to the channel profile and user role. Therefore, we recommend calling this method after the setChannelProfile method.

Parameters

mute	Sets whether to send/stop sending the local audio stream: true: Stops sending the local audio stream. false: (Default) Sends the local audio stream.

Returns

• 0: Success.
• < 0: Failure.

Stops/Resumes receiving all remote users' audio streams.

Parameters

mute	Sets whether to receive/stop receiving all remote users' audio streams. true: Stops receiving all remote users' audio streams. false: (Default) Receives all remote users' audio streams.

Returns

• 0: Success.
• < 0: Failure.

Sets whether to receive all remote audio streams by default.

You can call this method either before or after joining a channel. If you call setDefaultMuteAllRemoteAudioStreams (true) after joining a channel, the remote audio streams of all subsequent users are not received.

Note

If you want to resume receiving the audio stream, call muteRemoteAudioStream (false), and specify the ID of the remote user whose audio stream you want to receive. To receive the audio streams of multiple remote users, call muteRemoteAudioStream (false) as many times. Calling setDefaultMuteAllRemoteAudioStreams (false) resumes receiving the audio streams of subsequent users only.

Parameters

mute	Sets whether to receive/stop receiving all remote users' audio streams by default: true: Stops receiving all remote users' audio streams by default. false: (Default) Receives all remote users' audio streams by default.

Returns

• 0: Success.
• < 0: Failure.

Adjusts the playback volume of a specified remote user.

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

Note

• Call this method after joining a channel.
• The playback volume here refers to the mixed volume of a specified remote user.
• This method can only adjust the playback volume of one specified remote user at a time. To adjust the playback volume of different remote users, call the method as many times, once for each remote user.

Parameters

uid	The ID of the remote user.
volume	The playback volume of the specified remote user. The value ranges from 0 to 100: 0: Mute. 100: Original volume.

Returns

• 0: Success.
• < 0: Failure.

Stops/Resumes receiving a specified remote user's audio stream.

Note

If you called the muteAllRemoteAudioStreams method and set mute as true to stop receiving all remote users' audio streams, call the muteAllRemoteAudioStreams method and set mute as false before calling this method. The muteAllRemoteAudioStreams method sets all remote audio streams, while the muteRemoteAudioStream method sets a specified remote audio stream.

Parameters

userId	User ID of the specified remote user sending the audio.
mute	Sets whether to receive/stop receiving a specified remote user's audio stream: true: Stops receiving the specified remote user's audio stream. false: (Default) Receives the specified remote user's audio stream.

Returns

• 0: Success.
• < 0: Failure.

Stops/Resumes sending the local video stream.

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

Note

• When set to true, this method does not disable the camera which does not affect the retrieval of the local video streams. This method executes faster than the enableLocalVideo method which controls the sending of the local video stream.
• If you call setChannelProfile after this method, the SDK resets whether or not to mute the local video according to the channel profile and user role. Therefore, we recommend calling this method after the setChannelProfile method.

Parameters

mute	Sets whether to send/stop sending the local video stream: true: Stop sending the local video stream. false: (Default) Send the local video stream.

Returns

• 0: Success.
• < 0: Failure.

Enables/Disables the local video capture.

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

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

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

Note

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

Parameters

enabled

Sets whether to disable/re-enable the local video, including the capturer, renderer, and sender: true: (Default) Re-enable the local video. false: Disable the local video. Once the local video is disabled, the remote users can no longer receive the video stream of this user, while this user can still receive the video streams of the other remote users.

Returns

• 0: Success.
• < 0: Failure.

Stops/Resumes receiving all video stream from a specified remote user.

Parameters

mute	Sets whether to receive/stop receiving all remote users' video streams: true: Stop receiving all remote users' video streams. false: (Default) Receive all remote users' video streams.

Returns

• 0: Success.
• < 0: Failure.

Sets whether to receive all remote video streams by default.

You can call this method either before or after joining a channel. If you call setDefaultMuteAllRemoteVideoStreams (true) after joining a channel, the remote video streams of all subsequent users are not received.

Note

If you want to resume receiving the video stream, call muteRemoteVideoStream (false), and specify the ID of the remote user whose video stream you want to receive. To receive the video streams of multiple remote users, call muteRemoteVideoStream (false) as many times. Calling setDefaultMuteAllRemoteVideoStreams (false) resumes receiving the video streams of subsequent users only.

Parameters

mute	Sets whether to receive/stop receiving all remote users' video streams by default: true: Stop receiving all remote users' video streams by default. false: (Default) Receive all remote users' video streams by default.

Returns

• 0: Success.
• < 0: Failure.

Stops/Resumes receiving the video stream from a specified remote user.

Note

If you called the muteAllRemoteVideoStreams method and set mute as true to stop receiving all remote video streams, call the muteAllRemoteVideoStreams method and set mute as false before calling this method.

Parameters

userId	User ID of the specified remote user.
mute	Sets whether to stop/resume receiving the video stream from a specified remote user: true: Stop receiving the specified remote user's video stream. false: (Default) Receive the specified remote user's video stream.

Returns

• 0: Success.
• < 0: Failure.

Sets the remote user's video stream type received by the local user when the remote user sends dual streams.

This method allows the application to adjust the corresponding video-stream type based on the size of the video window to reduce the bandwidth and resources.

• If the remote user enables the dual-stream mode by calling the enableDualStreamMode method, the SDK receives the high-stream video by default.
• If the dual-stream mode is not enabled, the SDK receives the high-stream video by default.

The method result returns in the onApiCallExecuted callback. The SDK receives the high-stream video by default to reduce the bandwidth. If needed, users may use this method to switch to the low-stream video. By default, the aspect ratio of the low-stream video is the same as the high-stream video. Once the resolution of the high-stream video is set, the system automatically sets the resolution, frame rate, and bitrate of the low-stream video.

Parameters

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

Returns

• 0: Success.
• < 0: Failure.

Sets the default video-stream type for the video received by the local user when the remote user sends dual streams.

• If the dual-stream mode is enabled by calling the enableDualStreamMode method, the user receives the high-stream video by default. The setRemoteDefaultVideoStreamType method allows the application to adjust the corresponding video-stream type according to the size of the video window, reducing the bandwidth and resources.
• If the dual-stream mode is not enabled, the user receives the high-stream video by default.

The result after calling this method is returned in the onApiCallExecuted callback. The Agora SDK receives the high-stream video by default to reduce the bandwidth. If needed, users can switch to the low-stream video through this method.

Parameters

streamType

Sets the default video-stream type. See REMOTE_VIDEO_STREAM_TYPE.

Returns

• 0: Success.
• < 0: Failure.

Enables the onAudioVolumeIndication callback at a set time interval to report on which users are speaking and the speakers' volume.

Once this method is enabled, the SDK returns the volume indication in the onAudioVolumeIndication callback at the set time interval, whether or not any user is speaking in the channel.

Parameters

interval	Sets the time interval between two consecutive volume indications: ≤ 0: Disables the volume indication. > 0: Time interval (ms) between two consecutive volume indications. We recommend setting interval > 200 ms. Do not set interval < 10 ms, or the onAudioVolumeIndication callback will not be triggered.
smooth	Smoothing factor sets the sensitivity of the audio volume indicator. The value ranges between 0 and 10. The greater the value, the more sensitive the indicator. The recommended value is 3.
report_vad	true: Enable the voice activity detection of the local user. Once it is enabled, the vad parameter of the onAudioVolumeIndication callback reports the voice activity status of the local user. false: (Default) Disable the voice activity detection of the local user. Once it is disabled, the vad parameter of the onAudioVolumeIndication callback does not report the voice activity status of the local user, except for the scenario where the engine automatically detects the voice activity of the local user.

Returns

• 0: Success.
• < 0: Failure.

DEPRECATED Starts an audio recording. Use startAudioRecording2 instead.

The SDK allows recording during a call. Supported formats:

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

This method has a fixed sample rate of 32 kHz.

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

Parameters

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

Returns

• 0: Success.
• < 0: Failure.

Starts an audio recording on the client.

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

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

Note

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

Parameters

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

Returns

• 0: Success.
• < 0: Failure.

Stops an audio recording on the client.

You can call this method before calling the leaveChannel method else, the recording automatically stops when the leaveChannel method is called.

Returns

• 0: Success
• < 0: Failure.

Starts playing and mixing the music file.

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

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

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

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

Note

• Call this method after joining a channel, otherwise issues may occur.
• If the local audio mixing file does not exist, or if the SDK does not support the file format or cannot access the music file URL, the SDK returns WARN_AUDIO_MIXING_OPEN_ERROR = 701.
• If you want to play an online music file, ensure that the time interval between calling this method is more than 100 ms, or the AUDIO_MIXING_ERROR_TOO_FREQUENT_CALL(702) error code occurs.

Parameters

filePath	Pointer to the absolute path (including the suffixes of the filename) of the local or online audio file to mix, for example, c:/music/audio.mp4. Supported audio formats: 3GP, ASF, ADTS, AVI, MP3, MP4, MPEG-4, SAMI, and WAVE. For more information, see Supported Media Formats in Media Foundation.
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.

Stops playing and mixing the music file.

Call this method when you are in a channel.

Returns

• 0: Success.
• < 0: Failure.

Pauses playing and mixing the music file.

Call this method when you are in a channel.

Returns

• 0: Success.
• < 0: Failure.

Resumes playing and mixing the music file.

Call this method when you are in a channel.

Returns

• 0: Success.
• < 0: Failure.

DEPRECATED Agora does not recommend using this method.

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

Do not call this method again after joining a channel.

Parameters

fullband	Sets whether to enable/disable full-band codec (48-kHz sample rate). Not compatible with SDK versions before v1.7.4: true: Enable full-band codec. false: Disable full-band codec.
stereo	Sets whether to enable/disable stereo codec. Not compatible with SDK versions before v1.7.4: true: Enable stereo codec. false: Disable stereo codec.
fullBitrate	Sets whether to enable/disable high-bitrate mode. Recommended in voice-only mode: true: Enable high-bitrate mode. false: Disable high-bitrate mode.

Returns

• 0: Success.
• < 0: Failure.

Adjusts the volume during audio mixing.

Call this method when you are in a channel.

Note

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

Parameters

volume

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

Returns

• 0: Success.
• < 0: Failure.

Adjusts the audio mixing volume for local playback.

Note

Call this method when you are in a channel.

Parameters

volume

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

Returns

• 0: Success.
• < 0: Failure.

Retrieves the audio mixing volume for local playback.

This method helps troubleshoot audio volume related issues.

Note

Call this method when you are in a channel.

Returns

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

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

Note

Call this method when you are in a channel.

Parameters

volume

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

Returns

• 0: Success.
• < 0: Failure.

Retrieves the audio mixing volume for publishing.

This method helps troubleshoot audio volume related issues.

Note

Call this method when you are in a channel.

Returns

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

Gets the duration (ms) of the music file.

Call this method when you are in a channel.

Returns

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

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

Call this method when you are in a channel.

Returns

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

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

Parameters

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

Returns

• 0: Success.
• < 0: Failure.

Retrieves the volume of the audio effects.

The value ranges between 0.0 and 100.0.

Returns

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

Sets the volume of the audio effects.

Parameters

volume

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

Returns

• 0: Success.
• < 0: Failure.

Sets the volume of a specified audio effect.

Parameters

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

Returns

• 0: Success.
• < 0: Failure.

Plays a specified local or online audio effect file.

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

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

Parameters

soundId

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

Note

• If the audio effect is preloaded into the memory through the preloadEffect method, the value of soundID must be the same as that in the preloadEffect method.
• Playing multiple online audio effect files simultaneously is not supported on macOS and Windows.

Parameters

filePath	Specifies the absolute path (including the suffixes of the filename) to the local audio effect file or the URL of the online audio effect file, for example, c:/music/audio.mp4. Supported audio formats: mp3, mp4, m4a, aac, 3gp, mkv and wav.
loopCount	Sets the number of times the audio effect loops: 0: Play the audio effect once. 1: Play the audio effect twice. -1: Play the audio effect in an indefinite loop until the stopEffect or stopAllEffects method is called.
pitch	Sets the pitch of the audio effect. The value ranges between 0.5 and 2. The default value is 1 (no change to the pitch). The lower the value, the lower the pitch.
pan	Sets the spatial position of the audio effect. The value ranges between -1.0 and 1.0: 0.0: The audio effect displays ahead. 1.0: The audio effect displays to the right. -1.0: The audio effect displays to the left.
gain	Sets the volume of the audio effect. The value ranges between 0 and 100 (default). The lower the value, the lower the volume of the audio effect.
publish	Sets whether or not to publish the specified audio effect to the remote stream: true: The locally played audio effect is published to the Agora Cloud and the remote users can hear it. false: The locally played audio effect is not published to the Agora Cloud and the remote users cannot hear it.

Returns

• 0: Success.
• < 0: Failure.

Stops playing a specified audio effect.

Parameters

soundId

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

Returns

• 0: Success.
• < 0: Failure.

Stops playing all audio effects.

Returns

• 0: Success.
• < 0: Failure.

Preloads a specified audio effect file into the memory.

Note

This method does not support online audio effect files.

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

Supported audio formats: mp3, aac, m4a, 3gp, and wav.

Parameters

soundId	ID of the audio effect. Each audio effect has a unique ID.
filePath	Pointer to the absolute path of the audio effect file.

Returns

• 0: Success.
• < 0: Failure.

Releases a specified preloaded audio effect from the memory.

Parameters

soundId

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

Returns

• 0: Success.
• < 0: Failure.

Pauses a specified audio effect.

Parameters

soundId

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

Returns

• 0: Success.
• < 0: Failure.

Pauses all audio effects.

Returns

• 0: Success.
• < 0: Failure.

Resumes playing a specified audio effect.

Parameters

soundId

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

Returns

• 0: Success.
• < 0: Failure.

Resumes playing all audio effects.

Returns

• 0: Success.
• < 0: Failure.

Enables/Disables stereo panning for remote users.

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

Parameters

enabled

Sets whether or not to enable stereo panning for remote users: true: enables stereo panning. false: disables stereo panning.

Returns

• 0: Success.
• < 0: Failure.

Sets the sound position and gain of a remote user.

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

Note

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

Parameters

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

Returns

• 0: Success.
• < 0: Failure.

Changes the voice pitch of the local speaker.

Parameters

pitch

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

Returns

• 0: Success.
• < 0: Failure.

Sets the local voice equalization effect.

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, 500, 1k, 2k, 4k, 8k, and 16k Hz. See AUDIO_EQUALIZATION_BAND_FREQUENCY.
bandGain	Sets the gain of each band in dB. The value ranges between -15 and 15.

Returns

• 0: Success.
• < 0: Failure.

Sets the local voice reverberation.

v2.4.0 adds the setLocalVoiceReverbPreset method, a more user-friendly method for setting the local voice reverberation. You can use this method to set the local reverberation effect, such as pop music, R&B, rock music, and hip-hop.

Parameters

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

Returns

• 0: Success.
• < 0: Failure.

Sets the local voice changer option.

Note

Do not use this method together with the setLocalVoiceReverbPreset method, because the method called later overrides the one called earlier.

Parameters

voiceChanger

Sets the local voice changer option. See VOICE_CHANGER_PRESET.

Returns

• 0: Success.
• < 0: Failure.

Sets the preset local voice reverberation effect.

Note

• Do not use this method together with setLocalVoiceReverb.
• Do not use this method together with the setLocalVoiceChanger method, because the method called later overrides the one called earlier.

Parameters

reverbPreset

Sets the preset audio reverberation configuration. See AUDIO_REVERB_PRESET.

Returns

• 0: Success.
• < 0: Failure.

Specifies an SDK output log file.

The log file records all SDK operations during runtime. If it does not exist, the SDK creates one.

Note

• The default log file is located at: C:\Users\<user_name>\AppData\Local\Agora\<process_name>.
• Ensure that you call this method immediately after calling the initialize method, otherwise the output log may not be complete.

Parameters

filePath

File path of the log file. The string of the log file is in UTF-8.

Returns

• 0: Success.
• < 0: Failure.

Sets the output log level of the SDK.

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

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

Parameters

filter

Sets the log filter level. See LOG_FILTER_TYPE.

Returns

• 0: Success.
• < 0: Failure.

Sets the log file size (KB).

The SDK has two log files, each with a default size of 512 KB. If you set fileSizeInBytes as 1024 KB, the SDK outputs log files with a total maximum size of 2 MB. If the total size of the log files exceed the set value, the new output log files overwrite the old output log files.

Parameters

fileSizeInKBytes

The SDK log file size (KB).

Returns

• 0: Success.
• < 0: Failure.

Deprecated:

This method is deprecated, use the setLocalRenderMode2 method instead. Sets the local video display mode.

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

Parameters

renderMode

Sets the local video display mode. See RENDER_MODE_TYPE.

Returns

• 0: Success.
• < 0: Failure.

Since

v3.0.0

Updates the display mode of the local video view.

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 the display mode of the local video view.

Parameters

renderMode	The rendering mode of the local video view. See RENDER_MODE_TYPE.
mirrorMode	The mirror mode of the local video view. See VIDEO_MIRROR_MODE_TYPE. Note: If you use a front camera, the SDK enables the mirror mode by default; if you use a rear camera, the SDK disables the mirror mode by default.

Returns

• 0: Success.
• < 0: Failure.

Deprecated:

This method is deprecated, use the setRemoteRenderMode2 method instead. Sets the video display mode of a specified remote user.

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

Parameters

userId	ID of the remote user.
renderMode	Sets the video display mode. See RENDER_MODE_TYPE.

Returns

• 0: Success.
• < 0: Failure.

Since

v3.0.0

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

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

userId	The ID of the remote user.
renderMode	The rendering mode of the remote video view. See RENDER_MODE_TYPE.
mirrorMode	The mirror mode of the remote video view. See VIDEO_MIRROR_MODE_TYPE. Note: The SDK disables the mirror mode by default.

Returns

• 0: Success.
• < 0: Failure.

Deprecated:

This method is deprecated, use the setupLocalVideo or setLocalRenderMode method instead.

Sets the local video mirror mode.

You must call this method before calling the startPreview method, otherwise the mirror mode will not work.

Warning

• Call this method after calling the setupLocalVideo method to initialize the local video view.
• During a call, you can call this method as many times as necessary to update the mirror mode of the local video view.

Parameters

mirrorMode

Sets the local video mirror mode. See VIDEO_MIRROR_MODE_TYPE.

Returns

• 0: Success.
• < 0: Failure.

Sets the stream mode to the single-stream (default) or dual-stream mode. (Live broadcast only.)

If the dual-stream mode is enabled, the receiver can choose to receive the high stream (high-resolution and high-bitrate video stream), or the low stream (low-resolution and low-bitrate video stream).

Parameters

enabled

Sets the stream mode: true: Dual-stream mode. false: (Default) Single-stream mode.

Sets the external audio source. Please call this method before joinChannel.

Parameters

enabled	Sets whether to enable/disable the external audio source: true: Enables the external audio source. false: (Default) Disables the external audio source.
sampleRate	Sets the sample rate (Hz) of the external audio source, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
channels	Sets the number of audio channels of the external audio source: 1: Mono. 2: Stereo.

Returns

• 0: Success.
• < 0: Failure.

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

Note

Once you enable the external audio sink, the app will not retrieve any audio data from the onPlaybackAudioFrame callback.

Parameters

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

Returns

• 0: Success.
• < 0: Failure.

Sets the audio recording format for the onRecordAudioFrame callback.

Parameters

sampleRate	Sets the sample rate (samplesPerSec) returned in the onRecordAudioFrame callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
channel	Sets the number of audio channels (channels) returned in the onRecordAudioFrame callback: 1: Mono 2: Stereo
mode	Sets the use mode (see RAW_AUDIO_FRAME_OP_MODE_TYPE) of the onRecordAudioFrame callback.
samplesPerCall	Sets the number of samples returned in the onRecordAudioFrame callback. samplesPerCall is usually set as 1024 for RTMP streaming.

Note

The SDK triggers the onRecordAudioFrame callback according to the sample interval. Ensure that the sample interval ≥ 0.01 (s). And, Sample interval (sec) = samplePerCall/(sampleRate × channel).

Returns

• 0: Success.
• < 0: Failure.

Sets the audio playback format for the onPlaybackAudioFrame callback.

Parameters

sampleRate	Sets the sample rate (samplesPerSec) returned in the onPlaybackAudioFrame callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
channel	Sets the number of channels (channels) returned in the onPlaybackAudioFrame callback: 1: Mono 2: Stereo
mode	Sets the use mode (see RAW_AUDIO_FRAME_OP_MODE_TYPE) of the onPlaybackAudioFrame callback.
samplesPerCall	Sets the number of samples returned in the onPlaybackAudioFrame callback. samplesPerCall is usually set as 1024 for RTMP streaming.

Note

The SDK triggers the onPlaybackAudioFrame callback according to the sample interval. Ensure that the sample interval ≥ 0.01 (s). And, Sample interval (sec) = samplePerCall/(sampleRate × channel).

Returns

• 0: Success.
• < 0: Failure.

Sets the mixed audio format for the onMixedAudioFrame callback.

Parameters

sampleRate	Sets the sample rate (samplesPerSec) returned in the onMixedAudioFrame callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
samplesPerCall	Sets the number of samples (samples) returned in the onMixedAudioFrame callback. samplesPerCall is usually set as 1024 for RTMP streaming.

Note

The SDK triggers the onMixedAudioFrame callback according to the sample interval. Ensure that the sample interval ≥ 0.01 (s). And, Sample interval (sec) = samplePerCall/(sampleRate × channels).

Returns

• 0: Success.
• < 0: Failure.

Adjusts the recording volume.

Parameters

volume

Recording volume. The value ranges between 0 and 400: 0: Mute. 100: Original volume. 400: (Maximum) Four times the original volume with signal clipping protection.

Returns

• 0: Success.
• < 0: Failure.

Adjusts the playback volume of all remote users.

Note

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

Parameters

volume

The playback volume of all remote users. The value ranges from 0 to 400: 0: Mute. 100: Original volume. 400: (Maximum) Four times the original volume with signal clipping protection.

Returns

• 0: Success.
• < 0: Failure.

Deprecated:

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

Note

• This method applies only to the Live-broadcast profile. In the Communication profile, interoperability with the Agora Web SDK is enabled by default.
• 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.

Parameters

enabled

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

Returns

• 0: Success.
• < 0: Failure.

DEPRECATED Sets the preferences for the high-quality video. (Live broadcast only).

This method is deprecated as of v2.4.0.

Parameters

preferFrameRateOverImageQuality

Sets the video quality preference: true: Frame rate over image quality. false: (Default) Image quality over frame rate.

Returns

• 0: Success.
• < 0: Failure.

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

If option is set as STREAM_FALLBACK_OPTION_AUDIO_ONLY (2), the SDK will:

• Disable the upstream video but enable audio only when the network conditions deteriorate and cannot support both video and audio.
• Re-enable the video when the network conditions improve.

When the locally published video stream falls back to audio only or when the audio-only stream switches back to the video, the SDK triggers the onLocalPublishFallbackToAudioOnly callback.

Note

Agora does not recommend using this method for CDN live streaming, because the remote CDN live user will have a noticeable lag when the locally published video stream falls back to audio only.

Parameters

option

Sets the fallback option for the locally published video stream: STREAM_FALLBACK_OPTION_DISABLED (0): (Default) No fallback behavior for the locally published video stream when the uplink network condition is poor. The stream quality is not guaranteed. STREAM_FALLBACK_OPTION_AUDIO_ONLY (2): The locally published video stream falls back to audio only when the uplink network condition is poor.

Returns

• 0: Success.
• < 0: Failure.

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

The default setting for option is STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW (1), where the remotely subscribed video stream falls back to the low-stream video (low resolution and low bitrate) under poor downlink network conditions.

If option is set as STREAM_FALLBACK_OPTION_AUDIO_ONLY (2), the SDK automatically switches the video from a high-stream to a low-stream, or disables the video when the downlink network conditions cannot support both audio and video to guarantee the quality of the audio. The SDK monitors the network quality and restores the video stream when the network conditions improve.

When the remotely subscribed video stream falls back to audio only or when the audio-only stream switches back to the video stream, the SDK triggers the onRemoteSubscribeFallbackToAudioOnly callback.

Parameters

option

Sets the fallback option for the remotely subscribed video stream. See STREAM_FALLBACK_OPTIONS.

Returns

• 0: Success.
• < 0: Failure.

Switches between front and rear cameras.

Note

This method is for Android and iOS only.

Returns

• 0: Success.
• < 0: Failure.

Sets the default audio playback route.

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

The default setting for each profile:

• Communication: In a voice call, the default audio route is the earpiece. In a video call, the default audio route is the speakerphone. If a user who is in the Communication profile calls the disableVideo method or if the user calls the muteLocalVideoStream and muteAllRemoteVideoStreams methods, the default audio route switches back to the earpiece automatically.
• Live Broadcast: Speakerphone.

Note

• This method is for Android and iOS only.
• This method is applicable only to the Communication profile.
• For iOS, this method only works in a voice call.
• Call this method before calling the joinChannel method.

Parameters

defaultToSpeaker

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

Returns

• 0: Success.
• < 0: Failure.

Enables/Disables the audio playback route to the speakerphone.

This method sets whether the audio is routed to the speakerphone or earpiece.

See the default audio route explanation in the setDefaultAudioRouteToSpeakerphone method and check whether it is necessary to call this method.

Note

• This method is for Android and iOS only.
• Ensure that you have successfully called the joinChannel method before calling this method.
• After calling this method, the SDK returns the onAudioRouteChanged callback to indicate the changes.
• This method does not take effect if a headset is used.

Parameters

speakerOn

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

Returns

• 0: Success.
• < 0: Failure.

Enables in-ear monitoring (for Android and iOS only).

Parameters

enabled

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

Returns

• 0: Success.
• < 0: Failure.

Sets the volume of the in-ear monitor.

Parameters

volume

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

Note

This method is for Android and iOS only.

Returns

• 0: Success.
• < 0: Failure.

Checks whether the speakerphone is enabled.

Note

This method is for Android and iOS only.

Returns

• 0: Success.
• < 0: Failure.

Sets the audio session’s operational restriction.

The SDK and the app can both configure the audio session by default. The app may occasionally use other apps or third-party components to manipulate the audio session and restrict the SDK from doing so. This method allows the app to restrict the SDK’s manipulation of the audio session.

You can call this method at any time to return the control of the audio sessions to the SDK.

Note

• This method is for iOS only.
• This method restricts the SDK’s manipulation of the audio session. Any operation to the audio session relies solely on the app, other apps, or third-party components.

Parameters

restriction

The operational restriction (bit mask) of the SDK on the audio session. See AUDIO_SESSION_OPERATION_RESTRICTION.

Returns

• 0: Success.
• < 0: Failure.

Enables loopback recording.

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

Parameters

enabled	Sets whether to enable/disable loopback recording. true: Enable loopback recording. false: (Default) Disable loopback recording.
deviceName	Pointer to the device name of the sound card. The default value is NULL (the default sound card).

Note

• This method is for macOS and Windows only.
• macOS does not support loopback recording of the default sound card. If you need to use this method, please use a virtual sound card and pass its name to the deviceName parameter. Agora has tested and recommends using soundflower.

Shares the whole or part of a screen by specifying the display ID.

Note

This method is for macOS only.

Parameters

displayId	The display ID of the screen to be shared. This parameter specifies which screen you want to share.
regionRect	(Optional) Sets the relative location of the region to the screen. NIL means sharing the whole screen. See Rectangle. If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen.
captureParams	Sets the screen sharing encoding parameters. See ScreenCaptureParameters.

Returns

• 0: Success.
• < 0: Failure. ERR_INVALID_ARGUMENT: the argument is invalid.

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

Parameters

screenRect	Sets the relative location of the screen to the virtual screen. For information on how to get screenRect, see the Advanced Guide Share the Screen.
regionRect	(Optional) Sets the relative location of the region to the screen. NULL means sharing the whole screen. See Rectangle. If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen.
captureParams	Sets the screen sharing encoding parameters. See ScreenCaptureParameters.

Returns

• 0: Success.
• < 0: Failure. ERR_INVALID_ARGUMENT: the argument is invalid.

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

Since v3.0.0, this method supports sharing with common Windows platforms. Agora tests the mainstream Windows applications, see details as follows:

Parameters

windowId	The ID of the window to be shared. For information on how to get the windowId, see the Advanced Guide Share the Screen.
regionRect	(Optional) The relative location of the region to the window. NULL/NIL means sharing the whole window. See Rectangle. If the specified region overruns the window, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole window.
captureParams	Window sharing encoding parameters. See ScreenCaptureParameters.

Returns

• 0: Success.
• < 0: Failure. ERR_INVALID_ARGUMENT: the argument is invalid.

Sets the content hint for screen sharing.

A content hint suggests the type of the content being shared, so that the SDK applies different optimization algorithm to different types of content.

Parameters

contentHint

Sets the content hint for screen sharing. See VideoContentHint.

Returns

• 0: Success.
• < 0: Failure.

Updates the screen sharing parameters.

Parameters

captureParams

Sets the screen sharing encoding parameters. See ScreenCaptureParameters.

Returns

• 0: Success.
• < 0: Failure:
  • ERR_NOT_READY: no screen or windows is being shared.

Updates the screen sharing region.

Parameters

regionRect

Sets the relative location of the region to the screen or window. NULL means sharing the whole screen or window. See Rectangle. If the specified region overruns the screen or window, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen or window.

Returns

• 0: Success.
• < 0: Failure:
  • ERR_NOT_READY: no screen or window is being shared.

Stop screen sharing.

Returns

• 0: Success.
• < 0: Failure.

DEPRECATED Starts screen sharing.

This method is deprecated as of v2.4.0. See the following methods instead:

• startScreenCaptureByDisplayId
• startScreenCaptureByScreenRect
• startScreenCaptureByWindowId

This method shares the whole screen, specified window, or specified region:

• Whole screen: Set windowId as 0 and rect as NULL.
• Specified window: Set windowId as a value other than 0. Each window has a windowId that is not 0.
• Specified region: Set windowId as 0 and rect not as NULL. In this case, you can share the specified region, for example by dragging the mouse or implementing your own logic.

Note

The specified region is a region on the whole screen. Currently, sharing a specified region in a specific window is not supported. captureFreq* is the captured frame rate once the screen-sharing function is enabled. The mandatory value ranges between 1 fps and 15 fps.

Parameters

windowId	Sets the screen sharing area. See WindowIDType.
captureFreq	(Mandatory) The captured frame rate. The value ranges between 1 fps and 15 fps.
rect	Specifies the screen-sharing region. rect is valid when windowsId is set as 0. When rect is set as NULL, the whole screen is shared.
bitrate	The captured bitrate.

Returns

• 0: Success.
• < 0: Failure.

DEPRECATED Updates the screen capture region.

Parameters

rect	Specifies the required region inside the screen or window.

Returns

• 0: Success.
• < 0: Failure.

Retrieves the current call ID.

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

The rate and complain methods require the callId parameter retrieved from the getCallId method during a call. callId is passed as an argument into the rate and complain methods after the call ends.

Parameters

callId

Pointer to the current call ID.

Returns

• 0: Success.
• < 0: Failure.

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

Parameters

callId	Pointer to the ID of the call, retrieved from the getCallId method.
rating	Rating of the call. The value is between 1 (lowest score) and 5 (highest score). If you set a value out of this range, the ERR_INVALID_ARGUMENT (2) error returns.
description	(Optional) Pointer to the description of the rating, with a string length of less than 800 bytes.

Returns

• 0: Success.
• < 0: Failure.

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

Parameters

callId	Pointer to the ID of the call, retrieved from the getCallId method.
description	(Optional) Pointer to the description of the complaint, with a string length of less than 800 bytes.

Returns

• 0: Success.
• < 0: Failure.

Retrieves the SDK version number.

Parameters

build

Pointer to the build number.

Returns

The version of the current SDK in the string format. For example, 2.3.1.

Enables the network connection quality test.

This method tests the quality of the users' network connections and is disabled by default.

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

This method consumes additional network traffic, and hence may affect communication quality.

Call the disableLastmileTest method to disable this test after receiving the onLastmileQuality callback, and before joining a channel.

Note

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

Returns

• 0: Success.
• < 0: Failure.

Disables the network connection quality test.

Returns

• 0: Success.
• < 0: Failure.

Starts the last-mile network probe test.

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

Call this method to check the uplink network quality before users join a channel or before an audience switches to a host. Once this method is enabled, the SDK returns the following callbacks:

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

Note

• This method consumes extra network traffic and may affect communication quality. We do not recommend calling this method together with enableLastmileTest.
• Do not call other methods before receiving the onLastmileQuality and onLastmileProbeResult callbacks. Otherwise, the callbacks may be interrupted.
• In the Live-broadcast profile, a host should not call this method after joining a channel.

Parameters

config

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

Returns

• 0: Success.
• < 0: Failure.

Stops the last-mile network probe test.

Retrieves the warning or error description.

Parameters

code	Warning code or error code returned in the onWarning or onError callback.

Returns

WARN_CODE_TYPE or ERROR_CODE_TYPE.

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

All users in a channel must use the same encryption password. The encryption password is automatically cleared once a user leaves the channel.

If an encryption password is not specified, the encryption functionality will be disabled.

Note

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

Parameters

secret

Pointer to the encryption password.

Returns

• 0: Success.
• < 0: Failure.

Sets the built-in encryption mode.

The Agora SDK supports built-in encryption, which is set to the aes-128-xts mode by default. Call this method to use other encryption modes.

All users in the same channel must use the same encryption mode and password.

Refer to the information related to the AES encryption algorithm on the differences between the encryption modes.

Note

Call the setEncryptionSecret method to enable the built-in encryption function before calling this method.

Parameters

encryptionMode

Pointer to the set encryption mode: "aes-128-xts": (Default) 128-bit AES encryption, XTS mode. "aes-128-ecb": 128-bit AES encryption, ECB mode. "aes-256-xts": 256-bit AES encryption, XTS mode. "": When encryptionMode is set as NULL, the encryption mode is set as "aes-128-xts" by default.

Returns

• 0: Success.
• < 0: Failure.

Registers a packet observer.

The Agora SDK allows your application to register a packet observer to receive callbacks for voice or video packet transmission.

Note

• The size of the packet sent to the network after processing should not exceed 1200 bytes, otherwise, the packet may fail to be sent.
• Ensure that both receivers and senders call this method, otherwise, you may meet undefined behaviors such as no voice and black screen.
• When you use CDN live streaming, recording or storage functions, Agora doesn't recommend calling this method.

Parameters

observer

Pointer to the registered packet observer. See IPacketObserver.

Returns

• 0: Success.
• < 0: Failure.