Agora RTC Objective-C API Reference Refactor

Public Member Functions | Static Public Member Functions
IRtcEngine Class Referenceabstract

Inherits IEngineBase.

Inherited by IRtcEngineEx.

## Public Member Functions
virtual int | initialize (const RtcEngineContext &context)=0
virtual int | queryInterface (INTERFACE_ID_TYPE iid, void **inter)=0
virtual const char * | getVersion (int *build)=0
virtual const char * | getErrorDescription (int code)=0
virtual int | queryCodecCapability (CodecCapInfo *codecInfo, int &size)=0
virtual int | queryDeviceScore ()=0
virtual int | preloadChannel (const char *token, const char *channelId, uid_t uid)=0
virtual int | preloadChannelWithUserAccount (const char *token, const char *channelId, const char *userAccount)=0
virtual int | updatePreloadChannelToken (const char *token)=0
virtual int | joinChannel (const char *token, const char *channelId, const char *info, uid_t uid)=0
virtual int | joinChannel (const char *token, const char *channelId, uid_t uid, const ChannelMediaOptions &options)=0
virtual int | updateChannelMediaOptions (const ChannelMediaOptions &options)=0
virtual int | leaveChannel ()=0
virtual int | leaveChannel (const LeaveChannelOptions &options)=0
virtual int | renewToken (const char *token)=0
virtual int | setChannelProfile (CHANNEL_PROFILE_TYPE profile)=0
virtual int | setClientRole (CLIENT_ROLE_TYPE role)=0
virtual int | setClientRole (CLIENT_ROLE_TYPE role, const ClientRoleOptions &options)=0
virtual int | startEchoTest (const EchoTestConfiguration &config)=0
virtual int | enableVideo ()=0
virtual int | disableVideo ()=0
virtual int | startPreview ()=0
virtual int | startPreview (VIDEO_SOURCE_TYPE sourceType)=0
virtual int | stopPreview ()=0
virtual int | stopPreview (VIDEO_SOURCE_TYPE sourceType)=0
virtual int | startLastmileProbeTest (const LastmileProbeConfig &config)=0
virtual int | stopLastmileProbeTest ()=0
virtual int | setVideoEncoderConfiguration (const VideoEncoderConfiguration &config)=0
virtual int | setFaceShapeBeautyOptions (bool enabled, const FaceShapeBeautyOptions &options, agora::media::MEDIA_SOURCE_TYPE type=agora::media::PRIMARY_CAMERA_SOURCE)=0
virtual int | setFaceShapeAreaOptions (const FaceShapeAreaOptions &options, agora::media::MEDIA_SOURCE_TYPE type=agora::media::PRIMARY_CAMERA_SOURCE)=0
virtual int | getFaceShapeBeautyOptions (FaceShapeBeautyOptions &options, agora::media::MEDIA_SOURCE_TYPE type=agora::media::PRIMARY_CAMERA_SOURCE)=0
virtual int | getFaceShapeAreaOptions (agora::rtc::FaceShapeAreaOptions::FACE_SHAPE_AREA shapeArea, FaceShapeAreaOptions &options, agora::media::MEDIA_SOURCE_TYPE type=agora::media::PRIMARY_CAMERA_SOURCE)=0
virtual int | setLowlightEnhanceOptions (bool enabled, const LowlightEnhanceOptions &options, agora::media::MEDIA_SOURCE_TYPE type=agora::media::PRIMARY_CAMERA_SOURCE)=0
virtual int | setVideoDenoiserOptions (bool enabled, const VideoDenoiserOptions &options, agora::media::MEDIA_SOURCE_TYPE type=agora::media::PRIMARY_CAMERA_SOURCE)=0
virtual int | setColorEnhanceOptions (bool enabled, const ColorEnhanceOptions &options, agora::media::MEDIA_SOURCE_TYPE type=agora::media::PRIMARY_CAMERA_SOURCE)=0
virtual int | enableVirtualBackground (bool enabled, VirtualBackgroundSource backgroundSource, SegmentationProperty segproperty, agora::media::MEDIA_SOURCE_TYPE type=agora::media::PRIMARY_CAMERA_SOURCE)=0
virtual int | setupRemoteVideo (const VideoCanvas &canvas)=0
virtual int | setupLocalVideo (const VideoCanvas &canvas)=0
virtual int | setVideoScenario (VIDEO_APPLICATION_SCENARIO_TYPE scenarioType)=0
virtual int | setVideoQoEPreference (VIDEO_QOE_PREFERENCE_TYPE qoePreference)=0
virtual int | enableAudio ()=0
virtual int | disableAudio ()=0
virtual int | setAudioProfile (AUDIO_PROFILE_TYPE profile, AUDIO_SCENARIO_TYPE scenario) 1=0
virtual int | setAudioProfile (AUDIO_PROFILE_TYPE profile)=0
virtual int | setAudioScenario (AUDIO_SCENARIO_TYPE scenario)=0
virtual int | enableLocalAudio (bool enabled)=0
virtual int | muteLocalAudioStream (bool mute)=0
virtual int | muteAllRemoteAudioStreams (bool mute)=0
virtual int | muteRemoteAudioStream (uid_t uid, bool mute)=0
virtual int | muteLocalVideoStream (bool mute)=0
virtual int | enableLocalVideo (bool enabled)=0
virtual int | muteAllRemoteVideoStreams (bool mute)=0
virtual int | setRemoteDefaultVideoStreamType (VIDEO_STREAM_TYPE streamType)=0
virtual int | muteRemoteVideoStream (uid_t uid, bool mute)=0
virtual int | setRemoteVideoStreamType (uid_t uid, VIDEO_STREAM_TYPE streamType)=0
virtual int | setRemoteVideoSubscriptionOptions (uid_t uid, const VideoSubscriptionOptions &options)=0
virtual int | setSubscribeAudioAllowlist (uid_t *uidList, int uidNumber)=0
virtual int | setSubscribeVideoAllowlist (uid_t *uidList, int uidNumber)=0
virtual int | enableAudioVolumeIndication (int interval, int smooth, bool reportVad)=0
virtual int | startAudioRecording (const char *filePath, AUDIO_RECORDING_QUALITY_TYPE quality)=0
virtual int | startAudioRecording (const char *filePath, int sampleRate, AUDIO_RECORDING_QUALITY_TYPE quality)=0
virtual int | startAudioRecording (const AudioRecordingConfiguration &config)=0
virtual int | registerAudioEncodedFrameObserver (const AudioEncodedFrameObserverConfig &config, IAudioEncodedFrameObserver *observer)=0
virtual agora_refptr< IMediaPlayer > | createMediaPlayer ()=0
virtual int | destroyMediaPlayer (agora_refptr< IMediaPlayer > media_player)=0
virtual agora_refptr< IMediaRecorder > | createMediaRecorder (const RecorderStreamInfo &info)=0
virtual int | destroyMediaRecorder (agora_refptr< IMediaRecorder > mediaRecorder)=0
virtual int | selectAudioTrack (int index)=0
virtual int | getAudioTrackCount ()=0
virtual int | enableSoundPositionIndication (bool enabled)=0
virtual int | setRemoteVoicePosition (uid_t uid, double pan, double gain)=0
virtual int | enableSpatialAudio (bool enabled)=0
virtual int | setVoiceBeautifierPreset (VOICE_BEAUTIFIER_PRESET preset)=0
virtual int | setVoiceConversionPreset (VOICE_CONVERSION_PRESET preset)=0
virtual int | setVoiceBeautifierParameters (VOICE_BEAUTIFIER_PRESET preset, int param1, int param2)=0
virtual int | setVoiceConversionParameters (VOICE_CONVERSION_PRESET preset, int param1, int param2)=0
virtual int | setHeadphoneEQPreset (HEADPHONE_EQUALIZER_PRESET preset)=0
virtual int | setHeadphoneEQParameters (int lowGain, int highGain)=0
virtual int | enableVoiceAITuner (bool enabled, VOICE_AI_TUNER_TYPE type)=0
virtual int | setLogFile (const char *filePath)=0
virtual int | setLogFilter (unsigned int filter)=0
virtual int | setLogLevel (commons::LOG_LEVEL level)=0
virtual int | setLogFileSize (unsigned int fileSizeInKBytes)=0
virtual int | uploadLogFile (agora::util::AString &requestId)=0
virtual int | writeLog (commons::LOG_LEVEL level, const char *fmt,...)=0
virtual int | setLocalRenderMode (media::base::RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode)=0
virtual int | setRemoteRenderMode (uid_t uid, media::base::RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode)=0
virtual int | setLocalRenderTargetFps (VIDEO_SOURCE_TYPE sourceType, int targetFps)=0
virtual int | setRemoteRenderTargetFps (int targetFps)=0
virtual int | setLocalRenderMode (media::base::RENDER_MODE_TYPE renderMode) 1=0
virtual int | setLocalVideoMirrorMode (VIDEO_MIRROR_MODE_TYPE mirrorMode) 1=0
virtual int | enableDualStreamMode (bool enabled) 1=0
virtual int | enableDualStreamMode (bool enabled, const SimulcastStreamConfig &streamConfig) 1=0
virtual int | setDualStreamMode (SIMULCAST_STREAM_MODE mode)=0
virtual int | setSimulcastConfig (const SimulcastConfig &simulcastConfig)=0
virtual int | setDualStreamMode (SIMULCAST_STREAM_MODE mode, const SimulcastStreamConfig &streamConfig)=0
virtual int | enableCustomAudioLocalPlayback (track_id_t trackId, bool enabled)=0
virtual int | setRecordingAudioFrameParameters (int sampleRate, int channel, RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall)=0
virtual int | setPlaybackAudioFrameParameters (int sampleRate, int channel, RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall)=0
virtual int | setMixedAudioFrameParameters (int sampleRate, int channel, int samplesPerCall)=0
virtual int | setEarMonitoringAudioFrameParameters (int sampleRate, int channel, RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall)=0
virtual int | setPlaybackAudioFrameBeforeMixingParameters (int sampleRate, int channel)=0
virtual int | enableAudioSpectrumMonitor (int intervalInMS=100)=0
virtual int | disableAudioSpectrumMonitor ()=0
virtual int | registerAudioSpectrumObserver (agora::media::IAudioSpectrumObserver *observer)=0
virtual int | unregisterAudioSpectrumObserver (agora::media::IAudioSpectrumObserver *observer)=0
virtual int | adjustRecordingSignalVolume (int volume)=0
virtual int | muteRecordingSignal (bool mute)=0
virtual int | adjustPlaybackSignalVolume (int volume)=0
virtual int | setLocalPublishFallbackOption (STREAM_FALLBACK_OPTIONS option)=0
virtual int | setRemoteSubscribeFallbackOption (STREAM_FALLBACK_OPTIONS option)=0
virtual int | setHighPriorityUserList (uid_t *uidList, int uidNum, STREAM_FALLBACK_OPTIONS option)=0
virtual int | enableExtension (const char *provider, const char *extension, const ExtensionInfo &extensionInfo, bool enable=true)=0
virtual int | setExtensionProperty (const char *provider, const char *extension, const ExtensionInfo &extensionInfo, const char *key, const char *value)=0
virtual int | getExtensionProperty (const char *provider, const char *extension, const ExtensionInfo &extensionInfo, const char *key, char *value, int buf_len)=0
virtual int | enableLoopbackRecording (bool enabled, const char *deviceName=NULL)=0
virtual int | adjustLoopbackSignalVolume (int volume)=0
virtual int | getLoopbackRecordingVolume ()=0
virtual int | enableInEarMonitoring (bool enabled, int includeAudioFilters)=0
virtual int | setInEarMonitoringVolume (int volume)=0
virtual int | setExtensionProviderProperty (const char *provider, const char *key, const char *value)=0
virtual int | registerExtension (const char *provider, const char *extension, agora::media::MEDIA_SOURCE_TYPE type=agora::media::UNKNOWN_MEDIA_SOURCE)=0
virtual int | enableExtension (const char *provider, const char *extension, bool enable=true, agora::media::MEDIA_SOURCE_TYPE type=agora::media::UNKNOWN_MEDIA_SOURCE)=0
virtual int | setExtensionProperty (const char *provider, const char *extension, const char *key, const char *value, agora::media::MEDIA_SOURCE_TYPE type=agora::media::UNKNOWN_MEDIA_SOURCE)=0
virtual int | getExtensionProperty (const char *provider, const char *extension, const char *key, char *value, int buf_len, agora::media::MEDIA_SOURCE_TYPE type=agora::media::UNKNOWN_MEDIA_SOURCE)=0
virtual video_track_id_t | createCustomVideoTrack ()=0
virtual video_track_id_t | createCustomEncodedVideoTrack (const SenderOptions &sender_option)=0
virtual int | destroyCustomVideoTrack (video_track_id_t video_track_id)=0
virtual int | destroyCustomEncodedVideoTrack (video_track_id_t video_track_id)=0
virtual int | getCallId (agora::util::AString &callId)=0
virtual int | rate (const char *callId, int rating, const char *description)=0
virtual int | complain (const char *callId, const char *description)=0
virtual int | startRtmpStreamWithoutTranscoding (const char *url)=0
virtual int | startRtmpStreamWithTranscoding (const char *url, const LiveTranscoding &transcoding)=0
virtual int | updateRtmpTranscoding (const LiveTranscoding &transcoding)=0
virtual int | stopRtmpStream (const char *url)=0
virtual int | startLocalAudioMixer (const LocalAudioMixerConfiguration &config)=0
virtual int | updateLocalAudioMixerConfiguration (const LocalAudioMixerConfiguration &config)=0
virtual int | stopLocalAudioMixer ()=0
virtual int | startCameraCapture (VIDEO_SOURCE_TYPE sourceType, const CameraCapturerConfiguration &config)=0
virtual int | stopCameraCapture (VIDEO_SOURCE_TYPE sourceType)=0
virtual int | setScreenCaptureOrientation (VIDEO_SOURCE_TYPE type, VIDEO_ORIENTATION orientation)=0
virtual int | startScreenCapture (VIDEO_SOURCE_TYPE sourceType, const ScreenCaptureConfiguration &config)=0
virtual int | stopScreenCapture (VIDEO_SOURCE_TYPE sourceType)=0
virtual CONNECTION_STATE_TYPE | getConnectionState ()=0
virtual int | registerPacketObserver (IPacketObserver *observer)=0
virtual int | enableEncryption (bool enabled, const EncryptionConfig &config)=0
virtual int | createDataStream (int *streamId, bool reliable, bool ordered)=0
virtual int | createDataStream (int *streamId, const DataStreamConfig &config)=0
virtual int | sendStreamMessage (int streamId, const char *data, size_t length)=0
virtual int | addVideoWatermark (const RtcImage &watermark) 1=0
virtual int | addVideoWatermark (const char *watermarkUrl, const WatermarkOptions &options)=0
virtual int | enableWebSdkInteroperability (bool enabled) 1=0
virtual int | sendCustomReportMessage (const char *id, const char *category, const char *event, const char *label, int value)=0
virtual int | registerMediaMetadataObserver (IMetadataObserver *observer, IMetadataObserver::METADATA_TYPE type)=0
virtual int | unregisterMediaMetadataObserver (IMetadataObserver *observer, IMetadataObserver::METADATA_TYPE type)=0
virtual int | startAudioFrameDump (const char *channel_id, uid_t uid, const char *location, const char *uuid, const char *passwd, long duration_ms, bool auto_upload)=0
virtual int | stopAudioFrameDump (const char *channel_id, uid_t uid, const char *location)=0
virtual int | setAINSMode (bool enabled, AUDIO_AINS_MODE mode)=0
virtual int | registerLocalUserAccount (const char *appId, const char *userAccount)=0
virtual int | joinChannelWithUserAccount (const char *token, const char *channelId, const char *userAccount)=0
virtual int | joinChannelWithUserAccount (const char *token, const char *channelId, const char *userAccount, const ChannelMediaOptions &options)=0
virtual int | joinChannelWithUserAccountEx (const char *token, const char *channelId, const char *userAccount, const ChannelMediaOptions &options, IRtcEngineEventHandler *eventHandler)=0
virtual int | getUserInfoByUserAccount (const char *userAccount, rtc::UserInfo *userInfo)=0
virtual int | getUserInfoByUid (uid_t uid, rtc::UserInfo *userInfo)=0
virtual int | startOrUpdateChannelMediaRelay (const ChannelMediaRelayConfiguration &configuration)=0
virtual int | stopChannelMediaRelay ()=0
virtual int | pauseAllChannelMediaRelay ()=0
virtual int | resumeAllChannelMediaRelay ()=0
virtual int | setDirectCdnStreamingAudioConfiguration (AUDIO_PROFILE_TYPE profile)=0
virtual int | setDirectCdnStreamingVideoConfiguration (const VideoEncoderConfiguration &config)=0
virtual int | startDirectCdnStreaming (IDirectCdnStreamingEventHandler *eventHandler, const char *publishUrl, const DirectCdnStreamingMediaOptions &options)=0
virtual int | stopDirectCdnStreaming ()=0
virtual int | updateDirectCdnStreamingMediaOptions (const DirectCdnStreamingMediaOptions &options)=0
virtual int | startRhythmPlayer (const char *sound1, const char *sound2, const AgoraRhythmPlayerConfig &config)=0
virtual int | stopRhythmPlayer ()=0
virtual int | configRhythmPlayer (const AgoraRhythmPlayerConfig &config)=0
virtual int | takeSnapshot (uid_t uid, const char *filePath)=0
virtual int | takeSnapshot (uid_t uid, const media::SnapshotConfig &config)=0
virtual int | enableContentInspect (bool enabled, const media::ContentInspectConfig &config)=0
virtual int | setCloudProxy (CLOUD_PROXY_TYPE proxyType)=0
virtual int | setLocalAccessPoint (const LocalAccessPointConfiguration &config)=0
virtual int | setAdvancedAudioOptions (AdvancedAudioOptions &options, int sourceType=0)=0
virtual int | setAVSyncSource (const char *channelId, uid_t uid)=0
virtual int | enableVideoImageSource (bool enable, const ImageTrackOptions &options)=0
virtual int | enableWirelessAccelerate (bool enabled)=0
virtual int | getNetworkType ()=0
virtual int | setParameters (const char *parameters)=0
virtual int | startMediaRenderingTracing ()=0
virtual int | enableInstantMediaRendering ()=0
virtual uint64_t | getNtpWallTimeInMs ()=0
virtual bool | isFeatureAvailableOnDevice (FeatureType type)=0
virtual int | sendAudioMetadata (const char *metadata, size_t length)=0
virtual int | queryHDRCapability (VIDEO_MODULE_TYPE videoModule, HDR_CAPABILITY &capability)=0

## Static Public Member Functions
static AGORA_CPP_API void | release (RtcEngineReleaseCallback callback=nullptr)

## Detailed Description

The IRtcEngine class, which is the basic interface of the Agora SDK that implements the core functions of real-time communication.

`IRtcEngine` provides the main methods that your app can call.

## Member Function Documentation

## ◆ release()

static AGORA_CPP_API void release | ( | RtcEngineReleaseCallback | callback = `nullptr` | ) |
| static

Destroys the IRtcEngine object.

This method destroys the IRtcEngine instance and releases its associated resources. It is recommended for applications where users make occasional voice or video calls. When the real-time communication functionality is no longer needed, call this method to free up resources for other operations.

After a successful call, you can no longer use any methods or callbacks provided by the SDK. To use the real-time communication features again, you must create a new IRtcEngine instance by calling `createAgoraRtcEngine` and `initialize`.

Note
  If you plan to create a new IRtcEngine instance after destroying the current one, ensure that the `release` method has completed execution before creating the new instance. Do not call this method from within any SDK callback, as this may result in a deadlock.

Parameters

  callback | An optional pointer to the `RtcEngineReleaseCallback` function, used to configure synchronous or asynchronous destruction of the engine: Non-nullptr: Asynchronous destruction. The method returns immediately, and the engine resources may not be fully released yet. The `RtcEngineReleaseCallback` will be triggered once the engine destruction is complete. nullptr: Synchronous destruction. The method returns only after the engine resources have been fully released.

## ◆ initialize()

virtual int initialize | ( | const RtcEngineContext & | context | ) |
| pure virtual

Initializes `IRtcEngine`.

All called methods provided by the `IRtcEngine` class are executed asynchronously. Agora recommends calling these methods in the same thread.

Note
  - Before calling other APIs, you must call `createAgoraRtcEngine` and `initialize`to create and initialize the `IRtcEngine` object.
  - The SDK supports creating only one `IRtcEngine` instance for an app.

Parameters

  context | The RtcEngineContext object.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ queryInterface()

virtual int queryInterface | ( | INTERFACE_ID_TYPE | iid,
|  | void ** | inter
| ) |  |
| pure virtual

Gets the pointer to the specified interface.

Parameters

  iid | The ID of the interface. See INTERFACE_ID_TYPE for details.
  inter | Output parameter. The pointer to the specified interface.

Returns
  - 0: Success.
  - < 0: Failure.

Implements IEngineBase.

## ◆ getVersion()

virtual const char* getVersion | ( | int * | build | ) |
| pure virtual

Gets the SDK version.

Parameters

  build | The build number.

Returns
  The version of the current SDK in the string format.

## ◆ getErrorDescription()

virtual const char* getErrorDescription | ( | int | code | ) |
| pure virtual

Gets the warning or error description.

Parameters

  code | The error code or warning code reported by the SDK.

Returns
  The specific error or warning description.

## ◆ queryCodecCapability()

virtual int queryCodecCapability | ( | CodecCapInfo * | codecInfo,
|  | int & | size
| ) |  |
| pure virtual

Queries the capacity of the current device codec.

Parameters

  codecInfo | An array of the codec cap information: CodecCapInfo.
  size | The array size.

Returns
  0: Success. < 0: Failure.

## ◆ queryDeviceScore()

virtual int queryDeviceScore | ( |  | ) |
| pure virtual

Queries the score of the current device.

Returns

  > 0: If the value is greater than 0, it means that the device score has been retrieved and represents the score value.

  Most devices score between 60-100, with higher scores indicating better performance.

< 0: Failure.

## ◆ preloadChannel()

virtual int preloadChannel | ( | const char * | token,
|  | const char * | channelId,
|  | uid_t | uid
| ) |  |
| pure virtual

Preload a channel.

This method enables users to preload a channel.

A successful call of this method will reduce the time of joining the same channel.

Note:

1. The SDK supports preloading up to 20 channels. Once the preloaded channels exceed the limit, the SDK will keep the latest 20 available.
2. Renew the token of the preloaded channel by calling this method with the same 'channelId' and 'uid'.

Parameters

  token | The token generated on your server for authentication.
  channelId | The channel name. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported character scopes are: All lowercase English letters: a to z. All uppercase English letters: A to Z. All numeric characters: 0 to 9. The space character. Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
  uid | The user ID. This parameter is used to identify the user in the channel for real-time audio and video interaction. You need to set and manage user IDs yourself, and ensure that each user ID in the same channel is unique. This parameter is a 32-bit unsigned integer. The value range is 1 to 2<h>32</h>-1. If the user ID is not assigned (or set to 0), the SDK assigns a random user ID and returns it in the onJoinChannelSuccess callback. Your application must record and maintain the returned user ID, because the SDK does not do so.

Returns
  - 0: Success.
  - < 0: Failure.
    - -7: The IRtcEngine object has not been initialized. You need to initialize the IRtcEngine object before calling this method.
    - -102: The channel name is invalid. You need to pass in a valid channel name in channelId to preload the channel again.

## ◆ preloadChannelWithUserAccount()

virtual int preloadChannelWithUserAccount | ( | const char * | token,
|  | const char * | channelId,
|  | const char * | userAccount
| ) |  |
| pure virtual

Preload a channel.

This method enables users to preload a channel.

A successful call of this method will reduce the time of joining the same channel.

Note:

1. The SDK supports preloading up to 20 channels. Once the preloaded channels exceed the limit, the SDK will keep the latest 20 available.
2. Renew the token of the preloaded channel by calling this method with the same 'channelId' and 'userAccount'.

Parameters

  token | The token generated on your server for authentication.
  channelId | The channel name. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
  userAccount | The user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are: All lowercase English letters: a to z. All uppercase English letters: A to Z. All numeric characters: 0 to 9. The space character. Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".

Returns
  - 0: Success.
  - < 0: Failure.
    - -2: The parameter is invalid. For example, the userAccount parameter is empty. You need to pass in a valid parameter and preload the channel again.
    - -7: The IRtcEngine object has not been initialized. You need to initialize the IRtcEngine object before calling this method.
    - -102: The channel name is invalid. You need to pass in a valid channel name in channelId to preload the channel again.

## ◆ updatePreloadChannelToken()

virtual int updatePreloadChannelToken | ( | const char * | token | ) |
| pure virtual

Update token of the preloaded channels.

An easy way to update all preloaded channels' tokens, if all preloaded channels use the same token.

If preloaded channels use different tokens, we need to call the 'preloadChannel' method with the same 'channelId' and 'uid' or 'userAccount' to update the corresponding token.

Parameters

  token | The token generated on your server for authentication.

Returns
  - 0: Success.
  - < 0: Failure.
    - -2: The token is invalid. You need to pass in a valid token and update the token again.
    - -7: The IRtcEngine object has not been initialized. You need to initialize the IRtcEngine object before calling this method.

## ◆ joinChannel() [1/2]

virtual int joinChannel | ( | const char * | token,
|  | const char * | channelId,
|  | const char * | info,
|  | uid_t | uid
| ) |  |
| pure virtual

Joins a channel.

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

A successful call of this method triggers the following callbacks:

- The local client: The `onJoinChannelSuccess` and `onConnectionStateChanged` callbacks.
- 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.

Note
  Once a user joins the 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. To stop subscribing to a specified stream or all remote streams, call the corresponding `mute` methods.

Parameters

  token | The token generated on your server for authentication.
  channelId | The channel name. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported character scopes are: All lowercase English letters: a to z. All uppercase English letters: A to Z. All numeric characters: 0 to 9. The space character. Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
  info | (Optional) Reserved for future use.
  uid | The user ID. This parameter is used to identify the user in the channel for real-time audio and video interaction. You need to set and manage user IDs yourself, and ensure that each user ID in the same channel is unique. This parameter is a 32-bit unsigned integer. The value range is 1 to 2<h>32</h>-1. If the user ID is not assigned (or set to 0), the SDK assigns a random user ID and returns it in the onJoinChannelSuccess callback. Your application must record and maintain the returned user ID, because the SDK does not do so.

Returns
  - 0: Success.
  - < 0: Failure.
    - -2: The parameter is invalid. For example, the token is invalid, the uid parameter is not set to an integer, or the value of a member in the `ChannelMediaOptions` structure is invalid. You need to pass in a valid parameter and join the channel again.
    - -3: Failes to initialize the `IRtcEngine` object. You need to reinitialize the IRtcEngine object.
    - -7: The IRtcEngine object has not been initialized. You need to initialize the IRtcEngine object before calling this method.
    - -8: The internal state of the IRtcEngine object is wrong. The typical cause is that you call this method to join the channel without calling `stopEchoTest` to stop the test after calling `startEchoTest` to start a call loop test. You need to call `stopEchoTest` before calling this method.
    - -17: The request to join the channel is rejected. The typical cause is that the user is in the channel. Agora recommends using the `onConnectionStateChanged` callback to get whether the user is in the channel. Do not call this method to join the channel unless you receive the `CONNECTION_STATE_DISCONNECTED(1)` state.
    - -102: The channel name is invalid. You need to pass in a valid channel name in channelId to rejoin the channel.
    - -121: The user ID is invalid. You need to pass in a valid user ID in uid to rejoin the channel.

## ◆ joinChannel() [2/2]

virtual int joinChannel | ( | const char * | token,
|  | const char * | channelId,
|  | uid_t | uid,
|  | const ChannelMediaOptions & | options
| ) |  |
| pure virtual

Joins a channel with media options.

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

A successful call of this method triggers the following callbacks:

- The local client: The `onJoinChannelSuccess` and `onConnectionStateChanged` callbacks.
- 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.

Compared to `joinChannel`, this method adds the options parameter to configure whether to automatically subscribe to all remote audio and video streams in the channel when the user joins the channel. By default, the user subscribes to the audio and video streams of all the other users in the channel, giving rise to usage and billings. To unsubscribe, set the `options` parameter or call the `mute` methods accordingly.

Note
  - This method allows users to join only one channel at a time.
  - Ensure that the app ID you use to generate the token is the same app ID that you pass in the `initialize` method; otherwise, you may fail to join the channel by token.

Parameters

  token | The token generated on your server for authentication.
  channelId | The channel name. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported character scopes are: All lowercase English letters: a to z. All uppercase English letters: A to Z. All numeric characters: 0 to 9. The space character. Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
  uid | The user ID. This parameter is used to identify the user in the channel for real-time audio and video interaction. You need to set and manage user IDs yourself, and ensure that each user ID in the same channel is unique. This parameter is a 32-bit unsigned integer. The value range is 1 to 2<h>32</h>-1. If the user ID is not assigned (or set to 0), the SDK assigns a random user ID and returns it in the `onJoinChannelSuccess` callback. Your application must record and maintain the returned user ID, because the SDK does not do so.
  options | The channel media options: ChannelMediaOptions.

Returns
  - 0: Success.
  - < 0: Failure.
    - -2: The parameter is invalid. For example, the token is invalid, the uid parameter is not set to an integer, or the value of a member in the `ChannelMediaOptions` structure is invalid. You need to pass in a valid parameter and join the channel again.
    - -3: Failes to initialize the `IRtcEngine` object. You need to reinitialize the IRtcEngine object.
    - -7: The IRtcEngine object has not been initialized. You need to initialize the IRtcEngine object before calling this method.
    - -8: The internal state of the IRtcEngine object is wrong. The typical cause is that you call this method to join the channel without calling `stopEchoTest` to stop the test after calling `startEchoTest` to start a call loop test. You need to call `stopEchoTest` before calling this method.
    - -17: The request to join the channel is rejected. The typical cause is that the user is in the channel. Agora recommends using the `onConnectionStateChanged` callback to get whether the user is in the channel. Do not call this method to join the channel unless you receive the `CONNECTION_STATE_DISCONNECTED(1)` state.
    - -102: The channel name is invalid. You need to pass in a valid channel name in channelId to rejoin the channel.
    - -121: The user ID is invalid. You need to pass in a valid user ID in uid to rejoin the channel.

## ◆ updateChannelMediaOptions()

virtual int updateChannelMediaOptions | ( | const ChannelMediaOptions & | options | ) |
| pure virtual

Updates the channel media options after joining the channel.

Parameters

  options | The channel media options: ChannelMediaOptions.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ leaveChannel() [1/2]

virtual int leaveChannel | ( |  | ) |
| pure virtual

Leaves the channel.

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

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

Note
  If you call release immediately after this method, the leaveChannel process will be interrupted, and the SDK will not trigger the `onLeaveChannel` callback.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ leaveChannel() [2/2]

virtual int leaveChannel | ( | const LeaveChannelOptions & | options | ) |
| pure virtual

Leaves the channel.

Parameters

  options | The leave channel options.

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

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

Note
  If you call release immediately after this method, the leaveChannel process will be interrupted, and the SDK will not trigger the `onLeaveChannel` callback.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ renewToken()

virtual int renewToken | ( | const char * | token | ) |
| pure virtual

Renews the token.

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

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

- The IRtcEngineEventHandler onTokenPrivilegeWillExpire "onTokenPrivilegeWillExpire" callback is triggered;
- The onRequestToken callback is triggered;
- The `ERR_TOKEN_EXPIRED(-109)` error is reported.

Parameters

  token | The new token.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setChannelProfile()

virtual int setChannelProfile | ( | CHANNEL_PROFILE_TYPE | profile | ) |
| pure virtual

Sets the channel profile.

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

Note
  - To ensure the quality of real-time communication, we recommend that all users in a channel use the same channel profile.
  - Call this method before calling `joinChannel`. You cannot set the channel profile once you have joined the channel.

Parameters

  profile | The channel profile: CHANNEL_PROFILE_TYPE.

Returns
  - 0: Success.
  - < 0: Failure.
    - -8(ERR_INVALID_STATE): The current status is invalid, only allowed to be called when the connection is disconnected.

## ◆ setClientRole() [1/2]

virtual int setClientRole | ( | CLIENT_ROLE_TYPE | role | ) |
| pure virtual

Sets the role of a user.

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

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

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

Note
  After calling the setClientRole() method to CLIENT_ROLE_AUDIENCE, the SDK stops audio recording. However, CLIENT_ROLE_AUDIENCE will keep audio recording with AUDIO_SCENARIO_CHATROOM(5). Normally, app developer can also use mute api to achieve the same result, and we implement this 'non-orthogonal' behavior only to make API backward compatible.

Parameters

  role | The role of the client: CLIENT_ROLE_TYPE.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setClientRole() [2/2]

virtual int setClientRole | ( | CLIENT_ROLE_TYPE | role,
|  | const ClientRoleOptions & | options
| ) |  |
| pure virtual

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

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

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

- The local client: onClientRoleChanged
- The remote client: onUserJoined or onUserOffline (BECOME_AUDIENCE)

Note
  This method applies only to the `LIVE_BROADCASTING` profile.

Parameters

  role | Sets the role of the user. See CLIENT_ROLE_TYPE.
  options | Sets the audience latency level of the user. See #ClientRoleOptions.

Returns
  - 0(ERR_OK): Success.
  - < 0: Failure.
    - -1(ERR_FAILED): A general error occurs (no specified reason).
    - -2(ERR_INALID_ARGUMENT): The parameter is invalid.
    - -7(ERR_NOT_INITIALIZED): The SDK is not initialized.
    - -8(ERR_INVALID_STATE): The channel profile is not `LIVE_BROADCASTING`.

## ◆ startEchoTest()

virtual int startEchoTest | ( | const EchoTestConfiguration & | config | ) |
| pure virtual

Starts a video call test.

Parameters

  config | configuration for video call test.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableVideo()

virtual int enableVideo | ( |  | ) |
| pure virtual

Enables the video.

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

Note
  This method controls the underlying states of the Engine. It is still valid after one leaves the channel.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ disableVideo()

virtual int disableVideo | ( |  | ) |
| pure virtual

Disables the video.

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

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

## ◆ startPreview() [1/2]

virtual int startPreview | ( |  | ) |
| pure virtual

Starts the local video preview before joining a channel.

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

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ startPreview() [2/2]

virtual int startPreview | ( | VIDEO_SOURCE_TYPE | sourceType | ) |
| pure virtual

Starts the local video preview for specific source type.

Parameters

  sourceType | - The video source type.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ stopPreview() [1/2]

virtual int stopPreview | ( |  | ) |
| pure virtual

Stops the local video preview and the video.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ stopPreview() [2/2]

virtual int stopPreview | ( | VIDEO_SOURCE_TYPE | sourceType | ) |
| pure virtual

Stops the local video preview for specific source type.

Parameters

  sourceType | - The video source type.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ startLastmileProbeTest()

virtual int startLastmileProbeTest | ( | const LastmileProbeConfig & | config | ) |
| pure virtual

Starts the last-mile network probe test.

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

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

- onLastmileQuality: the SDK triggers this callback depending on the network conditions. This callback rates the network conditions and is more closely linked to the user experience.
- onLastmileProbeResult: the SDK triggers this callback within 30 seconds depending on the network conditions. This callback returns the real-time statistics of the network conditions and is more objective.

Note
  - Do not call other methods before receiving the onLastmileQuality and onLastmileProbeResult callbacks. Otherwise, the callbacks may be interrupted.
  - In the Live-broadcast profile, a host should not call this method after joining a channel.

Parameters

  config | Sets the configurations of the last-mile network probe test. See LastmileProbeConfig.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ stopLastmileProbeTest()

virtual int stopLastmileProbeTest | ( |  | ) |
| pure virtual

Stops the last-mile network probe test.

## ◆ setVideoEncoderConfiguration()

virtual int setVideoEncoderConfiguration | ( | const VideoEncoderConfiguration & | config | ) |
| pure virtual

Sets the video encoder configuration.

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

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

Parameters

  config | The local video encoder configuration: VideoEncoderConfiguration.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setFaceShapeBeautyOptions()

virtual int setFaceShapeBeautyOptions | ( | bool | enabled,
|  | const FaceShapeBeautyOptions & | options,
|  | agora::media::MEDIA_SOURCE_TYPE | type = `agora::media::PRIMARY_CAMERA_SOURCE`
| ) |  |
| pure virtual

Enables/Disables face shape and sets the beauty options.

Note
  Call this method after calling the enableVideo method.

Parameters

  enabled | Sets whether or not to enable face shape: true: enables face shape. false: disables face shape.
  options | Sets the face shape beauty option. See FaceShapeBeautyOptions.

## ◆ setFaceShapeAreaOptions()

virtual int setFaceShapeAreaOptions | ( | const FaceShapeAreaOptions & | options,
|  | agora::media::MEDIA_SOURCE_TYPE | type = `agora::media::PRIMARY_CAMERA_SOURCE`
| ) |  |
| pure virtual

Enables/Disables face shape and sets the area options.

Note
  Call this method after calling the setFaceShapeBeautyOptions method.

Parameters

  options | Sets the face shape area option. See FaceShapeAreaOptions.

## ◆ getFaceShapeBeautyOptions()

virtual int getFaceShapeBeautyOptions | ( | FaceShapeBeautyOptions & | options,
|  | agora::media::MEDIA_SOURCE_TYPE | type = `agora::media::PRIMARY_CAMERA_SOURCE`
| ) |  |
| pure virtual

Gets the face shape beauty options.

Note
  Call this method after calling the enableVideo method.

Parameters

  options | Gets the face shape beauty option. See FaceShapeBeautyOptions.

## ◆ getFaceShapeAreaOptions()

virtual int getFaceShapeAreaOptions | ( | agora::rtc::FaceShapeAreaOptions::FACE_SHAPE_AREA | shapeArea,
|  | FaceShapeAreaOptions & | options,
|  | agora::media::MEDIA_SOURCE_TYPE | type = `agora::media::PRIMARY_CAMERA_SOURCE`
| ) |  |
| pure virtual

Gets the face shape area options.

Note
  Call this method after calling the enableVideo method.

Parameters

  shapeArea | The face area. See FaceShapeAreaOptions::FACE_SHAPE_AREA.
  options | Gets the face area beauty option. See FaceShapeAreaOptions.

## ◆ setLowlightEnhanceOptions()

virtual int setLowlightEnhanceOptions | ( | bool | enabled,
|  | const LowlightEnhanceOptions & | options,
|  | agora::media::MEDIA_SOURCE_TYPE | type = `agora::media::PRIMARY_CAMERA_SOURCE`
| ) |  |
| pure virtual

Sets low-light enhancement.

Since
  v4.0.0

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

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

Note
  - Before calling this method, ensure that you have integrated the following dynamic library into your project:
    - Android: `libagora_clear_vision_extension.so`
    - iOS/macOS: `AgoraClearVisionExtension.xcframework`
    - Windows: `libagora_clear_vision_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

  enabled | Sets whether to enable low-light enhancement: `true`: Enable. `false`: (Default) Disable.
  options | The low-light enhancement options. See LowlightEnhanceOptions.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setVideoDenoiserOptions()

virtual int setVideoDenoiserOptions | ( | bool | enabled,
|  | const VideoDenoiserOptions & | options,
|  | agora::media::MEDIA_SOURCE_TYPE | type = `agora::media::PRIMARY_CAMERA_SOURCE`
| ) |  |
| pure virtual

Sets video noise reduction.

Since
  v4.0.0

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

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

Note
  - Before calling this method, ensure that you have integrated the following dynamic library into your project:
    - Android: `libagora_clear_vision_extension.so`
    - iOS/macOS: `AgoraClearVisionExtension.xcframework`
    - Windows: `libagora_clear_vision_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

  enabled | Sets whether to enable video noise reduction: `true`: Enable. `false`: (Default) Disable.
  options | The video noise reduction options. See VideoDenoiserOptions.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setColorEnhanceOptions()

virtual int setColorEnhanceOptions | ( | bool | enabled,
|  | const ColorEnhanceOptions & | options,
|  | agora::media::MEDIA_SOURCE_TYPE | type = `agora::media::PRIMARY_CAMERA_SOURCE`
| ) |  |
| pure virtual

Sets color enhancement.

Since
  v4.0.0

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

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

Note
  - Before calling this method, ensure that you have integrated the following dynamic library into your project:
    - Android: `libagora_clear_vision_extension.so`
    - iOS/macOS: `AgoraClearVisionExtension.xcframework`
    - Windows: `libagora_clear_vision_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

  enabled | Sets whether to enable color enhancement: `true`: Enable. `false`: (Default) Disable.
  options | The color enhancement options. See ColorEnhanceOptions.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableVirtualBackground()

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

Enables/Disables the virtual background. (beta function)

Since
  v3.7.200

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

Note
  - Before calling this method, ensure that you have integrated the `libagora_segmentation_extension.dll` (Windows)/`AgoraVideoSegmentationExtension.framework` (macOS) dynamic library into the project folder.
  - Call this method after enableVideo.
  - This function requires a high-performance device. Agora recommends that you use this function on devices with an i5 CPU and better.
  - Agora recommends that you use this function in scenarios that meet the following conditions:
    - A high-definition camera device is used, and the environment is uniformly lit.
    - The captured video image is uncluttered, the user's portrait is half-length and largely unobstructed, and the background is a single color that differs from the color of the user's clothing.

Parameters

  enabled | Sets whether to enable the virtual background: true: Enable. false: Disable.
  backgroundSource | The 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.

## ◆ setupRemoteVideo()

virtual int setupRemoteVideo | ( | const VideoCanvas & | canvas | ) |
| pure virtual

Initializes the video view of a remote user.

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

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

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

Note
  Ensure that you call this method in the UI thread.

Parameters

  canvas | The remote video view settings: VideoCanvas.

Returns
  int VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_SUCCESS = 0, VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_IMAGE_NOT_EXIST = -1, VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_COLOR_FORMAT_NOT_SUPPORTED = -2, VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_DEVICE_NOT_SUPPORTED = -3,

## ◆ setupLocalVideo()

virtual int setupLocalVideo | ( | const VideoCanvas & | canvas | ) |
| pure virtual

Initializes the local video view.

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

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

Note
  Call this method before joining a channel.

Parameters

  canvas | The local video view setting: VideoCanvas.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setVideoScenario()

virtual int setVideoScenario | ( | VIDEO_APPLICATION_SCENARIO_TYPE | scenarioType | ) |
| pure virtual

Sets the Video application scenario.

Since
  v4.2.0

You can call this method to set the expected video scenario. The SDK will optimize the video experience for each scenario you set.

Parameters

  scenarioType | The video application scenario. See #ApplicationScenarioType.

Returns
  - 0: Success.
  - < 0: Failure.
  - ERR_FAILED (1): A general error occurs (no specified reason).
  - ERR_NOT_SUPPORTED (4): Unable to set video application scenario.
  - ERR_NOT_INITIALIZED (7): The SDK is not initialized.

## ◆ setVideoQoEPreference()

virtual int setVideoQoEPreference | ( | VIDEO_QOE_PREFERENCE_TYPE | qoePreference | ) |
| pure virtual

Sets the video qoe preference.

Since
  v4.2.1

You can call this method to set the expected QoE Preference. The SDK will optimize the video experience for each preference you set.

Parameters

  qoePreference | The qoe preference type. See VIDEO_QOE_PREFERENCE_TYPE.

Returns
  - 0: Success.
  - < 0: Failure.
  - ERR_FAILED (1): A general error occurs (no specified reason).
  - ERR_NOT_SUPPORTED (4): Unable to set video application scenario.
  - ERR_NOT_INITIALIZED (7): The SDK is not initialized.

## ◆ enableAudio()

virtual int enableAudio | ( |  | ) |
| pure virtual

Enables the audio.

The audio is enabled by default.

Note
  This method controls the underlying states of the Engine. It is still valid after one leaves channel.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ disableAudio()

virtual int disableAudio | ( |  | ) |
| pure virtual

Disables the audio.

Note
  This method controls the underlying states of the Engine. It is still valid after one leaves channel.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setAudioProfile() [1/2]

virtual int setAudioProfile | ( | AUDIO_PROFILE_TYPE | profile,
|  | AUDIO_SCENARIO_TYPE | scenario
| ) |  |
| pure virtual

Sets the audio parameters and application scenarios.

Deprecated:
  This method is deprecated. You can use the setAudioProfile method instead. To set the audio scenario, call the initialize method and pass value in the `audioScenario` member in the RtcEngineContext struct.

Note
  - Call this method before calling the `joinChannel` method.
  - In scenarios requiring high-quality audio, we recommend setting `profile` as `MUSIC_HIGH_QUALITY`(4) and `scenario` as `AUDIO_SCENARIO_GAME_STREAMING`(3).

Parameters

  profile | Sets the sample rate, bitrate, encoding mode, and the number of channels: AUDIO_PROFILE_TYPE.
  scenario | Sets the audio application scenarios: AUDIO_SCENARIO_TYPE.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setAudioProfile() [2/2]

virtual int setAudioProfile | ( | AUDIO_PROFILE_TYPE | profile | ) |
| pure virtual

Sets the audio profile.

Note
  - Call this method before calling the `joinChannel` method.
  - In scenarios requiring high-quality audio, Agora recommends setting `profile` as `MUSIC_HIGH_QUALITY`(4).
  - To set the audio scenario, call the initialize method and pass value in the `audioScenario` member in the RtcEngineContext struct.

Parameters

  profile | The audio profile, such as the sample rate, bitrate and codec type: AUDIO_PROFILE_TYPE.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setAudioScenario()

virtual int setAudioScenario | ( | AUDIO_SCENARIO_TYPE | scenario | ) |
| pure virtual

Set the audio scenario.

Parameters

  scenario | The audio scenario: AUDIO_SCENARIO_TYPE.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableLocalAudio()

virtual int enableLocalAudio | ( | bool | enabled | ) |
| pure virtual

Enables or disables the local audio capture.

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

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

Parameters

  enabled | Determines whether to disable or re-enable the local audio function: true: (Default) Re-enable the local audio function, that is, to start local audio capture and processing. false: Disable the local audio function, that is, to stop local audio capture and processing.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ muteLocalAudioStream()

virtual int muteLocalAudioStream | ( | bool | mute | ) |
| pure virtual

Stops or resumes sending the local audio stream.

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

- REMOTE_AUDIO_STATE_STOPPED(0) and REMOTE_AUDIO_REASON_REMOTE_MUTED(5).
- REMOTE_AUDIO_STATE_DECODING(2) and REMOTE_AUDIO_REASON_REMOTE_UNMUTED(6).

Note
  - When `mute` is set as `true`, this method does not disable the microphone, which does not affect any ongoing recording.
  - If you call setChannelProfile after this method, the SDK resets whether or not to mute the local audio according to the channel profile and user role. Therefore, we recommend calling this method after the `setChannelProfile` method.

Parameters

  mute | Determines whether to send or stop sending the local audio stream: true: Stop sending the local audio stream. false: (Default) Send the local audio stream.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ muteAllRemoteAudioStreams()

virtual int muteAllRemoteAudioStreams | ( | bool | mute | ) |
| pure virtual

Stops or resumes receiving all remote audio stream.

This method works for all remote users that join or will join a channel using the `joinChannel` method. It is equivalent to the `autoSubscribeAudio` member in the ChannelMediaOptions class.

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

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

- To resume receiving all remote audio streams, call muteAllRemoteAudioStreams(false).
- To resume receiving the audio stream of a specified user, call muteRemoteAudioStream(uid, false), where uid is the ID of the user whose audio stream you want to resume receiving.

Note
  - The result of calling this method is affected by calling enableAudio and disableAudio. Settings in muteAllRemoteAudioStreams stop taking effect if either of the following occurs:
    - Calling `enableAudio` after muteAllRemoteAudioStreams(true).
    - Calling `disableAudio` after muteAllRemoteAudioStreams(false).
  - This method only works for the channel created by calling `joinChannel`. To set whether to receive remote audio streams for a specific channel, Agora recommends using `autoSubscribeAudio` in the ChannelMediaOptions class.

Parameters

  mute | Whether to stop receiving remote audio streams: true: Stop receiving any remote audio stream. false: (Default) Resume receiving all remote audio streams.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ muteRemoteAudioStream()

virtual int muteRemoteAudioStream | ( | uid_t | uid,
|  | bool | mute
| ) |  |
| pure virtual

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

Note
  You can call this method before or after joining a channel. If a user leaves a channel, the settings in this method become invalid.

Parameters

  uid | The ID of the specified user.
  mute | Whether to stop receiving the audio stream of the specified user: true: Stop receiving the audio stream of the specified user. false: (Default) Resume receiving the audio stream of the specified user.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ muteLocalVideoStream()

virtual int muteLocalVideoStream | ( | bool | mute | ) |
| pure virtual

Stops or resumes sending the local video stream.

Parameters

  mute | Determines whether to send or stop sending the local video stream: true: Stop sending the local video stream. false: (Default) Send the local video stream.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableLocalVideo()

virtual int enableLocalVideo | ( | bool | enabled | ) |
| pure virtual

Disables or re-enables the local video capture.

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

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

Note
  Call this method after `enableVideo`. Otherwise, this method may not work properly.

Parameters

  enabled | Determines whether to disable or re-enable the local video, including the capturer, renderer, and sender: true: (Default) Re-enable the local video. false: Disable the local video. Once the local video is disabled, the remote users can no longer receive the video stream of this user, while this user can still receive the video streams of other remote users. When you set `enabled` as `false`, this method does not require a local camera.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ muteAllRemoteVideoStreams()

virtual int muteAllRemoteVideoStreams | ( | bool | mute | ) |
| pure virtual

Stops or resumes receiving all remote video streams.

This method works for all remote users that join or will join a channel using the `joinChannel` method. It is equivalent to the `autoSubscribeVideo` member in the ChannelMediaOptions class.

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

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

- To resume receiving all remote video streams, call muteAllRemoteVideoStreams(false).
- To resume receiving the video stream of a specified user, call muteRemoteVideoStream(uid, false), where uid is the ID of the user whose video stream you want to resume receiving.

Note
  - The result of calling this method is affected by calling enableVideo and disableVideo. Settings in muteAllRemoteVideoStreams stop taking effect if either of the following occurs:
    - Calling `enableVideo` after muteAllRemoteVideoStreams(true).
    - Calling `disableVideo` after muteAllRemoteVideoStreams(false).
  - This method only works for the channel created by calling `joinChannel`. To set whether to receive remote audio streams for a specific channel, Agora recommends using `autoSubscribeVideo` in the ChannelMediaOptions class.

Parameters

  mute | Whether to stop receiving remote video streams: true: Stop receiving any remote video stream. false: (Default) Resume receiving all remote video streams.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setRemoteDefaultVideoStreamType()

virtual int setRemoteDefaultVideoStreamType | ( | VIDEO_STREAM_TYPE | streamType | ) |
| pure virtual

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

Parameters

  streamType | Sets the default video stream type: VIDEO_STREAM_TYPE.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ muteRemoteVideoStream()

virtual int muteRemoteVideoStream | ( | uid_t | uid,
|  | bool | mute
| ) |  |
| pure virtual

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

Note
  You can call this method before or after joining a channel. If a user leaves a channel, the settings in this method become invalid.

Parameters

  uid | The ID of the specified user.
  mute | Whether to stop receiving the video stream of the specified user: true: Stop receiving the video stream of the specified user. false: (Default) Resume receiving the video stream of the specified user.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setRemoteVideoStreamType()

virtual int setRemoteVideoStreamType | ( | uid_t | uid,
|  | VIDEO_STREAM_TYPE | streamType
| ) |  |
| pure virtual

Sets the remote video stream type.

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

Note
  This method applies to scenarios where the remote user has enabled the dual-stream mode using enableDualStreamMode(true) before joining the channel.

Parameters

  uid | ID of the remote user sending the video stream.
  streamType | Sets the video stream type: VIDEO_STREAM_TYPE.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setRemoteVideoSubscriptionOptions()

virtual int setRemoteVideoSubscriptionOptions | ( | uid_t | uid,
|  | const VideoSubscriptionOptions & | options
| ) |  |
| pure virtual

Sets the remote video subscription options

Parameters

  uid | ID of the remote user sending the video stream.
  options | Sets the video subscription options.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setSubscribeAudioAllowlist()

virtual int setSubscribeAudioAllowlist | ( | uid_t * | uidList,
|  | int | uidNumber
| ) |  |
| pure virtual

Sets the allowlist of subscribe remote stream audio.

Parameters

  uidList | The id list of users whose audio you want to subscribe to.
  uidNumber | The number of uid in uidList.

Note
  If uid is in uidList, the remote user's audio will be subscribed, even if muteRemoteAudioStream(uid, true) and muteAllRemoteAudioStreams(true) are operated.

If a user is in the blocklist and allowlist at the same time, only the blocklist takes effect.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setSubscribeVideoAllowlist()

virtual int setSubscribeVideoAllowlist | ( | uid_t * | uidList,
|  | int | uidNumber
| ) |  |
| pure virtual

Sets the allowlist of subscribe remote stream video.

Parameters

  uidList | The id list of users whose video you want to subscribe to.
  uidNumber | The number of uid in uidList.

Note
  If uid is in uidList, the remote user's video will be subscribed, even if muteRemoteVideoStream(uid, true) and muteAllRemoteVideoStreams(true) are operated.

If a user is in the blocklist and allowlist at the same time, only the blocklist takes effect.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableAudioVolumeIndication()

virtual int enableAudioVolumeIndication | ( | int | interval,
|  | int | smooth,
|  | bool | reportVad
| ) |  |
| pure virtual

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

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

Parameters

  interval | Sets the time interval between two consecutive volume indications: <= 0: Disables the volume indication. > 0: Time interval (ms) between two consecutive volume indications, and should be integral multiple of 200 (less than 200 will be set to 200).
  smooth | The smoothing factor that sets the sensitivity of the audio volume indicator. The value range is [0, 10]. The greater the value, the more sensitive the indicator. The recommended value is 3.
  reportVad | `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.

## ◆ startAudioRecording() [1/3]

virtual int startAudioRecording | ( | const char * | filePath,
|  | AUDIO_RECORDING_QUALITY_TYPE | quality
| ) |  |
| pure virtual

Starts an audio recording.

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

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

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

Parameters

  filePath | Full file path of the recording file. The string of the file name is in UTF-8 code.
  quality | Sets the audio recording quality: AUDIO_RECORDING_QUALITY_TYPE.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ startAudioRecording() [2/3]

virtual int startAudioRecording | ( | const char * | filePath,
|  | int | sampleRate,
|  | AUDIO_RECORDING_QUALITY_TYPE | quality
| ) |  |
| pure virtual

Starts an audio recording.

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

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

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

Parameters

  filePath | Full file path of the recording file. The string of the file name is in UTF-8 code.
  sampleRate | Sample rate, value should be 16000, 32000, 44100, or 48000.
  quality | Sets the audio recording quality: AUDIO_RECORDING_QUALITY_TYPE.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ startAudioRecording() [3/3]

virtual int startAudioRecording | ( | const AudioRecordingConfiguration & | config | ) |
| pure virtual

Starts an audio recording.

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

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

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

Parameters

  config | Audio recording config.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ registerAudioEncodedFrameObserver()

virtual int registerAudioEncodedFrameObserver | ( | const AudioEncodedFrameObserverConfig & | config,
|  | IAudioEncodedFrameObserver * | observer
| ) |  |
| pure virtual

register encoded audio frame observer

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ createMediaPlayer()

virtual agora_refptr<IMediaPlayer> createMediaPlayer | ( |  | ) |
| pure virtual

Creates a media player source object and return its pointer. If full featured media player source is supported, it will create it, or it will create a simple media player.

Returns
  - The pointer to IMediaPlayerSource, if the method call succeeds.
  - The empty pointer NULL, if the method call fails.

## ◆ destroyMediaPlayer()

virtual int destroyMediaPlayer | ( | agora_refptr< IMediaPlayer > | media_player | ) |
| pure virtual

Destroy a media player source instance. If a media player source instance is destroyed, the video and audio of it cannot be published.

Parameters

  media_player | The pointer to rtc::IMediaPlayerSource.

Returns
  - >0: The id of media player source instance.
  - < 0: Failure.

## ◆ createMediaRecorder()

virtual agora_refptr<IMediaRecorder> createMediaRecorder | ( | const RecorderStreamInfo & | info | ) |
| pure virtual

Creates a media recorder object and return its pointer.

Parameters

  info | The RecorderStreamInfo object. It contains the user ID and the channel name.

Returns
  - The pointer to IMediaRecorder, if the method call succeeds.
  - The empty pointer NULL, if the method call fails.

## ◆ destroyMediaRecorder()

virtual int destroyMediaRecorder | ( | agora_refptr< IMediaRecorder > | mediaRecorder | ) |
| pure virtual

Destroy a media recorder object.

Parameters

  mediaRecorder | The pointer to rtc::IMediaRecorder.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ selectAudioTrack()

virtual int selectAudioTrack | ( | int | index | ) |
| pure virtual

Select audio track for the music file.

Call this method when you are in a channel.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ getAudioTrackCount()

virtual int getAudioTrackCount | ( |  | ) |
| pure virtual

Get audio track count of the music file.

Call this method when you are in a channel.

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

## ◆ enableSoundPositionIndication()

virtual int 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

  enabled | Sets whether or not to enable stereo panning for remote users: true: enables stereo panning. false: disables stereo panning.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setRemoteVoicePosition()

virtual int 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

  uid | The ID of the remote user.
  pan | The 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.
  gain | Gain of the remote user. The value ranges from 0.0 to 100.0. The default value is 100.0 (the original gain of the remote user). The smaller the value, the less the gain.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableSpatialAudio()

virtual int enableSpatialAudio | ( | bool | enabled | ) |
| pure virtual

enable spatial audio

Parameters

  enabled | enable/disable spatial audio: true: enable spatial audio. false: disable spatial audio.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setVoiceBeautifierPreset()

virtual int setVoiceBeautifierPreset | ( | VOICE_BEAUTIFIER_PRESET | preset | ) |
| pure virtual

Sets an SDK preset voice beautifier effect.

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

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

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

Note
  - You can call this method either before or after joining a channel.
  - Do not set the `profile` parameter of setAudioProfile to `AUDIO_PROFILE_SPEECH_STANDARD(1)` or `AUDIO_PROFILE_IOT(6)`; otherwise, this method call fails.
  - This method works best with the human voice. Agora does not recommend using this method for audio containing music.
  - After calling this method, Agora recommends not calling the following methods, because they can override setAudioEffectParameters:
    - setAudioEffectPreset
    - setVoiceBeautifierPreset
    - setLocalVoicePitch
    - setLocalVoiceEqualization
    - setLocalVoiceReverb
    - setVoiceBeautifierParameters

Parameters

  preset | The options for SDK preset voice beautifier effects: VOICE_BEAUTIFIER_PRESET.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setVoiceConversionPreset()

virtual int setVoiceConversionPreset | ( | VOICE_CONVERSION_PRESET | preset | ) |
| pure virtual

Sets an SDK preset voice conversion.

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

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

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

Note
  - You can call this method either before or after joining a channel.
  - Do not set the profile `parameter` of `setAudioProfile` to `AUDIO_PROFILE_SPEECH_STANDARD(1)` or `AUDIO_PROFILE_IOT(6)`; otherwise, this method call fails.
  - This method works best with the human voice. Agora does not recommend using this method for audio containing music.
  - If you call this method and set the `preset` parameter to enumerators,
  - After calling this method, Agora recommends not calling the following methods, because they can override `setVoiceConversionPreset`:
    - setVoiceBeautifierPreset
    - setAudioEffectPreset
    - setLocalVoicePitch
    - setLocalVoiceFormant
    - setLocalVoiceEqualization
    - setLocalVoiceReverb
    - setVoiceBeautifierParameters
    - setAudioEffectParameters

Parameters

  preset | The options for SDK preset voice conversion. See VOICE_CONVERSION_PRESET.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setVoiceBeautifierParameters()

virtual int setVoiceBeautifierParameters | ( | VOICE_BEAUTIFIER_PRESET | preset,
|  | int | param1,
|  | int | param2
| ) |  |
| pure virtual

Sets parameters for SDK preset voice beautifier effects.

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

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

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

Note
  - You can call this method either before or after joining a channel.
  - Do not set the `profile` parameter of setAudioProfile as `AUDIO_PROFILE_SPEECH_STANDARD(1)` or `AUDIO_PROFILE_IOT(6)`; otherwise, this method call does not take effect.
  - This method works best with the human voice. Agora does not recommend using this method for audio containing music.
  - After you call this method, Agora recommends not calling the following methods, because they can override `setVoiceBeautifierParameters`:
    - setAudioEffectPreset
    - setAudioEffectParameters
    - setVoiceBeautifierPreset
    - setLocalVoicePitch
    - setLocalVoiceEqualization
    - setLocalVoiceReverb

Parameters

  preset | The options for SDK preset voice beautifier effects: `SINGING_BEAUTIFIER`: Singing beautifier effect.
  param1 | The gender characteristics options for the singing voice: `1`: A male-sounding voice. `2`: A female-sounding voice.
  param2 | The reverberation effects options: `1`: The reverberation effect sounds like singing in a small room. `2`: The reverberation effect sounds like singing in a large room. `3`: The reverberation effect sounds like singing in a hall.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setVoiceConversionParameters()

virtual int setVoiceConversionParameters | ( | VOICE_CONVERSION_PRESET | preset,
|  | int | param1,
|  | int | param2
| ) |  |
| pure virtual

Set parameters for SDK preset voice conversion.

Note
  - reserved interface

Parameters

  preset | The options for SDK preset audio effects. See VOICE_CONVERSION_PRESET.
  param1 | reserved.
  param2 | reserved.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setHeadphoneEQPreset()

virtual int setHeadphoneEQPreset | ( | HEADPHONE_EQUALIZER_PRESET | preset | ) |
| pure virtual

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

Parameters

  preset | The preset key: HEADPHONE_EQUALIZER_PRESET. HEADPHONE_EQUALIZER_OFF = 0x00000000 : Turn off the eualizer effect for headphones. HEADPHONE_EQUALIZER_OVEREAR = 0x04000001 : For over-ear headphones only. HEADPHONE_EQUALIZER_INEAR = 0x04000002 : For in-ear headphones only.

Returns
  - 0: Success.
  - < 0: Failure.
    - -1(ERR_FAILED): A general error occurs (no specified reason).

## ◆ setHeadphoneEQParameters()

virtual int setHeadphoneEQParameters | ( | int | lowGain,
|  | int | highGain
| ) |  |
| pure virtual

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

Parameters

  lowGain | The higher the parameter value, the deeper the sound. The value range is [-10,10].
  highGain | The higher the parameter value, the sharper the sound. The value range is [-10,10].

Returns
  - 0: Success.
  - < 0: Failure.
    - -1(ERR_FAILED): A general error occurs (no specified reason).

## ◆ enableVoiceAITuner()

virtual int enableVoiceAITuner | ( | bool | enabled,
|  | VOICE_AI_TUNER_TYPE | type
| ) |  |
| pure virtual

Enables or disables the voice AI tuner.

Parameters

  enabled | Determines whether to enable the voice AI tuner: true: Enable the voice AI tuner false: (default) Disable the voice AI tuner.
  type | The options for SDK voice AI tuner types. See VOICE_AI_TUNER_TYPE.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setLogFile()

virtual int setLogFile | ( | const char * | filePath | ) |
| pure virtual

DEPRECATED Specifies an SDK output log file.

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

Note
  Ensure that you call this method immediately after initialize, or the output log may not be complete.

Parameters

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

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setLogFilter()

virtual int setLogFilter | ( | unsigned int | filter | ) |
| pure virtual

Sets the output log filter level of the SDK.

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

Parameters

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

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setLogLevel()

virtual int setLogLevel | ( | commons::LOG_LEVEL | level | ) |
| pure virtual

Sets the output log level of the SDK.

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

Parameters

  level | The log level: `LOG_LEVEL_NONE (0x0000)`: Do not output any log file. `LOG_LEVEL_INFO (0x0001)`: (Recommended) Output log files of the INFO level. `LOG_LEVEL_WARN (0x0002)`: Output log files of the WARN level. `LOG_LEVEL_ERROR (0x0004)`: Output log files of the ERROR level. `LOG_LEVEL_FATAL (0x0008)`: Output log files of the FATAL level.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setLogFileSize()

virtual int setLogFileSize | ( | unsigned int | fileSizeInKBytes | ) |
| pure virtual

Sets the log file size (KB).

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

Parameters

  fileSizeInKBytes | The SDK log file size (KB).

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ uploadLogFile()

virtual int uploadLogFile | ( | agora::util::AString & | requestId | ) |
| pure virtual

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

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ writeLog()

virtual int writeLog | ( | commons::LOG_LEVEL | level,
|  | const char * | fmt,
|  |  | ...
| ) |  |
| pure virtual

- Write the log to SDK . @technical preview

You can Write the log to SDK log files of the specified level.

Parameters

  level | The log level: `LOG_LEVEL_NONE (0x0000)`: Do not output any log file. `LOG_LEVEL_INFO (0x0001)`: (Recommended) Output log files of the INFO level. `LOG_LEVEL_WARN (0x0002)`: Output log files of the WARN level. `LOG_LEVEL_ERROR (0x0004)`: Output log files of the ERROR level. `LOG_LEVEL_FATAL (0x0008)`: Output log files of the FATAL level.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setLocalRenderMode() [1/2]

virtual int setLocalRenderMode | ( | media::base::RENDER_MODE_TYPE | renderMode,
|  | VIDEO_MIRROR_MODE_TYPE | mirrorMode
| ) |  |
| pure virtual

Updates the display mode of the local video view.

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

Note
  - Ensure that you have called setupLocalVideo to initialize the local video view before this method.
  - During a call, you can call this method as many times as necessary to update the local video view.

Parameters

  renderMode | Sets the local display mode. See #RENDER_MODE_TYPE.
  mirrorMode | Sets the local mirror mode. See VIDEO_MIRROR_MODE_TYPE.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setRemoteRenderMode()

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

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

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

Note
  - Ensure that you have called setupRemoteVideo to initialize the remote video view before calling this method.
  - During a call, you can call this method as many times as necessary to update the display mode of the video view of a remote user.

Parameters

  uid | ID of the remote user.
  renderMode | Sets the remote display mode. See #RENDER_MODE_TYPE.
  mirrorMode | Sets the mirror type. See VIDEO_MIRROR_MODE_TYPE.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setLocalRenderTargetFps()

virtual int setLocalRenderTargetFps | ( | VIDEO_SOURCE_TYPE | sourceType,
|  | int | targetFps
| ) |  |
| pure virtual

Sets the target frames per second (FPS) for the local render target.

Parameters

  sourceType | The type of video source.
  targetFps | The target frames per second to be set.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setRemoteRenderTargetFps()

virtual int setRemoteRenderTargetFps | ( | int | targetFps | ) |
| pure virtual

Sets the target frames per second (FPS) for the remote render target.

Parameters

  targetFps | The target frames per second to be set for the remote render target.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setLocalRenderMode() [2/2]

virtual int setLocalRenderMode | ( | media::base::RENDER_MODE_TYPE | renderMode | ) |
| pure virtual

Updates the display mode of the local video view.

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

Note
  - Ensure that you have called setupLocalVideo to initialize the local video view before this method.
  - During a call, you can call this method as many times as necessary to update the local video view.

Parameters

  renderMode | Sets the local display mode. See #RENDER_MODE_TYPE.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setLocalVideoMirrorMode()

virtual int setLocalVideoMirrorMode | ( | VIDEO_MIRROR_MODE_TYPE | mirrorMode | ) |
| pure virtual

Sets the local video mirror mode.

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

Parameters

  mirrorMode | Sets the local video mirror mode. See VIDEO_MIRROR_MODE_TYPE.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableDualStreamMode() [1/2]

virtual int enableDualStreamMode | ( | bool | enabled | ) |
| pure virtual

Enables or disables the dual video stream mode.

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

Parameters

  enabled | true: Enable the dual-stream mode. false: (default) Disable the dual-stream mode.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableDualStreamMode() [2/2]

virtual int enableDualStreamMode | ( | bool | enabled,
|  | const SimulcastStreamConfig & | streamConfig
| ) |  |
| pure virtual

Enables or disables the dual video stream mode.

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

Parameters

  enabled | true: Enable the dual-stream mode. false: (default) Disable the dual-stream mode.
  streamConfig | The minor stream config

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setDualStreamMode() [1/2]

virtual int setDualStreamMode | ( | SIMULCAST_STREAM_MODE | mode | ) |
| pure virtual

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

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

Parameters

  mode | The dual stream mode

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setSimulcastConfig()

virtual int setSimulcastConfig | ( | const SimulcastConfig & | simulcastConfig | ) |
| pure virtual

Sets the multi-layer video stream configuration.

If multi-layer is configured, the subscriber can choose to receive the coresponding layer of video stream using setRemoteVideoStreamType.

Parameters

  simulcastConfig | The configuration for multi-layer video stream. It includes seven layers, ranging from STREAM_LAYER_1 to STREAM_LOW. A maximum of 3 layers can be enabled simultaneously.

Returns
  - 0: Success.
  - < 0: Failure. @technical preview

## ◆ setDualStreamMode() [2/2]

virtual int setDualStreamMode | ( | SIMULCAST_STREAM_MODE | mode,
|  | const SimulcastStreamConfig & | streamConfig
| ) |  |
| pure virtual

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

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

Parameters

  mode | Dual stream mode: SIMULCAST_STREAM_MODE.
  streamConfig | Configurations of the low stream: SimulcastStreamConfig.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableCustomAudioLocalPlayback()

virtual int enableCustomAudioLocalPlayback | ( | track_id_t | trackId,
|  | bool | enabled
| ) |  |
| pure virtual

Sets the external audio track.

Note
  Ensure that you call this method before joining the channel.

Parameters

  trackId | custom audio track id.
  enabled | Determines whether to local playback the external audio track: true: Local playback the external audio track. false: Local don`t playback the external audio track.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setRecordingAudioFrameParameters()

virtual int setRecordingAudioFrameParameters | ( | int | sampleRate,
|  | int | channel,
|  | RAW_AUDIO_FRAME_OP_MODE_TYPE | mode,
|  | int | samplesPerCall
| ) |  |
| pure virtual

Sets the audio recording format for the onRecordAudioFrame callback.

Parameters

  sampleRate | The sample rate (Hz) of the audio data returned in the `onRecordAudioFrame` callback, which can set be as 8000, 16000, 32000, 44100, or 48000.
  channel | The number of audio channels of the audio data returned in the `onRecordAudioFrame` callback, which can be set as 1 or 2: 1: Mono. 2: Stereo.
  mode | This mode is deprecated.
  samplesPerCall | not support. Sampling points in the called data returned in onRecordAudioFrame(). For example, it is usually set as 1024 for stream pushing.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setPlaybackAudioFrameParameters()

virtual int setPlaybackAudioFrameParameters | ( | int | sampleRate,
|  | int | channel,
|  | RAW_AUDIO_FRAME_OP_MODE_TYPE | mode,
|  | int | samplesPerCall
| ) |  |
| pure virtual

Sets the audio playback format for the onPlaybackAudioFrame callback.

Parameters

  sampleRate | Sets the sample rate (Hz) of the audio data returned in the `onPlaybackAudioFrame` callback, which can set be as 8000, 16000, 32000, 44100, or 48000.
  channel | The number of channels of the audio data returned in the `onPlaybackAudioFrame` callback, which can be set as 1 or 2: 1: Mono 2: Stereo
  mode | Deprecated. The use mode of the onPlaybackAudioFrame() callback: agora::rtc::RAW_AUDIO_FRAME_OP_MODE_TYPE.
  samplesPerCall | not support. Sampling points in the called data returned in onPlaybackAudioFrame(). For example, it is usually set as 1024 for stream pushing.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setMixedAudioFrameParameters()

virtual int setMixedAudioFrameParameters | ( | int | sampleRate,
|  | int | channel,
|  | int | samplesPerCall
| ) |  |
| pure virtual

Sets the mixed audio format for the onMixedAudioFrame callback.

Parameters

  sampleRate | The sample rate (Hz) of the audio data returned in the `onMixedAudioFrame` callback, which can set be as 8000, 16000, 32000, 44100, or 48000.
  channel | The number of channels of the audio data in `onMixedAudioFrame` callback, which can be set as 1 or 2: 1: Mono 2: Stereo
  samplesPerCall | not support. Sampling points in the called data returned in `onMixedAudioFrame`. For example, it is usually set as 1024 for stream pushing.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setEarMonitoringAudioFrameParameters()

virtual int setEarMonitoringAudioFrameParameters | ( | int | sampleRate,
|  | int | channel,
|  | RAW_AUDIO_FRAME_OP_MODE_TYPE | mode,
|  | int | samplesPerCall
| ) |  |
| pure virtual

Sets the audio ear monitoring format for the onEarMonitoringAudioFrame callback.

Parameters

  sampleRate | Sets the sample rate (Hz) of the audio data returned in the `onEarMonitoringAudioFrame` callback, which can set be as 8000, 16000, 32000, 44100, or 48000.
  channel | The number of channels of the audio data returned in the `onEarMonitoringAudioFrame` callback, which can be set as 1 or 2: 1: Mono 2: Stereo
  mode | Deprecated. The use mode of the onEarMonitoringAudioFrame() callback: agora::rtc::RAW_AUDIO_FRAME_OP_MODE_TYPE.
  samplesPerCall | not support. Sampling points in the called data returned in onEarMonitoringAudioFrame(). For example, it is usually set as 1024 for stream pushing.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setPlaybackAudioFrameBeforeMixingParameters()

virtual int setPlaybackAudioFrameBeforeMixingParameters | ( | int | sampleRate,
|  | int | channel
| ) |  |
| pure virtual

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

Parameters

  sampleRate | The sample rate (Hz) of the audio data returned in `onPlaybackAudioFrameBeforeMixing`, which can set be as 8000, 16000, 32000, 44100, or 48000.
  channel | Number of channels of the audio data returned in `onPlaybackAudioFrameBeforeMixing`, which can be set as 1 or 2: 1: Mono 2: Stereo

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableAudioSpectrumMonitor()

virtual int enableAudioSpectrumMonitor | ( | int | intervalInMS = `100` | ) |
| pure virtual

Enable the audio spectrum monitor.

Parameters

  intervalInMS | Sets the time interval(ms) between two consecutive audio spectrum callback. The default value is 100. This param should be larger than 10.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ disableAudioSpectrumMonitor()

virtual int disableAudioSpectrumMonitor | ( |  | ) |
| pure virtual

Disalbe the audio spectrum monitor.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ registerAudioSpectrumObserver()

virtual int registerAudioSpectrumObserver | ( | agora::media::IAudioSpectrumObserver * | observer | ) |
| pure virtual

Registers an audio spectrum observer.

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

- onAudioSpectrumComputed: Occurs when the SDK receives the audio data and at set intervals.

Parameters

  observer | A pointer to the audio spectrum observer: IAudioSpectrumObserver.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ unregisterAudioSpectrumObserver()

virtual int unregisterAudioSpectrumObserver | ( | agora::media::IAudioSpectrumObserver * | observer | ) |
| pure virtual

Releases the audio spectrum observer.

Parameters

  observer | The pointer to the audio spectrum observer: IAudioSpectrumObserver.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ adjustRecordingSignalVolume()

virtual int adjustRecordingSignalVolume | ( | int | volume | ) |
| pure virtual

Adjusts the recording volume.

Parameters

  volume | The recording volume, which ranges from 0 to 400:

- 0: Mute the recording volume.
- 100: The Original volume.
- 400: (Maximum) Four times the original volume with signal clipping protection.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ muteRecordingSignal()

virtual int muteRecordingSignal | ( | bool | mute | ) |
| pure virtual

Mute or resume recording signal volume.

Parameters

  mute | Determines whether to mute or resume the recording signal volume. true: Mute the recording signal volume. false: (Default) Resume the recording signal volume.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ adjustPlaybackSignalVolume()

virtual int adjustPlaybackSignalVolume | ( | int | volume | ) |
| pure virtual

Adjusts the playback volume.

Parameters

  volume | The playback volume, which ranges from 0 to 400:

- 0: Mute the recoridng volume.
- 100: The Original volume.
- 400: (Maximum) Four times the original volume with signal clipping protection.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ adjustUserPlaybackSignalVolume()

virtual int adjustUserPlaybackSignalVolume | ( | uid_t | uid,
|  | int | volume
| ) |  |
| pure virtual

## ◆ setLocalPublishFallbackOption()

virtual int 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

  option | Sets the fallback option for the published video stream: STREAM_FALLBACK_OPTION_DISABLED (0): (Default) No fallback behavior for the published video stream when the uplink network condition is poor. The stream quality is not guaranteed. STREAM_FALLBACK_OPTION_AUDIO_ONLY (2): The published video stream falls back to audio only when the uplink network condition is poor.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setRemoteSubscribeFallbackOption()

virtual int 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

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

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setHighPriorityUserList()

virtual int setHighPriorityUserList | ( | uid_t * | uidList,
|  | int | uidNum,
|  | STREAM_FALLBACK_OPTIONS | option
| ) |  |
| pure virtual

Sets the high priority user list and their fallback level in weak network condition.

Note
  - This method can be called before and after joining a channel.
  - If a subscriber is set to high priority, this stream only fallback to lower stream after all normal priority users fallback to their fallback level on weak network condition if needed.

Parameters

  uidList | The high priority user list.
  uidNum | The size of uidList.
  option | The fallback level of high priority users.

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

## ◆ enableExtension() [1/2]

virtual int enableExtension | ( | const char * | provider,
|  | const char * | extension,
|  | const ExtensionInfo & | extensionInfo,
|  | bool | enable = `true`
| ) |  |
| pure virtual

Enable/Disable an extension. By calling this function, you can dynamically enable/disable the extension without changing the pipeline. For example, enabling/disabling Extension_A means the data will be adapted/bypassed by Extension_A.

NOTE: For compatibility reasons, if you haven't call registerExtension, enableExtension will automatically register the specified extension. We suggest you call registerExtension explicitly.

Parameters

  provider | The name of the extension provider, e.g. agora.io.
  extension | The name of the extension, e.g. agora.beauty.
  extensionInfo | The information for extension.
  enable | Whether to enable the extension: true: (Default) Enable the extension. false: Disable the extension.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setExtensionProperty() [1/2]

virtual int setExtensionProperty | ( | const char * | provider,
|  | const char * | extension,
|  | const ExtensionInfo & | extensionInfo,
|  | const char * | key,
|  | const char * | value
| ) |  |
| pure virtual

Sets the properties of an extension.

Parameters

  provider | The name of the extension provider, e.g. agora.io.
  extension | The name of the extension, e.g. agora.beauty.
  extensionInfo | The information for extension.
  key | The key of the extension.
  value | The JSON formatted value of the extension key.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ getExtensionProperty() [1/2]

virtual int getExtensionProperty | ( | const char * | provider,
|  | const char * | extension,
|  | const ExtensionInfo & | extensionInfo,
|  | const char * | key,
|  | char * | value,
|  | int | buf_len
| ) |  |
| pure virtual

Gets the properties of an extension.

Parameters

  provider | The name of the extension provider, e.g. agora.io.
  extension | The name of the extension, e.g. agora.beauty.
  extensionInfo | The information for extension.
  key | The key of the extension.
  value | The value of the extension key.
  buf_len | Maximum length of the JSON string indicating the extension property.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableLoopbackRecording()

virtual int enableLoopbackRecording | ( | bool | enabled,
|  | const char * | deviceName = `NULL`
| ) |  |
| pure virtual

Enables loopback recording.

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

Note
  This method is for Windows only.

Parameters

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

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ adjustLoopbackSignalVolume()

virtual int adjustLoopbackSignalVolume | ( | int | volume | ) |
| pure virtual

Adjusts the loopback recording volume.

Parameters

  volume | The loopback volume, which ranges from 0 to 100:

- 0: Mute the recoridng volume.
- 100: The Original volume. protection.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ getLoopbackRecordingVolume()

virtual int getLoopbackRecordingVolume | ( |  | ) |
| pure virtual

Retrieves the audio volume for recording loopback.

Note
  Call this method when you are in a channel.

Returns
  - ≥ 0: The audio volume for loopback, if this method call succeeds. The value range is [0,100].
  - < 0: Failure.

## ◆ enableInEarMonitoring()

virtual int enableInEarMonitoring | ( | bool | enabled,
|  | int | includeAudioFilters
| ) |  |
| pure virtual

Enables in-ear monitoring.

Parameters

  enabled | Determines whether to enable in-ear monitoring. true: Enable. false: (Default) Disable.
  includeAudioFilters | The type of the ear monitoring: EAR_MONITORING_FILTER_TYPE

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setInEarMonitoringVolume()

virtual int setInEarMonitoringVolume | ( | int | volume | ) |
| pure virtual

Sets the volume of the in-ear monitor.

Parameters

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

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setExtensionProviderProperty()

virtual int setExtensionProviderProperty | ( | const char * | provider,
|  | const char * | key,
|  | const char * | value
| ) |  |
| pure virtual

Sets the provider property of an extension.

Parameters

  provider | The name of the extension provider, e.g. agora.io.
  key | The key of the extension.
  value | The JSON formatted value of the extension key.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ registerExtension()

virtual int registerExtension | ( | const char * | provider,
|  | const char * | extension,
|  | agora::media::MEDIA_SOURCE_TYPE | type = `agora::media::UNKNOWN_MEDIA_SOURCE`
| ) |  |
| pure virtual

Registers an extension. Normally you should call this function immediately after engine initialization. Once an extension is registered, the SDK will automatically create and add it to the pipeline.

Parameters

  provider | The name of the extension provider, e.g. agora.io.
  extension | The name of the extension, e.g. agora.beauty.
  type | The source type of the extension, e.g. PRIMARY_CAMERA_SOURCE. The default is UNKNOWN_MEDIA_SOURCE.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableExtension() [2/2]

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

Enable/Disable an extension. By calling this function, you can dynamically enable/disable the extension without changing the pipeline. For example, enabling/disabling Extension_A means the data will be adapted/bypassed by Extension_A.

NOTE: For compatibility reasons, if you haven't call registerExtension, enableExtension will automatically register the specified extension. We suggest you call registerExtension explicitly.

Parameters

  provider | The name of the extension provider, e.g. agora.io.
  extension | The name of the extension, e.g. agora.beauty.
  enable | Whether to enable the extension: true: (Default) Enable the extension. false: Disable the extension.
  type | The source type of the extension, e.g. PRIMARY_CAMERA_SOURCE. The default is UNKNOWN_MEDIA_SOURCE.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setExtensionProperty() [2/2]

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

Sets the properties of an extension.

Parameters

  provider | The name of the extension provider, e.g. agora.io.
  extension | The name of the extension, e.g. agora.beauty.
  key | The key of the extension.
  value | The JSON formatted value of the extension key.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ getExtensionProperty() [2/2]

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

Gets the properties of an extension.

Parameters

  provider | The name of the extension provider, e.g. agora.io.
  extension | The name of the extension, e.g. agora.beauty.
  key | The key of the extension.
  value | The value of the extension key.
  buf_len | Maximum length of the JSON string indicating the extension property.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ createCustomVideoTrack()

virtual video_track_id_t createCustomVideoTrack | ( |  | ) |
| pure virtual

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

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

## ◆ createCustomEncodedVideoTrack()

virtual video_track_id_t createCustomEncodedVideoTrack | ( | const SenderOptions & | sender_option | ) |
| pure virtual

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

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

## ◆ destroyCustomVideoTrack()

virtual int destroyCustomVideoTrack | ( | video_track_id_t | video_track_id | ) |
| pure virtual

destroy a created custom video track id

Parameters

  video_track_id | The video track id which was created by createCustomVideoTrack

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ destroyCustomEncodedVideoTrack()

virtual int destroyCustomEncodedVideoTrack | ( | video_track_id_t | video_track_id | ) |
| pure virtual

destroy a created custom encoded video track id

Parameters

  video_track_id | The video track id which was created by createCustomEncodedVideoTrack

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ getCallId()

virtual int getCallId | ( | agora::util::AString & | callId | ) |
| pure virtual

Gets the current call ID.

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

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

Parameters

  callId | The reference to the call ID.

Returns
  - The call ID if the method call is successful.
  - < 0: Failure.

## ◆ rate()

virtual int rate | ( | const char * | callId,
|  | int | rating,
|  | const char * | description
| ) |  |
| pure virtual

Allows a user to rate the call.

It is usually called after the call ends.

Parameters

  callId | The call ID retrieved from the getCallId method.
  rating | The rating of the call between 1 (the lowest score) to 5 (the highest score).
  description | (Optional) The description of the rating. The string length must be less than 800 bytes.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ complain()

virtual int complain | ( | const char * | callId,
|  | const char * | description
| ) |  |
| pure virtual

Allows a user to complain about the call quality.

This method is usually called after the call ends.

Parameters

  callId | The call ID retrieved from the `getCallId` method.
  description | (Optional) The description of the complaint. The string length must be less than 800 bytes.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ startRtmpStreamWithoutTranscoding()

virtual int startRtmpStreamWithoutTranscoding | ( | const char * | url | ) |
| pure virtual

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

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

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

Note
  - Ensure that the user joins the channel before calling this method.
  - This method adds only one stream RTMP URL address each time it is called.
  - The RTMP URL address must not contain special characters, such as Chinese language characters.
  - This method applies to Live Broadcast only.

Parameters

  url | The CDN streaming URL in the RTMP format. The maximum length of this parameter is 1024 bytes.

Returns
  - 0: Success.
  - < 0: Failure.
    - ERR_INVALID_ARGUMENT (2): The RTMP URL address is NULL or has a string length of 0.
    - ERR_NOT_INITIALIZED (7): You have not initialized the RTC engine when publishing the stream.
    - ERR_ALREADY_IN_USE (19): This streaming URL is already in use. Use a new streaming URL for CDN streaming.

## ◆ startRtmpStreamWithTranscoding()

virtual int startRtmpStreamWithTranscoding | ( | const char * | url,
|  | const LiveTranscoding & | transcoding
| ) |  |
| pure virtual

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

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

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

Note
  - Ensure that the user joins the channel before calling this method.
  - This method adds only one stream RTMP URL address each time it is called.
  - The RTMP URL address must not contain special characters, such as Chinese language characters.
  - This method applies to Live Broadcast only.

Parameters

  url | The CDN streaming URL in the RTMP format. The maximum length of this parameter is 1024 bytes.
  transcoding | Sets the CDN live audio/video transcoding settings. See LiveTranscoding.

Returns
  - 0: Success.
  - < 0: Failure.
    - ERR_INVALID_ARGUMENT (2): The RTMP URL address is NULL or has a string length of 0.
    - ERR_NOT_INITIALIZED (7): You have not initialized the RTC engine when publishing the stream.
    - ERR_ALREADY_IN_USE (19): This streaming URL is already in use. Use a new streaming URL for CDN streaming.

## ◆ updateRtmpTranscoding()

virtual int updateRtmpTranscoding | ( | const LiveTranscoding & | transcoding | ) |
| pure virtual

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

Note
  This method applies to Live Broadcast only.

Parameters

  transcoding | Sets the CDN live audio/video transcoding settings. See LiveTranscoding.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ startLocalVideoTranscoder()

virtual int startLocalVideoTranscoder | ( | const LocalTranscoderConfiguration & | config | ) |
| pure virtual

## ◆ updateLocalTranscoderConfiguration()

virtual int updateLocalTranscoderConfiguration | ( | const LocalTranscoderConfiguration & | config | ) |
| pure virtual

## ◆ stopRtmpStream()

virtual int stopRtmpStream | ( | const char * | url | ) |
| pure virtual

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

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

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

Note
  - This method removes only one RTMP URL address each time it is called.
  - The RTMP URL address must not contain special characters, such as Chinese language characters.
  - This method applies to Live Broadcast only.

Parameters

  url | The RTMP URL address to be removed. The maximum length of this parameter is 1024 bytes.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ stopLocalVideoTranscoder()

virtual int stopLocalVideoTranscoder | ( |  | ) |
| pure virtual

## ◆ startLocalAudioMixer()

virtual int startLocalAudioMixer | ( | const LocalAudioMixerConfiguration & | config | ) |
| pure virtual

Starts the local audio with a mixed audio stream.

Parameters

  config | Sets the mixed audio stream source settings.

Returns
  - 0: Success.
  - < 0: Failure.
    - ERR_NOT_INITIALIZED (7): You have not initialized the RTC engine when publishing the stream.

## ◆ updateLocalAudioMixerConfiguration()

virtual int updateLocalAudioMixerConfiguration | ( | const LocalAudioMixerConfiguration & | config | ) |
| pure virtual

Update the source stream settings for the mixed audio stream.

Parameters

  config | Update the source audio stream settings. See

Returns
  - 0: Success.
  - < 0: Failure.
    - ERR_NOT_INITIALIZED (7): You have not initialized the RTC engine when publishing the stream.

## ◆ stopLocalAudioMixer()

virtual int stopLocalAudioMixer | ( |  | ) |
| pure virtual

Stops a mixed audio track.

Returns
  - 0: Success.
  - < 0: Failure.
    - ERR_NOT_INITIALIZED (7): You have not initialized the RTC engine when publishing the stream.

## ◆ startCameraCapture()

virtual int startCameraCapture | ( | VIDEO_SOURCE_TYPE | sourceType,
|  | const CameraCapturerConfiguration & | config
| ) |  |
| pure virtual

Starts video capture with a camera.

Parameters

  config | The configuration of the video capture with a primary camera. For details, see CameraCaptureConfiguration.
  sourceType | Source type of camera. See VIDEO_SOURCE_TYPE.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ stopCameraCapture()

virtual int stopCameraCapture | ( | VIDEO_SOURCE_TYPE | sourceType | ) |
| pure virtual

Stops capturing video through camera.

You can call this method to stop capturing video through the first camera after calling `startCameraCapture`.

Parameters

  sourceType | Source type of camera. See VIDEO_SOURCE_TYPE.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setScreenCaptureOrientation()

virtual int setScreenCaptureOrientation | ( | VIDEO_SOURCE_TYPE | type,
|  | VIDEO_ORIENTATION | orientation
| ) |  |
| pure virtual

Sets the rotation angle of the video captured by the screen.

When the screen capture device does not have the gravity sensing function, you can call this method to manually adjust the rotation angle of the captured video.

Parameters

  type | The video source type. See VIDEO_SOURCE_TYPE.
  orientation | The clockwise rotation angle. See VIDEO_ORIENTATION.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ startScreenCapture()

virtual int startScreenCapture | ( | VIDEO_SOURCE_TYPE | sourceType,
|  | const ScreenCaptureConfiguration & | config
| ) |  |
| pure virtual

Starts sharing a screen.

Parameters

  config | The configuration of the captured screen. For details, see ScreenCaptureConfiguration.
  sourceType | source type of screen. See VIDEO_SOURCE_TYPE.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ stopScreenCapture()

virtual int stopScreenCapture | ( | VIDEO_SOURCE_TYPE | sourceType | ) |
| pure virtual

Stop sharing the screen.

After calling `startScreenCapture`, you can call this method to stop sharing the first screen.

Parameters

  sourceType | source type of screen. See VIDEO_SOURCE_TYPE.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ getConnectionState()

virtual CONNECTION_STATE_TYPE getConnectionState | ( |  | ) |
| pure virtual

Gets the current connection state of the SDK.

Returns
  #CONNECTION_STATE_TYPE.

## ◆ registerEventHandler()

virtual bool registerEventHandler | ( | IRtcEngineEventHandler * | eventHandler | ) |
| pure virtual

## ◆ unregisterEventHandler()

virtual bool unregisterEventHandler | ( | IRtcEngineEventHandler * | eventHandler | ) |
| pure virtual

## ◆ setRemoteUserPriority()

virtual int setRemoteUserPriority | ( | uid_t | uid,
|  | PRIORITY_TYPE | userPriority
| ) |  |
| pure virtual

## ◆ registerPacketObserver()

virtual int registerPacketObserver | ( | IPacketObserver * | observer | ) |
| pure virtual

Registers a packet observer.

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

Parameters

  observer | The IPacketObserver object.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableEncryption()

virtual int enableEncryption | ( | bool | enabled,
|  | const EncryptionConfig & | config
| ) |  |
| pure virtual

Enables/Disables the built-in encryption.

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

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

Note
  - If you enable the built-in encryption, you cannot use the RTMP streaming function.

Parameters

  enabled | Whether to enable the built-in encryption: true: Enable the built-in encryption. false: Disable the built-in encryption.
  config | Configurations of built-in encryption schemas. See EncryptionConfig.

Returns
  - 0: Success.
  - < 0: Failure.
    - -2(ERR_INVALID_ARGUMENT): An invalid parameter is used. Set the parameter with a valid value.
    - -4(ERR_NOT_SUPPORTED): The encryption mode is incorrect or the SDK fails to load the external encryption library. Check the enumeration or reload the external encryption library.
    - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. Initialize the `IRtcEngine` instance before calling this method.

## ◆ createDataStream() [1/2]

virtual int createDataStream | ( | int * | streamId,
|  | bool | reliable,
|  | bool | ordered
| ) |  |
| pure virtual

Creates a data stream.

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

Note
  - Ensure that you set the same value for `reliable` and `ordered`.
  - Each user can only create a maximum of 5 data streams during a RtcEngine lifecycle.
  - The data channel allows a data delay of up to 5 seconds. If the receiver does not receive the data stream within 5 seconds, the data channel reports an error.

Parameters

  [out] | streamId | The ID of the stream data.
  | reliable | Sets whether the recipients are guaranteed to receive the data stream from the sender within five seconds: true: The recipients receive the data stream from the sender within five seconds. If the recipient does not receive the data stream within five seconds, an error is reported to the application. false: There is no guarantee that the recipients receive the data stream within five seconds and no error message is reported for any delay or missing data stream.
  | ordered | Sets whether the recipients receive the data stream in the sent order: true: The recipients receive the data stream in the sent order. false: The recipients do not receive the data stream in the sent order.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ createDataStream() [2/2]

virtual int createDataStream | ( | int * | streamId,
|  | const DataStreamConfig & | config
| ) |  |
| pure virtual

Creates a data stream.

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

Parameters

  streamId | The ID of the created data stream.
  config | The config of data stream.

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

## ◆ sendStreamMessage()

virtual int sendStreamMessage | ( | int | streamId,
|  | const char * | data,
|  | size_t | length
| ) |  |
| pure virtual

Sends a data stream.

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

The SDK has the following restrictions on this method:

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

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

Note
  - Call this method after calling createDataStream.
  - This method applies only to the `COMMUNICATION` profile or to the hosts in the `LIVE_BROADCASTING` profile. If an audience in the `LIVE_BROADCASTING` profile calls this method, the audience may be switched to a host.

Parameters

  streamId | The ID of the stream data.
  data | The data stream.
  length | The length (byte) of the data stream.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ addVideoWatermark() [1/2]

virtual int addVideoWatermark | ( | const RtcImage & | watermark | ) |
| pure virtual

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

This method is not recommend, Use addVideoWatermark2 instead.

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

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

Parameters

  watermark | Pointer to the watermark image to be added to the local video stream. See RtcImage.

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

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ addVideoWatermark() [2/2]

virtual int addVideoWatermark | ( | const char * | watermarkUrl,
|  | const WatermarkOptions & | options
| ) |  |
| pure virtual

Adds a watermark image to the local video.

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

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

- If the orientation mode of the encoding video is ORIENTATION_MODE_FIXED_LANDSCAPE, or the landscape mode in ORIENTATION_MODE_ADAPTIVE, the watermark uses the landscape orientation.
- If the orientation mode of the encoding video is ORIENTATION_MODE_FIXED_PORTRAIT, or the portrait mode in ORIENTATION_MODE_ADAPTIVE, the watermark uses the portrait orientation.
- When setting the watermark position, the region must be less than the dimensions set in the `setVideoEncoderConfiguration` method. Otherwise, the watermark image will be cropped.

Note
  - Ensure that you have called the enableVideo method to enable the video module before calling this method.
  - If you only want to add a watermark image to the local video for the audience in the CDN live broadcast channel to see and capture, you can call this method or the setLiveTranscoding method.
  - This method supports adding a watermark image in the PNG file format only. Supported pixel formats of the PNG image are RGBA, RGB, Palette, Gray, and Alpha_gray.
  - If the dimensions of the PNG image differ from your settings in this method, the image will be cropped or zoomed to conform to your settings.
  - If you have enabled the local video preview by calling the startPreview method, you can use the `visibleInPreview` member in the WatermarkOptions class to set whether or not the watermark is visible in preview.
  - If you have enabled the mirror mode for the local video, the watermark on the local video is also mirrored. To avoid mirroring the watermark, Agora recommends that you do not use the mirror and watermark functions for the local video at the same time. You can implement the watermark function in your application layer.

Parameters

  watermarkUrl | The 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.
  options | Pointer to the watermark's options to be added. See WatermarkOptions for more infomation.

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

## ◆ enableWebSdkInteroperability()

virtual int enableWebSdkInteroperability | ( | bool | enabled | ) |
| pure virtual

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

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

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

Parameters

  enabled | Determines whether to enable interoperability with the Agora Web SDK. true: (Default) Enable interoperability with the Agora Native SDK. false: Disable interoperability with the Agora Native SDK.

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

## ◆ sendCustomReportMessage()

virtual int sendCustomReportMessage | ( | const char * | id,
|  | const char * | category,
|  | const char * | event,
|  | const char * | label,
|  | int | value
| ) |  |
| pure virtual

Agora supports reporting and analyzing customized messages.

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

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

## ◆ registerMediaMetadataObserver()

virtual int registerMediaMetadataObserver | ( | IMetadataObserver * | observer,
|  | IMetadataObserver::METADATA_TYPE | type
| ) |  |
| pure virtual

Registers the metadata observer.

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

A successful call of this method triggers the getMaxMetadataSize callback.

Note
  - Call this method before the `joinChannel` method.
  - This method applies to the `LIVE_BROADCASTING` channel profile.

Parameters

  observer | IMetadataObserver.
  type | The metadata type. See METADATA_TYPE. The SDK supports VIDEO_METADATA (0) only for now.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ unregisterMediaMetadataObserver()

virtual int unregisterMediaMetadataObserver | ( | IMetadataObserver * | observer,
|  | IMetadataObserver::METADATA_TYPE | type
| ) |  |
| pure virtual

Unregisters the metadata observer.

Parameters

  observer | IMetadataObserver.
  type | The metadata type. See METADATA_TYPE. The SDK supports VIDEO_METADATA (0) only for now.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ startAudioFrameDump()

virtual int startAudioFrameDump | ( | const char * | channel_id,
|  | uid_t | uid,
|  | const char * | location,
|  | const char * | uuid,
|  | const char * | passwd,
|  | long | duration_ms,
|  | bool | auto_upload
| ) |  |
| pure virtual

Start audio frame dump.

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

## ◆ stopAudioFrameDump()

virtual int stopAudioFrameDump | ( | const char * | channel_id,
|  | uid_t | uid,
|  | const char * | location
| ) |  |
| pure virtual

Stops the audio frame dump.

## ◆ setAINSMode()

virtual int setAINSMode | ( | bool | enabled,
|  | AUDIO_AINS_MODE | mode
| ) |  |
| pure virtual

Enables/Disables Agora AI Noise Suppression(AINS) with preset mode.

Parameters

  enabled | Sets whether or not to enable AINS. true: Enables the AINS. false: Disables the AINS.
  mode | The preset AINS mode, range is [0,1,2]: 0: AINS mode with soft suppression level. 1: AINS mode with aggressive suppression level. 2: AINS mode with aggressive suppression level and low algorithm latency.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ registerLocalUserAccount()

virtual int 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:

- Call the registerLocalUserAccount method to create a user account, and then the joinChannelWithUserAccount method to join the channel.
- Call the joinChannelWithUserAccount method to join the channel.

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

  appId | The App ID of your project.
  userAccount | The user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are: All lowercase English letters: a to z. All uppercase English letters: A to Z. All numeric characters: 0 to 9. The space character. Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ joinChannelWithUserAccount() [1/2]

virtual int 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:

- The local client: onLocalUserRegistered and onJoinChannelSuccess .
- The remote client: onUserJoined and onUserInfoUpdated , if the user joining the channel is in the `COMMUNICATION` profile, or is a host in the `LIVE_BROADCASTING` profile.

Note
  To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the uid of the user is set to the same parameter type.

Parameters

  token | The token generated at your server: For low-security requirements: You can use the temporary token generated at Console. For details, see Get a temporary toke. For high-security requirements: Set it as the token generated at your server. For details, see Get a token.
  channelId | The 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
  userAccount | The user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are: All lowercase English letters: a to z. All uppercase English letters: A to Z. All numeric characters: 0 to 9. The space character. Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ joinChannelWithUserAccount() [2/2]

virtual int joinChannelWithUserAccount | ( | const char * | token,
|  | const char * | channelId,
|  | const char * | userAccount,
|  | const ChannelMediaOptions & | options
| ) |  |
| pure virtual

Joins the channel with a user account.

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

- The local client: onLocalUserRegistered and onJoinChannelSuccess .
- The remote client: onUserJoined and onUserInfoUpdated , if the user joining the channel is in the `COMMUNICATION` profile, or is a host in the `LIVE_BROADCASTING` profile.

Note
  To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the uid of the user is set to the same parameter type.

Parameters

  token | The token generated at your server: For low-security requirements: You can use the temporary token generated at Console. For details, see Get a temporary toke. For high-security requirements: Set it as the token generated at your server. For details, see Get a token.
  channelId | The 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
  userAccount | The user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are: All lowercase English letters: a to z. All uppercase English letters: A to Z. All numeric characters: 0 to 9. The space character. Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
  options | The channel media options: ChannelMediaOptions

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ joinChannelWithUserAccountEx()

virtual int joinChannelWithUserAccountEx | ( | const char * | token,
|  | const char * | channelId,
|  | const char * | userAccount,
|  | const ChannelMediaOptions & | options,
|  | IRtcEngineEventHandler * | eventHandler
| ) |  |
| pure virtual

Joins the channel with a user account.

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

- The local client: onLocalUserRegistered and onJoinChannelSuccess .
- The remote client: onUserJoined and onUserInfoUpdated , if the user joining the channel is in the `COMMUNICATION` profile, or is a host in the `LIVE_BROADCASTING` profile.

Note
  To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the uid of the user is set to the same parameter type.

Parameters

  token | The token generated at your server: For low-security requirements: You can use the temporary token generated at Console. For details, see Get a temporary toke. For high-security requirements: Set it as the token generated at your server. For details, see Get a token.
  channelId | The 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
  userAccount | The user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are: All lowercase English letters: a to z. All uppercase English letters: A to Z. All numeric characters: 0 to 9. The space character. Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
  options | The channel media options: ChannelMediaOptions
  eventHandler | The pointer to the IRtcEngine event handler: IRtcEngineEventHandler.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ getUserInfoByUserAccount()

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

Gets the user information by passing in the user account.

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

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

Parameters

  | userAccount | The user account of the user. Ensure that you set this parameter.
  [in,out] | userInfo | A 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 getUserInfoByUid | ( | uid_t | uid,
|  | rtc::UserInfo * | userInfo
| ) |  |
| pure virtual

Gets the user information by passing in the user ID.

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

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

Parameters

  | uid | The user ID of the remote user. Ensure that you set this parameter.
  [in,out] | userInfo | A 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.

## ◆ startOrUpdateChannelMediaRelay()

virtual int startOrUpdateChannelMediaRelay | ( | const ChannelMediaRelayConfiguration & | configuration | ) |
| pure virtual

Starts relaying media streams across channels or updates the channels for media relay.

After a successful method call, the SDK triggers the onChannelMediaRelayStateChanged callback, and this callback return the state of the media stream relay.

- If the onChannelMediaRelayStateChanged callback returns RELAY_STATE_RUNNING (2) and RELAY_OK (0), the host starts sending data to the destination channel.
- If the onChannelMediaRelayStateChanged callback returns RELAY_STATE_FAILURE (3), an exception occurs during 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.
  - 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.

Since
  v4.2.0

Parameters

  configuration | The configuration of the media stream relay: ChannelMediaRelayConfiguration.

Returns
  - 0: Success.
  - < 0: Failure.
    - -1(ERR_FAILED): A general error occurs (no specified reason).
    - -2(ERR_INVALID_ARGUMENT): The argument is invalid.
    - -5(ERR_REFUSED): The request is rejected.
    - -8(ERR_INVALID_STATE): The current status is invalid, only allowed to be called when the role is the broadcaster.

## ◆ stopChannelMediaRelay()

virtual int stopChannelMediaRelay | ( |  | ) |
| pure virtual

Stops the media stream relay.

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

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

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

Returns
  - 0: Success.
  - < 0: Failure.
    - -1(ERR_FAILED): A general error occurs (no specified reason).
    - -2(ERR_INVALID_ARGUMENT): The argument is invalid.
    - -5(ERR_REFUSED): The request is rejected.
    - -7(ERR_NOT_INITIALIZED): cross channel media streams are not relayed.

## ◆ pauseAllChannelMediaRelay()

virtual int pauseAllChannelMediaRelay | ( |  | ) |
| pure virtual

pause the channels for media stream relay.

Returns
  - 0: Success.
  - < 0: Failure.
    - -1(ERR_FAILED): A general error occurs (no specified reason).
    - -2(ERR_INVALID_ARGUMENT): The argument is invalid.
    - -5(ERR_REFUSED): The request is rejected.
    - -7(ERR_NOT_INITIALIZED): cross channel media streams are not relayed.

## ◆ resumeAllChannelMediaRelay()

virtual int resumeAllChannelMediaRelay | ( |  | ) |
| pure virtual

resume the channels for media stream relay.

Returns
  - 0: Success.
  - < 0: Failure.
    - -1(ERR_FAILED): A general error occurs (no specified reason).
    - -2(ERR_INVALID_ARGUMENT): The argument is invalid.
    - -5(ERR_REFUSED): The request is rejected.
    - -7(ERR_NOT_INITIALIZED): cross channel media streams are not relayed.

## ◆ setDirectCdnStreamingAudioConfiguration()

virtual int setDirectCdnStreamingAudioConfiguration | ( | AUDIO_PROFILE_TYPE | profile | ) |
| pure virtual

Set audio parameters for direct streaming to CDN

Note
  Must call this api before "startDirectCdnStreaming"

Parameters

  profile | Sets the sample rate, bitrate, encoding mode, and the number of channels: AUDIO_PROFILE_TYPE.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setDirectCdnStreamingVideoConfiguration()

virtual int setDirectCdnStreamingVideoConfiguration | ( | const VideoEncoderConfiguration & | config | ) |
| pure virtual

Set video parameters for direct streaming to CDN

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

Note
  Must call this api before "startDirectCdnStreaming"

Parameters

  config | The local video encoder configuration: VideoEncoderConfiguration.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ startDirectCdnStreaming()

virtual int startDirectCdnStreaming | ( | IDirectCdnStreamingEventHandler * | eventHandler,
|  | const char * | publishUrl,
|  | const DirectCdnStreamingMediaOptions & | options
| ) |  |
| pure virtual

Start direct cdn streaming

Parameters

  eventHandler | A pointer to the direct cdn streaming event handler: IDirectCdnStreamingEventHandler.
  publishUrl | The url of the cdn used to publish the stream.
  options | The direct cdn streaming media options: DirectCdnStreamingMediaOptions. This API must pass an audio-related option, and temporarily cannot pass more than one. For video-related options, you can either choose to not pass any, or only one.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ stopDirectCdnStreaming()

virtual int stopDirectCdnStreaming | ( |  | ) |
| pure virtual

Stop direct cdn streaming

Note
  This method is synchronous.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ updateDirectCdnStreamingMediaOptions()

virtual int updateDirectCdnStreamingMediaOptions | ( | const DirectCdnStreamingMediaOptions & | options | ) |
| pure virtual

Change the media source during the pushing

Note
  This method is temporarily not supported.

Parameters

  options | The direct cdn streaming media options: DirectCdnStreamingMediaOptions.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ startRhythmPlayer()

virtual int startRhythmPlayer | ( | const char * | sound1,
|  | const char * | sound2,
|  | const AgoraRhythmPlayerConfig & | config
| ) |  |
| pure virtual

Enables the rhythm player.

Parameters

  sound1 | The absolute path or URL address (including the filename extensions) of the file for the downbeat.
  sound2 | The absolute path or URL address (including the filename extensions) of the file for the upbeats.
  config | The configuration of rhythm player.

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

## ◆ stopRhythmPlayer()

virtual int stopRhythmPlayer | ( |  | ) |
| pure virtual

Disables the rhythm player.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ configRhythmPlayer()

virtual int configRhythmPlayer | ( | const AgoraRhythmPlayerConfig & | config | ) |
| pure virtual

Configures the rhythm player.

Parameters

  config | The configuration of rhythm player.

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

## ◆ takeSnapshot() [1/2]

virtual int takeSnapshot | ( | uid_t | uid,
|  | const char * | filePath
| ) |  |
| pure virtual

Takes a snapshot of a video stream.

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 for that snapshot.

Note
  - Call this method after joining a channel.
  - This method takes a snapshot of the published video stream specified in `ChannelMediaOptions`.
  - If the user's video has been preprocessed, for example, watermarked or beautified, the resulting snapshot includes the pre-processing effect.

Parameters

  uid | The user ID. Set uid as 0 if you want to take a snapshot of the local user's video.
  filePath | The local path (including filename extensions) of the snapshot. For example: Windows: `C:\Users\<user_name>\AppData\Local\Agora\<process_name>\example.jpg` iOS: `/App Sandbox/Library/Caches/example.jpg` macOS: `～/Library/Logs/example.jpg` Android: `/storage/emulated/0/Android/data/<package name>/files/example.jpg`

Ensure that the path you specify exists and is writable.

Returns
  - 0 : Success.
  - < 0 : Failure.

## ◆ takeSnapshot() [2/2]

virtual int takeSnapshot | ( | uid_t | uid,
|  | const media::SnapshotConfig & | config
| ) |  |
| pure virtual

Takes a snapshot of a video stream.

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 for that snapshot.

Note
  - Call this method after joining a channel.
  - This method takes a snapshot of the published video stream specified in `ChannelMediaOptions`.

Parameters

  uid | The user ID. Set uid as 0 if you want to take a snapshot of the local user's video.
  config | The configuration for the take snapshot. See SnapshotConfig.

Ensure that the path you specify exists and is writable.

Returns
  - 0 : Success.
  - < 0: Failure.
    - -4: Incorrect observation position. Modify the input observation position according to the reqiurements specified in SnapshotConfig.

## ◆ enableContentInspect()

virtual int enableContentInspect | ( | bool | enabled,
|  | const media::ContentInspectConfig & | config
| ) |  |
| pure virtual

Enables the content inspect.

Parameters

  enabled | Whether to enable content inspect: `true`: Yes. `false`: No.
  config | The configuration for the content inspection.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ adjustCustomAudioPublishVolume()

virtual int adjustCustomAudioPublishVolume | ( | track_id_t | trackId,
|  | int | volume
| ) |  |
| pure virtual

## ◆ adjustCustomAudioPlayoutVolume()

virtual int adjustCustomAudioPlayoutVolume | ( | track_id_t | trackId,
|  | int | volume
| ) |  |
| pure virtual

## ◆ setCloudProxy()

virtual int setCloudProxy | ( | CLOUD_PROXY_TYPE | proxyType | ) |
| pure virtual

Sets the Agora cloud proxy service.

Since
  v3.3.0

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

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

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

Note
  - Agora recommends that you call this method before joining the channel or after leaving the channel.
  - For the SDK v3.3.x, the services for pushing streams to CDN and co-hosting across channels are not available when you use the cloud proxy for the UDP protocol. For the SDK v3.4.0 and later, the services for pushing streams to CDN and co-hosting across channels are not available when the user is in a network environment with a firewall and uses the cloud proxy for the UDP protocol.

Parameters

  proxyType | The cloud proxy type, see CLOUD_PROXY_TYPE. This parameter is required, and the SDK reports an error if you do not pass in a value.

Returns
  - 0: Success.
  - < 0: Failure.
    - `-2(ERR_INVALID_ARGUMENT)`: The parameter is invalid.
    - `-7(ERR_NOT_INITIALIZED)`: The SDK is not initialized.

## ◆ setLocalAccessPoint()

virtual int setLocalAccessPoint | ( | const LocalAccessPointConfiguration & | config | ) |
| pure virtual

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

Parameters

  config | The LocalAccessPointConfiguration class, See the definition of LocalAccessPointConfiguration for details.

Returns
  - 0: Success
  - < 0: Failure

## ◆ setAdvancedAudioOptions()

virtual int setAdvancedAudioOptions | ( | AdvancedAudioOptions & | options,
|  | int | sourceType = `0`
| ) |  |
| pure virtual

set advanced audio options.

Parameters

  options | The AdvancedAudioOptions class, See the definition of AdvancedAudioOptions for details.

Returns
  - 0: Success
  - < 0: Failure

## ◆ setAVSyncSource()

virtual int setAVSyncSource | ( | const char * | channelId,
|  | uid_t | uid
| ) |  |
| pure virtual

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

Parameters

  channelId | The channel id
  uid | The user ID of the remote user to be bound with (local user)

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableVideoImageSource()

virtual int enableVideoImageSource | ( | bool | enable,
|  | const ImageTrackOptions & | options
| ) |  |
| pure virtual

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

Parameters

  enable | true for enable, false for disable
  options | options for image track

## ◆ getCurrentMonotonicTimeInMs()

virtual int64_t getCurrentMonotonicTimeInMs | ( |  | ) |
| pure virtual

## ◆ enableWirelessAccelerate()

virtual int enableWirelessAccelerate | ( | bool | enabled | ) |
| pure virtual

Turns WIFI acceleration on or off.

Note
  - This method is called before and after joining a channel.
  - Users check the WIFI router app for information about acceleration. Therefore, if this interface is invoked, the caller accepts that the caller's name will be displayed to the user in the WIFI router application on behalf of the caller.

Parameters

  enabled | true：Turn WIFI acceleration on. false：Turn WIFI acceleration off.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ getNetworkType()

virtual int getNetworkType | ( |  | ) |
| pure virtual

get network type value

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

## ◆ setParameters()

virtual int setParameters | ( | const char * | parameters | ) |
| pure virtual

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

Parameters

  parameters | Pointer to the set parameters in a JSON string.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ startMediaRenderingTracing()

virtual int startMediaRenderingTracing | ( |  | ) |
| pure virtual

Start tracing media rendering events.

Since
  v4.1.1 @discussion
  - SDK will trace media rendering events when this API is called.
  - The tracing result can be obtained through callback `IRtcEngineEventHandler::onVideoRenderingTracingResult`

Note
  - By default, SDK will trace media rendering events when `IRtcEngine::joinChannel` is called.
  - The start point of event tracing will be reset after leaving channel.

Returns
  - 0: Success.
  - < 0: Failure.
    - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. Initialize the `IRtcEngine` instance before calling this method.

## ◆ enableInstantMediaRendering()

virtual int enableInstantMediaRendering | ( |  | ) |
| pure virtual

Enable instant media rendering.

Since
  v4.1.1 @discussion
  - This method enable SDK to render video or playout audio faster.

Note
  - Once enable this mode, we should destroy rtc engine to disable it.
  - Enable this mode, will sacrifice some part of experience.

Returns
  - 0: Success.
  - < 0: Failure.
    - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. Initialize the `IRtcEngine` instance before calling this method.

## ◆ getNtpWallTimeInMs()

virtual uint64_t getNtpWallTimeInMs | ( |  | ) |
| pure virtual

Return current NTP(unix timestamp) time in milliseconds.

## ◆ isFeatureAvailableOnDevice()

virtual bool isFeatureAvailableOnDevice | ( | FeatureType | type | ) |
| pure virtual

Whether the target feature is available for the device.

Since
  v4.3.0

Parameters

  type | The feature type. See FeatureType.

Returns
  - true: available.
  - false: not available.

## ◆ sendAudioMetadata()

virtual int sendAudioMetadata | ( | const char * | metadata,
|  | size_t | length
| ) |  |
| pure virtual

send audio metadata

Since
  v4.3.1

Parameters

  metadata | The pointer of metadata
  length | Size of metadata

Returns
  - 0: success
  - <0: failure @technical preview

## ◆ queryHDRCapability()

virtual int queryHDRCapability | ( | VIDEO_MODULE_TYPE | videoModule,
|  | HDR_CAPABILITY & | capability
| ) |  |
| pure virtual

Queries the HDR capability of the video module.

Parameters

  videoModule | The video module. See VIDEO_MODULE_TYPE
  capability | HDR capability of video module. See HDR_CAPABILITY

Returns
  - 0: success
  - <0: failure @technical preview