Video SDK v3.7.2 API Reference for C++, all platforms
agora::rtc::IRtcEngine Class Referenceabstract

Inherited by agora::rtc::IRtcEngine2.

Public Types

typedef unsigned int WindowIDType
 
typedef HWND WindowIDType
 

Public Member Functions

virtual int initialize (const RtcEngineContext &context)=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 joinChannel (const char *token, const char *channelId, const char *info, uid_t uid)=0
 
virtual int joinChannel (const char *token, const char *channelId, const char *info, uid_t uid, const ChannelMediaOptions &options)=0
 
virtual int switchChannel (const char *token, const char *channelId)=0
 
virtual int switchChannel (const char *token, const char *channelId, const ChannelMediaOptions &options)=0
 
virtual int leaveChannel ()=0
 
virtual int renewToken (const char *token)=0
 
virtual int queryInterface (INTERFACE_ID_TYPE iid, void **inter)=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 getUserInfoByUserAccount (const char *userAccount, UserInfo *userInfo)=0
 
virtual int getUserInfoByUid (uid_t uid, UserInfo *userInfo)=0
 
virtual int startEchoTest ()=0
 
virtual int startEchoTest (int intervalInSeconds)=0
 
virtual int startEchoTest (const EchoTestConfiguration &config)=0
 
virtual int stopEchoTest ()=0
 
virtual int setCloudProxy (CLOUD_PROXY_TYPE proxyType)=0
 
virtual int enableVideo ()=0
 
virtual int disableVideo ()=0
 
virtual int setVideoProfile (VIDEO_PROFILE_TYPE profile, bool swapWidthAndHeight) AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int setVideoEncoderConfiguration (const VideoEncoderConfiguration &config)=0
 
virtual int setCameraCapturerConfiguration (const CameraCapturerConfiguration &config)=0
 
virtual int setupLocalVideo (const VideoCanvas &canvas)=0
 
virtual int setupRemoteVideo (const VideoCanvas &canvas)=0
 
virtual int startPreview ()=0
 
virtual int setRemoteUserPriority (uid_t uid, PRIORITY_TYPE userPriority)=0
 
virtual int stopPreview ()=0
 
virtual int enableAudio ()=0
 
virtual int enableLocalAudio (bool enabled)=0
 
virtual int disableAudio ()=0
 
virtual int setAudioProfile (AUDIO_PROFILE_TYPE profile, AUDIO_SCENARIO_TYPE scenario)=0
 
virtual int muteLocalAudioStream (bool mute)=0
 
virtual int muteAllRemoteAudioStreams (bool mute)=0
 
virtual int setDefaultMuteAllRemoteAudioStreams (bool mute) AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int adjustUserPlaybackSignalVolume (unsigned int uid, int volume)=0
 
virtual int muteRemoteAudioStream (uid_t userId, 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) AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int muteRemoteVideoStream (uid_t userId, bool mute)=0
 
virtual int setRemoteVideoStreamType (uid_t userId, REMOTE_VIDEO_STREAM_TYPE streamType)=0
 
virtual int setRemoteDefaultVideoStreamType (REMOTE_VIDEO_STREAM_TYPE streamType)=0
 
virtual int enableAudioVolumeIndication (int interval, int smooth, bool report_vad)=0
 
virtual int enableLocalVoicePitchCallback (int interval)=0
 
virtual int startAudioRecording (const char *filePath, AUDIO_RECORDING_QUALITY_TYPE quality) AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int startAudioRecording (const char *filePath, int sampleRate, AUDIO_RECORDING_QUALITY_TYPE quality) AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int startAudioRecording (const AudioRecordingConfiguration &config)=0
 
virtual int stopAudioRecording ()=0
 
virtual int startAudioMixing (const char *filePath, bool loopback, bool replace, int cycle) AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int startAudioMixing (const char *filePath, bool loopback, bool replace, int cycle, int startPos)=0
 
virtual int setAudioMixingPlaybackSpeed (int speed)=0
 
virtual int stopAudioMixing ()=0
 
virtual int pauseAudioMixing ()=0
 
virtual int selectAudioTrack (int index)=0
 
virtual int getAudioTrackCount ()=0
 
virtual int setAudioMixingDualMonoMode (agora::media::AUDIO_MIXING_DUAL_MONO_MODE mode)=0
 
virtual int resumeAudioMixing ()=0
 
virtual int setHighQualityAudioParameters (bool fullband, bool stereo, bool fullBitrate)=0
 
virtual int adjustAudioMixingVolume (int volume)=0
 
virtual int adjustAudioMixingPlayoutVolume (int volume)=0
 
virtual int getAudioMixingPlayoutVolume ()=0
 
virtual int adjustAudioMixingPublishVolume (int volume)=0
 
virtual int getAudioMixingPublishVolume ()=0
 
virtual int getAudioMixingDuration () AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int getAudioMixingCurrentPosition ()=0
 
virtual int setAudioMixingPosition (int pos)=0
 
virtual int setAudioMixingPitch (int pitch)=0
 
virtual int getEffectsVolume ()=0
 
virtual int setEffectsVolume (int volume)=0
 
virtual int setVolumeOfEffect (int soundId, int volume)=0
 
virtual int enableFaceDetection (bool enable)=0
 
virtual int playEffect (int soundId, const char *filePath, int loopCount, double pitch, double pan, int gain, bool publish=false) AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int playEffect (int soundId, const char *filePath, int loopCount, double pitch, double pan, int gain, bool publish, int startPos)=0
 
virtual int stopEffect (int soundId)=0
 
virtual int stopAllEffects ()=0
 
virtual int preloadEffect (int soundId, const char *filePath)=0
 
virtual int unloadEffect (int soundId)=0
 
virtual int pauseEffect (int soundId)=0
 
virtual int pauseAllEffects ()=0
 
virtual int resumeEffect (int soundId)=0
 
virtual int resumeAllEffects ()=0
 
virtual int getEffectDuration (const char *filePath)=0
 
virtual int setEffectPosition (int soundId, int pos)=0
 
virtual int getEffectCurrentPosition (int soundId)=0
 
virtual int getAudioFileInfo (const char *filePath)=0
 
virtual int enableDeepLearningDenoise (bool enable)=0
 
virtual int enableSoundPositionIndication (bool enabled)=0
 
virtual int setRemoteVoicePosition (uid_t uid, double pan, double gain)=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 setLocalVoiceChanger (VOICE_CHANGER_PRESET voiceChanger) AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int setLocalVoiceReverbPreset (AUDIO_REVERB_PRESET reverbPreset) AGORA_DEPRECATED_ATTRIBUTE=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 setLogFile (const char *filePath) AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int setLogFilter (unsigned int filter) AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int setLogFileSize (unsigned int fileSizeInKBytes) AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int setLocalRenderMode (RENDER_MODE_TYPE renderMode) AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int setLocalRenderMode (RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode)=0
 
virtual int setRemoteRenderMode (uid_t userId, RENDER_MODE_TYPE renderMode) AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int setRemoteRenderMode (uid_t userId, RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode)=0
 
virtual int setLocalVideoMirrorMode (VIDEO_MIRROR_MODE_TYPE mirrorMode) AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int enableDualStreamMode (bool enabled)=0
 
virtual int setExternalAudioSource (bool enabled, int sampleRate, int channels)=0
 
virtual int setExternalAudioSink (bool enabled, int sampleRate, int channels)=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 samplesPerCall)=0
 
virtual int adjustRecordingSignalVolume (int volume)=0
 
virtual int adjustPlaybackSignalVolume (int volume)=0
 
virtual int adjustLoopbackRecordingSignalVolume (int volume)=0
 
virtual int enableWebSdkInteroperability (bool enabled) AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int setVideoQualityParameters (bool preferFrameRateOverImageQuality)=0
 
virtual int setLocalPublishFallbackOption (STREAM_FALLBACK_OPTIONS option)=0
 
virtual int setRemoteSubscribeFallbackOption (STREAM_FALLBACK_OPTIONS option)=0
 
virtual int switchCamera ()=0
 
virtual int setDefaultAudioRouteToSpeakerphone (bool defaultToSpeaker)=0
 
virtual int setEnableSpeakerphone (bool speakerOn)=0
 
virtual int enableInEarMonitoring (bool enabled)=0
 
virtual int setInEarMonitoringVolume (int volume)=0
 
virtual bool isSpeakerphoneEnabled ()=0
 
virtual int setAudioSessionOperationRestriction (AUDIO_SESSION_OPERATION_RESTRICTION restriction)=0
 
virtual int enableLoopbackRecording (bool enabled, const char *deviceName=NULL)=0
 
virtual IScreenCaptureSourceListgetScreenCaptureSources (const SIZE &thumbSize, const SIZE &iconSize, const bool includeScreen)=0
 
virtual int startScreenCaptureByDisplayId (unsigned int displayId, const Rectangle &regionRect, const ScreenCaptureParameters &captureParams)=0
 
virtual int startScreenCaptureByScreenRect (const Rectangle &screenRect, const Rectangle &regionRect, const ScreenCaptureParameters &captureParams)=0
 
virtual int startScreenCaptureByWindowId (view_t windowId, const Rectangle &regionRect, const ScreenCaptureParameters &captureParams)=0
 
virtual int setScreenCaptureContentHint (VideoContentHint contentHint)=0
 
virtual int setScreenCaptureScenario (SCREEN_SCENARIO_TYPE screenScenario)=0
 
virtual int updateScreenCaptureParameters (const ScreenCaptureParameters &captureParams)=0
 
virtual int updateScreenCaptureRegion (const Rectangle &regionRect)=0
 
virtual int stopScreenCapture ()=0
 
virtual int startScreenCapture (WindowIDType windowId, int captureFreq, const Rect *rect, int bitrate)=0
 
virtual int updateScreenCaptureRegion (const Rect *rect)=0
 
virtual bool setVideoSource (IVideoSource *source)=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 const char * getVersion (int *build)=0
 
virtual int enableLastmileTest ()=0
 
virtual int disableLastmileTest ()=0
 
virtual int startLastmileProbeTest (const LastmileProbeConfig &config)=0
 
virtual int stopLastmileProbeTest ()=0
 
virtual const char * getErrorDescription (int code)=0
 
virtual int setEncryptionSecret (const char *secret) AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int setEncryptionMode (const char *encryptionMode) AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int enableEncryption (bool enabled, const EncryptionConfig &config)=0
 
virtual int registerPacketObserver (IPacketObserver *observer)=0
 
virtual int createDataStream (int *streamId, bool reliable, bool ordered) AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int createDataStream (int *streamId, DataStreamConfig &config)=0
 
virtual int sendStreamMessage (int streamId, const char *data, size_t length)=0
 
virtual int addPublishStreamUrl (const char *url, bool transcodingEnabled) AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int removePublishStreamUrl (const char *url) AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int setLiveTranscoding (const LiveTranscoding &transcoding) AGORA_DEPRECATED_ATTRIBUTE=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 addVideoWatermark (const RtcImage &watermark)=0
 
virtual int addVideoWatermark (const char *watermarkUrl, const WatermarkOptions &options)=0
 
virtual int clearVideoWatermarks ()=0
 
virtual int setBeautyEffectOptions (bool enabled, BeautyOptions options)=0
 
virtual int setLowlightEnhanceOptions (bool enabled, LowLightEnhanceOptions options)=0
 
virtual int setVideoDenoiserOptions (bool enabled, VideoDenoiserOptions options)=0
 
virtual int setColorEnhanceOptions (bool enabled, ColorEnhanceOptions options)=0
 
virtual int enableVirtualBackground (bool enabled, VirtualBackgroundSource backgroundSource)=0
 
virtual int addInjectStreamUrl (const char *url, const InjectStreamConfig &config)=0
 
virtual int startChannelMediaRelay (const ChannelMediaRelayConfiguration &configuration)=0
 
virtual int updateChannelMediaRelay (const ChannelMediaRelayConfiguration &configuration)=0
 
virtual int pauseAllChannelMediaRelay ()=0
 
virtual int resumeAllChannelMediaRelay ()=0
 
virtual int stopChannelMediaRelay ()=0
 
virtual int removeInjectStreamUrl (const char *url)=0
 
virtual bool registerEventHandler (IRtcEngineEventHandler *eventHandler)=0
 
virtual bool unregisterEventHandler (IRtcEngineEventHandler *eventHandler)=0
 
virtual int sendCustomReportMessage (const char *id, const char *category, const char *event, const char *label, int value)=0
 
virtual CONNECTION_STATE_TYPE getConnectionState ()=0
 
virtual int enableRemoteSuperResolution (uid_t userId, bool enable) AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int enableRemoteSuperResolution (bool enabled, SR_MODE mode, uid_t userId)=0
 
virtual int registerMediaMetadataObserver (IMetadataObserver *observer, IMetadataObserver::METADATA_TYPE type)=0
 
virtual int setParameters (const char *parameters)=0
 
virtual int setLocalVideoRenderer (IVideoSink *videoSink)=0
 
virtual int setRemoteVideoRenderer (uid_t uid, IVideoSink *videoSink)=0
 
virtual int setCameraTorchOn (bool isOn)=0
 
virtual bool isCameraTorchSupported ()=0
 
virtual int setCameraZoomFactor (float factor)=0
 
virtual float getCameraMaxZoomFactor ()=0
 
virtual bool isCameraZoomSupported ()=0
 
virtual bool isCameraFocusSupported ()=0
 
virtual bool isCameraExposurePositionSupported ()=0
 
virtual bool isCameraAutoFocusFaceModeSupported ()=0
 
virtual int setCameraFocusPositionInPreview (float positionX, float positionY)=0
 
virtual int setCameraExposurePosition (float positionXinView, float positionYinView)=0
 
virtual int setCameraAutoFocusFaceModeEnabled (bool enabled)=0
 
virtual int takeSnapshot (const char *channel, uid_t uid, const char *filePath)=0
 

Static Public Member Functions

static AGORA_CPP_API void release (bool sync=false)
 

Protected Member Functions

virtual ~IRtcEngine ()
 

Detailed Description

IRtcEngine is the base interface class of the Agora SDK that provides the main Agora SDK methods invoked by your application. Enable the Agora SDK's communication functionality through the creation of an IRtcEngine object, then call the methods of this object.

Member Typedef Documentation

◆ WindowIDType [1/2]

◆ WindowIDType [2/2]

Constructor & Destructor Documentation

◆ ~IRtcEngine()

virtual agora::rtc::IRtcEngine::~IRtcEngine ( )
inlineprotectedvirtual

Member Function Documentation

◆ initialize()

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

Initializes the Agora service.

Unless otherwise specified, all the methods provided by the IRtcEngine class are executed asynchronously. Agora recommends calling these methods in the same thread.

Note
Ensure that you call the createAgoraRtcEngine and initialize methods before calling any other APIs.
Parameters
contextPointer to the RTC engine context. See RtcEngineContext.
Returns
  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2(ERR_INVALID_ARGUMENT): No IRtcEngineEventHandler object is specified.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized. Check whether context is properly set.
    • -22(ERR_RESOURCE_LIMITED): The resource is limited. The app uses too much of the system resource and fails to allocate any resources.
    • -101(ERR_INVALID_APP_ID): The App ID is invalid.

◆ release()

static AGORA_CPP_API void agora::rtc::IRtcEngine::release ( bool  sync = false)
static

Releases all IRtcEngine resources.

Use this method for apps in which users occasionally make voice or video calls. When users do not make calls, you can free up resources for other operations. Once you call release to destroy the created IRtcEngine instance, you cannot use any method or callback in the SDK any more. If you want to use the real-time communication functions again, you must call createAgoraRtcEngine and initialize to create a new IRtcEngine instance.

Note
If you want to create a new IRtcEngine instance after destroying the current one, ensure that you wait till the release method completes executing.
Parameters
sync
  • true: Synchronous call. Agora suggests calling this method in a sub-thread to avoid congestion in the main thread because the synchronous call and the app cannot move on to another task until the execution completes. Besides, you cannot call this method in any method or callback of the SDK. Otherwise, the SDK cannot release the resources occupied by the IRtcEngine instance until the callbacks return results, which may result in a deadlock. The SDK automatically detects the deadlock and converts this method into an asynchronous call, causing the test to take additional time.
  • false: Asynchronous call. Do not immediately uninstall the SDK's dynamic library after the call, or it may cause a crash due to the SDK clean-up thread not quitting.

◆ setChannelProfile()

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

Sets the channel profile of the Agora IRtcEngine.

After initialization, the SDK uses the CHANNEL_PROFILE_COMMUNICATION channel profile by default. You can call this method to set the channel profile. The Agora IRtcEngine differentiates channel profiles and applies optimization algorithms accordingly. For example, it prioritizes smoothness and low latency for a video call, and prioritizes video quality for the interactive live video streaming.

Warning
  • 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.
  • The default audio route and video encoding bitrate are different in different channel profiles. For details, see setDefaultAudioRouteToSpeakerphone and setVideoEncoderConfiguration.
Parameters
profileThe channel profile of the Agora IRtcEngine. See CHANNEL_PROFILE_TYPE
Returns
  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -2 (ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

◆ setClientRole() [1/2]

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

Sets the role of the user in interactive live streaming.

After calling setChannelProfile (CHANNEL_PROFILE_LIVE_BROADCASTING), the SDK sets the user role as audience by default. You can call setClientRole to set the user role as host.

You can call this method either before or after joining a channel. If you call this method to switch the user role after joining a channel, the SDK automatically does the following:

Note
This method applies to the LIVE_BROADCASTING profile only.
Parameters
roleThe role of a user in interactive live streaming. See CLIENT_ROLE_TYPE.
Returns
  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -5 (ERR_REFUSED): The request is rejected. In multichannel scenarios, if you have set any of the following in one channel, the SDK returns this error code when the user switches the user role to host in another channel:
      • Call joinChannel with the options parameter and use the default settings publishLocalAudio = true or publishLocalVideo = true.
      • Call setClientRole to set the user role as host.
      • Call muteLocalAudioStream(false) or muteLocalVideoStream(false).
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

◆ setClientRole() [2/2]

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

Sets the role of the user in interactive live streaming.

Since
v3.2.0

In the LIVE_BROADCASTING channel profile, the SDK sets the user role as audience by default. You can call setClientRole to set the user role as host.

You can call this method either before or after joining a channel. If you call this method to switch the user role after joining a channel, the SDK automatically does the following:

Note
  • This method applies to the LIVE_BROADCASTING profile only.
  • The difference between this method and setClientRole [1/2] is that this method can set the user level in addition to the user role.
    • The user role determines the permissions that the SDK grants to a user, such as permission to send local streams, receive remote streams, and push streams to a CDN address.
    • The user level determines the level of services that a user can enjoy within the permissions of the user's role. For example, an audience member can choose to receive remote streams with low latency or ultra low latency. User level affects the pricing of services.
Parameters
roleThe role of a user in interactive live streaming. See CLIENT_ROLE_TYPE.
optionsThe detailed options of a user, including user level. See ClientRoleOptions.
Returns
  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -5 (ERR_REFUSED): The request is rejected. In multichannel scenarios, if you have set any of the following in one channel, the SDK returns this error code when the user switches the user role to host in another channel:
      • Call joinChannel with the options parameter and use the default settings publishLocalAudio = true or publishLocalVideo = true.
      • Call setClientRole to set the user role as host.
      • Call muteLocalAudioStream(false) or muteLocalVideoStream(false).
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

◆ 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 with the user ID.

Users in the same channel can talk to each other, and multiple users in the same channel can start a group chat. Users with different App IDs cannot call each other.

You must call the leaveChannel method to exit the current call before entering another channel.

A successful joinChannel method call triggers the following callbacks:

  • The local client: onJoinChannelSuccess.
  • The remote client: onUserJoined , if the user joining the channel is in the COMMUNICATION profile, or is a host in the LIVE_BROADCASTING profile.

When the connection between the client and Agora's server is interrupted due to poor network conditions, the SDK tries reconnecting to the server. When the local client successfully rejoins the channel, the SDK triggers the onRejoinChannelSuccess callback on the local client.

Once the user joins the channel (switches to another channel), the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. If you do not want to subscribe to a specified stream or all remote streams, call the mute methods accordingly.

Note
A channel does not accept duplicate uids, such as two users with the same uid. If you set uid as 0, the system automatically assigns a uid. If you want to join a channel from different devices, ensure that each device has a different uid.
Warning
Ensure that the App ID used for creating the token is the same App ID used by the initialize method for initializing the RTC engine. Otherwise, the CDN live streaming may fail.
Parameters
tokenThe token generated at your server. See Authenticate Your Users with Tokens.
channelIdPointer to the unique channel name for the Agora RTC session in the string format smaller than 64 bytes. Supported characters:
  • 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) Pointer to additional information about the channel. This parameter can be set to NULL or contain channel related information. Other users in the channel will not receive this message.
uid(Optional) User ID. A 32-bit unsigned integer with a value ranging from 1 to 232-1. The uid must be unique. If a uid is not assigned (or set to 0), the SDK assigns and returns a uid in the onJoinChannelSuccess callback. Your application must record and maintain the returned uid, because the SDK does not do so.
Returns
  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -3(ERR_NOT_READY): The SDK fails to be initialized. You can try re-initializing the SDK.
    • -5(ERR_REFUSED): The request is rejected. This may be caused by the following:
      • You have created an IChannel object with the same channel name.
      • You have joined and published a stream in a channel created by the IChannel object. When you join a channel created by the IRtcEngine object, the SDK publishes the local audio and video streams to that channel by default. Because the SDK does not support publishing a local stream to more than one channel simultaneously, an error occurs in this occasion.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method.
    • -17(ERR_JOIN_CHANNEL_REJECTED): The request to join the channel is rejected. The SDK supports joining only one IRtcEngine channel at a time. Therefore, the SDK returns this error code when a user who has already joined an IRtcEngine channel calls the joining channel method of the IRtcEngine class with a valid channel name.

◆ joinChannel() [2/2]

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

Joins a channel with the user ID, and configures whether to publish or automatically subscribe to the audio or video streams.

Since
v3.3.0

Users in the same channel can talk to each other, and multiple users in the same channel can start a group chat. Users with different App IDs cannot call each other.

You must call the leaveChannel method to exit the current call before entering another channel.

A successful joinChannel method call triggers the following callbacks:

  • The local client: onJoinChannelSuccess.
  • The remote client: onUserJoined, if the user joining the channel is in the COMMUNICATION profile, or is a host in the LIVE_BROADCASTING profile.

When the connection between the client and the Agora server is interrupted due to poor network conditions, the SDK tries reconnecting to the server. When the local client successfully rejoins the channel, the SDK triggers the onRejoinChannelSuccess callback on the local client.

Note
  • Compared with joinChannel [1/2], this method has the options parameter, which configures whether the user publishes or automatically subscribes to the audio and video streams in the channel when joining the channel. By default, the user publishes the local audio and video streams and automatically subscribes to the audio and video streams of all the other users in the channel. Subscribing incurs all associated usage costs. To unsubscribe, set the options parameter or call the mute methods accordingly.
  • Ensure that the App ID used for generating the token is the same App ID used in the initialize method for creating an IRtcEngine object.
Parameters
tokenThe token generated at your server. See Authenticate Your Users with Tokens.
channelIdPointer to the unique channel name for the Agora RTC session in the string format smaller than 64 bytes. Supported characters:
  • 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) Reserved for future use.
uid(Optional) User ID. A 32-bit unsigned integer with a value ranging from 1 to 232-1. The uid must be unique. If a uid is not assigned (or set to 0), the SDK assigns and returns a uid in the onJoinChannelSuccess callback. Your application must record and maintain the returned uid, because the SDK does not do so. Note: The ID of each user in the channel should be unique. If you want to join the same channel from different devices, ensure that the user IDs in all devices are different.
optionsThe channel media options: ChannelMediaOptions.
Returns
  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -3(ERR_NOT_READY): The SDK fails to be initialized. You can try re-initializing the SDK.
    • -5(ERR_REFUSED): The request is rejected. This may be caused by the following:
      • You have created an IChannel object with the same channel name.
      • You have joined and published a stream in a channel created by the IChannel object. When you join a channel created by the IRtcEngine object, the SDK publishes the local audio and video streams to that channel by default. Because the SDK does not support publishing a local stream to more than one channel simultaneously, an error occurs in this occasion.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method.
    • -17(ERR_JOIN_CHANNEL_REJECTED): The request to join the channel is rejected. The SDK supports joining only one IRtcEngine channel at a time. Therefore, the SDK returns this error code when a user who has already joined an IRtcEngine channel calls the joining channel method of the IRtcEngine class with a valid channel name.

◆ switchChannel() [1/2]

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

Switches to a different channel.

This method allows the audience of a LIVE_BROADCASTING channel to switch to a different channel.

After the user successfully switches to another channel, the onLeaveChannel and onJoinChannelSuccess callbacks are triggered to indicate that the user has left the original channel and joined a new one.

Once the user switches to another channel, the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. If you do not want to subscribe to a specified stream or all remote streams, call the mute methods accordingly.

Note
This method applies to the audience role in a LIVE_BROADCASTING channel only.
Parameters
tokenThe token generated at your server. See Authenticate Your Users with Tokens.
channelIdUnique 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
Returns
  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -5(ERR_REFUSED): The request is rejected, probably because the user is not an audience.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.
    • -102(ERR_INVALID_CHANNEL_NAME): The channel name is invalid.
    • -113(ERR_NOT_IN_CHANNEL): The user is not in the channel.

◆ switchChannel() [2/2]

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

Switches to a different channel, and configures whether to automatically subscribe to audio or video streams in the target channel.

Since
v3.3.0

This method allows the audience of a LIVE_BROADCASTING channel to switch to a different channel.

After the user successfully switches to another channel, the onLeaveChannel and onJoinChannelSuccess callbacks are triggered to indicate that the user has left the original channel and joined a new one.

Note
  • This method applies to the audience role in a LIVE_BROADCASTING channel only.
  • The difference between this method and switchChannel[1/2] is that the former adds the options parameter to configure whether the user automatically subscribes to all remote audio and video streams in the target channel. By default, the user subscribes to the audio and video streams of all the other users in the target channel, thus incurring all associated usage costs. To unsubscribe, set the options parameter or call the mute methods accordingly.
Parameters
tokenThe token generated at your server. See Authenticate Your Users with Tokens.
channelIdUnique 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
optionsThe channel media options: ChannelMediaOptions.
Returns
  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -5(ERR_REFUSED): The request is rejected, probably because the user is not an audience.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.
    • -102(ERR_INVALID_CHANNEL_NAME): The channel name is invalid.
    • -113(ERR_NOT_IN_CHANNEL): The user is not in the channel.

◆ leaveChannel()

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

Allows a user to leave a channel, such as hanging up or exiting a call.

After joining a channel, the user must call the leaveChannel method to end the call before joining another channel.

This method returns 0 if the user leaves the channel and releases all resources related to the call.

This method call is asynchronous, and the user has not left the channel when the method call returns. Once the user leaves the channel, the SDK triggers the onLeaveChannel callback.

A successful leaveChannel method call triggers the following callbacks:

  • The local client: onLeaveChannel
  • The remote client: onUserOffline , if the user leaving the channel is in the COMMUNICATION channel, or is a host in the LIVE_BROADCASTING profile.
Note
  • If you call the release method immediately after the leaveChannel method, the leaveChannel process interrupts, and the onLeaveChannel callback is not triggered.
  • If you call the leaveChannel method during a CDN live streaming, the SDK triggers the removePublishStreamUrl method.
Returns
  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

◆ renewToken()

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

Gets a new token when the current token expires after a period of time.

The token expires after a period of time once the token schema is enabled when:

The application should call this method to get the new token. Failure to do so will result in the SDK disconnecting from the server.

Parameters
tokenThe new token.
Returns
  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

◆ queryInterface()

virtual int agora::rtc::IRtcEngine::queryInterface ( INTERFACE_ID_TYPE  iid,
void **  inter 
)
pure virtual

Gets the pointer to the device manager object.

Parameters
iidID of the interface.
interPointer to the DeviceManager object.
Returns
  • 0: Success.
  • < 0: Failure.

◆ 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 the user account is unique 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:

Once the user joins the channel (switches to another channel), the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. If you do not want to subscribe to a specified stream or all remote streams, call the mute methods accordingly.

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.
  • Before using a String user name, ensure that you read How can I use string user names for getting details about the limitations and implementation steps.
Parameters
tokenThe token generated at your server. See Authenticate Your Users with Tokens.
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 the user account is unique 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

◆ 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, and configures whether to publish or automatically subscribe to the audio or video streams.

Since
v3.3.0

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

Note
  • Compared with joinChannelWithUserAccount [1/2], this method has the options parameter, which configures whether the user publishes or automatically subscribes to the audio and video streams in the channel when joining the channel. By default, the user publishes the local audio and video streams and automatically subscribes to the audio and video streams of all the other users in the channel. Subscribing incurs all associated usage costs. To unsubscribe, set the options parameter or call the mute methods accordingly.
  • 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.
  • Before using a String user name, ensure that you read How can I use string user names for getting details about the limitations and implementation steps.
Parameters
tokenThe token generated at your server. See Authenticate Your Users with Tokens.
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 the user account is unique 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.
    • ERR_INVALID_ARGUMENT (-2)
    • ERR_NOT_READY (-3)
    • ERR_REFUSED (-5)
    • -17(ERR_JOIN_CHANNEL_REJECTED): The request to join the channel is rejected. The SDK supports joining only one IRtcEngine channel at a time. Therefore, the SDK returns this error code when a user who has already joined an IRtcEngine channel calls the joining channel method of the IRtcEngine class with a valid channel name.

◆ getUserInfoByUserAccount()

virtual int agora::rtc::IRtcEngine::getUserInfoByUserAccount ( const char *  userAccount,
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,
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.

◆ startEchoTest() [1/3]

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

Starts an audio call test.

Deprecated:
This method is deprecated as of v2.4.0.

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

To conduct the test:

  • The user speaks and the recording is played back within 10 seconds.
  • If the user can hear the recording within 10 seconds, the audio devices and network connection are working properly.
Note
  • After calling this method, always call the stopEchoTest method to end the test. Otherwise, the application cannot run the next echo test.
  • In the LIVE_BROADCASTING profile, only the hosts can call this method. If the user switches from the COMMUNICATION toLIVE_BROADCASTING profile, the user must call the setClientRole method to change the user role from the audience (default) to the host before calling this 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 an audio and video call loop test.

Since
v3.5.2

Before joining a channel, to test whether the user's local sending and receiving streams are normal, you can call this method to perform an audio and video call loop test, which tests whether the audio and video devices and the user's upstream and downstream networks are working properly.

After starting the test, the user needs to make a sound or face the camera. The audio or video is output after about two seconds. If the audio playback is normal, the audio device and the user's upstream and downstream networks are working properly; if the video playback is normal, the video device and the user's upstream and downstream networks are working properly.

Note
  • Call this method before joining a channel.
  • After calling this method, call stopEchoTest to end the test; otherwise, the user cannot perform the next audio and video call loop test and cannot join the channel.
  • In the LIVE_BROADCASTING profile, only a host can call this method.
Parameters
configThe configuration of the audio and video call loop test. See EchoTestConfiguration.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopEchoTest()

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

Stops call loop test.

After calling startEchoTest [2/3] or startEchoTest [3/3], call this method if you want to stop the call loop test.

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 users' network access is restricted by a firewall, configure the firewall to allow specific IP addresses and ports provided by Agora; then, call this method to enable the cloud proxy and set the cloud proxy type with the proxyType parameter.

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

As of v3.6.2, when a user calls this method and then joins a channel successfully, the SDK triggers the onProxyConnected callback to report the user ID, the proxy type connected, and the time elapsed from the user calling joinChannel until this callback is triggered.

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 with the desired proxyType.

Note
  • Agora recommends that you call this method before joining the channel or after leaving the channel.
  • For the SDK v3.3.x, when users use the Force UDP cloud proxy, the services for Media Push and cohosting across channels are not available; for the SDK v3.4.0 or later, when users behind a firewall use the Force UDP cloud proxy, the services for Media Push and cohosting across channels are not available.
  • When you use the Force TCP cloud proxy, note the following:
    • An error occurs when calling startAudioMixing to play online music files in the HTTP protocol.
    • The services for Media Push and cohosting across channels use the cloud proxy with the TCP 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.

◆ enableVideo()

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

Enables the video module.

Call this method either before joining a channel or during a call. If this method is called before joining a channel, the call starts in the video mode. If this method is called during an audio call, the audio mode switches to the video mode. To disable the video module, call the disableVideo method.

A successful enableVideo method call triggers the onUserEnableVideo (true) callback on the remote client.

Note
  • This method affects the internal engine and can be called after the leaveChannel method.
  • This method resets the internal engine and takes some time to take effect. We recommend using the following API methods to control the video engine modules separately:
Returns
  • 0: Success.
  • < 0: Failure.

◆ disableVideo()

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

Disables the video module.

This method can be called before joining a channel or during a call. If this method is called before joining a channel, the call starts in audio mode. If this method is called during a video call, the video mode switches to the audio mode. To enable the video module, call the enableVideo method.

A successful disableVideo method call triggers the onUserEnableVideo (false) callback on the remote client.

Note
  • This method affects the internal engine and can be called after the leaveChannel method.
  • This method resets the internal engine and takes some time to take effect. We recommend using the following APIs to control the video engine modules separately:
Returns
  • 0: Success.
  • < 0: Failure.

◆ setVideoProfile()

virtual int agora::rtc::IRtcEngine::setVideoProfile ( VIDEO_PROFILE_TYPE  profile,
bool  swapWidthAndHeight 
)
pure virtual

Sets the video profile.

Deprecated:
This method is deprecated as of v2.3. Use the setVideoEncoderConfiguration method instead.

Each video profile includes a set of parameters, such as the resolution, frame rate, and bitrate. If the camera device does not support the specified resolution, the SDK automatically chooses a suitable camera resolution, keeping the encoder resolution specified by the setVideoProfile method.

Note
  • You can call this method either before or after joining a channel.
  • If you do not need to set the video profile after joining the channel, call this method before the enableVideo method to reduce the render time of the first video frame.
  • Always set the video profile before calling the joinChannel or startPreview method.
Parameters
profileSets the video profile. See VIDEO_PROFILE_TYPE.
swapWidthAndHeightSets whether to swap the width and height of the video stream:
  • true: Swap the width and height.
  • false: (Default) Do not swap the width and height. The width and height of the output video are consistent with the set video profile.
Note
Since the landscape or portrait mode of the output video can be decided directly by the video profile, We recommend setting swapWidthAndHeight to false (default).
Returns
  • 0: Success.
  • < 0: Failure.

◆ setVideoEncoderConfiguration()

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

Sets the video encoder configuration.

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

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.

Note
  • You can call this method either before or after joining a channel.
  • If you do not need to set the video encoder configuration after joining the channel, you can call this method before the enableVideo method to reduce the render time of the first video frame.
Parameters
configSets the local video encoder configuration. See VideoEncoderConfiguration.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setCameraCapturerConfiguration()

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

Sets the camera capture configuration.

For a video call or the interactive live video streaming, generally the SDK controls the camera output parameters. When the default camera capturer settings do not meet special requirements or cause performance problems, we recommend using this method to set the camera capturer 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.

◆ setupLocalVideo()

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

Initializes the local video view.

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

Call this method to bind the local video stream to a video view and to set the rendering and mirror modes of the video view. The binding is still valid after the user leaves the channel, which means that the window still displays. To unbind the view, set the view in VideoCanvas to NULL.

Note
  • You can call this method either before or after joining a channel.
  • During a call, you can call this method as many times as necessary to update the display mode of the local video view.
Parameters
canvasPointer to the local video view and settings. See VideoCanvas.
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.

Call this method to bind the remote video stream to a video view and to set the rendering and mirror modes of the video view.

The application specifies the uid of the remote video in this method before the remote user joins the channel. If the remote uid is unknown to the application, set it after the application receives the onUserJoined callback. If the Video Recording function is enabled, the Video Recording Service joins the channel as a dummy client, causing other clients to also receive the onUserJoined callback. Do not bind the dummy client to the application view because the dummy client does not send any video streams. If your application does not recognize the dummy client, bind the remote user to the view when the SDK triggers the onFirstRemoteVideoDecoded callback. To unbind the remote user from the view, set the view in VideoCanvas to NULL. Once the remote user leaves the channel, the SDK unbinds the remote user.

Note
To update the rendering or mirror mode of the remote video view during a call, use the setRemoteRenderMode method.
Parameters
canvasPointer to the remote video view and settings. See VideoCanvas.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startPreview()

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

Starts the local video preview before joining the channel.

Before calling this method, you must:

  • Call the setupLocalVideo method to set up the local preview window and configure the attributes.
  • Call the enableVideo method to enable video.
Note
Once the startPreview method is called to start the local video preview, if you leave the channel by calling the leaveChannel method, the local video preview remains until you call the stopPreview method to disable it.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteUserPriority()

virtual int agora::rtc::IRtcEngine::setRemoteUserPriority ( uid_t  uid,
PRIORITY_TYPE  userPriority 
)
pure virtual

Prioritizes a remote user's stream.

The SDK ensures the high-priority user gets the best possible stream quality.

Note
  • The Agora SDK supports setting userPriority as high for one user only.
  • Ensure that you call this method before joining a channel.
Parameters
uidThe ID of the remote user.
userPrioritySets the priority of the remote user. See PRIORITY_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopPreview()

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

Stops the local video preview.

After calling startPreview, if you want to stop the local video preview, call stopPreview.

Note
Call this method before you join the channel or after you leave the channel.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableAudio()

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

Enables the audio module.

The audio mode is enabled by default.

Note
  • This method affects the audio module and can be called after the leaveChannel method. You can call this method either before or after joining a channel.
  • This method enables the audio module and takes some time to take effect. Agora recommends using the following API methods to control the audio module separately:
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableLocalAudio()

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

Disables/Re-enables the local audio function.

The audio function is enabled by default. This method disables or re-enables the local audio function, that is, to stop or restart local audio capturing.

This method does not affect receiving 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.

Once the local audio function is disabled or re-enabled, the SDK triggers the onLocalAudioStateChanged callback, which reports LOCAL_AUDIO_STREAM_STATE_STOPPED(0) or LOCAL_AUDIO_STREAM_STATE_RECORDING(1).

Note
  • This method is different from the muteLocalAudioStream method:
    • enableLocalAudio: Disables/Re-enables the local audio capturing and processing. If you disable or re-enable local audio capturing using the enableLocalAudio method, the local user may hear a pause in the remote audio playback.
    • muteLocalAudioStream: Sends/Stops sending the local audio streams.
  • This method can be called either before or after you join a channel. Calling it before you join a channel can set the device state only, and it takes effect immediately after you join the channel.
Parameters
enabledSets whether to disable/re-enable the local audio function:
  • true: (Default) Re-enable the local audio function, that is, to start the local audio capturing device (for example, the microphone).
  • false: Disable the local audio function, that is, to stop local audio capturing.
Returns
  • 0: Success.
  • < 0: Failure.

◆ disableAudio()

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

Disables the audio module.

Note
  • This method affects the internal engine and can be called after the leaveChannel method. You can call this method either before or after joining a channel.
  • This method resets the internal engine and takes some time to take effect. We recommend using the enableLocalAudio and muteLocalAudioStream methods to capture, process, and send the local audio streams.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setAudioProfile()

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

Sets the audio parameters and application scenarios.

Note
  • The setAudioProfile method must be called before the joinChannel method.
  • In the COMMUNICATION and LIVE_BROADCASTING profiles, the bitrate may be different from your settings due to network self-adaptation.
  • In scenarios requiring high-quality audio, for example, a music teaching scenario, we recommend setting profile as AUDIO_PROFILE_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. See AUDIO_PROFILE_TYPE.
scenarioSets the audio application scenario. See AUDIO_SCENARIO_TYPE. Under different audio scenarios, the device uses different volume types. For details, see What is the difference between the in-call volume and the media volume?.
Returns
  • 0: Success.
  • < 0: Failure.

◆ muteLocalAudioStream()

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

Stops or resumes publishing the local audio stream.

As of v3.4.5, this method only sets the publishing state of the audio stream in the channel of IRtcEngine.

A successful method call triggers the onUserMuteAudio callback on the remote client.

You can only publish the local stream in one channel at a time. If you create multiple channels, ensure that you only call muteLocalAudioStream (false) in one channel; otherwise, the method call fails, and the SDK returns -5 (ERR_REFUSED).

Note
  • This method does not change the usage state of the audio-capturing device.
  • Whether this method call takes effect is affected by the joinChannel [2/2] and setClientRole methods. For details, see Set the Publishing State.
Parameters
muteSets whether to stop publishing the local audio stream.
  • true: Stop publishing the local audio stream.
  • false: Resume publishing the local audio stream.
Returns
  • 0: Success.
  • < 0: Failure.
    • -5 (ERR_REFUSED): The request is rejected.

◆ muteAllRemoteAudioStreams()

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

Stops or resumes subscribing to the audio streams of all remote users.

After successfully calling this method, the local user stops or resumes subscribing to the audio streams of all remote users, including all subsequent users.

Note
  • Call this method after joining a channel.
  • As of v3.3.0, this method contains the function of setDefaultMuteAllRemoteAudioStreams. Agora recommends not calling muteAllRemoteAudioStreams and setDefaultMuteAllRemoteAudioStreams together; otherwise, the settings may not take effect. See Set the Subscribing State.
Parameters
muteSets whether to stop subscribing to the audio streams of all remote users.
  • true: Stop subscribing to the audio streams of all remote users.
  • false: (Default) Resume subscribing to the audio streams of all remote users.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setDefaultMuteAllRemoteAudioStreams()

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

Stops or resumes subscribing to the audio streams of all remote users by default.

Deprecated:
This method is deprecated from v3.3.0.

Call this method after joining a channel. After successfully calling this method, the local user stops or resumes subscribing to the audio streams of all subsequent users.

Note
If you need to resume subscribing to the audio streams of remote users in the channel after calling setDefaultMuteAllRemoteAudioStreams (true), do the following:
  • If you need to resume subscribing to the audio stream of a specified user, call muteRemoteAudioStream (false), and specify the user ID.
  • If you need to resume subscribing to the audio streams of multiple remote users, call muteRemoteAudioStream (false) multiple times.
Parameters
muteSets whether to stop subscribing to the audio streams of all remote users by default.
  • true: Stop subscribing to the audio streams of all remote users by default.
  • false: (Default) Resume subscribing to the audio streams of all remote users by default.
Returns
  • 0: Success.
  • < 0: Failure.

◆ adjustUserPlaybackSignalVolume()

virtual int agora::rtc::IRtcEngine::adjustUserPlaybackSignalVolume ( unsigned int  uid,
int  volume 
)
pure virtual

Adjusts the playback signal volume of a specified remote user.

You can call this method as many times as necessary to adjust the playback volume of different remote users, or to repeatedly adjust the playback volume of the same remote user.

Note
  • Call this method after joining a channel.
  • The playback volume here refers to the mixed volume of a specified remote user.
  • This method can only adjust the playback volume of one specified remote user at a time. To adjust the playback volume of different remote users, call the method as many times, once for each remote user.
Parameters
uidThe ID of the remote user.
volumeThe playback volume of the specified remote user. The value ranges between 0 and 100, including the following:
  • 0: Mute.
  • 100: (Default) Original volume.
Returns
  • 0: Success.
  • < 0: Failure.

◆ muteRemoteAudioStream()

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

Stops or resumes subscribing to the audio stream of a specified user.

Note
  • Call this method after joining a channel.
  • See recommended settings in Set the Subscribing State.
Parameters
userIdThe user ID of the specified remote user.
muteSets whether to stop subscribing to the audio stream of a specified user.
  • true: Stop subscribing to the audio stream of a specified user.
  • false: (Default) Resume subscribing to the audio stream of a specified user.
Returns
  • 0: Success.
  • < 0: Failure.

◆ muteLocalVideoStream()

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

Stops or resumes publishing the local video stream.

As of v3.4.5, this method only sets the publishing state of the video stream in the channel of IRtcEngine.

A successful method call triggers the onUserMuteVideo callback on the remote client.

You can only publish the local stream in one channel at a time. If you create multiple channels, ensure that you only call muteLocalVideoStream (false) in one channel; otherwise, the method call fails, and the SDK returns -5 (ERR_REFUSED).

Note
  • This method does not change the usage state of the video-capturing device.
  • Whether this method call takes effect is affected by the joinChannel [2/2] and setClientRole methods. For details, see Set the Publishing State.
Parameters
muteSets whether to stop publishing the local video stream.
  • true: Stop publishing the local video stream.
  • false: Resume publishing the local video stream.
Returns
  • 0: Success.
  • < 0: Failure.
    • -5 (ERR_REFUSED): The request is rejected.

◆ enableLocalVideo()

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

Enables/Disables the local video capture.

This method disables or re-enables the local video capturer, and does not affect receiving the remote video stream.

After you call the enableVideo method, the local video capturer is enabled by default. You can call enableLocalVideo(false) to disable the local video capturer. If you want to re-enable it, call enableLocalVideo(true).

After the local video capturer is successfully disabled or re-enabled, the SDK triggers the onUserEnableLocalVideo callback on the remote client.

Note
  • You can call this method either before or after joining a channel.
  • This method affects the internal engine and can be called after the leaveChannel method.
Parameters
enabledSets whether to disable/re-enable the local video, including the capturer, renderer, and sender:
  • true: (Default) Re-enable the local video.
  • false: Disable the local video. Once the local video is disabled, the remote users can no longer receive the video stream of this user, while this user can still receive the video streams of the other remote users.
Returns
  • 0: Success.
  • < 0: Failure.

◆ muteAllRemoteVideoStreams()

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

Stops or resumes subscribing to the video streams of all remote users.

After successfully calling this method, the local user stops or resumes subscribing to the video streams of all remote users, including all subsequent users.

Note
  • Call this method after joining a channel.
  • See recommended settings in Set the Subscribing State.
Parameters
muteSets whether to stop subscribing to the video streams of all remote users.
  • true: Stop subscribing to the video streams of all remote users.
  • false: (Default) Resume subscribing to the video streams of all remote users.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setDefaultMuteAllRemoteVideoStreams()

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

Stops or resumes subscribing to the video streams of all remote users by default.

Deprecated:
This method is deprecated from v3.3.0.

Call this method after joining a channel. After successfully calling this method, the local user stops or resumes subscribing to the video streams of all subsequent users.

Note
If you need to resume subscribing to the video streams of remote users in the channel after calling setDefaultMuteAllRemoteVideoStreams (true), do the following:
  • If you need to resume subscribing to the video stream of a specified user, call muteRemoteVideoStream (false), and specify the user ID.
  • If you need to resume subscribing to the video streams of multiple remote users, call muteRemoteVideoStream (false) multiple times.
Parameters
muteSets whether to stop subscribing to the video streams of all remote users by default.
  • true: Stop subscribing to the video streams of all remote users by default.
  • false: (Default) Resume subscribing to the video streams of all remote users by default.
Returns
  • 0: Success.
  • < 0: Failure.

◆ muteRemoteVideoStream()

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

Stops or resumes subscribing to the video stream of a specified user.

Note
  • Call this method after joining a channel.
  • See recommended settings in Set the Subscribing State.
Parameters
userIdThe user ID of the specified remote user.
muteSets whether to stop subscribing to the video stream of a specified user.
  • true: Stop subscribing to the video stream of a specified user.
  • false: (Default) Resume subscribing to the video stream of a specified user.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteVideoStreamType()

virtual int agora::rtc::IRtcEngine::setRemoteVideoStreamType ( uid_t  userId,
REMOTE_VIDEO_STREAM_TYPE  streamType 
)
pure virtual

Sets the stream type of the remote video.

Under limited network conditions, if the publisher has not disabled the dual-stream mode using enableDualStreamMode(false), the receiver can choose to receive either the high-quality video stream (the high resolution, and high bitrate video stream) or the low-video stream (the low resolution, and low bitrate video stream).

By default, users receive the high-quality video stream. Call this method if you want to switch to the low-video stream. This method allows the app to adjust the corresponding video stream type based on the size of the video window to reduce the bandwidth and resources.

The aspect ratio of the low-video stream is the same as the high-quality video stream. Once the resolution of the high-quality video stream is set, the system automatically sets the resolution, frame rate, and bitrate of the low-video stream.

The method result returns in the onApiCallExecuted callback.

Note
You can call this method either before or after joining a channel. If you call both setRemoteVideoStreamType and setRemoteDefaultVideoStreamType, the SDK applies the settings in the setRemoteVideoStreamType method.
Parameters
userIdID of the remote user sending the video stream.
streamTypeSets the video-stream type. See REMOTE_VIDEO_STREAM_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteDefaultVideoStreamType()

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

Sets the default stream type of remote videos.

Under limited network conditions, if the publisher has not disabled the dual-stream mode using enableDualStreamMode(false), the receiver can choose to receive either the high-quality video stream (the high resolution, and high bitrate video stream) or the low-video stream (the low resolution, and low bitrate video stream).

By default, users receive the high-quality video stream. Call this method if you want to switch to the low-video stream. This method allows the app to adjust the corresponding video stream type based on the size of the video window to reduce the bandwidth and resources. The aspect ratio of the low-video stream is the same as the high-quality video stream. Once the resolution of the high-quality video stream is set, the system automatically sets the resolution, frame rate, and bitrate of the low-video stream.

The method result returns in the onApiCallExecuted callback.

Note
  • This method can only be called before joining a channel. Agora does not support you to change the default subscribed video stream type after joining a channel.
  • If you call both this method and setRemoteVideoStreamType, the SDK applies the settings in the setRemoteVideoStreamType method.
Parameters
streamTypeSets the default video-stream type. See REMOTE_VIDEO_STREAM_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableAudioVolumeIndication()

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

Enables the reporting of users' volume indication.

This method enables the SDK to regularly report the volume information of the local user who sends a stream and remote users (up to three) whose instantaneous volumes are the highest to the app. Once you call this method and users send streams in the channel, the SDK triggers the onAudioVolumeIndication callback at the time interval set in this method.

Note
You can call this method either before or after joining a 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. We recommend setting interval > 200 ms. Do not set interval < 10 ms, or the onAudioVolumeIndication callback will not be triggered.
smoothSmoothing factor sets the sensitivity of the audio volume indicator. The value ranges between 0 and 10. The greater the value, the more sensitive the indicator. The recommended value is 3.
report_vad
  • true: Enable the voice activity detection of the local user. Once it is enabled, the vad parameter of the onAudioVolumeIndication callback reports the voice activity status of the local user.
  • false: (Default) Disable the voice activity detection of the local user. Once it is disabled, the vad parameter of the onAudioVolumeIndication callback does not report the voice activity status of the local user, except for the scenario where the engine automatically detects the voice activity of the local user.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableLocalVoicePitchCallback()

virtual int agora::rtc::IRtcEngine::enableLocalVoicePitchCallback ( int  interval)
pure virtual

Enables reporting the voice pitch of the local user.

Since
v3.7.0

This method enables the SDK to regularly report the voice pitch of the local user. After the local audio capture is enabled, and you call this method, the SDK triggers the onLocalVoicePitchInHz callback at the time interval set in this method.

Note
You can call this method either before or after joining a channel.
Parameters
intervalSets the time interval at which the SDK triggers the onLocalVoicePitchInHz callback:
  • ≤ 0: Disables the onLocalVoicePitchInHz callback.
  • > 0: The time interval (ms) at which the SDK triggers the onLocalVoicePitchInHz callback. The value must be greater than or equal to 10. If the value is less than 10, the SDK automatically changes it to 10.
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.

Deprecated:
Deprecated from v2.9.1. Use startAudioRecording [3/3] instead.

The SDK allows recording during a call. Supported formats:

  • .wav: Large file size with high fidelity.
  • .aac: Small file size with low fidelity.

This method has a fixed sample rate of 32 kHz.

Ensure that the directory to save the recording file exists and is writable. This method is usually called after the joinChannel method. The recording automatically stops when the leaveChannel method is called.

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

◆ 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 on the client.

Deprecated:
Deprecated from v3.4.0. Use startAudioRecording [3/3] instead.

The SDK allows recording during a call. After successfully calling this method, you can record the audio of all the users in the channel and get an audio recording file. Supported formats of the recording file are as follows:

  • .wav: Large file size with high fidelity.
  • .aac: Small file size with low fidelity.
Note
  • Ensure that the directory you use to save the recording file exists and is writable.
  • This method is usually called after the joinChannel method. The recording automatically stops when you call the leaveChannel method.
  • For better recording effects, set quality as AUDIO_RECORDING_QUALITY_MEDIUM or AUDIO_RECORDING_QUALITY_HIGH when sampleRate is 44.1 kHz or 48 kHz.
Parameters
filePathPointer to the absolute file path of the recording file. The string of the file name is in UTF-8, such as c:/music/audio.aac.
sampleRateSample rate (Hz) of the recording file. Supported values are as follows:
  • 16000
  • (Default) 32000
  • 44100
  • 48000
qualitySets the audio recording quality. See 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 on the client.

Since
v3.4.0

The SDK allows recording audio during a call. After successfully calling this method, you can record the audio of users in the channel and get an audio recording file. Supported file formats are as follows:

  • WAV: High-fidelity files with typically larger file sizes. For example, if the sample rate is 32,000 Hz, the file size for a 10-minute recording is approximately 73 MB.
  • AAC: Low-fidelity files with typically smaller file sizes. For example, if the sample rate is 32,000 Hz and the recording quality is AUDIO_RECORDING_QUALITY_MEDIUM, the file size for a 10-minute recording is approximately 2 MB.

Once the user leaves the channel, the recording automatically stops.

Note
Call this method after joining a channel.
Parameters
configRecording configuration. See AudioRecordingConfiguration.
Returns
  • 0: Success.
  • < 0: Failure.
    • -160(ERR_ALREADY_IN_RECORDING): The client is already recording audio. To start a new recording, call stopAudioRecording to stop the current recording first, and then call startAudioRecording.

◆ stopAudioRecording()

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

Stops an audio recording on the client.

Returns
  • 0: Success
  • < 0: Failure.

◆ startAudioMixing() [1/2]

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

Starts playing and mixing the music file.

Deprecated:
Deprecated from v3.4.0. Use startAudioMixing [2/2] instead.

This method mixes the specified local audio file with the audio stream from the microphone, or replaces the microphone's audio stream with the specified local audio file. You can choose whether the other user can hear the local audio playback and specify the number of playback loops. This method also supports online music playback.

When the audio mixing file playback finishes after calling this method, the SDK triggers the onAudioMixingFinished callback.

A successful startAudioMixing method call triggers the onAudioMixingStateChanged (PLAY) callback on the local client.

When the audio mixing file playback finishes, the SDK triggers the onAudioMixingStateChanged (STOPPED) callback on the local client.

Note
  • 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.
  • To avoid blocking, as of v3.4.5, this method changes from a synchronous call to an asynchronous call.
  • For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support.
  • On Android, to play an online file for which the URL address starts with http, you need to add android:usesCleartextTraffic="true" to the /app/Manifests/AndroidManifest.xml file.
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.
loopbackSets which user can hear the audio mixing:
  • true: Only the local user can hear the audio mixing.
  • false: Both users can hear the audio mixing.
replaceSets the audio mixing content:
  • true: Only publish the specified audio file. The audio stream from the microphone is not published.
  • false: The local audio file is mixed with the audio stream from the microphone.
cycleSets the number of playback loops:
  • Positive integer: Number of playback loops.
  • -1: Infinite playback loops.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startAudioMixing() [2/2]

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

Starts playing and mixing the music file.

Since
v3.4.0

This method supports mixing or replacing local or online music file and audio collected by a microphone. After successfully playing the music file, the SDK triggers onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING,AUDIO_MIXING_REASON_STARTED_BY_USER). After completing playing the music file, the SDK triggers onAudioMixingStateChanged(AUDIO_MIXING_STATE_STOPPED,AUDIO_MIXING_REASON_ALL_LOOPS_COMPLETED).

Note
  • If you need to call startAudioMixing multiple times, ensure that the call interval is longer than 500 ms.
  • If the local music 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).
  • On Android:
    • To use this method, ensure that the Android device is v4.2 or later and the API version is v16 or later.
    • If you need to play an online music file, Agora does not recommend using the redirected URL address. Some Android devices may fail to open a redirected URL address.
    • If you call this method on an emulator, ensure that the music file is in the /sdcard/ directory and the format is MP3.
    • To play an online file for which the URL address starts with http, you need to add android:usesCleartextTraffic="true" to the /app/Manifests/AndroidManifest.xml file.
  • To avoid blocking, as of v3.4.5, this method changes from a synchronous call to an asynchronous call.
  • For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support.
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.
loopbackWhether to only play the music file on the local client:
  • true: Only play the music file on the local client so that only the local user can hear the music.
  • false: Publish the music file to remote clients so that both the local user and remote users can hear the music.
replaceWhether to replace the audio collected by the microphone with a music file:
  • true: Replace. Users can only hear music.
  • false: Do not replace. Users can hear both music and audio collected by the microphone.
cycleThe number of times the music file plays.
  • ≥ 0: The number of playback times. For example, 0 means that the SDK does not play the music file, while 1 means that the SDK plays the music file once.
  • -1: Play the music in an indefinite loop.
startPosThe playback position (ms) of the music file.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setAudioMixingPlaybackSpeed()

virtual int agora::rtc::IRtcEngine::setAudioMixingPlaybackSpeed ( int  speed)
pure virtual

Sets the playback speed of the current music file.

Since
v3.5.1
Note
Call this method after calling startAudioMixing [2/2] and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.
Parameters
speedThe playback speed. Agora recommends that you limit this value to between 50 and 400, defined as follows:
  • 50: Half the original speed.
  • 100: The original speed.
  • 400: 4 times the original speed.
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.

◆ selectAudioTrack()

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

Specifies the playback track of the current music file.

Since
v3.5.1

After getting the number of audio tracks of the current music file, call this method to specify any audio track to play. For example, if different tracks of a multitrack file store songs in different languages, you can call this method to set the language of the music file to play.

Note
Parameters
indexThe specified playback track. The value range is [0, getAudioTrackCount()).
Returns
  • 0: Success.
  • < 0: Failure.

◆ getAudioTrackCount()

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

Gets the number of audio tracks of the current music file.

Since
v3.5.1
Note
Returns
  • > 0: The number of audio tracks of the current music file, if this method call succeeds.
  • < 0: Failure.

◆ setAudioMixingDualMonoMode()

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

Sets the channel mode of the current music file.

Since
v3.5.1

In a stereo music file, the left and right channels can store different audio data. According to your needs, you can set the channel mode to original mode, left channel mode, right channel mode, or mixed channel mode. For example, in the KTV scenario, the left channel of the music file stores the musical accompaniment, and the right channel stores the singing voice. If you only need to listen to the accompaniment, call this method to set the channel mode of the music file to left channel mode; if you need to listen to the accompaniment and the singing voice at the same time, call this method to set the channel mode to mixed channel mode.

Note
Parameters
modeThe channel mode. See AUDIO_MIXING_DUAL_MONO_MODE.
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.

◆ setHighQualityAudioParameters()

virtual int agora::rtc::IRtcEngine::setHighQualityAudioParameters ( bool  fullband,
bool  stereo,
bool  fullBitrate 
)
pure virtual
Deprecated:
Agora does not recommend using this method.

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

Do not call this method again after joining a channel.

Parameters
fullbandSets whether to enable/disable full-band codec (48-kHz sample rate). Not compatible with SDK versions before v1.7.4:
  • true: Enable full-band codec.
  • false: Disable full-band codec.
stereoSets whether to enable/disable stereo codec. Not compatible with SDK versions before v1.7.4:
  • true: Enable stereo codec.
  • false: Disable stereo codec.
fullBitrateSets whether to enable/disable high-bitrate mode. Recommended in voice-only mode:
  • true: Enable high-bitrate mode.
  • false: Disable high-bitrate mode.
Returns
  • 0: Success.
  • < 0: Failure.

◆ adjustAudioMixingVolume()

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

Adjusts the volume during audio mixing.

Note
Parameters
volumeAudio mixing volume. The value ranges between 0 and 100 (default).
Returns
  • 0: Success.
  • < 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 after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.
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

Gets the audio mixing volume for local playback.

This method helps troubleshoot audio volume related issues.

Note
Returns
  • ≥ 0: The audio mixing volume, if this method call succeeds. The value range is [0,100].
  • < 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 after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.
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

Gets the audio mixing volume for publishing.

This method helps troubleshoot audio volume related issues.

Note
Returns
  • ≥ 0: The audio mixing volume for publishing, 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.

Deprecated:
This method is deprecated as of v3.5.1. Use getAudioFileInfo instead.
Note
Returns
  • ≥ 0: The audio mixing duration, if this method call succeeds.
  • < 0: Failure.

◆ getAudioMixingCurrentPosition()

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

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

Note
  • Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.
  • If you need to call getAudioMixingCurrentPosition multiple times, ensure that the call interval is longer than 500 ms.
Returns
  • ≥ 0: The current playback position (ms) of the music file, if this method call succeeds. 0 represents that the current music file does not start playing.
  • < 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).

Note
Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.
Parameters
posThe playback starting position (ms) of the music file.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setAudioMixingPitch()

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

Sets the pitch of the local music file.

Since
v3.0.1

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 the audio effects.

The value ranges between 0.0 and 100.0.

Note
Ensure that this method is called after playEffect .
Returns
  • ≥ 0: Volume of the audio effects, if this method call succeeds.
  • < 0: Failure.

◆ setEffectsVolume()

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

Sets the volume of the audio effects.

Note
Ensure that this method is called after playEffect .
Parameters
volumeSets the volume of the audio effects. The value ranges between 0 and 100 (default).
Returns
  • 0: Success.
  • < 0: Failure.

◆ setVolumeOfEffect()

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

Sets the volume of a specified audio effect.

Note
Ensure that this method is called after playEffect .
Parameters
soundIdID of the audio effect. Each audio effect has a unique ID.
volumeSets the volume of the specified audio effect. The value ranges between 0 and 100 (default).
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableFaceDetection()

virtual int agora::rtc::IRtcEngine::enableFaceDetection ( bool  enable)
pure virtual

Enables/Disables face detection for the local user.

Since
v3.0.1
Note
  • Applies to Android and iOS only.
  • You can call this method either before or after joining a channel.

Once face detection is enabled, the SDK triggers the onFacePositionChanged callback to report the face information of the local user, which includes the following aspects:

  • The width and height of the local video.
  • The position of the human face in the local view.
  • The distance between the human face and the device screen.
Parameters
enableDetermines whether to enable the face detection function for the local user:
  • true: Enable face detection.
  • false: (Default) Disable face detection.
Returns
  • 0: Success.
  • < 0: Failure.

◆ playEffect() [1/2]

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

Plays a specified local or online audio effect file.

Deprecated:
Deprecated from v3.4.0. Use playEffect [2/2] instead.

This method allows you to set the loop count, pitch, pan, and gain of the audio effect file, as well as whether the remote user can hear the audio effect.

To play multiple audio effect files simultaneously, call this method multiple times with different soundIds and filePaths. We recommend playing no more than three audio effect files at the same time.

Note
  • If the audio effect is preloaded into the memory through the preloadEffect method, the value of soundID must be the same as that in the preloadEffect method.
  • Playing multiple online audio effect files simultaneously is not supported on macOS and Windows.
  • Ensure that you call this method after joining a channel.
  • For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support.
  • On Android, to play an online file for which the URL address starts with http, you need to add android:usesCleartextTraffic="true" to the /app/Manifests/AndroidManifest.xml file.
Parameters
soundIdID of the specified audio effect. Each audio effect has a unique ID.
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.
loopCountSets the number of times the audio effect loops:
  • 0: Play the audio effect once.
  • 1: Play the audio effect twice.
  • -1: Play the audio effect in an indefinite loop until the stopEffect or stopAllEffects method is called.
pitchSets the pitch of the audio effect. The value ranges between 0.5 and 2. The default value is 1 (no change to the pitch). The lower the value, the lower the pitch.
panSets the spatial position of the audio effect. The value ranges between -1.0 and 1.0:
  • 0.0: The audio effect displays ahead.
  • 1.0: The audio effect displays to the right.
  • -1.0: The audio effect displays to the left.
gainSets the volume of the audio effect. The value ranges between 0 and 100 (default). The lower the value, the lower the volume of the audio effect.
publishSets whether to publish the specified audio effect to the remote stream:
  • true: The locally played audio effect is published to the Agora Cloud and the remote users can hear it.
  • false: The locally played audio effect is not published to the Agora Cloud and the remote users cannot hear it.
Returns
  • 0: Success.
  • < 0: Failure.

◆ playEffect() [2/2]

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

Plays a specified local or online audio effect file.

Since
v3.4.0

To play multiple audio effect files at the same time, call this method multiple times with different soundId and filePath values. For the best user experience, Agora recommends playing no more than three audio effect files at the same time.

After completing playing an audio effect file, the SDK triggers the onAudioEffectFinished callback.

Note
  • Call this method after joining a channel.
  • For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support.
  • On Android, to play an online file for which the URL address starts with http, you need to add android:usesCleartextTraffic="true" to the /app/Manifests/AndroidManifest.xml file.
Parameters
soundIdAudio effect ID. The ID of each audio effect file is unique. If you preloaded an audio effect into memory by calling preloadEffect, ensure that this parameter is set to the same value as in preloadEffect.
filePathThe absolute path or URL address (including the filename extensions) of the music file. For example: C:\music\audio.mp4. If you preloaded an audio effect into memory by calling preloadEffect, ensure that this parameter is set to the same value as in preloadEffect. When you access a local file on Android, Agora recommends passing a URI address or the path starts with /assets/ in this parameter.
loopCountThe number of times the audio effect loops:
  • ≥ 0: The number of loops. For example, 1 means loop one time, which means play the audio effect two times in total.
  • -1: Play the audio effect in an indefinite loop.
pitchThe pitch of the audio effect. The range is 0.5 to 2.0. The default value is 1.0, which means the original pitch. The lower the value, the lower the pitch.
panThe spatial position of the audio effect. The range is -1.0 to 1.0. For example:
  • -1.0: The audio effect occurs on the left.
  • 0.0: The audio effect occurs in the front.
  • 1.0: The audio effect occurs on the right.
gainThe volume of the audio effect. The range is 0.0 to 100.0. The default value is 100.0, which means the original volume. The smaller the value, the less the gain.
publishWhether to publish the audio effect to the remote users:
  • true: Publish. Both the local user and remote users can hear the audio effect.
  • false: Do not publish. Only the local user can hear the audio effect.
startPosThe playback position (ms) of the audio effect file.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopEffect()

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

Stops playing a specified audio effect.

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

◆ stopAllEffects()

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

Stops playing all audio effects.

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

◆ preloadEffect()

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

Preloads a specified audio effect file into the memory.

Note
  • This method does not support online audio effect files. For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support.
  • To ensure smooth communication, limit the size of the audio effect file.
  • You can call this method either before or after joining a channel.
Parameters
soundIdID of the audio effect. Each audio effect has a unique ID.
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: Success.
  • < 0: Failure.

◆ unloadEffect()

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

Releases a specified preloaded audio effect from the memory.

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

◆ pauseEffect()

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

Pauses a specified audio effect.

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

◆ pauseAllEffects()

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

Pauses all audio effects.

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

◆ resumeEffect()

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

Resumes playing a specified audio effect.

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

◆ resumeAllEffects()

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

Resumes playing all audio effects.

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.

Since
v3.4.0
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.

Since
v3.4.0

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.

Since
v3.4.0
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.

◆ getAudioFileInfo()

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

Gets the information of a specified audio file.

Since
v3.5.1

After calling this method successfully, the SDK triggers the onRequestAudioFileInfo callback to report the information of an audio file, such as audio duration. You can call this method multiple times to get the information of multiple audio files.

Note
Parameters
filePathThe file path:
  • Windows: The absolute path or URL address (including the filename extensions) of the audio file. For example: C:\music\audio.mp4.
  • Android: The file path, including the filename extensions. To access an online file, Agora supports using a URL address; to access a local file, Agora supports using a URI address, an absolute path, or a path that starts with /assets/. You might encounter permission issues if you use an absolute path to access a local file, so Agora recommends using a URI address instead. For example: content://com.android.providers.media.documents/document/audio%3A14441.
  • iOS or macOS: The absolute path or URL address (including the filename extensions) of the audio file. For example: /var/mobile/Containers/Data/audio.mp4.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableDeepLearningDenoise()

virtual int agora::rtc::IRtcEngine::enableDeepLearningDenoise ( bool  enable)
pure virtual

Enables or disables deep-learning noise reduction.

Since
v3.3.0

The SDK enables traditional noise reduction mode by default to reduce most of the stationary background noise. If you need to reduce most of the non-stationary background noise, Agora recommends enabling deep-learning noise reduction as follows:

  1. Ensure that the dynamical library is integrated in your project:
    • Android: libagora_ai_denoise_extension.so
    • iOS/macOS: AgoraAIDenoiseExtension.xcframework
    • Windows: libagora_ai_denoise_extension.dll
  2. Call enableDeepLearningDenoise(true).

Deep-learning noise reduction requires high-performance devices. For example, the following devices and later models are known to support deep-learning noise reduction:

  • iPhone 6S
  • MacBook Pro 2015
  • iPad Pro (2nd generation)
  • iPad mini (5th generation)
  • iPad Air (3rd generation)

After successfully enabling deep-learning noise reduction, if the SDK detects that the device performance is not sufficient, it automatically disables deep-learning noise reduction and enables traditional noise reduction.

If you call enableDeepLearningDenoise(false) or the SDK automatically disables deep-learning noise reduction in the channel, when you need to re-enable deep-learning noise reduction, you need to call leaveChannel first, and then call enableDeepLearningDenoise(true).

Note
  • This method dynamically loads the library, so Agora recommends calling this method before joining a channel.
  • This method works best with the human voice. Agora does not recommend using this method for audio containing music.
Parameters
enableSets whether to enable deep-learning noise reduction.
  • true: Enables deep-learning noise reduction.
  • false: Disable deep-learning noise reduction.
Returns
  • 0: Success.
  • < 0: Failure.
    • -157 (ERR_MODULE_NOT_FOUND): The dynamical library for enabling deep-learning noise reduction is not integrated.

◆ 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 to enable stereo panning for remote users:
  • true: Enable stereo panning.
  • false: Disable 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.

◆ setLocalVoicePitch()

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

Changes the voice pitch of the local speaker.

Note
You can call this method either before or after joining a channel.
Parameters
pitchSets the voice pitch. The value ranges between 0.5 and 2.0. The lower the value, the lower the voice pitch. The default value is 1.0 (no change to the local voice pitch).
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLocalVoiceEqualization()

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

Sets the local voice equalization effect.

Note
You can call this method either before or after joining a channel.
Parameters
bandFrequencySets the band frequency. The value ranges between 0 and 9, representing the respective 10-band center frequencies of the voice effects, including 31, 62, 125, 250, 500, 1k, 2k, 4k, 8k, and 16k Hz. See AUDIO_EQUALIZATION_BAND_FREQUENCY.
bandGainSets the gain of each band in dB. The value ranges between -15 and 15.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLocalVoiceReverb()

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

Sets the local voice reverberation.

As of v3.2.0, the SDK provides a more convenient method setAudioEffectPreset, which directly implements the popular music, R&B music, KTV and other preset reverb effects.

Note
You can call this method either before or after joining a channel.
Parameters
reverbKeySets the reverberation key. See AUDIO_REVERB_TYPE.
valueSets the value of the reverberation key. See AUDIO_REVERB_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLocalVoiceChanger()

virtual int agora::rtc::IRtcEngine::setLocalVoiceChanger ( VOICE_CHANGER_PRESET  voiceChanger)
pure virtual

Sets the local voice changer option.

Deprecated:
Deprecated from v3.2.0. Use the following methods instead:

This method can be used to set the local voice effect for users in a COMMUNICATION channel or hosts in a LIVE_BROADCASTING channel. Voice changer options include the following voice effects:

  • VOICE_CHANGER_XXX: Changes the local voice to an old man, a little boy, or the Hulk. Applies to the voice talk scenario.
  • VOICE_BEAUTY_XXX: Beautifies the local voice by making it sound more vigorous, resounding, or adding spacial resonance. Applies to the voice talk and singing scenario.
  • GENERAL_VOICE_BEAUTY_XXX: Adds gender-based beautification effect to the local voice. Applies to the voice talk scenario.
    • For a male voice: Adds magnetism to the voice.
    • For a female voice: Adds freshness or vitality to the voice.
Note
  • To achieve better voice effect quality, Agora recommends setting the profile parameter in setAudioProfile as AUDIO_PROFILE_MUSIC_HIGH_QUALITY (4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO (5)
  • This method works best with the human voice, and Agora does not recommend using it for audio containing music and a human voice.
  • Do not use this method with setLocalVoiceReverbPreset , because the method called later overrides the one called earlier. For detailed considerations, see the advanced guide Set the Voice Effect.
  • You can call this method either before or after joining a channel.
Parameters
voiceChangerSets the local voice changer option. The default value is VOICE_CHANGER_OFF, which means the original voice. See details in VOICE_CHANGER_PRESET.
Returns
  • 0: Success.
  • < 0: Failure. Check if the enumeration is properly set.

◆ setLocalVoiceReverbPreset()

virtual int agora::rtc::IRtcEngine::setLocalVoiceReverbPreset ( AUDIO_REVERB_PRESET  reverbPreset)
pure virtual

Sets the local voice reverberation option, including the virtual stereo.

Deprecated:
Deprecated from v3.2.0. Use setAudioEffectPreset or setVoiceBeautifierPreset instead.

This method sets the local voice reverberation for users in a COMMUNICATION channel or hosts in a LIVE_BROADCASTING channel. After successfully calling this method, all users in the channel can hear the voice with reverberation.

Note
  • When calling this method with enumerations that begin with AUDIO_REVERB_FX, ensure that you set profile in setAudioProfile as AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5); otherwise, this methods cannot set the corresponding voice reverberation option.
  • When calling this method with AUDIO_VIRTUAL_STEREO, Agora recommends setting the profile parameter in setAudioProfile as AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5).
  • This method works best with the human voice, and Agora does not recommend using it for audio containing music and a human voice.
  • Do not use this method with setLocalVoiceChanger, because the method called later overrides the one called earlier. For detailed considerations, see the advanced guide Set the Voice Effect.
  • You can call this method either before or after joining a channel.
Parameters
reverbPresetThe local voice reverberation option. The default value is AUDIO_REVERB_OFF, which means the original voice. See AUDIO_REVERB_PRESET. To achieve better voice effects, Agora recommends the enumeration whose name begins with AUDIO_REVERB_FX.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setVoiceBeautifierPreset()

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

Sets an SDK preset voice beautifier effect.

Since
v3.2.0

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

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.

Since
v3.2.0

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

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

Since
v3.3.1

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

You can set different voice conversion effects for different scenarios. See Set the Voice Effect.

To achieve better voice 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) and the scenario parameter to AUDIO_SCENARIO_GAME_STREAMING (3) before calling this method.

Note
Parameters
presetThe options for SDK preset voice conversion effects: 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.

Since
v3.2.0

Call this method to set the following parameters for the local user who sends 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.

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.

Since
v3.3.0

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.

◆ setLogFile()

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

Sets the log files that the SDK outputs.

Deprecated:
This method is deprecated from v3.3.0. Use logConfig in the initialize method instead.

By default, the SDK outputs five log files, agorasdk.log, agorasdk_1.log, agorasdk_2.log, agorasdk_3.log, agorasdk_4.log, each with a default size of 1024 KB. These log files are encoded in UTF-8. The SDK writes the latest logs in agorasdk.log. When agorasdk.log is full, the SDK deletes the log file with the earliest modification time among the other four, renames agorasdk.log to the name of the deleted log file, and create a new agorasdk.log to record latest logs.

Note
Ensure that you call this method immediately after calling initialize , otherwise the output logs may not be complete.
See also
setLogFileSize
setLogFilter
Parameters
filePathThe absolute path of log files. The default file path is C: \Users\<user_name>\AppData\Local\Agora\<process_name>\agorasdk.log. Ensure that the directory for the log files exists and is writable. You can use this parameter to rename the log files.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLogFilter()

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

Sets the output log level of the SDK.

Deprecated:
This method is deprecated from v3.3.0. Use logConfig in the initialize method instead.

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

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

See also
setLogFile
setLogFileSize
Parameters
filterSets the log filter level. See LOG_FILTER_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLogFileSize()

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

Sets the size of a log file that the SDK outputs.

Deprecated:
This method is deprecated from v3.3.0. Use logConfig in the initialize method instead.
Note
If you want to set the log file size, ensure that you call this method before setLogFile, or the logs are cleared.

By default, the SDK outputs five log files, agorasdk.log, agorasdk_1.log, agorasdk_2.log, agorasdk_3.log, agorasdk_4.log, each with a default size of 1024 KB. These log files are encoded in UTF-8. The SDK writes the latest logs in agorasdk.log. When agorasdk.log is full, the SDK deletes the log file with the earliest modification time among the other four, renames agorasdk.log to the name of the deleted log file, and create a new agorasdk.log to record latest logs.

See also
setLogFile
setLogFilter
Parameters
fileSizeInKBytesThe size (KB) of a log file. The default value is 1024 KB. If you set fileSizeInKByte to 1024 KB, the SDK outputs at most 5 MB log files; if you set it to less than 1024 KB, the maximum size of a log file is still 1024 KB.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLocalRenderMode() [1/2]

virtual int agora::rtc::IRtcEngine::setLocalRenderMode ( RENDER_MODE_TYPE  renderMode)
pure virtual
Deprecated:
This method is deprecated, use the setLocalRenderMode [2/2] method instead. Sets the local video display mode.

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

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

◆ setLocalRenderMode() [2/2]

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

Updates the display mode of the local video view.

Since
v3.0.0

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

Note
  • Ensure that you have called the setupLocalVideo method to initialize the local 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 local video view.
Parameters
renderModeThe rendering mode of the local video view. See RENDER_MODE_TYPE.
mirrorMode
  • The mirror mode of the local video view. See VIDEO_MIRROR_MODE_TYPE.
  • Note: If you use a front camera, the SDK enables the mirror mode by default; if you use a rear camera, the SDK disables the mirror mode by default.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteRenderMode() [1/2]

virtual int agora::rtc::IRtcEngine::setRemoteRenderMode ( uid_t  userId,
RENDER_MODE_TYPE  renderMode 
)
pure virtual
Deprecated:
This method is deprecated, use the setRemoteRenderMode [2/2] method instead. Sets the video display mode of a specified remote user.

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

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

◆ setRemoteRenderMode() [2/2]

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

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

Since
v3.0.0 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 the setupRemoteVideo method 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
userIdThe ID of the remote user.
renderModeThe rendering mode of the remote video view. See RENDER_MODE_TYPE.
mirrorMode
  • The mirror mode of the remote video view. See VIDEO_MIRROR_MODE_TYPE.
  • Note: The SDK disables the mirror mode by default.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLocalVideoMirrorMode()

virtual int agora::rtc::IRtcEngine::setLocalVideoMirrorMode ( VIDEO_MIRROR_MODE_TYPE  mirrorMode)
pure virtual
Deprecated:
This method is deprecated, use the setupLocalVideo or setLocalRenderMode method instead.

Sets the local video mirror mode.

Warning
Call this method after calling the setupLocalVideo method to initialize the local video view.
Parameters
mirrorModeSets the local video mirror mode. See VIDEO_MIRROR_MODE_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableDualStreamMode()

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

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

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

Note
You can call this method either before or after joining a channel.
Parameters
enabledSets the stream mode:
  • true: Dual-stream mode.
  • false: Single-stream mode.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setExternalAudioSource()

virtual int agora::rtc::IRtcEngine::setExternalAudioSource ( bool  enabled,
int  sampleRate,
int  channels 
)
pure virtual

Sets the external audio source.

Note
Please call this method before joinChannel and startPreview.
Parameters
enabledSets whether to enable/disable the external audio source:
  • true: Enable the external audio source.
  • false: (Default) Disables the external audio source.
sampleRateSets the sample rate (Hz) of the external audio source, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
channelsSets the number of audio channels of the external audio source:
  • 1: Mono.
  • 2: Stereo.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setExternalAudioSink()

virtual int agora::rtc::IRtcEngine::setExternalAudioSink ( bool  enabled,
int  sampleRate,
int  channels 
)
pure virtual

Sets the external audio sink. This method applies to scenarios where you want to use external audio data for playback. After enabling the external audio sink, you can call the pullAudioFrame method to pull the remote audio data, process it, and play it with the audio effects that you want.

Note
  • When using the SDK with versions earlier than v3.5.0, you will not receive the onPlaybackAudioFrame callback after using the Pull method to set the external audio sink.
  • Ensure that you call this method before joining a channel.
Parameters
enabled
  • true: Enable the external audio sink.
  • false: (Default) Disables the external audio sink.
sampleRateSets the sample rate (Hz) of the external audio sink, which can be set as 16000, 32000, 44100 or 48000.
channelsSets the number of audio channels of the external audio sink:
  • 1: Mono.
  • 2: Stereo.
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.

Note
Ensure that you call this method before joining a channel.
Parameters
sampleRateSets the sample rate (samplesPerSec) returned in the onRecordAudioFrame callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
channelSets the number of audio channels (channels) returned in the onRecordAudioFrame callback:
  • 1: Mono
  • 2: Stereo
modeSets the use mode (see RAW_AUDIO_FRAME_OP_MODE_TYPE) of the onRecordAudioFrame callback.
samplesPerCallSets the number of samples returned in the onRecordAudioFrame callback. samplesPerCall is usually set as 1024 for RTMP or RTMPS streaming.
Note
The SDK triggers the onRecordAudioFrame callback according to the sample interval. Ensure that the sample interval ≥ 0.01 (s). And, Sample interval (sec) = samplePerCall/(sampleRate × channel).
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.

Note
Ensure that you call this method before joining a channel.
Parameters
sampleRateSets the sample rate (samplesPerSec) returned in the onPlaybackAudioFrame callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
channelSets the number of channels (channels) returned in the onPlaybackAudioFrame callback:
  • 1: Mono
  • 2: Stereo
modeSets the use mode (see RAW_AUDIO_FRAME_OP_MODE_TYPE) of the onPlaybackAudioFrame callback.
samplesPerCallSets the number of samples returned in the onPlaybackAudioFrame callback. samplesPerCall is usually set as 1024 for RTMP or RTMPS streaming.
Note
The SDK triggers the onPlaybackAudioFrame callback according to the sample interval. Ensure that the sample interval ≥ 0.01 (s). And, Sample interval (sec) = samplePerCall/(sampleRate × channel).
Returns
  • 0: Success.
  • < 0: Failure.

◆ setMixedAudioFrameParameters()

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

Sets the mixed audio format for the onMixedAudioFrame callback.

Note
Ensure that you call this method before joining a channel.
Parameters
sampleRateSets the sample rate (samplesPerSec) returned in the onMixedAudioFrame callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.
samplesPerCallSets the number of samples (samples) returned in the onMixedAudioFrame callback. samplesPerCall is usually set as 1024 for RTMP or RTMPS streaming.
Note
The SDK triggers the onMixedAudioFrame callback according to the sample interval. Ensure that the sample interval ≥ 0.01 (s). And, Sample interval (sec) = samplePerCall/(sampleRate × channels).
Returns
  • 0: Success.
  • < 0: Failure.

◆ adjustRecordingSignalVolume()

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

Adjusts the volume of the signal captured by the microphone.

Note
You can call this method either before or after joining a channel.
Parameters
volumeThe volume of the signal captured by the microphone. The value ranges between 0 and 400, including the following:
  • 0: Mute.
  • 100: (Default) Original volume.
  • 400: Four times the original volume with signal-clipping protection.
Returns
  • 0: Success.
  • < 0: Failure.

◆ adjustPlaybackSignalVolume()

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

Adjusts the playback signal volume of all remote users.

Note
  • This method adjusts the playback volume that is the mixed volume of all remote users.
  • You can call this method either before or after joining a channel.
  • (Since v2.3.2) To mute the local audio playback, call both the adjustPlaybackSignalVolume and adjustAudioMixingVolume methods and set the volume as 0.
Parameters
volumeThe playback volume. The value ranges between 0 and 400, including the following:
  • 0: Mute.
  • 100: (Default) Original volume.
  • 400: Four times the original volume with signal-clipping protection.
Returns
  • 0: Success.
  • < 0: Failure.

◆ adjustLoopbackRecordingSignalVolume()

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

Adjusts the volume of the signal captured by the sound card.

Since
v3.4.0

After calling enableLoopbackRecording to enable loopback audio capturing, you can call this method to adjust the volume of the signal captured by the sound card.

Note
This method applies to Windows and macOS only.
Parameters
volumeThe volume of the signal captured by the sound card. The value ranges between 0 and 100, including the following:
  • 0: Mute.
  • 100: (Default) Original volume.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableWebSdkInteroperability()

virtual int agora::rtc::IRtcEngine::enableWebSdkInteroperability ( bool  enabled)
pure virtual
Deprecated:
This method is deprecated. As of v3.0.0, the Native SDK automatically enables interoperability with the Web SDK, so you no longer need to call this method. Enables interoperability with the Agora Web SDK.
Note
  • This method applies to the LIVE_BROADCASTING profile. In the COMMUNICATION profile, interoperability with the Agora Web SDK is enabled by default.
  • If the channel has Web SDK users, ensure that you call this method, or the video of the Native user will be a black screen for the Web user.
Parameters
enabledSets whether to enable/disable interoperability with the Agora Web SDK:
  • true: Enable.
  • false: (Default) Disable.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setVideoQualityParameters()

virtual int agora::rtc::IRtcEngine::setVideoQualityParameters ( bool  preferFrameRateOverImageQuality)
pure virtual
Deprecated:
Sets the preferences for the high-quality video. (LIVE_BROADCASTING only).

This method is deprecated as of v2.4.0.

Parameters
preferFrameRateOverImageQualitySets the video quality preference:
  • true: Frame rate over image quality.
  • false: (Default) Image quality over frame rate.
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:
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.

◆ switchCamera()

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

Switches between front and rear cameras.

Note
  • This method is for Android and iOS only.
  • Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannel.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setDefaultAudioRouteToSpeakerphone()

virtual int agora::rtc::IRtcEngine::setDefaultAudioRouteToSpeakerphone ( bool  defaultToSpeaker)
pure virtual

Sets the default audio route.

If the default audio route of the SDK (see Set the Audio Route) cannot meet your requirements, you can call this method to switch the default audio route. After successfully switching the audio route, the SDK triggers the onAudioRouteChanged callback to indicate the changes.

Note
  • This method applies to Android and iOS only.
  • Call this method before calling joinChannel. If you need to switch the audio route after joining a channel, call setEnableSpeakerphone.
  • If the user uses an external audio playback device such as a Bluetooth or wired headset, this method does not take effect, and the SDK plays audio through the external device. When the user uses multiple external devices, the SDK plays audio through the last connected device.
Parameters
defaultToSpeakerSets the default audio route as follows:
  • true: Set to the speakerphone.
  • false: Set to the earpiece.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setEnableSpeakerphone()

virtual int agora::rtc::IRtcEngine::setEnableSpeakerphone ( bool  speakerOn)
pure virtual

Enables/Disables the audio route to the speakerphone.

If the default audio route of the SDK (see Set the Audio Route) or the setting in setDefaultAudioRouteToSpeakerphone cannot meet your requirements, you can call this method to switch the current audio route. After successfully switching the audio route, the SDK triggers the onAudioRouteChanged callback to indicate the changes.

This method only sets the audio route in the current channel and does not influence the default audio route. If the user leaves the current channel and joins another channel, the default audio route is used.

Note
  • This method applies to Android and iOS only.
  • Call this method after calling joinChannel.
  • If the user uses an external audio playback device such as a Bluetooth or wired headset, this method does not take effect, and the SDK plays audio through the external device. When the user uses multiple external devices, the SDK plays audio through the last connected device.
Parameters
speakerOnSets whether to enable the speakerphone or earpiece:
  • true: Enable the speakerphone. The audio route is the speakerphone.
  • false: Disable the speakerphone. The audio route is the earpiece.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableInEarMonitoring()

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

Enables in-ear monitoring (for Android and iOS only).

Note
  • Users must use wired earphones to hear their own voices.
  • You can call this method either before or after joining a channel.
Parameters
enabledDetermines whether to enable in-ear monitoring.
  • true: Enable.
  • false: (Default) Disable.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setInEarMonitoringVolume()

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

Sets the volume of the in-ear monitor.

Note
  • This method is for Android and iOS only.
  • Users must use wired earphones to hear their own voices.
  • You can call this method either before or after joining a channel.
Parameters
volumeSets the volume of the in-ear monitor. The value ranges between 0 and 100 (default).
Returns
  • 0: Success.
  • < 0: Failure.

◆ isSpeakerphoneEnabled()

virtual bool agora::rtc::IRtcEngine::isSpeakerphoneEnabled ( )
pure virtual

Checks whether the speakerphone is enabled.

Note
  • This method is for Android and iOS only.
  • You can call this method either before or after joining a channel.
Returns
  • true: The speakerphone is enabled, and the audio plays from the speakerphone.
  • false: The speakerphone is not enabled, and the audio plays from devices other than the speakerphone. For example, the headset or earpiece.

◆ setAudioSessionOperationRestriction()

virtual int agora::rtc::IRtcEngine::setAudioSessionOperationRestriction ( AUDIO_SESSION_OPERATION_RESTRICTION  restriction)
pure virtual

Sets the operational permission of the SDK on the audio session.

The SDK and the app can both configure the audio session by default. If you need to only use the app to configure the audio session, this method restricts the operational permission of the SDK on the audio session.

You can call this method either before or after joining a channel. Once you call this method to restrict the operational permission of the SDK on the audio session, the restriction takes effect when the SDK needs to change the audio session.

Note
  • This method is for iOS only.
  • This method does not restrict the operational permission of the app on the audio session.
Parameters
restrictionThe operational permission of the SDK on the audio session. See AUDIO_SESSION_OPERATION_RESTRICTION. This parameter is in bit mask format, and each bit corresponds to a permission.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableLoopbackRecording()

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

Enables loopback audio capturing.

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

Note
  • This method is for macOS and Windows only.
  • On macOS, call this method after joining a channel; on windows, call this method either before or after joining a channel.
  • The default sound card on the macOS system does not support loopback audio capture. To enable this capture, you need to enable a virtual sound card and pass the name of the virtual sound card in the deviceName parameter. Agora recommends that you use AgoraALD (Agora Audio Loopback Device) and pass in "AgoraALD".
Parameters
enabledSets whether to enable/disable loopback capturing.
  • true: Enable loopback capturing.
  • false: (Default) Disable loopback capturing.
deviceNameThe device name of the sound card. The default is set to null, which means the SDK uses the current sound card to capture. If you are using a virtual sound card, such as AgoraALD (Agora Audio Loopback Device), set this parameter as the name of the sound card ("AgoraALD").
Returns
  • 0: Success.
  • < 0: Failure.

◆ getScreenCaptureSources()

virtual IScreenCaptureSourceList* agora::rtc::IRtcEngine::getScreenCaptureSources ( const SIZE thumbSize,
const SIZE iconSize,
const bool  includeScreen 
)
pure virtual

Gets a list of shareable screens and windows.

Since
v3.5.2

You can call this method before sharing a screen or window to get a list of shareable screens and windows, which enables a user to use thumbnails in the list to easily choose a particular screen or window to share. This list also contains important information such as window ID and screen ID, with which you can call startScreenCaptureByWindowId or startScreenCaptureByDisplayId to start the sharing.

Note
This method applies to macOS and Windows only.
Parameters
thumbSizeThe target size of the screen or window thumbnail. The width and height are in pixels. See SIZE. The SDK scales the original image to make the length of the longest side of the image the same as that of the target size without distorting the original image. For example, if the original image is 400 × 300 and thumbSize is 100 × 100, the actual size of the thumbnail is 100 × 75. If the target size is larger than the original size, the thumbnail is the original image and the SDK does not scale it.
iconSizeThe target size of the icon corresponding to the application program. The width and height are in pixels. See SIZE. The SDK scales the original image to make the length of the longest side of the image the same as that of the target size without distorting the original image. For example, if the original image is 400 × 300 and iconSize is 100 × 100, the actual size of the icon is 100 × 75. If the target size is larger than the original size, the icon is the original image and the SDK does not scale it.
includeScreenWhether the SDK returns screen information in addition to window information:
  • true: The SDK returns screen and window information.
  • false: The SDK returns window information only.
Returns
IScreenCaptureSourceList

◆ startScreenCaptureByDisplayId()

virtual int agora::rtc::IRtcEngine::startScreenCaptureByDisplayId ( unsigned int  displayId,
const Rectangle regionRect,
const ScreenCaptureParameters captureParams 
)
pure virtual

Shares the whole or part of a screen by specifying the display ID.

Note
  • This method is for macOS and Windows only.
  • Ensure that you call this method after joining a channel.
Parameters
displayIdThe display ID of the screen to be shared. Use this parameter to specify which screen you want to share. For more information on how to get the display ID, see the advanced feature guide Share the Screen or get the display ID from sourceId returned by getScreenCaptureSources.
regionRect(Optional) Sets the relative location of the region to the screen. NIL means sharing the whole screen. See Rectangle. If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen.
captureParamsThe screen sharing encoding parameters. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of videoDimension to calculate the charges. For details, see descriptions in ScreenCaptureParameters.
Returns

◆ startScreenCaptureByScreenRect()

virtual int agora::rtc::IRtcEngine::startScreenCaptureByScreenRect ( const Rectangle screenRect,
const Rectangle regionRect,
const ScreenCaptureParameters captureParams 
)
pure virtual

Shares the whole or part of a screen by specifying the screen rect.

Deprecated:
This method is deprecated as of v3.7.0, use startScreenCaptureByDisplayId instead. Agora strongly recommends using startScreenCaptureByDisplayId if you need to start screen sharing on a device connected to another display.
Note
  • Ensure that you call this method after joining a channel.
  • Applies to the Windows platform only.
Parameters
screenRectSets the relative location of the screen to the virtual screen. For information on how to get screenRect, see the advanced guide Share Screen.
regionRect(Optional) Sets the relative location of the region to the screen. NULL means sharing the whole screen. See Rectangle. If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen.
captureParamsThe screen sharing encoding parameters. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of videoDimension to calculate the charges. For details, see descriptions in ScreenCaptureParameters.
Returns

◆ startScreenCaptureByWindowId()

virtual int agora::rtc::IRtcEngine::startScreenCaptureByWindowId ( view_t  windowId,
const Rectangle regionRect,
const ScreenCaptureParameters captureParams 
)
pure virtual

Shares the whole or part of a window by specifying the window ID.

Note
  • Ensure that you call this method after joining a channel.
  • Applies to the macOS and Windows platforms only.
  • The window sharing feature of the Agora SDK relies on WGC (Windows Graphics Capture) or GDI (Graphics Device Interface) capture, and WGC cannot be set to disable mouse capture on systems earlier than Windows 10 2004. Therefore, captureMouseCursor(false) might not work when you start window sharing on a device with a system earlier than Windows 10 2004. See IsCursorCapture.

As of v3.7.0, the window sharing feature supports most UWP (Universal Windows Platform) applications windows. The details of the support are as follows:

Device system Application Support or not
Windows 10 Chrome, Microsoft Office, WPS Office, Windows Media Player and other mainstream applications Yes
Windows 8 Chrome, Microsoft Office, WPS Office, Windows Media Player and other mainstream applications Yes
Windows 7 Microsoft Office, WPS PPT (11.1.0.9098) Yes
Windows 7 Chrome, Windows Media Player, WPS Word (11.1.0.9098), WPS Excel (11.1.0.9098) No
Parameters
windowIdThe ID of the window to be shared. For information on how to get the windowId, see the advanced guide Share Screen.
regionRect(Optional) The relative location of the region to the window. NULL/NIL means sharing the whole window. See Rectangle. If the specified region overruns the window, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole window.
captureParamsThe screen sharing encoding parameters. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of videoDimension to calculate the charges. For details, see descriptions in ScreenCaptureParameters.
Returns

◆ setScreenCaptureContentHint()

virtual int agora::rtc::IRtcEngine::setScreenCaptureContentHint ( VideoContentHint  contentHint)
pure virtual

Sets the content hint for screen sharing.

A content hint suggests the type of the content being shared, so that the SDK applies different optimization algorithm to different types of content.

Note
You can call this method either before or after you start screen sharing.
Parameters
contentHintSets the content hint for screen sharing. See VideoContentHint.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setScreenCaptureScenario()

virtual int agora::rtc::IRtcEngine::setScreenCaptureScenario ( SCREEN_SCENARIO_TYPE  screenScenario)
pure virtual

Sets the screen sharing scenario.

Since
v3.7.0

When you start screen sharing or window sharing, you can call this method to set the screen sharing scenario. The SDK adjusts the video quality and experience of the sharing according to the scenario.

Note
This method is only available for the macOS and Windows platforms.
Parameters
screenScenarioThe screen sharing scenario. See SCREEN_SCENARIO_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ updateScreenCaptureParameters()

virtual int agora::rtc::IRtcEngine::updateScreenCaptureParameters ( const ScreenCaptureParameters captureParams)
pure virtual

Updates the screen sharing parameters.

Note
Call this method after starting screen sharing or window sharing.
Parameters
captureParamsThe screen sharing encoding parameters. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of videoDimension to calculate the charges. For details, see descriptions in ScreenCaptureParameters.
Returns

◆ updateScreenCaptureRegion() [1/2]

virtual int agora::rtc::IRtcEngine::updateScreenCaptureRegion ( const Rectangle regionRect)
pure virtual

Updates the screen sharing region.

Note
Call this method after starting screen sharing or window sharing.
Parameters
regionRectSets the relative location of the region to the screen or window. NULL means sharing the whole screen or window. See Rectangle. If the specified region overruns the screen or window, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen or window.
Returns

◆ stopScreenCapture()

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

Stop screen sharing.

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

◆ startScreenCapture()

virtual int agora::rtc::IRtcEngine::startScreenCapture ( WindowIDType  windowId,
int  captureFreq,
const Rect rect,
int  bitrate 
)
pure virtual
Deprecated:
Starts screen sharing.

This method is deprecated as of v2.4.0. See the following methods instead:

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

  • Whole screen: Set windowId as 0 and rect as NULL.
  • Specified window: Set windowId as a value other than 0. Each window has a windowId that is not 0.
  • Specified region: Set windowId as 0 and rect not as NULL. In this case, you can share the specified region, for example by dragging the mouse or implementing your own logic.
Note
The specified region is a region on the whole screen. Currently, sharing a specified region in a specific window is not supported. captureFreq* is the captured frame rate once the screen-sharing function is enabled. The mandatory value ranges between 1 fps and 15 fps.
Parameters
windowIdSets the screen sharing area. See WindowIDType.
captureFreq(Mandatory) The captured frame rate. The value ranges between 1 fps and 15 fps.
rectSpecifies the screen-sharing region. rect is valid when windowsId is set as 0. When rect is set as NULL, the whole screen is shared.
bitrateThe captured bitrate.
Returns
  • 0: Success.
  • < 0: Failure.

◆ updateScreenCaptureRegion() [2/2]

virtual int agora::rtc::IRtcEngine::updateScreenCaptureRegion ( const Rect rect)
pure virtual
Deprecated:
Updates the screen capture region.
Parameters
rectSpecifies the required region inside the screen or window.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setVideoSource()

virtual bool agora::rtc::IRtcEngine::setVideoSource ( IVideoSource source)
pure virtual

Sets a custom video source.

During real-time communication, the Agora SDK enables the default video input device, that is, the built-in camera to capture video. If you need a custom video source, implement the IVideoSource class first, and call this method to add the custom video source to the SDK.

Note
You can call this method either before or after joining a channel.
Parameters
sourceThe custom video source. See IVideoSource.
Returns
  • true: The custom video source is added to the SDK.
  • false: The custom video source is not added to the SDK.

◆ 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 from the client. Feedback methods, such as rate and complain, must be called after the call ends to submit feedback to the SDK.

The rate and complain methods require the callId parameter retrieved from the getCallId method during a call. callId is passed as an argument into the rate and complain methods after the call ends.

Note
Ensure that you call this method after joining a channel.
Parameters
callIdPointer to the current call ID.
Returns
  • 0: Success.
  • < 0: Failure.

◆ rate()

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

Allows a user to rate a call after the call ends.

Note
Ensure that you call this method after joining a channel.
Parameters
callIdPointer to the ID of the call, retrieved from the getCallId method.
ratingRating of the call. The value is between 1 (lowest score) and 5 (highest score). If you set a value out of this range, the ERR_INVALID_ARGUMENT (2) error returns.
description(Optional) Pointer to the description of the rating, with a string length of 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 after a call ends.

Note
Ensure that you call this method after joining a channel.
Parameters
callIdPointer to the ID of the call, retrieved from the getCallId method.
description(Optional) Pointer to the description of the complaint, with a string length of less than 800 bytes.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getVersion()

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

Gets the SDK version number.

Parameters
buildPointer to the build number.
Returns
The version of the current SDK in the string format. For example, 2.3.1.

◆ enableLastmileTest()

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

Enables the network connection quality test.

This method tests the quality of the users' network connections and is disabled by default.

Before a user joins a channel or before an audience switches to a host, call this method to check the uplink network quality.

This method consumes additional network traffic, and hence may affect communication quality.

Call the disableLastmileTest method to disable this test after receiving the onLastmileQuality callback, and before joining a channel.

Note
  • Do not call any other methods before receiving the onLastmileQuality callback. Otherwise, the callback may be interrupted by other methods, and hence may not be triggered.
  • A host should not call this method after joining a channel (when in a call).
  • If you call this method to test the last mile network quality, the SDK consumes the bandwidth of a video stream, whose bitrate corresponds to the bitrate you set in the setVideoEncoderConfiguration method. After you join the channel, whether you have called the disableLastmileTest method or not, the SDK automatically stops consuming the bandwidth.
Returns
  • 0: Success.
  • < 0: Failure.

◆ disableLastmileTest()

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

Disables the network connection quality test.

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 within two seconds 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
  • This method consumes extra network traffic and may affect communication quality. We do not recommend calling this method together with enableLastmileTest.
  • Do not call other methods before receiving the onLastmileQuality and onLastmileProbeResult callbacks. Otherwise, the callbacks may be interrupted.
  • In the LIVE_BROADCASTING 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.

◆ getErrorDescription()

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

Gets the warning or error description.

Parameters
codeWarning code or error code returned in the onWarning or onError callback.
Returns
WARN_CODE_TYPE or ERROR_CODE_TYPE.

◆ setEncryptionSecret()

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

Enables built-in encryption with an encryption password before users join a channel.

Deprecated:
Deprecated as of v3.1.0. Use the enableEncryption instead.

All users in a channel must use the same encryption password. The encryption password is automatically cleared once a user leaves the channel.

If an encryption password is not specified, the encryption functionality will be disabled.

Note
  • Do not use this method for CDN live streaming.
  • For optimal transmission, ensure that the encrypted data size does not exceed the original data size + 16 bytes. 16 bytes is the maximum padding size for AES encryption.
Parameters
secretPointer to the encryption password.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setEncryptionMode()

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

Sets the built-in encryption mode.

Deprecated:
Deprecated as of v3.1.0. Use the enableEncryption instead.

The Agora SDK supports built-in encryption, which is set to the aes-128-xts mode by default. Call this method to use other encryption modes.

All users in the same channel must use the same encryption mode and password.

Refer to the information related to the AES encryption algorithm on the differences between the encryption modes.

Note
Call the setEncryptionSecret method to enable the built-in encryption function before calling this method.
Parameters
encryptionModePointer to the set encryption mode:
  • "aes-128-xts": (Default) 128-bit AES encryption, XTS mode.
  • "aes-128-ecb": 128-bit AES encryption, ECB mode.
  • "aes-256-xts": 256-bit AES encryption, XTS mode.
  • "": When encryptionMode is set as NULL, the encryption mode is set as "aes-128-xts" by default.
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.

Since
v3.1.0

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

After a user leaves the channel, the SDK automatically disables the built-in encryption. To re-enable the built-in encryption, call this method before the user joins the channel again.

As of v3.4.5, Agora recommends using either the AES_128_GCM2 or AES_256_GCM2 encryption mode, both of which support adding a salt and are more secure. For details, see Media Stream Encryption.

Warning
All users in the same channel must use the same encryption mode, encryption key, and salt; otherwise, users cannot communicate with each other.
Note
  • If you enable the built-in encryption, you cannot use the RTMP or RTMPS streaming function.
  • To enhance security, Agora recommends using a new key and salt every time you enable the media stream encryption.
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.

◆ registerPacketObserver()

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

Registers a packet observer.

The Agora SDK allows your application to register a packet observer to receive callbacks for voice or video packet transmission.

Note
  • The size of the packet sent to the network after processing should not exceed 1200 bytes, otherwise, the packet may fail to be sent.
  • Ensure that both receivers and senders call this method, otherwise, you may meet undefined behaviors such as no voice and black screen.
  • When you use CDN live streaming and recording functions, Agora doesn't recommend calling this method.
  • Call this method before joining a channel.
Parameters
observerPointer to the registered packet observer. See IPacketObserver.
Returns
  • 0: Success.
  • < 0: Failure.

◆ createDataStream() [1/2]

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

Creates a data stream.

Deprecated:
This method is deprecated from v3.3.0. Use the createDataStream [2/2] method instead.

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

Note
  • Do not set reliable as true while setting ordered as false.
  • Ensure that you call this method after joining a channel.
Parameters
[out]streamIdPointer to the ID of the created data stream.
reliableSets whether or not 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 or not 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.

Since
v3.3.0

Each user can create up to five data streams in a single channel.

This method does not support data reliability. If the receiver receives a data packet five seconds or more after it was sent, the SDK directly discards the data.

Parameters
[out]streamIdThe ID of the created data stream.
configThe configurations for the data stream: DataStreamConfig.
Returns
  • 0: Creates the data stream successfully.
  • < 0: Fails to create the data stream.

◆ sendStreamMessage()

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

Sends data stream messages to all users in a channel.

The SDK has the following restrictions on this method:

  • Up to 30 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 6 kB of data per second.
  • Each user can have up to five data streams simultaneously.

A successful sendStreamMessage method call triggers the onStreamMessage callback on the remote client, from which the remote user gets the stream message.

A failed sendStreamMessage method call triggers the onStreamMessage callback on the remote client.

Note
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
streamIdID of the sent data stream, returned in the createDataStream method.
dataPointer to the sent data.
lengthLength of the sent data.
Returns
  • 0: Success.
  • < 0: Failure.

◆ addPublishStreamUrl()

virtual int agora::rtc::IRtcEngine::addPublishStreamUrl ( const char *  url,
bool  transcodingEnabled 
)
pure virtual

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

Deprecated:
This method is deprecated as of v3.6.0. See Release Notes for an alternative solution.

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

The addPublishStreamUrl 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.
  • Ensure that you enable the Media Push service before using this function. See Prerequisites in the advanced guide Media Push.
  • This method adds only one stream CDN streaming URL each time it is called.
  • This method applies to LIVE_BROADCASTING only.
Parameters
urlThe CDN streaming URL in the RTMP or RTMPS format. The maximum length of this parameter is 1024 bytes. The CDN streaming URL must not contain special characters, such as Chinese language characters.
transcodingEnabledSets whether transcoding is enabled/disabled:
  • true: Enable transcoding. To transcode the audio or video streams when publishing them to CDN live, often used for combining the audio and video streams of multiple hosts in CDN live. If you set this parameter as true, ensure that you call the setLiveTranscoding method before this method.
  • false: Disable transcoding.
Returns
  • 0: Success.
  • < 0: Failure.

◆ removePublishStreamUrl()

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

Removes an RTMP or RTMPS stream from the CDN. (CDN live only.)

Deprecated:
This method is deprecated as of v3.6.0. See Release Notes for an alternative solution.

This method removes the CDN streaming URL (added by the addPublishStreamUrl method) from a CDN live stream. The SDK returns the result of this method call in the onStreamUnpublished callback.

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

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

◆ setLiveTranscoding()

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

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

Deprecated:
This method is deprecated as of v3.6.0. See Release Notes for an alternative solution.

The SDK triggers the onTranscodingUpdated callback when you call the setLiveTranscoding method to update the transcoding setting.

Note
  • This method applies to LIVE_BROADCASTING only.
  • Ensure that you enable the Media Push service before using this function. See Prerequisites in the advanced guide Media Push.
  • If you call the setLiveTranscoding method to update the transcoding setting for the first time, the SDK does not trigger the onTranscodingUpdated callback.
  • Ensure that you call this method after joining a channel.
  • Agora supports pushing media streams in RTMPS protocol to the CDN only when you enable transcoding.
Parameters
transcodingSets the CDN live audio/video transcoding settings. See LiveTranscoding.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startRtmpStreamWithoutTranscoding()

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

Starts pushing media streams to a CDN without transcoding.

Since
v3.6.0

You can call this method to push a live audio-and-video stream to the specified CDN address. This method can push media streams to only one CDN address at a time, so if you need to push streams to multiple addresses, call this method multiple times.

After you call this method, the SDK triggers the onRtmpStreamingStateChanged callback on the local client to report the state of the streaming.

Note
  • Ensure that you enable the Media Push service before using this function. See Prerequisites in Media Push.
  • Call this method after joining a channel.
  • Only hosts in the LIVE_BROADCASTING profile can call this method.
  • If you want to retry pushing streams after a failed push, make sure to call stopRtmpStream first, then call this method to retry pushing streams; otherwise, the SDK returns the same error code as the last failed push.
Parameters
urlThe address of the CDN live streaming. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported.
Returns
  • 0: Success.
  • < 0: Failure.
    • ERR_INVALID_ARGUMENT(-2): url is null or the string length is 0.
    • ERR_NOT_INITIALIZED(-7): The SDK is not initialized before calling this method.

◆ startRtmpStreamWithTranscoding()

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

Starts pushing media streams to a CDN and sets the transcoding configuration.

Since
v3.6.0

You can call this method to push a live audio-and-video stream to the specified CDN address and set the transcoding configuration. This method can push media streams to only one CDN address at a time, so if you need to push streams to multiple addresses, call this method multiple times.

After you call this method, the SDK triggers the onRtmpStreamingStateChanged callback on the local client to report the state of the streaming.

Note
  • Ensure that you enable the Media Push service before using this function. See Prerequisites in Media Push.
  • Call this method after joining a channel.
  • Only hosts in the LIVE_BROADCASTING profile can call this method.
  • If you want to retry pushing streams after a failed push, make sure to call stopRtmpStream first, then call this method to retry pushing streams; otherwise, the SDK returns the same error code as the last failed push.
Parameters
urlThe address of the CDN live streaming. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported.
transcodingThe transcoding configuration for CDN live streaming. See LiveTranscoding.
Returns
  • 0: Success.
  • < 0: Failure.
    • ERR_INVALID_ARGUMENT(-2): url is null or the string length is 0.
    • ERR_NOT_INITIALIZED(-7): The SDK is not initialized before calling this method.

◆ updateRtmpTranscoding()

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

Updates the transcoding configuration.

Since
v3.6.0

After you start pushing media streams to CDN with transcoding, you can dynamically update the transcoding configuration according to the scenario. The SDK triggers the onTranscodingUpdated callback after the transcoding configuration is updated.

Parameters
transcodingThe transcoding configuration for CDN live streaming. See LiveTranscoding.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopRtmpStream()

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

Stops pushing media streams to a CDN.

Since
v3.6.0

You can call this method to stop the live stream on the specified CDN address. This method can stop pushing media streams to only one CDN address at a time, so if you need to stop pushing streams to multiple addresses, call this method multiple times.

After you call this method, the SDK triggers the onRtmpStreamingStateChanged callback on the local client to report the state of the streaming.

Parameters
urlThe address of the CDN live streaming. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported.
Returns
  • 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 deprecated from v2.9.1. Use addVideoWatermark [2/2] instead.

This method adds a PNG watermark image to the local video stream for the capturing 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 streaming.
  • 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 the live streaming. Once the watermark image is added, all the audience in the channel (CDN audience included), and the capturing 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:

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 streaming 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. On Android, Agora recommends passing a URI address or the path starts with /assets/ in this parameter
optionsPointer to the watermark's options to be added. See WatermarkOptions for more infomation.
Returns
  • 0: Success.
  • < 0: Failure.

◆ clearVideoWatermarks()

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

Removes the watermark image from the video stream added by the addVideoWatermark method.

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

◆ setBeautyEffectOptions()

virtual int agora::rtc::IRtcEngine::setBeautyEffectOptions ( bool  enabled,
BeautyOptions  options 
)
pure virtual

Enables/Disables image enhancement and sets the options.

Note
  • Call this method after calling the enableVideo method.
  • On Android, this method applies to Android 5.0 or later.
  • Agora has updated the Agora image enhancement algorithm from v3.6.0 to enhance image enhancement effects and support sharpness adjustment. If you want to experience optimized image enhancement effects or set the sharpness, integrate the following dynamic library into the project before calling this method:
    • Android: libagora_video_process_extension.so
    • iOS/macOS: AgoraVideoProcessExtension.xcframework
    • Windows: libagora_video_process_extension.dll
Parameters
enabledDetermines whether to enable image enhancement:
  • true: Enable image enhancement.
  • false: (Default) Disables image enhancement.
optionsThe image enhancement option. See BeautyOptions.
Returns
  • 0: Success.
  • < 0: Failure.
    • -4(ERR_NOT_SUPPORTED): The system version is earlier than Android 5.0, which does not support this function.

◆ setLowlightEnhanceOptions()

virtual int agora::rtc::IRtcEngine::setLowlightEnhanceOptions ( bool  enabled,
LowLightEnhanceOptions  options 
)
pure virtual

Sets low-light enhancement.

Since
v3.6.2

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,
VideoDenoiserOptions  options 
)
pure virtual

Sets video noise reduction.

Since
v3.6.2

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,
ColorEnhanceOptions  options 
)
pure virtual

Sets color enhancement.

Since
v3.6.2

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 
)
pure virtual

Enables/Disables the virtual background.

Support for macOS and Windows as of v3.4.5 and Android and iOS as of v3.5.0.

After enabling the virtual background feature, 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. You can find out from the onVirtualBackgroundSourceEnabled callback whether the virtual background is successfully enabled or the cause of any errors.

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.
  • This functions requires a high-performance device. Agora recommends that you use this function on the following devices:
    • Android: Devices with the following chips:
      • Snapdragon 700 series 750G and later
      • Snapdragon 800 series 835 and later
      • Dimensity 700 series 720 and later
      • Kirin 800 series 810 and later
      • Kirin 900 series 980 and later
    • iOS: Devices with an A9 chip and better, as follows:
      • iPhone 6S and later
      • iPad Air (3rd generation) and later
      • iPad (5th generation) and later
      • iPad Pro (1st generation) and later
      • iPad mini (5th generation) and later
    • macOS and Windows: 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.
  • For versions earlier than v3.6.1, the virtual background feature does not support video in the Texture format or video obtained from custom video capture by the Push method.
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.

◆ addInjectStreamUrl()

virtual int agora::rtc::IRtcEngine::addInjectStreamUrl ( const char *  url,
const InjectStreamConfig config 
)
pure virtual

Adds a voice or video stream URL address to the live streaming.

The onStreamPublished callback returns the inject status. If this method call is successful, the server pulls the voice or video stream and injects it into a live channel. This is applicable to scenarios where all audience members in the channel can watch a live show and interact with each other.

The addInjectStreamUrl method call triggers the following callbacks:

  • The local client:
    • onStreamInjectedStatus , with the state of the injecting the online stream.
    • onUserJoined (uid: 666), if the method call is successful and the online media stream is injected into the channel.
  • The remote client:
    • onUserJoined (uid: 666), if the method call is successful and the online media stream is injected into the channel.
Warning
Agora will soon stop the service for injecting online media streams on the client. If you have not implemented this service, Agora recommends that you do not use it.
Note
  • Ensure that you enable the RTMP Converter service before using this function. See *Prerequisites* in the advanced guide Media Push.
  • This method applies to the Native SDK v2.4.1 and later.
  • This method applies to the LIVE_BROADCASTING profile only.
  • You can inject only one media stream into the channel at the same time.
  • Ensure that you call this method after joining a channel.
Parameters
urlPointer to the URL address to be added to the ongoing streaming. Valid protocols are RTMP, HLS, and HTTP-FLV.
  • Supported audio codec type: AAC.
  • Supported video codec type: H264 (AVC).
configPointer to the InjectStreamConfig object that contains the configuration of the added voice or video stream.
Returns
  • 0: Success.
  • < 0: Failure.
    • ERR_INVALID_ARGUMENT (-2): The injected URL does not exist. Call this method again to inject the stream and ensure that the URL is valid.
    • ERR_NOT_READY (-3): The user is not in the channel.
    • ERR_NOT_SUPPORTED (-4): The channel profile is not LIVE_BROADCASTING. Call the setChannelProfile method and set the channel profile to LIVE_BROADCASTING before calling this method.
    • ERR_NOT_INITIALIZED (-7): The SDK is not initialized. Ensure that the IRtcEngine object is initialized before calling this method.

◆ 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 successfully calling the startChannelMediaRelay method and receiving the onChannelMediaRelayStateChanged (RELAY_STATE_RUNNING, RELAY_OK) callback; otherwise, this method call fails.
Parameters
configurationThe media stream relay configuration: ChannelMediaRelayConfiguration.
Returns
  • 0: Success.
  • < 0: Failure.

◆ pauseAllChannelMediaRelay()

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

Pauses the media stream relay to all destination channels.

Since
v3.5.1

After the cross-channel media stream relay starts, you can call this method to pause relaying media streams to all destination channels; after the pause, if you want to resume the relay, call resumeAllChannelMediaRelay.

After a successful method call, the SDK triggers the onChannelMediaRelayEvent callback to report whether the media stream relay is successfully paused.

Note
Call this method after the startChannelMediaRelay method.
Returns
  • 0: Success.
  • < 0: Failure.

◆ resumeAllChannelMediaRelay()

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

Resumes the media stream relay to all destination channels.

Since
v3.5.1

After calling the pauseAllChannelMediaRelay method, you can call this method to resume relaying media streams to all destination channels.

After a successful method call, the SDK triggers the onChannelMediaRelayEvent callback to report whether the media stream relay is successfully resumed.

Note
Call this method after the pauseAllChannelMediaRelay method.
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) error code. You can leave the channel by calling the leaveChannel method, and the media stream relay automatically stops.
Returns
  • 0: Success.
  • < 0: Failure.

◆ removeInjectStreamUrl()

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

Removes the voice or video stream URL address from the live streaming.

This method removes the URL address (added by the addInjectStreamUrl method) from the live streaming.

Warning
Agora will soon stop the service for injecting online media streams on the client. If you have not implemented this service, Agora recommends that you do not use it.
Note
If this method is called successfully, the SDK triggers the onUserOffline callback and returns a stream uid of 666.
Parameters
urlPointer to the URL address of the injected stream to be removed.
Returns
  • 0: Success.
  • < 0: Failure.

◆ registerEventHandler()

virtual bool agora::rtc::IRtcEngine::registerEventHandler ( IRtcEngineEventHandler eventHandler)
pure virtual

◆ unregisterEventHandler()

virtual bool agora::rtc::IRtcEngine::unregisterEventHandler ( IRtcEngineEventHandler eventHandler)
pure virtual

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

Since
v3.1.0

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 and each string not exceeding 100 bytes. To try out this function, contact support@agora.io and discuss the format of customized messages with us.

◆ getConnectionState()

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

Gets the current connection state of the SDK.

Note
You can call this method either before or after joining a channel.
Returns
CONNECTION_STATE_TYPE.

◆ enableRemoteSuperResolution() [1/2]

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)

Deprecated:
This method is deprecated as of v3.7.1. Use enableRemoteSuperResolution [2/2] instead.
Since
v3.5.1

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.

After calling this method, the SDK triggers the onUserSuperResolutionEnabled callback to report whether you have successfully enabled super resolution.

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.
If you exceed these limitations, the SDK triggers the onWarning callback and returns the corresponding warning codes:
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.
    • -157 (ERR_MODULE_NOT_FOUND): The dynamic library for super resolution is not integrated.

◆ enableRemoteSuperResolution() [2/2]

virtual int agora::rtc::IRtcEngine::enableRemoteSuperResolution ( bool  enabled,
SR_MODE  mode,
uid_t  userId 
)
pure virtual

Enables/Disables the super-resolution feature for a remote user's video stream. This is a beta feature.

Since
v3.7.1

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.

After calling this method, the SDK triggers the onUserSuperResolutionEnabled callback to report whether you have successfully enabled super resolution.

Note
Before calling this method, ensure that you have integrated the following dynamic libraries into your project:
  • Android: libagora_super_resolution_extension.so
  • iOS/macOS: AgoraSuperResolutionExtension.xcframework
  • Windows: libagora_super_resolution_extension.dll
Warning
The super resolution feature requires extra system resources. To balance the visual experience and system consumption, the SDK poses the following restrictions:
Parameters
enabledDetermines whether to enable super resolution for the remote user's video:
  • true: Enable super resolution.
  • false: Disable super resolution.
modeThe mode of super resolution. See SR_MODE.
userIdThe user ID of the remote user. This parameter only applies when mode is set as SR_MODE_MANUAL(0).
Returns
  • 0: Success.
  • < 0: Failure.
    • -157 (ERR_MODULE_NOT_FOUND): The dynamic library for super resolution is not integrated.

◆ registerMediaMetadataObserver()

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

This method enables you to add synchronized metadata in the video stream for more diversified interactive live streaming, such as sending shopping links, digital coupons, and online quizzes.

Note
Call this method before the joinChannel method.
Parameters
observerThe IMetadataObserver class. See the definition of IMetadataObserver for details.
typeSee METADATA_TYPE. The SDK supports VIDEO_METADATA (0) only for now.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setParameters()

virtual int agora::rtc::IRtcEngine::setParameters ( const char *  parameters)
pure virtual

Provides technical preview functionalities or special customizations by configuring the SDK with JSON options.

The JSON options are not public by default. Agora is working on making commonly used JSON options public in a standard way.

Parameters
parametersSets the parameter as a JSON string in the specified format.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLocalVideoRenderer()

virtual int agora::rtc::IRtcEngine::setLocalVideoRenderer ( IVideoSink videoSink)
pure virtual

Customizes the local video renderer.

Since
v3.5.0

During a real-time audio and video interaction, the Agora SDK enables the default renderer to render local video. If you want to customize the local video rendering, you can first customize the video renderer via the IVideoSink class, and then call this method to use the custom video renderer to render the local video.

Note
You can call this method either before or after joining a channel.
Parameters
videoSinkThe custom video renderer. See IVideoSink.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteVideoRenderer()

virtual int agora::rtc::IRtcEngine::setRemoteVideoRenderer ( uid_t  uid,
IVideoSink videoSink 
)
pure virtual

Customizes the remote video renderer.

Since
v3.5.0

During a real-time audio and video interaction, the Agora SDK enables the default renderer to render remote video. If you want to customize the remote video rendering, you can first customize the video renderer via the IVideoSink class, and then call this method to use the custom video renderer to render the remote video.

Note
You can call this method either before or after joining a channel.
Parameters
uidThe user ID of the remote user.
videoSinkThe custom video renderer. See IVideoSink.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setCameraTorchOn()

virtual int agora::rtc::IRtcEngine::setCameraTorchOn ( bool  isOn)
pure virtual

Sets whether to enable the flash.

Since
v3.5.1
Note
  • Call this method after the camera is started.
  • This method is for Android and iOS only.
  • On iPads with system version 15, even if isCameraTorchSupported returns true, you might fail to successfully enable the flash by calling setCameraTorchOn due to system issues.
Parameters
isOnDetermines whether to enable the flash:
  • true: Enable the flash.
  • false: Disable the flash.
Returns
  • 0: Success
  • < 0: Failure

◆ isCameraTorchSupported()

virtual bool agora::rtc::IRtcEngine::isCameraTorchSupported ( )
pure virtual

Checks whether the device supports enabling the flash.

Since
v3.5.1

The SDK uses the front camera by default, so if you call isCameraTorchSupported directly, you can find out from the return value whether the device supports enabling the flash when using the front camera. If you want to check whether the device supports enabling the flash when using the rear camera, call switchCamera to switch the camera used by the SDK to the rear camera, and then call isCameraTorchSupported.

Note
  • Call this method after the camera is started.
  • This method is for Android and iOS only.
  • On iPads with system version 15, even if isCameraTorchSupported returns true, you might fail to successfully enable the flash by calling setCameraTorchOn due to system issues.
Returns
  • true: The device supports enabling the flash.
  • false: The device does not support enabling the flash.

◆ setCameraZoomFactor()

virtual int agora::rtc::IRtcEngine::setCameraZoomFactor ( float  factor)
pure virtual

Sets the camera zoom ratio.

Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannel.

Parameters
factorSets the camera zoom factor. The value ranges between 1.0 and the maximum zoom supported by the device.
Returns
  • The set camera zoom factor, if this method call is successful.
  • 0: Failure.

◆ getCameraMaxZoomFactor()

virtual float agora::rtc::IRtcEngine::getCameraMaxZoomFactor ( )
pure virtual

Gets the maximum zoom ratio supported by the camera.

Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannel.

Returns
The maximum camera zoom factor.

◆ isCameraZoomSupported()

virtual bool agora::rtc::IRtcEngine::isCameraZoomSupported ( )
pure virtual

Checks whether the camera zoom function is supported.

Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannel.

Returns
  • true: The device supports the camera zoom function.
  • false: The device does not support the camera zoom function.

◆ isCameraFocusSupported()

virtual bool agora::rtc::IRtcEngine::isCameraFocusSupported ( )
pure virtual

Checks whether the camera manual focus function is supported.

Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannel.

Returns
  • true: The device supports the camera manual focus function.
  • false: The device does not support the camera manual focus function.

◆ isCameraExposurePositionSupported()

virtual bool agora::rtc::IRtcEngine::isCameraExposurePositionSupported ( )
pure virtual

Checks whether the camera exposure function is supported.

Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannel.

Returns
  • true: The device supports the camera exposure function.
  • false: The device does not support the camera exposure function.

◆ isCameraAutoFocusFaceModeSupported()

virtual bool agora::rtc::IRtcEngine::isCameraAutoFocusFaceModeSupported ( )
pure virtual

Checks whether the camera auto-face focus function is supported.

Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannel.

Returns
  • true: The device supports the camera auto-face focus function.
  • false: The device does not support the camera auto-face focus function.

◆ setCameraFocusPositionInPreview()

virtual int agora::rtc::IRtcEngine::setCameraFocusPositionInPreview ( float  positionX,
float  positionY 
)
pure virtual

Sets the camera manual focus position.

Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannel.

A successful setCameraFocusPositionInPreview method call triggers the onCameraFocusAreaChanged callback on the local client.

Parameters
positionXThe horizontal coordinate of the touch point in the view.
positionYThe vertical coordinate of the touch point in the view.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setCameraExposurePosition()

virtual int agora::rtc::IRtcEngine::setCameraExposurePosition ( float  positionXinView,
float  positionYinView 
)
pure virtual

Sets the camera exposure position.

Ensure that you call this method after the camera starts, for example, by calling startPreview or joinChannel.

A successful setCameraExposurePosition method call triggers the onCameraExposureAreaChanged callback on the local client.

Parameters
positionXinViewThe horizontal coordinate of the touch point in the view.
positionYinViewThe vertical coordinate of the touch point in the view.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setCameraAutoFocusFaceModeEnabled()

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

Sets whether to enable face autofocus.

The SDK disables face autofocus by default. To set face autofocus, call this method.

Note
Call this method after the camera is started.
Parameters
enabledDetermines whether to enable face autofocus:
  • true: Enable face autofocus.
  • false: Disable face autofocus.
Returns
  • 0: Success.
  • < 0: Failure.

◆ takeSnapshot()

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

Takes a snapshot of a video stream.

Since
v3.5.2

This method takes a snapshot of a video stream from the specified user, generates a JPG image, and saves it to the specified path.

The method is asynchronous, and the SDK has not taken the snapshot when the method call returns. After a successful method call, the SDK triggers the onSnapshotTaken callback to report whether the snapshot is successfully taken as well as the details of the snapshot taken.

Note
  • Call this method after joining a channel.
  • If the video of the specified user is pre-processed, for example, added with watermarks or image enhancement effects, the generated snapshot also includes the pre-processing effects.
Parameters
channelThe channel name.
uidThe user ID of the user. Set uid as 0 if you want to take a snapshot of the local user's video.
filePathThe local path (including the filename extensions) of the snapshot. For example, C:\Users\<user_name>\AppData\Local\Agora\<process_name>\example.jpg on Windows, /App Sandbox/Library/Caches/example.jpg on iOS, ~/Library/Logs/example.jpg on macOS, and /storage/emulated/0/Android/data/<package name>/files/example.jpg on Android. Ensure that the path you specify exists and is writable.
Returns
  • 0: Success.
  • < 0: Failure.