AgoraRtcEngineKit

After calling this method, you can push media streams in RTMP or RTMPS protocol to the CDN. The SDK triggers the rtmpStreamingChangedToState callback on the local client to report the state of adding a local stream to the CDN.

Parameters

url

The media push URL in the RTMP or RTMPS format. The maximum length of this parameter is 1024 bytes. The URL address must not contain special characters, such as Chinese language characters.

transcodingEnabled

Whether to enable transcoding. Transcoding in a CDN live streaming converts the audio and video streams before pushing them to the CDN server. It applies to scenarios where a channel has multiple broadcasters and composite layout is needed.

• YES: Enable transcoding.
• NO: Disable transcoding.

Attention: If you set this parameter as YES, ensure that you call the setLiveTranscoding method before calling this method.

Returns

• 0: Success.
• < 0: Failure.
  • -2: Invalid parameter, usually an empty URL or a string with a length of 0.
  • -7: The engine is not initialized when streaming.

Deprecated:

This method is deprecated. Use addVideoWatermark [2/2] instead.

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

Parameters

watermark

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

Returns

• 0: Success.
• < 0: Failure.

This method adds a PNG watermark image to the local video in the live streaming. Once the watermark image is added, all the audience in the channel (CDN audience included), and the capturing device can see and capture it. Agora supports adding only one watermark image onto the local video, and the newly watermark image replaces the previous one.

Parameters

url

The local file path of the watermark image to be added. This method supports adding a watermark image from the local absolute or relative file path.

options

The options of the watermark image to be added. For details, see WatermarkOptions.

Returns

• 0: Success.
• < 0: Failure.

Since

v2.3.2

Parameters

volume

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

Returns

• 0: Success.
• < 0: Failure.

Since

v2.3.2

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

Parameters

volume

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

Returns

• 0: Success.
• < 0: Failure.

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

Parameters

volume

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

Returns

• 0: Success.
• < 0: Failure.

Since

v2.3.2

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

Parameters

volume

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

Returns

• 0: Success.
• < 0: Failure.

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

Parameters

volume

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

Returns

• 0: Success.
• < 0: Failure.

Parameters

volume

Integer only. The value range is [0,400].

• 0: Mute.
• 100: (Default) The original volume.
• 400: Four times the original volume (amplifying the audio signals by four times).

Returns

• 0: Success.
• < 0: Failure.

Parameters

volume

Integer only. The value range is [0,400].

• 0: Mute.
• 100: (Default) The original volume.
• 400: Four times the original volume (amplifying the audio signals by four times).

Returns

• 0: Success.
• < 0: Failure.

You can call this method to adjust the playback volume of a specified remote user. To adjust the playback volume of different remote users, call the method as many times, once for each remote user.

Parameters

uid

The ID of the remote user.

volume

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

Returns

• 0: Success.
• < 0: Failure.

Returns

• 0: Success.
• < 0: Failure.

This method allows users to complain about the quality of the call. Call this method after the user leaves the channel.

Parameters

callId

The current call ID. You can get the call ID by calling getCallId.

description

(Optional) A description of the call. The string length should be less than 800 bytes.

Returns

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

All called methods provided by the AgoraRtcEngineKit class are executed asynchronously. We recommend calling these methods in the same thread.

Parameters

appId

The App ID issued by Agora for your project. Only users in apps with the same App ID can join the same channel and communicate with each other. An App ID can only be used to create one AgoraRtcEngineKit instance. To change your App ID, call destroy to destroy the current AgoraRtcEngineKit instance, and then create a new one.

delegate

The event handler for AgoraRtcEngineKit. See AgoraRtcEngineDelegate.

Returns

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

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

Parameters

config

Configurations for the AgoraRtcEngineKit instance. See AgoraRtcEngineConfig.

delegate

The event handler for AgoraRtcEngineKit. See AgoraRtcEngineDelegate.

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

Parameters

reliable

Whether or not the data stream is reliable:

• YES: The recipients receive the data from the sender within five seconds. If the recipient does not receive the data within five seconds, the SDK triggers the didOccurStreamMessageErrorFromUid callback and returns an error code.
• NO: There is no guarantee that the recipients receive the data stream within five seconds and no error message is reported for any delay or missing data stream.

ordered

Whether or not the recipients receive the data stream in the sent order:

• YES: The recipients receive the data in the sent order.
• NO: The recipients do not receive the data in the sent order.

Returns

• ID of the created data stream, if the method call succeeds.
• < 0: Failure.

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

Compared with createDataStream [1/2][1/2], this method does not support data reliability. If a data packet is not received five seconds after it was sent, the SDK directly discards the data.

Parameters

config

The configurations for the data stream. For details, see AgoraDataStreamConfig.

Returns

• ID of the created data stream, if the method call succeeds.
• < 0: Failure.

Parameters

delegate

The event handler for AgoraRtcEngineKit. See AgoraRtcEngineDelegate.

Returns

• The AgoraRtcMediaPlayerProtocol instance, if the method call succeeds.
• An empty pointer , if the method call fails.

The SDK uses AgoraRtcEngineDelegate to inform the app on engine runtime events. All methods defined in the delegate are optional implementation methods.

This method releases all resources used by the Agora SDK. Use this method for apps in which users occasionally make voice or video calls. When users do not make calls, you can free up resources for other operations.

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

Returns

• 0: Success.
• < 0: Failure.

After calling enableAudioSpectrumMonitor, if you want to disable audio spectrum monitoring, you can call this method.

Returns

• 0: Success.
• < 0: Failure.

This method disables video. You can call this method either before or after joining a channel. If you call it before joining a channel, an audio call starts when you join the channel. If you call it after joining a channel, a video call switches to an audio call. Call enableVideo to enable video.

A successful call of this method triggers the didVideoEnabled(NO) callback on the remote client.

Returns

• 0: Success.
• < 0: Failure.

The audio mode is enabled by default.

Returns

• 0: Success.
• < 0: Failure.

If you want to obtain the audio spectrum data of local or remote users, please register the audio spectrum observer and enable audio spectrum monitoring.

Parameters

intervalInMS

The interval (in milliseconds) at which the SDK triggers the onLocalAudioSpectrum and onRemoteAudioSpectrum callbacks. The default value is 100. Do not set this parameter to less than 10 milliseconds, otherwise the callback will not be triggered.

Returns

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

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 reportAudioVolumeIndicationOfSpeakers callback at the time interval set in this method.

Parameters

interval

Sets the time interval between two consecutive volume indications:

• ≤ 0: Disables the volume indication.
• > 0: Time interval (ms) between two consecutive volume indications. We recommend a setting greater than 200 ms. Do not set this parameter to less than 10 milliseconds, otherwise the reportAudioVolumeIndicationOfSpeakers callback will not be triggered.

smooth

The smoothing factor sets the sensitivity of the audio volume indicator. The value ranges between 0 and 10. The recommended value is 3. The greater the value, the more sensitive the indicator.

reportVad

• YES: Enable the voice activity detection of the local user. Once it is enabled, the vad parameter of the reportAudioVolumeIndicationOfSpeakers callback reports the voice activity status of the local user.
• NO: (Default) Disable the voice activity detection of the local user. Once it is disabled, the vad parameter of the reportAudioVolumeIndicationOfSpeakers 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.

After you enable the dual-stream mode, you can call setRemoteVideoStream to choose to receive the high-quality video stream or low-quality video stream on the subscriber side.

Parameters

enabled

Whether to enable dual-stream mode.

• YES: Enable dual-stream mode.
• NO: Disable dual-stream mode.

Returns

• 0: Success.
• < 0: Failure.

After you enable the dual-stream mode, you can call setRemoteVideoStream to choose to receive the high-quality video stream or low-quality video stream on the subscriber side.

Parameters

sourceType

The capture type of the custom video source. For details, see AgoraVideoSourceType.

enabled

Enables dual-stream mode.

• YES: Enables dual-stream mode.
• NO: Disables dual-stream mode.

Returns

• 0: Success.
• < 0: Failure.

After you enable the dual-stream mode, you can call setRemoteVideoStream to choose to receive the high-quality video stream or low-quality video stream on the subscriber side.

Parameters

sourceType

The capture type of the custom video source. For details, see AgoraVideoSourceType.

enabled

Enables dual-stream mode.

• YES: Enables dual-stream mode.
• NO: Disables dual-stream mode.

streamConfig

The configuration of the low-quality video stream. See AgoraSimulcastStreamConfig.

Returns

• 0: Success.
• < 0: Failure.

In scenarios requiring high security, Agora recommends calling this method to enable the built-in encryption before joining a channel.

All users in the same channel must use the same encryption mode and encryption key. After the user leaves the channel, the SDK automatically disables the built-in encryption. To enable the built-in encryption, call this method before the user joins the channel again.

Parameters

enabled

Whether to enable built-in encryption:

• YES: Enable the built-in encryption.
• NO: Disable the built-in encryption.

config

Built-in encryption configurations. See AgoraEncryptionConfig for details.

Returns

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

Ensure that you call this method before joining a channel.

Parameters

provider

The name of the extension provider.

extension

The name of the extension.

enabled

Whether to enable the extension:

• YES: Enable the extension.
• NO: Disable the extension.

Returns

• 0: Success.
• < 0: Failure.

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

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

Parameters

enabled

• YES: (Default) Re-enable the local audio function, that is, to start the local audio capturing device (for example, the microphone).
• NO: Disable the local audio function, that is, to stop local audio capturing.

Returns

• 0: Success.
• < 0: Failure.

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

After calling enableVideo, the local video capturer is enabled by default. You can call enableLocalVideo(NO) to disable the local video capturer. If you want to re-enable the local video, call enableLocalVideo(YES).

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

Parameters

enabled

Whether to enable the local video capture.

• YES: (Default) Enable the local video capture.
• NO: Disables the local video capture. Once the local video is disabled, the remote users can no longer receive the video stream of this user, while this user can still receive the video streams of the other remote users. When set to NO, this method does not require a local camera.

Returns

• 0: Success.
• < 0: Failure.

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

Parameters

enabled

Sets whether to enable loopback capturing.

• YES: Enable loopback audio capturing.
• NO: (Default) Disable loopback capturing.

deviceName

The device name of the sound card. The default value is nil (the default sound card). If you use a virtual sound card like "Soundflower", set this parameter as the name of the sound card, "Soundflower". The SDK will find the corresponding sound card and start capturing.

Returns

• 0: Success.
• < 0: Failure.

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

Parameters

enabled

Whether to enable stereo panning for remote users:

• YES: Enable stereo panning.
• NO: Disable stereo panning.

Returns

• 0: Success.
• < 0: Failure.

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

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

Returns

• 0: Success.
• < 0: Failure.

The virtual background function allows you to replace the original background image of the local user or to blur the background. After successfully enabling the virtual background function, all users in the channel can see the customized background.

Parameters

enable

Whether to enable virtual background:

• YES: Enable virtual background.
• NO: Disable virtual background.

backData

The custom background image. See AgoraVirtualBackgroundSource for details. To adapt the resolution of the custom background image to that of the video captured by the SDK, the SDK scales and crops the custom background image while ensuring that the content of the custom background image is not distorted.

Returns

• 0: Success.
• < 0: Failure.
  • -1: The custom background image does not exist. Please check the value of source in AgoraVirtualBackgroundSource.
  • -2: The color format of the custom background image is invalid. Please check the value of color in AgoraVirtualBackgroundSource.
  • -3: The device does not support using the virtual background.

Deprecated:

The SDK automatically enables interoperability with the Web SDK, so you no longer need to call this method.

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

This method is only applicable in live streaming scenarios, and interoperability is enabled by default in communication scenarios.

Parameters

enabled

Whether to enable interoperability with the Agora Web SDK.

• YES: Enable interoperability.
• NO: (Default) Disable interoperability.

Returns

• 0: Success.
• < 0: Failure.

This method returns an NSArray object that includes all audio and video devices in the system. Apps can enumerate devices with the AgoraRtcDeviceInfo NSArray object.

Parameters

type

The device type, which includes the audio capturing, audio playback, video capturing, or video playback device. See AgoraMediaDeviceType.

Returns

An AgoraRtcDeviceInfo NSArray object that includes all audio and video devices if the method succeeds.

Retrieves the playback position (ms) of the audio.

Returns

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

Retrieves the total duration (ms) of the audio.

Returns

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

This method helps troubleshoot audio volume‑related issues.

Returns

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

Since

v2.4.1

This method helps troubleshoot audio volume‑related issues.

Returns

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

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

Returns

The current call ID.

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

Returns

The current connection state. For details, see AgoraConnectionState.

This method retrieves the current audio and video capturing device based on your settings in the type parameter.

Parameters

type

The device type, which includes the audio capturing, audio playback, video capturing, or video playback device. See AgoraMediaDeviceType.

Returns

• Returns AgoraRtcDeviceInfo when the method succeeds.
• Returns nil when the method fails.

Parameters

type

The device type, which includes the audio capturing, audio playback, video capturing, or video playback device. See AgoraMediaDeviceType.

Returns

• Returns the volume of the current device, if the method succeeds.
• < 0: Failure.

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

Returns

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

Parameters

error

The error code or warning code reported by the SDK.

Returns

The specific error or warning description.

This method is used to retrieve the native C++ handle of the SDK engine used in special scenarios, such as registering the audio and video frame observer.

Returns

The native handle of the SDK.

Returns

The SDK version number. The format is a string.

After a remote user joins the channel, the SDK gets the UID and user account of the remote user, caches them in a mapping table object, and triggers the didUserInfoUpdatedWithUserId callback on the local client. After receiving the callback, you can call this method to get the user account of the remote user from the AgoraUserInfo object by passing in the user ID.

Parameters

uid

User ID.

error

Error code.

Returns

After a remote user joins the channel, the SDK gets the UID and user account of the remote user, caches them in a mapping table object, and triggers the didUserInfoUpdatedWithUserId callback on the local client. After receiving the callback, you can call this method to get the user account of the remote user from the AgoraUserInfo object by passing in the user ID.

Parameters

userAccount

The user account.

error

Error code.

Returns

Parameters

soundId

The ID of the audio effect.

Returns

• ≥ 0: Returns the volume of the specified audio effect, if the method call is successful. The value ranges between 0 and 100. 100 represents the original volume.
• < 0: Failure.

This method enables users 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.

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

Parameters

token

The token generated on your server for authentication. See Authenticate Your Users with Token.

channelId

The channel name. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported character scopes are:

• All lowercase English letters: a to z.
• All uppercase English letters: A to Z.
• All numeric characters: 0 to 9.
• Space
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "= ", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

info

(Optional) Reserved for future use.

uid

User ID. This parameter is used to identify the user in the channel for real-time audio and video interaction. You need to set and manage user IDs yourself, and ensure that each user ID in the same channel is unique. This parameter is a 32-bit unsigned integer. The value range is 1 to 2³²-1. If the user ID is not assigned (or set to 0), the SDK assigns a random user ID and returns it in the didJoinChannel callback. Your app must maintain the returned user ID, because the SDK does not do so.

joinSuccessBlock

The block of a user joining the specified channel. joinSuccessBlock takes higher priority than didJoinChannel. If you implement both callbacks, only block is triggered. Agora recommends setting joinSuccessBlock as nil to use the AgoraRtcEngineDelegate callback.

Returns

• 0: Success.
• < 0: Failure.

This method enables users 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.

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

Compared to joinChannelByToken [1/2], this method adds the options parameter to configure whether to automatically subscribe to all remote audio and video streams in the channel when the user joins the channel. By default, the user subscribes to the audio and video streams of all the other users in the channel, giving rise to usage and billings. To unsubscribe, set the options parameter or call the mute methods accordingly.

Parameters

token

The token generated on your server for authentication. See Authenticate Your Users with Token.

channelId

The channel name. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported character scopes are:

• All lowercase English letters: a to z.
• All uppercase English letters: A to Z.
• All numeric characters: 0 to 9.
• Space
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "= ", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

uid

The user ID. This parameter is used to identify the user in the channel for real-time audio and video interaction. You need to set and manage user IDs yourself, and ensure that each user ID in the same channel is unique. This parameter is a 32-bit unsigned integer. The value range is 1 to 2³²-1. If the user ID is not assigned (or set to 0), the SDK assigns a random user ID and returns it in the didJoinChannel callback. Your application must record and maintain the returned user ID, because the SDK does not do so.

mediaOptions

The channel media options. See AgoraRtcChannelMediaOptions for details.

joinSuccessBlock

The block of a user joining the specified channel. joinSuccessBlock takes higher priority than didJoinChannel. If you implement both callbacks, only block is triggered. Agora recommends setting joinSuccessBlock as nil to use the AgoraRtcEngineDelegate callback.

Returns

• 0: Success.
• < 0: Failure.

Once a user joins the channel, the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. To stop subscribing to a specified stream or all remote streams, call the corresponding mute methods.

Parameters

token

The token generated on your server for authentication. See Authenticate Your Users with Token.

channelId

The channel name. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported character scopes are:

• All lowercase English letters: a to z.
• All uppercase English letters: A to Z.
• All numeric characters: 0 to 9.
• Space
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "= ", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

userAccount

The user account. This parameter is used to identify the user in the channel for real-time audio and video engagement. You need to set and manage user accounts yourself and ensure that each user account in the same channel is unique. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as nil. Supported characters are (89 in total):

• The 26 lowercase English letters: a to z.
• The 26 uppercase English letters: A to Z.
• All numeric characters: 0 to 9.
• Space
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

joinSuccessBlock

The block of a user joining the specified channel. joinSuccessBlock takes higher priority than didJoinChannel. If you implement both callbacks, only block is triggered. Agora recommends setting joinSuccessBlock as nil to use the AgoraRtcEngineDelegate callback.

Returns

• 0: Success.
• < 0: Failure.

Once a user joins the channel, the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. To stop subscribing to a specified stream or all remote streams, call the corresponding mute methods.

Compared to joinChannelByToken [1/2], this method adds the options parameter to configure whether to automatically subscribe to all remote audio and video streams in the channel when the user joins the channel. By default, the user subscribes to the audio and video streams of all the other users in the channel, giving rise to usage and billings. To unsubscribe, set the options parameter or call the mute methods accordingly.

Parameters

token

The token generated on your server for authentication. See Authenticate Your Users with Token.

channelId

The channel name. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported character scopes are:

• All lowercase English letters: a to z.
• All uppercase English letters: A to Z.
• All numeric characters: 0 to 9.
• Space
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "= ", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

userAccount

The user account. This parameter is used to identify the user in the channel for real-time audio and video engagement. You need to set and manage user accounts yourself and ensure that each user account in the same channel is unique. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as nil. Supported characters are (89 in total):

• The 26 lowercase English letters: a to z.
• The 26 uppercase English letters: A to Z.
• All numeric characters: 0 to 9.
• Space
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

mediaOptions

The channel media options. See AgoraRtcChannelMediaOptions for details.

joinSuccessBlock

The block of a user joining the specified channel. joinSuccessBlock takes higher priority than didJoinChannel. If you implement both callbacks, only block is triggered. Agora recommends setting joinSuccessBlock as nil to use the AgoraRtcEngineDelegate callback.

Returns

• 0: Success.
• < 0: Failure.

This method releases all resources related to the session. This method call is asynchronous. When this method returns, it does not necessarily mean that the user has left the channel.

After joining the channel, you must call this method or leaveChannel [2/2] to end the call; otherwise, you cannot join the next call.

Parameters

leaveChannelBlock

This callback indicates that a user leaves a channel, and provides the statistics of the call in AgoraChannelStats.

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.

This method lets the user leave the channel, for example, by hanging up or exiting the call.

After joining the channel, you must call this method or leaveChannel [1/2] to end the call, otherwise, the next call cannot be started.

No matter whether you are currently in a call or not, you can call this method without side effects. This method releases all resources related to the session.

This method call is asynchronous, and the user has not left the channel when the method call returns. After you leave the channel, the SDK triggers the didLeaveChannelWithStats callback. A successful call of this method triggers the following callbacks: The local client: didLeaveChannelWithStats.The remote client: didOfflineOfUid, if the user joining the channel is in the COMMUNICATION profile, or is a host in the LIVE_BROADCASTING profile.

Parameters

options

The options for leaving the channel. See AgoraLeaveChannelOptions.

leaveChannelBlock

This callback indicates that a user leaves a channel, and provides the statistics of the call in AgoraChannelStats.

Returns

• 0: Success.
• < 0: Failure.

Use this method to monitor the plugging and swapping of external audio or video devices, for example, an external camera.

Parameters

enabled

Whether to monitor the change of the device state:

• YES: Monitor the device state change.
• NO: Do not monitor the device state change.

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

Parameters

mute

Whether to subscribe to the audio streams of all remote users:

• YES: Do not subscribe to the audio streams of all remote users.
• NO: (Default) Subscribe to the audio streams of all remote users by default.

Returns

• 0: Success.
• < 0: Failure.

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

Parameters

mute

Whether to stop subscribing to the video streams of all remote users.

• YES: Stop subscribing to the video streams of all remote users.
• NO: (Default) Subscribe to the audio streams of all remote users by default.

Returns

• 0: Success.
• < 0: Failure.

Parameters

mute

Whether to stop publishing the local audio stream.

• YES: Stop publishing the local audio stream.
• NO: (Default) Resumes publishing the local audio stream.

Returns

• 0: Success.
• < 0: Failure.

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

Parameters

mute

Whether to stop publishing the local video stream.

• YES: Stop publishing the local video stream.
• NO: (Default) Publish the local video stream.

Returns

• 0: Success.
• < 0: Failure.

Parameters

muted

• YES: Mute the recording signal.
• NO: (Default) Unmute the recording signal.

Returns

• 0: Success.
• < 0: Failure.

Parameters

uid

The user ID of the specified user.

mute

Whether to stop subscribing to the audio stream of the specified user.

• YES: Stop subscribing to the audio stream of the specified user.
• NO: (Default) Subscribe to the audio stream of the specified user.

Returns

• 0: Success.
• < 0: Failure.

Parameters

The ID of the specified user.

mute

Whether to stop subscribing to the video stream of the specified user.

• YES: Stop subscribing to the video streams of the specified user.
• NO: (Default) Subscribe to the video stream of the specified user.

Returns

• 0: Success.
• < 0: Failure.

After the cross-channel media stream relay starts, you can call this method to pause relaying media streams to all destination channels; after the pause, if you want to resume the relay, call resumeAllChannelMediaRelay.

After a successful method call, the SDK triggers the didReceiveChannelMediaRelayEvent callback to report whether the media stream relay is successfully paused.

Returns

• 0: Success.
• < 0: Failure.

Call this method when you are in a channel.

Returns

• 0: Success.
• < 0: Failure.

Returns

• 0: Success.
• < 0: Failure.

Parameters

soundId

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

Returns

• 0: Success.
• < 0: Failure.

Parameters

soundId

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

Attention: If you have preloaded an audio effect into memory by calling preloadEffect, ensure that this parameter is set to the same value as soundId in preloadEffect.

filePath

The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example: /var/mobile/Containers/Data/audio.mp4. Supported audio formats include MP3, AAC, M4A, MP4, WAV, and 3GP. See supported audio formats.

loopCount

The number of times the audio effect loops:

• ≥ 0: The number of playback times. For example, 1 means loop one time, which means play the audio effect two times in total.
• -1: Play the music effect in an infinite loop.

pitch

The pitch of the audio effect. The value range is 0.5 to 2.0. The default value is 1.0, which means the original pitch. The lower the value, the lower the pitch.

pan

The spatial position of the audio effect. The value range is 1 to10000.

• -1.0: The audio effect displays to the left.
• 0.0: The audio effect displays ahead.
• 1.0: The audio effect displays to the right.

gain

The volume of the audio effect. The value range is 1 to10000. The default value is 100.0, which means the original volume. The smaller the value, the lower the volume.

Returns

• 0: Success.
• < 0: Failure.

Parameters

soundId

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

Attention: If you have preloaded an audio effect into memory by calling preloadEffect, ensure that this parameter is set to the same value as soundId in preloadEffect.

filePath

Attention: If you have preloaded an audio effect into memory by calling preloadEffect, ensure that this parameter is set to the same value as filePath in preloadEffect.

loopCount

The number of times the audio effect loops:

• ≥ 0: The number of playback times. For example, 1 means loop one time, which means play the audio effect two times in total.
• -1: Play the audio effect in an infinite loop.

pitch

The pitch of the audio effect. The value range is 0.5 to 2.0. The default value is 1.0, which means the original pitch. The smaller the value, the lower the pitch.

pan

The spatial position of the audio effect. The value ranges between -1.0 and 1.0, where:

• -1.0: The audio effect displays to the left.
• 0.0: The audio effect displays ahead.
• 1.0: The audio effect displays to the right.

gain

The volume of the audio effect. The value range is 0.0 to 100.0. The default value is 100.0, which means the original volume. The smaller the value, the lower the volume.

publish

Whether to publish the audio effect to the remote users.

• YES: Publish the audio effect to the remote users. Both the local user and remote users can hear the audio effect.
• NO: Do not publish the audio effect to the remote users. Only the local user can hear the audio effect.

Returns

• 0: Success.
• < 0: Failure.

Parameters

soundId

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

Attention: If you have preloaded an audio effect into memory by calling preloadEffect, ensure that this parameter is set to the same value as soundId in preloadEffect.

filePath

The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example: /var/mobile/Containers/Data/audio.mp4. Supported audio formats include MP3, AAC, M4A, MP4, WAV, and 3GP. See supported audio formats.

Attention: If you have preloaded an audio effect into memory by calling preloadEffect, ensure that this parameter is set to the same value as filePath in preloadEffect.

loopCount

The number of times the audio effect loops:

• ≥ 0: The number of playback times. For example, 1 means loop one time, which means play the audio effect two times in total.
• -1: Play the music effect in an infinite loop.

pitch

The pitch of the audio effect. The value range is 0.5 to 2.0. The default value is 1.0, which means the original pitch. The lower the value, the lower the pitch.

pan

The spatial position of the audio effect. The value range is 1 to10000.

• -1.0: The audio effect displays to the left.
• 0.0: The audio effect displays ahead.
• 1.0: The audio effect displays to the right.

gain

The volume of the audio effect. The value range is 1 to10000. The default value is 100.0, which means the original volume. The smaller the value, the lower the volume.

publish

Whether to publish the audio effect to the remote users.

• YES: Publish the audio effect to the remote users. Both the local user and remote users can hear the audio effect.
• NO: Do not publish the audio effect to the remote users. Only the local user can hear the audio effect.

startPos

The playback position (ms) of the audio effect file.

Returns

• 0: Success.
• < 0: Failure.

To ensure smooth communication, limit the size of the audio effect file. We recommend using this method to preload the audio effect before calling joinChannelByToken [2/2].

Parameters

soundId

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

filePath

File path:

• iOS or macOS: The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example: /var/mobile/Containers/Data/audio.mp4.

Returns

• 0: Success.
• < 0: Failure.

Parameters

data

External audio data.

samples

Number of samples for the push.

timestamp

The timestamp (ms) of the external audio frame. It is mandatory. You can use this parameter for the following purposes: restore the order of the captured audio frame; and synchronize audio and video frames in video-related scenarios, including scenarios where external video sources are used.

sourceId

The ID of external audio source. If you want to publish a custom external audio source, set this parameter to the ID of the corresponding custom audio track you want to publish.

Returns

Parameters

data

External audio data.

timestamp

The timestamp (ms) of the external audio frame. It is mandatory. You can use this parameter for the following purposes: restore the order of the captured audio frame; and synchronize audio and video frames in video-related scenarios, including scenarios where external video sources are used.

sourceId

The ID of external audio source. If you want to publish a custom external audio source, set this parameter to the ID of the corresponding custom audio track you want to publish.

Returns

• 0: Success.
• < 0: Failure.

Parameters

sampleBuffer

The sample buffer.

Returns

• 0: Success.
• < 0: Failure.

If you call setExternalVideoSource and set the enabled parameter as YES and the encodedFrame parameter as NO, you can call this method to push the external raw video frame to the SDK.

Parameters

frame

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

Returns

• YES: Pushes the external raw video frame to the SDK successfully.
• NO: Fails to push external raw video frame to the SDK.

Parameters

callId

The current call ID. You can get the call ID by calling getCallId.

rating

The rating of the call. The value is between 1 (lowest score) and 5 (highest score). If you set a value out of this range, the SDK returns the -2 (ERR_INVALID_ARGUMENT) error.

description

(Optional) A description of the call. The string length should be less than 800 bytes.

Returns

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

Parameters

config

Observer settings for the encoded audio. For details, see AgoraAudioEncodedFrameDelegateConfig.

delegate

The encoded audio observer. For details, see AgoraAudioEncodedFrameDelegate.

Returns

• 0: Success.
• < 0: Failure.

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

Parameters

delegate

The observer object instance. For details, see AgoraAudioFrameDelegate. Set the value as nil to release the observer object. Agora recommends releasing the observer object after receiving the didLeaveChannelWithStats callback.

Returns

• 0: Success.
• < 0: Failure.

After successfully registering the audio spectrum observer and calling enableAudioSpectrumMonitor to enable the audio spectrum monitoring, the SDK reports the callback that you implement in the AgoraAudioSpectrumDelegate class at the time interval you set.

Parameters

delegate

The Audio spectrum observer. For details, see AgoraAudioSpectrumDelegate.

Returns

• 0: Success.
• < 0: Failure.

Once registered, the user account can be used to identify the local user when the user joins the channel. After the registration is successful, the user account can identify the identity of the local user, and the user can use it to join the channel.

After the user successfully registers a user account, the SDK triggers the didLocalUserRegisteredWithUserId callback on the local client, reporting the user ID and user account of the local user.

The difference between the two ways is that the time elapsed between calling the registerLocalUserAccountWithAppID method and joining the channel is shorter than directly calling joinChannelByToken [2/2].

Parameters

appID

The App ID of your project on Agora Console.

userAccount

The user account. This parameter is used to identify the user in the channel for real-time audio and video engagement. You need to set and manage user accounts yourself and ensure that each user account in the same channel is unique. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as nil. Supported characters are (89 in total):

• The 26 lowercase English letters: a to z.
• The 26 uppercase English letters: A to Z.
• All numeric characters: 0 to 9.
• Space
• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

Returns

• 0: Success.
• < 0: Failure.

You need to implement the AgoraMediaMetadataDelegate class and specify the metadata type in this method. This method enables you to add synchronized metadata in the video stream for more diversified live interactive streaming, such as sending shopping links, digital coupons, and online quizzes.

A successful call of this method triggers the metadataMaxSize callback.

Parameters

observer

The metadata observer. See AgoraMediaMetadataDelegate.

type

The metadata type. The SDK currently only supports AgoraMetadataTypeVideo. See AgoraMetadataType.

Returns

• 0: Success.
• < 0: Failure.

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

Parameters

delegate

The observer object instance. To release the instance, set the value as nil. For details, see AgoraVideoFrameDelegate.

Returns

• 0: Success.
• < 0: Failure.

After calling the pauseAllChannelMediaRelay method, you can call this method to resume relaying media streams to all destination channels.

After a successful method call, the SDK triggers the didReceiveChannelMediaRelayEvent callback to report whether the media stream relay is successfully resumed.

Returns

• 0: Success.
• < 0: Failure.

Returns

• 0: Success.
• < 0: Failure.

Parameters

soundId

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

Returns

• 0: Success.
• < 0: Failure.

Parameters

volume

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

Returns

• 0: Success.
• < 0: Failure.

Parameters

soundId

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

volume

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

Returns

• 0: Success.
• < 0: Failure.

Returns

• 0: Success.
• < 0: Failure.

Parameters

soundId

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

Returns

• 0: Success.
• < 0: Failure.

Parameters

soundId

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

Returns

• 0: Success.
• < 0: Failure.

After a successful method call, the SDK triggers rtmpStreamingChangedToState on the local client to report the result of deleting the URL.

Parameters

url

The media push URL to be removed. The maximum length of this parameter is 1024 bytes. The media push URL must not contain special characters, such as Chinese characters.

Returns

• 0: Success.
• < 0: Failure.

• The SDK triggers the tokenPrivilegeWillExpire callback.
• The connectionChangedToState callback reports AgoraConnectionChangedReasonTokenExpired(9).

Parameters

token

The new token.

Returns

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

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

Returns

• 0: Success.
• < 0: Failure.

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

A successful method call triggers the receiveStreamMessageFromUid callback on the remote client, from which the remote user gets the stream message. A failed method call triggers the didOccurStreamMessageErrorFromUid callback on the remote client.

Parameters

streamId

The data stream ID. You can get the data stream ID by calling createDataStream [2/2].

data

The message to be sent.

Returns

• 0: Success.
• < 0: Failure.

Detailed Description

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

Parameters

preset

The options for SDK preset audio effects:

• AgoraAudioEffectPresetRoomAcous3DVoice, 3D voice effect:
  • Call and set the profile parameter in setAudioProfile [1/2] to AgoraAudioProfileMusicStandardStereo (3) or AgoraAudioProfileMusicHighQualityStereo(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.
• AgoraAudioEffectPresetPitchCorrection, Pitch correction effect: To achieve better audio effect quality, Agora recommends calling setAudioProfile [1/2] and setting the profile parameter to AgoraAudioProfileMusicHighQuality (4) or AgoraAudioProfileMusicHighQualityStereo(5) before setting this enumerator.

param1

• If you set preset to AgoraAudioEffectPresetRoomAcous3DVoice , param1 sets the cycle period of the 3D voice effect. The value range is [1,60] and the unit is seconds. The default value is 10, indicating that the voice moves around you every 10 seconds.
• If you set preset to AgoraAudioEffectPresetPitchCorrection , param1 sets the basic mode of the pitch correction effect:
  • 1: (Default) Natural major scale.
  • 2: Natural minor scale.
  • 3: Japanese pentatonic scale.

param2

• If you set preset to AgoraAudioEffectPresetRoomAcous3DVoice, you need to set param2 to 0.
• If you set preset to AgoraAudioEffectPresetPitchCorrection, param2 sets the tonic pitch of the pitch correction effect:
  • 1: A
  • 2: A#
  • 3: B
  • 4: (Default) C
  • 5: C#
  • 6: D
  • 7: D#
  • 8: E
  • 9: F
  • 10: F#
  • 11: G
  • 12: G#

Returns

• 0: Success.
• < 0: Failure.

Detailed Description

Call this method to set an SDK preset audio effect for the local user who sends an audio stream. This audio effect does not change the gender characteristics of the original voice. After setting an audio effect, all users in the channel can hear the effect.

To get better audio effect quality, Agora recommends calling setAudioProfile [1/2] and setting the scenario parameter as AgoraAudioScenarioGameStreaming (3) before calling this method.

Parameters

preset

The options for SDK preset audio effects. See AgoraAudioEffectPreset.

Returns

• 0: Success.
• < 0: Failure.

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

Parameters

pos

Integer. The playback position (ms).

Returns

• 0: Success.
• < 0: Failure.

Parameters

profile

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

scenario

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

Returns

• 0: Success.
• < 0: Failure.

Parameters

profile

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

Returns

• 0: Success.
• < 0: Failure.

Enables or disables image enhancement, and sets the options.

Parameters

enable

Whether to enable the image enhancement function:

• YES: Enable the image enhancement function.
• NO: (Default) Disable the image enhancement function.

options

The image enhancement options. See AgoraBeautyOptions.

Returns

• 0: Success.
• < 0: Failure.

After initializing the SDK, the default channel profile is the live streaming profile. You can call this method to set the usage scenario of Agora channel. The Agora SDK differentiates channel profiles and applies optimization algorithms accordingly. For example, it prioritizes smoothness and low latency for a video call and prioritizes video quality for interactive live video streaming.

Parameters

profile

The channel profile. See AgoraChannelProfile for details.

Returns

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

When users' network access is restricted by a firewall, , configure the firewall to allow specific IP addresses and ports provided by Agora; then, call this method to enable the cloud proxy and set the cloud proxy type with the proxyType parameter.

After successfully connecting to the cloud proxy, the SDK triggers the connectionChangedToState (AgoraConnectionStateConnecting, AgoraConnectionChangedReasonSettingProxyServer) callback.

To disable the cloud proxy that has been set, call the setCloudProxy(AgoraNoneProxy).

To change the cloud proxy type that has been set, call the setCloudProxy(AgoraNoneProxy) first, and then call the setCloudProxy to set the proxyType you want.

Parameters

proxyType

The type of the cloud proxy. See AgoraCloudProxyType.

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

Returns

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

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

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

Parameters

role

The user role. See AgoraClientRole for details.

Returns

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

In the interactive live streaming profile, the SDK sets the user role as audience by default. You can call this method to set the user role as host.

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

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

Parameters

role

The user role in the interactive live streaming. For details, see AgoraClientRole.

options

The detailed options of a user, including the user level. See AgoraClientRoleOptions for details.

Returns

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

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

Parameters

mute

Whether to stop subscribing to the audio streams of all remote users by default.

• YES: Stop subscribing to the audio streams of all remote users by default.
• NO: (Default) Subscribe to the audio streams of all remote users by default.

Returns

• 0: Success.
• < 0: Failure.

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

Parameters

mute

Whether to stop subscribing to the audio streams of all remote users by default.

• YES: Stop subscribing to the audio streams of all remote users by default.
• NO: (Default) Resume subscribing to the audio streams of all remote users by default.

Returns

• 0: Success.
• < 0: Failure.

Parameters

type

The device type, which includes the audio capturing, audio playback, video capturing, or video playback device. See AgoraMediaDeviceType.

deviceId

The device ID. You can get the device ID by calling enumerateDevices.Plugging or unplugging the audio device does not change the value of deviceId.

Returns

• 0: Success.
• < 0: Failure.

Sets the volume of audio or video capture or playback devices.

Parameters

type

The device type, which includes the audio capturing, audio playback, video capturing, or video playback device. See AgoraMediaDeviceType.

volume

The volume of the specified device. The value ranges between 0 (lowest volume) and 255 (highest volume).

Returns

• 0: Success.
• < 0: Failure.

Deprecated:

Use enableEncryption instead.

The Agora SDK supports built-in encryption, which is set to the AES-128-GCM mode by default. Call this method to use other encryption modes. All users in the same channel must use the same encryption mode and secret. Refer to the information related to the AES encryption algorithm on the differences between the encryption modes.

Parameters

encryptionMode

Encryption mode.

• "aes-128-xts": 128-bit AES encryption, XTS mode.
• "aes-128-ecb": 128-bit AES encryption, ECB mode.
• "aes-256-xts": 256-bit AES encryption, XTS mode.
• "sm4-128-ecb": 128-bit SM4 encryption, ECB mode.
• "aes-128-gcm": 128-bit AES encryption, GCM mode.
• "aes-256-gcm": 256-bit AES encryption, GCM mode.
• "": When this parameter is set as null, the encryption mode is set as "aes-128-gcm" by default.

Returns

• 0: Success.
• < 0: Failure.

Deprecated:

This method is deprecated from v3.2.0. Please use enableEncryption instead.

Before joining the channel, you need to call this method to set the secret parameter to enable the built-in encryption. All users in the same channel should use the same secret. The secret is automatically cleared once a user leaves the channel. If you do not specify the secret or secret is set as null, the built-in encryption is disabled.

Parameters

secret

The encryption password.

Returns

• 0: Success.
• < 0: Failure.

After enabling the extension, you can call this method to set the properties of the extension.

Parameters

provider

The name of the extension provider.

extension

The name of the extension.

key

The key of the extension.

value

The value of the extension key.

Returns

• 0: Success.
• < 0: Failure.

You can call this method to set the attributes of the extension provider and initialize the relevant parameters according to the type of the provider.

Parameters

provider

The name of the extension provider.

key

The key of the extension.

value

The value of the extension key.

Returns

• 0: Success.
• < 0: Failure.

Call this method before calling joinChannelByToken [1/2] and startPreview.

Parameters

enabled

• YES: Enable the external audio source.
• NO: (Default) Disable the external audio source.

sampleRate

The sample rate (Hz) of the external audio source, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.

channels

The number of audio channels of the external audio source:

• 1: Mono.
• 2: Stereo.

Returns

• 0: Success.
• < 0: Failure.

Parameters

enabled

Whether to enable the external audio source:

• YES: Enable the external audio source.
• NO: (Default) Disable the external audio source.

sampleRate

The sample rate (Hz) of the external audio source, which can be set as 8000, 16000, 32000, 44100, or 48000.

channels

The number of channels of the external audio source, which can be set as 1 (Mono) or 2 (Stereo).

sourceNumber

The number of external audio sources. The value of this parameter should be larger than 0. The SDK creates a corresponding number of custom audio tracks based on this parameter value and names the audio tracks starting from 0. In AgoraRtcChannelMediaOptions, you can set publishCustomAudioSourceId to the ID of the audio track you want to publish.

localPlayback

Whether to play the external audio source:

• YES: Play the external audio source.
• NO: (Default) Do not play the external source.

publish

Whether to publish audio to the remote users:

• YES: (Default) Publish audio to the remote users.
• NO: Do not publish audio to the remote users

Returns

• 0: Success.
• < 0: Failure.

Parameters

enable

Determines whether to use the external video source:

• YES: Use the external video source. The SDK prepares to accept the external video frame.
• NO: (Default) Do not use the external video source.

useTexture

Determines whether to use the external video frame in the Texture format.

• YES: Use the external video frame in the Texture format.
• NO: (Default) Do not use the external video frame in the Texture format.

sourceType

Whether to encode the external video frame, see AgoraExternalVideoSourceType.

Returns

• 0: Success.
• < 0: Failure.

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

Parameters

transcoding

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

Returns

• 0: Success.
• < 0: Failure.

Deprecated:

This method is deprecated. Use setLocalRenderMode [2/2] instead.

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

Parameters

mode

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

uid

User ID

Returns

• 0: Success.
• < 0: Failure.

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

Parameters

mode

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

mirror

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

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

Returns

• 0: Success.
• < 0: Failure.

Deprecated:

Deprecated as of v3.0.0.

Use setupLocalVideo or setLocalRenderMode [2/2] instead.

Parameters

mode

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

Returns

• 0: Success.
• < 0: Failure.

Deprecated:

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

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

Parameters

voiceChanger

The local voice changer option. The default value is AgoraAudioVoiceChangerOff , which means the original voice. For more details, see AgoraAudioVoiceChanger. The gender-based beatification effect works best only when assigned a proper gender. Use AgoraAudioGeneralBeautyVoiceMaleMagnetic for male and use AgoraAudioGeneralBeautyVoiceFemaleFresh and AgoraAudioGeneralBeautyVoiceFemaleVitality for female. Failure to do so can lead to voice distortion.

Returns

• 0: Success.
• < 0: Failure.

Parameters

bandFrequency

The band frequency. The value ranges between 0 and 9; representing the respective 10-band center frequencies of the voice effects, including 31, 62, 125, 250, 500, 1k, 2k, 4k, 8k, and 16k Hz. For more details, see AgoraAudioEqualizationBandFrequency.

gain

The gain of each band in dB. The value ranges between -15 and 15. The default value is 0.

Returns

• 0: Success.
• < 0: Failure.

Parameters

pitch

The local voice pitch. The value range is [0.5,2.0]. The lower the value, the lower the pitch. The default value is 1 (no change to the pitch).

Returns

• 0: Success.
• < 0: Failure.

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

Parameters

reverbType

The reverberation key. Agora provides 5 reverberation keys: AgoraAudioReverbType.

value

The value of the reverberation key.

Returns

• 0: Success.
• < 0: Failure.

This method sets the local voice reverberation for users in a COMMUNICATION channel or hosts in a LIVE_BROADCASTING channel. After successfully calling this method, all users in the channel can hear the voice with reverberation.

Parameters

reverbPreset

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

Returns

• 0: Success.
• < 0: Failure.

Deprecated:

Use the mLogConfig parameter in sharedEngineWithConfig method instead.

Specifies an SDK output log file. The log file records all log data for the SDK’s operation. Ensure that the directory for the log file exists and is writable.

Parameters

filePath

The absolute path of the log files. These log files are encoded in UTF-8.

Returns

• 0: Success.
• < 0: Failure.

Deprecated:

Use the logConfig parameter in sharedEngineWithConfig instead.

By default, the SDK generates five SDK log files and five API call log files with the following rules:

• The SDK log files are: agorasdk.log, agorasdk.1.log, agorasdk.2.log, agorasdk.3.log, and agorasdk.4.log.
• The API call log files are: agoraapi.log, agoraapi.1.log, agoraapi.2.log, agoraapi.3.log, and agoraapi.4.log.
• The default size for each SDK log file is 1,024 KB; the default size for each API call log file is 2,048 KB. These log files are encoded in UTF-8.
• The SDK writes the latest logs in agorasdk.log or agoraapi.log.
• When agorasdk.log is full, the SDK processes the log files in the following order:
  1. Delete the agorasdk.4.log file (if any).
  2. Rename agorasdk.3.log to agorasdk.4.log.
  3. Rename agorasdk.2.log to agorasdk.3.log.
  4. Rename agorasdk.1.log to agorasdk.2.log.
  5. Create a new agorasdk.log file.
• The overwrite rules for the agoraapi.log file are the same as for agorasdk.log.

Parameters

fileSizeInKBytes

The size (KB) of an agorasdk.log file. The value range is [128,20480]. The default value is 1,024 KB. If you set fileSizeInKByte smaller than 128 KB, the SDK automatically adjusts it to 128 KB; if you set fileSizeInKByte greater than 20,480 KB, the SDK automatically adjusts it to 20,480 KB.

Returns

• 0: Success.
• < 0: Failure.

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

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

Parameters

filter

The output log level of the SDK. For details, see AgoraLogFilter.

Returns

• 0: Success.
• < 0: Failure.

Deprecated:

This method is deprecated. Use AgoraRtcEngineConfig instead to set the log output level.

Choose a level to see the logs preceding that level.

Parameters

level

The log level: AgoraLogLevel.

Returns

• 0: Success.
• < 0: Failure.

- (BOOL)setMediaMetadataDataSource:(id<AgoraMediaMetadataDataSource> _Nullable)metadataDataSource withType:(AgoraMetadataType)type;

You need to implement the AgoraMediaMetadataDataSource protocol in this method and specify the data format of the metadata. After a successful method call, the SDK triggers the metadataMaxSize callback.

This method can be used with setMediaMetadataDelegate to add synchronized metadata in the video stream for more diversified live interactions, such as sending shopping links, digital coupons, and online quizzes.

Parameters

metadataDataSource

The AgoraMediaMetadataDataSource protocal.

type

The data type of the metadata. See AgoraMetadataType. We only support video metadata for now.

Returns

• YES: Success.
• NO: Failure.

Parameters

sampleRate

The sample rate (Hz) of the audio data, which can be set as 8000, 16000, 32000, 44100, or 48000.

channel

The number of channels of the audio data, which can be set as 1 (Mono) or 2 (Stereo).

samplesPerCall

Sets the number of samples. In media push scenarios, set it as 1024.

Returns

• 0: Success.
• < 0: Failure.

Sets the audio data format reported by onPlaybackAudioFrameBeforeMixing.

Parameters

sampleRate

The sample rate returned in the callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.

channel

The number of channels of the external audio source, which can be set as 1(Mono) or 2(Stereo).

Returns

• 0: Success.
• < 0: Failure.

Sets the data format for the onPlaybackAudioFrame callback.

Parameters

sampleRate

The sample rate returned in the onPlaybackAudioFrame callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.

channel

The number of channels returned in the onPlaybackAudioFrame callback:

• 1: Mono.
• 2: Stereo.

mode

The use mode of the audio frame. See AgoraAudioRawFrameOperationMode.

samplesPerCall

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

Returns

• 0: Success.
• < 0: Failure.

Sets the audio format for the onRecordAudioFrame callback.

Parameters

sampleRate

The sample rate returned in the onRecordAudioFrame callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.

channel

The number of channels returned in the onRecordAudioFrame callback:

• 1: Mono.
• 2: Stereo.

mode

The use mode of the audio frame. See AgoraAudioRawFrameOperationMode.

samplesPerCall

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

Returns

• 0: Success.
• < 0: Failure.

Under limited network conditions, if the publisher has not disabled the dual-stream mode using (),the receiver can choose to receive either the high-quality video stream or the low-quality video stream. The high-quality video stream has a higher resolution and bitrate, and the low-quality video stream has a lower resolution and bitrate.enableDualStreamMode [1/3]NO

By default, users receive the high-quality video stream. Call this method if you want to switch to the low-quality video stream. This method allows the app to adjust the corresponding video stream type based on the size of the video window to reduce the bandwidth and resources. The aspect ratio of the low-quality video stream is the same as the high-quality video stream. Once the resolution of the high-quality video stream is set, the system automatically sets the resolution, frame rate, and bitrate of the low-quality video stream.

The result of this method returns in the didApiCallExecute callback.

Parameters

streamType

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

Returns

• 0: Success.
• < 0: Failure.

Deprecated:

This method is deprecated. Use setRemoteRenderMode [2/2] instead.

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

Parameters

userId

The ID of the remote user.

renderMode

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

Returns

• 0: Success.
• < 0: Failure.

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

Parameters

userId

The ID of the remote user.

renderMode

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

mirrorMode

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

Returns

• 0: Success.
• < 0: Failure.

Under limited network conditions, if the publisher has not disabled the dual-stream mode using enableDualStreamMode [1/3](NO), the receiver can choose to receive either the high-quality video stream (the high resolution, and high bitrate video stream) or the low-quality video stream (the low resolution, and low bitrate video stream). The high-quality video stream has a higher resolution and bitrate, and the low-quality video stream has a lower resolution and bitrate.

By default, users receive the high-quality video stream. Call this method if you want to switch to the low-quality video stream. This method allows the app to adjust the corresponding video stream type based on the size of the video window to reduce the bandwidth and resources. The aspect ratio of the low-quality video stream is the same as the high-quality video stream. Once the resolution of the high-quality video stream is set, the system automatically sets the resolution, frame rate, and bitrate of the low-quality video stream.

The method result returns in the didApiCallExecute callback.

Parameters

uid

User ID.

streamType

The video stream type: AgoraVideoStreamType.

Returns

• 0: Success.
• < 0: Failure.

This method sets the 2D position and volume of a remote user, so that the local user can easily hear and identify the remote user's position.

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

Parameters

uid

The user ID of the remote user.

pan

The voice position of the remote user. The value ranges from -1.0 to 1.0:

• 0.0: (Default) The remote voice comes from the front.
• -1.0: The remote voice comes from the left.
• 1.0: The remote voice comes from the right.

gain

The volume of the remote user. The value ranges from 0.0 to 100.0. The default value is 100.0 (the original volume of the remote user). The smaller the value, the lower the volume.

Returns

• 0: Success.
• < 0: Failure.

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

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

Parameters

local

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

Returns

• 0: Success.
• < 0: Failure.

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

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

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

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

Parameters

remote

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

Returns

• 0: Success.
• < 0: Failure.

Sets the encoder configuration for the local video.

Parameters

config

Video profile. See AgoraVideoEncoderConfiguration.

Returns

• 0: Success.
• < 0: Failure.

Deprecated:

This method is deprecated as of v2.3. Please use setVideoEncoderConfiguration instead.

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

Parameters

profile

Video profile. For details, see AgoraVideoProfile.

swapWidthAndHeight

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

• YES: Swap the width and height.
• NO: (Default) Do not swap the width and height.

Returns

• 0: Success.
• < 0: Failure.

Deprecated:

This method is deprecated as of v2.3. Please use setVideoEncoderConfiguration instead.

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

Parameters

width

The width of the video. The maximum value of width × height is 1280 × 720.

height

The height of the video. The maximum value of width × height is 1280 × 720.

frameRate

The frame rate of the video. The highest value is 30. You can set the parameter as 5, 10, 15, 24, and 30.

bitrate

The bitrate of the video. You need to manually work out the bitrate according to the width, height, and frame rate. 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.

Deprecated:

Deprecated as of v2.4.0. Agora recommends using the degradationPreference parameter in the AgoraVideoEncoderConfiguration class to set the video quality preference.

Parameters

preferFrameRateOverImageQuality

Whether to prioritize smoothness or image quality.

• YES: Prioritizes smoothness.
• NO: (Default) Prioritizes the image quality.

Returns

• 0: Success.
• < 0: Failure.

Call this method to set a gender characteristic and a reverberation effect for the singing beautifier effect. This method sets parameters for the local user who sends an audio stream. After setting the audio parameters, all users in the channel can hear the effect.

For better voice effects, Agora recommends that you call setAudioProfile [1/2] and setscenario to AgoraAudioScenarioGameStreaming(3) and profile to AgoraAudioProfileMusicHighQuality(4) or AgoraAudioProfileMusicHighQualityStereo(5) before calling this method.

Parameters

preset

The option for the preset audio effect:

• SINGING_BEAUTIFIER: The singing beautifier effect.

param1

The gender characteristics options for the singing voice:

• 1: A male-sounding voice.
• 2: A female-sounding voice.

param2

The reverberation effect options for the singing voice:

• 1: The reverberation effect sounds like singing in a small room.
• 2: The reverberation effect sounds like singing in a large room.
• 3: The reverberation effect sounds like singing in a hall.

Returns

• 0: Success.
• < 0: Failure.

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

For better voice effects, Agora recommends that you call setAudioProfile [1/2] and set scenario to AgoraAudioScenarioGameStreaming (3) and profile to AgoraAudioProfileMusicHighQuality (4) or AgoraAudioProfileMusicHighQualityStereo (5) before calling this method.

Parameters

preset

The preset voice beautifier effect options: AgoraVoiceBeautifierPreset.

Returns

• 0: Success.
• < 0: Failure.

Call this method to set a preset voice beautifier effect for the local user who sends an audio stream. After setting an audio effect, all users in the channel can hear the effect. You can set different audio effects for different scenarios. See Set the Voice Beautifier and Audio Effects.

To achieve better audio effect quality, Agora recommends that you call setAudioProfile [1/2] and set the profile to AgoraAudioProfileMusicHighQuality(4) or AgoraAudioProfileMusicHighQualityStereo(5) and scenario to AgoraAudioScenarioGameStreaming(3) before calling this method.

Parameters

preset

The options for the preset voice beautifier effects: AgoraVoiceConversionPreset.

Returns

• 0: Success.
• < 0: Failure.

This method tests whether the local audio capture device and playback device are working properly. After starting the test, the audio capture device records the local audio, and the audio playback device plays the captured audio. The SDK triggers two independent reportAudioVolumeIndicationOfSpeakers callbacks at the time interval set in this method, which reports the volume information of the capture device (uid = 0) and the volume information of the playback device (uid = 1) respectively.

Parameters

indicationInterval

The time interval (ms) at which the SDK triggers the reportAudioVolumeIndicationOfSpeakers callback. Agora recommends a setting greater than 200 ms. This value must not be less than 10 ms; otherwise, you can not receive the reportAudioVolumeIndicationOfSpeakers callback.

Returns

• 0: Success.
• < 0: Failure.

Deprecated:

Please use startAudioMixing [2/2] instead.

This method mixes the specified local or online audio file with the audio from the microphone, or replaces the microphone's audio with the specified local or remote audio file. A successful method call triggers the audioMixingStateChanged (AgoraAudioMixingStateTypePlaying) callback. When the audio mixing file playback finishes, the SDK triggers the audioMixingStateChanged (AgoraAudioMixingStateTypeStopped) callback on the local client.

Parameters

filePath

The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example: /var/mobile/Containers/Data/audio.mp4. Supported audio formats include MP3, AAC, M4A, MP4, WAV, and 3GP. See supported audio formats.

loopback

Whether to only play music files on the local client:

• YES: Only play music files on the local client so that only the local user can hear the music.
• NO: Publish music files to remote clients so that both the local user and remote users can hear the music.

replace

Whether to replace the audio captured by the microphone with a music file:

• YES: Replace the audio captured by the microphone with a music file. Users can only hear the music.
• NO: Do not replace the audio captured by the microphone with a music file. Users can hear both music and audio captured by the microphone.

cycle

The number of times the music file plays.

• ≥ 0: The number of playback times. For example, 0 means that the SDK does not play the music file while 1 means that the SDK plays once.
• -1: Play the audio effect in an infinite loop.

Returns

• 0: Success.
• < 0: Failure.

This method mixes the specified local or online audio file with the audio from the microphone, or replaces the microphone's audio with the specified local or remote audio file. A successful method call triggers the audioMixingStateChanged (PLAY) callback. When the audio mixing file playback finishes, the SDK triggers the audioMixingStateChanged (STOPPED) callback on the local client.

Parameters

filePath

The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example: /var/mobile/Containers/Data/audio.mp4. Supported audio formats include MP3, AAC, M4A, MP4, WAV, and 3GP. See supported audio formats.

loopcount

Whether to only play music files on the local client:

• YES: Only play music files on the local client so that only the local user can hear the music.
• NO: Publish music files to remote clients so that both the local user and remote users can hear the music.

replace

Whether to replace the audio captured by the microphone with a music file:

• YES: Replace the audio captured by the microphone with a music file. Users can only hear the music.
• NO: Do not replace the audio captured by the microphone with a music file. Users can hear both music and audio captured by the microphone.

cycle

The number of times the music file plays.

• ≥ 0: The number of playback times. For example, 0 means that the SDK does not play the music file while 1 means that the SDK plays once.
• -1: Play the music effect in an infinite loop.

startPos

The playback position (ms) of the music file.

Returns

• 0: Success.
• < 0: Failure.

Deprecated:

This method is deprecated as of v2.9.1. It has a fixed recording sample rate of 32 kHz. Please use the startAudioRecording [2/2] method instead.

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

Parameters

filePath

The absolute path (including the filename extensions) of the recording file. For example: /var/mobile/Containers/Data/audio.mp4.

Attention:

Ensure that the directory for the log files exists and is writable.

quality

Audio recording quality. See AgoraAudioRecordingQuality.

Returns

• 0: Success.
• < 0: Failure.

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

Parameters

config

Recording configuration. See AgoraAudioRecordingConfiguration.

Returns

• 0: Success.
• < 0: Failure.

Parameters

config

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

Returns

• Success.
• <Failure.

Deprecated:

This method is deprecated as of v2.4.0. Use startEchoTestWithInterval instead.

This method starts an audio call test to determine whether the audio devices (for example, headset and speaker) and the network connection are working properly. To conduct the test, the user speaks, and the recording is played back within 10 seconds. If the user can hear the recording within the interval, the audio devices and network connection are working properly.

Parameters

successBlock

The SDK triggers the successBlock callback if this method call is successful.

Returns

• 0: Success.
• < 0: Failure.

This method starts an audio call test to determine whether the audio devices (for example, headset and speaker) and the network connection are working properly. To conduct the test, let the user speak for a while, and the recording is played back within the set interval. If the user can hear the recording within the interval, the audio devices and network connection are working properly.

Parameters

interval

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

successBlock

The SDK triggers the successBlock callback if this method call is successful.

Returns

• 0: Success.
• < 0: Failure.

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

Parameters

config

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

Returns

• 0: Success.
• < 0: Failure.

This method tests whether the audio playback device works properly. Once a user starts the test, the SDK plays an audio file specified by the user. If the user can hear the audio, the playback device works properly.

After calling this method, the SDK triggers the reportAudioVolumeIndicationOfSpeakers callback every 100 ms, reporting uid = 1 and the volume information of the playback device.

Parameters

audioFileName

The path of the audio file for the audio playback device test in UTF-8.

Returns

• 0: Success.
• < 0: Failure.

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

• Call setupLocalVideo to set the local preview window.
• Call enableVideo to enable the video.

Returns

• 0: Success.
• < 0: Failure.

This method tests whether the audio capture device works properly. After calling this method, the SDK triggers the reportAudioVolumeIndicationOfSpeakers callback at the time interval set in this method, which reports uid = 0 and the volume information of the capturing device.

Parameters

indicationInterval

The time interval (ms) at which the SDK triggers the reportAudioVolumeIndicationOfSpeakers callback. Agora recommends a setting greater than 200 ms. This value must not be less than 10 ms; otherwise, you can not receive the reportAudioVolumeIndicationOfSpeakers callback.

Returns

• 0: Success.
• < 0: Failure.

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

Parameters

displayId

The display ID of the screen to be shared. This parameter specifies which screen you want to share.

For more information on how to get the display ID, see https://docs.agora.io/en/live-streaming-4.x-beta/screensharing_ios_ng?platform=macOS.

regionRect

(Optional) Sets the relative location of the region to the screen. If you do not set this parameter, the SDK shares the whole screen. It consists of the following parameters:

• x: The horizontal offset from the top-left corner.
• y: The vertical offset from the top-left corner.
• width: The width of the region.
• height: The height of the region.

If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen.

captureParams

Screen sharing configurations. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges. See AgoraScreenCaptureParameters for details.

Returns

• 0: Success.
• < 0: Failure.

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

Parameters

windowId

The ID of the window to be shared.

regionRect

(Optional) The relative location of the region to the window. If you do not set this parameter, the SDK shares the whole window. It consists of the following parameters:

• x: The horizontal offset from the top-left corner.
• y: The vertical offset from the top-left corner.
• width: The width of the region.
• height: The height of the region.

If the specified region overruns the window, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole window.

captureParams

Screen sharing configurations. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges. For details, see AgoraScreenCaptureParameters.

Returns

• 0: Success.
• < 0: Failure.

Parameters

captureParams

The screen sharing encoding parameters. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges. For details, see AgoraScreenCaptureParameters.

Returns

• 0: Success.
• < 0: Failure.

Parameters

rect

The relative location of the region to the screen or window. If you do not set this parameter, the SDK shares the whole screen. 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.

You can call this method to push a live audio-and-video stream to the specified CDN address and set the transcoding configuration. This method can push media streams to only one CDN address at a time, so if you need to push streams to multiple addresses, call this method multiple times.

After you call this method, the SDK triggers the rtmpStreamingChangedToState callback on the local client to report the state of the streaming.

Parameters

url

The address of Media Push. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported.

Returns

• 0: Success.
• < 0: Failure.
  • -2: url is null or the string length is 0.
  • -7: The SDK is not initialized before calling this method.

You can call this method to push a live audio-and-video stream to the specified CDN address and set the transcoding configuration. This method can push media streams to only one CDN address at a time, so if you need to push streams to multiple addresses, call this method multiple times.

After you call this method, the SDK triggers the rtmpStreamingChangedToState callback on the local client to report the state of the streaming.

Parameters

url

The address of Media Push. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported.

transcoding

The transcoding configuration for Media Push. See AgoraLiveTranscoding.

Returns

• 0: Success.
• < 0: Failure.
  • -2: url is null or the string length is 0.
  • -7: The SDK is not initialized before calling this method.

Returns

• 0: Success.
• < 0: Failure.

Returns

• 0: Success.
• < 0: Failure.

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

Returns

• 0: Success.
• < 0: Failure.

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

Returns

• 0: Success.
• < 0: Failure.

After a successful method call, the SDK triggers the channelMediaRelayStateDidChange callback. If the callback reports AgoraChannelMediaRelayStateIdle (0) and AgoraChannelMediaRelayErrorNone (0), the host successfully stops the relay.

Returns

• 0: Success.
• < 0: Failure.

Returns

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

Returns

• 0: Success.
• < 0: Failure.

Returns

• 0: Success.
• < 0: Failure.

This method stops the audio playback device test. You must call this method to stop the test after calling the startPlaybackDeviceTest method.

Returns

• 0: Success.
• < 0: Failure.

This method stops the audio capture device test. You must call this method to stop the test after calling the startRecordingDeviceTest method.

Returns

• 0: Success.
• < 0: Failure.

You can call this method to stop the live stream on the specified CDN address. This method can stop pushing media streams to only one CDN address at a time, so if you need to stop pushing streams to multiple addresses, call this method multiple times.

After you call this method, the SDK triggers the rtmpStreamingChangedToState callback on the local client to report the state of the streaming.

Parameters

url

The address of Media Push. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported.

Returns

• 0: Success.
• < 0: Failure.

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

Parameters

channel

The channel name.

uid

The user ID. Set uid as 0 if you want to take a snapshot of the local user's video.

filePath

The local path (including the filename extensions) of the snapshot. For example,

• macOS: ～/Library/Logs/example.jpg

Ensure that the path you specify exists and is writable.

Returns

• 0: Success.
• < 0: Failure.

After calling registerAudioSpectrumDelegate, if you want to disable audio spectrum monitoring, you can call this method.

Parameters

delegate

The Audio spectrum observer. For details, see AgoraAudioSpectrumDelegate.

Returns

• 0: Success.
• < 0: Failure.

Parameters

mediaOptions

The channel media options. See AgoraRtcChannelMediaOptions.

Returns

• 0: Success.
• < 0: Failure.

After the media relay starts, if you want to relay the media stream to more channels, or leave the current relay channel, you can call the updateChannelMediaRelay method.

After a successful method call, the SDK triggers the didReceiveChannelMediaRelayEvent callback with the AgoraChannelMediaRelayEventUpdateDestinationChannel (7) state code.

Parameters

config

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

Returns

• 0: Success.
• < 0: Failure.

After you start pushing media streams to CDN with transcoding, you can dynamically update the transcoding configuration according to the scenario. The SDK triggers the rtcEngineTranscodingUpdated callback after the transcoding configuration is updated.

Parameters

transcoding

The transcoding configuration for Media Push. See AgoraLiveTranscoding.

Returns

• 0: Success.
• < 0: Failure.