Interactive Gaming API

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

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
warn	The 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.