Agora RTC Objective-C API Reference Refactor

Instance Methods
AgoraRtcEngineKit Class Reference

Inherits <NSObject>.

## Instance Methods
(int) | - joinChannelExByToken:connection:delegate:mediaOptions:joinSuccess:
(int) | - joinChannelExByToken:channelId:userAccount:delegate:mediaOptions:joinSuccess:
(int) | - updateChannelExWithMediaOptions:connection:
(int) | - setDelegateEx:connection:
(int) | - muteLocalAudioStreamEx:connection:
(int) | - muteLocalVideoStreamEx:connection:
(int) | - muteRemoteAudioStreamEx:mute:connection:
(int) | - muteAllRemoteAudioStreamsEx:connection:
(int) | - setVideoEncoderConfigurationEx:connection:
(int) | - setupRemoteVideoEx:connection:
(int) | - setRemoteRenderModeEx:mode:mirror:connection:
(int) | - muteRemoteVideoStreamEx:mute:connection:
(int) | - muteAllRemoteVideoStreamsEx:connection:
(int) | - enableDualStreamModeEx:streamConfig:connection:
(int) | - setDualStreamModeEx:streamConfig:connection:
(int) | - setSimulcastConfigEx:connection:
(int) | - setRemoteVideoStreamEx:type:connection:
(int) | - setRemoteVideoSubscriptionOptionsEx:options:connection:
(AgoraUserInfo *_Nullable) | - getUserInfoByUserAccountEx:connection:withError:
(AgoraUserInfo *_Nullable) | - getUserInfoByUidEx:connection:withError:
(AgoraConnectionState) | - getConnectionStateEx:
(int) | - adjustRecordingSignalVolumeEx:connection:
(int) | - muteRecordingSignalEx:connection:
(int) | - adjustUserPlaybackSignalVolumeEx:volume:connection:
(int) | - setRemoteVoicePositionEx:pan:gain:connection:
(int) | - addVideoWatermarkEx:options:connection:
(int) | - clearVideoWatermarkEx:

## Core Methods
##
id< AgoraRtcEngineDelegate > _Nullable | delegate
(instancetype _Nonnull) | + sharedEngineWithAppId:delegate:
(instancetype _Nonnull) | + sharedEngineWithConfig:delegate:
(void) | + destroy
(void) | + destroy:
(int) | - preloadChannelByToken:channelId:uid:
(int) | - preloadChannelByTokenWithUserAccount:channelId:userAccount:
(int) | - updatePreloadChannelToken:
(int) | - joinChannelByToken:channelId:info:uid:joinSuccess:
(int) | - joinChannelByToken:channelId:uid:mediaOptions:joinSuccess:
(int) | - leaveChannel:
(int) | - setChannelProfile:
(int) | - updateChannelWithMediaOptions:
(int) | - setClientRole:
(int) | - setClientRole:options:
(int) | - renewToken:
(AgoraConnectionState) | - getConnectionState
(int) | - startOrUpdateChannelMediaRelay:
(int) | - stopChannelMediaRelay
(int) | - pauseAllChannelMediaRelay
(int) | - resumeAllChannelMediaRelay
(int) | - enableWirelessAccelerate:
(int) | - startLocalAudioMixer:
(int) | - updateLocalAudioMixerConfiguration:
(int) | - stopLocalAudioMixer
(int) | - startMediaRenderingTracing
(int) | - enableInstantMediaRendering
(int) | - enableAudio
(int) | - disableAudio
(int) | - enableLocalAudio:
(int) | - setAudioProfile:
(int) | - enableAudioVolumeIndication:smooth:reportVad:
(int) | - adjustUserPlaybackSignalVolume:volume:
(int) | - startRecordingDeviceTest:
(int) | - stopRecordingDeviceTest
(int) | - startPlaybackDeviceTest:
(int) | - stopPlaybackDeviceTest
(int) | - registerExtensionWithVendor:extension:sourceType:
(int) | - enableExtensionWithVendor:extension:enabled:
(int) | - enableExtensionWithVendor:extension:enabled:sourceType:
(int) | - enableExtensionWithVendor:extension:extensionInfo:enabled:
(int) | - setExtensionProviderPropertyWithVendor:key:value:
(int) | - setExtensionPropertyWithVendor:extension:key:value:
(int) | - setExtensionPropertyWithVendor:extension:key:value:sourceType:
(int) | - setExtensionPropertyWithVendor:extension:extensionInfo:key:value:
(NSString *_Nullable) | - getExtensionPropertyWithVendor:extension:key:
(NSString *_Nullable) | - getExtensionPropertyWithVendor:extension:key:sourceType:
(NSString *_Nullable) | - getExtensionPropertyWithVendor:extension:extensionInfo:key:

## Core Video
##
(int) | - enableVideo
(int) | - disableVideo
(int) | - enableLocalVideo:
(NSArray< AgoraVideoCodecCapInfo * > *_Nullable) | - queryCodecCapability
(int) | - queryDeviceScore
(AgoraHDRCapability) | - queryHDRCapability:
(int) | - setupLocalVideo:
(int) | - setLocalRenderTargetFps:targetFps:
(int) | - setRemoteRenderTargetFps:
(int) | - setLocalRenderMode:mirror:
(int) | - startPreview
(int) | - startPreview:
(int) | - stopPreview
(int) | - stopPreview:
(int) | - setRemoteRenderMode:mode:mirror:
(int) | - muteLocalVideoStream:
(int) | - muteRemoteVideoStream:mute:
(int) | - muteAllRemoteVideoStreams:
(int) | - setFaceShapeBeautyOptions:options:
(int) | - setFaceShapeBeautyOptions:options:sourceType:
(AgoraFaceShapeBeautyOptions *_Nullable) | - getFaceShapeBeautyOptions
(AgoraFaceShapeBeautyOptions *_Nullable) | - getFaceShapeBeautyOptions:
(int) | - setFaceShapeAreaOptions:
(int) | - setFaceShapeAreaOptions:sourceType:
(AgoraFaceShapeAreaOptions *_Nullable) | - getFaceShapeAreaOptions:
(AgoraFaceShapeAreaOptions *_Nullable) | - getFaceShapeAreaOptions:sourceType:
(int) | - setVideoDenoiserOptions:options:
(int) | - setVideoDenoiserOptions:options:sourceType:
(int) | - setLowlightEnhanceOptions:options:
(int) | - setLowlightEnhanceOptions:options:sourceType:
(int) | - setColorEnhanceOptions:options:
(int) | - setColorEnhanceOptions:options:sourceType:
(int) | - enableVirtualBackground:backData:segData:
(int) | - enableVirtualBackground:backData:segData:sourceType:
(int) | - setVideoScenario:
(int) | - setVideoQoEPreference:
(BOOL) | - isFeatureAvailableOnDevice:

## Audio Effect Playback
##
(int) | - setVoiceBeautifierPreset:
(int) | - setVoiceConversionPreset:
(int) | - setVoiceBeautifierParameters:param1:param2:
(int) | - setVoiceConversionParameters:param1:param2:
(int) | - setHeadphoneEQPreset:
(int) | - setHeadphoneEQParameters:highGain:
(int) | - enableVoiceAITuner:type:

## Sound Position Indication
##
(int) | - enableSoundPositionIndication:
(int) | - setRemoteVoicePosition:pan:gain:
(int) | - enableSpatialAudio:
(int) | - setAINSMode:mode:

## Audio Mixing
##
(int) | - selectAudioTrack:
(int) | - getAudioTrackCount

## Audio Recording
##
(int) | - startAudioRecordingWithConfig:

## Echo Test
##
(int) | - startEchoTestWithConfig:

## Miscellaneous Audio Control
##
(int) | - enableInEarMonitoring:
(int) | - enableInEarMonitoring:includeAudioFilters:
(int) | - setInEarMonitoringVolume:

## Dual Video Mode
##
(int) | - enableDualStreamMode:
(int) | - enableDualStreamMode:streamConfig:
(int) | - setDualStreamMode:
(int) | - setDualStreamMode:streamConfig:
(int) | - setSimulcastConfig:
(int) | - setRemoteDefaultVideoStreamType:
(int) | - setRemoteVideoSubscriptionOptions:options:
(int) | - setSubscribeAudioAllowlist:
(int) | - setSubscribeVideoAllowlist:

## Stream Fallback
##
(int) | - setHighPriorityUserList:option:
(int) | - setHighPriorityUserListEx:option:connection:

## External Media Source
##
(void) | - setExternalVideoSource:useTexture:sourceType:
(void) | - setExternalVideoSource:useTexture:sourceType:encodedVideoTrackOption:
(BOOL) | - pushExternalVideoFrame:
(BOOL) | - pushExternalVideoFrame:videoTrackId:
(int) | - pushExternalEncodedVideoFrame:info:
(int) | - pushExternalEncodedVideoFrame:info:videoTrackId:
(unsigned int) | - createCustomVideoTrack
(unsigned int) | - createCustomEncodedVideoTrack:
(int) | - destroyCustomVideoTrack:
(int) | - destroyCustomEncodedVideoTrack:
(void) | - enableExternalAudioSink:sampleRate:channels:
(BOOL) | - pullPlaybackAudioFrameRawData:lengthInByte:
(CMSampleBufferRef _Nullable) | - pullPlaybackAudioFrameSampleBufferByLengthInByte:
(int) | - createCustomAudioTrack:config:
(int) | - destroyCustomAudioTrack:
(int) | - enableCustomAudioLocalPlayback:enabled:
(int) | - setRecordingAudioFrameParametersWithSampleRate:channel:mode:samplesPerCall:
(int) | - setPlaybackAudioFrameParametersWithSampleRate:channel:mode:samplesPerCall:
(int) | - setMixedAudioFrameParametersWithSampleRate:channel:samplesPerCall:
(int) | - setEarMonitoringAudioFrameParametersWithSampleRate:channel:mode:samplesPerCall:
(int) | - setPlaybackAudioFrameBeforeMixingParametersWithSampleRate:channel:
(int) | - registerAudioSpectrumDelegate:
(int) | - unregisterAudioSpectrumDelegate:
(int) | - enableAudioSpectrumMonitor:
(int) | - disableAudioSpectrumMonitor

## Built-in Encryption
##
(int) | - enableEncryption:encryptionConfig:
(int) | - enableEncryptionEx:encryptionConfig:connection:
(int) | - enableVideoImageSourceEx:options:connection:

## Data Steam
##
(int) | - createDataStream:config:
(int) | - createDataStreamEx:reliable:ordered:connection:
(int) | - createDataStreamEx:config:connection:
(int) | - sendStreamMessageEx:data:connection:

## Stream Publish
##
(int) | - startRtmpStreamWithoutTranscoding:
(int) | - startRtmpStreamWithTranscoding:transcoding:
(int) | - updateRtmpTranscoding:
(int) | - stopRtmpStream:
(int) | - setScreenCaptureScenario:
(int) | - stopScreenCapture
(int) | - startScreenCapture:
(int) | - updateScreenCapture:
(AgoraScreenCaptureFrameRateCapability) | - queryScreenCaptureCapability
(int) | - setSubscribeAudioAllowlistEx:connection:
(int) | - setSubscribeVideoAllowlistEx:connection:
(NSInteger) | - takeSnapshotEx:uid:filePath:
(NSInteger) | - takeSnapshotExWithConfig:uid:config:
(int) | - sendAudioMetadataEx:metadata:
(int) | - enableContentInspectEx:config:connection:
(int) | - startRtmpStreamWithoutTranscodingEx:connection:
(int) | - startRtmpStreamWithTranscodingEx:transcoding:connection:
(int) | - updateRtmpTranscodingEx:connection:
(int) | - stopRtmpStreamEx:connection:
(int) | - startOrUpdateChannelMediaRelayEx:connection:
(int) | - stopChannelMediaRelayEx:
(int) | - pauseAllChannelMediaRelayEx:
(int) | - resumeAllChannelMediaRelayEx:
(int) | - startMediaRenderingTracingEx:
(int) | - setParametersEx:connection:
(NSString *_Nullable) | - getCallIdEx:
(void) | - addDelegateEx:connection:
(void) | - removeDelegateEx:connection:

## Camera Control
##
(CGFloat) | - cameraMaxZoomFactor
(int) | - switchCamera
(int) | - enableMultiCamera:config:
(int) | - enableCameraCenterStage:
(int) | - startCameraCapture:config:
(int) | - stopCameraCapture:

## Face Detection
##
(int) | - enableFaceDetection:

## Watermark
##
(int) | - addVideoWatermark:options:
(int) | - registerLocalUserAccount:appId:
(int) | - joinChannelByToken:channelId:userAccount:joinSuccess:
(int) | - joinChannelByToken:channelId:userAccount:mediaOptions:joinSuccess:
(AgoraUserInfo *_Nullable) | - getUserInfoByUserAccount:withError:
(AgoraUserInfo *_Nullable) | - getUserInfoByUid:withError:
(BOOL) | - setAudioFrameDelegate:
(BOOL) | - setVideoFrameDelegate:
(BOOL) | - setEncodedVideoFrameDelegate:
(BOOL) | - setFaceInfoDelegate:

## Media Metadata
##
(BOOL) | - setMediaMetadataDataSource:withType:
(BOOL) | - setMediaMetadataDelegate:withType:

## Miscellaneous Methods
##
(NSString *_Nonnull) | + getSdkVersion
(NSString *_Nonnull) | + getErrorDescription:
(int) | - setLogFile:
(int) | - setLogFilter:
(int) | - setLogFileSize:
(NSString *_Nullable) | - uploadLogFile
(int) | - writeLog:content:
(NSString *_Nullable) | - getCallId
(int) | - rate:rating:description:
(int) | - complain:description:
(int) | - startLastmileProbeTest:
(int) | - stopLastmileProbeTest
(uint64_t) | - getNtpWallTimeInMs

## MediaPlayer publish
##
(id< AgoraRtcMediaPlayerProtocol >_Nullable) | - createMediaPlayerWithDelegate:
(id< AgoraRtcMediaPlayerCacheManagerProtocol > _Nullable) | - createMediaPlayerCacheManager
(int) | - destroyMediaPlayer:
(id< AgoraRtcMediaPlayerProtocol > _Nullable) | - getMediaPlayer:
(int) | - startRhythmPlayer:sound2:config:
(int) | - stopRhythmPlayer
(int) | - configRhythmPlayer:
(int) | - setDirectCdnStreamingAudioConfiguration:
(int) | - setDirectCdnStreamingVideoConfiguration:
(int) | - startDirectCdnStreaming:publishUrl:mediaOptions:
(int) | - stopDirectCdnStreaming
(int) | - updateDirectCdnStreamingMediaOptions:
(int) | - setAdvancedAudioOptions:
(int) | - sendCustomReportMessage:category:event:label:value:
(int) | - setLogLevel:
(int) | - setLocalAccessPoint:
(int) | - setCloudProxy:
(NSInteger) | - takeSnapshot:filePath:
(NSInteger) | - takeSnapshotWithConfig:config:
(int) | - setAVSyncSource:uid:
(int) | - sendAudioMetadata:
(int) | - enableVideoImageSource:options:
(int) | - getNetworkType
(AgoraMediaRecorder *_Nullable) | - createMediaRecorder:
(int) | - destroyMediaRecorder:
(id< AgoraH265TranscoderProtocol >_Nullable) | - getH265Transcoder
(int) | - enableWebSdkInteroperability:
(int) | - setAudioProfile:scenario:
(int) | - setExternalAudioSource:sampleRate:channels:
(int) | - setExternalAudioSource:sampleRate:channels:localPlayback:publish:
(int) | - setLocalRenderMode:mode:
(int) | - enableExternalAudioSourceLocalPlayback:
(void) | - addDelegate:
(void) | - removeDelegate:

## Detailed Description

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

The AgoraRtcEngineKit class is the entry point of the Agora SDK that provides simple APIs for applications to easily start voice and video communication. Provides all methods that can be invoked by your application.

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

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

## Method Documentation

## ◆ sharedEngineWithAppId:delegate:

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

Initializes the Agora SDK service.

After the initialization, the service is set to enable audio by default.

Note
  Ensure that you call this method before calling any other API.

Warning
  Only users with the same App ID can call each other.
  One AgoraRtcEngineKit can use only one App ID. If you need to change the App ID, call destroy to release the current instance first, and then call this method to create a new instance.

Parameters

  appId | App ID of your Agora project.
  delegate | AgoraRtcEngineDelegate.

Returns
  An AgoraRtcEngineKit object.

## ◆ sharedEngineWithConfig:delegate:

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

Creates an AgoraRtcEngineKit instance.

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 AgoraRtcEngineKit.sharedEngineWithAppId:delegate: sharedEngineWithAppId. The difference between `sharedEngineWithAppId` and this method is that this method enables you to specify the connection area.
  - The SDK supports creating only one AgoraRtcEngineKit instance for an app for now.

Parameters

  config | Configurations for the AgoraRtcEngineKit instance. For details, see AgoraRtcEngineConfig.
  delegate | AgoraRtcEngineDelegate.

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

## ◆ preloadChannelByToken:channelId:uid:

- (int) preloadChannelByToken: |  | (NSString *_Nullable) | token
channelId: |  | (NSString *_Nonnull) | channelId
uid: |  | (NSUInteger) | uid

Preload a channel.

This method enables users to preload a channel.

A successful call of this method will reduce the time of joining the same channel.

Note:

1. The SDK supports preloading up to 20 channels. Once the preloaded channels exceed the limit, the SDK will keep the latest 20 available.
2. Renew the token of the preloaded channel by calling this method with the same 'channelId' and 'uid'.

Parameters

  token | The token generated on your server for authentication.
  channelId | The channel name. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported character scopes are: All lowercase English letters: a to z. All uppercase English letters: A to Z. All numeric characters: 0 to 9. The space character. Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
  uid | The user ID. This parameter is used to identify the user in the channel for real-time audio and video interaction. You need to set and manage user IDs yourself, and ensure that each user ID in the same channel is unique. This parameter is a 32-bit unsigned integer. The value range is 1 to 2<h>32</h>-1. If the user ID is not assigned (or set to 0), the SDK assigns a random user ID and returns it in the onJoinChannelSuccess callback. Your application must record and maintain the returned user ID, because the SDK does not do so.

Returns
  - 0: Success.
  - < 0: Failure.
    - -7: The IRtcEngine object has not been initialized. You need to initialize the IRtcEngine object before calling this method.
    - -102: The channel name is invalid. You need to pass in a valid channel name in channelId to preload the channel again.

## ◆ preloadChannelByTokenWithUserAccount:channelId:userAccount:

- (int) preloadChannelByTokenWithUserAccount: |  | (NSString *_Nullable) | token
channelId: |  | (NSString *_Nonnull) | channelId
userAccount: |  | (NSString *_Nonnull) | userAccount

Preload a channel.

This method enables users to preload a channel.

A successful call of this method will reduce the time of joining the same channel.

Note:

1. The SDK supports preloading up to 20 channels. Once the preloaded channels exceed the limit, the SDK will keep the latest 20 available.
2. Renew the token of the preloaded channel by calling this method with the same 'channelId' and 'userAccount'.

Parameters

  token | The token generated on your server for authentication.
  channelId | The channel name. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported character scopes are: All lowercase English letters: a to z. All uppercase English letters: A to Z. All numeric characters: 0 to 9. The space character. Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
  userAccount | The user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are: All lowercase English letters: a to z. All uppercase English letters: A to Z. All numeric characters: 0 to 9. The space character. Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".

Returns
  - 0: Success.
  - < 0: Failure.
    - -2: The parameter is invalid. For example, the userAccount parameter is empty. You need to pass in a valid parameter and preload the channel again.
    - -7: The IRtcEngine object has not been initialized. You need to initialize the IRtcEngine object before calling this method.
    - -102: The channel name is invalid. You need to pass in a valid channel name in channelId to preload the channel again.

## ◆ updatePreloadChannelToken:

- (int) updatePreloadChannelToken: |  | (NSString *_Nonnull) | token |

Update token of the preloaded channels.

An easy way to update all preloaded channels' tokens, if all preloaded channels use the same token.

If preloaded channels use different tokens, we need to call the 'preloadChannel' method with the same 'channelId' and 'uid' or 'userAccount' to update the corresponding token.

Parameters

  token | The token generated on your server for authentication.

Returns
  - 0: Success.
  - < 0: Failure.
    - -2: The token is invalid. You need to pass in a valid token and update the token again.
    - -7: The IRtcEngine object has not been initialized. You need to initialize the IRtcEngine object before calling this method.

## ◆ joinChannelByToken:channelId:info:uid:joinSuccess:

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

Joins a channel.

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

You must call the leaveChannel: 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.

A successful method call triggers the following callbacks:

- The local client: AgoraRtcEngineDelegate.rtcEngine:didJoinChannel:withUid:elapsed: didJoinChannel.
- The remote client: AgoraRtcEngineDelegate.rtcEngine:didJoinedOfUid:elapsed: didJoinedOfUid, if the user joining the channel is in the Communication profile, or is a BROADCASTER in the Live Broadcast profile.

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

Note
  - 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.
  - The SDK uses the iOS's AVAudioSession shared object for audio recording and playback. Using this object may affect the SDK’s audio functions.

Parameters

  token | The token for authentication. In situations not requiring high security: You can use the temporary token generated at Console. For details, see Get a temporary token. In situations requiring high security: Set it as the token generated at you 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 the callback. Your app must record and maintain the returned `uid` since the SDK does not do so.
  joinSuccessBlock | Same as AgoraRtcEngineDelegate.rtcEngine:didJoinChannel:withUid:elapsed: didJoinChannel. We recommend you set this parameter as `nil` to use `didJoinChannel`. If `joinSuccessBlock` is nil, the SDK triggers the `didJoinChannel` callback. If you implement both `joinSuccessBlock` and `didJoinChannel`, `joinSuccessBlock` takes higher priority than `didJoinChannel`.

Returns
  - 0: Success.
  - < 0: Failure.
    - -2: AgoraErrorCodeInvalidArgument
    - -3: AgoraErrorCodeNotReady
    - -5: AgoraErrorCodeRefused

## ◆ joinChannelByToken:channelId:uid:mediaOptions:joinSuccess:

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

Joins a channel.

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

You must call the leaveChannel: 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.

A successful method call triggers the following callbacks:

- The local client: AgoraRtcEngineDelegate.rtcEngine:didJoinChannel:withUid:elapsed: didJoinChannel.
- The remote client: AgoraRtcEngineDelegate.rtcEngine:didJoinedOfUid:elapsed: didJoinedOfUid, if the user joining the channel is in the Communication profile, or is a BROADCASTER in the Live Broadcast profile.

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

Note
  - 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.
  - The SDK uses the iOS's AVAudioSession shared object for audio recording and playback. Using this object may affect the SDK’s audio functions.

Parameters

  token | The token for authentication. In situations not requiring high security: You can use the temporary token generated at Console. For details, see Get a temporary token. In situations requiring high security: Set it as the token generated at you 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
  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 the callback. Your app must record and maintain the returned `uid` since the SDK does not do so.
  mediaOptions | AgoraRtcChannelMediaOptions Object.
  joinSuccessBlock | Same as AgoraRtcEngineDelegate.rtcEngine:didJoinChannel:withUid:elapsed: didJoinChannel. We recommend you set this parameter as `nil` to use `didJoinChannel`. If `joinSuccessBlock` is nil, the SDK triggers the `didJoinChannel` callback. If you implement both `joinSuccessBlock` and `didJoinChannel`, `joinSuccessBlock` takes higher priority than `didJoinChannel`.

Returns
  - 0: Success.
  - < 0: Failure.
    - -2: AgoraErrorCodeInvalidArgument
    - -3: AgoraErrorCodeNotReady
    - -5: AgoraErrorCodeRefused

## ◆ leaveChannel:

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

Leaves the channel.

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

This method also releases all resources related to the call.

This method is an asynchronous call, which means that the result of this method returns before the user has not actually left the channel. Once the user successfully leaves the channel, the SDK triggers the AgoraRtcEngineDelegate.rtcEngine:didLeaveChannelWithStats: didLeaveChannelWithStats callback.

Note
  - If you call destroy immediately after this method, the leaveChannel process is interrupted, and the SDK does not trigger the `didLeaveChannelWithStats` callback.
  - When you call this method, the SDK deactivates the audio session on iOS by default, and may affect other apps.

Parameters

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

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setChannelProfile:

- (int) setChannelProfile: |  | (AgoraChannelProfile) | profile |

Sets the channel profile.

The SDK differentiates channel profiles and applies different optimization algorithms accordingly.

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.

Parameters

  profile | The channel profile: AgoraChannelProfile.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ updateChannelWithMediaOptions:

- (int) updateChannelWithMediaOptions: |  | (AgoraRtcChannelMediaOptions *_Nonnull) | mediaOptions |

Updates the channel media options after joining the channel.

Parameters

  mediaOptions | The channel media options: ChannelMediaOptions.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setClientRole:

- (int) setClientRole: |  | (AgoraClientRole) | role |

Sets the role of a user.

This method sets the role of a user as either a broadcaster or an audience.

- The broadcaster sends and receives streams.
- The audience receives streams only.
  Note
    By default, all users are audience regardless of the channel profile. Call this method to change the user role to BROADCASTER so that the user can send a stream.
  Parameters

    role | Role of the client: AgoraClientRole.

  Returns
- 0: Success.
- <0: Failure.

## ◆ setClientRole:options:

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

Sets the role of a user.

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:

- The local client: [didClientRoleChanged]([AgoraRtcEngineDelegate rtcEngine:didClientRoleChanged:newRole:])
- Remote clients: [didJoinedOfUid]([AgoraRtcEngineDelegate rtcEngine:didJoinedOfUid:elapsed:]) or [didOfflineOfUid(AgoraUserOfflineReasonBecomeAudience)]([AgoraRtcEngineDelegate rtcEngine:didOfflineOfUid:reason:])

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.

Parameters

  options | The client role of the user, see AgoraClientRoleOptions.

Returns
  - `0`(`AgoraRtmpStreamingReasonOK`): 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.

## ◆ renewToken:

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

Renews the token.

Once a token is enabled and used, it expires after a certain period of time.

Under the following circumstances, generate a new token on your server, and then call this method to renew it. Failure to do so results in the SDK disconnecting from the server.

- The AgoraRtcEngineDelegate.rtcEngine:tokenPrivilegeWillExpire: tokenPrivilegeWillExpire callback is triggered.
- The rtcEngineRequestToken: (AgoraRtcEngineDelegate-p) rtcEngineRequestToken callback is triggered.
- The `AgoraErrorCodeTokenExpired`(-109) error is reported.
  Parameters

    token | The new token.

  Returns
- 0: Success.
- < 0: Failure.

## ◆ getConnectionState

- (AgoraConnectionState) getConnectionState |  |  |

Gets the connection state of the SDK.

Returns
  The connection state. See AgoraConnectionState.

## ◆ startOrUpdateChannelMediaRelay:

- (int) startOrUpdateChannelMediaRelay: |  | (AgoraChannelMediaRelayConfiguration *_Nonnull) | config |

Starts or update to relay media streams across channels.

After a successful method call, the SDK triggers the [channelMediaRelayStateDidChange]([AgoraRtcEngineDelegate rtcEngine:channelMediaRelayStateDidChange:error:]) callback, and this callback return the state of the media stream relay.

- If the `channelMediaRelayStateDidChange` callback returns AgoraChannelMediaRelayStateRunning(2) and AgoraChannelMediaRelayStateIdle(0), 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]([AgoraRtcEngineKit joinChannelByToken:channelId:info:uid:joinSuccess:]) method.
- This method takes effect only when you are a broadcaster in a Live-broadcast channel.
- Contact sales.nosp@m.-us@.nosp@m.agora.nosp@m..io before implementing this function.
- We do not support string user accounts in this API.

Since
  v4.2.0

Parameters

  config | The configuration of the media stream relay: [AgoraChannelMediaRelayConfiguration](AgoraChannelMediaRelayConfiguration).

Returns
  - 0: Success.
  - < 0: Failure.
    - -1(ERR_FAILED): A general error occurs (no specified reason).
    - -2(ERR_INVALID_ARGUMENT): The argument is invalid.
    - -5(ERR_REFUSED): The request is rejected.
    - -8(ERR_INVALID_STATE): The current status is invalid, only allowed to be called when the role is the broadcaster.

## ◆ stopChannelMediaRelay

- (int) stopChannelMediaRelay |  |  |

Stops the media stream relay.

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

After a successful method call, the SDK triggers the [channelMediaRelayStateDidChange]([AgoraRtcEngineDelegate rtcEngine:channelMediaRelayStateDidChange:error:]) callback. If the callback returns AgoraChannelMediaRelayStateIdle(0) and AgoraChannelMediaRelayErrorNone(0), the broadcaster successfully stops the relay.

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

Returns
  - 0: Success.
  - < 0: Failure.
    - -1(ERR_FAILED): A general error occurs (no specified reason).
    - -2(ERR_INVALID_ARGUMENT): The argument is invalid.
    - -5(ERR_REFUSED): The request is rejected.
    - -7(ERR_NOT_INITIALIZED): cross channel media streams are not relayed.

## ◆ pauseAllChannelMediaRelay

- (int) pauseAllChannelMediaRelay |  |  |

pause the channels for media stream relay.

Returns
  - 0: Success.
  - < 0: Failure.
  - -1(ERR_FAILED): A general error occurs (no specified reason).
  - -2(ERR_INVALID_ARGUMENT): The argument is invalid.
  - -5(ERR_REFUSED): The request is rejected.
  - -7(ERR_NOT_INITIALIZED): cross channel media streams are not relayed.

## ◆ resumeAllChannelMediaRelay

- (int) resumeAllChannelMediaRelay |  |  |

resume the channels for media stream relay.

Returns
  - 0: Success.
  - < 0: Failure.
  - -1(ERR_FAILED): A general error occurs (no specified reason).
  - -2(ERR_INVALID_ARGUMENT): The argument is invalid.
  - -5(ERR_REFUSED): The request is rejected.
  - -7(ERR_NOT_INITIALIZED): cross channel media streams are not relayed.

## ◆ enableWirelessAccelerate:

- (int) enableWirelessAccelerate: |  | (BOOL) | enabled |

Turn WIFI acceleration on or off.

Note
  - This method is called before and after joining a channel.
  - Users check the WIFI router app for information about acceleration. Therefore, if this interface is invoked, the caller accepts that the caller's name will be displayed to the user in the WIFI router application on behalf of the caller.

Parameters

  enabled | true：Turn WIFI acceleration on. false：Turn WIFI acceleration off.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ startLocalVideoTranscoder:

- (int) startLocalVideoTranscoder: |  | (AgoraLocalTranscoderConfiguration *_Nonnull) | config |

## ◆ updateLocalTranscoderConfiguration:

- (int) updateLocalTranscoderConfiguration: |  | (AgoraLocalTranscoderConfiguration *_Nonnull) | config |

## ◆ stopLocalVideoTranscoder

- (int) stopLocalVideoTranscoder |  |  |

## ◆ startLocalAudioMixer:

- (int) startLocalAudioMixer: |  | (AgoraLocalAudioMixerConfiguration *_Nonnull) | config |

Starts the local audio with a mixed audio stream.

Parameters

  config | Sets the mixed audio stream source settings.

Returns
  - 0: Success.
  - < 0: Failure.
    - #ERR_NOT_INITIALIZED (7): You have not initialized the RTC engine when publishing the stream.

## ◆ updateLocalAudioMixerConfiguration:

- (int) updateLocalAudioMixerConfiguration: |  | (AgoraLocalAudioMixerConfiguration *_Nonnull) | config |

Update the source stream settings for the mixed audio stream.

Parameters

  config | Update the source audio stream settings. See

Returns
  - 0: Success.
  - < 0: Failure.
    - #ERR_NOT_INITIALIZED (7): You have not initialized the RTC engine when publishing the stream.

## ◆ stopLocalAudioMixer

- (int) stopLocalAudioMixer |  |  |

Stops the local audio mixing.

After calling `startLocalAudioMixer`, call this method if you want to stop the local audio mixing. Call timing: Call this method after `startLocalAudioMixer`.

Returns
  - 0: Success.
  - < 0: Failure.
    - -7: The `AgoraRtcEngineKit` object has not been initialized. You need to initialize the `AgoraRtcEngineKit` object before calling this method.

## ◆ startMediaRenderingTracing

- (int) startMediaRenderingTracing |  |  |

Start tracing media rendering events.

Since
  v4.1.1 @discussion
  - SDK will trace media rendering events when this API is called.
  - The tracing result can be obtained through callback `[AgoraRtcEngineDelegate rtcEngine:videoRenderingTracingResultOfUid:currentEvent:tracingInfo:]`

Note
  - By default, SDK will trace media rendering events when join channel.
  - The start point of event tracing will be reset after leaving channel.

Returns
  - 0: Success.
  - < 0: Failure.
    - `-7(AgoraErrorCodeNotInitialized)`: The SDK is not initialized.

## ◆ enableInstantMediaRendering

- (int) enableInstantMediaRendering |  |  |

Enable instant media rendering.

Since
  v4.1.1 @discussion
  - This method enable SDK to render video or playout audio faster.

Note
  - Once enable this mode, we should destroy rtc engine to disable it.
  - Enable this mode, will sacrifice some part of experience.

Returns
  - 0: Success.
  - < 0: Failure.
    - `-7(AgoraErrorCodeNotInitialized)`: The SDK is not initialized.

## ◆ destroy

+ (void) destroy |  |  |

Destroys the AgoraRtcEngineKit object.

Releases AgoraRtcEngineKit instance and releases its associated resources. It is recommended for applications where users make occasional voice or video calls. When the real-time communication functionality is no longer needed, call this method to free up resources for other operations. Once the application has called this method to destroy the created AgoraRtcEngineKit instance, no other methods in the SDK can be used and no callbacks occur. To start communications again, call sharedEngineWithAppId:delegate: sharedEngineWithAppId to establish a new AgoraRtcEngineKit instance.

Note
  - Call this method in the subthread.
  - This method is a synchronous call, which means that the result of this method call returns after the AgoraRtcEngineKit object resources are released. Do not call this method in any callback generated by the SDK, or it may result in a deadlock.

## ◆ destroy:

+ (void) destroy: |  | (void(^)(void)) | engineReleasedBlock |

Destroys the RtcEngine object.

Since
  v4.6.0

Releases RtcEngine instance and releases its associated resources. It is recommended for applications where users make occasional voice or video calls. When the real-time communication functionality is no longer needed, call this method to free up resources for other operations. Once the application has called this method to destroy the created AgoraRtcEngineKit instance, no other methods in the SDK can be used and no callbacks occur. To start communications again, call sharedEngineWithAppId:delegate: sharedEngineWithAppId to establish a new AgoraRtcEngineKit instance.

Note
  Do not call this method from within any SDK callback, as this may result in a deadlock.

Parameters

  engineReleasedBlock | A callback block when AgoraRtcEngineKit has been destroyed, used to configure synchronous or asynchronous destruction of the AgoraRtcEngineKit: `non-nil`: Asynchronous destruction. The method returns immediately, and the engine resources may not be fully released yet. The [engineReleasedBlock](void (^)(void)) will be triggered once the engine destruction is complete. `nil`: Synchronous destruction. The method returns only after the engine resources have been fully released, which is the same as [destroy]([AgoraRtcEngineKit destroy:]).

## ◆ enableAudio

- (int) enableAudio |  |  |

Enables the audio.

The audio is enabled by default.

Note
  This method controls the underlying states of the Engine. It is still valid after one leaves channel.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ disableAudio

- (int) disableAudio |  |  |

Disables the audio.

Note
  This method controls the underlying states of the Engine. It is still valid after one leaves channel.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableLocalAudio:

- (int) enableLocalAudio: |  | (BOOL) | enabled |

Enables or disables the local audio capture.

The audio function is enabled by default. This method disables or re-enables the local audio function, that is, to stop or restart local audio capture 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.

Parameters

  enabled | Determines whether to disable or re-enable the local audio function: `YES`: (Default) Re-enable the local audio function, that is, to start local audio capture and processing. `NO`: Disable the local audio function, that is, to stop local audio capture and processing.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setAudioProfile:

- (int) setAudioProfile: |  | (AgoraAudioProfile) | profile |

Sets the audio profile.

Note
  - Call this method before calling `joinChannelByToken`.
  - In scenarios requiring high-quality audio, Agora recommends setting `profile` as `AgoraAudioProfileMusicHighQuality`(4).
  - To set the audio scenario, call the sharedEngineWithConfig:delegate: sharedEngineWithConfig method.

Parameters

  profile | The audio profile, such as the sample rate, bitrate, encoding mode, and the number of channels, see AgoraAudioProfile.

Returns
  - 0: Success.
  - <0: Failure.

## ◆ setAudioScenario:

- (int) setAudioScenario: |  | (AgoraAudioScenario) | scenario |

## ◆ enableAudioVolumeIndication:smooth:reportVad:

- (int) enableAudioVolumeIndication: |  | (NSInteger) | interval
smooth: |  | (NSInteger) | smooth
reportVad: |  | (BOOL) | reportVad

Enables the `reportAudioVolumeIndicationOfSpeakers` callback to report on which users are speaking and the speakers' volume.

Once the AgoraRtcEngineDelegate.rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume: reportAudioVolumeIndicationOfSpeakers callback is enabled, the SDK returns the volume indication in the at the time interval set in `enableAudioVolumeIndication`, regardless of whether any user is speaking in the channel.

Parameters

  interval | Sets the time interval between two consecutive volume indications: <= 0: Disables the volume indication. > 0: Time interval (ms) between two consecutive volume indications, and should be integral multiple of 200 (less than 200 will be set to 200).
  smooth | The smoothing factor that sets the sensitivity of the audio volume indicator. The value range is [0, 10]. The greater the value, the more sensitive the indicator. The recommended value is 3.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ adjustUserPlaybackSignalVolume:volume:

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

Adjust the playback signal volume of a specified remote user.

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

Note**

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

Parameters

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

- 0: Mute.
- 100: Original volume.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ startRecordingDeviceTest:

- (int) startRecordingDeviceTest: |  | (int) | indicationInterval |

Starts the microphone test.

Note
  This method applies to macOS and iOS.

This method tests whether the microphone works properly. Once the test starts, the SDK reports the volume information by using the [reportAudioVolumeIndicationOfSpeakers]([AgoraRtcEngineDelegate rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume:]) callback method.

Parameters

  indicationInterval | Interval (ms) at which to report the microphone volume.

Returns
  * 0: Success. <0: Failure.

## ◆ stopRecordingDeviceTest

- (int) stopRecordingDeviceTest |  |  |

Stops the microphone test.

Note
  This method applies to macOS and iOS.

This method stops testing the microphone. You must call this method to stop the test after calling the [startRecordingDeviceTest](startRecordingDeviceTest:) method.

Returns
  * 0: Success. <0: Failure.

## ◆ startPlaybackDeviceTest:

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

Starts a playback device test.

Note
  This method applies to macOS and iOS.

This method tests whether the playback device works properly with the specified playback audio file.

Parameters

  audioFileName | File path of the audio file for the test, which is in utf8 absolute path:

- Supported File Format: wav, mp3, m4a, and aac
- Supported File Sampling Rate: 8000, 16000, 32000, 44100, and 48000

Returns
  * 0: Success. <0: Failure.

## ◆ stopPlaybackDeviceTest

- (int) stopPlaybackDeviceTest |  |  |

Stops the playback device test.

Note
  This method applies to macOS and iOS.

This method stops testing the playback device. You must call this method to stop the test after calling [startPlaybackDeviceTest](startPlaybackDeviceTest:).

Returns
  * 0: Success. <0: Failure.

## ◆ registerExtensionWithVendor:extension:sourceType:

- (int) registerExtensionWithVendor: |  | (NSString *_Nonnull) | provider
extension: |  | (NSString *_Nonnull) | extension
sourceType: |  | (AgoraMediaSourceType) | sourceType

Registers an extension. Normally, you should call this function immediately after initializing the engine. Once an extension is registered, the SDK will automatically create and add it to the pipeline.

Parameters

  provider | The name of the extension provider, e.g. agora.io.
  extension | The name of the extension, e.g. agora.beauty.
  sourceType | The source type of the extension, e.g. AgoraMediaSourceTypePrimaryCamera. See AgoraMediaSourceType.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableExtensionWithVendor:extension:enabled:

- (int) enableExtensionWithVendor: |  | (NSString *_Nonnull) | provider
extension: |  | (NSString *_Nonnull) | extension
enabled: |  | (BOOL) | enabled

Enable/Disable an extension. By calling this function, you can dynamically enable/disable the extension without changing the pipeline. For example, enabling/disabling Extension_A means the data will be adapted/bypassed by Extension_A.

NOTE: For compatibility reasons, if you haven't call registerExtensionWithVendor, enableExtension will automatically register the specified extension. We suggest you call registerExtensionWithVendor explicitly.

Parameters

  provider | The name of the extension provider, e.g. agora.io.
  extension | The name of the extension, e.g. agora.beauty.
  enabled | Whether to enable the extension: true: (Default) Enable the extension. false: Disable the extension.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableExtensionWithVendor:extension:enabled:sourceType:

- (int) enableExtensionWithVendor: |  | (NSString *_Nonnull) | provider
extension: |  | (NSString *_Nonnull) | extension
enabled: |  | (BOOL) | enabled
sourceType: |  | (AgoraMediaSourceType) | sourceType

Enable/Disable an extension. By calling this function, you can dynamically enable/disable the extension without changing the pipeline. For example, enabling/disabling Extension_A means the data will be adapted/bypassed by Extension_A.

NOTE: For compatibility reasons, if you haven't call registerExtensionWithVendor, enableExtension will automatically register the specified extension. We suggest you call registerExtensionWithVendor explicitly.

Parameters

  provider | The name of the extension provider, e.g. agora.io.
  extension | The name of the extension, e.g. agora.beauty.
  enabled | Whether to enable the extension: true: (Default) Enable the extension. false: Disable the extension.
  sourceType | The source type of the extension, e.g. AgoraMediaSourceTypePrimaryCamera. See AgoraMediaSourceType

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableExtensionWithVendor:extension:extensionInfo:enabled:

- (int) enableExtensionWithVendor: |  | (NSString *_Nonnull) | provider
extension: |  | (NSString *_Nonnull) | extension
extensionInfo: |  | (AgoraExtensionInfo *_Nonnull) | extensionInfo
enabled: |  | (BOOL) | enabled

Enable/Disable an extension. By calling this function, you can dynamically enable/disable the extension without changing the pipeline. For example, enabling/disabling Extension_A means the data will be adapted/bypassed by Extension_A.

NOTE: For compatibility reasons, if you haven't call registerExtensionWithVendor, enableExtension will automatically register the specified extension. We suggest you call registerExtensionWithVendor explicitly.

Parameters

  provider | The name of the extension provider, e.g. agora.io.
  extension | The name of the extension, e.g. agora.beauty.
  extensionInfo | The information for extension definition see AgoraExtensionInfo
  enabled | Whether to enable the extension: true: (Default) Enable the extension. false: Disable the extension.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setExtensionProviderPropertyWithVendor:key:value:

- (int) setExtensionProviderPropertyWithVendor: |  | (NSString *_Nonnull) | provider
key: |  | (NSString *_Nonnull) | key
value: |  | (NSString *_Nonnull) | value

Sets the provider property of an extension.

Parameters

  provider | The name of the extension provider, e.g. agora.io.
  key | The key of the extension.
  value | The JSON formatted value of the extension key.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setExtensionPropertyWithVendor:extension:key:value:

- (int) setExtensionPropertyWithVendor: |  | (NSString *_Nonnull) | provider
extension: |  | (NSString *_Nonnull) | extension
key: |  | (NSString *_Nonnull) | key
value: |  | (NSString *_Nonnull) | value

Sets the properties of an extension.

Parameters

  provider | The name of the extension provider, e.g. agora.io.
  extension | The name of the extension, e.g. agora.beauty.
  key | The key of the extension.
  value | The JSON formatted value of the extension key.

Returns
  true, if get property success, otherwise false

## ◆ setExtensionPropertyWithVendor:extension:key:value:sourceType:

- (int) setExtensionPropertyWithVendor: |  | (NSString *_Nonnull) | provider
extension: |  | (NSString *_Nonnull) | extension
key: |  | (NSString *_Nonnull) | key
value: |  | (NSString *_Nonnull) | value
sourceType: |  | (AgoraMediaSourceType) | sourceType

Sets the properties of an extension.

Parameters

  provider | The name of the extension provider, e.g. agora.io.
  extension | The name of the extension, e.g. agora.beauty.
  key | The key of the extension.
  value | The JSON formatted value of the extension key.
  sourceType | The source type of the extension, e.g. AgoraMediaSourceTypePrimaryCamera. See AgoraMediaSourceType.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setExtensionPropertyWithVendor:extension:extensionInfo:key:value:

- (int) setExtensionPropertyWithVendor: |  | (NSString *_Nonnull) | provider
extension: |  | (NSString *_Nonnull) | extension
extensionInfo: |  | (AgoraExtensionInfo *_Nonnull) | extensionInfo
key: |  | (NSString *_Nonnull) | key
value: |  | (NSString *_Nonnull) | value

Sets the properties of an extension.

Parameters

  provider | The name of the extension provider, e.g. agora.io.
  extension | The name of the extension, e.g. agora.beauty.
  extensionInfo | The information for extension. See AgoraExtensionInfo.
  key | The key of the extension.
  value | The JSON formatted value of the extension key.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ getExtensionPropertyWithVendor:extension:key:

- (NSString * _Nullable) getExtensionPropertyWithVendor: |  | (NSString *_Nonnull) | provider
extension: |  | (NSString *_Nonnull) | extension
key: |  | (NSString *_Nonnull) | key

Gets the properties of an extension.

Parameters

  provider | The name of the extension provider, e.g. agora.io.
  extension | The name of the extension, e.g. agora.beauty.
  key | The key of the extension.

Returns
  - JSON formatted string of property's value; return null if failed

## ◆ getExtensionPropertyWithVendor:extension:key:sourceType:

- (NSString * _Nullable) getExtensionPropertyWithVendor: |  | (NSString *_Nonnull) | provider
extension: |  | (NSString *_Nonnull) | extension
key: |  | (NSString *_Nonnull) | key
sourceType: |  | (AgoraMediaSourceType) | sourceType

Gets the properties of an extension.

Parameters

  provider | The name of the extension provider, e.g. agora.io.
  extension | The name of the extension, e.g. agora.beauty.
  key | The key of the extension.
  sourceType | The source type of the extension, e.g. AgoraMediaSourceTypePrimaryCamera. See AgoraMediaSourceType.

Returns
  - JSON formatted string of property's value; return null if failed

## ◆ getExtensionPropertyWithVendor:extension:extensionInfo:key:

- (NSString * _Nullable) getExtensionPropertyWithVendor: |  | (NSString *_Nonnull) | provider
extension: |  | (NSString *_Nonnull) | extension
extensionInfo: |  | (AgoraExtensionInfo *_Nonnull) | extensionInfo
key: |  | (NSString *_Nonnull) | key

Gets the properties of an extension.

Parameters

  provider | The name of the extension provider, e.g. agora.io.
  extension | The name of the extension, e.g. agora.beauty.
  extensionInfo | The information for extension. See AgoraExtensionInfo.
  key | The key of the extension.

Returns
  - JSON formatted string of property's value; return null if failed

## ◆ enableVideo

- (int) enableVideo |  |  |

Enables the video.

You can call this method either before joining a channel or during a call. If you call this method before entering a channel, the service starts the video; if you call it during a call, the audio call switches to a video call.

Note
  This method controls the underlying states of the engine. It is still valid after one leaves the channel.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ disableVideo

- (int) disableVideo |  |  |

Disables the video.

This method stops capturing the local video and receiving all remote video. To enable the local preview function, call enableLocalVideo: enableLocalVideo(YES).

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableLocalVideo:

- (int) enableLocalVideo: |  | (BOOL) | enabled |

Disables or re-enables the local video capture.

Once you enable the video using enableVideo, the local video is enabled by default. This method disables or re-enables the local video capture.

`enableLocalVideo(NO)` applies to scenarios when the user wants to watch the remote video without sending any video stream to the other user.

Note
  Call this method after `enableVideo`. Otherwise, this method may not work properly.

Parameters

  enabled | Determines whether to disable or re-enable the local video, including the capturer, renderer, and sender: `YES`: (Default) Re-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. When you set `enabled` as `NO`, this method does not require a local camera.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ queryCodecCapability

- (NSArray <AgoraVideoCodecCapInfo *> *_Nullable) queryCodecCapability |  |  |

Querys current device codec capacity.

Returns
  The codec actual capability with array of AgoraVideoCodecCapInfo.

## ◆ queryDeviceScore

- (int) queryDeviceScore |  |  |

Queries the score of the current device.

Returns

  > 0: If the value is greater than 0, it means that the device score has been retrieved and represents the score value.

  Most devices score between 60-100, with higher scores indicating better performance.

< 0: Failure.

## ◆ queryHDRCapability:

- (AgoraHDRCapability) queryHDRCapability: |  | (AgoraVideoModule) | videoModule |

Query the hdr capability of video module.

Returns
  Default is AgoraHDRCapabilityUnknown.

## ◆ setupLocalVideo:

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

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
  Call this method before joining a channel.

Parameters

  local | The local video view and settings. See AgoraRtcVideoCanvas.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setLocalRenderTargetFps:targetFps:

- (int) setLocalRenderTargetFps: |  | (AgoraVideoSourceType) | sourceType
targetFps: |  | (int) | targetFps

Sets the target frames per second (FPS) for the local render target.

Parameters

  sourceType | The type of video source.
  targetFps | The target frames per second to be set.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setRemoteRenderTargetFps:

- (int) setRemoteRenderTargetFps: |  | (int) | targetFps |

Sets the target frames per second (FPS) for the remote render target.

Parameters

  targetFps | The target frames per second to be set for the remote render target.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setLocalRenderMode:mirror:

- (int) setLocalRenderMode: |  | (AgoraVideoRenderMode) | mode
mirror: |  | (AgoraVideoMirrorMode) | mirror

Updates the display mode of the local video view.

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

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

Parameters

  mode | Sets the local display mode. See AgoraVideoRenderMode.
  mirror | Sets the mirror mode. See #AgoraVideoMirrorMode

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ startPreview

- (int) startPreview |  |  |

Starts the local video preview before joining a channel.

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

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ startPreview:

- (int) startPreview: |  | (AgoraVideoSourceType) | sourceType |

Starts the local video preview before joining a channel.

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

Parameters

  sourceType | source type of video. See AgoraVideoSourceType.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ stopPreview

- (int) stopPreview |  |  |

Stops the local video preview and the video.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ stopPreview:

- (int) stopPreview: |  | (AgoraVideoSourceType) | sourceType |

Stops the local video preview and the video.

Parameters

  sourceType | source type of video. See AgoraVideoSourceType.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setRemoteRenderMode:mode:mirror:

- (int) setRemoteRenderMode: |  | (NSUInteger) | uid
mode: |  | (AgoraVideoRenderMode) | mode
mirror: |  | (AgoraVideoMirrorMode) | mirror

Configures the remote video display mode. The application can call this method multiple times to change the display mode.

Parameters

  uid | User id of the user whose video streams are received.
  mode | AgoraVideoRenderMode
  mirror | AgoraVideoMirrorMode

Returns
  * 0: Success. <0: Failure.

## ◆ muteLocalVideoStream:

- (int) muteLocalVideoStream: |  | (BOOL) | mute |

Stops or resumes sending the local video stream.

Parameters

  mute | Determines whether to send or stop sending the local video stream: `YES`: Stop sending the local video stream. `NO`: (Default) Send the local video stream.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ muteRemoteVideoStream:mute:

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

Stops or resumes receiving the video stream of a specified user.

You can call this method before or after joining a channel. If a user leaves a channel, the settings in this method become invalid.

Parameters

  uid | ID of the specified remote user.
  mute | Whether to stop receiving the video stream of the specified user: `YES`: Stop receiving the video stream of the specified user. `NO`: (Default) Resume receiving the video stream of the specified user.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ muteAllRemoteVideoStreams:

- (int) muteAllRemoteVideoStreams: |  | (BOOL) | mute |

Stops/Resumes receiving all remote video streams.

This method works for all remote users that join or will join a channel. You can call this method before, during, or after a call.

- If you call `muteAllRemoteVideoStreams`(YES) before joining a channel, the local user does not receive any video stream after joining the channel.
- If you call `muteAllRemoteVideoStreams`(YES) after joining a channel, the local use stops receiving any video stream from any user in the channel, including any user who joins the channel after you call this method.
- If you call `muteAllRemoteVideoStreams`(YES) after leaving a channel, the local user does not receive any video stream the next time the user joins a channel.

After you successfully call `muteAllRemoteVideoStreams`(YES), you can take the following actions:

- To resume receiving all remote video streams, call `muteAllRemoteVideoStreams`(NO).
- To resume receiving the video stream of a specified user, call muteRemoteVideoStream:mute: muteRemoteVideoStream(uid, NO), where `uid` is the ID of the user whose video stream you want to resume receiving.

Note
  - The result of calling this method is affected by calling enableVideo and disableVideo. Settings in `muteAllRemoteVideoStreams` stop taking effect if either of the following occurs:
    - Calling `enableVideo` after `muteAllRemoteVideoStreams`(YES).
    - Calling `disableVideo` after `muteAllRemoteVideoStreams`(NO).
  - In scenarios involving multiple channels, use AgoraRtcChannelMediaOptions::autoSubscribeVideo autoSubscribeVideo to set whether to receive remote video streams for a specific channel.

Parameters

  mute | Whether to stop receiving remote video streams: `YES`: Stop receiving any remote video stream. `NO`: (Default) Resume receiving all remote video streams.

Returns
  - 0: Success.
  - <0: Failure.

## ◆ setFaceShapeBeautyOptions:options:

- (int) setFaceShapeBeautyOptions: |  | (BOOL) | enable
options: |  | (AgoraFaceShapeBeautyOptions *_Nullable) | options

Enables/Disables face shape and sets the beauty options.

Note
  Call this method after calling the [enableVideo]([AgoraRtcEngineKit enableVideo]) method.

Parameters

  enable | Sets whether or not to enable face shape:

- `YES`: Enable face shape.
- `NO`: Disable face shape.
  Parameters

    options | Sets the face shape beauty option. See AgoraFaceShapeBeautyOptions.

  Returns
    * 0: Success. < 0: Failure.

## ◆ setFaceShapeBeautyOptions:options:sourceType:

- (int) setFaceShapeBeautyOptions: |  | (BOOL) | enable
options: |  | (AgoraFaceShapeBeautyOptions *_Nullable) | options
sourceType: |  | (AgoraMediaSourceType) | sourceType

Enables/Disables face shape and sets the beauty options.

Note
  Call this method after calling the [enableVideo]([AgoraRtcEngineKit enableVideo]) method.

Parameters

  enable | Sets whether or not to enable face shape:

- `YES`: Enable face shape.
- `NO`: Disable face shape.
  Parameters

    options | Sets the face shape style option. See AgoraFaceShapeBeautyOptions.
    sourceType | The source type of the extension, e.g. AgoraMediaSourceTypePrimaryCamera. See AgoraMediaSourceType.

  Returns
    * 0: Success. < 0: Failure.

## ◆ getFaceShapeBeautyOptions

- (AgoraFaceShapeBeautyOptions * _Nullable) getFaceShapeBeautyOptions |  |  |

Gets the face shape beauty options.

Note
  Call this method after calling the [enableVideo]([AgoraRtcEngineKit enableVideo]) method.

Returns
  * 0: Success. < 0: Failure.

## ◆ getFaceShapeBeautyOptions:

- (AgoraFaceShapeBeautyOptions * _Nullable) getFaceShapeBeautyOptions: |  | (AgoraMediaSourceType) | sourceType |

Gets the face shape beauty options.

Note
  Call this method after calling the [enableVideo]([AgoraRtcEngineKit enableVideo]) method.

Parameters

  sourceType | The source type of the extension, e.g. AgoraMediaSourceTypePrimaryCamera. See AgoraMediaSourceType.

Returns
  * 0: Success. < 0: Failure.

## ◆ setFaceShapeAreaOptions:

- (int) setFaceShapeAreaOptions: |  | (AgoraFaceShapeAreaOptions *_Nullable) | options |

Sets the face shape area options.

Note
  Call this method after calling the [setFaceShapeBeautyOptions]([AgoraRtcEngineKit setFaceShapeBeautyOptions]) method.

Parameters

  options | Sets the face shape area option. See AgoraFaceShapeAreaOptions..

Returns
  * 0: Success. < 0: Failure.

## ◆ setFaceShapeAreaOptions:sourceType:

- (int) setFaceShapeAreaOptions: |  | (AgoraFaceShapeAreaOptions *_Nullable) | options
sourceType: |  | (AgoraMediaSourceType) | sourceType

Sets the face shape area options.

Note
  Call this method after calling the [setFaceShapeBeautyOptions]([AgoraRtcEngineKit setFaceShapeBeautyOptions]) method.

Parameters

  options | Sets the face shape area option. See AgoraFaceShapeAreaOptions.
  sourceType | The source type of the extension, e.g. AgoraMediaSourceTypePrimaryCamera. See AgoraMediaSourceType.

Returns
  * 0: Success. < 0: Failure.

## ◆ getFaceShapeAreaOptions:

- (AgoraFaceShapeAreaOptions * _Nullable) getFaceShapeAreaOptions: |  | (AgoraFaceShapeArea) | area |

Gets the face shape area options.

Note
  Call this method after calling the [enableVideo]([AgoraRtcEngineKit enableVideo]) method.

Parameters

  area | Sets the face shape area. See AgoraFaceShapeArea.

Returns
  * 0: Success. < 0: Failure.

## ◆ getFaceShapeAreaOptions:sourceType:

- (AgoraFaceShapeAreaOptions * _Nullable) getFaceShapeAreaOptions: |  | (AgoraFaceShapeArea) | area
sourceType: |  | (AgoraMediaSourceType) | sourceType

Gets the face shape area options.

Note
  Call this method after calling the [enableVideo]([AgoraRtcEngineKit enableVideo]) method.

Parameters

  area | Sets the face shape area. See AgoraFaceShapeArea.
  sourceType | The source type of the extension, e.g. AgoraMediaSourceTypePrimaryCamera. See AgoraMediaSourceType.

Returns
  * 0: Success. < 0: Failure.

## ◆ setVideoDenoiserOptions:options:

- (int) setVideoDenoiserOptions: |  | (BOOL) | enable
options: |  | (AgoraVideoDenoiserOptions *_Nullable) | options

Sets video noise reduction.

Since
  v4.0.0

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

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

Note:**

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

Parameters

  enable | Sets whether to enable video noise reduction:

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

Parameters

  options | The video noise reduction options. See AgoraVideoDenoiserOptions.

Returns
  * 0: Success. < 0: Failure.

## ◆ setVideoDenoiserOptions:options:sourceType:

- (int) setVideoDenoiserOptions: |  | (BOOL) | enable
options: |  | (AgoraVideoDenoiserOptions *_Nullable) | options
sourceType: |  | (AgoraMediaSourceType) | sourceType

Sets video noise reduction.

Since
  v4.0.0

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

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

Note:**

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

Parameters

  enable | Sets whether to enable video noise reduction:

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

Parameters

  options | The video noise reduction options. See AgoraVideoDenoiserOptions.
  sourceType | The source type of the extension, e.g. AgoraMediaSourceTypePrimaryCamera. See AgoraMediaSourceType.

Returns
  * 0: Success. < 0: Failure.

## ◆ setLowlightEnhanceOptions:options:

- (int) setLowlightEnhanceOptions: |  | (BOOL) | enable
options: |  | (AgoraLowlightEnhanceOptions *_Nullable) | options

Sets low-light enhancement.

Since
  v4.0.0

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

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

Note:**

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

Parameters

  enable | Sets whether to enable low-light enhancement:

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

Parameters

  options | The low-light enhancement options. See AgoraLowlightEnhanceOptions.

Returns
  * 0: Success. < 0: Failure.

## ◆ setLowlightEnhanceOptions:options:sourceType:

- (int) setLowlightEnhanceOptions: |  | (BOOL) | enable
options: |  | (AgoraLowlightEnhanceOptions *_Nullable) | options
sourceType: |  | (AgoraMediaSourceType) | sourceType

Sets low-light enhancement.

Since
  v4.0.0

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

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

Note:**

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

Parameters

  enable | Sets whether to enable low-light enhancement:

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

Parameters

  options | The low-light enhancement options. See AgoraLowlightEnhanceOptions.
  sourceType | The source type of the extension, e.g. AgoraMediaSourceTypePrimaryCamera. See AgoraMediaSourceType.

Returns
  * 0: Success. < 0: Failure.

## ◆ setColorEnhanceOptions:options:

- (int) setColorEnhanceOptions: |  | (BOOL) | enable
options: |  | (AgoraColorEnhanceOptions *_Nullable) | options

Sets color enhancement.

Since
  v4.0.0

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

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

Note:**

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

Parameters

  enable | Sets whether to enable color enhancement:

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

Parameters

  options | The color enhancement options. See AgoraColorEnhanceOptions.

Returns
  * 0: Success. < 0: Failure.

## ◆ setColorEnhanceOptions:options:sourceType:

- (int) setColorEnhanceOptions: |  | (BOOL) | enable
options: |  | (AgoraColorEnhanceOptions *_Nullable) | options
sourceType: |  | (AgoraMediaSourceType) | sourceType

Sets color enhancement.

Since
  v4.0.0

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

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

Note:**

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

Parameters

  enable | Sets whether to enable color enhancement:

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

Parameters

  options | The color enhancement options. See AgoraColorEnhanceOptions.
  sourceType | The source type of the extension, e.g. AgoraMediaSourceTypePrimaryCamera. See AgoraMediaSourceType.

Returns
  * 0: Success. < 0: Failure.

## ◆ enableVirtualBackground:backData:segData:

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

Enables/Disables the virtual background. (beta function)

Since
  v3.7.200

After enabling the virtual background function, you can replace the original background image of the local user with a custom background image. After the replacement, all users in the channel can see the custom background image. You can find out from the [virtualBackgroundSourceEnabled]([AgoraRtcEngineDelegate rtcEngine:virtualBackgroundSourceEnabled:reason:]) callback whether the virtual background is successfully enabled or the cause of any errors.

Note**:

- This method applies to macOS and iOS.
- Before calling this method, ensure that you have integrated the `AgoraVideoSegmentationExtension.framework` dynamic library into the project folder.
- Call this method after [enableVideo]([AgoraRtcEngineKit enableVideo]).
- This function requires a high-performance device. Agora recommends that you use this function on devices with an i5 CPU and better.
- Agora recommends that you use this function in scenarios that meet the following conditions:
  - A high-definition camera device is used, and the environment is uniformly lit.
  - The captured video image is uncluttered, the user's portrait is half-length and largely unobstructed, and the background is a single color that differs from the color of the user's clothing.

Parameters

  enable | Sets whether to enable the virtual background:

- `YES`: Enable.
- `NO`: Disable.
  Parameters

    backData | The custom background image. See AgoraVirtualBackgroundSource.

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

Parameters

  segData | See AgoraSegmentationProperty.

Returns
  0: Success. < 0: Failure. VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_SUCCESS = 0, VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_IMAGE_NOT_EXIST = -1, VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_COLOR_FORMAT_NOT_SUPPORTED = -2, VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_DEVICE_NOT_SUPPORTED = -3,

## ◆ enableVirtualBackground:backData:segData:sourceType:

- (int) enableVirtualBackground: |  | (BOOL) | enable
backData: |  | (AgoraVirtualBackgroundSource *_Nullable) | backData
segData: |  | (AgoraSegmentationProperty *_Nullable) | segData
sourceType: |  | (AgoraMediaSourceType) | sourceType

Enables/Disables the virtual background. (beta function)

Since
  v3.7.200

After enabling the virtual background function, you can replace the original background image of the local user with a custom background image. After the replacement, all users in the channel can see the custom background image. You can find out from the [virtualBackgroundSourceEnabled]([AgoraRtcEngineDelegate rtcEngine:virtualBackgroundSourceEnabled:reason:]) callback whether the virtual background is successfully enabled or the cause of any errors.

Note**:

- This method applies to macOS and iOS.
- Before calling this method, ensure that you have integrated the `AgoraVideoSegmentationExtension.framework` dynamic library into the project folder.
- Call this method after [enableVideo]([AgoraRtcEngineKit enableVideo]).
- This function requires a high-performance device. Agora recommends that you use this function on devices with an i5 CPU and better.
- Agora recommends that you use this function in scenarios that meet the following conditions:
  - A high-definition camera device is used, and the environment is uniformly lit.
  - The captured video image is uncluttered, the user's portrait is half-length and largely unobstructed, and the background is a single color that differs from the color of the user's clothing.

Parameters

  enable | Sets whether to enable the virtual background:

- `YES`: Enable.
- `NO`: Disable.
  Parameters

    backData | The custom background image. See AgoraVirtualBackgroundSource.

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

Parameters

  segData | See AgoraSegmentationProperty.
  sourceType | The source type of the extension, e.g. AgoraMediaSourceTypePrimaryCamera. See AgoraMediaSourceType.

Returns
  0: Success. < 0: Failure. VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_SUCCESS = 0, VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_IMAGE_NOT_EXIST = -1, VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_COLOR_FORMAT_NOT_SUPPORTED = -2, VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_DEVICE_NOT_SUPPORTED = -3,

## ◆ setVideoScenario:

- (int) setVideoScenario: |  | (AgoraApplicationScenarioType) | scenarioType |

You can call this method to set the expected video scenario. The SDK witll optimize the video experience for each scenario you set.

Since
  v4.2.0

Parameters

  scenarioType | The video application scenario(AgoraApplicationScenarioType).

Returns
  * 0: Success. < 0: Failure.
  - -1(ERR_FAILED): A general error occurs (no specified reason).
  - -4(ERR_NOT_SUPPORTED): Unable to set video application scenario.
  - -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

## ◆ setVideoQoEPreference:

- (int) setVideoQoEPreference: |  | (AgoraQoEPreferenceType) | preferenceType |

Sets the video qoe preference. You can call this method to set the expected QoE Preference. The SDK will optimize the video experience for each preference you set.

Since
  v4.2.1

Parameters

  preferenceType | The qoe preference type. See #VIDEO_QOE_PREFERENCE_TYPE.

Returns
  * - 0: Success. < 0: Failure.
  - -1(ERR_FAILED): A general error occurs (no specified reason).
  - -4(ERR_NOT_SUPPORTED): Unable to set video application scenario.
  - -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

## ◆ isFeatureAvailableOnDevice:

- (BOOL) isFeatureAvailableOnDevice: |  | (AgoraFeatureType) | type |

Whether the target feature is available for the device.

Since
  v4.3.0

Parameters

  type | The feature type. See AgoraFeatureType.

Returns
  - true: available.
  - false: not available.

## ◆ setVoiceBeautifierPreset:

- (int) setVoiceBeautifierPreset: |  | (AgoraVoiceBeautifierPreset) | preset |

Sets an SDK preset voice beautifier effect.

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

You can set different voice beautifier effects for different scenarios. See Set the Voice Beautifier and Audio Effects.

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

Note
  - You can call this method either before or after joining a channel.
  - Do not set the `profile` parameter of setAudioProfile to `AUDIO_PROFILE_SPEECH_STANDARD(1)` or `AUDIO_PROFILE_IOT(6)`; otherwise, this method call fails.
  - This method works best with the human voice. Agora does not recommend using this method for audio containing music.
  - After calling this method, Agora recommends not calling the following methods, because they can override setAudioEffectParameters:
    - setAudioEffectPreset
    - setVoiceBeautifierPreset
    - setLocalVoicePitch
    - setLocalVoiceEqualization
    - setLocalVoiceReverb
    - setVoiceBeautifierParameters

Parameters

  preset | The options for SDK preset voice beautifier effects: #VOICE_BEAUTIFIER_PRESET.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setVoiceConversionPreset:

- (int) setVoiceConversionPreset: |  | (AgoraVoiceConversionPreset) | preset |

Sets an SDK preset voice conversion.

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

You can set different audio effects for different scenarios. See Set the Voice Beautifier and Audio Effects.

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

Note
  - You can call this method either before or after joining a channel.
  - Do not set the profile `parameter` of `setAudioProfile` to `AUDIO_PROFILE_SPEECH_STANDARD(1)` or `AUDIO_PROFILE_IOT(6)`; otherwise, this method call fails.
  - This method works best with the human voice. Agora does not recommend using this method for audio containing music.
  - If you call this method and set the `preset` parameter to enumerators except `ROOM_ACOUSTICS_3D_VOICE` or `PITCH_CORRECTION`, do not call setAudioEffectParameters; otherwise, `setAudioEffectParameters` overrides this method.
  - After calling this method, Agora recommends not calling the following methods, because they can override `setAudioEffectPreset`:
    - setVoiceBeautifierPreset
    - setLocalVoicePitch
    - setLocalVoiceFormant
    - setLocalVoiceEqualization
    - setLocalVoiceReverb
    - setVoiceBeautifierParameters

Parameters

  preset | The options for SDK preset audio effects. See #VOICE_CONVERSION_PRESET.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setVoiceBeautifierParameters:param1:param2:

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

Sets parameters for SDK preset voice beautifier effects.

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

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

To achieve better audio effect quality, before you call this method, Agora recommends calling setAudioProfile, and setting the `scenario` parameter as `AUDIO_SCENARIO_GAME_STREAMING(3)` and the `profile` parameter as `AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4)` or `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)`.

Note
  - You can call this method either before or after joining a channel.
  - Do not set the `profile` parameter of setAudioProfile as `AUDIO_PROFILE_SPEECH_STANDARD(1)` or `AUDIO_PROFILE_IOT(6)`; otherwise, this method call does not take effect.
  - This method works best with the human voice. Agora does not recommend using this method for audio containing music.
  - After you call this method, Agora recommends not calling the following methods, because they can override `setVoiceBeautifierParameters`:
    - setAudioEffectPreset
    - setAudioEffectParameters
    - setVoiceBeautifierPreset
    - setLocalVoicePitch
    - setLocalVoiceEqualization
    - setLocalVoiceReverb

Parameters

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

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setVoiceConversionParameters:param1:param2:

- (int) setVoiceConversionParameters: |  | (AgoraVoiceConversionPreset) | preset
param1: |  | (int) | param1
param2: |  | (int) | param2

Set parameters for SDK preset voice conversion.

Note
  - reserved interface

Parameters

  preset | The options for SDK preset audio effects. See #VOICE_CONVERSION_PRESET.
  param1 | reserved.
  param2 | reserved.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setHeadphoneEQPreset:

- (int) setHeadphoneEQPreset: |  | (AgoraHeadphoneEQPreset) | preset |

Sets preset audio playback effect for remote headphones after remote audio is mixed.

Parameters

  preset | The preset key: #HEADPHONE_EQUALIZER_PRESET. HEADPHONE_EQUALIZER_OFF = 0x00000000 : Turn off the eualizer effect for headphones. HEADPHONE_EQUALIZER_OVEREAR = 0x04000001 : For over-ear headphones only. HEADPHONE_EQUALIZER_INEAR = 0x04000002 : For in-ear headphones only.

Returns
  - 0: Success.
  - < 0: Failure.
    - -1(ERR_FAILED): A general error occurs (no specified reason).

## ◆ setHeadphoneEQParameters:highGain:

- (int) setHeadphoneEQParameters: |  | (int) | lowGain
highGain: |  | (int) | highGain

Sets the parameters of audio playback effect for remote headphones after remote audio is mixed.

Parameters

  lowGain | The higher the parameter value, the deeper the sound. The value range is [-10,10].
  highGain | The higher the parameter value, the sharper the sound. The value range is [-10,10].

Returns
  - 0: Success.
  - < 0: Failure.
    - -1(ERR_FAILED): A general error occurs (no specified reason).

## ◆ enableVoiceAITuner:type:

- (int) enableVoiceAITuner: |  | (BOOL) | enabled
type: |  | (AgoraVoiceAITunerType) | type

Enables or disables the voice AI tuner.

Parameters

  enabled | Determines whether to enable the voice AI tuner: `YES`: Enable the voice AI tuner `NO`: (default) Disable the voice AI tuner.
  type | The options for SDK voice AI tuner types. See #VOICE_AI_TUNER_TYPE.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableSoundPositionIndication:

- (int) enableSoundPositionIndication: |  | (BOOL) | enabled |

Enables/Disables stereo panning for remote users.

If you need to use the [setRemoteVoicePosition]([AgoraRtcEngineKit setRemoteVoicePosition:pan:gain:]) method, ensure that you call this method before joining a channel to enable stereo panning for remote users.

Parameters

  enabled | Sets whether or not to enable stereo panning for remote users:

- `YES`: enables stereo panning.
- `NO`: disables stereo panning.

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

## ◆ setRemoteVoicePosition:pan:gain:

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

Sets the sound position and gain of a remote user.

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

Note:**

- Ensure that you call this method after joining a channel. For this method to work, enable stereo panning for remote users by calling [enableSoundPositionIndication]([AgoraRtcEngineKit 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.
    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.

Parameters

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

Returns
  * 0: Success. < 0: Failure.

## ◆ enableSpatialAudio:

- (int) enableSpatialAudio: |  | (BOOL) | enabled |

Enables/Disables spatial audio for remote users.

Parameters

  enabled | Sets whether or not to enable spatial audio for remote users:

- `YES`: enables spatial audio.
- `NO`: disables spatial audio.

Returns
  * 0: Success. < 0: Failure

## ◆ setAINSMode:mode:

- (int) setAINSMode: |  | (BOOL) | enabled
mode: |  | (AUDIO_AINS_MODE) | mode

Parameters

  enabled | Determines whether to enable AINS. `YES`: Enables AINS. `NO`: Disables AINS.
  mode | The type of the ains

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ selectAudioTrack:

- (int) selectAudioTrack: |  | (NSInteger) | index |

Select audio track for the music file.

Call this method when you are in a channel.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ getAudioTrackCount

- (int) getAudioTrackCount |  |  |

Get audio track count of the music file.

Call this method when you are in a channel.

Returns
  - ≥ 0: Audio track count of the music file, if the method call is successful.
  - < 0: Failure.

## ◆ startAudioRecordingWithConfig:

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

Starts an audio recording on the client.

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

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

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

Note
  Call this method after joining a channel.

Parameters

  config | Recording configuration. See AgoraAudioRecordingConfiguration.

Returns
  - 0: Success.

  - < 0: Failure.

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

## ◆ setAudioEncodedFrameDelegate:config:

- (int) setAudioEncodedFrameDelegate: |  | (id< AgoraAudioEncodedFrameDelegate > _Nullable) | delegate
config: |  | (AgoraAudioEncodedFrameDelegateConfig *_Nonnull) | config

## ◆ startEchoTestWithConfig:

- (int) startEchoTestWithConfig: |  | (AgoraEchoTestConfiguration *_Nonnull) | config |

Starts an audio/video call loop test.

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.

Parameters

  config | The configuration for audio/video echo test.

Returns
  * 0: Success. < 0: Failure.

## ◆ enableInEarMonitoring:

- (int) enableInEarMonitoring: |  | (BOOL) | enabled |

Enables in-ear monitoring.

Parameters

  enabled | Determines whether to enable in-ear monitoring. `YES`: Enable in-ear monitoring. `NO`: Disable in-ear monitoring.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableInEarMonitoring:includeAudioFilters:

- (int) enableInEarMonitoring: |  | (BOOL) | enabled
includeAudioFilters: |  | (AgoraEarMonitoringFilterType) | includeAudioFilters

Enables in-ear monitoring.

Parameters

  enabled | Determines whether to enable in-ear monitoring. `YES`: Enable in-ear monitoring. `NO`: Disable in-ear monitoring.
  includeAudioFilters | The type of the ear monitoring: AgoraEarMonitoringFilterType.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setInEarMonitoringVolume:

- (int) setInEarMonitoringVolume: |  | (NSInteger) | volume |

Sets the volume of the in-ear monitoring.

Parameters

  volume | The volume of the in-ear monitor, ranging from 0 to 100, can be amplified to 400, but not suggested. The default value is 100.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableDualStreamMode:

- (int) enableDualStreamMode: |  | (BOOL) | enabled |

Enables or disables the dual video stream mode.

Deprecated:
  v4.2.0. This method is deprecated. Use setDualStreamMode instead.

Parameters

  enabled | `YES`: Enable the dual-stream mode. `NO`: (default) Disable the dual-stream mode.

Returns
  - 0: Success.
  - <0: Failure.

## ◆ enableDualStreamMode:streamConfig:

- (int) enableDualStreamMode: |  | (BOOL) | enabled
streamConfig: |  | (AgoraSimulcastStreamConfig *_Nonnull) | streamConfig

Enables or disables the dual video stream mode.

Deprecated:
  v4.2.0. This method is deprecated. Use setDualStreamMode instead.

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

Parameters

  enabled | true: Enable the dual-stream mode. false: (default) Disable the dual-stream mode.
  streamConfig | The minor stream config

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setDualStreamMode:

- (int) setDualStreamMode: |  | (AgoraSimulcastStreamMode) | mode |

Enables, disables or auto enable the dual video stream mode.

Parameters

  mode | The dual-stream mode.

Returns
  - 0: Success.
  - <0: Failure.

## ◆ setDualStreamMode:streamConfig:

- (int) setDualStreamMode: |  | (AgoraSimulcastStreamMode) | mode
streamConfig: |  | (AgoraSimulcastStreamConfig *_Nonnull) | streamConfig

Enables, disables or auto enable the dual video stream mode.

If dual-stream mode is enabled, the subscriber can choose to receive the high-stream (high-resolution high-bitrate video stream) or low-stream (low-resolution low-bitrate video stream) If dual-stream mode is auto, if user subscriber low-stream, then we will send low-stream video using setRemoteVideoStreamType.

Parameters

  mode | The dual-stream mode.
  streamConfig | The minor stream config

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setSimulcastConfig:

- (int) setSimulcastConfig: |  | (AgoraSimulcastConfig *_Nonnull) | simulcastConfig |

Sets the multi-layer video stream configuration.

If multi-layer is configured, the subscriber can choose to receive the coresponding layer of video stream using setRemoteVideoStreamType.

Parameters

  simulcastConfig | The configuration for multi-layer video stream. It includes seven layers, ranging from STREAM_LAYER_1 to STREAM_LOW. A maximum of 3 layers can be enabled simultaneously.

Returns
  - 0: Success.
  - < 0: Failure. @technical preview

## ◆ setRemoteDefaultVideoStreamType:

- (int) setRemoteDefaultVideoStreamType: |  | (AgoraVideoStreamType) | streamType |

Sets the default stream type of the remote video if the remote user has enabled the dual-stream mode.

Parameters

  streamType | The default video stream type: AgoraVideoStreamType.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setRemoteVideoSubscriptionOptions:options:

- (int) setRemoteVideoSubscriptionOptions: |  | (NSUInteger) | uid
options: |  | (AgoraVideoSubscriptionOptions *_Nonnull) | options

Sets the remote video subscription options

Parameters

  uid | ID of the remote user sending the video stream.
  options | Sets the video subscription options.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setSubscribeAudioAllowlist:

- (int) setSubscribeAudioAllowlist: |  | (NSArray< NSNumber * > *_Nonnull) | allowlist |

Sets the allowlist of subscribe remote stream audio.

Parameters

  allowlist | The uid list of users who do subscribe to audio.

Note
  If uid is in allowlist, the remote user's audio will be subscribed, even if muteRemoteAudioStream(uid, true) and muteAllRemoteAudioStreams(true) are operated.

If a user is in the blocklist and allowlist at the same time, the user will not subscribe to audio.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setSubscribeVideoAllowlist:

- (int) setSubscribeVideoAllowlist: |  | (NSArray< NSNumber * > *_Nonnull) | allowlist |

Sets the allowlist of subscribe remote stream video.

Parameters

  allowlist | The uid list of users who do subscribe to video.

Note
  If uid is in allowlist, the remote user's video will be subscribed, even if muteRemoteVideoStream(uid, true) and muteAllRemoteVideoStreams(true) are operated.

If a user is in the blocklist and allowlist at the same time, the user will not subscribe to video.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setHighPriorityUserList:option:

- (int) setHighPriorityUserList: |  | (NSArray< NSNumber * > *_Nullable) | uidList
option: |  | (AgoraStreamFallbackOptions) | option

Sets high priority user list and related remote subscribe stream fallback option.

This method sets the high priority user list and disables/enables the vips' remote subscribe stream fallback option according to the network conditions in NASA2.

If you use the option as AgoraStreamFallbackOptionAudioOnly = 2, the AutVos will automatically switch the video from a high-stream to a low-stream, or disable the video when the downlink network conditions cannot support both audio and video to guarantee the quality of the audio. The AutVos monitors the network quality and re-enables the video stream when the network conditions improve. Once the subscribed stream falls back to audio only, or the audio stream switches back to the video stream, the [didRemoteSubscribeFallbackToAudioOnly]([AgoraRtcEngineDelegate rtcEngine:didRemoteSubscribeFallbackToAudioOnly:byUid:]) callback will be triggered.

Parameters

  option | AgoraStreamFallbackOptions

Returns
  * 0: Success. <0: Failure.

## ◆ setExternalVideoSource:useTexture:sourceType:

- (void) setExternalVideoSource: |  | (BOOL) | enable
useTexture: |  | (BOOL) | useTexture
sourceType: |  | (AgoraExternalVideoSourceType) | sourceType

Sets the external video source.

Call this API before `enableVideo` or `startPreview`.

Parameters

  enable | Determines whether to enable the external video source. `YES`: Use external video source. `NO`: Do not use external video source.

The Agora SDK does not support switching video sources dynamically in the channel. If an external video source is enabled and you are in a channel, if you want to switch to an internal video source, you must exit the channel. Then call this method to set enable as NO, and join the channel again.

Parameters

  useTexture | Determines whether to use textured video data. `YES`: Use the texture as an input. `NO`: Do not use the texture as an input.
  sourceType | Determines the type of the external video source. see AgoraExternalVideoSourceType in AgoraEnumerates.h

## ◆ setExternalVideoSource:useTexture:sourceType:encodedVideoTrackOption:

- (void) setExternalVideoSource: |  | (BOOL) | enable
useTexture: |  | (BOOL) | useTexture
sourceType: |  | (AgoraExternalVideoSourceType) | sourceType
encodedVideoTrackOption: |  | (AgoraEncodedVideoTrackOptions *_Nonnull) | encodedVideoTrackOption

Sets the external video source.

Call this API before `enableVideo` or `startPreview`.

Parameters

  enable | Determines whether to enable the external video source. `YES`: Use external video source. `NO`: Do not use external video source.

The Agora SDK does not support switching video sources dynamically in the channel. If an external video source is enabled and you are in a channel, if you want to switch to an internal video source, you must exit the channel. Then call this method to set enable as NO, and join the channel again.

Parameters

  useTexture | Determines whether to use textured video data. `YES`: Use the texture as an input. `NO`: Do not use the texture as an input.
  sourceType | Determines the type of the external video source.
  encodedVideoTrackOption | Determines encoded video track options.

## ◆ pushExternalVideoFrame:

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

Pushes the external video frame.

This method pushes the video frame using the AgoraVideoFrame class and passes it to the Agora SDK with the `format` parameter in AgoraVideoFormat.

Call setExternalVideoSource:useTexture:pushMode: setExternalVideoSource and set the `pushMode` parameter as `YES` before calling this method.

Note
  In the Communication profile, this method does not support pushing textured video frames.

Parameters

  frame | Video frame containing the SDK's encoded video data to be pushed: AgoraVideoFrame.

Returns
  - `YES`: Success.
  - `NO`: Failure.

## ◆ pushExternalVideoFrame:videoTrackId:

- (BOOL) pushExternalVideoFrame: |  | (AgoraVideoFrame *_Nonnull) | frame
videoTrackId: |  | (NSUInteger) | videoTrackId

Pushes the external video frame.

This method pushes the video frame using the AgoraVideoFrame class and passes it to the Agora SDK with the `format` parameter in AgoraVideoFormat.

Call setExternalVideoSource:useTexture:pushMode: setExternalVideoSource and set the `pushMode` parameter as `YES` before calling this method.

Note
  In the Communication profile, this method does not support pushing textured video frames.

Parameters

  frame | Video frame containing the SDK's encoded video data to be pushed: AgoraVideoFrame.
  videoTrackId | The id of the video track.

Returns
  - `YES`: Success.
  - `NO`: Failure.

## ◆ pushExternalEncodedVideoFrame:info:

- (int) pushExternalEncodedVideoFrame: |  | (NSData *_Nonnull) | frame
info: |  | (AgoraEncodedVideoFrameInfo *_Nonnull) | info

Pushes the encoded external video frame to Agora SDK.

Note
  Ensure that you have configured encoded video source before calling this method.

Parameters

  frame | The encoded external video data, which must be the direct buffer.
  info | The encoded external video frame info: AgoraEncodedVideoFrameInfo.

Returns
  - 0: Success, which means that the encoded external video frame is pushed successfully.
  - < 0: Failure, which means that the encoded external video frame fails to be pushed. @technical preview

## ◆ pushExternalEncodedVideoFrame:info:videoTrackId:

- (int) pushExternalEncodedVideoFrame: |  | (NSData *_Nonnull) | frame
info: |  | (AgoraEncodedVideoFrameInfo *_Nonnull) | info
videoTrackId: |  | (NSUInteger) | videoTrackId

Pushes the encoded external video frame to specified connection in Agora SDK.

Note
  Ensure that you have configured encoded video source before calling this method.

Parameters

  frame | The encoded external video data, which must be the direct buffer.
  info | The encoded external video frame info: AgoraEncodedVideoFrameInfo.
  videoTrackId | The id of the video track.

Returns
  - 0: Success, which means that the encoded external video frame is pushed successfully.
  - < 0: Failure, which means that the encoded external video frame fails to be pushed. @technical preview

## ◆ createCustomVideoTrack

- (unsigned int) createCustomVideoTrack |  |  |

Get an custom video track id created by internal,which could used to publish or preview

Returns
  - > 0: the useable video track id.
  - < 0: Failure.

## ◆ createCustomEncodedVideoTrack:

- (unsigned int) createCustomEncodedVideoTrack: |  | (AgoraEncodedVideoTrackOptions *_Nonnull) | encodedVideoTrackOption |

Get an custom encoded video track id created by internal,which could used to publish or preview

Returns
  - > 0: the useable video track id.
  - < 0: Failure.

## ◆ destroyCustomVideoTrack:

- (int) destroyCustomVideoTrack: |  | (NSUInteger) | videoTrackId |

destroy a created custom video track id

Parameters

  videoTrackId | The video track id which was created by createCustomVideoTrack

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ destroyCustomEncodedVideoTrack:

- (int) destroyCustomEncodedVideoTrack: |  | (NSUInteger) | videoTrackId |

destroy a created custom encoded video track id

Parameters

  videoTrackId | The video track id which was created by createCustomEncodedVideoTrack

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableExternalAudioSink:sampleRate:channels:

- (void) enableExternalAudioSink: |  | (BOOL) | enabled
sampleRate: |  | (NSUInteger) | sampleRate
channels: |  | (NSUInteger) | channels

Enables the external audio sink.

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

Parameters

  enabled | Determines whether to enable the external audio sick: true: Enable the external audio sick. false: Disable the external audio sick.
  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

## ◆ pullPlaybackAudioFrameRawData:lengthInByte:

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

Pulls the remote audio data in the RawData format.

Before calling this method, call the [enableExternalAudioSink]([AgoraRtcEngineKit enableExternalAudioSink:channels:]) 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**

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 value of the `sampleRate` parameter that you set in the [enableExternalAudioSink]([AgoraRtcEngineKit enableExternalAudioSink:channels:]) method: lengthInByte = sampleRate / 100 * 2 * number of channels * time (ms).

Returns
  - YES: Success.
  - NO: Failure.

## ◆ pullPlaybackAudioFrameSampleBufferByLengthInByte:

- (CMSampleBufferRef _Nullable) pullPlaybackAudioFrameSampleBufferByLengthInByte: |  | (NSUInteger) | lengthInByte |

Pulls the remote audio data in the SampleBuffer format.

Before calling this method, call the [enableExternalAudioSink]([AgoraRtcEngineKit enableExternalAudioSink:channels:]) 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**

Parameters

  lengthInByte | The data length (byte) of the external audio data.

The value of this parameter is related to the value of the sampleRate parameter that you set in the [enableExternalAudioSink]([AgoraRtcEngineKit enableExternalAudioSink:channels:]) method:

- `lengthInByte` = `sampleRate` / 100 * 2 * number of channels * time (ms).
- This parameter should be divisible by the value of sampleRate.

Returns
  - NOT NULL: Success.
  - NULL: Failure.

## ◆ createCustomAudioTrack:config:

- (int) createCustomAudioTrack: |  | (AgoraAudioTrackType) | trackType
config: |  | (AgoraAudioTrackConfig *_Nonnull) | config

Create a custom audio track and get the audio track id.

Note
  Ensure that you call this method before calling `joinChannel`.

Parameters

  trackType | The type of custom audio track See AgoraAudioTrackType.
  config | The config of custom audio track See AgoraAudioTrackConfig.

Returns
  - If the call is successful, SDK returns audio track id.
  - If the call fails, SDK returns 0xffffffff.

## ◆ destroyCustomAudioTrack:

- (int) destroyCustomAudioTrack: |  | (NSInteger) | trackId |

Destroy custom audio track by trackId

Parameters

  trackId | The custom audio track id

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableCustomAudioLocalPlayback:enabled:

- (int) enableCustomAudioLocalPlayback: |  | (NSInteger) | trackId
enabled: |  | (BOOL) | enabled

Sets the external audio source.

Note
  Ensure that you call this method before joining the channel.

Parameters

  trackId | custom audio track id.
  enabled | Enable/Disables the local playback of external audio track: true: Enable local playback false: Do not enable local playback

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setRecordingAudioFrameParametersWithSampleRate:channel:mode:samplesPerCall:

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

Sets the audio recording format for the `onRecordAudioFrame` callback.

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.

Parameters

  sampleRate | The audio sample rate (`samplesPerSec`) returned in the `onRecordAudioFrame` callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
  channel | The number of audio channels (`channels`) returned in the `onRecordAudioFrame` callback, which can be set as 1 or 2: 1: Mono 2: Stereo
  mode | Deprecated. The use mode of the `onRecordAudioFrame` callback.See AgoraAudioRawFrameOperationMode.
  samplesPerCall | The number of samples the `onRecordAudioFrame` callback returns. Set it as 1024 for RTMP streaming.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setPlaybackAudioFrameParametersWithSampleRate:channel:mode:samplesPerCall:

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

Sets the audio playback format for the `onPlaybackAudioFrame` callback.

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.

Parameters

  sampleRate | The sample rate (`samplesPerSec`) returned in the `onPlaybackAudioFrame` callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
  channel | The number of audio channels (`channels`) returned in the `onPlaybackAudioFrame` callback, which can be set as 1 or 2: 1: Mono 2: Stereo
  mode | Deprecated. The use mode of the `onPlaybackAudioFrame` callback. See AgoraAudioRawFrameOperationMode.
  samplesPerCall | The number of samples the `onPlaybackAudioFrame` callback returns. Set it as 1024 for RTMP streaming.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setMixedAudioFrameParametersWithSampleRate:channel:samplesPerCall:

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

Sets the mixed audio format for the `onMixedAudioFrame` callback.

Parameters

  sampleRate | The sample rate (Hz) of the audio data returned in the `onMixedAudioFrame` callback, which can set be as 8000, 16000, 32000, 44100, or 48000.
  channel | The number of channels of the audio data in `onMixedAudioFrame` callback, which can be set as 1 or 2: 1: Mono 2: Stereo
  samplesPerCall | Not supported. Sampling points in the called data returned in `onMixedAudioFrame`. For example, it is usually set as 1024 for stream pushing.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setEarMonitoringAudioFrameParametersWithSampleRate:channel:mode:samplesPerCall:

- (int) setEarMonitoringAudioFrameParametersWithSampleRate: |  | (NSInteger) | sampleRate
channel: |  | (NSInteger) | channel
mode: |  | (AgoraAudioRawFrameOperationMode) | mode
samplesPerCall: |  | (NSInteger) | samplesPerCall

Sets the audio ear monitoring format for the `onEarMonitoringAudioFrame` callback.

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 `onEarMonitoringAudioFrame` callback according to the sample interval.

Parameters

  sampleRate | The sample rate (`samplesPerSec`) returned in the `onEarMonitoringAudioFrame` callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
  channel | The number of audio channels (`channels`) returned in the `onEarMonitoringAudioFrame` callback, which can be set as 1 or 2: 1: Mono 2: Stereo
  mode | Deprecated. The use mode of the `onEarMonitoringAudioFrame` callback. See AgoraAudioRawFrameOperationMode.
  samplesPerCall | The number of samples the `onEarMonitoringAudioFrame` callback returns. Set it as 1024 for RTMP streaming.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setPlaybackAudioFrameBeforeMixingParametersWithSampleRate:channel:

- (int) setPlaybackAudioFrameBeforeMixingParametersWithSampleRate: |  | (NSInteger) | sampleRate
channel: |  | (NSInteger) | channel

Sets the audio frame parameters for the onPlaybackAudioFrameBeforeMixing callback.

Parameters

  sampleRate | The sample rate(Hz) contained in the `onPlaybackAudioFrameBeforeMixing` callback. You can set it as 8000, 16000, 32000, 44100, or 48000.
  channel | The number of channels contained in the `onPlaybackAudioFrameBeforeMixing` callback. 1: Mono. 2: Stereo.

Returns
  int
  - 0: Success.
  - < 0: Failure.

## ◆ adjustCustomAudioPublishVolume:volume:

- (int) adjustCustomAudioPublishVolume: |  | (NSInteger) | trackId
volume: |  | (NSInteger) | volume

## ◆ adjustCustomAudioPlayoutVolume:volume:

- (int) adjustCustomAudioPlayoutVolume: |  | (NSInteger) | trackId
volume: |  | (NSInteger) | volume

## ◆ getCurrentMonotonicTimeInMs

- (int64_t) getCurrentMonotonicTimeInMs |  |  |

## ◆ registerAudioSpectrumDelegate:

- (int) registerAudioSpectrumDelegate: |  | (id< AgoraAudioSpectrumDelegate > _Nullable) | delegate |

Registers an audio spectrum delegate.

You need to register the following callbacks according to your scenario:

- "onAudioSpectrumComputed": Occurs when the SDK receives the audio data and at set intervals.

Parameters

  delegate | AgoraAudioSpectrumDelegate

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ unregisterAudioSpectrumDelegate:

- (int) unregisterAudioSpectrumDelegate: |  | (id< AgoraAudioSpectrumDelegate > _Nullable) | delegate |

Releases the audio spectrum delegate.

Parameters

  delegate | AgoraAudioSpectrumDelegate

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableAudioSpectrumMonitor:

- (int) enableAudioSpectrumMonitor: |  | (int) | intervalInMS |

Enable the audio spectrum monitor.

Parameters

  intervalInMS | Sets the time interval(ms) between two consecutive audio spectrum callback. The default value is 100. This param should be larger than 10.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ disableAudioSpectrumMonitor

- (int) disableAudioSpectrumMonitor |  |  |

Disalbe the audio spectrum monitor.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableEncryption:encryptionConfig:

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

Enables/Disables the built-in encryption.

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.

Parameters

  enabled | Whether to enable the built-in encryption:

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

Parameters

  config | Configurations of built-in encryption schemas. See AgoraEncryptionConfig.

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

## ◆ createDataStream:config:

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

Creates a data stream.

Each user can create up to five data streams during the lifecycle of the [AgoraRtcChannel](AgoraRtcChannel).

Parameters

  streamId | ID of the created data stream.
  config | the config of data stream.

Returns
  * 0: Success. < 0: Failure.

## ◆ startRtmpStreamWithoutTranscoding:

- (int) startRtmpStreamWithoutTranscoding: |  | (NSString *_Nonnull) | url |

New publish stream interface, just publish raw stream

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.

Returns
  - 0: Success.
  - < 0: Failure.
    - #ERR_INVALID_ARGUMENT (2): The RTMP URL address is NULL or has a string length of 0.
    - #ERR_NOT_INITIALIZED (7): You have not initialized the RTC engine when publishing the stream.
    - #ERR_ALREADY_IN_USE (19): This streaming URL is already in use. Use a new streaming URL for CDN streaming.

## ◆ startRtmpStreamWithTranscoding:transcoding:

- (int) startRtmpStreamWithTranscoding: |  | (NSString *_Nonnull) | url
transcoding: |  | (AgoraLiveTranscoding *_Nullable) | transcoding

New publish stream interface, just publish mix stream

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.
  transcoding | Sets the CDN live audio/video transcoding settings. See AgoraLiveTranscoding.

Returns
  - 0: Success.
  - < 0: Failure.
    - #ERR_INVALID_ARGUMENT (2): The RTMP URL address is NULL or has a string length of 0.
    - #ERR_NOT_INITIALIZED (7): You have not initialized the RTC engine when publishing the stream.
    - #ERR_ALREADY_IN_USE (19): This streaming URL is already in use. Use a new streaming URL for CDN streaming.

## ◆ updateRtmpTranscoding:

- (int) updateRtmpTranscoding: |  | (AgoraLiveTranscoding *_Nullable) | transcoding |

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

The SDK triggers the [rtcEngineTranscodingUpdated]([AgoraRtcEngineDelegate rtcEngineTranscodingUpdated:]) callback when you call the `setLiveTranscoding` method to update the transcoding setting.

Note**

- This method applies to live-broadcast 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.

Parameters

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

Returns
  = 0: Success. < 0: Failure.

## ◆ stopRtmpStream:

- (int) stopRtmpStream: |  | (NSString *_Nonnull) | url |

Removes an RTMP stream from the CDN.

This method removes the RTMP URL address added by the [addPublishStreamUrl](addPublishStreamUrl:transcodingEnabled:) method from a CDN live stream.

This method call triggers the [rtmpStreamingChangedToState]([AgoraRtcEngineDelegate rtcEngine:rtmpStreamingChangedToState:state:errorCode:]) callback on the local client to report the state of removing an RTMP stream from the CDN.

Note:**

This method applies to live-broadcast 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.

Parameters

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

Returns
  = 0: Success. < 0: Failure.

## ◆ setScreenCaptureScenario:

- (int) setScreenCaptureScenario: |  | (AgoraScreenScenarioType) | scenarioType |

Setting the screen sharing capture scenario.

Parameters

  scenarioType | The screen sharing scenario parameters, see [AgoraScreenScenarioType](AgoraScreenScenarioType).

Returns
  * 0: Success. < 0: Failure.

- `ERR_NOT_READY`: no screen or windows is being shared.

## ◆ stopScreenCapture

- (int) stopScreenCapture |  |  |

Stops a screen capture.

Note
  This method applies to macOS / iOS.

Returns
  * 0: Success. <0: Failure.

## ◆ startScreenCapture:

- (int) startScreenCapture: |  | (AgoraScreenCaptureParameters2 *_Nullable) | parameters |

Starts screen sharing.

Before calling this method, ensure that you have integrated AgoraRelayKitExtension.framework. When you call this method, AgoraRtcEngine will establish a socket connection to the ReplayKit extension. In the ReplayKit extension, inherit the AgoraReplayKitHandler, and then AgoraRtcEngine will get the screen share data.

A successful call of this method triggers the [AgoraRtcEngineDelegate]([AgoraRtcEngineDelegate rtcEngine:localVideoStateChangedOfState:state:error:sourceType]) callback:

- When sourceType == AgoraVideoSourceTypeScreen and state == AgoraVideoLocalStateCapturing, you can call [AgoraRtcEngine updateChannelWithMediaOptions:] to change the publishScreenCaptureVideo/publishScreenCaptureAudio = YES and then publish the screen share video stream.
- When sourceType == AgoraVideoSourceTypeScreen and state == AgoraVideoLocalStateStopped, you can call [AgoraRtcEngine updateChannelWithMediaOptions:] to change the publishScreenCaptureVideo/publishScreenCaptureAudio = NO and then stop publishing the screen share video stream.

Note
  This method applies to iOS 11+ only.

Parameters

  parameters | The configuration of the screen sharing.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ updateScreenCapture:

- (int) updateScreenCapture: |  | (AgoraScreenCaptureParameters2 *_Nullable) | parameters |

Updates the screen sharing configuration.

Parameters

  parameters | The configuration of the screen sharing.

Note
  This method applies to iOS 11+ only.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ queryScreenCaptureCapability

- (AgoraScreenCaptureFrameRateCapability) queryScreenCaptureCapability |  |  |

Queries the ability of screen sharing to support the maximum frame rate.

Since
  v4.2.0

Returns
  - 0: support 15 fps, Low devices.
  - 1: support 30 fps, Usually low - to mid-range devices.
  - 2: support 60 fps, Advanced devices.
  - < 0: Failure.

## ◆ queryCameraFocalLengthCapability

- (NSArray<AgoraFocalLengthInfo *>* _Nullable) queryCameraFocalLengthCapability |  |  |

## ◆ cameraMaxZoomFactor

- (CGFloat) cameraMaxZoomFactor |  |  |

get the max camera zoom ratio.

Note
  This method applies to iOS only, not to macOS.

Returns
  the max camera zoom ratio.

## ◆ switchCamera

- (int) switchCamera |  |  |

Switches between the front and rear cameras.

Note
  This method applies to iOS only, not to macOS.

Returns
  - 0: Success.
  - <0: Failure.

## ◆ enableMultiCamera:config:

- (int) enableMultiCamera: |  | (BOOL) | enabled
config: |  | (AgoraCameraCapturerConfiguration *_Nullable) | config

Enables the SDK use AVCaptureMultiCamSession or AVCaptureSession. Applies to iOS 13.0+ only.

Parameters

  enabled | Whether to enable multi-camera when capturing video: true: Enable multi-camera, and the SDK uses AVCaptureMultiCamSession. false: Disable multi-camera, and the SDK uses AVCaptureSession.
  config | The config for secondary camera capture session. See AgoraCameraCapturerConfiguration.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableCameraCenterStage:

- (int) enableCameraCenterStage: |  | (BOOL) | enabled |

Enables the Portrait Center Stage.

Parameters

  enabled | enable Center Stage: true: Enable Center Stage. false: Disable Center Stage.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ startCameraCapture:config:

- (int) startCameraCapture: |  | (AgoraVideoSourceType) | sourceType
config: |  | (AgoraCameraCapturerConfiguration *_Nullable) | config

Start the camera capture

Parameters

  sourceType | source type of camera. See AgoraVideoSourceType.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ stopCameraCapture:

- (int) stopCameraCapture: |  | (AgoraVideoSourceType) | sourceType |

Stop the camera capture

Parameters

  sourceType | source type of camera. See AgoraVideoSourceType.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableFaceDetection:

- (int) enableFaceDetection: |  | (BOOL) | enable |

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

Once face detection is enabled, the SDK triggers the [facePositionDidChangeWidth]([AgoraRtcEngineDelegate rtcEngine:facePositionDidChangeWidth:previewHeight:faces:]) callback to report the face information of the local user, which includes the following aspects:

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

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

Parameters

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

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

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ addVideoWatermark:options:

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

Adds a watermark image to the local video.

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

The watermark position depends on the settings in the [setVideoEncoderConfiguration]([AgoraRtcEngineKit 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]([AgoraRtcEngineKit setVideoEncoderConfiguration:]) method. Otherwise, the watermark image will be cropped.

  Note**

- Ensure that you have called the [enableVideo]([AgoraRtcEngineKit 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]([AgoraRtcEngineKit 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]([AgoraRtcEngineKit 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.

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.

Returns
  * 0: Success. < 0: Failure.

## ◆ registerLocalUserAccount:appId:

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

Registers a user account.

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

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

Call the [registerLocalUserAccount]([AgoraRtcEngineKit registerLocalUserAccount:appId:]) method to create a user account, and then the [joinChannelByUserAccount]([AgoraRtcEngineKit joinChannelByUserAccount:token:channelId:joinSuccess:]) method to join the channel. Call the [joinChannelByUserAccount]([AgoraRtcEngineKit joinChannelByUserAccount:token:channelId:joinSuccess:]) method to join the channel.

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

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

Parameters

  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.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ joinChannelByToken:channelId:userAccount:joinSuccess:

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

Joins the channel with a user account.

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

- The local client: onLocalUserRegistered and onJoinChannelSuccess . The remote client: onUserJoined and onUserInfoUpdated , if the user joining the channel is in the `COMMUNICATION` profile, or is a host in the `LIVE_BROADCASTING` profile.

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

Parameters

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

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

## ◆ joinChannelByToken:channelId:userAccount:mediaOptions:joinSuccess:

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

Joins the channel with a user account.

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

- The local client: onLocalUserRegistered and onJoinChannelSuccess . The remote client: onUserJoined and onUserInfoUpdated , if the user joining the channel is in the `COMMUNICATION` profile, or is a host in the `LIVE_BROADCASTING` profile.

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

Parameters

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

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

## ◆ getUserInfoByUserAccount:withError:

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

Gets the user information by passing in the user account.

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

After receiving the [didUpdatedUserInfo]([AgoraRtcEngineDelegate rtcEngine:didUpdatedUserInfo:withUid:]) callback, you can call this method to get the user ID of the remote user from the `userInfo` object by passing in the user account.

Parameters

  userAccount | The user account of the user. Ensure that you set this parameter.
  error | The pointer to [AgoraErrorCode](AgoraErrorCode). It can be set as nil.

Returns
  An [AgoraUserInfo](AgoraUserInfo) object that contains the user account and user ID of the user.

## ◆ getUserInfoByUid:withError:

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

Gets the user information by passing in the user ID.

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]([AgoraRtcEngineDelegate rtcEngine:didUpdatedUserInfo:withUid:]) callback on the local client.

After receiving the [didUpdatedUserInfo]([AgoraRtcEngineDelegate rtcEngine:didUpdatedUserInfo:withUid:]) callback, you can call this method to get the user account of the user from the `userInfo` object by passing in the user ID.

Parameters

  uid | The user ID of the user. Ensure that you set this parameter.
  error | The pointer to [AgoraErrorCode](AgoraErrorCode). It can be set as nil.

Returns
  An [AgoraUserInfo](AgoraUserInfo) object that contains the user account and user ID of the user.

## ◆ setAudioFrameDelegate:

- (BOOL) setAudioFrameDelegate: |  | (id< AgoraAudioFrameDelegate > _Nullable) | delegate |

register & unregister the player audio observer

Parameters

  delegate | observer object, pass nil to unregister

Returns
  int <= 0 On behalf of an error, the value corresponds to one of PLAYER_ERROR

## ◆ setVideoFrameDelegate:

- (BOOL) setVideoFrameDelegate: |  | (id< AgoraVideoFrameDelegate > _Nullable) | delegate |

Registers & unregister video frame observer object.

Note
  - Ensure that you call this method before joining the channel.

Parameters

  delegate | An object to the video frame observer: id<AgoraVideoFrameDelegate>.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setEncodedVideoFrameDelegate:

- (BOOL) setEncodedVideoFrameDelegate: |  | (id< AgoraEncodedVideoFrameDelegate > _Nullable) | delegate |

Obtain H264 video data before decoding.

Note
  - Ensure that you call this method before joining the channel.

Parameters

  delegate | An object to the video frame observer: id<AgoraEncodedVideoFrameDelegate>.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setFaceInfoDelegate:

- (BOOL) setFaceInfoDelegate: |  | (id< AgoraFaceInfoDelegate > _Nullable) | delegate |

register & unregister the face info observer

Parameters

  delegate | observer object, pass nil to unregister

Returns
  int <= 0 On behalf of an error

## ◆ setMediaMetadataDataSource:withType:

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

Sets the data source of the metadata.

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

Use this method with the AgoraRtcEngineKit.setMediaMetadataDelegate:withType: 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.

Parameters

  metadataDataSource | The AgoraMediaMetadataDataSource protocol.
  type | The metadata type. See AgoraMetadataType. Currently, the SDK supports video metadata only.

Returns
  - YES: Success.
  - NO: Failure.

## ◆ setMediaMetadataDelegate:withType:

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

Sets the delegate of the metadata.

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.

Parameters

  metadataDelegate | The AgoraMediaMetadataDelegate protocol.
  type | The metadata type. See AgoraMetadataType. Currently, the SDK supports video metadata only.

Returns
  - YES: Success.
  - NO: Failure.

## ◆ getSdkVersion

+ (NSString * _Nonnull) getSdkVersion |  |  |

Gets the Agora SDK version.

Returns
  The version of the current SDK in the string format.

## ◆ getErrorDescription:

+ (NSString* _Nonnull) getErrorDescription: |  | (NSInteger) | error |

Gets the warning or error description.

Parameters

  error | The warning or error code.

Returns
  The detailed warning or error description.

## ◆ setLogFile:

- (int) setLogFile: |  | (NSString *_Nonnull) | filePath |

Specifies an SDK output log file.

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

Note
  - The default log file location 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:delegate: sharedEngineWithAppId method, otherwise the output log might not be complete.

Parameters

  filePath | Absolute path of the log file. The string of the log file is in UTF-8 code.

Returns
  - 0: Success.
  - <0: Failure.

## ◆ setLogFilter:

- (int) setLogFilter: |  | (NSUInteger) | filter |

Sets the output log filter level of the SDK.

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 filter level to `Warning`, you see the logs within levels `Critical`, `Error`, and `Warning`.

See also
  - setLogFile:
  setLogFile

Parameters

  filter | Log filter level: AgoraLogFilter.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setLogFileSize:

- (int) setLogFileSize: |  | (NSUInteger) | fileSizeInKBytes |

Sets the log file size (KB).

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

Parameters

  fileSizeInKBytes | The SDK log file size (KB).

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ uploadLogFile

- (NSString * _Nullable) uploadLogFile |  |  |

Upload current log file immediately to server. only use this when an error occurs block before log file upload success or timeout.

Returns
  requestID the id of this upload.

## ◆ writeLog:content:

- (int) writeLog: |  | (AgoraLogLevel) | level
content: |  | (NSString *_Nonnull) | content

- Write the log to SDK . @technical preview

You can Write the log to SDK log files of the specified level

Parameters

  level | Log level: AgoraLogLevel.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ getCallId

- (NSString * _Nullable) getCallId |  |  |

Gets the current call ID.

When a user joins a channel, a call ID is generated to identify the call.

After a call ends, you can call `rate` or `complain` to gather feedback from your customer.

Returns
  The call ID if the method call is successful.

## ◆ rate:rating:description:

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

Allows a user to rate the call.

It is usually called after the call ends.

Parameters

  callId | The call ID retrieved from the getCallId method.
  rating | The rating of the call between 1 (the lowest score) to 5 (the highest score). If you set a value out of this range, the AgoraErrorCodeInvalidArgument(-2) error occurs.
  description | (Optional) The description of the rating. The string length must be less than 800 bytes.

Returns
  - 0: Success.
  - < 0: Failure.
    - -2: AgoraErrorCodeInvalidArgument. The passed argument is invalid. For example, `callId` is invalid.
    - -3: AgoraErrorCodeNotReady. The SDK status is incorrect. For example, initialization fails.

## ◆ complain:description:

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

Allows a user to complain about the call quality.

This method is usually called after the call ends.

Parameters

  callId | The call ID retrieved from the getCallId method.
  description | (Optional) The description of the complaint. The string length must be less than 800 bytes.

Returns
  - 0: Success.
  - < 0: Failure.
    - -2: AgoraErrorCodeInvalidArgument. The passed argument is invalid. For example, `callId` is invalid.
    - -3: AgoraErrorCodeNotReady. The SDK status is incorrect. For example, initialization fails.

## ◆ startLastmileProbeTest:

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

Starts the last-mile network probe test.

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 triggers the AgoraRtcEngineDelegate.rtcEngine:lastmileProbeTestResult: lastmileProbeTestResult callback within 30 seconds depending on the network conditions. This callback reports the real-time statistics of the network conditions.

Note
  - Do not call other methods before receiving the `lastmileProbeTestResult` callback. Otherwise, the callback may be interrupted.
  - This method consumes extra network traffic and may affect communication quality.

Parameters

  config | The configurations for the last-mile network probe test. See AgoraLastmileProbeConfig.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ stopLastmileProbeTest

- (int) stopLastmileProbeTest |  |  |

Stops the last-mile network probe test.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ getNtpWallTimeInMs

- (uint64_t) getNtpWallTimeInMs |  |  |

Return current NTP(unix timestamp) time in milliseconds.

## ◆ createMediaPlayerWithDelegate:

- (id<AgoraRtcMediaPlayerProtocol>_Nullable) createMediaPlayerWithDelegate: |  | (id< AgoraRtcMediaPlayerDelegate >_Nullable) | delegate |

create MediaPlayer

Parameters

  delegate | An object to the mediaPlayer observer: id<AgoraRtcMediaPlayerDelegate>.

Returns
  id<AgoraMediaPlayerProtocol>

## ◆ createMediaPlayerCacheManager

- (id<AgoraRtcMediaPlayerCacheManagerProtocol> _Nullable) createMediaPlayerCacheManager |  |  |

create MediaPlayer cache manager

Returns
  id<AgoraRtcMediaPlayerCacheManagerProtocol>

## ◆ destroyMediaPlayer:

- (int) destroyMediaPlayer: |  | (id< AgoraRtcMediaPlayerProtocol >_Nullable) | mediaPlayer |

Destroy a media player source instance. If a media player source instance is destroyed, the video and audio of it cannot be published.

Parameters

  mediaPlayer | id<AgoraMediaPlayerProtocol>

Returns
  - >0: The id of media player source instance.
  - < 0: Failure.

## ◆ getMediaPlayer:

- (id<AgoraRtcMediaPlayerProtocol> _Nullable) getMediaPlayer: |  | (int) | mediaPlayerId |

getMediaPlayer

Parameters

  mediaPlayerId | of the mediaPlayer.

Returns
  id<AgoraMediaPlayerProtocol>

## ◆ startRhythmPlayer:sound2:config:

- (int) startRhythmPlayer: |  | (NSString *_Nonnull) | sound1
sound2: |  | (NSString *_Nonnull) | sound2
config: |  | (AgoraRhythmPlayerConfig *_Nullable) | config

Enables the rhythm player.

Parameters

  sound1 | The absolute path or URL address (including the filename extensions) of the file for the downbeat.
  sound2 | The absolute path or URL address (including the filename extensions) of the file for the upbeats.
  config | The configuration of rhythm player.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ stopRhythmPlayer

- (int) stopRhythmPlayer |  |  |

Disables the rhythm player.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ configRhythmPlayer:

- (int) configRhythmPlayer: |  | (AgoraRhythmPlayerConfig *_Nullable) | config |

Configures the rhythm player.

Parameters

  config | The configuration of rhythm player.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setDirectCdnStreamingAudioConfiguration:

- (int) setDirectCdnStreamingAudioConfiguration: |  | (AgoraAudioProfile) | profile |

Set audio parameters for direct streaming to CDN

Note
  Must call this api before "startDirectCdnStreaming"

Parameters

  profile | Sets the sample rate, bitrate, encoding mode, and the number of channels: #AUDIO_PROFILE_TYPE.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setDirectCdnStreamingVideoConfiguration:

- (int) setDirectCdnStreamingVideoConfiguration: |  | (AgoraVideoEncoderConfiguration *_Nonnull) | config |

Set video parameters for direct streaming to CDN

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

Note
  Must call this api before "startDirectCdnStreaming"

Parameters

  config | The local video encoder configuration: VideoEncoderConfiguration.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ startDirectCdnStreaming:publishUrl:mediaOptions:

- (int) startDirectCdnStreaming: |  | (id< AgoraDirectCdnStreamingEventDelegate > _Nonnull) | delegate
publishUrl: |  | (NSString *_Nonnull) | publishUrl
mediaOptions: |  | (AgoraDirectCdnStreamingMediaOptions *_Nonnull) | options

Start direct cdn streaming

Parameters

  delegate | A pointer to the direct cdn streaming event handler: IDirectCdnStreamingEventHandler.
  publishUrl | The url of the cdn used to publish the stream.
  options | The direct cdn streaming media options: AgoraDirectCdnStreamingMediaOptions. This API must pass an audio-related option, and temporarily cannot pass more than one. Video-related options may not be passed, or one, but not multiple.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ stopDirectCdnStreaming

- (int) stopDirectCdnStreaming |  |  |

Stop direct cdn streaming

Note
  This method is temporarily not supported.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ updateDirectCdnStreamingMediaOptions:

- (int) updateDirectCdnStreamingMediaOptions: |  | (AgoraDirectCdnStreamingMediaOptions *_Nonnull) | options |

Change the media source during the pushing

Note
  This method is synchronous.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setAdvancedAudioOptions:

- (int) setAdvancedAudioOptions: |  | (AgoraAdvancedAudioOptions *_Nonnull) | options |

set advanced audio options. use this method before join channel / enableAudio / enableLocalAudio.

Parameters

  options | The AgoraAdvancedAudioOptions class, See the definition of AgoraAdvancedAudioOptions for details.

Returns
  - 0: Success
  - < 0: Failure

## ◆ sendCustomReportMessage:category:event:label:value:

- (int) sendCustomReportMessage: |  | (NSString *_Nullable) | messageId
category: |  | (NSString *_Nullable) | category
event: |  | (NSString *_Nullable) | event
label: |  | (NSString *_Nullable) | label
value: |  | (NSInteger) | value

Agora supports reporting and analyzing customized messages.

This function is in the beta stage with a free trial. The ability provided in its beta test version is reporting a maximum of 10 message pieces within 6 seconds, with each message piece not exceeding 256 bytes.

To try out this function, contact support@agora.io and discuss the format of customized messages with us.

## ◆ setLogLevel:

- (int) setLogLevel: |  | (AgoraLogLevel) | level |

Sets the output log level of the SDK.

You can set the SDK to ouput the log files of the specified level.

Parameters

  level | The log level: `AgoraLogFilterOff (0)`: Do not output any log file. `AgoraLogFilterInfo (0x000f)`: (Recommended) Output log files of the Info level. `AgoraLogFilterWarning (0x000e)`: Output log files of the Warning level. `AgoraLogFilterError (0x000c)`: Output log files of the Error level. `AgoraLogFilterCritical (0x0008)`: Output log files of the Critical level.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setLocalAccessPoint:

- (int) setLocalAccessPoint: |  | (AgoraLocalAccessPointConfiguration *_Nonnull) | config |

Set local access point configuration for local proxy service. Use this method before join channel.

Parameters

  config | The configuration for local access point.

Returns
  * 0: Success. < 0: Failure.

## ◆ setCloudProxy:

- (int) setCloudProxy: |  | (AgoraCloudProxyType) | proxyType |

Sets the Agora cloud proxy service.

Since
  v3.3.0

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

After a successfully cloud proxy connection, the SDK triggers the [connectionChangedToState(AgoraConnectionStateConnecting, AgoraConnectionChangedSettingProxyServer)]([AgoraRtcEngineDelegate rtcEngine:connectionChangedToState:reason:]) callback.

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

Note**

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

Parameters

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

Returns
  - 0: Success.
  - < 0: Failure.
    - `-2(AgoraErrorCodeInvalidArgument)`: The parameter is invalid.
    - `-7(AgoraErrorCodeNotInitialized)`: The SDK is not initialized.

## ◆ takeSnapshot:filePath:

- (NSInteger) takeSnapshot: |  | (NSInteger) | uid
filePath: |  | (NSString *_Nonnull) | filePath

Takes a snapshot of a video stream.

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

The method is asynchronous, and the SDK has not taken the snapshot when the method call returns. After a successful method call, the SDK triggers the `snapshotTaken` callback to report whether the snapshot is successfully taken, as well as the details for that snapshot.

Note
  - Call this method after joining a channel.
  - This method takes a snapshot of the published video stream specified in `ChannelMediaOptions`.
  - If the user's video has been preprocessed, for example, watermarked or beautified, the resulting snapshot includes the pre-processing effect.

Parameters

  uid | The user ID. Set uid as 0 if you want to take a snapshot of the local user's video.
  filePath | The local path (including filename extensions) of the snapshot. For example: Windows: `C:\Users\<user_name>\AppData\Local\Agora\<process_name>\example.jpg` iOS: `/App Sandbox/Library/Caches/example.jpg` macOS: `～/Library/Logs/example.jpg` Android: `/storage/emulated/0/Android/data/<package name>/files/example.jpg`

Ensure that the path you specify exists and is writable.

Returns
  - 0 : Success.
  - < 0 : Failure.

## ◆ takeSnapshotWithConfig:config:

- (NSInteger) takeSnapshotWithConfig: |  | (NSInteger) | uid
config: |  | (AgoraSnapshotConfig *_Nonnull) | config

Takes a snapshot of a video stream.

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

The method is asynchronous, and the SDK has not taken the snapshot when the method call returns. After a successful method call, the SDK triggers the `snapshotTaken` callback to report whether the snapshot is successfully taken, as well as the details for that snapshot.

Note
  - Call this method after joining a channel.
  - This method takes a snapshot of the published video stream specified in `ChannelMediaOptions`.

Parameters

  uid | The user ID. Set uid as 0 if you want to take a snapshot of the local user's video.
  config | The configuration for the take snapshot. See SnapshotConfig.

Ensure that the path you specify exists and is writable.

Returns
  - 0 : Success.
  - < 0: Failure.
    - -4: Incorrect observation position. Modify the input observation position according to the reqiurements specified in SnapshotConfig.

## ◆ enableContentInspect:config:

- (int) enableContentInspect: |  | (BOOL) | enabled
config: |  | (AgoraContentInspectConfig *_Nonnull) | config

## ◆ setAVSyncSource:uid:

- (int) setAVSyncSource: |  | (NSString *_Nonnull) | channelId
uid: |  | (NSUInteger) | uid

Bind local user and a remote user as an audio&video sync group. The remote user is defined by cid and uid. There’s a usage limit that local user must be a video stream sender. On the receiver side, media streams from same sync group will be time-synced

Parameters

  channelId | The channel id
  uid | The user ID of the remote user to be bound with (local user)

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ sendAudioMetadata:

- (int) sendAudioMetadata: |  | (NSData *_Nonnull) | metadata |

send audio metadata

Since
  v4.3.1

Parameters

  metadata | The NSData of metadata

Returns
  - 0: success
  - <0: failure @technical preview

## ◆ enableVideoImageSource:options:

- (int) enableVideoImageSource: |  | (BOOL) | enable
options: |  | (AgoraImageTrackOptions *_Nullable) | options

Enable or disable video image source to replace the current video source published or resume it

Parameters

  enable | true for enable, false for disable
  options | options for image track

## ◆ getNetworkType

- (int) getNetworkType |  |  |

get network Type

Returns
  - 0: DISCONNECTED.
  - 1: LAN.
  - 2: WIFI.
  - 3: MOBILE_2G
  - 4: MOBILE_3G
  - 5: MOBILE_4G
  - 6: MOBILE_5G
  - -1: UNKNOWN

## ◆ createMediaRecorder:

- (AgoraMediaRecorder * _Nullable) createMediaRecorder: |  | (AgoraRecorderStreamInfo *_Nonnull) | info |

Creates a media recorder object and return its pointer.

Parameters

  info | The AgoraRecorderStreamInfo object. It contains the user ID and the channel name.

Returns
  - The pointer to "AgoraMediaRecorder", if the method call succeeds.
  - The empty pointer NULL, if the method call fails.

## ◆ destroyMediaRecorder:

- (int) destroyMediaRecorder: |  | (AgoraMediaRecorder *_Nullable) | mediaRecorder |

Destroy a media recorder source instance.

Parameters

  mediaRecorder | AgoraMediaRecorder pointer

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ getH265Transcoder

- (id<AgoraH265TranscoderProtocol>_Nullable) getH265Transcoder |  |  |

Get the H265Transcoder instance

Returns
  id<AgoraH265TranscoderProtocol>

## ◆ enableWebSdkInteroperability:

- (int) enableWebSdkInteroperability: |  | (BOOL) | enabled |

Deprecated:
  Web SDK interoperability is by default enabled.

Parameters

  enabled | Whether interoperability with the Agora Web SDK is enabled: YES: Enabled. NO: Disabled.

Returns
  - 0: Success.
  - <0: Failure.

## ◆ setAudioProfile:scenario:

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

Sets the audio parameters and application scenarios.

Deprecated:
  This method is deprecated. You can use the setAudioProfile: setAudioProfile method instead.

Note
  - Call this method before calling `joinChannelByToken`.
  - In scenarios requiring high-quality audio, we recommend setting `profile` as `AgoraAudioProfileMusicHighQuality`(4) and `scenario` as `AgoraAudioScenarioGameStreaming`(3).

Parameters

  profile | Sets the sample rate, bitrate, encoding mode, and the number of channels. See AgoraAudioProfile.
  scenario | Sets the audio application scenarios. See AgoraAudioScenario.

Returns
  - 0: Success.
  - <0: Failure.

## ◆ setExternalAudioSource:sampleRate:channels:

- (int) setExternalAudioSource: |  | (BOOL) | enabled
sampleRate: |  | (NSInteger) | sampleRate
channels: |  | (NSInteger) | channels

Sets the external audio source.

Note
  Ensure that you call this method before joining the channel.

Deprecated:
  This method is deprecated. Use createCustomAudioTrack:(AgoraAudioTrackType)trackType config:(AgoraAudioTrackConfig* _Nonnull)config instead.

Parameters

  enabled | Determines whether to enable the external audio source: true: Enable the external audio source. false: (default) Disable the external audio source.
  sampleRate | The Sample rate (Hz) of the external audio source, which can set be as 8000, 16000, 32000, 44100, or 48000.
  channels | The number of channels of the external audio source, which can be set as 1 or 2: 1: Mono. 2: Stereo.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setExternalAudioSource:sampleRate:channels:localPlayback:publish:

- (int) setExternalAudioSource: |  | (BOOL) | enabled
sampleRate: |  | (NSInteger) | sampleRate
channels: |  | (NSInteger) | channels
localPlayback: |  | (BOOL) | localPlayback
publish: |  | (BOOL) | publish

Sets the external audio source.

Note
  Ensure that you call this method before joining the channel.

Deprecated:
  This method is deprecated. Use createCustomAudioTrack:(AgoraAudioTrackType)trackType config:(AgoraAudioTrackConfig* _Nonnull)config instead.

Parameters

  enabled | Determines whether to enable the external audio source: true: Enable the external audio source. false: (default) Disable the external audio source.
  sampleRate | The Sample rate (Hz) of the external audio source, which can set be as 8000, 16000, 32000, 44100, or 48000.
  channels | The number of channels of the external audio source, which can be set as 1 or 2: 1: Mono. 2: Stereo.
  localPlayback | Enable/Disables the local playback of external audio track: true: Enable local playback false: (Default) Do not enable local playback
  publish | Determines whether to publish the external audio track: true: (Default) Publish the external audio track. false: Don`t publish the external audio track.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setLocalRenderMode:mode:

- (int) setLocalRenderMode: |  | (NSUInteger) | uid
mode: |  | (AgoraVideoRenderMode) | mode

Deprecated:

## ◆ enableExternalAudioSourceLocalPlayback:

- (int) enableExternalAudioSourceLocalPlayback: |  | (BOOL) | enable |

Enable or disable the external audio source local playback.

- Parameters

    enable | Determines whether to enable the external audio source local playback:

- true: Enable the external audio source local playback.
- false: (default) Disable the external audio source local playback.
  Returns
    int
- 0: Success.
- <0: Failure.

## ◆ addDelegate:

- (void) addDelegate: |  | (id< AgoraRtcEngineDelegate > _Nonnull) | delegate |

Adds multiple SDK delegate.

Parameters

  delegate | The AgoraRtcEngineDelegate object.

## ◆ removeDelegate:

- (void) removeDelegate: |  | (id< AgoraRtcEngineDelegate > _Nonnull) | delegate |

Removes multiple SDK delegate.

Parameters

  delegate | The AgoraRtcEngineDelegate object.

## ◆ joinChannelExByToken:connection:delegate:mediaOptions:joinSuccess:

- (int) joinChannelExByToken: |  | (NSString *_Nullable) | token
connection: |  | (AgoraRtcConnection *_Nonnull) | connection
delegate: |  | (id< AgoraRtcEngineDelegate > _Nullable) | delegate
mediaOptions: |  | (AgoraRtcChannelMediaOptions *_Nonnull) | mediaOptions
joinSuccess: |  | (void(^)(NSString *_Nonnull channel, NSUInteger uid, NSInteger elapsed)) | joinSuccessBlock

Joins a channel.

You can call this method multiple times to join multiple channels.

Parameters

  token | The token for authentication. In situations not requiring high security: You can use the temporary token generated at Console. For details, see Get a temporary token. In situations requiring high security: Set it as the token generated at you server. For details, see Generate a token.
  connection | AgoraRtcConnection by channelId and uid combine
  delegate | AgoraRtcEngineDelegate protocol.(Need a new object when called)
  mediaOptions | AgoraRtcChannelMediaOptions Object.
  joinSuccessBlock | Same as AgoraRtcEngineDelegate.rtcEngine:didJoinChannel:withUid:elapsed: didJoinChannel. We recommend you set this parameter as `nil` to use `didJoinChannel`. If `joinSuccessBlock` is nil, the SDK triggers the `didJoinChannel` callback. If you implement both `joinSuccessBlock` and `didJoinChannel`, `joinSuccessBlock` takes higher priority than `didJoinChannel`.

Returns
  - 0: Success.
  - < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ joinChannelExByToken:channelId:userAccount:delegate:mediaOptions:joinSuccess:

- (int) joinChannelExByToken: |  | (NSString *_Nullable) | token
channelId: |  | (NSString *_Nonnull) | channelId
userAccount: |  | (NSString *_Nonnull) | userAccount
delegate: |  | (id< AgoraRtcEngineDelegate > _Nullable) | delegate
mediaOptions: |  | (AgoraRtcChannelMediaOptions *_Nonnull) | mediaOptions
joinSuccess: |  | (void(^)(NSString *_Nonnull channel, NSUInteger uid, NSInteger elapsed)) | joinSuccessBlock

Joins the channel with a user account.

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

- The local client: onLocalUserRegistered and onJoinChannelSuccess . The remote client: onUserJoined and onUserInfoUpdated , if the user joining the channel is in the `COMMUNICATION` profile, or is a host in the `LIVE_BROADCASTING` profile.

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

Parameters

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

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

Provided by category AgoraRtcEngineKit(Ex).

## ◆ updateChannelExWithMediaOptions:connection:

- (int) updateChannelExWithMediaOptions: |  | (AgoraRtcChannelMediaOptions *_Nonnull) | mediaOptions
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Updates the channel media options after joining the channel.

Parameters

  mediaOptions | The channel media options: ChannelMediaOptions.
  connection | AgoraRtcConnection by channelId and uid combine

Returns
  - 0: Success.
  - < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ setDelegateEx:connection:

- (int) setDelegateEx: |  | (id< AgoraRtcEngineDelegate > _Nullable) | delegate
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Resets the SDK delegate.

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

Parameters

  delegate | The AgoraRtcEngineDelegate protocol.
  connection | The AgoraRtcConnection object.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ muteLocalAudioStreamEx:connection:

- (int) muteLocalAudioStreamEx: |  | (BOOL) | mute
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Stops or resumes sending the local audio stream with connection.

Parameters

  mute | Determines whether to send or stop sending the local audio stream: `YES`: Stop sending the local audio stream. `NO`: Send the local audio stream.
  connection | AgoraRtcConnection by channelId and uid combine

Returns
  - 0: Success.
  - < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ muteLocalVideoStreamEx:connection:

- (int) muteLocalVideoStreamEx: |  | (BOOL) | mute
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Stops or resumes sending the local video stream with connection.

Parameters

  mute | Determines whether to send or stop sending the local video stream: `YES`: Stop sending the local video stream. `NO`: Send the local video stream.
  connection | AgoraRtcConnection by channelId and uid combine

Returns
  - 0: Success.
  - < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ muteRemoteAudioStreamEx:mute:connection:

- (int) muteRemoteAudioStreamEx: |  | (NSUInteger) | uid
mute: |  | (BOOL) | mute
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Mutes a specified remote user's audio stream.

Note
  When setting to YES, this method stops playing audio streams without affecting the audio stream receiving process.

Parameters

  uid | User ID whose audio streams the user intends to mute.
  mute | * YES: Stops playing a specified user’s audio streams. NO: Resumes playing a specified user’s audio streams.
  connection | AgoraRtcConnection by channelId and uid combine

Returns
  * 0: Success. <0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ muteAllRemoteAudioStreamsEx:connection:

- (int) muteAllRemoteAudioStreamsEx: |  | (BOOL) | mute
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Stops or resumes receiving all remote audio stream with connection.

Parameters

  mute | Whether to stop receiving remote audio streams: `YES`: Stop receiving any remote audio stream. `NO`: Resume receiving all remote audio streams.
  connection | AgoraRtcConnection by channelId and uid combine

Returns
  - 0: Success.
  - < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ setVideoEncoderConfigurationEx:connection:

- (int) setVideoEncoderConfigurationEx: |  | (AgoraVideoEncoderConfiguration *_Nonnull) | config
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Sets the video encoder configuration.

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

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

Parameters

  config | The local video encoder configuration, see #AgoraVideoEncoderConfiguration.
  connection | AgoraRtcConnection by channelId and uid combine

Returns
  - 0: Success.
  - < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ setupRemoteVideoEx:connection:

- (int) setupRemoteVideoEx: |  | (AgoraRtcVideoCanvas *_Nonnull) | remote
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Binds the remote user to the video display window, that is, sets the view for the user of the specified uid.

Usually, the application should specify the uid of the remote video in the method call before the user enters a channel. If the remote uid is unknown to the application, you can set the uid after receiving the AgoraRtcEngineDelegate.rtcEngine:didJoinedOfUid:elapsed: didJoinedOfUid event.

Parameters

  remote | AgoraRtcVideoCanvas
  connection | AgoraRtcConnection by channelId and uid combine

Returns
  - 0: Success.
  - <0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ setRemoteRenderModeEx:mode:mirror:connection:

- (int) setRemoteRenderModeEx: |  | (NSUInteger) | uid
mode: |  | (AgoraVideoRenderMode) | mode
mirror: |  | (AgoraVideoMirrorMode) | mirror
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Configures the remote video display mode. The application can call this method multiple times to change the display mode.

Parameters

  uid | User id of the user whose video streams are received.
  mode | AgoraVideoRenderMode
  mirror | AgoraVideoMirrorMode
  connection | AgoraRtcConnection by channelId and uid combine

Returns
  - 0: Success.
  - <0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ muteRemoteVideoStreamEx:mute:connection:

- (int) muteRemoteVideoStreamEx: |  | (NSUInteger) | uid
mute: |  | (BOOL) | mute
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Stops or resumes receiving the video stream of a specified user.

Note
  Once you leave the channel, the settings in this method becomes invalid.

Parameters

  uid | ID of the specified remote user.
  mute | Determines whether to receive or stop receiving a specified video stream: `YES`: Stop receiving the specified video stream. `NO`: (Default) Receive the specified video stream.
  connection | AgoraRtcConnection by channelId and uid combine

Returns
  - 0: Success.
  - < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ muteAllRemoteVideoStreamsEx:connection:

- (int) muteAllRemoteVideoStreamsEx: |  | (BOOL) | mute
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Stops or resumes receiving all remote video stream with connection.

Parameters

  mute | Whether to stop receiving remote video streams: `YES`: Stop receiving any remote video stream. `NO`: Resume receiving all remote video streams.
  connection | AgoraRtcConnection by channelId and uid combine

Returns
  - 0: Success.
  - < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ enableDualStreamModeEx:streamConfig:connection:

- (int) enableDualStreamModeEx: |  | (BOOL) | enabled
streamConfig: |  | (AgoraSimulcastStreamConfig *) | streamConfig
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Enables or disables the dual video stream mode.

Deprecated:
  v4.2.0. This method is deprecated. Use setDualStreamModeEx instead.

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

Parameters

  enabled | true: Enable the dual-stream mode. false: (default) Disable the dual-stream mode.
  streamConfig | The minor stream config
  connection | An output parameter which is used to control different connection instances.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ setDualStreamModeEx:streamConfig:connection:

- (int) setDualStreamModeEx: |  | (AgoraSimulcastStreamMode) | mode
streamConfig: |  | (AgoraSimulcastStreamConfig *) | streamConfig
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Enables or disables the dual video stream mode.

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

Parameters

  mode | The dual-stream mode.
  streamConfig | The minor stream config
  connection | An output parameter which is used to control different connection instances.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ setSimulcastConfigEx:connection:

- (int) setSimulcastConfigEx: |  | (AgoraSimulcastConfig *) | simulcastConfig
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Set the multi-layer video stream configuration.

If multi-layer is configed, the subscriber can choose to receive the coresponding layer of video stream using setRemoteVideoStreamType.

Parameters

  simulcastConfig | The configuration for multi-layer video stream. It includes seven layers, ranging from STREAM_LAYER_1 to STREAM_LOW. A maximum of 3 layers can be enabled simultaneously.
  connection | The RtcConnection object.

Returns
  - 0: Success.
  - < 0: Failure. @technical preview

Provided by category AgoraRtcEngineKit(Ex).

## ◆ setRemoteVideoStreamEx:type:connection:

- (int) setRemoteVideoStreamEx: |  | (NSUInteger) | uid
type: |  | (AgoraVideoStreamType) | streamType
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Sets the remote video stream type.

If the remote user has enabled the dual-stream mode, by default the SDK receives the high-stream video. Call this method to switch to the low-stream video.

Note
  This method applies to scenarios where the remote user has enabled the dual-stream mode by enableDualStreamMode: enableDualStreamMode before joining the channel.

Parameters

  uid | ID of the remote user sending the video stream.
  streamType | The video stream type: AgoraVideoStreamType.
  connection | AgoraRtcConnection by channelId and uid combine

Returns
  - 0: Success.
  - < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ setRemoteVideoSubscriptionOptionsEx:options:connection:

- (int) setRemoteVideoSubscriptionOptionsEx: |  | (NSUInteger) | uid
options: |  | (AgoraVideoSubscriptionOptions *_Nonnull) | options
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Sets the remote video subscription options

Parameters

  uid | ID of the remote user sending the video stream.
  options | Sets the video subscription options.
  connection | AgoraRtcConnection by channelId and uid combine

Returns
  - 0: Success.
  - < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ getUserInfoByUserAccountEx:connection:withError:

- (AgoraUserInfo* _Nullable) getUserInfoByUserAccountEx: |  | (NSString *_Nonnull) | userAccount
connection: |  | (AgoraRtcConnection *_Nonnull) | connection
withError: |  | (AgoraErrorCode *_Nullable) | error

Gets the user information by passing in the user account.

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

After receiving the [didUpdatedUserInfo]([AgoraRtcEngineDelegate rtcEngine:didUpdatedUserInfo:withUid:]) callback, you can call this method to get the user ID of the remote user from the `userInfo` object by passing in the user account.

Parameters

  userAccount | The user account of the user. Ensure that you set this parameter.
  connection | AgoraRtcConnection by channelId and uid combine

Returns
  An [AgoraUserInfo](AgoraUserInfo) object that contains the user account and user ID of the user.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ getUserInfoByUidEx:connection:withError:

- (AgoraUserInfo* _Nullable) getUserInfoByUidEx: |  | (NSUInteger) | uid
connection: |  | (AgoraRtcConnection *_Nonnull) | connection
withError: |  | (AgoraErrorCode *_Nullable) | error

Gets the user information by passing in the user ID.

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

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

Parameters

  uid | The user ID of the remote user. Ensure that you set this parameter.
  connection | AgoraRtcConnection by channelId and uid combine

Returns
  An [AgoraUserInfo](AgoraUserInfo) object that contains the user account and user ID of the user.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ getConnectionStateEx:

- (AgoraConnectionState) getConnectionStateEx: |  | (AgoraRtcConnection *_Nonnull) | connection |

Gets the connection state of the SDK.

Parameters

  connection | AgoraRtcConnection by channelId and uid combine

Returns
  The connection state. See AgoraConnectionState.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ adjustRecordingSignalVolumeEx:connection:

- (int) adjustRecordingSignalVolumeEx: |  | (NSInteger) | volume
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Adjusts the recording volume.

Parameters

  volume | The recording volume, which ranges from 0 to 400: 0 : Mute the recording volume. 100: The original volume. 400: (Maximum) Four times the original volume with signal clipping protection.
  connection | AgoraRtcConnection by channelId and uid combine

Returns
  - 0 : Success.
  - < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ muteRecordingSignalEx:connection:

- (int) muteRecordingSignalEx: |  | (BOOL) | mute
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Mutes or resume recording signal volume.

Parameters

  mute | Determines whether to mute or resume the recording signal volume. YES: Mute the recording signal volume. NO: (Default) Resume the recording signal volume.
  connection | AgoraRtcConnection by channelId and uid combine

Returns
  - 0 : Success.
  - < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ adjustUserPlaybackSignalVolumeEx:volume:connection:

- (int) adjustUserPlaybackSignalVolumeEx: |  | (NSUInteger) | uid
volume: |  | (NSInteger) | volume
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Adjust the playback signal volume of a specified remote user.

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

Note**

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

Parameters

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

- 0: Mute.
- 100: (Default) Original volume.
  Parameters

    connection | AgoraRtcConnection by channelId and uid combine

  Returns
- 0: Success.
- < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ sendCustomReportMessageEx:category:event:label:value:connection:

- (int) sendCustomReportMessageEx: |  | (NSString *_Nullable) | messageId
category: |  | (NSString *_Nullable) | category
event: |  | (NSString *_Nullable) | event
label: |  | (NSString *_Nullable) | label
value: |  | (NSInteger) | value
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Provided by category AgoraRtcEngineKit(Ex).

## ◆ enableAudioVolumeIndicationEx:smooth:reportVad:connection:

- (int) enableAudioVolumeIndicationEx: |  | (NSInteger) | interval
smooth: |  | (NSInteger) | smooth
reportVad: |  | (BOOL) | reportVad
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Provided by category AgoraRtcEngineKit(Ex).

## ◆ setRemoteVoicePositionEx:pan:gain:connection:

- (int) setRemoteVoicePositionEx: |  | (NSUInteger) | uid
pan: |  | (double) | pan
gain: |  | (double) | gain
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Sets the sound position and gain of a remote user.

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

Note:**

- Ensure that you call this method after joining a channel. For this method to work, enable stereo panning for remote users by calling [enableSoundPositionIndication]([AgoraRtcEngineKit 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.
    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.

Parameters

  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.
  connection | AgoraRtcConnection by channelId and uid combine

Returns
  * 0: Success. < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ addVideoWatermarkEx:options:connection:

- (int) addVideoWatermarkEx: |  | (NSURL *_Nonnull) | url
options: |  | (WatermarkOptions *_Nonnull) | options
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Adds a watermark image to the local video.

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

The watermark position depends on the settings in the [setVideoEncoderConfiguration]([AgoraRtcEngineKit 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]([AgoraRtcEngineKit setVideoEncoderConfiguration:]) method. Otherwise, the watermark image will be cropped.

  Note**

- Ensure that you have called the [enableVideo]([AgoraRtcEngineKit 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]([AgoraRtcEngineKit 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]([AgoraRtcEngineKit 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.

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.
  connection | AgoraRtcConnection by channelId and uid combine

Returns
  * 0: Success. < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ clearVideoWatermarkEx:

- (int) clearVideoWatermarkEx: |  | (AgoraRtcConnection *_Nonnull) | connection |

Clears the watermark image on the video stream.

Parameters

  connection | AgoraRtcConnection by channelId and uid combine

Returns
  * 0: Success. < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ createDataStreamEx:reliable:ordered:connection:

- (int) createDataStreamEx: |  | (NSInteger *_Nonnull) | streamId
reliable: |  | (BOOL) | reliable
ordered: |  | (BOOL) | ordered
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Creates a data stream.

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

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.
  connection | AgoraRtcConnection by channelId and uid combine.

Returns
  - 0: Success.
  - < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ createDataStreamEx:config:connection:

- (int) createDataStreamEx: |  | (NSInteger *_Nonnull) | streamId
config: |  | (AgoraDataStreamConfig *_Nonnull) | config
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Creates a data stream.

Each user can create up to five data streams during the lifecycle of the [AgoraRtcChannel](AgoraRtcChannel).

Parameters

  streamId | ID of the created data stream.
  config | the config of data stream.
  connection | AgoraRtcConnection by channelId and uid combine.

Returns
  * 0: Success. < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ sendStreamMessageEx:data:connection:

- (int) sendStreamMessageEx: |  | (NSInteger) | streamId
data: |  | (NSData *_Nonnull) | data
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Sends data stream messages to all users in a channel.

The SDK has the following restrictions on this method:

- Up to 60 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 30 KB of data per second.
- Each user can have up to five data streams simultaneously.

If the remote user receives the data stream within five seconds, the SDK triggers the AgoraRtcEngineDelegate.rtcEngine:receiveStreamMessageFromUid:streamId:data: receiveStreamMessageFromUid callback on the remote client, from which the remote user gets the stream message.

If the remote user does not receive the data stream within five seconds, the SDK triggers the AgoraRtcEngineDelegate.rtcEngine:didOccurStreamMessageErrorFromUid:streamId:error:missed:cached: 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:reliable:ordered: createDataStream before calling this method.

Parameters

  streamId | ID of the sent data stream returned in the `createDataStream` method.
  data | Sent data.
  connection | AgoraRtcConnection by channelId and uid combine.

Returns
  - 0: Success.
  - < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ setHighPriorityUserListEx:option:connection:

- (int) setHighPriorityUserListEx: |  | (NSArray< NSNumber * > *_Nullable) | uidList
option: |  | (AgoraStreamFallbackOptions) | option
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Sets the high priority user list and related remote subscribe fallback option.

Parameters

  uidList | The uid list of high priority users.
  option | The remote subscribe fallback option of high priority users.
  connection | AgoraRtcConnection by channelId and uid combine.

Returns
  - 0: Success.
  - < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ setSubscribeAudioAllowlistEx:connection:

- (int) setSubscribeAudioAllowlistEx: |  | (NSArray< NSNumber * > *_Nonnull) | allowlist
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Sets the allowlist of subscribe remote stream audio.

Parameters

  allowlist | The uid list of users who do subscribe to audio.
  connection | AgoraRtcConnection by channelId and uid combine.

Note
  If uid is in allowlist, the remote user's audio will be subscribed, even if muteRemoteAudioStream(uid, true) and muteAllRemoteAudioStreams(true) are operated.

If a user is in the blocklist and allowlist at the same time, the user will not subscribe to audio.

Returns
  - 0: Success.
  - < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ setSubscribeVideoAllowlistEx:connection:

- (int) setSubscribeVideoAllowlistEx: |  | (NSArray< NSNumber * > *_Nonnull) | allowlist
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Sets the allowlist of subscribe remote stream video.

Parameters

  allowlist | The uid list of users who do subscribe to video.
  connection | AgoraRtcConnection by channelId and uid combine.

Note
  If uid is in whitelist, the remote user's video will be subscribed, even if muteRemoteVideoStream(uid, true) and muteAllRemoteVideoStreams(true) are operated.

If a user is in the blocklist and allowlist at the same time, the user will not subscribe to video.

Returns
  - 0: Success.
  - < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ takeSnapshotEx:uid:filePath:

- (NSInteger) takeSnapshotEx: |  | (AgoraRtcConnection *_Nonnull) | connection
uid: |  | (NSInteger) | uid
filePath: |  | (NSString *_Nonnull) | filePath

Takes a snapshot of a video stream.

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

The method is asynchronous, and the SDK has not taken the snapshot when the method call returns. After a successful method call, the SDK triggers the `snapshotTaken` callback to report whether the snapshot is successfully taken, as well as the details for that snapshot.

Note
  - Call this method after joining a channel.
  - This method takes a snapshot of the published video stream specified in `ChannelMediaOptions`.
  - If the user's video has been preprocessed, for example, watermarked or beautified, the resulting snapshot includes the pre-processing effect.

Parameters

  connection | The RtcConnection object.
  uid | The user ID. Set uid as 0 if you want to take a snapshot of the local user's video.
  filePath | The local path (including filename extensions) of the snapshot. For example: Windows: `C:\Users\<user_name>\AppData\Local\Agora\<process_name>\example.jpg` iOS: `/App Sandbox/Library/Caches/example.jpg` macOS: `～/Library/Logs/example.jpg` Android: `/storage/emulated/0/Android/data/<package name>/files/example.jpg`

Ensure that the path you specify exists and is writable.

Returns
  - 0 : Success.
  - < 0 : Failure.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ takeSnapshotExWithConfig:uid:config:

- (NSInteger) takeSnapshotExWithConfig: |  | (AgoraRtcConnection *_Nonnull) | connection
uid: |  | (NSInteger) | uid
config: |  | (AgoraSnapshotConfig *_Nonnull) | config

Takes a snapshot of a video stream.

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

The method is asynchronous, and the SDK has not taken the snapshot when the method call returns. After a successful method call, the SDK triggers the `snapshotTaken` callback to report whether the snapshot is successfully taken, as well as the details for that snapshot.

Note
  - Call this method after joining a channel.
  - This method takes a snapshot of the published video stream specified in `ChannelMediaOptions`.

Parameters

  connection | The RtcConnection object.
  uid | The user ID. Set uid as 0 if you want to take a snapshot of the local user's video.
  config | The configuration for the take snapshot. See SnapshotConfig.

Ensure that the path you specify exists and is writable.

Returns
  - 0 : Success.
  - < 0: Failure.
    - -4: Incorrect observation position. Modify the input observation position according to the reqiurements specified in SnapshotConfig.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ sendAudioMetadataEx:metadata:

- (int) sendAudioMetadataEx: |  | (AgoraRtcConnection *_Nonnull) | connection
metadata: |  | (NSData *_Nonnull) | metadata

send audio metadata

Since
  v4.3.1

Parameters

  metadata | The NSData of metadata
  connection | AgoraRtcConnection.

Returns
  - 0: success
  - <0: failure @technical preview

Provided by category AgoraRtcEngineKit(Ex).

## ◆ enableContentInspectEx:config:connection:

- (int) enableContentInspectEx: |  | (BOOL) | enabled
config: |  | (AgoraContentInspectConfig *_Nonnull) | config
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Enables video screenshot and upload with the connection ID.

Parameters

  enabled | Whether to video screenshot and upload: `true`: Yes. `false`: No.
  config | The configuration for video screenshot and upload.
  connection | The connection information. See AgoraRtcConnection.

Returns
  - 0: Success.
  - < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ startRtmpStreamWithoutTranscodingEx:connection:

- (int) startRtmpStreamWithoutTranscodingEx: |  | (NSString *_Nonnull) | url
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Publishes the local stream without transcoding to a specified CDN live RTMP address. (CDN live only.)

Parameters

  url | The CDN streaming URL in the RTMP format. The maximum length of this parameter is 1024 bytes.
  connection | AgoraRtcConnection.

Returns
  - 0: Success.
  - < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ startRtmpStreamWithTranscodingEx:transcoding:connection:

- (int) startRtmpStreamWithTranscodingEx: |  | (NSString *_Nonnull) | url
transcoding: |  | (AgoraLiveTranscoding *_Nullable) | transcoding
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Publishes the local stream with transcoding to a specified CDN live RTMP address. (CDN live only.)

Parameters

  url | The CDN streaming URL in the RTMP format. The maximum length of this parameter is 1024 bytes.
  transcoding | Sets the CDN live audio/video transcoding settings. See LiveTranscoding.
  connection | AgoraRtcConnection.

Returns
  - 0: Success.
  - < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ updateRtmpTranscodingEx:connection:

- (int) updateRtmpTranscodingEx: |  | (AgoraLiveTranscoding *_Nullable) | transcoding
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

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

Note
  This method applies to Live Broadcast only.

Parameters

  transcoding | Sets the CDN live audio/video transcoding settings. See LiveTranscoding.
  connection | AgoraRtcConnection.

Returns
  - 0: Success.
  - < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ stopRtmpStreamEx:connection:

- (int) stopRtmpStreamEx: |  | (NSString *_Nonnull) | url
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Stop an RTMP stream with transcoding or without transcoding from the CDN. (CDN live only.)

Parameters

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

Returns
  - 0: Success.
  - < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ startOrUpdateChannelMediaRelayEx:connection:

- (int) startOrUpdateChannelMediaRelayEx: |  | (AgoraChannelMediaRelayConfiguration *_Nonnull) | config
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Starts or update to relay media streams across channels.

Since
  v4.2.0

Parameters

  config | The configuration of the media stream relay:AgoraChannelMediaRelayConfiguration.
  connection | AgoraRtcConnection.

Returns
  - 0: Success.
  - < 0: Failure.
    - -1(ERR_FAILED): A general error occurs (no specified reason).
    - -2(ERR_INVALID_ARGUMENT): The argument is invalid.
    - -5(ERR_REFUSED): The request is rejected.
    - -8(ERR_INVALID_STATE): The current status is invalid, only allowed to be called when the role is the broadcaster.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ stopChannelMediaRelayEx:

- (int) stopChannelMediaRelayEx: |  | (AgoraRtcConnection *_Nonnull) | connection |

Stops the media stream relay.

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

Parameters

  connection | AgoraRtcConnection.

Returns
  - 0: Success.
  - < 0: Failure.
    - -1(ERR_FAILED): A general error occurs (no specified reason).
    - -2(ERR_INVALID_ARGUMENT): The argument is invalid.
    - -5(ERR_REFUSED): The request is rejected.
    - -7(ERR_NOT_INITIALIZED): cross channel media streams are not relayed.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ pauseAllChannelMediaRelayEx:

- (int) pauseAllChannelMediaRelayEx: |  | (AgoraRtcConnection *_Nonnull) | connection |

pause the channels for media stream relay.

Parameters

  connection | AgoraRtcConnection.

Returns
  - 0: Success.
  - < 0: Failure.
    - -1(ERR_FAILED): A general error occurs (no specified reason).
    - -2(ERR_INVALID_ARGUMENT): The argument is invalid.
    - -5(ERR_REFUSED): The request is rejected.
    - -7(ERR_NOT_INITIALIZED): cross channel media streams are not relayed.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ resumeAllChannelMediaRelayEx:

- (int) resumeAllChannelMediaRelayEx: |  | (AgoraRtcConnection *_Nonnull) | connection |

resume the channels for media stream relay.

Parameters

  connection | AgoraRtcConnection.

Returns
  - 0: Success.
  - < 0: Failure.
    - -1(ERR_FAILED): A general error occurs (no specified reason).
    - -2(ERR_INVALID_ARGUMENT): The argument is invalid.
    - -5(ERR_REFUSED): The request is rejected.
    - -7(ERR_NOT_INITIALIZED): cross channel media streams are not relayed.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ startMediaRenderingTracingEx:

- (int) startMediaRenderingTracingEx: |  | (AgoraRtcConnection *_Nonnull) | connection |

Start tracing media rendering events.

Since
  v4.1.1 @discussion
  - SDK will trace media rendering events when this API is called.
  - The tracing result can be obtained through callback `[AgoraRtcEngineDelegate rtcEngine:videoRenderingTracingResultOfUid:currentEvent:tracingInfo:]`

Parameters

  connection | AgoraRtcConnection.

Note
  - By default, SDK will trace media rendering events when join channel.
  - The start point of event tracing will be reset after leaving channel.

Returns
  - 0: Success.
  - < 0: Failure.
    - `-2(AgoraErrorCodeInvalidArgument)`: The parameter is invalid. Check the channel ID and local uid set by parameter `connection`.
    - `-7(AgoraErrorCodeNotInitialized)`: The SDK is not initialized.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ setParametersEx:connection:

- (int) setParametersEx: |  | (NSString *_Nonnull) | options
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Provides the technical preview functionalities or special customizations by configuring the SDK with JSON options.

Note
  The JSON options are not public by default. Agora is working on making commonly used JSON options public in a standard way. Contact suppo.nosp@m.rt@a.nosp@m.gora..nosp@m.io for more information.

Parameters

  options | SDK options in JSON format.
  connection | AgoraRtcConnection.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ getCallIdEx:

- (NSString * _Nullable) getCallIdEx: |  | (AgoraRtcConnection *_Nonnull) | connection |

Gets the current call ID.

When a user joins a channel, a call ID is generated to identify the call.

After a call ends, you can call `rate` or `complain` to gather feedback from your customer.

Parameters

  connection | The AgoraRtcConnection object.

Returns
  The call ID if the method call is successful.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ addDelegateEx:connection:

- (void) addDelegateEx: |  | (id< AgoraRtcEngineDelegate > _Nonnull) | delegate
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Adds multiple SDK delegate.

Parameters

  delegate | The AgoraRtcEngineDelegate object.
  connection | The AgoraRtcConnection object.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ removeDelegateEx:connection:

- (void) removeDelegateEx: |  | (id< AgoraRtcEngineDelegate > _Nonnull) | delegate
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Removes multiple SDK delegate.

Parameters

  delegate | The AgoraRtcEngineDelegate object.
  connection | The AgoraRtcConnection object.

Provided by category AgoraRtcEngineKit(Ex).

## ◆ enableEncryptionEx:encryptionConfig:connection:

- (int) enableEncryptionEx: |  | (BOOL) | enabled
encryptionConfig: |  | (AgoraEncryptionConfig *_Nonnull) | config
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Enables/Disables the built-in encryption.

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.

Parameters

  enabled | Whether to enable the built-in encryption:

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

Parameters

  config | Configurations of built-in encryption schemas. See AgoraEncryptionConfig.
  connection | AgoraRtcConnection by channelId and uid combine

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

Provided by category AgoraRtcEngineKit(Ex).

## ◆ enableVideoImageSourceEx:options:connection:

- (int) enableVideoImageSourceEx: |  | (BOOL) | enable
options: |  | (AgoraImageTrackOptions *_Nullable) | options
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Enable or disable video image source to replace the current video source published or resume it

Parameters

  enable | true for enable, false for disable
  options | options for image track
  connection | The AgoraRtcConnection object.

Provided by category AgoraRtcEngineKit(Ex).

## Property Documentation

## ◆ delegate

- (id<AgoraRtcEngineDelegate> _Nullable) delegate
| read write nonatomic weak

Sets and retrieves the SDK delegate.

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