Agora Java API Reference for Android
Public Member Functions | List of all members
agora::rtc::IRtcEngine Class Referenceabstract

#include <IAgoraRtcEngine.h>

Inheritance diagram for agora::rtc::IRtcEngine:
agora::base::IEngineBase agora::rtc::IRtcEngineEx

Public Member Functions

virtual void release (bool sync=false)=0
 
virtual int initialize (const RtcEngineContext &context)=0
 
virtual int queryInterface (INTERFACE_ID_TYPE iid, void **inter)=0
 
virtual const char * getVersion (int *build)=0
 
virtual const char * getErrorDescription (int code)=0
 
virtual int queryCodecCapability (CodecCapInfo *codec_info, int &size)=0
 
virtual int joinChannel (const char *token, const char *channelId, const char *info, uid_t uid)=0
 
virtual int joinChannel (const char *token, const char *channelId, uid_t uid, const ChannelMediaOptions &options)=0
 
virtual int updateChannelMediaOptions (const ChannelMediaOptions &options)=0
 
virtual int leaveChannel ()=0
 
virtual int leaveChannel (const LeaveChannelOptions &options)=0
 
virtual int renewToken (const char *token)=0
 
virtual int setChannelProfile (CHANNEL_PROFILE_TYPE profile)=0
 
virtual int setClientRole (CLIENT_ROLE_TYPE role)=0
 
virtual int setClientRole (CLIENT_ROLE_TYPE role, const ClientRoleOptions &options)=0
 
virtual int startEchoTest ()=0
 
virtual int startEchoTest (int intervalInSeconds)=0
 
virtual int startEchoTest (const EchoTestConfiguration &config)=0
 
virtual int stopEchoTest ()=0
 
virtual int enableVideo ()=0
 
virtual int disableVideo ()=0
 
virtual int startPreview ()=0
 
virtual int startPreview (VIDEO_SOURCE_TYPE sourceType)=0
 
virtual int stopPreview ()=0
 
virtual int stopPreview (VIDEO_SOURCE_TYPE sourceType)=0
 
virtual int startLastmileProbeTest (const LastmileProbeConfig &config)=0
 
virtual int stopLastmileProbeTest ()=0
 
virtual int setVideoEncoderConfiguration (const VideoEncoderConfiguration &config)=0
 
virtual int setBeautyEffectOptions (bool enabled, const BeautyOptions &options, agora::media::MEDIA_SOURCE_TYPE type=agora::media::PRIMARY_CAMERA_SOURCE)=0
 
virtual int setLowlightEnhanceOptions (bool enabled, const LowlightEnhanceOptions &options, agora::media::MEDIA_SOURCE_TYPE type=agora::media::PRIMARY_CAMERA_SOURCE)=0
 
virtual int setVideoDenoiserOptions (bool enabled, const VideoDenoiserOptions &options, agora::media::MEDIA_SOURCE_TYPE type=agora::media::PRIMARY_CAMERA_SOURCE)=0
 
virtual int setColorEnhanceOptions (bool enabled, const ColorEnhanceOptions &options, agora::media::MEDIA_SOURCE_TYPE type=agora::media::PRIMARY_CAMERA_SOURCE)=0
 
virtual int enableVirtualBackground (bool enabled, VirtualBackgroundSource backgroundSource, SegmentationProperty segproperty, agora::media::MEDIA_SOURCE_TYPE type=agora::media::PRIMARY_CAMERA_SOURCE)=0
 
virtual int enableRemoteSuperResolution (uid_t userId, bool enable)=0
 
virtual int setupRemoteVideo (const VideoCanvas &canvas)=0
 
virtual int setupLocalVideo (const VideoCanvas &canvas)=0
 
virtual int enableAudio ()=0
 
virtual int disableAudio ()=0
 
virtual int setAudioProfile (AUDIO_PROFILE_TYPE profile, AUDIO_SCENARIO_TYPE scenario) __deprecated=0
 
virtual int setAudioProfile (AUDIO_PROFILE_TYPE profile)=0
 
virtual int setAudioScenario (AUDIO_SCENARIO_TYPE scenario)=0
 
virtual int enableLocalAudio (bool enabled)=0
 
virtual int muteLocalAudioStream (bool mute)=0
 
virtual int muteAllRemoteAudioStreams (bool mute)=0
 
virtual int setDefaultMuteAllRemoteAudioStreams (bool mute) __deprecated=0
 
virtual int muteRemoteAudioStream (uid_t uid, bool mute)=0
 
virtual int muteLocalVideoStream (bool mute)=0
 
virtual int enableLocalVideo (bool enabled)=0
 
virtual int muteAllRemoteVideoStreams (bool mute)=0
 
virtual int setDefaultMuteAllRemoteVideoStreams (bool mute) __deprecated=0
 
virtual int muteRemoteVideoStream (uid_t uid, bool mute)=0
 
virtual int setRemoteVideoStreamType (uid_t uid, VIDEO_STREAM_TYPE streamType)=0
 
virtual int setRemoteVideoSubscriptionOptions (uid_t uid, const VideoSubscriptionOptions &options)=0
 
virtual int setRemoteDefaultVideoStreamType (VIDEO_STREAM_TYPE streamType)=0
 
virtual int setSubscribeAudioBlacklist (uid_t *uidList, int uidNumber)=0
 
virtual int setSubscribeAudioWhitelist (uid_t *uidList, int uidNumber)=0
 
virtual int setSubscribeVideoBlacklist (uid_t *uidList, int uidNumber)=0
 
virtual int setSubscribeVideoWhitelist (uid_t *uidList, int uidNumber)=0
 
virtual int enableAudioVolumeIndication (int interval, int smooth, bool reportVad)=0
 
virtual int startAudioRecording (const char *filePath, AUDIO_RECORDING_QUALITY_TYPE quality)=0
 
virtual int startAudioRecording (const char *filePath, int sampleRate, AUDIO_RECORDING_QUALITY_TYPE quality)=0
 
virtual int startAudioRecording (const AudioRecordingConfiguration &config)=0
 
virtual int registerAudioEncodedFrameObserver (const AudioEncodedFrameObserverConfig &config, IAudioEncodedFrameObserver *observer)=0
 
virtual int stopAudioRecording ()=0
 
virtual int destroyMediaPlayer (agora_refptr< IMediaPlayer > media_player)=0
 
virtual int startAudioMixing (const char *filePath, bool loopback, int cycle)=0
 
virtual int startAudioMixing (const char *filePath, bool loopback, int cycle, int startPos)=0
 
virtual int stopAudioMixing ()=0
 
virtual int pauseAudioMixing ()=0
 
virtual int resumeAudioMixing ()=0
 
virtual int selectAudioTrack (int index)=0
 
virtual int getAudioTrackCount ()=0
 
virtual int adjustAudioMixingVolume (int volume)=0
 
virtual int adjustAudioMixingPublishVolume (int volume)=0
 
virtual int getAudioMixingPublishVolume ()=0
 
virtual int adjustAudioMixingPlayoutVolume (int volume)=0
 
virtual int getAudioMixingPlayoutVolume ()=0
 
virtual int getAudioMixingDuration ()=0
 
virtual int getAudioMixingCurrentPosition ()=0
 
virtual int setAudioMixingPosition (int pos)=0
 
virtual int setAudioMixingDualMonoMode (media::AUDIO_MIXING_DUAL_MONO_MODE mode)=0
 
virtual int setAudioMixingPitch (int pitch)=0
 
virtual int getEffectsVolume ()=0
 
virtual int setEffectsVolume (int volume)=0
 
virtual int preloadEffect (int soundId, const char *filePath, int startPos=0)=0
 
virtual int playEffect (int soundId, const char *filePath, int loopCount, double pitch, double pan, int gain, bool publish=false, int startPos=0)=0
 
virtual int playAllEffects (int loopCount, double pitch, double pan, int gain, bool publish=false)=0
 
virtual int getVolumeOfEffect (int soundId)=0
 
virtual int setVolumeOfEffect (int soundId, int volume)=0
 
virtual int pauseEffect (int soundId)=0
 
virtual int pauseAllEffects ()=0
 
virtual int resumeEffect (int soundId)=0
 
virtual int resumeAllEffects ()=0
 
virtual int stopEffect (int soundId)=0
 
virtual int stopAllEffects ()=0
 
virtual int unloadEffect (int soundId)=0
 
virtual int unloadAllEffects ()=0
 
virtual int getEffectDuration (const char *filePath)=0
 
virtual int setEffectPosition (int soundId, int pos)=0
 
virtual int getEffectCurrentPosition (int soundId)=0
 
virtual int enableSoundPositionIndication (bool enabled)=0
 
virtual int setRemoteVoicePosition (uid_t uid, double pan, double gain)=0
 
virtual int enableSpatialAudio (bool enabled)=0
 
virtual int setRemoteUserSpatialAudioParams (uid_t uid, const agora::SpatialAudioParams &params)=0
 
virtual int setVoiceBeautifierPreset (VOICE_BEAUTIFIER_PRESET preset)=0
 
virtual int setAudioEffectPreset (AUDIO_EFFECT_PRESET preset)=0
 
virtual int setVoiceConversionPreset (VOICE_CONVERSION_PRESET preset)=0
 
virtual int setAudioEffectParameters (AUDIO_EFFECT_PRESET preset, int param1, int param2)=0
 
virtual int setVoiceBeautifierParameters (VOICE_BEAUTIFIER_PRESET preset, int param1, int param2)=0
 
virtual int setVoiceConversionParameters (VOICE_CONVERSION_PRESET preset, int param1, int param2)=0
 
virtual int setLocalVoicePitch (double pitch)=0
 
virtual int setLocalVoiceEqualization (AUDIO_EQUALIZATION_BAND_FREQUENCY bandFrequency, int bandGain)=0
 
virtual int setLocalVoiceReverb (AUDIO_REVERB_TYPE reverbKey, int value)=0
 
virtual int setHeadphoneEQPreset (HEADPHONE_EQUALIZER_PRESET preset)=0
 
virtual int setHeadphoneEQParameters (int lowGain, int highGain)=0
 
virtual int setLogFile (const char *filePath)=0
 
virtual int setLogFilter (unsigned int filter)=0
 
virtual int setLogLevel (commons::LOG_LEVEL level)=0
 
virtual int setLogFileSize (unsigned int fileSizeInKBytes)=0
 
virtual int uploadLogFile (agora::util::AString &requestId)=0
 
virtual int setLocalRenderMode (media::base::RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode)=0
 
virtual int setRemoteRenderMode (uid_t uid, media::base::RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode)=0
 
virtual int setLocalRenderMode (media::base::RENDER_MODE_TYPE renderMode)=0
 
virtual int setLocalVideoMirrorMode (VIDEO_MIRROR_MODE_TYPE mirrorMode)=0
 
virtual int enableDualStreamMode (bool enabled)=0
 
virtual int enableDualStreamMode (bool enabled, const SimulcastStreamConfig &streamConfig)=0
 
virtual int setDualStreamMode (SIMULCAST_STREAM_MODE mode)=0
 
virtual int setDualStreamMode (SIMULCAST_STREAM_MODE mode, const SimulcastStreamConfig &streamConfig)=0
 
virtual int enableEchoCancellationExternal (bool enabled, int audioSourceDelay)=0
 
virtual int enableCustomAudioLocalPlayback (int sourceId, bool enabled)=0
 
virtual int startPrimaryCustomAudioTrack (const AudioTrackConfig &config)=0
 
virtual int stopPrimaryCustomAudioTrack ()=0
 
virtual int startSecondaryCustomAudioTrack (const AudioTrackConfig &config)=0
 
virtual int stopSecondaryCustomAudioTrack ()=0
 
virtual int setRecordingAudioFrameParameters (int sampleRate, int channel, RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall)=0
 
virtual int setPlaybackAudioFrameParameters (int sampleRate, int channel, RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall)=0
 
virtual int setMixedAudioFrameParameters (int sampleRate, int channel, int samplesPerCall)=0
 
virtual int setEarMonitoringAudioFrameParameters (int sampleRate, int channel, RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall)=0
 
virtual int setPlaybackAudioFrameBeforeMixingParameters (int sampleRate, int channel)=0
 
virtual int enableAudioSpectrumMonitor (int intervalInMS=100)=0
 
virtual int disableAudioSpectrumMonitor ()=0
 
virtual int registerAudioSpectrumObserver (agora::media::IAudioSpectrumObserver *observer)=0
 
virtual int unregisterAudioSpectrumObserver (agora::media::IAudioSpectrumObserver *observer)=0
 
virtual int adjustRecordingSignalVolume (int volume)=0
 
virtual int muteRecordingSignal (bool mute)=0
 
virtual int adjustPlaybackSignalVolume (int volume)=0
 
virtual int adjustUserPlaybackSignalVolume (unsigned int uid, int volume)=0
 
virtual int setLocalPublishFallbackOption (STREAM_FALLBACK_OPTIONS option)=0
 
virtual int setRemoteSubscribeFallbackOption (STREAM_FALLBACK_OPTIONS option)=0
 
virtual int enableLoopbackRecording (bool enabled, const char *deviceName=NULL)=0
 
virtual int adjustLoopbackSignalVolume (int volume)=0
 
virtual int getLoopbackRecordingVolume ()=0
 
virtual int enableInEarMonitoring (bool enabled, int includeAudioFilters)=0
 
virtual int setInEarMonitoringVolume (int volume)=0
 
virtual int setExtensionProviderProperty (const char *provider, const char *key, const char *value)=0
 
virtual int enableExtension (const char *provider, const char *extension, bool enable=true, agora::media::MEDIA_SOURCE_TYPE type=agora::media::UNKNOWN_MEDIA_SOURCE)=0
 
virtual int setExtensionProperty (const char *provider, const char *extension, const char *key, const char *value, agora::media::MEDIA_SOURCE_TYPE type=agora::media::UNKNOWN_MEDIA_SOURCE)=0
 
virtual int getExtensionProperty (const char *provider, const char *extension, const char *key, char *value, int buf_len, agora::media::MEDIA_SOURCE_TYPE type=agora::media::UNKNOWN_MEDIA_SOURCE)=0
 
virtual int enableExtension (const char *provider, const char *extension, const ExtensionInfo &extensionInfo, bool enable=true)=0
 
virtual int setExtensionProperty (const char *provider, const char *extension, const ExtensionInfo &extensionInfo, const char *key, const char *value)=0
 
virtual int getExtensionProperty (const char *provider, const char *extension, const ExtensionInfo &extensionInfo, const char *key, char *value, int buf_len)=0
 
virtual int setCameraCapturerConfiguration (const CameraCapturerConfiguration &config)=0
 
virtual video_track_id_t createCustomVideoTrack ()=0
 
virtual video_track_id_t createCustomEncodedVideoTrack (const SenderOptions &sender_option)=0
 
virtual int destroyCustomVideoTrack (video_track_id_t video_track_id)=0
 
virtual int destroyCustomEncodedVideoTrack (video_track_id_t video_track_id)=0
 
virtual int getCallId (agora::util::AString &callId)=0
 
virtual int rate (const char *callId, int rating, const char *description)=0
 
virtual int complain (const char *callId, const char *description)=0
 
virtual int startRtmpStreamWithoutTranscoding (const char *url)=0
 
virtual int startRtmpStreamWithTranscoding (const char *url, const LiveTranscoding &transcoding)=0
 
virtual int updateRtmpTranscoding (const LiveTranscoding &transcoding)=0
 
virtual int stopRtmpStream (const char *url)=0
 
virtual int startLocalVideoTranscoder (const LocalTranscoderConfiguration &config)=0
 
virtual int updateLocalTranscoderConfiguration (const LocalTranscoderConfiguration &config)=0
 
virtual int stopLocalVideoTranscoder ()=0
 
virtual int startPrimaryCameraCapture (const CameraCapturerConfiguration &config)=0
 
virtual int startSecondaryCameraCapture (const CameraCapturerConfiguration &config)=0
 
virtual int stopPrimaryCameraCapture ()=0
 
virtual int stopSecondaryCameraCapture ()=0
 
virtual int setCameraDeviceOrientation (VIDEO_SOURCE_TYPE type, VIDEO_ORIENTATION orientation)=0
 
virtual int setScreenCaptureOrientation (VIDEO_SOURCE_TYPE type, VIDEO_ORIENTATION orientation)=0
 
virtual int startPrimaryScreenCapture (const ScreenCaptureConfiguration &config)=0
 
virtual int startSecondaryScreenCapture (const ScreenCaptureConfiguration &config)=0
 
virtual int stopPrimaryScreenCapture ()=0
 
virtual int stopSecondaryScreenCapture ()=0
 
virtual CONNECTION_STATE_TYPE getConnectionState ()=0
 
virtual bool registerEventHandler (IRtcEngineEventHandler *eventHandler)=0
 
virtual bool unregisterEventHandler (IRtcEngineEventHandler *eventHandler)=0
 
virtual int setRemoteUserPriority (uid_t uid, PRIORITY_TYPE userPriority)=0
 
virtual int registerPacketObserver (IPacketObserver *observer)=0
 
virtual int setEncryptionMode (const char *encryptionMode) __deprecated=0
 
virtual int setEncryptionSecret (const char *secret) __deprecated=0
 
virtual int enableEncryption (bool enabled, const EncryptionConfig &config)=0
 
virtual int createDataStream (int *streamId, bool reliable, bool ordered)=0
 
virtual int createDataStream (int *streamId, DataStreamConfig &config)=0
 
virtual int sendStreamMessage (int streamId, const char *data, size_t length)=0
 
virtual int addVideoWatermark (const RtcImage &watermark)=0
 
virtual int addVideoWatermark (const char *watermarkUrl, const WatermarkOptions &options)=0
 
virtual int clearVideoWatermarks ()=0
 
virtual int pauseAudio () __deprecated=0
 
virtual int resumeAudio () __deprecated=0
 
virtual int enableWebSdkInteroperability (bool enabled) __deprecated=0
 
virtual int sendCustomReportMessage (const char *id, const char *category, const char *event, const char *label, int value)=0
 
virtual int registerMediaMetadataObserver (IMetadataObserver *observer, IMetadataObserver::METADATA_TYPE type)=0
 
virtual int unregisterMediaMetadataObserver (IMetadataObserver *observer, IMetadataObserver::METADATA_TYPE type)=0
 
virtual int startAudioFrameDump (const char *channel_id, uid_t user_id, const char *location, const char *uuid, const char *passwd, long duration_ms, bool auto_upload)=0
 
virtual int stopAudioFrameDump (const char *channel_id, uid_t user_id, const char *location)=0
 
virtual int registerLocalUserAccount (const char *appId, const char *userAccount)=0
 
virtual int joinChannelWithUserAccount (const char *token, const char *channelId, const char *userAccount)=0
 
virtual int joinChannelWithUserAccount (const char *token, const char *channelId, const char *userAccount, const ChannelMediaOptions &options)=0
 
virtual int joinChannelWithUserAccountEx (const char *token, const char *channelId, const char *userAccount, const ChannelMediaOptions &options, IRtcEngineEventHandler *eventHandler)=0
 
virtual int getUserInfoByUserAccount (const char *userAccount, rtc::UserInfo *userInfo)=0
 
virtual int getUserInfoByUid (uid_t uid, rtc::UserInfo *userInfo)=0
 
virtual int startChannelMediaRelay (const ChannelMediaRelayConfiguration &configuration)=0
 
virtual int updateChannelMediaRelay (const ChannelMediaRelayConfiguration &configuration)=0
 
virtual int stopChannelMediaRelay ()=0
 
virtual int pauseAllChannelMediaRelay ()=0
 
virtual int resumeAllChannelMediaRelay ()=0
 
virtual int setDirectCdnStreamingAudioConfiguration (AUDIO_PROFILE_TYPE profile)=0
 
virtual int setDirectCdnStreamingVideoConfiguration (const VideoEncoderConfiguration &config)=0
 
virtual int startDirectCdnStreaming (IDirectCdnStreamingEventHandler *eventHandler, const char *publishUrl, const DirectCdnStreamingMediaOptions &options)=0
 
virtual int stopDirectCdnStreaming ()=0
 
virtual int updateDirectCdnStreamingMediaOptions (const DirectCdnStreamingMediaOptions &options)=0
 
virtual int startRhythmPlayer (const char *sound1, const char *sound2, const AgoraRhythmPlayerConfig &config)=0
 
virtual int stopRhythmPlayer ()=0
 
virtual int configRhythmPlayer (const AgoraRhythmPlayerConfig &config)=0
 
virtual int takeSnapshot (uid_t uid, const char *filePath)=0
 save current time video frame to jpeg and write as a jpeg More...
 
virtual int enableContentInspect (bool enabled, const media::ContentInspectConfig &config)=0
 
virtual int adjustCustomAudioPublishVolume (int32_t sourceId, int volume)=0
 
virtual int adjustCustomAudioPlayoutVolume (int32_t sourceId, int volume)=0
 
virtual int setCloudProxy (CLOUD_PROXY_TYPE proxyType)=0
 
virtual int setLocalAccessPoint (const LocalAccessPointConfiguration &config)=0
 
virtual int setAdvancedAudioOptions (AdvancedAudioOptions &options, int sourceType=0)=0
 
virtual int setAVSyncSource (const char *channelId, uid_t uid)=0
 
virtual int enableVideoImageSource (bool enable, const ImageTrackOptions &options)=0
 enable or disable video image source to replace the current video source published or resume it More...
 
virtual int64_t getCurrentMonotonicTimeInMs ()=0
 
virtual int enableWirelessAccelerate (bool enabled)=0
 
virtual int getNetworkType ()=0
 

Detailed Description

The IRtcEngine class.

This class provides the main methods that can be invoked by your app.

IRtcEngine is the basic interface class of the Agora Native SDK. Creating an IRtcEngine object and then calling the methods of this object enables you to use Agora Native SDK's communication functionality.

Member Function Documentation

◆ release()

virtual void agora::rtc::IRtcEngine::release ( bool  sync = false)
pure virtual

Releases the IRtcEngine object.

Parameters
syncDetermines whether this method is a synchronous call.
  • true: This method is a synchronous call, which means that the result of this method call returns after the IRtcEngine object resources are released. Do not call this method in any callback generated by the SDK, or it may result in a deadlock. The SDK automatically detects the deadlock and turns this method into an asynchronous call, but the test itself takes extra time.
  • false: This method is an asynchronous call. The result returns immediately even when the IRtcEngine object resources are not released.
Note
  • Do not immediately uninstall the SDK's dynamic library after the call, or it may crash because the SDK clean-up thread has not quit.
  • Call this method in the sub-thread.
  • Once the app destroys the created IRtcEngine instance, you cannot use any method or callback in the SDK.

◆ initialize()

virtual int agora::rtc::IRtcEngine::initialize ( const RtcEngineContext context)
pure virtual

Initializes the Agora SDK service.

In this method, you need to enter the issued Agora App ID to start initialization. After creating an IRtcEngine object, call this method to initialize the service before calling any other methods. After the initialization, the service is set to enable audio by default.

Parameters
contextThe RtcEngineContext object.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getVersion()

virtual const char* agora::rtc::IRtcEngine::getVersion ( int *  build)
pure virtual

Gets the SDK version.

Parameters
buildThe build number.
Returns
The version of the current SDK in the string format.

◆ getErrorDescription()

virtual const char* agora::rtc::IRtcEngine::getErrorDescription ( int  code)
pure virtual

Gets the warning or error description.

Parameters
codeThe warning or error code.
Returns
The detailed warning or error description.

◆ queryCodecCapability()

virtual int agora::rtc::IRtcEngine::queryCodecCapability ( CodecCapInfo codec_info,
int &  size 
)
pure virtual

Queries the capacity of the current device codec.

Parameters
codec_infoAn array of the codec cap information: CodecCapInfo.
sizeThe array size.
Returns
0: Success. < 0: Failure.

◆ joinChannel() [1/2]

virtual int agora::rtc::IRtcEngine::joinChannel ( const char *  token,
const char *  channelId,
const char *  info,
uid_t  uid 
)
pure virtual

Joins a channel.

Users in the same channel can talk to each other; and multiple users in the same channel can start a group chat. Note that users using different App IDs cannot call each other.

Note
  • This method allows you to join only one channel at a time.
  • A channel does not accept duplicate uids, that is, two users with the same uid. If you set uid as 0, the system automatically assigns a user ID.
  • Ensure that the app ID you use to generate the token is the same app ID that you pass in the initialize method.
Parameters
tokenThe token for authentication.
  • In situations not requiring high security: You can use the temporary token generated at Console. For details, see Get a temporary token.
  • In situations requiring high security: Set it as the token generated at you server. For details, see Generate a token.
channelIdThe unique channel name for the AgoraRTC session in the string format. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
info(Optional) Additional information about the channel that you want to add. It can be set as a NULL string or channel related information. Other users in the channel will 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 reports it in the onJoinChannelSuccess callback. Your app must record and maintain the returned value as the SDK does not maintain it.
Returns
  • 0: Success.
  • < 0: Failure.

◆ joinChannel() [2/2]

virtual int agora::rtc::IRtcEngine::joinChannel ( const char *  token,
const char *  channelId,
uid_t  uid,
const ChannelMediaOptions options 
)
pure virtual

Joins a channel with media options.

Users in the same channel can talk to each other; and multiple users in the same channel can start a group chat. Note that users using different App IDs cannot call each other.

Note
  • This method allows you to join only one channel at a time.
  • A channel does not accept duplicate uids, that is, two users with the same uid. If you set uid as 0, the system automatically assigns a user ID.
  • Ensure that the app ID you use to generate the token is the same app ID that you pass in the initialize method.
Parameters
tokenThe token for authentication.
  • In situations not requiring high security: You can use the temporary token generated at Console. For details, see Get a temporary token.
  • In situations requiring high security: Set it as the token generated at you server. For details, see Generate a token.
channelIdThe unique channel name for the AgoraRTC session in the string format. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
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 reports it in the onJoinChannelSuccess callback. Your app must record and maintain the returned value as the SDK does not maintain it.
optionsThe channel media options: ChannelMediaOptions.
Returns
  • 0: Success.
  • < 0: Failure.

◆ updateChannelMediaOptions()

virtual int agora::rtc::IRtcEngine::updateChannelMediaOptions ( const ChannelMediaOptions options)
pure virtual

Updates the channel media options after joining the channel.

Parameters
optionsThe channel media options: ChannelMediaOptions.
Returns
  • 0: Success.
  • < 0: Failure.

◆ leaveChannel() [1/2]

virtual int agora::rtc::IRtcEngine::leaveChannel ( )
pure virtual

Leaves the channel.

This method allows a user to leave the channel, for example, by hanging up or exiting a call.

This method is an asynchronous call, which means that the result of this method returns even before the user has not actually left the channel. Once the user successfully leaves the channel, the SDK triggers the onLeaveChannel callback.

Note
If you call release immediately after this method, the leaveChannel process will be interrupted, and the SDK will not trigger the onLeaveChannel callback.
Returns
  • 0: Success.
  • < 0: Failure.

◆ leaveChannel() [2/2]

virtual int agora::rtc::IRtcEngine::leaveChannel ( const LeaveChannelOptions options)
pure virtual

Leaves the channel.

Parameters
optionsThe leave channel options.

This method allows a user to leave the channel, for example, by hanging up or exiting a call.

This method is an asynchronous call, which means that the result of this method returns even before the user has not actually left the channel. Once the user successfully leaves the channel, the SDK triggers the onLeaveChannel callback.

Note
If you call release immediately after this method, the leaveChannel process will be interrupted, and the SDK will not trigger the onLeaveChannel callback.
Returns
  • 0: Success.
  • < 0: Failure.

◆ renewToken()

virtual int agora::rtc::IRtcEngine::renewToken ( const char *  token)
pure virtual

Renews the token.

Once a token is enabled and used, it expires after a certain period of time.

Under the following circumstances, generate a new token on your server, and then call this method to renew it. Failure to do so results in the SDK disconnecting from the server.

  • The IRtcEngineEventHandler onTokenPrivilegeWillExpire "onTokenPrivilegeWillExpire" callback is triggered;
  • The onRequestToken callback is triggered;
  • The ERR_TOKEN_EXPIRED(-109) error is reported.
Parameters
tokenThe new token.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setChannelProfile()

virtual int agora::rtc::IRtcEngine::setChannelProfile ( CHANNEL_PROFILE_TYPE  profile)
pure virtual

Sets the channel profile.

The IRtcEngine differentiates channel profiles and applies different optimization algorithms accordingly. For example, it prioritizes smoothness and low latency for a video call, and prioritizes video quality for a video broadcast.

Note
  • To ensure the quality of real-time communication, we recommend that all users in a channel use the same channel profile.
  • Call this method before calling joinChannel. You cannot set the channel profile once you have joined the channel.
Parameters
profileThe channel profile: #CHANNEL_PROFILE_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setClientRole() [1/2]

virtual int agora::rtc::IRtcEngine::setClientRole ( CLIENT_ROLE_TYPE  role)
pure virtual

Sets the role of a user.

This method sets the user role as either BROADCASTER or AUDIENCE (default).

  • The broadcaster sends and receives streams.
  • The audience receives streams only.

By default, all users are audience regardless of the channel profile. Call this method to change the user role to BROADCASTER so that the user can send a stream.

Note
After calling the setClientRole() method to CLIENT_ROLE_AUDIENCE, the SDK stops audio recording. However, CLIENT_ROLE_AUDIENCE will keep audio recording with AUDIO_SCENARIO_CHATROOM(5). Normally, app developer can also use mute api to achieve the same result, and we implement this 'non-orthogonal' behavior only to make API backward compatible.
Parameters
roleThe role of the client: #CLIENT_ROLE_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setClientRole() [2/2]

virtual int agora::rtc::IRtcEngine::setClientRole ( CLIENT_ROLE_TYPE  role,
const ClientRoleOptions options 
)
pure virtual

Sets the role of the user, such as a host or an audience (default), before joining a channel in the live interactive streaming.

This method can be used to switch the user role in the live interactive streaming after the user joins a channel.

In the LIVE_BROADCASTING profile, when a user switches user roles after joining a channel, a successful setClientRole method call triggers the following callbacks:

Note
This method applies only to the LIVE_BROADCASTING profile.
Parameters
roleSets the role of the user. See #CLIENT_ROLE_TYPE.
optionsSets the audience latency level of the user. See #ClientRoleOptions.
Returns
  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2(ERR_INALID_ARGUMENT): The parameter is invalid.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

◆ startEchoTest() [1/3]

virtual int agora::rtc::IRtcEngine::startEchoTest ( )
pure virtual

Starts an audio call test.

This method launches an audio call test to determine whether the audio devices (for example, headset and speaker) and the network connection are working properly.

In the test, the user first speaks, and the recording is played back in 10 seconds. If the user can hear the recording in 10 seconds, it indicates that the audio devices and network connection work properly.

Note
After calling the startEchoTest() method, always call stopEchoTest() to end the test. Otherwise, the app cannot run the next echo test, nor can it call the joinChannel() method.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startEchoTest() [2/3]

virtual int agora::rtc::IRtcEngine::startEchoTest ( int  intervalInSeconds)
pure virtual

Starts an audio call test.

This method starts an audio call test to determine whether the audio devices (for example, headset and speaker) and the network connection are working properly.

In the audio call test, you record your voice. If the recording plays back within the set time interval, the audio devices and the network connection are working properly.

Note
  • Call this method before joining a channel.
  • After calling this method, call the stopEchoTest method to end the test. Otherwise, the app cannot run the next echo test, or call the joinChannel method.
  • In the LIVE_BROADCASTING profile, only a host can call this method.
Parameters
intervalInSecondsThe time interval (s) between when you speak and when the recording plays back.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startEchoTest() [3/3]

virtual int agora::rtc::IRtcEngine::startEchoTest ( const EchoTestConfiguration config)
pure virtual

Starts a video call test.

Parameters
configconfiguration for video call test.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopEchoTest()

virtual int agora::rtc::IRtcEngine::stopEchoTest ( )
pure virtual

Stops the audio call test.

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

◆ enableVideo()

virtual int agora::rtc::IRtcEngine::enableVideo ( )
pure virtual

Enables the video.

You can call this method either before joining a channel or during a call. If you call this method before entering a channel, the service starts the video; if you call it during a call, the audio call switches to a video call.

Note
This method controls the underlying states of the Engine. It is still valid after one leaves the channel.
Returns
  • 0: Success.
  • < 0: Failure.

◆ disableVideo()

virtual int agora::rtc::IRtcEngine::disableVideo ( )
pure virtual

Disables the video.

This method stops capturing the local video and receiving any remote video. To enable the local preview function, call enableLocalVideo (true).

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

◆ startPreview() [1/2]

virtual int agora::rtc::IRtcEngine::startPreview ( )
pure virtual

Starts the local video preview before joining a channel.

Once you call this method to start the local video preview, if you leave the channel by calling leaveChannel, the local video preview remains until you call stopPreview to disable it.

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

◆ startPreview() [2/2]

virtual int agora::rtc::IRtcEngine::startPreview ( VIDEO_SOURCE_TYPE  sourceType)
pure virtual

Starts the local video preview for specific source type.

Parameters
sourceType- The video source type.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopPreview() [1/2]

virtual int agora::rtc::IRtcEngine::stopPreview ( )
pure virtual

Stops the local video preview and the video.

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

◆ stopPreview() [2/2]

virtual int agora::rtc::IRtcEngine::stopPreview ( VIDEO_SOURCE_TYPE  sourceType)
pure virtual

Stops the local video preview for specific source type.

Parameters
sourceType- The video source type.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startLastmileProbeTest()

virtual int agora::rtc::IRtcEngine::startLastmileProbeTest ( const LastmileProbeConfig config)
pure virtual

Starts the last-mile network probe test.

This method starts the last-mile network probe test before joining a channel to get the uplink and downlink last-mile network statistics, including the bandwidth, packet loss, jitter, and round-trip time (RTT).

Call this method to check the uplink network quality before users join a channel or before an audience switches to a host. Once this method is enabled, the SDK returns the following callbacks:

  • onLastmileQuality: the SDK triggers this callback depending on the network conditions. This callback rates the network conditions and is more closely linked to the user experience.
  • onLastmileProbeResult: the SDK triggers this callback within 30 seconds depending on the network conditions. This callback returns the real-time statistics of the network conditions and is more objective.
Note
  • Do not call other methods before receiving the onLastmileQuality and onLastmileProbeResult callbacks. Otherwise, the callbacks may be interrupted.
  • In the Live-broadcast profile, a host should not call this method after joining a channel.
Parameters
configSets the configurations of the last-mile network probe test. See LastmileProbeConfig.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopLastmileProbeTest()

virtual int agora::rtc::IRtcEngine::stopLastmileProbeTest ( )
pure virtual

Stops the last-mile network probe test.

◆ setVideoEncoderConfiguration()

virtual int agora::rtc::IRtcEngine::setVideoEncoderConfiguration ( const VideoEncoderConfiguration config)
pure virtual

Sets the video encoder configuration.

Each configuration profile corresponds to a set of video parameters, including the resolution, frame rate, and bitrate.

The parameters specified in this method are the maximum values under ideal network conditions. If the video engine cannot render the video using the specified parameters due to poor network conditions, the parameters further down the list are considered until a successful configuration is found.

Parameters
configThe local video encoder configuration: VideoEncoderConfiguration.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setBeautyEffectOptions()

virtual int agora::rtc::IRtcEngine::setBeautyEffectOptions ( bool  enabled,
const BeautyOptions options,
agora::media::MEDIA_SOURCE_TYPE  type = agora::media::PRIMARY_CAMERA_SOURCE 
)
pure virtual

Enables/Disables image enhancement and sets the options.

Note
Call this method after calling the enableVideo method.
Parameters
enabledSets whether or not to enable image enhancement:
  • true: enables image enhancement.
  • false: disables image enhancement.
optionsSets the image enhancement option. See BeautyOptions.

◆ setLowlightEnhanceOptions()

virtual int agora::rtc::IRtcEngine::setLowlightEnhanceOptions ( bool  enabled,
const LowlightEnhanceOptions options,
agora::media::MEDIA_SOURCE_TYPE  type = agora::media::PRIMARY_CAMERA_SOURCE 
)
pure virtual

Sets low-light enhancement.

Since
v4.0.0

The low-light enhancement feature can adaptively adjust the brightness value of the video captured in situations with low or uneven lighting, such as backlit, cloudy, or dark scenes. It restores or highlights the image details and improves the overall visual effect of the video.

You can call this method to enable the low-light enhancement feature and set the options of the low-light enhancement effect.

Note
  • Before calling this method, ensure that you have integrated the following dynamic library into your project:
    • Android: libagora_segmentation_extension.so
    • iOS/macOS: AgoraVideoSegmentationExtension.xcframework
    • Windows: libagora_segmentation_extension.dll
  • Call this method after enableVideo.
  • The low-light enhancement feature has certain performance requirements on devices. If your device overheats after you enable low-light enhancement, Agora recommends modifying the low-light enhancement options to a less performance-consuming level or disabling low-light enhancement entirely.
Parameters
enabledSets whether to enable low-light enhancement:
  • true: Enable.
  • false: (Default) Disable.
optionsThe low-light enhancement options. See LowlightEnhanceOptions.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setVideoDenoiserOptions()

virtual int agora::rtc::IRtcEngine::setVideoDenoiserOptions ( bool  enabled,
const VideoDenoiserOptions options,
agora::media::MEDIA_SOURCE_TYPE  type = agora::media::PRIMARY_CAMERA_SOURCE 
)
pure virtual

Sets video noise reduction.

Since
v4.0.0

Underlit environments and low-end video capture devices can cause video images to contain significant noise, which affects video quality. In real-time interactive scenarios, video noise also consumes bitstream resources and reduces encoding efficiency during encoding.

You can call this method to enable the video noise reduction feature and set the options of the video noise reduction effect.

Note
  • Before calling this method, ensure that you have integrated the following dynamic library into your project:
    • Android: libagora_segmentation_extension.so
    • iOS/macOS: AgoraVideoSegmentationExtension.xcframework
    • Windows: libagora_segmentation_extension.dll
  • Call this method after enableVideo.
  • The video noise reduction feature has certain performance requirements on devices. If your device overheats after you enable video noise reduction, Agora recommends modifying the video noise reduction options to a less performance-consuming level or disabling video noise reduction entirely.
Parameters
enabledSets whether to enable video noise reduction:
  • true: Enable.
  • false: (Default) Disable.
optionsThe video noise reduction options. See VideoDenoiserOptions.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setColorEnhanceOptions()

virtual int agora::rtc::IRtcEngine::setColorEnhanceOptions ( bool  enabled,
const ColorEnhanceOptions options,
agora::media::MEDIA_SOURCE_TYPE  type = agora::media::PRIMARY_CAMERA_SOURCE 
)
pure virtual

Sets color enhancement.

Since
v4.0.0

The video images captured by the camera can have color distortion. The color enhancement feature intelligently adjusts video characteristics such as saturation and contrast to enhance the video color richness and color reproduction, making the video more vivid.

You can call this method to enable the color enhancement feature and set the options of the color enhancement effect.

Note
  • Before calling this method, ensure that you have integrated the following dynamic library into your project:
    • Android: libagora_segmentation_extension.so
    • iOS/macOS: AgoraVideoSegmentationExtension.xcframework
    • Windows: libagora_segmentation_extension.dll
  • Call this method after enableVideo.
  • The color enhancement feature has certain performance requirements on devices. If your device overheats after you enable color enhancement, Agora recommends modifying the color enhancement options to a less performance-consuming level or disabling color enhancement entirely.
Parameters
enabledSets whether to enable color enhancement:
  • true: Enable.
  • false: (Default) Disable.
optionsThe color enhancement options. See ColorEnhanceOptions.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableVirtualBackground()

virtual int agora::rtc::IRtcEngine::enableVirtualBackground ( bool  enabled,
VirtualBackgroundSource  backgroundSource,
SegmentationProperty  segproperty,
agora::media::MEDIA_SOURCE_TYPE  type = agora::media::PRIMARY_CAMERA_SOURCE 
)
pure virtual

Enables/Disables the virtual background. (beta function)

Since
v3.7.200

After enabling the virtual background function, you can replace the original background image of the local user with a custom background image. After the replacement, all users in the channel can see the custom background image.

Note
  • Before calling this method, ensure that you have integrated the libagora_segmentation_extension.dll (Windows)/AgoraVideoSegmentationExtension.framework (macOS) dynamic library into the project folder.
  • Call this method after enableVideo.
  • This function requires a high-performance device. Agora recommends that you use this function on devices with an i5 CPU and better.
  • Agora recommends that you use this function in scenarios that meet the following conditions:
    • A high-definition camera device is used, and the environment is uniformly lit.
    • The captured video image is uncluttered, the user's portrait is half-length and largely unobstructed, and the background is a single color that differs from the color of the user's clothing.
Parameters
enabledSets whether to enable the virtual background:
  • true: Enable.
  • false: Disable.
backgroundSourceThe custom background image. See VirtualBackgroundSource. Note: To adapt the resolution of the custom background image to the resolution of the SDK capturing video, the SDK scales and crops the custom background image while ensuring that the content of the custom background image is not distorted.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableRemoteSuperResolution()

virtual int agora::rtc::IRtcEngine::enableRemoteSuperResolution ( uid_t  userId,
bool  enable 
)
pure virtual

Enables/Disables the super resolution feature for a remote user's video. (beta feature)

Since
v4.0.0

This feature effectively boosts the resolution of a remote user's video seen by the local user. If the original resolution of a remote user's video is a × b, the local user's device can render the remote video at a resolution of 2a × 2b after you enable this feature.

Warning
The super resolution feature requires extra system resources. To balance the visual experience and system consumption, the SDK poses the following restrictions:
  • This feature can only be enabled for a single remote user.
  • The original resolution of the remote user's video cannot exceed a certain range. If the local user use super resolution on Android, the original resolution of the remote user's video cannot exceed 640 × 360 pixels; if the local user use super resolution on iOS, the original resolution of the remote user's video cannot exceed 640 × 480 pixels.
Note
  • This method is for Android and iOS only.
  • Before calling this method, ensure that you have integrated the following dynamic library into your project:
    • Android: libagora_super_resolution_extension.so
    • iOS: AgoraSuperResolutionExtension.xcframework
  • Because this method has certain system performance requirements, Agora recommends that you use the following devices or better:
    • Android:
      • VIVO: V1821A, NEX S, 1914A, 1916A, 1962A, 1824BA, X60, X60 Pro
      • OPPO: PCCM00, Find X3
      • OnePlus: A6000
      • Xiaomi: Mi 8, Mi 9, Mi 10, Mi 11, MIX3, Redmi K20 Pro
      • SAMSUNG: SM-G9600, SM-G9650, SM-N9600, SM-G9708, SM-G960U, SM-G9750, S20, S21
      • HUAWEI: SEA-AL00, ELE-AL00, VOG-AL00, YAL-AL10, HMA-AL00, EVR-AN00, nova 4, nova 5 Pro, nova 6 5G, nova 7 5G, Mate 30, Mate 30 Pro, Mate 40, Mate 40 Pro, P40 P40 Pro, HUAWEI MediaPad M6, MatePad 10.8
    • iOS (iOS 12.0 or later):
      • iPhone XR
      • iPhone XS
      • iPhone XS Max
      • iPhone 11
      • iPhone 11 Pro
      • iPhone 11 Pro Max
      • iPhone 12
      • iPhone 12 mini
      • iPhone 12 Pro
      • iPhone 12 Pro Max
      • iPhone 12 SE (2nd generation)
      • iPad Pro 11-inch (3rd generation)
      • iPad Pro 12.9-inch (3rd generation)
      • iPad Air (3rd generation)
      • iPad Air (4th generation)
Parameters
userIdThe user ID of the remote user.
enableDetermines whether to enable super resolution for the remote user's video:
  • true: Enable super resolution.
  • false: Disable super resolution.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setupRemoteVideo()

virtual int agora::rtc::IRtcEngine::setupRemoteVideo ( const VideoCanvas canvas)
pure virtual

Initializes the video view of a remote user.

This method initializes the video view of a remote stream on the local device. It affects only the video view that the local user sees.

Usually the app should specify the uid of the remote video in the method call before the remote user joins the channel. If the remote uid is unknown to the app, set it later when the app receives the onUserJoined callback.

To unbind the remote user from the view, set view in VideoCanvas as null.

Note
Ensure that you call this method in the UI thread.
Parameters
canvasThe remote video view settings: VideoCanvas.
Returns
int VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_SUCCESS = 0, VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_IMAGE_NOT_EXIST = -1, VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_COLOR_FORMAT_NOT_SUPPORTED = -2, VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_DEVICE_NOT_SUPPORTED = -3,

◆ setupLocalVideo()

virtual int agora::rtc::IRtcEngine::setupLocalVideo ( const VideoCanvas canvas)
pure virtual

Initializes the local video view.

This method initializes the video view of the local stream on the local device. It affects only the video view that the local user sees, not the published local video stream.

To unbind the local video from the view, set view in VideoCanvas as null.

Note
Call this method before joining a channel.
Parameters
canvasThe local video view setting: VideoCanvas.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableAudio()

virtual int agora::rtc::IRtcEngine::enableAudio ( )
pure virtual

Enables the audio.

The audio is enabled by default.

Note
This method controls the underlying states of the Engine. It is still valid after one leaves channel.
Returns
  • 0: Success.
  • < 0: Failure.

◆ disableAudio()

virtual int agora::rtc::IRtcEngine::disableAudio ( )
pure virtual

Disables the audio.

Note
This method controls the underlying states of the Engine. It is still valid after one leaves channel.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setAudioProfile() [1/2]

virtual int agora::rtc::IRtcEngine::setAudioProfile ( AUDIO_PROFILE_TYPE  profile,
AUDIO_SCENARIO_TYPE  scenario 
)
pure virtual

Sets the audio parameters and application scenarios.

Deprecated:
This method is deprecated. You can use the setAudioProfile method instead. To set the audio scenario, call the initialize method and pass value in the audioScenario member in the RtcEngineContext struct.
Note
  • Call this method before calling the joinChannel method.
  • In scenarios requiring high-quality audio, we recommend setting profile as MUSIC_HIGH_QUALITY(4) and scenario as AUDIO_SCENARIO_GAME_STREAMING(3).
Parameters
profileSets the sample rate, bitrate, encoding mode, and the number of channels: #AUDIO_PROFILE_TYPE.
scenarioSets the audio application scenarios: #AUDIO_SCENARIO_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setAudioProfile() [2/2]

virtual int agora::rtc::IRtcEngine::setAudioProfile ( AUDIO_PROFILE_TYPE  profile)
pure virtual

Sets the audio profile.

Note
  • Call this method before calling the joinChannel method.
  • In scenarios requiring high-quality audio, Agora recommends setting profile as MUSIC_HIGH_QUALITY(4).
  • To set the audio scenario, call the initialize method and pass value in the audioScenario member in the RtcEngineContext struct.
Parameters
profileThe audio profile, such as the sample rate, bitrate and codec type: #AUDIO_PROFILE_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableLocalAudio()

virtual int agora::rtc::IRtcEngine::enableLocalAudio ( bool  enabled)
pure virtual

Enables or disables the local audio capture.

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 capture and processing.

This method does not affect receiving or playing the remote audio streams, and enableLocalAudio (false) is applicable to scenarios where the user wants to receive remote audio streams without sending any audio stream to other users in the channel.

Parameters
enabledDetermines whether to disable or re-enable the local audio function:
  • true: (Default) Re-enable the local audio function, that is, to start local audio capture and processing.
  • false: Disable the local audio function, that is, to stop local audio capture and processing.
Returns
  • 0: Success.
  • < 0: Failure.

◆ muteLocalAudioStream()

virtual int agora::rtc::IRtcEngine::muteLocalAudioStream ( bool  mute)
pure virtual

Stops or resumes sending the local audio stream.

After calling this method successfully, the SDK triggers the onRemoteAudioStateChanged callback with the following parameters:

  • REMOTE_AUDIO_STATE_STOPPED(0) and REMOTE_AUDIO_REASON_REMOTE_MUTED(5).
  • REMOTE_AUDIO_STATE_DECODING(2) and REMOTE_AUDIO_REASON_REMOTE_UNMUTED(6).
Note
  • When mute is set as true, this method does not disable the microphone, which does not affect any ongoing recording.
  • If you call setChannelProfile after this method, the SDK resets whether or not to mute the local audio according to the channel profile and user role. Therefore, we recommend calling this method after the setChannelProfile method.
Parameters
muteDetermines whether to send or stop sending the local audio stream:
  • true: Stop sending the local audio stream.
  • false: (Default) Send the local audio stream.
Returns
  • 0: Success.
  • < 0: Failure.

◆ muteAllRemoteAudioStreams()

virtual int agora::rtc::IRtcEngine::muteAllRemoteAudioStreams ( bool  mute)
pure virtual

Stops or resumes receiving all remote audio stream.

This method works for all remote users that join or will join a channel using the joinChannel method. It is equivalent to the autoSubscribeAudio member in the ChannelMediaOptions class. You can call this method before, during, or after a call.

  • If you call muteAllRemoteAudioStreams(true) before joining a channel, the local user does not receive any audio stream after joining the channel.
  • If you call muteAllRemoteAudioStreams(true) after joining a channel, the local use stops receiving any audio stream from any user in the channel, including any user who joins the channel after you call this method.
  • If you call muteAllRemoteAudioStreams(true) after leaving a channel, the local user does not receive any audio stream the next time the user joins a channel.

After you successfully call muteAllRemoteAudioStreams(true), you can take the following actions:

  • To resume receiving all remote audio streams, call muteAllRemoteAudioStreams(false).
  • To resume receiving the audio stream of a specified user, call muteRemoteAudioStream(uid, false), where uid is the ID of the user whose audio stream you want to resume receiving.
Note
  • The result of calling this method is affected by calling enableAudio and disableAudio. Settings in muteAllRemoteAudioStreams stop taking effect if either of the following occurs:
    • Calling enableAudio after muteAllRemoteAudioStreams(true).
    • Calling disableAudio after muteAllRemoteAudioStreams(false).
  • This method only works for the channel created by calling joinChannel. To set whether to receive remote audio streams for a specific channel, Agora recommends using autoSubscribeAudio in the ChannelMediaOptions class.
Parameters
muteWhether to stop receiving remote audio streams:
  • true: Stop receiving any remote audio stream.
  • false: (Default) Resume receiving all remote audio streams.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setDefaultMuteAllRemoteAudioStreams()

virtual int agora::rtc::IRtcEngine::setDefaultMuteAllRemoteAudioStreams ( bool  mute)
pure virtual

Determines whether to receive all remote audio streams by default.

Deprecated:
This method is deprecated. To set whether to receive remote audio streams by default, call muteAllRemoteAudioStreams before calling joinChannel

Use this method to set whether to receive audio streams of subsequent peer users. Agora recommends calling it before joining a channel.

A successful call of setDefaultMuteAllRemoteAudioStreams(true) results in that the local user not receiving any audio stream after joining a channel.

Parameters
muteWhether to receive remote audio streams by default:
  • true: Do not receive any remote audio stream by default.
  • false: (Default) Receive remote audio streams by default.
Returns
int
  • 0: Success.
  • < 0: Failure.

◆ muteRemoteAudioStream()

virtual int agora::rtc::IRtcEngine::muteRemoteAudioStream ( uid_t  uid,
bool  mute 
)
pure virtual

Stops or resumes receiving the audio stream of a specified user.

Note
You can call this method before or after joining a channel. If a user leaves a channel, the settings in this method become invalid.
Parameters
uidThe ID of the specified user.
muteWhether to stop receiving the audio stream of the specified user:
  • true: Stop receiving the audio stream of the specified user.
  • false: (Default) Resume receiving the audio stream of the specified user.
Returns
  • 0: Success.
  • < 0: Failure.

◆ muteLocalVideoStream()

virtual int agora::rtc::IRtcEngine::muteLocalVideoStream ( bool  mute)
pure virtual

Stops or resumes sending the local video stream.

Parameters
muteDetermines whether to send or 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.

◆ enableLocalVideo()

virtual int agora::rtc::IRtcEngine::enableLocalVideo ( bool  enabled)
pure virtual

Disables or re-enables the local video capture.

Once you enable the video using enableVideo, the local video is enabled by default. This method disables or re-enables the local video capture.

enableLocalVideo(false) applies to scenarios when the user wants to watch the remote video without sending any video stream to the other user.

Note
Call this method after enableVideo. Otherwise, this method may not work properly.
Parameters
enabledDetermines whether to disable or 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 other remote users. When you set enabled as false, this method does not require a local camera.
Returns
  • 0: Success.
  • < 0: Failure.

◆ muteAllRemoteVideoStreams()

virtual int agora::rtc::IRtcEngine::muteAllRemoteVideoStreams ( bool  mute)
pure virtual

Stops or resumes receiving all remote video streams.

This method works for all remote users that join or will join a channel using the joinChannel method. It is equivalent to the autoSubscribeVideo member in the ChannelMediaOptions class. You can call this method before, during, or after a call.

  • If you call muteAllRemoteVideoStreams(true) before joining a channel, the local user does not receive any video stream after joining the channel.
  • If you call muteAllRemoteVideoStreams(true) after joining a channel, the local use stops receiving any video stream from any user in the channel, including any user who joins the channel after you call this method.
  • If you call muteAllRemoteVideoStreams(true) after leaving a channel, the local user does not receive any video stream the next time the user joins a channel.

After you successfully call muteAllRemoteVideoStreams(true), you can take the following actions:

  • To resume receiving all remote video streams, call muteAllRemoteVideoStreams(false).
  • To resume receiving the video stream of a specified user, call muteRemoteVideoStream(uid, false), where uid is the ID of the user whose video stream you want to resume receiving.
Note
  • The result of calling this method is affected by calling enableVideo and disableVideo. Settings in muteAllRemoteVideoStreams stop taking effect if either of the following occurs:
    • Calling enableVideo after muteAllRemoteVideoStreams(true).
    • Calling disableVideo after muteAllRemoteVideoStreams(false).
  • This method only works for the channel created by calling joinChannel. To set whether to receive remote audio streams for a specific channel, Agora recommends using autoSubscribeVideo in the ChannelMediaOptions class.
Parameters
muteWhether to stop receiving remote video streams:
  • true: Stop receiving any remote video stream.
  • false: (Default) Resume receiving all remote video streams.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setDefaultMuteAllRemoteVideoStreams()

virtual int agora::rtc::IRtcEngine::setDefaultMuteAllRemoteVideoStreams ( bool  mute)
pure virtual

Determines whether to receive all remote video streams by default.

Deprecated:
This method is deprecated. To set whether to receive remote video streams by default, call muteAllRemoteVideoStreams before calling joinChannel.

Use this method to set whether to receive video streams of subsequent peer users. Agora recommends calling it before joining a channel.

A successful call of setDefaultMuteAllRemoteVideoStreams(true) results in that the local user not receiving any video stream after joining a channel.

Parameters
muteWhether to receive remote video streams by default:
  • true: Do not receive any remote video stream by default.
  • false: (Default) Receive remote video streams by default.
Returns
int
  • 0: Success.
  • < 0: Failure.

◆ muteRemoteVideoStream()

virtual int agora::rtc::IRtcEngine::muteRemoteVideoStream ( uid_t  uid,
bool  mute 
)
pure virtual

Stops or resumes receiving the video stream of a specified user.

Note
You can call this method before or after joining a channel. If a user leaves a channel, the settings in this method become invalid.
Parameters
uidThe ID of the specified user.
muteWhether to stop receiving the video stream of the specified user:
  • true: Stop receiving the video stream of the specified user.
  • false: (Default) Resume receiving the video stream of the specified user.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteVideoStreamType()

virtual int agora::rtc::IRtcEngine::setRemoteVideoStreamType ( uid_t  uid,
VIDEO_STREAM_TYPE  streamType 
)
pure virtual

Sets the remote video stream type.

If the remote user has enabled the dual-stream mode, by default the SDK receives the high-stream video by Call this method to switch to the low-stream video.

Note
This method applies to scenarios where the remote user has enabled the dual-stream mode using enableDualStreamMode(true) before joining the channel.
Parameters
uidID of the remote user sending the video stream.
streamTypeSets the video stream type: #VIDEO_STREAM_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteVideoSubscriptionOptions()

virtual int agora::rtc::IRtcEngine::setRemoteVideoSubscriptionOptions ( uid_t  uid,
const VideoSubscriptionOptions options 
)
pure virtual

Sets the remote video subscription options

Parameters
uidID of the remote user sending the video stream.
optionsSets the video subscription options.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteDefaultVideoStreamType()

virtual int agora::rtc::IRtcEngine::setRemoteDefaultVideoStreamType ( VIDEO_STREAM_TYPE  streamType)
pure virtual

Sets the default stream type of the remote video if the remote user has enabled dual-stream.

Parameters
streamTypeSets the default video stream type: #VIDEO_STREAM_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setSubscribeAudioBlacklist()

virtual int agora::rtc::IRtcEngine::setSubscribeAudioBlacklist ( uid_t *  uidList,
int  uidNumber 
)
pure virtual

Sets the blacklist of subscribe remote stream audio.

Parameters
uidListThe id list of users who do not subscribe to audio.
uidNumberThe number of uid in uidList.
Note
If uid is in uidList, the remote user's audio will not be subscribed, even if muteRemoteAudioStream(uid, false) and muteAllRemoteAudioStreams(false) are operated.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setSubscribeAudioWhitelist()

virtual int agora::rtc::IRtcEngine::setSubscribeAudioWhitelist ( uid_t *  uidList,
int  uidNumber 
)
pure virtual

Sets the whitelist of subscribe remote stream audio.

Parameters
uidListThe id list of users who do subscribe to audio.
uidNumberThe number of uid in uidList.
Note
If uid is in uidList, the remote user's audio will be subscribed, even if muteRemoteAudioStream(uid, true) and muteAllRemoteAudioStreams(true) are operated.

If a user is in the blacklist and whitelist at the same time, the user will not subscribe to audio.

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

◆ setSubscribeVideoBlacklist()

virtual int agora::rtc::IRtcEngine::setSubscribeVideoBlacklist ( uid_t *  uidList,
int  uidNumber 
)
pure virtual

Sets the blacklist of subscribe remote stream video.

Parameters
uidListThe id list of users who do not subscribe to video.
uidNumberThe number of uid in uidList.
Note
If uid is in uidList, the remote user's video will not be subscribed, even if muteRemoteVideoStream(uid, false) and muteAllRemoteVideoStreams(false) are operated.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setSubscribeVideoWhitelist()

virtual int agora::rtc::IRtcEngine::setSubscribeVideoWhitelist ( uid_t *  uidList,
int  uidNumber 
)
pure virtual

Sets the whitelist of subscribe remote stream video.

Parameters
uidListThe id list of users who do subscribe to video.
uidNumberThe number of uid in uidList.
Note
If uid is in uidList, the remote user's video will be subscribed, even if muteRemoteVideoStream(uid, true) and muteAllRemoteVideoStreams(true) are operated.

If a user is in the blacklist and whitelist at the same time, the user will not subscribe to video.

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

◆ enableAudioVolumeIndication()

virtual int agora::rtc::IRtcEngine::enableAudioVolumeIndication ( int  interval,
int  smooth,
bool  reportVad 
)
pure virtual

Enables the onAudioVolumeIndication callback to report on which users are speaking and the speakers' volume.

Once the onAudioVolumeIndication callback is enabled, the SDK returns the volume indication in the at the time interval set in enableAudioVolumeIndication, 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, and should be integral multiple of 200 (less than 200 will be set to 200).
smoothThe smoothing factor that sets the sensitivity of the audio volume indicator. The value range is [0, 10]. The greater the value, the more sensitive the indicator. The recommended value is 3.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startAudioRecording() [1/3]

virtual int agora::rtc::IRtcEngine::startAudioRecording ( const char *  filePath,
AUDIO_RECORDING_QUALITY_TYPE  quality 
)
pure virtual

Starts an audio recording.

The SDK allows recording during a call, which supports either one of the following two formats:

  • .wav: Large file size with high sound fidelity
  • .aac: Small file size with low sound 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
filePathFull file path of the recording file. The string of the file name is in UTF-8 code.
qualitySets the audio recording quality: #AUDIO_RECORDING_QUALITY_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startAudioRecording() [2/3]

virtual int agora::rtc::IRtcEngine::startAudioRecording ( const char *  filePath,
int  sampleRate,
AUDIO_RECORDING_QUALITY_TYPE  quality 
)
pure virtual

Starts an audio recording.

The SDK allows recording during a call, which supports either one of the following two formats:

  • .wav: Large file size with high sound fidelity
  • .aac: Small file size with low sound 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
filePathFull file path of the recording file. The string of the file name is in UTF-8 code.
sampleRateSample rate, value should be 16000, 32000, 44100, or 48000.
qualitySets the audio recording quality: #AUDIO_RECORDING_QUALITY_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startAudioRecording() [3/3]

virtual int agora::rtc::IRtcEngine::startAudioRecording ( const AudioRecordingConfiguration config)
pure virtual

Starts an audio recording.

The SDK allows recording during a call, which supports either one of the following two formats:

  • .wav: Large file size with high sound fidelity
  • .aac: Small file size with low sound 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
configAudio recording config.
Returns
  • 0: Success.
  • < 0: Failure.

◆ registerAudioEncodedFrameObserver()

virtual int agora::rtc::IRtcEngine::registerAudioEncodedFrameObserver ( const AudioEncodedFrameObserverConfig config,
IAudioEncodedFrameObserver observer 
)
pure virtual

register encoded audio frame observer

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

◆ stopAudioRecording()

virtual int agora::rtc::IRtcEngine::stopAudioRecording ( )
pure virtual

Stops the audio recording on the client.

The recording automatically stops when the leaveChannel() method is called.

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

◆ startAudioMixing() [1/2]

virtual int agora::rtc::IRtcEngine::startAudioMixing ( const char *  filePath,
bool  loopback,
int  cycle 
)
pure virtual

Starts playing and mixing the music file.

This method mixes the specified local audio file with the audio stream from the microphone. 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.

After calling this method successfully, the SDK triggers the

onAudioMixingStateChanged (PLAY) callback on the local client. When the audio mixing file playback finishes after calling this method, the SDK triggers the onAudioMixingStateChanged (STOPPED) callback on the local client.

Note
  • Call this method after joining a channel, otherwise issues may occur.
  • If the local audio mixing file does not exist, or if the SDK does not support the file format or cannot access the music file URL, the SDK returns #WARN_AUDIO_MIXING_OPEN_ERROR (701).
  • If you want to play an online music file, ensure that the time interval between calling this method is more than 100 ms, or the AUDIO_MIXING_ERROR_TOO_FREQUENT_CALL(702) error code occurs.
Parameters
filePathPointer to the absolute path (including the suffixes of the filename) of the local or online audio file to mix, for example, c:/music/au dio.mp4. Supported audio formats: 3GP, ASF, ADTS, AVI, MP3, MP4, MPEG-4, SAMI, and WAVE.
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.
cycleSets the number of playback loops:
  • Positive integer: Number of playback loops.
  • -1: Infinite playback loops.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startAudioMixing() [2/2]

virtual int agora::rtc::IRtcEngine::startAudioMixing ( const char *  filePath,
bool  loopback,
int  cycle,
int  startPos 
)
pure virtual

Starts playing and mixing the music file.

This method mixes the specified local audio file with the audio stream from the microphone. 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.

After calling this method successfully, the SDK triggers the

onAudioMixingStateChanged (PLAY) callback on the local client. When the audio mixing file playback finishes after calling this method, the SDK triggers the onAudioMixingStateChanged (STOPPED) callback on the local client.

Note
  • Call this method after joining a channel, otherwise issues may occur.
  • If the local audio mixing file does not exist, or if the SDK does not support the file format or cannot access the music file URL, the SDK returns #WARN_AUDIO_MIXING_OPEN_ERROR (701).
  • If you want to play an online music file, ensure that the time interval between calling this method is more than 100 ms, or the AUDIO_MIXING_ERROR_TOO_FREQUENT_CALL(702) error code occurs.
Parameters
filePathPointer to the absolute path (including the suffixes of the filename) of the local or online audio file to mix, for example, c:/music/au dio.mp4. Supported audio formats: 3GP, ASF, ADTS, AVI, MP3, MP4, MPEG-4, SAMI, and WAVE.
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.
cycleSets the number of playback loops:
  • Positive integer: Number of playback loops.
  • -1: Infinite playback loops.
startPosThe playback position (ms) of the music file.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopAudioMixing()

virtual int agora::rtc::IRtcEngine::stopAudioMixing ( )
pure virtual

Stops playing and mixing the music file.

Call this method when you are in a channel.

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

◆ pauseAudioMixing()

virtual int agora::rtc::IRtcEngine::pauseAudioMixing ( )
pure virtual

Pauses playing and mixing the music file.

Call this method when you are in a channel.

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

◆ resumeAudioMixing()

virtual int agora::rtc::IRtcEngine::resumeAudioMixing ( )
pure virtual

Resumes playing and mixing the music file.

Call this method when you are in a channel.

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

◆ selectAudioTrack()

virtual int agora::rtc::IRtcEngine::selectAudioTrack ( int  index)
pure virtual

Select audio track for the music file.

Call this method when you are in a channel.

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

◆ getAudioTrackCount()

virtual int agora::rtc::IRtcEngine::getAudioTrackCount ( )
pure virtual

Get audio track count of the music file.

Call this method when you are in a channel.

Returns
  • ≥ 0: Audio track count of the music file, if the method call is successful.
  • < 0: Failure.

◆ adjustAudioMixingVolume()

virtual int agora::rtc::IRtcEngine::adjustAudioMixingVolume ( int  volume)
pure virtual

Adjusts the volume during audio mixing.

Call this method when you are in a channel.

Note
This method does not affect the volume of audio effect file playback invoked by the playEffect method.
Parameters
volumeThe audio mixing volume. The value ranges between 0 and 100 (default).
Returns
  • 0: Success.
  • < 0: Failure.

◆ adjustAudioMixingPublishVolume()

virtual int agora::rtc::IRtcEngine::adjustAudioMixingPublishVolume ( int  volume)
pure virtual

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.

◆ getAudioMixingPublishVolume()

virtual int agora::rtc::IRtcEngine::getAudioMixingPublishVolume ( )
pure virtual

Retrieves the audio mixing volume for publishing. This method helps troubleshoot audio volume related issues.

Note
Call this method when you are in a channel.
Returns
  • ≥ 0: The audio mixing volume for publishing, if this method call succeeds. The value range is [0,100].
  • < 0: Failure.

◆ adjustAudioMixingPlayoutVolume()

virtual int agora::rtc::IRtcEngine::adjustAudioMixingPlayoutVolume ( int  volume)
pure virtual

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.

◆ getAudioMixingPlayoutVolume()

virtual int agora::rtc::IRtcEngine::getAudioMixingPlayoutVolume ( )
pure virtual

Retrieves the audio mixing volume for local playback. This method helps troubleshoot audio volume related issues.

Note
Call this method when you are in a channel.
Returns
  • ≥ 0: The audio mixing volume, if this method call succeeds. The value range is [0,100].
  • < 0: Failure.

◆ getAudioMixingDuration()

virtual int agora::rtc::IRtcEngine::getAudioMixingDuration ( )
pure virtual

Gets the duration (ms) of the music file.

Call this API when you are in a channel.

Returns
  • Returns the audio mixing duration, if the method call is successful.
  • < 0: Failure.

◆ getAudioMixingCurrentPosition()

virtual int agora::rtc::IRtcEngine::getAudioMixingCurrentPosition ( )
pure virtual

Gets 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()

virtual int agora::rtc::IRtcEngine::setAudioMixingPosition ( int  pos)
pure virtual

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 audio mixing file.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setAudioMixingDualMonoMode()

virtual int agora::rtc::IRtcEngine::setAudioMixingDualMonoMode ( media::AUDIO_MIXING_DUAL_MONO_MODE  mode)
pure virtual

In dual-channel music files, different audio data can be stored on the left and right channels. According to actual needs, you can set the channel mode as the original mode, the left channel mode, the right channel mode or the mixed mode

Parameters
modeThe mode of channel mode
Returns
  • 0: Success.
  • < 0: Failure.

◆ setAudioMixingPitch()

virtual int agora::rtc::IRtcEngine::setAudioMixingPitch ( int  pitch)
pure virtual

Sets the pitch of the local music file.

When a local music file is mixed with a local human voice, call this method to set the pitch of the local music file only.

Note
Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.
Parameters
pitchSets the pitch of the local music file by chromatic scale. The default value is 0, which means keeping the original pitch. The value ranges from -12 to 12, and the pitch value between consecutive values is a chromatic value. The greater the absolute value of this parameter, the higher or lower the pitch of the local music file.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getEffectsVolume()

virtual int agora::rtc::IRtcEngine::getEffectsVolume ( )
pure virtual

Gets the volume of audio effects.

Returns
  • ≥ 0: The volume of audio effects. The value ranges between 0 and 100 (original volume).
  • < 0: Failure.

◆ setEffectsVolume()

virtual int agora::rtc::IRtcEngine::setEffectsVolume ( int  volume)
pure virtual

Sets the volume of audio effects.

Parameters
volumeThe volume of audio effects. The value ranges between 0 and 100 (original volume).
Returns
  • 0: Success.
  • < 0: Failure.

◆ preloadEffect()

virtual int agora::rtc::IRtcEngine::preloadEffect ( int  soundId,
const char *  filePath,
int  startPos = 0 
)
pure virtual

Preloads a specified audio effect.

This method preloads only one specified audio effect into the memory each time it is called. To preload multiple audio effects, call this method multiple times.

After preloading, you can call playEffect to play the preloaded audio effect or call playAllEffects to play all the preloaded audio effects.

Note
  • To ensure smooth communication, limit the size of the audio effect file.
  • Agora recommends calling this method before joining the channel.
Parameters
soundIdThe ID of the audio effect.
filePathThe absolute path of the local audio effect file or the URL of the online audio effect file. Supported audio formats: mp3, mp4, m4a, aac, 3gp, mkv, and wav.
Returns
  • 0: Success.
  • < 0: Failure.

◆ playEffect()

virtual int agora::rtc::IRtcEngine::playEffect ( int  soundId,
const char *  filePath,
int  loopCount,
double  pitch,
double  pan,
int  gain,
bool  publish = false,
int  startPos = 0 
)
pure virtual

Plays a specified audio effect.

After calling preloadEffect, you can call this method to play the specified audio effect for all users in the channel.

This method plays only one specified audio effect each time it is called. To play multiple audio effects, call this method multiple times.

Note
  • Agora recommends playing no more than three audio effects at the same time.
  • The ID and file path of the audio effect in this method must be the same as that in the preloadEffect method.
Parameters
soundIdThe ID of the audio effect.
filePathThe absolute path of the local audio effect file or the URL of the online audio effect file. Supported audio formats: mp3, mp4, m4a, aac, 3gp, mkv, and wav.
loopCountThe number of times the audio effect loops:
  • -1: Play the audio effect in an indefinite loop until stopEffect or stopAllEffects
  • 0: Play the audio effect once.
  • 1: Play the audio effect twice.
pitchThe pitch of the audio effect. The value ranges between 0.5 and 2.0. The default value is 1.0 (original pitch). The lower the value, the lower the pitch.
panThe spatial position of the audio effect. The value ranges between -1.0 and 1.0:
  • -1.0: The audio effect displays to the left.
  • 0.0: The audio effect displays ahead.
  • 1.0: The audio effect displays to the right.
gainThe volume of the audio effect. The value ranges between 0 and 100. The default value is 100 (original volume). The lower the value, the lower the volume of the audio effect.
publishSets whether to publish the audio effect to the remote:
  • true: Publish the audio effect to the remote.
  • false: (Default) Do not publish the audio effect to the remote.
Returns
  • 0: Success.
  • < 0: Failure.

◆ playAllEffects()

virtual int agora::rtc::IRtcEngine::playAllEffects ( int  loopCount,
double  pitch,
double  pan,
int  gain,
bool  publish = false 
)
pure virtual

Plays all audio effects.

After calling preloadEffect multiple times to preload multiple audio effects into the memory, you can call this method to play all the specified audio effects for all users in the channel.

Parameters
loopCountThe number of times the audio effect loops:
  • -1: Play the audio effect in an indefinite loop until stopEffect or stopAllEffects
  • 0: Play the audio effect once.
  • 1: Play the audio effect twice.
pitchThe pitch of the audio effect. The value ranges between 0.5 and 2.0. The default value is 1.0 (original pitch). The lower the value, the lower the pitch.
panThe spatial position of the audio effect. The value ranges between -1.0 and 1.0:
  • -1.0: The audio effect displays to the left.
  • 0.0: The audio effect displays ahead.
  • 1.0: The audio effect displays to the right.
gainThe volume of the audio effect. The value ranges between 0 and 100. The default value is 100 (original volume). The lower the value, the lower the volume of the audio effect.
publishSets whether to publish the audio effect to the remote:
  • true: Publish the audio effect to the remote.
  • false: (Default) Do not publish the audio effect to the remote.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getVolumeOfEffect()

virtual int agora::rtc::IRtcEngine::getVolumeOfEffect ( int  soundId)
pure virtual

Gets the volume of the specified audio effect.

Parameters
soundIdThe ID of the audio effect.
Returns
  • ≥ 0: The volume of the specified audio effect. The value ranges between 0 and 100 (original volume).
  • < 0: Failure.

◆ setVolumeOfEffect()

virtual int agora::rtc::IRtcEngine::setVolumeOfEffect ( int  soundId,
int  volume 
)
pure virtual

Sets the volume of the specified audio effect.

Parameters
soundIdThe ID of the audio effect.
volumeThe volume of the specified audio effect. The value ranges between 0 and 100 (original volume).
Returns
  • 0: Success.
  • < 0: Failure.

◆ pauseEffect()

virtual int agora::rtc::IRtcEngine::pauseEffect ( int  soundId)
pure virtual

Pauses playing the specified audio effect.

Parameters
soundIdThe ID of the audio effect.
Returns
  • 0: Success.
  • < 0: Failure.

◆ pauseAllEffects()

virtual int agora::rtc::IRtcEngine::pauseAllEffects ( )
pure virtual

Pauses playing audio effects.

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

◆ resumeEffect()

virtual int agora::rtc::IRtcEngine::resumeEffect ( int  soundId)
pure virtual

Resumes playing the specified audio effect.

Parameters
soundIdThe ID of the audio effect.
Returns
  • 0: Success.
  • < 0: Failure.

◆ resumeAllEffects()

virtual int agora::rtc::IRtcEngine::resumeAllEffects ( )
pure virtual

Resumes playing audio effects.

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

◆ stopEffect()

virtual int agora::rtc::IRtcEngine::stopEffect ( int  soundId)
pure virtual

Stops playing the specified audio effect.

Parameters
soundIdThe ID of the audio effect.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopAllEffects()

virtual int agora::rtc::IRtcEngine::stopAllEffects ( )
pure virtual

Stops playing audio effects.

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

◆ unloadEffect()

virtual int agora::rtc::IRtcEngine::unloadEffect ( int  soundId)
pure virtual

Releases the specified preloaded audio effect from the memory.

Parameters
soundIdThe ID of the audio effect.
Returns
  • 0: Success.
  • < 0: Failure.

◆ unloadAllEffects()

virtual int agora::rtc::IRtcEngine::unloadAllEffects ( )
pure virtual

Releases preloaded audio effects from the memory.

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

◆ getEffectDuration()

virtual int agora::rtc::IRtcEngine::getEffectDuration ( const char *  filePath)
pure virtual

Gets the duration of the audio effect file.

Note
Parameters
filePathThe absolute path or URL address (including the filename extensions) of the music file. For example: C:\music\audio.mp4. When you access a local file on Android, Agora recommends passing a URI address or the path starts with /assets/ in this parameter.
Returns
  • ≥ 0: A successful method call. Returns the total duration (ms) of the specified audio effect file.
  • < 0: Failure.
    • -22(ERR_RESOURCE_LIMITED): Cannot find the audio effect file. Please set a correct filePath.

◆ setEffectPosition()

virtual int agora::rtc::IRtcEngine::setEffectPosition ( int  soundId,
int  pos 
)
pure virtual

Sets the playback position of an audio effect file. After a successful setting, the local audio effect file starts playing at the specified position.

Note
Call this method after playEffect .
Parameters
soundIdAudio effect ID. Ensure that this parameter is set to the same value as in playEffect .
posThe playback position (ms) of the audio effect file.
Returns
  • 0: Success.
  • < 0: Failure.
    • -22(ERR_RESOURCE_LIMITED): Cannot find the audio effect file. Please set a correct soundId.

◆ getEffectCurrentPosition()

virtual int agora::rtc::IRtcEngine::getEffectCurrentPosition ( int  soundId)
pure virtual

Gets the playback position of the audio effect file.

Note
Call this method after playEffect .
Parameters
soundIdAudio effect ID. Ensure that this parameter is set to the same value as in playEffect .
Returns
  • ≥ 0: A successful method call. Returns the playback position (ms) of the specified audio effect file.
  • < 0: Failure.
    • -22(ERR_RESOURCE_LIMITED): Cannot find the audio effect file. Please set a correct soundId.

◆ enableSoundPositionIndication()

virtual int agora::rtc::IRtcEngine::enableSoundPositionIndication ( bool  enabled)
pure virtual

Enables/Disables stereo panning for remote users.

Ensure that you call this method before joinChannel to enable stereo panning for remote users so that the local user can track the position of a remote user by calling setRemoteVoicePosition.

Parameters
enabledSets whether or not to enable stereo panning for remote users:
  • true: enables stereo panning.
  • false: disables stereo panning.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteVoicePosition()

virtual int agora::rtc::IRtcEngine::setRemoteVoicePosition ( uid_t  uid,
double  pan,
double  gain 
)
pure virtual

Sets the sound position and gain of a remote user.

When the local user calls this method to set the sound position of a remote user, the sound difference between the left and right channels allows the local user to track the real-time position of the remote user, creating a real sense of space. This method applies to massively multiplayer online games, such as Battle Royale games.

Note
  • For this method to work, enable stereo panning for remote users by calling the enableSoundPositionIndication method before joining a channel.
  • This method requires hardware support. For the best sound positioning, we recommend using a wired headset.
  • Ensure that you call this method after joining a channel.
Parameters
uidThe ID of the remote user.
panThe sound position of the remote user. The value ranges from -1.0 to 1.0:
  • 0.0: the remote sound comes from the front.
  • -1.0: the remote sound comes from the left.
  • 1.0: the remote sound comes from the right.
gainGain of the remote user. The value ranges from 0.0 to 100.0. The default value is 100.0 (the original gain of the remote user). The smaller the value, the less the gain.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableSpatialAudio()

virtual int agora::rtc::IRtcEngine::enableSpatialAudio ( bool  enabled)
pure virtual

enable spatial audio

Parameters
enabledenable/disable spatial audio:
  • true: enable spatial audio.
  • false: disable spatial audio.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteUserSpatialAudioParams()

virtual int agora::rtc::IRtcEngine::setRemoteUserSpatialAudioParams ( uid_t  uid,
const agora::SpatialAudioParams params 
)
pure virtual

Sets remote user parameters for spatial audio

Parameters
uidThe ID of the remote user.
paramspatial audio parameters
Returns
int
  • 0: Success.
  • < 0: Failure.

◆ setVoiceBeautifierPreset()

virtual int agora::rtc::IRtcEngine::setVoiceBeautifierPreset ( VOICE_BEAUTIFIER_PRESET  preset)
pure virtual

Sets an SDK preset voice beautifier effect.

Call this method to set an SDK preset voice beautifier effect for the local user who sends an audio stream. After setting a voice beautifier effect, all users in the channel can hear the effect.

You can set different voice beautifier effects for different scenarios. See Set the Voice Beautifier and Audio Effects.

To achieve better audio effect quality, Agora recommends calling setAudioProfile and setting the scenario parameter to AUDIO_SCENARIO_GAME_STREAMING(3) and the profile parameter to AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5) before calling this method.

Note
Parameters
presetThe options for SDK preset voice beautifier effects: #VOICE_BEAUTIFIER_PRESET.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setAudioEffectPreset()

virtual int agora::rtc::IRtcEngine::setAudioEffectPreset ( AUDIO_EFFECT_PRESET  preset)
pure virtual

Sets an SDK preset audio effect.

Call this method to set an SDK preset audio effect for the local user who sends an audio stream. This audio effect does not change the gender characteristics of the original voice. After setting an audio effect, all users in the channel can hear the effect.

You can set different audio effects for different scenarios. See Set the Voice Beautifier and Audio Effects.

To achieve better audio effect quality, Agora recommends calling setAudioProfile and setting the scenario parameter to AUDIO_SCENARIO_GAME_STREAMING(3) before calling this method.

Note
  • You can call this method either before or after joining a channel.
  • Do not set the profile parameter of setAudioProfile to AUDIO_PROFILE_SPEECH_STANDARD(1) or AUDIO_PROFILE_IOT(6); otherwise, this method call fails.
  • This method works best with the human voice. Agora does not recommend using this method for audio containing music.
  • If you call this method and set the preset parameter to enumerators except ROOM_ACOUSTICS_3D_VOICE or PITCH_CORRECTION, do not call setAudioEffectParameters; otherwise, setAudioEffectParameters overrides this method.
  • After calling this method, Agora recommends not calling the following methods, because they can override setAudioEffectPreset:
Parameters
presetThe options for SDK preset audio effects. See #AUDIO_EFFECT_PRESET.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setVoiceConversionPreset()

virtual int agora::rtc::IRtcEngine::setVoiceConversionPreset ( VOICE_CONVERSION_PRESET  preset)
pure virtual

Sets an SDK preset voice conversion.

Call this method to set an SDK preset voice conversion for the local user who sends an audio stream. After setting an voice conversion, all users in the channel can hear the effect.

You can set different voice conversion for different scenarios. See Set the Voice Beautifier and Audio Effects.

To achieve better voice conversion quality, Agora recommends calling setAudioProfile and setting the scenario parameter to AUDIO_SCENARIO_GAME_STREAMING(3) before calling this method.

Note
Parameters
presetThe options for SDK preset voice conversion. See #VOICE_CONVERSION_PRESET.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setAudioEffectParameters()

virtual int agora::rtc::IRtcEngine::setAudioEffectParameters ( AUDIO_EFFECT_PRESET  preset,
int  param1,
int  param2 
)
pure virtual

Sets parameters for SDK preset audio effects.

Call this method to set the following parameters for the local user who send an audio stream:

  • 3D voice effect: Sets the cycle period of the 3D voice effect.
  • Pitch correction effect: Sets the basic mode and tonic pitch of the pitch correction effect. Different songs have different modes and tonic pitches. Agora recommends bounding this method with interface elements to enable users to adjust the pitch correction interactively.

After setting parameters, all users in the channel can hear the relevant effect.

You can call this method directly or after setAudioEffectPreset. If you call this method after setAudioEffectPreset, ensure that you set the preset parameter of setAudioEffectPreset to ROOM_ACOUSTICS_3D_VOICE or PITCH_CORRECTION and then call this method to set the same enumerator; otherwise, this method overrides setAudioEffectPreset.

Note
Parameters
presetThe options for SDK preset audio effects:
  • 3D voice effect: ROOM_ACOUSTICS_3D_VOICE.
    • Call setAudioProfile and set the profile parameter to AUDIO_PROFILE_MUSIC_STANDARD_STEREO(3) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5) before setting this enumerator; otherwise, the enumerator setting does not take effect.
    • If the 3D voice effect is enabled, users need to use stereo audio playback devices to hear the anticipated voice effect.
  • Pitch correction effect: PITCH_CORRECTION. To achieve better audio effect quality, Agora recommends calling setAudioProfile and setting the profile parameter to AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5) before setting this enumerator.
param1
  • If you set preset to ROOM_ACOUSTICS_3D_VOICE, the param1 sets the cycle period of the 3D voice effect. The value range is [1,60] and the unit is a second. The default value is 10 seconds, indicating that the voice moves around you every 10 seconds.
  • If you set preset to PITCH_CORRECTION, param1 sets the basic mode of the pitch correction effect:
    • 1: (Default) Natural major scale.
    • 2: Natural minor scale.
    • 3: Japanese pentatonic scale.
param2
  • If you set preset to ROOM_ACOUSTICS_3D_VOICE, you need to set param2 to 0.
  • If you set preset to PITCH_CORRECTION, param2 sets the tonic pitch of the pitch correction effect:
    • 1: A
    • 2: A#
    • 3: B
    • 4: (Default) C
    • 5: C#
    • 6: D
    • 7: D#
    • 8: E
    • 9: F
    • 10: F#
    • 11: G
    • 12: G#
Returns
  • 0: Success.
  • < 0: Failure.

◆ setVoiceBeautifierParameters()

virtual int agora::rtc::IRtcEngine::setVoiceBeautifierParameters ( VOICE_BEAUTIFIER_PRESET  preset,
int  param1,
int  param2 
)
pure virtual

Sets parameters for SDK preset voice beautifier effects.

Call this method to set a gender characteristic and a reverberation effect for the singing beautifier effect. This method sets parameters for the local user who sends an audio stream.

After you call this method successfully, all users in the channel can hear the relevant effect.

To achieve better audio effect quality, before you call this method, Agora recommends calling setAudioProfile, and setting the scenario parameter as AUDIO_SCENARIO_GAME_STREAMING(3) and the profile parameter as AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5).

Note
Parameters
presetThe options for SDK preset voice beautifier effects:
  • SINGING_BEAUTIFIER: Singing beautifier effect.
param1The gender characteristics options for the singing voice:
  • 1: A male-sounding voice.
  • 2: A female-sounding voice.
param2The reverberation effects options:
  • 1: The reverberation effect sounds like singing in a small room.
  • 2: The reverberation effect sounds like singing in a large room.
  • 3: The reverberation effect sounds like singing in a hall.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setVoiceConversionParameters()

virtual int agora::rtc::IRtcEngine::setVoiceConversionParameters ( VOICE_CONVERSION_PRESET  preset,
int  param1,
int  param2 
)
pure virtual

Set parameters for SDK preset voice conversion.

Note
  • reserved interface
Parameters
presetThe options for SDK preset audio effects. See #VOICE_CONVERSION_PRESET.
param1reserved.
param2reserved.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLocalVoicePitch()

virtual int agora::rtc::IRtcEngine::setLocalVoicePitch ( double  pitch)
pure virtual

Changes the voice pitch of the local speaker.

Parameters
pitchThe 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.
  • -1: Failure.

◆ setLocalVoiceEqualization()

virtual int agora::rtc::IRtcEngine::setLocalVoiceEqualization ( AUDIO_EQUALIZATION_BAND_FREQUENCY  bandFrequency,
int  bandGain 
)
pure virtual

Sets the local voice equalization effect.

Parameters
bandFrequencyThe band frequency ranging from 0 to 9, representing the respective 10-band center frequencies of the voice effects, including 31, 62, 125, 500, 1k, 2k, 4k, 8k, and 16k Hz.
bandGainGain of each band in dB. The value ranges from -15 to 15. The default value is 0.
Returns
  • 0: Success.
  • -1: Failure.

◆ setLocalVoiceReverb()

virtual int agora::rtc::IRtcEngine::setLocalVoiceReverb ( AUDIO_REVERB_TYPE  reverbKey,
int  value 
)
pure virtual

Sets the local voice reverberation.

Parameters
reverbKeyThe reverberation key: #AUDIO_REVERB_TYPE.
valueThe value of the reverberation key: #AUDIO_REVERB_TYPE.
Returns
  • 0: Success.
  • -1: Failure.

◆ setHeadphoneEQPreset()

virtual int agora::rtc::IRtcEngine::setHeadphoneEQPreset ( HEADPHONE_EQUALIZER_PRESET  preset)
pure virtual

Sets preset audio playback effect for remote headphones after remote audio is mixed.

Parameters
presetThe preset key: #HEADPHONE_EQUALIZER_PRESET.
  • HEADPHONE_EQUALIZER_OFF = 0x00000000 : Turn off the eualizer effect for headphones.
  • HEADPHONE_EQUALIZER_OVEREAR = 0x04000001 : For over-ear headphones only.
  • HEADPHONE_EQUALIZER_INEAR = 0x04000002 : For in-ear headphones only.
Returns
  • 0: Success.
  • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).

◆ setHeadphoneEQParameters()

virtual int agora::rtc::IRtcEngine::setHeadphoneEQParameters ( int  lowGain,
int  highGain 
)
pure virtual

Sets the parameters of audio playback effect for remote headphones after remote audio is mixed.

Parameters
lowGainThe higher the parameter value, the deeper the sound. The value range is [-10,10].
highGainThe higher the parameter value, the sharper the sound. The value range is [-10,10].
Returns
  • 0: Success.
  • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).

◆ setLogFile()

virtual int agora::rtc::IRtcEngine::setLogFile ( const char *  filePath)
pure virtual

DEPRECATED 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
Ensure that you call this method immediately after initialize, or the output log may not be complete.
Parameters
filePathFile path of the log file. The string of the log file is in UTF-8.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLogFilter()

virtual int agora::rtc::IRtcEngine::setLogFilter ( unsigned int  filter)
pure virtual

Sets the output log filter level of the SDK.

You can use one or a combination of the filters. The log filter level follows the sequence of OFF, CRITICAL, ERROR, WARNING, INFO, and DEBUG. Choose a filter level and you will see logs preceding that filter level. For example, if you set the log filter level to WARNING, you see the logs within levels CRITICAL, ERROR, and WARNING.

Parameters
filterThe log filter level:
  • LOG_FILTER_DEBUG(0x80f): Output all API logs. Set your log filter as DEBUG if you want to get the most complete log file.
  • LOG_FILTER_INFO(0x0f): Output logs of the CRITICAL, ERROR, WARNING, and INFO level. We recommend setting your log filter as this level.
  • LOG_FILTER_WARNING(0x0e): Output logs of the CRITICAL, ERROR, and WARNING level.
  • LOG_FILTER_ERROR(0x0c): Output logs of the CRITICAL and ERROR level.
  • LOG_FILTER_CRITICAL(0x08): Output logs of the CRITICAL level.
  • LOG_FILTER_OFF(0): Do not output any log.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLogLevel()

virtual int agora::rtc::IRtcEngine::setLogLevel ( commons::LOG_LEVEL  level)
pure virtual

Sets the output log level of the SDK.

You can set the SDK to ouput the log files of the specified level.

Parameters
levelThe log level:
  • LOG_LEVEL_NONE (0x0000): Do not output any log file.
  • LOG_LEVEL_INFO (0x0001): (Recommended) Output log files of the INFO level.
  • LOG_LEVEL_WARN (0x0002): Output log files of the WARN level.
  • LOG_LEVEL_ERROR (0x0004): Output log files of the ERROR level.
  • LOG_LEVEL_FATAL (0x0008): Output log files of the FATAL level.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLogFileSize()

virtual int agora::rtc::IRtcEngine::setLogFileSize ( unsigned int  fileSizeInKBytes)
pure virtual

Sets the log file size (KB).

The SDK has two log files, each with a default size of 512 KB. If you set fileSizeInBytes as 1024 KB, the SDK outputs log files with a total maximum size of 2 MB. If the total size of the log files exceed the set value, the new output log files overwrite the old output log files.

Parameters
fileSizeInKBytesThe SDK log file size (KB).
Returns
  • 0: Success.
  • < 0: Failure.

◆ uploadLogFile()

virtual int agora::rtc::IRtcEngine::uploadLogFile ( agora::util::AString requestId)
pure virtual

Upload current log file immediately to server. only use this when an error occurs block before log file upload success or timeout.

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

◆ setLocalRenderMode() [1/2]

virtual int agora::rtc::IRtcEngine::setLocalRenderMode ( media::base::RENDER_MODE_TYPE  renderMode,
VIDEO_MIRROR_MODE_TYPE  mirrorMode 
)
pure virtual

Updates the display mode of the local video view.

After initializing the local video view, you can call this method to update its rendering mode. It affects only the video view that the local user sees, not the published local video stream.

Note
  • Ensure that you have called setupLocalVideo to initialize the local video view before this method.
  • During a call, you can call this method as many times as necessary to update the local video view.
Parameters
renderModeSets the local display mode. See #RENDER_MODE_TYPE.
mirrorModeSets the local mirror mode. See #VIDEO_MIRROR_MODE_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteRenderMode()

virtual int agora::rtc::IRtcEngine::setRemoteRenderMode ( uid_t  uid,
media::base::RENDER_MODE_TYPE  renderMode,
VIDEO_MIRROR_MODE_TYPE  mirrorMode 
)
pure virtual

Updates the display mode of the video view of a remote user.

After initializing the video view of a remote user, you can call this method to update its rendering and mirror modes. This method affects only the video view that the local user sees.

Note
  • Ensure that you have called setupRemoteVideo to initialize the remote video view before calling this method.
  • During a call, you can call this method as many times as necessary to update the display mode of the video view of a remote user.
Parameters
uidID of the remote user.
renderModeSets the remote display mode. See #RENDER_MODE_TYPE.
mirrorModeSets the mirror type. See #VIDEO_MIRROR_MODE_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLocalRenderMode() [2/2]

virtual int agora::rtc::IRtcEngine::setLocalRenderMode ( media::base::RENDER_MODE_TYPE  renderMode)
pure virtual

Updates the display mode of the local video view.

After initializing the local video view, you can call this method to update its rendering mode. It affects only the video view that the local user sees, not the published local video stream.

Note
  • Ensure that you have called setupLocalVideo to initialize the local video view before this method.
  • During a call, you can call this method as many times as necessary to update the local video view.
Parameters
renderModeSets the local display mode. See #RENDER_MODE_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLocalVideoMirrorMode()

virtual int agora::rtc::IRtcEngine::setLocalVideoMirrorMode ( VIDEO_MIRROR_MODE_TYPE  mirrorMode)
pure virtual

Sets the local video mirror mode.

Use this method before calling the startPreview method, or the mirror mode does not take effect until you call the startPreview method again.

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

◆ enableDualStreamMode() [1/2]

virtual int agora::rtc::IRtcEngine::enableDualStreamMode ( bool  enabled)
pure virtual

Enables or disables the dual video stream mode.

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

Parameters
enabled
  • true: Enable the dual-stream mode.
  • false: (default) Disable the dual-stream mode.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableDualStreamMode() [2/2]

virtual int agora::rtc::IRtcEngine::enableDualStreamMode ( bool  enabled,
const SimulcastStreamConfig streamConfig 
)
pure virtual

Enables or disables the dual video stream mode.

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

Parameters
enabled
  • true: Enable the dual-stream mode.
  • false: (default) Disable the dual-stream mode.
streamConfig
  • The minor stream config
Returns
  • 0: Success.
  • < 0: Failure.

◆ setDualStreamMode() [1/2]

virtual int agora::rtc::IRtcEngine::setDualStreamMode ( SIMULCAST_STREAM_MODE  mode)
pure virtual

Enables, disables or auto enable the dual video stream mode.

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

Parameters
mode
  • The dual stream mode
Returns
  • 0: Success.
  • < 0: Failure.

◆ setDualStreamMode() [2/2]

virtual int agora::rtc::IRtcEngine::setDualStreamMode ( SIMULCAST_STREAM_MODE  mode,
const SimulcastStreamConfig streamConfig 
)
pure virtual

Enables, disables or auto enable the dual video stream mode.

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

Parameters
mode
  • dual stream mode
streamConfig
  • The minor stream config
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableCustomAudioLocalPlayback()

virtual int agora::rtc::IRtcEngine::enableCustomAudioLocalPlayback ( int  sourceId,
bool  enabled 
)
pure virtual

Sets the external audio source.

Note
Ensure that you call this method before joining the channel.
Parameters
sourceIdcustom audio source id.
enabledDetermines whether to local playback the external audio source:
  • true: Local playback the external audio source.
  • false: Local don`t playback the external audio source.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startPrimaryCustomAudioTrack()

virtual int agora::rtc::IRtcEngine::startPrimaryCustomAudioTrack ( const AudioTrackConfig config)
pure virtual

Start primary custom audio track local playback.

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

◆ stopPrimaryCustomAudioTrack()

virtual int agora::rtc::IRtcEngine::stopPrimaryCustomAudioTrack ( )
pure virtual

Stop primary custom audio track local playback.

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

◆ startSecondaryCustomAudioTrack()

virtual int agora::rtc::IRtcEngine::startSecondaryCustomAudioTrack ( const AudioTrackConfig config)
pure virtual

Start secondary custom audio track local playback.

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

◆ stopSecondaryCustomAudioTrack()

virtual int agora::rtc::IRtcEngine::stopSecondaryCustomAudioTrack ( )
pure virtual

Stop secondary custom audio track local playback.

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

◆ setRecordingAudioFrameParameters()

virtual int agora::rtc::IRtcEngine::setRecordingAudioFrameParameters ( int  sampleRate,
int  channel,
RAW_AUDIO_FRAME_OP_MODE_TYPE  mode,
int  samplesPerCall 
)
pure virtual

Sets the audio recording format for the onRecordAudioFrame callback.

Parameters
sampleRateThe sample rate (Hz) of the audio data returned in the onRecordAudioFrame callback, which can set be as 8000, 16000, 32000, 44100, or 48000.
channelThe number of audio channels of the audio data returned in the onRecordAudioFrame callback, which can be set as 1 or 2:
  • 1: Mono.
  • 2: Stereo.
modeThis mode is deprecated.
samplesPerCallnot support. Sampling points in the called data returned in onRecordAudioFrame(). For example, it is usually set as 1024 for stream pushing.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setPlaybackAudioFrameParameters()

virtual int agora::rtc::IRtcEngine::setPlaybackAudioFrameParameters ( int  sampleRate,
int  channel,
RAW_AUDIO_FRAME_OP_MODE_TYPE  mode,
int  samplesPerCall 
)
pure virtual

Sets the audio playback format for the onPlaybackAudioFrame callback.

Parameters
sampleRateSets the sample rate (Hz) of the audio data returned in the onPlaybackAudioFrame callback, which can set be as 8000, 16000, 32000, 44100, or 48000.
channelThe number of channels of the audio data returned in the onPlaybackAudioFrame callback, which can be set as 1 or 2:
  • 1: Mono
  • 2: Stereo
modeDeprecated. The use mode of the onPlaybackAudioFrame() callback: agora::rtc::RAW_AUDIO_FRAME_OP_MODE_TYPE.
samplesPerCallnot support. Sampling points in the called data returned in onPlaybackAudioFrame(). For example, it is usually set as 1024 for stream pushing.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setMixedAudioFrameParameters()

virtual int agora::rtc::IRtcEngine::setMixedAudioFrameParameters ( int  sampleRate,
int  channel,
int  samplesPerCall 
)
pure virtual

Sets the mixed audio format for the onMixedAudioFrame callback.

Parameters
sampleRateThe sample rate (Hz) of the audio data returned in the onMixedAudioFrame callback, which can set be as 8000, 16000, 32000, 44100, or 48000.
channelThe number of channels of the audio data in onMixedAudioFrame callback, which can be set as 1 or 2:
  • 1: Mono
  • 2: Stereo
samplesPerCallnot support. Sampling points in the called data returned in onMixedAudioFrame. For example, it is usually set as 1024 for stream pushing.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setEarMonitoringAudioFrameParameters()

virtual int agora::rtc::IRtcEngine::setEarMonitoringAudioFrameParameters ( int  sampleRate,
int  channel,
RAW_AUDIO_FRAME_OP_MODE_TYPE  mode,
int  samplesPerCall 
)
pure virtual

Sets the audio ear monitoring format for the onEarMonitoringAudioFrame callback.

Parameters
sampleRateSets the sample rate (Hz) of the audio data returned in the onEarMonitoringAudioFrame callback, which can set be as 8000, 16000, 32000, 44100, or 48000.
channelThe number of channels of the audio data returned in the onEarMonitoringAudioFrame callback, which can be set as 1 or 2:
  • 1: Mono
  • 2: Stereo
modeDeprecated. The use mode of the onEarMonitoringAudioFrame() callback: agora::rtc::RAW_AUDIO_FRAME_OP_MODE_TYPE.
samplesPerCallnot support. Sampling points in the called data returned in onEarMonitoringAudioFrame(). For example, it is usually set as 1024 for stream pushing.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setPlaybackAudioFrameBeforeMixingParameters()

virtual int agora::rtc::IRtcEngine::setPlaybackAudioFrameBeforeMixingParameters ( int  sampleRate,
int  channel 
)
pure virtual

Sets the audio playback format before mixing in the onPlaybackAudioFrameBeforeMixing callback.

Parameters
sampleRateThe sample rate (Hz) of the audio data returned in onPlaybackAudioFrameBeforeMixing, which can set be as 8000, 16000, 32000, 44100, or 48000.
channelNumber of channels of the audio data returned in onPlaybackAudioFrameBeforeMixing, which can be set as 1 or 2:
  • 1: Mono
  • 2: Stereo
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableAudioSpectrumMonitor()

virtual int agora::rtc::IRtcEngine::enableAudioSpectrumMonitor ( int  intervalInMS = 100)
pure virtual

Enable the audio spectrum monitor.

Parameters
intervalInMSSets the time interval(ms) between two consecutive audio spectrum callback. The default value is 100. This param should be larger than 10.
Returns
  • 0: Success.
  • < 0: Failure.

◆ disableAudioSpectrumMonitor()

virtual int agora::rtc::IRtcEngine::disableAudioSpectrumMonitor ( )
pure virtual

Disalbe the audio spectrum monitor.

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

◆ registerAudioSpectrumObserver()

virtual int agora::rtc::IRtcEngine::registerAudioSpectrumObserver ( agora::media::IAudioSpectrumObserver observer)
pure virtual

Registers an audio spectrum observer.

You need to implement the IAudioSpectrumObserver class in this method, and register the following callbacks according to your scenario:

  • onAudioSpectrumComputed: Occurs when the SDK receives the audio data and at set intervals.
Parameters
observerA pointer to the audio spectrum observer: IAudioSpectrumObserver.
Returns
  • 0: Success.
  • < 0: Failure.

◆ unregisterAudioSpectrumObserver()

virtual int agora::rtc::IRtcEngine::unregisterAudioSpectrumObserver ( agora::media::IAudioSpectrumObserver observer)
pure virtual

Releases the audio spectrum observer.

Parameters
observerThe pointer to the audio spectrum observer: IAudioSpectrumObserver.
Returns
  • 0: Success.
  • < 0: Failure.

◆ adjustRecordingSignalVolume()

virtual int agora::rtc::IRtcEngine::adjustRecordingSignalVolume ( int  volume)
pure virtual

Adjusts the recording volume.

Parameters
volumeThe recording volume, which ranges from 0 to 400:
  • 0: Mute the recording volume.
  • 100: The Original volume.
  • 400: (Maximum) Four times the original volume with signal clipping protection.
Returns
  • 0: Success.
  • < 0: Failure.

◆ muteRecordingSignal()

virtual int agora::rtc::IRtcEngine::muteRecordingSignal ( bool  mute)
pure virtual

Mute or resume recording signal volume.

Parameters
muteDetermines whether to mute or resume the recording signal volume.
  • true: Mute the recording signal volume.
  • false: (Default) Resume the recording signal volume.
Returns
  • 0: Success.
  • < 0: Failure.

◆ adjustPlaybackSignalVolume()

virtual int agora::rtc::IRtcEngine::adjustPlaybackSignalVolume ( int  volume)
pure virtual

Adjusts the playback volume.

Parameters
volumeThe playback volume, which ranges from 0 to 400:
  • 0: Mute the recoridng volume.
  • 100: The Original volume.
  • 400: (Maximum) Four times the original volume with signal clipping protection.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLocalPublishFallbackOption()

virtual int agora::rtc::IRtcEngine::setLocalPublishFallbackOption ( STREAM_FALLBACK_OPTIONS  option)
pure virtual

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

If option is set as #STREAM_FALLBACK_OPTION_AUDIO_ONLY (2), 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 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 published video stream falls back to audio only.
  • Ensure that you call this method before joining a channel.
Parameters
optionSets the fallback option for the published video stream:
  • #STREAM_FALLBACK_OPTION_DISABLED (0): (Default) No fallback behavior for the published video stream when the uplink network condition is poor. The stream quality is not guaranteed.
  • #STREAM_FALLBACK_OPTION_AUDIO_ONLY (2): The published video stream falls back to audio only when the uplink network condition is poor.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteSubscribeFallbackOption()

virtual int agora::rtc::IRtcEngine::setRemoteSubscribeFallbackOption ( STREAM_FALLBACK_OPTIONS  option)
pure virtual

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 (1), 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 (2), 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.

Note
Ensure that you call this method before joining a channel.
Parameters
optionSets the fallback option for the remotely subscribed video stream. See #STREAM_FALLBACK_OPTIONS.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableLoopbackRecording()

virtual int agora::rtc::IRtcEngine::enableLoopbackRecording ( bool  enabled,
const char *  deviceName = NULL 
)
pure virtual

Enables loopback recording.

If you enable loopback recording, the output of the default sound card is mixed into the audio stream sent to the other end.

Note
This method is for Windows only.
Parameters
enabledSets whether to enable/disable loopback recording.
  • true: Enable loopback recording.
  • false: (Default) Disable loopback recording.
deviceNamePointer to the device name of the sound card. The default value is NULL (the default sound card).
  • This method is for macOS and Windows only.
  • macOS does not support loopback capturing of the default sound card. If you need to use this method, please use a virtual sound card and pass its name to the deviceName parameter. Agora has tested and recommends using soundflower.
Returns
  • 0: Success.
  • < 0: Failure.

◆ adjustLoopbackSignalVolume()

virtual int agora::rtc::IRtcEngine::adjustLoopbackSignalVolume ( int  volume)
pure virtual

Adjusts the loopback recording volume.

Parameters
volumeThe loopback volume, which ranges from 0 to 100:
  • 0: Mute the recoridng volume.
  • 100: The Original volume. protection.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getLoopbackRecordingVolume()

virtual int agora::rtc::IRtcEngine::getLoopbackRecordingVolume ( )
pure virtual

Retrieves the audio volume for recording loopback.

Note
Call this method when you are in a channel.
Returns
  • ≥ 0: The audio volume for loopback, if this method call succeeds. The value range is [0,100].
  • < 0: Failure.

◆ enableInEarMonitoring()

virtual int agora::rtc::IRtcEngine::enableInEarMonitoring ( bool  enabled,
int  includeAudioFilters 
)
pure virtual

Enables in-ear monitoring.

Parameters
enabledDetermines whether to enable in-ear monitoring.
  • true: Enable.
  • false: (Default) Disable.
includeAudioFiltersThe type of the ear monitoring: #EAR_MONITORING_FILTER_TYPE
Returns
  • 0: Success.
  • < 0: Failure.

◆ setInEarMonitoringVolume()

virtual int agora::rtc::IRtcEngine::setInEarMonitoringVolume ( int  volume)
pure virtual

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.

◆ setExtensionProviderProperty()

virtual int agora::rtc::IRtcEngine::setExtensionProviderProperty ( const char *  provider,
const char *  key,
const char *  value 
)
pure virtual

Set extension provider specific property.

Parameters
providername for provider, e.g. agora.io.
keykey for the property.
valueproperty value of json format.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableExtension() [1/2]

virtual int agora::rtc::IRtcEngine::enableExtension ( const char *  provider,
const char *  extension,
bool  enable = true,
agora::media::MEDIA_SOURCE_TYPE  type = agora::media::UNKNOWN_MEDIA_SOURCE 
)
pure virtual

Enable/Disable extension.

Parameters
providername for provider, e.g. agora.io.
extensionname for extension, e.g. agora.beauty.
enableenable or disable.
  • true: enable.
  • false: disable.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setExtensionProperty() [1/2]

virtual int agora::rtc::IRtcEngine::setExtensionProperty ( const char *  provider,
const char *  extension,
const char *  key,
const char *  value,
agora::media::MEDIA_SOURCE_TYPE  type = agora::media::UNKNOWN_MEDIA_SOURCE 
)
pure virtual

Set extension specific property.

Parameters
providername for provider, e.g. agora.io.
extensionname for extension, e.g. agora.beauty.
keykey for the property.
valueproperty value of json format.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getExtensionProperty() [1/2]

virtual int agora::rtc::IRtcEngine::getExtensionProperty ( const char *  provider,
const char *  extension,
const char *  key,
char *  value,
int  buf_len,
agora::media::MEDIA_SOURCE_TYPE  type = agora::media::UNKNOWN_MEDIA_SOURCE 
)
pure virtual

Get extension specific property.

Parameters
providername for provider, e.g. agora.io.
extensionname for extension, e.g. agora.beauty.
keykey for the property.
valueproperty value of json format.
buf_lenmax length of the json value buffer
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableExtension() [2/2]

virtual int agora::rtc::IRtcEngine::enableExtension ( const char *  provider,
const char *  extension,
const ExtensionInfo extensionInfo,
bool  enable = true 
)
pure virtual

Enable/Disable extension.

Parameters
providername for provider, e.g. agora.io.
extensionname for extension, e.g. agora.beauty.
extensionInfothe information for extension.
enableenable or disable.
  • true: enable.
  • false: disable.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setExtensionProperty() [2/2]

virtual int agora::rtc::IRtcEngine::setExtensionProperty ( const char *  provider,
const char *  extension,
const ExtensionInfo extensionInfo,
const char *  key,
const char *  value 
)
pure virtual

Set extension specific property.

Parameters
providername for provider, e.g. agora.io.
extensionname for extension, e.g. agora.beauty.
extensionInfothe information for extension.
keykey for the property.
valueproperty value of json format.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getExtensionProperty() [2/2]

virtual int agora::rtc::IRtcEngine::getExtensionProperty ( const char *  provider,
const char *  extension,
const ExtensionInfo extensionInfo,
const char *  key,
char *  value,
int  buf_len 
)
pure virtual

Get extension specific property.

Parameters
providername for provider, e.g. agora.io.
extensionname for extension, e.g. agora.beauty.
extensionInfothe information for extension.
keykey for the property.
valueproperty value of json format.
buf_lenmax length of the json value buffer
Returns
  • 0: Success.
  • < 0: Failure.

◆ setCameraCapturerConfiguration()

virtual int agora::rtc::IRtcEngine::setCameraCapturerConfiguration ( const CameraCapturerConfiguration config)
pure virtual

Sets the camera capture configuration.

Note
Call this method before enabling the local camera. That said, you can call this method before calling joinChannel, enableVideo, or enableLocalVideo, depending on which method you use to turn on your local camera.
Parameters
configSets the camera capturer configuration. See CameraCapturerConfiguration.
Returns
  • 0: Success.
  • < 0: Failure.

◆ createCustomVideoTrack()

virtual video_track_id_t agora::rtc::IRtcEngine::createCustomVideoTrack ( )
pure virtual

Get an custom video track id created by internal,which could used to publish or preview

Returns
  • > 0: the useable video track id.
  • < 0: Failure.

◆ createCustomEncodedVideoTrack()

virtual video_track_id_t agora::rtc::IRtcEngine::createCustomEncodedVideoTrack ( const SenderOptions sender_option)
pure virtual

Get an custom encoded video track id created by internal,which could used to publish or preview

Returns
  • > 0: the useable video track id.
  • < 0: Failure.

◆ destroyCustomVideoTrack()

virtual int agora::rtc::IRtcEngine::destroyCustomVideoTrack ( video_track_id_t  video_track_id)
pure virtual

destroy a created custom video track id

Parameters
video_track_idThe video track id which was created by createCustomVideoTrack
Returns
  • 0: Success.
  • < 0: Failure.

◆ destroyCustomEncodedVideoTrack()

virtual int agora::rtc::IRtcEngine::destroyCustomEncodedVideoTrack ( video_track_id_t  video_track_id)
pure virtual

destroy a created custom encoded video track id

Parameters
video_track_idThe video track id which was created by createCustomEncodedVideoTrack
Returns
  • 0: Success.
  • < 0: Failure.

◆ getCallId()

virtual int agora::rtc::IRtcEngine::getCallId ( agora::util::AString callId)
pure virtual

Gets the current call ID.

When a user joins a channel on a client, a callId is generated to identify the call.

After a call ends, you can call rate or complain to gather feedback from the customer. These methods require a callId parameter. To use these feedback methods, call the this method first to retrieve the callId during the call, and then pass the value as an argument in the rate or complain method after the call ends.

Parameters
callIdThe reference to the call ID.
Returns
  • The call ID if the method call is successful.
  • < 0: Failure.

◆ rate()

virtual int agora::rtc::IRtcEngine::rate ( const char *  callId,
int  rating,
const char *  description 
)
pure virtual

Allows a user to rate the call.

It is usually called after the call ends.

Parameters
callIdThe call ID retrieved from the getCallId method.
ratingThe rating of the call between 1 (the lowest score) to 5 (the highest score).
description(Optional) The description of the rating. The string length must be less than 800 bytes.
Returns
  • 0: Success.
  • < 0: Failure.

◆ complain()

virtual int agora::rtc::IRtcEngine::complain ( const char *  callId,
const char *  description 
)
pure virtual

Allows a user to complain about the call quality.

This method is usually called after the call ends.

Parameters
callIdThe call ID retrieved from the getCallId method.
description(Optional) The description of the complaint. The string length must be less than 800 bytes.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startRtmpStreamWithoutTranscoding()

virtual int agora::rtc::IRtcEngine::startRtmpStreamWithoutTranscoding ( const char *  url)
pure virtual

Publishes the local stream without transcoding to a specified CDN live RTMP address. (CDN live only.)

The SDK returns the result of this method call in the onStreamPublished callback.

The startRtmpStreamWithoutTranscoding method call triggers the onRtmpStreamingStateChanged callback on the local client to report the state of adding a local stream to the CDN.

Note
  • Ensure that the user joins the channel before calling this method.
  • This method adds only one stream RTMP URL address each time it is called.
  • The RTMP URL address must not contain special characters, such as Chinese language characters.
  • This method applies to Live Broadcast only.
Parameters
urlThe CDN streaming URL in the RTMP format. The maximum length of this parameter is 1024 bytes.
Returns
  • 0: Success.
  • < 0: Failure.
    • #ERR_INVALID_ARGUMENT (2): The RTMP URL address is NULL or has a string length of 0.
    • #ERR_NOT_INITIALIZED (7): You have not initialized the RTC engine when publishing the stream.
    • #ERR_ALREADY_IN_USE (19): This streaming URL is already in use. Use a new streaming URL for CDN streaming.

◆ startRtmpStreamWithTranscoding()

virtual int agora::rtc::IRtcEngine::startRtmpStreamWithTranscoding ( const char *  url,
const LiveTranscoding transcoding 
)
pure virtual

Publishes the local stream with transcoding to a specified CDN live RTMP address. (CDN live only.)

The SDK returns the result of this method call in the onStreamPublished callback.

The startRtmpStreamWithTranscoding method call triggers the onRtmpStreamingStateChanged callback on the local client to report the state of adding a local stream to the CDN.

Note
  • Ensure that the user joins the channel before calling this method.
  • This method adds only one stream RTMP URL address each time it is called.
  • The RTMP URL address must not contain special characters, such as Chinese language characters.
  • This method applies to Live Broadcast only.
Parameters
urlThe CDN streaming URL in the RTMP format. The maximum length of this parameter is 1024 bytes.
transcodingSets the CDN live audio/video transcoding settings. See LiveTranscoding.
Returns
  • 0: Success.
  • < 0: Failure.
    • #ERR_INVALID_ARGUMENT (2): The RTMP URL address is NULL or has a string length of 0.
    • #ERR_NOT_INITIALIZED (7): You have not initialized the RTC engine when publishing the stream.
    • #ERR_ALREADY_IN_USE (19): This streaming URL is already in use. Use a new streaming URL for CDN streaming.

◆ updateRtmpTranscoding()

virtual int agora::rtc::IRtcEngine::updateRtmpTranscoding ( const LiveTranscoding transcoding)
pure virtual

Update the video layout and audio settings for CDN live. (CDN live only.)

Note
This method applies to Live Broadcast only.
Parameters
transcodingSets the CDN live audio/video transcoding settings. See LiveTranscoding.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopRtmpStream()

virtual int agora::rtc::IRtcEngine::stopRtmpStream ( const char *  url)
pure virtual

Stop an RTMP stream with transcoding or without transcoding from the CDN. (CDN live only.)

This method removes the RTMP URL address (added by the startRtmpStreamWithoutTranscoding method or IRtcEngine::startRtmpStreamWithTranscoding "startRtmpStreamWithTranscoding" method) from a CDN live stream. The SDK returns the result of this method call in the onStreamUnpublished callback.

The stopRtmpStream method call triggers the onRtmpStreamingStateChanged callback on the local client to report the state of removing an RTMP stream from the CDN.

Note
  • This method removes only one RTMP URL address each time it is called.
  • The RTMP URL address must not contain special characters, such as Chinese language characters.
  • This method applies to Live Broadcast only.
Parameters
urlThe RTMP URL address to be removed. The maximum length of this parameter is 1024 bytes.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getConnectionState()

virtual CONNECTION_STATE_TYPE agora::rtc::IRtcEngine::getConnectionState ( )
pure virtual

Gets the current connection state of the SDK.

Returns
#CONNECTION_STATE_TYPE.

◆ registerPacketObserver()

virtual int agora::rtc::IRtcEngine::registerPacketObserver ( IPacketObserver observer)
pure virtual

Registers a packet observer.

The Agora Native SDK allows your app to register a packet observer to receive events whenever a voice or video packet is transmitting.

Parameters
observerThe IPacketObserver object.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setEncryptionMode()

virtual int agora::rtc::IRtcEngine::setEncryptionMode ( const char *  encryptionMode)
pure virtual

Sets the built-in encryption mode.

Deprecated:
This method is deprecated. Use enableEncryption(bool enabled, const EncryptionConfig&) instead.

The Agora Native SDK supports built-in encryption. Call this API to set the encryption mode.

All users in the same channel must use the same encryption mode and password. Refer to information related to the encryption algorithm on the differences between encryption modes.

Note
Call setEncryptionSecret to enable the built-in encryption function before calling this API.
Parameters
encryptionModeEncryption mode:
  • "sm4-128-ecb": 128-bit SM4 encryption, ECB mode.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setEncryptionSecret()

virtual int agora::rtc::IRtcEngine::setEncryptionSecret ( const char *  secret)
pure virtual

Enables built-in encryption.

Deprecated:
This method is deprecated. Use enableEncryption(bool enabled, const EncryptionConfig&) instead.

Use this method to specify 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 has left the channel. If the encryption password is not specified or set to empty, the encryption function will be disabled.

Parameters
secretThe encryption password.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableEncryption()

virtual int agora::rtc::IRtcEngine::enableEncryption ( bool  enabled,
const EncryptionConfig config 
)
pure virtual

Enables/Disables the built-in encryption.

In scenarios requiring high security, Agora recommends calling this method to enable the built-in encryption before joining a channel.

All users in the same channel must use the same encryption mode and encryption key. Once all users leave the channel, the encryption key of this channel is automatically cleared.

Note
  • If you enable the built-in encryption, you cannot use the RTMP streaming function.
Parameters
enabledWhether to enable the built-in encryption:
  • true: Enable the built-in encryption.
  • false: Disable the built-in encryption.
configConfigurations of built-in encryption schemas. See EncryptionConfig.
Returns
  • 0: Success.
  • < 0: Failure.
    • -2(ERR_INVALID_ARGUMENT): An invalid parameter is used. Set the parameter with a valid value.
    • -4(ERR_NOT_SUPPORTED): The encryption mode is incorrect or the SDK fails to load the external encryption library. Check the enumeration or reload the external encryption library.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized. Initialize the IRtcEngine instance before calling this method.

◆ createDataStream() [1/2]

virtual int agora::rtc::IRtcEngine::createDataStream ( int *  streamId,
bool  reliable,
bool  ordered 
)
pure virtual

Creates a data stream.

You can call this method to create a data stream and improve the reliability and ordering of data tranmission.

Note
  • Ensure that you set the same value for reliable and ordered.
  • Each user can only create a maximum of 5 data streams during a RtcEngine lifecycle.
  • The data channel allows a data delay of up to 5 seconds. If the receiver does not receive the data stream within 5 seconds, the data channel reports an error.
Parameters
[out]streamIdThe ID of the stream data.
reliableSets whether the recipients are guaranteed to receive the data stream from the sender within five seconds:
  • true: The recipients receive the data stream from the sender within five seconds. If the recipient does not receive the data stream within five seconds, an error is reported to the application.
  • false: There is no guarantee that the recipients receive the data stream within five seconds and no error message is reported for any delay or missing data stream.
orderedSets whether the recipients receive the data stream in the sent order:
  • true: The recipients receive the data stream in the sent order.
  • false: The recipients do not receive the data stream in the sent order.
Returns
  • 0: Success.
  • < 0: Failure.

◆ createDataStream() [2/2]

virtual int agora::rtc::IRtcEngine::createDataStream ( int *  streamId,
DataStreamConfig config 
)
pure virtual

Creates a data stream.

Each user can create up to five data streams during the lifecycle of the IChannel.

Parameters
streamIdThe ID of the created data stream.
configThe config of data stream.
Returns
int
  • Returns 0: Success.
  • < 0: Failure.

◆ sendStreamMessage()

virtual int agora::rtc::IRtcEngine::sendStreamMessage ( int  streamId,
const char *  data,
size_t  length 
)
pure virtual

Sends a data stream.

After calling createDataStream, you can call this method to send a data stream to all users in the channel.

The SDK has the following restrictions on this method:

  • Up to 60 packets can be sent per second in a channel with each packet having a maximum size of 1 KB.
  • Each client can send up to 30 KB of data per second.
  • Each user can have up to five data streams simultaneously.

After the remote user receives the data stream within 5 seconds, the SDK triggers the onStreamMessage callback on the remote client. After the remote user does not receive the data stream within 5 seconds, the SDK triggers the onStreamMessageError callback on the remote client.

Note
  • Call this method after calling createDataStream.
  • This method applies only to the COMMUNICATION profile or to the hosts in the LIVE_BROADCASTING profile. If an audience in the LIVE_BROADCASTING profile calls this method, the audience may be switched to a host.
Parameters
streamIdThe ID of the stream data.
dataThe data stream.
lengthThe length (byte) of the data stream.
Returns
int
  • 0: Success.
  • < 0: Failure.

◆ addVideoWatermark() [1/2]

virtual int agora::rtc::IRtcEngine::addVideoWatermark ( const RtcImage watermark)
pure virtual

DEPRECATED Adds a watermark image to the local video or CDN live stream.

This method is not recommend, Use addVideoWatermark2 instead.

This method adds a PNG watermark image to the local video stream for the recording device, channel audience, and CDN live audience to view and capture.

To add the PNG file to the CDN live publishing stream, see the setLiveTranscoding method.

Parameters
watermarkPointer to the watermark image to be added to the local video stream. See RtcImage.
Note
  • The URL descriptions are different for the local video and CDN live streams:
    • In a local video stream, url in RtcImage refers to the absolute path of the added watermark image file in the local video stream.
    • In a CDN live stream, url in RtcImage refers to the URL address of the added watermark image in the CDN live broadcast.
  • The source file of the watermark image must be in the PNG file format. If the width and height of the PNG file differ from your settings in this method, the PNG file will be cropped to conform to your settings.
  • The Agora SDK supports adding only one watermark image onto a local video or CDN live stream. The newly added watermark image replaces the previous one.
Returns
  • 0: Success.
  • < 0: Failure.

◆ addVideoWatermark() [2/2]

virtual int agora::rtc::IRtcEngine::addVideoWatermark ( const char *  watermarkUrl,
const WatermarkOptions options 
)
pure virtual

Adds a watermark image to the local video.

This method adds a PNG watermark image to the local video in a live broadcast. Once the watermark image is added, all the audience in the channel (CDN audience included), and the recording device can see and capture it. Agora supports adding only one watermark image onto the local video, and the newly watermark image replaces the previous one.

The watermark position depends on the settings in the setVideoEncoderConfiguration method:

  • If the orientation mode of the encoding video is #ORIENTATION_MODE_FIXED_LANDSCAPE, or the landscape mode in #ORIENTATION_MODE_ADAPTIVE, the watermark uses the landscape orientation.
  • If the orientation mode of the encoding video is #ORIENTATION_MODE_FIXED_PORTRAIT, or the portrait mode in #ORIENTATION_MODE_ADAPTIVE, the watermark uses the portrait orientation.
  • When setting the watermark position, the region must be less than the dimensions set in the setVideoEncoderConfiguration method. Otherwise, the watermark image will be cropped.
Note
  • Ensure that you have called the enableVideo method to enable the video module before calling this method.
  • If you only want to add a watermark image to the local video for the audience in the CDN live broadcast channel to see and capture, you can call this method or the setLiveTranscoding method.
  • This method supports adding a watermark image in the PNG file format only. Supported pixel formats of the PNG image are RGBA, RGB, Palette, Gray, and Alpha_gray.
  • If the dimensions of the PNG image differ from your settings in this method, the image will be cropped or zoomed to conform to your settings.
  • If you have enabled the local video preview by calling the startPreview method, you can use the visibleInPreview member in the WatermarkOptions class to set whether or not the watermark is visible in preview.
  • If you have enabled the mirror mode for the local video, the watermark on the local video is also mirrored. To avoid mirroring the watermark, Agora recommends that you do not use the mirror and watermark functions for the local video at the same time. You can implement the watermark function in your application layer.
Parameters
watermarkUrlThe local file path of the watermark image to be added. This method supports adding a watermark image from the local absolute or relative file path.
optionsPointer to the watermark's options to be added. See WatermarkOptions for more infomation.
Returns
int
  • 0: Success.
  • < 0: Failure.

◆ clearVideoWatermarks()

virtual int agora::rtc::IRtcEngine::clearVideoWatermarks ( )
pure virtual

Removes the watermark image on the video stream added by addVideoWatermark().

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

◆ pauseAudio()

virtual int agora::rtc::IRtcEngine::pauseAudio ( )
pure virtual
Deprecated:
Use disableAudio() instead.

Disables the audio function in the channel.

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

◆ resumeAudio()

virtual int agora::rtc::IRtcEngine::resumeAudio ( )
pure virtual
Deprecated:
Use enableAudio() instead.

Resumes the audio function in the channel.

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

◆ enableWebSdkInteroperability()

virtual int agora::rtc::IRtcEngine::enableWebSdkInteroperability ( bool  enabled)
pure virtual

Enables interoperability with the Agora Web SDK (Live Broadcast only).

Deprecated:
The Agora NG SDK enables the interoperablity with the Web SDK.

Use this method when the channel profile is Live Broadcast. Interoperability with the Agora Web SDK is enabled by default when the channel profile is Communication.

Parameters
enabledDetermines whether to enable interoperability with the Agora Web SDK.
  • true: (Default) Enable interoperability with the Agora Native SDK.
  • false: Disable interoperability with the Agora Native SDK.
Returns
int
  • 0: Success.
  • < 0: Failure.

◆ sendCustomReportMessage()

virtual int agora::rtc::IRtcEngine::sendCustomReportMessage ( const char *  id,
const char *  category,
const char *  event,
const char *  label,
int  value 
)
pure virtual

Agora supports reporting and analyzing customized messages.

This function is in the beta stage with a free trial. The ability provided in its beta test version is reporting a maximum of 10 message pieces within 6 seconds, with each message piece not exceeding 256 bytes.

To try out this function, contact support@agora.io and discuss the format of customized messages with us.

◆ registerMediaMetadataObserver()

virtual int agora::rtc::IRtcEngine::registerMediaMetadataObserver ( IMetadataObserver observer,
IMetadataObserver::METADATA_TYPE  type 
)
pure virtual

Registers the metadata observer.

You need to implement the IMetadataObserver class and specify the metadata type in this method. This method enables you to add synchronized metadata in the video stream for more diversified live interactive streaming, such as sending shopping links, digital coupons, and online quizzes.

A successful call of this method triggers the getMaxMetadataSize callback.

Note
  • Call this method before the joinChannel method.
  • This method applies to the LIVE_BROADCASTING channel profile.
Parameters
observerIMetadataObserver.
typeThe metadata type. See METADATA_TYPE. The SDK supports VIDEO_METADATA (0) only for now.
Returns
  • 0: Success.
  • < 0: Failure.

◆ unregisterMediaMetadataObserver()

virtual int agora::rtc::IRtcEngine::unregisterMediaMetadataObserver ( IMetadataObserver observer,
IMetadataObserver::METADATA_TYPE  type 
)
pure virtual

Unregisters the metadata observer.

Parameters
observerIMetadataObserver.
typeThe metadata type. See METADATA_TYPE. The SDK supports VIDEO_METADATA (0) only for now.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startAudioFrameDump()

virtual int agora::rtc::IRtcEngine::startAudioFrameDump ( const char *  channel_id,
uid_t  user_id,
const char *  location,
const char *  uuid,
const char *  passwd,
long  duration_ms,
bool  auto_upload 
)
pure virtual

Start audio frame dump.

Optional location is: "pre_apm_proc", "apm", "pre_send_proc", "filter", "enc", "tx_mixer", "at_record", "atw_record" for audio sending. "dec", "mixed", "play", "rx_mixer", "playback_mixer", "pcm_source_playback_mixer", "pre_play_proc", "at_playout", "atw_playout" for audio receiving.

◆ registerLocalUserAccount()

virtual int agora::rtc::IRtcEngine::registerLocalUserAccount ( const char *  appId,
const char *  userAccount 
)
pure virtual

Registers a user account.

Once registered, the user account can be used to identify the local user when the user joins the channel. After the user successfully registers a user account, the SDK triggers the onLocalUserRegistered callback on the local client, reporting the user ID and user account of the local user.

To join a channel with a user account, you can choose either of the following:

The difference between the two is that for the former, the time elapsed between calling the joinChannelWithUserAccount method and joining the channel is shorter than the latter.

Note
  • Ensure that you set the userAccount parameter. Otherwise, this method does not take effect.
  • Ensure that the value of the userAccount parameter is unique in the channel.
  • To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the uid of the user is set to the same parameter type.
Parameters
appIdThe App ID of your project.
userAccountThe user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
Returns
  • 0: Success.
  • < 0: Failure.

◆ joinChannelWithUserAccount() [1/2]

virtual int agora::rtc::IRtcEngine::joinChannelWithUserAccount ( const char *  token,
const char *  channelId,
const char *  userAccount 
)
pure virtual

Joins the channel with a user account.

After the user successfully joins the channel, the SDK triggers the following callbacks:

Note
To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the uid of the user is set to the same parameter type.
Parameters
tokenThe token generated at your server:
  • For low-security requirements: You can use the temporary token generated at Console. For details, see Get a temporary toke.
  • For high-security requirements: Set it as the token generated at your server. For details, see Get a token.
channelIdThe channel name. The maximum length of this parameter is 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
userAccountThe user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
Returns
  • 0: Success.
  • < 0: Failure.

◆ joinChannelWithUserAccount() [2/2]

virtual int agora::rtc::IRtcEngine::joinChannelWithUserAccount ( const char *  token,
const char *  channelId,
const char *  userAccount,
const ChannelMediaOptions options 
)
pure virtual

Joins the channel with a user account.

After the user successfully joins the channel, the SDK triggers the following callbacks:

Note
To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the uid of the user is set to the same parameter type.
Parameters
tokenThe token generated at your server:
  • For low-security requirements: You can use the temporary token generated at Console. For details, see Get a temporary toke.
  • For high-security requirements: Set it as the token generated at your server. For details, see Get a token.
channelIdThe channel name. The maximum length of this parameter is 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
userAccountThe user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
optionsThe channel media options: ChannelMediaOptions
Returns
  • 0: Success.
  • < 0: Failure.

◆ joinChannelWithUserAccountEx()

virtual int agora::rtc::IRtcEngine::joinChannelWithUserAccountEx ( const char *  token,
const char *  channelId,
const char *  userAccount,
const ChannelMediaOptions options,
IRtcEngineEventHandler eventHandler 
)
pure virtual

Joins the channel with a user account.

After the user successfully joins the channel, the SDK triggers the following callbacks:

Note
To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the uid of the user is set to the same parameter type.
Parameters
tokenThe token generated at your server:
  • For low-security requirements: You can use the temporary token generated at Console. For details, see Get a temporary toke.
  • For high-security requirements: Set it as the token generated at your server. For details, see Get a token.
channelIdThe channel name. The maximum length of this parameter is 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
userAccountThe user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
optionsThe channel media options: ChannelMediaOptions
eventHandlerThe pointer to the IRtcEngine event handler: IRtcEngineEventHandler.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getUserInfoByUserAccount()

virtual int agora::rtc::IRtcEngine::getUserInfoByUserAccount ( const char *  userAccount,
rtc::UserInfo userInfo 
)
pure virtual

Gets the user information by passing in the user account.

After a remote user joins the channel, the SDK gets the user ID and user account of the remote user, caches them in a mapping table object (userInfo), and triggers the onUserInfoUpdated callback on the local client.

After receiving the oonUserInfoUpdated callback, you can call this method to get the user ID of the remote user from the userInfo object by passing in the user account.

Parameters
userAccountThe user account of the user. Ensure that you set this parameter.
[in,out]userInfoA userInfo object that identifies the user:
  • Input: A userInfo object.
  • Output: A userInfo object that contains the user account and user ID of the user.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getUserInfoByUid()

virtual int agora::rtc::IRtcEngine::getUserInfoByUid ( uid_t  uid,
rtc::UserInfo userInfo 
)
pure virtual

Gets the user information by passing in the user ID.

After a remote user joins the channel, the SDK gets the user ID and user account of the remote user, caches them in a mapping table object (userInfo), and triggers the onUserInfoUpdated callback on the local client.

After receiving the onUserInfoUpdated callback, you can call this method to get the user account of the remote user from the userInfo object by passing in the user ID.

Parameters
uidThe user ID of the remote user. Ensure that you set this parameter.
[in,out]userInfoA userInfo object that identifies the user:
  • Input: A userInfo object.
  • Output: A userInfo object that contains the user account and user ID of the user.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startChannelMediaRelay()

virtual int agora::rtc::IRtcEngine::startChannelMediaRelay ( const ChannelMediaRelayConfiguration configuration)
pure virtual

Starts to relay media streams across channels.

After a successful method call, the SDK triggers the onChannelMediaRelayStateChanged and onChannelMediaRelayEvent callbacks, and these callbacks return the state and events of the media stream relay.

Note
  • Call this method after the joinChannel method.
  • This method takes effect only when you are a host in a LIVE_BROADCASTING channel.
  • After a successful method call, if you want to call this method again, ensure that you call the stopChannelMediaRelay method to quit the current relay.
  • Contact sales.nosp@m.-us@.nosp@m.agora.nosp@m..io before implementing this function.
  • We do not support string user accounts in this API.
Parameters
configurationThe configuration of the media stream relay: ChannelMediaRelayConfiguration.
Returns
  • 0: Success.
  • < 0: Failure.

◆ updateChannelMediaRelay()

virtual int agora::rtc::IRtcEngine::updateChannelMediaRelay ( const ChannelMediaRelayConfiguration configuration)
pure virtual

Updates the channels for media stream relay. After a successful startChannelMediaRelay method call, if you want to relay the media stream to more channels, or leave the current relay channel, you can call the updateChannelMediaRelay method.

After a successful method call, the SDK triggers the onChannelMediaRelayEvent callback with the #RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL (7) state code.

Note
Call this method after the startChannelMediaRelay method to update the destination channel.
Parameters
configurationThe media stream relay configuration: ChannelMediaRelayConfiguration.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopChannelMediaRelay()

virtual int agora::rtc::IRtcEngine::stopChannelMediaRelay ( )
pure virtual

Stops the media stream relay.

Once the relay stops, the host quits all the destination channels.

After a successful method call, the SDK triggers the onChannelMediaRelayStateChanged callback. If the callback returns #RELAY_STATE_IDLE (0) and #RELAY_OK (0), the host successfully stops the relay.

Note
If the method call fails, the SDK triggers the onChannelMediaRelayStateChanged callback with the #RELAY_ERROR_SERVER_NO_RESPONSE (2) or #RELAY_ERROR_SERVER_CONNECTION_LOST (8) state code. You can leave the channel by calling the leaveChannel method, and the media stream relay automatically stops.
Returns
  • 0: Success.
  • < 0: Failure.

◆ pauseAllChannelMediaRelay()

virtual int agora::rtc::IRtcEngine::pauseAllChannelMediaRelay ( )
pure virtual

pause the channels for media stream relay.

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

◆ resumeAllChannelMediaRelay()

virtual int agora::rtc::IRtcEngine::resumeAllChannelMediaRelay ( )
pure virtual

resume the channels for media stream relay.

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

◆ setDirectCdnStreamingAudioConfiguration()

virtual int agora::rtc::IRtcEngine::setDirectCdnStreamingAudioConfiguration ( AUDIO_PROFILE_TYPE  profile)
pure virtual

Set audio parameters for direct streaming to CDN

Note
Must call this api before "startDirectCdnStreaming"
Parameters
profileSets the sample rate, bitrate, encoding mode, and the number of channels: #AUDIO_PROFILE_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setDirectCdnStreamingVideoConfiguration()

virtual int agora::rtc::IRtcEngine::setDirectCdnStreamingVideoConfiguration ( const VideoEncoderConfiguration config)
pure virtual

Set video parameters for direct streaming to CDN

Each configuration profile corresponds to a set of video parameters, including the resolution, frame rate, and bitrate.

Note
Must call this api before "startDirectCdnStreaming"
Parameters
configThe local video encoder configuration: VideoEncoderConfiguration.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startDirectCdnStreaming()

virtual int agora::rtc::IRtcEngine::startDirectCdnStreaming ( IDirectCdnStreamingEventHandler eventHandler,
const char *  publishUrl,
const DirectCdnStreamingMediaOptions options 
)
pure virtual

Start direct cdn streaming

Parameters
eventHandlerA pointer to the direct cdn streaming event handler: IDirectCdnStreamingEventHandler.
publishUrlThe url of the cdn used to publish the stream.
optionsThe direct cdn streaming media options: DirectCdnStreamingMediaOptions. This API must pass an audio-related option, and temporarily cannot pass more than one. For video-related options, you can either choose to not pass any, or only one.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopDirectCdnStreaming()

virtual int agora::rtc::IRtcEngine::stopDirectCdnStreaming ( )
pure virtual

Stop direct cdn streaming

Note
This method is synchronous.
Returns
  • 0: Success.
  • < 0: Failure.

◆ updateDirectCdnStreamingMediaOptions()

virtual int agora::rtc::IRtcEngine::updateDirectCdnStreamingMediaOptions ( const DirectCdnStreamingMediaOptions options)
pure virtual

Change the media source during the pushing

Note
This method is temporarily not supported.
Parameters
optionsThe direct cdn streaming media options: DirectCdnStreamingMediaOptions.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startRhythmPlayer()

virtual int agora::rtc::IRtcEngine::startRhythmPlayer ( const char *  sound1,
const char *  sound2,
const AgoraRhythmPlayerConfig &  config 
)
pure virtual

Enables the rhythm player.

Parameters
sound1The absolute path or URL address (including the filename extensions) of the file for the downbeat.
sound2The absolute path or URL address (including the filename extensions) of the file for the upbeats.
configThe configuration of rhythm player.
Returns
int
  • 0: Success.
  • < 0: Failure.

◆ stopRhythmPlayer()

virtual int agora::rtc::IRtcEngine::stopRhythmPlayer ( )
pure virtual

Disables the rhythm player.

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

◆ configRhythmPlayer()

virtual int agora::rtc::IRtcEngine::configRhythmPlayer ( const AgoraRhythmPlayerConfig &  config)
pure virtual

Configures the rhythm player.

Parameters
configThe configuration of rhythm player.
Returns
int
  • 0: Success.
  • < 0: Failure.

◆ takeSnapshot()

virtual int agora::rtc::IRtcEngine::takeSnapshot ( uid_t  uid,
const char *  filePath 
)
pure virtual

save current time video frame to jpeg and write as a jpeg

Parameters
uidsave remote picture with user id. if uid = 0 save local user's picture
filePathsave file path
Returns
int
  • 0 : Success.
  • <0 : Failure.

◆ enableContentInspect()

virtual int agora::rtc::IRtcEngine::enableContentInspect ( bool  enabled,
const media::ContentInspectConfig config 
)
pure virtual

Enable the content inspect.

Parameters
media::ContentInspectConfig
Returns
  • 0: Success.
  • < 0: Failure.

◆ setCloudProxy()

virtual int agora::rtc::IRtcEngine::setCloudProxy ( CLOUD_PROXY_TYPE  proxyType)
pure virtual

Sets the Agora cloud proxy service.

Since
v3.3.0

When the user's firewall restricts the IP address and port, refer to Use Cloud Proxy to add the specific IP addresses and ports to the firewall whitelist; then, call this method to enable the cloud proxy and set the proxyType parameter as UDP_PROXY(1), which is the cloud proxy for the UDP protocol.

After a successfully cloud proxy connection, the SDK triggers the onConnectionStateChanged (CONNECTION_STATE_CONNECTING, CONNECTION_CHANGED_SETTING_PROXY_SERVER) callback.

To disable the cloud proxy that has been set, call setCloudProxy(NONE_PROXY). To change the cloud proxy type that has been set, call setCloudProxy(NONE_PROXY) first, and then call setCloudProxy, and pass the value that you expect in proxyType.

Note
  • Agora recommends that you call this method before joining the channel or after leaving the channel.
  • For the SDK v3.3.x, the services for pushing streams to CDN and co-hosting across channels are not available when you use the cloud proxy for the UDP protocol. For the SDK v3.4.0 and later, the services for pushing streams to CDN and co-hosting across channels are not available when the user is in a network environment with a firewall and uses the cloud proxy for the UDP protocol.
Parameters
proxyTypeThe cloud proxy type, see #CLOUD_PROXY_TYPE. This parameter is required, and the SDK reports an error if you do not pass in a value.
Returns
  • 0: Success.
  • < 0: Failure.
    • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

◆ setLocalAccessPoint()

virtual int agora::rtc::IRtcEngine::setLocalAccessPoint ( const LocalAccessPointConfiguration config)
pure virtual

set local access point addresses in local proxy mode. use this method before join channel.

Parameters
configThe LocalAccessPointConfiguration class, See the definition of LocalAccessPointConfiguration for details.
Returns
  • 0: Success
  • < 0: Failure

◆ setAdvancedAudioOptions()

virtual int agora::rtc::IRtcEngine::setAdvancedAudioOptions ( AdvancedAudioOptions options,
int  sourceType = 0 
)
pure virtual

set advanced audio options.

Parameters
optionsThe AdvancedAudioOptions class, See the definition of AdvancedAudioOptions for details.
Returns
  • 0: Success
  • < 0: Failure

◆ setAVSyncSource()

virtual int agora::rtc::IRtcEngine::setAVSyncSource ( const char *  channelId,
uid_t  uid 
)
pure virtual

Bind local user and a remote user as an audio&video sync group. The remote user is defined by cid and uid. There’s a usage limit that local user must be a video stream sender. On the receiver side, media streams from same sync group will be time-synced

Parameters
channelIdThe channel id
uidThe user ID of the remote user to be bound with (local user)
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableVideoImageSource()

virtual int agora::rtc::IRtcEngine::enableVideoImageSource ( bool  enable,
const ImageTrackOptions options 
)
pure virtual

enable or disable video image source to replace the current video source published or resume it

Parameters
enabletrue for enable, false for disable
optionsoptions for image track

◆ enableWirelessAccelerate()

virtual int agora::rtc::IRtcEngine::enableWirelessAccelerate ( bool  enabled)
pure virtual

Turn WIFI acceleration on or off.

Note
  • This method is called before and after joining a channel.
  • Users check the WIFI router app for information about acceleration. Therefore, if this interface is invoked, the caller accepts that the caller's name will be displayed to the user in the WIFI router application on behalf of the caller.
Parameters
enabled
  • true:Turn WIFI acceleration on.
  • false:Turn WIFI acceleration off.
Returns
  • 0: Success.
  • < 0: Failure.

Implemented in agora::rtc::IRtcEngineEx.

◆ getNetworkType()

virtual int agora::rtc::IRtcEngine::getNetworkType ( )
pure virtual

get network type value

Returns
  • 0: DISCONNECTED.
  • 1: LAN.
  • 2: WIFI.
  • 3: MOBILE_2G.
  • 4: MOBILE_3G.
  • 5: MOBILE_4G.
  • 6: MOBILE_5G.
  • -1: UNKNOWN.