The Interactive Gaming Audio Only API is composed of Objective-C Interface and C++ Interface, both of which provide main methods and callback events of the SDK on the iOS platform.

Objective-C Interface

Basic Methods (AgoraRtcEngineKit)

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

Initialize (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 service before using AgoraRtcEngineKit.

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

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

Set the Channel Profile (setChannelProfile)

- (int)setChannelProfile:(AgoraChannelProfile)profile;

This method configures the channel profile. The Agora 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 setClientRole. 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 Engine and create a new one using sharedEngineWithAppId before calling this method to set the new channel profile.
  • Make sure that different App IDs are used for different channel profiles.
  • This method must be called and configured before a user joining 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: Communication (default)
  • AgoraChannelProfileLiveBroadcasting = 1: Live Broadcast
  • AgoraChannelProfileGame = 2: Gaming
Return Value
  • 0: Method call succeeded.
  • < 0: Method call failed.

Set the User Role (setClientRole)

- (int)setClientRole:(AgoraClientRole)role;

In a live broadcasr channel, this method allows you:

  • 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: The Method is called successfully
  • <0: Failed to call the method

Enable the Audio Mode (enableAudio)

- (int)enableAudio;

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

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

This method sets to enable the internal engine, and still works after leaveChannel is called.

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 didMicrophoneEnabled callback function will be triggered once the local audio function is disabled or re-enabled.

  • Call this method after joinChannelByToken.
  • This method is different from muteLocalAudioStream:
    • enableLocalAudio: Disables/Re-enables the local audio capturing and handling.
    • 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 handling.
  • false: Disable the local audio function, that is, to stop local audio capturing and handling.
Return Value
  • 0: Success
  • <0: Failure

Disable the Audio Mode (disableAudio)

- (int)disableAudio;

This method disables the audio mode.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

This method sets to disable the internal engine, and still works after leaveChannel is called.

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 entering another channel. This method is called asynchronously; 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 playing, so using this object may affect the SDK’s audio functions.

Once this method is called successfully, the SDK will trigger the callback. If both joinChannelSuccessBlock and didJoinChannel are implemented, the priority of joinChannelSuccessBlock is higher than didJoinChannel, thus didJoinChannel will be 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 application developers. The developers can then generate a user key using the algorithm and App Certificate provided by Agora for user authentication on the server.

In most circumstances, the static App ID will suffice. 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 from a to z
  • The 26 uppercase English letters from A to Z
  • The 10 numbers from 0 to 9
  • The space
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
info (Optional) Any additional information the developer wants to add. [1] It can be set as a NIL Sting or channel related information. Other users in the channel will 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 user successfully joined the channel.

[1] For example, when a host wants to customize the resolution and bitrate for a live broadcast channel with CDN Live enabled, they 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 application should not set it to any other mode. When setting to this mode, the sound being played (for example a ringtone) will be interrupted.

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 the leaveChannel method to end the call before joining another one.

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

If you call destroy() immediately after leaveChannel, the leaveChannel process will be interrupted, and the SDK will not trigger the didLeaveChannelWithstats callback.

Name Description
leaveChannelBlock Callback on user successfully left the channel.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set the Local Voice Pitch (setLocalVoicePitch)

- (int) setLocalVoicePitch:(double) pitch;

This method changes the voice pitch of the local speaker.

Name Description
pitch Voice frequency, in the range of [0.5, 2.0]. The default value is 1.0.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Sets the Voice Position of the Remote user (setRemoteVoicePosition)

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

This method sets the voice position of the remote user.

This API 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 range is [-1, 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 range is [0.0, 100.0]. The default value is 100.0. The smaller the number 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 (transmit the audio stream only), and the other streams will be ignored; for example the sound of the keyboard strokes.

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

Set 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 ranging from 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 in dB; ranging from -15 to 15.
Return Value
  • 0: Method call succeeded.
  • < 0: Method call failed.

Set 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: Method call succeeded.
  • < 0: Method call failed.

Enable the Video Mode (enableVideo)

- (int)enableVideo;

This method enables the video mode. The application can call this method either before entering a channel or during a call. If it is called before entering a channel, the service starts in the video mode; if it is called during a call, it switches from the audio to video mode. To disable the video mode, call the disableVideo method.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

This method sets to enable the internal engine, and still works after leaveChannel is called.

Disable the Video (disableVideo)

- (int)disableVideo;

This method disables the video mode. The application can call this method either before entering a channel or during a call. If it is called before entering a channel, the service starts in the audio mode; If it is called during a call, it switches from the video to audio mode. To enable the video mode, call the enableVideo method.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

This method sets to disable the internal engine, and still works after leaveChannel is called.

Enable 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 enableVideo, otherwise this method may not work properly.

  • After enableVideo is called, the local video will be enabled by default. This method is useds to enable and disable the local video while the remote video remains unaffected.

Name Description
enabled

Sets to enable the local video:

  • YES: Enable the local video (default)
  • 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 set to NO, this method does not require a local camera.
Return value
  • 0: Method call succeeded
  • < 0: Method call failed

This method sets to enable/disable the internal engine, and still works after leaveChannel is called.

Set the Video Profile (setVideoProfile)

This method has been deprecated. If you hope to set the video encoder profile, Agora recommends using setVideoEncoderConfiguration.

- (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 enableVideo 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: Method call succeeded.
  • < 0: Method call failed.

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

Set the Video Resolution (setVideoResolution)

This method has been deprecated. If you hope to set the video encoder profile, Agora recommends using setVideoEncoderConfiguration.

- (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 the channel, Agora recommends calling this method before enableVideo 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 will automatically adjust it to a value within the range.

Set the Local Video View (setupLocalVideo)

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

This method configures the video display settings on local machine. The application calls this method to bind with the video window (view) of local video streams and configure the video display settings. Call this method after initialization to configure the local video display settings before entering 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 setupLocalVideo.

Name Description
local

Video display settings. Class VideoCanvas:

  • 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 will be filled with black.
  • Return value: The local user ID as set in the joinChannel method.
Return Value
  • 0: Method call succeeded.
  • < 0: Method call failed.

Set 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 application should specify the uid of the remote video in the method call before the user enters a channel. If the remote uid is unknown to the application, set it later when the application receives the onUserJoined event.

If the Video Recording function is enabled, the Video Recording Service joins the channel as a dumb client, which means other clients will also receive the didJoinedOfUid event. Your application should not bind it with the view, because it does not send any video stream. If your application cannot recognize the dumb client, bind it with the view when the firstRemoteVideoDecodedOfUid event is triggered. To unbind the user with the view, set the view to null. After the user has left the channel, the SDK unbinds the remote user.

Name Description
remote

Video display settings. Class VideoCanvas:

  • 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 will be filled with black.
Return Value
  • 0: Method call succeeded.
  • < 0: Method call failed.

Enable Dual-stream Mode (enableDualStreamMode)

- (int)enableDualStreamMode:(BOOL)enabled;

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

Name Description
enabled

The mode is in single stream or dual stream:

  • True: Dual stream
  • False: Single stream
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set 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 enableDualStreamMode, you will receive the high-video stream by default. This method allows the application to adjust the corresponding video-stream type according to the size of the video windows to save the bandwidth and calculation resources.

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

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

Name Description
uid User ID
streamType

Set the video-stream size.

The following lists the video-stream types:

  • AgoraVideoStreamTypeHigh(0): High-video stream
  • AgoraVideoStreamTypeLow(1): Low-video stream
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set the Default Remote Video Stream Type (setRemoteDefaultVideoStreamType)

- (int)setRemoteDefaultVideoStreamType:(AgoraVideoStreamType)streamType;

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

Name Description
streamType

The default remote video stream:

  • AgoraVideoStreamTypeHigh = 0: The high video stream
  • AgoraVideoStreamTypeLow = 1: The low video stream
Return Value
  • 0: Method call succeeded.
  • < 0: Method call failed.

Set High-quality Video Preferences (setVideoQualityParameters)

- (int)setVideoQualityParameters:(BOOL)preferFrameRateOverImageQuality;

This method allows users to set video preferences.

Name Description
preferFrameRateOverImageQuality

The video preference to be set:

  • True: Frame rate over image quality
  • False: Image quality over frame rate (default)
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Start Video Preview (startPreview)

- (int)startPreview;

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

  • Call setupLocalVideo to set up the local preview window and configure the attributes

  • Call enableVideo to enable video

Once the local video preview is enabled, the preview will not be shut down if you call leaveChannel to leave the channel. To shut down the preview, call stopPreview.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Stop Video Preview (stopPreview)

- (int)stopPreview;

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

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set the Local Video Display Mode (setLocalRenderMode)

- (int)setLocalRenderMode:(AgoraVideoRenderMode) mode;

This method configures the local video display mode. The application 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 will be filled with black.
Return Value
  • 0: Method call succeeded.
  • < 0: Method call failed.

Set the Remote Video Display Mode (setRemoteRenderMode)

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

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

Name Description
uid The user ID of the user whose video streams are received.
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 will be filled with black.
Return Value
  • 0: Method call succeeded.
  • < 0: Method call failed.

Set the Local Video Mirror Mode (setLocalVideoMirrorMode)

- (int)setLocalVideoMirrorMode:(AgoraVideoMirrorMode) mode;

This method sets the local video mirror mode. Use this method before startPreview, or it does not take effect until you re-enable startPreview.

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

Switch Between Front and Back Cameras (switchCamera)

- (int)switchCamera;

This method switches between front and back cameras.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Check whether Camera Zoom 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

Check whether Camera Flash 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 generally enables the front camera by default. If your front camera does not support front camera torch, this method will return false. If you want to check if the rear camera torch is supported, call switchCamera before using this method.

Check whether Manual Focus 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

Check whether Autofocus is Supported (isCameraAutoFocusFaceModeSupported)

- (BOOL)isCameraAutoFocusFaceModeSupported;

It returns:

  • True: The device supports the autofocus function;

  • False: The device does not support the autofocus function;

Set the Camera Zoom Ratio (setCameraZoomFactor)

- (CGFloat)setCameraZoomFactor:(CGFloat)zoomFactor;
Name Description
factor The camera zoom factor ranging from 1.0 to the max zoom

Set 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

Enable the Camera Flash (setCameraTorchOn)

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

Enable the Camera Autofocus (setCameraAutoFocusFaceModeEnabled)

- (BOOL)setCameraAutoFocusFaceModeEnabled:(BOOL)enable;
Name Description
enabled Whether to enable the camera autofocus function: True/False

Enable Web SDK Interoperability (enableWebSdkInteroperability)

- (int)enableWebSdkInteroperability:(BOOL)enabled;

This method enables interoperability with the Agora Web SDK.

Name Description
enabled

Whether to enable the interoperability with the Agora Web SDK is enabled:

  • True: Enable the interoperability
  • False: Disable the interoperability
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set the Default Audio Route (setDefaultAudioRouteToSpeakerPhone)

- (int)setDefaultAudioRouteToSpeakerphone:(BOOL)defaultToSpeaker;

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

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

If the user does 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.

Check Whether the Speakerphone is Enabled (isSpeakerphoneEnabled)

- (BOOL)isSpeakerphoneEnabled;

This method checks whether the speakerphone is enabled.

Name Description
Return Value
  • Yes: Yes, enabled.
  • No: No, not enabled.

Enable In-ear Monitoring (enableInEarMonitoring)

- (int)enableInEarMonitoring:(BOOL)enabled;

This method enables or disables the in-ear monitoring function.

Name Description
enabled
  • YES: Enable in-ear monitoring
  • NO: Disable in-ear monitoring (default)
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set the Audio Session Operation 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 API 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 comes as 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.

Enable the Audio Volume Indication (enableAudioVolumeIndication)

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

This method allows the SDK to regularly report to the application on which user is speaking and the volume of the speaker. Once the method is enabled, the SDK returns the volume indications at the set time internal in the reportAudioVolumeIndicationOfSpeakers and audioVolumeIndicationBlock callback, 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 between two consecutive volume indications in milliseconds. Agora recommends setting it to more than 200 ms. Do not set it lower than 10 ms, or the reportAudioVolumeIndicationOfSpeakers callback will not be triggered.
smooth The Smoothing factor that determines the sensitivity of this method. The range is [0-10] and Agora recommends setting it 3. The bigger the number, the more sensitive it is.
Return values
  • 0: Method call succeeded
  • < 0: Method call failed

Set the Volume of 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, ranging from 0 to 100. The default value is 100.
Return values
  • 0: Method call succeeded.
  • < 0: Method call failed.

Get the Audio Effect Volume (getEffectsVolume)

- (double)getEffectsVolume;

This method gets the volume of the audio effects from 0.0 to 100.0.

Set the Audio Effect Volume (setEffectsVolume)

- (int)setEffectsVolume:(double)volume;

This method sets the volume of the audio effects.

Name Description
volume Value ranging from 0.0 to 100.0. 100.0 is the default value.
Return Value
  • 0: Method call succeeded
  • <0: Method call failed

Adjust 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 Value ranging from 0.0 to 100.0. 100.0 is the default value.
Return Value
  • 0: Method call succeeded
  • <0: Method call failed

Play the 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

Set the number of times looping the audio effect

  • 0: Play the audio effect once
  • 1: Play the audio effect twice
  • -1: Play the audio effect in a loop indefinitely, until stopEffect or stopAllEffects is called
pitch Set whether to change the pitch of the audio effect. The range is [0.5, 2]. The default value is 1, which means no change to the pitch. The smaller the value, the lower the pitch.
pan

Spatial position of the local audio effect. The range is [-1.0, 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 range is [0.0, 100,0] The default value is 100.0. The smaller the value, the lower the volume of the audio effect
publish

Set whether 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: Method call succeeded
  • < 0: Method call failed

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

In version v2.1.x, the following method, which is 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;

Stop 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: Method call succeeded.
  • <0: Method call failed.

Stop 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 a specific audio effect file (compressed audio file) to the memory.

To ensure smooth communication, pay attention to the size of the audio effect file. Agora recommends using this method to preload the audio effect before calling joinChannelByToken.

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: Method call succeeded
  • <0: Method call failed

Release an Audio Effect (unloadEffect)

- (int)unloadEffect:(int)soundId;

This method releases a specific preloaded audio effect from the memory.

Name Description
soundId ID of the audio effect. Each audio effect has a unique ID.
Return Value
  • 0: Method call succeeded
  • <0: Method call failed

Pause an Audio Effect (pauseEffect)

- (int)pauseEffect:(int)soundId;

This method pauses a specific audio effect.

Name Description
soundId ID of the audio effect. Each audio effect has a unique ID.
Return Value
  • 0: Method call succeeded
  • <0: Method call failed

Pause all Audio Effects (pauseAllEffects)

- (int)pauseAllEffects;

This method pauses all the audio effects.

Name Description
Return Value
  • 0: Method call succeeded
  • <0: Method call failed

Resume an Audio Effect (resumeEffect)

- (int)resumeEffect:(int)soundId;

This method resumes playing a specific audio effect.

Name Description
soundId ID of the audio effect. Each audio effect has a unique ID.
Return Value
  • 0: Method call succeeded
  • <0: Method call failed

Resume all Audio Effects (resumeAllEffects)

- (int) esumeAllEffects;

This method resumes all the audio effects.

Mute the Local Audio Stream (muteLocalAudioStream)

- (int)muteLocalAudioStream:(BOOL)mute;

This method mutes/unmutes the local audio.

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

Name Description
mute
  • True: Mutes the local audio.
  • False: Unmutes the local audio.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Mute all Remote Audio Streams (muteAllRemoteAudioStreams)

- (int)muteAllRemoteAudioStreams:(BOOL)mute;

This method mutes/unmutes all remote users’ audio streams.

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

Name Description
muted
  • True: Stops playing all received audio streams.
  • False: Resumes playing all received audio streams.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Mute a Specified Remote Audio Stream (muteRemoteAudioStream)

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

Mute/unmute a specified remote user’s audio stream.

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

Name Description
uid User ID whose audio streams the user intends to mute.
mute
  • True: Stops playing a specified user’s audio streams.
  • False: Allows playing a specified user’s audio streams.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Mute the Local Video Stream (muteLocalVideoStream)

- (int)muteLocalVideoStream:(BOOL)muted;

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

When set to YES, this method does not disable the camera and thus does not affect the retrieval of local video streams. This method responds faster than enableLocalVideo (false).
This method takes effect only when the user is in the channel. After the user leaves the channel, all the mute states are reset.

Name Description
mute
  • Yes: Stops sending the local video stream to the network.
  • No: Allows sending the local video stream to the network.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Mute all Remote Video Streams (muteAllRemoteVideoStreams)

- (int)muteAllRemoteVideoStreams:(BOOL)mute;

This method enables/disables playing all remote callers’ video streams.

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

Name Description
mute
  • Yes: Stops playing all received video streams.
  • No: Allows playing all received video streams.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Mute a Specified Remote Video Stream (muteRemoteVideoStream)

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

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

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

Name Description
uid User ID of the specified user.
mute
  • Yes: Stops playing a specified user’s video stream.
  • No: Allows playing a specified user’s video stream.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Start 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 API also supports online music playback.

  • To use the startAudioMixing API, ensure the iOS device version is 8.0 or later.
  • Call this API 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.

    Stop Audio Mixing (stopAudioMixing)

    - (int)stopAudioMixing;

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

    Name Description
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Pause Audio Mixing (pauseAudioMixing)

    - (int)pauseAudioMixing;

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

    Name Description
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Resume Audio Mixing (resumeAudioMixing)

    - (int)resumeAudioMixing;

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

    Name Description
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Adjust the Audio Mixing Volume (adjustAudioMixingVolume)

    - (int)adjustAudioMixingVolume:(NSInteger)volume;

    This method adjusts the volume during audio mixing. Call this API 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.

    Get the Audio Mixing Duration (getAudioMixingDuration)

    - (int)getAudioMixingDuration;

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

    Get Current Audio Position (getAudioMixingCurrentPosition)

    - (int)getAudioMixingCurrentPosition;

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

    Drag the Audio Progress Bar (setAudioMixingPosition)

    - (int)setAudioMixingPosition:(NSInteger)pos;

    This method drags the playback progress bar of the audio mixing file to where you want to play instead of playing it from the beginning.

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

    Start 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 either one of the following two formats:

    • .wav: Large file size with high sound fidelity OR

    • .aac: Small file size with low sound fidelity

    Ensure that the saving directory in the application exists and is writable. Call this method after the joinChannelByToken method. The recording automatically stops when the leaveChannel method is called.

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

    Audio recording quality:

    • AgoraRtc_AudioRecordingQuality_Low = 0: Low quality, file size around 1.2 MB after 10 minutes of recording
    • AgoraRtc_AudioRecordingQuality_Low = 1: Medium quality, file size around 2 MB after 10 minutes of recording
    • AgoraRtc_AudioRecordingQuality_Low = 2: High quality, file size around 3.75 MB after 10 minutes of recording
    Return Value
    • 0: Method call succeeded
    • <0: Method call failed.

    Stop an Audio Recording (stopAudioRecording)

    - (int)stopAudioRecording;

    This method stops recording on the client.

    Call this method before calling leaveChannel, otherwise the recording automatically stops when the leaveChannel method is called.

    Name Description
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Adjust the Recording Volume (adjustRecordingSignalVolume)

    - (int)adjustRecordingSignalVolume:(NSInteger)volume;

    This method adjusts the recording volume.

    Name Description
    volume

    Recording volume, ranges from 0 to 400:

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

    Adjust the Playback Volume (adjustPlaybackSignalVolume)

    - (int)adjustPlaybackSignalVolume:(NSInteger)volume;

    This method adjusts the playback volume.

    Name Description
    volume

    Playback volume, ranges from 0 to 400:

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

    Enable Built-in Encryption and Set the Encryption Secret (setEncryptionSecret)

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

    Use setEncryptionSecret to specify 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 has left the channel. If the encryption password is not specified or set to empty, the encryption function will be disabled.

    Do not use this function together with CDN.

    Name Description
    secret Encryption Password
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Set 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 API to set the encryption mode.

    All users in the same channel must use the same encryption mode and password. Refer to information related to the AES encryption algorithm on the differences between encryption modes.

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

    Do not use this function together with CDN.

    Name Description
    encryptionMode

    Encryption mode. The following modes are currently 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 it is set to NUL string, the encryption is in “aes-128-xts” by default.
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Create 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 reliable and ordered both as True or both as False. Do not set one as True and the other as False.

    Name Description
    reliable
    • True: The recipients will receive data from the sender within 5 seconds. If the recipient does not receive the sent data within 5 seconds, the data channel will report an error to the application.
    • False: The recipients may not receive any data, and the SDK will not report any error upon data missing.
    ordered
    • True: The recipients will receive data in the order of the sender.
    • False: The recipients will not receive data in the order of the sender.
    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.

    Send 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 will be returned: ERR_SIZE_TOO_LARGE/ERR_TOO_OFTEN/ERR_BITRATE_LIMIT

    Start 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, headset and speaker) and the network connection are working properly. In the test, the user first speaks, and the recording is played back in 10 seconds. If the user can hear the recording in 10 seconds, it indicates that the audio devices and network connection work properly.

    • After calling the startEchoTest method, call stopEchoTest to end the test; otherwise, the application 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 mode from communication to live broadcast, ensure that setClientRole is called to change the user role from audience(default in the live broadcast mode) 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.

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

    Enable 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 disableLastmileTest to disable it immediately once the users have received the onLastmileQuality callback before they join the channel or switch the user role.

    For current hosts, do not call this method.

    Name Description
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Disable the Network Test (disableLastmileTest)

    - (int)disableLastmileTest;

    This method disables the network connection quality test.

    Name Description
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Retrieve the Current Call ID (getCallId)

    - (NSString * _Nullable)getCallId;

    When a user joins a channel on a client, a CallId is generated to identify the call from the client. Some methods such as rate and complain need to be called after the call ends in order to submit feedback to the SDK. These methods require assigned values of the CallId parameters. To use these feedback methods, call the getCallId 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.

    Rate the Call (rate)

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

    This method lets the user rate the call. It is usually called after the call ends.

    Name Description
    callId Call ID retrieved from the getCallId method.
    rating Rating for the call between 1 (lowest score) to 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.

    Complain about the Call Quality (complain)

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

    This method allows the user to complain about the call quality. It is usually called after the 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.

    Renew Token (renewToken)

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

    This method updates the Token.

    The key expires after a certain period of time 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, or

    The application should retrieve a new key and then call this method to renew it. Failure to do so will result in the SDK disconnecting from the server.

    Name Description
    token Token to be renewed.
    Return Value
    • 0: Method call succeeded.
    • < 0: Method call failed.

    Specify 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 code.
    Return Value
    • 0: Method call succeeded.
    • < 0: Method call failed.

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

    Set the Log Filter (setLogFilter)

    - (int)setLogFilter:(NSUInteger)filter;

    This method sets the output log level 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 logs that precede that level.

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

    Name Description
    filter

    Set the levels of the filters:

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

    Destroy the Engine Instance (destroy)

    + (void)destroy;

    This method releases all the resources used by the Agora SDK. This is useful for applications that occasionally make voice or video calls, to free up resources for other operations when not making calls.

    Once the application has called destroy() 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 sub thread.
    • This method is called synchronously. 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.

    Get 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 runtime events to the application. From v1.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 the current version. However, we recommend replacing them with Delegate methods. The SDK calls the Block method if a callback is defined in both Block and Delegate.

    Warning Occurred Callback (didOccurWarning)

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

    This callback method indicates that some warning occurred during SDK runtime. In most cases, the application can ignore the warnings 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.

    Error Occurred Callback (didOccurError)

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

    This callback indicates that a network or media error occurred 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 application 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 application 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.

    API Call Executed Callback (didApiCallExecute)

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

    This callback is triggered when the API has been executed.

    Name Description
    error The error code that the SDK returns when the method call fails. If the SDK returns o, then the method has been called successfully.
    api The API that the SDK executes
    result The result of calling the API

    Join Channel Callback (didJoinChannel)

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

    Same as joinSuccessBlock in the joinChannelByToken API. This callback indicates that the user has successfully joined the specified channel.

    Name Description
    channel Channel name.
    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 event occurs.

    Rejoin 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 then triggers this callback method 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 joinChannelByToken until this event occurs.

    User Left Channel Callback (didLeaveChannelWithStats)

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

    When the user executes leaveChannel() successfully, SDK will trigger this callback. 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 in seconds, 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 receive bitrate in kbit/s, represented by an instantaneous value.
    • txVideoKBitRate: Video transmission bitrate in kbit/s, represented by an instantaneous value.
    • rxVideoKBitRate: Video receive bitrate in kbit/s, represented by an instantaneous value.
    • lastmileDelay: The time delay in milliseconds from the Client to the VO Server
    • users: The instant number of users in the channel when the user leaves the channel.
    • puTotalUsage: System CPU usage (%).
    • cpuAppUsage: Application CPU usage (%).

    Audio Route Changed Callback (didAudioRouteChanged)

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

    This callback is triggered when the audio routing is changed. The definition of AgoraAudioOutputRouting is listed as follows:

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

    The State of the Microphone Has Changed Callback (didMicrophoneEnabled)

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

    Audio Quality Callback (audioQualityOfUid)

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

    Same as audioQualityBlock. During a call, 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(%).

    Audio Volume Indication Callback (reportAudioVolumeIndicationOfSpeakers)

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

    Same as audioVolumeIndicationBlock. By default this notification is disabled. If you need it, use the enableAudioVolumeIndication method to configure it.

    Name Description
    speakers

    The speakers (array). Each speaker ():

    • uid: User ID of the speaker. By default, 0 means the local user.
    • volume: The volume of the speaker that ranges from 0 (lowest volume) to 255 (highest volume).
    totalVolume Total volume after audio mixing that ranges from 0 (lowest volume) to 255 (highest volume).

    In the returned speakers array:

    • If the uid is 0, that is, the local user is the speaker, the returned volume is the same as totalVolumn.
    • If the uid is not 0 and the volume is 0, it indicates that the user specified by the uid did not speak.
    • If a uid is contained in the previous speakers array but not in the present one, it indicates that the user specified by the uid did not speak.

    Other User Joined Callback (didJoinedOfUid)

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

    Same as 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 of the host.

    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 (didOfflineOfUid)

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

    Same as userOfflineBlock. This callback indicates that the broadcaster 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

    This callback is triggered 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 certain period of time. 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.

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

    C++ Interface

    Basic Methods (IRtcEngine)

    agora::IRtcEngine is the basic interface class of Agora Native SDK. Creating an agora::IRtcEngine object and then calling the methods of this object enables the use of Agora Native SDK’s communication functionality. In the previous versions this class is named as IAgoraAudio, and it is renamed to agora::IRtcEngine from version 1.0.

    Create an agora::IRtcEngine Object (create)

    agora::rtc::IRtcEngine* AGORA_CALL createAgoraRtcEngine();

    This method creates an IRtcEngine object. Unless otherwise specified, all called methods provided by the RtcEngine class are executed asynchronously. Agora recommends calling the interface methods in the same thread. Unless otherwise specified, the following rule applies to all APIs whose return values are integer types: A return value of 0 indicates that the call was successful, and a return value less than 0 indicates that the call failed.

    Name Description
    Return Value An agora::IRtcEngine object.

    Initialize (initialize)

    virtual int initialize(const RtcEngineContext& context) = 0;

    This method initializes the Agora SDK service. Enter the Agoran App ID issued to developers to start initialization. After creating an agora::IRtcEngine object, call this method to initialize service before using any other methods. After initialization, the service is set to audio mode by default. To enable video mode, call enableVideo API afterwards.

    The definition of RTCEngineContext is:

    struct RtcEngineContext
    {
        IRtcEngineEventHandler* eventHandler;
        /** App ID issued to the developers by Agora. Apply for a new one from Agora if it is missing from your kit.
        */
        const char* appId;
        RtcEngineContext()
        :eventHandler(NULL)
        ,appId(NULL)
        {}
    };
    Name Description
    appID App ID issued to application developers by Agora. Apply for a new one from Agora if the key is missing from your kit. See Getting an App ID for more information to how to get an App ID.
    eventHandler IRtcEngineEventHandler is an abstract class that provides default implementations. The SDK uses this class to report to the application on SDK runtime events.
    Return Value
    • 0: Method call succeeded.
    • < 0: Method call failed.
      • ERR_INVALID_VENDOR_KEY(-101): The entered App ID is invalid.

    Set a Channel Profile (setChannelProfile)

    virtual int setChannelProfile(CHANNEL_PROFILE_TYPE profile) = 0;

    This method configures the channel profile. The Agora 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 freely.
    Live Broadcast Live Broadcast. Host and audience roles that can be set by calling setClientRole. 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 release to destroy the current Engine and create a new one using create and initialize before calling this method to set the new channel profile.
    • Make sure that different App IDs are used for different channel profiles.
    • This method must be called and configured before a user joining 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:

    • CHANNEL_PROFILE_COMMUNICATION = 0: Communication (default)
    • CHANNEL_PROFILE_LIVE_BROADCASTING = 1: Live Broadcast
    • CHANNEL_PROFILE_GAME = 2: Gaming
    Return Value
    • 0: Method call succeeded.
    • < 0: Method call failed.

    Set the User Role (setClientRole)

    virtual int setClientRole(CLIENT_ROLE_TYPE role) = 0;

    In a live broadcast channel, 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:

    • CLIENT_ROLE_BROADCASTER = 1; Host
    • CLIENT_ROLE_AUDIENCE = 2; Audience(default)
    Return Value
    • 0: The Method is called successfully
    • <0: Failed to call the method

    Enable the Audio Mode (enableAudio)

    virtual int enableAudio() = 0;

    This method enables the audio mode. This function is enabled by default.

    Name Description
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    This method sets to enable the internal engine, and still works after leaveChannel is called.

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

    virtual int enableLocalAudio(bool enabled) = 0;

    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 onMicrophoneEnabled callback function will be triggered once the local audio function is disabled or re-enabled.

    • Call this method after joinChannel.
    • This method is different from muteLocalAudioStream:
      • enableLocalAudio: Disables/Re-enables the local audio capturing and handling.
      • 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 handling.
    • false: Disable the local audio function, that is, to stop local audio capturing and handling.
    Return Value
    • 0: Success
    • <0: Failure

    Disable the Audio Mode (disableAudio)

    virtual int disableAudio() = 0;

    This method disables the audio mode.

    Name Description
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    This method sets to disable the internal engine, and still works after leaveChannel is called.

    Join a Channel (joinChannel)

    virtual int joinChannel(const char* token, const char* channelId, const char* info, uid_t uid) = 0;

    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 entering another channel.

    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 key, or App ID. In this case, pass NULL as the parameter value.

    If the user uses a Channel key, Agora issues an additional App Certificate to the developers. The developers can then generate a user key using the algorithm and App Certificate provided by Agora for user authentication on the server.

    In most circumstances, the static App ID will suffice. For added security, use the Channel Key.

    channel

    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 from a to z
    • The 26 uppercase English letters from A to Z
    • The 10 numbers from 0 to 9
    • The space
    • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","

    info (Optional) Additional information about the channel that developers need to add. [1] It can be set as a NULL String or channel related information. Other users in the channel will not receive this message.
    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 onJoinChannelSuccess callback. Your app must record and maintain the returned value, as the SDK does not maintain it.
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.
      • ERR_INVALID_ARGUMENT (-2): The passed argument is invalid.
      • ERR_NOT_READY (-3): Initialization failed.

    [1] For example, when a host wants to customize the resolution and bitrate for a live broadcast channel with CDN Live enabled, they 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.

    Leave a Channel (leaveChannel)

    virtual int leaveChannel() = 0;

    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 the leaveChannel method to end the call before joining another one. The leaveChannel method releases all resources related to the call. The leaveChannel method is called asynchronously, and the user has not actually left the channel when the call returns. Once the user leaves the channel, the SDK triggers the onLeaveChannel callback.

    If you call release() immediately after you call leaveChannel, it will interrupt the leavechannel process, and the SDK will not trigger the onLeaveChannel callback.

    Name Description
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.
      • ERR_REFUSED (-5): Failed to leave the channel, reasons being that the user is not currently in a call or is in the process of leaving the channel.

    Set the Local Voice Pitch (setLocalVoicePitch)

    int setLocalVoicePitch(double pitch);

    This method changes the voice pitch of the local speaker.

    Name Description
    pitch Voice frequency, in the range of [0.5, 2.0]. The default value is 1.0.
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Sets the Voice Position of the Remote user (setRemoteVoicePosition)

    virtual int setRemoteVoicePosition(int uid, double pan, double gain) = 0;

    This method sets the voice position of the remote user.

    This API 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 range is [-1, 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 range is [0.0, 100.0]. The default value is 100.0. The smaller the number is, the lower the volume of the audio effect.

    Return Value
    • 0: Success
    • < 0: Failure

    Sets to Voice-only Mode (setVoiceOnlyMode)

    virtual int setVoiceOnlyMode(bool enable) = 0;

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

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

    Set the Local Voice Equalization (setLocalVoiceEqualization)

    int setLocalVoiceEqualization(AUDIO_EQUALIZATION_BAND_FREQUENCY bandFrequency, int bandGain);

    This method sets the local voice equalization effect.

    Name Description
    bandFrequency The band frequency ranging from 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.
    bandGain Gain of each band in dB; ranging from -15 to 15.
    Return Value
    • 0: Method call succeeded.
    • < 0: Method call failed.

    Set the Local Voice Reverberation (setLocalVoiceReverb)

    int setLocalVoiceReverb(AUDIO_REVERB_TYPE reverbKey, int value)

    This method sets local voice reverberation.

    Name Description
    reverbKey The reverberation key. This method contains five reverberation keys. For details, see the description of each value:
    value
    • AUDIO_REVERB_DRY_LEVEL = 0, (dB, [-20,10]), level of the dry signal
    • AUDIO_REVERB_WET_LEVEL = 1, (dB, [-20,10]), level of the early reflection signal (wet signal)
    • AUDIO_REVERB_ROOM_SIZE = 2, ([0, 100]), room size of the reflection
    • AUDIO_REVERB_WET_DELAY = 3, (ms, [0, 200]), length of the initial latency of the wet signal in ms
    • AUDIO_REVERB_STRENGTH = 4, ([0, 100]), length of the late reverberation
    Return Value
    • 0: Method call succeeded.
    • < 0: Method call failed.

    Get the Audio Effect Volume (getEffectsVolume)

    int getEffectsVolume();

    This method gets the volume of the audio effects from 0.0 to 100.0.

    Set the Audio Effect Volume (setEffectsVolume)

    int setEffectsVolume(int volume);

    This method sets the volume of the audio effects from 0.0 to 1.0.

    Name Description
    volume The value ranges from 0.0 to 100.0. 100.0 is the default value.
    Return Value
    • 0: Method call succeeded.
    • < 0: Method call failed.

    Adjust the Audio Effect Volume in Real Time (setVolumeOfEffect)

    int setVolumeOfEffect(int soundId, int volume);

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

    Name Description
    soundId ID of the audio effect. Each audio effect has a unique ID.
    volume The value ranges from 0.0 to 100.0. 100.0 is the default value.
    Return Value
    • 0: Method call succeeded.
    • < 0: Method call failed.

    Play the Audio Effect (playEffect)

    int playEffect(int soundId, const char* filePath, int loopCount, double pitch, double pan, int gain, 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 [2]
    filePath The absolute path of the audio effect file
    loopCount

    Set the number of times looping the audio effect

    • 0: Play the audio effect once
    • 1: Play the audio effect twice
    • -1: Play the audio effect in a loop indefinitely, until stopEffect or stopAllEffects is called
    pitch Set whether to change the pitch of the audio effect. The range is [0.5, 2]. The default value is 1, which means no change to the pitch. The smaller the value, the lower the pitch.
    pan

    Spatial position of the local audio effect. The range is [-1.0, 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 range is [0.0, 100,0] The default value is 100.0. The smaller the value, the lower the volume of the audio effect
    publish

    Set whether 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: Method call succeeded
    • < 0: Method call failed

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

    Stop Playing an Audio Effect (stopEffect)

    int stopEffect(int soundId);

    This method stops playing a specific audio effect.

    Name Description
    soundId ID of the audio effect. Each audio effect has a unique ID.
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Stop Playing all Audio Effects (stopAllEffects)

    int stopAllEffects();

    This method stops playing all the audio effects.

    Preload an Audio Effect (preloadEffect)

    int preloadEffect(int soundId, String filePath);

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

    To ensure smooth communication, pay attention to the size of the audio effect file. Agora recommends using this method to preload the audio effect before calling joinChannel.

    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: Method call succeeded
    • <0: Method call failed

    Release an Audio Effect (unloadEffect)

    int unloadEffect(int soundId);

    This method releases a specific preloaded audio effect from the memory.

    Name Description
    soundId ID of the audio effect. Each audio effect has a unique ID.
    Return Value
    • 0: Method call succeeded
    • <0: Method call failed

    Pause an Audio Effect (pauseEffect)

    int pauseEffect(int soundId);

    This method pauses a specific audio effect.

    Name Description
    soundId ID of the audio effect. Each audio effect has a unique ID.
    Return Value
    • 0: Method call succeeded
    • <0: Method call failed

    Pause all Audio Effects (pauseAllEffects)

    int pauseAllEffects();

    This method pauses all the audio effects.

    Name Description
    Return Value
    • 0: Method call succeeded
    • <0: Method call failed

    Resume an Audio Effect (resumeEffect)

    int resumeEffect(int soundId);

    This method resumes playing a specific audio effect.

    Name Description
    soundId ID of the audio effect. Each audio effect has a unique ID.
    Return Value
    • 0: Method call succeeded
    • <0: Method call failed

    Resume Playing all Audio Effects (resumeAllEffects)

    int resumeAllEffects();

    This method resumes playing all the audio effects.

    Enable the Video Mode (enableVideo)

    virtual int enableVideo() = 0;

    The application can call this method either before entering a channel or during a call. If it is called before entering a channel, the service starts in the video mode; if it is called during a call, it switches from the audio to video mode. To disable the video mode, call the disablevideo method.

    Name Description
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    This method sets to enable the internal engine, and still works after leaveChannel is called.

    Disable the Video Mode (disableVideo)

    virtual int disableVideo() = 0;

    This method disables the video mode. The application can call this method either before entering a channel or during a call. If it is called before entering a channel, the service starts in the audio mode; if it is called during a call, it switches from the video to audio mode. To enable the video mode, call the enablevideo method.

    Name Description
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    This method sets to disable the internal engine, and still works after leaveChannel is called.

    Enable 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 enableVideo, otherwise this method may not work properly.

    • After enableVideo is called, the local video will be enabled by default. This method is useds to enable and disable the local video while the remote video remains unaffected.

    Name Description
    enabled

    Sets to enable the local video:

    • true: Enable the local video (default)
    • false: 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 set to false, this method does not require a local camera.
    Return value
    • 0: Method call succeeded
    • < 0: Method call failed

    This method sets to enable/disable the internal engine, and still works after leaveChannel is called.

    Set the Video Profile (setVideoProfile)

    virtual int setVideoProfile(VIDEO_PROFILE_TYPE profile, bool swapWidthAndHeight) = 0;

    This method sets the video encoding profile. Each profile includes a set of parameters, such as the resolution, frame rate, and bitrate. When the camera device does not support the specified resolution, the SDK will automatically choose a suitable camera resolution, while the encoder resolution will still be the one specified by setVideoProfile.

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

    Name Description
    profile The video profile. See the following 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: Method call succeeded.
    • < 0: Method call failed.

    Landscape Mode

    Video Profile Enumeration Resolution (Width x Height) Frame Rate(fps) Bitrate
    VIDEO_PROFILE_LANDSCAPE_120P 0 160 x 120 15 65
    VIDEO_PROFILE_LANDSCAPE_120P_3 2 120 x 120 15 50
    VIDEO_PROFILE_LANDSCAPE_180P 10 320 x 180 15 140
    VIDEO_PROFILE_LANDSCAPE_180P_3 12 180 x 180 15 100
    VIDEO_PROFILE_LANDSCAPE_180P_4 13 240 x 180 15 120
    VIDEO_PROFILE_LANDSCAPE_240P 20 320 x 240 15 200
    VIDEO_PROFILE_LANDSCAPE_240P_3 22 240 x 240 15 140
    VIDEO_PROFILE_LANDSCAPE_240P_4 23 424 x 240 15 220
    VIDEO_PROFILE_LANDSCAPE_360P 30 640 x 360 15 400
    VIDEO_PROFILE_LANDSCAPE_360P_3 32 360 x 360 15 260
    VIDEO_PROFILE_LANDSCAPE_360P_4 33 640 x 360 30 600
    VIDEO_PROFILE_LANDSCAPE_360P_6 35 360 x 360 30 400
    VIDEO_PROFILE_LANDSCAPE_360P_7 36 480 x 360 15 320
    VIDEO_PROFILE_LANDSCAPE_360P_8 37 480 x 360 30 490
    VIDEO_PROFILE_LANDSCAPE_360P_9 38 640 x 360 15 800
    VIDEO_PROFILE_LANDSCAPE_360P_10 39 640 x 360 24 800
    VIDEO_PROFILE_LANDSCAPE_360P_11 100 640 x 360 24 1000
    VIDEO_PROFILE_LANDSCAPE_480P 40 640 x 480 15 500
    VIDEO_PROFILE_LANDSCAPE_480P_3 42 480 x 480 15 400
    VIDEO_PROFILE_LANDSCAPE_480P_4 43 640 x 480 30 750
    VIDEO_PROFILE_LANDSCAPE_480P_6 45 480 x 480 30 600
    VIDEO_PROFILE_LANDSCAPE_480P_8 47 848 x 480 15 610
    VIDEO_PROFILE_LANDSCAPE_480P_9 48 848 x 480 30 930
    VIDEO_PROFILE_LANDSCAPE_480P_10 49 640 x 480 10 400
    VIDEO_PROFILE_LANDSCAPE_720P 50 1280 x 720 [3] 15 1130
    VIDEO_PROFILE_LANDSCAPE_720P_3 52 1280 x 720 [3] 30 1710
    VIDEO_PROFILE_LANDSCAPE_720P_5 54 960 x 720 [3] 15 910
    VIDEO_PROFILE_LANDSCAPE_720P_6 55 960 x 720 [3] 30 1380
    VIDEO_PROFILE_LANDSCAPE_1080P 60 1920 x 1080 [3] 15 2080
    VIDEO_PROFILE_LANDSCAPE_1080P_3 62 1920 x 1080 [3] 30 3150
    VIDEO_PROFILE_LANDSCAPE_1080P_5 64 1920 x 1080 [3] 60 4780
    VIDEO_PROFILE_LANDSCAPE_1440P 66 2560 x 1440 [3] 30 4850
    VIDEO_PROFILE_LANDSCAPE_1440P_2 67 2560 x 1440 [3] 60 6500
    VIDEO_PROFILE_LANDSCAPE_4K 70 3840 x 2160 [3] 30 6500
    VIDEO_PROFILE_LANDSCAPE_4K_3 72 3840 x 2160 [3] 60 6500

    Portrait Mode

    Video Profile Enumeration Resolution (Width x Height) Frame Rate(fps) Bitrate
    VIDEO_PROFILE_PORTRAIT_120P 1000 120 x 160 15 65
    VIDEO_PROFILE_PORTRAIT_120P_3 1002 120 x 120 15 50
    VIDEO_PROFILE_PORTRAIT_180P 1010 180 x 360 15 140
    VIDEO_PROFILE_PORTRAIT_180P_3 1012 180 x 180 15 100
    VIDEO_PROFILE_PORTRAIT_180P_4 1013 180 x 240 15 120
    VIDEO_PROFILE_PORTRAIT_240P 1020 240 x 320 15 200
    VIDEO_PROFILE_PORTRAIT_240P_3 1022 240 x 240 15 140
    VIDEO_PROFILE_PORTRAIT_240P_4 1023 240 x 424 15 220
    VIDEO_PROFILE_PORTRAIT_360P 1030 360 x 640 15 400
    VIDEO_PROFILE_PORTRAIT_360P_3 1032 360 x 360 15 260
    VIDEO_PROFILE_PORTRAIT_360P_4 1033 360 x 640 30 600
    VIDEO_PROFILE_PORTRAIT_360P_6 1035 360 x 360 30 400
    VIDEO_PROFILE_PORTRAIT_360P_7 1036 360 x 480 15 320
    VIDEO_PROFILE_PORTRAIT_360P_8 1037 360 x 480 30 490
    VIDEO_PROFILE_PORTRAIT_360P_9 1038 360 x 640 15 800
    VIDEO_PROFILE_PORTRAIT_360P_10 1039 360 x 640 24 800
    VIDEO_PROFILE_PORTRAIT_360P_11 1100 360 x 640 24 1000
    VIDEO_PROFILE_PORTRAIT_480P 1040 480 x 640 15 500
    VIDEO_PROFILE_PORTRAIT_480P_3 1042 480 x 480 15 400
    VIDEO_PROFILE_PORTRAIT_480P_4 1043 480 x 640 30 750
    VIDEO_PROFILE_PORTRAIT_480P_6 1045 480 x 480 30 600
    VIDEO_PROFILE_PORTRAIT_480P_8 1047 480 x 848 15 610
    VIDEO_PROFILE_PORTRAIT_480P_9 1048 480 x 848 30 930
    VIDEO_PROFILE_PORTRAIT_480P_10 1049 480 x 640 10 400
    VIDEO_PROFILE_PORTRAIT_720P 1050 720 x 1280 [3] 15 1130
    VIDEO_PROFILE_PORTRAIT_720P_3 1052 720 x 1280 [3] 30 1710
    VIDEO_PROFILE_PORTRAIT_720P_5 1054 720 x 960 [3] 15 910
    VIDEO_PROFILE_PORTRAIT_720P_6 1055 720 x 960 [3] 30 1380
    VIDEO_PROFILE_PORTRAIT_1080P 1060 1080 x 1920 [3] 15 2080
    VIDEO_PROFILE_PORTRAIT_1080P_3 1062 1080 x 1920 [3] 30 3150
    VIDEO_PROFILE_PORTRAIT_1080P_5 1064 1080 x 1920 [3] 60 4780
    VIDEO_PROFILE_PORTRAIT_1440P 1066 1440 x 2560 [3] 30 4850
    VIDEO_PROFILE_PORTRAIT_1440P_2 1067 1440 x 2560 [3] 60 6500
    VIDEO_PROFILE_PORTRAIT_4K 1070 2160 x 3840 [3] 30 6500
    VIDEO_PROFILE_PORTRAIT_4K_3 1072 2160 x 3840 [3] 60 6500

    [3] Whether 720p or over can be supported depends on the device. If the device cannot support 1080p, the frame rate will be lower than the one listed in the table. Agora optimizes the video in lower-end devices. Contact support@agora.io for special requirements.

    Set the Local Video View (setupLocalVideo)

    virtual int setupLocalVideo(const VideoCanvas& canvas) = 0;

    This method configures the video display settings on the local machine.

    The application calls this method to bind with the video window (view) of local video streams and configure the video display settings. Call this method after initialization to configure the local video display settings before entering a channel. After leaving the channel, the bind is still valid, which means the window still displays. To unbind the window, set the view value to NULL when calling setupLocalVideo.

    Name Description
    canvas

    Video display settings. Class VideoCanvas:

    • view: Video display window (view).
    • renderMode: Video display mode.
      • RENDER_MODE_HIDDEN (1): Uniformly scale the video until it fills the visible boundaries. One dimension of the video may have clipped contents.
      • RENDER_MODE_FIT (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 will be filled with black.
    • Return value: The local user ID as set in the joinchannel method.
    Return Value
    • 0: Method call succeeded.
    • < 0: Method call failed.
    struct VideoCanvas {
    view_t view;
    int renderMode;
    uid_t uid;
    };

    Set the Remote Video View (setupRemoteVideo)

    virtual int setupRemoteVideo(const VideoCanvas& canvas) = 0;

    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 application should specify the uid of the remote video in the method call before the user enters a channel.

    If the remote uid is unknown to the application, set it later when the application receives the onUserJoined event. If the Video Recording function is enabled, the Video Recording Service joins the channel as a dumb client, which means other clients also receive this onUserJoined event. Your application should not bind it with the view, because it does not send any video stream. If your application cannot recognize the dumb client, bind it with the view when the onFirstRemoteVideoDecoded event is triggered. To unbind the user with the view, set the view to null. Once the user has left the channel, the SDK unbinds the remote user.

    Name Description
    canvas

    Video display settings. Class VideoCanvas:

    • view: Video display window (view).
    • renderMode: Video display mode.
      • RENDER_MODE_HIDDEN (1): Uniformly scale the video until it fills the visible boundaries. One dimension of the video may have clipped contents.
      • RENDER_MODE_FIT (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 will be filled with black.
    Return Value
    • 0: Method call succeeded.
    • < 0: Method call failed.
    struct VideoCanvas {
    view_t view;
    int renderMode;
    uid_t uid;
    };

    Enable Dual-stream Mode (enableDualStreamMode)

    int enableDualStreamMode(boolean enabled);

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

    Name Description
    enabled

    The mode is in single stream or dual stream:

    • True: Dual stream
    • False: Single stream
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Set the Remote Video-stream Type (setRemoteVideoStreamType)

    int setRemoteVideoStreamType(uid_t uid, REMOTE_VIDEO_STREAM_TYPE 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 enableDualStreamMode, you will receive the high-video stream by default. This method allows the application to adjust the corresponding video-stream type according to the size of the video windows to save the bandwidth and calculation resources.

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

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

    Name Description
    uid User ID
    streamType

    Set the video-stream size.

    The following lists the video-stream types:

    • REMOTE_VIDEO_STREAM_HIGH(0): High-video stream
    • REMOTE_VIDEO_STREAM_LOW(1): Low-video stream
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Set the Default Remote Video Stream Type (setRemoteDefaultVideoStreamType)

    int setRemoteDefaultVideoStreamType(REMOTE_VIDEO_STREAM_TYPE streamType);

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

    Name Description
    streamType

    The default remote video stream:

    • REMOTE_VIDEO_STREAM_HIGH(0): High video stream
    • REMOTE_VIDEO_STREAM_LOW(1): Low video stream
    Return Value
    • 0: Method call succeeded.
    • < 0: Method call failed.

    Set High-quality Video Preferences (setVideoQualityParameters)

    int setVideoQualityParameters(bool preferFrameRateOverImageQuality);

    This method allows users to set video preferences.

    Name Description
    preferFrameRateOverImageQuality

    The video preference to be set:

    • True: Frame rate over image quality
    • False: Image quality over frame rate (default)
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Start Video Preview (startPreview)

    virtual int startPreview() = 0;

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

    • Call setupLocalVideo to set up the local preview window and configure the attributes

    • Call enableVideo to enable video

    Once startPreview is called to start the local video preview, if you call stopPreview before leaving the channel, call setRemoteVideo the next time you join a channel, or you will not be able to see the remote video view.

    Name Description
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Stop Video Preview (stopPreview)

    virtual int stopPreview() = 0;

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

    Name Description
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Set the Local Video Display Mode (setLocalRenderMode)

    int setLocalRenderMode(RENDER_MODE_TYPE renderMode);

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

    Name Description
    mode

    Configures the video display mode:

    • RENDER_MODE_HIDDEN (1): Uniformly scale the video until it fills the visible boundaries. One dimension of the video may have clipped contents.
    • RENDER_MODE_FIT (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 will be filled with black.
    Return Value
    • 0: Method call succeeded.
    • < 0: Method call failed.

    Set the Remote Video Display Mode (setRemoteRenderMode)

    int setRemoteRenderMode(uid_t uid, RENDER_MODE_TYPE renderMode);

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

    Name Description
    uid The user UID of the user whose video streams are received.
    mode

    Configures the video display mode:

    • RENDER_MODE_HIDDEN (1): Uniformly scale the video until it fills the visible boundaries. One dimension of the video may have clipped contents.
    • RENDER_MODE_FIT (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 will be filled with black.
    Return Value
    • 0: Method call succeeded.
    • < 0: Method call failed.

    Set the Local Video Mirror Mode (setLocalVideoMirrorMode)

    int setLocalVideoMirrorMode(VIDEO_MIRROR_MODE_TYPE mirrorMode);

    This method sets the local video mirror mode. Use this method before startPreview, or it does not take effect until you re-enable startPreview.

    Name Description
    mode

    Sets the local video mirror mode

    • VIDEO_MIRROR_MODE_AUTO = 0: The default mirror mode, that is, the mode set by the SDK
    • VIDEO_MIRROR_MODE_ENABLED = 1: Enable the mirror mode
    • VIDEO_MIRROR_MODE_DISABLED = 2: Disable the mirror mode
    Return value
    • 0: Method call succeeded
    • < 0: Method call failed

    Enable Web SDK Interoperability (enableWebSdkInteroperability)

    int enableWebSdkInteroperability(bool enabled);

    This method enables interoperability with the Agora Web SDK.

    Name Description
    enabled

    Whether to enable the interoperability with the Agora Web SDK is enabled:

    • True: Enable the interoperability
    • False: Disable the interoperability
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Enable Built-in Encryption and Set the Encryption Secret (setEncryptionSecret)

    virtual int setEncryptionSecret(const char* secret) = 0;

    Use setEncryptionSecret to specify 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 has left the channel. If the encryption password is not specified or set to empty, the encryption function will be disabled.

    Do not use this function together with CDN.

    Name Description
    secret Encryption Password
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Set the Built-in Encryption Mode (setEncryptionMode)

    virtual int setEncryptionMode(const char* encryptionMode) = 0;

    AThe 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 API to set the encryption mode.

    All users in the same channel must use the same encryption mode and password. Refer to information related to the AES encryption algorithm on the differences between encryption modes.

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

    Do not use this function together with CDN

    Name Description
    encryptionMode

    Encryption mode. The following modes are currently 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 it is set to NUL string, the encryption is in “aes-128-xts” by default.
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Create a Data Stream (createDataStream)

    virtual int createDataStream(int* streamId, bool reliable, bool ordered) = 0;

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

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

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

    [4] 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.

    Send a Data Stream (sendStreamMessage)

    virtual int sendStreamMessage(int streamId, const char* data, size_t length) = 0;

    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 returned by createDataStream
    data Data to be sent
    Return Value

    When it fails to send the message, the following error code will be returned:

    ERR_SIZE_TOO_LARGE/ERR_TOO_OFTEN/ERR_BITRATE_LIMIT

    Start an Audio Call Test (startEchoTest)

    virtual int startEchoTest() = 0;

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

    • After calling the startEchoTest method, call stopEchoTest to end the test; otherwise, the application 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 mode from communication to live broadcast, ensure that setClientRole is called to change the user role from audience(default in the live broadcast mode) to broadcaster before using this method.
    Name Description
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.
      • ERR_REFUSED (-5): Failed to launch the echo test, for example, initialization failed.

    Stop an Audio Call Test (stopEchoTest)

    virtual int stopEchoTest() = 0;

    This method stops an audio call test.

    Name Description
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.
      • ERR_REFUSED(-5): Failed to stop the echo test. It could be that the echo test is not running.

    Enable the Network Test (enableLastmileTest)

    virtual int enableLastmileTest() = 0;

    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 disableLastmileTest to disable it immediately once the users have received the onLastmileQuality callback before they join the channel or switch the user role.

    For current hosts, do not call this method.

    Name Description
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Disable the Network Test (disableLastmileTest)

    virtual int disableLastmileTest() = 0;

    This method disables the network connection quality test.

    Name Description
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Retrieve the Current Call ID (getCallId)

    virtual int getCallId(agora::util::AString& callId) = 0;

    When a user joins a channel on a client, a CallId is generated to identify the call from the client. Some methods such as rate and complain need to be called after the call ends in order to submit feedback to the SDK. These methods require assigned values of the CallId parameters. To use these feedback methods, call the getCallId 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
    callId The current call ID.
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Rate the Call (rate)

    virtual int rate(const char* callId, int rating, const char* description) = 0;

    This method lets the user rate the call. It is usually called after the call ends.

    Name Description
    callId Call ID retrieved from the getCallId method.
    rating The rating for the call between 1 (lowest score) to 10 (highest score).
    description

    A given description for the call with a length less than 800 bytes.

    This parameter is optional.

    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.
      • ERR_INVALID_ARGUMENT (-2): The passed argument is invalid, for example, callId invalid.
      • ERR_NOT_READY (-3): The SDK status is incorrect, for example, initialization failed.

    Complain about the Call Quality (complain)

    virtual int complain(const char* callId, const char* description) = 0;

    This method allows the user to complain about the call quality. It is usually called after the call ends.

    Name Description
    callId Call ID retrieved from the getCallId method.
    description

    A given description of the call with a length less than 800 bytes.

    This parameter is optional.

    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.
      • ERR_INVALID_ARGUMENT (-2): The passed argument is invalid, for example, callId invalid.
      • ERR_NOT_READY (-3): The SDK status is incorrect, for example, initialization failed.

    Renew Token (renewtoken)

    virtual int renewToken(const char* token) = 0;

    This method updates the Channel Key.

    The key expires after a certain period of time once the Token schema is enabled. When:

    • The onError callback reports the error ERR_TOKEN_EXPIRED(109), or
    • The onRequestToken callback reports the error ERR_TOKEN_EXPIRED(109)

    The application should retrieve a new key and then call this method to renew it. Failure to do so will result in the SDK disconnecting with the server.

    Name Description
    token Specifies the Channel Key to be renewed.
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Specify a Log File (setLogFile)

    int setLogFile(const char* 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 code.
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

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

    Set the Log Filter (setLogFilter)

    int setLogFilter(unsigned int filter);

    This method sets the output log level 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 logs that precede that level.

    For example, if you set the log level as WARNING, then you can see logs in levels CRITICAL, ERROR and WARNING.

    Name Description
    filter

    Set the levels of the filters:

    • LOG_FILTER_OFF = 0: Output no log.
    • LOG_FILTER_DEBUG = 0x80f: Output all the API logs.
    • LOG_FILTER_INFO = 0x0f: Output logs of the CRITICAL, ERROR, WARNING and INFO level.
    • LOG_FILTER_WARNING = 0x0e: Output logs of the CRITICAL, ERROR and WARNING level.
    • LOG_FILTER_ERROR = 0x0c: Output logs of the CRITICAL and ERROR level.
    • LOG_FILTER_CRITICAL = 0x08: Output logs of the CRITICAL level.
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Release the IRtcEngine Object (release)

    virtual void release() = 0;

    This method releases the IRtcEngine object.

    Name Description
    sync

    Indicates whether this method is called synchronously or asynchronously.

    • True: Synchronous call. 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 in order to recover the associated object resources, resulting in a deadlock. The SDK automatically detects the deadlock and turns it into an asynchronous call, but the test itself takes extra time.
    • False: Asynchronous call. The result returns immediately even when the IRtcEngine object resources are not released, and the SDK will release all resources on its own. Pay attention: Do not immediately uninstall the SDK’s dynamic library after the call, otherwise it may crash because the SDK clean-up thread has not quit.
    Return Value
    • <0: error code.
    • 0: method call succeed.

    Get the SDK Version (getVersion)

    virtual const char* getVersion(int* build) = 0;

    This method returns the string of the SDK version number in char format.

    Parameter Methods (RtcEngineParameters)

    This is an auxiliary class that sets parameters for the SDK. The following section describes each of the methods in this class.

    Mute the Local Audio Stream (muteLocalAudioStream)

    int muteLocalAudioStream(bool mute);

    This method mutes/unmutes local audio. It enables/disables sending local audio streams to the network.

    This method does not disable the microphone, and thus does not affect the recording process, if any.
    This method takes effect only when the user is in the channel. After the user leaves the channel, all the mute states are reset.

    Name Description
    mute
    • True: Mutes local audio.
    • False: Unmutes local audio.
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Mute All Remote Audio Streams (muteAllRemoteAudioStreams)

    int muteAllRemoteAudioStreams(bool mute);

    This method enables/disables playing all remote callers’ audio streams.

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

    Name Description
    mute
    • True: Stops playing all the received audio streams.
    • False: Allows playing all the received audio streams.
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Mute A Specified Remote Audio Stream (muteRemoteAudioStream)

    int muteRemoteAudioStream(uid_t uid, bool mute);

    This method mutes/unmutes the audio streams of a specified user. It enables or disables playing a certain user’s audio streams.

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

    Name Description
    uid User ID whose audio streams the user intends to mute.
    mute
    • True: Stops playing a specified user’s audio streams.
    • False: Allows playing a specified user’s audio streams.
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Mute the Local Video Stream (muteLocalVideoStream)

    int muteLocalVideoStream (bool mute);

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

    When set to True, this method does not disable the camera and thus does not affect the retrieval of local video streams. This method responds faster than enableLocalVideo (false).
    This method takes effect only when the user is in the channel. After the user leaves the channel, all the mute states are reset.

    Name Description
    mute
    • True: Stops sending local video streams to the network.
    • False: Allows sending local video streams to the network.
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Mute All Remote Video Streams (muteAllRemoteVideoStreams)

    int muteAllRemoteVideoStreams(bool mute);

    This method enables/disables playing all remote callers’ video streams.

    When set to True, this method stops playing video streams without affecting the video stream receiving process.
    This method takes effect only when the user is in the channel. After the user leaves the channel, all the mute states are reset.

    Name Description
    mute
    • True: Stops playing all the received video streams.
    • False: Allows playing all the received video streams.
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Mute a Specified Remote Video Stream (muteRemoteVideoStream)

    int muteRemoteVideoStream(uid_t uid, bool mute);

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

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

    Name Description
    uid User ID of the specified user.
    mute
    • True: Stops playing a specified user’s video stream.
    • False: Allows playing a specified user’s video stream.
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Enable the Audio Volume Indication (enableAudioVolumeIndication)

    int enableAudioVolumeIndication(int interval, int smooth);

    This method enables the SDK to regularly report to the application on which user is talking and the volume of the speaker. Once the method is enabled, the SDK returns the volume indications at the set time internal in the [Audio Volume Indication Callback onAudioVolumeIndication callback, 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 between two consecutive volume indications in milliseconds. Agora recommends setting it to more than 200 ms. Do not set it lower than 10 ms, or the onAudioVolumeIndication callback will not be triggered.
    smooth Smoothing factor. The default value is 3
    Return values
    • 0: Method call succeeded
    • < 0: Method call failed

    Start Audio Mixing (startAudioMixing)

    int startAudioMixing(const char* filePath, bool loopback, bool replace, int 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 API also supports online music playback.

    Call this API 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: Local audio file mixed 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.

    Stop Audio Mixing (stopAudioMixing)

    int stopAudioMixing();

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

    Name Description
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Pause Audio Mixing (pauseAudioMixing)

    int pauseAudioMixing();

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

    Name Description
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Resume Audio Mixing (resumeAudioMixing)

    int resumeAudioMixing();

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

    Name Description
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Adjust the Audio Mixing Volume (adjustAudioMixingVolume)

    int adjustAudioMixingVolume(int volume);

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

    Name Description
    volume Volume ranging from 0 to 100. By default, 100 is the original volume.
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Get the Audio Mixing Duration (getAudioMixingDuration)

    int getAudioMixingDuration();

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

    Get the Current Audio Position (getAudioMixingCurrentPosition)

    int getAudioMixingCurrentPosition();

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

    Drag the Audio Progress Bar (setAudioMixingPosition)

    int setAudioMixingPosition(int pos /*in ms*/);

    This method drags the playback progress bar of the audio mixing file to where you want to play instead of playing it from the beginning.

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

    Start an Audio Recording (startAudioRecording)

    int startAudioRecording(const char* filePath, AUDIO_RECORDING_QUALITY_TYPE quality);

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

    • .wav: Large file size with high sound fidelity OR

    • .aac: Small file size with low sound fidelity

    Ensure that the directory to save the recording file exists and is writable. Call this method after the joinChannel method. The recording automatically stops when the leaveChannel method is called.

    Name Description
    filePath Full file path of the recording file. The string of the file name is in UTF-8 code.
    Return Value
    • 0: Method call succeeded
    • <0: Method call failed

    Stop an Audio Recording (stopAudioRecording)

    int stopAudioRecording();

    This method stops recording on the client.

    Call this method before calling leaveChannel; otherwise the recording automatically stops when the leaveChannel method is called.

    Name Description
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Adjust the Recording Volume (adjustRecordingSignalVolume)

    int adjustRecordingSignalVolume(int volume);

    This method adjusts the recording volume.

    Name Description
    volume

    Recording volume, ranges from 0 to 400:

    • 0: Mute
    • 100: Original volume
    • 400: (Maximum) Four times the original volume with signal clipping protection
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Adjust the Playback Volume (adjustPlaybackSignalVolume)

    int adjustPlaybackSignalVolume(int volume);

    This method adjusts the playback volume.

    Name Description
    volume

    Playback volume, ranges from 0 to 400:

    • 0: Mute
    • 100: Original volume
    • 400: (Maximum) Four times the original volume with signal clipping protection
    Return Value
    • 0: Method call succeeded.
    • <0: Method call failed.

    Callback Methods (IRtcEngineEventHandler)

    The SDK uses the agora::IRtcEngineEventHandler interface class to send callback event notifications to the application, and the application inherits the methods of this interface class to retrieve these event notifications. All methods in this interface class have their (empty) default implementations, and the application can inherit only some of the required events instead of all of them. In the callback methods, the application should avoid time-consuming tasks or calling blocking APIs, for example, SendMessage, otherwise the SDK may not work properly.

    Join a Channel Callback (onJoinChannelSuccess)

    virtual void onJoinChannelSuccess (const char* channel, uid_t uid, int elapsed);

    This callback indicates that the user has successfully joined the specified channel.

    Name Description
    channel The channel name.
    uid

    User ID.

    If the uid is specified in the joinChannel method, it returns the specified ID; if not, it returns an ID that is automatically assigned by the Agora server.

    elapsed Time elapsed (ms) from calling joinChannel until this event occurs.

    Rejoin Channel Callback (onRejoinChannelSuccess)

    virtual void onRejoinChannelSuccess(const char* channel, uid_t uid, int elapsed);

    When the client loses connection with the server because of network problems, the SDK automatically attempts to reconnect, and then triggers this callback method upon reconnection.

    Name Description
    channel The channel name.
    uid User ID.
    elapsed Time elapsed (ms) from calling joinChannel until this event occurs.

    Warning Occurred Callback (onWarning)

    virtual void onWarning(int warn, const char* msg);

    This callback method indicates that some warning occurred during SDK runtime. In most cases the application can ignore the warnings reported by the SDK, because the SDK can usually fix the issue and resume running. For instance, the SDK may report an ERR_OPEN_CHANNEL_TIMEOUT warning upon disconnection with the server and attempts to reconnect.

    Name Description
    warn The warning code.
    msg The warning message.

    Error Occurred Callback (onError)

    virtual void onError(int err, const char* msg);

    This callback indicates that a network or media error occurred 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 application or simply informs the user on the issue. For instance, the SDK reports an ERR_START_CALL error when failing to initialize a call. In this case, the application informs the user that the call initialization failed and calls the leaveChannel method to exit the channel.

    Name Description
    err

    Error code:

    • ERR_INVALID_VENDOR_KEY(101): Invalid App ID.
    • ERR_INVALID_CHANNEL_NAME(102): Invalid channel name.
    • ERR_LOOKUP_CHANNEL_REJECTED(105): Failed to look up the channel, because the server rejected the request.
    • ERR_OPEN_CHANNEL_REJECTED(107): Failed to join the channel, because the media server rejected the request.
    • ERR_LOAD_MEDIA_ENGINE(1001): Failed to load the media engine.
    • ERR_START_CALL(1002): Failed to turn on the local audio or video devices and thus failed to start a call.
    • ERR_START_CAMERA(1003): Failed to turn on the local camera.
    msg The error message.

    API Call Executed Callback (onApiCallExecuted)

    virtual void onApiCallExecuted(int err, const char* api, const char* result);

    This callback is triggered when the API has been executed.

    Name Description
    error The error code that the SDK returns when the method call fails. If the SDK returns o, then the method has been called successfully.
    api The API that the SDK executes
    result The result of calling the API

    The State of the Microphone Has Changed Callback (onMicrophoneEnabled)

    virtual void onMicrophoneEnabled(bool enabled)
    Name Description
    enabled
    • true: The microphone is enabled.
    • false: The microphone is disabled.

    Audio Quality Callback (onAudioQuality)

    virtual void onAudioQuality(uid_t uid, int quality, unsigned short delay, unsigned short lost);

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

    Name Description
    uid User ID of the speaker
    quality

    Rating of the audio quality:

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

    Audio Volume Indication Callback (onAudioVolumeIndication)

    virtual void onAudioVolumeIndication (const AudioVolumeInfo* speakers, unsigned int speakerNumber, int totalVolume);

    This callback indicates who is talking and the speaker’s volume. By default the indication 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. The uid of the local user is 0.
    • volume: The volume of the speaker between 0 (lowest volume) to 255 (highest volume).
    speakerNumber Total number of speakers.
    totalVolume Total volume after audio mixing between 0 (lowest volume) to 255 (highest volume).

    In the returned speakers array:

    • If the uid is 0, that is, the local user is the speaker, the returned volume is the same as totalVolumn.

    • If the uid is not 0 and the volume is 0, it indicates that the user specified by the uid did not speak.

    • If a uid is contained in the previous speakers array but not in the present one, it indicates that the user specified by the uid did not speak.

    Leave Channel Callback (onLeaveChannel)

    virtual void onLeaveChannel(const RtcStats& stat);

    When the application calls the leaveChannel() method, the SDK uses this callback to notify the application that the user has successfully left the channel. With this callback function, the application retrieves information such as the call duration and the statistics of data received/transmitted by the SDK.

    Definition of RtcStats

    struct RtcStats
    {
        unsigned int duration;
        unsigned int txBytes;
        unsigned int rxBytes;
        unsigned short txKBitRate;
        unsigned short rxKBitRate;
    
        unsigned short rxAudioKBitRate;
        unsigned short txAudioKBitRate;
    
        unsigned short rxVideoKBitRate;
        unsigned short txVideoKBitRate;
        unsigned int userCount;
        double cpuAppUsage;
        double cpuTotalUsage;
    };
    Name Description
    stats

    Statistics about the call:

    • duration: Call duration in seconds, 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.
    • txKBitRate: Transmission bitrate in kbps, represented by an instantaneous value.
    • rxKBitRate: Receive bitrate in kbps, represented by an instantaneous value.
    • txAudioKBitrate: Audio transmission bitrate in kbps, represented by an instantaneous value.
    • rxAudioKBitRate: Audio receive bitrate in kbps, represented by an instantaneous value.
    • txVideoKBitRate: Video transmission bitrate in kbps, represented by an instantaneous value.
    • rxVideoKBitRate: Video receive bitrate in kbps, represented by an instantaneous value.
    • users: The instant number of users in the channel when the user leaves the channel.
    • puTotalUsage: System CPU usage (%).
    • cpuAppUsage: Application CPU usage (%).

    Other User Joined Channel Callback (onUserJoined)

    virtual void onUserJoined(uid_t uid, int elapsed);

    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.
    elapsed Time delay (ms) from calling joinChannel until this callback is triggered.

    Other User Offline Callback (onUserOffline)

    virtual void onUserOffline(uid_t uid, USER_OFFLINE_REASON_TYPE reason);

    This callback notifies the application that the broadcaster has left the channel 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

    This callback is triggered when:

    • USER_OFFLINE_QUIT(0): User has quit the call.
    • USER_OFFLINE_DROPPED(1): The SDK timed out and the user dropped offline because it has not received a data package within a certain period of time. 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.

    Video Size Changed Callback (onVideoSizeChanged)

    virtual void onVideoSizeChanged(uid_t uid, int width, int height, int rotation);

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

    Parameter Description
    uid User ID.
    width Width (pixels) of the video frame.
    height Height (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.

    The View Destroyed Callback (onViewDestroyed)

    virtual void onViewDestroyed() = 0;

    This callback is triggered when the video display window is destroyed.

    Call Session Statistics Callback (onRtcStats)

    virtual void onRtcStats(const RtcStats& stats);

    The SDK updates the application on the statistics of the call session once every two seconds.

    Name Description
    stat See descriptions in Leave Channel Callback (onLeaveChannel) .

    Local Video Statistics Callback (onLocalVideoStats)

    virtual void onLocalVideoStats(const LocalVideoStats& stats);

    The SDK updates the application on the statistics of uploading local video streams once every two seconds. The definition of LocalVideoStats is listed as follows:

    struct LocalVideoStats
    {
        int sentBitrate;
        int sentFrameRate;
    };
    Name Description
    stats

    The statistics of the local video, including:

    • sentBitrate: Transmission bitrate (kbit/s) since last count.
    • sentFrameRate: Transmission frame rate (fps) since last count.

    Remote Video Statistics Callback (onRemoteVideoStats)

    virtual void onRemoteVideoStats(const RemoteVideoStats& stats);

    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 RemoteVideoStats

    struct RemoteVideoStats
    {
        uid_t uid;
        int delay;  // obsolete
      int width;
      int height;
      int receivedBitrate;
      int receivedFrameRate;
        REMOTE_VIDEO_STREAM_TYPE rxStreamType;
    };
    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 (pixels) of the video stream.
    • height: Height (pixels) of the video stream.
    • receivedBitrate: The data receive bitrate (kbit/s) since last count.
    • receivedFrameRate: The data receive frame rate (fps) since last count.
    • rxStreamType: The stream type. High video stream or low video stream.

    First Local Audio Frame Sent Callback (onFirstLocalAudioFrame)

    virtual void onFirstLocalAudioFrame(int elapsed);

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

    Name Description
    elapsed Time elapsed (ms) from calling joinChannel until this callback is triggered.

    First Remote Audio Frame Received Callback (onFirstRemoteAudioFrame)

    virtual void onFirstRemoteAudioFrame(uid_t uid, int 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 Received and Displayed Callback (onFirstLocalVideoFrame)

    virtual void onFirstLocalVideoFrame(int width, int height, int elapsed);

    This callback is triggered when the first local video frame is displayed on the video window.

    Name Description
    width Width (pixels) of the video stream.
    height Height (pixels) of the video stream.
    elapsed Time elapsed (ms) from calling joinChannel until this callback is triggered.

    Frist Remote Video Frame Received and Decoded Callback (onFirstRemoteVideoDecoded)

    virtual void onFirstRemoteVideoDecoded(uid_t uid, int width, int height, int elapsed);

    This callback is triggered upon receiving and successfully decoding the first frame of the remote video. The application can configure the user view settings in this callback.

    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 calling joinChannel until this callback is triggered.

    First Remote Video Frame Received and Displayed Callback (onFirstRemoteVideoFrame)

    virtual void onFirstRemoteVideoFrame(uid_t uid, int width, int height, int elapsed, int elapsed);

    This method is triggered upon the display of the first frame of remote video on the user’s video window. The application can retrieve the time elapsed from a user joining the channel until the first video frame is displayed.

    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 calling joinChannel until this callback is triggered.

    Remote Video State Changed Callback (onRemoteVideoStateChanged)

    virtual void onRemoteVideoStateChanged(uid_t uid, REMOTE_VIDEO_STATE 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 vide:

    • REMOTE_VIDEO_STATE_RUNNING = 1: the remote video is normal
    • REMOTE_VIDEO_STATE_FROZEN = 2: the remote video is frozen

    Network Quality Callback (onLastmileQuality)

    virtual void onLastmileQuality(int quality);

    This callback reports on the network quality. It is triggered once every two seconds after enableLastmileTest() is called. When not in a call and the network test is enabled (by calling enableLastmileTest), this callback function is triggered irregularly to update the application on the network connection quality of the local user.

    Name Description
    quality

    Quality of the last mile network:

    • QUALITY_UNKNOWN(0): The network quality is unknown.
    • QUALITY_EXCELLENT(1): The network quality is excellent.
    • QUALITY_GOOD(2): The network quality is quite good, but the bitrate may be slightly lower than excellent.
    • QUALITY_POOR(3): Users can feel the communication slightly impaired.
    • QUALITY_BAD(4): Users can communicate only not very smoothly.
    • QUALITY_VBAD(5): The network is so bad that users can hardly communicate.
    • QUALITY_DOWN(6): Users cannot communicate at all.

    Channel Network Quality Callback (onNetworkQuality)

    virtual void onNetworkQuality(uid_t uid, int txQuality, int rxQuality);

    This callback is triggered every 2 seconds to update the application on the 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:

    • QUALITY_UNKNOWN(0): The network quality is unknown.
    • QUALITY_EXCELLENT(1): The network quality is excellent.
    • QUALITY_GOOD(2): The network quality is quite good, but the bitrate may be slightly lower than excellent.
    • QUALITY_POOR(3): Users can feel the communication slightly impaired.
    • QUALITY_BAD(4): Users can communicate only not very smoothly.
    • QUALITY_VBAD(5): The network is so bad that users can hardly communicate.
    • QUALITY_DOWN(6): Users cannot communicate at all.
    rxQuality

    The receiving quality of the user:

    • QUALITY_UNKNOWN(0): The network quality is unknown.
    • QUALITY_EXCELLENT(1): The network quality is excellent.
    • QUALITY_GOOD(2): The network quality is quite good, but the bitrate may be slightly lower than excellent.
    • QUALITY_POOR(3): Users can feel the communication slightly impaired.
    • QUALITY_BAD(4): Users can communicate only not very smoothly.
    • QUALITY_VBAD(5): The network is so bad that users can hardly communicate.
    • QUALITY_DOWN(6): Users cannot communicate at all.

    Other User Muted Audio Callback (onUserMuteAudio)

    virtual void onUserMuteAudio(uid_t uid, bool muted);

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

    Name Description
    uid User ID.
    muted
    • True: User has muted his/her audio.
    • False: User has unmuted his/her audio.

    Other User Paused/Resumed Video Callback (onUserMuteVideo)

    virtual void onUserMuteVideo(uid_t uid, bool muted);

    This callback indicates that some other user has paused/resumed his/her video streams.

    Name Description
    uid User ID.
    muted
    • True: User has muted his/her audio.
    • False: User has unmuted his/her audio.

    Other User Enabled/Disabled Video Callback (onUserEnableVideo)

    virtual void onUserEnableVideo(uid_t uid, bool enabled);

    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
    • true: The user has enabled the video function and can enter a video call or video live broadcast.
    • false: 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 (onUserEnableLocalVideo)

    virtual void onUserEnableLocalVideo(uid_t uid, bool enabled);

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

    Name Description
    uid User ID
    enabled
    • true: The user has enabled the local video function. Other users in the channel can see the video of this user.
    • false: 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.

    Camera Ready Callback (onCameraReady)

    virtual void onCameraReady();

    This callback indicates that the camera is turned on and ready to capture video. If the camera fails to turn on, handle the error in the onError() method.

    Video Stopped Callback (onVideoStopped)

    virtual void onVideoStopped();

    This callback indicates that the video has 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.

    Connection Interrupted Callback (onConnectionInterrupted)

    virtual void onConnectionInterrupted();

    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 (onConnectionLost)

    virtual void onConnectionLost();

    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 (onConnectionBanned)

    virtual void onConnectionBanned();

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

    Data Stream Received Callback (onStreamMessage)

    virtual void onStreamMessage(uid_t uid, int streamID, const char* data, size_t length);

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

    Name Description
    uid User ID
    data Data received by the recipients.
    length Length of the data

    Data Stream Sent Failure Callback (onStreamMessageError)

    virtual void onStreamMessageError(uid_t uid, int streamId, int code, int missed, int 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
    code
    • 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

    Token Expired Callback (onRequestToken)

    virtual void onRequestToken();

    When a Channel Key is specified by calling joinChannel(), if the SDK lost connection with the Agora server due to network issues, the Channel Key may expire after a certain period of time and a new Channel Key may be required to reconnect to the server.

    This callback notifies the application of generating a new Token, and calling renew token to specify the newly generated Channel Key.

    This function was previously provided in the callback report of onError(): ERR_TOEKN_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.

    Audio Mixing File Playback Finished Callback (onAudioMixingFinished)

    virtual void onAudioMixingFinished();

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

    Local Audio Effect Playback Finished Callback (onAudioEffectFinished)

    virtual void onAudioEffectFinished(int soundId)

    This callback is triggered when the local audio effect playback is finished.

    Name Description
    soundId ID of the audio effect. Each audio effect has a unique ID.

    Active Speaker Detected Callback (onActiveSpeaker)

    virtual void onActiveSpeaker(uid_t uid);

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

    User Role Changed Callback (onClientRoleChanged)

    virtual void onClientRoleChanged(CLIENT_ROLE_TYPE oldRole, CLIENT_ROLE_TYPE 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.

    Error Codes

    See Error Codes and Warning Codes.