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) - muteRemoteAudioStreamEx:mute:connection:
 
(int) - setVideoEncoderConfigurationEx:connection:
 
(int) - setupRemoteVideoEx:connection:
 
(int) - setRemoteRenderModeEx:mode:mirror:connection:
 
(int) - muteRemoteVideoStreamEx:mute:connection:
 
(int) - enableDualStreamModeEx:enabled:streamConfig:connection:
 
(int) - setRemoteVideoStreamEx:type:connection:
 
(BOOL) - pushExternalVideoFrame:connection:
 
(AgoraUserInfo *_Nullable) - getUserInfoByUserAccountEx:connection:withError:
 
(AgoraUserInfo *_Nullable) - getUserInfoByUidEx:connection:withError:
 
(AgoraConnectionState- getConnectionStateEx:
 
(int) - setRemoteVoicePositionEx:pan:gain:connection:
 
(int) - addVideoWatermarkEx:options:connection:
 
(int) - clearVideoWatermarkEx:
 

Core Methods


id< AgoraRtcEngineDelegate > _Nullable delegate
 
(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) - startChannelMediaRelay:
 
(int) - updateChannelMediaRelay:
 
(int) - stopChannelMediaRelay
 
(int) - pauseAllChannelMediaRelay
 
(int) - resumeAllChannelMediaRelay
 
(int) - enableWebSdkInteroperability:
 
(instancetype _Nonnull) + sharedEngineWithAppId:delegate:
 
(instancetype _Nonnull) + sharedEngineWithConfig:delegate:
 
(void) + destroy
 

Core Audio


(int) - enableAudio
 
(int) - disableAudio
 
(int) - enableLocalAudio:
 
(int) - setAudioProfile:
 
(int) - enableAudioVolumeIndication:smooth:reportVad:
 
(int) - adjustUserPlaybackSignalVolume:volume:
 
(int) - enableExtensionWithVendor:extension:enabled:sourceType:
 
(int) - setExtensionProviderPropertyWithVendor:key:value:
 
(int) - setExtensionPropertyWithVendor:extension:key:value:sourceType:
 

Core Video


(int) - enableVideo
 
(int) - disableVideo
 
(int) - enableLocalVideo:
 
(int) - setupLocalVideo:
 
(int) - setLocalRenderMode:mode:
 
(int) - setLocalRenderMode:mirror:
 
(int) - startPreview
 
(int) - stopPreview
 
(int) - setRemoteRenderMode:mode:mirror:
 
(int) - muteLocalVideoStream:
 
(int) - muteAllRemoteVideoStreams:
 
(int) - setDefaultMuteAllRemoteVideoStreams:
 
(int) - muteRemoteVideoStream:mute:
 
(int) - enableVirtualBackground:backData:
 
(int) - enableRemoteSuperResolution:enable:
 

Audio Effect Playback


(int) - setVoiceBeautifierPreset:
 
(int) - setVoiceConversionPreset:
 
(int) - setVoiceBeautifierParameters:param1:param2:
 
(int) - setVoiceConversionParameters:param1:param2:
 

Sound Position Indication


(int) - enableSoundPositionIndication:
 
(int) - setRemoteVoicePosition:pan:gain:
 
(int) - enableSpatialAudio:
 

Miscellaneous Audio Control


(int) - enableInEarMonitoring:
 
(int) - enableInEarMonitoring:includeAudioFilters:
 
(int) - setInEarMonitoringVolume:
 

Dual Video Mode


(int) - enableDualStreamMode:
 
(int) - enableDualStreamMode:enabled:
 
(int) - enableDualStreamMode:enabled:streamConfig:
 
(int) - setRemoteDefaultVideoStreamType:
 

External Media Source


(void) - setExternalVideoSource:useTexture:sourceType:
 
(BOOL) - pushExternalVideoFrame:
 
(void) - enableExternalAudioSink:channels:
 
(BOOL) - pullPlaybackAudioFrameRawData:lengthInByte:
 
(CMSampleBufferRef _Nullable) - pullPlaybackAudioFrameSampleBufferByLengthInByte:
 
(int) - setExternalAudioSource:sampleRate:channels:
 
(int) - setExternalAudioSource:sampleRate:channels:sourceNumber:localPlayback:publish:
 
(int) - enableCustomAudioLocalPlayback:enabled:
 
(int) - setDirectExternalAudioSource:
 
(int) - setDirectExternalAudioSource:localPlayback:
 
(int) - pushDirectAudioFrameNSData:
 
(int) - pushDirectAudioFrameRawData:samples:sampleRate:channels:
 
(int) - enableExternalAudioSourceLocalPlayback:
 
(int) - setRecordingAudioFrameParametersWithSampleRate:channel:mode:samplesPerCall:
 
(int) - setPlaybackAudioFrameParametersWithSampleRate:channel:mode:samplesPerCall:
 
(int) - setMixedAudioFrameParametersWithSampleRate:channel:samplesPerCall:
 
(int) - setPlaybackAudioFrameBeforeMixingParametersWithSampleRate:channel:
 
(int) - enableAudioSpectrumMonitor:
 
(int) - disableAudioSpectrumMonitor
 
(int) - registerAudioSpectrumDelegate:
 
(int) - unregisterAudioSpectrumDelegate:
 

Built-in Encryption


(int) - enableEncryption:encryptionConfig:
 

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:
 

Camera Control


(CGFloat) - cameraMaxZoomFactor
 
(int) - switchCamera
 

Face Detection


(int) - enableFaceDetection:
 

Watermark


(int) - addVideoWatermark:options:
 
(int) - registerLocalUserAccountWithAppID:userAccount:
 
(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:
 

Media Metadata


(BOOL) - setMediaMetadataDataSource:withType:
 
(BOOL) - setMediaMetadataDelegate:withType:
 

Miscellaneous Methods


(int) - setLogFile:
 
(int) - setLogFilter:
 
(int) - setLogFileSize:
 
(NSString *_Nullable) - uploadLogFile
 
(NSString *_Nullable) - getCallId
 
(int) - rate:rating:description:
 
(int) - complain:description:
 
(int) - startLastmileProbeTest:
 
(int) - stopLastmileProbeTest
 
(NSString *_Nonnull) + getSdkVersion
 
(NSString *_Nonnull) + getErrorDescription:
 

MediaPlayer publish


(id< AgoraRtcMediaPlayerProtocol >_Nullable) - createMediaPlayerWithDelegate:
 
(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) - pushDirectCdnStreamingCustomVideoFrame:
 

Deprecated Methods


(int) - setAudioProfile:scenario:
 
(int) - setAdvancedAudioOptions:
 
(int) - sendCustomReportMessage:category:event:label:value:
 
(int) - setLogLevel:
 
(int) - setLocalAccessPoint:
 
(int) - setCloudProxy:
 
(int) - enableFishCorrection:params:
 
(int) - setAVSyncSource:uid:
 

Detailed Description

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

◆ 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 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: didJoinChannel.
  • The remote client: 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 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
tokenThe 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.
channelIdUnique 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.
uidUser 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.
joinSuccessBlockSame as 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

◆ 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 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: didJoinChannel.
  • The remote client: 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 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
tokenThe 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.
channelIdUnique 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
uidUser 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.
mediaOptionsAgoraRtcChannelMediaOptions Object.
joinSuccessBlockSame as 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

◆ 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 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
leaveChannelBlockThis 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
profileThe channel profile: AgoraChannelProfile.
Returns
  • 0: Success.
  • < 0: Failure.

◆ updateChannelWithMediaOptions:

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

Updates the channel media options after joining the channel.

Parameters
mediaOptionsThe 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
    roleRole 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:

Parameters
roleThe 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
optionsThe client role of the user, see AgoraClientRoleOptions.
Returns
- 0(AgoraRtmpStreamingErrorCodeOK): Success.
  • < 0: Failure.
    • -1(AgoraErrorCodeFailed): A general error occurs (no specified reason).
    • -2(AgoraErrorCodeInvalidArgument): The parameter is invalid.
    • -7(AgoraErrorCodeNotInitialized): The SDK is not initialized.

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

◆ getConnectionState

- (AgoraConnectionState) getConnectionState

Gets the connection state of the SDK.

Returns
The connection state. See AgoraConnectionState.

◆ startChannelMediaRelay:

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

Starts to relay media streams across channels.

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

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

    Note**

  • Call this method after the [joinChannel]([AgoraRtcEngineKit joinChannelByToken:channelId:info:uid:joinSuccess:]) method.
  • This method takes effect only when you are a broadcaster in a Live-broadcast channel.
  • After a successful method call, if you want to call this method again, ensure that you call the [stopChannelMediaRelay]([AgoraRtcEngineKit stopChannelMediaRelay]) method to quit the current relay.
  • 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.
Parameters
configThe configuration of the media stream relay: [AgoraChannelMediaRelayConfiguration](AgoraChannelMediaRelayConfiguration).
Returns
- 0: Success.
  • < 0: Failure.

◆ updateChannelMediaRelay:

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

Updates the channels for media stream relay.

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

After a successful method call, the SDK triggers the [didReceiveChannelMediaRelayEvent]([AgoraRtcEngineDelegate rtcEngine:didReceiveChannelMediaRelayEvent:]) callback with the AgoraChannelMediaRelayEventUpdateDestinationChannel(7) state code.

Note**

  • Call this method after the [startChannelMediaRelay]([AgoraRtcEngineKit startChannelMediaRelay:]) method to update the destination channel.
  • This method supports adding at most four destination channels in the relay. If there are already four destination channels in the relay, remove the unnecessary ones with the removeDestinationInfoForChannelName method in channelMediaRelayConfiguration before calling this method.
Parameters
configThe media stream relay configuration: [AgoraChannelMediaRelayConfiguration](AgoraChannelMediaRelayConfiguration).
Returns
- 0: Success.
  • < 0: Failure.

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

◆ pauseAllChannelMediaRelay

- (int) pauseAllChannelMediaRelay

pause the channels for media stream relay.

Returns
  • 0: Success.
  • < 0: Failure.

◆ resumeAllChannelMediaRelay

- (int) resumeAllChannelMediaRelay

resume the channels for media stream relay.

Returns
  • 0: Success.
  • < 0: Failure.

◆ enableWebSdkInteroperability:

- (int) enableWebSdkInteroperability: (BOOL)  enabled
Deprecated:
Web SDK interoperability is by default enabled.
Parameters
enabledWhether interoperability with the Agora Web SDK is enabled:
  • YES: Enabled.
  • NO: Disabled.
Returns
  • 0: Success.
  • <0: Failure.

◆ 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
appIdApp ID of your Agora project.
delegateAgoraRtcEngineDelegate.
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 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
configConfigurations for the AgoraRtcEngineKit instance. For details, see AgoraRtcEngineConfig.
delegateAgoraRtcEngineDelegate.
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.

◆ destroy

+ (void) destroy

This method releases all the resources used by the Agora SDK. This is useful for applications that occasionally make voice or video calls, to free up resources for other operations when not making calls. 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 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.

◆ 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
enabledDetermines 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 method.
Parameters
profileThe audio profile, such as the sample rate, bitrate, encoding mode, and the number of channels, see AgoraAudioProfile.
Returns
  • 0: Success.
  • <0: Failure.

◆ 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 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
intervalSets 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).
smoothThe 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
uidThe ID of the remote user.
volumeThe playback volume of the specified remote user. The value ranges from 0 to 100:
  • 0: Mute.
  • 100: Original volume.
Returns
- 0: Success.
  • < 0: Failure.

◆ enableExtensionWithVendor:extension:enabled:

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

◆ enableExtensionWithVendor:extension:enabled:sourceType:

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

Enable/Disable extension.

Parameters
providername for provider, e.g. agora.builtin.
extensionname for extension, e.g. agora.beauty.
enabledenable or disable.
  • true: enable.
  • false: disable.
sourceTypeMedia source types definition see AgoraMediaSourceType, default is AgoraMediaSourceTypeUnknown.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setExtensionProviderPropertyWithVendor:key:value:

- (int) setExtensionProviderPropertyWithVendor: (NSString *__nonnull)  provider
key: (NSString *__nonnull)  key
value: (NSString *__nonnull)  value 

Set extension provider specific property.

Parameters
providername for provider, e.g. agora.io.
keykey for the property.
valueproperty value.
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 

◆ 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 

Set extension specific property.

Parameters
providername for provider, e.g. agora.builtin.
extensionname for extension, e.g. agora.beauty.
keykey for the property.
valueproperty value.
sourceTypeMedia source types definition see AgoraMediaSourceType, default is AgoraMediaSourceTypeUnknown.
Returns
  • 0: Success.
  • < 0: Failure.

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

◆ 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
localThe local video view and settings. See AgoraRtcVideoCanvas.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLocalRenderMode:mode:

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

◆ 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 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
modeSets the local display mode. See AgoraVideoRenderMode.
mirrorSets 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, the local video preview remains until you call stopPreview to disable it.

Returns
  • 0: Success.
  • < 0: Failure.

◆ stopPreview

- (int) stopPreview

Stops the local video preview and the video.

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
uidUser id of the user whose video streams are received.
modeAgoraVideoRenderMode
mirrorAgoraVideoMirrorMode
Returns
* 0: Success. <0: Failure.

◆ muteLocalVideoStream:

- (int) muteLocalVideoStream: (BOOL)  mute

Stops or resumes sending the local video stream.

Parameters
muteDetermines 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.

◆ 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(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 autoSubscribeVideo to set whether to receive remote video streams for a specific channel.
Parameters
muteWhether 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.

◆ setDefaultMuteAllRemoteVideoStreams:

- (int) setDefaultMuteAllRemoteVideoStreams: (BOOL)  mute
Deprecated:
To set whether to receive remote video streams by default, call muteAllRemoteVideoStreams before calling joinChannelByToken.

Determines whether to receive all remote video streams by default.

Parameters
muteWhether to receive remote video streams by default:
  • YES: Do not receive any remote video stream by default.
  • NO: (Default) Receive remote video streams by default.
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
uidID of the specified remote user.
muteWhether 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.

◆ enableVirtualBackground:backData:

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

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
enableSets whether to enable the virtual background:
  • YES: Enable.
  • NO: Disable.
    Parameters
    backDataThe 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.
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,

◆ enableRemoteSuperResolution:enable:

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

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

Since
v4.0.0

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

Warning
The super resolution feature requires extra system resources. To balance the visual experience and system consumption, the SDK poses the following restrictions:
  • This feature can only be enabled for a single remote user.
  • The original resolution of the remote user's video cannot exceed a certain range. If the local user use super resolution on Android, the original resolution of the remote user's video cannot exceed 640 × 360 pixels; if the local user use super resolution on iOS, the original resolution of the remote user's video cannot exceed 640 × 480 pixels.
Note
  • This method is for Android and iOS only.
  • Before calling this method, ensure that you have integrated the following dynamic library into your project:
    • Android: libagora_super_resolution_extension.so
    • iOS: AgoraSuperResolutionExtension.xcframework
  • Because this method has certain system performance requirements, Agora recommends that you use the following devices or better:
    • Android:
      • VIVO: V1821A, NEX S, 1914A, 1916A, 1962A, 1824BA, X60, X60 Pro
      • OPPO: PCCM00, Find X3
      • OnePlus: A6000
      • Xiaomi: Mi 8, Mi 9, Mi 10, Mi 11, MIX3, Redmi K20 Pro
      • SAMSUNG: SM-G9600, SM-G9650, SM-N9600, SM-G9708, SM-G960U, SM-G9750, S20, S21
      • HUAWEI: SEA-AL00, ELE-AL00, VOG-AL00, YAL-AL10, HMA-AL00, EVR-AN00, nova 4, nova 5 Pro, nova 6 5G, nova 7 5G, Mate 30, Mate 30 Pro, Mate 40, Mate 40 Pro, P40 P40 Pro, HUAWEI MediaPad M6, MatePad 10.8
    • iOS (iOS 12.0 or later):
      • iPhone XR
      • iPhone XS
      • iPhone XS Max
      • iPhone 11
      • iPhone 11 Pro
      • iPhone 11 Pro Max
      • iPhone 12
      • iPhone 12 mini
      • iPhone 12 Pro
      • iPhone 12 Pro Max
      • iPhone 12 SE (2nd generation)
      • iPad Pro 11-inch (3rd generation)
      • iPad Pro 12.9-inch (3rd generation)
      • iPad Air (3rd generation)
      • iPad Air (4th generation)
Parameters
uidThe user ID of the remote user.
enabledDetermines whether to enable super resolution for the remote user's video:
  • true: Enable super resolution.
  • false: Disable super resolution.
Returns
  • 0: Success.
  • < 0: Failure.

◆ 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
presetThe 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
    • setLocalVoiceEqualization
    • setLocalVoiceReverb
    • setVoiceBeautifierParameters
Parameters
presetThe 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
presetThe options for SDK preset voice beautifier effects:
  • SINGING_BEAUTIFIER: Singing beautifier effect.
param1The gender characteristics options for the singing voice:
  • 1: A male-sounding voice.
  • 2: A female-sounding voice.
param2The 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
presetThe options for SDK preset audio effects. See #VOICE_CONVERSION_PRESET.
param1reserved.
param2reserved.
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
enabledSets 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
      uidThe ID of the remote user.
      panThe 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
gainGain 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
enabledSets whether or not to enable spatial audio for remote users:
  • YES: enables spatial audio.
  • NO: disables spatial audio.
Returns
* 0: Success. < 0: Failure

◆ startAudioRecordingWithConfig:

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

◆ setAudioEncodedFrameDelegate:config:

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

◆ enableInEarMonitoring:

- (int) enableInEarMonitoring: (BOOL)  enabled

Enables in-ear monitoring.

Parameters
enabledDetermines 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
enabledDetermines whether to enable in-ear monitoring.
  • YES: Enable in-ear monitoring.
  • NO: Disable in-ear monitoring.
includeAudioFiltersThe 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
volumeThe 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.

Parameters
enabled
  • YES: Enable the dual-stream mode.
  • NO: (default) Disable the dual-stream mode.
Returns
  • 0: Success.
  • <0: Failure.

◆ enableDualStreamMode:enabled:

- (int) enableDualStreamMode: (AgoraVideoSourceType sourceType
enabled: (BOOL)  enabled 

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.

Parameters
sourceType
  • The video source type.
enabled
  • true: Enable the dual-stream mode.
  • false: (default) Disable the dual-stream mode.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableDualStreamMode:enabled:streamConfig:

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

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.

Parameters
sourceType
  • The video source type.
enabled
  • true: Enable the dual-stream mode.
  • false: (default) Disable the dual-stream mode.
streamConfig
  • The minor stream config
Returns
  • 0: Success.
  • < 0: Failure.

◆ 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
streamTypeThe default video stream type: AgoraVideoStreamType.
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
enableDetermines 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
useTextureDetermines whether to use textured video data.
  • YES: Use the texture as an input.
  • NO: Do not use the texture as an input.
sourceTypeDetermines the type of the external video source.

◆ 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 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
frameVideo frame containing the SDK's encoded video data to be pushed: AgoraVideoFrame.
Returns
  • YES: Success.
  • NO: Failure.

◆ enableExternalAudioSink:channels:

- (void) enableExternalAudioSink: (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
sampleRateSets the sample rate (Hz) of the external audio sink. You can set this parameter as 16000, 32000, 44100 or 48000.
channelsSets the number of audio channels of the external audio sink:
  • 1: Mono
  • 2: Stereo
Note
Once you enable the external audio sink, the app will not retrieve any audio data from the onPlaybackAudioFrame callback.

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

  • Once you call the [pullPlaybackAudioFrameRawData]([AgoraRtcEngineKit pullPlaybackAudioFrameRawData:lengthInByte:]) method successfully, the app will not retrieve any audio data from the onPlaybackAudioFrame callback.
  • The difference between the onPlaybackAudioFrame callback and the pullPlaybackAudioFrameRawData method is as follows:
    • onPlaybackAudioFrame: The SDK sends the audio data to the app once every 10 ms. Any delay in processing the audio frames may result in audio jitter.
    • pullPlaybackAudioFrameRawData: The app pulls the remote audio data autonomously. After setting the audio data parameters, the SDK adjusts the frame buffer and avoids problems caused by jitter in the external audio playback.
Parameters
dataThe audio data that you want to pull. The data format is in byte[].
lengthInByteThe 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**

  • Once you call the [pullPlaybackAudioFrameSampleBufferByLengthInByte]([AgoraRtcEngineKit pullPlaybackAudioFrameSampleBufferByLengthInByte:]) method successfully, the app will not retrieve any audio data from the onPlaybackAudioFrame callback.
  • The difference between the onPlaybackAudioFrame callback and the pullPlaybackAudioFrameSampleBufferByLengthInByte method is as follows:
    • onPlaybackAudioFrame: The SDK sends the audio data to the app once every 10 ms. Any delay in processing the audio frames may result in audio jitter.
    • pullPlaybackAudioFrameSampleBufferByLengthInByte: The app pulls the remote audio data. After setting the audio data parameters, the SDK adjusts the frame buffer and avoids problems caused by jitter in the external audio playback.
Parameters
lengthInByteThe 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.

◆ 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.
Parameters
enabledDetermines whether to enable the external audio source:
  • true: Enable the external audio source.
  • false: (default) Disable the external audio source.
sampleRateThe Sample rate (Hz) of the external audio source, which can set be as 8000, 16000, 32000, 44100, or 48000.
channelsThe 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.

◆ enableEchoCancellationExternal:audioSourceDelay:

- (int) enableEchoCancellationExternal: (BOOL)  enabled
audioSourceDelay: (NSInteger)  audioSourceDelay 

◆ setExternalAudioSource:sampleRate:channels:sourceNumber:localPlayback:publish:

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

Sets the external audio source.

Note
Ensure that you call this method before joining the channel.
Parameters
enabledDetermines whether to enable the external audio source:
  • true: Enable the external audio source.
  • false: (default) Disable the external audio source.
sampleRateThe Sample rate (Hz) of the external audio source, which can set be as 8000, 16000, 32000, 44100, or 48000.
channelsThe number of channels of the external audio source, which can be set as 1 or 2:
  • 1: Mono.
  • 2: Stereo.
sourceNumberThe number of the external audio sources, should be greater than 0.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableCustomAudioLocalPlayback:enabled:

- (int) enableCustomAudioLocalPlayback: (NSInteger)  sourceId
enabled: (BOOL)  enabled 

Sets the external audio source.

Note
Ensure that you call this method before joining the channel.
Parameters
sourceIdcustom audio source id.
enabledDetermines whether to local playback the external audio source:
  • true: Local playback the external audio source.
  • false: Local don`t playback the external audio source.
Returns
  • 0: Success.
  • < 0: Failure.

◆ pushCaptureAudioFrame:

- (int) pushCaptureAudioFrame: (AgoraAudioFrame *_Nonnull)  audioFrame

◆ pushReverseAudioFrame:

- (int) pushReverseAudioFrame: (AgoraAudioFrame *_Nonnull)  audioFrame

◆ setDirectExternalAudioSource:

- (int) setDirectExternalAudioSource: (BOOL)  enabled

Sets the direct external audio source.

Parameters
enabledDetermines whether to enable the direct external audio source:
  • true: Enable the direct external audio source.
  • false: (default) Disable the direct external audio source.

◆ setDirectExternalAudioSource:localPlayback:

- (int) setDirectExternalAudioSource: (BOOL)  enabled
localPlayback: (BOOL)  localPlayback 

Sets the direct external audio source.

Parameters
enabledDetermines whether to enable the direct external audio source:
  • true: Enable the direct external audio source.
  • false: (default) Disable the direct external audio source.
localPlaybackDetermines whether to enable the local playback of the direct external audio source

◆ pushDirectAudioFrameNSData:

- (int) pushDirectAudioFrameNSData: (NSData *_Nonnull)  data

Pushes the direct send audio data to the Agora SDK with not buffer.

Parameters
dataExternal audio data. (sampleRate / channels by setExternalAudioSource:)
Returns
  • 0: Success.
  • <0: Failure.

◆ pushDirectAudioFrameRawData:samples:sampleRate:channels:

- (int) pushDirectAudioFrameRawData: (void *_Nonnull)  data
samples: (NSInteger)  samples
sampleRate: (NSInteger)  sampleRate
channels: (NSInteger)  channels 

Pushes the direct send audio data to the Agora SDK with not buffer.

Parameters
dataExternal audio data.
samplesNumber of samples for the push, which can be set as "samples = data.length / sizeof(int16_t)"
sampleRateThe Sample rate (Hz) , which can set be as 8000, 16000, 32000, 44100, or 48000.
channelsThe number of channels, which can be set as 1 or 2:
  • 1: Mono.
  • 2: Stereo.
Returns
  • 0: Success.
  • <0: Failure.

◆ enableExternalAudioSourceLocalPlayback:

- (int) enableExternalAudioSourceLocalPlayback: (BOOL)  enable

Enable or disable the external audio source local playback.

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

◆ 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
sampleRateThe audio sample rate (samplesPerSec) returned in the onRecordAudioFrame callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
channelThe number of audio channels (channels) returned in the onRecordAudioFrame callback, which can be set as 1 or 2:
  • 1: Mono
  • 2: Stereo
modeDeprecated. The use mode of the onRecordAudioFrame callback.See AgoraAudioRawFrameOperationMode.
samplesPerCallThe 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
sampleRateThe sample rate (samplesPerSec) returned in the onPlaybackAudioFrame callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
channelThe number of audio channels (channels) returned in the onPlaybackAudioFrame callback, which can be set as 1 or 2:
  • 1: Mono
  • 2: Stereo
modeDeprecated. The use mode of the onPlaybackAudioFrame callback. See AgoraAudioRawFrameOperationMode.
samplesPerCallThe 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
sampleRateThe sample rate (Hz) of the audio data returned in the onMixedAudioFrame callback, which can set be as 8000, 16000, 32000, 44100, or 48000.
channelThe number of channels of the audio data in onMixedAudioFrame callback, which can be set as 1 or 2:
  • 1: Mono
  • 2: Stereo
samplesPerCallNot 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.

◆ setPlaybackAudioFrameBeforeMixingParametersWithSampleRate:channel:

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

Sets the audio frame parameters for the onPlaybackAudioFrameBeforeMixing callback.

Parameters
sampleRateThe sample rate(Hz) contained in the onPlaybackAudioFrameBeforeMixing callback. You can set it as 8000, 16000, 32000, 44100, or 48000.
channelThe number of channels contained in the onPlaybackAudioFrameBeforeMixing callback.
  • 1: Mono.
  • 2: Stereo.
Returns
int
  • 0: Success.
  • < 0: Failure.

◆ adjustCustomAudioPublishVolume:volume:

- (int) adjustCustomAudioPublishVolume: (NSInteger)  sourceId
volume: (NSInteger)  volume 

◆ adjustCustomAudioPlayoutVolume:volume:

- (int) adjustCustomAudioPlayoutVolume: (NSInteger)  sourceId
volume: (NSInteger)  volume 

◆ enableAudioSpectrumMonitor:

- (int) enableAudioSpectrumMonitor: (int)  intervalInMS

Enable the audio spectrum monitor.

Parameters
intervalInMSSets 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.

◆ 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
delegateAgoraAudioSpectrumDelegate
Returns
  • 0: Success.
  • < 0: Failure.

◆ unregisterAudioSpectrumDelegate:

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

Releases the audio spectrum delegate.

Parameters
delegateAgoraAudioSpectrumDelegate
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
enabledWhether to enable the built-in encryption:
  • YES: Enable the built-in encryption.
  • NO: Disable the built-in encryption.
Parameters
configConfigurations 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
streamIdID of the created data stream.
configthe config of data stream.
Returns
* 0: Success. < 0: Failure.

◆ startRtmpStreamWithoutTranscoding:

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

New publish stream interface, just publish raw stream

Parameters
urlThe 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.

◆ startRtmpStreamWithTranscoding:transcoding:

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

New publish stream interface, just publish mix stream

Parameters
urlThe 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.
transcodingSets the CDN live audio/video transcoding settings. See AgoraLiveTranscoding.
Returns
= 0: Success < 0: Failure.

◆ 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
transcodingSets 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
urlThe RTMP URL address to be removed. The maximum length of this parameter is 1024 bytes.
Returns
= 0: Success. < 0: Failure.

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

◆ 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
enableDetermines 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
urlThe 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.
optionsThe options of the watermark image to be added. See WatermarkOptions.
Returns
* 0: Success. < 0: Failure.

◆ switchChannel:channelName:

- (int) switchChannel: (NSString *_Nonnull)  token
channelName: (NSString *_Nonnull)  channelName 

◆ registerLocalUserAccountWithAppID:userAccount:

- (int) registerLocalUserAccountWithAppID: (NSString *_Nonnull)  appID
userAccount: (NSString *_Nonnull)  userAccount 

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:

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
appIDThe App ID of your project.
userAccountThe 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.

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

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
tokenThe 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.
channelIdThe 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
userAccountThe 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
joinSuccessBlockcallback 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:

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
tokenThe 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.
channelIdThe 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
userAccountThe 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
mediaOptionsThe channel media options: ChannelMediaOptions
joinSuccessBlockcallback 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
userAccountThe user account of the user. Ensure that you set this parameter.
errorThe 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
uidThe user ID of the user. Ensure that you set this parameter.
errorThe 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
delegateobserver 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
delegateAn 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
delegateAn object to the video frame observer: id<AgoraEncodedVideoFrameDelegate>.
Returns
  • 0: Success.
  • < 0: Failure.

◆ 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 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
metadataDataSourceThe AgoraMediaMetadataDataSource protocol.
typeThe 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
metadataDelegateThe AgoraMediaMetadataDelegate protocol.
typeThe 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
errorThe 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 method, otherwise the output log might not be complete.
Parameters
filePathAbsolute 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
Parameters
filterLog 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
fileSizeInKBytesThe 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.

◆ 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
callIdThe call ID retrieved from the getCallId method.
ratingThe 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

◆ 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
callIdThe call ID retrieved from the getCallId method.
description(Optional) The description of the complaint. The string length must be less than 800 bytes.
Returns

◆ 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 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
configThe 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.

◆ createMediaPlayerWithDelegate:

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

create MediaPlayer

Parameters
delegateAn object to the mediaPlayer observer: id<AgoraRtcMediaPlayerDelegate>.
Returns
id<AgoraMediaPlayerProtocol>

◆ 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
mediaPlayerid<AgoraMediaPlayerProtocol>
Returns
  • >0: The id of media player source instance.
  • < 0: Failure.

◆ getMediaPlayer:

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

getMediaPlayer

Parameters
mediaPlayerIdof 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
sound1The absolute path or URL address (including the filename extensions) of the file for the downbeat.
sound2The absolute path or URL address (including the filename extensions) of the file for the upbeats.
configThe 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
configThe 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
profileSets 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
configThe 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
delegateA pointer to the direct cdn streaming event handler: IDirectCdnStreamingEventHandler.
publishUrlThe url of the cdn used to publish the stream.
optionsThe direct cdn streaming media options: AgoraDirectCdnStreamingMediaOptions.
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.

◆ pushDirectCdnStreamingCustomVideoFrame:

- (int) pushDirectCdnStreamingCustomVideoFrame: (AgoraVideoFrame *_Nonnull)  frame

Push external video data

Parameters
frameThe reference to the video frame to send.
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 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
profileSets the sample rate, bitrate, encoding mode, and the number of channels. See AgoraAudioProfile.
scenarioSets the audio application scenarios. See AgoraAudioScenario.
Returns
  • 0: Success.
  • <0: Failure.

◆ setAdvancedAudioOptions:

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

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

Parameters
optionsThe AgoraAdvancedAudioOptions class, See the definition of AgoraAdvancedAudioOptions for details.
Returns
  • 0: Success
  • < 0: Failure

◆ isSecure

- (BOOL) isSecure

◆ 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
levelThe 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.

◆ takeSnapshot:uid:filePath:completion:

- (NSInteger) takeSnapshot: (NSString *_Nonnull)  channel
uid: (NSInteger)  uid
filePath: (NSString *_Nonnull)  filePath
completion: (id< AgoraSnapshotCallbackDelegate > _Nonnull)  snapshotDelegate 

◆ setLocalAccessPoint:

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

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

Parameters
configThe 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 whitelist; then, call this method to enable the cloud proxy and set the cloud proxy type with the proxyType parameter as AgoraUdpProxy(1), which is the cloud proxy for the UDP protocol.

After a successfully cloud proxy connection, the SDK triggers the [connectionChangedToState(AgoraConnectionStateConnecting, AgoraConnectionChangedSettingProxyServer)]([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
proxyTypeThe 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.

◆ enableContentInspect:config:

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

◆ enableFishCorrection:params:

- (int) enableFishCorrection: (BOOL)  enable
params: (AgoraFishCorrectionParams *_Nullable)  params 

Enable/ disable Fish Eye Correction and set fish eye parameters

Parameters
paramsfish eye function parameters enable: true enable fish eye function false disable fish eye function x_center, y_center: value in [0.4, 0.6] default x_center is 0.49, y_center is 0.48 scale_factor: value in [1, 5] default is 4.5 focal_length: value in [20, 40] default is 31 pol_focal_length: value in [20, 40] default is 31 ss[0~4] is the property of the fisheye mirror
Returns
  • 0: Success.
  • <0: Failure

◆ 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
channelIdThe channel id
uidThe user ID of the remote user to be bound with (local user)
Returns
  • 0: Success.
  • < 0: Failure.

◆ 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
tokenThe 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.
connectionAgoraRtcConnection by channelId and uid combine
delegateAgoraRtcEngineDelegate protocol.(Need a new object when called)
mediaOptionsAgoraRtcChannelMediaOptions Object.
joinSuccessBlockSame as 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:

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
tokenThe 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.
channelIdThe 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
userAccountThe 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
delegateAgoraRtcEngineDelegate protocol.
mediaOptionsThe 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
mediaOptionsThe channel media options: ChannelMediaOptions.
connectionAgoraRtcConnection 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
uidUser 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.
connectionAgoraRtcConnection 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
configThe local video encoder configuration, see #AgoraVideoEncoderConfiguration.
connectionAgoraRtcConnection 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 didJoinedOfUid event.

Parameters
remoteAgoraRtcVideoCanvas
connectionAgoraRtcConnection 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
uidUser id of the user whose video streams are received.
modeAgoraVideoRenderMode
mirrorAgoraVideoMirrorMode
connectionAgoraRtcConnection 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
uidID of the specified remote user.
muteDetermines whether to receive or stop receiving a specified video stream:
  • YES: Stop receiving the specified video stream.
  • NO: (Default) Receive the specified video stream.
connectionAgoraRtcConnection by channelId and uid combine
Returns
  • 0: Success.
  • < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

◆ enableDualStreamModeEx:enabled:streamConfig:connection:

- (int) enableDualStreamModeEx: (AgoraVideoSourceType sourceType
enabled: (BOOL)  enabled
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.

Parameters
sourceTypeThe video source type.
enabled
  • true: Enable the dual-stream mode.
  • false: (default) Disable the dual-stream mode.
streamConfigThe minor stream config
connectionAn output parameter which is used to control different connection instances.

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 before joining the channel.
Parameters
uidID of the remote user sending the video stream.
streamTypeThe video stream type: AgoraVideoStreamType.
connectionAgoraRtcConnection by channelId and uid combine
Returns
  • 0: Success.
  • < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

◆ pushExternalVideoFrame:connection:

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

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 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
frameVideo frame containing the SDK's encoded video data to be pushed: AgoraVideoFrame.
connectionAgoraRtcConnection by channelId and uid combine
Returns
  • YES: Success.
  • NO: 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
userAccountThe user account of the user. Ensure that you set this parameter.
connectionAgoraRtcConnection 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
uidThe user ID of the remote user. Ensure that you set this parameter.
connectionAgoraRtcConnection 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
connectionAgoraRtcConnection by channelId and uid combine
Returns
The connection state. See AgoraConnectionState.

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
      uidThe ID of the remote user.
      panThe 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
gainGain 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.
connectionAgoraRtcConnection 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
urlThe 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.
optionsThe options of the watermark image to be added. See WatermarkOptions.
connectionAgoraRtcConnection 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
connectionAgoraRtcConnection 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
streamIdID of the created data stream.
reliableSets 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.
orderedSets 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.
connectionAgoraRtcConnection 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
streamIdID of the created data stream.
configthe config of data stream.
connectionAgoraRtcConnection 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 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 didOccurStreamMessageErrorFromUid callback on the remote client.

Note
  • This method applies only to the Communication profile or to the hosts in the live interactive streaming profile. If an audience in the live interactive streaming profile calls this method, the audience role may be changed to a host.
  • Ensure that you have created the data stream using createDataStream before calling this method.
Parameters
streamIdID of the sent data stream returned in the createDataStream method.
dataSent data.
connectionAgoraRtcConnection by channelId and uid combine.
Returns
  • 0: Success.
  • < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

Property Documentation

◆ delegate

- (id<AgoraRtcEngineDelegate> _Nullable) delegate
readwritenonatomicweak

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.