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(AgoraRtmpStreamingErrorCodeOK): Success.
  • < 0: Failure.

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

Discussion

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

- (int)setClientRole:(AgoraClientRole)role

Parameters

role

The role of the user:

  • AgoraClientRoleBroadcaster(1): Host. A host can both send and receive streams.
  • AgoraClientRoleAudience(2): Audience, the default role. An audience can only receive streams.

Return Value

  • 0(AgoraRtmpStreamingErrorCodeOK): 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

This method is applicable only to the live interactive streaming profile.

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

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

When a user switches user roles after joining a channel, a successful method call triggers the following callback:

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 for authentication:

  • In situations not requiring high security: You can use the temporary token generated at Agora Console. For details, see Get a temporary token.
  • In situations requiring high security: Set it as the token generated at your server. For details, see Generate a token.
channelId

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

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

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

Return Value

  • 0(AgoraRtmpStreamingErrorCodeOK): 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.

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

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

– 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 null. Supported character scopes are:

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

The token generated at your server:

  • For low-security requirements: You can use the temporary token generated at Console. For details, see Get a temporary token.
  • For high-security requirements: Set it as the token generated at your server. For details, see Get a token.
channelId

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

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

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

Discussion

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

Note: To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the uid of the user is set to the same parameter type.

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 null. Supported character scopes are:

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

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

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

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

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(AgoraRtmpStreamingErrorCodeOK): 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(AgoraRtmpStreamingErrorCodeOK): 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.

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 live interactive 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 the startChannelMediaRelay method to update the destination channel.
  • 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

– 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

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 internal engine and can be called after the leaveChannel method. You can call this method either before or after joining a channel.
  • This method resets the internal engine and takes some time to take effect. 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 internal engine and can be called after the leaveChannel method. You can call this method either before or after joining a channel.
  • This method resets the internal engine and takes some time to take effect. 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 either the in-call volume or the media volume. For details, see What is the difference between the in-call volume and the media volume?.

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 live interactive 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 recording volume.

- (int)adjustRecordingSignalVolume:(NSInteger)volume

Parameters

volume

Recording volume. The value ranges between 0 and 400:

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

Note:

To avoid echoes and improve call quality, Agora recommends setting the value of volume between 0 and 100. If you need to set the value higher than 100, contact support@agora.io first.

Return Value

  • 0: Success.
  • < 0: Failure.

Declared In

AgoraRtcEngineKit.h

– adjustPlaybackSignalVolume:

Adjusts the playback volume of all remote users.

- (int)adjustPlaybackSignalVolume:(NSInteger)volume

Parameters

volume

The playback volume of all remote users. The value ranges from 0 to 400:

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

Note:

To avoid echoes and improve call quality, Agora recommends setting the value of volume between 0 and 100. If you need to set the value higher than 100, contact support@agora.io first.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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 SDK to regularly report to the app on which users are speaking and the speakers' volume.

- (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. Once this method is enabled, the SDK returns the volume indications at the set time interval in the reportAudioVolumeIndicationOfSpeakers and audioVolumeIndicationBlock callbacks, regardless of whether any user is speaking in the channel.
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.

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 or playing 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 is different from the muteLocalAudioStream method:

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

Declared In

AgoraRtcEngineKit.h

– muteLocalAudioStream:

Sends/Stops sending the local audio stream.

- (int)muteLocalAudioStream:(BOOL)mute

Parameters

mute

Sets whether to send/stop sending the local audio stream:

  • YES: Stops sending the local audio stream.
  • NO: (Default) Sends the local audio stream.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Use this method to stop/start sending the local audio stream. A successful muteLocalAudioStream method call triggers the didAudioMuted callback on the remote client.

Note:

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

Declared In

AgoraRtcEngineKit.h

– muteRemoteAudioStream:mute:

Receives/Stops receiving a specified remote user’s audio stream.

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

Parameters

uid

User ID of the specified remote user.

mute

Sets whether to receive/stop receiving a specified remote user’s audio stream:

  • YES: Stop receiving a specified remote user’s audio stream.
  • NO: (Default) Receive a specified remote user’s audio stream.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Note:

If you call the muteAllRemoteAudioStreams method and set mute as YES to mute all remote audio streams, call the muteAllRemoteAudioStreams method again and set mute as NO before calling this method. The muteAllRemoteAudioStreams method sets all remote streams, while the muteRemoteAudioStream method sets a specified stream.

Declared In

AgoraRtcEngineKit.h

– muteAllRemoteAudioStreams:

Receives/Stops receiving all remote audio streams.

- (int)muteAllRemoteAudioStreams:(BOOL)mute

Parameters

mute

Sets whether to receive/stop receiving all remote audio streams:

  • YES: Stop receiving all remote audio streams.
  • NO: (Default) Receive all remote audio streams.

Return Value

  • 0: Success.
  • < 0: Failure.

Declared In

AgoraRtcEngineKit.h

– setDefaultMuteAllRemoteAudioStreams:

Sets whether to receive all remote audio streams by default.

- (int)setDefaultMuteAllRemoteAudioStreams:(BOOL)mute

Parameters

mute

Sets whether to receive/stop receiving all remote audio streams by default:

  • YES: Stop receiving all remote audio streams by default.
  • NO: (Default) Receive all remote audio streams by default.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

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

Declared In

AgoraRtcEngineKit.h

– adjustUserPlaybackSignalVolume:volume:

Adjust the playback 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 from 0 to 100:

  • 0: Mute.
  • 100: Original volume.

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.

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.

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 and the video.

- (int)stopPreview

Return Value

  • 0: Success.
  • < 0: Failure.

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 didLocalVideoEnabled callback on the remote client.

Note:

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

Declared In

AgoraRtcEngineKit.h

– muteLocalVideoStream:

Sends/Stops sending the local video stream.

- (int)muteLocalVideoStream:(BOOL)mute

Parameters

mute

Sets whether to send/stop sending the local video stream:

  • YES: Stop sending the local video stream.
  • NO: (Default) Send the local video stream.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

Note:

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

Declared In

AgoraRtcEngineKit.h

– muteAllRemoteVideoStreams:

Receives/Stops receiving all remote video streams.

- (int)muteAllRemoteVideoStreams:(BOOL)mute

Parameters

mute

Sets whether to receive/stop receiving all remote video streams:

  • YES: Stops receiving all remote video streams.
  • NO: (Default) Receives all remote video streams.

Return Value

  • 0: Success.
  • < 0: Failure.

Declared In

AgoraRtcEngineKit.h

– muteRemoteVideoStream:mute:

Receives/Stops receiving a specified remote user’s video stream.

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

Parameters

uid

User ID of the specified remote user.

mute

Sets whether to receive/stop receiving a specified remote user’s video stream.

  • YES: Stops receiving a specified remote user’s video stream.
  • NO: (Default) Receives a specified remote user’s video stream.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Note:

If you call the muteAllRemoteVideoStreams method and set mute as YES to stop receiving all remote video streams, call the muteAllRemoteVideoStreams method again and set mute as NO before calling this method.

Declared In

AgoraRtcEngineKit.h

– setDefaultMuteAllRemoteVideoStreams:

Sets whether to receive all remote video streams by default.

- (int)setDefaultMuteAllRemoteVideoStreams:(BOOL)mute

Parameters

mute

Sets whether to receive/stop receiving all remote video streams by default.

  • YES: Stop receiving all remote video streams by default.
  • NO: (Default) Receive all remote video streams by default.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

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

Declared In

AgoraRtcEngineKit.h

Video Pre-Process and Post-Process

– setBeautyEffectOptions:options:

Enables/Disables image enhancement and sets the options. (iOS only)

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

Parameters

enable

Sets whether or not to enable image enhancement:

  • YES: enables image enhancement.
  • NO: disables 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

Audio Routing Controller

– setDefaultAudioRouteToSpeakerphone:

Sets the default audio route. (iOS only.)

- (int)setDefaultAudioRouteToSpeakerphone:(BOOL)defaultToSpeaker

Parameters

defaultToSpeaker

Sets the default audio route:

  • YES: Route the audio to the speakerphone. If the playback device connects to the earpiece or Bluetooth, the audio cannot be routed to the speakerphone.
  • NO: (Default) Route the audio to the earpiece. If a headset is plugged in, the audio is routed to the headset.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

If you need to change the default audio route after joining a channel, call the setEnableSpeakerphone method.

Note:

  • This method is applicable only to the Communication profile.
  • This method only works in a voice call.
  • Call this method before calling the joinChannelByToken method.

The default settings for each profile:

  • Communication: Earpiece.
  • Live Broadcast: Speakerphone.

Declared In

AgoraRtcEngineKit.h

– setEnableSpeakerphone:

Enables/Disables the audio route to the speakerphone. (iOS only.)

- (int)setEnableSpeakerphone:(BOOL)enableSpeaker

Parameters

enableSpeaker

Sets whether to route the audio to the speakerphone or earpiece:

  • YES: Route the audio to the speakerphone.
  • NO: Route the audio to the earpiece. If a headset is plugged in, the audio is routed to the headset.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

This method sets whether the audio is routed to the speakerphone. After this method is called, the SDK returns the didAudioRouteChanged callback, indicating that the audio route changes.

Note:

  • Ensure that you have successfully called the joinChannelByToken method before calling this method.
  • The SDK calls setCategory(AVAudioSessionCategoryPlayAndRecord) with options to configure the headset/speakerphone, so this method applies to all audio playback in the system.

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.

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

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

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

Declared In

AgoraRtcEngineKit.h

Audio Sound 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.

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

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

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

Declared In

AgoraRtcEngineKit.h

– setLocalVoiceChanger:

Sets the local voice changer option.

- (int)setLocalVoiceChanger:(AgoraAudioVoiceChanger)voiceChanger

Parameters

voiceChanger

The local voice changer option. The default value is `AgoraAudioVoiceChangerOff`, which means the original voice. See details in [AgoraAudioVoiceChanger](../Constants/AgoraAudioVoiceChanger.html).

Gender-based beatification effect works best only when assigned a proper gender:

  • For male: AgoraAudioGeneralBeautyVoiceMaleMagnetic.
  • For female: AgoraAudioGeneralBeautyVoiceFemaleFresh or AgoraAudioGeneralBeautyVoiceFemaleVitality.
  • Failure to do so can lead to voice distortion.

    Return Value

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

    Discussion

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

    Voice effect Description Scenario
    AgoraAudioVoiceChanger* Changes the local voice to an old man, a little boy, or the Hulk. Voice talk
    AgoraAudioVoiceBeauty* Beautifies the local voice by making it sound more vigorous, resounding, or adding spacial resonance. Voice talkSinging
    AgoraAudioGeneralBeautyVoice* Adds gender-based beautification effect to the local voice:
  • For a male voice: Adds magnetism to the voice.
  • For a female voice: Adds freshness or vitality to the voice.
  • Voice talk

    Note:

    • To achieve better voice effect quality, Agora recommends setting the profile parameter in setAudioProfile as AgoraAudioProfileMusicHighQuality(4) or AgoraAudioProfileMusicHighQualityStereo(5).
    • This method works best with the human voice, and Agora does not recommend using it for audio containing music and a human voice.
    • Do not use this method with setLocalVoiceReverbPreset, because the method called later overrides the one called earlier. For detailed considerations, see the advanced guide Voice Changer and Reverberation.

    Declared In

    AgoraRtcEngineKit.h

    – setLocalVoiceReverbPreset:

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

    - (int)setLocalVoiceReverbPreset:(AgoraAudioReverbPreset)reverbPreset

    Parameters

    reverbPreset

    The local voice reverberation option. The default value is AgoraAudioReverbPresetOff, which means the original voice. See details in AgoraAudioReverbPreset.

    Note

    To achieve better voice effects, Agora recommends the enumeration whose name begins with AgoraAudioReverbPresetFx.

    Return Value

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

    Discussion

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

    Note:

    • When calling this method with enumerations that begin with AgoraAudioReverbPresetFx, ensure that you set profile in setAudioProfile as AgoraAudioProfileMusicHighQuality(4) or AgoraAudioProfileMusicHighQualityStereo(5). Otherwise, this method call does not take effect.
    • When calling this method with AgoraAudioReverbPresetVirtualStereo, Agora recommends setting the profile parameter in setAudioProfile as AgoraAudioProfileMusicHighQualityStereo(5).
    • This method works best with the human voice, and Agora does not recommend using it for audio containing music and a human voice.
    • Do not use this method with setLocalVoiceChanger, because the method called later overrides the one called earlier. For detailed considerations, see the advanced guide Voice Changer and Reverberation.

    Declared In

    AgoraRtcEngineKit.h

    – enableSoundPositionIndication:

    Enables/Disables stereo panning for remote users.

    - (int)enableSoundPositionIndication:(BOOL)enabled

    Parameters

    enabled

    Sets whether or not 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:

    • 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 stereo headset.
      • (macOS) A stereo loudspeaker.

    Declared In

    AgoraRtcEngineKit.h

    Music File Playback and Mixing

    – 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 of the local or online audio file to be mixed, for example, /var/mobile/Containers/Data/audio.mp4. Agora recommends entering the file suffix. If you cannot determine the file suffix type, then leave it blank. Supported audio formats: mp3, aac, mp4, m4a, 3gp, and wav.

    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

    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 use this method, ensure that the iOS device version is 8.0 and later.
    • Call this method when you are in a channel.
    • 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).

    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

    – 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

    Call this method when you are in a channel.

    Note:

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

    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

    Call this method when you are in a channel.

    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

    Call this method when you are in a channel.

    Declared In

    AgoraRtcEngineKit.h

    – getAudioMixingPublishVolume

    Gets the audio mixing volume for publishing.

    - (int)getAudioMixingPublishVolume

    Discussion

    This method helps troubleshoot audio volume related issues.

    Declared In

    AgoraRtcEngineKit.h

    – getAudioMixingPlayoutVolume

    Gets the audio mixing volume for local playback.

    - (int)getAudioMixingPlayoutVolume

    Discussion

    This method helps troubleshoot audio volume related issues.

    Declared In

    AgoraRtcEngineKit.h

    – getAudioMixingDuration

    Retrieves the duration (ms) of audio mixing.

    - (int)getAudioMixingDuration

    Return Value

    • ≥ 0: The audio mixing duration, if this method call is successful.

    • < 0: Failure.

    Discussion

    Call this method when you are in a channel.

    Declared In

    AgoraRtcEngineKit.h

    – getAudioMixingCurrentPosition

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

    - (int)getAudioMixingCurrentPosition

    Return Value

    • ≥ 0: The current playback position of the audio mixing file, if this method call is successful.

    • < 0: Failure.

    Discussion

    Call this method when you are in a channel.

    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.

    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

    Retrieves 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

    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.

    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.

    Declared In

    AgoraRtcEngineKit.h

    – enableFaceDetection:

    Enables/Disables face detection for the local user.

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

    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

    Specifies the absolute path to the local audio effect file or the URL of the online audio effect file, for example, /var/mobile/Containers/Data/audio.mp4. Agora recommends entering the file suffix. If you cannot determine the file suffix type, then leave it blank. Supported audio formats: mp3, mp4, m4a, aac, 3gp, mkv and wav.

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

    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: Playing multiple online audio effect files simultaneously is not supported on macOS.

    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.

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

    Note: This method does not support online audio effect files.

    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

    Audio Recorder

    – 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

    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

    – stopAudioRecording

    Stops an audio recording on the client.

    - (int)stopAudioRecording

    Return Value

    • 0: Success.
    • < 0: Failure.

    Discussion

    Note:

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

    Declared In

    AgoraRtcEngineKit.h

    Loopback Recording

    – enableLoopbackRecording:deviceName:

    Enables loopback recording. (macOS only)

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

    Parameters

    enabled

    Sets whether to enable/disable loopback recording.

    • YES: Enable loopback recording.
    • NO: (Default) Disable loopback recording.
    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 recording, the output of the sound card is mixed into the audio stream sent to the other end.

    Note:

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

    Declared In

    AgoraRtcEngineKit.h

    Miscellaneous Audio Control

    – setAudioSessionOperationRestriction:

    Sets the audio session’s operational restriction. (iOS only.)

    - (void)setAudioSessionOperationRestriction:(AgoraAudioSessionOperationRestriction)restriction

    Parameters

    restriction

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

    Discussion

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

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

    Note:

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

    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 recording 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, you record your voice. If the recording plays back within the set time interval, the audio devices and the network connection are working properly.

    Note:

    • Call this method before joining a channel.

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

    • In the live interactive 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 live interactive 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 live interactive 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.

    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.

    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.

    Declared In

    AgoraRtcEngineKit.h

    – videoSource

    Retrieves the video source.

    - (id<AgoraVideoSourceProtocol> _Nullable)videoSource

    Return Value

    Video source. See AgoraVideoSourceProtocol.

    Declared In

    AgoraRtcEngineKit.h

    – localVideoRenderer

    Retrieves the local video renderer.

    - (id<AgoraVideoSinkProtocol> _Nullable)localVideoRenderer

    Return Value

    Local video renderer. See AgoraVideoSinkProtocol.

    Declared In

    AgoraRtcEngineKit.h

    – remoteVideoRendererOfUserId:

    Retrieves 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

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

    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

    • 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

    • 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 joining the channel.

    Declared In

    AgoraRtcEngineKit.h

    – disableExternalAudioSource

    Disables the external audio source.

    - (void)disableExternalAudioSource

    Declared In

    AgoraRtcEngineKit.h

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

    • 0: Success.
    • < 0: Failure.

    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.

    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 or not to use an external video source:

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

    Sets whether or not 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

    If an external video source is used, call this method before the enableVideo or startPreview method.

    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.

    Declared In

    AgoraRtcEngineKit.h

    Raw Audio Data

    – setRecordingAudioFrameParametersWithSampleRate:channel:mode:samplesPerCall:

    Sets the audio recording format for the onRecordAudioFrame callback.

    - (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 streaming.

    Return Value

    • 0: Success.
    • < 0: Failure.

    Discussion

    See Raw Audio Data.

    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 for the onPlaybackAudioFrame callback.

    - (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 streaming.

    Return Value

    • 0: Success.
    • < 0: Failure.

    Discussion

    See Raw Audio Data.

    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 mixed audio format for the onMixedAudioFrame callback.

    - (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 streaming.

    Return Value

    • 0: Success.
    • < 0: Failure.

    Discussion

    See Raw Audio Data.

    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

    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 live interactive streaming. Once the watermark image is added, all the audience in the channel (CDN audience included), and the recording 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.

    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.

    Declared In

    AgoraRtcEngineKit.h

    Dual-stream Mode

    – enableDualStreamMode:

    Enables/Disables dual-stream mode. (Live interactive 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.

    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.

    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.

    Declared In

    AgoraRtcEngineKit.h

    Encryption

    – enableEncryption:encryptionConfig:

    Enables/Disables the built-in encryption.

    - (int)enableEncryption:(bool)enabled encryptionConfig:(AgoraEncryptionConfig *)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.

    All users in the same channel must use the same encryption mode and encryption key. Once all users leave the channel, the encryption key of this channel is automatically cleared.

    Note

    • If you enable the built-in encryption, you cannot use the RTMP streaming function.
    • Agora supports four encryption modes. If you choose an encryption mode (excepting SM4_128_ECB mode), you need to add an external encryption library when integrating the SDK. See Channel Encryption.

    Declared In

    AgoraRtcEngineKit.h

    Inject an Online Media Stream

    – addInjectStreamUrl:config:

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

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

    Parameters

    url

    URL address to be added to the ongoing live interactive 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.

    Note:

    • 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 RTMP URL address from the live interactive 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 live interactive streaming.

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

    Declared In

    AgoraRtcEngineKit.h

    CDN Live Streaming

    – addPublishStreamUrl:transcodingEnabled:

    Publishes the local stream to the CDN.

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

    Parameters

    url

    The CDN streaming URL in the RTMP format. The maximum length of this parameter is 1024 bytes. The RTMP URL address 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

    This method call 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 live interactive 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.

    Declared In

    AgoraRtcEngineKit.h

    – removePublishStreamUrl:

    Removes an RTMP stream from the CDN.

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

    Parameters

    url

    The RTMP URL address to be removed. The maximum length of this parameter is 1024 bytes.

    Return Value

    • 0: Success.
    • < 0: Failure.

    Discussion

    This method removes the RTMP URL address 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 stream from the CDN.

    Note:

    • This method applies to the live interactive 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

    • This method applies to the live interactive 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.

    Declared In

    AgoraRtcEngineKit.h

    Data Stream

    – createDataStream:reliable:ordered:

    Creates a data stream.

    - (int)createDataStream:(NSInteger *_Nonnull)streamId reliable:(BOOL)reliable ordered:(BOOL)ordered

    Parameters

    streamId

    ID of the created data stream.

    reliable

    Sets whether or not the recipients are guaranteed to receive the data stream from the sender within five seconds:

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

    Sets whether or not the recipients receive the data stream in the sent order:

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

    Return Value

    • 0: Success.
    • < 0: Failure.

    Discussion

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

    Note:

    Set both the reliable and ordered parameters to YES or NO. Do not set one as YES and the other as NO.

    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 live interactive streaming profile. If an audience in the live interactive 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 live interactive 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).

    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.

    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.

    Declared In

    AgoraRtcEngineKit.h

    – isCameraTorchSupported

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

    - (BOOL)isCameraTorchSupported

    Return Value

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

    Discussion

    Note:

    The app generally enables the front camera by default. If your front camera flash is not supported, this method returns NO. If you want to check if the rear camera flash is supported, call the switchCamera method before calling this method.

    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.

    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.

    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.

    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.

    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.

    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.

    Declared In

    AgoraRtcEngineKit.h

    – setCameraTorchOn:

    Enables the camera flash function. (iOS only.)

    - (BOOL)setCameraTorchOn:(BOOL)isOn

    Parameters

    isOn
    • YES: Enable the camera flash function.
    • NO: Disable the camera flash function.

    Return Value

    • YES: Success.
    • NO: Failure.

    Declared In

    AgoraRtcEngineKit.h

    – setCameraAutoFocusFaceModeEnabled:

    Enables the camera auto-face focus function. (iOS only.)

    - (BOOL)setCameraAutoFocusFaceModeEnabled:(BOOL)enable

    Parameters

    enable
    • YES: Enable the camera auto-face focus function.
    • NO: (Default) Disable the camera auto-face focus function.

    Return Value

    • YES: Success.
    • NO: Failure.

    Declared In

    AgoraRtcEngineKit.h

    Screen Sharing

    – 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, see AgoraScreenCaptureParameters.

    Return Value

    • 0: Success.
    • < 0: Failure.

      • ERR_INVALID_STATE: the screen sharing state is invalid, probably because another screen or window is being shared. Call stopScreenCapture to stop the current screen sharing.
      • ERR_INVALID_ARGUMENT: the argument is invalid.

    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 window sharing encoding parameters, see AgoraScreenCaptureParameters.

    Return Value

    • 0: Success.
    • < 0: Failure.

      • ERR_INVALID_STATE: the window sharing state is invalid, probably because another screen or window is being shared. Call stopScreenCapture to stop sharing the current window.
      • ERR_INVALID_ARGUMENT: the argument is invalid.

    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.

    Declared In

    AgoraRtcEngineKit.h

    – updateScreenCaptureParameters:

    Updates the screen sharing parameters. (macOS only.)

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

    Parameters

    captureParams

    The screen sharing encoding parameters, see AgoraScreenCaptureParameters.

    Return Value

    • 0: Success.
    • < 0: Failure.

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

      • ERR_NOT_READY: 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:

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

    Retrieves the device information; such as a recording, playback, or video-capture 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 playback, recording, or audio-sampling 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:

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

    Declared In

    AgoraRtcEngineKit.h

    – startRecordingDeviceTest:

    Starts the microphone test. (macOS only.)

    - (int)startRecordingDeviceTest:(int)indicationInterval

    Parameters

    indicationInterval

    Interval period (ms) of the reportAudioVolumeIndicationOfSpeakers callback cycle.

    Return Value

    • 0: Success.
    • < 0: Failure.

    Discussion

    This method tests whether the microphone works properly. Once the test starts, the SDK reports the volume information by using the reportAudioVolumeIndicationOfSpeakers callback.

    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 an 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 playback device works properly. Once the test starts, the SDK plays an audio file specified by the user, and uses the reportAudioVolumeIndicationOfSpeakers callback to notify the application with the volume information. If the user can hear the audio, the playback device works properly.

    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.

    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.

    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.

    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 setting it as greater than 200 ms. The minimum value is 10 ms.

    Return Value

    • 0: Success.
    • < 0: Failure.

    Discussion

    This method tests whether the local audio devices are working properly. After calling this method, the microphone captures the local audio and plays it through the speaker. The reportAudioVolumeIndicationOfSpeakers callback returns the local audio volume information at the set interval.

    Note:

    This method tests the local audio devices and does not report the network conditions.

    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.

    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 live interactive 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 live interactive 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 live interactive streaming channel profile only.

    Declared In

    AgoraRtcEngineKit.h

    Miscellaneous Methods

    – getCallId

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

    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.

    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.

    Declared In

    AgoraRtcEngineKit.h

    – enableMainQueueDispatch:

    Enables/Disables dispatching delegate methods to the main queue.

    - (int)enableMainQueueDispatch:(BOOL)enabled

    Parameters

    enabled

    Sets whether or not 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

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

    Declared In

    AgoraRtcEngineKit.h

    + getErrorDescription:

    Retrieves 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

    – 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

    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.

    Declared In

    AgoraRtcEngineKit.h

    – setLogFilter:

    Sets the output log level of the SDK.

    - (int)setLogFilter:(NSUInteger)filter

    Parameters

    filter

    Log filter level: AgoraLogFilter.

    Return Value

    • 0: Success.
    • < 0: Failure.

    Discussion

    You can use one or a combination of the filters. The log level follows the sequence of Off, Critical, Error, Warning, Info and Debug. Choose a level to see the logs preceding that level.

    For example, if you set the log level to Warning, you see the logs within levels Critical, Error, and Warning.

    Declared In

    AgoraRtcEngineKit.h

    – setLogFileSize:

    Sets the size of a log file that the SDK outputs.

    - (int)setLogFileSize:(NSUInteger)fileSizeInKBytes

    Parameters

    fileSizeInKBytes

    The size (KB) of a log file. The default value is 1024 KB. If you set fileSizeInKByte to 1024 KB, the SDK outputs at most 5 MB log files; if you set it to less than 1024 KB, the maximum size of a log file is still 1024 KB.

    Return Value

    • 0: Success.
    • < 0: Failure.

    Discussion

    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 create a new agorasdk.log to record latest logs.

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

    – setEncryptionSecret:

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

    - (int)setEncryptionSecret:(NSString *_Nullable)secret

    Parameters

    secret

    Encryption password.

    Return Value

    • 0: Success.
    • < 0: Failure.

    Discussion

    DEPRECATED from v3.1.0. Use enableEncryption instead.

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

    If the encryption password is not specified or set to empty, the encryption functionality is disabled.

    Note:

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

    Declared In

    AgoraRtcEngineKit.h

    – setEncryptionMode:

    Sets the built-in encryption mode.

    - (int)setEncryptionMode:(NSString *_Nullable)encryptionMode

    Parameters

    encryptionMode

    Sets the encryption mode.

    • “aes-128-xts”: (default) 128-bit AES encryption, XTS mode.
    • “aes-256-xts”: 256-bit AES encryption, XTS mode.
    • “aes-128-ecb”: 128-bit AES encryption, ECB mode.

    When encryptionMode is set as NULL, the encryption mode is set as “aes-128-xts” by default.

    Return Value

    • 0: Success.
    • < 0: Failure.

    Discussion

    DEPRECATED from v3.1.0. Use enableEncryption instead.

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

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

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

    Note:

    • Call the setEncryptionSecret method to enable the built-in encryption function before calling this method.
    • Do not use this method for CDN live streaming.

    Declared In

    AgoraRtcEngineKit.h

    – setLocalRenderMode:

    Sets the local video display mode.

    - (int)setLocalRenderMode:(AgoraVideoRenderMode)mode

    Parameters

    mode

    Sets the local video display mode. See AgoraVideoRenderMode.

    Return Value

    • 0: Success.
    • < 0: Failure.

    Discussion

    DEPRECATED from v3.0.0, use the new setLocalRenderMode method instead.

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

    Declared In

    AgoraRtcEngineKit.h

    – setRemoteRenderMode:mode:

    Sets the remote video display mode.

    - (int)setRemoteRenderMode:(NSUInteger)uid mode:(AgoraVideoRenderMode)mode

    Parameters

    uid

    User ID of the remote user sending the video streams.

    mode

    Sets the remote video display mode. See AgoraVideoRenderMode.

    Return Value

    • 0: Success.
    • < 0: Failure.

    Discussion

    DEPRECATED from v3.0.0, use the new setRemoteRenderMode method instead.

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

    Declared In

    AgoraRtcEngineKit.h

    – setLocalVideoMirrorMode:

    Sets the local video mirror mode.

    - (int)setLocalVideoMirrorMode:(AgoraVideoMirrorMode)mode

    Parameters

    mode

    Sets the local video mirror mode. See AgoraVideoMirrorMode.

    Return Value

    • 0: Success.
    • < 0: Failure.

    Discussion

    DEPRECATED from v3.0.0, use the setupLocalVideo or setLocalRenderMode method instead.

    Use this method before calling the startPreview method, or the mirror mode does not take effect until you re-enable startPreview.

    Warning: Call this method after calling the initializing the local video view by calling setupLocalVideo.

    Declared In

    AgoraRtcEngineKit.h

    – enableWebSdkInteroperability:

    Enables interoperability with the Agora Web SDK.

    - (int)enableWebSdkInteroperability:(BOOL)enabled

    Parameters

    enabled

    Sets whether to enable/disable interoperability with the Agora Web SDK:

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

    Return Value

    • 0: Success.
    • < 0: Failure.

    Discussion

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

    • This method is applicable to the live interactive streaming profile only. In the Communication profile, the SDK is interoperable with the Web SDK by default.
    • If the channel has Web SDK users, ensure that you call this method, or the video of the Native user will be a black screen for the Web user.

    Declared In

    AgoraRtcEngineKit.h

    – addVideoWatermark:

    Adds a watermark image to the local video or CDN live stream.

    - (int)addVideoWatermark:(AgoraImage *_Nonnull)watermark

    Parameters

    watermark

    Watermark image to be added to the local video stream. See AgoraImage.

    Return Value

    • 0: Success.
    • < 0: Failure.

    Discussion

    DEPRECATED from v2.9.1. Use the new addVideoWatermark method.

    This method adds a PNG watermark to the local video stream for the recording device, channel audience, or CDN live audience to see and capture.

    To add the PNG file onto a CDN live publishing stream only, see the setLiveTranscoding method.

    Note:

    • The URL descriptions are different for the local video and CDN live streams:
      • In a local video stream, url in AgoraImage refers to the local file path of the added watermark image file in the local video stream.
      • In a CDN live stream, url in AgoraImage refers to the URL address of the added watermark image in the CDN live streaming.
    • The source file of the watermark image must be in the PNG file format. If the width and height of the PNG file differ from your settings in this method, the PNG file is cropped to conform to your settings.
    • The SDK supports adding only one watermark image onto a local video or CDN live stream. The newly added watermark image replaces the previous one.
    • If you set orientationMode as Adaptive in the setVideoEncoderConfiguration method, the watermark image rotates with the video frame and rotates around the upper left corner of the watermark image.

    Declared In

    AgoraRtcEngineKit.h

    – startAudioRecording:quality:

    Starts an audio recording.

    - (int)startAudioRecording:(NSString *_Nonnull)filePath quality:(AgoraAudioRecordingQuality)quality

    Parameters

    filePath

    Absolute file path of the recording file. The string of the file name is in UTF-8.

    quality

    Sets the audio recording quality. See AgoraAudioRecordingQuality.

    Return Value

    • 0: Success.
    • < 0: Failure.

    Discussion

    DEPRECATED from v2.9.1. Use the new startAudioRecording method instead.

    This method has a fixed sample rate of 32 kHz.

    The SDK allows recording during a call. Supported formats:

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

    Ensure that the directory to save the recording file exists and is writable. You can call this method after calling the joinChannelByToken method. The recording automatically stops when you call the leaveChannel method.

    Declared In

    AgoraRtcEngineKit.h

    – startEchoTest:

    Starts an audio call test.

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

    Parameters

    successBlock

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

    Return Value

    • 0: Success.
    • < 0: Failure.

    Discussion

    DEPRECATED from v2.4.

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

    To conduct the test:

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

    Note:

    • After calling this method, always call the stopEchoTest method to end the test. Otherwise, the app cannot run the next echo test, nor can it call the joinChannelByToken method to start a new call.
    • In the live interactive streaming profile, only the hosts can call this method. If the user switches from the Communication to live interactive streaming profile, the user must call the setClientRole method to change the user role from an audience (default) to a host before calling this method.

    Declared In

    AgoraRtcEngineKit.h

    – setVideoQualityParameters:

    Sets the preferences for the video quality. (Live interactive streaming only).

    - (int)setVideoQualityParameters:(BOOL)preferFrameRateOverImageQuality

    Parameters

    preferFrameRateOverImageQuality

    Sets the video quality preference:

    • YES: Frame rate over image quality.
    • NO: (Default) Image quality over frame rate.

    Return Value

    • 0: Success.
    • < 0: Failure.

    Discussion

    DEPRECATED from v2.4.

    Under unreliable network connections or the device’s CPU is overloaded, the video quality may be affected. You can use this method to choose the video smoothness (frame rate) over the image quality or vice versa.

    Declared In

    AgoraRtcEngineKit.h

    + sharedEngineWithAppId:error:

    Initializes the AgoraRtcEngineKit object.

    + (instancetype _Nonnull)sharedEngineWithAppId:(NSString *_Nonnull)AppId error:(void ( ^ _Nullable ) ( AgoraErrorCode errorCode ))errorBlock

    Parameters

    AppId

    App ID issued to you by Agora. Apply for a new App ID from Agora if it is missing from your kit. Each project is assigned a unique App ID. The App ID identifies your project and organization in the joinChannelByToken method to access the Agora Global Network, and enable one-to-one or one-to-more communication or the live interactive streaming sessions using a unique channel name for your App ID.

    errorBlock

    Error code: AgoraErrorCode.

    Discussion

    DEPRECATED from v2.3.

    Declared In

    AgoraRtcEngineKit.h

    – pauseAudio

    Disables the audio function in a channel.

    - (int)pauseAudio

    Return Value

    • 0: Success.
    • < 0: Failure.

    Discussion

    DEPRECATED from v2.3

    See Also

    Declared In

    AgoraRtcEngineKit.h

    – resumeAudio

    Resumes the audio in a channel.

    - (int)resumeAudio

    Return Value

    • 0: Success.
    • < 0: Failure.

    Discussion

    DEPRECATED from v2.3

    See Also

    Declared In

    AgoraRtcEngineKit.h

    – setHighQualityAudioParametersWithFullband:stereo:fullBitrate:

    Sets the high-quality audio parameters.

    - (int)setHighQualityAudioParametersWithFullband:(BOOL)fullband stereo:(BOOL)stereo fullBitrate:(BOOL)fullBitrate

    Parameters

    fullband

    Sets whether to enable/disable full-band codec (48 kHz sample rate). Not compatible with versions earlier than v1.7.4.

    • YES: Enable full-band codec.
    • NO: Disable full-band codec.
    stereo

    Sets whether to enable/disable stereo codec. Not compatible with versions earlier than v1.7.4.

    • YES: Enable stereo codec.
    • NO: Disable stereo codec.
    fullBitrate

    Sets whether to enable/disable high-bitrate mode. Recommended in voice-only mode.

    • YES: Enable high-bitrate mode.
    • NO: Disable high-bitrate mode.

    Return Value

    • 0: Success.
    • < 0: Failure.

    Discussion

    Replaced with setAudioProfile.

    DEPRECATED from v2.3.

    Declared In

    AgoraRtcEngineKit.h

    – setSpeakerphoneVolume:

    Sets the speakerphone volume. (macOS only.)

    - (int)setSpeakerphoneVolume:(NSUInteger)volume

    Parameters

    volume

    Sets the speakerphone volume. The value ranges between 0 (lowest volume) and 255 (highest volume).

    Return Value

    • 0: Success.
    • < 0: Failure.

    Discussion

    DEPRECATED from v2.3.

    See Also

    Declared In

    AgoraRtcEngineKit.h

    – startScreenCapture:withCaptureFreq:bitRate:andRect:

    Starts screen sharing. (macOS only.)

    - (int)startScreenCapture:(NSUInteger)windowId withCaptureFreq:(NSInteger)captureFreq bitRate:(NSInteger)bitRate andRect:(CGRect)rect

    Parameters

    windowId

    Sets to share the whole screen, a specified window, or a specified region: * Share the whole screen: Set windowId as 0 and set rect as nil. * Share the specified window: Set windowId not as 0. Each window has a windowId that is not 0. * Share the specified region: Set windowId as 0 and set rect not as nil. You can share the specified region, for example by dragging the mouse (the logic is implemented by yourself). The specified region is a region on the whole screen. Currently, sharing a specified region in a specific window is not supported.

    captureFreq

    (Mandatory) The captured frame rate. The value ranges between 1 fps and 15 fps.

    bitRate

    The captured bitrate.

    rect

    Specifies the screen-sharing region. rect is valid when windowsId is set as 0. When you set rect as nil, the whole screen is shared.

    Return Value

    • 0: Success.
    • < 0: Failure.

    Discussion

    DEPRECATED from v2.4.

    Declared In

    AgoraRtcEngineKit.h

    – setVideoProfile:swapWidthAndHeight:

    Sets the video profile.

    - (int)setVideoProfile:(AgoraVideoProfile)profile swapWidthAndHeight:(BOOL)swapWidthAndHeight

    Parameters

    profile

    Sets the video profile. See AgoraVideoProfile.

    swapWidthAndHeight

    Sets whether or not to swap the width and height of the video:

    • YES: Swap the width and height. The video is in portrait mode.
    • NO: (Default) Do not swap the width and height. The video remains in landscape mode.

    The width and height of the output video are consistent with the set video profile.

    Return Value

    • 0: Success.
    • < 0: Failure.

    Discussion

    DEPRECATED from v2.3.

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

    Note:

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

    Declared In

    AgoraRtcEngineKit.h

    – setVideoResolution:andFrameRate:bitrate:

    Sets the video encoding profile manually.

    - (int)setVideoResolution:(CGSize)size andFrameRate:(NSInteger)frameRate bitrate:(NSInteger)bitrate

    Parameters

    size

    Sets the size of the video. The highest value is 1280 * 720.

    frameRate

    Sets the frame rate of the video. The highest value is 30. You can set it to 5, 10, 15, 24, 30, and so on.

    bitrate

    Sets the bitrate of the video. You need to manually work out the bitrate according to the width, height, and frame rate. See the bitrate table in AgoraVideoEncoderConfiguration. With the same width and height, the bitrate varies with the change of the frame rate:

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

    For example, the resolution is 320 * 240 and the frame rate is 15 fps, hence, the bitrate is 200:

    • If the frame rate is 5 fps, the bitrate is 100.
    • If the frame rate is 30 fps, the bitrate is 300.
    • If you set a bitrate beyond the proper range, the SDK automatically adjusts the bitrate to a value within the proper range.

    Discussion

    DEPRECATED from v2.3.

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

    Declared In

    AgoraRtcEngineKit.h

    – getDeviceId:

    Retrieves the device type; such as a recording, playback, or video-capture device. (macOS only.)

    - (NSString *_Nullable)getDeviceId:(AgoraMediaDeviceType)type

    Parameters

    type

    Device type: AgoraMediaDeviceType.

    Return Value

    • Returns the device ID of the device, if this method call is successful.
    • nil: Failure.

    Discussion

    DEPRECATED from v2.3.

    See Also

    Declared In

    AgoraRtcEngineKit.h

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

    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

    Parameters

    soundId

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

    Note: If you preloaded the audio effect into the memory through the preloadEffect method, ensure that the soundID value is set to the same value as in preloadEffect.

    filePath

    Absolute path of the audio effect file.

    loopCount

    Sets the number of times looping the audio effect:

    • 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 whether to change 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 sound effect. The value ranges between 0.0 and 100.0 (default). The lower the value, the lower the volume of the sound effect.

    Return Value

    • 0: Success.
    • < 0: Failure.

    Discussion

    DEPRECATED from v2.3.

    See Also

    Declared In

    AgoraRtcEngineKit.h

    + getMediaEngineVersion

    Returns the media engine version.

    + (NSString *_Nonnull)getMediaEngineVersion

    Return Value

    The media engine version in the string format.

    Discussion

    DEPRECATED from v2.3.

    See Also

    Declared In

    AgoraRtcEngineKit.h

    Deprecated Blocks

    – audioVolumeIndicationBlock:

    Reports which users are speaking and the speakers' volume.

    - (void)audioVolumeIndicationBlock:(void ( ^ _Nullable ) ( NSArray *_Nonnull speakers , NSInteger totalVolume ))audioVolumeIndicationBlock

    Parameters

    audioVolumeIndicationBlock

    This block includes:

    • speakers: An array containing the user ID and volume information for each speaker.

      • uid: User ID of the speaker.
      • volume:Volume of the speaker. The value ranges between 0 (lowest volume) to 255 (highest volume).
    • totalVolume: Total volume after audio mixing between 0 (lowest volume) to 255 (highest volume).

    Discussion

    DEPRECATED from v1.1.

    This callback is disabled by default and can be enabled by the enableAudioVolumeIndication method.

    In the returned speakers' array:

    • If uid is 0 (the local user is the speaker), the returned volume is totalVolume.
    • If uid is not 0 and volume is 0, the specified user did not speak.
    • If a uid is found in the previous speakers' array but not in the current speakers' array, the specified user did not speak.

    Declared In

    AgoraRtcEngineKit.h

    – firstLocalVideoFrameBlock:

    Occurs when the first local video frame is displayed/rendered on the local video view.

    - (void)firstLocalVideoFrameBlock:(void ( ^ _Nullable ) ( NSInteger width , NSInteger height , NSInteger elapsed ))firstLocalVideoFrameBlock

    Parameters

    firstLocalVideoFrameBlock

    This block includes the:

    • width: Width (pixels) of the video stream.
    • height: Height (pixels) of the video stream.
    • elapsed: Time elapsed (ms) from the local user calling joinChannelByToken until the SDK triggers this callback.

    Discussion

    DEPRECATED from v1.1.

    Declared In

    AgoraRtcEngineKit.h

    – firstRemoteVideoDecodedBlock:

    Occurs when the engine decodes the first video frame from a specific remote user.

    - (void)firstRemoteVideoDecodedBlock:(void ( ^ _Nullable ) ( NSUInteger uid , NSInteger width , NSInteger height , NSInteger elapsed ))firstRemoteVideoDecodedBlock

    Parameters

    firstRemoteVideoDecodedBlock

    This block includes the:

    • uid: User ID of the user sending the video streams.
    • width: Width (pixels) of the video stream.
    • height: Height (pixels) of the video stream.
    • elapsed: Time elapsed (ms) from the remote user calling joinChannelByToken until the SDK triggers this callback.

    Discussion

    DEPRECATED from v1.1.

    Declared In

    AgoraRtcEngineKit.h

    – firstRemoteVideoFrameBlock:

    Occurs when the first remote video frame is rendered.

    - (void)firstRemoteVideoFrameBlock:(void ( ^ _Nullable ) ( NSUInteger uid , NSInteger width , NSInteger height , NSInteger elapsed ))firstRemoteVideoFrameBlock

    Parameters

    firstRemoteVideoFrameBlock

    This block includes the:

    • uid: User ID of the remote user sending the video streams.
    • width: Width (pixels) of the video stream.
    • height: Height (pixels) of the video stream.
    • elapsed: Time elapsed (ms) from the local user calling joinChannelByToken until the SDK triggers this callback.

    Discussion

    DEPRECATED from v1.1.

    Declared In

    AgoraRtcEngineKit.h

    – userJoinedBlock:

    Occurs when a user joins a channel.

    - (void)userJoinedBlock:(void ( ^ _Nullable ) ( NSUInteger uid , NSInteger elapsed ))userJoinedBlock

    Parameters

    userJoinedBlock

    This block includes the:

    • uid: User ID. If the uid is specified in the joinChannelByToken method, the specified user ID is returned. If the user ID is not specified in the joinChannel method, the server automatically assigns a uid.
    • elapsed: Time elapsed (ms) from the user calling joinChannelByToken until the SDK triggers this callback.

    Discussion

    DEPRECATED from v1.1.

    If there are other users in the channel when this user joins, the SDK also reports to the app on the existing users who are already in the channel.

    See Also

    Declared In

    AgoraRtcEngineKit.h

    – userOfflineBlock:

    Occurs when a user leaves a call or goes offline.

    - (void)userOfflineBlock:(void ( ^ _Nullable ) ( NSUInteger uid ))userOfflineBlock

    Parameters

    userOfflineBlock

    This block includes the user ID, uid.

    Discussion

    DEPRECATED from v1.1.

    The SDK reads the timeout data to determine if a user leaves a channel (or goes offline). If no data packet is received from the user within 15 seconds, the SDK assumes the user is offline. Sometimes a weak network connection may lead to NO detections; therefore, Agora recommends using the Agora RTM SDK for reliable offline detection.

    See Also

    Declared In

    AgoraRtcEngineKit.h

    – userMuteAudioBlock:

    Occurs when a remote user’s audio stream is muted/unmuted.

    - (void)userMuteAudioBlock:(void ( ^ _Nullable ) ( NSUInteger uid , BOOL muted ))userMuteAudioBlock

    Parameters

    userMuteAudioBlock

    This block includes the:

    • uid: ID of the remote user whose audio stream is muted/unmuted.
    • muted: Whether the remote user’s audio stream is muted/unmuted:

      • YES: Muted.
      • NO: Unmuted.

    Discussion

    DEPRECATED from v1.1.

    See Also

    Declared In

    AgoraRtcEngineKit.h

    – userMuteVideoBlock:

    Occurs when a remote user’s video stream playback pauses/resumes.

    - (void)userMuteVideoBlock:(void ( ^ _Nullable ) ( NSUInteger uid , BOOL muted ))userMuteVideoBlock

    Parameters

    userMuteVideoBlock

    This block includes the:

    • uid: ID of the remote user whose video stream playback pauses/resumes.
    • muted: Whether the remote user’s video playback pauses/resumes:

      • YES: Pauses.
      • NO: Resumes.

    Discussion

    DEPRECATED from v1.1.

    See Also

    Declared In

    AgoraRtcEngineKit.h

    – localVideoStatBlock:

    Reports the statistics of the uploading local video streams once every two seconds.

    - (void)localVideoStatBlock:(void ( ^ _Nullable ) ( NSInteger sentBitrate , NSInteger sentFrameRate ))localVideoStatBlock

    Parameters

    localVideoStatBlock

    This block includes the:

    • sentBitrate: Bitrate sent since last count.
    • sentFrameRate: Frame rate sent since last count.

    Discussion

    DEPRECATED from v1.1.

    See Also

    Declared In

    AgoraRtcEngineKit.h

    – remoteVideoStatBlock:

    Reports the statistics of the receiving remote video streams once every two seconds.

    - (void)remoteVideoStatBlock:(void ( ^ _Nullable ) ( NSUInteger uid , NSInteger delay , NSInteger receivedBitrate , NSInteger decoderOutputFrameRate , NSInteger rendererOutputFrameRate ))remoteVideoStatBlock

    Parameters

    remoteVideoStatBlock

    This block includes the:

    • uid: User ID of the remote user sending the video streams.
    • delay: Time delay (ms).
    • receivedBitrate: Bitrate received since last count.
    • decoderOutputFrameRate: Frame rate encoder output since last count.
    • renderererOutputFrameRate Frame rate render output since last count.

    Discussion

    DEPRECATED from v1.1.

    See Also

    Declared In

    AgoraRtcEngineKit.h

    – remoteAudioStatBlock:

    Reports the statistics of the receiving remote audio streams once every two seconds.

    - (void)remoteAudioStatBlock:(void ( ^ _Nullable ) ( NSUInteger uid , NSInteger quality , NSInteger networkTransportDelay , NSInteger jitterBufferDelay , NSInteger audioLossRate , NSInteger numChannels , NSInteger receivedSampleRate , NSInteger receivedBitrate , NSInteger totalFrozenTime , NSInteger frozenRate , NSInteger totalActiveTime , NSInteger publishDuration ))remoteAudioStatBlock

    Parameters

    remoteAudioStatBlock

    This block includes the:

    • uid: User ID of the user sending the audio streams.
    • quality: Audio receiving quality of the user
    • networkTransportDelay: Network delay from the sender to the receiver.
    • jitterBufferDelay: Jitter buffer delay at the receiver.
    • audioLossRate: Audio frame loss rate in the reported interval.

    Discussion

    DEPRECATED from v1.1.

    See Also

    Declared In

    AgoraRtcEngineKit.h

    – cameraReadyBlock:

    Occurs when the camera turns on and is ready to capture the video.

    - (void)cameraReadyBlock:(void ( ^ _Nullable ) ( void ))cameraReadyBlock

    Discussion

    DEPRECATED from v1.1.

    Declared In

    AgoraRtcEngineKit.h

    – connectionLostBlock:

    Occurs when the connection between the SDK and the server is lost.

    - (void)connectionLostBlock:(void ( ^ _Nullable ) ( void ))connectionLostBlock

    Discussion

    DEPRECATED from v1.1.

    Declared In

    AgoraRtcEngineKit.h

    – rejoinChannelSuccessBlock:

    Occurs when a user rejoins the channel after disconnection due to network problems.

    - (void)rejoinChannelSuccessBlock:(void ( ^ _Nullable ) ( NSString *_Nonnull channel , NSUInteger uid , NSInteger elapsed ))rejoinChannelSuccessBlock

    Parameters

    rejoinChannelSuccessBlock

    This block includes the:

    • channel: Channel name.
    • uid: User ID.
    • elapsed: Time elapsed (ms) from starting to reconnect until this callback occurs.

    Discussion

    When the client loses connection with the server because of network problems, the SDK automatically attempts to reconnect and triggers this callback upon reconnection.

    DEPRECATED from v1.1.

    See Also

    Declared In

    AgoraRtcEngineKit.h

    – rtcStatsBlock:

    Reports the RtcEngine runtime statistics once every two seconds.

    - (void)rtcStatsBlock:(void ( ^ _Nullable ) ( AgoraChannelStats *_Nonnull stat ))rtcStatsBlock

    Parameters

    rtcStatsBlock

    RtcEngine runtime statistics. See AgoraChannelStats.

    Discussion

    DEPRECATED from v1.1.

    See Also

    Declared In

    AgoraRtcEngineKit.h

    – leaveChannelBlock:

    Occurs when a user leaves a channel.

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

    Parameters

    leaveChannelBlock

    Statistics of the call. See AgoraChannelStats.

    Discussion

    DEPRECATED from v1.1.

    When the app calls the leaveChannel method, the SDK uses this callback to notify the app that a user leaves a channel.

    With this callback, the app retrieves information, such as the call duration and statistics of the received/transmitted data in the audioQualityOfUid callback.

    Declared In

    AgoraRtcEngineKit.h

    – audioQualityBlock:

    Reports the audio quality of the current call once every two seconds.

    - (void)audioQualityBlock:(void ( ^ _Nullable ) ( NSUInteger uid , AgoraNetworkQuality quality , NSUInteger delay , NSUInteger lost ))audioQualityBlock

    Parameters

    audioQualityBlock

    This block includes the:

    • uid: User ID of the speaker.
    • quality: Audio quality of the user: AgoraNetworkQuality.
    • delay: Time delay (ms).
    • lost: Audio packet loss rate (%).

    Discussion

    DEPRECATED from v1.1.

    Declared In

    AgoraRtcEngineKit.h

    – networkQualityBlock:

    Reports the network quality of a specified user in the Communication or Live Broadcast profile once every two seconds.

    - (void)networkQualityBlock:(void ( ^ _Nullable ) ( NSUInteger uid , AgoraNetworkQuality txQuality , AgoraNetworkQuality rxQuality ))networkQualityBlock

    Parameters

    networkQualityBlock

    This block includes the:

    • uid: User ID. The network quality of the user with this uid is reported. If uid is 0, the local network quality is reported.
    • txQuality: The transmission quality of the user: AgoraNetworkQuality.
    • rxQuality: The receiving quality of the user: AgoraNetworkQuality.

    Discussion

    DEPRECATED from v1.1.

    See Also

    Declared In

    AgoraRtcEngineKit.h

    – lastmileQualityBlock:

    Reports the last mile network quality of the local user once every two seconds before the user joins a channel.

    - (void)lastmileQualityBlock:(void ( ^ _Nullable ) ( AgoraNetworkQuality quality ))lastmileQualityBlock

    Parameters

    lastmileQualityBlock

    Network quality. See AgoraNetworkQuality.

    Discussion

    DEPRECATED from v1.1.

    Last mile refers to the connection between the local device and Agora’s edge server. After the app calls the enableLastmileTest method, this callback reports once every two seconds the uplink and downlink last mile network conditions of the local user before the user joins a channel.

    Declared In

    AgoraRtcEngineKit.h

    – mediaEngineEventBlock:

    Reports a media engine event.

    - (void)mediaEngineEventBlock:(void ( ^ _Nullable ) ( NSInteger code ))mediaEngineEventBlock

    Discussion

    DEPRECATED from v1.1.

    Declared In

    AgoraRtcEngineKit.h

    Extension Methods

    – createRtcChannel:

    Creates and gets an AgoraRtcChannel instance.

    - (AgoraRtcChannel *_Nullable)createRtcChannel:(NSString *_Nonnull)channelId

    Parameters

    channelId

    The unique channel name for an Agora RTC session. It must be in the string format and not exceed 64 bytes in length. 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: “!”, “#”, “$”, “%”, “&”, “(”, “)”, “+”, “-”, “:”, “;”, “<”, “=”, “.”, “>”, “?”, “@”, “[”, “]”, “^”, “_”, “ {”, “}”, “|”, “~”, “,”.

    Note

    • This parameter does not have a default value. You must set it.
    • Do not set it as the empty string “”. Otherwise, the SDK returns AgoraErrorCodeRefused(-5).

    Return Value

    • A pointer to the AgoraRtcChannel instance, if the method call succeeds.
    • An empty pointer nil, if the method call fails.
    • AgoraErrorCodeRefused(-5), if you set channelId as the empty string “”.

    Discussion

    To join more than one channel, call this method multiple times to create as many AgoraRtcChannel objects as needed, and call the joinChannelByToken method of each created AgoraRtcChannel instance.

    After joining multiple channels, you can simultaneously subscribe to streams of all the channels, but publish a stream in only one channel at one time.

    Declared In

    AgoraRtcChannel.h

    X
    Is this page helpful?