The Interactive Gaming API is composed of the Objective-C Interface and C++ Interface,

This page provides the Objective-C interface, with which you can integrate the voice and video function into your app on iOS. To refer to the C++ Interface, see C++ Interface.

Basic Methods (AgoraRtcEngineKit)

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

Initializes (sharedEngineWithAppId)

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

This method initializes the AgoraRtcEngineKit class as a singleton instance. Call this method to initialize the service before using the AgoraRtcEngineKit object.

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

Name Description
appId The App ID issued to you by Agora. Apply for a new one from Agora if it is missing in your kit.
delegate The AgoraRtcEngineDelegate Class

Implements a Live Voice Broadcast

Sets the Channel Profile (setChannelProfile)

- (int)setChannelProfile:(AgoraChannelProfile)profile;

This method configures the channel profile. RtcEngine needs to know what scenario the application is in to apply different methods for optimization.

The Agora Native SDK supports the following profiles:

Profile Description
Communication Default setting. This is used in one-on-one calls, where all users in the channel can talk.
Live Broadcast Live Broadcast. Host and audience roles that can be set by calling the setClientRole method. The host sends and receives voice, while the audience receives voice only with the sending function disabled.
Gaming Gaming Mode. Any user in the channel can talk freely. This mode uses the codec with low-power consumption and low bitrate by default.
  • Only one profile can be used at the same time in the same channel. If you want to switch to another profile, use destroy to destroy the current RtcEngine and create a new one using the sharedEngineWithAppId method before calling this method to set the new channel profile.
  • Ensure that different App IDs are used for different channel profiles.
  • This method must be called and configured before a user joins a channel because the channel profile cannot be configured when the channel is in use.
Name Description
profile

The channel profile. Choose one of the following:

  • AgoraChannelProfileCommunication = 0: (Default) Communication
  • AgoraChannelProfileLiveBroadcasting = 1: Live Broadcast
  • AgoraChannelProfileGame = 2: Gaming
Return Value
  • 0: Success.
  • < 0: Failure.

Sets the User Role (setClientRole)

- (int)setClientRole:(AgoraClientRole)role;

In a Live-broadcasr profile, this method allows you to:

  • Set the user role as a host or an audience (default) before joining a channel.
  • Switch the user role after joining a channel.
Name Description
role The user role in a live broadcast:
  • AgoraClientRoleBroadcaster = 1: Host.
  • AgoraClientRoleAudience = 2: (Default) Audience.)
Return Value
  • 0: Success.
  • < 0: Failure.

Enables the Audio Mode (enableAudio)

- (int)enableAudio;

This method enables the audio mode. The app can call this method before joining a channel. This function is enabled by default.

Name Description
Return Value
  • 0: Success.
  • < 0: Failure.

This method enables the internal engine and still works after calling the leaveChannel method.

Disables/Re-enables the Local Audio Function (enableLocalAudio)

- (int)enableLocalAudio:(BOOL)enabled;

When an app joins a channel, 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 capturing and handling.
This method does not affect receiving or playing the remote audio streams, and is applicable to scenarios where the user wants to receive the remote audio streams without sending any audio stream to other users in the channel.
The SDK triggers the didMicrophoneEnabled callback once the local audio function is disabled or re-enabled.

  • Call this method after calling the joinChannelByToken method.
  • This method is different from the muteLocalAudioStream method:
    • enableLocalAudio: Disables/Re-enables the local audio capturing and processing.
    • muteLocalAudioStream: Stops/Continues sending the local audio streams.
Name Description
enabled
  • true: Re-enable the local audio function, that is, to start local audio capturing and processing.
  • false: Disable the local audio function, that is, to stop local audio capturing and processing.
Return Value
  • 0: Success.
  • < 0: Failure.

Disables the Audio Mode (disableAudio)

- (int)disableAudio;

This method disables the audio mode.

Name Description
Return Value
  • 0: Success.
  • < 0: Failure.

This method disables the internal engine and still works after you call the leaveChannel method.

Allows a User to Join a Channel (joinChannelByToken)

- (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;

This method allows a user to join 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 using different App IDs cannot call each other. Once in a call, the user must call the leaveChannel method to exit the current call before joining another channel. This method call is asynchronous; therefore, it can be called 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.

Once this method call is successful, the SDK triggers a callback. If both the joinChannelSuccessBlock and didJoinChannel callbacks are implemented, the priority of joinChannelSuccessBlock is higher than didJoinChannel, thus didJoinChannel is ignored. If you want to use didJoinChannel, set joinChannelSuccessBlock as nil.

A channel does not accept duplicate UIDs, such as two users with the same UID. If your app supports logging in a user from different devices at the same time, ensure that you use different UIDs. For example, if you already used the same UID, make the UIDs different by adding the respective device ID to the UID. This is not applicable if your app does not support a user logging in from different devices at the same time. In this case, when you log in a new device, you will be logged out from the other device.

Name Description
token

A token generated by the application.

This parameter is optional if the user uses a static App ID. In this case, pass NIL as the parameter value.

If the user uses a token, Agora issues an additional App Certificate to the you. You can then generate a token using the algorithm and App Certificate provided by Agora for user authentication on the server.

In most cases, the static App ID suffices. For added security, use a token.

channelName

A string providing the unique channel name for the AgoraRTC session. The length must be within 64 bytes.

The following is the supported scope:

  • The 26 lowercase English letters: a to z
  • The 26 uppercase English letters: A to Z
  • The 10 numbers: 0 to 9
  • Space
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
info (Optional) Any additional information you want to add. [1] It can be set as a NIL Sting or channel related information. Other users in the channel do not receive this information.
uid (Optional) User ID: A 32-bit unsigned integer ranging from 1 to (2^32-1). It must be unique. If not assigned (or set to 0), the SDK assigns one and returns it in the joinSuccessBlock callback. The app must record and maintain the returned value, as the SDK does not maintain it.
joinSuccessBlock Callback on the user successfully joining the channel.

[1] For example, when a host wants to customize the resolution and bitrate for a live broadcast channel with CDN live enabled, you can include them in this parameter in JSON format. For example, {“owner”:true, …, “width”:300, “height”:400, “bitrate”:100}. Only when neither width, height, and bitrate is 0 can the bitrate and resolution settings take effect.

When joining a channel, the SDK calls setCategory AVAudioSessionCategoryPlayAndRecord to set AVAudioSession to PlayAndRecord mode. The app should not set it to any other mode. When setting to this mode, the sound being played (for example, a ringtone) is interrupted.

Allows a User to Leave a Channel (leaveChannel)

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

This method allows a user to leave a channel, such as hanging up or exiting a call. After joining a channel, the user must call this method to end the call before joining another one.

This method releases all resources related to the call and asynchronous. The user has not actually left the channel when the method call returns. When the user leaves the channel, the SDK triggers the didLeaveChannelWithstats callback.

If you call the destroy method immediately after calling the leaveChannel method, the leaveChannel process is interrupted, and the SDK does not trigger the didLeaveChannelWithstats callback.

Name Description
leaveChannelBlock Callback on the user successfully leaving the channel.
Return Value
  • 0: Success.
  • < 0: Failure.

Sets the Local Voice Pitch (setLocalVoicePitch)

- (int) setLocalVoicePitch:(double) pitch;

This method changes the voice pitch of the local speaker.

Name Description
pitch Voice frequency. The value ranges between 0.5 and 2.0. The default value is 1.0.
Return Value
  • 0: Success.
  • < 0: Failure.

Sets the Playback Position and Volume of the Audio Effects Sent from the Remote User (setRemoteVoicePosition)

- (int)setRemoteVoicePosition:(int)uid pan:(double)pan gain:(double)gain;

This method sets the playback position and volume of the audio effects sent from the remote user.

This method is valid only for earphones and is invalid when the speakerphone is enabled.

Name Description
uid

User ID of the remote user.

pan

Sets whether to change the spatial position of the audio effect. The value ranges between -1 and 1:

  • 0: The audio effect shows right ahead.
  • -1: The audio effect shows on the left.
  • 1: The audio effect shows on the right.
gain

Sets whether to change the volume of a single audio effect. The value ranges between 0.0 and 100.0. The default value is 100.0. The smaller the value is, the lower the volume of the audio effect.

Return Value
  • 0: Success.
  • < 0: Failure.

Sets to Voice-only Mode (setVoiceOnlyMode)

- (int)setVoiceOnlyMode:(bool)enable;

This method sets to voice-only mode (transmits the audio stream only) and the other streams are ignored; for example, the sound of keyboard strokes.

Name Description
enable
  • True: Enable voice-only mode.
  • False: Disable voice-only mode.
Return Value
  • 0: Success.
  • < 0: Failure.

Sets the Local Voice Equalization (setLocalVoiceEqualizationOfBandFrequency)

- (int)setLocalVoiceEqualizationOfBandFrequency:(AgoraAudioEqualizationBandFrequency)bandFrequency withGain:(NSInterger)gain;

This method sets the local voice equalization.

Name Description
bandFrequency The band frequency. The value ranges between 0 to 9; representing the respective 10-band center frequencies of the voice effects, including 31, 62, 125, 500, 1k, 2k, 4k, 8k, and 16k Hz.
gain Gain of each band (dB). The value ranges between -15 and 15.
Return Value
  • 0: Success.
  • < 0: Failure.

Sets the Local Voice Reverberation (setLocalVoiceReverbOfType)

- (int)setLocalVoiceReverbOfType:(AgoraAudioReverbType)reverbType withValue:(NSInterger)value;

This method sets the local voice reverberation.

Name Description
reverbType The reverberation types. This method contains five reverberation types. For details, see the description of each value:
value
  • AgoraAudioReverbDryLevel = 0, (dB, [-20,10]), level of the dry signal.
  • AgoraAudioReverbWetLevel = 1, (dB, [-20,10]), level of the early reflection signal (wet signal).
  • AgoraAudioReverbRoomSize = 2, ([0, 100]), room size of the reflection.
  • AgoraAudioReverbWetDelay = 3, (ms, [0, 200]), length of the initial latency of the wet signal in ms.
  • AgoraAudioReverbStrength = 4, ([0, 100]), length of the late reverberation.
Return Value
  • 0: Success.
  • < 0: Failure.

Implements a Live Video Broadcast

Enables the Video Mode (enableVideo)

- (int)enableVideo;

This method enables the video mode. 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 in the video mode. If you call this method during a call, the service switches from the audio to video mode. To disable the video mode, call the disableVideo method.

Name Description
Return Value
  • 0: Success.
  • < 0: Failure.

This method enables the internal engine and still works after you call the leaveChannel method.

Disables the Video (disableVideo)

- (int)disableVideo;

This method disables the video mode. You can call this method either before joining a channel or during a call. If you call this method before joining a channel, the service starts in the audio mode. If you call this method during a call, the service switches from the video to audio mode. To enable the video mode, call the enableVideo method.

Name Description
Return Value
  • 0: Success.
  • < 0: Failure.

This method disables the internal engine and still works after you call the leaveChannel method.

Enables the Local Video (enableLocalVideo)

- (int)enableLocalVideo:(BOOL)enabled;

This method enables/disables the local video, which is only applicable to the scenario when the user only wants to watch the remote video without sending any video stream to the other user.

  • Call this method after calling the enableVideo method. Otherwise, this method may not work properly.

  • After you call the enableVideo method, the local video is enabled by default. This method is used to enable and disable the local video while the remote video remains unaffected.

Name Description
enabled

Sets to enable the local video:

  • YES: (Default) Enable the local video.
  • NO: Disable the local video. Once the local video is disabled, the remote users can no longer receive the video stream of this user, while this user can still receive the video streams of other remote users. When enabled is set as NO, this method does not require a local camera.
Return value
  • 0: Success.
  • < 0: Failure.

This method enables/disables the internal engine and still works after you call the leaveChannel method.

Sets the Video Profile (setVideoProfile)

This method is deprecated. To set the video encoder profile, Agora recommends calling the setVideoEncoderConfiguration method.

- (int)setVideoProfile:(AgoraVideoProfile)profile
    swapWidthAndHeight:(BOOL)swapWidthAndHeight;

This method sets the video encoding profile. If the user does not need to set the video encoding profile after joining the channel, Agora recommends calling this method before calling the enableVideo method to minimize the time delay in receiving the first video frame.

Name Description
profile The video profile. See the Video Profile Definition Table for details.
swapWidthAndHeight

The width and height of the output video is consistent with that of the video profile you set. This parameter sets whether to swap the width and height of the stream:

  • True: Swap the width and height.
  • False: (Default) Do not swap the width and height.

Since the landscape or portrait mode of the output video can be decided directly by the video profile, Agora recommends setting this parameter as default.

Return Value
  • 0: Success.
  • < 0: Failure.

Video Profile Definition Table

Video Profile Resolution (Width x Height) Frame Rate (fps) Bitrate
120P 160 x 120 15 65
120P_3 120 x 120 15 50
180P 320 x 180 15 140
180P_3 180 x 180 15 100
180P_4 240 x 180 15 120
240P 320 x 240 15 200
240P_3 240 x 240 15 140
240P_4 424 x 240 15 220
360P 640 x 360 15 400
360P_3 360 x 360 15 260
360P_4 640 x 360 30 600
360P_6 360 x 360 30 400
360P_7 480 x 360 15 320
360P_8 480 x 360 30 490
360P_9 640 x 360 15 600
360P_10 640 x 360 24 800
360P_11 640 x 360 24 800
480P 640 x 480 15 500
480P_3 480 x 480 15 400
480P_4 640 x 480 30 750
480P_6 480 x 480 30 600
480P_8 848 x 480 15 610
480P_9 848 x 480 30 930
480P_10 640 x 480 10 400
720P 1280 x 720 15 1130
720P_3 1280 x 720 30 1710
720P_5 960 x 720 15 910
720P_6 960 x 720 30 1380

Whether the video can achieve 720p resolution depends on the performance and capabilities of the device. Devices with lower performance may experience low frame rates when using 1080p.

Sets the Video Resolution (setVideoResolution)

This method is deprecated. To set the video encoder profile, Agora recommends calling the setVideoEncoderConfiguration method.

- (int)setVideoResolution: (CGSize)size andFrameRate: (NSInteger)frameRate bitrate: (NSInteger) bitrate;

If the video profiles listed in the table do not meet your needs, use this method to manually set the width, height, frame rate, and bitrate of the video. If the user does not need to set the video encoding profile after joining a channel, Agora recommends calling this method before calling the enableVideo method to minimize the time delay in receiving the first video frame.

Name Description
size Size of the video that you want to set. The highest value is 1280 x 720.
frameRate Frame rate of the video that you want to set. The highest value is 30. You can set it to 5, 10, 15, 24, 30, and so on.
bitrate

Bitrate of the video that you want to set. You need to manually work out the bitrate according to the width, height, and frame rate. With the same width and height, the bitrate varies with the change of the frame rate:

  • If the frame rate is 5 fps, divide the recommended bitrate in the table by 2.
  • If the frame rate is 15 fps, use the recommended bitrate in the table.
  • If the frame rate is 30 fps, multiply the recommended bitrate in the table by 1.5.
  • Calculate your bitrate with the ratio if you choose other frame rates.

If the bitrate you set is beyond the proper range, the SDK automatically adjusts it to a value within the range.

Sets the Local Video View (setupLocalVideo)

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

This method configures the video display settings on the local machine. The app calls this method to bind with the video window (view) of the local video stream and configure the video display settings. Call this method after initialization to configure the local video display settings before joining a channel. After leaving the channel, the bind is still valid, which means the window still displays. To unbind the view, set the view value to NIL when calling the setupLocalVideo method.

Name Description
local

Video display settings. VideoCanvas class:

  • view: Video display window (view).
  • renderMode: Video display mode.
    • AgoraVideoRenderModeHidden (1): Uniformly scale the video until it fills the visible boundaries. One dimension of the video may have clipped contents.
    • AgoraVideoRenderModeFit (2): Uniformly scale the video until one of its dimension fits the boundary. Areas that are not filled due to the disparity in the aspect ratio are filled with black.
  • Return value: The local user ID as set in the joinChannel method.
Return Value
  • 0: Success.
  • < 0: Failure.

Sets the Remote Video View (setupRemoteVideo)

- (int)setupRemoteVideo:(AgoraRtcVideoCanvas * _Nonnull)remote;

This method binds the remote user to the video display window, that is, sets the view for the user of the specified uid. Usually the app specifies the uid of the remote video in this method call before the user joins a channel. If the remote uid is unknown to the app, set it later when the app receives the onUserJoined callback.

If the Video Recording function is enabled, the Video Recording Service joins the channel as a dummy client, which means other clients also receive the didJoinedOfUid callback. Your app should not bind the dummy client with the view, because the dummy client does not send any video stream. If your app cannot recognize the dummy client, bind the dummy client with the view when the SDK triggers the firstRemoteVideoDecodedOfUid callback. To unbind the user with the view, set view as null. After the user leaves the channel, the SDK unbinds the remote user.

Name Description
remote

Video display settings. VideoCanvas class:

  • view: Video display window (view).

  • renderMode: Video display mode.

    • AgoraVideoRenderModeHidden (1): Uniformly scale the video until it fills the visible boundaries. One dimension of the video may have clipped contents.
    • AgoraVideoRenderModeFit (2): Uniformly scale the video until one of its dimension fits the boundary. Areas that are not filled due to the disparity in the aspect ratio are filled with black.
Return Value
  • 0: Success.
  • < 0: Failure.

Enables Dual-stream Mode (enableDualStreamMode)

- (int)enableDualStreamMode:(BOOL)enabled;

This method sets the stream mode to single- (default) or dual-stream mode. After enabled is set as YES, the receiver can choose to receive the high-stream (high-resolution high-bitrate) or low-stream (low-resolution low-bitrate) video.

Name Description
enabled

The mode is in single stream or dual stream:

  • True: Dual stream.
  • False: Single stream.
Return Value
  • 0: Success.
  • < 0: Failure.

Sets the Remote Video-stream Type (setRemoteVideoStream)

- (int)setRemoteVideoStream:(NSUInteger)uid
                       type:(AgoraVideoStreamType)streamType;

This method specifies the video-stream type of the remote user to be received by the local user when the remote user sends dual streams.

  • If dual-stream mode is enabled by calling the enableDualStreamMode method, you receive the high-stream video by default. This method allows the app to adjust the corresponding video-stream type according to the size of the video window to save the bandwidth and resources.

  • If dual-stream mode is not enabled, you receive the high-stream video by default.

The result after calling this method is returned in the didApiCallExecute callback. The Agora SDK receives the high-stream video by default to save the bandwidth. If needed, users can switch to the low-stream video using this method.

Name Description
uid User ID
streamType

Sets the video-stream size.

The video-stream types:

  • AgoraVideoStreamTypeHigh(0): High-stream video.
  • AgoraVideoStreamTypeLow(1): Low-stream video.
Return Value
  • 0: Success.
  • < 0: Failure.

Sets the Default Remote Video Stream Type (setRemoteDefaultVideoStreamType)

- (int)setRemoteDefaultVideoStreamType:(AgoraVideoStreamType)streamType;

This method sets the default remote video stream type to high- or low-stream.

Name Description
streamType

The default remote video stream type:

  • AgoraVideoStreamTypeHigh = 0: The high-stream video.
  • AgoraVideoStreamTypeLow = 1: The low-stream video.
Return Value
  • 0: Success.
  • < 0: Failure.

Sets the High-quality Video Preferences (setVideoQualityParameters)

- (int)setVideoQualityParameters:(BOOL)preferFrameRateOverImageQuality;

This method allows you to set the video preferences.

Name Description
preferFrameRateOverImageQuality

The video preference to be set:

  • True: Frame rate over image quality.
  • False: (Default) Image quality over frame rate.
Return Value
  • 0: Success.
  • < 0: Failure.

Starts a Video Preview (startPreview)

- (int)startPreview;

This method starts a local video preview before joining a channel. Before using this method, you need to:

  • Call the setupLocalVideo method to set up the local preview window and configure the attributes.
  • Call the enableVideo method to enable the video.

Once the local video preview is enabled, the preview does not stop if you call the leaveChannel method to leave the channel. To stop the preview, call the stopPreview method.

Name Description
Return Value
  • 0: Success.
  • < 0: Failure.

Stops the Video Preview (stopPreview)

- (int)stopPreview;

This method stops the local video preview and closes the video.

Name Description
Return Value
  • 0: Success.
  • < 0: Failure.

Sets the Local Video Display Mode (setLocalRenderMode)

- (int)setLocalRenderMode:(AgoraVideoRenderMode) mode;

This method configures the local video display mode. The app can call this method multiple times to change the display mode.

Name Description
mode

Configures the video display mode:

  • AgoraVideoRenderModeHidden (1): Uniformly scale the video until it fills the visible boundaries. One dimension of the video may have clipped contents.
  • AgoraVideoRenderModeFit (2): Uniformly scale the video until one of its dimension fits the boundary. Areas that are not filled due to the disparity in the aspect ratio are filled with black.
Return Value
  • 0: Success.
  • < 0: Failure.

Sets the Remote Video Display Mode (setRemoteRenderMode)

- (int)setRemoteRenderMode:(NSUInteger)uid
                      mode:(AgoraVideoRenderMode) mode;

This method configures the remote video display mode. The app can call this method multiple times to change the display mode.

Name Description
uid The user ID of the remote user sending the video stream.
mode

Configures the video display mode:

  • AgoraVideoRenderModeHidden (1): Uniformly scale the video until it fills the visible boundaries. One dimension of the video may have clipped contents.
  • AgoraVideoRenderModeFit (2): Uniformly scale the video until one of its dimension fits the boundary. Areas that are not filled due to the disparity in the aspect ratio are filled with black.
Return Value
  • 0: Success.
  • < 0: Failure.

Sets the Local Video Mirror Mode (setLocalVideoMirrorMode)

- (int)setLocalVideoMirrorMode:(AgoraVideoMirrorMode) mode;

This method sets the local video mirror mode. Use this method before calling the startPreview method or this method does not work until you call the startPreview method again.

  typedef NS_ENUM(NSUInteger, AgoraVideoMirrorMode) {
    AgoraVideoMirrorModeAuto = 0,
    AgoraVideoMirrorModeEnabled = 1,
    AgoraVideoMirrorModeDisabled = 2,
};

Camera Management

Switches Between Front and Back Cameras (switchCamera)

- (int)switchCamera;

This method switches between front and back cameras.

Name Description
Return Value
  • 0: Success.
  • < 0: Failure.

Checks whether the Camera Zoom Function is Supported (isCameraZoomSupported)

- (BOOL)isCameraZoomSupported;

It returns:

  • True: The device supports the camera zoom function.
  • False: The device does not support the camera zoom function.

Checks whether the Camera Flash Function is Supported (isCameraTorchSupported)

- (BOOL)isCameraTorchSupported;

It returns:

  • True: The device supports the camera flash function.
  • False: The device does not support the camera flash function.

The app enables the front camera by default. If your front camera does not support front camera flash, this method returns False. To check if the rear camera flash is supported, call the switchCamera method before calling this method.

Checks whether the Camera Manual Focus Function is Supported (isCameraFocusPositionInPreviewSupported)

- (BOOL)isCameraFocusPositionInPreviewSupported;

It returns:

  • True: The device supports the manual focus function.
  • False: The device does not support the manual focus function.

Checks whether the Camera Auto Focus Function is Supported (isCameraAutoFocusFaceModeSupported)

- (BOOL)isCameraAutoFocusFaceModeSupported;

It returns:

  • True: The device supports the auto focus function.
  • False: The device does not support the auto focus function.

Sets the Camera Zoom Ratio (setCameraZoomFactor)

- (CGFloat)setCameraZoomFactor:(CGFloat)zoomFactor;
Name Description
factor The camera zoom factor. The value ranges between 1.0 to the maximum zoom supported by the device.

Sets the Manual Focus Position (setCameraFocusPositionInPreview)

- (BOOL)setCameraFocusPositionInPreview:(CGPoint)position;
Name Description
positionX Horizontal coordinate of the touch point in the view.
positionY Vertical coordinate of the touch point in the view.

Enables the Camera Flash (setCameraTorchOn)

- (BOOL)setCameraTorchOn:(BOOL)isOn;
Name Description
isOn Whether or not to enable the camera flash function: True/False.

Enables the Camera Auto Focus Function (setCameraAutoFocusFaceModeEnabled)

- (BOOL)setCameraAutoFocusFaceModeEnabled:(BOOL)enable;
Name Description
enabled Whether or not to enable the camera auto focus function: True/False.

Enables Web SDK Interoperability (enableWebSdkInteroperability)

- (int)enableWebSdkInteroperability:(BOOL)enabled;

This method enables interoperability with the Agora Web SDK.

Name Description
enabled

Whether or not to enable interoperability with the Agora Web SDK:

  • True: Enable interoperability.
  • False: Disable interoperability.
Return Value
  • 0: Success.
  • < 0: Failure.

Sets the Audio Route

Sets the Default Audio Route (setDefaultAudioRouteToSpeakerPhone)

- (int)setDefaultAudioRouteToSpeakerphone:(BOOL)defaultToSpeaker;

This method sets whether the received audio is routed to the earpiece or the speakerphone.

  • Call this method only if you want to change the default settings.
  • This method only works in the audio mode.
  • Call this method before calling the joinChannel method.

If you do not call this method, the audio is routed to the earpiece by default.

Name Description
defaultToSpeaker
  • YES: The audio is routed to the speakerphone.
  • NO: The audio is routed to the earpiece.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Enable the Speakerphone (setEnableSpeakerphone)

- (int)setEnableSpeakerphone:(BOOL)enableSpeaker;

This method enables the audio routing to the speaker. Ensure that the joinChannelByKey method has been executed successfully before calling this method.

The SDK calls setCategory AVAudioSessionCategoryPlayAndRecord with options to configure the headset/speaker, so any sound will be interrupted when calling this method.

After this method is called, the SDK returns the didAudioRouteChanged callback, indicating that the audio routing has changed.

Name Description
enableSpeaker
  • Yes: Switches to the speaker.
  • No: Switches to the headset.
Return Value
  • 0: Success.
  • < 0: Failure.

Checks Whether the Speakerphone is Enabled (isSpeakerphoneEnabled)

- (BOOL)isSpeakerphoneEnabled;

This method checks whether the speakerphone is enabled.

Name Description
Return Value
  • Yes: Enabled.
  • No: Disabled.

Enables In-ear Monitoring (enableInEarMonitoring)

- (int)enableInEarMonitoring:(BOOL)enabled;

This method enables or disables in-ear monitoring.

Name Description
enabled
  • YES: Enables in-ear monitoring.
  • NO: (Default) Disables in-ear monitoring.
Return Value
  • 0: Success.
  • < 0: Failure.

Sets the Audio Session Operational Restriction (setAudioSessionOperationRestriction)

- (void)setAudioSessionOperationRestriction:(AgoraAudioSessionOperationRestriction)restriction;

The SDK and the app can both configure the audio session by default. The app may occassionally 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 before or after joining the channel.
  • 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.
Name Description
restriction

The operational restriction of the SDK on the audio session. It is a bit mask.

  • AgoraAudioSessionOperationRestrictionNone = 0: No restrictions. The SDK has full control over the audio session operation.
  • AgoraAudioSessionOperationRestrictionSetCategory = 1: The SDK cannot change the category of the audio session.
  • AgoraAudioSessionOperationRestrictionConfigurationSession = 1 << 1: The SDK cannot change the category, mode or categoryOptions of the audio session.
  • AgoraAudioSessionOperationRestrictionDeactivateSession = 1 << 2: The SDK cannot deactivate the session when it leaves the channel.
  • AgoraAudioSessionOperationRestrictionAll = 1 << 7: Restricts the SDK from manipulating the audio session.

Sets the Audio Volume

Enables the Callback to Report on which Users are Speaking and the Speakers' Volume (enableAudioVolumeIndication)

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

This method allows the SDK to regularly report to the app on which users are speaking and the volume of the speakers. Once the method is enabled, the SDK returns the volume indications at the set time internal in the reportAudioVolumeIndicationOfSpeakers and audioVolumeIndicationBlock callbacks, regardless of whether anyone is speaking in the channel.

Name Description
interval

Time interval between two consecutive volume indications:

  • <= 0: Disables the volume indication.
  • > 0: The time interval (ms) between two consecutive volume indications. Agora recommends setting it to more than 200 ms. Do not set it lower than 10 ms, or the SDK does not trigger the reportAudioVolumeIndicationOfSpeakers callback.
smooth The smoothing factor that determines the sensitivity of this method. The value ranges between 0 and 10. Agora recommends setting it as 3. The bigger the value, the higher the sensitivity.
Return Value
  • 0: Success.
  • < 0: Failure.

Sets the Volume of the In-ear Monitor (setInEarMonitoringVolume)

- (int)setInEarMonitoringVolume:(NSInteger)volume;

This method sets the volume of the in-ear monitor.

Name Description
volume Volume of the in-ear monitor. The value ranges between 0 and 100. The default value is 100.
Return Value
  • 0: Success.
  • < 0: Failure.

Gets the Volume of the Audio Effect (getEffectsVolume)

- (double)getEffectsVolume;

This method gets the volume of the audio effect. The value ranges between 0.0 and 100.0.

Sets the Volume of the Audio Effect (setEffectsVolume)

- (int)setEffectsVolume:(double)volume;

This method sets the volume of the audio effects.

Name Description
volume Volume of the audio effect. The value ranges between 0.0 and 100.0 (default).
Return Value
  • 0: Success.
  • < 0: Failure.

Adjusts the Audio Effect Volume in Real Time (setVolumeOfEffect)

- (int)setVolumeOfEffect:(int)soundId
              withVolume:(double)volume;

This method adjusts the volume of the specified audio effect in real time.

Name Description
soundId ID of the audio effect. Each audio effect has a unique ID.
volume Volume of the specified audio effect. The value ranges between 0.0 and 100.0 (default).
Return Value
  • 0: Success.
  • < 0: Failure.

Plays an Audio Effect (playEffect)

- (int)playEffect:(int)soundId
         filePath:(NSString * _Nullable)filePath
        loopCount:(int)loopCount
            pitch:(double)pitch
              pan:(double)pan
             gain:(double)gain
          publish:(BOOL)publish;

This method plays the specified audio effect.

Name Description
soundId ID of the specified audio effect. Each audio effect has a unique ID [4].
filePath The absolute path of the audio effect file.
loopCount

Sets the number of times playing the audio effect.

  • 0: Plays the audio effect once.
  • 1: Plays the audio effect twice.
  • -1: Plays the audio effect in a loop indefinitely until the SDK calls the stopEffect or stopAllEffects method.
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 smaller the value, the lower the pitch.
pan

Spatial position of the local audio effect. The value ranges between -1.0 and 1.0.

  • 0.0: The audio effect shows ahead.
  • 1.0: The audio effect shows on the right.
  • -1.0: The audio effect shows on the left.
gain Volume of the audio effect. The value ranges between 0.0 and 100,0. The default value is 100.0. The smaller 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:

  • True: The audio effect, played locally, is published to the Agora Cloud and the remote users can hear it.
  • False: The audio effect, played locally, is not published to the Agora Cloud and the remote users cannot hear it.
Return Value
  • 0: Success.
  • < 0: Failure.

[4] If you preloaded the audio effect into the memory through the preloadEffect method, ensure that the soundID value is set as the same value as in the preloadEffect method.

In v2.1.x, the following method (not recommended by Agora) is used.

- (int) playEffect: (int) soundId
          filePath: (NSString*) filePath
              loop: (BOOL) loop
             pitch: (double) pitch
               pan: (double) pan
              gain: (double) gain;

Stops Playing an Audio Effect (stopEffect)

- (int)stopEffect:(int)soundId;

This method stops playing a specified audio effect.

Name Description
soundId ID of the audio effect. Each audio effect has a unique ID.
Return Value
  • 0: Success.
  • < 0: Failure.

Stops Playing all Audio Effects (stopAllEffects)

- (int)stopAllEffects;

This method stops playing all the audio effects.

Preload an Audio Effect (preloadEffect)

- (int)preloadEffect:(int)soundId
            filePath:(NSString * _Nullable) filePath;

This method preloads the specified audio effect file (compressed audio file) to the memory.

To ensure smooth communication, note the size of the audio effect file. Agora recommends using this method to preload the audio effect before you call the joinChannelByToken method.

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

Releases an Audio Effect (unloadEffect)

- (int)unloadEffect:(int)soundId;

This method releases the specified preloaded audio effect from the memory.

Name Description
soundId ID of the audio effect. Each audio effect has a unique ID.
Return Value
  • 0: Success.
  • < 0: Failure.

Pauses an Audio Effect (pauseEffect)

- (int)pauseEffect:(int)soundId;

This method pauses the specified audio effect.

Name Description
soundId ID of the audio effect. Each audio effect has a unique ID.
Return Value
  • 0: Success.
  • < 0: Failure.

Pauses all Audio Effects (pauseAllEffects)

- (int)pauseAllEffects;

This method pauses all audio effects.

Name Description
Return Value
  • 0: Success.
  • < 0: Failure.

Resumes Playing an Audio Effect (resumeEffect)

- (int)resumeEffect:(int)soundId;

This method resumes playing the specified audio effect.

Name Description
soundId ID of the audio effect. Each audio effect has a unique ID.
Return Value
  • 0: Success.
  • < 0: Failure.

Resumes Playing all Audio Effects (resumeAllEffects)

- (int) esumeAllEffects;

This method resumes playing all audio effects.

Mutes the Audio and Video Streams

Mutes the Local Audio Stream (muteLocalAudioStream)

- (int)muteLocalAudioStream:(BOOL)mute;

This method mutes/unmutes the local audio stream.

This method works only when a user is in a channel. After the user leaves the channel, all mute states are reset.

Name Description
mute
  • True: Mutes the local audio.
  • False: Unmutes the local audio.
Return Value
  • 0: Success.
  • < 0: Failure.

Mutes all Remote Audio Streams (muteAllRemoteAudioStreams)

- (int)muteAllRemoteAudioStreams:(BOOL)mute;

This method mutes/unmutes all remote audio streams.

This method works only when a user is in a channel. After the user leaves the channel, all mute states are reset.

Name Description
muted
  • True: Stops playing all remote audio streams.
  • False: Plays all remote audio streams.
Return Value
  • 0: Success.
  • < 0: Failure.

Mutes the Specified Remote User's Audio Stream (muteRemoteAudioStream)

- (int)muteRemoteAudioStream:(NSUInteger)uid muted:(BOOL)mute;

The method mutes/unmutes the specified remote user’s audio stream.

When mute is set as True, this method stops playing audio streams without affecting the audio stream receiving process.
This method works only when a user is in a channel. After the user leaves the channel, all mute states are reset.

Name Description
uid User ID of the remote user.
mute
  • True: Stops playing the specified remote user’s audio stream.
  • False: Plays the specified remote user’s audio stream.
Return Value
  • 0: Success.
  • < 0: Failure.

Mutes the Local Video Stream (muteLocalVideoStream)

- (int)muteLocalVideoStream:(BOOL)muted;

This method enables/disables sending a local video stream to the network.

When muted is set as YES, this method does not disable the camera and thus does not affect the retrieval of the local video stream. This method responds faster than the enableLocalVideo method with enabled set as YES.
This method works only when a user is in a channel. After the user leaves the channel, all mute states are reset.

Name Description
mute
  • Yes: Stops sending the local video stream to the network.
  • No: Sends the local video stream to the network.
Return Value
  • 0: Success.
  • < 0: Failure.

Mutes all Remote Video Streams (muteAllRemoteVideoStreams)

- (int)muteAllRemoteVideoStreams:(BOOL)mute;

This method enables/disables playing all remote video streams.

When mute is set as Yes, this method stops playing video streams without affecting the video stream receiving process.
This method works only when a user is in a channel. After the user leaves the channel, all mute states are reset.

Name Description
mute
  • Yes: Stops playing all remote video streams.
  • No: Plays all remote video streams.
Return Value
  • 0: Success.
  • < 0: Failure.

Mutes the Specified Remote User's Video Stream (muteRemoteVideoStream)

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

This method pauses/resumes receiving the specified remote user’s video stream.

When mute is set as Yes, this method stops playing video streams without affecting the video stream receiving process.
This method works only when a user is in a channel. After the user leaves the channel, all mute states are reset.

Name Description
uid User ID of the specified user.
mute
  • Yes: Stops playing a specified user’s video stream.
  • No: Plays a specified user’s video stream.
Return Value
  • 0: Success.
  • < 0: Failure.

Audio Mixing

Starts Audio Mixing (startAudioMixing)

- (int)startAudioMixing:(NSString *  _Nonnull)filePath
               loopback:(BOOL)loopback
                replace:(BOOL)replace
                  cycle:(NSInteger)cycle;

This method mixes the specified local audio file with the audio stream from the microphone; or, it 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 loop playbacks. This method also supports online music playback.

  • To use this method, ensure the iOS device is 8.0 or later.
  • Call this method when you are in a channel. Otherwise, it may cause issues.
Name Description
filePath Name and path of the local audio file to be mixed.
  • Supported audio formats: mp3, aac, m4a, 3gp, and wav.
  • loopback
    • True: Only the local user can hear the remix or the replaced audio stream.
    • False: Both users can hear the remix or the replaced audio stream.
    replace
    • True: The content of the local audio file replaces the audio stream from the microphone.
    • False: Mix the local audio file with the audio stream from the microphone.
    cycle Number of loop playbacks:
    • Positive integer: Number of loop playbacks.
    • -1:Infinite loop.
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Stops Audio Mixing (stopAudioMixing)

    - (int)stopAudioMixing;

    This method stops audio mixing. Call this method when you are in a channel.

    Name Description
    Return Value
    • 0: Success.
    • < 0: Failure.

    Pauses Audio Mixing (pauseAudioMixing)

    - (int)pauseAudioMixing;

    This method pauses audio mixing. Call this method when you are in a channel.

    Name Description
    Return Value
    • 0: Success.
    • < 0: Failure.

    Resumes Audio Mixing (resumeAudioMixing)

    - (int)resumeAudioMixing;

    This method resumes audio mixing. Call this method when you are in a channel.

    Name Description
    Return Value
    • 0: Success.
    • < 0: Failure.

    Adjusts the Audio Mixing Volume (adjustAudioMixingVolume)

    - (int)adjustAudioMixingVolume:(NSInteger)volume;

    This method adjusts the volume during audio mixing. Call this method when you are in a channel.

    Name Description
    volume The audio mixing volume. The value ranges between 0 and 100. By default, 100 is the original volume.
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Gets the Audio Mixing Duration (getAudioMixingDuration)

    - (int)getAudioMixingDuration;

    This method gets the duration (ms) of audio mixing. Call this method when you are in a channel.

    Gets Audio Mixing Playback Position (getAudioMixingCurrentPosition)

    - (int)getAudioMixingCurrentPosition;

    This method gets the playback position (ms) of the audio mixing. Call this method when you are in a channel.

    Sets the Playback Starting Position of the Audio Mixing File (setAudioMixingPosition)

    - (int)setAudioMixingPosition:(NSInteger)pos;

    This method sets the playback starting position of the audio mixing file to where you want to play from instead of from the beginning.

    Name Description
    pos Integer. The playback starting position of the audio mixing file (ms).

    Recording

    Starts an Audio Recording (startAudioRecording)

    - (int)startAudioRecording:(NSString * _Nonnull)filePath
                       quality:(AgoraAudioRecordingQuality)quality;

    This method starts an audio recording. The SDK allows recording during a call, which supports the following formats:

    • .wav: Large file size with high fidelity.
    • .aac: Small file size with low fidelity.

    Ensure that the directory to save the recording exists and is writable. Call this method after the calling the joinChannelByToken method. The recording automatically stops when you call the leaveChannel method.

    Name Description
    filePath Full file path of the recording file. The string of the file name is in UTF-8.
    quality

    Audio recording quality:

    • AgoraRtc_AudioRecordingQuality_Low = 0: Low quality, the file size is around 1.2 MB after 10 minutes of recording.
    • AgoraRtc_AudioRecordingQuality_Low = 1: Medium quality, the file size is around 2 MB after 10 minutes of recording.
    • AgoraRtc_AudioRecordingQuality_Low = 2: High quality, the file size is around 3.75 MB after 10 minutes of recording.
    Return Value
    • 0: Success.
    • < 0: Failure.

    Stops an Audio Recording (stopAudioRecording)

    - (int)stopAudioRecording;

    This method stops recording on the client.

    Call this method before calling the leaveChannel method. Otherwise, the recording automatically stops when you call the leaveChannel method.

    Name Description
    Return Value
    • 0: Success.
    • < 0: Failure.

    Adjusts the Recording Volume (adjustRecordingSignalVolume)

    - (int)adjustRecordingSignalVolume:(NSInteger)volume;

    This method adjusts the recording volume.

    Name Description
    volume

    Recording volume. The value ranges between 0 and 400:

    • 0: Mute.
    • 100: Original volume.
    • 400: (Maximum) Four times the original volume with signal clipping protection.
    Return Value
    • 0: Success.
    • < 0: Failure.

    Adjusts the Playback Volume (adjustPlaybackSignalVolume)

    - (int)adjustPlaybackSignalVolume:(NSInteger)volume;

    This method adjusts the playback volume.

    Name Description
    volume

    Playback volume. The value ranges between 0 and 400:

    • 0: Mute.
    • 100: Original volume.
    • 400: (Maximum) Four times the original volume with signal clipping protection.
    Return Value
    • 0: Success.
    • < 0: Failure.

    Encryption

    Enables Built-in Encryption with an Encryption Password (setEncryptionSecret)

    - (int)setEncryptionSecret:(NSString * _Nullable)secret;

    This method specifies an encryption password to enable built-in encryption before joining a channel. 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 function is disabled.

    Do not use this function in CDN live.

    Name Description
    secret Encryption Password
    Return Value
    • 0: Success.
    • < 0: Failure.

    Sets the Built-in Encryption Mode (setEncryptionMode)

    - (int)setEncryptionMode:(NSString * _Nullable)encryptionMode;

    The Agora Native SDK supports built-in encryption, which is in AES-128-XTS mode by default. If you want to use other modes, call this method to set the encryption mode.

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

    Call the setEncryptionSecret method to enable the built-in encryption function before calling this method.

    Do not use this function in CDN live.

    Name Description
    encryptionMode

    Encryption mode. The following modes are supported:

    • “aes-128-xts”: 128-bit AES encryption, XTS mode.
    • “aes-128-ecb”: 128-bit AES encryption, ECB mode.
    • “aes-256-xts”: 256-bit AES encryption, XTS mode.
    • “”: When set as NUL string, the encryption is in “aes-128-xts” by default.
    Return Value
    • 0: Success.
    • < 0: Failure.

    Establishes a Data Stream

    Creates a Data Stream (createDataStream)

    - (int)createDataStream:(NSInteger * _Nonnull)streamId
                   reliable:(BOOL)reliable
                    ordered:(BOOL)ordered;

    This method creates a data stream. Each user can only have up to five data channels at the same time.

    Set the reliable and ordered parameters both as True or both as False. Do not set one as True and the other as False.

    Name Description
    reliable
    • True: The recipients receive the data from the sender within 5 seconds. If the recipient does not receive the sent data within 5 seconds, the data channel reports an error to the app.
    • False: The recipients may not receive any data, and the SDK does not report any error upon data missing.
    ordered
    • True: The recipients receive data in the sent order.
    • False: The recipients do not receive data in the sent order.
    Return Value
    • <0 : Returns an error code when it fails to create the data stream. [5]
    • >0 : Returns the Stream ID when the data stream is created.

    [5] The error code is related to the positive integer displayed in Error Codes and Warning Codes. For example, if it returns -2, then it indicates 2: ERR_INVALID_ARGUMENT in Error Codes and Warning Codes.

    Sends a Data Stream (sendStreamMessage)

    - (int)sendStreamMessage:(NSInteger)streamId
                        data:(NSData * _Nonnull)data;

    This method sends data stream messages to all users in a channel. Up to 30 packets can be sent per second in a channel with each packet having a maximum size of 1 kB. The API controls the data channel transfer rate. Each client can send up to 6 kB of data per second. Each user can have up to five data channels simultaneously.

    Name Description
    streamId Stream ID.
    message Data to be sent.
    Return Value When it fails to send the message, the following error code is returned: ERR_SIZE_TOO_LARGE/ERR_TOO_OFTEN/ERR_BITRATE_LIMIT

    Test and Detection

    Starts an Audio Call Test (startEchoTest)

    - (int)startEchoTest:(void(^ _Nullable)(NSString * _Nonnull channel, NSUInteger uid, NSInteger elapsed))successBlock;

    This method launches an audio call test to determine whether the audio devices (for example, the headset and speaker) and the network connection are working properly. In this test, the user first speaks and the recording is played back in 10 seconds. If the user can hear the recording in 10 seconds, the audio devices and network connection work properly.

    • After calling this method, call the stopEchoTest method to end the test. Otherwise, the app cannot run the next echo test, nor can it call the joinChannel method to start a new call.
    • This method is applicable only when the user role is broadcaster. If you switch the channel profile from Communication to Live Broadcast, call the setClientRole method to change the user role from audience (the default setting in the live broadcast profile) to broadcaster before using this method.
    Name Description
    successBlock Callback on successfully starting the echo test. See joinSuccessBlock in joinChannelByToken for a description of the callback parameters.
    Return Value
    • 0: Success.
    • < 0: Failure:
      • ERR_REFUSED (-5): Failed to launch the echo test, for example, initialization failed.

    Stops the Audio Call Test (stopEchoTest)

    - (int)stopEchoTest;

    This method stops an audio call test.

    Name Description
    Return Value
    • 0: Success.
    • < 0: Failure:
      • ERR_REFUSED(-5): Fails to stop the echo test. The echo test may not be running.

    Enables the Network Test (enableLastmileTest)

    - (int)enableLastmileTest;

    This method tests the quality of the user’s network connection and is disabled by default.

    This method is mainly used in two scenarios:

    • Before users join a channel, this method can be called to check the uplink network quality.
    • Before the audience in a channel switch to a host role, this method can be called to check the uplink network quality.

    In both scenarios, calling this method consumes extra network traffic, which affects the communication quality.

    Call the disableLastmileTest method to disable this test immediately once the users have received the onLastmileQuality callback before they join the channel or switch user roles.

    For current hosts, do not call this method.

    Name Description
    callId Call ID retrieved from the getCallId method.
    rating Rating for the call. The value ranges between 1 (lowest score) and 10 (highest score).
    description (Optional) A description of the call with a length less of than 800 bytes.
    Return Value
    • 0: Succeess.
    • < 0: Failure.
      • ERR_INVALID_ARGUMENT (-2): The passed argument is invalid. For example, callId is invalid.
      • ERR_NOT_READY (-3): The SDK status is incorrect. For example, initialization failed.

    Disables the Network Test (disableLastmileTest)

    - (int)disableLastmileTest;

    This method disables the network connection quality test.

    Name Description
    Return Value
    • 0: Success.
    • < 0: Failure.

    Feedback

    Retrieves the Current Call ID (getCallId)

    - (NSString * _Nullable)getCallId;

    When a user joins a channel on a client, callId is generated to identify the call from the client. You can call the rate and complain methods after a call ends to submit feedback to the SDK. These feedback methods require assigned values of the callId parameters. To use these feedback methods, call this method to retrieve the callId during the call, and then pass the value as an argument in the feedback methods after the call ends.

    Name Description
    Return Value Current call ID.

    Allows a User to Rate a Call (rate)

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

    This method allows a user rate a call and is called after the call ends.

    Name Description
    callId Call ID retrieved from the getCallId method.
    rating Rating for the call. The value ranges between 1 (lowest score) and 10 (highest score).
    description (Optional) A description of the call with a length less of than 800 bytes.
    Return Value
    • 0: Succeess.
    • < 0: Failure.
      • ERR_INVALID_ARGUMENT (-2): The passed argument is invalid. For example, callId is invalid.
      • ERR_NOT_READY (-3): The SDK status is incorrect. For example, initialization failed.

    Allows a User to Complain about the Call Quality (complain)

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

    This method allows a user to complain about the call quality and is called after a call ends.

    Name Description
    callId Call ID retrieved from the getCallId method.
    description (Optional) A description of the call with a length of less than 800 bytes.
    Return Value
    • 0: Succeess.
    • < 0: Failure.
      • ERR_INVALID_ARGUMENT (-2): The passed argument is invalid. For example, callId is invalid.
      • ERR_NOT_READY (-3): The SDK status is incorrect. For example, initialization failed.

    Added Functions

    Renews the Token (renewToken)

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

    This method renews the token.

    The token expires after a time period once the token schema is enabled when:

    • The rtcEngine:didOccurError: callback reports the ERR_TOKEN_EXPIRED(109) error, or
    • The rtcEngineRequestToken: callback reports the ERR_TOKEN_EXPIRED(109) error.

    The app should retrieve a new token and then call this method to renew it. Failure to do so results in the SDK disconnecting from the server.

    Name Description
    token Token to be renewed.
    Return Value
    • 0: Success.
    • < 0: Failure.

    Specifies a Log File (setLogFile)

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

    This method specifies an SDK output log file. The log file records all the log data of the SDK’s operation. Ensure that the directory to save the log file exists and is writable.

    Name Description
    filePath File path of the log file. The string of the log file is in UTF-8.
    Return Value
    • 0: Success.
    • < 0: Failure.

    The default log file location is at: sdcard/<appname>/agorasdk.log, where appname is the name of the app.

    Sets the Log Filter (setLogFilter)

    - (int)setLogFilter:(NSUInteger)filter;

    This method sets the output log levels of the SDK. You can use either one or a combination of the filters.

    The log level follows the sequence of Off, Critical, Error, Warning, Info, and Debug. Choose a level, and you can see the logs that precede that level.

    For example, if you set the log level as Warning, then you can see the logs in levels Critical, Error, and Warning.

    Name Description
    filter

    Set the levels of the filters:

    • AgoraLogFilterOff = 0: Output no log.
    • AgoraLogFilterDebug = 0x080f: Output all API logs.
    • AgoraLogFilterInfo = 0x000f: Output logs of the CRITICAL, ERROR, WARNING, and INFO levels.
    • AgoraLogFilterWarning = 0x000e: Output logs of the CRITICAL, ERROR, and WARNING levels.
    • AgoraLogFilterError = 0x000c: Output logs of the CRITICAL and ERROR levels.
    • AgoraLogFilterCritical = 0x0008: Output logs of the CRITICAL level.
    Return Value
    • 0: Success.
    • < 0: Failure.

    Destroys the Engine Instance (destroy)

    + (void)destroy;

    This method releases all resources used by the Agora SDK. This 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 the destroy method to destroy the created RtcEngine instance, no other methods in the SDK can be used and no callbacks occur. To start communications again, initialize sharedEngineWithappId to establish a new AgoraRtcEngineKit instance.

    • Use this method in the subthread.
    • This method call is synchronous. The result returns after the IRtcEngine 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.

    Gets the SDK Version (getSdkVersion)

    + (NSString * _Nonnull)getSdkVersion;

    This method returns the string of the SDK version number.

    Delegate Methods (AgoraRtcEngineDelegate)

    The SDK uses Delegate methods AgoraRtcEngineDelegate to report callbacks to the app. From v1.1, some Block callbacks in the SDK are replaced with Delegate callbacks. The old Block callbacks are therefore deprecated, but can still be used in the current version. However, Agora recommends replacing them with Delegate callbacks. The SDK calls the Block callback if a callback is defined in both Block and Delegate.

    The callbacks are returned in the main thread.

    Reports a Warning during SDK Runtime (didOccurWarning)

    - (void)rtcEngine:(AgoraRtcEngineKit *)engine didOccurWarning:(AgoraRtcErrorCode)warningCode;

    This callback reports a warning during SDK runtime. In most cases, the app can ignore the warning reported by the SDK because the SDK can usually fix the issue and resume running.

    For instance, the SDK may report an AgoraRtc_Error_OpenChannelTimeout(106) warning upon disconnection with the server and attempts to reconnect.

    Name Description
    warningCode The warning code.

    Reports an Error during SDK Runtime (didOccurError)

    - (void)rtcEngine:(AgoraRtcEngineKit *)engine didOccurError:(AgoraRtcErrorCode)errorCode;

    This callback reports an error during SDK runtime. In most cases, reporting an error means that the SDK cannot fix the issue and resume running, and therefore requires actions from the app or simply informs the user on the issue. For instance, the SDK reports an AgoraRtc_Error_StartCall(1002) error when failing to initialize a call. In this case, the app informs the user that the call initialization failed and calls the leaveChannel method to exit the channel.

    Name Description
    Engine The AgoraRtcEngineKit object.
    errorCode Error code.

    Occurs when an API Method Executes (didApiCallExecute)

    - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didApiCallExecute:(NSInteger)error api:(NSString * _Nonnull)api result:(NSString * _Nonnull)result;

    The SDK triggers this callback when an API method executes.

    Name Description
    error The error code that the SDK returns when the method call fails. If the SDK returns 0, then the method call is successful.
    api The API method that the SDK executes.
    result The result of calling the API method.

    Occurs when a User Joins a Channel (didJoinChannel)

    - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didJoinChannel:(NSString * _Nonnull)channel withUid:(NSUInteger)uid elapsed:(NSInteger) elapsed;

    This callback is the same as joinSuccessBlock in the joinChannelByToken method. The SDK triggers this callback when a user has successfully joined a specified channel.

    Name Description
    channel Channel name.
    uid

    User ID.

    If the uid is specified in the joinChannelByToken method, the SDK returns the specified ID. If not, the SDK returns a uid that is automatically assigned by the Agora server.

    elapsed Time elapsed (ms) from calling the joinChannelByToken method until the SDK triggers this callback.

    Occurs when a User Rejoins a Channel (didRejoinChannel)

    - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didRejoinChannel:(NSString * _Nonnull)channel withUid:(NSUInteger)uid elapsed:(NSInteger) elapsed;

    If the client loses connection with the server because of network problems, the SDK automatically attempts to reconnect, and triggers this callback upon reconnection, indicating that the user has rejoined the channel with the assigned channel ID and user ID.

    Name Description
    channel Channel name.
    uid User ID.
    elapsed Time elapsed (ms) from calling the joinChannelByToken method until the SDK triggers this callback.

    Occurs when a User Leaves a Channel (didLeaveChannelWithStats)

    - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didLeaveChannelWithStats:(AgoraChannelStats * _Nonnull)stats;

    When a user calls the leaveChannel method, the SDK trigger this callback. This callback is the same as leaveChannelBlock.

    Definition of AgoraChannelStats

    __attribute__((visibility("default"))) @interface AgoraChannelStats: NSObject
    @property (assign, nonatomic) NSInteger duration;
    @property (assign, nonatomic) NSInteger txBytes;
    @property (assign, nonatomic) NSInteger rxBytes;
    @property (assign, nonatomic) NSInteger txAudioKBitrate;
    @property (assign, nonatomic) NSInteger rxAudioKBitrate;
    @property (assign, nonatomic) NSInteger txVideoKBitrate;
    @property (assign, nonatomic) NSInteger rxVideoKBitrate;
    @property (assign, nonatomic) NSInteger lastmileDelay;
    @property (assign, nonatomic) NSInteger userCount;
    @property (assign, nonatomic) double cpuAppUsage;
    @property (assign, nonatomic) double cpuTotalUsage;
    @end
    Name Description
    stats

    Statistics of the call:

    • duration: Call duration (s), represented by an aggregate value.
    • txBytes: Total number of bytes transmitted, represented by an aggregate value.
    • rxBytes: Total number of bytes received, represented by an aggregate value.
    • txAudioKBitrate: Audio transmission bitrate in kbit/s, represented by an instantaneous value.
    • rxAudioKBitRate: Audio receiving bitrate in kbit/s, represented by an instantaneous value.
    • txVideoKBitRate: Video transmission bitrate in kbit/s, represented by an instantaneous value.
    • rxVideoKBitRate: Video receiving bitrate in kbit/s, represented by an instantaneous value.
    • lastmileDelay: The time delay (ms) from the client to the VO server.
    • users: The number of users in the channel when the user leaves the channel.
    • puTotalUsage: System CPU usage (%).
    • cpuAppUsage: Application CPU usage (%).

    Occurs when the Audio Route Changes (didAudioRouteChanged)

    - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didAudioRouteChanged:(AgoraAudioOutputRouting)routing;

    The SDK triggers this callback when the audio route changes. Here is the definition of AgoraAudioOutputRouting:

    typedef NS_ENUM(NSInteger, AgoraAudioOutputRouting)
    {
        AgoraAudioOutputRoutingDefault = -1,
        AgoraAudioOutputRoutingHeadset = 0,
        AgoraAudioOutputRoutingEarpiece = 1,
        AgoraAudioOutputRoutingHeadsetNoMic = 2,
        AgoraAudioOutputRoutingSpeakerphone = 3,
        AgoraAudioOutputRoutingLoudspeaker = 4,
        AgoraAudioOutputRoutingHeadsetBluetooth = 5
    };

    Occurs when the Microphone is Enabled/Disabled (didMicrophoneEnabled)

    - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didMicrophoneEnabled:(BOOL)enabled;
    Name Description
    enabled
    • True: The microphone is enabled.
    • False: The microphone is disabled.

    Reports the Audio Quality of the Current Call (audioQualityOfUid)

    - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine audioQualityOfUid:(NSUInteger)uid quality:(AgoraNetworkQuality)quality delay:(NSUInteger)delay lost:(NSUInteger)lost;

    This callback is the same as audioQualityBlock. During a call, the SDK triggers this callback once every two seconds to report on the audio quality of the current call.

    Name Description
    uid User ID of the speaker.
    quality

    Rating of the audio quality:

    • AgoraNetworkQualityUnknown(0): The network quality is unknown.
    • AgoraNetworkQualityExcellent(1): The network quality is excellent.
    • AgoraNetworkQualityGood(2): The network quality is quite good, but the bitrate may be slightly lower than excellent.
    • AgoraNetworkQualityPoor(3): Users can feel the communication slightly impaired.
    • AgoraNetworkQualityBad(4): Users can communicate only not very smoothly.
    • AgoraNetworkQualityVBad(5): The network is so bad that users can hardly communicate.
    • AgoraNetworkQualityDown(6): Users cannot communicate at all.
    delay Time delay (ms).
    lost The packet loss rate(%).

    Reports which Users are Speaking and the Speakers' Volume (reportAudioVolumeIndicationOfSpeakers)

    - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine reportAudioVolumeIndicationOfSpeakers:(NSArray<AgoraRtcAudioVolumeInfo *> * _Nonnull)speakers totalVolume:(NSInteger)totalVolume;

    The callback is the same as audioVolumeIndicationBlock. By default this callback is disabled. You can use the enableAudioVolumeIndication method to enable/disable this callback.

    Name Description
    speakers

    The speakers (array). Each speaker ():

    • uid: User ID of the speaker. By default, 0 is the local user.
    • volume: The volume of the speaker. The value ranges between 0 (lowest volume) and 255 (highest volume).
    totalVolume Total volume after audio mixing. The volume ranges between 0 (lowest volume) and 255 (highest volume).

    In the returned speakers array:

    • If uid is 0 (the local user is the speaker) the returned volume is the same as totalVolume.
    • If uid is not 0 and volume is 0, the user specified by the uid did not speak.
    • If a uid is in the previous speakers array but not in the current one, the user specified by the uid did not speak.

    Occurs when a Host Joins the Channel (didJoinedOfUid)

    - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didJoinedOfUid:(NSUInteger)uid elapsed:(NSInteger)elapsed;

    This callback is the same as userJoinedBlock and notifies the app the host has joined the channel. If the host is already in the channel when the app joins the channel, the SDK also reports to the app on the hosts who are already in the channel.

    In the live broadcast scenario:

    • The host receives this callback when another host joins the channel.
    • All the audience members in the channel can receive this callback when a new host joins the channel.
    • When a Web application joins the channel, the SDK triggers this callback as long as the Web application publishes streams.
    Name Description
    uid

    User ID of the host.

    If the uid is specified in the joinChannelByToken method, the SDK returns the specified ID. If not, the SDK returns an ID that is automatically assigned by the Agora server.

    elapsed Time elapsed (ms) from calling the joinChannelByToken method until the SDK triggers this callback.

    Occurs when a Host Leaves a Channel (didOfflineOfUid)

    - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didOfflineOfUid:(NSUInteger)uid reason:(AgoraUserOfflineReason)reason;

    This callback is the same as userOfflineBlock and reports that the host has left the call or gone offline.

    The SDK reads the timeout data to determine if a user has left the channel (or has gone offline). If no data package is received from the user in 15 seconds, the SDK assumes the user is offline. A poor network connection may lead to false detections; therefore, use signaling for reliable offline detection.

    Name Description
    uid User ID.
    reason

    The SDK triggers this callback when:

    • AgoraRtc_UserOffline_Quit(0): A user has quit the call.
    • AgoraRtc_UserOffline_Dropped(1): The SDK timed out and the user dropped offline because it has not received any data package within a time period. If a user quits the call and the message is not passed to the SDK (due to an unreliable channel), the SDK assumes the event has timed out.

    Occurs when a Remote User’s Audio Stream is Muted/Unmuted. (didAudioMuted)

    - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didAudioMuted:(BOOL)muted byUid:(NSUInteger)uid;

    This callback is the same as userMuteAudioBlock and reports that a remote user's audio stream is muted/unmuted.

    This callback returns invalid when the number of hosts in a channel exceeds 20.

    Name Description
    uid User ID.
    muted
    • Yes: The remote user's audio is muted.
    • No: The remote user's audio is unmuted.

    RtcEngine Statistics Callback (reportRtcStats)

    - (void)rtcEngine:(AgoraRtcEngineKit *)engine
    reportRtcStats:(AgoraRtcStats*)stats;

    Same as rtcStatsBlock. The SDK updates the application on the statistics of the RtcEngine runtime status once every two seconds.

    Name Description
    stat See descriptions in User Left Channel Callback (didLeaveChannelWithStats) .

    Channel Network Quality Callback (networkQuality)

    - (void)rtcEngine:(AgoraRtcEngineKit *)engine networkQuality:(NSUInteger)uid txQuality:(AgoraRtcQuality)txQuality rxQuality:(AgoraRtcQuality)rxQuality;

    This callback is triggered every 2 seconds to update the application on the current network quality of each user in a communication or live broadcast channel.

    Name Description
    uid
    User ID. The network quality of the user with this UID will be reported.

    If uid is 0, it reports the local network quality.

    txQuality

    The transmission quality of the user:

    • AgoraNetworkQualityUnknown(0): The network quality is unknown.
    • AgoraNetworkQualityExcellent(1): The network quality is excellent.
    • AgoraNetworkQualityGood(2): The network quality is quite good, but the bitrate may be slightly lower than excellent.
    • AgoraNetworkQualityPoor(3): Users can feel the communication slightly impaired.
    • AgoraNetworkQualityBad(4): Users can communicate only not very smoothly.
    • AgoraNetworkQualityVBad(5): The network is so bad that users can hardly communicate.
    • AgoraNetworkQualityDown(6): Users cannot communicate at all.
    rxQuality

    The receiving quality of the user:

    • AgoraNetworkQualityUnknown(0): The network quality is unknown.
    • AgoraNetworkQualityExcellent(1): The network quality is excellent.
    • AgoraNetworkQualityGood(2): The network quality is quite good, but the bitrate may be slightly lower than excellent.
    • AgoraNetworkQualityPoor(3): Users can feel the communication slightly impaired.
    • AgoraNetworkQualityBad(4): Users can communicate only not very smoothly.
    • AgoraNetworkQualityVBad(5): The network is so bad that users can hardly communicate.
    • AgoraNetworkQualityDown(6): Users cannot communicate at all.

    Remote Video State Changed Callback (remoteVideoStateChangedOfUid)

    - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine remoteVideoStateChangedOfUid:(NSUInteger)uid state:(AgoraVideoRemoteState)state;

    This callback indicates that the state of the remote video has changed.

    Name Description
    uid ID of the user whose video state has changed
    state

    The state of the remote video:

    • Running: the remote video is normal
    • Frozen: the remote video is frozen

    Connection Interrupted Callback (rtcEngineConnectionDidInterrupted)

    - (void)rtcEngineConnectionDidInterrupted:(AgoraRtcEngineKit * _Nonnull)engine;

    This method indicates that the SDK has lost connection with the server.

    This method is triggered upon connection lost, while the onConnectionLost method is triggered when the SDK attempts to reconnect after losing connection. Once the connection is lost, and if the application does not call leaveChannel, the SDK automatically tries to reconnect repeatedly.

    Connection Lost Callback (rtcEngineConnectionDidLost)

    - (void)rtcEngineConnectionDidLost:(AgoraRtcEngineKit * _Nonnull)engine;

    This callback indicates that the SDK has lost connection with the network, and it has remained unconnected for a period of time (10 seconds by default) despite that it attempts to reconnect. It is also triggered when the SDK fails to join the channel 10 seconds after it calls joinChannel. The SDK will keep trying to reconnect after this callback is triggered. Upon reconnection, an onRejoinChannelSuccess callback will then be triggered.

    Connection Banned Callback (rtcEngineConnectionDidBanned)

    - (void)rtcEngineConnectionDidBanned:(AgoraRtcEngineKit * _Nonnull)engine;

    This callback is triggered when your connection is banned by the Agora Server.

    First Local Audio Frame Received Callback (firstLocalAudioFrame)

    - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine firstLocalAudioFrame:(NSUInteger)uid elapsed:(NSInteger)elapsed;

    This callback method is triggered when the first local audio frame is received.

    Name Description
    uid The UID of the remote user whose audio frame is received.
    elapsed Time elapsed (ms) from calling joinChannel until this callback is triggered.

    First Remote Audio Frame Received Callback (firstRemoteAudioFrameOfUid)

    - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine firstRemoteAudioFrameOfUid:(NSUInteger)uid elapsed:(NSInteger)elapsed;

    This callback method is triggered when the first remote audio frame is received.

    Name Description
    uid The UID of the remote user whose audio frame is received.
    elapsed Time elapsed (ms) from calling joinChannel until this callback is triggered.

    First Local Video Frame Displayed Callback (firstLocalVideoFrameWithSize)

    - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine firstLocalVideoFrameWithSize:(CGSize)size elapsed:(NSInteger)elapsed;

    Same as firstLocalVideoFrameBlock. Indicates that the first local video frame is displayed on the video window.

    Name Description
    engine The AgoraRtcEngineKit Object
    elapsed Time elapsed (ms) from calling joinChannelByToken until this callback is triggered.

    First Remote Video Frame Received and Decoded Callback (firstRemoteVideoDecodedOfUid)

    - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine firstRemoteVideoDecodedOfUid:(NSUInteger)uid size:(CGSize)size elapsed:(NSInteger)elapsed;

    Same as firstRemoteVideoDecodedBlock. Indicates that the first remote video frame is received and decoded.

    Name Description
    engine The AgoraRtcEngineKit Object
    uid User ID of the user whose video stream is received.
    elapsed Time elapsed (ms) from calling joinChannelByToken until this callback is triggered.

    First Remote Video Frame Displayed Callback (firstRemoteVideoFrameOfUid)

    - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine firstRemoteVideoFrameOfUid:(NSUInteger)uid size:(CGSize)size elapsed:(NSInteger)elapsed;

    Same as firstRemoteVideoFrameBlock. Indicates that the first remote video frame is displayed on the screen.

    Name Description
    uid The user ID of the user whose video stream is received.
    size The size of the video (width and height).
    elapsed The time elapsed (ms) from calling joinChannelByToken until this callback is triggered.

    First Remote Video Frame Displayed Callback (firstRemoteVideoFrameOfUid)

    - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine firstRemoteVideoFrameOfUid:(NSUInteger)uid size:(CGSize)size elapsed:(NSInteger)elapsed;

    Same as firstRemoteVideoFrameBlock. Indicates that the first remote video frame is displayed on the screen.

    Name Description
    uid The user ID of the user whose video stream is received.
    size The size of the video (width and height).
    elapsed The time elapsed (ms) from calling joinChannelByToken until this callback is triggered.

    Other User Muted Audio Callback (didAudioMuted)

    - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didAudioMuted:(BOOL)muted byUid:(NSUInteger)uid;

    Same as userMuteAudioBlock. This callback indicates that some other user has muted/unmuted his/her audio streams.

    Currently, this callback returns invalid when the number of broadcasters in a channel exceeds 20, which will be improved in the future.

    Name Description
    uid User ID.
    muted
    • Yes: User has muted his/her audio.
    • No: User has unmuted his/her audio.

    Other User Paused/Resumed Video Callback (didVideoMuted)

    - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didVideoMuted:(BOOL)muted byUid:(NSUInteger)uid;

    Same as userMuteVideoBlock. This callback indicates that another user has paused/resumed his/her video streams.

    Name Description
    uid User ID.
    muted
    • Yes: User has paused his/her video.
    • No: User has unmuted his/her video.

    Other User Enabled/Disabled Video Callback (didVideoEnabled)

    - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didVideoEnabled:(BOOL)enabled byUid:(NSUInteger)uid;

    This callback indicates that some other user has enabled/disabled the video function. Disabling the video function means that the user can only use voice call, can neither show/send their own videos nor receive or display videos from other people.

    Name Description
    uid User ID
    enabled
    • YES: The user has enabled the video function and can enter a video call or video live broadcast.
    • NO: The user has disabled the video function and can only enter a voice session where the user can neither send or receive any video streams.

    Other User Enabled/Disabled Local Video Callback (didLocalVideoEnabled)

    - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didLocalVideoEnabled:(BOOL)enabled byUid:(NSUInteger)uid;

    This callback indicates that some other user has enabled/disabled the local video function.

    Name Description
    uid User ID
    enabled
    • YES: The user has enabled the local video function. Other users in the channel can see the video of this user.
    • NO: the user has disabled the local video function. Other users in the channel can no longer receive the video stream from this user, while this user can still receive the video streams from other users.

    Local Video Statistics Callback (localVideoStats)

    - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine localVideoStats:(AgoraRtcLocalVideoStats * _Nonnull)stats;

    Same as localVideoStatBlock.The SDK updates the application on local video streams uploading statistics once every two seconds.

    Definition of AgoraRtcLocalVideoStats

    __attribute__((visibility("default"))) @interface AgoraRtcLocalVideoStats : NSObject
    @property (assign, nonatomic) NSUInteger sentBitrate;
    @property (assign, nonatomic) NSUInteger sentFrameRate;
    @end
    Name Description
    engine Engine kit.
    stats

    Statistics of the local video, including:

    • sentBytes: Total bytes sent since last count.
    • sentFrames: Total frames sent since last count.

    Remote Video Statistics Callback (remoteVideoStats)

    - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine remoteVideoStats:(AgoraRtcRemoteVideoStats * _Nonnull)stats;

    Same as remoteVideoStatBlock. The SDK updates the application on the statistics of receiving remote video streams for each host once every 2 seconds. If there are muptiple remote hosts, this callback is triggered for multiple times every 2 seconds.

    Definition of AgoraRtcLocalVideoStats

    __attribute__((visibility("default"))) @interface AgoraRtcRemoteVideoStats : NSObject
    @property (assign, nonatomic) NSUInteger uid;
    @property (assign, nonatomic) NSUInteger delay __deprecated;
    @property (assign, nonatomic) NSUInteger width;
    @property (assign, nonatomic) NSUInteger height;
    @property (assign, nonatomic) NSUInteger receivedBitrate;
    @property (assign, nonatomic) NSUInteger receivedFrameRate;
    @property (assign, nonatomic) AgoraVideoStreamType rxStreamType;
    @end
    Name Description
    stats

    The statistics of the remote video, including:

    • uid: User ID of the user whose video streams are received.
    • delay: Time delay (ms).
    • width: Width of the remote video.
    • height: Height of the remote video.
    • receivedBitrate: Data receiving bitrate (kbit/s).
    • receivedFrameRate: Data receiving frame rate (fps).
    • rxStreamType: High Video Stream or Low Video Stream.

    Camera Ready Callback (rtcEngineCameraDidReady)

    - (void)rtcEngineCameraDidReady:(AgoraRtcEngineKit * _Nonnull)engine;

    Same as cameraReadyBlock. This callback indicates that the camera is turned on and ready to capture video.

    Video Stopped Callback (rtcEngineVideoDidStop)

    - (void)rtcEngineVideoDidStop:(AgoraRtcEngineKit * _Nonnull)engine;

    This callback indicates that the video is stopped. The application can use this callback to change the configuration of the view (for example, displaying other pictures in the view) after the video stops.

    Data Stream Received Callback (receiveStreamMessageFromUid)

    - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine receiveStreamMessageFromUid:(NSUInteger)uid streamId:(NSInteger)streamId data:(NSData * _Nonnull)data;

    This callback indicates that the local user has received the data stream from the other user within five seconds.

    Name Description
    uid User ID
    streamId Stream ID
    data Data received by the recipients.

    Data Stream Sent Failure Callback (didOccurStreamMessageErrorFromUid)

    - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didOccurStreamMessageErrorFromUid:(NSUInteger)uid streamId:(NSInteger)streamId error:(NSInteger)error missed:(NSInteger)missed cached:(NSInteger)cached;

    This callback indicates that the local user has not received the data stream from the other user within five seconds.

    Name Description
    uid User ID
    streamId Stream ID
    error
    • ERR_OK = 0, No error
    • ERR_NOT_IN_CHANNEL=113, the user is not in a channel
    • ERR_BITRATE_LIMIT=115, limited bitrate

    For more error code descriptions, see Error Codes and Warning Codes.

    missed The number of lost messages
    cached The number of incoming cached messages when the data stream is interrupted

    Active Speaker Detected Callback (ActiveSpeaker)

    - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine activeSpeaker:(NSUInteger)speakerUid;

    If you have used the enableAudioVolumeIndication API, this callback is triggered then the volume detecting unit has detected active speaker in the channel. Also returns with the uid of the active speaker.

    Name Description
    speakerUid The UID of the active speaker. By default, 0 means the local user. If needed, you can also add relative functions on your App, for example, the active speaker, once detected, will have his/her head portrait zoomed in.
    • You need to call enableAudioVolumeIndication to receive this callback.
    • The active speaker means the uid of the speaker who speaks at the highest volume during a certain period of time.

    Refer to the following code for the logic:

     - (void)rtcEngine:(AgoraRtcEngineKit *)engine activeSpeaker:(NSUInteger)speakerUid {
    [self switchToMainViewOfSpeaker:speakerUid];
    }

    User Role Changed Callback (didClientRoleChanged)

    - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didClientRoleChanged:(AgoraClientRole)oldRole newRole:(AgoraClientRole)newRole;

    This callback is triggered when the user role is switched, for example, from a host to an audience or vice versa.

    Name Description
    oldRole Role that you switched from.
    newRole Role that you switched to.

    Camera Focus Changed Callback (cameraFocusDidChanged)

    (void)rtcEngine:(AgoraRtcEngineKit* _Nonnull)engine cameraFocusDidChangedToRect:(CGRect)rect;

    This callback is triggered when the camera focus area has changed.

    Name Description
    rect The rectangle area in the camera zoom that specifies the focus area

    Video Size Changed Callback (videoSizeChangedOfUid)

    - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine videoSizeChangedOfUid:(NSUInteger)uid size:(CGSize)size rotation:(NSInteger)rotation;

    This callback indicates that the size of the video frame has changed.

    Parameter Description
    uid User ID.
    size Size (pixels) of the video frame.
    rotation New rotational angle of the video. Can be 0, 90, 180, or 270. It is set as 0 by default.

    Token Expired Callback (rtcEngineRequestToken)

    - (void)rtcEngineRequestToken:(AgoraRtcEngineKit * _Nonnull)engine;

    If a Token is specified when calling joinChannelByToken, and due to Token will be expired after a certain amount of time, and if SDK lost the connection with the Agora server out of network issues, it might need a new Token to reconnect to the server.

    This callback notifies the application of generating a new Token, and calling renewtoken to specify the newly generated Token.

    This function was previously provided in the callback report of didOccurError(): ERR_TOKEN_EXPIRED(109), ERR_INVALID_TOKEN(110). Starting from v1.7.3, the old method is still working, but it is recommended for you to put the related logic in this callback.

    This function was previously provided when the callback reported didOccurError(): ERR_CHANNEL_KEY_EXPIRED(109)、ERR_INVALID_CHANNEL_KEY(110). Starting from v1.7.3, the old method still works, but it is recommended to use this callback.

    Local Audio Mixing Playback Finished Callback (rtcEngineLocalAudioMixingDidFinish)

    - (void)rtcEngineLocalAudioMixingDidFinish:(AgoraRtcEngineKit * _Nonnull)engine;

    This callback is triggered when the audio mixing file playback is finished after calling startAudioMixing. If you failed to execute the startAudioMixing method, it returns the error code in the didOccurError callback.

    Local Audio Effect Playback Finished Callback (rtcEngineDidAudioEffectFinish)

    - (void)rtcEngineDidAudioEffectFinish:(AgoraRtcEngineKit * _Nonnull)engine soundId:(NSInteger)soundId;
    Name Description
    soundId ID of the audio effect. Each audio effect has a unique ID.

    Remote Audio Mixing Started Callback (rtcEngineRemoteAudioMixingDidStart)

    - (void)rtcEngineRemoteAudioMixingDidStart:(AgoraRtcEngineKit * _Nonnull)engine;

    This callback is triggered when a remote host calls startAudioMixing.

    Remote Audio Mixing Stopped Callback (rtcEngineRemoteAudioMixingDidFinish)

    - (void)rtcEngineRemoteAudioMixingDidFinish:(AgoraRtcEngineKit * _Nonnull)engine;

    This callback is triggered when a remote host stops calling startAudioMixing.

    Block Callbacks

    The SDK supports Block callbacks to report runtime events to the application. From version 1.1, some Block callbacks in the SDK are replaced with Delegate methods. The old Block callbacks are therefore being deprecated, but can still be used in current versions. However, we recommend replacing them with Delegate methods. The SDK calls the Block method if a callback is defined in both Block and Delegate. If you want to use the Delegate methods, set the Block attribute of the method as nil. The following section describes each of the callback methods in the SDK.

    Other User Joined Callback (userJoinedBlock)

    - (void)userJoinedBlock:(void(^)
    (NSUInteger uid, NSInteger elapsed))userJoinedBlock;

    This callback method notifies the application the broadcaster has joined the channel. If the broadcaster is already in the channel when the application joins the channel, the SDK also reports to the application on the broadcaster that is already in the channel.

    In the live broadcast scenario:

    • The broadcaster can receive the callback when another broadcaster joins the channel.
    • All the audience in the channel can receive the callback when the new broadcaster joins the channel.
    • When a web application joins the channel, this callback is triggered as long as the web application publishes streams.
    Name Description
    uid User ID. If the uid is specified in the joinChannelByToken method, returns the specified ID; if not, returns an ID that is automatically allocated by the Agora server.
    elapsed Time elapsed (ms) from calling joinChannelByToken until this callback is triggered.

    Other User offline Callback (userOfflineBlock)

    - (void)userOfflineBlock:(void(^)
    (NSUInteger uid))userOfflineBlock;

    This callback indicates that a user has left the call or gone offline.

    The SDK reads the timeout data to determine if a user has left the channel (or has gone offline). If no data package is received from the user in 15 seconds, the SDK assumes the user is offline. Sometimes a weak network connection may lead to false detections, therefore we recommend using signaling for reliable offline detection.

    Name Description
    uid User ID.

    Rejoin Channel Callback (rejoinChannelSuccessBlock)

     - (void)rejoinChannelSuccessBlock:(void(^)(NSString* channel,
    NSUInteger uid, NSInteger elapsed))rejoinChannelSuccessBlock;

    When the local machine loses connection with the server because of network problems, the SDK automatically attempts to reconnect, and then triggers this callback method upon reconnection. The callback indicates that the user has rejoined the channel with an assigned channel ID and user ID.

    Name Description
    channel Channel name.
    uid User ID.
    elapsed Time delay (ms) in rejoining the channel.

    User Left Channel Callback (leaveChannelBlock)

    - (void)leaveChannelBlock:(void(^)
    (AgoraRtcStats* stat))leaveChannelBlock;

    This callback indicates that a user has left the channel, and it also provides call session statistics including the duration of the call and tx/rx bytes.

    Name Description
    stat See the table below.
    AgoraRtcStats Description
    duration Call duration (s), represented by an aggregate value.
    txBytes Total number of bytes transmitted, represented by an aggregate value.
    rxBytes Total number of bytes received, represented by an aggregate value.

    RtcEngine Statistics Callback (rtcStatsBlock)

    - (void)rtcStatsBlock:(void(^)
    (AgoraRtcStats* stat))rtcStatsBlock;

    This callback is triggered once every two seconds to update the application on RtcEngine runtime statistics.

    Name Description
    stat See the table below.
    AgoraRtcStats Description
    duration Call duration (s), represented by an aggregate value.
    txBytes Total number of bytes transmitted, represented by an aggregate value.
    rxBytes Total number of bytes received, represented by an aggregate value.

    Audio Volume Indication Callback (audioVolumeIndicationBlock)

    - (void)audioVolumeIndicationBlock:(void(^)(NSArray *speakers,
    NSInteger totalVolume))audioVolumeIndicationBlock;

    This callback indicates who is talking and the speaker’s volume. By default it is disabled. If needed, use the enableAudioVolumeIndication method to configure it.

    Name Description
    speakers The speakers (array). Each speaker ():
    uid User ID of the speaker
    volume Volume of the speaker, between 0 (lowest volume) to 255 (highest volume).
    totalVolume The total volume after audio mixing between 0 (lowest volume) to 255 (highest volume).

    First Local Video Frame Displayed Callback (firstLocalVideoFrameBlock)

     - (void)firstLocalVideoFrameBlock:(void(^)(NSInteger width,
    NSInteger height, NSInteger elapsed))firstLocalVideoFrameBlock;

    This callback indicates that the first local video frame is displayed on the screen.

    Name Description
    width Width (pixels) of the video stream.
    height Height (pixels) of the video stream.
    elapsed Time elapsed (ms) from a user joining the channel until this callback is triggered.

    First Remote Video Frame Displayed Callback (firstRemoteVideoFrameBlock)

    - (void)firstRemoteVideoFrameBlock:(void(^)(NSUInteger uid,
    NSInteger width, NSInteger height,
    NSInteger elapsed))firstRemoteVideoFrameBlock;

    This callback indicates that the first remote video frame is displayed on the screen.

    Name Description
    uid User ID of the user whose video streams are received.
    width Width (pixels) of the video stream.
    height Height (pixels) of the video stream.
    elapsed Time elapsed (ms) from the user joining the channel until this callback is triggered.

    First Remote Video Frame Received and Decoded Callback (firstRemoteVideoDecodedBlock)

    - (void)firstRemoteVideoDecodedBlock:(void(^)
    (NSUInteger uid, NSInteger width, NSInteger height,
    NSInteger elapsed))firstRemoteVideoDecodedBlock;

    This callback indicates that the first remote video frame is received and decoded.

    Name Description
    uid User ID of the user whose video streams are received.
    width Width (pixels) of the video stream.
    height Height (pixels) of the video stream.
    elapsed Time elapsed (ms) from the user joining the channel until this callback is triggered.

    Other User Muted Audio Callback (userMuteAudioBlock)

    - (void)userMuteAudioBlock:(void(^)
    (NSUInteger uid, bool muted))userMuteAudioBlock;

    This callback indicates that a user has muted/unmuted his/her audio stream.

    Name Description
    uid User ID.
    muted
    • Yes: Muted audio.
    • No: Unmuted audio.

    Other User Paused/Resumed Video Callback (userMuteVideoBlock)

    - (void)userMuteVideoBlock:(void(^)
    (NSUInteger uid, bool muted))userMuteVideoBlock;

    This callback indicates that a user has paused/resumed his/her video stream.

    Name Description
    uid User ID
    muted
    • Yes: User has paused his/her video.
    • No: User has resumed his/her video.

    Local Video Statistics Callback (localVideoStatBlock)

    - (void)localVideoStatBlock:(void(^)(NSInteger sentBytes,
    NSInteger sentFrames))localVideoStatBlock;

    The SDK updates the application about the statistics of uploading local video streams once every two seconds.

    Name Description
    sentBytes Total bytes sent since last count.
    sentFrames Total frames sent since last count.

    Remote Video Statistics Callback (remoteVideoStatBlock)

    - (void)remoteVideoStatBlock:(void(^)(NSUInteger uid,
    NSInteger frameCount, NSInteger delay,
    NSInteger receivedBytes))remoteVideoStatBlock;

    The SDK updates the application about the statistics of receiving remote video streams once every two seconds.

    Name Description
    uid User ID that specifies whose video streams are received.
    frameCount Total frames received since last count.
    delay Time delay (ms)
    receivedBytes Total bytes received since last count.

    Camera Ready Callback (cameraReadyBlock)

    - (void)cameraReadyBlock:(void(^)())cameraReadyBlock;

    This callback indicates that the camera is turned on and ready to capture video.

    Audio Quality Callback (audioQualityBlock)

    - (void)audioQualityBlock:(void(^)(NSUInteger uid,
    AgoraNetworkQuality quality,  NSUInteger delay,
    NSUInteger lost))audioQualityBlock;

    During a conversation, this callback is triggered once every two seconds to report on the audio quality of the current call.

    Name Description
    uid User ID of the speaker
    quality

    Rating of the audio quality:

    • AgoraNetworkQualityUnknown(0): The network quality is unknown.
    • AgoraNetworkQualityExcellent(1): The network quality is excellent.
    • AgoraNetworkQualityGood(2): The network quality is quite good, but the bitrate may be slightly lower than excellent.
    • AgoraNetworkQualityPoor(3): Users can feel the communication slightly impaired.
    • AgoraNetworkQualityBad(4): Users can communicate only not very smoothly.
    • AgoraNetworkQualityVBad(5): The network is so bad that users can hardly communicate.
    • AgoraNetworkQualityDown(6): Users cannot communicate at all.
    delay Time delay in milliseconds.
    lost The packet loss rate(%).

    Network Quality Callback (lastmileQualityBlock)

    - (void)lastmileQualityBlock:(void(^)
    (AgoraNetworkQuality quality))lastmileQualityBlock;

    This callback is triggered once every two seconds during a call to report on the network quality.

    Name Description
    quality Rating of the network quality:
    • AgoraRtc_Quality_Unknown = 0
    • AgoraRtc_Quality_Excellent = 1
    • AgoraRtc_Quality_Good = 2
    • AgoraRtc_Quality_Poor = 3
    • AgoraRtc_Quality_Bad = 4
    • AgoraRtc_Quality_VBad = 5
    • AgoraRtc_Quality_Down = 6

    Connection Lost Callback (connectionLostBlock)

    - (void)connectionLostBlock:(void(^)())connectionLostBlock;

    This callback indicates that the SDK has lost network connection with the server.