Communication API - Windows

C++ Interface Class Description
`Basic Methods(RtcEngine)`_ The RtcEngine class provides the main methods that can be invoked by your application
Parameter Methods(RtcEngineParameters) The RtcEngineParameters class provides the method to configure the parameters
Audio Device Management Methods(IAudioDeviceManager) The IAudioDeviceManager class tests the interfaces of the audio devices
Audio Device Collection Methods(IAudioDeviceCollection) The IAudioDeviceCollection class retrieves the device related numbers or data
Video Device Management Methods(IVideoDeviceManager) The IVideoDeviceManager class tests the interfaces of the video devices
Video Device Collection Methods(IVideoDeviceCollection) The IVideoDeviceCollection class retrieves the video device related numbers or data
Callback Methods(IRtcEngineEventHandler) The IRtcEngineEventHandler class send callback event notifications to the application

Basic Methods(IRtcEngine)

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

Create IRtcEngine Object

Create agora::rtc::IRtcEngine Object (create)

IRtcEngine*createAgoraRtcEngine(agora::rtc::IRtcEngineEventHandler* pEventHandler)

This method creates an IRtcEngine object. Unless otherwise specified, all called methods provided by this object are executed asynchronously. We recommend calling the interface methods in the same thread. Unless otherwise specified, the following applies to all the APIs whose return values are int type: a return value of 0 indicates that the call is successful, and a return value less than 0 indicates that the call fails.

Name Description
pEventHandler Agora Native SDK notifies the application of its triggered events by calling agora::rtc::IRtcEngineEventHandler. The application must inherit the interface class, implement a corresponding callback method and pass it when using createAgoraRtcEngine to create an ItcEngine object. All the callback methods have their default implementations, so the application can inherit the required callback methods only instead of all of them. Refer to the agora::rtc::IEventHandler Interface Class section in this document for more detailed information.
Return Value An agora::rtc::IRtcEngine object.

Initialize (initialize)

int initialize(const RTCEngineContext& context)

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

The definition of RTCEngineContext is:

struct RtcEngineContext {

           IRtcEngineEventHandler* eventHandler;
           const char* appId;
       };
Name Description
appId The App ID issued to the application developers by Agora.io. Apply for a new one from Agora.io if the key is missing in your kit.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.
  • ERR_INVALID_VENDOR_KEY(-101): The entered App ID is invalid.

Implement Audio Communication

The following shows how to implement a basic audio communication function. The developers can add more functions to the basic audio communication according to the following modules included in this document. Be sure that a IRtcEngine object has been created for the application.

../../_images/android_audio_api.png

Set Channel Profile (setChannelProfile)

int setChannelProfile (CHANNEL_PROFILE_TYPE profile)

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

The Agora Native SDK currently supports the following profiles:

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

Note

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

The channel profile. Choose from the following:

  • CHANNEL_PROFILE_COMMUNICATION: Communication (default)
  • CHANNEL_PROFILE _LIVE_BROADCASTING: Live Broadcast
  • CHANNEL_PROFILE _GAME: Game Voice
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Enable Audio Mode(enableAudio)

int enableAudio();

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

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

Disable Audio Mode(disableAudio)

int disableAudio();

This method disables audio mode.

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

Join Channel (joinChannel)

int joinChannel(const char* channelKey, const char* channel, const char* info, uid_t uid)

This method lets the user join a channel. Users in the same channel can talk to each other; and multiple users in the same channel can start a group chat. Users using different App IDs cannot call each other. Once in a call, the user must call the leaveChannel method to exit the current call before entering another channel.

Note

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

Name Description
channelKey

The token is a Channel Key generated by the application.

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

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

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

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: a-z,A-Z,0-9,space,! #$%&,()+, -,:;<=.,>? @[],^_,{|},~

info (Optional) Additional info about the channel that developers need to add. It can be set as NULL String, or channel related information. Other users in the channel cannot receive this message.
uid (Optional) User ID: a 32-bit unsigned integer ranges from 1 to (2^32-1). It must be unique. If not assigned (or set to 0), the SDK allocates one and returns it in onJoinChannelSuccess callback. Your app must record and maintain the returned value, because the SDK does not .
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.
  • ERR_INVALID_ARGUMENT (-2): The passed argument is invalid.
  • ERR_NOT_READY (-3): Initialization failed.
  • ERR_REFUSED (-5): The SDK cannot start a call. It could be that the SDK is in another call or failed to create a channel.

Leave Channel (leaveChannel)

int leaveChannel ()

This method lets the user leave a channel, that is, hanging up or exiting a call. After joining a channel, the user must call the leaveChannel method to end the call before joining another one. Returns 0 if the user has successfully left the channel. Calling the leaveChannel method even when not in a call is harmless. The leaveChannel method releases all resources related to the call.

The leaveChannel method is called asynchronously, and the user actually does not exit the channel when the call returns. Once the user exits the channel, the SDK triggers onLeaveChannel callback.

Note

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

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

Implement Video Communication

The following shows how to implement a basic video communication function. The developers can add more functions to the basic audio communication according to the following modules included in this document. Be sure that a IRtcEngine object has been created for the application.

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

../../_images/windows_video_api.png

Enable Video Mode (enableVideo)

int enableVideo()

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

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

Disable Video (disableVideo)

int disableVideo()

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

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

Set Video Profile (setVideoProfile)

int setVideoProfile(VIDEO_PROFILE_TYPE profile)

This method sets the video encoding profile. Each profile includes a set of parameters such as resolution, frame rate, bitrate, and so on. When the device camera does not support the specified resolution, the SDK chooses a suitable camera resolution, but the encoder resolution still uses the one specified by setVideoProfile.

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

Note

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

Whether to swap the width and height of the stream:

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

Video Profile Definition

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

Footnotes

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

Set Local Video View (setupLocalVideo)

int setupLocalVideo(const VideoCanvas& canvas)

This method configures the video display settings on local machine.

The application calls this method to bind with the video window (view) of local video streams and configures the video display settings. When developing the application, the usual practice is to call this method after initialization to configure local video display settings before entering a channel. The bind is still valid after exiting the channel. To unbind the view, set the view value to NULL when calling setupLocalVideo.

Name Description
canvas

The video display settings.

  • view: The video display window (view). In Windows, the data type of the view is Window Handle (HWND). The application needs to ensure that the Window Handle is valid during the call, otherwise it may cause the SDK to crash. The Window Handle can be safely released after calling leaveChannel with a returned value.
  • renderMode: The video display mode.
    • RENDER_MODE_HIDDEN(1): If the video size is different than that of the display window, crops the borders of the video (if the video is bigger) or stretch the video (if the video is smaller) to fit it in the window.
    • RENDER_MODE_FIT(2): If the video size is different than that of the display window, resizes the video proportionally to fit the window.
    • RENDER_MODE_ADAPTIVE(3): Adapts to the callers’ screen orientations. If both callers use the same screen orientation, that is, both use vertical screens or both use horizontal screens, the RENDER_MODE_HIDDEN mode applies; if they use different screen orientations, that is, one vertical and one horizontal, the RENDER_MODE_FIT mode applies.
  • uid: The local user ID as set in the joinchannel method.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.
struct VideoCanvas {
view_t view;
int renderMode;
uid_t uid;
};

Set Remote Video View (setupRemoteVideo)

int setupRemoteVideo(const VideoCanvas& canvas)

This method binds the remote user to the video display window, that is, sets the view for the user of the specified uid.

Usually the application should specify the uid of the remote video in the method call before the user enters a channel. If the remote uid is unknown to the application, set it later when the application receives the onUserJoined event.

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

Name Description
canvas

The video display settings.

  • view: The video display window (view). In Windows, the data type of the view is Window Handle (HWND). The application needs to ensure that the Window Handle is valid during the call, otherwise it may cause the SDK to crash. The Window Handle can be safely released after calling leaveChannel with a returned value.
  • renderMode: The video display mode.
    • RENDER_MODE_HIDDEN(1): If the video size is different than that of the display window, crops the borders of the video (if the video is bigger) or stretch the video (if the video is smaller) to fit it in the window.
    • RENDER_MODE_FIT(2): If the video size is different than that of the display window, resizes the video proportionally to fit the window.
    • RENDER_MODE_ADAPTIVE(3): The mode adapts to screen orientations. If both callers use the same screen orientation, that is, both use vertical screens or both use horizontal screens, the RENDER_MODE_HIDDEN mode applies; if they use different screen orientations, that is, one vertical and one horizontal, the RENDER_MODE_FIT mode applies.
  • uid: The user ID of the remote user whose video streams are received.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.
struct VideoCanvas {
view_t view;
int renderMode;
uid_t uid;
};

Set High-Quality Video Preferences(setVideoQualityParameters)

int setVideoQualityParameters(bool preferFrameRateOverImageQuality);

This method allows the users to set the video preferences.

Name Description
preferFrameRateOverImageQuality

The video preference to be set:

  • True: Frame Rate over Image Quality
  • False: Image Quality over Frame Rate (default)
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Start Video Preview (startPreview)

int startPreview()

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

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

Stop Video Preview (stopPreview)

int stopPreview()

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

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

Renew Channel Key (renewChannelKey)

int renewChannelKey(const char* channelKey)

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

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

Encryption

Register Packet Observer (registerPacketObserver)

int registerPacketObserver(IPacketObserver* observer)

This method registers the Packet Observer. Upon sending/receiving audio or video network packet, the Agora SDK triggers a callback on the interface defined by the IPacketObserver, and then the application processes the data, for example, data encryption or decryption, with this interface.

Note

The maximum size of the processed network packet is 1200 bytes; packet larger than the maximum size may not be sent successfully.

Name Description
observer Callback interface of the send/receive packet.
Return Value 0: Method call succeeded.
<0: Method call failed.

Enable Built-in Encryption(setEncryptionSecret)

int setEncryptionSecret(const char* secret)

Ensure that your application calls setEncryptionSecret to specify a secret to enable the built-in encryption before joining a channel, otherwise the communication is unencrypted. All users in a channel must set the same secret. The secret is automatically cleared once the user has left the channel. If the secret is not specified or set to empty, the encryption function is disabled.

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

Set Built-in Encryption Mode(setEncryptionMode)

int setEncryptionMode (const char* encryptionMode)

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

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

Note

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

Name Description
encryptionMode

Encryption mode. The following modes are supported currently:

  • “aes-128-xts”:128-bit AES encryption, XTS mode
  • “aes-128-ecb”:128-bit AES encryption, ECB mode
  • “aes-256-xts”: 256-bit AES encryption, XTS mode
  • “”: When it is set to NUL string, the encryption is in “aes-128-xts” by default.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Establish Data Channel

Create Data Stream(createDataStream)

int createDataStream(int* streamID, bool reliable, bool ordered)

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

Name Description
reliable True: The recipients will receive data from the sender within 5s.
ordered True: The recipients will receive data from the sender in order within 5s.
length Length of the data to be sent.
Return Value
  • <0: It returns error code when it fails to create the data stream [2]
  • >0: It returns the Stream ID when the data stream is created.

Footnotes

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

Send Data Stream(sendStreamMessage)

int sendStreamMessage(int streamID, const char* data, size_t length)

This method sends the created data stream to the recipients. Each channel supports up to 30 packets per second and each packet cannot exceed 1KB. The API controls the rate in data channel: each application supports up to 6KB data per second. Each user can have up to 5 data channels simultaneously.

Name Description
streamId Stream ID returned by createDataStream.
data data to be sent
Return Value

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

ERR_SIZE_TOO_LARGE/ERR_TOO_OFTEN/ERR_BITRATE_LIMIT and etc.

Test and Detection

Start Audio Call Test (startEchoTest)

int startEchoTest()

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

Note

After calling the startEchoTest method, always call stopEchoTest to end the test. Otherwise the application cannot run the next echo test, nor can it call the joinChannel method to start a new call.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.
  • ERR_REFUSED (-5): Failed to launch the echo test, for example, initialization failed.

Stop Audio Call Test (stopEchoTest)

int stopEchoTest()

This method stops the audio call test.

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

Enable Network Test (enableLastmileTest)

int enableLastmileTest()

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

This method is mainly used in this scenario:

Calling this method consumes extra network traffic, which may affect the communication quality. Call disableLastmileTest to disable it immediately once they have received the onLastmileQuality callback before they join the channel.

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

Disable Network Test (disableLastmileTest)

int disableLastmileTest()

This method disables the network connection quality test.

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

Feedback

Retrieve Current Call ID (getCallId)

int getCallId(agora::util::AString& callId)

This method retrieves the current call ID. Every time when a user joins a channel on a client machine, a CallId is generated to identify the call from this client. Some methods such as rate() and complain() submit feedback to the SDK and are invoked after the call ends. These methods require assigned values of the CallId parameters. To use these feedback methods, call the getCallId() method to retrieve the CallId during the call, and then pass the value as an argument in the feedback methods after the call ends.

Name Description
callId The current call ID.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Rate the Call (rate)

int rate(const char* callId, int rating, const char* description)

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

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

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

This parameter is optional.

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

Complain about Call Quality (complain)

int complain(const char* callId, const char* description)

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

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

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

This parameter is optional.

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

Release IRtcEngine Object (release)

void release()

This method releases the IRtcEngine object.

Name Description
sync

It indicates whether this method is called synchronously or asynchronously.

  • True: synchronous call. The result returns after the IRtcEngine Object resources are released. APP should not call this interface in the callback generated by the SDK, otherwise the SDK must wait for the callback to return to recover the associated object resources, resulting in deadlock. SDK automatically detects such a deadlock and turns it into an asynchronous call, but the test itself takes extra time.
  • False: asynchronous call. The result returns immediately even when the IRtcEngine object resources are not released, and the SDK will release all resources on its own. Pay attention: do not immediately uninstall the SDK dynamic library after the call, otherwise it may crash because the SDK clean-up thread has not quit yet.
Return Value
  • <0: error code.
  • 0: method call succeed.

Get SDK Version(getVersion)

virtual const char* getVersion(int* build)

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

Parameter Methods(RtcEngineParameters)

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

Mute Audio and Video Stream

Mute Local Audio Stream (muteLocalAudioStream)

int muteLocalAudioStream(bool mute)

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

Note

This method does not disable the microphone, and thus does not affect the recording process, if any.

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

Disable Local Video (enableLocalVideo)

int enableLocalVideo(bool enabled)

This method disables the local video, which is only applicable to the scenario when the user only wants to watch the remote video without sending any video stream to the other user. This method does not require a local camera.

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

Mute All Remote Audio Streams (muteAllRemoteAudioStreams)

int muteAllRemoteAudioStreams(bool mute)

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

Note

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

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

Mute Certain Remote Audio Stream (muteRemoteAudioStream)

int muteRemoteAudioStream(uid_t uid, bool mute);

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

Note

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

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

Mute Local Video Stream (muteLocalVideoStream)

int muteLocalVideoStream (bool mute)

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

Note

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

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

Mute All Remote Video Streams (muteAllRemoteVideoStreams)

int muteAllRemoteVideoStreams (bool mute)

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

Note

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

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

Mute Certain Remote Video Stream (muteRemoteVideoStream)

int muteRemoteVideoStream(uid_t uid, bool mute);

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

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

Set Video Display Mode

Set Local Video Display Mode (setLocalRenderMode)

int setLocalRenderMode (int mode);

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

Name Description
Mode

Configures the video display mode.

  • RENDER_MODE_HIDDEN(1): If the video size is different than that of the display window, crops the borders of the video (if the video is bigger) or stretch the video (if the video is smaller) to fit it in the window.
  • RENDER_MODE_FIT(2): If the video size is different than that of the display window, resizes the video proportionally to fit the window.
  • RENDER_MODE_ADAPTIVE(3): This mode adapts to the screen orientations. If both callers use the same screen orientation, that is, both use vertical screens or both use horizontal screens, the RENDER_MODE_HIDDEN mode applies; if they use different screen orientations, that is, one vertical and one horizontal, the RENDER_MODE_FIT mode applies.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set Remote Video Display Mode (setRemoteRenderMode)

int setRemoteRenderMode (uid_t uid, int mode);

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

Name Description
uid The user ID.
mode

Configures the video display mode.

  • RENDER_MODE_HIDDEN(1): If the video size is different than that of the display window, crops the borders of the video (if the video is bigger) or stretch the video (if the video is smaller) to fit it in the window.
  • RENDER_MODE_FIT(2): If the video size is different than that of the display window, resizes the video proportionally to fit the window.
  • RENDER_MODE_ADAPTIVE(3): This mode adapts to the screen orientations. If both callers use the same screen orientation, that is, both use vertical screens or both use horizontal screens, the RENDER_MODE_HIDDEN mode applies; if they use different screen orientations, that is, one vertical and one horizontal, the RENDER_MODE_FIT mode applies.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set Audio Volume

Enable Audio Volume Indication (enableAudioVolumeIndication)

int enableAudioVolumeIndication (int interval, int smooth)

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

Name Description
interval

Specifies the time interval between two consecutive volume indications.

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

Set Speakerphone Volume (setPlaybackDeviceVolume)

int setPlaybackDeviceVolume(int volume);

This method sets the speakerphone volume.

Name Description
volume Sets the speakerphone volume between 0 (lowest volume) to 255 (highest volume).
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Recording

Start Audio Recording (startAudioRecording)

int startAudioRecording (const char* filePath)

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

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

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

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

Stop Audio Recording (stopAudioRecording)

int stopAudioRecording ()

This method stops recording on the client machine.

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

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

Set Recording Audio Format (setRecordingAudioFrameParameters)

Refer to Set Recording Audio Format (setRecordingAudioFrameParameters).

Set Playback Audio Format (setPlaybackAudioFrameParameters)

Refer to Set Playback Audio Format (setPlaybackAudioFrameParameters).

Adjust Recording Signaling Volume (adjustRecordingSignalVolume)

int adjustRecordingSignalVolume(int volume);

This method adjusts the recording signal volume.

Name Description
volume

The recording signal volume ranges from 0~400:

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

Adjust Playback Signal Volume(adjustPlaybackSignalVolume)

int adjustPlaybackSignalVolume(int volume);

This method adjusts the playback Signal Volume.

Name Description
volume

The playback signal volume ranges from 0~400:

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

Audio Mixing

Start Audio Mixing (startAudioMixing)

int startAudioMixing(String filePath,
                                                    Boolean loopback,
                                                    Boolean replace,
                                                    int cycle);

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

Note

Call this API when you are in the channel, otherwise it will probably cause issues.

Name Description
filePath

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

The following lists the supported audio formats: mp3, aac, m4a, 3gp, wav

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

Specify the number of loop playbacks:

  • Positive integer: the number of loop playbacks
  • -1: infinite loop
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Stop Audio Mixing (stopAudioMixing)

int startAudioMixing()

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

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

Pause Audio Mixing (pauseAudioMixing)

int pauseAudioMixing();

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

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

Resume Audio Mixing (resumeAudioMixing)

int resumeAudioMixing();

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

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

Adjust Audio Mixing Volume (adjustAudioMixingVolume)

int adjustAudioMixingVolume(int volume);

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

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

Get the Audio Mixing Duration(getAudioMixingDuration)

int getAudioMixingDuration();

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

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

Get Music Current Position(getAudioMixingCurrentPosition)

int getAudioMixingCurrentPosition();

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

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

Drag Audio Progress Bar(setAudioMixingPosition)

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

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

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

Other Functions

Set Log File (setLogFile)

int setLogFile(const char* filePath)

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

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

Set Log Filter (setLogFilter)

int setLogFilter(unsigned int filter)

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

Name Description
filter

Filters

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

Screen Sharing

Start Screen Sharing (startScreenCapture)

int startScreenCapture(unsigned int windowId, int captureFreq, const Rect *rect)

This method shares the whole screen, the specified window, or the specified region:

  • **Share the whole screen: ** set windowId as 0 and set rect as null
  • Share the specified window: set windowId not as 0, each window has a windowId which is not
  • Share the specified region: set windowId as 0 and set rect not as null. In this case, you can share the specified region, for example by dragging the mouse, the logic of which is implemented by yourselves [3]

Footnotes

[3]Here the specified region means a region in the whole screen. Currently it does not support sharing a specified region in a specific window. captureFreq is the captured frame rate once the screensharing function is enabled, and the value(mandatory) ranges from 1 fps to 15 fps. No matter which function you have enabled, it returns 0 after the successful execution, otherwise it returns error code.

Stop Screen Sharing(stopScreenCapture)

int stopScreenCapture();

This method stops the screen sharing.

Audio Device Management Methods(IAudioDeviceManager)

agora::rtc::IAudioDeviceManager interface class tests the interfaces of the audio devices. Instantiate an AAudioDeviceManager class to get an IAudioDeviceManager interface.

Enumerate Playback Devices (enumeratePlaybackDevices)

IAudioDeviceCollection* enumeratePlaybackDevices()

This method returns an IAudioDeviceCollection object that includes all the playback devices in the system. With the IAudioDeviceCollection object, the application can enumerate the playback devices. The application must call the IAudioDeviceCollection::release() method to release the returned object after using it.

Name Description
Return Value

It returns an IAudioDeviceCollection object that includes all the playback devices in the system when the method call succeeded.

It returns NULL when the method call fails.

Enumerate Recording Devices (enumerateRecordingDevices)

IAudioDeviceCollection* enumerateRecordingDevices()

This method returns an IAudioDeviceCollection object that includes all the recording devices in the system. With the IAudioDeviceCollection object, the application can enumerate the recording devices. The application needs to call the IAudioDeviceCollection::release() method to release the returned object after using it.

Name Description
Return Value

When successful, it returns an IAudioDeviceCollection object that includes all the recording devices in the system when the call succeeded.

It returns NULL when the call failed.

Specify Playback Device with deviceID (setPlaybackDevice)

int setPlaybackDevice(const char deviceId[MAX_DEVICE_ID_LENGTH])

This method uses the device ID to specify a playback device.

Name Description
deviceId Device ID of the playback device. It can be retrieved by the enumeratePlaybackDevices() method. Plugging or unplugging the device does not change the device ID.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Specify Recording Device with deviceID (setRecordingDevice)

int setRecordingDevice(const char deviceId[MAX_DEVICE_ID_LENGTH])

This method uses the device ID to specify a recording device.

Name Description
deviceId Device ID of the recording device. It can be retrieved by the enumerateRecordingDevices() method. Plugging or unplugging the device does not change the device ID.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Start Playback Device Test (startPlaybackDeviceTest)

int startPlaybackDeviceTest(const char* testAudioFilePath)

This method tests if the playback device works properly or not. In the test, the SDK plays an audio file specified by the user (tester), and if the user can hear the sound it means that the playback device works properly.

Name Description
testAudioFilePath

Specifies the path of the audio file for the test which is utf8 absolute path:

  • Supported File Format: wav, mp3, m4a, and aac
  • Supported File Sampling Rate: 8000, 16000, 32000, 44100 and 48000
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Stop Playback Device Test (stopPlaybackDeviceTest)

int stopPlaybackDeviceTest()

This method stops the playback device test. To stop the test, call this method after calling the startPlaybackDeviceTest() method.

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

Start Microphone Test (startRecordingDeviceTest)

int startRecordingDeviceTest(int indicationInterval)

This method tests whether the microphone works properly. Once the test starts, the SDK uses the onAudioVolumeIndication callback to notify the application about the volume information.

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

Stop Microphone Test (stopRecordingDeviceTest)

int stopRecordingDeviceTest()

This method stops the microphone test. To stop the test, call this method after calling the startRecordingDeviceTest() method.

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

Audio Device Collection Methods(IAudioDeviceCollection)

agora::rtc::IAudioDeviceCollection interface class retrieves the device related numbers or data.

Retrieve Total Count of Playback or Recording Devices (getCount)

int getCount()

Call enumeratePlaybackDevices() first and then call this method to return the number of the audio playback devices. Call enumerateRecordingDevices() first and then call this method to return the number of the audio recording devices.

Name Description
Return Value The number of the audio devices.

Retrieve Indexed Device Info (getDevice)

int getDevice(int index, char deviceName[MAX_DEVICE_ID_LENGTH], char deviceId[MAX_DEVICE_ID_LENGTH])

This method retrieves a specified piece of information about an audio device.

Name Description
index An input parameter to specify the device information to be enquired.
deviceName An output parameter that indicates the device name.
deviceId An output parameter that indicates the device ID.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Specify Device with deviceID (setDevice)

int setDevice(const char deviceId[MAX_DEVICE_ID_LENGTH])

This method uses the device ID to specify a device, which is the recommended way.

Name Description
deviceId The device ID.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Video Device Management Methods(IVideoDeviceManager)

agora::rtc::IVideoDeviceManager interface class tests the interfaces of the video devices. Instantiate an AVideoDeviceManager class to get an IVideoDeviceManager interface.

Enumerate Video Capture Devices (enumerateVideoDevices)

IVideoDeviceCollection* enumerateVideoDevices()

This method returns an IVideoDeviceCollection object that includes all the video-capture devices in the system. With the IVideoDeviceCollection object, the application can enumerate the video-capture devices. The application must call the IVideoDeviceCollection::release() method to release the returned object after using it.

Name Description
Return Value

It returns an IVideoDeviceCollection object that includes all the video-capture devices in the system when the method call succeeded.

It returns NULL when the method call fails.

Specify Device with deviceID (setDevice)

int setDevice(const char deviceId[MAX_DEVICE_ID_LENGTH])

This method uses the device ID to specify a video-capture device, which is the recommended way.

Name Description
deviceId Device ID of the video-capture device. You can call enumerateVideoDevices() to retrieve it. Plugging or unplugging the device does not change the device ID.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Retrieve Current Device (getDevice)

int getDevice(char deviceId[MAX_DEVICE_ID_LENGTH])

This method retrieves the video-capture device that is in use currently.

Name Description
deviceId

Output parameter.

Device ID of the video-capture device.

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

Start Video Capture Device Test (startDeviceTest)

int startDeviceTest(view_t hwnd)

This method tests whether the current video-capture device works properly or not. Before calling this method, ensure that you have already called enableVideo and the HWND window handle of the incoming parameter is valid.

Name Description
hwnd

Output parameter.

The window handle is used to display screen.

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

Stop Video Capture Device Test (stopDeviceTest)

int stopDeviceTest()

This method stops the video-capture device test.

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

Video Device Collection Methods(IVideoDeviceCollection)

agora::rtc::IVideoDeviceCollection interface class retrieves the video device related numbers or data.

Retrieve Total Count of Video Capture Devices (getCount)

int getCount()

This method retrieves the total number of the indexed video-capture devices in the system.

Name Description
Return Value Total number of the indexed video-capture devices.

Retrieve Indexed Device Info (getDevice)

int getDevice(int index, char deviceName[MAX_DEVICE_ID_LENGTH], char deviceId[MAX_DEVICE_ID_LENGTH])

This method retrieves a specified piece of information about an indexed video-capture device.

Name Description
index

An input parameter. Specified index.

It must be smaller than the return value of getCount.

deviceName An output parameter that indicates the device name.
deviceId An output parameter that indicates the device ID.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Specify Device with deviceID (setDevice)

int setDevice(const char deviceId[MAX_DEVICE_ID_LENGTH])

This method uses the device ID to specify a video-capture device, which is the recommended way.

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

Callback Methods(IRtcEngineEventHandler)

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

Join Channel Callback (onJoinChannelSuccess)

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

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

Name Description
channel The channel name.
uid

User ID.

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

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

Rejoin Channel Callback (onRejoinChannelSuccess)

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

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

Name Description
channel The channel name.
uid User ID.
elapsed Time elapsed in milliseconds from calling joinChannel until this event occurs.

Warning Occurred Callback (onWarning)

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

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

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

Error Occurred Callback (onError)

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

This callback indicates that a network or media error occurred during the runtime of the SDK. In most cases reporting an error means that the SDK cannot fix the issue and resume running, and therefore requires actions from the application or simply informs the user on the issue. For instance, the SDK reports an ERR_START_CALL error when failed to initialize a call. In this case, the application informs the user that the call initialization failed and in the same time it also calls the leaveChannel method to exit the channel.

Name Description
err

Error code:

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

Audio Quality Callback (onAudioQuality)

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

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

Name Description
uid User ID of the speaker (that is, the user who is speaking).
quality

The rating of the audio quality:

  • QUALITY_UNKNOWN( = 0)
  • QUALITY_EXCELLENT(1)
  • QUALITY_GOOD(2)
  • QUALITY_POOR(3)
  • QUALITY_BAD(4)
  • QUALITY_VBAD(5)
delay Time delay in milliseconds.
lost The packet loss rate.

Audio Volume Indication Callback (onAudioVolumeIndication)

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

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

Name Description
speakers

The speakers (array). Each speaker ():

  • uid: User ID of the speaker (that is, the user who is speaking).
  • volume: The volume of the speaker between 0 (lowest volume) to 255 (highest volume).
speakerNumber Total number of speakers.
totalVolume Total volume after audio mixing between 0 (lowest volume) to 255 (highest volume).

Leave Channel Callback (onLeaveChannel)

virtual void onLeaveChannel(const RtcStats& stat)

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

Name Description
stat

The statistics about the call.

  • duration: Call duration in seconds.
  • txBytes: Total number of bytes transmitted.
  • rxBytes: Total number of bytes received.
  • txKBitRate: The transmission bitrate in kbps.
  • rxKBitRate: The receive bitrate in kbps.
struct RtcStats {
                unsigned int duration;
                unsigned int txBytes;
                unsigned int rxBytes;
          unsigned short txKBitRate;
          unsigned short rxKBitRate;
        };

Other User Joined Channel Callback (onUserJoined)

virtual void onUserJoined(uid_t uid, int elapsed)

This callback method notifies the application that another user has joined the channel. If there are other users in the channel when that user joins, the SDK also reports to the application on the existing users who are already in the channel.

Note

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

Name Description
uid The user ID.
elapsed The time delay in milliseconds from calling joinChannel until this callback is triggered.

Other User Offline Callback (onUserOffline)

virtual void onUserOffline(uid_t uid, USER_OFFLINE_REASON_TYPE reason);

This callback notifies the application that a user has left the channel or gone offline.

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

Name Description
uid User ID.
reason

Reason this callback is triggered:

  • USER_OFFLINE_QUIT: User has quit the call.
  • USER_OFFLINE_DROPPED: The SDK has dropped the user because it has not received anything from them for a period. Note: Sometimes the user has actually ended the call, but the message is not passed to the SDK (due to and unreliable channel). The SDK may mistake this for a time out.

Call Session Statistics Callback (onRtcStats)

virtual void onRtcStats(const RtcStats& stats)

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

Name Description
stat

The statistics about the call.

  • duration: Call duration in seconds, represented by an aggregate value.
  • txBytes: Total number of bytes transmitted, represented by an aggregate value.
  • rxBytes: Total number of bytes received, represented by an aggregate value.
  • txKBitRate: The transmission bitrate in kbps, represented by an instantaneous value.
  • rxKBitRate: The receive bitrate in kbps, represented by an instantaneous value.
  • lastmileQuality: The current network connection quality of the client machine, represented by an instantaneous value.
struct RtcStats {
        unsigned int duration;
        unsigned int txBytes;
        unsigned int rxBytes;
      unsigned short txKBitRate;
      unsigned short rxKBitRate;
    double cpuAppUsage;
    double cpuTotalUsage;
};

Local Video Statistics Callback (onLocalVideoStats)

virtual void onLocalVideoStats(const LocalVideoStats& stats)

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

Name Description
stats

The statistics of the local video, including:

  • sentBitrate: The transmission bitrate (in kbps) since last count.
  • sentFrameRate: The transmission frame rate (in fps) since last count.

Remote Video Statistics Callback (onRemoteVideoStats)

virtual void onRemoteVideoStats(const RemoteVideoStats& stats)

The SDK updates the application on the statistics about receiving remote video streams once every 2 seconds. The definition of RemoteVideoStats is listed as follows:

Name Description
stats

The statistics of the remote video, including:

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

First Local Video Frame Received and Displayed Callback (onFirstLocalVideoFrame)

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

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

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

Frist Remote Video Frame Received and Decoded Callback (onFirstRemoteVideoDecoded)

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

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

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

First Remote Video Frame Received and Displayed Callback (onFirstRemoteVideoFrame)

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

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

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

Audio Device State Changed Callback (onAudioDeviceStateChanged)

virtual void onAudioDeviceStateChanged(const char* deviceId, int deviceType, int deviceState)

This callback notifies the application that the system’s audio device state has been changed, for example, a headset is unplugged from the device.

Name Description
deviceId Device ID.
deviceType

Device type defined as follows:

  • UNKNOWN_AUDIO_DEVICE(-1)
  • PLAYOUT_DEVICE(0)
  • RECORDING_DEVICE(1)
deviceState

Device state defined as follows:

  • AUDIO_DEVICE_STATE_ACTIVE(1)
  • AUDIO_DEVICE_STATE_DISABLED(2)
  • AUDIO_DEVICE_STATE_NOT_PRESENT(4)
  • AUDIO_DEVICE_STATE_UNPLUGGED(8)

Network Quality Callback (onLastmileQuality)

virtual void onLastmileQuality(int quality)

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

Name Description
quality

The network quality is rated as follows:

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

In-Call Network Quality Callback(onNetworkQuality)

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

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

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

The uplink network quality of the user:

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

The downlink network quality of the user:

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

Other User Muted Audio Callback (onUserMuteAudio)

virtual void onUserMuteAudio(uid_t uid, bool muted)

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

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

Other User Paused/Resumed Video Callback (onUserMuteVideo)

virtual void onUserMuteVideo(uid_t uid, bool muted)

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

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

Other User Enabled/Disabled Video Callback(onUserEnableVideo)

virtual void onUserEnableVideo(uid_t uid, bool enabled)

This callback indicates that other users enabled/disabled the video function. Once the video function is disabled, the users cannot see any video from themselves or from other users.

Name Description
uid User ID
enabled
  • True: User has enabled the video function.
  • False: User has disabled the video function.

Camera Ready Callback (onCameraReady)

virtual void onCameraReady()

This callback indicates that the camera is opened and ready to capture video. If failed to open the camera, handle the error in the onError() method.

Video Stopped Callback (onVideoStopped)

virtual void onVideoStopped()

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

Connection Interrupted Callback (rtcEngineConnectionDidInterrupted)

virtual void onConnectionInterrupted ()

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

Connection Lost Callback (onConnectionLost)

virtual void onConnectionLost()

When the connection between the SDK and server is lost, the onConnectionInterrupted callback is triggered and the SDK reconnects automatically. If the reconnection fails within a certain period (10 seconds by default), the callback onConnectionLost is triggered。The SDK continues to reconnect until the application calls leaveChannel.

Data Stream Received Callback(onStreamMessage)

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

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

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

Data Stream Sent Failure Callback(onStreamMessageError)

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

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

Name Description
uid User ID
streamId Stream ID
code
  • ERR_OK = 0, No error
  • ERR_NOT_IN_CHANNEL=113, the user is not in a channel
  • ERR_SIZE_TOO_LARGE=114, data size is too big
  • ERR_BITRATE_LIMIT=115, limited bitrate
  • ERR_TOO_MANY_DATA_STREAMS =116, too many data streams
  • ERR_STREAM_MESSAGE_TIMEOUT=117, data stream timed out

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

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

Channel Key Expired Callback(onRequestChannelKey)

virtual void onRequestChannelKey();

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

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

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

Audio Mixing File Playback Finished Callback(onAudioMixingFinished)

virtual void onAudioMixingFinished()

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

Active Speaker Detected Callback (onActiveSpeaker)

virtual void onActiveSpeaker(uid_t uid);

When the Volume Detection Module finds that there is a new active speaker speaking, and it returns the user id of this specific user in this callback.

Name Description
uid The user id of the active speaker.

If needed, you can code by yourself to implement specific functions, for example, the video of a new active speaker will be automatically enlarged when the new active speaker is detected, while the rest users are switched to the small views automatically.