This page provides the C++ Interface, with which you can integrate the voice and video function into your app on Android and iOS.
Basic Methods (IRtcEngine)
agora::IRtcEngine is the basic interface class of the Agora Native SDK. Creating an agora::IRtcEngine object and then calling the methods of this object enables the use of Agora Native SDK’s communication functionality. In previous versions, this class was named IAgoraAudio and is renamed to agora::IRtcEngine from v1.0.
Creates an agora::IRtcEngine Object (create)
agora::rtc::IRtcEngine* AGORA_CALL createAgoraRtcEngine();
This method creates an IRtcEngine object. Unless otherwise specified, all called methods provided by the RtcEngine class are executed asynchronously. Agora recommends calling the methods in the same thread. Unless otherwise specified, the following rule applies to all API methods whose return values are integer types:
- A return value of 0 means that the method call is successful
- A return value of less than 0 means that the method call fails.
Name | Description |
---|---|
Return Value | An agora::IRtcEngine object. |
Initializes the Agora SDK Service (initialize)
virtual int initialize(const RtcEngineContext& context) = 0;
This method initializes the Agora SDK service. Enter the App ID issued to you to start initialization. After creating an agora::IRtcEngine
object, call this method to initialize the service before using any other methods. After initialization, the service is set to the audio mode by default. To enable video mode, call the enableVideo
method after calling this method.
The definition of RTCEngineContext is:
struct RtcEngineContext
{
IRtcEngineEventHandler* eventHandler;
/** App ID issued to you by Agora. Apply for a new one from Agora if it is missing from your kit.
*/
const char* appId;
RtcEngineContext()
:eventHandler(NULL)
,appId(NULL)
{}
};
Name | Description |
appID | App ID issued to you by Agora. Apply for a new one from Agora if it is missing from your kit. See Getting an App ID on to how to get an App ID. |
eventHandler | IRtcEngineEventHandler is an abstract class that provides default implementations. The SDK uses this class to report to the app on SDK runtime events (callbacks). |
Return Value |
|
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 currentIRtcEngine
and create a new one usingcreate
andinitialize
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:
|
Return Value |
|
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:
|
Return Value |
|
Enables Audio Mode (enableAudio)
virtual int enableAudio() = 0;
This method enables audio mode. Audio mode is enabled by default.
Name | Description |
---|---|
Return Value |
|
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 |
|
Return Value |
|
Disables Audio Mode (disableAudio)
virtual int disableAudio() = 0;
This method disables audio mode.
Name | Description |
---|---|
Return Value |
|
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:
|
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 |
|
[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
, andbitrate
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 callleaveChannel
, the SDK interrupts theleaveChannel
process, and does not trigger theonLeaveChannel
callback.
Name | Description |
---|---|
Return Value |
|
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 |
|
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:
|
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 |
|
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 |
|
Return Value |
|
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 |
|
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 |
|
Return Value |
|
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 |
|
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 |
|
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:
|
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.
|
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:
|
Return Value |
|
[2] If you preloaded the audio effect into the memory through the
preloadEffect
method, ensure that thesoundID
value is set as the same value as in thepreloadEffect
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 |
|
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 |
|
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 |
|
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 |
|
Pause all Audio Effects (pauseAllEffects)
int pauseAllEffects();
This method pauses all audio effects.
Name | Description |
Return Value |
|
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 |
|
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 |
|
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 |
|
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:
|
Return value |
|
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:
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 |
|
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:
|
Return Value |
|
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:
|
Return Value |
|
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:
|
Return Value |
|
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:
|
Return Value |
|
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:
|
Return Value |
|
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:
|
Return Value |
|
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 thesetRemoteVideo
method the next time you join a channel, or you will not see the remote video view.
Name | Description |
---|---|
Return Value |
|
Stops the Video Preview (stopPreview)
virtual int stopPreview() = 0;
This method stops the local video preview and closes the video.
Name | Description |
---|---|
Return Value |
|
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:
|
Return Value |
|
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:
|
Return Value |
|
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:
|
Return value |
|
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:
|
Return Value |
|
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 |
Live Broadcast | Speakerphone |
Game Voice | Speakerphone |
Modify the default audio route if necessary according to the following table:
Name | Description |
---|---|
defaultToSpeaker |
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 |
|
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 |
|
Return Value |
|
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 |
|
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:
|
Return Value |
|
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
andordered
parameters both asTrue
or both asFalse
. Do not set one asTrue
and the other asFalse
.
Name | Description |
---|---|
reliable |
|
ordered |
|
Return Value |
|
[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 thejoinChannel
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 thesetClientRole
method to change the user role fromaudience
(default in the live broadcast profile) tobroadcaster
before using this method.
Name | Description |
---|---|
Return Value |
|
Stops an Audio Call Test (stopEchoTest)
virtual int stopEchoTest() = 0;
This method stops an audio call test.
Name | Description |
---|---|
Return Value |
|
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 |
|
Disables the Network Test (disableLastmileTest)
virtual int disableLastmileTest() = 0;
This method disables the network connection quality test.
Name | Description |
---|---|
Return Value |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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:
|
Return Value |
|
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.
|
Return Value |
|
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 |
|
Return Value |
|
Mutes All Remote Audio Streams (muteAllRemoteAudioStreams)
int muteAllRemoteAudioStreams(bool mute);
This method enables/disables playing all remote audio streams.
When
mute
is set asTrue
, 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 |
|
Return Value |
|
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 asTrue
, 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 |
|
Return Value |
|
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 asTrue
, this method does not disable the camera and thus does not affect the retrieval of the local video stream. This method responds faster than theenableLocalVideo
method withenabled
set asNO
.
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 |
|
Return Value |
|
Mutes All Remote Video Streams (muteAllRemoteVideoStreams)
int muteAllRemoteVideoStreams(bool mute);
This method enables/disables playing all remote video streams.
When
mute
is set asTrue
, 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 |
|
Return Value |
|
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 |
|
Return Value |
|
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:
|
smooth | Smoothing factor. The default value is 3. |
Return values |
|
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 |
|
replace |
|
cycle | Number of loop playbacks:
|
Return Value |
|
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 |
|
Pauses Audio Mixing (pauseAudioMixing)
int pauseAudioMixing();
This method pauses audio mixing. Call this method when you are in a channel.
Name | Description |
---|---|
Return Value |
|
Resumes Audio Mixing (resumeAudioMixing)
int resumeAudioMixing();
This method resumes audio mixing. Call this method when you are in a channel.
Name | Description |
---|---|
Return Value |
|
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 |
|
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 |
|
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 |
|
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:
|
Return Value |
|
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:
|
Return Value |
|
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 |
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.
Name | Description |
---|---|
warn | lThe 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:
|
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 |
|
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:
|
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 ():
|
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 returnedvolume
is the same astotalVolume
. - If
uid
is not 0 andvolume
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:
|
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:
|
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:
|
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:
|
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:
|
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:
|
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:
|
rxQuality | The receiving quality of the user:
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
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. |