Live Broadcast API - iOS

Objective-C Interface Class Description
Basic Methods(AgoraRtcEngineKit) The AgoraRtcEngineKit class provides all the methods that can be invoked by your application.
Delegate Methods(AgoraRtcEngineDelegate) The AgoraRtcEngineDelegate class enables callback event notifications to your application.
Block Callbacks

Delegate methods are replacing the use of some Block callbacks from version 1.1 of the SDK. The Block callbacks are also documented below.

However, where appropriate 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 declare the Block method, and:

    • if you implement Block, it works.
    • if you implement Delegate, the Delegate won’t take effect.
  • If you declare the Delegate method, and:

    • if you implement Block, the Delegate won’t take effect.
    • if you implement Delegate, it works.

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)sharedEngineWithappId:(NSString*)appId
delegate:( id<AgoraRtcEngineDelegate>) 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  

Implement Audio Live Broadcast

The following shows how to implement a basic audio live broadcast function. The developers can add more functions to the basic audio live broadcast according to the following modules included in this document. Be sure that an AgoraRtcEngineKit instance has been initialized for the application.

../../_images/ios_audio_api_live.png

Set Channel Profile (setChannelProfile)

- (int)setChannelProfile (AgoraRtcChannelProfile) profile;

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

The Agora Native SDK currently supports the following profiles:

Profile Description
Communication The default setting. It is most commonly used in one-on-one conversations or meetings, where all users in the channel can talk freely.
Live Broadcast Live Broadcast has host and audience roles which can be set by calling setClientRole.,The host sends and receives audio/video, while the audience only receives audio/video only with sending function disabled.
Game Game Voice Mode. Any user in the channel can speak freely. This mode uses the codec with low power consumption and low bitrate by default.

Note

  • You can only use one profile at the same time in the same channel.
  • This method must be called and configured before user joining a channel, because the channel profile cannot be configured when the channel is in use.
Name Description
profile

The channel profile. Choose from the following:

  • AgoraRtc_ChannelProfile_Communication: Communication (default)
  • AgoraRtc_ChannelProfile_Broadcasting: Live Broadcast
  • AgoraRtc_ChannelProfile_Game: Game Voice
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set User Role(setClientRole)

- (int)setClientRole:(AgoraRtcClientRole)role withKey: (NSString *)permissionKey;

This method allows you to set the user role as a host or an audience(default) before joining a channel. This method also allows you to switch the user role after joining a channel.

Name Description
role The user role in a live broadcast:
  • AgoraRtc_ClientRole_Broadcaster = 1; Host
  • AgoraRtc_ClientRole_Audience = 2; Audience(default)
permissionKey

If you have not enabled the host-in authentication function, set it as NULL.

If you have enabled the host-in authentication function, depending on different user roles:

  • Audience: set it as NULL.
  • Host: set it as the In Channel Permission Key. For details, refer to Agora Keys User Guide.
Return Value
  • 0: The Method is called successfully
  • <0: Failed to call the method

Enable Audio Mode(enableAudio)

- (int)enableAudio;

This method enables 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.

Disable Audio Mode(disableAudio)

- (int)disableAudio;

This method disables audio mode.

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

Set High Quality Audio Preferences(setHighQualityAudioParametersWithFullband)

- (int)setHighQualityAudioParametersWithFullband:(BOOL)fullband
                            stereo:(BOOL)stereo
                       fullBitrate:(BOOL)fullBitrate;

This method sets the high quality audio preferences. Be sure that you call this method and set all the three modes before joining channel. Do NOT call this method again after joining channel.

Name Description
fullband

Full band codec (48kHz sampling rate), not compatible with the versions earlier than v1.7.4.

  • True: enable the full band codec.
  • False: disable use the full band codec.
stereo

Stereo codec, not compatible with the versions earlier than v1.7.4.

  • True: enable the stereo codec.
  • False: disable the stereo codec.
fullBitrate

High bitrate. Using in audio-only mode is recommended.

  • True: enable the high bitrate mode.
  • False: Disable the high bitrate mode.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Join Channel (joinChannelByKey)

- (int)joinChannelByKey:(NSString *)channelKey
            channelName:(NSString *)channelName
            info:(NSString *)info
            uid:(NSUInteger)uid
            joinSuccess:(void(^)(NSString* channel, NSUInteger uid, NSInteger elapsed))joinChannelSuccessBlock;

This method lets a user 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, and so operating on this object may affect the SDK’s audio functions.

Note

One channel does not accept duplicated UIDs, for example, two users with the same UID. If your App supports the function of one user logging in from different devices simultaneously, be sure that you will use different UIDs. For example, if you used the same UID previously, add the respective Device ID in the UID to make the UIDs different. This action does not apply to the scenario if your App does not support one user logging in from different devices, for example, you log onto a new device and it will be forced to quit on the previously logged-in device.

Name Description
channelKey

The token is a Channel Key generated by the application.

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

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

In most developer circumstances, the static App ID should suffice. For users who have a high security requirement, use the Channel Key.

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:a-z,A-Z,0-9,space,!

#$%&,()+,

-,:;<=.,>?

@[],^_,{|},~

info (Optional) Any additional information the developer wants to add. [1] It can be set as NULL Sting or channel related information. Other users in the channel won’t receive this information.
uid Optional) User ID: a 32-bit unsigned integer ranges from 1 to (2^32-1). It must be unique. If not assigned (or set to 0), the SDK allocates one and returns it in joinSuccessBlock callback. The app must record and maintain the returned value, as the SDK does not maintain it.

Footnotes

[1]For example, when a host wants to customize the resolution and bitrate for a live broadcast channel with Bypass Live enabled, they can include them in this parameter in Json format. For example, {“owner”:true, …, “width”:300, “height”:400, “bitrate”:100}; Here, only when none of width, height, and bitrate is 0 can the settings of bitrate and resolution take effect.

Note

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), if any, will be interrupted.

Leave Channel (leaveChannel)

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

This method lets the user leave a channel, that is, 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. Calling the leaveChannel method even when not in a call is harmless.

The leaveChannel method releases all recourses related to the call. The leaveChannel method is called asynchronously, and the user actually does not exit the channel when the call returns. When the user exits the channel, the SDK triggers didLeaveChannelWithstats callback.

Note

If you call destroy() immediately after you have called leaveChannel, it will interrupt the leavechannel process, which means the SDK won’t trigger the didLeaveChannelWithstats callback.

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

Implement Video Live Broadcast

The following shows how to implement a basic video live broadcast function. The developers can add more functions to the basic audio live broadcast according to the following modules included in this document. Be sure that a AgoraRtcEngineKit instance has been initialized for the application.

For the highlighted APIs same as the audio communication, refer to the description in the Implement Audio Live Broadcast.

../../_images/ios_video_api_live.png

Set Local Video View (setupLocalVideo)

- (int)setupLocalVideo:(AgoraRtcVideoCanvas*)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 configures the video display settings.

In application development, a usual practice is to call this method after initialization to configure local video display settings before entering a channel. The bind is still valid after exiting the channel. To unbind the view, set the view value to NULL when calling setupLocalVideo.

Name Description
local

Configures the video settings. AgoraRTCVideoCanvas types:

  • view: The video display window (view). The SDK does not maintain the lifecycle of the view, and it is the responsibility of the application to ensure that the view is valid during the call, otherwise it may cause the SDK to crash. The view can be safely released after calling leaveChannel with a returned value.
  • renderMode: The video display mode.
    • AgoraRtc_Render_Hidden(1): If the video size is different than that of the display window, crops the borders of the video (if the video is bigger) or stretch the video (if the video is smaller) to fit it in the window.
    • AgoraRtc_Render_Fit(2): If the video size is different than that of the display window, resizes the video proportionally to fit the window.
    • AgoraRtc_Render_Adaptive(3):Adjusts based on the orientations. If both callers use the same screen orientation, that is, both use vertical screens or both use horizontal screens, the AgoraRtc_Render_Hidden mode applies; if they use different screen orientations, that is, one vertical and one horizontal, the AgoraRtc_Render_Fit mode applies.
  • uid: The local user ID as set in the joinChannelByKey method.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set Remote Video View (setupRemoteVideo)

- (int)setupRemoteVideo:(AgoraRtcVideoCanvas*)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 didJoinedOfUid event.

If the Video Recording function is enabled, the Video Recording Service joins the channel as a dumb client, which means others clients will also receive its 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. To unbind the user with the view, set the view to null. After the user left the channel, the SDK unbinds the remote user.

Name Description
remote Configures the video settings. AgoraRTCVideoCanvas types:
  • view: The video display window (view). The SDK does not maintain the lifecycle of the view, and it is the responsibility of the application to ensure that the view is valid during the call, otherwise it may cause the SDK to crash. The view can be safely released after calling leaveChannel with a returned value.
  • renderMode: The video display mode.
    • AgoraRtc_Render_Hidden(1): If the video size is different than that of the display window, crops the borders of the video (if the video is bigger) or stretch the video (if the video is smaller) to fit it in the window.
    • AgoraRtc_Render_Fit(2): If the video size is different than that of the display window, resizes the video proportionally to fit the window.
    • AgoraRtc_Render_Adaptive(3): This mode adjusts to the orientations. If both callers use the same screen orientation, that is, both use vertical screens or both use horizontal screens, the AgoraRtc_Render_Hidden mode applies; if they use different screen orientations, that is, one vertical and one horizontal, the AgoraRtc_Render_Fit mode applies. uid: User ID of the remote user whose video streams are received.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Enable Video Mode (enableVideo)

- (int)enableVideo;

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

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

Disable Video (disableVideo)

- (int) disableVideo;

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

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

Set Video Profile (setVideoProfile)

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

This method sets the video encoding profile.

Each profile includes a set of parameters such as resolution, frame rate, bitrate and son. When the device camera does not support the specified resolution, the SDK automatically chooses a suitable camera resolution, but the encoder resolution still uses the one specified by setVideoProfile.

The method only sets the attributes of the streams encoded by the encoder which may be inconsistent with the final display. For example, when the resolution of the encoded stream is 640x480, and the rotation attribute of the stream is 90 degrees, then the resolution of the final display is in portrait mode.

Note

  • Always set the video profile after calling the enableVideo method.
  • Always set the video profile before calling the joinChannel/startPreview method.
Name Description
profile Video profile. See the table below for more details.
swapWidthAndHeight

Whether to swap the width and height of the stream:

  • YES: swap
  • NO: not swap(default)
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Video Profile Definition

Video Profile Enum value Resolution (width * height) Frame Rate (fps) Bitrate(kbps)
120P 0 160x120 15 65
120P_3 2 120x120 15 50
180P 10 320x180 15 140
180P_3 12 180x180 15 100
180P_4 13 240x180 15 120
240P 20 320x240 15 200
240P_3 22 240x240 15 140
240P_4 24 424x240 15 220
360P 30 640x360 15 400
360P_3 32 360x360 15 260
360P_4 33 640x360 30 600
360P_6 35 360x360 30 400
360P_7 36 480x360 15 320
360P_8 37 480x360 30 490
360P_9 38 640x360 15 800
360P_10 39 640x360 24 800
360P_11 100 640x360 24 1000
480P 40 640x480 15 500
480P_3 42 480x480 15 400
480P_4 43 640x480 30 750
480P_6 45 480x480 30 600
480P_8 47 848x480 15 610
480P_9 48 848x480 30 930
720P 50 1280x720 * [2] 15 1130
720P_3 52 1280x720 * [2] 30 1710
720P_5 54 960x720 * [2] 15 910
720P_6 55 960x720 * [2] 30 1380

Footnotes

[2](1, 2, 3, 4) Achieving 720P resolution depends on the performance and capabilities of the device and may not currently be possible on lower performance devices. If a device has inadequate performance then low frame rates may be experienced when using 720P. Agora.io is continuing to optimize video for lower-end devices in future releases – contact support@agora.io to discuss particular device needs.

Enable Dual Stream Mode(enableDualStreamMode)

- (int) enableDualStreamMode: (BOOL)enabled;

This method sets the stream mode: Single(default) or Dual Stream, which is only applicable to the live broadcast scenario.

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 Video Stream Type(setRemoteVideoStream)

- (int)setRemoteVideoStream: (NSUInteger)uid type:(AgoraRtcVideoStreamType)streamType

This method specifies the video stream type of the remote user to be received by the local when the remote user sends dual streams. This method allows the application to adjust the corresponding video stream type according to the size of the video windows to save bandwidth and calculation resources.

The result after calling this method will be returned in didApiCallExecute. Agora SDK receives the high video stream by default. 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:

  • AgoraRtc_VideoStream_High(0): High Video Stream
  • AgoraRtc_VideoStream_Low(1): Low Video Stream
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

The resolution of high video stream is 1.1, 4.3 and 16.9. The low video stream has the same aspect ratio:

Resolution Frame Rate Keyframe Interval Bitrate(kbps)
160*160 5 5 45
160*120 5 5 32
160*90 5 5 28

Set High-Quality Video Preferences(setVideoQualityParameters)

- (int) setVideoQualityParameters:(BOOL)enabled;

This method allows the users to set the video preferences.

Name Description
enabled

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.

Set Picture-in-Picture Layout(setVideoCompositingLayout)

- (int)setVideoCompositingLayout:(AgoraRtcVideoCompositingLayout*)layout;

This method sets the picture-in-picture layouts for the live broadcast scenario. This method is only applicable when you want to push streams at the Agora server side. When you push the stream at the server side:

  1. You need to define a canvas, its width and height(video resolution), the background color and the number of videos you want to display in total.
  2. You need to define the position and size of each video on the canvas, whether the picture is cropped or zooming to fit and etc.

The push stream application will format the detailed information of the customized layouts as JSON and package it to the Supplemental Enhancement Information(SEI) of each key frame when generating the H.264 video stream and pushing it to the CDN vendors via RTMP protocol.

The definition of layout is listed as follows:

@interface AgoraRtcVideoCompositingLayout : NSObject
@property (assign, nonatomic) NSInteger canvasWidth;
@property (assign, nonatomic) NSInteger canvasHeight;
@property (copy, nonatomic) NSString* backgroundColor;//e.g. "#c0c0c0"
@property (retain, nonatomic) NSArray* regions; //array of AgoraRtcVideoCompositingRegion
@property (copy, nonatomic) NSString* appData;//app defined data
@end

Parameter details are explained in the following table, and you can also read Adjust Picture-in-Picture to understand the parameters better with different scenario examples.

Note

  • Be sure that you call this method after joining channel.
  • The Application should gurantee that only one user calls this method in the same channel, if more than one user calls this method, the rest users must call clearVideoCompositingLayout to remove the settings.
Name Description
canvasWidth The width of the entire canvas(The display window or screen).
canvasHeight The height of the entire canvas(The display window or screen).
backgroundColor Enter any of the 6-digit symbols defined in RGB.
regions

The array of AgoraRtcVideoCompositingRegion. Each host in the channel can have a region to display the video on the screen with the following parameters to be set:

  • uid: The user id of the user with the video to be displayed on the region.
    • x[0.0,1.0]: the horizontal position of the region on the screen.
    • y[0.0,1.0]: the vertical position of the region on the screen.
    • width[0.0, 1.0]: the actual width of the region.
    • height[0.0, 1.0]: the actual height of the region.
  • zOrder[0, 100]: 0 means the region is on the bottom, and 100 means the region is on the top.
  • alpha[0.0, 1.0]: 0 means the region is transparent, and 1 means the region is opaque.
  • renderMode:
    • RENDER_MODE_HIDDEN(1): Cropped
    • RENDER_MODE_FIT(2): Zoom to fit
appData The application defined data.

Here is an example used to describe the position and size of the region:

../../_images/sei_overview.png

Remove the Picture-in-Picture Layout Settings(clearVideoCompositingLayout)

- (int)clearVideoCompositingLayout;

This method removes the settings made after calling setVideoCompositingLayout.

Configure Push-Stream for Bypass Live(configPublisher)

- (int)configPublisher:(AgoraPublisherConfiguration *)config;

This method configures the push-stream settings for the engine before joining channel for the bypass live.

Before you call the methods listed in this section:

  • Be sure that the bypass-live push-stream function is enabled by contacting Agora.io
  • Be sure that only the user who has called setClientRole and set the user role as host can use the methods in this section
  • The host must call the related methods before joining channel

The properties of AgoraPublisherConfiguration are listed as follows:

@property (assign, nonatomic) NSInteger width;
@property (assign, nonatomic) NSInteger height;
@property (assign, nonatomic) NSInteger framerate;
@property (assign, nonatomic) NSInteger bitrate;
@property (assign, nonatomic) NSInteger defaultLayout;
@property (assign, nonatomic) AgoraRtmpStreamLifeCycle lifeCycle;
@property (copy, nonatomic) NSString* publishUrl;
@property (copy, nonatomic) NSString* rawStreamUrl;
@property (copy, nonatomic) NSString* injectStreamUrl;
@property (copy, nonatomic) NSString* extraInfo;

Note

  • Check the AgoraPublisherConfiguration Interface for how to call each method included for push-stream settings configuration.
  • Be sure that set the resolution, frame rate and bitrate the same as that of the host uplink to avoid the video quality degradation.

AgoraPublisherConfiguration Interface

Set RTMP Stream Owner(owner)
- (AgoraPublisherConfigurationBuilder *) setOwner:(BOOL)isOwner;

In AgoraPublisherConfiguration, this method sets whether the current host is the RTMP Stream owner.

Name Description
isRoomOwner
  • true: Yes. This is the default value. When it is set as true, the push-stream configuration takes effect.
  • false: No. The push-stream configuration won’t work.
Set the Stream Resolution(setWidth)
- (AgoraPublisherConfigurationBuilder *) setWidth:(NSInteger)width height:(NSInteger)height framerate:(NSInteger)framerate bitrate:(NSInteger)bitrate;

In AgoraPublisherConfiguration , this method sets the resolution of the output data stream set for the bypass live.

Name Description
width The width of the output data stream set for the bypass live. 360 is the default value
height The height of the output data stream set for the bypass live. 640 is the default value
framerate The frame rate of the output data stream set for the bypass live. 15 fps is the default value
bitrate The bitrate of the output data stream set for the bypass live. 500 Kbps is the default value
Set Stream LifeCycle(setLifeCycle)
- (AgoraPublisherConfigurationBuilder *) setLifeCycle:(AgoraRtmpStreamLifeCycle)lifecycle;

In AgoraPublisherConfiguration , this method sets the resolution of the output data stream set for the bypass live.

Name Description
lifecycle

It specifies the video stream lifecyle of the bypass live, which can be either of the following values:

  • RTMP_STREAM_LIFE_CYCLE_BIND2CHANNEL = 1: Bound to the channel lifecycle
  • RTMP_STREAM_LIFE_CYCLE_BIND2OWNER = 2: Bound to the owner identity of the RTMP stream
Set Default Layout(setDefaultLayout)
- (AgoraPublisherConfigurationBuilder *) setDefaultLayout:(NSInteger)layoutStyle;

In AgoraPublisherConfiguration , this method sets the Default Layout if you do not use Flexible Adjustment .

Name Description
layoutStyle
  • 0: Tile Horizontally
  • 1: Layered Windows
  • 2: Tile Vertically
Set Publish URL(setPublisherUrl)
- (AgoraPublisherConfigurationBuilder *) setPublisherUrl:(NSString*)url;

In AgoraPublisherConfiguration , this method configures the push-stream address for the picture-in-picture layouts.

Name Description
url It configures the push-stream address for the picture-in-picture layouts. The default value is NULL
Set Raw Stream URL(setRawStreamUrl)
- (AgoraPublisherConfigurationBuilder *) setRawStreamUrl:(NSString*)url;

In AgoraPublisherConfiguration , this method sets the push-stream address of the original stream which does not require picture-blending.

Name Description
url The push-stream address of the original stream. The default value is NULL
Set Inject Stream(injectStreamUrl)
- (AgoraPublisherConfigurationBuilder *) injectStreamUrl:(NSString *)url width:(NSInteger)width height:(NSInteger)height;

In the Builder class, this method injects a stream to the current channel.

Name Description
url The address of the stream to be injected to the channel.
width The width of the stream. Set it as 0 currently.
height The height of the stream. Set it as 0 currently.
Add Extra Information (setExtraInfo)
- (AgoraPublisherConfigurationBuilder *) setExtraInfo:(NSString *)info;
Name Description
info Reserved Field. The default value is NULL

Start Video Preview (startPreview)

- (int)startPreview;

This method starts the local video preview. Before starting the preview, always call setupLocalVideo to setup the preview window and configure its attributes and also call the enableVideo method to enable video. If before calling joinChannelByKey to join the channel, you have called startPreview to start the local video preview, then the local preview will be still in the started state after you called leaveChannel to exit the channel. You can call stopPreview to close the local preview.

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 Local Video Display Mode (setLocalRenderMode)

- (int)setLocalRenderMode:(AgoraRtcRenderMode) 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 video mode.

  • AgoraRtcRenderMode types:
    • AgoraRtc_Render_Hidden(1): If the video size is different than that of the display window, crops the borders of the video (if the video is bigger) or stretch the video (if the video is smaller) to fit it in the window.
    • AgoraRtc_Render_Fit(2): If the video size is different than that of the display window, resizes the video proportionally to fit the window.
    • AgoraRtc_Render_Adaptive(3): This mode adjusts to the orientations. If both callers use the same screen orientation, that is, both use vertical screens or both use horizontal screens, the AgoraRtc_Render_Hidden mode applies; if they use different screen orientations, that is, one vertical and one horizontal, the AgoraRtc_Render_Fit mode applies.
  • uid: User ID of the remote user whose video streams are received.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set Remote Video Display Mode (setRemoteRenderMode)

- (int)setRemoteRenderMode: (NSUInteger)uid mode:(AgoraRtcRenderMode) 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 mode. AgoraRtcRenderMode types:

  • AgoraRtc_Render_Hidden(1): If the video size is different than that of the display window, crops the borders of the video (if the video is bigger) or stretch the video (if the video is smaller) to fit it in the window.
  • AgoraRtc_Render_Fit(2): If the video size is different than that of the display window, resizes the video proportionally to fit the window.
  • AgoraRtc_Render_Adaptive(3): This mode adjusts to the orientations. If both callers use the same screen orientation, that is, both use vertical screens or both use horizontal screens, the AgoraRtc_Render_Hidden mode applies; if they use different screen orientations, that is, one vertical and one horizontal, the AgoraRtc_Render_Fit mode applies. uid: User ID of the remote user whose video streams are received.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

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.

Start Playing Video Stream(startPlayingStream)

- (int) startPlayingStream:(NSString*)uri;

This method plays the video stream from the network.

Note

This method is obsolete, which will be removed later.

Name Description
uri The link of the video stream
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Stop Playing Video Stream(stopPlayingStream)

- (int) stopPlayingStream;

This method stops playing the video stream from the network.

Note

This method is obsolete, which will be removed later.

Name Description
uri The link of the video stream
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Enable Web SDK Interoperability(enableWebSdkInteroperability)

- (int)enableWebSdkInteroperability:(BOOL)enabled;

This method enables the interoperability with Agora Web SDK.

The relations between Agora Native SDK and Agora Web SDK can be found in Agora Product Overview.

Note

Due to Agora Web SDK is a beta version, the performance may be not very stable. Contact the support if any issue occurs.

Name Description
enabled

The interoperability with Agora Web SDK is enabled or not:

  • True: the interoperability is enabled with Agora Web SDK.
  • False: the interoperability is disabled with Agora Web SDK.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Configure External Video Source

This section introduces how to configure an external video source for users who want to capture video data by themselves. It merges the original external video source function supported in the libvideoprp and the texture encoding interfaces. It pushes the yuv/rgba/texture pictures to the Agora SDK for encoding.

Note

It is recommended that the new application under development use this method for better usability.

Check Whether Texture Encoding Is Supported (isTextureEncodeSupported)

+ (BOOL) isTextureEncodeSupported;

This method checks whether the texture encoding is supported.

Name Description
Return Value

True: Texture encoding is supported

False: Texture encoding is not supported

Configure the External Video Source(setExternalVideoSource)

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

This method sets whether to use an external video source or not:

  • If yes, whether to use texture as input as not;
  • If yes, whether to push the video frame to the Agora SDK for encoding or not;
Name Description
enable [3]

Whether you want to use an external video source:

  • True: use external video source
  • False: do not use external video source
useTexture

Whether you want to use Texture as input:

  • True: use texture as input
  • False: do not use texture as input
pushMode

Whether the external video source needs to call PushExternalVideoFrame to send the video frame to the Agora SDK:

  • True: use the push mode
  • False: use the pull mode(not supported yet)

Footnotes

[3]Currently the Agora SDK does not support switching video source dynamically in the channel. If you have enabled the external video source and you are now in a channel, and if you want to switch to the internal video source, you must exit the channel, call this method to set enable as false, then join channel again.

Push the External Video Frame (pushExternalVideoFrame)

- (BOOL) pushExternalVideoFrame:(AgoraVideoFrame *)frame;

This method encapsulates the video frame using the AgoraVideoFrame class and passes it to the Agora SDK, and the supported input formats are:

typedef NS_ENUM(NSUInteger, AgoraVideoFormat) {
   AgoraRtc_FrameFormat_texture = 12,
   AgoraRtc_FrameFormat_I420 = 1,
   AgoraRtc_FrameFormat_RGBA = 4,
   AgoraRtc_FrameFormat_IMC2 = 5,
};

Be sure that you have called setExternalVideoSource and set the parameter pushMode as true before calling this method. Otherwise, it will always return failure after calling this method.

Name Description
frame The video frame that contains the video data to be encoded by the Agora SDK.
Return Value
  • True: the frame is pushed successfully
  • False: failed to push the frame

The definition of AgoraVideoFrame class:

@interface AgoraVideoFrame : NSObject
@property (assign, nonatomic) NSInteger format;
@property (assign, nonatomic) long long timeStamp;
@property (assign, nonatomic) int stride;
@property (assign, nonatomic) int height;

@property (assign, nonatomic) CVPixelBufferRef textureBuf;

@property (strong, nonatomic) NSData *dataBuf;
@property (assign, nonatomic) int cropLeft;
@property (assign, nonatomic) int cropTop;
@property (assign, nonatomic) int cropRight;
@property (assign, nonatomic) int cropBottom;
@property (assign, nonatomic) int rotation;
@end

The detailed explanation of the fields are listed in the following table:

format Mandatory Field

The format of the incoming video frame, which must be specified as one of the following:

  • AgoraRtc_FrameFormat_texture = 12
  • AgoraRtc_FrameFormat_I420 = 1
  • AgoraRtc_FrameFormat_RGBA = 4
  • AgoraRtc_FrameFormat_IMC2 = 5
timestamp Mandatory Field The timestamp of the incoming video frame in milliseconds. Incorrect timestamp will result in frame loss or unsynchronized audio and video.
stride Mandatory Field The line spacing of the incoming video frame, which must be in pixel instead of byte.
height Mandatory Field The height of the incoming video frame.
textureBuf Texture Related Field When the format of the incoming video frame is texture, assign CVPixelBufferRef to it.
dataBuf Raw Data Related Field When the format of the incoming video frame is the raw data of YUV or RGBA, it is the data of the incoming video frame
cropLeft, cropTop, cropRight, cropBottom Raw Data Related Field (Optional) It specifies the number of pixels trimmed in each direction, which is set as 0 by default.
rotation Raw Data Related Field (Optional) It specifies whether to rotate the incoming video group. The optional value: 0, 90, 180, or 270. It is set as 0 by default.

Manage Audio Effects

Get Audio Effect Volume(getEffectsVolume)

- (double) getEffectsVolume;

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

Set Audio Effect Volume (setEffectsVolume)

- (int) setEffectsVolume:(double) volume;

This method sets the volume of the audio effects.

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 Audio Effect Volume in Real Time(setVolumeOfEffect)

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

This method adjusts the volume of the specified sound effect in realtime.

Name Description
soundId The 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 Audio Effect(playEffect)

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

This method plays the audio effect.

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

It sets whether to play the audio effect in loops

  • True: yes, it will be played in loops
  • False: no (default)
pitch

It sets whether to change the pitch of the audio effect. The range is [0.5, 2] with 1.0 as the default value, which means no need to change the pitch.

The smaller the value is set, the lower the pitch will be.

pan

It sets whether to change the spatial position of the audio effect. The range is [-1, 1]:

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

It 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, and the volume the audio effect will be.

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

Footnotes

[4]If you have loaded the audio effect to the memory via preloadEffect, be sure that the soundId to be set here is the same as the one set in preloadEffect

Stop Playing Audio Effect(stopEffect)

- (int) stopEffect:(int) soundId;

This method stops playing a specific audio effect.

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

Pre-Load Audio Effect(preloadEffect)

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

This method pre-loads a specific audio effect file, which is a compressed audio file, to the memory.

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

Release Audio Effect(unloadEffect)

- (int) unloadEffect:(int) soundId;

This method releases the specific pre-loaded audio effect from the memory.

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

Pause Audio Effect(pauseEffect)

- (int) pauseEffect:(int) soundId;

This method pauses the specific audio effect.

Name Description
soundId The 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 Audio Effect (resumeEffect)

- (int) resumeEffect:(int) soundId;

This method resumes playing a specific audio effect.

Name Description
soundId The 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) resumeAllEffects;

This method resumes all the audio effects.

Set Audio Route

Enable Speakerphone(setEnableSpeakerphone)

- (int)setEnableSpeakerphone:(BOOL)enableSpeaker;

This method enables audio output 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, and so any soundis interrupted when calling this method.

Name Description
enableSpeaker
  • Yes: Switches to speaker.
  • No: Switches to headset.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Is Speakerphone Enabled? (isSpeakerphoneEnabled)

- (BOOL)isSpeakerphoneEnabled;

This method tests whether the speakerphone is enabled or not.

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

Set Default Audio Route(setDefaultAudioRouteToSpeakerPhone)

- (int)setDefaultAudioRouteToSpeakerphone:(BOOL)defaultToSpeaker;

This method sets whether the received audio is routed to the earpiece or the speakerphone. 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 In-Ear Monitoring(enableInEarMonitoring)

- (int)enableInEarMonitoring:(BOOL)enabled;

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

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

Set Audio Volume

Enable Audio Volume Indication (enableAudioVolumeIndication)

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

This method enables the SDK to regularly report to the application on who is speaking and the volume of the speaker.

Name Description
interval

Specifies the time interval between two consecutive volume indications.

  • <=0: Disables volume indication.
  • >0: The volume indication interval in milliseconds. We recommend setting it to a minimum of 200ms.
smooth The smoothing factor. recommended default value is 3.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Mute Audio and Video Stream

Mute Local Audio Stream (muteLocalAudioStream)

- (int)muteLocalAudioStream:(BOOL)mute;

This method mutes/unmutes local audio.

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 mutes/unmutes all remote callers’ audio streams.

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

Mute Certain Remote Audio Stream (muteRemoteAudioStream)

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

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

Note

When set to True, this method stops playing audio streams without affecting the audio stream receiving process.

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 Local Video Stream (muteLocalVideoStream)

- (int)muteLocalVideoStream:(BOOL)muted;

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

Note

When set to Yes, this method does not disable the camera and thus does not affect the retrieval of local video stream.

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

Disable Local Video(enableLocalVideo)

- (int)enableLocalVideo:(BOOL)enabled

This method 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. This method does not require a local camera.

Name Description
enabled
  • YES: Enable the local video(by default)
  • NO: Disable the local video
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Mute All Remote Video Streams (muteAllRemoteVideoStreams)

- (int)muteAllRemoteVideoStreams:(BOOL)muted;

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

Note

When set to Yes, this method stops playing video streams without affecting the video stream receiving process.

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 Certain Remote Video Stream (muteRemoteVideoStream)

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

This method pauses/resumes playing a specified user’s video, that is, enables/disables playing a specified user’s video stream.

Note

When set to Yes, this method stops playing video streams without affecting the video stream receiving process.

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.

Audio Mixing

Start Audio Mixing (startAudioMixing)

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

This method mixes the specified local audio file with the audio stream collected by the microphone, or replaces the audio stream collected by the microphone with the specified local audio file. You can decide whether the other user can hear the local audio playback and specify the number of loop playbacks.

Note

  • If you want to use the startAudioMixing API, then ensure that iOS device is >=8.0.
  • Call this API when you are in the channel, otherwise it will probably cause issues.
Name Description
filePath

Specify the name and path of the local audio file to be mixed.

The following lists the supported audio formats: mp3, aac, m4a, 3gp, 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 collected by the microphone
  • False: Mix the content of the local audio file with the audio stream collected by the microphone
cycle

Specify the number of loop playbacks:

  • Positive integer: the 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 mixing the specified local audio with the microphone input. Call this API when you are in the channel.

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

Pause Audio Mixing (pauseAudioMixing)

- (int)pauseAudioMixing;

This method pauses mixing the specified local audio with the microphone input. Call this API when you are in the channel.

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

Resume Audio Mixing (resumeAudioMixing)

- (int)resumeAudioMixing;

This method resumes mixing the specified local audio with the microphone input. Call this API when you are in the channel.

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

Adjust Audio Mixing Volume (adjustAudioMixingVolume)

- (int)adjustAudioMixingVolume:(NSInteger) volume;

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

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

Get the Audio Mixing Duration(getAudioMixingDuration)

- (int)getAudioMixingDuration;

This method gets the duration(in milliseconds) of the music. Call this API when you are in the channel.

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

Get Music Current Position(getAudioMixingCurrentPosition)

- (int)getAudioMixingCurrentPosition;

This method gets the duration(in milliseconds) of the music that has been played. Call this API when you are in the channel.

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

Drag Audio Progress Bar(setAudioMixingPosition)

- (int)setAudioMixingPosition:(NSInteger) pos;

This method drags the progress bar of the audio mixing file to the place wherever you want to play instead of playing it from the very beginning to the end.

Name Description
pos Integer. The position of the audio mixing file in milliseconds.

Recording

Start Audio Recording (startAudioRecording)

- (int)startAudioRecording:(NSString*)filePath;

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

  • .wav : relatively large file size with high sound fidelity OR
  • .aac : relatively small file size with low sound fidelity

Ensure that the saving directory in the application exists and is writable. This method is usually called after the joinChannelByKey method. The recording automatically stops when the leaveChannel method is called.

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

The recording audio quality:

  • AgoraRtc_AudioRecordingQuality_Low = 0: low quality, and the file size is around 1.2 M after 10 minutes recording
  • AgoraRtc_AudioRecordingQuality_Low = 1: medium quality, and the file size is around 2 M after 10 minutes recording
  • AgoraRtc_AudioRecordingQuality_Low = 2: high quality, and the file size is around 3.75 M after 10 minutes recording
Return Value
  • 0: Method call succeeded
  • <0: Method call failed.

Stop Audio Recording (stopAudioRecording)

- (int)stopAudioRecording;

This method stops recording on the client machine.

Note

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.

Set Recording Audio Format (setRecordingAudioFrameParameters)

Refer to Set Recording Audio Format (setRecordingAudioFrameParameters).

Set Playback Audio Format (setPlaybackAudioFrameParameters)

Refer to Set Playback Audio Format (setPlaybackAudioFrameParameters).

Adjust Recording Signaling Volume (adjustRecordingSignalVolume)

- (int)adjustRecordingSignalVolume:(NSInteger)volume;

This method adjusts the recording signal volume.

Name Description
volume

The recording signal volume ranges from 0~400:

  • 0: Mute
  • 100: Original volume
  • 400: 4 times of the original volume in maximum with signal clipping protection
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Adjust Playback Signal Volume(adjustPlaybackSignalVolume)

- (int)adjustPlaybackSignalVolume:(NSInteger)volume;

This method adjusts the playback Signal Volume.

Name Description
volume

The playback signal volume ranges from 0~400:

  • 0: Mute
  • 100: Original volume
  • 400: 4 times of the original volume in maximum with signal clipping protection
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Encryption

Register Packet Observer (registerAgoraPacketObserver)

int registerAgoraPacketObserver(void* nativeHandle, agora::rtc::IPacketObserver* observer)

This method registers a packet observer. When sending/receiving audio or video network packets, the Agora SDK triggers a callback on the interface defined by IPacketObserver. The application can use this interface to process data, for example, data encryption and decryption. This API can be used directly in objective-c with an .mm file.

Note

Ensure that AgoraRtcEngineKit has been initialized before calling this API. The maximum size of the processed network packet is 1200 bytes; packet larger than the maximum size may not be sent successfully.

Name Description
nativeHandle It can be retrieved by calling the API - (void*)getNativeHandle;
observer Callback interface of the send/receive packet.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Enable Built-in Encryption(setEncryptionSecret)

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

Ensure that your application calls setEncryptionSecret to enable the built-in encryption before joining a channel. Otherwise the communication is unencrypted.

All users in a channel must set the same secret. The secret is automatically cleared once the user has left the channel. If the secret is not specified or set to empty, the encryption function is disabled.

Note

Do not use this function together with CDN, which means if you decide to use CDN for Bypass Live and recording/storage and etc, do not call this method.

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

Set Built-in Encryption Mode(setEncryptionMode)

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

Agora Native SDK supports built-in encryption, and it is in AES-128-XTS mode by default. If you want to use other mode, call this API to set the encryption mode.

All users in the same channel must use the same encryption mode and secret. You can refer to AES encryption algorithm related information on the differences of the several encryption modes.

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

Note

Do not use this function together with CDN, which means if you decide to use CDN for Bypass Live and recording/storage and etc, do not call this method.

Name Description
encryptionMode

Encryption mode. The following modes are supported currently:

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

Establish Data Channel

Create Data Stream(createDataStream)

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

This method creates the data stream. Each person can only have up to 5 data channels at the same time. It allows the maximum latency of 5s in a channel. If the recipient does not receive the sent data within 5s, the data channel will report an error to the application. Currently Agora Native SDK supports 99% reliable and 100% ordered data transmission.

Name Description
streamId Stream ID.
reliable True: The recipients will receive data from the sender within 5s.
ordered True: The recipients will receive data from the sender in order within 5s.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed with error code returned. [5]

Footnotes

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

Send Data Stream(sendStreamMessage)

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

This method sends the created data stream to the recipients. Each channel supports up to 30 packets per second and each packet cannot exceed 1KB. The API controls the rate in data channel: each application supports up to 6KB data per second. Each user can have up to 5 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 and etc.

Test and Detection

Start Audio Call Test (startEchoTest)

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

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

Note

After calling the startEchoTest method, always call stopEchoTest to end the test, otherwise the application will not be able to run the next echo test, nor can it call the joinChannelByKey method to start a new call.

Name Description
successBlock Callback on successfully starting the echo test. See joinSuccessBlock in joinChannelByKey for a description of the callback parameters.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.
  • ERR_REFUSED (-5): Failed to launch the echo test, for example, initialization failed.

Stop Audio Call Test (stopEchoTest)

- (int)stopEchoTest;

This method stops the 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 Network Test (enableLastmileTest)

- (int)enableLastmileTest;

This method enables the network quality test to test the user’s network connection quality. It is disabled by default.

This method is mainly used in two scenarios:

  • Before the users join a channel, they call this method to forecast whether the uplink network quality currently is good enough.
  • Before the audiences in the channel switch the user role to host in, they call this method to test whether the uplink network quality currently is good enough.

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

Be sure to call disableLastmileTest to disable it immediately once the users have received the onLastmileQuality callback before they join the channel or switch the user role.

Note

For the current hosts, do not call this method.

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

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

Feedback

Retrieve Current Call ID (getCallId)

- (NSString*) getCallId;

Every time when a user joins a channel using joinChannelByKey on a client machine, a CallId is generated to identify the call from this client. Some methods such as rate and complain submit feedback to the SDK and are invoked after the call ends. 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*) callId
      rating:(NSInteger) rating
 description:(NSString*) 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

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 Call Quality (complain)

- (int) complain:(NSString*) callId
     description:(NSString*) 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

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.

Others

Renew Channel Key (renewChannelKey)

- (int)renewChannelKey: (NSString*) channelKey;

This method updates the Channel Key. The key expires after a certain period of time once the Channel Key scheme is enabled. When the didOccurError callback reports the error ERR_CHANNEL_KEY_EXPIRED(109), the application should retrieve a new key and then call this method to renew it. Failure to do so results in the SDK disconnecting from the server.

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

Set Log File (setLogFile)

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

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

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

Set Log Filter (setLogFilter)

- (int)setLogFilter:(NSUInteger)filter;

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

Name Description
filter

Filters

  • 1: INFO
  • 2: WARNING
  • 4: ERROR
  • 8: FATAL
  • 0x800: DEBUG
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Destroy Engine Instance (destroy)

+ void destroy();

This method releases all the resources being used by the Agora SDK, and can be useful for applications that perform voice or video communications from time to time according to user needs, but at other times want to maintain resources for other application functions. Once the application has called destroy() to end the RtcEngine instance, no other methods in the SDK can be used and no callbacks occur. To start communications again, initialize with sharedEngineWithappId to establish a new AgoraRtcEngineKit instance.

Note

This method is called synchronously. The result returns after the IRtcEngine Object resources are released. APP should not call this interface in the callback generated by the SDK, otherwise the SDK must wait for the callback to return to recover the associated object resources, resulting in deadlock.

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

Get SDK Version(getSdkVersion)

+ (NSString *)getSdkVersion;

This method returns the string of the SDK version number.

Delegate Methods(AgoraRtcEngineDelegate)

The SDK uses Delegate methods to report runtime events to the application. From version 1.1 on, some Block callbacks in the SDK are replaced with Delegate. The old Block callbacks are therefore being depreciated, 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.

Warning Occurred Callback (didOccurWarning)

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

This callback method indicates that some warning occurred during the runtime of the SDK. In most cases the application can ignore the warnings reported by the SDK because the SDK usually can fix the issue and resume running.

For instance, the SDK may report an AgoraRtc_Error_OpenChannelTimeout(106) warning upon disconnection with the server, and in the meantime the SDK will attempt 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 the runtime of the SDK. 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 failed to initialize a call. In this case, the application informs the user that the call initialization failed and in the same time it also calls the leaveChannel method to exit the channel.

Name Description
Engine The AgoraRtcEngineKit Object.
errorCode Error code.

Join Channel Callback (didJoinChannel)

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

Same as joinSuccessBlock in the joinChannelByKey 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 joinChannelByKey method, returns the specified ID; if not, returns an ID that is automatically allocated by the Agora server.

elapsed Time elapsed in milliseconds from calling joinChannelByKey until this event occurs.

Rejoin Channel Callback (didRejoinChannel)

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

If the client machine 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 in milliseconds from calling joinChannelByKey until this event occurs.

Audio Volume Indication Callback (reportAudioVolumeIndicationOfSpeakers)

- (void)rtcEngine:(AgoraRtcEngineKit *)engine reportAudioVolumeIndicationOfSpeakers:
(NSArray*)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 (that is, the user who is speaking).
  • volume: The 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 (firstLocalVideoFrameWithSize)

- (void)rtcEngine:(AgoraRtcEngineKit *)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
size Size of the video (width and height ).
elapsed Time elapsed in milliseconds from calling joinChannelByKey until this callback is triggered.

First Remote Video Frame Received and Decoded Callback (firstRemoteVideoDecodedOfUid)

- (void)rtcEngine:(AgoraRtcEngineKit *)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
uid User ID of the user whose video stream is received.
size Size of the video (width and height).
elapsed Time elapsed in milliseconds from calling joinChannelByKey until this callback is triggered.

First Remote Video Frame Displayed Callback (firstRemoteVideoFrameOfUid)

- (void)rtcEngine:(AgoraRtcEngineKit *)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 in milliseconds from calling joinChannelByKey until this callback is triggered.

Other User Joined Callback (didJoinedOfUid)

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

Same as userJoinedBlock.This callback indicates that a user has successfully joined the channel. If there are other users in the channel when this user joins, the SDK also reports to the application on the existing users who are already in the channel.

Note

In the Live Broadcast scenario, only the hosts will receive this callback while audiences won’t.

Name Description
uid

User ID.

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

elapsed Time elapsed in milliseconds from calling joinChannelByKey until this callback is triggered.

Other User Offline Callback (didOfflineOfUid)

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

Same as 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) or not. If no data package is received from the user in 15 seconds, the SDK takes it as the user being offline. Sometimes a weak network connection may lead to false detection, therefore we recommend using signaling for reliable offline detection.

Name Description
uid User ID.
reason

Reasons for user going offline:

  • AgoraRtc_UserOffline_Quit: User has quit the call.
  • AgoraRtc_UserOffline_Dropped: The SDK is timed out and has dropped offline because it has not received a data package within a certain period. Note: Sometimes if a user quits the call and the message is not passed to the SDK (due to an unreliable channel), the SDK treat the event as a timeout.
  • AgoraRtc_UserOffline_BecomeAudience: It is triggered when the host is switched to the audience role.

Other User Muted Audio Callback (didAudioMuted)

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

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

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

Other User Paused/Resumed Video Callback (didVideoMuted)

- (void)rtcEngine:(AgoraRtcEngineKit *)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 *)engine
didVideoEnabled:(BOOL)enabled byUid:(NSUInteger)uid;

This callback indicates that other users enabled/disabled the video function. Once the video function is disabled, users can only perform audio call. They cannot see any video from both themselves and other users.

Name Description
uid User ID
enabled
  • Yes: User has enabled the video function.
  • No: User has disabled the video function.

Local Video Statistics Callback (localVideoStats)

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

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

Name Description
engine The engine kit.
stats

The statistics of the local video, including:

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

Remote Video Statistics Callback (remoteVideoStatOfUid)

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

Same as remoteVideoStatBlock.The SDK updates the application on the statistics about receiving remote video streams once every 2 seconds.

Name Description
engine The engine kit.
stats

The statistics of the remote video, including:

  • uid: User ID of the user whose video streams are received.
  • delay: Time delay (in milliseconds).
  • width: Width (in pixels) of the video stream.
  • height: Height (in pixels) of the video stream.
  • receivedBitrate: Data receive bitrate (in kbps) since last count.
  • receivedFrameRate: Data receive frame rate (in fps) since last count.

Camera Ready Callback (rtcEngineCameraDidReady)

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

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

Video Stopped Callback (rtcEngineVideoDidStop)

- (void)rtcEngineVideoDidStop:(AgoraRtcEngineKit *)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 on the view) after the video stops.

Connection Interrupted Callback (rtcEngineConnectionDidInterrupted)

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

This callback indicates that connection is lost between the SDK and server. Once the connection is lost, the SDK tries to reconnect it repeatedly until the application calls leaveChannel.

Connection Lost Callback (rtcEngineConnectionDidLost)

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

When the connection between the SDK and server is lost, the rtcEngineConnectionDidInterrupted callback is triggered and the SDK reconnects automatically. If the reconnection fails within a certain period (10s by default, the callback rtcEngineConnectionDidLost is triggered. The SDK continues to try reconnecting until the application calls leaveChannel.

Rtc Engine Statistics Callback (reportRtcStats)

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

Same as rtcStatsBlock. The SDK updates the application on the statistics of the Rtc Engine runtime status once every 2 seconds.

Name Description
stat See the table below.
AgoraRtcStats Description
duration Call duration in seconds, represented by an aggregate value.
txBytes The total number of bytes transmitted, represented by an aggregate value.
rxBytes The total number of bytes received, represented by an aggregate value.

Audio Quality Callback (audioQualityOfUid)

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

Same as audioQualityBlock. During a call, this callback is triggered once every 2 seconds to report on the audio quality of the current call.

Name Description
audioQualityBlock
uid

User ID.

Each callback reports on the audio quality of one user only (excluding the user himself). Every different user’s statistics is reported in a separate callback.

quality

Rating of the audio 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)
delay Time delay in milliseconds.
lost Packet loss rate (in percentage).

Network Quality Callback (lastmileQuality)

- (void)rtcEngine:(AgoraRtcEngineKit *)engine
lastmileQuality:(AgoraRtcQuality)quality;

Same as lastmileQualityBlock. This callback is triggered once every 2 seconds during a call to report the network quality of the local user.

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

In-Call Network Quality Callback(networkQuality)

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

This callback is triggered regularly to update the application on the current network quality in a communication or live broadcast channel.

Name Description
uid User ID. It indicates the specific callback reports the network quality of the user with this UID.
If uid is 0, it reports the local network quality. The current release only reports the quality for the local user.
txQuality

The uplink network quality of the user:

  • QUALITY_UNKNOWN(0)
  • QUALITY_EXCELLENT(1)
  • QUALITY_GOOD(2)
  • QUALITY_POOR(3)
  • QUALITY_BAD(4)
  • QUALITY_VBAD(5)
  • QUALITY_DOWN(6)
rxQuality

The downlink network quality of the user:

  • QUALITY_UNKNOWN(0)
  • QUALITY_EXCELLENT(1)
  • QUALITY_GOOD(2)
  • QUALITY_POOR(3)
  • QUALITY_BAD(4)
  • QUALITY_VBAD(5)
  • QUALITY_DOWN(6)

Video Stream Type Switched (didApiCallExecute)

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

This callback indicates whether the video stream type is switched or not.

Method API String Parameter Status Code
StartRemoteVideoStream rtc.video.set_remote_video_stream See Error and Warning Messages

Channel Key Expired Callback(rtcEngineRequestChannelKey)

- (void)rtcEngineRequestChannelKey:(AgoraRtcEngineKit *)engine;

If a Channel Key is specified when calling joinChannelByKey, and due to Channel Key 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 Channel Key to reconnect to the server.

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

This function was previously provided in the callback report of didOccurError(): ERR_CHANNEL_KEY_EXPIRED(109)、ERR_INVALID_CHANNEL_KEY(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(rtcEngineMediaEngineDidAudioMixingFinish)

- (void)rtcEngineMediaEngineDidAudioMixingFinish:(AgoraRtcEngineKit *)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.

Block Callbacks

The SDK supports Block to report runtime events to the application. However, see the previous section on delegate methods. From version 1.1 on, some Block callbacks in the SDK are replaced with Delegate. The old Block callbacks are therefore being depreciated, 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. 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 indicates that a user has successfully joined the channel. If there are other users in the channel when this user joins, the SDK also reports to the application on the existing users who are already in the channel.

Note

In the Live Broadcast scenario, only the hosts will receive this callback while audiences won’t.

Name Description
uid User ID.
If the uid is specified in the joinChannelByKey method, returns the specified ID; if not, returns an ID that is automatically allocated by the Agora server.
elapsed Time elapsed in milliseconds from calling joinChannelByKey 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 went offline) or not. If no data package is received from the user in 15 seconds, the SDK takes it as the user being offline. Sometimes a weak network connection may lead to false detection, 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;

In times 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 allocated channel ID and a user ID.

Name Description
channel Channel name.
uid User ID.
elapsed Time delay (in milliseconds) 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 in seconds, represented by an aggregate value.
txBytes The total number of bytes transmitted, represented by an aggregate value.
rxBytes The total number of bytes received, represented by an aggregate value.

Rtc Engine Statistics Callback (rtcStatsBlock)

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

This callback is triggered once every 2 seconds to update the application on Rtc Engine runtime statistics.

Name Description
stat See the table below.
AgoraRtcStats Description
duration Call duration in seconds, represented by an aggregate value.
txBytes The total number of bytes transmitted, represented by an aggregate value.
rxBytes The 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 speaking 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 (that is, the user who is speaking).
  • volume: The 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 (in pixels) of the video stream.
height Height (in pixels) of the video stream.
elapsed Time elapsed in milliseconds 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 (in pixels) of the video stream.
height Height (in pixels) of the video stream.
elapsed Time elapsed in milliseconds 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 (in pixels) of the video stream.
height Height (in pixels) of the video stream.
elapsed Time elapsed in milliseconds 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 on uploading local video streams once every 2 seconds.

Name Description
sentBytes The total bytes sent since last count.
sentFrames The 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 on receiving remote video streams once every 2 seconds.

Name Description
uid User ID that specifies whose video streams are received.
frameCount The total frames received since last count.
delay Time delay in milliseconds.
receivedBytes The total bytes received since last count.

Camera Ready Callback (cameraReadyBlock)

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

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

Audio Quality Callback (audioQualityBlock)

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

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

Name Description
audioQualityBlock
uid User ID.
Each callback reports on the audio quality of one user only (excluding the user himself). Every different user’s statistics is reported in a separate callback.
quality

Rating of the audio quality:

  • AgoraRtc_Quality_Excellent(1)
  • AgoraRtc_Quality_Good(2)
  • AgoraRtc_Quality_Poor(3)
  • AgoraRtc_Quality_Bad(4)
  • AgoraRtc_Quality_VBad(5)
  • AgoraRtc_Quality_Down(6)
delay Time delay in milliseconds.
lost Packet loss rate (in percentage).

Network Quality Callback (lastmileQualityBlock)

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

This callback s triggered once every 2 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.

Data Stream Received Callback(receiveStreamMessageFromUid)

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

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

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

Data Stream Sent Failure Callback(didOccurStreamMessageErrorFromUid)

- (void)rtcEngine:(AgoraRtcEngineKit *)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 5 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_SIZE_TOO_LARGE=114, data size is too big
  • ERR_BITRATE_LIMIT=115, limited bitrate
  • ERR_TOO_MANY_DATA_STREAMS =116, too many data streams
  • ERR_STREAM_MESSAGE_TIMEOUT=117, data stream timed out

For more error code description, see Error and Warning Messages.

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