AgoraRtcEngineKit Class Reference

Inherits from NSObject
Declared in AgoraRtcEngineKit.h

Overview

The AgoraRtcEngineKit class provides all methods invoked by your app.

Agora provides ensured quality of experience (QoE) for worldwide Internet-based voice and video communications through a virtual global network optimized for real-time web and mobile-to-mobile apps.

AgoraRtcEngineKit is the basic interface class of the SDK. Creating an AgoraRtcEngineKit object and then calling the methods of this object enables the use of the SDK’s communication functionality.

Core Service

+ sharedEngineWithAppId:delegate:

Creates an AgoraRtcEngineKit instance.

+ (instancetype _Nonnull)sharedEngineWithAppId:(NSString *_Nonnull)appId delegate:(id<AgoraRtcEngineDelegate> _Nullable)delegate

Parameters

appId

The App ID issued to you by Agora. See How to get the App ID. Only users in apps with the same App ID can join the same channel and communicate with each other. Use an App ID to create only one AgoraRtcEngineKit instance. To change your App ID, call destroy to destroy the current AgoraRtcEngineKit instance, and after destroy returns 0, call sharedEngineWithAppId to create an AgoraRtcEngineKit instance with the new App ID.

delegate

AgoraRtcEngineDelegate.

Return Value

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

    • -1(AgoraErrorCodeFailed): A general error occurs (no specified reason).
    • -2(AgoraErrorCodeInvalidArgument): No AgoraRtcEngineDelegate object is specified.
    • -7(AgoraErrorCodeNotInitialized): The SDK is not initialized.
    • -101(AgoraErrorCodeInvalidAppId): The App ID is invalid.

Discussion

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

Note:

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

Declared In

AgoraRtcEngineKit.h

+ sharedEngineWithConfig:delegate:

Creates an AgoraRtcEngineKit instance.

+ (instancetype _Nonnull)sharedEngineWithConfig:(AgoraRtcEngineConfig *_Nonnull)config delegate:(id<AgoraRtcEngineDelegate> _Nullable)delegate

Parameters

config

Configurations for the AgoraRtcEngineKit instance. For details, see AgoraRtcEngineConfig.

delegate

AgoraRtcEngineDelegate.

Return Value

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

    • -1(AgoraErrorCodeFailed): A general error occurs (no specified reason).
    • -2(AgoraErrorCodeInvalidArgument): No AgoraRtcEngineDelegate object is specified.
    • -7(AgoraErrorCodeNotInitialized): The SDK is not initialized.
    • -101(AgoraErrorCodeInvalidAppId): The App ID is invalid.

Discussion

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

Note:

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

Declared In

AgoraRtcEngineKit.h

+ destroy

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

+ (void)destroy

Discussion

Use this method for apps in which users occasionally make voice or video calls. When users do not make calls, you can free up resources for other operations. Once you call destroy to destroy the created AgoraRtcEngineKit instance, you cannot use any method or callback in the SDK any more. If you want to use the real-time communication functions again, you must call sharedEngineWithappId to create a new AgoraRtcEngineKit instance.

Note:

  • Because destroy is a synchronous method and the app cannot move on to another task until the execution completes, Agora suggests calling this method in a sub-thread to avoid congestion in the main thread. Besides, you cannot call destroy in any method or callback of the SDK. Otherwise, the SDK cannot release the resources occupied by the AgoraRtcEngineKit instance until the callbacks return results, which may result in a deadlock.
  • If you want to create a new AgoraRtcEngineKit instance after destroying the current one, ensure that you wait till the destroy method completes executing.

Declared In

AgoraRtcEngineKit.h

– setChannelProfile:

Sets the channel profile of the AgoraRtcEngineKit.

- (int)setChannelProfile:(AgoraChannelProfile)profile

Parameters

profile

The channel profile of the AgoraRtcEngineKit: AgoraChannelProfile.

Return Value

  • 0(AgoraErrorCodeNoError): Success.
  • < 0: Failure.

    • -2(AgoraErrorCodeInvalidArgument): The parameter is invalid.
    • -7(AgoraErrorCodeNotInitialized): The SDK is not initialized.

Discussion

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

Note:

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

Declared In

AgoraRtcEngineKit.h

– setClientRole:

Sets the role of the user in interactive live streaming.

- (int)setClientRole:(AgoraClientRole)role

Parameters

role

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

Return Value

  • 0(AgoraErrorCodeNoError): Success.
  • < 0: Failure.

    • -1(AgoraErrorCodeFailed): A general error occurs (no specified reason).
    • -2(AgoraErrorCodeInvalidArgument): The parameter is invalid.
    • -7(AgoraErrorCodeNotInitialized): The SDK is not initialized.
    • -5 (AgoraErrorCodeRefused): The request is rejected. In multichannel scenarios, if you have set any of the following in one channel, the SDK returns this error code when the user switches the user role to host in another channel:

      • Call joinChannelByToken with the options parameter and use the default settings publishLocalAudio = YES or publishLocalVideo = YES.
      • Call setClientRole to set the user role as host.
      • Call muteLocalAudioStream(NO) or muteLocalVideoStream(NO).

Discussion

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

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

Note: This method applies to the AgoraChannelProfileLiveBroadcasting profile only (when the profile parameter in setChannelProfile is set as AgoraChannelProfileLiveBroadcasting).

Declared In

AgoraRtcEngineKit.h

– setClientRole:options:

Sets the role of the user in interactive live streaming.

- (int)setClientRole:(AgoraClientRole)role options:(AgoraClientRoleOptions *_Nullable)options

Parameters

role

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

options

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

Return Value

  • 0(AgoraErrorCodeNoError): Success.
  • < 0: Failure.

    • -1(AgoraErrorCodeFailed): A general error occurs (no specified reason).
    • -2(AgoraErrorCodeInvalidArgument): The parameter is invalid.
    • -7(AgoraErrorCodeNotInitialized): The SDK is not initialized.
    • -5 (AgoraErrorCodeRefused): The request is rejected. In multichannel scenarios, if you have set any of the following in one channel, the SDK returns this error code when the user switches the user role to host in another channel:

      • Call joinChannelByToken with the options parameter and use the default settings publishLocalAudio = YES or publishLocalVideo = YES.
      • Call setClientRole to set the user role as host.
      • Call muteLocalAudioStream(NO) or muteLocalVideoStream(NO).

Availability

v3.2.0

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

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

Note

-This method applies to the AgoraChannelProfileLiveBroadcasting profile only (when the profile parameter in setChannelProfile is set as AgoraChannelProfileLiveBroadcasting). - The difference between this method and setClientRole1 is that this method can set the user level in addition to the user role.

  • The user role determines the permissions that the SDK grants to a user, such as permission to send local streams, receive remote streams, and push streams to a CDN address.
  • The user level determines the level of services that a user can enjoy within the permissions of the user’s role. For example, an audience member can choose to receive remote streams with low latency or ultra low latency. User level affects the pricing of services.

Declared In

AgoraRtcEngineKit.h

– joinChannelByToken:channelId:info:uid:joinSuccess:

Joins a channel with the user ID.

- (int)joinChannelByToken:(NSString *_Nullable)token channelId:(NSString *_Nonnull)channelId info:(NSString *_Nullable)info uid:(NSUInteger)uid joinSuccess:(void ( ^ _Nullable ) ( NSString *_Nonnull channel , NSUInteger uid , NSInteger elapsed ))joinSuccessBlock

Parameters

token

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

channelId

Unique channel name for the Agora RTC session in the string format. The string length must be less than 64 bytes. Supported character scopes are:

  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: “!”, “#”, “$”, “%”, “&”, “(”, “)”, “+”, “-”, “:”, “;”, “<”, “=”, “.”, “>”, “?”, “@”, “[”, “]”, “^”, “_”, “{”, “}”, “|”, “~”, “,”.
info

(Optional) Additional information about the channel. This parameter can be set to nil or contain channel related information. Other users in the channel do not receive this message.

uid

User ID. A 32-bit unsigned integer with a value ranging from 1 to (232-1). The uid must be unique. If a uid is not assigned (or set to 0), the SDK assigns and returns a uid in joinSuccessBlock. Your app must record and maintain the returned uid since the SDK does not do so.

joinSuccessBlock

Occurs when the local user joins a specified channel. If you implement both joinSuccessBlock and didJoinChannel, joinSuccessBlock takes higher priority than didJoinChannel. Agora recommends setting joinSuccessBlock as nil to use didJoinChannel.

Return Value

  • 0(AgoraErrorCodeNoError): Success.
  • < 0: Failure.

    • -2(AgoraErrorCodeInvalidArgument): The parameter is invalid.
    • -3(AgoraErrorCodeNotReady): The SDK fails to be initialized. You can try re-initializing the SDK.
    • -5(AgoraErrorCodeRefused): The request is rejected. This may be caused by the following:
    • -7(AgoraErrorCodeNotInitialized): The SDK is not initialized.

      • You have created an AgoraRtcChannel object with the same channel name.
      • You have joined and published a stream in a channel created by the AgoraRtcChannel object. When you join a channel created by AgoraRtcEngineKit, the SDK publishes the local audio and video streams to that channel by default. Because the SDK does not support publishing a local stream to more than one channel simultaneously, an error occurs in this occasion.
    • -7(AgoraErrorCodeNotInitialized): The SDK is not initialized before calling this method.

Discussion

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 even if they join the same channel.

You must call the leaveChannel method to exit the current call before entering another channel. This method call is asynchronous; therefore, you can call this method in the main user interface thread.

The SDK uses the iOS’s AVAudioSession shared object for audio sampling and playback. Using this object may affect the SDK’s audio functions.

If the joinChannelByToken method call succeeds, the SDK triggersjoinSuccessBlock. If you implement both joinSuccessBlock and didJoinChannel, joinSuccessBlock takes higher priority than didJoinChannel.

We recommend you set joinSuccessBlock as nil to use didJoinChannel.

A successful joinChannel method call triggers the following callbacks:

  • The local client: didJoinChannel
  • The remote client: didJoinedOfUid, if the user joining the channel is in the Communication profile, or is a host in the Live Broadcast profile.

Once the 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. If you do not want to subscribe to a specified stream or all remote streams, call the mute methods accordingly.

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.

Note:

  • A channel does not accept duplicate UIDs, such as two users with the same uid. If you set uid as 0, the system automatically assigns a uid. If you want to join the same channel on different devices, ensure that different uids are used for each device.
  • When joining a channel, the SDK calls setCategory(AVAudioSessionCategoryPlayAndRecord) to set AVAudioSession to PlayAndRecord mode. When AVAudioSession is set to PlayAndRecord mode, the sound played (for example a ringtone) is interrupted. The app should not set AVAudioSession to any other mode.

Declared In

AgoraRtcEngineKit.h

– joinChannelByToken:channelId:info:uid:options:

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

- (int)joinChannelByToken:(NSString *_Nullable)token channelId:(NSString *_Nonnull)channelId info:(NSString *_Nullable)info uid:(NSUInteger)uid options:(AgoraRtcChannelMediaOptions *_Nonnull)options

Parameters

token

The token generated at your server. For details, see Generate a token.

channelId

The unique channel name for the Agora RTC session in the string format. The string length must be less than 64 bytes. Supported character scopes are:

  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: “!”, “#”, “$”, “%”, “&”, “(”, “)”, “+”, “-”, “:”, “;”, “<”, “=”, “.”, “>”, “?”, “@”, “[”, “]”, “^”, “_”, “{”, “}”, “|”, “~”, “,”.
info

(Optional) Additional information about the channel. This parameter can be set to nil or contain channel related information. Other users in the channel do not receive this message.

uid

(Optional) User ID. A 32-bit unsigned integer with a value ranging from 1 to (232-1). The uid must be unique. If a uid is not assigned (or set to 0), the SDK assigns and returns a uid in the didJoinChannel callback. Your application must record and maintain the returned uid, because the SDK does not do so.

Note: The ID of each user in the channel should be unique. If you want to join the same channel from different devices, ensure that the user IDs in all devices are different.

options

The channel media options: AgoraRtcChannelMediaOptions.

Return Value

  • 0(AgoraErrorCodeNoError): Success.
  • < 0: Failure.

    • -2(AgoraErrorCodeInvalidArgument): The parameter is invalid.
    • -3(AgoraErrorCodeNotReady): The SDK fails to be initialized. You can try re-initializing the SDK.
    • -5(AgoraErrorCodeRefused): The request is rejected. This may be caused by the following:

      • You have created an AgoraRtcChannel object with the same channel name.
      • You have joined and published a stream in a channel created by the AgoraRtcChannel object. When you join a channel created by AgoraRtcEngineKit, the SDK publishes the local audio and video streams to that channel by default. Because the SDK does not support publishing a local stream to more than one channel simultaneously, an error occurs in this occasion.
    • -7(AgoraErrorCodeNotInitialized): The SDK is not initialized before calling this method.

Availability

v3.3.0

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

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

A successful joinChannelByToken method call triggers the following callbacks:

  • The local client: didJoinChannel
  • The remote client: didJoinedOfUid, if the user joining the channel is in the Communication profile, or is a host in the Live Broadcast profile.

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

Note

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

Declared In

AgoraRtcEngineKit.h

– joinChannelByUserAccount:token:channelId:joinSuccess:

Joins the channel with a user account.

- (int)joinChannelByUserAccount:(NSString *_Nonnull)userAccount token:(NSString *_Nullable)token channelId:(NSString *_Nonnull)channelId joinSuccess:(void ( ^ _Nullable ) ( NSString *_Nonnull channel , NSUInteger uid , NSInteger elapsed ))joinSuccessBlock

Parameters

userAccount

The user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as nil. Supported character scopes are:

  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: “!”, “#”, “$”, “%”, “&”, “(”, “)”, “+”, “-”, “:”, “;”, “<”, “=”, “.”, “>”, “?”, “@”, “[”, “]”, “^”, “_”, “{”, “}”, “|”, “~”, “,”.
token

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

channelId

The channel name. The maximum length of this parameter is 64 bytes. Supported character scopes are:

  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: “!”, “#”, “$”, “%”, “&”, “(”, “)”, “+”, “-”, “:”, “;”, “<”, “=”, “.”, “>”, “?”, “@”, “[”, “]”, “^”, “_”, “{”, “}”, “|”, “~”, “,”.
joinSuccessBlock

Occurs when the local user joins a specified channel. If you implement both joinSuccessBlock and didJoinChannel, joinSuccessBlock takes higher priority than didJoinChannel. Agora recommends setting joinSuccessBlock as nil to use didJoinChannel.

Return Value

  • 0: Success.
  • < 0: Failure.

    • AgoraErrorCodeInvalidArgument(-2)
    • AgoraErrorCodeNotReady(-3)
    • AgoraErrorCodeRefused(-5)
    • AgoraErrorCodeSDKNotInitialized(-7)

Discussion

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

Once the 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. If you do not want to subscribe to a specified stream or all remote streams, call the mute methods accordingly.

Note

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

Declared In

AgoraRtcEngineKit.h

– joinChannelByUserAccount:token:channelId:options:

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

- (int)joinChannelByUserAccount:(NSString *_Nonnull)userAccount token:(NSString *_Nullable)token channelId:(NSString *_Nonnull)channelId options:(AgoraRtcChannelMediaOptions *_Nonnull)options

Parameters

userAccount

The user account. The maximum length of this parameter is 255 bytes. Ensure that the user account is unique and do not set it as nil. Supported character scopes are:

  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: “!”, “#”, “$”, “%”, “&”, “(”, “)”, “+”, “-”, “:”, “;”, “<”, “=”, “.”, “>”, “?”, “@”, “[”, “]”, “^”, “_”, “{”, “}”, “|”, “~”, “,”.
token

The token generated at your server. For details, see Generate a token.

channelId

The channel name. The maximum length of this parameter is 64 bytes. Supported character scopes are:

  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: “!”, “#”, “$”, “%”, “&”, “(”, “)”, “+”, “-”, “:”, “;”, “<”, “=”, “.”, “>”, “?”, “@”, “[”, “]”, “^”, “_”, “{”, “}”, “|”, “~”, “,”.
options

The channel media options: AgoraRtcChannelMediaOptions.

Return Value

  • 0: Success.
  • < 0: Failure.

    • AgoraErrorCodeInvalidArgument(-2)
    • AgoraErrorCodeNotReady(-3)
    • AgoraErrorCodeRefused(-5)
    • AgoraErrorCodeSDKNotInitialized(-7)

Availability

v3.3.0

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

Note

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

Declared In

AgoraRtcEngineKit.h

– registerLocalUserAccount:appId:

Registers a user account.

- (int)registerLocalUserAccount:(NSString *_Nonnull)userAccount appId:(NSString *_Nonnull)appId

Parameters

userAccount

The user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as nil. Supported character scopes are:

  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: “!”, “#”, “$”, “%”, “&”, “(”, “)”, “+”, “-”, “:”, “;”, “<”, “=”, “.”, “>”, “?”, “@”, “[”, “]”, “^”, “_”, “{”, “}”, “|”, “~”, “,”.
appId

The App ID of your project.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

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

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

Note:

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

Declared In

AgoraRtcEngineKit.h

– getUserInfoByUserAccount:withError:

Gets the user information by passing in the user account.

- (AgoraUserInfo *_Nullable)getUserInfoByUserAccount:(NSString *_Nonnull)userAccount withError:(AgoraErrorCode *_Nullable)error

Parameters

userAccount

The user account of the user. Ensure that you set this parameter.

error

The pointer to AgoraErrorCode. It can be set as nil.

Return Value

An AgoraUserInfo object that contains the user account and user ID of the user.

Discussion

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

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

Declared In

AgoraRtcEngineKit.h

– getUserInfoByUid:withError:

Gets the user information by passing in the user ID.

- (AgoraUserInfo *_Nullable)getUserInfoByUid:(NSUInteger)uid withError:(AgoraErrorCode *_Nullable)error

Parameters

uid

The user ID of the user. Ensure that you set this parameter.

error

The pointer to AgoraErrorCode. It can be set as nil.

Return Value

An AgoraUserInfo object that contains the user account and user ID of the user.

Discussion

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

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

Declared In

AgoraRtcEngineKit.h

– switchChannelByToken:channelId:joinSuccess:

Switches to a different channel.

- (int)switchChannelByToken:(NSString *_Nullable)token channelId:(NSString *_Nonnull)channelId joinSuccess:(void ( ^ _Nullable ) ( NSString *_Nonnull channel , NSUInteger uid , NSInteger elapsed ))joinSuccessBlock

Parameters

token

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

channelId

Unique channel name for the Agora RTC session in the string format. The string length must be less than 64 bytes. Supported character scopes are:

  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: “!”, “#”, “$”, “%”, “&”, “(”, “)”, “+”, “-”, “:”, “;”, “<”, “=”, “.”, “>”, “?”, “@”, “[”, “]”, “^”, “_”, “{”, “}”, “|”, “~”, “,”.
joinSuccessBlock

Returns that the user joins the specified channel. Same as didJoinChannel. If joinSuccessBlock is nil, the SDK triggers the didJoinChannel callback.

Return Value

  • 0(AgoraErrorCodeNoError): Success.
  • < 0: Failure.

    • -1(AgoraErrorCodeFailed): A general error occurs (no specified reason).
    • -2(AgoraErrorCodeInvalidArgument): The parameter is invalid.
    • -5(AgoraErrorCodeRefused): The request is rejected, probably because the user is not an audience.
    • -7(AgoraErrorCodeNotInitialized): The SDK is not initialized.
    • -102(AgoraErrorCodeInvalidChannelId): The channel ID is invalid.
    • -113(AgoraErrorCodeNotInChannel): The user is not in the channel.

Discussion

This method allows the audience of the interactive live streaming channel to switch to a different channel.

After the user successfully switches to another channel, the didLeaveChannelWithStats and didJoinChannel callbacks are triggered to indicate that the user has left the original channel and joined a new one.

Once the user switches to another channel, the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. If you do not want to subscribe to a specified stream or all remote streams, call the mute methods accordingly.

Note: This method applies to the audience role in the interactive live streaming channel only.

Declared In

AgoraRtcEngineKit.h

– switchChannelByToken:channelId:options:

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

- (int)switchChannelByToken:(NSString *_Nullable)token channelId:(NSString *_Nonnull)channelId options:(AgoraRtcChannelMediaOptions *_Nonnull)options

Parameters

token

The token generated at your server. For details, see Generate a token.

channelId

The unique channel name for the Agora RTC session in the string format. The string length must be less than 64 bytes. Supported character scopes are:

  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: “!”, “#”, “$”, “%”, “&”, “(”, “)”, “+”, “-”, “:”, “;”, “<”, “=”, “.”, “>”, “?”, “@”, “[”, “]”, “^”, “_”, “{”, “}”, “|”, “~”, “,”.
options

The channel media options: AgoraRtcChannelMediaOptions.

Return Value

  • 0(AgoraErrorCodeNoError): Success.
  • < 0: Failure.

    • -1(AgoraErrorCodeFailed): A general error occurs (no specified reason).
    • -2(AgoraErrorCodeInvalidArgument): The parameter is invalid.
    • -5(AgoraErrorCodeRefused): The request is rejected, probably because the user is not an audience.
    • -7(AgoraErrorCodeNotInitialized): The SDK is not initialized.
    • -102(AgoraErrorCodeInvalidChannelId): The channel ID is invalid.
    • -113(AgoraErrorCodeNotInChannel): The user is not in the channel.

Availability

v3.3.0

This method allows the audience of the interactive live streaming channel to switch to a different channel.

After the user successfully switches to another channel, the didLeaveChannelWithStats and didJoinChannel callbacks are triggered to indicate that the user has left the original channel and joined a new one.

Note

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

Declared In

AgoraRtcEngineKit.h

– leaveChannel:

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

- (int)leaveChannel:(void ( ^ _Nullable ) ( AgoraChannelStats *_Nonnull stat ))leaveChannelBlock

Parameters

leaveChannelBlock

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

Return Value

  • 0(AgoraErrorCodeNoError): Success.
  • < 0: Failure.

    • -1(AgoraErrorCodeFailed): A general error occurs (no specified reason).
    • -2(AgoraErrorCodeInvalidArgument): The parameter is invalid.
    • -7(AgoraErrorCodeNotInitialized): The SDK is not initialized.

Discussion

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

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

This method call is asynchronous, and the user has not exited the channel when the method call returns.

A successful leaveChannel method call triggers the following callbacks:

Note:

  • If you call destroy immediately after leaveChannel, the leaveChannel process interrupts, and the SDK does not trigger the didLeaveChannelWithStats callback.
  • If you call this method during CDN live streaming, the SDK triggers the removePublishStreamUrl method.
  • When you call this method, the SDK deactivates the audio session on iOS by default, and may affect other apps. If you do not want this default behavior, use setAudioSessionOperationRestriction to set AgoraAudioSessionOperationRestrictionDeactivateSession so that when you call the leaveChannel method, the SDK does not deactivate the audio session.

Declared In

AgoraRtcEngineKit.h

– renewToken:

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

- (int)renewToken:(NSString *_Nonnull)token

Parameters

token

The new token.

Return Value

  • 0(AgoraErrorCodeNoError): Success.
  • < 0: Failure.

    • -1(AgoraErrorCodeFailed): A general error occurs (no specified reason).
    • -2(AgoraErrorCodeInvalidArgument): The parameter is invalid.
    • -7(AgoraErrorCodeNotInitialized): The SDK is not initialized.

Discussion

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

Note:

Agora recommends using the rtcEngineRequestToken callback to report the AgoraErrorCodeTokenExpired(-109) error, not using the didOccurError callback.

The app should call this method to get the token. Failure to do so results in the SDK disconnecting from the server.

Declared In

AgoraRtcEngineKit.h

– getConnectionState

Gets the connection state of the app.

- (AgoraConnectionStateType)getConnectionState

Return Value

The connection state, see AgoraConnectionStateType.

Discussion

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

Declared In

AgoraRtcEngineKit.h

– startChannelMediaRelay:

Starts to relay media streams across channels.

- (int)startChannelMediaRelay:(AgoraChannelMediaRelayConfiguration *_Nonnull)config

Parameters

config

The configuration of the media stream relay: AgoraChannelMediaRelayConfiguration.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

After a successful method call, the SDK triggers the channelMediaRelayStateDidChange and didReceiveChannelMediaRelayEvent callbacks, and these callbacks return the state and events of the media stream relay.

  • If the channelMediaRelayStateDidChange callback returns AgoraChannelMediaRelayStateRunning(2) and AgoraChannelMediaRelayStateIdle(0), and the didReceiveChannelMediaRelayEvent callback returns AgoraChannelMediaRelayEventSentToDestinationChannel(4), the SDK starts relaying media streams between the original and the destination channel.
  • If the channelMediaRelayStateDidChange callback returns AgoraChannelMediaRelayStateFailure(3), an exception occurs during the media stream relay.

Note

  • Call this method after the joinChannel method.
  • This method takes effect only when you are a host in the interactive live streaming channel.
  • After a successful method call, if you want to call this method again, ensure that you call the stopChannelMediaRelay method to quit the current relay.
  • Contact support@agora.io before implementing this function.
  • We do not support string user accounts in this API.

Declared In

AgoraRtcEngineKit.h

– updateChannelMediaRelay:

Updates the channels for media stream relay.

- (int)updateChannelMediaRelay:(AgoraChannelMediaRelayConfiguration *_Nonnull)config

Parameters

config

The media stream relay configuration: AgoraChannelMediaRelayConfiguration.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

After the channel 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.

Note

  • Call this method after successfully calling the startChannelMediaRelay method and receiving the channelMediaRelayStateDidChange (AgoraChannelMediaRelayStateRunning, AgoraChannelMediaRelayErrorNone) callback; otherwise, this method call fails.
  • This method supports adding at most four destination channels in the relay. If there are already four destination channels in the relay, remove the unnecessary ones with the removeDestinationInfoForChannelName method in channelMediaRelayConfiguration before calling this method.

Declared In

AgoraRtcEngineKit.h

– pauseAllChannelMediaRelay

Pauses the media stream relay to all destination channels.

- (int)pauseAllChannelMediaRelay

Return Value

  • 0: Success.
  • < 0: Failure.

Availability

v3.5.1

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.

Discussion

Note: Call this method after the startChannelMediaRelay method.

Declared In

AgoraRtcEngineKit.h

– resumeAllChannelMediaRelay

Resumes the media stream relay to all destination channels.

- (int)resumeAllChannelMediaRelay

Return Value

  • 0: Success.
  • < 0: Failure.

Availability

v3.5.1

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.

Discussion

Note: Call this method after the pauseAllChannelMediaRelay method.

Declared In

AgoraRtcEngineKit.h

– stopChannelMediaRelay

Stops the media stream relay.

- (int)stopChannelMediaRelay

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Once the relay stops, the host quits all the destination channels.

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

Note: If the method call fails, the SDK triggers the channelMediaRelayStateDidChange callback with the AgoraChannelMediaRelayErrorServerNoResponse(2) or AgoraChannelMediaRelayEventUpdateDestinationChannelRefused(8) state code. You can leave the channel by calling the leaveChannel method, and the media stream relay automatically stops.

Declared In

AgoraRtcEngineKit.h

– setCloudProxy:

Sets the Agora cloud proxy service.

- (int)setCloudProxy:(AgoraCloudProxyType)proxyType

Parameters

proxyType

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

Return Value

  • 0: Success.
  • < 0: Failure.

    • -2(AgoraErrorCodeInvalidArgument): The parameter is invalid.
    • -7(AgoraErrorCodeNotInitialized): The SDK is not initialized.

Availability

v3.3.0

When the user’s firewall restricts the IP address and port, refer to Use Cloud Proxy to add the specific IP addresses and ports to the firewall whitelist; then, call this method to enable the cloud proxy and set the cloud proxy type with the proxyType parameter as AgoraUdpProxy(1), which is the cloud proxy for the UDP protocol.

After a successfully cloud proxy connection, the SDK triggers the connectionChangedToState(AgoraConnectionStateConnecting, AgoraConnectionChangedSettingProxyServer) callback.

To disable the cloud proxy that has been set, call setCloudProxy(AgoraNoneProxy). To change the cloud proxy type that has been set, call setCloudProxy(AgoraNoneProxy) first, and then call setCloudProxy, and pass the value that you expect in proxyType.

Note

  • Agora recommends that you call this method before joining the channel or after leaving the channel.
  • For the SDK v3.3.x, the services for pushing streams to CDN and co-hosting across channels are not available when you use the cloud proxy for the UDP protocol. For the SDK v3.4.0 and later, the services for pushing streams to CDN and co-hosting across channels are not available when the user is in a network environment with a firewall and uses the cloud proxy for the UDP protocol.

Declared In

AgoraRtcEngineKit.h

Core Audio

– enableAudio

Enables the audio module.

- (int)enableAudio

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

The audio module is enabled by default.

Note:

  • This method affects the audio module and can be called after the leaveChannel method. You can call this method either before or after joining a channel.
  • This method enables the audio module and takes some time to take effect. Agora recommends using the following API methods to control the audio engine modules separately:

Declared In

AgoraRtcEngineKit.h

– disableAudio

Disables the audio module.

- (int)disableAudio

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Note:

  • This method affects the audio module and can be called after the leaveChannel method. You can call this method either before or after joining a channel.
  • This method disables the audio module and takes some time to take effect. Agora recommends using the following API methods to control the audio engine modules separately:

Declared In

AgoraRtcEngineKit.h

– setAudioProfile:scenario:

Sets the audio parameters and application scenarios.

- (int)setAudioProfile:(AgoraAudioProfile)profile scenario:(AgoraAudioScenario)scenario

Parameters

profile

Sets the sample rate, bitrate, encoding mode, and the number of channels. See AgoraAudioProfile.

scenario

Sets the audio application scenario. See AgoraAudioScenario. Under different audio scenarios, the device uses different volume types. For details, see What is the difference between the in-call volume and the media volume?.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Note:

  • You must call this method before the joinChannelByToken method.
  • In the Communication profile, you can set the profile but not the scenario.
  • In the Communication and interactive live streaming profiles, the bitrates may be different from your settings due to network self-adaptation.
  • In scenarios requiring high-quality audio, we recommend setting profile as AgoraAudioProfileMusicHighQuality(4) and scenario as AgoraAudioScenarioGameStreaming(3). For example, for music education scenarios.

Declared In

AgoraRtcEngineKit.h

– adjustRecordingSignalVolume:

Adjusts the volume of the signal captured by the microphone.

- (int)adjustRecordingSignalVolume:(NSInteger)volume

Parameters

volume

The volume of the signal captured by the microphone. The value ranges between 0 and 400, including the following:

  • 0: Mute.
  • 100: (Default) Original volume.
  • 400: Four times the original volume with signal-clipping protection.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

Declared In

AgoraRtcEngineKit.h

– adjustLoopbackRecordingSignalVolume:

Adjusts the volume of the signal captured by the sound card. (macOS only)

- (int)adjustLoopbackRecordingSignalVolume:(NSInteger)volume

Parameters

volume

The volume of the signal captured by the sound card. The value ranges between 0 and 400, including the following:

  • 0: Mute.
  • 100: (Default) Original volume.
  • 400: Four times the original volume with signal-clipping protection.

Return Value

  • 0: Success.
  • < 0: Failure.

Availability

v3.4.0

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.

Declared In

AgoraRtcEngineKit.h

– adjustPlaybackSignalVolume:

Adjusts the playback signal volume of all remote users.

- (int)adjustPlaybackSignalVolume:(NSInteger)volume

Parameters

volume

The playback volume. The value ranges between 0 and 400, including the following:

  • 0: Mute.
  • 100: (Default) Original volume.
  • 400: Four times the original volume with signal-clipping protection.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

Note

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

Declared In

AgoraRtcEngineKit.h

– enableAudioVolumeIndication:smooth:report_vad:

Enables the reporting of users' volume indication.

- (int)enableAudioVolumeIndication:(NSInteger)interval smooth:(NSInteger)smooth report_vad:(BOOL)report_vad

Parameters

interval

Sets the time interval between two consecutive volume indications:

  • ≤ 0: Disables the volume indication.
  • > 0: The time interval (ms) between two consecutive volume indications. Agora recommends setting interval ≥ 200 ms.
smooth

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

report_vad
  • 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.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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.

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

Declared In

AgoraRtcEngineKit.h

– enableLocalAudio:

Enables/Disables the local audio capture.

- (int)enableLocalAudio:(BOOL)enabled

Parameters

enabled
  • YES: (Default) Enable the local audio module, that is, to start local audio capturing and processing.
  • NO: Disable the local audio module, that is, to stop local audio capturing and processing.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

When an app joins a channel, the audio module is enabled by default. This method disables or re-enables the local audio capture, that is, to stop or restart local audio capturing and processing.

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

Once the local audio function is disabled or re-enabled, the SDK triggers the localAudioStateChange callback, which reports AgoraAudioLocalStateStopped(0) or AgoraAudioLocalStateRecording(1).

Note:

  • This method can be called either before or after you join a channel. Calling it before you join a channel can set the device state only, and it takes effect immediately after you join the channel.
  • This method is different from the muteLocalAudioStream method:

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

Declared In

AgoraRtcEngineKit.h

– muteLocalAudioStream:

Stops or resumes publishing the local audio stream.

- (int)muteLocalAudioStream:(BOOL)mute

Parameters

mute

Sets whether to stop publishing the local audio stream.

  • YES: Stop publishing the local audio stream.
  • NO: Resume publishing the local audio stream.

Return Value

  • 0: Success.
  • < 0: Failure.

  • -5 (AgoraErrorCodeRefused): The request is rejected.

Discussion

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

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

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

Note:

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

Declared In

AgoraRtcEngineKit.h

– muteRemoteAudioStream:mute:

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

- (int)muteRemoteAudioStream:(NSUInteger)uid mute:(BOOL)mute

Parameters

uid

The user ID of the specified remote user.

mute

Sets whether to stop subscribing to the audio stream of a specified user.

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

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Note:

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

Declared In

AgoraRtcEngineKit.h

– muteAllRemoteAudioStreams:

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

- (int)muteAllRemoteAudioStreams:(BOOL)mute

Parameters

mute

Sets whether to stop subscribing to the audio streams of all remote users.

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

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

Note

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

Declared In

AgoraRtcEngineKit.h

– adjustUserPlaybackSignalVolume:volume:

Adjust the playback signal volume of a specified remote user.

- (int)adjustUserPlaybackSignalVolume:(NSUInteger)uid volume:(int)volume

Parameters

uid

The ID of the remote user.

volume

The playback volume of the specified remote user. The value ranges between 0 and 400, including the following:

  • 0: Mute.
  • 100: (Default) Original volume.
  • 400: Four times the original volume with signal-clipping protection.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Since v3.0.0.

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

Note

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

Declared In

AgoraRtcEngineKit.h

Core Video

– enableVideo

Enables the video module.

- (int)enableVideo

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

A successful enableVideo method call triggers the didVideoEnabled(YES) callback on the remote client.

To disable the video, call the disableVideo method.

Note:

  • This method affects the internal engine and can be called after the leaveChannel method.
  • This method resets the internal engine and takes some time to take effect. Agora recommends using the following API methods to control the video engine modules separately:

Declared In

AgoraRtcEngineKit.h

– disableVideo

Disables the video module.

- (int)disableVideo

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

You can call this method before entering a channel or during a call. If you call this method before entering a channel, the service starts in the audio mode. If you call this method during a video call, the video mode switches to the audio mode. To enable the video module, call the enableVideo method.

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

Note:

  • This method affects the internal engine and can be called after the leaveChannel method.
  • This method resets the internal engine and takes some time to take effect. Agora recommends using the following API methods to control the video engine modules separately:

Declared In

AgoraRtcEngineKit.h

– setVideoEncoderConfiguration:

Sets the video encoder configuration.

- (int)setVideoEncoderConfiguration:(AgoraVideoEncoderConfiguration *_Nonnull)config

Parameters

config

Video encoder configuration: AgoraVideoEncoderConfiguration

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

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

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

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

Note:

From v2.3.0, the following API methods are deprecated:

Declared In

AgoraRtcEngineKit.h

– setupLocalVideo:

Initializes the local video view.

- (int)setupLocalVideo:(AgoraRtcVideoCanvas *_Nullable)local

Parameters

local

Sets the local video view and settings. See AgoraRtcVideoCanvas.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

Call this method to bind the local video stream to a video view and to set the rendering and mirror modes of the video view. To unbind the view, set the view in AgoraRtcVideoCanvas to nil.

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

Note

To update the rendering or mirror mode of the local video view during a call, use setLocalRenderMode.

Declared In

AgoraRtcEngineKit.h

– setupRemoteVideo:

Initializes the video view of a remote user.

- (int)setupRemoteVideo:(AgoraRtcVideoCanvas *_Nonnull)remote

Parameters

remote

Sets the remote video view and settings. See AgoraRtcVideoCanvas.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

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

The app specifies the uid of the remote video in this method call before the user joins a channel.

If the remote uid is unknown to the app, set it after the app receives the userJoinedBlock callback.

If the Video Recording function is enabled, the Video Recording Service joins the channel as a dummy client, causing other clients to also receive the didJoinedOfUid callback. Do not bind the dummy client to the app view because the dummy client does not send any video streams. If your app does not recognize the dummy client, bind the remote user to the view when the SDK triggers the firstRemoteVideoDecodedOfUid callback.

To unbind the remote user from the view, set the view in AgoraRtcVideoCanvas as nil. Once the remote user leaves the channel, the SDK unbinds the remote user.

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

Declared In

AgoraRtcEngineKit.h

– setLocalRenderMode:mirrorMode:

Updates the display mode of the local video view.

- (int)setLocalRenderMode:(AgoraVideoRenderMode)renderMode mirrorMode:(AgoraVideoMirrorMode)mirrorMode

Parameters

renderMode

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

mirrorMode

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

Note

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

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Since v3.0.0.

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

Note

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

Declared In

AgoraRtcEngineKit.h

– setRemoteRenderMode:renderMode:mirrorMode:

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

- (int)setRemoteRenderMode:(NSUInteger)uid renderMode:(AgoraVideoRenderMode)renderMode mirrorMode:(AgoraVideoMirrorMode)mirrorMode

Parameters

uid

The ID of the remote user.

renderMode

The rendering mode of the remote video view. See AgoraVideoRenderMode.

mirrorMode

The mirror mode of the remote video view. See AgoraVideoMirrorMode.

Note

The SDK disables the mirror mode by default.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Since v3.0.0.

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

Note

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

Declared In

AgoraRtcEngineKit.h

– startPreview

Starts the local video preview before joining a channel.

- (int)startPreview

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

By default, the local preview enables the mirror mode.

Before calling this method, you must:

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

Note:

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

Declared In

AgoraRtcEngineKit.h

– stopPreview

Stops the local video preview.

- (int)stopPreview

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

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

Declared In

AgoraRtcEngineKit.h

– enableLocalVideo:

Disables the local video.

- (int)enableLocalVideo:(BOOL)enabled

Parameters

enabled

Sets whether to enable/disable the local video, including the capturer, renderer, and sender:

  • YES: (Default) Enable the local video.
  • NO: Disable the local video. Once the local video is disabled, the remote users can no longer receive the video stream of this user, while this user can still receive the video streams of other remote users.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

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

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

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

Note:

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

Declared In

AgoraRtcEngineKit.h

– muteLocalVideoStream:

Stops or resumes publishing the local video stream.

- (int)muteLocalVideoStream:(BOOL)mute

Parameters

mute

Sets whether to stop publishing the local video stream.

  • YES: Stop publishing the local video stream.
  • NO: Resume publishing the local video stream.

Return Value

  • 0: Success.
  • < 0: Failure.

    • -5 (AgoraErrorCodeRefused): The request is rejected.

Discussion

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

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

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

Note:

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

Declared In

AgoraRtcEngineKit.h

– muteAllRemoteVideoStreams:

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

- (int)muteAllRemoteVideoStreams:(BOOL)mute

Parameters

mute

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

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

Note

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

Declared In

AgoraRtcEngineKit.h

– muteRemoteVideoStream:mute:

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

- (int)muteRemoteVideoStream:(NSUInteger)uid mute:(BOOL)mute

Parameters

uid

The user ID of the specified remote user.

mute

Sets whether to stop subscribing to the video stream of a specified user.

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

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Note:

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

Declared In

AgoraRtcEngineKit.h

Video Pre-Process and Post-Process

– setBeautyEffectOptions:options:

Enables/Disables image enhancement and sets the options.

- (int)setBeautyEffectOptions:(BOOL)enable options:(AgoraBeautyOptions *_Nullable)options

Parameters

enable

Sets whether to enable image enhancement:

  • YES: Enable image enhancement.
  • NO: Disable image enhancement.
options

The image enhancement options, see AgoraBeautyOptions.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Note: Call this method after calling the enableVideo method.

Declared In

AgoraRtcEngineKit.h

– enableVirtualBackground:backData:

Enables/Disables the virtual background. (beta feature)

- (int)enableVirtualBackground:(BOOL)enable backData:(AgoraVirtualBackgroundSource *_Nullable)backData

Parameters

enable

Sets whether to enable the virtual background:

  • YES: Enable.
  • NO: Disable.
backData

The custom background image. See AgoraVirtualBackgroundSource.

Note: To adapt the resolution of the custom background image to the resolution of the SDK capturing video, the SDK scales and crops the custom background image while ensuring that the content of the custom background image is not distorted.

Return Value

  • 0: Success.
  • < 0: Failure.

Availability

Support for macOS as of v3.4.5 and iOS as of v3.5.0.

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

Note:

  • Before calling this method, ensure that you have integrated the AgoraVideoSegmentationExtension.framework (macOS) or AgoraVideoSegmentationExtension.xcframework(iOS) dynamic library into the project folder.
  • Call this method after enableVideo.
  • The virtual background feature does not support video in the Texture format or video obtained from custom video capture by the Push method.
  • This feature requires a high-performance device. Agora recommends that you use this feature on the following devices:

    • macOS: Devices with an i5 CPU and better
    • iOS: Devices with an A9 chip and better, as follows:

      • iPhone 6S and later
      • iPad Air (3rd generation) and later
      • iPad (5th generation) and later
      • iPad Pro (1st generation) and later
      • iPad mini (5th generation) and later

Declared In

AgoraRtcEngineKit.h

– enableRemoteSuperResolution:enabled:

Enables/Disables the super resolution feature for a remote user’s video. (beta feature)

- (int)enableRemoteSuperResolution:(NSUInteger)uid enabled:(BOOL)enabled

Parameters

uid

The user ID of the remote user.

enabled

Determines whether to enable super resolution for the remote user’s video:

  • YES: Enable super-resolution.
  • NO: Do not enable super resolution.

Return Value

  • 0: Success.
  • < 0: Failure.

    • -157(AgoraErrorCodeModuleNotFound): The dynamic library for super resolution is not integrated.

Availability

v3.5.1

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

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

Warnings

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

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

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

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

Notes

  • This method is for iOS only.
  • Before calling this method, ensure that you have integrated the AgoraSuperResolutionExtension.xcframework dynamic library into your project.
  • Because this method has certain system performance requirements, Agora recommends that you use the following iOS devices (iOS 12.0 or later) or better:

    • iPhone XR
    • iPhone XS
    • iPhone XS Max
    • iPhone 11
    • iPhone 11 Pro
    • iPhone 11 Pro Max
    • iPhone 12
    • iPhone 12 mini
    • iPhone 12 Pro
    • iPhone 12 Pro Max
    • iPhone 12 SE (2nd generation)
    • iPad Pro 11-inch (3rd generation)
    • iPad Pro 12.9-inch (3rd generation)
    • iPad Air (3rd generation)
    • iPad Air (4th generation)

Declared In

AgoraRtcEngineKit.h

Face Detection

– enableFaceDetection:

Enables/Disables face detection for the local user. (iOS only)

- (int)enableFaceDetection:(bool)enable

Parameters

enable

Determines whether to enable the face detection function for the local user:

  • YES: Enable face detection.
  • NO: Disable face detection.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Since: v3.0.1.

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

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

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

Declared In

AgoraRtcEngineKit.h

Audio Routing Controller

– setDefaultAudioRouteToSpeakerphone:

Sets the default audio route.

- (int)setDefaultAudioRouteToSpeakerphone:(BOOL)defaultToSpeaker

Parameters

defaultToSpeaker

Sets the default audio route as follows:

  • YES: Set to the speakerphone.
  • NO: Set to the earpiece.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

Note

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

Declared In

AgoraRtcEngineKit.h

– setEnableSpeakerphone:

Enables/Disables the audio route to the speakerphone.

- (int)setEnableSpeakerphone:(BOOL)enableSpeaker

Parameters

enableSpeaker

Sets whether to enable the speakerphone or earpiece:

  • YES: Enable the speakerphone. The audio route is the speakerphone.
  • NO: Disable the speakerphone. The audio route is the earpiece.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

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

Notes

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

Declared In

AgoraRtcEngineKit.h

– isSpeakerphoneEnabled

Checks whether the speakerphone is enabled. (iOS only.)

- (BOOL)isSpeakerphoneEnabled

Return Value

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

Discussion

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

Declared In

AgoraRtcEngineKit.h

In-ear Monitor

– enableInEarMonitoring:

Enables in-ear monitoring. (iOS only.)

- (int)enableInEarMonitoring:(BOOL)enabled

Parameters

enabled

Sets whether to enable/disable in-ear monitoring.

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

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

Note: Users must use wired earphones to hear their own voices.

Declared In

AgoraRtcEngineKit.h

– setInEarMonitoringVolume:

Sets the volume of the in-ear monitor. (iOS only.)

- (int)setInEarMonitoringVolume:(NSInteger)volume

Parameters

volume

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

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

Note: Users must use wired earphones to hear their own voices.

Declared In

AgoraRtcEngineKit.h

Set the Voice Effect

– setLocalVoicePitch:

Changes the voice pitch of the local speaker.

- (int)setLocalVoicePitch:(double)pitch

Parameters

pitch

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

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

Declared In

AgoraRtcEngineKit.h

– setLocalVoiceEqualizationOfBandFrequency:withGain:

Sets the local voice equalization effect.

- (int)setLocalVoiceEqualizationOfBandFrequency:(AgoraAudioEqualizationBandFrequency)bandFrequency withGain:(NSInteger)gain

Parameters

bandFrequency

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

gain

Sets the gain of each band (dB). The value ranges between -15 and 15. The default value is 0.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

Declared In

AgoraRtcEngineKit.h

– setLocalVoiceReverbOfType:withValue:

Sets the local voice reverberation.

- (int)setLocalVoiceReverbOfType:(AgoraAudioReverbType)reverbType withValue:(NSInteger)value

Parameters

reverbType

Sets the reverberation type. See AgoraAudioReverbType.

value

Sets the effect of the reverberation type. See AgoraAudioReverbType for the value range.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

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

Declared In

AgoraRtcEngineKit.h

– setVoiceBeautifierPreset:

Sets an SDK preset voice beautifier effect.

- (int)setVoiceBeautifierPreset:(AgoraVoiceBeautifierPreset)preset

Parameters

preset

The options for SDK preset voice beautifier effects: AgoraVoiceBeautifierPreset.

Return Value

  • 0: Success.
  • < 0: Failure.

Availability

v3.2.0

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

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

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

Note

Declared In

AgoraRtcEngineKit.h

– setVoiceBeautifierParameters:param1:param2:

Sets parameters for SDK preset voice beautifier effects.

- (int)setVoiceBeautifierParameters:(AgoraVoiceBeautifierPreset)preset param1:(int)param1 param2:(int)param2

Parameters

preset

The options for SDK preset voice beautifier effects:

  • AgoraSingingBeautifier: Singing beautifier effect.
param1

The gender characteristics options for the singing voice:

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

The reverberation effects options:

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

Return Value

  • 0: Success.
  • < 0: Failure.

Availability

v3.3.0

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

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

To achieve better audio effect quality, before you call this method, Agora recommends calling setAudioProfile, and setting the scenario parameter to AgoraAudioScenarioGameStreaming(3) and the profile parameter to AgoraAudioProfileMusicHighQuality(4) or AgoraAudioProfileMusicHighQualityStereo(5).

Note

Declared In

AgoraRtcEngineKit.h

– setAudioEffectPreset:

Sets an SDK preset audio effect.

- (int)setAudioEffectPreset:(AgoraAudioEffectPreset)preset

Parameters

preset

The options for SDK preset audio effects: AgoraAudioEffectPreset.

Return Value

  • 0: Success.
  • < 0: Failure.

Availability

v3.2.0

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

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

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

Note:

Declared In

AgoraRtcEngineKit.h

– setVoiceConversionPreset:

Sets an SDK preset voice conversion effect.

- (int)setVoiceConversionPreset:(AgoraVoiceConversionPreset)preset

Parameters

preset

The options for SDK preset voice conversion effects: AgoraVoiceConversionPreset.

Return Value

  • 0: Success.
  • < 0: Failure.

Availability

v3.3.1

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

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

To achieve better voice effect quality, Agora recommends calling setAudioProfile and setting the profile parameter to AgoraAudioProfileMusicHighQuality(4) or AgoraAudioProfileMusicHighQualityStereo(5) and the scenario parameter to AgoraAudioScenarioGameStreaming(3) before calling this method.

Note:

Declared In

AgoraRtcEngineKit.h

– setAudioEffectParameters:param1:param2:

Sets parameters for SDK preset audio effects.

- (int)setAudioEffectParameters:(AgoraAudioEffectPreset)preset param1:(int)param1 param2:(int)param2

Parameters

preset

The options for SDK preset audio effects:

  • 3D voice effect: AgoraRoomAcoustics3DVoice.

    • Call setAudioProfile and set the profile parameter 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.
  • Pitch correction effect: AgoraPitchCorrection. To achieve better audio effect quality, Agora recommends calling setAudioProfile and setting the profile parameter to AgoraAudioProfileMusicHighQuality(4) or AgoraAudioProfileMusicHighQualityStereo(5) before setting this enumerator.

param1
  • If you set preset to AgoraRoomAcoustics3DVoice, the param1 sets the cycle period of the 3D voice effect. The value range is [1,60] and the unit is a second. The default value is 10 seconds, indicating that the voice moves around you every 10 seconds.
  • If you set preset to AgoraPitchCorrection, 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 AgoraRoomAcoustics3DVoice, you need to set param2 to 0.
  • If you setpreset to AgoraPitchCorrection, 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#

Return Value

  • 0: Success.
  • < 0: Failure.

Availability

v3.2.0

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

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

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

Note:

Declared In

AgoraRtcEngineKit.h

Sound Position Indication

– enableSoundPositionIndication:

Enables/Disables stereo panning for remote users.

- (int)enableSoundPositionIndication:(BOOL)enabled

Parameters

enabled

Sets whether to enable stereo panning for remote users:

  • YES: enables stereo panning.
  • NO: disables stereo panning.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

If you need to use the setRemoteVoicePosition method, ensure that you call this method before joining a channel to enable stereo panning for remote users.

Declared In

AgoraRtcEngineKit.h

– setRemoteVoicePosition:pan:gain:

Sets the sound position and gain of a remote user.

- (int)setRemoteVoicePosition:(NSUInteger)uid pan:(double)pan gain:(double)gain

Parameters

uid

The ID of the remote user.

pan

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

  • 0.0: (default) the remote sound comes from the front.
  • -1.0: the remote sound comes from the left.
  • 1.0: the remote sound comes from the right.
gain

Gain of the remote user. The value ranges from 0.0 to 100.0. The default value is 100.0 (the original gain of the remote user). The smaller the value, the less the gain.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

Note:

  • Ensure that you call this method after joining a channel. For this method to work, enable stereo panning for remote users by calling enableSoundPositionIndication before joining a channel. This method requires hardware support.
  • For the best effect, we recommend using the following audio output devices:
    • (iOS) A wired headset.
    • (macOS) A stereo loudspeaker.

Declared In

AgoraRtcEngineKit.h

Music File Playback and Mixing

– startAudioMixing:loopback:replace:cycle:startPos:

Starts playing and mixing the music file.

- (int)startAudioMixing:(NSString *_Nonnull)filePath loopback:(BOOL)loopback replace:(BOOL)replace cycle:(NSInteger)cycle startPos:(NSInteger)startPos

Parameters

filePath

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

loopback

Whether to only play the music file on the local client:

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

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

  • YES: Replace. Users can only hear music.
  • NO: Do not replace. Users can hear both music and audio collected by the microphone.
cycle

The number of times the music file plays.

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

The playback position (ms) of the music file.

Return Value

  • 0: Success.
  • < 0: Failure.

Availability

v3.4.0

This method supports mixing or replacing local or online music file and audio collected by a microphone. After successfully playing the music file, the SDK triggers localAudioMixingStateDidChanged(AgoraAudioMixingStatePlaying, AgoraAudioMixingReasonStartedByUser). After completing playing the music file, the SDK triggers localAudioMixingStateDidChanged(AgoraAudioMixingStateStopped, AgoraAudioMixingReasonAllLoopsCompleted).

Note:

  • To avoid blocking, as of v3.4.5, this method changes from a synchronous call to an asynchronous call.
  • If you need to call startAudioMixing multiple times, ensure that the call interval is longer than 500 ms.
  • If the local music file does not exist, or if the SDK does not support the file format or cannot access the music file URL, the SDK returns AgoraWarningCodeAudioMixingOpenError(701).
  • For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support.

Declared In

AgoraRtcEngineKit.h

– setAudioMixingPlaybackSpeed:

Sets the playback speed of the current music file.

- (int)setAudioMixingPlaybackSpeed:(int)speed

Parameters

speed

The playback speed. Agora recommends that you limit this value to between 50 and 400, defined as follows:

  • 50: Half the original speed.
  • 100: The original speed.
  • 400: 4 times the original speed.

Return Value

  • 0: Success.
  • < 0: Failure.

Availability

v3.5.1

Discussion

Note: Call this method after calling startAudioMixing and receiving the localAudioMixingStateDidChanged (AgoraAudioMixingStatePlaying) callback.

Declared In

AgoraRtcEngineKit.h

– stopAudioMixing

Stops audio mixing.

- (int)stopAudioMixing

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Call this method when you are in a channel.

Declared In

AgoraRtcEngineKit.h

– pauseAudioMixing

Pauses audio mixing.

- (int)pauseAudioMixing

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Call this method when you are in a channel.

Declared In

AgoraRtcEngineKit.h

– resumeAudioMixing

Resumes audio mixing.

- (int)resumeAudioMixing

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Call this method when you are in a channel.

Declared In

AgoraRtcEngineKit.h

– selectAudioTrack:

Specifies the playback track of the current music file.

- (int)selectAudioTrack:(NSInteger)index

Parameters

index

The specified playback track. This parameter must be less than or equal to the return value of getAudioTrackCount.

Return Value

  • 0: Success.
  • < 0: Failure.

Availability

v3.5.1

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

Notes

Declared In

AgoraRtcEngineKit.h

– getAudioTrackCount

Gets the audio track index of the current music file.

- (int)getAudioTrackCount

Return Value

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

Availability

v3.5.1

Notes

Declared In

AgoraRtcEngineKit.h

– setAudioMixingDualMonoMode:

Sets the channel mode of the current music file.

- (int)setAudioMixingDualMonoMode:(AgoraAudioMixingDualMonoMode)mode

Parameters

mode

The channel mode. See AgoraAudioMixingDualMonoMode.

Return Value

  • 0: Success.
  • < 0: Failure.

Availability

v3.5.1

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

Notes

Declared In

AgoraRtcEngineKit.h

– adjustAudioMixingVolume:

Adjusts the volume of audio mixing.

- (int)adjustAudioMixingVolume:(NSInteger)volume

Parameters

volume

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

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Ensure that this method is called after startAudioMixing.

Note:

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

Declared In

AgoraRtcEngineKit.h

– adjustAudioMixingPlayoutVolume:

Adjusts the volume of audio mixing for local playback.

- (int)adjustAudioMixingPlayoutVolume:(NSInteger)volume

Parameters

volume

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

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Ensure that this method is called after startAudioMixing.

Declared In

AgoraRtcEngineKit.h

– adjustAudioMixingPublishVolume:

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

- (int)adjustAudioMixingPublishVolume:(NSInteger)volume

Parameters

volume

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

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Ensure that this method is called after startAudioMixing.

Declared In

AgoraRtcEngineKit.h

– getAudioMixingPublishVolume

Gets the audio mixing volume for publishing.

- (int)getAudioMixingPublishVolume

Return Value

  • ≥ 0: The audio mixing volume for publishing, if this method call is successful. The value ranges between 0 to 100.
  • < 0: Failure.

Discussion

This method helps troubleshoot audio volume related issues.

Note: Call this method after calling startAudioMixing and receiving the localAudioMixingStateDidChanged(AgoraAudioMixingStatePlaying) callback.

Declared In

AgoraRtcEngineKit.h

– getAudioMixingPlayoutVolume

Gets the audio mixing volume for local playback.

- (int)getAudioMixingPlayoutVolume

Return Value

  • ≥ 0: The audio mixing volume for local playback, if this method call is successful. The value ranges between 0 to 100.
  • < 0: Failure.

Discussion

This method helps troubleshoot audio volume related issues.

Note: Call this method after calling startAudioMixing and receiving the localAudioMixingStateDidChanged(AgoraAudioMixingStatePlaying) callback.

Declared In

AgoraRtcEngineKit.h

– getAudioMixingCurrentPosition

Gets the playback position (ms) of the audio mixing file.

- (int)getAudioMixingCurrentPosition

Return Value

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

  • < 0: Failure.

Discussion

Note:

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

Declared In

AgoraRtcEngineKit.h

– setAudioMixingPosition:

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

- (int)setAudioMixingPosition:(NSInteger)pos

Parameters

pos

The playback starting position (ms) of the audio mixing file.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Ensure that this method is called after startAudioMixing.

Declared In

AgoraRtcEngineKit.h

– setAudioMixingPitch:

Sets the pitch of the local music file.

- (int)setAudioMixingPitch:(NSInteger)pitch

Parameters

pitch

Sets the pitch of the local music file by chromatic scale. The default value is 0, which means keeping the original pitch. The value ranges from -12 to 12, and the pitch value between consecutive values is a chromatic value. The greater the absolute value of this parameter, the higher or lower the pitch of the local music file.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Since: v3.0.1.

When a local music file is mixed with a local human voice, call this method to set the pitch of the local music file only.

Note: Call this method after calling startAudioMixing.

Declared In

AgoraRtcEngineKit.h

Audio Effect File Playback

– getEffectsVolume

Gets the volume of the audio effects.

- (double)getEffectsVolume

Return Value

  • ≥ 0: Volume of the audio effects, if this method call is successful.

  • < 0: Failure.

Discussion

Ensure that this method is called after playEffect.

The value ranges between 0.0 and 100.0.

Declared In

AgoraRtcEngineKit.h

– setEffectsVolume:

Sets the volume of the audio effects.

- (int)setEffectsVolume:(double)volume

Parameters

volume

Volume of the audio effects. The value ranges between 0.0 and 100.0 (default).

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Ensure that this method is called after playEffect.

Declared In

AgoraRtcEngineKit.h

– setVolumeOfEffect:withVolume:

Sets the volume of a specified audio effect.

- (int)setVolumeOfEffect:(int)soundId withVolume:(double)volume

Parameters

soundId

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

volume

Volume of the audio effect. The value ranges between 0.0 and 100.0 (default).

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Ensure that this method is called after playEffect.

Declared In

AgoraRtcEngineKit.h

– playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos:

Plays a specified local or online audio effect file.

- (int)playEffect:(int)soundId filePath:(NSString *_Nullable)filePath loopCount:(int)loopCount pitch:(double)pitch pan:(double)pan gain:(double)gain publish:(BOOL)publish startPos:(int)startPos

Parameters

soundId

Audio effect ID. The ID of each audio effect file is unique. If you preloaded an audio effect into memory by calling preloadEffect, ensure that this parameter is set to the same value as in preloadEffect.

filePath

The absolute path or URL address (including the filename extensions) of the audio effect file. For example: /var/mobile/Containers/Data/audio.mp4. If you preloaded an audio effect into memory by calling preloadEffect, ensure that this parameter is set to the same value as in preloadEffect.

loopCount

The number of times the audio effect loops:

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

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

pan

The spatial position of the audio effect. The range is -1.0 to 1.0. For example:

  • -1.0: The audio effect occurs on the left.
  • 0.0: The audio effect occurs in the front.
  • 1.0: The audio effect occurs on the right.
gain

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

publish

Whether to publish the audio effect to the remote users:

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

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

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

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

Note

Declared In

AgoraRtcEngineKit.h

– stopEffect:

Stops playing a specified audio effect.

- (int)stopEffect:(int)soundId

Parameters

soundId

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

Return Value

  • 0: Success.
  • < 0: Failure.

Declared In

AgoraRtcEngineKit.h

– stopAllEffects

Stops playing all audio effects.

- (int)stopAllEffects

Declared In

AgoraRtcEngineKit.h

– preloadEffect:filePath:

Preloads a specified audio effect file into the memory.

- (int)preloadEffect:(int)soundId filePath:(NSString *_Nullable)filePath

Parameters

soundId

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

filePath

Absolute path of the audio effect file.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

To ensure smooth communication, limit the size of the audio effect file. Agora recommends using this method to preload the audio effect before calling the joinChannelByToken method.

Note

Declared In

AgoraRtcEngineKit.h

– unloadEffect:

Releases a specified preloaded audio effect from the memory.

- (int)unloadEffect:(int)soundId

Parameters

soundId

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

Return Value

  • 0: Success.
  • < 0: Failure.

Declared In

AgoraRtcEngineKit.h

– pauseEffect:

Pauses a specified audio effect.

- (int)pauseEffect:(int)soundId

Parameters

soundId

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

Return Value

  • 0: Success.
  • < 0: Failure.

Declared In

AgoraRtcEngineKit.h

– pauseAllEffects

Pauses all audio effects.

- (int)pauseAllEffects

Return Value

  • 0: Success.
  • < 0: Failure.

Declared In

AgoraRtcEngineKit.h

– resumeEffect:

Resumes playing a specified audio effect.

- (int)resumeEffect:(int)soundId

Parameters

soundId

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

Return Value

  • 0: Success.
  • < 0: Failure.

Declared In

AgoraRtcEngineKit.h

– resumeAllEffects

Resumes playing all audio effects.

- (int)resumeAllEffects

Return Value

  • 0: Success.
  • < 0: Failure.

Declared In

AgoraRtcEngineKit.h

– getEffectCurrentPosition:

Gets the playback position of the audio effect file.

- (int)getEffectCurrentPosition:(int)soundId

Parameters

soundId

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

Return Value

  • ≥ 0: A successful method call. Returns the playback position (ms) of the specified audio effect file.
  • < 0: Failure.

    • -22(AgoraErrorCodeResourceLimited): Cannot find the audio effect file. Please set a correct soundId.

Availability

v3.4.0

Discussion

Note: Call this method after playEffect.

Declared In

AgoraRtcEngineKit.h

– setEffectPosition:pos:

Sets the playback position of an audio effect file.

- (int)setEffectPosition:(int)soundId pos:(NSInteger)pos

Parameters

soundId

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

pos

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

Return Value

  • 0: Success.
  • < 0: Failure.

    • -22(AgoraErrorCodeResourceLimited): Cannot find the audio effect file. Please set a correct soundId.

Availability

v3.4.0

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

Discussion

Note: Call this method after playEffect.

Declared In

AgoraRtcEngineKit.h

– getEffectDuration:

Gets the duration of the audio effect file.

- (int)getEffectDuration:(NSString *_Nonnull)filePath

Parameters

filePath

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

Return Value

  • ≥ 0: A successful method call. Returns the total duration (ms) of the specified audio effect file.
  • < 0: Failure.

    • -22(AgoraErrorCodeResourceLimited): Cannot find the audio effect file. Please set a correct filePath.

Availability

v3.4.0

Note

Declared In

AgoraRtcEngineKit.h

Virtual metronome

– startRhythmPlayer:sound2:config:

Enables the virtual metronome.

- (int)startRhythmPlayer:(NSString *_Nonnull)sound1 sound2:(NSString *_Nonnull)sound2 config:(AgoraRtcRhythmPlayerConfig *_Nonnull)config

Parameters

sound1

The absolute path or URL address (including the filename extensions) of the file for the downbeat. For example: /var/mobile/Containers/Data/audio.mp4.

sound2

The absolute path or URL address (including the filename extensions) of the file for the upbeats. For example: /var/mobile/Containers/Data/audio.mp4.

config

The metronome configuration. See AgoraRtcRhythmPlayerConfig.

Return Value

  • 0: Success.
  • < 0: Failure.

    • -22(AgoraErrorCodeResourceLimited): Cannot find audio effect files. Please set the correct paths for sound1 and sound2.

Availability

v3.4.0

In music education, physical education, and other scenarios, teachers often need to use a metronome so that students can practice at the correct tempo. A meter is composed of a downbeat and some number of upbeats (including zero). The first beat of each measure is called the downbeat, and the rest are called the upbeats. In this method, you need to set the paths of the upbeat and downbeat files, the number of beats per measure, the tempo, and whether to send the sound of the metronome to remote users.

Note

  • After enabling the virtual metronome, the SDK plays the specified files from the beginning and controls the beat duration according to the value you set in beatsPerMinute. If the file duration exceeds the beat duration, the SDK only plays the audio within the beat duration.
  • For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support.

Declared In

AgoraRtcEngineKit.h

– stopRhythmPlayer

Disables the virtual metronome.

- (int)stopRhythmPlayer

Return Value

  • 0: Success.
  • < 0: Failure.

Availability

v3.4.0

After calling startRhythmPlayer, you can call this method to disable the virtual metronome.

Declared In

AgoraRtcEngineKit.h

– configRhythmPlayer:

Configures the virtual metronome.

- (int)configRhythmPlayer:(AgoraRtcRhythmPlayerConfig *_Nonnull)config

Parameters

config

The metronome configuration. See AgoraRtcRhythmPlayerConfig.

Return Value

  • 0: Success.
  • < 0: Failure.

Availability

v3.4.0

After calling startRhythmPlayer, you can call this method to reconfigure the virtual metronome.

Discussion

Note: After reconfiguring the virtual metronome, the SDK plays the specified files from the beginning and controls the beat duration according to the value you set in beatsPerMinute. If the file duration exceeds the beat duration, the SDK only plays the audio within the beat duration.

Declared In

AgoraRtcEngineKit.h

Audio Recorder

– startAudioRecordingWithConfig:

Starts an audio recording on the client.

- (int)startAudioRecordingWithConfig:(AgoraAudioRecordingConfiguration *_Nonnull)config

Parameters

config

Recording configuration. See AgoraAudioRecordingConfiguration.

Return Value

  • 0: Success.
  • < 0: Failure.

    -160(AgoraErrorCodeAlreadyInRecording): The client is already recording audio. To start a new recording, call stopAudioRecording to stop the current recording first, and then call startAudioRecordingWithConfig.

Availability

v3.4.0

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

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

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

Discussion

Note: Call this method after joining a channel.

Declared In

AgoraRtcEngineKit.h

– stopAudioRecording

Stops an audio recording on the client.

- (int)stopAudioRecording

Return Value

  • 0: Success.
  • < 0: Failure.

Declared In

AgoraRtcEngineKit.h

Loopback Sampling

– enableLoopbackRecording:deviceName:

Enables loopback sampling. (macOS only)

- (int)enableLoopbackRecording:(BOOL)enabled deviceName:(NSString *_Nullable)deviceName

Parameters

enabled

Sets whether to enable/disable loopback sampling.

  • YES: Enable loopback sampling.
  • NO: (Default) Disable loopback sampling.
deviceName

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

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

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

Note:

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

Declared In

AgoraRtcEngineKit.h

Miscellaneous Audio Control

– setAudioSessionOperationRestriction:

Sets the operational permission of the SDK on the audio session. (iOS only)

- (void)setAudioSessionOperationRestriction:(AgoraAudioSessionOperationRestriction)restriction

Parameters

restriction

The operational permission of the SDK on the audio session. See AgoraAudioSessionOperationRestriction. This parameter is in bit mask format, and each bit corresponds to a permission.

Discussion

The SDK and the app can both configure the audio session by default. If you need to only use the app to configure the audio session, this method restricts the operational permission of the SDK on the audio session.

You can call this method either before or after joining a channel. Once you call this method to restrict the operational permission of the SDK on the audio session, the restriction takes effect when the SDK needs to change the audio session.

Note: This method does not restrict the operational permission of the app on the audio session.

Declared In

AgoraRtcEngineKit.h

– enableDeepLearningDenoise:

Enables or disables deep-learning noise reduction.

- (int)enableDeepLearningDenoise:(BOOL)enabled

Parameters

enabled

Sets whether to enable deep-learning noise reduction.

  • YES: (Default) Enables deep-learning noise reduction.
  • NO: Disables deep-learning noise reduction.

Return Value

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

Discussion

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

  1. Ensure that the following library is integrated in your project:

    • iOS: AgoraAIDenoiseExtension.xcframework
    • macOS: AgoraAIDenoiseExtension.framework
  2. Call enableDeepLearningDenoise(YES).

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

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

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

If you call enableDeepLearningDenoise(NO) or the SDK automatically disables deep-learning noise reduction in the channel, when you need to re-enable deep-learning noise reduction, you need to call leaveChannel first, and then call enableDeepLearningDenoise(YES).

Note

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

Declared In

AgoraRtcEngineKit.h

Network-related Test

– startEchoTestWithInterval:successBlock:

Starts an audio call test.

- (int)startEchoTestWithInterval:(NSInteger)interval successBlock:(void ( ^ _Nullable ) ( NSString *_Nonnull channel , NSUInteger uid , NSInteger elapsed ))successBlock

Parameters

interval

The time interval (s) between when you speak and when the sampled audio data plays back.

successBlock

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

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

In the audio call test, the SDK samples your voice. If the sampled audio data plays back within the set time interval, the audio devices and the network connection are working properly.

Note:

  • Call this method before joining a channel.

  • After calling this method, call the stopEchoTest method to end the test. Otherwise, the app cannot run the next echo test, or join a channel.

  • In the interactive live streaming profile, only a host can call this method.

Declared In

AgoraRtcEngineKit.h

– stopEchoTest

Stops the audio call test.

- (int)stopEchoTest

Return Value

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

Declared In

AgoraRtcEngineKit.h

– enableLastmileTest

Enables the network connection quality test.

- (int)enableLastmileTest

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

This method tests the quality of the user’s network connection and is disabled by default.

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

This method consumes additional network traffic, which may affect the communication quality. We do not recommend calling this method together with startLastmileProbeTest.

Call the disableLastmileTest method to disable this test after receiving the lastmileQuality callback, and before the user joins the channel or switches the user role.

Note:

  • Do not call any other methods before receiving the lastmileQuality callback. Otherwise, the callback may be interrupted by other methods and may not execute.

  • In the interactive live streaming profile, a host should not call this method after joining a channel.

  • If you call this method to test the last mile quality, the SDK consumes the bandwidth of a video stream, whose bitrate corresponds to the bitrate you set in the setVideoEncoderConfiguration method. After you join the channel, whether you have called the disableLastmileTest method or not, the SDK automatically stops consuming the bandwidth.

Declared In

AgoraRtcEngineKit.h

– disableLastmileTest

Disables the network connection quality test.

- (int)disableLastmileTest

Return Value

  • 0: Success.
  • < 0: Failure.

Declared In

AgoraRtcEngineKit.h

– startLastmileProbeTest:

Starts the last-mile network probe test.

- (int)startLastmileProbeTest:(AgoraLastmileProbeConfig *_Nullable)config

Parameters

config

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

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

Call this method to check the uplink network quality before users join a channel or before an audience switches to a host.

Once this method is enabled, the SDK returns the following callbacks:

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

Note:

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

Declared In

AgoraRtcEngineKit.h

– stopLastmileProbeTest

Stops the last-mile network probe test.

- (int)stopLastmileProbeTest

Return Value

  • 0: Success.
  • < 0: Failure.

Declared In

AgoraRtcEngineKit.h

Custom Video Module

– setVideoSource:

Sets the video source.

- (void)setVideoSource:(id<AgoraVideoSourceProtocol> _Nullable)videoSource

Parameters

videoSource

AgoraVideoSourceProtocol

Discussion

In real-time communications, the SDK uses the default video input source (the built-in camera) to publish streams. To use an external video source, call AgoraVideoSourceProtocol to set the custom video source and then use this method to add the external video source into the SDK.

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

Declared In

AgoraRtcEngineKit.h

– setLocalVideoRenderer:

Sets the local video renderer.

- (void)setLocalVideoRenderer:(id<AgoraVideoSinkProtocol> _Nullable)videoRenderer

Parameters

videoRenderer

Sets the local video renderer. See AgoraVideoSinkProtocol.

Discussion

In real-time communications, the SDK uses the default video renderer to render the video. To use an external video renderer, call AgoraVideoSinkProtocol to set the custom local video renderer and then use this method to add the external renderer into the SDK.

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

Declared In

AgoraRtcEngineKit.h

– setRemoteVideoRenderer:forUserId:

Sets the remote video renderer.

- (void)setRemoteVideoRenderer:(id<AgoraVideoSinkProtocol> _Nullable)videoRenderer forUserId:(NSUInteger)userId

Parameters

videoRenderer

Sets the video renderer of the remote user. See AgoraVideoSinkProtocol.

userId

ID of the remote user.

Discussion

This method sets the remote renderer. In real-time communications, the SDK uses the default video renderer to render the video. To use an external video renderer, call AgoraVideoSinkProtocol to set the custom remote video renderer and then use this method to add the external renderer into the SDK.

You can call this method either before or after joining a channel. If you call it before joining a channel, you need to maintain the uid of the remote user on your app level.

Declared In

AgoraRtcEngineKit.h

– videoSource

Gets the video source.

- (id<AgoraVideoSourceProtocol> _Nullable)videoSource

Return Value

Video source. See AgoraVideoSourceProtocol.

Declared In

AgoraRtcEngineKit.h

– localVideoRenderer

Gets the local video renderer.

- (id<AgoraVideoSinkProtocol> _Nullable)localVideoRenderer

Return Value

Local video renderer. See AgoraVideoSinkProtocol.

Declared In

AgoraRtcEngineKit.h

– remoteVideoRendererOfUserId:

Gets the video renderer of a specified remote user.

- (id<AgoraVideoSinkProtocol> _Nullable)remoteVideoRendererOfUserId:(NSUInteger)userId

Parameters

userId

ID of the remote user.

Return Value

Video renderer of the remote user. See AgoraVideoSinkProtocol.

Declared In

AgoraRtcEngineKit.h

– setVideoDataFrame:

Registers a raw video frame protocol.

- (void)setVideoDataFrame:(id<AgoraVideoDataFrameProtocol> _Nullable)videoData

Parameters

videoData

The raw video frame. See AgoraVideoDataFrameProtocol. If nil is passed, the protocol registration is canceled.

Availability

v3.4.5

After you successfully register the raw video frame protocol, the SDK triggers the callbacks that you have implemented in AgoraVideoDataFrameProtocol each time a video frame is received.

Note:

  • This method applies to iOS only.
  • Ensure that you call this method before joining a channel.
  • The width and height of the video obtained through the protocol may change due to poor network conditions and user-adjusted resolution.

Declared In

AgoraRtcEngineKit.h

– setVideoEncodedFrame:

Registers a local encoded video frame protocol.

- (void)setVideoEncodedFrame:(id<AgoraVideoEncodedFrameProtocol> _Nullable)videoEncode

Parameters

videoEncode

The local encoded video frame protocol. See AgoraVideoEncodedFrameProtocol. If nil is passed, the protocol registration is canceled.

Availability

v3.4.5

After you successfully register the local encoded video frame protocol, the SDK triggers the callbacks that you have implemented in AgoraVideoEncodedFrameProtocol each time a video frame is received.

Note:

  • This method applies to iOS only.
  • Ensure that you call this method before joining a channel.
  • The width and height of the video obtained through the protocol may change due to poor network conditions and user-adjusted resolution.

Declared In

AgoraRtcEngineKit.h

External Audio Sink

– enableExternalAudioSink:channels:

Enables the external audio sink.

- (void)enableExternalAudioSink:(NSUInteger)sampleRate channels:(NSUInteger)channels

Parameters

sampleRate

Sets the sample rate (Hz) of the external audio sink. You can set this parameter as 16000, 32000, 44100 or 48000.

channels

Sets the number of audio channels of the external audio sink:

  • 1: Mono
  • 2: Stereo

Discussion

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

Ensure that you call this method before joining a channel.

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

Declared In

AgoraRtcEngineKit.h

– disableExternalAudioSink

Disables the external audio sink.

- (void)disableExternalAudioSink

Declared In

AgoraRtcEngineKit.h

– pullPlaybackAudioFrameRawData:lengthInByte:

Pulls the remote audio data in the RawData format.

- (BOOL)pullPlaybackAudioFrameRawData:(void *_Nonnull)data lengthInByte:(NSUInteger)lengthInByte

Parameters

data

The audio data that you want to pull. The data format is in byte[].

lengthInByte

The data length (byte) of the external audio data. The value of this parameter is related to the audio duration, and the values of the sampleRate and channels parameters that you set in enableExternalAudioSink. Agora recommends setting the audio duration no shorter than 10 ms. The formula for lengthInByte is as follows: lengthInByte = sampleRate / 1000 × 2 × channels × audio duration (ms).

Return Value

  • YES: Success.
  • NO: Failure.

Discussion

Before calling this method, call the enableExternalAudioSink method to enable and set the external audio sink.

After a successful method call, the app pulls the decoded and mixed audio data for playback.

Note

  • Ensure that you call this method after joining a channel. Once you call the pullPlaybackAudioFrameRawData method successfully, the app will not retrieve any audio data from the onPlaybackAudioFrame callback.
  • The difference between the onPlaybackAudioFrame callback and the pullPlaybackAudioFrameRawData method is as follows:
    • onPlaybackAudioFrame: The SDK sends the audio data to the app through this callback. Any delay in processing the audio frames may result in audio jitter.
    • pullPlaybackAudioFrameRawData: The app pulls the remote audio data autonomously. After setting the audio data parameters, the SDK adjusts the frame buffer and avoids problems caused by jitter in the external audio playback.

Declared In

AgoraRtcEngineKit.h

– pullPlaybackAudioFrameSampleBufferByLengthInByte:

Pulls the remote audio data in the SampleBuffer format.

- (CMSampleBufferRef _Nullable)pullPlaybackAudioFrameSampleBufferByLengthInByte:(NSUInteger)lengthInByte

Parameters

lengthInByte

The data length (byte) of the external audio data. The value of this parameter is related to the audio duration, and the values of the sampleRate and channels parameters that you set in enableExternalAudioSink. This parameter should be divisible by the value of sampleRate, and Agora recommends setting the audio duration no shorter than 10 ms. The formula for lengthInByte is as follows: lengthInByte = sampleRate / 1000 × 2 × channels × audio duration (ms). - This parameter should be divisible by the value of sampleRate.

Return Value

  • YES: Success.
  • NO: Failure.

Discussion

Before calling this method, call the enableExternalAudioSink method to enable and set the external audio sink.

After a successful method call, the app pulls the decoded and mixed audio data for playback.

Note

  • Ensure that you call this method after joining a channel. Once you call the pullPlaybackAudioFrameSampleBufferByLengthInByte method successfully, the app will not retrieve any audio data from the onPlaybackAudioFrame callback.
  • The difference between the onPlaybackAudioFrame callback and the pullPlaybackAudioFrameSampleBufferByLengthInByte method is as follows:
    • onPlaybackAudioFrame: The SDK sends the audio data to the app through this callback. Any delay in processing the audio frames may result in audio jitter.
    • pullPlaybackAudioFrameSampleBufferByLengthInByte: The app pulls the remote audio data. After setting the audio data parameters, the SDK adjusts the frame buffer and avoids problems caused by jitter in the external audio playback.

Declared In

AgoraRtcEngineKit.h

External Audio Data (push-mode only)

– enableExternalAudioSourceWithSampleRate:channelsPerFrame:

Enables the external audio source.

- (void)enableExternalAudioSourceWithSampleRate:(NSUInteger)sampleRate channelsPerFrame:(NSUInteger)channelsPerFrame

Parameters

sampleRate

Sets the sample rate (Hz) of the external audio source: 8000, 16000, 44100, or 48000 Hz.

channelsPerFrame

Sets the number of external audio source channels:

  • 1: Mono.
  • 2: Stereo.

Discussion

Call this method before joinChannelByToken and startPreview.

Declared In

AgoraRtcEngineKit.h

– disableExternalAudioSource

Disables the external audio source.

- (void)disableExternalAudioSource

Declared In

AgoraRtcEngineKit.h

– setExternalAudioSourceVolume:volume:

Sets the volume of the external audio frame in the specified position.

- (void)setExternalAudioSourceVolume:(AgoraAudioExternalSourcePos)sourcePos volume:(NSUInteger)volume

Parameters

sourcePos

The push position of the external audio frame. See AgoraAudioExternalSourcePos.

volume

The volume of the external audio frame. The value range is [0,100]. The default value is 100, which represents the original value.

Availability

v3.5.1

You can call this method multiple times to set the volume of external audio frames in different positions. The volume setting takes effect for all external audio frames that are pushed to the specified position.

Discussion

Note: Call this method after joining a channel.

Declared In

AgoraRtcEngineKit.h

– pushExternalAudioFrameRawData:frame:

Pushes the external raw audio frame to a specified position.

- (int)pushExternalAudioFrameRawData:(AgoraAudioExternalSourcePos)sourcePos frame:(AgoraAudioFrame *_Nonnull)frame

Parameters

sourcePos

The push position of the external audio frame. See AgoraAudioExternalSourcePos.

frame

The audio frame. See AgoraAudioFrame. The value range of the audio frame length (ms) is [10,60].

Return Value

  • 0: Success.
  • < 0: Failure.

    • -2 (AgoraErrorCodeInvalidArgument): The parameter is invalid.
    • -12 (AgoraErrorCodeTooOften): The call frequency is too high, causing the internal buffer to overflow. Call this method again after 30-50 ms.

Availability

v3.5.1

According to your needs, you can push the external audio frame to one of three positions: after audio capture, before audio encoding, or before local playback. You can call this method multiple times to push one audio frame to multiple positions or multiple audio frames to different positions. For example, in the KTV scenario, you can push the singing voice to after audio capture, so that the singing voice can be processed by the SDK audio module and you can obtain a high-quality audio experience; you can also push the accompaniment to before audio encoding, so that the accompaniment is not affected by the audio module of the SDK.

Discussion

Note: Call this method after joining a channel.

Declared In

AgoraRtcEngineKit.h

– pushExternalAudioFrameSampleBuffer:sampleBuffer:

Pushes the external CMSampleBuffer audio frame to a specified position.

- (int)pushExternalAudioFrameSampleBuffer:(AgoraAudioExternalSourcePos)sourcePos sampleBuffer:(CMSampleBufferRef _Nonnull)sampleBuffer

Parameters

sourcePos

The push position of the external audio frame. See AgoraAudioExternalSourcePos.

sampleBuffer

The sample buffer. The value range of the sample buffer length (ms) is [10,60].

Return Value

  • 0: Success.
  • < 0: Failure.

    • -2 (AgoraErrorCodeInvalidArgument): The parameter is invalid.
    • -12 (AgoraErrorCodeTooOften): The call frequency is too high, causing the internal buffer to overflow. Call this method again after 30-50 ms.

Availability

v3.5.1

According to your needs, you can push the external audio frame to one of three positions: after audio capture, before audio encoding, or before local playback. You can call this method multiple times to push one audio frame to multiple positions or multiple audio frames to different positions. For example, in the KTV scenario, you can push the singing voice to after audio capture, so that the singing voice can be processed by the SDK audio module and you can obtain a high-quality audio experience; you can also push the accompaniment to before audio encoding, so that the accompaniment is not affected by the audio module of the SDK.

Discussion

Note: Call this method after joining a channel.

Declared In

AgoraRtcEngineKit.h

External Video Data (push-mode only)

– setExternalVideoSource:useTexture:pushMode:

Configures the external video source.

- (void)setExternalVideoSource:(BOOL)enable useTexture:(BOOL)useTexture pushMode:(BOOL)pushMode

Parameters

enable

Sets whether to use an external video source:

  • YES: Use an external video source.
  • NO: (Default) Do not use an external video source.
useTexture

Sets whether to use texture as an input:

  • YES: Use texture as an input.
  • NO: Do not use texture as an input.
pushMode

Sets whether or not the external video source needs to call the pushExternalVideoFrame method to send the video frame to the SDK:

  • YES: Use the push mode.
  • NO: Use the pull mode (not supported yet).

Discussion

Note: Call this method before joining a channel.

Declared In

AgoraRtcEngineKit.h

– pushExternalVideoFrame:

Pushes the external video frame.

- (BOOL)pushExternalVideoFrame:(AgoraVideoFrame *_Nonnull)frame

Parameters

frame

Video frame containing the SDK’s encoded video data to be pushed. See AgoraVideoFrame.

Return Value

  • YES: The frame is pushed successfully.
  • NO: Fails to push the frame.

Discussion

This method pushes the video frame using the AgoraVideoFrame class and passes the video frame to the SDK with the format parameter found in AgoraVideoFrame. Call the setExternalVideoSource method and set the pushMode parameter as YES before calling this method. Otherwise, a failure returns after calling this method.

Note: The SDK does not support the alpha channel, and discards any alpha value passed to the SDK.

Declared In

AgoraRtcEngineKit.h

Raw Audio Data

– setRecordingAudioFrameParametersWithSampleRate:channel:mode:samplesPerCall:

Sets the audio sampling format.

- (int)setRecordingAudioFrameParametersWithSampleRate:(NSInteger)sampleRate channel:(NSInteger)channel mode:(AgoraAudioRawFrameOperationMode)mode samplesPerCall:(NSInteger)samplesPerCall

Parameters

sampleRate

Sets the audio sample rate (samplesPerSec) returned in the onRecordAudioFrame callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.

channel

Sets the number of audio channels (channels) returned in the onRecordAudioFrame callback, which can be set as 1 or 2:

  • 1: Mono
  • 2: Stereo
mode

Sets the use mode of the onRecordAudioFrame callback. See AgoraAudioRawFrameOperationMode.

samplesPerCall

Sets the number of samples the onRecordAudioFrame callback returns. Set it as 1024 for RTMP or RTMPS streaming.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

This method sets the audio format of the onRecordAudioFrame callback. See Raw Audio Data.

Ensure that you call this method before joining a channel.

Note: The SDK calculates the sample interval according to the value of the sampleRate, channel, and samplesPerCall parameters you set in this method. Sample interval (sec) = samplePerCall/(sampleRate * channel). Ensure that the value of sample interval is no less than 0.01. The SDK triggers the onRecordAudioFrame callback according to the sample interval.

Declared In

AgoraRtcEngineKit.h

– setPlaybackAudioFrameParametersWithSampleRate:channel:mode:samplesPerCall:

Sets the audio playback format.

- (int)setPlaybackAudioFrameParametersWithSampleRate:(NSInteger)sampleRate channel:(NSInteger)channel mode:(AgoraAudioRawFrameOperationMode)mode samplesPerCall:(NSInteger)samplesPerCall

Parameters

sampleRate

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

channel

Sets the number of audio channels (channels) returned in the onPlaybackAudioFrame callback, which can be set as 1 or 2:

  • 1: Mono
  • 2: Stereo
mode

Sets the use mode of the onPlaybackAudioFrame callback. See AgoraAudioRawFrameOperationMode.

samplesPerCall

Sets the number of samples the onPlaybackAudioFrame callback returns. Set it as 1024 for RTMP or RTMPS streaming.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

This method sets the audio format of the onPlaybackAudioFrame callback. See Raw Audio Data.

Ensure that you call this method before joining a channel.

Note: The SDK calculates the sample interval according to the value of the sampleRate, channel, and samplesPerCall parameters you set in this method. Sample interval (sec) = samplePerCall/(sampleRate * channel). Ensure that the value of sample interval is no less than 0.01. The SDK triggers the onPlaybackAudioFrame callback according to the sample interval.

Declared In

AgoraRtcEngineKit.h

– setMixedAudioFrameParametersWithSampleRate:samplesPerCall:

Sets the format of the mixed sampled and playback audio frame.

- (int)setMixedAudioFrameParametersWithSampleRate:(NSInteger)sampleRate samplesPerCall:(NSInteger)samplesPerCall

Parameters

sampleRate

Sets the sample rate (samplesPerSec) returned in the onMixedAudioFrame callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.

samplesPerCall

Sets the number of samples the onMixedAudioFrame callback returns. Set it as 1024 for RTMP or RTMPS streaming.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

This method sets the audio format of the onMixedAudioFrame callback. See Raw Audio Data.

Ensure that you call this method before joining a channel.

Note: The SDK calculates the sample interval according to the value of the sampleRate, channel, and samplesPerCall parameters you set in this method. Sample interval (sec) = samplePerCall/(sampleRate * channel). Ensure that the value of sample interval is no less than 0.01. The SDK triggers the onMixedAudioFrame callback according to the sample interval.

Declared In

AgoraRtcEngineKit.h

– setAudioDataFrame:

Registers the raw audio data protocol.

- (BOOL)setAudioDataFrame:(id<AgoraAudioDataFrameProtocol> _Nullable)delegate

Parameters

delegate

The delegate of the audio frame. See AgoraAudioDataFrameProtocol.

Return Value

  • YES: Success.
  • NO: Failure.

Availability

v3.4.5

For the SDK to trigger the callbacks that provide the raw audio data, call this method to register the audio frame delegate. You need to implement AgoraAudioDataFrameProtocol in this method.

Note

  • This method applies to iOS only.
  • Ensure that you call this method before joining a channel.
  • To release the audio frame delegate, pass nil in the delegate parameter. Agora recommends calling setAudioDataFrame(nil) after receiving the didLeaveChannelWithStats callback.

Declared In

AgoraRtcEngineKit.h

Watermark

– addVideoWatermark:options:

Adds a watermark image to the local video.

- (int)addVideoWatermark:(NSURL *_Nonnull)url options:(WatermarkOptions *_Nonnull)options

Parameters

url

The local file path of the watermark image to be added. This method supports adding a watermark image from the local file path. If the watermark image to be added is in the project file, you need to change the image’s Type from PNG image to Data in the Xcode property, otherwise, the Agora Native SDK cannot recognize the image.

options

The options of the watermark image to be added. See WatermarkOptions.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

This method adds a PNG watermark image to the local video in the interactive 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.

The watermark position depends on the settings in the setVideoEncoderConfiguration method:

  • If the orientation mode of the encoding video is AgoraVideoOutputOrientationModeFixedLandscape, or the landscape mode in AgoraVideoOutputOrientationModeAdaptative, the watermark uses the landscape orientation.
  • If the orientation mode of the encoding video is AgoraVideoOutputOrientationModeFixedPortrait, or the portrait mode in AgoraVideoOutputOrientationModeAdaptative, the watermark uses the portrait orientation.
  • When setting the watermark position, the region must be less than the dimensions set in the setVideoEncoderConfiguration method. Otherwise, the watermark image will be cropped.

Note

  • Ensure that you have called the enableVideo method to enable the video module before calling this method.
  • If you only want to add a watermark image to the local video for the audience in the CDN live streaming channel to see and capture, you can call this method or the setLiveTranscoding method.
  • This method supports adding a watermark image in the PNG file format only. Supported pixel formats of the PNG image are RGBA, RGB, Palette, Gray, and Alpha_gray.
  • If the dimensions of the PNG image differ from your settings in this method, the image will be cropped or zoomed to conform to your settings.
  • If you have enabled the local video preview by calling the startPreview method, you can use the visibleInPreview member in the WatermarkOptions class to set whether or not the watermark is visible in preview.
  • If you have enabled the mirror mode for the local video, the watermark on the local video is also mirrored. To avoid mirroring the watermark, Agora recommends that you do not use the mirror and watermark functions for the local video at the same time. You can implement the watermark function in your application layer.

Declared In

AgoraRtcEngineKit.h

– clearVideoWatermarks

Removes the watermark image from the video stream added by addVideoWatermark.

- (int)clearVideoWatermarks

Return Value

  • 0: Success.
  • < 0: Failure.

Declared In

AgoraRtcEngineKit.h

Stream Fallback

– setRemoteUserPriority:type:

Sets the priority of a remote user’s stream.

- (int)setRemoteUserPriority:(NSUInteger)uid type:(AgoraUserPriority)userPriority

Parameters

uid

The ID of the remote user.

userPriority

The priority of the remote user, see AgoraUserPriority.

Return Value

  • 0: Success.
  • <0: Failure.

Discussion

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

Note:

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

Declared In

AgoraRtcEngineKit.h

– setLocalPublishFallbackOption:

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

- (int)setLocalPublishFallbackOption:(AgoraStreamFallbackOptions)option

Parameters

option

Sets the fallback option for the published video stream. The default value is AgoraStreamFallbackOptionDisabled. See AgoraStreamFallbackOptions.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

The default setting for option is AgoraStreamFallbackOptionDisabled, where there is no fallback behavior for the locally published video stream when the uplink network conditions are unreliable.

If option is set as AgoraStreamFallbackOptionAudioOnly, the SDK will:

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

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

Ensure that you call this method before joining a channel.

Note:

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

Declared In

AgoraRtcEngineKit.h

– setRemoteSubscribeFallbackOption:

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

- (int)setRemoteSubscribeFallbackOption:(AgoraStreamFallbackOptions)option

Parameters

option

Sets the fallback option for the remotely subscribed video stream. The default value is AgoraStreamFallbackOptionVideoStreamLow. See AgoraStreamFallbackOptions.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

If option is set as AgoraStreamFallbackOptionAudioOnly, the SDK automatically switches the video from a high stream to a low stream, or disables the video when the downlink network conditions cannot support both audio and video to guarantee the quality of the audio. The SDK monitors the network quality and re-enables the video stream when the network conditions improve. When the remotely subscribed video stream falls back to audio only or when the audio-only stream switches back to the video, the SDK triggers the didRemoteSubscribeFallbackToAudioOnly callback.

Ensure that you call this method before joining a channel.

Declared In

AgoraRtcEngineKit.h

Dual-stream Mode

– enableDualStreamMode:

Enables/Disables dual-stream mode. (Interactive live streaming only.)

- (int)enableDualStreamMode:(BOOL)enabled

Parameters

enabled

Sets the stream mode:

  • YES: Dual-stream mode.
  • NO: Single-stream mode.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

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

Declared In

AgoraRtcEngineKit.h

– setRemoteVideoStream:type:

Sets the stream type of the remote video.

- (int)setRemoteVideoStream:(NSUInteger)uid type:(AgoraVideoStreamType)streamType

Parameters

uid

ID of the remote user sending the video stream.

streamType

Sets the video-stream type. See AgoraVideoStreamType.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Under limited network conditions, if the publisher has not disabled the dual-stream mode using enableDualStreamMode(NO)enableDualStreamMode(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).

By default, users receive the high-quality video stream. Call this method if you want to switch the remote stream type 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 SDK reports the result of calling this method in the didApiCallExecute callback.

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

Declared In

AgoraRtcEngineKit.h

– setRemoteDefaultVideoStreamType:

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

- (int)setRemoteDefaultVideoStreamType:(AgoraVideoStreamType)streamType

Parameters

streamType

Sets the default video-stream type. See AgoraVideoStreamType.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

Declared In

AgoraRtcEngineKit.h

Encryption

– enableEncryption:encryptionConfig:

Enables/Disables the built-in encryption.

- (int)enableEncryption:(bool)enabled encryptionConfig:(AgoraEncryptionConfig *_Nonnull)config

Parameters

enabled

Whether to enable the built-in encryption:

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

Configurations of built-in encryption schemas. See AgoraEncryptionConfig.

Return Value

  • 0: Success.
  • < 0: Failure.

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

Availability

v3.1.0

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

After a user leaves the channel, the SDK automatically disables the built-in encryption. To re-enable the built-in encryption, call this method before the user joins the channel again.

As of v3.4.5, Agora recommends using either the AgoraEncryptionModeAES128GCM2 or AgoraEncryptionModeAES256GCM2 encryption mode, both of which support adding a salt and are more secure. For details, see Media Stream Encryption.

Discussion

Warning: All users in the same channel must use the same encryption mode, encryption key, and salt; otherwise, users cannot communicate with each other.

Note:

  • If you enable the built-in encryption, you cannot use the RTMP or RTMPS streaming function.
  • To enhance security, Agora recommends using a new key and salt every time you enable the media stream encryption.

Declared In

AgoraRtcEngineKit.h

Inject an Online Media Stream

– addInjectStreamUrl:config:

Adds a voice or video stream CDN streaming URL to the interactive live streaming.

- (int)addInjectStreamUrl:(NSString *_Nonnull)url config:(AgoraLiveInjectStreamConfig *_Nonnull)config

Parameters

url

URL address to be added to the ongoing interactive live streaming. Valid protocols are RTMP, HLS, and HTTP-FLV.

  • Supported audio codec type: AAC.
  • Supported video codec type: H264 (AVC).
config

AgoraLiveInjectStreamConfig object which contains the configuration information for the added voice or video stream.

Return Value

  • 0: Success.
  • < 0: Failure.
    • AgoraErrorCodeInvalidArgument(-2): The injected URL does not exist. Call this method again to inject the stream and ensure that the URL is valid.
    • AgoraErrorCodeNotReady(-3): The user is not in the channel.
    • AgoraErrorCodeNotSupported(-4): The channel profile is not Live Broadcast. Call the setChannelProfile method and set the channel profile to Live Broadcast before calling this method.
    • AgoraErrorCodeNotInitialized(-7): The SDK is not initialized. Ensure that the RtcEngine object is initialized before using this method.

Discussion

The streamPublishedWithUrl callback returns the inject stream status.

If this method call is successful, the server pulls the voice or video stream and injects it into a live channel. This is applicable to scenarios where all audience members in the channel can watch a live show and interact with each other.

The addInjectStreamUrl method call triggers the following callbacks:

  • The local client:

    • streamInjectedStatusOfUrl, with the state of the injecting the online stream.
    • didJoinedOfUid(uid: 666), if the method call is successful and the online media stream is injected into the channel.
  • The remote client:

    • didJoinedOfUid(uid: 666), if the method call is successful and the online media stream is injected into the channel.

Warning: Agora will soon stop the service for injecting online media streams on the client. If you have not implemented this service, Agora recommends that you do not use it.

Note:

  • Ensure that you call this method after joining a channel.
  • You can inject only one media stream into the channel at the same time.
  • Ensure that you enable the RTMP Converter service before using this function. See Prerequisites.
  • This method applies to the Native SDK v2.4.1 and later.

Declared In

AgoraRtcEngineKit.h

– removeInjectStreamUrl:

Removes the voice or video stream CDN streaming URL from the interactive live streaming.

- (int)removeInjectStreamUrl:(NSString *_Nonnull)url

Parameters

url

URL address of the added stream to be removed.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

This method removes the URL address (added by the addInjectStreamUrl method) from the interactive live streaming.

If this method call is successful, the SDK triggers the didOfflineOfUid callback and returns a stream uid of 666.

Warning: Agora will soon stop the service for injecting online media streams on the client. If you have not implemented this service, Agora recommends that you do not use it.

Declared In

AgoraRtcEngineKit.h

CDN Live Streaming

– addPublishStreamUrl:transcodingEnabled:

Publishes the local stream to a specified CDN streaming URL.

- (int)addPublishStreamUrl:(NSString *_Nonnull)url transcodingEnabled:(BOOL)transcodingEnabled

Parameters

url

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

transcodingEnabled

Sets whether transcoding is enabled/disabled:

  • YES: Enable transcoding. To transcode the audio or video streams when publishing them to CDN live, often used for combining the audio and video streams of multiple hosts in CDN live. If you set this parameter as YES, ensure that you call the setLiveTranscoding method before this method.
  • NO: Disable transcoding.

Return Value

  • 0: Success.
  • < 0: Failure.

    • AgoraErrorCodeInvalidArgument(-2): Invalid parameter. The URL is nil or the string length is 0.
    • AgoraErrorCodeNotInitialized(-7): You have not initialized the RTC Engine when publishing the stream.

Discussion

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.

Note:

  • This method applies to the interactive live streaming profile only.
  • Ensure that the user joins the channel before calling this method.
  • Ensure that you enable the RTMP Converter service before using this function. See Prerequisites.
  • This method adds only one stream URL each time it is called.
  • Agora supports pushing media streams in RTMPS protocol to the CDN only when you enable transcoding.

Declared In

AgoraRtcEngineKit.h

– removePublishStreamUrl:

Removes an RTMP or RTMPS stream from the CDN.

- (int)removePublishStreamUrl:(NSString *_Nonnull)url

Parameters

url

The CDN streaming URL to be removed. The maximum length of this parameter is 1024 bytes.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

This method removes the CDN streaming URL added by the addPublishStreamUrl method from a CDN live stream.

This method call triggers the rtmpStreamingChangedToState callback on the local client to report the state of removing an RTMP or RTMPS stream from the CDN.

Note:

  • This method applies to the interactive live streaming profile only.
  • This method removes only one URL each time it is called.
  • The URL must not contain special characters, such as Chinese language characters.

Declared In

AgoraRtcEngineKit.h

– setLiveTranscoding:

Sets the video layout and audio settings for CDN live. (CDN live only.)

- (int)setLiveTranscoding:(AgoraLiveTranscoding *_Nullable)transcoding

Parameters

transcoding

Sets the CDN live audio/video transcoding settings. See AgoraLiveTranscoding.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

The SDK triggers the rtcEngineTranscodingUpdated callback when you call the setLiveTranscoding method to update the transcoding setting.

Note

  • Ensure that you call this method after joining a channel.
  • This method applies to the interactive live streaming profile only.
  • Ensure that you enable the RTMP Converter service before using this function. See Prerequisites.
  • If you call the setLiveTranscoding method to update the transcoding setting for the first time, the SDK does not trigger the rtcEngineTranscodingUpdated callback.
  • Agora supports pushing media streams in RTMPS protocol to the CDN only when you enable transcoding.

Declared In

AgoraRtcEngineKit.h

Data Stream

– createDataStream:config:

Creates a data stream.

- (int)createDataStream:(NSInteger *_Nonnull)streamId config:(AgoraDataStreamConfig *_Nonnull)config

Parameters

streamId

ID of the created data stream.

config

The configurations for the data stream: AgoraDataStreamConfig.

Return Value

  • Returns the stream ID if you successfully create the data stream.
  • < 0: Fails to create the data stream.

Availability

v3.3.0

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

This method does not support data reliability. If the receiver receives a data packet five seconds or more after it was sent, the SDK directly discards the data.

Declared In

AgoraRtcEngineKit.h

– sendStreamMessage:data:

Sends data stream messages to all users in a channel.

- (int)sendStreamMessage:(NSInteger)streamId data:(NSData *_Nonnull)data

Parameters

streamId

ID of the sent data stream returned in the createDataStream method.

data

Sent data.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

The SDK has the following restrictions on this method:

  • Up to 30 packets can be sent per second in a channel with each packet having a maximum size of 1 kB.
  • Each client can send up to 6 kB of data per second.
  • Each user can have up to five data streams simultaneously.

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

A failed sendStreamMessage method call triggers the didOccurStreamMessageErrorFromUid callback on the remote client.

Note:

  • This method applies only to the Communication profile or to the hosts in the interactive live streaming profile. If an audience in the interactive live streaming profile calls this method, the audience role may be changed to a host.
  • Ensure that you have created the data stream using createDataStream before calling this method.

Declared In

AgoraRtcEngineKit.h

Miscellaneous Video Control

– setCameraCapturerConfiguration:

Sets the camera capture preference.

- (int)setCameraCapturerConfiguration:(AgoraCameraCapturerConfiguration *_Nullable)configuration

Parameters

configuration

The camera capturer configuration, see AgoraCameraCapturerConfiguration.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

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

Note:

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

Declared In

AgoraRtcEngineKit.h

Camera Control

– switchCamera

Switches between front and rear cameras. (iOS only)

- (int)switchCamera

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Note: Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannelByToken.

Declared In

AgoraRtcEngineKit.h

– isCameraZoomSupported

Checks whether the camera zoom function is supported. (iOS only.)

- (BOOL)isCameraZoomSupported

Return Value

  • YES: The device supports the camera zoom function.
  • NO: The device does not support the camera zoom function.

Discussion

Note: Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannelByToken.

Declared In

AgoraRtcEngineKit.h

– isCameraTorchSupported

Checks whether the device supports enabling the flash. (iOS only.)

- (BOOL)isCameraTorchSupported

Return Value

  • YES: The device supports enabling the flash.
  • NO: The device does not support enabling the flash.

Discussion

The SDK uses the front camera by default, so if you call isCameraTorchSupported directly, you can find out from the return value whether the device supports enabling the flash when using the front camera. If you want to check whether the device supports enabling the flash when using the rear camera, call switchCamera to switch the camera used by the SDK to the rear camera, and then call isCameraTorchSupported.

Note

  • Call this method after the camera is started.
  • On iPads with system version 15, even if isCameraTorchSupported returns YES, you might fail to successfully enable the flash by calling setCameraTorchOn due to system issues.

Declared In

AgoraRtcEngineKit.h

– isCameraFocusPositionInPreviewSupported

Checks whether the camera manual focus function is supported. (iOS only)

- (BOOL)isCameraFocusPositionInPreviewSupported

Return Value

  • YES: The device supports the camera manual focus function.
  • NO: The device does not support the camera manual focus function.

Discussion

Note: Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannelByToken.

Declared In

AgoraRtcEngineKit.h

– isCameraExposurePositionSupported

Checks whether the camera manual exposure function is supported. (iOS only)

- (BOOL)isCameraExposurePositionSupported

Return Value

  • YES: The device supports the manual exposure function.
  • NO: The device does not support the manual exposure function.

Discussion

Note: Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannelByToken.

Declared In

AgoraRtcEngineKit.h

– isCameraAutoFocusFaceModeSupported

Checks whether the camera auto-face focus function is supported. (iOS only)

- (BOOL)isCameraAutoFocusFaceModeSupported

Return Value

  • YES: The device supports the camera auto-face focus function.
  • NO: The device does not support the camera auto-face focus function.

Discussion

Note: Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannelByToken.

Declared In

AgoraRtcEngineKit.h

– setCameraZoomFactor:

Sets the camera zoom ratio. (iOS only)

- (CGFloat)setCameraZoomFactor:(CGFloat)zoomFactor

Parameters

zoomFactor

Sets the camera zoom factor. The value ranges between 1.0 and the maximum zoom supported by the device.

Return Value

  • The set camera zoom factor, if this method call is successful.
  • < 0: Failure.

Discussion

Note: Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannelByToken.

Declared In

AgoraRtcEngineKit.h

– setCameraFocusPositionInPreview:

Sets the manual focus position. (iOS only)

- (BOOL)setCameraFocusPositionInPreview:(CGPoint)position

Parameters

position

Coordinates of the touch point in the view.

Return Value

  • YES: Success.
  • NO: Failure.

Discussion

A successful setCameraFocusPositionInPreview method call triggers the ocameraFocusDidChangedToRect callback on the local client.

Note: Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannelByToken.

Declared In

AgoraRtcEngineKit.h

– setCameraExposurePosition:

Sets the camera exposure position. (iOS only)

- (BOOL)setCameraExposurePosition:(CGPoint)positionInView

Parameters

positionInView

Coordinates of the touch point in the view.

Return Value

  • YES: Success.
  • NO: Failure.

Discussion

A successful setCameraExposurePosition method call triggers the cameraExposureDidChangedToRect callback on the local client.

Note: Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannelByToken.

Declared In

AgoraRtcEngineKit.h

– setCameraTorchOn:

Sets whether to enable the flash. (iOS only.)

- (BOOL)setCameraTorchOn:(BOOL)isOn

Parameters

isOn

Determines whether to enable the flash:

  • YES: Enable the flash.
  • NO: Do not enable the flash.

Return Value

  • YES: Success.
  • NO: Failure.

Discussion

Note

  • Call this method after the camera is started.
  • On iPads with system version 15, even if isCameraTorchSupported returns YES, you might fail to successfully enable the flash by calling setCameraTorchOn due to system issues.

Declared In

AgoraRtcEngineKit.h

– setCameraAutoFocusFaceModeEnabled:

Sets whether to enable face autofocus. (iOS only.)

- (BOOL)setCameraAutoFocusFaceModeEnabled:(BOOL)enable

Parameters

enable

Determines whether to enable face autofocus:

  • YES: Enable face autofocus.
  • NO: Disable face autofocus.

Return Value

  • YES: Success.
  • NO: Failure.

Discussion

The SDK earlier than v3.5.0 disables face autofocus by default. The SDK v3.5.0 and later enables face autofocus by default. To set face autofocus, call this method.

Note: Call this method after the camera is started.

Declared In

AgoraRtcEngineKit.h

Screen Sharing (macOS)

– startScreenCaptureByDisplayId:rectangle:parameters:

Shares the whole or part of a screen by specifying the display ID. (macOS only.)

- (int)startScreenCaptureByDisplayId:(NSUInteger)displayId rectangle:(CGRect)rectangle parameters:(AgoraScreenCaptureParameters *_Nonnull)captureParams

Parameters

displayId

The display ID of the screen to be shared. This parameter specifies which screen you want to share. For information on how to get the displayId, see Share the Screen.

rectangle

(Optional) The relative location of the region to the screen. nil means sharing the whole screen. This parameter contains the following properties:

  • 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

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

Return Value

  • 0: Success.
  • < 0: Failure.

    • -2(AgoraErrorCodeInvalidArgument): the argument is invalid.

Discussion

Note: Ensure that you call this method after joining a channel.

Declared In

AgoraRtcEngineKit.h

– startScreenCaptureByWindowId:rectangle:parameters:

Shares the whole or part of a window by specifying the window ID. (macOS only.)

- (int)startScreenCaptureByWindowId:(NSUInteger)windowId rectangle:(CGRect)rectangle parameters:(AgoraScreenCaptureParameters *_Nonnull)captureParams

Parameters

windowId

The ID of the window to be shared. This parameter specifies which window you want to share. For information on how to get the windowId, see Share the Screen.

rectangle

(Optional) The relative location of the region to the window. nil means sharing the whole window. This parameter contains the following properties:

  • 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

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

Return Value

  • 0: Success.
  • < 0: Failure.

    • -2(AgoraErrorCodeInvalidArgument): the argument is invalid.

Discussion

Note: Ensure that you call this method after joining a channel.

Declared In

AgoraRtcEngineKit.h

– setScreenCaptureContentHint:

Sets the content hint for screen sharing.

- (int)setScreenCaptureContentHint:(AgoraVideoContentHint)contentHint

Parameters

contentHint

The content hint for screen sharing, see AgoraVideoContentHint.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

You can call this method either before or after you start screen sharing.

Declared In

AgoraRtcEngineKit.h

– updateScreenCaptureParameters:

Updates the screen sharing parameters. (macOS only.)

- (int)updateScreenCaptureParameters:(AgoraScreenCaptureParameters *_Nonnull)captureParams

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 dimensions to calculate the charges. For details, see descriptions in AgoraScreenCaptureParameters.

Return Value

  • 0: Success.
  • < 0: Failure.

    • -3(AgoraErrorCodeNotReady): no screen or windows is being shared.

Declared In

AgoraRtcEngineKit.h

– updateScreenCaptureRegion:

Updates the screen-sharing region. (macOS only.)

- (int)updateScreenCaptureRegion:(CGRect)rect

Parameters

rect

The relative location of the region to the screen or window. nil means sharing the whole screen or window. This parameter contains the following properties:

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

Return Value

  • 0: Success.
  • < 0: Failure.

    • -3(AgoraErrorCodeNotReady): no screen or windows is being shared.

Declared In

AgoraRtcEngineKit.h

– stopScreenCapture

Stops screen sharing. (macOS only.)

- (int)stopScreenCapture

Return Value

  • 0: Success.
  • < 0: Failure.

Declared In

AgoraRtcEngineKit.h

Device Manager (macOS only)

– monitorDeviceChange:

Monitors the change of a device state. (macOS only.)

- (void)monitorDeviceChange:(BOOL)enabled

Parameters

enabled
  • YES: Enable the monitoring of a device state change.
  • NO: Disable the monitoring of a device state change.

Discussion

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

Declared In

AgoraRtcEngineKit.h

– enumerateDevices:

Gets all devices in the system. (macOS only.)

- (NSArray<AgoraRtcDeviceInfo*> *_Nullable)enumerateDevices:(AgoraMediaDeviceType)type

Parameters

type

Device type: AgoraMediaDeviceType.

Return Value

An AgoraRtcDeviceInfo NSArray object including all devices, if this method call is successful.

Discussion

Note:

Do not call this method in the main thread.

This method returns an NSArray object, including all audio/video devices in the system. Your app can use the AgoraRtcDeviceInfo array object to enumerate the devices.

Declared In

AgoraRtcEngineKit.h

– getDeviceInfo:

Gets the information of devices, such as audio sampling and playback device. (macOS only.)

- (AgoraRtcDeviceInfo *_Nullable)getDeviceInfo:(AgoraMediaDeviceType)type

Parameters

type

Device type: AgoraMediaDeviceType.

Return Value

  • The device information (AgoraRtcDeviceInfo), if this method call is successful.
  • nil: Failure.

Declared In

AgoraRtcEngineKit.h

– setDevice:deviceId:

Sets the devices, such as audio sampling and playback device. (macOS only.)

- (int)setDevice:(AgoraMediaDeviceType)type deviceId:(NSString *_Nonnull)deviceId

Parameters

type

Device type: AgoraMediaDeviceType.

deviceId

Device ID of the device, which can be retrieved by calling the enumerateDevicesmethod. deviceId does not change when the device is plugged or unplugged.

Return Value

  • 0: Success.
  • < 0: Failure.

Declared In

AgoraRtcEngineKit.h

– getDeviceVolume:

Gets the specified device’s volume. (macOS only.)

- (int)getDeviceVolume:(AgoraMediaDeviceType)type

Parameters

type

Device type: AgoraMediaDeviceType.

Return Value

  • Returns the volume, if this method call is successful.

  • < 0: Failure.

Declared In

AgoraRtcEngineKit.h

– setDeviceVolume:volume:

Sets the specified device’s volume. (macOS only.)

- (int)setDeviceVolume:(AgoraMediaDeviceType)type volume:(int)volume

Parameters

type

Device type: AgoraMediaDeviceType

volume

Sets the specified device’s volume. The value ranges between 0 and 100.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Note: Call this method after joining a channel.

Declared In

AgoraRtcEngineKit.h

– startRecordingDeviceTest:

Starts the audio sampling device test. (macOS only)

- (int)startRecordingDeviceTest:(int)indicationInterval

Parameters

indicationInterval

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

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

This method tests whether the audio sampling 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 of the sampling device.

Note: Call this method before joining a channel.

Declared In

AgoraRtcEngineKit.h

– stopRecordingDeviceTest

Stops the microphone test. (macOS only.)

- (int)stopRecordingDeviceTest

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

This method stops testing the microphone. You must call this method to stop the test after calling the startRecordingDeviceTest method.

Declared In

AgoraRtcEngineKit.h

– startPlaybackDeviceTest:

Starts the audio playback device test. (macOS only)

- (int)startPlaybackDeviceTest:(NSString *_Nonnull)audioFileName

Parameters

audioFileName

Absolute path of the audio file for the test in UTF-8:

  • Supported file formats: wav, mp3, m4a, and aac.
  • Supported file sample rates: 8000, 16000, 32000, 44100, and 48000 Hz.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

This method tests if 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, which reports uid = 1 and the volume of the playback device.

Note: Call this method before joining a channel.

Declared In

AgoraRtcEngineKit.h

– stopPlaybackDeviceTest

Stops the audio playback device test. (macOS only.)

- (int)stopPlaybackDeviceTest

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

Note: Call this method before joining a channel.

Declared In

AgoraRtcEngineKit.h

– startCaptureDeviceTest:

Starts a video-capture device test. (macOS only.)

- (int)startCaptureDeviceTest:(NSView *_Nonnull)view

Parameters

view

Input parameter for displaying the video window.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

This method tests whether the video-capture device works properly. Ensure that you call the enableVideo method before calling this method and that the parameter view window is valid.

Note: Call this method before joining a channel.

Declared In

AgoraRtcEngineKit.h

– stopCaptureDeviceTest

Stops the video-capture device test. (macOS only.)

- (int)stopCaptureDeviceTest

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

This method stops testing the video-capture device. You must call this method to stop the test after calling the startCaptureDeviceTest method.

Note: Call this method before joining a channel.

Declared In

AgoraRtcEngineKit.h

– startAudioDeviceLoopbackTest:

Starts the audio device loopback test. (macOS only)

- (int)startAudioDeviceLoopbackTest:(int)indicationInterval

Parameters

indicationInterval

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

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

This method tests whether the local audio sampling device and playback device are working properly. After calling this method, the audio sampling device samples the local audio, and the audio playback device plays the sampled audio. The SDK triggers two independent reportAudioVolumeIndicationOfSpeakers callbacks at the time interval set in this method, which reports the following information:

  • uid = 0 and the volume information of the sampling device.
  • uid = 1 and the volume information of the playback device.

Note:

  • This method tests the local audio devices and does not report the network conditions.
  • Call this method before joining a channel.

Declared In

AgoraRtcEngineKit.h

– stopAudioDeviceLoopbackTest

Stops the audio device loopback test. (macOS only.)

- (int)stopAudioDeviceLoopbackTest

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Ensure that you call this method to stop the loopback test after calling the startAudioDeviceLoopbackTest method.

Note: Call this method before joining a channel.

Declared In

AgoraRtcEngineKit.h

Media Metadata

– setMediaMetadataDataSource:withType:

Sets the data source of the metadata.

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

Parameters

metadataDataSource

The AgoraMediaMetadataDataSource protocol.

type

The metadata type. See AgoraMetadataType. Currently, the SDK supports video metadata only.

Return Value

  • YES: Success.
  • NO: Failure.

Discussion

You need to implement the AgoraMediaMetadataDataSource protocol and specify the type of metadata in this method.

Use this method with the setMediaMetadataDelegate method to add synchronized metadata in the video stream. You can create more diversified interactive live streaming interactions, such as sending shopping links, digital coupons, and online quizzes.

Note

  • Call this method before the joinChannelByToken method.
  • This method applies to the interactive live streaming channel profile only.

Declared In

AgoraRtcEngineKit.h

– setMediaMetadataDelegate:withType:

Sets the delegate of the metadata.

- (BOOL)setMediaMetadataDelegate:(id<AgoraMediaMetadataDelegate> _Nullable)metadataDelegate withType:(AgoraMetadataType)type

Parameters

metadataDelegate

The AgoraMediaMetadataDelegate protocol.

type

The metadata type. See AgoraMetadataType. Currently, the SDK supports video metadata only.

Return Value

  • YES: Success.
  • NO: Failure.

Discussion

You need to implement the AgoraMediaMetadataDelegate protocol and specify the type of metadata in this method.

Note

  • Call this method before the joinChannelByToken method.
  • This method applies to the interactive live streaming channel profile only.

Declared In

AgoraRtcEngineKit.h

Miscellaneous Methods

– getAudioFileInfo:

Gets the information of a specified audio file.

- (int)getAudioFileInfo:(NSString *_Nullable)filePath

Parameters

filePath

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

Return Value

  • 0: Success.
  • < 0: Failure.

Availability

v3.5.1

After calling this method successfully, the SDK triggers the didRequestAudioFileInfo callback to report the information of an audio file, such as audio duration. You can call this method multiple times to get the information of multiple audio files.

Note

Declared In

AgoraRtcEngineKit.h

– getCallId

Gets the current call ID.

- (NSString *_Nullable)getCallId

Return Value

callId The current call ID.

Discussion

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

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

Note: Ensure that you call this method after joining a channel.

Declared In

AgoraRtcEngineKit.h

– rate:rating:description:

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

- (int)rate:(NSString *_Nonnull)callId rating:(NSInteger)rating description:(NSString *_Nullable)description

Parameters

callId

Call ID retrieved from the getCallId method.

rating

Rating of the call. The value is between 1 (lowest score) and 5 (highest score). If you set a value out of this range, the AgoraErrorCodeInvalidArgument(-2) error occurs.

description

(Optional) Description of the rating. The string length must be less than 800 bytes.

Return Value

  • 0: Success.
  • < 0: Failure.

    • Return AgoraErrorCodeInvalidArgument(-2):The passed argument is invalid. For example, callId is invalid.
    • Return AgoraErrorCodeNotReady(-3):The SDK status is incorrect. For example, initialization fails.

Discussion

Note: Ensure that you call this method after leaving a channel.

Declared In

AgoraRtcEngineKit.h

– complain:description:

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

- (int)complain:(NSString *_Nonnull)callId description:(NSString *_Nullable)description

Parameters

callId

Call ID retrieved from the getCallId method.

description

(Optional) Description of the complaint. The string length must be less than 800 bytes.

Return Value

  • 0: Success.
  • < 0: Failure.

    • -2(AgoraErrorCodeInvalidArgument): The parameter is invalid.
    • -3(AgoraErrorCodeNotReady): The SDK fails to be initialized. You can try re-initializing the SDK.

Discussion

Note: Ensure that you call this method after leaving a channel.

Declared In

AgoraRtcEngineKit.h

– enableMainQueueDispatch:

Enables/Disables dispatching delegate methods to the main queue.

- (int)enableMainQueueDispatch:(BOOL)enabled

Parameters

enabled

Sets whether to dispatch delegate methods to the main queue:

  • YES: Dispatch delegate methods to the main queue.
  • NO: Do not dispatch delegate methods to the main queue

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

If disabled, the app should dispatch UI operations to the main queue.

Declared In

AgoraRtcEngineKit.h

+ getSdkVersion

Gets the SDK version.

+ (NSString *_Nonnull)getSdkVersion

Return Value

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

Discussion

This method returns the string of the version number.

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

Declared In

AgoraRtcEngineKit.h

+ getErrorDescription:

Gets the description of a warning or error code.

+ (NSString *_Nullable)getErrorDescription:(NSInteger)code

Parameters

code

The warning or error code that the didOccurWarning or didOccurError callback returns.

Return Value

AgoraWarningCode or AgoraErrorCode.

Declared In

AgoraRtcEngineKit.h

– sendCustomReportMessage:category:event:label:value:

Agora supports reporting and analyzing customized messages.

- (int)sendCustomReportMessage:(NSString *_Nonnull)id category:(NSString *_Nonnull)category event:(NSString *_Nonnull)event label:(NSString *_Nonnull)label value:(NSInteger)value

Availability

3.1.0

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

Declared In

AgoraRtcEngineKit.h

– getNativeHandle

Returns the native handler of the SDK engine.

- (void *_Nullable)getNativeHandle

Discussion

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

Declared In

AgoraRtcEngineKit.h

  delegate

Sets and gets the SDK delegate.

@property (nonatomic, weak) id<AgoraRtcEngineDelegate> _Nullable delegate

Discussion

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

Declared In

AgoraRtcEngineKit.h

Deprecated Methods

– pushExternalAudioFrameRawData:samples:timestamp:

Pushes the external raw audio frame data to the SDK for encoding.

- (BOOL)pushExternalAudioFrameRawData:(void *_Nonnull)data samples:(NSUInteger)samples timestamp:(NSTimeInterval)timestamp

Parameters

data

External audio data to be pushed.

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.
  • Synchronize audio and video frames in video-related scenarios, including scenarios where external video sources are used.

Return Value

  • YES: Success.
  • NO: Failure.

Discussion

DeprecatedThis method is deprecated as of v3.5.1. Use pushExternalAudioFrameRawData 2 instead.

Declared In

AgoraRtcEngineKit.h

– pushExternalAudioFrameSampleBuffer:

Pushes the external CMSampleBuffer audio frame to the SDK for encoding.

- (BOOL)pushExternalAudioFrameSampleBuffer:(CMSampleBufferRef _Nonnull)sampleBuffer

Parameters

sampleBuffer

Sample buffer for the push.

Return Value

  • YES: Success.
  • NO: Failure.

Discussion

DeprecatedThis method is deprecated as of v3.5.1. Use pushExternalAudioFrameSampleBuffer 2 instead.

Declared In

AgoraRtcEngineKit.h

– getAudioMixingDuration

Gets the total duration of the current music file.

- (int)getAudioMixingDuration

Return Value

  • ≥ 0: A successful method call. Returns the total duration (ms) of the current music file.
  • < 0: Failure.

Availability

v3.4.0

Discussion

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

Note: Call this method after startAudioMixing.

Declared In

AgoraRtcEngineKit.h

– playEffect:filePath:loopCount:pitch:pan:gain:publish:

Plays a specified audio effect.

- (int)playEffect:(int)soundId filePath:(NSString *_Nullable)filePath loopCount:(int)loopCount pitch:(double)pitch pan:(double)pan gain:(double)gain publish:(BOOL)publish

Parameters

soundId

ID of the specified audio effect. Each audio effect has a unique ID. If the audio effect is preloaded into the memory through the preloadEffect method, ensure that the soundId value is set to the same value as in preloadEffect.

filePath

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

loopCount

Sets the number of times the audio effect loops:

  • 0: Plays the audio effect once.
  • 1: Plays the audio effect twice.
  • -1: Plays the audio effect in an indefinite loop until you call the stopEffect or stopAllEffects method.
pitch

Sets the pitch of the audio effect. The value ranges between 0.5 and 2. The default value is 1 (no change to the pitch). The lower the value, the lower the pitch.

pan

Sets the spatial position of the audio effect. The value ranges between -1.0 and 1.0.

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

Sets the volume of the audio effect. The value ranges between 0.0 and 100.0 (default). The lower the value, the lower the volume of the audio effect.

publish

Sets whether to publish the specified audio effect to the remote stream:

  • YES: The played audio effect is published to the Agora Cloud and the remote users can hear it.
  • NO: The played audio effect is not published to the Agora Cloud and the remote users cannot hear it.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Deprecated from v3.4.0. Use playEffect3 instead.

You can use this method to add specific audio effects for specific scenarios, for example, gaming.

With this method, you can set the loop count, pitch, pan, and gain of the audio effect file and whether the remote user can hear the audio effect.

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

When the audio effect file playback is finished, the SDK triggers the rtcEngineDidAudioEffectFinish callback.

Note

Declared In

AgoraRtcEngineKit.h

– startAudioRecording:sampleRate:quality:

Starts an audio recording on the client.

- (int)startAudioRecording:(NSString *_Nonnull)filePath sampleRate:(NSInteger)sampleRate quality:(AgoraAudioRecordingQuality)quality

Parameters

filePath

Absolute file path of the recording file, for example, /var/mobile/Containers/Data/audio.aac. The string of the filename is in UTF-8.

sampleRate

Sample rate (Hz) of the recording file. Supported values are as follows:

  • 16000
  • (Default) 32000
  • 44100
  • 48000
quality

Audio recording quality. See AgoraAudioRecordingQuality.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Deprecated from v3.4.0. Use startAudioRecordingWithConfig instead.

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

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

Note

  • Ensure that the directory you use to save the recording file exists and is writable.
  • This method is usually called after the joinChannelByToken method. The recording automatically stops when you call the leaveChannel method.
  • For better recording effects, set quality as AgoraAudioRecordingQualityMedium or AgoraAudioRecordingQualityHigh when sampleRate is 44100 Hz or 48000 Hz.

Declared In

AgoraRtcEngineKit.h

– startAudioMixing:loopback:replace:cycle:

Starts audio mixing.

- (int)startAudioMixing:(NSString *_Nonnull)filePath loopback:(BOOL)loopback replace:(BOOL)replace cycle:(NSInteger)cycle

Parameters

filePath

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

loopback

Sets which user can hear the audio mixing:

  • YES: Only the local user can hear the audio mixing.
  • NO: Both users can hear the audio mixing.
replace

Sets the audio mixing content:

  • YES: Only the specified audio file is published; the audio stream received by the microphone is not published.
  • NO: The local audio file mixed with the audio stream from the microphone.
cycle

Sets the number of playback loops:

  • Positive integer: Number of playback loops.
  • -1:Infinite playback loops.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Deprecated from v3.4.0. Use startAudioMixing2 instead.

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

A successful startAudioMixing method call triggers the localAudioMixingStateDidChanged(AgoraAudioMixingStatePlaying) callback on the local client.

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

Note:

  • To avoid blocking, as of v3.4.5, this method changes from a synchronous call to an asynchronous call.
  • If you want to play an online music file, ensure that the time interval between playing the online music file and calling this method is greater than 100 ms, or the AudioFileOpenTooFrequent(702) warning occurs.
  • If the local audio mixing file does not exist, or if the SDK does not support the file format or cannot access the music file URL, the SDK returns AgoraWarningCodeAudioMixingOpenError(701).
  • For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support.

Declared In

AgoraRtcEngineKit.h

– setDefaultMuteAllRemoteVideoStreams:

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

- (int)setDefaultMuteAllRemoteVideoStreams:(BOOL)mute

Parameters

mute

Sets whether to stop subscribing to the video streams of all remote users by default.

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

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Deprecated This method is deprecated from v3.3.0.

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

Note

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

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

Declared In

AgoraRtcEngineKit.h

– setDefaultMuteAllRemoteAudioStreams:

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

- (int)setDefaultMuteAllRemoteAudioStreams:(BOOL)mute

Parameters

mute

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

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Deprecated This method is deprecated from v3.3.0.

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

Note

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

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

Declared In

AgoraRtcEngineKit.h

– setLogFile:

Sets the log files that the SDK outputs.

- (int)setLogFile:(NSString *_Nonnull)filePath

Parameters

filePath

The absolute path of log files. Ensure that the directory for the log files exists and is writable. You can use this parameter to rename the log files.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Deprecated This method is deprecated from v3.3.0. Use the logConfig parameter in sharedEngineWithConfig to set the log file path instead.

By default, the SDK outputs five log files, agorasdk.log, agorasdk_1.log, agorasdk_2.log, agorasdk_3.log, agorasdk_4.log, each with a default size of 1024 KB. These log files are encoded in UTF-8. The SDK writes the latest logs in agorasdk.log. When agorasdk.log is full, the SDK deletes the log file with the earliest modification time among the other four, renames agorasdk.log to the name of the deleted log file, and creates a new agorasdk.log to record latest logs.

Note:

  • The default log file path is as follows:
    • iOS: App Sandbox/Library/caches/agorasdk.log
    • macOS
      • Sandbox enabled: App Sandbox/Library/Logs/agorasdk.log, for example /Users/<username>/Library/Containers/<App Bundle Identifier>/Data/Library/Logs/agorasdk.log.
      • Sandbox disabled: ~/Library/Logs/agorasdk.log.
  • Ensure that you call this method immediately after calling the sharedEngineWithAppId method, otherwise the output logs may not be complete.