This page provides the C++ Interface, with which you can integrate the voice and video function into your app on Android and iOS.

Basic Methods (IRtcEngine)

agora::IRtcEngine is the basic interface class of the 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 previous versions, this class was named IAgoraAudio and is renamed to agora::IRtcEngine from v1.0.

Creates 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 methods in the same thread. Unless otherwise specified, the following rule applies to all API methods whose return values are integer types:

  • A return value of 0 means that the method call is successful
  • A return value of less than 0 means that the method call fails.
Name Description
Return Value An agora::IRtcEngine object.

Initializes the Agora SDK Service (initialize)

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

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

The definition of RTCEngineContext is:

struct RtcEngineContext
{
    IRtcEngineEventHandler* eventHandler;
    /** App ID issued to you 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 you by Agora. Apply for a new one from Agora if it is missing from your kit. See Getting an App ID on 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 app on SDK runtime events (callbacks).
Return Value
  • 0: Success.
  • < 0: Failure:
    • ERR_INVALID_VENDOR_KEY(-101): The entered App ID is invalid.

Implements a Live Voice Broadcast

Sets a Channel Profile (setChannelProfile)

virtual int setChannelProfile(CHANNEL_PROFILE_TYPE profile) = 0;

This method configures the channel profile. 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 the setClientRole method. The host sends and receives voice, while the audience receives voice only with the sending function disabled.
Gaming Gaming Mode. Any user in the channel can talk freely. This mode uses the codec with low-power consumption and low bitrate by default.
  • Only one profile can be used at the same time in the same channel. If you want to switch to another profile, use release to destroy the current IRtcEngine and create a new one using create and initialize before calling this method to set the new channel profile.
  • Ensure that different App IDs are used for different channel profiles.
  • This method must be called and configured before a user joins a channel because the channel profile cannot be configured when the channel is in use.
Name Description
profile

The channel profile. Choose one of the following:

  • CHANNEL_PROFILE_COMMUNICATION = 0: (Default) Communication
  • CHANNEL_PROFILE_LIVE_BROADCASTING = 1: Live Broadcast
  • CHANNEL_PROFILE_GAME = 2: Gaming
Return Value
  • 0: Success
  • < 0: Failure

Sets the User Role (setClientRole)

virtual int setClientRole(CLIENT_ROLE_TYPE role) = 0;

In the live-broadcast profile, this method allows you to:

  • Set the user role as a host or an audience (default) before joining a channel.
  • Switch the user role after joining a channel.
Name Description
role

The user role in a live broadcast:

  • CLIENT_ROLE_BROADCASTER = 1: Host
  • CLIENT_ROLE_AUDIENCE = 2: (Default) Audience
Return Value
  • 0: Success.
  • < 0: Failure.

Enables Audio Mode (enableAudio)

virtual int enableAudio() = 0;

This method enables audio mode. Audio mode is enabled by default.

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

This method sets to enable the internal engine, and still works after you call the leaveChannel method.

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

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

Disables Audio Mode (disableAudio)

virtual int disableAudio() = 0;

This method disables audio mode.

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

This method sets to disable the internal engine, and still works after you call the leaveChannel method.

Allows a User to 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 joining 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 you. You can then generate a user key using the algorithm and App Certificate provided by Agora for user authentication on the server.

In most cases, the static App ID suffices. For added security, use 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: a to z
  • The 26 uppercase English letters: A to Z
  • The 10 numbers: 0 to 9
  • Space
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","

info (Optional) Additional information about the channel that you add. [1] It can be set as a NULL String or channel related information. Other users in the channel do 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: Success.
  • < 0: Failure:
    • ERR_INVALID_ARGUMENT (-2): The passed argument is invalid.
    • ERR_NOT_READY (-3): Initialization fails.

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

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

If you call release() immediately after you call leaveChannel, the SDK interrupts the leaveChannel process, and does not trigger the onLeaveChannel callback.

Name Description
Return Value
  • 0: Success.
  • < 0: Failure:
    • ERR_REFUSED (-5): Fails to leave the channel. Reasons being that the user is not currently in a call or is in the process of leaving the channel.

Sets the Local Voice Pitch (setLocalVoicePitch)

int setLocalVoicePitch(double pitch);

This method changes the voice pitch of the local speaker.

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

Sets the 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 method is valid only for earphones and is invalid when the speakerphone is enabled.

Name Description
uid

User ID of the remote user

pan

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

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

Sets whether to change the volume of a single audio effect. The value ranges between 0.0 and 100.0. The default value is 100.0. The smaller the 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 (transmits the audio stream only) and other streams are ignored, for example, the sound of the keyboard strokes.

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

Sets 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. The value ranges between 0 and 9, representing the respective 10-band center frequencies of the voice effects, including 31, 62, 125, 500, 1k, 2k, 4k, 8k, and 16k Hz.
bandGain Gain of each band (dB). The value ranges between -15 and 15.
Return Value
  • 0: Success.
  • < 0: Failure.

Sets the Local Voice Reverberation (setLocalVoiceReverb)

int setLocalVoiceReverb(AUDIO_REVERB_TYPE reverbKey, int value)

This method sets the 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: Success.
  • < 0: Failure.

Manages the Audio Effects

Gets the Audio Effect Volume (getEffectsVolume)

int getEffectsVolume();

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

Sets the Audio Effect Volume (setEffectsVolume)

int setEffectsVolume(int volume);

This method sets the volume of the audio effects. The value ranges between 0.0 and 100.0.

Name Description
volume The value ranges from 0.0 to 100.0 (default).
Return Value
  • 0: Success.
  • < 0: Failure.

Adjusts 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 (default).
Return Value
  • 0: Success.
  • < 0: Failure.

Plays 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: Plays the audio effect once.
  • 1: Plays the audio effect twice.
  • -1: Plays the audio effect in a loop indefinitely, until you call the stopEffect or stopAllEffects method.
pitch Sets whether to change the pitch of the audio effect. The value ranges between 0.5 and 2. The default value is 1, which means no change to the pitch. The smaller the value, the lower the pitch.
pan

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

  • 0.0: The audio effect shows ahead.
  • 1.0: The audio effect shows on the right.
  • -1.0: The audio effect shows on the left.
gain Volume of the audio effect. The 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

Sets whether or not to publish the specified audio effect to the remote stream:

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

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

Stops 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: Success.
  • < 0: Failure.

Stop Playing all Audio Effects (stopAllEffects)

int stopAllEffects();

This method stops playing all 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 the joinChannel method.

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

Releases an Audio Effect (unloadEffect)

int unloadEffect(int soundId);

This method releases 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: Success.
  • < 0: Failure.

Pauses 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: Success.
  • < 0: Failure.

Pause all Audio Effects (pauseAllEffects)

int pauseAllEffects();

This method pauses all audio effects.

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

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: Success.
  • < 0: Failure.

Resume Playing all Audio Effects (resumeAllEffects)

int resumeAllEffects();

This method resumes playing all audio effects.

Implements a Video Live Broadcast

Enables the Video Mode (enableVideo)

virtual int enableVideo() = 0;

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

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

This method sets to enable the internal engine, and still works after you call the leaveChannel method.

Disables the Video Mode (disableVideo)

virtual int disableVideo() = 0;

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

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

This method sets to disable the internal engine, and still works after you call the leaveChannel method.

Enables the Local Video (enableLocalVideo)

int enableLocalVideo(bool enabled);

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

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

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

Name Description
enabled

Sets to enable the local video:

  • true: (Default) Enable the local video.
  • false: Disable the local video. Once the local video is disabled, 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 you set enabled as false, this method does not require a local camera.
Return value
  • 0: Success.
  • < 0: Failure.

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

Sets the Video Profile (setVideoProfile)

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 automatically chooses a suitable camera resolution, while the encoder resolution is still the one specified by this method.

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

Name Description
profile The video profile. See the following table for details.
swapWidthAndHeight

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

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

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

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

Video profile definition

Video Profile Enumeration Resolution (Width x Height) Frame Rate(fps) Bitrate
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 15 1130
720P_3 52 1280x720 30 1710
720P_5 54 960x720 15 910
720P_6 55 960x720 30 1380
1080P 60 1920x1080 15 2080
1080P_3 62 1920x1080 30 3150
1080P_5 64 1920x1080 60 4780

Whether 720p or above 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.

Sets the Local Video View (setupLocalVideo)

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

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

This method binds the local user to the video window (view) of the local video stream and configures the video display settings. Call this method after initialization to configure the local video display settings before joining a channel. After leaving the channel, the bind is still valid, which means the window still displays. To unbind the window, set view as NULL when calling the setupLocalVideo method.

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 are filled with black.
  • Return value: The local user ID as set in the joinChannel method.
Return Value
  • 0: Success.
  • < 0: Failure.
struct VideoCanvas {
view_t view;
int renderMode;
uid_t uid;
};

Sets 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 app should specify the uid of the remote user sending the video in this method before the remote user joins a channel.

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

Name Description
canvas

Video display settings. VideoCanvas class:

  • 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 are filled with black.
Return Value
  • 0: Success.
  • < 0: Failure.
struct VideoCanvas {
view_t view;
int renderMode;
uid_t uid;
};

Enables Dual-stream Mode (enableDualStreamMode)

int enableDualStreamMode(boolean enabled);

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

Name Description
enabled

The video mode is in single stream or dual stream:

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

Sets the Remote Video-stream Type (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 the enableDualStreamMode method, you receive the high-video stream by default. This method allows the app to adjust the corresponding video-stream type according to the size of the video windows to save the bandwidth and resources.

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

The onApiCallExecuted callback returns the results of this method call. The Agora SDK receives the high-stream video by default to save the bandwidth. If needed, users can switch to the low-stream video using this method.

Name Description
uid User ID
streamType

Set the video-stream size.

The following lists the video-stream types:

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

Sets the Default Remote Video Stream Type (setRemoteDefaultVideoStreamType)

int setRemoteDefaultVideoStreamType(REMOTE_VIDEO_STREAM_TYPE streamType);

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

Name Description
streamType

The default remote video stream:

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

Sets the High-quality Video Preferences (setVideoQualityParameters)

int setVideoQualityParameters(bool preferFrameRateOverImageQuality);

This method allows users to set the video preferences.

Name Description
preferFrameRateOverImageQuality

The video preference to be set:

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

Starts a Video Preview (startPreview)

virtual int startPreview() = 0;

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

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

Once you call this method to start the local video preview, if you call the stopPreview method before leaving a channel, call the setRemoteVideo method the next time you join a channel, or you will not see the remote video view.

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

Stops the Video Preview (stopPreview)

virtual int stopPreview() = 0;

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

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

Sets the Local Video Display Mode (setLocalRenderMode)

int setLocalRenderMode(RENDER_MODE_TYPE renderMode);

This method configures the local video display mode. You 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 are filled with black.
Return Value
  • 0: Success.
  • < 0: Failure.

Sets the Remote Video Display Mode (setRemoteRenderMode)

int setRemoteRenderMode(uid_t uid, RENDER_MODE_TYPE renderMode);

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

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

Configures the video display mode:

  • 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 are filled with black.
Return Value
  • 0: Success.
  • < 0: Failure.

Sets 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 calling the startPreview method, or this method does not take effect until you call the startPreview method again.

Name Description
mode

Sets the local video mirror mode:

  • VIDEO_MIRROR_MODE_AUTO = 0: The default mirror mode, that is, the mode is 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: Success.
  • < 0: Failure.

Enables Agora Web SDK Interoperability (enableWebSdkInteroperability)

int enableWebSdkInteroperability(bool enabled);

This method enables interoperability with the Agora Web SDK.

Name Description
enabled

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

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

Set the Audio Route

Set the Default Audio Route (setDefaultAudioRouteToSpeakerphone)

int setDefaultAudioRouteToSpeakerphone(bool defaultToSpeaker) = 0;

This method modifies the default audio route if necessary.

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

The default audio routes are listed in the following table:

Channel Mode Default Audio Route
Communication

Voice Communication: Earpiece

Video Communication: Speakerphone

If the user in a communication channel has called disableVideo or if the user has called muteLocalVideoStream and muteAllRemoteVideoStreams, the audio route is switched back to the earpiece automatically.

Live Broadcast Speakerphone
Game Voice Speakerphone

Modify the default audio route if necessary according to the following table:

Name Description
defaultToSpeaker
  • True: Speakerphone.
  • False: Earpiece.

Whether the audio is routed to the speakerphone or earpiece, once a headset is plugged in or Bluetooth is connected,

the audio route will be changed. The audio route will be switched to default once removing the headset or disconnecting Bluetooth.

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

Enable the Speakerphone (setEnableSpeakerphone)

int setEnableSpeakerphone(bool speakerOn) = 0;

This method enables the audio routing to the speakerphone.

After calling this method, the SDK will return the onAudioRouteChanged callback to indicate the changes.

Read the default audio route explanation according to setDefaultAudioRouteToSpeakerphone and check whether it is necessary to call this method.

Name Description
enabled
  • True:
    • If this API is called after joining a channel, whether the audio was routed to the headset, Bluetooth device, or earpiece, it will be routed to the speaker.
    • If this API is called before joining a channel, when joining a channel, the audio will be routed to the speaker whether the user uses a headset or Bluetooth device.
  • False: The audio will follow the default audio route mentioned in Set the Default Audio Route (setDefaultAudioRouteToSpeakerphone).
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Encryption

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

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

This method specifies an encryption password to enable built-in encryption before joining a channel. All users in a channel must set the same encryption password. The encryption password is automatically cleared once a user leaves the channel. If the encryption password is not specified or set to empty, the encryption function is disabled.

Do not use this function in CDN live.

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

Sets the Built-in Encryption Mode (setEncryptionMode)

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

The Agora Native SDK supports built-in encryption, which is in AES-128-XTS mode by default. Call this method to set other encryption modes.

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 the setEncryptionSecret method to enable the built-in encryption before calling this method.

Do not use this function in CDN live.

Name Description
encryptionMode

Encryption mode. The following modes are supported:

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

Establishes a Data Stream

Creates a Data Stream (createDataStream)

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

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

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

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

Sends 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 Sent data.
Return Value

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

ERR_SIZE_TOO_LARGE/ERR_TOO_OFTEN/ERR_BITRATE_LIMIT

Test and Detection

Starts an Audio Call Test (startEchoTest)

virtual int startEchoTest() = 0;

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

  • After calling this method, call the stopEchoTest method to end the test; otherwise, the app cannot run the next echo test, nor can it call the joinChannel method to start a new call.
  • This method is applicable only when the user role is broadcaster. If you switch the channel profile from Communication to Live Broadcast, ensure that you call the setClientRole method to change the user role from audience (default in the live broadcast profile) to broadcaster before using this method.
Name Description
Return Value
  • 0: Success.
  • < 0: Failure:
    • ERR_REFUSED (-5): Fails to launch the echo test. For example, initialization fails.

Stops an Audio Call Test (stopEchoTest)

virtual int stopEchoTest() = 0;

This method stops an audio call test.

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

Enables the Network Test (enableLastmileTest)

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, you can call this method to check the uplink network quality.
  • Before the audience in a channel switches to a host role, you can call this method to check the uplink network quality.

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

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

For current hosts, do not call this method.

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

Disables the Network Test (disableLastmileTest)

virtual int disableLastmileTest() = 0;

This method disables the network connection quality test.

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

Feedback

Retrieves the Current Call ID (getCallId)

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

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

Name Description
callId The current call ID.
Return Value
  • 0: Success.
  • < 0: Failure.

Rates the Call (rate)

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

This method allows a user to rate a call after a call ends.

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

(Optional) A given description for the call with a length less of than 800 bytes.

Return Value
  • 0: Success.
  • < 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 fails.

Complains about the Call Quality (complain)

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

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

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

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

Return Value
  • 0: Success.
  • < 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 fails.

Added Functions

Renews the Token (renewtoken)

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

This method updates the token.

The token expires after a time period 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 app should retrieve a new token and then call this method to renew it. Failure to do so results in the SDK disconnecting with the server.

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

Specifies a Log File (setLogFile)

int setLogFile(const char* filePath);

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

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

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

Sets the Log Filter (setLogFilter)

int setLogFilter(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 to see the logs that precede that level.

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

Name Description
filter

Sets the levels of the filters:

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

Releases 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 releases all resources on its own. Do not immediately uninstall the SDK’s dynamic library after a call, otherwise, it may crash because the SDK clean-up thread has not quit.
Return Value
  • 0: Success.
  • < 0: Failure.

Gets 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 the parameters for the SDK. The following section describes each of the methods in this class.

Mutes the Local Audio Stream (muteLocalAudioStream)

int muteLocalAudioStream(bool mute);

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

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

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

Mutes All Remote Audio Streams (muteAllRemoteAudioStreams)

int muteAllRemoteAudioStreams(bool mute);

This method enables/disables playing all remote audio streams.

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

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

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

int muteRemoteAudioStream(uid_t uid, bool mute);

This method mutes/unmutes the audio stream of a specified remote user and enables/disables playing the user's audio streams.

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

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

Mutes the Local Video Stream (muteLocalVideoStream)

int muteLocalVideoStream (bool mute);

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

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

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

Mutes All Remote Video Streams (muteAllRemoteVideoStreams)

int muteAllRemoteVideoStreams(bool mute);

This method enables/disables playing all remote video streams.

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

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

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

int muteRemoteVideoStream(uid_t uid, bool mute);

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

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

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

Sets the Audio Volume

Reports on Which Users are Speaking and the Speakers' Volume. (enableAudioVolumeIndication)

int enableAudioVolumeIndication(int interval, int smooth);

This method enables the SDK to regularly report to the app on which users are speaking and the volume of the speakers. Once this method is enabled, the SDK returns the volume indications at the set time interval returned 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 (ms) between two consecutive volume indications. Agora recommends setting it to more than 200 ms. Do not set it lower than 10 ms, or the SDK does not trigger the onAudioVolumeIndication callback.
smooth Smoothing factor. The default value is 3.
Return values
  • 0: Success.
  • < 0: Failure.

Audio Mixing

Starts 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 method also supports online music playback.

Call this method when you are in a channel, otherwise, it may cause issues.

Name Description
filePath

Name and path of the local audio file to be mixed.

Supported audio formats: mp3, aac, m4a, 3gp, and wav.

loopback
  • True: Only the local user can hear the remix or the replaced audio stream.
  • False: Both users can hear the remix or the replaced audio stream.
replace
  • True: The content of the local audio file replaces the audio stream from the microphone.
  • False: Mix the local audio file with the audio stream from the microphone.
cycle

Number of loop playbacks:

  • Positive integer: Number of loop playbacks.
  • -1: Infinite loop.
Return Value
  • 0: Success.
  • < 0: Failure.

Stops Audio Mixing (stopAudioMixing)

int stopAudioMixing();

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

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

Pauses Audio Mixing (pauseAudioMixing)

int pauseAudioMixing();

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

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

Resumes Audio Mixing (resumeAudioMixing)

int resumeAudioMixing();

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

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

Adjusts the Audio Mixing Volume (adjustAudioMixingVolume)

int adjustAudioMixingVolume(int volume);

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

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

Gets the Audio Mixing Duration (getAudioMixingDuration)

int getAudioMixingDuration();

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

Gets the Audio Playback Position (getAudioMixingCurrentPosition)

int getAudioMixingCurrentPosition();

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

Sets the Audio Playback Position (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 playback position of the audio mixing file (ms).

Recording

Starts 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 one of the following formats:

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

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

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

Stops an Audio Recording (stopAudioRecording)

int stopAudioRecording();

This method stops recording on the client.

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

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

Adjusts the Recording Volume (adjustRecordingSignalVolume)

int adjustRecordingSignalVolume(int volume);

This method adjusts the recording volume.

Name Description
volume

The recording volume. The value ranges between 0 and 400:

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

Adjusts the Playback Volume (adjustPlaybackSignalVolume)

int adjustPlaybackSignalVolume(int volume);

This method adjusts the playback volume.

Name Description
volume

The playback volume. The value ranges between 0 and 400:

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

Callbacks (IRtcEngineEventHandler)

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

The callbakcs are returned in the main thread.

Occurs when a User Joins a Channel (onJoinChannelSuccess)

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

This callback reports that a user has successfully joined a 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 the joinChannel method until the SDK triggers this callback.

Occurs when a User Rejoins a Channel (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 upon reconnection.

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

Reports a Warning during SDK Runtime (onWarning)

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

This callback reports a warning during SDK runtime. In most cases, the app 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.

l
Name Description
warnThe warning code.
msg The warning message.

Reports an Error During SDK Runtime (onError)

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

This callback reports an error during SDK runtime. In most cases, reporting an error means that the SDK cannot fix the issue and resume running, and therefore requires actions from the app or simply informs the user on the issue. For instance, the SDK reports an ERR_START_CALL error when failing to initialize a call. In this case, the app informs the user that the call initialization fails 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): Fails to look up the channel, because the server rejects the request.
  • ERR_OPEN_CHANNEL_REJECTED(107): Fails to join the channel, because the media server rejects the request.
  • ERR_LOAD_MEDIA_ENGINE(1001): Fails to load the media engine.
  • ERR_START_CALL(1002): Fails to turn on the local audio or video devices and thus fails to start a call.
  • ERR_START_CAMERA(1003): Fails to turn on the local camera.
msg The error message.

Occurs When an API Method Executes (onApiCallExecuted)

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

The SDK triggers this callback when an API method executes.

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

Occurs when the State of the Microphone Changes (onMicrophoneEnabled)

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

Reports the Audio Quality of the Current Call (onAudioQuality)

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

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

Name Description
uid User ID of the speaker
quality

Rating of the audio quality:

  • 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 (ms).
lost The packet loss rate (%).

Reports Which Users are Speaking and the Speakers' Volume (onAudioVolumeIndication)

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

This callback reports which users are speaking and the speakers' volume. By default, this callback is disabled. You can use the enableAudioVolumeIndication method to enable/disable this callback.

Name Description
speakers

The speakers (array). Each speaker ():

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

In the returned speakers array:

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

Occurs when a User Leaves a Channel (onLeaveChannel)

virtual void onLeaveChannel(const RtcStats& stat);

When the app calls the leaveChannel method, the SDK uses this callback to notify the app that a user successfully leaves a channel. With this callback, the app retrieves information, such as the call duration and the statistics of the 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 of the call:

  • duration: Call duration (s), represented by an aggregate value.
  • txBytes: Total number of bytes transmitted, represented by an aggregate value.
  • rxBytes: Total number of bytes received, represented by an aggregate value.
  • txKBitRate: Transmission bitrate (Kbps), represented by an instantaneous value.
  • rxKBitRate: Receiving bitrate (Kbps), represented by an instantaneous value.
  • txAudioKBitrate: Audio transmission bitrate (Kbps), represented by an instantaneous value.
  • rxAudioKBitRate: Audio receiving bitrate (Kbps), represented by an instantaneous value.
  • txVideoKBitRate: Video transmission bitrate (Kbps), represented by an instantaneous value.
  • rxVideoKBitRate: Video receiving bitrate (Kbps), represented by an instantaneous value.
  • users: The number of users in the channel when the user leaves the channel.
  • puTotalUsage: System CPU usage (%).
  • cpuAppUsage: Application CPU usage (%).

Occurs when a Host Joins a Channel (onUserJoined)

virtual void onUserJoined(uid_t uid, int elapsed);

This callback notifies the app when a host joins a channel. If the host is already in the channel when the app joins the channel, the SDK also reports to the app on the hosts who are already in the channel.

In the Live-broadcast profile:

  • The host receives the callback when another host joins the channel.
  • All the audience members in the channel can receive the callback when the new host joins the channel.
  • When a Web app joins the channel, the SDK triggers this callback as long as the Web app publishes streams.
Name Description
uid User ID.
elapsed Time delay (ms) from calling the joinChannel method until the SDK triggers this callback.

Occurs when a Host Leaves a Channel or Goes Offline (onUserOffline)

virtual void onUserOffline(uid_t uid, USER_OFFLINE_REASON_TYPE reason);

This callback notifies the app that a host leaves a channel or goes offline.

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

Name Description
uid User ID.
reason

The SDK triggers this callback when:

  • USER_OFFLINE_QUIT(0): A user has quit the call.
  • USER_OFFLINE_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.

Occurs when the Video Frame Size Changes (onVideoSizeChanged)

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

This callback reports when the size of a video frame changes.

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 (default), 90, 180, or 270.

Occurs when a Video Display Window is Destroyed (onViewDestroyed)

virtual void onViewDestroyed() = 0;

The SDK triggers this callback when a video display window is destroyed.

Reports the Statistics of the Current Call Session (onRtcStats)

virtual void onRtcStats(const RtcStats& stats);

The SDK reports to the app on the statistics of the call session once every two seconds.

Name Description
stat See the descriptions in the leaveChannel callback (onLeaveChannel) .

Reports the Statistics of the Uploading Local Video Streams (onLocalVideoStats)

virtual void onLocalVideoStats(const LocalVideoStats& stats);

The SDK reports to the app on the statistics of the uploading local video streams once every two seconds. Here is the definition of LocalVideoStats

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

The statistics of the local video, including the:

  • sentBitrate: Transmission bitrate (Kbps) since last count.
  • sentFrameRate: Transmission frame rate (fps) since last count.

Reports the Statistics of the Receiving Remote Video Streams Sent from each Host (onRemoteVideoStats)

virtual void onRemoteVideoStats(const RemoteVideoStats& stats);

The SDK reports to the app on the statistics of the receiving remote video streams sent for each host once every two seconds. If there are multiple remote hosts, the SDK triggers this callback as many times.

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

  • uid: User ID of the remote user sending the video stream.
  • delay: Time delay (ms).
  • width: Width (pixels) of the video stream.
  • height: Height (pixels) of the video stream.
  • receivedBitrate: The data receive bitrate (Kbps) since the last count.
  • receivedFrameRate: The data receive frame rate (fps) since the last count.
  • rxStreamType: The stream type. High-stream or low-stream video.

Occurs when the Engine Sends the First Local Audio Frame (onFirstLocalAudioFrame)

virtual void onFirstLocalAudioFrame(int elapsed);

The SDK triggers this callback when the engine sends the first local audio frame.

Name Description
elapsed Time elapsed (ms) from calling the joinChannel method until the SDK triggers this callback.

Occurs when the Engine Receives the First Audio Frame From a Specific Remote User (onFirstRemoteAudioFrame)

virtual void onFirstRemoteAudioFrame(uid_t uid, int elapsed)

The SDK triggers this callback when the engine receives the first remote audio frame.

Name Description
uid The UID of the remote user sending the audio frame.
elapsed Time elapsed (ms) from calling the joinChannel method until the SDK triggers this callback.

Occurs when the Engine Renders the First Local Video Frame on the Video Window (onFirstLocalVideoFrame)

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

The SDK triggers this callback when the engine renders the first local video frame 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 the joinChannel method until the SDK triggers this callback.

Occurs when the Engine Decodes the First Video Frame from the Specified Remote User (onFirstRemoteVideoDecoded)

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

The SDK triggers this callback when the engine receives and decodes the first video frame from the specified remote user. The app can configure the user view settings in this callback.

Name Description
uid User ID of the remote user sending the video stream.
width Width (pixels) of the video stream.
height Height (pixels) of the video stream.
elapsed Time elapsed (ms) from calling the joinChannel method until the SDK triggers this callback.

Occurs when the First Remote Video Frame is Rendered.(onFirstRemoteVideoFrame)

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

The SDK triggers this callback when the first remote video frame is rendered on the user’s video window. The app 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 remote user sending the video stream.
width Width (pixels) of the video stream.
height Height (pixels) of the video stream.
elapsed Time elapsed (ms) from calling the joinChannel method until the SDK triggers this callback.

Occurs when the Remote Video State Changes (onRemoteVideoStateChanged)

virtual void onRemoteVideoStateChanged(uid_t uid, REMOTE_VIDEO_STATE state);

The SDK triggers this callback when the remote video state changes.

Name Description
uid ID of the remote user whose video state changes.
state

The state of the remote video:

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

Reports the Last Mile Network Quality of the Local User (onLastmileQuality)

virtual void onLastmileQuality(int quality);

This callback reports on the network quality once every two seconds after you call the enableLastmileTest method. When not in a call and the network test is enabled (by calling the enableLastmileTest method), the SDK triggers this callback irregularly to update the app 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.

Reports the Network Quality of Each User (onNetworkQuality)

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

The SDK triggers this callback once every two seconds to report to the app on the network quality of each user in a Communication or Live-broadcast profile.

Name Description
uid User ID. The network quality of the user with this UID is 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.

Occurs when a Remote User's Audio Stream is Muted/Unmuted. (onUserMuteAudio)

virtual void onUserMuteAudio(uid_t uid, bool muted);

The SDK triggers this callback when a remote user's audio stream has muted/unmuted.

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

Name Description
uid User ID of the remote user.
muted
  • True: The remote user's audio is muted.
  • False: The remote user's audio is unmuted.

Occurs when a Remote User's Video Stream Playback Pauses/Resumes. (onUserMuteVideo)

virtual void onUserMuteVideo(uid_t uid, bool muted);

The SDK triggers this callback when a remote user's video stream playback pauses/resumes.

Name Description
uid User ID of the remote user.
muted
  • True: The remote user's video stream playback has paused.
  • False: The remote user's video stream playback has resumed.

Occurs when the Specified Remote User Enables/Disables the Video Module (onUserEnableVideo)

virtual void onUserEnableVideo(uid_t uid, bool enabled);

The SDK triggers this callback when the specified remote user enables/disables the video module. Disabling the video function means that the user can only use a voice call, and can neither send their own video nor receive or display video from other users.

Name Description
uid User ID of the remote user.
enabled
  • True: The remote user has enabled the video function and can enter a video call or a 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.

Occurs when the Specified Remote User Enables/Disables the Local Video Capturing Function (onUserEnableLocalVideo)

virtual void onUserEnableLocalVideo(uid_t uid, bool enabled);

The SDK triggers this callback indicates when the specified remote user enables/disables the local video capturing function.

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

Occurs when the Camera Turns on and is Ready to Capture the Video (onCameraReady)

virtual void onCameraReady();

The SDK triggers this callback when the camera turns on and is ready to capture the video. If the camera fails to turn on, an error reports in the onError callback.

Occurs when the Video Stops Playing (onVideoStopped)

virtual void onVideoStopped();

The SDK triggers this callback when the video stops playing. The app can use this callback to change the configuration of the view (for example, display other pictures in the view) after the video stops playing.

Occurs when the Connection between the SDK and the Server is Interrupted (onConnectionInterrupted)

virtual void onConnectionInterrupted();

The SDK triggers this callback when the SDK loses connection with the server for more than four seconds after the connection is established.

The SDK triggers the onConnectionLost callback when the SDK attempts to reconnect after losing connection. Once the connection is lost, and if the app does not call the leaveChannel method, the SDK automatically tries to reconnect repeatedly.

Occurs when the Connection between the SDK and the Server is Lost (onConnectionLost)

virtual void onConnectionLost();

The SDK triggers this callback when the SDK has lost connection with the network and remained unconnected for a period of time (10 seconds by default) despite attempts to reconnect. The SDK also triggers this callback when the SDK fails to join the channel 10 seconds after calling the joinChannel method. The SDK keeps trying to reconnect after triggering this callback. Upon reconnection, the SDK triggers the onRejoinChannelSuccess callback.

Occurs when your Connection is Banned by the Agora Server (onConnectionBanned)

virtual void onConnectionBanned();

The SDK triggers this callback when your connection is banned by the Agora Server.

Occurs when the Local User Receives the Data Stream from the Remote User within Five Seconds (onStreamMessage)

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

The SDK triggers this callback when the local user receives the data stream from the remote user within five seconds.

Name Description
uid User ID
data Data sent from the remote user.
length Length of the data.

Occurs when the Local User does not Receive the Data Stream from the Remote User within Five Seconds (onStreamMessageError)

virtual void onStreamMessageError(uid_t uid, int streamId, int code, int missed, int cached);

The SDK triggers this callback when the local user receives the data stream from the remote 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

Occurs when the Token Expires (onRequestToken)

virtual void onRequestToken();

When a token is specified by calling the joinChannel method, if the SDK loses connection with the Agora server due to network issues, the token may expire after a time period and a new token may be required to reconnect to the server.

The SDK triggers this callback for the app to generate a new token in order to call the renewToken method to specify the newly generated token.

This function was previously reported in the onError callback in ERR_TOEKN_EXPIRED(109) and ERR_INVALID_TOKEN(110). Starting from v1.7.3, the old method still works, but Agora recommends using this callback instead.

Occurs when the Audio Mixing File Playback Finishes (onAudioMixingFinished)

virtual void onAudioMixingFinished();

The SDK triggers this callback when the audio mixing file playback finishes after calling the startAudioMixing method. If you do not call the startAudioMixing method, an error code returns in the onError callback.

Occurs when the Local Audio Effect Playback Finishes (onAudioEffectFinished)

virtual void onAudioEffectFinished(int soundId)

The SDK triggers this callback when the local audio effect playback finishes.

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

Reports which User is the Loudest Speaker (onActiveSpeaker)

virtual void onActiveSpeaker(uid_t uid);

If you called the enableAudioVolumeIndication method, this callback returns the uid of the active speaker detected by the audio volume detection module of the SDK.

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

Occurs when the User Role Switches in a Live Broadcast (onClientRoleChanged)

virtual void onClientRoleChanged(CLIENT_ROLE_TYPE oldRole, CLIENT_ROLE_TYPE newRole);

The SDK triggers this callback when the user role switches, 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.