Agora RTC Objective-C API Reference  Refactor
Instance Methods
AgoraRtcEngineKit Class Reference

Inherits <NSObject>.

Instance Methods

(int) - joinChannelExByToken:channelId:uid:connectionId:delegate:mediaOptions:joinSuccess:
 
(int) - updateChannelExWithMediaOptions:connectionId:
 
(int) - muteRemoteAudioStreamEx:mute:connectionId:
 
(int) - setVideoEncoderConfigurationEx:connectionId:
 
(int) - setupRemoteVideoEx:connectionId:
 
(int) - setRemoteRenderModeEx:mode:connectionId:
 
(int) - muteRemoteVideoStreamEx:mute:connectionId:
 
(BOOL) - pushExternalVideoFrame:connectionId:
 

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) - renewToken:
 
(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:
 

Core Video


(int) - enableVideo
 
(int) - disableVideo
 
(int) - enableLocalVideo:
 
(int) - setupLocalVideo:
 
(int) - setLocalRenderMode:
 
(int) - startPreview
 
(int) - stopPreview
 
(int) - muteLocalVideoStream:
 
(int) - muteAllRemoteVideoStreams:
 
(int) - setDefaultMuteAllRemoteVideoStreams:
 
(int) - muteRemoteVideoStream:mute:
 

Miscellaneous Audio Control


(int) - enableInEarMonitoring:
 
(int) - enableInEarMonitoring:includeAudioFilter:
 
(int) - setInEarMonitoringVolume:
 

Dual Video Mode


(int) - enableDualStreamMode:
 
(int) - setRemoteDefaultVideoStreamType:
 

External Media Source


(void) - setExternalVideoSource:useTexture:pushMode:
 
(BOOL) - pushExternalVideoFrame:
 
(int) - setExternalAudioSource:sampleRate:channels:
 
(int) - setExternalAudioSource:sampleRate:channels:sourceNumber:
 
(int) - setRecordingAudioFrameParametersWithSampleRate:channel:mode:samplesPerCall:
 
(int) - setPlaybackAudioFrameParametersWithSampleRate:channel:mode:samplesPerCall:
 
(int) - setMixedAudioFrameParametersWithSampleRate:channel:samplesPerCall:
 
(int) - setPlaybackAudioFrameBeforeMixingParametersWithSampleRate:channel:
 

Camera Control


(int) - switchCamera
 

Watermark


(BOOL) - setAudioFrameDelegate:
 

Media Metadata


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

Miscellaneous Methods


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

Deprecated Methods


(int) - setAudioProfile:scenario:
 

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.

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

◆ 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 

Initializes the Agora SDK service with config.

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

Parameters
configRtcEngine config info.
delegateAgoraRtcEngineDelegate.
Returns
An AgoraRtcEngineKit object.

◆ 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 parameters and application scenarios.

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
profileThe sample rate, bitrate, encoding mode, and the number of channels, see AgoraAudioProfile.
scenarioThe audio application scenarios, see AgoraAudioScenario.
Returns
  • 0: Success.
  • <0: Failure.

◆ enableAudioVolumeIndication:smooth:

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

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. We recommend setting this parameter to a value larger than 200 (included).
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.

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

- (int) setLocalRenderMode: (AgoraVideoRenderMode)  mode

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

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

◆ enableInEarMonitoring:

- (int) enableInEarMonitoring: (BOOL)  enabled

Enables in-ear monitoring.

Note
This method applies to iOS only.
Parameters
enabledDetermines whether to enable in-ear monitoring.
  • YES: Enable in-ear monitoring.
  • NO: Disable in-ear monitoring.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableInEarMonitoring:includeAudioFilter:

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

Enables in-ear monitoring.

Note
This method applies to iOS only.
Parameters
enabledDetermines whether to enable in-ear monitoring.
  • YES: Enable in-ear monitoring.
  • NO: Disable in-ear monitoring.
includeAudioFilterDetermines whether to include audio filters, for example, voice changer or reverberation, in the in-ear monitoring.
  • YES: Include audio filter in-ear monitoring.
  • NO: No audio filter in-ear monitoring. This parameter is ignored when enabled is set to NO.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setInEarMonitoringVolume:

- (int) setInEarMonitoringVolume: (NSInteger)  volume

Sets the volume of the in-ear monitoring.

Note
This method applies to iOS only.
Parameters
volumeThe volume of the in-ear monitor, ranging from 0 to 100. 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.

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

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

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.
pushModeDetermines whether the external video source needs to call pushExternalVideoFrame to send the video frame to the Agora SDK:
  • YES: Use the push mode.
  • NO: Use the pull mode (not supported yet).

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

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

◆ setExternalAudioSource:sampleRate:channels:sourceNumber:

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

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.

◆ 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
numberOfChannelsThe number of channels contained in the onPlaybackAudioFrameBeforeMixing callback.
  • 1: Mono.
  • 2: Stereo.
sampleRateHzThe sample rate(Hz) contained in the onPlaybackAudioFrameBeforeMixing callback. You can set it as 8000, 16000, 32000, 44100, or 48000.
Returns
  • 0: Success.
  • < 0: Failure.

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

◆ setAudioFrameDelegate:

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

register & unregister the player audio observer

Parameters
observerobserver object, pass nil to unregister
Returns
int <= 0 On behalf of an error, the value corresponds to one of PLAYER_ERROR

◆ setMediaMetadataDataSource:withType:

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

Sets the data source of the metadata. You need to implement the [AgoraMediaMetadataDataSource](AgoraMediaMetadataDataSource) protocol and specify the type of metadata in this method. Use this method with the [setMediaMetadataDelegate]([AgoraRtcEngineKit setMediaMetadataDelegate:withType:]) method to add synchronized metadata in the video stream. You can create more diversified live broadcast interactions, such as sending shopping links, digital coupons, and online quizzes. Note**

  • Call this method before the [joinChannelByToken]([AgoraRtcEngineKit joinChannelByToken:channelId:info:uid:joinSuccess:]) method.
  • This method applies to the live broadcast channel profile only.
    Parameters
    metadataDataSourceThe AgoraMediaMetadataDataSource protocol.
    typeThe metadata type. See [AgoraMetadataType](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]([AgoraRtcEngineKit joinChannelByToken:channelId:info:uid:joinSuccess:]) method.
  • This method applies to the live broadcast channel profile only.
    Parameters
    metadataDelegateThe AgoraMediaMetadataDelegate protocol.
    typeThe metadata type. See [AgoraMetadataType](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 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 level to WARNING, you see the logs within levels CRITICAL, ERROR, and WARNING.

Parameters
filterLog filter level: AgoraLogFilter.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getCallId

- (NSString * _Nullable) getCallId

Gets the current call ID.

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

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

Returns
The call ID if the method call is successful.

◆ rate:rating:description:

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

Allows a user to rate the call.

It is usually called after the call ends.

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

◆ setAudioProfile:scenario:

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

Sets the audio parameters and application scenarios.

Deprecated:
From v2.7.1_fury. Scenario is set in initialize(const RtcEngineContext& context), Setting audio profile using setAudioProfile(int profile).
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
profileThe sample rate, bitrate, encoding mode, and the number of channels, see AgoraAudioProfile.
scenarioThe audio application scenarios, see AgoraAudioScenario.
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 

◆ setLogLevel:

- (int) setLogLevel: (AgoraLogLevel)  level

◆ joinChannelExByToken:channelId:uid:connectionId:delegate:mediaOptions:joinSuccess:

- (int) joinChannelExByToken: (NSString *_Nullable)  token
channelId: (NSString *_Nonnull)  channelId
uid: (NSUInteger)  uid
connectionId: (unsigned int *)  connectionId
delegate: (id< AgoraRtcEngineDelegate > _Nullable)  delegate
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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
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.
connectionIdpointer to connection ID, out param
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).

◆ updateChannelExWithMediaOptions:connectionId:

- (int) updateChannelExWithMediaOptions: (AgoraRtcChannelMediaOptions *_Nonnull)  mediaOptions
connectionId: (unsigned int)  connectionId 

Updates the channel media options after joining the channel.

Parameters
mediaOptionsThe channel media options: ChannelMediaOptions.
connectionIdconnection ID
Returns
  • 0: Success.
  • < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

◆ muteRemoteAudioStreamEx:mute:connectionId:

- (int) muteRemoteAudioStreamEx: (NSUInteger)  uid
mute: (BOOL)  mute
connectionId: (unsigned int)  connectionId 

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.
connectionIdconnection ID.
Returns
* 0: Success. <0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

◆ setVideoEncoderConfigurationEx:connectionId:

- (int) setVideoEncoderConfigurationEx: (AgoraVideoEncoderConfiguration *_Nonnull)  config
connectionId: (unsigned int)  connectionId 

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.
connectionIdconnection ID.
Returns
  • 0: Success.
  • < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

◆ setupRemoteVideoEx:connectionId:

- (int) setupRemoteVideoEx: (AgoraRtcVideoCanvas *_Nonnull)  remote
connectionId: (unsigned int)  connectionId 

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, set it later when the application receives the [userJoinedBlock]([AgoraRtcEngineKit userJoinedBlock:]) event. If the Video Recording function is enabled, the Video Recording Service joins the channel as a dumb client, which means other clients will also receive the [didJoinedOfUid]([AgoraRtcEngineDelegate rtcEngine:didJoinedOfUid:elapsed:]) event. Your application should not bind it with the view, because it does not send any video stream. If your application cannot recognize the dumb client, bind it with the view when the [firstRemoteVideoDecodedOfUid]([AgoraRtcEngineDelegate rtcEngine:firstRemoteVideoDecodedOfUid:size:elapsed:]) event is triggered. To unbind the user with the view, set the view to null. After the user has left the channel, the SDK unbinds the remote user.

Parameters
remoteAgoraRtcVideoCanvas
connectionIdconnection ID.
Returns
* 0: Success. <0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

◆ setRemoteRenderModeEx:mode:connectionId:

- (int) setRemoteRenderModeEx: (NSUInteger)  uid
mode: (AgoraVideoRenderMode)  mode
connectionId: (unsigned int)  connectionId 

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
connectionIdconnection ID.
Returns
* 0: Success. <0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

◆ muteRemoteVideoStreamEx:mute:connectionId:

- (int) muteRemoteVideoStreamEx: (NSUInteger)  uid
mute: (BOOL)  mute
connectionId: (unsigned int)  connectionId 

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.
connectionIdconnection ID.
Returns
  • 0: Success.
  • < 0: Failure.

Provided by category AgoraRtcEngineKit(Ex).

◆ pushExternalVideoFrame:connectionId:

- (BOOL) pushExternalVideoFrame: (AgoraVideoFrame *_Nonnull)  frame
connectionId: (unsigned int)  connectionId 

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.
connectionIdconnection ID.
Returns
  • YES: Success.
  • NO: Failure.

Provided by category AgoraRtcEngineKit(Ex).

◆ sendCustomReportMessageEx:category:event:label:value:connectionId:

- (int) sendCustomReportMessageEx: (NSString *_Nullable)  messageId
category: (NSString *_Nullable)  category
event: (NSString *_Nullable)  event
label: (NSString *_Nullable)  label
value: (NSInteger)  value
connectionId: (unsigned int)  connectionId 

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.