AgoraRtcEngineKit Class Reference
Inherits from | NSObject |
---|---|
Declared in | AgoraRtcEngineKit.h |
Overview
The AgoraRtcEngineKit class provides all methods invoked by your app.
Agora provides ensured quality of experience (QoE) for worldwide Internet-based voice and video communications through a virtual global network optimized for real-time web and mobile-to-mobile apps.
AgoraRtcEngineKit is the basic interface class of the Agora SDK. Creating an AgoraRtcEngineKit object and then calling the methods of this object enables the use of the Agora SDK’s communication functionality.
Core Service
+ sharedEngineWithAppId:delegate:
Initializes the AgoraRtcEngineKit object.
+ (instancetype _Nonnull)sharedEngineWithAppId:(NSString *_Nonnull)appId delegate:(id<AgoraRtcEngineDelegate> _Nullable)delegate
Parameters
appId |
App ID issued to the application developers by Agora. Apply for a new one from Agora if the key is missing in your kit. Each project is assigned a unique App ID. The App ID identifies your project and organization in the joinChannelByToken method to access the Agora Global Network, and enable one-to-one or one-to-more communication or live-broadcast sessions using a unique channel name for your App ID. |
---|---|
delegate |
Return Value
An object of the AgoraRtcEngineKit class.
Discussion
Call this method to initialize the service before using AgoraRtcEngineKit.
Warning: Only users with the same App ID can call each other.
Warning: 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.
Declared In
AgoraRtcEngineKit.h
+ destroy
Destroys the RtcEngine instance and releases all resources used by the Agora SDK.
+ (void)destroy
Discussion
This method is useful for apps that occasionally make voice or video calls, to free up resources for other operations when not making calls.
Once the app calls this method to release the created RtcEngine instance, no other methods in the SDK can be used and no callbacks can occur. To start communications again, initialize sharedEngineWithappId to establish a new AgoraRtcEngineKit instance.
Note:
- Call this method in the subthread.
- This method call is synchronous. The result returns after the AgoraRtcEngineKit object resources are released. The app should not call this interface in the callback generated by the SDK. Otherwise, the SDK must wait for the callback to return before it can reclaim the related object resources, causing a deadlock.
Declared In
AgoraRtcEngineKit.h
– setChannelProfile:
Sets the channel profile.
- (int)setChannelProfile:(AgoraChannelProfile)profile
Parameters
profile |
Channel profile: AgoraChannelProfile. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
The SDK needs to know the application scenario to set the appropriate channel profile to apply different optimization methods.
The Agora Native SDK supports the following channel profiles:
- Communication
- Live Broadcast
- Gaming (for the Agora Gaming SDK only)
Note:
- Users in the same channel must use the same channel profile.
- Before calling this method to set a new channel profile, destroy the current engine and create a new engine using sharedEngineWithAppId.
- Call this method before a user joins a channel because you cannot configure the channel profile when the channel is in use.
- In the communication profile, the Agora SDK supports encoding only in raw data, not in texture.
Declared In
AgoraRtcEngineKit.h
– setClientRole:
Sets the role of the user.
- (int)setClientRole:(AgoraClientRole)role
Parameters
role |
Role of the client: AgoraClientRole. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
This method is applicable only to live broadcast profile.
Sets the role of the user such as a host or an audience (default), before joining a channel.
This method can be used to switch the user role after the user joins a channel.
Declared In
AgoraRtcEngineKit.h
– joinChannelByToken:channelId:info:uid:joinSuccess:
Allows a user to join a channel.
- (int)joinChannelByToken:(NSString *_Nullable)token channelId:(NSString *_Nonnull)channelId info:(NSString *_Nullable)info uid:(NSUInteger)uid joinSuccess:(void ( ^ _Nullable ) ( NSString *_Nonnull channel , NSUInteger uid , NSInteger elapsed ))joinSuccessBlock
Parameters
token |
A
|
---|---|
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. Note: When joining a channel, the SDK calls |
uid |
User ID. A 32-bit unsigned integer with a value ranging from 1 to (232-1). The |
joinSuccessBlock |
Returns that the user joins the specified channel. Same as didJoinChannel. If |
Return Value
- 0: Success.
- < 0: Failure.
Discussion
Users in the same channel can talk to each other, and multiple users in the same channel can start a group chat. Users with different App IDs cannot call each other even if they join the same channel.
You must call the leaveChannel method to exit the current call before entering another channel. This method call is asynchronous; therefore, you can call this method in the main user interface thread.
The SDK uses the OS X’s AVAudioSession shared object for audio recording and playback, so using this object may affect the SDK’s audio functions.
If the joinChannelByToken method call is successful, the joinSuccessBlock
callback is triggered. If you implement both joinSuccessBlock
and didJoinChannel, joinSuccessBlock
takes higher priority than didJoinChannel. If you want to use didJoinChannel, set joinSuccessBlock
as nil.
Note:
A channel does not accept duplicate uids, such as two users with the same uid
. If you set uid
as 0, the system automatically assigns a uid
.
Declared In
AgoraRtcEngineKit.h
– leaveChannel:
Allows a user to leave a channel, such as hanging up or exiting a call.
- (int)leaveChannel:(void ( ^ _Nullable ) ( AgoraChannelStats *_Nonnull stat ))leaveChannelBlock
Parameters
leaveChannelBlock |
The callback indicates that a user leaves the channel, and provides the statistics of this call. See AgoraChannelStats for details. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
After joining a channel, the user must call the leaveChannel method to end the call before joining another channel.
This method returns 0 if the user leaves the channel and releases all resources related to the call.
This method call is asynchronous, and the user has not exited the channel when the method call returns. Once the user leaves the channel, the SDK triggers the didLeaveChannelWithStats callback.
Note:
If you call destroy immediately after leaveChannel, the leaveChannel process interrupts, and the didLeaveChannelWithStats callback is not triggered.
If you call this method during a CDN live streaming, the removePublishStreamUrl method is triggered.
When you call this method, the SDK deactivates the audio session on iOS by default, and may affect other apps. If you do not want this default behavior, use setAudioSessionOperationRestriction to set
AgoraAudioSessionOperationRestrictionDeactivateSession
so that when you call leaveChannel, the SDK does not deactivate the audio session.
Declared In
AgoraRtcEngineKit.h
– renewToken:
Gets a new token when the current token expires after a period of time.
- (int)renewToken:(NSString *_Nonnull)token
Parameters
token |
The new token. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
The token
expires after a period of time once the token schema is enabled when:
- The tokenPrivilegeWillExpire callback is triggered, or
- The didOccurError callback reports the AgoraErrorCodeTokenExpired(-109) error, or
- The rtcEngineRequestToken callback reports the AgoraErrorCodeTokenExpired(-109) error.
Note:
Agora recommends using the rtcEngineRequestToken callback to report the AgoraErrorCodeTokenExpired(-109) error, not using the didOccurError callback.
The app should call this method to get the token
. Failure to do so results in the SDK disconnecting from the server.
Declared In
AgoraRtcEngineKit.h
– enableWebSdkInteroperability:
Enables interoperability with the Agora Web SDK.
- (int)enableWebSdkInteroperability:(BOOL)enabled
Parameters
enabled |
Sets whether to enable/disable interoperability with the Agora Web SDK:
|
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
This method is applicable to the live broadcast profile only. In the communication profile, the SDK is interoperable with the Web SDK by default.
Declared In
AgoraRtcEngineKit.h
Core Audio
– enableAudio
Enables the audio module.
- (int)enableAudio
Return Value
- 0: Success.
- < 0: Failure.
Discussion
The audio module is enabled by default.
Note:
- This method affects the internal engine and can be called after leaveChannel. You can call this method either before or after joining a channel.
This method resets the internal engine and takes some time to take effect. Agora recommends using the following API methods to control the audio engine modules separately:
- enableLocalAudio: Whether to enable the microphone to create the local audio stream.
- muteLocalAudioStream: Whether to publish the local audio stream.
- muteRemoteAudioStream: Whether to subscribe to and play the remote audio stream.
- muteAllRemoteAudioStreams: Whether to subscribe to and play all remote audio streams.
Declared In
AgoraRtcEngineKit.h
– disableAudio
Disables the audio module.
- (int)disableAudio
Return Value
- 0: Success.
- < 0: Failure.
Discussion
Note:
- This method affects the internal engine and can be called after leaveChannel. You can call this method either before or after joining a channel.
This method resets the internal engine and takes some time to take effect. Agora recommends using the following API methods to control the audio engine modules separately:
- enableLocalAudio: Whether to enable the microphone to create the local audio stream.
- muteLocalAudioStream: Whether to publish the local audio stream.
- muteRemoteAudioStream: Whether to subscribe to and play the remote audio stream.
- muteAllRemoteAudioStreams: Whether to subscribe to and play all remote audio streams.
Declared In
AgoraRtcEngineKit.h
– setAudioProfile:scenario:
Sets the audio parameters and application scenarios.
- (int)setAudioProfile:(AgoraAudioProfile)profile scenario:(AgoraAudioScenario)scenario
Parameters
profile |
Sets the sampling rate, bitrate, encoding mode, and the number of channels. See AgoraAudioProfile. |
---|---|
scenario |
Sets the audio application scenario. See AgoraAudioScenario. |
Return Value
- 0: Success.
- < 0: Failure.
Discussion
Note:
- You must call setAudioProfile before joinChannelByToken.
- In the communication profile, you can set the profile but not the scenario.
- In the communication and live-broadcast profile, the bitrate may be different from your settings due to network self-adaptation.
- In scenarios involving music education, Agora recommends setting
profile
as AgoraAudioProfileMusicHighQuality(4) andscenario
as AgoraAudioScenarioGameStreaming(3) in AgoraAudioScenario.
Declared In
AgoraRtcEngineKit.h
– adjustRecordingSignalVolume:
Adjusts the recording volume.
- (int)adjustRecordingSignalVolume:(NSInteger)volume
Parameters
volume |
Recording volume. The value ranges between 0 and 400:
|
---|
Return Value
- 0: Success.
- < 0: Failure.
Declared In
AgoraRtcEngineKit.h
– adjustPlaybackSignalVolume:
Adjusts the playback volume.
- (int)adjustPlaybackSignalVolume:(NSInteger)volume
Parameters
volume |
Playback volume. The value ranges between 0 and 400:
|
---|
Return Value
- 0: Success.
- < 0: Failure.
Declared In
AgoraRtcEngineKit.h
– enableAudioVolumeIndication:smooth:
Enables the SDK to regularly report to the application on which user is speaking and the speaker’s volume.
- (int)enableAudioVolumeIndication:(NSInteger)interval smooth:(NSInteger)smooth
Parameters
interval |
Sets the time interval between two consecutive volume indications:
|
---|---|
smooth |
The smoothing factor sets the sensitivity of the audio volume indicator. The value ranges between 0 and 10. The greater the value, the more sensitive the indicator. The recommended value is 3. |
Return Value
- 0: Success.
- < 0: Failure.
Declared In
AgoraRtcEngineKit.h
– enableLocalAudio:
Enables/Disables the local audio capture.
- (int)enableLocalAudio:(BOOL)enabled
Parameters
enabled |
|
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
When an app joins a channel, the audio module is enabled by default. This method disables or re-enables the local audio capture, that is, to stop or restart local audio capturing and processing.
This method does not affect receiving or playing the remote audio streams, and is applicable to scenarios where the user wants to receive remote audio streams without sending any audio stream to other users in the channel.
The didMicrophoneEnabled callback is triggered once the local audio module is disabled or re-enabled.
Note:
Call this method after joinChannelByToken.
This method is different from muteLocalAudioStream:
- enableLocalAudio: Disables/Re-enables the local audio capturing and processing.
- muteLocalAudioStream: Stops/Continues sending the local audio streams.
Declared In
AgoraRtcEngineKit.h
– muteLocalAudioStream:
Sends/Stops sending the local audio stream.
- (int)muteLocalAudioStream:(BOOL)mute
Parameters
mute |
Sets whether to send/stop sending the local audio stream:
|
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
Use this method to stop/start sending the local audio stream.
Note:
When set to YES, this method does not disable the microphone and thus does not affect any ongoing recording.
Declared In
AgoraRtcEngineKit.h
– muteRemoteAudioStream:mute:
Receives/Stops receiving a specified remote user’s audio stream.
- (int)muteRemoteAudioStream:(NSUInteger)uid mute:(BOOL)mute
Parameters
uid |
User ID of the specified remote user. |
---|---|
mute |
Sets whether to receive/stop receiving a specified remote user’s audio stream:
|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
Note:
If you have called muteAllRemoteAudioStreams(YES) to mute all remote audio streams, please call muteAllRemoteAudioStreams(NO) before calling this method. muteAllRemoteAudioStreams sets all the remote streams, while muteRemoteAudioStream sets a specified stream.
Declared In
AgoraRtcEngineKit.h
– muteAllRemoteAudioStreams:
Receives/Stops receiving all remote users' audio streams.
- (int)muteAllRemoteAudioStreams:(BOOL)mute
Parameters
mute |
Sets whether to receive/stop receiving all remote users' audio streams:
|
---|
Return Value
- 0: Success.
- < 0: Failure.
Declared In
AgoraRtcEngineKit.h
– setDefaultMuteAllRemoteAudioStreams:
Sets whether to receive audio streams by default.
- (int)setDefaultMuteAllRemoteAudioStreams:(BOOL)mute
Parameters
mute |
Sets whether to receive/stop receiving all remote users' audio streams by default:
|
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
This method can be called either before or after joining the channel. If you call this method after joining the channel, then the audio streams of all the users joining after this are not received.
Declared In
AgoraRtcEngineKit.h
Core Video
– enableVideo
Enables the video module.
- (int)enableVideo
Return Value
- 0: Success.
- < 0: Failure.
Discussion
The app can call this method either before entering a channel or during a call. If this method is called before entering a channel, the service starts in the video mode. If this method is called during an audio call, the audio mode switches to the video mode.
To disable the video, call the disableVideo method.
Note:
- This method affects the internal engine and can be called after leaveChannel.
This method resets the internal engine and takes some time to take effect. Agora recommends using the following API methods to control the video engine modules separately:
- enableLocalVideo: Whether to enable the camera to create the local video stream.
- muteLocalVideoStream: Whether to publish the local video stream.
- muteRemoteVideoStream: Whether to subscribe to and play the remote video stream.
- muteAllRemoteVideoStreams: Whether to subscribe to and play all remote video streams.
Declared In
AgoraRtcEngineKit.h
– disableVideo
Disables the video module.
- (int)disableVideo
Return Value
- 0: Success.
- < 0: Failure.
Discussion
The app may call this method before entering a channel or during a call. If this method is called before entering a channel, the service starts in the audio mode. If this method is called during a video call, the video mode switches to the audio mode. To enable the video module, call the enableVideo method.
Note:
- This method affects the internal engine and can be called after leaveChannel.
This method resets the internal engine and takes some time to take effect. Agora recommends using the following API methods to control the video engine modules separately:
- enableLocalVideo: Whether to enable the camera to create the local video stream.
- muteLocalVideoStream: Whether to publish the local video stream.
- muteRemoteVideoStream: Whether to subscribe to and play the remote video stream.
- muteAllRemoteVideoStreams: Whether to subscribe to and play all remote video streams.
Declared In
AgoraRtcEngineKit.h
– setVideoEncoderConfiguration:
Sets the video encoder configuration.
- (int)setVideoEncoderConfiguration:(AgoraVideoEncoderConfiguration *_Nonnull)config
Parameters
config |
Video encoder configuration: AgoraVideoEncoderConfiguration |
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
Each video encoder configuration corresponds to a set of video parameters, including the resolution, frame rate, bitrate, and video orientation.
The parameters specified in this method are the maximum values under ideal network conditions. If the video engine cannot render the video using the specified parameters due to unreliable network conditions, the parameters further down the list are considered until a successful configuration is found.
If you do not need to set the video encoder configuration after joining the channel, you can call this method before enableVideo to reduce the render time of the first video frame.
Note:
Since v2.3.0, the following API methods are deprecated:
Declared In
AgoraRtcEngineKit.h
– setupLocalVideo:
Sets the local video view and configures the video display settings on the local machine.
- (int)setupLocalVideo:(AgoraRtcVideoCanvas *_Nullable)local
Parameters
local |
Sets the local video view and settings. See AgoraRtcVideoCanvas. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
The app calls this method to bind each video window (view) of the local video streams and configures the video display settings. Call this method after initialization to configure the local video display settings before entering a channel. The binding is still valid after the user leaves the channel, which means the window still displays. To unbind the view, set the view
in AgoraRtcVideoCanvas to nil.
Declared In
AgoraRtcEngineKit.h
– setupRemoteVideo:
Sets the remote video view.
- (int)setupRemoteVideo:(AgoraRtcVideoCanvas *_Nonnull)remote
Parameters
remote |
Sets the remote video view and settings. See AgoraRtcVideoCanvas. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
This method binds the remote user to the video display window (sets the view for the user of the specified uid).
The app specifies the uid of the remote video in the method call before the user joins a channel.
If the remote uid is unknown to the app, set it after the app receives the userJoinedBlock event.
If the Video Recording function is enabled, the Video Recording Service joins the channel as a dummy client, causing other clients to also receive the didJoinedOfUid event. Do not bind the dummy client to the app view because the dummy client does not send any video streams. If your app does not recognize the dummy client, bind the remote user to the view when the firstRemoteVideoDecodedOfUid callback is triggered.
To unbind the remote user from the view, set the view
in AgoraRtcVideoCanvas to nil. Once the remote user leaves the channel, the SDK unbinds the remote user.
Declared In
AgoraRtcEngineKit.h
– setLocalRenderMode:
Sets the local video display mode.
- (int)setLocalRenderMode:(AgoraVideoRenderMode)mode
Parameters
mode |
Sets the local video display mode. See AgoraVideoRenderMode. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
This method may be invoked multiple times during a call to change the display mode.
Declared In
AgoraRtcEngineKit.h
– setRemoteRenderMode:mode:
Sets the remote video display mode.
- (int)setRemoteRenderMode:(NSUInteger)uid mode:(AgoraVideoRenderMode)mode
Parameters
uid |
User ID of the remote user sending the video streams. |
---|---|
mode |
Sets the video display mode. See AgoraVideoRenderMode. |
Return Value
- 0: Success.
- < 0: Failure.
Discussion
This method can be invoked multiple times during a call to change the display mode.
Declared In
AgoraRtcEngineKit.h
– startPreview
Starts the local video preview before joining the channel.
- (int)startPreview
Return Value
- 0: Success.
- < 0: Failure.
Discussion
Before calling this method, you must:
- Call setupLocalVideo to set up the local preview window and configure the attributes.
- Call enableVideo to enable video.
Note:
Once startPreview is called 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.
Declared In
AgoraRtcEngineKit.h
– stopPreview
Stops the local video preview and the video.
- (int)stopPreview
Return Value
- 0: Success.
- < 0: Failure.
Declared In
AgoraRtcEngineKit.h
– enableLocalVideo:
Disables the local video.
- (int)enableLocalVideo:(BOOL)enabled
Parameters
enabled |
Sets whether to enable/disable the local video, including the capturer, renderer, and sender:
|
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
This method disables the local video and is only applicable when the user wants to watch the remote video without sending any video stream to the other user.
Call this method after enableVideo, otherwise, this method may not work properly.
After enableVideo is called, the local video is enabled by default. This method is used to disable the local video while the remote video remains unaffected.
Note:
This method enables the internal engine and can be called after leaveChannel.
Declared In
AgoraRtcEngineKit.h
– muteLocalVideoStream:
Sends/Stops sending the local video stream.
- (int)muteLocalVideoStream:(BOOL)mute
Parameters
mute |
Sets whether to send/stop sending the local video stream:
|
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
When set to YES
, this method does not disable the camera, and thus does not affect the retrieval of the local video stream. This method responds faster compared to enableLocalVideo which controls the sending of local video streams.
Declared In
AgoraRtcEngineKit.h
– muteAllRemoteVideoStreams:
Receives/Stops receiving all remote users' video streams.
- (int)muteAllRemoteVideoStreams:(BOOL)mute
Parameters
mute |
Sets whether to receive/stop receiving the local video stream:
|
---|
Return Value
- 0: Success.
- < 0: Failure.
Declared In
AgoraRtcEngineKit.h
– muteRemoteVideoStream:mute:
Receives/Stops receiving a specified remote user’s video stream.
- (int)muteRemoteVideoStream:(NSUInteger)uid mute:(BOOL)mute
Parameters
uid |
User ID of the specified remote user. |
---|---|
mute |
Sets whether to receive/stop receiving a specified remote user’s video stream.
|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
Note:
If you called muteAllRemoteVideoStreams and set to YES
to stop receiving all remote video streams, ensure that muteAllRemoteVideoStreams is called and set to NO
before calling this method.
Declared In
AgoraRtcEngineKit.h
– setDefaultMuteAllRemoteVideoStreams:
Sets whether to receive video streams by default.
- (int)setDefaultMuteAllRemoteVideoStreams:(BOOL)mute
Parameters
mute |
Sets whether to receive/stop receiving all remote users' video streams by default.
|
---|
Return Value
- 0: Success.
- < 0: Failure.
Declared In
AgoraRtcEngineKit.h
Audio Routing Controller
– setDefaultAudioRouteToSpeakerphone:
Sets the default audio route. (iOS only.)
- (int)setDefaultAudioRouteToSpeakerphone:(BOOL)defaultToSpeaker
Parameters
defaultToSpeaker |
Sets the default audio route:
|
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
This method sets whether the received audio is routed to the earpiece or speakerphone by default before joining the channel. If the user does not call this method, the audio is routed to the earpiece by default.
If you need to change the default audio route after joining the channel, call setEnableSpeakerphone.
Note:
- This method only works in audio mode.
- Call this method before calling joinChannel.
The default settings for each mode:
- Voice: Earpiece.
- Video: Speakerphone. If the user in a communication channel calls disableVideo or if the user calls muteLocalVideoStream and muteAllRemoteVideoStreams, the default audio route is switched to the earpiece automatically.
- Live Broadcast: Speakerphone.
- Gaming Voice: Speakerphone.
Declared In
AgoraRtcEngineKit.h
– setEnableSpeakerphone:
Enables/Disables the audio routing to the speakerphone. (iOS only.)
- (int)setEnableSpeakerphone:(BOOL)enableSpeaker
Parameters
enableSpeaker |
Sets whether to route the audio to the speakerphone or earpiece:
|
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
This method sets whether the audio is routed to the speakerphone.
Note:
- Ensure that you have successfully called the joinChannelByToken method before calling this method.
- The SDK calls setCategory(AVAudioSessionCategoryPlayAndRecord) with options to configure the headset/speakerphone, so this method applies to all audio playback in the system.
- After this method is called, the SDK returns the didAudioRouteChanged callback, indicating that the audio route changes.
- This method does not take effect when using a headset.
Declared In
AgoraRtcEngineKit.h
– isSpeakerphoneEnabled
Checks whether the speakerphone is enabled. (iOS only.)
- (BOOL)isSpeakerphoneEnabled
Return Value
- YES: The speakerphone is enabled, and the audio plays from the speakerphone.
- NO: The speakerphone is not enabled, and the audio plays from devices other than the speakerphone. For example, the headset or earpiece.
Declared In
AgoraRtcEngineKit.h
In-ear Monitor
– enableInEarMonitoring:
Enables the in-ear monitoring function. (iOS only.)
- (int)enableInEarMonitoring:(BOOL)enabled
Parameters
enabled |
Sets whether to enable/disable the in-ear monitoring function.
|
---|
Return Value
- 0: Success.
- < 0: Failure.
Declared In
AgoraRtcEngineKit.h
– setInEarMonitoringVolume:
Sets the volume of the in-ear monitor. (iOS only.)
- (int)setInEarMonitoringVolume:(NSInteger)volume
Parameters
volume |
Sets the volume of the in-ear monitor. The value ranges between 0 and 100 (default). |
---|
Return Value
- 0: Success.
- < 0: Failure.
Declared In
AgoraRtcEngineKit.h
Audio Sound Effect
– setLocalVoicePitch:
Changes the voice pitch of the local speaker.
- (int)setLocalVoicePitch:(double)pitch
Parameters
pitch |
Sets the voice pitch. The value ranges between 0.5 and 2.0. The lower the value, the lower the voice pitch. The default value is 1.0 (no change to the local voice pitch). |
---|
Return Value
- 0: Success.
- -1: Failure.
Declared In
AgoraRtcEngineKit.h
– setLocalVoiceEqualizationOfBandFrequency:withGain:
Sets the local voice equalization effect.
- (int)setLocalVoiceEqualizationOfBandFrequency:(AgoraAudioEqualizationBandFrequency)bandFrequency withGain:(NSInteger)gain
Parameters
bandFrequency |
Sets the band frequency. The value ranges between 0 and 9, representing the respective 10-band center frequencies of the voice effects, including 31, 62, 125, 500, 1k, 2k, 4k, 8k, and 16k Hz. See AgoraAudioEqualizationBandFrequency for details. |
---|---|
gain |
Sets the gain of each band in dB. The value ranges between -15 and 15. The default value is 0. |
Return Value
- 0: Success.
- -1: Failure.
Declared In
AgoraRtcEngineKit.h
– setLocalVoiceReverbOfType:withValue:
Sets the local voice reverberation.
- (int)setLocalVoiceReverbOfType:(AgoraAudioReverbType)reverbType withValue:(NSInteger)value
Parameters
reverbType |
Sets the reverberation type. See AgoraAudioReverbType. |
---|---|
value |
Sets the effect of the reverberation type. See AgoraAudioReverbType for the value range. |
Return Value
- 0: Success.
- -1: Failure.
Declared In
AgoraRtcEngineKit.h
Music File Playback and Mixing
– startAudioMixing:loopback:replace:cycle:
Starts audio mixing.
- (int)startAudioMixing:(NSString *_Nonnull)filePath loopback:(BOOL)loopback replace:(BOOL)replace cycle:(NSInteger)cycle
Parameters
filePath |
The absolute path of the local or online audio file to be mixed. Supported audio formats: mp3, aac, m4a, 3gp, and wav. |
---|---|
loopback |
Sets which user can hear the audio mixing:
|
replace |
Sets the audio mixing content:
|
cycle |
Sets the number of playback loops:
|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
This method mixes the specified local audio file with the audio stream from the microphone, or replaces the microphone’s audio stream with the specified local audio file. You can choose whether the other user can hear the local audio playback and specify the number of playback loops. This method also supports online music playback.
When the audio mixing file playback finishes after calling this method, the rtcEngineLocalAudioMixingDidFinish callback is triggered.
Note:
- To use this method, ensure that the iOS device version is 8.0+.
- Call this method when you are in a channel.
Declared In
AgoraRtcEngineKit.h
– stopAudioMixing
Stops audio mixing.
- (int)stopAudioMixing
Return Value
- 0: Success.
- < 0: Failure.
Discussion
Call this method when you are in a channel.
Declared In
AgoraRtcEngineKit.h
– pauseAudioMixing
Pauses audio mixing.
- (int)pauseAudioMixing
Return Value
- 0: Success.
- < 0: Failure.
Discussion
Call this method when you are in a channel.
Declared In
AgoraRtcEngineKit.h
– resumeAudioMixing
Resumes audio mixing.
- (int)resumeAudioMixing
Return Value
- 0: Success.
- < 0: Failure.
Discussion
Call this method when you are in a channel.
Declared In
AgoraRtcEngineKit.h
– adjustAudioMixingVolume:
Adjusts the volume during audio mixing.
- (int)adjustAudioMixingVolume:(NSInteger)volume
Parameters
volume |
Audio mixing volume. The value ranges between 0 and 100 (default). |
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
Call this method when you are in a channel.
Declared In
AgoraRtcEngineKit.h
– getAudioMixingDuration
Retrieves the duration (ms) of audio mixing.
- (int)getAudioMixingDuration
Return Value
≥ 0: The audio mixing duration, if this method call is successful.
< 0: Failure.
Discussion
Call this method when you are in a channel.
Declared In
AgoraRtcEngineKit.h
– getAudioMixingCurrentPosition
Retrieves the playback position (ms) of the audio mixing.
- (int)getAudioMixingCurrentPosition
Return Value
≥ 0: The current playback position of the audio mixing, if this method call is successful.
< 0: Failure.
Discussion
Call this method when you are in a channel.
Declared In
AgoraRtcEngineKit.h
– setAudioMixingPosition:
Sets the playback position of the audio mixing file to a different starting position (the default plays from the beginning).
- (int)setAudioMixingPosition:(NSInteger)pos
Parameters
pos |
The starting playback position (ms) of the audio mixing file. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Declared In
AgoraRtcEngineKit.h
Audio Effect File Playback
– getEffectsVolume
Retrieves the volume of the audio effects.
- (double)getEffectsVolume
Return Value
≥ 0: Volume of the audio effects, if this method call is successful.
< 0: Failure.
Discussion
The value ranges between 0.0 and 100.0.
Declared In
AgoraRtcEngineKit.h
– setEffectsVolume:
Sets the volume of the audio effects.
- (int)setEffectsVolume:(double)volume
Parameters
volume |
Volume of the audio effects. The value ranges between 0.0 and 100.0 (default). |
---|
Return Value
- 0: Success.
- < 0: Failure.
Declared In
AgoraRtcEngineKit.h
– setVolumeOfEffect:withVolume:
Sets the volume of a specified audio effect.
- (int)setVolumeOfEffect:(int)soundId withVolume:(double)volume
Parameters
soundId |
ID of the audio effect. Each audio effect has a unique ID. |
---|---|
volume |
Volume of the audio effect. The value ranges between 0.0 and 100.0 (default). |
Return Value
- 0: Success.
- < 0: Failure.
Declared In
AgoraRtcEngineKit.h
– playEffect:filePath:loopCount:pitch:pan:gain:publish:
Plays a specified audio effect.
- (int)playEffect:(int)soundId filePath:(NSString *_Nullable)filePath loopCount:(int)loopCount pitch:(double)pitch pan:(double)pan gain:(double)gain publish:(BOOL)publish
Parameters
soundId |
ID of the specified audio effect. Each audio effect has a unique ID.
If the audio effect is preloaded into the memory through preloadEffect, ensure that the |
---|---|
filePath |
The absolute path of the audio effect file. |
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:
|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
You can use this method to add specific audio effects for specific scenarios, for example, gaming. When the audio effect file playback is finished, the rtcEngineDidAudioEffectFinish callback is triggered。
Declared In
AgoraRtcEngineKit.h
– stopEffect:
Stops playing a specified audio effect.
- (int)stopEffect:(int)soundId
Parameters
soundId |
ID of the audio effect. Each audio effect has a unique ID. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Declared In
AgoraRtcEngineKit.h
– stopAllEffects
Stops playing all audio effects.
- (int)stopAllEffects
Declared In
AgoraRtcEngineKit.h
– preloadEffect:filePath:
Preloads a specified audio effect file into the memory.
- (int)preloadEffect:(int)soundId filePath:(NSString *_Nullable)filePath
Parameters
soundId |
ID of the audio effect. Each audio effect has a unique ID. |
---|---|
filePath |
Absolute path of the audio effect file. |
Return Value
- 0: Success.
- < 0: Failure.
Discussion
To ensure smooth communication, limit the size of the audio effect file. Agora recommends using this method to preload the audio effect before calling joinChannelByToken.
Supported audio formats: mp3, aac, m4a, 3gp, and wav.
Declared In
AgoraRtcEngineKit.h
– unloadEffect:
Releases a specified preloaded audio effect from the memory.
- (int)unloadEffect:(int)soundId
Parameters
soundId |
ID of the audio effect. Each audio effect has a unique ID. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Declared In
AgoraRtcEngineKit.h
– pauseEffect:
Pauses a specified audio effect.
- (int)pauseEffect:(int)soundId
Parameters
soundId |
ID of the audio effect. Each audio effect has a unique ID. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Declared In
AgoraRtcEngineKit.h
– pauseAllEffects
Pauses all audio effects.
- (int)pauseAllEffects
Return Value
- 0: Success.
- < 0: Failure.
Declared In
AgoraRtcEngineKit.h
– resumeEffect:
Resumes playing a specified audio effect.
- (int)resumeEffect:(int)soundId
Parameters
soundId |
ID of the audio effect. Each audio effect has a unique ID. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Declared In
AgoraRtcEngineKit.h
– resumeAllEffects
Resumes playing all audio effects.
- (int)resumeAllEffects
Return Value
- 0: Success.
- < 0: Failure.
Declared In
AgoraRtcEngineKit.h
Audio Recorder
– startAudioRecording:quality:
Starts an audio recording.
- (int)startAudioRecording:(NSString *_Nonnull)filePath quality:(AgoraAudioRecordingQuality)quality
Parameters
filePath |
Absolute file path of the recording file. The string of the file name is in UTF-8. |
---|---|
quality |
Sets the audio recording quality. See AgoraAudioRecordingQuality. |
Return Value
- 0: Success.
- < 0: Failure.
Discussion
The SDK allows recording during a call. Supported formats:
- .wav: Large file size with high fidelity
- .aac: Small file size with low fidelity
Ensure that the directory to save the recording file exists and is writable. This method is usually called after the joinChannelByToken method. The recording automatically stops when the leaveChannel method is called.
Declared In
AgoraRtcEngineKit.h
– stopAudioRecording
Stops an audio recording on the client.
- (int)stopAudioRecording
Return Value
- 0: Success.
- < 0: Failure.
Discussion
Note:
You can call this method before calling leaveChannel else, the recording automatically stops when the leaveChannel method is called.
Declared In
AgoraRtcEngineKit.h
Loopback Recording
– enableLoopbackRecording:deviceName:
Enables loopback recording. (macOS only.)
- (int)enableLoopbackRecording:(BOOL)enabled deviceName:(NSString *_Nullable)deviceName
Parameters
enabled |
Sets whether to enable/disable loopback recording.
|
---|---|
deviceName |
Device name of the sound card |
Return Value
- 0: Success.
- < 0: Failure.
Discussion
If you enable loopback recording, the output of the sound card is mixed into the audio stream sent to the other end.
Note:
macOS does not support loopback of the default sound card. If you need to use this method, please use a virtual sound card and pass its name to the deviceName
parameter. Agora has tested and recommends using soundflower.
Declared In
AgoraRtcEngineKit.h
Miscellaneous Audio Control
– setAudioSessionOperationRestriction:
Sets the audio session’s operational restriction. (iOS only.)
- (void)setAudioSessionOperationRestriction:(AgoraAudioSessionOperationRestriction)restriction
Parameters
restriction |
The operational restriction (bit mask) of the SDK on the audio session. See AgoraAudioSessionOperationRestriction for details. |
---|
Discussion
The SDK and the app can both configure the audio session by default. The app may occasionally use other applications or third-party components to manipulate the audio session and restrict the SDK from doing so. This method allows the app to restrict the SDK’s manipulation of the audio session.
You can call this method at any time to return the control of the audio sessions to the SDK.
Note:
This method restricts the SDK’s manipulation of the audio session. Any operation to the audio session relies solely on the app, other applications, or third-party components.
Declared In
AgoraRtcEngineKit.h
Network-related Test
– startEchoTest:
Starts an audio call test.
- (int)startEchoTest:(void ( ^ _Nullable ) ( NSString *_Nonnull channel , NSUInteger uid , NSInteger elapsed ))successBlock
Parameters
successBlock |
The |
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
This method launches an audio call test to determine whether the audio devices (for example, headset and speaker) and the network connection are working properly.
To conduct the test:
- The user speaks and the recording is played back within 10 seconds.
- If the user can hear the recording within 10 seconds, the audio devices and network connection are working properly.
Note:
- After calling this method, always call stopEchoTest to end the test. Otherwise, the app cannot run the next echo test, nor can it call the joinChannelByToken method to start a new call.
- In the live broadcast profile, only the hosts can call this method. If the user switches from a communication to live broadcast channel, the user must call setClientRole to change the user role from the audience (default) to the host before calling this method.
Declared In
AgoraRtcEngineKit.h
– stopEchoTest
Stops the audio call test.
- (int)stopEchoTest
Return Value
- 0: Success.
- < 0: Failure. For example, AgoraErrorCodeRefused(-5):Failed to stop the echo test. The echo test may not be running.
Declared In
AgoraRtcEngineKit.h
– enableLastmileTest
Enables the network connection quality test.
- (int)enableLastmileTest
Return Value
- 0: Success.
- < 0: Failure.
Discussion
This method tests the quality of the user’s network connection and is disabled by default.
Before users join a channel or before an audience switches to a host, call this method to check the uplink network quality.
This method consumes additional network traffic, which may affect the communication quality.
Call disableLastmileTest to disable the test immediately after receiving the lastmileQuality callback, and before the user joins the channel or switches the user role.
Note:
Do not call any other methods before receiving the lastmileQuality callback. Otherwise, the callback may be interrupted by other methods and may not execute.
In the Live Broadcast profile, a host should not call this method.
Declared In
AgoraRtcEngineKit.h
– disableLastmileTest
Disables the network connection quality test.
- (int)disableLastmileTest
Return Value
- 0: Success.
- < 0: Failure.
Declared In
AgoraRtcEngineKit.h
Custom Video Module
– setVideoSource:
Sets the video source.
- (void)setVideoSource:(id<AgoraVideoSourceProtocol> _Nullable)videoSource
Parameters
videoSource |
---|
Discussion
In real-time communications, the Agora SDK uses the default video input source (the built-in camera) to publish streams. To use the external video source, call AgoraVideoSourceProtocol to set the custom video source and then use this method to add the external video source into the SDK.
Declared In
AgoraRtcEngineKit.h
– setLocalVideoRenderer:
Sets the local video renderer.
- (void)setLocalVideoRenderer:(id<AgoraVideoSinkProtocol> _Nullable)videoRenderer
Parameters
videoRenderer |
Sets the local video renderer. See AgoraVideoSinkProtocol. |
---|
Discussion
In real-time communications, the Agora SDK uses the default video renderer to render the video. To use the external video renderer, call AgoraVideoSinkProtocol to set the custom local video renderer and then use this method to add the external renderer into the SDK.
Declared In
AgoraRtcEngineKit.h
– setRemoteVideoRenderer:forUserId:
Sets the remote video renderer.
- (void)setRemoteVideoRenderer:(id<AgoraVideoSinkProtocol> _Nullable)videoRenderer forUserId:(NSUInteger)userId
Parameters
videoRenderer |
Sets the video renderer of the remote user. See AgoraVideoSinkProtocol. |
---|---|
userId |
ID of the remote user. |
Discussion
This method sets the remote local renderer. In real-time communications, the Agora SDK uses the default video renderer to render the video. To use the external video renderer, call AgoraVideoSinkProtocol to set the custom remote video renderer and then use this method to add the external renderer into the SDK.
Declared In
AgoraRtcEngineKit.h
– videoSource
Retrieves the video source.
- (id<AgoraVideoSourceProtocol> _Nullable)videoSource
Return Value
Video source. See AgoraVideoSourceProtocol.
Declared In
AgoraRtcEngineKit.h
– localVideoRenderer
Retrieves the local video renderer.
- (id<AgoraVideoSinkProtocol> _Nullable)localVideoRenderer
Return Value
Local video renderer. See AgoraVideoSinkProtocol.
Declared In
AgoraRtcEngineKit.h
– remoteVideoRendererOfUserId:
Retrieves the video renderer of a specified remote user.
- (id<AgoraVideoSinkProtocol> _Nullable)remoteVideoRendererOfUserId:(NSUInteger)userId
Parameters
userId |
ID of the remote user. |
---|
Return Value
Video renderer of the remote user. See AgoraVideoSinkProtocol.
Declared In
AgoraRtcEngineKit.h
External Audio Data (push-mode only)
– enableExternalAudioSourceWithSampleRate:channelsPerFrame:
Enables the external audio source.
- (void)enableExternalAudioSourceWithSampleRate:(NSUInteger)sampleRate channelsPerFrame:(NSUInteger)channelsPerFrame
Parameters
sampleRate |
Sets the sampling rate of the external audio source: 8000, 16000, 44100 or 48000. |
---|---|
channelsPerFrame |
Sets the number of the external audio source channels (two channels maximum). |
Declared In
AgoraRtcEngineKit.h
– disableExternalAudioSource
Disables the external audio source.
- (void)disableExternalAudioSource
Declared In
AgoraRtcEngineKit.h
– pushExternalAudioFrameRawData:samples:timestamp:
Pushes the external raw data audio frame to the Agora SDK for encoding.
- (BOOL)pushExternalAudioFrameRawData:(void *_Nonnull)data samples:(NSUInteger)samples timestamp:(NSTimeInterval)timestamp
Parameters
data |
External audio data to be pushed. |
---|---|
samples |
Sampling point for the push. |
timestamp |
Timestamp of the external audio frame to be synchronized with the external video source. |
Return Value
- 0: Success.
- < 0: Failure.
Declared In
AgoraRtcEngineKit.h
– pushExternalAudioFrameSampleBuffer:
Pushes the external CMSampleBuffer audio frame to the Agora SDK for encoding.
- (BOOL)pushExternalAudioFrameSampleBuffer:(CMSampleBufferRef _Nonnull)sampleBuffer
Parameters
sampleBuffer |
Sample buffer for the push. |
---|
Return Value
- YES: Success.
- NO: Failure.
Declared In
AgoraRtcEngineKit.h
External Video Data (push-mode only)
– setExternalVideoSource:useTexture:pushMode:
Configures the external video source.
- (void)setExternalVideoSource:(BOOL)enable useTexture:(BOOL)useTexture pushMode:(BOOL)pushMode
Parameters
enable |
Sets whether or not to use an external video source:
|
---|---|
useTexture |
Sets whether or not to use texture as an input:
|
pushMode |
Sets whether or not the external video source needs to call pushExternalVideoFrame to send the video frame to the Agora SDK:
|
Discussion
If an external video source is used, call this method before enableVideo or startPreview.
Declared In
AgoraRtcEngineKit.h
– pushExternalVideoFrame:
Pushes the external video frame.
- (BOOL)pushExternalVideoFrame:(AgoraVideoFrame *_Nonnull)frame
Parameters
frame |
Video frame containing the Agora SDK’s encoded video data to be pushed. See AgoraVideoFrame for details. |
---|
Return Value
- YES: The frame is pushed successfully.
- NO: Failed to push the frame.
Discussion
This method pushes the video frame using the AgoraVideoFrame class and passes the video frame to the Agora SDK with the input format
found in AgoraVideoFrame.
Call setExternalVideoSource and set the pushMode
parameter as YES before calling this method. Otherwise, a failure returns after calling this method.
Note:
This method supports pushing textured video frames in the live-broadcast profile only, not in the communication profile.
Declared In
AgoraRtcEngineKit.h
Raw Audio Data
– setRecordingAudioFrameParametersWithSampleRate:channel:mode:samplesPerCall:
Sets the audio recording format for the onRecordAudioFrame
callback.
- (int)setRecordingAudioFrameParametersWithSampleRate:(NSInteger)sampleRate channel:(NSInteger)channel mode:(AgoraAudioRawFrameOperationMode)mode samplesPerCall:(NSInteger)samplesPerCall
Parameters
sampleRate |
Sets the sampling rate ( |
---|---|
channel |
Sets the number of audio channels (
|
mode |
Sets the use mode of the |
samplesPerCall |
Sets the sample points ( |
Return Value
- 0: Success.
- < 0: Failure.
Discussion
See Modify Raw Data for details.
Declared In
AgoraRtcEngineKit.h
– setPlaybackAudioFrameParametersWithSampleRate:channel:mode:samplesPerCall:
Sets the audio playback format for the onPlaybackAudioFrame
callback.
- (int)setPlaybackAudioFrameParametersWithSampleRate:(NSInteger)sampleRate channel:(NSInteger)channel mode:(AgoraAudioRawFrameOperationMode)mode samplesPerCall:(NSInteger)samplesPerCall
Parameters
sampleRate |
Sets the sampling rate ( |
---|---|
channel |
Sets the number of audio channels (
|
mode |
Sets the use mode of the |
samplesPerCall |
Sets the sample points ( |
Return Value
- 0: Success.
- < 0: Failure.
Discussion
See Modify Raw Data for details.
Declared In
AgoraRtcEngineKit.h
– setMixedAudioFrameParametersWithSampleRate:samplesPerCall:
Sets the mixed audio format for the onMixedAudioFrame
callback.
- (int)setMixedAudioFrameParametersWithSampleRate:(NSInteger)sampleRate samplesPerCall:(NSInteger)samplesPerCall
Parameters
sampleRate |
Sets the sampling rate ( |
---|---|
samplesPerCall |
Sets the sample points ( |
Return Value
- 0: Success.
- < 0: Failure.
Discussion
See Modify Raw Data for details.
Declared In
AgoraRtcEngineKit.h
Watermark
– addVideoWatermark:
Adds a watermark image to the local video or CDN live stream.
- (int)addVideoWatermark:(AgoraImage *_Nonnull)watermark
Parameters
watermark |
Watermark image to be added to the local video stream. See AgoraImage. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
This method adds a PNG watermark to the local video stream for the recording device, channel audience, and CDN live audience to see and capture.
To add the PNG file onto a CDN live publishing stream only, see the setLiveTranscoding method.
Note:
- The URL descriptions are different for the local video and CDN live streams:
- In a local video stream,
url
in AgoraImage refers to the absolute path of the added watermark image file in the local video stream. - In a CDN live stream,
url
in AgoraImage refers to the HTTP/HTTPS URL address of the added watermark image in the CDN live broadcast.
- In a local video stream,
- The source file of the watermark image must be in the PNG file format. If the width and height of the PNG file differ from your settings in this method, the PNG file is cropped to conform to your settings.
- The Agora SDK supports adding only one watermark image onto a local video or CDN live stream. The newly added watermark image replaces the previous one.
- If you set
orientationMode
asAdaptive
in the setVideoEncoderConfiguration method, the watermark image rotates with the video frame and rotates around the upper left corner of the watermark image.
Declared In
AgoraRtcEngineKit.h
– clearVideoWatermarks
Removes the watermark image from the video stream added by addVideoWatermark.
- (void)clearVideoWatermarks
Return Value
- 0: Success.
- < 0: Failure.
Declared In
AgoraRtcEngineKit.h
Stream Fallback
– setLocalPublishFallbackOption:
Sets the fallback option for the published local stream based on the network conditions.
- (int)setLocalPublishFallbackOption:(AgoraStreamFallbackOptions)option
Parameters
option |
Sets the fallback option for the published video stream. The default value is AgoraStreamFallbackOptionDisabled. See AgoraStreamFallbackOptions for details. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
The default setting for option
is AgoraStreamFallbackOptionDisabled
, where there is no fallback for the published video stream when the uplink network conditions are unreliable.
If option
is set to AgoraStreamFallbackOptionAudioOnly
, the SDK will:
- Disable the upstream video but enable audio only when the network conditions deteriorate and cannot support both video and audio.
- Re-enable the video when the network conditions improve.
When the published stream falls back to audio-only or when the audio stream switches back to the video, the didLocalPublishFallbackToAudioOnly callback is triggered.
Note:
Agora does not recommend using this method for CDN live streaming, because the remote CDN live user will have a noticeable lag when the published stream falls back to audio-only.
Declared In
AgoraRtcEngineKit.h
– setRemoteSubscribeFallbackOption:
Sets the fallback option for the remote stream based on the network conditions.
- (int)setRemoteSubscribeFallbackOption:(AgoraStreamFallbackOptions)option
Parameters
option |
Sets the fallback option for the remote stream. The default value is |
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
The default setting for option
is AgoraStreamFallbackOptionVideoStreamLow
, where the remote stream falls back to the low-video stream (low resolution and low bitrate) under unreliable downlink network conditions.
If option
is set to AgoraStreamFallbackOptionAudioOnly
, the SDK automatically switches the video from a high stream to a low stream, or disable the video when the downlink network conditions cannot support both audio and video to guarantee the quality of the audio. The SDK monitors the network quality and re-enables the video stream when the network conditions improve.
Once the published stream falls back to audio only, or the audio stream switches back to the video stream, the didRemoteSubscribeFallbackToAudioOnly callback is triggered.
Declared In
AgoraRtcEngineKit.h
Dual-stream Mode
– enableDualStreamMode:
Enables/Disables the dual-stream mode. (Live broadcast only.)
- (int)enableDualStreamMode:(BOOL)enabled
Parameters
enabled |
Sets the stream mode:
|
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
If dual-stream mode is enabled, the receiver can choose to receive the high stream (high-resolution high-bitrate video stream), or low stream (low-resolution low-bitrate video stream).
Declared In
AgoraRtcEngineKit.h
– setRemoteVideoStream:type:
Sets the remote user’s video stream type received by the local user when the remote user sends dual streams.
- (int)setRemoteVideoStream:(NSUInteger)uid type:(AgoraVideoStreamType)streamType
Parameters
uid |
ID of the remote user sending the video stream. |
---|---|
streamType |
Sets the video-stream type. See AgoraVideoStreamType. |
Return Value
- 0: Success.
- < 0: Failure.
Discussion
This method allows the app to adjust the corresponding video-stream type based on the size of the video window to reduce the bandwidth and resources.
- If the remote user enables the dual-stream mode by calling enableDualStreamMode, the SDK receives the high-video stream by default. You can use this method to switch to the low-video stream type.
- If the dual-stream mode is not enabled, the SDK receives the high-video stream by default.
The method result returns in the didApiCallExecute callback. The Agora SDK receives the high-video stream by default to save the bandwidth. If needed, users may use this method to switch to the low-video stream.
By default, the aspect ratio of the low-video stream is the same as the high-video stream. Once the resolution of the high-video stream is set, the system automatically sets the resolution, frame rate, and bitrate for the low-video stream.
Declared In
AgoraRtcEngineKit.h
– setRemoteDefaultVideoStreamType:
Sets the default video-stream type for the video received by the local user when the remote user sends dual streams.
- (int)setRemoteDefaultVideoStreamType:(AgoraVideoStreamType)streamType
Parameters
streamType |
Sets the default video-stream type. See AgoraVideoStreamType. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Declared In
AgoraRtcEngineKit.h
Encryption
– setEncryptionSecret:
Enables built-in encryption with an encryption password before joining a channel.
- (int)setEncryptionSecret:(NSString *_Nullable)secret
Parameters
secret |
Encryption password. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
All users in a channel must set the same encryption password. The encryption password is automatically cleared once a user leaves the channel.
If the encryption password is not specified or set to empty, the encryption functionality is disabled.
Note:
Do not use this method for CDN live streaming.
Declared In
AgoraRtcEngineKit.h
– setEncryptionMode:
Sets the built-in encryption mode.
- (int)setEncryptionMode:(NSString *_Nullable)encryptionMode
Parameters
encryptionMode |
Sets the encryption mode. See AgoraEncryptionMode. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
The Agora SDK supports built-in encryption, which is set to the AgoraEncryptionModeAES128XTS
mode by default. Call this method to use other encryption modes.
All users in the same channel must use the same encryption mode and password.
Refer to the information related to the AES encryption algorithm on the differences between the encryption modes.
Note:
- Call setEncryptionSecret to enable the built-in encryption function before calling this method.
- Do not use this method for CDN live streaming.
Declared In
AgoraRtcEngineKit.h
Inject an Online Media Stream
– addInjectStreamUrl:config:
Adds a voice or video stream HTTP/HTTPS URL address to a live broadcast.
- (int)addInjectStreamUrl:(NSString *_Nonnull)url config:(AgoraLiveInjectStreamConfig *_Nonnull)config
Parameters
url |
HTTP/HTTPS URL address to be added to the ongoing live broadcast. Valid protocols are RTMP, HLS, and FLV.
|
---|---|
config |
AgoraLiveInjectStreamConfig object which contains the configuration information for the added voice or video stream. @return * 0: Success.
|
Discussion
The streamPublishedWithUrl callback returns the inject stream status.
If this method call is successful, the server pulls the voice or video stream and injects it into a live channel. This is applicable to scenarios where all the audience members in the channel can watch a live show and interact with each other.
The didJoinedOfUid and firstRemoteVideoDecodedOfUid callbacks are triggered and a stream uid of 666 is returned.
Declared In
AgoraRtcEngineKit.h
– removeInjectStreamUrl:
Removes the voice or video stream HTTP/HTTPS URL address from a live broadcast.
- (int)removeInjectStreamUrl:(NSString *_Nonnull)url
Parameters
url |
HTTP/HTTPS URL address of the added stream to be removed. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
This method removes the HTTP/HTTPS URL address (added by addInjectStreamUrl) from a live broadcast.
If this method call is successful, the didOfflineOfUid callback is triggered and a stream uid of 666 is returned.
Declared In
AgoraRtcEngineKit.h
CDN Live Streaming
– addPublishStreamUrl:transcodingEnabled:
Adds a stream RTMP URL address, to which the host publishes the stream. (CDN live only.)
- (int)addPublishStreamUrl:(NSString *_Nonnull)url transcodingEnabled:(BOOL)transcodingEnabled
Parameters
url |
RTMP URL address, to which the host publishes the stream. |
---|---|
transcodingEnabled |
Sets whether transcoding is enabled/disabled:
|
Return Value
- 0: Success.
< 0: Failure.
- AgoraErrorCodeInvalidArgument(2): Invalid parameter. The URL is nil or the string length is 0.
- AgoraErrorCodeNotInitialized(7): You have not initialized the RTC Engine when publishing the stream.
Discussion
The host publishes the stream to the specified CDN live RTMP URL address. This method triggers the streamPublishedWithUrl callback.
Note:
- Ensure that the user joins the channel before calling this method.
- This method adds only one stream URL each time it is called.
- The URL must not contain special characters, such as Chinese language characters.
Declared In
AgoraRtcEngineKit.h
– removePublishStreamUrl:
Removes a stream RTMP URL address. (CDN live only.)
- (int)removePublishStreamUrl:(NSString *_Nonnull)url
Parameters
url |
RTMP URL address to be removed. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
This method removes the RTMP URL address added by addPublishStreamUrl from a CDN live stream.
Note:
- This method removes only one URL each time it is called.
- The URL must not contain special characters such as Chinese language characters.
Declared In
AgoraRtcEngineKit.h
– setLiveTranscoding:
Sets the video layout and audio settings for CDN live. (CDN live only.)
- (int)setLiveTranscoding:(AgoraLiveTranscoding *_Nullable)transcoding
Parameters
transcoding |
Sets the CDN live audio/video transcoding settings. See AgoraLiveTranscoding. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Declared In
AgoraRtcEngineKit.h
Data Stream
– createDataStream:reliable:ordered:
Creates a data stream.
- (int)createDataStream:(NSInteger *_Nonnull)streamId reliable:(BOOL)reliable ordered:(BOOL)ordered
Parameters
streamId |
ID of the created data stream. |
---|---|
reliable |
Sets whether or not the recipients are guaranteed to receive the data stream from the sender within five seconds:
|
ordered |
Sets whether or not the recipients receive the data stream in the sent order:
|
Return Value
Returns the ID of the data stream, if this method call is successful.
< 0: Failure.
Discussion
Each user can have up to five simultaneous data channels.
Note:
Set both the reliable
and ordered
parameters to YES
or NO
. Do not set one as YES
and the other as NO
.
Declared In
AgoraRtcEngineKit.h
– sendStreamMessage:data:
Sends data stream messages to all users in a channel.
- (int)sendStreamMessage:(NSInteger)streamId data:(NSData *_Nonnull)data
Parameters
streamId |
ID of the sent data stream, returned in createDataStream. |
---|---|
data |
Sent data. |
Return Value
- 0: Success.
- < 0: Failure.
Discussion
The SDK has the following restrictions on this method:
- Up to 30 packets can be sent per second in a channel with each packet having a maximum size of 1 kB.
- Each client can send up to 6 kB of data per second.
- Each user can have up to five data streams simultaneously.
Note:
This method applies only to the communication profile or to the hosts in the live broadcast profile. If an audience in the live broadcast profile calls this method, the audience role may be changed to a host.
Declared In
AgoraRtcEngineKit.h
Miscellaneous Video Control
– setVideoQualityParameters:
Sets the preferences for the video quality. (Live broadcast only).
- (int)setVideoQualityParameters:(BOOL)preferFrameRateOverImageQuality
Parameters
preferFrameRateOverImageQuality |
Sets the video quality preference:
|
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
Under unreliable network connections or the device’s CPU is overloaded, the video quality may be affected. You can use this method to choose the video smoothness (frame rate) over the image quality or vice versa.
Declared In
AgoraRtcEngineKit.h
– setLocalVideoMirrorMode:
Sets the local video mirror mode.
- (int)setLocalVideoMirrorMode:(AgoraVideoMirrorMode)mode
Parameters
mode |
Sets the local video mirror mode. See AgoraVideoMirrorMode. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
Use this method before startPreview, or the mirror mode does not take effect until you re-enable startPreview.
Declared In
AgoraRtcEngineKit.h
Camera Control
– switchCamera
Switches between the front and rear cameras. (iOS only.)
- (int)switchCamera
Return Value
- 0: Success.
- < 0: Failure.
Declared In
AgoraRtcEngineKit.h
– isCameraZoomSupported
Checks whether the camera zoom function is supported. (iOS only.)
- (BOOL)isCameraZoomSupported
Return Value
- YES: The device supports the camera zoom function.
- NO: The device does not support the camera zoom function.
Declared In
AgoraRtcEngineKit.h
– isCameraTorchSupported
Checks whether the camera flash function is supported. (iOS only.)
- (BOOL)isCameraTorchSupported
Return Value
- YES: The device supports the camera flash function.
- NO: The device does not support the camera flash function.
Discussion
Note:
The app generally enables the front camera by default. If your front camera flash is not supported, this method returns NO
. If you want to check if the rear camera flash is supported, call switchCamera before calling this method.
Declared In
AgoraRtcEngineKit.h
– isCameraFocusPositionInPreviewSupported
Checks whether the camera manual focus function is supported. (iOS only.)
- (BOOL)isCameraFocusPositionInPreviewSupported
Return Value
- YES: The device supports the camera manual focus function.
- NO: The device does not support the camera manual focus function.
Declared In
AgoraRtcEngineKit.h
– isCameraAutoFocusFaceModeSupported
Checks whether the camera auto-face focus function is supported. (iOS only.)
- (BOOL)isCameraAutoFocusFaceModeSupported
Return Value
- YES: The device supports the camera auto-face focus function.
- NO: The device does not support the camera auto-face focus function.
Declared In
AgoraRtcEngineKit.h
– setCameraZoomFactor:
Sets the camera zoom ratio. (iOS only.)
- (CGFloat)setCameraZoomFactor:(CGFloat)zoomFactor
Parameters
zoomFactor |
Sets the camera zoom factor. The value ranges between 1.0 and the maximum zoom supported by the device. |
---|
Return Value
- The set camera zoom factor, if this method call is successful.
- < 0: Failure.
Declared In
AgoraRtcEngineKit.h
– setCameraFocusPositionInPreview:
Sets the manual focus position. (iOS only.)
- (BOOL)setCameraFocusPositionInPreview:(CGPoint)position
Parameters
position |
Coordinates of the touch point in the view. |
---|
Return Value
- YES: Success.
- NO: Failure.
Declared In
AgoraRtcEngineKit.h
– setCameraTorchOn:
Enables the camera flash function. (iOS only.)
- (BOOL)setCameraTorchOn:(BOOL)isOn
Parameters
isOn |
|
---|
Return Value
- YES: Success.
- NO: Failure.
Declared In
AgoraRtcEngineKit.h
– setCameraAutoFocusFaceModeEnabled:
Enables the camera auto-face focus function. (iOS only.)
- (BOOL)setCameraAutoFocusFaceModeEnabled:(BOOL)enable
Parameters
enable |
|
---|
Return Value
- YES: Success.
- NO: Failure.
Declared In
AgoraRtcEngineKit.h
Screen Sharing
– startScreenCapture:withCaptureFreq:bitRate:andRect:
Starts screen sharing. (macOS only.)
- (int)startScreenCapture:(NSUInteger)windowId withCaptureFreq:(NSInteger)captureFreq bitRate:(NSInteger)bitRate andRect:(CGRect)rect
Parameters
windowId |
Sets to share the whole screen, a specified window, or a specified region:
|
---|---|
captureFreq |
(Mandatory) The captured frame rate. The value ranges between 1 fps and 15 fps. |
bitRate |
The captured bitrate. |
rect |
Specifies the screen-sharing region. |
Return Value
- 0: Success.
- < 0: Failure.
Declared In
AgoraRtcEngineKit.h
– stopScreenCapture
Stops screen sharing. (macOS only.)
- (int)stopScreenCapture
Return Value
- 0: Success.
- < 0: Failure.
Declared In
AgoraRtcEngineKit.h
– updateScreenCaptureRegion:
Updates the screen-sharing region. (macOS only.)
- (int)updateScreenCaptureRegion:(CGRect)rect
Parameters
rect |
Specifies the screen-sharing region. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Declared In
AgoraRtcEngineKit.h
Device Manager (macOS only)
– monitorDeviceChange:
Monitors the change of a device state. (macOS only.)
- (void)monitorDeviceChange:(BOOL)enabled
Parameters
enabled |
|
---|
Discussion
Use this method to monitor the plugging and swapping of external audio/video devices, for example, an external camera.
Declared In
AgoraRtcEngineKit.h
– enumerateDevices:
Retrieves all the devices in the system. (macOS only.)
- (NSArray<AgoraRtcDeviceInfo*> *_Nullable)enumerateDevices:(AgoraMediaDeviceType)type
Parameters
type |
Device type: AgoraMediaDeviceType. |
---|
Return Value
An AgoraRtcDeviceInfo NSArray object including all the devices, if this method call is successful.
Discussion
Note:
Do not call this method in the main thread.
This method returns an NSArray object, including all the audio/video devices in the system. Your app can use the AgoraRtcDeviceInfo array object to enumerate the devices.
Declared In
AgoraRtcEngineKit.h
– getDeviceInfo:
Retrieves the device information; such as a recording, playback, or video capture device. (macOS only.)
- (AgoraRtcDeviceInfo *_Nullable)getDeviceInfo:(AgoraMediaDeviceType)type
Parameters
type |
Device type: AgoraMediaDeviceType. |
---|
Return Value
- The device information (AgoraRtcDeviceInfo), if this method call is successful.
- nil: Failure.
Declared In
AgoraRtcEngineKit.h
– setDevice:deviceId:
Sets the playback, recording, or audio-sampling device. (macOS only.)
- (int)setDevice:(AgoraMediaDeviceType)type deviceId:(NSString *_Nonnull)deviceId
Parameters
type |
Device type: AgoraMediaDeviceType. |
---|---|
deviceId |
Device ID of the device, which can be retrieved by calling enumerateDevices. |
Return Value
- 0: Success.
- < 0: Failure.
Declared In
AgoraRtcEngineKit.h
– getDeviceVolume:
Retrieves the specified device’s volume. (macOS only.)
- (int)getDeviceVolume:(AgoraMediaDeviceType)type
Parameters
type |
Device type: AgoraMediaDeviceType. |
---|
Return Value
Returns the volume, if this method call is successful.
< 0: Failure.
Declared In
AgoraRtcEngineKit.h
– setDeviceVolume:volume:
Sets the specified device’s volume. (macOS only.)
- (int)setDeviceVolume:(AgoraMediaDeviceType)type volume:(int)volume
Parameters
type |
Device type: AgoraMediaDeviceType |
---|---|
volume |
Sets the specified device’s volume. The value ranges between 0 and 100. |
Return Value
- 0: Success.
- < 0: Failure.
Declared In
AgoraRtcEngineKit.h
– startRecordingDeviceTest:
Starts the microphone test. (macOS only.)
- (int)startRecordingDeviceTest:(int)indicationInterval
Parameters
indicationInterval |
Interval period (ms) of the reportAudioVolumeIndicationOfSpeakers callback cycle. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
This method tests whether the microphone works properly. Once the test starts, the SDK reports the volume information by using the reportAudioVolumeIndicationOfSpeakers callback.
Declared In
AgoraRtcEngineKit.h
– stopRecordingDeviceTest
Stops the microphone test. (macOS only.)
- (int)stopRecordingDeviceTest
Return Value
- 0: Success.
- < 0: Failure.
Discussion
This method stops testing the microphone. You must call this method to stop the test after calling the startRecordingDeviceTest method.
Declared In
AgoraRtcEngineKit.h
– startPlaybackDeviceTest:
Starts an audio playback device test. (macOS only.)
- (int)startPlaybackDeviceTest:(NSString *_Nonnull)audioFileName
Parameters
audioFileName |
Absolute path of the audio file for the test in UTF-8:
|
---|
Return Value
- 0: Success, and you can hear the sound of the specified audio file.
- < 0: Failure.
Discussion
This method tests whether the audio playback device works properly with a specified playback audio file.
Declared In
AgoraRtcEngineKit.h
– stopPlaybackDeviceTest
Stops the audio playback device test. (macOS only.)
- (int)stopPlaybackDeviceTest
Return Value
- 0: Success.
- < 0: Failure.
Discussion
This method stops testing the audio playback device. You must call this method to stop the test after calling startPlaybackDeviceTest.
Declared In
AgoraRtcEngineKit.h
– startCaptureDeviceTest:
Starts the capture device test. (macOS only.)
- (int)startCaptureDeviceTest:(NSView *_Nonnull)view
Parameters
view |
Input parameter, for displaying the video window. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
This method tests whether the current video capture device works properly. Ensure that you have called enableVideo before calling this method and that the parameter view window is valid.
Declared In
AgoraRtcEngineKit.h
– stopCaptureDeviceTest
Stops the capture device test. (macOS only.)
- (int)stopCaptureDeviceTest
Return Value
- 0: Success.
- < 0: Failure.
Discussion
This method stops testing the capture device. You must call this method to stop the test after calling startCaptureDeviceTest.
Declared In
AgoraRtcEngineKit.h
Miscellaneous Methods
– getCallId
Retrieves the current call ID.
- (NSString *_Nullable)getCallId
Return Value
callId The current call ID.
Discussion
When a user joins a channel on a client, a callId
is generated to identify the call from the client. Feedback methods, such as the rate and complain methods, must be called after the call ends to submit feedback to the SDK.
The rate and complain methods require the callId
parameter retrieved from the getCallId
method during a call. callId is passed as an argument into the rate and complain methods after the call ends.
Declared In
AgoraRtcEngineKit.h
– rate:rating:description:
Allows a user to rate a call after the call ends.
- (int)rate:(NSString *_Nonnull)callId rating:(NSInteger)rating description:(NSString *_Nullable)description
Parameters
callId |
Call ID retrieved from the getCallId method. |
---|---|
rating |
The rating of the call. |
description |
(Optional) Description of the rating. The string length must be less than 800 bytes. |
Return Value
- 0: Success.
< 0: Failure.
- Return AgoraErrorCodeInvalidArgument(-2):The passed argument is invalid. For example,
callId
invalid. - Return AgoraErrorCodeNotReady(-3):The SDK status is incorrect. For example, initialization failed.
- Return AgoraErrorCodeInvalidArgument(-2):The passed argument is invalid. For example,
Declared In
AgoraRtcEngineKit.h
– complain:description:
Allows a user to complain about the call quality after a call ends.
- (int)complain:(NSString *_Nonnull)callId description:(NSString *_Nullable)description
Parameters
callId |
Call ID retrieved from the getCallId method. |
---|---|
description |
(Optional) Description of the complaint. The character length must be less than 800 bytes. |
Return Value
- 0: Success.
- < 0: Failure.
Declared In
AgoraRtcEngineKit.h
– enableMainQueueDispatch:
Enables/Disables dispatching the delegate to the main queue.
- (int)enableMainQueueDispatch:(BOOL)enabled
Parameters
enabled |
Sets whether or not to dispatch the delegate to the main queue: |
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
If disabled, the app should dispatch the UI operating to the main queue.
Declared In
AgoraRtcEngineKit.h
+ getSdkVersion
Retrieves the Agora SDK version.
+ (NSString *_Nonnull)getSdkVersion
Return Value
The version of the current SDK in the string format. For example, 2.3.0
Discussion
This method returns the string of the version number.
Declared In
AgoraRtcEngineKit.h
– setLogFile:
Specifies an SDK output log file.
- (int)setLogFile:(NSString *_Nonnull)filePath
Parameters
filePath |
Absolute path of the log file. The string of the log file is in UTF-8. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
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 at Library/caches/agorasdk.log.
Declared In
AgoraRtcEngineKit.h
– setLogFilter:
Sets the output log level of the SDK.
- (int)setLogFilter:(NSUInteger)filter
Parameters
filter |
Log filter level: AgoraLogFilter. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
You can use one or a combination of the filters. The log level follows the sequence of OFF, CRITICAL, ERROR, WARNING, INFO, and DEBUG. Choose a level to see the logs preceding that level.
For example, if you set the log level to WARNING, you see the logs within levels CRITICAL, ERROR, and WARNING.
Declared In
AgoraRtcEngineKit.h
– getNativeHandle
Returns the native handler of the SDK engine.
- (void *_Nullable)getNativeHandle
Discussion
This interface is used to get the native C++ handler of the SDK engine used in special scenarios, such as registering the audio and video frame observer.
Declared In
AgoraRtcEngineKit.h
delegate
Sets and retrieves the SDK delegate.
@property (nonatomic, weak) id<AgoraRtcEngineDelegate> _Nullable delegate
Discussion
The SDK uses the delegate to inform the app on engine runtime events. All methods defined in the delegate are optional implementation methods.
Declared In
AgoraRtcEngineKit.h
Customized Methods (Technical Preview)
– setParameters:
Provides the technical preview functionalities or special customizations by configuring the SDK with JSON options.
- (int)setParameters:(NSString *_Nonnull)options
Parameters
options |
SDK options in JSON format. |
---|
Discussion
Note:
The JSON options are not public by default. Agora is working on making commonly used JSON options public in a standard way. Contact support@agora.io for more information.
Declared In
AgoraRtcEngineKit.h
– getParameter:args:
Retrieves the Agora SDK’s parameters for customization purposes.
- (NSString *_Nullable)getParameter:(NSString *_Nonnull)parameter args:(NSString *_Nullable)args
Discussion
Note:
This method is not public. Contact support@agora.io for more information.
Declared In
AgoraRtcEngineKit.h
Deprecated Methods
+ sharedEngineWithAppId:error:
Initializes the AgoraRtcEngineKit object.
+ (instancetype _Nonnull)sharedEngineWithAppId:(NSString *_Nonnull)AppId error:(void ( ^ _Nullable ) ( AgoraErrorCode errorCode ))errorBlock
Parameters
AppId |
App ID issued to the developers by Agora. Apply for a new App ID from Agora if it is missing from your kit. Each project is assigned a unique App ID. The App ID identifies your project and organization in the joinChannelByToken method to access the Agora Global Network, and enable one-to-one or one-to-more communication or live-broadcast sessions using a unique channel name for your App ID. |
---|---|
errorBlock |
Error code: AgoraErrorCode. |
Discussion
DEPRECATED from v2.3.
See Also
Declared In
AgoraRtcEngineKit.h
– pauseAudio
Disables the audio function in the channel.
- (int)pauseAudio
Return Value
- 0: Success.
- < 0: Failure.
Discussion
DEPRECATED from v2.3
See Also
Declared In
AgoraRtcEngineKit.h
– resumeAudio
Resumes the audio in the channel.
- (int)resumeAudio
Return Value
- 0: Success.
- < 0: Failure.
Discussion
DEPRECATED from v2.3
See Also
Declared In
AgoraRtcEngineKit.h
– setHighQualityAudioParametersWithFullband:stereo:fullBitrate:
Sets the high-quality audio parameters.
- (int)setHighQualityAudioParametersWithFullband:(BOOL)fullband stereo:(BOOL)stereo fullBitrate:(BOOL)fullBitrate
Parameters
fullband |
Sets whether to enable/disable full-band codec (48 kHz sampling rate). Not compatible with versions before v1.7.4.
|
---|---|
stereo |
Sets whether to enable/disable stereo codec. Not compatible with versions before v1.7.4.
|
fullBitrate |
Sets whether to enable/disable high-bitrate mode. Recommended in voice-only mode.
|
Return Value
- 0: Success.
- < 0: Failure.
See Also
Declared In
AgoraRtcEngineKit.h
– setSpeakerphoneVolume:
Sets the speakerphone volume. (macOS only.)
- (int)setSpeakerphoneVolume:(NSUInteger)volume
Parameters
volume |
Sets the speakerphone volume. The value ranges between 0 (lowest volume) and 255 (highest volume). |
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
DEPRECATED from v2.3.
See Also
Declared In
AgoraRtcEngineKit.h
– setVideoProfile:swapWidthAndHeight:
Sets the video profile.
- (int)setVideoProfile:(AgoraVideoProfile)profile swapWidthAndHeight:(BOOL)swapWidthAndHeight
Parameters
profile |
Sets the video profile. See AgoraVideoProfile. |
---|---|
swapWidthAndHeight |
Sets whether or not to swap the width and height of the video:
The width and height of the output video are consistent with the set video profile. |
Return Value
- 0: Success.
- < 0: Failure.
Discussion
DEPRECATED from v2.3.
Each video profile includes a set of parameters, such as the resolution, frame rate, and bitrate. If the camera device does not support the specified resolution, the SDK automatically chooses a suitable camera resolution, keeping the encoder resolution specified by setVideoProfile.
Note:
- Always set the video profile after calling the enableVideo method.
- Always set the video profile before calling the joinChannelByToken or startPreview method.
- If you do not need to set the video profile after joining the channel, call this method before enableVideo to reduce the render time of the first video frame.
See Also
Declared In
AgoraRtcEngineKit.h
– setVideoResolution:andFrameRate:bitrate:
Sets the video encoding profile manually.
- (int)setVideoResolution:(CGSize)size andFrameRate:(NSInteger)frameRate bitrate:(NSInteger)bitrate
Parameters
size |
Sets the size of the video. The highest value is 1280 × 720. |
---|---|
frameRate |
Sets the frame rate of the video. The highest value is 30. You can set it to 5, 10, 15, 24, 30, and so on. |
bitrate |
Sets the bitrate of the video. You need to manually work out the bitrate according to the width, height, and frame rate. See the bitrate table in AgoraVideoEncoderConfiguration. With the same width and height, the bitrate varies with the change of the frame rate:
For example, the resolution is 320 × 240 and the frame rate is 15 fps, hence, the bitrate is 200:
|
Discussion
DEPRECATED from v2.3.
If you do not need to change the video profile after joining the channel, Agora recommends calling this method before enableVideo to reduce the render time of the first video frame.
See Also
Declared In
AgoraRtcEngineKit.h
– configPublisher:
Configures the CDN live streaming before joining a channel.
- (int)configPublisher:(AgoraPublisherConfiguration *_Nonnull)config
Parameters
config |
CDN live streaming settings: AgoraPublisherConfiguration |
---|
Discussion
DEPRECATED
This method is deprecated. Agora recommends using the following methods instead:
Declared In
AgoraRtcEngineKit.h
– setVideoCompositingLayout:
Sets the picture-in-picture layout for the CDN live broadcast.
- (int)setVideoCompositingLayout:(AgoraRtcVideoCompositingLayout *_Nonnull)layout
Parameters
layout |
Sets the picture-in-picture layout. See AgoraRtcVideoCompositingLayout. |
---|
Discussion
DEPRECATED
This method is deprecated and Agora recommends using the setLiveTranscoding method.
This method sets the picture-in-picture layouts for live broadcasts. This method is only applicable when you want to push streams to the Agora server. When you push the stream to the server:
- Define a canvas, its width and height (video resolution), background color, and the total number of video streams you want to display.
- Define the position and size for each video stream on the canvas, and indicate whether the view is cropped or zoomed to fit.
The push stream application formats the information of the customized layouts as JSON and packages it in the Supplemental Enhancement Information (SEI) of each keyframe when generating the H.264 video stream and pushing it to the CDN live vendors through the RTMP protocol.
Note:
- Call this method after joining a channel.
- The app should only allow one user to call this method in the same channel. Call clearVideoCompositingLayout to remove the settings.
See Also
Declared In
AgoraRtcEngineKit.h
– clearVideoCompositingLayout
Removes the picture-in-picture layout settings.
- (int)clearVideoCompositingLayout
Discussion
DEPRECATED
Removes the picture-in-picture layout settings created by setVideoCompositingLayout.
Declared In
AgoraRtcEngineKit.h
– getDeviceId:
Retrieves the device type; such as a recording, playback, or video capture device. (macOS only.)
- (NSString *_Nullable)getDeviceId:(AgoraMediaDeviceType)type
Parameters
type |
Device type: AgoraMediaDeviceType. |
---|
Return Value
- Returns the device ID of the device, if this method call is successful.
- nil: Failure.
Discussion
DEPRECATED from v2.3.
See Also
Declared In
AgoraRtcEngineKit.h
– playEffect:filePath:loopCount:pitch:pan:gain:
Plays a specified audio effect.
- (int)playEffect:(int)soundId filePath:(NSString *_Nullable)filePath loopCount:(int)loopCount pitch:(double)pitch pan:(double)pan gain:(double)gain
Parameters
soundId |
ID of the audio effect. Each audio effect has a unique ID. Note: If you preloaded the audio effect into the memory through preloadEffect, ensure that the |
---|---|
filePath |
Absolute path of the audio effect file. |
loopCount |
Sets the number of times looping the audio effect:
|
pitch |
Sets whether to change the pitch of the audio effect. The value ranges between 0.5 and 2. The default value is 1 (no change to the pitch). The lower the value, the lower the pitch. |
pan |
Sets the spatial position of the audio effect. The value ranges between -1.0 and 1.0.
|
gain |
Sets the volume of the sound effect. The value ranges between 0.0 and 100.0 (default). The lower the value, the lower the volume of the sound effect. |
Return Value
- 0: Success.
- < 0: Failure.
Discussion
DEPRECATED from v2.3.
See Also
Declared In
AgoraRtcEngineKit.h
+ getMediaEngineVersion
Returns the Media Engine version.
+ (NSString *_Nonnull)getMediaEngineVersion
Return Value
string, Media engine version
Discussion
DEPRECATED from v2.3.
See Also
Declared In
AgoraRtcEngineKit.h
Deprecated Blocks
– audioVolumeIndicationBlock:
Reports which users are speaking and the speakers' volume.
- (void)audioVolumeIndicationBlock:(void ( ^ _Nullable ) ( NSArray *_Nonnull speakers , NSInteger totalVolume ))audioVolumeIndicationBlock
Parameters
audioVolumeIndicationBlock |
This block includes:
|
---|
Discussion
DEPRECATED from v1.1.
This callback is disabled by default and can be enabled by the enableAudioVolumeIndication method.
In the returned speaker’s array:
- If the
uid
is 0 (the local user is the speaker), the returned volume is thetotalVolume
. - If the
uid
is not 0 and thevolume
is 0, the specified user did not speak. - If a
uid
is found in the previous speaker’s array but not in the current speaker’s array, the specified user did not speak.
Declared In
AgoraRtcEngineKit.h
– firstLocalVideoFrameBlock:
Occurs when the engine renders the first local video frame on the video window.
- (void)firstLocalVideoFrameBlock:(void ( ^ _Nullable ) ( NSInteger width , NSInteger height , NSInteger elapsed ))firstLocalVideoFrameBlock
Parameters
firstLocalVideoFrameBlock |
This block includes:
|
---|
Discussion
DEPRECATED from v1.1.
See Also
Declared In
AgoraRtcEngineKit.h
– firstRemoteVideoDecodedBlock:
Occurs when the engine decodes the first video frame from a specific remote user.
- (void)firstRemoteVideoDecodedBlock:(void ( ^ _Nullable ) ( NSUInteger uid , NSInteger width , NSInteger height , NSInteger elapsed ))firstRemoteVideoDecodedBlock
Parameters
firstRemoteVideoDecodedBlock |
This block includes:
|
---|
Discussion
DEPRECATED from v1.1.
See Also
Declared In
AgoraRtcEngineKit.h
– firstRemoteVideoFrameBlock:
Occurs when the first remote video frame is rendered.
- (void)firstRemoteVideoFrameBlock:(void ( ^ _Nullable ) ( NSUInteger uid , NSInteger width , NSInteger height , NSInteger elapsed ))firstRemoteVideoFrameBlock
Parameters
firstRemoteVideoFrameBlock |
This block includes:
|
---|
Discussion
DEPRECATED from v1.1.
See Also
Declared In
AgoraRtcEngineKit.h
– userJoinedBlock:
Occurs when a user joins the channel.
- (void)userJoinedBlock:(void ( ^ _Nullable ) ( NSUInteger uid , NSInteger elapsed ))userJoinedBlock
Parameters
userJoinedBlock |
This block includes:
|
---|
Discussion
DEPRECATED from v1.1.
If there are other users in the channel when this user joins, the SDK also reports to the app on the existing users who are already in the channel.
See Also
Declared In
AgoraRtcEngineKit.h
– userOfflineBlock:
Occurs when a user leaves the call or goes offline.
- (void)userOfflineBlock:(void ( ^ _Nullable ) ( NSUInteger uid ))userOfflineBlock
Parameters
userOfflineBlock |
This block includes the user ID, |
---|
Discussion
DEPRECATED from v1.1.
The SDK reads the timeout data to determine if a user leaves the channel (or goes offline). If no data packet is received from the user within 15 seconds, the SDK assumes the user is offline. Sometimes a weak network connection may lead to false detections; therefore, Agora recommends using signaling for reliable offline detection.
See Also
Declared In
AgoraRtcEngineKit.h
– userMuteAudioBlock:
Occurs when a remote user’s audio stream is muted/unmuted.
- (void)userMuteAudioBlock:(void ( ^ _Nullable ) ( NSUInteger uid , BOOL muted ))userMuteAudioBlock
Parameters
userMuteAudioBlock |
This block includes:
|
---|
Discussion
DEPRECATED from v1.1.
See Also
Declared In
AgoraRtcEngineKit.h
– userMuteVideoBlock:
Occurs when a remote user’s video stream pauses/resumes playing.
- (void)userMuteVideoBlock:(void ( ^ _Nullable ) ( NSUInteger uid , BOOL muted ))userMuteVideoBlock
Parameters
userMuteVideoBlock |
This block includes:
|
---|
Discussion
DEPRECATED from v1.1.
See Also
Declared In
AgoraRtcEngineKit.h
– localVideoStatBlock:
Reports the statistics of the uploading local video streams once every two seconds.
- (void)localVideoStatBlock:(void ( ^ _Nullable ) ( NSInteger sentBitrate , NSInteger sentFrameRate ))localVideoStatBlock
Parameters
localVideoStatBlock |
This block includes:
|
---|
Discussion
DEPRECATED from v1.1.
See Also
Declared In
AgoraRtcEngineKit.h
– remoteVideoStatBlock:
Reports the statistics of receiving remote video streams once every two seconds.
- (void)remoteVideoStatBlock:(void ( ^ _Nullable ) ( NSUInteger uid , NSInteger delay , NSInteger receivedBitrate , NSInteger receivedFrameRate ))remoteVideoStatBlock
Parameters
remoteVideoStatBlock |
This block includes:
|
---|
Discussion
DEPRECATED from v1.1.
See Also
Declared In
AgoraRtcEngineKit.h
– cameraReadyBlock:
Occurs when the camera turns on and is ready to capture the video.
- (void)cameraReadyBlock:(void ( ^ _Nullable ) ( void ))cameraReadyBlock
Discussion
DEPRECATED from v1.1.
See Also
Declared In
AgoraRtcEngineKit.h
– connectionLostBlock:
Occurs when the connection between the SDK and the server is lost.
- (void)connectionLostBlock:(void ( ^ _Nullable ) ( void ))connectionLostBlock
Discussion
DEPRECATED from v1.1.
Declared In
AgoraRtcEngineKit.h
– rejoinChannelSuccessBlock:
Occurs when a user rejoins the channel after disconnection due to network problems.
- (void)rejoinChannelSuccessBlock:(void ( ^ _Nullable ) ( NSString *_Nonnull channel , NSUInteger uid , NSInteger elapsed ))rejoinChannelSuccessBlock
Parameters
rejoinChannelSuccessBlock |
This block includes:
|
---|
Discussion
When the client loses connection with the server because of network problems, the SDK automatically attempts to reconnect and triggers this callback upon reconnection.
DEPRECATED from v1.1.
See Also
Declared In
AgoraRtcEngineKit.h
– rtcStatsBlock:
Reports the RtcEngine runtime statistics once every two seconds.
- (void)rtcStatsBlock:(void ( ^ _Nullable ) ( AgoraChannelStats *_Nonnull stat ))rtcStatsBlock
Parameters
rtcStatsBlock |
RtcEngine runtime statistics. See AgoraChannelStats. |
---|
Discussion
DEPRECATED from v1.1.
See Also
Declared In
AgoraRtcEngineKit.h
– leaveChannelBlock:
Occurs when a user leaves the channel.
- (void)leaveChannelBlock:(void ( ^ _Nullable ) ( AgoraChannelStats *_Nonnull stat ))leaveChannelBlock
Parameters
leaveChannelBlock |
Statistics of the call. See AgoraChannelStats. |
---|
Discussion
DEPRECATED from v1.1.
When the app calls the leaveChannel method, the SDK uses this callback to notify the app that a user leaves the channel.
With this callback, the app retrieves information, such as the call duration and the statistics of the data received/transmitted by audioQualityOfUid.
See Also
Declared In
AgoraRtcEngineKit.h
– audioQualityBlock:
Reports the audio quality of the current call once every two seconds.
- (void)audioQualityBlock:(void ( ^ _Nullable ) ( NSUInteger uid , AgoraNetworkQuality quality , NSUInteger delay , NSUInteger lost ))audioQualityBlock
Parameters
audioQualityBlock |
This block includes:
|
---|
Discussion
DEPRECATED from v1.1.
See Also
Declared In
AgoraRtcEngineKit.h
– networkQualityBlock:
Reports the network quality of a specified user in a communication or live broadcast channel once every two seconds.
- (void)networkQualityBlock:(void ( ^ _Nullable ) ( NSUInteger uid , AgoraNetworkQuality txQuality , AgoraNetworkQuality rxQuality ))networkQualityBlock
Parameters
networkQualityBlock |
This block includes:
|
---|
Discussion
DEPRECATED from v1.1.
See Also
Declared In
AgoraRtcEngineKit.h
– lastmileQualityBlock:
The last mile network quality of the local user is reported once every two seconds after enableLastmileTest is called.
- (void)lastmileQualityBlock:(void ( ^ _Nullable ) ( AgoraNetworkQuality quality ))lastmileQualityBlock
Parameters
lastmileQualityBlock |
Network quality. See AgoraNetworkQuality. |
---|
Discussion
DEPRECATED from v1.1.
Declared In
AgoraRtcEngineKit.h
– mediaEngineEventBlock:
Reports a media engine event.
- (void)mediaEngineEventBlock:(void ( ^ _Nullable ) ( NSInteger code ))mediaEngineEventBlock
Discussion
DEPRECATED from v1.1.
Declared In
AgoraRtcEngineKit.h