Inherits <NSObject>.
Instance Methods | |
(int) | - joinChannelExByToken:channelId:uid:connectionId:delegate:mediaOptions:joinSuccess: |
(int) | - leaveChannelEx:connectionId:leaveChannelBlock: |
(int) | - setupRemoteVideoEx:connectionId: |
(int) | - setRemoteRenderModeEx:mode:connectionId: |
Core Methods | |
id< AgoraRtcEngineDelegate > _Nullable | delegate |
(int) | - joinChannelByToken:channelId:info:uid:joinSuccess: |
(int) | - joinChannelByToken:channelId:uid:mediaOptions:joinSuccess: |
(int) | - leaveChannel: |
(int) | - setChannelProfile: |
(int) | - setClientRole: |
(int) | - renewToken: |
(AgoraConnectionState) | - getConnectionState: |
(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: |
(int) | - setEnableSpeakerphone: |
(BOOL) | - isSpeakerphoneEnabled |
(int) | - setDefaultAudioRouteToSpeakerphone: |
(int) | - adjustRecordingSignalVolume: |
(int) | - muteLocalAudioStream: |
(int) | - muteRemoteAudioStream:mute: |
(int) | - muteAllRemoteAudioStreams: |
(int) | - setDefaultMuteAllRemoteAudioStreams: |
Core Video | |
(int) | - enableVideo |
(int) | - disableVideo |
(int) | - enableLocalVideo: |
(int) | - setVideoEncoderConfiguration: |
(int) | - setupLocalVideo: |
(int) | - setLocalRenderMode: |
(int) | - startPreview |
(int) | - stopPreview |
(int) | - muteLocalVideoStream: |
(int) | - muteAllRemoteVideoStreams: |
(int) | - setDefaultMuteAllRemoteVideoStreams: |
(int) | - muteRemoteVideoStream:mute: |
Audio Effect | |
(int) | - setLocalVoiceChanger: |
(int) | - setLocalVoiceReverbPreset: |
Audio Effect Playback | |
(int) | - preloadEffect:filePath: |
(int) | - playEffect:filePath:loopCount:pitch:pan:gain:publish: |
(int) | - playAllEffectsWithLoopCount:pitch:pan:gain:publish: |
(int) | - getEffectsVolume |
(int) | - setEffectsVolume: |
(int) | - setVolumeOfEffect:withVolume: |
(int) | - getVolumeOfEffect: |
(int) | - pauseEffect: |
(int) | - pauseAllEffects |
(int) | - resumeEffect: |
(int) | - resumeAllEffects |
(int) | - stopEffect: |
(int) | - stopAllEffects |
(int) | - unloadEffect: |
(int) | - unloadAllEffects |
Audio Mixing | |
(int) | - startAudioMixing:loopback:replace:cycle: |
(int) | - stopAudioMixing |
(int) | - pauseAudioMixing |
(int) | - resumeAudioMixing |
(int) | - adjustAudioMixingVolume: |
(int) | - adjustAudioMixingPublishVolume: |
(int) | - getAudioMixingPublishVolume |
(int) | - adjustAudioMixingPlayoutVolume: |
(int) | - getAudioMixingPlayoutVolume |
(int) | - getAudioMixingDuration |
(int) | - getAudioMixingCurrentPosition |
(int) | - setAudioMixingPosition: |
Miscellaneous Audio Control | |
(int) | - enableInEarMonitoring: |
(int) | - enableInEarMonitoring:includeAudioFilter: |
(int) | - setInEarMonitoringVolume: |
Dual Video Mode | |
(int) | - enableDualStreamMode: |
(int) | - setRemoteDefaultVideoStreamType: |
Data Steam | |
(int) | - createDataStream:reliable:ordered: |
(int) | - sendStreamMessage:data: |
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 |
(int) | - setAudioProfile:scenario: |
(int) | - sendCustomReportMessage:category:event:label:value: |
(int) | - setLogLevel: |
(NSString *_Nonnull) | + getSdkVersion |
(NSString *_Nonnull) | + getErrorDescription: |
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.
- (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:
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.
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.token | The token for authentication.
|
channelId | Unique channel name for the AgoraRTC session in the string format. The string length must be less than 64 bytes. Supported character scopes are:
|
info | (Optional) Additional information about the channel. This parameter can be set to nil or contain channel related information. Other users in the channel do not receive this message. |
uid | User ID. A 32-bit unsigned integer with a value ranging from 1 to (232-1). The uid must be unique. If a uid is not assigned (or set to 0), the SDK assigns and returns a uid in the callback. Your app must record and maintain the returned uid since the SDK does not do so. |
joinSuccessBlock | Same as didJoinChannel. We recommend you set this parameter as nil to use didJoinChannel .
|
- (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:
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.
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.token | The token for authentication.
|
channelId | Unique channel name for the AgoraRTC session in the string format. The string length must be less than 64 bytes. Supported character scopes are:
|
uid | User ID. A 32-bit unsigned integer with a value ranging from 1 to (232-1). The uid must be unique. If a uid is not assigned (or set to 0), the SDK assigns and returns a uid in the callback. Your app must record and maintain the returned uid since the SDK does not do so. |
mediaOptions | AgoraRtcChannelMediaOptions Object. |
joinSuccessBlock | Same as didJoinChannel. We recommend you set this parameter as nil to use didJoinChannel .
|
- (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.
didLeaveChannelWithStats
callback.leaveChannelBlock | This callback indicates that a user leaves a channel, and provides the statistics of the call in AgoraChannelStats. |
- (int) setChannelProfile: | (AgoraChannelProfile) | profile |
Sets the channel profile.
The SDK differentiates channel profiles and applies different optimization algorithms accordingly.
joinChannelByToken
. You cannot set the channel profile once you have joined the channel.profile | The channel profile: AgoraChannelProfile. |
- (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.
role | Role of the client: AgoraClientRole. |
- (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.
AgoraErrorCodeTokenExpired
(-109) error is reported. token | The new token. |
- (AgoraConnectionState) getConnectionState: | (unsigned int) | connectionId |
Gets the connection state of the SDK.
connectionId | An output parameter that is used to control different connection instances. |
- (int) enableWebSdkInteroperability: | (BOOL) | enabled |
enabled | Whether interoperability with the Agora Web SDK is enabled:
|
+ (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.
appId | App ID of your Agora project. |
delegate | AgoraRtcEngineDelegate. |
+ (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.
sharedEngineWithAppId
and this method is that this method enables you to specify the connection area.config | Configurations for the AgoraRtcEngineKit instance. For details, see AgoraRtcEngineConfig. |
delegate | AgoraRtcEngineDelegate. |
-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. + (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.
- (int) enableAudio |
Enables the audio.
The audio is enabled by default.
- (int) disableAudio |
Disables the audio.
- (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.
enabled | Determines whether to disable or re-enable the local audio function:
|
- (int) setAudioProfile: | (AgoraAudioProfile) | profile |
Sets the audio profile.
joinChannelByToken
.profile
as AgoraAudioProfileMusicHighQuality
(4).profile | The audio profile, such as the sample rate, bitrate, encoding mode, and the number of channels, see AgoraAudioProfile. |
- (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.
interval | Sets the time interval between two consecutive volume indications:
|
smooth | The smoothing factor that sets the sensitivity of the audio volume indicator. The value range is [0, 10]. The greater the value, the more sensitive the indicator. The recommended value is 3. |
- (int) setEnableSpeakerphone: | (BOOL) | enableSpeaker |
Enables/Disables the speakerphone temporarily. (iOS only)
When the audio route changes, the SDK triggers the didAudioRouteChanged callback.
You can call this method before, during, or after a call. However, Agora recommends calling this method only when you are in a channel to change the audio route temporarily.
setCategory(AVAudioSessionCategoryPlayAndRecord)
with options to configure the headset or speakerphone, so this method call applies to all audio playback in the system.enableSpeaker | Whether to set the speakerphone as the temporary audio route:
|
- (BOOL) isSpeakerphoneEnabled |
Checks whether the speakerphone is enabled. (iOS only)
YES
: The speakerphone is enabled, and the audio plays from the speakerphone.NO
: The speakerphone is not enabled, and the audio plays from devices other than the speakerphone. For example, the headset or earpiece. - (int) setDefaultAudioRouteToSpeakerphone: | (BOOL) | defaultToSpeaker |
Sets the default audio route. (iOS only)
Most mobile phones have two audio routes: An earpiece at the top, and a speakerphone at the bottom. The earpiece plays at a lower volume, and the speakerphone plays at a higher volume.
By setting the default audio route, you determine whether the audio playback comes through the earpiece or speakerphone when no external audio device is connected.
Depending on the scenario, Agora uses different default audio routes:
Call this method to change the default audio route before, during, or after a call. When the audio route changes, the SDK triggers the didAudioRouteChanged callback.
defaultToSpeaker | Whether to set the speakerphone as the default audio route:
|
- (int) adjustRecordingSignalVolume: | (NSInteger) | volume |
Adjusts the recording volume.
volume | Recording volume. The value ranges between 0 and 400:
|
- (int) muteLocalAudioStream: | (BOOL) | mute |
Stops or resumes sending the local audio stream.
mute | Whether to send or stop sending the local audio stream:
|
- (int) muteRemoteAudioStream: | (NSUInteger) | uid | |
mute: | (BOOL) | mute | |
Stops/Resumes receiving the audio 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.
uid | The ID of the specified user. |
mute | Whether to stop receiving the audio stream of the specified user:
|
- (int) muteAllRemoteAudioStreams: | (BOOL) | mute |
Stops/Resumes receiving all remote audio 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.
muteAllRemoteAudioStreams
(true) before joining a channel, the local user does not receive any audio stream after joining the channel.muteAllRemoteAudioStreams
(true) after joining a channel, the local use stops receiving any audio stream from any user in the channel, including any user who joins the channel after you call this method.muteAllRemoteAudioStreams
(true) after leaving a channel, the local user does not receive any audio stream the next time the user joins a channel.After you successfully call muteAllRemoteAudioStreams
(true), you can take the following actions:
muteAllRemoteAudioStreams
(false).uid
is the ID of the user whose audio stream you want to resume receiving.muteAllRemoteAudioStreams
stop taking effect if either of the following occurs:enableAudio
after muteAllRemoteAudioStreams
(true).disableAudio
after muteAllRemoteAudioStreams
(false).mute | Whether to stop receiving remote audio streams:
|
- (int) setDefaultMuteAllRemoteAudioStreams: | (BOOL) | mute |
joinChannelByToken
.Determines whether to receive all remote audio streams by default.
mute | Whether to receive remote audio streams by default:
|
- (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.
- (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).
- (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.
enableVideo
. Otherwise, this method may not work properly.enabled | Determines whether to disable or re-enable the local video, including the capturer, renderer, and sender:
|
- (int) setVideoEncoderConfiguration: | (AgoraVideoEncoderConfiguration *_Nonnull) | config |
Sets the video encoder configuration.
Each video encoder configuration corresponds to a set of video parameters, including the resolution, frame rate, bitrate, and video orientation.
The parameters specified in this method are the maximum values under ideal network conditions.
If the video engine cannot render the video using the specified parameters due to unreliable network conditions, the parameters further down the list are considered until a successful configuration is found.If you do not need to set the video encoder configuration after joining a channel, you can call this method before calling the enableVideo method to reduce the render time of the first video frame.
config | The local video encoder configuration, see AgoraVideoEncoderConfiguration. |
- (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
.
local | The local video view and settings. See AgoraRtcVideoCanvas. |
- (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.
mode | Sets the local display mode. See AgoraVideoRenderMode. |
- (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.
- (int) stopPreview |
Stops the local video preview and the video.
- (int) muteLocalVideoStream: | (BOOL) | mute |
Stops or resumes sending the local video stream.
mute | Determines whether to send or stop sending the local video stream:
|
- (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.
muteAllRemoteVideoStreams
(true) before joining a channel, the local user does not receive any video stream after joining the channel.muteAllRemoteVideoStreams
(true) 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.muteAllRemoteVideoStreams
(true) 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
(true), you can take the following actions:
muteAllRemoteVideoStreams
(false).uid
is the ID of the user whose video stream you want to resume receiving.muteAllRemoteVideoStreams
stop taking effect if either of the following occurs:enableVideo
after muteAllRemoteVideoStreams
(true).disableVideo
after muteAllRemoteVideoStreams
(false).mute | Whether to stop receiving remote video streams:
|
- (int) setDefaultMuteAllRemoteVideoStreams: | (BOOL) | mute |
joinChannelByToken
.Determines whether to receive all remote video streams by default.
mute | Whether to receive remote video streams by default:
|
- (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.
uid | ID of the specified remote user. |
mute | Whether to stop receiving the video stream of the specified user:
|
- (int) setLocalVoiceChanger: | (AgoraAudioVoiceChanger) | voiceChanger |
Sets the local voice changer option.
This method can be used to set the local voice effect for users in a communication channel or broadcasters in a live broadcast channel. Voice changer options include the following groups of voice effects:
AgoraAudioVoiceChanger*
: Changes the local voice to an old man, a little boy, or the Hulk. Applies to the voice talk scenario.AgoraAudioVoiceBeauty*
: Beautifies the local voice by making it sound more vigorous, resounding, or adding spacial resonance. Applies to the voice talk and singing scenario.AgoraAudioGeneralBeautyVoice*
: Adds gender-based beautification effect to the local voice. Applies to the voice talk scenario.profile
parameter in setAudioProfile as AgoraAudioProfileMusicHighQuality
(4) or AgoraAudioProfileMusicHighQualityStereo
(5).voiceChanger | The local voice changer option. See AgoraAudioVoiceChanger. |
voiceChanger
. - (int) setLocalVoiceReverbPreset: | (AgoraAudioReverbPreset) | reverbPreset |
Sets the local voice reverberation option.
This method sets the local voice reverberation for users in a communication channel or broadcasters in a live-broadcast channel. After this method call succeeds, all users in the channel can hear the voice with reverberation.
AgoraAudioReverbPresetFx
, ensure that you set profile in setAudioProfile as AgoraAudioProfileMusicHighQuality
(4) or AgoraAudioProfileMusicHighQualityStereo
(5). Otherwise, this method call does not take effect.reverbPreset | The local voice reverberation option. To achieve better voice effects, Agora recommends the enumerations beginning with AgoraAudioReverbPresetFx . See AgoraAudioReverbPreset. |
reverbPrest
. - (int) preloadEffect: | (int) | soundId | |
filePath: | (NSString *_Nonnull) | filePath | |
Preloads a specified audio effect.
This method preloads only one specified audio effect into the memory each time it is called. To preload multiple audio effects, call this method multiple times.
After preloading, you can call playEffect to play the preloaded audio effect or call playAllEffects to play all the preloaded audio effects.
soundId | The ID of the audio effect. |
filePath | The absolute path of the local audio effect file or the URL of the online audio effect file. Supported audio formats: mp3, mp4, m4a, aac, 3gp, mkv and wav. |
- (int) playEffect: | (int) | soundId | |
filePath: | (NSString *_Nonnull) | filePath | |
loopCount: | (NSInteger) | loopCount | |
pitch: | (double) | pitch | |
pan: | (double) | pan | |
gain: | (NSInteger) | gain | |
publish: | (BOOL) | publish | |
Plays a specified audio effect.
With this method, you can set the loop count, pitch, pan, and gain of the audio effect file and whether the remote user can hear the audio effect.
To play multiple audio effect files simultaneously, call this method multiple times with different soundIds and filePaths. We recommend playing no more than three audio effect files at the same time.
When the audio effect file playback is finished, the SDK triggers the rtcEngineDidAudioEffectFinish callback.
soundId | ID of the specified audio effect. Each audio effect has a unique ID. If the audio effect is preloaded into the memory through the preloadEffect method, ensure that the soundId value is set to the same value as in preloadEffect. |
filePath | Specifies the absolute path (including the suffixes of the filename) to the local audio effect file or the URL of the online audio effect file, for example, /var/mobile/Containers/Data/audio.mp4 . Supported audio formats: mp3, mp4, m4a, aac, 3gp, mkv and wav. |
loopCount | Sets the number of times the audio effect loops:
|
pitch | Sets the pitch of the audio effect. The value ranges between 0.5 and 2. The default value is 1 (no change to the pitch). The lower the value, the lower the pitch. |
pan | Sets the spatial position of the audio effect. The value ranges between -1.0 and 1.0.
|
gain | Sets the volume of the audio effect. The value ranges between 0.0 and 100.0 (default). The lower the value, the lower the volume of the audio effect. |
publish | Sets whether or not to publish the specified audio effect to the remote stream:
|
- (int) playAllEffectsWithLoopCount: | (NSInteger) | loopCount | |
pitch: | (double) | pitch | |
pan: | (double) | pan | |
gain: | (NSInteger) | gain | |
publish: | (BOOL) | publish | |
Plays all audio effects.
After calling preloadEffect multiple times to preload multiple audio effects into the memory, you can call this method to play all the specified audio effects for all users in the channel.
loopCount | The number of times the audio effect loops:
|
pitch | The pitch of the audio effect. The value ranges between 0.5 and 2.0. The default value is 1.0 (original pitch). The lower the value, the lower the pitch. |
pan | The spatial position of the audio effect. The value ranges between -1.0 and 1.0:
|
gain | The volume of the audio effect. The value ranges between 0 and 100. The default value is 100 (original volume). The lower the value, the lower the volume of the audio effect. |
publish | Sets whether to publish the audio effect to the remote:
|
- (int) getEffectsVolume |
Gets the volume of audio effects.
- (int) setEffectsVolume: | (NSInteger) | volume |
Sets the volume of audio effects.
volume | The volume of audio effects. The value ranges between 0 and 100 (original volume). |
- (int) setVolumeOfEffect: | (int) | soundId | |
withVolume: | (int) | volume | |
Sets the volume of the specified audio effect.
soundId | The ID of the audio effect. |
volume | The volume of the specified audio effect. The value ranges between 0 and 100 (original volume). |
- (int) getVolumeOfEffect: | (int) | soundId |
Gets the volume of the specified audio effect.
soundId | The ID of the audio effect. |
- (int) pauseEffect: | (int) | soundId |
Pauses playing a specific audio effect.
soundId | ID of the audio effect. Each audio effect has a unique ID. |
- (int) pauseAllEffects |
Pauses playing all audio effects.
- (int) resumeEffect: | (int) | soundId |
Resumes playing the specified audio effect.
soundId | The ID of the audio effect. |
- (int) resumeAllEffects |
Resumes playing all audio effects.
- (int) stopEffect: | (int) | soundId |
Stops playing a specific audio effect.
soundId | The ID of the audio effect. |
- (int) stopAllEffects |
Stops playing all audio effects.
- (int) unloadEffect: | (int) | soundId |
Releases a specific preloaded audio effect from the memory.
soundId | The ID of the audio effect. |
- (int) unloadAllEffects |
Release all preloaded audio effects from the memory.
soundId | The ID of the audio effect. |
- (int) startAudioMixing: | (NSString *_Nonnull) | filePath | |
loopback: | (BOOL) | loopback | |
replace: | (BOOL) | replace | |
cycle: | (NSInteger) | cycle | |
Starts audio mixing.
This method mixes the specified local audio file with the audio stream from the microphone, or replaces the microphone’s audio stream with the specified local audio file.
You can choose whether the other users can hear the local audio playback and specify the number of playback loops.
This method also supports online music playback.
A successful method call triggers the audioMixingStateChanged callback on the local client to report the AgoraAudioMixingStateTypePlaying
state.
When the audio mixing file playback finishes, the SDK triggers the audioMixingStateChanged
callback on the local client to report the AgoraAudioMixingStateTypeStopped
state.
audioMixingStateChanged
callback reports the AgoraAudioMixingErrorTypeTooFrequentlyCall
(702) error. filePath | Specifies the absolute path (including the suffixes of the filename) of the local or online audio file to be mixed. For example, /var/mobile/Containers/Data/audio.mp4 . Supported audio formats: MP3, MP4, M4A, AAC, 3GP, MKV, and WAV. |
loopback | Sets which user can hear the audio mixing:
|
replace | Sets the audio mixing content:
|
cycle | Sets the number of playback loops:
|
- (int) stopAudioMixing |
Stops audio mixing.
Call this method when the user is in a channel.
- (int) pauseAudioMixing |
Pauses audio mixing.
Call this method when the user is in a channel.
- (int) resumeAudioMixing |
Resumes audio mixing.
Call this API when the user is in a channel.
- (int) adjustAudioMixingVolume: | (NSInteger) | volume |
Adjusts the volume of audio mixing.
Call this API when the user is in a channel.
volume | Audio mixing volume. The value ranges between 0 and 100 (default). 100 is the original volume. |
- (int) adjustAudioMixingPublishVolume: | (NSInteger) | volume |
Adjusts the audio mixing volume for publishing (for remote users).
volume | Audio mixing volume for publishing. The value ranges between 0 and 100 (default). |
- (int) getAudioMixingPublishVolume |
Retrieves the audio mixing volume for publishing. This method helps troubleshoot audio volume related issues.
- (int) adjustAudioMixingPlayoutVolume: | (NSInteger) | volume |
Adjusts the audio mixing volume for local playback.
volume | Audio mixing volume for local playback. The value ranges between 0 and 100 (default). |
- (int) getAudioMixingPlayoutVolume |
Retrieves the audio mixing volume for local playback. This method helps troubleshoot audio volume related issues.
- (int) getAudioMixingDuration |
Gets the duration of audio mixing.
Call this API when the user is in a channel.
- (int) getAudioMixingCurrentPosition |
Gets the playback position of the audio.
Call this API when the user is in a channel.
- (int) setAudioMixingPosition: | (NSInteger) | pos |
Sets the playback position of the audio mixing file.
Sets the playback starting position of the audio mixing file instead of playing it from the beginning.
pos | Integer. The playback starting position of the audio mixing file (ms). |
- (int) enableInEarMonitoring: | (BOOL) | enabled |
Enables in-ear monitoring.
enabled | Determines whether to enable in-ear monitoring.
|
- (int) enableInEarMonitoring: | (BOOL) | enabled | |
includeAudioFilter: | (BOOL) | includeAudioFilter | |
Enables in-ear monitoring.
enabled | Determines whether to enable in-ear monitoring.
|
includeAudioFilter | Determines whether to include audio filters, for example, voice changer or reverberation, in the in-ear monitoring.
|
- (int) setInEarMonitoringVolume: | (NSInteger) | volume |
Sets the volume of the in-ear monitoring.
volume | The volume of the in-ear monitor, ranging from 0 to 100. The default value is 100. |
- (int) enableDualStreamMode: | (BOOL) | enabled |
Enables or disables the dual video stream mode.
enabled |
|
- (int) setRemoteDefaultVideoStreamType: | (AgoraVideoStreamType) | streamType |
Sets the default stream type of the remote video if the remote user has enabled the dual-stream mode.
streamType | The default video stream type: AgoraVideoStreamType. |
- (void) setExternalVideoSource: | (BOOL) | enable | |
useTexture: | (BOOL) | useTexture | |
pushMode: | (BOOL) | pushMode | |
Sets the external video source.
Call this API before enableVideo
or startPreview
.
enable | Determines whether to enable the 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.
useTexture | Determines whether to use textured video data.
|
pushMode | Determines whether the external video source needs to call pushExternalVideoFrame to send the video frame to the Agora SDK:
|
- (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.
frame | Video frame containing the SDK's encoded video data to be pushed: AgoraVideoFrame. |
YES
: Success.NO
: Failure. - (int) setExternalAudioSource: | (BOOL) | enabled | |
sampleRate: | (NSInteger) | sampleRate | |
channels: | (NSInteger) | channels | |
Sets the external audio source.
Call this method before joining the channel.
enabled | Whether to enable the external audio source:
|
sampleRate | Sample rate (Hz) of the external audio source: 8000 , 16000 , 32000 , 44100 , or 48000 Hz. |
channels | The number of external audio source channels. You can set it as 1 (mono channel) or 2 (dual channel). |
- (int) setExternalAudioSource: | (BOOL) | enabled | |
sampleRate: | (NSInteger) | sampleRate | |
channels: | (NSInteger) | channels | |
sourceNumber: | (NSInteger) | sourceNumber | |
Sets the external audio source.
Call this method before joining the channel.
enabled | Whether to enable the external audio source:
|
sampleRate | Sample rate (Hz) of the external audio source: 8000 , 16000 , 32000 , 44100 , or 48000 Hz. |
channels | The number of external audio source channels. You can set it as 1 (mono channel) or 2 (dual channel). |
sourceNumber | The number of the external audio sources. Ensure that the number is greater than 0. |
- (int) pushExternalAudioFrameRawData: | (void *_Nonnull) | data | |
sourceId: | (NSInteger) | sourceId | |
timestamp: | (NSTimeInterval) | timestamp | |
Pushes the external raw audio frame to the Agora SDK for encoding.
data | External audio data to be pushed. |
sourceId | ID of the external audio source. |
timestamp | The timestamp of the external audio frame in milliseconds. It is mandatory. You can use this parameter for the following purposes:
|
- (int) pushExternalAudioFrameSampleBuffer: | (CMSampleBufferRef _Nonnull) | sampleBuffer |
Pushes the external CMSampleBuffer audio frame to the SDK for encoding.
sampleBuffer | Sample buffer for the push. |
- (int) setRecordingAudioFrameParametersWithSampleRate: | (NSInteger) | sampleRate | |
channel: | (NSInteger) | channel | |
mode: | (AgoraAudioRawFrameOperationMode) | mode | |
samplesPerCall: | (NSInteger) | samplesPerCall | |
Sets the audio recording format for the onRecordAudioFrame callback.
sampleRate | The sample rate (Hz) of the audio frame. You can set it as 8000 , 16000 , 32000 , 44100 , or 48000 . |
channel | The number of audio channels of the audio frame. You can set it as 1 (mono channel) or 2 (dual channel). |
mode | Use mode of the audio frame. See AgoraAudioRawFrameOperationMode. |
samplesPerCall | The number of samples of the audio frame. For CDN live streaming, Agora recommends setting it as 1024 . |
onRecordAudioFrame
callback according to the sample interval (in seconds). The sample interval = samplesPerCall/(sampleRate × channel)
. Ensure that the sample interval is no less than 0.01 second.- (int) setPlaybackAudioFrameParametersWithSampleRate: | (NSInteger) | sampleRate | |
channel: | (NSInteger) | channel | |
mode: | (AgoraAudioRawFrameOperationMode) | mode | |
samplesPerCall: | (NSInteger) | samplesPerCall | |
Sets the audio frame format for the onPlaybackAudioFrame callback.
sampleRate | The sample rate (Hz) of the audio frame. You can set it as 8000 , 16000 , 32000 , 44100 , or 48000 . |
channel | The number of audio channels of the audio frame. You can set it as 1 (mono channel) or 2 (dual channel). |
mode | Use mode of the audio frame. See AgoraAudioRawFrameOperationMode. |
samplesPerCall | The number of samples of the audio frame. It is usually set as 1024 for the CDN live streaming. |
onPlaybackAudioFrame
callback according to the sample interval (in seconds). The sample interval = samplesPerCall/(sampleRate × channel)
. Ensure that the sample interval is no less than 0.01 second.- (int) setMixedAudioFrameParametersWithSampleRate: | (NSInteger) | sampleRate | |
channel: | (NSInteger) | channel | |
samplesPerCall: | (NSInteger) | samplesPerCall | |
Sets the audio frame format for the onPlaybackAudioFrameBeforeMixing callback.
sampleRate | The sample rate (Hz) of the audio frame. You can set it as 8000 , 16000 , 32000 , 44100 , or 48000 . |
channel | The number of audio channels of the audio frame. You can set it as 1 (mono channel) or 2 (dual channel). |
samplesPerCall | The number of samples of the audio frame. It is usually set as 1024 for the CDN live streaming. |
onPlaybackAudioFrameBeforeMixing
callback according to the sample interval (in seconds). The sample interval = samplesPerCall/(sampleRate × channel)
. Ensure that the sample interval is no less than 0.01 second.- (int) setPlaybackAudioFrameBeforeMixingParametersWithSampleRate: | (NSInteger) | sampleRate | |
channel: | (NSInteger) | channel | |
Sets the audio frame format for the onPlaybackAudioFrameBeforeMixing callback.
sampleRate | The sample rate (Hz) of the audio frame. You can set it as 8000 , 16000 , 32000 , 44100 , or 48000 . |
channel | The number of audio channels of the audio frame. You can set it as 1 (mono channel) or 2 (dual channel). |
- (int) createDataStream: | (NSInteger *_Nonnull) | streamId | |
reliable: | (BOOL) | reliable | |
ordered: | (BOOL) | ordered | |
Creates a data stream.
Each user can create up to five data streams during the lifecycle of the AgoraRtcEngineKit
.
reliable
and ordered
parameters to YES
or NO
. Do not set one as YES
and the other as NO
.streamId | ID of the created data stream. |
reliable | Sets whether or not the recipients are guaranteed to receive the data stream from the sender within five seconds:
|
ordered | Sets whether or not the recipients receive the data stream in the sent order:
|
- (int) sendStreamMessage: | (NSInteger) | streamId | |
data: | (NSData *_Nonnull) | data | |
Sends data stream messages to all users in a channel.
The SDK has the following restrictions on this method:
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.
streamId | ID of the sent data stream returned in the createDataStream method. |
data | Sent data. |
- (int) switchCamera |
Switches between the front and rear cameras.
- (BOOL) setAudioFrameDelegate: | (id< AgoraAudioFrameDelegate > _Nullable) | delegate |
Registers an audio frame delegate.
joinChannelByToken
.delegate | AgoraAudioFrameDelegate object. To cancel the registration, specify nil for this parameter. |
- (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**
joinChannelByToken
method.metadataDataSource | The AgoraMediaMetadataDataSource protocol. |
type | The metadata type. See AgoraMetadataType. Currently, the SDK supports video metadata only. |
- (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**
joinChannelByToken
method.metadataDelegate | The AgoraMediaMetadataDelegate protocol. |
type | The metadata type. See AgoraMetadataType. Currently, the SDK supports video metadata only. |
+ (NSString * _Nonnull) getSdkVersion |
Gets the Agora SDK version.
+ (NSString* _Nonnull) getErrorDescription: | (NSInteger) | error |
Gets the warning or error description.
error | The warning or error code. |
- (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.
App Sandbox/Library/caches/agorasdk.log
App Sandbox/Library/Logs/agorasdk.log
, for example /Users/<username>/Library/Containers/<App Bundle Identifier>/Data/Library/Logs/agorasdk.log
.~/Library/Logs/agorasdk.log
.filePath | Absolute path of the log file. The string of the log file is in UTF-8 code. |
- (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
.
filter | Log filter level: AgoraLogFilter. |
- (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.
- (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.
callId | The call ID retrieved from the getCallId method. |
rating | The rating of the call between 1 (the lowest score) to 5 (the highest score). If you set a value out of this range, the AgoraErrorCodeInvalidArgument(-2) error occurs. |
description | (Optional) The description of the rating. The string length must be less than 800 bytes. |
callId
is invalid.- (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.
callId | The call ID retrieved from the getCallId method. |
description | (Optional) The description of the complaint. The string length must be less than 800 bytes. |
callId
is invalid.- (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.
lastmileProbeTestResult
callback. Otherwise, the callback may be interrupted.config | The configurations for the last-mile network probe test. See AgoraLastmileProbeConfig. |
- (int) stopLastmileProbeTest |
Stops the last-mile network probe test.
- (int) setAudioProfile: | (AgoraAudioProfile) | profile | |
scenario: | (AgoraAudioScenario) | scenario | |
Sets the audio parameters and application scenarios.
joinChannelByToken
.profile
as AgoraAudioProfileMusicHighQuality
(4) and scenario
as AgoraAudioScenarioGameStreaming
(3). profile | Sets the sample rate, bitrate, encoding mode, and the number of channels. See AgoraAudioProfile. |
scenario | Sets the audio application scenarios. See AgoraAudioScenario. |
- (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.
- (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.
level | The log level:
|
- (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.
You can call this method multiple times to join multiple channels.
token | The token for authentication.
|
channelId | Unique channel name for the AgoraRTC session in the string format. The string length must be less than 64 bytes. Supported character scopes are:
|
uid | User ID. A 32-bit unsigned integer with a value ranging from 1 to (232-1). The uid must be unique. If a uid is not assigned (or set to 0), the SDK assigns and returns a uid in the callback. Your app must record and maintain the returned uid since the SDK does not do so. |
connectionId | pointer to connection ID (out param). |
delegate | AgoraRtcEngineDelegate protocol. |
mediaOptions | AgoraRtcChannelMediaOptions Object. |
joinSuccessBlock | Same as didJoinChannel. We recommend you set this parameter as nil to use didJoinChannel .
|
Provided by category AgoraRtcEngineKit(Ex).
- (int) leaveChannelEx: | (NSString *_Nonnull) | channelId | |
connectionId: | (unsigned int) | connectionId | |
leaveChannelBlock: | (void(^)(AgoraChannelStats *_Nonnull stat)) | leaveChannelBlock | |
Leaves the channel by ID.
channelId | channel ID |
connectionId | connection ID |
leaveChannelBlock | This callback indicates that a user leaves a channel, and provides the statistics of the call in AgoraChannelStats. |
Provided by category AgoraRtcEngineKit(Ex).
- (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, you can set the uid after receiving the didJoinedOfUid event.
remote | AgoraRtcVideoCanvas |
connectionId | connection ID. |
Provided by category AgoraRtcEngineKit(Ex).
- (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.
uid | User id of the user whose video streams are received. |
mode | AgoraVideoRenderMode |
connectionId | connection ID. |
Provided by category AgoraRtcEngineKit(Ex).
|
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.