Public Member Functions

 RtcEngineParameters (IRtcEngine &engine)
 
 RtcEngineParameters (IRtcEngine *engine)
 
int enableLocalVideo (bool enabled)
 
int muteLocalVideoStream (bool mute)
 
int muteAllRemoteVideoStreams (bool mute)
 
int setDefaultMuteAllRemoteVideoStreams (bool mute)
 
int muteRemoteVideoStream (uid_t uid, bool mute)
 
int setPlaybackDeviceVolume (int volume)
 
int startAudioRecording (const char *filePath, AUDIO_RECORDING_QUALITY_TYPE quality)
 
int stopAudioRecording ()
 
int startAudioMixing (const char *filePath, bool loopback, bool replace, int cycle)
 
int stopAudioMixing ()
 
int pauseAudioMixing ()
 
int resumeAudioMixing ()
 
int adjustAudioMixingVolume (int volume)
 
int adjustAudioMixingPlayoutVolume (int volume)
 
int adjustAudioMixingPublishVolume (int volume)
 
int getAudioMixingDuration ()
 
int getAudioMixingCurrentPosition ()
 
int setAudioMixingPosition (int pos)
 
int getEffectsVolume ()
 
int setEffectsVolume (int volume)
 
int setVolumeOfEffect (int soundId, int volume)
 
int playEffect (int soundId, const char *filePath, int loopCount, double pitch, double pan, int gain, bool publish=false)
 
int stopEffect (int soundId)
 
int stopAllEffects ()
 
int preloadEffect (int soundId, char *filePath)
 
int unloadEffect (int soundId)
 
int pauseEffect (int soundId)
 
int pauseAllEffects ()
 
int resumeEffect (int soundId)
 
int resumeAllEffects ()
 
int setLocalVoicePitch (double pitch)
 
int setLocalVoiceEqualization (AUDIO_EQUALIZATION_BAND_FREQUENCY bandFrequency, int bandGain)
 
int setLocalVoiceReverb (AUDIO_REVERB_TYPE reverbKey, int value)
 
int pauseAudio ()
 
int resumeAudio ()
 
int setHighQualityAudioParameters (bool fullband, bool stereo, bool fullBitrate)
 
int adjustRecordingSignalVolume (int volume)
 
int adjustPlaybackSignalVolume (int volume)
 
int enableAudioVolumeIndication (int interval, int smooth)
 
int muteLocalAudioStream (bool mute)
 
int muteRemoteAudioStream (uid_t uid, bool mute)
 
int muteAllRemoteAudioStreams (bool mute)
 
int setDefaultMuteAllRemoteAudioStreams (bool mute)
 
int setExternalAudioSource (bool enabled, int sampleRate, int channels)
 
int setExternalAudioSink (bool enabled, int sampleRate, int channels)
 
int setLogFile (const char *filePath)
 
int setLogFilter (unsigned int filter)
 
int setLocalRenderMode (RENDER_MODE_TYPE renderMode)
 
int setRemoteRenderMode (uid_t uid, RENDER_MODE_TYPE renderMode)
 
int enableDualStreamMode (bool enabled)
 
int setRemoteVideoStreamType (uid_t uid, REMOTE_VIDEO_STREAM_TYPE streamType)
 
int setRemoteDefaultVideoStreamType (REMOTE_VIDEO_STREAM_TYPE streamType)
 
int setRecordingAudioFrameParameters (int sampleRate, int channel, RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall)
 
int setPlaybackAudioFrameParameters (int sampleRate, int channel, RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall)
 
int setMixedAudioFrameParameters (int sampleRate, int samplesPerCall)
 
int enableWebSdkInteroperability (bool enabled)
 
int setVideoQualityParameters (bool preferFrameRateOverImageQuality)
 
int setLocalVideoMirrorMode (VIDEO_MIRROR_MODE_TYPE mirrorMode)
 
int setLocalPublishFallbackOption (STREAM_FALLBACK_OPTIONS option)
 
int setRemoteSubscribeFallbackOption (STREAM_FALLBACK_OPTIONS option)
 
int enableLoopbackRecording (bool enabled, const char *deviceName=NULL)
 
int setInEarMonitoringVolume (int volume)
 

Protected Member Functions

AParameterparameter ()
 
int setParameters (const char *format,...)
 
int setObject (const char *key, const char *format,...)
 
int stopAllRemoteVideo ()
 

Detailed Description

The RtcEngineParameters class is an auxiliary class setting parameters for the SDK.

Constructor & Destructor Documentation

◆ RtcEngineParameters() [1/2]

agora::rtc::RtcEngineParameters::RtcEngineParameters ( IRtcEngine engine)
inline

◆ RtcEngineParameters() [2/2]

agora::rtc::RtcEngineParameters::RtcEngineParameters ( IRtcEngine engine)
inline

Member Function Documentation

◆ enableLocalVideo()

int agora::rtc::RtcEngineParameters::enableLocalVideo ( bool  enabled)
inline

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
enabledSets 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.

◆ muteLocalVideoStream()

int agora::rtc::RtcEngineParameters::muteLocalVideoStream ( bool  mute)
inline

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
muteSets 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.

◆ muteAllRemoteVideoStreams()

int agora::rtc::RtcEngineParameters::muteAllRemoteVideoStreams ( bool  mute)
inline

Stops receiving all remote users’ video streams.

Parameters
muteSets 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.

◆ setDefaultMuteAllRemoteVideoStreams()

int agora::rtc::RtcEngineParameters::setDefaultMuteAllRemoteVideoStreams ( bool  mute)
inline

Stops receiving all remote users' video streams by default.

Parameters
muteSets 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.

◆ muteRemoteVideoStream()

int agora::rtc::RtcEngineParameters::muteRemoteVideoStream ( uid_t  uid,
bool  mute 
)
inline

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
uidUser ID of the specified remote user.
muteSets 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.

◆ setPlaybackDeviceVolume()

int agora::rtc::RtcEngineParameters::setPlaybackDeviceVolume ( int  volume)
inline
Deprecated:
Use setPlaybackDeviceVolume instead. Sets the playback device volume.
Parameters
volumeSets the volume of the playback device. The value ranges between 0 and 255.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startAudioRecording()

int agora::rtc::RtcEngineParameters::startAudioRecording ( const char *  filePath,
AUDIO_RECORDING_QUALITY_TYPE  quality 
)
inline

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
filePathPointer to the absolute file path of the recording file. The string of the file name is in UTF-8.
qualitySets the audio recording quality. See AUDIO_RECORDING_QUALITY_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopAudioRecording()

int agora::rtc::RtcEngineParameters::stopAudioRecording ( )
inline

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.

◆ startAudioMixing()

int agora::rtc::RtcEngineParameters::startAudioMixing ( const char *  filePath,
bool  loopback,
bool  replace,
int  cycle 
)
inline

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 SDK triggers the onAudioMixingFinished callback.

Note
Call this method when you are in a channel.
Parameters
filePathPointer 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.
loopbackSets 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.
replaceSets 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.
cycleSets the number of playback loops:
  • Positive integer: Number of playback loops.
  • -1: Infinite playback loops.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopAudioMixing()

int agora::rtc::RtcEngineParameters::stopAudioMixing ( )
inline

Stops playing and mixing the music file.

Call this method when you are in a channel.

Returns
  • 0: Success.
  • < 0: Failure.

◆ pauseAudioMixing()

int agora::rtc::RtcEngineParameters::pauseAudioMixing ( )
inline

Pauses playing and mixing the music file.

Call this method when you are in a channel.

Returns
  • 0: Success.
  • < 0: Failure.

◆ resumeAudioMixing()

int agora::rtc::RtcEngineParameters::resumeAudioMixing ( )
inline

Resumes playing and mixing the music file.

Call this method when you are in a channel.

Returns
  • 0: Success.
  • < 0: Failure.

◆ adjustAudioMixingVolume()

int agora::rtc::RtcEngineParameters::adjustAudioMixingVolume ( int  volume)
inline

Adjusts the volume during audio mixing.

Call this method when you are in a channel.

Parameters
volumeAudio mixing volume. The value ranges between 0 and 100 (default).
Returns
  • 0: Success.
  • < 0: Failure.

◆ adjustAudioMixingPlayoutVolume()

int agora::rtc::RtcEngineParameters::adjustAudioMixingPlayoutVolume ( int  volume)
inline

Adjusts the audio mixing volume for local playback.

Note
Call this method when you are in a channel.
Parameters
volumeAudio mixing volume for local playback. The value ranges between 0 and 100 (default).
Returns
  • 0: Success.
  • < 0: Failure.

◆ adjustAudioMixingPublishVolume()

int agora::rtc::RtcEngineParameters::adjustAudioMixingPublishVolume ( int  volume)
inline

Adjusts the audio mixing volume for publishing (for remote users).

Note
Call this method when you are in a channel.
Parameters
volumeAudio mixing volume for publishing. The value ranges between 0 and 100 (default).
Returns
  • 0: Success.
  • < 0: Failure.

◆ getAudioMixingDuration()

int agora::rtc::RtcEngineParameters::getAudioMixingDuration ( )
inline

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.

◆ getAudioMixingCurrentPosition()

int agora::rtc::RtcEngineParameters::getAudioMixingCurrentPosition ( )
inline

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.

◆ setAudioMixingPosition()

int agora::rtc::RtcEngineParameters::setAudioMixingPosition ( int  pos)
inline

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

Parameters
posThe playback starting position (ms) of the music file.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getEffectsVolume()

int agora::rtc::RtcEngineParameters::getEffectsVolume ( )
inline

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.

◆ setEffectsVolume()

int agora::rtc::RtcEngineParameters::setEffectsVolume ( int  volume)
inline

Sets the volume of the audio effects.

Parameters
volumeSets the volume of the audio effects. The value ranges between 0.0 and 100.0 (default).
Returns
  • 0: Success.
  • < 0: Failure.

◆ setVolumeOfEffect()

int agora::rtc::RtcEngineParameters::setVolumeOfEffect ( int  soundId,
int  volume 
)
inline

Sets the volume of a specified audio effect.

Parameters
soundIdID of the audio effect. Each audio effect has a unique ID.
volumeSets the volume of the specified audio effect. The value ranges between 0.0 and 100.0 (default).
Returns
  • 0: Success.
  • < 0: Failure.

◆ playEffect()

int agora::rtc::RtcEngineParameters::playEffect ( int  soundId,
const char *  filePath,
int  loopCount,
double  pitch,
double  pan,
int  gain,
bool  publish = false 
)
inline

Plays a specified audio effect.

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

Parameters
soundIdID 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
filePathPointer to the absolute path of the audio effect file.
loopCountSets 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.
pitchSets 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.
panSets 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.
gainSets 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.
publishSets 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.

◆ stopEffect()

int agora::rtc::RtcEngineParameters::stopEffect ( int  soundId)
inline

Stops playing a specified audio effect.

Parameters
soundIdID of the audio effect to stop playing. Each audio effect has a unique ID.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopAllEffects()

int agora::rtc::RtcEngineParameters::stopAllEffects ( )
inline

Stops playing all audio effects.

Returns
  • 0: Success.
  • < 0: Failure.

◆ preloadEffect()

int agora::rtc::RtcEngineParameters::preloadEffect ( int  soundId,
char *  filePath 
)
inline

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
soundIdID of the audio effect. Each audio effect has a unique ID.
filePathPointer to the absolute path of the audio effect file.
Returns
  • 0: Success.
  • < 0: Failure.

◆ unloadEffect()

int agora::rtc::RtcEngineParameters::unloadEffect ( int  soundId)
inline

Releases a specified preloaded audio effect from the memory.

Parameters
soundIdID of the audio effect. Each audio effect has a unique ID.
Returns
  • 0: Success.
  • < 0: Failure.

◆ pauseEffect()

int agora::rtc::RtcEngineParameters::pauseEffect ( int  soundId)
inline

Pauses a specified audio effect.

Parameters
soundIdID of the audio effect. Each audio effect has a unique ID.
Returns
  • 0: Success.
  • < 0: Failure.

◆ pauseAllEffects()

int agora::rtc::RtcEngineParameters::pauseAllEffects ( )
inline

Pauses all audio effects.

Returns
  • 0: Success.
  • < 0: Failure.

◆ resumeEffect()

int agora::rtc::RtcEngineParameters::resumeEffect ( int  soundId)
inline

Resumes playing a specified audio effect.

Parameters
soundIdID of the audio effect. Each audio effect has a unique ID.
Returns
  • 0: Success.
  • < 0: Failure.

◆ resumeAllEffects()

int agora::rtc::RtcEngineParameters::resumeAllEffects ( )
inline

Resumes playing all audio effects.

Returns
  • 0: Success.
  • < 0: Failure.

◆ setLocalVoicePitch()

int agora::rtc::RtcEngineParameters::setLocalVoicePitch ( double  pitch)
inline

Changes the voice pitch of the local speaker.

Parameters
pitchSets 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.

◆ setLocalVoiceEqualization()

int agora::rtc::RtcEngineParameters::setLocalVoiceEqualization ( AUDIO_EQUALIZATION_BAND_FREQUENCY  bandFrequency,
int  bandGain 
)
inline

Sets the local voice equalization effect.

Parameters
bandFrequencySets 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.
bandGainSets the gain of each band in dB. The value ranges between -15 and 15.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLocalVoiceReverb()

int agora::rtc::RtcEngineParameters::setLocalVoiceReverb ( AUDIO_REVERB_TYPE  reverbKey,
int  value 
)
inline

Sets the local voice reverberation.

Parameters
reverbKeySets the reverberation key. See AUDIO_REVERB_TYPE.
valueSets the value of the reverberation key.
Returns
  • 0: Success.
  • < 0: Failure.

◆ pauseAudio()

int agora::rtc::RtcEngineParameters::pauseAudio ( )
inline
Deprecated:
Use the disableAudio method instead. Disables the audio function in the channel.
Returns
  • 0: Success.
  • < 0: Failure.

◆ resumeAudio()

int agora::rtc::RtcEngineParameters::resumeAudio ( )
inline
Deprecated:
Use the enableAudio method instead.

Resumes playing the audio in the channel.

Returns
  • 0: Success.
  • < 0: Failure.

◆ setHighQualityAudioParameters()

int agora::rtc::RtcEngineParameters::setHighQualityAudioParameters ( bool  fullband,
bool  stereo,
bool  fullBitrate 
)
inline
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
fullbandSets 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.
stereoSets whether to enable/disable stereo codec. Not compatible with SDK versions before v1.7.4:
  • true: Enable stereo codec.
  • false: Disable stereo codec.
fullBitrateSets 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.

◆ adjustRecordingSignalVolume()

int agora::rtc::RtcEngineParameters::adjustRecordingSignalVolume ( int  volume)
inline

Adjusts the recording volume.

Parameters
volumeRecording 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.

◆ adjustPlaybackSignalVolume()

int agora::rtc::RtcEngineParameters::adjustPlaybackSignalVolume ( int  volume)
inline

Adjusts the playback volume.

Parameters
volumePlayback 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.

◆ enableAudioVolumeIndication()

int agora::rtc::RtcEngineParameters::enableAudioVolumeIndication ( int  interval,
int  smooth 
)
inline

Enables the onAudioVolumeIndication callback at a set time interval to report on which users are speaking and the speakers' 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
intervalSets 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.
smoothSmoothing 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.

◆ muteLocalAudioStream()

int agora::rtc::RtcEngineParameters::muteLocalAudioStream ( bool  mute)
inline

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
muteSets 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.

◆ muteRemoteAudioStream()

int agora::rtc::RtcEngineParameters::muteRemoteAudioStream ( uid_t  uid,
bool  mute 
)
inline

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
uidUser ID of the specified remote user sending the audio.
muteSets 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.

◆ muteAllRemoteAudioStreams()

int agora::rtc::RtcEngineParameters::muteAllRemoteAudioStreams ( bool  mute)
inline

Stops receiving all remote users' audio streams.

Parameters
muteSets 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.

◆ setDefaultMuteAllRemoteAudioStreams()

int agora::rtc::RtcEngineParameters::setDefaultMuteAllRemoteAudioStreams ( bool  mute)
inline

Stops receiving all remote users' audio streams by default.

Parameters
muteSets 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.

◆ setExternalAudioSource()

int agora::rtc::RtcEngineParameters::setExternalAudioSource ( bool  enabled,
int  sampleRate,
int  channels 
)
inline

Sets the external audio source.

Parameters
enabledSets whether to enable/disable the external audio source:
  • true: Enables the external audio source.
  • false: (Default) Disables the external audio source.
sampleRateSets the sample rate of the external audio source, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
channelsSets the audio channels of the external audio source (two channels maximum).
Returns
  • 0: Success.
  • < 0: Failure.

◆ setExternalAudioSink()

int agora::rtc::RtcEngineParameters::setExternalAudioSink ( bool  enabled,
int  sampleRate,
int  channels 
)
inline

Sets the external audio sink.

If you enable the external audio sink, you can pull the audio frame by periodically calling the pullAudioFrame method.

Parameters
enabled
  • true: Enables the external audio sink.
  • false: Disables the external audio sink.
sampleRateSets the sampling rate for the external audio sink, which can be set as 8000, 16000, 32000, 44100, or 48000.
channelsSets the audio channels of the external audio sink (two channels maximum).
Note
Enabling the external audio sink disables the "Raw Audio Data" method, and the application will not retrieve the audio frame from the onPlaybackAudioFrame callback.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLogFile()

int agora::rtc::RtcEngineParameters::setLogFile ( const char *  filePath)
inline

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
filePathFile path of the log file. The string of the log file is in the UTF-8 code.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLogFilter()

int agora::rtc::RtcEngineParameters::setLogFilter ( unsigned int  filter)
inline

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
filterSets the log filter level. See LOG_FILTER_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLocalRenderMode()

int agora::rtc::RtcEngineParameters::setLocalRenderMode ( RENDER_MODE_TYPE  renderMode)
inline

Sets the local video display mode.

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

Parameters
renderModeSets the local video display mode. See RENDER_MODE_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteRenderMode()

int agora::rtc::RtcEngineParameters::setRemoteRenderMode ( uid_t  uid,
RENDER_MODE_TYPE  renderMode 
)
inline

Sets the video display mode of a specified remote user.

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

Parameters
uidID of the remote user.
renderModeSets the video display mode. See RENDER_MODE_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableDualStreamMode()

int agora::rtc::RtcEngineParameters::enableDualStreamMode ( bool  enabled)
inline

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
enabledSets the stream mode:
  • true: Dual-stream mode.
  • false: (Default) Single-stream mode.

◆ setRemoteVideoStreamType()

int agora::rtc::RtcEngineParameters::setRemoteVideoStreamType ( uid_t  uid,
REMOTE_VIDEO_STREAM_TYPE  streamType 
)
inline

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
uidID of the remote user sending the video stream.
streamTypeSets the video-stream type. See REMOTE_VIDEO_STREAM_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteDefaultVideoStreamType()

int agora::rtc::RtcEngineParameters::setRemoteDefaultVideoStreamType ( REMOTE_VIDEO_STREAM_TYPE  streamType)
inline

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
streamTypeSets the default video-stream type. See REMOTE_VIDEO_STREAM_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRecordingAudioFrameParameters()

int agora::rtc::RtcEngineParameters::setRecordingAudioFrameParameters ( int  sampleRate,
int  channel,
RAW_AUDIO_FRAME_OP_MODE_TYPE  mode,
int  samplesPerCall 
)
inline

Sets the audio recording format for the onRecordAudioFrame callback.

Parameters
sampleRateSets the sample rate (samplesPerSec) returned in the onRecordAudioFrame callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
channelSets the number of audio channels (channels) returned in the onRecordAudioFrame callback:
  • 1: Mono
  • 2: Stereo
modeSets the use mode (see RAW_AUDIO_FRAME_OP_MODE_TYPE) of the onRecordAudioFrame callback.
samplesPerCallSets 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.

◆ setPlaybackAudioFrameParameters()

int agora::rtc::RtcEngineParameters::setPlaybackAudioFrameParameters ( int  sampleRate,
int  channel,
RAW_AUDIO_FRAME_OP_MODE_TYPE  mode,
int  samplesPerCall 
)
inline

Sets the audio playback format for the onPlaybackAudioFrame callback.

Parameters
sampleRateSets the sample rate (samplesPerSec) returned in the onPlaybackAudioFrame callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
channelSets the number of channels (channels) returned in the onPlaybackAudioFrame callback:
  • 1: Mono
  • 2: Stereo
modeSets the use mode (see RAW_AUDIO_FRAME_OP_MODE_TYPE) of the onPlaybackAudioFrame callback.
samplesPerCallSets 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.

◆ setMixedAudioFrameParameters()

int agora::rtc::RtcEngineParameters::setMixedAudioFrameParameters ( int  sampleRate,
int  samplesPerCall 
)
inline

Sets the mixed audio format for the onMixedAudioFrame callback.

Parameters
sampleRateSets the sample rate (samplesPerSec) returned in the onMixedAudioFrame callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
samplesPerCallSets 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.

◆ enableWebSdkInteroperability()

int agora::rtc::RtcEngineParameters::enableWebSdkInteroperability ( bool  enabled)
inline

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
enabledSets whether to enable/disable interoperability with the Agora Web SDK:
  • true: Enable.
  • false: (Default) Disable.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setVideoQualityParameters()

int agora::rtc::RtcEngineParameters::setVideoQualityParameters ( bool  preferFrameRateOverImageQuality)
inline

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

Parameters
preferFrameRateOverImageQualitySets the video quality preference:
  • true: Frame rate over image quality.
  • false: (Default) Image quality over frame rate.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLocalVideoMirrorMode()

int agora::rtc::RtcEngineParameters::setLocalVideoMirrorMode ( VIDEO_MIRROR_MODE_TYPE  mirrorMode)
inline

Sets the local video mirror mode.

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

Parameters
mirrorModeSets the local video mirror mode. See VIDEO_MIRROR_MODE_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLocalPublishFallbackOption()

int agora::rtc::RtcEngineParameters::setLocalPublishFallbackOption ( STREAM_FALLBACK_OPTIONS  option)
inline

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 behavior for the locally published video stream when the uplink network conditions are poor.

If option is set as STREAM_FALLBACK_OPTION_AUDIO_ONLY, the SDK will:

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

When the locally published video stream falls back to audio only or when the audio-only stream switches back to the video, the SDK triggers the onLocalPublishFallbackToAudioOnly callback.

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
optionSets the fallback option for the locally published video stream. See STREAM_FALLBACK_OPTIONS.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteSubscribeFallbackOption()

int agora::rtc::RtcEngineParameters::setRemoteSubscribeFallbackOption ( STREAM_FALLBACK_OPTIONS  option)
inline

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

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

If option is set as STREAM_FALLBACK_OPTION_AUDIO_ONLY, the SDK automatically switches the video from a high-stream to a low-stream, or disables 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.

When the remotely subscribed video stream falls back to audio only or when the audio-only stream switches back to the video stream, the SDK triggers the onRemoteSubscribeFallbackToAudioOnly callback.

Parameters
optionSets the fallback option for the remotely subscribed video stream. See STREAM_FALLBACK_OPTIONS.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableLoopbackRecording()

int agora::rtc::RtcEngineParameters::enableLoopbackRecording ( bool  enabled,
const char *  deviceName = NULL 
)
inline

Enables loopback recording.

Parameters
enabledSets whether to enable/disable loopback recording:
  • true: Enables loopback recording.
  • false: (Default) Disables loopback recording.
deviceNamePointer to the device name of the sound card. The default value is NULL (the default sound card). If you use a virtual sound card like "Soundflower", set this parameter as the name of the sound card, "Soundflower", and the SDK will find the corresponding sound card and start capturing.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setInEarMonitoringVolume()

int agora::rtc::RtcEngineParameters::setInEarMonitoringVolume ( int  volume)
inline

Sets the volume of the in-ear monitor.

Parameters
volumeSets the volume of the in-ear monitor. The value ranges between 0 and 100 (default).
Returns
  • 0: Success.
  • < 0: Failure.

◆ parameter()

AParameter& agora::rtc::RtcEngineParameters::parameter ( )
inlineprotected

◆ setParameters()

int agora::rtc::RtcEngineParameters::setParameters ( const char *  format,
  ... 
)
inlineprotected

◆ setObject()

int agora::rtc::RtcEngineParameters::setObject ( const char *  key,
const char *  format,
  ... 
)
inlineprotected

◆ stopAllRemoteVideo()

int agora::rtc::RtcEngineParameters::stopAllRemoteVideo ( )
inlineprotected