Agora C++ API Reference for All Platforms

Disables/Re-enables the local video.

This method is only applicable when the user 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 the enableVideo method is called, the local video is enabled by default. This method is used to disable/re-enable the local video while the remote video remains unaffected.

Note

This method affects the internal engine and can be called after the leaveChannel method.

Parameters

enabled

Sets whether to disable/re-enable the local video, including the capturer, renderer, and sender: true: (Default) Re-enable the local video. false: Disable the local video. Once the local video is disabled, the remote users can no longer receive the video stream of this user, while this user can still receive the video streams of the other remote users.

Returns

• 0: Success.
• < 0: Failure.

Stops sending the local video stream.

Note

When set to true, this method does not disable the camera which does not affect the retrieval of the local video streams. This method executes faster than the enableLocalVideo method which controls the sending of the local video stream.

Parameters

mute	Sets whether to send/stop sending the local video stream: true: Stop sending the local video stream. false: (Default) Send the local video stream.

Returns

• 0: Success.
• < 0: Failure.

Stops receiving all remote users’ video streams.

Parameters

mute	Sets whether to receive/stop receiving all remote users' video streams: true: Stop receiving all remote users' video streams. false: (Default) Receive all remote users' video streams.

Returns

• 0: Success.
• < 0: Failure.

Stops receiving all remote users' video streams by default.

Parameters

mute	Sets whether to receive/stop receiving all remote users' video streams by default: true: Stop receiving all remote users' video streams by default. false: (Default) Receive all remote users' video streams by default.

Returns

• 0: Success.
• < 0: Failure.

Stops receiving a specified remote user’s video stream.

Note

If you called the muteAllRemoteVideoStreams method and set mute as true to stop receiving all remote video streams, call the muteAllRemoteVideoStreams method and set mute as false before calling this method.

Parameters

uid	User ID of the specified remote user.
mute	Sets whether to receive/stop receiving the specified remote user’s video stream: true: Stop receiving the specified remote user’s video stream. false: (Default) Receive the specified remote user’s video stream.

Returns

• 0: Success.
• < 0: Failure.

Deprecated:

Use setPlaybackDeviceVolume instead. Sets the playback device volume.

Parameters

volume

Sets the volume of the playback device. The value ranges between 0 and 255.

Returns

• 0: Success.
• < 0: Failure.

Starts an audio recording.

The SDK allows recording during a call. Supported 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. This method is usually called after the joinChannel method. The recording automatically stops when the leaveChannel method is called.

Parameters

filePath	Pointer to the absolute file path of the recording file. The string of the file name is in UTF-8.
quality	Sets the audio recording quality. See AUDIO_RECORDING_QUALITY_TYPE.

Returns

• 0: Success.
• < 0: Failure.

Stops an audio recording on the client.

You can call this method before calling the leaveChannel method else, the recording automatically stops when the leaveChannel method is called.

Returns

• 0: Success
• < 0: Failure.

Starts playing and mixing the music file.

This method mixes the specified local audio file with the audio stream from the microphone, or 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 playback loops. This method also supports online music playback.

When the audio mixing file playback finishes after calling this method, the onAudioMixingFinished callback is triggered.

Note

Call this method when you are in a channel.

Parameters

filePath	Pointer to the absolute path of the local or online audio file to mix. Supported audio formats: 3GP, ASF, ADTS, AVI, MP3, MPEG-4, SAMI, and WAVE. For more information, see Supported Media Formats in Media Foundation.
loopback	Sets which user can hear the audio mixing: true: Only the local user can hear the audio mixing. false: Both users can hear the audio mixing.
replace	Sets the audio mixing content: true: Only the specified audio file is published; the audio stream received by the microphone is not published. false: The local audio file is mixed with the audio stream from the microphone.
cycle	Sets the number of playback loops: Positive integer: Number of playback loops. -1: Infinite playback loops.

Returns

• 0: Success.
• < 0: Failure.

Stops playing and mixing the music file.

Call this method when you are in a channel.

Returns

• 0: Success.
• < 0: Failure.

Pauses playing and mixing the music file.

Call this method when you are in a channel.

Returns

• 0: Success.
• < 0: Failure.

Resumes playing and mixing the music file.

Call this method when you are in a channel.

Returns

• 0: Success.
• < 0: Failure.

Adjusts the volume during audio mixing.

Call this method when you are in a channel.

Parameters

volume

Audio mixing volume. The value ranges between 0 and 100 (default).

Returns

• 0: Success.
• < 0: Failure.

Retrieves the duration (ms) of the music file.

Call this method when you are in a channel.

Returns

• ≥ 0: The audio mixing duration, if this method call succeeds.
• < 0: Failure.

Retrieves the playback position (ms) of the music file.

Call this method when you are in a channel.

Returns

• ≥ 0: The current playback position of the audio mixing, if this method call succeeds.
• < 0: Failure.

Sets the playback position of the music file to a different start position (the default plays from the beginning).

Parameters

pos	The playback start position (ms) of the music file.

Returns

• 0: Success.
• < 0: Failure.

Retrieves the volume of the audio effects.

The value ranges between 0.0 and 100.0.

Returns

• ≥ 0: Volume of the audio effects, if this method call succeeds.
• < 0: Failure.

Sets the volume of the audio effects.

Parameters

volume

Sets the volume of the audio effects. The value ranges between 0.0 and 100.0 (default).

Returns

• 0: Success.
• < 0: Failure.

Sets the volume of a specified audio effect.

Parameters

soundId	ID of the audio effect. Each audio effect has a unique ID.
volume	Sets the volume of the specified audio effect. The value ranges between 0.0 and 100.0 (default).

Returns

• 0: Success.
• < 0: Failure.

Plays a specified audio effect.

If this method call succeeds, the Agora SDK returns the onAudioEffectFinished callback.

Parameters

soundId

ID of the specified audio effect. Each audio effect has a unique ID.

Note

If the audio effect is preloaded into the memory through the preloadEffect method, the value of soundID must be the same as that in the preloadEffect method.

Parameters

filePath	Pointer to the absolute path of the audio effect file.
loopCount	Sets the number of times the audio effect loops: 0: Play the audio effect once. 1: Play the audio effect twice. -1: Play the audio effect in an indefinite loop until the stopEffect or stopAllEffects method is called.
pitch	Sets the pitch of the audio effect. The value ranges between 0.5 and 2. The default value is 1 (no change to the pitch). The lower the value, the lower the pitch.
pan	Sets the spatial position of the audio effect. The value ranges between -1.0 and 1.0: 0.0: The audio effect displays ahead. 1.0: The audio effect displays to the right. -1.0: The audio effect displays to the left.
gain	Sets the volume of the audio effect. The value ranges between 0.0 and 100.0 (default). The lower the value, the lower the volume of the audio effect.
publish	Sets whether or not to publish the specified audio effect to the remote stream: true: The locally played audio effect is published to the Agora Cloud and the remote users can hear it. false: The locally played audio effect is not published to the Agora Cloud and the remote users cannot hear it.

Returns

• 0: Success.
• < 0: Failure.

Stops playing a specified audio effect.

Parameters

soundId

ID of the audio effect to stop playing. Each audio effect has a unique ID.

Returns

• 0: Success.
• < 0: Failure.

Stops playing all audio effects.

Returns

• 0: Success.
• < 0: Failure.

Preloads a specified audio effect file into the memory.

To ensure smooth communication, limit the size of the audio effect file. Agora recommends using this method to preload the audio effect before calling the joinChannel method.

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

Parameters

soundId	ID of the audio effect. Each audio effect has a unique ID.
filePath	Pointer to the absolute path of the audio effect file.

Returns

• 0: Success.
• < 0: Failure.

Releases a specified preloaded audio effect from the memory.

Parameters

soundId

ID of the audio effect. Each audio effect has a unique ID.

Returns

• 0: Success.
• < 0: Failure.

Pauses a specified audio effect.

Parameters

soundId

ID of the audio effect. Each audio effect has a unique ID.

Returns

• 0: Success.
• < 0: Failure.

Pauses all audio effects.

Returns

• 0: Success.
• < 0: Failure.

Resumes playing a specified audio effect.

Parameters

soundId

ID of the audio effect. Each audio effect has a unique ID.

Returns

• 0: Success.
• < 0: Failure.

Resumes playing all audio effects.

Returns

• 0: Success.
• < 0: Failure.

Changes the voice pitch of the local speaker.

Parameters

pitch

Sets the voice pitch. The value ranges between 0.5 and 2.0. The lower the value, the lower the voice pitch. The default value is 1.0 (no change to the local voice pitch).

Returns

• 0: Success.
• < 0: Failure.

Sets the local voice equalization effect.

Parameters

bandFrequency	Sets 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. See AUDIO_EQUALIZATION_BAND_FREQUENCY.
bandGain	Sets the gain of each band in dB. The value ranges between -15 and 15.

Returns

• 0: Success.
• < 0: Failure.

Sets the local voice reverberation.

Parameters

reverbKey	Sets the reverberation key. See AUDIO_REVERB_TYPE.
value	Sets the value of the reverberation key.

Returns

• 0: Success.
• < 0: Failure.

Deprecated:

Use the disableAudio method instead. Disables the audio function in the channel.

Returns

• 0: Success.
• < 0: Failure.

Deprecated:

Use the enableAudio method instead.

Resumes playing the audio in the channel.

Returns

• 0: Success.
• < 0: Failure.

Deprecated:

Agora does not recommend using this method.

Sets the high-quality audio preferences. Call this method and set all parameters before joining a channel.

Do not call this method again after joining a channel.

Parameters

fullband	Sets whether to enable/disable full-band codec (48-kHz sampling rate). Not compatible with SDK versions before v1.7.4: true: Enable full-band codec. false: Disable full-band codec.
stereo	Sets whether to enable/disable stereo codec. Not compatible with SDK versions before v1.7.4: true: Enable stereo codec. false: Disable stereo codec.
fullBitrate	Sets whether to enable/disable high-bitrate mode. Recommended in voice-only mode: true: Enable high-bitrate mode. false: Disable high-bitrate mode.

Returns

• 0: Success.
• < 0: Failure.

Adjusts the recording volume.

Parameters

volume

Recording volume. The value ranges between 0 and 400: 0: Mute. 100: Original volume. 400: (Maximum) Four times the original volume with signal clipping protection.

Returns

• 0: Success.
• < 0: Failure.

Adjusts the playback volume.

Parameters

volume

Playback volume. The value ranges between 0 and 400: 0: Mute. 100: Original volume. 400: (Maximum) Four times the original volume with signal clipping protection.

Returns

• 0: Success.
• < 0: Failure.

Enables the onAudioVolumeIndication callback at a set time interval to report on which user is speaking and the speaker's volume.

Once this method is enabled, the SDK returns the volume indication in the onAudioVolumeIndication callback at the set time interval, regardless of whether any user is speaking in the channel.

Parameters

interval	Sets the time interval between two consecutive volume indications: ≤ 0: Disables the volume indication. > 0: Time interval (ms) between two consecutive volume indications. Agora recommends setting interval > 200 ms. Do not set interval < 10 ms, or the onAudioVolumeIndication callback will not be triggered.
smooth	Smoothing factor sets the sensitivity of the audio volume indicator. The value ranges between 0 and 10. The greater the value, the more sensitive the indicator. The recommended value is 3.

Returns

• 0: Success.
• < 0: Failure.

Stops sending/Re-sends the local audio stream.

Note

When mute is set as true, this method does not disable the microphone, which does not affect any ongoing recording.

Parameters

mute	Sets whether to send/stop sending the local audio stream: true: Stops sending the local audio stream. false: (Default) Sends the local audio stream.

Returns

• 0: Success.
• < 0: Failure.

Stops receiving a specified remote user’s audio stream.

Note

If you called the muteAllRemoteAudioStreams method and set mute as true to stop receiving all remote users' audio streams, call the muteAllRemoteAudioStreams method and set mute as false before calling this method. The muteAllRemoteAudioStreams method sets all remote audio streams, while the muteRemoteAudioStream method sets a specified remote audio stream.

Parameters

uid	User ID of the specified remote user sending the audio.
mute	Sets whether to receive/stop receiving a specified remote user’s audio stream: true: Stops receiving the specified remote user’s audio stream. false: (Default) Receives the specified remote user’s audio stream.

Returns

• 0: Success.
• < 0: Failure.

Stops receiving all remote users' audio streams.

Parameters

mute	Sets whether to receive/stop receiving all remote users' audio streams. true: Stops receiving all remote users' audio streams. false: (Default) Receives all remote users' audio streams.

Returns

• 0: Success.
• < 0: Failure.

Stops receiving all remote users' audio streams by default.

Parameters

mute	Sets whether to receive/stop receiving all remote users' audio streams by default: true: Stops receiving all remote users' audio streams by default. false: (Default) Receives all remote users' audio streams by default.

Returns

• 0: Success.
• < 0: Failure.

Sets the external audio source.

Parameters

enabled	Sets whether to enable/disable the external audio source: true: Enables the external audio source. false: (Default) Disables the external audio source.
sampleRate	Sets the sampling rate of the external audio source, which can set be as 8000, 16000, 32000, 44100, or 48000.
channels	Sets the audio channels of the external audio source (two channels maximum).

Returns

• 0: Success.
• < 0: Failure.

Specifies an SDK output log file.

The log file records all log data for the SDK’s operation. Ensure that the directory for the log file exists and is writable.

Note

The default log file is located at: "C:\Users\<user_name>\AppData\Local\Agora\<process_name>".

Parameters

filePath

File path of the log file. The string of the log file is in the UTF-8 code.

Returns

• 0: Success.
• < 0: Failure.

Sets the output log level of the SDK.

You can use one or a combination of the log filter levels. The log level follows the sequence of OFF, CRITICAL, ERROR, WARNING, INFO, and DEBUG. Choose a level to see the logs preceding that level.

For example, if you set the log level to WARNING, you see the logs within levels CRITICAL, ERROR, and WARNING.

Parameters

filter

Sets the log filter level. See LOG_FILTER_TYPE.

Returns

• 0: Success.
• < 0: Failure.

Sets the local video display mode.

This method may be invoked multiple times during a call to change the display mode.

Parameters

renderMode

Sets the local video display mode. See RENDER_MODE_TYPE.

Returns

• 0: Success.
• < 0: Failure.

Sets the video display mode of a specified remote user.

This method can be invoked multiple times during a call to change the display mode.

Parameters

uid	ID of the remote user.
renderMode	Sets the video display mode. See RENDER_MODE_TYPE.

Returns

• 0: Success.
• < 0: Failure.

Sets the stream mode to the single-stream (default) or dual-stream mode. (Live broadcast only.)

If the dual-stream mode is enabled, the receiver can choose to receive the high stream (high-resolution and high-bitrate video stream), or the low stream (low-resolution and low-bitrate video stream).

Parameters

enabled

Sets the stream mode: true: Dual-stream mode. false: (Default) Single-stream mode.

Sets the remote user’s video stream type received by the local user when the remote user sends dual streams.

This method allows the application to adjust the corresponding video-stream type based on the size of the video window to reduce the bandwidth and resources.

• If the remote user enables the dual-stream mode by calling the enableDualStreamMode method, the SDK receives the high-stream video by default.
• If the dual-stream mode is not enabled, the SDK receives the high-stream video by default.

The method result returns in the onApiCallExecuted callback. The Agora SDK receives the high-stream video by default to reduce the bandwidth. If needed, users may use this method to switch to the low-stream video. By default, the aspect ratio of the low-stream video is the same as the high-stream video. Once the resolution of the high-stream video is set, the system automatically sets the resolution, frame rate, and bitrate of the low-stream video.

Parameters

uid	ID of the remote user sending the video stream.
streamType	Sets the video-stream type. See REMOTE_VIDEO_STREAM_TYPE.

Returns

• 0: Success.
• < 0: Failure.

Sets the default video-stream type for the video received by the local user when the remote user sends dual streams.

• If the dual-stream mode is enabled by calling the enableDualStreamMode method, the user receives the high-stream video by default. The setRemoteDefaultVideoStreamType method allows the application to adjust the corresponding video-stream type according to the size of the video window, reducing the bandwidth and resources.
• If the dual-stream mode is not enabled, the user receives the high-stream video by default.

The result after calling this method is returned in the onApiCallExecuted callback. The Agora SDK receives the high-stream video by default to reduce the bandwidth. If needed, users can switch to the low-stream video through this method.

Parameters

streamType

Sets the default video-stream type. See REMOTE_VIDEO_STREAM_TYPE.

Returns

• 0: Success.
• < 0: Failure.

Sets the audio recording format for the onRecordAudioFrame callback.

Parameters

sampleRate	Sets the sampling rate (samplesPerSec) returned in the onRecordAudioFrame callback, which can set be as 8000, 16000, 32000, 44100, or 48000.
channel	Sets the number of audio channels (channels) returned in the onRecordAudioFrame callback: 1: Mono 2: Stereo
mode	Sets the use mode (see RAW_AUDIO_FRAME_OP_MODE_TYPE) of the onRecordAudioFrame callback.
samplesPerCall	Sets the sample points (samples) returned in the onRecordAudioFrame callback. samplesPerCall is usually set as 1024 for stream pushing.

samplesPerCall = (int)(sampleRate × sampleInterval), where sampleInterval ≥ 0.01 in seconds.

Returns

• 0: Success.
• < 0: Failure.

Sets the audio playback format for the onPlaybackAudioFrame callback.

Parameters

sampleRate	Sets the sampling rate (samplesPerSec) returned in the onPlaybackAudioFrame callback, which can set be as 8000, 16000, 32000, 44100, or 48000.
channel	Sets the number of channels (channels) returned in the onPlaybackAudioFrame callback: 1: Mono 2: Stereo
mode	Sets the use mode (see RAW_AUDIO_FRAME_OP_MODE_TYPE) of the onPlaybackAudioFrame callback.
samplesPerCall	Sets the sample points (samples) returned in the onPlaybackAudioFrame callback. samplesPerCall is usually set as 1024 for stream pushing.

samplesPerCall = (int)(sampleRate × sampleInterval), where sampleInterval ≥ 0.01 in seconds.

Returns

• 0: Success.
• < 0: Failure.

Sets the mixed audio format for the onMixedAudioFrame callback.

Parameters

sampleRate	Sets the sampling rate (samplesPerSec) returned in the onMixedAudioFrame callback, which can set be as 8000, 16000, 32000, 44100, or 48000.
samplesPerCall	Sets the sample points (samples) returned in the onMixedAudioFrame callback. samplesPerCall is usually set as 1024 for stream pushing.

samplesPerCall = (int)(sampleRate × sampleInterval), where sampleInterval ≥ 0.01 in seconds.

Returns

• 0: Success.
• < 0: Failure.

Enables interoperability with the Agora Web SDK.

Note

This method applies only to the live broadcast profile. In the communication profile, interoperability with the Agora Web SDK is enabled by default.

Parameters

enabled

Sets whether to enable/disable interoperability with the Agora Web SDK: true: Enable. false: (Default) Disable.

Returns

• 0: Success.
• < 0: Failure.

Sets the preferences for the high-quality video. (Live broadcast only).

Parameters

preferFrameRateOverImageQuality

Sets the video quality preference: true: Frame rate over image quality. false: (Default) Image quality over frame rate.

Returns

• 0: Success.
• < 0: Failure.

Sets the local video mirror mode.

You must call this method before calling the startPreview method, else the mirror mode will not work.

Parameters

mirrorMode

Sets the local video mirror mode. See VIDEO_MIRROR_MODE_TYPE.

Returns

• 0: Success.
• < 0: Failure.

Sets the fallback option for the locally published video stream based on the network conditions.

The default setting for option is STREAM_FALLBACK_OPTION_DISABLED, where there is no fallback for the locally published video stream when the uplink network conditions are poor.

If option is set to STREAM_FALLBACK_OPTION_AUDIO_ONLY, the SDK will:

• Disable the upstream video but enable audio only when the network conditions deteriorate and cannot support both video and audio.
• Re-enable the video when the network conditions improve.

When the locally published stream falls back to audio only or when the audio stream switches back to the video, the onLocalPublishFallbackToAudioOnly callback is triggered.

Note

Agora does not recommend using this method for CDN live streaming, because the remote CDN live user will have a noticeable lag when the locally publish stream falls back to audio-only.

Parameters

option

Sets the fallback option for the locally published video stream. See STREAM_FALLBACK_OPTIONS.

Returns

• 0: Success.
• < 0: Failure.

Sets the fallback option for the remotely subscribed stream based on the network conditions.

The default setting for option is STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW, where the remotely subscribed stream falls back to the low-stream video (low resolution and low bitrate) under poor downlink network conditions.

If option is set to STREAM_FALLBACK_OPTION_AUDIO_ONLY, the SDK automatically switches the video from a high-stream to a low-stream, or disable the video when the downlink network conditions cannot support both audio and video to guarantee the quality of the audio. The SDK monitors the network quality and restores the video stream when the network conditions improve.

Once the locally published stream falls back to audio only or the audio stream switches back to the video stream, the onRemoteSubscribeFallbackToAudioOnly callback is triggered.

Parameters

option

Sets the fallback option for the remotely subscribed stream. See STREAM_FALLBACK_OPTIONS.

Returns

• 0: Success.
• < 0: Failure.

Enables loopback recording.

Parameters

enabled	Sets whether to enable/disable loopback recording: true: Enables loopback recording. false: (Default) Disables loopback recording.
deviceName	Pointer to the device name of the sound card. The default value is NULL, meaning the default sound card is used. If you are using a virtual sound card like "Soundflower", set this parameter as the name of the sound card, like "Soundflower", and the SDK will find the corresponding sound card and start capturing.

Returns

• 0: Success.
• < 0: Failure.

Sets the volume of the in-ear monitor.

Parameters

volume

Sets the volume of the in-ear monitor. The value ranges between 0 and 100 (default).

Returns

• 0: Success.
• < 0: Failure.