From e4b8b2f59d4c11efbd7226a4a4cec82aaea6d9b5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=99=88=E8=90=8C?= Date: Tue, 15 Mar 2022 16:23:18 +0800 Subject: [PATCH] add five core API md files for review --- en-US/markdown/Video/API/IRtcEngine.md | 5518 +++++++++++++++ .../Video/API/IRtcEngineEventHandler.md | 2212 ++++++ en-US/markdown/Video/API/IRtcEngineEx.md | 561 ++ en-US/markdown/Video/API/api_overview.md | 602 ++ en-US/markdown/Video/API/structs_enums.md | 6266 +++++++++++++++++ 5 files changed, 15159 insertions(+) create mode 100644 en-US/markdown/Video/API/IRtcEngine.md create mode 100644 en-US/markdown/Video/API/IRtcEngineEventHandler.md create mode 100644 en-US/markdown/Video/API/IRtcEngineEx.md create mode 100644 en-US/markdown/Video/API/api_overview.md create mode 100644 en-US/markdown/Video/API/structs_enums.md diff --git a/en-US/markdown/Video/API/IRtcEngine.md b/en-US/markdown/Video/API/IRtcEngine.md new file mode 100644 index 00000000000..d91e3146a89 --- /dev/null +++ b/en-US/markdown/Video/API/IRtcEngine.md @@ -0,0 +1,5518 @@ +# [IRtcEngine](class_irtcengine.html#class_irtcengine) + +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. + +Before calling other APIs, you must call [createAgoraRtcEngine](class_irtcengine.html#api_createagorartcengine) to create an IRtcEngine object. + +## [addPublishStreamUrl](class_irtcengine.html#api_addpublishstreamurl) + +Publishes the local stream to a specified CDN live streaming URL. + +```cpp +virtual int addPublishStreamUrl(const char* url, bool transcodingEnabled) = 0; +``` + +After calling this method, you can push media streams in RTMP or RTMPS protocol to the CDN. The SDK triggers the [onRtmpStreamingStateChanged](class_irtcengineeventhandler.html#callback_onrtmpstreamingstatechanged) callback on the local client to report the state of adding a local stream to the CDN. + +**Note** + +- Call this method after joining a channel. +- Ensure that the media push function is enabled. +- This method takes effect only when you are a host in live interactive streaming. +- This method adds only one streaming URL to the CDN each time it is called. To push multiple URLs, call this method multiple times. +- Agora only supports pushing media streams to the CDN in RTMPS protocol when you enable transcoding. + +### Parameters + +- url + + The CDN streaming URL in the RTMP or RTMPS format. The maximum length of this parameter is 1024 bytes. The URL address must not contain special characters, such as Chinese language characters. + +- transcodingEnabled + + Whether to enable transcoding. [Transcoding](https://docs.agora.io/en/Agora Platform/transcoding) in a CDN live streaming converts the audio and video streams before pushing them to the CDN server. It applies to scenarios where a channel has multiple broadcasters and composite layout is needed.`true`: Enable transcoding.`false`: Disable transcoding.**Note** If you set this parameter as `true`, ensure that you call the [setLiveTranscoding](class_irtcengine.html#api_setlivetranscoding) method before calling this method. + +### Returns + +- 0: Success. +- < 0: Failure. + - `ERR_INVALID_ARGUMENT` (-2): Invalid argument, usually because the URL address is null or the string length is 0. + - `ERR_NOT_INITIALIZED` (-7): You have not initialized the RTC Engine when publishing the stream. + +**See also** + +- [onRtmpStreamingStateChanged](../API/class_irtcengineeventhandler.html#callback_onrtmpstreamingstatechanged) + +## [addVideoWatermark [1/2\]](class_irtcengine.html#api_addvideowatermark) + +Adds a watermark image to the local video. + +```cpp +virtual int addVideoWatermark(const RtcImage& watermark) = 0; +``` + +- Deprecated: + + This method is deprecated. Use [addVideoWatermark [2/2\]](class_irtcengine.html#api_addvideowatermark2) instead. + +This method adds a PNG watermark image to the local video stream in a live streaming session. Once the watermark image is added, all the users in the channel (CDN audience included) and the video capturing device can see and capture it. If you only want to add a watermark to the CDN live streaming, see descriptions in [setLiveTranscoding](class_irtcengine.html#api_setlivetranscoding). + +**Note** + +- The URL descriptions are different for the local video and CDN live streaming: In a local video stream, URL refers to the absolute path of the added watermark image file in the local video stream. In a CDN live stream, URL refers to the URL address of the added watermark image in the CDN live streaming. +- The source file of the watermark image must be in the PNG file format. If the width and height of the PNG file differ from your settings in this method, the PNG file will be cropped to conform to your settings. +- The Agora SDK supports adding only one watermark image onto a local video or CDN live stream. The newly added watermark image replaces the previous one. + +### Parameters + +- watermark + + The watermark image to be added to the local live streaming: [RtcImage](rtc_api_data_type.html#class_rtcimage). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [addVideoWatermark [2/2\]](class_irtcengine.html#api_addvideowatermark2) + +Adds a watermark image to the local video. + +```cpp +virtual int addVideoWatermark(const char* watermarkUrl, const WatermarkOptions& options) = 0; +``` + +This method adds a PNG watermark image to the local video in the live streaming. Once the watermark image is added, all the audience in the channel (CDN audience included), and the capturing device can see and capture it. Agora supports adding only one watermark image onto the local video, and the newly watermark image replaces the previous one. + +The watermark coordinates are dependent on the settings in the [setVideoEncoderConfiguration](class_irtcengine.html#api_setvideoencoderconfiguration) method: + +- If the orientation mode of the encoding video ([ORIENTATION_MODE](rtc_api_data_type.html#enum_orientationmode)) is FIXED_LANDSCAPE, or the landscape mode in ADAPTIVE, the watermark uses the landscape orientation. +- If the orientation mode of the encoding video (ORIENTATION_MODE) is FIXED_PORTRAIT, or the portrait mode in 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 [enableVideo](class_irtcengine.html#api_enablevideo) before calling this method. +- If you only want to add a watermark to the CDN live streaming, you can call this method or the [setLiveTranscoding](class_irtcengine.html#api_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](class_irtcengine.html#api_startpreview) method, you can use the `visibleInPreview` member to set whether or not the watermark is visible in the 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 + + The options of the watermark image to be added. For details, see [WatermarkOptions](rtc_api_data_type.html#class_watermarkoptions). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [adjustAudioMixingPlayoutVolume](class_irtcengine.html#api_adjustaudiomixingplayoutvolume) + +Adjusts the volume of audio mixing for local playback. + +```cpp +virtual int adjustAudioMixingPlayoutVolume(int volume) = 0; +``` + +- Since + + v2.3.2 + +**Note** You need to call this method after calling [startAudioMixing [2/2\]](class_irtcengine.html#api_startaudiomixing2) and receiving the onAudioMixingStateChanged(`PLAY`) callback. + +### Parameters + +- volume + + Audio mixing volume for local playback. The value range is [0,100]. The default value is 100, the original volume. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [adjustAudioMixingPublishVolume](class_irtcengine.html#api_adjustaudiomixingpublishvolume) + +Adjusts the volume of audio mixing for publishing. + +```cpp +virtual int adjustAudioMixingPublishVolume(int volume) = 0; +``` + +- Since + + v2.3.2 + +This method adjusts the volume of audio mixing for publishing (sending to other users). + +**Note** You need to call this method after calling [startAudioMixing [2/2\]](class_irtcengine.html#api_startaudiomixing2) and receiving the onAudioMixingStateChanged(`PLAY`) callback. + +### Parameters + +- volume + + Audio mixing volume. The value range is [0,100]. The default value is 100, the original volume. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [adjustAudioMixingVolume](class_irtcengine.html#api_adjustaudiomixingvolume) + +Adjusts the volume during audio mixing. + +```cpp +virtual int adjustAudioMixingVolume(int volume) = 0; +``` + +This method adjusts the audio mixing volume on both the local client and remote clients. + +**Note** + +- Call this method after [startAudioMixing [2/2\]](class_irtcengine.html#api_startaudiomixing2). +- Calling this method does not affect the volume of audio effect file playback invoked by the [playEffect](class_irtcengine.html#api_playeffect3) method. + +### Parameters + +- volume + + Audio mixing volume. The value ranges between 0 and 100. The default value is 100, the original volume. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [adjustLoopbackRecordingVolume](class_irtcengine.html#api_adjustloopbackrecordingvolume) + +Adjusts the volume of the signal captured by the sound card. + +```cpp +virtual int adjustLoopbackRecordingVolume(int volume) = 0; +``` + +After calling [enableLoopbackRecording](class_irtcengine.html#api_enableloopbackrecording_ng) to enable loopback audio capturing, you can call this method to adjust the volume of the signal captured by the sound card. + +### Parameters + +- volume + + Audio mixing volume. The value ranges between 0 and 100. The default value is 100, the original volume. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [adjustPlaybackSignalVolume](class_irtcengine.html#api_adjustplaybacksignalvolume) + +Adjusts the playback signal volume of all remote users. + +```cpp +virtual int adjustPlaybackSignalVolume(int volume) = 0; +``` + +**Note** + +- This method adjusts the playback volume that is the mixed volume of all remote users. +- You can call this method either before or after joining a channel. + +### Parameters + +- volume + + Integer only. The value range is [0,400].0: Mute.100: (Default) The original volume.400: Four times the original volume (amplifying the audio signals by four times). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [adjustRecordingSignalVolume](class_irtcengine.html#api_adjustrecordingsignalvolume) + +Adjusts the capturing signal volume. + +```cpp +virtual int adjustRecordingSignalVolume(int volume) = 0; +``` + +**Note** + +You can call this method either before or after joining a channel. + +### Parameters + +- volume + + Integer only. The value range is [0,400].0: Mute.100: (Default) The original volume.400: Four times the original volume (amplifying the audio signals by four times). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [adjustUserPlaybackSignalVolume](class_irtcengine.html#api_adjustuserplaybacksignalvolume) + +Adjusts the playback signal volume of a specified remote user. + +```cpp +virtual int adjustUserPlaybackSignalVolume(unsigned int uid, int volume) = 0; +``` + +You can call this method to adjust the playback volume of a specified remote user. To adjust the playback volume of different remote users, call the method as many times, once for each remote user. + +**Note** + +- Call this method after joining a channel. +- The playback volume here refers to the mixed volume of a specified remote user. + +### Parameters + +- uid + + The ID of the remote user. + +- volume + + Audio mixing volume. The value ranges between 0 and 100. The default value is 100, the original volume. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [clearVideoWatermarks](class_irtcengine.html#api_clearvideowatermarks) + +Removes the watermark image from the video stream. + +```cpp +virtual int clearVideoWatermarks() = 0; +``` + +### Returns + +- 0: Success. +- < 0: Failure. + +## [complain](class_irtcengine.html#api_complain) + +Allows a user to complain about the call quality after a call ends. + +```cpp +virtual int complain(const char* callId, const char* description) = 0; +``` + +This method allows users to complain about the quality of the call. Call this method after the user leaves the channel. + +### Parameters + +- callId + + The current call ID. You can get the call ID by calling [getCallId](class_irtcengine.html#api_getcallid). + +- description + + (Optional) A description of the call. The string length should be less than 800 bytes. + +### Returns + +- 0: Success. +- < 0: Failure. + - -2 (`ERR_INVALID_ARGUMENT`). + - -3 (`ERR_NOT_READY`)。 + +## [configRhythmPlayer](class_irtcengine.html#api_configrhythmplayer) + +Configures the virtual metronome. + +```cpp +virtual int configRhythmPlayer(const AgoraRhythmPlayerConfig& config) = 0; +``` + +After calling [startRhythmPlayer](class_irtcengine.html#api_startrhythmplayer), you can call this method to reconfigure the virtual metronome. + +**Note** + +- This method is for Android and iOS only. +- After enabling the virtual metronome, the SDK plays the specified audio effect file from the beginning, and controls the playback duration of each file according to **beatsPerMinute** you set in [AgoraRhythmPlayerConfig](rtc_api_data_type.html#class_agorarhythmplayerconfig). For example, if you set **beatsPerMinute** as `60`, the SDK plays one beat every second. If the file duration exceeds the beat duration, the SDK only plays the audio within the beat duration. + +### Parameters + +- config + + The metronome configuration. See [AgoraRhythmPlayerConfig](rtc_api_data_type.html#class_agorarhythmplayerconfig). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [initialize](class_irtcengine.html#api_create2) + +Initializes IRtcEngine. + +```cpp +virtual int initialize(const RtcEngineContext& context) = 0; +``` + +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](class_irtcengine.html#api_createagorartcengine) and initialize to create and initialize the IRtcEngine object. +- The SDK supports creating only one IRtcEngine instance for an app. + +### Parameters + +- context + + Configurations for the [IRtcEngine](class_irtcengine.html#class_irtcengine) instance. See [RtcEngineContext](rtc_api_data_type.html#class_rtcengineconfig_ng) for details. + +### Returns + +- 0(ERR_OK): Success. +- < 0: Failure. + - -1(ERR_FAILED): A general error occurs (no specified reason). + - -2(ERR_INVALID_ARGUMENT): An invalid parameter is used. + - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. + - -22(ERR_RESOURCE_LIMITED): The resource is limited. The SDK fails to allocate resources because your app consumes too much system resource or the system resources are insufficient. + - -101(ERR_INVALID_APP_ID): The App ID is invalid. + +## [createAgoraRtcEngine](class_irtcengine.html#api_createagorartcengine) + +Creates the IRtcEngine object. + +```cpp +AGORA_API agora::rtc::IRtcEngine *AGORA_CALL createAgoraRtcEngine () +``` + +- Deprecated: + + This method is deprecated. Use [initialize](class_irtcengine.html#api_create2) instead. + +### Parameters + +- appId + + The Agora App ID of your Agora project. + +### Returns + +- The IRtcEngine instance, if the method call succeeds. +- An error code, if the call fails. + +## [createDataStream [1/2\]](class_irtcengine.html#api_createdatastream) + +Creates a data stream. + +```cpp +virtual int createDataStream(int* streamId, bool reliable, bool ordered) = 0; +``` + +Each user can create up to five data streams during the lifecycle of [IRtcEngine](class_irtcengine.html#class_irtcengine). + +**Note** + +- Call this method after joining a channel. +- Agora does not support setting **reliable** as `true` and **ordered** as `true`. + +### Parameters + +- streamId + + Output parameter. Pointer to the ID of the created data stream. + +- reliable + + Whether or not the data stream is reliable:`true`: The recipients receive the data from the sender within five seconds. If the recipient does not receive the data within five seconds, the SDK triggers the [onStreamMessageError](class_irtcengineeventhandler.html#callback_onstreammessageerror) callback and returns an error code.`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 + + Whether or not the recipients receive the data stream in the sent order:`true`: The recipients receive the data in the sent order.`false`: The recipients do not receive the data in the sent order. + +### Returns + +- 0: The data stream is successfully created. +- < 0: Failure. + +## [createDataStream [2/2\]](class_irtcengine.html#api_createdatastream2) + +Creates a data stream. + +```cpp +virtual int createDataStream(int* streamId, DataStreamConfig& config) = 0; +``` + +Creates a data stream. Each user can create up to five data streams in a single channel. + +Compared with [createDataStream [1/2\]](class_irtcengine.html#api_createdatastream)[1/2], this method does not support data reliability. If a data packet is not received five seconds after it was sent, the SDK directly discards the data. + +### Parameters + +- streamId + + Output parameter. Pointer to the ID of the created data stream. + +- config + + The configurations for the data stream. For details, see [DataStreamConfig](rtc_api_data_type.html#class_datastreamconfig). + +### Returns + +- 0: The data stream is successfully created. +- < 0: Failure. + +## [createMediaPlayer](class_irtcengine.html#api_createmediaplayer) + +Creates a media player instance. + +```cpp +virtual agora_refptr createMediaPlayer() = 0; +``` + +### Returns + +- The [IMediaPlayer](class_imediaplayer.html#class_imediaplayer) instance, if the method call succeeds. +- An empty pointer , if the method call fails. + +## [destroyMediaPlayer](class_irtcengine.html#api_destroymediaplayer) + +Destroys the media player instance. + +```cpp +virtual int destroyMediaPlayer(agora_refptr media_player) = 0; +``` + +### Parameters + +- media_player + + [IMediaPlayer](class_imediaplayer.html#class_imediaplayer) object. + +### Returns + +- ≥ 0: Success. Returns the ID of media player source instance. +- < 0: Failure. + +## [disableAudio](class_irtcengine.html#api_disableaudio) + +Disables the audio module. + +```cpp +virtual int disableAudio() = 0; +``` + +**Note** + +- This method disables the internal engine and can be called anytime after initialization. It is still valid after one leaves channel. +- This method resets the internal engine and takes some time to take effect. Agora recommends using the following API methods to control the audio modules separately: + - [enableLocalAudio](class_irtcengine.html#api_enablelocalaudio): Whether to enable the microphone to create the local audio stream. + - [muteLocalAudioStream](class_irtcengine.html#api_mutelocalaudiostream): Whether to publish the local audio stream. + - [muteRemoteAudioStream](class_irtcengine.html#api_muteremoteaudiostream): Whether to subscribe and play the remote audio stream. + - [muteAllRemoteAudioStreams](class_irtcengine.html#api_muteallremoteaudiostreams): Whether to subscribe to and play all remote audio streams. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [disableAudioSpectrumMonitor](class_irtcengine.html#api_disableaudiospectrummonitor) + +Disables audio spectrum monitoring. + +```cpp +virtual int disableAudioSpectrumMonitor() = 0; +``` + +After calling [enableAudioSpectrumMonitor](class_irtcengine.html#api_enableaudiospectrummonitor), if you want to disable audio spectrum monitoring, you can call this method. + +**Note** + +You can call this method either before or after joining a channel. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [disableVideo](class_irtcengine.html#api_disablevideo) + +Disables the video module. + +```cpp +virtual int disableVideo() = 0; +``` + +This method disables video. You can call this method either before or after joining a channel. If you call it before joining a channel, an audio call starts when you join the channel. If you call it after joining a channel, a video call switches to an audio call. Call [enableVideo](class_irtcengine.html#api_enablevideo) to enable video. + +A successful call of this method triggers the [onUserEnableVideo](class_irtcengineeventhandler.html#callback_onuserenablevideo)(`false`) callback on the remote client. + +**Note** + +- This method affects the internal engine and can be called after leaving the channel. +- This method resets the internal engine and takes some time to take effect. Agora recommends using the following API methods to control the video engine modules separately: + - [enableLocalVideo](class_irtcengine.html#api_enablelocalvideo): Whether to enable the camera to create the local video stream. + - [muteLocalVideoStream](class_irtcengine.html#api_mutelocalvideostream): Whether to publish the local video stream. + - [muteRemoteVideoStream](class_irtcengine.html#api_muteremotevideostream): Whether to subscribe to and play the remote video stream. + - [muteAllRemoteVideoStreams](class_irtcengine.html#api_muteallremotevideostreams): Whether to subscribe to and play all remote video streams. + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [onRemoteVideoStateChanged](../API/class_irtcengineeventhandler.html#callback_onremotevideostatechanged) +- [onUserEnableVideo](../API/class_irtcengineeventhandler.html#callback_onuserenablevideo) + +## [enableAudio](class_irtcengine.html#api_enableaudio) + +Enables the audio module. + +```cpp +virtual int enableAudio() = 0; +``` + +The audio mode is enabled by default. + +**Note** + +- This method enables the internal engine and can be called anytime after initialization. It is still valid after one leaves channel. +- This method enables the audio module and takes some time to take effect. Agora recommends using the following API methods to control the audio module separately: + - [enableLocalAudio](class_irtcengine.html#api_enablelocalaudio): Whether to enable the microphone to create the local audio stream. + - [muteLocalAudioStream](class_irtcengine.html#api_mutelocalaudiostream): Whether to publish the local audio stream. + - [muteRemoteAudioStream](class_irtcengine.html#api_muteremoteaudiostream): Whether to subscribe and play the remote audio stream. + - [muteAllRemoteAudioStreams](class_irtcengine.html#api_muteallremoteaudiostreams): Whether to subscribe to and play all remote audio streams. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [enableAudioSpectrumMonitor](class_irtcengine.html#api_enableaudiospectrummonitor) + +Turn on audio spectrum monitoring. + +```cpp +virtual int enableAudioSpectrumMonitor(int intervalInMS = 100) = 0; +``` + +If you want to obtain the audio spectrum data of local or remote users, please register the audio spectrum observer and enable audio spectrum monitoring. + +**Note** + +You can call this method either before or after joining a channel. + +### Parameters + +- **intervalInMS** + + The interval (in milliseconds) at which the SDK triggers the [onLocalAudioSpectrum](class_iaudiospectrumobserver.html#callback_iaudiospectrumobserver_onlocalaudiospectrum) and [onRemoteAudioSpectrum](class_iaudiospectrumobserver.html#callback_iaudiospectrumobserver_onremoteaudiospectrum) callbacks. The default value is 100. Do not set this parameter to less than 10 milliseconds, otherwise the callback will not be triggered. + +### Returns + +- 0: Success. +- < 0: Failure. + - `-2 (ERR_INVALID_ARGUMENT)`: The parameter is invalid. + +**See also** + +- [onLocalAudioSpectrum](../API/class_iaudiospectrumobserver.html#callback_iaudiospectrumobserver_onlocalaudiospectrum) +- [onRemoteAudioSpectrum](../API/class_iaudiospectrumobserver.html#callback_iaudiospectrumobserver_onremoteaudiospectrum) + +## [enableAudioVolumeIndication](class_irtcengine.html#api_enableaudiovolumeindication) + +Enables the reporting of users' volume indication. + +```cpp +virtual int enableAudioVolumeIndication(int interval, int smooth, bool reportVad) = 0; +``` + +This method enables the SDK to regularly report the volume information of the local user who sends a stream and remote users (up to three) whose instantaneous volumes are the highest to the app. Once you call this method and users send streams in the channel, the SDK triggers the [onAudioVolumeIndication](class_irtcengineeventhandler.html#callback_onaudiovolumeindication) callback at the time interval set in this method. + +**Note** You can call this method either before or after joining a 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. We recommend a setting greater than 200 ms. Do not set this parameter to less than 10 milliseconds, otherwise the onAudioVolumeIndication callback will not be triggered. + +- smooth + + The smoothing factor sets the sensitivity of the audio volume indicator. The value ranges between 0 and 10. The recommended value is 3. The greater the value, the more sensitive the indicator. + +- 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. + +**See also** + +- [onAudioVolumeIndication](../API/class_irtcengineeventhandler.html#callback_onaudiovolumeindication) + +## [enableDualStreamMode [1/3\]](class_irtcengine.html#api_enabledualstreammode) + +Enables/Disables dual-stream mode. + +```cpp +virtual int enableDualStreamMode(bool enabled) = 0; +``` + +You can call this method to enable or disable the dual-stream mode on the publisher side. Dual streams are a hybrid of a high-quality video stream and a low-quality video stream: + +- High-quality video stream: High bitrate, high resolution. +- Low-quality video stream: Low bitrate, low resolution. + +After you enable the dual-stream mode, you can call [setRemoteVideoStreamType](class_irtcengine.html#api_setremotevideostreamtype) to choose to receive the high-quality video stream or low-quality video stream on the subscriber side. + +**Note** + +You can call this method either before or after joining a channel. + +### Parameters + +- enabled + + Enables dual-stream mode.`true`: Enables dual-stream mode.`false`: Disables dual-stream mode. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [enableDualStreamMode [2/3\]](class_irtcengine.html#api_enabledualstreammode2) + +Enables/Disables dual-stream mode. + +```cpp +virtual int enableDualStreamMode(VIDEO_SOURCE_TYPE sourceType, bool enabled) = 0; +``` + +You can call this method to enable or disable the dual-stream mode on the publisher side. Dual streams are a hybrid of a high-quality video stream and a low-quality video stream: + +- High-quality video stream: High bitrate, high resolution. +- Low-quality video stream: Low bitrate, low resolution. + +After you enable the dual-stream mode, you can call [setRemoteVideoStreamType](class_irtcengine.html#api_setremotevideostreamtype) to choose to receive the high-quality video stream or low-quality video stream on the subscriber side. + +**Note** + +You can call this method either before or after joining a channel. + +### Parameters + +- sourceType + + The capture type of the custom video source. For details, see [VIDEO_SOURCE_TYPE](rtc_api_data_type.html#enum_videosourcetype). + +- enabled + + Enables dual-stream mode.`true`: Enables dual-stream mode.`false`: Disables dual-stream mode. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [enableDualStreamMode [3/3\]](class_irtcengine.html#api_enabledualstreammode3) + +Enables/Disables dual-stream mode. + +```cpp +virtual int enableDualStreamMode( + VIDEO_SOURCE_TYPE sourceType, bool enabled, const SimulcastStreamConfig& streamConfig) = 0; +``` + +You can call this method to enable or disable the dual-stream mode on the publisher side. Dual streams are a hybrid of a high-quality video stream and a low-quality video stream: + +- High-quality video stream: High bitrate, high resolution. +- Low-quality video stream: Low bitrate, low resolution. + +After you enable the dual-stream mode, you can call [setRemoteVideoStreamType](class_irtcengine.html#api_setremotevideostreamtype) to choose to receive the high-quality video stream or low-quality video stream on the subscriber side. + +**Note** + +You can call this method either before or after joining a channel. + +### Parameters + +- sourceType + + The capture type of the custom video source. For details, see [VIDEO_SOURCE_TYPE](rtc_api_data_type.html#enum_videosourcetype). + +- enabled + + Enables dual-stream mode.`true`: Enables dual-stream mode.`false`: Disables dual-stream mode. + +- streamConfig + + The configuration of the low-quality video stream. See [SimulcastStreamConfig](rtc_api_data_type.html#class_simulcaststreamconfig). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [enableEncryption](class_irtcengine.html#api_enableencryption) + +Enables/Disables the built-in encryption. + +```cpp +virtual int enableEncryption(bool enabled, const EncryptionConfig& config) = 0; +``` + +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. After the user leaves the channel, the SDK automatically disables the built-in encryption. To enable the built-in encryption, call this method before the user joins the channel again. + +**Note** If you enable the built-in encryption, you cannot use the RTMP or RTMPS streaming function. + +### Parameters + +- enabled + + Whether to enable built-in encryption:true: Enable the built-in encryption.false: Disable the built-in encryption. + +- config + + Configurations of built-in encryption. For details, see [EncryptionConfig](rtc_api_data_type.html#class_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](class_irtcengine.html#class_irtcengine) instance before calling this method. + +## [enableExtension](class_irtcengine.html#api_enableextension) + +Enables/Disables extensions. + +```cpp +virtual int enableExtension( + const char* provider, const char* extension, bool enable=true, agora::media::MEDIA_SOURCE_TYPE type = agora::media::UNKNOWN_MEDIA_SOURCE) = 0; +``` + +Ensure that you call this method before joining a channel. + +**Note** + +- If you want to enable multiple extensions, you need to call this method multiple times. +- The data processing order of different extensions in the SDK is determined by the order in which the extensions are enabled. That is, the extension that is enabled first will process the data first. + +### Parameters + +- provider + + The name of the extension provider. + +- extension + + The name of the extension. + +- enable + + Whether to enable the extension:`true`: Enable the extension.`false`: Disable the extension. + +- type + + The type of media source. See [MEDIA_SOURCE_TYPE](rtc_api_data_type.html#enum_mediasourcetype).**Note** This parameter in this method only supports two values:The default value is UNKNOWN_MEDIA_SOURCE.If you want to use a secondary camera to capture video, set this parameter to SECONDARY_CAMERA_SOURCE. + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [onExtensionStarted](../API/class_irtcengineeventhandler.html#callback_onextensionstarted) +- [onExtensionStopped](../API/class_irtcengineeventhandler.html#callback_onextensionstoped) +- [onExtensionError](../API/class_irtcengineeventhandler.html#callback_onextensionerror) + +## [enableFaceDetection](class_irtcengine.html#api_enablefacedetection) + +Enables/Disables face detection for the local user. + +```cpp +virtual int enableFaceDetection(bool enabled) = 0; +``` + + + +You can call this method either before or after joining a channel. + +**Note** This method is for Android and iOS only. + +Once face detection is enabled, the SDK triggers the [onFacePositionChanged](class_irtcengineeventhandler.html#callback_onfacepositionchanged) callback to report the face information of the local user: + +- The width and height of the local video. +- The position of the human face in the local video. +- The distance between the human face and the screen. + +This method needs to be called after the camera is started (for example, by calling startPreview or joinChannel [2/2]). + +### Parameters + +- enabled + + Whether to enable face detection:`true`: Enable face detection.`false`: (Default) Disable face detection. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [enableInEarMonitoring](class_irtcengine.html#api_enableinearmonitoring2) + +Enables in-ear monitoring. + +```cpp +virtual int enableInEarMonitoring(bool enabled, int includeAudioFilters) = 0; +``` + +This method enables or disables in-ear monitoring. + +### Parameters + +- enabled + + Enables in-ear monitoring.`true`: Enables in-ear monitoring.`false`: (Default) Disables in-ear monitoring. + +- includeAudioFilters + + The audio filter of in-ear monitoring: For details, see [EAR_MONITORING_FILTER_TYPE](rtc_api_data_type.html#enum_earmonitoringfiltertype). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [enableLocalAudio](class_irtcengine.html#api_enablelocalaudio) + +Enables/Disables the local audio capture. + +```cpp +virtual int enableLocalAudio(bool enabled) = 0; +``` + +The audio function is enabled by default. This method disables or re-enables the local audio function to stop or restart local audio capturing. + +This method does not affect receiving or playing the remote audio streams, and [enableLocalAudio](class_irtcengine.html#api_enablelocalaudio)(`false`) applies to scenarios where the user wants to receive remote audio streams without sending any audio stream to other users in the channel. + +Once the local audio function is disabled or re-enabled, the SDK triggers the [onLocalAudioStateChanged](class_irtcengineeventhandler.html#callback_onlocalaudiostatechanged) callback, which reports LOCAL_AUDIO_STREAM_STATE_STOPPED(0) or LOCAL_AUDIO_STREAM_STATE_RECORDING(1). + +**Note** + +- This method is different from the + + + + muteLocalAudioStream + + + + method: + + - enableLocalVideo: Disables/Re-enables the local audio capturing and processing. If you disable or re-enable local audio capturing using the `enableLocalAudio` method, the local user might hear a pause in the remote audio playback. + - muteLocalAudioStream: Sends/Stops sending the local audio streams. + +- You can call this method either before or after joining a channel. + +### Parameters + +- enabled + + `true`: (Default) Re-enable the local audio function, that is, to start the local audio capturing device (for example, the microphone).`false`: Disable the local audio function, that is, to stop local audio capturing. + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [onLocalAudioStateChanged](../API/class_irtcengineeventhandler.html#callback_onlocalaudiostatechanged) + +## [enableLocalVideo](class_irtcengine.html#api_enablelocalvideo) + +Enables/Disables the local video capture. + +```cpp +virtual int enableLocalVideo(bool enabled) = 0; +``` + +This method disables or re-enables the local video capturer, and does not affect receiving the remote video stream. + +After calling [enableVideo](class_irtcengine.html#api_enablevideo), the local video capturer is enabled by default. You can call [enableLocalVideo](class_irtcengine.html#api_enablelocalvideo)(`false`) to disable the local video capturer. If you want to re-enable the local video, call enableLocalVideo(`true`). + +After the local video capturer is successfully disabled or re-enabled, the SDK triggers the callback on the remote client[onRemoteVideoStateChanged](class_irtcengineeventhandler.html#callback_onremotevideostatechanged). + +**Note** + +- You can call this method either before or after joining a channel. +- This method enables the internal engine and is valid after . + +### Parameters + +- enabled + + Whether to enable the local video capture.`true`: (Default) Enable the local video capture.`false`: Disables the local video capture. Once the local video is disabled, the remote users can no longer receive the video stream of this user, while this user can still receive the video streams of the other remote users. When set to `false`, this method does not require a local camera. + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [onUserEnableLocalVideo](../API/class_irtcengineeventhandler.html#callback_onuserenablelocalvideo) + +## [enableLoopbackRecording](class_irtcengine.html#api_enableloopbackrecording_ng) + +Enables loopback audio capturing. + +```cpp +virtual int enableLoopbackRecording(bool enabled) = 0; +``` + +If you enable loopback audio capturing, the output of the sound card is mixed into the audio stream sent to the other end. + +**Note** + +This method applies to Windows only. + +### Parameters + +- enabled + + Sets whether to enable loopback capturing.`true`: Enable loopback audio capturing.`false`: (Default) Disable loopback capturing. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [enableSoundPositionIndication](class_irtcengine.html#api_enablesoundpositionindication) + +Enables/Disables stereo panning for remote users. + +```cpp +virtual int enableSoundPositionIndication(bool enabled) = 0; +``` + +Ensure that you call this method before joining a channel 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 + + Whether to enable stereo panning for remote users:`true`: Enable stereo panning.`false`: Disable stereo panning. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [enableVideo](class_irtcengine.html#api_enablevideo) + +Enables the video module. + +```cpp +virtual int enableVideo() = 0; +``` + +Call this method either before joining a channel or during a call. If this method is called before joining a channel, the call starts in the video mode. Call [disableVideo](class_irtcengine.html#api_disablevideo) to disable the video mode. + +A successful call of this method triggers the [onRemoteVideoStateChanged](class_irtcengineeventhandler.html#callback_onremotevideostatechanged) callback on the remote client. + +**Note** + +- This method enables the internal engine and is valid after leaving the channel. +- This method resets the internal engine and takes some time to take effect. Agora recommends using the following API methods to control the video engine modules separately: + - [enableLocalVideo](class_irtcengine.html#api_enablelocalvideo): Whether to enable the camera to create the local video stream. + - [muteLocalVideoStream](class_irtcengine.html#api_mutelocalvideostream): Whether to publish the local video stream. + - [muteRemoteVideoStream](class_irtcengine.html#api_muteremotevideostream): Whether to subscribe to and play the remote video stream. + - [muteAllRemoteVideoStreams](class_irtcengine.html#api_muteallremotevideostreams): Whether to subscribe to and play all remote video streams. + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [onRemoteVideoStateChanged](../API/class_irtcengineeventhandler.html#callback_onremotevideostatechanged) +- [onUserEnableVideo](../API/class_irtcengineeventhandler.html#callback_onuserenablevideo) + +## [enableVirtualBackground](class_irtcengine.html#api_enablevirtualbackground) + +Enables/Disables the virtual background. (beta feature) + +``` +virtual int enableVirtualBackground(bool enabled, VirtualBackgroundSource backgroundSource) = 0; +``` + +The virtual background function allows you to replace the original background image of the local user or to blur the background. After successfully enabling the virtual background function, all users in the channel can see the customized background. + +Enabling the virtual background function involves a series of method calls. The calling sequence is as follows: + +1. Call `loadExtensionProvider(libagora_segmentation_extension.dll)` during [IRtcEngine](class_irtcengine.html#class_irtcengine) initialization to specify the extension's library path. +2. Call `enableExtension(agora_segmentation, PortraitSegmentation, true)` to enable the extension. +3. Call [enableVideo](class_irtcengine.html#api_enablevideo) to enable the video module. +4. Call this method to enable the virtual background function. + +**Note** + +- This function requires a high-performance device. Agora recommends that you use this function on devices with the following chips: + - Snapdragon 700 series 750G and later + - Snapdragon 800 series 835 and later + - Dimensity 700 series 720 and later + - Kirin 800 series 810 and later + - Kirin 900 series 980 and later + - Devices with an i5 CPU and better + - Devices with an A9 chip and better, as follows: + - iPhone 6S and later + - iPad Air 3rd generation and later + - iPad 5th generation and later + - iPad Pro 2nd generation and later + - iPad mini 5th generation and later +- 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. + - There are few objects in the captured video. Portraits are half-length and unobstructed. Ensure that the background is a solid color that is different from the color of the user's clothing. + +### Parameters + +- enabled + + Whether to enable virtual background:`true`: Enable virtual background.`false`: Disable virtual background. + +- backgroundSource + + The custom background image. See [VirtualBackgroundSource](rtc_api_data_type.html#class_virtualbackgroundsource) for details. To adapt the resolution of the custom background image to that of the video captured by the SDK, 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. + - -1: The custom background image does not exist. Please check the value of **source** in [VirtualBackgroundSource](rtc_api_data_type.html#class_virtualbackgroundsource). + - -2: The color format of the custom background image is invalid. Please check the value of **color** in [VirtualBackgroundSource](rtc_api_data_type.html#class_virtualbackgroundsource). + - -3: The device does not support using the virtual background. + +## [enableWebSdkInteroperability](class_irtcengine.html#api_enablewebsdkinteroperability) + +Enables interoperability with the Agora Web SDK (applicable only in the live streaming scenarios). + +```cpp +virtual int enableWebSdkInteroperability(bool enabled) = 0; +``` + +- Deprecated: + + The SDK automatically enables interoperability with the Web SDK, so you no longer need to call this method. + +This method enables or disables interoperability with the Agora Web SDK. If the channel has Web SDK users, ensure that you call this method, or the video of the Native user will be a black screen for the Web user. + +This method is only applicable in live streaming scenarios, and interoperability is enabled by default in communication scenarios. + +### Parameters + +- enabled + + Whether to enable interoperability with the Agora Web SDK.`true`: Enable interoperability.`false`: (Default) Disable interoperability. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [getAudioDeviceInfo](class_irtcengine.html#api_getaudiodeviceinfo) + +Gets the audio device information. + +```cpp +virtual int getAudioDeviceInfo(DeviceInfo& deviceInfo) = 0; +``` + +After calling this method, you can get whether the audio device supports ultra-low-latency capture and playback. + +**Note** + +- This method is for Android only. +- You can call this method either before or after joining a channel. + +### Parameters + +- deviceInfo + + Input and output parameter. A [DeviceInfo](rtc_api_data_type.html#class_deviceinfo) object that identifies the audio device information.Input value: A DeviceInfo object.Output value: A DeviceInfo object containing audio device information. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [getAudioMixingCurrentPosition](class_irtcengine.html#api_getaudiomixingcurrentposition) + +Retrieves the playback position (ms) of the music file. + +```cpp +virtual int getAudioMixingCurrentPosition() = 0; +``` + +Retrieves the playback position (ms) of the audio. + +**Note** You need to call this method after calling startAudioMixing [2/2] and receiving the onAudioMixingStateChanged(`PLAY`) callback. + +### Returns + +- ≥ 0: The current playback position of the audio mixing, if this method call succeeds. +- < 0: Failure. + +## [getAudioMixingDuration](class_irtcengine.html#api_getaudiomixingduration) + +Retrieves the duration (ms) of the music file. + +```cpp +virtual int getAudioMixingDuration() = 0; +``` + +Retrieves the total duration (ms) of the audio. + +**Note** You need to call this method after calling [startAudioMixing [2/2\]](class_irtcengine.html#api_startaudiomixing2) and receiving the [onAudioMixingStateChanged](class_irtcengineeventhandler.html#callback_onaudiomixingstatechanged_ng)(AUDIO_MIXING_STATE_PLAYING) callback. + +### Returns + +- ≥ 0: The audio mixing duration, if this method call succeeds. +- < 0: Failure. + +## [getAudioMixingPlayoutVolume](class_irtcengine.html#api_getaudiomixingplayoutvolume) + +Retrieves the audio mixing volume for local playback. + +```cpp +virtual int getAudioMixingPlayoutVolume() = 0; +``` + +This method helps troubleshoot audio volume‑related issues. + +**Note** You need to call this method after calling startAudioMixing [2/2] and receiving the onAudioMixingStateChanged(`PLAY`) callback. + +### Returns + +- ≥ 0: The audio mixing volume, if this method call succeeds. The value range is [0,100]. +- < 0: Failure. + +## [getAudioMixingPublishVolume](class_irtcengine.html#api_getaudiomixingpublishvolume) + +Retrieves the audio mixing volume for publishing. + +```cpp +virtual int getAudioMixingPublishVolume() = 0; +``` + +- Since + + v2.4.1 + +This method helps troubleshoot audio volume‑related issues. + +**Note** You need to call this method after calling startAudioMixing [2/2] and receiving the onAudioMixingStateChanged(`PLAY`) callback. + +### Returns + +- ≥ 0: The audio mixing volume, if this method call succeeds. The value range is [0,100]. +- < 0: Failure. + +## [getCallId](class_irtcengine.html#api_getcallid) + +Retrieves the call ID. + +```cpp +virtual int getCallId(agora::util::AString& callId) = 0; +``` + +When a user joins a channel on a client, a **callId** is generated to identify the call from the client. Some methods, such as [rate](class_irtcengine.html#api_rate) and [complain](class_irtcengine.html#api_complain), must be called after the call ends to submit feedback to the SDK. These methods require the **callId** parameter. + +**Note** Call this method after joining a channel. + +### Parameters + +- callId + + Output parameter, the current call ID. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [getCameraMaxZoomFactor](class_irtcengine.html#api_getcameramaxzoomfactor) + +Gets the maximum zoom ratio supported by the camera. + +```cpp +virtual float getCameraMaxZoomFactor() = 0; +``` + +**Note** + +- This method is for Android and iOS only. +- Call this method before calling [joinChannel [2/2\]](class_irtcengine.html#api_joinchannel2_ng), [enableVideo](class_irtcengine.html#api_enablevideo), or [enableLocalVideo](class_irtcengine.html#api_enablelocalvideo), depending on which method you use to turn on your local camera. + +### Returns + +The maximum zoom factor. + +## [getConnectionState](class_irtcengine.html#api_getconnectionstate) + +Gets the current connection state of the SDK. + +```cpp +virtual CONNECTION_STATE_TYPE getConnectionState() = 0; +``` + +You can call this method either before or after joining a channel. + +### Returns + +The current connection state. For details, see [CONNECTION_STATE_TYPE](rtc_api_data_type.html#enum_connectionstatetype). + +## [getEffectsVolume](class_irtcengine.html#api_geteffectsvolume) + +Retrieves the volume of the audio effects. + +```cpp +virtual int getEffectsVolume() = 0; +``` + +The volume is an integer ranging from 0 to 100. The default value is 100, the original volume. + +### Returns + +- Volume of the audio effects, if this method call succeeds. +- < 0: Failure. + +## [getErrorDescription](class_irtcengine.html#api_geterrordescription) + +Gets the warning or error description. + +```cpp +virtual const char* getErrorDescription(int code) = 0; +``` + +### Parameters + +- code + + The error code or warning code reported by the SDK. + +### Returns + +The specific error or warning description. + +## [getVolumeOfEffect](class_irtcengine.html#api_getvolumeofeffect) + +Gets the volume of a specified audio effect. + +```cpp +virtual int getVolumeOfEffect(int soundId) = 0; +``` + +### Parameters + +- soundId + + The ID of the audio effect. + +### Returns + +- ≥ 0: Returns the volume of the specified audio effect, if the method call is successful. The value ranges between 0 and 100. 100 represents the original volume. +- < 0: Failure. + +## [getVersion](class_irtcengine.html#api_getversion) + +Gets the SDK version. + +```cpp +virtual const char* getVersion(int* build) = 0; +``` + +### Returns + +The SDK version number. The format is a string. + +## [getUserInfoByUid](class_irtcengine.html#api_getuserinfobyuid) + +Gets the user information by passing in the user ID. + +```cpp +virtual int getUserInfoByUid(uid_t uid, rtc::UserInfo* userInfo, const char* channelId = NULL, const char* localUserAccount = NULL) = 0; +``` + +After a remote user joins the channel, the SDK gets the UID and user account of the remote user, caches them in a mapping table object, and triggers the [onUserInfoUpdated](class_irtcengineeventhandler.html#callback_onuserinfoupdated) callback on the local client. After receiving the callback, you can call this method to get the user account of the remote user from the [UserInfo](rtc_api_data_type.html#class_userinfo) object by passing in the user ID. + +### Parameters + +- uid + + User ID. + +- userInfo + + Input and output parameter. The [UserInfo](rtc_api_data_type.html#class_userinfo) object that identifies the user information.Input: A UserInfo object.Output: A UserInfo object that contains the user account and user ID of the user. + +- 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.Space"!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "= ", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", "," + +- localUserAccount + + The user account of the local user. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [getUserInfoByUserAccount](class_irtcengine.html#api_getuserinfobyuseraccount) + +Gets the user information by passing in the user account. + +```cpp +virtual int getUserInfoByUserAccount(const char* userAccount, rtc::UserInfo* userInfo, const char* channelId = NULL, const char* localUserAccount = NULL) = 0; +``` + +After a remote user joins the channel, the SDK gets the UID and user account of the remote user, caches them in a mapping table object, and triggers the [onUserInfoUpdated](class_irtcengineeventhandler.html#callback_onuserinfoupdated) callback on the local client. After receiving the callback, you can call this method to get the user account of the remote user from the [UserInfo](rtc_api_data_type.html#class_userinfo) object by passing in the user ID. + +### Parameters + +- userAccount + + The user account. + +- userInfo + + Input and output parameter. The [UserInfo](rtc_api_data_type.html#class_userinfo) object that identifies the user information.Input: A UserInfo object.Output: A UserInfo object that contains the user account and user ID of the user. + +- 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.Space"!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "= ", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", "," + +- localUserAccount + + The user account of the local user. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [isCameraAutoFocusFaceModeSupported](class_irtcengine.html#api_iscameraautofocusfacemodesupported) + +Checks whether the device supports the face auto-focus function. + +This method needs to be called after the camera is started (for example, by calling [startPreview](class_irtcengine.html#api_startpreview) or [joinChannel [2/2\]](class_irtcengine.html#api_joinchannel2_ng)). + +### Returns + +- `true`: The device supports the face auto-focus function. +- `false`: The device does not support the face auto-focus function. + +## [isCameraExposurePositionSupported](class_irtcengine.html#api_iscameraexposurepositionsupported) + +Checks whether the device supports manual exposure. + +```cpp +virtual bool isCameraExposurePositionSupported() = 0; +``` + +**Note** + +- This method is for Android and iOS only. +- Call this method before calling [joinChannel [2/2\]](class_irtcengine.html#api_joinchannel2_ng), [enableVideo](class_irtcengine.html#api_enablevideo), or [enableLocalVideo](class_irtcengine.html#api_enablelocalvideo), depending on which method you use to turn on your local camera. + +### Returns + +- `true`: The device supports manual exposure. +- `false`: The device does not support manual exposure. + +## [isCameraFaceDetectSupported](class_irtcengine.html#api_iscamerafacedetectsupported) + +Checks whether the device camera supports face detection. + +```cpp +virtual bool isCameraFaceDetectSupported() = 0; +``` + +**Note** This method is for Android and iOS only. + +### Returns + +- `true`: The device camera supports face detection. +- `false`: The device camera does not support face detection. + +## [isCameraFocusSupported](class_irtcengine.html#api_iscamerafocussupported) + +Check whether the device supports the manual focus function. + +```cpp +virtual bool isCameraFocusSupported() = 0; +``` + +**Note** + +- This method is for Android and iOS only. +- Call this method before calling [joinChannel [2/2\]](class_irtcengine.html#api_joinchannel2_ng), [enableVideo](class_irtcengine.html#api_enablevideo), or [enableLocalVideo](class_irtcengine.html#api_enablelocalvideo), depending on which method you use to turn on your local camera. + +### Returns + +- `true`: The device supports the manual focus function. +- `false`: The device does not support the manual focus function. + +## [isCameraTorchSupported](class_irtcengine.html#api_iscameratorchsupported) + +Checks whether the device supports camera flash. + +```cpp +virtual bool isCameraTorchSupported() = 0; +``` + +This method needs to be called after the camera is started (for example, by calling [startPreview](class_irtcengine.html#api_startpreview) or [joinChannel [2/2\]](class_irtcengine.html#api_joinchannel2_ng)). + +**Note** + +- This method is for Android and iOS only. +- The app enables the front camera by default. If your front camera does not support flash, this method returns false. If you want to check whether the rear camera supports flash, call [switchCamera](class_irtcengine.html#api_switchcamera) before this method. + +### Returns + +- `true`: The device supports camera flash. +- `false`: The device does not support camera flash. + +## [isCameraZoomSupported](class_irtcengine.html#api_iscamerazoomsupported) + +Checks whether the device supports camera zoom. + +```cpp +virtual bool isCameraZoomSupported() = 0; +``` + +**Note** + +- This method is for Android and iOS only. +- Call this method before calling [joinChannel [2/2\]](class_irtcengine.html#api_joinchannel2_ng), [enableVideo](class_irtcengine.html#api_enablevideo), or [enableLocalVideo](class_irtcengine.html#api_enablelocalvideo), depending on which method you use to turn on your local camera. + +### Returns + +- `true`: The device supports camera zoom. +- `false`: The device does not support camera zoom. + +## [isSpeakerphoneEnabled](class_irtcengine.html#api_isspeakerphoneenabled) + +Checks whether the speakerphone is enabled. + +```cpp +virtual bool isSpeakerphoneEnabled() = 0; +``` + +**Note** This method is for Android and iOS only. + +### Returns + +- `true`: The speakerphone is enabled, and the audio plays from the speakerphone. +- `false`: The speakerphone is not enabled, and the audio plays from devices other than the speakerphone. For example, the headset or earpiece. + +## [joinChannel [1/2\]](class_irtcengine.html#api_joinchannel) + +Joins a channel. + +```cpp +virtual int joinChannel(const char* token, const char* channelId, const char* info, + uid_t uid) = 0; +``` + + + +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](class_irtcengineeventhandler.html#callback_onjoinchannelsuccess) and [onConnectionStateChanged](class_irtcengineeventhandler.html#callback_onconnectionstatechanged) callbacks. +- The remote client: [onUserJoined](class_irtcengineeventhandler.html#callback_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](class_irtcengineeventhandler.html#callback_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. See [Authenticate Your Users with Token](https://docs.agora.io/en/live-streaming-4.x-preview/token_server_android_ng?platform=Windows). + +- 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.Space"!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "= ", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", "," + +- info + + (Optional) Reserved for future use. + +- uid + + 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 232-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 app must maintain the returned user ID, because the SDK does not do so. + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [onJoinChannelSuccess](../API/class_irtcengineeventhandler.html#callback_onjoinchannelsuccess) +- [onUserJoined](../API/class_irtcengineeventhandler.html#callback_onuserjoined) +- [onRejoinChannelSuccess](../API/class_irtcengineeventhandler.html#callback_onrejoinchannelsuccess) + +## [joinChannel [2/2\]](class_irtcengine.html#api_joinchannel2_ng) + +Joins a channel with media options. + +```cpp +virtual int joinChannel(const char* token, const char* channelId, uid_t uid, + const ChannelMediaOptions& options) = 0; +``` + +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](class_irtcengineeventhandler.html#callback_onjoinchannelsuccess) and [onConnectionStateChanged](class_irtcengineeventhandler.html#callback_onconnectionstatechanged) callbacks. +- The remote client: [onUserJoined](class_irtcengineeventhandler.html#callback_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](class_irtcengineeventhandler.html#callback_onrejoinchannelsuccess) callback on the local client. + +Compared to [joinChannel [1/2\]](class_irtcengine.html#api_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](class_irtcengine.html#api_create2) method; otherwise, you may fail to join the channel by token. + +### Parameters + +- token + + The token generated on your server for authentication. See [Authenticate Your Users with Token](https://docs.agora.io/en/live-streaming-4.x-preview/token_server_android_ng?platform=Windows). + +- 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.Space"!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "= ", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", "," + +- 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 232-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. See [ChannelMediaOptions](rtc_api_data_type.html#class_channelmediaoptions_ng) for details. + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [onJoinChannelSuccess](../API/class_irtcengineeventhandler.html#callback_onjoinchannelsuccess) +- [onUserJoined](../API/class_irtcengineeventhandler.html#callback_onuserjoined) +- [onRejoinChannelSuccess](../API/class_irtcengineeventhandler.html#callback_onrejoinchannelsuccess) + +## [joinChannelWithUserAccount [1/2\]](class_irtcengine.html#api_joinchannelwithuseraccount) + +Joins the channel with a user account. + + + +```cpp +virtual int joinChannelWithUserAccount(const char* token, + const char* channelId, + const char* userAccount) = 0; +``` + +This method allows a user to join the channel with the user account. After the user successfully joins the channel, the SDK triggers the following callbacks: + +- The local client: [onLocalUserRegistered](class_irtcengineeventhandler.html#callback_onlocaluserregistered), [onJoinChannelSuccess](class_irtcengineeventhandler.html#callback_onjoinchannelsuccess) and [onConnectionStateChanged](class_irtcengineeventhandler.html#callback_onconnectionstatechanged) callbacks. +- The remote client: [onUserJoined](class_irtcengineeventhandler.html#callback_onuserjoined) and [onUserInfoUpdated](class_irtcengineeventhandler.html#callback_onuserinfoupdated), if the user joining the channel is in the communication profile or is a host in the live streaming profile. + +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. + +**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 ID of the user is set to the same parameter type. + +### Parameters + +- token + + The token generated on your server for authentication. See [Authenticate Your Users with Token](https://docs.agora.io/en/live-streaming-4.x-preview/token_server_android_ng?platform=Windows). + +- 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.Space"!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "= ", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", "," + +- userAccount + + The user account. This parameter is used to identify the user in the channel for real-time audio and video engagement. You need to set and manage user accounts yourself and ensure that each user account in the same channel is unique. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as NULL. Supported characters are (89 in total):The 26 lowercase English letters: a to z.The 26 uppercase English letters: A to Z.All numeric characters: 0 to 9.Space"!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", "," + +### Returns + +- 0: Success. +- < 0: Failure. + - -2 (ERR_INVALID_ARGUMENT): The parameter is invalid. + - -3(ERR_NOT_READY): The SDK fails to be initialized. You can try re-initializing the SDK. + - -5(ERR_REFUSED): The request is rejected. + +**See also** + +- [onLocalUserRegistered](../API/class_irtcengineeventhandler.html#callback_onlocaluserregistered) +- [onJoinChannelSuccess](../API/class_irtcengineeventhandler.html#callback_onjoinchannelsuccess) +- [onUserJoined](../API/class_irtcengineeventhandler.html#callback_onuserjoined) +- [onUserInfoUpdated](../API/class_irtcengineeventhandler.html#callback_onuserinfoupdated) + +## [joinChannelWithUserAccount [2/2\]](class_irtcengine.html#api_joinchannelwithuseraccount2) + +Joins the channel with a user account, and configures whether to automatically subscribe to audio or video streams after joining the channel. + + + +```cpp +virtual int joinChannelWithUserAccount(const char* token, + const char* channelId, + const char* userAccount, + const ChannelMediaOptions& options) = 0; +``` + +This method allows a user to join the channel with the user account. After the user successfully joins the channel, the SDK triggers the following callbacks: + +- The local client: [onLocalUserRegistered](class_irtcengineeventhandler.html#callback_onlocaluserregistered), [onJoinChannelSuccess](class_irtcengineeventhandler.html#callback_onjoinchannelsuccess) and [onConnectionStateChanged](class_irtcengineeventhandler.html#callback_onconnectionstatechanged) callbacks. +- The remote client: The [onUserJoined](class_irtcengineeventhandler.html#callback_onuserjoined) callback if the user is in the COMMUNICATION profile, and the [onUserInfoUpdated](class_irtcengineeventhandler.html#callback_onuserinfoupdated) callback if the user is a host in the LIVE_BROADCASTING profile. + +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. + +Compared to [joinChannelWithUserAccount [1/2\]](class_irtcengine.html#api_joinchannelwithuseraccount), 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** 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 ID of the user is set to the same parameter type. + +### Parameters + +- token + + The token generated on your server for authentication. See [Authenticate Your Users with Token](https://docs.agora.io/en/live-streaming-4.x-preview/token_server_android_ng?platform=Windows). + +- 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.Space"!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "= ", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", "," + +- userAccount + + The user account. This parameter is used to identify the user in the channel for real-time audio and video engagement. You need to set and manage user accounts yourself and ensure that each user account in the same channel is unique. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as NULL. Supported characters are (89 in total):The 26 lowercase English letters: a to z.The 26 uppercase English letters: A to Z.All numeric characters: 0 to 9.Space"!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", "," + +- options + + The channel media options. See [ChannelMediaOptions](rtc_api_data_type.html#class_channelmediaoptions_ng) for details. + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [onLocalUserRegistered](../API/class_irtcengineeventhandler.html#callback_onlocaluserregistered) +- [onJoinChannelSuccess](../API/class_irtcengineeventhandler.html#callback_onjoinchannelsuccess) +- [onUserJoined](../API/class_irtcengineeventhandler.html#callback_onuserjoined) +- [onUserInfoUpdated](../API/class_irtcengineeventhandler.html#callback_onuserinfoupdated) + +## [leaveChannel [1/2\]](class_irtcengine.html#api_leavechannel) + +Leaves a channel. + +```cpp +virtual int leaveChannel() = 0; +``` + +This method releases all resources related to the session. This method call is asynchronous. When this method returns, it does not necessarily mean that the user has left the channel. + +After joining the channel, you must call this method or leaveChannel [2/2] to end the call; otherwise, you cannot join the next call. + +A successful call of this method triggers the following callbacks: + +- The local client: [onLeaveChannel](class_irtcengineeventhandler.html#callback_onleavechannel). +- The remote client: [onUserOffline](class_irtcengineeventhandler.html#callback_onuseroffline), if the user joining the channel is in the Communication profile, or is a host in the Live-broadcasting profile. + +**Note** + +- If you call [release](class_irtcengine.html#api_release) immediately after calling this method, the SDK does not trigger the onLeaveChannel callback. +- If you call this method during a CDN live streaming, the SDK automatically calls the [removePublishStreamUrl](class_irtcengine.html#api_removepublishstreamurl) method. + +### Returns + +- 0(ERR_OK): Success. +- < 0: Failure. + - -1(ERR_FAILED): A general error occurs (no specified reason). + - -2 (ERR_INVALID_ARGUMENT): The parameter is invalid. + - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. + +**See also** + +- [onLeaveChannel](../API/class_irtcengineeventhandler.html#callback_onleavechannel) +- [onUserOffline](../API/class_irtcengineeventhandler.html#callback_onuseroffline) + +## [leaveChannel [2/2\]](class_irtcengine.html#api_leavechannel2) + +Leaves a channel. + +```cpp +virtual int leaveChannel(const LeaveChannelOptions& options) = 0; +``` + +This method lets the user leave the channel, for example, by hanging up or exiting the call. + +After joining the channel, you must call this method or [leaveChannel [1/2\]](class_irtcengine.html#api_leavechannel) to end the call, otherwise, the next call cannot be started. + +No matter whether you are currently in a call or not, you can call this method without side effects. This method releases all resources related to the session. + +This method call is asynchronous, and the user has not left the channel when the method call returns. After you leave the channel, the SDK triggers the [onLeaveChannel](class_irtcengineeventhandler.html#callback_onleavechannel) callback. A successful call of this method triggers the following callbacks: The local client: onLeaveChannel.The remote client: [onUserOffline](class_irtcengineeventhandler.html#callback_onuseroffline), if the user joining the channel is in the COMMUNICATION profile, or is a host in the LIVE_BROADCASTING profile. + +**Note** + +- If you call [release](class_irtcengine.html#api_release) immediately after calling this method, the SDK does not trigger the onLeaveChannel callback. +- If you call this method during a CDN live streaming, the SDK automatically calls the [removePublishStreamUrl](class_irtcengine.html#api_removepublishstreamurl) method. + +### Parameters + +- options + + The options for leaving the channel. See [LeaveChannelOptions](rtc_api_data_type.html#class_leavechanneloptions). + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [onLeaveChannel](../API/class_irtcengineeventhandler.html#callback_onleavechannel) +- [onUserOffline](../API/class_irtcengineeventhandler.html#callback_onuseroffline) + +## [loadExtensionProvider](class_irtcengine.html#api_loadextensionprovider) + +Adds an extension to the SDK. + +```cpp +virtual int loadExtensionProvider(const char* extension_lib_path) = 0; +``` + +### Parameters + +- extension_lib_path + + The extension library path and name. For example: `/library/libagora_segmentation_extension.dll`. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [muteAllRemoteAudioStreams](class_irtcengine.html#api_muteallremoteaudiostreams) + +Stops or resumes subscribing to the audio streams of all remote users. + +```cpp +virtual int muteAllRemoteAudioStreams(bool mute) = 0; +``` + +As of v3.3.0, after successfully calling this method, the local user stops or resumes subscribing to the audio streams of all remote users, including all subsequent users. + +**Note** + +- Call this method after joining a channel. +- See recommended settings in[ Set the Subscribing State](https://docs.agora.io/en/live-streaming-4.x-preview/set_subscribing_state?platform=Windows). + +### Parameters + +- mute + + Whether to subscribe to the audio streams of all remote users:`true`: Do not subscribe to the audio streams of all remote users.`false`: (Default) Subscribe to the audio streams of all remote users by default. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [muteAllRemoteVideoStreams](class_irtcengine.html#api_muteallremotevideostreams) + +Stops or resumes subscribing to the video streams of all remote users. + +```cpp +virtual int muteAllRemoteVideoStreams(bool mute) = 0; +``` + +As of v3.3.0, after successfully calling this method, the local user stops or resumes subscribing to the video streams of all remote users, including all subsequent users. + +**Note** + +- Call this method after joining a channel. + +### Parameters + +- mute + + Whether to stop subscribing to the video streams of all remote users.`true`: Stop subscribing to the video streams of all remote users.`false`: (Default) Subscribe to the audio streams of all remote users by default. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [muteLocalAudioStream](class_irtcengine.html#api_mutelocalaudiostream) + +Stops or resumes publishing the local audio stream. + +```cpp +virtual int muteLocalAudioStream(bool mute) = 0; +``` + +**Note** + +- This method does not affect any ongoing audio recording, because it does not disable the microphone. + +### Parameters + +- mute + + Whether to stop publishing the local audio stream.`true`: Stop publishing the local audio stream.`false`: (Default) Resumes publishing the local audio stream. + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [onUserMuteAudio](../API/class_irtcengineeventhandler.html#callback_onusermuteaudio) + +## [muteLocalVideoStream](class_irtcengine.html#api_mutelocalvideostream) + +Stops or resumes publishing the local video stream. + +```cpp +virtual int muteLocalVideoStream(bool mute) = 0; +``` + +A successful call of this method triggers the [onUserMuteVideo](class_irtcengineeventhandler.html#callback_onusermutevideo) callback on the remote client. + +**Note** + +- This method executes faster than the [enableLocalVideo](class_irtcengine.html#api_enablelocalvideo)(`false`) method, which controls the sending of the local video stream. +- This method does not affect any ongoing video recording, because it does not disable the camera. + +### Parameters + +- mute + + Whether to stop publishing the local video stream.`true`: Stop publishing the local video stream.`false`: (Default) Publish the local video stream. + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [onUserMuteVideo](../API/class_irtcengineeventhandler.html#callback_onusermutevideo) + +## [muteRecordingSignal](class_irtcengine.html#api_muterecordingsignal) + +Whether to mute the recording signal. + +```cpp +virtual int muteRecordingSignal(bool mute) = 0; +``` + +### Parameters + +- mute + + `true`: Mute the recording signal.`false`: (Default) Unmute the recording signal. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [muteRemoteAudioStream](class_irtcengine.html#api_muteremoteaudiostream) + +Stops or resumes subscribing to the audio stream of a specified user. + +```cpp +virtual int muteRemoteAudioStream(uid_t uid, bool mute) = 0; +``` + +**Note** + +- Call this method after joining a channel. +- See recommended settings in Set the Subscribing State. + +### Parameters + +- uid + + The user ID of the specified user. + +- mute + + Whether to stop subscribing to the audio stream of the specified user.`true`: Stop subscribing to the audio stream of the specified user.`false`: (Default) Subscribe to the audio stream of the specified user. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [muteRemoteVideoStream](class_irtcengine.html#api_muteremotevideostream) + +Stops or resumes subscribing to the video stream of a specified user. + +```cpp +virtual int muteRemoteVideoStream(uid_t userId, bool mute) = 0; +``` + +**Note** + +- Call this method after joining a channel. +- See recommended settings in Set the Subscribing State. + +### Parameters + +- mute + + Whether to stop subscribing to the video stream of the specified user.`true`: Stop subscribing to the video streams of the specified user.`false`: (Default) Subscribe to the video stream of the specified user. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [pauseAllChannelMediaRelay](class_irtcengine.html#api_pauseallchannelmediarelay) + +Pauses the media stream relay to all destination channels. + +```cpp +virtual int pauseAllChannelMediaRelay() = 0; +``` + +After the cross-channel media stream relay starts, you can call this method to pause relaying media streams to all destination channels; after the pause, if you want to resume the relay, call [resumeAllChannelMediaRelay](class_irtcengine.html#api_resumeallchannelmediarelay). + +After a successful method call, the SDK triggers the [onChannelMediaRelayEvent](class_irtcengineeventhandler.html#callback_onchannelmediarelayevent) callback to report whether the media stream relay is successfully paused. + +**Note** Call this method after [startChannelMediaRelay](class_irtcengine.html#api_startchannelmediarelay). + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [onChannelMediaRelayEvent](../API/class_irtcengineeventhandler.html#callback_onchannelmediarelayevent) + +## [pauseAllEffects](class_irtcengine.html#api_pausealleffects) + +Pauses all audio effects. + +```cpp +virtual int pauseAllEffects() = 0; +``` + +### Returns + +- 0: Success. +- < 0: Failure. + +## [pauseAudioMixing](class_irtcengine.html#api_pauseaudiomixing) + +Pauses playing and mixing the music file. + +```cpp +virtual int pauseAudioMixing() = 0; +``` + +Call this method when you are in a channel. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [pauseEffect](class_irtcengine.html#api_pauseeffect) + +Pauses a specified audio effect. + +```cpp +virtual int pauseEffect(int soundId) = 0; +``` + +### Parameters + +- soundId + + The audio effect ID. The ID of each audio effect file is unique. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [playAllEffects](class_irtcengine.html#api_playalleffects) + +Plays all audio effects. + +```cpp +virtual int playAllEffects(int loopCount, double pitch, double pan, int gain, bool publish = false) = 0; +``` + +After calling [preloadEffect](class_irtcengine.html#api_preloadeffect) multiple times to preload multiple audio effects into the memory, you can call this method to play all the specified audio effects for all users in the channel. + +### Parameters + +- loopCount + + The number of times the audio effect loops:-1: Play the audio effect in an indefinite loop until you call [stopEffect](class_irtcengine.html#api_stopeffect) or [stopAllEffects](class_irtcengine.html#api_stopalleffects).0: Play the audio effect once.1: Play the audio effect twice. + +- pitch + + The pitch of the audio effect. The value ranges between 0.5 and 2.0. The default value is 1.0 (original pitch). The lower the value, the lower the pitch. + +- pan + + The spatial position of the audio effect. The value ranges between -1.0 and 1.0:-1.0: The audio effect shows on the left.0: The audio effect shows ahead.1.0: The audio effect shows on the right. + +- gain + + The volume of the audio effect. The value ranges from 0 to 100. The default value is 100 (original volume). The smaller the value, the less the gain. + +- publish + + Whether to publish the audio effect to the remote users:`true`: Publish the audio effect to the remote users. Both the local user and remote users can hear the audio effect.`false`: Do not publish the audio effect to the remote users. Only the local user can hear the audio effect. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [playEffect](class_irtcengine.html#api_playeffect3) + +Plays the specified local or online audio effect file. + +```cpp +virtual int playEffect(int soundId, + const char* filePath, + int loopCount, + double pitch, + double pan, + int gain, + bool publish, + int startPos) = 0; +``` + +To play multiple audio effect files at the same time, call this method multiple times with different **soundId** and **filePath**. For the best user experience, Agora recommends playing no more than three audio effect files at the same time. After the playback of an audio effect file completes, the SDK triggers the onAudioEffectFinished callback. + +**Note** Call this method after joining a channel. + +### Parameters + +- soundId + + The audio effect ID. The ID of each audio effect file is unique.**Note** If you have preloaded an audio effect into memory by calling [preloadEffect](class_irtcengine.html#api_preloadeffect), ensure that this parameter is set to the same value as **soundId** in preloadEffect. + +- filePath + + The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example: `C:\music\audio.mp4`. Supported audio formats include MP3, AAC, M4A, MP4, WAV, and 3GP. See [supported audio formats](https://docs.microsoft.com/en-us/windows/win32/medfound/supported-media-formats-in-media-foundation).**Note** If you have preloaded an audio effect into memory by calling [preloadEffect](class_irtcengine.html#api_preloadeffect), ensure that this parameter is set to the same value as **filePath** in preloadEffect. + +- loopCount + + The number of times the audio effect loops:≥ 0: The number of playback times. For example, 1 means loop one time, which means play the audio effect two times in total.-1: Play the music effect in an infinite loop. + +- pitch + + The pitch of the audio effect. The value range is 0.5 to 2.0. The default value is 1.0, which means the original pitch. The lower the value, the lower the pitch. + +- pan + + The spatial position of the audio effect. The value range is 1 to10000.-1.0: The audio effect displays to the left.0.0: The audio effect displays ahead.1.0: The audio effect displays to the right. + +- gain + + The volume of the audio effect. The value range is 1 to10000. The default value is 100.0, which means the original volume. The smaller the value, the lower the volume. + +- publish + + Whether to publish the audio effect to the remote users.`true`: Publish the audio effect to the remote users. Both the local user and remote users can hear the audio effect.`false`: Do not publish the audio effect to the remote users. Only the local user can hear the audio effect. + +- startPos + + The playback position (ms) of the audio effect file. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [preloadEffect](class_irtcengine.html#api_preloadeffect) + +Preloads a specified audio effect file into the memory. + +```cpp +virtual int preloadEffect(int soundId, const char* filePath) = 0; +``` + +To ensure smooth communication, limit the size of the audio effect file. We recommend using this method to preload the audio effect before calling joinChannel [2/2]. + +**Note** + +- This method does not support online audio effect files. +- For the audio file formats supported by this method, see [What formats of audio files does the Agora RTC SDK support](https://docs.agora.io/en/faq/audio_format). + +### Parameters + +- soundId + + The audio effect ID. The ID of each audio effect file is unique. + +- filePath + + File path:Android: The file path, which needs to be accurate to the file name and suffix. Agora supports using a URI address, an absolute path, or a path that starts with /assets/. You might encounter permission issues if you use an absolute path to access a local file, so Agora recommends using a URI address instead. For example: content://com.android.providers.media.documents/document/audio%203A14441Windows: The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example: C:\music\audio.mp4. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [queryInterface](class_irtcengine.html#api_queryinterface) + +Gets the pointer to the specified interface. + +```cpp +virtual int queryInterface(INTERFACE_ID_TYPE iid, void** inter) = 0; +``` + +### Parameters + +- iid + + The ID of the interface. See [INTERFACE_ID_TYPE](rtc_api_data_type.html#enum_interfaceidtype) for details. + +- inter + + Output parameter. The pointer to the specified interface. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [rate](class_irtcengine.html#api_rate) + +Allows a user to rate a call after the call ends. + +```cpp +virtual int rate(const char* callId, + int rating, + const char* description) = 0; +``` + +**Note** Ensure that you call this method after leaving a channel. + +### Parameters + +- callId + + The current call ID. You can get the call ID by calling [getCallId](class_irtcengine.html#api_getcallid). + +- rating + + The rating of the call. The value is between 1 (lowest score) and 5 (highest score). If you set a value out of this range, the SDK returns the -2 (`ERR_INVALID_ARGUMENT`) error. + +- description + + (Optional) A description of the call. The string length should be less than 800 bytes. + +### Returns + +- 0: Success. +- < 0: Failure. + - -2 (`ERR_INVALID_ARGUMENT`). + - -3 (`ERR_NOT_READY`)。 + +## [registerAudioEncodedFrameObserver](class_irtcengine.html#api_registeraudioencodedframeobserver) + +Registers an encoded audio observer. + +```cpp +virtual int registerAudioEncodedFrameObserver(const AudioEncodedFrameObserverConfig& config, IAudioEncodedFrameObserver *observer) = 0; +``` + +**Note** + +- Call this method after joining a channel. +- This method and [startAudioRecording](class_irtcengine.html#api_startaudiorecording3_ng) both set the audio content and audio quality. Agora recommends not using this method and startAudioRecording together; otherwise, only the method called later will take effect. + +### Parameters + +- config + + Observer settings for the encoded audio. For details, see [AudioEncodedFrameObserverConfig](rtc_api_data_type.html#class_audioencodedframeobserverconfig). + +- observer + + The encoded audio observer. For details, see [IAudioEncodedFrameObserver](class_iaudioencodedframeobserver.html#class_iaudioencodedframeobserver). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [registerAudioSpectrumObserver](class_irtcengine.html#api_registeraudiospectrumobserver) + +Register an audio spectrum observer. + +```cpp +virtual int registerAudioSpectrumObserver(agora::media::IAudioSpectrumObserver * observer) = 0; +``` + +After successfully registering the audio spectrum observer and calling [enableAudioSpectrumMonitor](class_irtcengine.html#api_enableaudiospectrummonitor) to enable the audio spectrum monitoring, the SDK reports the callback that you implement in the [IAudioSpectrumObserver](class_iaudiospectrumobserver.html#class_iaudiospectrumobserver) class at the time interval you set. + +**Note** You can call this method either before or after joining a channel. + +### Parameters + +- observer + + The Audio spectrum observer. For details, see [IAudioSpectrumObserver](class_iaudiospectrumobserver.html#class_iaudiospectrumobserver). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [registerLocalUserAccount](class_irtcengine.html#api_registerlocaluseraccount) + +Registers a user account. + + + +```cpp +virtual int registerLocalUserAccount(const char* appId, const char* userAccount) = 0; +``` + +Once registered, the user account can be used to identify the local user when the user joins the channel. After the registration is successful, the user account can identify the identity of the local user, and the user can use it to join the channel. + +After the user successfully registers a user account, the SDK triggers the [onLocalUserRegistered](class_irtcengineeventhandler.html#callback_onlocaluserregistered) callback on the local client, reporting the user ID and user account of the local user. + +This method is optional. To join a channel with a user account, you can choose either of the following ways: + +- Call registerLocalUserAccount to to create a user account, and then call [joinChannelWithUserAccount [2/2\]](class_irtcengine.html#api_joinchannelwithuseraccount2) to join the channel. +- Call the joinChannelWithUserAccount [2/2] method to join the channel. + +The difference between the two ways is that the time elapsed between calling the registerLocalUserAccount method and joining the channel is shorter than directly calling joinChannelWithUserAccount [2/2]. + +**Note** + +- Ensure that you set the **userAccount** parameter; otherwise, this method does not take effect. +- Ensure that the **userAccount** 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 ID of the user is set to the same parameter type. + +### Parameters + +- appId + + The App ID of your project on Agora Console. + +- userAccount + + The user account. This parameter is used to identify the user in the channel for real-time audio and video engagement. You need to set and manage user accounts yourself and ensure that each user account in the same channel is unique. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as NULL. Supported characters are (89 in total):The 26 lowercase English letters: a to z.The 26 uppercase English letters: A to Z.All numeric characters: 0 to 9.Space"!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", "," + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [onLocalUserRegistered](../API/class_irtcengineeventhandler.html#callback_onlocaluserregistered) + +## [registerMediaMetadataObserver](class_irtcengine.html#api_registermediametadataobserver) + +Registers the metadata observer. + +```cpp +virtual int registerMediaMetadataObserver(IMetadataObserver *observer, IMetadataObserver::METADATA_TYPE type) = 0; +``` + +You need to implement the [IMetadataObserver](class_imetadataobserver.html#class_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](class_imetadataobserver.html#callback_imetadataobserver_getmaxmetadatasize) callback. + +**Note** + +- Call this method before joinChannel [2/2]. +- This method applies only to interactive live streaming. + +### Parameters + +- observer + + The metadata observer. See [IMetadataObserver](class_imetadataobserver.html#class_imetadataobserver). + +- type + + The metadata type. The SDK currently only supports VIDEO_METADATA. See [METADATA_TYPE](class_imetadataobserver.html#enum_metadatatype). + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [getMaxMetadataSize](../API/class_imetadataobserver.html#callback_imetadataobserver_getmaxmetadatasize) + +## [registerPacketObserver](class_irtcengine.html#api_registerpacketobserver) + +Registers a packet observer. + +```cpp +virtual int registerPacketObserver(IPacketObserver* observer) = 0; +``` + +Call this method registers a packet observer. When the Agora SDK triggers callbacks registered by [IPacketObserver](class_ipacketobserver.html#class_ipacketobserver) for voice or video packet transmission, you can call this method to process the packets, such as encryption and decryption. + +**Note** + +- The size of the packet sent to the network after processing should not exceed 1200 bytes, otherwise, the SDK may fail to send the packet. +- Ensure that both receivers and senders call this method, otherwise, you may meet undefined behaviors such as no voice and black screen. +- When you use CDN live streaming, recording, or storage functions, Agora doesn't recommend calling this method. +- Call this method before joining a channel. + +### Parameters + +- observer + + [IPacketObserver](class_ipacketobserver.html#class_ipacketobserver) . + +### Returns + +- 0: Success. +- < 0: Failure. + +## [release](class_irtcengine.html#api_release) + +Releases the IRtcEngine instance. + +```cpp +virtual void release(bool sync = false) = 0; +``` + + + +This method releases all resources used by the Agora SDK. Use this method for apps in which users occasionally make voice or video calls. When users do not make calls, you can free up resources for other operations. + +After a successful method call, you can no longer use any method or callback in the SDK anymore. If you want to use the real-time communication functions again, you must call [createAgoraRtcEngine](class_irtcengine.html#api_createagorartcengine) and [initialize](class_irtcengine.html#api_create2) to create a new IRtcEngine instance. + +**Note** If you want to create a new IRtcEngine instance after destroying the current one, ensure that you wait till the release method execution to complete. + +### Parameters + +- sync + + `true`: Synchronous call. Agora suggests calling this method in a sub-thread to avoid congestion in the main thread because the synchronous call and the app cannot move on to another task until the resources used by IRtcEngine are released. Besides, you cannot call release in any method or callback of the SDK. Otherwise, the SDK cannot release the resources until the callbacks return results, which may result in a deadlock. The SDK automatically detects the deadlock and converts this method into an asynchronous call, causing the test to take additional time.`false`: Asynchronous call. The app can move on to another task, no matter the resources used by IRtcEngine are released or not. Do not immediately uninstall the SDK's dynamic library after the call; otherwise, it may cause a crash due to the SDK clean-up thread not quitting. + +## [removePublishStreamUrl](class_irtcengine.html#api_removepublishstreamurl) + +Removes an RTMP or RTMPS stream from the CDN. + +```cpp +virtual int removePublishStreamUrl(const char *url) = 0; +``` + +After a successful method call, the SDK triggers [onRtmpStreamingStateChanged](class_irtcengineeventhandler.html#callback_onrtmpstreamingstatechanged) on the local client to report the result of deleting the address. + +**Note** + +- Ensure that you enable the RTMP Converter service before using this function. +- This method takes effect only when you are a host in live interactive streaming. +- Call this method after joining a channel. +- This method removes only one CDN streaming URL each time it is called. To remove multiple URLs, call this method multiple times. + +### Parameters + +- url + + The CDN streaming URL to be removed. The maximum length of this parameter is 1024 bytes. The CDN streaming URL must not contain special characters, such as Chinese characters. + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [onRtmpStreamingStateChanged](../API/class_irtcengineeventhandler.html#callback_onrtmpstreamingstatechanged) + +## [renewToken](class_irtcengine.html#api_renewtoken) + +Gets a new token when the current token expires after a period of time. + +```cpp +virtual int renewToken(const char* token) = 0; +``` + +Passes a new token to the SDK. A token expires after a certain period of time. In the following two cases, the app should call this method to pass in a new token. Failure to do so will result in the SDK disconnecting from the server. + +- The SDK triggers the [onTokenPrivilegeWillExpire](class_irtcengineeventhandler.html#callback_ontokenprivilegewillexpire) callback. +- The [onConnectionStateChanged](class_irtcengineeventhandler.html#callback_onconnectionstatechanged) callback reports CONNECTION_CHANGED_TOKEN_EXPIRED(9). + +### Parameters + +- token + + The new token. + +### Returns + +- 0(ERR_OK): Success. +- < 0: Failure. + - -1(ERR_FAILED): A general error occurs (no specified reason). + - -2 (ERR_INVALID_ARGUMENT): The parameter is invalid. + - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. + +**See also** + +- [onTokenPrivilegeWillExpire](../API/class_irtcengineeventhandler.html#callback_ontokenprivilegewillexpire) +- [onConnectionStateChanged](../API/class_irtcengineeventhandler.html#callback_onconnectionstatechanged) + +## [resumeAllChannelMediaRelay](class_irtcengine.html#api_resumeallchannelmediarelay) + +Resumes the media stream relay to all destination channels. + +```cpp +virtual int resumeAllChannelMediaRelay() = 0; +``` + +After calling the [pauseAllChannelMediaRelay](class_irtcengine.html#api_pauseallchannelmediarelay) method, you can call this method to resume relaying media streams to all destination channels. + +After a successful method call, the SDK triggers the [onChannelMediaRelayEvent](class_irtcengineeventhandler.html#callback_onchannelmediarelayevent) callback to report whether the media stream relay is successfully resumed. + +**Note** Call this method after the [pauseAllChannelMediaRelay](class_irtcengine.html#api_pauseallchannelmediarelay) method. + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [onChannelMediaRelayEvent](../API/class_irtcengineeventhandler.html#callback_onchannelmediarelayevent) + +## [resumeAllEffects](class_irtcengine.html#api_resumealleffects) + +Resumes playing all audio effects. + +```cpp +virtual int resumeAllEffects() = 0; +``` + +### Returns + +- 0: Success. +- < 0: Failure. + +## [resumeAudioMixing](class_irtcengine.html#api_resumeaudiomixing) + +Resumes playing and mixing the music file. + +```cpp +virtual int resumeAudioMixing() = 0; +``` + +This method resumes playing and mixing the music file. Call this method when you are in a channel. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [resumeEffect](class_irtcengine.html#api_resumeeffect) + +Resumes playing a specified audio effect. + +```cpp +virtual int resumeEffect(int soundId) = 0; +``` + +### Parameters + +- soundId + + The audio effect ID. The ID of each audio effect file is unique. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [sendCustomReportMessage](class_irtcengine.html#api_sendcustomreportmessage) + +Reports customized messages. + +```cpp +virtual int sendCustomReportMessage(const char *id, + const char* category, + const char* event, + const char* label, + int value) = 0; +``` + +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 and each string not exceeding 100 bytes. To try out this function, contact [support@agora.io](mailto:support@agora.io) and discuss the format of customized messages with us. + +## [sendStreamMessage](class_irtcengine.html#api_sendstreammessage) + +Sends data stream messages. + +```cpp +virtual int sendStreamMessage(int streamId, + const char* data, + size_t length) = 0; +``` + +Sends data stream messages to all users in a channel. The SDK has the following restrictions on this method: + +- Up to 30 packets can be sent per second in a channel with each packet having a maximum size of 1 KB. +- Each client can send up to 6 KB of data per second. +- Each user can have up to five data streams simultaneously. + +A successful method call triggers the [onStreamMessage](class_irtcengineeventhandler.html#callback_onstreammessage) callback on the remote client, from which the remote user gets the stream message. A failed method call triggers the [onStreamMessageError](class_irtcengineeventhandler.html#callback_onstreammessageerror) callback on the remote client. + +**Note** + +- Ensure that you call [createDataStream [2/2\]](class_irtcengine.html#api_createdatastream2) to create a data channel before calling this method. +- In live streaming scenarios, this method only applies to hosts. + +### Parameters + +- streamId + + The data stream ID. You can get the data stream ID by calling createDataStream [2/2]. + +- data + + The message to be sent. + +- length + + The length of the data. + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [onStreamMessage](../API/class_irtcengineeventhandler.html#callback_onstreammessage) +- [onStreamMessageError](../API/class_irtcengineeventhandler.html#callback_onstreammessageerror) + +## [setAudioEffectParameters](class_irtcengine.html#api_setaudioeffectparameters) + +Sets parameters for SDK preset audio effects. + +```cpp +virtual int setAudioEffectParameters(AUDIO_EFFECT_PRESET preset, int param1, int param2) = 0; +``` + +### Detailed Description + +Call this method to set the following parameters for the local user who sends an audio stream: + +- 3D voice effect: Sets the cycle period of the 3D voice effect. +- Pitch correction effect: Sets the basic mode and tonic pitch of the pitch correction effect. Different songs have different modes and tonic pitches. Agora recommends bounding this method with interface elements to enable users to adjust the pitch correction interactively. + +After setting the audio parameters, all users in the channel can hear the effect. + +**Note** + +- You can call this method either before or after joining a channel. + +- To get better audio effect quality, Agora recommends calling and setting **scenario** in [setAudioProfile [1/2\]](class_irtcengine.html#api_setaudioprofile) as AUDIO_SCENARIO_GAME_STREAMING(3) before calling this method. + +- Do not set the **profile** parameter in setAudioProfile [1/2] to AUDIO_PROFILE_SPEECH_STANDARD (1) or AUDIO_PROFILE_IOT(6), or the method does not take effect. + +- This method works best with the human voice. Agora does not recommend using this method for audio containing music. + +- After calling + + + + setAudioEffectParameters + + , Agora recommends not calling the following methods, or the settings in + + + + setAudioEffectParameters + + + + are overridden : + + - [setAudioEffectPreset](class_irtcengine.html#api_setaudioeffectpreset) + - [setVoiceBeautifierPreset](class_irtcengine.html#api_setvoicebeautifierpreset) + - [setLocalVoiceReverbPreset](class_irtcengine.html#api_setlocalvoicereverbpreset) + - [setLocalVoiceChanger](class_irtcengine.html#api_setlocalvoicechanger) + - [setLocalVoicePitch](class_irtcengine.html#api_setlocalvoicepitch) + - [setLocalVoiceEqualization](class_irtcengine.html#api_setlocalvoiceequalization) + - [setLocalVoiceReverb](class_irtcengine.html#api_setlocalvoicereverb) + - [setVoiceBeautifierParameters](class_irtcengine.html#api_setvoicebeautifierparameters) + - [setVoiceConversionPreset](class_irtcengine.html#api_setvoiceconversionpreset) + +### Parameters + +- preset + + The options for SDK preset audio effects:ROOM_ACOUSTICS_3D_VOICE, 3D voice effect:Call and set the **profile** parameter in setAudioProfile [1/2] to AUDIO_PROFILE_MUSIC_STANDARD_STEREO (3) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5) before setting this enumerator; otherwise, the enumerator setting does not take effect.If the 3D voice effect is enabled, users need to use stereo audio playback devices to hear the anticipated voice effect.PITCH_CORRECTION, Pitch correction effect: To achieve better audio effect quality, Agora recommends calling setAudioProfile [1/2] and setting the **profile** parameter to AUDIO_PROFILE_MUSIC_HIGH_QUALITY (4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5) before setting this enumerator. + +- param1 + + If you set **preset** to ROOM_ACOUSTICS_3D_VOICE , **param1** sets the cycle period of the 3D voice effect. The value range is [1,60] and the unit is seconds. The default value is 10, indicating that the voice moves around you every 10 seconds.If you set **preset** to PITCH_CORRECTION , **param1** sets the basic mode of the pitch correction effect:`1`: (Default) Natural major scale.`2`: Natural minor scale.`3`: Japanese pentatonic scale. + +- param2 + + If you set **preset** to ROOM_ACOUSTICS_3D_VOICE, you need to set **param2** to `0`.If you set **preset** to PITCH_CORRECTION, **param2** sets the tonic pitch of the pitch correction effect:`1`: A`2`: A#`3`: B`4`: (Default) C`5`: C#`6`: D`7`: D#`8`: E`9`: F`10`: F#`11`: G`12`: G# + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setAudioEffectPreset](class_irtcengine.html#api_setaudioeffectpreset) + +Sets an SDK preset audio effect. + +```cpp +virtual int setAudioEffectPreset(AUDIO_EFFECT_PRESET preset) = 0; +``` + +### Detailed Description + +Call this method to set an SDK preset audio effect for the local user who sends an audio stream. This audio effect does not change the gender characteristics of the original voice. After setting an audio effect, all users in the channel can hear the effect. + +To get better audio effect quality, Agora recommends calling [setAudioProfile [1/2\]](class_irtcengine.html#api_setaudioprofile) and setting the **scenario** parameter as 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 in setAudioProfile [1/2] to AUDIO_PROFILE_SPEECH_STANDARD (1) or AUDIO_PROFILE_IOT(6), or the method does not take effect. + +- Do not set the **profile** parameter in setAudioProfile [1/2] to AUDIO_PROFILE_SPEECH_STANDARD (1), or the method does not take effect. + +- This method works best with the human voice. Agora does not recommend using this method for audio containing music. + +- If you call setAudioEffectPreset and set enumerators except for ROOM_ACOUSTICS_3D_VOICE or PITCH_CORRECTION, do not call [setAudioEffectParameters](class_irtcengine.html#api_setaudioeffectparameters); otherwise, setAudioEffectPreset is overridden. + +- After calling + + + + setAudioEffectPreset + + , Agora recommends not calling the following methods, because they can override + + + + setAudioEffectPreset + + : + + - [setVoiceBeautifierPreset](class_irtcengine.html#api_setvoicebeautifierpreset) + - [setLocalVoiceReverbPreset](class_irtcengine.html#api_setlocalvoicereverbpreset) + - [setLocalVoiceChanger](class_irtcengine.html#api_setlocalvoicechanger) + - [setLocalVoicePitch](class_irtcengine.html#api_setlocalvoicepitch) + - [setLocalVoiceEqualization](class_irtcengine.html#api_setlocalvoiceequalization) + - [setLocalVoiceReverb](class_irtcengine.html#api_setlocalvoicereverb) + - [setVoiceBeautifierParameters](class_irtcengine.html#api_setvoicebeautifierparameters) + - [setVoiceConversionPreset](class_irtcengine.html#api_setvoiceconversionpreset) + +### Parameters + +- preset + + The options for SDK preset audio effects. See [AUDIO_EFFECT_PRESET](rtc_api_data_type.html#enum_audioeffectpreset). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setAudioMixingPosition](class_irtcengine.html#api_setaudiomixingposition) + +Sets the audio mixing position. + +```cpp +virtual int setAudioMixingPosition(int pos /*in ms*/) = 0; +``` + +Call this method to set the playback position of the music file to a different starting position (the default plays from the beginning). + +**Note** You need to call this method after calling startAudioMixing [2/2] and receiving the onAudioMixingStateChanged(`PLAY`) callback. + +### Parameters + +- pos + + Integer. The playback position (ms). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setAudioProfile [1/2\]](class_irtcengine.html#api_setaudioprofile) + +Sets the audio profile and audio scenario. + +```cpp +virtual int setAudioProfile(AUDIO_PROFILE_TYPE profile, AUDIO_SCENARIO_TYPE scenario) = 0; +``` + +**Note** + +- You can call this method either before or after joining a channel. +- In scenarios requiring high-quality audio, such as online music tutoring, Agora recommends you set **profile** as AUDIO_PROFILE_MUSIC_HIGH_QUALITY (4), and **scenario** as AUDIO_SCENARIO_GAME_STREAMING (3) or AUDIO_SCENARIO_HIGH_DEFINITION(6). + +### Parameters + +- profile + + The audio profile, including the sampling rate, bitrate, encoding mode, and the number of channels. See [AUDIO_PROFILE_TYPE](rtc_api_data_type.html#enum_audioprofiletype). + +- scenario + + The audio scenario. See [AUDIO_SCENARIO_TYPE](rtc_api_data_type.html#enum_audioscenariotype_ng). Under different audio scenarios, the device uses different volume types. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setAudioProfile [2/2\]](class_irtcengine.html#api_setaudioprofile2) + +Sets the audio parameters and application scenarios. + +```cpp +virtual int setAudioProfile(AUDIO_PROFILE_TYPE profile) = 0; +``` + +**Note** + +- You can call this method either before or after joining a channel. +- In scenarios requiring high-quality audio, such as online music tutoring, Agora recommends you set `profile` as `AUDIO_PROFILE_MUSIC_HIGH_QUALITY (4)`. +- If you want to set the audio scenario, call [initialize](class_irtcengine.html#api_create2) and set **audioScenario** in the [RtcEngineContext](rtc_api_data_type.html#class_rtcengineconfig_ng) struct. + +### Parameters + +- profile + + The audio profile, including the sampling rate, bitrate, encoding mode, and the number of channels. See [AUDIO_PROFILE_TYPE](rtc_api_data_type.html#enum_audioprofiletype). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setBeautyEffectOptions](class_irtcengine.html#api_setbeautyeffectoptions) + +Sets the image enhancement options. + +```cpp +virtual int setBeautyEffectOptions(bool enabled, BeautyOptions options) = 0; +``` + +Enables or disables image enhancement, and sets the options. + +Enabling the image enhancement function involves a series of method calls. The calling sequence is as follows: + +1. Call `loadExtensionProvider(libagora_video_process_extension.dll)` during [IRtcEngine](class_irtcengine.html#class_irtcengine) initialization to specify the extension's library path. +2. Call `enableExtension(agora, beauty, true)` to enable the extension. +3. Call [enableVideo](class_irtcengine.html#api_enablevideo) to enable the video module. +4. Call this method to enable the image enhancement function. + +### Parameters + +- enabled + + Whether to enable the image enhancement function:`true`: Enable the image enhancement function.`false`: (Default) Disable the image enhancement function. + +- options + + The image enhancement options. See [BeautyOptions](rtc_api_data_type.html#class_beautyoptions). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setCameraAutoFocusFaceModeEnabled](class_irtcengine.html#api_setcameraautofocusfacemodeenabled) + +Enables the camera auto-face focus function. + +```cpp +virtual int setCameraAutoFocusFaceModeEnabled(bool enabled) = 0; +``` + +**Note** + +- This method is for Android and iOS only. +- Call this method before calling [joinChannel [2/2\]](class_irtcengine.html#api_joinchannel2_ng), [enableVideo](class_irtcengine.html#api_enablevideo), or [enableLocalVideo](class_irtcengine.html#api_enablelocalvideo), depending on which method you use to turn on your local camera. + +### Parameters + +- enabled + + Whether to enable the camera auto-face focus function:`true`: Enable the camera auto-face focus function.`false`: (Default) Disable the camera auto-face focus function. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setCameraCapturerConfiguration](class_irtcengine.html#api_setcameracapturerconfiguration) + +Sets the camera capture configuration. + +```cpp +virtual int setCameraCapturerConfiguration(const CameraCapturerConfiguration& config) = 0; +``` + +**Note** + +- This method is for Android and iOS only. +- Call this method before calling [joinChannel [2/2\]](class_irtcengine.html#api_joinchannel2_ng), [enableVideo](class_irtcengine.html#api_enablevideo), or [enableLocalVideo](class_irtcengine.html#api_enablelocalvideo), depending on which method you use to turn on your local camera. + +### Parameters + +- config + + The camera capturer configuration. See [CameraCapturerConfiguration](rtc_api_data_type.html#class_cameracapturerconfiguration_ng). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setCameraDeviceOrientation](class_irtcengine.html#api_setcameradeviceorientation) + +Sets the rotation angle of the captured video. + +```cpp +virtual int setCameraDeviceOrientation(VIDEO_SOURCE_TYPE type, VIDEO_ORIENTATION orientation) = 0; +``` + +When the video 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](rtc_api_data_type.html#enum_videosourcetype). + +- orientation + + The clockwise rotation angle. See [VIDEO_ORIENTATION](rtc_api_data_type.html#enum_videoorientation). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setCameraExposurePosition](class_irtcengine.html#api_setcameraexposureposition) + +Sets the camera exposure position. + +```cpp +virtual int setCameraExposurePosition(float positionXinView, float positionYinView) = 0; +``` + +This method needs to be called after the camera is started (for example, by calling [startPreview](class_irtcengine.html#api_startpreview) or [joinChannel [2/2\]](class_irtcengine.html#api_joinchannel2_ng)). + +After a successful method call, the SDK triggers the [onCameraExposureAreaChanged](class_irtcengineeventhandler.html#callback_oncameraexposureareachanged) callback. + +**Note** This method is for Android and iOS only. + +### Parameters + +- positionXinView + + The horizontal coordinate of the touchpoint in the view. + +- positionYinView + + The vertical coordinate of the touchpoint in the view. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setCameraFocusPositionInPreview](class_irtcengine.html#api_setcamerafocuspositioninpreview) + +Sets the camera manual focus position. + +```cpp +virtual int setCameraFocusPositionInPreview(float positionX, float positionY) = 0; +``` + +This method needs to be called after the camera is started (for example, by calling [startPreview](class_irtcengine.html#api_startpreview) or [joinChannel [2/2\]](class_irtcengine.html#api_joinchannel2_ng)). After a successful method call, the SDK triggers the [onCameraFocusAreaChanged](class_irtcengineeventhandler.html#callback_oncamerafocusareachanged) callback. + +**Note** This method is for Android and iOS only. + +### Parameters + +- positionX + + The horizontal coordinate of the touchpoint in the view. + +- positionY + + The vertical coordinate of the touchpoint in the view. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setCameraTorchOn](class_irtcengine.html#api_setcameratorchon) + +Enables the camera flash. + +```cpp +virtual int setCameraTorchOn(bool isOn) = 0; +``` + +**Note** + +- This method is for Android and iOS only. +- Call this method before calling [joinChannel [2/2\]](class_irtcengine.html#api_joinchannel2_ng), [enableVideo](class_irtcengine.html#api_enablevideo), or [enableLocalVideo](class_irtcengine.html#api_enablelocalvideo), depending on which method you use to turn on your local camera. + +### Parameters + +- isOn + + Whether to turn on the camera flash:`true`: Turn on the flash.`false`: (Default) Turn off the flash. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setCameraZoomFactor](class_irtcengine.html#api_setcamerazoomfactor) + +Sets the camera zoom ratio. + +```cpp +virtual int setCameraZoomFactor(float factor) = 0; +``` + +**Note** + +- This method is for Android and iOS only. +- Call this method before calling [joinChannel [2/2\]](class_irtcengine.html#api_joinchannel2_ng), [enableVideo](class_irtcengine.html#api_enablevideo), or [enableLocalVideo](class_irtcengine.html#api_enablelocalvideo), depending on which method you use to turn on your local camera. + +### Parameters + + + +### Returns + +- The camera zoom **factor** value, if successful. +- < 0: if the method if failed. + +## [setChannelProfile](class_irtcengine.html#api_setchannelprofile) + +Sets the channel profile. + +```cpp +virtual int setChannelProfile(CHANNEL_PROFILE_TYPE profile) = 0; +``` + +Sets the profile of the Agora channel. The Agora SDK differentiates channel profiles and applies optimization algorithms accordingly. For example, it prioritizes smoothness and low latency for a video call and prioritizes video quality for interactive live video streaming. + +**Note** + +- To ensure the quality of real-time communication, Agora recommends that all users in a channel use the same channel profile. +- This method must be called and set before joinChannel [2/2], and cannot be set again after entering the channel. +- The default audio route and video encoding bitrate are different in different channel profiles. For details, see [setDefaultAudioRouteToSpeakerphone](class_irtcengine.html#api_setdefaultaudioroutetospeakerphone_ng) and [setVideoEncoderConfiguration](class_irtcengine.html#api_setvideoencoderconfiguration). + +### Parameters + +- profile + + The channel profile. For details, see [CHANNEL_PROFILE_TYPE](rtc_api_data_type.html#enum_channelprofiletype_ng). + +### Returns + +- 0(ERR_OK): Success. +- < 0: Failure. + - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. + - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. + +## [setClientRole [1/2\]](class_irtcengine.html#api_setclientrole) + +Sets the client role. + +```cpp +virtual int setClientRole(CLIENT_ROLE_TYPE role) = 0; +``` + +You can call this method either before or after joining the channel to set the user role as audience or host. + +If you call this method to switch the user role after joining the channel, the SDK triggers the following callbacks: + +- The local client: [onClientRoleChanged](class_irtcengineeventhandler.html#callback_onclientrolechanged). +- The remote client: [onUserJoined](class_irtcengineeventhandler.html#callback_onuserjoined) or [onUserOffline](class_irtcengineeventhandler.html#callback_onuseroffline) (USER_OFFLINE_BECOME_AUDIENCE). + +### Parameters + +- role + + The user role. For details, see [CLIENT_ROLE_TYPE](rtc_api_data_type.html#enum_clientroletype). + +### 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. + +**See also** + +- [onClientRoleChanged](../API/class_irtcengineeventhandler.html#callback_onclientrolechanged) +- [onUserJoined](../API/class_irtcengineeventhandler.html#callback_onuserjoined) +- [onUserOffline](../API/class_irtcengineeventhandler.html#callback_onuseroffline) + +## [setClientRole [2/2\]](class_irtcengine.html#api_setclientrole2) + +Sets the user role and level in an interactive live streaming channel. + +```cpp +virtual int setClientRole(CLIENT_ROLE_TYPE role, const ClientRoleOptions& options) = 0; +``` + +In the interactive live streaming profile, the SDK sets the user role as audience by default. You can call this method to set the user role as host. + +You can call this method either before or after joining a channel. If you call this method to switch the user role after joining a channel, the SDK automatically does the following: + +- Calls [muteLocalAudioStream](class_irtcengine.html#api_mutelocalaudiostream) and [muteLocalVideoStream](class_irtcengine.html#api_mutelocalvideostream) to change the publishing state. +- Triggers [onClientRoleChanged](class_irtcengineeventhandler.html#callback_onclientrolechanged) on the local client. +- Triggers [onUserJoined](class_irtcengineeventhandler.html#callback_onuserjoined) or [onUserOffline](class_irtcengineeventhandler.html#callback_onuseroffline) on the remote client. + +The difference between this method and [setClientRole [1/2\]](class_irtcengine.html#api_setclientrole) is that this method can set the user level in addition to the user role. + +- The user role (**role**) determines the permissions that the SDK grants to a user, such as permission to send local streams, receive remote streams, and push streams to a CDN address. +- The user (**level**) determines the level of services that a user can enjoy within the permissions of the user's role. For example, an audience member can choose to receive remote streams with low latency or ultra-low latency. **User level affects the pricing of services.** + +**Note** This method applies to the interactive live streaming profile (the **profile** parameter of [setChannelProfile](class_irtcengine.html#api_setchannelprofile) is CHANNEL_PROFILE_LIVE_BROADCASTING) only. + +### Parameters + +- role + + The user role in the interactive live streaming. See [CLIENT_ROLE_TYPE](rtc_api_data_type.html#enum_clientroletype). + +- options + + The detailed options of a user, including the user level. See [ClientRoleOptions](rtc_api_data_type.html#class_clientroleoptions). + +### Returns + +- 0: Success. +- < 0: Failure. + - -1: A general error occurs (no specified reason). + - -2: The parameter is invalid. + - -5: The request is rejected. + - -7: The SDK is not initialized. + +**See also** + +- [onClientRoleChanged](../API/class_irtcengineeventhandler.html#callback_onclientrolechanged) +- [onUserJoined](../API/class_irtcengineeventhandler.html#callback_onuserjoined) +- [onUserOffline](../API/class_irtcengineeventhandler.html#callback_onuseroffline) + +## [setDefaultAudioRouteToSpeakerphone](class_irtcengine.html#api_setdefaultaudioroutetospeakerphone_ng) + +Sets the default audio playback route. + +```cpp +virtual int setDefaultAudioRouteToSpeakerphone(bool defaultToSpeaker) = 0; +``` + +**Note** + +This method applies to Android and iOS only. + +Most mobile phones have two audio routes: an earpiece at the top, and a speakerphone at the bottom. The earpiece plays at a lower volume, and the speakerphone at a higher volume. When setting the default audio route, you determine whether audio playback comes through the earpiece or speakerphone when no external audio device is connected. + +Depending on the scenario, Agora uses different default audio routes: + +- Voice call: Earpiece +- Audio broadcast: Speakerphone. +- Video call: Speakerphone. +- Video broadcast: Speakerphone + +You can call this method to change the default audio route. This method can be called before, during, or after a call. After a successful method call, the SDK triggers the [onAudioRoutingChanged](class_irtcengineeventhandler.html#callback_onaudioroutechanged) callback. + +**Note** + +The system audio route changes when an external audio device, such as a headphone or a Bluetooth audio device, is connected. See [Principles for Changing the Audio Route](https://docs.agora.io/en/live-streaming-4.x-preview/audio_route_ng?platform=Android). + +### Parameters + +- defaultToSpeaker + + Whether to set the speakerphone as the default audio route:`true`: Set the speakerphone as the default audio route.`false`: Do not set the speakerphone as the default audio route. + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [onAudioRoutingChanged](../API/class_irtcengineeventhandler.html#callback_onaudioroutechanged) + +## [setDefaultMuteAllRemoteAudioStreams](class_irtcengine.html#api_setdefaultmuteallremoteaudiostreams) + +Stops or resumes subscribing to the audio streams of all remote users by default. + +```cpp +virtual int setDefaultMuteAllRemoteAudioStreams(bool mute) = 0; +``` + +Call this method after joining a channel. After successfully calling this method, the local user stops or resumes subscribing to the audio streams of all subsequent users. + +**Note** + +If you need to resume subscribing to the audio streams of remote users in the channel after calling this method, do the following: + +- To resume subscribing to the audio stream of a specified user, call [muteRemoteAudioStream](class_irtcengine.html#api_muteremoteaudiostream)(`false`), and specify the user ID. +- To resume subscribing to the audio streams of multiple remote users, call muteRemoteAudioStream (`false`)multiple times. + +### Parameters + +- mute + + Whether to stop subscribing to the audio streams of all remote users by default.`true`: Stop subscribing to the audio streams of all remote users by default.`false`: (Default) Subscribe to the audio streams of all remote users by default. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setDefaultMuteAllRemoteVideoStreams](class_irtcengine.html#api_setdefaultmuteallremotevideostreams) + +Stops or resumes subscribing to the video streams of all remote users by default. + +```cpp +virtual int setDefaultMuteAllRemoteVideoStreams(bool mute) = 0; +``` + +Call this method after joining a channel. After successfully calling this method, the local user stops or resumes subscribing to the audio streams of all subsequent users. + +**Note** + +If you need to resume subscribing to the audio streams of remote users in the channel after calling this method, do the following: + +- To resume subscribing to the audio stream of a specified user, call [muteRemoteVideoStream](class_irtcengine.html#api_muteremotevideostream)(`false`), and specify the user ID. +- To resume subscribing to the audio streams of multiple remote users, call muteRemoteVideoStream(`false`)multiple times. + +### Parameters + +- mute + + Whether to stop subscribing to the audio streams of all remote users by default.`true`: Stop subscribing to the audio streams of all remote users by default.`false`: (Default) Resume subscribing to the audio streams of all remote users by default. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setEffectsVolume](class_irtcengine.html#api_seteffectsvolume) + +Sets the volume of the audio effects. + +```cpp +virtual int setEffectsVolume(int volume) = 0; +``` + + + +### Parameters + +- volume + + The playback volume. The value ranges from 0 to 100. The default value is 100, which represents the original volume. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setEnableSpeakerphone](class_irtcengine.html#api_setenablespeakerphone_ng) + +Enables/Disables the speakerphone temporarily. + +```cpp +virtual int setEnableSpeakerphone(bool speakerOn) = 0; +``` + +**Note** + +This method is for Android and iOS only. + +After a successful method call, the SDK triggers the [onAudioRoutingChanged](class_irtcengineeventhandler.html#callback_onaudioroutechanged) callback. + +You can call this method before, during, or after a call. However, Agora recommends calling this method only when you are in a channel to change the audio route temporarily. + +**Note** + +This method sets the audio route temporarily. Connecting in or disconnecting a headphone, or the SDK re-enabling the audio device module (ADM) to adjust the media volume in some scenarios relating to audio, leads to a change in the audio route. See [Principles for Changing the Audio Route](https://docs.agora.io/en/live-streaming-4.x-preview/audio_route_ng?platform=Android). + +Due to system limitations, if the user uses an external audio playback device such as a Bluetooth or wired headset on an iOS device, this method does not take effect. + +### Parameters + +- speakerOn + + Whether to set the speakerphone as the default audio route:`true`: Set the speakerphone as the audio route temporarily.`false`: Do not set the speakerphone as the audio route. + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [onAudioRoutingChanged](../API/class_irtcengineeventhandler.html#callback_onaudioroutechanged) + +## [setEncryptionMode](class_irtcengine.html#api_setencryptionmode) + +Sets the built-in encryption mode. + +```cpp +virtual int setEncryptionMode(const char* encryptionMode) = 0; +``` + +- Deprecated: + + Use [enableEncryption](class_irtcengine.html#api_enableencryption) instead. + +The Agora SDK supports built-in encryption, which is set to the AES-128-GCM mode by default. Call this method to use other encryption modes. All users in the same channel must use the same encryption mode and **secret**. Refer to the information related to the AES encryption algorithm on the differences between the encryption modes. + +**Note** Before calling this method, please call [setEncryptionSecret](class_irtcengine.html#api_setencryptionsecret) to enable the built-in encryption function. + +### Parameters + +- encryptionMode + + Encryption mode."`aes-128-xts`": 128-bit AES encryption, XTS mode."`aes-128-ecb`": 128-bit AES encryption, ECB mode."`aes-256-xts`": 256-bit AES encryption, XTS mode."`sm4-128-ecb`": 128-bit SM4 encryption, ECB mode."`aes-128-gcm`": 128-bit AES encryption, GCM mode."`aes-256-gcm`": 256-bit AES encryption, GCM mode."": When this parameter is set as null, the encryption mode is set as "`aes-128-gcm`" by default. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setEncryptionSecret](class_irtcengine.html#api_setencryptionsecret) + +Enables built-in encryption with an encryption password before users join a channel. + +```cpp +virtual int setEncryptionSecret(const char* secret) = 0; +``` + +- Deprecated: + + This method is deprecated from v3.2.0. Please use [enableEncryption](class_irtcengine.html#api_enableencryption) instead. + +Before joining the channel, you need to call this method to set the **secret** parameter to enable the built-in encryption. All users in the same channel should use the same **secret**. The **secret** is automatically cleared once a user leaves the channel. If you do not specify the **secret** or **secret** is set as null, the built-in encryption is disabled. + +**Note** + +- Do not use this method for CDN live streaming. +- For optimal transmission, ensure that the encrypted data size does not exceed the original data size + 16 bytes. 16 bytes is the maximum padding size for AES encryption. + +### Parameters + +- secret + + The encryption password. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setExtensionProperty](class_irtcengine.html#api_setextensionproperty) + +Sets the properties of the extension. + +```cpp +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; +``` + +After enabling the extension, you can call this method to set the properties of the extension. + +### Parameters + +- provider + + The name of the extension provider. + +- extension + + The name of the extension. + +- key + + The key of the extension. + +- value + + The value of the extension key. + +- type + + The type of media source. See [MEDIA_SOURCE_TYPE](rtc_api_data_type.html#enum_mediasourcetype).**Note** This parameter in this method only supports two values:The default value is UNKNOWN_MEDIA_SOURCE.If you want to use a secondary camera to capture video, set this parameter to SECONDARY_CAMERA_SOURCE. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setExtensionProviderProperty](class_irtcengine.html#api_setextensionproviderproperty) + +Sets the properties of the extension provider. + +```cpp +virtual int setExtensionProviderProperty( + const char* provider, const char* key, const char* value) = 0; +``` + +You can call this method to set the attributes of the extension provider and initialize the relevant parameters according to the type of the provider. + +**Note** + +Call this method after [enableExtension](class_irtcengine.html#api_enableextension), and before enabling the audio ([enableAudio](class_irtcengine.html#api_enableaudio)/[enableLocalAudio](class_irtcengine.html#api_enablelocalaudio)) or the video ([enableVideo](class_irtcengine.html#api_enablevideo)/[enableLocalVideo](class_irtcengine.html#api_enablelocalvideo)). + +### Parameters + +- provider + + The name of the extension provider. + +- key + + The key of the extension. + +- value + + The value of the extension key. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setExternalAudioSink](class_irtcengine.html#api_setexternalaudiosink_ng) + +Sets the external audio sink. + +```cpp +virtual int setExternalAudioSink(int sampleRate, int channels) = 0; +``` + +This method applies to scenarios where you want to use external audio data for playback. After setting `enableAudioDevice` to `false` in [initialize](class_irtcengine.html#api_create2), you can call [setExternalAudioSink](class_irtcengine.html#api_setexternalaudiosink_ng) to set the external audio sink. After the setting is successful, you can call [pullAudioFrame](class_imediaengine.html#api_imediaengine_pullaudioframe) to pull the remote audio data. The app can process the remote audio and play it with the audio effects that you want. + +**Note** + +- Ensure that you call this method before joining a channel. +- Once you enable the external audio sink, the app does not retrieve any audio data from the [onPlaybackAudioFrame](class_iaudioframeobserverbase.html#callback_iaudioframeobserverbase_onplaybackaudioframe) callback. + +### Parameters + +- sampleRate + + The sample rate (Hz) of the external audio sink, which can be set as 16000, 32000, 44100, or 48000. + +- channels + + The number of audio channels of the external audio sink:1: Mono.2: Stereo. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setExternalAudioSource](class_imediaengine.html#api_setexternalaudiosource2) + +Sets the external audio source parameters. + +```cpp +virtual int setExternalAudioSource(bool enabled, + int sampleRate, + int channels, + int sourceNumber, + bool localPlayback = false, + bool publish = true) = 0; +``` + +**Note** Call this method before joining a channel. + +### Parameters + +- enabled + + Whether to enable the external audio source:`true`: Enable the external audio source.`false`: (Default) Disable the external audio source. + +- sampleRate + + The sample rate (Hz) of the external audio source, which can be set as `8000`, `16000`, `32000`, `44100`, or `48000`. + +- channels + + The number of channels of the external audio source, which can be set as `1` (Mono) or `2` (Stereo). + +- sourceNumber + + The number of external audio sources. The value of this parameter should be larger than 0. The SDK creates a corresponding number of custom audio tracks based on this parameter value and names the audio tracks starting from 0. In [ChannelMediaOptions](rtc_api_data_type.html#class_channelmediaoptions_ng), you can set **publishCustomAudioSourceId** to the ID of the audio track you want to publish. + +- localPlayback + + Whether to play the external audio source:`true`: Play the external audio source.`false`: (Default) Do not play the external source. + +- publish + + Whether to publish audio to the remote users:`true`: (Default) Publish audio to the remote users.`false`: Do not publish audio to the remote users + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setInEarMonitoringVolume](class_irtcengine.html#api_setinearmonitoringvolume) + +Sets the volume of the in-ear monitor. + +```cpp +virtual int setInEarMonitoringVolume(int volume) = 0; +``` + +**Note** + +- This method is for Android and iOS only. +- Users must use wired earphones to hear their own voices. +- You can call this method either before or after joining a channel. + +### Parameters + +- volume + + The volume of the in-ear monitor. The value ranges between 0 and 100. The default value is 100. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setLiveTranscoding](class_irtcengine.html#api_setlivetranscoding) + +Sets the transcoding configurations for CDN live streaming. + +```cpp +virtual int setLiveTranscoding(const LiveTranscoding &transcoding) = 0; +``` + +This method sets the video layout and audio settings for CDN live streaming. The SDK triggers the [onTranscodingUpdated](class_irtcengineeventhandler.html#callback_ontranscodingupdated) callback when you call this method to update the transcoding settings. + +**Note** + +- This method takes effect only when you are a host in live interactive streaming. +- Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in the advanced guide Push Streams to CDN. +- If you call this method to set the transcoding configuration for the first time, the SDK does not trigger the onTranscodingUpdated callback. +- Call this method after joining a channel. +- Agora supports pushing media streams in RTMPS protocol to the CDN only when you enable transcoding. + +### Parameters + +- transcoding + + The transcoding configurations for CDN live streaming. For details, see [LiveTranscoding](rtc_api_data_type.html#class_livetranscoding). + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [onTranscodingUpdated](../API/class_irtcengineeventhandler.html#callback_ontranscodingupdated) + +## [setLocalRenderMode [1/2\]](class_irtcengine.html#api_setlocalrendermode) + +Sets the local video display mode. + +```cpp +virtual int setLocalRenderMode(media::base::RENDER_MODE_TYPE renderMode) = 0; +``` + + + +- Deprecated: + + This method is deprecated. Use [setLocalRenderMode [2/2\]](class_irtcengine.html#api_setlocalrendermode2) instead. + +Call this method to set the local video display mode. This method can be called multiple times during a call to change the display mode. + +### Parameters + +- renderMode + + The local video display mode. For details, see [RENDER_MODE_TYPE](rtc_api_data_type.html#enum_rendermodetype). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setLocalRenderMode [2/2\]](class_irtcengine.html#api_setlocalrendermode2) + +Updates the display mode of the local video view. + +```cpp +virtual int setLocalRenderMode(media::base::RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode) = 0; +``` + + + +After initializing the local video view, you can call this method to update its rendering and mirror modes. It affects only the video view that the local user sees, not the published local video stream. + +**Note** + +- Ensure that you have called the [setupLocalVideo](class_irtcengine.html#api_setuplocalvideo) method to initialize the local video view before calling this method. +- During a call, you can call this method as many times as necessary to update the display mode of the local video view. + +### Parameters + +- renderMode + + The local video display mode. For details, see [RENDER_MODE_TYPE](rtc_api_data_type.html#enum_rendermodetype). + +- mirrorMode + + The rendering mode of the local video view. See [VIDEO_MIRROR_MODE_TYPE](rtc_api_data_type.html#enum_videomirrormodetype).**Note** If you use a front camera, the SDK enables the mirror mode by default; if you use a rear camera, the SDK disables the mirror mode by default. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setLocalVideoMirrorMode](class_irtcengine.html#api_setlocalvideomirrormode) + +Sets the local video mirror mode. + +```cpp +virtual int setLocalVideoMirrorMode(VIDEO_MIRROR_MODE_TYPE mirrorMode) = 0; +``` + +- Deprecated: + + Deprecated as of v3.0.0. + + Use [setupLocalVideo](class_irtcengine.html#api_setuplocalvideo) or [setLocalRenderMode [2/2\]](class_irtcengine.html#api_setlocalrendermode2) instead. + +### Parameters + +- mirrorMode + + The local video mirror mode. For details, see [VIDEO_MIRROR_MODE_TYPE](rtc_api_data_type.html#enum_videomirrormodetype). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setLocalVoiceChanger](class_irtcengine.html#api_setlocalvoicechanger) + +Sets the local voice changer option. + +```cpp +virtual int setLocalVoiceChanger(VOICE_CHANGER_PRESET voiceChanger) = 0; +``` + +- Deprecated: + + Deprecated from v3.2.0. Use the following methods instead:[setAudioEffectPreset](class_irtcengine.html#api_setaudioeffectpreset) : Audio effects.[setVoiceBeautifierPreset](class_irtcengine.html#api_setvoicebeautifierpreset) : Voice beautifier effects.[setVoiceConversionPreset](class_irtcengine.html#api_setvoiceconversionpreset) : Voice conversion effects. + +This method can be used to set the local voice effect for users in a COMMUNICATION channel or hosts in a LIVE_BROADCASTING channel. After successfully calling this method, all users in the channel can hear the voice with reverberation. + +- `VOICE_CHANGER_XXX`: Changes the local voice to an old man, a little boy, or the Hulk. Applies to the voice talk scenario. +- `VOICE_BEAUTY_XXX`: Beautifies the local voice by making it sound more vigorous, resounding, or adding spacial resonance. Applies to the voice talk and singing scenario. +- `GENERAL_VOICE_BEAUTY_XXX`: Adds gender-based beautification effect to the local voice. Applies to the voice talk scenario. For a male voice: Adds magnetism to the voice. For a male voice: Adds magnetism to the voice. For a female voice: Adds freshness or vitality to the voice. + +**Note** + +- To achieve better voice effect quality, Agora recommends setting the [setAudioProfile [1/2\]](class_irtcengine.html#api_setaudioprofile)**profile** parameter in asAUDIO_PROFILE_MUSIC_HIGH_QUALITY (4) orAUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO (5). +- This method works best with the human voice, and Agora does not recommend using it for audio containing music and a human voice. +- Do not use this method with [setLocalVoiceReverbPreset](class_irtcengine.html#api_setlocalvoicereverbpreset), because the method called later overrides the one called earlier. For detailed considerations, see the advanced guide Set the Voice Effect. +- You can call this method either before or after joining a channel. + +### Parameters + +- voiceChanger + + The local voice changer option. The default value is VOICE_CHANGER_OFF , which means the original voice. For more details, see [VOICE_CHANGER_PRESET](rtc_api_data_type.html#enum_voicechangerpreset). The gender-based beatification effect works best only when assigned a proper gender. Use GENERAL_BEAUTY_VOICE_MALE_MAGNETIC for male and use GENERAL_BEAUTY_VOICE_FEMALE_FRESH and GENERAL_BEAUTY_VOICE_FEMALE_VITALITY for female. Failure to do so can lead to voice distortion. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setLocalVoiceEqualization](class_irtcengine.html#api_setlocalvoiceequalization) + +Sets the local voice equalization effect. + +```cpp +virtual int setLocalVoiceEqualization(AUDIO_EQUALIZATION_BAND_FREQUENCY bandFrequency, int bandGain) = 0; +``` + +**Note** You can call this method either before or after joining a channel. + +### Parameters + +- bandFrequency + + The band frequency. The value ranges between 0 and 9; representing the respective 10-band center frequencies of the voice effects, including 31, 62, 125, 250, 500, 1k, 2k, 4k, 8k, and 16k Hz. For more details, see [AUDIO_EQUALIZATION_BAND_FREQUENCY](rtc_api_data_type.html#enum_audioequalizationbandfrequency). + +- bandGain + + The gain of each band in dB. The value ranges between -15 and 15. The default value is 0. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setLocalVoicePitch](class_irtcengine.html#api_setlocalvoicepitch) + +Changes the voice pitch of the local speaker. + +```cpp +virtual int setLocalVoicePitch(double pitch) = 0; +``` + +**Note** You can call this method either before or after joining a channel. + +### Parameters + +- pitch + + The local voice pitch. The value range is [0.5,2.0]. The lower the value, the lower the pitch. The default value is 1 (no change to the pitch). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setLocalVoiceReverb](class_irtcengine.html#api_setlocalvoicereverb) + +Sets the local voice reverberation. + +```cpp +virtual int setLocalVoiceReverb(AUDIO_REVERB_TYPE reverbKey, int value) = 0; +``` + +You can call this method either before or after joining a channel. + +### Parameters + +- reverbKey + + The reverberation key. Agora provides 5 reverberation keys: [AUDIO_REVERB_TYPE](rtc_api_data_type.html#enum_audioreverbtype). + +- value + + The value of the reverberation key. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setLocalVoiceReverbPreset](class_irtcengine.html#api_setlocalvoicereverbpreset) + +Sets the local voice reverberation option, including the virtual stereo. + +```cpp +virtual int setLocalVoiceReverbPreset(AUDIO_REVERB_PRESET reverbPreset) = 0; +``` + +This method sets the local voice reverberation for users in a COMMUNICATION channel or hosts in a LIVE_BROADCASTING channel. After successfully calling this method, all users in the channel can hear the voice with reverberation. + +**Note** + +- When using the enumeration value prefixed with `AUDIO_REVERB_FX`, ensure that you set the **profile** parameter in [setAudioProfile [1/2\]](class_irtcengine.html#api_setaudioprofile) toAUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5) before calling this method. Otherwise, the method setting is invalid. +- When calling the AUDIO_VIRTUAL_STEREO method, Agora recommends setting the **profile** parameter in setAudioProfile [1/2] as AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5). +- This method works best with the human voice, and Agora does not recommend using it for audio containing music and a human voice. +- Do not use this method with [setLocalVoiceChanger](class_irtcengine.html#api_setlocalvoicechanger), because the method called later overrides the one called earlier. For detailed considerations, see the advanced guide Set the Voice Effect. +- You can call this method either before or after joining a channel. + +### Parameters + +- reverbPreset + + The local voice reverberation option. The default value is AUDIO_REVERB_OFF, which means the original voice. For more details, see [AUDIO_REVERB_PRESET](rtc_api_data_type.html#enum_audioreverbpreset). To achieve better voice effects, Agora recommends the enumeration whose name begins with `AUDIO_REVERB_FX`. + + + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setLogFile](class_irtcengine.html#api_setlogfile_ng) + +Set the log file + +```cpp +virtual int setLogFile(const char* filePath) = 0; +``` + +- Deprecated: + + Use the `mLogConfig` parameter in [initialize](class_irtcengine.html#api_create2) method instead. + +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 calling the initialize[IRtcEngine](class_irtcengine.html#class_irtcengine) method, or the output log may not be complete. + +### Parameters + +- filePath + + The absolute path of the log files. These log files are encoded in UTF-8. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setLogFileSize](class_irtcengine.html#api_setlogfilesize_ng) + +Sets the log file size. + +```cpp +virtual int setLogFileSize(unsigned int fileSizeInKBytes) = 0; +``` + +- Deprecated: + + Use the `logConfig` parameter in [initialize](class_irtcengine.html#api_create2) instead. + +By default, the SDK outputs four log files: `agorasdk.log`, `agorasdk1.log`, `agoraapi.log`, and `agoraapi1.log`. The `agorasdk.log` and `agorasdk1.log` files each have a default size of 1024 KB, and the `agoraapi.log` and `agoraapi1.log` files each have a default size of 2,048 KB. These log files are encoded in UTF-8. + +The SDK writes the latest logs in `agorasdk.log` or `agoraapi.log`. + +When `agorasdk.log` or `agoraapi.log` is full, the SDK deletes `agorasdk1.log` or `agoraapi1.log`, renames `agorasdk.log` to `agorasdk1.log` and `agoraapi.log` to `agoraapi1.log`, and creates a new `agorasdk.log` or `agoraapi.log` to record the latest logs. + +**Note** + +This method applies to the `agorasdk.log` file only and does not take effect for the `agoraapi.log` file. + +### Parameters + +- **fileSizeInKBytes** + + The size (KB) of an `agorasdk.log` file. The value range is [128,1024]. The default value is 1,024 KB. If you set `fileSizeInKByte` smaller than 128 KB, the SDK automatically adjusts it to 128 KB; if you set `fileSizeInKByte` greater than 1,024 KB, the SDK automatically adjusts it to 1,024 KB. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setLogFilter](class_irtcengine.html#api_setlogfilter) + +Sets the log output level of the SDK. + +```cpp +virtual int setLogFilter(unsigned int filter) = 0; +``` + +This method sets the output log level of the SDK. You can use one or a combination of the log filter levels. The log level follows the sequence of OFF, CRITICAL, ERROR, WARNING, INFO, and DEBUG. Choose a level to see the logs preceding that level. + +If, for example, you set the log level to WARNING, you see the logs within levels CRITICAL, ERROR, and WARNING. + +### Parameters + +- filter + + The output log level of the SDK. For details, see [LOG_FILTER_TYPE](rtc_api_data_type.html#enum_logfiltertype). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setLogLevel](class_irtcengine.html#api_setloglevel) + +Sets the output log level of the SDK. + +```cpp +virtual int setLogLevel(commons::LOG_LEVEL level) = 0; +``` + +- Deprecated: + + This method is deprecated. Use [RtcEngineContext](rtc_api_data_type.html#class_rtcengineconfig_ng) instead to set the log output level. + +Choose a level to see the logs preceding that level. + +### Parameters + +- level + + The log level: [LOG_LEVEL](rtc_api_data_type.html#enum_loglevel). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setMixedAudioFrameParameters](class_irtcengine.html#api_setmixedaudioframeparameters_ng) + +Sets the audio data format reported by [onMixedAudioFrame](class_iaudioframeobserverbase.html#callback_iaudioframeobserverbase_onmixedaudioframe). + +```cpp +virtual int setMixedAudioFrameParameters(int sampleRate, int channel, int samplesPerCall) = 0; +``` + +### Parameters + +- sampleRate + + The sample rate returned in the callback, which can be set as `8000`, `16000`, `32000`, `44100`, or `48000` Hz. + +- channel + + The number of channels of the external audio source, which can be set as `1`(Mono) or `2`(Stereo). + +- samplesPerCall + + Sets the number of samples the onMixedAudioFrame callback returns. In RTMP streaming scenarios, set it as `1024`. + +**Note** + +The SDK triggers the onMixedAudioFrame callback according to the sample interval. Sample interval (sec) = `samplePerCall`/(`sampleRate` × `channel`). Ensure that the value of sample interval ≥ 0.01. + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [onMixedAudioFrame](../API/class_iaudioframeobserverbase.html#callback_iaudioframeobserverbase_onmixedaudioframe) + +## [setPlaybackAudioFrameBeforeMixingParameters](class_irtcengine.html#api_setplaybackaudioframebeforemixingparameters) + +Sets the audio data format reported by [onPlaybackAudioFrameBeforeMixing](class_iaudioframeobserverbase.html#callback_iaudioframeobserverbase_onplaybackaudioframebeforemixing). + +```cpp +virtual int setPlaybackAudioFrameBeforeMixingParameters(int sampleRate, int channel) = 0; +``` + +Sets the audio data format reported by [onPlaybackAudioFrameBeforeMixing](class_iaudioframeobserverbase.html#callback_iaudioframeobserverbase_onplaybackaudioframebeforemixing). + +### Parameters + +- **sampleRate** + + The sample rate returned in the callback, which can be set as `8000`, `16000`, `32000`, `44100`, or `48000` Hz. + +- **channel** + + The number of channels of the external audio source, which can be set as `1`(Mono) or `2`(Stereo). + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [onPlaybackAudioFrameBeforeMixing](../API/class_iaudioframeobserverbase.html#callback_iaudioframeobserverbase_onplaybackaudioframebeforemixing) + +## [setPlaybackAudioFrameParameters](class_irtcengine.html#api_setplaybackaudioframeparameters) + +Sets the audio data format for playback. + +```cpp +virtual int setPlaybackAudioFrameParameters(int sampleRate, + int channel, + RAW_AUDIO_FRAME_OP_MODE_TYPE mode, + int samplesPerCall) = 0; +``` + +Sets the audio format for the [onPlaybackAudioFrame](class_iaudioframeobserverbase.html#callback_iaudioframeobserverbase_onplaybackaudioframe) callback. + +**Note** + +- Ensure that you call this method before joining a channel. +- The SDK calculates the sampling interval based on the **samplesPerCall**, **sampleRate** and **channel** parameters set in this method.Sample interval (sec) = **samplePerCall**/(**sampleRate** × **channel**). Ensure that the sample interval ≥ 0.01 (s). The SDK triggers the onPlaybackAudioFrame callback according to the sampling interval. + +### Parameters + +- sampleRate + + The sample rate returned in the onPlaybackAudioFrame callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz. + +- channel + + The number of channels (channels) returned in the onPlaybackAudioFrame callback:1: Mono.2: Stereo. + +- mode + + The use mode of the audio frame. See [RAW_AUDIO_FRAME_OP_MODE_TYPE](rtc_api_data_type.html#enum_rawaudioframeopmodetype). + +- samplesPerCall + + The number of samples returned in the onPlaybackAudioFrame callback. Usually set as 1024 for RTMP or RTMPS streaming. + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [onPlaybackAudioFrame](../API/class_iaudioframeobserverbase.html#callback_iaudioframeobserverbase_onplaybackaudioframe) + +## [setRecordingAudioFrameParameters](class_irtcengine.html#api_setrecordingaudioframeparameters) + +Set the format of the captured raw audio data. + +```cpp +virtual int setRecordingAudioFrameParameters(int sampleRate, + int channel, + RAW_AUDIO_FRAME_OP_MODE_TYPE mode, + int samplesPerCall) = 0; +``` + +Sets the audio format for the [onRecordAudioFrame](class_iaudioframeobserverbase.html#callback_iaudioframeobserverbase_onrecordaudioframe) callback. + +**Note** + +- Ensure that you call this method before joining a channel. +- The SDK calculates the sampling interval based on the **samplesPerCall**, **sampleRate** and **channel** parameters set in this method.Sample interval (sec) = **samplePerCall**/(**sampleRate** × **channel**). Ensure that the sample interval ≥ 0.01 (s). The SDK triggers the callback according to the sampling intervalonRecordAudioFrame. + +### Parameters + +- sampleRate + + The sample rate returned in the onRecordAudioFrame callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz. + +- channel + + The number of channels (channels) returned in the onRecordAudioFrame callback:1: Mono.2: Stereo. + +- mode + + The use mode of the audio frame. See [RAW_AUDIO_FRAME_OP_MODE_TYPE](rtc_api_data_type.html#enum_rawaudioframeopmodetype). + +- samplesPerCall + + The number of samples returned in the onRecordAudioFrame callback. Usually set as 1024 for RTMP or RTMPS streaming. + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [onRecordAudioFrame](../API/class_iaudioframeobserverbase.html#callback_iaudioframeobserverbase_onrecordaudioframe) + +## [setRemoteDefaultVideoStreamType](class_irtcengine.html#api_setremotedefaultvideostreamtype) + +Sets the default stream type of remote video streams. + +```cpp +virtual int setRemoteVideoStreamType(uid_t uid, VIDEO_STREAM_TYPE streamType) = 0; +``` + + + +Under limited network conditions, if the publisher has not disabled the dual-stream mode using (),the receiver can choose to receive either the high-quality video stream or the low-quality video stream. The high-quality video stream has a higher resolution and bitrate, and the low-quality video stream has a lower resolution and bitrate.[enableDualStreamMode [1/3\]](class_irtcengine.html#api_enabledualstreammode)`false` + +By default, users receive the high-quality video stream. Call this method if you want to switch to the low-quality video stream. This method allows the app to adjust the corresponding video stream type based on the size of the video window to reduce the bandwidth and resources. The aspect ratio of the low-quality video stream is the same as the high-quality video stream. Once the resolution of the high-quality video stream is set, the system automatically sets the resolution, frame rate, and bitrate of the low-quality video stream. + +The result of this method returns in the [onApiCallExecuted](class_irtcengineeventhandler.html#callback_onapicallexecuted) callback. + +**Note** You can call this method either before or after joining a channel. If you call both setRemoteVideoStreamType and [setRemoteDefaultVideoStreamType](class_irtcengine.html#api_setremotedefaultvideostreamtype), the settings in setRemoteVideoStreamType take effect. + +### Parameters + +- streamType + + The default stream type of the remote video, see [REMOTE_VIDEO_STREAM_TYPE](rtc_api_data_type.html#enum_remotevideostreamtype). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setupRemoteVideo](class_irtcengine.html#api_setupremotevideo) + +Initializes the video view of a remote user. + +```cpp +virtual int setupRemoteVideo(const VideoCanvas& canvas) = 0; +``` + +This method initializes the video view of a remote stream on the local device. It affects only the video view that the local user sees. Call this method to bind the remote video stream to a video view and to set the rendering and mirror modes of the video view. + +You need to specify the ID of the remote user in this method. If the remote user ID is unknown to the application, set it after the app receives the [onUserJoined](class_irtcengineeventhandler.html#callback_onuserjoined) callback. + +To unbind the remote user from the view, set the **view** parameter to NULL. + +Once the remote user leaves the channel, the SDK unbinds the remote user. + +**Note** + +- To update the rendering or mirror mode of the remote video view during a call, use the [setRemoteRenderMode](class_irtcengine.html#api_setremoterendermode2) method. +- If you use the Agora recording feature, the recording client joins the channel as a dummy client, triggering the [onUserJoined](class_irtcengineeventhandler.html#callback_onuserjoined) callback. Do not bind the dummy client to the app view because the dummy client does not send any video streams. If your app does not recognize the dummy client, bind the remote user to the view when the SDK triggers the [onFirstRemoteVideoDecoded](class_irtcengineeventhandler.html#callback_onfirstremotevideodecoded) callback. + +### Parameters + +- canvas + + The remote video view and settings. For details, see [VideoCanvas](rtc_api_data_type.html#class_videocanvas_ng). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setRemoteRenderMode](class_irtcengine.html#api_setremoterendermode2) + +Updates the display mode of the video view of a remote user. + +```cpp +virtual int setRemoteRenderMode(uid_t userId, RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode) = 0; +``` + +After initializing the video view of a remote user, you can call this method to update its rendering and mirror modes. This method affects only the video view that the local user sees. + +**Note** + +- Please call this method after initializing the remote view by calling the [setupRemoteVideo](class_irtcengine.html#api_setupremotevideo) 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 + +- userId + + The ID of the remote user. + +- renderMode + + The rendering mode of the remote user view. For details, see [RENDER_MODE_TYPE](rtc_api_data_type.html#enum_rendermodetype). + +- mirrorMode + + The mirror mode of the remote user view. For details, see [VIDEO_MIRROR_MODE_TYPE](rtc_api_data_type.html#enum_videomirrormodetype). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setRemoteVideoStreamType](class_irtcengine.html#api_setremotevideostreamtype) + +Sets the stream type of the remote video. + +```cpp +virtual int setRemoteVideoStreamType(uid_t uid, VIDEO_STREAM_TYPE streamType) = 0; +``` + + + +Under limited network conditions, if the publisher has not disabled the dual-stream mode using [enableDualStreamMode [1/3\]](class_irtcengine.html#api_enabledualstreammode)(false), the receiver can choose to receive either the high-quality video stream (the high resolution, and high bitrate video stream) or the low-quality video stream (the low resolution, and low bitrate video stream). The high-quality video stream has a higher resolution and bitrate, and the low-quality video stream has a lower resolution and bitrate. + +By default, users receive the high-quality video stream. Call this method if you want to switch to the low-quality video stream. This method allows the app to adjust the corresponding video stream type based on the size of the video window to reduce the bandwidth and resources. The aspect ratio of the low-quality video stream is the same as the high-quality video stream. Once the resolution of the high-quality video stream is set, the system automatically sets the resolution, frame rate, and bitrate of the low-quality video stream. + +The method result returns in the [onApiCallExecuted](class_irtcengineeventhandler.html#callback_onapicallexecuted) callback. + +**Note** You can call this method either before or after joining a channel. If you call both setRemoteVideoStreamType and [setRemoteDefaultVideoStreamType](class_irtcengine.html#api_setremotedefaultvideostreamtype), the setting of setRemoteVideoStreamType takes effect. + +### Parameters + +- uid + + User ID. + +- streamType + + The video stream type: [REMOTE_VIDEO_STREAM_TYPE](rtc_api_data_type.html#enum_remotevideostreamtype). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setRemoteVoicePosition](class_irtcengine.html#api_setremotevoiceposition) + +Sets the 2D position (the position on the horizontal plane) of the remote user's voice. + +```cpp +virtual int setRemoteVoicePosition(uid_t uid, double pan, double gain) = 0; +``` + +This method sets the 2D position and volume of a remote user, so that the local user can easily hear and identify the remote user's position. + +When the local user calls this method to set the voice position of a remote user, the voice difference between the left and right channels allows the local user to track the real-time position of the remote user, creating a sense of space. This method applies to massive multiplayer online games, such as Battle Royale games. + +**Note** + +- For this method to work, enable stereo panning for remote users by calling the [enableSoundPositionIndication](class_irtcengine.html#api_enablesoundpositionindication) method before joining a channel. +- For the best voice positioning, Agora recommends using a wired headset. +- Call this method after joining a channel. + +### Parameters + +- uid + + The user ID of the remote user. + +- pan + + The voice position of the remote user. The value ranges from -1.0 to 1.0:0.0: (Default) The remote voice comes from the front.-1.0: The remote voice comes from the left.1.0: The remote voice comes from the right. + +- gain + + The volume of the remote user. The value ranges from 0.0 to 100.0. The default value is 100.0 (the original volume of the remote user). The smaller the value, the lower the volume. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setScreenCaptureContentHint](class_irtcengine.html#api_setscreencapturecontenthint) + +Sets the content hint for screen sharing. + +```cpp +virtual int setScreenCaptureContentHint(VIDEO_CONTENT_HINT contentHint) = 0; + +``` + +A content hint suggests the type of the content being shared, so that the SDK applies different optimization algorithms to different types of content. If you don't call this method, the default content hint is CONTENT_HINT_NONE. + +**Note** You can call this method either before or after you start screen sharing. + +### Parameters + +- contentHint + + The content hint for screen sharing. For details, see [VideoContentHint](rtc_api_data_type.html#enum_videocontenthint). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setVideoEncoderConfiguration](class_irtcengine.html#api_setvideoencoderconfiguration) + +Sets the video encoder configuration. + +```cpp +virtual int setVideoEncoderConfiguration(const VideoEncoderConfiguration& config) = 0; +``` + +Sets the encoder configuration for the local video. + +**Note** You can call this method either before or after joining a channel. If you don't need to set the video encoder configuration after joining a channel, Agora recommends you calling this method before the [enableVideo](class_irtcengine.html#api_enablevideo) method to reduce the rendering time of the first video frame. + +### Parameters + +- config + + Video profile. See [VideoEncoderConfiguration](rtc_api_data_type.html#class_videoencoderconfiguration). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setupLocalVideo](class_irtcengine.html#api_setuplocalvideo) + +Initializes the local video view. + +```cpp +virtual int setupLocalVideo(const VideoCanvas& canvas) = 0; +``` + +This method initializes the video view of a local stream on the local device. It affects only the video view that the local user sees, not the published local video stream. Call this method to bind the local video stream to a video **view** and to set the rendering and mirror modes of the video view. + +After initialization, call this method to set the local video and then join the channel. The local video still binds to the view after you leave the channel. To unbind the local video from the view, set the **view** parameter as NULL. + +**Note** + +- You can call this method either before or after joining a channel. +- To update the rendering or mirror mode of the local video view during a call, use the [setLocalRenderMode [2/2\]](class_irtcengine.html#api_setlocalrendermode2) method. + +### Parameters + +- canvas + + The local video view and settings. For details, see [VideoCanvas](rtc_api_data_type.html#class_videocanvas_ng). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setVoiceBeautifierParameters](class_irtcengine.html#api_setvoicebeautifierparameters) + +Sets parameters for the preset voice beautifier effects. + +```cpp +virtual int setVoiceBeautifierParameters(VOICE_BEAUTIFIER_PRESET preset, int param1, int param2) = 0; +``` + +Call this method to set a gender characteristic and a reverberation effect for the singing beautifier effect. This method sets parameters for the local user who sends an audio stream. After setting the audio parameters, all users in the channel can hear the effect. + +For better voice effects, Agora recommends that you call [setAudioProfile [1/2\]](class_irtcengine.html#api_setaudioprofile) and set**scenario** to AUDIO_SCENARIO_GAME_STREAMING(3) and **profile** 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 [1/2] to AUDIO_PROFILE_SPEECH_STANDARD(1) or AUDIO_PROFILE_IOT(6). Otherwise, the method does not take effect. + +- This method works best with the human voice. Agora does not recommend using this method for audio containing music. + +- After calling + + + + setVoiceBeautifierParameters + + , Agora recommends not calling the following methods, because they can override settings in + + + + setVoiceBeautifierParameters + + : + + - [setAudioEffectPreset](class_irtcengine.html#api_setaudioeffectpreset) + - [setAudioEffectParameters](class_irtcengine.html#api_setaudioeffectparameters) + - [setVoiceBeautifierPreset](class_irtcengine.html#api_setvoicebeautifierpreset) + - [setLocalVoiceReverbPreset](class_irtcengine.html#api_setlocalvoicereverbpreset) + - [setLocalVoiceChanger](class_irtcengine.html#api_setlocalvoicechanger) + - [setLocalVoicePitch](class_irtcengine.html#api_setlocalvoicepitch) + - [setLocalVoiceEqualization](class_irtcengine.html#api_setlocalvoiceequalization) + - [setLocalVoiceReverb](class_irtcengine.html#api_setlocalvoicereverb) + - [setVoiceConversionPreset](class_irtcengine.html#api_setvoiceconversionpreset) + +### Parameters + +- preset + + The option for the preset audio effect:`SINGING_BEAUTIFIER`: The 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 effect options for the singing voice:`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. + +## [setVoiceBeautifierPreset](class_irtcengine.html#api_setvoicebeautifierpreset) + +Sets a preset voice beautifier effect. + +```cpp +virtual int setVoiceBeautifierPreset(VOICE_BEAUTIFIER_PRESET preset) = 0; +``` + +Call this method to set a 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. + +For better voice effects, Agora recommends that you call [setAudioProfile [1/2\]](class_irtcengine.html#api_setaudioprofile) and set **scenario** to AUDIO_SCENARIO_GAME_STREAMING (3) and **profile** 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 in setAudioProfile [1/2] to AUDIO_PROFILE_SPEECH_STANDARD(1) or AUDIO_PROFILE_IOT(6), or the method does not take effect. + +- This method works best with the human voice. Agora does not recommend using this method for audio containing music. + +- After calling + + + + setVoiceBeautifierPreset + + , Agora recommends not calling the following methods, because they can override + + + + setVoiceBeautifierPreset + + : + + - [setAudioEffectPreset](class_irtcengine.html#api_setaudioeffectpreset) + - [setAudioEffectParameters](class_irtcengine.html#api_setaudioeffectparameters) + - [setLocalVoiceReverbPreset](class_irtcengine.html#api_setlocalvoicereverbpreset) + - [setLocalVoiceChanger](class_irtcengine.html#api_setlocalvoicechanger) + - [setLocalVoicePitch](class_irtcengine.html#api_setlocalvoicepitch) + - [setLocalVoiceEqualization](class_irtcengine.html#api_setlocalvoiceequalization) + - [setLocalVoiceReverb](class_irtcengine.html#api_setlocalvoicereverb) + - [setVoiceBeautifierParameters](class_irtcengine.html#api_setvoicebeautifierparameters) + - [setVoiceConversionPreset](class_irtcengine.html#api_setvoiceconversionpreset) + +### Parameters + +- preset + + The preset voice beautifier effect options: [VOICE_BEAUTIFIER_PRESET](rtc_api_data_type.html#enum_voicebeautifierpreset). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setVoiceConversionPreset](class_irtcengine.html#api_setvoiceconversionpreset) + +Sets a preset voice beautifier effect. + +```cpp +virtual int setVoiceConversionPreset(VOICE_CONVERSION_PRESET preset) = 0; +``` + +Call this method to set a preset voice beautifier effect for the local user who sends an audio stream. After setting an audio effect, all users in the channel can hear the effect. You can set different audio effects for different scenarios. See Set the Voice Beautifier and Audio Effects. + +To achieve better audio effect quality, Agora recommends that you call [setAudioProfile [1/2\]](class_irtcengine.html#api_setaudioprofile) and set the **profile** to AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5) and **scenario** 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 setsetAudioProfile [1/2] the **profile** parameter in to AUDIO_PROFILE_SPEECH_STANDARD(1) or AUDIO_PROFILE_IOT(6), or the method does not take effect. + +- This method works best with the human voice. Agora does not recommend using this method for audio containing music. + +- After calling + + + + setVoiceConversionPreset + + , Agora recommends not calling the following methods, or the settings in + + + + setVoiceConversionPreset + + + + are overridden : + + - [setAudioEffectPreset](class_irtcengine.html#api_setaudioeffectpreset) + - [setAudioEffectParameters](class_irtcengine.html#api_setaudioeffectparameters) + - [setVoiceBeautifierPreset](class_irtcengine.html#api_setvoicebeautifierpreset) + - [setVoiceBeautifierParameters](class_irtcengine.html#api_setvoicebeautifierparameters) + - [setLocalVoiceReverbPreset](class_irtcengine.html#api_setlocalvoicereverbpreset) + - [setLocalVoiceChanger](class_irtcengine.html#api_setlocalvoicechanger) + - [setLocalVoicePitch](class_irtcengine.html#api_setlocalvoicepitch) + - [setLocalVoiceEqualization](class_irtcengine.html#api_setlocalvoiceequalization) + - [setLocalVoiceReverb](class_irtcengine.html#api_setlocalvoicereverb) + +### Parameters + +- preset + + The options for the preset voice beautifier effects: [VOICE_CONVERSION_PRESET](rtc_api_data_type.html#enum_voiceconversionpreset). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setVolumeOfEffect](class_irtcengine.html#api_setvolumeofeffect) + +Sets the volume of a specified audio effect. + +```cpp +virtual int setVolumeOfEffect(int soundId, int volume) = 0; +``` + + + +### Parameters + +- soundId + + The audio effect ID. The ID of each audio effect file is unique. + +- volume + + The playback volume. The value ranges from 0 to 100. The default value is 100, which represents the original volume. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [startAudioMixing [1/2\]](class_irtcengine.html#api_startaudiomixing) + +Starts playing the music file. + +```cpp +virtual int startAudioMixing(const char* filePath, + bool loopback, + bool replace, + int cycle) = 0; +``` + +- Deprecated: + + Please use [startAudioMixing [2/2\]](class_irtcengine.html#api_startaudiomixing2) instead. + +This method mixes the specified local or online audio file with the audio from the microphone, or replaces the microphone's audio with the specified local or remote audio file. A successful method call triggers the [onAudioMixingStateChanged](class_irtcengineeventhandler.html#callback_onaudiomixingstatechanged_ng) (AUDIO_MIXING_STATE_PLAYING) callback. When the audio mixing file playback finishes, the SDK triggers the onAudioMixingStateChanged (AUDIO_MIXING_STATE_STOPPED) callback on the local client. + +**Note** + +- Call this method after joining a channel. If you need to call startAudioMixing [1/2] multiple times, ensure that the time interval between calling this method is more than 500 ms. +- If the local audio mixing file does not exist, or if the SDK does not support the file format or cannot access the music file URL, the SDK returns `WARN_AUDIO_MIXING_OPEN_ERROR` (701). + +### Parameters + +- filePath + + The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example: `C:\music\audio.mp4`. Supported audio formats include MP3, AAC, M4A, MP4, WAV, and 3GP. See [supported audio formats](https://docs.microsoft.com/en-us/windows/win32/medfound/supported-media-formats-in-media-foundation). + +- loopback + + Whether to only play music files on the local client:`true`: Only play music files on the local client so that only the local user can hear the music.`false`: Publish music files to remote clients so that both the local user and remote users can hear the music. + +- replace + + Whether to replace the audio captured by the microphone with a music file:`true`: Replace the audio captured by the microphone with a music file. Users can only hear the music.`false`: Do not replace the audio captured by the microphone with a music file. Users can hear both music and audio captured by the microphone. + +- cycle + + The number of times the music file plays.≥ 0: The number of playback times. For example, 0 means that the SDK does not play the music file while 1 means that the SDK plays once.-1: Play the audio effect in an infinite loop. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [startAudioMixing [2/2\]](class_irtcengine.html#api_startaudiomixing2) + +Starts playing the music file. + +```cpp +virtual int startAudioMixing(const char* filePath, bool loopback, bool replace, int cycle, int startPos) = 0; +``` + +This method mixes the specified local or online audio file with the audio from the microphone, or replaces the microphone's audio with the specified local or remote audio file. A successful method call triggers the [onAudioMixingStateChanged](class_irtcengineeventhandler.html#callback_onaudiomixingstatechanged_ng) (`PLAY`) callback. When the audio mixing file playback finishes, the SDK triggers the onAudioMixingStateChanged (`STOPPED`) callback on the local client. + +**Note** + +- Call this method after joining a channel. If you need to call startAudioMixing [2/2] multiple times, ensure that the time interval between calling this method is more than 500 ms. +- If the local audio mixing file does not exist, or if the SDK does not support the file format or cannot access the music file URL, the SDK returns `WARN_AUDIO_MIXING_OPEN_ERROR` (701). + +### Parameters + +- filePath + + The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example: `C:\music\audio.mp4`. Supported audio formats include MP3, AAC, M4A, MP4, WAV, and 3GP. See [supported audio formats](https://docs.microsoft.com/en-us/windows/win32/medfound/supported-media-formats-in-media-foundation). + +- loopcount + + Whether to only play music files on the local client:`true`: Only play music files on the local client so that only the local user can hear the music.`false`: Publish music files to remote clients so that both the local user and remote users can hear the music. + +- replace + + Whether to replace the audio captured by the microphone with a music file:`true`: Replace the audio captured by the microphone with a music file. Users can only hear the music.`false`: Do not replace the audio captured by the microphone with a music file. Users can hear both music and audio captured by the microphone. + +- cycle + + The number of times the music file plays.≥ 0: The number of playback times. For example, 0 means that the SDK does not play the music file while 1 means that the SDK plays once.-1: Play the music effect in an infinite loop. + +- startPos + + The playback position (ms) of the music file. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [startAudioRecording](class_irtcengine.html#api_startaudiorecording3_ng) + +Starts audio recording on the client. + +```cpp +virtual int startAudioRecording(const AudioFileRecordingConfig& config) = 0; +``` + +The Agora SDK allows recording audio on the client during a call. After successfully calling this method, you can record the audio of users in the channel and get an audio recording file. Supported formats of the recording file are as follows: + +- WAV: High-fidelity files with typically larger file sizes. For example, if the sample rate is 32,000 Hz, the file size for 10-minute recording is approximately 73 MB. +- AAC: Low-fidelity files with typically smaller file sizes. For example, if the sample rate is 32,000 Hz and the recording quality is AUDIO_RECORDING_QUALITY_MEDIUM, the file size for 10-minute recording is approximately 2 MB. + +Once the user leaves the channel, the recording automatically stops. + +**Note** Call this method after joining a channel. + +### Parameters + +- config + + Recording configuration. See [AudioRecordingConfiguration](rtc_api_data_type.html#class_audiorecordingconfiguration_ng). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [startChannelMediaRelay](class_irtcengine.html#api_startchannelmediarelay) + +Starts relaying media streams across channels. This method can be used to implement scenarios such as co-host across channels. + +```cpp +virtual int startChannelMediaRelay(const ChannelMediaRelayConfiguration &configuration) = 0; +``` + +After a successful method call, the SDK triggers the [onChannelMediaRelayStateChanged](class_irtcengineeventhandler.html#callback_onchannelmediarelaystatechanged) and [onChannelMediaRelayEvent](class_irtcengineeventhandler.html#callback_onchannelmediarelayevent) callbacks, and these callbacks return the state and events of the media stream relay. + +- If the onChannelMediaRelayStateChanged callback returns RELAY_STATE_RUNNING (2) and RELAY_OK (0), and the onChannelMediaRelayEvent callback returns RELAY_EVENT_PACKET_SENT_TO_DEST_CHANNEL (4), it means that the SDK starts relaying media streams between the source channel and 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 joining the channel. +- This method takes effect only when you are a host in a live streaming channel. +- After a successful method call, if you want to call this method again, ensure that you call the [stopChannelMediaRelay](class_irtcengine.html#api_stopchannelmediarelay) method to quit the current relay. +- Contact [support@agora.io](https://agora-ticket.agora.io/) before implementing this function. +- We do not support string user accounts in this API. + +### Parameters + +- configuration + + The configuration of the media stream relay. For details, see [ChannelMediaRelayConfiguration](rtc_api_data_type.html#class_channelmediarelayconfiguration). + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [onChannelMediaRelayStateChanged](../API/class_irtcengineeventhandler.html#callback_onchannelmediarelaystatechanged) +- [onChannelMediaRelayEvent](../API/class_irtcengineeventhandler.html#callback_onchannelmediarelayevent) + +## [startEchoTest [1/2\]](class_irtcengine.html#api_startechotest) + +Starts an audio call test. + +```cpp +virtual int startEchoTest() = 0; +``` + +- Deprecated: + + This method is deprecated as of v2.4.0. Use [startEchoTest [2/2\]](class_irtcengine.html#api_startechotest2) instead. + +This method starts an audio call test to determine whether the audio devices (for example, headset and speaker) and the network connection are working properly. To conduct the test, the user speaks, and the recording is played back within 10 seconds. If the user can hear the recording within the interval, the audio devices and network connection are working properly. + +**Note** + +- Call this method before joining a channel. +- After calling [stopEchoTest](class_irtcengine.html#api_stopechotest), you must call startEchoTest [1/2] to end the test. Otherwise, the app cannot perform the next echo test, and you cannot join the channel. +- In the live streaming channels, only a host can call this method. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [startEchoTest [2/2\]](class_irtcengine.html#api_startechotest2) + +Starts an audio call test. + +```cpp +virtual int startEchoTest(int intervalInSeconds) = 0; +``` + +This method starts an audio call test to determine whether the audio devices (for example, headset and speaker) and the network connection are working properly. To conduct the test, let the user speak for a while, and the recording is played back within the set interval. If the user can hear the recording within the interval, the audio devices and network connection are working properly. + +**Note** + +- Call this method before joining a channel. +- After calling [stopEchoTest](class_irtcengine.html#api_stopechotest), you must call startEchoTest [2/2] to end the test. Otherwise, the app cannot perform the next echo test, and you cannot join the channel. +- In the live streaming channels, only a host can call this method. + +### Parameters + +- intervalInSeconds + + The time interval (s) between when you speak and when the recording plays back. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [startLastmileProbeTest](class_irtcengine.html#api_startlastmileprobetest) + +Starts the last mile network probe test. + +```cpp +virtual int startLastmileProbeTest(const LastmileProbeConfig& config) = 0; +``` + +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). + +Once this method is enabled, the SDK returns the following callbacks: + +- [onLastmileQuality](class_irtcengineeventhandler.html#callback_onlastmilequality): The SDK triggers this callback within two seconds depending on the network conditions. This callback rates the network conditions and is more closely linked to the user experience. +- [onLastmileProbeResult](class_irtcengineeventhandler.html#callback_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. + +This method applies to the following scenarios: + +- Before a user joins a channel, call this method to check the uplink network quality. +- In a live streaming channel, call this method to check the uplink network quality before an audience member switches to a host. + +**Note** + +- Do not call other methods before receiving the onLastmileQuality and onLastmileProbeResult callbacks. Otherwise, the callbacks may be interrupted. +- A host should not call this method after joining a channel (when in a call). + +### Parameters + +- config + + The configurations of the last-mile network probe test. See [LastmileProbeConfig](rtc_api_data_type.html#class_lastmileprobeconfig). + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [onLastmileQuality](../API/class_irtcengineeventhandler.html#callback_onlastmilequality) +- [onLastmileProbeResult](../API/class_irtcengineeventhandler.html#callback_onlastmileproberesult) + +## [startPreview](class_irtcengine.html#api_startpreview) + +Enables the local video preview. + +```cpp +virtual int startPreview() = 0; +``` + +This method starts the local video preview before joining the channel. Before calling this method, ensure that you do the following: + +- Call [setupLocalVideo](class_irtcengine.html#api_setuplocalvideo) to set the local preview window. +- Call [enableVideo](class_irtcengine.html#api_enablevideo) to enable the video. + +**Note** + +- The local preview enables the mirror mode by default. +- After the local video preview is enabled, if you call [leaveChannel [1/2\]](class_irtcengine.html#api_leavechannel) to exit the channel, the local preview remains until you call [stopPreview](class_irtcengine.html#api_stoppreview) to disable it. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [startPrimaryCameraCapture](class_irtcengine.html#api_startprimarycameracapture) + +Starts video capture with a primary camera. + +```cpp +virtual int startPrimaryCameraCapture(const CameraCapturerConfiguration& config) = 0; +``` + +### Parameters + +- config + + The configuration of the video capture with a primary camera. For details, see [CameraCapturerConfiguration](rtc_api_data_type.html#class_cameracapturerconfiguration_ng). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [startPrimaryScreenCapture](class_irtcengine.html#api_startprimaryscreencapture) + +Starts video capture with a primary camera. + +```cpp +virtual int startPrimaryScreenCapture(const ScreenCaptureConfiguration& config) = 0; +``` + +### Parameters + +- config + + The configuration of the video capture with a primary camera. For details, see [ScreenCaptureConfiguration](rtc_api_data_type.html#class_screencaptureconfiguration). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [startRhythmPlayer](class_irtcengine.html#api_startrhythmplayer) + +Enables the virtual metronome. + +```cpp +virtual int startRhythmPlayer(const char* sound1, const char* sound2, const AgoraRhythmPlayerConfig& config) = 0; +``` + +In music education, physical education and other scenarios, teachers usually need to use a metronome so that students can practice with the correct beat. The meter is composed of a downbeat and upbeats. The first beat of each measure is called a downbeat, and the rest are called upbeats. + +In this method, you need to set the paths of the upbeat and downbeat files, the number of beats per measure, the tempo, and whether to send the sound of the metronome to remote users. + +**Note** + +- This method is for Android and iOS only. +- After enabling the virtual metronome, the SDK plays the specified audio effect file from the beginning, and controls the playback duration of each file according to **beatsPerMinute** you set in [AgoraRhythmPlayerConfig](rtc_api_data_type.html#class_agorarhythmplayerconfig). For example, if you set **beatsPerMinute** as `60`, the SDK plays one beat every second. If the file duration exceeds the beat duration, the SDK only plays the audio within the beat duration. + +### Parameters + +- sound1 + + The absolute path or URL address (including the filename extensions) of the file for the downbeat. For example: `C:\music\audio.mp4`. For the audio file formats supported by this method, see [What formats of audio files does the Agora RTC SDK support](https://docs.agora.io/en/faq/audio_format). + +- sound2 + + The absolute path or URL address (including the filename extensions) of the file for the upbeats. For example: `C:\music\audio.mp4`. For the audio file formats supported by this method, see [What formats of audio files does the Agora RTC SDK support](https://docs.agora.io/en/faq/audio_format). + +- config + + The metronome configuration. See [AgoraRhythmPlayerConfig](rtc_api_data_type.html#class_agorarhythmplayerconfig). + +### Returns + +- 0: Success. +- < 0: Failure. + - -22: Cannot find audio effect files. Please set the correct paths for **sound1** and **sound2**. + +## [startScreenCapture](class_irtcengine.html#api_startscreencapture_ng) + +Starts screen sharing. + +```cpp +virtual int startScreenCapture(void* mediaProjectionPermissionResultData, + const ScreenCaptureParameters& captureParams) = 0; +``` + +After successfully calling this method, you can share the entire screen through [MediaProjection](https://developer.android.google.en/reference/android/media/projection/MediaProjection). + +**Note** + +- This method is for Android only. +- Call this method after joining a channel. +- Before calling this method, you need to implement [onActivityResult](https://developer.android.google.en/reference/android/preference/PreferenceManager.OnActivityResultListener?hl=en#onActivityResult(int, int, android.content.Intent)), an Android native callback, and obtain the value of the **data** parameter in this callback. +- When sharing the screen on Android 10 or later, to avoid the Android system from triggering [SecurityException](https://developer.android.google.en/reference/java/lang/SecurityException), you need to call [startForeground](https://developer.android.google.en/guide/components/foreground-services?hl=en#start) (the Android native method) before calling [MediaProjection](https://developer.android.google.en/reference/android/media/projection/MediaProjection) to notify the user that the current device starts screen sharing. + +### Parameters + +- mediaProjectionPermissionResultData + + Pass in the **data** parameter of the onActivity callback. + +- captureParams + + The screen sharing encoding parameters. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges. For details, see [ScreenCaptureParameters](rtc_api_data_type.html#class_screencaptureparameters). + +### Returns + +- 0: Success. +- < 0: Failure. + - -2(`ERR_INVALID_ARGUMENT`): The **mediaProjectionPermissionResultData** parameter is null. + +## [startScreenCaptureByDisplayId](class_irtcengine.html#api_startscreencapturebydisplayid) + +Shares the screen by specifying the display ID. + + + +```cpp +virtual int startScreenCaptureByDisplayId(unsigned int displayId, const Rectangle& regionRect, + const ScreenCaptureParameters& captureParams) = 0; + +``` + +This method shares a screen or part of the screen. You need to specify the ID of the screen to be shared in this method. + +**Note** + +- This method applies to macOS only. +- Call this method after joining a channel. + +### Parameters + +- displayId + + The display ID of the screen to be shared. This parameter specifies which screen you want to share. + +- regionRect + + (Optional) Sets the relative location of the region to the screen. If you do not set this parameter, the SDK shares the whole screen. For details, see [Rectangle](rtc_api_data_type.html#class_rectangle). If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen. + +- captureParams + + Screen sharing configurations. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges. For details, see [ScreenCaptureParameters](rtc_api_data_type.html#class_screencaptureparameters). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [startScreenCaptureByScreenRect](class_irtcengine.html#api_startscreencapturebyscreenrect) + +Shares the whole or part of a screen by specifying the screen rect. + +```cpp +virtual int startScreenCaptureByScreenRect(const Rectangle& screenRect, + const Rectangle& regionRect, + const ScreenCaptureParameters& captureParams) = 0; +``` + +This method shares a screen or part of the screen. You need to specify the area of the screen to be shared. + +**Note** Call this method after joining a channel. + +### Parameters + +- screenRect + + Sets the relative location of the screen to the virtual screen. + +- regionRect + + (Optional) Sets the relative location of the region to the screen. If you do not set this parameter, the SDK shares the whole screen. See [Rectangle](rtc_api_data_type.html#class_rectangle). If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen. + +- captureParams + + The screen sharing encoding parameters. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges. See [ScreenCaptureParameters](rtc_api_data_type.html#class_screencaptureparameters). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [startScreenCaptureByWindowId](class_irtcengine.html#api_startscreencapturebywindowid) + +Shares the whole or part of a window by specifying the window ID. + + + +```cpp +virtual int startScreenCaptureByWindowId(view_t windowId, + const Rectangle& regionRect, + const ScreenCaptureParameters& captureParams) = 0; +``` + +This method shares a window or part of the window. You need to specify the ID of the window to be shared. + +**Note** + +- Call this method after joining a channel. +- This method applies to macOS and Windows only. + +Since v3.0.0, this method supports window sharing of UWP (Universal Windows Platform) applications. Agora tests the mainstream UWP applications by using the lastest SDK, see details as follows: + +| **System version** | **Software** | **Compatible versions** | **Support** | +| ----------------------------------- | -------------- | ----------------------- | ----------- | +| win10 | Chrome | 76.0.3809.100 | No | +| Office Word | 18.1903.1152.0 | Yes | | +| Office Excel | No | | | +| Office PPT | Yes | | | +| WPS Word | 11.1.0.9145 | Yes | | +| WPS Excel | | | | +| WPS PPT | | | | +| Media Player (come with the system) | All | Yes | | +| win8 | Chrome | All | Yes | +| Office Word | All | Yes | | +| Office Excel | | | | +| Office PPT | | | | +| WPS Word | 11.1.0.9098 | Yes | | +| WPS Excel | | | | +| WPS PPT | | | | +| Media Player (come with the system) | All | Yes | | +| win7 | Chrome | 73.0.3683.103 | No | +| Office Word | All | Yes | | +| Office Excel | | | | +| Office PPT | | | | +| WPS Word | 11.1.0.9098 | No | | +| WPS Excel | | | | +| WPS PPT | 11.1.0.9098 | Yes | | +| Media Player (come with the system) | All | No | | + +### Parameters + +- windowId + + The ID of the window to be shared. + +- regionRect + + (Optional) Sets the relative location of the region to the screen. If you do not set this parameter, the SDK shares the whole screen. For details, see [Rectangle](rtc_api_data_type.html#class_rectangle). If the specified region overruns the window, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole window. + +- captureParams + + Screen sharing configurations. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges. For details, see [ScreenCaptureParameters](rtc_api_data_type.html#class_screencaptureparameters). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [startSecondaryCameraCapture](class_irtcengine.html#api_startsecondarycameracapture) + +Starts video capture with a secondary camera. + +```cpp +virtual int startSecondaryCameraCapture(const CameraCapturerConfiguration& config) = 0; +``` + +### Parameters + +- config + + The configuration of the video capture with a primary camera. For details, see [CameraCapturerConfiguration](rtc_api_data_type.html#class_cameracapturerconfiguration_ng). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [startSecondaryScreenCapture](class_irtcengine.html#api_startsecondaryscreencapture) + +Starts sharing a secondary screen. + +```cpp +virtual int startSecondaryScreenCapture(const ScreenCaptureConfiguration& config) = 0; +``` + +### Parameters + +- config + + The configuration of the captured screen. For details, see [ScreenCaptureConfiguration](rtc_api_data_type.html#class_screencaptureconfiguration). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [stopAllEffects](class_irtcengine.html#api_stopalleffects) + +Stops playing all audio effects. + +```cpp +virtual int stopAllEffects() = 0; +``` + +### Returns + +- 0: Success. +- < 0: Failure. + +## [stopAudioMixing](class_irtcengine.html#api_stopaudiomixing) + +Stops playing and mixing the music file. + +```cpp +virtual int stopAudioMixing() = 0; +``` + +This method stops the audio mixing. Call this method when you are in a channel. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [stopAudioRecording](class_irtcengine.html#api_stopaudiorecording) + +Stops the audio recording on the client. + +```cpp +virtual int stopAudioRecording() = 0; +``` + +If you call [startAudioRecording](class_irtcengine.html#api_startaudiorecording3_ng) to start recording, you can call this method to stop the recording. + +**Note** Once the user leaves the channel, the recording automatically stops. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [stopChannelMediaRelay](class_irtcengine.html#api_stopchannelmediarelay) + +Stops the media stream relay. Once the relay stops, the host quits all the destination channels. + +```cpp +virtual int stopChannelMediaRelay() = 0; +``` + +After a successful method call, the SDK triggers the [onChannelMediaRelayStateChanged](class_irtcengineeventhandler.html#callback_onchannelmediarelaystatechanged) callback. If the callback reports 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) status code. You can call the [leaveChannel [1/2\]](class_irtcengine.html#api_leavechannel) method to leave the channel, and the media stream relay automatically stops. + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [onChannelMediaRelayStateChanged](../API/class_irtcengineeventhandler.html#callback_onchannelmediarelaystatechanged) + +## [stopEchoTest](class_irtcengine.html#api_stopechotest) + +Stops the audio call test. + +```cpp +virtual int stopEchoTest() = 0; +``` + +### Returns + +- 0: Success. +- < 0: Failure. + - -5(ERR_REFUSED): Failed to stop the echo test. The echo test may not be running. + +## [stopEffect](class_irtcengine.html#api_stopeffect) + +Stops playing a specified audio effect. + +```cpp +virtual int stopEffect(int soundId) = 0; +``` + +### Parameters + +- soundId + + The audio effect ID. The ID of each audio effect file is unique. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [stopLastmileProbeTest](class_irtcengine.html#api_stoplastmileprobetest) + +Stops the last mile network probe test. + +```cpp +virtual int stopLastmileProbeTest() = 0; +``` + + + +### Returns + +- 0: Success. +- < 0: Failure. + +## [stopPreview](class_irtcengine.html#api_stoppreview) + +Stops the local video preview. + +```cpp +virtual int stopPreview() = 0; +``` + +### Returns + +- 0: Success. +- < 0: Failure. + +## [stopPrimaryCameraCapture](class_irtcengine.html#api_stopprimarycameracapture) + +Stops capturing video through the first camera. + +```cpp +virtual int stopPrimaryCameraCapture() = 0; +``` + +You can call this method to stop capturing video through the first camera after calling the [startPrimaryCameraCapture](class_irtcengine.html#api_startprimarycameracapture). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [stopPrimaryScreenCapture](class_irtcengine.html#api_stopprimaryscreencapture) + +Stop sharing the first screen. + +```cpp +virtual int stopPrimaryScreenCapture() = 0; +``` + +After calling [startPrimaryScreenCapture](class_irtcengine.html#api_startprimaryscreencapture), you can call this method to stop sharing the first screen. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [stopRhythmPlayer](class_irtcengine.html#api_stoprhythmplayer) + +Disables the virtual metronome. + + + +```cpp +virtual int stopRhythmPlayer() = 0; +``` + +After calling [startRhythmPlayer](class_irtcengine.html#api_startrhythmplayer), you can call this method to disable the virtual metronome. + +**Note** This method is for Android and iOS only. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [stopScreenCapture](class_irtcengine.html#api_stopscreencapture) + +Stops screen sharing. + +```cpp +virtual int stopScreenCapture() = 0; +``` + +### Returns + +- 0: Success. +- < 0: Failure. + +## [stopSecondaryCameraCapture](class_irtcengine.html#api_stopsecondarycameracapture) + +Stops capturing video through the second camera. + +```cpp +virtual int stopSecondaryCameraCapture() = 0; +``` + +You can call this method to stop capturing video through the second camera after calling the [startSecondaryCameraCapture](class_irtcengine.html#api_startsecondarycameracapture). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [stopSecondaryScreenCapture](class_irtcengine.html#api_stopsecondaryscreencapture) + +Stop sharing the second screen. + +```cpp +virtual int stopSecondaryScreenCapture() = 0; +``` + +After calling [startSecondaryScreenCapture](class_irtcengine.html#api_startsecondaryscreencapture), you can call this method to stop sharing the second screen. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [switchCamera](class_irtcengine.html#api_switchcamera) + +Switches between front and rear cameras. + +```cpp +virtual int switchCamera() = 0; +``` + +This method needs to be called after the camera is started (for example, by calling [startPreview](class_irtcengine.html#api_startpreview) or [joinChannel [2/2\]](class_irtcengine.html#api_joinchannel2_ng)). + +**Note** This method is for Android and iOS only. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [takeSnapshot](class_irtcengine.html#api_takesnapshot) + +Takes a snapshot of a video stream. + + + +```cpp +virtual int takeSnapshot(const char* channel, uid_t uid, const char* filePath) = 0; +``` + +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 [onSnapshotTaken](class_irtcengineeventhandler.html#callback_onsnapshottaken) callback to report whether the snapshot is successfully taken as well as the details for the snapshot taken. + +**Note** + +- Call this method after joining a channel. +- If the video of the specified user is pre-processed, for example, added with watermarks or image enhancement effects, the generated snapshot also includes the pre-processing effects. + +### Parameters + +- channel + + The channel name. + +- 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 the filename extensions) of the snapshot. For example,Windows: C:\Users\\AppData\Local\Agora\\example.jpgiOS: /App Sandbox/Library/Caches/example.jpgmacOS: ～/Library/Logs/example.jpgAndroid: /storage/emulated/0/Android/data//files/example.jpgEnsure that the path you specify exists and is writable. + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [onSnapshotTaken](../API/class_irtcengineeventhandler.html#callback_onsnapshottaken) + +## [unloadAllEffects](class_irtcengine.html#api_unloadalleffects) + +releases a specified preloaded audio effect from the memory. + +```cpp +virtual int unloadAllEffects() = 0; +``` + +### Returns + +- 0: Success. +- < 0: Failure. + +## [unloadEffect](class_irtcengine.html#api_unloadeffect) + +Releases a specified preloaded audio effect from the memory. + +```cpp +virtual int unloadEffect(int soundId) = 0; +``` + +### Parameters + +- soundId + + The audio effect ID. The ID of each audio effect file is unique. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [unregisterAudioSpectrumObserver](class_irtcengine.html#api_unregisteraudiospectrumobserver) + +Unregisters the audio spectrum observer. + +```cpp +virtual int unregisterAudioSpectrumObserver(agora::media::IAudioSpectrumObserver * observer) = 0; +``` + +After calling [registerAudioSpectrumObserver](class_irtcengine.html#api_registeraudiospectrumobserver), if you want to disable audio spectrum monitoring, you can call this method. + +**Note** You can call this method either before or after joining a channel. + +### Parameters + +- observer + + The Audio spectrum observer. For details, see [IAudioSpectrumObserver](class_iaudiospectrumobserver.html#class_iaudiospectrumobserver). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [unregisterMediaMetadataObserver](class_irtcengine.html#api_unregistermediametadataobserver) + +Unregisters the specified metadata observer. + +```cpp +virtual int unregisterMediaMetadataObserver(IMetadataObserver* observer, IMetadataObserver::METADATA_TYPE type) = 0; +``` + +### Parameters + +- observer + + The metadata observer. See [IMetadataObserver](class_imetadataobserver.html#class_imetadataobserver). + +- type + + The metadata type. The SDK currently only supports VIDEO_METADATA. For details, see [METADATA_TYPE](class_imetadataobserver.html#enum_metadatatype). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [updateChannelMediaOptions](class_irtcengine.html#api_updatechannelmediaoptions) + +Updates the channel media options after joining the channel. + +### Parameters + +- options + + The channel media options. See [ChannelMediaOptions](rtc_api_data_type.html#class_channelmediaoptions_ng). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [updateChannelMediaRelay](class_irtcengine.html#api_updatechannelmediarelay) + +Updates the channels for media stream relay. + +```cpp +virtual int updateChannelMediaRelay(const ChannelMediaRelayConfiguration &configuration) = 0; +``` + +After the media relay starts, if you want to relay the media stream to more channels, or leave the current relay channel, you can call the updateChannelMediaRelay method. + +After a successful method call, the SDK triggers the [onChannelMediaRelayEvent](class_irtcengineeventhandler.html#callback_onchannelmediarelayevent) callback with the RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL (7) state code. + +**Note** Call this method after the [startChannelMediaRelay](class_irtcengine.html#api_startchannelmediarelay) method to update the destination channel. + +### Parameters + +- configuration + + The configuration of the media stream relay. For more details, see [ChannelMediaRelayConfiguration](rtc_api_data_type.html#class_channelmediarelayconfiguration). + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [onChannelMediaRelayEvent](../API/class_irtcengineeventhandler.html#callback_onchannelmediarelayevent) + +## [updateScreenCaptureParameters](class_irtcengine.html#api_updatescreencaptureparameters) + +Updates the screen sharing parameters. + +```cpp +virtual int updateScreenCaptureParameters(const ScreenCaptureParameters& captureParams) = 0; +``` + + + +### Parameters + +- captureParams + + The screen sharing encoding parameters. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges. For details, see [ScreenCaptureParameters](rtc_api_data_type.html#class_screencaptureparameters). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [updateScreenCaptureRegion](class_irtcengine.html#api_updatescreencaptureregion) + +Updates the screen sharing region. + +```cpp +virtual int updateScreenCaptureRegion(const Rectangle& regionRect) = 0; +``` + + + +### Parameters + +- regionRect + + The relative location of the screen-shared area to the screen or window. If you do not set this parameter, the SDK shares the whole screen or window. See [Rectangle](rtc_api_data_type.html#class_rectangle). If the specified region overruns the screen or window, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen or window. + +### Returns + +- 0: Success. +- < 0: Failure. + - -3(ERR_NOT_READY): No screen or window is being shared. \ No newline at end of file diff --git a/en-US/markdown/Video/API/IRtcEngineEventHandler.md b/en-US/markdown/Video/API/IRtcEngineEventHandler.md new file mode 100644 index 00000000000..c4a571f0beb --- /dev/null +++ b/en-US/markdown/Video/API/IRtcEngineEventHandler.md @@ -0,0 +1,2212 @@ +# [IRtcEngineEventHandler](class_irtcengineeventhandler.html#class_irtcengineeventhandler) + +The SDK uses the IRtcEngineEventHandler interface to send event notifications to your app. Your app can get those notifications through methods that inherit this interface. + +All methods in this interface have default (empty) implementation. You can choose to inherit events related to your app scenario. In the callbacks, avoid implementing time-consuming tasks or calling APIs that may cause thread blocking (such as sendMessage). Otherwise, the SDK may not work properly. + +**See als** + +- [joinChannelEx](../API/class_irtcengineex.html#api_irtcengineex_joinchannelex) +- [joinChannelWithUserAccountEx](../API/class_irtcengineex.html#api_irtcengineex_joinchannelwithuseraccountex) + +## [onActiveSpeaker](class_irtcengineeventhandler.html#callback_onactivespeaker) + +Occurs when the most active speaker is detected. + +```cpp +virtual void onActiveSpeaker(uid_t userId) { (void)userId; } +``` + + + +After a successful call of [enableAudioVolumeIndication](class_irtcengine.html#api_enableaudiovolumeindication), the SDK continuously detects which remote user has the loudest volume. During the current period, the remote user, who is detected as the loudest for the most times, is the most active user. + +When the number of users exceeds two (included) and an active speaker is detected, the SDK triggers this callback and reports the **uid** of the most active speaker. + +- If the most active speaker remains the same, the SDK triggers the onActiveSpeaker callback only once. +- If the most active speaker changes to another user, the SDK triggers this callback again and reports the **uid** of the new active speaker. + +### Parameters + +- userId + + The user ID of the most active speaker. + +## [onApiCallExecuted](class_irtcengineeventhandler.html#callback_onapicallexecuted) + +Occurs when a method is executed by the SDK. + +```cpp +virtual void onApiCallExecuted(int err, + const char* api, + const char* result) { + (void)err; + (void)api; + (void)result; + } +``` + +### Parameters + +- err + + The error code returned by the SDK when the method call fails. If the SDK returns 0, then the method call is successful. + +- api + + The method executed by the SDK. + +- result + + The result of the method call. + +## [onAudioDeviceStateChanged](class_irtcengineeventhandler.html#callback_onaudiodevicestatechanged) + +Occurs when the audio device state changes. + +```cpp +virtual void onAudioDeviceStateChanged(const char* deviceId, + int deviceType, + int deviceState) { + (void)deviceId; + (void)deviceType; + (void)deviceState; + } +``` + +This callback notifies the application that the system's audio device state is changed. For example, a headset is unplugged from the device. + +**Note** This method is for Windows and macOS only. + +### Parameters + +- deviceId + + The device ID. + +- deviceType + + The device type. For details, see [MEDIA_DEVICE_TYPE](rtc_api_data_type.html#enum_mediadevicetype). + +- deviceState + + The device state.on macOS:0: The device is ready for use.8: The device is not connected.On Windows: [MEDIA_DEVICE_STATE_TYPE](rtc_api_data_type.html#enum_mediadevicestatetype). + +## [onAudioEffectFinished](class_irtcengineeventhandler.html#callback_onaudioeffectfinished) + +Occurs when the playback of the local audio effect file finishes. + +```cpp +virtual void onAudioEffectFinished(int soundId) { + } +``` + +This callback occurs when the local audio effect file finishes playing. + +### Parameters + +- soundId + + The audio effect ID. The ID of each audio effect file is unique. + +## [onAudioMixingFinished](class_irtcengineeventhandler.html#callback_onaudiomixingfinished) + +Occurs when the playback of the local music file finishes. + +```cpp +virtual void onAudioMixingFinished() { + } +``` + +- Deprecated: + + This method is deprecated as of v2.4.0. Use [onAudioMixingStateChanged](class_irtcengineeventhandler.html#callback_onaudiomixingstatechanged_ng) instead. + +After you call [startAudioMixing [2/2\]](class_irtcengine.html#api_startaudiomixing2) to play a local music file, this callback occurs when the playback finishes. If the call of startAudioMixing [2/2] fails, the callback returns the error code **WARN_AUDIO_MIXING_OPEN_ERROR**. + +## [onAudioMixingStateChanged](class_irtcengineeventhandler.html#callback_onaudiomixingstatechanged_ng) + +Occurs when the playback state of the music file changes. + +```cpp +virtual void onAudioMixingStateChanged(AUDIO_MIXING_STATE_TYPE state, AUDIO_MIXING_ERROR_TYPE errorCode) { + (void)state; + (void)errorCode; +``` + +This callback occurs when the playback state of the music file changes, and reports the current state and error code. + +### Parameters + +- state + + The playback state of the music file. For details, see [AUDIO_MIXING_STATE_TYPE](rtc_api_data_type.html#enum_audiomixingstatetype). + +- errorCode + + Error code. For details, see [AUDIO_MIXING_ERROR_TYPE](rtc_api_data_type.html#enum_audiomixingerrortype). + +## [onAudioPublishStateChanged](class_irtcengineeventhandler.html#callback_onaudiopublishstatechanged) + +Occurs when the audio publishing state changes. + +```cpp +virtual void onAudioPublishStateChanged(const char* channel, + STREAM_PUBLISH_STATE oldState, + STREAM_PUBLISH_STATE newState, + int elapseSinceLastState) { + (void)channel; + (void)oldState; + (void)newState; + (void)elapseSinceLastState; + } +``` + + + +### Parameters + +- channel + + The name of the channel. + +- oldState + + For the previous publishing state, see [STREAM_PUBLISH_STATE](rtc_api_data_type.html#enum_streampublishstate). + +- newState + + For the current publishing state, see STREAM_PUBLISH_STATE. + +- elapseSinceLastState + + The time elapsed (ms) from the previous state to the current state. + +## [onAudioQuality](class_irtcengineeventhandler.html#callback_onaudioquality) + +Reports the statistics of the audio stream from each remote user. + +```cpp +virtual void onAudioQuality(uid_t uid, int quality, unsigned short delay, unsigned short lost) { + (void)uid; + (void)quality; + (void)delay; + (void)lost; +} +``` + +- Deprecated: + + Deprecated.Please use [onRemoteAudioStats](class_irtcengineeventhandler.html#callback_onremoteaudiostats) instead. + +The SDK triggers this callback once every two seconds to report the audio quality of each remote user/host sending an audio stream. If a channel has multiple users/hosts sending audio streams, the SDK triggers this callback as many times. + +### Parameters + +- uid + + The user ID of the remote user sending the audio stream. + +- quality + + Audio quality of the user. For details, see [QUALITY_TYPE](rtc_api_data_type.html#enum_qualitytype). + +- delay + + The network delay (ms) from the sender to the receiver, including the delay caused by audio sampling pre-processing, network transmission, and network jitter buffering. + +- lost + + Packet loss rate (%) of the audio packet sent from the sender to the receiver. + +## [onAudioRoutingChanged](class_irtcengineeventhandler.html#callback_onaudioroutechanged) + +Occurs when the local audio route changes. + +```cpp +virtual void onAudioRoutingChanged(int routing) { (void)routing; } + +``` + +**注：** + +This method applies to Android and iOS only. + +### Parameters + +- routing + + The current audio routing.-1: Default audio route.0: The audio route is a headset with a microphone.1: The audio route is an earpiece.2: The audio route is a headset without a microphone.3: The audio route is the speaker that comes with the device.4: The audio route is an external speaker.5：The audio route is a Bluetooth headset. + +**See als** + +- [setEnableSpeakerphone](../API/class_irtcengine.html#api_setenablespeakerphone_ng) +- [setDefaultAudioRouteToSpeakerphone](../API/class_irtcengine.html#api_setdefaultaudioroutetospeakerphone_ng) + +## [onAudioSubscribeStateChanged](class_irtcengineeventhandler.html#callback_onaudiosubscribestatechanged) + +Occurs when the audio subscribing state changes. + +```cpp +virtual void onAudioSubscribeStateChanged(const char* channel, + uid_t uid, + STREAM_SUBSCRIBE_STATE oldState, + STREAM_SUBSCRIBE_STATE newState, + int elapseSinceLastState) { + (void)channel; + (void)uid; + (void)oldState; + (void)newState; + (void)elapseSinceLastState; + } +``` + + + +### Parameters + +- channel + + The name of the channel. + +- uid + + The ID of the remote user. + +- oldState + + The previous subscribing status, see [STREAM_SUBSCRIBE_STATE](rtc_api_data_type.html#enum_streamsubscribestate) for details. + +- newState + + The current subscribing status, see STREAM_SUBSCRIBE_STATE for details. + +- elapseSinceLastState + + The time elapsed (ms) from the previous state to the current state. + +## [onAudioVolumeIndication](class_irtcengineeventhandler.html#callback_onaudiovolumeindication) + +Reports the volume information of users. + +```cpp +virtual void onAudioVolumeIndication(const AudioVolumeInfo* speakers, + unsigned int speakerNumber, + int totalVolume) { + (void)speakers; + (void)speakerNumber; + (void)totalVolume; + } +``` + +By default, this callback is disabled. You can enable it by calling [enableAudioVolumeIndication](class_irtcengine.html#api_enableaudiovolumeindication). Once this callback is enabled and users send streams in the channel, the SDK triggers the enableAudioVolumeIndication callback at the time interval set in onAudioVolumeIndication. The SDK triggers two independent onAudioVolumeIndication callbacks simultaneously, which separately report the volume information of the local user who sends a stream and the remote users (up to three) whose instantaneous volumes are the highest. + +**Note** After you enable this callback, calling [muteLocalAudioStream](class_irtcengine.html#api_mutelocalaudiostream) affects the SDK's behavior as follows: + +- If the local user stops publishing the audio stream, the SDK stops triggering the local user's callback. +- 20 seconds after a remote user whose volume is one of the three highest stops publishing the audio stream, the callback excludes this user's information; 20 seconds after all remote users stop publishing audio streams, the SDK stops triggering the callback for remote users. + +### Parameters + +- speakers + + The volume information of the users, see [AudioVolumeInfo](rtc_api_data_type.html#class_audiovolumeinfo). An empty **speakers** array in the callback indicates that no remote user is in the channel or sending a stream at the moment. + +- speakerNumber + + The total number of users.In the callback for the local user, if the local user is sending streams, the value of **speakerNumber** is 1.In the callback for remote users, the value range of **speakerNumber** is [0,3]. If the number of remote users who send streams is greater than or equal to three, the value of **speakerNumber** is 3. + +- totalVolume + + The volume of the speaker. The value range is [0,255].In the callback for the local user, **totalVolume** is the volume of the local user who sends a stream.In the callback for remote users, **totalVolume** is the sum of the volume of all remote users (up to three) whose instantaneous volumes are the highest. If the user calls [startAudioMixing [2/2\]](class_irtcengine.html#api_startaudiomixing2), then **totalVolume** is the volume after audio mixing. + +**See als** + +- [enableAudioVolumeIndication](../API/class_irtcengine.html#api_enableaudiovolumeindication) +- [startPlaybackDeviceTest](../API/class_iaudiodevicemanager.html#api_iaudiodevicemanager_startplaybackdevicetest) +- [startRecordingDeviceTest](../API/class_iaudiodevicemanager.html#api_iaudiodevicemanager_startrecordingdevicetest) +- [startAudioDeviceLoopbackTest](../API/class_iaudiodevicemanager.html#api_iaudiodevicemanager_startaudiodeviceloopbacktest) + +## [onCameraExposureAreaChanged](class_irtcengineeventhandler.html#callback_oncameraexposureareachanged) + +Occurs when the camera exposure area changes. + +```cpp +virtual void onCameraExposureAreaChanged(int x, int y, int width, int height) { + (void)x; + (void)y; + (void)width; + (void)height; + } +``` + +The SDK triggers this callback when the local user changes the camera exposure position by calling [setCameraExposurePosition](class_irtcengine.html#api_setcameraexposureposition). + +**Note** This method is for Android and iOS only. + +### Parameters + +- x + + The x coordinate of the changed camera exposure area. + +- y + + The y coordinate of the changed camera exposure area. + +- width + + The width of the changed camera exposure area. + +- height + + The height of the changed exposure area. + +## [onCameraFocusAreaChanged](class_irtcengineeventhandler.html#callback_oncamerafocusareachanged) + +Occurs when the camera focus area changes. + +```cpp +virtual void onCameraFocusAreaChanged(int x, int y, int width, int height) { + (void)x; + (void)y; + (void)width; + (void)height; + } +``` + +The SDK triggers this callback when the local user changes the camera focus position by calling [setCameraFocusPositionInPreview](class_irtcengine.html#api_setcamerafocuspositioninpreview). + +**Note** This method is for Android and iOS only. + +### Parameters + +- x + + The x coordinate of the changed camera focus area. + +- y + + The y coordinate of the changed camera focus area. + +- width + + The width of the changed camera focus area. + +- height + + The height of the changed camera focus area. + +## [onCameraReady](class_irtcengineeventhandler.html#callback_oncameraready) + +Occurs when the camera turns on and is ready to capture the video. + +```cpp +virtual void onCameraReady() +``` + +- Deprecated: + + Please use LOCAL_VIDEO_STREAM_STATE_CAPTURING(1) in [onLocalVideoStateChanged](class_irtcengineeventhandler.html#callback_onlocalvideostatechanged) instead. + +This callback indicates that the camera has been successfully turned on and you can start to capture video. + +## [onChannelMediaRelayEvent](class_irtcengineeventhandler.html#callback_onchannelmediarelayevent) + +Reports events during the media stream relay. + +```cpp +virtual void onChannelMediaRelayEvent(int code) { + (void)code; +} +``` + + + +### Parameters + +- code + + The event code of channel media relay. See [CHANNEL_MEDIA_RELAY_EVENT](rtc_api_data_type.html#enum_channelmediarelayevent). + +**See als** + +- [startChannelMediaRelay](../API/class_irtcengine.html#api_startchannelmediarelay) +- [updateChannelMediaRelay](../API/class_irtcengine.html#api_updatechannelmediarelay) +- [pauseAllChannelMediaRelay](../API/class_irtcengine.html#api_pauseallchannelmediarelay) +- [resumeAllChannelMediaRelay](../API/class_irtcengine.html#api_resumeallchannelmediarelay) + +## [onChannelMediaRelayStateChanged](class_irtcengineeventhandler.html#callback_onchannelmediarelaystatechanged) + +Occurs when the state of the media stream relay changes. + +```cpp +virtual void onChannelMediaRelayStateChanged(CHANNEL_MEDIA_RELAY_STATE state,CHANNEL_MEDIA_RELAY_ERROR code) { + } +``` + +The SDK returns the state of the current media relay with any error message. + +### Parameters + +- state + + The state code. For details, see [CHANNEL_MEDIA_RELAY_STATE](rtc_api_data_type.html#enum_channelmediarelaystate). + +- code + + The error code of the channel media replay. For details, see [CHANNEL_MEDIA_RELAY_ERROR](rtc_api_data_type.html#enum_channelmediarelayerror). + +**See als** + +- [startChannelMediaRelay](../API/class_irtcengine.html#api_startchannelmediarelay) +- [stopChannelMediaRelay](../API/class_irtcengine.html#api_stopchannelmediarelay) + +## [onClientRoleChanged](class_irtcengineeventhandler.html#callback_onclientrolechanged) + +Occurs when the user role switches in the interactive live streaming. + +```cpp +virtual void onClientRoleChanged(CLIENT_ROLE_TYPE oldRole, CLIENT_ROLE_TYPE newRole) +``` + +The SDK triggers this callback when the local user switches the user role after joining the channel. + +### Parameters + +- oldRole + + Role that the user switches from: [CLIENT_ROLE_TYPE](rtc_api_data_type.html#enum_clientroletype). + +- newRole + + Role that the user switches to: [CLIENT_ROLE_TYPE](rtc_api_data_type.html#enum_clientroletype). + +**See als** + +- [setClientRole [1/2\]](../API/class_irtcengine.html#api_setclientrole) +- [setClientRole [2/2\]](../API/class_irtcengine.html#api_setclientrole2) + +## [onConnectionBanned](class_irtcengineeventhandler.html#callback_onconnectionbanned) + +Occurs when the connection is banned by the Agora server. + +```cpp +virtual void onConnectionBanned() +``` + +- Deprecated: + + Please use [onConnectionStateChanged](class_irtcengineeventhandler.html#callback_onconnectionstatechanged) instead. + +## [onConnectionInterrupted](class_irtcengineeventhandler.html#callback_onconnectioninterrupted) + +Occurs when the connection between the SDK and the server is interrupted. + +```cpp +virtual void onConnectionInterrupted() {} +``` + +- Deprecated: + + Please use [onConnectionStateChanged](class_irtcengineeventhandler.html#callback_onconnectionstatechanged) instead. + +The SDK triggers this callback when it loses connection with the server for more than four seconds after the connection is established. After triggering this callback, the SDK tries to reconnect to the server. You can use this callback to implement pop-up reminders. The difference between this callback and [onConnectionLost](class_irtcengineeventhandler.html#callback_onconnectionlost) is: + +- The SDK triggers the onConnectionInterrupted callback when it loses connection with the server for more than four seconds after it successfully joins the channel. +- The SDK triggers the onConnectionLost callback when it loses connection with the server for more than 10 seconds, whether or not it joins the channel. + +If the SDK fails to rejoin the channel 20 minutes after being disconnected from Agora's edge server, the SDK stops rejoining the channel. + +## [onConnectionLost](class_irtcengineeventhandler.html#callback_onconnectionlost) + +Occurs when the SDK cannot reconnect to Agora's edge server 10 seconds after its connection to the server is interrupted. + +```cpp +virtual void onConnectionLost() +``` + +The SDK triggers this callback when it cannot connect to the server 10 seconds after calling the joinChannel [2/2] method, regardless of whether it is in the channel. If the SDK fails to rejoin the channel 20 minutes after being disconnected from Agora's edge server, the SDK stops rejoining the channel. + +## [onConnectionStateChanged](class_irtcengineeventhandler.html#callback_onconnectionstatechanged) + +Occurs when the network connection state changes. + +```cpp +virtual void onConnectionStateChanged(CONNECTION_STATE_TYPE state, CONNECTION_CHANGED_REASON_TYPE reason) { + (void)state; + (void)reason; + } +``` + +When the network connection state changes, the SDK triggers this callback and reports the current connection state and the reason for the change. + +### Parameters + +- state + + The current connection state. For details, see [CONNECTION_STATE_TYPE](rtc_api_data_type.html#enum_connectionstatetype). + +- reason + + The reason for a connection state change. For details, see [CONNECTION_CHANGED_REASON_TYPE](rtc_api_data_type.html#enum_connectionchangedreasontype). + +**See als** + +- [renewToken](../API/class_irtcengine.html#api_renewtoken) + +## [onEncryptionError](class_irtcengineeventhandler.html#callback_onencryptionerror) + +Reports the built-in encryption errors. + +```cpp +virtual void onEncryptionError(ENCRYPTION_ERROR_TYPE errorType) { + (void)errorType; +} +``` + +When encryption is enabled by calling [enableEncryption](class_irtcengine.html#api_enableencryption), the SDK triggers this callback if an error occurs in encryption or decryption on the sender or the receiver side. + +### Parameters + +- errorType + + For details about the error type, see [ENCRYPTION_ERROR_TYPE](rtc_api_data_type.html#enum_encryptionerrortype). + +## [onError](class_irtcengineeventhandler.html#callback_onerror) + +Reports an error during SDK runtime. + +```cpp +virtual void onError(int err, const char* msg) { + (void)err; + (void)msg; + } +``` + +This callback indicates that an error (concerning network or media) occurs during SDK runtime. In most cases, the SDK cannot fix the issue and resume running. The SDK requires the application to take action or informs the user about the issue. For example, the SDK reports an **ERR_START_CALL** error when failing to initialize a call. The app informs the user that the call initialization failed and calls [leaveChannel [1/2\]](class_irtcengine.html#api_leavechannel) to leave the channel. + +### Parameters + +- err + + The error code. + +## [onExtensionError](class_irtcengineeventhandler.html#callback_onextensionerror) + +Occurs when the extension runs incorrectly. + +```cpp +virtual void onExtensionError(const char* provider, const char* extension, int error, const char* message) { + (void)provider; + (void)extension; + (void)error; + (void)message; + } +``` + +When calling `enableExtension(true)` fails or the extension runs in error, the extension triggers this callback and reports the error code and reason. + +### Parameters + +- provider + + The name of the extension provider. + +- extension + + The name of the extension. + +- error + + Error code. For details, see the extension documentation provided by the extension provider. + +- message + + Reason. For details, see the extension documentation provided by the extension provider. + +**See als** + +- [enableExtension](../API/class_irtcengine.html#api_enableextension) + +## [onExtensionEvent](class_irtcengineeventhandler.html#callback_onextensionevent) + +The event callback of the extension. + +```cpp +virtual void onExtensionEvent(const char* provider, const char* extension, const char* key, const char* value) { + (void)provider; + (void)extension; + (void)key; + (void)value; + } +``` + +To listen for events while the extension is running, you need to register this callback. + +### Parameters + +- provider + + The name of the extension provider. + +- extension + + The name of the extension. + +- key + + The key of the extension. + +- value + + The value of the extension key. + +## [onExtensionStarted](class_irtcengineeventhandler.html#callback_onextensionstarted) + +Occurs when the extension is enabled. + +```cpp +virtual void onExtensionStarted(const char* provider, const char* extension) { + (void)provider; + (void)extension; +} +``` + +After a successful call of `enableExtension(true)`, the extension triggers this callback. + +### Parameters + +- provider + + The name of the extension provider. + +- extension + + The name of the extension. + +**See als** + +- [enableExtension](../API/class_irtcengine.html#api_enableextension) + +## [onExtensionStopped](class_irtcengineeventhandler.html#callback_onextensionstoped) + +Occurs when the extension is disabled. + +```cpp +virtual void onExtensionStopped(const char* provider, const char* extension) { + (void)provider; + (void)extension; + } +``` + +After a successful call of `enableExtension(false)`, the extension triggers this callback. + +### Parameters + +- provider + + The name of the extension provider. + +- extension + + The name of the extension. + +**See als** + +- [enableExtension](../API/class_irtcengine.html#api_enableextension) + +## [onFacePositionChanged](class_irtcengineeventhandler.html#callback_onfacepositionchanged) + +Reports the face detection result of the local user. + +```cpp +virtual void onFacePositionChanged(int imageWidth, int imageHeight, + const Rectangle* vecRectangle, const int* vecDistance, + int numFaces) { + (void) imageWidth; + (void) imageHeight; + (void) vecRectangle; + (void) vecDistance; + (void) numFaces; + } +``` + + + +Once you enable face detection by calling [enableFaceDetection](class_irtcengine.html#api_enablefacedetection)(true), you can get the following information on the local user in real-time: + +- The width and height of the local video. +- The position of the human face in the local video. +- The distance between the human face and the screen. + +The distance between the human face and the screen is based on the fitting calculation of the local video size and the position of the human face captured by the camera. + +**Note** + +- This callback is for Android and iOS only. +- If the SDK does not detect a face, it reduces the frequency of this callback to reduce power consumption on the local device. +- The SDK stops triggering this callback when a human face is in close proximity to the screen. +- On Android, the value of **distance** reported in this callback may be slightly different from the actual distance. Therefore, Agora does not recommend using it for accurate calculation. + +### Parameters + +- imageWidth + + The width (px) of the video image captured by the local camera. + +- imageHeight + + The height (px) of the video image captured by the local camera. + +- vecRectangle + + The information of the detected human face.`x`: The x coordinate (px) of the human face in the local video. Taking the top left corner of the captured video as the origin, the x coordinate represents the relative lateral displacement of the top left corner of the human face to the origin.`y`: The y coordinate (px) of the human face in the local video. Taking the top left corner of the captured video as the origin, the y coordinate represents the relative longitudinal displacement of the top left corner of the human face to the origin.`width`: The `width` (px) of the human face in the captured video.`height`: The `height` (px) of the human face in the captured video. + +- vecDistance + + The distance between the human face and the device screen (cm). + +- numFaces + + The number of faces detected. If the value is 0, it means that no human face is detected. + +## [onFirstLocalAudioFramePublished](class_irtcengineeventhandler.html#callback_onfirstlocalaudioframepublished) + +Occurs when the first audio frame is published. + +```cpp +virtual void onFirstLocalAudioFramePublished(int elapsed) { + (void)elapsed; + } +``` + +The SDK triggers this callback under one of the following circumstances: + +- The local client enables the audio module and calls joinChannel [2/2] successfully. +- The local client calls [muteLocalAudioStream](class_irtcengine.html#api_mutelocalaudiostream)(`true`) and muteLocalAudioStream(`false`) in sequence. +- The local client calls [disableAudio](class_irtcengine.html#api_disableaudio) and [enableAudio](class_irtcengine.html#api_enableaudio) in sequence. +- The[pushAudioFrame](class_imediaengine.html#api_imediaengine_pushaudioframe0) local client calls to successfully push the audio frame to the SDK. + +### Parameters + +- elapsed + + The time elapsed (ms) from the local client calling joinChannel [2/2] until the SDK triggers this callback. + +## [onFirstLocalVideoFrame](class_irtcengineeventhandler.html#callback_onfirstlocalvideoframe) + +Occurs when the first local video frame is rendered. + +```cpp +virtual void onFirstLocalVideoFrame(int width, + int height, + int elapsed) { + (void)width; + (void)height; + (void)elapsed; + } +``` + +The SDK triggers this callback when the first local video frame is displayed/rendered on the local video view. + +### Parameters + +- width + + The width (px) of the first local video frame. + +- height + + The height (px) of the first local video frame. + +- elapsed + + The time elapsed (ms) from the local user calling joinChannel [2/2]until the SDK triggers this callback. If you call [startPreview](class_irtcengine.html#api_startpreview) before calling joinChannel [2/2], then this parameter is the time elapsed from calling the startPreview method until the SDK triggers this callback. + +## [onFirstLocalVideoFramePublished](class_irtcengineeventhandler.html#callback_onfirstlocalvideoframepublished) + +Occurs when the first video frame is published. + +```cpp +virtual void onFirstLocalVideoFramePublished(int elapsed) { + (void)elapsed; + } +``` + +The SDK triggers this callback under one of the following circumstances: + +- The local client enables the video module and calls joinChannel [2/2] successfully. +- The local client calls [muteLocalVideoStream](class_irtcengine.html#api_mutelocalvideostream)(`true`) and muteLocalVideoStream(`false`) in sequence. +- The local client calls [disableVideo](class_irtcengine.html#api_disablevideo) and [enableVideo](class_irtcengine.html#api_enablevideo) in sequence. +- The local client calls [pushVideoFrame [1/2\]](class_imediaengine.html#api_imediaengine_pushvideoframe) to successfully push the video frame to the SDK. + +### Parameters + +- elapsed + + The time elapsed(ms) from the local client calling joinChannel [2/2] until the SDK triggers this callback. + +## [onFirstRemoteAudioFrame](class_irtcengineeventhandler.html#callback_onfirstremoteaudioframe) + +Occurs when the SDK receives the first audio frame from a specific remote user. + +```cpp +virtual void onFirstRemoteAudioFrame(uid_t uid, int elapsed) AGORA_DEPRECATED_ATTRIBUTE { + (void)uid; + (void)elapsed; + } +``` + +- Deprecated: + + Please use [onRemoteAudioStateChanged](class_irtcengineeventhandler.html#callback_onremoteaudiostatechanged) instead. + +### Parameters + +- uid + + The user ID of the remote user. + +- elapsed + + The time elapsed (ms) from the local user calling joinChannel [2/2] until the SDK triggers this callback. + +## [onFirstRemoteAudioDecoded](class_irtcengineeventhandler.html#callback_onfirstremoteaudiodecoded) + +Occurs when the SDK decodes the first remote audio frame for playback. + +```cpp +virtual void onFirstRemoteAudioDecoded(uid_t uid, int elapsed) { + (void)uid; + (void)elapsed; + } + +``` + + + +- Deprecated: + + Please use [onRemoteAudioStateChanged](class_irtcengineeventhandler.html#callback_onremoteaudiostatechanged) instead. + +The SDK triggers this callback under one of the following circumstances: + +- The remote user joins the channel and sends the audio stream for the first time. +- The remote user's audio is offline and then goes online to re-send audio. It means the local user cannot receive audio in 15 seconds. Reasons for such an interruption include: + - The remote user leaves channel. + - The remote user drops offline. + - The remote user calls [muteLocalAudioStream](class_irtcengine.html#api_mutelocalaudiostream) to stop sending the audio stream. + - The remote user calls [disableAudio](class_irtcengine.html#api_disableaudio) to disable audio. + +### Parameters + +- uid + + The ID of the remote user. + +- elapsed + + The time elapsed (ms) from the local user calling joinChannel [2/2] until the SDK triggers this callback. + +## [onFirstRemoteVideoDecoded](class_irtcengineeventhandler.html#callback_onfirstremotevideodecoded) + +Occurs when the first remote video frame is received and decoded. + +```cpp +virtual void onFirstRemoteVideoDecoded(uid_t uid, + int width, + int height, + int elapsed) { + (void)uid; + (void)width; + (void)height; + (void)elapsed; + } +``` + +- Deprecated: + + Please use the [onRemoteVideoStateChanged](class_irtcengineeventhandler.html#callback_onremotevideostatechanged) callback with the following parameters:REMOTE_VIDEO_STATE_STARTING (1).REMOTE_VIDEO_STATE_DECODING (2). + +The SDK triggers this callback under one of the following circumstances: + +- The remote user joins the channel and sends the video stream. +- The remote user stops sending the video stream and re-sends it after 15 seconds. Reasons for such an interruption include: + - The remote user leaves the channel. + - The remote user drops offline. + - The remote user calls [muteLocalVideoStream](class_irtcengine.html#api_mutelocalvideostream) to stop sending the video stream. + - The remote user calls [disableVideo](class_irtcengine.html#api_disablevideo) to disable video. + +### Parameters + +- uid + + The user ID of the remote user sending the video stream. + +- width + + The width (px) of the video stream. + +- height + + The height (px) of the video stream. + +- elapsed + + The time elapsed (ms) from the local user calling joinChannel [2/2] until the SDK triggers this callback. + +## [onFirstRemoteVideoFrame](class_irtcengineeventhandler.html#callback_onfirstremotevideoframe) + +Occurs when the first remote video frame is rendered. + +```cpp +virtual void onFirstRemoteVideoFrame(uid_t userId, int width, int height, int elapsed) { + (void)userId; + (void)width; + (void)height; + (void)elapsed; + } +``` + + + +The SDK triggers this callback when the first local video frame is displayed/rendered on the local video view. The application can retrieve the time elapsed (the **elapsed** parameter) from a user joining the channel until the first video frame is displayed. + +### Parameters + +- userId + + The user ID of the remote user sending the video stream. + +- width + + The width (px) of the video stream. + +- height + + The height (px) of the video stream. + +- elapsed + + Time elapsed (ms) from the local user calling joinChannel [2/2] until the SDK triggers this callback. + +## [onJoinChannelSuccess](class_irtcengineeventhandler.html#callback_onjoinchannelsuccess) + +Occurs when a user joins a channel. + +```cpp +virtual void onJoinChannelSuccess(const char* channel, + uid_t uid, + int elapsed) { + (void)channel; + (void)uid; + (void)elapsed; + } +``` + +This callback notifies the application that a user joins a specified channel. + +### Parameters + +- channel + + The name of the channel. + +- uid + + The ID of the user who joins the channel. + +- elapsed + + The time elapsed (ms) from the local user calling joinChannel [2/2] until the SDK triggers this callback. + +**See als** + +- [joinChannel [1/2\]](../API/class_irtcengine.html#api_joinchannel) +- [joinChannel [2/2\]](../API/class_irtcengine.html#api_joinchannel2_ng) +- [joinChannelWithUserAccountEx](../API/class_irtcengineex.html#api_irtcengineex_joinchannelwithuseraccountex) +- [joinChannelWithUserAccount [1/2\]](../API/class_irtcengine.html#api_joinchannelwithuseraccount) +- [joinChannelWithUserAccount [2/2\]](../API/class_irtcengine.html#api_joinchannelwithuseraccount2) + +## [onLastmileProbeResult](class_irtcengineeventhandler.html#callback_onlastmileproberesult) + +Reports the last mile network probe result. + +```cpp +virtual void onLastmileProbeResult(const LastmileProbeResult& result) { + (void)result; + } +``` + +The SDK triggers this callback within 30 seconds after the app calls [startLastmileProbeTest](class_irtcengine.html#api_startlastmileprobetest). + +### Parameters + +- result + + The uplink and downlink last-mile network probe test result. For details, see [LastmileProbeResult](rtc_api_data_type.html#class_lastmileproberesult). + +**See als** + +- [startLastmileProbeTest](../API/class_irtcengine.html#api_startlastmileprobetest) + +## [onLastmileQuality](class_irtcengineeventhandler.html#callback_onlastmilequality) + +Reports the last-mile network quality of the local user once every two seconds. + +```cpp +virtual void onLastmileQuality(int quality) { + (void)quality; + } +``` + +This callback reports the last-mile network conditions of the local user before the user joins the channel. Last mile refers to the connection between the local device and Agora's edge server. + +Before the user joins the channel, this callback is triggered by the SDK once [startLastmileProbeTest](class_irtcengine.html#api_startlastmileprobetest) is called and reports the last-mile network conditions of the local user. + +### Parameters + +- quality + + The last mile network quality. See [QUALITY_TYPE](rtc_api_data_type.html#enum_qualitytype). + +**See als** + +- [startLastmileProbeTest](../API/class_irtcengine.html#api_startlastmileprobetest) + +## [onLeaveChannel](class_irtcengineeventhandler.html#callback_onleavechannel) + +Occurs when a user leaves a channel. + +```cpp +virtual void onLeaveChannel(const RtcStats& stats) { + (void)stats; + } +``` + +This callback notifies the app that the user leaves the channel by calling [leaveChannel [1/2\]](class_irtcengine.html#api_leavechannel). From this callback, the app can get information such as the call duration and quality statistics. + +### Parameters + +- stats + + The statistics of the call, see [RtcStats](rtc_api_data_type.html#class_rtcstats) . + +**See als** + +- [leaveChannel [1/2\]](../API/class_irtcengine.html#api_leavechannel) +- [leaveChannel [2/2\]](../API/class_irtcengine.html#api_leavechannel2) +- [leaveChannelEx](../API/class_irtcengineex.html#api_irtcengineex_leavechannelex) + +## [onLocalAudioStateChanged](class_irtcengineeventhandler.html#callback_onlocalaudiostatechanged) + +Occurs when the local audio stream state changes. + +```cpp +virtual void onLocalAudioStateChanged(LOCAL_AUDIO_STREAM_STATE state, LOCAL_AUDIO_STREAM_ERROR error) { + (void)state; + (void)error; + } +``` + +When the state of the local audio stream changes (including the state of the audio capture and encoding), the SDK triggers this callback to report the current state. This callback indicates the state of the local audio stream, and allows you to troubleshoot issues when audio exceptions occur. + +**Note** When the state isLOCAL_AUDIO_STREAM_STATE_FAILED (3), you can view the **error** information in the **error** parameter. + +### Parameters + +- state + + The state of the local audio. For details, see [LOCAL_AUDIO_STREAM_STATE](rtc_api_data_type.html#enum_localaudiostreamstate). + +- error + + Local audio state error codes. For details, see [LOCAL_AUDIO_STREAM_ERROR](rtc_api_data_type.html#enum_localaudiostreamerror). + +**See als** + +- [enableLocalAudio](../API/class_irtcengine.html#api_enablelocalaudio) + +## [onLocalAudioStats](class_irtcengineeventhandler.html#callback_onlocalaudiostats) + +Reports the statistics of the local audio stream. + +```cpp +virtual void onLocalAudioStats(const LocalAudioStats& stats) { + (void)stats; + } +``` + +The SDK triggers this callback once every two seconds. + +### Parameters + +- stats + + Local audio statistics. For details, see [LocalAudioStats](rtc_api_data_type.html#class_localaudiostats). + +## [onLocalUserRegistered](class_irtcengineeventhandler.html#callback_onlocaluserregistered) + +Occurs when the local user registers a user account. + + + +```cpp +virtual void onLocalUserRegistered(uid_t uid, const char* userAccount) { + (void)uid; + (void)userAccount; + } +``` + +After the local user successfully calls [registerLocalUserAccount](class_irtcengine.html#api_registerlocaluseraccount) to register the user account or calls joinChannelWithUserAccount [2/2] to join a channel, the SDK triggers the callback and informs the local user's UID and User Account. + +### Parameters + +- uid + + The ID of the local user. + +- userAccount + + The user account of the local user. + +**See als** + +- [registerLocalUserAccount](../API/class_irtcengine.html#api_registerlocaluseraccount) +- [joinChannelWithUserAccount [1/2\]](../API/class_irtcengine.html#api_joinchannelwithuseraccount) +- [joinChannelWithUserAccount [2/2\]](../API/class_irtcengine.html#api_joinchannelwithuseraccount2) +- [joinChannelWithUserAccountEx](../API/class_irtcengineex.html#api_irtcengineex_joinchannelwithuseraccountex) + +## [onLocalVideoStateChanged](class_irtcengineeventhandler.html#callback_onlocalvideostatechanged) + +Occurs when the local video stream state changes. + +```cpp +virtual void onLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE state, LOCAL_VIDEO_STREAM_ERROR error) { + (void)state; + (void)error; + } +``` + + + +When the state of the local video stream changes (including the state of the video capture and encoding), the SDK triggers this callback to report the current state. This callback indicates the state of the local video stream, including camera capturing and video encoding, and allows you to troubleshoot issues when exceptions occur. + +The SDK triggers the onLocalVideoStateChanged callback with the state code `LOCAL_VIDEO_STREAM_STATE_FAILED` and error code `LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE` in the following situations: + +- The app switches to the background, and the system gets the camera resource. +- The camera starts normally, but does not output video for four consecutive seconds. + +When the camera outputs the captured video frames, if the video frames are the same for 15 consecutive frames, the SDK triggers the onLocalVideoStateChanged callback with the state code `LOCAL_VIDEO_STREAM_STATE_CAPTURING` and error code `LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE`. Note that the video frame duplication detection is only available for video frames with a resolution greater than 200 × 200, a frame rate greater than or equal to 10 fps, and a bitrate less than 20 Kbps. + +**Note** For some device models, the SDK does not trigger this callback when the state of the local video changes while the local video capturing device is in use, so you have to make your own timeout judgment. + +### Parameters + +- state + + The state of the local video, see [LOCAL_VIDEO_STREAM_STATE](rtc_api_data_type.html#enum_localvideostreamstate). + +- error + + The detailed error information, see [LOCAL_VIDEO_STREAM_ERROR](rtc_api_data_type.html#enum_localvideostreamerror). + +## [onLocalVideoStats](class_irtcengineeventhandler.html#callback_onlocalvideostats) + +Reports the statistics of the local video stream. + +```cpp +virtual void onLocalVideoStats(const LocalVideoStats& stats) { + (void)stats; + } +``` + +The SDK triggers this callback once every two seconds to report the statistics of the local video stream. + +### Parameters + +- stats + + The statistics of the local video stream. For details, see [LocalVideoStats](rtc_api_data_type.html#class_localvideostats). + +## [onMediaEngineStartCallSuccess](class_irtcengineeventhandler.html#callback_onmediaenginestartcallsuccess) + +Occurs when the media engine call starts. + +```cpp +virtual void onMediaEngineStartCallSuccess() +``` + +## [onNetworkQuality](class_irtcengineeventhandler.html#callback_onnetworkquality) + +Reports the last mile network quality of each user in the channel. + +```cpp +virtual void onNetworkQuality(uid_t uid, int txQuality, int rxQuality) { + (void)uid; + (void)txQuality; + (void)rxQuality; + } +``` + +This callback reports the last mile network conditions of each user in the channel. Last mile refers to the connection between the local device and Agora's edge server. + +The SDK triggers this callback once every two seconds. If a channel includes multiple users, the SDK triggers this callback as many times. + +### Parameters + +- uid + + User ID. The network quality of the user with this user ID is reported. + +- txQuality + + Uplink network quality rating of the user in terms of the transmission bit rate, packet loss rate, average RTT (Round-Trip Time) and jitter of the uplink network. This parameter is a quality rating helping you understand how well the current uplink network conditions can support the selected video encoder configuration. For example, a 1000 Kbps uplink network may be adequate for video frames with a resolution of 640 × 480 and a frame rate of 15 fps in the LIVE_BROADCASTING profile, but might be inadequate for resolutions higher than 1280 × 720. For details, see [QUALITY_TYPE](rtc_api_data_type.html#enum_qualitytype). + +- rxQuality + + Downlink network quality rating of the user in terms of packet loss rate, average RTT, and jitter of the downlink network. For details, see [QUALITY_TYPE](rtc_api_data_type.html#enum_qualitytype). + +## [onNetworkTypeChanged](class_irtcengineeventhandler.html#callback_onnetworktypechanged) + +Occurs when the local network type changes. + +```cpp +virtual void onNetworkTypeChanged(NETWORK_TYPE type) { + (void)type; + } +``` + +This callback occurs when the connection state of the local user changes. You can get the connection state and reason for the state change in this callback. When the network connection is interrupted, this callback indicates whether the interruption is caused by a network type change or poor network conditions. + +### Parameters + +- type + + The type of the local network connection. For details, see [NETWORK_TYPE](rtc_api_data_type.html#enum_networktype). + +## [onPermissionError](class_irtcengineeventhandler.html#callback_onpermissionerror) + +Occurs when the SDK cannot get the device permission. + +```cpp +virtual void onPermissionError(PERMISSION_TYPE permissionType) { + (void)permissionType; +} +``` + +When the SDK fails to get the device permission, the SDK triggers this callback to report which device permission cannot be got. + +**Note** This method is for Android and iOS only. + +### Parameters + +- permissionType + + The type of the device permission. For details, see [PERMISSION_TYPE](rtc_api_data_type.html#enum_permissiontype). + +## [onRejoinChannelSuccess](class_irtcengineeventhandler.html#callback_onrejoinchannelsuccess) + +Occurs when a user rejoins the channel. + +```cpp +virtual void onRejoinChannelSuccess(const char* channel, uid_t uid, int elapsed) { + (void)channel; + (void)uid; + (void)elapsed; + } +``` + +When a user loses connection with the server because of network problems, the SDK automatically tries to reconnect and triggers this callback upon reconnection. + +### Parameters + +- channel + + The name of the channel. + +- uid + + The ID of the user who rejoins the channel. + +- elapsed + + Time elapsed (ms) from starting to reconnect until the SDK triggers this callback. + +**See als** + +- [joinChannel [1/2\]](../API/class_irtcengine.html#api_joinchannel) +- [joinChannel [2/2\]](../API/class_irtcengine.html#api_joinchannel2_ng) + +## [onRemoteAudioStateChanged](class_irtcengineeventhandler.html#callback_onremoteaudiostatechanged) + +Occurs when the remote audio state changes. + +```cpp +virtual void onRemoteAudioStateChanged(uid_t uid, + REMOTE_AUDIO_STATE state, + REMOTE_AUDIO_STATE_REASON reason, + int elapsed) { + (void)uid; + (void)state; + (void)reason; + (void)elapsed; + } +``` + +When the audio state of a remote user (in the voice/video call channel) or host (in the live streaming channel) changes, the SDK triggers this callback to report the current state of the remote audio stream. + +**Note** This callback does not work properly when the number of users (in the voice/video call channel) or hosts (in the live streaming channel) in the channel exceeds 17. + +### Parameters + +- uid + + The ID of the remote user whose audio state changes. + +- state + + The state of the remote audio, see [REMOTE_AUDIO_STATE](rtc_api_data_type.html#enum_remoteaudiostate). + +- reason + + The reason of the remote audio state change, see [REMOTE_AUDIO_STATE_REASON](rtc_api_data_type.html#enum_remoteaudiostatereason). + +- elapsed + + Time elapsed (ms) from the local user calling the joinChannel [2/2] method until the SDK triggers this callback. + +## [onRemoteAudioStats](class_irtcengineeventhandler.html#callback_onremoteaudiostats) + +Reports the transport-layer statistics of each remote audio stream. + +```cpp +virtual void onRemoteAudioStats(const RemoteAudioStats& stats) { + (void)stats; + } +``` + +The SDK triggers this callback once every two seconds for each remote user who is sending audio streams. If a channel includes multiple remote users, the SDK triggers this callback as many times. + +### Parameters + +- stats + + The statistics of the received remote audio streams. See [RemoteAudioStats](rtc_api_data_type.html#class_remoteaudiostats). + +## [onRemoteAudioTransportStats](class_irtcengineeventhandler.html#callback_onremoteaudiotransportstats) + +Reports the transport-layer statistics of each remote audio stream. + +```cpp +virtual void onRemoteAudioTransportStats(uid_t uid, + unsigned short delay, + unsigned short lost, + unsigned short rxKBitRate) { + (void)uid; + (void)delay; + (void)lost; + (void)rxKBitRate; + } +``` + +- Deprecated: + + Please use [onRemoteAudioStats](class_irtcengineeventhandler.html#callback_onremoteaudiostats) instead. + +This callback reports the transport-layer statistics, such as the packet loss rate and network time delay, once every two seconds after the local user receives an audio packet from a remote user. During a call, when the user receives the audio packet sent by the remote user/host, the callback is triggered every 2 seconds. + +### Parameters + +- uid + + The ID of the remote user sending the audio streams. + +- delay + + The network delay (ms) from the sender to the receiver. + +- lost + + Packet loss rate (%) of the audio packet sent from the sender to the receiver. + +- rxKBitrate + + Bitrate of the received audio (Kbps). + +## [onRemoteVideoStateChanged](class_irtcengineeventhandler.html#callback_onremotevideostatechanged) + +Occurs when the remote video state changes. + +```cpp +virtual void onRemoteVideoStateChanged(uid_t uid, + REMOTE_VIDEO_STATE state, + REMOTE_VIDEO_STATE_REASON reason, + int elapsed) { + (void)uid; + (void)state; + (void)reason; + (void)elapsed; + } +``` + +**Note** This callback does not work properly when the number of users (in the voice/video call channel) or hosts (in the live streaming channel) in the channel exceeds 17. + +### Parameters + +- uid + + The ID of the remote user whose video state changes. + +- state + + The state of the remote video, see [REMOTE_VIDEO_STATE](rtc_api_data_type.html#enum_remotevideostate). + +- reason + + The reason for the remote video state change, see [REMOTE_VIDEO_STATE_REASON](rtc_api_data_type.html#enum_remotevideostatereason). + +- elapsed + + Time elapsed (ms) from the local user calling the joinChannel [2/2] method until the SDK triggers this callback. + +**See als** + +- [enableVideo](../API/class_irtcengine.html#api_enablevideo) +- [disableVideo](../API/class_irtcengine.html#api_disablevideo) + +## [onRemoteVideoStats](class_irtcengineeventhandler.html#callback_onremotevideostats) + +Reports the transport-layer statistics of each remote video stream. + +```cpp +virtual void onRemoteVideoStats(const RemoteVideoStats& stats) { + (void)stats; + } +``` + +Reports the statistics of the video stream from the remote users. The SDK triggers this callback once every two seconds for each remote user. If a channel has multiple users/hosts sending video streams, the SDK triggers this callback as many times. + +### Parameters + +- stats + + Statistics of the remote video stream. For details, see [RemoteVideoStats](rtc_api_data_type.html#class_remotevideostats). + +## [onRemoteVideoTransportStats](class_irtcengineeventhandler.html#callback_onremotevideotransportstats) + +Reports the transport-layer statistics of each remote video stream. + +```cpp +virtual void onRemoteVideoTransportStats(uid_t uid, + unsigned short delay, + unsigned short lost, + unsigned short rxKBitRate) { + (void)uid; + (void)delay; + (void)lost; + (void)rxKBitRate; + } +``` + +- Deprecated: + + Please use [onRemoteVideoStats](class_irtcengineeventhandler.html#callback_onremotevideostats) instead. + +This callback reports the transport-layer statistics, such as the packet loss rate and network time delay, once every two seconds after the local user receives a video packet from a remote user. + +During a call, when the user receives the video packet sent by the remote user/host, the callback is triggered every 2 seconds. + +### Parameters + +- uid + + The ID of the remote user sending the video packets. + +- delay + + The network delay (ms) from the sender to the receiver. + +- lost + + The packet loss rate (%) of the video packet sent from the remote user. + +- rxKBitRate + + The bitrate of the received video (Kbps). + +## [onRequestToken](class_irtcengineeventhandler.html#callback_onrequesttoken) + +Occurs when the token expires. + +```cpp +virtual void onRequestToken() +``` + +When the token expires during a call, the SDK triggers this callback to remind the app to renew the token. + +Once you receive this callback, generate a new token on your app server, and call [joinChannel [2/2\]](class_irtcengine.html#api_joinchannel2_ng) to rejoin the channel. + +## [onRtcStats](class_irtcengineeventhandler.html#callback_onrtcstats) + +Reports the statistics of the current call. + +```cpp +virtual void onRtcStats(const RtcStats& stats) { + (void)stats; + } +``` + +The SDK triggers this callback once every two seconds after the user joins the channel. + +### Parameters + +- stats + + Statistics of the RTC engine, see [RtcStats](rtc_api_data_type.html#class_rtcstats) for details. + +## [onRtmpStreamingStateChanged](class_irtcengineeventhandler.html#callback_onrtmpstreamingstatechanged) + +Occurs when the state of the RTMP or RTMPS streaming changes. + +```cpp +virtual void onRtmpStreamingStateChanged(const char *url, + RTMP_STREAM_PUBLISH_STATE state, + RTMP_STREAM_PUBLISH_ERROR errCode) { + (void) url; + (void) state; + (void) errCode; + } +``` + +The SDK triggers this callback to report the result of the local user calling the [addPublishStreamUrl](class_irtcengine.html#api_addpublishstreamurl) or [removePublishStreamUrl](class_irtcengine.html#api_removepublishstreamurl) method. When the RTMP/RTMPS streaming status changes, the SDK triggers this callback and report the URL address and the current status of the streaming. This callback indicates the state of the RTMP or RTMPS streaming. When exceptions occur, you can troubleshoot issues by referring to the detailed error descriptions in the error code parameter. + +### Parameters + +- url + + The CDN streaming URL. + +- state + + The RTMP or RTMPS streaming state, see [RTMP_STREAM_PUBLISH_STATE](rtc_api_data_type.html#enum_rtmpstreampublishstate). When the streaming status is RTMP_STREAM_PUBLISH_STATE_FAILURE(4), you can view the error information in the **errorCode** parameter. + +- errCode + + The detailed error information for streaming, see [RTMP_STREAM_PUBLISH_ERROR](rtc_api_data_type.html#enum_rtmpstreampublisherror). + +**See als** + +- [addPublishStreamUrl](../API/class_irtcengine.html#api_addpublishstreamurl) +- [removePublishStreamUrl](../API/class_irtcengine.html#api_removepublishstreamurl) + +## [onSnapshotTaken](class_irtcengineeventhandler.html#callback_onsnapshottaken) + +Reports the result of taking a video snapshot. + +```cpp +virtual void onSnapshotTaken(const char* channel, uid_t uid, const char* filePath, int width, int height, int errCode) { + (void)channel; + (void)uid; + (void)filePath; + (void)width; + (void)height; + (void)errCode; + } +``` + +After a successful [takeSnapshot](class_irtcengine.html#api_takesnapshot) method call, the SDK triggers this callback to report whether the snapshot is successfully taken as well as the details for the snapshot taken. + +### Parameters + +- channel + + The channel name. + +- uid + + The user ID. A **uid** of 0 indicates the local user. + +- filePath + + The local path of the snapshot. + +- width + + The width (px) of the snapshot. + +- height + + The height (px) of the snapshot. + +- errCode + + The message that confirms success or the reason why the snapshot is not successfully taken:0: Success.< 0: Failure:-1: The SDK fails to write data to a file or encode a JPEG image.-2: The SDK does not find the video stream of the specified user within one second after the takeSnapshot method call succeeds. + +**See als** + +- [takeSnapshot](../API/class_irtcengine.html#api_takesnapshot) + +## [onStreamMessage](class_irtcengineeventhandler.html#callback_onstreammessage) + +Occurs when the local user receives the data stream from the remote user. + +```cpp +virtual void onStreamMessage(uid_t userId, int streamId, const char* data, size_t length, uint64_t sentTs) { + (void)userId; + (void)streamId; + (void)data; + (void)length; + (void)sentTs; +} +``` + + + +The SDK triggers this callback when the local user receives the stream message that the remote user sends by calling the [sendStreamMessage](class_irtcengine.html#api_sendstreammessage) method. + +### Parameters + +- userId + + The ID of the remote user sending the message. + +- streamId + + The stream ID of the received message. + +- data + + The data received. + +- length + + The data length (byte). + +- sentTs + + The time when the data stream is sent. + +**See als** + +- [sendStreamMessageEx](../API/class_irtcengineex.html#api_irtcengineex_sendstreammessageex) +- [sendStreamMessage](../API/class_irtcengine.html#api_sendstreammessage) + +## [onStreamMessageError](class_irtcengineeventhandler.html#callback_onstreammessageerror) + +Occurs when the local user does not receive the data stream from the remote user. + +```cpp +virtual void onStreamMessageError(uid_t userId, int streamId, int code, int missed, int cached) { + (void)userId; + (void)streamId; + (void)code; + (void)missed; + (void)cached; + } +``` + + + +The SDK triggers this callback when the local user fails to receive the stream message that the remote user sends by calling the [sendStreamMessage](class_irtcengine.html#api_sendstreammessage) method. + +### Parameters + +- userId + + The ID of the remote user sending the message. + +- streamId + + The stream ID of the received message. + +- code + + The error code. + +- missed + + The number of lost messages. + +- cached + + Number of incoming cached messages when the data stream is interrupted. + +**See als** + +- [sendStreamMessageEx](../API/class_irtcengineex.html#api_irtcengineex_sendstreammessageex) +- [sendStreamMessage](../API/class_irtcengine.html#api_sendstreammessage) + +## [onStreamPublished](class_irtcengineeventhandler.html#callback_onstreampublished) + +Occurs when an RTMP or RTMPS stream is published. + +```cpp +virtual void onStreamPublished(const char *url, int error) { + (void)url; + (void)error; + } +``` + +- Deprecated: + + Please use [onRtmpStreamingStateChanged](class_irtcengineeventhandler.html#callback_onrtmpstreamingstatechanged) instead. + +Reports the result of publishing an RTMP or RTMPS stream. + +### Parameters + +- url + + The CDN streaming URL. + +- error + + Error codes of the RTMP or RTMPS streaming.`ERR_OK` (0): The publishing succeeds.`ERR_FAILED` (1): The publishing fails.`ERR_INVALID_ARGUMENT` (-2): Invalid argument used. If you do not call [setLiveTranscoding](class_irtcengine.html#api_setlivetranscoding) to configure [LiveTranscoding](rtc_api_data_type.html#class_livetranscoding) before calling [addPublishStreamUrl](class_irtcengine.html#api_addpublishstreamurl), the SDK reports `ERR_INVALID_ARGUMENT`.`ERR_TIMEDOUT` (10): The publishing timed out.`ERR_ALREADY_IN_USE` (19): The chosen URL address is already in use for CDN live streaming.`ERR_ENCRYPTED_STREAM_NOT_ALLOWED_PUBLISH` (130): You cannot publish an encrypted stream.`ERR_PUBLISH_STREAM_CDN_ERROR` (151): CDN related error. Remove the original URL address and add a new one by calling the [removePublishStreamUrl](class_irtcengine.html#api_removepublishstreamurl) and [addPublishStreamUrl](class_irtcengine.html#api_addpublishstreamurl) methods.`ERR_PUBLISH_STREAM_NUM_REACH_LIMIT` (152): The host manipulates more than 10 URLs. Delete the unnecessary URLs before adding new ones.`ERR_PUBLISH_STREAM_NOT_AUTHORIZED` (153): The host manipulates other hosts' URLs. Please check your app logic.`ERR_PUBLISH_STREAM_INTERNAL_SERVER_ERROR` (154): An error occurs in Agora's streaming server. Call the [removePublishStreamUrl](class_irtcengine.html#api_removepublishstreamurl) method to publish the streaming again.`ERR_PUBLISH_STREAM_FORMAT_NOT_SUPPORTED` (156): The format of the CDN streaming URL is not supported. Check whether the URL format is correct. + +## [onStreamUnpublished](class_irtcengineeventhandler.html#callback_onstreamunpublished) + +Occurs when an RTMP or RTMPS stream is removed. + +```cpp +virtual void onStreamUnpublished(const char *url) { + (void)url; + } +``` + +- Deprecated: + + Please use [onRtmpStreamingStateChanged](class_irtcengineeventhandler.html#callback_onrtmpstreamingstatechanged) instead. + +### Parameters + +- url + + The URL of the removed RTMP or RTMPS stream. + +## [onTokenPrivilegeWillExpire](class_irtcengineeventhandler.html#callback_ontokenprivilegewillexpire) + +Occurs when the token expires in 30 seconds. + +```cpp +virtual void onTokenPrivilegeWillExpire(const char* token) { + (void)token; + } +``` + +When the token is about to expire in 30 seconds, the SDK triggers this callback to remind the app to renew the token. + +Upon receiving this callback, generate a new token on your server, and call [renewToken](class_irtcengine.html#api_renewtoken) to pass the new token to the SDK. + +### Parameters + +- token + + The token that expires in 30 seconds. + +**See als** + +- [renewToken](../API/class_irtcengine.html#api_renewtoken) + +## [onTranscodingUpdated](class_irtcengineeventhandler.html#callback_ontranscodingupdated) + +Occurs when the publisher's transcoding is updated. + +```cpp +virtual void onTranscodingUpdated() +``` + +When the [LiveTranscoding](rtc_api_data_type.html#class_livetranscoding) class in the [setLiveTranscoding](class_irtcengine.html#api_setlivetranscoding) method updates, the SDK triggers the onTranscodingUpdated callback to report the update information. + +**Note** If you call the setLiveTranscoding method to set the LiveTranscoding class for the first time, the SDK does not trigger this callback. + +**See als** + +- [setLiveTranscoding](../API/class_irtcengine.html#api_setlivetranscoding) + +## [onUplinkNetworkInfoUpdated](class_irtcengineeventhandler.html#callback_onuplinknetworkinfoupdated) + +Occurs when the uplink network information changes. + +```cpp +virtual void onUplinkNetworkInfoUpdated(const UplinkNetworkInfo& info) { + (void)info; +} +``` + +The SDK triggers this callback when the uplink network information changes. + +**Note** This callback only applies to scenarios where you push externally encoded video data in H.264 format to the SDK. + +### Parameters + +- info + + The uplink network information. See [UplinkNetworkInfo](rtc_api_data_type.html#class_uplinknetworkinfo). + +## [onUserEnableLocalVideo](class_irtcengineeventhandler.html#callback_onuserenablelocalvideo) + +Occurs when a specific remote user enables/disables the local video capturing function. + +```cpp +virtual void onUserEnableLocalVideo(uid_t uid, bool enabled) { + (void)uid; + (void)enabled; + } +``` + +The SDK triggers this callback when the remote user resumes or stops capturing the video stream by calling the [enableLocalVideo](class_irtcengine.html#api_enablelocalvideo) method. + +### Parameters + +- uid + + The user ID of the remote user. + +- enabled + + Whether the specified remote user enables/disables the local video capturing function:`true`: Enable. Other users in the channel can see the video of this remote user.`false`: Disable. Other users in the channel can no longer receive the video stream from this remote user, while this remote user can still receive the video streams from other users. + +**See als** + +- [enableLocalVideo](../API/class_irtcengine.html#api_enablelocalvideo) + +## [onUserEnableVideo](class_irtcengineeventhandler.html#callback_onuserenablevideo) + +Occurs when a remote user enables/disables the video module. + +```cpp +virtual void onUserEnableVideo(uid_t uid, bool enabled) { + (void)uid; + (void)enabled; + } +``` + +Once the video module is disabled, the user can only use a voice call. The user cannot send or receive any video. + +The SDK triggers this callback when a remote user enables or disables the video module by calling the [enableVideo](class_irtcengine.html#api_enablevideo) or [disableVideo](class_irtcengine.html#api_disablevideo) method. + +### Parameters + +- uid + + The user ID of the remote user. + +- enabled + + `true`: Enable.`false`: Disable. + +**See als** + +- [enableVideo](../API/class_irtcengine.html#api_enablevideo) +- [disableVideo](../API/class_irtcengine.html#api_disablevideo) + +## [onUserInfoUpdated](class_irtcengineeventhandler.html#callback_onuserinfoupdated) + +Occurs when the SDK gets the user ID and user account of the remote user. + + + +```cpp +virtual void onUserInfoUpdated(uid_t uid, const UserInfo& info) { + (void)uid; + (void)info; + } +``` + +After a remote user joins the channel, the SDK gets the UID and user account of the remote user, caches them in a mapping table object, and triggers this callback on the local client. + +### Parameters + +- uid + + The ID of the remote user. + +- info + + The UserInfo object that contains the user ID and user account of the remote user. See [UserInfo](rtc_api_data_type.html#class_userinfo) for details. + +**See als** + +- [joinChannelWithUserAccountEx](../API/class_irtcengineex.html#api_irtcengineex_joinchannelwithuseraccountex) +- [joinChannelWithUserAccount [1/2\]](../API/class_irtcengine.html#api_joinchannelwithuseraccount) +- [joinChannelWithUserAccount [2/2\]](../API/class_irtcengine.html#api_joinchannelwithuseraccount2) + +## [onUserJoined](class_irtcengineeventhandler.html#callback_onuserjoined) + +Occurs when a remote user (COMMUNICATION)/ host (LIVE_BROADCASTING) joins the channel. + +```cpp +virtual void onUserJoined(uid_t uid, int elapsed) { + (void)uid; + (void)elapsed; + } +``` + +- In a communication channel, this callback indicates that a remote user joins the channel. The SDK also triggers this callback to report the existing users in the channel when a user joins the channel. +- In a live-broadcast channel, this callback indicates that a host joins the channel. The SDK also triggers this callback to report the existing hosts in the channel when a host joins the channel. Agora recommends limiting the number of hosts to 17. + +The SDK triggers this callback under one of the following circumstances: + +- A remote user/host joins the channel by calling the joinChannel [2/2] method. +- A remote user switches the user role to the host after joining the channel. +- A remote user/host rejoins the channel after a network interruption. + +### Parameters + +- uid + + The ID of the user or host who joins the channel. + +- elapsed + + Time delay (ms) from the local user calling joinChannel [2/2] until this callback is triggered. + +**See als** + +- [joinChannel [1/2\]](../API/class_irtcengine.html#api_joinchannel) +- [joinChannel [2/2\]](../API/class_irtcengine.html#api_joinchannel2_ng) +- [setClientRole [1/2\]](../API/class_irtcengine.html#api_setclientrole) +- [setClientRole [2/2\]](../API/class_irtcengine.html#api_setclientrole2) +- [joinChannelWithUserAccountEx](../API/class_irtcengineex.html#api_irtcengineex_joinchannelwithuseraccountex) +- [joinChannelWithUserAccount [1/2\]](../API/class_irtcengine.html#api_joinchannelwithuseraccount) +- [joinChannelWithUserAccount [2/2\]](../API/class_irtcengine.html#api_joinchannelwithuseraccount2) + +## [onUserMuteAudio](class_irtcengineeventhandler.html#callback_onusermuteaudio) + +Occurs when a remote user (in the communication profile)/ host (in the live streaming profile) joins the channel. + +```cpp +virtual void onUserMuteAudio(uid_t uid, bool muted) { + (void)uid; + (void)muted; + } +``` + +The SDK triggers this callback when the remote user stops or resumes sending the audio stream by calling the [muteLocalAudioStream](class_irtcengine.html#api_mutelocalaudiostream) method. + +**Note** This callback does not work properly when the number of users (in the communication profile) or hosts (in the live streaming profile) in the channel exceeds 17. + +### Parameters + +- uid + + User ID. + +- muted + + Whether the remote user's audio stream is muted/unmuted:`true`: Muted.`false`: Unmuted. + +**See als** + +- [muteLocalAudioStream](../API/class_irtcengine.html#api_mutelocalaudiostream) + +## [onUserMuteVideo](class_irtcengineeventhandler.html#callback_onusermutevideo) + +Occurs when a remote user's video stream playback pauses/resumes. + +```cpp +virtual void onUserMuteVideo(uid_t uid, bool muted) { + (void)uid; + (void)muted; + } +``` + +The SDK triggers this callback when the remote user stops or resumes sending the video stream by calling the [muteLocalVideoStream](class_irtcengine.html#api_mutelocalvideostream) method. + +**Note** This callback does not work properly when the number of users (in the COMMUNICATION profile) or hosts (in the LIVE_BROADCASTING profile) in the channel exceeds 17. + +### Parameters + +- uid + + The ID of the remote user. + +- muted + + Whether the remote user's video stream playback is paused/resumed:`true`: Paused.`false`: Resumed. + +**See als** + +- [muteLocalVideoStream](../API/class_irtcengine.html#api_mutelocalvideostream) + +## [onUserOffline](class_irtcengineeventhandler.html#callback_onuseroffline) + +Occurs when a remote user (COMMUNICATION)/ host (LIVE_BROADCASTING) leaves the channel. + +```cpp +virtual void onUserOffline(uid_t uid, USER_OFFLINE_REASON_TYPE reason) { + (void)uid; + (void)reason; + } +``` + +There are two reasons for users to become offline: + +- Leave the channel: When a user/host leaves the channel, the user/host sends a goodbye message. When this message is received, the SDK determines that the user/host leaves the channel. +- Drop offline: When no data packet of the user or host is received for a certain period of time (20 seconds for the communication profile, and more for the live broadcast profile), the SDK assumes that the user/host drops offline. A poor network connection may lead to false detections. It's recommended to use the Agora RTM SDK for reliable offline detection. + +### Parameters + +- uid + + The ID of the user who leaves the channel or goes offline. + +- reason + + Reasons why the user goes offline: [USER_OFFLINE_REASON_TYPE](rtc_api_data_type.html#enum_userofflinereasontype). + +**See als** + +- [setClientRole [1/2\]](../API/class_irtcengine.html#api_setclientrole) +- [setClientRole [2/2\]](../API/class_irtcengine.html#api_setclientrole2) +- [leaveChannel [1/2\]](../API/class_irtcengine.html#api_leavechannel) +- [leaveChannel [2/2\]](../API/class_irtcengine.html#api_leavechannel2) +- [leaveChannelEx](../API/class_irtcengineex.html#api_irtcengineex_leavechannelex) + +## [onVideoPublishStateChanged](class_irtcengineeventhandler.html#callback_onvideopublishstatechanged) + +Occurs when the video publishing state changes. + +```cpp +virtual void onVideoPublishStateChanged(const char* channel, STREAM_PUBLISH_STATE oldState, STREAM_PUBLISH_STATE newState, int elapseSinceLastState) { + (void)channel; + (void)oldState; + (void)newState; + (void)elapseSinceLastState; + } +``` + + + +### Parameters + +- channel + + The name of the channel. + +- oldState + + For the previous publishing state, see [STREAM_PUBLISH_STATE](rtc_api_data_type.html#enum_streampublishstate). + +- newState + + For the current publishing state, see STREAM_PUBLISH_STATE. + +- elapseSinceLastState + + The time elapsed (ms) from the previous state to the current state. + +## [onVideoSizeChanged](class_irtcengineeventhandler.html#callback_onvideosizechanged) + +Occurs when the video size or rotation of a specified user changes. + +```cpp +virtual void onVideoSizeChanged(uid_t uid, + int width, + int height, + int rotation) { + (void)uid; + (void)width; + (void)height; + (void)rotation; + } +``` + +### Parameters + +- uid + + The ID of the user whose video size or rotation changes. **uid** is 0 for the local user. + +- width + + The width (pixels) of the video stream. + +- height + + The height (pixels) of the video stream. + +- rotation + + The rotation information. The value range is [0,360). + +## [onVideoStopped](class_irtcengineeventhandler.html#callback_onvideostopped) + +Occurs when the video stops playing. + +```cpp +virtual void onVideoStopped() +``` + +- Deprecated: + + Please use LOCAL_VIDEO_STREAM_STATE_STOPPED(0) in the [onLocalVideoStateChanged](class_irtcengineeventhandler.html#callback_onlocalvideostatechanged) callback instead. + +The application can use this callback to change the configuration of the **view** (for example, displaying other pictures in the view) after the video stops playing. + +## [onVideoSubscribeStateChanged](class_irtcengineeventhandler.html#callback_onvideosubscribestatechanged) + +Occurs when the video subscribing state changes. + +```cpp +virtual void onVideoSubscribeStateChanged(const char* channel, + uid_t uid, + STREAM_SUBSCRIBE_STATE oldState, + STREAM_SUBSCRIBE_STATE newState, + int elapseSinceLastState) { + (void)channel; + (void)uid; + (void)oldState; + (void)newState; + (void)elapseSinceLastState; + } +``` + + + +### Parameters + +- channel + + The name of the channel. + +- uid + + The ID of the remote user. + +- oldState + + The previous subscribing status, see [STREAM_SUBSCRIBE_STATE](rtc_api_data_type.html#enum_streamsubscribestate) for details. + +- newState + + The current subscribing status, see STREAM_SUBSCRIBE_STATE for details. + +- elapseSinceLastState + + The time elapsed (ms) from the previous state to the current state. + +## [onWarning](class_irtcengineeventhandler.html#callback_onwarning) + +Reports a warning during SDK runtime. + +```cpp +virtual void onWarning(int warn, const char* msg) { + (void)warn; + (void)msg; + } +``` + +Occurs when a warning occurs during SDK runtime. In most cases, the app can ignore the warnings reported by the SDK because the SDK can usually fix the issue and resume running. For example, when losing connection with the server, the SDK may report **WARN_LOOKUP_CHANNEL_TIMEOUT** and automatically try to reconnect. + +### Parameters + +- warn + + Warning codes. + +- msg + + Warning description. \ No newline at end of file diff --git a/en-US/markdown/Video/API/IRtcEngineEx.md b/en-US/markdown/Video/API/IRtcEngineEx.md new file mode 100644 index 00000000000..2acfd31f16f --- /dev/null +++ b/en-US/markdown/Video/API/IRtcEngineEx.md @@ -0,0 +1,561 @@ +# [IRtcEngineEx](class_irtcengineex.html#class_irtcengineex) + +This interface class contains multi-channel methods. + +Inherited from [IRtcEngine](class_irtcengine.html#class_irtcengine). + +## [addPublishStreamUrlEx](class_irtcengineex.html#api_addpublishstreamurlex) + +Publishes the local stream to a specified CDN live streaming URL. + +```cpp +virtual int addPublishStreamUrlEx(const char* url, bool transcodingEnabled, const RtcConnection& connection) = 0; +``` + +After calling this method, you can push media streams in RTMP or RTMPS protocol to the CDN according to [RtcConnection](rtc_api_data_type.html#class_rtcconnection). The SDK triggers the [onRtmpStreamingStateChanged](class_irtcengineeventhandler.html#callback_onrtmpstreamingstatechanged) callback on the local client to report the state of adding a local stream to the CDN. + +**Note** + +- Call this method after joining a channel. +- Ensure that the media push function is enabled. +- This method takes effect only when you are a host in live interactive streaming. +- This method adds only one streaming URL to the CDN each time it is called. To push multiple URLs, call this method multiple times. +- In one [IRtcEngineEx](class_irtcengineex.html#class_irtcengineex) instance, you can only push one upstream media stream to the CDN (such as the video stream captured by the camera or the video stream for screen sharing selected by the RtcConnection). +- Agora only supports pushing media streams to the CDN in RTMPS protocol when you enable transcoding. + +### Parameters + +- url + + The CDN streaming URL in the RTMP or RTMPS format. The maximum length of this parameter is 1024 bytes. The URL address must not contain special characters, such as Chinese language characters. + +- transcodingEnabled + + Whether to enable transcoding. [Transcoding](https://docs.agora.io/en/Agora Platform/transcoding) in a CDN live streaming converts the audio and video streams before pushing them to the CDN server. It applies to scenarios where a channel has multiple broadcasters and composite layout is needed.`true`: Enable transcoding.`false`: Disable transcoding.**Note** If you set this parameter as `true`, ensure that you call the [setLiveTranscoding](class_irtcengine.html#api_setlivetranscoding) method before calling this method. + +- connection + + The connection info. For details, see [RtcConnection](rtc_api_data_type.html#class_rtcconnection). + +### Returns + +- 0: Success. +- < 0: Failure. + - -2: Invalid parameter, usually an empty URL or a string with a length of 0. + - -7: The engine is not initialized when streaming. + +## [addVideoWatermarkEx](class_irtcengineex.html#api_irtcengineex_addvideowatermarkex) + +Adds a watermark image to the local video. + +```cpp +virtual int addVideoWatermarkEx(const char* watermarkUrl, + const WatermarkOptions& options, + const RtcConnection& connection) = 0; +``` + +This method adds a PNG watermark image to the local video in the live streaming. Once the watermark image is added, all the audience in the channel (CDN audience included), and the capturing device can see and capture it. Agora supports adding only one watermark image onto the local video, and the newly watermark image replaces the previous one. + +The watermark coordinates are dependent on the settings in the [setVideoEncoderConfigurationEx](class_irtcengineex.html#api_irtcengineex_setvideoencoderconfigurationex) method: + +- If the orientation mode of the encoding video ([ORIENTATION_MODE](rtc_api_data_type.html#enum_orientationmode)) is FIXED_LANDSCAPE, or the landscape mode in ADAPTIVE, the watermark uses the landscape orientation. +- If the orientation mode of the encoding video (ORIENTATION_MODE) is FIXED_PORTRAIT, or the portrait mode in ADAPTIVE, the watermark uses the portrait orientation. +- When setting the watermark position, the region must be less than the dimensions set in the setVideoEncoderConfigurationEx method. Otherwise, the watermark image will be cropped. + +**Note** + +- Ensure that you have called [enableVideo](class_irtcengine.html#api_enablevideo) before calling this 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](class_irtcengine.html#api_startpreview) method, you can use the `visibleInPreview` member to set whether or not the watermark is visible in the 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 + + The options of the watermark image to be added. For details, see [WatermarkOptions](rtc_api_data_type.html#class_watermarkoptions). + +- connection + + The connection info. For details, see [RtcConnection](rtc_api_data_type.html#class_rtcconnection). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [clearVideoWatermarkEx](class_irtcengineex.html#api_irtcengineex_clearvideowatermarkex) + +Removes the watermark image from the video stream. + +```cpp +virtual int clearVideoWatermarkEx(const RtcConnection& connection) = 0; +``` + +### Parameters + +- connection + + The connection info. For details, see [RtcConnection](rtc_api_data_type.html#class_rtcconnection). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [createDataStreamEx [1/2\]](class_irtcengineex.html#api_irtcengineex_createdatastreamex) + +Creates a data stream. + +```cpp +virtual int createDataStreamEx(int* streamId, bool reliable, bool ordered, const RtcConnection& connection) = 0; +``` + +- Deprecated: + + This method is deprecated. Please use [createDataStreamEx [2/2\]](class_irtcengineex.html#api_irtcengineex_createdatastreamex2) instead. + +You can call this method to create a data stream and improve the reliability and ordering of data transmission. + +**Note** + +- Ensure that you set the same value for `reliable` and `ordered`. +- Each user can create up to five data streams during the lifecycle of [IRtcEngine](class_irtcengine.html#class_irtcengine). +- 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 + +- streamId + + Output parameter. Pointer to the ID of the created data stream. + +- 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 in the sent order.`false`: The recipients receive the data in the sent order. + +- connection + + The connection info. For details, see [RtcConnection](rtc_api_data_type.html#class_rtcconnection). + +### Returns + +- 0: The data stream is successfully created. +- < 0: Fails to create the data stream. + +## [createDataStreamEx [2/2\]](class_irtcengineex.html#api_irtcengineex_createdatastreamex2) + +Creates a data stream. + +```cpp +virtual int createDataStreamEx(int* streamId, DataStreamConfig& config, const RtcConnection& connection) = 0; +``` + +Creates a data stream. Each user can create up to five data streams in a single channel. + +Compared with [createDataStreamEx [1/2\]](class_irtcengineex.html#api_irtcengineex_createdatastreamex), this method does not support data reliability. If a data packet is not received five seconds after it was sent, the SDK directly discards the data. + +### Parameters + +- streamId + + Output parameter. Pointer to the ID of the created data stream. + +- config + + The configurations for the data stream. For details, see [DataStreamConfig](rtc_api_data_type.html#class_datastreamconfig). + +- connection + + The connection info. For details, see [RtcConnection](rtc_api_data_type.html#class_rtcconnection). + +### Returns + +- 0: The data stream is successfully created. +- < 0: Failure. + +## [enableLoopbackRecordingEx](class_irtcengineex.html#api_irtcengineex_enableloopbackrecordingex) + +Enables loopback audio capturing. + +```cpp +virtual int enableLoopbackRecordingEx(bool enabled, const RtcConnection& connection) = 0; +``` + +If you enable loopback audio capturing, the output of the sound card is mixed into the audio stream sent to the other end. + +**Note** + +This method applies to macOS and Windows only. + +### Parameters + +- connection + + The connection info. For details, see [RtcConnection](rtc_api_data_type.html#class_rtcconnection). + +- enabled + + Sets whether to enable loopback audio capturing.`true`: Enable loopback audio capturing.`false`: (Default) Disable loopback audio capturing. + +### Returns + +- 0: Success. +- < 0: Failure. + +## [getConnectionStateEx](class_irtcengineex.html#api_irtcengineex_getconnectionstateex) + +Gets the current connection state of the SDK. + +```cpp +virtual CONNECTION_STATE_TYPE getConnectionStateEx(const RtcConnection& connection) = 0; +``` + +You can call this method either before or after joining a channel. + +### Parameters + +- connection + + The connection info. For details, see [RtcConnection](rtc_api_data_type.html#class_rtcconnection). + +### Returns + +The current connection state. For details, see [CONNECTION_STATE_TYPE](rtc_api_data_type.html#enum_connectionstatetype). + +## [joinChannelEx](class_irtcengineex.html#api_irtcengineex_joinchannelex) + +Joins a channel with the connection ID. + +```cpp +virtual int joinChannelEx(const char* token, const RtcConnection& connection, + const ChannelMediaOptions& options, + IRtcEngineEventHandler* eventHandler) = 0; +``` + +You can call this method multiple times to join more than one channels. + +**Note** + +- If you are already in a channel, you cannot rejoin it with the same user ID. +- We recommend using different user IDs for different channels. +- If you want to join the same channel from different devices, ensure that the user IDs in all devices are different. +- Ensure that the App ID you use to generate the token is the same with the App ID used when creating the [IRtcEngine](class_irtcengine.html#class_irtcengine) instance. + +### Parameters + +- token + + The token generated on your server for authentication. See [Authenticate Your Users with Token](https://docs.agora.io/en/live-streaming-4.x-preview/token_server_android_ng?platform=Windows). + +- connection + + The connection info. For details, see [RtcConnection](rtc_api_data_type.html#class_rtcconnection). + +- options + + The channel media options. See [ChannelMediaOptions](rtc_api_data_type.html#class_channelmediaoptions_ng) for details. + +- eventHandler + + The callback class of [IRtcEngineEx](class_irtcengineex.html#class_irtcengineex). For details, see [IRtcEngineEventHandler](class_irtcengineeventhandler.html#class_irtcengineeventhandler). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [joinChannelWithUserAccountEx](class_irtcengineex.html#api_irtcengineex_joinchannelwithuseraccountex) + +Joins the channel with a user account, and configures whether to automatically subscribe to audio or video streams after joining the channel. + +```cpp +virtual int joinChannelWithUserAccountEx(const char* token, const char* channelId, + const char* userAccount, const ChannelMediaOptions& options, + IRtcEngineEventHandler* eventHandler) = 0; +``` + +This method allows a user to join the channel with the user account. After the user successfully joins the channel, the SDK triggers the following callbacks: + +- The local client: [onLocalUserRegistered](class_irtcengineeventhandler.html#callback_onlocaluserregistered), [onJoinChannelSuccess](class_irtcengineeventhandler.html#callback_onjoinchannelsuccess) and [onConnectionStateChanged](class_irtcengineeventhandler.html#callback_onconnectionstatechanged) callbacks. +- The remote client: The [onUserJoined](class_irtcengineeventhandler.html#callback_onuserjoined) callback if the user is in the COMMUNICATION profile, and the [onUserInfoUpdated](class_irtcengineeventhandler.html#callback_onuserinfoupdated) callback if the user is a host in the LIVE_BROADCASTING profile. + +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. + +**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 ID of the user is set to the same parameter type. + +### Parameters + +- token + + The token generated on your server for authentication. See [Authenticate Your Users with Token](https://docs.agora.io/en/live-streaming-4.x-preview/token_server_android_ng?platform=Windows). + +- 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.Space"!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "= ", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", "," + +- userAccount + + The user account. This parameter is used to identify the user in the channel for real-time audio and video engagement. You need to set and manage user accounts yourself and ensure that each user account in the same channel is unique. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as NULL. Supported characters are (89 in total):The 26 lowercase English letters: a to z.The 26 uppercase English letters: A to Z.All numeric characters: 0 to 9.Space"!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", "," + +- options + + The channel media options. See [ChannelMediaOptions](rtc_api_data_type.html#class_channelmediaoptions_ng) for details. + +- eventHandler + + The callback class of [IRtcEngineEx](class_irtcengineex.html#class_irtcengineex). For details, see [IRtcEngineEventHandler](class_irtcengineeventhandler.html#class_irtcengineeventhandler). + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [onLocalUserRegistered](../API/class_irtcengineeventhandler.html#callback_onlocaluserregistered) +- [onJoinChannelSuccess](../API/class_irtcengineeventhandler.html#callback_onjoinchannelsuccess) +- [onUserJoined](../API/class_irtcengineeventhandler.html#callback_onuserjoined) +- [onUserInfoUpdated](../API/class_irtcengineeventhandler.html#callback_onuserinfoupdated) + +## [leaveChannelEx](class_irtcengineex.html#api_irtcengineex_leavechannelex) + +Leaves a channel. + +```cpp +virtual int leaveChannelEx(const RtcConnection& connection) = 0; +``` + +### Parameters + +- connection + + The connection info. For details, see [RtcConnection](rtc_api_data_type.html#class_rtcconnection). + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [onLeaveChannel](../API/class_irtcengineeventhandler.html#callback_onleavechannel) +- [onUserOffline](../API/class_irtcengineeventhandler.html#callback_onuseroffline) + +## [muteRemoteAudioStreamEx](class_irtcengineex.html#api_irtcengineex_muteremoteaudiostreamex) + +Stops or resumes receiving the audio stream of a specified user. + +```cpp +virtual int muteRemoteAudioStreamEx(uid_t uid, bool mute, const RtcConnection& connection) = 0; +``` + +This method is used to stops or resumes receiving the audio stream of a specified user. 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. + +- connection + + The connection info. For details, see [RtcConnection](rtc_api_data_type.html#class_rtcconnection). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [muteRemoteVideoStreamEx](class_irtcengineex.html#api_irtcengineex_muteremotevideostreamex) + +Stops or resumes receiving the video stream of a specified user. + +```cpp +virtual int muteRemoteVideoStreamEx(uid_t uid, bool mute, const RtcConnection& connection) = 0; +``` + +This method is used to stops or resumes receiving the video stream of a specified user. 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 user ID of the remote 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. + +- connection + + The connection info. For details, see [RtcConnection](rtc_api_data_type.html#class_rtcconnection). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [sendCustomReportMessageEx](class_irtcengineex.html#api_irtcengineex_sendcustomreportmessageex) + +Agora supports reporting and analyzing customized messages. + +```cpp +virtual int sendCustomReportMessageEx(const char* id, const char* category, const char* event, const char* label, + int value, const RtcConnection& connection) = 0; +``` + +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 and each string not exceeding 100 bytes. To try out this function, contact [support@agora.io](mailto:support@agora.io) and discuss the format of customized messages with us. + +## [setRemoteVoicePositionEx](class_irtcengineex.html#api_setremotevoicepositionex) + +Sets the 2D position (the position on the horizontal plane) of the remote user's voice. + +```cpp +virtual int setRemoteVoicePositionEx(uid_t uid, double pan, double gain, const RtcConnection& connection) = 0; +``` + +This method sets the voice position and volume of a remote user. + +When the local user calls this method to set the voice position of a remote user, the voice difference between the left and right channels allows the local user to track the real-time position of the remote user, creating a sense of space. This method applies to massive multiplayer online games, such as Battle Royale games. + +**Note** + +- For the best voice positioning, Agora recommends using a wired headset. +- Call this method after joining a channel. + +### Parameters + +- uid + + The user ID of the remote user. + +- pan + + The voice position of the remote user. The value ranges from -1.0 to 1.0:-1.0: The remote voice comes from the left.0.0: (Default) The remote voice comes from the front.1.0: The remote voice comes from the right. + +- gain + + The volume of the remote user. The value ranges from 0.0 to 100.0. The default value is 100.0 (the original volume of the remote user). The smaller the value, the lower the volume. + +- connection + + The connection info. For details, see [RtcConnection](rtc_api_data_type.html#class_rtcconnection). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [setVideoEncoderConfigurationEx](class_irtcengineex.html#api_irtcengineex_setvideoencoderconfigurationex) + +Sets the encoder configuration for the local video. + +```cpp +virtual int setVideoEncoderConfigurationEx(const VideoEncoderConfiguration& config, const RtcConnection& connection) = 0; +``` + +Each configuration profile corresponds to a set of video parameters, including the resolution, frame rate, and bitrate. + +The **config** specified in this method is the maximum values under ideal network conditions. If the video engine cannot render the video using the specified **config** due to unreliable network conditions, the parameters further down the list are considered until a successful configuration is found. + +### Parameters + +- config + + Video profile. For details, see [VideoEncoderConfiguration](rtc_api_data_type.html#class_videoencoderconfiguration). + +- connection + + The connection info. For details, see [RtcConnection](rtc_api_data_type.html#class_rtcconnection). + +### Returns + +- 0: Success. +- < 0: Failure. + +## [sendStreamMessageEx](class_irtcengineex.html#api_irtcengineex_sendstreammessageex) + +Sends data stream messages. + +```cpp +virtual int sendStreamMessageEx(int streamId, const char* data, size_t length, const RtcConnection& connection) = 0; +``` + +After calling [createDataStreamEx [2/2\]](class_irtcengineex.html#api_irtcengineex_createdatastreamex2), you can call this method to send data stream messages to all users in the channel. + +The SDK has the following restrictions on this method: + +- Up to 30 packets can be sent per second in a channel with each packet having a maximum size of 1 kB. +- Each client can send up to 6 KB of data per second. +- Each user can have up to five data streams simultaneously. + +A successful method call triggers the [onStreamMessage](class_irtcengineeventhandler.html#callback_onstreammessage) callback on the remote client, from which the remote user gets the stream message. A failed method call triggers the [onStreamMessageError](class_irtcengineeventhandler.html#callback_onstreammessageerror) callback on the remote client. + +**Note** + +- Ensure that you call createDataStreamEx [2/2] to create a data channel before calling this method. +- 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 data stream ID. You can get the data stream ID by calling createDataStreamEx [2/2]. + +- data + + The message to be sent. + +- length + + The length of the data. + +- connection + + The connection info. For details, see [RtcConnection](rtc_api_data_type.html#class_rtcconnection). + +### Returns + +- 0: Success. +- < 0: Failure. + +**See also** + +- [onStreamMessage](../API/class_irtcengineeventhandler.html#callback_onstreammessage) +- [onStreamMessageError](../API/class_irtcengineeventhandler.html#callback_onstreammessageerror) + +## [updateChannelMediaOptionsEx](class_irtcengineex.html#api_irtcengineex_updatechannelmediaoptionsex) + +Updates the channel media options after joining the channel. + +```cpp +virtual int updateChannelMediaOptionsEx(const ChannelMediaOptions& options, const RtcConnection& connection) = 0; +``` + +### Parameters + +- options + + The channel media options. See [ChannelMediaOptions](rtc_api_data_type.html#class_channelmediaoptions_ng). + +- connection + + The connection info. For details, see [RtcConnection](rtc_api_data_type.html#class_rtcconnection). + +### Returns + +- 0: Success. +- < 0: Failure. \ No newline at end of file diff --git a/en-US/markdown/Video/API/api_overview.md b/en-US/markdown/Video/API/api_overview.md new file mode 100644 index 00000000000..5ce7c2a4b08 --- /dev/null +++ b/en-US/markdown/Video/API/api_overview.md @@ -0,0 +1,602 @@ +# API Overview + +Agora provides ensured quality of experience (QoE) for worldwide Internet-based voice and video communications through SD-RTN™. + +## Channel management + +| Method | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [createAgoraRtcEngine](class_irtcengine.html#api_createagorartcengine) | Creates the IRtcEngine object. | +| [initialize](class_irtcengine.html#api_create2) | Initializes IRtcEngine. | +| [release](class_irtcengine.html#api_release) | Releases the IRtcEngine instance. | +| [setChannelProfile](class_irtcengine.html#api_setchannelprofile) | Sets the channel profile. | +| [joinChannel [1/2\]](class_irtcengine.html#api_joinchannel) | Joins a channel. | +| [joinChannel [2/2\]](class_irtcengine.html#api_joinchannel2_ng) | Joins a channel with media options. | +| [updateChannelMediaOptions](class_irtcengine.html#api_updatechannelmediaoptions) | Updates the channel media options after joining the channel. | +| [leaveChannel [1/2\]](class_irtcengine.html#api_leavechannel) | Leaves a channel. | +| [leaveChannel [2/2\]](class_irtcengine.html#api_leavechannel2) | Leaves a channel. | +| [renewToken](class_irtcengine.html#api_renewtoken) | Gets a new token when the current token expires after a period of time. | +| [setClientRole [1/2\]](class_irtcengine.html#api_setclientrole) | Sets the client role. | +| [setClientRole [2/2\]](class_irtcengine.html#api_setclientrole2) | Sets the user role and level in an interactive live streaming channel. | +| [getConnectionState](class_irtcengine.html#api_getconnectionstate) | Gets the current connection state of the SDK. | + +## Channel events + +| Event | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [onJoinChannelSuccess](class_irtcengineeventhandler.html#callback_onjoinchannelsuccess) | Occurs when a user joins a channel. | +| [onRejoinChannelSuccess](class_irtcengineeventhandler.html#callback_onrejoinchannelsuccess) | Occurs when a user rejoins the channel. | +| [onClientRoleChanged](class_irtcengineeventhandler.html#callback_onclientrolechanged) | Occurs when the user role switches in the interactive live streaming. | +| [onLeaveChannel](class_irtcengineeventhandler.html#callback_onleavechannel) | Occurs when a user leaves a channel. | +| [onUserJoined](class_irtcengineeventhandler.html#callback_onuserjoined) | Occurs when a remote user (COMMUNICATION)/ host (LIVE_BROADCASTING) joins the channel. | +| [onUserOffline](class_irtcengineeventhandler.html#callback_onuseroffline) | Occurs when a remote user (COMMUNICATION)/ host (LIVE_BROADCASTING) leaves the channel. | +| [onUserMuteAudio](class_irtcengineeventhandler.html#callback_onusermuteaudio) | Occurs when a remote user (in the communication profile)/ host (in the live streaming profile) joins the channel. | +| [onNetworkTypeChanged](class_irtcengineeventhandler.html#callback_onnetworktypechanged) | Occurs when the local network type changes. | +| [onUplinkNetworkInfoUpdated](class_irtcengineeventhandler.html#callback_onuplinknetworkinfoupdated) | Occurs when the uplink network information changes. | +| [onConnectionLost](class_irtcengineeventhandler.html#callback_onconnectionlost) | Occurs when the SDK cannot reconnect to Agora's edge server 10 seconds after its connection to the server is interrupted. | +| [onConnectionStateChanged](class_irtcengineeventhandler.html#callback_onconnectionstatechanged) | Occurs when the network connection state changes. | +| [onRequestToken](class_irtcengineeventhandler.html#callback_onrequesttoken) | Occurs when the token expires. | +| [onTokenPrivilegeWillExpire](class_irtcengineeventhandler.html#callback_ontokenprivilegewillexpire) | Occurs when the token expires in 30 seconds. | + +## Audio management + +| Method | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [enableAudio](class_irtcengine.html#api_enableaudio) | Enables the audio module. | +| [disableAudio](class_irtcengine.html#api_disableaudio) | Disables the audio module. | +| [setAudioProfile [1/2\]](class_irtcengine.html#api_setaudioprofile) | Sets the audio profile and audio scenario. | +| [setAudioProfile [2/2\]](class_irtcengine.html#api_setaudioprofile2) | Sets the audio parameters and application scenarios. | +| [adjustRecordingSignalVolume](class_irtcengine.html#api_adjustrecordingsignalvolume) | Adjusts the capturing signal volume. | +| [adjustUserPlaybackSignalVolume](class_irtcengine.html#api_adjustuserplaybacksignalvolume) | Adjusts the playback signal volume of a specified remote user. | +| [adjustPlaybackSignalVolume](class_irtcengine.html#api_adjustplaybacksignalvolume) | Adjusts the playback signal volume of all remote users. | +| [adjustLoopbackRecordingVolume](class_irtcengine.html#api_adjustloopbackrecordingvolume) | Adjusts the volume of the signal captured by the sound card. | +| [enableLocalAudio](class_irtcengine.html#api_enablelocalaudio) | Enables/Disables the local audio capture. | +| [muteLocalAudioStream](class_irtcengine.html#api_mutelocalaudiostream) | Stops or resumes publishing the local audio stream. | +| [muteRemoteAudioStream](class_irtcengine.html#api_muteremoteaudiostream) | Stops or resumes subscribing to the audio stream of a specified user. | +| [muteAllRemoteAudioStreams](class_irtcengine.html#api_muteallremoteaudiostreams) | Stops or resumes subscribing to the audio streams of all remote users. | +| [setDefaultMuteAllRemoteAudioStreams](class_irtcengine.html#api_setdefaultmuteallremoteaudiostreams) | Stops or resumes subscribing to the audio streams of all remote users by default. | +| [getAudioDeviceInfo](class_irtcengine.html#api_getaudiodeviceinfo) | Gets the audio device information. | + +## Video management + +| Method | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [enableVideo](class_irtcengine.html#api_enablevideo) | Enables the video module. | +| [disableVideo](class_irtcengine.html#api_disablevideo) | Disables the video module. | +| [setVideoEncoderConfiguration](class_irtcengine.html#api_setvideoencoderconfiguration) | Sets the video encoder configuration. | +| [startPreview](class_irtcengine.html#api_startpreview) | Enables the local video preview. | +| [stopPreview](class_irtcengine.html#api_stoppreview) | Stops the local video preview. | +| [setupLocalVideo](class_irtcengine.html#api_setuplocalvideo) | Initializes the local video view. | +| [setupRemoteVideo](class_irtcengine.html#api_setupremotevideo) | Initializes the video view of a remote user. | +| [setLocalRenderMode [2/2\]](class_irtcengine.html#api_setlocalrendermode2) | Updates the display mode of the local video view. | +| [setRemoteRenderMode](class_irtcengine.html#api_setremoterendermode2) | Updates the display mode of the video view of a remote user. | +| [enableLocalVideo](class_irtcengine.html#api_enablelocalvideo) | Enables/Disables the local video capture. | +| [muteLocalVideoStream](class_irtcengine.html#api_mutelocalvideostream) | Stops or resumes publishing the local video stream. | +| [muteRemoteVideoStream](class_irtcengine.html#api_muteremotevideostream) | Stops or resumes subscribing to the video stream of a specified user. | +| [muteAllRemoteVideoStreams](class_irtcengine.html#api_muteallremotevideostreams) | Stops or resumes subscribing to the video streams of all remote users. | +| [setDefaultMuteAllRemoteVideoStreams](class_irtcengine.html#api_setdefaultmuteallremotevideostreams) | Stops or resumes subscribing to the video streams of all remote users by default. | + +## Capture screenshots + +| Method | Description | +| ------------------------------------------------------ | ----------------------------------- | +| [takeSnapshot](class_irtcengine.html#api_takesnapshot) | Takes a snapshot of a video stream. | + +| Event | Description | +| ------------------------------------------------------------ | ---------------------------------------------- | +| [onSnapshotTaken](class_irtcengineeventhandler.html#callback_onsnapshottaken) | Reports the result of taking a video snapshot. | + +## Multi-device capture + +| Method | Description | +| ------------------------------------------------------------ | ------------------------------------------------ | +| [startPrimaryCameraCapture](class_irtcengine.html#api_startprimarycameracapture) | Starts video capture with a primary camera. | +| [startPrimaryScreenCapture](class_irtcengine.html#api_startprimaryscreencapture) | Starts video capture with a primary camera. | +| [startSecondaryCameraCapture](class_irtcengine.html#api_startsecondarycameracapture) | Starts video capture with a secondary camera. | +| [startSecondaryScreenCapture](class_irtcengine.html#api_startsecondaryscreencapture) | Starts sharing a secondary screen. | +| [stopPrimaryCameraCapture](class_irtcengine.html#api_stopprimarycameracapture) | Stops capturing video through the first camera. | +| [stopPrimaryScreenCapture](class_irtcengine.html#api_stopprimaryscreencapture) | Stop sharing the first screen. | +| [stopSecondaryCameraCapture](class_irtcengine.html#api_stopsecondarycameracapture) | Stops capturing video through the second camera. | +| [stopSecondaryScreenCapture](class_irtcengine.html#api_stopsecondaryscreencapture) | Stop sharing the second screen. | + +## Media player + +| Method | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [createMediaPlayer](class_irtcengine.html#api_createmediaplayer) | Creates a media player instance. | +| [IMediaPlayer](class_imediaplayer.html#class_imediaplayer) | This class provides media player functions and supports multiple instances. | +| [IMediaPlayerSourceObserver](class_imediaplayersourceobserver.html#class_imediaplayersourceobserver) | Provides callbacks for media players. | + +## Local media events + +| Event | Description | +| ------------------------------------------------------------ | ------------------------------------------------- | +| [onLocalAudioStateChanged](class_irtcengineeventhandler.html#callback_onlocalaudiostatechanged) | Occurs when the local audio stream state changes. | +| [onLocalVideoStateChanged](class_irtcengineeventhandler.html#callback_onlocalvideostatechanged) | Occurs when the local video stream state changes. | +| [onFirstLocalAudioFramePublished](class_irtcengineeventhandler.html#callback_onfirstlocalaudioframepublished) | Occurs when the first audio frame is published. | +| [onFirstLocalVideoFramePublished](class_irtcengineeventhandler.html#callback_onfirstlocalvideoframepublished) | Occurs when the first video frame is published. | +| [onAudioPublishStateChanged](class_irtcengineeventhandler.html#callback_onaudiopublishstatechanged) | Occurs when the audio publishing state changes. | +| [onVideoPublishStateChanged](class_irtcengineeventhandler.html#callback_onvideopublishstatechanged) | Occurs when the video publishing state changes. | + +## Remote media events + +| Event | Description | +| ------------------------------------------------------------ | ------------------------------------------------ | +| [onRemoteAudioStateChanged](class_irtcengineeventhandler.html#callback_onremoteaudiostatechanged) | Occurs when the remote audio state changes. | +| [onRemoteVideoStateChanged](class_irtcengineeventhandler.html#callback_onremotevideostatechanged) | Occurs when the remote video state changes. | +| [onAudioSubscribeStateChanged](class_irtcengineeventhandler.html#callback_onaudiosubscribestatechanged) | Occurs when the audio subscribing state changes. | +| [onVideoSubscribeStateChanged](class_irtcengineeventhandler.html#callback_onvideosubscribestatechanged) | Occurs when the video subscribing state changes. | + +## Statistics events + +| Event | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [onRtcStats](class_irtcengineeventhandler.html#callback_onrtcstats) | Reports the statistics of the current call. | +| [onNetworkQuality](class_irtcengineeventhandler.html#callback_onnetworkquality) | Reports the last mile network quality of each user in the channel. | +| [onLocalAudioStats](class_irtcengineeventhandler.html#callback_onlocalaudiostats) | Reports the statistics of the local audio stream. | +| [onLocalVideoStats](class_irtcengineeventhandler.html#callback_onlocalvideostats) | Reports the statistics of the local video stream. | +| [onRemoteAudioStats](class_irtcengineeventhandler.html#callback_onremoteaudiostats) | Reports the transport-layer statistics of each remote audio stream. | +| [onRemoteVideoStats](class_irtcengineeventhandler.html#callback_onremotevideostats) | Reports the transport-layer statistics of each remote video stream. | + +## Video pre-process and post-process + +| Method | Description | +| ------------------------------------------------------------ | ------------------------------------------------------- | +| [setBeautyEffectOptions](class_irtcengine.html#api_setbeautyeffectoptions) | Sets the image enhancement options. | +| [enableVirtualBackground](class_irtcengine.html#api_enablevirtualbackground) | Enables/Disables the virtual background. (beta feature) | + +## In-ear monitoring + +**Attention:** + +This method is for Android and iOS only. + +| Method | Description | +| ------------------------------------------------------------ | -------------------------------------- | +| [enableInEarMonitoring](class_irtcengine.html#api_enableinearmonitoring2) | Enables in-ear monitoring. | +| [setInEarMonitoringVolume](class_irtcengine.html#api_setinearmonitoringvolume) | Sets the volume of the in-ear monitor. | + +## Music file playback and mixing + +| Method | Description | +| ------------------------------------------------------------ | ------------------------------------------------------- | +| [startAudioMixing [2/2\]](class_irtcengine.html#api_startaudiomixing2) | Starts playing the music file. | +| [stopAudioMixing](class_irtcengine.html#api_stopaudiomixing) | Stops playing and mixing the music file. | +| [pauseAudioMixing](class_irtcengine.html#api_pauseaudiomixing) | Pauses playing and mixing the music file. | +| [resumeAudioMixing](class_irtcengine.html#api_resumeaudiomixing) | Resumes playing and mixing the music file. | +| [adjustAudioMixingVolume](class_irtcengine.html#api_adjustaudiomixingvolume) | Adjusts the volume during audio mixing. | +| [adjustAudioMixingPlayoutVolume](class_irtcengine.html#api_adjustaudiomixingplayoutvolume) | Adjusts the volume of audio mixing for local playback. | +| [adjustAudioMixingPublishVolume](class_irtcengine.html#api_adjustaudiomixingpublishvolume) | Adjusts the volume of audio mixing for publishing. | +| [getAudioMixingPlayoutVolume](class_irtcengine.html#api_getaudiomixingplayoutvolume) | Retrieves the audio mixing volume for local playback. | +| [getAudioMixingPublishVolume](class_irtcengine.html#api_getaudiomixingpublishvolume) | Retrieves the audio mixing volume for publishing. | +| [getAudioMixingDuration](class_irtcengine.html#api_getaudiomixingduration) | Retrieves the duration (ms) of the music file. | +| [getAudioMixingCurrentPosition](class_irtcengine.html#api_getaudiomixingcurrentposition) | Retrieves the playback position (ms) of the music file. | +| [setAudioMixingPitch](class_imediaplayer.html#api_setaudiomixingpitch) | Sets the pitch of the local music file. | +| [setAudioMixingPosition](class_irtcengine.html#api_setaudiomixingposition) | Sets the audio mixing position. | + +| Event | Description | +| ------------------------------------------------------------ | --------------------------------------------------------- | +| [onAudioMixingStateChanged](class_irtcengineeventhandler.html#callback_onaudiomixingstatechanged_ng) | Occurs when the playback state of the music file changes. | + +## Audio effect file playback + +| Method | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [getEffectsVolume](class_irtcengine.html#api_geteffectsvolume) | Retrieves the volume of the audio effects. | +| [setEffectsVolume](class_irtcengine.html#api_seteffectsvolume) | Sets the volume of the audio effects. | +| [getVolumeOfEffect](class_irtcengine.html#api_getvolumeofeffect) | Gets the volume of a specified audio effect. | +| [setVolumeOfEffect](class_irtcengine.html#api_setvolumeofeffect) | Sets the volume of a specified audio effect. | +| [preloadEffect](class_irtcengine.html#api_preloadeffect) | Preloads a specified audio effect file into the memory. | +| [playEffect](class_irtcengine.html#api_playeffect3) | Plays the specified local or online audio effect file. | +| [playAllEffects](class_irtcengine.html#api_playalleffects) | Plays all audio effects. | +| [pauseEffect](class_irtcengine.html#api_pauseeffect) | Pauses a specified audio effect. | +| [pauseAllEffects](class_irtcengine.html#api_pausealleffects) | Pauses all audio effects. | +| [resumeEffect](class_irtcengine.html#api_resumeeffect) | Resumes playing a specified audio effect. | +| [resumeAllEffects](class_irtcengine.html#api_resumealleffects) | Resumes playing all audio effects. | +| [stopEffect](class_irtcengine.html#api_stopeffect) | Stops playing a specified audio effect. | +| [stopAllEffects](class_irtcengine.html#api_stopalleffects) | Stops playing all audio effects. | +| [unloadEffect](class_irtcengine.html#api_unloadeffect) | Releases a specified preloaded audio effect from the memory. | +| [unloadAllEffects](class_irtcengine.html#api_unloadalleffects) | releases a specified preloaded audio effect from the memory. | + +## Virtual metronome + +**Attention:** + +This method is for Android and iOS only. + +| Method | Description | +| ------------------------------------------------------------ | --------------------------------- | +| [startRhythmPlayer](class_irtcengine.html#api_startrhythmplayer) | Enables the virtual metronome. | +| [stopRhythmPlayer](class_irtcengine.html#api_stoprhythmplayer) | Disables the virtual metronome. | +| [configRhythmPlayer](class_irtcengine.html#api_configrhythmplayer) | Configures the virtual metronome. | + +## Voice changer and reverberation + +| Method | Description | +| ------------------------------------------------------------ | -------------------------------------------------------- | +| [setLocalVoiceEqualization](class_irtcengine.html#api_setlocalvoiceequalization) | Sets the local voice equalization effect. | +| [setLocalVoicePitch](class_irtcengine.html#api_setlocalvoicepitch) | Changes the voice pitch of the local speaker. | +| [setLocalVoiceReverb](class_irtcengine.html#api_setlocalvoicereverb) | Sets the local voice reverberation. | +| [setVoiceBeautifierPreset](class_irtcengine.html#api_setvoicebeautifierpreset) | Sets a preset voice beautifier effect. | +| [setVoiceBeautifierParameters](class_irtcengine.html#api_setvoicebeautifierparameters) | Sets parameters for the preset voice beautifier effects. | +| [setAudioEffectPreset](class_irtcengine.html#api_setaudioeffectpreset) | Sets an SDK preset audio effect. | +| [setAudioEffectParameters](class_irtcengine.html#api_setaudioeffectparameters) | Sets parameters for SDK preset audio effects. | +| [setVoiceConversionPreset](class_irtcengine.html#api_setvoiceconversionpreset) | Sets a preset voice beautifier effect. | + +## Pre-call network test + +| Method | Description | +| ------------------------------------------------------------ | ---------------------------------------- | +| [startEchoTest [2/2\]](class_irtcengine.html#api_startechotest2) | Starts an audio call test. | +| [stopEchoTest](class_irtcengine.html#api_stopechotest) | Stops the audio call test. | +| [startLastmileProbeTest](class_irtcengine.html#api_startlastmileprobetest) | Starts the last mile network probe test. | +| [stopLastmileProbeTest](class_irtcengine.html#api_stoplastmileprobetest) | Stops the last mile network probe test. | + +| Event | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [onLastmileQuality](class_irtcengineeventhandler.html#callback_onlastmilequality) | Reports the last-mile network quality of the local user once every two seconds. | +| [onLastmileProbeResult](class_irtcengineeventhandler.html#callback_onlastmileproberesult) | Reports the last mile network probe result. | + +## Screen sharing + +| Method | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [startScreenCaptureByWindowId](class_irtcengine.html#api_startscreencapturebywindowid) | Shares the whole or part of a window by specifying the window ID. (For Windows and macOS only) | +| [startScreenCaptureByScreenRect](class_irtcengine.html#api_startscreencapturebyscreenrect) | Shares the whole or part of a screen by specifying the screen rect. (For Windows only) | +| [startScreenCaptureByDisplayId](class_irtcengine.html#api_startscreencapturebydisplayid) | Shares the screen by specifying the display ID. (For Windows and macOS only) | +| [setScreenCaptureContentHint](class_irtcengine.html#api_setscreencapturecontenthint) | Sets the content hint for screen sharing. (For Windows and macOS only) | +| [updateScreenCaptureRegion](class_irtcengine.html#api_updatescreencaptureregion) | Updates the screen sharing region. (For Windows and macOS only) | +| [updateScreenCaptureParameters](class_irtcengine.html#api_updatescreencaptureparameters) | Updates the screen sharing parameters. (For Windows and macOS only) | +| [startScreenCapture](class_irtcengine.html#api_startscreencapture_ng) | Starts screen sharing. (For Windows and Android only) | +| [stopScreenCapture](class_irtcengine.html#api_stopscreencapture) | Stops screen sharing. (For Android, Windows and macOS only) | + +## Video dual stream + +| Method | Description | +| ------------------------------------------------------------ | ----------------------------------------------------- | +| [enableDualStreamMode [1/3\]](class_irtcengine.html#api_enabledualstreammode) | Enables/Disables dual-stream mode. | +| [enableDualStreamMode [2/3\]](class_irtcengine.html#api_enabledualstreammode2) | Enables/Disables dual-stream mode. | +| [enableDualStreamMode [3/3\]](class_irtcengine.html#api_enabledualstreammode3) | Enables/Disables dual-stream mode. | +| [setRemoteVideoStreamType](class_irtcengine.html#api_setremotevideostreamtype) | Sets the stream type of the remote video. | +| [setRemoteDefaultVideoStreamType](class_irtcengine.html#api_setremotedefaultvideostreamtype) | Sets the default stream type of remote video streams. | + +## Watermark + +| Method | Description | +| ------------------------------------------------------------ | -------------------------------------------------- | +| [addVideoWatermark [2/2\]](class_irtcengine.html#api_addvideowatermark2) | Adds a watermark image to the local video. | +| [clearVideoWatermarks](class_irtcengine.html#api_clearvideowatermarks) | Removes the watermark image from the video stream. | + +## Encryption + +| Method | Description | +| ------------------------------------------------------------ | ----------------------------------------- | +| [enableEncryption](class_irtcengine.html#api_enableencryption) | Enables/Disables the built-in encryption. | +| [registerPacketObserver](class_irtcengine.html#api_registerpacketobserver) | Registers a packet observer. | + +| Event | Description | +| ------------------------------------------------------------ | --------------------------------------- | +| [onEncryptionError](class_irtcengineeventhandler.html#callback_onencryptionerror) | Reports the built-in encryption errors. | + +## Sound localization + +| Method | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [enableSoundPositionIndication](class_irtcengine.html#api_enablesoundpositionindication) | Enables/Disables stereo panning for remote users. | +| [setRemoteVoicePosition](class_irtcengine.html#api_setremotevoiceposition) | Sets the 2D position (the position on the horizontal plane) of the remote user's voice. | + +## CDN publisher + +| Method | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [setLiveTranscoding](class_irtcengine.html#api_setlivetranscoding) | Sets the transcoding configurations for CDN live streaming. | +| [addPublishStreamUrl](class_irtcengine.html#api_addpublishstreamurl) | Publishes the local stream to a specified CDN live streaming URL. | +| [removePublishStreamUrl](class_irtcengine.html#api_removepublishstreamurl) | Removes an RTMP or RTMPS stream from the CDN. | + +| Event | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [onRtmpStreamingStateChanged](class_irtcengineeventhandler.html#callback_onrtmpstreamingstatechanged) | Occurs when the state of the RTMP or RTMPS streaming changes. | +| [onTranscodingUpdated](class_irtcengineeventhandler.html#callback_ontranscodingupdated) | Occurs when the publisher's transcoding is updated. | + +## Channel media stream relay + +| Method | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [startChannelMediaRelay](class_irtcengine.html#api_startchannelmediarelay) | Starts relaying media streams across channels. This method can be used to implement scenarios such as co-host across channels. | +| [updateChannelMediaRelay](class_irtcengine.html#api_updatechannelmediarelay) | Updates the channels for media stream relay. | +| [stopChannelMediaRelay](class_irtcengine.html#api_stopchannelmediarelay) | Stops the media stream relay. Once the relay stops, the host quits all the destination channels. | +| [pauseAllChannelMediaRelay](class_irtcengine.html#api_pauseallchannelmediarelay) | Pauses the media stream relay to all destination channels. | +| [resumeAllChannelMediaRelay](class_irtcengine.html#api_resumeallchannelmediarelay) | Resumes the media stream relay to all destination channels. | + +| Event | Description | +| ------------------------------------------------------------ | -------------------------------------------------------- | +| [onChannelMediaRelayStateChanged](class_irtcengineeventhandler.html#callback_onchannelmediarelaystatechanged) | Occurs when the state of the media stream relay changes. | +| [onChannelMediaRelayEvent](class_irtcengineeventhandler.html#callback_onchannelmediarelayevent) | Reports events during the media stream relay. | + +## Custom audio source + +| Method | Description | +| ------------------------------------------------------------ | ------------------------------------------ | +| [setExternalAudioSource](class_imediaengine.html#api_setexternalaudiosource2) | Sets the external audio source parameters. | +| [pushAudioFrame](class_imediaengine.html#api_imediaengine_pushaudioframe0) | Pushes the external audio frame. | + +## Custom audio renderer + +| Method | Description | +| ------------------------------------------------------------ | ----------------------------- | +| [setExternalAudioSink](class_irtcengine.html#api_setexternalaudiosink_ng) | Sets the external audio sink. | +| [pullAudioFrame](class_imediaengine.html#api_imediaengine_pullaudioframe) | Pulls the remote audio data. | + +## Raw audio data + +| Method | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [registerAudioFrameObserver](class_imediaengine.html#api_imediaengine_registeraudioframeobserver) | Registers an audio frame observer object. | +| [setRecordingAudioFrameParameters](class_irtcengine.html#api_setrecordingaudioframeparameters) | Set the format of the captured raw audio data. | +| [setPlaybackAudioFrameParameters](class_irtcengine.html#api_setplaybackaudioframeparameters) | Sets the audio data format for playback. | +| [setMixedAudioFrameParameters](class_irtcengine.html#api_setmixedaudioframeparameters_ng) | Sets the audio data format reported by [onMixedAudioFrame](class_iaudioframeobserverbase.html#callback_iaudioframeobserverbase_onmixedaudioframe). | +| [setPlaybackAudioFrameBeforeMixingParameters](class_irtcengine.html#api_setplaybackaudioframebeforemixingparameters) | Sets the audio data format reported by [onPlaybackAudioFrameBeforeMixing](class_iaudioframeobserverbase.html#callback_iaudioframeobserverbase_onplaybackaudioframebeforemixing). | + +| Event | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [onRecordAudioFrame](class_iaudioframeobserverbase.html#callback_iaudioframeobserverbase_onrecordaudioframe) | Gets the captured audio frame. | +| [onPlaybackAudioFrame](class_iaudioframeobserverbase.html#callback_iaudioframeobserverbase_onplaybackaudioframe) | Gtes the audio frame for playback. | +| [onPlaybackAudioFrameBeforeMixing](class_iaudioframeobserverbase.html#callback_iaudioframeobserverbase_onplaybackaudioframebeforemixing) | Retrieves the audio frame of a specified user before mixing. | +| [onMixedAudioFrame](class_iaudioframeobserverbase.html#callback_iaudioframeobserverbase_onmixedaudioframe) | Retrieves the mixed captured and playback audio frame. | + +## Encoded audio data + +| Method | Description | +| ------------------------------------------------------------ | ------------------------------------ | +| [registerAudioEncodedFrameObserver](class_irtcengine.html#api_registeraudioencodedframeobserver) | Registers an encoded audio observer. | + +| Event | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [OnRecordAudioEncodedFrame](class_iaudioencodedframeobserver.html#callback_iaudioencodedframeobserver_onrecordaudioencodedframe) | Gets the encoded audio data of the local user. | +| [OnPlaybackAudioEncodedFrame](class_iaudioencodedframeobserver.html#callback_iaudioencodedframeobserver_onplaybackaudioencodedframe) | Gets the encoded audio data of all remote users. | +| [OnMixedAudioEncodedFrame](class_iaudioencodedframeobserver.html#callback_iaudioencodedframeobserver_onmixedaudioencodedframe) | Gets the mixed and encoded audio data of the local and all remote users. | + +## Audio spectrum + +| Method | Description | +| ------------------------------------------------------------ | ---------------------------------------- | +| [registerAudioSpectrumObserver](class_irtcengine.html#api_registeraudiospectrumobserver) | Register an audio spectrum observer. | +| [enableAudioSpectrumMonitor](class_irtcengine.html#api_enableaudiospectrummonitor) | Turn on audio spectrum monitoring. | +| [disableAudioSpectrumMonitor](class_irtcengine.html#api_disableaudiospectrummonitor) | Disables audio spectrum monitoring. | +| [unregisterAudioSpectrumObserver](class_irtcengine.html#api_unregisteraudiospectrumobserver) | Unregisters the audio spectrum observer. | + +| Event | Description | +| ------------------------------------------------------------ | ---------------------------------------------- | +| [onLocalAudioSpectrum](class_iaudiospectrumobserver.html#callback_iaudiospectrumobserver_onlocalaudiospectrum) | Gets the statistics of a local audio spectrum. | +| [onRemoteAudioSpectrum](class_iaudiospectrumobserver.html#callback_iaudiospectrumobserver_onremoteaudiospectrum) | Gets the remote audio spectrum. | + +## External video source + +| Method | Description | +| ------------------------------------------------------------ | --------------------------------------------------- | +| [setExternalVideoSource](class_imediaengine.html#api_imediaengine_setexternalvideosource_ng) | Configures the external video source. | +| [pushVideoFrame [1/2\]](class_imediaengine.html#api_imediaengine_pushvideoframe) | Pushes the external encoded video frame to the SDK. | +| [pushEncodedVideoImage [1/2\]](class_imediaengine.html#api_imediaengine_pushencodedvideoimage) | Pushes the external encoded video frame to the SDK. | + +## Raw video data + +| Method | Description | +| ------------------------------------------------------------ | -------------------------------------------------------- | +| [registerVideoFrameObserver](class_imediaengine.html#api_imediaengine_registervideoframeobserver) | Registers a video frame observer object. | +| [registerVideoEncodedImageReceiver](class_imediaengine.html#api_imediaengine_registervideoencodedimagereceiver) | Registers a receiver object for the encoded video image. | + +| Event | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [onCaptureVideoFrame](class_ivideoframeobserver.html#callback_ivideoframeobserver_oncapturevideoframe) | Occurs each time the SDK receives a video frame captured by the local camera. | +| [onPreEncodeVideoFrame](class_ivideoframeobserver.html#callback_ivideoframeobserver_onpreencodevideoframe) | Occurs each time the SDK receives a video frame before encoding. | +| [onPreEncodeScreenVideoFrame](class_ivideoframeobserver.html#callback_ivideoframeobserver_onpreencodescreenvideoframe) | Gets the video data captured from the screen before encoding. | +| [onScreenCaptureVideoFrame](class_ivideoframeobserver.html#callback_ivideoframeobserver_onscreencapturevideoframe) | Occurs each time the SDK receives a video frame captured by the screen. | +| [onSecondaryPreEncodeCameraVideoFrame](class_ivideoframeobserver.html#callback_ivideoframeobserver_onsecondarypreencodecameravideoframe) | Gets the video data captured from the second camera before encoding. | +| [onSecondaryPreEncodeScreenVideoFrame](class_ivideoframeobserver.html#callback_ivideoframeobserver_onsecondarypreencodescreenvideoframe) | Gets the video data captured from the second screen before encoding. | +| [onRenderVideoFrame](class_ivideoframeobserver.html#callback_ivideoframeobserver_onrendervideoframe) | Occurs each time the SDK receives a video frame sent by the remote user. | +| [onMediaPlayerVideoFrame](class_ivideoframeobserver.html#callback_ivideoframeobserver_onmediaplayervideoframe) | Gets the video data of the media player. | +| [getObservedFramePosition](class_ivideoframeobserver.html#callback_ivideoframeobserver_getobservedframeposition) | Sets the frame position for the video observer. | +| [getVideoFrameProcessMode](class_ivideoframeobserver.html#callback_ivideoframeobserver_getvideoframeprocessmode) | Occurs each time the SDK receives a video frame and prompts you to set the process mode of the video frame. | +| [OnEncodedVideoImageReceived](class_ivideoencodedimagereceiver.html#callback_ivideoencodedimagereceiver_onencodedvideoimagereceived) | Occurs each time the SDK receives an encoded video image. | +| [getMirrorApplied](class_ivideoframeobserver.html#callback_ivideoframeobserver_getmirrorapplied) | Occurs each time the SDK receives a video frame and prompts you whether or not to mirror the captured video. | +| [getRotationApplied](class_ivideoframeobserver.html#callback_ivideoframeobserver_getrotationapplied) | Occurs each time the SDK receives a video frame, and prompts you whether to rotate the captured video. | + +## Extension + +| Method | Description | +| ------------------------------------------------------------ | ---------------------------------------------- | +| [enableExtension](class_irtcengine.html#api_enableextension) | Enables/Disables extensions. | +| [setExtensionProperty](class_irtcengine.html#api_setextensionproperty) | Sets the properties of the extension. | +| [setExtensionProviderProperty](class_irtcengine.html#api_setextensionproviderproperty) | Sets the properties of the extension provider. | + +| Event | Description | +| ------------------------------------------------------------ | ------------------------------------------- | +| [onExtensionEvent](class_irtcengineeventhandler.html#callback_onextensionevent) | The event callback of the extension. | +| [onExtensionStarted](class_irtcengineeventhandler.html#callback_onextensionstarted) | Occurs when the extension is enabled. | +| [onExtensionStopped](class_irtcengineeventhandler.html#callback_onextensionstoped) | Occurs when the extension is disabled. | +| [onExtensionError](class_irtcengineeventhandler.html#callback_onextensionerror) | Occurs when the extension runs incorrectly. | + +## Media metadata + +| Method | Description | +| ------------------------------------------------------------ | -------------------------------------------- | +| [registerMediaMetadataObserver](class_irtcengine.html#api_registermediametadataobserver) | Registers the metadata observer. | +| [unregisterMediaMetadataObserver](class_irtcengine.html#api_unregistermediametadataobserver) | Unregisters the specified metadata observer. | + +| Event | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [getMaxMetadataSize](class_imetadataobserver.html#callback_imetadataobserver_getmaxmetadatasize) | Occurs when the SDK requests the maximum size of the metadata. | +| [onReadyToSendMetadata](class_imetadataobserver.html#callback_imetadataobserver_onreadytosendmetadata) | Occurs when the SDK is ready to send metadata. | +| [onMetadataReceived](class_imetadataobserver.html#callback_imetadataobserver_onmetadatareceived) | Occurs when the local user receives the metadata. | + +## Audio recording + +| Method | Description | +| ------------------------------------------------------------ | ---------------------------------------- | +| [startAudioRecording](class_irtcengine.html#api_startaudiorecording3_ng) | Starts audio recording on the client. | +| [stopAudioRecording](class_irtcengine.html#api_stopaudiorecording) | Stops the audio recording on the client. | + +## Camera management + +**Attention:** This method is for Android and iOS only. + +| Method | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [switchCamera](class_irtcengine.html#api_switchcamera) | Switches between front and rear cameras. | +| [setCameraCapturerConfiguration](class_irtcengine.html#api_setcameracapturerconfiguration) | Sets the camera capture configuration. | +| [isCameraZoomSupported](class_irtcengine.html#api_iscamerazoomsupported) | Checks whether the device supports camera zoom. | +| [getCameraMaxZoomFactor](class_irtcengine.html#api_getcameramaxzoomfactor) | Gets the maximum zoom ratio supported by the camera. | +| [setCameraZoomFactor](class_irtcengine.html#api_setcamerazoomfactor) | Sets the camera zoom ratio. | +| [isCameraTorchSupported](class_irtcengine.html#api_iscameratorchsupported) | Checks whether the device supports camera flash. | +| [setCameraTorchOn](class_irtcengine.html#api_setcameratorchon) | Enables the camera flash. | +| [isCameraFaceDetectSupported](class_irtcengine.html#api_iscamerafacedetectsupported) | Checks whether the device camera supports face detection. | +| [isCameraFocusSupported](class_irtcengine.html#api_iscamerafocussupported) | Check whether the device supports the manual focus function. | +| [setCameraFocusPositionInPreview](class_irtcengine.html#api_setcamerafocuspositioninpreview) | Sets the camera manual focus position. | +| [isCameraAutoFocusFaceModeSupported](class_irtcengine.html#api_iscameraautofocusfacemodesupported) | Checks whether the device supports the face auto-focus function. | +| [setCameraAutoFocusFaceModeEnabled](class_irtcengine.html#api_setcameraautofocusfacemodeenabled) | Enables the camera auto-face focus function. | +| [isCameraExposurePositionSupported](class_irtcengine.html#api_iscameraexposurepositionsupported) | Checks whether the device supports manual exposure. | +| [setCameraExposurePosition](class_irtcengine.html#api_setcameraexposureposition) | Sets the camera exposure position. | + +| Event | Description | +| ------------------------------------------------------------ | --------------------------------------------- | +| [onCameraFocusAreaChanged](class_irtcengineeventhandler.html#callback_oncamerafocusareachanged) | Occurs when the camera focus area changes. | +| [onCameraExposureAreaChanged](class_irtcengineeventhandler.html#callback_oncameraexposureareachanged) | Occurs when the camera exposure area changes. | + +## Multiple channels + +| Method | Description | +| ------------------------------------------------------------ | --------------------------------------- | +| [joinChannelEx](class_irtcengineex.html#api_irtcengineex_joinchannelex) | Joins a channel with the connection ID. | +| [leaveChannelEx](class_irtcengineex.html#api_irtcengineex_leavechannelex) | Leaves a channel. | + +## Audio route + +This method is for Android and iOS only. + +| Method | Description | +| ------------------------------------------------------------ | ---------------------------------------------- | +| [setDefaultAudioRouteToSpeakerphone](class_irtcengine.html#api_setdefaultaudioroutetospeakerphone_ng) | Sets the default audio playback route. | +| [setEnableSpeakerphone](class_irtcengine.html#api_setenablespeakerphone_ng) | Enables/Disables the speakerphone temporarily. | +| [isSpeakerphoneEnabled](class_irtcengine.html#api_isspeakerphoneenabled) | Checks whether the speakerphone is enabled. | + +## Volume indication + +| Method | Description | +| ------------------------------------------------------------ | -------------------------------------------------- | +| [enableAudioVolumeIndication](class_irtcengine.html#api_enableaudiovolumeindication) | Enables the reporting of users' volume indication. | + +| Event | Description | +| ------------------------------------------------------------ | ------------------------------------------------ | +| [onAudioVolumeIndication](class_irtcengineeventhandler.html#callback_onaudiovolumeindication) | Reports the volume information of users. | +| [onActiveSpeaker](class_irtcengineeventhandler.html#callback_onactivespeaker) | Occurs when the most active speaker is detected. | + +## Data stream + +| Method | Description | +| ------------------------------------------------------------ | --------------------------- | +| [createDataStream [2/2\]](class_irtcengine.html#api_createdatastream2) | Creates a data stream. | +| [sendStreamMessage](class_irtcengine.html#api_sendstreammessage) | Sends data stream messages. | + +| Event | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [onStreamMessage](class_irtcengineeventhandler.html#callback_onstreammessage) | Occurs when the local user receives the data stream from the remote user. | +| [onStreamMessageError](class_irtcengineeventhandler.html#callback_onstreammessageerror) | Occurs when the local user does not receive the data stream from the remote user. | + +## Video device management + +**Attention:** + +This group of methods are for Windows only. + +| Method | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [enumerateVideoDevices](class_ivideodevicemanager.html#api_ivideodevicemanager_enumeratevideodevices) | Enumerates the video devices. | +| [setDevice](class_ivideodevicemanager.html#api_ivideodevicemanager_setdevice) | Specifies the video capture device with the device ID. | +| [getDevice](class_ivideodevicemanager.html#api_ivideodevicemanager_getdevice) | Retrieves the current video capture device. | +| [release](class_ivideodevicemanager.html#api_ivideodevicemanager_release) | Releases all the resources occupied by the [IVideoDeviceManager](class_ivideodevicemanager.html#class_ivideodevicemanager) object. | + +## Video device collection + +**Attention:** + +This group of methods are for Windows only. + +| Method | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [setDevice](class_ivideodevicecollection.html#api_ivideodevicecollection_setdevice) | Specifies a device with the device ID. | +| [getDevice](class_ivideodevicecollection.html#api_ivideodevicecollection_getdevice) | Gets a specified piece of information about an indexed video device. | +| [getCount](class_ivideodevicecollection.html#api_ivideodevicecollection_getcount) | Gets the total number of the indexed video devices in the system. | +| [release](class_ivideodevicecollection.html#api_ivideodevicecollection_release) | Releases all the resources occupied by the [IVideoDeviceCollection](class_ivideodevicecollection.html#class_ivideodevicecollection) object. | + +## Audio device management + +**Attention:** + +This group of methods are for Windows only. + +| Method | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [enumeratePlaybackDevices](class_iaudiodevicemanager.html#api_iaudiodevicemanager_enumerateplaybackdevices) | Enumerates the audio playback devices. | +| [enumerateRecordingDevices](class_iaudiodevicemanager.html#api_iaudiodevicemanager_enumeraterecordingdevices) | Enumerates the audio capture devices. | +| [setPlaybackDevice](class_iaudiodevicemanager.html#api_iaudiodevicemanager_setplaybackdevice) | Sets the audio playback device. | +| [getPlaybackDevice](class_iaudiodevicemanager.html#api_iaudiodevicemanager_getplaybackdevice) | Retrieves the audio playback device associated with the device ID. | +| [getPlaybackDeviceInfo](class_iaudiodevicemanager.html#api_iaudiodevicemanager_getplaybackdeviceinfo) | Retrieves the audio playback device information associated with the device ID and device name. | +| [setRecordingDevice](class_iaudiodevicemanager.html#api_iaudiodevicemanager_setrecordingdevice) | Sets the audio capture device. | +| [getRecordingDevice](class_iaudiodevicemanager.html#api_iaudiodevicemanager_getrecordingdevice) | Gets the current audio recording device. | +| [getRecordingDeviceInfo](class_iaudiodevicemanager.html#api_iaudiodevicemanager_getrecordingdeviceinfo) | Retrieves the audio capture device information associated with the device ID and device name. | +| [startPlaybackDeviceTest](class_iaudiodevicemanager.html#api_iaudiodevicemanager_startplaybackdevicetest) | Starts the audio playback device test. (For Windows and macOS only) | +| [stopPlaybackDeviceTest](class_iaudiodevicemanager.html#api_iaudiodevicemanager_stopplaybackdevicetest) | Stops the audio playback device test. (For Windows and macOS only) | +| [startRecordingDeviceTest](class_iaudiodevicemanager.html#api_iaudiodevicemanager_startrecordingdevicetest) | Starts the audio capture device test. (For Windows and macOS only) | +| [stopRecordingDeviceTest](class_iaudiodevicemanager.html#api_iaudiodevicemanager_stoprecordingdevicetest) | Stops the audio capture device test. (For Windows and macOS only) | +| [startAudioDeviceLoopbackTest](class_iaudiodevicemanager.html#api_iaudiodevicemanager_startaudiodeviceloopbacktest) | Starts an audio device loopback test. (For Windows and macOS only) | +| [stopAudioDeviceLoopbackTest](class_iaudiodevicemanager.html#api_iaudiodevicemanager_stopaudiodeviceloopbacktest) | Stops the audio device loopback test. (For Windows and macOS only) | +| [release](class_iaudiodevicemanager.html#api_iaudiodevicemanager_release) | Releases all the resources occupied by the [IAudioDeviceManager](class_iaudiodevicemanager.html#class_iaudiodevicemanager) object. | + +| Event | Description | +| ------------------------------------------------------------ | ------------------------------------------- | +| [onAudioDeviceStateChanged](class_irtcengineeventhandler.html#callback_onaudiodevicestatechanged) | Occurs when the audio device state changes. | + +## Audio device collection + +**Attention:** + +This group of methods are for Windows only. + +| Method | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [setDevice](class_iaudiodevicecollection.html#api_iaudiodevicecollection_setdevice) | Specifies an audio device. | +| [getDevice](class_iaudiodevicecollection.html#api_iaudiodevicecollection_getdevice) | Gets the information of a specified audio device. | +| [getCount](class_iaudiodevicecollection.html#api_iaudiodevicecollection_getcount) | Gets the total number of audio playback or audio capture devices. | +| [setApplicationVolume](class_iaudiodevicecollection.html#api_iaudiodevicecollection_setapplicationvolume) | Sets the application volume. | +| [getApplicationVolume](class_iaudiodevicecollection.html#api_iaudiodevicecollection_getapplicationvolume) | Gets the volume of the application. | +| [setApplicationMute](class_iaudiodevicecollection.html#api_iaudiodevicecollection_setapplicationmute) | Mutes/Unmutes the application. | +| [isApplicationMute](class_iaudiodevicecollection.html#api_iaudiodevicecollection_isapplicationmute) | Gets the mute state of the application. | +| [release](class_iaudiodevicecollection.html#api_iaudiodevicecollection_release) | Releases all IAudioDeviceCollection resources. | + +## Miscellaneous audio control + +**Attention:** + +This method is for Windows and macOS only. + +| Method | Description | +| ------------------------------------------------------------ | --------------------------------- | +| [enableLoopbackRecording](class_irtcengine.html#api_enableloopbackrecording_ng) | Enables loopback audio capturing. | + +## Miscellaneous methods + +| Method | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [sendCustomReportMessageEx](class_irtcengineex.html#api_irtcengineex_sendcustomreportmessageex) | Agora supports reporting and analyzing customized messages. | +| [getCallId](class_irtcengine.html#api_getcallid) | Retrieves the call ID. | +| [rate](class_irtcengine.html#api_rate) | Allows a user to rate a call after the call ends. | +| [complain](class_irtcengine.html#api_complain) | Allows a user to complain about the call quality after a call ends. | +| [getVersion](class_irtcengine.html#api_getversion) | Gets the SDK version. | +| [getErrorDescription](class_irtcengine.html#api_geterrordescription) | Gets the warning or error description. | +| [queryInterface](class_irtcengine.html#api_queryinterface) | Gets the pointer to the specified interface. | + +## Miscellaneous events + +| Event | Description | +| ------------------------------------------------------------ | -------------------------------------------- | +| [onApiCallExecuted](class_irtcengineeventhandler.html#callback_onapicallexecuted) | Occurs when a method is executed by the SDK. | \ No newline at end of file diff --git a/en-US/markdown/Video/API/structs_enums.md b/en-US/markdown/Video/API/structs_enums.md new file mode 100644 index 00000000000..93f8cf8cb92 --- /dev/null +++ b/en-US/markdown/Video/API/structs_enums.md @@ -0,0 +1,6266 @@ +C++ API Reference for All Platforms[API Overview](../API/rtc_api_overview_ng.html)[IRtcEngine](../API/class_irtcengine.html#class_irtcengine)[IRtcEngineEx](../API/class_irtcengineex.html#class_irtcengineex)[IRtcEngineEventHandler](../API/class_irtcengineeventhandler.html#class_irtcengineeventhandler)[IMediaPlayer](../API/class_imediaplayer.html#class_imediaplayer)[IAudioEncodedFrameObserver](../API/class_iaudioencodedframeobserver.html#class_iaudioencodedframeobserver)[IAudioDeviceManager](../API/class_iaudiodevicemanager.html#class_iaudiodevicemanager)[IAudioDeviceCollection](../API/class_iaudiodevicecollection.html#class_iaudiodevicecollection)[IVideoDeviceManager](../API/class_ivideodevicemanager.html#class_ivideodevicemanager)[IVideoDeviceCollection](../API/class_ivideodevicecollection.html#class_ivideodevicecollection)[IMediaEngine](../API/class_imediaengine.html#class_imediaengine)[IMediaPlayerCustomDataProvider](../API/class_imediaplayercustomdataprovider.html#class_imediaplayercustomdataprovider)[IMediaPlayerSourceObserver](../API/class_imediaplayersourceobserver.html#class_imediaplayersourceobserver)[IAudioFrameObserver](../API/class_iaudioframeobserver.html#class_iaudioframeobserver)[IAudioFrameObserverBase](../API/class_iaudioframeobserverbase.html#class_iaudioframeobserverbase)[IAudioSpectrumObserver](../API/class_iaudiospectrumobserver.html#class_iaudiospectrumobserver)[IPacketObserver](../API/class_ipacketobserver.html#class_ipacketobserver)[IMetadataObserver](../API/class_imetadataobserver.html#class_imetadataobserver)[IVideoEncodedImageReceiver](../API/class_ivideoencodedimagereceiver.html#class_ivideoencodedimagereceiver)[IVideoFrameObserver](../API/class_ivideoframeobserver.html#class_ivideoframeobserver)[Type definition](../API/rtc_api_data_type.html#rtc_api_data_type) + +# Type definition + +This page lists all the type definitions of the Windows API. + +## [AREA_CODE](rtc_api_data_type.html#enum_areacode) + +The region for connection, which is the region where the server the SDK connects to is located. + +### Enumerator + +- AREA_CODE_CN + + Mainland China. + +- AREA_CODE_NA + + North America. + +- AREA_CODE_EU + + Europe. + +- AREA_CODE_AS + + Asia, excluding Mainland China. + +- AREA_CODE_JP + + Japan. + +- AREA_CODE_IN + + India. + +- AREA_CODE_GLOB + + (Default) Global. + +**See also** + +- [initialize](../API/class_irtcengine.html#api_create2) + +## [AUDIENCE_LATENCY_LEVEL_TYPE](rtc_api_data_type.html#enum_audiencelatencyleveltype) + +The latency level of an audience member in interactive live streaming. This enum takes effect only when the user role is set to CLIENT_ROLE_AUDIENCE. + +### Enumerator + +- AUDIENCE_LATENCY_LEVEL_LOW_LATENCY + + 1: Low latency. + +- AUDIENCE_LATENCY_LEVEL_ULTRA_LOW_LATENCY + + 2: (Default) Ultra low latency. + +**See also** + +- [setClientRole [2/2\]](../API/class_irtcengine.html#api_setclientrole2) + +## [AUDIO_CODEC_PROFILE_TYPE](rtc_api_data_type.html#enum_audiocodecprofiletype) + +The codec type of the output audio stream for CDN live streaming. The default value is LC-ACC. + +### Enumerator + +- AUDIO_CODEC_PROFILE_LC_AAC + + 0: (Default) LC-AAC, which is the low-complexity audio codec type. + +- AUDIO_CODEC_PROFILE_HE_AAC + + 1: HE-AAC, which is the high-efficiency audio codec type. + +**See also** + +- [setLiveTranscoding](../API/class_irtcengine.html#api_setlivetranscoding) + +## [AUDIO_CODEC_TYPE](rtc_api_data_type.html#enum_audiocodectype) + +The codec type of audio. + +### Enumerator + +- AUDIO_CODEC_OPUS + + 1: OPUS. + +- AUDIO_CODEC_PCMA + + 3: PCMA. + +- AUDIO_CODEC_PCMU + + 4: PCMU. + +- AUDIO_CODEC_G722 + + 5: G722. + +- AUDIO_CODEC_AACLC + + 8: LC-AAC. + +- AUDIO_CODEC_HEAAC + + 9: HE-AAC. + +- AUDIO_CODEC_JC1 + + 10: JC1. + +- AUDIO_CODEC_HEAAC2 + + 11: HE-AAC v2. + +## [AUDIO_DUAL_MONO_MODE](rtc_api_data_type.html#enum_audiodualmonomode) + +The channel mode. + +### Enumerator + +- AUDIO_DUAL_MONO_STEREO + + 0: Original mode. + +- AUDIO_DUAL_MONO_L + + 1: Left channel mode. This mode replaces the audio of the right channel with the audio of the left channel, which means the user can only hear the audio of the left channel. + +- AUDIO_DUAL_MONO_R + + 2: Right channel mode. This mode replaces the audio of the left channel with the audio of the right channel, which means the user can only hear the audio of the right channel. + +- AUDIO_DUAL_MONO_MIX + + 3: Mixed channel mode. This mode mixes the audio of the left channel and the right channel, which means the user can hear the audio of the left channel and the right channel at the same time. + +**See also** + +- [setAudioDualMonoMode](../API/class_imediaplayer.html#api_setaudiodualmonomode) + +## [AUDIO_EFFECT_PRESET](rtc_api_data_type.html#enum_audioeffectpreset) + +Preset voice effects. + +For better voice effects, Agora recommends setting the **profile** parameter of [setAudioProfile [1/2\]](class_irtcengine.html#api_setaudioprofile) to AUDIO_PROFILE_MUSIC_HIGH_QUALITY or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO before using the following presets: + +- ROOM_ACOUSTICS_KTV +- ROOM_ACOUSTICS_VOCAL_CONCERT +- ROOM_ACOUSTICS_STUDIO +- ROOM_ACOUSTICS_PHONOGRAPH +- ROOM_ACOUSTICS_SPACIAL +- ROOM_ACOUSTICS_ETHEREAL +- VOICE_CHANGER_EFFECT_UNCLE +- VOICE_CHANGER_EFFECT_OLDMAN +- VOICE_CHANGER_EFFECT_BOY +- VOICE_CHANGER_EFFECT_SISTER +- VOICE_CHANGER_EFFECT_GIRL +- VOICE_CHANGER_EFFECT_PIGKING +- VOICE_CHANGER_EFFECT_HULK +- PITCH_CORRECTION + +### Enumerator + +- AUDIO_EFFECT_OFF + + Turn off voice effects, that is, use the original voice. + +- ROOM_ACOUSTICS_KTV + + The voice effect typical of a KTV venue. + +- ROOM_ACOUSTICS_VOCAL_CONCERT + + The voice effect typical of a concert hall. + +- ROOM_ACOUSTICS_STUDIO + + The voice effect typical of a recording studio. + +- ROOM_ACOUSTICS_PHONOGRAPH + + The voice effect typical of a vintage phonograph. + +- ROOM_ACOUSTICS_VIRTUAL_STEREO + + The virtual stereo effect, which renders monophonic audio as stereo audio.**Note** Before using this preset, set the **profile** parameter of [setAudioProfile [1/2\]](class_irtcengine.html#api_setaudioprofile) to AUDIO_PROFILE_MUSIC_HIGH_QUALITY or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO; otherwise, the preset setting is invalid. + +- ROOM_ACOUSTICS_SPACIAL + + A more spatial voice effect. + +- ROOM_ACOUSTICS_ETHEREAL + + A more ethereal voice effect. + +- ROOM_ACOUSTICS_3D_VOICE + + A 3D voice effect that makes the voice appear to be moving around the user. The default movement cycle is 10 seconds. After setting this effect, you can call [setAudioEffectParameters](class_irtcengine.html#api_setaudioeffectparameters) to modify the movement period.**Note**Before using this preset, set the **profile** parameter of [setAudioProfile [1/2\]](class_irtcengine.html#api_setaudioprofile) to AUDIO_PROFILE_MUSIC_STANDARD_STEREO or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO; otherwise, the preset setting is invalid.If the 3D voice effect is enabled, users need to use stereo audio playback devices to hear the anticipated voice effect. + +- VOICE_CHANGER_EFFECT_UNCLE + + A middle-aged man's voice.**Note** Agora recommends using this preset to process a male-sounding voice; otherwise, you may not hear the anticipated voice effect. + +- VOICE_CHANGER_EFFECT_OLDMAN + + A senior man's voice.**Note** Agora recommends using this preset to process a male-sounding voice; otherwise, you may not hear the anticipated voice effect. + +- VOICE_CHANGER_EFFECT_BOY + + A boy's voice.**Note** Agora recommends using this preset to process a male-sounding voice; otherwise, you may not hear the anticipated voice effect. + +- VOICE_CHANGER_EFFECT_SISTER + + A young woman's voice.**Note** Agora recommends using this preset to process a female-sounding voice; otherwise, you may not hear the anticipated voice effect. + +- VOICE_CHANGER_EFFECT_GIRL + + A girl's voice.**Note** Agora recommends using this preset to process a female-sounding voice; otherwise, you may not hear the anticipated voice effect. + +- VOICE_CHANGER_EFFECT_PIGKING + + The voice of Pig King, a character in Journey to the West who has a voice like a growling bear. + +- VOICE_CHANGER_EFFECT_HULK + + The Hulk's voice. + +- STYLE_TRANSFORMATION_RNB + + The voice effect typical of R&B music.**Note** Before using this preset, set the **profile** parameter of [setAudioProfile [1/2\]](class_irtcengine.html#api_setaudioprofile) to AUDIO_PROFILE_MUSIC_HIGH_QUALITY or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO; otherwise, the preset setting is invalid. + +- STYLE_TRANSFORMATION_POPULAR + + The voice effect typical of popular music.**Note** Before using this preset, set the **profile** parameter of [setAudioProfile [1/2\]](class_irtcengine.html#api_setaudioprofile) to AUDIO_PROFILE_MUSIC_HIGH_QUALITY or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO; otherwise, the preset setting is invalid. + +- PITCH_CORRECTION + + A pitch correction effect that corrects the user's pitch based on the pitch of the natural C major scale. After setting this voice effect, you can call [setAudioEffectParameters](class_irtcengine.html#api_setaudioeffectparameters) to adjust the basic mode of tuning and the pitch of the main tone. + +**See also** + +- [setAudioEffectPreset](../API/class_irtcengine.html#api_setaudioeffectpreset) + +## [AUDIO_ENCODED_FRAME_OBSERVER_POSITION](rtc_api_data_type.html#enum_audioencodedframeobserverposition) + +Audio profile. + +### Enumerator + +- AUDIO_ENCODED_FRAME_OBSERVER_POSITION_RECORD + + 1: Only records the audio of the local user. + +- AUDIO_ENCODED_FRAME_OBSERVER_POSITION_PLAYBACK + + 2: Only records the audio of all remote users. + +- AUDIO_ENCODED_FRAME_OBSERVER_POSITION_MIXED + + 3: Records the mixed audio of the local and all remote users. + +**See also** + +- [OnPlaybackAudioEncodedFrame](../API/class_iaudioencodedframeobserver.html#callback_iaudioencodedframeobserver_onplaybackaudioencodedframe) +- [OnRecordAudioEncodedFrame](../API/class_iaudioencodedframeobserver.html#callback_iaudioencodedframeobserver_onrecordaudioencodedframe) +- [OnMixedAudioEncodedFrame](../API/class_iaudioencodedframeobserver.html#callback_iaudioencodedframeobserver_onmixedaudioencodedframe) + +## [AUDIO_ENCODING_TYPE](rtc_api_data_type.html#enum_audioencodingtype) + +Audio encoding type. + +### Enumerator + +- AUDIO_ENCODING_TYPE_AAC_16000_LOW + + AAC encoding format, 16000 Hz sampling rate, bass quality. A file with an audio duration of 10 minutes is approximately 1.2 MB after encoding. + +- AUDIO_ENCODING_TYPE_AAC_16000_MEDIUM + + AAC encoding format, 16000 Hz sampling rate, medium sound quality. A file with an audio duration of 10 minutes is approximately 2 MB after encoding. + +- AUDIO_ENCODING_TYPE_AAC_32000_LOW + + AAC encoding format, 32000 Hz sampling rate, bass quality. A file with an audio duration of 10 minutes is approximately 1.2 MB after encoding. + +- AUDIO_ENCODING_TYPE_AAC_32000_MEDIUM + + AAC encoding format, 32000 Hz sampling rate, medium sound quality. A file with an audio duration of 10 minutes is approximately 2 MB after encoding. + +- AUDIO_ENCODING_TYPE_AAC_32000_HIGH + + AAC encoding format, 32000 Hz sampling rate, high sound quality. A file with an audio duration of 10 minutes is approximately 3.5 MB after encoding. + +- AUDIO_ENCODING_TYPE_AAC_48000_MEDIUM + + AAC encoding format, 48000 Hz sampling rate, medium sound quality. A file with an audio duration of 10 minutes is approximately 2 MB after encoding. + +- AUDIO_ENCODING_TYPE_AAC_48000_HIGH + + AAC encoding format, 48000 Hz sampling rate, high sound quality. A file with an audio duration of 10 minutes is approximately 3.5 MB after encoding. + +- AUDIO_ENCODING_TYPE_OPUS_16000_LOW + + OPUS encoding format, 16000 Hz sampling rate, bass quality. A file with an audio duration of 10 minutes is approximately 2 MB after encoding. + +- AUDIO_ENCODING_TYPE_OPUS_16000_MEDIUM + + OPUS encoding format, 16000 Hz sampling rate, medium sound quality. A file with an audio duration of 10 minutes is approximately 2 MB after encoding. + +- AUDIO_ENCODING_TYPE_OPUS_48000_MEDIUM + + OPUS encoding format, 48000 Hz sampling rate, medium sound quality. A file with an audio duration of 10 minutes is approximately 2 MB after encoding. + +- AUDIO_ENCODING_TYPE_OPUS_48000_HIGH + + OPUS encoding format, 48000 Hz sampling rate, high sound quality. A file with an audio duration of 10 minutes is approximately 3.5 MB after encoding. + +## [AUDIO_EQUALIZATION_BAND_FREQUENCY](rtc_api_data_type.html#enum_audioequalizationbandfrequency) + +The midrange frequency for audio equalization. + +### Enumerator + +- AUDIO_EQUALIZATION_BAND_31 + + 0: 31 Hz + +- AUDIO_EQUALIZATION_BAND_62 + + 1: 62 Hz + +- AUDIO_EQUALIZATION_BAND_125 + + 2: 125 Hz + +- AUDIO_EQUALIZATION_BAND_250 + + 3: 250 Hz + +- AUDIO_EQUALIZATION_BAND_500 + + 4: 500 Hz + +- AUDIO_EQUALIZATION_BAND_1K + + 5: 1 kHz + +- AUDIO_EQUALIZATION_BAND_2K + + 6: 2 kHz + +- AUDIO_EQUALIZATION_BAND_4K + + 7: 4 kHz + +- AUDIO_EQUALIZATION_BAND_8K + + 8: 8 kHz + +- AUDIO_EQUALIZATION_BAND_16K + + 9: 16 kHz + +**See also** + +- [setLocalVoiceEqualization](../API/class_irtcengine.html#api_setlocalvoiceequalization) + +## [AUDIO_FRAME_TYPE](rtc_api_data_type.html#enum_audioframetype) + +Audio frame type. + +### Enumerator + +- FRAME_TYPE_PCM16 + + 0: PCM 16 + +**See also** + +- [pullAudioFrame](../API/class_imediaengine.html#api_imediaengine_pullaudioframe) +- [onRecordAudioFrame](../API/class_iaudioframeobserverbase.html#callback_iaudioframeobserverbase_onrecordaudioframe) +- [onPlaybackAudioFrame](../API/class_iaudioframeobserverbase.html#callback_iaudioframeobserverbase_onplaybackaudioframe) +- [onPlaybackAudioFrameBeforeMixing](../API/class_iaudioframeobserverbase.html#callback_iaudioframeobserverbase_onplaybackaudioframebeforemixing) +- [onMixedAudioFrame](../API/class_iaudioframeobserverbase.html#callback_iaudioframeobserverbase_onmixedaudioframe) + +## [AUDIO_RECORDING_POSITION](rtc_api_data_type.html#enum_audiorecordingposition) + +Recording content. Set in [startAudioRecording](class_irtcengine.html#api_startaudiorecording3_ng). + + + +### Enumerator + +- AUDIO_RECORDING_POSITION_MIXED_RECORDING_AND_PLAYBACK + + 0: (Default) Records the mixed audio of the local and all remote users. + +- AUDIO_RECORDING_POSITION_RECORDING + + 1: Only records the audio of the local user. + +- AUDIO_RECORDING_POSITION_MIXED_PLAYBACK + + 2: Only records the audio of all remote users. + +**See also** + +- [startAudioRecording](../API/class_irtcengine.html#api_startaudiorecording3_ng) + +## [AUDIO_MIXING_ERROR_TYPE](rtc_api_data_type.html#enum_audiomixingerrortype) + +Errors that might occur when playing a music file. + +- Deprecated: + + Deprecated as of v3.4.0. + +### Enumerator + +- AUDIO_MIXING_ERROR_CAN_NOT_OPEN + + The SDK cannot open the music file. + +- AUDIO_MIXING_ERROR_TOO_FREQUENT_CALL + + The SDK opens the music file too frequently. + +- AUDIO_MIXING_ERROR_INTERRUPTED_EOF + + The playback of the music file is interrupted. + +- AUDIO_MIXING_ERROR_OK + + The music file is playing. + +## [AUDIO_MIXING_REASON_TYPE](rtc_api_data_type.html#enum_audiomixingreasontype) + +The reason why the playback state of the music file changes. Reported in the [onAudioMixingStateChanged](class_irtcengineeventhandler.html#callback_onaudiomixingstatechanged_ng) callback. + +- Since + + v3.4.0 + +### Enumerator + +- AUDIO_MIXING_REASON_CAN_NOT_OPEN + + 701: The SDK cannot open the music file. For example, the local music file does not exist, the SDK does not support the file format, or the SDK cannot access the music file URL. + +- AUDIO_MIXING_REASON_TOO_FREQUENT_CALL + + 702: The SDK opens the music file too frequently. If you need to call startAudioMixing multiple times, ensure that the call interval is more than 500 ms. + +- AAUDIO_MIXING_REASON_INTERRUPTED_EOF + + 703: The music file playback is interrupted. + +- AUDIO_MIXING_REASON_STARTED_BY_USER + + 720: The method call of startAudioMixing to play music files succeeds. + +- AUDIO_MIXING_REASON_ONE_LOOP_COMPLETED + + 721: The music file completes a loop playback. + +- AUDIO_MIXING_REASON_START_NEW_LOOP + + 722: The music file starts a new loop playback. + +- AUDIO_MIXING_REASON_ALL_LOOPS_COMPLETED + + 723: The music file completes all loop playbacks. + +- AUDIO_MIXING_REASON_STOPPED_BY_USER + + 724: The method call of [stopAudioMixing](class_irtcengine.html#api_stopaudiomixing) to stop playing the music file succeeds. + +- AUDIO_MIXING_REASON_PAUSED_BY_USER + + 725: The method call of [pauseAudioMixing](class_irtcengine.html#api_pauseaudiomixing) to pause playing the music file succeeds. + +- AUDIO_MIXING_REASON_RESUMED_BY_USER + + 726: The method call of [resumeAudioMixing](class_irtcengine.html#api_resumeaudiomixing) to resume playing the music file succeeds. + +## [AUDIO_MIXING_STATE_TYPE](rtc_api_data_type.html#enum_audiomixingstatetype) + +The playback state of the music file. + +### Enumerator + +- AUDIO_MIXING_STATE_PLAYING + + 710: The music file is playing. + +- AUDIO_MIXING_STATE_PAUSED + + 711: The music file pauses playing. + +- AUDIO_MIXING_STATE_STOPPED + + 713: The music file stops playing. + +- AUDIO_MIXING_STATE_FAILED + + 714: An error occurs during the playback of the audio mixing file. + +- AUDIO_MIXING_STATE_COMPLETED + + (715): The music file is played once. + +- AUDIO_MIXING_STATE_ALL_LOOPS_COMPLETED + + (716): The music file is all played out. + +**See also** + +- [onAudioMixingStateChanged](../API/class_irtcengineeventhandler.html#callback_onaudiomixingstatechanged_ng) + +## [AUDIO_PROFILE_TYPE](rtc_api_data_type.html#enum_audioprofiletype) + +The audio profile. + +### Enumerator + +- AUDIO_PROFILE_DEFAULT + + 0: The default audio profile.For the interactive streaming profile: A sample rate of 48 kHz, music encoding, mono, and a bitrate of up to 64 Kbps.For the communication profile:Windows: A sample rate of 16 kHz, audio encoding, mono, and a bitrate of up to 16 Kbps.Android/macOS/iOS: A sample rate of 32 kHz, audio encoding, mono, and a bitrate of up to 18 Kbps. + +- AUDIO_PROFILE_SPEECH_STANDARD + + 1: A sample rate of 32 kHz, audio encoding, mono, and a bitrate of up to 18 Kbps. + +- AUDIO_PROFILE_MUSIC_STANDARD + + 2: A sample rate of 48 kHz, music encoding, mono, and a bitrate of up to 64 Kbps. + +- AUDIO_PROFILE_MUSIC_STANDARD_STEREO + + 3: A sample rate of 48 kHz, music encoding, stereo, and a bitrate of up to 80 Kbps. + +- AUDIO_PROFILE_MUSIC_HIGH_QUALITY + + 4: A sample rate of 48 kHz, music encoding, mono, and a bitrate of up to 96 Kbps. + +- AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO + + 5: A sample rate of 48 kHz, music encoding, stereo, and a bitrate of up to 128 Kbps. + +- AUDIO_PROFILE_IOT + + 6: A sample rate of 16 kHz, audio encoding, mono, and Acoustic Echo Cancellation (AES) enabled. + +**See also** + +- [setAudioProfile [1/2\]](../API/class_irtcengine.html#api_setaudioprofile) +- [setAudioProfile [2/2\]](../API/class_irtcengine.html#api_setaudioprofile2) + +## [AUDIO_RECORDING_QUALITY_TYPE](rtc_api_data_type.html#enum_audiorecordingqualitytype) + +Recording quality. + +### Enumerator + +- AUDIO_RECORDING_QUALITY_LOW + + 0: Low quality. The sample rate is 32 kHz, and the file size is around 1.2 MB for 10 minutes of recording. + +- AUDIO_RECORDING_QUALITY_MEDIUM + + 1: Medium quality. The sample rate is 32 kHz, and the file size is around 2 MB for 10 minutes of recording. + +- AUDIO_RECORDING_QUALITY_HIGH + + 2: High quality. The sample rate is 32 kHz, and the file size is around 3.75 MB for 10 minutes of recording. + +**See also** + +- [startAudioRecording](../API/class_irtcengine.html#api_startaudiorecording3_ng) + +## [AUDIO_REVERB_PRESET](rtc_api_data_type.html#enum_audioreverbpreset) + +Voice reverb presets. + + + +### Enumerator + +- AUDIO_REVERB_OFF + + Turn off voice reverb, that is, to use the original voice. + +- AUDIO_REVERB_FX_KTV + + The reverb style typical of a KTV venue (enhanced). + +- AUDIO_REVERB_FX_VOCAL_CONCERT + + The reverb style typical of a concert hall (enhanced). + +- AUDIO_REVERB_FX_UNCLE + + A middle-aged man's voice. + +- AUDIO_REVERB_FX_SISTER + + The reverb style typical of a young woman's voice. + +- AUDIO_REVERB_FX_STUDIO + + The reverb style typical of a recording studio (enhanced). + +- AUDIO_REVERB_FX_POPULAR + + The reverb style typical of popular music (enhanced). + +- AUDIO_REVERB_FX_RNB + + The reverb style typical of R&B music (enhanced). + +- AUDIO_REVERB_FX_PHONOGRAPH + + The voice effect typical of a vintage phonograph. + +**See also** + +- [setLocalVoiceReverbPreset](../API/class_irtcengine.html#api_setlocalvoicereverbpreset) + +## [AUDIO_REVERB_TYPE](rtc_api_data_type.html#enum_audioreverbtype) + +Audio reverberation types. + +### Enumerator + +- AUDIO_REVERB_DRY_LEVEL + + 0: The level of the dry signal (dB). The value is between -20 and 10. + +- AUDIO_REVERB_WET_LEVEL + + 1: The level of the early reflection signal (wet signal) (dB). The value is between -20 and 10. + +- AUDIO_REVERB_ROOM_SIZE + + 2: The room size of the reflection. The value is between 0 and 100. + +- AUDIO_REVERB_WET_DELAY + + 3: The length of the initial delay of the wet signal (ms). The value is between 0 and 200. + +- AUDIO_REVERB_STRENGTH + + 4: The reverberation strength. The value is between 0 and 100. + +**See also** + +- [setLocalVoiceReverb](../API/class_irtcengine.html#api_setlocalvoicereverb) + +## [AUDIO_ROUTE_TYPE](rtc_api_data_type.html#enum_audioroutetype) + +The type of the audio route. + +### Enumerator + +- AUDIO_ROUTE_DEFAULT + + -1: The default audio route. + +- AUDIO_ROUTE_HEADSET + + 0: The headset. + +- AUDIO_ROUTE_EARPIECE + + 1: The earpiece. + +- AUDIO_ROUTE_HEADSET_NO_MIC + + 2: The headset with no microphone. + +- AUDIO_ROUTE_SPEAKERPHONE + + 3: The built-in speaker on a mobile device. + +- AUDIO_ROUTE_LOUDSPEAKER + + 4: The external speaker. + +- AUDIO_ROUTE_BLUETOOTH + + 5: The bluetooth headset. + +**See also** + +- [onAudioRoutingChanged](../API/class_irtcengineeventhandler.html#callback_onaudioroutechanged) + +## [AUDIO_SAMPLE_RATE_TYPE](rtc_api_data_type.html#enum_audiosampleratetype) + +The audio sampling rate of the stream to be pushed to the CDN. + +### Enumerator + +- AUDIO_SAMPLE_RATE_32000 + + 32000: 32 kHz + +- AUDIO_SAMPLE_RATE_44100 + + 44100: 44.1 kHz + +- AUDIO_SAMPLE_RATE_48000 + + 48000: (Default) 48 kHz + +**See also** + +- [setLiveTranscoding](../API/class_irtcengine.html#api_setlivetranscoding) + +## [AUDIO_SCENARIO_TYPE](rtc_api_data_type.html#enum_audioscenariotype_ng) + +The audio scenario. + +### Enumerator + +- AUDIO_SCENARIO_DEFAULT + + 0: (Default) Automatic scenario match, where the SDK chooses the appropriate audio quality according to the user role and audio route. + +- AUDIO_SCENARIO_GAME_STREAMING + + 3: High-quality audio scenario, where users mainly play music. + +- AUDIO_SCENARIO_HIGH_DEFINITION + + 6: High-quality audio scenario, where users mainly play music. + +- AUDIO_SCENARIO_CHORUS + + 7: Real-time chorus scenario, where users have good network conditions and require ultra-low latency. + +- AUDIO_SCENARIO_NUM + + The number of enumerations. + +**See also** + +- [setAudioProfile [1/2\]](../API/class_irtcengine.html#api_setaudioprofile) + +## [AUDIO_SESSION_OPERATION_RESTRICTION](rtc_api_data_type.html#enum_audiosessionoperationrestriction) + +The operational permission of the SDK on the audio session. + +### Enumerator + +- AUDIO_SESSION_OPERATION_RESTRICTION_NONE + + No restriction, the SDK has full control of the audio session operations. + +- AUDIO_SESSION_OPERATION_RESTRICTION_SET_CATEGORY + + The SDK does not change the audio session category. + +- AUDIO_SESSION_OPERATION_RESTRICTION_CONFIGURE_SESSION + + The SDK does not change any setting of the audio session (category, mode, categoryOptions). + +- AUDIO_SESSION_OPERATION_RESTRICTION_DEACTIVATE_SESSION + + The SDK keeps the audio session active when leaving a channel. + +- AUDIO_SESSION_OPERATION_RESTRICTION_ALL + + The SDK does not configure the audio session anymore. + +## [CAMERA_DIRECTION](rtc_api_data_type.html#enum_cameradirection) + +The camera direction. + +### Enumerator + +- CAMERA_REAR + + The rear camera. + +- CAMERA_FRONT + + The front camera. + +**See also** + +- [setCameraCapturerConfiguration](../API/class_irtcengine.html#api_setcameracapturerconfiguration) + +## [CAPTURE_BRIGHTNESS_LEVEL_TYPE](rtc_api_data_type.html#enum_capturebrightnessleveltype) + +The brightness level of the video image captured by the local camera. + + + +### Enumerator + +- CAPTURE_BRIGHTNESS_LEVEL_INVALID + + -1: The SDK does not detect the brightness level of the video image. Wait a few seconds to get the brightness level from **captureBrightnessLevel** in the next callback. + +- CAPTURE_BRIGHTNESS_LEVEL_NORMAL + + 0: The brightness level of the video image is normal. + +- CAPTURE_BRIGHTNESS_LEVEL_BRIGHT + + 1: The brightness level of the video image is too bright. + +- CAPTURE_BRIGHTNESS_LEVEL_DARK + + 2: The brightness level of the video image is too dark. + +## [CAPTURER_OUTPUT_PREFERENCE](rtc_api_data_type.html#enum_captureroutputpreference) + +Camera capture preference. + +### Enumerator + +- CAPTURER_OUTPUT_PREFERENCE_AUTO + + 0: (Default) Automatically adjust the camera capture preference. The SDK adjusts the camera output parameters according to the system performance and network conditions to balance CPU consumption and video preview quality. + +- CAPTURER_OUTPUT_PREFERENCE_PERFORMANCE + + 1: Prioritizes the system performance. The SDK chooses the dimension and frame rate of the local camera capture closest to those set by [setVideoEncoderConfiguration](class_irtcengine.html#api_setvideoencoderconfiguration). In this case, the local preview quality depends on the encoder. + +- CAPTURER_OUTPUT_PREFERENCE_PREVIEW + + 2: Prioritizes the local preview quality. The SDK chooses higher camera output parameters to improve the local video preview quality. This option requires extra CPU and RAM usage for video pre-processing. + +- CAPTURER_OUTPUT_PREFERENCE_MANUAL + + 3: Allows you to customize the width and height of the video image captured by the local camera. + +**See also** + +- [setCameraCapturerConfiguration](../API/class_irtcengine.html#api_setcameracapturerconfiguration) + +## [CHANNEL_MEDIA_RELAY_ERROR](rtc_api_data_type.html#enum_channelmediarelayerror) + +The error code of the channel media replay. + +### Enumerator + +- RELAY_OK + + 0: No error. + +- RELAY_ERROR_SERVER_ERROR_RESPONSE + + 1: An error occurs in the server response. + +- RELAY_ERROR_SERVER_NO_RESPONSE + + 2: No server response.You can call [leaveChannel [1/2\]](class_irtcengine.html#api_leavechannel) to leave the channel.This error can also occur if your project has not enabled co-host token authentication. Contact [support@agora.io](mailto:support@agora.io) to enable the co-host token authentication service before starting a channel media relay. + +- RELAY_ERROR_NO_RESOURCE_AVAILABLE + + 3: The SDK fails to access the service, probably due to limited resources of the server. + +- RELAY_ERROR_FAILED_JOIN_SRC + + 4: Fails to send the relay request. + +- RELAY_ERROR_FAILED_JOIN_DEST + + 5: Fails to accept the relay request. + +- RELAY_ERROR_FAILED_PACKET_RECEIVED_FROM_SRC + + 6: The server fails to receive the media stream. + +- RELAY_ERROR_FAILED_PACKET_SENT_TO_DEST + + 7: The server fails to send the media stream. + +- RELAY_ERROR_SERVER_CONNECTION_LOST + + 8: The SDK disconnects from the server due to poor network connections. You can call the [leaveChannel [1/2\]](class_irtcengine.html#api_leavechannel) method to leave the channel. + +- RELAY_ERROR_INTERNAL_ERROR + + 9: An internal error occurs in the server. + +- RELAY_ERROR_SRC_TOKEN_EXPIRED + + 10: The token of the source channel has expired. + +- RELAY_ERROR_DEST_TOKEN_EXPIRED + + 11: The token of the destination channel has expired. + +**See also** + +- [onChannelMediaRelayStateChanged](../API/class_irtcengineeventhandler.html#callback_onchannelmediarelaystatechanged) + +## [CHANNEL_MEDIA_RELAY_EVENT](rtc_api_data_type.html#enum_channelmediarelayevent) + +The event code of channel media relay. + +### Enumerator + +- RELAY_EVENT_NETWORK_DISCONNECTED + + 0: The user disconnects from the server due to a poor network connection. + +- RELAY_EVENT_NETWORK_CONNECTED + + 1: The user is connected to the server. + +- RELAY_EVENT_PACKET_JOINED_SRC_CHANNEL + + 2: The user joins the source channel. + +- RELAY_EVENT_PACKET_JOINED_DEST_CHANNEL + + 3: The user joins the destination channel. + +- RELAY_EVENT_PACKET_SENT_TO_DEST_CHANNEL + + 4: The SDK starts relaying the media stream to the destination channel. + +- RELAY_EVENT_PACKET_RECEIVED_VIDEO_FROM_SRC + + 5: The server receives the audio stream from the source channel. + +- RELAY_EVENT_PACKET_RECEIVED_AUDIO_FROM_SRC + + 6: The server receives the audio stream from the source channel. + +- RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL + + 7: The destination channel is updated. + +- RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL_REFUSED + + 8: The destination channel update fails due to internal reasons. + +- RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL_NOT_CHANGE + + 9: The destination channel does not change, which means that the destination channel fails to be updated. + +- RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL_IS_NULL + + 10: The destination channel name is `NULL`. + +- RELAY_EVENT_VIDEO_PROFILE_UPDATE + + 11: The video profile is sent to the server. + +- RELAY_EVENT_PAUSE_SEND_PACKET_TO_DEST_CHANNEL_SUCCESS + + 12: The SDK successfully pauses relaying the media stream to destination channels. + +- RELAY_EVENT_PAUSE_SEND_PACKET_TO_DEST_CHANNEL_FAILED + + 13: The SDK fails to pause relaying the media stream to destination channels. + +- RELAY_EVENT_RESUME_SEND_PACKET_TO_DEST_CHANNEL_SUCCESS + + 14: The SDK successfully resumes relaying the media stream to destination channels. + +- RELAY_EVENT_RESUME_SEND_PACKET_TO_DEST_CHANNEL_FAILED + + 15: The SDK fails to resume relaying the media stream to destination channels. + +**See also** + +- [onChannelMediaRelayEvent](../API/class_irtcengineeventhandler.html#callback_onchannelmediarelayevent) + +## [CHANNEL_MEDIA_RELAY_STATE](rtc_api_data_type.html#enum_channelmediarelaystate) + +The state code of the channel media relay. + +### Enumerator + +- RELAY_STATE_IDLE + + 0: The initial state. After you successfully stop the channel media relay by calling [stopChannelMediaRelay](class_irtcengine.html#api_stopchannelmediarelay), the [onChannelMediaRelayStateChanged](class_irtcengineeventhandler.html#callback_onchannelmediarelaystatechanged) callback returns this state. + +- RELAY_STATE_CONNECTING + + 1: The SDK tries to relay the media stream to the destination channel. + +- RELAY_STATE_RUNNING + + 2: The SDK successfully relays the media stream to the destination channel. + +- RELAY_STATE_FAILURE + + 3: An error occurs. See **code** in [onChannelMediaRelayStateChanged](class_irtcengineeventhandler.html#callback_onchannelmediarelaystatechanged) for the error code. + +**See also** + +- [onChannelMediaRelayStateChanged](../API/class_irtcengineeventhandler.html#callback_onchannelmediarelaystatechanged) + +## [CHANNEL_PROFILE_TYPE](rtc_api_data_type.html#enum_channelprofiletype_ng) + +The channel profile. + +### Enumerator + +- CHANNEL_PROFILE_COMMUNICATION + + 0: Communication. Use this profile of there are only two users in the channel. + +- CHANNEL_PROFILE_LIVE_BROADCASTING + + 1: Live streaming. Live streaming. Use this profile when there are more than two users in the channel. + +- CHANNEL_PROFILE_GAME + + 2: Gaming. This profile is deprecated. + +- CHANNEL_PROFILE_CLOUD_GAMING + + Cloud gaming. The scenario is optimized for latency. Use this profile if the use case requires frequent interactions between users. + +**See also** + +- [setChannelProfile](../API/class_irtcengine.html#api_setchannelprofile) + +## [CLIENT_ROLE_TYPE](rtc_api_data_type.html#enum_clientroletype) + +The user role in the interactive live streaming. + +### Enumerator + +- CLIENT_ROLE_BROADCASTER + + 1: Host. A host can both send and receive streams. + +- CLIENT_ROLE_AUDIENCE + + 2: (Default) Audience. An audience member can only receive streams. + +**See also** + +- [setClientRole [1/2\]](../API/class_irtcengine.html#api_setclientrole) +- [setClientRole [2/2\]](../API/class_irtcengine.html#api_setclientrole2) +- [onClientRoleChanged](../API/class_irtcengineeventhandler.html#callback_onclientrolechanged) + +## [CLOUD_PROXY_TYPE](rtc_api_data_type.html#enum_cloudproxytype) + +The cloud proxy type. + + + +### Enumerator + +- NONE_PROXY + + 0: Do not use cloud proxy. + +- UDP_PROXY + + 1: Use cloud proxy with the UDP protocol. + +## [CONNECTION_CHANGED_REASON_TYPE](rtc_api_data_type.html#enum_connectionchangedreasontype) + +Reasons causing the change of the connection state. + +### Enumerator + +- CONNECTION_CHANGED_CONNECTING + + 0: The SDK is connecting to the Agora edge server. + +- CONNECTION_CHANGED_JOIN_SUCCESS + + 1: The SDK has joined the channel successfully. + +- CONNECTION_CHANGED_INTERRUPTED + + 2: The connection between the SDK and the Agora edge server is interrupted. + +- CONNECTION_CHANGED_BANNED_BY_SERVER + + 3: The connection between the SDK and the Agora edge server is banned by the Agora edge server. This error occurs when the user is kicked out of the channel by the server. + +- CONNECTION_CHANGED_JOIN_FAILED + + 4: The SDK fails to join the channel. When the SDK fails to join the channel for more than 20 minutes, this error occurs and the SDK stops reconnecting to the channel. + +- CONNECTION_CHANGED_LEAVE_CHANNEL + + 5: The SDK has left the channel. + +- CONNECTION_CHANGED_INVALID_APP_ID + + 6: The connection failed because the App ID is not valid. Please rejoin the channel with a valid App ID. + +- CONNECTION_CHANGED_INVALID_CHANNEL_NAME + + 7: The connection failed since channel name is not valid. Please rejoin the channel with a valid channel name. + +- CONNECTION_CHANGED_INVALID_TOKEN + + 8: The connection failed because the token is not valid. Typical reasons include:The App Certificate for the project is enabled in Agora Console, but you do not use a token when joining the channel. If you enable the App Certificate, you must use a token to join the channel.The uid specified when calling joinChannel [2/2] to join the channel is inconsistent with the uid passed in when generating the token. + +- CONNECTION_CHANGED_TOKEN_EXPIRED + + 9: The connection failed since token is expired. + +- CONNECTION_CHANGED_REJECTED_BY_SERVER + + 10: The connection is rejected by server. Typical reasons include:The user is already in the channel and still calls a method, for example, joinChannel [2/2], to join the channel. Stop calling this method to clear this error.The user tries to join the channel when conducting a pre-call test. The user needs to call the channel after the call test ends. + +- CONNECTION_CHANGED_SETTING_PROXY_SERVER + + 11: The connection state changed to reconnecting because the SDK has set a proxy server. + +- CONNECTION_CHANGED_RENEW_TOKEN + + 12: The connection state changed because the token is renewed. + +- CONNECTION_CHANGED_CLIENT_IP_ADDRESS_CHANGED + + 13: The IP address of the client has changed, possibly because the network type, IP address, or port has been changed. + +- CONNECTION_CHANGED_KEEP_ALIVE_TIMEOUT + + 14: Timeout for the keep-alive of the connection between the SDK and the Agora edge server. The connection state changes to CONNECTION_STATE_RECONNECTING. + +**See also** + +- [onConnectionStateChanged](../API/class_irtcengineeventhandler.html#callback_onconnectionstatechanged) + +## [CONNECTION_STATE_TYPE](rtc_api_data_type.html#enum_connectionstatetype) + +Connection states. + +### Enumerator + +- CONNECTION_STATE_DISCONNECTED + + 1: The SDK is disconnected from the Agora edge server. The state indicates the SDK is in one of the following phases:The initial state before calling the joinChannel [2/2] method.The app calls the [leaveChannel [1/2\]](class_irtcengine.html#api_leavechannel) method. + +- CONNECTION_STATE_CONNECTING + + 2: The SDK is connecting to the Agora edge server. This state indicates that the SDK is establishing a connection with the specified channel after the app calls joinChannel [2/2].If the SDK successfully joins the channel, it triggers the [onConnectionStateChanged](class_irtcengineeventhandler.html#callback_onconnectionstatechanged) callback and the connection state switches to CONNECTION_STATE_CONNECTED.After the connection is established, the SDK also initializes the media and triggers [onJoinChannelSuccess](class_irtcengineeventhandler.html#callback_onjoinchannelsuccess) when everything is ready. + +- CONNECTION_STATE_CONNECTED + + 3: The SDK is connected to the Agora edge server. This state also indicates that the user has joined a channel and can now publish or subscribe to a media stream in the channel. If the connection to the Agora edge server is lost because, for example, the network is down or switched, the SDK automatically tries to reconnect and triggers [onConnectionStateChanged](class_irtcengineeventhandler.html#callback_onconnectionstatechanged) that indicates the connection state switches to CONNECTION_STATE_RECONNECTING. + +- CONNECTION_STATE_RECONNECTING + + 4: The SDK keeps reconnecting to the Agora edge server. The SDK keeps rejoining the channel after being disconnected from a joined channel because of network issues.If the SDK cannot rejoin the channel within 10 seconds, it triggers [onConnectionLost](class_irtcengineeventhandler.html#callback_onconnectionlost), stays in the CONNECTION_STATE_RECONNECTING state, and keeps rejoining the channel.If the SDK fails to rejoin the channel 20 minutes after being disconnected from the Agora edge server, the SDK triggers the [onConnectionStateChanged](class_irtcengineeventhandler.html#callback_onconnectionstatechanged) callback, switches to the CONNECTION_STATE_FAILED state, and stops rejoining the channel. + +- CONNECTION_STATE_FAILED + + 5: The SDK fails to connect to the Agora edge server or join the channel. This state indicates that the SDK stops trying to rejoin the channel. You must call [leaveChannel [1/2\]](class_irtcengine.html#api_leavechannel) to leave the channel.You can call joinChannel [2/2] to rejoin the channel.If the SDK is banned from joining the channel by the Agora edge server through the RESTful API, the SDK triggers the [onConnectionStateChanged](class_irtcengineeventhandler.html#callback_onconnectionstatechanged) callback. + +**See also** + +- [getConnectionStateEx](../API/class_irtcengineex.html#api_irtcengineex_getconnectionstateex) +- [onConnectionStateChanged](../API/class_irtcengineeventhandler.html#callback_onconnectionstatechanged) + +## [DEGRADATION_PREFERENCE](rtc_api_data_type.html#enum_degradationpreference) + +Video degradation preferences when the bandwidth is a constraint. + +### Enumerator + +- MAINTAIN_QUALITY + + 0: (Default) Prefers to reduce the video frame rate while maintaining video quality during video encoding under limited bandwidth. This degradation preference is suitable for scenarios where video quality is prioritized.**Note** In the COMMUNICATION channel profile, the resolution of the video sent may change, so remote users need to handle this issue. See [onVideoSizeChanged](class_irtcengineeventhandler.html#callback_onvideosizechanged). + +- MAINTAIN_FRAMERATE + + 1: Prefers to reduce the video quality while maintaining the video frame rate during video encoding under limited bandwidth. This degradation preference is suitable for scenarios where smoothness is prioritized and video quality is allowed to be reduced. + +- MAINTAIN_BALANCED + + 2: Reduces the video frame rate and video quality simultaneously during video encoding under limited bandwidth. MAINTAIN_BALANCED has a lower reduction than MAINTAIN_QUALITY and MAINTAIN_FRAMERATE, and this preference is suitable for scenarios where both smoothness and video quality are a priority.**Note** The resolution of the video sent may change, so remote users need to handle this issue. See [onVideoSizeChanged](class_irtcengineeventhandler.html#callback_onvideosizechanged). + +**See also** + +- [setVideoEncoderConfiguration](../API/class_irtcengine.html#api_setvideoencoderconfiguration) + +## [EAR_MONITORING_FILTER_TYPE](rtc_api_data_type.html#enum_earmonitoringfiltertype) + +The audio filter of in-ear monitoring: + +### Enumerator + +- EAR_MONITORING_FILTER_NONE + + 1: Do not add an audio filter to the in-ear monitor. + +- EAR_MONITORING_FILTER_BUILT_IN_AUDIO_FILTERS + + 2: Add an audio filter to the in-ear monitor. If you implement functions such as voice beautifier and audio effect, users can hear the voice after adding these effects. + +- EAR_MONITORING_FILTER_NOISE_SUPPRESSION + + 4: Enable noise suppression to the in-ear monitor. + +**See also** + +- [enableInEarMonitoring](../API/class_irtcengine.html#api_enableinearmonitoring2) + +## [ENCRYPTION_ERROR_TYPE](rtc_api_data_type.html#enum_encryptionerrortype) + +Encryption error type. + +### Enumerator + +- ENCRYPTION_ERROR_INTERNAL_FAILURE + + 0: Internal reason. + +- ENCRYPTION_ERROR_DECRYPTION_FAILURE + + 1: Decryption errors. Ensure that the receiver and the sender use the same encryption mode and key. + +- ENCRYPTION_ERROR_ENCRYPTION_FAILURE + + 2: Encryption errors. + +**See also** + +- [onEncryptionError](../API/class_irtcengineeventhandler.html#callback_onencryptionerror) + +## [ENCRYPTION_MODE](rtc_api_data_type.html#enum_encryptionmode) + +The built-in encryption mode. + +Agora recommends using AES_128_GCM2 or AES_256_GCM2 encrypted mode. These two modes support the use of salt for higher security. + +### Enumerator + +- AES_128_XTS + + 1: 128-bit AES encryption, XTS mode. + +- AES_128_ECB + + 2: 128-bit AES encryption, ECB mode. + +- AES_256_XTS + + 3: 256-bit AES encryption, XTS mode. + +- SM4_128_ECB + + 4: 128-bit SM4 encryption, ECB mode. + +- AES_128_GCM + + 5: 128-bit AES encryption, GCM mode. + +- AES_256_GCM + + 6: 256-bit AES encryption, GCM mode. + +- AES_128_GCM2 + + 7: (Default) 128-bit AES encryption, GCM mode. This encryption mode requires the setting of salt (`encryptionKdfSalt`). + +- AES_256_GCM2 + + 8: 256-bit AES encryption, GCM mode. This encryption mode requires the setting of salt (`encryptionKdfSalt`). + +- MODE_END + + Enumerator boundary. + +**See also** + +- [enableEncryption](../API/class_irtcengine.html#api_enableencryption) + +## [EXPERIENCE_POOR_REASON](rtc_api_data_type.html#enum_experiencepoorreason) + +Reasons why the QoE of the local user when receiving a remote audio stream is poor. + + + +### Enumerator + +- EXPERIENCE_REASON_NONE + + 0: No reason, indicating a good QoE of the local user. + +- REMOTE_NETWORK_QUALITY_POOR + + 1: The remote user's network quality is poor. + +- LOCAL_NETWORK_QUALITY_POOR + + 2: The local user's network quality is poor. + +- WIRELESS_SIGNAL_POOR + + 4: The local user's Wi-Fi or mobile network signal is weak. + +- WIFI_BLUETOOTH_COEXIST + + 8: The local user enables both Wi-Fi and bluetooth, and their signals interfere with each other. As a result, audio transmission quality is undermined. + +## [EXPERIENCE_QUALITY_TYPE](rtc_api_data_type.html#enum_experiencequalitytype) + +The Quality of Experience (QoE) of the local user when receiving a remote audio stream. + + + +### Enumerator + +- EXPERIENCE_QUALITY_GOOD + + 0: The QoE of the local user is good. + +- EXPERIENCE_QUALITY_BAD + + 1: The QoE of the local user is poor. + +## [EXTERNAL_VIDEO_SOURCE_TYPE](rtc_api_data_type.html#enum_externalvideosourcetype) + +The external video frame encoding type. + +### Enumerator + +- VIDEO_FRAME + + 0: The video frame is not encoded. + +- ENCODED_VIDEO_FRAME + + 1: The video frame is encoded. + +## [FRAME_RATE](rtc_api_data_type.html#enum_framerate) + +Video frame rate. + +### Enumerator + +- FRAME_RATE_FPS_1 + + 1: 1 fps + +- FRAME_RATE_FPS_7 + + 7: 7 fps + +- FRAME_RATE_FPS_10 + + 10: 10 fps + +- FRAME_RATE_FPS_15 + + 15: 15 fps + +- FRAME_RATE_FPS_24 + + 24: 24 fps + +- FRAME_RATE_FPS_30 + + 30: 30 fps + +- FRAME_RATE_FPS_60 + + 60: 60 fps**Note** (For Windows and macOS only) + +**See also** + +- [setVideoEncoderConfiguration](../API/class_irtcengine.html#api_setvideoencoderconfiguration) + +## [INJECT_STREAM_STATUS](rtc_api_data_type.html#enum_injectstreamstatus) + +States of importing an external video stream in the interactive live streaming. + +### Enumerator + +- INJECT_STREAM_STATUS_START_SUCCESS + + 0: The external video stream is imported successfully. + +- INJECT_STREAM_STATUS_START_ALREADY_EXISTS + + 1: The external video stream already exists. + +- INJECT_STREAM_STATUS_START_UNAUTHORIZED + + 2: The external video stream to be imported is unauthorized. + +- INJECT_STREAM_STATUS_START_TIMEDOUT + + 3: A timeout occurs when importing the external video stream. + +- INJECT_STREAM_STATUS_START_FAILED + + 4: The SDK fails to import the external video stream. + +- INJECT_STREAM_STATUS_STOP_SUCCESS + + 5: The SDK successfully stops importing the external video stream. + +- INJECT_STREAM_STATUS_STOP_NOT_FOUND + + 6: The external video stream to be stopped importing is not found. + +- INJECT_STREAM_STATUS_STOP_UNAUTHORIZED + + 7: The external video stream to be stopped importing is unauthorized. + +- INJECT_STREAM_STATUS_STOP_TIMEDOUT + + 8: A timeout occurs when stopping importing the external video stream. + +- INJECT_STREAM_STATUS_STOP_FAILED + + 9: The SDK fails to stop importing the external video stream. + +- INJECT_STREAM_STATUS_BROKEN + + 10: The external video stream is corrupted. + +## [INTERFACE_ID_TYPE](rtc_api_data_type.html#enum_interfaceidtype) + +The interface class. + +### Enumerator + +- AGORA_IID_AUDIO_DEVICE_MANAGER + + The [IAudioDeviceManager](class_iaudiodevicemanager.html#class_iaudiodevicemanager) interface class. + +- AGORA_IID_VIDEO_DEVICE_MANAGER + + The [IVideoDeviceManager](class_ivideodevicemanager.html#class_ivideodevicemanager) interface class. + +- AGORA_IID_RTC_ENGINE_PARAMETER + + This interface class is deprecated. + +- AGORA_IID_MEDIA_ENGINE + + The [IMediaEngine](class_imediaengine.html#class_imediaengine) interface class. + +- AGORA_IID_SIGNALING_ENGINE + + This interface class is deprecated. + +**See also** + +- [queryInterface](../API/class_irtcengine.html#api_queryinterface) + +## [LASTMILE_PROBE_RESULT_STATE](rtc_api_data_type.html#enum_lastmileproberesultstate) + +The status of the last-mile network tests. + +### Enumerator + +- LASTMILE_PROBE_RESULT_COMPLETE + + 1: The last-mile network probe test is complete. + +- LASTMILE_PROBE_RESULT_INCOMPLETE_NO_BWE + + 2: The last-mile network probe test is incomplete because the bandwidth estimation is not available due to limited test resources. + +- LASTMILE_PROBE_RESULT_UNAVAILABLE + + 3: The last-mile network probe test is not carried out, probably due to poor network conditions. + +**See also** + +- [onLastmileProbeResult](../API/class_irtcengineeventhandler.html#callback_onlastmileproberesult) + +## [LIGHTENING_CONTRAST_LEVEL](rtc_api_data_type.html#enum_lighteningcontrastlevel) + +The contrast level. + +### Enumerator + +- LIGHTENING_CONTRAST_LOW + + Low contrast level. + +- LIGHTENING_CONTRAST_NORMAL + + (Default) Normal contrast level. + +- LIGHTENING_CONTRAST_HIGH + + High contrast level. + +## [LOCAL_AUDIO_STREAM_ERROR](rtc_api_data_type.html#enum_localaudiostreamerror) + +Local audio state error codes. + +### Enumerator + +- LOCAL_AUDIO_STREAM_ERROR_OK + + 0: The local audio is normal. + +- LOCAL_AUDIO_STREAM_ERROR_FAILURE + + 1: No specified reason for the local audio failure. + +- LOCAL_AUDIO_STREAM_ERROR_DEVICE_NO_PERMISSION + + 2: No permission to use the local audio device. + +- LOCAL_AUDIO_STREAM_ERROR_DEVICE_BUSY + + 3: The microphone is in use. + +- LOCAL_AUDIO_STREAM_ERROR_RECORD_FAILURE + + 4: The local audio capturing fails. Check whether the capturing device is working properly. + +- LOCAL_AUDIO_STREAM_ERROR_ENCODE_FAILURE + + 5: The local audio encoding fails. + +**See also** + +- [onLocalAudioStateChanged](../API/class_irtcengineeventhandler.html#callback_onlocalaudiostatechanged) + +## [LOCAL_AUDIO_STREAM_STATE](rtc_api_data_type.html#enum_localaudiostreamstate) + +Local audio states. + +### Enumerator + +- LOCAL_AUDIO_STREAM_STATE_STOPPED + + 0: The local audio is in the initial state. + +- LOCAL_AUDIO_STREAM_STATE_RECORDING + + 1: The capturing device starts successfully. + +- LOCAL_AUDIO_STREAM_STATE_ENCODING + + 2: The first audio frame encodes successfully. + +- LOCAL_AUDIO_STREAM_STATE_FAILED + + 3: The local audio fails to start. + +**See also** + +- [onLocalAudioStateChanged](../API/class_irtcengineeventhandler.html#callback_onlocalaudiostatechanged) + +## [LOCAL_VIDEO_STREAM_ERROR](rtc_api_data_type.html#enum_localvideostreamerror) + +Local video state error codes. + +### Enumerator + +- LOCAL_VIDEO_STREAM_ERROR_OK + + 0: The local video is normal. + +- LOCAL_VIDEO_STREAM_ERROR_FAILURE + + 1: No specified reason for the local video failure. + +- LOCAL_VIDEO_STREAM_ERROR_DEVICE_NO_PERMISSION + + 2: No permission to use the local video capturing device. + +- LOCAL_VIDEO_STREAM_ERROR_DEVICE_BUSY + + 3: The local video capturing device is in use. + +- LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE + + 4: The local video capture fails. Check whether the capturing device is working properly. + +- LOCAL_VIDEO_STREAM_ERROR_ENCODE_FAILURE + + 5: The local video encoding fails. + +- LOCAL_VIDEO_STREAM_ERROR_DEVICE_NOT_FOUND + + 8: Fails to find a local video capture device. + +- LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_MINIMIZED + + [startScreenCaptureByWindowId](class_irtcengine.html#api_startscreencapturebywindowid)11: When calling to share the window, the shared window is in a minimized state. + +- LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_CLOSED + + 12: The error code indicates that a window shared by the window ID has been closed, or a full-screen window shared by the window ID has exited full-screen mode. After exiting full-screen mode, remote users cannot see the shared window. To prevent remote users from seeing a black screen, Agora recommends that you immediately stop screen sharing.Common scenarios for reporting this error code:When the local user closes the shared window, the SDK reports this error code.The local user shows some slides in full-screen mode first, and then shares the windows of the slides. After the user exits full-screen mode, the SDK reports this error code.The local user watches web video or reads web document in full-screen mode first, and then shares the window of the web video or document. After the user exits full-screen mode, the SDK reports this error code. + +**See also** + +- [onLocalVideoStateChanged](../API/class_irtcengineeventhandler.html#callback_onlocalvideostatechanged) + +## [LOCAL_VIDEO_STREAM_STATE](rtc_api_data_type.html#enum_localvideostreamstate) + +Local video state types + +### Enumerator + +- LOCAL_VIDEO_STREAM_STATE_STOPPED + + 0: The local video is in the initial state. + +- LOCAL_VIDEO_STREAM_STATE_CAPTURING + + 1: The local video capturing device starts successfully. The SDK also reports this state when you call [startScreenCaptureByWindowId](class_irtcengine.html#api_startscreencapturebywindowid) to share a maximized window. + +- LOCAL_VIDEO_STREAM_STATE_ENCODING + + 2: The first video frame is successfully encoded. + +- LOCAL_VIDEO_STREAM_STATE_FAILED + + 3: Fails to start the local video. + +**See also** + +- [onLocalVideoStateChanged](../API/class_irtcengineeventhandler.html#callback_onlocalvideostatechanged) + +## [LOG_FILTER_TYPE](rtc_api_data_type.html#enum_logfiltertype) + +The output log level of the SDK. + +### Enumerator + +- LOG_FILTER_OFF + + 0: Do not output any log information. + +- LOG_FILTER_DEBUG + + 0x080f: Output all log information. Set your log filter as DEBUG if you want to get the most complete log file. + +- LOG_FILTER_INFO + + 0x000f: Output CRITICAL, ERROR, WARNING, and INFO level log information. We recommend setting your log filter as this level. + +- LOG_FILTER_WARN + + 0x000e: Output CRITICAL, ERROR, and WARNING level log information. + +- LOG_FILTER_ERROR + + 0x000c: Output CRITICAL and ERROR level log information. + +- LOG_FILTER_CRITICAL + + 0x0008: Output CRITICAL level log information. + +**See also** + +- [setLogFilter](../API/class_irtcengine.html#api_setlogfilter) + +## [LOG_LEVEL](rtc_api_data_type.html#enum_loglevel) + +The output log level of the SDK. + + + +### Enumerator + +- LOG_LEVEL_NONE + + 0: Do not output any log information. + +- LOG_LEVEL_INFO + + 0x0001: (Default) Output `FATAL`, `ERROR`, `WARN`, and `INFO` level log information. We recommend setting your log filter as this level. + +- LOG_LEVEL_WARN + + 0x0002: Output `FATAL`, `ERROR`, and `WARN` level log information. + +- LOG_LEVEL_ERROR + + 0x0004: Output `FATAL` and `ERROR` level log information. + +- LOG_LEVEL_FATAL + + 0x0008: Output `FATAL` level log information. + +**See also** + +- [initialize](../API/class_irtcengine.html#api_create2) +- [setLogLevel](../API/class_irtcengine.html#api_setloglevel) + +## [MAX_CHANNEL_ID_LENGTH_TYPE](rtc_api_data_type.html#enum_maxchannelidlengthtype) + +The maximum length of the channel name. + +### Enumerator + +- MAX_CHANNEL_ID_LENGTH + + The maximum length of the channel name is 64 bytes. + +## [MAX_DEVICE_ID_LENGTH_TYPE](rtc_api_data_type.html#enum_maxdeviceidlengthtype) + +The maximum length of the device ID. + +### Enumerator + +- MAX_DEVICE_ID_LENGTH + + The maximum length of the device ID is 512 bytes. + +**See also** + +- [getPlaybackDevice](../API/class_iaudiodevicemanager.html#api_iaudiodevicemanager_getplaybackdevice) +- [getPlaybackDeviceInfo](../API/class_iaudiodevicemanager.html#api_iaudiodevicemanager_getplaybackdeviceinfo) +- [setPlaybackDevice](../API/class_iaudiodevicemanager.html#api_iaudiodevicemanager_setplaybackdevice) +- [setRecordingDevice](../API/class_iaudiodevicemanager.html#api_iaudiodevicemanager_setrecordingdevice) +- [getDevice](../API/class_ivideodevicecollection.html#api_ivideodevicecollection_getdevice) +- [release](../API/class_iaudiodevicecollection.html#api_iaudiodevicecollection_release) +- [setDevice](../API/class_iaudiodevicecollection.html#api_iaudiodevicecollection_setdevice) +- [getDevice](../API/class_ivideodevicemanager.html#api_ivideodevicemanager_getdevice) +- [setDevice](../API/class_ivideodevicemanager.html#api_ivideodevicemanager_setdevice) +- [setDevice](../API/class_ivideodevicecollection.html#api_ivideodevicecollection_setdevice) + +## [MAX_USER_ACCOUNT_LENGTH_TYPE](rtc_api_data_type.html#enum_maxuseraccountlengthtype) + +The maximum length of the user account. + +### Enumerator + +- MAX_USER_ACCOUNT_LENGTH + + The maximum length of the user account is 256 bytes. + +## [MEDIA_DEVICE_STATE_TYPE](rtc_api_data_type.html#enum_mediadevicestatetype) + +Media device states. + +### Enumerator + +- MEDIA_DEVICE_STATE_IDLE + + 0: The device is ready for use. + +- MEDIA_DEVICE_STATE_ACTIVE + + 1: The device is in use. + +- MEDIA_DEVICE_STATE_DISABLED + + 2: The device is disabled. + +- MEDIA_DEVICE_STATE_NOT_PRESENT + + 4: The device is not found. + +- MEDIA_DEVICE_STATE_UNPLUGGED + + 8: The device is unplugged. + +**See also** + +- [onAudioDeviceStateChanged](../API/class_irtcengineeventhandler.html#callback_onaudiodevicestatechanged) + +## [MEDIA_DEVICE_TYPE](rtc_api_data_type.html#enum_mediadevicetype) + +Media device types. + +### Enumerator + +- UNKNOWN_AUDIO_DEVICE + + -1: Unknown device type. + +- AUDIO_PLAYOUT_DEVICE + + 0: Audio playback device. + +- AUDIO_RECORDING_DEVICE + + 1: Audio capturing device. + +- VIDEO_RENDER_DEVICE + + 2: Video renderer. + +- VIDEO_CAPTURE_DEVICE + + 3: Video capturer. + +- AUDIO_APPLICATION_PLAYOUT_DEVICE + + 4: Application audio playback device. + +**See also** + +- [onAudioDeviceStateChanged](../API/class_irtcengineeventhandler.html#callback_onaudiodevicestatechanged) + +## [MEDIA_PLAYER_PLAYBACK_SPEED](rtc_api_data_type.html#enum_mediaplayerplaybackspeed) + +The playback speed. + +### Enumerator + +- PLAYBACK_SPEED_ORIGINAL + + 100: The original playback speed. + +- PLAYBACK_SPEED_50_PERCENT + + 50: The playback speed is 0.50 times the original speed. + +- PLAYBACK_SPEED_75_PERCENT + + 75: The playback speed is 0.75 times the original speed. + +- PLAYBACK_SPEED_125_PERCENT + + 125: The playback speed is 1.25 times the original speed. + +- PLAYBACK_SPEED_150_PERCENT + + 150: The playback speed is 1.50 times the original speed. + +- PLAYBACK_SPEED_200_PERCENT + + 200: The playback speed is 2.00 times the original speed. + +## [MEDIA_PLAYER_ERROR](rtc_api_data_type.html#enum_mediaplayererror) + +Error codes of the media player. + +### Enumerator + +- PLAYER_ERROR_NONE + + 0: No error. + +- PLAYER_ERROR_INVALID_ARGUMENTS + + -1: Invalid arguments. + +- PLAYER_ERROR_INTERNAL + + -2: Internal errors. + +- PLAYER_ERROR_NO_RESOURCE + + -3: No resource. + +- PLAYER_ERROR_INVALID_MEDIA_SOURCE + + -4: Invalid media resource. + +- PLAYER_ERROR_UNKNOWN_STREAM_TYPE + + -5: The type of the media stream is unknown. + +- PLAYER_ERROR_OBJ_NOT_INITIALIZED + + -6: The object is not initialized. + +- PLAYER_ERROR_CODEC_NOT_SUPPORTED + + -7: The codec is not supported. + +- PLAYER_ERROR_VIDEO_RENDER_FAILED + + -8: Invalid renderer. + +- PLAYER_ERROR_INVALID_STATE + + -9: An error with the internal state of the player occurs. + +- PLAYER_ERROR_URL_NOT_FOUND + + -10: The URL of the media resource can not be found. + +- PLAYER_ERROR_INVALID_CONNECTION_STATE + + -11: Invalid connection between the player and Agora's Server. + +- PLAYER_ERROR_SRC_BUFFER_UNDERFLOW + + -12: The playback buffer is insufficient. + +- PLAYER_ERROR_INTERRUPTED + + -13: The playback is interrupted. + +- PLAYER_ERROR_NOT_SUPPORTED + + -14: The SDK does support the method being called. + +- PLAYER_ERROR_UNKNOWN + + -100: An unknown error. + +**See also** + +- [onPlayerSourceStateChanged](../API/class_imediaplayersourceobserver.html#callback_imediaplayersourceobserver_onplayersourcestatechanged) +- [getPlayPosition](../API/class_imediaplayer.html#api_imediaplayer_getplayposition) + +## [MEDIA_PLAYER_EVENT](rtc_api_data_type.html#enum_mediaplayerevent) + +Media player events. + +### Enumerator + +- PLAYER_EVENT_SEEK_BEGIN + + 0: The player begins to seek to a new playback position. + +- PLAYER_EVENT_SEEK_COMPLETE + + 1: The player finishes seeking to a new playback position. + +- PLAYER_EVENT_SEEK_ERROR + + 2: An error occurs when seeking to a new playback position. + +- PLAYER_EVENT_AUDIO_TRACK_CHANGED + + 5: The audio track used by the player has been changed. + +- PLAYER_EVENT_BUFFER_LOW + + 6: The currently buffered data is not enough to support playback. + +- PLAYER_EVENT_BUFFER_RECOVER + + 7: The currently buffered data is just enough to support playback. + +- PLAYER_EVENT_FREEZE_START + + 8: The audio or video playback freezes. + +- PLAYER_EVENT_FREEZE_STOP + + 9: The audio or video playback resumes without freezing. + +- PLAYER_EVENT_SWITCH_BEGIN + + 10: The player starts switching the media resource. + +- PLAYER_EVENT_SWITCH_COMPLETE + + 11: Media resource switching is complete. + +- PLAYER_EVENT_SWITCH_ERROR + + 12: Media resource switching error. + +- PLAYER_EVENT_FIRST_DISPLAYED + + 13: The first video frame is rendered. + +**See also** + +- [onPlayerEvent](../API/class_imediaplayersourceobserver.html#callback_imediaplayersourceobserver_onplayerevent) + +## [MEDIA_PLAYER_METADATA_TYPE](rtc_api_data_type.html#enum_mediaplayermetadatatype) + +The type of media metadata. + +### Enumerator + +- PLAYER_METADATA_TYPE_UNKNOWN + + 0: The type is unknown. + +- PLAYER_METADATA_TYPE_SEI + + 1: The type is SEI. + +## [MEDIA_PLAYER_STATE](rtc_api_data_type.html#enum_mediaplayerstate) + +The playback state. + +### Enumerator + +- PLAYER_STATE_IDLE + + 0: The default state. The media player returns this state code before you open the media resource or after you stop the playback. + +- PLAYER_STATE_OPENING + + Opening the media resource. + +- PLAYER_STATE_OPEN_COMPLETED + + Opens the media resource successfully. + +- PLAYER_STATE_PLAYING + + The media resource is playing. + +- PLAYER_STATE_PAUSED + + Pauses the playback. + +- PLAYER_STATE_PLAYBACK_COMPLETED + + The playback finishes. + +- PLAYER_STATE_PLAYBACK_ALL_LOOPS_COMPLETED + + The loop finishes. + +- PLAYER_STATE_STOPPED + + The playback stops. + +- PLAYER_STATE_FAILED + + 100: The media player fails to play the media resource. + +**See also** + +- [getState](../API/class_imediaplayer.html#api_imediaplayer_getstate) +- [onPlayerSourceStateChanged](../API/class_imediaplayersourceobserver.html#callback_imediaplayersourceobserver_onplayersourcestatechanged) + +## [MEDIA_SOURCE_TYPE](rtc_api_data_type.html#enum_mediasourcetype) + +Media source type. + +### Enumerator + +- AUDIO_PLAYOUT_SOURCE + + 0: Audio playback device. + +- AUDIO_RECORDING_SOURCE + + 1: Audio capturing device. + +- SECONDARY_CAMERA_SOURCE + + 3: A secondary camera. + +- UNKNOWN_MEDIA_SOURCE + + 100: Unknown media source. + +**See also** + +- [enableVirtualBackground](../API/class_irtcengine.html#api_enablevirtualbackground) +- [enableExtension](../API/class_irtcengine.html#api_enableextension) +- [setExtensionProperty](../API/class_irtcengine.html#api_setextensionproperty) + +## [MEDIA_STREAM_TYPE](rtc_api_data_type.html#enum_mediastreamtype) + +The type of the media stream. + +### Enumerator + +- STREAM_TYPE_UNKNOWN + + 0: The type is unknown. + +- STREAM_TYPE_VIDEO + + 1: The video stream. + +- STREAM_TYPE_AUDIO + + 2: The audio stream. + +- STREAM_TYPE_SUBTITLE + + 3: The subtitle stream. + +## [NETWORK_TYPE](rtc_api_data_type.html#enum_networktype) + +Network type. + +### Enumerator + +- NETWORK_TYPE_UNKNOWN + + -1: The network type is unknown. + +- NETWORK_TYPE_DISCONNECTED + + 0: The SDK disconnects from the network. + +- NETWORK_TYPE_LAN + + 1: The network type is LAN. + +- NETWORK_TYPE_WIFI + + 2: The network type is Wi-Fi (including hotspots). + +- NETWORK_TYPE_MOBILE_2G + + 3: The network type is mobile 2G. + +- NETWORK_TYPE_MOBILE_3G + + 4: The network type is mobile 3G. + +- NETWORK_TYPE_MOBILE_4G + + 5: The network type is mobile 4G. + +**See also** + +- [onNetworkTypeChanged](../API/class_irtcengineeventhandler.html#callback_onnetworktypechanged) + +## [ORIENTATION_MODE](rtc_api_data_type.html#enum_orientationmode) + +Video output orientation modes. + +### Enumerator + +- ORIENTATION_MODE_ADAPTIVE + + 0: (Default) The output video always follows the orientation of the captured video. The receiver takes the rotational information passed on from the video encoder. This mode applies to scenarios where video orientation can be adjusted on the receiver.If the captured video is in landscape mode, the output video is in landscape mode.If the captured video is in portrait mode, the output video is in portrait mode. + +- ORIENTATION_FIXED_LANDSCAPE + + 1: In this mode, the SDK always outputs videos in landscape (horizontal) mode. If the captured video is in portrait mode, the video encoder crops it to fit the output. Applies to situations where the receiving end cannot process the rotational information. For example, CDN live streaming. + +- ORIENTATION_FIXED_PORTRAIT + + 2: In this mode, the SDK always outputs video in portrait (portrait) mode. If the captured video is in landscape mode, the video encoder crops it to fit the output. Applies to situations where the receiving end cannot process the rotational information. For example, CDN live streaming. + +**See also** + +- [setVideoEncoderConfiguration](../API/class_irtcengine.html#api_setvideoencoderconfiguration) +- [addVideoWatermark [2/2\]](../API/class_irtcengine.html#api_addvideowatermark2) + +## [PERMISSION_TYPE](rtc_api_data_type.html#enum_permissiontype) + +The type of the device permission. + +### Enumerator + +- RECORD_AUDIO + + 0: Permission for the audio capture device. + +- CAMERA + + 1: Permission for the camera. + +**See also** + +- [onPermissionError](../API/class_irtcengineeventhandler.html#callback_onpermissionerror) + +## [PLAYER_PRELOAD_EVENT](rtc_api_data_type.html#enum_playerpreloadevent) + +Events that occur when media resources are preloaded. + +### Enumerator + +- PLAYER_PRELOAD_EVENT_BEGIN + + 0: Starts preloading media resources. + +- PLAYER_PRELOAD_EVENT_COMPLETE + + 1: Preloading media resources is complete. + +- PLAYER_PRELOAD_EVENT_ERROR + + 2: An error occurs when preloading media resources. + +## [PRIORITY_TYPE](rtc_api_data_type.html#enum_prioritytype) + +The priority of the remote user. + +### Enumerator + +- PRIORITY_HIGH + + The user's priority is high. + +- PRIORITY_NORMAL + + (Default) The user's priority is normal. + +## [QUALITY_ADAPT_INDICATION](rtc_api_data_type.html#enum_qualityadaptindication) + +Quality change of the local video in terms of target frame rate and target bit rate since last count. + +### Enumerator + +- ADAPT_NONE + + 0: The local video quality stays the same. + +- ADAPT_UP_BANDWIDTH + + 1: The local video quality improves because the network bandwidth increases. + +- ADAPT_DOWN_BANDWIDTH + + 2: The local video quality deteriorates because the network bandwidth decreases. + +**See also** + +- [onLocalVideoStats](../API/class_irtcengineeventhandler.html#callback_onlocalvideostats) + +## [QUALITY_REPORT_FORMAT_TYPE](rtc_api_data_type.html#enum_qualityreportformattype) + +Formats of the quality report. + +### Enumerator + +- QUALITY_REPORT_JSON + + 0: The quality report in JSON format. + +- QUALITY_REPORT_HTML + + 1: The quality report in HTML format. + +## [QUALITY_TYPE](rtc_api_data_type.html#enum_qualitytype) + +Network quality types. + +### Enumerator + +- QUALITY_UNKNOWN + + 0: The network quality is unknown. + +- QUALITY_EXCELLENT + + 1: The network quality is excellent. + +- QUALITY_GOOD + + 2: The network quality is quite good, but the bitrate may be slightly lower than excellent. + +- QUALITY_POOR + + 3: Users can feel the communication slightly impaired. + +- QUALITY_BAD + + 4: Users cannot communicate smoothly. + +- QUALITY_VBAD + + 5: The quality is so bad that users can barely communicate. + +- QUALITY_DOWN + + 6: The network is down and users cannot communicate at all. + +- QUALITY_UNSUPPORTED + + 7: Users cannot detect the network quality. (Not in use.) + +- QUALITY_DETECTING + + 8: Detecting the network quality. + +**See also** + +- [onNetworkQuality](../API/class_irtcengineeventhandler.html#callback_onnetworkquality) +- [onRemoteAudioStats](../API/class_irtcengineeventhandler.html#callback_onremoteaudiostats) +- [onLastmileQuality](../API/class_irtcengineeventhandler.html#callback_onlastmilequality) + +## [RAW_AUDIO_FRAME_OP_MODE_TYPE](rtc_api_data_type.html#enum_rawaudioframeopmodetype) + +The use mode of the audio data. + +### Enumerator + +- RAW_AUDIO_FRAME_OP_MODE_READ_ONLY + + 0: Read-only mode: Users only read the [AudioFrame](class_iaudioframeobserverbase.html#class_audioframe) data without modifying anything.For example, when users acquire the data with the Agora SDK, then push the RTMP or RTMPS streams. + +- RAW_AUDIO_FRAME_OP_MODE_READ_WRITE + + 2: Read and write mode: Users read the data from [AudioFrame](class_iaudioframeobserverbase.html#class_audioframe), modify it, and then play it.For example, when users have their own sound-effect processing module and perform some voice pre-processing, such as a voice change. + +**See also** + +- [setRecordingAudioFrameParameters](../API/class_irtcengine.html#api_setrecordingaudioframeparameters) +- [setPlaybackAudioFrameParameters](../API/class_irtcengine.html#api_setplaybackaudioframeparameters) +- [registerAudioFrameObserver](../API/class_imediaengine.html#api_imediaengine_registeraudioframeobserver) + +## [REMOTE_AUDIO_STATE_REASON](rtc_api_data_type.html#enum_remoteaudiostatereason) + +The reason for the remote audio state change. + +### Enumerator + +- REMOTE_AUDIO_STATE_REASON_INTERNAL + + 0: The SDK reports this reason when the audio state changes. + +- REMOTE_AUDIO_STATE_REASON_NETWORK_CONGESTION + + 1: Network congestion. + +- REMOTE_AUDIO_STATE_REASON_NETWORK_RECOVERY + + 2: Network recovery. + +- REMOTE_AUDIO_STATE_REASON_LOCAL_MUTED + + 3: The local user stops receiving the remote audio stream or disables the audio module. + +- REMOTE_AUDIO_STATE_REASON_LOCAL_UNMUTED + + 4: The local user resumes receiving the remote audio stream or enables the audio module. + +- REMOTE_AUDIO_STATE_REASON_REMOTE_MUTED + + 5: The remote user stops sending the audio stream or disables the audio module. + +- REMOTE_AUDIO_STATE_REASON_REMOTE_UNMUTED + + 6: The remote user resumes sending the audio stream or enables the audio module. + +- REMOTE_AUDIO_STATE_REASON_REMOTE_OFFLINE + + 7: The remote user leaves the channel. + +**See also** + +- [onRemoteAudioStateChanged](../API/class_irtcengineeventhandler.html#callback_onremoteaudiostatechanged) + +## [REMOTE_AUDIO_STATE](rtc_api_data_type.html#enum_remoteaudiostate) + +Remote audio states. + +### Enumerator + +- REMOTE_AUDIO_STATE_STOPPED + + 0: The local audio is in the initial state. The SDK reports this state in the case of REMOTE_AUDIO_STATE_REASON_LOCAL_MUTED, REMOTE_AUDIO_STATE_REASON_REMOTE_MUTED or REMOTE_AUDIO_STATE_REASON_REMOTE_OFFLINE. + +- REMOTE_AUDIO_STATE_STARTING + + 1: The first remote audio packet is received. + +- REMOTE_AUDIO_STATE_DECODING + + 2: The remote audio stream is decoded and plays normally. The SDK reports this state in the case of REMOTE_AUDIO_STATE_REASON_NETWORK_RECOVERY, REMOTE_AUDIO_STATE_REASON_LOCAL_UNMUTED or REMOTE_AUDIO_STATE_REASON_REMOTE_UNMUTED. + +- REMOTE_AUDIO_STATE_FROZEN + + 3: The remote audio is frozen. The SDK reports this state in the case of REMOTE_AUDIO_STATE_REASON_NETWORK_CONGESTION. + +- REMOTE_AUDIO_STATE_FAILED + + 4: The remote audio fails to start. The SDK reports this state in the case of REMOTE_AUDIO_STATE_REASON_INTERNAL. + +**See also** + +- [onRemoteAudioStateChanged](../API/class_irtcengineeventhandler.html#callback_onremoteaudiostatechanged) + +## [REMOTE_VIDEO_STATE_REASON](rtc_api_data_type.html#enum_remotevideostatereason) + +The reason for the remote video state change. + +### Enumerator + +- REMOTE_VIDEO_STATE_REASON_INTERNAL + + 0: The SDK reports this reason when the video state changes. + +- REMOTE_VIDEO_STATE_REASON_NETWORK_CONGESTION + + 1: Network congestion. + +- REMOTE_VIDEO_STATE_REASON_NETWORK_RECOVERY + + 2: Network recovery. + +- REMOTE_VIDEO_STATE_REASON_LOCAL_MUTED + + 3: The local user stops receiving the remote video stream or disables the video module. + +- REMOTE_VIDEO_STATE_REASON_LOCAL_UNMUTED + + 4: The local user resumes receiving the remote video stream or enables the video module. + +- REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED + + 5: The remote user stops sending the video stream or disables the video module. + +- REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED + + 6: The remote user resumes sending the video stream or enables the video module. + +- REMOTE_VIDEO_STATE_REASON_REMOTE_OFFLINE + + 7: The remote user leaves the channel. + +- REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK + + 8: The remote audio-and-video stream falls back to the audio-only stream due to poor network conditions. + +- REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK_RECOVERY + + 9: The remote audio-only stream switches back to the audio-and-video stream after the network conditions improve. + +**See also** + +- [onRemoteVideoStateChanged](../API/class_irtcengineeventhandler.html#callback_onremotevideostatechanged) + +## [REMOTE_VIDEO_STATE](rtc_api_data_type.html#enum_remotevideostate) + +The state of the remote video. + +### Enumerator + +- REMOTE_VIDEO_STATE_STOPPED + + 0: The remote video is in the initial state. The SDK reports this state in the case of REMOTE_VIDEO_STATE_REASON_LOCAL_MUTED, REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED or REMOTE_VIDEO_STATE_REASON_REMOTE_OFFLINE. + +- REMOTE_VIDEO_STATE_STARTING + + 1: The first remote video packet is received. + +- REMOTE_VIDEO_STATE_DECODING + + 2: The remote video stream is decoded and plays normally. The SDK reports this state in the case of REMOTE_VIDEO_STATE_REASON_NETWORK_RECOVERY, REMOTE_VIDEO_STATE_REASON_LOCAL_UNMUTED,REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED, or REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK_RECOVERY. + +- REMOTE_VIDEO_STATE_FROZEN + + 3: The remote video is frozen. The SDK reports this state in the case of REMOTE_VIDEO_STATE_REASON_NETWORK_CONGESTION or REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK. + +- REMOTE_VIDEO_STATE_FAILED + + 4: The remote video fails to start. The SDK reports this state in the case of REMOTE_VIDEO_STATE_REASON_INTERNAL. + +**See also** + +- [onRemoteVideoStateChanged](../API/class_irtcengineeventhandler.html#callback_onremotevideostatechanged) + +## [REMOTE_VIDEO_STREAM_TYPE](rtc_api_data_type.html#enum_remotevideostreamtype) + +The type of video streams. + +### Enumerator + +- REMOTE_VIDEO_STREAM_HIGH + + 0: High-quality video stream. + +- REMOTE_VIDEO_STREAM_LOW + + 1: Low-quality video stream. + +**See also** + +- [setRemoteVideoStreamType](../API/class_irtcengine.html#api_setremotevideostreamtype) +- [setRemoteDefaultVideoStreamType](../API/class_irtcengine.html#api_setremotedefaultvideostreamtype) +- [onRemoteVideoStats](../API/class_irtcengineeventhandler.html#callback_onremotevideostats) + +## [RENDER_MODE_TYPE](rtc_api_data_type.html#enum_rendermodetype) + +Video display modes. + +### Enumerator + +- RENDER_MODE_HIDDEN + + 1: Uniformly scale the video until one of its dimension fits the boundary (zoomed to fit). Hidden mode. One dimension of the video may have clipped contents. + +- RENDER_MODE_FIT + + 2: Uniformly scale the video until one of its dimension fits the boundary (zoomed to fit). Fit mode. Areas that are not filled due to disparity in the aspect ratio are filled with black. + +- RENDER_MODE_ADAPTIVE + + Deprecated:3: This mode is deprecated. + +**See also** + +- [setupLocalVideo](../API/class_irtcengine.html#api_setuplocalvideo) +- [setupRemoteVideo](../API/class_irtcengine.html#api_setupremotevideo) +- [setLocalRenderMode [1/2\]](../API/class_irtcengine.html#api_setlocalrendermode) +- [setLocalRenderMode [2/2\]](../API/class_irtcengine.html#api_setlocalrendermode2) +- [setRemoteRenderMode](../API/class_irtcengine.html#api_setremoterendermode2) +- [setRenderMode](../API/class_imediaplayer.html#api_imediaplayer_setrendermode) + +## [RTMP_STREAM_LIFE_CYCLE_TYPE](rtc_api_data_type.html#enum_rtmpstreamlifecycletype) + +Lifecycle of the CDN live video stream. + +- Deprecated + + + +### Enumerator + +- RTMP_STREAM_LIFE_CYCLE_BIND2CHANNEL + + Bind to the channel lifecycle. If all hosts leave the channel, the CDN live streaming stops after 30 seconds. + +- RTMP_STREAM_LIFE_CYCLE_BIND2OWNER + + Bind to the owner of the RTMP stream. If the owner leaves the channel, the CDN live streaming stops immediately. + +## [RTMP_STREAM_PUBLISH_ERROR](rtc_api_data_type.html#enum_rtmpstreampublisherror) + +Error codes of the RTMP or RTMPS streaming. + +### Enumerator + +- RTMP_STREAM_PUBLISH_ERROR_OK + + The RTMP or RTMPS streaming publishes successfully. + +- RTMP_STREAM_PUBLISH_ERROR_INVALID_ARGUMENT + + Invalid argument used. Please check the parameter setting. For example, if you do not call [setLiveTranscoding](class_irtcengine.html#api_setlivetranscoding) to set the transcoding parameters before calling [addPublishStreamUrl](class_irtcengine.html#api_addpublishstreamurl), the SDK returns this error. + +- RTMP_STREAM_PUBLISH_ERROR_ENCRYPTED_STREAM_NOT_ALLOWED + + Check whether you set the parameters in the setLiveTranscoding method properly. + +- RTMP_STREAM_PUBLISH_ERROR_CONNECTION_TIMEOUT + + The RTMP or RTMPS streaming is encrypted and cannot be published. Call [addPublishStreamUrl](class_irtcengine.html#api_addpublishstreamurl) to re-publish the stream. + +- RTMP_STREAM_PUBLISH_ERROR_INTERNAL_SERVER_ERROR + + An error occurs in Agora's streaming server. Call the [addPublishStreamUrl](class_irtcengine.html#api_addpublishstreamurl) method to publish the streaming again. + +- RTMP_STREAM_PUBLISH_ERROR_RTMP_SERVER_ERROR + + An error occurs in the CDN server. + +- RTMP_STREAM_PUBLISH_ERROR_TOO_OFTEN + + The RTMP or RTMPS streaming publishes too frequently. + +- RTMP_STREAM_PUBLISH_ERROR_REACH_LIMIT + + The host has published more than 10 URLs. Delete the unnecessary URLs before adding new ones. + +- RTMP_STREAM_PUBLISH_ERROR_NOT_AUTHORIZED + + The host manipulates other hosts' streams. For example, the host updates or stops other hosts' streams. Check your app logic. + +- RTMP_STREAM_PUBLISH_ERROR_STREAM_NOT_FOUND + + Agora's server fails to find the RTMP or RTMPS streaming. + +- RTMP_STREAM_PUBLISH_ERROR_FORMAT_NOT_SUPPORTED + + The URL format is incorrect. Check whether the URL format is correct. + +**See also** + +- [onRtmpStreamingStateChanged](../API/class_irtcengineeventhandler.html#callback_onrtmpstreamingstatechanged) + +## [RTMP_STREAM_PUBLISH_STATE](rtc_api_data_type.html#enum_rtmpstreampublishstate) + +States of the RTMP or RTMPS streaming. + +### Enumerator + +- RTMP_STREAM_PUBLISH_STATE_IDLE + + The RTMP or RTMPS streaming has not started or has ended. This state is also triggered after you remove an RTMP or RTMPS stream from the CDN by calling [removePublishStreamUrl](class_irtcengine.html#api_removepublishstreamurl). + +- RTMP_STREAM_PUBLISH_STATE_CONNECTING + + The SDK is connecting to Agora's streaming server and the CDN server. This state is triggered after you call the [addPublishStreamUrl](class_irtcengine.html#api_addpublishstreamurl) method. + +- RTMP_STREAM_PUBLISH_STATE_RUNNING + + The RTMP or RTMPS streaming publishes. The SDK successfully publishes the RTMP or RTMPS streaming and returns this state. + +- RTMP_STREAM_PUBLISH_STATE_RECOVERING + + The RTMP or RTMPS streaming is recovering. When exceptions occur to the CDN, or the streaming is interrupted, the SDK tries to resume RTMP or RTMPS streaming and returns this state.If the SDK successfully resumes the streaming, RTMP_STREAM_PUBLISH_STATE_RUNNING(2) returns.If the streaming does not resume within 60 seconds or server errors occur, RTMP_STREAM_PUBLISH_STATE_FAILURE(4) returns. You can also reconnect to the server by calling the [removePublishStreamUrl](class_irtcengine.html#api_removepublishstreamurl) and [addPublishStreamUrl](class_irtcengine.html#api_addpublishstreamurl) methods. + +- RTMP_STREAM_PUBLISH_STATE_FAILURE + + The RTMP or RTMPS streaming fails. See the error code for the detailed error information. You can also call the [addPublishStreamUrl](class_irtcengine.html#api_addpublishstreamurl) method to publish the RTMP or RTMPS stream again. + +**See also** + +- [onRtmpStreamingStateChanged](../API/class_irtcengineeventhandler.html#callback_onrtmpstreamingstatechanged) + +## [RTMP_STREAMING_EVENT](rtc_api_data_type.html#enum_rtmpstreamingevent) + +Events during the RTMP or RTMPS streaming. + +### Enumerator + +- RTMP_STREAMING_EVENT_FAILED_LOAD_IMAGE + + An error occurs when you add a background image or a watermark image to the RTMP or RTMPS stream. + +## [STREAM_PUBLISH_STATE](rtc_api_data_type.html#enum_streampublishstate) + +The publishing state. + +### Enumerator + +- PUB_STATE_IDLE + + 0: The initial publishing state after joining the channel. + +- PUB_STATE_NO_PUBLISHED + + 1: Fails to publish the local stream. Possible reasons:The local user calls [muteLocalAudioStream](class_irtcengine.html#api_mutelocalaudiostream)(`true`) or [muteLocalVideoStream](class_irtcengine.html#api_mutelocalvideostream)(`true`) to stop sending the local media stream.The local user calls [disableAudio](class_irtcengine.html#api_disableaudio) or [disableVideo](class_irtcengine.html#api_disablevideo) to disable the local audio or video module.The local user calls [enableLocalAudio](class_irtcengine.html#api_enablelocalaudio)(`false`) or [enableLocalVideo](class_irtcengine.html#api_enablelocalvideo)(`false`) to disable the local audio or video capture.The role of the local user is audience. + +- PUB_STATE_PUBLISHING + + 2: Publishing. + +- PUB_STATE_PUBLISHED + + 3: Publishes successfully. + +**See also** + +- [onAudioPublishStateChanged](../API/class_irtcengineeventhandler.html#callback_onaudiopublishstatechanged) +- [onVideoPublishStateChanged](../API/class_irtcengineeventhandler.html#callback_onvideopublishstatechanged) + +## [STREAM_SUBSCRIBE_STATE](rtc_api_data_type.html#enum_streamsubscribestate) + +The subscribing state. + +### Enumerator + +- SUB_STATE_IDLE + + 0: The initial subscribing state after joining the channel. + +- SUB_STATE_NO_SUBSCRIBED + + 1: Fails to subscribe to the remote stream. Possible reasons:The remote user:Calls [muteLocalAudioStream](class_irtcengine.html#api_mutelocalaudiostream)(`true`) or [muteLocalVideoStream](class_irtcengine.html#api_mutelocalvideostream)(`true`) to stop sending local media stream.Calls [disableAudio](class_irtcengine.html#api_disableaudio) or [disableVideo](class_irtcengine.html#api_disablevideo) to disable the local audio or video module.Calls [enableLocalAudio](class_irtcengine.html#api_enablelocalaudio)(false) or [enableLocalVideo](class_irtcengine.html#api_enablelocalvideo)(false) to disable the local audio or video capture.The role of the remote user is audience.The local user calls the following methods to stop receiving remote streams:Calls [muteRemoteAudioStream](class_irtcengine.html#api_muteremoteaudiostream)(true), [muteAllRemoteAudioStreams](class_irtcengine.html#api_muteallremoteaudiostreams)(true) or [setDefaultMuteAllRemoteAudioStreams](class_irtcengine.html#api_setdefaultmuteallremoteaudiostreams)(true) to stop receiving the remote audio streams.Calls [muteRemoteVideoStream](class_irtcengine.html#api_muteremotevideostream)(true), [muteAllRemoteVideoStreams](class_irtcengine.html#api_muteallremotevideostreams)(true) or [setDefaultMuteAllRemoteVideoStreams](class_irtcengine.html#api_setdefaultmuteallremotevideostreams)(true) to stop receiving the remote video streams. + +- SUB_STATE_SUBSCRIBING + + 2: Subscribing. + +- SUB_STATE_SUBSCRIBED + + 3: Subscribes to and receives the remote stream successfully. + +**See also** + +- [onAudioSubscribeStateChanged](../API/class_irtcengineeventhandler.html#callback_onaudiosubscribestatechanged) +- [onVideoSubscribeStateChanged](../API/class_irtcengineeventhandler.html#callback_onvideosubscribestatechanged) + +## [USER_OFFLINE_REASON_TYPE](rtc_api_data_type.html#enum_userofflinereasontype) + +Reasons for a user being offline. + +### Enumerator + +- USER_OFFLINE_QUIT + + 0: The user quits the call. + +- USER_OFFLINE_DROPPED + + 1: The SDK times out and the user drops offline because no data packet is received within a certain period of time.**Note** If the user quits the call and the message is not passed to the SDK (due to an unreliable channel), the SDK assumes the user dropped offline. + +- USER_OFFLINE_BECOME_AUDIENCE + + 2: The user switches the client role from the host to the audience. + +**See also** + +- [onUserOffline](../API/class_irtcengineeventhandler.html#callback_onuseroffline) + +## [VIDEO_BUFFER_TYPE](rtc_api_data_type.html#enum_videobuffertype) + +The video buffer type. + +### Enumerator + +- VIDEO_BUFFER_RAW_DATA + + 1: The video buffer in the format of raw data. + +- VIDEO_BUFFER_ARRAY + + 2: The video buffer in the format of raw data. + +- VIDEO_BUFFER_TEXTURE + + 3: The video buffer in the format of `Texture`. + +**See also** + +- [pushVideoFrame [1/2\]](../API/class_imediaengine.html#api_imediaengine_pushvideoframe) +- [pushVideoFrame [2/2\]](../API/class_imediaengine.html#api_irtcengineex_pushvideoframeex) + +## [VIDEO_CAPTURE_TYPE](rtc_api_data_type.html#enum_videocapturetype) + +The capture type of the custom video source. + +### Enumerator + +- VIDEO_CAPTURE_UNKNOWN + + Unknown type. + +- VIDEO_CAPTURE_CAMERA + + (Default) Video captured by the camera. + +- VIDEO_CAPTURE_SCREEN + + Video for screen sharing. + +## [VIDEO_CODEC_PROFILE_TYPE](rtc_api_data_type.html#enum_videocodecprofiletype) + +Video codec profile types. + +- VIDEO_CODEC_PROFILE_BASELINE + + 66: Baseline video codec profile. Generally used for video calls on mobile phones. + +- VIDEO_CODEC_PROFILE_MAIN + + 77: Main video codec profile. Generally used in mainstream electronics such as MP4 players, portable video players, PSP, and iPads. + +- VIDEO_CODEC_PROFILE_HIGH + + 100: (Default) High video codec profile. Generally used in high-resolution live streaming or television. + +**See also** + +- [setLiveTranscoding](../API/class_irtcengine.html#api_setlivetranscoding) + +## [VIDEO_CODEC_TYPE](rtc_api_data_type.html#enum_videocodectype) + +Video codec types. + +### Enumerator + +- VIDEO_CODEC_VP8 + + Standard VP8. + +- VIDEO_CODEC_H264 + + Standard H.264. + +- VIDEO_CODEC_H265 + + Standard H.264. + +- VIDEO_CODEC_GENERIC + + Generic.This type is used for transmitting raw video data, such as encrypted video frames. The SDK returns this type of video frames in callbacks, and you need to decode and render the frames yourself. + +- VIDEO_CODEC_GENERIC_JPEG + + Generic JPEG.This type consumes minimum computing resources and applies to IoT devices. + +- VIDEO_CODEC_VP9 + + Standard VP9. + +**See also** + +- [setLiveTranscoding](../API/class_irtcengine.html#api_setlivetranscoding) +- [onLocalVideoStats](../API/class_irtcengineeventhandler.html#callback_onlocalvideostats) + +## [VideoContentHint](rtc_api_data_type.html#enum_videocontenthint) + +The content hint for screen sharing. + +### Enumerator + +- CONTENT_HINT_NONE + + (Default) No content hint. + +- CONTENT_HINT_MOTION + + Motion-intensive content. Choose this option if you prefer smoothness or when you are sharing a video clip, movie, or video game. + +- CONTENT_HINT_DETAILS + + Motionless content. Choose this option if you prefer sharpness or when you are sharing a picture, PowerPoint slides, or texts. + +**See also** + +- [setScreenCaptureContentHint](../API/class_irtcengine.html#api_setscreencapturecontenthint) + +## [VIDEO_FRAME_TYPE](rtc_api_data_type.html#enum_videoframetype_ng) + +The video frame type. + +### Enumerator + +- VIDEO_FRAME_TYPE_BLANK_FRAME + + 0: A black frame. + +- VIDEO_FRAME_TYPE_KEY_FRAME + + 3: Keyframe. + +- VIDEO_FRAME_TYPE_DELTA_FRAME + + 4: Delta frame. + +- VIDEO_FRAME_TYPE_B_FRAME + + 5: The B frame. + +- VIDEO_FRAME_TYPE_DROPPABLE_FRAME + + 6: A discarded frame. + +- VIDEO_FRAME_TYPE_UNKNOW + + Unknown frame. + +## [VIDEO_MIRROR_MODE_TYPE](rtc_api_data_type.html#enum_videomirrormodetype) + +Video mirror mode. + +### Enumerator + +- VIDEO_MIRROR_MODE_AUTO + + 0: (Default) The SDK determines the mirror mode. + +- VIDEO_MIRROR_MODE_ENABLED + + 1: Enable mirror mode. + +- VIDEO_MIRROR_MODE_DISABLED + + 2: Disable mirror mode. + +**See also** + +- [setVideoEncoderConfiguration](../API/class_irtcengine.html#api_setvideoencoderconfiguration) +- [setupLocalVideo](../API/class_irtcengine.html#api_setuplocalvideo) +- [setupRemoteVideo](../API/class_irtcengine.html#api_setupremotevideo) +- [setLocalRenderMode [1/2\]](../API/class_irtcengine.html#api_setlocalrendermode) +- [setLocalRenderMode [2/2\]](../API/class_irtcengine.html#api_setlocalrendermode2) +- [setRemoteRenderMode](../API/class_irtcengine.html#api_setremoterendermode2) +- [setLocalVideoMirrorMode](../API/class_irtcengine.html#api_setlocalvideomirrormode) + +## [VIDEO_MODULE_POSITION](rtc_api_data_type.html#enum_videoobserverposition) + +The frame position of the video observer. + +### Enumerator + +- POSITION_POST_CAPTURER + + 1: The post-capturer position, which corresponds to the video data in the onCaptureVideoFrame callback. + +- POSITION_PRE_RENDERER + + 2: The pre-renderer position, which corresponds to the video data in the onRenderVideoFrame callback. + +- POSITION_PRE_ENCODER + + 4: The pre-encoder position, which corresponds to the video data in the onPreEncodeVideoFrame callback. + +## [VIDEO_ORIENTATION](rtc_api_data_type.html#enum_videoorientation) + +The clockwise rotation of the video. + +### Enumerator + +- VIDEO_ORIENTATION_0 + + 0: (Default) No rotation. + +- VIDEO_ORIENTATION_90 + + 90: 90 degrees. + +- VIDEO_ORIENTATION_180 + + 180: 180 degrees. + +- VIDEO_ORIENTATION_270 + + 270: 270 degrees. + +**See also** + +- [setCameraDeviceOrientation](../API/class_irtcengine.html#api_setcameradeviceorientation) + +## [VIDEO_PIXEL_FORMAT](rtc_api_data_type.html#enum_videopixelformat) + +The video pixel format. + +### Enumerator + +**Note** The SDK does not support the alpha channel, and discards any alpha value passed to the SDK. + +- VIDEO_PIXEL_UNKNOWN + + 0: The format is known. + +- VIDEO_PIXEL_I420 + + 1: The format is I420. + +- VIDEO_PIXEL_BGRA + + 2: The format is BGRA. + +- VIDEO_PIXEL_NV21 + + 3: The format is NV21. + +- VIDEO_PIXEL_RGBA + + 4: The format is RGBA. + +- VIDEO_PIXEL_IMC2 + + 5: The format is IMC2. + +- VIDEO_PIXEL_ARGB + + 7: The format is ARGB. + +- VIDEO_PIXEL_NV12 + + 8: The format is NV12. + +- VIDEO_PIXEL_I422 + + 16: The format is I422. + +**See also** + +- [pushVideoFrame [1/2\]](../API/class_imediaengine.html#api_imediaengine_pushvideoframe) +- [pushVideoFrame [2/2\]](../API/class_imediaengine.html#api_irtcengineex_pushvideoframeex) +- [onCaptureVideoFrame](../API/class_ivideoframeobserver.html#callback_ivideoframeobserver_oncapturevideoframe) +- [onRenderVideoFrame](../API/class_ivideoframeobserver.html#callback_ivideoframeobserver_onrendervideoframe) +- [getRotationApplied](../API/class_ivideoframeobserver.html#callback_ivideoframeobserver_getrotationapplied) + +## [VIDEO_PROFILE_TYPE](rtc_api_data_type.html#enum_videoprofiletype) + +Video profile + +- Deprecated + + + +### Enumerator + +- VIDEO_PROFILE_LANDSCAPE_120P + + 0: 160 × 120, frame rate 15 fps, bitrate 65 Kbps. + +- VIDEO_PROFILE_LANDSCAPE_120P_3 + + 2: 120 × 120, frame rate 15 fps, bitrate 50 Kbps. + +- VIDEO_PROFILE_LANDSCAPE_180P + + 10: 320 × 180, frame rate 15 fps, bitrate 140 Kbps. + +- VIDEO_PROFILE_LANDSCAPE_180P_3 + + 12: 180 × 180, frame rate 15 fps, bitrate 100 Kbps. + +- VIDEO_PROFILE_LANDSCAPE_180P_4 + + 13: 240 × 180, frame rate 15 fps, bitrate 120 Kbps. + +- VIDEO_PROFILE_LANDSCAPE_240P + + 20: 320 × 240, frame rate 15 fps, bitrate 200 Kbps. + +- VIDEO_PROFILE_LANDSCAPE_240P_3 + + 22: 240 × 240, frame rate 15 fps, bitrate 140 Kbps. + +- VIDEO_PROFILE_LANDSCAPE_240P_4 + + 23: 424 × 240, frame rate 15 fps, bitrate 220 Kbps. + +- VIDEO_PROFILE_LANDSCAPE_360P + + 30: 640 × 360, frame rate 15 fps, bitrate 400 Kbps. + +- VIDEO_PROFILE_LANDSCAPE_360P_3 + + 32: 360 × 360, frame rate 15 fps, bitrate 260 Kbps. + +- VIDEO_PROFILE_LANDSCAPE_360P_4 + + 33: 640 × 360, frame rate 30 fps, bitrate 600 Kbps. + +- VIDEO_PROFILE_LANDSCAPE_360P_6 + + 35: 360 × 360, frame rate 30 fps, bitrate 400 Kbps. + +- VIDEO_PROFILE_LANDSCAPE_360P_7 + + 36: 480 × 360, frame rate 15 fps, bitrate 320 Kbps. + +- VIDEO_PROFILE_LANDSCAPE_360P_8 + + 37: 480 × 360, frame rate 30 fps, bitrate 490 Kbps. + +- VIDEO_PROFILE_LANDSCAPE_360P_9 + + 38: 640 × 360, frame rate 15 fps, bitrate 800 Kbps.**Note** This profile applies only to the live streaming channel profile. + +- VIDEO_PROFILE_LANDSCAPE_360P_10 + + 39: 640 × 360, frame rate 24 fps, bitrate 800 Kbps.**Note** This profile applies only to the live streaming channel profile. + +- VIDEO_PROFILE_LANDSCAPE_360P_11 + + 100: 640 × 360, frame rate 24 fps, bitrate 1000 Kbps.**Note** This profile applies only to the live streaming channel profile. + +- VIDEO_PROFILE_LANDSCAPE_480P + + 40: 640 × 480, frame rate 15 fps, bitrate 500 Kbps. + +- VIDEO_PROFILE_LANDSCAPE_480P_3 + + 42: 480 × 480, frame rate 15 fps, bitrate 400 Kbps. + +- VIDEO_PROFILE_LANDSCAPE_480P_4 + + 43: 640 × 480, frame rate 30 fps, bitrate 750 Kbps. + +- VIDEO_PROFILE_LANDSCAPE_480P_6 + + 45: 480 × 480, frame rate 30 fps, bitrate 600 Kbps. + +- VIDEO_PROFILE_LANDSCAPE_480P_8 + + 47: 848 × 480, frame rate 15 fps, bitrate 610 Kbps. + +- VIDEO_PROFILE_LANDSCAPE_480P_9 + + 48: 848 × 480, frame rate 30 fps, bitrate 930 Kbps. + +- VIDEO_PROFILE_LANDSCAPE_480P_10 + + 49: 640 × 480, frame rate 10 fps, bitrate 400 Kbps. + +- VIDEO_PROFILE_LANDSCAPE_720P + + 50: 1280 × 720, frame rate 15 fps, bitrate 1130 Kbps. + +- VIDEO_PROFILE_LANDSCAPE_720P_3 + + 52: 1280 × 720, frame rate 30 fps, bitrate 1710 Kbps. + +- VIDEO_PROFILE_LANDSCAPE_720P_5 + + 54: 960 × 720, frame rate 15 fps, bitrate 910 Kbps. + +- VIDEO_PROFILE_LANDSCAPE_720P_6 + + 55: 960 × 720, frame rate 30 fps, bitrate 1380 Kbps. + +- VIDEO_PROFILE_LANDSCAPE_1080P + + 60: 1920 × 1080, frame rate 15 fps, bitrate 2080 Kbps. + +- VIDEO_PROFILE_LANDSCAPE_1080P_3 + + 60: 1920 × 1080, frame rate 30 fps, bitrate 3150 Kbps. + +- VIDEO_PROFILE_LANDSCAPE_1080P_5 + + 64: 1920 × 1080, frame rate 60 fps, bitrate 4780 Kbps. + +- VIDEO_PROFILE_PORTRAIT_120P + + 1000: 120 × 160, frame rate 15 fps, bitrate 65 Kbps. + +- VIDEO_PROFILE_PORTRAIT_120P_3 + + 1002: 120 × 120, frame rate 15 fps, bitrate 50 Kbps. + +- VIDEO_PROFILE_PORTRAIT_180P + + 1010: 180 × 320, frame rate 15 fps, bitrate 140 Kbps. + +- VIDEO_PROFILE_PORTRAIT_180P_3 + + 1012: 180 × 180, frame rate 15 fps, bitrate 100 Kbps. + +- VIDEO_PROFILE_PORTRAIT_180P_4 + + 1013: 180 × 240, frame rate 15 fps, bitrate 120 Kbps. + +- VIDEO_PROFILE_PORTRAIT_240P + + 1020: 240 × 320, frame rate 15 fps, bitrate 200 Kbps. + +- VIDEO_PROFILE_PORTRAIT_240P_3 + + 1022: 240 × 240, frame rate 15 fps, bitrate 140 Kbps. + +- VIDEO_PROFILE_PORTRAIT_240P_4 + + 1023: 240 × 424, frame rate 15 fps, bitrate 220 Kbps. + +- VIDEO_PROFILE_PORTRAIT_360P + + 1030: 360 × 640, frame rate 15 fps, bitrate 400 Kbps. + +- VIDEO_PROFILE_PORTRAIT_360P_3 + + 1032: 360 × 360, frame rate 15 fps, bitrate 260 Kbps. + +- VIDEO_PROFILE_PORTRAIT_360P_4 + + 1033: 360 × 640, frame rate 15 fps, bitrate 600 Kbps. + +- VIDEO_PROFILE_PORTRAIT_360P_6 + + 1035: 360 × 360, frame rate 30 fps, bitrate 400 Kbps. + +- VIDEO_PROFILE_PORTRAIT_360P_7 + + 1036: 360 × 480, frame rate 15 fps, bitrate 320 Kbps. + +- VIDEO_PROFILE_PORTRAIT_360P_8 + + 1037: 360 × 480, frame rate 30 fps, bitrate 490 Kbps. + +- VIDEO_PROFILE_PORTRAIT_360P_9 + + 1038: 360 × 640, frame rate 15 fps, bitrate 800 Kbps.**Note** This profile applies only to the live streaming channel profile. + +- VIDEO_PROFILE_PORTRAIT_360P_10 + + 1039: 360 × 640, frame rate 24 fps, bitrate 800 Kbps.**Note** This profile applies only to the live streaming channel profile. + +- VIDEO_PROFILE_PORTRAIT_360P_11 + + 1100: 360 × 640, frame rate 24 fps, bitrate 1000 Kbps.**Note** This profile applies only to the live streaming channel profile. + +- VIDEO_PROFILE_PORTRAIT_480P + + 1040: 480 × 640, frame rate 15 fps, bitrate 500 Kbps. + +- VIDEO_PROFILE_PORTRAIT_480P_3 + + 1042: 480 × 480, frame rate 15 fps, bitrate 400 Kbps. + +- VIDEO_PROFILE_PORTRAIT_480P_4 + + 1043: 480 × 640, frame rate 30 fps, bitrate 750 Kbps. + +- VIDEO_PROFILE_PORTRAIT_480P_6 + + 1045: 480 × 480, frame rate 30 fps, bitrate 600 Kbps. + +- VIDEO_PROFILE_PORTRAIT_480P_8 + + 1047: 480 × 848, frame rate 15 fps, bitrate 610 Kbps. + +- VIDEO_PROFILE_PORTRAIT_480P_9 + + 1048: 480 × 848, frame rate 30 fps, bitrate 930 Kbps. + +- VIDEO_PROFILE_PORTRAIT_480P_10 + + 1049: 480 × 640, frame rate 10 fps, bitrate 400 Kbps. + +- VIDEO_PROFILE_PORTRAIT_720P + + 1050: 720 × 1280, frame rate 15 fps, bitrate 1130 Kbps. + +- VIDEO_PROFILE_PORTRAIT_720P_3 + + 1052: 720 × 1280, frame rate 30 fps, bitrate 1710 Kbps. + +- VIDEO_PROFILE_PORTRAIT_720P_5 + + 1054: 720 × 960, frame rate 15 fps, bitrate 910 Kbps. + +- VIDEO_PROFILE_PORTRAIT_720P_6 + + 1055: 720 × 960, frame rate 30 fps, bitrate 1380 Kbps. + +- VIDEO_PROFILE_PORTRAIT_1080P + + 1060: 1080 × 1920, frame rate 15 fps, bitrate 2080 Kbps. + +- VIDEO_PROFILE_PORTRAIT_1080P_3 + + 1062: 1080 × 1920, frame rate 30 fps, bitrate 3150 Kbps. + +- VIDEO_PROFILE_PORTRAIT_1080P_5 + + 1064: 1080 × 1920, frame rate 60 fps, bitrate 4780 Kbps. + +- VIDEO_PROFILE_DEFAULT + + (Default) 640 × 360, frame rate 15 fps, bitrate 400 Kbps. + +## [VIDEO_SOURCE_TYPE](rtc_api_data_type.html#enum_videosourcetype) + +The capture type of the custom video source. + +### Enumerator + +- VIDEO_SOURCE_CAMERA_PRIMARY + + (Default) The primary camera. + +- VIDEO_SOURCE_CAMERA + + The camera. + +- VIDEO_SOURCE_CAMERA_SECONDARY + + The secondary camera. + +- VIDEO_SOURCE_SCREEN_PRIMARY + + The primary screen. + +- VIDEO_SOURCE_SCREEN + + The screen. + +- VIDEO_SOURCE_SCREEN_SECONDARY + + The secondary screen. + +- VIDEO_SOURCE_CUSTOM + + The custom video source. + +- VIDEO_SOURCE_MEDIA_PLAYER + + The video source from the media player. + +- VIDEO_SOURCE_RTC_IMAGE_PNG + + The video source is a PNG image. + +- VIDEO_SOURCE_RTC_IMAGE_JPEG + + The video source is a JPEG image. + +- VIDEO_SOURCE_RTC_IMAGE_GIF + + The video source is a GIF image. + +- VIDEO_SOURCE_REMOTE + + The video source is remote video acquired by the network. + +- VIDEO_SOURCE_TRANSCODED + + A transcoded video source. + +- VIDEO_SOURCE_UNKNOWN + + An unknown video source. + +**Note** + +- VIDEO_SOURCE_CAMERA_PRIMARY and VIDEO_SOURCE_CAMERA are the same video source. +- VIDEO_SOURCE_SCREEN_PRIMARY and VIDEO_SOURCE_SCREEN are the same video source. + +**See also** + +- [enableDualStreamMode [2/3\]](../API/class_irtcengine.html#api_enabledualstreammode2) +- [enableDualStreamMode [3/3\]](../API/class_irtcengine.html#api_enabledualstreammode3) +- [setCameraDeviceOrientation](../API/class_irtcengine.html#api_setcameradeviceorientation) + +## [VOICE_BEAUTIFIER_PRESET](rtc_api_data_type.html#enum_voicebeautifierpreset) + +The options for SDK preset voice beautifier effects. + +### Enumerator + +- VOICE_BEAUTIFIER_OFF + + Turn off voice beautifier effects and use the original voice. + +- CHAT_BEAUTIFIER_MAGNETIC + + A more magnetic voice.**Note** Agora recommends using this enumerator to process a male-sounding voice; otherwise, you may experience vocal distortion. + +- CHAT_BEAUTIFIER_FRESH + + A fresher voice.**Note** Agora recommends using this enumerator to process a female-sounding voice; otherwise, you may experience vocal distortion. + +- CHAT_BEAUTIFIER_VITALITY + + A more vital voice.**Note** Agora recommends using this enumerator to process a female-sounding voice; otherwise, you may experience vocal distortion. + +- SINGING_BEAUTIFIER + + Singing beautifier effect.If you call [setVoiceBeautifierPreset](class_irtcengine.html#api_setvoicebeautifierpreset)(SINGING_BEAUTIFIER), you can beautify a male-sounding voice and add a reverberation effect that sounds like singing in a small room. Agora recommends using this enumerator to process a male-sounding voice; otherwise, you might experience vocal distortion.If you call [setVoiceBeautifierParameters](class_irtcengine.html#api_setvoicebeautifierparameters)(SINGING_BEAUTIFIER, param1, param2), you can beautify a male- or female-sounding voice and add a reverberation effect. + +- TIMBRE_TRANSFORMATION_VIGOROUS + + A more vigorous voice. + +- TIMBRE_TRANSFORMATION_DEEP + + A deep voice. + +- TIMBRE_TRANSFORMATION_MELLOW + + A mellower voice. + +- TIMBRE_TRANSFORMATION_FALSETTO + + Falsetto. + +- TIMBRE_TRANSFORMATION_FULL + + A fuller voice. + +- TIMBRE_TRANSFORMATION_CLEAR + + A clearer voice. + +- TIMBRE_TRANSFORMATION_RESOUNDING + + A more resounding voice. + +- TIMBRE_TRANSFORMATION_RINGING + + A more ringing voice. + +- ULTRA_HIGH_QUALITY_VOICE + + A ultra-high quality voice, which makes the audio clearer and restores more details.To achieve better audio effect quality, Agora recommends that you call [setAudioProfile [2/2\]](class_irtcengine.html#api_setaudioprofile2) and set the **profile** to AUDIO_PROFILE_MUSIC_HIGH_QUALITY (4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO (5) and **scenario** to AUDIO_SCENARIO_HIGH_DEFINITION (6) before calling [setVoiceBeautifierPreset](class_irtcengine.html#api_setvoicebeautifierpreset).If you have an audio capturing device that can already restore audio details to a high degree, Agora recommends that you do not enable ultra-high quality; otherwise, the SDK may over-restore audio details, and you may not hear the anticipated voice effect. + +**See also** + +- [setVoiceBeautifierPreset](../API/class_irtcengine.html#api_setvoicebeautifierpreset) + +## [VOICE_CHANGER_PRESET](rtc_api_data_type.html#enum_voicechangerpreset) + +Local voice changer options. + +- Deprecated + + Deprecated as of v3.2.0. + +### Enumerator + +- VOICE_CHANGER_OFF + + The original voice (no local voice change). + +- VOICE_CHANGER_OLDMAN + + The voice of an old man. + +- VOICE_CHANGER_BABYBOY + + The voice of a little boy. + +- VOICE_CHANGER_BABYGIRL + + The voice of a little girl. + +- VOICE_CHANGER_ZHUBAJIE + + The voice of Zhu Bajie, a character in Journey to the West who has a voice like that of a growling bear. + +- VOICE_CHANGER_ETHEREAL + + The ethereal voice. + +- VOICE_CHANGER_HULK + + The voice of Hulk. + +- VOICE_BEAUTY_VIGOROUS + + A more vigorous voice. + +- VOICE_BEAUTY_DEEP + + A deeper voice. + +- VOICE_BEAUTY_MELLOW + + A mellower voice. + +- VOICE_BEAUTY_FALSETTO + + Falsetto. + +- VOICE_BEAUTY_FULL + + A fuller voice. + +- VOICE_BEAUTY_CLEAR + + A clearer voice. + +- VOICE_BEAUTY_RESOUNDING + + A more resounding voice. + +- VOICE_BEAUTY_RINGING + + A more ringing voice. + +- VOICE_BEAUTY_SPACIAL + + A more spatially resonant voice. + +- GENERAL_BEAUTY_VOICE_MALE_MAGNETIC + + (For male only) A more magnetic voice. Do not use it when the speaker is a female; otherwise, voice distortion occurs. + +- GENERAL_BEAUTY_VOICE_FEMALE_FRESH + + (For female only) A fresher voice. Do not use it when the speaker is a male; otherwise, voice distortion occurs. + +- GENERAL_BEAUTY_VOICE_FEMALE_VITALITY + + (For female only) A more vital voice. Do not use it when the speaker is a male; otherwise, voice distortion occurs. + +**See also** + +- [setLocalVoiceChanger](../API/class_irtcengine.html#api_setlocalvoicechanger) + +## [VOICE_CONVERSION_PRESET](rtc_api_data_type.html#enum_voiceconversionpreset) + +The options for SDK preset voice conversion effects. + + + +### Enumerator + +- VOICE_CONVERSION_OFF + + Turn off voice conversion effects and use the original voice. + +- VOICE_CHANGER_NEUTRAL + + A gender-neutral voice. To avoid audio distortion, ensure that you use this enumerator to process a female-sounding voice. + +- VOICE_CHANGER_SWEET + + A sweet voice. To avoid audio distortion, ensure that you use this enumerator to process a female-sounding voice. + +- VOICE_CHANGER_SOLID + + A steady voice. To avoid audio distortion, ensure that you use this enumerator to process a male-sounding voice. + +- VOICE_CHANGER_BASS + + A deep voice. To avoid audio distortion, ensure that you use this enumerator to process a male-sounding voice. + +**See also** + +- [setVoiceConversionPreset](../API/class_irtcengine.html#api_setvoiceconversionpreset) + +## [AgoraRhythmPlayerConfig](rtc_api_data_type.html#class_agorarhythmplayerconfig) + +The metronome configuration. + +```cpp +struct AgoraRhythmPlayerConfig { + int beatsPerMeasure; + int beatsPerMinute; + + AgoraRhythmPlayerConfig() : beatsPerMeasure(4), beatsPerMinute(60) {} +}; +``` + + + +### Attributes + +- beatsPerMeasure + + The number of beats per measure, which ranges from 1 to 9. The default value is 4, which means that each measure contains one downbeat and three upbeats. + +- beatsPerMinute + + The beat speed (beats/minute), which ranges from 60 to 360. The default value is 60, which means that the metronome plays 60 beats in one minute. + +**See also** + +- [startRhythmPlayer](../API/class_irtcengine.html#api_startrhythmplayer) +- [configRhythmPlayer](../API/class_irtcengine.html#api_configrhythmplayer) + +## [AudioEncodedFrameObserverConfig](rtc_api_data_type.html#class_audioencodedframeobserverconfig) + +Observer settings for the encoded audio. + +```cpp +struct AudioEncodedFrameObserverConfig { + AUDIO_ENCODED_FRAME_OBSERVER_POSITION postionType; + AUDIO_ENCODING_TYPE encodingType; + AudioEncodedFrameObserverConfig() + : postionType(AUDIO_ENCODED_FRAME_OBSERVER_POSITION_PLAYBACK), + encodingType(AUDIO_ENCODING_TYPE_OPUS_48000_MEDIUM){} +}; +``` + +### Attributes + +- postionType + + Audio profile. For details, see [AUDIO_ENCODED_FRAME_OBSERVER_POSITION](rtc_api_data_type.html#enum_audioencodedframeobserverposition). + +- encodingType + + Audio encoding type. For details, see [AUDIO_ENCODING_TYPE](rtc_api_data_type.html#enum_audioencodingtype). + +**See also** + +- [registerAudioEncodedFrameObserver](../API/class_irtcengine.html#api_registeraudioencodedframeobserver) + +## [AudioRecordingConfiguration](rtc_api_data_type.html#class_audiorecordingconfiguration_ng) + +Recording configuration. + +```cpp +struct AudioRecordingConfiguration { + const char* filePath; + bool encode; + int sampleRate; + AUDIO_FILE_RECORDING_TYPE fileRecordingType; + AUDIO_RECORDING_QUALITY_TYPE quality; + + AudioRecordingConfiguration() + : filePath(NULL), + encode(false), + sampleRate(32000), + fileRecordingType(AUDIO_FILE_RECORDING_MIXED), + quality(AUDIO_RECORDING_QUALITY_LOW) {} + + AudioRecordingConfiguration(const char* file_path, int sample_rate, AUDIO_RECORDING_QUALITY_TYPE quality_type) + : filePath(file_path), + encode(false), + sampleRate(sample_rate), + fileRecordingType(AUDIO_FILE_RECORDING_MIXED), + quality(quality_type) {} + + AudioRecordingConfiguration(const char* file_path, bool enc, int sample_rate, AUDIO_FILE_RECORDING_TYPE type, AUDIO_RECORDING_QUALITY_TYPE quality_type) + : filePath(file_path), + encode(enc), + sampleRate(sample_rate), + fileRecordingType(type), + quality(quality_type) {} + + AudioRecordingConfiguration(const AudioRecordingConfiguration &rhs) + : filePath(rhs.filePath), + encode(rhs.encode), + sampleRate(rhs.sampleRate), + fileRecordingType(rhs.fileRecordingType), + quality(rhs.quality) {} +}; +``` + +### Attributes + +- filePath + + The absolute path (including the filename extensions) of the recording file. For example: `C:\music\audio.mp4`.**Note**Ensure that the directory for the log files exists and is writable. + +- encode + + Whether to encode the audio data:`true`: Encode audio data in AAC.`false`: (Default) Do not encode audio data, but save the recorded audio data directly. + +- sampleRate + + Recording sample rate (Hz).16000(Default) 320004410048000**Note**If you set this parameter to 44100 or 48000, Agora recommends recording WAV files, or AAC files with **quality** to be AUDIO_RECORDING_QUALITY_MEDIUM or AUDIO_RECORDING_QUALITY_HIGH for better recording quality. + +- fileRecordingType + + The recording content. See [AUDIO_RECORDING_POSITION](rtc_api_data_type.html#enum_audiorecordingposition). + +- quality + + Recording quality. See [AUDIO_RECORDING_QUALITY_TYPE](rtc_api_data_type.html#enum_audiorecordingqualitytype).**Note**Note: This parameter applies to AAC files only. + +**See also** + +- [startAudioRecording](../API/class_irtcengine.html#api_startaudiorecording3_ng) + +## [AudioSpectrumData](rtc_api_data_type.html#class_audiospectrumdata) + +The audio spectrum data. + +```cpp +struct AudioSpectrumData { + const float *audioSpectrumData; + int dataLength; + + AudioSpectrumData() : audioSpectrumData(NULL), dataLength(0) {} + AudioSpectrumData(const float *data, int length) : + audioSpectrumData(data), dataLength(length) {} +}; +``` + +### Attributes + +- AudioSpectrumData + + The audio spectrum data. Agora divides the audio frequency into 160 frequency domains, and reports the energy value of each frequency domain through this parameter. The value range of each energy type is [0, 1]. + +- dataLength + + The length of the audio spectrum data in byte. + +**See also** + +- [onLocalAudioSpectrum](../API/class_iaudiospectrumobserver.html#callback_iaudiospectrumobserver_onlocalaudiospectrum) + +## [AudioVolumeInfo](rtc_api_data_type.html#class_audiovolumeinfo) + +The volume information of users. + +```cpp +struct AudioVolumeInfo { + uid_t uid; + unsigned int volume; + unsigned int vad; + double voicePitch; + AudioVolumeInfo() : uid(0), volume(0), vad(0), voicePitch(0.0) {} + }; +``` + +### Attributes + +- uid + + The user ID.In the local user's callback, **uid** = 0.In the remote users' callback, **uid** is the user ID of a remote user whose instantaneous volume is one of the three highest. + +- volume + + The volume of the user. The value ranges between 0 (lowest volume) and 255 (highest volume). If the user calls [startAudioMixing [2/2\]](class_irtcengine.html#api_startaudiomixing2), the value of **volume** is the volume after audio mixing. + +- vad + + The voice activity status of the local user.0: The local user is not speaking.1: The local user is speaking.**Note**The **vad** parameter does not report the voice activity status of remote users. In the remote users' callback, the value of **vad** is always 0.To use this parameter, you must set **reportVad** to `true` when calling [enableAudioVolumeIndication](class_irtcengine.html#api_enableaudiovolumeindication). + +- voicePitch + + The voice pitch of the local user. The value ranges between 0.0 and 4000.0.**Note** The **voicePitch** parameter does not report the voice pitch of remote users. In the remote users' callback, the value of **voicePitch** is always 0. + +**See also** + +- [onAudioVolumeIndication](../API/class_irtcengineeventhandler.html#callback_onaudiovolumeindication) + +## [BeautyOptions](rtc_api_data_type.html#class_beautyoptions) + +Image enhancement options. + +```cpp +struct BeautyOptions { + enum LIGHTENING_CONTRAST_LEVEL { + LIGHTENING_CONTRAST_LOW = 0, + LIGHTENING_CONTRAST_NORMAL, + LIGHTENING_CONTRAST_HIGH + }; + LIGHTENING_CONTRAST_LEVEL lighteningContrastLevel; + float lighteningLevel; + float smoothnessLevel; + float rednessLevel; + float sharpnessLevel; + BeautyOptions(LIGHTENING_CONTRAST_LEVEL contrastLevel, float lightening, float smoothness, float redness, float sharpness) : lighteningContrastLevel(contrastLevel), lighteningLevel(lightening), smoothnessLevel(smoothness), rednessLevel(redness), sharpnessLevel(sharpness) {} + BeautyOptions() : lighteningContrastLevel(LIGHTENING_CONTRAST_NORMAL), lighteningLevel(0), smoothnessLevel(0), rednessLevel(0), sharpnessLevel(0) {} +}; +``` + +### Attributes + +- lighteningContrastLevel + + The contrast level. For details, see [LIGHTENING_CONTRAST_LEVEL](rtc_api_data_type.html#enum_lighteningcontrastlevel). + +- lighteningLevel + + The brightness level. The value ranges from 0.0 (original) to 1.0. The default value is 0.0. This parameter makes video whitening. + +- smoothnessLevel + + The smoothness level. The value ranges from 0.0 (original) to 1.0. The default value is 0.0. This parameter is usually used to remove blemishes. + +- rednessLevel + + The redness level. The value ranges from 0.0 (original) to 1.0. The default value is 0.0. This parameter adjusts the red saturation level. + +- sharpnessLevel + + The sharpness level. The value ranges from 0.0 (original) to 1.0. The default value is 0.0. + +**See also** + +- [setBeautyEffectOptions](../API/class_irtcengine.html#api_setbeautyeffectoptions) + +## [CameraCapturerConfiguration](rtc_api_data_type.html#class_cameracapturerconfiguration_ng) + +The camera capturer preference. + +```cpp +struct CameraCapturerConfiguration { + CAMERA_DIRECTION cameraDirection; + char deviceId[MAX_DEVICE_ID_LENGTH]; + VideoFormat format; +}; +``` + +### Attributes + +- cameraDirection + + **Note** This parameter applies to Android and iOS only.The camera direction. For details, see [CAMERA_DIRECTION](rtc_api_data_type.html#enum_cameradirection). + +- format + + For details, see [VideoFormat](rtc_api_data_type.html#class_videoformat_ng). + +- deviceId + + The device ID of the playback device. The maximum length is [MAX_DEVICE_ID_LENGTH_TYPE](rtc_api_data_type.html#enum_maxdeviceidlengthtype). + +**See also** + +- [setCameraCapturerConfiguration](../API/class_irtcengine.html#api_setcameracapturerconfiguration) +- [startPrimaryCameraCapture](../API/class_irtcengine.html#api_startprimarycameracapture) +- [startSecondaryCameraCapture](../API/class_irtcengine.html#api_startsecondarycameracapture) + +## [ChannelMediaInfo](rtc_api_data_type.html#class_channelmediainfo) + +The definition of ChannelMediaInfo. + +```cpp +struct ChannelMediaInfo { + const char* channelName; + const char* token; + uid_t uid; + }; +``` + +### Attributes + +- channelName + + The name of the channel. + +- token + + The token that enables the user to join the channel. + +- uid + + User ID. + +**See also** + +- [startChannelMediaRelay](../API/class_irtcengine.html#api_startchannelmediarelay) +- [updateChannelMediaRelay](../API/class_irtcengine.html#api_updatechannelmediarelay) + +## [ChannelMediaOptions](rtc_api_data_type.html#class_channelmediaoptions_ng) + +The channel media options. + +```cpp +struct ChannelMediaOptions { + Optional publishCameraTrack; + Optional publishSecondaryCameraTrack; + Optional publishAudioTrack; + Optional publishScreenTrack; + Optional publishSecondaryScreenTrack; + Optional publishCustomAudioTrack; + Optional publishCustomAudioTrackEnableAec; + Optional publishCustomVideoTrack; + Optional publishEncodedVideoTrack; + Optional publishMediaPlayerAudioTrack; + Optional publishMediaPlayerVideoTrack; + Optional publishTrancodedVideoTrack; + Optional publishCustomAudioSourceId; + Optional autoSubscribeAudio; + Optional autoSubscribeVideo; + Optional enableAudioRecordingOrPlayout; + Optional publishMediaPlayerId; + Optional clientRoleType; + Optional defaultVideoStreamType; + Optional channelProfile; + Optional audioDelayMs; + Optional token; + ChannelMediaOptions() {} + ~ChannelMediaOptions() {} +``` + +### Attributes + +- publishCameraTrack + + Whether to publish the video captured by the camera:`true`: Publish the video captured by the camera.`false`: Do not publish the video captured by the camera. + +- publishSecondaryCameraTrack + + Whether to publish the video captured by the camera:`true`: Publish the video captured by the second camera.`false`: Do not publish the video captured by the second camera. + +- publishAudioTrack + + Whether to publish the captured audio:`true`: Publish the captured audio.`false`: Do not publish the captured audio. + +- publishScreenTrack + + Whether to publish the captured video from the screen:`true`: Publish the captured video from the screen.`false`: Do not publish the captured video from the screen. + +- publishSecondaryScreenTrack + + Whether to publish the captured video from the second screen:`true`: Publish the captured video from the second screen.`false`: Do not publish the captured video from the second screen. + +- publishTrancodedVideoTrack + + Whether to publish the local transcoded video.`true: Publish the local transcoded video.``false: Do not publish the local transcoded video.` + +- publishCustomAudioTrack + + Whether to publish the captured audio from a custom source:`true`: Publish the captured audio from a custom source.`false`: Do not publish the captured audio from a custom source. + +- publishCustomAudioSourceId + + The ID of the custom audio source to publish. The default value is 0.If you have set the value of **sourceNumber** greater than 1 in [setExternalAudioSource](class_imediaengine.html#api_setexternalaudiosource2), the SDK creates the corresponding number of custom audio tracks and assigns an ID to each audio track starting from 0. + +- publishCustomAudioTrackEnableAec + + Whether to enable AEC when publishing the captured audio from a custom source:`true`: Enable AEC when publishing the captured audio from a custom source.`false`: Do not enable AEC when publishing the captured audio from a custom source. + +- publishCustomVideoTrack + + Whether to publish the captured video from a custom source:`true`: Publish the captured video from a custom source.`false`: Do not publish the captured video from a custom source. + +- publishEncodedVideoTrack + + Whether to publish the encoded video:`true`: Publish the encoded video.`false`: Do not publish the encoded video. + +- publishMediaPlayerAudioTrack + + Whether to publish the audio from the media player:`true`: Publish the audio from the media player.`false`: Do not publish the audio from the media player. + +- publishMediaPlayerVideoTrack + + Whether to publish the video from the media player:`true`: Publish the video from the media player.`false`: Do not publish the video from the media player. + +- autoSubscribeAudio + + Whether to automatically subscribe to all remote audio streams when the user joins a channel:`true`: Subscribe to all remote audio streams.`false`: Do not subscribe to any remote audio stream. + +- autoSubscribeVideo + + Whether to subscribe to all remote video streams when the user joins the channel:`true`: Subscribe to all remote video streams.`false`: Do not subscribe to any remote video stream. + +- enableAudioRecordingOrPlayout + + Whether to enable audio capturing or playback.`true`: Enable audio capturing and playback.`false`: Do not enable audio capturing or playback. + +- publishMediaPlayerId + + The ID of the media player to be published. The default value is 0. + +- clientRoleType + + The user role. For details, see [CLIENT_ROLE_TYPE](rtc_api_data_type.html#enum_clientroletype). + +- defaultVideoStreamType + + The default stream type of the remote video, see [REMOTE_VIDEO_STREAM_TYPE](rtc_api_data_type.html#enum_remotevideostreamtype). + +- channelProfile + + The channel profile. For details, see [CHANNEL_PROFILE_TYPE](rtc_api_data_type.html#enum_channelprofiletype_ng). + +- audioDelayMs + + The delay in ms for sending audio frames. This is used for explicit control of A/V sync.To switch off the delay, set the value to 0. + +- token + + (Optional) The token generated on your server for authentication. See [Authenticate Your Users with Token](https://docs.agora.io/en/live-streaming-4.x-preview/token_server_android_ng?platform=Windows).**警告：**This parameter takes effect only when calling [updateChannelMediaOptions](class_irtcengine.html#api_updatechannelmediaoptions) or [updateChannelMediaOptionsEx](class_irtcengineex.html#api_irtcengineex_updatechannelmediaoptionsex).Ensure that the App ID, channel name, and user name used for creating the token are the same ones as those used by the [initialize](class_irtcengine.html#api_create2) method for initializing the RTC engine, and those used by the [joinChannel [2/2\]](class_irtcengine.html#api_joinchannel2_ng) and [joinChannelEx](class_irtcengineex.html#api_irtcengineex_joinchannelex) methods for joining the channel. + +**See also** + +- [joinChannel [2/2\]](../API/class_irtcengine.html#api_joinchannel2_ng) +- [joinChannelWithUserAccount [2/2\]](../API/class_irtcengine.html#api_joinchannelwithuseraccount2) +- [joinChannelWithUserAccountEx](../API/class_irtcengineex.html#api_irtcengineex_joinchannelwithuseraccountex) +- [joinChannelEx](../API/class_irtcengineex.html#api_irtcengineex_joinchannelex) +- [updateChannelMediaOptions](../API/class_irtcengine.html#api_updatechannelmediaoptions) +- [updateChannelMediaOptionsEx](../API/class_irtcengineex.html#api_irtcengineex_updatechannelmediaoptionsex) + +## [ChannelMediaRelayConfiguration](rtc_api_data_type.html#class_channelmediarelayconfiguration) + +The definition of ChannelMediaRelayConfiguration. + +```cpp +struct ChannelMediaRelayConfiguration { + ChannelMediaInfo *srcInfo; + ChannelMediaInfo *destInfos; + int destCount; + + ChannelMediaRelayConfiguration() + : srcInfo(nullptr) + , destInfos(nullptr) + , destCount(0) + {} + }; +``` + +### Attributes + +- srcInfo + + The information of the source channel [ChannelMediaInfo](rtc_api_data_type.html#class_channelmediainfo). It contains the following members:channelName: The name of the source channel. The default value is , which means the SDK applies the name of the current channel.```NULL``uid`: The unique ID to identify the relay stream in the source channel. The default value is 0, which means the SDK generates a random `UID`. You must set it as 0.`token`: The token for joining the source channel``. It is generated with the `channelName` and `uid` you set in `srcInfo`.If you have not enabled the App Certificate, set this parameter as the default value `NULL` , which means the SDK applies the App ID.If you have enabled the App Certificate, you must use the `token` generated with the `channelName` and `uid`, and the `uid` must be set as 0. + +- destInfos + + The information of the destination channel ChannelMediaInfo. It contains the following members:`channelName`: The name of the destination channel.`uid`: The unique ID to identify the relay stream in the destination channel. The value ranges from 0 to (232-1). To avoid UID conflicts, this `UID` must be different from any other `UID` in the destination channel. The default value is 0, which means the SDK generates a random `UID`. Do not set this parameter as the `UID` of the host in the destination channel, and ensure that this `UID` is different from any other `UID` in the channel.`token`: The `token` for joining the destination channel. It is generated with the `channelName` and `uid` you set in `destInfos`.If you have not enabled the App Certificate, set this parameter as the default value `NULL` , which means the SDK applies the App ID.If you have enabled the App Certificate, you must use the `token` generated with the `channelName` and `uid`. + +- destCount + + The number of destination channels. The default value is 0, and the value range is from 0 to 4. Ensure that the value of this parameter corresponds to the number of ChannelMediaInfo structs you define in `destInfo`. + +**See also** + +- [startChannelMediaRelay](../API/class_irtcengine.html#api_startchannelmediarelay) +- [updateChannelMediaRelay](../API/class_irtcengine.html#api_updatechannelmediarelay) + +## [ClientRoleOptions](rtc_api_data_type.html#class_clientroleoptions) + +The detailed options of a user. + + + +```cpp +struct ClientRoleOptions { + AUDIENCE_LATENCY_LEVEL_TYPE audienceLatencyLevel; + ClientRoleOptions() + : audienceLatencyLevel(AUDIENCE_LATENCY_LEVEL_ULTRA_LOW_LATENCY) {} + }; +``` + +### Attributes + +- audienceLatencyLevel + + The latency level of an audience member in interactive live streaming. See [AUDIENCE_LATENCY_LEVEL_TYPE](rtc_api_data_type.html#enum_audiencelatencyleveltype). + +**See also** + +- [setClientRole [2/2\]](../API/class_irtcengine.html#api_setclientrole2) + +## [DataStreamConfig](rtc_api_data_type.html#class_datastreamconfig) + +The configurations for the data stream. + +```cpp +struct DataStreamConfig { + bool syncWithAudio; + bool ordered; + }; +``` + +The following table shows the SDK behaviors under different parameter settings: + +| `syncWithAudio` | `ordered` | SDK behaviors | +| --------------- | --------- | ------------------------------------------------------------ | +| `false` | `false` | The SDK triggers the [onStreamMessage](class_irtcengineeventhandler.html#callback_onstreammessage) callback immediately after the receiver receives a data packet. | +| `true` | `false` | If the data packet delay is within the audio delay, the SDK triggers the [onStreamMessage](class_irtcengineeventhandler.html#callback_onstreammessage) callback when the synchronized audio packet is played out. If the data packet delay exceeds the audio delay, the SDK triggers the [onStreamMessage](class_irtcengineeventhandler.html#callback_onstreammessage) callback as soon as the data packet is received. | +| `false` | `true` | If the delay of a data packet is less than five seconds, the SDK corrects the order of the data packet. If the delay of a data packet exceeds five seconds, the SDK discards the data packet. | +| `true` | `true` | If the delay of the data packet is within the range of the audio delay, the SDK corrects the order of the data packet. If the delay of a data packet exceeds the audio delay, the SDK discards this data packet. | + +### Attributes + +- syncWithAudio + + Whether to synchronize the data packet with the published audio packet.`true`: Synchronize the data packet with the audio packet.`false`: Do not synchronize the data packet with the audio packet.When you set the data packet to synchronize with the audio, then if the data packet delay is within the audio delay, the SDK triggers the [onStreamMessage](class_irtcengineeventhandler.html#callback_onstreammessage) callback when the synchronized audio packet is played out. Do not set this parameter as true if you need the receiver to receive the data packet immediately. Agora recommends that you set this parameter to `true` only when you need to implement specific functions, for example lyric synchronization. + +- ordered + + Whether the SDK guarantees that the receiver receives the data in the sent order.`true`: Guarantee that the receiver receives the data in the sent order.`false`: Do not guarantee that the receiver receives the data in the sent order.Do not set this parameter as `true` if you need the receiver to receive the data packet immediately. + +**See also** + +- [createDataStream [2/2\]](../API/class_irtcengine.html#api_createdatastream2) +- [createDataStreamEx [2/2\]](../API/class_irtcengineex.html#api_irtcengineex_createdatastreamex2) + +## [DeviceInfo](rtc_api_data_type.html#class_deviceinfo) + +The audio device information. + +```cpp +struct DeviceInfo { + bool isLowLatencyAudioSupported; + + DeviceInfo() : isLowLatencyAudioSupported(false) {} +}; +``` + +**Note** This class is for Android only. + +### Attributes + +- isLowLatencyAudioSupported + + Whether the audio device supports ultra-low-latency capture and playback:`true`: The device supports ultra-low-latency capture and playback.`false`: The device does not support ultra-low-latency capture and playback. + +## [EncodedAudioFrameInfo](rtc_api_data_type.html#class_encodedaudioframeinfo) + +Audio information after encoding. + +```cpp +struct EncodedAudioFrameInfo { + EncodedAudioFrameInfo() + : codec(AUDIO_CODEC_AACLC), + sampleRateHz(0), + samplesPerChannel(0), + numberOfChannels(0) {} + EncodedAudioFrameInfo(const EncodedAudioFrameInfo& rhs) + : codec(rhs.codec), + sampleRateHz(rhs.sampleRateHz), + samplesPerChannel(rhs.samplesPerChannel), + numberOfChannels(rhs.numberOfChannels), + advancedSettings(rhs.advancedSettings) {} + AUDIO_CODEC_TYPE codec; + int sampleRateHz; + int samplesPerChannel; + int numberOfChannels; + EncodedAudioFrameAdvancedSettings advancedSettings; +}; +``` + +### Attributes + +- codec + + Audio Codec type:[AUDIO_CODEC_TYPE](rtc_api_data_type.html#enum_audiocodectype) + +- sampleRateHz + + Audio sample rate (Hz). + +- samplesPerChannel + + The number of audio samples per channel. + +- numberOfChannels: + + The number of audio channels. + +- advancedSettings + + This function is currently not supported. + +**See also** + +- [OnPlaybackAudioEncodedFrame](../API/class_iaudioencodedframeobserver.html#callback_iaudioencodedframeobserver_onplaybackaudioencodedframe) +- [OnRecordAudioEncodedFrame](../API/class_iaudioencodedframeobserver.html#callback_iaudioencodedframeobserver_onrecordaudioencodedframe) +- [OnMixedAudioEncodedFrame](../API/class_iaudioencodedframeobserver.html#callback_iaudioencodedframeobserver_onmixedaudioencodedframe) + +## [EncodedVideoFrameInfo](rtc_api_data_type.html#class_encodedvideoframeinfo) + +Information about externally encoded video frames. + +```cpp +struct EncodedVideoFrameInfo { + EncodedVideoFrameInfo() + : codecType(VIDEO_CODEC_H264), + width(0), + height(0), + framesPerSecond(0), + frameType(VIDEO_FRAME_TYPE_BLANK_FRAME), + rotation(VIDEO_ORIENTATION_0), + trackId(0), + renderTimeMs(0), + uid(0), + streamType(VIDEO_STREAM_HIGH) {} + EncodedVideoFrameInfo(const EncodedVideoFrameInfo& rhs) + : codecType(rhs.codecType), + width(rhs.width), + height(rhs.height), + framesPerSecond(rhs.framesPerSecond), + frameType(rhs.frameType), + rotation(rhs.rotation), + trackId(rhs.trackId), + renderTimeMs(rhs.renderTimeMs), + uid(rhs.uid), + streamType(rhs.streamType) {} + VIDEO_CODEC_TYPE codecType; + int width; + int height; + int framesPerSecond; + VIDEO_FRAME_TYPE frameType; + VIDEO_ORIENTATION rotation; + int trackId; + int64_t renderTimeMs; + uid_t uid; + VIDEO_STREAM_TYPE streamType; + }; + +``` + +### Attributes + +- codecType + + The codec type of the local video stream. See [VIDEO_CODEC_TYPE](rtc_api_data_type.html#enum_videocodectype). The default value is `VIDEO_CODEC_H264 (2)`. + +- width + + Width (pixel) of the video frame. + +- height + + Height (pixel) of the video frame. + +- framesPerSecond + + The number of video frames per second.When this parameter is not `0`, you can use it to calculate the Unix timestamp of externally encoded video frames. + +- frameType + + The video frame type, see [VIDEO_FRAME_TYPE](rtc_api_data_type.html#enum_videoframetype_ng). + +- rotation + + The rotation information of the video frame, see [VIDEO_ORIENTATION](rtc_api_data_type.html#enum_videoorientation). + +- trackId + + Reserved for future use. + + The track ID. Used in scenarios with multiple video tracks in the channel. + +- renderTimeMs + + The Unix timestamp (ms) for rendering externally encoded video frames. + +- uid + + The user ID to push the externally encoded video frame. + +- streamType + + The type of video streams. + +**See also** + +- [pushEncodedVideoImage [1/2\]](../API/class_imediaengine.html#api_imediaengine_pushencodedvideoimage) +- [OnEncodedVideoImageReceived](../API/class_ivideoencodedimagereceiver.html#callback_ivideoencodedimagereceiver_onencodedvideoimagereceived) + +## [EncryptionConfig](rtc_api_data_type.html#class_encryptionconfig) + +Built-in encryption configurations. + +```cpp +struct EncryptionConfig { + ENCRYPTION_MODE encryptionMode; + const char* encryptionKey; + uint8_t encryptionKdfSalt[32]; + + EncryptionConfig() + : encryptionMode(AES_128_GCM2), + encryptionKey(NULL) + { + memset(encryptionKdfSalt, 0, sizeof(encryptionKdfSalt)); + } + + const char* getEncryptionString() const { + switch(encryptionMode) { + case AES_128_XTS: + return "aes-128-xts"; + case AES_128_ECB: + return "aes-128-ecb"; + case AES_256_XTS: + return "aes-256-xts"; + case SM4_128_ECB: + return "sm4-128-ecb"; + case AES_128_GCM: + return "aes-128-gcm"; + case AES_256_GCM: + return "aes-256-gcm"; + case AES_128_GCM2: + return "aes-128-gcm-2"; + case AES_256_GCM2: + return "aes-256-gcm-2"; + default: + return "aes-128-gcm-2"; + } + return "aes-128-gcm-2"; + } +}; +``` + + + +### Attributes + +- encryptionMode + + The built-in encryption mode. See [ENCRYPTION_MODE](rtc_api_data_type.html#enum_encryptionmode). Agora recommends using `AES_128_GCM2` or `AES_256_GCM2` encrypted mode. These two modes support the use of salt for higher security. + +- encryptionKey + + Encryption key in string type.**Note** If you do not set an encryption key or set it as `NULL`, you cannot use the built-in encryption, and the SDK returns `-2`. + +- encryptionKdfSalt + + Salt, 32 bytes in length. Agora recommends that you use OpenSSL to generate salt on the server side. See Media Stream Encryption for details.**Note** This parameter takes effect only in `AES_128_GCM2` or `AES_256_GCM2` encrypted mode. In this case, ensure that this parameter is not `0`. + +**See also** + +- [enableEncryption](../API/class_irtcengine.html#api_enableencryption) + +## [ExternalVideoFrame](rtc_api_data_type.html#class_externalvideoframe_ng) + +The external video frame. + +```cpp +struct ExternalVideoFrame { + ExternalVideoFrame() + : type(VIDEO_BUFFER_RAW_DATA), + format(VIDEO_PIXEL_UNKNOWN), + buffer(NULL), + stride(0), + height(0), + cropLeft(0), + cropTop(0), + cropRight(0), + cropBottom(0), + rotation(0), + timestamp(0), + eglContext(NULL), + eglType(EGL_CONTEXT10), + textureId(0), + metadata_buffer(NULL), + metadata_size(0){} + enum EGL_CONTEXT_TYPE { + EGL_CONTEXT10 = 0, + EGL_CONTEXT14 = 1, + }; + enum VIDEO_BUFFER_TYPE { + VIDEO_BUFFER_RAW_DATA = 1, + VIDEO_BUFFER_ARRAY = 2, + VIDEO_BUFFER_TEXTURE = 3, + }; + VIDEO_BUFFER_TYPE type; + VIDEO_PIXEL_FORMAT format; + void* buffer; + int stride; + int height; + int cropLeft; + int cropTop; + int cropRight; + int cropBottom; + int rotation; + long long timestamp; + void *eglContext; + EGL_CONTEXT_TYPE eglType; + int textureId; + uint8_t* metadata_buffer; + int metadata_size; + }; +``` + +### Attributes + +- type + + The video buffer type. For details, see [VIDEO_BUFFER_TYPE](rtc_api_data_type.html#enum_videobuffertype). + +- format + + The pixel format. For details, see [VIDEO_PIXEL_FORMAT](rtc_api_data_type.html#enum_videopixelformat). + +- buffer + + Video frame buffer. + +- stride + + Line spacing of the incoming video frame, which must be in pixels instead of bytes. For textures, it is the width of the texture. + +- height + + Height of the incoming video frame. + +- eglContext + + This parameter only applies to video data in Texture format.When using the OpenGL interface (javax.microedition.khronos.egl.*) defined by Khronos, set eglContext to this field.When using the OpenGL interface (android.opengl.*) defined by Android, set eglContext to this field. + +- eglType + + This parameter only applies to video data in Texture format. Texture ID of the frame. + +- textureId + + This parameter only applies to video data in Texture format. Incoming 4 x 4 transformational matrix. The typical value is a unit matrix. + +- metadata_buffer + + This parameter only applies to video data in Texture format. The MetaData buffer. The default value is `NULL`. + +- metadata_size + + This parameter only applies to video data in Texture format. The MetaData size. The default value is `0`. + +- cropLeft + + Raw data related parameter. The number of pixels trimmed from the left. The default value is 0. + + This parameter only applies to raw video data. + +- cropTop + + Raw data related parameter. The number of pixels trimmed from the top. The default value is 0. + + This parameter only applies to raw video data. + +- cropRight + + Raw data related parameter. The number of pixels trimmed from the right. The default value is 0. + + This parameter only applies to raw video data. + +- cropBottom + + Raw data related parameter. The number of pixels trimmed from the bottom. The default value is 0. + + This parameter only applies to raw video data. + +- rotation + + Raw data related parameter. The clockwise rotation of the video frame. You can set the rotation angle as 0, 90, 180, or 270. The default value is 0. + +- timestamp + + Timestamp (ms) of the incoming video frame. An incorrect timestamp results in frame loss or unsynchronized audio and video. + +**See also** + +- [pushVideoFrame [1/2\]](../API/class_imediaengine.html#api_imediaengine_pushvideoframe) +- [pushVideoFrame [2/2\]](../API/class_imediaengine.html#api_irtcengineex_pushvideoframeex) + +## [LastmileProbeConfig](rtc_api_data_type.html#class_lastmileprobeconfig) + +Configurations of the last-mile network test. + +```cpp +struct LastmileProbeConfig { + bool probeUplink; + bool probeDownlink; + unsigned int expectedUplinkBitrate; + unsigned int expectedDownlinkBitrate; + }; +``` + +### Attributes + +- probeUplink + + Sets whether to test the uplink network. Some users, for example, the audience members in a LIVE_BROADCASTING channel, do not need such a test.`true`: Test.`false`: Not test. + +- probeDownlink + + Sets whether to test the downlink network:`true`: Test.`false`: Not test. + +- expectedUplinkBitrate + + The expected maximum uplink bitrate (bps) of the local user. The value range is [100000, 5000000]. Agora recommends referring to [setVideoEncoderConfiguration](class_irtcengine.html#api_setvideoencoderconfiguration) to set the value. + +- expectedDownlinkBitrate + + The expected maximum downlink bitrate (bps) of the local user. The value range is [100000,5000000]. + +**See also** + +- [startLastmileProbeTest](../API/class_irtcengine.html#api_startlastmileprobetest) + +## [LastmileProbeOneWayResult](rtc_api_data_type.html#class_lastmileprobeonewayresult) + +Results of the uplink or downlink last-mile network test. + +```cpp +struct LastmileProbeOneWayResult { + unsigned int packetLossRate; + unsigned int jitter; + unsigned int availableBandwidth; + + LastmileProbeOneWayResult() : packetLossRate(0), + jitter(0), + availableBandwidth(0) {} + }; +struct LastmileProbeOneWayResult { + unsigned int packetLossRate; + unsigned int jitter; + unsigned int availableBandwidth; + }; +``` + +### Attributes + +- packetLossRate + + The packet loss rate (%). + +- jitter + + The network jitter (ms). + +- availableBandwidth + + The estimated available bandwidth (bps). + +**See also** + +- [onLastmileProbeResult](../API/class_irtcengineeventhandler.html#callback_onlastmileproberesult) + +## [LastmileProbeResult](rtc_api_data_type.html#class_lastmileproberesult) + +Results of the uplink and downlink last-mile network tests. + +```cpp +struct LastmileProbeResult { + LASTMILE_PROBE_RESULT_STATE state; + LastmileProbeOneWayResult uplinkReport; + LastmileProbeOneWayResult downlinkReport; + unsigned int rtt; + + LastmileProbeResult() : state(LASTMILE_PROBE_RESULT_UNAVAILABLE), + rtt(0) {} + }; +``` + + + +### Attributes + +- state + + The status of the last-mile network tests. See [LASTMILE_PROBE_RESULT_STATE](rtc_api_data_type.html#enum_lastmileproberesultstate). + +- uplinkReport + + Results of the uplink last-mile network test. For details, see [LastmileProbeOneWayResult](rtc_api_data_type.html#class_lastmileprobeonewayresult). + +- downlinkReport + + Results of the downlink last-mile network test. For details, see [LastmileProbeOneWayResult](rtc_api_data_type.html#class_lastmileprobeonewayresult). + +- rtt + + The round-trip time (ms). + +**See also** + +- [onLastmileProbeResult](../API/class_irtcengineeventhandler.html#callback_onlastmileproberesult) + +## [LeaveChannelOptions](rtc_api_data_type.html#class_leavechanneloptions) + +The options for leaving a channel. + +```cpp +struct LeaveChannelOptions { + bool stopAudioMixing; + bool stopAllEffect; + bool stopMicrophoneRecording; + LeaveChannelOptions() : stopAudioMixing(true), stopAllEffect(true), stopMicrophoneRecording(true) {} +}; +``` + +### Attributes + +- stopAudioMixing + + Whether to stop playing and mixing the music file when a user leaves the channel.`true`: (Default) Stop playing and mixing the music file.`false`: Do not stop playing and mixing the music file. + +- stopAllEffect + + Whether to stop playing all audio effects when a user leaves the channel.`true`: (Default) Stop playing all audio effects.`false`: Do not stop playing any audio effect. + +- stopMicrophoneRecording + + Whether to stop microphone recording when a user leaves the channel.`true`: (Default) Stop microphone recording.`false`: Do not stop microphone recording. + +**See also** + +- [leaveChannel [2/2\]](../API/class_irtcengine.html#api_leavechannel2) + +## [LiveTranscoding](rtc_api_data_type.html#class_livetranscoding) + +Transcoding configurations for CDN live streaming. + +```cpp +struct LiveTranscoding { + int width; + int height; + int videoBitrate; + int videoFramerate; + bool lowLatency; + int videoGop; + VIDEO_CODEC_PROFILE_TYPE videoCodecProfile; + unsigned int backgroundColor; + unsigned int userCount; + TranscodingUser* transcodingUsers; + const char* transcodingExtraInfo; + const char* metadata; + RtcImage* watermark; + unsigned int watermarkCount; + RtcImage* backgroundImage; + unsigned int backgroundImageCount; + AUDIO_SAMPLE_RATE_TYPE audioSampleRate; + int audioBitrate; + int audioChannels; + AUDIO_CODEC_PROFILE_TYPE audioCodecProfile; + + LiveTranscoding() + : width(360), + height(640), + videoBitrate(400), + videoFramerate(15), + lowLatency(false), + videoGop(30), + videoCodecProfile(VIDEO_CODEC_PROFILE_HIGH), + backgroundColor(0x000000), + userCount(0), + transcodingUsers(NULL), + transcodingExtraInfo(NULL), + metadata(NULL), + watermark(NULL), + watermarkCount(0), + backgroundImage(NULL), + backgroundImageCount(0), + audioSampleRate(AUDIO_SAMPLE_RATE_48000), + audioBitrate(48), + audioChannels(1), + audioCodecProfile(AUDIO_CODEC_PROFILE_LC_AAC) {} +}; +``` + +### Attributes + +- width + + The width of the output media stream in pixels. The default value is 360.When the output media stream is video, ensure that `width` is set to 64 or higher. Otherwise, the Agora server adjusts the value to 64.When the output media stream is audio, set `width` to 0. + +- height + + The height of the output media stream in pixels. The default value is 640.When the output media stream is video, ensure that `height` is set to 64 or higher. Otherwise, the Agora server adjusts the value to 64.When the output media stream is audio, set `height` to 0. + +- videoBitrate + + The video bitrate (Kbps) of the output media stream. The default value is 400. You can refer to [Push Streams to CND](https://docs.agora.io/en/live-streaming-4.x-preview/cdn_streaming_windows?platform=Windows) for how to set the parameters. + +- videoFrameRate + + The video frame rate (fps) of the output media stream. The default value is 15, and the value range is [1, 30].**Note** The Agora server adjusts any frame rate higher than 30 fps to 30 fps. + +- lowLatency + + DeprecatedThis attribute is deprecated since v2.8.0, and Agora does not recommend it.`true`: Low latency with unassured quality.`false`: (Default) High latency with assured quality. + +- videoGop + + The video GOP (Group of Pictures) of the output media stream. The default value is 30. + +- videoCodecProfile + + The video encoding configuration of the output media stream. See [VIDEO_CODEC_PROFILE_TYPE](rtc_api_data_type.html#enum_videocodecprofiletype).**Note** If you set this parameter to any other value, Agora adjusts it to the default value. + +- transcodingUsers + + Transcoding configurations of each host. One live streaming channel supports up to 17 hosts. For details, see [TranscodingUser](rtc_api_data_type.html#class_transcodinguser). + +- transcodingExtraInfo + + The user SEI information embedded in the output media stream. This parameter is used to send SEI information to the CDN. The maximum length is 4096 bytes. See [How to solve SEI-related issues](https://docs.agora.io/en/faq/sei). + +- backgroundColor + + The video background color of the output media stream. The format is a hexadecimal integer defined by RGB without the # symbol. For example, `0xFFB6C1` means light pink. The default value is `0x000000 `(black). + +- userCount + + The number of hosts in the transcoding. The default value is 0. + +- metadata + + Deprecated:This attribute is deprecated.The metadata sent to the CDN client. + +- watermark + + The video watermark of the output media stream. Ensure that the format of the watermark image is PNG. For details, see [RtcImage](rtc_api_data_type.html#class_rtcimage). + +- backgroundImage + + The video background image of the output media stream. For details, see [RtcImage](rtc_api_data_type.html#class_rtcimage). + +- audioSampleRate + + The audio sampling rate (Hz) of the output media stream. See [AUDIO_SAMPLE_RATE_TYPE](rtc_api_data_type.html#enum_audiosampleratetype). + +- audioBitrate + + The audio bitrate (Kbps) of the output media stream. The default value is 48, and the maximum is 128. + +- audioChannels + + The number of audio channels of the output media stream. The default value is 1. Agora recommends setting it to 1 or 2.1: (Default) Mono2: Stereo.3: Three audio channels.4: Four audio channels.5: Five audio channels. + +- audioCodecProfile + + The audio codec of the output media stream. For details, see [AUDIO_CODEC_PROFILE_TYPE](rtc_api_data_type.html#enum_audiocodecprofiletype). + +- watermarkCount + + The number of watermarks of the output media stream.If you do not add a watermark or add only one watermark, this parameter is optional.If you add more than one watermarks, ensure that you set this parameter. + +- backgroundCount + + The number of background images of the output media stream.If you do not add a background image or add only one background image, this parameter is optional.If you add more than one background images, ensure that you set this parameter. + +**See also** + +- [setLiveTranscoding](../API/class_irtcengine.html#api_setlivetranscoding) + +## [LocalAudioStats](rtc_api_data_type.html#class_localaudiostats) + +Local audio statistics. + +```cpp +struct LocalAudioStats +{ + int numChannels; + int sentSampleRate; + int sentBitrate; + int internalCodec; + int txPacketLossRate; +}; +``` + +### Attributes + +- numChannels + + The number of audio channels. + +- sentSampleRate + + The sampling rate (Hz) of sending the local user's audio stream. + +- sentBitrate + + The average bitrate (Kbps) of sending the local user's audio stream. + +- txPacketLossRate + + The packet loss rate (%) from the local client to the Agora server before applying the anti-packet loss strategies. + +- internalCodec + + The internal payload codec. + +**See also** + +- [onLocalAudioStats](../API/class_irtcengineeventhandler.html#callback_onlocalaudiostats) + +## [LocalTranscoderConfiguration](rtc_api_data_type.html#class_localtranscoderconfiguration) + +The configuration of the video mixing on the local client. + +```cpp +struct LocalTranscoderConfiguration { + unsigned int streamCount; + TranscodingVideoStream* VideoInputStreams; + VideoEncoderConfiguration videoOutputConfiguration; + LocalTranscoderConfiguration() + : streamCount(0), + VideoInputStreams(NULL), + videoOutputConfiguration() {} +}; +``` + +### Attributes + +- streamCount + + The number of the video streams for the video mixing on the local client. + +- VideoInputStreams + + The video streams for the video mixing on the local client. See [TranscodingVideoStream](rtc_api_data_type.html#class_transcodingvideostream). + +- videoOutputConfiguration + + The encoding configuration of the mixed video stream after the video mixing on the local client. See [VideoEncoderConfiguration](rtc_api_data_type.html#class_videoencoderconfiguration). + +## [LocalVideoStats](rtc_api_data_type.html#class_localvideostats) + +The statistics of the local video stream. + +```cpp +struct LocalVideoStats +{ + uid_t uid; + int sentBitrate; + int sentFrameRate; + int encoderOutputFrameRate; + int rendererOutputFrameRate; + int targetBitrate; + int targetFrameRate; + QUALITY_ADAPT_INDICATION qualityAdaptIndication; + int encodedBitrate; + int encodedFrameWidth; + int encodedFrameHeight; + int encodedFrameCount; + VIDEO_CODEC_TYPE codecType; + int txPacketLossRate; +}; +``` + +### Attributes + +- uid + + The ID of the local user. + +- sentBitrate + + The actual bitrate (Kbps) for sending the local video stream.**Note** This value does not include the bitrate for resending the video after packet loss. + +- sentFrameRate + + The actual frame rate (Kbps) while sending the local video stream.**Note** This value does not include the frame rate for resending the video after packet loss. + +- encoderOutputFrameRate + + The output frame rate (fps) of the local video encoder. + +- rendererOutputFrameRate + + The output frame rate (fps) of the local video renderer. + +- targetBitrate + + The target bitrate (Kbps) of the current encoder. This is an estimate made by the SDK based on the current network conditions. + +- targetFrameRate + + The target frame rate (fps) of the current encoder. + +- qualityAdaptIndication + + Quality change of the local video in terms of target frame rate and target bit rate in this reported interval. For details, see [QUALITY_ADAPT_INDICATION](rtc_api_data_type.html#enum_qualityadaptindication). + +- encodedBitrate + + The bitrate (Kbps) for encoding the local video stream.**Note** This value does not include the bitrate for resending the video after packet loss. + +- encodedFrameWidth + + The width of the encoded video (px). + +- encodedFrameHeight + + The height of the encoded video (px). + +- encodedFrameCount + + The number of the sent video frames, represented by an aggregate value. + +- codecType + + The codec type of the local video. For details, see [VIDEO_CODEC_TYPE](rtc_api_data_type.html#enum_videocodectype). + +- txPacketLossRate + + The video packet loss rate (%) from the local client to the Agora server before applying the anti-packet loss strategies. + +**See also** + +- [onLocalVideoStats](../API/class_irtcengineeventhandler.html#callback_onlocalvideostats) + +## [LogConfig](rtc_api_data_type.html#class_logconfig_ng) + +The configuration of the SDK log files. + +```cpp +struct LogConfig +{ + const char* filePath; + uint32_t fileSizeInKB; + LOG_LEVEL level; + LogConfig() : filePath(NULL), fileSizeInKB(DEFAULT_LOG_SIZE_IN_KB), level(OPTIONAL_LOG_LEVEL_SPECIFIER LOG_LEVEL_INFO) {} +}; +``` + +### Attributes + +- filePath + + The complete path of the log files. Ensure that the path for the log file exists and is writable. You can use this parameter to rename the log files.The default file path is:Android: /storage/emulated/0/Android/data//files/agorasdk.log/.iOS: AppSandbox/Library/caches/agorasdk.log.macOS:If Sandbox is enabled: App~/Library/Logs/agorasdk.log. For example, /Users//Library/Containers//Data/Library/Logs/agorasdk.log.If Sandbox is disabled: ~/Library/Logs/agorasdk.logWindows: C: \Users\\AppData\Local\Agora\\agorasdk.log. + +- fileSizeInKB + + The size (KB) of an `agorasdk.log` file. The value range is [128,1024]. The default value is 1,024 KB. If you set `fileSizeInKByte` to a value lower than 128 KB, the SDK adjusts it to 128 KB. If you set `fileSizeInKBytes` to a value higher than 1,024 KB, the SDK adjusts it to 1,024 KB. + + **Note**This method only applies to the `agorasdk.log` file, but not the `agoraapi.log` file. + +- level + + The output level of the SDK log file. See [LOG_LEVEL](rtc_api_data_type.html#enum_loglevel).For example, if you set the log level to WARN, the SDK outputs the logs within levels FATAL, ERROR, and WARN. + +**See also** + +- [initialize](../API/class_irtcengine.html#api_create2) + +## [PlayerStreamInfo](rtc_api_data_type.html#class_playerstreaminfo) + +The detailed information of the media stream. + +```cpp +struct PlayerStreamInfo { + int streamIndex; + MEDIA_STREAM_TYPE streamType; + char codecName[kMaxCharBufferLength]; + char language[kMaxCharBufferLength]; + int videoFrameRate; + int videoBitRate; + int videoWidth; + int videoHeight; + int videoRotation; + int audioSampleRate; + int audioChannels; + int audioBitsPerSample; + int64_t duration; + PlayerStreamInfo() : streamIndex(0), + streamType(STREAM_TYPE_UNKNOWN), + videoFrameRate(0), + videoBitRate(0), + videoWidth(0), + videoHeight(0), + videoRotation(0), + audioSampleRate(0), + audioChannels(0), + audioBitsPerSample(0), + duration(0) { + memset(codecName, 0, sizeof(codecName)); + memset(language, 0, sizeof(language)); +``` + +### Attributes + +- streamIndex + + The index of the media stream. + +- streamType + + The type of the media stream. See [MEDIA_STREAM_TYPE](rtc_api_data_type.html#enum_mediastreamtype). + +- codecName + + The codec of the media stream. + +- language + + The language of the media stream. + +- videoFrameRate + + This parameter only takes effect for video streams, and indicates the video frame rate (fps). + +- videoBitrate + + This parameter only takes effect for video streams, and indicates the video bitrate (bps). + +- videoWidth + + This parameter only takes effect for video streams, and indicates the video width (pixel). + +- videoHeight + + This parameter only takes effect for video streams, and indicates the video height (pixel). + +- audioSampleRate + + This parameter only takes effect for audio streams, and indicates the audio sample rate (Hz). + +- audioChannels + + This parameter only takes effect for audio streams, and indicates the audio channel number. + +- audioBitsPerSample + + This parameter only takes effect for audio streams, and indicates the bit number of each audio sample. + +- duration + + The total duration (s) of the media stream. + +**See also** + +- [getStreamInfo](../API/class_imediaplayer.html#api_imediaplayer_getstreaminfo) + +## [PlayerUpdatedInfo](rtc_api_data_type.html#class_playerupdatedinfo) + +Information related to the media player. + +```cpp +struct PlayerUpdatedInfo { + Optional playerId; + Optional deviceId; +}; +``` + +### Attributes + +- playerId + + The ID of a media player. + +- deviceId + + The ID of a deivce. + +## [Rectangle](rtc_api_data_type.html#class_rectangle) + +The location of the target area relative to the screen or window. If you do not set this parameter, the SDK selects the whole screen or window. + +```cpp +struct Rectangle { + int x; + int y; + int width; + int height; + + Rectangle(): x(0), y(0), width(0), height(0) {} + Rectangle(int xx, int yy, int ww, int hh): x(xx), y(yy), width(ww), height(hh) {} +}; +``` + +### Attributes + +- x + + The horizontal offset from the top-left corner. + +- y + + The vertical offset from the top-left corner. + +- width + + The width of the target area. + +- height + + The height of the target area. + +**See also** + +- [startScreenCaptureByScreenRect](../API/class_irtcengine.html#api_startscreencapturebyscreenrect) +- [startScreenCaptureByWindowId](../API/class_irtcengine.html#api_startscreencapturebywindowid) +- [updateScreenCaptureRegion](../API/class_irtcengine.html#api_updatescreencaptureregion) +- [addVideoWatermark [2/2\]](../API/class_irtcengine.html#api_addvideowatermark2) + +## [RemoteAudioStats](rtc_api_data_type.html#class_remoteaudiostats) + +Audio statistics of the remote user. + +```cpp +struct RemoteAudioStats +{ + uid_t uid; + int quality; + int networkTransportDelay; + int jitterBufferDelay; + int audioLossRate; + int numChannels; + int receivedSampleRate; + int receivedBitrate; + int totalFrozenTime; + int frozenRate; + int mosValue; + int totalActiveTime; + int publishDuration; + RemoteAudioStats() : + uid(0), + quality(0), + networkTransportDelay(0), + jitterBufferDelay(0), + audioLossRate(0), + numChannels(0), + receivedSampleRate(0), + receivedBitrate(0), + totalFrozenTime(0), + frozenRate(0), + mosValue(0), + totalActiveTime(0), + publishDuration(0){} +}; +``` + +### Attributes + +- uid + + The user ID of the remote user. + +- quality + + The quality of the audio stream sent by the user. See [QUALITY_TYPE](rtc_api_data_type.html#enum_qualitytype). + +- networkTransportDelay + + The network delay (ms) from the sender to the receiver. + +- jitterBufferDelay + + The network delay (ms) from the receiver to the jitter buffer.**Note** This parameter does not take effect if the receiver is an audience member and **audienceLatencyLevel** of [ClientRoleOptions](rtc_api_data_type.html#class_clientroleoptions) is 1. + +- audioLossRate + + The frame loss rate (%) of the remote audio stream in the reported interval. + +- numChannels + + The number of audio channels. + +- receivedSampleRate + + The sampling rate of the received audio stream in the reported interval. + +- receivedBitrate + + The average bitrate (Kbps) of the received audio stream in the reported interval. + +- totalFrozenTime + + The total freeze time (ms) of the remote audio stream after the remote user joins the channel. In a session, audio freeze occurs when the audio frame loss rate reaches 4%. + +- frozenRate + + The total audio freeze time as a percentage (%) of the total time when the audio is available. The audio is considered available when the remote user neither stops sending the audio stream nor disables the audio module after joining the channel. + +- totalActiveTime + + The total active time (ms) between the start of the audio call and the callback of the remote user.The active time refers to the total duration of the remote user without the mute state. + +- publishDuration + + The total duration (ms) of the remote audio stream. + +- mosValue + + The quality of the remote audio stream in the reported interval. The quality is determined by the Agora real-time audio MOS (Mean Opinion Score) measurement method. The return value range is [0, 500]. Dividing the return value by 100 gets the MOS score, which ranges from 0 to 5. The higher the score, the better the audio quality.The subjective perception of audio quality corresponding to the Agora real-time audio MOS scores is as follows:MOS scorePerception of audio qualityGreater than 4Excellent. The audio sounds clear and smooth.From 3.5 to 4Good. The audio has some perceptible impairment but still sounds clear.From 3 to 3.5Fair. The audio freezes occasionally and requires attentive listening.From 2.5 to 3Poor. The audio sounds choppy and requires considerable effort to understand.From 2 to 2.5Bad. The audio has occasional noise. Consecutive audio dropouts occur, resulting in some information loss. The users can communicate only with difficulty.Less than 2Very bad. The audio has persistent noise. Consecutive audio dropouts are frequent, resulting in severe information loss. Communication is nearly impossible. + +**See also** + +- [onRemoteAudioStats](../API/class_irtcengineeventhandler.html#callback_onremoteaudiostats) + +## [RemoteVideoStats](rtc_api_data_type.html#class_remotevideostats) + +Statistics of the remote video stream. + +```cpp +struct RemoteVideoStats { + uid_t uid; + int delay; + int width; + int height; + int receivedBitrate; + int decoderOutputFrameRate; + int rendererOutputFrameRate; + int frameLossRate; + int packetLossRate; + VIDEO_STREAM_TYPE rxStreamType; + int totalFrozenTime; + int frozenRate; + int avSyncTimeMs; + int totalActiveTime; + int publishDuration; +}; +``` + +### Attributes + +- uid + + The user ID of the remote user sending the video stream. + +- delay + + Deprecated:In scenarios where audio and video are synchronized, you can get the video delay data from **networkTransportDelay** and **jitterBufferDelay** in [RemoteAudioStats](rtc_api_data_type.html#class_remoteaudiostats).The video delay (ms). + +- width + + The width (pixels) of the video. + +- height + + The height (pixels) of the video. + +- receivedBitrate + + The bitrate (Kbps) of receiving the remote video since the last count. + +- decoderOutputFrameRate + + The frame rate (fps) of decoding the remote video. + +- rendererOutputFrameRate + + The frame rate (fps) of rendering the remote video. + +- frameLossRate + + Packet loss rate (%) of the remote video. + +- packetLossRate + + The packet loss rate (%) of the remote video after using the anti-packet-loss technology. + +- rxStreamType + + The type of the video stream. For details, see [REMOTE_VIDEO_STREAM_TYPE](rtc_api_data_type.html#enum_remotevideostreamtype). + +- totalFrozenTime + + The total freeze time (ms) of the remote video stream after the remote user joins the channel. In a video session where the frame rate is set to 5 fps or higher, video freeze occurs when the time interval between two adjacent video frames is more than 500 ms. + +- frozenRate + + The total video freeze time as a percentage (%) of the total time when the video is available. The video is available means that the remote user neither stops sending the video stream nor disables the video module after joining the channel. + +- totalActiveTime + + Total active time (ms) of the video.When the remote user/host neither stops sending the video stream nor disables the video module after joining the channel, the video is available. + +- publishDuration + + The total duration (ms) of the remote video stream. + +- avSyncTimeMs + + The amount of time (ms) that the audio is ahead of the video.**Note** If it is negative, it means that the audio is lagging behind the video. + +**See also** + +- [onRemoteVideoStats](../API/class_irtcengineeventhandler.html#callback_onremotevideostats) + +## [RtcEngineContext](rtc_api_data_type.html#class_rtcengineconfig_ng) + +Configurations for the RtcEngineContext instance. + +```cpp +struct RtcEngineContext { + IRtcEngineEventHandler* eventHandler; + const char* appId; + void* context; + bool enableAudioDevice; + CHANNEL_PROFILE_TYPE channelProfile; + AUDIO_SCENARIO_TYPE audioScenario; + unsigned int areaCode; + commons::LogConfig logConfig; + + RtcEngineContext() + : eventHandler(NULL), appId(NULL), context(NULL), + enableAudioDevice(true), channelProfile(CHANNEL_PROFILE_LIVE_BROADCASTING), + audioScenario(AUDIO_SCENARIO_HIGH_DEFINITION), + areaCode(AREA_CODE_GLOB), + logConfig() {} +}; +``` + +### Attributes + +- eventHandler + + The event handler for [IRtcEngine](class_irtcengine.html#class_irtcengine). See [IRtcEngineEventHandler](class_irtcengineeventhandler.html#class_irtcengineeventhandler). + +- appId + + The App ID issued by Agora for your project. Only users in apps with the same App ID can join the same channel and communicate with each other. An App ID can only be used to create one IRtcEngine instance. To change your App ID, call [release](class_irtcengine.html#api_release) to destroy the current IRtcEngine instanceand then create a new one. + +- context + + For Windows, it is the window handle of the app. Once set, this parameter enables you to plug or unplug the video devices while they are powered.For Android, it is the context of Android Activity. + +- enableAudioDevice + + Sets whether to allow the SDK to use audio devices:`true`: (Default) Allow the SDK to use audio devices.`false`: Do not allow the SDK to use audio devices. + + **Note**If you need to get the mixed remote audio data through [pullAudioFrame](class_imediaengine.html#api_imediaengine_pullaudioframe), ensure that you set this parameter as `false`. + +- channelProfile + + The channel profile. For details, see [CHANNEL_PROFILE_TYPE](rtc_api_data_type.html#enum_channelprofiletype_ng). + +- audioScenario + + The audio scenario. See [AUDIO_SCENARIO_TYPE](rtc_api_data_type.html#enum_audioscenariotype_ng). Under different audio scenarios, the device uses different volume types. + +- areaCode + + The region for connection. This is an advanced feature and applies to scenarios that have regional restrictions. For details on supported regions, see [AREA_CODE](rtc_api_data_type.html#enum_areacode).After specifying the region, the app integrated with the Agora SDK connects to the Agora servers within that region. + +- logConfig + + The log files that the SDK outputs. See [LogConfig](rtc_api_data_type.html#class_logconfig_ng).By default, the SDK outputs four log files: `agorasdk.log`, `agorasdk1.log`, `agoraapi.log`, and `agoraapi1.log`. The `agorasdk.log` and `agorasdk1.log` files each have a default size of 1024 KB, and the `agoraapi.log` and `agoraapi1.log` files each have a default size of 2,048 KB. These log files are encoded in UTF-8.The SDK writes the latest logs in `agorasdk.log` or `agoraapi.log`. When `agorasdk.log` or `agoraapi.log` is full, the SDK deletes `agorasdk1.log` or `agoraapi1.log`, renames `agorasdk.log` to `agorasdk1.log` and `agoraapi.log` to `agorasapi1.log`, and creates a new `agorasdk.log` or `agoraapi.log` to record the latest logs. + +**See also** + +- [initialize](../API/class_irtcengine.html#api_create2) +- [setAudioProfile [2/2\]](../API/class_irtcengine.html#api_setaudioprofile2) + +## [RtcConnection](rtc_api_data_type.html#class_rtcconnection) + +Contains connection information. + +```cpp +struct RtcConnection { + const char* channelId; + uid_t localUid; + + RtcConnection() : RtcConnection(NULL, 0) {} + RtcConnection(const char* channel_id, uid_t local_uid) + : channelId(channel_id), localUid(local_uid) {} +}; +``` + +### Attributes + +- channelId + + The channel name. + +- localUid + + The ID of the local user. + +## [RtcImage](rtc_api_data_type.html#class_rtcimage) + +Image properties. + +```cpp +typedef struct RtcImage { + const char* url; + int x; + int y; + int width; + int height; + int zOrder; + + RtcImage() : url(NULL), x(0), y(0), width(0), height(0), zOrder(0) {} + } RtcImage; +``` + + + +This class sets the properties of the watermark and background images in the live video. + +### Attributes + +- url + + The HTTP/HTTPS URL address of the image in the live video. The maximum length of this parameter is 1024 bytes. + +- x + + The x coordinate (pixel) of the image on the video frame (taking the upper left corner of the video frame as the origin). + +- y + + The y coordinate (pixel) of the image on the video frame (taking the upper left corner of the video frame as the origin). + +- width + + The width (pixel) of the image on the video frame. + +- height + + The height (pixel) of the image on the video frame. + +- zOrder + + The layer index of the video frame. An integer. The value range is [0, 100]. 1 represents the lowest layer. 100 represents the top layer. + +**See also** + +- [setLiveTranscoding](../API/class_irtcengine.html#api_setlivetranscoding) +- [addVideoWatermark [1/2\]](../API/class_irtcengine.html#api_addvideowatermark) + +## [RtcStats](rtc_api_data_type.html#class_rtcstats) + +Statistics of a call session. + +```cpp +struct RtcStats { + unsigned int duration; + unsigned int txBytes; + unsigned int rxBytes; + unsigned int txAudioBytes; + unsigned int txVideoBytes; + unsigned int rxAudioBytes; + unsigned int rxVideoBytes; + unsigned short txKBitRate; + unsigned short rxKBitRate; + unsigned short rxAudioKBitRate; + unsigned short txAudioKBitRate; + unsigned short rxVideoKBitRate; + unsigned short txVideoKBitRate; + unsigned short lastmileDelay; + unsigned int userCount; + double cpuAppUsage; + double cpuTotalUsage; + int gatewayRtt; + double memoryAppUsageRatio; + double memoryTotalUsageRatio; + int memoryAppUsageInKbytes; + int connectTimeMs; + int txPacketLossRate; + int rxPacketLossRate; + RtcStats() : + duration(0), + txBytes(0), + rxBytes(0), + txAudioBytes(0), + txVideoBytes(0), + rxAudioBytes(0), + rxVideoBytes(0), + txKBitRate(0), + rxKBitRate(0), + rxAudioKBitRate(0), + txAudioKBitRate(0), + rxVideoKBitRate(0), + txVideoKBitRate(0), + lastmileDelay(0), + userCount(0), + cpuAppUsage(0.0), + cpuTotalUsage(0.0), + gatewayRtt(0), + memoryAppUsageRatio(0.0), + memoryTotalUsageRatio(0.0), + memoryAppUsageInKbytes(0), + connectTimeMs(0), + txPacketLossRate(0), + rxPacketLossRate(0) {} +}; +``` + +### Attributes + +- duration + + Call duration of the local user in seconds, represented by an aggregate value. + +- txBytes + + The number of bytes sent. + +- rxBytes + + The number of bytes received. + +- txAudioBytes + + The total number of audio bytes sent, represented by an aggregate value. + +- txVideoBytes + + The total number of video bytes sent, represented by an aggregate value. + +- rxAudioBytes + + The total number of audio bytes received, represented by an aggregate value. + +- rxVideoBytes + + The total number of video bytes received, represented by an aggregate value. + +- txKBitRate + + Video transmission bitrate (Kbps), represented by an instantaneous value. + +- rxKBitRate + + The receiving bitrate (Kbps), represented by an instantaneous value. + +- rxAudioKBitRate + + Audio receive bitrate (Kbps), represented by an instantaneous value. + +- txAudioKBitRate + + The bitrate (Kbps) of sending the audio packet. + +- rxVideoKBitRate + + Video receive bitrate (Kbps), represented by an instantaneous value. + +- txVideoKBitRate + + The bitrate (Kbps) of sending the video. + +- lastmileDelay + + The client-to-server delay (milliseconds). + +- txPacketLossRate + + The packet loss rate (%) from the client to the Agora server before applying the anti-packet-loss algorithm. + +- rxPacketLossRate + + The packet loss rate (%) from the Agora server to the client before using the anti-packet-loss method. + +- userCount + + The number of users in the channel. + +- cpuAppUsage + + The CPU usage (%) of the app. + +- cpuTotalUsage + + The system CPU usage (%).For Windows, in the multi-kernel environment, this member represents the average CPU usage. The value = 100 - System Idle Progress in Task Manager.**Note** The value of cpuTotalUsage is always reported as 0 in the [onLeaveChannel](class_irtcengineeventhandler.html#callback_onleavechannel) callback. + +- connectTimeMs + + The duration (ms) between the SDK starts connecting and the connection is established. If the value reported is 0, it means invalid. + +- gatewayRtt + + The round-trip time delay (ms) from the client to the local router. + +- memoryAppUsageRatio + + The memory ratio occupied by the app (%).**Note** This value is for reference only. Due to system limitations, you may not get this value. + +- memoryTotalUsageRatio + + The memory occupied by the system (%).**Note** This value is for reference only. Due to system limitations, you may not get this value. + +- memoryAppUsageInKbytes + + The memory size occupied by the app (KB).**Note** This value is for reference only. Due to system limitations, you may not get this value. + +**See also** + +- [onLeaveChannel](../API/class_irtcengineeventhandler.html#callback_onleavechannel) +- [onRtcStats](../API/class_irtcengineeventhandler.html#callback_onrtcstats) + +## [ScreenCaptureConfiguration](rtc_api_data_type.html#class_screencaptureconfiguration) + +The configuration of the captured screen. + +```cpp +struct ScreenCaptureConfiguration { + bool isCaptureWindow; + uint32_t displayId; + Rectangle screenRect; + view_t windowId; + ScreenCaptureParameters params; + Rectangle regionRect; + + ScreenCaptureConfiguration() : isCaptureWindow(false), displayId(0) {} +}; +``` + +### Attributes + +- isCaptureWindow + + Whether to capture the window on the screen:`true`: Capture the window.`false`: (Default) Capture the screen, not the window. + +- displayId + + (macOS only) The display ID of the screen.**Note** This parameter takes effect only when you want to capture the screen on macOS. + +- screenRect + + (Windows only) The relative position of the shared screen to the virtual screen.**Note** This parameter takes effect only when you want to capture the screen on Windows. + +- windowId + + (For Windows and macOS only)**Note** This parameter takes effect only when you want to capture the window. + +- params + + (For Windows and macOS only) The screen capture configuration. For details, see [ScreenCaptureParameters](rtc_api_data_type.html#class_screencaptureparameters). + +- regionRect + + (For Windows and macOS only) The relative position of the shared region to the whole screen. For details, see [Rectangle](rtc_api_data_type.html#class_rectangle).If you do not set this parameter, the SDK shares the whole screen. If the region you set exceeds the boundary of the screen, only the region within in the screen is shared. If you set width or height in Rectangle as 0, the whole screen is shared. + +**See also** + +- [startPrimaryScreenCapture](../API/class_irtcengine.html#api_startprimaryscreencapture) +- [startSecondaryScreenCapture](../API/class_irtcengine.html#api_startsecondaryscreencapture) + +## [ScreenCaptureParameters](rtc_api_data_type.html#class_screencaptureparameters) + +Screen sharing configurations. + +```cpp +struct ScreenCaptureParameters { + VideoDimensions dimensions; + int frameRate; + int bitrate; + bool captureMouseCursor; + bool windowFocus; + view_t *excludeWindowList; + int excludeWindowCount; + + ScreenCaptureParameters() + : dimensions(1920, 1080), frameRate(5), bitrate(STANDARD_BITRATE), captureMouseCursor(true), windowFocus(false), excludeWindowList(OPTIONAL_NULLPTR), excludeWindowCount(0) {} + ScreenCaptureParameters(const VideoDimensions& d, int f, int b) + : dimensions(d), frameRate(f), bitrate(b), captureMouseCursor(true), windowFocus(false), excludeWindowList(OPTIONAL_NULLPTR), excludeWindowCount(0) {} + ScreenCaptureParameters(int width, int height, int f, int b) + : dimensions(width, height), frameRate(f), bitrate(b), captureMouseCursor(true), windowFocus(false), excludeWindowList(OPTIONAL_NULLPTR), excludeWindowCount(0) {} + ScreenCaptureParameters(int width, int height, int f, int b, bool cur, bool fcs) + : dimensions(width, height), frameRate(f), bitrate(b), captureMouseCursor(cur), windowFocus(fcs), excludeWindowList(OPTIONAL_NULLPTR), excludeWindowCount(0) {} + ScreenCaptureParameters(int width, int height, int f, int b, view_t *ex, int cnt) + : dimensions(width, height), frameRate(f), bitrate(b), captureMouseCursor(true), windowFocus(false), excludeWindowList(ex), excludeWindowCount(cnt) {} + ScreenCaptureParameters(int width, int height, int f, int b, bool cur, bool fcs, view_t *ex, int cnt) + : dimensions(width, height), frameRate(f), bitrate(b), captureMouseCursor(cur), windowFocus(fcs), excludeWindowList(ex), excludeWindowCount(cnt) {} +}; +``` + +### Attributes + +- dimensions + + The maximum dimensions of encoding the shared region. For details, see [VideoDimensions](rtc_api_data_type.html#class_videodimensions). The default value is 1,920 × 1,080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges.If the screen dimensions are different from the value of this parameter, Agora applies the following strategies for encoding. Suppose `dimensions` are set to 1,920 x 1,080:If the value of the screen dimensions is lower than that of `dimensions`, for example, 1,000 x 1,000 pixels, the SDK uses 1,000 x 1,000 pixels for encoding.If the value of the screen dimensions is larger than that of `dimensions`, for example, 2,000 × 1,500, the SDK uses the maximum value next to 1,920 × 1,080 with the aspect ratio of the screen dimension (4:3) for encoding, that is, 1,440 × 1,080. + +- frameRate + + The frame rate (fps) of the shared region. The default value is 5. Agora does not recommend setting it to a value greater than 15. + +- bitrate + + The bitrate (Kbps) of the shared region. The default value is 0, which represents that the SDK works out a bitrate according to the dimensions of the current screen. + +- captureMouseCursor + + Whether to capture the mouse in screen sharing:`true`: (Default) Capture the mouse.`false`: Do not capture the mouse. + +- windowFocus + + Whether to bring the window to the front when calling the [startScreenCaptureByWindowId](class_irtcengine.html#api_startscreencapturebywindowid) method to share it:`true`:Bring the window to the front.`false`: (Default) Do not bring the window to the front. + +- excludeWindowList + + The ID list of the windows to be blocked. When calling [startScreenCaptureByScreenRect](class_irtcengine.html#api_startscreencapturebyscreenrect) to start screen sharing, you can use this parameter to block a specified window. When calling to[updateScreenCaptureParameters](class_irtcengine.html#api_updatescreencaptureparameters) update screen sharing configurations, you can use this parameter to dynamically block a specified window. + +- excludeWindowCount + + The number of windows to be blocked. + +**See also** + +- [startScreenCaptureByScreenRect](../API/class_irtcengine.html#api_startscreencapturebyscreenrect) +- [startScreenCaptureByWindowId](../API/class_irtcengine.html#api_startscreencapturebywindowid) +- [updateScreenCaptureParameters](../API/class_irtcengine.html#api_updatescreencaptureparameters) +- [startScreenCapture](../API/class_irtcengine.html#api_startscreencapture_ng) + +## [SimulcastStreamConfig](rtc_api_data_type.html#class_simulcaststreamconfig) + +The configuration of the low-quality video stream. + +```cpp +struct SimulcastStreamConfig { + VideoDimensions dimensions; + int bitrate; + int framerate; + SimulcastStreamConfig() : dimensions(160, 120), bitrate(65), framerate(5) {} + bool operator==(const SimulcastStreamConfig& rhs) const { + return dimensions == rhs.dimensions && bitrate == rhs.bitrate && framerate == rhs.framerate; + } +}; +``` + +### Attributes + +- dimensions + + The video dimensions, see [VideoDimensions](rtc_api_data_type.html#class_videodimensions). The default value is 160 × 120. + +- bitrate + + Video receive bitrate (Kbps), represented by an instantaneous value. The default value of the log level is 5. + +- frameRate + + The capture frame rate (fps) of the local video. The default value is 5. + +**See also** + +- [enableDualStreamMode [2/3\]](../API/class_irtcengine.html#api_enabledualstreammode2) +- [enableDualStreamMode [3/3\]](../API/class_irtcengine.html#api_enabledualstreammode3) + +## [SrcInfo](rtc_api_data_type.html#class_srcinfo) + +Information about the video bitrate of the media resource being played. + +```cpp +struct SrcInfo { + int bitrateInKbps; + const char* name; +}; +``` + +### Attributes + +- bitrateInKbps + + The video bitrate (Kbps) of the media resource being played. + +- name + + The name of the media resource. + +## [TranscodingUser](rtc_api_data_type.html#class_transcodinguser) + +Transcoding configurations of each host. + +```cpp +truct TranscodingUser { + uid_t uid; + int x; + int y; + int width; + int height; + int zOrder; + double alpha; + int audioChannel; + TranscodingUser() + : uid(0), + x(0), + y(0), + width(0), + height(0), + zOrder(0), + alpha(1.0), + audioChannel(0) {} +}; +``` + +### Attributes + +- uid + + The user ID of the host. + +- x + + The x coordinate (pixel) of the host's video on the output video frame (taking the upper left corner of the video frame as the origin). The value range is [0, width], where width is the [LiveTranscoding](rtc_api_data_type.html#class_livetranscoding)`width` set in . + +- y + + The y coordinate (pixel) of the host's video on the output video frame (taking the upper left corner of the video frame as the origin). The value range is [0, height], where height is the [LiveTranscoding](rtc_api_data_type.html#class_livetranscoding)`height` set in . + +- width + + The width (pixel) of the host's video. + +- height + + The height (pixel) of the host's video. + +- zOrder + + The layer index number of the host's video. The value range is [0, 100].0: (Default) The host's video is the bottom layer.100: The host's video is the top layer.**Note**If the value is beyond this range, the SDK reports the error code `ERR_INVALID_ARGUMENT`.As of v2.3, the SDK supports setting zOrder to 0. + +- alpha + + The transparency of the host's video. The value range is [0.0, 1.0].0.0: Completely transparent.1.0: (Default) Opaque. + +- audioChannel + + The audio channel used by the host's audio in the output audio. The default value is 0, and the value range is [0, 5].`0`: (Recommended) The defaut setting, which supports dual channels at most and depends on the upstream of the host.`1`: The host's audio uses the FL audio channel. If the host's upstream uses multiple audio channels, the Agora server mixes them into mono first.`2`: The host's audio uses the FC audio channel. If the host's upstream uses multiple audio channels, the Agora server mixes them into mono first.`3`: The host's audio uses the FR audio channel. If the host's upstream uses multiple audio channels, the Agora server mixes them into mono first.`4`: The host's audio uses the BL audio channel. If the host's upstream uses multiple audio channels, the Agora server mixes them into mono first.`5`: The host's audio uses the BR audio channel. If the host's upstream uses multiple audio channels, the Agora server mixes them into mono first.`0xFF` or a value greater than `5`: The host's audio is muted, and the Agora server removes the host's audio.**Note** If the value is not `0`, a special player is required. + +**See also** + +- [setLiveTranscoding](../API/class_irtcengine.html#api_setlivetranscoding) + +## [TranscodingVideoStream](rtc_api_data_type.html#class_transcodingvideostream) + +The video streams for the video mixing on the local client. + +```cpp +struct TranscodingVideoStream { + agora::media::MEDIA_SOURCE_TYPE sourceType; + uid_t remoteUserUid; + const char* imageUrl; + int x; + int y; + int width; + int height; + int zOrder; + double alpha; + bool mirror; + + TranscodingVideoStream() + : sourceType(agora::media::PRIMARY_CAMERA_SOURCE), + remoteUserUid(0), + imageUrl(NULL), + x(0), + y(0), + width(0), + height(0), + zOrder(0), + alpha(1.0), + mirror(false) {} +}; +``` + +### Attributes + +- sourceType + + The source type of video for the video mixing on the local client. See [VIDEO_SOURCE_TYPE](rtc_api_data_type.html#enum_videosourcetype). + +- remoteUserUid + + The ID of the remote user.**Note** Use this parameter only when the source type of the video for the video mixing on the local client is VIDEO_SOURCE_REMOTE. + +- imageUrl + + The URL of the image.**Note** Use this parameter only when the source type of the video for the video mixing on the local client is `RTC_IMAGE`. + +- x + + The horizontal displacement of the top-left corner of the video for the video mixing on the client relative to the top-left corner (origin) of the canvas for this video mixing. + +- y + + The vertical displacement of the top-left corner of the video for the video mixing on the client relative to the top-left corner (origin) of the canvas for this video mixing. + +- width + + The width (px) of the video for the video mixing on the local client. + +- heigh + + The height (px) of the video for the video mixing on the local client. + +- zOrder + + The number of the layer to which the video for the video mixing on the local client belongs. The value range is [0,100].0: (Default) The layer is at the bottom.100: The layer is at the top. + +- alpha + + The transparency of the video for the video mixing on the local client. The value range is [0.0,1.0]. 0.0 means the transparency is completely transparent. 1.0 means the transparency is opaque. + +- mirror + + Whether to mirror the video for the video mixing on the local client.`true`: Mirroring.`false`: (Default) Do not mirror.**Note** The paramter only works for videos with the source type `CAMERA`. + +## [UplinkNetworkInfo](rtc_api_data_type.html#class_uplinknetworkinfo) + +The uplink network information. + +```cpp +struct UplinkNetworkInfo { + int video_encoder_target_bitrate_bps; + + UplinkNetworkInfo() : video_encoder_target_bitrate_bps(0) {} + + bool operator==(const UplinkNetworkInfo& rhs) const { + return (video_encoder_target_bitrate_bps == rhs.video_encoder_target_bitrate_bps); + } +}; +``` + +### Attributes + +- video_encoder_target_bitrate_bps + + The target video encoder bitrate (bps). + +**See also** + +- [onUplinkNetworkInfoUpdated](../API/class_irtcengineeventhandler.html#callback_onuplinknetworkinfoupdated) + +## [UserAudioSpectrumInfo](rtc_api_data_type.html#class_useraudiospectruminfo) + +Audio spectrum information of the remote user. + +```cpp +struct UserAudioSpectrumInfo { + agora::rtc::uid_t uid; + struct AudioSpectrumData spectrumData; + + UserAudioSpectrumInfo () : uid(0), spectrumData() {} + UserAudioSpectrumInfo(agora::rtc::uid_t _uid, const float *data, int length) : + uid(_uid) { spectrumData.audioSpectrumData = data; spectrumData.dataLength = length; } +}; +``` + +### Attributes + +- uid + + The ID of the remote user. + +- spectrumData + + Audio spectrum information of the remote user. For details, see [AudioSpectrumData](rtc_api_data_type.html#class_audiospectrumdata). + +**See also** + +- [onRemoteAudioSpectrum](../API/class_iaudiospectrumobserver.html#callback_iaudiospectrumobserver_onremoteaudiospectrum) + +## [UserInfo](rtc_api_data_type.html#class_userinfo) + +The information of the user. + + + +```cpp +struct UserInfo { + uid_t uid; + char userAccount[MAX_USER_ACCOUNT_LENGTH]; + UserInfo() + : uid(0) { + userAccount[0] = '\0'; + } + }; +``` + + + +### Attributes + +- uid + + User ID + +- userAccount + + The user account. The maximum data length is [MAX_USER_ACCOUNT_LENGTH_TYPE](rtc_api_data_type.html#enum_maxuseraccountlengthtype). + +## [VideoCanvas](rtc_api_data_type.html#class_videocanvas_ng) + +Attributes of video canvas object. + + + + + +### Attributes + +- view + + Video display window. + +- renderMode + + The rendering mode of the video. See [RENDER_MODE_TYPE](rtc_api_data_type.html#enum_rendermodetype). + +- mirrorMode + + The mirror mode of the view. See [VIDEO_MIRROR_MODE_TYPE](rtc_api_data_type.html#enum_videomirrormodetype).**Note**For the mirror mode of the local video view: If you use a front camera, the SDK enables the mirror mode by default; if you use a rear camera, the SDK disables the mirror mode by default.For the remote user: The mirror mode is disabled by default. + +- uid + + User ID. + +- sourceType + + The type of the video frame, see [VIDEO_SOURCE_TYPE](rtc_api_data_type.html#enum_videosourcetype). + +**See also** + +- [setupLocalVideo](../API/class_irtcengine.html#api_setuplocalvideo) +- [setupRemoteVideo](../API/class_irtcengine.html#api_setupremotevideo) + +## [VideoDimensions](rtc_api_data_type.html#class_videodimensions) + +Video dimensions. + +```cpp +struct VideoDimensions { + int width; + int height; + VideoDimensions() : width(640), height(480) {} + VideoDimensions(int w, int h) : width(w), height(h) {} + bool operator==(const VideoDimensions& rhs) const { + return width == rhs.width && height == rhs.height; + } +}; +``` + +### Attributes + +- width + + The width (pixels) of the video. + +- height + + The height (pixels) of the video. + +**See also** + +- [setVideoEncoderConfiguration](../API/class_irtcengine.html#api_setvideoencoderconfiguration) +- [startScreenCaptureByScreenRect](../API/class_irtcengine.html#api_startscreencapturebyscreenrect) +- [startScreenCaptureByWindowId](../API/class_irtcengine.html#api_startscreencapturebywindowid) +- [updateScreenCaptureParameters](../API/class_irtcengine.html#api_updatescreencaptureparameters) + +## [VideoEncoderConfiguration](rtc_api_data_type.html#class_videoencoderconfiguration) + +Video encoder configurations. + +```cpp +struct VideoEncoderConfiguration { + VIDEO_CODEC_TYPE codecType; + VideoDimensions dimensions; + int frameRate; + int bitrate; + int minBitrate; + ORIENTATION_MODE orientationMode; + DEGRADATION_PREFERENCE degradationPreference; + VIDEO_MIRROR_MODE_TYPE mirrorMode; + + VideoEncoderConfiguration(const VideoDimensions& d, int f, int b, ORIENTATION_MODE m, VIDEO_MIRROR_MODE_TYPE mirror = VIDEO_MIRROR_MODE_DISABLED) + : codecType(VIDEO_CODEC_H264), + dimensions(d), + frameRate(f), + bitrate(b), + minBitrate(DEFAULT_MIN_BITRATE), + orientationMode(m), + degradationPreference(MAINTAIN_QUALITY), + mirrorMode(mirror) {} + VideoEncoderConfiguration(int width, int height, int f, int b, ORIENTATION_MODE m, VIDEO_MIRROR_MODE_TYPE mirror = VIDEO_MIRROR_MODE_DISABLED) + : codecType(VIDEO_CODEC_H264), + dimensions(width, height), + frameRate(f), + bitrate(b), + minBitrate(DEFAULT_MIN_BITRATE), + orientationMode(m), + degradationPreference(MAINTAIN_QUALITY), + mirrorMode(mirror) {} + VideoEncoderConfiguration(const VideoEncoderConfiguration& config) + : codecType(config.codecType), + dimensions(config.dimensions), + frameRate(config.frameRate), + bitrate(config.bitrate), + minBitrate(config.minBitrate), + orientationMode(config.orientationMode), + degradationPreference(config.degradationPreference), + mirrorMode(config.mirrorMode) {} + VideoEncoderConfiguration() + : codecType(VIDEO_CODEC_H264), + dimensions(FRAME_WIDTH_640, FRAME_HEIGHT_360), + frameRate(FRAME_RATE_FPS_15), + bitrate(STANDARD_BITRATE), + minBitrate(DEFAULT_MIN_BITRATE), + orientationMode(ORIENTATION_MODE_ADAPTIVE), + degradationPreference(MAINTAIN_QUALITY), + mirrorMode(VIDEO_MIRROR_MODE_DISABLED) {} +}; +``` + +### Attributes + +- dimensions + + The dimensions of the encoded video (px). See [VideoDimensions](rtc_api_data_type.html#class_videodimensions). This parameter measures the video encoding quality in the format of length × width. The default value is 640 × 360. You can set a custom value. + +- codecType + + The codec type of the local video stream. See [VIDEO_CODEC_TYPE](rtc_api_data_type.html#enum_videocodectype). + +- frameRate + + The frame rate (fps) of the encoding video frame. The default value is 15. See [FRAME_RATE](rtc_api_data_type.html#enum_framerate). + +- minFramerate + + The minimum encoding frame rate of the video. The default value is -1. + +- bitrate + + The encoding bitrate (Kbps) of the video.STANDARD_BITRATE : (Recommended) Standard bitrate mode. In this mode, the video bitrate is twice the base bitrate.COMPATIBLE_BITRATE: Adaptive bitrate mode. In this mode, the video bitrate is the same as the base bitrate. If you choose this mode in the interactive streaming profile, the video frame rate may be lower than the set value. + +- minBitrate + + The minimum encoding bitrate (Kbps) of the video.The SDK automatically adjusts the encoding bitrate to adapt to the network conditions. Using a value greater than the default value forces the video encoder to output high-quality images but may cause more packet loss and sacrifice the smoothness of the video transmission. Unless you have special requirements for image quality, Agora does not recommend changing this value.**Note** This parameter only applies to the interactive streaming profile. + +- orientationMode + + The orientation mode of the encoded video. See [ORIENTATION_MODE](rtc_api_data_type.html#enum_orientationmode). + +- degradationPreference + + Video degradation preference under limited bandwidth. See [DEGRADATION_PREFERENCE](rtc_api_data_type.html#enum_degradationpreference). + +- mirrorMode + + Sets the mirror mode of the published local video stream. It only affects the video that the remote user sees. See [VIDEO_MIRROR_MODE_TYPE](rtc_api_data_type.html#enum_videomirrormodetype).**Note** By default, the video is not mirrored. + +**See also** + +- [setVideoEncoderConfiguration](../API/class_irtcengine.html#api_setvideoencoderconfiguration) + +## [VideoFrame](rtc_api_data_type.html#class_videoframe_ng) + +Configurations of the video frame + +```cpp +struct VideoFrame { + VIDEO_PIXEL_FORMAT type; + int width; + int height; + int yStride; + int uStride; + int vStride; + void* yBuffer; + void* uBuffer; + void* vBuffer; + int rotation; + int64_t renderTimeMs; + int avsync_type; + }; +``` + +The video data format is YUV420. Note that the buffer provides a pointer to a pointer. This interface cannot modify the pointer of the buffer but can modify the content of the buffer. + +### Attributes + +- type + + The pixel format. For details, see [VIDEO_PIXEL_FORMAT](rtc_api_data_type.html#enum_videopixelformat). + +- width + + Width of the video in the number of pixels. + +- height + + Height of the video in the number of pixels. + +- yStride + + The line span of the Y buffer within the YUV data. + +- uStride + + The line span of the U buffer within the YUV data. + +- vStride + + The line span of the V buffer within the YUV data. + +- yBuffer + + The pointer to the Y buffer pointer within the YUV data. + +- uBuffer + + The pointer to the U buffer pointer within the YUV data. + +- vBuffer + + The pointer to the V buffer pointer within the YUV data. + +- rotation + + Sets the clockwise rotation of the video frame before rendering. Supported values include 0, 90, 180, and 270 degrees. + +- renderTimeMs + + The timestamp (ms) of the external audio frame. It is mandatory. You can use it to restore the order of the captured audio frame, or synchronize audio and video frames in video-related scenarios (including scenarios where external video sources are used). + +- avsync_type + + A reserved parameter. + +**See also** + +- [onCaptureVideoFrame](../API/class_ivideoframeobserver.html#callback_ivideoframeobserver_oncapturevideoframe) +- [onRenderVideoFrame](../API/class_ivideoframeobserver.html#callback_ivideoframeobserver_onrendervideoframe) +- [getRotationApplied](../API/class_ivideoframeobserver.html#callback_ivideoframeobserver_getrotationapplied) +- [onMediaPlayerVideoFrame](../API/class_ivideoframeobserver.html#callback_ivideoframeobserver_onmediaplayervideoframe) +- [onScreenCaptureVideoFrame](../API/class_ivideoframeobserver.html#callback_ivideoframeobserver_onscreencapturevideoframe) + +## [VideoFormat](rtc_api_data_type.html#class_videoformat_ng) + +The format of the video frame. + +```cpp +struct VideoFormat { + int width; + int height; + int fps; +} +``` + +### Attributes + +- width + + The width (px) of the video frame. + +- height + + The height (px) of the video frame. + +- fps + + The video frame rate (fps). + +## [VirtualBackgroundSource](rtc_api_data_type.html#class_virtualbackgroundsource) + +The custom background image. + + + +```cpp +struct VirtualBackgroundSource { + enum BACKGROUND_SOURCE_TYPE { + BACKGROUND_COLOR = 1, + BACKGROUND_IMG, + BACKGROUND_BLUR, + }; + enum BACKGROUND_BLUR_DEGREE { + BLUR_DEGREE_LOW = 1, + BLUR_DEGREE_MEDIUM, + BLUR_DEGREE_HIGH, + }; + BACKGROUND_SOURCE_TYPE background_source_type; + unsigned int color; + const char* source; + BACKGROUND_BLUR_DEGREE blur_degree; + VirtualBackgroundSource() : background_source_type(BACKGROUND_COLOR), color(0xffffff), source(NULL), blur_degree(BLUR_DEGREE_HIGH) {} + +``` + + + +### Attributes + +- background_source_type + + The type of the custom background image. See [BACKGROUND_SOURCE_TYPE](rtc_api_data_type.html#enum_backgroundsourcetype). + +- color + + The type of the custom background image. The color of the custom background image. The format is a hexadecimal integer defined by RGB, without the # sign, such as 0xFFB6C1 for light pink. The default value is 0xFFFFFF, which signifies white. The value range is [0x000000, 0xffffff]. If the value is invalid, the SDK replaces the original background image with a white background image.**Note** This parameter takes effect only when the type of the custom background image is BACKGROUND_COLOR. + +- source + + The local absolute path of the custom background image. PNG and JPG formats are supported. If the path is invalid, the SDK replaces the original background image with a white background image.**Note** This parameter takes effect only when the type of the custom background image is BACKGROUND_IMG. + +- blur_degree + + The degree of blurring applied to the custom background image. See [BACKGROUND_BLUR_DEGREE](rtc_api_data_type.html#enum_backgroundblurdegree).**Note** This parameter takes effect only when the type of the custom background image is BACKGROUND_BLUR. + +**See also** + +- [enableVirtualBackground](../API/class_irtcengine.html#api_enablevirtualbackground) + +### [BACKGROUND_SOURCE_TYPE](rtc_api_data_type.html#enum_backgroundsourcetype) + +The type of the custom background image. + + + +#### Enumerator + +- BACKGROUND_COLOR + + 1: (Default) The background image is a solid color. + +- BACKGROUND_IMG + + The background image is a file in PNG or JPG format. + +- BACKGROUND_BLUR + + The background image is the blurred background. + +**See also** + +- [enableVirtualBackground](../API/class_irtcengine.html#api_enablevirtualbackground) + +### [BACKGROUND_BLUR_DEGREE](rtc_api_data_type.html#enum_backgroundblurdegree) + +The degree of blurring applied to the custom background image. + + + +#### Enumerator + +- BLUR_DEGREE_LOW + + 1: The degree of blurring applied to the custom background image is low. The user can almost see the background clearly. + +- BLUR_DEGREE_MEDIUM + + The degree of blurring applied to the custom background image is medium. It is difficult for the user to recognize details in the background. + +- BLUR_DEGREE_HIGH + + (Default) The degree of blurring applied to the custom background image is high. The user can barely see any distinguishing features in the background. + +**See also** + +- [enableVirtualBackground](../API/class_irtcengine.html#api_enablevirtualbackground) + +## [WatermarkOptions](rtc_api_data_type.html#class_watermarkoptions) + +Configurations of the watermark image. + +```cpp +typedef struct WatermarkOptions { + bool visibleInPreview; + Rectangle positionInLandscapeMode; + Rectangle positionInPortraitMode; + + WatermarkOptions() + : visibleInPreview(true) + , positionInLandscapeMode(0, 0, 0, 0) + , positionInPortraitMode(0, 0, 0, 0) + {} + } WatermarkOptions; +``` + +### Attributes + +- visibleInPreview + + Whether the watermark image is visible in the local video preview:`true`: (Default) The watermark image is visible in the local preview.`false`: The watermark image is not visible in the local preview. + +- positionInLandscapeMode + + The area to display the watermark image in landscape mode. For details, see [Rectangle](rtc_api_data_type.html#class_rectangle).For details about the landscape mode, see [Set the Video Profile](https://docs.agora.io/en/live-streaming-4.x-preview/video_profile_windows?platform=Windows). + +- positionInPortraitMode + + The area to display the watermark image in portrait mode. For details, see [Rectangle](rtc_api_data_type.html#class_rectangle).For details about the portrait mode, see [Set the Video Profile](https://docs.agora.io/en/live-streaming-4.x-preview/video_profile_windows?platform=Windows). + +**See also** + +- [addVideoWatermark [2/2\]](../API/class_irtcengine.html#api_addvideowatermark2) +- [addVideoWatermarkEx](../API/class_irtcengineex.html#api_irtcengineex_addvideowatermarkex) \ No newline at end of file