From 421e37258093b23c1fef505f64b584eef0224f1b Mon Sep 17 00:00:00 2001 From: xianing Date: Sun, 9 Jan 2022 18:10:56 +0800 Subject: [PATCH 01/21] adapt 3.6.1 windows --- .../ScreenShare/AgoraScreenCapture.cpp | 22 +++++++++++++++++++ .../Advanced/ScreenShare/AgoraScreenCapture.h | 7 ++++++ windows/APIExample/APIExample/stdafx.h | 2 ++ windows/APIExample/install.ps1 | 2 +- 4 files changed, 32 insertions(+), 1 deletion(-) diff --git a/windows/APIExample/APIExample/Advanced/ScreenShare/AgoraScreenCapture.cpp b/windows/APIExample/APIExample/Advanced/ScreenShare/AgoraScreenCapture.cpp index e9dfdf1c6..c66406bf2 100644 --- a/windows/APIExample/APIExample/Advanced/ScreenShare/AgoraScreenCapture.cpp +++ b/windows/APIExample/APIExample/Advanced/ScreenShare/AgoraScreenCapture.cpp @@ -230,6 +230,14 @@ LRESULT CAgoraScreenCapture::OnEIDRemoteVideoStateChanged(WPARAM wParam, LPARAM return 0; } +LRESULT CAgoraScreenCapture::OnEIDScreenCaptureInfoUpdated(WPARAM wParam, LPARAM lParam) +{ + CString strInfo; + strInfo.Format(_T("OnScreenCaptureInfoUpdated state:\n%s: error:\n%u"), wParam, lParam); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + return TRUE; +} + LRESULT CAgoraScreenCapture::OnEIDLocalVideoStateChanged(WPARAM wParam, LPARAM lParam) { LOCAL_VIDEO_STREAM_STATE localVideoState =(LOCAL_VIDEO_STREAM_STATE) wParam; @@ -305,6 +313,7 @@ BEGIN_MESSAGE_MAP(CAgoraScreenCapture, CDialogEx) ON_MESSAGE(WM_MSGID(EID_USER_OFFLINE), &CAgoraScreenCapture::OnEIDUserOffline) ON_MESSAGE(WM_MSGID(EID_REMOTE_VIDEO_STATE_CHANED), &CAgoraScreenCapture::OnEIDRemoteVideoStateChanged) ON_MESSAGE(WM_MSGID(EID_LOCAL_VIDEO_STATE_CHANGED), &CAgoraScreenCapture::OnEIDLocalVideoStateChanged) + ON_MESSAGE(WM_MSGID(EID_SCREEN_CAPTURE_INFO_UPDATED), &CAgoraScreenCapture::OnEIDScreenCaptureInfoUpdated) ON_WM_SHOWWINDOW() ON_BN_CLICKED(IDC_BUTTON_UPDATEPARAM, &CAgoraScreenCapture::OnBnClickedButtonUpdateparam) @@ -637,6 +646,19 @@ void CScreenCaptureEventHandler::onRemoteVideoStateChanged(uid_t uid, REMOTE_VID } } +/** Occurs when screencapture fail to filter window + * + * + * @param ScreenCaptureInfo + */ +void CScreenCaptureEventHandler::onScreenCaptureInfoUpdated(agora::rtc::ScreenCaptureInfo& info) +{ + if (m_hMsgHanlder) + { + ::PostMessage(m_hMsgHanlder, WM_MSGID(EID_SCREEN_CAPTURE_INFO_UPDATED), (WPARAM)info.cardType, (LPARAM)info.errCode); + } +} + static BOOL IsWindowCloaked(HWND hwnd) { diff --git a/windows/APIExample/APIExample/Advanced/ScreenShare/AgoraScreenCapture.h b/windows/APIExample/APIExample/Advanced/ScreenShare/AgoraScreenCapture.h index 4d52508c3..ebe7da796 100644 --- a/windows/APIExample/APIExample/Advanced/ScreenShare/AgoraScreenCapture.h +++ b/windows/APIExample/APIExample/Advanced/ScreenShare/AgoraScreenCapture.h @@ -83,6 +83,12 @@ class CScreenCaptureEventHandler : public IRtcEngineEventHandler SDK triggers this callback. */ virtual void onRemoteVideoStateChanged(uid_t uid, REMOTE_VIDEO_STATE state, REMOTE_VIDEO_STATE_REASON reason, int elapsed) override; + /** Occurs when screencapture fail to filter window + * + * + * @param ScreenCaptureInfo + */ + virtual void onScreenCaptureInfoUpdated(agora::rtc::ScreenCaptureInfo & info) override; private: HWND m_hMsgHanlder; }; @@ -152,6 +158,7 @@ class CAgoraScreenCapture : public CDialogEx afx_msg LRESULT OnEIDUserOffline(WPARAM wParam, LPARAM lParam); afx_msg LRESULT OnEIDRemoteVideoStateChanged(WPARAM wParam, LPARAM lParam); afx_msg LRESULT OnEIDLocalVideoStateChanged(WPARAM wParam, LPARAM lParam); + afx_msg LRESULT OnEIDScreenCaptureInfoUpdated(WPARAM wParam, LPARAM lParam); protected: virtual void DoDataExchange(CDataExchange* pDX); diff --git a/windows/APIExample/APIExample/stdafx.h b/windows/APIExample/APIExample/stdafx.h index e20bab258..fbc87b285 100644 --- a/windows/APIExample/APIExample/stdafx.h +++ b/windows/APIExample/APIExample/stdafx.h @@ -88,6 +88,7 @@ using namespace agora::media; #define EID_AUDIO_DEVICE_STATE_CHANGED 0x00000019 #define EID_RTMP_STREAM_EVENT 0x00000020 +#define EID_SCREEN_CAPTURE_INFO_UPDATED 0x00000021 typedef struct _StreamPublished { char* url; int error; @@ -110,6 +111,7 @@ typedef struct _tagVideoStateStateChanged { REMOTE_VIDEO_STATE_REASON reason; }VideoStateStateChanged, *PVideoStateStateChanged; + std::string cs2utf8(CString str); CString utf82cs(std::string utf8); CString getCurrentTime(); diff --git a/windows/APIExample/install.ps1 b/windows/APIExample/install.ps1 index 848ca43bf..94391de75 100644 --- a/windows/APIExample/install.ps1 +++ b/windows/APIExample/install.ps1 @@ -1,6 +1,6 @@ $ThirdPartysrc = 'https://agora-adc-artifacts.oss-cn-beijing.aliyuncs.com/libs/ThirdParty.zip' $ThirdPartydes = 'ThirdParty.zip' -$agora_sdk = 'https://download.agora.io/sdk/release/Agora_Native_SDK_for_Windows_v3_5_0_3_FULL.zip' +$agora_sdk = 'https://download.agora.io/sdk/release/Agora_Native_SDK_for_Windows_v3_6_1_FULL.zip' $agora_des = 'Agora_Native_SDK_for_Windows.zip' $MediaPlayerSDK = 'https://download.agora.io/sdk/release/Agora_Media_Player_for_Windows_x86_32597_20200923_2306.zip' $MediaPlayerDes = 'MediaPlayerPartSave.zip' From a1bc08e236dbf329d32dfffa44d3e50b6d49fa63 Mon Sep 17 00:00:00 2001 From: xianing Date: Mon, 10 Jan 2022 15:58:49 +0800 Subject: [PATCH 02/21] fix android mpk issues --- .../examples/advanced/MediaPlayerKit.java | 12 +- .../src/main/cpp/include/AgoraBase.h | 52 +- .../src/main/cpp/include/IAgoraMediaEngine.h | 601 ++- .../src/main/cpp/include/IAgoraRtcChannel.h | 751 ++- .../src/main/cpp/include/IAgoraRtcEngine.h | 4639 +++++++++++------ .../src/main/cpp/include/IAgoraService.h | 2 +- 6 files changed, 4132 insertions(+), 1925 deletions(-) diff --git a/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/MediaPlayerKit.java b/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/MediaPlayerKit.java index b3ac96898..051bfaf9a 100644 --- a/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/MediaPlayerKit.java +++ b/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/MediaPlayerKit.java @@ -564,13 +564,15 @@ public void run() { @Override public void onDestroy() { super.onDestroy(); - /**leaveChannel and Destroy the RtcEngine instance*/ - agoraMediaPlayerKit.destroy(); if (engine != null) { - engine.leaveChannel(); + /**leaveChannel and Destroy the RtcEngine instance*/ + if (joined) { + engine.leaveChannel(); + } + agoraMediaPlayerKit.destroy(); + handler.post(RtcEngine::destroy); + engine = null; } - handler.post(RtcEngine::destroy); - engine = null; } } diff --git a/Android/APIExample/lib-player-helper/src/main/cpp/include/AgoraBase.h b/Android/APIExample/lib-player-helper/src/main/cpp/include/AgoraBase.h index c729bf7da..337390cf0 100644 --- a/Android/APIExample/lib-player-helper/src/main/cpp/include/AgoraBase.h +++ b/Android/APIExample/lib-player-helper/src/main/cpp/include/AgoraBase.h @@ -13,7 +13,9 @@ #include #if defined(_WIN32) +#ifndef WIN32_LEAN_AND_MEAN #define WIN32_LEAN_AND_MEAN +#endif #include #define AGORA_CALL __cdecl #if defined(AGORARTC_EXPORT) @@ -38,6 +40,20 @@ #define AGORA_CALL #endif +#ifdef __GNUC__ +#define AGORA_GCC_VERSION_AT_LEAST(x, y) (__GNUC__ > (x) || __GNUC__ == (x) && __GNUC_MINOR__ >= (y)) +#else +#define AGORA_GCC_VERSION_AT_LEAST(x, y) 0 +#endif + +#if AGORA_GCC_VERSION_AT_LEAST(3, 1) +#define AGORA_DEPRECATED_ATTRIBUTE __attribute__((deprecated)) +#elif defined(_MSC_VER) +#define AGORA_DEPRECATED_ATTRIBUTE +#else +#define AGORA_DEPRECATED_ATTRIBUTE +#endif + namespace agora { namespace util { @@ -220,6 +236,9 @@ enum WARN_CODE_TYPE { /** 1053: Audio Processing Module: A residual echo is detected, which may be caused by the belated scheduling of system threads or the signal overflow. */ WARN_APM_RESIDUAL_ECHO = 1053, + /** 1054: Audio Processing Module: AI NS is closed, this can be triggered by manual settings or by performance detection modules. + */ + WARN_APM_AINS_CLOSED = 1054, /// @cond WARN_ADM_WIN_CORE_NO_RECORDING_DEVICE = 1322, /// @endcond @@ -234,13 +253,13 @@ enum WARN_CODE_TYPE { * - Update the sound card drive. */ WARN_ADM_WIN_CORE_IMPROPER_CAPTURE_RELEASE = 1324, - /** 1610: The origin resolution of the remote video is beyond the range where the super-resolution algorithm can be applied. + /** 1610: The original resolution of the remote user's video is beyond the range where super resolution can be applied. */ WARN_SUPER_RESOLUTION_STREAM_OVER_LIMITATION = 1610, - /** 1611: Another user is already using the super-resolution algorithm. + /** 1611: Super resolution is already being used to boost another remote user's video. */ WARN_SUPER_RESOLUTION_USER_COUNT_OVER_LIMITATION = 1611, - /** 1612: The device does not support the super-resolution algorithm. + /** 1612: The device does not support using super resolution. */ WARN_SUPER_RESOLUTION_DEVICE_NOT_SUPPORTED = 1612, /// @cond @@ -411,7 +430,6 @@ enum ERROR_CODE_TYPE { ERR_ENCRYPTED_STREAM_NOT_ALLOWED_PUBLISH = 130, /** 134: The user account is invalid. */ ERR_INVALID_USER_ACCOUNT = 134, - /** 151: CDN related errors. Remove the original URL address and add a new one by calling the \ref agora::rtc::IRtcEngine::removePublishStreamUrl "removePublishStreamUrl" and \ref agora::rtc::IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" methods. */ ERR_PUBLISH_STREAM_CDN_ERROR = 151, @@ -436,16 +454,13 @@ enum ERROR_CODE_TYPE { * */ ERR_MODULE_NOT_FOUND = 157, - /// @cond - /** 158: The dynamical library for the super-resolution algorithm is not integrated. - * When you call the \ref agora::rtc::IRtcEngine::enableRemoteSuperResolution "enableRemoteSuperResolution" method but - * do not integrate the dynamical library for the super-resolution algorithm - * into your project, the SDK reports this error code. - */ - ERR_MODULE_SUPER_RESOLUTION_NOT_FOUND = 158, - /// @endcond - /** 160: The recording operation has been performed. + /** 160: The client is already recording audio. To start a new recording, + * call \ref agora::rtc::IRtcEngine::stopAudioRecording "stopAudioRecording" to stop + * the current recording first, and then + * call \ref agora::rtc::IRtcEngine::startAudioRecording(const AudioRecordingConfiguration&) "startAudioRecording". + * + * @since v3.4.0 */ ERR_ALREADY_IN_RECORDING = 160, @@ -708,10 +723,11 @@ enum ERROR_CODE_TYPE { ERR_ADM_NO_PLAYOUT_DEVICE = 1360, // VDM error code starts from 1500 - + /// @cond /** 1500: Video Device Module: There is no camera device. */ ERR_VDM_CAMERA_NO_DEVICE = 1500, + /// @endcond /** 1501: Video Device Module: The camera is unauthorized. */ @@ -735,6 +751,12 @@ enum ERROR_CODE_TYPE { /** 1603: Video Device Module: An error occurs in setting the video encoder. */ ERR_VCM_ENCODER_SET_ERROR = 1603, + /** 1735: (Windows only) The Windows Audio service is disabled. You need to + * either enable the Windows Audio service or restart the device. + * + * @since v3.5.0 + */ + ERR_ADM_WIN_CORE_SERVRE_SHUT_DOWN = 1735, }; /** Output log filter level. */ @@ -764,7 +786,7 @@ enum LOG_FILTER_TYPE { * @since v3.3.0 */ enum class LOG_LEVEL { - /** 0: Do not output any log. */ + /** 0x0000: Do not output any log. */ LOG_LEVEL_NONE = 0x0000, /** 0x0001: (Default) Output logs of the FATAL, ERROR, WARN and INFO level. We recommend setting your log filter as this level. */ diff --git a/Android/APIExample/lib-player-helper/src/main/cpp/include/IAgoraMediaEngine.h b/Android/APIExample/lib-player-helper/src/main/cpp/include/IAgoraMediaEngine.h index 9690d8840..c213346ac 100644 --- a/Android/APIExample/lib-player-helper/src/main/cpp/include/IAgoraMediaEngine.h +++ b/Android/APIExample/lib-player-helper/src/main/cpp/include/IAgoraMediaEngine.h @@ -1,6 +1,7 @@ #ifndef AGORA_MEDIA_ENGINE_H #define AGORA_MEDIA_ENGINE_H #include +#include "AgoraBase.h" namespace agora { namespace media { @@ -15,11 +16,64 @@ enum MEDIA_SOURCE_TYPE { AUDIO_RECORDING_SOURCE = 1, }; +/** + * The channel mode. Set in \ref agora::rtc::IRtcEngine::setAudioMixingDualMonoMode "setAudioMixingDualMonoMode". + * + * @since v3.5.1 + */ +enum AUDIO_MIXING_DUAL_MONO_MODE { + /** + * 0: Original mode. + */ + AUDIO_MIXING_DUAL_MONO_AUTO = 0, + /** + * 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_MIXING_DUAL_MONO_L = 1, + /** + * 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_MIXING_DUAL_MONO_R = 2, + /** + * 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. + */ + AUDIO_MIXING_DUAL_MONO_MIX = 3 +}; +/** + * The push position of the external audio frame. + * Set in \ref IMediaEngine::pushAudioFrame(int32_t, IAudioFrameObserver::AudioFrame*) "pushAudioFrame" + * or \ref IMediaEngine::setExternalAudioSourceVolume "setExternalAudioSourceVolume". + * + * @since v3.5.1 + */ +enum AUDIO_EXTERNAL_SOURCE_POSITION { + /** 0: The position before local playback. If you need to play the external audio frame on the local client, + * set this position. + */ + AUDIO_EXTERNAL_PLAYOUT_SOURCE = 0, + /** 1: The position after audio capture and before audio pre-processing. If you need the audio module of the SDK + * to process the external audio frame, set this position. + */ + AUDIO_EXTERNAL_RECORD_SOURCE_PRE_PROCESS = 1, + /** 2: The position after audio pre-processing and before audio encoding. If you do not need the audio module of + * the SDK to process the external audio frame, set this position. + */ + AUDIO_EXTERNAL_RECORD_SOURCE_POST_PROCESS = 2, +}; + /** * The IAudioFrameObserver class. */ class IAudioFrameObserver { public: + IAudioFrameObserver() {} + virtual ~IAudioFrameObserver() {} /** The frame type. */ enum AUDIO_FRAME_TYPE { /** 0: PCM16. */ @@ -59,43 +113,64 @@ class IAudioFrameObserver { }; public: - /** Retrieves the captured audio frame. - - @param audioFrame Pointer to AudioFrame. - @return - - true: Valid buffer in AudioFrame, and the captured audio frame is sent out. - - false: Invalid buffer in AudioFrame, and the captured audio frame is discarded. + /** Gets the captured audio frame. + * + * @note To ensure that the captured audio frame has the expected format, + * Agora recommends that you + * call \ref agora::rtc::IRtcEngine::setRecordingAudioFrameParameters "setRecordingAudioFrameParameters" + * after calling \ref IMediaEngine::registerAudioFrameObserver "registerAudioFrameObserver" to + * set the audio capturing format. + * + * @param audioFrame Pointer to AudioFrame. + * @return + * - true: Valid buffer in AudioFrame, and the captured audio frame is sent out. + * - false: Invalid buffer in AudioFrame, and the captured audio frame is discarded. */ virtual bool onRecordAudioFrame(AudioFrame& audioFrame) = 0; - /** Retrieves the audio playback frame for getting the audio. - - @param audioFrame Pointer to AudioFrame. - @return - - true: Valid buffer in AudioFrame, and the audio playback frame is sent out. - - false: Invalid buffer in AudioFrame, and the audio playback frame is discarded. + /** Gets the audio playback frame for getting the audio. + * + * @note To ensure that the audio playback frame has the expected format, Agora + * recommends that you call \ref agora::rtc::IRtcEngine::setPlaybackAudioFrameParameters "setPlaybackAudioFrameParameters" + * after calling \ref IMediaEngine::registerAudioFrameObserver "registerAudioFrameObserver" to + * set the audio playback format. + * + * @param audioFrame Pointer to AudioFrame. + * @return + * - true: Valid buffer in AudioFrame, and the audio playback frame is sent out. + * - false: Invalid buffer in AudioFrame, and the audio playback frame is discarded. */ virtual bool onPlaybackAudioFrame(AudioFrame& audioFrame) = 0; - /** Retrieves the mixed captured and playback audio frame. - - - @note This callback only returns the single-channel data. - - @param audioFrame Pointer to AudioFrame. - @return - - true: Valid buffer in AudioFrame and the mixed captured and playback audio frame is sent out. - - false: Invalid buffer in AudioFrame and the mixed captured and playback audio frame is discarded. + /** Gets the mixed captured and playback audio frame. + * + * @note + * - This callback only returns the single-channel data. + * - To ensure that the mixed captured and playback audio frame has the + * expected format, Agora recommends that you call + * \ref agora::rtc::IRtcEngine::setMixedAudioFrameParameters "setMixedAudioFrameParameters" + * after calling \ref IMediaEngine::registerAudioFrameObserver "registerAudioFrameObserver" to + * set the mixed audio format. + * + * @param audioFrame Pointer to AudioFrame. + * @return + * - true: Valid buffer in AudioFrame and the mixed captured and playback audio frame is sent out. + * - false: Invalid buffer in AudioFrame and the mixed captured and playback audio frame is discarded. */ virtual bool onMixedAudioFrame(AudioFrame& audioFrame) = 0; - /** Retrieves the audio frame of a specified user before mixing. - - The SDK triggers this callback if isMultipleChannelFrameWanted returns false. - - @param uid The user ID - @param audioFrame Pointer to AudioFrame. - @return - - true: Valid buffer in AudioFrame, and the mixed captured and playback audio frame is sent out. - - false: Invalid buffer in AudioFrame, and the mixed captured and playback audio frame is discarded. - */ + /** Gets the audio frame of a specified user before mixing. + * + * The SDK triggers this callback if \ref IAudioFrameObserver::isMultipleChannelFrameWanted "isMultipleChannelFrameWanted" returns false. + * + * @note To ensure that the audio playback frame has the expected format, Agora + * recommends that you call \ref agora::rtc::IRtcEngine::setPlaybackAudioFrameParameters "setPlaybackAudioFrameParameters" + * after calling \ref IMediaEngine::registerAudioFrameObserver "registerAudioFrameObserver" to + * set the audio playback format. + * + * @param uid The user ID + * @param audioFrame Pointer to AudioFrame. + * @return + * - true: Valid buffer in AudioFrame, and the mixed captured and playback audio frame is sent out. + * - false: Invalid buffer in AudioFrame, and the mixed captured and playback audio frame is discarded. + */ virtual bool onPlaybackAudioFrameBeforeMixing(unsigned int uid, AudioFrame& audioFrame) = 0; /** Determines whether to receive audio data from multiple channels. @@ -121,18 +196,23 @@ class IAudioFrameObserver { virtual bool isMultipleChannelFrameWanted() { return false; } /** Gets the before-mixing playback audio frame from multiple channels. - - After you successfully register the audio frame observer, if you set the return - value of \ref IAudioFrameObserver::isMultipleChannelFrameWanted "isMultipleChannelFrameWanted" as true, the SDK triggers this callback each - time it receives a before-mixing audio frame from any of the channel. - - @param channelId The channel ID of this audio frame. - @param uid The ID of the user sending this audio frame. - @param audioFrame The pointer to AudioFrame. - @return - - `true`: The data in AudioFrame is valid, and send this audio frame. - - `false`: The data in AudioFrame in invalid, and do not send this audio frame. - */ + * + * After you successfully register the audio frame observer, if you set the return + * value of \ref IAudioFrameObserver::isMultipleChannelFrameWanted "isMultipleChannelFrameWanted" as true, the SDK triggers this callback each + * time it receives a before-mixing audio frame from any of the channel. + * + * @note To ensure that the audio playback frame has the expected format, Agora + * recommends that you call \ref agora::rtc::IRtcEngine::setPlaybackAudioFrameParameters "setPlaybackAudioFrameParameters" + * after calling \ref IMediaEngine::registerAudioFrameObserver "registerAudioFrameObserver" to + * set the audio playback format. + * + * @param channelId The channel ID of this audio frame. + * @param uid The ID of the user sending this audio frame. + * @param audioFrame The pointer to AudioFrame. + * @return + * - `true`: The data in AudioFrame is valid, and send this audio frame. + * - `false`: The data in AudioFrame in invalid, and do not send this audio frame. + */ virtual bool onPlaybackAudioFrameBeforeMixingEx(const char* channelId, unsigned int uid, AudioFrame& audioFrame) { return true; } }; @@ -141,14 +221,16 @@ class IAudioFrameObserver { */ class IVideoFrameObserver { public: + IVideoFrameObserver() {} + virtual ~IVideoFrameObserver() {} /** The video frame type. */ enum VIDEO_FRAME_TYPE { /** - * 0: YUV420 + * 0: (Default) YUV 420 */ FRAME_TYPE_YUV420 = 0, // YUV 420 format /** - * 1: YUV422 + * 1: YUV 422 */ FRAME_TYPE_YUV422 = 1, // YUV 422 format /** @@ -173,7 +255,7 @@ class IVideoFrameObserver { */ POSITION_PRE_ENCODER = 1 << 2, }; - /** Video frame information. The video data format is YUV420. The buffer provides a pointer to a pointer. The interface cannot modify the pointer of the buffer, but can modify the content of the buffer only. + /** Video frame information. The video data format is YUV 420. The buffer provides a pointer to a pointer. The interface cannot modify the pointer of the buffer, but can modify the content of the buffer only. */ struct VideoFrame { VIDEO_FRAME_TYPE type; @@ -183,32 +265,37 @@ class IVideoFrameObserver { /** Video pixel height. */ int height; // height of video frame - /** Line span of the Y buffer within the YUV data. + /** + * For YUV data, the line span of the Y buffer; for RGBA data, the total data length. */ int yStride; // stride of Y data buffer - /** Line span of the U buffer within the YUV data. + /** + * For YUV data, the line span of the U buffer; for RGBA data, the value is 0. */ int uStride; // stride of U data buffer - /** Line span of the V buffer within the YUV data. + /** + * For YUV data, the line span of the V buffer; for RGBA data, the value is 0. */ int vStride; // stride of V data buffer - /** Pointer to the Y buffer pointer within the YUV data. + /** + * For YUV data, the pointer to the Y buffer; for RGBA data, the data buffer. */ void* yBuffer; // Y data buffer - /** Pointer to the U buffer pointer within the YUV data. + /** + * For YUV data, the pointer to the U buffer; for RGBA data, the value is 0. */ void* uBuffer; // U data buffer - /** Pointer to the V buffer pointer within the YUV data. + /** + * For YUV data, the pointer to the V buffer; for RGBA data, the value is 0. */ void* vBuffer; // V data buffer - /** Set the rotation of this frame before rendering the video. Supports 0, 90, 180, 270 degrees clockwise. + /** The clockwise rotation angle of the video frame. The supported values are 0, 90, 180, or 270 degrees. */ int rotation; // rotation of this frame (0, 90, 180, 270) - /** The timestamp (ms) of the external audio frame. It is mandatory. You can use this parameter for the following purposes: - - Restore the order of the captured audio frame. - - Synchronize audio and video frames in video-related scenarios, including scenarios where external video sources are used. - @note This timestamp is for rendering the video stream, and not for capturing the video stream. - */ + /** + * The Unix timestamp (ms) when the video frame is rendered. This timestamp can be used to guide the rendering of + * the video frame. This parameter is required. + */ int64_t renderTimeMs; int avsync_type; }; @@ -226,9 +313,9 @@ class IVideoFrameObserver { * - The video data that this callback gets has not been pre-processed, without the watermark, the cropped content, the rotation, and the image enhancement. * * @param videoFrame Pointer to VideoFrame. - * @return Whether or not to ignore the current video frame if the pre-processing fails: - * - true: Do not ignore. - * - false: Ignore the current video frame, and do not send it back to the SDK. + * @return + * - true: Sets the SDK to receive the video frame. + * - false: Sets the SDK to discard the video frame. */ virtual bool onCaptureVideoFrame(VideoFrame& videoFrame) = 0; /** @since v3.0.0 @@ -245,15 +332,18 @@ class IVideoFrameObserver { * - This callback does not support sending processed RGBA video data back to the SDK. * * @param videoFrame A pointer to VideoFrame - * @return Whether to ignore the current video frame if the processing fails: - * - true: Do not ignore the current video frame. - * - false: Ignore the current video frame, and do not send it back to the SDK. + * @return + * - true: Sets the SDK to receive the video frame. + * - false: Sets the SDK to discard the video frame. */ virtual bool onPreEncodeVideoFrame(VideoFrame& videoFrame) { return true; } /** Occurs each time the SDK receives a video frame sent by the remote user. * - * After you successfully register the video frame observer and isMultipleChannelFrameWanted return false, the SDK triggers this callback each time a video frame is received. - * In this callback, you can get the video data sent by the remote user. You can then post-process the data according to your scenarios. + * After you successfully register the video frame observer and + * \ref IVideoFrameObserver::isMultipleChannelFrameWanted "isMultipleChannelFrameWanted" + * return false, the SDK triggers this callback each time a video frame is received. + * In this callback, you can get the video data sent by the remote user. You can then + * post-process the data according to your scenarios. * * After post-processing, you can send the processed data back to the SDK by setting the `videoFrame` parameter in this callback. * @@ -262,67 +352,73 @@ class IVideoFrameObserver { * * @param uid ID of the remote user who sends the current video frame. * @param videoFrame Pointer to VideoFrame. - * @return Whether or not to ignore the current video frame if the post-processing fails: - * - true: Do not ignore. - * - false: Ignore the current video frame, and do not send it back to the SDK. + * @return + * - true: Sets the SDK to receive the video frame. + * - false: Sets the SDK to discard the video frame. */ virtual bool onRenderVideoFrame(unsigned int uid, VideoFrame& videoFrame) = 0; /** Occurs each time the SDK receives a video frame and prompts you to set the video format. * - * YUV420 is the default video format. If you want to receive other video formats, register this callback in the IVideoFrameObserver class. + * YUV 420 is the default video format. If you want to receive other video formats, register this callback in the IVideoFrameObserver class. * * After you successfully register the video frame observer, the SDK triggers this callback each time it receives a video frame. * You need to set your preferred video data in the return value of this callback. * * @return Sets the video format: #VIDEO_FRAME_TYPE - * - #FRAME_TYPE_YUV420 (0): (Default) YUV420. - * - #FRAME_TYPE_RGBA (2): RGBA */ virtual VIDEO_FRAME_TYPE getVideoFormatPreference() { return FRAME_TYPE_YUV420; } - /** Occurs each time the SDK receives a video frame and prompts you whether or not to rotate the captured video according to the rotation member in the VideoFrame class. + /** Occurs each time the SDK receives a video frame and prompts you whether to + * rotate the raw video frame according to the rotation member in the VideoFrame class. * - * The SDK does not rotate the captured video by default. If you want to rotate the captured video according to the rotation member in the VideoFrame class, register this callback in the IVideoFrameObserver class. + * The SDK does not rotate the raw video frame by default. If you want to receive + * the raw video frame rotated according to the rotation member in the VideoFrame + * class, register this callback in the IVideoFrameObserver class. * - * After you successfully register the video frame observer, the SDK triggers this callback each time it receives a video frame. You need to set whether or not to rotate the video frame in the return value of this callback. + * After you successfully register the video frame observer, the SDK triggers this + * callback each time it receives a video frame. You need to set whether to rotate + * the raw video frame in the return value of this callback. * - * @note - * This callback applies to RGBA video data only. + * @note This callback applies to the video frame in the YUV 420 and RGBA formats only. * - * @return Sets whether or not to rotate the captured video: + * @return Sets whether to rotate the raw video frame: * - true: Rotate. - * - false: （Default) Do not rotate. + * - false: (Default) Do not rotate. */ virtual bool getRotationApplied() { return false; } - /** Occurs each time the SDK receives a video frame and prompts you whether or not to mirror the captured video. + /** Occurs each time the SDK receives a video frame and prompts you whether to mirror the raw video frame. * - * The SDK does not mirror the captured video by default. Register this callback in the IVideoFrameObserver class if you want to mirror the captured video. + * The SDK does not mirror the raw video frame by default. If you want to receive the raw video frame mirrored, register this callback in the IVideoFrameObserver class. * * After you successfully register the video frame observer, the SDK triggers this callback each time a video frame is received. - * You need to set whether or not to mirror the captured video in the return value of this callback. + * You need to set whether to mirror the raw video frame in the return value of this callback. * - * @note - * This callback applies to RGBA video data only. + * @note This callback applies to the video frame in the YUV 420 and RGBA formats only. * - * @return Sets whether or not to mirror the captured video: + * @return Sets whether to mirror the raw video frame: * - true: Mirror. * - false: (Default) Do not mirror. */ virtual bool getMirrorApplied() { return false; } - /** @since v3.0.0 - - Sets whether to output the acquired video frame smoothly. - - If you want the video frames acquired from \ref IVideoFrameObserver::onRenderVideoFrame "onRenderVideoFrame" to be more evenly spaced, you can register the `getSmoothRenderingEnabled` callback in the `IVideoFrameObserver` class and set its return value as `true`. - - @note - - Register this callback before joining a channel. - - This callback applies to scenarios where the acquired video frame is self-rendered after being processed, not to scenarios where the video frame is sent back to the SDK after being processed. - - @return Set whether or not to smooth the video frames: - - true: Smooth the video frame. - - false: (Default) Do not smooth. + /** + * Sets whether to output the acquired video frame smoothly. + * + * @since v3.0.0 + * + * @deprecated As of v3.2.0, this callback function is deprecated, and the SDK + * smooths the video frames output by `onRenderVideoFrame` and `onRenderVideoFrameEx` by default. + * + * If you want the video frames acquired from `onRenderVideoFrame` + * or `onRenderVideoFrameEx` to be more evenly spaced, you can register the `getSmoothRenderingEnabled` callback in the `IVideoFrameObserver` class and set its return value as `true`. + * + * @note + * - Register this callback before joining a channel. + * - This callback applies to scenarios where the acquired video frame is self-rendered after being processed, not to scenarios where the video frame is sent back to the SDK after being processed. + * + * @return Set whether to smooth the video frames: + * - true: Smooth the video frame. + * - false: (Default) Do not smooth. */ - virtual bool getSmoothRenderingEnabled() { return false; } + virtual bool getSmoothRenderingEnabled() AGORA_DEPRECATED_ATTRIBUTE { return false; } /** * Sets the frame position for the video observer. * @since v3.0.1 @@ -334,7 +430,7 @@ class IVideoFrameObserver { * - `POSITION_PRE_ENCODER(1 << 2)`: The position before encoding the video data, which corresponds to the \ref onPreEncodeVideoFrame "onPreEncodeVideoFrame" callback. * * @note - * - Use '|' (the OR operator) to observe multiple frame positions. + * - To observe multiple frame positions, use '|' (the OR operator). * - This callback observes `POSITION_POST_CAPTURER(1 << 0)` and `POSITION_PRE_RENDERER(1 << 1)` by default. * - To conserve the system consumption, you can reduce the number of frame positions that you want to observe. * @@ -345,6 +441,8 @@ class IVideoFrameObserver { /** Determines whether to receive video data from multiple channels. + @since v3.0.1 + After you register the video frame observer, the SDK triggers this callback every time it captures a video frame. @@ -364,22 +462,22 @@ class IVideoFrameObserver { virtual bool isMultipleChannelFrameWanted() { return false; } /** Gets the video frame from multiple channels. - - After you successfully register the video frame observer, if you set the return value of - \ref IVideoFrameObserver::isMultipleChannelFrameWanted "isMultipleChannelFrameWanted" as true, the SDK triggers this callback each time it receives a video frame - from any of the channel. - - You can process the video data retrieved from this callback according to your scenario, and send the - processed data back to the SDK using the `videoFrame` parameter in this callback. - - @note This callback does not support sending RGBA video data back to the SDK. - - @param channelId The channel ID of this video frame. - @param uid The ID of the user sending this video frame. - @param videoFrame The pointer to VideoFrame. - @return Whether to send this video frame to the SDK if post-processing fails: - - `true`: Send this video frame. - - `false`: Do not send this video frame. + * + * After you successfully register the video frame observer, if you set the return value of + * \ref IVideoFrameObserver::isMultipleChannelFrameWanted "isMultipleChannelFrameWanted" as true, the SDK triggers this callback each time it receives a video frame + * from any of the channel. + * + * You can process the video data retrieved from this callback according to your scenario, and send the + * processed data back to the SDK using the `videoFrame` parameter in this callback. + * + * @note This callback does not support sending RGBA video data back to the SDK. + * + * @param channelId The channel ID of this video frame. + * @param uid The ID of the user sending this video frame. + * @param videoFrame The pointer to VideoFrame. + * @return + * - true: Sets the SDK to receive the video frame. + * - false: Sets the SDK to discard the video frame. */ virtual bool onRenderVideoFrameEx(const char* channelId, unsigned int uid, VideoFrame& videoFrame) { return true; } }; @@ -432,26 +530,26 @@ class IVideoFrame { - < 0: Failure. */ virtual int convertFrame(VIDEO_TYPE dst_video_type, int dst_sample_size, unsigned char* dst_frame) const = 0; - /** Retrieves the specified component in the YUV space. + /** Gets the specified component in the YUV space. @param type Component type: #PLANE_TYPE */ virtual int allocated_size(PLANE_TYPE type) const = 0; - /** Retrieves the stride of the specified component in the YUV space. + /** Gets the stride of the specified component in the YUV space. @param type Component type: #PLANE_TYPE */ virtual int stride(PLANE_TYPE type) const = 0; - /** Retrieves the width of the frame. + /** Gets the width of the frame. */ virtual int width() const = 0; - /** Retrieves the height of the frame. + /** Gets the height of the frame. */ virtual int height() const = 0; - /** Retrieves the timestamp (ms) of the frame. + /** Gets the timestamp (ms) of the frame. */ virtual unsigned int timestamp() const = 0; - /** Retrieves the render time (ms). + /** Gets the render time (ms). */ virtual int64_t render_time_ms() const = 0; /** Checks if a plane is of zero size. @@ -519,12 +617,19 @@ class IExternalVideoRenderFactory { /** The external video frame. */ struct ExternalVideoFrame { - /** The video buffer type. + /** + * The data type of the video frame. + * + * @since v3.5.0 */ enum VIDEO_BUFFER_TYPE { - /** 1: The video buffer in the format of raw data. + /** 1: The data type is raw data. */ VIDEO_BUFFER_RAW_DATA = 1, + /** + * 2: The data type is the pixel. + */ + VIDEO_BUFFER_PIXEL_BUFFER = 2 }; /** The video pixel format. @@ -597,56 +702,143 @@ struct ExternalVideoFrame { ExternalVideoFrame() : cropLeft(0), cropTop(0), cropRight(0), cropBottom(0), rotation(0) {} }; +/** + * The video frame type. + * + * @since v3.4.5 + */ +enum CODEC_VIDEO_FRAME_TYPE { + /** + * 0: (Default) A black frame + */ + CODEC_VIDEO_FRAME_TYPE_BLANK_FRAME = 0, + /** + * 3: The keyframe + */ + CODEC_VIDEO_FRAME_TYPE_KEY_FRAME = 3, + /** + * 4: The delta frame + */ + CODEC_VIDEO_FRAME_TYPE_DELTA_FRAME = 4, + /** + * 5: The B-frame + */ + CODEC_VIDEO_FRAME_TYPE_B_FRAME = 5, + /** + * Unknown frame + */ + CODEC_VIDEO_FRAME_TYPE_UNKNOW +}; -enum CODEC_VIDEO_FRAME_TYPE { CODEC_VIDEO_FRAME_TYPE_BLANK_FRAME = 0, CODEC_VIDEO_FRAME_TYPE_KEY_FRAME = 3, CODEC_VIDEO_FRAME_TYPE_DELTA_FRAME = 4, CODEC_VIDEO_FRAME_TYPE_B_FRAME = 5, CODEC_VIDEO_FRAME_TYPE_UNKNOW }; - -enum VIDEO_ROTATION { VIDEO_ROTATION_0 = 0, VIDEO_ROTATION_90 = 90, VIDEO_ROTATION_180 = 180, VIDEO_ROTATION_270 = 270 }; +/** + * The clockwise rotation angle of the video frame. + * + * @since v3.4.5 + */ +enum VIDEO_ROTATION { + /** + * 0: 0 degree + */ + VIDEO_ROTATION_0 = 0, + /** + * 90: 90 degrees + */ + VIDEO_ROTATION_90 = 90, + /** + * 180: 180 degrees + */ + VIDEO_ROTATION_180 = 180, + /** + * 270: 270 degrees + */ + VIDEO_ROTATION_270 = 270 +}; -/** Video codec types */ +/** + * The video codec type. + * + * @since v3.4.5 + */ enum VIDEO_CODEC_TYPE { - /** Standard VP8 */ + /** 1: VP8 */ VIDEO_CODEC_VP8 = 1, - /** Standard H264 */ + /** 2: (Default) H.264 */ VIDEO_CODEC_H264 = 2, - /** Enhanced VP8 */ + /** 3: Enhanced VP8 */ VIDEO_CODEC_EVP = 3, - /** Enhanced H264 */ + /** 4: Enhanced H.264 */ VIDEO_CODEC_E264 = 4, }; -/** * The struct of VideoEncodedFrame. */ +/** + * The VideoEncodedFrame struct. + * + * @since v3.4.5 + */ struct VideoEncodedFrame { VideoEncodedFrame() : codecType(VIDEO_CODEC_H264), width(0), height(0), buffer(nullptr), length(0), frameType(CODEC_VIDEO_FRAME_TYPE_BLANK_FRAME), rotation(VIDEO_ROTATION_0), renderTimeMs(0) {} /** - * The video codec: #VIDEO_CODEC_TYPE. + * The video codec type. See #VIDEO_CODEC_TYPE. */ VIDEO_CODEC_TYPE codecType; - /** * The width (px) of the video. */ + /** + * The width (px) of the video. + */ int width; - /** * The height (px) of the video. */ + /** + * The height (px) of the video. + */ int height; - /** * The buffer of video encoded frame */ + /** + * The video buffer, which is in the `DirectByteBuffer` data type. + */ const uint8_t* buffer; - /** * The Length of video encoded frame buffer. */ + /** + * The length (in bytes) of the video buffer. + */ unsigned int length; - /** * The frame type of the encoded video frame: #VIDEO_FRAME_TYPE. */ + /** + * The video frame type. See #CODEC_VIDEO_FRAME_TYPE. + */ CODEC_VIDEO_FRAME_TYPE frameType; - /** * The rotation information of the encoded video frame: #VIDEO_ROTATION. */ + /** + * The clockwise rotation angle of the video frame. See #VIDEO_ROTATION. + */ VIDEO_ROTATION rotation; - /** * The timestamp for rendering the video. */ + /** + * The Unix timestamp (ms) when the video frame is rendered. This timestamp + * can be used to guide the rendering of the video frame. This parameter is required. + */ int64_t renderTimeMs; }; - -class IVideoEncodedFrameReceiver { +/** + * The IVideoEncodedFrameObserver class. + * + * @since v3.4.5 + */ +class IVideoEncodedFrameObserver { public: /** - * Occurs each time the SDK receives an encoded video image. - * @param videoEncodedFrame The information of the encoded video frame: VideoEncodedFrame. + * Gets the local encoded video frame. + * + * @since v3.4.5 * + * After you successfully register the local encoded video frame observer, + * the SDK triggers this callback each time a video frame is received. You + * can get the local encoded video frame in `videoEncodedFrame` and then + * process the video data according to your scenario. After processing, + * you can use `videoEncodedFrame` to pass the processed video data back to + * the SDK. + * + * @param videoEncodedFrame The local encoded video frame. See VideoEncodedFrame. + * + * @return + * - true: Sets the SDK to receive the video frame. + * - false: Sets the SDK to discard the video frame. */ - virtual bool OnVideoEncodedFrameReceived(const VideoEncodedFrame& videoEncodedFrame) = 0; + virtual bool onVideoEncodedFrame(const VideoEncodedFrame& videoEncodedFrame) = 0; - virtual ~IVideoEncodedFrameReceiver() {} + virtual ~IVideoEncodedFrameObserver() {} }; class IMediaEngine { @@ -687,30 +879,78 @@ class IMediaEngine { virtual int registerVideoFrameObserver(IVideoFrameObserver* observer) = 0; /** **DEPRECATED** */ virtual int registerVideoRenderFactory(IExternalVideoRenderFactory* factory) = 0; - /** **DEPRECATED** Use \ref agora::media::IMediaEngine::pushAudioFrame(IAudioFrameObserver::AudioFrame* frame) "pushAudioFrame(IAudioFrameObserver::AudioFrame* frame)" instead. - - Pushes the external audio frame. - - @param type Type of audio capture device: #MEDIA_SOURCE_TYPE. - @param frame Audio frame pointer: \ref IAudioFrameObserver::AudioFrame "AudioFrame". - @param wrap Whether to use the placeholder. We recommend setting the default value. - - true: Use. - - false: (Default) Not use. - - @return - - 0: Success. - - < 0: Failure. + /** + * Pushes the external audio frame. + * + * @deprecated This method is deprecated. Use \ref IMediaEngine::pushAudioFrame(int32_t,IAudioFrameObserver::AudioFrame*) "pushAudioFrame" [3/3] instead. + * + * @param type Type of audio capture device: #MEDIA_SOURCE_TYPE. + * @param frame Audio frame pointer: \ref IAudioFrameObserver::AudioFrame "AudioFrame". + * @param wrap Whether to use the placeholder. We recommend setting the default value. + * - true: Use. + * - false: (Default) Not use. + * + * @return + * - 0: Success. + * - < 0: Failure. */ - virtual int pushAudioFrame(MEDIA_SOURCE_TYPE type, IAudioFrameObserver::AudioFrame* frame, bool wrap) = 0; + virtual int pushAudioFrame(MEDIA_SOURCE_TYPE type, IAudioFrameObserver::AudioFrame* frame, bool wrap) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Pushes the external audio frame. + * + * @deprecated This method is deprecated. Use \ref IMediaEngine::pushAudioFrame(int32_t,IAudioFrameObserver::AudioFrame*) "pushAudioFrame" [3/3] instead. + * + * @param frame Pointer to the audio frame: \ref IAudioFrameObserver::AudioFrame "AudioFrame". + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int pushAudioFrame(IAudioFrameObserver::AudioFrame* frame) AGORA_DEPRECATED_ATTRIBUTE = 0; - @param frame Pointer to the audio frame: \ref IAudioFrameObserver::AudioFrame "AudioFrame". - - @return - - 0: Success. - - < 0: Failure. + /** + * Pushes the external audio frame to a specified position. + * + * @since v3.5.1 + * + * According to your needs, you can push the external audio frame to one of three positions: after audio capture, + * before audio encoding, or before local playback. You can call this method multiple times to push one audio frame + * to multiple positions or multiple audio frames to different positions. For example, in the KTV scenario, you can + * push the singing voice to after audio capture, so that the singing voice can be processed by the SDK audio module + * and you can obtain a high-quality audio experience; you can also push the accompaniment to before audio encoding, + * so that the accompaniment is not affected by the audio module of the SDK. + * + * @note Call this method after joining a channel. + * + * @param sourcePos The push position of the external audio frame. See #AUDIO_EXTERNAL_SOURCE_POSITION. + * @param frame The external audio frame. See AudioFrame. The value range of the audio frame length (ms) is [10,60]. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `-2 (ERR_INVALID_ARGUMENT)`: The parameter is invalid. + * - `-12 (ERR_TOO_OFTEN)`: The call frequency is too high, causing the internal buffer to overflow. Call this method again after 30-50 ms. */ - virtual int pushAudioFrame(IAudioFrameObserver::AudioFrame* frame) = 0; + virtual int pushAudioFrame(int32_t sourcePos, IAudioFrameObserver::AudioFrame* frame) = 0; + /** + * Sets the volume of the external audio frame in the specified position. + * + * @since v3.5.1 + * + * You can call this method multiple times to set the volume of external audio frames in different positions. + * The volume setting takes effect for all external audio frames that are pushed to the specified position. + * + * @note Call this method after joining a channel. + * + * @param sourcePos The push position of the external audio frame. See #AUDIO_EXTERNAL_SOURCE_POSITION. + * @param volume The volume of the external audio frame. The value range is [0,100]. The default value is 100, which + * represents the original value. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `-2 (ERR_INVALID_ARGUMENT)`: The parameter is invalid. + */ + virtual int setExternalAudioSourceVolume(int32_t sourcePos, int32_t volume) = 0; /** Pulls the remote audio data. * * Before calling this method, call the @@ -722,8 +962,9 @@ class IMediaEngine { * audio data for playback. * * @note + * - Ensure that you call this method after joining a channel. * - Once you call the \ref agora::media::IMediaEngine::pullAudioFrame - * "pullAudioFrame" method successfully, the app will not retrieve any audio + * "pullAudioFrame" method successfully, the app will not get any audio * data from the * \ref agora::media::IAudioFrameObserver::onPlaybackAudioFrame * "onPlaybackAudioFrame" callback. @@ -774,8 +1015,28 @@ class IMediaEngine { - < 0: Failure. */ virtual int pushVideoFrame(ExternalVideoFrame* frame) = 0; - - virtual int registerVideoEncodedFrameReceiver(IVideoEncodedFrameReceiver* receiver) = 0; + /** + * Registers a local encoded video frame observer. + * + * @since v3.4.5 + * + * After you successfully register the local encoded video frame observer, + * the SDK triggers the callbacks that you have implemented in the + * IVideoEncodedFrameObserver class each time a video frame is received. + * + * @note + * - Ensure that you call this method before joining a channel. + * - The width and height of the video obtained through the observer may + * change due to poor network conditions and user-adjusted resolution. + * + * @param observer The local encoded video frame observer. See IVideoEncodedFrameObserver. + * If null is passed, the observer registration is canceled. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int registerVideoEncodedFrameObserver(IVideoEncodedFrameObserver* observer) = 0; }; } // namespace media diff --git a/Android/APIExample/lib-player-helper/src/main/cpp/include/IAgoraRtcChannel.h b/Android/APIExample/lib-player-helper/src/main/cpp/include/IAgoraRtcChannel.h index 5c5a6fafe..9a0ec7193 100644 --- a/Android/APIExample/lib-player-helper/src/main/cpp/include/IAgoraRtcChannel.h +++ b/Android/APIExample/lib-player-helper/src/main/cpp/include/IAgoraRtcChannel.h @@ -69,7 +69,7 @@ class IChannelEventHandler { This callback notifies the application that a user leaves the channel when the application calls the \ref agora::rtc::IChannel::leaveChannel "leaveChannel" method. - The application retrieves information, such as the call duration and statistics. + The application gets information, such as the call duration and statistics. @param rtcChannel IChannel @param stats The call statistics: RtcStats. @@ -181,13 +181,17 @@ class IChannelEventHandler { (void)stats; } /** Reports the last mile network quality of each user in the channel once every two seconds. - - Last mile refers to the connection between the local device and Agora's edge server. This callback reports once every two seconds the last mile network conditions of each user in the channel. If a channel includes multiple users, the SDK triggers this callback as many times. - - @param rtcChannel IChannel - @param uid User ID. The network quality of the user with this @p uid is reported. If @p uid is 0, the local network quality is reported. - @param txQuality Uplink transmission quality rating of the user in terms of the transmission bitrate, packet loss rate, average RTT (Round-Trip Time), and jitter of the uplink network. @p txQuality is a quality rating helping you understand how well the current uplink network conditions can support the selected VideoEncoderConfiguration. 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 may be inadequate for resolutions higher than 1280 * 720. See #QUALITY_TYPE. - @param rxQuality Downlink network quality rating of the user in terms of the packet loss rate, average RTT, and jitter of the downlink network. See #QUALITY_TYPE. + * + * Last mile refers to the connection between the local device and Agora's edge server. This callback reports once every + * two seconds the last mile network conditions of each user in the channel. If a channel includes multiple users, the + * SDK triggers this callback as many times. + * + * @note `txQuality` is `UNKNOWN` when the user is not sending a stream; `rxQuality` is `UNKNOWN` when the user is not receiving a stream. + * + * @param rtcChannel IChannel + * @param uid User ID. The network quality of the user with this @p uid is reported. If @p uid is 0, the local network quality is reported. + * @param txQuality Uplink transmission quality rating of the user in terms of the transmission bitrate, packet loss rate, average RTT (Round-Trip Time), and jitter of the uplink network. @p txQuality is a quality rating helping you understand how well the current uplink network conditions can support the selected VideoEncoderConfiguration. 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 may be inadequate for resolutions higher than 1280 * 720. See #QUALITY_TYPE. + * @param rxQuality Downlink network quality rating of the user in terms of the packet loss rate, average RTT, and jitter of the downlink network. See #QUALITY_TYPE. */ virtual void onNetworkQuality(IChannel* rtcChannel, uid_t uid, int txQuality, int rxQuality) { (void)rtcChannel; @@ -223,18 +227,19 @@ class IChannelEventHandler { (void)stats; } /** Occurs when the remote audio state changes. - - This callback indicates the state change of the remote audio stream. - @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. - - @param rtcChannel IChannel - @param uid ID of the remote user whose audio state changes. - @param state State of the remote audio. See #REMOTE_AUDIO_STATE. - @param reason The reason of the remote audio state change. - See #REMOTE_AUDIO_STATE_REASON. - @param elapsed Time elapsed (ms) from the local user calling the - \ref IChannel::joinChannel "joinChannel" method until the SDK - triggers this callback. + * + * This callback indicates the state change of the remote audio stream. + * + * @note This callback can be inaccurate when the number of users (in the `COMMUNICATION` profile) + * or hosts (in the `LIVE_BROADCASTING` profile) in a channel exceeds 17. + * + * @param rtcChannel IChannel + * @param uid ID of the remote user whose audio state changes. + * @param state State of the remote audio. See #REMOTE_AUDIO_STATE. + * @param reason The reason of the remote audio state change. See #REMOTE_AUDIO_STATE_REASON. + * @param elapsed Time elapsed (ms) from the local user calling the + * \ref IChannel::joinChannel "joinChannel" method until the SDK + * triggers this callback. */ virtual void onRemoteAudioStateChanged(IChannel* rtcChannel, uid_t uid, REMOTE_AUDIO_STATE state, REMOTE_AUDIO_STATE_REASON reason, int elapsed) { (void)rtcChannel; @@ -319,21 +324,23 @@ class IChannelEventHandler { (void)newState; (void)elapseSinceLastState; } - /// @cond - /** Reports whether the super-resolution algorithm is enabled. + + /** Reports whether the super resolution feature is successfully enabled. (beta feature) * - * @since v3.2.0 + * @since v3.5.1 * - * After calling \ref IRtcChannel::enableRemoteSuperResolution "enableRemoteSuperResolution", the SDK triggers this - * callback to report whether the super-resolution algorithm is successfully enabled. If not successfully enabled, - * you can use reason for troubleshooting. + * After calling \ref IChannel::enableRemoteSuperResolution "enableRemoteSuperResolution", the SDK triggers this + * callback to report whether super resolution is successfully enabled. If it is not successfully enabled, + * use `reason` for troubleshooting. * * @param rtcChannel IChannel - * @param uid The ID of the remote user. - * @param enabled Whether the super-resolution algorithm is successfully enabled: - * - true: The super-resolution algorithm is successfully enabled. - * - false: The super-resolution algorithm is not successfully enabled. - * @param reason The reason why the super-resolution algorithm is not successfully enabled. See #SUPER_RESOLUTION_STATE_REASON. + * @param uid The user ID of the remote user. + * @param enabled Whether super resolution is successfully enabled: + * - true: Super resolution is successfully enabled. + * - false: Super resolution is not successfully enabled. + * @param reason The reason why super resolution is not successfully enabled or the message + * that confirms success. See #SUPER_RESOLUTION_STATE_REASON. + * */ virtual void onUserSuperResolutionEnabled(IChannel* rtcChannel, uid_t uid, bool enabled, SUPER_RESOLUTION_STATE_REASON reason) { (void)rtcChannel; @@ -341,9 +348,8 @@ class IChannelEventHandler { (void)enabled; (void)reason; } - /// @endcond - /** Occurs when the most active speaker is detected. + /** Occurs when the most active remote speaker is detected. After a successful call of \ref IRtcEngine::enableAudioVolumeIndication(int, int, bool) "enableAudioVolumeIndication", the SDK continuously detects which remote user has the loudest volume. During the current period, the remote user, @@ -354,7 +360,7 @@ class IChannelEventHandler { - If the most active speaker changes to another user, the SDK triggers this callback again and reports the `uid` of the new active speaker. @param rtcChannel IChannel - @param uid The user ID of the most active speaker. + @param uid The user ID of the most active remote speaker. */ virtual void onActiveSpeaker(IChannel* rtcChannel, uid_t uid) { (void)rtcChannel; @@ -376,17 +382,17 @@ class IChannelEventHandler { (void)rotation; } /** Occurs when the remote video state changes. - - @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. - - @param rtcChannel IChannel - @param uid ID of the remote user whose video state changes. - @param state State of the remote video. See #REMOTE_VIDEO_STATE. - @param reason The reason of the remote video state change. See - #REMOTE_VIDEO_STATE_REASON. - @param elapsed Time elapsed (ms) from the local user calling the - \ref agora::rtc::IChannel::joinChannel "joinChannel" method until the - SDK triggers this callback. + * + * @note This callback can be inaccurate when the number of users (in the `COMMUNICATION` profile) or + * hosts (in the `LIVE_BROADCASTING` profile) in a channel exceeds 17. + * + * @param rtcChannel IChannel + * @param uid ID of the remote user whose video state changes. + * @param state State of the remote video. See #REMOTE_VIDEO_STATE. + * @param reason The reason of the remote video state change. See #REMOTE_VIDEO_STATE_REASON. + * @param elapsed Time elapsed (ms) from the local user calling the + * \ref agora::rtc::IChannel::joinChannel "joinChannel" method until the + * SDK triggers this callback. */ virtual void onRemoteVideoStateChanged(IChannel* rtcChannel, uid_t uid, REMOTE_VIDEO_STATE state, REMOTE_VIDEO_STATE_REASON reason, int elapsed) { (void)rtcChannel; @@ -453,22 +459,23 @@ class IChannelEventHandler { (void)code; } /** - Occurs when the state of the RTMP or RTMPS streaming changes. - - The SDK triggers this callback to report the result of the local user calling the \ref agora::rtc::IChannel::addPublishStreamUrl "addPublishStreamUrl" or \ref agora::rtc::IChannel::removePublishStreamUrl "removePublishStreamUrl" method. - - 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 *errCode* parameter. - - @param rtcChannel IChannel - @param url The CDN streaming URL. - @param state The RTMP or RTMPS streaming state. See: #RTMP_STREAM_PUBLISH_STATE. - @param errCode The detailed error information for streaming. See: #RTMP_STREAM_PUBLISH_ERROR. + * Occurs when the state of the RTMP or RTMPS streaming changes. + * + * When the CDN live streaming state changes, the SDK triggers this callback to report the current state and the reason + * why the state has changed. + * + * When exceptions occur, you can troubleshoot issues by referring to the detailed error descriptions in the *errCode* parameter. + * + * @param rtcChannel IChannel + * @param url The CDN streaming URL. + * @param state The RTMP or RTMPS streaming state. See: #RTMP_STREAM_PUBLISH_STATE. + * @param errCode The detailed error information for streaming. See: #RTMP_STREAM_PUBLISH_ERROR_TYPE. */ - virtual void onRtmpStreamingStateChanged(IChannel* rtcChannel, const char* url, RTMP_STREAM_PUBLISH_STATE state, RTMP_STREAM_PUBLISH_ERROR errCode) { + virtual void onRtmpStreamingStateChanged(IChannel* rtcChannel, const char* url, RTMP_STREAM_PUBLISH_STATE state, RTMP_STREAM_PUBLISH_ERROR_TYPE errCode) { (void)rtcChannel; (void)url; - (RTMP_STREAM_PUBLISH_STATE) state; - (RTMP_STREAM_PUBLISH_ERROR) errCode; + (void)state; + (void)errCode; } /** Reports events during the RTMP or RTMPS streaming. @@ -482,7 +489,7 @@ class IChannelEventHandler { virtual void onRtmpStreamingEvent(IChannel* rtcChannel, const char* url, RTMP_STREAMING_EVENT eventCode) { (void)rtcChannel; (void)url; - (RTMP_STREAMING_EVENT) eventCode; + (void)eventCode; } /** Occurs when the publisher's transcoding is updated. @@ -531,8 +538,8 @@ class IChannelEventHandler { * "setRemoteSubscribeFallbackOption" and set * @p option as #STREAM_FALLBACK_OPTION_AUDIO_ONLY, the SDK triggers this * callback when the remote media stream falls back to audio-only mode due - * to poor uplink conditions, or when the remote media stream switches - * back to the video after the uplink network condition improves. + * to poor downlink conditions, or when the remote media stream switches + * back to the video after the downlink network condition improves. * * @note Once the remote media stream switches to the low stream due to * poor network conditions, you can monitor the stream switch between a @@ -588,68 +595,77 @@ class IChannel { */ virtual int setChannelEventHandler(IChannelEventHandler* channelEh) = 0; /** Joins the channel with a user ID. - - This method differs from the `joinChannel` method in the `IRtcEngine` class in the following aspects: - - | IChannel::joinChannel | IRtcEngine::joinChannel | - |------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------| - | Does not contain the `channelId` parameter, because `channelId` is specified when creating the `IChannel` object. | Contains the `channelId` parameter, which specifies the channel to join. | - | Contains the `options` parameter, which decides whether to subscribe to all streams before joining the channel. | Does not contain the `options` parameter. By default, users subscribe to all streams when joining the channel. | - | Users can join multiple channels simultaneously by creating multiple `IChannel` objects and calling the `joinChannel` method of each object. | Users can join only one channel. | - | By default, the SDK does not publish any stream after the user joins the channel. You need to call the publish method to do that. | By default, the SDK publishes streams once the user joins the channel. | - - Once the user joins the channel (switches to another channel), the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. If you do not want to subscribe to a specified stream or all remote streams, call the `mute` methods accordingly. - - @note - - If you are already in a channel, you cannot rejoin it with the same `uid`. - - We recommend using different UIDs for different channels. - - If you want to join the same channel from different devices, ensure that the UIDs 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` object. - - @param token The token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Windows). - @param info (Optional) Additional information about the channel. This parameter can be set as null. Other users in the channel do not receive this information. - @param uid The user ID. A 32-bit unsigned integer with a value ranging from 1 to (232-1). This parameter must be unique. If `uid` is not assigned (or set as `0`), the SDK assigns a `uid` and reports it in the \ref agora::rtc::IChannelEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" callback. The app must maintain this user ID. - @param options The channel media options: \ref agora::rtc::ChannelMediaOptions::ChannelMediaOptions "ChannelMediaOptions" - - @return - - 0(ERR_OK): Success. - - < 0: Failure. - - -2(ERR_INALID_ARGUMENT): The parameter is invalid. - - -3(ERR_NOT_READY): The SDK fails to be initialized. You can try re-initializing the SDK. - - -5(ERR_REFUSED): The request is rejected. This may be caused by the following: - - You have created an IChannel object with the same channel name. - - You have joined and published a stream in a channel created by the IChannel object. When you join a channel created by the IRtcEngine object, the SDK publishes the local audio and video streams to that channel by default. Because the SDK does not support publishing a local stream to more than one channel simultaneously, an error occurs in this occasion. - - -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method. + * + * Compared with the `joinChannel` method in the IRtcEngine class, this method supports joining multiple channels at + * a time by creating multiple IChannel objects and then calling `joinChannel` in each IChannel object. + * + * Once the user joins the channel, the user publishes the local audio and video streams and automatically + * subscribes to the audio and video streams of all the other users in the channel by default. Subscribing + * incurs all associated usage costs. To unsubscribe, set the `options` parameter or call the `mute` methods accordingly. + * + * @note + * - If you are already in a channel, you cannot rejoin it with the same `uid`. + * - We recommend using different UIDs for different channels. + * - If you want to join the same channel from different devices, ensure that the UIDs 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` object. + * + * @param token The token generated at your server. See [Authenticate Your Users with Tokens](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=All%20Platforms). + * @param info (Optional) Additional information about the channel. This parameter can be set as null. Other users in the channel do not receive this information. + * @param uid The user ID. A 32-bit unsigned integer with a value ranging from 1 to (232-1). This parameter must be unique. If `uid` is not assigned (or set as `0`), the SDK assigns a `uid` and reports it in the \ref agora::rtc::IChannelEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" callback. The app must maintain this user ID. + * @param options The channel media options: \ref agora::rtc::ChannelMediaOptions::ChannelMediaOptions "ChannelMediaOptions" + * + * @return + * - 0(ERR_OK): Success. + * - < 0: Failure. + * - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. + * - -3(ERR_NOT_READY): The SDK fails to be initialized. You can try re-initializing the SDK. + * - -5(ERR_REFUSED): The request is rejected. This may be caused by the following: + * - You have created an IChannel object with the same channel name. + * - You have joined and published a stream in a channel created by the IChannel object. When you join a channel created by the IRtcEngine object, the SDK publishes the local audio and video streams to that channel by default. Because the SDK does not support publishing a local stream to more than one channel simultaneously, an error occurs in this occasion. + * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method. + * - `ERR_JOIN_CHANNEL_REJECTED(-17)`: The request to join the channel is rejected. The SDK does not support + * joining the same IChannel channel repeatedly. Therefore, the SDK returns this error code when a user who has + * already joined an IChannel channel calls the joining channel method of this IChannel object. */ virtual int joinChannel(const char* token, const char* info, uid_t uid, const ChannelMediaOptions& options) = 0; /** Joins the channel with a user account. - - After the user successfully joins the channel, the SDK triggers the following callbacks: - - - The local client: \ref agora::rtc::IRtcEngineEventHandler::onLocalUserRegistered "onLocalUserRegistered" and \ref agora::rtc::IChannelEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" . - - The remote client: \ref agora::rtc::IChannelEventHandler::onUserJoined "onUserJoined" and \ref agora::rtc::IRtcEngineEventHandler::onUserInfoUpdated "onUserInfoUpdated" , if the user joining the channel is in the `COMMUNICATION` profile, or is a host in the `LIVE_BROADCASTING` profile. - - Once the user joins the channel (switches to another channel), the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. If you do not want to subscribe to a specified stream or all remote streams, call the `mute` methods accordingly. - - @note To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. - If a user joins the channel with the Agora Web SDK, ensure that the uid of the user is set to the same parameter type. - - @param token The token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Windows). - @param userAccount The user account. The maximum length of this parameter is 255 bytes. Ensure that the user account is unique and do not set it as null. Supported character scopes are: - - All lowercase English letters: a to z. - - All uppercase English letters: A to Z. - - All numeric characters: 0 to 9. - - The space character. - - Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",". - @param options The channel media options: \ref agora::rtc::ChannelMediaOptions::ChannelMediaOptions “ChannelMediaOptions”. - - @return - - 0: Success. - - < 0: Failure. - - #ERR_INVALID_ARGUMENT (-2) - - #ERR_NOT_READY (-3) - - #ERR_REFUSED (-5) - - #ERR_NOT_INITIALIZED (-7) + * + * Compared with the `joinChannelWithUserAccount` method in the IRtcEngine class, this method supports joining multiple channels at + * a time by creating multiple IChannel objects and then calling `joinChannelWithUserAccount` in each IChannel object. + * + * After the user successfully joins the channel, the SDK triggers the following callbacks: + * + * - The local client: \ref agora::rtc::IRtcEngineEventHandler::onLocalUserRegistered "onLocalUserRegistered" and \ref agora::rtc::IChannelEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" . + * - The remote client: \ref agora::rtc::IChannelEventHandler::onUserJoined "onUserJoined" and \ref agora::rtc::IRtcEngineEventHandler::onUserInfoUpdated "onUserInfoUpdated" , if the user joining the channel is in the `COMMUNICATION` profile, or is a host in the `LIVE_BROADCASTING` profile. + * + * Once the user joins the channel, the user publishes the local audio and video streams and + * automatically subscribes to the audio and video streams of all the other users in the channel by default. + * Subscribing incurs all associated usage costs. To unsubscribe, set the `options` parameters 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 uid of the user is set to the same parameter type. + * - Before using a String user name, ensure that you read [How can I use string user names](https://docs.agora.io/en/faq/string) for getting details about the limitations and implementation steps. + * + * @param token The token generated at your server. See [Authenticate Your Users with Tokens](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=All%20Platforms). + * @param userAccount The user account. The maximum length of this parameter is 255 bytes. Ensure that the user account is unique and do not set it as null. Supported character scopes are: + * - All lowercase English letters: a to z. + * - All uppercase English letters: A to Z. + * - All numeric characters: 0 to 9. + * - The space character. + * - Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",". + * @param options The channel media options: \ref agora::rtc::ChannelMediaOptions::ChannelMediaOptions “ChannelMediaOptions”. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - #ERR_INVALID_ARGUMENT (-2) + * - #ERR_NOT_READY (-3) + * - #ERR_REFUSED (-5) + * - #ERR_NOT_INITIALIZED (-7) + * - `ERR_JOIN_CHANNEL_REJECTED(-17)`: The request to join the channel is rejected. The SDK does not support + * joining the same IChannel channel repeatedly. Therefore, the SDK returns this error code when a user who has + * already joined an IChannel channel calls the joining channel method of this IChannel object. */ virtual int joinChannelWithUserAccount(const char* token, const char* userAccount, const ChannelMediaOptions& options) = 0; /** Allows a user to leave a channel, such as hanging up or exiting a call. @@ -668,20 +684,28 @@ class IChannel { - If you call the \ref IChannel::release "release" method immediately after the *leaveChannel* method, the *leaveChannel* process interrupts, and the \ref IChannelEventHandler::onLeaveChannel "onLeaveChannel" callback is not triggered. - If you call the *leaveChannel* method during a CDN live streaming, the SDK triggers the \ref IChannel::removePublishStreamUrl "removePublishStreamUrl" method. - @return - - 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. - */ + @return + - 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. + */ virtual int leaveChannel() = 0; + /// @cond + virtual int setAVSyncSource(const char* channelId, uid_t uid) = 0; + /// @endcond + /** Publishes the local stream to the channel. + @deprecated This method is deprecated as of v3.4.5. Use \ref IChannel::muteLocalAudioStream "muteLocalAudioStream" (false) + or \ref IChannel::muteLocalVideoStream "muteLocalVideoStream" (false) instead. + You must keep the following restrictions in mind when calling this method. Otherwise, the SDK returns the #ERR_REFUSED (5): - - This method publishes one stream only to the channel corresponding to the current `IChannel` object. - - In the interactive live streaming channel, only a host can call this method. To switch the client role, call \ref agora::rtc::IChannel::setClientRole "setClientRole" of the current `IChannel` object. + - This method publishes one stream only to the channel corresponding to the current IChannel object. + - In the interactive live streaming channel, only a host can call this method. + To switch the client role, call \ref IChannel::setClientRole "setClientRole" of the current IChannel object. - You can publish a stream to only one channel at a time. For details on joining multiple channels, see the advanced guide *Join Multiple Channels*. @return @@ -689,10 +713,13 @@ class IChannel { - < 0: Failure. - #ERR_REFUSED (5): The method call is refused. */ - virtual int publish() = 0; + virtual int publish() AGORA_DEPRECATED_ATTRIBUTE = 0; /** Stops publishing a stream to the channel. + @deprecated This method is deprecated as of v3.4.5. Use \ref IChannel::muteLocalAudioStream "muteLocalAudioStream" (true) + or \ref IChannel::muteLocalVideoStream "muteLocalVideoStream" (true) instead. + If you call this method in a channel where you are not publishing streams, the SDK returns #ERR_REFUSED (5). @return @@ -700,7 +727,7 @@ class IChannel { - < 0: Failure. - #ERR_REFUSED (5): The method call is refused. */ - virtual int unpublish() = 0; + virtual int unpublish() AGORA_DEPRECATED_ATTRIBUTE = 0; /** Gets the channel ID of the current `IChannel` object. @@ -709,7 +736,7 @@ class IChannel { - The empty string "", if the method call fails. */ virtual const char* channelId() = 0; - /** Retrieves the current call ID. + /** Gets the current call ID. When a user joins a channel on a client, a `callId` is generated to identify the call from the client. Feedback methods, such as \ref IRtcEngine::rate "rate" and \ref IRtcEngine::complain "complain", must be called after the call ends to submit feedback to the SDK. @@ -734,13 +761,13 @@ class IChannel { The application should call this method to get the new `token`. Failure to do so will result in the SDK disconnecting from the server. - @param token Pointer to the new token. + @param token The new token. @return - 0(ERR_OK): Success. - < 0: Failure. - -1(ERR_FAILED): A general error occurs (no specified reason). - - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. */ virtual int renewToken(const char* token) = 0; @@ -762,7 +789,7 @@ class IChannel { - 0: Success. - < 0: Failure. */ - virtual int setEncryptionSecret(const char* secret) = 0; + virtual int setEncryptionSecret(const char* secret) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Sets the built-in encryption mode. @deprecated Deprecated as of v3.1.0. Use the \ref agora::rtc::IChannel::enableEncryption "enableEncryption" instead. @@ -785,16 +812,25 @@ class IChannel { - 0: Success. - < 0: Failure. */ - virtual int setEncryptionMode(const char* encryptionMode) = 0; + virtual int setEncryptionMode(const char* encryptionMode) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Enables/Disables the built-in encryption. * * @since v3.1.0 * * In scenarios requiring high security, Agora recommends calling this method to enable the built-in encryption before joining a channel. * - * All users in the same channel must use the same encryption mode and encryption key. After a 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. + * After a user leaves the channel, the SDK automatically disables the built-in encryption. + * To re-enable the built-in encryption, call this method before the user joins the channel again. + * + * As of v3.4.5, Agora recommends using either the `AES_128_GCM2` or `AES_256_GCM2` encryption mode, + * both of which support adding a salt and are more secure. For details, see *Media Stream Encryption*. * - * @note If you enable the built-in encryption, you cannot use the RTMP or RTMPS streaming function. + * @warning All users in the same channel must use the same encryption mode, encryption key, and salt; otherwise, + * users cannot communicate with each other. + * + * @note + * - If you enable the built-in encryption, you cannot use the RTMP or RTMPS streaming function. + * - To enhance security, Agora recommends using a new key and salt every time you enable the media stream encryption. * * @param enabled Whether to enable the built-in encryption: * - true: Enable the built-in encryption. @@ -816,7 +852,7 @@ class IChannel { @note - The size of the packet sent to the network after processing should not exceed 1200 bytes, otherwise, the packet may fail to be sent. - Ensure that both receivers and senders call this method, otherwise, you may meet undefined behaviors such as no voice and black screen. - - When you use CDN live streaming, recording or storage functions, Agora doesn't recommend calling this method. + - When you use CDN live streaming and recording functions, Agora doesn't recommend calling this method. - Call this method before joining a channel. @param observer The registered packet observer. See IPacketObserver. @@ -842,43 +878,61 @@ class IChannel { - < 0: Failure. */ virtual int registerMediaMetadataObserver(IMetadataObserver* observer, IMetadataObserver::METADATA_TYPE type) = 0; - /** Sets the role of the user, such as a host or an audience (default), before joining a channel in the interactive live streaming. - - This method can be used to switch the user role in the interactive live streaming after the user joins a channel. - - In the `LIVE_BROADCASTING` profile, when a user switches user roles after joining a channel, a successful \ref agora::rtc::IChannel::setClientRole "setClientRole" method call triggers the following callbacks: - - The local client: \ref agora::rtc::IChannelEventHandler::onClientRoleChanged "onClientRoleChanged" - - The remote client: \ref agora::rtc::IChannelEventHandler::onUserJoined "onUserJoined" or \ref agora::rtc::IChannelEventHandler::onUserOffline "onUserOffline" (BECOME_AUDIENCE) - - @note - This method applies only to the `LIVE_BROADCASTING` profile. - - @param role Sets the role of the user. See #CLIENT_ROLE_TYPE. - @return - - 0: Success. - - < 0: Failure. + /** Sets the role of the user in interactive live streaming. + * + * In the `LIVE_BROADCASTING` channel profile, the + * SDK sets the user role as audience by default. You can call `setClientRole` to set the user role as host. + * + * You can call this method either before or after joining a channel. If you + * call this method to switch the user role after joining a channel, the SDK automatically does the following: + * - Calls \ref IChannel::muteLocalAudioStream "muteLocalAudioStream" and \ref IChannel::muteLocalVideoStream "muteLocalVideoStream" to + * change the publishing state. + * - Triggers \ref IChannelEventHandler::onClientRoleChanged "onClientRoleChanged" on the local client. + * - Triggers \ref IChannelEventHandler::onUserJoined "onUserJoined" or \ref IChannelEventHandler::onUserOffline "onUserOffline" (BECOME_AUDIENCE) + * on the remote client. + * + * @note This method applies to the `LIVE_BROADCASTING` profile only. + * + * @param role The role of a user in interactive live streaming. See #CLIENT_ROLE_TYPE. + * + * @return + * - 0(ERR_OK): Success. + * - < 0: Failure. + * - -1(ERR_FAILED): A general error occurs (no specified reason). + * - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. + * - -5 (ERR_REFUSED): The request is rejected. In multichannel scenarios, if you have set any of the following in + * one channel, the SDK returns this error code when the user switches the user role to host in another channel: + * - Call `joinChannel` with the `options` parameter and use the default settings `publishLocalAudio = true` or `publishLocalVideo = true`. + * - Call `setClientRole` to set the user role as host. + * - Call `muteLocalAudioStream(false)` or `muteLocalVideoStream(false)`. + * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. */ virtual int setClientRole(CLIENT_ROLE_TYPE role) = 0; - /** Sets the role of a user in interactive live streaming. + /** Sets the role of the user in interactive live streaming. * * @since v3.2.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: \ref IChannelEventHandler::onClientRoleChanged "onClientRoleChanged". - * - The remote client: \ref IChannelEventHandler::onUserJoined "onUserJoined" - * or \ref IChannelEventHandler::onUserOffline "onUserOffline". + * In the `LIVE_BROADCASTING` channel profile, the + * SDK sets the user role as audience by default. You can call `setClientRole` to set the user role as host. + * + * You can call this method either before or after joining a channel. If you + * call this method to switch the user role after joining a channel, the SDK automatically does the following: + * - Calls \ref IChannel::muteLocalAudioStream "muteLocalAudioStream" and \ref IChannel::muteLocalVideoStream "muteLocalVideoStream" to + * change the publishing state. + * - Triggers \ref IChannelEventHandler::onClientRoleChanged "onClientRoleChanged" on the local client. + * - Triggers \ref IChannelEventHandler::onUserJoined "onUserJoined" or \ref IChannelEventHandler::onUserOffline "onUserOffline" (BECOME_AUDIENCE) + * on the remote client. * * @note * - This method applies to the `LIVE_BROADCASTING` profile only. * - The difference between this method and \ref IChannel::setClientRole(CLIENT_ROLE_TYPE) "setClientRole" [1/2] is that * this method can set the user level in addition to the user role. - * - The user role determines the permissions that the SDK grants to a user, such as permission to send local - * streams, receive remote streams, and push streams to a CDN address. - * - The user level determines the level of services that a user can enjoy within the permissions of the user's - * role. For example, an audience can choose to receive remote streams with low latency or ultra low latency. Levels - * affect prices. + * - The user role determines the permissions that the SDK grants to a user, such as permission to send local streams, + * receive remote streams, and push streams to a CDN address. + * - The user level determines the level of services that a user can enjoy within the permissions of the user's role. + * For example, an audience member can choose to receive remote streams with low latency or ultra low latency. + * **User level affects the pricing of services.** * * @param role The role of a user in interactive live streaming. See #CLIENT_ROLE_TYPE. * @param options The detailed options of a user, including user level. See ClientRoleOptions. @@ -887,7 +941,12 @@ class IChannel { * - 0(ERR_OK): Success. * - < 0: Failure. * - -1(ERR_FAILED): A general error occurs (no specified reason). - * - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + * - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. + * - -5 (ERR_REFUSED): The request is rejected. In multichannel scenarios, if you have set any of the following in + * one channel, the SDK returns this error code when the user switches the user role to host in another channel: + * - Call `joinChannel` with the `options` parameter and use the default settings `publishLocalAudio = true` or `publishLocalVideo = true`. + * - Call `setClientRole` to set the user role as host. + * - Call `muteLocalAudioStream(false)` or `muteLocalVideoStream(false)`. * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. */ virtual int setClientRole(CLIENT_ROLE_TYPE role, const ClientRoleOptions& options) = 0; @@ -973,7 +1032,7 @@ class IChannel { * - 0: Success. * - < 0: Failure. */ - virtual int setDefaultMuteAllRemoteAudioStreams(bool mute) = 0; + virtual int setDefaultMuteAllRemoteAudioStreams(bool mute) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Stops or resumes subscribing to the video streams of all remote users by default. * * @deprecated This method is deprecated from v3.3.0. @@ -994,16 +1053,76 @@ class IChannel { * - 0: Success. * - < 0: Failure. */ - virtual int setDefaultMuteAllRemoteVideoStreams(bool mute) = 0; + virtual int setDefaultMuteAllRemoteVideoStreams(bool mute) AGORA_DEPRECATED_ATTRIBUTE = 0; + /** + * Stops or resumes publishing the local audio stream. + * + * @since v3.4.5 + * + * This method only sets the publishing state of the audio stream in the channel of IChannel. + * + * A successful method call triggers the + * \ref IChannelEventHandler::onRemoteAudioStateChanged "onRemoteAudioStateChanged" + * callback on the remote client. + * + * You can only publish the local stream in one channel at a time. If you create multiple channels, ensure that + * you only call \ref IChannel::muteLocalAudioStream "muteLocalAudioStream" (false) in one channel; + * otherwise, the method call fails, and the SDK returns `-5 (ERR_REFUSED)`. + * + * @note + * - This method does not change the usage state of the audio-capturing device. + * - Whether this method call takes effect is affected by the \ref IChannel::joinChannel "joinChannel" + * and \ref IChannel::setClientRole "setClientRole" methods. For details, see *Set the Publishing State*. + * + * @param mute Sets whether to stop publishing the local audio stream. + * - true: Stop publishing the local audio stream. + * - false: Resume publishing the local audio stream. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `-5 (ERR_REFUSED)`: The request is rejected. + */ + virtual int muteLocalAudioStream(bool mute) = 0; + /** Stops or resumes publishing the local video stream. + * + * @since v3.4.5 + * + * This method only sets the publishing state of the video stream in the channel of IChannel. + * + * A successful method call triggers the \ref IChannelEventHandler::onRemoteVideoStateChanged "onRemoteVideoStateChanged" + * callback on the remote client. + * + * You can only publish the local stream in one channel at a time. If you create multiple channels, + * ensure that you only call \ref IChannel::muteLocalVideoStream "muteLocalVideoStream" (false) in one channel; + * otherwise, the method call fails, and the SDK returns `-5 (ERR_REFUSED)`. + * + * @note + * - This method does not change the usage state of the video-capturing device. + * - Whether this method call takes effect is affected by the \ref IChannel::joinChannel "joinChannel" + * and \ref IChannel::setClientRole "setClientRole" methods. For details, see *Set the Publishing State*. + * + * @param mute Sets whether to stop publishing the local video stream. + * - true: Stop publishing the local video stream. + * - false: Resume publishing the local video stream. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `-5 (ERR_REFUSED)`: The request is rejected. + */ + virtual int muteLocalVideoStream(bool mute) = 0; /** * Stops or resumes subscribing to the audio streams of all remote users. * - * As of v3.3.0, after successfully calling this method, the local user stops or resumes + * 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*. + * - As of v3.3.0, this method contains the function of \ref IChannel::setDefaultMuteAllRemoteAudioStreams "setDefaultMuteAllRemoteAudioStreams". + * Agora recommends not calling `muteAllRemoteAudioStreams` and `setDefaultMuteAllRemoteAudioStreams` + * together; otherwise, the settings may not take effect. See *Set the Subscribing State*. * * @param mute Sets whether to stop subscribing to the audio streams of all remote users. * - true: Stop subscribing to the audio streams of all remote users. @@ -1015,24 +1134,26 @@ class IChannel { */ virtual int muteAllRemoteAudioStreams(bool mute) = 0; /** Adjust the playback signal volume of the specified remote user. - - After joining a channel, call \ref agora::rtc::IRtcEngine::adjustPlaybackSignalVolume "adjustPlaybackSignalVolume" to adjust the playback volume of different remote users, - or adjust multiple times for one remote user. - - @note - - Call this method after joining a channel. - - This method adjusts the playback volume, which is the mixed volume for the specified remote user. - - This method can only adjust the playback volume of one specified remote user at a time. If you want to adjust the playback volume of several remote users, - call the method multiple times, once for each remote user. - - @param userId The user ID, which should be the same as the `uid` of \ref agora::rtc::IChannel::joinChannel "joinChannel" - @param volume The playback volume of the voice. The value ranges from 0 to 100: - - 0: Mute. - - 100: Original volume. - - @return - - 0: Success. - - < 0: Failure. + * + * After joining a channel, call \ref agora::rtc::IRtcEngine::adjustPlaybackSignalVolume "adjustPlaybackSignalVolume" to adjust the playback volume of different remote users, + * or adjust multiple times for one remote user. + * + * @note + * - Call this method after joining a channel. + * - This method adjusts the playback volume, which is the mixed volume for the specified remote user. + * - This method can only adjust the playback volume of one specified remote user at a time. If you want to adjust the playback volume of several remote users, + * call the method multiple times, once for each remote user. + * + * @param userId The user ID, which should be the same as the `uid` of \ref agora::rtc::IChannel::joinChannel "joinChannel" + * @param volume The playback volume of the voice. The value + * ranges between 0 and 400, including the following: + * - 0: Mute. + * - 100: (Default) Original volume. + * - 400: Four times the original volume with signal-clipping protection. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int adjustUserPlaybackSignalVolume(uid_t userId, int volume) = 0; /** @@ -1055,7 +1176,7 @@ class IChannel { /** * Stops or resumes subscribing to the video streams of all remote users. * - * As of v3.3.0, after successfully calling this method, the local user stops or resumes + * 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 @@ -1145,7 +1266,7 @@ class IChannel { virtual int setRemoteDefaultVideoStreamType(REMOTE_VIDEO_STREAM_TYPE streamType) = 0; /** Creates a data stream. - @deprecated This method is deprecated from v3.3.0. Use the \ref IChannel::createDataStream(int* streamId, DataStreamConfig& config) "createDataStream" [2/2] method instead. + @deprecated This method is deprecated from v3.3.0. Use the \ref IChannel::createDataStream(int* streamId, DataStreamConfig& config) "createDataStream" [2/2] method instead. Each user can create up to five data streams during the lifecycle of the IChannel. @@ -1167,7 +1288,7 @@ class IChannel { - Returns 0: Success. - < 0: Failure. */ - virtual int createDataStream(int* streamId, bool reliable, bool ordered) = 0; + virtual int createDataStream(int* streamId, bool reliable, bool ordered) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Creates a data stream. * * @since v3.3.0 @@ -1213,6 +1334,8 @@ class IChannel { virtual int sendStreamMessage(int streamId, const char* data, size_t length) = 0; /** Publishes the local stream to a specified CDN streaming URL. (CDN live only.) + @deprecated This method is deprecated as of v3.6.0. See [Release Notes](https://docs.agora.io/en/Interactive%20Broadcast/release_windows_video?platform=Windows) for an alternative solution. + The SDK returns the result of this method call in the \ref IRtcEngineEventHandler::onStreamPublished "onStreamPublished" callback. After calling this method, you can push media streams in RTMP or RTMPS protocol to the CDN. The SDK triggers @@ -1236,9 +1359,11 @@ class IChannel { - #ERR_INVALID_ARGUMENT (-2): The CDN streaming URL is NULL or has a string length of 0. - #ERR_NOT_INITIALIZED (-7): You have not initialized `IChannel` when publishing the stream. */ - virtual int addPublishStreamUrl(const char* url, bool transcodingEnabled) = 0; + virtual int addPublishStreamUrl(const char* url, bool transcodingEnabled) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Removes an RTMP or RTMPS stream from the CDN. + @deprecated This method is deprecated as of v3.6.0. See [Release Notes](https://docs.agora.io/en/Interactive%20Broadcast/release_windows_video?platform=Windows) for an alternative solution. + This method removes the CDN streaming URL (added by the \ref IChannel::addPublishStreamUrl "addPublishStreamUrl" method) from a CDN live stream. The SDK returns the result of this method call in the \ref IRtcEngineEventHandler::onStreamUnpublished "onStreamUnpublished" callback. @@ -1255,9 +1380,11 @@ class IChannel { - 0: Success. - < 0: Failure. */ - virtual int removePublishStreamUrl(const char* url) = 0; + virtual int removePublishStreamUrl(const char* url) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Sets the video layout and audio settings for CDN live. (CDN live only.) + @deprecated This method is deprecated as of v3.6.0. See [Release Notes](https://docs.agora.io/en/Interactive%20Broadcast/release_windows_video?platform=Windows) for an alternative solution. + The SDK triggers the \ref agora::rtc::IChannelEventHandler::onTranscodingUpdated "onTranscodingUpdated" callback when you call the `setLiveTranscoding` method to update the transcoding setting. @@ -1273,7 +1400,105 @@ class IChannel { - 0: Success. - < 0: Failure. */ - virtual int setLiveTranscoding(const LiveTranscoding& transcoding) = 0; + virtual int setLiveTranscoding(const LiveTranscoding& transcoding) AGORA_DEPRECATED_ATTRIBUTE = 0; + /** + * Starts pushing media streams to a CDN without transcoding. + * + * @since v3.6.0 + * + * You can call this method to push a live audio-and-video stream to the specified CDN address. This method can push + * media streams to only one CDN address at a time, so if you need to push streams to multiple addresses, call this + * method multiple times. + * + * After you call this method, the SDK triggers the \ref IChannelEventHandler::onRtmpStreamingStateChanged "onRtmpStreamingStateChanged" + * callback on the local client to report the state of the streaming. + * + * @note + * - Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in *Push Streams to CDN*. + * - Call this method after joining a channel. + * - Only hosts in the `LIVE_BROADCASTING` profile can call this method. + * - If you want to retry pushing streams after a failed push, make sure to call \ref IChannel::stopRtmpStream "stopRtmpStream" first, + * then call this method to retry pushing streams; otherwise, the SDK returns the same error code as the last failed push. + * - If you want to push media streams in the RTMPS protocol to CDN, call \ref IChannel::startRtmpStreamWithTranscoding "startRtmpStreamWithTranscoding" + * instead of \ref IChannel::startRtmpStreamWithoutTranscoding "startRtmpStreamWithoutTranscoding". + * + * @param url The address of the CDN live streaming. The format is RTMP. The character length cannot exceed 1024 bytes. + * Special characters such as Chinese characters are not supported. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `ERR_INVALID_ARGUMENT(-2)`: url is null or the string length is 0. + * - `ERR_NOT_INITIALIZED(-7)`: The SDK is not initialized before calling this method. + */ + virtual int startRtmpStreamWithoutTranscoding(const char* url) = 0; + /** + * Starts pushing media streams to a CDN and sets the transcoding configuration. + * + * @since v3.6.0 + * + * You can call this method to push a live audio-and-video stream to the specified CDN address and set the transcoding + * configuration. This method can push media streams to only one CDN address at a time, so if you need to push streams to + * multiple addresses, call this method multiple times. + * + * After you call this method, the SDK triggers the \ref IChannelEventHandler::onRtmpStreamingStateChanged "onRtmpStreamingStateChanged" + * callback on the local client to report the state of the streaming. + * + * @note + * - Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in *Push Streams to CDN*. + * - Call this method after joining a channel. + * - Only hosts in the `LIVE_BROADCASTING` profile can call this method. + * - If you want to retry pushing streams after a failed push, make sure to call \ref IChannel::stopRtmpStream "stopRtmpStream" first, + * then call this method to retry pushing streams; otherwise, the SDK returns the same error code as the last failed push. + * - If you want to push media streams in the RTMPS protocol to CDN, call \ref IChannel::startRtmpStreamWithTranscoding "startRtmpStreamWithTranscoding" + * instead of \ref IChannel::startRtmpStreamWithoutTranscoding "startRtmpStreamWithoutTranscoding". + * + * @param url The address of the CDN live streaming. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. + * Special characters such as Chinese characters are not supported. + * @param transcoding The transcoding configuration for CDN live streaming. See LiveTranscoding. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `ERR_INVALID_ARGUMENT(-2)`: url is null or the string length is 0. + * - `ERR_NOT_INITIALIZED(-7)`: The SDK is not initialized before calling this method. + */ + virtual int startRtmpStreamWithTranscoding(const char* url, const LiveTranscoding& transcoding) = 0; + /** + * Updates the transcoding configuration. + * + * @since v3.6.0 + * + * After you start pushing media streams to CDN with transcoding, you can dynamically update the transcoding configuration according to the scenario. + * The SDK triggers the \ref IChannelEventHandler::onTranscodingUpdated "onTranscodingUpdated" callback after the + * transcoding configuration is updated. + * + * @param transcoding The transcoding configuration for CDN live streaming. See LiveTranscoding. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int updateRtmpTranscoding(const LiveTranscoding& transcoding) = 0; + /** + * Stops pushing media streams to a CDN. + * + * @since v3.6.0 + * + * You can call this method to stop the live stream on the specified CDN address. + * This method can stop pushing media streams to only one CDN address at a time, so if you need to stop pushing streams to multiple addresses, call this method multiple times. + * + * After you call this method, the SDK triggers the \ref IChannelEventHandler::onRtmpStreamingStateChanged "onRtmpStreamingStateChanged" callback on the local client to report the state of the streaming. + * + * @param url The address of the CDN live streaming. The format is RTMP or RTMPS. + * The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int stopRtmpStream(const char* url) = 0; + /** Adds a voice or video stream URL address to the interactive live streaming. The \ref IRtcEngineEventHandler::onStreamPublished "onStreamPublished" callback returns the inject status. @@ -1379,10 +1604,9 @@ class IChannel { * "onChannelMediaRelayEvent" callback with the * #RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL (7) state code. * - * @note - * Call this method after the - * \ref startChannelMediaRelay() "startChannelMediaRelay" method to update - * the destination channel. + * @note Call this method after successfully calling the \ref startChannelMediaRelay() "startChannelMediaRelay" method + * and receiving the \ref IChannelEventHandler::onChannelMediaRelayStateChanged "onChannelMediaRelayStateChanged" (RELAY_STATE_RUNNING, RELAY_OK) callback; + * otherwise, this method call fails. * * @param configuration The media stream relay configuration: * ChannelMediaRelayConfiguration. @@ -1392,6 +1616,47 @@ class IChannel { * - < 0: Failure. */ virtual int updateChannelMediaRelay(const ChannelMediaRelayConfiguration& configuration) = 0; + + /** + * Pauses the media stream relay to all destination channels. + * + * @since v3.5.1 + * + * After the cross-channel media stream relay starts, you can call this method + * to pause relaying media streams to all destination channels; after the pause, + * if you want to resume the relay, call \ref IChannel::resumeAllChannelMediaRelay "resumeAllChannelMediaRelay". + * + * After a successful method call, the SDK triggers the + * \ref IChannelEventHandler::onChannelMediaRelayEvent "onChannelMediaRelayEvent" + * callback to report whether the media stream relay is successfully paused. + * + * @note Call this method after the \ref IChannel::startChannelMediaRelay "startChannelMediaRelay" method. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int pauseAllChannelMediaRelay() = 0; + + /** Resumes the media stream relay to all destination channels. + * + * @since v3.5.1 + * + * After calling the \ref IChannel::pauseAllChannelMediaRelay "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 + * \ref IChannelEventHandler::onChannelMediaRelayEvent "onChannelMediaRelayEvent" + * callback to report whether the media stream relay is successfully resumed. + * + * @note Call this method after the \ref IChannel::pauseAllChannelMediaRelay "pauseAllChannelMediaRelay" method. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int resumeAllChannelMediaRelay() = 0; + /** Stops the media stream relay. * * Once the relay stops, the host quits all the destination @@ -1424,64 +1689,76 @@ class IChannel { @return #CONNECTION_STATE_TYPE. */ virtual CONNECTION_STATE_TYPE getConnectionState() = 0; - /// @cond - /** Enables/Disables the super-resolution algorithm for a remote user's video stream. + + /** Enables/Disables the super resolution feature for a remote user's video. (beta feature) * - * @since v3.2.0 + * @since v3.5.1 * - * The algorithm effectively improves the resolution of the specified remote user's video stream. When the original - * resolution of the remote video stream is a × b pixels, you can receive and render the stream at a higher - * resolution (2a × 2b pixels) by enabling the algorithm. + * This feature effectively boosts the resolution of a remote user's video seen by the local + * user. If the original resolution of a remote user's video is a × b, the local user's device + * can render the remote video at a resolution of 2a × 2b after you enable this feature. * * After calling this method, the SDK triggers the - * \ref IRtcChannelEventHandler::onUserSuperResolutionEnabled "onUserSuperResolutionEnabled" callback to report - * whether you have successfully enabled the super-resolution algorithm. - * - * @warning The super-resolution algorithm requires extra system resources. - * To balance the visual experience and system usage, the SDK poses the following restrictions: - * - The algorithm can only be used for a single user at a time. - * - On the Android platform, the original resolution of the remote video must not exceed 640 × 360 pixels. - * - On the iOS platform, the original resolution of the remote video must not exceed 640 × 480 pixels. - * If you exceed these limitations, the SDK triggers the \ref IRtcChannelEventHandler::onWarning "onWarning" - * callback with the corresponding warning codes: - * - #WARN_SUPER_RESOLUTION_STREAM_OVER_LIMITATION (1610): The origin resolution of the remote video is beyond the range where the super-resolution algorithm can be applied. - * - #WARN_SUPER_RESOLUTION_USER_COUNT_OVER_LIMITATION (1611): Another user is already using the super-resolution algorithm. - * - #WARN_SUPER_RESOLUTION_DEVICE_NOT_SUPPORTED (1612): The device does not support the super-resolution algorithm. + * \ref IChannelEventHandler::onUserSuperResolutionEnabled "onUserSuperResolutionEnabled" + * callback to report whether you have successfully enabled super resolution. + * + * @warning The super resolution feature requires extra system resources. To balance the visual experience and system consumption, the SDK poses the following restrictions: + * - This feature can only be enabled for a single remote user. + * - The original resolution of the remote user's video cannot exceed a certain range. If the local user use super resolution on Android, + * the original resolution of the remote user's video cannot exceed 640 × 360 pixels; if the local user use super resolution on iOS, + * the original resolution of the remote user's video cannot exceed 640 × 480 pixels. + * + * @warning If you exceed these limitations, the SDK triggers the + * \ref IRtcEngineEventHandler::onWarning "onWarning" callback and returns the corresponding warning codes: + * + * - #WARN_SUPER_RESOLUTION_STREAM_OVER_LIMITATION (1610): The original resolution of the remote user's video is beyond + * the range where super resolution can be applied. + * - #WARN_SUPER_RESOLUTION_USER_COUNT_OVER_LIMITATION (1611): Super resolution is already being used to boost another + * remote user's video. + * - #WARN_SUPER_RESOLUTION_DEVICE_NOT_SUPPORTED (1612): The device does not support using super resolution. * * @note - * - This method applies to Android and iOS only. - * - Requirements for the user's device: - * - Android: The following devices are known to support the method: - * - VIVO: V1821A, NEX S, 1914A, 1916A, and 1824BA - * - OPPO: PCCM00 + * - This method is for Android and iOS only. + * - Before calling this method, ensure that you have integrated the following dynamic library into your project: + * - Android: `libagora_super_resolution_extension.so` + * - iOS: `AgoraSuperResolutionExtension.xcframework` + * - Because this method has certain system performance requirements, Agora recommends that you use the following devices or better: + * - Android: + * - VIVO: V1821A, NEX S, 1914A, 1916A, 1962A, 1824BA, X60, X60 Pro + * - OPPO: PCCM00, Find X3 * - OnePlus: A6000 - * - Xiaomi: Mi 8, Mi 9, MIX3, and Redmi K20 Pro - * - SAMSUNG: SM-G9600, SM-G9650, SM-N9600, SM-G9708, SM-G960U, and SM-G9750 - * - HUAWEI: SEA-AL00, ELE-AL00, VOG-AL00, YAL-AL10, HMA-AL00, and EVR-AN00 - * - iOS: This method is supported on devices running iOS 12.0 or later. The following - * device models are known to support the method: + * - Xiaomi: Mi 8, Mi 9, Mi 10, Mi 11, MIX3, Redmi K20 Pro + * - SAMSUNG: SM-G9600, SM-G9650, SM-N9600, SM-G9708, SM-G960U, SM-G9750, S20, S21 + * - HUAWEI: SEA-AL00, ELE-AL00, VOG-AL00, YAL-AL10, HMA-AL00, EVR-AN00, nova 4, nova 5 Pro, + * nova 6 5G, nova 7 5G, Mate 30, Mate 30 Pro, Mate 40, Mate 40 Pro, P40 P40 Pro, HUAWEI MediaPad M6, MatePad 10.8 + * - iOS (iOS 12.0 or later): * - iPhone XR * - iPhone XS * - iPhone XS Max * - iPhone 11 * - iPhone 11 Pro * - iPhone 11 Pro Max - * - iPad Pro 11-inch (3rd Generation) - * - iPad Pro 12.9-inch (3rd Generation) - * - iPad Air 3 (3rd Generation) - * - * @param userId The ID of the remote user. - * @param enable Whether to enable the super-resolution algorithm: - * - true: Enable the super-resolution algorithm. - * - false: Disable the super-resolution algorithm. + * - iPhone 12 + * - iPhone 12 mini + * - iPhone 12 Pro + * - iPhone 12 Pro Max + * - iPhone 12 SE (2nd generation) + * - iPad Pro 11-inch (3rd generation) + * - iPad Pro 12.9-inch (3rd generation) + * - iPad Air (3rd generation) + * - iPad Air (4th generation) + * + * @param userId The user ID of the remote user. + * @param enable Determines whether to enable super resolution for the remote user's video: + * - true: Enable super resolution. + * - false: Disable super resolution. * * @return * - 0: Success. * - < 0: Failure. - * - -158 (ERR_MODULE_SUPER_RESOLUTION_NOT_FOUND): You have not integrated the dynamic library for the super-resolution algorithm. + * - `-157 (ERR_MODULE_NOT_FOUND)`: The dynamic library for super resolution is not integrated. */ virtual int enableRemoteSuperResolution(uid_t userId, bool enable) = 0; - /// @endcond }; /** @since v3.0.0 diff --git a/Android/APIExample/lib-player-helper/src/main/cpp/include/IAgoraRtcEngine.h b/Android/APIExample/lib-player-helper/src/main/cpp/include/IAgoraRtcEngine.h index 8fc262d28..cdc96614a 100644 --- a/Android/APIExample/lib-player-helper/src/main/cpp/include/IAgoraRtcEngine.h +++ b/Android/APIExample/lib-player-helper/src/main/cpp/include/IAgoraRtcEngine.h @@ -14,12 +14,24 @@ #include "IAgoraService.h" #include "IAgoraLog.h" -#if defined(_WIN32) #include "IAgoraMediaEngine.h" +#if defined(TARGET_OS_IPHONE) && TARGET_OS_IPHONE /* Warning fixing. Lionfore Oct 12th, 2019 */ +#include #endif namespace agora { namespace rtc { +/** The IMediaRecorderObserver class. + * + * @since v3.5.2 + */ +class IMediaRecorderObserver; +/** + * The MediaRecorderConfiguration struct. + * + * @since v3.5.2 + */ +struct MediaRecorderConfiguration; typedef unsigned int uid_t; typedef void* view_t; /** Maximum length of the device ID. @@ -53,7 +65,7 @@ enum QUALITY_REPORT_FORMAT_TYPE { */ QUALITY_REPORT_HTML = 1, }; - +/// @cond enum MEDIA_ENGINE_EVENT_CODE_TYPE { /** 0: For internal use only. */ @@ -115,6 +127,9 @@ enum MEDIA_ENGINE_EVENT_CODE_TYPE { /** 113: For internal use only. */ MEDIA_ENGINE_AUDIO_ADM_USING_NORM_PARAMS = 113, + /** 114: For internal use only. + */ + MEDIA_ENGINE_AUDIO_ADM_ROUTING_UPDATE = 114, // audio mix event /** 720: For internal use only. */ @@ -151,31 +166,50 @@ enum MEDIA_ENGINE_EVENT_CODE_TYPE { */ MEDIA_ENGINE_AUDIO_ERROR_MIXING_NO_ERROR = 0, }; +/// @endcond -/** The states of the local user's audio mixing file. +/** The current music file playback state. + * + * Reports in the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" callback. */ enum AUDIO_MIXING_STATE_TYPE { - /** 710: The audio mixing file is playing after the method call of - * \ref IRtcEngine::startAudioMixing "startAudioMixing" or \ref IRtcEngine::resumeAudioMixing "resumeAudioMixing" succeeds. + /** 710: The music file is playing. + * + * This state comes with one of the following associated reasons: + * - #AUDIO_MIXING_REASON_STARTED_BY_USER (720) + * - #AUDIO_MIXING_REASON_ONE_LOOP_COMPLETED (721) + * - #AUDIO_MIXING_REASON_START_NEW_LOOP (722) + * - #AUDIO_MIXING_REASON_RESUMED_BY_USER (726) */ AUDIO_MIXING_STATE_PLAYING = 710, - /** 711: The audio mixing file pauses playing after the method call of \ref IRtcEngine::pauseAudioMixing "pauseAudioMixing" succeeds. + /** 711: The music file pauses playing. + * + * This state comes with #AUDIO_MIXING_REASON_PAUSED_BY_USER (725). */ AUDIO_MIXING_STATE_PAUSED = 711, - /** 713: The audio mixing file stops playing after the method call of \ref IRtcEngine::stopAudioMixing "stopAudioMixing" succeeds. + /** 713: The music file stops playing. + * + * This state comes with one of the following associated reasons: + * - #AUDIO_MIXING_REASON_ALL_LOOPS_COMPLETED (723) + * - #AUDIO_MIXING_REASON_STOPPED_BY_USER (724) */ AUDIO_MIXING_STATE_STOPPED = 713, - /** 714: An exception occurs during the playback of the audio mixing file. See the `errorCode` for details. + /** 714: An exception occurs during the playback of the music file. + * + * This state comes with one of the following associated reasons: + * - #AUDIO_MIXING_REASON_CAN_NOT_OPEN (701) + * - #AUDIO_MIXING_REASON_TOO_FREQUENT_CALL (702) + * - #AUDIO_MIXING_REASON_INTERRUPTED_EOF (703) */ AUDIO_MIXING_STATE_FAILED = 714, }; /** - * @deprecated Deprecated from v3.4.0, use AUDIO_MIXING_REASON_TYPE instead. + * @deprecated Deprecated from v3.4.0. Use #AUDIO_MIXING_REASON_TYPE instead. * * The error codes of the local user's audio mixing file. */ -enum AUDIO_MIXING_ERROR_TYPE { +enum AGORA_DEPRECATED_ATTRIBUTE AUDIO_MIXING_ERROR_TYPE { /** 701: The SDK cannot open the audio mixing file. */ AUDIO_MIXING_ERROR_CAN_NOT_OPEN = 701, @@ -190,37 +224,49 @@ enum AUDIO_MIXING_ERROR_TYPE { AUDIO_MIXING_ERROR_OK = 0, }; -/** The reason of audio mixing state change. +/** The reason for the change of the music file playback state. + * + * @since v3.4.0 + * + * Reports in the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" callback. */ enum AUDIO_MIXING_REASON_TYPE { - /** 701: The SDK cannot open the audio mixing file. + /** 701: The SDK cannot open the music file. Possible causes include 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_CAN_NOT_OPEN = 701, - /** 702: The SDK opens the audio mixing file too frequently. + /** 702: The SDK opens the music file too frequently. If you need to call + * \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" multiple times, ensure + * that the call interval is longer than 500 ms. */ AUDIO_MIXING_REASON_TOO_FREQUENT_CALL = 702, - /** 703: The audio mixing file playback is interrupted. + /** 703: The music file playback is interrupted. */ AUDIO_MIXING_REASON_INTERRUPTED_EOF = 703, - /** 720: The audio mixing is started by user. + /** 720: Successfully calls \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" + * to play a music file. */ AUDIO_MIXING_REASON_STARTED_BY_USER = 720, - /** 721: The audio mixing file is played once. + /** 721: The music file completes a loop playback. */ AUDIO_MIXING_REASON_ONE_LOOP_COMPLETED = 721, - /** 722: The audio mixing file is playing in a new loop. + /** 722: The music file starts a new loop playback. */ AUDIO_MIXING_REASON_START_NEW_LOOP = 722, - /** 723: The audio mixing file is all played out. + /** 723: The music file completes all loop playback. */ AUDIO_MIXING_REASON_ALL_LOOPS_COMPLETED = 723, - /** 724: Playing of audio file is stopped by user. + /** 724: Successfully calls \ref IRtcEngine::stopAudioMixing "stopAudioMixing" + * to stop playing the music file. */ AUDIO_MIXING_REASON_STOPPED_BY_USER = 724, - /** 725: Playing of audio file is paused by user. + /** 725: Successfully calls \ref IRtcEngine::pauseAudioMixing "pauseAudioMixing" + * to pause playing the music file. */ AUDIO_MIXING_REASON_PAUSED_BY_USER = 725, - /** 726: Playing of audio file is resumed by user. + /** 726: Successfully calls \ref IRtcEngine::resumeAudioMixing "resumeAudioMixing" + * to resume playing the music file. */ AUDIO_MIXING_REASON_RESUMED_BY_USER = 726, }; @@ -228,7 +274,14 @@ enum AUDIO_MIXING_REASON_TYPE { /** Media device states. */ enum MEDIA_DEVICE_STATE_TYPE { - /** 1: The device is active. + /** 0: The device is ready for use. + * + * @since v3.4.5 + */ + MEDIA_DEVICE_STATE_IDLE = 0, + /** 1: The device is in use. + * + * @since v3.4.5 */ MEDIA_DEVICE_STATE_ACTIVE = 1, /** 2: The device is disabled. @@ -242,7 +295,7 @@ enum MEDIA_DEVICE_STATE_TYPE { MEDIA_DEVICE_STATE_UNPLUGGED = 8, /** 16: The device is not recommended. */ - MEDIA_DEVICE_STATE_UNRECOMMENDED = 16 + MEDIA_DEVICE_STATE_UNRECOMMENDED = 16, }; /** Media device types. @@ -268,10 +321,10 @@ enum MEDIA_DEVICE_TYPE { AUDIO_APPLICATION_PLAYOUT_DEVICE = 4, }; -/** Local video state types +/** Local video state types. */ enum LOCAL_VIDEO_STREAM_STATE { - /** 0: Initial state */ + /** 0: Initial state. */ LOCAL_VIDEO_STREAM_STATE_STOPPED = 0, /** 1: The local video capturing device starts successfully. * @@ -284,7 +337,7 @@ enum LOCAL_VIDEO_STREAM_STATE { LOCAL_VIDEO_STREAM_STATE_FAILED = 3 }; -/** Local video state error codes +/** Local video state error codes. */ enum LOCAL_VIDEO_STREAM_ERROR { /** 0: The local video is normal. */ @@ -309,9 +362,24 @@ enum LOCAL_VIDEO_STREAM_ERROR { * @since v3.3.0 */ LOCAL_VIDEO_STREAM_ERROR_CAPTURE_MULTIPLE_FOREGROUND_APPS = 7, - /** 8:capture not found*/ + /** + * 8: The SDK cannot find the local video capture device. + * + * @since v3.4.0 + */ LOCAL_VIDEO_STREAM_ERROR_DEVICE_NOT_FOUND = 8, - + /** + * 10: (macOS and Windows only) The SDK cannot find the video device in the video device list. Check whether the ID + * of the video device is valid. + * + * @since v3.5.2 + */ + LOCAL_VIDEO_STREAM_ERROR_DEVICE_INVALID_ID = 10, + /** + * 11: The shared window is minimized when you call + * \ref IRtcEngine::startScreenCaptureByWindowId "startScreenCaptureByWindowId" + * to share a window. + */ LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_MINIMIZED = 11, /** 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. @@ -326,8 +394,20 @@ enum LOCAL_VIDEO_STREAM_ERROR { * the web video or document. After the user exits full-screen mode, the SDK reports this error code. */ LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_CLOSED = 12, - + /** + * 13: (Windows only) The window being shared is overlapped by another window, so the overlapped area is blacked out by + * the SDK during window sharing. + * + * @since v3.5.2 + */ + LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_OCCLUDED = 13, + /** + * 20: (Windows only) The SDK does not support sharing this type of window. + * + * @since v3.5.2 + */ LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_NOT_SUPPORTED = 20, + }; /** Local audio state types. @@ -369,27 +449,47 @@ enum LOCAL_AUDIO_STREAM_ERROR { /** 5: The local audio encoding fails. */ LOCAL_AUDIO_STREAM_ERROR_ENCODE_FAILURE = 5, - /** 6: No recording audio device. + /** 6: The SDK cannot find the local audio recording device. + * + * @since v3.4.0 */ LOCAL_AUDIO_STREAM_ERROR_NO_RECORDING_DEVICE = 6, - /** 7: No playout audio device. + /** 7: The SDK cannot find the local audio playback device. + * + * @since v3.4.0 + */ + LOCAL_AUDIO_STREAM_ERROR_NO_PLAYOUT_DEVICE = 7, + /** + * 8: The local audio capturing is interrupted by the system call. + */ + LOCAL_AUDIO_STREAM_ERROR_INTERRUPTED = 8, + /** 9: An invalid audio capture device ID. + * + * @since v3.5.1 + */ + LOCAL_AUDIO_STREAM_ERROR_RECORD_INVALID_ID = 9, + /** 10: An invalid audio playback device ID. + * + * @since v3.5.1 */ - LOCAL_AUDIO_STREAM_ERROR_NO_PLAYOUT_DEVICE = 7 + LOCAL_AUDIO_STREAM_ERROR_PLAYOUT_INVALID_ID = 10, }; -/** Audio recording qualities. +/** Audio recording quality, which is set in + * \ref IRtcEngine::startAudioRecording(const AudioRecordingConfiguration&) "startAudioRecording". */ enum AUDIO_RECORDING_QUALITY_TYPE { - /** 0: Low quality. The sample rate is 32 kHz, and the file size is around - * 1.2 MB after 10 minutes of recording. + /** 0: Low quality. For example, the size of an AAC file with a sample rate + * of 32,000 Hz and a 10-minute recording is approximately 1.2 MB. */ AUDIO_RECORDING_QUALITY_LOW = 0, - /** 1: Medium quality. The sample rate is 32 kHz, and the file size is - * around 2 MB after 10 minutes of recording. + /** 1: (Default) Medium quality. For example, the size of an AAC file with + * a sample rate of 32,000 Hz and a 10-minute recording is approximately + * 2 MB. */ AUDIO_RECORDING_QUALITY_MEDIUM = 1, - /** 2: High quality. The sample rate is 32 kHz, and the file size is - * around 3.75 MB after 10 minutes of recording. + /** 2: High quality. For example, the size of an AAC file with a sample rate + * of 32,000 Hz and a 10-minute recording is approximately 3.75 MB. */ AUDIO_RECORDING_QUALITY_HIGH = 2, }; @@ -446,8 +546,8 @@ enum VIDEO_MIRROR_MODE_TYPE { VIDEO_MIRROR_MODE_DISABLED = 2, // disable mirror }; -/** **DEPRECATED** Video profiles. */ -enum VIDEO_PROFILE_TYPE { +/** @deprecated Video profiles. */ +enum AGORA_DEPRECATED_ATTRIBUTE VIDEO_PROFILE_TYPE { /** 0: 160 * 120, frame rate 15 fps, bitrate 65 Kbps. */ VIDEO_PROFILE_LANDSCAPE_120P = 0, /** 2: 120 * 120, frame rate 15 fps, bitrate 50 Kbps. */ @@ -610,12 +710,12 @@ Sets the sample rate, bitrate, encoding mode, and the number of channels:*/ enum AUDIO_PROFILE_TYPE // sample rate, bit rate, mono/stereo, speech/music codec { /** - 0: 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, music encoding, mono, and a bitrate of up to 16 Kbps. - - Android/macOS/iOS: A sample rate of 32 KHz, music encoding, mono, and a bitrate of up to 18 Kbps. - */ + * 0: Default audio profile: + * - For the `LIVE_BROADCASTING` 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_DEFAULT = 0, // use default settings /** 1: A sample rate of 32 KHz, audio encoding, mono, and a bitrate of up to 18 Kbps. @@ -650,7 +750,12 @@ enum AUDIO_PROFILE_TYPE // sample rate, bit rate, mono/stereo, speech/music cod */ enum AUDIO_SCENARIO_TYPE // set a suitable scenario for your app type { - /** 0: Default audio scenario. */ + /** 0: Default audio scenario. + * + * @note If you run the iOS app on an M1 Mac, due to the hardware differences + * between M1 Macs, iPhones, and iPads, the default audio scenario of the Agora + * iOS SDK is the same as that of the Agora macOS SDK. + */ AUDIO_SCENARIO_DEFAULT = 0, /** 1: Entertainment scenario where users need to frequently switch the user role. */ AUDIO_SCENARIO_CHATROOM_ENTERTAINMENT = 1, @@ -677,7 +782,7 @@ enum AUDIO_SCENARIO_TYPE // set a suitable scenario for your app type /** The channel profile. */ enum CHANNEL_PROFILE_TYPE { - /** (Default) Communication. This profile applies to scenarios such as an audio call or video call, + /** Communication. This profile applies to scenarios such as an audio call or video call, * where all users can publish and subscribe to streams. */ CHANNEL_PROFILE_COMMUNICATION = 0, @@ -703,7 +808,7 @@ enum CLIENT_ROLE_TYPE { /** The latency level of an audience member in interactive live streaming. * - * @note Takes effect only when the user role is `CLIENT_ROLE_BROADCASTER`. + * @note Takes effect only when the user role is `CLIENT_ROLE_AUDIENCE`. */ enum AUDIENCE_LATENCY_LEVEL_TYPE { /** 1: Low latency. */ @@ -711,24 +816,58 @@ enum AUDIENCE_LATENCY_LEVEL_TYPE { /** 2: (Default) Ultra low latency. */ AUDIENCE_LATENCY_LEVEL_ULTRA_LOW_LATENCY = 2, }; -/// @cond -/** The reason why the super-resolution algorithm is not successfully enabled. + +/** + * The reason why super resolution is not successfully enabled or the message + * that confirms success. + * + * @since v3.5.1 */ enum SUPER_RESOLUTION_STATE_REASON { - /** 0: The super-resolution algorithm is successfully enabled. + /** 0: Super resolution is successfully enabled. */ SR_STATE_REASON_SUCCESS = 0, - /** 1: The origin resolution of the remote video is beyond the range where - * the super-resolution algorithm can be applied. + /** 1: The original resolution of the remote video is beyond the range where + * super resolution can be applied. */ SR_STATE_REASON_STREAM_OVER_LIMITATION = 1, - /** 2: Another user is already using the super-resolution algorithm. + /** 2: Super resolution is already being used to boost another remote user's video. */ SR_STATE_REASON_USER_COUNT_OVER_LIMITATION = 2, - /** 3: The device does not support the super-resolution algorithm. + /** 3: The device does not support using super resolution. */ SR_STATE_REASON_DEVICE_NOT_SUPPORTED = 3, }; + +/** + * The reason why the virtual background is not successfully enabled or the message that confirms success. + * + * @since v3.4.5 + */ +enum VIRTUAL_BACKGROUND_SOURCE_STATE_REASON { + /** + * 0: The virtual background is successfully enabled. + */ + VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_SUCCESS = 0, + /** + * 1: The custom background image does not exist. Please check the value of `source` in VirtualBackgroundSource. + */ + VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_IMAGE_NOT_EXIST = 1, + /** + * 2: The color format of the custom background image is invalid. Please check the value of `color` in VirtualBackgroundSource. + */ + VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_COLOR_FORMAT_NOT_SUPPORTED = 2, + /** + * 3: The device does not support using the virtual background. + */ + VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_DEVICE_NOT_SUPPORTED = 3, +}; +/// @cond +enum CONTENT_INSPECT_RESULT { + CONTENT_INSPECT_NEUTRAL = 1, + CONTENT_INSPECT_SEXY = 2, + CONTENT_INSPECT_PORN = 3, +}; /// @endcond /** Reasons for a user being offline. */ @@ -762,41 +901,98 @@ enum RTMP_STREAM_PUBLISH_STATE { /** The RTMP or RTMPS streaming fails. See the errCode parameter for the detailed error information. You can also call the \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method to publish the RTMP or RTMPS streaming again. */ RTMP_STREAM_PUBLISH_STATE_FAILURE = 4, + /** The SDK is disconnecting from the Agora streaming server and CDN. + * When you call remove or stop to stop the streaming normally, the SDK reports the streaming state as `DISCONNECTING`, `IDLE` in sequence. + * + * @since v3.6.0 + */ + RTMP_STREAM_PUBLISH_STATE_DISCONNECTING = 5, }; /** Error codes of the RTMP or RTMPS streaming. */ -enum RTMP_STREAM_PUBLISH_ERROR { - /** The RTMP or RTMPS streaming publishes successfully. */ +enum RTMP_STREAM_PUBLISH_ERROR_TYPE { + /** 0: The RTMP or RTMPS streaming publishes successfully. */ RTMP_STREAM_PUBLISH_ERROR_OK = 0, - /** Invalid argument used. If, for example, you do not call the \ref IRtcEngine::setLiveTranscoding "setLiveTranscoding" method to configure the LiveTranscoding parameters before calling the addPublishStreamUrl method, the SDK returns this error. Check whether you set the parameters in the *setLiveTranscoding* method properly. */ + /** 1: Invalid argument used. If, for example, you do not call the \ref IRtcEngine::setLiveTranscoding "setLiveTranscoding" method to configure the LiveTranscoding parameters before calling the addPublishStreamUrl method, the SDK returns this error. Check whether you set the parameters in the *setLiveTranscoding* method properly. */ RTMP_STREAM_PUBLISH_ERROR_INVALID_ARGUMENT = 1, - /** The RTMP or RTMPS streaming is encrypted and cannot be published. */ + /** 2: The RTMP or RTMPS streaming is encrypted and cannot be published. */ RTMP_STREAM_PUBLISH_ERROR_ENCRYPTED_STREAM_NOT_ALLOWED = 2, - /** Timeout for the RTMP or RTMPS streaming. Call the \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method to publish the streaming again. */ + /** 3: Timeout for the RTMP or RTMPS streaming. Call the \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method to publish the streaming again. */ RTMP_STREAM_PUBLISH_ERROR_CONNECTION_TIMEOUT = 3, - /** An error occurs in Agora's streaming server. Call the `addPublishStreamUrl` method to publish the streaming again. */ + /** 4: An error occurs in Agora's streaming server. Call the `addPublishStreamUrl` method to publish the streaming again. */ RTMP_STREAM_PUBLISH_ERROR_INTERNAL_SERVER_ERROR = 4, - /** An error occurs in the CDN server. */ + /** 5: An error occurs in the CDN server. */ RTMP_STREAM_PUBLISH_ERROR_RTMP_SERVER_ERROR = 5, - /** The RTMP or RTMPS streaming publishes too frequently. */ + /** 6; The RTMP or RTMPS streaming publishes too frequently. */ RTMP_STREAM_PUBLISH_ERROR_TOO_OFTEN = 6, - /** The host publishes more than 10 URLs. Delete the unnecessary URLs before adding new ones. */ + /** 7: The host publishes more than 10 URLs. Delete the unnecessary URLs before adding new ones. */ RTMP_STREAM_PUBLISH_ERROR_REACH_LIMIT = 7, - /** The host manipulates other hosts' URLs. Check your app logic. */ + /** 8: The host manipulates other hosts' URLs. Check your app logic. */ RTMP_STREAM_PUBLISH_ERROR_NOT_AUTHORIZED = 8, - /** Agora's server fails to find the RTMP or RTMPS streaming. */ + /** 9: Agora's server fails to find the RTMP or RTMPS streaming. */ RTMP_STREAM_PUBLISH_ERROR_STREAM_NOT_FOUND = 9, - /** The format of the RTMP or RTMPS streaming URL is not supported. Check whether the URL format is correct. */ + /** 10: The format of the RTMP or RTMPS streaming URL is not supported. Check whether the URL format is correct. */ RTMP_STREAM_PUBLISH_ERROR_FORMAT_NOT_SUPPORTED = 10, + /** + * 11: The user role is not host, so the user cannot use the CDN live streaming function. + * Check your application code logic. + * + * @since v3.6.0 + */ + RTMP_STREAM_PUBLISH_ERROR_NOT_BROADCASTER = 11, // Note: match to ERR_PUBLISH_STREAM_NOT_BROADCASTER in AgoraBase.h + /** + * 13: The `updateRtmpTranscoding` or `setLiveTranscoding` method is called to update the transcoding configuration in a scenario where there is streaming without transcoding. + * Check your application code logic. + * + * @since v3.6.0 + */ + RTMP_STREAM_PUBLISH_ERROR_TRANSCODING_NO_MIX_STREAM = 13, // Note: match to ERR_PUBLISH_STREAM_TRANSCODING_NO_MIX_STREAM in AgoraBase.h + /** + * 14: Errors occurred in the host's network. + * + * @since v3.6.0 + */ + RTMP_STREAM_PUBLISH_ERROR_NET_DOWN = 14, // Note: match to ERR_NET_DOWN in AgoraBase.h + /** + * 15: Your App ID does not have permission to use the CDN live streaming function. + * Refer to [Prerequisites](https://docs.agora.io/en/Interactive%20Broadcast/cdn_streaming_windows?platform=Windows#prerequisites) to + * enable the CDN live streaming permission. + * + * @since v3.6.0 + */ + RTMP_STREAM_PUBLISH_ERROR_INVALID_APPID = 15, // Note: match to ERR_PUBLISH_STREAM_APPID_INVALID in AgoraBase.h + /** + * 100: The streaming has been stopped normally. After you call + * \ref IRtcEngine::removePublishStreamUrl "removePublishStreamUrl" + * to stop streaming, the SDK returns this value. + * + * @since v3.4.5 + */ + RTMP_STREAM_UNPUBLISH_ERROR_OK = 100, }; /** Events during the RTMP or RTMPS streaming. */ enum RTMP_STREAMING_EVENT { - /** An error occurs when you add a background image or a watermark image to the RTMP or RTMPS stream. + /** 1: An error occurs when you add a background image or a watermark image to the RTMP or RTMPS stream. */ RTMP_STREAMING_EVENT_FAILED_LOAD_IMAGE = 1, + /** 2: The streaming URL is already being used for CDN live streaming. If you want to start new streaming, use a new streaming URL. + * + * @since v3.4.5 + */ + RTMP_STREAMING_EVENT_URL_ALREADY_IN_USE = 2, + /** 3: The feature is not supported. + * + * @since v3.6.0 + */ + RTMP_STREAMING_EVENT_ADVANCED_FEATURE_NOT_SUPPORT = 3, + /** 4: Reserved. + * + * @since v3.6.0 + */ + RTMP_STREAMING_EVENT_REQUEST_TOO_OFTEN = 4, }; /** States of importing an external video stream in the interactive live streaming. */ @@ -883,19 +1079,29 @@ enum VIDEO_CODEC_PROFILE_TYPE { /** 66: Baseline video codec profile. Generally /** Video codec types */ enum VIDEO_CODEC_TYPE { - /** Standard VP8 */ + /** 1: Standard VP8 */ VIDEO_CODEC_VP8 = 1, - /** Standard H264 */ + /** 2: Standard H.264 */ VIDEO_CODEC_H264 = 2, - /** Enhanced VP8 */ + /** 3: Enhanced VP8 */ VIDEO_CODEC_EVP = 3, - /** Enhanced H264 */ + /** 4: Enhanced H.264 */ VIDEO_CODEC_E264 = 4, }; -/** Video Codec types for publishing streams. */ +/** + * The video codec type of the output video stream. + * + * @since v3.2.0 + */ enum VIDEO_CODEC_TYPE_FOR_STREAM { + /** + * 1: (Default) H.264 + */ VIDEO_CODEC_H264_FOR_STREAM = 1, + /** + * 2: H.265 + */ VIDEO_CODEC_H265_FOR_STREAM = 2, }; @@ -941,8 +1147,15 @@ enum AUDIO_REVERB_TYPE { * @deprecated Deprecated from v3.2.0. * * Local voice changer options. + * + * Gender-based beatification effect works best only when assigned a proper gender: + * + * - For male: #GENERAL_BEAUTY_VOICE_MALE_MAGNETIC + * - For female: #GENERAL_BEAUTY_VOICE_FEMALE_FRESH or #GENERAL_BEAUTY_VOICE_FEMALE_VITALITY + * + * Failure to do so can lead to voice distortion. */ -enum VOICE_CHANGER_PRESET { +enum AGORA_DEPRECATED_ATTRIBUTE VOICE_CHANGER_PRESET { /** * The original voice (no local voice change). */ @@ -1026,7 +1239,7 @@ enum VOICE_CHANGER_PRESET { * * Local voice reverberation presets. */ -enum AUDIO_REVERB_PRESET { +enum AGORA_DEPRECATED_ATTRIBUTE AUDIO_REVERB_PRESET { /** * Turn off local voice reverberation, that is, to use the original voice. */ @@ -1098,9 +1311,13 @@ enum AUDIO_REVERB_PRESET { * as `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)`. */ AUDIO_VIRTUAL_STEREO = 0x00200001, - /** 1: Electronic Voice.*/ + /** + * A pitch correction effect that corrects the user's pitch based on the pitch of the natural C major scale. + */ AUDIO_ELECTRONIC_VOICE = 0x00300001, - /** 1: 3D Voice.*/ + /** + * A 3D voice effect that makes the voice appear to be moving around the user. + */ AUDIO_THREEDIM_VOICE = 0x00400001 }; /** The options for SDK preset voice beautifier effects. @@ -1334,10 +1551,15 @@ enum VOICE_CONVERSION_PRESET { }; /** Audio codec profile types. The default value is LC_ACC. */ enum AUDIO_CODEC_PROFILE_TYPE { - /** 0: LC-AAC, which is the low-complexity audio codec type. */ + /** 0: (Default) LC-AAC */ AUDIO_CODEC_PROFILE_LC_AAC = 0, - /** 1: HE-AAC, which is the high-efficiency audio codec type. */ + /** 1: HE-AAC */ AUDIO_CODEC_PROFILE_HE_AAC = 1, + /** 2: HE-AAC v2 + * + * @since v3.6.0 + */ + AUDIO_CODEC_PROFILE_HE_AAC_V2 = 2, }; /** Remote audio states. @@ -1414,7 +1636,7 @@ enum REMOTE_AUDIO_STATE_REASON { /** The state of the remote video. */ enum REMOTE_VIDEO_STATE { - /** 0: The remote video is in the default state, probably due to #REMOTE_VIDEO_STATE_REASON_LOCAL_MUTED (3), #REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED (5), or #REMOTE_VIDEO_STATE_REASON_REMOTE_OFFLINE (7). + /** 0: The remote video is in the default state, probably due to #REMOTE_VIDEO_STATE_REASON_LOCAL_MUTED (3), #REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED (5), or #REMOTE_VIDEO_STATE_REASON_REMOTE_OFFLINE (7). */ REMOTE_VIDEO_STATE_STOPPED = 0, @@ -1593,13 +1815,34 @@ enum ORIENTATION_MODE { ORIENTATION_MODE_FIXED_PORTRAIT = 2, }; -/** Video degradation preferences when the bandwidth is a constraint. */ +/** Video degradation preferences under limited bandwidth. */ enum DEGRADATION_PREFERENCE { - /** 0: (Default) Degrade the frame rate in order to maintain the video 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 \ref IRtcEngineEventHandler::onVideoSizeChanged "onVideoSizeChanged". + */ MAINTAIN_QUALITY = 0, - /** 1: Degrade the video quality in order to maintain the frame rate. */ + /** 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_FRAMERATE = 1, - /** 2: (For future use) Maintain a balance between the frame rate and video quality. */ + /** 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 \ref IRtcEngineEventHandler::onVideoSizeChanged "onVideoSizeChanged". + */ MAINTAIN_BALANCED = 2, }; @@ -1696,7 +1939,9 @@ enum CONNECTION_CHANGED_REASON_TYPE { CONNECTION_CHANGED_JOIN_FAILED = 4, /** 5: The SDK has left the channel. */ CONNECTION_CHANGED_LEAVE_CHANNEL = 5, - /** 6: The connection failed since Appid is not valid. */ + /** + * 6: The specified App ID is invalid. Try to rejoin the channel with a valid App ID. + */ CONNECTION_CHANGED_INVALID_APP_ID = 6, /** 7: The connection failed since channel name is not valid. */ CONNECTION_CHANGED_INVALID_CHANNEL_NAME = 7, @@ -1724,8 +1969,6 @@ enum CONNECTION_CHANGED_REASON_TYPE { CONNECTION_CHANGED_CLIENT_IP_ADDRESS_CHANGED = 13, /** 14: Timeout for the keep-alive of the connection between the SDK and Agora's edge server. The connection state changes to CONNECTION_STATE_RECONNECTING(4). */ CONNECTION_CHANGED_KEEP_ALIVE_TIMEOUT = 14, - /** 15: In cloud proxy mode, the proxy server connection interrupted. */ - CONNECTION_CHANGED_PROXY_SERVER_INTERRUPTED = 15, }; /** Network type. */ @@ -1744,7 +1987,13 @@ enum NETWORK_TYPE { NETWORK_TYPE_MOBILE_3G = 4, /** 5: The network type is mobile 4G. */ NETWORK_TYPE_MOBILE_4G = 5, + /** 6: The network type is mobile 5G. + * + * @since v3.5.1 + */ + NETWORK_TYPE_MOBILE_5G = 6, }; +/// @cond /** * The reason for the upload failure. * @@ -1763,6 +2012,7 @@ enum UPLOAD_ERROR_REASON { */ UPLOAD_SERVER_ERROR = 2, }; +/// @endcond /** States of the last-mile network probe test. */ enum LASTMILE_PROBE_RESULT_STATE { @@ -1773,39 +2023,42 @@ enum LASTMILE_PROBE_RESULT_STATE { /** 3: The last-mile network probe test is not carried out, probably due to poor network conditions. */ LASTMILE_PROBE_RESULT_UNAVAILABLE = 3 }; -/** Audio output routing. */ +/** The current audio route. + * + * Reports in the \ref IRtcEngineEventHandler::onAudioRouteChanged "onAudioRouteChanged" callback. + */ enum AUDIO_ROUTE_TYPE { - /** Default. + /** -1: Default audio route. */ AUDIO_ROUTE_DEFAULT = -1, - /** Headset. + /** 0: The audio route is a headset with a microphone. */ AUDIO_ROUTE_HEADSET = 0, - /** Earpiece. + /** 1: The audio route is an earpiece. */ AUDIO_ROUTE_EARPIECE = 1, - /** Headset with no microphone. + /** 2: The audio route is a headset without a microphone. */ AUDIO_ROUTE_HEADSET_NO_MIC = 2, - /** Speakerphone. + /** 3: The audio route is the speaker that comes with the device. */ AUDIO_ROUTE_SPEAKERPHONE = 3, - /** Loudspeaker. + /** 4: (iOS and macOS only) The audio route is an external speaker. */ AUDIO_ROUTE_LOUDSPEAKER = 4, - /** Bluetooth headset. + /** 5: The audio route is a Bluetooth headset. */ AUDIO_ROUTE_BLUETOOTH = 5, - /** USB peripheral (macOS only). + /** 6: (macOS only) The audio route is a USB peripheral device. */ AUDIO_ROUTE_USB = 6, - /** HDMI peripheral (macOS only). + /** 7: (macOS only) The audio route is an HDMI peripheral device. */ AUDIO_ROUTE_HDMI = 7, - /** DisplayPort peripheral (macOS only). + /** 8: (macOS only) The audio route is a DisplayPort peripheral device. */ AUDIO_ROUTE_DISPLAYPORT = 8, - /** Apple AirPlay (macOS only). + /** 9: (iOS and macOS only) The audio route is Apple AirPlay. */ AUDIO_ROUTE_AIRPLAY = 9, }; @@ -1821,23 +2074,50 @@ enum CLOUD_PROXY_TYPE { /** 1: The cloud proxy for the UDP protocol. */ UDP_PROXY = 1, + /// @cond /** 2: The cloud proxy for the TCP (encrypted) protocol. */ TCP_PROXY = 2, + /// @endcond +}; +/// @cond +/** The local proxy mode type. */ +enum LOCAL_PROXY_MODE { + /** 0: Connect local proxy with high priority, if not connected to local proxy, fallback to sdrtn. + */ + kConnectivityFirst = 0, + /** 1: Only connect local proxy + */ + kLocalOnly = 1, }; +/// @endcond #if (defined(__APPLE__) && TARGET_OS_IOS) -/** Audio session restriction. */ +/** + * The operational permission of the SDK on the audio session. + */ enum AUDIO_SESSION_OPERATION_RESTRICTION { - /** No restriction, the SDK has full control of the audio session operations. */ + /** + * 0: No restriction; the SDK can change the audio session. + */ AUDIO_SESSION_OPERATION_RESTRICTION_NONE = 0, - /** The SDK does not change the audio session category. */ + /** + * 1: The SDK cannot change the audio session category. + */ AUDIO_SESSION_OPERATION_RESTRICTION_SET_CATEGORY = 1, - /** The SDK does not change any setting of the audio session (category, mode, categoryOptions). */ + /** + * 2: The SDK cannot change the audio session category, mode, or categoryOptions. + */ AUDIO_SESSION_OPERATION_RESTRICTION_CONFIGURE_SESSION = 1 << 1, - /** The SDK keeps the audio session active when leaving a channel. */ + /** + * 4: The SDK keeps the audio session active when the user leaves the + * channel, for example, to play an audio file in the background. + */ AUDIO_SESSION_OPERATION_RESTRICTION_DEACTIVATE_SESSION = 1 << 2, - /** The SDK does not configure the audio session anymore. */ + /** + * 128: Completely restricts the operational permission of the SDK on the + * audio session; the SDK cannot change the audio session. + */ AUDIO_SESSION_OPERATION_RESTRICTION_ALL = 1 << 7, }; #endif @@ -1851,13 +2131,20 @@ enum CAMERA_DIRECTION { }; #endif -/** Audio recording position. */ +/** + * Recording content, which is set + * in \ref IRtcEngine::startAudioRecording(const AudioRecordingConfiguration&) "startAudioRecording". + */ enum AUDIO_RECORDING_POSITION { - /** The SDK will record the voices of all users in the channel. */ + /** 0: (Default) Records the mixed audio of the local user and all remote + * users. + */ AUDIO_RECORDING_POSITION_MIXED_RECORDING_AND_PLAYBACK = 0, - /** The SDK will record the voice of the local user. */ + /** 1: Records the audio of the local user only. + */ AUDIO_RECORDING_POSITION_RECORDING = 1, - /** The SDK will record the voices of remote users. */ + /** 2: Records the audio of all remote users only. + */ AUDIO_RECORDING_POSITION_MIXED_PLAYBACK = 2, }; @@ -1885,11 +2172,11 @@ struct LastmileProbeResult { /** Configurations of the last-mile network probe test. */ struct LastmileProbeConfig { - /** Sets whether or not to test the uplink network. Some users, for example, the audience in a `LIVE_BROADCASTING` channel, do not need such a test: + /** Sets whether to test the uplink network. Some users, for example, the audience in a `LIVE_BROADCASTING` channel, do not need such a test: - true: test. - false: do not test. */ bool probeUplink; - /** Sets whether or not to test the downlink network: + /** Sets whether to test the downlink network: - true: test. - false: do not test. */ bool probeDownlink; @@ -1918,7 +2205,7 @@ struct AudioVolumeInfo { * * @note * - The `vad` parameter cannot report the voice activity status of remote users. - * In the remote users' callback, `vad` is always `0`. + * In the remote users' callback, `vad` is always `1`. * - To use this parameter, you must set the `report_vad` parameter to `true` * when calling \ref agora::rtc::IRtcEngine::enableAudioVolumeIndication(int, int, bool) "enableAudioVolumeIndication". */ @@ -1927,6 +2214,37 @@ struct AudioVolumeInfo { */ const char* channelId; }; + +/** + * The information of an audio file. This struct is reported + * in \ref IRtcEngineEventHandler::onRequestAudioFileInfo "onRequestAudioFileInfo". + * + * @since v3.5.1 + */ +struct AudioFileInfo { + /** The file path. + */ + const char* filePath; + /** The file duration (ms). + */ + int durationMs; +}; + +/** The information acquisition state. This enum is reported + * in \ref IRtcEngineEventHandler::onRequestAudioFileInfo "onRequestAudioFileInfo". + * + * @since v3.5.1 + */ +enum AUDIO_FILE_INFO_ERROR { + /** 0: Successfully get the information of an audio file. + */ + AUDIO_FILE_INFO_ERROR_OK = 0, + + /** 1: Fail to get the information of an audio file. + */ + AUDIO_FILE_INFO_ERROR_FAILURE = 1 +}; + /** The detailed options of a user. */ struct ClientRoleOptions { @@ -2013,7 +2331,9 @@ struct RtcStats { /** * Application CPU usage (%). * - * @note The `cpuAppUsage` reported in the \ref IRtcEngineEventHandler::onLeaveChannel "onLeaveChannel" callback is always 0. + * @note + * - The `cpuAppUsage` reported in the \ref IRtcEngineEventHandler::onLeaveChannel "onLeaveChannel" callback is always 0. + * - As of Android 8.1, you cannot get the CPU usage from this attribute due to system limitations. */ double cpuAppUsage; /** @@ -2022,10 +2342,19 @@ struct RtcStats { * In the multi-kernel environment, this member represents the average CPU usage. * The value **=** 100 **-** System Idle Progress in Task Manager (%). * - * @note The `cpuTotalUsage` reported in the \ref IRtcEngineEventHandler::onLeaveChannel "onLeaveChannel" callback is always 0. + * @note + * - The `cpuTotalUsage` reported in the \ref IRtcEngineEventHandler::onLeaveChannel "onLeaveChannel" callback is always 0. + * - As of Android 8.1, you cannot get the CPU usage from this attribute due to system limitations. */ double cpuTotalUsage; /** The round-trip time delay from the client to the local router. + * + * @note + * - On iOS, As of v3.3.0, this attribute is disabled on devices running iOS 14 or later, and enabled on devices + * running versions earlier than iOS 14 by default. To enable this property on devices running iOS 14 or later, + * contact support@agora.io. See [FAQ](https://docs.agora.io/en/Interactive%20Broadcast/faq/local_network_privacy) for details. + * - On Android, to get this attribute, ensure that the `android.permission.ACCESS_WIFI_STATE` permission has been added after `` in + * the `AndroidManifest.xml` file in your project. */ int gatewayRtt; /** @@ -2185,6 +2514,26 @@ enum CHANNEL_MEDIA_RELAY_EVENT { /** 11: The video profile is sent to the server. */ RELAY_EVENT_VIDEO_PROFILE_UPDATE = 11, + /** 12: The SDK successfully pauses relaying the media stream to destination channels. + * + * @since v3.5.1 + */ + RELAY_EVENT_PAUSE_SEND_PACKET_TO_DEST_CHANNEL_SUCCESS = 12, + /** 13: The SDK fails to pause relaying the media stream to destination channels. + * + * @since v3.5.1 + */ + RELAY_EVENT_PAUSE_SEND_PACKET_TO_DEST_CHANNEL_FAILED = 13, + /** 14: The SDK successfully resumes relaying the media stream to destination channels. + * + * @since v3.5.1 + */ + RELAY_EVENT_RESUME_SEND_PACKET_TO_DEST_CHANNEL_SUCCESS = 14, + /** 15: The SDK fails to resume relaying the media stream to destination channels. + * + * @since v3.5.1 + */ + RELAY_EVENT_RESUME_SEND_PACKET_TO_DEST_CHANNEL_FAILED = 15, }; /** The state code in CHANNEL_MEDIA_RELAY_STATE. */ @@ -2509,10 +2858,6 @@ struct VideoEncoderConfiguration { | 1920 * 1080 | 15 | 2080 | 4160 | | 1920 * 1080 | 30 | 3150 | 6300 | | 1920 * 1080 | 60 | 4780 | 6500 | - | 2560 * 1440 | 30 | 4850 | 6500 | - | 2560 * 1440 | 60 | 6500 | 6500 | - | 3840 * 2160 | 30 | 6500 | 6500 | - | 3840 * 2160 | 60 | 6500 | 6500 | */ int bitrate; @@ -2540,32 +2885,37 @@ struct VideoEncoderConfiguration { VideoEncoderConfiguration() : dimensions(640, 480), frameRate(FRAME_RATE_FPS_15), minFrameRate(-1), bitrate(STANDARD_BITRATE), minBitrate(DEFAULT_MIN_BITRATE), orientationMode(ORIENTATION_MODE_ADAPTIVE), degradationPreference(MAINTAIN_QUALITY), mirrorMode(VIDEO_MIRROR_MODE_AUTO) {} }; -/** Audio recording configurations. +/** Recording configuration, which is set in + * \ref IRtcEngine::startAudioRecording(const AudioRecordingConfiguration&) "startAudioRecording". + * + * @since v3.4.0 */ struct AudioRecordingConfiguration { - /** Pointer to the absolute file path of the recording file. The string of the file name is in UTF-8. - - The SDK determines the storage format of the recording file by the file name suffix: - - - .wav: Large file size with high fidelity. - - .aac: Small file size with low fidelity. - - Ensure that the directory to save the recording file exists and is writable. + /** The absolute path (including the filename extensions) of the recording + * file. For example: `C:\music\audio.aac`. + * + * @note Ensure that the path you specify exists and is writable. */ const char* filePath; - /** Sets the audio recording quality. See #AUDIO_RECORDING_QUALITY_TYPE. - - @note It is effective only when the recording format is AAC. + /** Audio recording quality. See #AUDIO_RECORDING_QUALITY_TYPE. + * + * @note This parameter applies to AAC files only. */ AUDIO_RECORDING_QUALITY_TYPE recordingQuality; - /** Sets the audio recording position. See #AUDIO_RECORDING_POSITION. + /** Recording content. See #AUDIO_RECORDING_POSITION. */ AUDIO_RECORDING_POSITION recordingPosition; - /** Sets the sample rate (Hz) of the recording file. Supported values are as follows: - * - 16000 - * - (Default) 32000 - * - 44100 - * - 48000 + /** Recording sample rate (Hz). The following values are supported: + * + * - `16000` + * - (Default) `32000` + * - `44100` + * - `48000` + * + * @note If this parameter is set to `44100` or `48000`, for better + * recording effects, Agora recommends recording WAV files or AAC files + * whose `recordingQuality` is + * #AUDIO_RECORDING_QUALITY_MEDIUM or #AUDIO_RECORDING_QUALITY_HIGH. */ int recordingSampleRate; AudioRecordingConfiguration() : filePath(nullptr), recordingQuality(AUDIO_RECORDING_QUALITY_MEDIUM), recordingPosition(AUDIO_RECORDING_POSITION_MIXED_RECORDING_AND_PLAYBACK), recordingSampleRate(32000) {} @@ -2629,7 +2979,7 @@ typedef struct TranscodingUser { The properties of the watermark and background images. */ typedef struct RtcImage { - RtcImage() : url(NULL), x(0), y(0), width(0), height(0) {} + RtcImage() : url(NULL), x(0), y(0), width(0), height(0), zOrder(0), alpha(1.0) {} /** HTTP/HTTPS URL address of the image on the live video. The maximum length of this parameter is 1024 bytes. */ const char* url; /** Horizontal position of the image from the upper left of the live video. */ @@ -2640,17 +2990,32 @@ typedef struct RtcImage { int width; /** Height of the image on the live video. */ int height; + /** + * The layer number of the watermark or background image. The value range is [0,255]: + * - `0`: (Default) The bottom layer. + * - `255`: The top layer. + * + * @since v3.6.0 + */ + int zOrder; + /** The transparency of the watermark or background image. The value range is [0.0,1.0]: + * - `0.0`: Completely transparent. + * - `1.0`: (Default) Opaque. + * + * @since v3.6.0 + */ + double alpha; } RtcImage; /// @cond /** The configuration for advanced features of the RTMP or RTMPS streaming with transcoding. */ typedef struct LiveStreamAdvancedFeature { LiveStreamAdvancedFeature() : featureName(NULL), opened(false) {} - + LiveStreamAdvancedFeature(const char* feat_name, bool open) : featureName(feat_name), opened(open) {} /** The advanced feature for high-quality video with a lower bitrate. */ - const char* LBHQ = "lbhq"; + // static const char* LBHQ = "lbhq"; /** The advanced feature for the optimized video encoder. */ - const char* VEO = "veo"; + // static const char* VEO = "veo"; /** The name of the advanced feature. It contains LBHQ and VEO. */ @@ -2662,17 +3027,22 @@ typedef struct LiveStreamAdvancedFeature { */ bool opened; } LiveStreamAdvancedFeature; + /// @endcond /** A struct for managing CDN live audio/video transcoding settings. */ typedef struct LiveTranscoding { /** The width of the video in pixels. The default value is 360. - * - When pushing video streams to the CDN, ensure that `width` is at least 64; otherwise, the Agora server adjusts the value to 64. + * - When pushing video streams to the CDN, the value range of `width` is [64,1920]. + * If the value is less than 64, Agora server automatically adjusts it to 64; if the + * value is greater than 1920, Agora server automatically adjusts it to 1920. * - When pushing audio streams to the CDN, set `width` and `height` as 0. */ int width; /** The height of the video in pixels. The default value is 640. - * - When pushing video streams to the CDN, ensure that `height` is at least 64; otherwise, the Agora server adjusts the value to 64. + * - When pushing video streams to the CDN, the value range of `height` is [64,1080]. + * If the value is less than 64, Agora server automatically adjusts it to 64; if the + * value is greater than 1080, Agora server automatically adjusts it to 1080. * - When pushing audio streams to the CDN, set `width` and `height` as 0. */ int height; @@ -2706,10 +3076,16 @@ typedef struct LiveTranscoding { */ unsigned int backgroundColor; - /** video codec type */ + /** + * The video codec type of the output video stream. See #VIDEO_CODEC_TYPE_FOR_STREAM. + * + * @since v3.2.0 + */ VIDEO_CODEC_TYPE_FOR_STREAM videoCodecType; /** The number of users in the interactive live streaming. + * + * The value range is [0, 17]. */ unsigned int userCount; /** TranscodingUser @@ -2724,16 +3100,33 @@ typedef struct LiveTranscoding { /** **DEPRECATED** The metadata sent to the CDN live client defined by the RTMP or HTTP-FLV metadata. */ const char* metadata; - /** The watermark image added to the CDN live publishing stream. - - Ensure that the format of the image is PNG. Once a watermark image is added, the audience of the CDN live publishing stream can see the watermark image. See RtcImage. - */ + /** + * The watermark on the live video. The format must be in the PNG format. See RtcImage. + * You can add a watermark or use an array to add multiple watermarks. + * This parameter is used in conjunction with `watermarkCount`. + */ RtcImage* watermark; - /** The background image added to the CDN live publishing stream. - Once a background image is added, the audience of the CDN live publishing stream can see the background image. See RtcImage. - */ + /** + * The number of watermarks on the live video. The value range is [0,100]. + * This parameter is used in conjunction with `watermark`. + * + * @since v3.6.0 + */ + unsigned int watermarkCount; + + /** + * The background image on the live video. The format must be in the PNG format. See RtcImage. + * You can add a background image or use an array to add multiple background images. + * This parameter is used in conjunction with `backgroundImageCount`. + */ RtcImage* backgroundImage; + /** + * The number of background images on the live video. The value range is [0,100]. + * This parameter is used in conjunction with `backgroundImage`. + */ + unsigned int backgroundImageCount; + /** Self-defined audio-sample rate: #AUDIO_SAMPLE_RATE_TYPE. */ AUDIO_SAMPLE_RATE_TYPE audioSampleRate; @@ -2763,7 +3156,7 @@ typedef struct LiveTranscoding { /** The number of enabled advanced features. The default value is 0. */ unsigned int advancedFeatureCount; /// @endcond - LiveTranscoding() : width(360), height(640), videoBitrate(400), videoFramerate(15), lowLatency(false), videoGop(30), videoCodecProfile(VIDEO_CODEC_PROFILE_HIGH), backgroundColor(0x000000), videoCodecType(VIDEO_CODEC_H264_FOR_STREAM), userCount(0), transcodingUsers(NULL), transcodingExtraInfo(NULL), metadata(NULL), watermark(NULL), backgroundImage(NULL), audioSampleRate(AUDIO_SAMPLE_RATE_48000), audioBitrate(48), audioChannels(1), audioCodecProfile(AUDIO_CODEC_PROFILE_LC_AAC), advancedFeatures(NULL), advancedFeatureCount(0) {} + LiveTranscoding() : width(360), height(640), videoBitrate(400), videoFramerate(15), lowLatency(false), videoGop(30), videoCodecProfile(VIDEO_CODEC_PROFILE_HIGH), backgroundColor(0x000000), videoCodecType(VIDEO_CODEC_H264_FOR_STREAM), 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), advancedFeatures(NULL), advancedFeatureCount(0) {} } LiveTranscoding; /** Camera capturer configuration. @@ -2916,6 +3309,29 @@ struct ChannelMediaRelayConfiguration { ChannelMediaRelayConfiguration() : srcInfo(nullptr), destInfos(nullptr), destCount(0) {} }; +/// @cond +struct LocalAccessPointConfiguration { + /** local access point ip address list. + */ + const char** ipList; + /** the number of local access point ip address. + */ + int ipListSize; + /** local access point domain list. + */ + const char** domainList; + /** the number of local access point domain. + */ + int domainListSize; + /** certificate domain name installed on specific local access point. pass "" means using sni domain on specific local access point + */ + const char* verifyDomainName; + /** local proxy connection mode, connectivity first or local only. + */ + LOCAL_PROXY_MODE mode; + LocalAccessPointConfiguration() : ipList(nullptr), ipListSize(0), domainList(nullptr), domainListSize(0), verifyDomainName(nullptr), mode(kConnectivityFirst) {} +}; +/// @endcond /** **DEPRECATED** Lifecycle of the CDN live video stream. */ @@ -3025,7 +3441,7 @@ struct ScreenCaptureParameters { The default value is 0 (the SDK works out a bitrate according to the dimensions of the current screen). */ int bitrate; - /** Sets whether or not to capture the mouse for screen sharing: + /** Sets whether to capture the mouse for screen sharing: - true: (Default) Capture the mouse. - false: Do not capture the mouse. @@ -3098,10 +3514,10 @@ struct VideoCanvas { /** Image enhancement options. */ struct BeautyOptions { - /** The contrast level, used with the @p lightening parameter. + /** The contrast level, often used in conjunction with `lighteningLevel`. */ enum LIGHTENING_CONTRAST_LEVEL { - /** Low contrast level. */ + /** 0: Low contrast level. */ LIGHTENING_CONTRAST_LOW = 0, /** (Default) Normal contrast level. */ LIGHTENING_CONTRAST_NORMAL, @@ -3109,42 +3525,175 @@ struct BeautyOptions { LIGHTENING_CONTRAST_HIGH }; - /** The contrast level, used with the @p lightening parameter. + /** The contrast level, often used in conjunction with `lighteningLevel`. + * The higher the value, the greater the contrast level. See #LIGHTENING_CONTRAST_LEVEL. */ LIGHTENING_CONTRAST_LEVEL lighteningContrastLevel; - /** The brightness level. The value ranges from 0.0 (original) to 1.0. */ + /** + * The brightening level, in the range [0.0,1.0], where 0.0 means the original brightening. The default value is 0.6. The higher the value, the greater the brightening level. + */ float lighteningLevel; - /** The sharpness level. The value ranges between 0 (original) and 1. This parameter is usually used to remove blemishes. + /** The smoothness level, in the range [0.0,1.0], where 0.0 means the original smoothness. The default value is 0.5. The higher the value, the greater the smoothness level. */ float smoothnessLevel; - /** The redness level. The value ranges between 0 (original) and 1. This parameter adjusts the red saturation level. + /** The redness level, in the range [0.0,1.0], where 0.0 means the original redness. The default value is 0.1. The higher the value, the greater the redness level. */ float rednessLevel; - BeautyOptions(LIGHTENING_CONTRAST_LEVEL contrastLevel, float lightening, float smoothness, float redness) : lighteningLevel(lightening), smoothnessLevel(smoothness), rednessLevel(redness), lighteningContrastLevel(contrastLevel) {} + /** The sharpness level, in the range [0.0,1.0], where 0.0 means the original sharpness. + * The default value is 0.3. The higher the value, the greater the sharpness level. + * + * @since v3.6.0 + */ + float sharpnessLevel; + + BeautyOptions(LIGHTENING_CONTRAST_LEVEL contrastLevel, float lightening, float smoothness, float redness, float sharpness) : lighteningLevel(lightening), smoothnessLevel(smoothness), rednessLevel(redness), lighteningContrastLevel(contrastLevel), sharpnessLevel(sharpness) {} - BeautyOptions() : lighteningLevel(0), smoothnessLevel(0), rednessLevel(0), lighteningContrastLevel(LIGHTENING_CONTRAST_NORMAL) {} + BeautyOptions() : lighteningLevel(0), smoothnessLevel(0), rednessLevel(0), sharpnessLevel(0), lighteningContrastLevel(LIGHTENING_CONTRAST_NORMAL) {} }; -/** - * The UserInfo struct. +/** The custom background image. + * + * @since v3.4.5 */ -struct UserInfo { - /** - * The user ID. +struct VirtualBackgroundSource { + /** The type of the custom background image. + * + * @since v3.4.5 */ - uid_t uid; + enum BACKGROUND_SOURCE_TYPE { + /** + * 1: (Default) The background image is a solid color. + */ + BACKGROUND_COLOR = 1, + /** + * The background image is a file in PNG or JPG format. + */ + BACKGROUND_IMG, + /** + * The background image is blurred. + * + * @since v3.5.1 + */ + BACKGROUND_BLUR, + }; + /** - * The user account. + * The degree of blurring applied to the custom background image. + * + * @since v3.5.1 */ - char userAccount[MAX_USER_ACCOUNT_LENGTH]; - UserInfo() : uid(0) { userAccount[0] = '\0'; } -}; + enum BACKGROUND_BLUR_DEGREE { + /** + * 1: The degree of blurring applied to the custom background image is low. + * The user can almost see the background clearly. + */ + BLUR_DEGREE_LOW = 1, + /** + * 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_MEDIUM, + /** + * (Default) The degree of blurring applied to the custom background image is high. + * The user can barely see any distinguishing features in the background. + */ + BLUR_DEGREE_HIGH, + }; -/** + /** The type of the custom background image. See #BACKGROUND_SOURCE_TYPE. + */ + BACKGROUND_SOURCE_TYPE background_source_type; + + /** + * 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`. + */ + unsigned int color; + + /** + * 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`. + */ + const char* source; + + /** + * The degree of blurring applied to the custom background image. See #BACKGROUND_BLUR_DEGREE. + * + * @note This parameter takes effect only when the type of the custom background image is `BACKGROUND_BLUR`. + * + * @since v3.5.1 + */ + BACKGROUND_BLUR_DEGREE blur_degree; + + VirtualBackgroundSource() : color(0xffffff), source(NULL), background_source_type(BACKGROUND_COLOR), blur_degree(BLUR_DEGREE_HIGH) {} +}; + +/** + * The UserInfo struct. + */ +struct UserInfo { + /** + * The user ID. + */ + uid_t uid; + /** + * The user account. + */ + char userAccount[MAX_USER_ACCOUNT_LENGTH]; + UserInfo() : uid(0) { userAccount[0] = '\0'; } +}; +/** + * The configuration of the audio and video call loop test. + * + * @since v3.5.2 + */ +struct EchoTestConfiguration { + /** + * The view used to render the local user's video. This parameter is only applicable to scenarios testing video + * devices, that is, when `enableVideo` is `true`. + */ + view_t view; + /** + * Whether to enable the audio device for the call loop test: + * - true: (Default) Enables the audio device. To test the audio device, set this parameter as `true`. + * - false: Disables the audio device. + */ + bool enableAudio; + /** + * Whether to enable the video device for the call loop test: + * - true: (Default) Enables the video device. To test the video device, set this parameter as `true`. + * - false: Disables the video device. + */ + bool enableVideo; + /** + * The token used to secure the audio and video call loop test. If you do not enable App Certificate in Agora + * Console, you do not need to pass a value in this parameter; if you have enabled App Certificate in Agora Console, + * you must pass a token in this parameter, the `uid` used when you generate the token must be 0xFFFFFFFF, and the + * channel name used must be the channel name that identifies each audio and video call loop tested. For server-side + * token generation, see [Authenticate Your Users with Tokens](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=All%20Platforms). + */ + const char* token; + /** + * The channel name that identifies each audio and video call loop. To ensure proper loop test functionality, the + * channel name passed in to identify each loop test cannot be the same when users of the same project (App ID) + * perform audio and video call loop tests on different devices. + */ + const char* channelId; + EchoTestConfiguration() : view(NULL), enableAudio(true), enableVideo(true), token(NULL), channelId(NULL) {} + EchoTestConfiguration(view_t v, bool ea, bool ev, const char* t, const char* c) : view(v), enableAudio(ea), enableVideo(ev), token(t), channelId(c) {} +}; + +/** * Regions for connetion. */ enum AREA_CODE { @@ -3190,6 +3739,71 @@ enum ENCRYPTION_CONFIG { */ ENCRYPTION_FORCE_DISABLE_PACKET = (1 << 1) }; +/// @cond +typedef int ContentInspectType; +/** + * (Default) content inspect type invalid + */ +const ContentInspectType kContentInspectInvalid = 0; +/** + * Content inspect type moderation + */ +const ContentInspectType kContentInspectModeration = 1; +/** + * Content inspect type supervise + */ +const ContentInspectType kContentInspectSupervise = 2; + +enum MAX_CONTENT_INSPECT_MODULE_TYPE { + /** The maximum count of content inspect feature type is 32. + */ + MAX_CONTENT_INSPECT_MODULE_COUNT = 32 +}; +/// @endcond +/// @cond +/** Definition of ContentInspectModule. + */ +struct ContentInspectModule { + /** + * The content inspect module type. + * the module type can be 0 to 31. + * kContentInspectInvalid(0) + * kContentInspectModeration(1) + * kContentInspectSupervise(2) + */ + ContentInspectType type; + /**The content inspect frequency, default is 0 second. + * the frequency <= 0 is invalid. + */ + int interval; + /**The content inspect default value. + */ + ContentInspectModule() { + type = kContentInspectInvalid; + interval = 0; + } +}; +/// @endcond +/// @cond +/** Definition of ContentInspectConfig. + */ +struct ContentInspectConfig { + /** The extra information, max length of extraInfo is 1024. + * The extra information will send to server with content(image). + */ + const char* extraInfo; + /**The content inspect modules, max length of modules is 32. + * the content(snapshot of send video stream, image) can be used to max of 32 types functions. + */ + ContentInspectModule modules[MAX_CONTENT_INSPECT_MODULE_COUNT]; + /**The content inspect module count. + */ + int moduleCount; + + ContentInspectConfig() : extraInfo(NULL), moduleCount(0) {} +}; +/// @endcond + /** Definition of IPacketObserver. */ class IPacketObserver { @@ -3198,7 +3812,9 @@ class IPacketObserver { */ struct Packet { /** Buffer address of the sent or received data. - * @note Agora recommends that the value of buffer is more than 2048 bytes, otherwise, you may meet undefined behaviors such as a crash. + * + * @note Agora recommends that the value of buffer is more than 2048 bytes, + * otherwise, you may meet undefined behaviors such as a crash. */ const unsigned char* buffer; /** Buffer size of the sent or received data. @@ -3351,6 +3967,158 @@ class IVideoSource { }; #endif +#if (defined(__APPLE__) && TARGET_OS_MAC && !TARGET_OS_IPHONE) +/** + * The target size of the thumbnail or icon. (macOS only) + * + * @since v3.5.2 + */ +struct SIZE { + /** The target width (px) of the thumbnail or icon. The default value is 0. + */ + int width; + /** The target height (px) of the thumbnail or icon. The default value is 0. + */ + int height; + + SIZE() : width(0), height(0) {} + SIZE(int w, int h) : width(w), height(h) {} +}; +#endif +/** + * The image content of the thumbnail or icon. + * + * @since v3.5.2 + * + * @note The default image is in the RGBA format. If you need to use another format, you need to convert the image on + * your own. + */ +struct ThumbImageBuffer { + /** + * The buffer of the thumbnail or icon. + */ + const char* buffer; + /** + * The buffer length (bytes) of the thumbnail or icon. + */ + unsigned int length; + /** + * The actual width (px) of the thumbnail or icon. + */ + unsigned int width; + /** + * The actual height (px) of the thumbnail or icon. + */ + unsigned int height; + ThumbImageBuffer() : buffer(nullptr), length(0), width(0), height(0) {} +}; +/** + * The type of the shared target. + * + * @since v3.5.2 + */ +enum ScreenCaptureSourceType { + /** + * -1: Unknown type. + */ + ScreenCaptureSourceType_Unknown = -1, + /** + * 0: The shared target is a window. + */ + ScreenCaptureSourceType_Window = 0, + /** + * 1: The shared target is a screen of a particular monitor. + */ + ScreenCaptureSourceType_Screen = 1, + /** + * 2: Reserved parameter. + */ + ScreenCaptureSourceType_Custom = 2, +}; +/** + * The information about the specified shareable window or screen. + * + * @since v3.5.2 + */ +struct ScreenCaptureSourceInfo { + /** + * The type of the shared target. See \ref agora::rtc::ScreenCaptureSourceType "ScreenCaptureSourceType". + */ + ScreenCaptureSourceType type; + /** + * The window ID for a window or the display ID for a screen. + */ + view_t sourceId; + /** + * The name of the window or screen. UTF-8 encoding. + */ + const char* sourceName; + /** + * The image content of the thumbnail. See ThumbImageBuffer. + */ + ThumbImageBuffer thumbImage; + /** + * The image content of the icon. See ThumbImageBuffer. + */ + ThumbImageBuffer iconImage; + /** + * The process to which the window belongs. UTF-8 encoding. + */ + const char* processPath; + /** + * The title of the window. UTF-8 encoding. + */ + const char* sourceTitle; + /** + * Determines whether the screen is the primary display: + * - true: The screen is the primary display. + * - false: The screen is not the primary display. + */ + bool primaryMonitor; + ScreenCaptureSourceInfo() : type(ScreenCaptureSourceType_Unknown), sourceId(nullptr), sourceName(nullptr), processPath(nullptr), sourceTitle(nullptr), primaryMonitor(false) {} +}; +/** + * The IScreenCaptureSourceList class. + * + * @since v3.5.2 + */ +class IScreenCaptureSourceList { + protected: + virtual ~IScreenCaptureSourceList(){}; + + public: + /** + * Gets the number of shareable windows and screens. + * + * @since v3.5.2 + * + * @return The number of shareable windows and screens. + */ + virtual unsigned int getCount() = 0; + /** + * Gets information about the specified shareable window or screen. + * + * @since v3.5.2 + * + * After you get IScreenCaptureSourceList, you can pass in the index value of the specified shareable window or + * screen to get information about that window or screen from ScreenCaptureSourceInfo. + * + * @param index The index of the specified shareable window or screen. The value range is [0,`getCount()`). + * + * @return ScreenCaptureSourceInfo + */ + virtual ScreenCaptureSourceInfo getSourceInfo(unsigned int index) = 0; + /** + * Releases IScreenCaptureSourceList. + * + * @since v3.5.2 + * + * After you get the list of shareable windows and screens, to avoid memory leaks, call `release` to release + * `IScreenCaptureSourceList` instead of deleting `IScreenCaptureSourceList` directly. + */ + virtual void release() = 0; +}; + /** The SDK uses the IRtcEngineEventHandler interface class to send callbacks to the application. The application inherits the methods of this interface class to retrieve these callbacks. All methods in this interface class have default (empty) implementations. Therefore, the application can only inherit some required events. In the callbacks, avoid time-consuming tasks or calling blocking APIs, such as the SendMessage method. Otherwise, the SDK may not work properly. @@ -3421,7 +4189,7 @@ class IRtcEngineEventHandler { This callback notifies the application that a user leaves the channel when the application calls the \ref IRtcEngine::leaveChannel "leaveChannel" method. - The application retrieves information, such as the call duration and statistics. + The application gets information, such as the call duration and statistics. @param stats Pointer to the statistics of the call: RtcStats. */ @@ -3556,7 +4324,7 @@ class IRtcEngineEventHandler { The user becomes offline if the token used in the \ref IRtcEngine::joinChannel "joinChannel" method expires. The SDK triggers this callback 30 seconds before the token expires to remind the application to get a new token. Upon receiving this callback, generate a new token on the server and call the \ref IRtcEngine::renewToken "renewToken" method to pass the new token to the SDK. - @param token Pointer to the token that expires in 30 seconds. + @param token The token that expires in 30 seconds. */ virtual void onTokenPrivilegeWillExpire(const char* token) { (void)token; } @@ -3587,12 +4355,16 @@ class IRtcEngineEventHandler { virtual void onRtcStats(const RtcStats& stats) { (void)stats; } /** Reports the last mile network quality of each user in the channel once every two seconds. - - Last mile refers to the connection between the local device and Agora's edge server. This callback reports once every two seconds the last mile network conditions of each user in the channel. If a channel includes multiple users, the SDK triggers this callback as many times. - - @param uid User ID. The network quality of the user with this @p uid is reported. If @p uid is 0, the local network quality is reported. - @param txQuality Uplink transmission quality rating of the user in terms of the transmission bitrate, packet loss rate, average RTT (Round-Trip Time), and jitter of the uplink network. @p txQuality is a quality rating helping you understand how well the current uplink network conditions can support the selected VideoEncoderConfiguration. 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 may be inadequate for resolutions higher than 1280 * 720. See #QUALITY_TYPE. - @param rxQuality Downlink network quality rating of the user in terms of the packet loss rate, average RTT, and jitter of the downlink network. See #QUALITY_TYPE. + * + * Last mile refers to the connection between the local device and Agora's edge server. This callback + * reports once every two seconds the last mile network conditions of each user in the channel. If a channel includes + * multiple users, the SDK triggers this callback as many times. + * + * @note `txQuality` is `UNKNOWN` when the user is not sending a stream; `rxQuality` is `UNKNOWN` when the user is not receiving a stream. + * + * @param uid User ID. The network quality of the user with this @p uid is reported. If @p uid is 0, the local network quality is reported. + * @param txQuality Uplink transmission quality rating of the user in terms of the transmission bitrate, packet loss rate, average RTT (Round-Trip Time), and jitter of the uplink network. @p txQuality is a quality rating helping you understand how well the current uplink network conditions can support the selected VideoEncoderConfiguration. 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 may be inadequate for resolutions higher than 1280 * 720. See #QUALITY_TYPE. + * @param rxQuality Downlink network quality rating of the user in terms of the packet loss rate, average RTT, and jitter of the downlink network. See #QUALITY_TYPE. */ virtual void onNetworkQuality(uid_t uid, int txQuality, int rxQuality) { (void)uid; @@ -3666,17 +4438,18 @@ class IRtcEngineEventHandler { } /** Occurs when the remote audio state changes. - - This callback indicates the state change of the remote audio stream. - @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. - - @param uid ID of the remote user whose audio state changes. - @param state State of the remote audio. See #REMOTE_AUDIO_STATE. - @param reason The reason of the remote audio state change. - See #REMOTE_AUDIO_STATE_REASON. - @param elapsed Time elapsed (ms) from the local user calling the - \ref IRtcEngine::joinChannel "joinChannel" method until the SDK - triggers this callback. + * + * This callback indicates the state change of the remote audio stream. + * + * @note This callback can be inaccurate when the number of users (in the `COMMUNICATION` profile) + * or hosts (in the `LIVE_BROADCASTING` profile) in a channel exceeds 17. + * + * @param uid ID of the remote user whose audio state changes. + * @param state State of the remote audio. See #REMOTE_AUDIO_STATE. + * @param reason The reason of the remote audio state change. See #REMOTE_AUDIO_STATE_REASON. + * @param elapsed Time elapsed (ms) from the local user calling the + * \ref IRtcEngine::joinChannel "joinChannel" method until the SDK + * triggers this callback. */ virtual void onRemoteAudioStateChanged(uid_t uid, REMOTE_AUDIO_STATE state, REMOTE_AUDIO_STATE_REASON reason, int elapsed) { (void)uid; @@ -3790,7 +4563,7 @@ class IRtcEngineEventHandler { * - In the remote users' callback, totalVolume is the sum of the volume of all remote users (up to three) whose * instantaneous volumes are the highest. * - * If the user calls \ref agora::rtc::IRtcEngine::startAudioMixing "startAudioMixing", `totalVolume` is the sum of + * If the user calls \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing", `totalVolume` is the sum of * the voice volume and audio-mixing volume. */ virtual void onAudioVolumeIndication(const AudioVolumeInfo* speakers, unsigned int speakerNumber, int totalVolume) { @@ -3799,7 +4572,7 @@ class IRtcEngineEventHandler { (void)totalVolume; } - /** Occurs when the most active speaker is detected. + /** Occurs when the most active remote speaker is detected. After a successful call of \ref IRtcEngine::enableAudioVolumeIndication(int, int, bool) "enableAudioVolumeIndication", the SDK continuously detects which remote user has the loudest volume. During the current period, the remote user, @@ -3809,7 +4582,7 @@ class IRtcEngineEventHandler { - If the most active speaker is always the same user, the SDK triggers this 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. - @param uid The user ID of the most active speaker. + @param uid The user ID of the most active remote speaker. */ virtual void onActiveSpeaker(uid_t uid) { (void)uid; } @@ -3849,14 +4622,6 @@ class IRtcEngineEventHandler { virtual void onFirstLocalVideoFramePublished(int elapsed) { (void)elapsed; } /** Occurs when the first remote video frame is received and decoded. - * - * @deprecated v2.9.0 - * - * This callback is deprecated and replaced by the - * \ref onRemoteVideoStateChanged() "onRemoteVideoStateChanged" callback - * with the following parameters: - * - #REMOTE_VIDEO_STATE_STARTING (1) - * - #REMOTE_VIDEO_STATE_DECODING (2) * * This callback is triggered in either of the following scenarios: * @@ -3881,7 +4646,7 @@ class IRtcEngineEventHandler { * \ref IRtcEngine::joinChannel "joinChannel" method until the SDK * triggers this callback. */ - virtual void onFirstRemoteVideoDecoded(uid_t uid, int width, int height, int elapsed) { + virtual void onFirstRemoteVideoDecoded(uid_t uid, int width, int height, int elapsed) AGORA_DEPRECATED_ATTRIBUTE { (void)uid; (void)width; (void)height; @@ -3889,7 +4654,7 @@ class IRtcEngineEventHandler { } /** Occurs when the first remote video frame is rendered. - The SDK triggers this callback when the first frame of the remote video is displayed in the user's video window. The application can retrieve the time elapsed from a user joining the channel until the first video frame is displayed. + The SDK triggers this callback when the first frame of the remote video is displayed in the user's video window. The application can get the time elapsed from a user joining the channel until the first video frame is displayed. @param uid User ID of the remote user sending the video stream. @param width Width (px) of the video frame. @@ -3903,46 +4668,38 @@ class IRtcEngineEventHandler { (void)elapsed; } - /** @deprecated This method is deprecated from v3.0.0, use the \ref agora::rtc::IRtcEngineEventHandler::onRemoteAudioStateChanged "onRemoteAudioStateChanged" callback instead. - - Occurs when a remote user's audio stream playback pauses/resumes. - - The SDK triggers this callback when the remote user stops or resumes sending the audio stream by calling the \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" 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. - - @param uid User ID of the remote user. - @param muted Whether the remote user's audio stream is muted/unmuted: - - true: Muted. - - false: Unmuted. + /** Occurs when a remote user's audio stream playback pauses/resumes. + * + * The SDK triggers this callback when the remote user stops or resumes sending the audio stream by calling the \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" method. + * + * @note This callback can be inaccurate when the number of users (in the `COMMUNICATION` profile) + * or hosts (in the `LIVE_BROADCASTING` profile) in a channel exceeds 17. + * + * @param uid User ID of the remote user. + * @param muted Whether the remote user's audio stream is muted/unmuted: + * - true: Muted. + * - false: Unmuted. */ virtual void onUserMuteAudio(uid_t uid, bool muted) { (void)uid; (void)muted; } - /** Occurs when a remote user's video stream playback pauses/resumes. - * - * You can also use the - * \ref onRemoteVideoStateChanged() "onRemoteVideoStateChanged" callback - * with the following parameters: - * - #REMOTE_VIDEO_STATE_STOPPED (0) and - * #REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED (5). - * - #REMOTE_VIDEO_STATE_DECODING (2) and - * #REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED (6). + /** + * Occurs when a remote user stops or resumes publishing the video stream. * - * The SDK triggers this callback when the remote user stops or resumes - * sending the video stream by calling the - * \ref agora::rtc::IRtcEngine::muteLocalVideoStream - * "muteLocalVideoStream" method. + * When a remote user calls \ref IRtcEngine::muteLocalVideoStream "muteLocalVideoStream" to + * stop or resume publishing the video stream, the SDK triggers this callback to report the + * state of the remote user's publishing stream to the local user. * - * @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. + * @note This callback can be inaccurate when the number of users + * (in the `COMMUNICATION` profile) or hosts (in the `LIVE_BROADCASTING` profile) in a + * channel exceeds 17. * - * @param uid User ID of the remote user. - * @param muted Whether the remote user's video stream playback is - * paused/resumed: - * - true: Paused. - * - false: Resumed. + * @param uid The user ID of the remote user. + * @param muted Whether the remote user stops publishing the video stream: + * - true: Stop publishing the video stream. + * - false: Publish the video stream. */ virtual void onUserMuteVideo(uid_t uid, bool muted) { (void)uid; @@ -3952,16 +4709,6 @@ class IRtcEngineEventHandler { /** Occurs when a specific remote user enables/disables the video * module. * - * @deprecated v2.9.0 - * - * This callback is deprecated and replaced by the - * \ref onRemoteVideoStateChanged() "onRemoteVideoStateChanged" callback - * with the following parameters: - * - #REMOTE_VIDEO_STATE_STOPPED (0) and - * #REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED (5). - * - #REMOTE_VIDEO_STATE_DECODING (2) and - * #REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED (6). - * * Once the video module is disabled, the remote user can only use a * voice call. The remote user cannot send or receive any video from * other users. @@ -3987,12 +4734,16 @@ class IRtcEngineEventHandler { } /** Occurs when the audio device state changes. - - This callback notifies the application that the system's audio device state is changed. For example, a headset is unplugged from the device. - - @param deviceId Pointer to the device ID. - @param deviceType Device type: #MEDIA_DEVICE_TYPE. - @param deviceState Device state: #MEDIA_DEVICE_STATE_TYPE. + * + * This callback notifies the application that the system's audio device state is changed. For example, a headset is unplugged from the device. + * + * @param deviceId Pointer to the device ID. + * @param deviceType Device type: #MEDIA_DEVICE_TYPE. + * @param deviceState The state of the device: + * - On macOS: + * - 0: The device is ready for use. + * - 8: The device is not connected. + * - On Windows: #MEDIA_DEVICE_STATE_TYPE. */ virtual void onAudioDeviceStateChanged(const char* deviceId, int deviceType, int deviceState) { (void)deviceId; @@ -4096,33 +4847,46 @@ class IRtcEngineEventHandler { **DEPRECATED** use onAudioMixingStateChanged instead. - You can start an audio mixing file playback by calling the \ref IRtcEngine::startAudioMixing "startAudioMixing" method. The SDK triggers this callback when the audio mixing file playback finishes. + You can start an audio mixing file playback by calling the \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" method. The SDK triggers this callback when the audio mixing file playback finishes. If the *startAudioMixing* method call fails, an error code returns in the \ref IRtcEngineEventHandler::onError "onError" callback. */ virtual void onAudioMixingFinished() {} - /** Occurs when the state of the local user's audio mixing file changes. - - When you call the \ref IRtcEngine::startAudioMixing "startAudioMixing" method and the state of audio mixing file changes, the SDK triggers this callback. - - When the audio mixing file plays, pauses playing, or stops playing, this callback returns 710, 711, or 713 in @p state, and corresponding reason in @p reason. - - When exceptions occur during playback, this callback returns 714 in @p state and an error reason in @p reason. - - 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 AUDIO_MIXING_REASON_CAN_NOT_OPEN = 701. - - @param state The state code. See #AUDIO_MIXING_STATE_TYPE. - @param reason The reason code. See #AUDIO_MIXING_REASON_TYPE. + /** Occurs when the state of the local user's music file changes. + * + * @since v3.4.0 + * + * When the playback state of the local user's music file changes, the SDK triggers this callback and + * reports the current playback state and the reason for the change. + * + * @param state The current music file playback state. See #AUDIO_MIXING_STATE_TYPE. + * @param reason The reason for the change of the music file playback state. See #AUDIO_MIXING_REASON_TYPE. */ virtual void onAudioMixingStateChanged(AUDIO_MIXING_STATE_TYPE state, AUDIO_MIXING_REASON_TYPE reason) {} /** Occurs when a remote user starts audio mixing. - When a remote user calls \ref IRtcEngine::startAudioMixing "startAudioMixing" to play the background music, the SDK reports this callback. + When a remote user calls \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" to play the background music, the SDK reports this callback. */ virtual void onRemoteAudioMixingBegin() {} /** Occurs when a remote user finishes audio mixing. */ virtual void onRemoteAudioMixingEnd() {} + /** + * Reports the information of an audio file. + * + * @since v3.5.1 + * + * After successfully calling \ref IRtcEngine::getAudioFileInfo "getAudioFileInfo", the SDK triggers this + * callback to report the information of the audio file, such as the file path and duration. + * + * @param info The information of an audio file. See AudioFileInfo. + * @param error The information acquisition state. See #AUDIO_FILE_INFO_ERROR. + */ + virtual void onRequestAudioFileInfo(const AudioFileInfo& info, AUDIO_FILE_INFO_ERROR error) {} + /** Occurs when the local audio effect playback finishes. The SDK triggers this callback when the local audio effect file playback finishes. @@ -4130,9 +4894,11 @@ class IRtcEngineEventHandler { @param soundId ID of the local audio effect. Each local audio effect has a unique ID. */ virtual void onAudioEffectFinished(int soundId) {} + /// @cond /** Occurs when AirPlay is connected. */ virtual void onAirPlayConnected() {} + /// @endcond /** Occurs when the SDK decodes the first remote audio frame for playback. @@ -4153,18 +4919,22 @@ class IRtcEngineEventHandler { @param uid User ID of the remote user sending the audio stream. @param elapsed Time elapsed (ms) from the local user calling the \ref IRtcEngine::joinChannel "joinChannel" method until the SDK triggers this callback. */ - virtual void onFirstRemoteAudioDecoded(uid_t uid, int elapsed) { + virtual void onFirstRemoteAudioDecoded(uid_t uid, int elapsed) AGORA_DEPRECATED_ATTRIBUTE { (void)uid; (void)elapsed; } /** Occurs when the video device state changes. - - @note On a Windows device with an external camera for video capturing, the video disables once the external camera is unplugged. - - @param deviceId Pointer to the device ID of the video device that changes state. - @param deviceType Device type: #MEDIA_DEVICE_TYPE. - @param deviceState Device state: #MEDIA_DEVICE_STATE_TYPE. + * + * @note On a Windows device with an external camera for video capturing, the video disables once the external camera is unplugged. + * + * @param deviceId Pointer to the device ID of the video device that changes state. + * @param deviceType Device type: #MEDIA_DEVICE_TYPE. + * @param deviceState The state of the device: + * - On macOS: + * - 0: The device is ready for use. + * - 8: The device is not connected. + * - On Windows: #MEDIA_DEVICE_STATE_TYPE. */ virtual void onVideoDeviceStateChanged(const char* deviceId, int deviceType, int deviceState) { (void)deviceId; @@ -4176,12 +4946,12 @@ class IRtcEngineEventHandler { * * 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(LOCAL_VIDEO_STREAM_STATE_FAILED，LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE)` callback in the following situations: + * The SDK triggers the `onLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_FAILED, LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE)` callback in the following situations: * - The application exits to the background, and the system recycles the camera. * - The camera starts normally, but the captured video is not output for four seconds. * * When the camera outputs the captured video frames, if all the video frames are the same for 15 consecutive frames, the SDK triggers the - * `onLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_CAPTURING，LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE)` callback. Note that the + * `onLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_CAPTURING, LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE)` callback. 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. * @@ -4209,15 +4979,16 @@ class IRtcEngineEventHandler { (void)rotation; } /** Occurs when the remote video state changes. - @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. - - @param uid ID of the remote user whose video state changes. - @param state State of the remote video. See #REMOTE_VIDEO_STATE. - @param reason The reason of the remote video state change. See - #REMOTE_VIDEO_STATE_REASON. - @param elapsed Time elapsed (ms) from the local user calling the - \ref agora::rtc::IRtcEngine::joinChannel "joinChannel" method until the - SDK triggers this callback. + * + * @note This callback can be inaccurate when the number of users (in the `COMMUNICATION` profile) + * or hosts (in the `LIVE_BROADCASTING` profile) in a channel exceeds 17. + * + * @param uid ID of the remote user whose video state changes. + * @param state State of the remote video. See #REMOTE_VIDEO_STATE. + * @param reason The reason of the remote video state change. See #REMOTE_VIDEO_STATE_REASON. + * @param elapsed Time elapsed (ms) from the local user calling the + * \ref agora::rtc::IRtcEngine::joinChannel "joinChannel" method until the + * SDK triggers this callback. */ virtual void onRemoteVideoStateChanged(uid_t uid, REMOTE_VIDEO_STATE state, REMOTE_VIDEO_STATE_REASON reason, int elapsed) { (void)uid; @@ -4229,16 +5000,6 @@ class IRtcEngineEventHandler { /** Occurs when a specified remote user enables/disables the local video * capturing function. * - * @deprecated v2.9.0 - * - * This callback is deprecated and replaced by the - * \ref onRemoteVideoStateChanged() "onRemoteVideoStateChanged" callback - * with the following parameters: - * - #REMOTE_VIDEO_STATE_STOPPED (0) and - * #REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED (5). - * - #REMOTE_VIDEO_STATE_DECODING (2) and - * #REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED (6). - * * This callback is only applicable to the scenario when the user only * wants to watch the remote video without sending any video stream to the * other user. @@ -4298,27 +5059,82 @@ The SDK triggers this callback when the local user fails to receive the stream m virtual void onMediaEngineLoadSuccess() {} /** Occurs when the media engine call starts.*/ virtual void onMediaEngineStartCallSuccess() {} - /// @cond - /** Reports whether the super-resolution algorithm is enabled. + + /** Reports whether the super resolution feature is successfully enabled. (beta feature) * - * @since v3.2.0 + * @since v3.5.1 * * After calling \ref IRtcEngine::enableRemoteSuperResolution "enableRemoteSuperResolution", the SDK triggers this - * callback to report whether the super-resolution algorithm is successfully enabled. If not successfully enabled, - * you can use reason for troubleshooting. + * callback to report whether super resolution is successfully enabled. If it is not successfully enabled, + * use `reason` for troubleshooting. + * + * @param uid The user ID of the remote user. + * @param enabled Whether super resolution is successfully enabled: + * - true: Super resolution is successfully enabled. + * - false: Super resolution is not successfully enabled. + * @param reason The reason why super resolution is not successfully enabled or the message + * that confirms success. See #SUPER_RESOLUTION_STATE_REASON. * - * @param uid The ID of the remote user. - * @param enabled Whether the super-resolution algorithm is successfully enabled: - * - true: The super-resolution algorithm is successfully enabled. - * - false: The super-resolution algorithm is not successfully enabled. - * @param reason The reason why the super-resolution algorithm is not successfully enabled. See #SUPER_RESOLUTION_STATE_REASON. */ virtual void onUserSuperResolutionEnabled(uid_t uid, bool enabled, SUPER_RESOLUTION_STATE_REASON reason) { (void)uid; (void)enabled; (void)reason; } + + /** + * Reports whether the virtual background is successfully enabled. (beta feature) + * + * @since v3.4.5 + * + * After you call \ref IRtcEngine::enableVirtualBackground "enableVirtualBackground", the SDK triggers this callback + * to report whether the virtual background is successfully enabled. + * + * @note If the background image customized in the virtual background is in PNG or JPG format, the triggering of this + * callback is delayed until the image is read. + * + * @param enabled Whether the virtual background is successfully enabled: + * - true: The virtual background is successfully enabled. + * - false: The virtual background is not successfully enabled. + * @param reason The reason why the virtual background is not successfully enabled or the message that confirms + * success. See #VIRTUAL_BACKGROUND_SOURCE_STATE_REASON. + */ + virtual void onVirtualBackgroundSourceEnabled(bool enabled, VIRTUAL_BACKGROUND_SOURCE_STATE_REASON reason) { + (void)enabled; + (void)reason; + } + /// @cond + /** Reports result of Content Inspect*/ + virtual void onContentInspectResult(CONTENT_INSPECT_RESULT result) { (void)result; } /// @endcond + /** + * Reports the result of taking a video snapshot. + * + * @since v3.5.2 + * + * After a successful \ref IRtcEngine::takeSnapshot "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. + * + * @param channel The channel name. + * @param uid The user ID of the user. A `uid` of 0 indicates the local user. + * @param filePath The local path of the snapshot. + * @param width The width (px) of the snapshot. + * @param height The height (px) of the snapshot. + * @param 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 \ref IRtcEngine::takeSnapshot "takeSnapshot" method call succeeds. + */ + 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; + } /** Occurs when the state of the media stream relay changes. * @@ -4342,7 +5158,7 @@ The SDK triggers this callback when the local user fails to receive the stream m @param elapsed Time elapsed (ms) from the local user calling \ref IRtcEngine::joinChannel "joinChannel" until the SDK triggers this callback. */ - virtual void onFirstLocalAudioFrame(int elapsed) { (void)elapsed; } + virtual void onFirstLocalAudioFrame(int elapsed) AGORA_DEPRECATED_ATTRIBUTE { (void)elapsed; } /** Occurs when the first audio frame is published. * @@ -4367,23 +5183,24 @@ The SDK triggers this callback when the local user fails to receive the stream m @param uid User ID of the remote user. @param elapsed Time elapsed (ms) from the remote user calling \ref IRtcEngine::joinChannel "joinChannel" until the SDK triggers this callback. */ - virtual void onFirstRemoteAudioFrame(uid_t uid, int elapsed) { + virtual void onFirstRemoteAudioFrame(uid_t uid, int elapsed) AGORA_DEPRECATED_ATTRIBUTE { (void)uid; (void)elapsed; } /** - Occurs when the state of the RTMP or RTMPS streaming changes. - - The SDK triggers this callback to report the result of the local user calling the \ref agora::rtc::IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" or \ref agora::rtc::IRtcEngine::removePublishStreamUrl "removePublishStreamUrl" method. - - 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 *errCode* parameter. - - @param url The CDN streaming URL. - @param state The RTMP or RTMPS streaming state. See: #RTMP_STREAM_PUBLISH_STATE. - @param errCode The detailed error information for streaming. See: #RTMP_STREAM_PUBLISH_ERROR. + * Occurs when the state of the RTMP or RTMPS streaming changes. + * + * When the CDN live streaming state changes, the SDK triggers this callback to report the current state and the reason + * why the state has changed. + * + * When exceptions occur, you can troubleshoot issues by referring to the detailed error descriptions in the *errCode* parameter. + * + * @param url The CDN streaming URL. + * @param state The RTMP or RTMPS streaming state. See: #RTMP_STREAM_PUBLISH_STATE. + * @param errCode The detailed error information for streaming. See: #RTMP_STREAM_PUBLISH_ERROR_TYPE. */ - virtual void onRtmpStreamingStateChanged(const char* url, RTMP_STREAM_PUBLISH_STATE state, RTMP_STREAM_PUBLISH_ERROR errCode) { + virtual void onRtmpStreamingStateChanged(const char* url, RTMP_STREAM_PUBLISH_STATE state, RTMP_STREAM_PUBLISH_ERROR_TYPE errCode) { (void)url; (void)state; (void)errCode; @@ -4412,7 +5229,6 @@ The SDK triggers this callback when the local user fails to receive the stream m - #ERR_INVALID_ARGUMENT (-2): Invalid argument used. If, for example, you did not call \ref agora::rtc::IRtcEngine::setLiveTranscoding "setLiveTranscoding" to configure LiveTranscoding before calling \ref agora::rtc::IRtcEngine::addPublishStreamUrl "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_RESOURCE_LIMITED (-22): The backend system does not have enough resources for the CDN live streaming. - #ERR_ENCRYPTED_STREAM_NOT_ALLOWED_PUBLISH (130): You cannot publish an encrypted stream. - #ERR_PUBLISH_STREAM_CDN_ERROR (151) - #ERR_PUBLISH_STREAM_NUM_REACH_LIMIT (152) @@ -4420,7 +5236,7 @@ The SDK triggers this callback when the local user fails to receive the stream m - #ERR_PUBLISH_STREAM_INTERNAL_SERVER_ERROR (154) - #ERR_PUBLISH_STREAM_FORMAT_NOT_SUPPORTED (156) */ - virtual void onStreamPublished(const char* url, int error) { + virtual void onStreamPublished(const char* url, int error) AGORA_DEPRECATED_ATTRIBUTE { (void)url; (void)error; } @@ -4432,7 +5248,7 @@ The SDK triggers this callback when the local user fails to receive the stream m @param url The CDN streaming URL. */ - virtual void onStreamUnpublished(const char* url) { (void)url; } + virtual void onStreamUnpublished(const char* url) AGORA_DEPRECATED_ATTRIBUTE { (void)url; } /** Occurs when the publisher's transcoding is updated. * * When the `LiveTranscoding` class in the \ref agora::rtc::IRtcEngine::setLiveTranscoding "setLiveTranscoding" method updates, the SDK triggers the `onTranscodingUpdated` callback to report the update information to the local host. @@ -4456,7 +5272,10 @@ The SDK triggers this callback when the local user fails to receive the stream m } /** Occurs when the local audio route changes. - @param routing The current audio routing. See: #AUDIO_ROUTE_TYPE. + * + * @note This callback applies to Android, iOS and macOS only. + * + * @param routing The current audio routing. See: #AUDIO_ROUTE_TYPE. */ virtual void onAudioRouteChanged(AUDIO_ROUTE_TYPE routing) { (void)routing; } @@ -4481,8 +5300,8 @@ The SDK triggers this callback when the local user fails to receive the stream m * "setRemoteSubscribeFallbackOption" and set * @p option as #STREAM_FALLBACK_OPTION_AUDIO_ONLY, the SDK triggers this * callback when the remote media stream falls back to audio-only mode due - * to poor uplink conditions, or when the remote media stream switches - * back to the video after the uplink network condition improves. + * to poor downlink conditions, or when the remote media stream switches + * back to the video after the downlink network condition improves. * * @note Once the remote media stream switches to the low stream due to * poor network conditions, you can monitor the stream switch between a @@ -4519,7 +5338,7 @@ The SDK triggers this callback when the local user fails to receive the stream m * @param rxKBitRate Received bitrate (Kbps) of the audio packet sent * from the remote user. */ - virtual void onRemoteAudioTransportStats(uid_t uid, unsigned short delay, unsigned short lost, unsigned short rxKBitRate) { + virtual void onRemoteAudioTransportStats(uid_t uid, unsigned short delay, unsigned short lost, unsigned short rxKBitRate) AGORA_DEPRECATED_ATTRIBUTE { (void)uid; (void)delay; (void)lost; @@ -4544,7 +5363,7 @@ The SDK triggers this callback when the local user fails to receive the stream m * @param rxKBitRate Received bitrate (Kbps) of the video packet sent * from the remote user. */ - virtual void onRemoteVideoTransportStats(uid_t uid, unsigned short delay, unsigned short lost, unsigned short rxKBitRate) { + virtual void onRemoteVideoTransportStats(uid_t uid, unsigned short delay, unsigned short lost, unsigned short rxKBitRate) AGORA_DEPRECATED_ATTRIBUTE { (void)uid; (void)delay; (void)lost; @@ -4569,7 +5388,7 @@ The SDK triggers this callback when the local user fails to receive the stream m * - true: Enabled. * - false: Disabled. */ - virtual void onMicrophoneEnabled(bool enabled) { (void)enabled; } + virtual void onMicrophoneEnabled(bool enabled) AGORA_DEPRECATED_ATTRIBUTE { (void)enabled; } /** Occurs when the connection state between the SDK and the server changes. @param state See #CONNECTION_STATE_TYPE. @@ -4601,13 +5420,14 @@ The SDK triggers this callback when the local user fails to receive the stream m 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 (`userInfo`), and triggers this callback on the local client. - @param uid The ID of the remote user. - @param info The `UserInfo` object that contains the user ID and user account of the remote user. - */ + @param uid The ID of the remote user. + @param info The `UserInfo` object that contains the user ID and user account of the remote user. + */ virtual void onUserInfoUpdated(uid_t uid, const UserInfo& info) { (void)uid; (void)info; } + /// @cond /** Reports the result of uploading the SDK log files. * * @since v3.3.0 @@ -4627,25 +5447,26 @@ The SDK triggers this callback when the local user fails to receive the stream m (void)success; (void)reason; } + /// @endcond }; /** * Video device collection methods. - The IVideoDeviceCollection interface class retrieves the video device information. + The IVideoDeviceCollection interface class gets the video device information. */ class IVideoDeviceCollection { protected: virtual ~IVideoDeviceCollection() {} public: - /** Retrieves the total number of the indexed video devices in the system. + /** Gets the total number of the indexed video devices in the system. @return Total number of the indexed video devices: */ virtual int getCount() = 0; - /** Retrieves a specified piece of information about an indexed video device. + /** Gets a specified piece of information about an indexed video device. @param index The specified index of the video device that must be less than the return value of \ref IVideoDeviceCollection::getCount "getCount". @param deviceName Pointer to the video device name. @@ -4672,7 +5493,7 @@ class IVideoDeviceCollection { /** Video device management methods. - The IVideoDeviceManager interface class tests the video device interfaces. Instantiate an AVideoDeviceManager class to retrieve an IVideoDeviceManager interface. + The IVideoDeviceManager interface class tests the video device interfaces. Instantiate an AVideoDeviceManager class to get an IVideoDeviceManager interface. */ class IVideoDeviceManager { protected: @@ -4713,7 +5534,7 @@ class IVideoDeviceManager { /** Sets a device with the device ID. - @param deviceId Pointer to the video-capture device ID. Call the \ref IVideoDeviceManager::enumerateVideoDevices "enumerateVideoDevices" method to retrieve it. + @param deviceId Pointer to the video-capture device ID. Call the \ref IVideoDeviceManager::enumerateVideoDevices "enumerateVideoDevices" method to get it. @note Plugging or unplugging the device does not change the device ID. @@ -4723,7 +5544,7 @@ class IVideoDeviceManager { */ virtual int setDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0; - /** Retrieves the video-capture device that is in use. + /** Gets the video-capture device that is in use. @param deviceId Pointer to the video-capture device ID. @return @@ -4739,14 +5560,14 @@ class IVideoDeviceManager { /** Audio device collection methods. -The IAudioDeviceCollection interface class retrieves device-related information. +The IAudioDeviceCollection interface class gets device-related information. */ class IAudioDeviceCollection { protected: virtual ~IAudioDeviceCollection() {} public: - /** Retrieves the total number of audio playback or audio capturing devices. + /** Gets the total number of audio playback or audio capturing devices. @note You must first call the \ref IAudioDeviceManager::enumeratePlaybackDevices "enumeratePlaybackDevices" or \ref IAudioDeviceManager::enumerateRecordingDevices "enumerateRecordingDevices" method before calling this method to return the number of audio playback or audio capturing devices. @@ -4754,7 +5575,7 @@ class IAudioDeviceCollection { */ virtual int getCount() = 0; - /** Retrieves a specified piece of information about an indexed audio device. + /** Gets a specified piece of information about an indexed audio device. @param index The specified index that must be less than the return value of \ref IAudioDeviceCollection::getCount "getCount". @param deviceName Pointer to the audio device name. @@ -4774,6 +5595,20 @@ class IAudioDeviceCollection { */ virtual int setDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0; + /** + * Gets the default audio device of the system. + * + * @since v3.6.0 + * + * @param deviceName The name of the system default audio device. + * @param deviceId The device ID of the the system default audio device. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int getDefaultDevice(char deviceName[MAX_DEVICE_ID_LENGTH], char deviceId[MAX_DEVICE_ID_LENGTH]) = 0; + /** Sets the volume of the application. @param volume Application volume. The value ranges between 0 (lowest volume) and 255 (highest volume). @@ -4783,7 +5618,7 @@ class IAudioDeviceCollection { */ virtual int setApplicationVolume(int volume) = 0; - /** Retrieves the volume of the application. + /** Gets the volume of the application. @param volume Pointer to the application volume. The volume value ranges between 0 (lowest volume) and 255 (highest volume). @@ -4822,7 +5657,7 @@ class IAudioDeviceCollection { }; /** Audio device management methods. - The IAudioDeviceManager interface class allows for audio device interface testing. Instantiate an AAudioDeviceManager class to retrieve the IAudioDeviceManager interface. + The IAudioDeviceManager interface class allows for audio device interface testing. Instantiate an AAudioDeviceManager class to get the IAudioDeviceManager interface. */ class IAudioDeviceManager { protected: @@ -4877,6 +5712,36 @@ class IAudioDeviceManager { */ virtual int setRecordingDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0; + /** + * Sets the audio playback device used by the SDK to follow the system default audio playback device. + * + * @since v3.6.0 + * + * @param enable Whether to follow the system default audio playback device: + * - true: Follow. The SDK immediately switches the audio playback device when the system default audio playback device changes. + * - false: Do not follow. The SDK switches the audio playback device to the system default audio playback device only when the currently used audio playback device is disconnected. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int followSystemPlaybackDevice(bool enable) = 0; + + /** + * Sets the audio recording device used by the SDK to follow the system default audio recording device. + * + * @since v3.6.0 + * + * @param enable Whether to follow the system default audio recording device: + * - true: Follow. The SDK immediately switches the audio recording device when the system default audio recording device changes. + * - false: Do not follow. The SDK switches the audio recording device to the system default audio recording device only when the currently used audio recording device is disconnected. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int followSystemRecordingDevice(bool enable) = 0; + /** Starts the audio playback device test. * * This method tests if the audio playback device works properly. Once a user starts the test, the SDK plays an @@ -4919,7 +5784,7 @@ class IAudioDeviceManager { */ virtual int setPlaybackDeviceVolume(int volume) = 0; - /** Retrieves the volume of the audio playback device. + /** Gets the volume of the audio playback device. @param volume Pointer to the audio playback device volume. The volume value ranges between 0 (lowest volume) and 255 (highest volume). @return @@ -4939,7 +5804,7 @@ class IAudioDeviceManager { */ virtual int setRecordingDeviceVolume(int volume) = 0; - /** Retrieves the volume of the microphone. + /** Gets the volume of the microphone. @param volume Pointer to the microphone volume. The volume value ranges between 0 (lowest volume) and 255 (highest volume). @return @@ -4959,7 +5824,7 @@ class IAudioDeviceManager { - < 0: Failure. */ virtual int setPlaybackDeviceMute(bool mute) = 0; - /** Retrieves the mute status of the audio playback device. + /** Gets the mute status of the audio playback device. @param mute Pointer to whether the audio playback device is muted/unmuted. - true: Muted. @@ -4982,7 +5847,7 @@ class IAudioDeviceManager { */ virtual int setRecordingDeviceMute(bool mute) = 0; - /** Retrieves the microphone's mute status. + /** Gets the microphone's mute status. @param mute Pointer to whether the microphone is muted/unmuted. - true: Muted. @@ -5026,7 +5891,7 @@ class IAudioDeviceManager { */ virtual int stopRecordingDeviceTest() = 0; - /** Retrieves the audio playback device associated with the device ID. + /** Gets the audio playback device associated with the device ID. @param deviceId Pointer to the ID of the audio playback device. @return @@ -5035,7 +5900,7 @@ class IAudioDeviceManager { */ virtual int getPlaybackDevice(char deviceId[MAX_DEVICE_ID_LENGTH]) = 0; - /** Retrieves the audio playback device information associated with the device ID and device name. + /** Gets the audio playback device information associated with the device ID and device name. @param deviceId Pointer to the device ID of the audio playback device. @param deviceName Pointer to the device name of the audio playback device. @@ -5045,7 +5910,7 @@ class IAudioDeviceManager { */ virtual int getPlaybackDeviceInfo(char deviceId[MAX_DEVICE_ID_LENGTH], char deviceName[MAX_DEVICE_ID_LENGTH]) = 0; - /** Retrieves the audio capturing device associated with the device ID. + /** Gets the audio capturing device associated with the device ID. @param deviceId Pointer to the device ID of the audio capturing device. @return @@ -5054,7 +5919,7 @@ class IAudioDeviceManager { */ virtual int getRecordingDevice(char deviceId[MAX_DEVICE_ID_LENGTH]) = 0; - /** Retrieves the audio capturing device information associated with the device ID and device name. + /** Gets the audio capturing device information associated with the device ID and device name. @param deviceId Pointer to the device ID of the audio capturing device. @param deviceName Pointer to the device name of the audio capturing device. @@ -5156,8 +6021,9 @@ struct RtcEngineContext { /** * The region for connection. This advanced feature applies to scenarios that have regional restrictions. * - * For the regions that Agora supports, see #AREA_CODE. After specifying the region, the SDK connects to the Agora servers within that region. + * For the regions that Agora supports, see #AREA_CODE. The area codes support bitwise operation. * + * After specifying the region, the SDK connects to the Agora servers within that region. */ unsigned int areaCode; /** The configuration of the log files that the SDK outputs. See LogConfig. @@ -5242,10 +6108,11 @@ class IMetadataObserver { virtual void onMetadataReceived(const Metadata& metadata) = 0; }; -/** Encryption mode. +/** Encryption mode. Agora recommends using either the `AES_128_GCM2` or `AES_256_GCM2` + * encryption mode, both of which support adding a salt and are more secure. */ enum ENCRYPTION_MODE { - /** 1: (Default) 128-bit AES encryption, XTS mode. + /** 1: 128-bit AES encryption, XTS mode. */ AES_128_XTS = 1, /** 2: 128-bit AES encryption, ECB mode. @@ -5254,9 +6121,11 @@ enum ENCRYPTION_MODE { /** 3: 256-bit AES encryption, XTS mode. */ AES_256_XTS = 3, + /// @cond /** 4: 128-bit SM4 encryption, ECB mode. */ SM4_128_ECB = 4, + /// @endcond /** 5: 128-bit AES encryption, GCM mode. * * @since v3.3.1 @@ -5267,6 +6136,18 @@ enum ENCRYPTION_MODE { * @since v3.3.1 */ AES_256_GCM = 6, + /** 7: (Default) 128-bit AES encryption, GCM mode. Compared to `AES_128_GCM` encryption mode, + * `AES_128_GCM2` encryption mode is more secure and requires you to set the salt (`encryptionKdfSalt`). + * + * @since v3.4.5 + */ + AES_128_GCM2 = 7, + /** 8: 256-bit AES encryption, GCM mode. Compared to `AES_256_GCM` encryption mode, + * `AES_256_GCM2` encryption mode is more secure and requires you to set the salt (`encryptionKdfSalt`). + * + * @since v3.4.5 + */ + AES_256_GCM2 = 8, /** Enumerator boundary. */ MODE_END, @@ -5275,19 +6156,30 @@ enum ENCRYPTION_MODE { /** Configurations of built-in encryption schemas. */ struct EncryptionConfig { /** - * Encryption mode. The default encryption mode is `AES_128_XTS`. See #ENCRYPTION_MODE. + * Encryption mode. The default encryption mode is `AES_128_GCM2`. See #ENCRYPTION_MODE. */ ENCRYPTION_MODE encryptionMode; /** - * Encryption key in string type. + * Encryption key in string type with unlimited length. Agora recommends using a 32-byte key. * * @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 #ERR_INVALID_ARGUMENT (-2). */ const char* encryptionKey; + /** + * The salt with the length of 32 bytes. Agora recommends using OpenSSL to generate the salt on your server. + * For details, see *Media Stream Encryption*. + * + * @note This parameter is only valid when you set the encryption mode as `AES_128_GCM2` or `AES_256_GCM2`. + * In this case, ensure that this parameter is not `0`. + * + * @since v3.4.5 + */ + uint8_t encryptionKdfSalt[32]; EncryptionConfig() { - encryptionMode = AES_128_XTS; + encryptionMode = AES_128_GCM2; encryptionKey = nullptr; + memset(encryptionKdfSalt, 0, sizeof(encryptionKdfSalt)); } /// @cond @@ -5305,10 +6197,14 @@ struct EncryptionConfig { 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-xts"; + return "aes-128-gcm-2"; } - return "aes-128-xts"; + return "aes-128-gcm-2"; } /// @endcond }; @@ -5332,11 +6228,143 @@ struct ChannelMediaOptions { you can call the `muteAllRemoteVideoStreams` method to set whether to subscribe to video streams in the channel. */ bool autoSubscribeVideo; - ChannelMediaOptions() : autoSubscribeAudio(true), autoSubscribeVideo(true) {} + /** Determines whether to publish the local audio stream when the user joins a channel: + * - true: (Default) Publish. + * - false: Do not publish. + * + * This member serves a similar function to the `muteLocalAudioStream` method. After the user joins + * the channel, you can call the `muteLocalAudioStream` method to set whether to publish the + * local audio stream in the channel. + * + * @since v3.4.5 + */ + bool publishLocalAudio; + /** Determines whether to publish the local video stream when the user joins a channel: + * - true: (Default) Publish. + * - false: Do not publish. + * + * This member serves a similar function to the `muteLocalVideoStream` method. After the user joins + * the channel, you can call the `muteLocalVideoStream` method to set whether to publish the + * local video stream in the channel. + */ + bool publishLocalVideo; + ChannelMediaOptions() : autoSubscribeAudio(true), autoSubscribeVideo(true), publishLocalAudio(true), publishLocalVideo(true) {} }; - -/** IRtcEngine is the base interface class of the Agora SDK that provides the main Agora SDK methods invoked by your application. - +/** + * @since v3.5.0 + * + * The IVideoSink class, which can set up a custom video renderer. + * + * During a real-time audio and video interaction, the Agora SDK enables the default renderer to render local and + * remote video. The IVideoSink class can customize the video renderer. You can implement this interface first, and + * then customize the video renderer that you want by calling + * \ref IRtcEngine::setLocalVideoRenderer "setLocalVideoRenderer" or + * \ref IRtcEngine::setRemoteVideoRenderer "setRemoteVideoRenderer". + */ +class IVideoSink { + public: + /** + * Notification for initializing the custom video renderer. + * + * @since v3.5.0 + * + * The SDK triggers this callback to remind you to initialize the custom video renderer. + * After receiving this callback, you can do some preparation, and then use the return value to tell the SDK + * whether the custom video renderer is prepared. The SDK takes the corresponding behavior based on the return value. + * + * @return + * - true: The custom video renderer is initialized. The SDK is ready to send the video data to be rendered. + * - false: The custom video renderer is not ready or fails to initialize. The SDK reports the error. + */ + virtual bool onInitialize() = 0; + /** + * Notification for starting the custom video source. + * + * @since v3.5.0 + * + * The SDK triggers this callback to remind you to start the custom video source for capturing video. After receiving + * this callback, you can do some preparation, and then use the return value to tell the SDK whether the custom video + * renderer is started. The SDK takes the corresponding behavior based on the return value. + * + * @return + * - true: The custom video renderer is started. The SDK is ready to send the video data to be rendered to the custom video renderer for rendering. + * - false: The custom video renderer is not ready or fails to initialize. The SDK stops and reports the error. + */ + virtual bool onStart() = 0; + /** + * Notification for stopping rendering the video. + * + * @since v3.5.0 + * + * The SDK triggers this callback to remind you to stop rendering the video. This callback informs you that the SDK + * is about to stop sending video data to the custom video renderer. + */ + virtual void onStop() = 0; + /** + * Notification for disabling the custom video renderer. + * + * @since v3.5.0 + * + * The SDK triggers this callback to remind you to disable the custom video renderer. + */ + virtual void onDispose() = 0; + /** + * Gets the video frame type. + * + * @since v3.5.0 + * + * Before you initialize the custom video renderer, the SDK triggers this callback to query the data type of the + * video frame that you want to process. You must specify the data type of the video frame in the return value of + * this callback and then pass it to the SDK. + * + * @return \ref agora::media::ExternalVideoFrame::VIDEO_BUFFER_TYPE "VIDEO_BUFFER_TYPE" + */ + virtual agora::media::ExternalVideoFrame::VIDEO_BUFFER_TYPE getBufferType() = 0; + /** + * Gets the video frame pixel format. + * + * @since v3.5.0 + * + * Before you initialize the custom video renderer, the SDK triggers this callback to query the pixel format of the + * video frame that you want to process. You must specify a pixel format for the video frame in the return value of + * this callback and then pass it to the SDK. + * + * @return \ref agora::media::ExternalVideoFrame::VIDEO_PIXEL_FORMAT "VIDEO_PIXEL_FORMAT" + */ + virtual agora::media::ExternalVideoFrame::VIDEO_PIXEL_FORMAT getPixelFormat() = 0; +#if (defined(__APPLE__) && TARGET_OS_IOS) + /** + * Notification for rendering the video in the pixel data type. + * + * @since v3.5.0 + * + * The SDK triggers this callback after capturing video in the pixel data type to alter the custom video renderer + * to process the video data. + * + * @note This method applies to iOS only. + * + * @param pixelBuffer The video data in the pixel data type. + * @param rotation The clockwise rotation angle of the video. + */ + virtual void onRenderPixelBuffer(CVPixelBufferRef pixelBuffer, int rotation) = 0; +#endif + /** + * Notification for rendering the video in the raw data type. + * + * @since v3.5.0 + * + * The SDK triggers this callback after capturing video in the raw data type to alter the custom video renderer to + * process the video data. + * + * @param rawData The video data in the raw data type. + * @param width The width (px) of the video. + * @param height The height (px) of the video. + * @param rotation The clockwise rotation angle of the video. + */ + virtual void onRenderRawData(uint8_t* rawData, int width, int height, int rotation) = 0; +}; +/** IRtcEngine is the base interface class of the Agora SDK that provides the main Agora SDK methods +invoked by your application. Enable the Agora SDK's communication functionality through the creation of an IRtcEngine object, then call the methods of this object. */ class IRtcEngine { @@ -5359,7 +6387,7 @@ class IRtcEngine { * - 0(ERR_OK): Success. * - < 0: Failure. * - -1(ERR_FAILED): A general error occurs (no specified reason). - * - -2(ERR_INALID_ARGUMENT): No `IRtcEngineEventHandler` object is specified. + * - -2(ERR_INVALID_ARGUMENT): No `IRtcEngineEventHandler` object is specified. * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. Check whether `context` is properly set. * - -22(ERR_RESOURCE_LIMITED): The resource is limited. The app uses too much of the system resource and fails to allocate any resources. * - -101(ERR_INVALID_APP_ID): The App ID is invalid. @@ -5391,7 +6419,9 @@ class IRtcEngine { /** Sets the channel profile of the Agora IRtcEngine. * - * The Agora IRtcEngine differentiates channel profiles and applies optimization algorithms accordingly. + * After initialization, the SDK uses the `CHANNEL_PROFILE_COMMUNICATION` channel profile by default. + * You can call this method to set the channel profile. The Agora IRtcEngine differentiates channel profiles and + * applies optimization algorithms accordingly. * For example, it prioritizes smoothness and low latency for a video call, and prioritizes video quality for the interactive live video streaming. * * @warning @@ -5409,48 +6439,61 @@ class IRtcEngine { */ virtual int setChannelProfile(CHANNEL_PROFILE_TYPE profile) = 0; - /** Sets the role of the user, such as a host or an audience (default), before joining a channel in the interactive live streaming. + /** Sets the role of the user in interactive live streaming. * - * This method can be used to switch the user role in the interactive live streaming after the user joins a channel. + * After calling \ref IRtcEngine::setChannelProfile "setChannelProfile" (CHANNEL_PROFILE_LIVE_BROADCASTING), the + * SDK sets the user role as audience by default. You can call `setClientRole` to set the user role as host. * - * In the `LIVE_BROADCASTING` profile, when a user switches user roles after joining a channel, a successful \ref agora::rtc::IRtcEngine::setClientRole "setClientRole" method call triggers the following callbacks: - * - The local client: \ref agora::rtc::IRtcEngineEventHandler::onClientRoleChanged "onClientRoleChanged" - * - The remote client: \ref agora::rtc::IRtcEngineEventHandler::onUserJoined "onUserJoined" or \ref agora::rtc::IRtcEngineEventHandler::onUserOffline "onUserOffline" (BECOME_AUDIENCE) + * 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 \ref IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" and \ref IRtcEngine::muteLocalVideoStream "muteLocalVideoStream" to + * change the publishing state. + * - Triggers \ref IRtcEngineEventHandler::onClientRoleChanged "onClientRoleChanged" on the local client. + * - Triggers \ref IRtcEngineEventHandler::onUserJoined "onUserJoined" or \ref IRtcEngineEventHandler::onUserOffline "onUserOffline" (BECOME_AUDIENCE) + * on the remote client. * - * @note - * This method applies only to the `LIVE_BROADCASTING` profile. + * @note This method applies to the `LIVE_BROADCASTING` profile only. * - * @param role Sets the role of the user. See #CLIENT_ROLE_TYPE. + * @param role The role of a user in interactive live streaming. See #CLIENT_ROLE_TYPE. * * @return * - 0(ERR_OK): Success. * - < 0: Failure. * - -1(ERR_FAILED): A general error occurs (no specified reason). - * - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + * - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. + * - -5 (ERR_REFUSED): The request is rejected. In multichannel scenarios, if you have set any of the following in + * one channel, the SDK returns this error code when the user switches the user role to host in another channel: + * - Call `joinChannel` with the `options` parameter and use the default settings `publishLocalAudio = true` or `publishLocalVideo = true`. + * - Call `setClientRole` to set the user role as host. + * - Call `muteLocalAudioStream(false)` or `muteLocalVideoStream(false)`. * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. */ virtual int setClientRole(CLIENT_ROLE_TYPE role) = 0; - /** Sets the role of a user in interactive live streaming. + /** Sets the role of the user in interactive live streaming. * * @since v3.2.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: \ref IRtcEngineEventHandler::onClientRoleChanged "onClientRoleChanged". - * - The remote client: \ref IRtcEngineEventHandler::onUserJoined "onUserJoined" - * or \ref IRtcEngineEventHandler::onUserOffline "onUserOffline". + * In the `LIVE_BROADCASTING` channel profile, the + * SDK sets the user role as audience by default. You can call `setClientRole` to set the user role as host. + * + * You can call this method either before or after joining a channel. If you + * call this method to switch the user role after joining a channel, the SDK automatically does the following: + * - Calls \ref IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" and \ref IRtcEngine::muteLocalVideoStream "muteLocalVideoStream" to + * change the publishing state. + * - Triggers \ref IRtcEngineEventHandler::onClientRoleChanged "onClientRoleChanged" on the local client. + * - Triggers \ref IRtcEngineEventHandler::onUserJoined "onUserJoined" or \ref IRtcEngineEventHandler::onUserOffline "onUserOffline" (BECOME_AUDIENCE) + * on the remote client. * * @note - * - This method applies to the `LIVE_BROADCASTING` profile only (when the `profile` parameter in - * \ref IRtcEngine::setChannelProfile "setChannelProfile" is set as `CHANNEL_PROFILE_LIVE_BROADCASTING`). + * - This method applies to the `LIVE_BROADCASTING` profile only. * - The difference between this method and \ref IRtcEngine::setClientRole(CLIENT_ROLE_TYPE) "setClientRole" [1/2] is that * this method can set the user level in addition to the user role. - * - The user role determines the permissions that the SDK grants to a user, such as permission to send local - * streams, receive remote streams, and push streams to a CDN address. - * - The user level determines the level of services that a user can enjoy within the permissions of the user's - * role. For example, an audience can choose to receive remote streams with low latency or ultra low latency. Levels - * affect prices. + * - The user role determines the permissions that the SDK grants to a user, such as permission to send local streams, + * receive remote streams, and push streams to a CDN address. + * - The user level determines the level of services that a user can enjoy within the permissions of the user's role. + * For example, an audience member can choose to receive remote streams with low latency or ultra low latency. + * **User level affects the pricing of services.** * * @param role The role of a user in interactive live streaming. See #CLIENT_ROLE_TYPE. * @param options The detailed options of a user, including user level. See ClientRoleOptions. @@ -5459,7 +6502,12 @@ class IRtcEngine { * - 0(ERR_OK): Success. * - < 0: Failure. * - -1(ERR_FAILED): A general error occurs (no specified reason). - * - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + * - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. + * - -5 (ERR_REFUSED): The request is rejected. In multichannel scenarios, if you have set any of the following in + * one channel, the SDK returns this error code when the user switches the user role to host in another channel: + * - Call `joinChannel` with the `options` parameter and use the default settings `publishLocalAudio = true` or `publishLocalVideo = true`. + * - Call `setClientRole` to set the user role as host. + * - Call `muteLocalAudioStream(false)` or `muteLocalVideoStream(false)`. * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. */ virtual int setClientRole(CLIENT_ROLE_TYPE role, const ClientRoleOptions& options) = 0; @@ -5482,7 +6530,7 @@ class IRtcEngine { @note A channel does not accept duplicate uids, such as two users with the same @p uid. If you set @p uid as 0, the system automatically assigns a @p uid. If you want to join a channel from different devices, ensure that each device has a different uid. @warning Ensure that the App ID used for creating the token is the same App ID used by the \ref IRtcEngine::initialize "initialize" method for initializing the RTC engine. Otherwise, the CDN live streaming may fail. - @param token The token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Windows). + @param token The token generated at your server. See [Authenticate Your Users with Tokens](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=All%20Platforms). @param channelId Pointer to the unique channel name for the Agora RTC session in the string format smaller than 64 bytes. Supported characters: - All lowercase English letters: a to z. - All uppercase English letters: A to Z. @@ -5495,15 +6543,18 @@ class IRtcEngine { @return - 0(ERR_OK): Success. - < 0: Failure. - - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. - -3(ERR_NOT_READY): The SDK fails to be initialized. You can try re-initializing the SDK. - -5(ERR_REFUSED): The request is rejected. This may be caused by the following: - You have created an IChannel object with the same channel name. - You have joined and published a stream in a channel created by the IChannel object. When you join a channel created by the IRtcEngine object, the SDK publishes the local audio and video streams to that channel by default. Because the SDK does not support publishing a local stream to more than one channel simultaneously, an error occurs in this occasion. - -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method. + - -17(ERR_JOIN_CHANNEL_REJECTED): The request to join the channel is rejected. The SDK supports joining only one + IRtcEngine channel at a time. Therefore, the SDK returns this error code when a user who has already joined an + IRtcEngine channel calls the joining channel method of the IRtcEngine class with a valid channel name. */ virtual int joinChannel(const char* token, const char* channelId, const char* info, uid_t uid) = 0; - /** Joins a channel with the user ID, and configures whether to automatically subscribe to the audio or video streams. + /** Joins a channel with the user ID, and configures whether to publish or automatically subscribe to the audio or video streams. * * @since v3.3.0 * @@ -5520,13 +6571,14 @@ class IRtcEngine { * * @note * - Compared with \ref IRtcEngine::joinChannel(const char* token, const char* channelId, const char* info, uid_t uid) "joinChannel" [1/2], this method - * has the options parameter which configures whether the user automatically subscribes to all remote audio and video streams in the channel when - * joining the channel. By default, the user subscribes to the audio and video streams of all the other users in the channel, thus incurring all + * has the `options` parameter, which configures whether the user publishes or automatically subscribes to the audio and video streams in the channel when + * joining the channel. By default, the user publishes the local audio and video streams and automatically subscribes to the audio and video streams + * of all the other users in the channel. Subscribing incurs all * associated usage costs. To unsubscribe, set the `options` parameter or call the `mute` methods accordingly. * - Ensure that the App ID used for generating the token is the same App ID used in the \ref IRtcEngine::initialize "initialize" method for * creating an `IRtcEngine` object. * - * @param token The token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Windows). + * @param token The token generated at your server. See [Authenticate Your Users with Tokens](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=All%20Platforms). * @param channelId Pointer to the unique channel name for the Agora RTC session in the string format smaller than 64 bytes. Supported characters: * - All lowercase English letters: a to z. * - All uppercase English letters: A to Z. @@ -5535,19 +6587,22 @@ class IRtcEngine { * - Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",". * @param info (Optional) Reserved for future use. * @param uid (Optional) User ID. A 32-bit unsigned integer with a value ranging from 1 to 232-1. The @p uid must be unique. If a @p uid is - * not assigned (or set to 0), the SDK assigns and returns a @p uid in the \ref IRtcEngineEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" callback. + * not assigned (or set to 0), the SDK assigns and returns a `uid` in the \ref IRtcEngineEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" callback. * Your application must record and maintain the returned `uid`, because the SDK does not do so. **Note**: The ID of each user in the channel should be unique. * If you want to join the same channel from different devices, ensure that the user IDs in all devices are different. * @param options The channel media options: ChannelMediaOptions. @return * - 0(ERR_OK): Success. * - < 0: Failure. - * - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + * - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. * - -3(ERR_NOT_READY): The SDK fails to be initialized. You can try re-initializing the SDK. * - -5(ERR_REFUSED): The request is rejected. This may be caused by the following: * - You have created an IChannel object with the same channel name. * - You have joined and published a stream in a channel created by the IChannel object. When you join a channel created by the IRtcEngine object, the SDK publishes the local audio and video streams to that channel by default. Because the SDK does not support publishing a local stream to more than one channel simultaneously, an error occurs in this occasion. * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method. + * - -17(ERR_JOIN_CHANNEL_REJECTED): The request to join the channel is rejected. The SDK supports joining only one + * IRtcEngine channel at a time. Therefore, the SDK returns this error code when a user who has already joined an + * IRtcEngine channel calls the joining channel method of the IRtcEngine class with a valid channel name. */ virtual int joinChannel(const char* token, const char* channelId, const char* info, uid_t uid, const ChannelMediaOptions& options) = 0; /** Switches to a different channel. @@ -5571,7 +6626,7 @@ class IRtcEngine { * This method applies to the audience role in a `LIVE_BROADCASTING` channel * only. * - * @param token The token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Windows). + * @param token The token generated at your server. See [Authenticate Your Users with Tokens](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=All%20Platforms). * @param channelId Unique channel name for the AgoraRTC session in the * string format. The string length must be less than 64 bytes. Supported * character scopes are: @@ -5585,7 +6640,7 @@ class IRtcEngine { * - 0(ERR_OK): Success. * - < 0: Failure. * - -1(ERR_FAILED): A general error occurs (no specified reason). - * - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + * - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. * - -5(ERR_REFUSED): The request is rejected, probably because the user is not an audience. * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. * - -102(ERR_INVALID_CHANNEL_NAME): The channel name is invalid. @@ -5609,7 +6664,7 @@ class IRtcEngine { * By default, the user subscribes to the audio and video streams of all the other users in the target channel, thus incurring all associated usage costs. * To unsubscribe, set the `options` parameter or call the `mute` methods accordingly. * - * @param token The token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Windows). + * @param token The token generated at your server. See [Authenticate Your Users with Tokens](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=All%20Platforms). * @param channelId Unique channel name for the AgoraRTC session in the * string format. The string length must be less than 64 bytes. Supported * character scopes are: @@ -5624,7 +6679,7 @@ class IRtcEngine { * - 0(ERR_OK): Success. * - < 0: Failure. * - -1(ERR_FAILED): A general error occurs (no specified reason). - * - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + * - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. * - -5(ERR_REFUSED): The request is rejected, probably because the user is not an audience. * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. * - -102(ERR_INVALID_CHANNEL_NAME): The channel name is invalid. @@ -5652,11 +6707,15 @@ class IRtcEngine { - 0(ERR_OK): Success. - < 0: Failure. - -1(ERR_FAILED): A general error occurs (no specified reason). - - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. */ virtual int leaveChannel() = 0; + /// @cond + virtual int setAVSyncSource(const char* channelId, uid_t uid) = 0; + /// @endcond + /** Gets a new token when the current token expires after a period of time. The `token` expires after a period of time once the token schema is enabled when: @@ -5666,18 +6725,18 @@ class IRtcEngine { The application should call this method to get the new `token`. Failure to do so will result in the SDK disconnecting from the server. - @param token Pointer to the new token. + @param token The new token. @return - 0(ERR_OK): Success. - < 0: Failure. - -1(ERR_FAILED): A general error occurs (no specified reason). - - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. */ virtual int renewToken(const char* token) = 0; - /** Retrieves the pointer to the device manager object. + /** Gets the pointer to the device manager object. @param iid ID of the interface. @param inter Pointer to the *DeviceManager* object. @@ -5728,10 +6787,12 @@ class IRtcEngine { Once the user joins the channel (switches to another channel), the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. If you do not want to subscribe to a specified stream or all remote streams, call the `mute` methods accordingly. - @note To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. + @note + - To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the uid of the user is set to the same parameter type. + - Before using a String user name, ensure that you read [How can I use string user names](https://docs.agora.io/en/faq/string) for getting details about the limitations and implementation steps. - @param token The token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Windows). + @param token The token generated at your server. See [Authenticate Your Users with Tokens](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=All%20Platforms). @param channelId The channel name. The maximum length of this parameter is 64 bytes. Supported character scopes are: - All lowercase English letters: a to z. - All uppercase English letters: A to Z. @@ -5752,9 +6813,13 @@ class IRtcEngine { - #ERR_NOT_READY (-3) - #ERR_REFUSED (-5) - #ERR_NOT_INITIALIZED (-7) + - -17(ERR_JOIN_CHANNEL_REJECTED): The request to join the channel is rejected. The SDK supports joining only one + IRtcEngine channel at a time. Therefore, the SDK returns this error code when a user who has already joined an + IRtcEngine channel calls the joining channel method of the IRtcEngine class with a valid channel name. */ virtual int joinChannelWithUserAccount(const char* token, const char* channelId, const char* userAccount) = 0; - /** Joins the channel with a user account, and configures whether to automatically subscribe to audio or video streams after joining the channel. + /** Joins the channel with a user account, and configures + * whether to publish or automatically subscribe to the audio or video streams. * * @since v3.3.0 * @@ -5764,14 +6829,15 @@ class IRtcEngine { * * @note * - Compared with \ref IRtcEngine::joinChannelWithUserAccount(const char* token, const char* channelId, const char* userAccount) "joinChannelWithUserAccount" [1/2], - * this method has the options parameter to configure whether the end user automatically subscribes to all remote audio and video streams in a - * channel when joining the channel. By default, the user subscribes to the audio and video streams of all the other users in the channel, thus - * incurring all associated usage costs. To unsubscribe, set the `options` parameter or call the `mute` methods accordingly. + * this method has the options parameter, which configures whether the user publishes or automatically subscribes to the audio and video streams in the channel when + * joining the channel. By default, the user publishes the local audio and video streams and automatically subscribes to the audio and video streams of all the other + * users in the channel. Subscribing incurs all associated usage costs. To unsubscribe, set the `options` parameter or call the `mute` methods accordingly. * - To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all * the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the * uid of the user is set to the same parameter type. + * - Before using a String user name, ensure that you read [How can I use string user names](https://docs.agora.io/en/faq/string) for getting details about the limitations and implementation steps. * - * @param token The token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Windows). + * @param token The token generated at your server. See [Authenticate Your Users with Tokens](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=All%20Platforms). * @param channelId The channel name. The maximum length of this parameter is 64 bytes. Supported character scopes are: * - All lowercase English letters: a to z. * - All uppercase English letters: A to Z. @@ -5791,6 +6857,9 @@ class IRtcEngine { * - #ERR_INVALID_ARGUMENT (-2) * - #ERR_NOT_READY (-3) * - #ERR_REFUSED (-5) + * - -17(ERR_JOIN_CHANNEL_REJECTED): The request to join the channel is rejected. The SDK supports joining only one + * IRtcEngine channel at a time. Therefore, the SDK returns this error code when a user who has already joined an + * IRtcEngine channel calls the joining channel method of the IRtcEngine class with a valid channel name. */ virtual int joinChannelWithUserAccount(const char* token, const char* channelId, const char* userAccount, const ChannelMediaOptions& options) = 0; @@ -5870,85 +6939,121 @@ class IRtcEngine { */ virtual int startEchoTest(int intervalInSeconds) = 0; - /** Stops the audio call test. + /** Starts an audio and video call loop test. + * + * @since v3.5.2 + * + * Before joining a channel, to test whether the user's local sending and receiving streams are normal, you can call + * this method to perform an audio and video call loop test, which tests whether the audio and video devices and the + * user's upstream and downstream networks are working properly. + * + * After starting the test, the user needs to make a sound or face the camera. The audio or video is output after + * about two seconds. If the audio playback is normal, the audio device and the user's upstream and downstream + * networks are working properly; if the video playback is normal, the video device and the user's upstream and + * downstream networks are working properly. + * + * @note + * - Call this method before joining a channel. + * - After calling this method, call \ref IRtcEngine::stopEchoTest "stopEchoTest" to end the test; otherwise, the + * user cannot perform the next audio and video call loop test and cannot join the channel. + * - In the `LIVE_BROADCASTING` profile, only a host can call this method. + * + * @param config The configuration of the audio and video call loop test. See EchoTestConfiguration. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int startEchoTest(const EchoTestConfiguration& config) = 0; - @return - - 0: Success. - - < 0: Failure. + /** Stops call loop test. + * + * After calling `startEchoTest [2/3]` or `startEchoTest [3/3]`, call this method if you want to stop the call loop test. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int stopEchoTest() = 0; + /** Sets the Agora cloud proxy service. * * @since v3.3.0 * * When the user's firewall restricts the IP address and port, refer to *Use Cloud Proxy* to add the specific * IP addresses and ports to the firewall whitelist; then, call this method to enable the cloud proxy and set - * the cloud proxy type with the `proxyType` parameter: - * - `UDP_PROXY(1)`: The cloud proxy for the UDP protocol. - * - `TCP_PROXY(2)`: The cloud proxy for the TCP (encrypted) protocol. + * the `proxyType` parameter as `UDP_PROXY(1)`, which is the cloud proxy for the UDP protocol. * - * After a successfully cloud proxy connection, the SDK triggers the \ref IRtcEngineEventHandler::onConnectionStateChanged "onConnectionStateChanged" (CONNECTION_STATE_CONNECTING, CONNECTION_CHANGED_SETTING_PROXY_SERVER) callback. + * After a successfully cloud proxy connection, the SDK triggers + * the \ref IRtcEngineEventHandler::onConnectionStateChanged "onConnectionStateChanged" (CONNECTION_STATE_CONNECTING, CONNECTION_CHANGED_SETTING_PROXY_SERVER) callback. * * To disable the cloud proxy that has been set, call `setCloudProxy(NONE_PROXY)`. To change the cloud proxy type that has been set, * call `setCloudProxy(NONE_PROXY)` first, and then call `setCloudProxy`, and pass the value that you expect in `proxyType`. * * @note * - Agora recommends that you call this method before joining the channel or after leaving the channel. - * - When you use the cloud proxy for the UDP protocol, the services for pushing streams to CDN and co-hosting across channels are not available. - * - When you use the cloud proxy for the TCP (encrypted) protocol, note the following: - * - An error occurs when calling \ref IRtcEngine::startAudioMixing "startAudioMixing" to play online audio files in the HTTP protocol. - * - The services for pushing streams to CDN and co-hosting across channels will use the cloud proxy with the TCP protocol. + * - For the SDK v3.3.x, the services for pushing streams to CDN and co-hosting across channels are not available + * when you use the cloud proxy for the UDP protocol. For the SDK v3.4.0 and later, the services for pushing streams + * to CDN and co-hosting across channels are not available when the user is in a network environment with a firewall + * and uses the cloud proxy for the UDP protocol. * * @param proxyType The cloud proxy type, see #CLOUD_PROXY_TYPE. This parameter is required, and the SDK reports an error if you do not pass in a value. * * @return * - 0: Success. * - < 0: Failure. - * - `-2（ERR_INVALID_ARGUMENT)`: The parameter is invalid. + * - `-2(ERR_INVALID_ARGUMENT)`: The parameter is invalid. * - `-7(ERR_NOT_INITIALIZED)`: The SDK is not initialized. */ virtual int setCloudProxy(CLOUD_PROXY_TYPE proxyType) = 0; /** Enables the video module. - - Call this method either before joining a channel or during a call. If this method is called before joining a channel, the call starts in the video mode. If this method is called during an audio call, the audio mode switches to the video mode. To disable the video module, call the \ref IRtcEngine::disableVideo "disableVideo" method. - - A successful \ref agora::rtc::IRtcEngine::enableVideo "enableVideo" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onUserEnableVideo "onUserEnableVideo" (true) callback on the remote client. - @note - - This method affects the internal engine and can be called after the \ref agora::rtc::IRtcEngine::leaveChannel "leaveChannel" method. - - This method resets the internal engine and takes some time to take effect. We recommend using the following API methods to control the video engine modules separately: - - \ref IRtcEngine::enableLocalVideo "enableLocalVideo": Whether to enable the camera to create the local video stream. - - \ref IRtcEngine::muteLocalVideoStream "muteLocalVideoStream": Whether to publish the local video stream. - - \ref IRtcEngine::muteRemoteVideoStream "muteRemoteVideoStream": Whether to subscribe to and play the remote video stream. - - \ref IRtcEngine::muteAllRemoteVideoStreams "muteAllRemoteVideoStreams": Whether to subscribe to and play all remote video streams. - - @return - - 0: Success. - - < 0: Failure. + * + * Call this method either before joining a channel or during a call. If this method is called before joining a channel, the call starts in the video mode. If this method is called during an audio call, the audio mode switches to the video mode. To disable the video module, call the \ref IRtcEngine::disableVideo "disableVideo" method. + * + * A successful \ref agora::rtc::IRtcEngine::enableVideo "enableVideo" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onUserEnableVideo "onUserEnableVideo" (true) callback on the remote client. + * @note + * - This method affects the internal engine and can be called after the \ref agora::rtc::IRtcEngine::leaveChannel "leaveChannel" method. + * - This method resets the internal engine and takes some time to take effect. We recommend using the following API methods to control the video engine modules separately: + * - \ref IRtcEngine::enableLocalVideo "enableLocalVideo": Whether to enable the camera to create the local video stream. + * - \ref IRtcEngine::muteLocalVideoStream "muteLocalVideoStream": Whether to publish the local video stream. + * - \ref IRtcEngine::muteRemoteVideoStream "muteRemoteVideoStream": Whether to subscribe to and play the remote video stream. + * - \ref IRtcEngine::muteAllRemoteVideoStreams "muteAllRemoteVideoStreams": Whether to subscribe to and play all remote video streams. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int enableVideo() = 0; /** Disables the video module. - - This method can be called before joining a channel or during a call. If this method is called before joining a channel, the call starts in audio mode. If this method is called during a video call, the video mode switches to the audio mode. To enable the video module, call the \ref IRtcEngine::enableVideo "enableVideo" method. - - A successful \ref agora::rtc::IRtcEngine::disableVideo "disableVideo" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onUserEnableVideo "onUserEnableVideo" (false) callback on the remote client. - @note - - This method affects the internal engine and can be called after the \ref agora::rtc::IRtcEngine::leaveChannel "leaveChannel" method. - - This method resets the internal engine and takes some time to take effect. We recommend using the following API methods to control the video engine modules separately: - - \ref IRtcEngine::enableLocalVideo "enableLocalVideo": Whether to enable the camera to create the local video stream. - - \ref IRtcEngine::muteLocalVideoStream "muteLocalVideoStream": Whether to publish the local video stream. - - \ref IRtcEngine::muteRemoteVideoStream "muteRemoteVideoStream": Whether to subscribe to and play the remote video stream. - - \ref IRtcEngine::muteAllRemoteVideoStreams "muteAllRemoteVideoStreams": Whether to subscribe to and play all remote video streams. - - @return - - 0: Success. - - < 0: Failure. + * + * This method can be called before joining a channel or during a call. If this method is called before joining a + * channel, the call starts in audio mode. If this method is called during a video call, the video mode switches to + * the audio mode. To enable the video module, call the \ref IRtcEngine::enableVideo "enableVideo" method. + * + * A successful \ref agora::rtc::IRtcEngine::disableVideo "disableVideo" method call triggers + * the \ref agora::rtc::IRtcEngineEventHandler::onUserEnableVideo "onUserEnableVideo" (false) callback on the remote + * client. + * + * @note + * - This method affects the internal engine and can be called after + * the \ref agora::rtc::IRtcEngine::leaveChannel "leaveChannel" method. + * - This method resets the internal engine and takes some time to take effect. We recommend using the following + * APIs to control the video engine modules separately: + * - \ref IRtcEngine::enableLocalVideo "enableLocalVideo": Whether to enable the camera to create the local video stream. + * - \ref IRtcEngine::muteLocalVideoStream "muteLocalVideoStream": Whether to publish the local video stream. + * - \ref IRtcEngine::muteRemoteVideoStream "muteRemoteVideoStream": Whether to subscribe to and play the remote video stream. + * - \ref IRtcEngine::muteAllRemoteVideoStreams "muteAllRemoteVideoStreams": Whether to subscribe to and play all remote video streams. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int disableVideo() = 0; - /** **DEPRECATED** Sets the video profile. + /** Sets the video profile. - This method is deprecated as of v2.3. Use the \ref IRtcEngine::setVideoEncoderConfiguration "setVideoEncoderConfiguration" method instead. + @deprecated This method is deprecated as of v2.3. Use the \ref IRtcEngine::setVideoEncoderConfiguration "setVideoEncoderConfiguration" method instead. Each video profile includes a set of parameters, such as the resolution, frame rate, and bitrate. If the camera device does not support the specified resolution, the SDK automatically chooses a suitable camera resolution, keeping the encoder resolution specified by the *setVideoProfile* method. @@ -5968,7 +7073,7 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int setVideoProfile(VIDEO_PROFILE_TYPE profile, bool swapWidthAndHeight) = 0; + virtual int setVideoProfile(VIDEO_PROFILE_TYPE profile, bool swapWidthAndHeight) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Sets the video encoder configuration. @@ -6074,13 +7179,16 @@ class IRtcEngine { */ virtual int setRemoteUserPriority(uid_t uid, PRIORITY_TYPE userPriority) = 0; - /** Stops the local video preview and disables video. - - @note Call this method before joining a channel. - - @return - - 0: Success. - - < 0: Failure. + /** Stops the local video preview. + * + * After calling \ref IRtcEngine::startPreview "startPreview", if you want to stop + * the local video preview, call `stopPreview`. + * + * @note Call this method before you join the channel or after you leave the channel. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int stopPreview() = 0; @@ -6103,29 +7211,31 @@ class IRtcEngine { virtual int enableAudio() = 0; /** Disables/Re-enables the local audio function. - - The audio function is enabled by default. This method disables or re-enables the local audio function, that is, to stop or restart local audio capturing. - - This method does not affect receiving or playing the remote audio streams,and enableLocalAudio(false) is applicable to scenarios where the user wants to - receive remote audio streams without sending any audio stream to other users in the channel. - - Once the local audio function is disabled or re-enabled, the SDK triggers the \ref agora::rtc::IRtcEngineEventHandler::onLocalAudioStateChanged "onLocalAudioStateChanged" callback, - which reports `LOCAL_AUDIO_STREAM_STATE_STOPPED(0)` or `LOCAL_AUDIO_STREAM_STATE_RECORDING(1)`. - - @note - - This method is different from the \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" method: - - \ref agora::rtc::IRtcEngine::enableLocalAudio "enableLocalAudio": Disables/Re-enables the local audio capturing and processing. - If you disable or re-enable local audio capturing using the `enableLocalAudio` method, the local user may hear a pause in the remote audio playback. - - \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream": Sends/Stops sending the local audio streams. - - You can call this method either before or after joining a channel. - - @param enabled Sets whether to disable/re-enable the local audio function: - - true: (Default) Re-enable the local audio function, that is, to start the local audio capturing device (for example, the microphone). - - false: Disable the local audio function, that is, to stop local audio capturing. - - @return - - 0: Success. - - < 0: Failure. + * + * The audio function is enabled by default. This method disables or re-enables the local audio function, that is, to stop or restart local audio capturing. + * + * This method does not affect receiving the remote audio streams,and enableLocalAudio(false) is applicable to scenarios where the user wants to + * receive remote audio streams without sending any audio stream to other users in the channel. + * + * Once the local audio function is disabled or re-enabled, the SDK triggers the \ref agora::rtc::IRtcEngineEventHandler::onLocalAudioStateChanged "onLocalAudioStateChanged" callback, + * which reports `LOCAL_AUDIO_STREAM_STATE_STOPPED(0)` or `LOCAL_AUDIO_STREAM_STATE_RECORDING(1)`. + * + * @note + * - This method is different from the \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" method: + * - \ref agora::rtc::IRtcEngine::enableLocalAudio "enableLocalAudio": Disables/Re-enables the local audio capturing and processing. + * If you disable or re-enable local audio capturing using the `enableLocalAudio` method, the local user may hear a pause in the remote audio playback. + * - \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream": Sends/Stops sending the local audio streams. + * - This method can be called either before or after you join a channel. Calling it before you + * join a channel can set the device state only, and it takes effect immediately after you join the + * channel. + * + * @param enabled Sets whether to disable/re-enable the local audio function: + * - true: (Default) Re-enable the local audio function, that is, to start the local audio capturing device (for example, the microphone). + * - false: Disable the local audio function, that is, to stop local audio capturing. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int enableLocalAudio(bool enabled) = 0; @@ -6148,8 +7258,8 @@ class IRtcEngine { - In the `COMMUNICATION` and `LIVE_BROADCASTING` profiles, the bitrate may be different from your settings due to network self-adaptation. - In scenarios requiring high-quality audio, for example, a music teaching scenario, we recommend setting profile as AUDIO_PROFILE_MUSIC_HIGH_QUALITY (4) and scenario as AUDIO_SCENARIO_GAME_STREAMING (3). - @param profile Sets the sample rate, bitrate, encoding mode, and the number of channels. See #AUDIO_PROFILE_TYPE. - @param scenario Sets the audio application scenario. See #AUDIO_SCENARIO_TYPE. + @param profile Sets the sample rate, bitrate, encoding mode, and the number of channels. See #AUDIO_PROFILE_TYPE. + @param scenario Sets the audio application scenario. See #AUDIO_SCENARIO_TYPE. Under different audio scenarios, the device uses different volume types. For details, see [What is the difference between the in-call volume and the media volume?](https://docs.agora.io/en/faq/system_volume). @@ -6161,33 +7271,42 @@ class IRtcEngine { /** * Stops or resumes publishing the local audio stream. * - * A successful \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" method call - * triggers the \ref agora::rtc::IRtcEngineEventHandler::onUserMuteAudio "onUserMuteAudio" callback on the remote client. + * As of v3.4.5, this method only sets the publishing state of the audio stream in the channel of IRtcEngine. + * + * A successful method call triggers the \ref IRtcEngineEventHandler::onUserMuteAudio "onUserMuteAudio" callback + * on the remote client. + * + * You can only publish the local stream in one channel at a time. If you create multiple channels, ensure that + * you only call \ref IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" (false) in one channel; + * otherwise, the method call fails, and the SDK returns `-5 (ERR_REFUSED)`. * * @note - * - When @p mute is set as @p true, this method does not affect any ongoing audio recording, because it does not disable the microphone. - * - You can call this method either before or after joining a channel. If you call \ref agora::rtc::IRtcEngine::setChannelProfile "setChannelProfile" - * after this method, the SDK resets whether or not to stop publishing the local audio according to the channel profile and user role. - * Therefore, we recommend calling this method after the `setChannelProfile` method. + * - This method does not change the usage state of the audio-capturing device. + * - Whether this method call takes effect is affected by the + * \ref IRtcEngine::joinChannel(const char* token, const char* channelId, const char* info, uid_t uid, const ChannelMediaOptions& options) "joinChannel" [2/2] + * and \ref IRtcEngine::setClientRole "setClientRole" methods. For details, see *Set the Publishing State*. * * @param mute Sets whether to stop publishing the local audio stream. * - true: Stop publishing the local audio stream. - * - false: (Default) Resumes publishing the local audio stream. + * - false: Resume publishing the local audio stream. * * @return * - 0: Success. * - < 0: Failure. + * - `-5 (ERR_REFUSED)`: The request is rejected. */ virtual int muteLocalAudioStream(bool mute) = 0; /** * Stops or resumes subscribing to the audio streams of all remote users. * - * As of v3.3.0, after successfully calling this method, the local user stops or resumes + * 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*. + * - As of v3.3.0, this method contains the function of \ref IRtcEngine::setDefaultMuteAllRemoteAudioStreams "setDefaultMuteAllRemoteAudioStreams". + * Agora recommends not calling `muteAllRemoteAudioStreams` and `setDefaultMuteAllRemoteAudioStreams` + * together; otherwise, the settings may not take effect. See *Set the Subscribing State*. * * @param mute Sets whether to stop subscribing to the audio streams of all remote users. * - true: Stop subscribing to the audio streams of all remote users. @@ -6219,25 +7338,27 @@ class IRtcEngine { * - 0: Success. * - < 0: Failure. */ - virtual int setDefaultMuteAllRemoteAudioStreams(bool mute) = 0; + virtual int setDefaultMuteAllRemoteAudioStreams(bool mute) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Adjusts the playback signal volume of a specified remote user. - - You can call this method as many times as necessary to adjust the playback volume of different remote users, or to repeatedly adjust the playback volume of the same remote user. - - @note - - Call this method after joining a channel. - - The playback volume here refers to the mixed volume of a specified remote user. - - This method can only adjust the playback volume of one specified remote user at a time. To adjust the playback volume of different remote users, call the method as many times, once for each remote user. - - @param uid The ID of the remote user. - @param volume The playback volume of the specified remote user. The value ranges from 0 to 100: - - 0: Mute. - - 100: Original volume. - - @return - - 0: Success. - - < 0: Failure. + * + * You can call this method as many times as necessary to adjust the playback volume of different remote users, or to repeatedly adjust the playback volume of the same remote user. + * + * @note + * - Call this method after joining a channel. + * - The playback volume here refers to the mixed volume of a specified remote user. + * - This method can only adjust the playback volume of one specified remote user at a time. To adjust the playback volume of different remote users, call the method as many times, once for each remote user. + * + * @param uid The ID of the remote user. + * @param volume The playback volume of the specified remote user. The value + * ranges between 0 and 400, including the following: + * - 0: Mute. + * - 100: (Default) Original volume. + * - 400: Four times the original volume with signal-clipping protection. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int adjustUserPlaybackSignalVolume(unsigned int uid, int volume) = 0; /** @@ -6259,25 +7380,29 @@ class IRtcEngine { virtual int muteRemoteAudioStream(uid_t userId, bool mute) = 0; /** Stops or resumes publishing the local video stream. * - * A successful \ref agora::rtc::IRtcEngine::muteLocalVideoStream "muteLocalVideoStream" method call - * triggers the \ref agora::rtc::IRtcEngineEventHandler::onUserMuteVideo "onUserMuteVideo" callback on - * the remote client. + * As of v3.4.5, this method only sets the publishing state of the video stream in the channel of IRtcEngine. + * + * A successful method call triggers the \ref IRtcEngineEventHandler::onUserMuteVideo "onUserMuteVideo" + * callback on the remote client. + * + * You can only publish the local stream in one channel at a time. If you create multiple channels, + * ensure that you only call \ref IRtcEngine::muteLocalVideoStream "muteLocalVideoStream" (false) in one channel; + * otherwise, the method call fails, and the SDK returns `-5 (ERR_REFUSED)`. * * @note - * - This method executes faster than the \ref IRtcEngine::enableLocalVideo "enableLocalVideo" method, - * which controls the sending of the local video stream. - * - When `mute` is set as `true`, this method does not affect any ongoing video recording, because it does not disable the camera. - * - You can call this method either before or after joining a channel. If you call \ref IRtcEngine::setChannelProfile "setChannelProfile" - * after this method, the SDK resets whether or not to stop publishing the local video according to the channel profile and user role. - * Therefore, Agora recommends calling this method after the `setChannelProfile` method. + * - This method does not change the usage state of the video-capturing device. + * - Whether this method call takes effect is affected by the + * \ref IRtcEngine::joinChannel(const char* token, const char* channelId, const char* info, uid_t uid, const ChannelMediaOptions& options) "joinChannel" [2/2] + * and \ref IRtcEngine::setClientRole "setClientRole" methods. For details, see *Set the Publishing State*. * * @param mute Sets whether to stop publishing the local video stream. * - true: Stop publishing the local video stream. - * - false: (Default) Resumes publishing the local video stream. + * - false: Resume publishing the local video stream. * * @return * - 0: Success. * - < 0: Failure. + * - `-5 (ERR_REFUSED)`: The request is rejected. */ virtual int muteLocalVideoStream(bool mute) = 0; /** Enables/Disables the local video capture. @@ -6304,7 +7429,7 @@ class IRtcEngine { /** * Stops or resumes subscribing to the video streams of all remote users. * - * As of v3.3.0, after successfully calling this method, the local user stops or resumes + * 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 @@ -6340,7 +7465,7 @@ class IRtcEngine { * - 0: Success. * - < 0: Failure. */ - virtual int setDefaultMuteAllRemoteVideoStreams(bool mute) = 0; + virtual int setDefaultMuteAllRemoteVideoStreams(bool mute) AGORA_DEPRECATED_ATTRIBUTE = 0; /** * Stops or resumes subscribing to the video stream of a specified user. * @@ -6436,7 +7561,8 @@ class IRtcEngine { virtual int enableAudioVolumeIndication(int interval, int smooth, bool report_vad) = 0; /** Starts an audio recording. - @deprecated + @deprecated Deprecated from v2.9.1. + Use \ref IRtcEngine::startAudioRecording(const AudioRecordingConfiguration&) "startAudioRecording" [3/3] instead. The SDK allows recording during a call. Supported formats: @@ -6456,11 +7582,12 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int startAudioRecording(const char* filePath, AUDIO_RECORDING_QUALITY_TYPE quality) = 0; + virtual int startAudioRecording(const char* filePath, AUDIO_RECORDING_QUALITY_TYPE quality) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Starts an audio recording on the client. * - * @deprecated + * @deprecated Deprecated from v3.4.0. Use + * \ref IRtcEngine::startAudioRecording(const AudioRecordingConfiguration&) "startAudioRecording" [3/3] instead. * * The SDK allows recording during a call. After successfully calling this method, you can record the audio of all the users in the channel and get an audio recording file. * Supported formats of the recording file are as follows: @@ -6484,24 +7611,41 @@ class IRtcEngine { * - 0: Success. * - < 0: Failure. */ - virtual int startAudioRecording(const char* filePath, int sampleRate, AUDIO_RECORDING_QUALITY_TYPE quality) = 0; - /** Starts an audio recording. - - The SDK allows recording during a call. - This method is usually called after the \ref agora::rtc::IRtcEngine::joinChannel "joinChannel" method. - The recording automatically stops when the \ref agora::rtc::IRtcEngine::leaveChannel "leaveChannel" method is called. - - @param config Sets the audio recording configuration. See #AudioRecordingConfiguration. - - @return - - 0: Success. - - < 0: Failure. + virtual int startAudioRecording(const char* filePath, int sampleRate, AUDIO_RECORDING_QUALITY_TYPE quality) AGORA_DEPRECATED_ATTRIBUTE = 0; + /** + * Starts an audio recording on the client. + * + * @since v3.4.0 + * + * The SDK allows recording audio during a call. After successfully calling + * this method, you can record the audio of users in the channel and get + * an audio recording file. Supported file formats are as follows: + * - WAV: High-fidelity files with typically larger file sizes. For example, + * if the sample rate is 32,000 Hz, the file size for a 10-minute recording + * is approximately 73 MB. + * - AAC: Low-fidelity files with typically smaller file sizes. For example, + * if the sample rate is 32,000 Hz and the recording quality is + * #AUDIO_RECORDING_QUALITY_MEDIUM, the file size for a 10-minute recording + * is approximately 2 MB. + * + * Once the user leaves the channel, the recording automatically stops. + * + * @note Call this method after joining a channel. + * + * @param config Recording configuration. See AudioRecordingConfiguration. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `-160(ERR_ALREADY_IN_RECORDING)`: The client is already recording + * audio. To start a new recording, + * call \ref IRtcEngine::stopAudioRecording "stopAudioRecording" to stop the + * current recording first, and then + * call \ref IRtcEngine::startAudioRecording(const AudioRecordingConfiguration&) "startAudioRecording". */ virtual int startAudioRecording(const AudioRecordingConfiguration& config) = 0; /** Stops an audio recording on the client. - You can call this method before calling the \ref agora::rtc::IRtcEngine::leaveChannel "leaveChannel" method else, the recording automatically stops when the \ref agora::rtc::IRtcEngine::leaveChannel "leaveChannel" method is called. - @return - 0: Success - < 0: Failure. @@ -6509,71 +7653,116 @@ class IRtcEngine { virtual int stopAudioRecording() = 0; /** Starts playing and mixing the music file. - - @deprecated Deprecated from v3.4.0. Using the following methods instead: - - \ref IRtcEngine::startAudioMixing(const char* filePath, bool loopback, bool replace, int cycle, int startPos = 0) - - This method mixes the specified local audio file with the audio stream from the microphone, or replaces the microphone's audio stream with the specified local audio file. You can choose whether the other user can hear the local audio playback and specify the number of playback loops. This method also supports online music playback. - - When the audio mixing file playback finishes after calling this method, the SDK triggers the \ref agora::rtc::IRtcEngineEventHandler::onAudioMixingFinished "onAudioMixingFinished" callback. - - A successful \ref agora::rtc::IRtcEngine::startAudioMixing "startAudioMixing" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (PLAY) callback on the local client. - - When the audio mixing file playback finishes, the SDK triggers the \ref agora::rtc::IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (STOPPED) callback on the local client. - @note - - Call this method after joining a channel, otherwise issues may occur. - - If the local audio mixing file does not exist, or if the SDK does not support the file format or cannot access the music file URL, the SDK returns #WARN_AUDIO_MIXING_OPEN_ERROR (701). - - If you want to play an online music file, ensure that the time interval between calling this method is more than 100 ms, or the #AUDIO_MIXING_ERROR_TOO_FREQUENT_CALL (702) error code occurs. - - @param filePath Pointer to the absolute path (including the suffixes of the filename) of the local or online audio file to mix, for example, `C:/music/audio.mp4`. Supported audio formats: 3GP, ASF, ADTS, AVI, MP3, MP4, MPEG-4, SAMI, and WAVE. For more information, see [Supported Media Formats in Media Foundation](https://docs.microsoft.com/en-us/windows/desktop/medfound/supported-media-formats-in-media-foundation). - @param loopback Sets which user can hear the audio mixing: - - true: Only the local user can hear the audio mixing. - - false: Both users can hear the audio mixing. - @param replace Sets the audio mixing content: - - true: Only publish the specified audio file. The audio stream from the microphone is not published. - - false: The local audio file is mixed with the audio stream from the microphone. - @param cycle Sets the number of playback loops: - - Positive integer: Number of playback loops. - - `-1`: Infinite playback loops. - - @return - - 0: Success. - - < 0: Failure. - */ - virtual int startAudioMixing(const char* filePath, bool loopback, bool replace, int cycle) = 0; - - /** Starts playing and mixing the music file. - - This method mixes the specified local audio file with the audio stream from the microphone, or replaces the microphone's audio stream with the specified local audio file. You can choose whether the other user can hear the local audio playback and specify the number of playback loops. This method also supports online music playback. - - When the audio mixing file playback finishes after calling this method, the SDK triggers the \ref agora::rtc::IRtcEngineEventHandler::onAudioMixingFinished "onAudioMixingFinished" callback. - - A successful \ref agora::rtc::IRtcEngine::startAudioMixing "startAudioMixing" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (PLAY) callback on the local client. - - When the audio mixing file playback finishes, the SDK triggers the \ref agora::rtc::IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (STOPPED) callback on the local client. - @note - - Call this method after joining a channel, otherwise issues may occur. - - If the local audio mixing file does not exist, or if the SDK does not support the file format or cannot access the music file URL, the SDK returns #WARN_AUDIO_MIXING_OPEN_ERROR (701). - - If you want to play an online music file, ensure that the time interval between calling this method is more than 100 ms, or the #AUDIO_MIXING_ERROR_TOO_FREQUENT_CALL (702) error code occurs. - - @param filePath Pointer to the absolute path (including the suffixes of the filename) of the local or online audio file to mix, for example, `C:/music/audio.mp4`. Supported audio formats: 3GP, ASF, ADTS, AVI, MP3, MP4, MPEG-4, SAMI, and WAVE. For more information, see [Supported Media Formats in Media Foundation](https://docs.microsoft.com/en-us/windows/desktop/medfound/supported-media-formats-in-media-foundation). - @param loopback Sets which user can hear the audio mixing: - - true: Only the local user can hear the audio mixing. - - false: Both users can hear the audio mixing. - @param replace Sets the audio mixing content: - - true: Only publish the specified audio file. The audio stream from the microphone is not published. - - false: The local audio file is mixed with the audio stream from the microphone. - @param cycle Sets the number of playback loops: - - Positive integer: Number of playback loops. - - `-1`: Infinite playback loops. - @param startPos start playback position. - - Min value is 0. - - Max value is file length, the unit is ms - @return - - 0: Success. - - < 0: Failure. + * + * @deprecated Deprecated from v3.4.0. Use + * \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" [2/2] instead. + * + * This method mixes the specified local audio file with the audio stream from the microphone, or replaces the microphone's audio stream with the specified local audio file. You can choose whether the other user can hear the local audio playback and specify the number of playback loops. This method also supports online music playback. + * + * When the audio mixing file playback finishes after calling this method, the SDK triggers the \ref agora::rtc::IRtcEngineEventHandler::onAudioMixingFinished "onAudioMixingFinished" callback. + * + * A successful \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (PLAY) callback on the local client. + * + * When the audio mixing file playback finishes, the SDK triggers the \ref agora::rtc::IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (STOPPED) callback on the local client. + * + * @note + * - If the local audio mixing file does not exist, or if the SDK does not support the file format or cannot access the music file URL, the SDK returns #WARN_AUDIO_MIXING_OPEN_ERROR (701). + * - If you want to play an online music file, ensure that the time interval between calling this method is more than 100 ms, or the `AUDIO_MIXING_ERROR_TOO_FREQUENT_CALL(702)` error code occurs. + * - To avoid blocking, as of v3.4.5, this method changes from a synchronous call to an asynchronous call. + * - For the audio file formats supported by this method, see [What formats of audio files does the Agora RTC SDK support](https://docs.agora.io/en/faq/audio_format). + * + * @param filePath The absolute path or URL address (including the filename extensions) + * of the music file. For example: `C:\music\audio.mp4`. + * When you access a local file on Android, Agora recommends passing a URI address or the path starts + * with `/assets/` in this parameter. + * @param loopback Sets which user can hear the audio mixing: + * - true: Only the local user can hear the audio mixing. + * - false: Both users can hear the audio mixing. + * @param replace Sets the audio mixing content: + * - true: Only publish the specified audio file. The audio stream from the microphone is not published. + * - false: The local audio file is mixed with the audio stream from the microphone. + * @param cycle Sets the number of playback loops: + * - Positive integer: Number of playback loops. + * - `-1`: Infinite playback loops. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int startAudioMixing(const char* filePath, bool loopback, bool replace, int cycle) AGORA_DEPRECATED_ATTRIBUTE = 0; + /** + * Starts playing and mixing the music file. + * + * @since v3.4.0 + * + * This method supports mixing or replacing local or online music file and + * audio collected by a microphone. After successfully playing the music + * file, the SDK triggers + * \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING,AUDIO_MIXING_REASON_STARTED_BY_USER). + * After completing playing the music file, the SDK triggers + * `onAudioMixingStateChanged(AUDIO_MIXING_STATE_STOPPED,AUDIO_MIXING_REASON_ALL_LOOPS_COMPLETED)`. + * + * @note + * - If you need to call + * \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" multiple times, + * ensure that the call interval is longer than 500 ms. + * - If the local music file does not exist, or if the SDK does not support + * the file format or cannot access the music file URL, the SDK returns + * #WARN_AUDIO_MIXING_OPEN_ERROR (701). + * - On Android: + * - To use this method, ensure that the Android device is v4.2 or later + * and the API version is v16 or later. + * - If you need to play an online music file, Agora does not recommend + * using the redirected URL address. Some Android devices may fail to open a redirected URL address. + * - If you call this method on an emulator, ensure that the music file is + * in the `/sdcard/` directory and the format is MP3. + * - To avoid blocking, as of v3.4.5, this method changes from a synchronous call to an asynchronous call. + * - For the audio file formats supported by this method, see [What formats of audio files does the Agora RTC SDK support](https://docs.agora.io/en/faq/audio_format). + * + * @param filePath The absolute path or URL address (including the filename extensions) + * of the music file. For example: `C:\music\audio.mp4`. + * When you access a local file on Android, Agora recommends passing a URI address or the path starts + * with `/assets/` in this parameter. + * @param loopback Whether to only play the music file on the local client: + * - true: Only play the music file on the local client so that only the local + * user can hear the music. + * - false: Publish the music file to remote clients so that both the local + * user and remote users can hear the music. + * @param replace Whether to replace the audio collected by the microphone + * with a music file: + * - true: Replace. Users can only hear music. + * - false: Do not replace. Users can hear both music and audio collected by + * the microphone. + * @param 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 the + * music file once. + * - `-1`: Play the music in an indefinite loop. + * @param startPos The playback position (ms) of the music file. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int startAudioMixing(const char* filePath, bool loopback, bool replace, int cycle, int startPos) = 0; + /** + * Sets the playback speed of the current music file. + * + * @since v3.5.1 + * + * @note Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" [2/2] + * and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + * + * @param speed The playback speed. Agora recommends that you limit this value to between 50 and 400, defined as follows: + * - 50: Half the original speed. + * - 100: The original speed. + * - 400: 4 times the original speed. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int setAudioMixingPlaybackSpeed(int speed) = 0; /** Stops playing and mixing the music file. Call this method when you are in a channel. @@ -6592,6 +7781,72 @@ class IRtcEngine { - < 0: Failure. */ virtual int pauseAudioMixing() = 0; + /** + * Specifies the playback track of the current music file. + * + * @since v3.5.1 + * + * After getting the audio track index of the current music file, call this + * method to specify any audio track to play. For example, if different tracks + * of a multitrack file store songs in different languages, you can call this + * method to set the language of the music file to play. + * + * @note + * - This method is for Android, iOS, and Windows only. + * - Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" [2/2] + * and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + * - 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). + * + * @param index The specified playback track. This parameter must be less than or equal to the return value + * of \ref IRtcEngine::getAudioTrackCount "getAudioTrackCount". + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int selectAudioTrack(int index) = 0; + /** + * Gets the audio track index of the current music file. + * + * @since v3.5.1 + * + * @note + * - This method is for Android, iOS, and Windows only. + * - Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" [2/2] + * and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + * - 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). + * + * @return + * - ≥ 0: The audio track index of the current music file, if this method call succeeds. + * - < 0: Failure. + */ + virtual int getAudioTrackCount() = 0; + /** + * Sets the channel mode of the current music file. + * + * @since v3.5.1 + * + * In a stereo music file, the left and right channels can store different audio data. + * According to your needs, you can set the channel mode to original mode, left channel mode, + * right channel mode, or mixed channel mode. For example, in the KTV scenario, the left + * channel of the music file stores the musical accompaniment, and the right channel + * stores the singing voice. If you only need to listen to the accompaniment, call this + * method to set the channel mode of the music file to left channel mode; if you need to + * listen to the accompaniment and the singing voice at the same time, call this method + * to set the channel mode to mixed channel mode. + * + * @note + * - Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" [2/2] + * and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + * - This method only applies to stereo audio files. + * + * @param mode The channel mode. See \ref agora::media::AUDIO_MIXING_DUAL_MONO_MODE "AUDIO_MIXING_DUAL_MONO_MODE". + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int setAudioMixingDualMonoMode(agora::media::AUDIO_MIXING_DUAL_MONO_MODE mode) = 0; /** Resumes playing and mixing the music file. Call this method when you are in a channel. @@ -6625,8 +7880,8 @@ class IRtcEngine { /** Adjusts the volume during audio mixing. @note - - Calling this method does not affect the volume of audio effect file playback invoked by the \ref agora::rtc::IRtcEngine::playEffect "playEffect" method. - - Call this method after calling \ref IRtcEngine::startAudioMixing "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + - Calling this method does not affect the volume of audio effect file playback invoked by the \ref IRtcEngine::playEffect(int,const char*,int,double,double,int,bool,int) "playEffect" method. + - Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. @param volume Audio mixing volume. The value ranges between 0 and 100 (default). @@ -6637,7 +7892,7 @@ class IRtcEngine { virtual int adjustAudioMixingVolume(int volume) = 0; /** Adjusts the audio mixing volume for local playback. - @note Call this method after calling \ref IRtcEngine::startAudioMixing "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + @note Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. @param volume Audio mixing volume for local playback. The value ranges between 0 and 100 (default). @@ -6646,13 +7901,13 @@ class IRtcEngine { - < 0: Failure. */ virtual int adjustAudioMixingPlayoutVolume(int volume) = 0; - /** Retrieves the audio mixing volume for local playback. + /** Gets the audio mixing volume for local playback. This method helps troubleshoot audio volume related issues. @note - Call this method when you are in a channel. - - Call this method after calling \ref IRtcEngine::startAudioMixing "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + - Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. @return - ≥ 0: The audio mixing volume, if this method call succeeds. The value range is [0,100]. @@ -6661,7 +7916,7 @@ class IRtcEngine { virtual int getAudioMixingPlayoutVolume() = 0; /** Adjusts the audio mixing volume for publishing (for remote users). - @note Call this method after calling \ref IRtcEngine::startAudioMixing "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + @note Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. @param volume Audio mixing volume for publishing. The value ranges between 0 and 100 (default). @@ -6670,13 +7925,13 @@ class IRtcEngine { - < 0: Failure. */ virtual int adjustAudioMixingPublishVolume(int volume) = 0; - /** Retrieves the audio mixing volume for publishing. + /** Gets the audio mixing volume for publishing. This method helps troubleshoot audio volume related issues. @note - Call this method when you are in a channel. - - Call this method after calling \ref IRtcEngine::startAudioMixing "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + - Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. @return - ≥ 0: The audio mixing volume for publishing, if this method call succeeds. The value range is [0,100]. @@ -6684,44 +7939,34 @@ class IRtcEngine { */ virtual int getAudioMixingPublishVolume() = 0; - /** Retrieves the duration (ms) of the music file. - @deprecated Deprecated from v3.4.0. Use the following methods instead: - \ref IRtcEngine::getAudioMixingDuration(const char* filePath = NULL) - @note - - Call this method when you are in a channel. - - Call this method after calling \ref IRtcEngine::startAudioMixing "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. - - @return - - ≥ 0: The audio mixing duration, if this method call succeeds. - - < 0: Failure. - */ - virtual int getAudioMixingDuration() = 0; - /** Retrieves the duration (ms) of the music file. - - @note - - Call this method when you are in a channel. - - Call this method after calling \ref IRtcEngine::startAudioMixing "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. - @param filePath - - Return the file length while it is being played - @return - - ≥ 0: The audio mixing duration, if this method call succeeds. - - < 0: Failure. + /** Gets the duration (ms) of the music file. + * + * @deprecated This method is deprecated as of v3.5.1. Use \ref IRtcEngine::getAudioFileInfo "getAudioFileInfo" instead. + * + * @note + * - Call this method when you are in a channel. + * - Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" + * and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + * + * @return + * - ≥ 0: The audio mixing duration, if this method call succeeds. + * - < 0: Failure. */ - virtual int getAudioMixingDuration(const char* filePath) = 0; - /** Retrieves the playback position (ms) of the music file. - - @note - - Call this method when you are in a channel. - - Call this method after calling \ref IRtcEngine::startAudioMixing "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. - - @return - - ≥ 0: The current playback position of the audio mixing, if this method call succeeds. - - < 0: Failure. + virtual int getAudioMixingDuration() AGORA_DEPRECATED_ATTRIBUTE = 0; + /** Gets the playback position (ms) of the music file. + * + * @note + * - Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + * - If you need to call `getAudioMixingCurrentPosition` multiple times, ensure that the call interval is longer than 500 ms. + * + * @return + * - ≥ 0: The current playback position (ms) of the music file, if this method call succeeds. 0 represents that the current music file does not start playing. + * - < 0: Failure. */ virtual int getAudioMixingCurrentPosition() = 0; /** Sets the playback position of the music file to a different starting position (the default plays from the beginning). - @note Call this method after calling \ref IRtcEngine::startAudioMixing "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + @note Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. @param pos The playback starting position (ms) of the music file. @@ -6735,7 +7980,7 @@ class IRtcEngine { * * When a local music file is mixed with a local human voice, call this method to set the pitch of the local music file only. * - * @note Call this method after calling \ref IRtcEngine::startAudioMixing "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + * @note Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. * * @param pitch Sets the pitch of the local music file by chromatic scale. The default value is 0, * which means keeping the original pitch. The value ranges from -12 to 12, and the pitch value between @@ -6747,11 +7992,11 @@ class IRtcEngine { * - < 0: Failure. */ virtual int setAudioMixingPitch(int pitch) = 0; - /** Retrieves the volume of the audio effects. + /** Gets the volume of the audio effects. The value ranges between 0.0 and 100.0. - @note Ensure that this method is called after \ref IRtcEngine::playEffect "playEffect". + @note Ensure that this method is called after \ref IRtcEngine::playEffect(int,const char*,int,double,double,int,bool,int) "playEffect" . @return - ≥ 0: Volume of the audio effects, if this method call succeeds. @@ -6761,7 +8006,7 @@ class IRtcEngine { virtual int getEffectsVolume() = 0; /** Sets the volume of the audio effects. - @note Ensure that this method is called after \ref IRtcEngine::playEffect "playEffect". + @note Ensure that this method is called after \ref IRtcEngine::playEffect(int,const char*,int,double,double,int,bool,int) "playEffect" . @param volume Sets the volume of the audio effects. The value ranges between 0 and 100 (default). @@ -6772,7 +8017,7 @@ class IRtcEngine { virtual int setEffectsVolume(int volume) = 0; /** Sets the volume of a specified audio effect. - @note Ensure that this method is called after \ref IRtcEngine::playEffect "playEffect". + @note Ensure that this method is called after \ref IRtcEngine::playEffect(int,const char*,int,double,double,int,bool,int) "playEffect" . @param soundId ID of the audio effect. Each audio effect has a unique ID. @param volume Sets the volume of the specified audio effect. The value ranges between 0 and 100 (default). @@ -6808,72 +8053,98 @@ class IRtcEngine { */ virtual int enableFaceDetection(bool enable) = 0; #endif - /** Plays a specified local or online audio effect file. - @deprecated Deprecated from v3.4.0 Use the following methods instead: - - \ref IRtcEngine::playEffect(int soundId, const char* filePath, int loopCount, double pitch, double pan, int gain, bool publish = false, int startPos = 0) - - This method allows you to set the loop count, pitch, pan, and gain of the audio effect file, as well as whether the remote user can hear the audio effect. - - To play multiple audio effect files simultaneously, call this method multiple times with different soundIds and filePaths. We recommend playing no more than three audio effect files at the same time. - - @note - - If the audio effect is preloaded into the memory through the \ref IRtcEngine::preloadEffect "preloadEffect" method, the value of @p soundID must be the same as that in the *preloadEffect* method. - - Playing multiple online audio effect files simultaneously is not supported on macOS and Windows. - - Ensure that you call this method after joining a channel. - - @param soundId ID of the specified audio effect. Each audio effect has a unique ID. - @param filePath Specifies the absolute path (including the suffixes of the filename) to the local audio effect file or the URL of the online audio effect file, for example, c:/music/audio.mp4. Supported audio formats: mp3, mp4, m4a, aac, 3gp, mkv and wav. - @param loopCount Sets the number of times the audio effect loops: - - 0: Play the audio effect once. - - 1: Play the audio effect twice. - - -1: Play the audio effect in an indefinite loop until the \ref IRtcEngine::stopEffect "stopEffect" or \ref IRtcEngine::stopAllEffects "stopAllEffects" method is called. - @param pitch Sets the pitch of the audio effect. The value ranges between 0.5 and 2. The default value is 1 (no change to the pitch). The lower the value, the lower the pitch. - @param pan Sets the spatial position of the audio effect. The value ranges between -1.0 and 1.0: - - 0.0: The audio effect displays ahead. - - 1.0: The audio effect displays to the right. - - -1.0: The audio effect displays to the left. - @param gain Sets the volume of the audio effect. The value ranges between 0 and 100 (default). The lower the value, the lower the volume of the audio effect. - @param publish Sets whether or not to publish the specified audio effect to the remote stream: - - true: The locally played audio effect is published to the Agora Cloud and the remote users can hear it. - - false: The locally played audio effect is not published to the Agora Cloud and the remote users cannot hear it. - @return - - 0: Success. - - < 0: Failure. + * + * @deprecated Deprecated from v3.4.0. Use + * \ref IRtcEngine::playEffect(int,const char*,int,double,double,int,bool,int) "playEffect" [2/2] instead. + * + * This method allows you to set the loop count, pitch, pan, and gain of the audio effect file, as well as whether the remote user can hear the audio effect. + * + * To play multiple audio effect files simultaneously, call this method multiple times with different soundIds and filePaths. We recommend playing no more than three audio effect files at the same time. + * + * @note + * - If the audio effect is preloaded into the memory through the \ref IRtcEngine::preloadEffect "preloadEffect" method, the value of @p soundID must be the same as that in the *preloadEffect* method. + * - Playing multiple online audio effect files simultaneously is not supported on macOS and Windows. + * - Ensure that you call this method after joining a channel. + * - For the audio file formats supported by this method, see [What formats of audio files does the Agora RTC SDK support](https://docs.agora.io/en/faq/audio_format). + * + * @param soundId ID of the specified audio effect. Each audio effect has a unique ID. + * @param filePath The absolute path or URL address (including the filename extensions) + * of the music file. For example: `C:\music\audio.mp4`. + * When you access a local file on Android, Agora recommends passing a URI address or the path starts + * with `/assets/` in this parameter. + * @param loopCount Sets the number of times the audio effect loops: + * - 0: Play the audio effect once. + * - 1: Play the audio effect twice. + * - -1: Play the audio effect in an indefinite loop until the \ref IRtcEngine::stopEffect "stopEffect" or \ref IRtcEngine::stopAllEffects "stopAllEffects" method is called. + * @param pitch Sets the pitch of the audio effect. The value ranges between 0.5 and 2. The default value is 1 (no change to the pitch). The lower the value, the lower the pitch. + * @param pan Sets the spatial position of the audio effect. The value ranges between -1.0 and 1.0: + * - 0.0: The audio effect displays ahead. + * - 1.0: The audio effect displays to the right. + * - -1.0: The audio effect displays to the left. + * @param gain Sets the volume of the audio effect. The value ranges between 0 and 100 (default). The lower the value, the lower the volume of the audio effect. + * @param publish Sets whether to publish the specified audio effect to the remote stream: + * - true: The locally played audio effect is published to the Agora Cloud and the remote users can hear it. + * - false: The locally played audio effect is not published to the Agora Cloud and the remote users cannot hear it. + * @return + * - 0: Success. + * - < 0: Failure. */ - virtual int playEffect(int soundId, const char* filePath, int loopCount, double pitch, double pan, int gain, bool publish = false) = 0; - /** Plays a specified local or online audio effect file. - - This method allows you to set the loop count, pitch, pan, and gain of the audio effect file, as well as whether the remote user can hear the audio effect. - - To play multiple audio effect files simultaneously, call this method multiple times with different soundIds and filePaths. We recommend playing no more than three audio effect files at the same time. - - @note - - If the audio effect is preloaded into the memory through the \ref IRtcEngine::preloadEffect "preloadEffect" method, the value of @p soundID must be the same as that in the *preloadEffect* method. - - Playing multiple online audio effect files simultaneously is not supported on macOS and Windows. - - Ensure that you call this method after joining a channel. - - @param soundId ID of the specified audio effect. Each audio effect has a unique ID. - @param filePath Specifies the absolute path (including the suffixes of the filename) to the local audio effect file or the URL of the online audio effect file, for example, c:/music/audio.mp4. Supported audio formats: mp3, mp4, m4a, aac, 3gp, mkv and wav. - @param loopCount Sets the number of times the audio effect loops: - - 0: Play the audio effect once. - - 1: Play the audio effect twice. - - -1: Play the audio effect in an indefinite loop until the \ref IRtcEngine::stopEffect "stopEffect" or \ref IRtcEngine::stopAllEffects "stopAllEffects" method is called. - @param pitch Sets the pitch of the audio effect. The value ranges between 0.5 and 2. The default value is 1 (no change to the pitch). The lower the value, the lower the pitch. - @param pan Sets the spatial position of the audio effect. The value ranges between -1.0 and 1.0: - - 0.0: The audio effect displays ahead. - - 1.0: The audio effect displays to the right. - - -1.0: The audio effect displays to the left. - @param gain Sets the volume of the audio effect. The value ranges between 0 and 100 (default). The lower the value, the lower the volume of the audio effect. - @param publish Sets whether or not to publish the specified audio effect to the remote stream: - - true: The locally played audio effect is published to the Agora Cloud and the remote users can hear it. - - false: The locally played audio effect is not published to the Agora Cloud and the remote users cannot hear it. - @param startPos Set the play position when call this API - - Min 0, start play a url/file from start - - max value is the file length. the unit is ms - @return - - 0: Success. - - < 0: Failure. + virtual int playEffect(int soundId, const char* filePath, int loopCount, double pitch, double pan, int gain, bool publish = false) AGORA_DEPRECATED_ATTRIBUTE = 0; + /** + * Plays a specified local or online audio effect file. + * + * @since v3.4.0 + * + * To play multiple audio effect files at the same time, call this method + * multiple times with different `soundId` and `filePath` values. For the + * best user experience, Agora recommends playing no more than three audio + * effect files at the same time. + * + * After completing playing an audio effect file, the SDK triggers the + * \ref IRtcEngineEventHandler::onAudioEffectFinished "onAudioEffectFinished" + * callback. + * + * @note + * - Call this method after joining a channel. + * - For the audio file formats supported by this method, see [What formats of audio files does the Agora RTC SDK support](https://docs.agora.io/en/faq/audio_format). + * + * @param soundId Audio effect ID. The ID of each audio effect file is + * unique. If you preloaded an audio effect into memory by calling + * \ref IRtcEngine::preloadEffect "preloadEffect", ensure that this + * parameter is set to the same value as in `preloadEffect`. + * @param filePath The absolute path or URL address (including the filename extensions) + * of the music file. For example: `C:\music\audio.mp4`. + * If you preloaded an audio effect into memory by calling + * \ref IRtcEngine::preloadEffect "preloadEffect", ensure that this + * parameter is set to the same value as in `preloadEffect`. + * When you access a local file on Android, Agora recommends passing a URI address or the path starts + * with `/assets/` in this parameter. + * + * @param loopCount The number of times the audio effect loops: + * - ≥ 0: The number of loops. For example, `1` means loop one time, + * which means play the audio effect two times in total. + * - `-1`: Play the audio effect in an indefinite loop. + * @param pitch The pitch of the audio effect. The range is 0.5 to 2.0. + * The default value is 1.0, which means the original pitch. The lower the + * value, the lower the pitch. + * @param pan The spatial position of the audio effect. The range is `-1.0` + * to `1.0`. For example: + * - `-1.0`: The audio effect occurs on the left. + * - `0.0`: The audio effect occurs in the front. + * - `1.0`: The audio effect occurs on the right. + * @param gain The volume of the audio effect. The range is 0.0 to 100.0. + * The default value is 100.0, which means the original volume. The smaller + * the value, the less the gain. + * @param publish Whether to publish the audio effect to the remote users: + * - true: Publish. Both the local user and remote users can hear the audio + * effect. + * - false: Do not publish. Only the local user can hear the audio effect. + * @param startPos The playback position (ms) of the audio effect file. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int playEffect(int soundId, const char* filePath, int loopCount, double pitch, double pan, int gain, bool publish, int startPos) = 0; /** Stops playing a specified audio effect. @@ -6894,19 +8165,20 @@ class IRtcEngine { virtual int stopAllEffects() = 0; /** Preloads a specified audio effect file into the memory. - - @note This method does not support online audio effect files. - - To ensure smooth communication, limit the size of the audio effect file. We recommend using this method to preload the audio effect before calling the \ref IRtcEngine::joinChannel "joinChannel" method. - - Supported audio formats: mp3, aac, m4a, 3gp, and wav. - - @param soundId ID of the audio effect. Each audio effect has a unique ID. - @param filePath Pointer to the absolute path of the audio effect file. - - @return - - 0: Success. - - < 0: Failure. + * + * To ensure smooth communication, limit the size of the audio effect file. We recommend using this method to preload the audio effect before calling the \ref IRtcEngine::joinChannel "joinChannel" method. + * + * @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). + * + * @param soundId ID of the audio effect. Each audio effect has a unique ID. + * @param filePath The absolute path or URL address (including the filename extensions) + * of the music file. For example: `C:\music\audio.mp4`. + * When you access a local file on Android, Agora recommends passing a URI address or the path starts + * with `/assets/` in this parameter. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int preloadEffect(int soundId, const char* filePath) = 0; /** Releases a specified preloaded audio effect from the memory. @@ -6947,20 +8219,106 @@ class IRtcEngine { - < 0: Failure. */ virtual int resumeAllEffects() = 0; - + /** + * Gets the duration of the audio effect file. + * + * @since v3.4.0 + * + * @note + * - Call this method after joining a channel. + * - For the audio file formats supported by this method, see [What formats of audio files does the Agora RTC SDK support](https://docs.agora.io/en/faq/audio_format). + * + * @param filePath The absolute path or URL address (including the filename extensions) + * of the music file. For example: `C:\music\audio.mp4`. + * When you access a local file on Android, Agora recommends passing a URI address or the path starts + * with `/assets/` in this parameter. + * + * @return + * - ≥ 0: A successful method call. Returns the total duration (ms) of + * the specified audio effect file. + * - < 0: Failure. + * - `-22(ERR_RESOURCE_LIMITED)`: Cannot find the audio effect file. Please + * set a correct `filePath`. + */ virtual int getEffectDuration(const char* filePath) = 0; - + /** + * Sets the playback position of an audio effect file. + * + * @since v3.4.0 + * + * After a successful setting, the local audio effect file starts playing at the specified position. + * + * @note Call this method after \ref IRtcEngine::playEffect(int,const char*,int,double,double,int,bool,int) "playEffect" . + * + * @param soundId Audio effect ID. Ensure that this parameter is set to the + * same value as in \ref IRtcEngine::playEffect(int,const char*,int,double,double,int,bool,int) "playEffect" . + * @param pos The playback position (ms) of the audio effect file. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `-22(ERR_RESOURCE_LIMITED)`: Cannot find the audio effect file. Please + * set a correct `soundId`. + */ virtual int setEffectPosition(int soundId, int pos) = 0; - + /** + * Gets the playback position of the audio effect file. + * + * @since v3.4.0 + * + * @note Call this method after \ref IRtcEngine::playEffect(int,const char*,int,double,double,int,bool,int) "playEffect" . + * + * @param soundId Audio effect ID. Ensure that this parameter is set to the + * same value as in \ref IRtcEngine::playEffect(int,const char*,int,double,double,int,bool,int) "playEffect" . + * + * @return + * - ≥ 0: A successful method call. Returns the playback position (ms) of + * the specified audio effect file. + * - < 0: Failure. + * - `-22(ERR_RESOURCE_LIMITED)`: Cannot find the audio effect file. Please + * set a correct `soundId`. + */ virtual int getEffectCurrentPosition(int soundId) = 0; + /** Gets the information of a specified audio file. + * + * @since v3.5.1 + * + * After calling this method successfully, the SDK triggers the + * \ref IRtcEngineEventHandler::onRequestAudioFileInfo "onRequestAudioFileInfo" + * callback to report the information of an audio file, such as audio duration. + * You can call this method multiple times to get the information of multiple audio files. + * + * @note + * - Call this method after joining a channel. + * - For the audio file formats supported by this method, see [What formats of audio files does the Agora RTC SDK support](https://docs.agora.io/en/faq/audio_format). + * + * @param filePath The file path: + * - Windows: The absolute path or URL address (including the filename extensions) of + * the audio file. For example: `C:\music\audio.mp4`. + * - Android: The file path, including the filename extensions. To access an online file, + * Agora supports using a URL address; to access a local file, Agora supports using a URI + * address, an absolute path, or a path that starts with `/assets/`. You might encounter + * permission issues if you use an absolute path to access a local file, so Agora recommends + * using a URI address instead. For example: `content://com.android.providers.media.documents/document/audio%3A14441`. + * - iOS or macOS: The absolute path or URL address (including the filename extensions) of the audio file. + * For example: `/var/mobile/Containers/Data/audio.mp4`. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int getAudioFileInfo(const char* filePath) = 0; + /** Enables or disables deep-learning noise reduction. + * + * @since v3.3.0 * * The SDK enables traditional noise reduction mode by default to reduce most of the stationary background noise. * If you need to reduce most of the non-stationary background noise, Agora recommends enabling deep-learning * noise reduction as follows: * - * 1. Integrate the dynamical library under the libs folder to your project: + * 1. Ensure that the dynamical library is integrated in your project: * - Android: `libagora_ai_denoise_extension.so` * - iOS: `AgoraAIDenoiseExtension.xcframework` * - macOS: `AgoraAIDenoiseExtension.framework` @@ -7000,7 +8358,7 @@ class IRtcEngine { Ensure that you call this method before joinChannel to enable stereo panning for remote users so that the local user can track the position of a remote user by calling \ref agora::rtc::IRtcEngine::setRemoteVoicePosition "setRemoteVoicePosition". - @param enabled Sets whether or not to enable stereo panning for remote users: + @param enabled Sets whether to enable stereo panning for remote users: - true: enables stereo panning. - false: disables stereo panning. @@ -7053,18 +8411,21 @@ class IRtcEngine { - < 0: Failure. */ virtual int setLocalVoiceEqualization(AUDIO_EQUALIZATION_BAND_FREQUENCY bandFrequency, int bandGain) = 0; - /** Sets the local voice reverberation. - - v2.4.0 adds the \ref agora::rtc::IRtcEngine::setLocalVoiceReverbPreset "setLocalVoiceReverbPreset" method, a more user-friendly method for setting the local voice reverberation. You can use this method to set the local reverberation effect, such as pop music, R&B, rock music, and hip-hop. - - @note You can call this method either before or after joining a channel. - - @param reverbKey Sets the reverberation key. See #AUDIO_REVERB_TYPE. - @param value Sets the value of the reverberation key. - - @return - - 0: Success. - - < 0: Failure. + /** Sets the local voice reverberation. + * + * As of v3.2.0, the SDK provides a more convenient method + * \ref IRtcEngine::setAudioEffectPreset "setAudioEffectPreset", which + * directly implements the popular music, R&B music, KTV and other preset + * reverb effects. + * + * @note You can call this method either before or after joining a channel. + * + * @param reverbKey Sets the reverberation key. See #AUDIO_REVERB_TYPE. + * @param value Sets the value of the reverberation key. See #AUDIO_REVERB_TYPE. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int setLocalVoiceReverb(AUDIO_REVERB_TYPE reverbKey, int value) = 0; /** Sets the local voice changer option. @@ -7089,17 +8450,14 @@ class IRtcEngine { - Do not use this method with \ref IRtcEngine::setLocalVoiceReverbPreset "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. - @param voiceChanger Sets the local voice changer option. The default value is #VOICE_CHANGER_OFF, which means the original voice. See details in #VOICE_CHANGER_PRESET - Gender-based beatification effect works best only when assigned a proper gender: - - For male: #GENERAL_BEAUTY_VOICE_MALE_MAGNETIC - - For female: #GENERAL_BEAUTY_VOICE_FEMALE_FRESH or #GENERAL_BEAUTY_VOICE_FEMALE_VITALITY - Failure to do so can lead to voice distortion. + @param voiceChanger Sets the local voice changer option. The default value is `VOICE_CHANGER_OFF`, + which means the original voice. See details in #VOICE_CHANGER_PRESET. @return - 0: Success. - < 0: Failure. Check if the enumeration is properly set. */ - virtual int setLocalVoiceChanger(VOICE_CHANGER_PRESET voiceChanger) = 0; + virtual int setLocalVoiceChanger(VOICE_CHANGER_PRESET voiceChanger) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Sets the local voice reverberation option, including the virtual stereo. * * @deprecated Deprecated from v3.2.0. Use \ref IRtcEngine::setAudioEffectPreset "setAudioEffectPreset" or @@ -7125,7 +8483,7 @@ class IRtcEngine { * - 0: Success. * - < 0: Failure. */ - virtual int setLocalVoiceReverbPreset(AUDIO_REVERB_PRESET reverbPreset) = 0; + virtual int setLocalVoiceReverbPreset(AUDIO_REVERB_PRESET reverbPreset) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Sets an SDK preset voice beautifier effect. * * @since v3.2.0 @@ -7372,8 +8730,8 @@ class IRtcEngine { * - 0: Success. * - < 0: Failure. */ - virtual int setLogFile(const char* filePath) = 0; - + virtual int setLogFile(const char* filePath) AGORA_DEPRECATED_ATTRIBUTE = 0; + /// @cond /** Specifies an SDK external log writer. The external log writer output all SDK operations during runtime if it exist. @@ -7398,6 +8756,7 @@ class IRtcEngine { - < 0: Failure. */ virtual int releaseLogWriter() = 0; + /// @endcond /** Sets the output log level of the SDK. @deprecated This method is deprecated from v3.3.0. Use `logConfig` in the \ref IRtcEngine::initialize "initialize" method instead. @@ -7415,7 +8774,7 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int setLogFilter(unsigned int filter) = 0; + virtual int setLogFilter(unsigned int filter) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Sets the size of a log file that the SDK outputs. * * @deprecated This method is deprecated from v3.3.0. Use `logConfig` in the \ref IRtcEngine::initialize "initialize" method instead. @@ -7437,7 +8796,8 @@ class IRtcEngine { * - 0: Success. * - < 0: Failure. */ - virtual int setLogFileSize(unsigned int fileSizeInKBytes) = 0; + virtual int setLogFileSize(unsigned int fileSizeInKBytes) AGORA_DEPRECATED_ATTRIBUTE = 0; + /// @cond /** Uploads all SDK log files. * * @since v3.3.0 @@ -7461,6 +8821,7 @@ class IRtcEngine { * - -12(ERR_TOO_OFTEN): The call frequency exceeds the limit. */ virtual int uploadLogFile(agora::util::AString& requestId) = 0; + /// @endcond /** @deprecated This method is deprecated, use the \ref IRtcEngine::setLocalRenderMode(RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode) "setLocalRenderMode" [2/2] method instead. Sets the local video display mode. @@ -7472,7 +8833,7 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int setLocalRenderMode(RENDER_MODE_TYPE renderMode) = 0; + virtual int setLocalRenderMode(RENDER_MODE_TYPE renderMode) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Updates the display mode of the local video view. @since v3.0.0 @@ -7503,7 +8864,7 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int setRemoteRenderMode(uid_t userId, RENDER_MODE_TYPE renderMode) = 0; + virtual int setRemoteRenderMode(uid_t userId, RENDER_MODE_TYPE renderMode) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Updates the display mode of the video view of a remote user. @since v3.0.0 @@ -7537,8 +8898,8 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int setLocalVideoMirrorMode(VIDEO_MIRROR_MODE_TYPE mirrorMode) = 0; - /** Sets the stream mode to the single-stream (default) or dual-stream mode. (`LIVE_BROADCASTING` only.) + virtual int setLocalVideoMirrorMode(VIDEO_MIRROR_MODE_TYPE mirrorMode) AGORA_DEPRECATED_ATTRIBUTE = 0; + /** Sets the stream mode to the single-stream (default) or dual-stream mode. If the dual-stream mode is enabled, the receiver can choose to receive the high stream (high-resolution and high-bitrate video stream), or the low stream (low-resolution and low-bitrate video stream). @@ -7547,6 +8908,10 @@ class IRtcEngine { @param enabled Sets the stream mode: - true: Dual-stream mode. - false: Single-stream mode. + + @return + - 0: Success. + - < 0: Failure. */ virtual int enableDualStreamMode(bool enabled) = 0; /** Sets the external audio source. @@ -7574,7 +8939,7 @@ class IRtcEngine { * it, and play it with the audio effects that you want. * * @note - * - Once you enable the external audio sink, the app will not retrieve any + * - Once you enable the external audio sink, the app will not get any * audio data from the * \ref agora::media::IAudioFrameObserver::onPlaybackAudioFrame "onPlaybackAudioFrame" callback. * - Ensure that you call this method before joining a channel. @@ -7644,62 +9009,71 @@ class IRtcEngine { - < 0: Failure. */ virtual int setMixedAudioFrameParameters(int sampleRate, int samplesPerCall) = 0; - /** Adjusts the capturing signal volume. - - @note You can call this method either before or after joining a channel. - - @param volume Volume. To avoid echoes and - improve call quality, Agora recommends setting the value of volume between - 0 and 100. If you need to set the value higher than 100, contact - support@agora.io first. - - 0: Mute. - - 100: Original volume. - - - @return - - 0: Success. - - < 0: Failure. + /** Adjusts the volume of the signal captured by the microphone. + * + * @note You can call this method either before or after joining a channel. + * + * @param volume The volume of the signal captured by the microphone. + * The value ranges between 0 and 400, including the following: + * - 0: Mute. + * - 100: (Default) Original volume. + * - 400: Four times the original volume with signal-clipping protection. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int adjustRecordingSignalVolume(int volume) = 0; /** Adjusts the playback signal volume of all remote users. - - @note - - This method adjusts the playback volume that is the mixed volume of all remote users. - - You can call this method either before or after joining a channel. - - (Since v2.3.2) To mute the local audio playback, call both the `adjustPlaybackSignalVolume` and \ref IRtcEngine::adjustAudioMixingVolume "adjustAudioMixingVolume" methods and set the volume as `0`. - - @param volume The playback volume of all remote users. To avoid echoes and - improve call quality, Agora recommends setting the value of volume between - 0 and 100. If you need to set the value higher than 100, contact - support@agora.io first. - - 0: Mute. - - 100: Original volume. - - @return - - 0: Success. - - < 0: Failure. + * + * @note + * - This method adjusts the playback volume that is the mixed volume of all + * remote users. + * - You can call this method either before or after joining a channel. + * - (Since v2.3.2) To mute the local audio playback, call both the + * `adjustPlaybackSignalVolume` and + * \ref IRtcEngine::adjustAudioMixingVolume "adjustAudioMixingVolume" + * methods and set the volume as `0`. + * + * @param volume The playback volume. The value ranges between 0 and 400, + * including the following: + * - 0: Mute. + * - 100: (Default) Original volume. + * - 400: Four times the original volume with signal-clipping protection. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int adjustPlaybackSignalVolume(int volume) = 0; - /** Adjusts the loopback signal volume. - - @note You can call this method either before or after joining a channel. - - @param volume Volume. To avoid quality issues, Agora recommends setting the value of volume - between 0 and 100. If you need to set the value higher than 100, contact support@agora.io first. - - 0: Mute. - - 100: Original volume. - - @return - - 0: Success. - - < 0: Failure. - */ + /** + * Adjusts the volume of the signal captured by the sound card. + * + * @since v3.4.0 + * + * After calling enableLoopbackRecording to enable loopback audio capturing, + * you can call this method to adjust the volume of the signal captured by + * the sound card. + * + * @note This method applies to Windows and macOS only. + * + * @param volume The volume of the signal captured by the sound card. + * The value ranges between 0 and 400, including the following: + * - 0: Mute. + * - 100: (Default) Original volume. + * - 400: Four times the original volume with signal-clipping protection. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ virtual int adjustLoopbackRecordingSignalVolume(int volume) = 0; /** @deprecated This method is deprecated. As of v3.0.0, the Native SDK automatically enables interoperability with the Web SDK, so you no longer need to call this method. Enables interoperability with the Agora Web SDK. @note - - This method applies only to the `LIVE_BROADCASTING` profile. In the `COMMUNICATION` profile, interoperability with the Agora Web SDK is enabled by default. + - This method applies to the `LIVE_BROADCASTING` profile. In the `COMMUNICATION` profile, interoperability with the Agora Web SDK is enabled by default. - If the channel has Web SDK users, ensure that you call this method, or the video of the Native user will be a black screen for the Web user. @param enabled Sets whether to enable/disable interoperability with the Agora Web SDK: @@ -7710,7 +9084,7 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int enableWebSdkInteroperability(bool enabled) = 0; + virtual int enableWebSdkInteroperability(bool enabled) AGORA_DEPRECATED_ATTRIBUTE = 0; // only for live broadcast /** **DEPRECATED** Sets the preferences for the high-quality video. (`LIVE_BROADCASTING` only). @@ -7793,60 +9167,56 @@ class IRtcEngine { */ virtual int switchCamera(CAMERA_DIRECTION direction) = 0; /// @endcond - /** Sets the default audio playback route. - - This method sets whether the received audio is routed to the earpiece or speakerphone by default before joining a channel. - If a user does not call this method, the audio is routed to the earpiece by default. If you need to change the default audio route after joining a channel, call the \ref IRtcEngine::setEnableSpeakerphone "setEnableSpeakerphone" method. - - The default setting for each profile: - - `COMMUNICATION`: In a voice call, the default audio route is the earpiece. In a video call, the default audio route is the speakerphone. If a user who is in the `COMMUNICATION` profile calls - the \ref IRtcEngine.disableVideo "disableVideo" method or if the user calls - the \ref IRtcEngine.muteLocalVideoStream "muteLocalVideoStream" and - \ref IRtcEngine.muteAllRemoteVideoStreams "muteAllRemoteVideoStreams" methods, the - default audio route switches back to the earpiece automatically. - - `LIVE_BROADCASTING`: Speakerphone. - - @note - - This method is for Android and iOS only. - - This method is applicable only to the `COMMUNICATION` profile. - - For iOS, this method only works in a voice call. - - Call this method before calling the \ref IRtcEngine::joinChannel "joinChannel" method. - - @param defaultToSpeaker Sets the default audio route: - - true: Route the audio to the speakerphone. If the playback device connects to the earpiece or Bluetooth, the audio cannot be routed to the speakerphone. - - false: (Default) Route the audio to the earpiece. If a headset is plugged in, the audio is routed to the headset. - - @return - - 0: Success. - - < 0: Failure. + /** + * Sets the default audio route. + * + * If the default audio route of the SDK (see *Set the Audio Route*) cannot meet your requirements, you can + * call this method to switch the default audio route. After successfully switching the audio route, the SDK + * triggers the \ref IRtcEngineEventHandler::onAudioRouteChanged "onAudioRouteChanged" callback to indicate the changes. + * + * @note + * - This method applies to Android and iOS only. + * - Call this method before calling \ref IRtcEngine::joinChannel "joinChannel". If you need to switch the audio + * route after joining a channel, call \ref IRtcEngine::setEnableSpeakerphone "setEnableSpeakerphone". + * - If the user uses an external audio playback device such as a Bluetooth or wired headset, this method does not + * take effect, and the SDK plays audio through the external device. When the user uses multiple external devices, + * the SDK plays audio through the last connected device. + * + * @param defaultToSpeaker Sets the default audio route as follows: + * - true: Set to the speakerphone. + * - false: Set to the earpiece. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int setDefaultAudioRouteToSpeakerphone(bool defaultToSpeaker) = 0; - /** Enables/Disables the audio playback route to the speakerphone. - - This method sets whether the audio is routed to the speakerphone or earpiece. - - See the default audio route explanation in the \ref IRtcEngine::setDefaultAudioRouteToSpeakerphone "setDefaultAudioRouteToSpeakerphone" method and check whether it is necessary to call this method. - - @note - - This method is for Android and iOS only. - - Ensure that you have successfully called the \ref IRtcEngine::joinChannel "joinChannel" method before calling this method. - - After calling this method, the SDK returns the \ref IRtcEngineEventHandler::onAudioRouteChanged "onAudioRouteChanged" callback to indicate the changes. - - This method does not take effect if a headset is used. - - Settings of \ref IRtcEngine::setAudioProfile "setAudioProfile" and \ref IRtcEngine::setChannelProfile "setChannelProfile" affect the call - result of `setEnableSpeakerphone`. The following are scenarios where `setEnableSpeakerphone` does not take effect: - - If you set `scenario` as `AUDIO_SCENARIO_GAME_STREAMING`, no user can change the audio playback route. - - If you set `scenario` as `AUDIO_SCENARIO_DEFAULT` or `AUDIO_SCENARIO_SHOWROOM`, the audience cannot change - the audio playback route. If there is only one broadcaster is in the channel, the broadcaster cannot change - the audio playback route either. - - If you set `scenario` as `AUDIO_SCENARIO_EDUCATION`, the audience cannot change the audio playback route. - - @param speakerOn Sets whether to route the audio to the speakerphone or earpiece: - - true: Route the audio to the speakerphone. If the playback device connects to the headset or Bluetooth, the audio cannot be routed to the speakerphone. - - false: Route the audio to the earpiece. If a headset is plugged in, the audio is routed to the headset. - - @return - - 0: Success. - - < 0: Failure. + /** + * Enables/Disables the audio route to the speakerphone. + * + * If the default audio route of the SDK (see *Set the Audio Route*) or the + * setting in \ref IRtcEngine::setDefaultAudioRouteToSpeakerphone "setDefaultAudioRouteToSpeakerphone" + * cannot meet your requirements, you can call this method to switch the current audio route. + * After successfully switching the audio route, the SDK triggers the + * \ref IRtcEngineEventHandler::onAudioRouteChanged "onAudioRouteChanged" callback to indicate the changes. + * + * This method only sets the audio route in the current channel and does not influence the default audio route. + * If the user leaves the current channel and joins another channel, the default audio route is used. + * + * @note + * - This method applies to Android and iOS only. + * - Call this method after calling joinChannel. + * - If the user uses an external audio playback device such as a Bluetooth or wired headset, this method + * does not take effect, and the SDK plays audio through the external device. When the user uses multiple external + * devices, the SDK plays audio through the last connected device. + * + * @param speakerOn Sets whether to enable the speakerphone or earpiece: + * - true: Enable the speakerphone. The audio route is the speakerphone. + * - false: Disable the speakerphone. The audio route is the earpiece. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int setEnableSpeakerphone(bool speakerOn) = 0; /** Enables in-ear monitoring (for Android and iOS only). @@ -7892,22 +9262,29 @@ class IRtcEngine { #endif #if (defined(__APPLE__) && TARGET_OS_IOS) - /** Sets the audio session’s operational restriction. - - The SDK and the app can both configure the audio session by default. The app may occasionally use other apps or third-party components to manipulate the audio session and restrict the SDK from doing so. This method allows the app to restrict the SDK’s manipulation of the audio session. - - You can call this method at any time to return the control of the audio sessions to the SDK. - - @note - - This method is for iOS only. - - This method restricts the SDK’s manipulation of the audio session. Any operation to the audio session relies solely on the app, other apps, or third-party components. - - You can call this method either before or after joining a channel. - - @param restriction The operational restriction (bit mask) of the SDK on the audio session. See #AUDIO_SESSION_OPERATION_RESTRICTION. - - @return - - 0: Success. - - < 0: Failure. + /** Sets the operational permission of the SDK on the audio session. + * + * The SDK and the app can both configure the audio session by default. If + * you need to only use the app to configure the audio session, this method + * restricts the operational permission of the SDK on the audio session. + * + * You can call this method either before or after joining a channel. Once + * you call this method to restrict the operational permission of the SDK + * on the audio session, the restriction takes effect when the SDK needs to + * change the audio session. + * + * @note + * - This method is for iOS only. + * - This method does not restrict the operational permission of the app on + * the audio session. + * + * @param restriction The operational permission of the SDK on the audio session. + * See #AUDIO_SESSION_OPERATION_RESTRICTION. This parameter is in bit mask + * format, and each bit corresponds to a permission. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int setAudioSessionOperationRestriction(AUDIO_SESSION_OPERATION_RESTRICTION restriction) = 0; #endif @@ -7930,15 +9307,49 @@ class IRtcEngine { */ virtual int enableLoopbackRecording(bool enabled, const char* deviceName = NULL) = 0; - -#if (defined(__APPLE__) && TARGET_OS_MAC && !TARGET_OS_IPHONE) + /** + * Gets a list of shareable screens and windows. + * + * @since v3.5.2 + * + * You can call this method before sharing a screen or window to get a list of shareable screens and windows, which + * enables a user to use thumbnails in the list to easily choose a particular screen or window to share. This list + * also contains important information such as window ID and screen ID, with which you can + * call \ref IRtcEngine::startScreenCaptureByWindowId "startScreenCaptureByWindowId" or + * \ref IRtcEngine::startScreenCaptureByDisplayId "startScreenCaptureByDisplayId" to start the sharing. + * + * @note This method applies to macOS and Windows only. + * + * @param thumbSize The target size of the screen or window thumbnail. The width and height are in pixels. See SIZE. + * The SDK scales the original image to make the length of the longest side of the image the same as that of the + * target size without distorting the original image. For example, if the original image is 400 × 300 and `thumbSize` + * is 100 × 100, the actual size of the thumbnail is 100 × 75. If the target size is larger than the original size, + * the thumbnail is the original image and the SDK does not scale it. + * @param iconSize The target size of the icon corresponding to the application program. The width and height are in + * pixels. See SIZE. The SDK scales the original image to make the length of the longest side of the image the same + * as that of the target size without distorting the original image. For example, if the original image is 400 × 300 + * and `iconSize` is 100 × 100, the actual size of the icon is 100 × 75. If the target size is larger than the + * original size, the icon is the original image and the SDK does not scale it. + * @param includeScreen Whether the SDK returns screen information in addition to window information: + * - true: The SDK returns screen and window information. + * - false: The SDK returns window information only. + * + * @return IScreenCaptureSourceList + */ + virtual IScreenCaptureSourceList* getScreenCaptureSources(const SIZE& thumbSize, const SIZE& iconSize, const bool includeScreen) = 0; /** Shares the whole or part of a screen by specifying the display ID. * * @note - * - This method is for macOS only. + * - This method is for macOS and Windows only. * - Ensure that you call this method after joining a channel. * - * @param displayId The display ID of the screen to be shared. This parameter specifies which screen you want to share. + * @warning On Windows platforms, if the user device is connected to another display, to avoid screen sharing issues, + * use `startScreenCaptureByDisplayId` to start sharing instead of + * using \ref IRtcEngine::startScreenCaptureByScreenRect "startScreenCaptureByScreenRect". + * + * @param displayId The display ID of the screen to be shared. Use this parameter to specify which screen you want to + * share. For more information on how to get the display ID, see the advanced feature guide *Share the Screen* or get + * the display ID from `sourceId` returned by \ref IRtcEngine::getScreenCaptureSources "getScreenCaptureSources". * @param regionRect (Optional) Sets the relative location of the region to the screen. NIL means sharing the whole screen. See Rectangle. If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen. * @param 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 `videoDimension` to calculate the charges. * For details, see descriptions in ScreenCaptureParameters. @@ -7950,7 +9361,6 @@ class IRtcEngine { * - #ERR_INVALID_ARGUMENT: The argument is invalid. */ virtual int startScreenCaptureByDisplayId(unsigned int displayId, const Rectangle& regionRect, const ScreenCaptureParameters& captureParams) = 0; -#endif #if defined(_WIN32) /** Shares the whole or part of a screen by specifying the screen rect. @@ -7959,6 +9369,10 @@ class IRtcEngine { * - Ensure that you call this method after joining a channel. * - Applies to the Windows platform only. * + * @warning On Windows platforms, if the user device is connected to another display, to avoid screen sharing issues, + * use \ref IRtcEngine::startScreenCaptureByDisplayId "startScreenCaptureByDisplayId" to start sharing instead of + * using \ref IRtcEngine::startScreenCaptureByScreenRect "startScreenCaptureByScreenRect". + * * @param screenRect Sets the relative location of the screen to the virtual screen. For information on how to get screenRect, see the advanced guide *Share Screen*. * @param regionRect (Optional) Sets the relative location of the region to the screen. NULL means sharing the whole screen. See Rectangle. If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen. * @param captureParams The screen sharing encoding parameters. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. @@ -7967,7 +9381,7 @@ class IRtcEngine { * @return * - 0: Success. * - < 0: Failure: - * - #ERR_INVALID_ARGUMENT : The argument is invalid. + * - #ERR_INVALID_ARGUMENT: The argument is invalid. */ virtual int startScreenCaptureByScreenRect(const Rectangle& screenRect, const Rectangle& regionRect, const ScreenCaptureParameters& captureParams) = 0; #endif @@ -8192,7 +9606,6 @@ class IRtcEngine { - < 0: Failure. */ virtual int updateScreenCaptureRegion(const Rect* rect) = 0; - #endif #if defined(_WIN32) @@ -8213,7 +9626,7 @@ class IRtcEngine { virtual bool setVideoSource(IVideoSource* source) = 0; #endif - /** Retrieves the current call ID. + /** Gets the current call ID. When a user joins a channel on a client, a @p callId is generated to identify the call from the client. Feedback methods, such as \ref IRtcEngine::rate "rate" and \ref IRtcEngine::complain "complain", must be called after the call ends to submit feedback to the SDK. @@ -8257,7 +9670,7 @@ class IRtcEngine { */ virtual int complain(const char* callId, const char* description) = 0; - /** Retrieves the SDK version number. + /** Gets the SDK version number. @param build Pointer to the build number. @return The version of the current SDK in the string format. For example, 2.3.1. @@ -8318,7 +9731,7 @@ class IRtcEngine { /** Stops the last-mile network probe test. */ virtual int stopLastmileProbeTest() = 0; - /** Retrieves the warning or error description. + /** Gets the warning or error description. @param code Warning code or error code returned in the \ref agora::rtc::IRtcEngineEventHandler::onWarning "onWarning" or \ref agora::rtc::IRtcEngineEventHandler::onError "onError" callback. @@ -8326,9 +9739,9 @@ class IRtcEngine { */ virtual const char* getErrorDescription(int code) = 0; - /** **DEPRECATED** Enables built-in encryption with an encryption password before users join a channel. + /** Enables built-in encryption with an encryption password before users join a channel. - Deprecated as of v3.1.0. Use the \ref agora::rtc::IRtcEngine::enableEncryption "enableEncryption" instead. + @deprecated Deprecated as of v3.1.0. Use the \ref agora::rtc::IRtcEngine::enableEncryption "enableEncryption" instead. All users in a channel must use the same encryption password. The encryption password is automatically cleared once a user leaves the channel. @@ -8344,9 +9757,9 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int setEncryptionSecret(const char* secret) = 0; + virtual int setEncryptionSecret(const char* secret) AGORA_DEPRECATED_ATTRIBUTE = 0; - /** **DEPRECATED** Sets the built-in encryption mode. + /** Sets the built-in encryption mode. @deprecated Deprecated as of v3.1.0. Use the \ref agora::rtc::IRtcEngine::enableEncryption "enableEncryption" instead. @@ -8368,7 +9781,7 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int setEncryptionMode(const char* encryptionMode) = 0; + virtual int setEncryptionMode(const char* encryptionMode) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Enables/Disables the built-in encryption. * @@ -8376,9 +9789,18 @@ class IRtcEngine { * * 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 a 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. + * After a user leaves the channel, the SDK automatically disables the built-in encryption. + * To re-enable the built-in encryption, call this method before the user joins the channel again. * - * @note If you enable the built-in encryption, you cannot use the RTMP or RTMPS streaming function. + * As of v3.4.5, Agora recommends using either the `AES_128_GCM2` or `AES_256_GCM2` encryption mode, + * both of which support adding a salt and are more secure. For details, see *Media Stream Encryption*. + * + * @warning All users in the same channel must use the same encryption mode, encryption key, and salt; otherwise, + * users cannot communicate with each other. + * + * @note + * - If you enable the built-in encryption, you cannot use the RTMP or RTMPS streaming function. + * - To enhance security, Agora recommends using a new key and salt every time you enable the media stream encryption. * * @param enabled Whether to enable the built-in encryption: * - true: Enable the built-in encryption. @@ -8401,7 +9823,7 @@ class IRtcEngine { @note - The size of the packet sent to the network after processing should not exceed 1200 bytes, otherwise, the packet may fail to be sent. - Ensure that both receivers and senders call this method, otherwise, you may meet undefined behaviors such as no voice and black screen. - - When you use CDN live streaming, recording or storage functions, Agora doesn't recommend calling this method. + - When you use CDN live streaming and recording functions, Agora doesn't recommend calling this method. - Call this method before joining a channel. @param observer Pointer to the registered packet observer. See IPacketObserver. @@ -8434,7 +9856,7 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int createDataStream(int* streamId, bool reliable, bool ordered) = 0; + virtual int createDataStream(int* streamId, bool reliable, bool ordered) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Creates a data stream. * * @since v3.3.0 @@ -8478,6 +9900,8 @@ class IRtcEngine { /** Publishes the local stream to a specified CDN live address. (CDN live only.) + @deprecated This method is deprecated as of v3.6.0. See [Release Notes](https://docs.agora.io/en/Interactive%20Broadcast/release_windows_video?platform=Windows) for an alternative solution. + The SDK returns the result of this method call in the \ref IRtcEngineEventHandler::onStreamPublished "onStreamPublished" callback. The \ref agora::rtc::IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onRtmpStreamingStateChanged "onRtmpStreamingStateChanged" callback on the local client to report the state of adding a local stream to the CDN. @@ -8498,10 +9922,12 @@ class IRtcEngine { - #ERR_INVALID_ARGUMENT (-2): The CDN streaming URL is NULL or has a string length of 0. - #ERR_NOT_INITIALIZED (-7): You have not initialized the RTC engine when publishing the stream. */ - virtual int addPublishStreamUrl(const char* url, bool transcodingEnabled) = 0; + virtual int addPublishStreamUrl(const char* url, bool transcodingEnabled) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Removes an RTMP or RTMPS stream from the CDN. (CDN live only.) + @deprecated This method is deprecated as of v3.6.0. See [Release Notes](https://docs.agora.io/en/Interactive%20Broadcast/release_windows_video?platform=Windows) for an alternative solution. + This method removes the CDN streaming URL (added by the \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method) from a CDN live stream. The SDK returns the result of this method call in the \ref IRtcEngineEventHandler::onStreamUnpublished "onStreamUnpublished" callback. The \ref agora::rtc::IRtcEngine::removePublishStreamUrl "removePublishStreamUrl" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onRtmpStreamingStateChanged "onRtmpStreamingStateChanged" callback on the local client to report the state of removing an RTMP or RTMPS stream from the CDN. @@ -8517,10 +9943,12 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int removePublishStreamUrl(const char* url) = 0; + virtual int removePublishStreamUrl(const char* url) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Sets the video layout and audio settings for CDN live. (CDN live only.) + @deprecated This method is deprecated as of v3.6.0. See [Release Notes](https://docs.agora.io/en/Interactive%20Broadcast/release_windows_video?platform=Windows) for an alternative solution. + The SDK triggers the \ref agora::rtc::IRtcEngineEventHandler::onTranscodingUpdated "onTranscodingUpdated" callback when you call the `setLiveTranscoding` method to update the transcoding setting. @note @@ -8536,7 +9964,104 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int setLiveTranscoding(const LiveTranscoding& transcoding) = 0; + virtual int setLiveTranscoding(const LiveTranscoding& transcoding) AGORA_DEPRECATED_ATTRIBUTE = 0; + /** + * Starts pushing media streams to a CDN without transcoding. + * + * @since v3.6.0 + * + * You can call this method to push a live audio-and-video stream to the specified CDN address. This method can push + * media streams to only one CDN address at a time, so if you need to push streams to multiple addresses, call this + * method multiple times. + * + * After you call this method, the SDK triggers the \ref IRtcEngineEventHandler::onRtmpStreamingStateChanged "onRtmpStreamingStateChanged" + * callback on the local client to report the state of the streaming. + * + * @note + * - Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in *Push Streams to CDN*. + * - Call this method after joining a channel. + * - Only hosts in the `LIVE_BROADCASTING` profile can call this method. + * - If you want to retry pushing streams after a failed push, make sure to call \ref IRtcEngine::stopRtmpStream "stopRtmpStream" first, + * then call this method to retry pushing streams; otherwise, the SDK returns the same error code as the last failed push. + * - If you want to push media streams in the RTMPS protocol to CDN, call \ref IRtcEngine::startRtmpStreamWithTranscoding "startRtmpStreamWithTranscoding" + * instead of \ref IRtcEngine::startRtmpStreamWithoutTranscoding "startRtmpStreamWithoutTranscoding". + * + * @param url The address of the CDN live streaming. The format is RTMP. The character length cannot exceed 1024 bytes. + * Special characters such as Chinese characters are not supported. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `ERR_INVALID_ARGUMENT(-2)`: url is null or the string length is 0. + * - `ERR_NOT_INITIALIZED(-7)`: The SDK is not initialized before calling this method. + */ + virtual int startRtmpStreamWithoutTranscoding(const char* url) = 0; + /** + * Starts pushing media streams to a CDN and sets the transcoding configuration. + * + * @since v3.6.0 + * + * You can call this method to push a live audio-and-video stream to the specified CDN address and set the transcoding + * configuration. This method can push media streams to only one CDN address at a time, so if you need to push streams to + * multiple addresses, call this method multiple times. + * + * After you call this method, the SDK triggers the \ref IRtcEngineEventHandler::onRtmpStreamingStateChanged "onRtmpStreamingStateChanged" + * callback on the local client to report the state of the streaming. + * + * @note + * - Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in *Push Streams to CDN*. + * - Call this method after joining a channel. + * - Only hosts in the `LIVE_BROADCASTING` profile can call this method. + * - If you want to retry pushing streams after a failed push, make sure to call \ref IRtcEngine::stopRtmpStream "stopRtmpStream" first, + * then call this method to retry pushing streams; otherwise, the SDK returns the same error code as the last failed push. + * - If you want to push media streams in the RTMPS protocol to CDN, call \ref IRtcEngine::startRtmpStreamWithTranscoding "startRtmpStreamWithTranscoding" + * instead of \ref IRtcEngine::startRtmpStreamWithoutTranscoding "startRtmpStreamWithoutTranscoding". + * + * @param url The address of the CDN live streaming. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. + * Special characters such as Chinese characters are not supported. + * @param transcoding The transcoding configuration for CDN live streaming. See LiveTranscoding. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `ERR_INVALID_ARGUMENT(-2)`: url is null or the string length is 0. + * - `ERR_NOT_INITIALIZED(-7)`: The SDK is not initialized before calling this method. + */ + virtual int startRtmpStreamWithTranscoding(const char* url, const LiveTranscoding& transcoding) = 0; + /** + * Updates the transcoding configuration. + * + * @since v3.6.0 + * + * After you start pushing media streams to CDN with transcoding, you can dynamically update the transcoding configuration according to the scenario. + * The SDK triggers the \ref IRtcEngineEventHandler::onTranscodingUpdated "onTranscodingUpdated" callback after the + * transcoding configuration is updated. + * + * @param transcoding The transcoding configuration for CDN live streaming. See LiveTranscoding. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int updateRtmpTranscoding(const LiveTranscoding& transcoding) = 0; + /** + * Stops pushing media streams to a CDN. + * + * @since v3.6.0 + * + * You can call this method to stop the live stream on the specified CDN address. + * This method can stop pushing media streams to only one CDN address at a time, so if you need to stop pushing streams to multiple addresses, call this method multiple times. + * + * After you call this method, the SDK triggers the \ref IRtcEngineEventHandler::onRtmpStreamingStateChanged "onRtmpStreamingStateChanged" callback on the local client to report the state of the streaming. + * + * @param url The address of the CDN live streaming. The format is RTMP or RTMPS. + * The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int stopRtmpStream(const char* url) = 0; /** **DEPRECATED** Adds a watermark image to the local video or CDN live stream. @@ -8562,29 +10087,31 @@ class IRtcEngine { virtual int addVideoWatermark(const RtcImage& watermark) = 0; /** Adds a watermark image to the local video. - - This method adds a PNG watermark image to the local video in the live streaming. Once the watermark image is added, all the audience in the channel (CDN audience included), - and the capturing device can see and capture it. Agora supports adding only one watermark image onto the local video, and the newly watermark image replaces the previous one. - - The watermark position depends on the settings in the \ref IRtcEngine::setVideoEncoderConfiguration "setVideoEncoderConfiguration" method: - - If the orientation mode of the encoding video is #ORIENTATION_MODE_FIXED_LANDSCAPE, or the landscape mode in #ORIENTATION_MODE_ADAPTIVE, the watermark uses the landscape orientation. - - If the orientation mode of the encoding video is #ORIENTATION_MODE_FIXED_PORTRAIT, or the portrait mode in #ORIENTATION_MODE_ADAPTIVE, the watermark uses the portrait orientation. - - When setting the watermark position, the region must be less than the dimensions set in the `setVideoEncoderConfiguration` method. Otherwise, the watermark image will be cropped. - - @note - - Ensure that you have called the \ref agora::rtc::IRtcEngine::enableVideo "enableVideo" method to enable the video module before calling this method. - - If you only want to add a watermark image to the local video for the audience in the CDN live streaming channel to see and capture, you can call this method or the \ref agora::rtc::IRtcEngine::setLiveTranscoding "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 \ref agora::rtc::IRtcEngine::startPreview "startPreview" method, you can use the `visibleInPreview` member in the WatermarkOptions class to set whether or not the watermark is visible in preview. - - If you have enabled the mirror mode for the local video, the watermark on the local video is also mirrored. To avoid mirroring the watermark, Agora recommends that you do not use the mirror and watermark functions for the local video at the same time. You can implement the watermark function in your application layer. - - @param 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. - @param options Pointer to the watermark's options to be added. See WatermarkOptions for more infomation. - - @return - - 0: Success. - - < 0: Failure. + * + * This method adds a PNG watermark image to the local video in the live streaming. Once the watermark image is added, all the audience in the channel (CDN audience included), + * and the capturing device can see and capture it. Agora supports adding only one watermark image onto the local video, and the newly watermark image replaces the previous one. + * + * The watermark position depends on the settings in the \ref IRtcEngine::setVideoEncoderConfiguration "setVideoEncoderConfiguration" method: + * - If the orientation mode of the encoding video is #ORIENTATION_MODE_FIXED_LANDSCAPE, or the landscape mode in #ORIENTATION_MODE_ADAPTIVE, the watermark uses the landscape orientation. + * - If the orientation mode of the encoding video is #ORIENTATION_MODE_FIXED_PORTRAIT, or the portrait mode in #ORIENTATION_MODE_ADAPTIVE, the watermark uses the portrait orientation. + * - When setting the watermark position, the region must be less than the dimensions set in the `setVideoEncoderConfiguration` method. Otherwise, the watermark image will be cropped. + * + * @note + * - Ensure that you have called the \ref agora::rtc::IRtcEngine::enableVideo "enableVideo" method to enable the video module before calling this method. + * - If you only want to add a watermark image to the local video for the audience in the CDN live streaming channel to see and capture, you can call this method or the \ref agora::rtc::IRtcEngine::setLiveTranscoding "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 \ref agora::rtc::IRtcEngine::startPreview "startPreview" method, you can use the `visibleInPreview` member in the WatermarkOptions class to set whether or not the watermark is visible in preview. + * - If you have enabled the mirror mode for the local video, the watermark on the local video is also mirrored. To avoid mirroring the watermark, Agora recommends that you do not use the mirror and watermark functions for the local video at the same time. You can implement the watermark function in your application layer. + * + * @param 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. + * On Android, Agora recommends passing a URI address or the path starts with `/assets/` in this parameter + * @param options Pointer to the watermark's options to be added. See WatermarkOptions for more infomation. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int addVideoWatermark(const char* watermarkUrl, const WatermarkOptions& options) = 0; @@ -8598,14 +10125,79 @@ class IRtcEngine { /** Enables/Disables image enhancement and sets the options. * - * @note Call this method after calling the \ref IRtcEngine::enableVideo "enableVideo" method. + * @note + * - Call this method after calling the \ref IRtcEngine::enableVideo "enableVideo" method. + * - On Android, this method applies to Android 5.0 or later. + * - Agora has updated the Agora image enhancement algorithm from v3.6.0 to enhance image enhancement effects and support sharpness adjustment. + * If you want to experience optimized image enhancement effects or set the sharpness, integrate the following dynamic library into the project before calling this method: + * - Android: `libagora_video_process_extension.so` + * - iOS: `AgoraVideoProcessExtension.xcframework` + * - macOS: `AgoraVideoProcessExtension.framework` + * - Windows: `libagora_video_process_extension.dll` + * + * @param enabled Determines whether to enable image enhancement: + * - true: Enables image enhancement. + * - false: Disables image enhancement. + * @param options The image enhancement option. See BeautyOptions. * - * @param enabled Sets whether or not to enable image enhancement: - * - true: enables image enhancement. - * - false: disables image enhancement. - * @param options Sets the image enhancement option. See BeautyOptions. + * @return + * - 0: Success. + * - < 0: Failure. + * - `-4(ERR_NOT_SUPPORTED)`: The system version is earlier than Android 5.0, which does not support this function. */ virtual int setBeautyEffectOptions(bool enabled, BeautyOptions options) = 0; + /** + * Enables/Disables the virtual background. (beta feature) + * + * Support for macOS and Windows as of v3.4.5 and Android and iOS as of v3.5.0. + * + * After enabling the virtual background feature, you can replace the original background image of the local user + * with a custom background image. After the replacement, all users in the channel can see the custom background + * image. You can find out from the + * \ref IRtcEngineEventHandler::onVirtualBackgroundSourceEnabled "onVirtualBackgroundSourceEnabled" callback + * whether the virtual background is successfully enabled or the cause of any errors. + * + * @note + * - Before calling this method, ensure that you have integrated the following dynamic library into your project: + * - Android: `libagora_segmentation_extension.so` + * - iOS: `AgoraVideoSegmentationExtension.xcframework` + * - macOS: `AgoraVideoSegmentationExtension.framework` + * - Windows: `libagora_segmentation_extension.dll` + * - Call this method after \ref IRtcEngine::enableVideo "enableVideo". + * - This functions requires a high-performance device. Agora recommends that you use this function on the + * following devices: + * - Android: Devices with the following chips: + * - Snapdragon 700 series 750G and later + * - Snapdragon 800 series 835 and later + * - Dimensity 700 series 720 and later + * - Kirin 800 series 810 and later + * - Kirin 900 series 980 and later + * - iOS: Devices with an A9 chip and better, as follows: + * - iPhone 6S and later + * - iPad Air (3rd generation) and later + * - iPad (5th generation) and later + * - iPad Pro (1st generation) and later + * - iPad mini (5th generation) and later + * - macOS and Windows: Devices with an i5 CPU and better + * - Agora recommends that you use this function in scenarios that meet the following conditions: + * - A high-definition camera device is used, and the environment is uniformly lit. + * - The captured video image is uncluttered, the user's portrait is half-length and largely unobstructed, and the + * background is a single color that differs from the color of the user's clothing. + * - The virtual background feature does not support video in the Texture format or video obtained from custom video capture by the Push method. + * + * @param enabled Sets whether to enable the virtual background: + * - true: Enable. + * - false: Disable. + * @param backgroundSource The custom background image. See VirtualBackgroundSource. + * Note: To adapt the resolution of the custom background image to the resolution of the SDK capturing video, + * the SDK scales and crops + * the custom background image while ensuring that the content of the custom background image is not distorted. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int enableVirtualBackground(bool enabled, VirtualBackgroundSource backgroundSource) = 0; /** Adds a voice or video stream URL address to the live streaming. @@ -8693,10 +10285,9 @@ class IRtcEngine { * "onChannelMediaRelayEvent" callback with the * #RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL (7) state code. * - * @note - * Call this method after the - * \ref startChannelMediaRelay() "startChannelMediaRelay" method to update - * the destination channel. + * @note Call this method after successfully calling the \ref startChannelMediaRelay() "startChannelMediaRelay" method + * and receiving the \ref IRtcEngineEventHandler::onChannelMediaRelayStateChanged "onChannelMediaRelayStateChanged" (RELAY_STATE_RUNNING, RELAY_OK) callback; + * otherwise, this method call fails. * * @param configuration The media stream relay configuration: * ChannelMediaRelayConfiguration. @@ -8706,6 +10297,47 @@ class IRtcEngine { * - < 0: Failure. */ virtual int updateChannelMediaRelay(const ChannelMediaRelayConfiguration& configuration) = 0; + + /** + * Pauses the media stream relay to all destination channels. + * + * @since v3.5.1 + * + * After the cross-channel media stream relay starts, you can call this method + * to pause relaying media streams to all destination channels; after the pause, + * if you want to resume the relay, call \ref IRtcEngine::resumeAllChannelMediaRelay "resumeAllChannelMediaRelay". + * + * After a successful method call, the SDK triggers the + * \ref IRtcEngineEventHandler::onChannelMediaRelayEvent "onChannelMediaRelayEvent" + * callback to report whether the media stream relay is successfully paused. + * + * @note Call this method after the \ref IRtcEngine::startChannelMediaRelay "startChannelMediaRelay" method. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int pauseAllChannelMediaRelay() = 0; + + /** Resumes the media stream relay to all destination channels. + * + * @since v3.5.1 + * + * After calling the \ref IRtcEngine::pauseAllChannelMediaRelay "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 + * \ref IRtcEngineEventHandler::onChannelMediaRelayEvent "onChannelMediaRelayEvent" + * callback to report whether the media stream relay is successfully resumed. + * + * @note Call this method after the \ref IRtcEngine::pauseAllChannelMediaRelay "pauseAllChannelMediaRelay" method. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int resumeAllChannelMediaRelay() = 0; + /** Stops the media stream relay. * * Once the relay stops, the host quits all the destination @@ -8764,81 +10396,88 @@ class IRtcEngine { @return #CONNECTION_STATE_TYPE. */ virtual CONNECTION_STATE_TYPE getConnectionState() = 0; - /// @cond - /** Enables/Disables the super-resolution algorithm for a remote user's video stream. + + /** Enables/Disables the super resolution feature for a remote user's video. (beta feature) * - * @since v3.2.0 + * @since v3.5.1 * - * The algorithm effectively improves the resolution of the specified remote user's video stream. When the original - * resolution of the remote video stream is a × b pixels, you can receive and render the stream at a higher - * resolution (2a × 2b pixels) by enabling the algorithm. + * This feature effectively boosts the resolution of a remote user's video seen by the local + * user. If the original resolution of a remote user's video is a × b, the local user's device + * can render the remote video at a resolution of 2a × 2b after you enable this feature. * * After calling this method, the SDK triggers the - * \ref IRtcEngineEventHandler::onUserSuperResolutionEnabled "onUserSuperResolutionEnabled" callback to report - * whether you have successfully enabled the super-resolution algorithm. - * - * @warning The super-resolution algorithm requires extra system resources. - * To balance the visual experience and system usage, the SDK poses the following restrictions: - * - The algorithm can only be used for a single user at a time. - * - On the Android platform, the original resolution of the remote video must not exceed 640 × 360 pixels. - * - On the iOS platform, the original resolution of the remote video must not exceed 640 × 480 pixels. - * If you exceed these limitations, the SDK triggers the \ref IRtcEngineEventHandler::onWarning "onWarning" - * callback with the corresponding warning codes: - * - #WARN_SUPER_RESOLUTION_STREAM_OVER_LIMITATION (1610): The origin resolution of the remote video is beyond the range where the super-resolution algorithm can be applied. - * - #WARN_SUPER_RESOLUTION_USER_COUNT_OVER_LIMITATION (1611): Another user is already using the super-resolution algorithm. - * - #WARN_SUPER_RESOLUTION_DEVICE_NOT_SUPPORTED (1612): The device does not support the super-resolution algorithm. + * \ref IRtcEngineEventHandler::onUserSuperResolutionEnabled "onUserSuperResolutionEnabled" + * callback to report whether you have successfully enabled super resolution. + * + * @warning The super resolution feature requires extra system resources. To balance the visual experience and system consumption, the SDK poses the following restrictions: + * - This feature can only be enabled for a single remote user. + * - The original resolution of the remote user's video cannot exceed a certain range. If the local user use super resolution on Android, + * the original resolution of the remote user's video cannot exceed 640 × 360 pixels; if the local user use super resolution on iOS, + * the original resolution of the remote user's video cannot exceed 640 × 480 pixels. + * + * @warning If you exceed these limitations, the SDK triggers the + * \ref IRtcEngineEventHandler::onWarning "onWarning" callback and returns the corresponding warning codes: + * - #WARN_SUPER_RESOLUTION_STREAM_OVER_LIMITATION (1610): The original resolution of the remote user's video is beyond + * the range where super resolution can be applied. + * - #WARN_SUPER_RESOLUTION_USER_COUNT_OVER_LIMITATION (1611): Super resolution is already being used to boost another + * remote user's video. + * - #WARN_SUPER_RESOLUTION_DEVICE_NOT_SUPPORTED (1612): The device does not support using super resolution. * * @note - * - This method applies to Android and iOS only. - * - Requirements for the user's device: - * - Android: The following devices are known to support the method: - * - VIVO: V1821A, NEX S, 1914A, 1916A, and 1824BA - * - OPPO: PCCM00 + * - This method is for Android and iOS only. + * - Before calling this method, ensure that you have integrated the following dynamic library into your project: + * - Android: `libagora_super_resolution_extension.so` + * - iOS: `AgoraSuperResolutionExtension.xcframework` + * - Because this method has certain system performance requirements, Agora recommends that you use the following devices or better: + * - Android: + * - VIVO: V1821A, NEX S, 1914A, 1916A, 1962A, 1824BA, X60, X60 Pro + * - OPPO: PCCM00, Find X3 * - OnePlus: A6000 - * - Xiaomi: Mi 8, Mi 9, MIX3, and Redmi K20 Pro - * - SAMSUNG: SM-G9600, SM-G9650, SM-N9600, SM-G9708, SM-G960U, and SM-G9750 - * - HUAWEI: SEA-AL00, ELE-AL00, VOG-AL00, YAL-AL10, HMA-AL00, and EVR-AN00 - * - iOS: This method is supported on devices running iOS 12.0 or later. The following - * device models are known to support the method: + * - Xiaomi: Mi 8, Mi 9, Mi 10, Mi 11, MIX3, Redmi K20 Pro + * - SAMSUNG: SM-G9600, SM-G9650, SM-N9600, SM-G9708, SM-G960U, SM-G9750, S20, S21 + * - HUAWEI: SEA-AL00, ELE-AL00, VOG-AL00, YAL-AL10, HMA-AL00, EVR-AN00, nova 4, nova 5 Pro, + * nova 6 5G, nova 7 5G, Mate 30, Mate 30 Pro, Mate 40, Mate 40 Pro, P40 P40 Pro, HUAWEI MediaPad M6, MatePad 10.8 + * - iOS (iOS 12.0 or later): * - iPhone XR * - iPhone XS * - iPhone XS Max * - iPhone 11 * - iPhone 11 Pro * - iPhone 11 Pro Max - * - iPad Pro 11-inch (3rd Generation) - * - iPad Pro 12.9-inch (3rd Generation) - * - iPad Air 3 (3rd Generation) - * - * @param userId The ID of the remote user. - * @param enable Whether to enable the super-resolution algorithm: - * - true: Enable the super-resolution algorithm. - * - false: Disable the super-resolution algorithm. + * - iPhone 12 + * - iPhone 12 mini + * - iPhone 12 Pro + * - iPhone 12 Pro Max + * - iPhone 12 SE (2nd generation) + * - iPad Pro 11-inch (3rd generation) + * - iPad Pro 12.9-inch (3rd generation) + * - iPad Air (3rd generation) + * - iPad Air (4th generation) + * + * @param userId The user ID of the remote user. + * @param enable Determines whether to enable super resolution for the remote user's video: + * - true: Enable super resolution. + * - false: Disable super resolution. * * @return * - 0: Success. * - < 0: Failure. - * - -158 (ERR_MODULE_SUPER_RESOLUTION_NOT_FOUND): You have not integrated the dynamic library for the super-resolution algorithm. + * - `-157 (ERR_MODULE_NOT_FOUND)`: The dynamic library for super resolution is not integrated. */ virtual int enableRemoteSuperResolution(uid_t userId, bool enable) = 0; - /// @endcond - - /** Registers the metadata observer. + /** This method enables you to add synchronized metadata in the video stream for more diversified interactive live streaming, such as sending shopping links, digital coupons, and online quizzes. - Registers the metadata observer. You need to implement the IMetadataObserver class and specify the metadata type in this method. A successful call of this method triggers the \ref agora::rtc::IMetadataObserver::getMaxMetadataSize "getMaxMetadataSize" callback. - This method enables you to add synchronized metadata in the video stream for more diversified interactive live streaming, such as sending shopping links, digital coupons, and online quizzes. - - @note - - Call this method before the joinChannel method. - - This method applies to the `LIVE_BROADCASTING` channel profile. + @note + - Call this method before the joinChannel method. + - This method applies to the `LIVE_BROADCASTING` channel profile. - @param observer The IMetadataObserver class. See the definition of IMetadataObserver for details. - @param type See \ref IMetadataObserver::METADATA_TYPE "METADATA_TYPE". The SDK supports VIDEO_METADATA (0) only for now. + @param observer The IMetadataObserver class. See the definition of IMetadataObserver for details. + @param type See \ref IMetadataObserver::METADATA_TYPE "METADATA_TYPE". The SDK supports VIDEO_METADATA (0) only for now. - @return - - 0: Success. - - < 0: Failure. - */ + @return + - 0: Success. + - < 0: Failure. + */ virtual int registerMediaMetadataObserver(IMetadataObserver* observer, IMetadataObserver::METADATA_TYPE type) = 0; /** Provides technical preview functionalities or special customizations by configuring the SDK with JSON options. @@ -8851,53 +10490,186 @@ class IRtcEngine { - < 0: Failure. */ virtual int setParameters(const char* parameters) = 0; -}; - -class IRtcEngineParameter { - public: - virtual ~IRtcEngineParameter() {} - /** - * Releases all IRtcEngineParameter resources. - */ - virtual void release() = 0; - - /** Sets the bool value of a specified key in the JSON format. - - @param key Pointer to the name of the key. - @param value Sets the value. - @return - - 0: Success. - - < 0: Failure. - */ - virtual int setBool(const char* key, bool value) = 0; - - /** Sets the int value of a specified key in the JSON format. - @param key Pointer to the name of the key. - @param value Sets the value. + // virtual int getMediaRecorder(IMediaRecorderObserver *observer, int sys_version = 0) = 0; - @return - - 0: Success. - - < 0: Failure. - */ - virtual int setInt(const char* key, int value) = 0; - /** Sets the unsigned int value of a specified key in the JSON format. + // virtual int startRecording(const MediaRecorderConfiguration &config) = 0; - @param key Pointer to the name of the key. - @param value Sets the value. + // virtual int stopRecording() = 0; - @return - - 0: Success. - - < 0: Failure. + // virtual int releaseRecorder() = 0; +#if defined(_WIN32) + /** + * Customizes the local video renderer. (for Windows only) + * + * @since v3.5.0 + * + * During a real-time audio and video interaction, the Agora SDK enables the default renderer to render local video. + * If you want to customize the local video rendering, you can first customize the video renderer via the IVideoSink + * class, and then call this method to use the custom video renderer to render the local video. + * + * @note You can call this method either before or after joining a channel. + * + * @param videoSink The custom video renderer. See IVideoSink. + * + * @return + * - 0: Success. + * - < 0: Failure. */ - virtual int setUInt(const char* key, unsigned int value) = 0; - - /** Sets the double value of a specified key in the JSON format. - - @param key Pointer to the name of the key. - @param value Sets the value. - + virtual int setLocalVideoRenderer(IVideoSink* videoSink) = 0; + /** + * Customizes the remote video renderer. (for Windows only) + * + * @since v3.5.0 + * + * During a real-time audio and video interaction, the Agora SDK enables the default renderer to render remote video. + * If you want to customize the remote video rendering, you can first customize the video renderer via the IVideoSink + * class, and then call this method to use the custom video renderer to render the remote video. + * + * @note You can call this method either before or after joining a channel. + * + * @param uid The user ID of the remote user. + * @param videoSink The custom video renderer. See IVideoSink. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int setRemoteVideoRenderer(uid_t uid, IVideoSink* videoSink) = 0; +#endif + /// @cond + virtual int setLocalAccessPoint(const LocalAccessPointConfiguration& config) = 0; + /// @endcond +#if defined(__ANDROID__) || (defined(__APPLE__) && TARGET_OS_IOS) + /** + * Sets whether to enable the flash. + * + * @since v3.5.1 + * + * @note + * - Call this method after the camera is started. + * - This method is for Android and iOS only. + * - On iPads with system version 15, even if \ref IRtcEngine::isCameraTorchSupported "isCameraTorchSupported" + * returns true, you might fail to successfully enable the flash by calling `setCameraTorchOn` due to + * system issues. + * + * @param isOn Determines whether to enable the flash: + * - true: Enable the flash. + * - false: Disable the flash. + * + * @return + * - 0: Success + * - < 0: Failure + */ + virtual int setCameraTorchOn(bool isOn) = 0; + /** + * Checks whether the device supports enabling the flash. + * + * @since v3.5.1 + * + * The SDK uses the front camera by default, so if you call `isCameraTorchSupported` directly, + * you can find out from the return value whether the device supports enabling the flash + * when using the front camera. If you want to check whether the device supports enabling the + * flash when using the rear camera, call \ref IRtcEngine::switchCamera "switchCamera" + * to switch the camera used by the SDK to the rear camera, and then call `isCameraTorchSupported`. + * + * @note + * - Call this method after the camera is started. + * - This method is for Android and iOS only. + * - On iPads with system version 15, even if `isCameraTorchSupported` returns true, you might + * fail to successfully enable the flash by calling \ref IRtcEngine::setCameraTorchOn "setCameraTorchOn" + * due to system issues. + * + * + * @return + * - true: The device supports enabling the flash. + * - false: The device does not support enabling the flash. + */ + virtual bool isCameraTorchSupported() = 0; +#endif + + /** + * Takes a snapshot of a video stream. + * + * @since v3.5.2 + * + * This method takes a snapshot of a video stream from the specified user, generates a JPG image, + * and saves it to the specified path. + * + * The method is asynchronous, and the SDK has not taken the snapshot when the method call returns. + * After a successful method call, the SDK triggers the \ref IRtcEngineEventHandler::onSnapshotTaken "onSnapshotTaken" + * callback to report whether the snapshot is successfully taken as well as the details of the snapshot taken. + * + * @note + * - Call this method after joining a channel. + * - If the video of the specified user is pre-processed, for example, added with watermarks or image enhancement + * effects, the generated snapshot also includes the pre-processing effects. + * + * @param channel The channel name. + * @param uid The user ID of the user. Set `uid` as 0 if you want to take a snapshot of the local user's video. + * @param filePath The local path (including the filename extensions) of the snapshot. For example, + * `C:\Users\\AppData\Local\Agora\\example.jpg` on Windows, + * `/App Sandbox/Library/Caches/example.jpg` on iOS, `～/Library/Logs/example.jpg` on macOS, and + * `/storage/emulated/0/Android/data//files/example.jpg` on Android. Ensure that the path you specify + * exists and is writable. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int takeSnapshot(const char* channel, uid_t uid, const char* filePath) = 0; + + /// @cond + virtual int enableContentInspect(bool enabled, const ContentInspectConfig& config) = 0; + /// @endcond +}; + +class IRtcEngineParameter { + public: + virtual ~IRtcEngineParameter() {} + /** + * Releases all IRtcEngineParameter resources. + */ + virtual void release() = 0; + + /** Sets the bool value of a specified key in the JSON format. + + @param key Pointer to the name of the key. + @param value Sets the value. + @return + - 0: Success. + - < 0: Failure. + */ + virtual int setBool(const char* key, bool value) = 0; + + /** Sets the int value of a specified key in the JSON format. + + @param key Pointer to the name of the key. + @param value Sets the value. + + @return + - 0: Success. + - < 0: Failure. + */ + virtual int setInt(const char* key, int value) = 0; + + /** Sets the unsigned int value of a specified key in the JSON format. + + @param key Pointer to the name of the key. + @param value Sets the value. + + @return + - 0: Success. + - < 0: Failure. + */ + virtual int setUInt(const char* key, unsigned int value) = 0; + + /** Sets the double value of a specified key in the JSON format. + + @param key Pointer to the name of the key. + @param value Sets the value. + @return - 0: Success. - < 0: Failure. @@ -8926,7 +10698,7 @@ class IRtcEngineParameter { */ virtual int setObject(const char* key, const char* value) = 0; - /** Retrieves the bool value of a specified key in the JSON format. + /** Gets the bool value of a specified key in the JSON format. @param key Pointer to the name of the key. @param value Pointer to the retrieved value. @@ -8937,7 +10709,7 @@ class IRtcEngineParameter { */ virtual int getBool(const char* key, bool& value) = 0; - /** Retrieves the int value of the JSON format. + /** Gets the int value of the JSON format. @param key Pointer to the name of the key. @param value Pointer to the retrieved value. @@ -8948,7 +10720,7 @@ class IRtcEngineParameter { */ virtual int getInt(const char* key, int& value) = 0; - /** Retrieves the unsigned int value of a specified key in the JSON format. + /** Gets the unsigned int value of a specified key in the JSON format. @param key Pointer to the name of the key. @param value Pointer to the retrieved value. @@ -8958,7 +10730,7 @@ class IRtcEngineParameter { */ virtual int getUInt(const char* key, unsigned int& value) = 0; - /** Retrieves the double value of a specified key in the JSON format. + /** Gets the double value of a specified key in the JSON format. @param key Pointer to the name of the key. @param value Pointer to the retrieved value. @@ -8969,7 +10741,7 @@ class IRtcEngineParameter { */ virtual int getNumber(const char* key, double& value) = 0; - /** Retrieves the string value of a specified key in the JSON format. + /** Gets the string value of a specified key in the JSON format. @param key Pointer to the name of the key. @param value Pointer to the retrieved value. @@ -8980,7 +10752,7 @@ class IRtcEngineParameter { */ virtual int getString(const char* key, agora::util::AString& value) = 0; - /** Retrieves a child object value of a specified key in the JSON format. + /** Gets a child object value of a specified key in the JSON format. @param key Pointer to the name of the key. @param value Pointer to the retrieved value. @@ -8990,7 +10762,7 @@ class IRtcEngineParameter { */ virtual int getObject(const char* key, agora::util::AString& value) = 0; - /** Retrieves the array value of a specified key in the JSON format. + /** Gets the array value of a specified key in the JSON format. @param key Pointer to the name of the key. @param value Pointer to the retrieved value. @@ -9036,7 +10808,7 @@ class AVideoDeviceManager : public agora::util::AutoPtr { AVideoDeviceManager(IRtcEngine* engine) { queryInterface(engine, AGORA_IID_VIDEO_DEVICE_MANAGER); } }; -class AParameter : public agora::util::AutoPtr { +class AGORA_CPP_API AParameter : public agora::util::AutoPtr { public: AParameter(IRtcEngine& engine) { initialize(&engine); } AParameter(IRtcEngine* engine) { initialize(engine); } @@ -9051,483 +10823,92 @@ class AParameter : public agora::util::AutoPtr { }; /** **DEPRECATED** The RtcEngineParameters class is deprecated, use the IRtcEngine class instead. */ -class RtcEngineParameters { +class AGORA_CPP_API RtcEngineParameters { public: RtcEngineParameters(IRtcEngine& engine) : m_parameter(&engine) {} RtcEngineParameters(IRtcEngine* engine) : m_parameter(engine) {} - int enableLocalVideo(bool enabled) { return setParameters("{\"rtc.video.capture\":%s,\"che.video.local.capture\":%s,\"che.video.local.render\":%s,\"che.video.local.send\":%s}", enabled ? "true" : "false", enabled ? "true" : "false", enabled ? "true" : "false", enabled ? "true" : "false"); } - - int muteLocalVideoStream(bool mute) { return setParameters("{\"rtc.video.mute_me\":%s,\"che.video.local.send\":%s}", mute ? "true" : "false", mute ? "false" : "true"); } - - int muteAllRemoteVideoStreams(bool mute) { return m_parameter ? m_parameter->setBool("rtc.video.mute_peers", mute) : -ERR_NOT_INITIALIZED; } - - int setDefaultMuteAllRemoteVideoStreams(bool mute) { return m_parameter ? m_parameter->setBool("rtc.video.set_default_mute_peers", mute) : -ERR_NOT_INITIALIZED; } - - int muteRemoteVideoStream(uid_t uid, bool mute) { return setObject("rtc.video.mute_peer", "{\"uid\":%u,\"mute\":%s}", uid, mute ? "true" : "false"); } - - int setPlaybackDeviceVolume(int volume) { // [0,255] - return m_parameter ? m_parameter->setInt("che.audio.output.volume", volume) : -ERR_NOT_INITIALIZED; - } - - int startAudioRecording(const char* filePath, AUDIO_RECORDING_QUALITY_TYPE quality) { return startAudioRecording(filePath, 32000, quality); } - - int startAudioRecording(const char* filePath, int sampleRate, AUDIO_RECORDING_QUALITY_TYPE quality) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; -#if defined(_WIN32) - util::AString path; - if (!m_parameter->convertPath(filePath, path)) - filePath = path->c_str(); - else - return -ERR_INVALID_ARGUMENT; -#endif - return setObject("che.audio.start_recording", "{\"filePath\":\"%s\",\"sampleRate\":%d,\"quality\":%d}", filePath, sampleRate, quality); - } - - int stopAudioRecording() { return setParameters("{\"che.audio.stop_recording\":true, \"che.audio.stop_nearend_recording\":true, \"che.audio.stop_farend_recording\":true}"); } - - int startAudioMixing(const char* filePath, bool loopback, bool replace, int cycle, int startPos = 0) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; -#if defined(_WIN32) - util::AString path; - if (!m_parameter->convertPath(filePath, path)) - filePath = path->c_str(); - else - return -ERR_INVALID_ARGUMENT; -#endif - return setObject("che.audio.start_file_as_playout", "{\"filePath\":\"%s\",\"loopback\":%s,\"replace\":%s,\"cycle\":%d, \"startPos\":%d}", filePath, loopback ? "true" : "false", replace ? "true" : "false", cycle, startPos); - } - - int stopAudioMixing() { return m_parameter ? m_parameter->setBool("che.audio.stop_file_as_playout", true) : -ERR_NOT_INITIALIZED; } - - int pauseAudioMixing() { return m_parameter ? m_parameter->setBool("che.audio.pause_file_as_playout", true) : -ERR_NOT_INITIALIZED; } - - int resumeAudioMixing() { return m_parameter ? m_parameter->setBool("che.audio.pause_file_as_playout", false) : -ERR_NOT_INITIALIZED; } - - int adjustAudioMixingVolume(int volume) { - int ret = adjustAudioMixingPlayoutVolume(volume); - if (ret == 0) { - adjustAudioMixingPublishVolume(volume); - } - return ret; - } - - int adjustAudioMixingPlayoutVolume(int volume) { return m_parameter ? m_parameter->setInt("che.audio.set_file_as_playout_volume", volume) : -ERR_NOT_INITIALIZED; } - - int getAudioMixingPlayoutVolume() { - int volume = 0; - int r = m_parameter ? m_parameter->getInt("che.audio.get_file_as_playout_volume", volume) : -ERR_NOT_INITIALIZED; - if (r == 0) r = volume; - return r; - } - - int adjustAudioMixingPublishVolume(int volume) { return m_parameter ? m_parameter->setInt("che.audio.set_file_as_playout_publish_volume", volume) : -ERR_NOT_INITIALIZED; } - - int getAudioMixingPublishVolume() { - int volume = 0; - int r = m_parameter ? m_parameter->getInt("che.audio.get_file_as_playout_publish_volume", volume) : -ERR_NOT_INITIALIZED; - if (r == 0) r = volume; - return r; - } - - int getAudioMixingDuration() { - int duration = 0; - int r = m_parameter ? m_parameter->getInt("che.audio.get_mixing_file_length_ms", duration) : -ERR_NOT_INITIALIZED; - if (r == 0) r = duration; - return r; - } - - int getAudioMixingCurrentPosition() { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - int pos = 0; - int r = m_parameter->getInt("che.audio.get_mixing_file_played_ms", pos); - if (r == 0) r = pos; - return r; - } - - int setAudioMixingPosition(int pos /*in ms*/) { return m_parameter ? m_parameter->setInt("che.audio.mixing.file.position", pos) : -ERR_NOT_INITIALIZED; } - - int setAudioMixingPitch(int pitch) { - if (!m_parameter) { - return -ERR_NOT_INITIALIZED; - } - if (pitch > 12 || pitch < -12) { - return -ERR_INVALID_ARGUMENT; - } - return m_parameter->setInt("che.audio.set_playout_file_pitch_semitones", pitch); - } - - int getEffectsVolume() { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - int volume = 0; - int r = m_parameter->getInt("che.audio.game_get_effects_volume", volume); - if (r == 0) r = volume; - return r; - } - - int setEffectsVolume(int volume) { return m_parameter ? m_parameter->setInt("che.audio.game_set_effects_volume", volume) : -ERR_NOT_INITIALIZED; } - - int setVolumeOfEffect(int soundId, int volume) { return setObject("che.audio.game_adjust_effect_volume", "{\"soundId\":%d,\"gain\":%d}", soundId, volume); } - - int playEffect(int soundId, const char* filePath, int loopCount, double pitch, double pan, int gain, bool publish = false) { -#if defined(_WIN32) - util::AString path; - if (!m_parameter->convertPath(filePath, path)) - filePath = path->c_str(); - else if (!filePath) - filePath = ""; -#endif - return setObject("che.audio.game_play_effect", "{\"soundId\":%d,\"filePath\":\"%s\",\"loopCount\":%d, \"pitch\":%lf,\"pan\":%lf,\"gain\":%d, \"send2far\":%d}", soundId, filePath, loopCount, pitch, pan, gain, publish); - } - - int stopEffect(int soundId) { return m_parameter ? m_parameter->setInt("che.audio.game_stop_effect", soundId) : -ERR_NOT_INITIALIZED; } - - int stopAllEffects() { return m_parameter ? m_parameter->setBool("che.audio.game_stop_all_effects", true) : -ERR_NOT_INITIALIZED; } - - int preloadEffect(int soundId, char* filePath) { return setObject("che.audio.game_preload_effect", "{\"soundId\":%d,\"filePath\":\"%s\"}", soundId, filePath); } - - int unloadEffect(int soundId) { return m_parameter ? m_parameter->setInt("che.audio.game_unload_effect", soundId) : -ERR_NOT_INITIALIZED; } - - int pauseEffect(int soundId) { return m_parameter ? m_parameter->setInt("che.audio.game_pause_effect", soundId) : -ERR_NOT_INITIALIZED; } - - int pauseAllEffects() { return m_parameter ? m_parameter->setBool("che.audio.game_pause_all_effects", true) : -ERR_NOT_INITIALIZED; } - - int resumeEffect(int soundId) { return m_parameter ? m_parameter->setInt("che.audio.game_resume_effect", soundId) : -ERR_NOT_INITIALIZED; } - - int resumeAllEffects() { return m_parameter ? m_parameter->setBool("che.audio.game_resume_all_effects", true) : -ERR_NOT_INITIALIZED; } - - int enableSoundPositionIndication(bool enabled) { return m_parameter ? m_parameter->setBool("che.audio.enable_sound_position", enabled) : -ERR_NOT_INITIALIZED; } - - int setRemoteVoicePosition(uid_t uid, double pan, double gain) { return setObject("che.audio.game_place_sound_position", "{\"uid\":%u,\"pan\":%lf,\"gain\":%lf}", uid, pan, gain); } - - int setLocalVoicePitch(double pitch) { return m_parameter ? m_parameter->setInt("che.audio.morph.pitch_shift", static_cast(pitch * 100)) : -ERR_NOT_INITIALIZED; } - - int setLocalVoiceEqualization(AUDIO_EQUALIZATION_BAND_FREQUENCY bandFrequency, int bandGain) { return setObject("che.audio.morph.equalization", "{\"index\":%d,\"gain\":%d}", static_cast(bandFrequency), bandGain); } - - int setLocalVoiceReverb(AUDIO_REVERB_TYPE reverbKey, int value) { return setObject("che.audio.morph.reverb", "{\"key\":%d,\"value\":%d}", static_cast(reverbKey), value); } - - int setLocalVoiceChanger(VOICE_CHANGER_PRESET voiceChanger) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - if (voiceChanger == 0x00000000) { - return m_parameter->setInt("che.audio.morph.voice_changer", static_cast(voiceChanger)); - } else if (voiceChanger > 0x00000000 && voiceChanger < 0x00100000) { - return m_parameter->setInt("che.audio.morph.voice_changer", static_cast(voiceChanger)); - } else if (voiceChanger > 0x00100000 && voiceChanger < 0x00200000) { - return m_parameter->setInt("che.audio.morph.voice_changer", static_cast(voiceChanger - 0x00100000 + 6)); - } else if (voiceChanger > 0x00200000 && voiceChanger < 0x00300000) { - return m_parameter->setInt("che.audio.morph.beauty_voice", static_cast(voiceChanger - 0x00200000)); - } else { - return -ERR_INVALID_ARGUMENT; - } - } - - int setLocalVoiceReverbPreset(AUDIO_REVERB_PRESET reverbPreset) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - if (reverbPreset == 0x00000000) { - return m_parameter->setInt("che.audio.morph.reverb_preset", static_cast(reverbPreset)); - } else if (reverbPreset > 0x00000000 && reverbPreset < 0x00100000) { - return m_parameter->setInt("che.audio.morph.reverb_preset", static_cast(reverbPreset + 8)); - } else if (reverbPreset > 0x00100000 && reverbPreset < 0x00200000) { - return m_parameter->setInt("che.audio.morph.reverb_preset", static_cast(reverbPreset - 0x00100000)); - } else if (reverbPreset > 0x00200000 && reverbPreset < 0x00200002) { - return m_parameter->setInt("che.audio.morph.virtual_stereo", static_cast(reverbPreset - 0x00200000)); - } else if (reverbPreset > (AUDIO_REVERB_PRESET)0x00300000 && reverbPreset < (AUDIO_REVERB_PRESET)0x00300002) - return setObject("che.audio.morph.electronic_voice", "{\"key\":%d,\"value\":%d}", 1, 4); - else if (reverbPreset > (AUDIO_REVERB_PRESET)0x00400000 && reverbPreset < (AUDIO_REVERB_PRESET)0x00400002) - return m_parameter->setInt("che.audio.morph.threedim_voice", 10); - else { - return -ERR_INVALID_ARGUMENT; - } - } - - int setAudioEffectPreset(AUDIO_EFFECT_PRESET preset) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - if (preset == AUDIO_EFFECT_OFF) { - return m_parameter->setInt("che.audio.morph.voice_changer", 0); - } - if (preset == ROOM_ACOUSTICS_KTV) { - return m_parameter->setInt("che.audio.morph.reverb_preset", 1); - } - if (preset == ROOM_ACOUSTICS_VOCAL_CONCERT) { - return m_parameter->setInt("che.audio.morph.reverb_preset", 2); - } - if (preset == ROOM_ACOUSTICS_STUDIO) { - return m_parameter->setInt("che.audio.morph.reverb_preset", 5); - } - if (preset == ROOM_ACOUSTICS_PHONOGRAPH) { - return m_parameter->setInt("che.audio.morph.reverb_preset", 8); - } - if (preset == ROOM_ACOUSTICS_VIRTUAL_STEREO) { - return m_parameter->setInt("che.audio.morph.virtual_stereo", 1); - } - if (preset == ROOM_ACOUSTICS_SPACIAL) { - return m_parameter->setInt("che.audio.morph.voice_changer", 15); - } - if (preset == ROOM_ACOUSTICS_ETHEREAL) { - return m_parameter->setInt("che.audio.morph.voice_changer", 5); - } - if (preset == ROOM_ACOUSTICS_3D_VOICE) { - return m_parameter->setInt("che.audio.morph.threedim_voice", 10); - } - if (preset == VOICE_CHANGER_EFFECT_UNCLE) { - return m_parameter->setInt("che.audio.morph.reverb_preset", 3); - } - if (preset == VOICE_CHANGER_EFFECT_OLDMAN) { - return m_parameter->setInt("che.audio.morph.voice_changer", 1); - } - if (preset == VOICE_CHANGER_EFFECT_BOY) { - return m_parameter->setInt("che.audio.morph.voice_changer", 2); - } - if (preset == VOICE_CHANGER_EFFECT_SISTER) { - return m_parameter->setInt("che.audio.morph.reverb_preset", 4); - } - if (preset == VOICE_CHANGER_EFFECT_GIRL) { - return m_parameter->setInt("che.audio.morph.voice_changer", 3); - } - if (preset == VOICE_CHANGER_EFFECT_PIGKING) { - return m_parameter->setInt("che.audio.morph.voice_changer", 4); - } - if (preset == VOICE_CHANGER_EFFECT_HULK) { - return m_parameter->setInt("che.audio.morph.voice_changer", 6); - } - if (preset == STYLE_TRANSFORMATION_RNB) { - return m_parameter->setInt("che.audio.morph.reverb_preset", 7); - } - if (preset == STYLE_TRANSFORMATION_POPULAR) { - return m_parameter->setInt("che.audio.morph.reverb_preset", 6); - } - if (preset == PITCH_CORRECTION) { - return setObject("che.audio.morph.electronic_voice", "{\"key\":%d,\"value\":%d}", 1, 4); - } - return -ERR_INVALID_ARGUMENT; - } - - int setVoiceBeautifierPreset(VOICE_BEAUTIFIER_PRESET preset) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - if (preset == VOICE_BEAUTIFIER_OFF) { - return m_parameter->setInt("che.audio.morph.voice_changer", 0); - } - if (preset == CHAT_BEAUTIFIER_MAGNETIC) { - return m_parameter->setInt("che.audio.morph.beauty_voice", 1); - } - if (preset == CHAT_BEAUTIFIER_FRESH) { - return m_parameter->setInt("che.audio.morph.beauty_voice", 2); - } - if (preset == CHAT_BEAUTIFIER_VITALITY) { - return m_parameter->setInt("che.audio.morph.beauty_voice", 3); - } - if (preset == SINGING_BEAUTIFIER) { - return setObject("che.audio.morph.beauty_sing", "{\"key\":%d,\"value\":%d}", 1, 1); - } - if (preset == TIMBRE_TRANSFORMATION_VIGOROUS) { - return m_parameter->setInt("che.audio.morph.voice_changer", 7); - } - if (preset == TIMBRE_TRANSFORMATION_DEEP) { - return m_parameter->setInt("che.audio.morph.voice_changer", 8); - } - if (preset == TIMBRE_TRANSFORMATION_MELLOW) { - return m_parameter->setInt("che.audio.morph.voice_changer", 9); - } - if (preset == TIMBRE_TRANSFORMATION_FALSETTO) { - return m_parameter->setInt("che.audio.morph.voice_changer", 10); - } - if (preset == TIMBRE_TRANSFORMATION_FULL) { - return m_parameter->setInt("che.audio.morph.voice_changer", 11); - } - if (preset == TIMBRE_TRANSFORMATION_CLEAR) { - return m_parameter->setInt("che.audio.morph.voice_changer", 12); - } - if (preset == TIMBRE_TRANSFORMATION_RESOUNDING) { - return m_parameter->setInt("che.audio.morph.voice_changer", 13); - } - if (preset == TIMBRE_TRANSFORMATION_RINGING) { - return m_parameter->setInt("che.audio.morph.voice_changer", 14); - } - return -ERR_INVALID_ARGUMENT; - } - - int setAudioEffectParameters(AUDIO_EFFECT_PRESET preset, int param1, int param2) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - if (preset == PITCH_CORRECTION) { - return setObject("che.audio.morph.electronic_voice", "{\"key\":%d,\"value\":%d}", param1, param2); - } - if (preset == ROOM_ACOUSTICS_3D_VOICE) { - return m_parameter->setInt("che.audio.morph.threedim_voice", param1); - } - return -ERR_INVALID_ARGUMENT; - } - - int setVoiceBeautifierParameters(VOICE_BEAUTIFIER_PRESET preset, int param1, int param2) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - if (preset == SINGING_BEAUTIFIER) { - return setObject("che.audio.morph.beauty_sing", "{\"key\":%d,\"value\":%d}", param1, param2); - } - return -ERR_INVALID_ARGUMENT; - } - - /** **DEPRECATED** Use \ref IRtcEngine::disableAudio "disableAudio" instead. Disables the audio function in the channel. - - @return - - 0: Success. - - < 0: Failure. - */ - int pauseAudio() { return m_parameter ? m_parameter->setBool("che.pause.audio", true) : -ERR_NOT_INITIALIZED; } - - int resumeAudio() { return m_parameter ? m_parameter->setBool("che.pause.audio", false) : -ERR_NOT_INITIALIZED; } - - int setHighQualityAudioParameters(bool fullband, bool stereo, bool fullBitrate) { return setObject("che.audio.codec.hq", "{\"fullband\":%s,\"stereo\":%s,\"fullBitrate\":%s}", fullband ? "true" : "false", stereo ? "true" : "false", fullBitrate ? "true" : "false"); } - - int adjustRecordingSignalVolume(int volume) { //[0, 400]: e.g. 50~0.5x 100~1x 400~4x - if (volume < 0) - volume = 0; - else if (volume > 400) - volume = 400; - return m_parameter ? m_parameter->setInt("che.audio.record.signal.volume", volume) : -ERR_NOT_INITIALIZED; - } - - int adjustPlaybackSignalVolume(int volume) { //[0, 400] - if (volume < 0) - volume = 0; - else if (volume > 400) - volume = 400; - return m_parameter ? m_parameter->setInt("che.audio.playout.signal.volume", volume) : -ERR_NOT_INITIALIZED; - } - - int enableAudioVolumeIndication(int interval, int smooth, bool report_vad) { // in ms: <= 0: disable, > 0: enable, interval in ms - if (interval < 0) interval = 0; - return setObject("che.audio.volume_indication", "{\"interval\":%d,\"smooth\":%d,\"vad\":%d}", interval, smooth, report_vad); - } - - int muteLocalAudioStream(bool mute) { return setParameters("{\"rtc.audio.mute_me\":%s,\"che.audio.mute_me\":%s}", mute ? "true" : "false", mute ? "true" : "false"); } - // mute/unmute all peers. unmute will clear all muted peers specified mutePeer() interface - - int muteRemoteAudioStream(uid_t uid, bool mute) { return setObject("rtc.audio.mute_peer", "{\"uid\":%u,\"mute\":%s}", uid, mute ? "true" : "false"); } - - int muteAllRemoteAudioStreams(bool mute) { return m_parameter ? m_parameter->setBool("rtc.audio.mute_peers", mute) : -ERR_NOT_INITIALIZED; } - - int setVoiceConversionPreset(VOICE_CONVERSION_PRESET preset) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - if (preset == VOICE_CONVERSION_OFF) { - return m_parameter->setInt("che.audio.morph.voice_changer", 0); - } - if (preset == VOICE_CHANGER_NEUTRAL) { - return m_parameter->setInt("che.audio.morph.vocal_changer", 1); - } - if (preset == VOICE_CHANGER_SWEET) { - return m_parameter->setInt("che.audio.morph.vocal_changer", 2); - } - if (preset == VOICE_CHANGER_SOLID) { - return m_parameter->setInt("che.audio.morph.vocal_changer", 3); - } - if (preset == VOICE_CHANGER_BASS) { - return m_parameter->setInt("che.audio.morph.vocal_changer", 4); - } - return -ERR_INVALID_ARGUMENT; - } - - int setDefaultMuteAllRemoteAudioStreams(bool mute) { return m_parameter ? m_parameter->setBool("rtc.audio.set_default_mute_peers", mute) : -ERR_NOT_INITIALIZED; } - - int setExternalAudioSource(bool enabled, int sampleRate, int channels) { - if (enabled) - return setParameters("{\"che.audio.external_capture\":true,\"che.audio.external_capture.push\":true,\"che.audio.set_capture_raw_audio_format\":{\"sampleRate\":%d,\"channelCnt\":%d,\"mode\":%d}}", sampleRate, channels, RAW_AUDIO_FRAME_OP_MODE_TYPE::RAW_AUDIO_FRAME_OP_MODE_READ_WRITE); - else - return setParameters("{\"che.audio.external_capture\":false,\"che.audio.external_capture.push\":false}"); - } - - int setExternalAudioSink(bool enabled, int sampleRate, int channels) { - if (enabled) - return setParameters("{\"che.audio.external_render\":true,\"che.audio.external_render.pull\":true,\"che.audio.set_render_raw_audio_format\":{\"sampleRate\":%d,\"channelCnt\":%d,\"mode\":%d}}", sampleRate, channels, RAW_AUDIO_FRAME_OP_MODE_TYPE::RAW_AUDIO_FRAME_OP_MODE_READ_ONLY); - else - return setParameters("{\"che.audio.external_render\":false,\"che.audio.external_render.pull\":false}"); - } - - int setLogFile(const char* filePath) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; -#if defined(_WIN32) - util::AString path; - if (!m_parameter->convertPath(filePath, path)) - filePath = path->c_str(); - else if (!filePath) - filePath = ""; -#endif - return m_parameter->setString("rtc.log_file", filePath); - } - - int setLogFilter(unsigned int filter) { return m_parameter ? m_parameter->setUInt("rtc.log_filter", filter & LOG_FILTER_MASK) : -ERR_NOT_INITIALIZED; } - - int setLogFileSize(unsigned int fileSizeInKBytes) { return m_parameter ? m_parameter->setUInt("rtc.log_size", fileSizeInKBytes) : -ERR_NOT_INITIALIZED; } - - int setLocalRenderMode(RENDER_MODE_TYPE renderMode) { return setRemoteRenderMode(0, renderMode); } - - int setRemoteRenderMode(uid_t uid, RENDER_MODE_TYPE renderMode) { return setParameters("{\"che.video.render_mode\":[{\"uid\":%u,\"renderMode\":%d}]}", uid, renderMode); } - - int setCameraCapturerConfiguration(const CameraCapturerConfiguration& config) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - if (config.preference == CAPTURER_OUTPUT_PREFERENCE_MANUAL) { - m_parameter->setInt("che.video.capture_width", config.captureWidth); - m_parameter->setInt("che.video.capture_height", config.captureHeight); - } - return m_parameter->setInt("che.video.camera_capture_mode", (int)config.preference); - } - - int enableDualStreamMode(bool enabled) { return setParameters("{\"rtc.dual_stream_mode\":%s,\"che.video.enableLowBitRateStream\":%d}", enabled ? "true" : "false", enabled ? 1 : 0); } - - int setRemoteVideoStreamType(uid_t uid, REMOTE_VIDEO_STREAM_TYPE streamType) { - return setParameters("{\"rtc.video.set_remote_video_stream\":{\"uid\":%u,\"stream\":%d}, \"che.video.setstream\":{\"uid\":%u,\"stream\":%d}}", uid, streamType, uid, streamType); - // return setObject("rtc.video.set_remote_video_stream", "{\"uid\":%u,\"stream\":%d}", uid, streamType); - } - - int setRemoteDefaultVideoStreamType(REMOTE_VIDEO_STREAM_TYPE streamType) { return m_parameter ? m_parameter->setInt("rtc.video.set_remote_default_video_stream_type", streamType) : -ERR_NOT_INITIALIZED; } - - int setRecordingAudioFrameParameters(int sampleRate, int channel, RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall) { return setObject("che.audio.set_capture_raw_audio_format", "{\"sampleRate\":%d,\"channelCnt\":%d,\"mode\":%d,\"samplesPerCall\":%d}", sampleRate, channel, mode, samplesPerCall); } - - int setPlaybackAudioFrameParameters(int sampleRate, int channel, RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall) { return setObject("che.audio.set_render_raw_audio_format", "{\"sampleRate\":%d,\"channelCnt\":%d,\"mode\":%d,\"samplesPerCall\":%d}", sampleRate, channel, mode, samplesPerCall); } - - int setMixedAudioFrameParameters(int sampleRate, int samplesPerCall) { return setObject("che.audio.set_mixed_raw_audio_format", "{\"sampleRate\":%d,\"samplesPerCall\":%d}", sampleRate, samplesPerCall); } - - int enableWebSdkInteroperability(bool enabled) { // enable interoperability with zero-plugin web sdk - return setParameters("{\"rtc.video.web_h264_interop_enable\":%s,\"che.video.web_h264_interop_enable\":%s}", enabled ? "true" : "false", enabled ? "true" : "false"); - } + int enableLocalVideo(bool enabled); + int muteLocalVideoStream(bool mute); + int muteAllRemoteVideoStreams(bool mute); + int setDefaultMuteAllRemoteVideoStreams(bool mute); + int muteRemoteVideoStream(uid_t uid, bool mute); + int setPlaybackDeviceVolume(int volume /* [0,255] */); + int startAudioRecording(const char* filePath, AUDIO_RECORDING_QUALITY_TYPE quality); + int startAudioRecording(const char* filePath, int sampleRate, AUDIO_RECORDING_QUALITY_TYPE quality); + int stopAudioRecording(); + int startAudioMixing(const char* filePath, bool loopback, bool replace, int cycle, int startPos = 0); + int stopAudioMixing(); + int pauseAudioMixing(); + int resumeAudioMixing(); + int adjustAudioMixingVolume(int volume); + int adjustAudioMixingPlayoutVolume(int volume); + int getAudioMixingPlayoutVolume(); + int adjustAudioMixingPublishVolume(int volume); + int getAudioMixingPublishVolume(); + int getAudioMixingDuration(); + int getAudioMixingCurrentPosition(); + int setAudioMixingPosition(int pos /*in ms*/); + int setAudioMixingPitch(int pitch); + int getEffectsVolume(); + int setEffectsVolume(int volume); + int setVolumeOfEffect(int soundId, int volume); + int playEffect(int soundId, const char* filePath, int loopCount, double pitch, double pan, int gain, bool publish = false); + int stopEffect(int soundId); + int stopAllEffects(); + int preloadEffect(int soundId, char* filePath); + int unloadEffect(int soundId); + int pauseEffect(int soundId); + int pauseAllEffects(); + int resumeEffect(int soundId); + int resumeAllEffects(); + int enableSoundPositionIndication(bool enabled); + int setRemoteVoicePosition(uid_t uid, double pan, double gain); + int setLocalVoicePitch(double pitch); + int setLocalVoiceEqualization(AUDIO_EQUALIZATION_BAND_FREQUENCY bandFrequency, int bandGain); + int setLocalVoiceReverb(AUDIO_REVERB_TYPE reverbKey, int value); + int setLocalVoiceChanger(VOICE_CHANGER_PRESET voiceChanger); + int setLocalVoiceReverbPreset(AUDIO_REVERB_PRESET reverbPreset); + int setAudioEffectPreset(AUDIO_EFFECT_PRESET preset); + int setVoiceBeautifierPreset(VOICE_BEAUTIFIER_PRESET preset); + int setAudioEffectParameters(AUDIO_EFFECT_PRESET preset, int param1, int param2); + int setVoiceBeautifierParameters(VOICE_BEAUTIFIER_PRESET preset, int param1, int param2); + int pauseAudio(); + int resumeAudio(); + int setHighQualityAudioParameters(bool fullband, bool stereo, bool fullBitrate); + int adjustRecordingSignalVolume(int volume /* [0, 400]: e.g. 50~0.5x 100~1x 400~4x */); + int adjustPlaybackSignalVolume(int volume /* [0, 400] */); + int enableAudioVolumeIndication(int interval, int smooth, bool report_vad); // in ms: <= 0: disable, > 0: enable, interval in ms + int muteLocalAudioStream(bool mute); + int muteRemoteAudioStream(uid_t uid, bool mute); + int muteAllRemoteAudioStreams(bool mute); + int setVoiceConversionPreset(VOICE_CONVERSION_PRESET preset); + int setDefaultMuteAllRemoteAudioStreams(bool mute); + int setExternalAudioSource(bool enabled, int sampleRate, int channels); + int setExternalAudioSink(bool enabled, int sampleRate, int channels); + int setLogFile(const char* filePath); + int setLogFilter(unsigned int filter); + int setLogFileSize(unsigned int fileSizeInKBytes); + int setLocalRenderMode(RENDER_MODE_TYPE renderMode); + int setRemoteRenderMode(uid_t uid, RENDER_MODE_TYPE renderMode); + int setCameraCapturerConfiguration(const CameraCapturerConfiguration& config); + int enableDualStreamMode(bool enabled); + int setRemoteVideoStreamType(uid_t uid, REMOTE_VIDEO_STREAM_TYPE streamType); + int setRemoteDefaultVideoStreamType(REMOTE_VIDEO_STREAM_TYPE streamType); + int setRecordingAudioFrameParameters(int sampleRate, int channel, RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall); + int setPlaybackAudioFrameParameters(int sampleRate, int channel, RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall); + int setMixedAudioFrameParameters(int sampleRate, int samplesPerCall); + int enableWebSdkInteroperability(bool enabled); // only for live broadcast - - int setVideoQualityParameters(bool preferFrameRateOverImageQuality) { return setParameters("{\"rtc.video.prefer_frame_rate\":%s,\"che.video.prefer_frame_rate\":%s}", preferFrameRateOverImageQuality ? "true" : "false", preferFrameRateOverImageQuality ? "true" : "false"); } - - int setLocalVideoMirrorMode(VIDEO_MIRROR_MODE_TYPE mirrorMode) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - const char* value; - switch (mirrorMode) { - case VIDEO_MIRROR_MODE_AUTO: - value = "default"; - break; - case VIDEO_MIRROR_MODE_ENABLED: - value = "forceMirror"; - break; - case VIDEO_MIRROR_MODE_DISABLED: - value = "disableMirror"; - break; - default: - return -ERR_INVALID_ARGUMENT; - } - return m_parameter->setString("che.video.localViewMirrorSetting", value); - } - - int setLocalPublishFallbackOption(STREAM_FALLBACK_OPTIONS option) { return m_parameter ? m_parameter->setInt("rtc.local_publish_fallback_option", option) : -ERR_NOT_INITIALIZED; } - - int setRemoteSubscribeFallbackOption(STREAM_FALLBACK_OPTIONS option) { return m_parameter ? m_parameter->setInt("rtc.remote_subscribe_fallback_option", option) : -ERR_NOT_INITIALIZED; } - + int setVideoQualityParameters(bool preferFrameRateOverImageQuality); + int setLocalVideoMirrorMode(VIDEO_MIRROR_MODE_TYPE mirrorMode); + int setLocalPublishFallbackOption(STREAM_FALLBACK_OPTIONS option); + int setRemoteSubscribeFallbackOption(STREAM_FALLBACK_OPTIONS option); #if (defined(__APPLE__) && TARGET_OS_MAC && !TARGET_OS_IPHONE) || defined(_WIN32) - - int enableLoopbackRecording(bool enabled, const char* deviceName = NULL) { - if (!deviceName) { - return setParameters("{\"che.audio.loopback.recording\":%s}", enabled ? "true" : "false"); - } else { - return setParameters("{\"che.audio.loopback.deviceName\":\"%s\",\"che.audio.loopback.recording\":%s}", deviceName, enabled ? "true" : "false"); - } - } + int enableLoopbackRecording(bool enabled, const char* deviceName = NULL); #endif - - int setInEarMonitoringVolume(int volume) { return m_parameter ? m_parameter->setInt("che.audio.headset.monitoring.parameter", volume) : -ERR_NOT_INITIALIZED; } + int setInEarMonitoringVolume(int volume); protected: AParameter& parameter() { return m_parameter; } @@ -9547,11 +10928,275 @@ class RtcEngineParameters { va_end(args); return m_parameter ? m_parameter->setObject(key, buf) : -ERR_NOT_INITIALIZED; } - int stopAllRemoteVideo() { return m_parameter ? m_parameter->setBool("che.video.peer.stop_render", true) : -ERR_NOT_INITIALIZED; } private: AParameter m_parameter; }; +/** + * The format of the recording file. + * + * @since v3.5.2 + */ +enum MediaRecorderContainerFormat { + /** + * 1: (Default) MP4. + */ + FORMAT_MP4 = 1, + /** + * Reserved parameter. + */ + FORMAT_FLV = 2, +}; +/** + * The recording content. + * + * @since v3.5.2 + */ +enum MediaRecorderStreamType { + /** + * Only audio. + */ + STREAM_TYPE_AUDIO = 0x01, + /** + * Only video. + */ + STREAM_TYPE_VIDEO = 0x02, + /** + * (Default) Audio and video. + */ + STREAM_TYPE_BOTH = STREAM_TYPE_AUDIO | STREAM_TYPE_VIDEO, +}; +/** + * The current recording state. + * + * @since v3.5.2 + */ +enum RecorderState { + /** + * -1: An error occurs during the recording. See RecorderErrorCode for the reason. + */ + RECORDER_STATE_ERROR = -1, + /** + * 2: The audio and video recording is started. + */ + RECORDER_STATE_START = 2, + /** + * 3: The audio and video recording is stopped. + */ + RECORDER_STATE_STOP = 3, +}; +/** + * The reason for the state change + * + * @since v3.5.2 + */ +enum RecorderErrorCode { + /** + * 0: No error occurs. + */ + RECORDER_ERROR_NONE = 0, + /** + * 1: The SDK fails to write the recorded data to a file. + */ + RECORDER_ERROR_WRITE_FAILED = 1, + /** + * 2: The SDK does not detect audio and video streams to be recorded, or audio and video streams are interrupted for more than five seconds during recording. + */ + RECORDER_ERROR_NO_STREAM = 2, + /** + * 3: The recording duration exceeds the upper limit. + */ + RECORDER_ERROR_OVER_MAX_DURATION = 3, + /** + * 4: The recording configuration changes. + */ + RECORDER_ERROR_CONFIG_CHANGED = 4, + /** + * 5: The SDK detects audio and video streams from users using versions of the SDK earlier than v3.0.0 in + * the `COMMUNICATION` channel profile. + */ + RECORDER_ERROR_CUSTOM_STREAM_DETECTED = 5, +}; +/** + * Configurations for the local audio and video recording. + * + * @since v3.5.2 + */ +struct MediaRecorderConfiguration { + /** + * The absolute path (including the filename extensions) of the recording file. + * For example, `C:\Users\\AppData\Local\Agora\\example.mp4` on Windows, + * `/App Sandbox/Library/Caches/example.mp4` on iOS, `/Library/Logs/example.mp4` on macOS, and + * `/storage/emulated/0/Android/data//files/example.mp4` on Android. + * + * @note Ensure that the specified path exists and is writable. + */ + const char* storagePath; + /** + * The format of the recording file. See \ref agora::rtc::MediaRecorderContainerFormat "MediaRecorderContainerFormat". + */ + MediaRecorderContainerFormat containerFormat; + /** + * The recording content. See \ref agora::rtc::MediaRecorderStreamType "MediaRecorderStreamType". + */ + MediaRecorderStreamType streamType; + /** + * The maximum recording duration, in milliseconds. The default value is 120000. + */ + int maxDurationMs; + /** + * The interval (ms) of updating the recording information. The value range is + * [1000,10000]. Based on the set value of `recorderInfoUpdateInterval`, the + * SDK triggers the \ref IMediaRecorderObserver::onRecorderInfoUpdated "onRecorderInfoUpdated" + * callback to report the updated recording information. + */ + int recorderInfoUpdateInterval; + + MediaRecorderConfiguration() : storagePath(nullptr), containerFormat(FORMAT_MP4), streamType(STREAM_TYPE_BOTH), maxDurationMs(120000), recorderInfoUpdateInterval(0) {} + MediaRecorderConfiguration(const char* path, MediaRecorderContainerFormat format, MediaRecorderStreamType type, int duration, int interval) : storagePath(path), containerFormat(format), streamType(type), maxDurationMs(duration), recorderInfoUpdateInterval(interval) {} +}; +/** + * Information for the recording file. + * + * @since v3.5.2 + */ +struct RecorderInfo { + /** + * The absolute path of the recording file. + */ + const char* fileName; + /** + * The recording duration, in milliseconds. + */ + unsigned int durationMs; + /** + * The size in bytes of the recording file. + */ + unsigned int fileSize; + + RecorderInfo() = default; + RecorderInfo(const char* name, unsigned int dur, unsigned int size) : fileName(name), durationMs(dur), fileSize(size) {} +}; + +/** + * The IMediaRecorderObserver class. + * + * @since v3.5.2 + */ +class IMediaRecorderObserver { + public: + /** + * Occurs when the recording state changes. + * + * @since v3.5.2 + * + * When the local audio and video recording state changes, the SDK triggers this callback to report the current + * recording state and the reason for the change. + * + * @param state The current recording state. See \ref agora::rtc::RecorderState "RecorderState". + * @param error The reason for the state change. See \ref agora::rtc::RecorderErrorCode "RecorderErrorCode". + */ + virtual void onRecorderStateChanged(RecorderState state, RecorderErrorCode error) = 0; + /** + * Occurs when the recording information is updated. + * + * @since v3.5.2 + * + * After you successfully register this callback and enable the local audio and video recording, the SDK periodically triggers + * the `onRecorderInfoUpdated` callback based on the set value of `recorderInfoUpdateInterval`. This callback reports the + * filename, duration, and size of the current recording file. + * + * @param info Information for the recording file. See RecorderInfo. + * + */ + virtual void onRecorderInfoUpdated(const RecorderInfo& info){}; +}; +/** + * The IMediaRecorder class, for recording the audio and video on the client. IMediaRecorder can record the + * following content: + * - The audio captured by the local microphone and encoded in AAC format. + * - The video captured by the local camera and encoded by the SDK. + * + * @since v3.5.2 + * + * @note In the `COMMUNICATION` channel profile, this function is unavailable when there are users using versions of + * the SDK earlier than v3.0.0 in the channel. + */ +class IMediaRecorder { + public: + /** + * Gets the IMediaRecorder object. + * + * @since v3.5.2 + * + * @note Call this method after initializing the IRtcEngine object. + * + * @param engine IRtcEngine + * @param callback IMediaRecorderObserver + * + * @return IMediaRecorder + */ + AGORA_CPP_API static IMediaRecorder* getMediaRecorder(IRtcEngine* engine, IMediaRecorderObserver* callback); + /** + * Starts recording the local audio and video. + * + * @since v3.5.2 + * + * After successfully getting the object, you can call this method to enable the recording of the local audio and video. + * + * This method can record the following content: + * - The audio captured by the local microphone and encoded in AAC format. + * - The video captured by the local camera and encoded by the SDK. + * + * The SDK can generate a recording file only when it detects the recordable audio and video streams; when there are + * no audio and video streams to be recorded or the audio and video streams are interrupted for more than five + * seconds, the SDK stops recording and triggers the + * \ref IMediaRecorderObserver::onRecorderStateChanged "onRecorderStateChanged" (RECORDER_STATE_ERROR, RECORDER_ERROR_NO_STREAM) + * callback. + * + * @note Call this method after joining the channel. + * + * @param config The recording configurations. See MediaRecorderConfiguration. + * + * @return + * - 0(ERR_OK): Success. + * - < 0: Failure: + * - `-2(ERR_INVALID_ARGUMENT)`: The parameter is invalid. Ensure the following: + * - The specified path of the recording file exists and is writable. + * - The specified format of the recording file is supported. + * - The maximum recording duration is correctly set. + * - `-4(ERR_NOT_SUPPORTED)`: IRtcEngine does not support the request due to one of the following reasons: + * - The recording is ongoing. + * - The recording stops because an error occurs. + * - `-7(ERR_NOT_INITIALIZED)`: This method is called before the initialization of IRtcEngine. Ensure that you have + * called \ref IMediaRecorder::getMediaRecorder "getMediaRecorder" before calling `startRecording`. + */ + virtual int startRecording(const MediaRecorderConfiguration& config) = 0; + /** + * Stops recording the local audio and video. + * + * @since v3.5.2 + * + * @note Call this method after calling \ref IMediaRecorder::startRecording "startRecording". + * + * @return + * - 0(ERR_OK): Success. + * - < 0: Failure: + * - `-7(ERR_NOT_INITIALIZED)`: This method is called before the initialization of IRtcEngine. Ensure that you have + * called \ref IMediaRecorder::getMediaRecorder "getMediaRecorder" before calling `stopRecording`. + */ + virtual int stopRecording() = 0; + /** + * Releases the IMediaRecorder object. + * + * @since v3.5.2 + * + * This method releases the IRtcEngine object and all other resources used by the IMediaRecorder object. After calling + * this method, if you want to enable the recording again, you must call + * \ref IMediaRecorder::getMediaRecorder "getMediaRecorder" to get the IMediaRecorder object. + */ + virtual void releaseRecorder() = 0; +}; } // namespace rtc } // namespace agora diff --git a/Android/APIExample/lib-player-helper/src/main/cpp/include/IAgoraService.h b/Android/APIExample/lib-player-helper/src/main/cpp/include/IAgoraService.h index 61420d53f..555ed8866 100644 --- a/Android/APIExample/lib-player-helper/src/main/cpp/include/IAgoraService.h +++ b/Android/APIExample/lib-player-helper/src/main/cpp/include/IAgoraService.h @@ -34,7 +34,7 @@ class IAgoraService { */ virtual int initialize(const AgoraServiceContext& context) = 0; - /** Retrieves the SDK version number. + /** Gets the SDK version number. * @param build Build number. * @return The current SDK version in the string format. For example, 2.4.0 */ From 95a06857d05387020bc6f7a4e402ec3e2c8093bd Mon Sep 17 00:00:00 2001 From: xianing Date: Tue, 11 Jan 2022 13:36:13 +0800 Subject: [PATCH 03/21] fix android readme --- Android/APIExample/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Android/APIExample/README.md b/Android/APIExample/README.md index c87e7e2d6..58bd1cbce 100644 --- a/Android/APIExample/README.md +++ b/Android/APIExample/README.md @@ -55,7 +55,7 @@ The project uses a single app to combine a variety of functionalities. Each func 1. In Android Studio, open `/Android/APIExample`. 2. Sync the project with Gradle files. -3. Edit the `/Android/APIExample/app/src/main/res/values/string_config.xml` file. +3. Edit the `/Android/APIExample/app/src/main/res/values/string_configs.xml` file. - Replace `YOUR APP ID` with your App ID. - Replace `YOUR ACCESS TOKEN` with the Access Token. From 681746e538f3b430f4529852e911caa728528c2d Mon Sep 17 00:00:00 2001 From: xianing Date: Tue, 18 Jan 2022 13:13:55 +0800 Subject: [PATCH 04/21] fix ios mpk issues --- Android/APIExample/app/build.gradle | 2 +- .../io/agora/api/example/ExampleActivity.java | 4 + .../example/examples/advanced/FaceBeauty.java | 53 ++- .../examples/advanced/ScreenShare.java | 434 ++++++++++++++++++ .../main/res/layout/fragment_screen_share.xml | 82 ++++ .../res/layout/fragment_video_enhancement.xml | 87 ++++ .../app/src/main/res/navigation/nav_graph.xml | 8 + .../app/src/main/res/values-zh/strings.xml | 3 + .../app/src/main/res/values/colors.xml | 1 + .../app/src/main/res/values/strings.xml | 3 + Android/APIExample/lib-component/build.gradle | 6 +- .../lib-push-externalvideo/build.gradle | 2 +- Android/APIExample/lib-raw-data/build.gradle | 2 +- .../APIExample/lib-screensharing/build.gradle | 2 +- .../lib-stream-encrypt/build.gradle | 2 +- .../lib-switch-external-video/build.gradle | 2 +- 16 files changed, 681 insertions(+), 12 deletions(-) create mode 100644 Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/ScreenShare.java create mode 100644 Android/APIExample/app/src/main/res/layout/fragment_screen_share.xml diff --git a/Android/APIExample/app/build.gradle b/Android/APIExample/app/build.gradle index 6ee743196..5dbeb0161 100644 --- a/Android/APIExample/app/build.gradle +++ b/Android/APIExample/app/build.gradle @@ -7,7 +7,7 @@ android { defaultConfig { applicationId "io.agora.api.example" - minSdkVersion 19 + minSdkVersion 21 targetSdkVersion 29 versionCode 1 versionName "1.0" diff --git a/Android/APIExample/app/src/main/java/io/agora/api/example/ExampleActivity.java b/Android/APIExample/app/src/main/java/io/agora/api/example/ExampleActivity.java index 3d4907049..fa5cc0e30 100644 --- a/Android/APIExample/app/src/main/java/io/agora/api/example/ExampleActivity.java +++ b/Android/APIExample/app/src/main/java/io/agora/api/example/ExampleActivity.java @@ -27,6 +27,7 @@ import io.agora.api.example.examples.advanced.ProcessAudioRawData; import io.agora.api.example.examples.advanced.ProcessRawData; import io.agora.api.example.examples.advanced.PushExternalVideo; +import io.agora.api.example.examples.advanced.ScreenShare; import io.agora.api.example.examples.advanced.SendDataStream; import io.agora.api.example.examples.advanced.SetVideoProfile; import io.agora.api.example.examples.advanced.SuperResolution; @@ -162,6 +163,9 @@ protected void onCreate(@Nullable Bundle savedInstanceState) { case R.id.action_mainFragment_video_enhancement: fragment = new FaceBeauty(); break; + case R.id.action_mainFragment_to_screen_share: + fragment = new ScreenShare(); + break; default: fragment = new JoinChannelAudio(); break; diff --git a/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/FaceBeauty.java b/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/FaceBeauty.java index 302ea8775..29111fced 100644 --- a/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/FaceBeauty.java +++ b/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/FaceBeauty.java @@ -22,6 +22,8 @@ import com.yanzhenjie.permission.AndPermission; import com.yanzhenjie.permission.runtime.Permission; +import org.json.JSONException; + import io.agora.api.example.MainApplication; import io.agora.api.example.R; import io.agora.api.example.annotation.Example; @@ -32,8 +34,12 @@ import io.agora.rtc.RtcEngineConfig; import io.agora.rtc.models.ChannelMediaOptions; import io.agora.rtc.video.BeautyOptions; +import io.agora.rtc.video.ColorEnhanceOptions; +import io.agora.rtc.video.LowLightEnhanceOptions; import io.agora.rtc.video.VideoCanvas; +import io.agora.rtc.video.VideoDenoiserOptions; import io.agora.rtc.video.VideoEncoderConfiguration; +import io.agora.rtc.video.VirtualBackgroundSource; import static io.agora.api.example.common.model.Examples.ADVANCED; import static io.agora.rtc.Constants.CHANNEL_PROFILE_LIVE_BROADCASTING; @@ -56,13 +62,19 @@ public class FaceBeauty extends BaseFragment implements View.OnClickListener, Co private FrameLayout fl_local, fl_remote; private LinearLayout controlPanel; private Button join; - private Switch beauty; - private SeekBar seek_lightness, seek_redness, seek_sharpness, seek_smoothness; + private Switch beauty, lightness, colorful, noiseReduce, virtualBackground; + private SeekBar seek_lightness, seek_redness, seek_sharpness, seek_smoothness, seek_strength, seek_skin; private EditText et_channel; private RtcEngine engine; private int myUid; private boolean joined = false; private BeautyOptions beautyOptions = new BeautyOptions(); + private LowLightEnhanceOptions lowLightEnhanceOptions = new LowLightEnhanceOptions(); + private ColorEnhanceOptions colorEnhanceOptions = new ColorEnhanceOptions(); + private VideoDenoiserOptions videoDenoiserOptions = new VideoDenoiserOptions(); + private VirtualBackgroundSource virtualBackgroundSource = new VirtualBackgroundSource(); + private float skinProtect = 1.0f; + private float strength = 0.5f; @Nullable @Override @@ -84,6 +96,14 @@ public void onViewCreated(@NonNull View view, @Nullable Bundle savedInstanceStat controlPanel = view.findViewById(R.id.controlPanel); beauty = view.findViewById(R.id.switch_face_beautify); beauty.setOnCheckedChangeListener(this); + lightness = view.findViewById(R.id.switch_lightness); + lightness.setOnCheckedChangeListener(this); + colorful = view.findViewById(R.id.switch_color); + colorful.setOnCheckedChangeListener(this); + virtualBackground = view.findViewById(R.id.switch_virtual_background); + virtualBackground.setOnCheckedChangeListener(this); + noiseReduce = view.findViewById(R.id.switch_video_noise_reduce); + noiseReduce.setOnCheckedChangeListener(this); seek_lightness = view.findViewById(R.id.lightening); seek_lightness.setOnSeekBarChangeListener(this); seek_redness = view.findViewById(R.id.redness); @@ -92,6 +112,12 @@ public void onViewCreated(@NonNull View view, @Nullable Bundle savedInstanceStat seek_sharpness.setOnSeekBarChangeListener(this); seek_smoothness = view.findViewById(R.id.smoothness); seek_smoothness.setOnSeekBarChangeListener(this); + seek_strength = view.findViewById(R.id.strength); + seek_strength.setOnSeekBarChangeListener(this); + seek_skin = view.findViewById(R.id.skinProtect); + seek_skin.setOnSeekBarChangeListener(this); + + virtualBackgroundSource.blur_degree = 2; } @Override @@ -274,9 +300,22 @@ public void onCheckedChanged(CompoundButton buttonView, boolean isChecked) { if(buttonView.getId() == beauty.getId()){ engine.setBeautyEffectOptions(isChecked, beautyOptions); } + else if(buttonView.getId() == lightness.getId()){ + engine.setLowlightEnhanceOptions(isChecked, lowLightEnhanceOptions); + } + else if(buttonView.getId() == colorful.getId()){ + colorEnhanceOptions.skinProtectLevel = skinProtect; + colorEnhanceOptions.strengthLevel = strength; + engine.setColorEnhanceOptions(isChecked, colorEnhanceOptions); + } + else if(buttonView.getId() == noiseReduce.getId()){ + engine.setVideoDenoiserOptions(isChecked, videoDenoiserOptions); + } + else if(buttonView.getId() == virtualBackground.getId()){ + engine.enableVirtualBackground(isChecked, virtualBackgroundSource); + } } - @Override public void onProgressChanged(SeekBar seekBar, int progress, boolean fromUser) { float value = ((float) progress) / 10; @@ -296,6 +335,14 @@ else if(seekBar.getId() == seek_smoothness.getId()){ beautyOptions.smoothnessLevel = value; engine.setBeautyEffectOptions(beauty.isChecked(), beautyOptions); } + else if(seekBar.getId() == seek_strength.getId()) { + colorEnhanceOptions.strengthLevel = value; + engine.setColorEnhanceOptions(colorful.isChecked(), colorEnhanceOptions); + } + else if(seekBar.getId() == seek_skin.getId()) { + colorEnhanceOptions.skinProtectLevel = value; + engine.setColorEnhanceOptions(colorful.isChecked(), colorEnhanceOptions); + } } @Override diff --git a/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/ScreenShare.java b/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/ScreenShare.java new file mode 100644 index 000000000..997f81d3f --- /dev/null +++ b/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/ScreenShare.java @@ -0,0 +1,434 @@ +package io.agora.api.example.examples.advanced; + +import android.content.Context; +import android.os.Bundle; +import android.text.TextUtils; +import android.util.Log; +import android.view.LayoutInflater; +import android.view.SurfaceView; +import android.view.View; +import android.view.ViewGroup; +import android.widget.Button; +import android.widget.EditText; +import android.widget.FrameLayout; +import android.widget.TextView; + +import androidx.annotation.NonNull; +import androidx.annotation.Nullable; + +import com.yanzhenjie.permission.AndPermission; +import com.yanzhenjie.permission.runtime.Permission; + +import io.agora.api.example.MainApplication; +import io.agora.api.example.R; +import io.agora.api.example.annotation.Example; +import io.agora.api.example.common.BaseFragment; +import io.agora.api.example.utils.CommonUtil; +import io.agora.rtc.Constants; +import io.agora.rtc.IRtcEngineEventHandler; +import io.agora.rtc.RtcEngine; +import io.agora.rtc.ScreenCaptureParameters; +import io.agora.rtc.models.ChannelMediaOptions; +import io.agora.rtc.video.VideoCanvas; +import io.agora.rtc.video.VideoEncoderConfiguration; + +import static io.agora.api.example.common.model.Examples.ADVANCED; +import static io.agora.rtc.video.VideoCanvas.RENDER_MODE_HIDDEN; +import static io.agora.rtc.video.VideoEncoderConfiguration.STANDARD_BITRATE; + +@Example( + index = 6, + group = ADVANCED, + name = R.string.item_ScreenShare, + actionId = R.id.action_mainFragment_to_screen_share, + tipsId = R.string.ScreenShare +) +public class ScreenShare extends BaseFragment implements View.OnClickListener { + + private static final String TAG = ScreenShare.class.getSimpleName(); + + private FrameLayout fl_remote; + private Button join; + private EditText et_channel; + private TextView description; + private RtcEngine engine; + private int myUid; + private boolean joined = false; + + @Nullable + @Override + public View onCreateView(@NonNull LayoutInflater inflater, @Nullable ViewGroup container, @Nullable Bundle savedInstanceState) + { + return inflater.inflate(R.layout.fragment_screen_share, container, false); + } + + @Override + public void onViewCreated(@NonNull View view, @Nullable Bundle savedInstanceState) + { + super.onViewCreated(view, savedInstanceState); + join = view.findViewById(R.id.btn_join); + description = view.findViewById(R.id.description); + et_channel = view.findViewById(R.id.et_channel); + view.findViewById(R.id.btn_join).setOnClickListener(this); + fl_remote = view.findViewById(R.id.fl_remote); + } + + @Override + public void onActivityCreated(@Nullable Bundle savedInstanceState) + { + super.onActivityCreated(savedInstanceState); + // Check if the context is valid + Context context = getContext(); + if (context == null) + { + return; + } + try + { + /**Creates an RtcEngine instance. + * @param context The context of Android Activity + * @param appId The App ID issued to you by Agora. See + * How to get the App ID + * @param handler IRtcEngineEventHandler is an abstract class providing default implementation. + * The SDK uses this class to report to the app on SDK runtime events.*/ + engine = RtcEngine.create(context.getApplicationContext(), getString(R.string.agora_app_id), iRtcEngineEventHandler); + } + catch (Exception e) + { + e.printStackTrace(); + getActivity().onBackPressed(); + } + } + + @Override + public void onDestroy() + { + super.onDestroy(); + /**leaveChannel and Destroy the RtcEngine instance*/ + if(engine != null) + { + engine.leaveChannel(); + } + handler.post(RtcEngine::destroy); + engine = null; + } + + @Override + public void onClick(View v) { + + if (v.getId() == R.id.btn_join) + { + if (!joined) + { + CommonUtil.hideInputBoard(getActivity(), et_channel); + // call when join button hit + String channelId = et_channel.getText().toString(); + // Check permission + if (AndPermission.hasPermissions(this, Permission.Group.STORAGE, Permission.Group.MICROPHONE, Permission.Group.CAMERA)) + { + joinChannel(channelId); + return; + } + // Request permission + AndPermission.with(this).runtime().permission( + Permission.Group.STORAGE, + Permission.Group.MICROPHONE, + Permission.Group.CAMERA + ).onGranted(permissions -> + { + // Permissions Granted + joinChannel(channelId); + }).start(); + } + else + { + joined = false; + /**After joining a channel, the user must call the leaveChannel method to end the + * call before joining another channel. This method returns 0 if the user leaves the + * channel and releases all resources related to the call. This method call is + * asynchronous, and the user has not exited the channel when the method call returns. + * Once the user leaves the channel, the SDK triggers the onLeaveChannel callback. + * A successful leaveChannel method call triggers the following callbacks: + * 1:The local client: onLeaveChannel. + * 2:The remote client: onUserOffline, if the user leaving the channel is in the + * Communication channel, or is a BROADCASTER in the Live Broadcast profile. + * @returns 0: Success. + * < 0: Failure. + * PS: + * 1:If you call the destroy method immediately after calling the leaveChannel + * method, the leaveChannel process interrupts, and the SDK does not trigger + * the onLeaveChannel callback. + * 2:If you call the leaveChannel method during CDN live streaming, the SDK + * triggers the removeInjectStreamUrl method.*/ + engine.leaveChannel(); + join.setText(getString(R.string.join)); + } + } + } + + private void joinChannel(String channelId) + { + // Check if the context is valid + Context context = getContext(); + if (context == null) + { + return; + } + + /** Sets the channel profile of the Agora RtcEngine. + CHANNEL_PROFILE_COMMUNICATION(0): (Default) The Communication profile. + Use this profile in one-on-one calls or group calls, where all users can talk freely. + CHANNEL_PROFILE_LIVE_BROADCASTING(1): The Live-Broadcast profile. Users in a live-broadcast + channel have a role as either broadcaster or audience. A broadcaster can both send and receive streams; + an audience can only receive streams.*/ + engine.setChannelProfile(Constants.CHANNEL_PROFILE_LIVE_BROADCASTING); + /**In the demo, the default is to enter as the anchor.*/ + engine.setClientRole(IRtcEngineEventHandler.ClientRole.CLIENT_ROLE_BROADCASTER); + // Enable video module + engine.enableVideo(); + + ScreenCaptureParameters screenCaptureParameters = new ScreenCaptureParameters(); + screenCaptureParameters.captureAudio = true; + screenCaptureParameters.captureVideo = true; + ScreenCaptureParameters.VideoCaptureParameters videoCaptureParameters = new ScreenCaptureParameters.VideoCaptureParameters(); + screenCaptureParameters.videoCaptureParameters = videoCaptureParameters; + engine.startScreenCapture(screenCaptureParameters); + description.setText("Screen Sharing Starting"); + + /**Please configure accessToken in the string_config file. + * A temporary token generated in Console. A temporary token is valid for 24 hours. For details, see + * https://docs.agora.io/en/Agora%20Platform/token?platform=All%20Platforms#get-a-temporary-token + * A token generated at the server. This applies to scenarios with high-security requirements. For details, see + * https://docs.agora.io/en/cloud-recording/token_server_java?platform=Java*/ + String accessToken = getString(R.string.agora_access_token); + if (TextUtils.equals(accessToken, "") || TextUtils.equals(accessToken, "<#YOUR ACCESS TOKEN#>")) + { + accessToken = null; + } + /** Allows a user to join a channel. + if you do not specify the uid, we will generate the uid for you*/ + + ChannelMediaOptions option = new ChannelMediaOptions(); + option.autoSubscribeAudio = true; + option.autoSubscribeVideo = true; + int res = engine.joinChannel(accessToken, channelId, "Extra Optional Data", 0, option); + if (res != 0) + { + // Usually happens with invalid parameters + // Error code description can be found at: + // en: https://docs.agora.io/en/Voice/API%20Reference/java/classio_1_1agora_1_1rtc_1_1_i_rtc_engine_event_handler_1_1_error_code.html + // cn: https://docs.agora.io/cn/Voice/API%20Reference/java/classio_1_1agora_1_1rtc_1_1_i_rtc_engine_event_handler_1_1_error_code.html + showAlert(RtcEngine.getErrorDescription(Math.abs(res))); + return; + } + // Prevent repeated entry + join.setEnabled(false); + } + + /** + * IRtcEngineEventHandler is an abstract class providing default implementation. + * The SDK uses this class to report to the app on SDK runtime events. + */ + private final IRtcEngineEventHandler iRtcEngineEventHandler = new IRtcEngineEventHandler() + { + /**Reports a warning during SDK runtime. + * Warning code: https://docs.agora.io/en/Voice/API%20Reference/java/classio_1_1agora_1_1rtc_1_1_i_rtc_engine_event_handler_1_1_warn_code.html*/ + @Override + public void onWarning(int warn) + { + Log.w(TAG, String.format("onWarning code %d message %s", warn, RtcEngine.getErrorDescription(warn))); + } + + /**Reports an error during SDK runtime. + * Error code: https://docs.agora.io/en/Voice/API%20Reference/java/classio_1_1agora_1_1rtc_1_1_i_rtc_engine_event_handler_1_1_error_code.html*/ + @Override + public void onError(int err) + { + Log.e(TAG, String.format("onError code %d message %s", err, RtcEngine.getErrorDescription(err))); + showAlert(String.format("onError code %d message %s", err, RtcEngine.getErrorDescription(err))); + } + + /**Occurs when a user leaves the channel. + * @param stats With this callback, the application retrieves the channel information, + * such as the call duration and statistics.*/ + @Override + public void onLeaveChannel(RtcStats stats) + { + super.onLeaveChannel(stats); + Log.i(TAG, String.format("local user %d leaveChannel!", myUid)); + showLongToast(String.format("local user %d leaveChannel!", myUid)); + } + + /**Occurs when the local user joins a specified channel. + * The channel name assignment is based on channelName specified in the joinChannel method. + * If the uid is not specified when joinChannel is called, the server automatically assigns a uid. + * @param channel Channel name + * @param uid User ID + * @param elapsed Time elapsed (ms) from the user calling joinChannel until this callback is triggered*/ + @Override + public void onJoinChannelSuccess(String channel, int uid, int elapsed) + { + Log.i(TAG, String.format("onJoinChannelSuccess channel %s uid %d", channel, uid)); + showLongToast(String.format("onJoinChannelSuccess channel %s uid %d", channel, uid)); + myUid = uid; + joined = true; + handler.post(new Runnable() + { + @Override + public void run() + { + join.setEnabled(true); + join.setText(getString(R.string.leave)); + } + }); + } + + @Override + public void onFirstLocalVideoFramePublished(int elapsed) { + description.setText("Screen Sharing started"); + } + + /**Since v2.9.0. + * This callback indicates the state change of the remote audio stream. + * PS: This callback does not work properly when the number of users (in the Communication profile) or + * broadcasters (in the Live-broadcast profile) in the channel exceeds 17. + * @param uid ID of the user whose audio state changes. + * @param state State of the remote audio + * REMOTE_AUDIO_STATE_STOPPED(0): The remote audio is in the default state, probably due + * to REMOTE_AUDIO_REASON_LOCAL_MUTED(3), REMOTE_AUDIO_REASON_REMOTE_MUTED(5), + * or REMOTE_AUDIO_REASON_REMOTE_OFFLINE(7). + * 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, + * probably due to REMOTE_AUDIO_REASON_NETWORK_RECOVERY(2), + * REMOTE_AUDIO_REASON_LOCAL_UNMUTED(4) or REMOTE_AUDIO_REASON_REMOTE_UNMUTED(6). + * REMOTE_AUDIO_STATE_FROZEN(3): The remote audio is frozen, probably due to + * REMOTE_AUDIO_REASON_NETWORK_CONGESTION(1). + * REMOTE_AUDIO_STATE_FAILED(4): The remote audio fails to start, probably due to + * REMOTE_AUDIO_REASON_INTERNAL(0). + * @param reason The reason of the remote audio state change. + * REMOTE_AUDIO_REASON_INTERNAL(0): Internal reasons. + * REMOTE_AUDIO_REASON_NETWORK_CONGESTION(1): Network congestion. + * REMOTE_AUDIO_REASON_NETWORK_RECOVERY(2): Network recovery. + * REMOTE_AUDIO_REASON_LOCAL_MUTED(3): The local user stops receiving the remote audio + * stream or disables the audio module. + * REMOTE_AUDIO_REASON_LOCAL_UNMUTED(4): The local user resumes receiving the remote audio + * stream or enables the audio module. + * REMOTE_AUDIO_REASON_REMOTE_MUTED(5): The remote user stops sending the audio stream or + * disables the audio module. + * REMOTE_AUDIO_REASON_REMOTE_UNMUTED(6): The remote user resumes sending the audio stream + * or enables the audio module. + * REMOTE_AUDIO_REASON_REMOTE_OFFLINE(7): The remote user leaves the channel. + * @param elapsed Time elapsed (ms) from the local user calling the joinChannel method + * until the SDK triggers this callback.*/ + @Override + public void onRemoteAudioStateChanged(int uid, int state, int reason, int elapsed) + { + super.onRemoteAudioStateChanged(uid, state, reason, elapsed); + Log.i(TAG, "onRemoteAudioStateChanged->" + uid + ", state->" + state + ", reason->" + reason); + } + + /**Since v2.9.0. + * Occurs when the remote video state changes. + * PS: This callback does not work properly when the number of users (in the Communication + * profile) or broadcasters (in the Live-broadcast profile) in the channel exceeds 17. + * @param uid ID of the remote user whose video state changes. + * @param state State of the remote video: + * REMOTE_VIDEO_STATE_STOPPED(0): The remote video is in the default state, probably due + * to REMOTE_VIDEO_STATE_REASON_LOCAL_MUTED(3), REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED(5), + * or REMOTE_VIDEO_STATE_REASON_REMOTE_OFFLINE(7). + * 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, + * probably due to REMOTE_VIDEO_STATE_REASON_NETWORK_RECOVERY (2), + * REMOTE_VIDEO_STATE_REASON_LOCAL_UNMUTED(4), REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED(6), + * or REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK_RECOVERY(9). + * REMOTE_VIDEO_STATE_FROZEN(3): The remote video is frozen, probably due to + * REMOTE_VIDEO_STATE_REASON_NETWORK_CONGESTION(1) or REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK(8). + * REMOTE_VIDEO_STATE_FAILED(4): The remote video fails to start, probably due to + * REMOTE_VIDEO_STATE_REASON_INTERNAL(0). + * @param reason The reason of the remote video state change: + * REMOTE_VIDEO_STATE_REASON_INTERNAL(0): Internal reasons. + * 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 media stream falls back to the + * audio-only stream due to poor network conditions. + * REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK_RECOVERY(9): The remote media stream switches + * back to the video stream after the network conditions improve. + * @param elapsed Time elapsed (ms) from the local user calling the joinChannel method until + * the SDK triggers this callback.*/ + @Override + public void onRemoteVideoStateChanged(int uid, int state, int reason, int elapsed) + { + super.onRemoteVideoStateChanged(uid, state, reason, elapsed); + Log.i(TAG, "onRemoteVideoStateChanged->" + uid + ", state->" + state + ", reason->" + reason); + } + + /**Occurs when a remote user (Communication)/host (Live Broadcast) joins the channel. + * @param uid ID of the user whose audio state changes. + * @param elapsed Time delay (ms) from the local user calling joinChannel/setClientRole + * until this callback is triggered.*/ + @Override + public void onUserJoined(int uid, int elapsed) + { + super.onUserJoined(uid, elapsed); + Log.i(TAG, "onUserJoined->" + uid); + showLongToast(String.format("user %d joined!", uid)); + /**Check if the context is correct*/ + Context context = getContext(); + if (context == null) { + return; + } + handler.post(() -> + { + /**Display remote video stream*/ + SurfaceView surfaceView = null; + if (fl_remote.getChildCount() > 0) + { + fl_remote.removeAllViews(); + } + // Create render view by RtcEngine + surfaceView = RtcEngine.CreateRendererView(context); + surfaceView.setZOrderMediaOverlay(true); + // Add to the remote container + fl_remote.addView(surfaceView, new FrameLayout.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT)); + + // Setup remote video to render + engine.setupRemoteVideo(new VideoCanvas(surfaceView, RENDER_MODE_HIDDEN, uid)); + }); + } + + /**Occurs when a remote user (Communication)/host (Live Broadcast) leaves the channel. + * @param uid ID of the user whose audio state changes. + * @param reason Reason why the user goes offline: + * USER_OFFLINE_QUIT(0): The user left the current channel. + * USER_OFFLINE_DROPPED(1): The SDK timed out and the user dropped offline because no data + * packet was received within a certain period of time. If a 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): (Live broadcast only.) The client role switched from + * the host to the audience.*/ + @Override + public void onUserOffline(int uid, int reason) + { + Log.i(TAG, String.format("user %d offline! reason:%d", uid, reason)); + showLongToast(String.format("user %d offline! reason:%d", uid, reason)); + handler.post(new Runnable() { + @Override + public void run() { + /**Clear render view + Note: The video will stay at its last frame, to completely remove it you will need to + remove the SurfaceView from its parent*/ + engine.setupRemoteVideo(new VideoCanvas(null, RENDER_MODE_HIDDEN, uid)); + } + }); + } + }; +} diff --git a/Android/APIExample/app/src/main/res/layout/fragment_screen_share.xml b/Android/APIExample/app/src/main/res/layout/fragment_screen_share.xml new file mode 100644 index 000000000..1143d2246 --- /dev/null +++ b/Android/APIExample/app/src/main/res/layout/fragment_screen_share.xml @@ -0,0 +1,82 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/Android/APIExample/app/src/main/res/layout/fragment_video_enhancement.xml b/Android/APIExample/app/src/main/res/layout/fragment_video_enhancement.xml index 135a9fba3..7fbe38f3c 100644 --- a/Android/APIExample/app/src/main/res/layout/fragment_video_enhancement.xml +++ b/Android/APIExample/app/src/main/res/layout/fragment_video_enhancement.xml @@ -154,6 +154,93 @@ + + + + + + + + + + + + + + + + + + + + + + + diff --git a/Android/APIExample/app/src/main/res/navigation/nav_graph.xml b/Android/APIExample/app/src/main/res/navigation/nav_graph.xml index 2085c0933..09cca0722 100755 --- a/Android/APIExample/app/src/main/res/navigation/nav_graph.xml +++ b/Android/APIExample/app/src/main/res/navigation/nav_graph.xml @@ -92,6 +92,9 @@ + @@ -242,6 +245,11 @@ android:name="io.agora.api.example.examples.advanced.MultiProcess" android:label="TwoProcess" tools:layout="@layout/fragment_two_process_screen_share" /> + 此示例演示了在音频通话过程中如何通过回调获取裸数据的功能。 音频耳返 此示例演示了音频通话过程中SDK内置的各类视频增强功能。 + 此示例演示了音频通话过程中使用SDK提供的手机屏幕共享功能。 混音控制 开始 恢复播放 @@ -178,4 +179,6 @@ 视频降噪 强度 肤色保护 + 屏幕共享 + 虚拟背景 \ No newline at end of file diff --git a/Android/APIExample/app/src/main/res/values/colors.xml b/Android/APIExample/app/src/main/res/values/colors.xml index 030098fe0..e5fc74bc9 100644 --- a/Android/APIExample/app/src/main/res/values/colors.xml +++ b/Android/APIExample/app/src/main/res/values/colors.xml @@ -3,4 +3,5 @@ #6200EE #3700B3 #03DAC5 + #939393 diff --git a/Android/APIExample/app/src/main/res/values/strings.xml b/Android/APIExample/app/src/main/res/values/strings.xml index c7813b111..7a9f60130 100644 --- a/Android/APIExample/app/src/main/res/values/strings.xml +++ b/Android/APIExample/app/src/main/res/values/strings.xml @@ -135,6 +135,7 @@ This example shows how to use RTC Engine to share Artifactial Reality App to remote audience. AR module is based on Google ARCore in this Example. This example shows how to use sendDataStream API to send your custom data along with Video Frame in Channel. This example shows how to register Audio Observer to engine for extract raw audio data during RTC communication + This example shows how to use startScreenCapture API to publish phone screen content during RTC communication Audio Loopback This example shows the features for video enhancement for RTC communication. Audio Mixing Control @@ -182,4 +183,6 @@ Video Denoise Strength Skin Protect + Screen Share + Virtual Background diff --git a/Android/APIExample/lib-component/build.gradle b/Android/APIExample/lib-component/build.gradle index f410b0573..7f133c262 100644 --- a/Android/APIExample/lib-component/build.gradle +++ b/Android/APIExample/lib-component/build.gradle @@ -5,7 +5,7 @@ android { buildToolsVersion "29.0.3" defaultConfig { - minSdkVersion 19 + minSdkVersion 21 targetSdkVersion 29 versionCode 1 versionName "1.0" @@ -23,14 +23,14 @@ android { } dependencies { - api fileTree(dir: 'libs', include: ['*.jar']) + api fileTree(dir: 'libs', include: ['*.jar','*.aar']) implementation 'androidx.appcompat:appcompat:1.1.0' testImplementation 'junit:junit:4.12' androidTestImplementation 'androidx.test.ext:junit:1.1.1' androidTestImplementation 'androidx.test.espresso:espresso-core:3.2.0' - api 'io.agora.rtc:full-sdk:3.6.0.1' + api 'io.agora.rtc:full-sdk:3.6.2' api 'io.agora:player:1.3.0' } diff --git a/Android/APIExample/lib-push-externalvideo/build.gradle b/Android/APIExample/lib-push-externalvideo/build.gradle index 0580f8882..f6c630945 100644 --- a/Android/APIExample/lib-push-externalvideo/build.gradle +++ b/Android/APIExample/lib-push-externalvideo/build.gradle @@ -5,7 +5,7 @@ android { buildToolsVersion "29.0.3" defaultConfig { - minSdkVersion 19 + minSdkVersion 21 targetSdkVersion 29 versionCode 1 versionName "1.0" diff --git a/Android/APIExample/lib-raw-data/build.gradle b/Android/APIExample/lib-raw-data/build.gradle index e04fd9311..0dd78834c 100644 --- a/Android/APIExample/lib-raw-data/build.gradle +++ b/Android/APIExample/lib-raw-data/build.gradle @@ -5,7 +5,7 @@ android { buildToolsVersion "29.0.2" defaultConfig { - minSdkVersion 19 + minSdkVersion 21 targetSdkVersion 29 versionCode 1 versionName "1.0" diff --git a/Android/APIExample/lib-screensharing/build.gradle b/Android/APIExample/lib-screensharing/build.gradle index 5f7ffb803..d64cd28c5 100644 --- a/Android/APIExample/lib-screensharing/build.gradle +++ b/Android/APIExample/lib-screensharing/build.gradle @@ -5,7 +5,7 @@ android { buildToolsVersion "29.0.2" defaultConfig { - minSdkVersion 19 + minSdkVersion 21 targetSdkVersion 29 versionCode 1 versionName "1.0" diff --git a/Android/APIExample/lib-stream-encrypt/build.gradle b/Android/APIExample/lib-stream-encrypt/build.gradle index df5ab811e..2ae9d5223 100644 --- a/Android/APIExample/lib-stream-encrypt/build.gradle +++ b/Android/APIExample/lib-stream-encrypt/build.gradle @@ -5,7 +5,7 @@ android { buildToolsVersion "29.0.3" defaultConfig { - minSdkVersion 19 + minSdkVersion 21 targetSdkVersion 29 versionCode 1 versionName "1.0" diff --git a/Android/APIExample/lib-switch-external-video/build.gradle b/Android/APIExample/lib-switch-external-video/build.gradle index d5db48e45..b46e70a88 100644 --- a/Android/APIExample/lib-switch-external-video/build.gradle +++ b/Android/APIExample/lib-switch-external-video/build.gradle @@ -6,7 +6,7 @@ android { defaultConfig { - minSdkVersion 19 + minSdkVersion 21 targetSdkVersion 29 versionCode 1 versionName "1.0" From ed5ccc1dfa01e1d92e1a02eb811c6ab197cbeddd Mon Sep 17 00:00:00 2001 From: Arlin Date: Wed, 19 Jan 2022 12:44:39 +0800 Subject: [PATCH 05/21] add feature video enhancement and virtual background base on v3.6.2 --- .../Base.lproj/VideoProcess.storyboard | 280 +++++++++++++++--- .../Advanced/VideoProcess/VideoProcess.swift | 111 +++++-- .../zh-Hans.lproj/VideoProcess.strings | 56 ++-- 3 files changed, 345 insertions(+), 102 deletions(-) diff --git a/iOS/APIExample/Examples/Advanced/VideoProcess/Base.lproj/VideoProcess.storyboard b/iOS/APIExample/Examples/Advanced/VideoProcess/Base.lproj/VideoProcess.storyboard index 7575139b5..128a68f9a 100644 --- a/iOS/APIExample/Examples/Advanced/VideoProcess/Base.lproj/VideoProcess.storyboard +++ b/iOS/APIExample/Examples/Advanced/VideoProcess/Base.lproj/VideoProcess.storyboard @@ -1,9 +1,9 @@ - + - + @@ -72,7 +72,6 @@ - @@ -95,25 +94,28 @@ - + - + @@ -121,14 +123,8 @@ - - + @@ -137,13 +133,13 @@ - + @@ -152,13 +148,13 @@ - + @@ -166,42 +162,246 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - + + + + + + + - + + + - - - - - - + + + + + + + + + + + + + + - - - - - + + + + + + + - - - + + + + + - + + - - - - + + diff --git a/iOS/APIExample/Examples/Advanced/VideoProcess/VideoProcess.swift b/iOS/APIExample/Examples/Advanced/VideoProcess/VideoProcess.swift index 6ceea24c7..e1d8cb302 100644 --- a/iOS/APIExample/Examples/Advanced/VideoProcess/VideoProcess.swift +++ b/iOS/APIExample/Examples/Advanced/VideoProcess/VideoProcess.swift @@ -12,9 +12,7 @@ import AGEVideoLayout class VideoProcessEntry : UIViewController { - @IBOutlet weak var joinButton: AGButton! @IBOutlet weak var channelTextField: AGTextField! - let identifier = "VideoProcess" override func viewDidLoad() { super.viewDidLoad() @@ -22,11 +20,10 @@ class VideoProcessEntry : UIViewController @IBAction func doJoinPressed(sender: AGButton) { guard let channelName = channelTextField.text else {return} - //resign channel text field channelTextField.resignFirstResponder() + let identifier = "VideoProcess" let storyBoard: UIStoryboard = UIStoryboard(name: identifier, bundle: nil) - // create new view controller every time to ensure we get a clean vc guard let newViewController = storyBoard.instantiateViewController(withIdentifier: identifier) as? BaseViewController else {return} newViewController.title = channelName newViewController.configs = ["channelName":channelName] @@ -34,30 +31,24 @@ class VideoProcessEntry : UIViewController } } + class VideoProcessMain : BaseViewController { - var localVideo = Bundle.loadVideoView(type: .local, audioOnly: false) - var remoteVideo = Bundle.loadVideoView(type: .remote, audioOnly: false) - @IBOutlet weak var container: AGEVideoContainer! - var agoraKit: AgoraRtcEngineKit! - - @IBOutlet weak var beauty: UISwitch! - @IBOutlet weak var lightness: UISwitch! - @IBOutlet weak var colorful: UISwitch! - @IBOutlet weak var denoiser: UISwitch! + @IBOutlet weak var beautySwitch: UISwitch! + @IBOutlet weak var colorEnhanceSwitch: UISwitch! + @IBOutlet weak var virtualBgSwitch: UISwitch! + @IBOutlet weak var virtualBgSegment: UISegmentedControl! - @IBOutlet weak var lightenSlider: UISlider! - @IBOutlet weak var rednessSlider: UISlider! - @IBOutlet weak var sharpnessSlider: UISlider! - @IBOutlet weak var smoothSlider: UISlider! + var agoraKit: AgoraRtcEngineKit! + var localVideo = Bundle.loadVideoView(type: .local, audioOnly: false) + var remoteVideo = Bundle.loadVideoView(type: .remote, audioOnly: false) // indicate if current instance has joined channel var isJoined: Bool = false var beautifyOption = AgoraBeautyOptions() - var skinProtect = 1.0 - var strength = 0.5 - + var colorEnhanceOption = AgoraColorEnhanceOptions() + override func viewDidLoad(){ super.viewDidLoad() // layout render view @@ -74,7 +65,7 @@ class VideoProcessMain : BaseViewController let logConfig = AgoraLogConfig() logConfig.level = .info config.logConfig = logConfig - + agoraKit = AgoraRtcEngineKit.sharedEngine(with: config, delegate: self) // get channel name from configs @@ -82,7 +73,7 @@ class VideoProcessMain : BaseViewController let resolution = GlobalSettings.shared.getSetting(key: "resolution")?.selectedOption().value as? CGSize, let fps = GlobalSettings.shared.getSetting(key: "fps")?.selectedOption().value as? AgoraVideoFrameRate, let orientation = GlobalSettings.shared.getSetting(key: "orientation")?.selectedOption().value as? AgoraVideoOutputOrientationMode else {return} - + // make myself a broadcaster agoraKit.setChannelProfile(.liveBroadcasting) agoraKit.setClientRole(.broadcaster) @@ -90,10 +81,10 @@ class VideoProcessMain : BaseViewController // enable video module and set up video encoding configs agoraKit.enableVideo() agoraKit.setVideoEncoderConfiguration(AgoraVideoEncoderConfiguration(size: resolution, - frameRate: fps, - bitrate: AgoraVideoBitrateStandard, - orientationMode: orientation)) - + frameRate: fps, + bitrate: AgoraVideoBitrateStandard, + orientationMode: orientation)) + // set up local video to render your local camera preview let videoCanvas = AgoraRtcVideoCanvas() videoCanvas.uid = 0 @@ -133,24 +124,80 @@ class VideoProcessMain : BaseViewController } } + @IBAction func onChangeBeauty(_ sender:UISwitch){ + agoraKit.setBeautyEffectOptions(sender.isOn, options: beautifyOption) + } + @IBAction func onLightenSlider(_ sender:UISlider){ beautifyOption.lighteningLevel = sender.value - agoraKit.setBeautyEffectOptions(beauty.isOn, options: beautifyOption) + agoraKit.setBeautyEffectOptions(beautySwitch.isOn, options: beautifyOption) } + @IBAction func onRednessSlider(_ sender:UISlider){ beautifyOption.rednessLevel = sender.value - agoraKit.setBeautyEffectOptions(beauty.isOn, options: beautifyOption) + agoraKit.setBeautyEffectOptions(beautySwitch.isOn, options: beautifyOption) } + @IBAction func onSharpnessSlider(_ sender:UISlider){ beautifyOption.sharpnessLevel = sender.value - agoraKit.setBeautyEffectOptions(beauty.isOn, options: beautifyOption) + agoraKit.setBeautyEffectOptions(beautySwitch.isOn, options: beautifyOption) } + @IBAction func onSmoothSlider(_ sender:UISlider){ beautifyOption.smoothnessLevel = sender.value - agoraKit.setBeautyEffectOptions(beauty.isOn, options: beautifyOption) + agoraKit.setBeautyEffectOptions(beautySwitch.isOn, options: beautifyOption) } - @IBAction func onChangeBeauty(_ sender:UISwitch){ - agoraKit.setBeautyEffectOptions(sender.isOn, options: beautifyOption) + + @IBAction func onChangeLowLightEnhance(_ sender: UISwitch) { + agoraKit.setLowlightEnhanceOptions(sender.isOn, options: nil) + } + + @IBAction func onChangeVideoDenoise(_ sender: UISwitch) { + agoraKit.setVideoDenoiserOptions(sender.isOn, options: nil) + } + + @IBAction func onChangeColorEnhance(_ sender: UISwitch) { + agoraKit.setColorEnhanceOptions(sender.isOn, options: colorEnhanceOption) + } + + @IBAction func onStrengthSlider(_ sender:UISlider){ + colorEnhanceOption.strengthLevel = sender.value; + agoraKit.setColorEnhanceOptions(colorEnhanceSwitch.isOn, options: colorEnhanceOption) + } + + @IBAction func onSkinProtectSlider(_ sender:UISlider){ + colorEnhanceOption.skinProtectLevel = sender.value; + agoraKit.setColorEnhanceOptions(colorEnhanceSwitch.isOn, options: colorEnhanceOption) + } + + @IBAction func onChangeVirtualBgSwtich(_ sender: UISwitch) { + changeVirtualBackground() + } + + @IBAction func onChangeVirtualBgSegment(_ sender: UISegmentedControl) { + changeVirtualBackground() + } + + func changeVirtualBackground() { + let source = AgoraVirtualBackgroundSource() + switch virtualBgSegment.selectedSegmentIndex { + case 0: + let imgPath = Bundle.main.path(forResource: "agora-logo", ofType: "png") + source.backgroundSourceType = .img + source.source = imgPath + break + case 1: + source.backgroundSourceType = .color + source.color = 0xFFFF + break + case 2: + source.backgroundSourceType = .blur + source.blur_degree = .high; + break + default: + break + } + agoraKit.enableVirtualBackground(virtualBgSwitch.isOn, backData: source) } } diff --git a/iOS/APIExample/Examples/Advanced/VideoProcess/zh-Hans.lproj/VideoProcess.strings b/iOS/APIExample/Examples/Advanced/VideoProcess/zh-Hans.lproj/VideoProcess.strings index fc209274c..76621ad69 100644 --- a/iOS/APIExample/Examples/Advanced/VideoProcess/zh-Hans.lproj/VideoProcess.strings +++ b/iOS/APIExample/Examples/Advanced/VideoProcess/zh-Hans.lproj/VideoProcess.strings @@ -1,51 +1,47 @@ - -/* Class = "UISwitch"; title = "Face Beautify"; ObjectID = "0lt-yn-0yl"; */ -"0lt-yn-0yl.title" = "美颜"; +/* Class = "UITextField"; placeholder = "Enter channel name"; ObjectID = "moa-hL-hhA"; */ +"moa-hL-hhA.placeholder" = "请输入频道名"; /* Class = "UIButton"; normalTitle = "Join"; ObjectID = "1Vr-cE-fQI"; */ "1Vr-cE-fQI.normalTitle" = "加入"; -/* Class = "UILabel"; text = "Lightening Enhance"; ObjectID = "2y0-8E-3Er"; */ -"2y0-8E-3Er.text" = "暗光增强"; +/* Class = "UILabel"; text = "Face Beautify"; ObjectID = "Ty6-YP-tus"; */ +"Ty6-YP-tus.text" = "美颜"; /* Class = "UILabel"; text = "Smoothness"; ObjectID = "3Cr-C9-PWm"; */ "3Cr-C9-PWm.text" = "平滑"; -/* Class = "UISwitch"; title = "Face Beautify"; ObjectID = "3jT-PF-fry"; */ -"3jT-PF-fry.title" = "美颜"; - /* Class = "UILabel"; text = "Lightening"; ObjectID = "6Yy-cm-VP3"; */ "6Yy-cm-VP3.text" = "美白"; -/* Class = "UIViewController"; title = "Simple Filter"; ObjectID = "8Zn-pj-gkm"; */ -"8Zn-pj-gkm.title" = "视频增强"; +/* Class = "UILabel"; text = "Redness"; ObjectID = "c7I-oU-1Ty"; */ +"c7I-oU-1Ty.text" = "红润"; -/* Class = "UISwitch"; title = "Face Beautify"; ObjectID = "HJK-u9-Pbi"; */ -"HJK-u9-Pbi.title" = "美颜"; +/* Class = "UILabel"; text = "Sharpness"; ObjectID = "nxu-z3-DfB"; */ +"nxu-z3-DfB.text" = "锐利"; -/* Class = "UILabel"; text = "Video Denoiser"; ObjectID = "IK4-hW-gbx"; */ -"IK4-hW-gbx.text" = "视频降噪"; +/* Class = "UILabel"; text = "Low light Enhancement"; ObjectID = "tw2-gf-2I6"; */ +"tw2-gf-2I6.text" = "暗光增强"; -/* Class = "UILabel"; text = "Colorful Enhance"; ObjectID = "Ijy-ys-cZf"; */ -"Ijy-ys-cZf.text" = "色彩增强"; +/* Class = "UILabel"; text = "Video Denoiser"; ObjectID = "147-rT-JTP"; */ +"147-rT-JTP.text" = "视频降噪"; -/* Class = "UILabel"; text = "Face Beautify"; ObjectID = "Ty6-YP-tus"; */ -"Ty6-YP-tus.text" = "美颜"; +/* Class = "UILabel"; text = "Color Enhancement"; ObjectID = "uW9-fr-9eC"; */ +"uW9-fr-9eC.text" = "色彩增强"; -/* Class = "UISwitch"; title = "Face Beautify"; ObjectID = "YBf-iq-ZSD"; */ -"YBf-iq-ZSD.title" = "美颜"; +/* Class = "UILabel"; text = "Strength"; ObjectID = "Tim-Kh-axW"; */ +"Tim-Kh-axW.text" = "强度"; -/* Class = "UILabel"; text = "Redness"; ObjectID = "c7I-oU-1Ty"; */ -"c7I-oU-1Ty.text" = "红润"; +/* Class = "UILabel"; text = "Skin Protect"; ObjectID = "OAR-9q-CrU"; */ +"OAR-9q-CrU.text" = "肤色保护"; -/* Class = "UITextField"; placeholder = "Enter channel name"; ObjectID = "moa-hL-hhA"; */ -"moa-hL-hhA.placeholder" = "请输入频道名"; +/* Class = "UILabel"; text = "Virtual Background"; ObjectID = "0N7-qv-24q"; */ +"0N7-qv-24q.text" = "虚拟背景"; -/* Class = "UILabel"; text = "Sharpness"; ObjectID = "nxu-z3-DfB"; */ -"nxu-z3-DfB.text" = "锐利"; +/* Class = "UISegmentedControl"; 64G-UU-8yO.segmentTitles[0] = "Image"; ObjectID = "64G-UU-8yO"; */ +"64G-UU-8yO.segmentTitles[0]" = "图片"; -/* Class = "UILabel"; text = "Strength"; ObjectID = "OIO-FL-y7u"; */ -"OIO-FL-y7u.text" = "强度"; +/* Class = "UISegmentedControl"; 64G-UU-8yO.segmentTitles[1] = "Color"; ObjectID = "64G-UU-8yO"; */ +"64G-UU-8yO.segmentTitles[1]" = "颜色"; -/* Class = "UILabel"; text = "Skin Protect"; ObjectID = "C1K-xQ-TKU"; */ -"C1K-xQ-TKU.text" = "肤色保护"; +/* Class = "UISegmentedControl"; 64G-UU-8yO.segmentTitles[2] = "Blur"; ObjectID = "64G-UU-8yO"; */ +"64G-UU-8yO.segmentTitles[2]" = "毛玻璃"; From 1007df13e8aa278ddc5a48e16b9487180c2cd0bb Mon Sep 17 00:00:00 2001 From: sbd021 Date: Thu, 20 Jan 2022 16:58:20 +0800 Subject: [PATCH 06/21] win sdk version --- windows/APIExample/APIExample/APIExample.vcxproj | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/windows/APIExample/APIExample/APIExample.vcxproj b/windows/APIExample/APIExample/APIExample.vcxproj index 31411bbaa..04de37f51 100644 --- a/windows/APIExample/APIExample/APIExample.vcxproj +++ b/windows/APIExample/APIExample/APIExample.vcxproj @@ -23,7 +23,7 @@ {DB16CA2F-3910-4449-A5BD-6A602B33BE0F} MFCProj APIExample - 8.1 + 10.0.22000.0 From c321736a955413785b8685d2d6481b44cdb46b28 Mon Sep 17 00:00:00 2001 From: sbd021 Date: Thu, 20 Jan 2022 17:34:51 +0800 Subject: [PATCH 07/21] report nework data --- windows/APIExample/APIExample/APIExample.rc | 1 + .../LiveBroadcasting/CLiveBroadcastingDlg.cpp | 308 ++++++++++++++++++ .../LiveBroadcasting/CLiveBroadcastingDlg.h | 106 ++++++ windows/APIExample/APIExample/resource.h | 8 +- windows/APIExample/APIExample/stdafx.h | 26 ++ 5 files changed, 446 insertions(+), 3 deletions(-) diff --git a/windows/APIExample/APIExample/APIExample.rc b/windows/APIExample/APIExample/APIExample.rc index 84419dc2b..32998e25a 100644 --- a/windows/APIExample/APIExample/APIExample.rc +++ b/windows/APIExample/APIExample/APIExample.rc @@ -602,6 +602,7 @@ BEGIN COMBOBOX IDC_COMBO_COLOR,411,331,76,30,CBS_DROPDOWN | CBS_SORT | WS_VSCROLL | WS_TABSTOP PUSHBUTTON "Image File Path",IDC_BUTTON_IMAGE,331,329,73,14 EDITTEXT IDC_EDIT_IMAGE_PATH,411,329,144,14,ES_AUTOHSCROLL + CONTROL "Report",IDC_CHECK_REPORT,"Button",BS_AUTOCHECKBOX | WS_TABSTOP,570,325,38,10 END IDD_DIALOG_MUTI_SOURCE DIALOGEX 0, 0, 632, 400 diff --git a/windows/APIExample/APIExample/Basic/LiveBroadcasting/CLiveBroadcastingDlg.cpp b/windows/APIExample/APIExample/Basic/LiveBroadcasting/CLiveBroadcastingDlg.cpp index bbcef9ced..7069cfbf8 100644 --- a/windows/APIExample/APIExample/Basic/LiveBroadcasting/CLiveBroadcastingDlg.cpp +++ b/windows/APIExample/APIExample/Basic/LiveBroadcasting/CLiveBroadcastingDlg.cpp @@ -129,6 +129,7 @@ void CLiveBroadcastingDlg::DoDataExchange(CDataExchange* pDX) DDX_Control(pDX, IDC_BUTTON_IMAGE, m_btnImagePath); DDX_Control(pDX, IDC_CHECK_ENABLE_BACKGROUND, m_chkEnableBackground); DDX_Control(pDX, IDC_EDIT_IMAGE_PATH, m_edtImagePath); + DDX_Control(pDX, IDC_CHECK_REPORT, m_chkReport); } @@ -150,6 +151,18 @@ BEGIN_MESSAGE_MAP(CLiveBroadcastingDlg, CDialogEx) ON_BN_CLICKED(IDC_BUTTON_IMAGE, &CLiveBroadcastingDlg::OnBnClickedButtonImage) ON_BN_CLICKED(IDC_CHECK_ENABLE_BACKGROUND, &CLiveBroadcastingDlg::OnBnClickedCheckEnableBackground) ON_CBN_SELCHANGE(IDC_COMBO_BACKGROUND_TYPE, &CLiveBroadcastingDlg::OnSelchangeComboBackgroundType) + + + ON_MESSAGE(WM_MSGID(EID_NETWORK_QUALITY), &CLiveBroadcastingDlg::OnEIDNetworkQuality) + ON_MESSAGE(WM_MSGID(EID_RTC_STATS), &CLiveBroadcastingDlg::onEIDRtcStats) + ON_MESSAGE(WM_MSGID(EID_LOCAL_AUDIO_STATS), &CLiveBroadcastingDlg::onEIDLocalAudioStats) + ON_MESSAGE(WM_MSGID(EID_LOCAL_AUDIO_STATE_CHANED), &CLiveBroadcastingDlg::onEIDLocalAudioStateChanged) + ON_MESSAGE(WM_MSGID(EID_REMOTE_AUDIO_STATS), &CLiveBroadcastingDlg::onEIDRemoteAudioStats) + ON_MESSAGE(WM_MSGID(EID_REMOTE_AUDIO_STATE_CHANGED), &CLiveBroadcastingDlg::onEIDRemoteAudioStateChanged) + ON_MESSAGE(WM_MSGID(EID_LOCAL_VIDEO_STATS), &CLiveBroadcastingDlg::onEIDLocalVideoStats) + ON_MESSAGE(WM_MSGID(EID_LOCAL_VIDEO_STATE_CHANGED), &CLiveBroadcastingDlg::onEIDLocalVideoStateChanged) + ON_MESSAGE(WM_MSGID(EID_REMOTE_VIDEO_STATS), &CLiveBroadcastingDlg::onEIDRemoteVideoStats) + ON_BN_CLICKED(IDC_CHECK_REPORT, &CLiveBroadcastingDlg::OnBnClickedCheckReport) END_MESSAGE_MAP() @@ -833,3 +846,298 @@ void CLiveBroadcastingDlg::OnSelchangeComboBackgroundType() m_btnImagePath.ShowWindow(SW_SHOW); } } + +LRESULT CLiveBroadcastingDlg::OnEIDNetworkQuality(WPARAM wParam, LPARAM lParam) { + PNetworkQuality quality = (PNetworkQuality)wParam; + CString strInfo = _T("===onNetworkQuality==="); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("uid:%u"), quality->uid); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("txQuality:%d"), quality->txQuality); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("rxQuality:%u"), quality->rxQuality); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + if (quality) { + delete quality; + quality = nullptr; + } + return 0; +} +LRESULT CLiveBroadcastingDlg::onEIDRtcStats(WPARAM wParam, LPARAM lParam) { + RtcStats* stats = (RtcStats*)wParam; + CString strInfo = _T("===onRtcStats==="); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("duration:%u"), stats->duration); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("txBytes:%u"), stats->txBytes); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("rxBytes:%u"), stats->rxBytes); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + strInfo.Format(_T("txAudioBytes:%u"), stats->txAudioBytes); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("txVideoBytes:%u"), stats->txVideoBytes); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + strInfo.Format(_T("rxAudioBytes:%u"), stats->rxAudioBytes); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("rxVideoBytes:%u"), stats->rxVideoBytes); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + strInfo.Format(_T("txKBitRate:%u"), stats->txKBitRate); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("rxKBitRate:%u"), stats->rxKBitRate); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + strInfo.Format(_T("rxAudioKBitRate:%u"), stats->rxAudioKBitRate); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("txAudioKBitRate:%u"), stats->txAudioKBitRate); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + strInfo.Format(_T("rxVideoKBitRate:%u"), stats->rxVideoKBitRate); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("txVideoKBitRate:%u"), stats->txVideoKBitRate); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + strInfo.Format(_T("lastmileDelay:%u"), stats->lastmileDelay); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("userCount:%u"), stats->userCount); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + strInfo.Format(_T("cpuAppUsage:%u"), stats->cpuAppUsage); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("cpuTotalUsage:%u"), stats->cpuTotalUsage); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + + strInfo.Format(_T("gatewayRtt:%u"), stats->gatewayRtt); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("memoryAppUsageRatio:%u"), stats->memoryAppUsageRatio); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("memoryTotalUsageRatio:%u"), stats->memoryTotalUsageRatio); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("memoryAppUsageInKbytes:%u"), stats->memoryAppUsageInKbytes); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + + strInfo.Format(_T("txPacketLossRate:%u"), stats->txPacketLossRate); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("rxPacketLossRate:%u"), stats->rxPacketLossRate); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + + if (stats) { + delete stats; + stats = nullptr; + } + return 0; +} + +LRESULT CLiveBroadcastingDlg::onEIDLocalAudioStats(WPARAM wParam, LPARAM lParam) { + LocalAudioStats* stats = (LocalAudioStats*)wParam; + CString strInfo = _T("===onLocalAudioStats==="); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + strInfo.Format(_T("numChannels:%u"), stats->numChannels); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("sentSampleRate:%u"), stats->sentSampleRate); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + strInfo.Format(_T("sentBitrate:%u"), stats->sentBitrate); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("txPacketLossRate:%u"), stats->txPacketLossRate); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + + if (stats) { + delete stats; + stats = nullptr; + } + return 0; +} + +LRESULT CLiveBroadcastingDlg::onEIDLocalAudioStateChanged(WPARAM wParam, LPARAM lParam) { + LOCAL_AUDIO_STREAM_STATE state = (LOCAL_AUDIO_STREAM_STATE)wParam; + LOCAL_AUDIO_STREAM_ERROR error = (LOCAL_AUDIO_STREAM_ERROR)lParam; + CString strInfo = _T("===onLocalAudioStateChanged==="); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + strInfo.Format(_T("state:%d"), state); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("error:%d"), error); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + return 0; +} +LRESULT CLiveBroadcastingDlg::onEIDRemoteAudioStats(WPARAM wParam, LPARAM lParam) { + RemoteAudioStats* stats = (RemoteAudioStats*)wParam; + CString strInfo = _T("===onRemoteAudioStats==="); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + strInfo.Format(_T("uid:%u"), stats->uid); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("quality:%d"), stats->quality); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + strInfo.Format(_T("networkTransportDelay:%d"), stats->networkTransportDelay); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("jitterBufferDelay:%d"), stats->jitterBufferDelay); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + strInfo.Format(_T("audioLossRate:%d"), stats->audioLossRate); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("numChannels:%d"), stats->numChannels); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("receivedSampleRate:%d"), stats->receivedSampleRate); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("receivedBitrate:%d"), stats->receivedBitrate); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + strInfo.Format(_T("totalFrozenTime:%d"), stats->totalFrozenTime); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("frozenRate:%d"), stats->frozenRate); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("mosValue:%d"), stats->mosValue); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("totalActiveTime:%d"), stats->totalActiveTime); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + strInfo.Format(_T("publishDuration:%d"), stats->publishDuration); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + if (stats) { + delete stats; + stats = nullptr; + } + return 0; +} +LRESULT CLiveBroadcastingDlg::onEIDRemoteAudioStateChanged(WPARAM wParam, LPARAM lParam) { + CString strInfo = _T("===onRemoteAudioStateChanged==="); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + PRemoteAudioState state = (PRemoteAudioState)wParam; + + strInfo.Format(_T("elapsed:%d"), state->elapsed); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("uid:%u"), state->uid); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("state:%d"), state->state); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("reason:%d"), state->reason); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + return 0; +} +LRESULT CLiveBroadcastingDlg::onEIDLocalVideoStats(WPARAM wParam, LPARAM lParam) { + LocalVideoStats* stats = (LocalVideoStats*)wParam; + CString strInfo = _T("===onLocalVideoStats==="); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + strInfo.Format(_T("sentBitrate:%d"), stats->sentBitrate); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + strInfo.Format(_T("sentFrameRate:%d"), stats->sentFrameRate); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("encoderOutputFrameRate:%d"), stats->encoderOutputFrameRate); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + strInfo.Format(_T("rendererOutputFrameRate:%d"), stats->rendererOutputFrameRate); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("targetBitrate:%d"), stats->targetBitrate); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + strInfo.Format(_T("qualityAdaptIndication:%d"), stats->qualityAdaptIndication); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("encodedBitrate:%d"), stats->encodedBitrate); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + strInfo.Format(_T("encodedFrameWidth:%d"), stats->encodedFrameWidth); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("encodedFrameHeight:%d"), stats->encodedFrameHeight); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + strInfo.Format(_T("encodedFrameCount:%d"), stats->encodedFrameCount); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("codecType:%d"), stats->codecType); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + if (stats) { + delete stats; + stats = nullptr; + } + return 0; +} +LRESULT CLiveBroadcastingDlg::onEIDLocalVideoStateChanged(WPARAM wParam, LPARAM lParam) { + + LOCAL_VIDEO_STREAM_STATE state = (LOCAL_VIDEO_STREAM_STATE)wParam; + LOCAL_VIDEO_STREAM_ERROR error = (LOCAL_VIDEO_STREAM_ERROR)lParam; + CString strInfo = _T("===onLocalVideoStateChanged==="); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + strInfo.Format(_T("state:%d"), state); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("error:%d"), error); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + return 0; +} +LRESULT CLiveBroadcastingDlg::onEIDRemoteVideoStats(WPARAM wParam, LPARAM lParam) { + RemoteVideoStats* stats = (RemoteVideoStats*)wParam; + CString strInfo = _T("===onRemoteVideoStats==="); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + strInfo.Format(_T("uid:%u"), stats->uid); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("delay:%d"), stats->delay); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + strInfo.Format(_T("width:%d"), stats->width); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("height:%d"), stats->height); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + strInfo.Format(_T("receivedBitrate:%d"), stats->receivedBitrate); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("decoderOutputFrameRate:%d"), stats->decoderOutputFrameRate); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + strInfo.Format(_T("rendererOutputFrameRate:%d"), stats->rendererOutputFrameRate); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + strInfo.Format(_T("packetLossRate:%d"), stats->packetLossRate); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("rxStreamType:%d"), stats->rxStreamType); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + strInfo.Format(_T("totalFrozenTime:%d"), stats->totalFrozenTime); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("frozenRate:%d"), stats->frozenRate); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + strInfo.Format(_T("totalActiveTime:%d"), stats->totalActiveTime); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("publishDuration:%d"), stats->publishDuration); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + + if (stats) { + delete stats; + stats = nullptr; + } + return 0; +} +LRESULT CLiveBroadcastingDlg::onEIDRemoteVideoStateChanged(WPARAM wParam, LPARAM lParam) { + CString strInfo = _T("===onRemoteVideoStateChanged==="); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + PRemoteVideoState state = (PRemoteVideoState)wParam; + + strInfo.Format(_T("elapsed:%d"), state->elapsed); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("uid:%u"), state->uid); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("state:%d"), state->state); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("reason:%d"), state->reason); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + return 0; +} + +void CLiveBroadcastingDlg::OnBnClickedCheckReport() +{ + m_eventHandler.SetReport(m_chkReport.GetCheck() != 0); +} diff --git a/windows/APIExample/APIExample/Basic/LiveBroadcasting/CLiveBroadcastingDlg.h b/windows/APIExample/APIExample/Basic/LiveBroadcasting/CLiveBroadcastingDlg.h index c8a676704..00596dc4a 100644 --- a/windows/APIExample/APIExample/Basic/LiveBroadcasting/CLiveBroadcastingDlg.h +++ b/windows/APIExample/APIExample/Basic/LiveBroadcasting/CLiveBroadcastingDlg.h @@ -69,8 +69,102 @@ class CLiveBroadcastingRtcEngineEventHandler virtual void onLeaveChannel(const RtcStats& stats) override; virtual void onAudioDeviceStateChanged(const char* deviceId, int deviceType, int deviceState) override; + + virtual void onNetworkQuality(uid_t uid, int txQuality, int rxQuality) override { + if (m_hMsgHanlder&& report) { + PNetworkQuality quality = new NetworkQuality; + quality->uid = uid; + quality->txQuality = txQuality; + quality->txQuality = rxQuality; + + ::PostMessage(m_hMsgHanlder, WM_MSGID(EID_NETWORK_QUALITY), (WPARAM)quality, 0); + + } + } + virtual void onRtcStats(const RtcStats& stats) override { + if (m_hMsgHanlder&& report) { + RtcStats* s = new RtcStats; + *s = stats; + + ::PostMessage(m_hMsgHanlder, WM_MSGID(EID_RTC_STATS), (WPARAM)s, 0); + + } + } + + + virtual void onLocalAudioStats(const LocalAudioStats& stats) override { + if (m_hMsgHanlder&& report) { + LocalAudioStats* s = new LocalAudioStats; + *s = stats; + ::PostMessage(m_hMsgHanlder, WM_MSGID(EID_LOCAL_AUDIO_STATS), (WPARAM)s, 0); + + } + } + + virtual void onLocalAudioStateChanged(LOCAL_AUDIO_STREAM_STATE state, LOCAL_AUDIO_STREAM_ERROR error) { + if (m_hMsgHanlder&& report) { + ::PostMessage(m_hMsgHanlder, WM_MSGID(EID_LOCAL_AUDIO_STATE_CHANED), (WPARAM)state, (LPARAM)error); + } + } + + virtual void onRemoteAudioStats(const RemoteAudioStats& stats) { + if (m_hMsgHanlder&& report) { + RemoteAudioStats* s = new RemoteAudioStats; + *s = stats; + ::PostMessage(m_hMsgHanlder, WM_MSGID(EID_REMOTE_AUDIO_STATS), (WPARAM)s, 0); + + } + } + + virtual void onRemoteAudioStateChanged(uid_t uid, REMOTE_AUDIO_STATE state, REMOTE_AUDIO_STATE_REASON reason, int elapsed) { + if (m_hMsgHanlder&& report) { + PRemoteAudioState s = new RemoteAudioState; + s->elapsed = elapsed; + s->uid = uid; + s->state = state; + s->reason = reason; + ::PostMessage(m_hMsgHanlder, WM_MSGID(EID_REMOTE_AUDIO_STATE_CHANGED), (WPARAM)s, 0); + + } + } + virtual void onLocalVideoStats(const LocalVideoStats& stats) { + if (m_hMsgHanlder&& report) { + LocalVideoStats* s = new LocalVideoStats; + *s = stats; + ::PostMessage(m_hMsgHanlder, WM_MSGID(EID_LOCAL_VIDEO_STATS), (WPARAM)s, 0); + + } + } + + virtual void onLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE state, LOCAL_VIDEO_STREAM_ERROR error) { + if (m_hMsgHanlder&& report) { + ::PostMessage(m_hMsgHanlder, WM_MSGID(EID_LOCAL_VIDEO_STATE_CHANGED), (WPARAM)state, (LPARAM)error); + } + } + virtual void onRemoteVideoStats(const RemoteVideoStats& stats) { + if (m_hMsgHanlder&& report) { + RemoteVideoStats* s = new RemoteVideoStats; + *s = stats; + ::PostMessage(m_hMsgHanlder, WM_MSGID(EID_REMOTE_VIDEO_STATS), (WPARAM)s, 0); + + } + } + + virtual void onRemoteVideoStateChanged(uid_t uid, REMOTE_VIDEO_STATE state, REMOTE_VIDEO_STATE_REASON reason, int elapsed) { + if (m_hMsgHanlder&& report) { + PRemoteVideoState s = new RemoteVideoState; + s->elapsed = elapsed; + s->uid = uid; + s->state = state; + s->reason = reason; + ::PostMessage(m_hMsgHanlder, WM_MSGID(EID_REMOTE_VIDEO_STATE_CHANED), (WPARAM)s, 0); + + } + } + void SetReport(bool b) { report = b; } private: HWND m_hMsgHanlder; + bool report = false; }; class CLiveBroadcastingDlg : public CDialogEx @@ -112,6 +206,16 @@ class CLiveBroadcastingDlg : public CDialogEx afx_msg LRESULT OnEIDUserJoined(WPARAM wParam, LPARAM lParam); afx_msg LRESULT OnEIDUserOffline(WPARAM wParam, LPARAM lParam); afx_msg LRESULT OnEIDAudioDeviceStateChanged(const char* deviceId, int deviceType, int deviceState); + afx_msg LRESULT OnEIDNetworkQuality(WPARAM wParam, LPARAM lParam); + afx_msg LRESULT onEIDRtcStats(WPARAM wParam, LPARAM lParam); + afx_msg LRESULT onEIDLocalAudioStats(WPARAM wParam, LPARAM lParam); + afx_msg LRESULT onEIDLocalAudioStateChanged(WPARAM wParam, LPARAM lParam); + afx_msg LRESULT onEIDRemoteAudioStats(WPARAM wParam, LPARAM lParam); + afx_msg LRESULT onEIDRemoteAudioStateChanged(WPARAM wParam, LPARAM lParam); + afx_msg LRESULT onEIDLocalVideoStats(WPARAM wParam, LPARAM lParam); + afx_msg LRESULT onEIDLocalVideoStateChanged(WPARAM wParam, LPARAM lParam); + afx_msg LRESULT onEIDRemoteVideoStats(WPARAM wParam, LPARAM lParam); + afx_msg LRESULT onEIDRemoteVideoStateChanged(WPARAM wParam, LPARAM lParam); private: //set control text from config. void InitCtrlText(); @@ -172,4 +276,6 @@ class CLiveBroadcastingDlg : public CDialogEx CButton m_chkEnableBackground; afx_msg void OnSelchangeComboBackgroundType(); CEdit m_edtImagePath; + afx_msg void OnBnClickedCheckReport(); + CButton m_chkReport; }; diff --git a/windows/APIExample/APIExample/resource.h b/windows/APIExample/APIExample/resource.h index 09cc9c968..de9aaafe5 100644 --- a/windows/APIExample/APIExample/resource.h +++ b/windows/APIExample/APIExample/resource.h @@ -1,6 +1,6 @@ //{{NO_DEPENDENCIES}} -// Microsoft Visual C++ generated include file. -// Used by APIExample.rc +// Microsoft Visual C++ ɵİļ +// APIExample.rc ʹ // #define IDM_ABOUTBOX 0x0010 #define IDD_ABOUTBOX 100 @@ -301,6 +301,8 @@ #define IDC_EDIT1 1179 #define IDC_EDIT_IMAGE_PATH 1180 #define IDC_BUTTON_ECHO_TEST2 1181 +#define IDC_CHECK_ 1182 +#define IDC_CHECK_REPORT 1182 // Next default values for new objects // @@ -308,7 +310,7 @@ #ifndef APSTUDIO_READONLY_SYMBOLS #define _APS_NEXT_RESOURCE_VALUE 139 #define _APS_NEXT_COMMAND_VALUE 32771 -#define _APS_NEXT_CONTROL_VALUE 1182 +#define _APS_NEXT_CONTROL_VALUE 1183 #define _APS_NEXT_SYMED_VALUE 101 #endif #endif diff --git a/windows/APIExample/APIExample/stdafx.h b/windows/APIExample/APIExample/stdafx.h index e20bab258..118d94b79 100644 --- a/windows/APIExample/APIExample/stdafx.h +++ b/windows/APIExample/APIExample/stdafx.h @@ -142,6 +142,32 @@ typedef struct _AGE_SCREENSHARE_START HWND hWnd; }AGE_SCREENSHARE_START, *PAGE_SCREENSHARE_START, *LPAGE_SCREENSHARE_START; +typedef struct _tagNetworkQuality { + uid_t uid; + int txQuality; + int rxQuality; +}NetworkQuality, *PNetworkQuality; + +typedef struct _tagRemoteAudioState { + uid_t uid; + REMOTE_AUDIO_STATE state; + REMOTE_AUDIO_STATE_REASON reason; + int elapsed; +}RemoteAudioState, *PRemoteAudioState; + +typedef struct _tagRemoteVideoState { + uid_t uid; + REMOTE_VIDEO_STATE state; + REMOTE_VIDEO_STATE_REASON reason; + int elapsed; +}RemoteVideoState, *PRemoteVideoState; + +#define EID_NETWORK_QUALITY 0x00000022 + +#define EID_LOCAL_AUDIO_STATS 0x00000024 +#define EID_LOCAL_AUDIO_STATE_CHANED 0x00000025 +#define EID_REMOTE_AUDIO_STATE_CHANGED 0x00000027 + #define EID_SCREENSHARE_START 0x00000022 #define EID_SCREENSHARE_STOP 0x00000023 #define EID_SCREENSHARE_CLOSE 0x00000024 From fdb1e204a24183cd4922fdf4731ed68e15e719eb Mon Sep 17 00:00:00 2001 From: sbd021 Date: Thu, 20 Jan 2022 18:27:04 +0800 Subject: [PATCH 08/21] beauty enhance --- windows/APIExample/APIExample/APIExample.rc | 74 +++++----- .../Advanced/Beauty/CAgoraBeautyDlg.cpp | 126 +++++++++++++++--- .../Advanced/Beauty/CAgoraBeautyDlg.h | 23 +++- windows/APIExample/APIExample/resource.h | 25 ++-- 4 files changed, 190 insertions(+), 58 deletions(-) diff --git a/windows/APIExample/APIExample/APIExample.rc b/windows/APIExample/APIExample/APIExample.rc index 32998e25a..c4e252285 100644 --- a/windows/APIExample/APIExample/APIExample.rc +++ b/windows/APIExample/APIExample/APIExample.rc @@ -437,27 +437,6 @@ BEGIN LTEXT "vloume",IDC_STATIC_AUDIO_VLOUME,327,386,42,8 END -IDD_DIALOG_BEAUTY DIALOGEX 0, 0, 632, 400 -STYLE DS_SETFONT | DS_FIXEDSYS | WS_CHILD | WS_SYSMENU -FONT 8, "MS Shell Dlg", 400, 0, 0x1 -BEGIN - LTEXT "",IDC_STATIC_VIDEO,1,0,483,310,NOT WS_VISIBLE - LISTBOX IDC_LIST_INFO_BROADCASTING,491,0,139,312,LBS_NOINTEGRALHEIGHT | LBS_DISABLENOSCROLL | WS_VSCROLL | WS_HSCROLL | WS_TABSTOP - LTEXT "Channel Name",IDC_STATIC_CHANNELNAME,11,328,48,8 - EDITTEXT IDC_EDIT_CHANNELNAME,71,326,218,13,ES_AUTOHSCROLL - PUSHBUTTON "JoinChannel",IDC_BUTTON_JOINCHANNEL,307,326,50,14 - LTEXT "lightening contrast",IDC_STATIC_BEAUTY_LIGHTENING_CONTRAST_LEVEL,11,353,93,8 - COMBOBOX IDC_COMBO_BEAUTE_LIGHTENING_CONTRAST_LEVEL,80,352,79,30,CBS_DROPDOWNLIST | CBS_SORT | WS_VSCROLL | WS_TABSTOP - LTEXT "",IDC_STATIC_DETAIL,442,325,181,58 - LTEXT "lightening",IDC_STATIC_BEAUTY_LIGHTENING,11,370,48,8 - EDITTEXT IDC_EDIT_LIGHTENING,79,369,80,13,ES_AUTOHSCROLL - LTEXT "redness",IDC_STATIC_BEAUTY_REDNESS,166,353,48,8 - LTEXT "smoothness",IDC_STATIC_BEAUTY_SMOOTHNESS,166,371,48,8 - EDITTEXT IDC_EDIT_BEAUTY_REDNESS,222,351,80,13,ES_AUTOHSCROLL - EDITTEXT IDC_EDIT_BEAUTY_SMOOTHNESS,222,370,80,13,ES_AUTOHSCROLL - CONTROL "Beauty Enable",IDC_CHECK_BEAUTY_ENABLE,"Button",BS_AUTOCHECKBOX | WS_TABSTOP,310,358,62,10 -END - IDD_DIALOG_PERCALL_TEST DIALOGEX 0, 0, 632, 400 STYLE DS_SETFONT | DS_FIXEDSYS | WS_CHILD | WS_SYSMENU FONT 8, "MS Shell Dlg", 400, 0, 0x1 @@ -620,6 +599,37 @@ BEGIN LTEXT "Share Info",IDC_STATIC_SHARE,17,370,38,8 END +IDD_DIALOG_BEAUTY DIALOGEX 0, 0, 632, 400 +STYLE DS_SETFONT | DS_FIXEDSYS | WS_CHILD | WS_SYSMENU +FONT 8, "MS Shell Dlg", 400, 0, 0x1 +BEGIN + LTEXT "",IDC_STATIC_VIDEO,0,0,483,289,NOT WS_VISIBLE + LISTBOX IDC_LIST_INFO_BROADCASTING,491,0,139,286,LBS_NOINTEGRALHEIGHT | LBS_DISABLENOSCROLL | WS_VSCROLL | WS_HSCROLL | WS_TABSTOP + LTEXT "Channel Name",IDC_STATIC_CHANNELNAME,12,309,48,8 + EDITTEXT IDC_EDIT_CHANNELNAME,72,307,115,13,ES_AUTOHSCROLL + PUSHBUTTON "JoinChannel",IDC_BUTTON_JOINCHANNEL,194,306,50,14 + LTEXT "lightening contrast",IDC_STATIC_BEAUTY_LIGHTENING_CONTRAST_LEVEL,12,334,64,8 + COMBOBOX IDC_COMBO_BEAUTE_LIGHTENING_CONTRAST_LEVEL,81,333,79,30,CBS_DROPDOWNLIST | CBS_SORT | WS_VSCROLL | WS_TABSTOP + LTEXT "",IDC_STATIC_DETAIL,485,297,132,56 + LTEXT "lightening",IDC_STATIC_BEAUTY_LIGHTENING,12,351,45,8 + LTEXT "redness",IDC_STATIC_BEAUTY_REDNESS,167,334,41,8 + LTEXT "smoothness",IDC_STATIC_BEAUTY_SMOOTHNESS,167,352,42,8 + CONTROL "Beauty Enable",IDC_CHECK_BEAUTY_ENABLE,"Button",BS_AUTOCHECKBOX | WS_TABSTOP,251,307,62,10 + GROUPBOX "Beauty",IDC_STATIC_BEaUTY,0,300,352,67 + GROUPBOX "Enhance",IDC_STATIC,0,373,412,24 + CONTROL "Colorful Enhance",IDC_CHECK_ENHANCE,"Button",BS_AUTOCHECKBOX | WS_TABSTOP,5,384,75,13 + CONTROL "",IDC_SLIDER_STRENGTH,"msctls_trackbar32",TBS_BOTH | TBS_NOTICKS | WS_TABSTOP,130,382,104,15 + LTEXT "Strength",IDC_STATIC_STRENTH,92,389,29,8 + LTEXT "Skin Protect",IDC_STATIC_SKIN_PROTECT,241,389,40,8 + LTEXT "Strength",IDC_STATIC_STRENTH2,95,389,29,8 + LTEXT "Static",IDC_STATIC,267,389,19,8 + CONTROL "",IDC_SLIDER_SKIN_PROTECT,"msctls_trackbar32",TBS_BOTH | TBS_NOTICKS | WS_TABSTOP,294,382,110,15 + CONTROL "Video Denoise",IDC_CHECK_VIDEO_DENOISE,"Button",BS_AUTOCHECKBOX | WS_TABSTOP,370,299,58,10 + CONTROL "",IDC_SLIDER_REDNESS,"msctls_trackbar32",TBS_BOTH | TBS_NOTICKS | WS_TABSTOP,219,330,121,15 + CONTROL "",IDC_SLIDER_LIGHTENING,"msctls_trackbar32",TBS_BOTH | TBS_NOTICKS | WS_TABSTOP,55,348,100,15 + CONTROL "",IDC_SLIDER_SMOOTHNESS,"msctls_trackbar32",TBS_BOTH | TBS_NOTICKS | WS_TABSTOP,222,346,117,15 +END + ///////////////////////////////////////////////////////////////////////////// // @@ -732,12 +742,6 @@ BEGIN BOTTOMMARGIN, 397 END - IDD_DIALOG_BEAUTY, DIALOG - BEGIN - RIGHTMARGIN, 630 - BOTTOMMARGIN, 397 - END - IDD_DIALOG_PERCALL_TEST, DIALOG BEGIN RIGHTMARGIN, 630 @@ -779,6 +783,12 @@ BEGIN RIGHTMARGIN, 630 BOTTOMMARGIN, 397 END + + IDD_DIALOG_BEAUTY, DIALOG + BEGIN + RIGHTMARGIN, 630 + BOTTOMMARGIN, 397 + END END #endif // APSTUDIO_INVOKED @@ -873,11 +883,6 @@ BEGIN 0 END -IDD_DIALOG_BEAUTY AFX_DIALOG_LAYOUT -BEGIN - 0 -END - IDD_DIALOG_PERCALL_TEST AFX_DIALOG_LAYOUT BEGIN 0 @@ -913,6 +918,11 @@ BEGIN 0 END +IDD_DIALOG_BEAUTY AFX_DIALOG_LAYOUT +BEGIN + 0 +END + ///////////////////////////////////////////////////////////////////////////// // diff --git a/windows/APIExample/APIExample/Advanced/Beauty/CAgoraBeautyDlg.cpp b/windows/APIExample/APIExample/Advanced/Beauty/CAgoraBeautyDlg.cpp index cb8ef1ea2..ec16a5305 100644 --- a/windows/APIExample/APIExample/Advanced/Beauty/CAgoraBeautyDlg.cpp +++ b/windows/APIExample/APIExample/Advanced/Beauty/CAgoraBeautyDlg.cpp @@ -111,9 +111,7 @@ void CAgoraBeautyDlg::RenderLocalVideo() void CAgoraBeautyDlg::ResumeStatus() { m_edtChannel.SetWindowText(_T("")); - m_edtLightLevel.SetWindowText(_T("")); - m_edtReadness.SetWindowText(_T("")); - m_edtSmoothness.SetWindowText(_T("")); + m_staDetail.SetWindowText(_T("")); m_chkBeauty.SetCheck(BST_UNCHECKED); @@ -122,6 +120,18 @@ void CAgoraBeautyDlg::ResumeStatus() SetBeauty(false); m_joinChannel = false; m_initialize = false; + + m_sldStrength.SetRange(0, 100); + m_sldStrength.SetPos(50); + m_sldSkin.SetRange(0, 100); + m_sldSkin.SetPos(100); + + m_sdlLightening.SetRange(0, 100); + m_sdlLightening.SetPos(0); + m_sldRedness.SetRange(0, 100); + m_sldRedness.SetPos(0); + m_sldSmoothness.SetRange(0, 100); + m_sldSmoothness.SetPos(0); } @@ -133,16 +143,24 @@ void CAgoraBeautyDlg::DoDataExchange(CDataExchange* pDX) DDX_Control(pDX, IDC_CHECK_BEAUTY_ENABLE, m_chkBeauty); DDX_Control(pDX, IDC_BUTTON_JOINCHANNEL, m_btnJoinChannel); DDX_Control(pDX, IDC_COMBO_BEAUTE_LIGHTENING_CONTRAST_LEVEL, m_cmbBeautyLevel); - DDX_Control(pDX, IDC_EDIT_LIGHTENING, m_edtLightLevel); + DDX_Control(pDX, IDC_STATIC_BEAUTY_REDNESS, m_staRedness); DDX_Control(pDX, IDC_STATIC_BEAUTY_SMOOTHNESS, m_staSoomthness); - DDX_Control(pDX, IDC_EDIT_BEAUTY_REDNESS, m_edtReadness); - DDX_Control(pDX, IDC_EDIT_BEAUTY_SMOOTHNESS, m_edtSmoothness); + DDX_Control(pDX, IDC_STATIC_VIDEO, m_staVideoArea); DDX_Control(pDX, IDC_LIST_INFO_BROADCASTING, m_lstInfo); DDX_Control(pDX, IDC_STATIC_BEAUTY_LIGHTENING_CONTRAST_LEVEL, m_staLightContrast); DDX_Control(pDX, IDC_STATIC_BEAUTY_LIGHTENING, m_staLight); DDX_Control(pDX, IDC_STATIC_DETAIL, m_staDetail); + DDX_Control(pDX, IDC_CHECK_ENHANCE, m_chkEnhance); + DDX_Control(pDX, IDC_SLIDER_STRENGTH, m_sldStrength); + DDX_Control(pDX, IDC_STATIC_SKIN_PROTECT, m_staSkin); + DDX_Control(pDX, IDC_SLIDER_SKIN_PROTECT, m_sldSkin); + DDX_Control(pDX, IDC_CHECK_VIDEO_DENOISE, m_chkVideoDenoise); + + DDX_Control(pDX, IDC_SLIDER_LIGHTENING, m_sdlLightening); + DDX_Control(pDX, IDC_SLIDER_REDNESS, m_sldRedness); + DDX_Control(pDX, IDC_SLIDER_SMOOTHNESS, m_sldSmoothness); } @@ -156,9 +174,36 @@ BEGIN_MESSAGE_MAP(CAgoraBeautyDlg, CDialogEx) ON_WM_SHOWWINDOW() ON_BN_CLICKED(IDC_CHECK_BEAUTY_ENABLE, &CAgoraBeautyDlg::OnBnClickedCheckbeautyCtrlEnable) ON_LBN_SELCHANGE(IDC_LIST_INFO_BROADCASTING, &CAgoraBeautyDlg::OnSelchangeListInfoBroadcasting) + ON_NOTIFY(NM_CUSTOMDRAW, IDC_SLIDER_REDNESS, &CAgoraBeautyDlg::OnNMCustomdrawSliderRedness) + ON_NOTIFY(NM_CUSTOMDRAW, IDC_SLIDER_LIGHTENING, &CAgoraBeautyDlg::OnNMCustomdrawSliderLightening) + ON_NOTIFY(NM_CUSTOMDRAW, IDC_SLIDER_SMOOTHNESS, &CAgoraBeautyDlg::OnNMCustomdrawSliderSmoothness) + ON_NOTIFY(NM_CUSTOMDRAW, IDC_SLIDER_STRENGTH, &CAgoraBeautyDlg::OnNMCustomdrawSliderStrength) + ON_NOTIFY(NM_CUSTOMDRAW, IDC_SLIDER_SKIN_PROTECT, &CAgoraBeautyDlg::OnNMCustomdrawSliderSkinProtect) + ON_BN_CLICKED(IDC_CHECK_ENHANCE, &CAgoraBeautyDlg::OnBnClickedCheckEnhance) + ON_BN_CLICKED(IDC_CHECK_VIDEO_DENOISE, &CAgoraBeautyDlg::OnBnClickedCheckVideoDenoise) + ON_CBN_SELCHANGE(IDC_COMBO_BEAUTE_LIGHTENING_CONTRAST_LEVEL, &CAgoraBeautyDlg::OnSelchangeComboBeauteLighteningContrastLevel) END_MESSAGE_MAP() +void CAgoraBeautyDlg::SetBeauty() +{ + if (!m_rtcEngine) return; + BeautyOptions option; + option.rednessLevel = m_sldRedness.GetPos() / 100.0f; + option.lighteningLevel = m_sdlLightening.GetPos() / 100.0f; + option.smoothnessLevel = m_sldSmoothness.GetPos() / 100.0f; + option.lighteningContrastLevel = (agora::rtc::BeautyOptions::LIGHTENING_CONTRAST_LEVEL)m_cmbBeautyLevel.GetCurSel(); + m_rtcEngine->setBeautyEffectOptions(m_chkBeauty.GetCheck() != 0, option); +} + +void CAgoraBeautyDlg::SetColorful() +{ + if (!m_rtcEngine) return; + ColorEnhanceOptions options; + options.skinProtectLevel = m_sldSkin.GetPos() / 100.0f; + options.strengthLevel = m_sldStrength.GetPos() / 100.0f; + m_rtcEngine->setColorEnhanceOptions(m_chkEnhance.GetCheck()!=0,options); +} // join channel or level channel. void CAgoraBeautyDlg::OnBnClickedButtonJoinchannel() @@ -213,25 +258,24 @@ void CAgoraBeautyDlg::SetBeauty(bool enabled, void CAgoraBeautyDlg::OnBnClickedCheckbeautyCtrlEnable() { bool enabled = m_chkBeauty.GetCheck() == BST_CHECKED ? TRUE : FALSE; + m_sldRedness.EnableWindow(enabled); + m_sldSmoothness.EnableWindow(enabled); + m_sdlLightening.EnableWindow(enabled); + //Beauty options to set CString tmp; auto lighteningContrastLevel = (agora::rtc::BeautyOptions::LIGHTENING_CONTRAST_LEVEL)m_cmbBeautyLevel.GetCurSel(); float lighteningLevel; float rednessLevel; float smoothnessLevel; - m_edtLightLevel.GetWindowText(tmp); - auto func = [](float a)->float { - return a <0.0f ? 0.0f : a>1.0f ? 1.0f : a; - }; - lighteningLevel = func(static_cast(_ttof(tmp)/10)); - m_edtReadness.GetWindowText(tmp); - rednessLevel = func(static_cast(_ttof(tmp)/10)); - m_edtSmoothness.GetWindowText(tmp); - smoothnessLevel = func(static_cast(_ttof(tmp)/10)); + lighteningLevel = m_sdlLightening.GetPos() / 100.0f; + rednessLevel = m_sldRedness.GetPos() / 100.0f; + smoothnessLevel = m_sldSmoothness.GetPos() / 100.0f; CString strInfo; CString strlighteningContrastLevel; m_cmbBeautyLevel.GetWindowText(strlighteningContrastLevel); SetBeauty(enabled, lighteningContrastLevel, lighteningLevel, rednessLevel, smoothnessLevel); + SetColorful(); if (enabled) { strInfo.Format(_T("lighteningContrastLevel:%s,\nlightening:%.1f,\nredness:%.1f,\nsmoothness:%.1f"), @@ -485,3 +529,55 @@ void CAgoraBeautyDlg::OnSelchangeListInfoBroadcasting() m_lstInfo.GetText(sel, strDetail); m_staDetail.SetWindowText(strDetail); } + + +void CAgoraBeautyDlg::OnNMCustomdrawSliderRedness(NMHDR *pNMHDR, LRESULT *pResult) +{ + SetBeauty(); +} + + +void CAgoraBeautyDlg::OnNMCustomdrawSliderLightening(NMHDR *pNMHDR, LRESULT *pResult) +{ + SetBeauty(); +} + + +void CAgoraBeautyDlg::OnNMCustomdrawSliderSmoothness(NMHDR *pNMHDR, LRESULT *pResult) +{ + SetBeauty(); +} + + +void CAgoraBeautyDlg::OnNMCustomdrawSliderStrength(NMHDR *pNMHDR, LRESULT *pResult) +{ + SetColorful(); +} + + +void CAgoraBeautyDlg::OnNMCustomdrawSliderSkinProtect(NMHDR *pNMHDR, LRESULT *pResult) +{ + SetColorful(); +} + + +void CAgoraBeautyDlg::OnBnClickedCheckEnhance() +{ + m_sldStrength.EnableWindow(m_chkEnhance.GetCheck() != 0); + m_sldSkin.EnableWindow(m_chkEnhance.GetCheck() != 0); + + SetColorful(); +} + + +void CAgoraBeautyDlg::OnBnClickedCheckVideoDenoise() +{ + VideoDenoiserOptions options; + m_rtcEngine->setVideoDenoiserOptions(m_chkVideoDenoise.GetCheck() != 0,options); +} + + +void CAgoraBeautyDlg::OnSelchangeComboBeauteLighteningContrastLevel() +{ + SetBeauty(); +} diff --git a/windows/APIExample/APIExample/Advanced/Beauty/CAgoraBeautyDlg.h b/windows/APIExample/APIExample/Advanced/Beauty/CAgoraBeautyDlg.h index 43a9490c7..307a54bac 100644 --- a/windows/APIExample/APIExample/Advanced/Beauty/CAgoraBeautyDlg.h +++ b/windows/APIExample/APIExample/Advanced/Beauty/CAgoraBeautyDlg.h @@ -115,6 +115,8 @@ class CAgoraBeautyDlg : public CDialogEx CBeautyEventHandler m_eventHandler; protected: + void SetBeauty(); + void SetColorful(); virtual void DoDataExchange(CDataExchange* pDX); LRESULT OnEIDJoinChannelSuccess(WPARAM wParam, LPARAM lParam); LRESULT OnEIDLeaveChannel(WPARAM wParam, LPARAM lParam); @@ -129,11 +131,9 @@ class CAgoraBeautyDlg : public CDialogEx CButton m_chkBeauty; CButton m_btnJoinChannel; CComboBox m_cmbBeautyLevel; - CEdit m_edtLightLevel; + CStatic m_staRedness; CStatic m_staSoomthness; - CEdit m_edtReadness; - CEdit m_edtSmoothness; CStatic m_staVideoArea; CListBox m_lstInfo; CStatic m_staLightContrast; @@ -146,6 +146,23 @@ class CAgoraBeautyDlg : public CDialogEx virtual BOOL PreTranslateMessage(MSG* pMsg); CStatic m_staDetail; afx_msg void OnSelchangeListInfoBroadcasting(); + + CSliderCtrl m_sldStrength; + CStatic m_staSkin; + CSliderCtrl m_sldSkin; + CButton m_chkVideoDenoise; + CButton m_chkEnhance; + CSliderCtrl m_sdlLightening; + CSliderCtrl m_sldRedness; + CSliderCtrl m_sldSmoothness; + afx_msg void OnNMCustomdrawSliderRedness(NMHDR *pNMHDR, LRESULT *pResult); + afx_msg void OnNMCustomdrawSliderLightening(NMHDR *pNMHDR, LRESULT *pResult); + afx_msg void OnNMCustomdrawSliderSmoothness(NMHDR *pNMHDR, LRESULT *pResult); + afx_msg void OnNMCustomdrawSliderStrength(NMHDR *pNMHDR, LRESULT *pResult); + afx_msg void OnNMCustomdrawSliderSkinProtect(NMHDR *pNMHDR, LRESULT *pResult); + afx_msg void OnBnClickedCheckEnhance(); + afx_msg void OnBnClickedCheckVideoDenoise(); + afx_msg void OnSelchangeComboBeauteLighteningContrastLevel(); }; diff --git a/windows/APIExample/APIExample/resource.h b/windows/APIExample/APIExample/resource.h index de9aaafe5..d5851de87 100644 --- a/windows/APIExample/APIExample/resource.h +++ b/windows/APIExample/APIExample/resource.h @@ -12,8 +12,8 @@ #define IDD_DIALOG_SCREEN_SHARE 134 #define IDD_DIALOG_CUSTOM_CAPTURE_VIDEO 135 #define IDD_DIALOG_CUSTOM_CAPTURE_AUDIO 136 -#define IDD_DIALOG_BEAUTY 137 #define IDB_BITMAP_NETWORK_STATE 137 +#define IDD_DIALOG_BEAUTY 137 #define IDD_DIALOG_AUDIO_PROFILE 138 #define IDR_TEST_WAVE 138 #define IDD_DIALOG_BEAUTY_AUDIO 139 @@ -57,7 +57,6 @@ #define IDC_BUTTON1 1021 #define IDC_BUTTON_JOINCHANNEL 1021 #define IDC_STATIC_SENDSEI 1022 -#define IDC_EDIT_LIGHTENING 1022 #define IDC_EDIT_AUDIO_MIX_PATH 1022 #define IDC_STATIC_FPS 1022 #define IDC_BUTTON_SET_AUDIO_PROC 1022 @@ -69,7 +68,6 @@ #define IDC_COMBO_PERSONS2 1022 #define IDC_COMBO_AUDIENCE_LATENCY 1022 #define IDC_EDIT_SEI 1023 -#define IDC_EDIT_BEAUTY_REDNESS 1023 #define IDC_EDIT_AUDIO_REPEAT_TIMES 1023 #define IDC_EDIT_FPS 1023 #define IDC_EDIT_VIDEO_SOURCE 1023 @@ -77,7 +75,6 @@ #define IDC_STATIC_AUDIENCE_LATENCY 1023 #define IDC_BUTTON_ADDSTREAM 1024 #define IDC_BUTTON_SEND 1024 -#define IDC_EDIT_BEAUTY_SMOOTHNESS 1024 #define IDC_STATIC_BITRATE 1024 #define IDC_BUTTON_OPEN 1024 #define IDC_EDIT_VIDEO_FPS 1024 @@ -109,9 +106,9 @@ #define IDC_COMBO_SCREEN_CAPTURE 1042 #define IDC_BUTTON_START_CAPUTRE 1043 #define IDC_STATIC_CAPTUREDEVICE 1044 -#define IDC_STATIC_BEAUTY_LIGHTENING 1044 #define IDC_BUTTON_SHARE_DESKTOP 1044 #define IDC_STATIC_SCREEN_SHARE 1044 +#define IDC_STATIC_BEAUTY_LIGHTENING 1044 #define IDC_COMBO_CAPTURE_VIDEO_DEVICE 1045 #define IDC_COMBO_SCREEN_SCREEN 1045 #define IDC_BUTTON_RENDER_AUDIO 1045 @@ -123,21 +120,21 @@ #define IDC_STATIC_SDKCAMERA 1047 #define IDC_COMBO_CAPTURE_AUDIO_TYPE 1048 #define IDC_COMBO_SDKCAMERA 1048 -#define IDC_STATIC_BEAUTY_LIGHTENING_CONTRAST_LEVEL 1049 #define IDC_COMBO_SDK_RESOLUTION 1049 +#define IDC_STATIC_BEAUTY_LIGHTENING_CONTRAST_LEVEL 1049 #define IDC_COMBO_BEAUTE_LIGHTENING_CONTRAST_LEVEL 1050 #define IDC_STATIC_BEAUTY_REDNESS 1051 -#define IDC_STATIC_BEAUTY_SMOOTHNESS 1052 #define IDC_STATIC_CAPTURE_TYPE 1052 +#define IDC_STATIC_BEAUTY_SMOOTHNESS 1052 #define IDC_COMBO_SDKCAMERA2 1053 #define IDC_CMB_MEDIO_CAPTURETYPE 1053 #define IDC_CHECK1 1054 -#define IDC_CHECK_BEAUTY_ENABLE 1054 #define IDC_CHK_ONLY_LOCAL 1054 #define IDC_CHECK_CURSOR 1054 #define IDC_CHK_TRANS_CODING 1054 #define IDC_CHECK_LOOPBACK 1054 #define IDC_CHECK_PUBLISH_AUDIO 1054 +#define IDC_CHECK_BEAUTY_ENABLE 1054 #define IDC_STATIC_ADUIO_PROFILE 1055 #define IDC_CHK_REPLACE_MICROPHONE 1055 #define IDC_CHECK_PUBLISH_VIDEO 1055 @@ -194,19 +191,31 @@ #define IDC_BUTTON_SET_MEDIA_ENCRYPT 1088 #define IDC_STATIC_ENCRYPT_KEY 1089 #define IDC_CHECK_WINDOW_FOCUS 1090 +#define IDC_STATIC_BEaUTY 1090 #define IDC_COMBO_FPS 1091 +#define IDC_CHECK_ENHANCE 1091 #define IDC_STATIC_AUDIO_EFFECT_PATH 1092 +#define IDC_SLIDER_STRENGTH 1092 #define IDC_EDIT_AUDIO_EFFECT_PATH 1093 +#define IDC_STATIC_STRENTH 1093 #define IDC_SPIN1 1094 #define IDC_SPIN_AGIN 1094 +#define IDC_STATIC_SKIN_PROTECT 1094 #define IDC_STATIC_AUDIO_PITCH 1095 +#define IDC_SLIDER_SKIN_PROTECT 1095 #define IDC_SPIN2 1096 #define IDC_SPIN_PITCH 1096 +#define IDC_CHECK_VIDEO_DENOISE 1096 #define IDC_STATIC_AUDIO_PAN 1097 +#define IDC_SLIDER_REDNESS 1097 #define IDC_COMBO_PAN 1098 +#define IDC_SLIDER_LIGHTENING 1098 #define IDC_CHK_PUBLISH 1099 +#define IDC_STATIC_STRENTH2 1099 #define IDC_BUTTON_ADD_EFFECT 1100 +#define IDC_CHECK_VIDEO_DENOISE2 1100 #define IDC_STATIC_AUDIO_EFFECT 1101 +#define IDC_SLIDER_SMOOTHNESS 1101 #define IDC_COMBO2 1102 #define IDC_BUTTON_REMOVE 1103 #define IDC_BUTTON_PRELOAD 1104 From 0adf03f04f45e6a68ecd45f23b9084ed8401e8f9 Mon Sep 17 00:00:00 2001 From: sbd021 Date: Thu, 20 Jan 2022 18:39:48 +0800 Subject: [PATCH 09/21] volume test callback in channel --- .../AudioVolume/CAgoraAudioVolumeDlg.cpp | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/windows/APIExample/APIExample/Advanced/AudioVolume/CAgoraAudioVolumeDlg.cpp b/windows/APIExample/APIExample/Advanced/AudioVolume/CAgoraAudioVolumeDlg.cpp index 738134749..b5961c55f 100644 --- a/windows/APIExample/APIExample/Advanced/AudioVolume/CAgoraAudioVolumeDlg.cpp +++ b/windows/APIExample/APIExample/Advanced/AudioVolume/CAgoraAudioVolumeDlg.cpp @@ -166,6 +166,8 @@ BEGIN_MESSAGE_MAP(CAgoraAudioVolumeDlg, CDialogEx) ON_MESSAGE(WM_MSGID(EID_USER_JOINED), &CAgoraAudioVolumeDlg::OnEIDUserJoined) ON_MESSAGE(WM_MSGID(EID_USER_OFFLINE), &CAgoraAudioVolumeDlg::OnEIDUserOffline) ON_MESSAGE(WM_MSGID(EID_AUDIO_VOLUME_INDICATION), &CAgoraAudioVolumeDlg::OnEIDAudioVolumeIndication) + ON_MESSAGE(WM_MSGID(EID_AUDIO_VOLUME_TEST_INDICATION), &CAgoraAudioVolumeDlg::OnEIDAudioVolumeTestIndication) + ON_BN_CLICKED(IDC_BUTTON_JOINCHANNEL, &CAgoraAudioVolumeDlg::OnBnClickedButtonJoinchannel) ON_LBN_SELCHANGE(IDC_LIST_INFO_BROADCASTING, &CAgoraAudioVolumeDlg::OnSelchangeListInfoBroadcasting) ON_NOTIFY(NM_RELEASEDCAPTURE, IDC_SLIDER_CAP_VOLUME, &CAgoraAudioVolumeDlg::OnReleasedcaptureSliderCapVolume) @@ -321,6 +323,17 @@ LRESULT CAgoraAudioVolumeDlg::OnEIDActiveSpeaker(WPARAM wparam, LPARAM lparam) return TRUE; } +LRESULT CAgoraAudioVolumeDlg::OnEIDAudioVolumeTestIndication(WPARAM wparam, LPARAM lparam) +{ + CString strInfo; + strInfo.Format(_T("onAudioVolumeTestIndication")); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("type:%s"), wparam == AudioTestRecordingVolume? L"recording":L"playback"); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + strInfo.Format(_T("volume:%d"), lparam); + m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo); + return TRUE; +} //audio volume indication void CAudioVolumeEventHandler::onAudioVolumeIndication(const AudioVolumeInfo * speakers, unsigned int speakerNumber, int totalVolume) @@ -334,6 +347,12 @@ void CAudioVolumeEventHandler::onAudioVolumeIndication(const AudioVolumeInfo * s ::PostMessage(m_hMsgHanlder, WM_MSGID(EID_AUDIO_VOLUME_INDICATION), (WPARAM)p, 0); } +void CAudioVolumeEventHandler::onAudioDeviceTestVolumeIndication(AudioDeviceTestVolumeType volumeType, int volume) +{ + if (m_hMsgHanlder) + ::PostMessage(m_hMsgHanlder, WM_MSGID(EID_AUDIO_VOLUME_TEST_INDICATION), (WPARAM)volumeType, volume); +} + //active speaker void CAudioVolumeEventHandler::onActiveSpeaker(uid_t uid) { From 34a1e9734e269e2180c00c49cd41eb3d9482003e Mon Sep 17 00:00:00 2001 From: Arlin Date: Fri, 21 Jan 2022 18:00:52 +0800 Subject: [PATCH 10/21] add feature video enhancement and virtual background base on v3.6.2 macos --- macOS/APIExample.xcodeproj/project.pbxproj | 16 + .../VideoProcess/VideoProcess.storyboard | 229 +++++++++ .../Advanced/VideoProcess/VideoProcess.swift | 444 ++++++++++++++++++ .../Base.lproj/JoinChannelVideo.storyboard | 17 +- .../JoinChannelVideo/JoinChannelVideo.swift | 56 +-- macOS/APIExample/ViewController.swift | 3 +- .../zh-Hans.lproj/Localizable.strings | 11 +- 7 files changed, 705 insertions(+), 71 deletions(-) create mode 100644 macOS/APIExample/Examples/Advanced/VideoProcess/VideoProcess.storyboard create mode 100644 macOS/APIExample/Examples/Advanced/VideoProcess/VideoProcess.swift diff --git a/macOS/APIExample.xcodeproj/project.pbxproj b/macOS/APIExample.xcodeproj/project.pbxproj index 691d22a03..04fc8faf0 100644 --- a/macOS/APIExample.xcodeproj/project.pbxproj +++ b/macOS/APIExample.xcodeproj/project.pbxproj @@ -87,6 +87,8 @@ 57AF397B259B31AA00601E02 /* RawAudioData.swift in Sources */ = {isa = PBXBuildFile; fileRef = 57AF397A259B31AA00601E02 /* RawAudioData.swift */; }; 57AF3981259B329B00601E02 /* RawAudioData.storyboard in Resources */ = {isa = PBXBuildFile; fileRef = 57AF3980259B329B00601E02 /* RawAudioData.storyboard */; }; 596A9F79AF0CD8DC1CA93253 /* Pods_APIExample.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 6F65EF2B97B89DE4581B426B /* Pods_APIExample.framework */; }; + 67C3646427980E600080DB3A /* VideoProcess.swift in Sources */ = {isa = PBXBuildFile; fileRef = 67C3646327980E600080DB3A /* VideoProcess.swift */; }; + 67C3646A27993A580080DB3A /* VideoProcess.storyboard in Resources */ = {isa = PBXBuildFile; fileRef = 67C3646927993A580080DB3A /* VideoProcess.storyboard */; }; 8B6F4EAD276ECC370097E67E /* Localizable.strings in Resources */ = {isa = PBXBuildFile; fileRef = 8B6F4EAF276ECC370097E67E /* Localizable.strings */; }; 8B733B8C267B1C0B00CC3DE3 /* bg.jpg in Resources */ = {isa = PBXBuildFile; fileRef = 8B733B8B267B1C0B00CC3DE3 /* bg.jpg */; }; EBDD0209B272C276B21B6270 /* Pods_APIExample_APIExampleUITests.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = FC2BAB0AC82140B7CEEA31DA /* Pods_APIExample_APIExampleUITests.framework */; }; @@ -227,6 +229,8 @@ 57A635F32593544600EDC2F7 /* effectA.wav */ = {isa = PBXFileReference; lastKnownFileType = audio.wav; path = effectA.wav; sourceTree = ""; }; 57AF397A259B31AA00601E02 /* RawAudioData.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = RawAudioData.swift; sourceTree = ""; }; 57AF3980259B329B00601E02 /* RawAudioData.storyboard */ = {isa = PBXFileReference; lastKnownFileType = file.storyboard; path = RawAudioData.storyboard; sourceTree = ""; }; + 67C3646327980E600080DB3A /* VideoProcess.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = VideoProcess.swift; sourceTree = ""; }; + 67C3646927993A580080DB3A /* VideoProcess.storyboard */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = file.storyboard; path = VideoProcess.storyboard; sourceTree = ""; }; 6F65EF2B97B89DE4581B426B /* Pods_APIExample.framework */ = {isa = PBXFileReference; explicitFileType = wrapper.framework; includeInIndex = 0; path = Pods_APIExample.framework; sourceTree = BUILT_PRODUCTS_DIR; }; 84C863718A380DFD36ABF19F /* Pods-APIExample.debug.xcconfig */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = text.xcconfig; name = "Pods-APIExample.debug.xcconfig"; path = "Target Support Files/Pods-APIExample/Pods-APIExample.debug.xcconfig"; sourceTree = ""; }; 8B6F4EAE276ECC370097E67E /* zh-Hans */ = {isa = PBXFileReference; lastKnownFileType = text.plist.strings; name = "zh-Hans"; path = "zh-Hans.lproj/Localizable.strings"; sourceTree = ""; }; @@ -475,6 +479,7 @@ 036D3AA524FB797700B1D8DC /* Advanced */ = { isa = PBXGroup; children = ( + 67C3646227980E1F0080DB3A /* VideoProcess */, 57AF3979259B30BB00601E02 /* RawAudioData */, 576459FD259B1C22007B1E30 /* CreateDataStream */, 033A9F95252EA86A00BC26E1 /* CustomAudioRender */, @@ -639,6 +644,15 @@ path = RawAudioData; sourceTree = ""; }; + 67C3646227980E1F0080DB3A /* VideoProcess */ = { + isa = PBXGroup; + children = ( + 67C3646327980E600080DB3A /* VideoProcess.swift */, + 67C3646927993A580080DB3A /* VideoProcess.storyboard */, + ); + path = VideoProcess; + sourceTree = ""; + }; 72510F6AF209B24C1F66A819 /* Pods */ = { isa = PBXGroup; children = ( @@ -790,6 +804,7 @@ 033A9FBD252EB02600BC26E1 /* CustomAudioRender.storyboard in Resources */, 034C62A025297ABB00296ECF /* audioeffect.mp3 in Resources */, 03896D3424F8A011008593CD /* Assets.xcassets in Resources */, + 67C3646A27993A580080DB3A /* VideoProcess.storyboard in Resources */, 03896D3724F8A011008593CD /* Main.storyboard in Resources */, 033A9FE0252EB58600BC26E1 /* CustomVideoSourceMediaIO.storyboard in Resources */, 8B733B8C267B1C0B00CC3DE3 /* bg.jpg in Resources */, @@ -944,6 +959,7 @@ 034C629C25295F2800296ECF /* AudioMixing.swift in Sources */, 03267E222500C265004A91A6 /* AgoraMediaDataPlugin.mm in Sources */, 036D3AA224FAA00A00B1D8DC /* Configs.swift in Sources */, + 67C3646427980E600080DB3A /* VideoProcess.swift in Sources */, 03267E1C24FF3AF4004A91A6 /* AgoraCameraSourcePush.swift in Sources */, 034C626C25259FC200296ECF /* JoinChannelVideo.swift in Sources */, 033A9FA5252EA86A00BC26E1 /* RawMediaData.swift in Sources */, diff --git a/macOS/APIExample/Examples/Advanced/VideoProcess/VideoProcess.storyboard b/macOS/APIExample/Examples/Advanced/VideoProcess/VideoProcess.storyboard new file mode 100644 index 000000000..0bb772625 --- /dev/null +++ b/macOS/APIExample/Examples/Advanced/VideoProcess/VideoProcess.storyboard @@ -0,0 +1,229 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/macOS/APIExample/Examples/Advanced/VideoProcess/VideoProcess.swift b/macOS/APIExample/Examples/Advanced/VideoProcess/VideoProcess.swift new file mode 100644 index 000000000..48b894707 --- /dev/null +++ b/macOS/APIExample/Examples/Advanced/VideoProcess/VideoProcess.swift @@ -0,0 +1,444 @@ +// +// VideoProcess.swift +// APIExample +// +// Created by Arlin on 2022/1/19. +// Copyright © 2022 Agora Corp. All rights reserved. +// + +import Cocoa +import AgoraRtcKit +import AGEVideoLayout + +class VideoProcess: BaseViewController { + + @IBOutlet weak var Container: AGEVideoContainer! + @IBOutlet weak var selectResolutionPicker: Picker! + @IBOutlet weak var selectFpsPicker: Picker! + @IBOutlet weak var selectLayoutPicker: Picker! + @IBOutlet weak var virtualBackgroundSwitch: NSSwitch! + @IBOutlet weak var selectVirtualBackgroundPicker: Picker! + @IBOutlet weak var channelField: Input! + @IBOutlet weak var joinChannelButton: NSButton! + @IBOutlet weak var colorEnhanceSwitch: NSSwitch! + + @IBOutlet weak var lowlightEnhanceLabel: NSTextField! + @IBOutlet weak var videoDenoiseLabel: NSTextField! + @IBOutlet weak var colorEnhanceLabel: NSTextField! + @IBOutlet weak var strenghtLabel: NSTextField! + @IBOutlet weak var skinProtectLabel: NSTextField! + + var videos: [VideoView] = [] + let layouts = [Layout("1v1", 2), Layout("1v3", 4), Layout("1v8", 9), Layout("1v15", 16)] + let backgroundTypes = AgoraVirtualBackgroundSourceType.allValues() + var agoraKit: AgoraRtcEngineKit! + var colorEnhanceOptions = AgoraColorEnhanceOptions() + + // indicate if current instance has joined channel + var isJoined: Bool = false { + didSet { + channelField.isEnabled = !isJoined + selectLayoutPicker.isEnabled = !isJoined + joinChannelButton.title = isJoined ? "Leave Channel".localized : "Join Channel".localized + } + } + + // MARK: - LifeCycle + override func viewDidLoad() { + super.viewDidLoad() + self.setupUI() + self.setupAgoraKit() + } + + func setupAgoraKit() { + let config = AgoraRtcEngineConfig() + config.appId = KeyCenter.AppId + config.areaCode = GlobalSettings.shared.area.rawValue + agoraKit = AgoraRtcEngineKit.sharedEngine(with: config, delegate: self) + + agoraKit.setChannelProfile(.liveBroadcasting) + agoraKit.setClientRole(.broadcaster) + + agoraKit.enableVideo() + } + + override func viewWillBeRemovedFromSplitView() { + if isJoined { + agoraKit.disableVideo() + agoraKit.leaveChannel { (stats:AgoraChannelStats) in + LogUtils.log(message: "Left channel", level: .info) + } + } + AgoraRtcEngineKit.destroy() + } + + // MARK: - UI + func setupUI() { + channelField.label.stringValue = "Channel".localized + channelField.field.placeholderString = "Channel Name".localized + joinChannelButton.title = isJoined ? "Leave Channel".localized : "Join Channel".localized + lowlightEnhanceLabel.stringValue = "Low light Enhancement".localized + videoDenoiseLabel.stringValue = "Video Denoise".localized + colorEnhanceLabel.stringValue = "Color Enhancement".localized + strenghtLabel.stringValue = "Strength".localized + skinProtectLabel.stringValue = "Skin Protect".localized + + initSelectResolutionPicker() + initSelectFpsPicker() + initSelectLayoutPicker() + initSelectBackgroundPicker() + } + + @IBAction func onJoinButtonPressed(_ sender: NSButton) { + if !isJoined { + let channel = channelField.stringValue + guard !channel.isEmpty, + let resolution = selectedResolution(), + let fps = selectedFps() else { + return + } + + agoraKit.setVideoEncoderConfiguration( + AgoraVideoEncoderConfiguration( + size: resolution.size(), + frameRate: AgoraVideoFrameRate(rawValue: fps) ?? .fps15, + bitrate: AgoraVideoBitrateStandard, + orientationMode: .adaptative + ) + ) + + // set up local video to render your local camera preview + let localVideo = videos[0] + let videoCanvas = AgoraRtcVideoCanvas() + videoCanvas.uid = 0 + // the view to be binded + videoCanvas.view = localVideo.videocanvas + videoCanvas.renderMode = .hidden + agoraKit.setupLocalVideo(videoCanvas) + + setVirtualBackground() + + // start joining channel + // 1. Users can only see each other after they join the + // same channel successfully using the same app id. + // 2. If app certificate is turned on at dashboard, token is needed + // when joining channel. The channel name and uid used to calculate + // the token has to match the ones used for channel join + let option = AgoraRtcChannelMediaOptions() + let result = agoraKit.joinChannel(byToken: KeyCenter.Token, channelId: channel, info: nil, uid: 0, options: option) + if result != 0 { + // Usually happens with invalid parameters + // Error code description can be found at: + // en: https://docs.agora.io/en/Voice/API%20Reference/oc/Constants/AgoraErrorCode.html + // cn: https://docs.agora.io/cn/Voice/API%20Reference/oc/Constants/AgoraErrorCode.html + self.showAlert(title: "Error", message: "joinChannel call failed: \(result), please check your params") + } + } else { + agoraKit.leaveChannel { (stats:AgoraChannelStats) in + LogUtils.log(message: "Left channel", level: .info) + self.videos[0].uid = nil + self.isJoined = false + self.videos.forEach { + $0.uid = nil + $0.statsLabel.stringValue = "" + } + } + } + } + + @IBAction func onLowLightEnhanceSwitchChange(_ sender: NSSwitch) { + agoraKit.setLowlightEnhanceOptions(sender.state.rawValue != 0, options: nil) + } + + @IBAction func onVideoDenoiseSwitchChange(_ sender: NSSwitch) { + agoraKit.setVideoDenoiserOptions(sender.state.rawValue != 0, options: nil) + } + + @IBAction func onColorEnhanceSwitchChange(_ sender: NSSwitch) { + agoraKit.setColorEnhanceOptions(colorEnhanceSwitch.state.rawValue != 0, options: colorEnhanceOptions) + } + + @IBAction func onStrengthSliderChange(_ sender: NSSlider) { + colorEnhanceOptions.strengthLevel = sender.floatValue + agoraKit.setColorEnhanceOptions(colorEnhanceSwitch.state.rawValue != 0, options: colorEnhanceOptions) + } + + @IBAction func onSkinProtectSliderChange(_ sender: NSSlider) { + colorEnhanceOptions.skinProtectLevel = sender.floatValue + agoraKit.setColorEnhanceOptions(colorEnhanceSwitch.state.rawValue != 0, options: colorEnhanceOptions) + } + + @IBAction func onVirtualBackgroundSwitchChange(_ sender: NSSwitch) { + setVirtualBackground() + } + + func setVirtualBackground(){ + let backgroundSource = AgoraVirtualBackgroundSource() + backgroundSource.backgroundSourceType = selectedBackgroundType() ?? .img + switch backgroundSource.backgroundSourceType { + case .color: + backgroundSource.color = 0xFFFFFF + break + case .img: + if let resourcePath = Bundle.main.resourcePath { + let imgPath = resourcePath + "/" + "bg.jpg" + backgroundSource.source = imgPath + } + break + case .blur: + backgroundSource.blur_degree = .high + break + default: + break + } + agoraKit.enableVirtualBackground(virtualBackgroundSwitch.state.rawValue != 0, backData: backgroundSource) + } + + func initSelectBackgroundPicker() { + selectVirtualBackgroundPicker.label.stringValue = "Virtual Background".localized + selectVirtualBackgroundPicker.picker.addItems(withTitles: backgroundTypes.map { $0.description() }) + + selectVirtualBackgroundPicker.onSelectChanged { + guard self.selectedBackgroundType() != nil else { return } + self.setVirtualBackground() + } + } + + func selectedBackgroundType() ->AgoraVirtualBackgroundSourceType? { + let index = selectVirtualBackgroundPicker.indexOfSelectedItem + if index >= 0 && index < backgroundTypes.count { + return backgroundTypes[index] + } else { + return nil + } + } + + // MARK: Vedio Setting + func initSelectResolutionPicker() { + selectResolutionPicker.label.stringValue = "Resolution".localized + selectResolutionPicker.picker.addItems(withTitles: Configs.Resolutions.map { $0.name() }) + selectResolutionPicker.picker.selectItem(at: GlobalSettings.shared.resolutionSetting.selectedOption().value) + + selectResolutionPicker.onSelectChanged { + if !self.isJoined { + return + } + + guard let resolution = self.selectedResolution(), + let fps = self.selectedFps() else { + return + } + self.agoraKit.setVideoEncoderConfiguration( + AgoraVideoEncoderConfiguration( + size: resolution.size(), + frameRate: AgoraVideoFrameRate(rawValue: fps) ?? .fps15, + bitrate: AgoraVideoBitrateStandard, + orientationMode: .adaptative + ) + ) + } + } + + func selectedResolution() -> Resolution? { + let index = self.selectResolutionPicker.indexOfSelectedItem + if index >= 0 && index < Configs.Resolutions.count { + return Configs.Resolutions[index] + } else { + return nil + } + } + + func initSelectFpsPicker() { + selectFpsPicker.label.stringValue = "Frame Rate".localized + selectFpsPicker.picker.addItems(withTitles: Configs.Fps.map { "\($0)fps" }) + selectFpsPicker.picker.selectItem(at: GlobalSettings.shared.fpsSetting.selectedOption().value) + + selectFpsPicker.onSelectChanged { + if !self.isJoined { + return + } + + guard let resolution = self.selectedResolution(), + let fps = self.selectedFps() else { + return + } + self.agoraKit.setVideoEncoderConfiguration( + AgoraVideoEncoderConfiguration( + size: resolution.size(), + frameRate: AgoraVideoFrameRate(rawValue: fps) ?? .fps15, + bitrate: AgoraVideoBitrateStandard, + orientationMode: .adaptative + ) + ) + } + } + + func selectedFps() -> Int? { + let index = self.selectFpsPicker.indexOfSelectedItem + if index >= 0 && index < Configs.Fps.count { + return Configs.Fps[index] + } else { + return nil + } + } + + func initSelectLayoutPicker() { + layoutVideos(2) + selectLayoutPicker.label.stringValue = "Layout".localized + selectLayoutPicker.picker.addItems(withTitles: layouts.map { $0.label }) + selectLayoutPicker.onSelectChanged { + if self.isJoined { + return + } + guard let layout = self.selectedLayout() else { return } + self.layoutVideos(layout.value) + } + } + + func selectedLayout() ->Layout? { + let index = self.selectLayoutPicker.indexOfSelectedItem + if index >= 0 && index < layouts.count { + return layouts[index] + } else { + return nil + } + } + + func layoutVideos(_ count: Int) { + videos = [] + for i in 0...count - 1 { + let view = VideoView.createFromNib()! + if(i == 0) { + view.placeholder.stringValue = "Local" + view.type = .local + view.statsInfo = StatisticsInfo(type: .local(StatisticsInfo.LocalInfo())) + } else { + view.placeholder.stringValue = "Remote \(i)" + view.type = .remote + view.statsInfo = StatisticsInfo(type: .remote(StatisticsInfo.RemoteInfo())) + } + videos.append(view) + } + // layout render view + Container.layoutStream(views: videos) + } +} + +/// agora rtc engine delegate events +extension VideoProcess: AgoraRtcEngineDelegate { + /// callback when warning occured for agora sdk, warning can usually be ignored, still it's nice to check out + /// what is happening + /// Warning code description can be found at: + /// en: https://docs.agora.io/en/Voice/API%20Reference/oc/Constants/AgoraWarningCode.html + /// cn: https://docs.agora.io/cn/Voice/API%20Reference/oc/Constants/AgoraWarningCode.html + /// @param warningCode warning code of the problem + func rtcEngine(_ engine: AgoraRtcEngineKit, didOccurWarning warningCode: AgoraWarningCode) { + LogUtils.log(message: "warning: \(warningCode.rawValue)", level: .warning) + } + + /// callback when error occured for agora sdk, you are recommended to display the error descriptions on demand + /// to let user know something wrong is happening + /// Error code description can be found at: + /// en: https://docs.agora.io/en/Voice/API%20Reference/oc/Constants/AgoraErrorCode.html + /// cn: https://docs.agora.io/cn/Voice/API%20Reference/oc/Constants/AgoraErrorCode.html + /// @param errorCode error code of the problem + func rtcEngine(_ engine: AgoraRtcEngineKit, didOccurError errorCode: AgoraErrorCode) { + LogUtils.log(message: "error: \(errorCode)", level: .error) + self.showAlert(title: "Error", message: "Error \(errorCode.rawValue) occur") + } + + /// callback when the local user joins a specified channel. + /// @param channel + /// @param uid uid of local user + /// @param elapsed time elapse since current sdk instance join the channel in ms + func rtcEngine(_ engine: AgoraRtcEngineKit, didJoinChannel channel: String, withUid uid: UInt, elapsed: Int) { + isJoined = true + let localVideo = videos[0] + localVideo.uid = uid + LogUtils.log(message: "Join \(channel) with uid \(uid) elapsed \(elapsed)ms", level: .info) + } + + /// callback when a remote user is joinning the channel, note audience in live broadcast mode will NOT trigger this event + /// @param uid uid of remote joined user + /// @param elapsed time elapse since current sdk instance join the channel in ms + func rtcEngine(_ engine: AgoraRtcEngineKit, didJoinedOfUid uid: UInt, elapsed: Int) { + LogUtils.log(message: "remote user join: \(uid) \(elapsed)ms", level: .info) + + // find a VideoView w/o uid assigned + if let remoteVideo = videos.first(where: { $0.uid == nil }) { + let videoCanvas = AgoraRtcVideoCanvas() + videoCanvas.uid = uid + // the view to be binded + videoCanvas.view = remoteVideo.videocanvas + videoCanvas.renderMode = .hidden + agoraKit.setupRemoteVideo(videoCanvas) + remoteVideo.uid = uid + } else { + LogUtils.log(message: "no video canvas available for \(uid), cancel bind", level: .warning) + } + } + + /// callback when a remote user is leaving the channel, note audience in live broadcast mode will NOT trigger this event + /// @param uid uid of remote joined user + /// @param reason reason why this user left, note this event may be triggered when the remote user + /// become an audience in live broadcasting profile + func rtcEngine(_ engine: AgoraRtcEngineKit, didOfflineOfUid uid: UInt, reason: AgoraUserOfflineReason) { + LogUtils.log(message: "remote user left: \(uid) reason \(reason)", level: .info) + + // to unlink your view from sdk, so that your view reference will be released + // note the video will stay at its last frame, to completely remove it + // you will need to remove the EAGL sublayer from your binded view + if let remoteVideo = videos.first(where: { $0.uid == uid }) { + let videoCanvas = AgoraRtcVideoCanvas() + videoCanvas.uid = uid + // the view to be binded + videoCanvas.view = nil + videoCanvas.renderMode = .hidden + agoraKit.setupRemoteVideo(videoCanvas) + remoteVideo.uid = nil + } else { + LogUtils.log(message: "no matching video canvas for \(uid), cancel unbind", level: .warning) + } + } + + /// Reports the statistics of the current call. The SDK triggers this callback once every two seconds after the user joins the channel. + /// @param stats stats struct + func rtcEngine(_ engine: AgoraRtcEngineKit, reportRtcStats stats: AgoraChannelStats) { + videos[0].statsInfo?.updateChannelStats(stats) + } + + /// Reports the statistics of the uploading local video streams once every two seconds. + /// @param stats stats struct + func rtcEngine(_ engine: AgoraRtcEngineKit, localVideoStats stats: AgoraRtcLocalVideoStats) { + videos[0].statsInfo?.updateLocalVideoStats(stats) + } + + /// Reports the statistics of the uploading local audio streams once every two seconds. + /// @param stats stats struct + func rtcEngine(_ engine: AgoraRtcEngineKit, localAudioStats stats: AgoraRtcLocalAudioStats) { + videos[0].statsInfo?.updateLocalAudioStats(stats) + } + + /// Reports the statistics of the video stream from each remote user/host. + /// @param stats stats struct + func rtcEngine(_ engine: AgoraRtcEngineKit, remoteVideoStats stats: AgoraRtcRemoteVideoStats) { + videos.first(where: { $0.uid == stats.uid })?.statsInfo?.updateVideoStats(stats) + } + + /// Reports the statistics of the audio stream from each remote user/host. + /// @param stats stats struct for current call statistics + func rtcEngine(_ engine: AgoraRtcEngineKit, remoteAudioStats stats: AgoraRtcRemoteAudioStats) { + videos.first(where: { $0.uid == stats.uid })?.statsInfo?.updateAudioStats(stats) + } + + /// Reports the video background substitution success or failed. + /// @param enabled whether background substitution is enabled. + /// @param reason The reason of the background substitution callback. See [AgoraVideoBackgroundSourceStateReason](AgoraVideoBackgroundSourceStateReason). + + func rtcEngine(_ engine: AgoraRtcEngineKit, virtualBackgroundSourceEnabled enabled: Bool, reason: AgoraVirtualBackgroundSourceStateReason) { + if reason != .vbsStateReasonSuccess { + LogUtils.log(message: "background substitution failed to enabled for \(reason.rawValue)", level: .warning) + } + } +} + diff --git a/macOS/APIExample/Examples/Basic/JoinChannelVideo/Base.lproj/JoinChannelVideo.storyboard b/macOS/APIExample/Examples/Basic/JoinChannelVideo/Base.lproj/JoinChannelVideo.storyboard index 9ff1bbc31..383683219 100644 --- a/macOS/APIExample/Examples/Basic/JoinChannelVideo/Base.lproj/JoinChannelVideo.storyboard +++ b/macOS/APIExample/Examples/Basic/JoinChannelVideo/Base.lproj/JoinChannelVideo.storyboard @@ -1,8 +1,8 @@ - + - + @@ -52,21 +52,10 @@ - - - - - - - - - - - @@ -137,14 +126,12 @@ - - diff --git a/macOS/APIExample/Examples/Basic/JoinChannelVideo/JoinChannelVideo.swift b/macOS/APIExample/Examples/Basic/JoinChannelVideo/JoinChannelVideo.swift index 3ed6c67be..6a5a5c1eb 100644 --- a/macOS/APIExample/Examples/Basic/JoinChannelVideo/JoinChannelVideo.swift +++ b/macOS/APIExample/Examples/Basic/JoinChannelVideo/JoinChannelVideo.swift @@ -15,10 +15,7 @@ class JoinChannelVideoMain: BaseViewController { var videos: [VideoView] = [] @IBOutlet weak var Container: AGEVideoContainer! - - var isVirtualBackgroundEnabled: Bool = false - @IBOutlet weak var virtualBackgroundSwitch: NSSwitch! - + /** --- Cameras Picker --- */ @@ -220,29 +217,7 @@ class JoinChannelVideoMain: BaseViewController { } } } - - /** - --- Background Picker --- - */ - @IBOutlet weak var selectBackgroundPicker: Picker! - private let backgroundTypes = AgoraVirtualBackgroundSourceType.allValues() - var selectedBackgroundType: AgoraVirtualBackgroundSourceType? { - let index = self.selectBackgroundPicker.indexOfSelectedItem - if index >= 0 && index < backgroundTypes.count { - return backgroundTypes[index] - } else { - return nil - } - } - func initSelectBackgroundPicker() { - selectBackgroundPicker.label.stringValue = "Virtual Background".localized - selectBackgroundPicker.picker.addItems(withTitles: backgroundTypes.map { $0.description() }) - selectBackgroundPicker.onSelectChanged { - guard self.selectedBackgroundType != nil else { return } - self.setBackground() - } - } - + /** --- Channel TextField --- */ @@ -284,36 +259,16 @@ class JoinChannelVideoMain: BaseViewController { config.areaCode = GlobalSettings.shared.area.rawValue agoraKit = AgoraRtcEngineKit.sharedEngine(with: config, delegate: self) agoraKit.enableVideo() - setBackground() initSelectCameraPicker() initSelectResolutionPicker() initSelectFpsPicker() initSelectMicsPicker() initSelectLayoutPicker() initSelectRolePicker() - initSelectBackgroundPicker() initChannelField() initJoinChannelButton() } - - private func setBackground(){ - let backgroundSource = AgoraVirtualBackgroundSource() - backgroundSource.backgroundSourceType = selectedBackgroundType ?? .img - switch self.selectedBackgroundType { - case .color: - backgroundSource.color = 0x000000 - case .img: - if let resourcePath = Bundle.main.resourcePath { - let imgName = "bg.jpg" - let path = resourcePath + "/" + imgName - backgroundSource.source = path - } - default: - break - } - agoraKit.enableVirtualBackground(isVirtualBackgroundEnabled, backData: backgroundSource) - } - + func layoutVideos(_ count: Int) { videos = [] for i in 0...count - 1 { @@ -333,11 +288,6 @@ class JoinChannelVideoMain: BaseViewController { Container.layoutStream(views: videos) } - @IBAction func onSwitchVirtualBackground(_ sender: NSSwitch) { - isVirtualBackgroundEnabled = (sender.state.rawValue != 0) - setBackground() - } - @IBAction func onVideoCallButtonPressed(_ sender: NSButton) { if !isJoined { // check configuration diff --git a/macOS/APIExample/ViewController.swift b/macOS/APIExample/ViewController.swift index d57fbdea3..2290ab6b5 100644 --- a/macOS/APIExample/ViewController.swift +++ b/macOS/APIExample/ViewController.swift @@ -39,7 +39,8 @@ class MenuController: NSViewController { MenuItem(name: "Voice Changer".localized, identifier: "menuCell", controller: "VoiceChanger", storyboard: "VoiceChanger"), MenuItem(name: "Create Data Stream".localized, identifier: "menuCell", controller: "CreateDataStream", storyboard: "CreateDataStream"), MenuItem(name: "Raw Audio Data".localized, identifier: "menuCell", controller: "RawAudioData", storyboard: "RawAudioData"), - MenuItem(name: "Precall Test".localized, identifier: "menuCell", controller: "PrecallTest", storyboard: "PrecallTest") + MenuItem(name: "Precall Test".localized, identifier: "menuCell", controller: "PrecallTest", storyboard: "PrecallTest"), + MenuItem(name: "Video Process".localized, identifier: "menuCell", controller: "Video Process", storyboard: "VideoProcess") ] @IBOutlet weak var tableView:NSTableView! diff --git a/macOS/APIExample/zh-Hans.lproj/Localizable.strings b/macOS/APIExample/zh-Hans.lproj/Localizable.strings index b52135e82..2b1774163 100644 --- a/macOS/APIExample/zh-Hans.lproj/Localizable.strings +++ b/macOS/APIExample/zh-Hans.lproj/Localizable.strings @@ -158,9 +158,16 @@ "Video Source" = "视频源选择"; "Sending" = "发送中"; "None" = "无背景"; +"Start Video/Audio Echo Test" = "开始音视频回路测试"; +"Stop Video/Audio Echo Test" = "停止音视频回路测试"; +"Video Process" = "视频增强"; +"Low light Enhancement" = "暗光增强"; +"Video Denoise" = "视频降噪"; +"Color Enhancement" = "色彩增强"; +"Strength" = "强度"; +"Skin Protect" = "肤色保护"; "Colored Background" = "纯色背景"; "Image Background" = "图片背景"; "Virtual Background" = "虚拟背景"; "Blur Background" = "背景虚化"; -"Start Video/Audio Echo Test" = "开始音视频回路测试"; -"Stop Video/Audio Echo Test" = "停止音视频回路测试"; + From 788a59ffe7032000f28c76523ac0436768960df8 Mon Sep 17 00:00:00 2001 From: Arlin Date: Fri, 28 Jan 2022 09:59:04 +0800 Subject: [PATCH 11/21] [Bug] : remove Thread sleep on change splitview and fix unowned object crash --- .../Examples/Advanced/AudioMixing/AudioMixing.swift | 2 +- .../Advanced/CustomAudioRender/CustomAudioRender.swift | 2 +- .../Advanced/CustomAudioSource/CustomAudioSource.swift | 2 +- .../Examples/Advanced/PrecallTest/PrecallTest.swift | 7 ++++--- .../Examples/Advanced/RawAudioData/RawAudioData.swift | 2 +- .../Examples/Advanced/VoiceChanger/VoiceChanger.swift | 2 +- .../Examples/Basic/JoinChannelAudio/JoinChannelAudio.swift | 2 +- .../Examples/Basic/JoinChannelVideo/JoinChannelVideo.swift | 6 +++--- macOS/APIExample/ViewController.swift | 1 - 9 files changed, 13 insertions(+), 13 deletions(-) diff --git a/macOS/APIExample/Examples/Advanced/AudioMixing/AudioMixing.swift b/macOS/APIExample/Examples/Advanced/AudioMixing/AudioMixing.swift index b1551d603..9c0630aab 100644 --- a/macOS/APIExample/Examples/Advanced/AudioMixing/AudioMixing.swift +++ b/macOS/APIExample/Examples/Advanced/AudioMixing/AudioMixing.swift @@ -91,7 +91,7 @@ class AudioMixing: BaseViewController { @IBOutlet weak var selectMicsPicker: Picker! var mics:[AgoraRtcDeviceInfo] = [] { didSet { - DispatchQueue.main.async {[unowned self] in + DispatchQueue.main.async { self.selectMicsPicker.picker.addItems(withTitles: self.mics.map {$0.deviceName ?? "unknown"}) } } diff --git a/macOS/APIExample/Examples/Advanced/CustomAudioRender/CustomAudioRender.swift b/macOS/APIExample/Examples/Advanced/CustomAudioRender/CustomAudioRender.swift index 5479f782c..cdc53e4e0 100644 --- a/macOS/APIExample/Examples/Advanced/CustomAudioRender/CustomAudioRender.swift +++ b/macOS/APIExample/Examples/Advanced/CustomAudioRender/CustomAudioRender.swift @@ -23,7 +23,7 @@ class CustomAudioRender: BaseViewController { @IBOutlet weak var selectMicsPicker: Picker! var mics: [AgoraRtcDeviceInfo] = [] { didSet { - DispatchQueue.main.async {[unowned self] in + DispatchQueue.main.async { self.selectMicsPicker.picker.addItems(withTitles: self.mics.map {$0.deviceName ?? "unknown"}) } } diff --git a/macOS/APIExample/Examples/Advanced/CustomAudioSource/CustomAudioSource.swift b/macOS/APIExample/Examples/Advanced/CustomAudioSource/CustomAudioSource.swift index 02c4cdf8a..5e094a599 100644 --- a/macOS/APIExample/Examples/Advanced/CustomAudioSource/CustomAudioSource.swift +++ b/macOS/APIExample/Examples/Advanced/CustomAudioSource/CustomAudioSource.swift @@ -22,7 +22,7 @@ class CustomAudioSource: BaseViewController { @IBOutlet weak var selectMicsPicker: Picker! var mics: [AgoraRtcDeviceInfo] = [] { didSet { - DispatchQueue.main.async {[unowned self] in + DispatchQueue.main.async { self.selectMicsPicker.picker.addItems(withTitles: self.mics.map {$0.deviceName ?? "unknown"}) } } diff --git a/macOS/APIExample/Examples/Advanced/PrecallTest/PrecallTest.swift b/macOS/APIExample/Examples/Advanced/PrecallTest/PrecallTest.swift index 1dd491038..4ed062e88 100644 --- a/macOS/APIExample/Examples/Advanced/PrecallTest/PrecallTest.swift +++ b/macOS/APIExample/Examples/Advanced/PrecallTest/PrecallTest.swift @@ -37,7 +37,7 @@ class PrecallTest: BaseViewController { @IBOutlet weak var echoValidatePopover: NSView! var cameras:[AgoraRtcDeviceInfo] = [] { didSet { - DispatchQueue.main.async {[unowned self] in + DispatchQueue.main.async { self.cameraPicker.addItems(withTitles: self.cameras.map({ (device: AgoraRtcDeviceInfo) -> String in return (device.deviceName ?? "") })) @@ -46,7 +46,7 @@ class PrecallTest: BaseViewController { } var mics:[AgoraRtcDeviceInfo] = [] { didSet { - DispatchQueue.main.async {[unowned self] in + DispatchQueue.main.async { self.micPicker.addItems(withTitles: self.mics.map({ (device: AgoraRtcDeviceInfo) -> String in return (device.deviceName ?? "") })) @@ -55,7 +55,7 @@ class PrecallTest: BaseViewController { } var speakers:[AgoraRtcDeviceInfo] = [] { didSet { - DispatchQueue.main.async {[unowned self] in + DispatchQueue.main.async { self.speakerPicker.addItems(withTitles: self.speakers.map({ (device: AgoraRtcDeviceInfo) -> String in return (device.deviceName ?? "") })) @@ -303,6 +303,7 @@ extension PrecallTest: AgoraRtcEngineDelegate { /// @params totalVolume Total volume after audio mixing. The value range is [0,255]. func rtcEngine(_ engine: AgoraRtcEngineKit, reportAudioVolumeIndicationOfSpeakers speakers: [AgoraRtcAudioVolumeInfo], totalVolume: Int) { for speaker in speakers { + print("reportAudioVolumeIndicationOfSpeakers:\(speaker.uid), \(speaker.volume)") if(speaker.uid == 0) { micTestingVolumeIndicator.doubleValue = Double(speaker.volume) } diff --git a/macOS/APIExample/Examples/Advanced/RawAudioData/RawAudioData.swift b/macOS/APIExample/Examples/Advanced/RawAudioData/RawAudioData.swift index f72bb4016..8e9754189 100644 --- a/macOS/APIExample/Examples/Advanced/RawAudioData/RawAudioData.swift +++ b/macOS/APIExample/Examples/Advanced/RawAudioData/RawAudioData.swift @@ -23,7 +23,7 @@ class RawAudioData: BaseViewController { @IBOutlet weak var selectMicsPicker: Picker! var mics: [AgoraRtcDeviceInfo] = [] { didSet { - DispatchQueue.main.async {[unowned self] in + DispatchQueue.main.async { self.selectMicsPicker.picker.addItems(withTitles: self.mics.map {$0.deviceName ?? "unknown"}) } } diff --git a/macOS/APIExample/Examples/Advanced/VoiceChanger/VoiceChanger.swift b/macOS/APIExample/Examples/Advanced/VoiceChanger/VoiceChanger.swift index 30e3896aa..954b860dd 100644 --- a/macOS/APIExample/Examples/Advanced/VoiceChanger/VoiceChanger.swift +++ b/macOS/APIExample/Examples/Advanced/VoiceChanger/VoiceChanger.swift @@ -57,7 +57,7 @@ class VoiceChanger: BaseViewController { @IBOutlet weak var selectMicsPicker: Picker! var mics:[AgoraRtcDeviceInfo] = [] { didSet { - DispatchQueue.main.async {[unowned self] in + DispatchQueue.main.async { self.selectMicsPicker.picker.addItems(withTitles: self.mics.map {$0.deviceName ?? "unknown"}) } } diff --git a/macOS/APIExample/Examples/Basic/JoinChannelAudio/JoinChannelAudio.swift b/macOS/APIExample/Examples/Basic/JoinChannelAudio/JoinChannelAudio.swift index 10613f478..6f7853644 100644 --- a/macOS/APIExample/Examples/Basic/JoinChannelAudio/JoinChannelAudio.swift +++ b/macOS/APIExample/Examples/Basic/JoinChannelAudio/JoinChannelAudio.swift @@ -79,7 +79,7 @@ class JoinChannelAudioMain: BaseViewController { @IBOutlet weak var selectMicsPicker: Picker! var mics:[AgoraRtcDeviceInfo] = [] { didSet { - DispatchQueue.main.async {[unowned self] in + DispatchQueue.main.async { self.selectMicsPicker.picker.addItems(withTitles: self.mics.map {$0.deviceName ?? "unknown"}) } } diff --git a/macOS/APIExample/Examples/Basic/JoinChannelVideo/JoinChannelVideo.swift b/macOS/APIExample/Examples/Basic/JoinChannelVideo/JoinChannelVideo.swift index 6a5a5c1eb..5feda8e3c 100644 --- a/macOS/APIExample/Examples/Basic/JoinChannelVideo/JoinChannelVideo.swift +++ b/macOS/APIExample/Examples/Basic/JoinChannelVideo/JoinChannelVideo.swift @@ -22,7 +22,7 @@ class JoinChannelVideoMain: BaseViewController { @IBOutlet weak var selectCameraPicker: Picker! var cameras: [AgoraRtcDeviceInfo] = [] { didSet { - DispatchQueue.main.async {[unowned self] in + DispatchQueue.main.async { self.selectCameraPicker.picker.addItems(withTitles: self.cameras.map {$0.deviceName ?? "unknown"}) } } @@ -135,7 +135,7 @@ class JoinChannelVideoMain: BaseViewController { @IBOutlet weak var selectMicsPicker: Picker! var mics: [AgoraRtcDeviceInfo] = [] { didSet { - DispatchQueue.main.async {[unowned self] in + DispatchQueue.main.async { self.selectMicsPicker.picker.addItems(withTitles: self.mics.map {$0.deviceName ?? "unknown"}) } } @@ -268,7 +268,7 @@ class JoinChannelVideoMain: BaseViewController { initChannelField() initJoinChannelButton() } - + func layoutVideos(_ count: Int) { videos = [] for i in 0...count - 1 { diff --git a/macOS/APIExample/ViewController.swift b/macOS/APIExample/ViewController.swift index 2290ab6b5..328e2ef9d 100644 --- a/macOS/APIExample/ViewController.swift +++ b/macOS/APIExample/ViewController.swift @@ -110,7 +110,6 @@ extension MenuController: NSTableViewDataSource, NSTableViewDelegate { func tableViewSelectionDidChange(_ notification: Notification) { if tableView.selectedRow >= 0 && tableView.selectedRow < menus.count { - Thread.sleep(forTimeInterval: 1) loadSplitViewItem(item: menus[tableView.selectedRow]) } } From dc4e051343118cf641a9f4c03724717422ed5d65 Mon Sep 17 00:00:00 2001 From: Arlin Date: Fri, 28 Jan 2022 14:56:57 +0800 Subject: [PATCH 12/21] import video process slider and adapt new api on v3.6.2 ios --- .../JoinMultiChannel/JoinMultiChannel.swift | 8 ++--- .../RTMPStreaming/RTMPStreaming.swift | 2 +- .../Base.lproj/VideoProcess.storyboard | 6 ++++ .../Advanced/VideoProcess/VideoProcess.swift | 33 +++++++++++++++---- 4 files changed, 38 insertions(+), 11 deletions(-) diff --git a/iOS/APIExample/Examples/Advanced/JoinMultiChannel/JoinMultiChannel.swift b/iOS/APIExample/Examples/Advanced/JoinMultiChannel/JoinMultiChannel.swift index 635510bd2..e772d0bdb 100644 --- a/iOS/APIExample/Examples/Advanced/JoinMultiChannel/JoinMultiChannel.swift +++ b/iOS/APIExample/Examples/Advanced/JoinMultiChannel/JoinMultiChannel.swift @@ -184,7 +184,7 @@ extension JoinMultiChannelMain: AgoraRtcEngineDelegate { extension JoinMultiChannelMain: AgoraRtcChannelDelegate { func rtcChannelDidJoin(_ rtcChannel: AgoraRtcChannel, withUid uid: UInt, elapsed: Int) { - LogUtils.log(message: "Join \(rtcChannel.getId() ?? "") with uid \(uid) elapsed \(elapsed)ms", level: .info) + LogUtils.log(message: "Join \(rtcChannel.getChannelId() ?? "") with uid \(uid) elapsed \(elapsed)ms", level: .info) } /// callback when warning occured for a channel, warning can usually be ignored, still it's nice to check out /// what is happening @@ -193,7 +193,7 @@ extension JoinMultiChannelMain: AgoraRtcChannelDelegate /// cn: https://docs.agora.io/cn/Voice/API%20Reference/oc/Constants/AgoraWarningCode.html /// @param warningCode warning code of the problem func rtcChannel(_ rtcChannel: AgoraRtcChannel, didOccurWarning warningCode: AgoraWarningCode) { - LogUtils.log(message: "channel: \(rtcChannel.getId() ?? ""), warning: \(warningCode.description)", level: .warning) + LogUtils.log(message: "channel: \(rtcChannel.getChannelId() ?? ""), warning: \(warningCode.description)", level: .warning) } /// callback when error occured for a channel, you are recommended to display the error descriptions on demand @@ -222,7 +222,7 @@ extension JoinMultiChannelMain: AgoraRtcChannelDelegate videoCanvas.view = channel1 == rtcChannel ? channel1RemoteVideo.videoView : channel2RemoteVideo.videoView videoCanvas.renderMode = .hidden // set channelId so that it knows which channel the video belongs to - videoCanvas.channelId = rtcChannel.getId() + videoCanvas.channelId = rtcChannel.getChannelId() agoraKit.setupRemoteVideo(videoCanvas) } @@ -242,7 +242,7 @@ extension JoinMultiChannelMain: AgoraRtcChannelDelegate videoCanvas.view = nil videoCanvas.renderMode = .hidden // set channelId so that it knows which channel the video belongs to - videoCanvas.channelId = rtcChannel.getId() + videoCanvas.channelId = rtcChannel.getChannelId() agoraKit.setupRemoteVideo(videoCanvas) } } diff --git a/iOS/APIExample/Examples/Advanced/RTMPStreaming/RTMPStreaming.swift b/iOS/APIExample/Examples/Advanced/RTMPStreaming/RTMPStreaming.swift index 7d48f0318..772c11d5c 100644 --- a/iOS/APIExample/Examples/Advanced/RTMPStreaming/RTMPStreaming.swift +++ b/iOS/APIExample/Examples/Advanced/RTMPStreaming/RTMPStreaming.swift @@ -180,7 +180,7 @@ class RTMPStreamingMain: BaseViewController { // therefore we have to create a livetranscoding object and call before addPublishStreamUrl transcoding.size = CGSize(width: CANVAS_WIDTH, height: CANVAS_HEIGHT) agoraKit.setLiveTranscoding(transcoding) - agoraKit.startRtmpStream(withTranscoding: rtmpURL, transcoding: transcoding) + agoraKit.startRtmpStreamWithTranscoding(rtmpURL, transcoding: transcoding) } else{ agoraKit.startRtmpStreamWithoutTranscoding(rtmpURL) diff --git a/iOS/APIExample/Examples/Advanced/VideoProcess/Base.lproj/VideoProcess.storyboard b/iOS/APIExample/Examples/Advanced/VideoProcess/Base.lproj/VideoProcess.storyboard index 128a68f9a..5d82513ed 100644 --- a/iOS/APIExample/Examples/Advanced/VideoProcess/Base.lproj/VideoProcess.storyboard +++ b/iOS/APIExample/Examples/Advanced/VideoProcess/Base.lproj/VideoProcess.storyboard @@ -400,6 +400,12 @@ + + + + + + diff --git a/iOS/APIExample/Examples/Advanced/VideoProcess/VideoProcess.swift b/iOS/APIExample/Examples/Advanced/VideoProcess/VideoProcess.swift index e1d8cb302..7659853cf 100644 --- a/iOS/APIExample/Examples/Advanced/VideoProcess/VideoProcess.swift +++ b/iOS/APIExample/Examples/Advanced/VideoProcess/VideoProcess.swift @@ -39,6 +39,13 @@ class VideoProcessMain : BaseViewController @IBOutlet weak var colorEnhanceSwitch: UISwitch! @IBOutlet weak var virtualBgSwitch: UISwitch! @IBOutlet weak var virtualBgSegment: UISegmentedControl! + @IBOutlet weak var lightenSlider: UISlider! + @IBOutlet weak var rednessSlider: UISlider! + @IBOutlet weak var sharpnessSlider: UISlider! + @IBOutlet weak var smoothSlider: UISlider! + @IBOutlet weak var strengthSlider: UISlider! + @IBOutlet weak var skinProtectSlider: UISlider! + var agoraKit: AgoraRtcEngineKit! var localVideo = Bundle.loadVideoView(type: .local, audioOnly: false) @@ -51,11 +58,8 @@ class VideoProcessMain : BaseViewController override func viewDidLoad(){ super.viewDidLoad() - // layout render view - localVideo.setPlaceholder(text: "Local Host".localized) - remoteVideo.setPlaceholder(text: "Remote Host".localized) - container.layoutStream(views: [localVideo, remoteVideo]) - + setupUI() + // set up agora instance when view loaded let config = AgoraRtcEngineConfig() config.appId = KeyCenter.AppId @@ -124,6 +128,23 @@ class VideoProcessMain : BaseViewController } } + // MARK: - UI + + func setupUI() { + // layout render view + localVideo.setPlaceholder(text: "Local Host".localized) + remoteVideo.setPlaceholder(text: "Remote Host".localized) + container.layoutStream(views: [localVideo, remoteVideo]) + + lightenSlider.value = beautifyOption.lighteningLevel + rednessSlider.value = beautifyOption.rednessLevel + sharpnessSlider.value = beautifyOption.sharpnessLevel + smoothSlider.value = beautifyOption.smoothnessLevel + strengthSlider.value = colorEnhanceOption.strengthLevel + skinProtectSlider.value = colorEnhanceOption.skinProtectLevel + } + + @IBAction func onChangeBeauty(_ sender:UISwitch){ agoraKit.setBeautyEffectOptions(sender.isOn, options: beautifyOption) } @@ -188,7 +209,7 @@ class VideoProcessMain : BaseViewController break case 1: source.backgroundSourceType = .color - source.color = 0xFFFF + source.color = 0xFFFFFF break case 2: source.backgroundSourceType = .blur From b182257527bacfcea9a94b21167b2faa6f1caf88 Mon Sep 17 00:00:00 2001 From: Arlin Date: Sat, 29 Jan 2022 20:27:08 +0800 Subject: [PATCH 13/21] change AGEVideoLayout to v1.0.4 to avoid crash on macos --- iOS/Podfile | 2 +- macOS/Podfile | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/iOS/Podfile b/iOS/Podfile index 5e4de0606..ff1960c95 100644 --- a/iOS/Podfile +++ b/iOS/Podfile @@ -5,7 +5,7 @@ target 'APIExample' do use_frameworks! pod 'Floaty', '~> 4.2.0' - pod 'AGEVideoLayout', '~> 1.0.2' + pod 'AGEVideoLayout', '~> 1.0.4' pod 'AgoraRtcEngine_iOS', '3.6.0.1' pod 'AgoraMediaPlayer_iOS', '1.2.2' end diff --git a/macOS/Podfile b/macOS/Podfile index c75c54009..f21e3feac 100644 --- a/macOS/Podfile +++ b/macOS/Podfile @@ -6,7 +6,7 @@ target 'APIExample' do use_frameworks! # Pods for APIExample - pod 'AGEVideoLayout', '~> 1.0.2' + pod 'AGEVideoLayout', '~> 1.0.4' pod 'AgoraRtcEngine_macOS', '3.6.0.1' target 'APIExampleTests' do @@ -18,4 +18,4 @@ target 'APIExample' do # Pods for testing end -end +end \ No newline at end of file From dfc4129dc46425b68cd568e177d40ad234a7fee6 Mon Sep 17 00:00:00 2001 From: xianing Date: Mon, 7 Feb 2022 20:55:57 +0800 Subject: [PATCH 14/21] update 3.6.2 c++ header files --- .../src/main/cpp/include/AgoraBase.h | 3 +- .../src/main/cpp/include/IAgoraMediaEngine.h | 6 + .../src/main/cpp/include/IAgoraRtcChannel.h | 53 +- .../src/main/cpp/include/IAgoraRtcEngine.h | 316 +- .../src/main/cpp/include/AgoraBase.h | 55 +- .../src/main/cpp/include/IAgoraMediaEngine.h | 607 ++- .../src/main/cpp/include/IAgoraRtcChannel.h | 800 ++- .../src/main/cpp/include/IAgoraRtcEngine.h | 4841 ++++++++++++----- .../src/main/cpp/include/IAgoraService.h | 2 +- .../src/main/cpp/include/agora/AgoraBase.h | 55 +- .../cpp/include/agora/IAgoraMediaEngine.h | 607 ++- .../main/cpp/include/agora/IAgoraRtcChannel.h | 800 ++- .../main/cpp/include/agora/IAgoraRtcEngine.h | 4841 ++++++++++++----- .../main/cpp/include/agora/IAgoraService.h | 2 +- 14 files changed, 9185 insertions(+), 3803 deletions(-) diff --git a/Android/APIExample/lib-player-helper/src/main/cpp/include/AgoraBase.h b/Android/APIExample/lib-player-helper/src/main/cpp/include/AgoraBase.h index 337390cf0..aad4a83fe 100644 --- a/Android/APIExample/lib-player-helper/src/main/cpp/include/AgoraBase.h +++ b/Android/APIExample/lib-player-helper/src/main/cpp/include/AgoraBase.h @@ -398,7 +398,8 @@ enum ERROR_CODE_TYPE { /** 117: The data stream transmission timed out. */ ERR_STREAM_MESSAGE_TIMEOUT = 117, - /** 119: Switching roles fail. Please try to rejoin the channel. + /** **DEPRECATED** 119: Deprecated as of v3.6.1. Use CLIENT_ROLE_CHANGE_FAILED_REASON in the \ref agora::rtc::IRtcEngineEventHandler::onClientRoleChangeFailed "onClientRoleChangeFailed" callback instead. + * Switching roles fail. Please try to rejoin the channel. */ ERR_SET_CLIENT_ROLE_NOT_AUTHORIZED = 119, /** 120: Decryption fails. The user may have used a different encryption password to join the channel. Check your settings or try rejoining the channel. diff --git a/Android/APIExample/lib-player-helper/src/main/cpp/include/IAgoraMediaEngine.h b/Android/APIExample/lib-player-helper/src/main/cpp/include/IAgoraMediaEngine.h index c213346ac..6f7fd88c2 100644 --- a/Android/APIExample/lib-player-helper/src/main/cpp/include/IAgoraMediaEngine.h +++ b/Android/APIExample/lib-player-helper/src/main/cpp/include/IAgoraMediaEngine.h @@ -664,6 +664,12 @@ struct ExternalVideoFrame { /** 16: The video pixel format is I422. */ VIDEO_PIXEL_I422 = 16, + /** 17: The video pixel format is GL_TEXTURE_2D. + */ + VIDEO_TEXTURE_2D = 17, + /** 18: The video pixel format is GL_TEXTURE_OES. + */ + VIDEO_TEXTURE_OES = 18, }; /** The buffer type. See #VIDEO_BUFFER_TYPE diff --git a/Android/APIExample/lib-player-helper/src/main/cpp/include/IAgoraRtcChannel.h b/Android/APIExample/lib-player-helper/src/main/cpp/include/IAgoraRtcChannel.h index 9a0ec7193..8f9e71506 100644 --- a/Android/APIExample/lib-player-helper/src/main/cpp/include/IAgoraRtcChannel.h +++ b/Android/APIExample/lib-player-helper/src/main/cpp/include/IAgoraRtcChannel.h @@ -80,9 +80,9 @@ class IChannelEventHandler { } /** Occurs when the user role switches in the interactive live streaming. For example, from a host to an audience or vice versa. - This callback notifies the application of a user role switch when the application calls the \ref IChannel::setClientRole "setClientRole" method. + This callback notifies the application of a user role switch when the application calls the \ref IChannel::setClientRole "setClientRole" method, and successfully changed role. - The SDK triggers this callback when the local user switches the user role by calling the \ref IChannel::setClientRole "setClientRole" method after joining the channel. + The SDK triggers this callback when the local user switches the user role by calling the \ref IChannel::setClientRole "setClientRole" method after joining the channel, and successfully changed role. @param rtcChannel IChannel @param oldRole Role that the user switches from: #CLIENT_ROLE_TYPE. @@ -93,6 +93,21 @@ class IChannelEventHandler { (void)oldRole; (void)newRole; } + + /** Occurs when the user role switches in the interactive live streaming. For example, from a host to an audience or vice versa. + + This callback notifies the application of a user role switch when the application calls the \ref IChannel::setClientRole "setClientRole" method, and failed to change role. + + The SDK triggers this callback when the local user switches the user role by calling the \ref IChannel::setClientRole "setClientRole" method after joining the channel, and failed to change role. + @param reason The reason of changing client role failed. See #CLIENT_ROLE_CHANGE_FAILED_REASON. + @param currentRole Current Role that the user holds: #CLIENT_ROLE_TYPE. + */ + virtual void onClientRoleChangeFailed(IChannel* rtcChannel, CLIENT_ROLE_CHANGE_FAILED_REASON reason, CLIENT_ROLE_TYPE currentRole) { + (void)rtcChannel; + (void)reason; + (void)currentRole; + } + /** Occurs when a remote user (`COMMUNICATION`)/ host (`LIVE_BROADCASTING`) joins the channel. - `COMMUNICATION` profile: This callback notifies the application that another user joins the channel. If other users are already in the channel, the SDK also reports to the application on the existing users. @@ -569,6 +584,21 @@ class IChannelEventHandler { (void)state; (void)reason; } + + /** Occurs when join success after calling \ref IRtcEngine::setLocalAccessPoint "setLocalAccessPoint" or \ref IRtcEngine::setCloudProxy "setCloudProxy" + @param rtcChannel IChannel + @param uid User ID of the user joining the channel. + @param proxyType type of proxy agora sdk connected, proxyType will be NONE_PROXY_TYPE if not connected to proxy(fallback). + @param localProxyIp local proxy ip list. if not join local proxy, it will be "". + @param elapsed Time elapsed (ms) from the user calling the \ref IRtcEngine::joinChannel "joinChannel" method until the SDK triggers this callback. + */ + virtual void onProxyConnected(IChannel* rtcChannel, uid_t uid, PROXY_TYPE proxyType, const char* localProxyIp, int elapsed) { + (void)rtcChannel; + (void)uid; + (void)proxyType; + (void)localProxyIp; + (void)elapsed; + } }; /** The IChannel class. */ @@ -887,7 +917,7 @@ class IChannel { * call this method to switch the user role after joining a channel, the SDK automatically does the following: * - Calls \ref IChannel::muteLocalAudioStream "muteLocalAudioStream" and \ref IChannel::muteLocalVideoStream "muteLocalVideoStream" to * change the publishing state. - * - Triggers \ref IChannelEventHandler::onClientRoleChanged "onClientRoleChanged" on the local client. + * - Triggers \ref IChannelEventHandler::onClientRoleChanged "onClientRoleChanged" or \ref IChannelEventHandler::onClientRoleChangeFailed "onClientRoleChangeFailed" on the local client in 5s. * - Triggers \ref IChannelEventHandler::onUserJoined "onUserJoined" or \ref IChannelEventHandler::onUserOffline "onUserOffline" (BECOME_AUDIENCE) * on the remote client. * @@ -920,7 +950,7 @@ class IChannel { * call this method to switch the user role after joining a channel, the SDK automatically does the following: * - Calls \ref IChannel::muteLocalAudioStream "muteLocalAudioStream" and \ref IChannel::muteLocalVideoStream "muteLocalVideoStream" to * change the publishing state. - * - Triggers \ref IChannelEventHandler::onClientRoleChanged "onClientRoleChanged" on the local client. + * - Triggers \ref IChannelEventHandler::onClientRoleChanged "onClientRoleChanged" or \ref IChannelEventHandler::onClientRoleChangeFailed "onClientRoleChangeFailed" on the local client in 5s. * - Triggers \ref IChannelEventHandler::onUserJoined "onUserJoined" or \ref IChannelEventHandler::onUserOffline "onUserOffline" (BECOME_AUDIENCE) * on the remote client. * @@ -1237,6 +1267,21 @@ class IChannel { - < 0: Failure. */ virtual int setRemoteVideoStreamType(uid_t userId, REMOTE_VIDEO_STREAM_TYPE streamType) = 0; + /** Turn WIFI acceleration on or off. + + @note + - This method is called before and after joining a channel. + - Users check the WIFI router app for information about acceleration. Therefore, if this interface is invoked, the caller accepts that the caller's name will be displayed to the user in the WIFI router application on behalf of the caller. + + @param enabled + - true：Turn WIFI acceleration on. + - false：Turn WIFI acceleration off. + + @return + - 0: Success. + - < 0: Failure. + */ + virtual int enableWirelessAccelerate(bool enabled) = 0; /** Sets the default stream type of remote videos. Under limited network conditions, if the publisher has not disabled the dual-stream mode using diff --git a/Android/APIExample/lib-player-helper/src/main/cpp/include/IAgoraRtcEngine.h b/Android/APIExample/lib-player-helper/src/main/cpp/include/IAgoraRtcEngine.h index cdc96614a..b050af84a 100644 --- a/Android/APIExample/lib-player-helper/src/main/cpp/include/IAgoraRtcEngine.h +++ b/Android/APIExample/lib-player-helper/src/main/cpp/include/IAgoraRtcEngine.h @@ -492,6 +492,10 @@ enum AUDIO_RECORDING_QUALITY_TYPE { * of 32,000 Hz and a 10-minute recording is approximately 3.75 MB. */ AUDIO_RECORDING_QUALITY_HIGH = 2, + /** 3: Ultra high quality. For example, the size of an AAC file with a sample rate + * of 32,000 Hz and a 10-minute recording is approximately 7.5 MB. + */ + AUDIO_RECORDING_QUALITY_ULTRA_HIGH = 3, }; /** Network quality types. */ @@ -1969,6 +1973,10 @@ enum CONNECTION_CHANGED_REASON_TYPE { CONNECTION_CHANGED_CLIENT_IP_ADDRESS_CHANGED = 13, /** 14: Timeout for the keep-alive of the connection between the SDK and Agora's edge server. The connection state changes to CONNECTION_STATE_RECONNECTING(4). */ CONNECTION_CHANGED_KEEP_ALIVE_TIMEOUT = 14, + /** 19: The connection failed due to same uid joined again on another device. */ + CONNECTION_CHANGED_SAME_UID_LOGIN = 19, + /** 20: The connection failed due to too many broadcasters in the channel. */ + CONNECTION_CHANGED_TOO_MANY_BROADCASTERS = 20, }; /** Network type. */ @@ -2085,13 +2093,45 @@ enum CLOUD_PROXY_TYPE { enum LOCAL_PROXY_MODE { /** 0: Connect local proxy with high priority, if not connected to local proxy, fallback to sdrtn. */ - kConnectivityFirst = 0, + ConnectivityFirst = 0, /** 1: Only connect local proxy */ - kLocalOnly = 1, + LocalOnly = 1, }; /// @endcond +enum PROXY_TYPE { + /** 0: Do not use the cloud proxy. + */ + NONE_PROXY_TYPE = 0, + /** 1: The cloud proxy for the UDP protocol. + */ + UDP_PROXY_TYPE = 1, + /// @cond + /** 2: The cloud proxy for the TCP (encrypted) protocol. + */ + TCP_PROXY_TYPE = 2, + /// @endcond + /** 3: The local proxy. + */ + LOCAL_PROXY_TYPE = 3, + /** 4: auto fallback to tcp cloud proxy + */ + TCP_PROXY_AUTO_FALLBACK_TYPE = 4, +}; +/** screencapture exclude window error. + * + * + */ +enum EXCLUDE_WINDOW_ERROR { + /** negative : fail to exclude window. + */ + EXCLUDE_WINDOW_FAIL = -1, + /** 0: none define. + */ + EXCLUDE_WINDOW_NONE = 0 +}; // namespace rtc + #if (defined(__APPLE__) && TARGET_OS_IOS) /** * The operational permission of the SDK on the audio session. @@ -2245,6 +2285,31 @@ enum AUDIO_FILE_INFO_ERROR { AUDIO_FILE_INFO_ERROR_FAILURE = 1 }; +/// @cond +/** + * The reason for failure of changing role. + * + * @since v3.6.1 + */ +enum CLIENT_ROLE_CHANGE_FAILED_REASON { + /** 1: Too many broadcasters in the channel. + */ + CLIENT_ROLE_CHANGE_FAILED_BY_TOO_MANY_BROADCASTERS = 1, + + /** 2: Change operation not authorized. + */ + CLIENT_ROLE_CHANGE_FAILED_BY_NOT_AUTHORIZED = 2, + + /** 3: Change operation timer out. + */ + CLIENT_ROLE_CHANGE_FAILED_BY_REQUEST_TIME_OUT = 3, + + /** 4: Change operation is interrupted since we lost connection with agora service. + */ + CLIENT_ROLE_CHANGE_FAILED_BY_CONNECTION_FAILED = 4, +}; +/// @endcond + /** The detailed options of a user. */ struct ClientRoleOptions { @@ -2378,6 +2443,37 @@ struct RtcStats { 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), txPacketLossRate(0), rxPacketLossRate(0), userCount(0), cpuAppUsage(0), cpuTotalUsage(0), gatewayRtt(0), memoryAppUsageRatio(0), memoryTotalUsageRatio(0), memoryAppUsageInKbytes(0) {} }; +/** The reason of notifying the user of a message. + */ +enum WLACC_MESSAGE_REASON { + /** WIFI signal is weak.*/ + WLACC_MESSAGE_REASON_WEAK_SIGNAL = 0, + /** 2.4G band congestion.*/ + WLACC_MESSAGE_REASON_2G_CHANNEL_CONGESTION = 1, +}; +/** Suggest an action for the user. + */ +enum WLACC_SUGGEST_ACTION { + /** Please get close to AP.*/ + WLACC_SUGGEST_ACTION_CLOSE_TO_WIFI = 0, + /** The user is advised to connect to the prompted SSID.*/ + WLACC_SUGGEST_ACTION_CONNECT_5G = 1, + /** The user is advised to check whether the AP supports 5G band and enable 5G band (the aciton link is attached), or purchases an AP that supports 5G. AP does not support 5G band.*/ + WLACC_SUGGEST_ACTION_CHECK_5G = 2, + /** The user is advised to change the SSID of the 2.4G or 5G band (the aciton link is attached). The SSID of the 2.4G band AP is the same as that of the 5G band.*/ + WLACC_SUGGEST_ACTION_MODIFY_SSID = 3, +}; +/** Indicator optimization degree. + */ +struct WlAccStats { + /** End-to-end delay optimization percentage.*/ + unsigned short e2eDelayPercent; + /** Frozen Ratio optimization percentage.*/ + unsigned short frozenRatioPercent; + /** Loss Rate optimization percentage.*/ + unsigned short lossRatePercent; +}; + /** Quality change of the local video in terms of target frame rate and target bit rate since last count. */ enum QUALITY_ADAPT_INDICATION { @@ -2388,6 +2484,12 @@ enum QUALITY_ADAPT_INDICATION { /** The quality worsens because the network bandwidth decreases. */ ADAPT_DOWN_BANDWIDTH = 2, }; + +struct ScreenCaptureInfo { + const char* graphicsCardType; + EXCLUDE_WINDOW_ERROR errCode; +}; + /** Quality of experience (QoE) of the local user when receiving a remote audio stream. * * @since v3.3.0 @@ -2555,6 +2657,12 @@ enum CHANNEL_MEDIA_RELAY_STATE { RELAY_STATE_FAILURE = 3, }; +/**Audio Device Test.different volume Type*/ +enum AudioDeviceTestVolumeType { + AudioTestRecordingVolume = 0, + AudioTestPlaybackVolume = 1, +}; + /** Statistics of the local video stream. */ struct LocalVideoStats { @@ -2918,8 +3026,15 @@ struct AudioRecordingConfiguration { * #AUDIO_RECORDING_QUALITY_MEDIUM or #AUDIO_RECORDING_QUALITY_HIGH. */ int recordingSampleRate; - AudioRecordingConfiguration() : filePath(nullptr), recordingQuality(AUDIO_RECORDING_QUALITY_MEDIUM), recordingPosition(AUDIO_RECORDING_POSITION_MIXED_RECORDING_AND_PLAYBACK), recordingSampleRate(32000) {} - AudioRecordingConfiguration(const char* path, AUDIO_RECORDING_QUALITY_TYPE quality, AUDIO_RECORDING_POSITION position, int sampleRate) : filePath(path), recordingQuality(quality), recordingPosition(position), recordingSampleRate(sampleRate) {} + /** Recording channel. The following values are supported: + * + * - (Default) 1 + * - 2 + */ + int recordingChannel; + + AudioRecordingConfiguration() : filePath(nullptr), recordingQuality(AUDIO_RECORDING_QUALITY_MEDIUM), recordingPosition(AUDIO_RECORDING_POSITION_MIXED_RECORDING_AND_PLAYBACK), recordingSampleRate(32000), recordingChannel(1) {} + AudioRecordingConfiguration(const char* path, AUDIO_RECORDING_QUALITY_TYPE quality, AUDIO_RECORDING_POSITION position, int sampleRate, int channel) : filePath(path), recordingQuality(quality), recordingPosition(position), recordingSampleRate(sampleRate), recordingChannel(channel) {} }; /** The video and audio properties of the user displaying the video in the CDN live. Agora supports a maximum of 17 transcoding users in a CDN streaming channel. @@ -3329,7 +3444,7 @@ struct LocalAccessPointConfiguration { /** local proxy connection mode, connectivity first or local only. */ LOCAL_PROXY_MODE mode; - LocalAccessPointConfiguration() : ipList(nullptr), ipListSize(0), domainList(nullptr), domainListSize(0), verifyDomainName(nullptr), mode(kConnectivityFirst) {} + LocalAccessPointConfiguration() : ipList(nullptr), ipListSize(0), domainList(nullptr), domainListSize(0), verifyDomainName(nullptr), mode(ConnectivityFirst) {} }; /// @endcond @@ -3555,6 +3670,83 @@ struct BeautyOptions { BeautyOptions() : lighteningLevel(0), smoothnessLevel(0), rednessLevel(0), sharpnessLevel(0), lighteningContrastLevel(LIGHTENING_CONTRAST_NORMAL) {} }; +/** lowlight enhancement options. + */ +struct LowLightEnhanceOptions { + enum LOW_LIGHT_ENHANCE_MODE { + /** low light enhancement is applied automatically when neccessary. */ + LOW_LIGHT_ENHANCE_AUTO = 0, + /** low light enhancement is applied manually. */ + LOW_LIGHT_ENHANCE_MANUAL + }; + + enum LOW_LIGHT_ENHANCE_LEVEL { + /** low light enhancement is applied without reducing frame rate. */ + LOW_LIGHT_ENHANCE_LEVEL_HIGH_QUALITY = 0, + /** High-quality low light enhancement is applied, at the cost of possibly reduced frame rate and higher cpu usage. */ + LOW_LIGHT_ENHANCE_LEVEL_FAST + }; + + /** lowlight enhancement mode. + */ + LOW_LIGHT_ENHANCE_MODE mode; + + /** lowlight enhancement level. + */ + LOW_LIGHT_ENHANCE_LEVEL level; + + LowLightEnhanceOptions(LOW_LIGHT_ENHANCE_MODE lowlightMode, LOW_LIGHT_ENHANCE_LEVEL lowlightLevel) : mode(lowlightMode), level(lowlightLevel) {} + + LowLightEnhanceOptions() : mode(LOW_LIGHT_ENHANCE_AUTO), level(LOW_LIGHT_ENHANCE_LEVEL_HIGH_QUALITY) {} +}; + +struct VideoDenoiserOptions { + /** video noise reduction mode + */ + enum VIDEO_DENOISER_MODE { + /** video noise reduction is applied automatically when neccessary. */ + VIDEO_DENOISER_AUTO = 0, + /** video noise reduction is applied manually. */ + VIDEO_DENOISER_MANUAL + }; + + enum VIDEO_DENOISER_LEVEL { + /** Video noise reduction is applied for the default scene */ + VIDEO_DENOISER_LEVEL_HIGH_QUALITY = 0, + /** Video noise reduction is applied for the fixed-camera scene to save the cpu usage */ + VIDEO_DENOISER_LEVEL_FAST, + /** Video noise reduction is applied for the high noisy scene to further denoise the video. */ + VIDEO_DENOISER_LEVEL_STRENGTH + }; + /** video noise reduction mode. + */ + VIDEO_DENOISER_MODE mode; + + /** video noise reduction level. + */ + VIDEO_DENOISER_LEVEL level; + + VideoDenoiserOptions(VIDEO_DENOISER_MODE denoiserMode, VIDEO_DENOISER_LEVEL denoiserLevel) : mode(denoiserMode), level(denoiserLevel) {} + + VideoDenoiserOptions() : mode(VIDEO_DENOISER_AUTO), level(VIDEO_DENOISER_LEVEL_HIGH_QUALITY) {} +}; + +/** color enhancement options. + */ +struct ColorEnhanceOptions { + /** Color enhance strength. The value ranges between 0 (original) and 1. + */ + float strengthLevel; + + /** Skin protect level. The value ranges between 0 (original) and 1. + */ + float skinProtectLevel; + + ColorEnhanceOptions(float stength, float skinProtect) : strengthLevel(stength), skinProtectLevel(skinProtect) {} + + ColorEnhanceOptions() : strengthLevel(0), skinProtectLevel(1) {} +}; + /** The custom background image. * * @since v3.4.5 @@ -3855,7 +4047,6 @@ class IPacketObserver { virtual bool onReceiveVideoPacket(Packet& packet) = 0; }; -#if defined(_WIN32) /** The capture type of the custom video source. */ enum VIDEO_CAPTURE_TYPE { @@ -3965,7 +4156,6 @@ class IVideoSource { */ virtual VideoContentHint getVideoContentHint() = 0; }; -#endif #if (defined(__APPLE__) && TARGET_OS_MAC && !TARGET_OS_IPHONE) /** @@ -4197,14 +4387,24 @@ class IRtcEngineEventHandler { /** Occurs when the user role switches in the interactive live streaming. For example, from a host to an audience or vice versa. - This callback notifies the application of a user role switch when the application calls the \ref IRtcEngine::setClientRole "setClientRole" method. + This callback notifies the application of a user role switch when the application calls the \ref IRtcEngine::setClientRole "setClientRole" method, and successfully changed role. - The SDK triggers this callback when the local user switches the user role by calling the \ref agora::rtc::IRtcEngine::setClientRole "setClientRole" method after joining the channel. + The SDK triggers this callback when the local user switches the user role by calling the \ref agora::rtc::IRtcEngine::setClientRole "setClientRole" method after joining the channel, and successfully changed role. @param oldRole Role that the user switches from: #CLIENT_ROLE_TYPE. @param newRole Role that the user switches to: #CLIENT_ROLE_TYPE. */ virtual void onClientRoleChanged(CLIENT_ROLE_TYPE oldRole, CLIENT_ROLE_TYPE newRole) {} + /** Occurs when the user role switches in the interactive live streaming. For example, from a host to an audience or vice versa. + + This callback notifies the application of a user role switch when the application calls the \ref IRtcEngine::setClientRole "setClientRole" method, and failed to change role. + + The SDK triggers this callback when the local user switches the user role by calling the \ref agora::rtc::IRtcEngine::setClientRole "setClientRole" method after joining the channel, and failed to change role. + @param reason The reason of changing client role failed. See #CLIENT_ROLE_CHANGE_FAILED_REASON. + @param currentRole Current Role that the user holds: #CLIENT_ROLE_TYPE. + */ + virtual void onClientRoleChangeFailed(CLIENT_ROLE_CHANGE_FAILED_REASON reason, CLIENT_ROLE_TYPE currentRole) {} + /** Occurs when a remote user (`COMMUNICATION`)/ host (`LIVE_BROADCASTING`) joins the channel. - `COMMUNICATION` profile: This callback notifies the application that another user joins the channel. If other users are already in the channel, the SDK also reports to the application on the existing users. @@ -4244,6 +4444,21 @@ class IRtcEngineEventHandler { (void)reason; } + /** Occurs when join success after calling \ref IRtcEngine::setLocalAccessPoint "setLocalAccessPoint" or \ref IRtcEngine::setCloudProxy "setCloudProxy" + @param channel Channel name. + @param uid User ID of the user joining the channel. + @param proxyType type of proxy agora sdk connected, proxyType will be NONE_PROXY_TYPE if not connected to proxy(fallback). + @param localProxyIp local proxy ip. if not join local proxy, it will be "". + @param elapsed Time elapsed (ms) from the user calling the \ref IRtcEngine::joinChannel "joinChannel" method until the SDK triggers this callback. + */ + virtual void onProxyConnected(const char* channel, uid_t uid, PROXY_TYPE proxyType, const char* localProxyIp, int elapsed) { + (void)channel; + (void)uid; + (void)proxyType; + (void)localProxyIp; + (void)elapsed; + } + /** Reports the last mile network quality of the local user once every two seconds before the user joins the channel. Last mile refers to the connection between the local device and Agora's edge server. After the application calls the \ref IRtcEngine::enableLastmileTest "enableLastmileTest" method, this callback reports once every two seconds the uplink and downlink last mile network conditions of the local user before the user joins the channel. @@ -4572,6 +4787,12 @@ class IRtcEngineEventHandler { (void)totalVolume; } + /** add for audio device test:report playback volume and recording volume + **/ + virtual void onAudioDeviceTestVolumeIndication(AudioDeviceTestVolumeType volumeType, int volume) { + (void)volumeType; + (void)volume; + } /** Occurs when the most active remote speaker is detected. After a successful call of \ref IRtcEngine::enableAudioVolumeIndication(int, int, bool) "enableAudioVolumeIndication", @@ -5399,6 +5620,27 @@ The SDK triggers this callback when the local user fails to receive the stream m (void)reason; } + /** Occurs when the WIFI message need be sent to the user. + + @param reason The reason of notifying the user of a message. + @param action Suggest an action for the user. + @param wlAccMsg The message content of notifying the user. + */ + virtual void onWlAccMessage(WLACC_MESSAGE_REASON reason, WLACC_SUGGEST_ACTION action, const char* wlAccMsg) { + (void)reason; + (void)action; + (void)wlAccMsg; + } + /** Occurs when SDK statistics wifi acceleration optimization effect. + + @param currentStats Instantaneous value of optimization effect. + @param averageStats Average value of cumulative optimization effect. + */ + virtual void onWlAccStats(WlAccStats currentStats, WlAccStats averageStats) { + (void)currentStats; + (void)averageStats; + } + /** Occurs when the local network type changes. When the network connection is interrupted, this callback indicates whether the interruption is caused by a network type change or poor network conditions. @@ -5447,6 +5689,15 @@ The SDK triggers this callback when the local user fails to receive the stream m (void)success; (void)reason; } + +#ifdef _WIN32 + /** Occurs when screencapture fail to filter window + * + * + * @param ScreenCaptureInfo + */ + virtual void onScreenCaptureInfoUpdated(ScreenCaptureInfo& info) { (void)info; } +#endif /// @endcond }; @@ -5491,6 +5742,7 @@ class IVideoDeviceCollection { virtual void release() = 0; }; +#if !defined(__ANDROID__) && !(defined(__APPLE__) && TARGET_OS_IPHONE) /** Video device management methods. The IVideoDeviceManager interface class tests the video device interfaces. Instantiate an AVideoDeviceManager class to get an IVideoDeviceManager interface. @@ -5968,6 +6220,7 @@ class IAudioDeviceManager { */ virtual void release() = 0; }; +#endif /** The configuration of the log files. * @@ -6448,7 +6701,7 @@ class IRtcEngine { * call this method to switch the user role after joining a channel, the SDK automatically does the following: * - Calls \ref IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" and \ref IRtcEngine::muteLocalVideoStream "muteLocalVideoStream" to * change the publishing state. - * - Triggers \ref IRtcEngineEventHandler::onClientRoleChanged "onClientRoleChanged" on the local client. + * - Triggers \ref IRtcEngineEventHandler::onClientRoleChanged "onClientRoleChanged" or \ref IRtcEngineEventHandler::onClientRoleChangeFailed "onClientRoleChangeFailed" on the local client in 5s. * - Triggers \ref IRtcEngineEventHandler::onUserJoined "onUserJoined" or \ref IRtcEngineEventHandler::onUserOffline "onUserOffline" (BECOME_AUDIENCE) * on the remote client. * @@ -6481,7 +6734,7 @@ class IRtcEngine { * call this method to switch the user role after joining a channel, the SDK automatically does the following: * - Calls \ref IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" and \ref IRtcEngine::muteLocalVideoStream "muteLocalVideoStream" to * change the publishing state. - * - Triggers \ref IRtcEngineEventHandler::onClientRoleChanged "onClientRoleChanged" on the local client. + * - Triggers \ref IRtcEngineEventHandler::onClientRoleChanged "onClientRoleChanged" or \ref IRtcEngineEventHandler::onClientRoleChangeFailed "onClientRoleChangeFailed" on the local client in 5s. * - Triggers \ref IRtcEngineEventHandler::onUserJoined "onUserJoined" or \ref IRtcEngineEventHandler::onUserOffline "onUserOffline" (BECOME_AUDIENCE) * on the remote client. * @@ -7537,6 +7790,22 @@ class IRtcEngine { */ virtual int setRemoteDefaultVideoStreamType(REMOTE_VIDEO_STREAM_TYPE streamType) = 0; + /** Turn WIFI acceleration on or off. + + @note + - This method is called before and after joining a channel. + - Users check the WIFI router app for information about acceleration. Therefore, if this interface is invoked, the caller accepts that the caller's name will be displayed to the user in the WIFI router application on behalf of the caller. + + @param enabled + - true：Turn WIFI acceleration on. + - false：Turn WIFI acceleration off. + + @return + - 0: Success. + - < 0: Failure. + */ + virtual int enableWirelessAccelerate(bool enabled) = 0; + /** Enables the reporting of users' volume indication. This method enables the SDK to regularly report the volume information of the local user who sends a stream and @@ -9290,16 +9559,17 @@ class IRtcEngine { #endif #if (defined(__APPLE__) && TARGET_OS_MAC && !TARGET_OS_IPHONE) || defined(_WIN32) + /** Enables loopback audio capturing. - If you enable loopback audio capturing, the output of the sound card is mixed into the audio stream sent to the other end. + If you enable loopback audio capturing, the output of the sound card is mixed into the audio stream sent to the other end. - @note You can call this method either before or after joining a channel. + @note You can call this method either before or after joining a channel. - @param enabled Sets whether to enable/disable loopback capturing. - - true: Enable loopback capturing. - - false: (Default) Disable loopback capturing. - @param deviceName Pointer to the device name of the sound card. The default value is NULL (the default sound card). + @param enabled Sets whether to enable/disable loopback capturing. + - true: Enable loopback capturing. + - false: (Default) Disable loopback capturing. + @param deviceName Pointer to the device name of the sound card. The default value is NULL (the default sound card). @note - This method is for macOS and Windows only. @@ -9337,6 +9607,7 @@ class IRtcEngine { * @return IScreenCaptureSourceList */ virtual IScreenCaptureSourceList* getScreenCaptureSources(const SIZE& thumbSize, const SIZE& iconSize, const bool includeScreen) = 0; + /** Shares the whole or part of a screen by specifying the display ID. * * @note @@ -9608,7 +9879,6 @@ class IRtcEngine { virtual int updateScreenCaptureRegion(const Rect* rect) = 0; #endif -#if defined(_WIN32) /** Sets a custom video source. * * During real-time communication, the Agora SDK enables the default video input device, that is, the built-in camera to @@ -9624,7 +9894,6 @@ class IRtcEngine { * - false: The custom video source is not added to the SDK. */ virtual bool setVideoSource(IVideoSource* source) = 0; -#endif /** Gets the current call ID. @@ -10146,6 +10415,9 @@ class IRtcEngine { * - `-4(ERR_NOT_SUPPORTED)`: The system version is earlier than Android 5.0, which does not support this function. */ virtual int setBeautyEffectOptions(bool enabled, BeautyOptions options) = 0; + virtual int setLowlightEnhanceOptions(bool enabled, LowLightEnhanceOptions options) = 0; + virtual int setVideoDenoiserOptions(bool enabled, VideoDenoiserOptions options) = 0; + virtual int setColorEnhanceOptions(bool enabled, ColorEnhanceOptions options) = 0; /** * Enables/Disables the virtual background. (beta feature) * @@ -10493,13 +10765,11 @@ class IRtcEngine { // virtual int getMediaRecorder(IMediaRecorderObserver *observer, int sys_version = 0) = 0; - // virtual int startRecording(const MediaRecorderConfiguration &config) = 0; // virtual int stopRecording() = 0; // virtual int releaseRecorder() = 0; -#if defined(_WIN32) /** * Customizes the local video renderer. (for Windows only) * @@ -10537,7 +10807,6 @@ class IRtcEngine { * - < 0: Failure. */ virtual int setRemoteVideoRenderer(uid_t uid, IVideoSink* videoSink) = 0; -#endif /// @cond virtual int setLocalAccessPoint(const LocalAccessPointConfiguration& config) = 0; /// @endcond @@ -10798,6 +11067,7 @@ class IRtcEngineParameter { virtual int convertPath(const char* filePath, agora::util::AString& value) = 0; }; +#if !defined(__ANDROID__) && !(defined(__APPLE__) && TARGET_OS_IPHONE) class AAudioDeviceManager : public agora::util::AutoPtr { public: AAudioDeviceManager(IRtcEngine* engine) { queryInterface(engine, AGORA_IID_AUDIO_DEVICE_MANAGER); } @@ -10807,6 +11077,7 @@ class AVideoDeviceManager : public agora::util::AutoPtr { public: AVideoDeviceManager(IRtcEngine* engine) { queryInterface(engine, AGORA_IID_VIDEO_DEVICE_MANAGER); } }; +#endif class AGORA_CPP_API AParameter : public agora::util::AutoPtr { public: @@ -10901,6 +11172,7 @@ class AGORA_CPP_API RtcEngineParameters { int enableWebSdkInteroperability(bool enabled); // only for live broadcast + int setVideoQualityParameters(bool preferFrameRateOverImageQuality); int setLocalVideoMirrorMode(VIDEO_MIRROR_MODE_TYPE mirrorMode); int setLocalPublishFallbackOption(STREAM_FALLBACK_OPTIONS option); diff --git a/Android/APIExample/lib-raw-data/src/main/cpp/include/AgoraBase.h b/Android/APIExample/lib-raw-data/src/main/cpp/include/AgoraBase.h index c729bf7da..aad4a83fe 100644 --- a/Android/APIExample/lib-raw-data/src/main/cpp/include/AgoraBase.h +++ b/Android/APIExample/lib-raw-data/src/main/cpp/include/AgoraBase.h @@ -13,7 +13,9 @@ #include #if defined(_WIN32) +#ifndef WIN32_LEAN_AND_MEAN #define WIN32_LEAN_AND_MEAN +#endif #include #define AGORA_CALL __cdecl #if defined(AGORARTC_EXPORT) @@ -38,6 +40,20 @@ #define AGORA_CALL #endif +#ifdef __GNUC__ +#define AGORA_GCC_VERSION_AT_LEAST(x, y) (__GNUC__ > (x) || __GNUC__ == (x) && __GNUC_MINOR__ >= (y)) +#else +#define AGORA_GCC_VERSION_AT_LEAST(x, y) 0 +#endif + +#if AGORA_GCC_VERSION_AT_LEAST(3, 1) +#define AGORA_DEPRECATED_ATTRIBUTE __attribute__((deprecated)) +#elif defined(_MSC_VER) +#define AGORA_DEPRECATED_ATTRIBUTE +#else +#define AGORA_DEPRECATED_ATTRIBUTE +#endif + namespace agora { namespace util { @@ -220,6 +236,9 @@ enum WARN_CODE_TYPE { /** 1053: Audio Processing Module: A residual echo is detected, which may be caused by the belated scheduling of system threads or the signal overflow. */ WARN_APM_RESIDUAL_ECHO = 1053, + /** 1054: Audio Processing Module: AI NS is closed, this can be triggered by manual settings or by performance detection modules. + */ + WARN_APM_AINS_CLOSED = 1054, /// @cond WARN_ADM_WIN_CORE_NO_RECORDING_DEVICE = 1322, /// @endcond @@ -234,13 +253,13 @@ enum WARN_CODE_TYPE { * - Update the sound card drive. */ WARN_ADM_WIN_CORE_IMPROPER_CAPTURE_RELEASE = 1324, - /** 1610: The origin resolution of the remote video is beyond the range where the super-resolution algorithm can be applied. + /** 1610: The original resolution of the remote user's video is beyond the range where super resolution can be applied. */ WARN_SUPER_RESOLUTION_STREAM_OVER_LIMITATION = 1610, - /** 1611: Another user is already using the super-resolution algorithm. + /** 1611: Super resolution is already being used to boost another remote user's video. */ WARN_SUPER_RESOLUTION_USER_COUNT_OVER_LIMITATION = 1611, - /** 1612: The device does not support the super-resolution algorithm. + /** 1612: The device does not support using super resolution. */ WARN_SUPER_RESOLUTION_DEVICE_NOT_SUPPORTED = 1612, /// @cond @@ -379,7 +398,8 @@ enum ERROR_CODE_TYPE { /** 117: The data stream transmission timed out. */ ERR_STREAM_MESSAGE_TIMEOUT = 117, - /** 119: Switching roles fail. Please try to rejoin the channel. + /** **DEPRECATED** 119: Deprecated as of v3.6.1. Use CLIENT_ROLE_CHANGE_FAILED_REASON in the \ref agora::rtc::IRtcEngineEventHandler::onClientRoleChangeFailed "onClientRoleChangeFailed" callback instead. + * Switching roles fail. Please try to rejoin the channel. */ ERR_SET_CLIENT_ROLE_NOT_AUTHORIZED = 119, /** 120: Decryption fails. The user may have used a different encryption password to join the channel. Check your settings or try rejoining the channel. @@ -411,7 +431,6 @@ enum ERROR_CODE_TYPE { ERR_ENCRYPTED_STREAM_NOT_ALLOWED_PUBLISH = 130, /** 134: The user account is invalid. */ ERR_INVALID_USER_ACCOUNT = 134, - /** 151: CDN related errors. Remove the original URL address and add a new one by calling the \ref agora::rtc::IRtcEngine::removePublishStreamUrl "removePublishStreamUrl" and \ref agora::rtc::IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" methods. */ ERR_PUBLISH_STREAM_CDN_ERROR = 151, @@ -436,16 +455,13 @@ enum ERROR_CODE_TYPE { * */ ERR_MODULE_NOT_FOUND = 157, - /// @cond - /** 158: The dynamical library for the super-resolution algorithm is not integrated. - * When you call the \ref agora::rtc::IRtcEngine::enableRemoteSuperResolution "enableRemoteSuperResolution" method but - * do not integrate the dynamical library for the super-resolution algorithm - * into your project, the SDK reports this error code. - */ - ERR_MODULE_SUPER_RESOLUTION_NOT_FOUND = 158, - /// @endcond - /** 160: The recording operation has been performed. + /** 160: The client is already recording audio. To start a new recording, + * call \ref agora::rtc::IRtcEngine::stopAudioRecording "stopAudioRecording" to stop + * the current recording first, and then + * call \ref agora::rtc::IRtcEngine::startAudioRecording(const AudioRecordingConfiguration&) "startAudioRecording". + * + * @since v3.4.0 */ ERR_ALREADY_IN_RECORDING = 160, @@ -708,10 +724,11 @@ enum ERROR_CODE_TYPE { ERR_ADM_NO_PLAYOUT_DEVICE = 1360, // VDM error code starts from 1500 - + /// @cond /** 1500: Video Device Module: There is no camera device. */ ERR_VDM_CAMERA_NO_DEVICE = 1500, + /// @endcond /** 1501: Video Device Module: The camera is unauthorized. */ @@ -735,6 +752,12 @@ enum ERROR_CODE_TYPE { /** 1603: Video Device Module: An error occurs in setting the video encoder. */ ERR_VCM_ENCODER_SET_ERROR = 1603, + /** 1735: (Windows only) The Windows Audio service is disabled. You need to + * either enable the Windows Audio service or restart the device. + * + * @since v3.5.0 + */ + ERR_ADM_WIN_CORE_SERVRE_SHUT_DOWN = 1735, }; /** Output log filter level. */ @@ -764,7 +787,7 @@ enum LOG_FILTER_TYPE { * @since v3.3.0 */ enum class LOG_LEVEL { - /** 0: Do not output any log. */ + /** 0x0000: Do not output any log. */ LOG_LEVEL_NONE = 0x0000, /** 0x0001: (Default) Output logs of the FATAL, ERROR, WARN and INFO level. We recommend setting your log filter as this level. */ diff --git a/Android/APIExample/lib-raw-data/src/main/cpp/include/IAgoraMediaEngine.h b/Android/APIExample/lib-raw-data/src/main/cpp/include/IAgoraMediaEngine.h index 9690d8840..6f7fd88c2 100644 --- a/Android/APIExample/lib-raw-data/src/main/cpp/include/IAgoraMediaEngine.h +++ b/Android/APIExample/lib-raw-data/src/main/cpp/include/IAgoraMediaEngine.h @@ -1,6 +1,7 @@ #ifndef AGORA_MEDIA_ENGINE_H #define AGORA_MEDIA_ENGINE_H #include +#include "AgoraBase.h" namespace agora { namespace media { @@ -15,11 +16,64 @@ enum MEDIA_SOURCE_TYPE { AUDIO_RECORDING_SOURCE = 1, }; +/** + * The channel mode. Set in \ref agora::rtc::IRtcEngine::setAudioMixingDualMonoMode "setAudioMixingDualMonoMode". + * + * @since v3.5.1 + */ +enum AUDIO_MIXING_DUAL_MONO_MODE { + /** + * 0: Original mode. + */ + AUDIO_MIXING_DUAL_MONO_AUTO = 0, + /** + * 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_MIXING_DUAL_MONO_L = 1, + /** + * 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_MIXING_DUAL_MONO_R = 2, + /** + * 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. + */ + AUDIO_MIXING_DUAL_MONO_MIX = 3 +}; +/** + * The push position of the external audio frame. + * Set in \ref IMediaEngine::pushAudioFrame(int32_t, IAudioFrameObserver::AudioFrame*) "pushAudioFrame" + * or \ref IMediaEngine::setExternalAudioSourceVolume "setExternalAudioSourceVolume". + * + * @since v3.5.1 + */ +enum AUDIO_EXTERNAL_SOURCE_POSITION { + /** 0: The position before local playback. If you need to play the external audio frame on the local client, + * set this position. + */ + AUDIO_EXTERNAL_PLAYOUT_SOURCE = 0, + /** 1: The position after audio capture and before audio pre-processing. If you need the audio module of the SDK + * to process the external audio frame, set this position. + */ + AUDIO_EXTERNAL_RECORD_SOURCE_PRE_PROCESS = 1, + /** 2: The position after audio pre-processing and before audio encoding. If you do not need the audio module of + * the SDK to process the external audio frame, set this position. + */ + AUDIO_EXTERNAL_RECORD_SOURCE_POST_PROCESS = 2, +}; + /** * The IAudioFrameObserver class. */ class IAudioFrameObserver { public: + IAudioFrameObserver() {} + virtual ~IAudioFrameObserver() {} /** The frame type. */ enum AUDIO_FRAME_TYPE { /** 0: PCM16. */ @@ -59,43 +113,64 @@ class IAudioFrameObserver { }; public: - /** Retrieves the captured audio frame. - - @param audioFrame Pointer to AudioFrame. - @return - - true: Valid buffer in AudioFrame, and the captured audio frame is sent out. - - false: Invalid buffer in AudioFrame, and the captured audio frame is discarded. + /** Gets the captured audio frame. + * + * @note To ensure that the captured audio frame has the expected format, + * Agora recommends that you + * call \ref agora::rtc::IRtcEngine::setRecordingAudioFrameParameters "setRecordingAudioFrameParameters" + * after calling \ref IMediaEngine::registerAudioFrameObserver "registerAudioFrameObserver" to + * set the audio capturing format. + * + * @param audioFrame Pointer to AudioFrame. + * @return + * - true: Valid buffer in AudioFrame, and the captured audio frame is sent out. + * - false: Invalid buffer in AudioFrame, and the captured audio frame is discarded. */ virtual bool onRecordAudioFrame(AudioFrame& audioFrame) = 0; - /** Retrieves the audio playback frame for getting the audio. - - @param audioFrame Pointer to AudioFrame. - @return - - true: Valid buffer in AudioFrame, and the audio playback frame is sent out. - - false: Invalid buffer in AudioFrame, and the audio playback frame is discarded. + /** Gets the audio playback frame for getting the audio. + * + * @note To ensure that the audio playback frame has the expected format, Agora + * recommends that you call \ref agora::rtc::IRtcEngine::setPlaybackAudioFrameParameters "setPlaybackAudioFrameParameters" + * after calling \ref IMediaEngine::registerAudioFrameObserver "registerAudioFrameObserver" to + * set the audio playback format. + * + * @param audioFrame Pointer to AudioFrame. + * @return + * - true: Valid buffer in AudioFrame, and the audio playback frame is sent out. + * - false: Invalid buffer in AudioFrame, and the audio playback frame is discarded. */ virtual bool onPlaybackAudioFrame(AudioFrame& audioFrame) = 0; - /** Retrieves the mixed captured and playback audio frame. - - - @note This callback only returns the single-channel data. - - @param audioFrame Pointer to AudioFrame. - @return - - true: Valid buffer in AudioFrame and the mixed captured and playback audio frame is sent out. - - false: Invalid buffer in AudioFrame and the mixed captured and playback audio frame is discarded. + /** Gets the mixed captured and playback audio frame. + * + * @note + * - This callback only returns the single-channel data. + * - To ensure that the mixed captured and playback audio frame has the + * expected format, Agora recommends that you call + * \ref agora::rtc::IRtcEngine::setMixedAudioFrameParameters "setMixedAudioFrameParameters" + * after calling \ref IMediaEngine::registerAudioFrameObserver "registerAudioFrameObserver" to + * set the mixed audio format. + * + * @param audioFrame Pointer to AudioFrame. + * @return + * - true: Valid buffer in AudioFrame and the mixed captured and playback audio frame is sent out. + * - false: Invalid buffer in AudioFrame and the mixed captured and playback audio frame is discarded. */ virtual bool onMixedAudioFrame(AudioFrame& audioFrame) = 0; - /** Retrieves the audio frame of a specified user before mixing. - - The SDK triggers this callback if isMultipleChannelFrameWanted returns false. - - @param uid The user ID - @param audioFrame Pointer to AudioFrame. - @return - - true: Valid buffer in AudioFrame, and the mixed captured and playback audio frame is sent out. - - false: Invalid buffer in AudioFrame, and the mixed captured and playback audio frame is discarded. - */ + /** Gets the audio frame of a specified user before mixing. + * + * The SDK triggers this callback if \ref IAudioFrameObserver::isMultipleChannelFrameWanted "isMultipleChannelFrameWanted" returns false. + * + * @note To ensure that the audio playback frame has the expected format, Agora + * recommends that you call \ref agora::rtc::IRtcEngine::setPlaybackAudioFrameParameters "setPlaybackAudioFrameParameters" + * after calling \ref IMediaEngine::registerAudioFrameObserver "registerAudioFrameObserver" to + * set the audio playback format. + * + * @param uid The user ID + * @param audioFrame Pointer to AudioFrame. + * @return + * - true: Valid buffer in AudioFrame, and the mixed captured and playback audio frame is sent out. + * - false: Invalid buffer in AudioFrame, and the mixed captured and playback audio frame is discarded. + */ virtual bool onPlaybackAudioFrameBeforeMixing(unsigned int uid, AudioFrame& audioFrame) = 0; /** Determines whether to receive audio data from multiple channels. @@ -121,18 +196,23 @@ class IAudioFrameObserver { virtual bool isMultipleChannelFrameWanted() { return false; } /** Gets the before-mixing playback audio frame from multiple channels. - - After you successfully register the audio frame observer, if you set the return - value of \ref IAudioFrameObserver::isMultipleChannelFrameWanted "isMultipleChannelFrameWanted" as true, the SDK triggers this callback each - time it receives a before-mixing audio frame from any of the channel. - - @param channelId The channel ID of this audio frame. - @param uid The ID of the user sending this audio frame. - @param audioFrame The pointer to AudioFrame. - @return - - `true`: The data in AudioFrame is valid, and send this audio frame. - - `false`: The data in AudioFrame in invalid, and do not send this audio frame. - */ + * + * After you successfully register the audio frame observer, if you set the return + * value of \ref IAudioFrameObserver::isMultipleChannelFrameWanted "isMultipleChannelFrameWanted" as true, the SDK triggers this callback each + * time it receives a before-mixing audio frame from any of the channel. + * + * @note To ensure that the audio playback frame has the expected format, Agora + * recommends that you call \ref agora::rtc::IRtcEngine::setPlaybackAudioFrameParameters "setPlaybackAudioFrameParameters" + * after calling \ref IMediaEngine::registerAudioFrameObserver "registerAudioFrameObserver" to + * set the audio playback format. + * + * @param channelId The channel ID of this audio frame. + * @param uid The ID of the user sending this audio frame. + * @param audioFrame The pointer to AudioFrame. + * @return + * - `true`: The data in AudioFrame is valid, and send this audio frame. + * - `false`: The data in AudioFrame in invalid, and do not send this audio frame. + */ virtual bool onPlaybackAudioFrameBeforeMixingEx(const char* channelId, unsigned int uid, AudioFrame& audioFrame) { return true; } }; @@ -141,14 +221,16 @@ class IAudioFrameObserver { */ class IVideoFrameObserver { public: + IVideoFrameObserver() {} + virtual ~IVideoFrameObserver() {} /** The video frame type. */ enum VIDEO_FRAME_TYPE { /** - * 0: YUV420 + * 0: (Default) YUV 420 */ FRAME_TYPE_YUV420 = 0, // YUV 420 format /** - * 1: YUV422 + * 1: YUV 422 */ FRAME_TYPE_YUV422 = 1, // YUV 422 format /** @@ -173,7 +255,7 @@ class IVideoFrameObserver { */ POSITION_PRE_ENCODER = 1 << 2, }; - /** Video frame information. The video data format is YUV420. The buffer provides a pointer to a pointer. The interface cannot modify the pointer of the buffer, but can modify the content of the buffer only. + /** Video frame information. The video data format is YUV 420. The buffer provides a pointer to a pointer. The interface cannot modify the pointer of the buffer, but can modify the content of the buffer only. */ struct VideoFrame { VIDEO_FRAME_TYPE type; @@ -183,32 +265,37 @@ class IVideoFrameObserver { /** Video pixel height. */ int height; // height of video frame - /** Line span of the Y buffer within the YUV data. + /** + * For YUV data, the line span of the Y buffer; for RGBA data, the total data length. */ int yStride; // stride of Y data buffer - /** Line span of the U buffer within the YUV data. + /** + * For YUV data, the line span of the U buffer; for RGBA data, the value is 0. */ int uStride; // stride of U data buffer - /** Line span of the V buffer within the YUV data. + /** + * For YUV data, the line span of the V buffer; for RGBA data, the value is 0. */ int vStride; // stride of V data buffer - /** Pointer to the Y buffer pointer within the YUV data. + /** + * For YUV data, the pointer to the Y buffer; for RGBA data, the data buffer. */ void* yBuffer; // Y data buffer - /** Pointer to the U buffer pointer within the YUV data. + /** + * For YUV data, the pointer to the U buffer; for RGBA data, the value is 0. */ void* uBuffer; // U data buffer - /** Pointer to the V buffer pointer within the YUV data. + /** + * For YUV data, the pointer to the V buffer; for RGBA data, the value is 0. */ void* vBuffer; // V data buffer - /** Set the rotation of this frame before rendering the video. Supports 0, 90, 180, 270 degrees clockwise. + /** The clockwise rotation angle of the video frame. The supported values are 0, 90, 180, or 270 degrees. */ int rotation; // rotation of this frame (0, 90, 180, 270) - /** The timestamp (ms) of the external audio frame. It is mandatory. You can use this parameter for the following purposes: - - Restore the order of the captured audio frame. - - Synchronize audio and video frames in video-related scenarios, including scenarios where external video sources are used. - @note This timestamp is for rendering the video stream, and not for capturing the video stream. - */ + /** + * The Unix timestamp (ms) when the video frame is rendered. This timestamp can be used to guide the rendering of + * the video frame. This parameter is required. + */ int64_t renderTimeMs; int avsync_type; }; @@ -226,9 +313,9 @@ class IVideoFrameObserver { * - The video data that this callback gets has not been pre-processed, without the watermark, the cropped content, the rotation, and the image enhancement. * * @param videoFrame Pointer to VideoFrame. - * @return Whether or not to ignore the current video frame if the pre-processing fails: - * - true: Do not ignore. - * - false: Ignore the current video frame, and do not send it back to the SDK. + * @return + * - true: Sets the SDK to receive the video frame. + * - false: Sets the SDK to discard the video frame. */ virtual bool onCaptureVideoFrame(VideoFrame& videoFrame) = 0; /** @since v3.0.0 @@ -245,15 +332,18 @@ class IVideoFrameObserver { * - This callback does not support sending processed RGBA video data back to the SDK. * * @param videoFrame A pointer to VideoFrame - * @return Whether to ignore the current video frame if the processing fails: - * - true: Do not ignore the current video frame. - * - false: Ignore the current video frame, and do not send it back to the SDK. + * @return + * - true: Sets the SDK to receive the video frame. + * - false: Sets the SDK to discard the video frame. */ virtual bool onPreEncodeVideoFrame(VideoFrame& videoFrame) { return true; } /** Occurs each time the SDK receives a video frame sent by the remote user. * - * After you successfully register the video frame observer and isMultipleChannelFrameWanted return false, the SDK triggers this callback each time a video frame is received. - * In this callback, you can get the video data sent by the remote user. You can then post-process the data according to your scenarios. + * After you successfully register the video frame observer and + * \ref IVideoFrameObserver::isMultipleChannelFrameWanted "isMultipleChannelFrameWanted" + * return false, the SDK triggers this callback each time a video frame is received. + * In this callback, you can get the video data sent by the remote user. You can then + * post-process the data according to your scenarios. * * After post-processing, you can send the processed data back to the SDK by setting the `videoFrame` parameter in this callback. * @@ -262,67 +352,73 @@ class IVideoFrameObserver { * * @param uid ID of the remote user who sends the current video frame. * @param videoFrame Pointer to VideoFrame. - * @return Whether or not to ignore the current video frame if the post-processing fails: - * - true: Do not ignore. - * - false: Ignore the current video frame, and do not send it back to the SDK. + * @return + * - true: Sets the SDK to receive the video frame. + * - false: Sets the SDK to discard the video frame. */ virtual bool onRenderVideoFrame(unsigned int uid, VideoFrame& videoFrame) = 0; /** Occurs each time the SDK receives a video frame and prompts you to set the video format. * - * YUV420 is the default video format. If you want to receive other video formats, register this callback in the IVideoFrameObserver class. + * YUV 420 is the default video format. If you want to receive other video formats, register this callback in the IVideoFrameObserver class. * * After you successfully register the video frame observer, the SDK triggers this callback each time it receives a video frame. * You need to set your preferred video data in the return value of this callback. * * @return Sets the video format: #VIDEO_FRAME_TYPE - * - #FRAME_TYPE_YUV420 (0): (Default) YUV420. - * - #FRAME_TYPE_RGBA (2): RGBA */ virtual VIDEO_FRAME_TYPE getVideoFormatPreference() { return FRAME_TYPE_YUV420; } - /** Occurs each time the SDK receives a video frame and prompts you whether or not to rotate the captured video according to the rotation member in the VideoFrame class. + /** Occurs each time the SDK receives a video frame and prompts you whether to + * rotate the raw video frame according to the rotation member in the VideoFrame class. * - * The SDK does not rotate the captured video by default. If you want to rotate the captured video according to the rotation member in the VideoFrame class, register this callback in the IVideoFrameObserver class. + * The SDK does not rotate the raw video frame by default. If you want to receive + * the raw video frame rotated according to the rotation member in the VideoFrame + * class, register this callback in the IVideoFrameObserver class. * - * After you successfully register the video frame observer, the SDK triggers this callback each time it receives a video frame. You need to set whether or not to rotate the video frame in the return value of this callback. + * After you successfully register the video frame observer, the SDK triggers this + * callback each time it receives a video frame. You need to set whether to rotate + * the raw video frame in the return value of this callback. * - * @note - * This callback applies to RGBA video data only. + * @note This callback applies to the video frame in the YUV 420 and RGBA formats only. * - * @return Sets whether or not to rotate the captured video: + * @return Sets whether to rotate the raw video frame: * - true: Rotate. - * - false: （Default) Do not rotate. + * - false: (Default) Do not rotate. */ virtual bool getRotationApplied() { return false; } - /** Occurs each time the SDK receives a video frame and prompts you whether or not to mirror the captured video. + /** Occurs each time the SDK receives a video frame and prompts you whether to mirror the raw video frame. * - * The SDK does not mirror the captured video by default. Register this callback in the IVideoFrameObserver class if you want to mirror the captured video. + * The SDK does not mirror the raw video frame by default. If you want to receive the raw video frame mirrored, register this callback in the IVideoFrameObserver class. * * After you successfully register the video frame observer, the SDK triggers this callback each time a video frame is received. - * You need to set whether or not to mirror the captured video in the return value of this callback. + * You need to set whether to mirror the raw video frame in the return value of this callback. * - * @note - * This callback applies to RGBA video data only. + * @note This callback applies to the video frame in the YUV 420 and RGBA formats only. * - * @return Sets whether or not to mirror the captured video: + * @return Sets whether to mirror the raw video frame: * - true: Mirror. * - false: (Default) Do not mirror. */ virtual bool getMirrorApplied() { return false; } - /** @since v3.0.0 - - Sets whether to output the acquired video frame smoothly. - - If you want the video frames acquired from \ref IVideoFrameObserver::onRenderVideoFrame "onRenderVideoFrame" to be more evenly spaced, you can register the `getSmoothRenderingEnabled` callback in the `IVideoFrameObserver` class and set its return value as `true`. - - @note - - Register this callback before joining a channel. - - This callback applies to scenarios where the acquired video frame is self-rendered after being processed, not to scenarios where the video frame is sent back to the SDK after being processed. - - @return Set whether or not to smooth the video frames: - - true: Smooth the video frame. - - false: (Default) Do not smooth. + /** + * Sets whether to output the acquired video frame smoothly. + * + * @since v3.0.0 + * + * @deprecated As of v3.2.0, this callback function is deprecated, and the SDK + * smooths the video frames output by `onRenderVideoFrame` and `onRenderVideoFrameEx` by default. + * + * If you want the video frames acquired from `onRenderVideoFrame` + * or `onRenderVideoFrameEx` to be more evenly spaced, you can register the `getSmoothRenderingEnabled` callback in the `IVideoFrameObserver` class and set its return value as `true`. + * + * @note + * - Register this callback before joining a channel. + * - This callback applies to scenarios where the acquired video frame is self-rendered after being processed, not to scenarios where the video frame is sent back to the SDK after being processed. + * + * @return Set whether to smooth the video frames: + * - true: Smooth the video frame. + * - false: (Default) Do not smooth. */ - virtual bool getSmoothRenderingEnabled() { return false; } + virtual bool getSmoothRenderingEnabled() AGORA_DEPRECATED_ATTRIBUTE { return false; } /** * Sets the frame position for the video observer. * @since v3.0.1 @@ -334,7 +430,7 @@ class IVideoFrameObserver { * - `POSITION_PRE_ENCODER(1 << 2)`: The position before encoding the video data, which corresponds to the \ref onPreEncodeVideoFrame "onPreEncodeVideoFrame" callback. * * @note - * - Use '|' (the OR operator) to observe multiple frame positions. + * - To observe multiple frame positions, use '|' (the OR operator). * - This callback observes `POSITION_POST_CAPTURER(1 << 0)` and `POSITION_PRE_RENDERER(1 << 1)` by default. * - To conserve the system consumption, you can reduce the number of frame positions that you want to observe. * @@ -345,6 +441,8 @@ class IVideoFrameObserver { /** Determines whether to receive video data from multiple channels. + @since v3.0.1 + After you register the video frame observer, the SDK triggers this callback every time it captures a video frame. @@ -364,22 +462,22 @@ class IVideoFrameObserver { virtual bool isMultipleChannelFrameWanted() { return false; } /** Gets the video frame from multiple channels. - - After you successfully register the video frame observer, if you set the return value of - \ref IVideoFrameObserver::isMultipleChannelFrameWanted "isMultipleChannelFrameWanted" as true, the SDK triggers this callback each time it receives a video frame - from any of the channel. - - You can process the video data retrieved from this callback according to your scenario, and send the - processed data back to the SDK using the `videoFrame` parameter in this callback. - - @note This callback does not support sending RGBA video data back to the SDK. - - @param channelId The channel ID of this video frame. - @param uid The ID of the user sending this video frame. - @param videoFrame The pointer to VideoFrame. - @return Whether to send this video frame to the SDK if post-processing fails: - - `true`: Send this video frame. - - `false`: Do not send this video frame. + * + * After you successfully register the video frame observer, if you set the return value of + * \ref IVideoFrameObserver::isMultipleChannelFrameWanted "isMultipleChannelFrameWanted" as true, the SDK triggers this callback each time it receives a video frame + * from any of the channel. + * + * You can process the video data retrieved from this callback according to your scenario, and send the + * processed data back to the SDK using the `videoFrame` parameter in this callback. + * + * @note This callback does not support sending RGBA video data back to the SDK. + * + * @param channelId The channel ID of this video frame. + * @param uid The ID of the user sending this video frame. + * @param videoFrame The pointer to VideoFrame. + * @return + * - true: Sets the SDK to receive the video frame. + * - false: Sets the SDK to discard the video frame. */ virtual bool onRenderVideoFrameEx(const char* channelId, unsigned int uid, VideoFrame& videoFrame) { return true; } }; @@ -432,26 +530,26 @@ class IVideoFrame { - < 0: Failure. */ virtual int convertFrame(VIDEO_TYPE dst_video_type, int dst_sample_size, unsigned char* dst_frame) const = 0; - /** Retrieves the specified component in the YUV space. + /** Gets the specified component in the YUV space. @param type Component type: #PLANE_TYPE */ virtual int allocated_size(PLANE_TYPE type) const = 0; - /** Retrieves the stride of the specified component in the YUV space. + /** Gets the stride of the specified component in the YUV space. @param type Component type: #PLANE_TYPE */ virtual int stride(PLANE_TYPE type) const = 0; - /** Retrieves the width of the frame. + /** Gets the width of the frame. */ virtual int width() const = 0; - /** Retrieves the height of the frame. + /** Gets the height of the frame. */ virtual int height() const = 0; - /** Retrieves the timestamp (ms) of the frame. + /** Gets the timestamp (ms) of the frame. */ virtual unsigned int timestamp() const = 0; - /** Retrieves the render time (ms). + /** Gets the render time (ms). */ virtual int64_t render_time_ms() const = 0; /** Checks if a plane is of zero size. @@ -519,12 +617,19 @@ class IExternalVideoRenderFactory { /** The external video frame. */ struct ExternalVideoFrame { - /** The video buffer type. + /** + * The data type of the video frame. + * + * @since v3.5.0 */ enum VIDEO_BUFFER_TYPE { - /** 1: The video buffer in the format of raw data. + /** 1: The data type is raw data. */ VIDEO_BUFFER_RAW_DATA = 1, + /** + * 2: The data type is the pixel. + */ + VIDEO_BUFFER_PIXEL_BUFFER = 2 }; /** The video pixel format. @@ -559,6 +664,12 @@ struct ExternalVideoFrame { /** 16: The video pixel format is I422. */ VIDEO_PIXEL_I422 = 16, + /** 17: The video pixel format is GL_TEXTURE_2D. + */ + VIDEO_TEXTURE_2D = 17, + /** 18: The video pixel format is GL_TEXTURE_OES. + */ + VIDEO_TEXTURE_OES = 18, }; /** The buffer type. See #VIDEO_BUFFER_TYPE @@ -597,56 +708,143 @@ struct ExternalVideoFrame { ExternalVideoFrame() : cropLeft(0), cropTop(0), cropRight(0), cropBottom(0), rotation(0) {} }; +/** + * The video frame type. + * + * @since v3.4.5 + */ +enum CODEC_VIDEO_FRAME_TYPE { + /** + * 0: (Default) A black frame + */ + CODEC_VIDEO_FRAME_TYPE_BLANK_FRAME = 0, + /** + * 3: The keyframe + */ + CODEC_VIDEO_FRAME_TYPE_KEY_FRAME = 3, + /** + * 4: The delta frame + */ + CODEC_VIDEO_FRAME_TYPE_DELTA_FRAME = 4, + /** + * 5: The B-frame + */ + CODEC_VIDEO_FRAME_TYPE_B_FRAME = 5, + /** + * Unknown frame + */ + CODEC_VIDEO_FRAME_TYPE_UNKNOW +}; -enum CODEC_VIDEO_FRAME_TYPE { CODEC_VIDEO_FRAME_TYPE_BLANK_FRAME = 0, CODEC_VIDEO_FRAME_TYPE_KEY_FRAME = 3, CODEC_VIDEO_FRAME_TYPE_DELTA_FRAME = 4, CODEC_VIDEO_FRAME_TYPE_B_FRAME = 5, CODEC_VIDEO_FRAME_TYPE_UNKNOW }; - -enum VIDEO_ROTATION { VIDEO_ROTATION_0 = 0, VIDEO_ROTATION_90 = 90, VIDEO_ROTATION_180 = 180, VIDEO_ROTATION_270 = 270 }; +/** + * The clockwise rotation angle of the video frame. + * + * @since v3.4.5 + */ +enum VIDEO_ROTATION { + /** + * 0: 0 degree + */ + VIDEO_ROTATION_0 = 0, + /** + * 90: 90 degrees + */ + VIDEO_ROTATION_90 = 90, + /** + * 180: 180 degrees + */ + VIDEO_ROTATION_180 = 180, + /** + * 270: 270 degrees + */ + VIDEO_ROTATION_270 = 270 +}; -/** Video codec types */ +/** + * The video codec type. + * + * @since v3.4.5 + */ enum VIDEO_CODEC_TYPE { - /** Standard VP8 */ + /** 1: VP8 */ VIDEO_CODEC_VP8 = 1, - /** Standard H264 */ + /** 2: (Default) H.264 */ VIDEO_CODEC_H264 = 2, - /** Enhanced VP8 */ + /** 3: Enhanced VP8 */ VIDEO_CODEC_EVP = 3, - /** Enhanced H264 */ + /** 4: Enhanced H.264 */ VIDEO_CODEC_E264 = 4, }; -/** * The struct of VideoEncodedFrame. */ +/** + * The VideoEncodedFrame struct. + * + * @since v3.4.5 + */ struct VideoEncodedFrame { VideoEncodedFrame() : codecType(VIDEO_CODEC_H264), width(0), height(0), buffer(nullptr), length(0), frameType(CODEC_VIDEO_FRAME_TYPE_BLANK_FRAME), rotation(VIDEO_ROTATION_0), renderTimeMs(0) {} /** - * The video codec: #VIDEO_CODEC_TYPE. + * The video codec type. See #VIDEO_CODEC_TYPE. */ VIDEO_CODEC_TYPE codecType; - /** * The width (px) of the video. */ + /** + * The width (px) of the video. + */ int width; - /** * The height (px) of the video. */ + /** + * The height (px) of the video. + */ int height; - /** * The buffer of video encoded frame */ + /** + * The video buffer, which is in the `DirectByteBuffer` data type. + */ const uint8_t* buffer; - /** * The Length of video encoded frame buffer. */ + /** + * The length (in bytes) of the video buffer. + */ unsigned int length; - /** * The frame type of the encoded video frame: #VIDEO_FRAME_TYPE. */ + /** + * The video frame type. See #CODEC_VIDEO_FRAME_TYPE. + */ CODEC_VIDEO_FRAME_TYPE frameType; - /** * The rotation information of the encoded video frame: #VIDEO_ROTATION. */ + /** + * The clockwise rotation angle of the video frame. See #VIDEO_ROTATION. + */ VIDEO_ROTATION rotation; - /** * The timestamp for rendering the video. */ + /** + * The Unix timestamp (ms) when the video frame is rendered. This timestamp + * can be used to guide the rendering of the video frame. This parameter is required. + */ int64_t renderTimeMs; }; - -class IVideoEncodedFrameReceiver { +/** + * The IVideoEncodedFrameObserver class. + * + * @since v3.4.5 + */ +class IVideoEncodedFrameObserver { public: /** - * Occurs each time the SDK receives an encoded video image. - * @param videoEncodedFrame The information of the encoded video frame: VideoEncodedFrame. + * Gets the local encoded video frame. + * + * @since v3.4.5 + * + * After you successfully register the local encoded video frame observer, + * the SDK triggers this callback each time a video frame is received. You + * can get the local encoded video frame in `videoEncodedFrame` and then + * process the video data according to your scenario. After processing, + * you can use `videoEncodedFrame` to pass the processed video data back to + * the SDK. + * + * @param videoEncodedFrame The local encoded video frame. See VideoEncodedFrame. * + * @return + * - true: Sets the SDK to receive the video frame. + * - false: Sets the SDK to discard the video frame. */ - virtual bool OnVideoEncodedFrameReceived(const VideoEncodedFrame& videoEncodedFrame) = 0; + virtual bool onVideoEncodedFrame(const VideoEncodedFrame& videoEncodedFrame) = 0; - virtual ~IVideoEncodedFrameReceiver() {} + virtual ~IVideoEncodedFrameObserver() {} }; class IMediaEngine { @@ -687,30 +885,78 @@ class IMediaEngine { virtual int registerVideoFrameObserver(IVideoFrameObserver* observer) = 0; /** **DEPRECATED** */ virtual int registerVideoRenderFactory(IExternalVideoRenderFactory* factory) = 0; - /** **DEPRECATED** Use \ref agora::media::IMediaEngine::pushAudioFrame(IAudioFrameObserver::AudioFrame* frame) "pushAudioFrame(IAudioFrameObserver::AudioFrame* frame)" instead. - - Pushes the external audio frame. - - @param type Type of audio capture device: #MEDIA_SOURCE_TYPE. - @param frame Audio frame pointer: \ref IAudioFrameObserver::AudioFrame "AudioFrame". - @param wrap Whether to use the placeholder. We recommend setting the default value. - - true: Use. - - false: (Default) Not use. - - @return - - 0: Success. - - < 0: Failure. + /** + * Pushes the external audio frame. + * + * @deprecated This method is deprecated. Use \ref IMediaEngine::pushAudioFrame(int32_t,IAudioFrameObserver::AudioFrame*) "pushAudioFrame" [3/3] instead. + * + * @param type Type of audio capture device: #MEDIA_SOURCE_TYPE. + * @param frame Audio frame pointer: \ref IAudioFrameObserver::AudioFrame "AudioFrame". + * @param wrap Whether to use the placeholder. We recommend setting the default value. + * - true: Use. + * - false: (Default) Not use. + * + * @return + * - 0: Success. + * - < 0: Failure. */ - virtual int pushAudioFrame(MEDIA_SOURCE_TYPE type, IAudioFrameObserver::AudioFrame* frame, bool wrap) = 0; + virtual int pushAudioFrame(MEDIA_SOURCE_TYPE type, IAudioFrameObserver::AudioFrame* frame, bool wrap) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Pushes the external audio frame. + * + * @deprecated This method is deprecated. Use \ref IMediaEngine::pushAudioFrame(int32_t,IAudioFrameObserver::AudioFrame*) "pushAudioFrame" [3/3] instead. + * + * @param frame Pointer to the audio frame: \ref IAudioFrameObserver::AudioFrame "AudioFrame". + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int pushAudioFrame(IAudioFrameObserver::AudioFrame* frame) AGORA_DEPRECATED_ATTRIBUTE = 0; - @param frame Pointer to the audio frame: \ref IAudioFrameObserver::AudioFrame "AudioFrame". - - @return - - 0: Success. - - < 0: Failure. + /** + * Pushes the external audio frame to a specified position. + * + * @since v3.5.1 + * + * According to your needs, you can push the external audio frame to one of three positions: after audio capture, + * before audio encoding, or before local playback. You can call this method multiple times to push one audio frame + * to multiple positions or multiple audio frames to different positions. For example, in the KTV scenario, you can + * push the singing voice to after audio capture, so that the singing voice can be processed by the SDK audio module + * and you can obtain a high-quality audio experience; you can also push the accompaniment to before audio encoding, + * so that the accompaniment is not affected by the audio module of the SDK. + * + * @note Call this method after joining a channel. + * + * @param sourcePos The push position of the external audio frame. See #AUDIO_EXTERNAL_SOURCE_POSITION. + * @param frame The external audio frame. See AudioFrame. The value range of the audio frame length (ms) is [10,60]. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `-2 (ERR_INVALID_ARGUMENT)`: The parameter is invalid. + * - `-12 (ERR_TOO_OFTEN)`: The call frequency is too high, causing the internal buffer to overflow. Call this method again after 30-50 ms. */ - virtual int pushAudioFrame(IAudioFrameObserver::AudioFrame* frame) = 0; + virtual int pushAudioFrame(int32_t sourcePos, IAudioFrameObserver::AudioFrame* frame) = 0; + /** + * Sets the volume of the external audio frame in the specified position. + * + * @since v3.5.1 + * + * You can call this method multiple times to set the volume of external audio frames in different positions. + * The volume setting takes effect for all external audio frames that are pushed to the specified position. + * + * @note Call this method after joining a channel. + * + * @param sourcePos The push position of the external audio frame. See #AUDIO_EXTERNAL_SOURCE_POSITION. + * @param volume The volume of the external audio frame. The value range is [0,100]. The default value is 100, which + * represents the original value. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `-2 (ERR_INVALID_ARGUMENT)`: The parameter is invalid. + */ + virtual int setExternalAudioSourceVolume(int32_t sourcePos, int32_t volume) = 0; /** Pulls the remote audio data. * * Before calling this method, call the @@ -722,8 +968,9 @@ class IMediaEngine { * audio data for playback. * * @note + * - Ensure that you call this method after joining a channel. * - Once you call the \ref agora::media::IMediaEngine::pullAudioFrame - * "pullAudioFrame" method successfully, the app will not retrieve any audio + * "pullAudioFrame" method successfully, the app will not get any audio * data from the * \ref agora::media::IAudioFrameObserver::onPlaybackAudioFrame * "onPlaybackAudioFrame" callback. @@ -774,8 +1021,28 @@ class IMediaEngine { - < 0: Failure. */ virtual int pushVideoFrame(ExternalVideoFrame* frame) = 0; - - virtual int registerVideoEncodedFrameReceiver(IVideoEncodedFrameReceiver* receiver) = 0; + /** + * Registers a local encoded video frame observer. + * + * @since v3.4.5 + * + * After you successfully register the local encoded video frame observer, + * the SDK triggers the callbacks that you have implemented in the + * IVideoEncodedFrameObserver class each time a video frame is received. + * + * @note + * - Ensure that you call this method before joining a channel. + * - The width and height of the video obtained through the observer may + * change due to poor network conditions and user-adjusted resolution. + * + * @param observer The local encoded video frame observer. See IVideoEncodedFrameObserver. + * If null is passed, the observer registration is canceled. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int registerVideoEncodedFrameObserver(IVideoEncodedFrameObserver* observer) = 0; }; } // namespace media diff --git a/Android/APIExample/lib-raw-data/src/main/cpp/include/IAgoraRtcChannel.h b/Android/APIExample/lib-raw-data/src/main/cpp/include/IAgoraRtcChannel.h index 5c5a6fafe..8f9e71506 100644 --- a/Android/APIExample/lib-raw-data/src/main/cpp/include/IAgoraRtcChannel.h +++ b/Android/APIExample/lib-raw-data/src/main/cpp/include/IAgoraRtcChannel.h @@ -69,7 +69,7 @@ class IChannelEventHandler { This callback notifies the application that a user leaves the channel when the application calls the \ref agora::rtc::IChannel::leaveChannel "leaveChannel" method. - The application retrieves information, such as the call duration and statistics. + The application gets information, such as the call duration and statistics. @param rtcChannel IChannel @param stats The call statistics: RtcStats. @@ -80,9 +80,9 @@ class IChannelEventHandler { } /** Occurs when the user role switches in the interactive live streaming. For example, from a host to an audience or vice versa. - This callback notifies the application of a user role switch when the application calls the \ref IChannel::setClientRole "setClientRole" method. + This callback notifies the application of a user role switch when the application calls the \ref IChannel::setClientRole "setClientRole" method, and successfully changed role. - The SDK triggers this callback when the local user switches the user role by calling the \ref IChannel::setClientRole "setClientRole" method after joining the channel. + The SDK triggers this callback when the local user switches the user role by calling the \ref IChannel::setClientRole "setClientRole" method after joining the channel, and successfully changed role. @param rtcChannel IChannel @param oldRole Role that the user switches from: #CLIENT_ROLE_TYPE. @@ -93,6 +93,21 @@ class IChannelEventHandler { (void)oldRole; (void)newRole; } + + /** Occurs when the user role switches in the interactive live streaming. For example, from a host to an audience or vice versa. + + This callback notifies the application of a user role switch when the application calls the \ref IChannel::setClientRole "setClientRole" method, and failed to change role. + + The SDK triggers this callback when the local user switches the user role by calling the \ref IChannel::setClientRole "setClientRole" method after joining the channel, and failed to change role. + @param reason The reason of changing client role failed. See #CLIENT_ROLE_CHANGE_FAILED_REASON. + @param currentRole Current Role that the user holds: #CLIENT_ROLE_TYPE. + */ + virtual void onClientRoleChangeFailed(IChannel* rtcChannel, CLIENT_ROLE_CHANGE_FAILED_REASON reason, CLIENT_ROLE_TYPE currentRole) { + (void)rtcChannel; + (void)reason; + (void)currentRole; + } + /** Occurs when a remote user (`COMMUNICATION`)/ host (`LIVE_BROADCASTING`) joins the channel. - `COMMUNICATION` profile: This callback notifies the application that another user joins the channel. If other users are already in the channel, the SDK also reports to the application on the existing users. @@ -181,13 +196,17 @@ class IChannelEventHandler { (void)stats; } /** Reports the last mile network quality of each user in the channel once every two seconds. - - Last mile refers to the connection between the local device and Agora's edge server. This callback reports once every two seconds the last mile network conditions of each user in the channel. If a channel includes multiple users, the SDK triggers this callback as many times. - - @param rtcChannel IChannel - @param uid User ID. The network quality of the user with this @p uid is reported. If @p uid is 0, the local network quality is reported. - @param txQuality Uplink transmission quality rating of the user in terms of the transmission bitrate, packet loss rate, average RTT (Round-Trip Time), and jitter of the uplink network. @p txQuality is a quality rating helping you understand how well the current uplink network conditions can support the selected VideoEncoderConfiguration. 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 may be inadequate for resolutions higher than 1280 * 720. See #QUALITY_TYPE. - @param rxQuality Downlink network quality rating of the user in terms of the packet loss rate, average RTT, and jitter of the downlink network. See #QUALITY_TYPE. + * + * Last mile refers to the connection between the local device and Agora's edge server. This callback reports once every + * two seconds the last mile network conditions of each user in the channel. If a channel includes multiple users, the + * SDK triggers this callback as many times. + * + * @note `txQuality` is `UNKNOWN` when the user is not sending a stream; `rxQuality` is `UNKNOWN` when the user is not receiving a stream. + * + * @param rtcChannel IChannel + * @param uid User ID. The network quality of the user with this @p uid is reported. If @p uid is 0, the local network quality is reported. + * @param txQuality Uplink transmission quality rating of the user in terms of the transmission bitrate, packet loss rate, average RTT (Round-Trip Time), and jitter of the uplink network. @p txQuality is a quality rating helping you understand how well the current uplink network conditions can support the selected VideoEncoderConfiguration. 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 may be inadequate for resolutions higher than 1280 * 720. See #QUALITY_TYPE. + * @param rxQuality Downlink network quality rating of the user in terms of the packet loss rate, average RTT, and jitter of the downlink network. See #QUALITY_TYPE. */ virtual void onNetworkQuality(IChannel* rtcChannel, uid_t uid, int txQuality, int rxQuality) { (void)rtcChannel; @@ -223,18 +242,19 @@ class IChannelEventHandler { (void)stats; } /** Occurs when the remote audio state changes. - - This callback indicates the state change of the remote audio stream. - @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. - - @param rtcChannel IChannel - @param uid ID of the remote user whose audio state changes. - @param state State of the remote audio. See #REMOTE_AUDIO_STATE. - @param reason The reason of the remote audio state change. - See #REMOTE_AUDIO_STATE_REASON. - @param elapsed Time elapsed (ms) from the local user calling the - \ref IChannel::joinChannel "joinChannel" method until the SDK - triggers this callback. + * + * This callback indicates the state change of the remote audio stream. + * + * @note This callback can be inaccurate when the number of users (in the `COMMUNICATION` profile) + * or hosts (in the `LIVE_BROADCASTING` profile) in a channel exceeds 17. + * + * @param rtcChannel IChannel + * @param uid ID of the remote user whose audio state changes. + * @param state State of the remote audio. See #REMOTE_AUDIO_STATE. + * @param reason The reason of the remote audio state change. See #REMOTE_AUDIO_STATE_REASON. + * @param elapsed Time elapsed (ms) from the local user calling the + * \ref IChannel::joinChannel "joinChannel" method until the SDK + * triggers this callback. */ virtual void onRemoteAudioStateChanged(IChannel* rtcChannel, uid_t uid, REMOTE_AUDIO_STATE state, REMOTE_AUDIO_STATE_REASON reason, int elapsed) { (void)rtcChannel; @@ -319,21 +339,23 @@ class IChannelEventHandler { (void)newState; (void)elapseSinceLastState; } - /// @cond - /** Reports whether the super-resolution algorithm is enabled. + + /** Reports whether the super resolution feature is successfully enabled. (beta feature) * - * @since v3.2.0 + * @since v3.5.1 * - * After calling \ref IRtcChannel::enableRemoteSuperResolution "enableRemoteSuperResolution", the SDK triggers this - * callback to report whether the super-resolution algorithm is successfully enabled. If not successfully enabled, - * you can use reason for troubleshooting. + * After calling \ref IChannel::enableRemoteSuperResolution "enableRemoteSuperResolution", the SDK triggers this + * callback to report whether super resolution is successfully enabled. If it is not successfully enabled, + * use `reason` for troubleshooting. * * @param rtcChannel IChannel - * @param uid The ID of the remote user. - * @param enabled Whether the super-resolution algorithm is successfully enabled: - * - true: The super-resolution algorithm is successfully enabled. - * - false: The super-resolution algorithm is not successfully enabled. - * @param reason The reason why the super-resolution algorithm is not successfully enabled. See #SUPER_RESOLUTION_STATE_REASON. + * @param uid The user ID of the remote user. + * @param enabled Whether super resolution is successfully enabled: + * - true: Super resolution is successfully enabled. + * - false: Super resolution is not successfully enabled. + * @param reason The reason why super resolution is not successfully enabled or the message + * that confirms success. See #SUPER_RESOLUTION_STATE_REASON. + * */ virtual void onUserSuperResolutionEnabled(IChannel* rtcChannel, uid_t uid, bool enabled, SUPER_RESOLUTION_STATE_REASON reason) { (void)rtcChannel; @@ -341,9 +363,8 @@ class IChannelEventHandler { (void)enabled; (void)reason; } - /// @endcond - /** Occurs when the most active speaker is detected. + /** Occurs when the most active remote speaker is detected. After a successful call of \ref IRtcEngine::enableAudioVolumeIndication(int, int, bool) "enableAudioVolumeIndication", the SDK continuously detects which remote user has the loudest volume. During the current period, the remote user, @@ -354,7 +375,7 @@ class IChannelEventHandler { - If the most active speaker changes to another user, the SDK triggers this callback again and reports the `uid` of the new active speaker. @param rtcChannel IChannel - @param uid The user ID of the most active speaker. + @param uid The user ID of the most active remote speaker. */ virtual void onActiveSpeaker(IChannel* rtcChannel, uid_t uid) { (void)rtcChannel; @@ -376,17 +397,17 @@ class IChannelEventHandler { (void)rotation; } /** Occurs when the remote video state changes. - - @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. - - @param rtcChannel IChannel - @param uid ID of the remote user whose video state changes. - @param state State of the remote video. See #REMOTE_VIDEO_STATE. - @param reason The reason of the remote video state change. See - #REMOTE_VIDEO_STATE_REASON. - @param elapsed Time elapsed (ms) from the local user calling the - \ref agora::rtc::IChannel::joinChannel "joinChannel" method until the - SDK triggers this callback. + * + * @note This callback can be inaccurate when the number of users (in the `COMMUNICATION` profile) or + * hosts (in the `LIVE_BROADCASTING` profile) in a channel exceeds 17. + * + * @param rtcChannel IChannel + * @param uid ID of the remote user whose video state changes. + * @param state State of the remote video. See #REMOTE_VIDEO_STATE. + * @param reason The reason of the remote video state change. See #REMOTE_VIDEO_STATE_REASON. + * @param elapsed Time elapsed (ms) from the local user calling the + * \ref agora::rtc::IChannel::joinChannel "joinChannel" method until the + * SDK triggers this callback. */ virtual void onRemoteVideoStateChanged(IChannel* rtcChannel, uid_t uid, REMOTE_VIDEO_STATE state, REMOTE_VIDEO_STATE_REASON reason, int elapsed) { (void)rtcChannel; @@ -453,22 +474,23 @@ class IChannelEventHandler { (void)code; } /** - Occurs when the state of the RTMP or RTMPS streaming changes. - - The SDK triggers this callback to report the result of the local user calling the \ref agora::rtc::IChannel::addPublishStreamUrl "addPublishStreamUrl" or \ref agora::rtc::IChannel::removePublishStreamUrl "removePublishStreamUrl" method. - - 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 *errCode* parameter. - - @param rtcChannel IChannel - @param url The CDN streaming URL. - @param state The RTMP or RTMPS streaming state. See: #RTMP_STREAM_PUBLISH_STATE. - @param errCode The detailed error information for streaming. See: #RTMP_STREAM_PUBLISH_ERROR. + * Occurs when the state of the RTMP or RTMPS streaming changes. + * + * When the CDN live streaming state changes, the SDK triggers this callback to report the current state and the reason + * why the state has changed. + * + * When exceptions occur, you can troubleshoot issues by referring to the detailed error descriptions in the *errCode* parameter. + * + * @param rtcChannel IChannel + * @param url The CDN streaming URL. + * @param state The RTMP or RTMPS streaming state. See: #RTMP_STREAM_PUBLISH_STATE. + * @param errCode The detailed error information for streaming. See: #RTMP_STREAM_PUBLISH_ERROR_TYPE. */ - virtual void onRtmpStreamingStateChanged(IChannel* rtcChannel, const char* url, RTMP_STREAM_PUBLISH_STATE state, RTMP_STREAM_PUBLISH_ERROR errCode) { + virtual void onRtmpStreamingStateChanged(IChannel* rtcChannel, const char* url, RTMP_STREAM_PUBLISH_STATE state, RTMP_STREAM_PUBLISH_ERROR_TYPE errCode) { (void)rtcChannel; (void)url; - (RTMP_STREAM_PUBLISH_STATE) state; - (RTMP_STREAM_PUBLISH_ERROR) errCode; + (void)state; + (void)errCode; } /** Reports events during the RTMP or RTMPS streaming. @@ -482,7 +504,7 @@ class IChannelEventHandler { virtual void onRtmpStreamingEvent(IChannel* rtcChannel, const char* url, RTMP_STREAMING_EVENT eventCode) { (void)rtcChannel; (void)url; - (RTMP_STREAMING_EVENT) eventCode; + (void)eventCode; } /** Occurs when the publisher's transcoding is updated. @@ -531,8 +553,8 @@ class IChannelEventHandler { * "setRemoteSubscribeFallbackOption" and set * @p option as #STREAM_FALLBACK_OPTION_AUDIO_ONLY, the SDK triggers this * callback when the remote media stream falls back to audio-only mode due - * to poor uplink conditions, or when the remote media stream switches - * back to the video after the uplink network condition improves. + * to poor downlink conditions, or when the remote media stream switches + * back to the video after the downlink network condition improves. * * @note Once the remote media stream switches to the low stream due to * poor network conditions, you can monitor the stream switch between a @@ -562,6 +584,21 @@ class IChannelEventHandler { (void)state; (void)reason; } + + /** Occurs when join success after calling \ref IRtcEngine::setLocalAccessPoint "setLocalAccessPoint" or \ref IRtcEngine::setCloudProxy "setCloudProxy" + @param rtcChannel IChannel + @param uid User ID of the user joining the channel. + @param proxyType type of proxy agora sdk connected, proxyType will be NONE_PROXY_TYPE if not connected to proxy(fallback). + @param localProxyIp local proxy ip list. if not join local proxy, it will be "". + @param elapsed Time elapsed (ms) from the user calling the \ref IRtcEngine::joinChannel "joinChannel" method until the SDK triggers this callback. + */ + virtual void onProxyConnected(IChannel* rtcChannel, uid_t uid, PROXY_TYPE proxyType, const char* localProxyIp, int elapsed) { + (void)rtcChannel; + (void)uid; + (void)proxyType; + (void)localProxyIp; + (void)elapsed; + } }; /** The IChannel class. */ @@ -588,68 +625,77 @@ class IChannel { */ virtual int setChannelEventHandler(IChannelEventHandler* channelEh) = 0; /** Joins the channel with a user ID. - - This method differs from the `joinChannel` method in the `IRtcEngine` class in the following aspects: - - | IChannel::joinChannel | IRtcEngine::joinChannel | - |------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------| - | Does not contain the `channelId` parameter, because `channelId` is specified when creating the `IChannel` object. | Contains the `channelId` parameter, which specifies the channel to join. | - | Contains the `options` parameter, which decides whether to subscribe to all streams before joining the channel. | Does not contain the `options` parameter. By default, users subscribe to all streams when joining the channel. | - | Users can join multiple channels simultaneously by creating multiple `IChannel` objects and calling the `joinChannel` method of each object. | Users can join only one channel. | - | By default, the SDK does not publish any stream after the user joins the channel. You need to call the publish method to do that. | By default, the SDK publishes streams once the user joins the channel. | - - Once the user joins the channel (switches to another channel), the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. If you do not want to subscribe to a specified stream or all remote streams, call the `mute` methods accordingly. - - @note - - If you are already in a channel, you cannot rejoin it with the same `uid`. - - We recommend using different UIDs for different channels. - - If you want to join the same channel from different devices, ensure that the UIDs 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` object. - - @param token The token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Windows). - @param info (Optional) Additional information about the channel. This parameter can be set as null. Other users in the channel do not receive this information. - @param uid The user ID. A 32-bit unsigned integer with a value ranging from 1 to (232-1). This parameter must be unique. If `uid` is not assigned (or set as `0`), the SDK assigns a `uid` and reports it in the \ref agora::rtc::IChannelEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" callback. The app must maintain this user ID. - @param options The channel media options: \ref agora::rtc::ChannelMediaOptions::ChannelMediaOptions "ChannelMediaOptions" - - @return - - 0(ERR_OK): Success. - - < 0: Failure. - - -2(ERR_INALID_ARGUMENT): The parameter is invalid. - - -3(ERR_NOT_READY): The SDK fails to be initialized. You can try re-initializing the SDK. - - -5(ERR_REFUSED): The request is rejected. This may be caused by the following: - - You have created an IChannel object with the same channel name. - - You have joined and published a stream in a channel created by the IChannel object. When you join a channel created by the IRtcEngine object, the SDK publishes the local audio and video streams to that channel by default. Because the SDK does not support publishing a local stream to more than one channel simultaneously, an error occurs in this occasion. - - -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method. + * + * Compared with the `joinChannel` method in the IRtcEngine class, this method supports joining multiple channels at + * a time by creating multiple IChannel objects and then calling `joinChannel` in each IChannel object. + * + * Once the user joins the channel, the user publishes the local audio and video streams and automatically + * subscribes to the audio and video streams of all the other users in the channel by default. Subscribing + * incurs all associated usage costs. To unsubscribe, set the `options` parameter or call the `mute` methods accordingly. + * + * @note + * - If you are already in a channel, you cannot rejoin it with the same `uid`. + * - We recommend using different UIDs for different channels. + * - If you want to join the same channel from different devices, ensure that the UIDs 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` object. + * + * @param token The token generated at your server. See [Authenticate Your Users with Tokens](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=All%20Platforms). + * @param info (Optional) Additional information about the channel. This parameter can be set as null. Other users in the channel do not receive this information. + * @param uid The user ID. A 32-bit unsigned integer with a value ranging from 1 to (232-1). This parameter must be unique. If `uid` is not assigned (or set as `0`), the SDK assigns a `uid` and reports it in the \ref agora::rtc::IChannelEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" callback. The app must maintain this user ID. + * @param options The channel media options: \ref agora::rtc::ChannelMediaOptions::ChannelMediaOptions "ChannelMediaOptions" + * + * @return + * - 0(ERR_OK): Success. + * - < 0: Failure. + * - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. + * - -3(ERR_NOT_READY): The SDK fails to be initialized. You can try re-initializing the SDK. + * - -5(ERR_REFUSED): The request is rejected. This may be caused by the following: + * - You have created an IChannel object with the same channel name. + * - You have joined and published a stream in a channel created by the IChannel object. When you join a channel created by the IRtcEngine object, the SDK publishes the local audio and video streams to that channel by default. Because the SDK does not support publishing a local stream to more than one channel simultaneously, an error occurs in this occasion. + * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method. + * - `ERR_JOIN_CHANNEL_REJECTED(-17)`: The request to join the channel is rejected. The SDK does not support + * joining the same IChannel channel repeatedly. Therefore, the SDK returns this error code when a user who has + * already joined an IChannel channel calls the joining channel method of this IChannel object. */ virtual int joinChannel(const char* token, const char* info, uid_t uid, const ChannelMediaOptions& options) = 0; /** Joins the channel with a user account. - - After the user successfully joins the channel, the SDK triggers the following callbacks: - - - The local client: \ref agora::rtc::IRtcEngineEventHandler::onLocalUserRegistered "onLocalUserRegistered" and \ref agora::rtc::IChannelEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" . - - The remote client: \ref agora::rtc::IChannelEventHandler::onUserJoined "onUserJoined" and \ref agora::rtc::IRtcEngineEventHandler::onUserInfoUpdated "onUserInfoUpdated" , if the user joining the channel is in the `COMMUNICATION` profile, or is a host in the `LIVE_BROADCASTING` profile. - - Once the user joins the channel (switches to another channel), the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. If you do not want to subscribe to a specified stream or all remote streams, call the `mute` methods accordingly. - - @note To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. - If a user joins the channel with the Agora Web SDK, ensure that the uid of the user is set to the same parameter type. - - @param token The token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Windows). - @param userAccount The user account. The maximum length of this parameter is 255 bytes. Ensure that the user account is unique and do not set it as null. Supported character scopes are: - - All lowercase English letters: a to z. - - All uppercase English letters: A to Z. - - All numeric characters: 0 to 9. - - The space character. - - Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",". - @param options The channel media options: \ref agora::rtc::ChannelMediaOptions::ChannelMediaOptions “ChannelMediaOptions”. - - @return - - 0: Success. - - < 0: Failure. - - #ERR_INVALID_ARGUMENT (-2) - - #ERR_NOT_READY (-3) - - #ERR_REFUSED (-5) - - #ERR_NOT_INITIALIZED (-7) + * + * Compared with the `joinChannelWithUserAccount` method in the IRtcEngine class, this method supports joining multiple channels at + * a time by creating multiple IChannel objects and then calling `joinChannelWithUserAccount` in each IChannel object. + * + * After the user successfully joins the channel, the SDK triggers the following callbacks: + * + * - The local client: \ref agora::rtc::IRtcEngineEventHandler::onLocalUserRegistered "onLocalUserRegistered" and \ref agora::rtc::IChannelEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" . + * - The remote client: \ref agora::rtc::IChannelEventHandler::onUserJoined "onUserJoined" and \ref agora::rtc::IRtcEngineEventHandler::onUserInfoUpdated "onUserInfoUpdated" , if the user joining the channel is in the `COMMUNICATION` profile, or is a host in the `LIVE_BROADCASTING` profile. + * + * Once the user joins the channel, the user publishes the local audio and video streams and + * automatically subscribes to the audio and video streams of all the other users in the channel by default. + * Subscribing incurs all associated usage costs. To unsubscribe, set the `options` parameters 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 uid of the user is set to the same parameter type. + * - Before using a String user name, ensure that you read [How can I use string user names](https://docs.agora.io/en/faq/string) for getting details about the limitations and implementation steps. + * + * @param token The token generated at your server. See [Authenticate Your Users with Tokens](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=All%20Platforms). + * @param userAccount The user account. The maximum length of this parameter is 255 bytes. Ensure that the user account is unique and do not set it as null. Supported character scopes are: + * - All lowercase English letters: a to z. + * - All uppercase English letters: A to Z. + * - All numeric characters: 0 to 9. + * - The space character. + * - Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",". + * @param options The channel media options: \ref agora::rtc::ChannelMediaOptions::ChannelMediaOptions “ChannelMediaOptions”. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - #ERR_INVALID_ARGUMENT (-2) + * - #ERR_NOT_READY (-3) + * - #ERR_REFUSED (-5) + * - #ERR_NOT_INITIALIZED (-7) + * - `ERR_JOIN_CHANNEL_REJECTED(-17)`: The request to join the channel is rejected. The SDK does not support + * joining the same IChannel channel repeatedly. Therefore, the SDK returns this error code when a user who has + * already joined an IChannel channel calls the joining channel method of this IChannel object. */ virtual int joinChannelWithUserAccount(const char* token, const char* userAccount, const ChannelMediaOptions& options) = 0; /** Allows a user to leave a channel, such as hanging up or exiting a call. @@ -668,20 +714,28 @@ class IChannel { - If you call the \ref IChannel::release "release" method immediately after the *leaveChannel* method, the *leaveChannel* process interrupts, and the \ref IChannelEventHandler::onLeaveChannel "onLeaveChannel" callback is not triggered. - If you call the *leaveChannel* method during a CDN live streaming, the SDK triggers the \ref IChannel::removePublishStreamUrl "removePublishStreamUrl" method. - @return - - 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. - */ + @return + - 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. + */ virtual int leaveChannel() = 0; + /// @cond + virtual int setAVSyncSource(const char* channelId, uid_t uid) = 0; + /// @endcond + /** Publishes the local stream to the channel. + @deprecated This method is deprecated as of v3.4.5. Use \ref IChannel::muteLocalAudioStream "muteLocalAudioStream" (false) + or \ref IChannel::muteLocalVideoStream "muteLocalVideoStream" (false) instead. + You must keep the following restrictions in mind when calling this method. Otherwise, the SDK returns the #ERR_REFUSED (5): - - This method publishes one stream only to the channel corresponding to the current `IChannel` object. - - In the interactive live streaming channel, only a host can call this method. To switch the client role, call \ref agora::rtc::IChannel::setClientRole "setClientRole" of the current `IChannel` object. + - This method publishes one stream only to the channel corresponding to the current IChannel object. + - In the interactive live streaming channel, only a host can call this method. + To switch the client role, call \ref IChannel::setClientRole "setClientRole" of the current IChannel object. - You can publish a stream to only one channel at a time. For details on joining multiple channels, see the advanced guide *Join Multiple Channels*. @return @@ -689,10 +743,13 @@ class IChannel { - < 0: Failure. - #ERR_REFUSED (5): The method call is refused. */ - virtual int publish() = 0; + virtual int publish() AGORA_DEPRECATED_ATTRIBUTE = 0; /** Stops publishing a stream to the channel. + @deprecated This method is deprecated as of v3.4.5. Use \ref IChannel::muteLocalAudioStream "muteLocalAudioStream" (true) + or \ref IChannel::muteLocalVideoStream "muteLocalVideoStream" (true) instead. + If you call this method in a channel where you are not publishing streams, the SDK returns #ERR_REFUSED (5). @return @@ -700,7 +757,7 @@ class IChannel { - < 0: Failure. - #ERR_REFUSED (5): The method call is refused. */ - virtual int unpublish() = 0; + virtual int unpublish() AGORA_DEPRECATED_ATTRIBUTE = 0; /** Gets the channel ID of the current `IChannel` object. @@ -709,7 +766,7 @@ class IChannel { - The empty string "", if the method call fails. */ virtual const char* channelId() = 0; - /** Retrieves the current call ID. + /** Gets the current call ID. When a user joins a channel on a client, a `callId` is generated to identify the call from the client. Feedback methods, such as \ref IRtcEngine::rate "rate" and \ref IRtcEngine::complain "complain", must be called after the call ends to submit feedback to the SDK. @@ -734,13 +791,13 @@ class IChannel { The application should call this method to get the new `token`. Failure to do so will result in the SDK disconnecting from the server. - @param token Pointer to the new token. + @param token The new token. @return - 0(ERR_OK): Success. - < 0: Failure. - -1(ERR_FAILED): A general error occurs (no specified reason). - - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. */ virtual int renewToken(const char* token) = 0; @@ -762,7 +819,7 @@ class IChannel { - 0: Success. - < 0: Failure. */ - virtual int setEncryptionSecret(const char* secret) = 0; + virtual int setEncryptionSecret(const char* secret) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Sets the built-in encryption mode. @deprecated Deprecated as of v3.1.0. Use the \ref agora::rtc::IChannel::enableEncryption "enableEncryption" instead. @@ -785,16 +842,25 @@ class IChannel { - 0: Success. - < 0: Failure. */ - virtual int setEncryptionMode(const char* encryptionMode) = 0; + virtual int setEncryptionMode(const char* encryptionMode) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Enables/Disables the built-in encryption. * * @since v3.1.0 * * In scenarios requiring high security, Agora recommends calling this method to enable the built-in encryption before joining a channel. * - * All users in the same channel must use the same encryption mode and encryption key. After a 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. + * After a user leaves the channel, the SDK automatically disables the built-in encryption. + * To re-enable the built-in encryption, call this method before the user joins the channel again. + * + * As of v3.4.5, Agora recommends using either the `AES_128_GCM2` or `AES_256_GCM2` encryption mode, + * both of which support adding a salt and are more secure. For details, see *Media Stream Encryption*. + * + * @warning All users in the same channel must use the same encryption mode, encryption key, and salt; otherwise, + * users cannot communicate with each other. * - * @note If you enable the built-in encryption, you cannot use the RTMP or RTMPS streaming function. + * @note + * - If you enable the built-in encryption, you cannot use the RTMP or RTMPS streaming function. + * - To enhance security, Agora recommends using a new key and salt every time you enable the media stream encryption. * * @param enabled Whether to enable the built-in encryption: * - true: Enable the built-in encryption. @@ -816,7 +882,7 @@ class IChannel { @note - The size of the packet sent to the network after processing should not exceed 1200 bytes, otherwise, the packet may fail to be sent. - Ensure that both receivers and senders call this method, otherwise, you may meet undefined behaviors such as no voice and black screen. - - When you use CDN live streaming, recording or storage functions, Agora doesn't recommend calling this method. + - When you use CDN live streaming and recording functions, Agora doesn't recommend calling this method. - Call this method before joining a channel. @param observer The registered packet observer. See IPacketObserver. @@ -842,43 +908,61 @@ class IChannel { - < 0: Failure. */ virtual int registerMediaMetadataObserver(IMetadataObserver* observer, IMetadataObserver::METADATA_TYPE type) = 0; - /** Sets the role of the user, such as a host or an audience (default), before joining a channel in the interactive live streaming. - - This method can be used to switch the user role in the interactive live streaming after the user joins a channel. - - In the `LIVE_BROADCASTING` profile, when a user switches user roles after joining a channel, a successful \ref agora::rtc::IChannel::setClientRole "setClientRole" method call triggers the following callbacks: - - The local client: \ref agora::rtc::IChannelEventHandler::onClientRoleChanged "onClientRoleChanged" - - The remote client: \ref agora::rtc::IChannelEventHandler::onUserJoined "onUserJoined" or \ref agora::rtc::IChannelEventHandler::onUserOffline "onUserOffline" (BECOME_AUDIENCE) - - @note - This method applies only to the `LIVE_BROADCASTING` profile. - - @param role Sets the role of the user. See #CLIENT_ROLE_TYPE. - @return - - 0: Success. - - < 0: Failure. + /** Sets the role of the user in interactive live streaming. + * + * In the `LIVE_BROADCASTING` channel profile, the + * SDK sets the user role as audience by default. You can call `setClientRole` to set the user role as host. + * + * You can call this method either before or after joining a channel. If you + * call this method to switch the user role after joining a channel, the SDK automatically does the following: + * - Calls \ref IChannel::muteLocalAudioStream "muteLocalAudioStream" and \ref IChannel::muteLocalVideoStream "muteLocalVideoStream" to + * change the publishing state. + * - Triggers \ref IChannelEventHandler::onClientRoleChanged "onClientRoleChanged" or \ref IChannelEventHandler::onClientRoleChangeFailed "onClientRoleChangeFailed" on the local client in 5s. + * - Triggers \ref IChannelEventHandler::onUserJoined "onUserJoined" or \ref IChannelEventHandler::onUserOffline "onUserOffline" (BECOME_AUDIENCE) + * on the remote client. + * + * @note This method applies to the `LIVE_BROADCASTING` profile only. + * + * @param role The role of a user in interactive live streaming. See #CLIENT_ROLE_TYPE. + * + * @return + * - 0(ERR_OK): Success. + * - < 0: Failure. + * - -1(ERR_FAILED): A general error occurs (no specified reason). + * - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. + * - -5 (ERR_REFUSED): The request is rejected. In multichannel scenarios, if you have set any of the following in + * one channel, the SDK returns this error code when the user switches the user role to host in another channel: + * - Call `joinChannel` with the `options` parameter and use the default settings `publishLocalAudio = true` or `publishLocalVideo = true`. + * - Call `setClientRole` to set the user role as host. + * - Call `muteLocalAudioStream(false)` or `muteLocalVideoStream(false)`. + * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. */ virtual int setClientRole(CLIENT_ROLE_TYPE role) = 0; - /** Sets the role of a user in interactive live streaming. + /** Sets the role of the user in interactive live streaming. * * @since v3.2.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: \ref IChannelEventHandler::onClientRoleChanged "onClientRoleChanged". - * - The remote client: \ref IChannelEventHandler::onUserJoined "onUserJoined" - * or \ref IChannelEventHandler::onUserOffline "onUserOffline". + * In the `LIVE_BROADCASTING` channel profile, the + * SDK sets the user role as audience by default. You can call `setClientRole` to set the user role as host. + * + * You can call this method either before or after joining a channel. If you + * call this method to switch the user role after joining a channel, the SDK automatically does the following: + * - Calls \ref IChannel::muteLocalAudioStream "muteLocalAudioStream" and \ref IChannel::muteLocalVideoStream "muteLocalVideoStream" to + * change the publishing state. + * - Triggers \ref IChannelEventHandler::onClientRoleChanged "onClientRoleChanged" or \ref IChannelEventHandler::onClientRoleChangeFailed "onClientRoleChangeFailed" on the local client in 5s. + * - Triggers \ref IChannelEventHandler::onUserJoined "onUserJoined" or \ref IChannelEventHandler::onUserOffline "onUserOffline" (BECOME_AUDIENCE) + * on the remote client. * * @note * - This method applies to the `LIVE_BROADCASTING` profile only. * - The difference between this method and \ref IChannel::setClientRole(CLIENT_ROLE_TYPE) "setClientRole" [1/2] is that * this method can set the user level in addition to the user role. - * - The user role determines the permissions that the SDK grants to a user, such as permission to send local - * streams, receive remote streams, and push streams to a CDN address. - * - The user level determines the level of services that a user can enjoy within the permissions of the user's - * role. For example, an audience can choose to receive remote streams with low latency or ultra low latency. Levels - * affect prices. + * - The user role determines the permissions that the SDK grants to a user, such as permission to send local streams, + * receive remote streams, and push streams to a CDN address. + * - The user level determines the level of services that a user can enjoy within the permissions of the user's role. + * For example, an audience member can choose to receive remote streams with low latency or ultra low latency. + * **User level affects the pricing of services.** * * @param role The role of a user in interactive live streaming. See #CLIENT_ROLE_TYPE. * @param options The detailed options of a user, including user level. See ClientRoleOptions. @@ -887,7 +971,12 @@ class IChannel { * - 0(ERR_OK): Success. * - < 0: Failure. * - -1(ERR_FAILED): A general error occurs (no specified reason). - * - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + * - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. + * - -5 (ERR_REFUSED): The request is rejected. In multichannel scenarios, if you have set any of the following in + * one channel, the SDK returns this error code when the user switches the user role to host in another channel: + * - Call `joinChannel` with the `options` parameter and use the default settings `publishLocalAudio = true` or `publishLocalVideo = true`. + * - Call `setClientRole` to set the user role as host. + * - Call `muteLocalAudioStream(false)` or `muteLocalVideoStream(false)`. * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. */ virtual int setClientRole(CLIENT_ROLE_TYPE role, const ClientRoleOptions& options) = 0; @@ -973,7 +1062,7 @@ class IChannel { * - 0: Success. * - < 0: Failure. */ - virtual int setDefaultMuteAllRemoteAudioStreams(bool mute) = 0; + virtual int setDefaultMuteAllRemoteAudioStreams(bool mute) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Stops or resumes subscribing to the video streams of all remote users by default. * * @deprecated This method is deprecated from v3.3.0. @@ -994,16 +1083,76 @@ class IChannel { * - 0: Success. * - < 0: Failure. */ - virtual int setDefaultMuteAllRemoteVideoStreams(bool mute) = 0; + virtual int setDefaultMuteAllRemoteVideoStreams(bool mute) AGORA_DEPRECATED_ATTRIBUTE = 0; + /** + * Stops or resumes publishing the local audio stream. + * + * @since v3.4.5 + * + * This method only sets the publishing state of the audio stream in the channel of IChannel. + * + * A successful method call triggers the + * \ref IChannelEventHandler::onRemoteAudioStateChanged "onRemoteAudioStateChanged" + * callback on the remote client. + * + * You can only publish the local stream in one channel at a time. If you create multiple channels, ensure that + * you only call \ref IChannel::muteLocalAudioStream "muteLocalAudioStream" (false) in one channel; + * otherwise, the method call fails, and the SDK returns `-5 (ERR_REFUSED)`. + * + * @note + * - This method does not change the usage state of the audio-capturing device. + * - Whether this method call takes effect is affected by the \ref IChannel::joinChannel "joinChannel" + * and \ref IChannel::setClientRole "setClientRole" methods. For details, see *Set the Publishing State*. + * + * @param mute Sets whether to stop publishing the local audio stream. + * - true: Stop publishing the local audio stream. + * - false: Resume publishing the local audio stream. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `-5 (ERR_REFUSED)`: The request is rejected. + */ + virtual int muteLocalAudioStream(bool mute) = 0; + /** Stops or resumes publishing the local video stream. + * + * @since v3.4.5 + * + * This method only sets the publishing state of the video stream in the channel of IChannel. + * + * A successful method call triggers the \ref IChannelEventHandler::onRemoteVideoStateChanged "onRemoteVideoStateChanged" + * callback on the remote client. + * + * You can only publish the local stream in one channel at a time. If you create multiple channels, + * ensure that you only call \ref IChannel::muteLocalVideoStream "muteLocalVideoStream" (false) in one channel; + * otherwise, the method call fails, and the SDK returns `-5 (ERR_REFUSED)`. + * + * @note + * - This method does not change the usage state of the video-capturing device. + * - Whether this method call takes effect is affected by the \ref IChannel::joinChannel "joinChannel" + * and \ref IChannel::setClientRole "setClientRole" methods. For details, see *Set the Publishing State*. + * + * @param mute Sets whether to stop publishing the local video stream. + * - true: Stop publishing the local video stream. + * - false: Resume publishing the local video stream. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `-5 (ERR_REFUSED)`: The request is rejected. + */ + virtual int muteLocalVideoStream(bool mute) = 0; /** * Stops or resumes subscribing to the audio streams of all remote users. * - * As of v3.3.0, after successfully calling this method, the local user stops or resumes + * 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*. + * - As of v3.3.0, this method contains the function of \ref IChannel::setDefaultMuteAllRemoteAudioStreams "setDefaultMuteAllRemoteAudioStreams". + * Agora recommends not calling `muteAllRemoteAudioStreams` and `setDefaultMuteAllRemoteAudioStreams` + * together; otherwise, the settings may not take effect. See *Set the Subscribing State*. * * @param mute Sets whether to stop subscribing to the audio streams of all remote users. * - true: Stop subscribing to the audio streams of all remote users. @@ -1015,24 +1164,26 @@ class IChannel { */ virtual int muteAllRemoteAudioStreams(bool mute) = 0; /** Adjust the playback signal volume of the specified remote user. - - After joining a channel, call \ref agora::rtc::IRtcEngine::adjustPlaybackSignalVolume "adjustPlaybackSignalVolume" to adjust the playback volume of different remote users, - or adjust multiple times for one remote user. - - @note - - Call this method after joining a channel. - - This method adjusts the playback volume, which is the mixed volume for the specified remote user. - - This method can only adjust the playback volume of one specified remote user at a time. If you want to adjust the playback volume of several remote users, - call the method multiple times, once for each remote user. - - @param userId The user ID, which should be the same as the `uid` of \ref agora::rtc::IChannel::joinChannel "joinChannel" - @param volume The playback volume of the voice. The value ranges from 0 to 100: - - 0: Mute. - - 100: Original volume. - - @return - - 0: Success. - - < 0: Failure. + * + * After joining a channel, call \ref agora::rtc::IRtcEngine::adjustPlaybackSignalVolume "adjustPlaybackSignalVolume" to adjust the playback volume of different remote users, + * or adjust multiple times for one remote user. + * + * @note + * - Call this method after joining a channel. + * - This method adjusts the playback volume, which is the mixed volume for the specified remote user. + * - This method can only adjust the playback volume of one specified remote user at a time. If you want to adjust the playback volume of several remote users, + * call the method multiple times, once for each remote user. + * + * @param userId The user ID, which should be the same as the `uid` of \ref agora::rtc::IChannel::joinChannel "joinChannel" + * @param volume The playback volume of the voice. The value + * ranges between 0 and 400, including the following: + * - 0: Mute. + * - 100: (Default) Original volume. + * - 400: Four times the original volume with signal-clipping protection. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int adjustUserPlaybackSignalVolume(uid_t userId, int volume) = 0; /** @@ -1055,7 +1206,7 @@ class IChannel { /** * Stops or resumes subscribing to the video streams of all remote users. * - * As of v3.3.0, after successfully calling this method, the local user stops or resumes + * 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 @@ -1116,6 +1267,21 @@ class IChannel { - < 0: Failure. */ virtual int setRemoteVideoStreamType(uid_t userId, REMOTE_VIDEO_STREAM_TYPE streamType) = 0; + /** Turn WIFI acceleration on or off. + + @note + - This method is called before and after joining a channel. + - Users check the WIFI router app for information about acceleration. Therefore, if this interface is invoked, the caller accepts that the caller's name will be displayed to the user in the WIFI router application on behalf of the caller. + + @param enabled + - true：Turn WIFI acceleration on. + - false：Turn WIFI acceleration off. + + @return + - 0: Success. + - < 0: Failure. + */ + virtual int enableWirelessAccelerate(bool enabled) = 0; /** Sets the default stream type of remote videos. Under limited network conditions, if the publisher has not disabled the dual-stream mode using @@ -1145,7 +1311,7 @@ class IChannel { virtual int setRemoteDefaultVideoStreamType(REMOTE_VIDEO_STREAM_TYPE streamType) = 0; /** Creates a data stream. - @deprecated This method is deprecated from v3.3.0. Use the \ref IChannel::createDataStream(int* streamId, DataStreamConfig& config) "createDataStream" [2/2] method instead. + @deprecated This method is deprecated from v3.3.0. Use the \ref IChannel::createDataStream(int* streamId, DataStreamConfig& config) "createDataStream" [2/2] method instead. Each user can create up to five data streams during the lifecycle of the IChannel. @@ -1167,7 +1333,7 @@ class IChannel { - Returns 0: Success. - < 0: Failure. */ - virtual int createDataStream(int* streamId, bool reliable, bool ordered) = 0; + virtual int createDataStream(int* streamId, bool reliable, bool ordered) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Creates a data stream. * * @since v3.3.0 @@ -1213,6 +1379,8 @@ class IChannel { virtual int sendStreamMessage(int streamId, const char* data, size_t length) = 0; /** Publishes the local stream to a specified CDN streaming URL. (CDN live only.) + @deprecated This method is deprecated as of v3.6.0. See [Release Notes](https://docs.agora.io/en/Interactive%20Broadcast/release_windows_video?platform=Windows) for an alternative solution. + The SDK returns the result of this method call in the \ref IRtcEngineEventHandler::onStreamPublished "onStreamPublished" callback. After calling this method, you can push media streams in RTMP or RTMPS protocol to the CDN. The SDK triggers @@ -1236,9 +1404,11 @@ class IChannel { - #ERR_INVALID_ARGUMENT (-2): The CDN streaming URL is NULL or has a string length of 0. - #ERR_NOT_INITIALIZED (-7): You have not initialized `IChannel` when publishing the stream. */ - virtual int addPublishStreamUrl(const char* url, bool transcodingEnabled) = 0; + virtual int addPublishStreamUrl(const char* url, bool transcodingEnabled) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Removes an RTMP or RTMPS stream from the CDN. + @deprecated This method is deprecated as of v3.6.0. See [Release Notes](https://docs.agora.io/en/Interactive%20Broadcast/release_windows_video?platform=Windows) for an alternative solution. + This method removes the CDN streaming URL (added by the \ref IChannel::addPublishStreamUrl "addPublishStreamUrl" method) from a CDN live stream. The SDK returns the result of this method call in the \ref IRtcEngineEventHandler::onStreamUnpublished "onStreamUnpublished" callback. @@ -1255,9 +1425,11 @@ class IChannel { - 0: Success. - < 0: Failure. */ - virtual int removePublishStreamUrl(const char* url) = 0; + virtual int removePublishStreamUrl(const char* url) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Sets the video layout and audio settings for CDN live. (CDN live only.) + @deprecated This method is deprecated as of v3.6.0. See [Release Notes](https://docs.agora.io/en/Interactive%20Broadcast/release_windows_video?platform=Windows) for an alternative solution. + The SDK triggers the \ref agora::rtc::IChannelEventHandler::onTranscodingUpdated "onTranscodingUpdated" callback when you call the `setLiveTranscoding` method to update the transcoding setting. @@ -1273,7 +1445,105 @@ class IChannel { - 0: Success. - < 0: Failure. */ - virtual int setLiveTranscoding(const LiveTranscoding& transcoding) = 0; + virtual int setLiveTranscoding(const LiveTranscoding& transcoding) AGORA_DEPRECATED_ATTRIBUTE = 0; + /** + * Starts pushing media streams to a CDN without transcoding. + * + * @since v3.6.0 + * + * You can call this method to push a live audio-and-video stream to the specified CDN address. This method can push + * media streams to only one CDN address at a time, so if you need to push streams to multiple addresses, call this + * method multiple times. + * + * After you call this method, the SDK triggers the \ref IChannelEventHandler::onRtmpStreamingStateChanged "onRtmpStreamingStateChanged" + * callback on the local client to report the state of the streaming. + * + * @note + * - Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in *Push Streams to CDN*. + * - Call this method after joining a channel. + * - Only hosts in the `LIVE_BROADCASTING` profile can call this method. + * - If you want to retry pushing streams after a failed push, make sure to call \ref IChannel::stopRtmpStream "stopRtmpStream" first, + * then call this method to retry pushing streams; otherwise, the SDK returns the same error code as the last failed push. + * - If you want to push media streams in the RTMPS protocol to CDN, call \ref IChannel::startRtmpStreamWithTranscoding "startRtmpStreamWithTranscoding" + * instead of \ref IChannel::startRtmpStreamWithoutTranscoding "startRtmpStreamWithoutTranscoding". + * + * @param url The address of the CDN live streaming. The format is RTMP. The character length cannot exceed 1024 bytes. + * Special characters such as Chinese characters are not supported. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `ERR_INVALID_ARGUMENT(-2)`: url is null or the string length is 0. + * - `ERR_NOT_INITIALIZED(-7)`: The SDK is not initialized before calling this method. + */ + virtual int startRtmpStreamWithoutTranscoding(const char* url) = 0; + /** + * Starts pushing media streams to a CDN and sets the transcoding configuration. + * + * @since v3.6.0 + * + * You can call this method to push a live audio-and-video stream to the specified CDN address and set the transcoding + * configuration. This method can push media streams to only one CDN address at a time, so if you need to push streams to + * multiple addresses, call this method multiple times. + * + * After you call this method, the SDK triggers the \ref IChannelEventHandler::onRtmpStreamingStateChanged "onRtmpStreamingStateChanged" + * callback on the local client to report the state of the streaming. + * + * @note + * - Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in *Push Streams to CDN*. + * - Call this method after joining a channel. + * - Only hosts in the `LIVE_BROADCASTING` profile can call this method. + * - If you want to retry pushing streams after a failed push, make sure to call \ref IChannel::stopRtmpStream "stopRtmpStream" first, + * then call this method to retry pushing streams; otherwise, the SDK returns the same error code as the last failed push. + * - If you want to push media streams in the RTMPS protocol to CDN, call \ref IChannel::startRtmpStreamWithTranscoding "startRtmpStreamWithTranscoding" + * instead of \ref IChannel::startRtmpStreamWithoutTranscoding "startRtmpStreamWithoutTranscoding". + * + * @param url The address of the CDN live streaming. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. + * Special characters such as Chinese characters are not supported. + * @param transcoding The transcoding configuration for CDN live streaming. See LiveTranscoding. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `ERR_INVALID_ARGUMENT(-2)`: url is null or the string length is 0. + * - `ERR_NOT_INITIALIZED(-7)`: The SDK is not initialized before calling this method. + */ + virtual int startRtmpStreamWithTranscoding(const char* url, const LiveTranscoding& transcoding) = 0; + /** + * Updates the transcoding configuration. + * + * @since v3.6.0 + * + * After you start pushing media streams to CDN with transcoding, you can dynamically update the transcoding configuration according to the scenario. + * The SDK triggers the \ref IChannelEventHandler::onTranscodingUpdated "onTranscodingUpdated" callback after the + * transcoding configuration is updated. + * + * @param transcoding The transcoding configuration for CDN live streaming. See LiveTranscoding. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int updateRtmpTranscoding(const LiveTranscoding& transcoding) = 0; + /** + * Stops pushing media streams to a CDN. + * + * @since v3.6.0 + * + * You can call this method to stop the live stream on the specified CDN address. + * This method can stop pushing media streams to only one CDN address at a time, so if you need to stop pushing streams to multiple addresses, call this method multiple times. + * + * After you call this method, the SDK triggers the \ref IChannelEventHandler::onRtmpStreamingStateChanged "onRtmpStreamingStateChanged" callback on the local client to report the state of the streaming. + * + * @param url The address of the CDN live streaming. The format is RTMP or RTMPS. + * The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int stopRtmpStream(const char* url) = 0; + /** Adds a voice or video stream URL address to the interactive live streaming. The \ref IRtcEngineEventHandler::onStreamPublished "onStreamPublished" callback returns the inject status. @@ -1379,10 +1649,9 @@ class IChannel { * "onChannelMediaRelayEvent" callback with the * #RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL (7) state code. * - * @note - * Call this method after the - * \ref startChannelMediaRelay() "startChannelMediaRelay" method to update - * the destination channel. + * @note Call this method after successfully calling the \ref startChannelMediaRelay() "startChannelMediaRelay" method + * and receiving the \ref IChannelEventHandler::onChannelMediaRelayStateChanged "onChannelMediaRelayStateChanged" (RELAY_STATE_RUNNING, RELAY_OK) callback; + * otherwise, this method call fails. * * @param configuration The media stream relay configuration: * ChannelMediaRelayConfiguration. @@ -1392,6 +1661,47 @@ class IChannel { * - < 0: Failure. */ virtual int updateChannelMediaRelay(const ChannelMediaRelayConfiguration& configuration) = 0; + + /** + * Pauses the media stream relay to all destination channels. + * + * @since v3.5.1 + * + * After the cross-channel media stream relay starts, you can call this method + * to pause relaying media streams to all destination channels; after the pause, + * if you want to resume the relay, call \ref IChannel::resumeAllChannelMediaRelay "resumeAllChannelMediaRelay". + * + * After a successful method call, the SDK triggers the + * \ref IChannelEventHandler::onChannelMediaRelayEvent "onChannelMediaRelayEvent" + * callback to report whether the media stream relay is successfully paused. + * + * @note Call this method after the \ref IChannel::startChannelMediaRelay "startChannelMediaRelay" method. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int pauseAllChannelMediaRelay() = 0; + + /** Resumes the media stream relay to all destination channels. + * + * @since v3.5.1 + * + * After calling the \ref IChannel::pauseAllChannelMediaRelay "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 + * \ref IChannelEventHandler::onChannelMediaRelayEvent "onChannelMediaRelayEvent" + * callback to report whether the media stream relay is successfully resumed. + * + * @note Call this method after the \ref IChannel::pauseAllChannelMediaRelay "pauseAllChannelMediaRelay" method. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int resumeAllChannelMediaRelay() = 0; + /** Stops the media stream relay. * * Once the relay stops, the host quits all the destination @@ -1424,64 +1734,76 @@ class IChannel { @return #CONNECTION_STATE_TYPE. */ virtual CONNECTION_STATE_TYPE getConnectionState() = 0; - /// @cond - /** Enables/Disables the super-resolution algorithm for a remote user's video stream. + + /** Enables/Disables the super resolution feature for a remote user's video. (beta feature) * - * @since v3.2.0 + * @since v3.5.1 * - * The algorithm effectively improves the resolution of the specified remote user's video stream. When the original - * resolution of the remote video stream is a × b pixels, you can receive and render the stream at a higher - * resolution (2a × 2b pixels) by enabling the algorithm. + * This feature effectively boosts the resolution of a remote user's video seen by the local + * user. If the original resolution of a remote user's video is a × b, the local user's device + * can render the remote video at a resolution of 2a × 2b after you enable this feature. * * After calling this method, the SDK triggers the - * \ref IRtcChannelEventHandler::onUserSuperResolutionEnabled "onUserSuperResolutionEnabled" callback to report - * whether you have successfully enabled the super-resolution algorithm. - * - * @warning The super-resolution algorithm requires extra system resources. - * To balance the visual experience and system usage, the SDK poses the following restrictions: - * - The algorithm can only be used for a single user at a time. - * - On the Android platform, the original resolution of the remote video must not exceed 640 × 360 pixels. - * - On the iOS platform, the original resolution of the remote video must not exceed 640 × 480 pixels. - * If you exceed these limitations, the SDK triggers the \ref IRtcChannelEventHandler::onWarning "onWarning" - * callback with the corresponding warning codes: - * - #WARN_SUPER_RESOLUTION_STREAM_OVER_LIMITATION (1610): The origin resolution of the remote video is beyond the range where the super-resolution algorithm can be applied. - * - #WARN_SUPER_RESOLUTION_USER_COUNT_OVER_LIMITATION (1611): Another user is already using the super-resolution algorithm. - * - #WARN_SUPER_RESOLUTION_DEVICE_NOT_SUPPORTED (1612): The device does not support the super-resolution algorithm. + * \ref IChannelEventHandler::onUserSuperResolutionEnabled "onUserSuperResolutionEnabled" + * callback to report whether you have successfully enabled super resolution. + * + * @warning The super resolution feature requires extra system resources. To balance the visual experience and system consumption, the SDK poses the following restrictions: + * - This feature can only be enabled for a single remote user. + * - The original resolution of the remote user's video cannot exceed a certain range. If the local user use super resolution on Android, + * the original resolution of the remote user's video cannot exceed 640 × 360 pixels; if the local user use super resolution on iOS, + * the original resolution of the remote user's video cannot exceed 640 × 480 pixels. + * + * @warning If you exceed these limitations, the SDK triggers the + * \ref IRtcEngineEventHandler::onWarning "onWarning" callback and returns the corresponding warning codes: + * + * - #WARN_SUPER_RESOLUTION_STREAM_OVER_LIMITATION (1610): The original resolution of the remote user's video is beyond + * the range where super resolution can be applied. + * - #WARN_SUPER_RESOLUTION_USER_COUNT_OVER_LIMITATION (1611): Super resolution is already being used to boost another + * remote user's video. + * - #WARN_SUPER_RESOLUTION_DEVICE_NOT_SUPPORTED (1612): The device does not support using super resolution. * * @note - * - This method applies to Android and iOS only. - * - Requirements for the user's device: - * - Android: The following devices are known to support the method: - * - VIVO: V1821A, NEX S, 1914A, 1916A, and 1824BA - * - OPPO: PCCM00 + * - This method is for Android and iOS only. + * - Before calling this method, ensure that you have integrated the following dynamic library into your project: + * - Android: `libagora_super_resolution_extension.so` + * - iOS: `AgoraSuperResolutionExtension.xcframework` + * - Because this method has certain system performance requirements, Agora recommends that you use the following devices or better: + * - Android: + * - VIVO: V1821A, NEX S, 1914A, 1916A, 1962A, 1824BA, X60, X60 Pro + * - OPPO: PCCM00, Find X3 * - OnePlus: A6000 - * - Xiaomi: Mi 8, Mi 9, MIX3, and Redmi K20 Pro - * - SAMSUNG: SM-G9600, SM-G9650, SM-N9600, SM-G9708, SM-G960U, and SM-G9750 - * - HUAWEI: SEA-AL00, ELE-AL00, VOG-AL00, YAL-AL10, HMA-AL00, and EVR-AN00 - * - iOS: This method is supported on devices running iOS 12.0 or later. The following - * device models are known to support the method: + * - Xiaomi: Mi 8, Mi 9, Mi 10, Mi 11, MIX3, Redmi K20 Pro + * - SAMSUNG: SM-G9600, SM-G9650, SM-N9600, SM-G9708, SM-G960U, SM-G9750, S20, S21 + * - HUAWEI: SEA-AL00, ELE-AL00, VOG-AL00, YAL-AL10, HMA-AL00, EVR-AN00, nova 4, nova 5 Pro, + * nova 6 5G, nova 7 5G, Mate 30, Mate 30 Pro, Mate 40, Mate 40 Pro, P40 P40 Pro, HUAWEI MediaPad M6, MatePad 10.8 + * - iOS (iOS 12.0 or later): * - iPhone XR * - iPhone XS * - iPhone XS Max * - iPhone 11 * - iPhone 11 Pro * - iPhone 11 Pro Max - * - iPad Pro 11-inch (3rd Generation) - * - iPad Pro 12.9-inch (3rd Generation) - * - iPad Air 3 (3rd Generation) - * - * @param userId The ID of the remote user. - * @param enable Whether to enable the super-resolution algorithm: - * - true: Enable the super-resolution algorithm. - * - false: Disable the super-resolution algorithm. + * - iPhone 12 + * - iPhone 12 mini + * - iPhone 12 Pro + * - iPhone 12 Pro Max + * - iPhone 12 SE (2nd generation) + * - iPad Pro 11-inch (3rd generation) + * - iPad Pro 12.9-inch (3rd generation) + * - iPad Air (3rd generation) + * - iPad Air (4th generation) + * + * @param userId The user ID of the remote user. + * @param enable Determines whether to enable super resolution for the remote user's video: + * - true: Enable super resolution. + * - false: Disable super resolution. * * @return * - 0: Success. * - < 0: Failure. - * - -158 (ERR_MODULE_SUPER_RESOLUTION_NOT_FOUND): You have not integrated the dynamic library for the super-resolution algorithm. + * - `-157 (ERR_MODULE_NOT_FOUND)`: The dynamic library for super resolution is not integrated. */ virtual int enableRemoteSuperResolution(uid_t userId, bool enable) = 0; - /// @endcond }; /** @since v3.0.0 diff --git a/Android/APIExample/lib-raw-data/src/main/cpp/include/IAgoraRtcEngine.h b/Android/APIExample/lib-raw-data/src/main/cpp/include/IAgoraRtcEngine.h index 8fc262d28..b050af84a 100644 --- a/Android/APIExample/lib-raw-data/src/main/cpp/include/IAgoraRtcEngine.h +++ b/Android/APIExample/lib-raw-data/src/main/cpp/include/IAgoraRtcEngine.h @@ -14,12 +14,24 @@ #include "IAgoraService.h" #include "IAgoraLog.h" -#if defined(_WIN32) #include "IAgoraMediaEngine.h" +#if defined(TARGET_OS_IPHONE) && TARGET_OS_IPHONE /* Warning fixing. Lionfore Oct 12th, 2019 */ +#include #endif namespace agora { namespace rtc { +/** The IMediaRecorderObserver class. + * + * @since v3.5.2 + */ +class IMediaRecorderObserver; +/** + * The MediaRecorderConfiguration struct. + * + * @since v3.5.2 + */ +struct MediaRecorderConfiguration; typedef unsigned int uid_t; typedef void* view_t; /** Maximum length of the device ID. @@ -53,7 +65,7 @@ enum QUALITY_REPORT_FORMAT_TYPE { */ QUALITY_REPORT_HTML = 1, }; - +/// @cond enum MEDIA_ENGINE_EVENT_CODE_TYPE { /** 0: For internal use only. */ @@ -115,6 +127,9 @@ enum MEDIA_ENGINE_EVENT_CODE_TYPE { /** 113: For internal use only. */ MEDIA_ENGINE_AUDIO_ADM_USING_NORM_PARAMS = 113, + /** 114: For internal use only. + */ + MEDIA_ENGINE_AUDIO_ADM_ROUTING_UPDATE = 114, // audio mix event /** 720: For internal use only. */ @@ -151,31 +166,50 @@ enum MEDIA_ENGINE_EVENT_CODE_TYPE { */ MEDIA_ENGINE_AUDIO_ERROR_MIXING_NO_ERROR = 0, }; +/// @endcond -/** The states of the local user's audio mixing file. +/** The current music file playback state. + * + * Reports in the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" callback. */ enum AUDIO_MIXING_STATE_TYPE { - /** 710: The audio mixing file is playing after the method call of - * \ref IRtcEngine::startAudioMixing "startAudioMixing" or \ref IRtcEngine::resumeAudioMixing "resumeAudioMixing" succeeds. + /** 710: The music file is playing. + * + * This state comes with one of the following associated reasons: + * - #AUDIO_MIXING_REASON_STARTED_BY_USER (720) + * - #AUDIO_MIXING_REASON_ONE_LOOP_COMPLETED (721) + * - #AUDIO_MIXING_REASON_START_NEW_LOOP (722) + * - #AUDIO_MIXING_REASON_RESUMED_BY_USER (726) */ AUDIO_MIXING_STATE_PLAYING = 710, - /** 711: The audio mixing file pauses playing after the method call of \ref IRtcEngine::pauseAudioMixing "pauseAudioMixing" succeeds. + /** 711: The music file pauses playing. + * + * This state comes with #AUDIO_MIXING_REASON_PAUSED_BY_USER (725). */ AUDIO_MIXING_STATE_PAUSED = 711, - /** 713: The audio mixing file stops playing after the method call of \ref IRtcEngine::stopAudioMixing "stopAudioMixing" succeeds. + /** 713: The music file stops playing. + * + * This state comes with one of the following associated reasons: + * - #AUDIO_MIXING_REASON_ALL_LOOPS_COMPLETED (723) + * - #AUDIO_MIXING_REASON_STOPPED_BY_USER (724) */ AUDIO_MIXING_STATE_STOPPED = 713, - /** 714: An exception occurs during the playback of the audio mixing file. See the `errorCode` for details. + /** 714: An exception occurs during the playback of the music file. + * + * This state comes with one of the following associated reasons: + * - #AUDIO_MIXING_REASON_CAN_NOT_OPEN (701) + * - #AUDIO_MIXING_REASON_TOO_FREQUENT_CALL (702) + * - #AUDIO_MIXING_REASON_INTERRUPTED_EOF (703) */ AUDIO_MIXING_STATE_FAILED = 714, }; /** - * @deprecated Deprecated from v3.4.0, use AUDIO_MIXING_REASON_TYPE instead. + * @deprecated Deprecated from v3.4.0. Use #AUDIO_MIXING_REASON_TYPE instead. * * The error codes of the local user's audio mixing file. */ -enum AUDIO_MIXING_ERROR_TYPE { +enum AGORA_DEPRECATED_ATTRIBUTE AUDIO_MIXING_ERROR_TYPE { /** 701: The SDK cannot open the audio mixing file. */ AUDIO_MIXING_ERROR_CAN_NOT_OPEN = 701, @@ -190,37 +224,49 @@ enum AUDIO_MIXING_ERROR_TYPE { AUDIO_MIXING_ERROR_OK = 0, }; -/** The reason of audio mixing state change. +/** The reason for the change of the music file playback state. + * + * @since v3.4.0 + * + * Reports in the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" callback. */ enum AUDIO_MIXING_REASON_TYPE { - /** 701: The SDK cannot open the audio mixing file. + /** 701: The SDK cannot open the music file. Possible causes include 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_CAN_NOT_OPEN = 701, - /** 702: The SDK opens the audio mixing file too frequently. + /** 702: The SDK opens the music file too frequently. If you need to call + * \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" multiple times, ensure + * that the call interval is longer than 500 ms. */ AUDIO_MIXING_REASON_TOO_FREQUENT_CALL = 702, - /** 703: The audio mixing file playback is interrupted. + /** 703: The music file playback is interrupted. */ AUDIO_MIXING_REASON_INTERRUPTED_EOF = 703, - /** 720: The audio mixing is started by user. + /** 720: Successfully calls \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" + * to play a music file. */ AUDIO_MIXING_REASON_STARTED_BY_USER = 720, - /** 721: The audio mixing file is played once. + /** 721: The music file completes a loop playback. */ AUDIO_MIXING_REASON_ONE_LOOP_COMPLETED = 721, - /** 722: The audio mixing file is playing in a new loop. + /** 722: The music file starts a new loop playback. */ AUDIO_MIXING_REASON_START_NEW_LOOP = 722, - /** 723: The audio mixing file is all played out. + /** 723: The music file completes all loop playback. */ AUDIO_MIXING_REASON_ALL_LOOPS_COMPLETED = 723, - /** 724: Playing of audio file is stopped by user. + /** 724: Successfully calls \ref IRtcEngine::stopAudioMixing "stopAudioMixing" + * to stop playing the music file. */ AUDIO_MIXING_REASON_STOPPED_BY_USER = 724, - /** 725: Playing of audio file is paused by user. + /** 725: Successfully calls \ref IRtcEngine::pauseAudioMixing "pauseAudioMixing" + * to pause playing the music file. */ AUDIO_MIXING_REASON_PAUSED_BY_USER = 725, - /** 726: Playing of audio file is resumed by user. + /** 726: Successfully calls \ref IRtcEngine::resumeAudioMixing "resumeAudioMixing" + * to resume playing the music file. */ AUDIO_MIXING_REASON_RESUMED_BY_USER = 726, }; @@ -228,7 +274,14 @@ enum AUDIO_MIXING_REASON_TYPE { /** Media device states. */ enum MEDIA_DEVICE_STATE_TYPE { - /** 1: The device is active. + /** 0: The device is ready for use. + * + * @since v3.4.5 + */ + MEDIA_DEVICE_STATE_IDLE = 0, + /** 1: The device is in use. + * + * @since v3.4.5 */ MEDIA_DEVICE_STATE_ACTIVE = 1, /** 2: The device is disabled. @@ -242,7 +295,7 @@ enum MEDIA_DEVICE_STATE_TYPE { MEDIA_DEVICE_STATE_UNPLUGGED = 8, /** 16: The device is not recommended. */ - MEDIA_DEVICE_STATE_UNRECOMMENDED = 16 + MEDIA_DEVICE_STATE_UNRECOMMENDED = 16, }; /** Media device types. @@ -268,10 +321,10 @@ enum MEDIA_DEVICE_TYPE { AUDIO_APPLICATION_PLAYOUT_DEVICE = 4, }; -/** Local video state types +/** Local video state types. */ enum LOCAL_VIDEO_STREAM_STATE { - /** 0: Initial state */ + /** 0: Initial state. */ LOCAL_VIDEO_STREAM_STATE_STOPPED = 0, /** 1: The local video capturing device starts successfully. * @@ -284,7 +337,7 @@ enum LOCAL_VIDEO_STREAM_STATE { LOCAL_VIDEO_STREAM_STATE_FAILED = 3 }; -/** Local video state error codes +/** Local video state error codes. */ enum LOCAL_VIDEO_STREAM_ERROR { /** 0: The local video is normal. */ @@ -309,9 +362,24 @@ enum LOCAL_VIDEO_STREAM_ERROR { * @since v3.3.0 */ LOCAL_VIDEO_STREAM_ERROR_CAPTURE_MULTIPLE_FOREGROUND_APPS = 7, - /** 8:capture not found*/ + /** + * 8: The SDK cannot find the local video capture device. + * + * @since v3.4.0 + */ LOCAL_VIDEO_STREAM_ERROR_DEVICE_NOT_FOUND = 8, - + /** + * 10: (macOS and Windows only) The SDK cannot find the video device in the video device list. Check whether the ID + * of the video device is valid. + * + * @since v3.5.2 + */ + LOCAL_VIDEO_STREAM_ERROR_DEVICE_INVALID_ID = 10, + /** + * 11: The shared window is minimized when you call + * \ref IRtcEngine::startScreenCaptureByWindowId "startScreenCaptureByWindowId" + * to share a window. + */ LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_MINIMIZED = 11, /** 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. @@ -326,8 +394,20 @@ enum LOCAL_VIDEO_STREAM_ERROR { * the web video or document. After the user exits full-screen mode, the SDK reports this error code. */ LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_CLOSED = 12, - + /** + * 13: (Windows only) The window being shared is overlapped by another window, so the overlapped area is blacked out by + * the SDK during window sharing. + * + * @since v3.5.2 + */ + LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_OCCLUDED = 13, + /** + * 20: (Windows only) The SDK does not support sharing this type of window. + * + * @since v3.5.2 + */ LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_NOT_SUPPORTED = 20, + }; /** Local audio state types. @@ -369,29 +449,53 @@ enum LOCAL_AUDIO_STREAM_ERROR { /** 5: The local audio encoding fails. */ LOCAL_AUDIO_STREAM_ERROR_ENCODE_FAILURE = 5, - /** 6: No recording audio device. + /** 6: The SDK cannot find the local audio recording device. + * + * @since v3.4.0 */ LOCAL_AUDIO_STREAM_ERROR_NO_RECORDING_DEVICE = 6, - /** 7: No playout audio device. + /** 7: The SDK cannot find the local audio playback device. + * + * @since v3.4.0 + */ + LOCAL_AUDIO_STREAM_ERROR_NO_PLAYOUT_DEVICE = 7, + /** + * 8: The local audio capturing is interrupted by the system call. + */ + LOCAL_AUDIO_STREAM_ERROR_INTERRUPTED = 8, + /** 9: An invalid audio capture device ID. + * + * @since v3.5.1 + */ + LOCAL_AUDIO_STREAM_ERROR_RECORD_INVALID_ID = 9, + /** 10: An invalid audio playback device ID. + * + * @since v3.5.1 */ - LOCAL_AUDIO_STREAM_ERROR_NO_PLAYOUT_DEVICE = 7 + LOCAL_AUDIO_STREAM_ERROR_PLAYOUT_INVALID_ID = 10, }; -/** Audio recording qualities. +/** Audio recording quality, which is set in + * \ref IRtcEngine::startAudioRecording(const AudioRecordingConfiguration&) "startAudioRecording". */ enum AUDIO_RECORDING_QUALITY_TYPE { - /** 0: Low quality. The sample rate is 32 kHz, and the file size is around - * 1.2 MB after 10 minutes of recording. + /** 0: Low quality. For example, the size of an AAC file with a sample rate + * of 32,000 Hz and a 10-minute recording is approximately 1.2 MB. */ AUDIO_RECORDING_QUALITY_LOW = 0, - /** 1: Medium quality. The sample rate is 32 kHz, and the file size is - * around 2 MB after 10 minutes of recording. + /** 1: (Default) Medium quality. For example, the size of an AAC file with + * a sample rate of 32,000 Hz and a 10-minute recording is approximately + * 2 MB. */ AUDIO_RECORDING_QUALITY_MEDIUM = 1, - /** 2: High quality. The sample rate is 32 kHz, and the file size is - * around 3.75 MB after 10 minutes of recording. + /** 2: High quality. For example, the size of an AAC file with a sample rate + * of 32,000 Hz and a 10-minute recording is approximately 3.75 MB. */ AUDIO_RECORDING_QUALITY_HIGH = 2, + /** 3: Ultra high quality. For example, the size of an AAC file with a sample rate + * of 32,000 Hz and a 10-minute recording is approximately 7.5 MB. + */ + AUDIO_RECORDING_QUALITY_ULTRA_HIGH = 3, }; /** Network quality types. */ @@ -446,8 +550,8 @@ enum VIDEO_MIRROR_MODE_TYPE { VIDEO_MIRROR_MODE_DISABLED = 2, // disable mirror }; -/** **DEPRECATED** Video profiles. */ -enum VIDEO_PROFILE_TYPE { +/** @deprecated Video profiles. */ +enum AGORA_DEPRECATED_ATTRIBUTE VIDEO_PROFILE_TYPE { /** 0: 160 * 120, frame rate 15 fps, bitrate 65 Kbps. */ VIDEO_PROFILE_LANDSCAPE_120P = 0, /** 2: 120 * 120, frame rate 15 fps, bitrate 50 Kbps. */ @@ -610,12 +714,12 @@ Sets the sample rate, bitrate, encoding mode, and the number of channels:*/ enum AUDIO_PROFILE_TYPE // sample rate, bit rate, mono/stereo, speech/music codec { /** - 0: 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, music encoding, mono, and a bitrate of up to 16 Kbps. - - Android/macOS/iOS: A sample rate of 32 KHz, music encoding, mono, and a bitrate of up to 18 Kbps. - */ + * 0: Default audio profile: + * - For the `LIVE_BROADCASTING` 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_DEFAULT = 0, // use default settings /** 1: A sample rate of 32 KHz, audio encoding, mono, and a bitrate of up to 18 Kbps. @@ -650,7 +754,12 @@ enum AUDIO_PROFILE_TYPE // sample rate, bit rate, mono/stereo, speech/music cod */ enum AUDIO_SCENARIO_TYPE // set a suitable scenario for your app type { - /** 0: Default audio scenario. */ + /** 0: Default audio scenario. + * + * @note If you run the iOS app on an M1 Mac, due to the hardware differences + * between M1 Macs, iPhones, and iPads, the default audio scenario of the Agora + * iOS SDK is the same as that of the Agora macOS SDK. + */ AUDIO_SCENARIO_DEFAULT = 0, /** 1: Entertainment scenario where users need to frequently switch the user role. */ AUDIO_SCENARIO_CHATROOM_ENTERTAINMENT = 1, @@ -677,7 +786,7 @@ enum AUDIO_SCENARIO_TYPE // set a suitable scenario for your app type /** The channel profile. */ enum CHANNEL_PROFILE_TYPE { - /** (Default) Communication. This profile applies to scenarios such as an audio call or video call, + /** Communication. This profile applies to scenarios such as an audio call or video call, * where all users can publish and subscribe to streams. */ CHANNEL_PROFILE_COMMUNICATION = 0, @@ -703,7 +812,7 @@ enum CLIENT_ROLE_TYPE { /** The latency level of an audience member in interactive live streaming. * - * @note Takes effect only when the user role is `CLIENT_ROLE_BROADCASTER`. + * @note Takes effect only when the user role is `CLIENT_ROLE_AUDIENCE`. */ enum AUDIENCE_LATENCY_LEVEL_TYPE { /** 1: Low latency. */ @@ -711,24 +820,58 @@ enum AUDIENCE_LATENCY_LEVEL_TYPE { /** 2: (Default) Ultra low latency. */ AUDIENCE_LATENCY_LEVEL_ULTRA_LOW_LATENCY = 2, }; -/// @cond -/** The reason why the super-resolution algorithm is not successfully enabled. + +/** + * The reason why super resolution is not successfully enabled or the message + * that confirms success. + * + * @since v3.5.1 */ enum SUPER_RESOLUTION_STATE_REASON { - /** 0: The super-resolution algorithm is successfully enabled. + /** 0: Super resolution is successfully enabled. */ SR_STATE_REASON_SUCCESS = 0, - /** 1: The origin resolution of the remote video is beyond the range where - * the super-resolution algorithm can be applied. + /** 1: The original resolution of the remote video is beyond the range where + * super resolution can be applied. */ SR_STATE_REASON_STREAM_OVER_LIMITATION = 1, - /** 2: Another user is already using the super-resolution algorithm. + /** 2: Super resolution is already being used to boost another remote user's video. */ SR_STATE_REASON_USER_COUNT_OVER_LIMITATION = 2, - /** 3: The device does not support the super-resolution algorithm. + /** 3: The device does not support using super resolution. */ SR_STATE_REASON_DEVICE_NOT_SUPPORTED = 3, }; + +/** + * The reason why the virtual background is not successfully enabled or the message that confirms success. + * + * @since v3.4.5 + */ +enum VIRTUAL_BACKGROUND_SOURCE_STATE_REASON { + /** + * 0: The virtual background is successfully enabled. + */ + VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_SUCCESS = 0, + /** + * 1: The custom background image does not exist. Please check the value of `source` in VirtualBackgroundSource. + */ + VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_IMAGE_NOT_EXIST = 1, + /** + * 2: The color format of the custom background image is invalid. Please check the value of `color` in VirtualBackgroundSource. + */ + VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_COLOR_FORMAT_NOT_SUPPORTED = 2, + /** + * 3: The device does not support using the virtual background. + */ + VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_DEVICE_NOT_SUPPORTED = 3, +}; +/// @cond +enum CONTENT_INSPECT_RESULT { + CONTENT_INSPECT_NEUTRAL = 1, + CONTENT_INSPECT_SEXY = 2, + CONTENT_INSPECT_PORN = 3, +}; /// @endcond /** Reasons for a user being offline. */ @@ -762,41 +905,98 @@ enum RTMP_STREAM_PUBLISH_STATE { /** The RTMP or RTMPS streaming fails. See the errCode parameter for the detailed error information. You can also call the \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method to publish the RTMP or RTMPS streaming again. */ RTMP_STREAM_PUBLISH_STATE_FAILURE = 4, + /** The SDK is disconnecting from the Agora streaming server and CDN. + * When you call remove or stop to stop the streaming normally, the SDK reports the streaming state as `DISCONNECTING`, `IDLE` in sequence. + * + * @since v3.6.0 + */ + RTMP_STREAM_PUBLISH_STATE_DISCONNECTING = 5, }; /** Error codes of the RTMP or RTMPS streaming. */ -enum RTMP_STREAM_PUBLISH_ERROR { - /** The RTMP or RTMPS streaming publishes successfully. */ +enum RTMP_STREAM_PUBLISH_ERROR_TYPE { + /** 0: The RTMP or RTMPS streaming publishes successfully. */ RTMP_STREAM_PUBLISH_ERROR_OK = 0, - /** Invalid argument used. If, for example, you do not call the \ref IRtcEngine::setLiveTranscoding "setLiveTranscoding" method to configure the LiveTranscoding parameters before calling the addPublishStreamUrl method, the SDK returns this error. Check whether you set the parameters in the *setLiveTranscoding* method properly. */ + /** 1: Invalid argument used. If, for example, you do not call the \ref IRtcEngine::setLiveTranscoding "setLiveTranscoding" method to configure the LiveTranscoding parameters before calling the addPublishStreamUrl method, the SDK returns this error. Check whether you set the parameters in the *setLiveTranscoding* method properly. */ RTMP_STREAM_PUBLISH_ERROR_INVALID_ARGUMENT = 1, - /** The RTMP or RTMPS streaming is encrypted and cannot be published. */ + /** 2: The RTMP or RTMPS streaming is encrypted and cannot be published. */ RTMP_STREAM_PUBLISH_ERROR_ENCRYPTED_STREAM_NOT_ALLOWED = 2, - /** Timeout for the RTMP or RTMPS streaming. Call the \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method to publish the streaming again. */ + /** 3: Timeout for the RTMP or RTMPS streaming. Call the \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method to publish the streaming again. */ RTMP_STREAM_PUBLISH_ERROR_CONNECTION_TIMEOUT = 3, - /** An error occurs in Agora's streaming server. Call the `addPublishStreamUrl` method to publish the streaming again. */ + /** 4: An error occurs in Agora's streaming server. Call the `addPublishStreamUrl` method to publish the streaming again. */ RTMP_STREAM_PUBLISH_ERROR_INTERNAL_SERVER_ERROR = 4, - /** An error occurs in the CDN server. */ + /** 5: An error occurs in the CDN server. */ RTMP_STREAM_PUBLISH_ERROR_RTMP_SERVER_ERROR = 5, - /** The RTMP or RTMPS streaming publishes too frequently. */ + /** 6; The RTMP or RTMPS streaming publishes too frequently. */ RTMP_STREAM_PUBLISH_ERROR_TOO_OFTEN = 6, - /** The host publishes more than 10 URLs. Delete the unnecessary URLs before adding new ones. */ + /** 7: The host publishes more than 10 URLs. Delete the unnecessary URLs before adding new ones. */ RTMP_STREAM_PUBLISH_ERROR_REACH_LIMIT = 7, - /** The host manipulates other hosts' URLs. Check your app logic. */ + /** 8: The host manipulates other hosts' URLs. Check your app logic. */ RTMP_STREAM_PUBLISH_ERROR_NOT_AUTHORIZED = 8, - /** Agora's server fails to find the RTMP or RTMPS streaming. */ + /** 9: Agora's server fails to find the RTMP or RTMPS streaming. */ RTMP_STREAM_PUBLISH_ERROR_STREAM_NOT_FOUND = 9, - /** The format of the RTMP or RTMPS streaming URL is not supported. Check whether the URL format is correct. */ + /** 10: The format of the RTMP or RTMPS streaming URL is not supported. Check whether the URL format is correct. */ RTMP_STREAM_PUBLISH_ERROR_FORMAT_NOT_SUPPORTED = 10, + /** + * 11: The user role is not host, so the user cannot use the CDN live streaming function. + * Check your application code logic. + * + * @since v3.6.0 + */ + RTMP_STREAM_PUBLISH_ERROR_NOT_BROADCASTER = 11, // Note: match to ERR_PUBLISH_STREAM_NOT_BROADCASTER in AgoraBase.h + /** + * 13: The `updateRtmpTranscoding` or `setLiveTranscoding` method is called to update the transcoding configuration in a scenario where there is streaming without transcoding. + * Check your application code logic. + * + * @since v3.6.0 + */ + RTMP_STREAM_PUBLISH_ERROR_TRANSCODING_NO_MIX_STREAM = 13, // Note: match to ERR_PUBLISH_STREAM_TRANSCODING_NO_MIX_STREAM in AgoraBase.h + /** + * 14: Errors occurred in the host's network. + * + * @since v3.6.0 + */ + RTMP_STREAM_PUBLISH_ERROR_NET_DOWN = 14, // Note: match to ERR_NET_DOWN in AgoraBase.h + /** + * 15: Your App ID does not have permission to use the CDN live streaming function. + * Refer to [Prerequisites](https://docs.agora.io/en/Interactive%20Broadcast/cdn_streaming_windows?platform=Windows#prerequisites) to + * enable the CDN live streaming permission. + * + * @since v3.6.0 + */ + RTMP_STREAM_PUBLISH_ERROR_INVALID_APPID = 15, // Note: match to ERR_PUBLISH_STREAM_APPID_INVALID in AgoraBase.h + /** + * 100: The streaming has been stopped normally. After you call + * \ref IRtcEngine::removePublishStreamUrl "removePublishStreamUrl" + * to stop streaming, the SDK returns this value. + * + * @since v3.4.5 + */ + RTMP_STREAM_UNPUBLISH_ERROR_OK = 100, }; /** Events during the RTMP or RTMPS streaming. */ enum RTMP_STREAMING_EVENT { - /** An error occurs when you add a background image or a watermark image to the RTMP or RTMPS stream. + /** 1: An error occurs when you add a background image or a watermark image to the RTMP or RTMPS stream. */ RTMP_STREAMING_EVENT_FAILED_LOAD_IMAGE = 1, + /** 2: The streaming URL is already being used for CDN live streaming. If you want to start new streaming, use a new streaming URL. + * + * @since v3.4.5 + */ + RTMP_STREAMING_EVENT_URL_ALREADY_IN_USE = 2, + /** 3: The feature is not supported. + * + * @since v3.6.0 + */ + RTMP_STREAMING_EVENT_ADVANCED_FEATURE_NOT_SUPPORT = 3, + /** 4: Reserved. + * + * @since v3.6.0 + */ + RTMP_STREAMING_EVENT_REQUEST_TOO_OFTEN = 4, }; /** States of importing an external video stream in the interactive live streaming. */ @@ -883,19 +1083,29 @@ enum VIDEO_CODEC_PROFILE_TYPE { /** 66: Baseline video codec profile. Generally /** Video codec types */ enum VIDEO_CODEC_TYPE { - /** Standard VP8 */ + /** 1: Standard VP8 */ VIDEO_CODEC_VP8 = 1, - /** Standard H264 */ + /** 2: Standard H.264 */ VIDEO_CODEC_H264 = 2, - /** Enhanced VP8 */ + /** 3: Enhanced VP8 */ VIDEO_CODEC_EVP = 3, - /** Enhanced H264 */ + /** 4: Enhanced H.264 */ VIDEO_CODEC_E264 = 4, }; -/** Video Codec types for publishing streams. */ +/** + * The video codec type of the output video stream. + * + * @since v3.2.0 + */ enum VIDEO_CODEC_TYPE_FOR_STREAM { + /** + * 1: (Default) H.264 + */ VIDEO_CODEC_H264_FOR_STREAM = 1, + /** + * 2: H.265 + */ VIDEO_CODEC_H265_FOR_STREAM = 2, }; @@ -941,8 +1151,15 @@ enum AUDIO_REVERB_TYPE { * @deprecated Deprecated from v3.2.0. * * Local voice changer options. + * + * Gender-based beatification effect works best only when assigned a proper gender: + * + * - For male: #GENERAL_BEAUTY_VOICE_MALE_MAGNETIC + * - For female: #GENERAL_BEAUTY_VOICE_FEMALE_FRESH or #GENERAL_BEAUTY_VOICE_FEMALE_VITALITY + * + * Failure to do so can lead to voice distortion. */ -enum VOICE_CHANGER_PRESET { +enum AGORA_DEPRECATED_ATTRIBUTE VOICE_CHANGER_PRESET { /** * The original voice (no local voice change). */ @@ -1026,7 +1243,7 @@ enum VOICE_CHANGER_PRESET { * * Local voice reverberation presets. */ -enum AUDIO_REVERB_PRESET { +enum AGORA_DEPRECATED_ATTRIBUTE AUDIO_REVERB_PRESET { /** * Turn off local voice reverberation, that is, to use the original voice. */ @@ -1098,9 +1315,13 @@ enum AUDIO_REVERB_PRESET { * as `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)`. */ AUDIO_VIRTUAL_STEREO = 0x00200001, - /** 1: Electronic Voice.*/ + /** + * A pitch correction effect that corrects the user's pitch based on the pitch of the natural C major scale. + */ AUDIO_ELECTRONIC_VOICE = 0x00300001, - /** 1: 3D Voice.*/ + /** + * A 3D voice effect that makes the voice appear to be moving around the user. + */ AUDIO_THREEDIM_VOICE = 0x00400001 }; /** The options for SDK preset voice beautifier effects. @@ -1334,10 +1555,15 @@ enum VOICE_CONVERSION_PRESET { }; /** Audio codec profile types. The default value is LC_ACC. */ enum AUDIO_CODEC_PROFILE_TYPE { - /** 0: LC-AAC, which is the low-complexity audio codec type. */ + /** 0: (Default) LC-AAC */ AUDIO_CODEC_PROFILE_LC_AAC = 0, - /** 1: HE-AAC, which is the high-efficiency audio codec type. */ + /** 1: HE-AAC */ AUDIO_CODEC_PROFILE_HE_AAC = 1, + /** 2: HE-AAC v2 + * + * @since v3.6.0 + */ + AUDIO_CODEC_PROFILE_HE_AAC_V2 = 2, }; /** Remote audio states. @@ -1414,7 +1640,7 @@ enum REMOTE_AUDIO_STATE_REASON { /** The state of the remote video. */ enum REMOTE_VIDEO_STATE { - /** 0: The remote video is in the default state, probably due to #REMOTE_VIDEO_STATE_REASON_LOCAL_MUTED (3), #REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED (5), or #REMOTE_VIDEO_STATE_REASON_REMOTE_OFFLINE (7). + /** 0: The remote video is in the default state, probably due to #REMOTE_VIDEO_STATE_REASON_LOCAL_MUTED (3), #REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED (5), or #REMOTE_VIDEO_STATE_REASON_REMOTE_OFFLINE (7). */ REMOTE_VIDEO_STATE_STOPPED = 0, @@ -1593,13 +1819,34 @@ enum ORIENTATION_MODE { ORIENTATION_MODE_FIXED_PORTRAIT = 2, }; -/** Video degradation preferences when the bandwidth is a constraint. */ +/** Video degradation preferences under limited bandwidth. */ enum DEGRADATION_PREFERENCE { - /** 0: (Default) Degrade the frame rate in order to maintain the video 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 \ref IRtcEngineEventHandler::onVideoSizeChanged "onVideoSizeChanged". + */ MAINTAIN_QUALITY = 0, - /** 1: Degrade the video quality in order to maintain the frame rate. */ + /** 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_FRAMERATE = 1, - /** 2: (For future use) Maintain a balance between the frame rate and video quality. */ + /** 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 \ref IRtcEngineEventHandler::onVideoSizeChanged "onVideoSizeChanged". + */ MAINTAIN_BALANCED = 2, }; @@ -1696,7 +1943,9 @@ enum CONNECTION_CHANGED_REASON_TYPE { CONNECTION_CHANGED_JOIN_FAILED = 4, /** 5: The SDK has left the channel. */ CONNECTION_CHANGED_LEAVE_CHANNEL = 5, - /** 6: The connection failed since Appid is not valid. */ + /** + * 6: The specified App ID is invalid. Try to rejoin the channel with a valid App ID. + */ CONNECTION_CHANGED_INVALID_APP_ID = 6, /** 7: The connection failed since channel name is not valid. */ CONNECTION_CHANGED_INVALID_CHANNEL_NAME = 7, @@ -1724,8 +1973,10 @@ enum CONNECTION_CHANGED_REASON_TYPE { CONNECTION_CHANGED_CLIENT_IP_ADDRESS_CHANGED = 13, /** 14: Timeout for the keep-alive of the connection between the SDK and Agora's edge server. The connection state changes to CONNECTION_STATE_RECONNECTING(4). */ CONNECTION_CHANGED_KEEP_ALIVE_TIMEOUT = 14, - /** 15: In cloud proxy mode, the proxy server connection interrupted. */ - CONNECTION_CHANGED_PROXY_SERVER_INTERRUPTED = 15, + /** 19: The connection failed due to same uid joined again on another device. */ + CONNECTION_CHANGED_SAME_UID_LOGIN = 19, + /** 20: The connection failed due to too many broadcasters in the channel. */ + CONNECTION_CHANGED_TOO_MANY_BROADCASTERS = 20, }; /** Network type. */ @@ -1744,7 +1995,13 @@ enum NETWORK_TYPE { NETWORK_TYPE_MOBILE_3G = 4, /** 5: The network type is mobile 4G. */ NETWORK_TYPE_MOBILE_4G = 5, + /** 6: The network type is mobile 5G. + * + * @since v3.5.1 + */ + NETWORK_TYPE_MOBILE_5G = 6, }; +/// @cond /** * The reason for the upload failure. * @@ -1763,6 +2020,7 @@ enum UPLOAD_ERROR_REASON { */ UPLOAD_SERVER_ERROR = 2, }; +/// @endcond /** States of the last-mile network probe test. */ enum LASTMILE_PROBE_RESULT_STATE { @@ -1773,39 +2031,42 @@ enum LASTMILE_PROBE_RESULT_STATE { /** 3: The last-mile network probe test is not carried out, probably due to poor network conditions. */ LASTMILE_PROBE_RESULT_UNAVAILABLE = 3 }; -/** Audio output routing. */ +/** The current audio route. + * + * Reports in the \ref IRtcEngineEventHandler::onAudioRouteChanged "onAudioRouteChanged" callback. + */ enum AUDIO_ROUTE_TYPE { - /** Default. + /** -1: Default audio route. */ AUDIO_ROUTE_DEFAULT = -1, - /** Headset. + /** 0: The audio route is a headset with a microphone. */ AUDIO_ROUTE_HEADSET = 0, - /** Earpiece. + /** 1: The audio route is an earpiece. */ AUDIO_ROUTE_EARPIECE = 1, - /** Headset with no microphone. + /** 2: The audio route is a headset without a microphone. */ AUDIO_ROUTE_HEADSET_NO_MIC = 2, - /** Speakerphone. + /** 3: The audio route is the speaker that comes with the device. */ AUDIO_ROUTE_SPEAKERPHONE = 3, - /** Loudspeaker. + /** 4: (iOS and macOS only) The audio route is an external speaker. */ AUDIO_ROUTE_LOUDSPEAKER = 4, - /** Bluetooth headset. + /** 5: The audio route is a Bluetooth headset. */ AUDIO_ROUTE_BLUETOOTH = 5, - /** USB peripheral (macOS only). + /** 6: (macOS only) The audio route is a USB peripheral device. */ AUDIO_ROUTE_USB = 6, - /** HDMI peripheral (macOS only). + /** 7: (macOS only) The audio route is an HDMI peripheral device. */ AUDIO_ROUTE_HDMI = 7, - /** DisplayPort peripheral (macOS only). + /** 8: (macOS only) The audio route is a DisplayPort peripheral device. */ AUDIO_ROUTE_DISPLAYPORT = 8, - /** Apple AirPlay (macOS only). + /** 9: (iOS and macOS only) The audio route is Apple AirPlay. */ AUDIO_ROUTE_AIRPLAY = 9, }; @@ -1821,23 +2082,82 @@ enum CLOUD_PROXY_TYPE { /** 1: The cloud proxy for the UDP protocol. */ UDP_PROXY = 1, + /// @cond /** 2: The cloud proxy for the TCP (encrypted) protocol. */ TCP_PROXY = 2, + /// @endcond +}; +/// @cond +/** The local proxy mode type. */ +enum LOCAL_PROXY_MODE { + /** 0: Connect local proxy with high priority, if not connected to local proxy, fallback to sdrtn. + */ + ConnectivityFirst = 0, + /** 1: Only connect local proxy + */ + LocalOnly = 1, +}; +/// @endcond + +enum PROXY_TYPE { + /** 0: Do not use the cloud proxy. + */ + NONE_PROXY_TYPE = 0, + /** 1: The cloud proxy for the UDP protocol. + */ + UDP_PROXY_TYPE = 1, + /// @cond + /** 2: The cloud proxy for the TCP (encrypted) protocol. + */ + TCP_PROXY_TYPE = 2, + /// @endcond + /** 3: The local proxy. + */ + LOCAL_PROXY_TYPE = 3, + /** 4: auto fallback to tcp cloud proxy + */ + TCP_PROXY_AUTO_FALLBACK_TYPE = 4, }; +/** screencapture exclude window error. + * + * + */ +enum EXCLUDE_WINDOW_ERROR { + /** negative : fail to exclude window. + */ + EXCLUDE_WINDOW_FAIL = -1, + /** 0: none define. + */ + EXCLUDE_WINDOW_NONE = 0 +}; // namespace rtc #if (defined(__APPLE__) && TARGET_OS_IOS) -/** Audio session restriction. */ +/** + * The operational permission of the SDK on the audio session. + */ enum AUDIO_SESSION_OPERATION_RESTRICTION { - /** No restriction, the SDK has full control of the audio session operations. */ + /** + * 0: No restriction; the SDK can change the audio session. + */ AUDIO_SESSION_OPERATION_RESTRICTION_NONE = 0, - /** The SDK does not change the audio session category. */ + /** + * 1: The SDK cannot change the audio session category. + */ AUDIO_SESSION_OPERATION_RESTRICTION_SET_CATEGORY = 1, - /** The SDK does not change any setting of the audio session (category, mode, categoryOptions). */ + /** + * 2: The SDK cannot change the audio session category, mode, or categoryOptions. + */ AUDIO_SESSION_OPERATION_RESTRICTION_CONFIGURE_SESSION = 1 << 1, - /** The SDK keeps the audio session active when leaving a channel. */ + /** + * 4: The SDK keeps the audio session active when the user leaves the + * channel, for example, to play an audio file in the background. + */ AUDIO_SESSION_OPERATION_RESTRICTION_DEACTIVATE_SESSION = 1 << 2, - /** The SDK does not configure the audio session anymore. */ + /** + * 128: Completely restricts the operational permission of the SDK on the + * audio session; the SDK cannot change the audio session. + */ AUDIO_SESSION_OPERATION_RESTRICTION_ALL = 1 << 7, }; #endif @@ -1851,13 +2171,20 @@ enum CAMERA_DIRECTION { }; #endif -/** Audio recording position. */ +/** + * Recording content, which is set + * in \ref IRtcEngine::startAudioRecording(const AudioRecordingConfiguration&) "startAudioRecording". + */ enum AUDIO_RECORDING_POSITION { - /** The SDK will record the voices of all users in the channel. */ + /** 0: (Default) Records the mixed audio of the local user and all remote + * users. + */ AUDIO_RECORDING_POSITION_MIXED_RECORDING_AND_PLAYBACK = 0, - /** The SDK will record the voice of the local user. */ + /** 1: Records the audio of the local user only. + */ AUDIO_RECORDING_POSITION_RECORDING = 1, - /** The SDK will record the voices of remote users. */ + /** 2: Records the audio of all remote users only. + */ AUDIO_RECORDING_POSITION_MIXED_PLAYBACK = 2, }; @@ -1885,11 +2212,11 @@ struct LastmileProbeResult { /** Configurations of the last-mile network probe test. */ struct LastmileProbeConfig { - /** Sets whether or not to test the uplink network. Some users, for example, the audience in a `LIVE_BROADCASTING` channel, do not need such a test: + /** Sets whether to test the uplink network. Some users, for example, the audience in a `LIVE_BROADCASTING` channel, do not need such a test: - true: test. - false: do not test. */ bool probeUplink; - /** Sets whether or not to test the downlink network: + /** Sets whether to test the downlink network: - true: test. - false: do not test. */ bool probeDownlink; @@ -1918,7 +2245,7 @@ struct AudioVolumeInfo { * * @note * - The `vad` parameter cannot report the voice activity status of remote users. - * In the remote users' callback, `vad` is always `0`. + * In the remote users' callback, `vad` is always `1`. * - To use this parameter, you must set the `report_vad` parameter to `true` * when calling \ref agora::rtc::IRtcEngine::enableAudioVolumeIndication(int, int, bool) "enableAudioVolumeIndication". */ @@ -1927,6 +2254,62 @@ struct AudioVolumeInfo { */ const char* channelId; }; + +/** + * The information of an audio file. This struct is reported + * in \ref IRtcEngineEventHandler::onRequestAudioFileInfo "onRequestAudioFileInfo". + * + * @since v3.5.1 + */ +struct AudioFileInfo { + /** The file path. + */ + const char* filePath; + /** The file duration (ms). + */ + int durationMs; +}; + +/** The information acquisition state. This enum is reported + * in \ref IRtcEngineEventHandler::onRequestAudioFileInfo "onRequestAudioFileInfo". + * + * @since v3.5.1 + */ +enum AUDIO_FILE_INFO_ERROR { + /** 0: Successfully get the information of an audio file. + */ + AUDIO_FILE_INFO_ERROR_OK = 0, + + /** 1: Fail to get the information of an audio file. + */ + AUDIO_FILE_INFO_ERROR_FAILURE = 1 +}; + +/// @cond +/** + * The reason for failure of changing role. + * + * @since v3.6.1 + */ +enum CLIENT_ROLE_CHANGE_FAILED_REASON { + /** 1: Too many broadcasters in the channel. + */ + CLIENT_ROLE_CHANGE_FAILED_BY_TOO_MANY_BROADCASTERS = 1, + + /** 2: Change operation not authorized. + */ + CLIENT_ROLE_CHANGE_FAILED_BY_NOT_AUTHORIZED = 2, + + /** 3: Change operation timer out. + */ + CLIENT_ROLE_CHANGE_FAILED_BY_REQUEST_TIME_OUT = 3, + + /** 4: Change operation is interrupted since we lost connection with agora service. + */ + CLIENT_ROLE_CHANGE_FAILED_BY_CONNECTION_FAILED = 4, +}; +/// @endcond + /** The detailed options of a user. */ struct ClientRoleOptions { @@ -2013,7 +2396,9 @@ struct RtcStats { /** * Application CPU usage (%). * - * @note The `cpuAppUsage` reported in the \ref IRtcEngineEventHandler::onLeaveChannel "onLeaveChannel" callback is always 0. + * @note + * - The `cpuAppUsage` reported in the \ref IRtcEngineEventHandler::onLeaveChannel "onLeaveChannel" callback is always 0. + * - As of Android 8.1, you cannot get the CPU usage from this attribute due to system limitations. */ double cpuAppUsage; /** @@ -2022,10 +2407,19 @@ struct RtcStats { * In the multi-kernel environment, this member represents the average CPU usage. * The value **=** 100 **-** System Idle Progress in Task Manager (%). * - * @note The `cpuTotalUsage` reported in the \ref IRtcEngineEventHandler::onLeaveChannel "onLeaveChannel" callback is always 0. + * @note + * - The `cpuTotalUsage` reported in the \ref IRtcEngineEventHandler::onLeaveChannel "onLeaveChannel" callback is always 0. + * - As of Android 8.1, you cannot get the CPU usage from this attribute due to system limitations. */ double cpuTotalUsage; /** The round-trip time delay from the client to the local router. + * + * @note + * - On iOS, As of v3.3.0, this attribute is disabled on devices running iOS 14 or later, and enabled on devices + * running versions earlier than iOS 14 by default. To enable this property on devices running iOS 14 or later, + * contact support@agora.io. See [FAQ](https://docs.agora.io/en/Interactive%20Broadcast/faq/local_network_privacy) for details. + * - On Android, to get this attribute, ensure that the `android.permission.ACCESS_WIFI_STATE` permission has been added after `` in + * the `AndroidManifest.xml` file in your project. */ int gatewayRtt; /** @@ -2049,6 +2443,37 @@ struct RtcStats { 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), txPacketLossRate(0), rxPacketLossRate(0), userCount(0), cpuAppUsage(0), cpuTotalUsage(0), gatewayRtt(0), memoryAppUsageRatio(0), memoryTotalUsageRatio(0), memoryAppUsageInKbytes(0) {} }; +/** The reason of notifying the user of a message. + */ +enum WLACC_MESSAGE_REASON { + /** WIFI signal is weak.*/ + WLACC_MESSAGE_REASON_WEAK_SIGNAL = 0, + /** 2.4G band congestion.*/ + WLACC_MESSAGE_REASON_2G_CHANNEL_CONGESTION = 1, +}; +/** Suggest an action for the user. + */ +enum WLACC_SUGGEST_ACTION { + /** Please get close to AP.*/ + WLACC_SUGGEST_ACTION_CLOSE_TO_WIFI = 0, + /** The user is advised to connect to the prompted SSID.*/ + WLACC_SUGGEST_ACTION_CONNECT_5G = 1, + /** The user is advised to check whether the AP supports 5G band and enable 5G band (the aciton link is attached), or purchases an AP that supports 5G. AP does not support 5G band.*/ + WLACC_SUGGEST_ACTION_CHECK_5G = 2, + /** The user is advised to change the SSID of the 2.4G or 5G band (the aciton link is attached). The SSID of the 2.4G band AP is the same as that of the 5G band.*/ + WLACC_SUGGEST_ACTION_MODIFY_SSID = 3, +}; +/** Indicator optimization degree. + */ +struct WlAccStats { + /** End-to-end delay optimization percentage.*/ + unsigned short e2eDelayPercent; + /** Frozen Ratio optimization percentage.*/ + unsigned short frozenRatioPercent; + /** Loss Rate optimization percentage.*/ + unsigned short lossRatePercent; +}; + /** Quality change of the local video in terms of target frame rate and target bit rate since last count. */ enum QUALITY_ADAPT_INDICATION { @@ -2059,6 +2484,12 @@ enum QUALITY_ADAPT_INDICATION { /** The quality worsens because the network bandwidth decreases. */ ADAPT_DOWN_BANDWIDTH = 2, }; + +struct ScreenCaptureInfo { + const char* graphicsCardType; + EXCLUDE_WINDOW_ERROR errCode; +}; + /** Quality of experience (QoE) of the local user when receiving a remote audio stream. * * @since v3.3.0 @@ -2185,6 +2616,26 @@ enum CHANNEL_MEDIA_RELAY_EVENT { /** 11: The video profile is sent to the server. */ RELAY_EVENT_VIDEO_PROFILE_UPDATE = 11, + /** 12: The SDK successfully pauses relaying the media stream to destination channels. + * + * @since v3.5.1 + */ + RELAY_EVENT_PAUSE_SEND_PACKET_TO_DEST_CHANNEL_SUCCESS = 12, + /** 13: The SDK fails to pause relaying the media stream to destination channels. + * + * @since v3.5.1 + */ + RELAY_EVENT_PAUSE_SEND_PACKET_TO_DEST_CHANNEL_FAILED = 13, + /** 14: The SDK successfully resumes relaying the media stream to destination channels. + * + * @since v3.5.1 + */ + RELAY_EVENT_RESUME_SEND_PACKET_TO_DEST_CHANNEL_SUCCESS = 14, + /** 15: The SDK fails to resume relaying the media stream to destination channels. + * + * @since v3.5.1 + */ + RELAY_EVENT_RESUME_SEND_PACKET_TO_DEST_CHANNEL_FAILED = 15, }; /** The state code in CHANNEL_MEDIA_RELAY_STATE. */ @@ -2206,6 +2657,12 @@ enum CHANNEL_MEDIA_RELAY_STATE { RELAY_STATE_FAILURE = 3, }; +/**Audio Device Test.different volume Type*/ +enum AudioDeviceTestVolumeType { + AudioTestRecordingVolume = 0, + AudioTestPlaybackVolume = 1, +}; + /** Statistics of the local video stream. */ struct LocalVideoStats { @@ -2509,10 +2966,6 @@ struct VideoEncoderConfiguration { | 1920 * 1080 | 15 | 2080 | 4160 | | 1920 * 1080 | 30 | 3150 | 6300 | | 1920 * 1080 | 60 | 4780 | 6500 | - | 2560 * 1440 | 30 | 4850 | 6500 | - | 2560 * 1440 | 60 | 6500 | 6500 | - | 3840 * 2160 | 30 | 6500 | 6500 | - | 3840 * 2160 | 60 | 6500 | 6500 | */ int bitrate; @@ -2540,36 +2993,48 @@ struct VideoEncoderConfiguration { VideoEncoderConfiguration() : dimensions(640, 480), frameRate(FRAME_RATE_FPS_15), minFrameRate(-1), bitrate(STANDARD_BITRATE), minBitrate(DEFAULT_MIN_BITRATE), orientationMode(ORIENTATION_MODE_ADAPTIVE), degradationPreference(MAINTAIN_QUALITY), mirrorMode(VIDEO_MIRROR_MODE_AUTO) {} }; -/** Audio recording configurations. +/** Recording configuration, which is set in + * \ref IRtcEngine::startAudioRecording(const AudioRecordingConfiguration&) "startAudioRecording". + * + * @since v3.4.0 */ struct AudioRecordingConfiguration { - /** Pointer to the absolute file path of the recording file. The string of the file name is in UTF-8. - - The SDK determines the storage format of the recording file by the file name suffix: - - - .wav: Large file size with high fidelity. - - .aac: Small file size with low fidelity. - - Ensure that the directory to save the recording file exists and is writable. + /** The absolute path (including the filename extensions) of the recording + * file. For example: `C:\music\audio.aac`. + * + * @note Ensure that the path you specify exists and is writable. */ const char* filePath; - /** Sets the audio recording quality. See #AUDIO_RECORDING_QUALITY_TYPE. - - @note It is effective only when the recording format is AAC. + /** Audio recording quality. See #AUDIO_RECORDING_QUALITY_TYPE. + * + * @note This parameter applies to AAC files only. */ AUDIO_RECORDING_QUALITY_TYPE recordingQuality; - /** Sets the audio recording position. See #AUDIO_RECORDING_POSITION. + /** Recording content. See #AUDIO_RECORDING_POSITION. */ AUDIO_RECORDING_POSITION recordingPosition; - /** Sets the sample rate (Hz) of the recording file. Supported values are as follows: - * - 16000 - * - (Default) 32000 - * - 44100 - * - 48000 + /** Recording sample rate (Hz). The following values are supported: + * + * - `16000` + * - (Default) `32000` + * - `44100` + * - `48000` + * + * @note If this parameter is set to `44100` or `48000`, for better + * recording effects, Agora recommends recording WAV files or AAC files + * whose `recordingQuality` is + * #AUDIO_RECORDING_QUALITY_MEDIUM or #AUDIO_RECORDING_QUALITY_HIGH. */ int recordingSampleRate; - AudioRecordingConfiguration() : filePath(nullptr), recordingQuality(AUDIO_RECORDING_QUALITY_MEDIUM), recordingPosition(AUDIO_RECORDING_POSITION_MIXED_RECORDING_AND_PLAYBACK), recordingSampleRate(32000) {} - AudioRecordingConfiguration(const char* path, AUDIO_RECORDING_QUALITY_TYPE quality, AUDIO_RECORDING_POSITION position, int sampleRate) : filePath(path), recordingQuality(quality), recordingPosition(position), recordingSampleRate(sampleRate) {} + /** Recording channel. The following values are supported: + * + * - (Default) 1 + * - 2 + */ + int recordingChannel; + + AudioRecordingConfiguration() : filePath(nullptr), recordingQuality(AUDIO_RECORDING_QUALITY_MEDIUM), recordingPosition(AUDIO_RECORDING_POSITION_MIXED_RECORDING_AND_PLAYBACK), recordingSampleRate(32000), recordingChannel(1) {} + AudioRecordingConfiguration(const char* path, AUDIO_RECORDING_QUALITY_TYPE quality, AUDIO_RECORDING_POSITION position, int sampleRate, int channel) : filePath(path), recordingQuality(quality), recordingPosition(position), recordingSampleRate(sampleRate), recordingChannel(channel) {} }; /** The video and audio properties of the user displaying the video in the CDN live. Agora supports a maximum of 17 transcoding users in a CDN streaming channel. @@ -2629,7 +3094,7 @@ typedef struct TranscodingUser { The properties of the watermark and background images. */ typedef struct RtcImage { - RtcImage() : url(NULL), x(0), y(0), width(0), height(0) {} + RtcImage() : url(NULL), x(0), y(0), width(0), height(0), zOrder(0), alpha(1.0) {} /** HTTP/HTTPS URL address of the image on the live video. The maximum length of this parameter is 1024 bytes. */ const char* url; /** Horizontal position of the image from the upper left of the live video. */ @@ -2640,17 +3105,32 @@ typedef struct RtcImage { int width; /** Height of the image on the live video. */ int height; + /** + * The layer number of the watermark or background image. The value range is [0,255]: + * - `0`: (Default) The bottom layer. + * - `255`: The top layer. + * + * @since v3.6.0 + */ + int zOrder; + /** The transparency of the watermark or background image. The value range is [0.0,1.0]: + * - `0.0`: Completely transparent. + * - `1.0`: (Default) Opaque. + * + * @since v3.6.0 + */ + double alpha; } RtcImage; /// @cond /** The configuration for advanced features of the RTMP or RTMPS streaming with transcoding. */ typedef struct LiveStreamAdvancedFeature { LiveStreamAdvancedFeature() : featureName(NULL), opened(false) {} - + LiveStreamAdvancedFeature(const char* feat_name, bool open) : featureName(feat_name), opened(open) {} /** The advanced feature for high-quality video with a lower bitrate. */ - const char* LBHQ = "lbhq"; + // static const char* LBHQ = "lbhq"; /** The advanced feature for the optimized video encoder. */ - const char* VEO = "veo"; + // static const char* VEO = "veo"; /** The name of the advanced feature. It contains LBHQ and VEO. */ @@ -2662,17 +3142,22 @@ typedef struct LiveStreamAdvancedFeature { */ bool opened; } LiveStreamAdvancedFeature; + /// @endcond /** A struct for managing CDN live audio/video transcoding settings. */ typedef struct LiveTranscoding { /** The width of the video in pixels. The default value is 360. - * - When pushing video streams to the CDN, ensure that `width` is at least 64; otherwise, the Agora server adjusts the value to 64. + * - When pushing video streams to the CDN, the value range of `width` is [64,1920]. + * If the value is less than 64, Agora server automatically adjusts it to 64; if the + * value is greater than 1920, Agora server automatically adjusts it to 1920. * - When pushing audio streams to the CDN, set `width` and `height` as 0. */ int width; /** The height of the video in pixels. The default value is 640. - * - When pushing video streams to the CDN, ensure that `height` is at least 64; otherwise, the Agora server adjusts the value to 64. + * - When pushing video streams to the CDN, the value range of `height` is [64,1080]. + * If the value is less than 64, Agora server automatically adjusts it to 64; if the + * value is greater than 1080, Agora server automatically adjusts it to 1080. * - When pushing audio streams to the CDN, set `width` and `height` as 0. */ int height; @@ -2706,10 +3191,16 @@ typedef struct LiveTranscoding { */ unsigned int backgroundColor; - /** video codec type */ + /** + * The video codec type of the output video stream. See #VIDEO_CODEC_TYPE_FOR_STREAM. + * + * @since v3.2.0 + */ VIDEO_CODEC_TYPE_FOR_STREAM videoCodecType; /** The number of users in the interactive live streaming. + * + * The value range is [0, 17]. */ unsigned int userCount; /** TranscodingUser @@ -2724,16 +3215,33 @@ typedef struct LiveTranscoding { /** **DEPRECATED** The metadata sent to the CDN live client defined by the RTMP or HTTP-FLV metadata. */ const char* metadata; - /** The watermark image added to the CDN live publishing stream. - - Ensure that the format of the image is PNG. Once a watermark image is added, the audience of the CDN live publishing stream can see the watermark image. See RtcImage. - */ + /** + * The watermark on the live video. The format must be in the PNG format. See RtcImage. + * You can add a watermark or use an array to add multiple watermarks. + * This parameter is used in conjunction with `watermarkCount`. + */ RtcImage* watermark; - /** The background image added to the CDN live publishing stream. - Once a background image is added, the audience of the CDN live publishing stream can see the background image. See RtcImage. - */ + /** + * The number of watermarks on the live video. The value range is [0,100]. + * This parameter is used in conjunction with `watermark`. + * + * @since v3.6.0 + */ + unsigned int watermarkCount; + + /** + * The background image on the live video. The format must be in the PNG format. See RtcImage. + * You can add a background image or use an array to add multiple background images. + * This parameter is used in conjunction with `backgroundImageCount`. + */ RtcImage* backgroundImage; + /** + * The number of background images on the live video. The value range is [0,100]. + * This parameter is used in conjunction with `backgroundImage`. + */ + unsigned int backgroundImageCount; + /** Self-defined audio-sample rate: #AUDIO_SAMPLE_RATE_TYPE. */ AUDIO_SAMPLE_RATE_TYPE audioSampleRate; @@ -2763,7 +3271,7 @@ typedef struct LiveTranscoding { /** The number of enabled advanced features. The default value is 0. */ unsigned int advancedFeatureCount; /// @endcond - LiveTranscoding() : width(360), height(640), videoBitrate(400), videoFramerate(15), lowLatency(false), videoGop(30), videoCodecProfile(VIDEO_CODEC_PROFILE_HIGH), backgroundColor(0x000000), videoCodecType(VIDEO_CODEC_H264_FOR_STREAM), userCount(0), transcodingUsers(NULL), transcodingExtraInfo(NULL), metadata(NULL), watermark(NULL), backgroundImage(NULL), audioSampleRate(AUDIO_SAMPLE_RATE_48000), audioBitrate(48), audioChannels(1), audioCodecProfile(AUDIO_CODEC_PROFILE_LC_AAC), advancedFeatures(NULL), advancedFeatureCount(0) {} + LiveTranscoding() : width(360), height(640), videoBitrate(400), videoFramerate(15), lowLatency(false), videoGop(30), videoCodecProfile(VIDEO_CODEC_PROFILE_HIGH), backgroundColor(0x000000), videoCodecType(VIDEO_CODEC_H264_FOR_STREAM), 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), advancedFeatures(NULL), advancedFeatureCount(0) {} } LiveTranscoding; /** Camera capturer configuration. @@ -2916,6 +3424,29 @@ struct ChannelMediaRelayConfiguration { ChannelMediaRelayConfiguration() : srcInfo(nullptr), destInfos(nullptr), destCount(0) {} }; +/// @cond +struct LocalAccessPointConfiguration { + /** local access point ip address list. + */ + const char** ipList; + /** the number of local access point ip address. + */ + int ipListSize; + /** local access point domain list. + */ + const char** domainList; + /** the number of local access point domain. + */ + int domainListSize; + /** certificate domain name installed on specific local access point. pass "" means using sni domain on specific local access point + */ + const char* verifyDomainName; + /** local proxy connection mode, connectivity first or local only. + */ + LOCAL_PROXY_MODE mode; + LocalAccessPointConfiguration() : ipList(nullptr), ipListSize(0), domainList(nullptr), domainListSize(0), verifyDomainName(nullptr), mode(ConnectivityFirst) {} +}; +/// @endcond /** **DEPRECATED** Lifecycle of the CDN live video stream. */ @@ -3025,7 +3556,7 @@ struct ScreenCaptureParameters { The default value is 0 (the SDK works out a bitrate according to the dimensions of the current screen). */ int bitrate; - /** Sets whether or not to capture the mouse for screen sharing: + /** Sets whether to capture the mouse for screen sharing: - true: (Default) Capture the mouse. - false: Do not capture the mouse. @@ -3098,10 +3629,10 @@ struct VideoCanvas { /** Image enhancement options. */ struct BeautyOptions { - /** The contrast level, used with the @p lightening parameter. + /** The contrast level, often used in conjunction with `lighteningLevel`. */ enum LIGHTENING_CONTRAST_LEVEL { - /** Low contrast level. */ + /** 0: Low contrast level. */ LIGHTENING_CONTRAST_LOW = 0, /** (Default) Normal contrast level. */ LIGHTENING_CONTRAST_NORMAL, @@ -3109,24 +3640,194 @@ struct BeautyOptions { LIGHTENING_CONTRAST_HIGH }; - /** The contrast level, used with the @p lightening parameter. + /** The contrast level, often used in conjunction with `lighteningLevel`. + * The higher the value, the greater the contrast level. See #LIGHTENING_CONTRAST_LEVEL. */ LIGHTENING_CONTRAST_LEVEL lighteningContrastLevel; - /** The brightness level. The value ranges from 0.0 (original) to 1.0. */ + /** + * The brightening level, in the range [0.0,1.0], where 0.0 means the original brightening. The default value is 0.6. The higher the value, the greater the brightening level. + */ float lighteningLevel; - /** The sharpness level. The value ranges between 0 (original) and 1. This parameter is usually used to remove blemishes. + /** The smoothness level, in the range [0.0,1.0], where 0.0 means the original smoothness. The default value is 0.5. The higher the value, the greater the smoothness level. */ float smoothnessLevel; - /** The redness level. The value ranges between 0 (original) and 1. This parameter adjusts the red saturation level. + /** The redness level, in the range [0.0,1.0], where 0.0 means the original redness. The default value is 0.1. The higher the value, the greater the redness level. */ float rednessLevel; - BeautyOptions(LIGHTENING_CONTRAST_LEVEL contrastLevel, float lightening, float smoothness, float redness) : lighteningLevel(lightening), smoothnessLevel(smoothness), rednessLevel(redness), lighteningContrastLevel(contrastLevel) {} + /** The sharpness level, in the range [0.0,1.0], where 0.0 means the original sharpness. + * The default value is 0.3. The higher the value, the greater the sharpness level. + * + * @since v3.6.0 + */ + float sharpnessLevel; + + BeautyOptions(LIGHTENING_CONTRAST_LEVEL contrastLevel, float lightening, float smoothness, float redness, float sharpness) : lighteningLevel(lightening), smoothnessLevel(smoothness), rednessLevel(redness), lighteningContrastLevel(contrastLevel), sharpnessLevel(sharpness) {} + + BeautyOptions() : lighteningLevel(0), smoothnessLevel(0), rednessLevel(0), sharpnessLevel(0), lighteningContrastLevel(LIGHTENING_CONTRAST_NORMAL) {} +}; + +/** lowlight enhancement options. + */ +struct LowLightEnhanceOptions { + enum LOW_LIGHT_ENHANCE_MODE { + /** low light enhancement is applied automatically when neccessary. */ + LOW_LIGHT_ENHANCE_AUTO = 0, + /** low light enhancement is applied manually. */ + LOW_LIGHT_ENHANCE_MANUAL + }; + + enum LOW_LIGHT_ENHANCE_LEVEL { + /** low light enhancement is applied without reducing frame rate. */ + LOW_LIGHT_ENHANCE_LEVEL_HIGH_QUALITY = 0, + /** High-quality low light enhancement is applied, at the cost of possibly reduced frame rate and higher cpu usage. */ + LOW_LIGHT_ENHANCE_LEVEL_FAST + }; + + /** lowlight enhancement mode. + */ + LOW_LIGHT_ENHANCE_MODE mode; + + /** lowlight enhancement level. + */ + LOW_LIGHT_ENHANCE_LEVEL level; + + LowLightEnhanceOptions(LOW_LIGHT_ENHANCE_MODE lowlightMode, LOW_LIGHT_ENHANCE_LEVEL lowlightLevel) : mode(lowlightMode), level(lowlightLevel) {} + + LowLightEnhanceOptions() : mode(LOW_LIGHT_ENHANCE_AUTO), level(LOW_LIGHT_ENHANCE_LEVEL_HIGH_QUALITY) {} +}; + +struct VideoDenoiserOptions { + /** video noise reduction mode + */ + enum VIDEO_DENOISER_MODE { + /** video noise reduction is applied automatically when neccessary. */ + VIDEO_DENOISER_AUTO = 0, + /** video noise reduction is applied manually. */ + VIDEO_DENOISER_MANUAL + }; + + enum VIDEO_DENOISER_LEVEL { + /** Video noise reduction is applied for the default scene */ + VIDEO_DENOISER_LEVEL_HIGH_QUALITY = 0, + /** Video noise reduction is applied for the fixed-camera scene to save the cpu usage */ + VIDEO_DENOISER_LEVEL_FAST, + /** Video noise reduction is applied for the high noisy scene to further denoise the video. */ + VIDEO_DENOISER_LEVEL_STRENGTH + }; + /** video noise reduction mode. + */ + VIDEO_DENOISER_MODE mode; + + /** video noise reduction level. + */ + VIDEO_DENOISER_LEVEL level; + + VideoDenoiserOptions(VIDEO_DENOISER_MODE denoiserMode, VIDEO_DENOISER_LEVEL denoiserLevel) : mode(denoiserMode), level(denoiserLevel) {} + + VideoDenoiserOptions() : mode(VIDEO_DENOISER_AUTO), level(VIDEO_DENOISER_LEVEL_HIGH_QUALITY) {} +}; + +/** color enhancement options. + */ +struct ColorEnhanceOptions { + /** Color enhance strength. The value ranges between 0 (original) and 1. + */ + float strengthLevel; + + /** Skin protect level. The value ranges between 0 (original) and 1. + */ + float skinProtectLevel; + + ColorEnhanceOptions(float stength, float skinProtect) : strengthLevel(stength), skinProtectLevel(skinProtect) {} + + ColorEnhanceOptions() : strengthLevel(0), skinProtectLevel(1) {} +}; + +/** The custom background image. + * + * @since v3.4.5 + */ +struct VirtualBackgroundSource { + /** The type of the custom background image. + * + * @since v3.4.5 + */ + enum BACKGROUND_SOURCE_TYPE { + /** + * 1: (Default) The background image is a solid color. + */ + BACKGROUND_COLOR = 1, + /** + * The background image is a file in PNG or JPG format. + */ + BACKGROUND_IMG, + /** + * The background image is blurred. + * + * @since v3.5.1 + */ + BACKGROUND_BLUR, + }; + + /** + * The degree of blurring applied to the custom background image. + * + * @since v3.5.1 + */ + enum BACKGROUND_BLUR_DEGREE { + /** + * 1: The degree of blurring applied to the custom background image is low. + * The user can almost see the background clearly. + */ + BLUR_DEGREE_LOW = 1, + /** + * 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_MEDIUM, + /** + * (Default) The degree of blurring applied to the custom background image is high. + * The user can barely see any distinguishing features in the background. + */ + BLUR_DEGREE_HIGH, + }; + + /** The type of the custom background image. See #BACKGROUND_SOURCE_TYPE. + */ + BACKGROUND_SOURCE_TYPE background_source_type; + + /** + * 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`. + */ + unsigned int color; + + /** + * 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`. + */ + const char* source; + + /** + * The degree of blurring applied to the custom background image. See #BACKGROUND_BLUR_DEGREE. + * + * @note This parameter takes effect only when the type of the custom background image is `BACKGROUND_BLUR`. + * + * @since v3.5.1 + */ + BACKGROUND_BLUR_DEGREE blur_degree; - BeautyOptions() : lighteningLevel(0), smoothnessLevel(0), rednessLevel(0), lighteningContrastLevel(LIGHTENING_CONTRAST_NORMAL) {} + VirtualBackgroundSource() : color(0xffffff), source(NULL), background_source_type(BACKGROUND_COLOR), blur_degree(BLUR_DEGREE_HIGH) {} }; /** @@ -3143,6 +3844,46 @@ struct UserInfo { char userAccount[MAX_USER_ACCOUNT_LENGTH]; UserInfo() : uid(0) { userAccount[0] = '\0'; } }; +/** + * The configuration of the audio and video call loop test. + * + * @since v3.5.2 + */ +struct EchoTestConfiguration { + /** + * The view used to render the local user's video. This parameter is only applicable to scenarios testing video + * devices, that is, when `enableVideo` is `true`. + */ + view_t view; + /** + * Whether to enable the audio device for the call loop test: + * - true: (Default) Enables the audio device. To test the audio device, set this parameter as `true`. + * - false: Disables the audio device. + */ + bool enableAudio; + /** + * Whether to enable the video device for the call loop test: + * - true: (Default) Enables the video device. To test the video device, set this parameter as `true`. + * - false: Disables the video device. + */ + bool enableVideo; + /** + * The token used to secure the audio and video call loop test. If you do not enable App Certificate in Agora + * Console, you do not need to pass a value in this parameter; if you have enabled App Certificate in Agora Console, + * you must pass a token in this parameter, the `uid` used when you generate the token must be 0xFFFFFFFF, and the + * channel name used must be the channel name that identifies each audio and video call loop tested. For server-side + * token generation, see [Authenticate Your Users with Tokens](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=All%20Platforms). + */ + const char* token; + /** + * The channel name that identifies each audio and video call loop. To ensure proper loop test functionality, the + * channel name passed in to identify each loop test cannot be the same when users of the same project (App ID) + * perform audio and video call loop tests on different devices. + */ + const char* channelId; + EchoTestConfiguration() : view(NULL), enableAudio(true), enableVideo(true), token(NULL), channelId(NULL) {} + EchoTestConfiguration(view_t v, bool ea, bool ev, const char* t, const char* c) : view(v), enableAudio(ea), enableVideo(ev), token(t), channelId(c) {} +}; /** * Regions for connetion. @@ -3190,6 +3931,71 @@ enum ENCRYPTION_CONFIG { */ ENCRYPTION_FORCE_DISABLE_PACKET = (1 << 1) }; +/// @cond +typedef int ContentInspectType; +/** + * (Default) content inspect type invalid + */ +const ContentInspectType kContentInspectInvalid = 0; +/** + * Content inspect type moderation + */ +const ContentInspectType kContentInspectModeration = 1; +/** + * Content inspect type supervise + */ +const ContentInspectType kContentInspectSupervise = 2; + +enum MAX_CONTENT_INSPECT_MODULE_TYPE { + /** The maximum count of content inspect feature type is 32. + */ + MAX_CONTENT_INSPECT_MODULE_COUNT = 32 +}; +/// @endcond +/// @cond +/** Definition of ContentInspectModule. + */ +struct ContentInspectModule { + /** + * The content inspect module type. + * the module type can be 0 to 31. + * kContentInspectInvalid(0) + * kContentInspectModeration(1) + * kContentInspectSupervise(2) + */ + ContentInspectType type; + /**The content inspect frequency, default is 0 second. + * the frequency <= 0 is invalid. + */ + int interval; + /**The content inspect default value. + */ + ContentInspectModule() { + type = kContentInspectInvalid; + interval = 0; + } +}; +/// @endcond +/// @cond +/** Definition of ContentInspectConfig. + */ +struct ContentInspectConfig { + /** The extra information, max length of extraInfo is 1024. + * The extra information will send to server with content(image). + */ + const char* extraInfo; + /**The content inspect modules, max length of modules is 32. + * the content(snapshot of send video stream, image) can be used to max of 32 types functions. + */ + ContentInspectModule modules[MAX_CONTENT_INSPECT_MODULE_COUNT]; + /**The content inspect module count. + */ + int moduleCount; + + ContentInspectConfig() : extraInfo(NULL), moduleCount(0) {} +}; +/// @endcond + /** Definition of IPacketObserver. */ class IPacketObserver { @@ -3198,7 +4004,9 @@ class IPacketObserver { */ struct Packet { /** Buffer address of the sent or received data. - * @note Agora recommends that the value of buffer is more than 2048 bytes, otherwise, you may meet undefined behaviors such as a crash. + * + * @note Agora recommends that the value of buffer is more than 2048 bytes, + * otherwise, you may meet undefined behaviors such as a crash. */ const unsigned char* buffer; /** Buffer size of the sent or received data. @@ -3239,7 +4047,6 @@ class IPacketObserver { virtual bool onReceiveVideoPacket(Packet& packet) = 0; }; -#if defined(_WIN32) /** The capture type of the custom video source. */ enum VIDEO_CAPTURE_TYPE { @@ -3349,7 +4156,158 @@ class IVideoSource { */ virtual VideoContentHint getVideoContentHint() = 0; }; + +#if (defined(__APPLE__) && TARGET_OS_MAC && !TARGET_OS_IPHONE) +/** + * The target size of the thumbnail or icon. (macOS only) + * + * @since v3.5.2 + */ +struct SIZE { + /** The target width (px) of the thumbnail or icon. The default value is 0. + */ + int width; + /** The target height (px) of the thumbnail or icon. The default value is 0. + */ + int height; + + SIZE() : width(0), height(0) {} + SIZE(int w, int h) : width(w), height(h) {} +}; #endif +/** + * The image content of the thumbnail or icon. + * + * @since v3.5.2 + * + * @note The default image is in the RGBA format. If you need to use another format, you need to convert the image on + * your own. + */ +struct ThumbImageBuffer { + /** + * The buffer of the thumbnail or icon. + */ + const char* buffer; + /** + * The buffer length (bytes) of the thumbnail or icon. + */ + unsigned int length; + /** + * The actual width (px) of the thumbnail or icon. + */ + unsigned int width; + /** + * The actual height (px) of the thumbnail or icon. + */ + unsigned int height; + ThumbImageBuffer() : buffer(nullptr), length(0), width(0), height(0) {} +}; +/** + * The type of the shared target. + * + * @since v3.5.2 + */ +enum ScreenCaptureSourceType { + /** + * -1: Unknown type. + */ + ScreenCaptureSourceType_Unknown = -1, + /** + * 0: The shared target is a window. + */ + ScreenCaptureSourceType_Window = 0, + /** + * 1: The shared target is a screen of a particular monitor. + */ + ScreenCaptureSourceType_Screen = 1, + /** + * 2: Reserved parameter. + */ + ScreenCaptureSourceType_Custom = 2, +}; +/** + * The information about the specified shareable window or screen. + * + * @since v3.5.2 + */ +struct ScreenCaptureSourceInfo { + /** + * The type of the shared target. See \ref agora::rtc::ScreenCaptureSourceType "ScreenCaptureSourceType". + */ + ScreenCaptureSourceType type; + /** + * The window ID for a window or the display ID for a screen. + */ + view_t sourceId; + /** + * The name of the window or screen. UTF-8 encoding. + */ + const char* sourceName; + /** + * The image content of the thumbnail. See ThumbImageBuffer. + */ + ThumbImageBuffer thumbImage; + /** + * The image content of the icon. See ThumbImageBuffer. + */ + ThumbImageBuffer iconImage; + /** + * The process to which the window belongs. UTF-8 encoding. + */ + const char* processPath; + /** + * The title of the window. UTF-8 encoding. + */ + const char* sourceTitle; + /** + * Determines whether the screen is the primary display: + * - true: The screen is the primary display. + * - false: The screen is not the primary display. + */ + bool primaryMonitor; + ScreenCaptureSourceInfo() : type(ScreenCaptureSourceType_Unknown), sourceId(nullptr), sourceName(nullptr), processPath(nullptr), sourceTitle(nullptr), primaryMonitor(false) {} +}; +/** + * The IScreenCaptureSourceList class. + * + * @since v3.5.2 + */ +class IScreenCaptureSourceList { + protected: + virtual ~IScreenCaptureSourceList(){}; + + public: + /** + * Gets the number of shareable windows and screens. + * + * @since v3.5.2 + * + * @return The number of shareable windows and screens. + */ + virtual unsigned int getCount() = 0; + /** + * Gets information about the specified shareable window or screen. + * + * @since v3.5.2 + * + * After you get IScreenCaptureSourceList, you can pass in the index value of the specified shareable window or + * screen to get information about that window or screen from ScreenCaptureSourceInfo. + * + * @param index The index of the specified shareable window or screen. The value range is [0,`getCount()`). + * + * @return ScreenCaptureSourceInfo + */ + virtual ScreenCaptureSourceInfo getSourceInfo(unsigned int index) = 0; + /** + * Releases IScreenCaptureSourceList. + * + * @since v3.5.2 + * + * After you get the list of shareable windows and screens, to avoid memory leaks, call `release` to release + * `IScreenCaptureSourceList` instead of deleting `IScreenCaptureSourceList` directly. + */ + virtual void release() = 0; +}; /** The SDK uses the IRtcEngineEventHandler interface class to send callbacks to the application. The application inherits the methods of this interface class to retrieve these callbacks. @@ -3421,7 +4379,7 @@ class IRtcEngineEventHandler { This callback notifies the application that a user leaves the channel when the application calls the \ref IRtcEngine::leaveChannel "leaveChannel" method. - The application retrieves information, such as the call duration and statistics. + The application gets information, such as the call duration and statistics. @param stats Pointer to the statistics of the call: RtcStats. */ @@ -3429,14 +4387,24 @@ class IRtcEngineEventHandler { /** Occurs when the user role switches in the interactive live streaming. For example, from a host to an audience or vice versa. - This callback notifies the application of a user role switch when the application calls the \ref IRtcEngine::setClientRole "setClientRole" method. + This callback notifies the application of a user role switch when the application calls the \ref IRtcEngine::setClientRole "setClientRole" method, and successfully changed role. - The SDK triggers this callback when the local user switches the user role by calling the \ref agora::rtc::IRtcEngine::setClientRole "setClientRole" method after joining the channel. + The SDK triggers this callback when the local user switches the user role by calling the \ref agora::rtc::IRtcEngine::setClientRole "setClientRole" method after joining the channel, and successfully changed role. @param oldRole Role that the user switches from: #CLIENT_ROLE_TYPE. @param newRole Role that the user switches to: #CLIENT_ROLE_TYPE. */ virtual void onClientRoleChanged(CLIENT_ROLE_TYPE oldRole, CLIENT_ROLE_TYPE newRole) {} + /** Occurs when the user role switches in the interactive live streaming. For example, from a host to an audience or vice versa. + + This callback notifies the application of a user role switch when the application calls the \ref IRtcEngine::setClientRole "setClientRole" method, and failed to change role. + + The SDK triggers this callback when the local user switches the user role by calling the \ref agora::rtc::IRtcEngine::setClientRole "setClientRole" method after joining the channel, and failed to change role. + @param reason The reason of changing client role failed. See #CLIENT_ROLE_CHANGE_FAILED_REASON. + @param currentRole Current Role that the user holds: #CLIENT_ROLE_TYPE. + */ + virtual void onClientRoleChangeFailed(CLIENT_ROLE_CHANGE_FAILED_REASON reason, CLIENT_ROLE_TYPE currentRole) {} + /** Occurs when a remote user (`COMMUNICATION`)/ host (`LIVE_BROADCASTING`) joins the channel. - `COMMUNICATION` profile: This callback notifies the application that another user joins the channel. If other users are already in the channel, the SDK also reports to the application on the existing users. @@ -3476,6 +4444,21 @@ class IRtcEngineEventHandler { (void)reason; } + /** Occurs when join success after calling \ref IRtcEngine::setLocalAccessPoint "setLocalAccessPoint" or \ref IRtcEngine::setCloudProxy "setCloudProxy" + @param channel Channel name. + @param uid User ID of the user joining the channel. + @param proxyType type of proxy agora sdk connected, proxyType will be NONE_PROXY_TYPE if not connected to proxy(fallback). + @param localProxyIp local proxy ip. if not join local proxy, it will be "". + @param elapsed Time elapsed (ms) from the user calling the \ref IRtcEngine::joinChannel "joinChannel" method until the SDK triggers this callback. + */ + virtual void onProxyConnected(const char* channel, uid_t uid, PROXY_TYPE proxyType, const char* localProxyIp, int elapsed) { + (void)channel; + (void)uid; + (void)proxyType; + (void)localProxyIp; + (void)elapsed; + } + /** Reports the last mile network quality of the local user once every two seconds before the user joins the channel. Last mile refers to the connection between the local device and Agora's edge server. After the application calls the \ref IRtcEngine::enableLastmileTest "enableLastmileTest" method, this callback reports once every two seconds the uplink and downlink last mile network conditions of the local user before the user joins the channel. @@ -3556,7 +4539,7 @@ class IRtcEngineEventHandler { The user becomes offline if the token used in the \ref IRtcEngine::joinChannel "joinChannel" method expires. The SDK triggers this callback 30 seconds before the token expires to remind the application to get a new token. Upon receiving this callback, generate a new token on the server and call the \ref IRtcEngine::renewToken "renewToken" method to pass the new token to the SDK. - @param token Pointer to the token that expires in 30 seconds. + @param token The token that expires in 30 seconds. */ virtual void onTokenPrivilegeWillExpire(const char* token) { (void)token; } @@ -3587,12 +4570,16 @@ class IRtcEngineEventHandler { virtual void onRtcStats(const RtcStats& stats) { (void)stats; } /** Reports the last mile network quality of each user in the channel once every two seconds. - - Last mile refers to the connection between the local device and Agora's edge server. This callback reports once every two seconds the last mile network conditions of each user in the channel. If a channel includes multiple users, the SDK triggers this callback as many times. - - @param uid User ID. The network quality of the user with this @p uid is reported. If @p uid is 0, the local network quality is reported. - @param txQuality Uplink transmission quality rating of the user in terms of the transmission bitrate, packet loss rate, average RTT (Round-Trip Time), and jitter of the uplink network. @p txQuality is a quality rating helping you understand how well the current uplink network conditions can support the selected VideoEncoderConfiguration. 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 may be inadequate for resolutions higher than 1280 * 720. See #QUALITY_TYPE. - @param rxQuality Downlink network quality rating of the user in terms of the packet loss rate, average RTT, and jitter of the downlink network. See #QUALITY_TYPE. + * + * Last mile refers to the connection between the local device and Agora's edge server. This callback + * reports once every two seconds the last mile network conditions of each user in the channel. If a channel includes + * multiple users, the SDK triggers this callback as many times. + * + * @note `txQuality` is `UNKNOWN` when the user is not sending a stream; `rxQuality` is `UNKNOWN` when the user is not receiving a stream. + * + * @param uid User ID. The network quality of the user with this @p uid is reported. If @p uid is 0, the local network quality is reported. + * @param txQuality Uplink transmission quality rating of the user in terms of the transmission bitrate, packet loss rate, average RTT (Round-Trip Time), and jitter of the uplink network. @p txQuality is a quality rating helping you understand how well the current uplink network conditions can support the selected VideoEncoderConfiguration. 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 may be inadequate for resolutions higher than 1280 * 720. See #QUALITY_TYPE. + * @param rxQuality Downlink network quality rating of the user in terms of the packet loss rate, average RTT, and jitter of the downlink network. See #QUALITY_TYPE. */ virtual void onNetworkQuality(uid_t uid, int txQuality, int rxQuality) { (void)uid; @@ -3666,17 +4653,18 @@ class IRtcEngineEventHandler { } /** Occurs when the remote audio state changes. - - This callback indicates the state change of the remote audio stream. - @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. - - @param uid ID of the remote user whose audio state changes. - @param state State of the remote audio. See #REMOTE_AUDIO_STATE. - @param reason The reason of the remote audio state change. - See #REMOTE_AUDIO_STATE_REASON. - @param elapsed Time elapsed (ms) from the local user calling the - \ref IRtcEngine::joinChannel "joinChannel" method until the SDK - triggers this callback. + * + * This callback indicates the state change of the remote audio stream. + * + * @note This callback can be inaccurate when the number of users (in the `COMMUNICATION` profile) + * or hosts (in the `LIVE_BROADCASTING` profile) in a channel exceeds 17. + * + * @param uid ID of the remote user whose audio state changes. + * @param state State of the remote audio. See #REMOTE_AUDIO_STATE. + * @param reason The reason of the remote audio state change. See #REMOTE_AUDIO_STATE_REASON. + * @param elapsed Time elapsed (ms) from the local user calling the + * \ref IRtcEngine::joinChannel "joinChannel" method until the SDK + * triggers this callback. */ virtual void onRemoteAudioStateChanged(uid_t uid, REMOTE_AUDIO_STATE state, REMOTE_AUDIO_STATE_REASON reason, int elapsed) { (void)uid; @@ -3790,7 +4778,7 @@ class IRtcEngineEventHandler { * - In the remote users' callback, totalVolume is the sum of the volume of all remote users (up to three) whose * instantaneous volumes are the highest. * - * If the user calls \ref agora::rtc::IRtcEngine::startAudioMixing "startAudioMixing", `totalVolume` is the sum of + * If the user calls \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing", `totalVolume` is the sum of * the voice volume and audio-mixing volume. */ virtual void onAudioVolumeIndication(const AudioVolumeInfo* speakers, unsigned int speakerNumber, int totalVolume) { @@ -3799,7 +4787,13 @@ class IRtcEngineEventHandler { (void)totalVolume; } - /** Occurs when the most active speaker is detected. + /** add for audio device test:report playback volume and recording volume + **/ + virtual void onAudioDeviceTestVolumeIndication(AudioDeviceTestVolumeType volumeType, int volume) { + (void)volumeType; + (void)volume; + } + /** Occurs when the most active remote speaker is detected. After a successful call of \ref IRtcEngine::enableAudioVolumeIndication(int, int, bool) "enableAudioVolumeIndication", the SDK continuously detects which remote user has the loudest volume. During the current period, the remote user, @@ -3809,7 +4803,7 @@ class IRtcEngineEventHandler { - If the most active speaker is always the same user, the SDK triggers this 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. - @param uid The user ID of the most active speaker. + @param uid The user ID of the most active remote speaker. */ virtual void onActiveSpeaker(uid_t uid) { (void)uid; } @@ -3849,14 +4843,6 @@ class IRtcEngineEventHandler { virtual void onFirstLocalVideoFramePublished(int elapsed) { (void)elapsed; } /** Occurs when the first remote video frame is received and decoded. - * - * @deprecated v2.9.0 - * - * This callback is deprecated and replaced by the - * \ref onRemoteVideoStateChanged() "onRemoteVideoStateChanged" callback - * with the following parameters: - * - #REMOTE_VIDEO_STATE_STARTING (1) - * - #REMOTE_VIDEO_STATE_DECODING (2) * * This callback is triggered in either of the following scenarios: * @@ -3881,7 +4867,7 @@ class IRtcEngineEventHandler { * \ref IRtcEngine::joinChannel "joinChannel" method until the SDK * triggers this callback. */ - virtual void onFirstRemoteVideoDecoded(uid_t uid, int width, int height, int elapsed) { + virtual void onFirstRemoteVideoDecoded(uid_t uid, int width, int height, int elapsed) AGORA_DEPRECATED_ATTRIBUTE { (void)uid; (void)width; (void)height; @@ -3889,7 +4875,7 @@ class IRtcEngineEventHandler { } /** Occurs when the first remote video frame is rendered. - The SDK triggers this callback when the first frame of the remote video is displayed in the user's video window. The application can retrieve the time elapsed from a user joining the channel until the first video frame is displayed. + The SDK triggers this callback when the first frame of the remote video is displayed in the user's video window. The application can get the time elapsed from a user joining the channel until the first video frame is displayed. @param uid User ID of the remote user sending the video stream. @param width Width (px) of the video frame. @@ -3903,46 +4889,38 @@ class IRtcEngineEventHandler { (void)elapsed; } - /** @deprecated This method is deprecated from v3.0.0, use the \ref agora::rtc::IRtcEngineEventHandler::onRemoteAudioStateChanged "onRemoteAudioStateChanged" callback instead. - - Occurs when a remote user's audio stream playback pauses/resumes. - - The SDK triggers this callback when the remote user stops or resumes sending the audio stream by calling the \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" 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. - - @param uid User ID of the remote user. - @param muted Whether the remote user's audio stream is muted/unmuted: - - true: Muted. - - false: Unmuted. + /** Occurs when a remote user's audio stream playback pauses/resumes. + * + * The SDK triggers this callback when the remote user stops or resumes sending the audio stream by calling the \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" method. + * + * @note This callback can be inaccurate when the number of users (in the `COMMUNICATION` profile) + * or hosts (in the `LIVE_BROADCASTING` profile) in a channel exceeds 17. + * + * @param uid User ID of the remote user. + * @param muted Whether the remote user's audio stream is muted/unmuted: + * - true: Muted. + * - false: Unmuted. */ virtual void onUserMuteAudio(uid_t uid, bool muted) { (void)uid; (void)muted; } - /** Occurs when a remote user's video stream playback pauses/resumes. - * - * You can also use the - * \ref onRemoteVideoStateChanged() "onRemoteVideoStateChanged" callback - * with the following parameters: - * - #REMOTE_VIDEO_STATE_STOPPED (0) and - * #REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED (5). - * - #REMOTE_VIDEO_STATE_DECODING (2) and - * #REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED (6). + /** + * Occurs when a remote user stops or resumes publishing the video stream. * - * The SDK triggers this callback when the remote user stops or resumes - * sending the video stream by calling the - * \ref agora::rtc::IRtcEngine::muteLocalVideoStream - * "muteLocalVideoStream" method. + * When a remote user calls \ref IRtcEngine::muteLocalVideoStream "muteLocalVideoStream" to + * stop or resume publishing the video stream, the SDK triggers this callback to report the + * state of the remote user's publishing stream to the local user. * - * @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. + * @note This callback can be inaccurate when the number of users + * (in the `COMMUNICATION` profile) or hosts (in the `LIVE_BROADCASTING` profile) in a + * channel exceeds 17. * - * @param uid User ID of the remote user. - * @param muted Whether the remote user's video stream playback is - * paused/resumed: - * - true: Paused. - * - false: Resumed. + * @param uid The user ID of the remote user. + * @param muted Whether the remote user stops publishing the video stream: + * - true: Stop publishing the video stream. + * - false: Publish the video stream. */ virtual void onUserMuteVideo(uid_t uid, bool muted) { (void)uid; @@ -3952,16 +4930,6 @@ class IRtcEngineEventHandler { /** Occurs when a specific remote user enables/disables the video * module. * - * @deprecated v2.9.0 - * - * This callback is deprecated and replaced by the - * \ref onRemoteVideoStateChanged() "onRemoteVideoStateChanged" callback - * with the following parameters: - * - #REMOTE_VIDEO_STATE_STOPPED (0) and - * #REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED (5). - * - #REMOTE_VIDEO_STATE_DECODING (2) and - * #REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED (6). - * * Once the video module is disabled, the remote user can only use a * voice call. The remote user cannot send or receive any video from * other users. @@ -3987,12 +4955,16 @@ class IRtcEngineEventHandler { } /** Occurs when the audio device state changes. - - This callback notifies the application that the system's audio device state is changed. For example, a headset is unplugged from the device. - - @param deviceId Pointer to the device ID. - @param deviceType Device type: #MEDIA_DEVICE_TYPE. - @param deviceState Device state: #MEDIA_DEVICE_STATE_TYPE. + * + * This callback notifies the application that the system's audio device state is changed. For example, a headset is unplugged from the device. + * + * @param deviceId Pointer to the device ID. + * @param deviceType Device type: #MEDIA_DEVICE_TYPE. + * @param deviceState The state of the device: + * - On macOS: + * - 0: The device is ready for use. + * - 8: The device is not connected. + * - On Windows: #MEDIA_DEVICE_STATE_TYPE. */ virtual void onAudioDeviceStateChanged(const char* deviceId, int deviceType, int deviceState) { (void)deviceId; @@ -4096,33 +5068,46 @@ class IRtcEngineEventHandler { **DEPRECATED** use onAudioMixingStateChanged instead. - You can start an audio mixing file playback by calling the \ref IRtcEngine::startAudioMixing "startAudioMixing" method. The SDK triggers this callback when the audio mixing file playback finishes. + You can start an audio mixing file playback by calling the \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" method. The SDK triggers this callback when the audio mixing file playback finishes. If the *startAudioMixing* method call fails, an error code returns in the \ref IRtcEngineEventHandler::onError "onError" callback. */ virtual void onAudioMixingFinished() {} - /** Occurs when the state of the local user's audio mixing file changes. - - When you call the \ref IRtcEngine::startAudioMixing "startAudioMixing" method and the state of audio mixing file changes, the SDK triggers this callback. - - When the audio mixing file plays, pauses playing, or stops playing, this callback returns 710, 711, or 713 in @p state, and corresponding reason in @p reason. - - When exceptions occur during playback, this callback returns 714 in @p state and an error reason in @p reason. - - 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 AUDIO_MIXING_REASON_CAN_NOT_OPEN = 701. - - @param state The state code. See #AUDIO_MIXING_STATE_TYPE. - @param reason The reason code. See #AUDIO_MIXING_REASON_TYPE. + /** Occurs when the state of the local user's music file changes. + * + * @since v3.4.0 + * + * When the playback state of the local user's music file changes, the SDK triggers this callback and + * reports the current playback state and the reason for the change. + * + * @param state The current music file playback state. See #AUDIO_MIXING_STATE_TYPE. + * @param reason The reason for the change of the music file playback state. See #AUDIO_MIXING_REASON_TYPE. */ virtual void onAudioMixingStateChanged(AUDIO_MIXING_STATE_TYPE state, AUDIO_MIXING_REASON_TYPE reason) {} /** Occurs when a remote user starts audio mixing. - When a remote user calls \ref IRtcEngine::startAudioMixing "startAudioMixing" to play the background music, the SDK reports this callback. + When a remote user calls \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" to play the background music, the SDK reports this callback. */ virtual void onRemoteAudioMixingBegin() {} /** Occurs when a remote user finishes audio mixing. */ virtual void onRemoteAudioMixingEnd() {} + /** + * Reports the information of an audio file. + * + * @since v3.5.1 + * + * After successfully calling \ref IRtcEngine::getAudioFileInfo "getAudioFileInfo", the SDK triggers this + * callback to report the information of the audio file, such as the file path and duration. + * + * @param info The information of an audio file. See AudioFileInfo. + * @param error The information acquisition state. See #AUDIO_FILE_INFO_ERROR. + */ + virtual void onRequestAudioFileInfo(const AudioFileInfo& info, AUDIO_FILE_INFO_ERROR error) {} + /** Occurs when the local audio effect playback finishes. The SDK triggers this callback when the local audio effect file playback finishes. @@ -4130,9 +5115,11 @@ class IRtcEngineEventHandler { @param soundId ID of the local audio effect. Each local audio effect has a unique ID. */ virtual void onAudioEffectFinished(int soundId) {} + /// @cond /** Occurs when AirPlay is connected. */ virtual void onAirPlayConnected() {} + /// @endcond /** Occurs when the SDK decodes the first remote audio frame for playback. @@ -4153,18 +5140,22 @@ class IRtcEngineEventHandler { @param uid User ID of the remote user sending the audio stream. @param elapsed Time elapsed (ms) from the local user calling the \ref IRtcEngine::joinChannel "joinChannel" method until the SDK triggers this callback. */ - virtual void onFirstRemoteAudioDecoded(uid_t uid, int elapsed) { + virtual void onFirstRemoteAudioDecoded(uid_t uid, int elapsed) AGORA_DEPRECATED_ATTRIBUTE { (void)uid; (void)elapsed; } /** Occurs when the video device state changes. - - @note On a Windows device with an external camera for video capturing, the video disables once the external camera is unplugged. - - @param deviceId Pointer to the device ID of the video device that changes state. - @param deviceType Device type: #MEDIA_DEVICE_TYPE. - @param deviceState Device state: #MEDIA_DEVICE_STATE_TYPE. + * + * @note On a Windows device with an external camera for video capturing, the video disables once the external camera is unplugged. + * + * @param deviceId Pointer to the device ID of the video device that changes state. + * @param deviceType Device type: #MEDIA_DEVICE_TYPE. + * @param deviceState The state of the device: + * - On macOS: + * - 0: The device is ready for use. + * - 8: The device is not connected. + * - On Windows: #MEDIA_DEVICE_STATE_TYPE. */ virtual void onVideoDeviceStateChanged(const char* deviceId, int deviceType, int deviceState) { (void)deviceId; @@ -4176,12 +5167,12 @@ class IRtcEngineEventHandler { * * 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(LOCAL_VIDEO_STREAM_STATE_FAILED，LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE)` callback in the following situations: + * The SDK triggers the `onLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_FAILED, LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE)` callback in the following situations: * - The application exits to the background, and the system recycles the camera. * - The camera starts normally, but the captured video is not output for four seconds. * * When the camera outputs the captured video frames, if all the video frames are the same for 15 consecutive frames, the SDK triggers the - * `onLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_CAPTURING，LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE)` callback. Note that the + * `onLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_CAPTURING, LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE)` callback. 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. * @@ -4209,15 +5200,16 @@ class IRtcEngineEventHandler { (void)rotation; } /** Occurs when the remote video state changes. - @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. - - @param uid ID of the remote user whose video state changes. - @param state State of the remote video. See #REMOTE_VIDEO_STATE. - @param reason The reason of the remote video state change. See - #REMOTE_VIDEO_STATE_REASON. - @param elapsed Time elapsed (ms) from the local user calling the - \ref agora::rtc::IRtcEngine::joinChannel "joinChannel" method until the - SDK triggers this callback. + * + * @note This callback can be inaccurate when the number of users (in the `COMMUNICATION` profile) + * or hosts (in the `LIVE_BROADCASTING` profile) in a channel exceeds 17. + * + * @param uid ID of the remote user whose video state changes. + * @param state State of the remote video. See #REMOTE_VIDEO_STATE. + * @param reason The reason of the remote video state change. See #REMOTE_VIDEO_STATE_REASON. + * @param elapsed Time elapsed (ms) from the local user calling the + * \ref agora::rtc::IRtcEngine::joinChannel "joinChannel" method until the + * SDK triggers this callback. */ virtual void onRemoteVideoStateChanged(uid_t uid, REMOTE_VIDEO_STATE state, REMOTE_VIDEO_STATE_REASON reason, int elapsed) { (void)uid; @@ -4229,16 +5221,6 @@ class IRtcEngineEventHandler { /** Occurs when a specified remote user enables/disables the local video * capturing function. * - * @deprecated v2.9.0 - * - * This callback is deprecated and replaced by the - * \ref onRemoteVideoStateChanged() "onRemoteVideoStateChanged" callback - * with the following parameters: - * - #REMOTE_VIDEO_STATE_STOPPED (0) and - * #REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED (5). - * - #REMOTE_VIDEO_STATE_DECODING (2) and - * #REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED (6). - * * This callback is only applicable to the scenario when the user only * wants to watch the remote video without sending any video stream to the * other user. @@ -4298,27 +5280,82 @@ The SDK triggers this callback when the local user fails to receive the stream m virtual void onMediaEngineLoadSuccess() {} /** Occurs when the media engine call starts.*/ virtual void onMediaEngineStartCallSuccess() {} - /// @cond - /** Reports whether the super-resolution algorithm is enabled. + + /** Reports whether the super resolution feature is successfully enabled. (beta feature) * - * @since v3.2.0 + * @since v3.5.1 * * After calling \ref IRtcEngine::enableRemoteSuperResolution "enableRemoteSuperResolution", the SDK triggers this - * callback to report whether the super-resolution algorithm is successfully enabled. If not successfully enabled, - * you can use reason for troubleshooting. + * callback to report whether super resolution is successfully enabled. If it is not successfully enabled, + * use `reason` for troubleshooting. + * + * @param uid The user ID of the remote user. + * @param enabled Whether super resolution is successfully enabled: + * - true: Super resolution is successfully enabled. + * - false: Super resolution is not successfully enabled. + * @param reason The reason why super resolution is not successfully enabled or the message + * that confirms success. See #SUPER_RESOLUTION_STATE_REASON. * - * @param uid The ID of the remote user. - * @param enabled Whether the super-resolution algorithm is successfully enabled: - * - true: The super-resolution algorithm is successfully enabled. - * - false: The super-resolution algorithm is not successfully enabled. - * @param reason The reason why the super-resolution algorithm is not successfully enabled. See #SUPER_RESOLUTION_STATE_REASON. */ virtual void onUserSuperResolutionEnabled(uid_t uid, bool enabled, SUPER_RESOLUTION_STATE_REASON reason) { (void)uid; (void)enabled; (void)reason; } + + /** + * Reports whether the virtual background is successfully enabled. (beta feature) + * + * @since v3.4.5 + * + * After you call \ref IRtcEngine::enableVirtualBackground "enableVirtualBackground", the SDK triggers this callback + * to report whether the virtual background is successfully enabled. + * + * @note If the background image customized in the virtual background is in PNG or JPG format, the triggering of this + * callback is delayed until the image is read. + * + * @param enabled Whether the virtual background is successfully enabled: + * - true: The virtual background is successfully enabled. + * - false: The virtual background is not successfully enabled. + * @param reason The reason why the virtual background is not successfully enabled or the message that confirms + * success. See #VIRTUAL_BACKGROUND_SOURCE_STATE_REASON. + */ + virtual void onVirtualBackgroundSourceEnabled(bool enabled, VIRTUAL_BACKGROUND_SOURCE_STATE_REASON reason) { + (void)enabled; + (void)reason; + } + /// @cond + /** Reports result of Content Inspect*/ + virtual void onContentInspectResult(CONTENT_INSPECT_RESULT result) { (void)result; } /// @endcond + /** + * Reports the result of taking a video snapshot. + * + * @since v3.5.2 + * + * After a successful \ref IRtcEngine::takeSnapshot "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. + * + * @param channel The channel name. + * @param uid The user ID of the user. A `uid` of 0 indicates the local user. + * @param filePath The local path of the snapshot. + * @param width The width (px) of the snapshot. + * @param height The height (px) of the snapshot. + * @param 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 \ref IRtcEngine::takeSnapshot "takeSnapshot" method call succeeds. + */ + 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; + } /** Occurs when the state of the media stream relay changes. * @@ -4342,7 +5379,7 @@ The SDK triggers this callback when the local user fails to receive the stream m @param elapsed Time elapsed (ms) from the local user calling \ref IRtcEngine::joinChannel "joinChannel" until the SDK triggers this callback. */ - virtual void onFirstLocalAudioFrame(int elapsed) { (void)elapsed; } + virtual void onFirstLocalAudioFrame(int elapsed) AGORA_DEPRECATED_ATTRIBUTE { (void)elapsed; } /** Occurs when the first audio frame is published. * @@ -4367,23 +5404,24 @@ The SDK triggers this callback when the local user fails to receive the stream m @param uid User ID of the remote user. @param elapsed Time elapsed (ms) from the remote user calling \ref IRtcEngine::joinChannel "joinChannel" until the SDK triggers this callback. */ - virtual void onFirstRemoteAudioFrame(uid_t uid, int elapsed) { + virtual void onFirstRemoteAudioFrame(uid_t uid, int elapsed) AGORA_DEPRECATED_ATTRIBUTE { (void)uid; (void)elapsed; } /** - Occurs when the state of the RTMP or RTMPS streaming changes. - - The SDK triggers this callback to report the result of the local user calling the \ref agora::rtc::IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" or \ref agora::rtc::IRtcEngine::removePublishStreamUrl "removePublishStreamUrl" method. - - 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 *errCode* parameter. - - @param url The CDN streaming URL. - @param state The RTMP or RTMPS streaming state. See: #RTMP_STREAM_PUBLISH_STATE. - @param errCode The detailed error information for streaming. See: #RTMP_STREAM_PUBLISH_ERROR. + * Occurs when the state of the RTMP or RTMPS streaming changes. + * + * When the CDN live streaming state changes, the SDK triggers this callback to report the current state and the reason + * why the state has changed. + * + * When exceptions occur, you can troubleshoot issues by referring to the detailed error descriptions in the *errCode* parameter. + * + * @param url The CDN streaming URL. + * @param state The RTMP or RTMPS streaming state. See: #RTMP_STREAM_PUBLISH_STATE. + * @param errCode The detailed error information for streaming. See: #RTMP_STREAM_PUBLISH_ERROR_TYPE. */ - virtual void onRtmpStreamingStateChanged(const char* url, RTMP_STREAM_PUBLISH_STATE state, RTMP_STREAM_PUBLISH_ERROR errCode) { + virtual void onRtmpStreamingStateChanged(const char* url, RTMP_STREAM_PUBLISH_STATE state, RTMP_STREAM_PUBLISH_ERROR_TYPE errCode) { (void)url; (void)state; (void)errCode; @@ -4412,7 +5450,6 @@ The SDK triggers this callback when the local user fails to receive the stream m - #ERR_INVALID_ARGUMENT (-2): Invalid argument used. If, for example, you did not call \ref agora::rtc::IRtcEngine::setLiveTranscoding "setLiveTranscoding" to configure LiveTranscoding before calling \ref agora::rtc::IRtcEngine::addPublishStreamUrl "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_RESOURCE_LIMITED (-22): The backend system does not have enough resources for the CDN live streaming. - #ERR_ENCRYPTED_STREAM_NOT_ALLOWED_PUBLISH (130): You cannot publish an encrypted stream. - #ERR_PUBLISH_STREAM_CDN_ERROR (151) - #ERR_PUBLISH_STREAM_NUM_REACH_LIMIT (152) @@ -4420,7 +5457,7 @@ The SDK triggers this callback when the local user fails to receive the stream m - #ERR_PUBLISH_STREAM_INTERNAL_SERVER_ERROR (154) - #ERR_PUBLISH_STREAM_FORMAT_NOT_SUPPORTED (156) */ - virtual void onStreamPublished(const char* url, int error) { + virtual void onStreamPublished(const char* url, int error) AGORA_DEPRECATED_ATTRIBUTE { (void)url; (void)error; } @@ -4432,7 +5469,7 @@ The SDK triggers this callback when the local user fails to receive the stream m @param url The CDN streaming URL. */ - virtual void onStreamUnpublished(const char* url) { (void)url; } + virtual void onStreamUnpublished(const char* url) AGORA_DEPRECATED_ATTRIBUTE { (void)url; } /** Occurs when the publisher's transcoding is updated. * * When the `LiveTranscoding` class in the \ref agora::rtc::IRtcEngine::setLiveTranscoding "setLiveTranscoding" method updates, the SDK triggers the `onTranscodingUpdated` callback to report the update information to the local host. @@ -4456,7 +5493,10 @@ The SDK triggers this callback when the local user fails to receive the stream m } /** Occurs when the local audio route changes. - @param routing The current audio routing. See: #AUDIO_ROUTE_TYPE. + * + * @note This callback applies to Android, iOS and macOS only. + * + * @param routing The current audio routing. See: #AUDIO_ROUTE_TYPE. */ virtual void onAudioRouteChanged(AUDIO_ROUTE_TYPE routing) { (void)routing; } @@ -4481,8 +5521,8 @@ The SDK triggers this callback when the local user fails to receive the stream m * "setRemoteSubscribeFallbackOption" and set * @p option as #STREAM_FALLBACK_OPTION_AUDIO_ONLY, the SDK triggers this * callback when the remote media stream falls back to audio-only mode due - * to poor uplink conditions, or when the remote media stream switches - * back to the video after the uplink network condition improves. + * to poor downlink conditions, or when the remote media stream switches + * back to the video after the downlink network condition improves. * * @note Once the remote media stream switches to the low stream due to * poor network conditions, you can monitor the stream switch between a @@ -4519,7 +5559,7 @@ The SDK triggers this callback when the local user fails to receive the stream m * @param rxKBitRate Received bitrate (Kbps) of the audio packet sent * from the remote user. */ - virtual void onRemoteAudioTransportStats(uid_t uid, unsigned short delay, unsigned short lost, unsigned short rxKBitRate) { + virtual void onRemoteAudioTransportStats(uid_t uid, unsigned short delay, unsigned short lost, unsigned short rxKBitRate) AGORA_DEPRECATED_ATTRIBUTE { (void)uid; (void)delay; (void)lost; @@ -4544,7 +5584,7 @@ The SDK triggers this callback when the local user fails to receive the stream m * @param rxKBitRate Received bitrate (Kbps) of the video packet sent * from the remote user. */ - virtual void onRemoteVideoTransportStats(uid_t uid, unsigned short delay, unsigned short lost, unsigned short rxKBitRate) { + virtual void onRemoteVideoTransportStats(uid_t uid, unsigned short delay, unsigned short lost, unsigned short rxKBitRate) AGORA_DEPRECATED_ATTRIBUTE { (void)uid; (void)delay; (void)lost; @@ -4569,7 +5609,7 @@ The SDK triggers this callback when the local user fails to receive the stream m * - true: Enabled. * - false: Disabled. */ - virtual void onMicrophoneEnabled(bool enabled) { (void)enabled; } + virtual void onMicrophoneEnabled(bool enabled) AGORA_DEPRECATED_ATTRIBUTE { (void)enabled; } /** Occurs when the connection state between the SDK and the server changes. @param state See #CONNECTION_STATE_TYPE. @@ -4580,6 +5620,27 @@ The SDK triggers this callback when the local user fails to receive the stream m (void)reason; } + /** Occurs when the WIFI message need be sent to the user. + + @param reason The reason of notifying the user of a message. + @param action Suggest an action for the user. + @param wlAccMsg The message content of notifying the user. + */ + virtual void onWlAccMessage(WLACC_MESSAGE_REASON reason, WLACC_SUGGEST_ACTION action, const char* wlAccMsg) { + (void)reason; + (void)action; + (void)wlAccMsg; + } + /** Occurs when SDK statistics wifi acceleration optimization effect. + + @param currentStats Instantaneous value of optimization effect. + @param averageStats Average value of cumulative optimization effect. + */ + virtual void onWlAccStats(WlAccStats currentStats, WlAccStats averageStats) { + (void)currentStats; + (void)averageStats; + } + /** Occurs when the local network type changes. When the network connection is interrupted, this callback indicates whether the interruption is caused by a network type change or poor network conditions. @@ -4601,13 +5662,14 @@ The SDK triggers this callback when the local user fails to receive the stream m 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 (`userInfo`), and triggers this callback on the local client. - @param uid The ID of the remote user. - @param info The `UserInfo` object that contains the user ID and user account of the remote user. - */ + @param uid The ID of the remote user. + @param info The `UserInfo` object that contains the user ID and user account of the remote user. + */ virtual void onUserInfoUpdated(uid_t uid, const UserInfo& info) { (void)uid; (void)info; } + /// @cond /** Reports the result of uploading the SDK log files. * * @since v3.3.0 @@ -4627,25 +5689,35 @@ The SDK triggers this callback when the local user fails to receive the stream m (void)success; (void)reason; } + +#ifdef _WIN32 + /** Occurs when screencapture fail to filter window + * + * + * @param ScreenCaptureInfo + */ + virtual void onScreenCaptureInfoUpdated(ScreenCaptureInfo& info) { (void)info; } +#endif + /// @endcond }; /** * Video device collection methods. - The IVideoDeviceCollection interface class retrieves the video device information. + The IVideoDeviceCollection interface class gets the video device information. */ class IVideoDeviceCollection { protected: virtual ~IVideoDeviceCollection() {} public: - /** Retrieves the total number of the indexed video devices in the system. + /** Gets the total number of the indexed video devices in the system. @return Total number of the indexed video devices: */ virtual int getCount() = 0; - /** Retrieves a specified piece of information about an indexed video device. + /** Gets a specified piece of information about an indexed video device. @param index The specified index of the video device that must be less than the return value of \ref IVideoDeviceCollection::getCount "getCount". @param deviceName Pointer to the video device name. @@ -4670,9 +5742,10 @@ class IVideoDeviceCollection { virtual void release() = 0; }; +#if !defined(__ANDROID__) && !(defined(__APPLE__) && TARGET_OS_IPHONE) /** Video device management methods. - The IVideoDeviceManager interface class tests the video device interfaces. Instantiate an AVideoDeviceManager class to retrieve an IVideoDeviceManager interface. + The IVideoDeviceManager interface class tests the video device interfaces. Instantiate an AVideoDeviceManager class to get an IVideoDeviceManager interface. */ class IVideoDeviceManager { protected: @@ -4713,7 +5786,7 @@ class IVideoDeviceManager { /** Sets a device with the device ID. - @param deviceId Pointer to the video-capture device ID. Call the \ref IVideoDeviceManager::enumerateVideoDevices "enumerateVideoDevices" method to retrieve it. + @param deviceId Pointer to the video-capture device ID. Call the \ref IVideoDeviceManager::enumerateVideoDevices "enumerateVideoDevices" method to get it. @note Plugging or unplugging the device does not change the device ID. @@ -4723,7 +5796,7 @@ class IVideoDeviceManager { */ virtual int setDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0; - /** Retrieves the video-capture device that is in use. + /** Gets the video-capture device that is in use. @param deviceId Pointer to the video-capture device ID. @return @@ -4739,14 +5812,14 @@ class IVideoDeviceManager { /** Audio device collection methods. -The IAudioDeviceCollection interface class retrieves device-related information. +The IAudioDeviceCollection interface class gets device-related information. */ class IAudioDeviceCollection { protected: virtual ~IAudioDeviceCollection() {} public: - /** Retrieves the total number of audio playback or audio capturing devices. + /** Gets the total number of audio playback or audio capturing devices. @note You must first call the \ref IAudioDeviceManager::enumeratePlaybackDevices "enumeratePlaybackDevices" or \ref IAudioDeviceManager::enumerateRecordingDevices "enumerateRecordingDevices" method before calling this method to return the number of audio playback or audio capturing devices. @@ -4754,7 +5827,7 @@ class IAudioDeviceCollection { */ virtual int getCount() = 0; - /** Retrieves a specified piece of information about an indexed audio device. + /** Gets a specified piece of information about an indexed audio device. @param index The specified index that must be less than the return value of \ref IAudioDeviceCollection::getCount "getCount". @param deviceName Pointer to the audio device name. @@ -4774,6 +5847,20 @@ class IAudioDeviceCollection { */ virtual int setDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0; + /** + * Gets the default audio device of the system. + * + * @since v3.6.0 + * + * @param deviceName The name of the system default audio device. + * @param deviceId The device ID of the the system default audio device. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int getDefaultDevice(char deviceName[MAX_DEVICE_ID_LENGTH], char deviceId[MAX_DEVICE_ID_LENGTH]) = 0; + /** Sets the volume of the application. @param volume Application volume. The value ranges between 0 (lowest volume) and 255 (highest volume). @@ -4783,7 +5870,7 @@ class IAudioDeviceCollection { */ virtual int setApplicationVolume(int volume) = 0; - /** Retrieves the volume of the application. + /** Gets the volume of the application. @param volume Pointer to the application volume. The volume value ranges between 0 (lowest volume) and 255 (highest volume). @@ -4822,7 +5909,7 @@ class IAudioDeviceCollection { }; /** Audio device management methods. - The IAudioDeviceManager interface class allows for audio device interface testing. Instantiate an AAudioDeviceManager class to retrieve the IAudioDeviceManager interface. + The IAudioDeviceManager interface class allows for audio device interface testing. Instantiate an AAudioDeviceManager class to get the IAudioDeviceManager interface. */ class IAudioDeviceManager { protected: @@ -4877,6 +5964,36 @@ class IAudioDeviceManager { */ virtual int setRecordingDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0; + /** + * Sets the audio playback device used by the SDK to follow the system default audio playback device. + * + * @since v3.6.0 + * + * @param enable Whether to follow the system default audio playback device: + * - true: Follow. The SDK immediately switches the audio playback device when the system default audio playback device changes. + * - false: Do not follow. The SDK switches the audio playback device to the system default audio playback device only when the currently used audio playback device is disconnected. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int followSystemPlaybackDevice(bool enable) = 0; + + /** + * Sets the audio recording device used by the SDK to follow the system default audio recording device. + * + * @since v3.6.0 + * + * @param enable Whether to follow the system default audio recording device: + * - true: Follow. The SDK immediately switches the audio recording device when the system default audio recording device changes. + * - false: Do not follow. The SDK switches the audio recording device to the system default audio recording device only when the currently used audio recording device is disconnected. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int followSystemRecordingDevice(bool enable) = 0; + /** Starts the audio playback device test. * * This method tests if the audio playback device works properly. Once a user starts the test, the SDK plays an @@ -4919,7 +6036,7 @@ class IAudioDeviceManager { */ virtual int setPlaybackDeviceVolume(int volume) = 0; - /** Retrieves the volume of the audio playback device. + /** Gets the volume of the audio playback device. @param volume Pointer to the audio playback device volume. The volume value ranges between 0 (lowest volume) and 255 (highest volume). @return @@ -4939,7 +6056,7 @@ class IAudioDeviceManager { */ virtual int setRecordingDeviceVolume(int volume) = 0; - /** Retrieves the volume of the microphone. + /** Gets the volume of the microphone. @param volume Pointer to the microphone volume. The volume value ranges between 0 (lowest volume) and 255 (highest volume). @return @@ -4959,7 +6076,7 @@ class IAudioDeviceManager { - < 0: Failure. */ virtual int setPlaybackDeviceMute(bool mute) = 0; - /** Retrieves the mute status of the audio playback device. + /** Gets the mute status of the audio playback device. @param mute Pointer to whether the audio playback device is muted/unmuted. - true: Muted. @@ -4982,7 +6099,7 @@ class IAudioDeviceManager { */ virtual int setRecordingDeviceMute(bool mute) = 0; - /** Retrieves the microphone's mute status. + /** Gets the microphone's mute status. @param mute Pointer to whether the microphone is muted/unmuted. - true: Muted. @@ -5026,7 +6143,7 @@ class IAudioDeviceManager { */ virtual int stopRecordingDeviceTest() = 0; - /** Retrieves the audio playback device associated with the device ID. + /** Gets the audio playback device associated with the device ID. @param deviceId Pointer to the ID of the audio playback device. @return @@ -5035,7 +6152,7 @@ class IAudioDeviceManager { */ virtual int getPlaybackDevice(char deviceId[MAX_DEVICE_ID_LENGTH]) = 0; - /** Retrieves the audio playback device information associated with the device ID and device name. + /** Gets the audio playback device information associated with the device ID and device name. @param deviceId Pointer to the device ID of the audio playback device. @param deviceName Pointer to the device name of the audio playback device. @@ -5045,7 +6162,7 @@ class IAudioDeviceManager { */ virtual int getPlaybackDeviceInfo(char deviceId[MAX_DEVICE_ID_LENGTH], char deviceName[MAX_DEVICE_ID_LENGTH]) = 0; - /** Retrieves the audio capturing device associated with the device ID. + /** Gets the audio capturing device associated with the device ID. @param deviceId Pointer to the device ID of the audio capturing device. @return @@ -5054,7 +6171,7 @@ class IAudioDeviceManager { */ virtual int getRecordingDevice(char deviceId[MAX_DEVICE_ID_LENGTH]) = 0; - /** Retrieves the audio capturing device information associated with the device ID and device name. + /** Gets the audio capturing device information associated with the device ID and device name. @param deviceId Pointer to the device ID of the audio capturing device. @param deviceName Pointer to the device name of the audio capturing device. @@ -5103,6 +6220,7 @@ class IAudioDeviceManager { */ virtual void release() = 0; }; +#endif /** The configuration of the log files. * @@ -5156,8 +6274,9 @@ struct RtcEngineContext { /** * The region for connection. This advanced feature applies to scenarios that have regional restrictions. * - * For the regions that Agora supports, see #AREA_CODE. After specifying the region, the SDK connects to the Agora servers within that region. + * For the regions that Agora supports, see #AREA_CODE. The area codes support bitwise operation. * + * After specifying the region, the SDK connects to the Agora servers within that region. */ unsigned int areaCode; /** The configuration of the log files that the SDK outputs. See LogConfig. @@ -5242,10 +6361,11 @@ class IMetadataObserver { virtual void onMetadataReceived(const Metadata& metadata) = 0; }; -/** Encryption mode. +/** Encryption mode. Agora recommends using either the `AES_128_GCM2` or `AES_256_GCM2` + * encryption mode, both of which support adding a salt and are more secure. */ enum ENCRYPTION_MODE { - /** 1: (Default) 128-bit AES encryption, XTS mode. + /** 1: 128-bit AES encryption, XTS mode. */ AES_128_XTS = 1, /** 2: 128-bit AES encryption, ECB mode. @@ -5254,9 +6374,11 @@ enum ENCRYPTION_MODE { /** 3: 256-bit AES encryption, XTS mode. */ AES_256_XTS = 3, + /// @cond /** 4: 128-bit SM4 encryption, ECB mode. */ SM4_128_ECB = 4, + /// @endcond /** 5: 128-bit AES encryption, GCM mode. * * @since v3.3.1 @@ -5267,6 +6389,18 @@ enum ENCRYPTION_MODE { * @since v3.3.1 */ AES_256_GCM = 6, + /** 7: (Default) 128-bit AES encryption, GCM mode. Compared to `AES_128_GCM` encryption mode, + * `AES_128_GCM2` encryption mode is more secure and requires you to set the salt (`encryptionKdfSalt`). + * + * @since v3.4.5 + */ + AES_128_GCM2 = 7, + /** 8: 256-bit AES encryption, GCM mode. Compared to `AES_256_GCM` encryption mode, + * `AES_256_GCM2` encryption mode is more secure and requires you to set the salt (`encryptionKdfSalt`). + * + * @since v3.4.5 + */ + AES_256_GCM2 = 8, /** Enumerator boundary. */ MODE_END, @@ -5275,19 +6409,30 @@ enum ENCRYPTION_MODE { /** Configurations of built-in encryption schemas. */ struct EncryptionConfig { /** - * Encryption mode. The default encryption mode is `AES_128_XTS`. See #ENCRYPTION_MODE. + * Encryption mode. The default encryption mode is `AES_128_GCM2`. See #ENCRYPTION_MODE. */ ENCRYPTION_MODE encryptionMode; /** - * Encryption key in string type. + * Encryption key in string type with unlimited length. Agora recommends using a 32-byte key. * * @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 #ERR_INVALID_ARGUMENT (-2). */ const char* encryptionKey; + /** + * The salt with the length of 32 bytes. Agora recommends using OpenSSL to generate the salt on your server. + * For details, see *Media Stream Encryption*. + * + * @note This parameter is only valid when you set the encryption mode as `AES_128_GCM2` or `AES_256_GCM2`. + * In this case, ensure that this parameter is not `0`. + * + * @since v3.4.5 + */ + uint8_t encryptionKdfSalt[32]; EncryptionConfig() { - encryptionMode = AES_128_XTS; + encryptionMode = AES_128_GCM2; encryptionKey = nullptr; + memset(encryptionKdfSalt, 0, sizeof(encryptionKdfSalt)); } /// @cond @@ -5305,10 +6450,14 @@ struct EncryptionConfig { 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-xts"; + return "aes-128-gcm-2"; } - return "aes-128-xts"; + return "aes-128-gcm-2"; } /// @endcond }; @@ -5332,11 +6481,143 @@ struct ChannelMediaOptions { you can call the `muteAllRemoteVideoStreams` method to set whether to subscribe to video streams in the channel. */ bool autoSubscribeVideo; - ChannelMediaOptions() : autoSubscribeAudio(true), autoSubscribeVideo(true) {} + /** Determines whether to publish the local audio stream when the user joins a channel: + * - true: (Default) Publish. + * - false: Do not publish. + * + * This member serves a similar function to the `muteLocalAudioStream` method. After the user joins + * the channel, you can call the `muteLocalAudioStream` method to set whether to publish the + * local audio stream in the channel. + * + * @since v3.4.5 + */ + bool publishLocalAudio; + /** Determines whether to publish the local video stream when the user joins a channel: + * - true: (Default) Publish. + * - false: Do not publish. + * + * This member serves a similar function to the `muteLocalVideoStream` method. After the user joins + * the channel, you can call the `muteLocalVideoStream` method to set whether to publish the + * local video stream in the channel. + */ + bool publishLocalVideo; + ChannelMediaOptions() : autoSubscribeAudio(true), autoSubscribeVideo(true), publishLocalAudio(true), publishLocalVideo(true) {} }; - -/** IRtcEngine is the base interface class of the Agora SDK that provides the main Agora SDK methods invoked by your application. - +/** + * @since v3.5.0 + * + * The IVideoSink class, which can set up a custom video renderer. + * + * During a real-time audio and video interaction, the Agora SDK enables the default renderer to render local and + * remote video. The IVideoSink class can customize the video renderer. You can implement this interface first, and + * then customize the video renderer that you want by calling + * \ref IRtcEngine::setLocalVideoRenderer "setLocalVideoRenderer" or + * \ref IRtcEngine::setRemoteVideoRenderer "setRemoteVideoRenderer". + */ +class IVideoSink { + public: + /** + * Notification for initializing the custom video renderer. + * + * @since v3.5.0 + * + * The SDK triggers this callback to remind you to initialize the custom video renderer. + * After receiving this callback, you can do some preparation, and then use the return value to tell the SDK + * whether the custom video renderer is prepared. The SDK takes the corresponding behavior based on the return value. + * + * @return + * - true: The custom video renderer is initialized. The SDK is ready to send the video data to be rendered. + * - false: The custom video renderer is not ready or fails to initialize. The SDK reports the error. + */ + virtual bool onInitialize() = 0; + /** + * Notification for starting the custom video source. + * + * @since v3.5.0 + * + * The SDK triggers this callback to remind you to start the custom video source for capturing video. After receiving + * this callback, you can do some preparation, and then use the return value to tell the SDK whether the custom video + * renderer is started. The SDK takes the corresponding behavior based on the return value. + * + * @return + * - true: The custom video renderer is started. The SDK is ready to send the video data to be rendered to the custom video renderer for rendering. + * - false: The custom video renderer is not ready or fails to initialize. The SDK stops and reports the error. + */ + virtual bool onStart() = 0; + /** + * Notification for stopping rendering the video. + * + * @since v3.5.0 + * + * The SDK triggers this callback to remind you to stop rendering the video. This callback informs you that the SDK + * is about to stop sending video data to the custom video renderer. + */ + virtual void onStop() = 0; + /** + * Notification for disabling the custom video renderer. + * + * @since v3.5.0 + * + * The SDK triggers this callback to remind you to disable the custom video renderer. + */ + virtual void onDispose() = 0; + /** + * Gets the video frame type. + * + * @since v3.5.0 + * + * Before you initialize the custom video renderer, the SDK triggers this callback to query the data type of the + * video frame that you want to process. You must specify the data type of the video frame in the return value of + * this callback and then pass it to the SDK. + * + * @return \ref agora::media::ExternalVideoFrame::VIDEO_BUFFER_TYPE "VIDEO_BUFFER_TYPE" + */ + virtual agora::media::ExternalVideoFrame::VIDEO_BUFFER_TYPE getBufferType() = 0; + /** + * Gets the video frame pixel format. + * + * @since v3.5.0 + * + * Before you initialize the custom video renderer, the SDK triggers this callback to query the pixel format of the + * video frame that you want to process. You must specify a pixel format for the video frame in the return value of + * this callback and then pass it to the SDK. + * + * @return \ref agora::media::ExternalVideoFrame::VIDEO_PIXEL_FORMAT "VIDEO_PIXEL_FORMAT" + */ + virtual agora::media::ExternalVideoFrame::VIDEO_PIXEL_FORMAT getPixelFormat() = 0; +#if (defined(__APPLE__) && TARGET_OS_IOS) + /** + * Notification for rendering the video in the pixel data type. + * + * @since v3.5.0 + * + * The SDK triggers this callback after capturing video in the pixel data type to alter the custom video renderer + * to process the video data. + * + * @note This method applies to iOS only. + * + * @param pixelBuffer The video data in the pixel data type. + * @param rotation The clockwise rotation angle of the video. + */ + virtual void onRenderPixelBuffer(CVPixelBufferRef pixelBuffer, int rotation) = 0; +#endif + /** + * Notification for rendering the video in the raw data type. + * + * @since v3.5.0 + * + * The SDK triggers this callback after capturing video in the raw data type to alter the custom video renderer to + * process the video data. + * + * @param rawData The video data in the raw data type. + * @param width The width (px) of the video. + * @param height The height (px) of the video. + * @param rotation The clockwise rotation angle of the video. + */ + virtual void onRenderRawData(uint8_t* rawData, int width, int height, int rotation) = 0; +}; +/** IRtcEngine is the base interface class of the Agora SDK that provides the main Agora SDK methods +invoked by your application. Enable the Agora SDK's communication functionality through the creation of an IRtcEngine object, then call the methods of this object. */ class IRtcEngine { @@ -5359,7 +6640,7 @@ class IRtcEngine { * - 0(ERR_OK): Success. * - < 0: Failure. * - -1(ERR_FAILED): A general error occurs (no specified reason). - * - -2(ERR_INALID_ARGUMENT): No `IRtcEngineEventHandler` object is specified. + * - -2(ERR_INVALID_ARGUMENT): No `IRtcEngineEventHandler` object is specified. * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. Check whether `context` is properly set. * - -22(ERR_RESOURCE_LIMITED): The resource is limited. The app uses too much of the system resource and fails to allocate any resources. * - -101(ERR_INVALID_APP_ID): The App ID is invalid. @@ -5391,7 +6672,9 @@ class IRtcEngine { /** Sets the channel profile of the Agora IRtcEngine. * - * The Agora IRtcEngine differentiates channel profiles and applies optimization algorithms accordingly. + * After initialization, the SDK uses the `CHANNEL_PROFILE_COMMUNICATION` channel profile by default. + * You can call this method to set the channel profile. The Agora IRtcEngine differentiates channel profiles and + * applies optimization algorithms accordingly. * For example, it prioritizes smoothness and low latency for a video call, and prioritizes video quality for the interactive live video streaming. * * @warning @@ -5409,48 +6692,61 @@ class IRtcEngine { */ virtual int setChannelProfile(CHANNEL_PROFILE_TYPE profile) = 0; - /** Sets the role of the user, such as a host or an audience (default), before joining a channel in the interactive live streaming. + /** Sets the role of the user in interactive live streaming. * - * This method can be used to switch the user role in the interactive live streaming after the user joins a channel. + * After calling \ref IRtcEngine::setChannelProfile "setChannelProfile" (CHANNEL_PROFILE_LIVE_BROADCASTING), the + * SDK sets the user role as audience by default. You can call `setClientRole` to set the user role as host. * - * In the `LIVE_BROADCASTING` profile, when a user switches user roles after joining a channel, a successful \ref agora::rtc::IRtcEngine::setClientRole "setClientRole" method call triggers the following callbacks: - * - The local client: \ref agora::rtc::IRtcEngineEventHandler::onClientRoleChanged "onClientRoleChanged" - * - The remote client: \ref agora::rtc::IRtcEngineEventHandler::onUserJoined "onUserJoined" or \ref agora::rtc::IRtcEngineEventHandler::onUserOffline "onUserOffline" (BECOME_AUDIENCE) + * 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 \ref IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" and \ref IRtcEngine::muteLocalVideoStream "muteLocalVideoStream" to + * change the publishing state. + * - Triggers \ref IRtcEngineEventHandler::onClientRoleChanged "onClientRoleChanged" or \ref IRtcEngineEventHandler::onClientRoleChangeFailed "onClientRoleChangeFailed" on the local client in 5s. + * - Triggers \ref IRtcEngineEventHandler::onUserJoined "onUserJoined" or \ref IRtcEngineEventHandler::onUserOffline "onUserOffline" (BECOME_AUDIENCE) + * on the remote client. * - * @note - * This method applies only to the `LIVE_BROADCASTING` profile. + * @note This method applies to the `LIVE_BROADCASTING` profile only. * - * @param role Sets the role of the user. See #CLIENT_ROLE_TYPE. + * @param role The role of a user in interactive live streaming. See #CLIENT_ROLE_TYPE. * * @return * - 0(ERR_OK): Success. * - < 0: Failure. * - -1(ERR_FAILED): A general error occurs (no specified reason). - * - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + * - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. + * - -5 (ERR_REFUSED): The request is rejected. In multichannel scenarios, if you have set any of the following in + * one channel, the SDK returns this error code when the user switches the user role to host in another channel: + * - Call `joinChannel` with the `options` parameter and use the default settings `publishLocalAudio = true` or `publishLocalVideo = true`. + * - Call `setClientRole` to set the user role as host. + * - Call `muteLocalAudioStream(false)` or `muteLocalVideoStream(false)`. * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. */ virtual int setClientRole(CLIENT_ROLE_TYPE role) = 0; - /** Sets the role of a user in interactive live streaming. + /** Sets the role of the user in interactive live streaming. * * @since v3.2.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: \ref IRtcEngineEventHandler::onClientRoleChanged "onClientRoleChanged". - * - The remote client: \ref IRtcEngineEventHandler::onUserJoined "onUserJoined" - * or \ref IRtcEngineEventHandler::onUserOffline "onUserOffline". + * In the `LIVE_BROADCASTING` channel profile, the + * SDK sets the user role as audience by default. You can call `setClientRole` to set the user role as host. + * + * You can call this method either before or after joining a channel. If you + * call this method to switch the user role after joining a channel, the SDK automatically does the following: + * - Calls \ref IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" and \ref IRtcEngine::muteLocalVideoStream "muteLocalVideoStream" to + * change the publishing state. + * - Triggers \ref IRtcEngineEventHandler::onClientRoleChanged "onClientRoleChanged" or \ref IRtcEngineEventHandler::onClientRoleChangeFailed "onClientRoleChangeFailed" on the local client in 5s. + * - Triggers \ref IRtcEngineEventHandler::onUserJoined "onUserJoined" or \ref IRtcEngineEventHandler::onUserOffline "onUserOffline" (BECOME_AUDIENCE) + * on the remote client. * * @note - * - This method applies to the `LIVE_BROADCASTING` profile only (when the `profile` parameter in - * \ref IRtcEngine::setChannelProfile "setChannelProfile" is set as `CHANNEL_PROFILE_LIVE_BROADCASTING`). + * - This method applies to the `LIVE_BROADCASTING` profile only. * - The difference between this method and \ref IRtcEngine::setClientRole(CLIENT_ROLE_TYPE) "setClientRole" [1/2] is that * this method can set the user level in addition to the user role. - * - The user role determines the permissions that the SDK grants to a user, such as permission to send local - * streams, receive remote streams, and push streams to a CDN address. - * - The user level determines the level of services that a user can enjoy within the permissions of the user's - * role. For example, an audience can choose to receive remote streams with low latency or ultra low latency. Levels - * affect prices. + * - The user role determines the permissions that the SDK grants to a user, such as permission to send local streams, + * receive remote streams, and push streams to a CDN address. + * - The user level determines the level of services that a user can enjoy within the permissions of the user's role. + * For example, an audience member can choose to receive remote streams with low latency or ultra low latency. + * **User level affects the pricing of services.** * * @param role The role of a user in interactive live streaming. See #CLIENT_ROLE_TYPE. * @param options The detailed options of a user, including user level. See ClientRoleOptions. @@ -5459,7 +6755,12 @@ class IRtcEngine { * - 0(ERR_OK): Success. * - < 0: Failure. * - -1(ERR_FAILED): A general error occurs (no specified reason). - * - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + * - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. + * - -5 (ERR_REFUSED): The request is rejected. In multichannel scenarios, if you have set any of the following in + * one channel, the SDK returns this error code when the user switches the user role to host in another channel: + * - Call `joinChannel` with the `options` parameter and use the default settings `publishLocalAudio = true` or `publishLocalVideo = true`. + * - Call `setClientRole` to set the user role as host. + * - Call `muteLocalAudioStream(false)` or `muteLocalVideoStream(false)`. * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. */ virtual int setClientRole(CLIENT_ROLE_TYPE role, const ClientRoleOptions& options) = 0; @@ -5482,7 +6783,7 @@ class IRtcEngine { @note A channel does not accept duplicate uids, such as two users with the same @p uid. If you set @p uid as 0, the system automatically assigns a @p uid. If you want to join a channel from different devices, ensure that each device has a different uid. @warning Ensure that the App ID used for creating the token is the same App ID used by the \ref IRtcEngine::initialize "initialize" method for initializing the RTC engine. Otherwise, the CDN live streaming may fail. - @param token The token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Windows). + @param token The token generated at your server. See [Authenticate Your Users with Tokens](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=All%20Platforms). @param channelId Pointer to the unique channel name for the Agora RTC session in the string format smaller than 64 bytes. Supported characters: - All lowercase English letters: a to z. - All uppercase English letters: A to Z. @@ -5495,15 +6796,18 @@ class IRtcEngine { @return - 0(ERR_OK): Success. - < 0: Failure. - - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. - -3(ERR_NOT_READY): The SDK fails to be initialized. You can try re-initializing the SDK. - -5(ERR_REFUSED): The request is rejected. This may be caused by the following: - You have created an IChannel object with the same channel name. - You have joined and published a stream in a channel created by the IChannel object. When you join a channel created by the IRtcEngine object, the SDK publishes the local audio and video streams to that channel by default. Because the SDK does not support publishing a local stream to more than one channel simultaneously, an error occurs in this occasion. - -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method. + - -17(ERR_JOIN_CHANNEL_REJECTED): The request to join the channel is rejected. The SDK supports joining only one + IRtcEngine channel at a time. Therefore, the SDK returns this error code when a user who has already joined an + IRtcEngine channel calls the joining channel method of the IRtcEngine class with a valid channel name. */ virtual int joinChannel(const char* token, const char* channelId, const char* info, uid_t uid) = 0; - /** Joins a channel with the user ID, and configures whether to automatically subscribe to the audio or video streams. + /** Joins a channel with the user ID, and configures whether to publish or automatically subscribe to the audio or video streams. * * @since v3.3.0 * @@ -5520,13 +6824,14 @@ class IRtcEngine { * * @note * - Compared with \ref IRtcEngine::joinChannel(const char* token, const char* channelId, const char* info, uid_t uid) "joinChannel" [1/2], this method - * has the options parameter which configures whether the user automatically subscribes to all remote audio and video streams in the channel when - * joining the channel. By default, the user subscribes to the audio and video streams of all the other users in the channel, thus incurring all + * has the `options` parameter, which configures whether the user publishes or automatically subscribes to the audio and video streams in the channel when + * joining the channel. By default, the user publishes the local audio and video streams and automatically subscribes to the audio and video streams + * of all the other users in the channel. Subscribing incurs all * associated usage costs. To unsubscribe, set the `options` parameter or call the `mute` methods accordingly. * - Ensure that the App ID used for generating the token is the same App ID used in the \ref IRtcEngine::initialize "initialize" method for * creating an `IRtcEngine` object. * - * @param token The token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Windows). + * @param token The token generated at your server. See [Authenticate Your Users with Tokens](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=All%20Platforms). * @param channelId Pointer to the unique channel name for the Agora RTC session in the string format smaller than 64 bytes. Supported characters: * - All lowercase English letters: a to z. * - All uppercase English letters: A to Z. @@ -5535,19 +6840,22 @@ class IRtcEngine { * - Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",". * @param info (Optional) Reserved for future use. * @param uid (Optional) User ID. A 32-bit unsigned integer with a value ranging from 1 to 232-1. The @p uid must be unique. If a @p uid is - * not assigned (or set to 0), the SDK assigns and returns a @p uid in the \ref IRtcEngineEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" callback. + * not assigned (or set to 0), the SDK assigns and returns a `uid` in the \ref IRtcEngineEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" callback. * Your application must record and maintain the returned `uid`, because the SDK does not do so. **Note**: The ID of each user in the channel should be unique. * If you want to join the same channel from different devices, ensure that the user IDs in all devices are different. * @param options The channel media options: ChannelMediaOptions. @return * - 0(ERR_OK): Success. * - < 0: Failure. - * - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + * - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. * - -3(ERR_NOT_READY): The SDK fails to be initialized. You can try re-initializing the SDK. * - -5(ERR_REFUSED): The request is rejected. This may be caused by the following: * - You have created an IChannel object with the same channel name. * - You have joined and published a stream in a channel created by the IChannel object. When you join a channel created by the IRtcEngine object, the SDK publishes the local audio and video streams to that channel by default. Because the SDK does not support publishing a local stream to more than one channel simultaneously, an error occurs in this occasion. * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method. + * - -17(ERR_JOIN_CHANNEL_REJECTED): The request to join the channel is rejected. The SDK supports joining only one + * IRtcEngine channel at a time. Therefore, the SDK returns this error code when a user who has already joined an + * IRtcEngine channel calls the joining channel method of the IRtcEngine class with a valid channel name. */ virtual int joinChannel(const char* token, const char* channelId, const char* info, uid_t uid, const ChannelMediaOptions& options) = 0; /** Switches to a different channel. @@ -5571,7 +6879,7 @@ class IRtcEngine { * This method applies to the audience role in a `LIVE_BROADCASTING` channel * only. * - * @param token The token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Windows). + * @param token The token generated at your server. See [Authenticate Your Users with Tokens](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=All%20Platforms). * @param channelId Unique channel name for the AgoraRTC session in the * string format. The string length must be less than 64 bytes. Supported * character scopes are: @@ -5585,7 +6893,7 @@ class IRtcEngine { * - 0(ERR_OK): Success. * - < 0: Failure. * - -1(ERR_FAILED): A general error occurs (no specified reason). - * - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + * - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. * - -5(ERR_REFUSED): The request is rejected, probably because the user is not an audience. * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. * - -102(ERR_INVALID_CHANNEL_NAME): The channel name is invalid. @@ -5609,7 +6917,7 @@ class IRtcEngine { * By default, the user subscribes to the audio and video streams of all the other users in the target channel, thus incurring all associated usage costs. * To unsubscribe, set the `options` parameter or call the `mute` methods accordingly. * - * @param token The token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Windows). + * @param token The token generated at your server. See [Authenticate Your Users with Tokens](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=All%20Platforms). * @param channelId Unique channel name for the AgoraRTC session in the * string format. The string length must be less than 64 bytes. Supported * character scopes are: @@ -5624,7 +6932,7 @@ class IRtcEngine { * - 0(ERR_OK): Success. * - < 0: Failure. * - -1(ERR_FAILED): A general error occurs (no specified reason). - * - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + * - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. * - -5(ERR_REFUSED): The request is rejected, probably because the user is not an audience. * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. * - -102(ERR_INVALID_CHANNEL_NAME): The channel name is invalid. @@ -5652,11 +6960,15 @@ class IRtcEngine { - 0(ERR_OK): Success. - < 0: Failure. - -1(ERR_FAILED): A general error occurs (no specified reason). - - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. */ virtual int leaveChannel() = 0; + /// @cond + virtual int setAVSyncSource(const char* channelId, uid_t uid) = 0; + /// @endcond + /** Gets a new token when the current token expires after a period of time. The `token` expires after a period of time once the token schema is enabled when: @@ -5666,18 +6978,18 @@ class IRtcEngine { The application should call this method to get the new `token`. Failure to do so will result in the SDK disconnecting from the server. - @param token Pointer to the new token. + @param token The new token. @return - 0(ERR_OK): Success. - < 0: Failure. - -1(ERR_FAILED): A general error occurs (no specified reason). - - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. */ virtual int renewToken(const char* token) = 0; - /** Retrieves the pointer to the device manager object. + /** Gets the pointer to the device manager object. @param iid ID of the interface. @param inter Pointer to the *DeviceManager* object. @@ -5728,10 +7040,12 @@ class IRtcEngine { Once the user joins the channel (switches to another channel), the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. If you do not want to subscribe to a specified stream or all remote streams, call the `mute` methods accordingly. - @note To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. + @note + - To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the uid of the user is set to the same parameter type. + - Before using a String user name, ensure that you read [How can I use string user names](https://docs.agora.io/en/faq/string) for getting details about the limitations and implementation steps. - @param token The token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Windows). + @param token The token generated at your server. See [Authenticate Your Users with Tokens](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=All%20Platforms). @param channelId The channel name. The maximum length of this parameter is 64 bytes. Supported character scopes are: - All lowercase English letters: a to z. - All uppercase English letters: A to Z. @@ -5752,9 +7066,13 @@ class IRtcEngine { - #ERR_NOT_READY (-3) - #ERR_REFUSED (-5) - #ERR_NOT_INITIALIZED (-7) + - -17(ERR_JOIN_CHANNEL_REJECTED): The request to join the channel is rejected. The SDK supports joining only one + IRtcEngine channel at a time. Therefore, the SDK returns this error code when a user who has already joined an + IRtcEngine channel calls the joining channel method of the IRtcEngine class with a valid channel name. */ virtual int joinChannelWithUserAccount(const char* token, const char* channelId, const char* userAccount) = 0; - /** Joins the channel with a user account, and configures whether to automatically subscribe to audio or video streams after joining the channel. + /** Joins the channel with a user account, and configures + * whether to publish or automatically subscribe to the audio or video streams. * * @since v3.3.0 * @@ -5764,14 +7082,15 @@ class IRtcEngine { * * @note * - Compared with \ref IRtcEngine::joinChannelWithUserAccount(const char* token, const char* channelId, const char* userAccount) "joinChannelWithUserAccount" [1/2], - * this method has the options parameter to configure whether the end user automatically subscribes to all remote audio and video streams in a - * channel when joining the channel. By default, the user subscribes to the audio and video streams of all the other users in the channel, thus - * incurring all associated usage costs. To unsubscribe, set the `options` parameter or call the `mute` methods accordingly. + * this method has the options parameter, which configures whether the user publishes or automatically subscribes to the audio and video streams in the channel when + * joining the channel. By default, the user publishes the local audio and video streams and automatically subscribes to the audio and video streams of all the other + * users in the channel. Subscribing incurs all associated usage costs. To unsubscribe, set the `options` parameter or call the `mute` methods accordingly. * - To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all * the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the * uid of the user is set to the same parameter type. + * - Before using a String user name, ensure that you read [How can I use string user names](https://docs.agora.io/en/faq/string) for getting details about the limitations and implementation steps. * - * @param token The token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Windows). + * @param token The token generated at your server. See [Authenticate Your Users with Tokens](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=All%20Platforms). * @param channelId The channel name. The maximum length of this parameter is 64 bytes. Supported character scopes are: * - All lowercase English letters: a to z. * - All uppercase English letters: A to Z. @@ -5791,6 +7110,9 @@ class IRtcEngine { * - #ERR_INVALID_ARGUMENT (-2) * - #ERR_NOT_READY (-3) * - #ERR_REFUSED (-5) + * - -17(ERR_JOIN_CHANNEL_REJECTED): The request to join the channel is rejected. The SDK supports joining only one + * IRtcEngine channel at a time. Therefore, the SDK returns this error code when a user who has already joined an + * IRtcEngine channel calls the joining channel method of the IRtcEngine class with a valid channel name. */ virtual int joinChannelWithUserAccount(const char* token, const char* channelId, const char* userAccount, const ChannelMediaOptions& options) = 0; @@ -5870,85 +7192,121 @@ class IRtcEngine { */ virtual int startEchoTest(int intervalInSeconds) = 0; - /** Stops the audio call test. + /** Starts an audio and video call loop test. + * + * @since v3.5.2 + * + * Before joining a channel, to test whether the user's local sending and receiving streams are normal, you can call + * this method to perform an audio and video call loop test, which tests whether the audio and video devices and the + * user's upstream and downstream networks are working properly. + * + * After starting the test, the user needs to make a sound or face the camera. The audio or video is output after + * about two seconds. If the audio playback is normal, the audio device and the user's upstream and downstream + * networks are working properly; if the video playback is normal, the video device and the user's upstream and + * downstream networks are working properly. + * + * @note + * - Call this method before joining a channel. + * - After calling this method, call \ref IRtcEngine::stopEchoTest "stopEchoTest" to end the test; otherwise, the + * user cannot perform the next audio and video call loop test and cannot join the channel. + * - In the `LIVE_BROADCASTING` profile, only a host can call this method. + * + * @param config The configuration of the audio and video call loop test. See EchoTestConfiguration. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int startEchoTest(const EchoTestConfiguration& config) = 0; - @return - - 0: Success. - - < 0: Failure. + /** Stops call loop test. + * + * After calling `startEchoTest [2/3]` or `startEchoTest [3/3]`, call this method if you want to stop the call loop test. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int stopEchoTest() = 0; + /** Sets the Agora cloud proxy service. * * @since v3.3.0 * * When the user's firewall restricts the IP address and port, refer to *Use Cloud Proxy* to add the specific * IP addresses and ports to the firewall whitelist; then, call this method to enable the cloud proxy and set - * the cloud proxy type with the `proxyType` parameter: - * - `UDP_PROXY(1)`: The cloud proxy for the UDP protocol. - * - `TCP_PROXY(2)`: The cloud proxy for the TCP (encrypted) protocol. + * the `proxyType` parameter as `UDP_PROXY(1)`, which is the cloud proxy for the UDP protocol. * - * After a successfully cloud proxy connection, the SDK triggers the \ref IRtcEngineEventHandler::onConnectionStateChanged "onConnectionStateChanged" (CONNECTION_STATE_CONNECTING, CONNECTION_CHANGED_SETTING_PROXY_SERVER) callback. + * After a successfully cloud proxy connection, the SDK triggers + * the \ref IRtcEngineEventHandler::onConnectionStateChanged "onConnectionStateChanged" (CONNECTION_STATE_CONNECTING, CONNECTION_CHANGED_SETTING_PROXY_SERVER) callback. * * To disable the cloud proxy that has been set, call `setCloudProxy(NONE_PROXY)`. To change the cloud proxy type that has been set, * call `setCloudProxy(NONE_PROXY)` first, and then call `setCloudProxy`, and pass the value that you expect in `proxyType`. * * @note * - Agora recommends that you call this method before joining the channel or after leaving the channel. - * - When you use the cloud proxy for the UDP protocol, the services for pushing streams to CDN and co-hosting across channels are not available. - * - When you use the cloud proxy for the TCP (encrypted) protocol, note the following: - * - An error occurs when calling \ref IRtcEngine::startAudioMixing "startAudioMixing" to play online audio files in the HTTP protocol. - * - The services for pushing streams to CDN and co-hosting across channels will use the cloud proxy with the TCP protocol. + * - For the SDK v3.3.x, the services for pushing streams to CDN and co-hosting across channels are not available + * when you use the cloud proxy for the UDP protocol. For the SDK v3.4.0 and later, the services for pushing streams + * to CDN and co-hosting across channels are not available when the user is in a network environment with a firewall + * and uses the cloud proxy for the UDP protocol. * * @param proxyType The cloud proxy type, see #CLOUD_PROXY_TYPE. This parameter is required, and the SDK reports an error if you do not pass in a value. * * @return * - 0: Success. * - < 0: Failure. - * - `-2（ERR_INVALID_ARGUMENT)`: The parameter is invalid. + * - `-2(ERR_INVALID_ARGUMENT)`: The parameter is invalid. * - `-7(ERR_NOT_INITIALIZED)`: The SDK is not initialized. */ virtual int setCloudProxy(CLOUD_PROXY_TYPE proxyType) = 0; /** Enables the video module. - - Call this method either before joining a channel or during a call. If this method is called before joining a channel, the call starts in the video mode. If this method is called during an audio call, the audio mode switches to the video mode. To disable the video module, call the \ref IRtcEngine::disableVideo "disableVideo" method. - - A successful \ref agora::rtc::IRtcEngine::enableVideo "enableVideo" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onUserEnableVideo "onUserEnableVideo" (true) callback on the remote client. - @note - - This method affects the internal engine and can be called after the \ref agora::rtc::IRtcEngine::leaveChannel "leaveChannel" method. - - This method resets the internal engine and takes some time to take effect. We recommend using the following API methods to control the video engine modules separately: - - \ref IRtcEngine::enableLocalVideo "enableLocalVideo": Whether to enable the camera to create the local video stream. - - \ref IRtcEngine::muteLocalVideoStream "muteLocalVideoStream": Whether to publish the local video stream. - - \ref IRtcEngine::muteRemoteVideoStream "muteRemoteVideoStream": Whether to subscribe to and play the remote video stream. - - \ref IRtcEngine::muteAllRemoteVideoStreams "muteAllRemoteVideoStreams": Whether to subscribe to and play all remote video streams. - - @return - - 0: Success. - - < 0: Failure. + * + * Call this method either before joining a channel or during a call. If this method is called before joining a channel, the call starts in the video mode. If this method is called during an audio call, the audio mode switches to the video mode. To disable the video module, call the \ref IRtcEngine::disableVideo "disableVideo" method. + * + * A successful \ref agora::rtc::IRtcEngine::enableVideo "enableVideo" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onUserEnableVideo "onUserEnableVideo" (true) callback on the remote client. + * @note + * - This method affects the internal engine and can be called after the \ref agora::rtc::IRtcEngine::leaveChannel "leaveChannel" method. + * - This method resets the internal engine and takes some time to take effect. We recommend using the following API methods to control the video engine modules separately: + * - \ref IRtcEngine::enableLocalVideo "enableLocalVideo": Whether to enable the camera to create the local video stream. + * - \ref IRtcEngine::muteLocalVideoStream "muteLocalVideoStream": Whether to publish the local video stream. + * - \ref IRtcEngine::muteRemoteVideoStream "muteRemoteVideoStream": Whether to subscribe to and play the remote video stream. + * - \ref IRtcEngine::muteAllRemoteVideoStreams "muteAllRemoteVideoStreams": Whether to subscribe to and play all remote video streams. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int enableVideo() = 0; /** Disables the video module. - - This method can be called before joining a channel or during a call. If this method is called before joining a channel, the call starts in audio mode. If this method is called during a video call, the video mode switches to the audio mode. To enable the video module, call the \ref IRtcEngine::enableVideo "enableVideo" method. - - A successful \ref agora::rtc::IRtcEngine::disableVideo "disableVideo" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onUserEnableVideo "onUserEnableVideo" (false) callback on the remote client. - @note - - This method affects the internal engine and can be called after the \ref agora::rtc::IRtcEngine::leaveChannel "leaveChannel" method. - - This method resets the internal engine and takes some time to take effect. We recommend using the following API methods to control the video engine modules separately: - - \ref IRtcEngine::enableLocalVideo "enableLocalVideo": Whether to enable the camera to create the local video stream. - - \ref IRtcEngine::muteLocalVideoStream "muteLocalVideoStream": Whether to publish the local video stream. - - \ref IRtcEngine::muteRemoteVideoStream "muteRemoteVideoStream": Whether to subscribe to and play the remote video stream. - - \ref IRtcEngine::muteAllRemoteVideoStreams "muteAllRemoteVideoStreams": Whether to subscribe to and play all remote video streams. - - @return - - 0: Success. - - < 0: Failure. + * + * This method can be called before joining a channel or during a call. If this method is called before joining a + * channel, the call starts in audio mode. If this method is called during a video call, the video mode switches to + * the audio mode. To enable the video module, call the \ref IRtcEngine::enableVideo "enableVideo" method. + * + * A successful \ref agora::rtc::IRtcEngine::disableVideo "disableVideo" method call triggers + * the \ref agora::rtc::IRtcEngineEventHandler::onUserEnableVideo "onUserEnableVideo" (false) callback on the remote + * client. + * + * @note + * - This method affects the internal engine and can be called after + * the \ref agora::rtc::IRtcEngine::leaveChannel "leaveChannel" method. + * - This method resets the internal engine and takes some time to take effect. We recommend using the following + * APIs to control the video engine modules separately: + * - \ref IRtcEngine::enableLocalVideo "enableLocalVideo": Whether to enable the camera to create the local video stream. + * - \ref IRtcEngine::muteLocalVideoStream "muteLocalVideoStream": Whether to publish the local video stream. + * - \ref IRtcEngine::muteRemoteVideoStream "muteRemoteVideoStream": Whether to subscribe to and play the remote video stream. + * - \ref IRtcEngine::muteAllRemoteVideoStreams "muteAllRemoteVideoStreams": Whether to subscribe to and play all remote video streams. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int disableVideo() = 0; - /** **DEPRECATED** Sets the video profile. + /** Sets the video profile. - This method is deprecated as of v2.3. Use the \ref IRtcEngine::setVideoEncoderConfiguration "setVideoEncoderConfiguration" method instead. + @deprecated This method is deprecated as of v2.3. Use the \ref IRtcEngine::setVideoEncoderConfiguration "setVideoEncoderConfiguration" method instead. Each video profile includes a set of parameters, such as the resolution, frame rate, and bitrate. If the camera device does not support the specified resolution, the SDK automatically chooses a suitable camera resolution, keeping the encoder resolution specified by the *setVideoProfile* method. @@ -5968,7 +7326,7 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int setVideoProfile(VIDEO_PROFILE_TYPE profile, bool swapWidthAndHeight) = 0; + virtual int setVideoProfile(VIDEO_PROFILE_TYPE profile, bool swapWidthAndHeight) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Sets the video encoder configuration. @@ -6074,17 +7432,20 @@ class IRtcEngine { */ virtual int setRemoteUserPriority(uid_t uid, PRIORITY_TYPE userPriority) = 0; - /** Stops the local video preview and disables video. + /** Stops the local video preview. + * + * After calling \ref IRtcEngine::startPreview "startPreview", if you want to stop + * the local video preview, call `stopPreview`. + * + * @note Call this method before you join the channel or after you leave the channel. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int stopPreview() = 0; - @note Call this method before joining a channel. - - @return - - 0: Success. - - < 0: Failure. - */ - virtual int stopPreview() = 0; - - /** Enables the audio module. + /** Enables the audio module. The audio mode is enabled by default. @@ -6103,29 +7464,31 @@ class IRtcEngine { virtual int enableAudio() = 0; /** Disables/Re-enables the local audio function. - - The audio function is enabled by default. This method disables or re-enables the local audio function, that is, to stop or restart local audio capturing. - - This method does not affect receiving or playing the remote audio streams,and enableLocalAudio(false) is applicable to scenarios where the user wants to - receive remote audio streams without sending any audio stream to other users in the channel. - - Once the local audio function is disabled or re-enabled, the SDK triggers the \ref agora::rtc::IRtcEngineEventHandler::onLocalAudioStateChanged "onLocalAudioStateChanged" callback, - which reports `LOCAL_AUDIO_STREAM_STATE_STOPPED(0)` or `LOCAL_AUDIO_STREAM_STATE_RECORDING(1)`. - - @note - - This method is different from the \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" method: - - \ref agora::rtc::IRtcEngine::enableLocalAudio "enableLocalAudio": Disables/Re-enables the local audio capturing and processing. - If you disable or re-enable local audio capturing using the `enableLocalAudio` method, the local user may hear a pause in the remote audio playback. - - \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream": Sends/Stops sending the local audio streams. - - You can call this method either before or after joining a channel. - - @param enabled Sets whether to disable/re-enable the local audio function: - - true: (Default) Re-enable the local audio function, that is, to start the local audio capturing device (for example, the microphone). - - false: Disable the local audio function, that is, to stop local audio capturing. - - @return - - 0: Success. - - < 0: Failure. + * + * The audio function is enabled by default. This method disables or re-enables the local audio function, that is, to stop or restart local audio capturing. + * + * This method does not affect receiving the remote audio streams,and enableLocalAudio(false) is applicable to scenarios where the user wants to + * receive remote audio streams without sending any audio stream to other users in the channel. + * + * Once the local audio function is disabled or re-enabled, the SDK triggers the \ref agora::rtc::IRtcEngineEventHandler::onLocalAudioStateChanged "onLocalAudioStateChanged" callback, + * which reports `LOCAL_AUDIO_STREAM_STATE_STOPPED(0)` or `LOCAL_AUDIO_STREAM_STATE_RECORDING(1)`. + * + * @note + * - This method is different from the \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" method: + * - \ref agora::rtc::IRtcEngine::enableLocalAudio "enableLocalAudio": Disables/Re-enables the local audio capturing and processing. + * If you disable or re-enable local audio capturing using the `enableLocalAudio` method, the local user may hear a pause in the remote audio playback. + * - \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream": Sends/Stops sending the local audio streams. + * - This method can be called either before or after you join a channel. Calling it before you + * join a channel can set the device state only, and it takes effect immediately after you join the + * channel. + * + * @param enabled Sets whether to disable/re-enable the local audio function: + * - true: (Default) Re-enable the local audio function, that is, to start the local audio capturing device (for example, the microphone). + * - false: Disable the local audio function, that is, to stop local audio capturing. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int enableLocalAudio(bool enabled) = 0; @@ -6148,8 +7511,8 @@ class IRtcEngine { - In the `COMMUNICATION` and `LIVE_BROADCASTING` profiles, the bitrate may be different from your settings due to network self-adaptation. - In scenarios requiring high-quality audio, for example, a music teaching scenario, we recommend setting profile as AUDIO_PROFILE_MUSIC_HIGH_QUALITY (4) and scenario as AUDIO_SCENARIO_GAME_STREAMING (3). - @param profile Sets the sample rate, bitrate, encoding mode, and the number of channels. See #AUDIO_PROFILE_TYPE. - @param scenario Sets the audio application scenario. See #AUDIO_SCENARIO_TYPE. + @param profile Sets the sample rate, bitrate, encoding mode, and the number of channels. See #AUDIO_PROFILE_TYPE. + @param scenario Sets the audio application scenario. See #AUDIO_SCENARIO_TYPE. Under different audio scenarios, the device uses different volume types. For details, see [What is the difference between the in-call volume and the media volume?](https://docs.agora.io/en/faq/system_volume). @@ -6161,33 +7524,42 @@ class IRtcEngine { /** * Stops or resumes publishing the local audio stream. * - * A successful \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" method call - * triggers the \ref agora::rtc::IRtcEngineEventHandler::onUserMuteAudio "onUserMuteAudio" callback on the remote client. + * As of v3.4.5, this method only sets the publishing state of the audio stream in the channel of IRtcEngine. + * + * A successful method call triggers the \ref IRtcEngineEventHandler::onUserMuteAudio "onUserMuteAudio" callback + * on the remote client. + * + * You can only publish the local stream in one channel at a time. If you create multiple channels, ensure that + * you only call \ref IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" (false) in one channel; + * otherwise, the method call fails, and the SDK returns `-5 (ERR_REFUSED)`. * * @note - * - When @p mute is set as @p true, this method does not affect any ongoing audio recording, because it does not disable the microphone. - * - You can call this method either before or after joining a channel. If you call \ref agora::rtc::IRtcEngine::setChannelProfile "setChannelProfile" - * after this method, the SDK resets whether or not to stop publishing the local audio according to the channel profile and user role. - * Therefore, we recommend calling this method after the `setChannelProfile` method. + * - This method does not change the usage state of the audio-capturing device. + * - Whether this method call takes effect is affected by the + * \ref IRtcEngine::joinChannel(const char* token, const char* channelId, const char* info, uid_t uid, const ChannelMediaOptions& options) "joinChannel" [2/2] + * and \ref IRtcEngine::setClientRole "setClientRole" methods. For details, see *Set the Publishing State*. * * @param mute Sets whether to stop publishing the local audio stream. * - true: Stop publishing the local audio stream. - * - false: (Default) Resumes publishing the local audio stream. + * - false: Resume publishing the local audio stream. * * @return * - 0: Success. * - < 0: Failure. + * - `-5 (ERR_REFUSED)`: The request is rejected. */ virtual int muteLocalAudioStream(bool mute) = 0; /** * Stops or resumes subscribing to the audio streams of all remote users. * - * As of v3.3.0, after successfully calling this method, the local user stops or resumes + * 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*. + * - As of v3.3.0, this method contains the function of \ref IRtcEngine::setDefaultMuteAllRemoteAudioStreams "setDefaultMuteAllRemoteAudioStreams". + * Agora recommends not calling `muteAllRemoteAudioStreams` and `setDefaultMuteAllRemoteAudioStreams` + * together; otherwise, the settings may not take effect. See *Set the Subscribing State*. * * @param mute Sets whether to stop subscribing to the audio streams of all remote users. * - true: Stop subscribing to the audio streams of all remote users. @@ -6219,25 +7591,27 @@ class IRtcEngine { * - 0: Success. * - < 0: Failure. */ - virtual int setDefaultMuteAllRemoteAudioStreams(bool mute) = 0; + virtual int setDefaultMuteAllRemoteAudioStreams(bool mute) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Adjusts the playback signal volume of a specified remote user. - - You can call this method as many times as necessary to adjust the playback volume of different remote users, or to repeatedly adjust the playback volume of the same remote user. - - @note - - Call this method after joining a channel. - - The playback volume here refers to the mixed volume of a specified remote user. - - This method can only adjust the playback volume of one specified remote user at a time. To adjust the playback volume of different remote users, call the method as many times, once for each remote user. - - @param uid The ID of the remote user. - @param volume The playback volume of the specified remote user. The value ranges from 0 to 100: - - 0: Mute. - - 100: Original volume. - - @return - - 0: Success. - - < 0: Failure. + * + * You can call this method as many times as necessary to adjust the playback volume of different remote users, or to repeatedly adjust the playback volume of the same remote user. + * + * @note + * - Call this method after joining a channel. + * - The playback volume here refers to the mixed volume of a specified remote user. + * - This method can only adjust the playback volume of one specified remote user at a time. To adjust the playback volume of different remote users, call the method as many times, once for each remote user. + * + * @param uid The ID of the remote user. + * @param volume The playback volume of the specified remote user. The value + * ranges between 0 and 400, including the following: + * - 0: Mute. + * - 100: (Default) Original volume. + * - 400: Four times the original volume with signal-clipping protection. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int adjustUserPlaybackSignalVolume(unsigned int uid, int volume) = 0; /** @@ -6259,25 +7633,29 @@ class IRtcEngine { virtual int muteRemoteAudioStream(uid_t userId, bool mute) = 0; /** Stops or resumes publishing the local video stream. * - * A successful \ref agora::rtc::IRtcEngine::muteLocalVideoStream "muteLocalVideoStream" method call - * triggers the \ref agora::rtc::IRtcEngineEventHandler::onUserMuteVideo "onUserMuteVideo" callback on - * the remote client. + * As of v3.4.5, this method only sets the publishing state of the video stream in the channel of IRtcEngine. + * + * A successful method call triggers the \ref IRtcEngineEventHandler::onUserMuteVideo "onUserMuteVideo" + * callback on the remote client. + * + * You can only publish the local stream in one channel at a time. If you create multiple channels, + * ensure that you only call \ref IRtcEngine::muteLocalVideoStream "muteLocalVideoStream" (false) in one channel; + * otherwise, the method call fails, and the SDK returns `-5 (ERR_REFUSED)`. * * @note - * - This method executes faster than the \ref IRtcEngine::enableLocalVideo "enableLocalVideo" method, - * which controls the sending of the local video stream. - * - When `mute` is set as `true`, this method does not affect any ongoing video recording, because it does not disable the camera. - * - You can call this method either before or after joining a channel. If you call \ref IRtcEngine::setChannelProfile "setChannelProfile" - * after this method, the SDK resets whether or not to stop publishing the local video according to the channel profile and user role. - * Therefore, Agora recommends calling this method after the `setChannelProfile` method. + * - This method does not change the usage state of the video-capturing device. + * - Whether this method call takes effect is affected by the + * \ref IRtcEngine::joinChannel(const char* token, const char* channelId, const char* info, uid_t uid, const ChannelMediaOptions& options) "joinChannel" [2/2] + * and \ref IRtcEngine::setClientRole "setClientRole" methods. For details, see *Set the Publishing State*. * * @param mute Sets whether to stop publishing the local video stream. * - true: Stop publishing the local video stream. - * - false: (Default) Resumes publishing the local video stream. + * - false: Resume publishing the local video stream. * * @return * - 0: Success. * - < 0: Failure. + * - `-5 (ERR_REFUSED)`: The request is rejected. */ virtual int muteLocalVideoStream(bool mute) = 0; /** Enables/Disables the local video capture. @@ -6304,7 +7682,7 @@ class IRtcEngine { /** * Stops or resumes subscribing to the video streams of all remote users. * - * As of v3.3.0, after successfully calling this method, the local user stops or resumes + * 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 @@ -6340,7 +7718,7 @@ class IRtcEngine { * - 0: Success. * - < 0: Failure. */ - virtual int setDefaultMuteAllRemoteVideoStreams(bool mute) = 0; + virtual int setDefaultMuteAllRemoteVideoStreams(bool mute) AGORA_DEPRECATED_ATTRIBUTE = 0; /** * Stops or resumes subscribing to the video stream of a specified user. * @@ -6412,6 +7790,22 @@ class IRtcEngine { */ virtual int setRemoteDefaultVideoStreamType(REMOTE_VIDEO_STREAM_TYPE streamType) = 0; + /** Turn WIFI acceleration on or off. + + @note + - This method is called before and after joining a channel. + - Users check the WIFI router app for information about acceleration. Therefore, if this interface is invoked, the caller accepts that the caller's name will be displayed to the user in the WIFI router application on behalf of the caller. + + @param enabled + - true：Turn WIFI acceleration on. + - false：Turn WIFI acceleration off. + + @return + - 0: Success. + - < 0: Failure. + */ + virtual int enableWirelessAccelerate(bool enabled) = 0; + /** Enables the reporting of users' volume indication. This method enables the SDK to regularly report the volume information of the local user who sends a stream and @@ -6436,7 +7830,8 @@ class IRtcEngine { virtual int enableAudioVolumeIndication(int interval, int smooth, bool report_vad) = 0; /** Starts an audio recording. - @deprecated + @deprecated Deprecated from v2.9.1. + Use \ref IRtcEngine::startAudioRecording(const AudioRecordingConfiguration&) "startAudioRecording" [3/3] instead. The SDK allows recording during a call. Supported formats: @@ -6456,11 +7851,12 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int startAudioRecording(const char* filePath, AUDIO_RECORDING_QUALITY_TYPE quality) = 0; + virtual int startAudioRecording(const char* filePath, AUDIO_RECORDING_QUALITY_TYPE quality) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Starts an audio recording on the client. * - * @deprecated + * @deprecated Deprecated from v3.4.0. Use + * \ref IRtcEngine::startAudioRecording(const AudioRecordingConfiguration&) "startAudioRecording" [3/3] instead. * * The SDK allows recording during a call. After successfully calling this method, you can record the audio of all the users in the channel and get an audio recording file. * Supported formats of the recording file are as follows: @@ -6484,24 +7880,41 @@ class IRtcEngine { * - 0: Success. * - < 0: Failure. */ - virtual int startAudioRecording(const char* filePath, int sampleRate, AUDIO_RECORDING_QUALITY_TYPE quality) = 0; - /** Starts an audio recording. - - The SDK allows recording during a call. - This method is usually called after the \ref agora::rtc::IRtcEngine::joinChannel "joinChannel" method. - The recording automatically stops when the \ref agora::rtc::IRtcEngine::leaveChannel "leaveChannel" method is called. - - @param config Sets the audio recording configuration. See #AudioRecordingConfiguration. - - @return - - 0: Success. - - < 0: Failure. + virtual int startAudioRecording(const char* filePath, int sampleRate, AUDIO_RECORDING_QUALITY_TYPE quality) AGORA_DEPRECATED_ATTRIBUTE = 0; + /** + * Starts an audio recording on the client. + * + * @since v3.4.0 + * + * The SDK allows recording audio during a call. After successfully calling + * this method, you can record the audio of users in the channel and get + * an audio recording file. Supported file formats are as follows: + * - WAV: High-fidelity files with typically larger file sizes. For example, + * if the sample rate is 32,000 Hz, the file size for a 10-minute recording + * is approximately 73 MB. + * - AAC: Low-fidelity files with typically smaller file sizes. For example, + * if the sample rate is 32,000 Hz and the recording quality is + * #AUDIO_RECORDING_QUALITY_MEDIUM, the file size for a 10-minute recording + * is approximately 2 MB. + * + * Once the user leaves the channel, the recording automatically stops. + * + * @note Call this method after joining a channel. + * + * @param config Recording configuration. See AudioRecordingConfiguration. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `-160(ERR_ALREADY_IN_RECORDING)`: The client is already recording + * audio. To start a new recording, + * call \ref IRtcEngine::stopAudioRecording "stopAudioRecording" to stop the + * current recording first, and then + * call \ref IRtcEngine::startAudioRecording(const AudioRecordingConfiguration&) "startAudioRecording". */ virtual int startAudioRecording(const AudioRecordingConfiguration& config) = 0; /** Stops an audio recording on the client. - You can call this method before calling the \ref agora::rtc::IRtcEngine::leaveChannel "leaveChannel" method else, the recording automatically stops when the \ref agora::rtc::IRtcEngine::leaveChannel "leaveChannel" method is called. - @return - 0: Success - < 0: Failure. @@ -6509,71 +7922,116 @@ class IRtcEngine { virtual int stopAudioRecording() = 0; /** Starts playing and mixing the music file. - - @deprecated Deprecated from v3.4.0. Using the following methods instead: - - \ref IRtcEngine::startAudioMixing(const char* filePath, bool loopback, bool replace, int cycle, int startPos = 0) - - This method mixes the specified local audio file with the audio stream from the microphone, or replaces the microphone's audio stream with the specified local audio file. You can choose whether the other user can hear the local audio playback and specify the number of playback loops. This method also supports online music playback. - - When the audio mixing file playback finishes after calling this method, the SDK triggers the \ref agora::rtc::IRtcEngineEventHandler::onAudioMixingFinished "onAudioMixingFinished" callback. - - A successful \ref agora::rtc::IRtcEngine::startAudioMixing "startAudioMixing" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (PLAY) callback on the local client. - - When the audio mixing file playback finishes, the SDK triggers the \ref agora::rtc::IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (STOPPED) callback on the local client. - @note - - Call this method after joining a channel, otherwise issues may occur. - - If the local audio mixing file does not exist, or if the SDK does not support the file format or cannot access the music file URL, the SDK returns #WARN_AUDIO_MIXING_OPEN_ERROR (701). - - If you want to play an online music file, ensure that the time interval between calling this method is more than 100 ms, or the #AUDIO_MIXING_ERROR_TOO_FREQUENT_CALL (702) error code occurs. - - @param filePath Pointer to the absolute path (including the suffixes of the filename) of the local or online audio file to mix, for example, `C:/music/audio.mp4`. Supported audio formats: 3GP, ASF, ADTS, AVI, MP3, MP4, MPEG-4, SAMI, and WAVE. For more information, see [Supported Media Formats in Media Foundation](https://docs.microsoft.com/en-us/windows/desktop/medfound/supported-media-formats-in-media-foundation). - @param loopback Sets which user can hear the audio mixing: - - true: Only the local user can hear the audio mixing. - - false: Both users can hear the audio mixing. - @param replace Sets the audio mixing content: - - true: Only publish the specified audio file. The audio stream from the microphone is not published. - - false: The local audio file is mixed with the audio stream from the microphone. - @param cycle Sets the number of playback loops: - - Positive integer: Number of playback loops. - - `-1`: Infinite playback loops. - - @return - - 0: Success. - - < 0: Failure. + * + * @deprecated Deprecated from v3.4.0. Use + * \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" [2/2] instead. + * + * This method mixes the specified local audio file with the audio stream from the microphone, or replaces the microphone's audio stream with the specified local audio file. You can choose whether the other user can hear the local audio playback and specify the number of playback loops. This method also supports online music playback. + * + * When the audio mixing file playback finishes after calling this method, the SDK triggers the \ref agora::rtc::IRtcEngineEventHandler::onAudioMixingFinished "onAudioMixingFinished" callback. + * + * A successful \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (PLAY) callback on the local client. + * + * When the audio mixing file playback finishes, the SDK triggers the \ref agora::rtc::IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (STOPPED) callback on the local client. + * + * @note + * - If the local audio mixing file does not exist, or if the SDK does not support the file format or cannot access the music file URL, the SDK returns #WARN_AUDIO_MIXING_OPEN_ERROR (701). + * - If you want to play an online music file, ensure that the time interval between calling this method is more than 100 ms, or the `AUDIO_MIXING_ERROR_TOO_FREQUENT_CALL(702)` error code occurs. + * - To avoid blocking, as of v3.4.5, this method changes from a synchronous call to an asynchronous call. + * - For the audio file formats supported by this method, see [What formats of audio files does the Agora RTC SDK support](https://docs.agora.io/en/faq/audio_format). + * + * @param filePath The absolute path or URL address (including the filename extensions) + * of the music file. For example: `C:\music\audio.mp4`. + * When you access a local file on Android, Agora recommends passing a URI address or the path starts + * with `/assets/` in this parameter. + * @param loopback Sets which user can hear the audio mixing: + * - true: Only the local user can hear the audio mixing. + * - false: Both users can hear the audio mixing. + * @param replace Sets the audio mixing content: + * - true: Only publish the specified audio file. The audio stream from the microphone is not published. + * - false: The local audio file is mixed with the audio stream from the microphone. + * @param cycle Sets the number of playback loops: + * - Positive integer: Number of playback loops. + * - `-1`: Infinite playback loops. + * + * @return + * - 0: Success. + * - < 0: Failure. */ - virtual int startAudioMixing(const char* filePath, bool loopback, bool replace, int cycle) = 0; - - /** Starts playing and mixing the music file. - - This method mixes the specified local audio file with the audio stream from the microphone, or replaces the microphone's audio stream with the specified local audio file. You can choose whether the other user can hear the local audio playback and specify the number of playback loops. This method also supports online music playback. - - When the audio mixing file playback finishes after calling this method, the SDK triggers the \ref agora::rtc::IRtcEngineEventHandler::onAudioMixingFinished "onAudioMixingFinished" callback. - - A successful \ref agora::rtc::IRtcEngine::startAudioMixing "startAudioMixing" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (PLAY) callback on the local client. - - When the audio mixing file playback finishes, the SDK triggers the \ref agora::rtc::IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (STOPPED) callback on the local client. - @note - - Call this method after joining a channel, otherwise issues may occur. - - If the local audio mixing file does not exist, or if the SDK does not support the file format or cannot access the music file URL, the SDK returns #WARN_AUDIO_MIXING_OPEN_ERROR (701). - - If you want to play an online music file, ensure that the time interval between calling this method is more than 100 ms, or the #AUDIO_MIXING_ERROR_TOO_FREQUENT_CALL (702) error code occurs. - - @param filePath Pointer to the absolute path (including the suffixes of the filename) of the local or online audio file to mix, for example, `C:/music/audio.mp4`. Supported audio formats: 3GP, ASF, ADTS, AVI, MP3, MP4, MPEG-4, SAMI, and WAVE. For more information, see [Supported Media Formats in Media Foundation](https://docs.microsoft.com/en-us/windows/desktop/medfound/supported-media-formats-in-media-foundation). - @param loopback Sets which user can hear the audio mixing: - - true: Only the local user can hear the audio mixing. - - false: Both users can hear the audio mixing. - @param replace Sets the audio mixing content: - - true: Only publish the specified audio file. The audio stream from the microphone is not published. - - false: The local audio file is mixed with the audio stream from the microphone. - @param cycle Sets the number of playback loops: - - Positive integer: Number of playback loops. - - `-1`: Infinite playback loops. - @param startPos start playback position. - - Min value is 0. - - Max value is file length, the unit is ms - @return - - 0: Success. - - < 0: Failure. + virtual int startAudioMixing(const char* filePath, bool loopback, bool replace, int cycle) AGORA_DEPRECATED_ATTRIBUTE = 0; + /** + * Starts playing and mixing the music file. + * + * @since v3.4.0 + * + * This method supports mixing or replacing local or online music file and + * audio collected by a microphone. After successfully playing the music + * file, the SDK triggers + * \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING,AUDIO_MIXING_REASON_STARTED_BY_USER). + * After completing playing the music file, the SDK triggers + * `onAudioMixingStateChanged(AUDIO_MIXING_STATE_STOPPED,AUDIO_MIXING_REASON_ALL_LOOPS_COMPLETED)`. + * + * @note + * - If you need to call + * \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" multiple times, + * ensure that the call interval is longer than 500 ms. + * - If the local music file does not exist, or if the SDK does not support + * the file format or cannot access the music file URL, the SDK returns + * #WARN_AUDIO_MIXING_OPEN_ERROR (701). + * - On Android: + * - To use this method, ensure that the Android device is v4.2 or later + * and the API version is v16 or later. + * - If you need to play an online music file, Agora does not recommend + * using the redirected URL address. Some Android devices may fail to open a redirected URL address. + * - If you call this method on an emulator, ensure that the music file is + * in the `/sdcard/` directory and the format is MP3. + * - To avoid blocking, as of v3.4.5, this method changes from a synchronous call to an asynchronous call. + * - For the audio file formats supported by this method, see [What formats of audio files does the Agora RTC SDK support](https://docs.agora.io/en/faq/audio_format). + * + * @param filePath The absolute path or URL address (including the filename extensions) + * of the music file. For example: `C:\music\audio.mp4`. + * When you access a local file on Android, Agora recommends passing a URI address or the path starts + * with `/assets/` in this parameter. + * @param loopback Whether to only play the music file on the local client: + * - true: Only play the music file on the local client so that only the local + * user can hear the music. + * - false: Publish the music file to remote clients so that both the local + * user and remote users can hear the music. + * @param replace Whether to replace the audio collected by the microphone + * with a music file: + * - true: Replace. Users can only hear music. + * - false: Do not replace. Users can hear both music and audio collected by + * the microphone. + * @param 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 the + * music file once. + * - `-1`: Play the music in an indefinite loop. + * @param startPos The playback position (ms) of the music file. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int startAudioMixing(const char* filePath, bool loopback, bool replace, int cycle, int startPos) = 0; + /** + * Sets the playback speed of the current music file. + * + * @since v3.5.1 + * + * @note Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" [2/2] + * and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + * + * @param speed The playback speed. Agora recommends that you limit this value to between 50 and 400, defined as follows: + * - 50: Half the original speed. + * - 100: The original speed. + * - 400: 4 times the original speed. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int setAudioMixingPlaybackSpeed(int speed) = 0; /** Stops playing and mixing the music file. Call this method when you are in a channel. @@ -6592,6 +8050,72 @@ class IRtcEngine { - < 0: Failure. */ virtual int pauseAudioMixing() = 0; + /** + * Specifies the playback track of the current music file. + * + * @since v3.5.1 + * + * After getting the audio track index of the current music file, call this + * method to specify any audio track to play. For example, if different tracks + * of a multitrack file store songs in different languages, you can call this + * method to set the language of the music file to play. + * + * @note + * - This method is for Android, iOS, and Windows only. + * - Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" [2/2] + * and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + * - 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). + * + * @param index The specified playback track. This parameter must be less than or equal to the return value + * of \ref IRtcEngine::getAudioTrackCount "getAudioTrackCount". + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int selectAudioTrack(int index) = 0; + /** + * Gets the audio track index of the current music file. + * + * @since v3.5.1 + * + * @note + * - This method is for Android, iOS, and Windows only. + * - Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" [2/2] + * and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + * - 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). + * + * @return + * - ≥ 0: The audio track index of the current music file, if this method call succeeds. + * - < 0: Failure. + */ + virtual int getAudioTrackCount() = 0; + /** + * Sets the channel mode of the current music file. + * + * @since v3.5.1 + * + * In a stereo music file, the left and right channels can store different audio data. + * According to your needs, you can set the channel mode to original mode, left channel mode, + * right channel mode, or mixed channel mode. For example, in the KTV scenario, the left + * channel of the music file stores the musical accompaniment, and the right channel + * stores the singing voice. If you only need to listen to the accompaniment, call this + * method to set the channel mode of the music file to left channel mode; if you need to + * listen to the accompaniment and the singing voice at the same time, call this method + * to set the channel mode to mixed channel mode. + * + * @note + * - Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" [2/2] + * and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + * - This method only applies to stereo audio files. + * + * @param mode The channel mode. See \ref agora::media::AUDIO_MIXING_DUAL_MONO_MODE "AUDIO_MIXING_DUAL_MONO_MODE". + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int setAudioMixingDualMonoMode(agora::media::AUDIO_MIXING_DUAL_MONO_MODE mode) = 0; /** Resumes playing and mixing the music file. Call this method when you are in a channel. @@ -6625,8 +8149,8 @@ class IRtcEngine { /** Adjusts the volume during audio mixing. @note - - Calling this method does not affect the volume of audio effect file playback invoked by the \ref agora::rtc::IRtcEngine::playEffect "playEffect" method. - - Call this method after calling \ref IRtcEngine::startAudioMixing "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + - Calling this method does not affect the volume of audio effect file playback invoked by the \ref IRtcEngine::playEffect(int,const char*,int,double,double,int,bool,int) "playEffect" method. + - Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. @param volume Audio mixing volume. The value ranges between 0 and 100 (default). @@ -6637,7 +8161,7 @@ class IRtcEngine { virtual int adjustAudioMixingVolume(int volume) = 0; /** Adjusts the audio mixing volume for local playback. - @note Call this method after calling \ref IRtcEngine::startAudioMixing "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + @note Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. @param volume Audio mixing volume for local playback. The value ranges between 0 and 100 (default). @@ -6646,13 +8170,13 @@ class IRtcEngine { - < 0: Failure. */ virtual int adjustAudioMixingPlayoutVolume(int volume) = 0; - /** Retrieves the audio mixing volume for local playback. + /** Gets the audio mixing volume for local playback. This method helps troubleshoot audio volume related issues. @note - Call this method when you are in a channel. - - Call this method after calling \ref IRtcEngine::startAudioMixing "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + - Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. @return - ≥ 0: The audio mixing volume, if this method call succeeds. The value range is [0,100]. @@ -6661,7 +8185,7 @@ class IRtcEngine { virtual int getAudioMixingPlayoutVolume() = 0; /** Adjusts the audio mixing volume for publishing (for remote users). - @note Call this method after calling \ref IRtcEngine::startAudioMixing "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + @note Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. @param volume Audio mixing volume for publishing. The value ranges between 0 and 100 (default). @@ -6670,13 +8194,13 @@ class IRtcEngine { - < 0: Failure. */ virtual int adjustAudioMixingPublishVolume(int volume) = 0; - /** Retrieves the audio mixing volume for publishing. + /** Gets the audio mixing volume for publishing. This method helps troubleshoot audio volume related issues. @note - Call this method when you are in a channel. - - Call this method after calling \ref IRtcEngine::startAudioMixing "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + - Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. @return - ≥ 0: The audio mixing volume for publishing, if this method call succeeds. The value range is [0,100]. @@ -6684,44 +8208,34 @@ class IRtcEngine { */ virtual int getAudioMixingPublishVolume() = 0; - /** Retrieves the duration (ms) of the music file. - @deprecated Deprecated from v3.4.0. Use the following methods instead: - \ref IRtcEngine::getAudioMixingDuration(const char* filePath = NULL) - @note - - Call this method when you are in a channel. - - Call this method after calling \ref IRtcEngine::startAudioMixing "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. - - @return - - ≥ 0: The audio mixing duration, if this method call succeeds. - - < 0: Failure. - */ - virtual int getAudioMixingDuration() = 0; - /** Retrieves the duration (ms) of the music file. - - @note - - Call this method when you are in a channel. - - Call this method after calling \ref IRtcEngine::startAudioMixing "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. - @param filePath - - Return the file length while it is being played - @return - - ≥ 0: The audio mixing duration, if this method call succeeds. - - < 0: Failure. + /** Gets the duration (ms) of the music file. + * + * @deprecated This method is deprecated as of v3.5.1. Use \ref IRtcEngine::getAudioFileInfo "getAudioFileInfo" instead. + * + * @note + * - Call this method when you are in a channel. + * - Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" + * and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + * + * @return + * - ≥ 0: The audio mixing duration, if this method call succeeds. + * - < 0: Failure. */ - virtual int getAudioMixingDuration(const char* filePath) = 0; - /** Retrieves the playback position (ms) of the music file. - - @note - - Call this method when you are in a channel. - - Call this method after calling \ref IRtcEngine::startAudioMixing "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. - - @return - - ≥ 0: The current playback position of the audio mixing, if this method call succeeds. - - < 0: Failure. + virtual int getAudioMixingDuration() AGORA_DEPRECATED_ATTRIBUTE = 0; + /** Gets the playback position (ms) of the music file. + * + * @note + * - Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + * - If you need to call `getAudioMixingCurrentPosition` multiple times, ensure that the call interval is longer than 500 ms. + * + * @return + * - ≥ 0: The current playback position (ms) of the music file, if this method call succeeds. 0 represents that the current music file does not start playing. + * - < 0: Failure. */ virtual int getAudioMixingCurrentPosition() = 0; /** Sets the playback position of the music file to a different starting position (the default plays from the beginning). - @note Call this method after calling \ref IRtcEngine::startAudioMixing "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + @note Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. @param pos The playback starting position (ms) of the music file. @@ -6735,7 +8249,7 @@ class IRtcEngine { * * When a local music file is mixed with a local human voice, call this method to set the pitch of the local music file only. * - * @note Call this method after calling \ref IRtcEngine::startAudioMixing "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + * @note Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. * * @param pitch Sets the pitch of the local music file by chromatic scale. The default value is 0, * which means keeping the original pitch. The value ranges from -12 to 12, and the pitch value between @@ -6747,11 +8261,11 @@ class IRtcEngine { * - < 0: Failure. */ virtual int setAudioMixingPitch(int pitch) = 0; - /** Retrieves the volume of the audio effects. + /** Gets the volume of the audio effects. The value ranges between 0.0 and 100.0. - @note Ensure that this method is called after \ref IRtcEngine::playEffect "playEffect". + @note Ensure that this method is called after \ref IRtcEngine::playEffect(int,const char*,int,double,double,int,bool,int) "playEffect" . @return - ≥ 0: Volume of the audio effects, if this method call succeeds. @@ -6761,7 +8275,7 @@ class IRtcEngine { virtual int getEffectsVolume() = 0; /** Sets the volume of the audio effects. - @note Ensure that this method is called after \ref IRtcEngine::playEffect "playEffect". + @note Ensure that this method is called after \ref IRtcEngine::playEffect(int,const char*,int,double,double,int,bool,int) "playEffect" . @param volume Sets the volume of the audio effects. The value ranges between 0 and 100 (default). @@ -6772,7 +8286,7 @@ class IRtcEngine { virtual int setEffectsVolume(int volume) = 0; /** Sets the volume of a specified audio effect. - @note Ensure that this method is called after \ref IRtcEngine::playEffect "playEffect". + @note Ensure that this method is called after \ref IRtcEngine::playEffect(int,const char*,int,double,double,int,bool,int) "playEffect" . @param soundId ID of the audio effect. Each audio effect has a unique ID. @param volume Sets the volume of the specified audio effect. The value ranges between 0 and 100 (default). @@ -6808,72 +8322,98 @@ class IRtcEngine { */ virtual int enableFaceDetection(bool enable) = 0; #endif - /** Plays a specified local or online audio effect file. - @deprecated Deprecated from v3.4.0 Use the following methods instead: - - \ref IRtcEngine::playEffect(int soundId, const char* filePath, int loopCount, double pitch, double pan, int gain, bool publish = false, int startPos = 0) - - This method allows you to set the loop count, pitch, pan, and gain of the audio effect file, as well as whether the remote user can hear the audio effect. - - To play multiple audio effect files simultaneously, call this method multiple times with different soundIds and filePaths. We recommend playing no more than three audio effect files at the same time. - - @note - - If the audio effect is preloaded into the memory through the \ref IRtcEngine::preloadEffect "preloadEffect" method, the value of @p soundID must be the same as that in the *preloadEffect* method. - - Playing multiple online audio effect files simultaneously is not supported on macOS and Windows. - - Ensure that you call this method after joining a channel. - - @param soundId ID of the specified audio effect. Each audio effect has a unique ID. - @param filePath Specifies the absolute path (including the suffixes of the filename) to the local audio effect file or the URL of the online audio effect file, for example, c:/music/audio.mp4. Supported audio formats: mp3, mp4, m4a, aac, 3gp, mkv and wav. - @param loopCount Sets the number of times the audio effect loops: - - 0: Play the audio effect once. - - 1: Play the audio effect twice. - - -1: Play the audio effect in an indefinite loop until the \ref IRtcEngine::stopEffect "stopEffect" or \ref IRtcEngine::stopAllEffects "stopAllEffects" method is called. - @param pitch Sets the pitch of the audio effect. The value ranges between 0.5 and 2. The default value is 1 (no change to the pitch). The lower the value, the lower the pitch. - @param pan Sets the spatial position of the audio effect. The value ranges between -1.0 and 1.0: - - 0.0: The audio effect displays ahead. - - 1.0: The audio effect displays to the right. - - -1.0: The audio effect displays to the left. - @param gain Sets the volume of the audio effect. The value ranges between 0 and 100 (default). The lower the value, the lower the volume of the audio effect. - @param publish Sets whether or not to publish the specified audio effect to the remote stream: - - true: The locally played audio effect is published to the Agora Cloud and the remote users can hear it. - - false: The locally played audio effect is not published to the Agora Cloud and the remote users cannot hear it. - @return - - 0: Success. - - < 0: Failure. + * + * @deprecated Deprecated from v3.4.0. Use + * \ref IRtcEngine::playEffect(int,const char*,int,double,double,int,bool,int) "playEffect" [2/2] instead. + * + * This method allows you to set the loop count, pitch, pan, and gain of the audio effect file, as well as whether the remote user can hear the audio effect. + * + * To play multiple audio effect files simultaneously, call this method multiple times with different soundIds and filePaths. We recommend playing no more than three audio effect files at the same time. + * + * @note + * - If the audio effect is preloaded into the memory through the \ref IRtcEngine::preloadEffect "preloadEffect" method, the value of @p soundID must be the same as that in the *preloadEffect* method. + * - Playing multiple online audio effect files simultaneously is not supported on macOS and Windows. + * - Ensure that you call this method after joining a channel. + * - For the audio file formats supported by this method, see [What formats of audio files does the Agora RTC SDK support](https://docs.agora.io/en/faq/audio_format). + * + * @param soundId ID of the specified audio effect. Each audio effect has a unique ID. + * @param filePath The absolute path or URL address (including the filename extensions) + * of the music file. For example: `C:\music\audio.mp4`. + * When you access a local file on Android, Agora recommends passing a URI address or the path starts + * with `/assets/` in this parameter. + * @param loopCount Sets the number of times the audio effect loops: + * - 0: Play the audio effect once. + * - 1: Play the audio effect twice. + * - -1: Play the audio effect in an indefinite loop until the \ref IRtcEngine::stopEffect "stopEffect" or \ref IRtcEngine::stopAllEffects "stopAllEffects" method is called. + * @param pitch Sets the pitch of the audio effect. The value ranges between 0.5 and 2. The default value is 1 (no change to the pitch). The lower the value, the lower the pitch. + * @param pan Sets the spatial position of the audio effect. The value ranges between -1.0 and 1.0: + * - 0.0: The audio effect displays ahead. + * - 1.0: The audio effect displays to the right. + * - -1.0: The audio effect displays to the left. + * @param gain Sets the volume of the audio effect. The value ranges between 0 and 100 (default). The lower the value, the lower the volume of the audio effect. + * @param publish Sets whether to publish the specified audio effect to the remote stream: + * - true: The locally played audio effect is published to the Agora Cloud and the remote users can hear it. + * - false: The locally played audio effect is not published to the Agora Cloud and the remote users cannot hear it. + * @return + * - 0: Success. + * - < 0: Failure. */ - virtual int playEffect(int soundId, const char* filePath, int loopCount, double pitch, double pan, int gain, bool publish = false) = 0; - /** Plays a specified local or online audio effect file. - - This method allows you to set the loop count, pitch, pan, and gain of the audio effect file, as well as whether the remote user can hear the audio effect. - - To play multiple audio effect files simultaneously, call this method multiple times with different soundIds and filePaths. We recommend playing no more than three audio effect files at the same time. - - @note - - If the audio effect is preloaded into the memory through the \ref IRtcEngine::preloadEffect "preloadEffect" method, the value of @p soundID must be the same as that in the *preloadEffect* method. - - Playing multiple online audio effect files simultaneously is not supported on macOS and Windows. - - Ensure that you call this method after joining a channel. - - @param soundId ID of the specified audio effect. Each audio effect has a unique ID. - @param filePath Specifies the absolute path (including the suffixes of the filename) to the local audio effect file or the URL of the online audio effect file, for example, c:/music/audio.mp4. Supported audio formats: mp3, mp4, m4a, aac, 3gp, mkv and wav. - @param loopCount Sets the number of times the audio effect loops: - - 0: Play the audio effect once. - - 1: Play the audio effect twice. - - -1: Play the audio effect in an indefinite loop until the \ref IRtcEngine::stopEffect "stopEffect" or \ref IRtcEngine::stopAllEffects "stopAllEffects" method is called. - @param pitch Sets the pitch of the audio effect. The value ranges between 0.5 and 2. The default value is 1 (no change to the pitch). The lower the value, the lower the pitch. - @param pan Sets the spatial position of the audio effect. The value ranges between -1.0 and 1.0: - - 0.0: The audio effect displays ahead. - - 1.0: The audio effect displays to the right. - - -1.0: The audio effect displays to the left. - @param gain Sets the volume of the audio effect. The value ranges between 0 and 100 (default). The lower the value, the lower the volume of the audio effect. - @param publish Sets whether or not to publish the specified audio effect to the remote stream: - - true: The locally played audio effect is published to the Agora Cloud and the remote users can hear it. - - false: The locally played audio effect is not published to the Agora Cloud and the remote users cannot hear it. - @param startPos Set the play position when call this API - - Min 0, start play a url/file from start - - max value is the file length. the unit is ms - @return - - 0: Success. - - < 0: Failure. + virtual int playEffect(int soundId, const char* filePath, int loopCount, double pitch, double pan, int gain, bool publish = false) AGORA_DEPRECATED_ATTRIBUTE = 0; + /** + * Plays a specified local or online audio effect file. + * + * @since v3.4.0 + * + * To play multiple audio effect files at the same time, call this method + * multiple times with different `soundId` and `filePath` values. For the + * best user experience, Agora recommends playing no more than three audio + * effect files at the same time. + * + * After completing playing an audio effect file, the SDK triggers the + * \ref IRtcEngineEventHandler::onAudioEffectFinished "onAudioEffectFinished" + * callback. + * + * @note + * - Call this method after joining a channel. + * - For the audio file formats supported by this method, see [What formats of audio files does the Agora RTC SDK support](https://docs.agora.io/en/faq/audio_format). + * + * @param soundId Audio effect ID. The ID of each audio effect file is + * unique. If you preloaded an audio effect into memory by calling + * \ref IRtcEngine::preloadEffect "preloadEffect", ensure that this + * parameter is set to the same value as in `preloadEffect`. + * @param filePath The absolute path or URL address (including the filename extensions) + * of the music file. For example: `C:\music\audio.mp4`. + * If you preloaded an audio effect into memory by calling + * \ref IRtcEngine::preloadEffect "preloadEffect", ensure that this + * parameter is set to the same value as in `preloadEffect`. + * When you access a local file on Android, Agora recommends passing a URI address or the path starts + * with `/assets/` in this parameter. + * + * @param loopCount The number of times the audio effect loops: + * - ≥ 0: The number of loops. For example, `1` means loop one time, + * which means play the audio effect two times in total. + * - `-1`: Play the audio effect in an indefinite loop. + * @param pitch The pitch of the audio effect. The range is 0.5 to 2.0. + * The default value is 1.0, which means the original pitch. The lower the + * value, the lower the pitch. + * @param pan The spatial position of the audio effect. The range is `-1.0` + * to `1.0`. For example: + * - `-1.0`: The audio effect occurs on the left. + * - `0.0`: The audio effect occurs in the front. + * - `1.0`: The audio effect occurs on the right. + * @param gain The volume of the audio effect. The range is 0.0 to 100.0. + * The default value is 100.0, which means the original volume. The smaller + * the value, the less the gain. + * @param publish Whether to publish the audio effect to the remote users: + * - true: Publish. Both the local user and remote users can hear the audio + * effect. + * - false: Do not publish. Only the local user can hear the audio effect. + * @param startPos The playback position (ms) of the audio effect file. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int playEffect(int soundId, const char* filePath, int loopCount, double pitch, double pan, int gain, bool publish, int startPos) = 0; /** Stops playing a specified audio effect. @@ -6894,19 +8434,20 @@ class IRtcEngine { virtual int stopAllEffects() = 0; /** Preloads a specified audio effect file into the memory. - - @note This method does not support online audio effect files. - - To ensure smooth communication, limit the size of the audio effect file. We recommend using this method to preload the audio effect before calling the \ref IRtcEngine::joinChannel "joinChannel" method. - - Supported audio formats: mp3, aac, m4a, 3gp, and wav. - - @param soundId ID of the audio effect. Each audio effect has a unique ID. - @param filePath Pointer to the absolute path of the audio effect file. - - @return - - 0: Success. - - < 0: Failure. + * + * To ensure smooth communication, limit the size of the audio effect file. We recommend using this method to preload the audio effect before calling the \ref IRtcEngine::joinChannel "joinChannel" method. + * + * @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). + * + * @param soundId ID of the audio effect. Each audio effect has a unique ID. + * @param filePath The absolute path or URL address (including the filename extensions) + * of the music file. For example: `C:\music\audio.mp4`. + * When you access a local file on Android, Agora recommends passing a URI address or the path starts + * with `/assets/` in this parameter. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int preloadEffect(int soundId, const char* filePath) = 0; /** Releases a specified preloaded audio effect from the memory. @@ -6947,20 +8488,106 @@ class IRtcEngine { - < 0: Failure. */ virtual int resumeAllEffects() = 0; - - virtual int getEffectDuration(const char* filePath) = 0; - - virtual int setEffectPosition(int soundId, int pos) = 0; - - virtual int getEffectCurrentPosition(int soundId) = 0; - + /** + * Gets the duration of the audio effect file. + * + * @since v3.4.0 + * + * @note + * - Call this method after joining a channel. + * - For the audio file formats supported by this method, see [What formats of audio files does the Agora RTC SDK support](https://docs.agora.io/en/faq/audio_format). + * + * @param filePath The absolute path or URL address (including the filename extensions) + * of the music file. For example: `C:\music\audio.mp4`. + * When you access a local file on Android, Agora recommends passing a URI address or the path starts + * with `/assets/` in this parameter. + * + * @return + * - ≥ 0: A successful method call. Returns the total duration (ms) of + * the specified audio effect file. + * - < 0: Failure. + * - `-22(ERR_RESOURCE_LIMITED)`: Cannot find the audio effect file. Please + * set a correct `filePath`. + */ + virtual int getEffectDuration(const char* filePath) = 0; + /** + * Sets the playback position of an audio effect file. + * + * @since v3.4.0 + * + * After a successful setting, the local audio effect file starts playing at the specified position. + * + * @note Call this method after \ref IRtcEngine::playEffect(int,const char*,int,double,double,int,bool,int) "playEffect" . + * + * @param soundId Audio effect ID. Ensure that this parameter is set to the + * same value as in \ref IRtcEngine::playEffect(int,const char*,int,double,double,int,bool,int) "playEffect" . + * @param pos The playback position (ms) of the audio effect file. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `-22(ERR_RESOURCE_LIMITED)`: Cannot find the audio effect file. Please + * set a correct `soundId`. + */ + virtual int setEffectPosition(int soundId, int pos) = 0; + /** + * Gets the playback position of the audio effect file. + * + * @since v3.4.0 + * + * @note Call this method after \ref IRtcEngine::playEffect(int,const char*,int,double,double,int,bool,int) "playEffect" . + * + * @param soundId Audio effect ID. Ensure that this parameter is set to the + * same value as in \ref IRtcEngine::playEffect(int,const char*,int,double,double,int,bool,int) "playEffect" . + * + * @return + * - ≥ 0: A successful method call. Returns the playback position (ms) of + * the specified audio effect file. + * - < 0: Failure. + * - `-22(ERR_RESOURCE_LIMITED)`: Cannot find the audio effect file. Please + * set a correct `soundId`. + */ + virtual int getEffectCurrentPosition(int soundId) = 0; + + /** Gets the information of a specified audio file. + * + * @since v3.5.1 + * + * After calling this method successfully, the SDK triggers the + * \ref IRtcEngineEventHandler::onRequestAudioFileInfo "onRequestAudioFileInfo" + * callback to report the information of an audio file, such as audio duration. + * You can call this method multiple times to get the information of multiple audio files. + * + * @note + * - Call this method after joining a channel. + * - For the audio file formats supported by this method, see [What formats of audio files does the Agora RTC SDK support](https://docs.agora.io/en/faq/audio_format). + * + * @param filePath The file path: + * - Windows: The absolute path or URL address (including the filename extensions) of + * the audio file. For example: `C:\music\audio.mp4`. + * - Android: The file path, including the filename extensions. To access an online file, + * Agora supports using a URL address; to access a local file, Agora supports using a URI + * address, an absolute path, or a path that starts with `/assets/`. You might encounter + * permission issues if you use an absolute path to access a local file, so Agora recommends + * using a URI address instead. For example: `content://com.android.providers.media.documents/document/audio%3A14441`. + * - iOS or macOS: The absolute path or URL address (including the filename extensions) of the audio file. + * For example: `/var/mobile/Containers/Data/audio.mp4`. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int getAudioFileInfo(const char* filePath) = 0; + /** Enables or disables deep-learning noise reduction. + * + * @since v3.3.0 * * The SDK enables traditional noise reduction mode by default to reduce most of the stationary background noise. * If you need to reduce most of the non-stationary background noise, Agora recommends enabling deep-learning * noise reduction as follows: * - * 1. Integrate the dynamical library under the libs folder to your project: + * 1. Ensure that the dynamical library is integrated in your project: * - Android: `libagora_ai_denoise_extension.so` * - iOS: `AgoraAIDenoiseExtension.xcframework` * - macOS: `AgoraAIDenoiseExtension.framework` @@ -7000,7 +8627,7 @@ class IRtcEngine { Ensure that you call this method before joinChannel to enable stereo panning for remote users so that the local user can track the position of a remote user by calling \ref agora::rtc::IRtcEngine::setRemoteVoicePosition "setRemoteVoicePosition". - @param enabled Sets whether or not to enable stereo panning for remote users: + @param enabled Sets whether to enable stereo panning for remote users: - true: enables stereo panning. - false: disables stereo panning. @@ -7053,18 +8680,21 @@ class IRtcEngine { - < 0: Failure. */ virtual int setLocalVoiceEqualization(AUDIO_EQUALIZATION_BAND_FREQUENCY bandFrequency, int bandGain) = 0; - /** Sets the local voice reverberation. - - v2.4.0 adds the \ref agora::rtc::IRtcEngine::setLocalVoiceReverbPreset "setLocalVoiceReverbPreset" method, a more user-friendly method for setting the local voice reverberation. You can use this method to set the local reverberation effect, such as pop music, R&B, rock music, and hip-hop. - - @note You can call this method either before or after joining a channel. - - @param reverbKey Sets the reverberation key. See #AUDIO_REVERB_TYPE. - @param value Sets the value of the reverberation key. - - @return - - 0: Success. - - < 0: Failure. + /** Sets the local voice reverberation. + * + * As of v3.2.0, the SDK provides a more convenient method + * \ref IRtcEngine::setAudioEffectPreset "setAudioEffectPreset", which + * directly implements the popular music, R&B music, KTV and other preset + * reverb effects. + * + * @note You can call this method either before or after joining a channel. + * + * @param reverbKey Sets the reverberation key. See #AUDIO_REVERB_TYPE. + * @param value Sets the value of the reverberation key. See #AUDIO_REVERB_TYPE. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int setLocalVoiceReverb(AUDIO_REVERB_TYPE reverbKey, int value) = 0; /** Sets the local voice changer option. @@ -7089,17 +8719,14 @@ class IRtcEngine { - Do not use this method with \ref IRtcEngine::setLocalVoiceReverbPreset "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. - @param voiceChanger Sets the local voice changer option. The default value is #VOICE_CHANGER_OFF, which means the original voice. See details in #VOICE_CHANGER_PRESET - Gender-based beatification effect works best only when assigned a proper gender: - - For male: #GENERAL_BEAUTY_VOICE_MALE_MAGNETIC - - For female: #GENERAL_BEAUTY_VOICE_FEMALE_FRESH or #GENERAL_BEAUTY_VOICE_FEMALE_VITALITY - Failure to do so can lead to voice distortion. + @param voiceChanger Sets the local voice changer option. The default value is `VOICE_CHANGER_OFF`, + which means the original voice. See details in #VOICE_CHANGER_PRESET. @return - 0: Success. - < 0: Failure. Check if the enumeration is properly set. */ - virtual int setLocalVoiceChanger(VOICE_CHANGER_PRESET voiceChanger) = 0; + virtual int setLocalVoiceChanger(VOICE_CHANGER_PRESET voiceChanger) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Sets the local voice reverberation option, including the virtual stereo. * * @deprecated Deprecated from v3.2.0. Use \ref IRtcEngine::setAudioEffectPreset "setAudioEffectPreset" or @@ -7125,7 +8752,7 @@ class IRtcEngine { * - 0: Success. * - < 0: Failure. */ - virtual int setLocalVoiceReverbPreset(AUDIO_REVERB_PRESET reverbPreset) = 0; + virtual int setLocalVoiceReverbPreset(AUDIO_REVERB_PRESET reverbPreset) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Sets an SDK preset voice beautifier effect. * * @since v3.2.0 @@ -7372,8 +8999,8 @@ class IRtcEngine { * - 0: Success. * - < 0: Failure. */ - virtual int setLogFile(const char* filePath) = 0; - + virtual int setLogFile(const char* filePath) AGORA_DEPRECATED_ATTRIBUTE = 0; + /// @cond /** Specifies an SDK external log writer. The external log writer output all SDK operations during runtime if it exist. @@ -7398,6 +9025,7 @@ class IRtcEngine { - < 0: Failure. */ virtual int releaseLogWriter() = 0; + /// @endcond /** Sets the output log level of the SDK. @deprecated This method is deprecated from v3.3.0. Use `logConfig` in the \ref IRtcEngine::initialize "initialize" method instead. @@ -7415,7 +9043,7 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int setLogFilter(unsigned int filter) = 0; + virtual int setLogFilter(unsigned int filter) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Sets the size of a log file that the SDK outputs. * * @deprecated This method is deprecated from v3.3.0. Use `logConfig` in the \ref IRtcEngine::initialize "initialize" method instead. @@ -7437,7 +9065,8 @@ class IRtcEngine { * - 0: Success. * - < 0: Failure. */ - virtual int setLogFileSize(unsigned int fileSizeInKBytes) = 0; + virtual int setLogFileSize(unsigned int fileSizeInKBytes) AGORA_DEPRECATED_ATTRIBUTE = 0; + /// @cond /** Uploads all SDK log files. * * @since v3.3.0 @@ -7461,6 +9090,7 @@ class IRtcEngine { * - -12(ERR_TOO_OFTEN): The call frequency exceeds the limit. */ virtual int uploadLogFile(agora::util::AString& requestId) = 0; + /// @endcond /** @deprecated This method is deprecated, use the \ref IRtcEngine::setLocalRenderMode(RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode) "setLocalRenderMode" [2/2] method instead. Sets the local video display mode. @@ -7472,7 +9102,7 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int setLocalRenderMode(RENDER_MODE_TYPE renderMode) = 0; + virtual int setLocalRenderMode(RENDER_MODE_TYPE renderMode) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Updates the display mode of the local video view. @since v3.0.0 @@ -7503,7 +9133,7 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int setRemoteRenderMode(uid_t userId, RENDER_MODE_TYPE renderMode) = 0; + virtual int setRemoteRenderMode(uid_t userId, RENDER_MODE_TYPE renderMode) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Updates the display mode of the video view of a remote user. @since v3.0.0 @@ -7537,8 +9167,8 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int setLocalVideoMirrorMode(VIDEO_MIRROR_MODE_TYPE mirrorMode) = 0; - /** Sets the stream mode to the single-stream (default) or dual-stream mode. (`LIVE_BROADCASTING` only.) + virtual int setLocalVideoMirrorMode(VIDEO_MIRROR_MODE_TYPE mirrorMode) AGORA_DEPRECATED_ATTRIBUTE = 0; + /** Sets the stream mode to the single-stream (default) or dual-stream mode. If the dual-stream mode is enabled, the receiver can choose to receive the high stream (high-resolution and high-bitrate video stream), or the low stream (low-resolution and low-bitrate video stream). @@ -7547,6 +9177,10 @@ class IRtcEngine { @param enabled Sets the stream mode: - true: Dual-stream mode. - false: Single-stream mode. + + @return + - 0: Success. + - < 0: Failure. */ virtual int enableDualStreamMode(bool enabled) = 0; /** Sets the external audio source. @@ -7574,7 +9208,7 @@ class IRtcEngine { * it, and play it with the audio effects that you want. * * @note - * - Once you enable the external audio sink, the app will not retrieve any + * - Once you enable the external audio sink, the app will not get any * audio data from the * \ref agora::media::IAudioFrameObserver::onPlaybackAudioFrame "onPlaybackAudioFrame" callback. * - Ensure that you call this method before joining a channel. @@ -7644,62 +9278,71 @@ class IRtcEngine { - < 0: Failure. */ virtual int setMixedAudioFrameParameters(int sampleRate, int samplesPerCall) = 0; - /** Adjusts the capturing signal volume. - - @note You can call this method either before or after joining a channel. - - @param volume Volume. To avoid echoes and - improve call quality, Agora recommends setting the value of volume between - 0 and 100. If you need to set the value higher than 100, contact - support@agora.io first. - - 0: Mute. - - 100: Original volume. - - - @return - - 0: Success. - - < 0: Failure. + /** Adjusts the volume of the signal captured by the microphone. + * + * @note You can call this method either before or after joining a channel. + * + * @param volume The volume of the signal captured by the microphone. + * The value ranges between 0 and 400, including the following: + * - 0: Mute. + * - 100: (Default) Original volume. + * - 400: Four times the original volume with signal-clipping protection. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int adjustRecordingSignalVolume(int volume) = 0; /** Adjusts the playback signal volume of all remote users. - - @note - - This method adjusts the playback volume that is the mixed volume of all remote users. - - You can call this method either before or after joining a channel. - - (Since v2.3.2) To mute the local audio playback, call both the `adjustPlaybackSignalVolume` and \ref IRtcEngine::adjustAudioMixingVolume "adjustAudioMixingVolume" methods and set the volume as `0`. - - @param volume The playback volume of all remote users. To avoid echoes and - improve call quality, Agora recommends setting the value of volume between - 0 and 100. If you need to set the value higher than 100, contact - support@agora.io first. - - 0: Mute. - - 100: Original volume. - - @return - - 0: Success. - - < 0: Failure. + * + * @note + * - This method adjusts the playback volume that is the mixed volume of all + * remote users. + * - You can call this method either before or after joining a channel. + * - (Since v2.3.2) To mute the local audio playback, call both the + * `adjustPlaybackSignalVolume` and + * \ref IRtcEngine::adjustAudioMixingVolume "adjustAudioMixingVolume" + * methods and set the volume as `0`. + * + * @param volume The playback volume. The value ranges between 0 and 400, + * including the following: + * - 0: Mute. + * - 100: (Default) Original volume. + * - 400: Four times the original volume with signal-clipping protection. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int adjustPlaybackSignalVolume(int volume) = 0; - /** Adjusts the loopback signal volume. - - @note You can call this method either before or after joining a channel. - - @param volume Volume. To avoid quality issues, Agora recommends setting the value of volume - between 0 and 100. If you need to set the value higher than 100, contact support@agora.io first. - - 0: Mute. - - 100: Original volume. - - @return - - 0: Success. - - < 0: Failure. - */ + /** + * Adjusts the volume of the signal captured by the sound card. + * + * @since v3.4.0 + * + * After calling enableLoopbackRecording to enable loopback audio capturing, + * you can call this method to adjust the volume of the signal captured by + * the sound card. + * + * @note This method applies to Windows and macOS only. + * + * @param volume The volume of the signal captured by the sound card. + * The value ranges between 0 and 400, including the following: + * - 0: Mute. + * - 100: (Default) Original volume. + * - 400: Four times the original volume with signal-clipping protection. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ virtual int adjustLoopbackRecordingSignalVolume(int volume) = 0; /** @deprecated This method is deprecated. As of v3.0.0, the Native SDK automatically enables interoperability with the Web SDK, so you no longer need to call this method. Enables interoperability with the Agora Web SDK. @note - - This method applies only to the `LIVE_BROADCASTING` profile. In the `COMMUNICATION` profile, interoperability with the Agora Web SDK is enabled by default. + - This method applies to the `LIVE_BROADCASTING` profile. In the `COMMUNICATION` profile, interoperability with the Agora Web SDK is enabled by default. - If the channel has Web SDK users, ensure that you call this method, or the video of the Native user will be a black screen for the Web user. @param enabled Sets whether to enable/disable interoperability with the Agora Web SDK: @@ -7710,7 +9353,7 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int enableWebSdkInteroperability(bool enabled) = 0; + virtual int enableWebSdkInteroperability(bool enabled) AGORA_DEPRECATED_ATTRIBUTE = 0; // only for live broadcast /** **DEPRECATED** Sets the preferences for the high-quality video. (`LIVE_BROADCASTING` only). @@ -7793,60 +9436,56 @@ class IRtcEngine { */ virtual int switchCamera(CAMERA_DIRECTION direction) = 0; /// @endcond - /** Sets the default audio playback route. - - This method sets whether the received audio is routed to the earpiece or speakerphone by default before joining a channel. - If a user does not call this method, the audio is routed to the earpiece by default. If you need to change the default audio route after joining a channel, call the \ref IRtcEngine::setEnableSpeakerphone "setEnableSpeakerphone" method. - - The default setting for each profile: - - `COMMUNICATION`: In a voice call, the default audio route is the earpiece. In a video call, the default audio route is the speakerphone. If a user who is in the `COMMUNICATION` profile calls - the \ref IRtcEngine.disableVideo "disableVideo" method or if the user calls - the \ref IRtcEngine.muteLocalVideoStream "muteLocalVideoStream" and - \ref IRtcEngine.muteAllRemoteVideoStreams "muteAllRemoteVideoStreams" methods, the - default audio route switches back to the earpiece automatically. - - `LIVE_BROADCASTING`: Speakerphone. - - @note - - This method is for Android and iOS only. - - This method is applicable only to the `COMMUNICATION` profile. - - For iOS, this method only works in a voice call. - - Call this method before calling the \ref IRtcEngine::joinChannel "joinChannel" method. - - @param defaultToSpeaker Sets the default audio route: - - true: Route the audio to the speakerphone. If the playback device connects to the earpiece or Bluetooth, the audio cannot be routed to the speakerphone. - - false: (Default) Route the audio to the earpiece. If a headset is plugged in, the audio is routed to the headset. - - @return - - 0: Success. - - < 0: Failure. + /** + * Sets the default audio route. + * + * If the default audio route of the SDK (see *Set the Audio Route*) cannot meet your requirements, you can + * call this method to switch the default audio route. After successfully switching the audio route, the SDK + * triggers the \ref IRtcEngineEventHandler::onAudioRouteChanged "onAudioRouteChanged" callback to indicate the changes. + * + * @note + * - This method applies to Android and iOS only. + * - Call this method before calling \ref IRtcEngine::joinChannel "joinChannel". If you need to switch the audio + * route after joining a channel, call \ref IRtcEngine::setEnableSpeakerphone "setEnableSpeakerphone". + * - If the user uses an external audio playback device such as a Bluetooth or wired headset, this method does not + * take effect, and the SDK plays audio through the external device. When the user uses multiple external devices, + * the SDK plays audio through the last connected device. + * + * @param defaultToSpeaker Sets the default audio route as follows: + * - true: Set to the speakerphone. + * - false: Set to the earpiece. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int setDefaultAudioRouteToSpeakerphone(bool defaultToSpeaker) = 0; - /** Enables/Disables the audio playback route to the speakerphone. - - This method sets whether the audio is routed to the speakerphone or earpiece. - - See the default audio route explanation in the \ref IRtcEngine::setDefaultAudioRouteToSpeakerphone "setDefaultAudioRouteToSpeakerphone" method and check whether it is necessary to call this method. - - @note - - This method is for Android and iOS only. - - Ensure that you have successfully called the \ref IRtcEngine::joinChannel "joinChannel" method before calling this method. - - After calling this method, the SDK returns the \ref IRtcEngineEventHandler::onAudioRouteChanged "onAudioRouteChanged" callback to indicate the changes. - - This method does not take effect if a headset is used. - - Settings of \ref IRtcEngine::setAudioProfile "setAudioProfile" and \ref IRtcEngine::setChannelProfile "setChannelProfile" affect the call - result of `setEnableSpeakerphone`. The following are scenarios where `setEnableSpeakerphone` does not take effect: - - If you set `scenario` as `AUDIO_SCENARIO_GAME_STREAMING`, no user can change the audio playback route. - - If you set `scenario` as `AUDIO_SCENARIO_DEFAULT` or `AUDIO_SCENARIO_SHOWROOM`, the audience cannot change - the audio playback route. If there is only one broadcaster is in the channel, the broadcaster cannot change - the audio playback route either. - - If you set `scenario` as `AUDIO_SCENARIO_EDUCATION`, the audience cannot change the audio playback route. - - @param speakerOn Sets whether to route the audio to the speakerphone or earpiece: - - true: Route the audio to the speakerphone. If the playback device connects to the headset or Bluetooth, the audio cannot be routed to the speakerphone. - - false: Route the audio to the earpiece. If a headset is plugged in, the audio is routed to the headset. - - @return - - 0: Success. - - < 0: Failure. + /** + * Enables/Disables the audio route to the speakerphone. + * + * If the default audio route of the SDK (see *Set the Audio Route*) or the + * setting in \ref IRtcEngine::setDefaultAudioRouteToSpeakerphone "setDefaultAudioRouteToSpeakerphone" + * cannot meet your requirements, you can call this method to switch the current audio route. + * After successfully switching the audio route, the SDK triggers the + * \ref IRtcEngineEventHandler::onAudioRouteChanged "onAudioRouteChanged" callback to indicate the changes. + * + * This method only sets the audio route in the current channel and does not influence the default audio route. + * If the user leaves the current channel and joins another channel, the default audio route is used. + * + * @note + * - This method applies to Android and iOS only. + * - Call this method after calling joinChannel. + * - If the user uses an external audio playback device such as a Bluetooth or wired headset, this method + * does not take effect, and the SDK plays audio through the external device. When the user uses multiple external + * devices, the SDK plays audio through the last connected device. + * + * @param speakerOn Sets whether to enable the speakerphone or earpiece: + * - true: Enable the speakerphone. The audio route is the speakerphone. + * - false: Disable the speakerphone. The audio route is the earpiece. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int setEnableSpeakerphone(bool speakerOn) = 0; /** Enables in-ear monitoring (for Android and iOS only). @@ -7892,37 +9531,45 @@ class IRtcEngine { #endif #if (defined(__APPLE__) && TARGET_OS_IOS) - /** Sets the audio session’s operational restriction. - - The SDK and the app can both configure the audio session by default. The app may occasionally use other apps or third-party components to manipulate the audio session and restrict the SDK from doing so. This method allows the app to restrict the SDK’s manipulation of the audio session. - - You can call this method at any time to return the control of the audio sessions to the SDK. - - @note - - This method is for iOS only. - - This method restricts the SDK’s manipulation of the audio session. Any operation to the audio session relies solely on the app, other apps, or third-party components. - - You can call this method either before or after joining a channel. - - @param restriction The operational restriction (bit mask) of the SDK on the audio session. See #AUDIO_SESSION_OPERATION_RESTRICTION. - - @return - - 0: Success. - - < 0: Failure. + /** Sets the operational permission of the SDK on the audio session. + * + * The SDK and the app can both configure the audio session by default. If + * you need to only use the app to configure the audio session, this method + * restricts the operational permission of the SDK on the audio session. + * + * You can call this method either before or after joining a channel. Once + * you call this method to restrict the operational permission of the SDK + * on the audio session, the restriction takes effect when the SDK needs to + * change the audio session. + * + * @note + * - This method is for iOS only. + * - This method does not restrict the operational permission of the app on + * the audio session. + * + * @param restriction The operational permission of the SDK on the audio session. + * See #AUDIO_SESSION_OPERATION_RESTRICTION. This parameter is in bit mask + * format, and each bit corresponds to a permission. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int setAudioSessionOperationRestriction(AUDIO_SESSION_OPERATION_RESTRICTION restriction) = 0; #endif #if (defined(__APPLE__) && TARGET_OS_MAC && !TARGET_OS_IPHONE) || defined(_WIN32) + /** Enables loopback audio capturing. - If you enable loopback audio capturing, the output of the sound card is mixed into the audio stream sent to the other end. + If you enable loopback audio capturing, the output of the sound card is mixed into the audio stream sent to the other end. - @note You can call this method either before or after joining a channel. + @note You can call this method either before or after joining a channel. - @param enabled Sets whether to enable/disable loopback capturing. - - true: Enable loopback capturing. - - false: (Default) Disable loopback capturing. - @param deviceName Pointer to the device name of the sound card. The default value is NULL (the default sound card). + @param enabled Sets whether to enable/disable loopback capturing. + - true: Enable loopback capturing. + - false: (Default) Disable loopback capturing. + @param deviceName Pointer to the device name of the sound card. The default value is NULL (the default sound card). @note - This method is for macOS and Windows only. @@ -7930,15 +9577,50 @@ class IRtcEngine { */ virtual int enableLoopbackRecording(bool enabled, const char* deviceName = NULL) = 0; + /** + * Gets a list of shareable screens and windows. + * + * @since v3.5.2 + * + * You can call this method before sharing a screen or window to get a list of shareable screens and windows, which + * enables a user to use thumbnails in the list to easily choose a particular screen or window to share. This list + * also contains important information such as window ID and screen ID, with which you can + * call \ref IRtcEngine::startScreenCaptureByWindowId "startScreenCaptureByWindowId" or + * \ref IRtcEngine::startScreenCaptureByDisplayId "startScreenCaptureByDisplayId" to start the sharing. + * + * @note This method applies to macOS and Windows only. + * + * @param thumbSize The target size of the screen or window thumbnail. The width and height are in pixels. See SIZE. + * The SDK scales the original image to make the length of the longest side of the image the same as that of the + * target size without distorting the original image. For example, if the original image is 400 × 300 and `thumbSize` + * is 100 × 100, the actual size of the thumbnail is 100 × 75. If the target size is larger than the original size, + * the thumbnail is the original image and the SDK does not scale it. + * @param iconSize The target size of the icon corresponding to the application program. The width and height are in + * pixels. See SIZE. The SDK scales the original image to make the length of the longest side of the image the same + * as that of the target size without distorting the original image. For example, if the original image is 400 × 300 + * and `iconSize` is 100 × 100, the actual size of the icon is 100 × 75. If the target size is larger than the + * original size, the icon is the original image and the SDK does not scale it. + * @param includeScreen Whether the SDK returns screen information in addition to window information: + * - true: The SDK returns screen and window information. + * - false: The SDK returns window information only. + * + * @return IScreenCaptureSourceList + */ + virtual IScreenCaptureSourceList* getScreenCaptureSources(const SIZE& thumbSize, const SIZE& iconSize, const bool includeScreen) = 0; -#if (defined(__APPLE__) && TARGET_OS_MAC && !TARGET_OS_IPHONE) /** Shares the whole or part of a screen by specifying the display ID. * * @note - * - This method is for macOS only. + * - This method is for macOS and Windows only. * - Ensure that you call this method after joining a channel. * - * @param displayId The display ID of the screen to be shared. This parameter specifies which screen you want to share. + * @warning On Windows platforms, if the user device is connected to another display, to avoid screen sharing issues, + * use `startScreenCaptureByDisplayId` to start sharing instead of + * using \ref IRtcEngine::startScreenCaptureByScreenRect "startScreenCaptureByScreenRect". + * + * @param displayId The display ID of the screen to be shared. Use this parameter to specify which screen you want to + * share. For more information on how to get the display ID, see the advanced feature guide *Share the Screen* or get + * the display ID from `sourceId` returned by \ref IRtcEngine::getScreenCaptureSources "getScreenCaptureSources". * @param regionRect (Optional) Sets the relative location of the region to the screen. NIL means sharing the whole screen. See Rectangle. If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen. * @param 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 `videoDimension` to calculate the charges. * For details, see descriptions in ScreenCaptureParameters. @@ -7950,7 +9632,6 @@ class IRtcEngine { * - #ERR_INVALID_ARGUMENT: The argument is invalid. */ virtual int startScreenCaptureByDisplayId(unsigned int displayId, const Rectangle& regionRect, const ScreenCaptureParameters& captureParams) = 0; -#endif #if defined(_WIN32) /** Shares the whole or part of a screen by specifying the screen rect. @@ -7959,6 +9640,10 @@ class IRtcEngine { * - Ensure that you call this method after joining a channel. * - Applies to the Windows platform only. * + * @warning On Windows platforms, if the user device is connected to another display, to avoid screen sharing issues, + * use \ref IRtcEngine::startScreenCaptureByDisplayId "startScreenCaptureByDisplayId" to start sharing instead of + * using \ref IRtcEngine::startScreenCaptureByScreenRect "startScreenCaptureByScreenRect". + * * @param screenRect Sets the relative location of the screen to the virtual screen. For information on how to get screenRect, see the advanced guide *Share Screen*. * @param regionRect (Optional) Sets the relative location of the region to the screen. NULL means sharing the whole screen. See Rectangle. If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen. * @param captureParams The screen sharing encoding parameters. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. @@ -7967,7 +9652,7 @@ class IRtcEngine { * @return * - 0: Success. * - < 0: Failure: - * - #ERR_INVALID_ARGUMENT : The argument is invalid. + * - #ERR_INVALID_ARGUMENT: The argument is invalid. */ virtual int startScreenCaptureByScreenRect(const Rectangle& screenRect, const Rectangle& regionRect, const ScreenCaptureParameters& captureParams) = 0; #endif @@ -8192,10 +9877,8 @@ class IRtcEngine { - < 0: Failure. */ virtual int updateScreenCaptureRegion(const Rect* rect) = 0; - #endif -#if defined(_WIN32) /** Sets a custom video source. * * During real-time communication, the Agora SDK enables the default video input device, that is, the built-in camera to @@ -8211,9 +9894,8 @@ class IRtcEngine { * - false: The custom video source is not added to the SDK. */ virtual bool setVideoSource(IVideoSource* source) = 0; -#endif - /** Retrieves the current call ID. + /** Gets the current call ID. When a user joins a channel on a client, a @p callId is generated to identify the call from the client. Feedback methods, such as \ref IRtcEngine::rate "rate" and \ref IRtcEngine::complain "complain", must be called after the call ends to submit feedback to the SDK. @@ -8257,7 +9939,7 @@ class IRtcEngine { */ virtual int complain(const char* callId, const char* description) = 0; - /** Retrieves the SDK version number. + /** Gets the SDK version number. @param build Pointer to the build number. @return The version of the current SDK in the string format. For example, 2.3.1. @@ -8318,7 +10000,7 @@ class IRtcEngine { /** Stops the last-mile network probe test. */ virtual int stopLastmileProbeTest() = 0; - /** Retrieves the warning or error description. + /** Gets the warning or error description. @param code Warning code or error code returned in the \ref agora::rtc::IRtcEngineEventHandler::onWarning "onWarning" or \ref agora::rtc::IRtcEngineEventHandler::onError "onError" callback. @@ -8326,9 +10008,9 @@ class IRtcEngine { */ virtual const char* getErrorDescription(int code) = 0; - /** **DEPRECATED** Enables built-in encryption with an encryption password before users join a channel. + /** Enables built-in encryption with an encryption password before users join a channel. - Deprecated as of v3.1.0. Use the \ref agora::rtc::IRtcEngine::enableEncryption "enableEncryption" instead. + @deprecated Deprecated as of v3.1.0. Use the \ref agora::rtc::IRtcEngine::enableEncryption "enableEncryption" instead. All users in a channel must use the same encryption password. The encryption password is automatically cleared once a user leaves the channel. @@ -8344,9 +10026,9 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int setEncryptionSecret(const char* secret) = 0; + virtual int setEncryptionSecret(const char* secret) AGORA_DEPRECATED_ATTRIBUTE = 0; - /** **DEPRECATED** Sets the built-in encryption mode. + /** Sets the built-in encryption mode. @deprecated Deprecated as of v3.1.0. Use the \ref agora::rtc::IRtcEngine::enableEncryption "enableEncryption" instead. @@ -8368,7 +10050,7 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int setEncryptionMode(const char* encryptionMode) = 0; + virtual int setEncryptionMode(const char* encryptionMode) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Enables/Disables the built-in encryption. * @@ -8376,9 +10058,18 @@ class IRtcEngine { * * 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 a 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. + * After a user leaves the channel, the SDK automatically disables the built-in encryption. + * To re-enable the built-in encryption, call this method before the user joins the channel again. * - * @note If you enable the built-in encryption, you cannot use the RTMP or RTMPS streaming function. + * As of v3.4.5, Agora recommends using either the `AES_128_GCM2` or `AES_256_GCM2` encryption mode, + * both of which support adding a salt and are more secure. For details, see *Media Stream Encryption*. + * + * @warning All users in the same channel must use the same encryption mode, encryption key, and salt; otherwise, + * users cannot communicate with each other. + * + * @note + * - If you enable the built-in encryption, you cannot use the RTMP or RTMPS streaming function. + * - To enhance security, Agora recommends using a new key and salt every time you enable the media stream encryption. * * @param enabled Whether to enable the built-in encryption: * - true: Enable the built-in encryption. @@ -8401,7 +10092,7 @@ class IRtcEngine { @note - The size of the packet sent to the network after processing should not exceed 1200 bytes, otherwise, the packet may fail to be sent. - Ensure that both receivers and senders call this method, otherwise, you may meet undefined behaviors such as no voice and black screen. - - When you use CDN live streaming, recording or storage functions, Agora doesn't recommend calling this method. + - When you use CDN live streaming and recording functions, Agora doesn't recommend calling this method. - Call this method before joining a channel. @param observer Pointer to the registered packet observer. See IPacketObserver. @@ -8434,7 +10125,7 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int createDataStream(int* streamId, bool reliable, bool ordered) = 0; + virtual int createDataStream(int* streamId, bool reliable, bool ordered) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Creates a data stream. * * @since v3.3.0 @@ -8478,6 +10169,8 @@ class IRtcEngine { /** Publishes the local stream to a specified CDN live address. (CDN live only.) + @deprecated This method is deprecated as of v3.6.0. See [Release Notes](https://docs.agora.io/en/Interactive%20Broadcast/release_windows_video?platform=Windows) for an alternative solution. + The SDK returns the result of this method call in the \ref IRtcEngineEventHandler::onStreamPublished "onStreamPublished" callback. The \ref agora::rtc::IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onRtmpStreamingStateChanged "onRtmpStreamingStateChanged" callback on the local client to report the state of adding a local stream to the CDN. @@ -8498,10 +10191,12 @@ class IRtcEngine { - #ERR_INVALID_ARGUMENT (-2): The CDN streaming URL is NULL or has a string length of 0. - #ERR_NOT_INITIALIZED (-7): You have not initialized the RTC engine when publishing the stream. */ - virtual int addPublishStreamUrl(const char* url, bool transcodingEnabled) = 0; + virtual int addPublishStreamUrl(const char* url, bool transcodingEnabled) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Removes an RTMP or RTMPS stream from the CDN. (CDN live only.) + @deprecated This method is deprecated as of v3.6.0. See [Release Notes](https://docs.agora.io/en/Interactive%20Broadcast/release_windows_video?platform=Windows) for an alternative solution. + This method removes the CDN streaming URL (added by the \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method) from a CDN live stream. The SDK returns the result of this method call in the \ref IRtcEngineEventHandler::onStreamUnpublished "onStreamUnpublished" callback. The \ref agora::rtc::IRtcEngine::removePublishStreamUrl "removePublishStreamUrl" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onRtmpStreamingStateChanged "onRtmpStreamingStateChanged" callback on the local client to report the state of removing an RTMP or RTMPS stream from the CDN. @@ -8517,10 +10212,12 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int removePublishStreamUrl(const char* url) = 0; + virtual int removePublishStreamUrl(const char* url) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Sets the video layout and audio settings for CDN live. (CDN live only.) + @deprecated This method is deprecated as of v3.6.0. See [Release Notes](https://docs.agora.io/en/Interactive%20Broadcast/release_windows_video?platform=Windows) for an alternative solution. + The SDK triggers the \ref agora::rtc::IRtcEngineEventHandler::onTranscodingUpdated "onTranscodingUpdated" callback when you call the `setLiveTranscoding` method to update the transcoding setting. @note @@ -8536,7 +10233,104 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int setLiveTranscoding(const LiveTranscoding& transcoding) = 0; + virtual int setLiveTranscoding(const LiveTranscoding& transcoding) AGORA_DEPRECATED_ATTRIBUTE = 0; + /** + * Starts pushing media streams to a CDN without transcoding. + * + * @since v3.6.0 + * + * You can call this method to push a live audio-and-video stream to the specified CDN address. This method can push + * media streams to only one CDN address at a time, so if you need to push streams to multiple addresses, call this + * method multiple times. + * + * After you call this method, the SDK triggers the \ref IRtcEngineEventHandler::onRtmpStreamingStateChanged "onRtmpStreamingStateChanged" + * callback on the local client to report the state of the streaming. + * + * @note + * - Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in *Push Streams to CDN*. + * - Call this method after joining a channel. + * - Only hosts in the `LIVE_BROADCASTING` profile can call this method. + * - If you want to retry pushing streams after a failed push, make sure to call \ref IRtcEngine::stopRtmpStream "stopRtmpStream" first, + * then call this method to retry pushing streams; otherwise, the SDK returns the same error code as the last failed push. + * - If you want to push media streams in the RTMPS protocol to CDN, call \ref IRtcEngine::startRtmpStreamWithTranscoding "startRtmpStreamWithTranscoding" + * instead of \ref IRtcEngine::startRtmpStreamWithoutTranscoding "startRtmpStreamWithoutTranscoding". + * + * @param url The address of the CDN live streaming. The format is RTMP. The character length cannot exceed 1024 bytes. + * Special characters such as Chinese characters are not supported. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `ERR_INVALID_ARGUMENT(-2)`: url is null or the string length is 0. + * - `ERR_NOT_INITIALIZED(-7)`: The SDK is not initialized before calling this method. + */ + virtual int startRtmpStreamWithoutTranscoding(const char* url) = 0; + /** + * Starts pushing media streams to a CDN and sets the transcoding configuration. + * + * @since v3.6.0 + * + * You can call this method to push a live audio-and-video stream to the specified CDN address and set the transcoding + * configuration. This method can push media streams to only one CDN address at a time, so if you need to push streams to + * multiple addresses, call this method multiple times. + * + * After you call this method, the SDK triggers the \ref IRtcEngineEventHandler::onRtmpStreamingStateChanged "onRtmpStreamingStateChanged" + * callback on the local client to report the state of the streaming. + * + * @note + * - Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in *Push Streams to CDN*. + * - Call this method after joining a channel. + * - Only hosts in the `LIVE_BROADCASTING` profile can call this method. + * - If you want to retry pushing streams after a failed push, make sure to call \ref IRtcEngine::stopRtmpStream "stopRtmpStream" first, + * then call this method to retry pushing streams; otherwise, the SDK returns the same error code as the last failed push. + * - If you want to push media streams in the RTMPS protocol to CDN, call \ref IRtcEngine::startRtmpStreamWithTranscoding "startRtmpStreamWithTranscoding" + * instead of \ref IRtcEngine::startRtmpStreamWithoutTranscoding "startRtmpStreamWithoutTranscoding". + * + * @param url The address of the CDN live streaming. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. + * Special characters such as Chinese characters are not supported. + * @param transcoding The transcoding configuration for CDN live streaming. See LiveTranscoding. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `ERR_INVALID_ARGUMENT(-2)`: url is null or the string length is 0. + * - `ERR_NOT_INITIALIZED(-7)`: The SDK is not initialized before calling this method. + */ + virtual int startRtmpStreamWithTranscoding(const char* url, const LiveTranscoding& transcoding) = 0; + /** + * Updates the transcoding configuration. + * + * @since v3.6.0 + * + * After you start pushing media streams to CDN with transcoding, you can dynamically update the transcoding configuration according to the scenario. + * The SDK triggers the \ref IRtcEngineEventHandler::onTranscodingUpdated "onTranscodingUpdated" callback after the + * transcoding configuration is updated. + * + * @param transcoding The transcoding configuration for CDN live streaming. See LiveTranscoding. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int updateRtmpTranscoding(const LiveTranscoding& transcoding) = 0; + /** + * Stops pushing media streams to a CDN. + * + * @since v3.6.0 + * + * You can call this method to stop the live stream on the specified CDN address. + * This method can stop pushing media streams to only one CDN address at a time, so if you need to stop pushing streams to multiple addresses, call this method multiple times. + * + * After you call this method, the SDK triggers the \ref IRtcEngineEventHandler::onRtmpStreamingStateChanged "onRtmpStreamingStateChanged" callback on the local client to report the state of the streaming. + * + * @param url The address of the CDN live streaming. The format is RTMP or RTMPS. + * The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int stopRtmpStream(const char* url) = 0; /** **DEPRECATED** Adds a watermark image to the local video or CDN live stream. @@ -8562,29 +10356,31 @@ class IRtcEngine { virtual int addVideoWatermark(const RtcImage& watermark) = 0; /** Adds a watermark image to the local video. - - This method adds a PNG watermark image to the local video in the live streaming. Once the watermark image is added, all the audience in the channel (CDN audience included), - and the capturing device can see and capture it. Agora supports adding only one watermark image onto the local video, and the newly watermark image replaces the previous one. - - The watermark position depends on the settings in the \ref IRtcEngine::setVideoEncoderConfiguration "setVideoEncoderConfiguration" method: - - If the orientation mode of the encoding video is #ORIENTATION_MODE_FIXED_LANDSCAPE, or the landscape mode in #ORIENTATION_MODE_ADAPTIVE, the watermark uses the landscape orientation. - - If the orientation mode of the encoding video is #ORIENTATION_MODE_FIXED_PORTRAIT, or the portrait mode in #ORIENTATION_MODE_ADAPTIVE, the watermark uses the portrait orientation. - - When setting the watermark position, the region must be less than the dimensions set in the `setVideoEncoderConfiguration` method. Otherwise, the watermark image will be cropped. - - @note - - Ensure that you have called the \ref agora::rtc::IRtcEngine::enableVideo "enableVideo" method to enable the video module before calling this method. - - If you only want to add a watermark image to the local video for the audience in the CDN live streaming channel to see and capture, you can call this method or the \ref agora::rtc::IRtcEngine::setLiveTranscoding "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 \ref agora::rtc::IRtcEngine::startPreview "startPreview" method, you can use the `visibleInPreview` member in the WatermarkOptions class to set whether or not the watermark is visible in preview. - - If you have enabled the mirror mode for the local video, the watermark on the local video is also mirrored. To avoid mirroring the watermark, Agora recommends that you do not use the mirror and watermark functions for the local video at the same time. You can implement the watermark function in your application layer. - - @param 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. - @param options Pointer to the watermark's options to be added. See WatermarkOptions for more infomation. - - @return - - 0: Success. - - < 0: Failure. + * + * This method adds a PNG watermark image to the local video in the live streaming. Once the watermark image is added, all the audience in the channel (CDN audience included), + * and the capturing device can see and capture it. Agora supports adding only one watermark image onto the local video, and the newly watermark image replaces the previous one. + * + * The watermark position depends on the settings in the \ref IRtcEngine::setVideoEncoderConfiguration "setVideoEncoderConfiguration" method: + * - If the orientation mode of the encoding video is #ORIENTATION_MODE_FIXED_LANDSCAPE, or the landscape mode in #ORIENTATION_MODE_ADAPTIVE, the watermark uses the landscape orientation. + * - If the orientation mode of the encoding video is #ORIENTATION_MODE_FIXED_PORTRAIT, or the portrait mode in #ORIENTATION_MODE_ADAPTIVE, the watermark uses the portrait orientation. + * - When setting the watermark position, the region must be less than the dimensions set in the `setVideoEncoderConfiguration` method. Otherwise, the watermark image will be cropped. + * + * @note + * - Ensure that you have called the \ref agora::rtc::IRtcEngine::enableVideo "enableVideo" method to enable the video module before calling this method. + * - If you only want to add a watermark image to the local video for the audience in the CDN live streaming channel to see and capture, you can call this method or the \ref agora::rtc::IRtcEngine::setLiveTranscoding "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 \ref agora::rtc::IRtcEngine::startPreview "startPreview" method, you can use the `visibleInPreview` member in the WatermarkOptions class to set whether or not the watermark is visible in preview. + * - If you have enabled the mirror mode for the local video, the watermark on the local video is also mirrored. To avoid mirroring the watermark, Agora recommends that you do not use the mirror and watermark functions for the local video at the same time. You can implement the watermark function in your application layer. + * + * @param 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. + * On Android, Agora recommends passing a URI address or the path starts with `/assets/` in this parameter + * @param options Pointer to the watermark's options to be added. See WatermarkOptions for more infomation. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int addVideoWatermark(const char* watermarkUrl, const WatermarkOptions& options) = 0; @@ -8598,14 +10394,82 @@ class IRtcEngine { /** Enables/Disables image enhancement and sets the options. * - * @note Call this method after calling the \ref IRtcEngine::enableVideo "enableVideo" method. + * @note + * - Call this method after calling the \ref IRtcEngine::enableVideo "enableVideo" method. + * - On Android, this method applies to Android 5.0 or later. + * - Agora has updated the Agora image enhancement algorithm from v3.6.0 to enhance image enhancement effects and support sharpness adjustment. + * If you want to experience optimized image enhancement effects or set the sharpness, integrate the following dynamic library into the project before calling this method: + * - Android: `libagora_video_process_extension.so` + * - iOS: `AgoraVideoProcessExtension.xcframework` + * - macOS: `AgoraVideoProcessExtension.framework` + * - Windows: `libagora_video_process_extension.dll` + * + * @param enabled Determines whether to enable image enhancement: + * - true: Enables image enhancement. + * - false: Disables image enhancement. + * @param options The image enhancement option. See BeautyOptions. * - * @param enabled Sets whether or not to enable image enhancement: - * - true: enables image enhancement. - * - false: disables image enhancement. - * @param options Sets the image enhancement option. See BeautyOptions. + * @return + * - 0: Success. + * - < 0: Failure. + * - `-4(ERR_NOT_SUPPORTED)`: The system version is earlier than Android 5.0, which does not support this function. */ virtual int setBeautyEffectOptions(bool enabled, BeautyOptions options) = 0; + virtual int setLowlightEnhanceOptions(bool enabled, LowLightEnhanceOptions options) = 0; + virtual int setVideoDenoiserOptions(bool enabled, VideoDenoiserOptions options) = 0; + virtual int setColorEnhanceOptions(bool enabled, ColorEnhanceOptions options) = 0; + /** + * Enables/Disables the virtual background. (beta feature) + * + * Support for macOS and Windows as of v3.4.5 and Android and iOS as of v3.5.0. + * + * After enabling the virtual background feature, you can replace the original background image of the local user + * with a custom background image. After the replacement, all users in the channel can see the custom background + * image. You can find out from the + * \ref IRtcEngineEventHandler::onVirtualBackgroundSourceEnabled "onVirtualBackgroundSourceEnabled" callback + * whether the virtual background is successfully enabled or the cause of any errors. + * + * @note + * - Before calling this method, ensure that you have integrated the following dynamic library into your project: + * - Android: `libagora_segmentation_extension.so` + * - iOS: `AgoraVideoSegmentationExtension.xcframework` + * - macOS: `AgoraVideoSegmentationExtension.framework` + * - Windows: `libagora_segmentation_extension.dll` + * - Call this method after \ref IRtcEngine::enableVideo "enableVideo". + * - This functions requires a high-performance device. Agora recommends that you use this function on the + * following devices: + * - Android: Devices with the following chips: + * - Snapdragon 700 series 750G and later + * - Snapdragon 800 series 835 and later + * - Dimensity 700 series 720 and later + * - Kirin 800 series 810 and later + * - Kirin 900 series 980 and later + * - iOS: Devices with an A9 chip and better, as follows: + * - iPhone 6S and later + * - iPad Air (3rd generation) and later + * - iPad (5th generation) and later + * - iPad Pro (1st generation) and later + * - iPad mini (5th generation) and later + * - macOS and Windows: Devices with an i5 CPU and better + * - Agora recommends that you use this function in scenarios that meet the following conditions: + * - A high-definition camera device is used, and the environment is uniformly lit. + * - The captured video image is uncluttered, the user's portrait is half-length and largely unobstructed, and the + * background is a single color that differs from the color of the user's clothing. + * - The virtual background feature does not support video in the Texture format or video obtained from custom video capture by the Push method. + * + * @param enabled Sets whether to enable the virtual background: + * - true: Enable. + * - false: Disable. + * @param backgroundSource The custom background image. See VirtualBackgroundSource. + * Note: To adapt the resolution of the custom background image to the resolution of the SDK capturing video, + * the SDK scales and crops + * the custom background image while ensuring that the content of the custom background image is not distorted. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int enableVirtualBackground(bool enabled, VirtualBackgroundSource backgroundSource) = 0; /** Adds a voice or video stream URL address to the live streaming. @@ -8693,10 +10557,9 @@ class IRtcEngine { * "onChannelMediaRelayEvent" callback with the * #RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL (7) state code. * - * @note - * Call this method after the - * \ref startChannelMediaRelay() "startChannelMediaRelay" method to update - * the destination channel. + * @note Call this method after successfully calling the \ref startChannelMediaRelay() "startChannelMediaRelay" method + * and receiving the \ref IRtcEngineEventHandler::onChannelMediaRelayStateChanged "onChannelMediaRelayStateChanged" (RELAY_STATE_RUNNING, RELAY_OK) callback; + * otherwise, this method call fails. * * @param configuration The media stream relay configuration: * ChannelMediaRelayConfiguration. @@ -8706,6 +10569,47 @@ class IRtcEngine { * - < 0: Failure. */ virtual int updateChannelMediaRelay(const ChannelMediaRelayConfiguration& configuration) = 0; + + /** + * Pauses the media stream relay to all destination channels. + * + * @since v3.5.1 + * + * After the cross-channel media stream relay starts, you can call this method + * to pause relaying media streams to all destination channels; after the pause, + * if you want to resume the relay, call \ref IRtcEngine::resumeAllChannelMediaRelay "resumeAllChannelMediaRelay". + * + * After a successful method call, the SDK triggers the + * \ref IRtcEngineEventHandler::onChannelMediaRelayEvent "onChannelMediaRelayEvent" + * callback to report whether the media stream relay is successfully paused. + * + * @note Call this method after the \ref IRtcEngine::startChannelMediaRelay "startChannelMediaRelay" method. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int pauseAllChannelMediaRelay() = 0; + + /** Resumes the media stream relay to all destination channels. + * + * @since v3.5.1 + * + * After calling the \ref IRtcEngine::pauseAllChannelMediaRelay "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 + * \ref IRtcEngineEventHandler::onChannelMediaRelayEvent "onChannelMediaRelayEvent" + * callback to report whether the media stream relay is successfully resumed. + * + * @note Call this method after the \ref IRtcEngine::pauseAllChannelMediaRelay "pauseAllChannelMediaRelay" method. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int resumeAllChannelMediaRelay() = 0; + /** Stops the media stream relay. * * Once the relay stops, the host quits all the destination @@ -8764,81 +10668,88 @@ class IRtcEngine { @return #CONNECTION_STATE_TYPE. */ virtual CONNECTION_STATE_TYPE getConnectionState() = 0; - /// @cond - /** Enables/Disables the super-resolution algorithm for a remote user's video stream. + + /** Enables/Disables the super resolution feature for a remote user's video. (beta feature) * - * @since v3.2.0 + * @since v3.5.1 * - * The algorithm effectively improves the resolution of the specified remote user's video stream. When the original - * resolution of the remote video stream is a × b pixels, you can receive and render the stream at a higher - * resolution (2a × 2b pixels) by enabling the algorithm. + * This feature effectively boosts the resolution of a remote user's video seen by the local + * user. If the original resolution of a remote user's video is a × b, the local user's device + * can render the remote video at a resolution of 2a × 2b after you enable this feature. * * After calling this method, the SDK triggers the - * \ref IRtcEngineEventHandler::onUserSuperResolutionEnabled "onUserSuperResolutionEnabled" callback to report - * whether you have successfully enabled the super-resolution algorithm. - * - * @warning The super-resolution algorithm requires extra system resources. - * To balance the visual experience and system usage, the SDK poses the following restrictions: - * - The algorithm can only be used for a single user at a time. - * - On the Android platform, the original resolution of the remote video must not exceed 640 × 360 pixels. - * - On the iOS platform, the original resolution of the remote video must not exceed 640 × 480 pixels. - * If you exceed these limitations, the SDK triggers the \ref IRtcEngineEventHandler::onWarning "onWarning" - * callback with the corresponding warning codes: - * - #WARN_SUPER_RESOLUTION_STREAM_OVER_LIMITATION (1610): The origin resolution of the remote video is beyond the range where the super-resolution algorithm can be applied. - * - #WARN_SUPER_RESOLUTION_USER_COUNT_OVER_LIMITATION (1611): Another user is already using the super-resolution algorithm. - * - #WARN_SUPER_RESOLUTION_DEVICE_NOT_SUPPORTED (1612): The device does not support the super-resolution algorithm. + * \ref IRtcEngineEventHandler::onUserSuperResolutionEnabled "onUserSuperResolutionEnabled" + * callback to report whether you have successfully enabled super resolution. + * + * @warning The super resolution feature requires extra system resources. To balance the visual experience and system consumption, the SDK poses the following restrictions: + * - This feature can only be enabled for a single remote user. + * - The original resolution of the remote user's video cannot exceed a certain range. If the local user use super resolution on Android, + * the original resolution of the remote user's video cannot exceed 640 × 360 pixels; if the local user use super resolution on iOS, + * the original resolution of the remote user's video cannot exceed 640 × 480 pixels. + * + * @warning If you exceed these limitations, the SDK triggers the + * \ref IRtcEngineEventHandler::onWarning "onWarning" callback and returns the corresponding warning codes: + * - #WARN_SUPER_RESOLUTION_STREAM_OVER_LIMITATION (1610): The original resolution of the remote user's video is beyond + * the range where super resolution can be applied. + * - #WARN_SUPER_RESOLUTION_USER_COUNT_OVER_LIMITATION (1611): Super resolution is already being used to boost another + * remote user's video. + * - #WARN_SUPER_RESOLUTION_DEVICE_NOT_SUPPORTED (1612): The device does not support using super resolution. * * @note - * - This method applies to Android and iOS only. - * - Requirements for the user's device: - * - Android: The following devices are known to support the method: - * - VIVO: V1821A, NEX S, 1914A, 1916A, and 1824BA - * - OPPO: PCCM00 + * - This method is for Android and iOS only. + * - Before calling this method, ensure that you have integrated the following dynamic library into your project: + * - Android: `libagora_super_resolution_extension.so` + * - iOS: `AgoraSuperResolutionExtension.xcframework` + * - Because this method has certain system performance requirements, Agora recommends that you use the following devices or better: + * - Android: + * - VIVO: V1821A, NEX S, 1914A, 1916A, 1962A, 1824BA, X60, X60 Pro + * - OPPO: PCCM00, Find X3 * - OnePlus: A6000 - * - Xiaomi: Mi 8, Mi 9, MIX3, and Redmi K20 Pro - * - SAMSUNG: SM-G9600, SM-G9650, SM-N9600, SM-G9708, SM-G960U, and SM-G9750 - * - HUAWEI: SEA-AL00, ELE-AL00, VOG-AL00, YAL-AL10, HMA-AL00, and EVR-AN00 - * - iOS: This method is supported on devices running iOS 12.0 or later. The following - * device models are known to support the method: + * - Xiaomi: Mi 8, Mi 9, Mi 10, Mi 11, MIX3, Redmi K20 Pro + * - SAMSUNG: SM-G9600, SM-G9650, SM-N9600, SM-G9708, SM-G960U, SM-G9750, S20, S21 + * - HUAWEI: SEA-AL00, ELE-AL00, VOG-AL00, YAL-AL10, HMA-AL00, EVR-AN00, nova 4, nova 5 Pro, + * nova 6 5G, nova 7 5G, Mate 30, Mate 30 Pro, Mate 40, Mate 40 Pro, P40 P40 Pro, HUAWEI MediaPad M6, MatePad 10.8 + * - iOS (iOS 12.0 or later): * - iPhone XR * - iPhone XS * - iPhone XS Max * - iPhone 11 * - iPhone 11 Pro * - iPhone 11 Pro Max - * - iPad Pro 11-inch (3rd Generation) - * - iPad Pro 12.9-inch (3rd Generation) - * - iPad Air 3 (3rd Generation) - * - * @param userId The ID of the remote user. - * @param enable Whether to enable the super-resolution algorithm: - * - true: Enable the super-resolution algorithm. - * - false: Disable the super-resolution algorithm. + * - iPhone 12 + * - iPhone 12 mini + * - iPhone 12 Pro + * - iPhone 12 Pro Max + * - iPhone 12 SE (2nd generation) + * - iPad Pro 11-inch (3rd generation) + * - iPad Pro 12.9-inch (3rd generation) + * - iPad Air (3rd generation) + * - iPad Air (4th generation) + * + * @param userId The user ID of the remote user. + * @param enable Determines whether to enable super resolution for the remote user's video: + * - true: Enable super resolution. + * - false: Disable super resolution. * * @return * - 0: Success. * - < 0: Failure. - * - -158 (ERR_MODULE_SUPER_RESOLUTION_NOT_FOUND): You have not integrated the dynamic library for the super-resolution algorithm. + * - `-157 (ERR_MODULE_NOT_FOUND)`: The dynamic library for super resolution is not integrated. */ virtual int enableRemoteSuperResolution(uid_t userId, bool enable) = 0; - /// @endcond - - /** Registers the metadata observer. - - Registers the metadata observer. You need to implement the IMetadataObserver class and specify the metadata type in this method. A successful call of this method triggers the \ref agora::rtc::IMetadataObserver::getMaxMetadataSize "getMaxMetadataSize" callback. - This method enables you to add synchronized metadata in the video stream for more diversified interactive live streaming, such as sending shopping links, digital coupons, and online quizzes. + /** This method enables you to add synchronized metadata in the video stream for more diversified interactive live streaming, such as sending shopping links, digital coupons, and online quizzes. - @note - - Call this method before the joinChannel method. - - This method applies to the `LIVE_BROADCASTING` channel profile. + @note + - Call this method before the joinChannel method. + - This method applies to the `LIVE_BROADCASTING` channel profile. - @param observer The IMetadataObserver class. See the definition of IMetadataObserver for details. - @param type See \ref IMetadataObserver::METADATA_TYPE "METADATA_TYPE". The SDK supports VIDEO_METADATA (0) only for now. + @param observer The IMetadataObserver class. See the definition of IMetadataObserver for details. + @param type See \ref IMetadataObserver::METADATA_TYPE "METADATA_TYPE". The SDK supports VIDEO_METADATA (0) only for now. - @return - - 0: Success. - - < 0: Failure. - */ + @return + - 0: Success. + - < 0: Failure. + */ virtual int registerMediaMetadataObserver(IMetadataObserver* observer, IMetadataObserver::METADATA_TYPE type) = 0; /** Provides technical preview functionalities or special customizations by configuring the SDK with JSON options. @@ -8851,6 +10762,136 @@ class IRtcEngine { - < 0: Failure. */ virtual int setParameters(const char* parameters) = 0; + + // virtual int getMediaRecorder(IMediaRecorderObserver *observer, int sys_version = 0) = 0; + + // virtual int startRecording(const MediaRecorderConfiguration &config) = 0; + + // virtual int stopRecording() = 0; + + // virtual int releaseRecorder() = 0; + /** + * Customizes the local video renderer. (for Windows only) + * + * @since v3.5.0 + * + * During a real-time audio and video interaction, the Agora SDK enables the default renderer to render local video. + * If you want to customize the local video rendering, you can first customize the video renderer via the IVideoSink + * class, and then call this method to use the custom video renderer to render the local video. + * + * @note You can call this method either before or after joining a channel. + * + * @param videoSink The custom video renderer. See IVideoSink. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int setLocalVideoRenderer(IVideoSink* videoSink) = 0; + /** + * Customizes the remote video renderer. (for Windows only) + * + * @since v3.5.0 + * + * During a real-time audio and video interaction, the Agora SDK enables the default renderer to render remote video. + * If you want to customize the remote video rendering, you can first customize the video renderer via the IVideoSink + * class, and then call this method to use the custom video renderer to render the remote video. + * + * @note You can call this method either before or after joining a channel. + * + * @param uid The user ID of the remote user. + * @param videoSink The custom video renderer. See IVideoSink. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int setRemoteVideoRenderer(uid_t uid, IVideoSink* videoSink) = 0; + /// @cond + virtual int setLocalAccessPoint(const LocalAccessPointConfiguration& config) = 0; + /// @endcond +#if defined(__ANDROID__) || (defined(__APPLE__) && TARGET_OS_IOS) + /** + * Sets whether to enable the flash. + * + * @since v3.5.1 + * + * @note + * - Call this method after the camera is started. + * - This method is for Android and iOS only. + * - On iPads with system version 15, even if \ref IRtcEngine::isCameraTorchSupported "isCameraTorchSupported" + * returns true, you might fail to successfully enable the flash by calling `setCameraTorchOn` due to + * system issues. + * + * @param isOn Determines whether to enable the flash: + * - true: Enable the flash. + * - false: Disable the flash. + * + * @return + * - 0: Success + * - < 0: Failure + */ + virtual int setCameraTorchOn(bool isOn) = 0; + /** + * Checks whether the device supports enabling the flash. + * + * @since v3.5.1 + * + * The SDK uses the front camera by default, so if you call `isCameraTorchSupported` directly, + * you can find out from the return value whether the device supports enabling the flash + * when using the front camera. If you want to check whether the device supports enabling the + * flash when using the rear camera, call \ref IRtcEngine::switchCamera "switchCamera" + * to switch the camera used by the SDK to the rear camera, and then call `isCameraTorchSupported`. + * + * @note + * - Call this method after the camera is started. + * - This method is for Android and iOS only. + * - On iPads with system version 15, even if `isCameraTorchSupported` returns true, you might + * fail to successfully enable the flash by calling \ref IRtcEngine::setCameraTorchOn "setCameraTorchOn" + * due to system issues. + * + * + * @return + * - true: The device supports enabling the flash. + * - false: The device does not support enabling the flash. + */ + virtual bool isCameraTorchSupported() = 0; +#endif + + /** + * Takes a snapshot of a video stream. + * + * @since v3.5.2 + * + * This method takes a snapshot of a video stream from the specified user, generates a JPG image, + * and saves it to the specified path. + * + * The method is asynchronous, and the SDK has not taken the snapshot when the method call returns. + * After a successful method call, the SDK triggers the \ref IRtcEngineEventHandler::onSnapshotTaken "onSnapshotTaken" + * callback to report whether the snapshot is successfully taken as well as the details of the snapshot taken. + * + * @note + * - Call this method after joining a channel. + * - If the video of the specified user is pre-processed, for example, added with watermarks or image enhancement + * effects, the generated snapshot also includes the pre-processing effects. + * + * @param channel The channel name. + * @param uid The user ID of the user. Set `uid` as 0 if you want to take a snapshot of the local user's video. + * @param filePath The local path (including the filename extensions) of the snapshot. For example, + * `C:\Users\\AppData\Local\Agora\\example.jpg` on Windows, + * `/App Sandbox/Library/Caches/example.jpg` on iOS, `～/Library/Logs/example.jpg` on macOS, and + * `/storage/emulated/0/Android/data//files/example.jpg` on Android. Ensure that the path you specify + * exists and is writable. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int takeSnapshot(const char* channel, uid_t uid, const char* filePath) = 0; + + /// @cond + virtual int enableContentInspect(bool enabled, const ContentInspectConfig& config) = 0; + /// @endcond }; class IRtcEngineParameter { @@ -8926,7 +10967,7 @@ class IRtcEngineParameter { */ virtual int setObject(const char* key, const char* value) = 0; - /** Retrieves the bool value of a specified key in the JSON format. + /** Gets the bool value of a specified key in the JSON format. @param key Pointer to the name of the key. @param value Pointer to the retrieved value. @@ -8937,7 +10978,7 @@ class IRtcEngineParameter { */ virtual int getBool(const char* key, bool& value) = 0; - /** Retrieves the int value of the JSON format. + /** Gets the int value of the JSON format. @param key Pointer to the name of the key. @param value Pointer to the retrieved value. @@ -8948,7 +10989,7 @@ class IRtcEngineParameter { */ virtual int getInt(const char* key, int& value) = 0; - /** Retrieves the unsigned int value of a specified key in the JSON format. + /** Gets the unsigned int value of a specified key in the JSON format. @param key Pointer to the name of the key. @param value Pointer to the retrieved value. @@ -8958,7 +10999,7 @@ class IRtcEngineParameter { */ virtual int getUInt(const char* key, unsigned int& value) = 0; - /** Retrieves the double value of a specified key in the JSON format. + /** Gets the double value of a specified key in the JSON format. @param key Pointer to the name of the key. @param value Pointer to the retrieved value. @@ -8969,7 +11010,7 @@ class IRtcEngineParameter { */ virtual int getNumber(const char* key, double& value) = 0; - /** Retrieves the string value of a specified key in the JSON format. + /** Gets the string value of a specified key in the JSON format. @param key Pointer to the name of the key. @param value Pointer to the retrieved value. @@ -8980,7 +11021,7 @@ class IRtcEngineParameter { */ virtual int getString(const char* key, agora::util::AString& value) = 0; - /** Retrieves a child object value of a specified key in the JSON format. + /** Gets a child object value of a specified key in the JSON format. @param key Pointer to the name of the key. @param value Pointer to the retrieved value. @@ -8990,7 +11031,7 @@ class IRtcEngineParameter { */ virtual int getObject(const char* key, agora::util::AString& value) = 0; - /** Retrieves the array value of a specified key in the JSON format. + /** Gets the array value of a specified key in the JSON format. @param key Pointer to the name of the key. @param value Pointer to the retrieved value. @@ -9026,6 +11067,7 @@ class IRtcEngineParameter { virtual int convertPath(const char* filePath, agora::util::AString& value) = 0; }; +#if !defined(__ANDROID__) && !(defined(__APPLE__) && TARGET_OS_IPHONE) class AAudioDeviceManager : public agora::util::AutoPtr { public: AAudioDeviceManager(IRtcEngine* engine) { queryInterface(engine, AGORA_IID_AUDIO_DEVICE_MANAGER); } @@ -9035,8 +11077,9 @@ class AVideoDeviceManager : public agora::util::AutoPtr { public: AVideoDeviceManager(IRtcEngine* engine) { queryInterface(engine, AGORA_IID_VIDEO_DEVICE_MANAGER); } }; +#endif -class AParameter : public agora::util::AutoPtr { +class AGORA_CPP_API AParameter : public agora::util::AutoPtr { public: AParameter(IRtcEngine& engine) { initialize(&engine); } AParameter(IRtcEngine* engine) { initialize(engine); } @@ -9051,483 +11094,93 @@ class AParameter : public agora::util::AutoPtr { }; /** **DEPRECATED** The RtcEngineParameters class is deprecated, use the IRtcEngine class instead. */ -class RtcEngineParameters { +class AGORA_CPP_API RtcEngineParameters { public: RtcEngineParameters(IRtcEngine& engine) : m_parameter(&engine) {} RtcEngineParameters(IRtcEngine* engine) : m_parameter(engine) {} - int enableLocalVideo(bool enabled) { return setParameters("{\"rtc.video.capture\":%s,\"che.video.local.capture\":%s,\"che.video.local.render\":%s,\"che.video.local.send\":%s}", enabled ? "true" : "false", enabled ? "true" : "false", enabled ? "true" : "false", enabled ? "true" : "false"); } - - int muteLocalVideoStream(bool mute) { return setParameters("{\"rtc.video.mute_me\":%s,\"che.video.local.send\":%s}", mute ? "true" : "false", mute ? "false" : "true"); } - - int muteAllRemoteVideoStreams(bool mute) { return m_parameter ? m_parameter->setBool("rtc.video.mute_peers", mute) : -ERR_NOT_INITIALIZED; } - - int setDefaultMuteAllRemoteVideoStreams(bool mute) { return m_parameter ? m_parameter->setBool("rtc.video.set_default_mute_peers", mute) : -ERR_NOT_INITIALIZED; } - - int muteRemoteVideoStream(uid_t uid, bool mute) { return setObject("rtc.video.mute_peer", "{\"uid\":%u,\"mute\":%s}", uid, mute ? "true" : "false"); } - - int setPlaybackDeviceVolume(int volume) { // [0,255] - return m_parameter ? m_parameter->setInt("che.audio.output.volume", volume) : -ERR_NOT_INITIALIZED; - } - - int startAudioRecording(const char* filePath, AUDIO_RECORDING_QUALITY_TYPE quality) { return startAudioRecording(filePath, 32000, quality); } - - int startAudioRecording(const char* filePath, int sampleRate, AUDIO_RECORDING_QUALITY_TYPE quality) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; -#if defined(_WIN32) - util::AString path; - if (!m_parameter->convertPath(filePath, path)) - filePath = path->c_str(); - else - return -ERR_INVALID_ARGUMENT; -#endif - return setObject("che.audio.start_recording", "{\"filePath\":\"%s\",\"sampleRate\":%d,\"quality\":%d}", filePath, sampleRate, quality); - } - - int stopAudioRecording() { return setParameters("{\"che.audio.stop_recording\":true, \"che.audio.stop_nearend_recording\":true, \"che.audio.stop_farend_recording\":true}"); } - - int startAudioMixing(const char* filePath, bool loopback, bool replace, int cycle, int startPos = 0) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; -#if defined(_WIN32) - util::AString path; - if (!m_parameter->convertPath(filePath, path)) - filePath = path->c_str(); - else - return -ERR_INVALID_ARGUMENT; -#endif - return setObject("che.audio.start_file_as_playout", "{\"filePath\":\"%s\",\"loopback\":%s,\"replace\":%s,\"cycle\":%d, \"startPos\":%d}", filePath, loopback ? "true" : "false", replace ? "true" : "false", cycle, startPos); - } - - int stopAudioMixing() { return m_parameter ? m_parameter->setBool("che.audio.stop_file_as_playout", true) : -ERR_NOT_INITIALIZED; } - - int pauseAudioMixing() { return m_parameter ? m_parameter->setBool("che.audio.pause_file_as_playout", true) : -ERR_NOT_INITIALIZED; } - - int resumeAudioMixing() { return m_parameter ? m_parameter->setBool("che.audio.pause_file_as_playout", false) : -ERR_NOT_INITIALIZED; } - - int adjustAudioMixingVolume(int volume) { - int ret = adjustAudioMixingPlayoutVolume(volume); - if (ret == 0) { - adjustAudioMixingPublishVolume(volume); - } - return ret; - } - - int adjustAudioMixingPlayoutVolume(int volume) { return m_parameter ? m_parameter->setInt("che.audio.set_file_as_playout_volume", volume) : -ERR_NOT_INITIALIZED; } - - int getAudioMixingPlayoutVolume() { - int volume = 0; - int r = m_parameter ? m_parameter->getInt("che.audio.get_file_as_playout_volume", volume) : -ERR_NOT_INITIALIZED; - if (r == 0) r = volume; - return r; - } - - int adjustAudioMixingPublishVolume(int volume) { return m_parameter ? m_parameter->setInt("che.audio.set_file_as_playout_publish_volume", volume) : -ERR_NOT_INITIALIZED; } - - int getAudioMixingPublishVolume() { - int volume = 0; - int r = m_parameter ? m_parameter->getInt("che.audio.get_file_as_playout_publish_volume", volume) : -ERR_NOT_INITIALIZED; - if (r == 0) r = volume; - return r; - } - - int getAudioMixingDuration() { - int duration = 0; - int r = m_parameter ? m_parameter->getInt("che.audio.get_mixing_file_length_ms", duration) : -ERR_NOT_INITIALIZED; - if (r == 0) r = duration; - return r; - } - - int getAudioMixingCurrentPosition() { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - int pos = 0; - int r = m_parameter->getInt("che.audio.get_mixing_file_played_ms", pos); - if (r == 0) r = pos; - return r; - } - - int setAudioMixingPosition(int pos /*in ms*/) { return m_parameter ? m_parameter->setInt("che.audio.mixing.file.position", pos) : -ERR_NOT_INITIALIZED; } - - int setAudioMixingPitch(int pitch) { - if (!m_parameter) { - return -ERR_NOT_INITIALIZED; - } - if (pitch > 12 || pitch < -12) { - return -ERR_INVALID_ARGUMENT; - } - return m_parameter->setInt("che.audio.set_playout_file_pitch_semitones", pitch); - } - - int getEffectsVolume() { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - int volume = 0; - int r = m_parameter->getInt("che.audio.game_get_effects_volume", volume); - if (r == 0) r = volume; - return r; - } - - int setEffectsVolume(int volume) { return m_parameter ? m_parameter->setInt("che.audio.game_set_effects_volume", volume) : -ERR_NOT_INITIALIZED; } - - int setVolumeOfEffect(int soundId, int volume) { return setObject("che.audio.game_adjust_effect_volume", "{\"soundId\":%d,\"gain\":%d}", soundId, volume); } - - int playEffect(int soundId, const char* filePath, int loopCount, double pitch, double pan, int gain, bool publish = false) { -#if defined(_WIN32) - util::AString path; - if (!m_parameter->convertPath(filePath, path)) - filePath = path->c_str(); - else if (!filePath) - filePath = ""; -#endif - return setObject("che.audio.game_play_effect", "{\"soundId\":%d,\"filePath\":\"%s\",\"loopCount\":%d, \"pitch\":%lf,\"pan\":%lf,\"gain\":%d, \"send2far\":%d}", soundId, filePath, loopCount, pitch, pan, gain, publish); - } - - int stopEffect(int soundId) { return m_parameter ? m_parameter->setInt("che.audio.game_stop_effect", soundId) : -ERR_NOT_INITIALIZED; } - - int stopAllEffects() { return m_parameter ? m_parameter->setBool("che.audio.game_stop_all_effects", true) : -ERR_NOT_INITIALIZED; } - - int preloadEffect(int soundId, char* filePath) { return setObject("che.audio.game_preload_effect", "{\"soundId\":%d,\"filePath\":\"%s\"}", soundId, filePath); } - - int unloadEffect(int soundId) { return m_parameter ? m_parameter->setInt("che.audio.game_unload_effect", soundId) : -ERR_NOT_INITIALIZED; } - - int pauseEffect(int soundId) { return m_parameter ? m_parameter->setInt("che.audio.game_pause_effect", soundId) : -ERR_NOT_INITIALIZED; } - - int pauseAllEffects() { return m_parameter ? m_parameter->setBool("che.audio.game_pause_all_effects", true) : -ERR_NOT_INITIALIZED; } - - int resumeEffect(int soundId) { return m_parameter ? m_parameter->setInt("che.audio.game_resume_effect", soundId) : -ERR_NOT_INITIALIZED; } - - int resumeAllEffects() { return m_parameter ? m_parameter->setBool("che.audio.game_resume_all_effects", true) : -ERR_NOT_INITIALIZED; } - - int enableSoundPositionIndication(bool enabled) { return m_parameter ? m_parameter->setBool("che.audio.enable_sound_position", enabled) : -ERR_NOT_INITIALIZED; } - - int setRemoteVoicePosition(uid_t uid, double pan, double gain) { return setObject("che.audio.game_place_sound_position", "{\"uid\":%u,\"pan\":%lf,\"gain\":%lf}", uid, pan, gain); } - - int setLocalVoicePitch(double pitch) { return m_parameter ? m_parameter->setInt("che.audio.morph.pitch_shift", static_cast(pitch * 100)) : -ERR_NOT_INITIALIZED; } - - int setLocalVoiceEqualization(AUDIO_EQUALIZATION_BAND_FREQUENCY bandFrequency, int bandGain) { return setObject("che.audio.morph.equalization", "{\"index\":%d,\"gain\":%d}", static_cast(bandFrequency), bandGain); } - - int setLocalVoiceReverb(AUDIO_REVERB_TYPE reverbKey, int value) { return setObject("che.audio.morph.reverb", "{\"key\":%d,\"value\":%d}", static_cast(reverbKey), value); } - - int setLocalVoiceChanger(VOICE_CHANGER_PRESET voiceChanger) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - if (voiceChanger == 0x00000000) { - return m_parameter->setInt("che.audio.morph.voice_changer", static_cast(voiceChanger)); - } else if (voiceChanger > 0x00000000 && voiceChanger < 0x00100000) { - return m_parameter->setInt("che.audio.morph.voice_changer", static_cast(voiceChanger)); - } else if (voiceChanger > 0x00100000 && voiceChanger < 0x00200000) { - return m_parameter->setInt("che.audio.morph.voice_changer", static_cast(voiceChanger - 0x00100000 + 6)); - } else if (voiceChanger > 0x00200000 && voiceChanger < 0x00300000) { - return m_parameter->setInt("che.audio.morph.beauty_voice", static_cast(voiceChanger - 0x00200000)); - } else { - return -ERR_INVALID_ARGUMENT; - } - } - - int setLocalVoiceReverbPreset(AUDIO_REVERB_PRESET reverbPreset) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - if (reverbPreset == 0x00000000) { - return m_parameter->setInt("che.audio.morph.reverb_preset", static_cast(reverbPreset)); - } else if (reverbPreset > 0x00000000 && reverbPreset < 0x00100000) { - return m_parameter->setInt("che.audio.morph.reverb_preset", static_cast(reverbPreset + 8)); - } else if (reverbPreset > 0x00100000 && reverbPreset < 0x00200000) { - return m_parameter->setInt("che.audio.morph.reverb_preset", static_cast(reverbPreset - 0x00100000)); - } else if (reverbPreset > 0x00200000 && reverbPreset < 0x00200002) { - return m_parameter->setInt("che.audio.morph.virtual_stereo", static_cast(reverbPreset - 0x00200000)); - } else if (reverbPreset > (AUDIO_REVERB_PRESET)0x00300000 && reverbPreset < (AUDIO_REVERB_PRESET)0x00300002) - return setObject("che.audio.morph.electronic_voice", "{\"key\":%d,\"value\":%d}", 1, 4); - else if (reverbPreset > (AUDIO_REVERB_PRESET)0x00400000 && reverbPreset < (AUDIO_REVERB_PRESET)0x00400002) - return m_parameter->setInt("che.audio.morph.threedim_voice", 10); - else { - return -ERR_INVALID_ARGUMENT; - } - } - - int setAudioEffectPreset(AUDIO_EFFECT_PRESET preset) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - if (preset == AUDIO_EFFECT_OFF) { - return m_parameter->setInt("che.audio.morph.voice_changer", 0); - } - if (preset == ROOM_ACOUSTICS_KTV) { - return m_parameter->setInt("che.audio.morph.reverb_preset", 1); - } - if (preset == ROOM_ACOUSTICS_VOCAL_CONCERT) { - return m_parameter->setInt("che.audio.morph.reverb_preset", 2); - } - if (preset == ROOM_ACOUSTICS_STUDIO) { - return m_parameter->setInt("che.audio.morph.reverb_preset", 5); - } - if (preset == ROOM_ACOUSTICS_PHONOGRAPH) { - return m_parameter->setInt("che.audio.morph.reverb_preset", 8); - } - if (preset == ROOM_ACOUSTICS_VIRTUAL_STEREO) { - return m_parameter->setInt("che.audio.morph.virtual_stereo", 1); - } - if (preset == ROOM_ACOUSTICS_SPACIAL) { - return m_parameter->setInt("che.audio.morph.voice_changer", 15); - } - if (preset == ROOM_ACOUSTICS_ETHEREAL) { - return m_parameter->setInt("che.audio.morph.voice_changer", 5); - } - if (preset == ROOM_ACOUSTICS_3D_VOICE) { - return m_parameter->setInt("che.audio.morph.threedim_voice", 10); - } - if (preset == VOICE_CHANGER_EFFECT_UNCLE) { - return m_parameter->setInt("che.audio.morph.reverb_preset", 3); - } - if (preset == VOICE_CHANGER_EFFECT_OLDMAN) { - return m_parameter->setInt("che.audio.morph.voice_changer", 1); - } - if (preset == VOICE_CHANGER_EFFECT_BOY) { - return m_parameter->setInt("che.audio.morph.voice_changer", 2); - } - if (preset == VOICE_CHANGER_EFFECT_SISTER) { - return m_parameter->setInt("che.audio.morph.reverb_preset", 4); - } - if (preset == VOICE_CHANGER_EFFECT_GIRL) { - return m_parameter->setInt("che.audio.morph.voice_changer", 3); - } - if (preset == VOICE_CHANGER_EFFECT_PIGKING) { - return m_parameter->setInt("che.audio.morph.voice_changer", 4); - } - if (preset == VOICE_CHANGER_EFFECT_HULK) { - return m_parameter->setInt("che.audio.morph.voice_changer", 6); - } - if (preset == STYLE_TRANSFORMATION_RNB) { - return m_parameter->setInt("che.audio.morph.reverb_preset", 7); - } - if (preset == STYLE_TRANSFORMATION_POPULAR) { - return m_parameter->setInt("che.audio.morph.reverb_preset", 6); - } - if (preset == PITCH_CORRECTION) { - return setObject("che.audio.morph.electronic_voice", "{\"key\":%d,\"value\":%d}", 1, 4); - } - return -ERR_INVALID_ARGUMENT; - } - - int setVoiceBeautifierPreset(VOICE_BEAUTIFIER_PRESET preset) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - if (preset == VOICE_BEAUTIFIER_OFF) { - return m_parameter->setInt("che.audio.morph.voice_changer", 0); - } - if (preset == CHAT_BEAUTIFIER_MAGNETIC) { - return m_parameter->setInt("che.audio.morph.beauty_voice", 1); - } - if (preset == CHAT_BEAUTIFIER_FRESH) { - return m_parameter->setInt("che.audio.morph.beauty_voice", 2); - } - if (preset == CHAT_BEAUTIFIER_VITALITY) { - return m_parameter->setInt("che.audio.morph.beauty_voice", 3); - } - if (preset == SINGING_BEAUTIFIER) { - return setObject("che.audio.morph.beauty_sing", "{\"key\":%d,\"value\":%d}", 1, 1); - } - if (preset == TIMBRE_TRANSFORMATION_VIGOROUS) { - return m_parameter->setInt("che.audio.morph.voice_changer", 7); - } - if (preset == TIMBRE_TRANSFORMATION_DEEP) { - return m_parameter->setInt("che.audio.morph.voice_changer", 8); - } - if (preset == TIMBRE_TRANSFORMATION_MELLOW) { - return m_parameter->setInt("che.audio.morph.voice_changer", 9); - } - if (preset == TIMBRE_TRANSFORMATION_FALSETTO) { - return m_parameter->setInt("che.audio.morph.voice_changer", 10); - } - if (preset == TIMBRE_TRANSFORMATION_FULL) { - return m_parameter->setInt("che.audio.morph.voice_changer", 11); - } - if (preset == TIMBRE_TRANSFORMATION_CLEAR) { - return m_parameter->setInt("che.audio.morph.voice_changer", 12); - } - if (preset == TIMBRE_TRANSFORMATION_RESOUNDING) { - return m_parameter->setInt("che.audio.morph.voice_changer", 13); - } - if (preset == TIMBRE_TRANSFORMATION_RINGING) { - return m_parameter->setInt("che.audio.morph.voice_changer", 14); - } - return -ERR_INVALID_ARGUMENT; - } - - int setAudioEffectParameters(AUDIO_EFFECT_PRESET preset, int param1, int param2) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - if (preset == PITCH_CORRECTION) { - return setObject("che.audio.morph.electronic_voice", "{\"key\":%d,\"value\":%d}", param1, param2); - } - if (preset == ROOM_ACOUSTICS_3D_VOICE) { - return m_parameter->setInt("che.audio.morph.threedim_voice", param1); - } - return -ERR_INVALID_ARGUMENT; - } - - int setVoiceBeautifierParameters(VOICE_BEAUTIFIER_PRESET preset, int param1, int param2) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - if (preset == SINGING_BEAUTIFIER) { - return setObject("che.audio.morph.beauty_sing", "{\"key\":%d,\"value\":%d}", param1, param2); - } - return -ERR_INVALID_ARGUMENT; - } - - /** **DEPRECATED** Use \ref IRtcEngine::disableAudio "disableAudio" instead. Disables the audio function in the channel. - - @return - - 0: Success. - - < 0: Failure. - */ - int pauseAudio() { return m_parameter ? m_parameter->setBool("che.pause.audio", true) : -ERR_NOT_INITIALIZED; } - - int resumeAudio() { return m_parameter ? m_parameter->setBool("che.pause.audio", false) : -ERR_NOT_INITIALIZED; } - - int setHighQualityAudioParameters(bool fullband, bool stereo, bool fullBitrate) { return setObject("che.audio.codec.hq", "{\"fullband\":%s,\"stereo\":%s,\"fullBitrate\":%s}", fullband ? "true" : "false", stereo ? "true" : "false", fullBitrate ? "true" : "false"); } - - int adjustRecordingSignalVolume(int volume) { //[0, 400]: e.g. 50~0.5x 100~1x 400~4x - if (volume < 0) - volume = 0; - else if (volume > 400) - volume = 400; - return m_parameter ? m_parameter->setInt("che.audio.record.signal.volume", volume) : -ERR_NOT_INITIALIZED; - } - - int adjustPlaybackSignalVolume(int volume) { //[0, 400] - if (volume < 0) - volume = 0; - else if (volume > 400) - volume = 400; - return m_parameter ? m_parameter->setInt("che.audio.playout.signal.volume", volume) : -ERR_NOT_INITIALIZED; - } - - int enableAudioVolumeIndication(int interval, int smooth, bool report_vad) { // in ms: <= 0: disable, > 0: enable, interval in ms - if (interval < 0) interval = 0; - return setObject("che.audio.volume_indication", "{\"interval\":%d,\"smooth\":%d,\"vad\":%d}", interval, smooth, report_vad); - } - - int muteLocalAudioStream(bool mute) { return setParameters("{\"rtc.audio.mute_me\":%s,\"che.audio.mute_me\":%s}", mute ? "true" : "false", mute ? "true" : "false"); } - // mute/unmute all peers. unmute will clear all muted peers specified mutePeer() interface - - int muteRemoteAudioStream(uid_t uid, bool mute) { return setObject("rtc.audio.mute_peer", "{\"uid\":%u,\"mute\":%s}", uid, mute ? "true" : "false"); } - - int muteAllRemoteAudioStreams(bool mute) { return m_parameter ? m_parameter->setBool("rtc.audio.mute_peers", mute) : -ERR_NOT_INITIALIZED; } - - int setVoiceConversionPreset(VOICE_CONVERSION_PRESET preset) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - if (preset == VOICE_CONVERSION_OFF) { - return m_parameter->setInt("che.audio.morph.voice_changer", 0); - } - if (preset == VOICE_CHANGER_NEUTRAL) { - return m_parameter->setInt("che.audio.morph.vocal_changer", 1); - } - if (preset == VOICE_CHANGER_SWEET) { - return m_parameter->setInt("che.audio.morph.vocal_changer", 2); - } - if (preset == VOICE_CHANGER_SOLID) { - return m_parameter->setInt("che.audio.morph.vocal_changer", 3); - } - if (preset == VOICE_CHANGER_BASS) { - return m_parameter->setInt("che.audio.morph.vocal_changer", 4); - } - return -ERR_INVALID_ARGUMENT; - } - - int setDefaultMuteAllRemoteAudioStreams(bool mute) { return m_parameter ? m_parameter->setBool("rtc.audio.set_default_mute_peers", mute) : -ERR_NOT_INITIALIZED; } - - int setExternalAudioSource(bool enabled, int sampleRate, int channels) { - if (enabled) - return setParameters("{\"che.audio.external_capture\":true,\"che.audio.external_capture.push\":true,\"che.audio.set_capture_raw_audio_format\":{\"sampleRate\":%d,\"channelCnt\":%d,\"mode\":%d}}", sampleRate, channels, RAW_AUDIO_FRAME_OP_MODE_TYPE::RAW_AUDIO_FRAME_OP_MODE_READ_WRITE); - else - return setParameters("{\"che.audio.external_capture\":false,\"che.audio.external_capture.push\":false}"); - } - - int setExternalAudioSink(bool enabled, int sampleRate, int channels) { - if (enabled) - return setParameters("{\"che.audio.external_render\":true,\"che.audio.external_render.pull\":true,\"che.audio.set_render_raw_audio_format\":{\"sampleRate\":%d,\"channelCnt\":%d,\"mode\":%d}}", sampleRate, channels, RAW_AUDIO_FRAME_OP_MODE_TYPE::RAW_AUDIO_FRAME_OP_MODE_READ_ONLY); - else - return setParameters("{\"che.audio.external_render\":false,\"che.audio.external_render.pull\":false}"); - } - - int setLogFile(const char* filePath) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; -#if defined(_WIN32) - util::AString path; - if (!m_parameter->convertPath(filePath, path)) - filePath = path->c_str(); - else if (!filePath) - filePath = ""; -#endif - return m_parameter->setString("rtc.log_file", filePath); - } - - int setLogFilter(unsigned int filter) { return m_parameter ? m_parameter->setUInt("rtc.log_filter", filter & LOG_FILTER_MASK) : -ERR_NOT_INITIALIZED; } - - int setLogFileSize(unsigned int fileSizeInKBytes) { return m_parameter ? m_parameter->setUInt("rtc.log_size", fileSizeInKBytes) : -ERR_NOT_INITIALIZED; } - - int setLocalRenderMode(RENDER_MODE_TYPE renderMode) { return setRemoteRenderMode(0, renderMode); } - - int setRemoteRenderMode(uid_t uid, RENDER_MODE_TYPE renderMode) { return setParameters("{\"che.video.render_mode\":[{\"uid\":%u,\"renderMode\":%d}]}", uid, renderMode); } - - int setCameraCapturerConfiguration(const CameraCapturerConfiguration& config) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - if (config.preference == CAPTURER_OUTPUT_PREFERENCE_MANUAL) { - m_parameter->setInt("che.video.capture_width", config.captureWidth); - m_parameter->setInt("che.video.capture_height", config.captureHeight); - } - return m_parameter->setInt("che.video.camera_capture_mode", (int)config.preference); - } - - int enableDualStreamMode(bool enabled) { return setParameters("{\"rtc.dual_stream_mode\":%s,\"che.video.enableLowBitRateStream\":%d}", enabled ? "true" : "false", enabled ? 1 : 0); } - - int setRemoteVideoStreamType(uid_t uid, REMOTE_VIDEO_STREAM_TYPE streamType) { - return setParameters("{\"rtc.video.set_remote_video_stream\":{\"uid\":%u,\"stream\":%d}, \"che.video.setstream\":{\"uid\":%u,\"stream\":%d}}", uid, streamType, uid, streamType); - // return setObject("rtc.video.set_remote_video_stream", "{\"uid\":%u,\"stream\":%d}", uid, streamType); - } - - int setRemoteDefaultVideoStreamType(REMOTE_VIDEO_STREAM_TYPE streamType) { return m_parameter ? m_parameter->setInt("rtc.video.set_remote_default_video_stream_type", streamType) : -ERR_NOT_INITIALIZED; } - - int setRecordingAudioFrameParameters(int sampleRate, int channel, RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall) { return setObject("che.audio.set_capture_raw_audio_format", "{\"sampleRate\":%d,\"channelCnt\":%d,\"mode\":%d,\"samplesPerCall\":%d}", sampleRate, channel, mode, samplesPerCall); } - - int setPlaybackAudioFrameParameters(int sampleRate, int channel, RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall) { return setObject("che.audio.set_render_raw_audio_format", "{\"sampleRate\":%d,\"channelCnt\":%d,\"mode\":%d,\"samplesPerCall\":%d}", sampleRate, channel, mode, samplesPerCall); } - - int setMixedAudioFrameParameters(int sampleRate, int samplesPerCall) { return setObject("che.audio.set_mixed_raw_audio_format", "{\"sampleRate\":%d,\"samplesPerCall\":%d}", sampleRate, samplesPerCall); } - - int enableWebSdkInteroperability(bool enabled) { // enable interoperability with zero-plugin web sdk - return setParameters("{\"rtc.video.web_h264_interop_enable\":%s,\"che.video.web_h264_interop_enable\":%s}", enabled ? "true" : "false", enabled ? "true" : "false"); - } + int enableLocalVideo(bool enabled); + int muteLocalVideoStream(bool mute); + int muteAllRemoteVideoStreams(bool mute); + int setDefaultMuteAllRemoteVideoStreams(bool mute); + int muteRemoteVideoStream(uid_t uid, bool mute); + int setPlaybackDeviceVolume(int volume /* [0,255] */); + int startAudioRecording(const char* filePath, AUDIO_RECORDING_QUALITY_TYPE quality); + int startAudioRecording(const char* filePath, int sampleRate, AUDIO_RECORDING_QUALITY_TYPE quality); + int stopAudioRecording(); + int startAudioMixing(const char* filePath, bool loopback, bool replace, int cycle, int startPos = 0); + int stopAudioMixing(); + int pauseAudioMixing(); + int resumeAudioMixing(); + int adjustAudioMixingVolume(int volume); + int adjustAudioMixingPlayoutVolume(int volume); + int getAudioMixingPlayoutVolume(); + int adjustAudioMixingPublishVolume(int volume); + int getAudioMixingPublishVolume(); + int getAudioMixingDuration(); + int getAudioMixingCurrentPosition(); + int setAudioMixingPosition(int pos /*in ms*/); + int setAudioMixingPitch(int pitch); + int getEffectsVolume(); + int setEffectsVolume(int volume); + int setVolumeOfEffect(int soundId, int volume); + int playEffect(int soundId, const char* filePath, int loopCount, double pitch, double pan, int gain, bool publish = false); + int stopEffect(int soundId); + int stopAllEffects(); + int preloadEffect(int soundId, char* filePath); + int unloadEffect(int soundId); + int pauseEffect(int soundId); + int pauseAllEffects(); + int resumeEffect(int soundId); + int resumeAllEffects(); + int enableSoundPositionIndication(bool enabled); + int setRemoteVoicePosition(uid_t uid, double pan, double gain); + int setLocalVoicePitch(double pitch); + int setLocalVoiceEqualization(AUDIO_EQUALIZATION_BAND_FREQUENCY bandFrequency, int bandGain); + int setLocalVoiceReverb(AUDIO_REVERB_TYPE reverbKey, int value); + int setLocalVoiceChanger(VOICE_CHANGER_PRESET voiceChanger); + int setLocalVoiceReverbPreset(AUDIO_REVERB_PRESET reverbPreset); + int setAudioEffectPreset(AUDIO_EFFECT_PRESET preset); + int setVoiceBeautifierPreset(VOICE_BEAUTIFIER_PRESET preset); + int setAudioEffectParameters(AUDIO_EFFECT_PRESET preset, int param1, int param2); + int setVoiceBeautifierParameters(VOICE_BEAUTIFIER_PRESET preset, int param1, int param2); + int pauseAudio(); + int resumeAudio(); + int setHighQualityAudioParameters(bool fullband, bool stereo, bool fullBitrate); + int adjustRecordingSignalVolume(int volume /* [0, 400]: e.g. 50~0.5x 100~1x 400~4x */); + int adjustPlaybackSignalVolume(int volume /* [0, 400] */); + int enableAudioVolumeIndication(int interval, int smooth, bool report_vad); // in ms: <= 0: disable, > 0: enable, interval in ms + int muteLocalAudioStream(bool mute); + int muteRemoteAudioStream(uid_t uid, bool mute); + int muteAllRemoteAudioStreams(bool mute); + int setVoiceConversionPreset(VOICE_CONVERSION_PRESET preset); + int setDefaultMuteAllRemoteAudioStreams(bool mute); + int setExternalAudioSource(bool enabled, int sampleRate, int channels); + int setExternalAudioSink(bool enabled, int sampleRate, int channels); + int setLogFile(const char* filePath); + int setLogFilter(unsigned int filter); + int setLogFileSize(unsigned int fileSizeInKBytes); + int setLocalRenderMode(RENDER_MODE_TYPE renderMode); + int setRemoteRenderMode(uid_t uid, RENDER_MODE_TYPE renderMode); + int setCameraCapturerConfiguration(const CameraCapturerConfiguration& config); + int enableDualStreamMode(bool enabled); + int setRemoteVideoStreamType(uid_t uid, REMOTE_VIDEO_STREAM_TYPE streamType); + int setRemoteDefaultVideoStreamType(REMOTE_VIDEO_STREAM_TYPE streamType); + int setRecordingAudioFrameParameters(int sampleRate, int channel, RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall); + int setPlaybackAudioFrameParameters(int sampleRate, int channel, RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall); + int setMixedAudioFrameParameters(int sampleRate, int samplesPerCall); + int enableWebSdkInteroperability(bool enabled); // only for live broadcast - int setVideoQualityParameters(bool preferFrameRateOverImageQuality) { return setParameters("{\"rtc.video.prefer_frame_rate\":%s,\"che.video.prefer_frame_rate\":%s}", preferFrameRateOverImageQuality ? "true" : "false", preferFrameRateOverImageQuality ? "true" : "false"); } - - int setLocalVideoMirrorMode(VIDEO_MIRROR_MODE_TYPE mirrorMode) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - const char* value; - switch (mirrorMode) { - case VIDEO_MIRROR_MODE_AUTO: - value = "default"; - break; - case VIDEO_MIRROR_MODE_ENABLED: - value = "forceMirror"; - break; - case VIDEO_MIRROR_MODE_DISABLED: - value = "disableMirror"; - break; - default: - return -ERR_INVALID_ARGUMENT; - } - return m_parameter->setString("che.video.localViewMirrorSetting", value); - } - - int setLocalPublishFallbackOption(STREAM_FALLBACK_OPTIONS option) { return m_parameter ? m_parameter->setInt("rtc.local_publish_fallback_option", option) : -ERR_NOT_INITIALIZED; } - - int setRemoteSubscribeFallbackOption(STREAM_FALLBACK_OPTIONS option) { return m_parameter ? m_parameter->setInt("rtc.remote_subscribe_fallback_option", option) : -ERR_NOT_INITIALIZED; } - + int setVideoQualityParameters(bool preferFrameRateOverImageQuality); + int setLocalVideoMirrorMode(VIDEO_MIRROR_MODE_TYPE mirrorMode); + int setLocalPublishFallbackOption(STREAM_FALLBACK_OPTIONS option); + int setRemoteSubscribeFallbackOption(STREAM_FALLBACK_OPTIONS option); #if (defined(__APPLE__) && TARGET_OS_MAC && !TARGET_OS_IPHONE) || defined(_WIN32) - - int enableLoopbackRecording(bool enabled, const char* deviceName = NULL) { - if (!deviceName) { - return setParameters("{\"che.audio.loopback.recording\":%s}", enabled ? "true" : "false"); - } else { - return setParameters("{\"che.audio.loopback.deviceName\":\"%s\",\"che.audio.loopback.recording\":%s}", deviceName, enabled ? "true" : "false"); - } - } + int enableLoopbackRecording(bool enabled, const char* deviceName = NULL); #endif - - int setInEarMonitoringVolume(int volume) { return m_parameter ? m_parameter->setInt("che.audio.headset.monitoring.parameter", volume) : -ERR_NOT_INITIALIZED; } + int setInEarMonitoringVolume(int volume); protected: AParameter& parameter() { return m_parameter; } @@ -9547,11 +11200,275 @@ class RtcEngineParameters { va_end(args); return m_parameter ? m_parameter->setObject(key, buf) : -ERR_NOT_INITIALIZED; } - int stopAllRemoteVideo() { return m_parameter ? m_parameter->setBool("che.video.peer.stop_render", true) : -ERR_NOT_INITIALIZED; } private: AParameter m_parameter; }; +/** + * The format of the recording file. + * + * @since v3.5.2 + */ +enum MediaRecorderContainerFormat { + /** + * 1: (Default) MP4. + */ + FORMAT_MP4 = 1, + /** + * Reserved parameter. + */ + FORMAT_FLV = 2, +}; +/** + * The recording content. + * + * @since v3.5.2 + */ +enum MediaRecorderStreamType { + /** + * Only audio. + */ + STREAM_TYPE_AUDIO = 0x01, + /** + * Only video. + */ + STREAM_TYPE_VIDEO = 0x02, + /** + * (Default) Audio and video. + */ + STREAM_TYPE_BOTH = STREAM_TYPE_AUDIO | STREAM_TYPE_VIDEO, +}; +/** + * The current recording state. + * + * @since v3.5.2 + */ +enum RecorderState { + /** + * -1: An error occurs during the recording. See RecorderErrorCode for the reason. + */ + RECORDER_STATE_ERROR = -1, + /** + * 2: The audio and video recording is started. + */ + RECORDER_STATE_START = 2, + /** + * 3: The audio and video recording is stopped. + */ + RECORDER_STATE_STOP = 3, +}; +/** + * The reason for the state change + * + * @since v3.5.2 + */ +enum RecorderErrorCode { + /** + * 0: No error occurs. + */ + RECORDER_ERROR_NONE = 0, + /** + * 1: The SDK fails to write the recorded data to a file. + */ + RECORDER_ERROR_WRITE_FAILED = 1, + /** + * 2: The SDK does not detect audio and video streams to be recorded, or audio and video streams are interrupted for more than five seconds during recording. + */ + RECORDER_ERROR_NO_STREAM = 2, + /** + * 3: The recording duration exceeds the upper limit. + */ + RECORDER_ERROR_OVER_MAX_DURATION = 3, + /** + * 4: The recording configuration changes. + */ + RECORDER_ERROR_CONFIG_CHANGED = 4, + /** + * 5: The SDK detects audio and video streams from users using versions of the SDK earlier than v3.0.0 in + * the `COMMUNICATION` channel profile. + */ + RECORDER_ERROR_CUSTOM_STREAM_DETECTED = 5, +}; +/** + * Configurations for the local audio and video recording. + * + * @since v3.5.2 + */ +struct MediaRecorderConfiguration { + /** + * The absolute path (including the filename extensions) of the recording file. + * For example, `C:\Users\\AppData\Local\Agora\\example.mp4` on Windows, + * `/App Sandbox/Library/Caches/example.mp4` on iOS, `/Library/Logs/example.mp4` on macOS, and + * `/storage/emulated/0/Android/data//files/example.mp4` on Android. + * + * @note Ensure that the specified path exists and is writable. + */ + const char* storagePath; + /** + * The format of the recording file. See \ref agora::rtc::MediaRecorderContainerFormat "MediaRecorderContainerFormat". + */ + MediaRecorderContainerFormat containerFormat; + /** + * The recording content. See \ref agora::rtc::MediaRecorderStreamType "MediaRecorderStreamType". + */ + MediaRecorderStreamType streamType; + /** + * The maximum recording duration, in milliseconds. The default value is 120000. + */ + int maxDurationMs; + /** + * The interval (ms) of updating the recording information. The value range is + * [1000,10000]. Based on the set value of `recorderInfoUpdateInterval`, the + * SDK triggers the \ref IMediaRecorderObserver::onRecorderInfoUpdated "onRecorderInfoUpdated" + * callback to report the updated recording information. + */ + int recorderInfoUpdateInterval; + + MediaRecorderConfiguration() : storagePath(nullptr), containerFormat(FORMAT_MP4), streamType(STREAM_TYPE_BOTH), maxDurationMs(120000), recorderInfoUpdateInterval(0) {} + MediaRecorderConfiguration(const char* path, MediaRecorderContainerFormat format, MediaRecorderStreamType type, int duration, int interval) : storagePath(path), containerFormat(format), streamType(type), maxDurationMs(duration), recorderInfoUpdateInterval(interval) {} +}; +/** + * Information for the recording file. + * + * @since v3.5.2 + */ +struct RecorderInfo { + /** + * The absolute path of the recording file. + */ + const char* fileName; + /** + * The recording duration, in milliseconds. + */ + unsigned int durationMs; + /** + * The size in bytes of the recording file. + */ + unsigned int fileSize; + + RecorderInfo() = default; + RecorderInfo(const char* name, unsigned int dur, unsigned int size) : fileName(name), durationMs(dur), fileSize(size) {} +}; + +/** + * The IMediaRecorderObserver class. + * + * @since v3.5.2 + */ +class IMediaRecorderObserver { + public: + /** + * Occurs when the recording state changes. + * + * @since v3.5.2 + * + * When the local audio and video recording state changes, the SDK triggers this callback to report the current + * recording state and the reason for the change. + * + * @param state The current recording state. See \ref agora::rtc::RecorderState "RecorderState". + * @param error The reason for the state change. See \ref agora::rtc::RecorderErrorCode "RecorderErrorCode". + */ + virtual void onRecorderStateChanged(RecorderState state, RecorderErrorCode error) = 0; + /** + * Occurs when the recording information is updated. + * + * @since v3.5.2 + * + * After you successfully register this callback and enable the local audio and video recording, the SDK periodically triggers + * the `onRecorderInfoUpdated` callback based on the set value of `recorderInfoUpdateInterval`. This callback reports the + * filename, duration, and size of the current recording file. + * + * @param info Information for the recording file. See RecorderInfo. + * + */ + virtual void onRecorderInfoUpdated(const RecorderInfo& info){}; +}; +/** + * The IMediaRecorder class, for recording the audio and video on the client. IMediaRecorder can record the + * following content: + * - The audio captured by the local microphone and encoded in AAC format. + * - The video captured by the local camera and encoded by the SDK. + * + * @since v3.5.2 + * + * @note In the `COMMUNICATION` channel profile, this function is unavailable when there are users using versions of + * the SDK earlier than v3.0.0 in the channel. + */ +class IMediaRecorder { + public: + /** + * Gets the IMediaRecorder object. + * + * @since v3.5.2 + * + * @note Call this method after initializing the IRtcEngine object. + * + * @param engine IRtcEngine + * @param callback IMediaRecorderObserver + * + * @return IMediaRecorder + */ + AGORA_CPP_API static IMediaRecorder* getMediaRecorder(IRtcEngine* engine, IMediaRecorderObserver* callback); + /** + * Starts recording the local audio and video. + * + * @since v3.5.2 + * + * After successfully getting the object, you can call this method to enable the recording of the local audio and video. + * + * This method can record the following content: + * - The audio captured by the local microphone and encoded in AAC format. + * - The video captured by the local camera and encoded by the SDK. + * + * The SDK can generate a recording file only when it detects the recordable audio and video streams; when there are + * no audio and video streams to be recorded or the audio and video streams are interrupted for more than five + * seconds, the SDK stops recording and triggers the + * \ref IMediaRecorderObserver::onRecorderStateChanged "onRecorderStateChanged" (RECORDER_STATE_ERROR, RECORDER_ERROR_NO_STREAM) + * callback. + * + * @note Call this method after joining the channel. + * + * @param config The recording configurations. See MediaRecorderConfiguration. + * + * @return + * - 0(ERR_OK): Success. + * - < 0: Failure: + * - `-2(ERR_INVALID_ARGUMENT)`: The parameter is invalid. Ensure the following: + * - The specified path of the recording file exists and is writable. + * - The specified format of the recording file is supported. + * - The maximum recording duration is correctly set. + * - `-4(ERR_NOT_SUPPORTED)`: IRtcEngine does not support the request due to one of the following reasons: + * - The recording is ongoing. + * - The recording stops because an error occurs. + * - `-7(ERR_NOT_INITIALIZED)`: This method is called before the initialization of IRtcEngine. Ensure that you have + * called \ref IMediaRecorder::getMediaRecorder "getMediaRecorder" before calling `startRecording`. + */ + virtual int startRecording(const MediaRecorderConfiguration& config) = 0; + /** + * Stops recording the local audio and video. + * + * @since v3.5.2 + * + * @note Call this method after calling \ref IMediaRecorder::startRecording "startRecording". + * + * @return + * - 0(ERR_OK): Success. + * - < 0: Failure: + * - `-7(ERR_NOT_INITIALIZED)`: This method is called before the initialization of IRtcEngine. Ensure that you have + * called \ref IMediaRecorder::getMediaRecorder "getMediaRecorder" before calling `stopRecording`. + */ + virtual int stopRecording() = 0; + /** + * Releases the IMediaRecorder object. + * + * @since v3.5.2 + * + * This method releases the IRtcEngine object and all other resources used by the IMediaRecorder object. After calling + * this method, if you want to enable the recording again, you must call + * \ref IMediaRecorder::getMediaRecorder "getMediaRecorder" to get the IMediaRecorder object. + */ + virtual void releaseRecorder() = 0; +}; } // namespace rtc } // namespace agora diff --git a/Android/APIExample/lib-raw-data/src/main/cpp/include/IAgoraService.h b/Android/APIExample/lib-raw-data/src/main/cpp/include/IAgoraService.h index 61420d53f..555ed8866 100644 --- a/Android/APIExample/lib-raw-data/src/main/cpp/include/IAgoraService.h +++ b/Android/APIExample/lib-raw-data/src/main/cpp/include/IAgoraService.h @@ -34,7 +34,7 @@ class IAgoraService { */ virtual int initialize(const AgoraServiceContext& context) = 0; - /** Retrieves the SDK version number. + /** Gets the SDK version number. * @param build Build number. * @return The current SDK version in the string format. For example, 2.4.0 */ diff --git a/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/AgoraBase.h b/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/AgoraBase.h index c729bf7da..aad4a83fe 100644 --- a/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/AgoraBase.h +++ b/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/AgoraBase.h @@ -13,7 +13,9 @@ #include #if defined(_WIN32) +#ifndef WIN32_LEAN_AND_MEAN #define WIN32_LEAN_AND_MEAN +#endif #include #define AGORA_CALL __cdecl #if defined(AGORARTC_EXPORT) @@ -38,6 +40,20 @@ #define AGORA_CALL #endif +#ifdef __GNUC__ +#define AGORA_GCC_VERSION_AT_LEAST(x, y) (__GNUC__ > (x) || __GNUC__ == (x) && __GNUC_MINOR__ >= (y)) +#else +#define AGORA_GCC_VERSION_AT_LEAST(x, y) 0 +#endif + +#if AGORA_GCC_VERSION_AT_LEAST(3, 1) +#define AGORA_DEPRECATED_ATTRIBUTE __attribute__((deprecated)) +#elif defined(_MSC_VER) +#define AGORA_DEPRECATED_ATTRIBUTE +#else +#define AGORA_DEPRECATED_ATTRIBUTE +#endif + namespace agora { namespace util { @@ -220,6 +236,9 @@ enum WARN_CODE_TYPE { /** 1053: Audio Processing Module: A residual echo is detected, which may be caused by the belated scheduling of system threads or the signal overflow. */ WARN_APM_RESIDUAL_ECHO = 1053, + /** 1054: Audio Processing Module: AI NS is closed, this can be triggered by manual settings or by performance detection modules. + */ + WARN_APM_AINS_CLOSED = 1054, /// @cond WARN_ADM_WIN_CORE_NO_RECORDING_DEVICE = 1322, /// @endcond @@ -234,13 +253,13 @@ enum WARN_CODE_TYPE { * - Update the sound card drive. */ WARN_ADM_WIN_CORE_IMPROPER_CAPTURE_RELEASE = 1324, - /** 1610: The origin resolution of the remote video is beyond the range where the super-resolution algorithm can be applied. + /** 1610: The original resolution of the remote user's video is beyond the range where super resolution can be applied. */ WARN_SUPER_RESOLUTION_STREAM_OVER_LIMITATION = 1610, - /** 1611: Another user is already using the super-resolution algorithm. + /** 1611: Super resolution is already being used to boost another remote user's video. */ WARN_SUPER_RESOLUTION_USER_COUNT_OVER_LIMITATION = 1611, - /** 1612: The device does not support the super-resolution algorithm. + /** 1612: The device does not support using super resolution. */ WARN_SUPER_RESOLUTION_DEVICE_NOT_SUPPORTED = 1612, /// @cond @@ -379,7 +398,8 @@ enum ERROR_CODE_TYPE { /** 117: The data stream transmission timed out. */ ERR_STREAM_MESSAGE_TIMEOUT = 117, - /** 119: Switching roles fail. Please try to rejoin the channel. + /** **DEPRECATED** 119: Deprecated as of v3.6.1. Use CLIENT_ROLE_CHANGE_FAILED_REASON in the \ref agora::rtc::IRtcEngineEventHandler::onClientRoleChangeFailed "onClientRoleChangeFailed" callback instead. + * Switching roles fail. Please try to rejoin the channel. */ ERR_SET_CLIENT_ROLE_NOT_AUTHORIZED = 119, /** 120: Decryption fails. The user may have used a different encryption password to join the channel. Check your settings or try rejoining the channel. @@ -411,7 +431,6 @@ enum ERROR_CODE_TYPE { ERR_ENCRYPTED_STREAM_NOT_ALLOWED_PUBLISH = 130, /** 134: The user account is invalid. */ ERR_INVALID_USER_ACCOUNT = 134, - /** 151: CDN related errors. Remove the original URL address and add a new one by calling the \ref agora::rtc::IRtcEngine::removePublishStreamUrl "removePublishStreamUrl" and \ref agora::rtc::IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" methods. */ ERR_PUBLISH_STREAM_CDN_ERROR = 151, @@ -436,16 +455,13 @@ enum ERROR_CODE_TYPE { * */ ERR_MODULE_NOT_FOUND = 157, - /// @cond - /** 158: The dynamical library for the super-resolution algorithm is not integrated. - * When you call the \ref agora::rtc::IRtcEngine::enableRemoteSuperResolution "enableRemoteSuperResolution" method but - * do not integrate the dynamical library for the super-resolution algorithm - * into your project, the SDK reports this error code. - */ - ERR_MODULE_SUPER_RESOLUTION_NOT_FOUND = 158, - /// @endcond - /** 160: The recording operation has been performed. + /** 160: The client is already recording audio. To start a new recording, + * call \ref agora::rtc::IRtcEngine::stopAudioRecording "stopAudioRecording" to stop + * the current recording first, and then + * call \ref agora::rtc::IRtcEngine::startAudioRecording(const AudioRecordingConfiguration&) "startAudioRecording". + * + * @since v3.4.0 */ ERR_ALREADY_IN_RECORDING = 160, @@ -708,10 +724,11 @@ enum ERROR_CODE_TYPE { ERR_ADM_NO_PLAYOUT_DEVICE = 1360, // VDM error code starts from 1500 - + /// @cond /** 1500: Video Device Module: There is no camera device. */ ERR_VDM_CAMERA_NO_DEVICE = 1500, + /// @endcond /** 1501: Video Device Module: The camera is unauthorized. */ @@ -735,6 +752,12 @@ enum ERROR_CODE_TYPE { /** 1603: Video Device Module: An error occurs in setting the video encoder. */ ERR_VCM_ENCODER_SET_ERROR = 1603, + /** 1735: (Windows only) The Windows Audio service is disabled. You need to + * either enable the Windows Audio service or restart the device. + * + * @since v3.5.0 + */ + ERR_ADM_WIN_CORE_SERVRE_SHUT_DOWN = 1735, }; /** Output log filter level. */ @@ -764,7 +787,7 @@ enum LOG_FILTER_TYPE { * @since v3.3.0 */ enum class LOG_LEVEL { - /** 0: Do not output any log. */ + /** 0x0000: Do not output any log. */ LOG_LEVEL_NONE = 0x0000, /** 0x0001: (Default) Output logs of the FATAL, ERROR, WARN and INFO level. We recommend setting your log filter as this level. */ diff --git a/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/IAgoraMediaEngine.h b/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/IAgoraMediaEngine.h index 9690d8840..6f7fd88c2 100644 --- a/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/IAgoraMediaEngine.h +++ b/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/IAgoraMediaEngine.h @@ -1,6 +1,7 @@ #ifndef AGORA_MEDIA_ENGINE_H #define AGORA_MEDIA_ENGINE_H #include +#include "AgoraBase.h" namespace agora { namespace media { @@ -15,11 +16,64 @@ enum MEDIA_SOURCE_TYPE { AUDIO_RECORDING_SOURCE = 1, }; +/** + * The channel mode. Set in \ref agora::rtc::IRtcEngine::setAudioMixingDualMonoMode "setAudioMixingDualMonoMode". + * + * @since v3.5.1 + */ +enum AUDIO_MIXING_DUAL_MONO_MODE { + /** + * 0: Original mode. + */ + AUDIO_MIXING_DUAL_MONO_AUTO = 0, + /** + * 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_MIXING_DUAL_MONO_L = 1, + /** + * 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_MIXING_DUAL_MONO_R = 2, + /** + * 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. + */ + AUDIO_MIXING_DUAL_MONO_MIX = 3 +}; +/** + * The push position of the external audio frame. + * Set in \ref IMediaEngine::pushAudioFrame(int32_t, IAudioFrameObserver::AudioFrame*) "pushAudioFrame" + * or \ref IMediaEngine::setExternalAudioSourceVolume "setExternalAudioSourceVolume". + * + * @since v3.5.1 + */ +enum AUDIO_EXTERNAL_SOURCE_POSITION { + /** 0: The position before local playback. If you need to play the external audio frame on the local client, + * set this position. + */ + AUDIO_EXTERNAL_PLAYOUT_SOURCE = 0, + /** 1: The position after audio capture and before audio pre-processing. If you need the audio module of the SDK + * to process the external audio frame, set this position. + */ + AUDIO_EXTERNAL_RECORD_SOURCE_PRE_PROCESS = 1, + /** 2: The position after audio pre-processing and before audio encoding. If you do not need the audio module of + * the SDK to process the external audio frame, set this position. + */ + AUDIO_EXTERNAL_RECORD_SOURCE_POST_PROCESS = 2, +}; + /** * The IAudioFrameObserver class. */ class IAudioFrameObserver { public: + IAudioFrameObserver() {} + virtual ~IAudioFrameObserver() {} /** The frame type. */ enum AUDIO_FRAME_TYPE { /** 0: PCM16. */ @@ -59,43 +113,64 @@ class IAudioFrameObserver { }; public: - /** Retrieves the captured audio frame. - - @param audioFrame Pointer to AudioFrame. - @return - - true: Valid buffer in AudioFrame, and the captured audio frame is sent out. - - false: Invalid buffer in AudioFrame, and the captured audio frame is discarded. + /** Gets the captured audio frame. + * + * @note To ensure that the captured audio frame has the expected format, + * Agora recommends that you + * call \ref agora::rtc::IRtcEngine::setRecordingAudioFrameParameters "setRecordingAudioFrameParameters" + * after calling \ref IMediaEngine::registerAudioFrameObserver "registerAudioFrameObserver" to + * set the audio capturing format. + * + * @param audioFrame Pointer to AudioFrame. + * @return + * - true: Valid buffer in AudioFrame, and the captured audio frame is sent out. + * - false: Invalid buffer in AudioFrame, and the captured audio frame is discarded. */ virtual bool onRecordAudioFrame(AudioFrame& audioFrame) = 0; - /** Retrieves the audio playback frame for getting the audio. - - @param audioFrame Pointer to AudioFrame. - @return - - true: Valid buffer in AudioFrame, and the audio playback frame is sent out. - - false: Invalid buffer in AudioFrame, and the audio playback frame is discarded. + /** Gets the audio playback frame for getting the audio. + * + * @note To ensure that the audio playback frame has the expected format, Agora + * recommends that you call \ref agora::rtc::IRtcEngine::setPlaybackAudioFrameParameters "setPlaybackAudioFrameParameters" + * after calling \ref IMediaEngine::registerAudioFrameObserver "registerAudioFrameObserver" to + * set the audio playback format. + * + * @param audioFrame Pointer to AudioFrame. + * @return + * - true: Valid buffer in AudioFrame, and the audio playback frame is sent out. + * - false: Invalid buffer in AudioFrame, and the audio playback frame is discarded. */ virtual bool onPlaybackAudioFrame(AudioFrame& audioFrame) = 0; - /** Retrieves the mixed captured and playback audio frame. - - - @note This callback only returns the single-channel data. - - @param audioFrame Pointer to AudioFrame. - @return - - true: Valid buffer in AudioFrame and the mixed captured and playback audio frame is sent out. - - false: Invalid buffer in AudioFrame and the mixed captured and playback audio frame is discarded. + /** Gets the mixed captured and playback audio frame. + * + * @note + * - This callback only returns the single-channel data. + * - To ensure that the mixed captured and playback audio frame has the + * expected format, Agora recommends that you call + * \ref agora::rtc::IRtcEngine::setMixedAudioFrameParameters "setMixedAudioFrameParameters" + * after calling \ref IMediaEngine::registerAudioFrameObserver "registerAudioFrameObserver" to + * set the mixed audio format. + * + * @param audioFrame Pointer to AudioFrame. + * @return + * - true: Valid buffer in AudioFrame and the mixed captured and playback audio frame is sent out. + * - false: Invalid buffer in AudioFrame and the mixed captured and playback audio frame is discarded. */ virtual bool onMixedAudioFrame(AudioFrame& audioFrame) = 0; - /** Retrieves the audio frame of a specified user before mixing. - - The SDK triggers this callback if isMultipleChannelFrameWanted returns false. - - @param uid The user ID - @param audioFrame Pointer to AudioFrame. - @return - - true: Valid buffer in AudioFrame, and the mixed captured and playback audio frame is sent out. - - false: Invalid buffer in AudioFrame, and the mixed captured and playback audio frame is discarded. - */ + /** Gets the audio frame of a specified user before mixing. + * + * The SDK triggers this callback if \ref IAudioFrameObserver::isMultipleChannelFrameWanted "isMultipleChannelFrameWanted" returns false. + * + * @note To ensure that the audio playback frame has the expected format, Agora + * recommends that you call \ref agora::rtc::IRtcEngine::setPlaybackAudioFrameParameters "setPlaybackAudioFrameParameters" + * after calling \ref IMediaEngine::registerAudioFrameObserver "registerAudioFrameObserver" to + * set the audio playback format. + * + * @param uid The user ID + * @param audioFrame Pointer to AudioFrame. + * @return + * - true: Valid buffer in AudioFrame, and the mixed captured and playback audio frame is sent out. + * - false: Invalid buffer in AudioFrame, and the mixed captured and playback audio frame is discarded. + */ virtual bool onPlaybackAudioFrameBeforeMixing(unsigned int uid, AudioFrame& audioFrame) = 0; /** Determines whether to receive audio data from multiple channels. @@ -121,18 +196,23 @@ class IAudioFrameObserver { virtual bool isMultipleChannelFrameWanted() { return false; } /** Gets the before-mixing playback audio frame from multiple channels. - - After you successfully register the audio frame observer, if you set the return - value of \ref IAudioFrameObserver::isMultipleChannelFrameWanted "isMultipleChannelFrameWanted" as true, the SDK triggers this callback each - time it receives a before-mixing audio frame from any of the channel. - - @param channelId The channel ID of this audio frame. - @param uid The ID of the user sending this audio frame. - @param audioFrame The pointer to AudioFrame. - @return - - `true`: The data in AudioFrame is valid, and send this audio frame. - - `false`: The data in AudioFrame in invalid, and do not send this audio frame. - */ + * + * After you successfully register the audio frame observer, if you set the return + * value of \ref IAudioFrameObserver::isMultipleChannelFrameWanted "isMultipleChannelFrameWanted" as true, the SDK triggers this callback each + * time it receives a before-mixing audio frame from any of the channel. + * + * @note To ensure that the audio playback frame has the expected format, Agora + * recommends that you call \ref agora::rtc::IRtcEngine::setPlaybackAudioFrameParameters "setPlaybackAudioFrameParameters" + * after calling \ref IMediaEngine::registerAudioFrameObserver "registerAudioFrameObserver" to + * set the audio playback format. + * + * @param channelId The channel ID of this audio frame. + * @param uid The ID of the user sending this audio frame. + * @param audioFrame The pointer to AudioFrame. + * @return + * - `true`: The data in AudioFrame is valid, and send this audio frame. + * - `false`: The data in AudioFrame in invalid, and do not send this audio frame. + */ virtual bool onPlaybackAudioFrameBeforeMixingEx(const char* channelId, unsigned int uid, AudioFrame& audioFrame) { return true; } }; @@ -141,14 +221,16 @@ class IAudioFrameObserver { */ class IVideoFrameObserver { public: + IVideoFrameObserver() {} + virtual ~IVideoFrameObserver() {} /** The video frame type. */ enum VIDEO_FRAME_TYPE { /** - * 0: YUV420 + * 0: (Default) YUV 420 */ FRAME_TYPE_YUV420 = 0, // YUV 420 format /** - * 1: YUV422 + * 1: YUV 422 */ FRAME_TYPE_YUV422 = 1, // YUV 422 format /** @@ -173,7 +255,7 @@ class IVideoFrameObserver { */ POSITION_PRE_ENCODER = 1 << 2, }; - /** Video frame information. The video data format is YUV420. The buffer provides a pointer to a pointer. The interface cannot modify the pointer of the buffer, but can modify the content of the buffer only. + /** Video frame information. The video data format is YUV 420. The buffer provides a pointer to a pointer. The interface cannot modify the pointer of the buffer, but can modify the content of the buffer only. */ struct VideoFrame { VIDEO_FRAME_TYPE type; @@ -183,32 +265,37 @@ class IVideoFrameObserver { /** Video pixel height. */ int height; // height of video frame - /** Line span of the Y buffer within the YUV data. + /** + * For YUV data, the line span of the Y buffer; for RGBA data, the total data length. */ int yStride; // stride of Y data buffer - /** Line span of the U buffer within the YUV data. + /** + * For YUV data, the line span of the U buffer; for RGBA data, the value is 0. */ int uStride; // stride of U data buffer - /** Line span of the V buffer within the YUV data. + /** + * For YUV data, the line span of the V buffer; for RGBA data, the value is 0. */ int vStride; // stride of V data buffer - /** Pointer to the Y buffer pointer within the YUV data. + /** + * For YUV data, the pointer to the Y buffer; for RGBA data, the data buffer. */ void* yBuffer; // Y data buffer - /** Pointer to the U buffer pointer within the YUV data. + /** + * For YUV data, the pointer to the U buffer; for RGBA data, the value is 0. */ void* uBuffer; // U data buffer - /** Pointer to the V buffer pointer within the YUV data. + /** + * For YUV data, the pointer to the V buffer; for RGBA data, the value is 0. */ void* vBuffer; // V data buffer - /** Set the rotation of this frame before rendering the video. Supports 0, 90, 180, 270 degrees clockwise. + /** The clockwise rotation angle of the video frame. The supported values are 0, 90, 180, or 270 degrees. */ int rotation; // rotation of this frame (0, 90, 180, 270) - /** The timestamp (ms) of the external audio frame. It is mandatory. You can use this parameter for the following purposes: - - Restore the order of the captured audio frame. - - Synchronize audio and video frames in video-related scenarios, including scenarios where external video sources are used. - @note This timestamp is for rendering the video stream, and not for capturing the video stream. - */ + /** + * The Unix timestamp (ms) when the video frame is rendered. This timestamp can be used to guide the rendering of + * the video frame. This parameter is required. + */ int64_t renderTimeMs; int avsync_type; }; @@ -226,9 +313,9 @@ class IVideoFrameObserver { * - The video data that this callback gets has not been pre-processed, without the watermark, the cropped content, the rotation, and the image enhancement. * * @param videoFrame Pointer to VideoFrame. - * @return Whether or not to ignore the current video frame if the pre-processing fails: - * - true: Do not ignore. - * - false: Ignore the current video frame, and do not send it back to the SDK. + * @return + * - true: Sets the SDK to receive the video frame. + * - false: Sets the SDK to discard the video frame. */ virtual bool onCaptureVideoFrame(VideoFrame& videoFrame) = 0; /** @since v3.0.0 @@ -245,15 +332,18 @@ class IVideoFrameObserver { * - This callback does not support sending processed RGBA video data back to the SDK. * * @param videoFrame A pointer to VideoFrame - * @return Whether to ignore the current video frame if the processing fails: - * - true: Do not ignore the current video frame. - * - false: Ignore the current video frame, and do not send it back to the SDK. + * @return + * - true: Sets the SDK to receive the video frame. + * - false: Sets the SDK to discard the video frame. */ virtual bool onPreEncodeVideoFrame(VideoFrame& videoFrame) { return true; } /** Occurs each time the SDK receives a video frame sent by the remote user. * - * After you successfully register the video frame observer and isMultipleChannelFrameWanted return false, the SDK triggers this callback each time a video frame is received. - * In this callback, you can get the video data sent by the remote user. You can then post-process the data according to your scenarios. + * After you successfully register the video frame observer and + * \ref IVideoFrameObserver::isMultipleChannelFrameWanted "isMultipleChannelFrameWanted" + * return false, the SDK triggers this callback each time a video frame is received. + * In this callback, you can get the video data sent by the remote user. You can then + * post-process the data according to your scenarios. * * After post-processing, you can send the processed data back to the SDK by setting the `videoFrame` parameter in this callback. * @@ -262,67 +352,73 @@ class IVideoFrameObserver { * * @param uid ID of the remote user who sends the current video frame. * @param videoFrame Pointer to VideoFrame. - * @return Whether or not to ignore the current video frame if the post-processing fails: - * - true: Do not ignore. - * - false: Ignore the current video frame, and do not send it back to the SDK. + * @return + * - true: Sets the SDK to receive the video frame. + * - false: Sets the SDK to discard the video frame. */ virtual bool onRenderVideoFrame(unsigned int uid, VideoFrame& videoFrame) = 0; /** Occurs each time the SDK receives a video frame and prompts you to set the video format. * - * YUV420 is the default video format. If you want to receive other video formats, register this callback in the IVideoFrameObserver class. + * YUV 420 is the default video format. If you want to receive other video formats, register this callback in the IVideoFrameObserver class. * * After you successfully register the video frame observer, the SDK triggers this callback each time it receives a video frame. * You need to set your preferred video data in the return value of this callback. * * @return Sets the video format: #VIDEO_FRAME_TYPE - * - #FRAME_TYPE_YUV420 (0): (Default) YUV420. - * - #FRAME_TYPE_RGBA (2): RGBA */ virtual VIDEO_FRAME_TYPE getVideoFormatPreference() { return FRAME_TYPE_YUV420; } - /** Occurs each time the SDK receives a video frame and prompts you whether or not to rotate the captured video according to the rotation member in the VideoFrame class. + /** Occurs each time the SDK receives a video frame and prompts you whether to + * rotate the raw video frame according to the rotation member in the VideoFrame class. * - * The SDK does not rotate the captured video by default. If you want to rotate the captured video according to the rotation member in the VideoFrame class, register this callback in the IVideoFrameObserver class. + * The SDK does not rotate the raw video frame by default. If you want to receive + * the raw video frame rotated according to the rotation member in the VideoFrame + * class, register this callback in the IVideoFrameObserver class. * - * After you successfully register the video frame observer, the SDK triggers this callback each time it receives a video frame. You need to set whether or not to rotate the video frame in the return value of this callback. + * After you successfully register the video frame observer, the SDK triggers this + * callback each time it receives a video frame. You need to set whether to rotate + * the raw video frame in the return value of this callback. * - * @note - * This callback applies to RGBA video data only. + * @note This callback applies to the video frame in the YUV 420 and RGBA formats only. * - * @return Sets whether or not to rotate the captured video: + * @return Sets whether to rotate the raw video frame: * - true: Rotate. - * - false: （Default) Do not rotate. + * - false: (Default) Do not rotate. */ virtual bool getRotationApplied() { return false; } - /** Occurs each time the SDK receives a video frame and prompts you whether or not to mirror the captured video. + /** Occurs each time the SDK receives a video frame and prompts you whether to mirror the raw video frame. * - * The SDK does not mirror the captured video by default. Register this callback in the IVideoFrameObserver class if you want to mirror the captured video. + * The SDK does not mirror the raw video frame by default. If you want to receive the raw video frame mirrored, register this callback in the IVideoFrameObserver class. * * After you successfully register the video frame observer, the SDK triggers this callback each time a video frame is received. - * You need to set whether or not to mirror the captured video in the return value of this callback. + * You need to set whether to mirror the raw video frame in the return value of this callback. * - * @note - * This callback applies to RGBA video data only. + * @note This callback applies to the video frame in the YUV 420 and RGBA formats only. * - * @return Sets whether or not to mirror the captured video: + * @return Sets whether to mirror the raw video frame: * - true: Mirror. * - false: (Default) Do not mirror. */ virtual bool getMirrorApplied() { return false; } - /** @since v3.0.0 - - Sets whether to output the acquired video frame smoothly. - - If you want the video frames acquired from \ref IVideoFrameObserver::onRenderVideoFrame "onRenderVideoFrame" to be more evenly spaced, you can register the `getSmoothRenderingEnabled` callback in the `IVideoFrameObserver` class and set its return value as `true`. - - @note - - Register this callback before joining a channel. - - This callback applies to scenarios where the acquired video frame is self-rendered after being processed, not to scenarios where the video frame is sent back to the SDK after being processed. - - @return Set whether or not to smooth the video frames: - - true: Smooth the video frame. - - false: (Default) Do not smooth. + /** + * Sets whether to output the acquired video frame smoothly. + * + * @since v3.0.0 + * + * @deprecated As of v3.2.0, this callback function is deprecated, and the SDK + * smooths the video frames output by `onRenderVideoFrame` and `onRenderVideoFrameEx` by default. + * + * If you want the video frames acquired from `onRenderVideoFrame` + * or `onRenderVideoFrameEx` to be more evenly spaced, you can register the `getSmoothRenderingEnabled` callback in the `IVideoFrameObserver` class and set its return value as `true`. + * + * @note + * - Register this callback before joining a channel. + * - This callback applies to scenarios where the acquired video frame is self-rendered after being processed, not to scenarios where the video frame is sent back to the SDK after being processed. + * + * @return Set whether to smooth the video frames: + * - true: Smooth the video frame. + * - false: (Default) Do not smooth. */ - virtual bool getSmoothRenderingEnabled() { return false; } + virtual bool getSmoothRenderingEnabled() AGORA_DEPRECATED_ATTRIBUTE { return false; } /** * Sets the frame position for the video observer. * @since v3.0.1 @@ -334,7 +430,7 @@ class IVideoFrameObserver { * - `POSITION_PRE_ENCODER(1 << 2)`: The position before encoding the video data, which corresponds to the \ref onPreEncodeVideoFrame "onPreEncodeVideoFrame" callback. * * @note - * - Use '|' (the OR operator) to observe multiple frame positions. + * - To observe multiple frame positions, use '|' (the OR operator). * - This callback observes `POSITION_POST_CAPTURER(1 << 0)` and `POSITION_PRE_RENDERER(1 << 1)` by default. * - To conserve the system consumption, you can reduce the number of frame positions that you want to observe. * @@ -345,6 +441,8 @@ class IVideoFrameObserver { /** Determines whether to receive video data from multiple channels. + @since v3.0.1 + After you register the video frame observer, the SDK triggers this callback every time it captures a video frame. @@ -364,22 +462,22 @@ class IVideoFrameObserver { virtual bool isMultipleChannelFrameWanted() { return false; } /** Gets the video frame from multiple channels. - - After you successfully register the video frame observer, if you set the return value of - \ref IVideoFrameObserver::isMultipleChannelFrameWanted "isMultipleChannelFrameWanted" as true, the SDK triggers this callback each time it receives a video frame - from any of the channel. - - You can process the video data retrieved from this callback according to your scenario, and send the - processed data back to the SDK using the `videoFrame` parameter in this callback. - - @note This callback does not support sending RGBA video data back to the SDK. - - @param channelId The channel ID of this video frame. - @param uid The ID of the user sending this video frame. - @param videoFrame The pointer to VideoFrame. - @return Whether to send this video frame to the SDK if post-processing fails: - - `true`: Send this video frame. - - `false`: Do not send this video frame. + * + * After you successfully register the video frame observer, if you set the return value of + * \ref IVideoFrameObserver::isMultipleChannelFrameWanted "isMultipleChannelFrameWanted" as true, the SDK triggers this callback each time it receives a video frame + * from any of the channel. + * + * You can process the video data retrieved from this callback according to your scenario, and send the + * processed data back to the SDK using the `videoFrame` parameter in this callback. + * + * @note This callback does not support sending RGBA video data back to the SDK. + * + * @param channelId The channel ID of this video frame. + * @param uid The ID of the user sending this video frame. + * @param videoFrame The pointer to VideoFrame. + * @return + * - true: Sets the SDK to receive the video frame. + * - false: Sets the SDK to discard the video frame. */ virtual bool onRenderVideoFrameEx(const char* channelId, unsigned int uid, VideoFrame& videoFrame) { return true; } }; @@ -432,26 +530,26 @@ class IVideoFrame { - < 0: Failure. */ virtual int convertFrame(VIDEO_TYPE dst_video_type, int dst_sample_size, unsigned char* dst_frame) const = 0; - /** Retrieves the specified component in the YUV space. + /** Gets the specified component in the YUV space. @param type Component type: #PLANE_TYPE */ virtual int allocated_size(PLANE_TYPE type) const = 0; - /** Retrieves the stride of the specified component in the YUV space. + /** Gets the stride of the specified component in the YUV space. @param type Component type: #PLANE_TYPE */ virtual int stride(PLANE_TYPE type) const = 0; - /** Retrieves the width of the frame. + /** Gets the width of the frame. */ virtual int width() const = 0; - /** Retrieves the height of the frame. + /** Gets the height of the frame. */ virtual int height() const = 0; - /** Retrieves the timestamp (ms) of the frame. + /** Gets the timestamp (ms) of the frame. */ virtual unsigned int timestamp() const = 0; - /** Retrieves the render time (ms). + /** Gets the render time (ms). */ virtual int64_t render_time_ms() const = 0; /** Checks if a plane is of zero size. @@ -519,12 +617,19 @@ class IExternalVideoRenderFactory { /** The external video frame. */ struct ExternalVideoFrame { - /** The video buffer type. + /** + * The data type of the video frame. + * + * @since v3.5.0 */ enum VIDEO_BUFFER_TYPE { - /** 1: The video buffer in the format of raw data. + /** 1: The data type is raw data. */ VIDEO_BUFFER_RAW_DATA = 1, + /** + * 2: The data type is the pixel. + */ + VIDEO_BUFFER_PIXEL_BUFFER = 2 }; /** The video pixel format. @@ -559,6 +664,12 @@ struct ExternalVideoFrame { /** 16: The video pixel format is I422. */ VIDEO_PIXEL_I422 = 16, + /** 17: The video pixel format is GL_TEXTURE_2D. + */ + VIDEO_TEXTURE_2D = 17, + /** 18: The video pixel format is GL_TEXTURE_OES. + */ + VIDEO_TEXTURE_OES = 18, }; /** The buffer type. See #VIDEO_BUFFER_TYPE @@ -597,56 +708,143 @@ struct ExternalVideoFrame { ExternalVideoFrame() : cropLeft(0), cropTop(0), cropRight(0), cropBottom(0), rotation(0) {} }; +/** + * The video frame type. + * + * @since v3.4.5 + */ +enum CODEC_VIDEO_FRAME_TYPE { + /** + * 0: (Default) A black frame + */ + CODEC_VIDEO_FRAME_TYPE_BLANK_FRAME = 0, + /** + * 3: The keyframe + */ + CODEC_VIDEO_FRAME_TYPE_KEY_FRAME = 3, + /** + * 4: The delta frame + */ + CODEC_VIDEO_FRAME_TYPE_DELTA_FRAME = 4, + /** + * 5: The B-frame + */ + CODEC_VIDEO_FRAME_TYPE_B_FRAME = 5, + /** + * Unknown frame + */ + CODEC_VIDEO_FRAME_TYPE_UNKNOW +}; -enum CODEC_VIDEO_FRAME_TYPE { CODEC_VIDEO_FRAME_TYPE_BLANK_FRAME = 0, CODEC_VIDEO_FRAME_TYPE_KEY_FRAME = 3, CODEC_VIDEO_FRAME_TYPE_DELTA_FRAME = 4, CODEC_VIDEO_FRAME_TYPE_B_FRAME = 5, CODEC_VIDEO_FRAME_TYPE_UNKNOW }; - -enum VIDEO_ROTATION { VIDEO_ROTATION_0 = 0, VIDEO_ROTATION_90 = 90, VIDEO_ROTATION_180 = 180, VIDEO_ROTATION_270 = 270 }; +/** + * The clockwise rotation angle of the video frame. + * + * @since v3.4.5 + */ +enum VIDEO_ROTATION { + /** + * 0: 0 degree + */ + VIDEO_ROTATION_0 = 0, + /** + * 90: 90 degrees + */ + VIDEO_ROTATION_90 = 90, + /** + * 180: 180 degrees + */ + VIDEO_ROTATION_180 = 180, + /** + * 270: 270 degrees + */ + VIDEO_ROTATION_270 = 270 +}; -/** Video codec types */ +/** + * The video codec type. + * + * @since v3.4.5 + */ enum VIDEO_CODEC_TYPE { - /** Standard VP8 */ + /** 1: VP8 */ VIDEO_CODEC_VP8 = 1, - /** Standard H264 */ + /** 2: (Default) H.264 */ VIDEO_CODEC_H264 = 2, - /** Enhanced VP8 */ + /** 3: Enhanced VP8 */ VIDEO_CODEC_EVP = 3, - /** Enhanced H264 */ + /** 4: Enhanced H.264 */ VIDEO_CODEC_E264 = 4, }; -/** * The struct of VideoEncodedFrame. */ +/** + * The VideoEncodedFrame struct. + * + * @since v3.4.5 + */ struct VideoEncodedFrame { VideoEncodedFrame() : codecType(VIDEO_CODEC_H264), width(0), height(0), buffer(nullptr), length(0), frameType(CODEC_VIDEO_FRAME_TYPE_BLANK_FRAME), rotation(VIDEO_ROTATION_0), renderTimeMs(0) {} /** - * The video codec: #VIDEO_CODEC_TYPE. + * The video codec type. See #VIDEO_CODEC_TYPE. */ VIDEO_CODEC_TYPE codecType; - /** * The width (px) of the video. */ + /** + * The width (px) of the video. + */ int width; - /** * The height (px) of the video. */ + /** + * The height (px) of the video. + */ int height; - /** * The buffer of video encoded frame */ + /** + * The video buffer, which is in the `DirectByteBuffer` data type. + */ const uint8_t* buffer; - /** * The Length of video encoded frame buffer. */ + /** + * The length (in bytes) of the video buffer. + */ unsigned int length; - /** * The frame type of the encoded video frame: #VIDEO_FRAME_TYPE. */ + /** + * The video frame type. See #CODEC_VIDEO_FRAME_TYPE. + */ CODEC_VIDEO_FRAME_TYPE frameType; - /** * The rotation information of the encoded video frame: #VIDEO_ROTATION. */ + /** + * The clockwise rotation angle of the video frame. See #VIDEO_ROTATION. + */ VIDEO_ROTATION rotation; - /** * The timestamp for rendering the video. */ + /** + * The Unix timestamp (ms) when the video frame is rendered. This timestamp + * can be used to guide the rendering of the video frame. This parameter is required. + */ int64_t renderTimeMs; }; - -class IVideoEncodedFrameReceiver { +/** + * The IVideoEncodedFrameObserver class. + * + * @since v3.4.5 + */ +class IVideoEncodedFrameObserver { public: /** - * Occurs each time the SDK receives an encoded video image. - * @param videoEncodedFrame The information of the encoded video frame: VideoEncodedFrame. + * Gets the local encoded video frame. + * + * @since v3.4.5 + * + * After you successfully register the local encoded video frame observer, + * the SDK triggers this callback each time a video frame is received. You + * can get the local encoded video frame in `videoEncodedFrame` and then + * process the video data according to your scenario. After processing, + * you can use `videoEncodedFrame` to pass the processed video data back to + * the SDK. + * + * @param videoEncodedFrame The local encoded video frame. See VideoEncodedFrame. * + * @return + * - true: Sets the SDK to receive the video frame. + * - false: Sets the SDK to discard the video frame. */ - virtual bool OnVideoEncodedFrameReceived(const VideoEncodedFrame& videoEncodedFrame) = 0; + virtual bool onVideoEncodedFrame(const VideoEncodedFrame& videoEncodedFrame) = 0; - virtual ~IVideoEncodedFrameReceiver() {} + virtual ~IVideoEncodedFrameObserver() {} }; class IMediaEngine { @@ -687,30 +885,78 @@ class IMediaEngine { virtual int registerVideoFrameObserver(IVideoFrameObserver* observer) = 0; /** **DEPRECATED** */ virtual int registerVideoRenderFactory(IExternalVideoRenderFactory* factory) = 0; - /** **DEPRECATED** Use \ref agora::media::IMediaEngine::pushAudioFrame(IAudioFrameObserver::AudioFrame* frame) "pushAudioFrame(IAudioFrameObserver::AudioFrame* frame)" instead. - - Pushes the external audio frame. - - @param type Type of audio capture device: #MEDIA_SOURCE_TYPE. - @param frame Audio frame pointer: \ref IAudioFrameObserver::AudioFrame "AudioFrame". - @param wrap Whether to use the placeholder. We recommend setting the default value. - - true: Use. - - false: (Default) Not use. - - @return - - 0: Success. - - < 0: Failure. + /** + * Pushes the external audio frame. + * + * @deprecated This method is deprecated. Use \ref IMediaEngine::pushAudioFrame(int32_t,IAudioFrameObserver::AudioFrame*) "pushAudioFrame" [3/3] instead. + * + * @param type Type of audio capture device: #MEDIA_SOURCE_TYPE. + * @param frame Audio frame pointer: \ref IAudioFrameObserver::AudioFrame "AudioFrame". + * @param wrap Whether to use the placeholder. We recommend setting the default value. + * - true: Use. + * - false: (Default) Not use. + * + * @return + * - 0: Success. + * - < 0: Failure. */ - virtual int pushAudioFrame(MEDIA_SOURCE_TYPE type, IAudioFrameObserver::AudioFrame* frame, bool wrap) = 0; + virtual int pushAudioFrame(MEDIA_SOURCE_TYPE type, IAudioFrameObserver::AudioFrame* frame, bool wrap) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Pushes the external audio frame. + * + * @deprecated This method is deprecated. Use \ref IMediaEngine::pushAudioFrame(int32_t,IAudioFrameObserver::AudioFrame*) "pushAudioFrame" [3/3] instead. + * + * @param frame Pointer to the audio frame: \ref IAudioFrameObserver::AudioFrame "AudioFrame". + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int pushAudioFrame(IAudioFrameObserver::AudioFrame* frame) AGORA_DEPRECATED_ATTRIBUTE = 0; - @param frame Pointer to the audio frame: \ref IAudioFrameObserver::AudioFrame "AudioFrame". - - @return - - 0: Success. - - < 0: Failure. + /** + * Pushes the external audio frame to a specified position. + * + * @since v3.5.1 + * + * According to your needs, you can push the external audio frame to one of three positions: after audio capture, + * before audio encoding, or before local playback. You can call this method multiple times to push one audio frame + * to multiple positions or multiple audio frames to different positions. For example, in the KTV scenario, you can + * push the singing voice to after audio capture, so that the singing voice can be processed by the SDK audio module + * and you can obtain a high-quality audio experience; you can also push the accompaniment to before audio encoding, + * so that the accompaniment is not affected by the audio module of the SDK. + * + * @note Call this method after joining a channel. + * + * @param sourcePos The push position of the external audio frame. See #AUDIO_EXTERNAL_SOURCE_POSITION. + * @param frame The external audio frame. See AudioFrame. The value range of the audio frame length (ms) is [10,60]. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `-2 (ERR_INVALID_ARGUMENT)`: The parameter is invalid. + * - `-12 (ERR_TOO_OFTEN)`: The call frequency is too high, causing the internal buffer to overflow. Call this method again after 30-50 ms. */ - virtual int pushAudioFrame(IAudioFrameObserver::AudioFrame* frame) = 0; + virtual int pushAudioFrame(int32_t sourcePos, IAudioFrameObserver::AudioFrame* frame) = 0; + /** + * Sets the volume of the external audio frame in the specified position. + * + * @since v3.5.1 + * + * You can call this method multiple times to set the volume of external audio frames in different positions. + * The volume setting takes effect for all external audio frames that are pushed to the specified position. + * + * @note Call this method after joining a channel. + * + * @param sourcePos The push position of the external audio frame. See #AUDIO_EXTERNAL_SOURCE_POSITION. + * @param volume The volume of the external audio frame. The value range is [0,100]. The default value is 100, which + * represents the original value. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `-2 (ERR_INVALID_ARGUMENT)`: The parameter is invalid. + */ + virtual int setExternalAudioSourceVolume(int32_t sourcePos, int32_t volume) = 0; /** Pulls the remote audio data. * * Before calling this method, call the @@ -722,8 +968,9 @@ class IMediaEngine { * audio data for playback. * * @note + * - Ensure that you call this method after joining a channel. * - Once you call the \ref agora::media::IMediaEngine::pullAudioFrame - * "pullAudioFrame" method successfully, the app will not retrieve any audio + * "pullAudioFrame" method successfully, the app will not get any audio * data from the * \ref agora::media::IAudioFrameObserver::onPlaybackAudioFrame * "onPlaybackAudioFrame" callback. @@ -774,8 +1021,28 @@ class IMediaEngine { - < 0: Failure. */ virtual int pushVideoFrame(ExternalVideoFrame* frame) = 0; - - virtual int registerVideoEncodedFrameReceiver(IVideoEncodedFrameReceiver* receiver) = 0; + /** + * Registers a local encoded video frame observer. + * + * @since v3.4.5 + * + * After you successfully register the local encoded video frame observer, + * the SDK triggers the callbacks that you have implemented in the + * IVideoEncodedFrameObserver class each time a video frame is received. + * + * @note + * - Ensure that you call this method before joining a channel. + * - The width and height of the video obtained through the observer may + * change due to poor network conditions and user-adjusted resolution. + * + * @param observer The local encoded video frame observer. See IVideoEncodedFrameObserver. + * If null is passed, the observer registration is canceled. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int registerVideoEncodedFrameObserver(IVideoEncodedFrameObserver* observer) = 0; }; } // namespace media diff --git a/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/IAgoraRtcChannel.h b/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/IAgoraRtcChannel.h index 5c5a6fafe..8f9e71506 100644 --- a/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/IAgoraRtcChannel.h +++ b/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/IAgoraRtcChannel.h @@ -69,7 +69,7 @@ class IChannelEventHandler { This callback notifies the application that a user leaves the channel when the application calls the \ref agora::rtc::IChannel::leaveChannel "leaveChannel" method. - The application retrieves information, such as the call duration and statistics. + The application gets information, such as the call duration and statistics. @param rtcChannel IChannel @param stats The call statistics: RtcStats. @@ -80,9 +80,9 @@ class IChannelEventHandler { } /** Occurs when the user role switches in the interactive live streaming. For example, from a host to an audience or vice versa. - This callback notifies the application of a user role switch when the application calls the \ref IChannel::setClientRole "setClientRole" method. + This callback notifies the application of a user role switch when the application calls the \ref IChannel::setClientRole "setClientRole" method, and successfully changed role. - The SDK triggers this callback when the local user switches the user role by calling the \ref IChannel::setClientRole "setClientRole" method after joining the channel. + The SDK triggers this callback when the local user switches the user role by calling the \ref IChannel::setClientRole "setClientRole" method after joining the channel, and successfully changed role. @param rtcChannel IChannel @param oldRole Role that the user switches from: #CLIENT_ROLE_TYPE. @@ -93,6 +93,21 @@ class IChannelEventHandler { (void)oldRole; (void)newRole; } + + /** Occurs when the user role switches in the interactive live streaming. For example, from a host to an audience or vice versa. + + This callback notifies the application of a user role switch when the application calls the \ref IChannel::setClientRole "setClientRole" method, and failed to change role. + + The SDK triggers this callback when the local user switches the user role by calling the \ref IChannel::setClientRole "setClientRole" method after joining the channel, and failed to change role. + @param reason The reason of changing client role failed. See #CLIENT_ROLE_CHANGE_FAILED_REASON. + @param currentRole Current Role that the user holds: #CLIENT_ROLE_TYPE. + */ + virtual void onClientRoleChangeFailed(IChannel* rtcChannel, CLIENT_ROLE_CHANGE_FAILED_REASON reason, CLIENT_ROLE_TYPE currentRole) { + (void)rtcChannel; + (void)reason; + (void)currentRole; + } + /** Occurs when a remote user (`COMMUNICATION`)/ host (`LIVE_BROADCASTING`) joins the channel. - `COMMUNICATION` profile: This callback notifies the application that another user joins the channel. If other users are already in the channel, the SDK also reports to the application on the existing users. @@ -181,13 +196,17 @@ class IChannelEventHandler { (void)stats; } /** Reports the last mile network quality of each user in the channel once every two seconds. - - Last mile refers to the connection between the local device and Agora's edge server. This callback reports once every two seconds the last mile network conditions of each user in the channel. If a channel includes multiple users, the SDK triggers this callback as many times. - - @param rtcChannel IChannel - @param uid User ID. The network quality of the user with this @p uid is reported. If @p uid is 0, the local network quality is reported. - @param txQuality Uplink transmission quality rating of the user in terms of the transmission bitrate, packet loss rate, average RTT (Round-Trip Time), and jitter of the uplink network. @p txQuality is a quality rating helping you understand how well the current uplink network conditions can support the selected VideoEncoderConfiguration. 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 may be inadequate for resolutions higher than 1280 * 720. See #QUALITY_TYPE. - @param rxQuality Downlink network quality rating of the user in terms of the packet loss rate, average RTT, and jitter of the downlink network. See #QUALITY_TYPE. + * + * Last mile refers to the connection between the local device and Agora's edge server. This callback reports once every + * two seconds the last mile network conditions of each user in the channel. If a channel includes multiple users, the + * SDK triggers this callback as many times. + * + * @note `txQuality` is `UNKNOWN` when the user is not sending a stream; `rxQuality` is `UNKNOWN` when the user is not receiving a stream. + * + * @param rtcChannel IChannel + * @param uid User ID. The network quality of the user with this @p uid is reported. If @p uid is 0, the local network quality is reported. + * @param txQuality Uplink transmission quality rating of the user in terms of the transmission bitrate, packet loss rate, average RTT (Round-Trip Time), and jitter of the uplink network. @p txQuality is a quality rating helping you understand how well the current uplink network conditions can support the selected VideoEncoderConfiguration. 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 may be inadequate for resolutions higher than 1280 * 720. See #QUALITY_TYPE. + * @param rxQuality Downlink network quality rating of the user in terms of the packet loss rate, average RTT, and jitter of the downlink network. See #QUALITY_TYPE. */ virtual void onNetworkQuality(IChannel* rtcChannel, uid_t uid, int txQuality, int rxQuality) { (void)rtcChannel; @@ -223,18 +242,19 @@ class IChannelEventHandler { (void)stats; } /** Occurs when the remote audio state changes. - - This callback indicates the state change of the remote audio stream. - @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. - - @param rtcChannel IChannel - @param uid ID of the remote user whose audio state changes. - @param state State of the remote audio. See #REMOTE_AUDIO_STATE. - @param reason The reason of the remote audio state change. - See #REMOTE_AUDIO_STATE_REASON. - @param elapsed Time elapsed (ms) from the local user calling the - \ref IChannel::joinChannel "joinChannel" method until the SDK - triggers this callback. + * + * This callback indicates the state change of the remote audio stream. + * + * @note This callback can be inaccurate when the number of users (in the `COMMUNICATION` profile) + * or hosts (in the `LIVE_BROADCASTING` profile) in a channel exceeds 17. + * + * @param rtcChannel IChannel + * @param uid ID of the remote user whose audio state changes. + * @param state State of the remote audio. See #REMOTE_AUDIO_STATE. + * @param reason The reason of the remote audio state change. See #REMOTE_AUDIO_STATE_REASON. + * @param elapsed Time elapsed (ms) from the local user calling the + * \ref IChannel::joinChannel "joinChannel" method until the SDK + * triggers this callback. */ virtual void onRemoteAudioStateChanged(IChannel* rtcChannel, uid_t uid, REMOTE_AUDIO_STATE state, REMOTE_AUDIO_STATE_REASON reason, int elapsed) { (void)rtcChannel; @@ -319,21 +339,23 @@ class IChannelEventHandler { (void)newState; (void)elapseSinceLastState; } - /// @cond - /** Reports whether the super-resolution algorithm is enabled. + + /** Reports whether the super resolution feature is successfully enabled. (beta feature) * - * @since v3.2.0 + * @since v3.5.1 * - * After calling \ref IRtcChannel::enableRemoteSuperResolution "enableRemoteSuperResolution", the SDK triggers this - * callback to report whether the super-resolution algorithm is successfully enabled. If not successfully enabled, - * you can use reason for troubleshooting. + * After calling \ref IChannel::enableRemoteSuperResolution "enableRemoteSuperResolution", the SDK triggers this + * callback to report whether super resolution is successfully enabled. If it is not successfully enabled, + * use `reason` for troubleshooting. * * @param rtcChannel IChannel - * @param uid The ID of the remote user. - * @param enabled Whether the super-resolution algorithm is successfully enabled: - * - true: The super-resolution algorithm is successfully enabled. - * - false: The super-resolution algorithm is not successfully enabled. - * @param reason The reason why the super-resolution algorithm is not successfully enabled. See #SUPER_RESOLUTION_STATE_REASON. + * @param uid The user ID of the remote user. + * @param enabled Whether super resolution is successfully enabled: + * - true: Super resolution is successfully enabled. + * - false: Super resolution is not successfully enabled. + * @param reason The reason why super resolution is not successfully enabled or the message + * that confirms success. See #SUPER_RESOLUTION_STATE_REASON. + * */ virtual void onUserSuperResolutionEnabled(IChannel* rtcChannel, uid_t uid, bool enabled, SUPER_RESOLUTION_STATE_REASON reason) { (void)rtcChannel; @@ -341,9 +363,8 @@ class IChannelEventHandler { (void)enabled; (void)reason; } - /// @endcond - /** Occurs when the most active speaker is detected. + /** Occurs when the most active remote speaker is detected. After a successful call of \ref IRtcEngine::enableAudioVolumeIndication(int, int, bool) "enableAudioVolumeIndication", the SDK continuously detects which remote user has the loudest volume. During the current period, the remote user, @@ -354,7 +375,7 @@ class IChannelEventHandler { - If the most active speaker changes to another user, the SDK triggers this callback again and reports the `uid` of the new active speaker. @param rtcChannel IChannel - @param uid The user ID of the most active speaker. + @param uid The user ID of the most active remote speaker. */ virtual void onActiveSpeaker(IChannel* rtcChannel, uid_t uid) { (void)rtcChannel; @@ -376,17 +397,17 @@ class IChannelEventHandler { (void)rotation; } /** Occurs when the remote video state changes. - - @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. - - @param rtcChannel IChannel - @param uid ID of the remote user whose video state changes. - @param state State of the remote video. See #REMOTE_VIDEO_STATE. - @param reason The reason of the remote video state change. See - #REMOTE_VIDEO_STATE_REASON. - @param elapsed Time elapsed (ms) from the local user calling the - \ref agora::rtc::IChannel::joinChannel "joinChannel" method until the - SDK triggers this callback. + * + * @note This callback can be inaccurate when the number of users (in the `COMMUNICATION` profile) or + * hosts (in the `LIVE_BROADCASTING` profile) in a channel exceeds 17. + * + * @param rtcChannel IChannel + * @param uid ID of the remote user whose video state changes. + * @param state State of the remote video. See #REMOTE_VIDEO_STATE. + * @param reason The reason of the remote video state change. See #REMOTE_VIDEO_STATE_REASON. + * @param elapsed Time elapsed (ms) from the local user calling the + * \ref agora::rtc::IChannel::joinChannel "joinChannel" method until the + * SDK triggers this callback. */ virtual void onRemoteVideoStateChanged(IChannel* rtcChannel, uid_t uid, REMOTE_VIDEO_STATE state, REMOTE_VIDEO_STATE_REASON reason, int elapsed) { (void)rtcChannel; @@ -453,22 +474,23 @@ class IChannelEventHandler { (void)code; } /** - Occurs when the state of the RTMP or RTMPS streaming changes. - - The SDK triggers this callback to report the result of the local user calling the \ref agora::rtc::IChannel::addPublishStreamUrl "addPublishStreamUrl" or \ref agora::rtc::IChannel::removePublishStreamUrl "removePublishStreamUrl" method. - - 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 *errCode* parameter. - - @param rtcChannel IChannel - @param url The CDN streaming URL. - @param state The RTMP or RTMPS streaming state. See: #RTMP_STREAM_PUBLISH_STATE. - @param errCode The detailed error information for streaming. See: #RTMP_STREAM_PUBLISH_ERROR. + * Occurs when the state of the RTMP or RTMPS streaming changes. + * + * When the CDN live streaming state changes, the SDK triggers this callback to report the current state and the reason + * why the state has changed. + * + * When exceptions occur, you can troubleshoot issues by referring to the detailed error descriptions in the *errCode* parameter. + * + * @param rtcChannel IChannel + * @param url The CDN streaming URL. + * @param state The RTMP or RTMPS streaming state. See: #RTMP_STREAM_PUBLISH_STATE. + * @param errCode The detailed error information for streaming. See: #RTMP_STREAM_PUBLISH_ERROR_TYPE. */ - virtual void onRtmpStreamingStateChanged(IChannel* rtcChannel, const char* url, RTMP_STREAM_PUBLISH_STATE state, RTMP_STREAM_PUBLISH_ERROR errCode) { + virtual void onRtmpStreamingStateChanged(IChannel* rtcChannel, const char* url, RTMP_STREAM_PUBLISH_STATE state, RTMP_STREAM_PUBLISH_ERROR_TYPE errCode) { (void)rtcChannel; (void)url; - (RTMP_STREAM_PUBLISH_STATE) state; - (RTMP_STREAM_PUBLISH_ERROR) errCode; + (void)state; + (void)errCode; } /** Reports events during the RTMP or RTMPS streaming. @@ -482,7 +504,7 @@ class IChannelEventHandler { virtual void onRtmpStreamingEvent(IChannel* rtcChannel, const char* url, RTMP_STREAMING_EVENT eventCode) { (void)rtcChannel; (void)url; - (RTMP_STREAMING_EVENT) eventCode; + (void)eventCode; } /** Occurs when the publisher's transcoding is updated. @@ -531,8 +553,8 @@ class IChannelEventHandler { * "setRemoteSubscribeFallbackOption" and set * @p option as #STREAM_FALLBACK_OPTION_AUDIO_ONLY, the SDK triggers this * callback when the remote media stream falls back to audio-only mode due - * to poor uplink conditions, or when the remote media stream switches - * back to the video after the uplink network condition improves. + * to poor downlink conditions, or when the remote media stream switches + * back to the video after the downlink network condition improves. * * @note Once the remote media stream switches to the low stream due to * poor network conditions, you can monitor the stream switch between a @@ -562,6 +584,21 @@ class IChannelEventHandler { (void)state; (void)reason; } + + /** Occurs when join success after calling \ref IRtcEngine::setLocalAccessPoint "setLocalAccessPoint" or \ref IRtcEngine::setCloudProxy "setCloudProxy" + @param rtcChannel IChannel + @param uid User ID of the user joining the channel. + @param proxyType type of proxy agora sdk connected, proxyType will be NONE_PROXY_TYPE if not connected to proxy(fallback). + @param localProxyIp local proxy ip list. if not join local proxy, it will be "". + @param elapsed Time elapsed (ms) from the user calling the \ref IRtcEngine::joinChannel "joinChannel" method until the SDK triggers this callback. + */ + virtual void onProxyConnected(IChannel* rtcChannel, uid_t uid, PROXY_TYPE proxyType, const char* localProxyIp, int elapsed) { + (void)rtcChannel; + (void)uid; + (void)proxyType; + (void)localProxyIp; + (void)elapsed; + } }; /** The IChannel class. */ @@ -588,68 +625,77 @@ class IChannel { */ virtual int setChannelEventHandler(IChannelEventHandler* channelEh) = 0; /** Joins the channel with a user ID. - - This method differs from the `joinChannel` method in the `IRtcEngine` class in the following aspects: - - | IChannel::joinChannel | IRtcEngine::joinChannel | - |------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------| - | Does not contain the `channelId` parameter, because `channelId` is specified when creating the `IChannel` object. | Contains the `channelId` parameter, which specifies the channel to join. | - | Contains the `options` parameter, which decides whether to subscribe to all streams before joining the channel. | Does not contain the `options` parameter. By default, users subscribe to all streams when joining the channel. | - | Users can join multiple channels simultaneously by creating multiple `IChannel` objects and calling the `joinChannel` method of each object. | Users can join only one channel. | - | By default, the SDK does not publish any stream after the user joins the channel. You need to call the publish method to do that. | By default, the SDK publishes streams once the user joins the channel. | - - Once the user joins the channel (switches to another channel), the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. If you do not want to subscribe to a specified stream or all remote streams, call the `mute` methods accordingly. - - @note - - If you are already in a channel, you cannot rejoin it with the same `uid`. - - We recommend using different UIDs for different channels. - - If you want to join the same channel from different devices, ensure that the UIDs 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` object. - - @param token The token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Windows). - @param info (Optional) Additional information about the channel. This parameter can be set as null. Other users in the channel do not receive this information. - @param uid The user ID. A 32-bit unsigned integer with a value ranging from 1 to (232-1). This parameter must be unique. If `uid` is not assigned (or set as `0`), the SDK assigns a `uid` and reports it in the \ref agora::rtc::IChannelEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" callback. The app must maintain this user ID. - @param options The channel media options: \ref agora::rtc::ChannelMediaOptions::ChannelMediaOptions "ChannelMediaOptions" - - @return - - 0(ERR_OK): Success. - - < 0: Failure. - - -2(ERR_INALID_ARGUMENT): The parameter is invalid. - - -3(ERR_NOT_READY): The SDK fails to be initialized. You can try re-initializing the SDK. - - -5(ERR_REFUSED): The request is rejected. This may be caused by the following: - - You have created an IChannel object with the same channel name. - - You have joined and published a stream in a channel created by the IChannel object. When you join a channel created by the IRtcEngine object, the SDK publishes the local audio and video streams to that channel by default. Because the SDK does not support publishing a local stream to more than one channel simultaneously, an error occurs in this occasion. - - -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method. + * + * Compared with the `joinChannel` method in the IRtcEngine class, this method supports joining multiple channels at + * a time by creating multiple IChannel objects and then calling `joinChannel` in each IChannel object. + * + * Once the user joins the channel, the user publishes the local audio and video streams and automatically + * subscribes to the audio and video streams of all the other users in the channel by default. Subscribing + * incurs all associated usage costs. To unsubscribe, set the `options` parameter or call the `mute` methods accordingly. + * + * @note + * - If you are already in a channel, you cannot rejoin it with the same `uid`. + * - We recommend using different UIDs for different channels. + * - If you want to join the same channel from different devices, ensure that the UIDs 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` object. + * + * @param token The token generated at your server. See [Authenticate Your Users with Tokens](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=All%20Platforms). + * @param info (Optional) Additional information about the channel. This parameter can be set as null. Other users in the channel do not receive this information. + * @param uid The user ID. A 32-bit unsigned integer with a value ranging from 1 to (232-1). This parameter must be unique. If `uid` is not assigned (or set as `0`), the SDK assigns a `uid` and reports it in the \ref agora::rtc::IChannelEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" callback. The app must maintain this user ID. + * @param options The channel media options: \ref agora::rtc::ChannelMediaOptions::ChannelMediaOptions "ChannelMediaOptions" + * + * @return + * - 0(ERR_OK): Success. + * - < 0: Failure. + * - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. + * - -3(ERR_NOT_READY): The SDK fails to be initialized. You can try re-initializing the SDK. + * - -5(ERR_REFUSED): The request is rejected. This may be caused by the following: + * - You have created an IChannel object with the same channel name. + * - You have joined and published a stream in a channel created by the IChannel object. When you join a channel created by the IRtcEngine object, the SDK publishes the local audio and video streams to that channel by default. Because the SDK does not support publishing a local stream to more than one channel simultaneously, an error occurs in this occasion. + * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method. + * - `ERR_JOIN_CHANNEL_REJECTED(-17)`: The request to join the channel is rejected. The SDK does not support + * joining the same IChannel channel repeatedly. Therefore, the SDK returns this error code when a user who has + * already joined an IChannel channel calls the joining channel method of this IChannel object. */ virtual int joinChannel(const char* token, const char* info, uid_t uid, const ChannelMediaOptions& options) = 0; /** Joins the channel with a user account. - - After the user successfully joins the channel, the SDK triggers the following callbacks: - - - The local client: \ref agora::rtc::IRtcEngineEventHandler::onLocalUserRegistered "onLocalUserRegistered" and \ref agora::rtc::IChannelEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" . - - The remote client: \ref agora::rtc::IChannelEventHandler::onUserJoined "onUserJoined" and \ref agora::rtc::IRtcEngineEventHandler::onUserInfoUpdated "onUserInfoUpdated" , if the user joining the channel is in the `COMMUNICATION` profile, or is a host in the `LIVE_BROADCASTING` profile. - - Once the user joins the channel (switches to another channel), the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. If you do not want to subscribe to a specified stream or all remote streams, call the `mute` methods accordingly. - - @note To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. - If a user joins the channel with the Agora Web SDK, ensure that the uid of the user is set to the same parameter type. - - @param token The token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Windows). - @param userAccount The user account. The maximum length of this parameter is 255 bytes. Ensure that the user account is unique and do not set it as null. Supported character scopes are: - - All lowercase English letters: a to z. - - All uppercase English letters: A to Z. - - All numeric characters: 0 to 9. - - The space character. - - Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",". - @param options The channel media options: \ref agora::rtc::ChannelMediaOptions::ChannelMediaOptions “ChannelMediaOptions”. - - @return - - 0: Success. - - < 0: Failure. - - #ERR_INVALID_ARGUMENT (-2) - - #ERR_NOT_READY (-3) - - #ERR_REFUSED (-5) - - #ERR_NOT_INITIALIZED (-7) + * + * Compared with the `joinChannelWithUserAccount` method in the IRtcEngine class, this method supports joining multiple channels at + * a time by creating multiple IChannel objects and then calling `joinChannelWithUserAccount` in each IChannel object. + * + * After the user successfully joins the channel, the SDK triggers the following callbacks: + * + * - The local client: \ref agora::rtc::IRtcEngineEventHandler::onLocalUserRegistered "onLocalUserRegistered" and \ref agora::rtc::IChannelEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" . + * - The remote client: \ref agora::rtc::IChannelEventHandler::onUserJoined "onUserJoined" and \ref agora::rtc::IRtcEngineEventHandler::onUserInfoUpdated "onUserInfoUpdated" , if the user joining the channel is in the `COMMUNICATION` profile, or is a host in the `LIVE_BROADCASTING` profile. + * + * Once the user joins the channel, the user publishes the local audio and video streams and + * automatically subscribes to the audio and video streams of all the other users in the channel by default. + * Subscribing incurs all associated usage costs. To unsubscribe, set the `options` parameters 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 uid of the user is set to the same parameter type. + * - Before using a String user name, ensure that you read [How can I use string user names](https://docs.agora.io/en/faq/string) for getting details about the limitations and implementation steps. + * + * @param token The token generated at your server. See [Authenticate Your Users with Tokens](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=All%20Platforms). + * @param userAccount The user account. The maximum length of this parameter is 255 bytes. Ensure that the user account is unique and do not set it as null. Supported character scopes are: + * - All lowercase English letters: a to z. + * - All uppercase English letters: A to Z. + * - All numeric characters: 0 to 9. + * - The space character. + * - Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",". + * @param options The channel media options: \ref agora::rtc::ChannelMediaOptions::ChannelMediaOptions “ChannelMediaOptions”. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - #ERR_INVALID_ARGUMENT (-2) + * - #ERR_NOT_READY (-3) + * - #ERR_REFUSED (-5) + * - #ERR_NOT_INITIALIZED (-7) + * - `ERR_JOIN_CHANNEL_REJECTED(-17)`: The request to join the channel is rejected. The SDK does not support + * joining the same IChannel channel repeatedly. Therefore, the SDK returns this error code when a user who has + * already joined an IChannel channel calls the joining channel method of this IChannel object. */ virtual int joinChannelWithUserAccount(const char* token, const char* userAccount, const ChannelMediaOptions& options) = 0; /** Allows a user to leave a channel, such as hanging up or exiting a call. @@ -668,20 +714,28 @@ class IChannel { - If you call the \ref IChannel::release "release" method immediately after the *leaveChannel* method, the *leaveChannel* process interrupts, and the \ref IChannelEventHandler::onLeaveChannel "onLeaveChannel" callback is not triggered. - If you call the *leaveChannel* method during a CDN live streaming, the SDK triggers the \ref IChannel::removePublishStreamUrl "removePublishStreamUrl" method. - @return - - 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. - */ + @return + - 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. + */ virtual int leaveChannel() = 0; + /// @cond + virtual int setAVSyncSource(const char* channelId, uid_t uid) = 0; + /// @endcond + /** Publishes the local stream to the channel. + @deprecated This method is deprecated as of v3.4.5. Use \ref IChannel::muteLocalAudioStream "muteLocalAudioStream" (false) + or \ref IChannel::muteLocalVideoStream "muteLocalVideoStream" (false) instead. + You must keep the following restrictions in mind when calling this method. Otherwise, the SDK returns the #ERR_REFUSED (5): - - This method publishes one stream only to the channel corresponding to the current `IChannel` object. - - In the interactive live streaming channel, only a host can call this method. To switch the client role, call \ref agora::rtc::IChannel::setClientRole "setClientRole" of the current `IChannel` object. + - This method publishes one stream only to the channel corresponding to the current IChannel object. + - In the interactive live streaming channel, only a host can call this method. + To switch the client role, call \ref IChannel::setClientRole "setClientRole" of the current IChannel object. - You can publish a stream to only one channel at a time. For details on joining multiple channels, see the advanced guide *Join Multiple Channels*. @return @@ -689,10 +743,13 @@ class IChannel { - < 0: Failure. - #ERR_REFUSED (5): The method call is refused. */ - virtual int publish() = 0; + virtual int publish() AGORA_DEPRECATED_ATTRIBUTE = 0; /** Stops publishing a stream to the channel. + @deprecated This method is deprecated as of v3.4.5. Use \ref IChannel::muteLocalAudioStream "muteLocalAudioStream" (true) + or \ref IChannel::muteLocalVideoStream "muteLocalVideoStream" (true) instead. + If you call this method in a channel where you are not publishing streams, the SDK returns #ERR_REFUSED (5). @return @@ -700,7 +757,7 @@ class IChannel { - < 0: Failure. - #ERR_REFUSED (5): The method call is refused. */ - virtual int unpublish() = 0; + virtual int unpublish() AGORA_DEPRECATED_ATTRIBUTE = 0; /** Gets the channel ID of the current `IChannel` object. @@ -709,7 +766,7 @@ class IChannel { - The empty string "", if the method call fails. */ virtual const char* channelId() = 0; - /** Retrieves the current call ID. + /** Gets the current call ID. When a user joins a channel on a client, a `callId` is generated to identify the call from the client. Feedback methods, such as \ref IRtcEngine::rate "rate" and \ref IRtcEngine::complain "complain", must be called after the call ends to submit feedback to the SDK. @@ -734,13 +791,13 @@ class IChannel { The application should call this method to get the new `token`. Failure to do so will result in the SDK disconnecting from the server. - @param token Pointer to the new token. + @param token The new token. @return - 0(ERR_OK): Success. - < 0: Failure. - -1(ERR_FAILED): A general error occurs (no specified reason). - - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. */ virtual int renewToken(const char* token) = 0; @@ -762,7 +819,7 @@ class IChannel { - 0: Success. - < 0: Failure. */ - virtual int setEncryptionSecret(const char* secret) = 0; + virtual int setEncryptionSecret(const char* secret) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Sets the built-in encryption mode. @deprecated Deprecated as of v3.1.0. Use the \ref agora::rtc::IChannel::enableEncryption "enableEncryption" instead. @@ -785,16 +842,25 @@ class IChannel { - 0: Success. - < 0: Failure. */ - virtual int setEncryptionMode(const char* encryptionMode) = 0; + virtual int setEncryptionMode(const char* encryptionMode) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Enables/Disables the built-in encryption. * * @since v3.1.0 * * In scenarios requiring high security, Agora recommends calling this method to enable the built-in encryption before joining a channel. * - * All users in the same channel must use the same encryption mode and encryption key. After a 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. + * After a user leaves the channel, the SDK automatically disables the built-in encryption. + * To re-enable the built-in encryption, call this method before the user joins the channel again. + * + * As of v3.4.5, Agora recommends using either the `AES_128_GCM2` or `AES_256_GCM2` encryption mode, + * both of which support adding a salt and are more secure. For details, see *Media Stream Encryption*. + * + * @warning All users in the same channel must use the same encryption mode, encryption key, and salt; otherwise, + * users cannot communicate with each other. * - * @note If you enable the built-in encryption, you cannot use the RTMP or RTMPS streaming function. + * @note + * - If you enable the built-in encryption, you cannot use the RTMP or RTMPS streaming function. + * - To enhance security, Agora recommends using a new key and salt every time you enable the media stream encryption. * * @param enabled Whether to enable the built-in encryption: * - true: Enable the built-in encryption. @@ -816,7 +882,7 @@ class IChannel { @note - The size of the packet sent to the network after processing should not exceed 1200 bytes, otherwise, the packet may fail to be sent. - Ensure that both receivers and senders call this method, otherwise, you may meet undefined behaviors such as no voice and black screen. - - When you use CDN live streaming, recording or storage functions, Agora doesn't recommend calling this method. + - When you use CDN live streaming and recording functions, Agora doesn't recommend calling this method. - Call this method before joining a channel. @param observer The registered packet observer. See IPacketObserver. @@ -842,43 +908,61 @@ class IChannel { - < 0: Failure. */ virtual int registerMediaMetadataObserver(IMetadataObserver* observer, IMetadataObserver::METADATA_TYPE type) = 0; - /** Sets the role of the user, such as a host or an audience (default), before joining a channel in the interactive live streaming. - - This method can be used to switch the user role in the interactive live streaming after the user joins a channel. - - In the `LIVE_BROADCASTING` profile, when a user switches user roles after joining a channel, a successful \ref agora::rtc::IChannel::setClientRole "setClientRole" method call triggers the following callbacks: - - The local client: \ref agora::rtc::IChannelEventHandler::onClientRoleChanged "onClientRoleChanged" - - The remote client: \ref agora::rtc::IChannelEventHandler::onUserJoined "onUserJoined" or \ref agora::rtc::IChannelEventHandler::onUserOffline "onUserOffline" (BECOME_AUDIENCE) - - @note - This method applies only to the `LIVE_BROADCASTING` profile. - - @param role Sets the role of the user. See #CLIENT_ROLE_TYPE. - @return - - 0: Success. - - < 0: Failure. + /** Sets the role of the user in interactive live streaming. + * + * In the `LIVE_BROADCASTING` channel profile, the + * SDK sets the user role as audience by default. You can call `setClientRole` to set the user role as host. + * + * You can call this method either before or after joining a channel. If you + * call this method to switch the user role after joining a channel, the SDK automatically does the following: + * - Calls \ref IChannel::muteLocalAudioStream "muteLocalAudioStream" and \ref IChannel::muteLocalVideoStream "muteLocalVideoStream" to + * change the publishing state. + * - Triggers \ref IChannelEventHandler::onClientRoleChanged "onClientRoleChanged" or \ref IChannelEventHandler::onClientRoleChangeFailed "onClientRoleChangeFailed" on the local client in 5s. + * - Triggers \ref IChannelEventHandler::onUserJoined "onUserJoined" or \ref IChannelEventHandler::onUserOffline "onUserOffline" (BECOME_AUDIENCE) + * on the remote client. + * + * @note This method applies to the `LIVE_BROADCASTING` profile only. + * + * @param role The role of a user in interactive live streaming. See #CLIENT_ROLE_TYPE. + * + * @return + * - 0(ERR_OK): Success. + * - < 0: Failure. + * - -1(ERR_FAILED): A general error occurs (no specified reason). + * - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. + * - -5 (ERR_REFUSED): The request is rejected. In multichannel scenarios, if you have set any of the following in + * one channel, the SDK returns this error code when the user switches the user role to host in another channel: + * - Call `joinChannel` with the `options` parameter and use the default settings `publishLocalAudio = true` or `publishLocalVideo = true`. + * - Call `setClientRole` to set the user role as host. + * - Call `muteLocalAudioStream(false)` or `muteLocalVideoStream(false)`. + * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. */ virtual int setClientRole(CLIENT_ROLE_TYPE role) = 0; - /** Sets the role of a user in interactive live streaming. + /** Sets the role of the user in interactive live streaming. * * @since v3.2.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: \ref IChannelEventHandler::onClientRoleChanged "onClientRoleChanged". - * - The remote client: \ref IChannelEventHandler::onUserJoined "onUserJoined" - * or \ref IChannelEventHandler::onUserOffline "onUserOffline". + * In the `LIVE_BROADCASTING` channel profile, the + * SDK sets the user role as audience by default. You can call `setClientRole` to set the user role as host. + * + * You can call this method either before or after joining a channel. If you + * call this method to switch the user role after joining a channel, the SDK automatically does the following: + * - Calls \ref IChannel::muteLocalAudioStream "muteLocalAudioStream" and \ref IChannel::muteLocalVideoStream "muteLocalVideoStream" to + * change the publishing state. + * - Triggers \ref IChannelEventHandler::onClientRoleChanged "onClientRoleChanged" or \ref IChannelEventHandler::onClientRoleChangeFailed "onClientRoleChangeFailed" on the local client in 5s. + * - Triggers \ref IChannelEventHandler::onUserJoined "onUserJoined" or \ref IChannelEventHandler::onUserOffline "onUserOffline" (BECOME_AUDIENCE) + * on the remote client. * * @note * - This method applies to the `LIVE_BROADCASTING` profile only. * - The difference between this method and \ref IChannel::setClientRole(CLIENT_ROLE_TYPE) "setClientRole" [1/2] is that * this method can set the user level in addition to the user role. - * - The user role determines the permissions that the SDK grants to a user, such as permission to send local - * streams, receive remote streams, and push streams to a CDN address. - * - The user level determines the level of services that a user can enjoy within the permissions of the user's - * role. For example, an audience can choose to receive remote streams with low latency or ultra low latency. Levels - * affect prices. + * - The user role determines the permissions that the SDK grants to a user, such as permission to send local streams, + * receive remote streams, and push streams to a CDN address. + * - The user level determines the level of services that a user can enjoy within the permissions of the user's role. + * For example, an audience member can choose to receive remote streams with low latency or ultra low latency. + * **User level affects the pricing of services.** * * @param role The role of a user in interactive live streaming. See #CLIENT_ROLE_TYPE. * @param options The detailed options of a user, including user level. See ClientRoleOptions. @@ -887,7 +971,12 @@ class IChannel { * - 0(ERR_OK): Success. * - < 0: Failure. * - -1(ERR_FAILED): A general error occurs (no specified reason). - * - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + * - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. + * - -5 (ERR_REFUSED): The request is rejected. In multichannel scenarios, if you have set any of the following in + * one channel, the SDK returns this error code when the user switches the user role to host in another channel: + * - Call `joinChannel` with the `options` parameter and use the default settings `publishLocalAudio = true` or `publishLocalVideo = true`. + * - Call `setClientRole` to set the user role as host. + * - Call `muteLocalAudioStream(false)` or `muteLocalVideoStream(false)`. * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. */ virtual int setClientRole(CLIENT_ROLE_TYPE role, const ClientRoleOptions& options) = 0; @@ -973,7 +1062,7 @@ class IChannel { * - 0: Success. * - < 0: Failure. */ - virtual int setDefaultMuteAllRemoteAudioStreams(bool mute) = 0; + virtual int setDefaultMuteAllRemoteAudioStreams(bool mute) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Stops or resumes subscribing to the video streams of all remote users by default. * * @deprecated This method is deprecated from v3.3.0. @@ -994,16 +1083,76 @@ class IChannel { * - 0: Success. * - < 0: Failure. */ - virtual int setDefaultMuteAllRemoteVideoStreams(bool mute) = 0; + virtual int setDefaultMuteAllRemoteVideoStreams(bool mute) AGORA_DEPRECATED_ATTRIBUTE = 0; + /** + * Stops or resumes publishing the local audio stream. + * + * @since v3.4.5 + * + * This method only sets the publishing state of the audio stream in the channel of IChannel. + * + * A successful method call triggers the + * \ref IChannelEventHandler::onRemoteAudioStateChanged "onRemoteAudioStateChanged" + * callback on the remote client. + * + * You can only publish the local stream in one channel at a time. If you create multiple channels, ensure that + * you only call \ref IChannel::muteLocalAudioStream "muteLocalAudioStream" (false) in one channel; + * otherwise, the method call fails, and the SDK returns `-5 (ERR_REFUSED)`. + * + * @note + * - This method does not change the usage state of the audio-capturing device. + * - Whether this method call takes effect is affected by the \ref IChannel::joinChannel "joinChannel" + * and \ref IChannel::setClientRole "setClientRole" methods. For details, see *Set the Publishing State*. + * + * @param mute Sets whether to stop publishing the local audio stream. + * - true: Stop publishing the local audio stream. + * - false: Resume publishing the local audio stream. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `-5 (ERR_REFUSED)`: The request is rejected. + */ + virtual int muteLocalAudioStream(bool mute) = 0; + /** Stops or resumes publishing the local video stream. + * + * @since v3.4.5 + * + * This method only sets the publishing state of the video stream in the channel of IChannel. + * + * A successful method call triggers the \ref IChannelEventHandler::onRemoteVideoStateChanged "onRemoteVideoStateChanged" + * callback on the remote client. + * + * You can only publish the local stream in one channel at a time. If you create multiple channels, + * ensure that you only call \ref IChannel::muteLocalVideoStream "muteLocalVideoStream" (false) in one channel; + * otherwise, the method call fails, and the SDK returns `-5 (ERR_REFUSED)`. + * + * @note + * - This method does not change the usage state of the video-capturing device. + * - Whether this method call takes effect is affected by the \ref IChannel::joinChannel "joinChannel" + * and \ref IChannel::setClientRole "setClientRole" methods. For details, see *Set the Publishing State*. + * + * @param mute Sets whether to stop publishing the local video stream. + * - true: Stop publishing the local video stream. + * - false: Resume publishing the local video stream. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `-5 (ERR_REFUSED)`: The request is rejected. + */ + virtual int muteLocalVideoStream(bool mute) = 0; /** * Stops or resumes subscribing to the audio streams of all remote users. * - * As of v3.3.0, after successfully calling this method, the local user stops or resumes + * 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*. + * - As of v3.3.0, this method contains the function of \ref IChannel::setDefaultMuteAllRemoteAudioStreams "setDefaultMuteAllRemoteAudioStreams". + * Agora recommends not calling `muteAllRemoteAudioStreams` and `setDefaultMuteAllRemoteAudioStreams` + * together; otherwise, the settings may not take effect. See *Set the Subscribing State*. * * @param mute Sets whether to stop subscribing to the audio streams of all remote users. * - true: Stop subscribing to the audio streams of all remote users. @@ -1015,24 +1164,26 @@ class IChannel { */ virtual int muteAllRemoteAudioStreams(bool mute) = 0; /** Adjust the playback signal volume of the specified remote user. - - After joining a channel, call \ref agora::rtc::IRtcEngine::adjustPlaybackSignalVolume "adjustPlaybackSignalVolume" to adjust the playback volume of different remote users, - or adjust multiple times for one remote user. - - @note - - Call this method after joining a channel. - - This method adjusts the playback volume, which is the mixed volume for the specified remote user. - - This method can only adjust the playback volume of one specified remote user at a time. If you want to adjust the playback volume of several remote users, - call the method multiple times, once for each remote user. - - @param userId The user ID, which should be the same as the `uid` of \ref agora::rtc::IChannel::joinChannel "joinChannel" - @param volume The playback volume of the voice. The value ranges from 0 to 100: - - 0: Mute. - - 100: Original volume. - - @return - - 0: Success. - - < 0: Failure. + * + * After joining a channel, call \ref agora::rtc::IRtcEngine::adjustPlaybackSignalVolume "adjustPlaybackSignalVolume" to adjust the playback volume of different remote users, + * or adjust multiple times for one remote user. + * + * @note + * - Call this method after joining a channel. + * - This method adjusts the playback volume, which is the mixed volume for the specified remote user. + * - This method can only adjust the playback volume of one specified remote user at a time. If you want to adjust the playback volume of several remote users, + * call the method multiple times, once for each remote user. + * + * @param userId The user ID, which should be the same as the `uid` of \ref agora::rtc::IChannel::joinChannel "joinChannel" + * @param volume The playback volume of the voice. The value + * ranges between 0 and 400, including the following: + * - 0: Mute. + * - 100: (Default) Original volume. + * - 400: Four times the original volume with signal-clipping protection. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int adjustUserPlaybackSignalVolume(uid_t userId, int volume) = 0; /** @@ -1055,7 +1206,7 @@ class IChannel { /** * Stops or resumes subscribing to the video streams of all remote users. * - * As of v3.3.0, after successfully calling this method, the local user stops or resumes + * 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 @@ -1116,6 +1267,21 @@ class IChannel { - < 0: Failure. */ virtual int setRemoteVideoStreamType(uid_t userId, REMOTE_VIDEO_STREAM_TYPE streamType) = 0; + /** Turn WIFI acceleration on or off. + + @note + - This method is called before and after joining a channel. + - Users check the WIFI router app for information about acceleration. Therefore, if this interface is invoked, the caller accepts that the caller's name will be displayed to the user in the WIFI router application on behalf of the caller. + + @param enabled + - true：Turn WIFI acceleration on. + - false：Turn WIFI acceleration off. + + @return + - 0: Success. + - < 0: Failure. + */ + virtual int enableWirelessAccelerate(bool enabled) = 0; /** Sets the default stream type of remote videos. Under limited network conditions, if the publisher has not disabled the dual-stream mode using @@ -1145,7 +1311,7 @@ class IChannel { virtual int setRemoteDefaultVideoStreamType(REMOTE_VIDEO_STREAM_TYPE streamType) = 0; /** Creates a data stream. - @deprecated This method is deprecated from v3.3.0. Use the \ref IChannel::createDataStream(int* streamId, DataStreamConfig& config) "createDataStream" [2/2] method instead. + @deprecated This method is deprecated from v3.3.0. Use the \ref IChannel::createDataStream(int* streamId, DataStreamConfig& config) "createDataStream" [2/2] method instead. Each user can create up to five data streams during the lifecycle of the IChannel. @@ -1167,7 +1333,7 @@ class IChannel { - Returns 0: Success. - < 0: Failure. */ - virtual int createDataStream(int* streamId, bool reliable, bool ordered) = 0; + virtual int createDataStream(int* streamId, bool reliable, bool ordered) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Creates a data stream. * * @since v3.3.0 @@ -1213,6 +1379,8 @@ class IChannel { virtual int sendStreamMessage(int streamId, const char* data, size_t length) = 0; /** Publishes the local stream to a specified CDN streaming URL. (CDN live only.) + @deprecated This method is deprecated as of v3.6.0. See [Release Notes](https://docs.agora.io/en/Interactive%20Broadcast/release_windows_video?platform=Windows) for an alternative solution. + The SDK returns the result of this method call in the \ref IRtcEngineEventHandler::onStreamPublished "onStreamPublished" callback. After calling this method, you can push media streams in RTMP or RTMPS protocol to the CDN. The SDK triggers @@ -1236,9 +1404,11 @@ class IChannel { - #ERR_INVALID_ARGUMENT (-2): The CDN streaming URL is NULL or has a string length of 0. - #ERR_NOT_INITIALIZED (-7): You have not initialized `IChannel` when publishing the stream. */ - virtual int addPublishStreamUrl(const char* url, bool transcodingEnabled) = 0; + virtual int addPublishStreamUrl(const char* url, bool transcodingEnabled) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Removes an RTMP or RTMPS stream from the CDN. + @deprecated This method is deprecated as of v3.6.0. See [Release Notes](https://docs.agora.io/en/Interactive%20Broadcast/release_windows_video?platform=Windows) for an alternative solution. + This method removes the CDN streaming URL (added by the \ref IChannel::addPublishStreamUrl "addPublishStreamUrl" method) from a CDN live stream. The SDK returns the result of this method call in the \ref IRtcEngineEventHandler::onStreamUnpublished "onStreamUnpublished" callback. @@ -1255,9 +1425,11 @@ class IChannel { - 0: Success. - < 0: Failure. */ - virtual int removePublishStreamUrl(const char* url) = 0; + virtual int removePublishStreamUrl(const char* url) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Sets the video layout and audio settings for CDN live. (CDN live only.) + @deprecated This method is deprecated as of v3.6.0. See [Release Notes](https://docs.agora.io/en/Interactive%20Broadcast/release_windows_video?platform=Windows) for an alternative solution. + The SDK triggers the \ref agora::rtc::IChannelEventHandler::onTranscodingUpdated "onTranscodingUpdated" callback when you call the `setLiveTranscoding` method to update the transcoding setting. @@ -1273,7 +1445,105 @@ class IChannel { - 0: Success. - < 0: Failure. */ - virtual int setLiveTranscoding(const LiveTranscoding& transcoding) = 0; + virtual int setLiveTranscoding(const LiveTranscoding& transcoding) AGORA_DEPRECATED_ATTRIBUTE = 0; + /** + * Starts pushing media streams to a CDN without transcoding. + * + * @since v3.6.0 + * + * You can call this method to push a live audio-and-video stream to the specified CDN address. This method can push + * media streams to only one CDN address at a time, so if you need to push streams to multiple addresses, call this + * method multiple times. + * + * After you call this method, the SDK triggers the \ref IChannelEventHandler::onRtmpStreamingStateChanged "onRtmpStreamingStateChanged" + * callback on the local client to report the state of the streaming. + * + * @note + * - Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in *Push Streams to CDN*. + * - Call this method after joining a channel. + * - Only hosts in the `LIVE_BROADCASTING` profile can call this method. + * - If you want to retry pushing streams after a failed push, make sure to call \ref IChannel::stopRtmpStream "stopRtmpStream" first, + * then call this method to retry pushing streams; otherwise, the SDK returns the same error code as the last failed push. + * - If you want to push media streams in the RTMPS protocol to CDN, call \ref IChannel::startRtmpStreamWithTranscoding "startRtmpStreamWithTranscoding" + * instead of \ref IChannel::startRtmpStreamWithoutTranscoding "startRtmpStreamWithoutTranscoding". + * + * @param url The address of the CDN live streaming. The format is RTMP. The character length cannot exceed 1024 bytes. + * Special characters such as Chinese characters are not supported. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `ERR_INVALID_ARGUMENT(-2)`: url is null or the string length is 0. + * - `ERR_NOT_INITIALIZED(-7)`: The SDK is not initialized before calling this method. + */ + virtual int startRtmpStreamWithoutTranscoding(const char* url) = 0; + /** + * Starts pushing media streams to a CDN and sets the transcoding configuration. + * + * @since v3.6.0 + * + * You can call this method to push a live audio-and-video stream to the specified CDN address and set the transcoding + * configuration. This method can push media streams to only one CDN address at a time, so if you need to push streams to + * multiple addresses, call this method multiple times. + * + * After you call this method, the SDK triggers the \ref IChannelEventHandler::onRtmpStreamingStateChanged "onRtmpStreamingStateChanged" + * callback on the local client to report the state of the streaming. + * + * @note + * - Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in *Push Streams to CDN*. + * - Call this method after joining a channel. + * - Only hosts in the `LIVE_BROADCASTING` profile can call this method. + * - If you want to retry pushing streams after a failed push, make sure to call \ref IChannel::stopRtmpStream "stopRtmpStream" first, + * then call this method to retry pushing streams; otherwise, the SDK returns the same error code as the last failed push. + * - If you want to push media streams in the RTMPS protocol to CDN, call \ref IChannel::startRtmpStreamWithTranscoding "startRtmpStreamWithTranscoding" + * instead of \ref IChannel::startRtmpStreamWithoutTranscoding "startRtmpStreamWithoutTranscoding". + * + * @param url The address of the CDN live streaming. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. + * Special characters such as Chinese characters are not supported. + * @param transcoding The transcoding configuration for CDN live streaming. See LiveTranscoding. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `ERR_INVALID_ARGUMENT(-2)`: url is null or the string length is 0. + * - `ERR_NOT_INITIALIZED(-7)`: The SDK is not initialized before calling this method. + */ + virtual int startRtmpStreamWithTranscoding(const char* url, const LiveTranscoding& transcoding) = 0; + /** + * Updates the transcoding configuration. + * + * @since v3.6.0 + * + * After you start pushing media streams to CDN with transcoding, you can dynamically update the transcoding configuration according to the scenario. + * The SDK triggers the \ref IChannelEventHandler::onTranscodingUpdated "onTranscodingUpdated" callback after the + * transcoding configuration is updated. + * + * @param transcoding The transcoding configuration for CDN live streaming. See LiveTranscoding. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int updateRtmpTranscoding(const LiveTranscoding& transcoding) = 0; + /** + * Stops pushing media streams to a CDN. + * + * @since v3.6.0 + * + * You can call this method to stop the live stream on the specified CDN address. + * This method can stop pushing media streams to only one CDN address at a time, so if you need to stop pushing streams to multiple addresses, call this method multiple times. + * + * After you call this method, the SDK triggers the \ref IChannelEventHandler::onRtmpStreamingStateChanged "onRtmpStreamingStateChanged" callback on the local client to report the state of the streaming. + * + * @param url The address of the CDN live streaming. The format is RTMP or RTMPS. + * The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int stopRtmpStream(const char* url) = 0; + /** Adds a voice or video stream URL address to the interactive live streaming. The \ref IRtcEngineEventHandler::onStreamPublished "onStreamPublished" callback returns the inject status. @@ -1379,10 +1649,9 @@ class IChannel { * "onChannelMediaRelayEvent" callback with the * #RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL (7) state code. * - * @note - * Call this method after the - * \ref startChannelMediaRelay() "startChannelMediaRelay" method to update - * the destination channel. + * @note Call this method after successfully calling the \ref startChannelMediaRelay() "startChannelMediaRelay" method + * and receiving the \ref IChannelEventHandler::onChannelMediaRelayStateChanged "onChannelMediaRelayStateChanged" (RELAY_STATE_RUNNING, RELAY_OK) callback; + * otherwise, this method call fails. * * @param configuration The media stream relay configuration: * ChannelMediaRelayConfiguration. @@ -1392,6 +1661,47 @@ class IChannel { * - < 0: Failure. */ virtual int updateChannelMediaRelay(const ChannelMediaRelayConfiguration& configuration) = 0; + + /** + * Pauses the media stream relay to all destination channels. + * + * @since v3.5.1 + * + * After the cross-channel media stream relay starts, you can call this method + * to pause relaying media streams to all destination channels; after the pause, + * if you want to resume the relay, call \ref IChannel::resumeAllChannelMediaRelay "resumeAllChannelMediaRelay". + * + * After a successful method call, the SDK triggers the + * \ref IChannelEventHandler::onChannelMediaRelayEvent "onChannelMediaRelayEvent" + * callback to report whether the media stream relay is successfully paused. + * + * @note Call this method after the \ref IChannel::startChannelMediaRelay "startChannelMediaRelay" method. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int pauseAllChannelMediaRelay() = 0; + + /** Resumes the media stream relay to all destination channels. + * + * @since v3.5.1 + * + * After calling the \ref IChannel::pauseAllChannelMediaRelay "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 + * \ref IChannelEventHandler::onChannelMediaRelayEvent "onChannelMediaRelayEvent" + * callback to report whether the media stream relay is successfully resumed. + * + * @note Call this method after the \ref IChannel::pauseAllChannelMediaRelay "pauseAllChannelMediaRelay" method. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int resumeAllChannelMediaRelay() = 0; + /** Stops the media stream relay. * * Once the relay stops, the host quits all the destination @@ -1424,64 +1734,76 @@ class IChannel { @return #CONNECTION_STATE_TYPE. */ virtual CONNECTION_STATE_TYPE getConnectionState() = 0; - /// @cond - /** Enables/Disables the super-resolution algorithm for a remote user's video stream. + + /** Enables/Disables the super resolution feature for a remote user's video. (beta feature) * - * @since v3.2.0 + * @since v3.5.1 * - * The algorithm effectively improves the resolution of the specified remote user's video stream. When the original - * resolution of the remote video stream is a × b pixels, you can receive and render the stream at a higher - * resolution (2a × 2b pixels) by enabling the algorithm. + * This feature effectively boosts the resolution of a remote user's video seen by the local + * user. If the original resolution of a remote user's video is a × b, the local user's device + * can render the remote video at a resolution of 2a × 2b after you enable this feature. * * After calling this method, the SDK triggers the - * \ref IRtcChannelEventHandler::onUserSuperResolutionEnabled "onUserSuperResolutionEnabled" callback to report - * whether you have successfully enabled the super-resolution algorithm. - * - * @warning The super-resolution algorithm requires extra system resources. - * To balance the visual experience and system usage, the SDK poses the following restrictions: - * - The algorithm can only be used for a single user at a time. - * - On the Android platform, the original resolution of the remote video must not exceed 640 × 360 pixels. - * - On the iOS platform, the original resolution of the remote video must not exceed 640 × 480 pixels. - * If you exceed these limitations, the SDK triggers the \ref IRtcChannelEventHandler::onWarning "onWarning" - * callback with the corresponding warning codes: - * - #WARN_SUPER_RESOLUTION_STREAM_OVER_LIMITATION (1610): The origin resolution of the remote video is beyond the range where the super-resolution algorithm can be applied. - * - #WARN_SUPER_RESOLUTION_USER_COUNT_OVER_LIMITATION (1611): Another user is already using the super-resolution algorithm. - * - #WARN_SUPER_RESOLUTION_DEVICE_NOT_SUPPORTED (1612): The device does not support the super-resolution algorithm. + * \ref IChannelEventHandler::onUserSuperResolutionEnabled "onUserSuperResolutionEnabled" + * callback to report whether you have successfully enabled super resolution. + * + * @warning The super resolution feature requires extra system resources. To balance the visual experience and system consumption, the SDK poses the following restrictions: + * - This feature can only be enabled for a single remote user. + * - The original resolution of the remote user's video cannot exceed a certain range. If the local user use super resolution on Android, + * the original resolution of the remote user's video cannot exceed 640 × 360 pixels; if the local user use super resolution on iOS, + * the original resolution of the remote user's video cannot exceed 640 × 480 pixels. + * + * @warning If you exceed these limitations, the SDK triggers the + * \ref IRtcEngineEventHandler::onWarning "onWarning" callback and returns the corresponding warning codes: + * + * - #WARN_SUPER_RESOLUTION_STREAM_OVER_LIMITATION (1610): The original resolution of the remote user's video is beyond + * the range where super resolution can be applied. + * - #WARN_SUPER_RESOLUTION_USER_COUNT_OVER_LIMITATION (1611): Super resolution is already being used to boost another + * remote user's video. + * - #WARN_SUPER_RESOLUTION_DEVICE_NOT_SUPPORTED (1612): The device does not support using super resolution. * * @note - * - This method applies to Android and iOS only. - * - Requirements for the user's device: - * - Android: The following devices are known to support the method: - * - VIVO: V1821A, NEX S, 1914A, 1916A, and 1824BA - * - OPPO: PCCM00 + * - This method is for Android and iOS only. + * - Before calling this method, ensure that you have integrated the following dynamic library into your project: + * - Android: `libagora_super_resolution_extension.so` + * - iOS: `AgoraSuperResolutionExtension.xcframework` + * - Because this method has certain system performance requirements, Agora recommends that you use the following devices or better: + * - Android: + * - VIVO: V1821A, NEX S, 1914A, 1916A, 1962A, 1824BA, X60, X60 Pro + * - OPPO: PCCM00, Find X3 * - OnePlus: A6000 - * - Xiaomi: Mi 8, Mi 9, MIX3, and Redmi K20 Pro - * - SAMSUNG: SM-G9600, SM-G9650, SM-N9600, SM-G9708, SM-G960U, and SM-G9750 - * - HUAWEI: SEA-AL00, ELE-AL00, VOG-AL00, YAL-AL10, HMA-AL00, and EVR-AN00 - * - iOS: This method is supported on devices running iOS 12.0 or later. The following - * device models are known to support the method: + * - Xiaomi: Mi 8, Mi 9, Mi 10, Mi 11, MIX3, Redmi K20 Pro + * - SAMSUNG: SM-G9600, SM-G9650, SM-N9600, SM-G9708, SM-G960U, SM-G9750, S20, S21 + * - HUAWEI: SEA-AL00, ELE-AL00, VOG-AL00, YAL-AL10, HMA-AL00, EVR-AN00, nova 4, nova 5 Pro, + * nova 6 5G, nova 7 5G, Mate 30, Mate 30 Pro, Mate 40, Mate 40 Pro, P40 P40 Pro, HUAWEI MediaPad M6, MatePad 10.8 + * - iOS (iOS 12.0 or later): * - iPhone XR * - iPhone XS * - iPhone XS Max * - iPhone 11 * - iPhone 11 Pro * - iPhone 11 Pro Max - * - iPad Pro 11-inch (3rd Generation) - * - iPad Pro 12.9-inch (3rd Generation) - * - iPad Air 3 (3rd Generation) - * - * @param userId The ID of the remote user. - * @param enable Whether to enable the super-resolution algorithm: - * - true: Enable the super-resolution algorithm. - * - false: Disable the super-resolution algorithm. + * - iPhone 12 + * - iPhone 12 mini + * - iPhone 12 Pro + * - iPhone 12 Pro Max + * - iPhone 12 SE (2nd generation) + * - iPad Pro 11-inch (3rd generation) + * - iPad Pro 12.9-inch (3rd generation) + * - iPad Air (3rd generation) + * - iPad Air (4th generation) + * + * @param userId The user ID of the remote user. + * @param enable Determines whether to enable super resolution for the remote user's video: + * - true: Enable super resolution. + * - false: Disable super resolution. * * @return * - 0: Success. * - < 0: Failure. - * - -158 (ERR_MODULE_SUPER_RESOLUTION_NOT_FOUND): You have not integrated the dynamic library for the super-resolution algorithm. + * - `-157 (ERR_MODULE_NOT_FOUND)`: The dynamic library for super resolution is not integrated. */ virtual int enableRemoteSuperResolution(uid_t userId, bool enable) = 0; - /// @endcond }; /** @since v3.0.0 diff --git a/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/IAgoraRtcEngine.h b/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/IAgoraRtcEngine.h index 8fc262d28..b050af84a 100644 --- a/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/IAgoraRtcEngine.h +++ b/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/IAgoraRtcEngine.h @@ -14,12 +14,24 @@ #include "IAgoraService.h" #include "IAgoraLog.h" -#if defined(_WIN32) #include "IAgoraMediaEngine.h" +#if defined(TARGET_OS_IPHONE) && TARGET_OS_IPHONE /* Warning fixing. Lionfore Oct 12th, 2019 */ +#include #endif namespace agora { namespace rtc { +/** The IMediaRecorderObserver class. + * + * @since v3.5.2 + */ +class IMediaRecorderObserver; +/** + * The MediaRecorderConfiguration struct. + * + * @since v3.5.2 + */ +struct MediaRecorderConfiguration; typedef unsigned int uid_t; typedef void* view_t; /** Maximum length of the device ID. @@ -53,7 +65,7 @@ enum QUALITY_REPORT_FORMAT_TYPE { */ QUALITY_REPORT_HTML = 1, }; - +/// @cond enum MEDIA_ENGINE_EVENT_CODE_TYPE { /** 0: For internal use only. */ @@ -115,6 +127,9 @@ enum MEDIA_ENGINE_EVENT_CODE_TYPE { /** 113: For internal use only. */ MEDIA_ENGINE_AUDIO_ADM_USING_NORM_PARAMS = 113, + /** 114: For internal use only. + */ + MEDIA_ENGINE_AUDIO_ADM_ROUTING_UPDATE = 114, // audio mix event /** 720: For internal use only. */ @@ -151,31 +166,50 @@ enum MEDIA_ENGINE_EVENT_CODE_TYPE { */ MEDIA_ENGINE_AUDIO_ERROR_MIXING_NO_ERROR = 0, }; +/// @endcond -/** The states of the local user's audio mixing file. +/** The current music file playback state. + * + * Reports in the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" callback. */ enum AUDIO_MIXING_STATE_TYPE { - /** 710: The audio mixing file is playing after the method call of - * \ref IRtcEngine::startAudioMixing "startAudioMixing" or \ref IRtcEngine::resumeAudioMixing "resumeAudioMixing" succeeds. + /** 710: The music file is playing. + * + * This state comes with one of the following associated reasons: + * - #AUDIO_MIXING_REASON_STARTED_BY_USER (720) + * - #AUDIO_MIXING_REASON_ONE_LOOP_COMPLETED (721) + * - #AUDIO_MIXING_REASON_START_NEW_LOOP (722) + * - #AUDIO_MIXING_REASON_RESUMED_BY_USER (726) */ AUDIO_MIXING_STATE_PLAYING = 710, - /** 711: The audio mixing file pauses playing after the method call of \ref IRtcEngine::pauseAudioMixing "pauseAudioMixing" succeeds. + /** 711: The music file pauses playing. + * + * This state comes with #AUDIO_MIXING_REASON_PAUSED_BY_USER (725). */ AUDIO_MIXING_STATE_PAUSED = 711, - /** 713: The audio mixing file stops playing after the method call of \ref IRtcEngine::stopAudioMixing "stopAudioMixing" succeeds. + /** 713: The music file stops playing. + * + * This state comes with one of the following associated reasons: + * - #AUDIO_MIXING_REASON_ALL_LOOPS_COMPLETED (723) + * - #AUDIO_MIXING_REASON_STOPPED_BY_USER (724) */ AUDIO_MIXING_STATE_STOPPED = 713, - /** 714: An exception occurs during the playback of the audio mixing file. See the `errorCode` for details. + /** 714: An exception occurs during the playback of the music file. + * + * This state comes with one of the following associated reasons: + * - #AUDIO_MIXING_REASON_CAN_NOT_OPEN (701) + * - #AUDIO_MIXING_REASON_TOO_FREQUENT_CALL (702) + * - #AUDIO_MIXING_REASON_INTERRUPTED_EOF (703) */ AUDIO_MIXING_STATE_FAILED = 714, }; /** - * @deprecated Deprecated from v3.4.0, use AUDIO_MIXING_REASON_TYPE instead. + * @deprecated Deprecated from v3.4.0. Use #AUDIO_MIXING_REASON_TYPE instead. * * The error codes of the local user's audio mixing file. */ -enum AUDIO_MIXING_ERROR_TYPE { +enum AGORA_DEPRECATED_ATTRIBUTE AUDIO_MIXING_ERROR_TYPE { /** 701: The SDK cannot open the audio mixing file. */ AUDIO_MIXING_ERROR_CAN_NOT_OPEN = 701, @@ -190,37 +224,49 @@ enum AUDIO_MIXING_ERROR_TYPE { AUDIO_MIXING_ERROR_OK = 0, }; -/** The reason of audio mixing state change. +/** The reason for the change of the music file playback state. + * + * @since v3.4.0 + * + * Reports in the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" callback. */ enum AUDIO_MIXING_REASON_TYPE { - /** 701: The SDK cannot open the audio mixing file. + /** 701: The SDK cannot open the music file. Possible causes include 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_CAN_NOT_OPEN = 701, - /** 702: The SDK opens the audio mixing file too frequently. + /** 702: The SDK opens the music file too frequently. If you need to call + * \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" multiple times, ensure + * that the call interval is longer than 500 ms. */ AUDIO_MIXING_REASON_TOO_FREQUENT_CALL = 702, - /** 703: The audio mixing file playback is interrupted. + /** 703: The music file playback is interrupted. */ AUDIO_MIXING_REASON_INTERRUPTED_EOF = 703, - /** 720: The audio mixing is started by user. + /** 720: Successfully calls \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" + * to play a music file. */ AUDIO_MIXING_REASON_STARTED_BY_USER = 720, - /** 721: The audio mixing file is played once. + /** 721: The music file completes a loop playback. */ AUDIO_MIXING_REASON_ONE_LOOP_COMPLETED = 721, - /** 722: The audio mixing file is playing in a new loop. + /** 722: The music file starts a new loop playback. */ AUDIO_MIXING_REASON_START_NEW_LOOP = 722, - /** 723: The audio mixing file is all played out. + /** 723: The music file completes all loop playback. */ AUDIO_MIXING_REASON_ALL_LOOPS_COMPLETED = 723, - /** 724: Playing of audio file is stopped by user. + /** 724: Successfully calls \ref IRtcEngine::stopAudioMixing "stopAudioMixing" + * to stop playing the music file. */ AUDIO_MIXING_REASON_STOPPED_BY_USER = 724, - /** 725: Playing of audio file is paused by user. + /** 725: Successfully calls \ref IRtcEngine::pauseAudioMixing "pauseAudioMixing" + * to pause playing the music file. */ AUDIO_MIXING_REASON_PAUSED_BY_USER = 725, - /** 726: Playing of audio file is resumed by user. + /** 726: Successfully calls \ref IRtcEngine::resumeAudioMixing "resumeAudioMixing" + * to resume playing the music file. */ AUDIO_MIXING_REASON_RESUMED_BY_USER = 726, }; @@ -228,7 +274,14 @@ enum AUDIO_MIXING_REASON_TYPE { /** Media device states. */ enum MEDIA_DEVICE_STATE_TYPE { - /** 1: The device is active. + /** 0: The device is ready for use. + * + * @since v3.4.5 + */ + MEDIA_DEVICE_STATE_IDLE = 0, + /** 1: The device is in use. + * + * @since v3.4.5 */ MEDIA_DEVICE_STATE_ACTIVE = 1, /** 2: The device is disabled. @@ -242,7 +295,7 @@ enum MEDIA_DEVICE_STATE_TYPE { MEDIA_DEVICE_STATE_UNPLUGGED = 8, /** 16: The device is not recommended. */ - MEDIA_DEVICE_STATE_UNRECOMMENDED = 16 + MEDIA_DEVICE_STATE_UNRECOMMENDED = 16, }; /** Media device types. @@ -268,10 +321,10 @@ enum MEDIA_DEVICE_TYPE { AUDIO_APPLICATION_PLAYOUT_DEVICE = 4, }; -/** Local video state types +/** Local video state types. */ enum LOCAL_VIDEO_STREAM_STATE { - /** 0: Initial state */ + /** 0: Initial state. */ LOCAL_VIDEO_STREAM_STATE_STOPPED = 0, /** 1: The local video capturing device starts successfully. * @@ -284,7 +337,7 @@ enum LOCAL_VIDEO_STREAM_STATE { LOCAL_VIDEO_STREAM_STATE_FAILED = 3 }; -/** Local video state error codes +/** Local video state error codes. */ enum LOCAL_VIDEO_STREAM_ERROR { /** 0: The local video is normal. */ @@ -309,9 +362,24 @@ enum LOCAL_VIDEO_STREAM_ERROR { * @since v3.3.0 */ LOCAL_VIDEO_STREAM_ERROR_CAPTURE_MULTIPLE_FOREGROUND_APPS = 7, - /** 8:capture not found*/ + /** + * 8: The SDK cannot find the local video capture device. + * + * @since v3.4.0 + */ LOCAL_VIDEO_STREAM_ERROR_DEVICE_NOT_FOUND = 8, - + /** + * 10: (macOS and Windows only) The SDK cannot find the video device in the video device list. Check whether the ID + * of the video device is valid. + * + * @since v3.5.2 + */ + LOCAL_VIDEO_STREAM_ERROR_DEVICE_INVALID_ID = 10, + /** + * 11: The shared window is minimized when you call + * \ref IRtcEngine::startScreenCaptureByWindowId "startScreenCaptureByWindowId" + * to share a window. + */ LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_MINIMIZED = 11, /** 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. @@ -326,8 +394,20 @@ enum LOCAL_VIDEO_STREAM_ERROR { * the web video or document. After the user exits full-screen mode, the SDK reports this error code. */ LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_CLOSED = 12, - + /** + * 13: (Windows only) The window being shared is overlapped by another window, so the overlapped area is blacked out by + * the SDK during window sharing. + * + * @since v3.5.2 + */ + LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_OCCLUDED = 13, + /** + * 20: (Windows only) The SDK does not support sharing this type of window. + * + * @since v3.5.2 + */ LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_NOT_SUPPORTED = 20, + }; /** Local audio state types. @@ -369,29 +449,53 @@ enum LOCAL_AUDIO_STREAM_ERROR { /** 5: The local audio encoding fails. */ LOCAL_AUDIO_STREAM_ERROR_ENCODE_FAILURE = 5, - /** 6: No recording audio device. + /** 6: The SDK cannot find the local audio recording device. + * + * @since v3.4.0 */ LOCAL_AUDIO_STREAM_ERROR_NO_RECORDING_DEVICE = 6, - /** 7: No playout audio device. + /** 7: The SDK cannot find the local audio playback device. + * + * @since v3.4.0 + */ + LOCAL_AUDIO_STREAM_ERROR_NO_PLAYOUT_DEVICE = 7, + /** + * 8: The local audio capturing is interrupted by the system call. + */ + LOCAL_AUDIO_STREAM_ERROR_INTERRUPTED = 8, + /** 9: An invalid audio capture device ID. + * + * @since v3.5.1 + */ + LOCAL_AUDIO_STREAM_ERROR_RECORD_INVALID_ID = 9, + /** 10: An invalid audio playback device ID. + * + * @since v3.5.1 */ - LOCAL_AUDIO_STREAM_ERROR_NO_PLAYOUT_DEVICE = 7 + LOCAL_AUDIO_STREAM_ERROR_PLAYOUT_INVALID_ID = 10, }; -/** Audio recording qualities. +/** Audio recording quality, which is set in + * \ref IRtcEngine::startAudioRecording(const AudioRecordingConfiguration&) "startAudioRecording". */ enum AUDIO_RECORDING_QUALITY_TYPE { - /** 0: Low quality. The sample rate is 32 kHz, and the file size is around - * 1.2 MB after 10 minutes of recording. + /** 0: Low quality. For example, the size of an AAC file with a sample rate + * of 32,000 Hz and a 10-minute recording is approximately 1.2 MB. */ AUDIO_RECORDING_QUALITY_LOW = 0, - /** 1: Medium quality. The sample rate is 32 kHz, and the file size is - * around 2 MB after 10 minutes of recording. + /** 1: (Default) Medium quality. For example, the size of an AAC file with + * a sample rate of 32,000 Hz and a 10-minute recording is approximately + * 2 MB. */ AUDIO_RECORDING_QUALITY_MEDIUM = 1, - /** 2: High quality. The sample rate is 32 kHz, and the file size is - * around 3.75 MB after 10 minutes of recording. + /** 2: High quality. For example, the size of an AAC file with a sample rate + * of 32,000 Hz and a 10-minute recording is approximately 3.75 MB. */ AUDIO_RECORDING_QUALITY_HIGH = 2, + /** 3: Ultra high quality. For example, the size of an AAC file with a sample rate + * of 32,000 Hz and a 10-minute recording is approximately 7.5 MB. + */ + AUDIO_RECORDING_QUALITY_ULTRA_HIGH = 3, }; /** Network quality types. */ @@ -446,8 +550,8 @@ enum VIDEO_MIRROR_MODE_TYPE { VIDEO_MIRROR_MODE_DISABLED = 2, // disable mirror }; -/** **DEPRECATED** Video profiles. */ -enum VIDEO_PROFILE_TYPE { +/** @deprecated Video profiles. */ +enum AGORA_DEPRECATED_ATTRIBUTE VIDEO_PROFILE_TYPE { /** 0: 160 * 120, frame rate 15 fps, bitrate 65 Kbps. */ VIDEO_PROFILE_LANDSCAPE_120P = 0, /** 2: 120 * 120, frame rate 15 fps, bitrate 50 Kbps. */ @@ -610,12 +714,12 @@ Sets the sample rate, bitrate, encoding mode, and the number of channels:*/ enum AUDIO_PROFILE_TYPE // sample rate, bit rate, mono/stereo, speech/music codec { /** - 0: 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, music encoding, mono, and a bitrate of up to 16 Kbps. - - Android/macOS/iOS: A sample rate of 32 KHz, music encoding, mono, and a bitrate of up to 18 Kbps. - */ + * 0: Default audio profile: + * - For the `LIVE_BROADCASTING` 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_DEFAULT = 0, // use default settings /** 1: A sample rate of 32 KHz, audio encoding, mono, and a bitrate of up to 18 Kbps. @@ -650,7 +754,12 @@ enum AUDIO_PROFILE_TYPE // sample rate, bit rate, mono/stereo, speech/music cod */ enum AUDIO_SCENARIO_TYPE // set a suitable scenario for your app type { - /** 0: Default audio scenario. */ + /** 0: Default audio scenario. + * + * @note If you run the iOS app on an M1 Mac, due to the hardware differences + * between M1 Macs, iPhones, and iPads, the default audio scenario of the Agora + * iOS SDK is the same as that of the Agora macOS SDK. + */ AUDIO_SCENARIO_DEFAULT = 0, /** 1: Entertainment scenario where users need to frequently switch the user role. */ AUDIO_SCENARIO_CHATROOM_ENTERTAINMENT = 1, @@ -677,7 +786,7 @@ enum AUDIO_SCENARIO_TYPE // set a suitable scenario for your app type /** The channel profile. */ enum CHANNEL_PROFILE_TYPE { - /** (Default) Communication. This profile applies to scenarios such as an audio call or video call, + /** Communication. This profile applies to scenarios such as an audio call or video call, * where all users can publish and subscribe to streams. */ CHANNEL_PROFILE_COMMUNICATION = 0, @@ -703,7 +812,7 @@ enum CLIENT_ROLE_TYPE { /** The latency level of an audience member in interactive live streaming. * - * @note Takes effect only when the user role is `CLIENT_ROLE_BROADCASTER`. + * @note Takes effect only when the user role is `CLIENT_ROLE_AUDIENCE`. */ enum AUDIENCE_LATENCY_LEVEL_TYPE { /** 1: Low latency. */ @@ -711,24 +820,58 @@ enum AUDIENCE_LATENCY_LEVEL_TYPE { /** 2: (Default) Ultra low latency. */ AUDIENCE_LATENCY_LEVEL_ULTRA_LOW_LATENCY = 2, }; -/// @cond -/** The reason why the super-resolution algorithm is not successfully enabled. + +/** + * The reason why super resolution is not successfully enabled or the message + * that confirms success. + * + * @since v3.5.1 */ enum SUPER_RESOLUTION_STATE_REASON { - /** 0: The super-resolution algorithm is successfully enabled. + /** 0: Super resolution is successfully enabled. */ SR_STATE_REASON_SUCCESS = 0, - /** 1: The origin resolution of the remote video is beyond the range where - * the super-resolution algorithm can be applied. + /** 1: The original resolution of the remote video is beyond the range where + * super resolution can be applied. */ SR_STATE_REASON_STREAM_OVER_LIMITATION = 1, - /** 2: Another user is already using the super-resolution algorithm. + /** 2: Super resolution is already being used to boost another remote user's video. */ SR_STATE_REASON_USER_COUNT_OVER_LIMITATION = 2, - /** 3: The device does not support the super-resolution algorithm. + /** 3: The device does not support using super resolution. */ SR_STATE_REASON_DEVICE_NOT_SUPPORTED = 3, }; + +/** + * The reason why the virtual background is not successfully enabled or the message that confirms success. + * + * @since v3.4.5 + */ +enum VIRTUAL_BACKGROUND_SOURCE_STATE_REASON { + /** + * 0: The virtual background is successfully enabled. + */ + VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_SUCCESS = 0, + /** + * 1: The custom background image does not exist. Please check the value of `source` in VirtualBackgroundSource. + */ + VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_IMAGE_NOT_EXIST = 1, + /** + * 2: The color format of the custom background image is invalid. Please check the value of `color` in VirtualBackgroundSource. + */ + VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_COLOR_FORMAT_NOT_SUPPORTED = 2, + /** + * 3: The device does not support using the virtual background. + */ + VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_DEVICE_NOT_SUPPORTED = 3, +}; +/// @cond +enum CONTENT_INSPECT_RESULT { + CONTENT_INSPECT_NEUTRAL = 1, + CONTENT_INSPECT_SEXY = 2, + CONTENT_INSPECT_PORN = 3, +}; /// @endcond /** Reasons for a user being offline. */ @@ -762,41 +905,98 @@ enum RTMP_STREAM_PUBLISH_STATE { /** The RTMP or RTMPS streaming fails. See the errCode parameter for the detailed error information. You can also call the \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method to publish the RTMP or RTMPS streaming again. */ RTMP_STREAM_PUBLISH_STATE_FAILURE = 4, + /** The SDK is disconnecting from the Agora streaming server and CDN. + * When you call remove or stop to stop the streaming normally, the SDK reports the streaming state as `DISCONNECTING`, `IDLE` in sequence. + * + * @since v3.6.0 + */ + RTMP_STREAM_PUBLISH_STATE_DISCONNECTING = 5, }; /** Error codes of the RTMP or RTMPS streaming. */ -enum RTMP_STREAM_PUBLISH_ERROR { - /** The RTMP or RTMPS streaming publishes successfully. */ +enum RTMP_STREAM_PUBLISH_ERROR_TYPE { + /** 0: The RTMP or RTMPS streaming publishes successfully. */ RTMP_STREAM_PUBLISH_ERROR_OK = 0, - /** Invalid argument used. If, for example, you do not call the \ref IRtcEngine::setLiveTranscoding "setLiveTranscoding" method to configure the LiveTranscoding parameters before calling the addPublishStreamUrl method, the SDK returns this error. Check whether you set the parameters in the *setLiveTranscoding* method properly. */ + /** 1: Invalid argument used. If, for example, you do not call the \ref IRtcEngine::setLiveTranscoding "setLiveTranscoding" method to configure the LiveTranscoding parameters before calling the addPublishStreamUrl method, the SDK returns this error. Check whether you set the parameters in the *setLiveTranscoding* method properly. */ RTMP_STREAM_PUBLISH_ERROR_INVALID_ARGUMENT = 1, - /** The RTMP or RTMPS streaming is encrypted and cannot be published. */ + /** 2: The RTMP or RTMPS streaming is encrypted and cannot be published. */ RTMP_STREAM_PUBLISH_ERROR_ENCRYPTED_STREAM_NOT_ALLOWED = 2, - /** Timeout for the RTMP or RTMPS streaming. Call the \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method to publish the streaming again. */ + /** 3: Timeout for the RTMP or RTMPS streaming. Call the \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method to publish the streaming again. */ RTMP_STREAM_PUBLISH_ERROR_CONNECTION_TIMEOUT = 3, - /** An error occurs in Agora's streaming server. Call the `addPublishStreamUrl` method to publish the streaming again. */ + /** 4: An error occurs in Agora's streaming server. Call the `addPublishStreamUrl` method to publish the streaming again. */ RTMP_STREAM_PUBLISH_ERROR_INTERNAL_SERVER_ERROR = 4, - /** An error occurs in the CDN server. */ + /** 5: An error occurs in the CDN server. */ RTMP_STREAM_PUBLISH_ERROR_RTMP_SERVER_ERROR = 5, - /** The RTMP or RTMPS streaming publishes too frequently. */ + /** 6; The RTMP or RTMPS streaming publishes too frequently. */ RTMP_STREAM_PUBLISH_ERROR_TOO_OFTEN = 6, - /** The host publishes more than 10 URLs. Delete the unnecessary URLs before adding new ones. */ + /** 7: The host publishes more than 10 URLs. Delete the unnecessary URLs before adding new ones. */ RTMP_STREAM_PUBLISH_ERROR_REACH_LIMIT = 7, - /** The host manipulates other hosts' URLs. Check your app logic. */ + /** 8: The host manipulates other hosts' URLs. Check your app logic. */ RTMP_STREAM_PUBLISH_ERROR_NOT_AUTHORIZED = 8, - /** Agora's server fails to find the RTMP or RTMPS streaming. */ + /** 9: Agora's server fails to find the RTMP or RTMPS streaming. */ RTMP_STREAM_PUBLISH_ERROR_STREAM_NOT_FOUND = 9, - /** The format of the RTMP or RTMPS streaming URL is not supported. Check whether the URL format is correct. */ + /** 10: The format of the RTMP or RTMPS streaming URL is not supported. Check whether the URL format is correct. */ RTMP_STREAM_PUBLISH_ERROR_FORMAT_NOT_SUPPORTED = 10, + /** + * 11: The user role is not host, so the user cannot use the CDN live streaming function. + * Check your application code logic. + * + * @since v3.6.0 + */ + RTMP_STREAM_PUBLISH_ERROR_NOT_BROADCASTER = 11, // Note: match to ERR_PUBLISH_STREAM_NOT_BROADCASTER in AgoraBase.h + /** + * 13: The `updateRtmpTranscoding` or `setLiveTranscoding` method is called to update the transcoding configuration in a scenario where there is streaming without transcoding. + * Check your application code logic. + * + * @since v3.6.0 + */ + RTMP_STREAM_PUBLISH_ERROR_TRANSCODING_NO_MIX_STREAM = 13, // Note: match to ERR_PUBLISH_STREAM_TRANSCODING_NO_MIX_STREAM in AgoraBase.h + /** + * 14: Errors occurred in the host's network. + * + * @since v3.6.0 + */ + RTMP_STREAM_PUBLISH_ERROR_NET_DOWN = 14, // Note: match to ERR_NET_DOWN in AgoraBase.h + /** + * 15: Your App ID does not have permission to use the CDN live streaming function. + * Refer to [Prerequisites](https://docs.agora.io/en/Interactive%20Broadcast/cdn_streaming_windows?platform=Windows#prerequisites) to + * enable the CDN live streaming permission. + * + * @since v3.6.0 + */ + RTMP_STREAM_PUBLISH_ERROR_INVALID_APPID = 15, // Note: match to ERR_PUBLISH_STREAM_APPID_INVALID in AgoraBase.h + /** + * 100: The streaming has been stopped normally. After you call + * \ref IRtcEngine::removePublishStreamUrl "removePublishStreamUrl" + * to stop streaming, the SDK returns this value. + * + * @since v3.4.5 + */ + RTMP_STREAM_UNPUBLISH_ERROR_OK = 100, }; /** Events during the RTMP or RTMPS streaming. */ enum RTMP_STREAMING_EVENT { - /** An error occurs when you add a background image or a watermark image to the RTMP or RTMPS stream. + /** 1: An error occurs when you add a background image or a watermark image to the RTMP or RTMPS stream. */ RTMP_STREAMING_EVENT_FAILED_LOAD_IMAGE = 1, + /** 2: The streaming URL is already being used for CDN live streaming. If you want to start new streaming, use a new streaming URL. + * + * @since v3.4.5 + */ + RTMP_STREAMING_EVENT_URL_ALREADY_IN_USE = 2, + /** 3: The feature is not supported. + * + * @since v3.6.0 + */ + RTMP_STREAMING_EVENT_ADVANCED_FEATURE_NOT_SUPPORT = 3, + /** 4: Reserved. + * + * @since v3.6.0 + */ + RTMP_STREAMING_EVENT_REQUEST_TOO_OFTEN = 4, }; /** States of importing an external video stream in the interactive live streaming. */ @@ -883,19 +1083,29 @@ enum VIDEO_CODEC_PROFILE_TYPE { /** 66: Baseline video codec profile. Generally /** Video codec types */ enum VIDEO_CODEC_TYPE { - /** Standard VP8 */ + /** 1: Standard VP8 */ VIDEO_CODEC_VP8 = 1, - /** Standard H264 */ + /** 2: Standard H.264 */ VIDEO_CODEC_H264 = 2, - /** Enhanced VP8 */ + /** 3: Enhanced VP8 */ VIDEO_CODEC_EVP = 3, - /** Enhanced H264 */ + /** 4: Enhanced H.264 */ VIDEO_CODEC_E264 = 4, }; -/** Video Codec types for publishing streams. */ +/** + * The video codec type of the output video stream. + * + * @since v3.2.0 + */ enum VIDEO_CODEC_TYPE_FOR_STREAM { + /** + * 1: (Default) H.264 + */ VIDEO_CODEC_H264_FOR_STREAM = 1, + /** + * 2: H.265 + */ VIDEO_CODEC_H265_FOR_STREAM = 2, }; @@ -941,8 +1151,15 @@ enum AUDIO_REVERB_TYPE { * @deprecated Deprecated from v3.2.0. * * Local voice changer options. + * + * Gender-based beatification effect works best only when assigned a proper gender: + * + * - For male: #GENERAL_BEAUTY_VOICE_MALE_MAGNETIC + * - For female: #GENERAL_BEAUTY_VOICE_FEMALE_FRESH or #GENERAL_BEAUTY_VOICE_FEMALE_VITALITY + * + * Failure to do so can lead to voice distortion. */ -enum VOICE_CHANGER_PRESET { +enum AGORA_DEPRECATED_ATTRIBUTE VOICE_CHANGER_PRESET { /** * The original voice (no local voice change). */ @@ -1026,7 +1243,7 @@ enum VOICE_CHANGER_PRESET { * * Local voice reverberation presets. */ -enum AUDIO_REVERB_PRESET { +enum AGORA_DEPRECATED_ATTRIBUTE AUDIO_REVERB_PRESET { /** * Turn off local voice reverberation, that is, to use the original voice. */ @@ -1098,9 +1315,13 @@ enum AUDIO_REVERB_PRESET { * as `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)`. */ AUDIO_VIRTUAL_STEREO = 0x00200001, - /** 1: Electronic Voice.*/ + /** + * A pitch correction effect that corrects the user's pitch based on the pitch of the natural C major scale. + */ AUDIO_ELECTRONIC_VOICE = 0x00300001, - /** 1: 3D Voice.*/ + /** + * A 3D voice effect that makes the voice appear to be moving around the user. + */ AUDIO_THREEDIM_VOICE = 0x00400001 }; /** The options for SDK preset voice beautifier effects. @@ -1334,10 +1555,15 @@ enum VOICE_CONVERSION_PRESET { }; /** Audio codec profile types. The default value is LC_ACC. */ enum AUDIO_CODEC_PROFILE_TYPE { - /** 0: LC-AAC, which is the low-complexity audio codec type. */ + /** 0: (Default) LC-AAC */ AUDIO_CODEC_PROFILE_LC_AAC = 0, - /** 1: HE-AAC, which is the high-efficiency audio codec type. */ + /** 1: HE-AAC */ AUDIO_CODEC_PROFILE_HE_AAC = 1, + /** 2: HE-AAC v2 + * + * @since v3.6.0 + */ + AUDIO_CODEC_PROFILE_HE_AAC_V2 = 2, }; /** Remote audio states. @@ -1414,7 +1640,7 @@ enum REMOTE_AUDIO_STATE_REASON { /** The state of the remote video. */ enum REMOTE_VIDEO_STATE { - /** 0: The remote video is in the default state, probably due to #REMOTE_VIDEO_STATE_REASON_LOCAL_MUTED (3), #REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED (5), or #REMOTE_VIDEO_STATE_REASON_REMOTE_OFFLINE (7). + /** 0: The remote video is in the default state, probably due to #REMOTE_VIDEO_STATE_REASON_LOCAL_MUTED (3), #REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED (5), or #REMOTE_VIDEO_STATE_REASON_REMOTE_OFFLINE (7). */ REMOTE_VIDEO_STATE_STOPPED = 0, @@ -1593,13 +1819,34 @@ enum ORIENTATION_MODE { ORIENTATION_MODE_FIXED_PORTRAIT = 2, }; -/** Video degradation preferences when the bandwidth is a constraint. */ +/** Video degradation preferences under limited bandwidth. */ enum DEGRADATION_PREFERENCE { - /** 0: (Default) Degrade the frame rate in order to maintain the video 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 \ref IRtcEngineEventHandler::onVideoSizeChanged "onVideoSizeChanged". + */ MAINTAIN_QUALITY = 0, - /** 1: Degrade the video quality in order to maintain the frame rate. */ + /** 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_FRAMERATE = 1, - /** 2: (For future use) Maintain a balance between the frame rate and video quality. */ + /** 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 \ref IRtcEngineEventHandler::onVideoSizeChanged "onVideoSizeChanged". + */ MAINTAIN_BALANCED = 2, }; @@ -1696,7 +1943,9 @@ enum CONNECTION_CHANGED_REASON_TYPE { CONNECTION_CHANGED_JOIN_FAILED = 4, /** 5: The SDK has left the channel. */ CONNECTION_CHANGED_LEAVE_CHANNEL = 5, - /** 6: The connection failed since Appid is not valid. */ + /** + * 6: The specified App ID is invalid. Try to rejoin the channel with a valid App ID. + */ CONNECTION_CHANGED_INVALID_APP_ID = 6, /** 7: The connection failed since channel name is not valid. */ CONNECTION_CHANGED_INVALID_CHANNEL_NAME = 7, @@ -1724,8 +1973,10 @@ enum CONNECTION_CHANGED_REASON_TYPE { CONNECTION_CHANGED_CLIENT_IP_ADDRESS_CHANGED = 13, /** 14: Timeout for the keep-alive of the connection between the SDK and Agora's edge server. The connection state changes to CONNECTION_STATE_RECONNECTING(4). */ CONNECTION_CHANGED_KEEP_ALIVE_TIMEOUT = 14, - /** 15: In cloud proxy mode, the proxy server connection interrupted. */ - CONNECTION_CHANGED_PROXY_SERVER_INTERRUPTED = 15, + /** 19: The connection failed due to same uid joined again on another device. */ + CONNECTION_CHANGED_SAME_UID_LOGIN = 19, + /** 20: The connection failed due to too many broadcasters in the channel. */ + CONNECTION_CHANGED_TOO_MANY_BROADCASTERS = 20, }; /** Network type. */ @@ -1744,7 +1995,13 @@ enum NETWORK_TYPE { NETWORK_TYPE_MOBILE_3G = 4, /** 5: The network type is mobile 4G. */ NETWORK_TYPE_MOBILE_4G = 5, + /** 6: The network type is mobile 5G. + * + * @since v3.5.1 + */ + NETWORK_TYPE_MOBILE_5G = 6, }; +/// @cond /** * The reason for the upload failure. * @@ -1763,6 +2020,7 @@ enum UPLOAD_ERROR_REASON { */ UPLOAD_SERVER_ERROR = 2, }; +/// @endcond /** States of the last-mile network probe test. */ enum LASTMILE_PROBE_RESULT_STATE { @@ -1773,39 +2031,42 @@ enum LASTMILE_PROBE_RESULT_STATE { /** 3: The last-mile network probe test is not carried out, probably due to poor network conditions. */ LASTMILE_PROBE_RESULT_UNAVAILABLE = 3 }; -/** Audio output routing. */ +/** The current audio route. + * + * Reports in the \ref IRtcEngineEventHandler::onAudioRouteChanged "onAudioRouteChanged" callback. + */ enum AUDIO_ROUTE_TYPE { - /** Default. + /** -1: Default audio route. */ AUDIO_ROUTE_DEFAULT = -1, - /** Headset. + /** 0: The audio route is a headset with a microphone. */ AUDIO_ROUTE_HEADSET = 0, - /** Earpiece. + /** 1: The audio route is an earpiece. */ AUDIO_ROUTE_EARPIECE = 1, - /** Headset with no microphone. + /** 2: The audio route is a headset without a microphone. */ AUDIO_ROUTE_HEADSET_NO_MIC = 2, - /** Speakerphone. + /** 3: The audio route is the speaker that comes with the device. */ AUDIO_ROUTE_SPEAKERPHONE = 3, - /** Loudspeaker. + /** 4: (iOS and macOS only) The audio route is an external speaker. */ AUDIO_ROUTE_LOUDSPEAKER = 4, - /** Bluetooth headset. + /** 5: The audio route is a Bluetooth headset. */ AUDIO_ROUTE_BLUETOOTH = 5, - /** USB peripheral (macOS only). + /** 6: (macOS only) The audio route is a USB peripheral device. */ AUDIO_ROUTE_USB = 6, - /** HDMI peripheral (macOS only). + /** 7: (macOS only) The audio route is an HDMI peripheral device. */ AUDIO_ROUTE_HDMI = 7, - /** DisplayPort peripheral (macOS only). + /** 8: (macOS only) The audio route is a DisplayPort peripheral device. */ AUDIO_ROUTE_DISPLAYPORT = 8, - /** Apple AirPlay (macOS only). + /** 9: (iOS and macOS only) The audio route is Apple AirPlay. */ AUDIO_ROUTE_AIRPLAY = 9, }; @@ -1821,23 +2082,82 @@ enum CLOUD_PROXY_TYPE { /** 1: The cloud proxy for the UDP protocol. */ UDP_PROXY = 1, + /// @cond /** 2: The cloud proxy for the TCP (encrypted) protocol. */ TCP_PROXY = 2, + /// @endcond +}; +/// @cond +/** The local proxy mode type. */ +enum LOCAL_PROXY_MODE { + /** 0: Connect local proxy with high priority, if not connected to local proxy, fallback to sdrtn. + */ + ConnectivityFirst = 0, + /** 1: Only connect local proxy + */ + LocalOnly = 1, +}; +/// @endcond + +enum PROXY_TYPE { + /** 0: Do not use the cloud proxy. + */ + NONE_PROXY_TYPE = 0, + /** 1: The cloud proxy for the UDP protocol. + */ + UDP_PROXY_TYPE = 1, + /// @cond + /** 2: The cloud proxy for the TCP (encrypted) protocol. + */ + TCP_PROXY_TYPE = 2, + /// @endcond + /** 3: The local proxy. + */ + LOCAL_PROXY_TYPE = 3, + /** 4: auto fallback to tcp cloud proxy + */ + TCP_PROXY_AUTO_FALLBACK_TYPE = 4, }; +/** screencapture exclude window error. + * + * + */ +enum EXCLUDE_WINDOW_ERROR { + /** negative : fail to exclude window. + */ + EXCLUDE_WINDOW_FAIL = -1, + /** 0: none define. + */ + EXCLUDE_WINDOW_NONE = 0 +}; // namespace rtc #if (defined(__APPLE__) && TARGET_OS_IOS) -/** Audio session restriction. */ +/** + * The operational permission of the SDK on the audio session. + */ enum AUDIO_SESSION_OPERATION_RESTRICTION { - /** No restriction, the SDK has full control of the audio session operations. */ + /** + * 0: No restriction; the SDK can change the audio session. + */ AUDIO_SESSION_OPERATION_RESTRICTION_NONE = 0, - /** The SDK does not change the audio session category. */ + /** + * 1: The SDK cannot change the audio session category. + */ AUDIO_SESSION_OPERATION_RESTRICTION_SET_CATEGORY = 1, - /** The SDK does not change any setting of the audio session (category, mode, categoryOptions). */ + /** + * 2: The SDK cannot change the audio session category, mode, or categoryOptions. + */ AUDIO_SESSION_OPERATION_RESTRICTION_CONFIGURE_SESSION = 1 << 1, - /** The SDK keeps the audio session active when leaving a channel. */ + /** + * 4: The SDK keeps the audio session active when the user leaves the + * channel, for example, to play an audio file in the background. + */ AUDIO_SESSION_OPERATION_RESTRICTION_DEACTIVATE_SESSION = 1 << 2, - /** The SDK does not configure the audio session anymore. */ + /** + * 128: Completely restricts the operational permission of the SDK on the + * audio session; the SDK cannot change the audio session. + */ AUDIO_SESSION_OPERATION_RESTRICTION_ALL = 1 << 7, }; #endif @@ -1851,13 +2171,20 @@ enum CAMERA_DIRECTION { }; #endif -/** Audio recording position. */ +/** + * Recording content, which is set + * in \ref IRtcEngine::startAudioRecording(const AudioRecordingConfiguration&) "startAudioRecording". + */ enum AUDIO_RECORDING_POSITION { - /** The SDK will record the voices of all users in the channel. */ + /** 0: (Default) Records the mixed audio of the local user and all remote + * users. + */ AUDIO_RECORDING_POSITION_MIXED_RECORDING_AND_PLAYBACK = 0, - /** The SDK will record the voice of the local user. */ + /** 1: Records the audio of the local user only. + */ AUDIO_RECORDING_POSITION_RECORDING = 1, - /** The SDK will record the voices of remote users. */ + /** 2: Records the audio of all remote users only. + */ AUDIO_RECORDING_POSITION_MIXED_PLAYBACK = 2, }; @@ -1885,11 +2212,11 @@ struct LastmileProbeResult { /** Configurations of the last-mile network probe test. */ struct LastmileProbeConfig { - /** Sets whether or not to test the uplink network. Some users, for example, the audience in a `LIVE_BROADCASTING` channel, do not need such a test: + /** Sets whether to test the uplink network. Some users, for example, the audience in a `LIVE_BROADCASTING` channel, do not need such a test: - true: test. - false: do not test. */ bool probeUplink; - /** Sets whether or not to test the downlink network: + /** Sets whether to test the downlink network: - true: test. - false: do not test. */ bool probeDownlink; @@ -1918,7 +2245,7 @@ struct AudioVolumeInfo { * * @note * - The `vad` parameter cannot report the voice activity status of remote users. - * In the remote users' callback, `vad` is always `0`. + * In the remote users' callback, `vad` is always `1`. * - To use this parameter, you must set the `report_vad` parameter to `true` * when calling \ref agora::rtc::IRtcEngine::enableAudioVolumeIndication(int, int, bool) "enableAudioVolumeIndication". */ @@ -1927,6 +2254,62 @@ struct AudioVolumeInfo { */ const char* channelId; }; + +/** + * The information of an audio file. This struct is reported + * in \ref IRtcEngineEventHandler::onRequestAudioFileInfo "onRequestAudioFileInfo". + * + * @since v3.5.1 + */ +struct AudioFileInfo { + /** The file path. + */ + const char* filePath; + /** The file duration (ms). + */ + int durationMs; +}; + +/** The information acquisition state. This enum is reported + * in \ref IRtcEngineEventHandler::onRequestAudioFileInfo "onRequestAudioFileInfo". + * + * @since v3.5.1 + */ +enum AUDIO_FILE_INFO_ERROR { + /** 0: Successfully get the information of an audio file. + */ + AUDIO_FILE_INFO_ERROR_OK = 0, + + /** 1: Fail to get the information of an audio file. + */ + AUDIO_FILE_INFO_ERROR_FAILURE = 1 +}; + +/// @cond +/** + * The reason for failure of changing role. + * + * @since v3.6.1 + */ +enum CLIENT_ROLE_CHANGE_FAILED_REASON { + /** 1: Too many broadcasters in the channel. + */ + CLIENT_ROLE_CHANGE_FAILED_BY_TOO_MANY_BROADCASTERS = 1, + + /** 2: Change operation not authorized. + */ + CLIENT_ROLE_CHANGE_FAILED_BY_NOT_AUTHORIZED = 2, + + /** 3: Change operation timer out. + */ + CLIENT_ROLE_CHANGE_FAILED_BY_REQUEST_TIME_OUT = 3, + + /** 4: Change operation is interrupted since we lost connection with agora service. + */ + CLIENT_ROLE_CHANGE_FAILED_BY_CONNECTION_FAILED = 4, +}; +/// @endcond + /** The detailed options of a user. */ struct ClientRoleOptions { @@ -2013,7 +2396,9 @@ struct RtcStats { /** * Application CPU usage (%). * - * @note The `cpuAppUsage` reported in the \ref IRtcEngineEventHandler::onLeaveChannel "onLeaveChannel" callback is always 0. + * @note + * - The `cpuAppUsage` reported in the \ref IRtcEngineEventHandler::onLeaveChannel "onLeaveChannel" callback is always 0. + * - As of Android 8.1, you cannot get the CPU usage from this attribute due to system limitations. */ double cpuAppUsage; /** @@ -2022,10 +2407,19 @@ struct RtcStats { * In the multi-kernel environment, this member represents the average CPU usage. * The value **=** 100 **-** System Idle Progress in Task Manager (%). * - * @note The `cpuTotalUsage` reported in the \ref IRtcEngineEventHandler::onLeaveChannel "onLeaveChannel" callback is always 0. + * @note + * - The `cpuTotalUsage` reported in the \ref IRtcEngineEventHandler::onLeaveChannel "onLeaveChannel" callback is always 0. + * - As of Android 8.1, you cannot get the CPU usage from this attribute due to system limitations. */ double cpuTotalUsage; /** The round-trip time delay from the client to the local router. + * + * @note + * - On iOS, As of v3.3.0, this attribute is disabled on devices running iOS 14 or later, and enabled on devices + * running versions earlier than iOS 14 by default. To enable this property on devices running iOS 14 or later, + * contact support@agora.io. See [FAQ](https://docs.agora.io/en/Interactive%20Broadcast/faq/local_network_privacy) for details. + * - On Android, to get this attribute, ensure that the `android.permission.ACCESS_WIFI_STATE` permission has been added after `` in + * the `AndroidManifest.xml` file in your project. */ int gatewayRtt; /** @@ -2049,6 +2443,37 @@ struct RtcStats { 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), txPacketLossRate(0), rxPacketLossRate(0), userCount(0), cpuAppUsage(0), cpuTotalUsage(0), gatewayRtt(0), memoryAppUsageRatio(0), memoryTotalUsageRatio(0), memoryAppUsageInKbytes(0) {} }; +/** The reason of notifying the user of a message. + */ +enum WLACC_MESSAGE_REASON { + /** WIFI signal is weak.*/ + WLACC_MESSAGE_REASON_WEAK_SIGNAL = 0, + /** 2.4G band congestion.*/ + WLACC_MESSAGE_REASON_2G_CHANNEL_CONGESTION = 1, +}; +/** Suggest an action for the user. + */ +enum WLACC_SUGGEST_ACTION { + /** Please get close to AP.*/ + WLACC_SUGGEST_ACTION_CLOSE_TO_WIFI = 0, + /** The user is advised to connect to the prompted SSID.*/ + WLACC_SUGGEST_ACTION_CONNECT_5G = 1, + /** The user is advised to check whether the AP supports 5G band and enable 5G band (the aciton link is attached), or purchases an AP that supports 5G. AP does not support 5G band.*/ + WLACC_SUGGEST_ACTION_CHECK_5G = 2, + /** The user is advised to change the SSID of the 2.4G or 5G band (the aciton link is attached). The SSID of the 2.4G band AP is the same as that of the 5G band.*/ + WLACC_SUGGEST_ACTION_MODIFY_SSID = 3, +}; +/** Indicator optimization degree. + */ +struct WlAccStats { + /** End-to-end delay optimization percentage.*/ + unsigned short e2eDelayPercent; + /** Frozen Ratio optimization percentage.*/ + unsigned short frozenRatioPercent; + /** Loss Rate optimization percentage.*/ + unsigned short lossRatePercent; +}; + /** Quality change of the local video in terms of target frame rate and target bit rate since last count. */ enum QUALITY_ADAPT_INDICATION { @@ -2059,6 +2484,12 @@ enum QUALITY_ADAPT_INDICATION { /** The quality worsens because the network bandwidth decreases. */ ADAPT_DOWN_BANDWIDTH = 2, }; + +struct ScreenCaptureInfo { + const char* graphicsCardType; + EXCLUDE_WINDOW_ERROR errCode; +}; + /** Quality of experience (QoE) of the local user when receiving a remote audio stream. * * @since v3.3.0 @@ -2185,6 +2616,26 @@ enum CHANNEL_MEDIA_RELAY_EVENT { /** 11: The video profile is sent to the server. */ RELAY_EVENT_VIDEO_PROFILE_UPDATE = 11, + /** 12: The SDK successfully pauses relaying the media stream to destination channels. + * + * @since v3.5.1 + */ + RELAY_EVENT_PAUSE_SEND_PACKET_TO_DEST_CHANNEL_SUCCESS = 12, + /** 13: The SDK fails to pause relaying the media stream to destination channels. + * + * @since v3.5.1 + */ + RELAY_EVENT_PAUSE_SEND_PACKET_TO_DEST_CHANNEL_FAILED = 13, + /** 14: The SDK successfully resumes relaying the media stream to destination channels. + * + * @since v3.5.1 + */ + RELAY_EVENT_RESUME_SEND_PACKET_TO_DEST_CHANNEL_SUCCESS = 14, + /** 15: The SDK fails to resume relaying the media stream to destination channels. + * + * @since v3.5.1 + */ + RELAY_EVENT_RESUME_SEND_PACKET_TO_DEST_CHANNEL_FAILED = 15, }; /** The state code in CHANNEL_MEDIA_RELAY_STATE. */ @@ -2206,6 +2657,12 @@ enum CHANNEL_MEDIA_RELAY_STATE { RELAY_STATE_FAILURE = 3, }; +/**Audio Device Test.different volume Type*/ +enum AudioDeviceTestVolumeType { + AudioTestRecordingVolume = 0, + AudioTestPlaybackVolume = 1, +}; + /** Statistics of the local video stream. */ struct LocalVideoStats { @@ -2509,10 +2966,6 @@ struct VideoEncoderConfiguration { | 1920 * 1080 | 15 | 2080 | 4160 | | 1920 * 1080 | 30 | 3150 | 6300 | | 1920 * 1080 | 60 | 4780 | 6500 | - | 2560 * 1440 | 30 | 4850 | 6500 | - | 2560 * 1440 | 60 | 6500 | 6500 | - | 3840 * 2160 | 30 | 6500 | 6500 | - | 3840 * 2160 | 60 | 6500 | 6500 | */ int bitrate; @@ -2540,36 +2993,48 @@ struct VideoEncoderConfiguration { VideoEncoderConfiguration() : dimensions(640, 480), frameRate(FRAME_RATE_FPS_15), minFrameRate(-1), bitrate(STANDARD_BITRATE), minBitrate(DEFAULT_MIN_BITRATE), orientationMode(ORIENTATION_MODE_ADAPTIVE), degradationPreference(MAINTAIN_QUALITY), mirrorMode(VIDEO_MIRROR_MODE_AUTO) {} }; -/** Audio recording configurations. +/** Recording configuration, which is set in + * \ref IRtcEngine::startAudioRecording(const AudioRecordingConfiguration&) "startAudioRecording". + * + * @since v3.4.0 */ struct AudioRecordingConfiguration { - /** Pointer to the absolute file path of the recording file. The string of the file name is in UTF-8. - - The SDK determines the storage format of the recording file by the file name suffix: - - - .wav: Large file size with high fidelity. - - .aac: Small file size with low fidelity. - - Ensure that the directory to save the recording file exists and is writable. + /** The absolute path (including the filename extensions) of the recording + * file. For example: `C:\music\audio.aac`. + * + * @note Ensure that the path you specify exists and is writable. */ const char* filePath; - /** Sets the audio recording quality. See #AUDIO_RECORDING_QUALITY_TYPE. - - @note It is effective only when the recording format is AAC. + /** Audio recording quality. See #AUDIO_RECORDING_QUALITY_TYPE. + * + * @note This parameter applies to AAC files only. */ AUDIO_RECORDING_QUALITY_TYPE recordingQuality; - /** Sets the audio recording position. See #AUDIO_RECORDING_POSITION. + /** Recording content. See #AUDIO_RECORDING_POSITION. */ AUDIO_RECORDING_POSITION recordingPosition; - /** Sets the sample rate (Hz) of the recording file. Supported values are as follows: - * - 16000 - * - (Default) 32000 - * - 44100 - * - 48000 + /** Recording sample rate (Hz). The following values are supported: + * + * - `16000` + * - (Default) `32000` + * - `44100` + * - `48000` + * + * @note If this parameter is set to `44100` or `48000`, for better + * recording effects, Agora recommends recording WAV files or AAC files + * whose `recordingQuality` is + * #AUDIO_RECORDING_QUALITY_MEDIUM or #AUDIO_RECORDING_QUALITY_HIGH. */ int recordingSampleRate; - AudioRecordingConfiguration() : filePath(nullptr), recordingQuality(AUDIO_RECORDING_QUALITY_MEDIUM), recordingPosition(AUDIO_RECORDING_POSITION_MIXED_RECORDING_AND_PLAYBACK), recordingSampleRate(32000) {} - AudioRecordingConfiguration(const char* path, AUDIO_RECORDING_QUALITY_TYPE quality, AUDIO_RECORDING_POSITION position, int sampleRate) : filePath(path), recordingQuality(quality), recordingPosition(position), recordingSampleRate(sampleRate) {} + /** Recording channel. The following values are supported: + * + * - (Default) 1 + * - 2 + */ + int recordingChannel; + + AudioRecordingConfiguration() : filePath(nullptr), recordingQuality(AUDIO_RECORDING_QUALITY_MEDIUM), recordingPosition(AUDIO_RECORDING_POSITION_MIXED_RECORDING_AND_PLAYBACK), recordingSampleRate(32000), recordingChannel(1) {} + AudioRecordingConfiguration(const char* path, AUDIO_RECORDING_QUALITY_TYPE quality, AUDIO_RECORDING_POSITION position, int sampleRate, int channel) : filePath(path), recordingQuality(quality), recordingPosition(position), recordingSampleRate(sampleRate), recordingChannel(channel) {} }; /** The video and audio properties of the user displaying the video in the CDN live. Agora supports a maximum of 17 transcoding users in a CDN streaming channel. @@ -2629,7 +3094,7 @@ typedef struct TranscodingUser { The properties of the watermark and background images. */ typedef struct RtcImage { - RtcImage() : url(NULL), x(0), y(0), width(0), height(0) {} + RtcImage() : url(NULL), x(0), y(0), width(0), height(0), zOrder(0), alpha(1.0) {} /** HTTP/HTTPS URL address of the image on the live video. The maximum length of this parameter is 1024 bytes. */ const char* url; /** Horizontal position of the image from the upper left of the live video. */ @@ -2640,17 +3105,32 @@ typedef struct RtcImage { int width; /** Height of the image on the live video. */ int height; + /** + * The layer number of the watermark or background image. The value range is [0,255]: + * - `0`: (Default) The bottom layer. + * - `255`: The top layer. + * + * @since v3.6.0 + */ + int zOrder; + /** The transparency of the watermark or background image. The value range is [0.0,1.0]: + * - `0.0`: Completely transparent. + * - `1.0`: (Default) Opaque. + * + * @since v3.6.0 + */ + double alpha; } RtcImage; /// @cond /** The configuration for advanced features of the RTMP or RTMPS streaming with transcoding. */ typedef struct LiveStreamAdvancedFeature { LiveStreamAdvancedFeature() : featureName(NULL), opened(false) {} - + LiveStreamAdvancedFeature(const char* feat_name, bool open) : featureName(feat_name), opened(open) {} /** The advanced feature for high-quality video with a lower bitrate. */ - const char* LBHQ = "lbhq"; + // static const char* LBHQ = "lbhq"; /** The advanced feature for the optimized video encoder. */ - const char* VEO = "veo"; + // static const char* VEO = "veo"; /** The name of the advanced feature. It contains LBHQ and VEO. */ @@ -2662,17 +3142,22 @@ typedef struct LiveStreamAdvancedFeature { */ bool opened; } LiveStreamAdvancedFeature; + /// @endcond /** A struct for managing CDN live audio/video transcoding settings. */ typedef struct LiveTranscoding { /** The width of the video in pixels. The default value is 360. - * - When pushing video streams to the CDN, ensure that `width` is at least 64; otherwise, the Agora server adjusts the value to 64. + * - When pushing video streams to the CDN, the value range of `width` is [64,1920]. + * If the value is less than 64, Agora server automatically adjusts it to 64; if the + * value is greater than 1920, Agora server automatically adjusts it to 1920. * - When pushing audio streams to the CDN, set `width` and `height` as 0. */ int width; /** The height of the video in pixels. The default value is 640. - * - When pushing video streams to the CDN, ensure that `height` is at least 64; otherwise, the Agora server adjusts the value to 64. + * - When pushing video streams to the CDN, the value range of `height` is [64,1080]. + * If the value is less than 64, Agora server automatically adjusts it to 64; if the + * value is greater than 1080, Agora server automatically adjusts it to 1080. * - When pushing audio streams to the CDN, set `width` and `height` as 0. */ int height; @@ -2706,10 +3191,16 @@ typedef struct LiveTranscoding { */ unsigned int backgroundColor; - /** video codec type */ + /** + * The video codec type of the output video stream. See #VIDEO_CODEC_TYPE_FOR_STREAM. + * + * @since v3.2.0 + */ VIDEO_CODEC_TYPE_FOR_STREAM videoCodecType; /** The number of users in the interactive live streaming. + * + * The value range is [0, 17]. */ unsigned int userCount; /** TranscodingUser @@ -2724,16 +3215,33 @@ typedef struct LiveTranscoding { /** **DEPRECATED** The metadata sent to the CDN live client defined by the RTMP or HTTP-FLV metadata. */ const char* metadata; - /** The watermark image added to the CDN live publishing stream. - - Ensure that the format of the image is PNG. Once a watermark image is added, the audience of the CDN live publishing stream can see the watermark image. See RtcImage. - */ + /** + * The watermark on the live video. The format must be in the PNG format. See RtcImage. + * You can add a watermark or use an array to add multiple watermarks. + * This parameter is used in conjunction with `watermarkCount`. + */ RtcImage* watermark; - /** The background image added to the CDN live publishing stream. - Once a background image is added, the audience of the CDN live publishing stream can see the background image. See RtcImage. - */ + /** + * The number of watermarks on the live video. The value range is [0,100]. + * This parameter is used in conjunction with `watermark`. + * + * @since v3.6.0 + */ + unsigned int watermarkCount; + + /** + * The background image on the live video. The format must be in the PNG format. See RtcImage. + * You can add a background image or use an array to add multiple background images. + * This parameter is used in conjunction with `backgroundImageCount`. + */ RtcImage* backgroundImage; + /** + * The number of background images on the live video. The value range is [0,100]. + * This parameter is used in conjunction with `backgroundImage`. + */ + unsigned int backgroundImageCount; + /** Self-defined audio-sample rate: #AUDIO_SAMPLE_RATE_TYPE. */ AUDIO_SAMPLE_RATE_TYPE audioSampleRate; @@ -2763,7 +3271,7 @@ typedef struct LiveTranscoding { /** The number of enabled advanced features. The default value is 0. */ unsigned int advancedFeatureCount; /// @endcond - LiveTranscoding() : width(360), height(640), videoBitrate(400), videoFramerate(15), lowLatency(false), videoGop(30), videoCodecProfile(VIDEO_CODEC_PROFILE_HIGH), backgroundColor(0x000000), videoCodecType(VIDEO_CODEC_H264_FOR_STREAM), userCount(0), transcodingUsers(NULL), transcodingExtraInfo(NULL), metadata(NULL), watermark(NULL), backgroundImage(NULL), audioSampleRate(AUDIO_SAMPLE_RATE_48000), audioBitrate(48), audioChannels(1), audioCodecProfile(AUDIO_CODEC_PROFILE_LC_AAC), advancedFeatures(NULL), advancedFeatureCount(0) {} + LiveTranscoding() : width(360), height(640), videoBitrate(400), videoFramerate(15), lowLatency(false), videoGop(30), videoCodecProfile(VIDEO_CODEC_PROFILE_HIGH), backgroundColor(0x000000), videoCodecType(VIDEO_CODEC_H264_FOR_STREAM), 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), advancedFeatures(NULL), advancedFeatureCount(0) {} } LiveTranscoding; /** Camera capturer configuration. @@ -2916,6 +3424,29 @@ struct ChannelMediaRelayConfiguration { ChannelMediaRelayConfiguration() : srcInfo(nullptr), destInfos(nullptr), destCount(0) {} }; +/// @cond +struct LocalAccessPointConfiguration { + /** local access point ip address list. + */ + const char** ipList; + /** the number of local access point ip address. + */ + int ipListSize; + /** local access point domain list. + */ + const char** domainList; + /** the number of local access point domain. + */ + int domainListSize; + /** certificate domain name installed on specific local access point. pass "" means using sni domain on specific local access point + */ + const char* verifyDomainName; + /** local proxy connection mode, connectivity first or local only. + */ + LOCAL_PROXY_MODE mode; + LocalAccessPointConfiguration() : ipList(nullptr), ipListSize(0), domainList(nullptr), domainListSize(0), verifyDomainName(nullptr), mode(ConnectivityFirst) {} +}; +/// @endcond /** **DEPRECATED** Lifecycle of the CDN live video stream. */ @@ -3025,7 +3556,7 @@ struct ScreenCaptureParameters { The default value is 0 (the SDK works out a bitrate according to the dimensions of the current screen). */ int bitrate; - /** Sets whether or not to capture the mouse for screen sharing: + /** Sets whether to capture the mouse for screen sharing: - true: (Default) Capture the mouse. - false: Do not capture the mouse. @@ -3098,10 +3629,10 @@ struct VideoCanvas { /** Image enhancement options. */ struct BeautyOptions { - /** The contrast level, used with the @p lightening parameter. + /** The contrast level, often used in conjunction with `lighteningLevel`. */ enum LIGHTENING_CONTRAST_LEVEL { - /** Low contrast level. */ + /** 0: Low contrast level. */ LIGHTENING_CONTRAST_LOW = 0, /** (Default) Normal contrast level. */ LIGHTENING_CONTRAST_NORMAL, @@ -3109,24 +3640,194 @@ struct BeautyOptions { LIGHTENING_CONTRAST_HIGH }; - /** The contrast level, used with the @p lightening parameter. + /** The contrast level, often used in conjunction with `lighteningLevel`. + * The higher the value, the greater the contrast level. See #LIGHTENING_CONTRAST_LEVEL. */ LIGHTENING_CONTRAST_LEVEL lighteningContrastLevel; - /** The brightness level. The value ranges from 0.0 (original) to 1.0. */ + /** + * The brightening level, in the range [0.0,1.0], where 0.0 means the original brightening. The default value is 0.6. The higher the value, the greater the brightening level. + */ float lighteningLevel; - /** The sharpness level. The value ranges between 0 (original) and 1. This parameter is usually used to remove blemishes. + /** The smoothness level, in the range [0.0,1.0], where 0.0 means the original smoothness. The default value is 0.5. The higher the value, the greater the smoothness level. */ float smoothnessLevel; - /** The redness level. The value ranges between 0 (original) and 1. This parameter adjusts the red saturation level. + /** The redness level, in the range [0.0,1.0], where 0.0 means the original redness. The default value is 0.1. The higher the value, the greater the redness level. */ float rednessLevel; - BeautyOptions(LIGHTENING_CONTRAST_LEVEL contrastLevel, float lightening, float smoothness, float redness) : lighteningLevel(lightening), smoothnessLevel(smoothness), rednessLevel(redness), lighteningContrastLevel(contrastLevel) {} + /** The sharpness level, in the range [0.0,1.0], where 0.0 means the original sharpness. + * The default value is 0.3. The higher the value, the greater the sharpness level. + * + * @since v3.6.0 + */ + float sharpnessLevel; + + BeautyOptions(LIGHTENING_CONTRAST_LEVEL contrastLevel, float lightening, float smoothness, float redness, float sharpness) : lighteningLevel(lightening), smoothnessLevel(smoothness), rednessLevel(redness), lighteningContrastLevel(contrastLevel), sharpnessLevel(sharpness) {} + + BeautyOptions() : lighteningLevel(0), smoothnessLevel(0), rednessLevel(0), sharpnessLevel(0), lighteningContrastLevel(LIGHTENING_CONTRAST_NORMAL) {} +}; + +/** lowlight enhancement options. + */ +struct LowLightEnhanceOptions { + enum LOW_LIGHT_ENHANCE_MODE { + /** low light enhancement is applied automatically when neccessary. */ + LOW_LIGHT_ENHANCE_AUTO = 0, + /** low light enhancement is applied manually. */ + LOW_LIGHT_ENHANCE_MANUAL + }; + + enum LOW_LIGHT_ENHANCE_LEVEL { + /** low light enhancement is applied without reducing frame rate. */ + LOW_LIGHT_ENHANCE_LEVEL_HIGH_QUALITY = 0, + /** High-quality low light enhancement is applied, at the cost of possibly reduced frame rate and higher cpu usage. */ + LOW_LIGHT_ENHANCE_LEVEL_FAST + }; + + /** lowlight enhancement mode. + */ + LOW_LIGHT_ENHANCE_MODE mode; + + /** lowlight enhancement level. + */ + LOW_LIGHT_ENHANCE_LEVEL level; + + LowLightEnhanceOptions(LOW_LIGHT_ENHANCE_MODE lowlightMode, LOW_LIGHT_ENHANCE_LEVEL lowlightLevel) : mode(lowlightMode), level(lowlightLevel) {} + + LowLightEnhanceOptions() : mode(LOW_LIGHT_ENHANCE_AUTO), level(LOW_LIGHT_ENHANCE_LEVEL_HIGH_QUALITY) {} +}; + +struct VideoDenoiserOptions { + /** video noise reduction mode + */ + enum VIDEO_DENOISER_MODE { + /** video noise reduction is applied automatically when neccessary. */ + VIDEO_DENOISER_AUTO = 0, + /** video noise reduction is applied manually. */ + VIDEO_DENOISER_MANUAL + }; + + enum VIDEO_DENOISER_LEVEL { + /** Video noise reduction is applied for the default scene */ + VIDEO_DENOISER_LEVEL_HIGH_QUALITY = 0, + /** Video noise reduction is applied for the fixed-camera scene to save the cpu usage */ + VIDEO_DENOISER_LEVEL_FAST, + /** Video noise reduction is applied for the high noisy scene to further denoise the video. */ + VIDEO_DENOISER_LEVEL_STRENGTH + }; + /** video noise reduction mode. + */ + VIDEO_DENOISER_MODE mode; + + /** video noise reduction level. + */ + VIDEO_DENOISER_LEVEL level; + + VideoDenoiserOptions(VIDEO_DENOISER_MODE denoiserMode, VIDEO_DENOISER_LEVEL denoiserLevel) : mode(denoiserMode), level(denoiserLevel) {} + + VideoDenoiserOptions() : mode(VIDEO_DENOISER_AUTO), level(VIDEO_DENOISER_LEVEL_HIGH_QUALITY) {} +}; + +/** color enhancement options. + */ +struct ColorEnhanceOptions { + /** Color enhance strength. The value ranges between 0 (original) and 1. + */ + float strengthLevel; + + /** Skin protect level. The value ranges between 0 (original) and 1. + */ + float skinProtectLevel; + + ColorEnhanceOptions(float stength, float skinProtect) : strengthLevel(stength), skinProtectLevel(skinProtect) {} + + ColorEnhanceOptions() : strengthLevel(0), skinProtectLevel(1) {} +}; + +/** The custom background image. + * + * @since v3.4.5 + */ +struct VirtualBackgroundSource { + /** The type of the custom background image. + * + * @since v3.4.5 + */ + enum BACKGROUND_SOURCE_TYPE { + /** + * 1: (Default) The background image is a solid color. + */ + BACKGROUND_COLOR = 1, + /** + * The background image is a file in PNG or JPG format. + */ + BACKGROUND_IMG, + /** + * The background image is blurred. + * + * @since v3.5.1 + */ + BACKGROUND_BLUR, + }; + + /** + * The degree of blurring applied to the custom background image. + * + * @since v3.5.1 + */ + enum BACKGROUND_BLUR_DEGREE { + /** + * 1: The degree of blurring applied to the custom background image is low. + * The user can almost see the background clearly. + */ + BLUR_DEGREE_LOW = 1, + /** + * 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_MEDIUM, + /** + * (Default) The degree of blurring applied to the custom background image is high. + * The user can barely see any distinguishing features in the background. + */ + BLUR_DEGREE_HIGH, + }; + + /** The type of the custom background image. See #BACKGROUND_SOURCE_TYPE. + */ + BACKGROUND_SOURCE_TYPE background_source_type; + + /** + * 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`. + */ + unsigned int color; + + /** + * 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`. + */ + const char* source; + + /** + * The degree of blurring applied to the custom background image. See #BACKGROUND_BLUR_DEGREE. + * + * @note This parameter takes effect only when the type of the custom background image is `BACKGROUND_BLUR`. + * + * @since v3.5.1 + */ + BACKGROUND_BLUR_DEGREE blur_degree; - BeautyOptions() : lighteningLevel(0), smoothnessLevel(0), rednessLevel(0), lighteningContrastLevel(LIGHTENING_CONTRAST_NORMAL) {} + VirtualBackgroundSource() : color(0xffffff), source(NULL), background_source_type(BACKGROUND_COLOR), blur_degree(BLUR_DEGREE_HIGH) {} }; /** @@ -3143,6 +3844,46 @@ struct UserInfo { char userAccount[MAX_USER_ACCOUNT_LENGTH]; UserInfo() : uid(0) { userAccount[0] = '\0'; } }; +/** + * The configuration of the audio and video call loop test. + * + * @since v3.5.2 + */ +struct EchoTestConfiguration { + /** + * The view used to render the local user's video. This parameter is only applicable to scenarios testing video + * devices, that is, when `enableVideo` is `true`. + */ + view_t view; + /** + * Whether to enable the audio device for the call loop test: + * - true: (Default) Enables the audio device. To test the audio device, set this parameter as `true`. + * - false: Disables the audio device. + */ + bool enableAudio; + /** + * Whether to enable the video device for the call loop test: + * - true: (Default) Enables the video device. To test the video device, set this parameter as `true`. + * - false: Disables the video device. + */ + bool enableVideo; + /** + * The token used to secure the audio and video call loop test. If you do not enable App Certificate in Agora + * Console, you do not need to pass a value in this parameter; if you have enabled App Certificate in Agora Console, + * you must pass a token in this parameter, the `uid` used when you generate the token must be 0xFFFFFFFF, and the + * channel name used must be the channel name that identifies each audio and video call loop tested. For server-side + * token generation, see [Authenticate Your Users with Tokens](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=All%20Platforms). + */ + const char* token; + /** + * The channel name that identifies each audio and video call loop. To ensure proper loop test functionality, the + * channel name passed in to identify each loop test cannot be the same when users of the same project (App ID) + * perform audio and video call loop tests on different devices. + */ + const char* channelId; + EchoTestConfiguration() : view(NULL), enableAudio(true), enableVideo(true), token(NULL), channelId(NULL) {} + EchoTestConfiguration(view_t v, bool ea, bool ev, const char* t, const char* c) : view(v), enableAudio(ea), enableVideo(ev), token(t), channelId(c) {} +}; /** * Regions for connetion. @@ -3190,6 +3931,71 @@ enum ENCRYPTION_CONFIG { */ ENCRYPTION_FORCE_DISABLE_PACKET = (1 << 1) }; +/// @cond +typedef int ContentInspectType; +/** + * (Default) content inspect type invalid + */ +const ContentInspectType kContentInspectInvalid = 0; +/** + * Content inspect type moderation + */ +const ContentInspectType kContentInspectModeration = 1; +/** + * Content inspect type supervise + */ +const ContentInspectType kContentInspectSupervise = 2; + +enum MAX_CONTENT_INSPECT_MODULE_TYPE { + /** The maximum count of content inspect feature type is 32. + */ + MAX_CONTENT_INSPECT_MODULE_COUNT = 32 +}; +/// @endcond +/// @cond +/** Definition of ContentInspectModule. + */ +struct ContentInspectModule { + /** + * The content inspect module type. + * the module type can be 0 to 31. + * kContentInspectInvalid(0) + * kContentInspectModeration(1) + * kContentInspectSupervise(2) + */ + ContentInspectType type; + /**The content inspect frequency, default is 0 second. + * the frequency <= 0 is invalid. + */ + int interval; + /**The content inspect default value. + */ + ContentInspectModule() { + type = kContentInspectInvalid; + interval = 0; + } +}; +/// @endcond +/// @cond +/** Definition of ContentInspectConfig. + */ +struct ContentInspectConfig { + /** The extra information, max length of extraInfo is 1024. + * The extra information will send to server with content(image). + */ + const char* extraInfo; + /**The content inspect modules, max length of modules is 32. + * the content(snapshot of send video stream, image) can be used to max of 32 types functions. + */ + ContentInspectModule modules[MAX_CONTENT_INSPECT_MODULE_COUNT]; + /**The content inspect module count. + */ + int moduleCount; + + ContentInspectConfig() : extraInfo(NULL), moduleCount(0) {} +}; +/// @endcond + /** Definition of IPacketObserver. */ class IPacketObserver { @@ -3198,7 +4004,9 @@ class IPacketObserver { */ struct Packet { /** Buffer address of the sent or received data. - * @note Agora recommends that the value of buffer is more than 2048 bytes, otherwise, you may meet undefined behaviors such as a crash. + * + * @note Agora recommends that the value of buffer is more than 2048 bytes, + * otherwise, you may meet undefined behaviors such as a crash. */ const unsigned char* buffer; /** Buffer size of the sent or received data. @@ -3239,7 +4047,6 @@ class IPacketObserver { virtual bool onReceiveVideoPacket(Packet& packet) = 0; }; -#if defined(_WIN32) /** The capture type of the custom video source. */ enum VIDEO_CAPTURE_TYPE { @@ -3349,7 +4156,158 @@ class IVideoSource { */ virtual VideoContentHint getVideoContentHint() = 0; }; + +#if (defined(__APPLE__) && TARGET_OS_MAC && !TARGET_OS_IPHONE) +/** + * The target size of the thumbnail or icon. (macOS only) + * + * @since v3.5.2 + */ +struct SIZE { + /** The target width (px) of the thumbnail or icon. The default value is 0. + */ + int width; + /** The target height (px) of the thumbnail or icon. The default value is 0. + */ + int height; + + SIZE() : width(0), height(0) {} + SIZE(int w, int h) : width(w), height(h) {} +}; #endif +/** + * The image content of the thumbnail or icon. + * + * @since v3.5.2 + * + * @note The default image is in the RGBA format. If you need to use another format, you need to convert the image on + * your own. + */ +struct ThumbImageBuffer { + /** + * The buffer of the thumbnail or icon. + */ + const char* buffer; + /** + * The buffer length (bytes) of the thumbnail or icon. + */ + unsigned int length; + /** + * The actual width (px) of the thumbnail or icon. + */ + unsigned int width; + /** + * The actual height (px) of the thumbnail or icon. + */ + unsigned int height; + ThumbImageBuffer() : buffer(nullptr), length(0), width(0), height(0) {} +}; +/** + * The type of the shared target. + * + * @since v3.5.2 + */ +enum ScreenCaptureSourceType { + /** + * -1: Unknown type. + */ + ScreenCaptureSourceType_Unknown = -1, + /** + * 0: The shared target is a window. + */ + ScreenCaptureSourceType_Window = 0, + /** + * 1: The shared target is a screen of a particular monitor. + */ + ScreenCaptureSourceType_Screen = 1, + /** + * 2: Reserved parameter. + */ + ScreenCaptureSourceType_Custom = 2, +}; +/** + * The information about the specified shareable window or screen. + * + * @since v3.5.2 + */ +struct ScreenCaptureSourceInfo { + /** + * The type of the shared target. See \ref agora::rtc::ScreenCaptureSourceType "ScreenCaptureSourceType". + */ + ScreenCaptureSourceType type; + /** + * The window ID for a window or the display ID for a screen. + */ + view_t sourceId; + /** + * The name of the window or screen. UTF-8 encoding. + */ + const char* sourceName; + /** + * The image content of the thumbnail. See ThumbImageBuffer. + */ + ThumbImageBuffer thumbImage; + /** + * The image content of the icon. See ThumbImageBuffer. + */ + ThumbImageBuffer iconImage; + /** + * The process to which the window belongs. UTF-8 encoding. + */ + const char* processPath; + /** + * The title of the window. UTF-8 encoding. + */ + const char* sourceTitle; + /** + * Determines whether the screen is the primary display: + * - true: The screen is the primary display. + * - false: The screen is not the primary display. + */ + bool primaryMonitor; + ScreenCaptureSourceInfo() : type(ScreenCaptureSourceType_Unknown), sourceId(nullptr), sourceName(nullptr), processPath(nullptr), sourceTitle(nullptr), primaryMonitor(false) {} +}; +/** + * The IScreenCaptureSourceList class. + * + * @since v3.5.2 + */ +class IScreenCaptureSourceList { + protected: + virtual ~IScreenCaptureSourceList(){}; + + public: + /** + * Gets the number of shareable windows and screens. + * + * @since v3.5.2 + * + * @return The number of shareable windows and screens. + */ + virtual unsigned int getCount() = 0; + /** + * Gets information about the specified shareable window or screen. + * + * @since v3.5.2 + * + * After you get IScreenCaptureSourceList, you can pass in the index value of the specified shareable window or + * screen to get information about that window or screen from ScreenCaptureSourceInfo. + * + * @param index The index of the specified shareable window or screen. The value range is [0,`getCount()`). + * + * @return ScreenCaptureSourceInfo + */ + virtual ScreenCaptureSourceInfo getSourceInfo(unsigned int index) = 0; + /** + * Releases IScreenCaptureSourceList. + * + * @since v3.5.2 + * + * After you get the list of shareable windows and screens, to avoid memory leaks, call `release` to release + * `IScreenCaptureSourceList` instead of deleting `IScreenCaptureSourceList` directly. + */ + virtual void release() = 0; +}; /** The SDK uses the IRtcEngineEventHandler interface class to send callbacks to the application. The application inherits the methods of this interface class to retrieve these callbacks. @@ -3421,7 +4379,7 @@ class IRtcEngineEventHandler { This callback notifies the application that a user leaves the channel when the application calls the \ref IRtcEngine::leaveChannel "leaveChannel" method. - The application retrieves information, such as the call duration and statistics. + The application gets information, such as the call duration and statistics. @param stats Pointer to the statistics of the call: RtcStats. */ @@ -3429,14 +4387,24 @@ class IRtcEngineEventHandler { /** Occurs when the user role switches in the interactive live streaming. For example, from a host to an audience or vice versa. - This callback notifies the application of a user role switch when the application calls the \ref IRtcEngine::setClientRole "setClientRole" method. + This callback notifies the application of a user role switch when the application calls the \ref IRtcEngine::setClientRole "setClientRole" method, and successfully changed role. - The SDK triggers this callback when the local user switches the user role by calling the \ref agora::rtc::IRtcEngine::setClientRole "setClientRole" method after joining the channel. + The SDK triggers this callback when the local user switches the user role by calling the \ref agora::rtc::IRtcEngine::setClientRole "setClientRole" method after joining the channel, and successfully changed role. @param oldRole Role that the user switches from: #CLIENT_ROLE_TYPE. @param newRole Role that the user switches to: #CLIENT_ROLE_TYPE. */ virtual void onClientRoleChanged(CLIENT_ROLE_TYPE oldRole, CLIENT_ROLE_TYPE newRole) {} + /** Occurs when the user role switches in the interactive live streaming. For example, from a host to an audience or vice versa. + + This callback notifies the application of a user role switch when the application calls the \ref IRtcEngine::setClientRole "setClientRole" method, and failed to change role. + + The SDK triggers this callback when the local user switches the user role by calling the \ref agora::rtc::IRtcEngine::setClientRole "setClientRole" method after joining the channel, and failed to change role. + @param reason The reason of changing client role failed. See #CLIENT_ROLE_CHANGE_FAILED_REASON. + @param currentRole Current Role that the user holds: #CLIENT_ROLE_TYPE. + */ + virtual void onClientRoleChangeFailed(CLIENT_ROLE_CHANGE_FAILED_REASON reason, CLIENT_ROLE_TYPE currentRole) {} + /** Occurs when a remote user (`COMMUNICATION`)/ host (`LIVE_BROADCASTING`) joins the channel. - `COMMUNICATION` profile: This callback notifies the application that another user joins the channel. If other users are already in the channel, the SDK also reports to the application on the existing users. @@ -3476,6 +4444,21 @@ class IRtcEngineEventHandler { (void)reason; } + /** Occurs when join success after calling \ref IRtcEngine::setLocalAccessPoint "setLocalAccessPoint" or \ref IRtcEngine::setCloudProxy "setCloudProxy" + @param channel Channel name. + @param uid User ID of the user joining the channel. + @param proxyType type of proxy agora sdk connected, proxyType will be NONE_PROXY_TYPE if not connected to proxy(fallback). + @param localProxyIp local proxy ip. if not join local proxy, it will be "". + @param elapsed Time elapsed (ms) from the user calling the \ref IRtcEngine::joinChannel "joinChannel" method until the SDK triggers this callback. + */ + virtual void onProxyConnected(const char* channel, uid_t uid, PROXY_TYPE proxyType, const char* localProxyIp, int elapsed) { + (void)channel; + (void)uid; + (void)proxyType; + (void)localProxyIp; + (void)elapsed; + } + /** Reports the last mile network quality of the local user once every two seconds before the user joins the channel. Last mile refers to the connection between the local device and Agora's edge server. After the application calls the \ref IRtcEngine::enableLastmileTest "enableLastmileTest" method, this callback reports once every two seconds the uplink and downlink last mile network conditions of the local user before the user joins the channel. @@ -3556,7 +4539,7 @@ class IRtcEngineEventHandler { The user becomes offline if the token used in the \ref IRtcEngine::joinChannel "joinChannel" method expires. The SDK triggers this callback 30 seconds before the token expires to remind the application to get a new token. Upon receiving this callback, generate a new token on the server and call the \ref IRtcEngine::renewToken "renewToken" method to pass the new token to the SDK. - @param token Pointer to the token that expires in 30 seconds. + @param token The token that expires in 30 seconds. */ virtual void onTokenPrivilegeWillExpire(const char* token) { (void)token; } @@ -3587,12 +4570,16 @@ class IRtcEngineEventHandler { virtual void onRtcStats(const RtcStats& stats) { (void)stats; } /** Reports the last mile network quality of each user in the channel once every two seconds. - - Last mile refers to the connection between the local device and Agora's edge server. This callback reports once every two seconds the last mile network conditions of each user in the channel. If a channel includes multiple users, the SDK triggers this callback as many times. - - @param uid User ID. The network quality of the user with this @p uid is reported. If @p uid is 0, the local network quality is reported. - @param txQuality Uplink transmission quality rating of the user in terms of the transmission bitrate, packet loss rate, average RTT (Round-Trip Time), and jitter of the uplink network. @p txQuality is a quality rating helping you understand how well the current uplink network conditions can support the selected VideoEncoderConfiguration. 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 may be inadequate for resolutions higher than 1280 * 720. See #QUALITY_TYPE. - @param rxQuality Downlink network quality rating of the user in terms of the packet loss rate, average RTT, and jitter of the downlink network. See #QUALITY_TYPE. + * + * Last mile refers to the connection between the local device and Agora's edge server. This callback + * reports once every two seconds the last mile network conditions of each user in the channel. If a channel includes + * multiple users, the SDK triggers this callback as many times. + * + * @note `txQuality` is `UNKNOWN` when the user is not sending a stream; `rxQuality` is `UNKNOWN` when the user is not receiving a stream. + * + * @param uid User ID. The network quality of the user with this @p uid is reported. If @p uid is 0, the local network quality is reported. + * @param txQuality Uplink transmission quality rating of the user in terms of the transmission bitrate, packet loss rate, average RTT (Round-Trip Time), and jitter of the uplink network. @p txQuality is a quality rating helping you understand how well the current uplink network conditions can support the selected VideoEncoderConfiguration. 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 may be inadequate for resolutions higher than 1280 * 720. See #QUALITY_TYPE. + * @param rxQuality Downlink network quality rating of the user in terms of the packet loss rate, average RTT, and jitter of the downlink network. See #QUALITY_TYPE. */ virtual void onNetworkQuality(uid_t uid, int txQuality, int rxQuality) { (void)uid; @@ -3666,17 +4653,18 @@ class IRtcEngineEventHandler { } /** Occurs when the remote audio state changes. - - This callback indicates the state change of the remote audio stream. - @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. - - @param uid ID of the remote user whose audio state changes. - @param state State of the remote audio. See #REMOTE_AUDIO_STATE. - @param reason The reason of the remote audio state change. - See #REMOTE_AUDIO_STATE_REASON. - @param elapsed Time elapsed (ms) from the local user calling the - \ref IRtcEngine::joinChannel "joinChannel" method until the SDK - triggers this callback. + * + * This callback indicates the state change of the remote audio stream. + * + * @note This callback can be inaccurate when the number of users (in the `COMMUNICATION` profile) + * or hosts (in the `LIVE_BROADCASTING` profile) in a channel exceeds 17. + * + * @param uid ID of the remote user whose audio state changes. + * @param state State of the remote audio. See #REMOTE_AUDIO_STATE. + * @param reason The reason of the remote audio state change. See #REMOTE_AUDIO_STATE_REASON. + * @param elapsed Time elapsed (ms) from the local user calling the + * \ref IRtcEngine::joinChannel "joinChannel" method until the SDK + * triggers this callback. */ virtual void onRemoteAudioStateChanged(uid_t uid, REMOTE_AUDIO_STATE state, REMOTE_AUDIO_STATE_REASON reason, int elapsed) { (void)uid; @@ -3790,7 +4778,7 @@ class IRtcEngineEventHandler { * - In the remote users' callback, totalVolume is the sum of the volume of all remote users (up to three) whose * instantaneous volumes are the highest. * - * If the user calls \ref agora::rtc::IRtcEngine::startAudioMixing "startAudioMixing", `totalVolume` is the sum of + * If the user calls \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing", `totalVolume` is the sum of * the voice volume and audio-mixing volume. */ virtual void onAudioVolumeIndication(const AudioVolumeInfo* speakers, unsigned int speakerNumber, int totalVolume) { @@ -3799,7 +4787,13 @@ class IRtcEngineEventHandler { (void)totalVolume; } - /** Occurs when the most active speaker is detected. + /** add for audio device test:report playback volume and recording volume + **/ + virtual void onAudioDeviceTestVolumeIndication(AudioDeviceTestVolumeType volumeType, int volume) { + (void)volumeType; + (void)volume; + } + /** Occurs when the most active remote speaker is detected. After a successful call of \ref IRtcEngine::enableAudioVolumeIndication(int, int, bool) "enableAudioVolumeIndication", the SDK continuously detects which remote user has the loudest volume. During the current period, the remote user, @@ -3809,7 +4803,7 @@ class IRtcEngineEventHandler { - If the most active speaker is always the same user, the SDK triggers this 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. - @param uid The user ID of the most active speaker. + @param uid The user ID of the most active remote speaker. */ virtual void onActiveSpeaker(uid_t uid) { (void)uid; } @@ -3849,14 +4843,6 @@ class IRtcEngineEventHandler { virtual void onFirstLocalVideoFramePublished(int elapsed) { (void)elapsed; } /** Occurs when the first remote video frame is received and decoded. - * - * @deprecated v2.9.0 - * - * This callback is deprecated and replaced by the - * \ref onRemoteVideoStateChanged() "onRemoteVideoStateChanged" callback - * with the following parameters: - * - #REMOTE_VIDEO_STATE_STARTING (1) - * - #REMOTE_VIDEO_STATE_DECODING (2) * * This callback is triggered in either of the following scenarios: * @@ -3881,7 +4867,7 @@ class IRtcEngineEventHandler { * \ref IRtcEngine::joinChannel "joinChannel" method until the SDK * triggers this callback. */ - virtual void onFirstRemoteVideoDecoded(uid_t uid, int width, int height, int elapsed) { + virtual void onFirstRemoteVideoDecoded(uid_t uid, int width, int height, int elapsed) AGORA_DEPRECATED_ATTRIBUTE { (void)uid; (void)width; (void)height; @@ -3889,7 +4875,7 @@ class IRtcEngineEventHandler { } /** Occurs when the first remote video frame is rendered. - The SDK triggers this callback when the first frame of the remote video is displayed in the user's video window. The application can retrieve the time elapsed from a user joining the channel until the first video frame is displayed. + The SDK triggers this callback when the first frame of the remote video is displayed in the user's video window. The application can get the time elapsed from a user joining the channel until the first video frame is displayed. @param uid User ID of the remote user sending the video stream. @param width Width (px) of the video frame. @@ -3903,46 +4889,38 @@ class IRtcEngineEventHandler { (void)elapsed; } - /** @deprecated This method is deprecated from v3.0.0, use the \ref agora::rtc::IRtcEngineEventHandler::onRemoteAudioStateChanged "onRemoteAudioStateChanged" callback instead. - - Occurs when a remote user's audio stream playback pauses/resumes. - - The SDK triggers this callback when the remote user stops or resumes sending the audio stream by calling the \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" 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. - - @param uid User ID of the remote user. - @param muted Whether the remote user's audio stream is muted/unmuted: - - true: Muted. - - false: Unmuted. + /** Occurs when a remote user's audio stream playback pauses/resumes. + * + * The SDK triggers this callback when the remote user stops or resumes sending the audio stream by calling the \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" method. + * + * @note This callback can be inaccurate when the number of users (in the `COMMUNICATION` profile) + * or hosts (in the `LIVE_BROADCASTING` profile) in a channel exceeds 17. + * + * @param uid User ID of the remote user. + * @param muted Whether the remote user's audio stream is muted/unmuted: + * - true: Muted. + * - false: Unmuted. */ virtual void onUserMuteAudio(uid_t uid, bool muted) { (void)uid; (void)muted; } - /** Occurs when a remote user's video stream playback pauses/resumes. - * - * You can also use the - * \ref onRemoteVideoStateChanged() "onRemoteVideoStateChanged" callback - * with the following parameters: - * - #REMOTE_VIDEO_STATE_STOPPED (0) and - * #REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED (5). - * - #REMOTE_VIDEO_STATE_DECODING (2) and - * #REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED (6). + /** + * Occurs when a remote user stops or resumes publishing the video stream. * - * The SDK triggers this callback when the remote user stops or resumes - * sending the video stream by calling the - * \ref agora::rtc::IRtcEngine::muteLocalVideoStream - * "muteLocalVideoStream" method. + * When a remote user calls \ref IRtcEngine::muteLocalVideoStream "muteLocalVideoStream" to + * stop or resume publishing the video stream, the SDK triggers this callback to report the + * state of the remote user's publishing stream to the local user. * - * @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. + * @note This callback can be inaccurate when the number of users + * (in the `COMMUNICATION` profile) or hosts (in the `LIVE_BROADCASTING` profile) in a + * channel exceeds 17. * - * @param uid User ID of the remote user. - * @param muted Whether the remote user's video stream playback is - * paused/resumed: - * - true: Paused. - * - false: Resumed. + * @param uid The user ID of the remote user. + * @param muted Whether the remote user stops publishing the video stream: + * - true: Stop publishing the video stream. + * - false: Publish the video stream. */ virtual void onUserMuteVideo(uid_t uid, bool muted) { (void)uid; @@ -3952,16 +4930,6 @@ class IRtcEngineEventHandler { /** Occurs when a specific remote user enables/disables the video * module. * - * @deprecated v2.9.0 - * - * This callback is deprecated and replaced by the - * \ref onRemoteVideoStateChanged() "onRemoteVideoStateChanged" callback - * with the following parameters: - * - #REMOTE_VIDEO_STATE_STOPPED (0) and - * #REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED (5). - * - #REMOTE_VIDEO_STATE_DECODING (2) and - * #REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED (6). - * * Once the video module is disabled, the remote user can only use a * voice call. The remote user cannot send or receive any video from * other users. @@ -3987,12 +4955,16 @@ class IRtcEngineEventHandler { } /** Occurs when the audio device state changes. - - This callback notifies the application that the system's audio device state is changed. For example, a headset is unplugged from the device. - - @param deviceId Pointer to the device ID. - @param deviceType Device type: #MEDIA_DEVICE_TYPE. - @param deviceState Device state: #MEDIA_DEVICE_STATE_TYPE. + * + * This callback notifies the application that the system's audio device state is changed. For example, a headset is unplugged from the device. + * + * @param deviceId Pointer to the device ID. + * @param deviceType Device type: #MEDIA_DEVICE_TYPE. + * @param deviceState The state of the device: + * - On macOS: + * - 0: The device is ready for use. + * - 8: The device is not connected. + * - On Windows: #MEDIA_DEVICE_STATE_TYPE. */ virtual void onAudioDeviceStateChanged(const char* deviceId, int deviceType, int deviceState) { (void)deviceId; @@ -4096,33 +5068,46 @@ class IRtcEngineEventHandler { **DEPRECATED** use onAudioMixingStateChanged instead. - You can start an audio mixing file playback by calling the \ref IRtcEngine::startAudioMixing "startAudioMixing" method. The SDK triggers this callback when the audio mixing file playback finishes. + You can start an audio mixing file playback by calling the \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" method. The SDK triggers this callback when the audio mixing file playback finishes. If the *startAudioMixing* method call fails, an error code returns in the \ref IRtcEngineEventHandler::onError "onError" callback. */ virtual void onAudioMixingFinished() {} - /** Occurs when the state of the local user's audio mixing file changes. - - When you call the \ref IRtcEngine::startAudioMixing "startAudioMixing" method and the state of audio mixing file changes, the SDK triggers this callback. - - When the audio mixing file plays, pauses playing, or stops playing, this callback returns 710, 711, or 713 in @p state, and corresponding reason in @p reason. - - When exceptions occur during playback, this callback returns 714 in @p state and an error reason in @p reason. - - 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 AUDIO_MIXING_REASON_CAN_NOT_OPEN = 701. - - @param state The state code. See #AUDIO_MIXING_STATE_TYPE. - @param reason The reason code. See #AUDIO_MIXING_REASON_TYPE. + /** Occurs when the state of the local user's music file changes. + * + * @since v3.4.0 + * + * When the playback state of the local user's music file changes, the SDK triggers this callback and + * reports the current playback state and the reason for the change. + * + * @param state The current music file playback state. See #AUDIO_MIXING_STATE_TYPE. + * @param reason The reason for the change of the music file playback state. See #AUDIO_MIXING_REASON_TYPE. */ virtual void onAudioMixingStateChanged(AUDIO_MIXING_STATE_TYPE state, AUDIO_MIXING_REASON_TYPE reason) {} /** Occurs when a remote user starts audio mixing. - When a remote user calls \ref IRtcEngine::startAudioMixing "startAudioMixing" to play the background music, the SDK reports this callback. + When a remote user calls \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" to play the background music, the SDK reports this callback. */ virtual void onRemoteAudioMixingBegin() {} /** Occurs when a remote user finishes audio mixing. */ virtual void onRemoteAudioMixingEnd() {} + /** + * Reports the information of an audio file. + * + * @since v3.5.1 + * + * After successfully calling \ref IRtcEngine::getAudioFileInfo "getAudioFileInfo", the SDK triggers this + * callback to report the information of the audio file, such as the file path and duration. + * + * @param info The information of an audio file. See AudioFileInfo. + * @param error The information acquisition state. See #AUDIO_FILE_INFO_ERROR. + */ + virtual void onRequestAudioFileInfo(const AudioFileInfo& info, AUDIO_FILE_INFO_ERROR error) {} + /** Occurs when the local audio effect playback finishes. The SDK triggers this callback when the local audio effect file playback finishes. @@ -4130,9 +5115,11 @@ class IRtcEngineEventHandler { @param soundId ID of the local audio effect. Each local audio effect has a unique ID. */ virtual void onAudioEffectFinished(int soundId) {} + /// @cond /** Occurs when AirPlay is connected. */ virtual void onAirPlayConnected() {} + /// @endcond /** Occurs when the SDK decodes the first remote audio frame for playback. @@ -4153,18 +5140,22 @@ class IRtcEngineEventHandler { @param uid User ID of the remote user sending the audio stream. @param elapsed Time elapsed (ms) from the local user calling the \ref IRtcEngine::joinChannel "joinChannel" method until the SDK triggers this callback. */ - virtual void onFirstRemoteAudioDecoded(uid_t uid, int elapsed) { + virtual void onFirstRemoteAudioDecoded(uid_t uid, int elapsed) AGORA_DEPRECATED_ATTRIBUTE { (void)uid; (void)elapsed; } /** Occurs when the video device state changes. - - @note On a Windows device with an external camera for video capturing, the video disables once the external camera is unplugged. - - @param deviceId Pointer to the device ID of the video device that changes state. - @param deviceType Device type: #MEDIA_DEVICE_TYPE. - @param deviceState Device state: #MEDIA_DEVICE_STATE_TYPE. + * + * @note On a Windows device with an external camera for video capturing, the video disables once the external camera is unplugged. + * + * @param deviceId Pointer to the device ID of the video device that changes state. + * @param deviceType Device type: #MEDIA_DEVICE_TYPE. + * @param deviceState The state of the device: + * - On macOS: + * - 0: The device is ready for use. + * - 8: The device is not connected. + * - On Windows: #MEDIA_DEVICE_STATE_TYPE. */ virtual void onVideoDeviceStateChanged(const char* deviceId, int deviceType, int deviceState) { (void)deviceId; @@ -4176,12 +5167,12 @@ class IRtcEngineEventHandler { * * 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(LOCAL_VIDEO_STREAM_STATE_FAILED，LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE)` callback in the following situations: + * The SDK triggers the `onLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_FAILED, LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE)` callback in the following situations: * - The application exits to the background, and the system recycles the camera. * - The camera starts normally, but the captured video is not output for four seconds. * * When the camera outputs the captured video frames, if all the video frames are the same for 15 consecutive frames, the SDK triggers the - * `onLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_CAPTURING，LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE)` callback. Note that the + * `onLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_CAPTURING, LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE)` callback. 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. * @@ -4209,15 +5200,16 @@ class IRtcEngineEventHandler { (void)rotation; } /** Occurs when the remote video state changes. - @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. - - @param uid ID of the remote user whose video state changes. - @param state State of the remote video. See #REMOTE_VIDEO_STATE. - @param reason The reason of the remote video state change. See - #REMOTE_VIDEO_STATE_REASON. - @param elapsed Time elapsed (ms) from the local user calling the - \ref agora::rtc::IRtcEngine::joinChannel "joinChannel" method until the - SDK triggers this callback. + * + * @note This callback can be inaccurate when the number of users (in the `COMMUNICATION` profile) + * or hosts (in the `LIVE_BROADCASTING` profile) in a channel exceeds 17. + * + * @param uid ID of the remote user whose video state changes. + * @param state State of the remote video. See #REMOTE_VIDEO_STATE. + * @param reason The reason of the remote video state change. See #REMOTE_VIDEO_STATE_REASON. + * @param elapsed Time elapsed (ms) from the local user calling the + * \ref agora::rtc::IRtcEngine::joinChannel "joinChannel" method until the + * SDK triggers this callback. */ virtual void onRemoteVideoStateChanged(uid_t uid, REMOTE_VIDEO_STATE state, REMOTE_VIDEO_STATE_REASON reason, int elapsed) { (void)uid; @@ -4229,16 +5221,6 @@ class IRtcEngineEventHandler { /** Occurs when a specified remote user enables/disables the local video * capturing function. * - * @deprecated v2.9.0 - * - * This callback is deprecated and replaced by the - * \ref onRemoteVideoStateChanged() "onRemoteVideoStateChanged" callback - * with the following parameters: - * - #REMOTE_VIDEO_STATE_STOPPED (0) and - * #REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED (5). - * - #REMOTE_VIDEO_STATE_DECODING (2) and - * #REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED (6). - * * This callback is only applicable to the scenario when the user only * wants to watch the remote video without sending any video stream to the * other user. @@ -4298,27 +5280,82 @@ The SDK triggers this callback when the local user fails to receive the stream m virtual void onMediaEngineLoadSuccess() {} /** Occurs when the media engine call starts.*/ virtual void onMediaEngineStartCallSuccess() {} - /// @cond - /** Reports whether the super-resolution algorithm is enabled. + + /** Reports whether the super resolution feature is successfully enabled. (beta feature) * - * @since v3.2.0 + * @since v3.5.1 * * After calling \ref IRtcEngine::enableRemoteSuperResolution "enableRemoteSuperResolution", the SDK triggers this - * callback to report whether the super-resolution algorithm is successfully enabled. If not successfully enabled, - * you can use reason for troubleshooting. + * callback to report whether super resolution is successfully enabled. If it is not successfully enabled, + * use `reason` for troubleshooting. + * + * @param uid The user ID of the remote user. + * @param enabled Whether super resolution is successfully enabled: + * - true: Super resolution is successfully enabled. + * - false: Super resolution is not successfully enabled. + * @param reason The reason why super resolution is not successfully enabled or the message + * that confirms success. See #SUPER_RESOLUTION_STATE_REASON. * - * @param uid The ID of the remote user. - * @param enabled Whether the super-resolution algorithm is successfully enabled: - * - true: The super-resolution algorithm is successfully enabled. - * - false: The super-resolution algorithm is not successfully enabled. - * @param reason The reason why the super-resolution algorithm is not successfully enabled. See #SUPER_RESOLUTION_STATE_REASON. */ virtual void onUserSuperResolutionEnabled(uid_t uid, bool enabled, SUPER_RESOLUTION_STATE_REASON reason) { (void)uid; (void)enabled; (void)reason; } + + /** + * Reports whether the virtual background is successfully enabled. (beta feature) + * + * @since v3.4.5 + * + * After you call \ref IRtcEngine::enableVirtualBackground "enableVirtualBackground", the SDK triggers this callback + * to report whether the virtual background is successfully enabled. + * + * @note If the background image customized in the virtual background is in PNG or JPG format, the triggering of this + * callback is delayed until the image is read. + * + * @param enabled Whether the virtual background is successfully enabled: + * - true: The virtual background is successfully enabled. + * - false: The virtual background is not successfully enabled. + * @param reason The reason why the virtual background is not successfully enabled or the message that confirms + * success. See #VIRTUAL_BACKGROUND_SOURCE_STATE_REASON. + */ + virtual void onVirtualBackgroundSourceEnabled(bool enabled, VIRTUAL_BACKGROUND_SOURCE_STATE_REASON reason) { + (void)enabled; + (void)reason; + } + /// @cond + /** Reports result of Content Inspect*/ + virtual void onContentInspectResult(CONTENT_INSPECT_RESULT result) { (void)result; } /// @endcond + /** + * Reports the result of taking a video snapshot. + * + * @since v3.5.2 + * + * After a successful \ref IRtcEngine::takeSnapshot "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. + * + * @param channel The channel name. + * @param uid The user ID of the user. A `uid` of 0 indicates the local user. + * @param filePath The local path of the snapshot. + * @param width The width (px) of the snapshot. + * @param height The height (px) of the snapshot. + * @param 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 \ref IRtcEngine::takeSnapshot "takeSnapshot" method call succeeds. + */ + 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; + } /** Occurs when the state of the media stream relay changes. * @@ -4342,7 +5379,7 @@ The SDK triggers this callback when the local user fails to receive the stream m @param elapsed Time elapsed (ms) from the local user calling \ref IRtcEngine::joinChannel "joinChannel" until the SDK triggers this callback. */ - virtual void onFirstLocalAudioFrame(int elapsed) { (void)elapsed; } + virtual void onFirstLocalAudioFrame(int elapsed) AGORA_DEPRECATED_ATTRIBUTE { (void)elapsed; } /** Occurs when the first audio frame is published. * @@ -4367,23 +5404,24 @@ The SDK triggers this callback when the local user fails to receive the stream m @param uid User ID of the remote user. @param elapsed Time elapsed (ms) from the remote user calling \ref IRtcEngine::joinChannel "joinChannel" until the SDK triggers this callback. */ - virtual void onFirstRemoteAudioFrame(uid_t uid, int elapsed) { + virtual void onFirstRemoteAudioFrame(uid_t uid, int elapsed) AGORA_DEPRECATED_ATTRIBUTE { (void)uid; (void)elapsed; } /** - Occurs when the state of the RTMP or RTMPS streaming changes. - - The SDK triggers this callback to report the result of the local user calling the \ref agora::rtc::IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" or \ref agora::rtc::IRtcEngine::removePublishStreamUrl "removePublishStreamUrl" method. - - 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 *errCode* parameter. - - @param url The CDN streaming URL. - @param state The RTMP or RTMPS streaming state. See: #RTMP_STREAM_PUBLISH_STATE. - @param errCode The detailed error information for streaming. See: #RTMP_STREAM_PUBLISH_ERROR. + * Occurs when the state of the RTMP or RTMPS streaming changes. + * + * When the CDN live streaming state changes, the SDK triggers this callback to report the current state and the reason + * why the state has changed. + * + * When exceptions occur, you can troubleshoot issues by referring to the detailed error descriptions in the *errCode* parameter. + * + * @param url The CDN streaming URL. + * @param state The RTMP or RTMPS streaming state. See: #RTMP_STREAM_PUBLISH_STATE. + * @param errCode The detailed error information for streaming. See: #RTMP_STREAM_PUBLISH_ERROR_TYPE. */ - virtual void onRtmpStreamingStateChanged(const char* url, RTMP_STREAM_PUBLISH_STATE state, RTMP_STREAM_PUBLISH_ERROR errCode) { + virtual void onRtmpStreamingStateChanged(const char* url, RTMP_STREAM_PUBLISH_STATE state, RTMP_STREAM_PUBLISH_ERROR_TYPE errCode) { (void)url; (void)state; (void)errCode; @@ -4412,7 +5450,6 @@ The SDK triggers this callback when the local user fails to receive the stream m - #ERR_INVALID_ARGUMENT (-2): Invalid argument used. If, for example, you did not call \ref agora::rtc::IRtcEngine::setLiveTranscoding "setLiveTranscoding" to configure LiveTranscoding before calling \ref agora::rtc::IRtcEngine::addPublishStreamUrl "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_RESOURCE_LIMITED (-22): The backend system does not have enough resources for the CDN live streaming. - #ERR_ENCRYPTED_STREAM_NOT_ALLOWED_PUBLISH (130): You cannot publish an encrypted stream. - #ERR_PUBLISH_STREAM_CDN_ERROR (151) - #ERR_PUBLISH_STREAM_NUM_REACH_LIMIT (152) @@ -4420,7 +5457,7 @@ The SDK triggers this callback when the local user fails to receive the stream m - #ERR_PUBLISH_STREAM_INTERNAL_SERVER_ERROR (154) - #ERR_PUBLISH_STREAM_FORMAT_NOT_SUPPORTED (156) */ - virtual void onStreamPublished(const char* url, int error) { + virtual void onStreamPublished(const char* url, int error) AGORA_DEPRECATED_ATTRIBUTE { (void)url; (void)error; } @@ -4432,7 +5469,7 @@ The SDK triggers this callback when the local user fails to receive the stream m @param url The CDN streaming URL. */ - virtual void onStreamUnpublished(const char* url) { (void)url; } + virtual void onStreamUnpublished(const char* url) AGORA_DEPRECATED_ATTRIBUTE { (void)url; } /** Occurs when the publisher's transcoding is updated. * * When the `LiveTranscoding` class in the \ref agora::rtc::IRtcEngine::setLiveTranscoding "setLiveTranscoding" method updates, the SDK triggers the `onTranscodingUpdated` callback to report the update information to the local host. @@ -4456,7 +5493,10 @@ The SDK triggers this callback when the local user fails to receive the stream m } /** Occurs when the local audio route changes. - @param routing The current audio routing. See: #AUDIO_ROUTE_TYPE. + * + * @note This callback applies to Android, iOS and macOS only. + * + * @param routing The current audio routing. See: #AUDIO_ROUTE_TYPE. */ virtual void onAudioRouteChanged(AUDIO_ROUTE_TYPE routing) { (void)routing; } @@ -4481,8 +5521,8 @@ The SDK triggers this callback when the local user fails to receive the stream m * "setRemoteSubscribeFallbackOption" and set * @p option as #STREAM_FALLBACK_OPTION_AUDIO_ONLY, the SDK triggers this * callback when the remote media stream falls back to audio-only mode due - * to poor uplink conditions, or when the remote media stream switches - * back to the video after the uplink network condition improves. + * to poor downlink conditions, or when the remote media stream switches + * back to the video after the downlink network condition improves. * * @note Once the remote media stream switches to the low stream due to * poor network conditions, you can monitor the stream switch between a @@ -4519,7 +5559,7 @@ The SDK triggers this callback when the local user fails to receive the stream m * @param rxKBitRate Received bitrate (Kbps) of the audio packet sent * from the remote user. */ - virtual void onRemoteAudioTransportStats(uid_t uid, unsigned short delay, unsigned short lost, unsigned short rxKBitRate) { + virtual void onRemoteAudioTransportStats(uid_t uid, unsigned short delay, unsigned short lost, unsigned short rxKBitRate) AGORA_DEPRECATED_ATTRIBUTE { (void)uid; (void)delay; (void)lost; @@ -4544,7 +5584,7 @@ The SDK triggers this callback when the local user fails to receive the stream m * @param rxKBitRate Received bitrate (Kbps) of the video packet sent * from the remote user. */ - virtual void onRemoteVideoTransportStats(uid_t uid, unsigned short delay, unsigned short lost, unsigned short rxKBitRate) { + virtual void onRemoteVideoTransportStats(uid_t uid, unsigned short delay, unsigned short lost, unsigned short rxKBitRate) AGORA_DEPRECATED_ATTRIBUTE { (void)uid; (void)delay; (void)lost; @@ -4569,7 +5609,7 @@ The SDK triggers this callback when the local user fails to receive the stream m * - true: Enabled. * - false: Disabled. */ - virtual void onMicrophoneEnabled(bool enabled) { (void)enabled; } + virtual void onMicrophoneEnabled(bool enabled) AGORA_DEPRECATED_ATTRIBUTE { (void)enabled; } /** Occurs when the connection state between the SDK and the server changes. @param state See #CONNECTION_STATE_TYPE. @@ -4580,6 +5620,27 @@ The SDK triggers this callback when the local user fails to receive the stream m (void)reason; } + /** Occurs when the WIFI message need be sent to the user. + + @param reason The reason of notifying the user of a message. + @param action Suggest an action for the user. + @param wlAccMsg The message content of notifying the user. + */ + virtual void onWlAccMessage(WLACC_MESSAGE_REASON reason, WLACC_SUGGEST_ACTION action, const char* wlAccMsg) { + (void)reason; + (void)action; + (void)wlAccMsg; + } + /** Occurs when SDK statistics wifi acceleration optimization effect. + + @param currentStats Instantaneous value of optimization effect. + @param averageStats Average value of cumulative optimization effect. + */ + virtual void onWlAccStats(WlAccStats currentStats, WlAccStats averageStats) { + (void)currentStats; + (void)averageStats; + } + /** Occurs when the local network type changes. When the network connection is interrupted, this callback indicates whether the interruption is caused by a network type change or poor network conditions. @@ -4601,13 +5662,14 @@ The SDK triggers this callback when the local user fails to receive the stream m 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 (`userInfo`), and triggers this callback on the local client. - @param uid The ID of the remote user. - @param info The `UserInfo` object that contains the user ID and user account of the remote user. - */ + @param uid The ID of the remote user. + @param info The `UserInfo` object that contains the user ID and user account of the remote user. + */ virtual void onUserInfoUpdated(uid_t uid, const UserInfo& info) { (void)uid; (void)info; } + /// @cond /** Reports the result of uploading the SDK log files. * * @since v3.3.0 @@ -4627,25 +5689,35 @@ The SDK triggers this callback when the local user fails to receive the stream m (void)success; (void)reason; } + +#ifdef _WIN32 + /** Occurs when screencapture fail to filter window + * + * + * @param ScreenCaptureInfo + */ + virtual void onScreenCaptureInfoUpdated(ScreenCaptureInfo& info) { (void)info; } +#endif + /// @endcond }; /** * Video device collection methods. - The IVideoDeviceCollection interface class retrieves the video device information. + The IVideoDeviceCollection interface class gets the video device information. */ class IVideoDeviceCollection { protected: virtual ~IVideoDeviceCollection() {} public: - /** Retrieves the total number of the indexed video devices in the system. + /** Gets the total number of the indexed video devices in the system. @return Total number of the indexed video devices: */ virtual int getCount() = 0; - /** Retrieves a specified piece of information about an indexed video device. + /** Gets a specified piece of information about an indexed video device. @param index The specified index of the video device that must be less than the return value of \ref IVideoDeviceCollection::getCount "getCount". @param deviceName Pointer to the video device name. @@ -4670,9 +5742,10 @@ class IVideoDeviceCollection { virtual void release() = 0; }; +#if !defined(__ANDROID__) && !(defined(__APPLE__) && TARGET_OS_IPHONE) /** Video device management methods. - The IVideoDeviceManager interface class tests the video device interfaces. Instantiate an AVideoDeviceManager class to retrieve an IVideoDeviceManager interface. + The IVideoDeviceManager interface class tests the video device interfaces. Instantiate an AVideoDeviceManager class to get an IVideoDeviceManager interface. */ class IVideoDeviceManager { protected: @@ -4713,7 +5786,7 @@ class IVideoDeviceManager { /** Sets a device with the device ID. - @param deviceId Pointer to the video-capture device ID. Call the \ref IVideoDeviceManager::enumerateVideoDevices "enumerateVideoDevices" method to retrieve it. + @param deviceId Pointer to the video-capture device ID. Call the \ref IVideoDeviceManager::enumerateVideoDevices "enumerateVideoDevices" method to get it. @note Plugging or unplugging the device does not change the device ID. @@ -4723,7 +5796,7 @@ class IVideoDeviceManager { */ virtual int setDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0; - /** Retrieves the video-capture device that is in use. + /** Gets the video-capture device that is in use. @param deviceId Pointer to the video-capture device ID. @return @@ -4739,14 +5812,14 @@ class IVideoDeviceManager { /** Audio device collection methods. -The IAudioDeviceCollection interface class retrieves device-related information. +The IAudioDeviceCollection interface class gets device-related information. */ class IAudioDeviceCollection { protected: virtual ~IAudioDeviceCollection() {} public: - /** Retrieves the total number of audio playback or audio capturing devices. + /** Gets the total number of audio playback or audio capturing devices. @note You must first call the \ref IAudioDeviceManager::enumeratePlaybackDevices "enumeratePlaybackDevices" or \ref IAudioDeviceManager::enumerateRecordingDevices "enumerateRecordingDevices" method before calling this method to return the number of audio playback or audio capturing devices. @@ -4754,7 +5827,7 @@ class IAudioDeviceCollection { */ virtual int getCount() = 0; - /** Retrieves a specified piece of information about an indexed audio device. + /** Gets a specified piece of information about an indexed audio device. @param index The specified index that must be less than the return value of \ref IAudioDeviceCollection::getCount "getCount". @param deviceName Pointer to the audio device name. @@ -4774,6 +5847,20 @@ class IAudioDeviceCollection { */ virtual int setDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0; + /** + * Gets the default audio device of the system. + * + * @since v3.6.0 + * + * @param deviceName The name of the system default audio device. + * @param deviceId The device ID of the the system default audio device. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int getDefaultDevice(char deviceName[MAX_DEVICE_ID_LENGTH], char deviceId[MAX_DEVICE_ID_LENGTH]) = 0; + /** Sets the volume of the application. @param volume Application volume. The value ranges between 0 (lowest volume) and 255 (highest volume). @@ -4783,7 +5870,7 @@ class IAudioDeviceCollection { */ virtual int setApplicationVolume(int volume) = 0; - /** Retrieves the volume of the application. + /** Gets the volume of the application. @param volume Pointer to the application volume. The volume value ranges between 0 (lowest volume) and 255 (highest volume). @@ -4822,7 +5909,7 @@ class IAudioDeviceCollection { }; /** Audio device management methods. - The IAudioDeviceManager interface class allows for audio device interface testing. Instantiate an AAudioDeviceManager class to retrieve the IAudioDeviceManager interface. + The IAudioDeviceManager interface class allows for audio device interface testing. Instantiate an AAudioDeviceManager class to get the IAudioDeviceManager interface. */ class IAudioDeviceManager { protected: @@ -4877,6 +5964,36 @@ class IAudioDeviceManager { */ virtual int setRecordingDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0; + /** + * Sets the audio playback device used by the SDK to follow the system default audio playback device. + * + * @since v3.6.0 + * + * @param enable Whether to follow the system default audio playback device: + * - true: Follow. The SDK immediately switches the audio playback device when the system default audio playback device changes. + * - false: Do not follow. The SDK switches the audio playback device to the system default audio playback device only when the currently used audio playback device is disconnected. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int followSystemPlaybackDevice(bool enable) = 0; + + /** + * Sets the audio recording device used by the SDK to follow the system default audio recording device. + * + * @since v3.6.0 + * + * @param enable Whether to follow the system default audio recording device: + * - true: Follow. The SDK immediately switches the audio recording device when the system default audio recording device changes. + * - false: Do not follow. The SDK switches the audio recording device to the system default audio recording device only when the currently used audio recording device is disconnected. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int followSystemRecordingDevice(bool enable) = 0; + /** Starts the audio playback device test. * * This method tests if the audio playback device works properly. Once a user starts the test, the SDK plays an @@ -4919,7 +6036,7 @@ class IAudioDeviceManager { */ virtual int setPlaybackDeviceVolume(int volume) = 0; - /** Retrieves the volume of the audio playback device. + /** Gets the volume of the audio playback device. @param volume Pointer to the audio playback device volume. The volume value ranges between 0 (lowest volume) and 255 (highest volume). @return @@ -4939,7 +6056,7 @@ class IAudioDeviceManager { */ virtual int setRecordingDeviceVolume(int volume) = 0; - /** Retrieves the volume of the microphone. + /** Gets the volume of the microphone. @param volume Pointer to the microphone volume. The volume value ranges between 0 (lowest volume) and 255 (highest volume). @return @@ -4959,7 +6076,7 @@ class IAudioDeviceManager { - < 0: Failure. */ virtual int setPlaybackDeviceMute(bool mute) = 0; - /** Retrieves the mute status of the audio playback device. + /** Gets the mute status of the audio playback device. @param mute Pointer to whether the audio playback device is muted/unmuted. - true: Muted. @@ -4982,7 +6099,7 @@ class IAudioDeviceManager { */ virtual int setRecordingDeviceMute(bool mute) = 0; - /** Retrieves the microphone's mute status. + /** Gets the microphone's mute status. @param mute Pointer to whether the microphone is muted/unmuted. - true: Muted. @@ -5026,7 +6143,7 @@ class IAudioDeviceManager { */ virtual int stopRecordingDeviceTest() = 0; - /** Retrieves the audio playback device associated with the device ID. + /** Gets the audio playback device associated with the device ID. @param deviceId Pointer to the ID of the audio playback device. @return @@ -5035,7 +6152,7 @@ class IAudioDeviceManager { */ virtual int getPlaybackDevice(char deviceId[MAX_DEVICE_ID_LENGTH]) = 0; - /** Retrieves the audio playback device information associated with the device ID and device name. + /** Gets the audio playback device information associated with the device ID and device name. @param deviceId Pointer to the device ID of the audio playback device. @param deviceName Pointer to the device name of the audio playback device. @@ -5045,7 +6162,7 @@ class IAudioDeviceManager { */ virtual int getPlaybackDeviceInfo(char deviceId[MAX_DEVICE_ID_LENGTH], char deviceName[MAX_DEVICE_ID_LENGTH]) = 0; - /** Retrieves the audio capturing device associated with the device ID. + /** Gets the audio capturing device associated with the device ID. @param deviceId Pointer to the device ID of the audio capturing device. @return @@ -5054,7 +6171,7 @@ class IAudioDeviceManager { */ virtual int getRecordingDevice(char deviceId[MAX_DEVICE_ID_LENGTH]) = 0; - /** Retrieves the audio capturing device information associated with the device ID and device name. + /** Gets the audio capturing device information associated with the device ID and device name. @param deviceId Pointer to the device ID of the audio capturing device. @param deviceName Pointer to the device name of the audio capturing device. @@ -5103,6 +6220,7 @@ class IAudioDeviceManager { */ virtual void release() = 0; }; +#endif /** The configuration of the log files. * @@ -5156,8 +6274,9 @@ struct RtcEngineContext { /** * The region for connection. This advanced feature applies to scenarios that have regional restrictions. * - * For the regions that Agora supports, see #AREA_CODE. After specifying the region, the SDK connects to the Agora servers within that region. + * For the regions that Agora supports, see #AREA_CODE. The area codes support bitwise operation. * + * After specifying the region, the SDK connects to the Agora servers within that region. */ unsigned int areaCode; /** The configuration of the log files that the SDK outputs. See LogConfig. @@ -5242,10 +6361,11 @@ class IMetadataObserver { virtual void onMetadataReceived(const Metadata& metadata) = 0; }; -/** Encryption mode. +/** Encryption mode. Agora recommends using either the `AES_128_GCM2` or `AES_256_GCM2` + * encryption mode, both of which support adding a salt and are more secure. */ enum ENCRYPTION_MODE { - /** 1: (Default) 128-bit AES encryption, XTS mode. + /** 1: 128-bit AES encryption, XTS mode. */ AES_128_XTS = 1, /** 2: 128-bit AES encryption, ECB mode. @@ -5254,9 +6374,11 @@ enum ENCRYPTION_MODE { /** 3: 256-bit AES encryption, XTS mode. */ AES_256_XTS = 3, + /// @cond /** 4: 128-bit SM4 encryption, ECB mode. */ SM4_128_ECB = 4, + /// @endcond /** 5: 128-bit AES encryption, GCM mode. * * @since v3.3.1 @@ -5267,6 +6389,18 @@ enum ENCRYPTION_MODE { * @since v3.3.1 */ AES_256_GCM = 6, + /** 7: (Default) 128-bit AES encryption, GCM mode. Compared to `AES_128_GCM` encryption mode, + * `AES_128_GCM2` encryption mode is more secure and requires you to set the salt (`encryptionKdfSalt`). + * + * @since v3.4.5 + */ + AES_128_GCM2 = 7, + /** 8: 256-bit AES encryption, GCM mode. Compared to `AES_256_GCM` encryption mode, + * `AES_256_GCM2` encryption mode is more secure and requires you to set the salt (`encryptionKdfSalt`). + * + * @since v3.4.5 + */ + AES_256_GCM2 = 8, /** Enumerator boundary. */ MODE_END, @@ -5275,19 +6409,30 @@ enum ENCRYPTION_MODE { /** Configurations of built-in encryption schemas. */ struct EncryptionConfig { /** - * Encryption mode. The default encryption mode is `AES_128_XTS`. See #ENCRYPTION_MODE. + * Encryption mode. The default encryption mode is `AES_128_GCM2`. See #ENCRYPTION_MODE. */ ENCRYPTION_MODE encryptionMode; /** - * Encryption key in string type. + * Encryption key in string type with unlimited length. Agora recommends using a 32-byte key. * * @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 #ERR_INVALID_ARGUMENT (-2). */ const char* encryptionKey; + /** + * The salt with the length of 32 bytes. Agora recommends using OpenSSL to generate the salt on your server. + * For details, see *Media Stream Encryption*. + * + * @note This parameter is only valid when you set the encryption mode as `AES_128_GCM2` or `AES_256_GCM2`. + * In this case, ensure that this parameter is not `0`. + * + * @since v3.4.5 + */ + uint8_t encryptionKdfSalt[32]; EncryptionConfig() { - encryptionMode = AES_128_XTS; + encryptionMode = AES_128_GCM2; encryptionKey = nullptr; + memset(encryptionKdfSalt, 0, sizeof(encryptionKdfSalt)); } /// @cond @@ -5305,10 +6450,14 @@ struct EncryptionConfig { 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-xts"; + return "aes-128-gcm-2"; } - return "aes-128-xts"; + return "aes-128-gcm-2"; } /// @endcond }; @@ -5332,11 +6481,143 @@ struct ChannelMediaOptions { you can call the `muteAllRemoteVideoStreams` method to set whether to subscribe to video streams in the channel. */ bool autoSubscribeVideo; - ChannelMediaOptions() : autoSubscribeAudio(true), autoSubscribeVideo(true) {} + /** Determines whether to publish the local audio stream when the user joins a channel: + * - true: (Default) Publish. + * - false: Do not publish. + * + * This member serves a similar function to the `muteLocalAudioStream` method. After the user joins + * the channel, you can call the `muteLocalAudioStream` method to set whether to publish the + * local audio stream in the channel. + * + * @since v3.4.5 + */ + bool publishLocalAudio; + /** Determines whether to publish the local video stream when the user joins a channel: + * - true: (Default) Publish. + * - false: Do not publish. + * + * This member serves a similar function to the `muteLocalVideoStream` method. After the user joins + * the channel, you can call the `muteLocalVideoStream` method to set whether to publish the + * local video stream in the channel. + */ + bool publishLocalVideo; + ChannelMediaOptions() : autoSubscribeAudio(true), autoSubscribeVideo(true), publishLocalAudio(true), publishLocalVideo(true) {} }; - -/** IRtcEngine is the base interface class of the Agora SDK that provides the main Agora SDK methods invoked by your application. - +/** + * @since v3.5.0 + * + * The IVideoSink class, which can set up a custom video renderer. + * + * During a real-time audio and video interaction, the Agora SDK enables the default renderer to render local and + * remote video. The IVideoSink class can customize the video renderer. You can implement this interface first, and + * then customize the video renderer that you want by calling + * \ref IRtcEngine::setLocalVideoRenderer "setLocalVideoRenderer" or + * \ref IRtcEngine::setRemoteVideoRenderer "setRemoteVideoRenderer". + */ +class IVideoSink { + public: + /** + * Notification for initializing the custom video renderer. + * + * @since v3.5.0 + * + * The SDK triggers this callback to remind you to initialize the custom video renderer. + * After receiving this callback, you can do some preparation, and then use the return value to tell the SDK + * whether the custom video renderer is prepared. The SDK takes the corresponding behavior based on the return value. + * + * @return + * - true: The custom video renderer is initialized. The SDK is ready to send the video data to be rendered. + * - false: The custom video renderer is not ready or fails to initialize. The SDK reports the error. + */ + virtual bool onInitialize() = 0; + /** + * Notification for starting the custom video source. + * + * @since v3.5.0 + * + * The SDK triggers this callback to remind you to start the custom video source for capturing video. After receiving + * this callback, you can do some preparation, and then use the return value to tell the SDK whether the custom video + * renderer is started. The SDK takes the corresponding behavior based on the return value. + * + * @return + * - true: The custom video renderer is started. The SDK is ready to send the video data to be rendered to the custom video renderer for rendering. + * - false: The custom video renderer is not ready or fails to initialize. The SDK stops and reports the error. + */ + virtual bool onStart() = 0; + /** + * Notification for stopping rendering the video. + * + * @since v3.5.0 + * + * The SDK triggers this callback to remind you to stop rendering the video. This callback informs you that the SDK + * is about to stop sending video data to the custom video renderer. + */ + virtual void onStop() = 0; + /** + * Notification for disabling the custom video renderer. + * + * @since v3.5.0 + * + * The SDK triggers this callback to remind you to disable the custom video renderer. + */ + virtual void onDispose() = 0; + /** + * Gets the video frame type. + * + * @since v3.5.0 + * + * Before you initialize the custom video renderer, the SDK triggers this callback to query the data type of the + * video frame that you want to process. You must specify the data type of the video frame in the return value of + * this callback and then pass it to the SDK. + * + * @return \ref agora::media::ExternalVideoFrame::VIDEO_BUFFER_TYPE "VIDEO_BUFFER_TYPE" + */ + virtual agora::media::ExternalVideoFrame::VIDEO_BUFFER_TYPE getBufferType() = 0; + /** + * Gets the video frame pixel format. + * + * @since v3.5.0 + * + * Before you initialize the custom video renderer, the SDK triggers this callback to query the pixel format of the + * video frame that you want to process. You must specify a pixel format for the video frame in the return value of + * this callback and then pass it to the SDK. + * + * @return \ref agora::media::ExternalVideoFrame::VIDEO_PIXEL_FORMAT "VIDEO_PIXEL_FORMAT" + */ + virtual agora::media::ExternalVideoFrame::VIDEO_PIXEL_FORMAT getPixelFormat() = 0; +#if (defined(__APPLE__) && TARGET_OS_IOS) + /** + * Notification for rendering the video in the pixel data type. + * + * @since v3.5.0 + * + * The SDK triggers this callback after capturing video in the pixel data type to alter the custom video renderer + * to process the video data. + * + * @note This method applies to iOS only. + * + * @param pixelBuffer The video data in the pixel data type. + * @param rotation The clockwise rotation angle of the video. + */ + virtual void onRenderPixelBuffer(CVPixelBufferRef pixelBuffer, int rotation) = 0; +#endif + /** + * Notification for rendering the video in the raw data type. + * + * @since v3.5.0 + * + * The SDK triggers this callback after capturing video in the raw data type to alter the custom video renderer to + * process the video data. + * + * @param rawData The video data in the raw data type. + * @param width The width (px) of the video. + * @param height The height (px) of the video. + * @param rotation The clockwise rotation angle of the video. + */ + virtual void onRenderRawData(uint8_t* rawData, int width, int height, int rotation) = 0; +}; +/** IRtcEngine is the base interface class of the Agora SDK that provides the main Agora SDK methods +invoked by your application. Enable the Agora SDK's communication functionality through the creation of an IRtcEngine object, then call the methods of this object. */ class IRtcEngine { @@ -5359,7 +6640,7 @@ class IRtcEngine { * - 0(ERR_OK): Success. * - < 0: Failure. * - -1(ERR_FAILED): A general error occurs (no specified reason). - * - -2(ERR_INALID_ARGUMENT): No `IRtcEngineEventHandler` object is specified. + * - -2(ERR_INVALID_ARGUMENT): No `IRtcEngineEventHandler` object is specified. * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. Check whether `context` is properly set. * - -22(ERR_RESOURCE_LIMITED): The resource is limited. The app uses too much of the system resource and fails to allocate any resources. * - -101(ERR_INVALID_APP_ID): The App ID is invalid. @@ -5391,7 +6672,9 @@ class IRtcEngine { /** Sets the channel profile of the Agora IRtcEngine. * - * The Agora IRtcEngine differentiates channel profiles and applies optimization algorithms accordingly. + * After initialization, the SDK uses the `CHANNEL_PROFILE_COMMUNICATION` channel profile by default. + * You can call this method to set the channel profile. The Agora IRtcEngine differentiates channel profiles and + * applies optimization algorithms accordingly. * For example, it prioritizes smoothness and low latency for a video call, and prioritizes video quality for the interactive live video streaming. * * @warning @@ -5409,48 +6692,61 @@ class IRtcEngine { */ virtual int setChannelProfile(CHANNEL_PROFILE_TYPE profile) = 0; - /** Sets the role of the user, such as a host or an audience (default), before joining a channel in the interactive live streaming. + /** Sets the role of the user in interactive live streaming. * - * This method can be used to switch the user role in the interactive live streaming after the user joins a channel. + * After calling \ref IRtcEngine::setChannelProfile "setChannelProfile" (CHANNEL_PROFILE_LIVE_BROADCASTING), the + * SDK sets the user role as audience by default. You can call `setClientRole` to set the user role as host. * - * In the `LIVE_BROADCASTING` profile, when a user switches user roles after joining a channel, a successful \ref agora::rtc::IRtcEngine::setClientRole "setClientRole" method call triggers the following callbacks: - * - The local client: \ref agora::rtc::IRtcEngineEventHandler::onClientRoleChanged "onClientRoleChanged" - * - The remote client: \ref agora::rtc::IRtcEngineEventHandler::onUserJoined "onUserJoined" or \ref agora::rtc::IRtcEngineEventHandler::onUserOffline "onUserOffline" (BECOME_AUDIENCE) + * 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 \ref IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" and \ref IRtcEngine::muteLocalVideoStream "muteLocalVideoStream" to + * change the publishing state. + * - Triggers \ref IRtcEngineEventHandler::onClientRoleChanged "onClientRoleChanged" or \ref IRtcEngineEventHandler::onClientRoleChangeFailed "onClientRoleChangeFailed" on the local client in 5s. + * - Triggers \ref IRtcEngineEventHandler::onUserJoined "onUserJoined" or \ref IRtcEngineEventHandler::onUserOffline "onUserOffline" (BECOME_AUDIENCE) + * on the remote client. * - * @note - * This method applies only to the `LIVE_BROADCASTING` profile. + * @note This method applies to the `LIVE_BROADCASTING` profile only. * - * @param role Sets the role of the user. See #CLIENT_ROLE_TYPE. + * @param role The role of a user in interactive live streaming. See #CLIENT_ROLE_TYPE. * * @return * - 0(ERR_OK): Success. * - < 0: Failure. * - -1(ERR_FAILED): A general error occurs (no specified reason). - * - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + * - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. + * - -5 (ERR_REFUSED): The request is rejected. In multichannel scenarios, if you have set any of the following in + * one channel, the SDK returns this error code when the user switches the user role to host in another channel: + * - Call `joinChannel` with the `options` parameter and use the default settings `publishLocalAudio = true` or `publishLocalVideo = true`. + * - Call `setClientRole` to set the user role as host. + * - Call `muteLocalAudioStream(false)` or `muteLocalVideoStream(false)`. * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. */ virtual int setClientRole(CLIENT_ROLE_TYPE role) = 0; - /** Sets the role of a user in interactive live streaming. + /** Sets the role of the user in interactive live streaming. * * @since v3.2.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: \ref IRtcEngineEventHandler::onClientRoleChanged "onClientRoleChanged". - * - The remote client: \ref IRtcEngineEventHandler::onUserJoined "onUserJoined" - * or \ref IRtcEngineEventHandler::onUserOffline "onUserOffline". + * In the `LIVE_BROADCASTING` channel profile, the + * SDK sets the user role as audience by default. You can call `setClientRole` to set the user role as host. + * + * You can call this method either before or after joining a channel. If you + * call this method to switch the user role after joining a channel, the SDK automatically does the following: + * - Calls \ref IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" and \ref IRtcEngine::muteLocalVideoStream "muteLocalVideoStream" to + * change the publishing state. + * - Triggers \ref IRtcEngineEventHandler::onClientRoleChanged "onClientRoleChanged" or \ref IRtcEngineEventHandler::onClientRoleChangeFailed "onClientRoleChangeFailed" on the local client in 5s. + * - Triggers \ref IRtcEngineEventHandler::onUserJoined "onUserJoined" or \ref IRtcEngineEventHandler::onUserOffline "onUserOffline" (BECOME_AUDIENCE) + * on the remote client. * * @note - * - This method applies to the `LIVE_BROADCASTING` profile only (when the `profile` parameter in - * \ref IRtcEngine::setChannelProfile "setChannelProfile" is set as `CHANNEL_PROFILE_LIVE_BROADCASTING`). + * - This method applies to the `LIVE_BROADCASTING` profile only. * - The difference between this method and \ref IRtcEngine::setClientRole(CLIENT_ROLE_TYPE) "setClientRole" [1/2] is that * this method can set the user level in addition to the user role. - * - The user role determines the permissions that the SDK grants to a user, such as permission to send local - * streams, receive remote streams, and push streams to a CDN address. - * - The user level determines the level of services that a user can enjoy within the permissions of the user's - * role. For example, an audience can choose to receive remote streams with low latency or ultra low latency. Levels - * affect prices. + * - The user role determines the permissions that the SDK grants to a user, such as permission to send local streams, + * receive remote streams, and push streams to a CDN address. + * - The user level determines the level of services that a user can enjoy within the permissions of the user's role. + * For example, an audience member can choose to receive remote streams with low latency or ultra low latency. + * **User level affects the pricing of services.** * * @param role The role of a user in interactive live streaming. See #CLIENT_ROLE_TYPE. * @param options The detailed options of a user, including user level. See ClientRoleOptions. @@ -5459,7 +6755,12 @@ class IRtcEngine { * - 0(ERR_OK): Success. * - < 0: Failure. * - -1(ERR_FAILED): A general error occurs (no specified reason). - * - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + * - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. + * - -5 (ERR_REFUSED): The request is rejected. In multichannel scenarios, if you have set any of the following in + * one channel, the SDK returns this error code when the user switches the user role to host in another channel: + * - Call `joinChannel` with the `options` parameter and use the default settings `publishLocalAudio = true` or `publishLocalVideo = true`. + * - Call `setClientRole` to set the user role as host. + * - Call `muteLocalAudioStream(false)` or `muteLocalVideoStream(false)`. * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. */ virtual int setClientRole(CLIENT_ROLE_TYPE role, const ClientRoleOptions& options) = 0; @@ -5482,7 +6783,7 @@ class IRtcEngine { @note A channel does not accept duplicate uids, such as two users with the same @p uid. If you set @p uid as 0, the system automatically assigns a @p uid. If you want to join a channel from different devices, ensure that each device has a different uid. @warning Ensure that the App ID used for creating the token is the same App ID used by the \ref IRtcEngine::initialize "initialize" method for initializing the RTC engine. Otherwise, the CDN live streaming may fail. - @param token The token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Windows). + @param token The token generated at your server. See [Authenticate Your Users with Tokens](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=All%20Platforms). @param channelId Pointer to the unique channel name for the Agora RTC session in the string format smaller than 64 bytes. Supported characters: - All lowercase English letters: a to z. - All uppercase English letters: A to Z. @@ -5495,15 +6796,18 @@ class IRtcEngine { @return - 0(ERR_OK): Success. - < 0: Failure. - - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. - -3(ERR_NOT_READY): The SDK fails to be initialized. You can try re-initializing the SDK. - -5(ERR_REFUSED): The request is rejected. This may be caused by the following: - You have created an IChannel object with the same channel name. - You have joined and published a stream in a channel created by the IChannel object. When you join a channel created by the IRtcEngine object, the SDK publishes the local audio and video streams to that channel by default. Because the SDK does not support publishing a local stream to more than one channel simultaneously, an error occurs in this occasion. - -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method. + - -17(ERR_JOIN_CHANNEL_REJECTED): The request to join the channel is rejected. The SDK supports joining only one + IRtcEngine channel at a time. Therefore, the SDK returns this error code when a user who has already joined an + IRtcEngine channel calls the joining channel method of the IRtcEngine class with a valid channel name. */ virtual int joinChannel(const char* token, const char* channelId, const char* info, uid_t uid) = 0; - /** Joins a channel with the user ID, and configures whether to automatically subscribe to the audio or video streams. + /** Joins a channel with the user ID, and configures whether to publish or automatically subscribe to the audio or video streams. * * @since v3.3.0 * @@ -5520,13 +6824,14 @@ class IRtcEngine { * * @note * - Compared with \ref IRtcEngine::joinChannel(const char* token, const char* channelId, const char* info, uid_t uid) "joinChannel" [1/2], this method - * has the options parameter which configures whether the user automatically subscribes to all remote audio and video streams in the channel when - * joining the channel. By default, the user subscribes to the audio and video streams of all the other users in the channel, thus incurring all + * has the `options` parameter, which configures whether the user publishes or automatically subscribes to the audio and video streams in the channel when + * joining the channel. By default, the user publishes the local audio and video streams and automatically subscribes to the audio and video streams + * of all the other users in the channel. Subscribing incurs all * associated usage costs. To unsubscribe, set the `options` parameter or call the `mute` methods accordingly. * - Ensure that the App ID used for generating the token is the same App ID used in the \ref IRtcEngine::initialize "initialize" method for * creating an `IRtcEngine` object. * - * @param token The token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Windows). + * @param token The token generated at your server. See [Authenticate Your Users with Tokens](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=All%20Platforms). * @param channelId Pointer to the unique channel name for the Agora RTC session in the string format smaller than 64 bytes. Supported characters: * - All lowercase English letters: a to z. * - All uppercase English letters: A to Z. @@ -5535,19 +6840,22 @@ class IRtcEngine { * - Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",". * @param info (Optional) Reserved for future use. * @param uid (Optional) User ID. A 32-bit unsigned integer with a value ranging from 1 to 232-1. The @p uid must be unique. If a @p uid is - * not assigned (or set to 0), the SDK assigns and returns a @p uid in the \ref IRtcEngineEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" callback. + * not assigned (or set to 0), the SDK assigns and returns a `uid` in the \ref IRtcEngineEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" callback. * Your application must record and maintain the returned `uid`, because the SDK does not do so. **Note**: The ID of each user in the channel should be unique. * If you want to join the same channel from different devices, ensure that the user IDs in all devices are different. * @param options The channel media options: ChannelMediaOptions. @return * - 0(ERR_OK): Success. * - < 0: Failure. - * - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + * - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. * - -3(ERR_NOT_READY): The SDK fails to be initialized. You can try re-initializing the SDK. * - -5(ERR_REFUSED): The request is rejected. This may be caused by the following: * - You have created an IChannel object with the same channel name. * - You have joined and published a stream in a channel created by the IChannel object. When you join a channel created by the IRtcEngine object, the SDK publishes the local audio and video streams to that channel by default. Because the SDK does not support publishing a local stream to more than one channel simultaneously, an error occurs in this occasion. * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method. + * - -17(ERR_JOIN_CHANNEL_REJECTED): The request to join the channel is rejected. The SDK supports joining only one + * IRtcEngine channel at a time. Therefore, the SDK returns this error code when a user who has already joined an + * IRtcEngine channel calls the joining channel method of the IRtcEngine class with a valid channel name. */ virtual int joinChannel(const char* token, const char* channelId, const char* info, uid_t uid, const ChannelMediaOptions& options) = 0; /** Switches to a different channel. @@ -5571,7 +6879,7 @@ class IRtcEngine { * This method applies to the audience role in a `LIVE_BROADCASTING` channel * only. * - * @param token The token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Windows). + * @param token The token generated at your server. See [Authenticate Your Users with Tokens](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=All%20Platforms). * @param channelId Unique channel name for the AgoraRTC session in the * string format. The string length must be less than 64 bytes. Supported * character scopes are: @@ -5585,7 +6893,7 @@ class IRtcEngine { * - 0(ERR_OK): Success. * - < 0: Failure. * - -1(ERR_FAILED): A general error occurs (no specified reason). - * - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + * - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. * - -5(ERR_REFUSED): The request is rejected, probably because the user is not an audience. * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. * - -102(ERR_INVALID_CHANNEL_NAME): The channel name is invalid. @@ -5609,7 +6917,7 @@ class IRtcEngine { * By default, the user subscribes to the audio and video streams of all the other users in the target channel, thus incurring all associated usage costs. * To unsubscribe, set the `options` parameter or call the `mute` methods accordingly. * - * @param token The token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Windows). + * @param token The token generated at your server. See [Authenticate Your Users with Tokens](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=All%20Platforms). * @param channelId Unique channel name for the AgoraRTC session in the * string format. The string length must be less than 64 bytes. Supported * character scopes are: @@ -5624,7 +6932,7 @@ class IRtcEngine { * - 0(ERR_OK): Success. * - < 0: Failure. * - -1(ERR_FAILED): A general error occurs (no specified reason). - * - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + * - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. * - -5(ERR_REFUSED): The request is rejected, probably because the user is not an audience. * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. * - -102(ERR_INVALID_CHANNEL_NAME): The channel name is invalid. @@ -5652,11 +6960,15 @@ class IRtcEngine { - 0(ERR_OK): Success. - < 0: Failure. - -1(ERR_FAILED): A general error occurs (no specified reason). - - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. */ virtual int leaveChannel() = 0; + /// @cond + virtual int setAVSyncSource(const char* channelId, uid_t uid) = 0; + /// @endcond + /** Gets a new token when the current token expires after a period of time. The `token` expires after a period of time once the token schema is enabled when: @@ -5666,18 +6978,18 @@ class IRtcEngine { The application should call this method to get the new `token`. Failure to do so will result in the SDK disconnecting from the server. - @param token Pointer to the new token. + @param token The new token. @return - 0(ERR_OK): Success. - < 0: Failure. - -1(ERR_FAILED): A general error occurs (no specified reason). - - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. */ virtual int renewToken(const char* token) = 0; - /** Retrieves the pointer to the device manager object. + /** Gets the pointer to the device manager object. @param iid ID of the interface. @param inter Pointer to the *DeviceManager* object. @@ -5728,10 +7040,12 @@ class IRtcEngine { Once the user joins the channel (switches to another channel), the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. If you do not want to subscribe to a specified stream or all remote streams, call the `mute` methods accordingly. - @note To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. + @note + - To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the uid of the user is set to the same parameter type. + - Before using a String user name, ensure that you read [How can I use string user names](https://docs.agora.io/en/faq/string) for getting details about the limitations and implementation steps. - @param token The token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Windows). + @param token The token generated at your server. See [Authenticate Your Users with Tokens](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=All%20Platforms). @param channelId The channel name. The maximum length of this parameter is 64 bytes. Supported character scopes are: - All lowercase English letters: a to z. - All uppercase English letters: A to Z. @@ -5752,9 +7066,13 @@ class IRtcEngine { - #ERR_NOT_READY (-3) - #ERR_REFUSED (-5) - #ERR_NOT_INITIALIZED (-7) + - -17(ERR_JOIN_CHANNEL_REJECTED): The request to join the channel is rejected. The SDK supports joining only one + IRtcEngine channel at a time. Therefore, the SDK returns this error code when a user who has already joined an + IRtcEngine channel calls the joining channel method of the IRtcEngine class with a valid channel name. */ virtual int joinChannelWithUserAccount(const char* token, const char* channelId, const char* userAccount) = 0; - /** Joins the channel with a user account, and configures whether to automatically subscribe to audio or video streams after joining the channel. + /** Joins the channel with a user account, and configures + * whether to publish or automatically subscribe to the audio or video streams. * * @since v3.3.0 * @@ -5764,14 +7082,15 @@ class IRtcEngine { * * @note * - Compared with \ref IRtcEngine::joinChannelWithUserAccount(const char* token, const char* channelId, const char* userAccount) "joinChannelWithUserAccount" [1/2], - * this method has the options parameter to configure whether the end user automatically subscribes to all remote audio and video streams in a - * channel when joining the channel. By default, the user subscribes to the audio and video streams of all the other users in the channel, thus - * incurring all associated usage costs. To unsubscribe, set the `options` parameter or call the `mute` methods accordingly. + * this method has the options parameter, which configures whether the user publishes or automatically subscribes to the audio and video streams in the channel when + * joining the channel. By default, the user publishes the local audio and video streams and automatically subscribes to the audio and video streams of all the other + * users in the channel. Subscribing incurs all associated usage costs. To unsubscribe, set the `options` parameter or call the `mute` methods accordingly. * - To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all * the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the * uid of the user is set to the same parameter type. + * - Before using a String user name, ensure that you read [How can I use string user names](https://docs.agora.io/en/faq/string) for getting details about the limitations and implementation steps. * - * @param token The token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Windows). + * @param token The token generated at your server. See [Authenticate Your Users with Tokens](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=All%20Platforms). * @param channelId The channel name. The maximum length of this parameter is 64 bytes. Supported character scopes are: * - All lowercase English letters: a to z. * - All uppercase English letters: A to Z. @@ -5791,6 +7110,9 @@ class IRtcEngine { * - #ERR_INVALID_ARGUMENT (-2) * - #ERR_NOT_READY (-3) * - #ERR_REFUSED (-5) + * - -17(ERR_JOIN_CHANNEL_REJECTED): The request to join the channel is rejected. The SDK supports joining only one + * IRtcEngine channel at a time. Therefore, the SDK returns this error code when a user who has already joined an + * IRtcEngine channel calls the joining channel method of the IRtcEngine class with a valid channel name. */ virtual int joinChannelWithUserAccount(const char* token, const char* channelId, const char* userAccount, const ChannelMediaOptions& options) = 0; @@ -5870,85 +7192,121 @@ class IRtcEngine { */ virtual int startEchoTest(int intervalInSeconds) = 0; - /** Stops the audio call test. + /** Starts an audio and video call loop test. + * + * @since v3.5.2 + * + * Before joining a channel, to test whether the user's local sending and receiving streams are normal, you can call + * this method to perform an audio and video call loop test, which tests whether the audio and video devices and the + * user's upstream and downstream networks are working properly. + * + * After starting the test, the user needs to make a sound or face the camera. The audio or video is output after + * about two seconds. If the audio playback is normal, the audio device and the user's upstream and downstream + * networks are working properly; if the video playback is normal, the video device and the user's upstream and + * downstream networks are working properly. + * + * @note + * - Call this method before joining a channel. + * - After calling this method, call \ref IRtcEngine::stopEchoTest "stopEchoTest" to end the test; otherwise, the + * user cannot perform the next audio and video call loop test and cannot join the channel. + * - In the `LIVE_BROADCASTING` profile, only a host can call this method. + * + * @param config The configuration of the audio and video call loop test. See EchoTestConfiguration. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int startEchoTest(const EchoTestConfiguration& config) = 0; - @return - - 0: Success. - - < 0: Failure. + /** Stops call loop test. + * + * After calling `startEchoTest [2/3]` or `startEchoTest [3/3]`, call this method if you want to stop the call loop test. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int stopEchoTest() = 0; + /** Sets the Agora cloud proxy service. * * @since v3.3.0 * * When the user's firewall restricts the IP address and port, refer to *Use Cloud Proxy* to add the specific * IP addresses and ports to the firewall whitelist; then, call this method to enable the cloud proxy and set - * the cloud proxy type with the `proxyType` parameter: - * - `UDP_PROXY(1)`: The cloud proxy for the UDP protocol. - * - `TCP_PROXY(2)`: The cloud proxy for the TCP (encrypted) protocol. + * the `proxyType` parameter as `UDP_PROXY(1)`, which is the cloud proxy for the UDP protocol. * - * After a successfully cloud proxy connection, the SDK triggers the \ref IRtcEngineEventHandler::onConnectionStateChanged "onConnectionStateChanged" (CONNECTION_STATE_CONNECTING, CONNECTION_CHANGED_SETTING_PROXY_SERVER) callback. + * After a successfully cloud proxy connection, the SDK triggers + * the \ref IRtcEngineEventHandler::onConnectionStateChanged "onConnectionStateChanged" (CONNECTION_STATE_CONNECTING, CONNECTION_CHANGED_SETTING_PROXY_SERVER) callback. * * To disable the cloud proxy that has been set, call `setCloudProxy(NONE_PROXY)`. To change the cloud proxy type that has been set, * call `setCloudProxy(NONE_PROXY)` first, and then call `setCloudProxy`, and pass the value that you expect in `proxyType`. * * @note * - Agora recommends that you call this method before joining the channel or after leaving the channel. - * - When you use the cloud proxy for the UDP protocol, the services for pushing streams to CDN and co-hosting across channels are not available. - * - When you use the cloud proxy for the TCP (encrypted) protocol, note the following: - * - An error occurs when calling \ref IRtcEngine::startAudioMixing "startAudioMixing" to play online audio files in the HTTP protocol. - * - The services for pushing streams to CDN and co-hosting across channels will use the cloud proxy with the TCP protocol. + * - For the SDK v3.3.x, the services for pushing streams to CDN and co-hosting across channels are not available + * when you use the cloud proxy for the UDP protocol. For the SDK v3.4.0 and later, the services for pushing streams + * to CDN and co-hosting across channels are not available when the user is in a network environment with a firewall + * and uses the cloud proxy for the UDP protocol. * * @param proxyType The cloud proxy type, see #CLOUD_PROXY_TYPE. This parameter is required, and the SDK reports an error if you do not pass in a value. * * @return * - 0: Success. * - < 0: Failure. - * - `-2（ERR_INVALID_ARGUMENT)`: The parameter is invalid. + * - `-2(ERR_INVALID_ARGUMENT)`: The parameter is invalid. * - `-7(ERR_NOT_INITIALIZED)`: The SDK is not initialized. */ virtual int setCloudProxy(CLOUD_PROXY_TYPE proxyType) = 0; /** Enables the video module. - - Call this method either before joining a channel or during a call. If this method is called before joining a channel, the call starts in the video mode. If this method is called during an audio call, the audio mode switches to the video mode. To disable the video module, call the \ref IRtcEngine::disableVideo "disableVideo" method. - - A successful \ref agora::rtc::IRtcEngine::enableVideo "enableVideo" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onUserEnableVideo "onUserEnableVideo" (true) callback on the remote client. - @note - - This method affects the internal engine and can be called after the \ref agora::rtc::IRtcEngine::leaveChannel "leaveChannel" method. - - This method resets the internal engine and takes some time to take effect. We recommend using the following API methods to control the video engine modules separately: - - \ref IRtcEngine::enableLocalVideo "enableLocalVideo": Whether to enable the camera to create the local video stream. - - \ref IRtcEngine::muteLocalVideoStream "muteLocalVideoStream": Whether to publish the local video stream. - - \ref IRtcEngine::muteRemoteVideoStream "muteRemoteVideoStream": Whether to subscribe to and play the remote video stream. - - \ref IRtcEngine::muteAllRemoteVideoStreams "muteAllRemoteVideoStreams": Whether to subscribe to and play all remote video streams. - - @return - - 0: Success. - - < 0: Failure. + * + * Call this method either before joining a channel or during a call. If this method is called before joining a channel, the call starts in the video mode. If this method is called during an audio call, the audio mode switches to the video mode. To disable the video module, call the \ref IRtcEngine::disableVideo "disableVideo" method. + * + * A successful \ref agora::rtc::IRtcEngine::enableVideo "enableVideo" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onUserEnableVideo "onUserEnableVideo" (true) callback on the remote client. + * @note + * - This method affects the internal engine and can be called after the \ref agora::rtc::IRtcEngine::leaveChannel "leaveChannel" method. + * - This method resets the internal engine and takes some time to take effect. We recommend using the following API methods to control the video engine modules separately: + * - \ref IRtcEngine::enableLocalVideo "enableLocalVideo": Whether to enable the camera to create the local video stream. + * - \ref IRtcEngine::muteLocalVideoStream "muteLocalVideoStream": Whether to publish the local video stream. + * - \ref IRtcEngine::muteRemoteVideoStream "muteRemoteVideoStream": Whether to subscribe to and play the remote video stream. + * - \ref IRtcEngine::muteAllRemoteVideoStreams "muteAllRemoteVideoStreams": Whether to subscribe to and play all remote video streams. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int enableVideo() = 0; /** Disables the video module. - - This method can be called before joining a channel or during a call. If this method is called before joining a channel, the call starts in audio mode. If this method is called during a video call, the video mode switches to the audio mode. To enable the video module, call the \ref IRtcEngine::enableVideo "enableVideo" method. - - A successful \ref agora::rtc::IRtcEngine::disableVideo "disableVideo" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onUserEnableVideo "onUserEnableVideo" (false) callback on the remote client. - @note - - This method affects the internal engine and can be called after the \ref agora::rtc::IRtcEngine::leaveChannel "leaveChannel" method. - - This method resets the internal engine and takes some time to take effect. We recommend using the following API methods to control the video engine modules separately: - - \ref IRtcEngine::enableLocalVideo "enableLocalVideo": Whether to enable the camera to create the local video stream. - - \ref IRtcEngine::muteLocalVideoStream "muteLocalVideoStream": Whether to publish the local video stream. - - \ref IRtcEngine::muteRemoteVideoStream "muteRemoteVideoStream": Whether to subscribe to and play the remote video stream. - - \ref IRtcEngine::muteAllRemoteVideoStreams "muteAllRemoteVideoStreams": Whether to subscribe to and play all remote video streams. - - @return - - 0: Success. - - < 0: Failure. + * + * This method can be called before joining a channel or during a call. If this method is called before joining a + * channel, the call starts in audio mode. If this method is called during a video call, the video mode switches to + * the audio mode. To enable the video module, call the \ref IRtcEngine::enableVideo "enableVideo" method. + * + * A successful \ref agora::rtc::IRtcEngine::disableVideo "disableVideo" method call triggers + * the \ref agora::rtc::IRtcEngineEventHandler::onUserEnableVideo "onUserEnableVideo" (false) callback on the remote + * client. + * + * @note + * - This method affects the internal engine and can be called after + * the \ref agora::rtc::IRtcEngine::leaveChannel "leaveChannel" method. + * - This method resets the internal engine and takes some time to take effect. We recommend using the following + * APIs to control the video engine modules separately: + * - \ref IRtcEngine::enableLocalVideo "enableLocalVideo": Whether to enable the camera to create the local video stream. + * - \ref IRtcEngine::muteLocalVideoStream "muteLocalVideoStream": Whether to publish the local video stream. + * - \ref IRtcEngine::muteRemoteVideoStream "muteRemoteVideoStream": Whether to subscribe to and play the remote video stream. + * - \ref IRtcEngine::muteAllRemoteVideoStreams "muteAllRemoteVideoStreams": Whether to subscribe to and play all remote video streams. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int disableVideo() = 0; - /** **DEPRECATED** Sets the video profile. + /** Sets the video profile. - This method is deprecated as of v2.3. Use the \ref IRtcEngine::setVideoEncoderConfiguration "setVideoEncoderConfiguration" method instead. + @deprecated This method is deprecated as of v2.3. Use the \ref IRtcEngine::setVideoEncoderConfiguration "setVideoEncoderConfiguration" method instead. Each video profile includes a set of parameters, such as the resolution, frame rate, and bitrate. If the camera device does not support the specified resolution, the SDK automatically chooses a suitable camera resolution, keeping the encoder resolution specified by the *setVideoProfile* method. @@ -5968,7 +7326,7 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int setVideoProfile(VIDEO_PROFILE_TYPE profile, bool swapWidthAndHeight) = 0; + virtual int setVideoProfile(VIDEO_PROFILE_TYPE profile, bool swapWidthAndHeight) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Sets the video encoder configuration. @@ -6074,17 +7432,20 @@ class IRtcEngine { */ virtual int setRemoteUserPriority(uid_t uid, PRIORITY_TYPE userPriority) = 0; - /** Stops the local video preview and disables video. + /** Stops the local video preview. + * + * After calling \ref IRtcEngine::startPreview "startPreview", if you want to stop + * the local video preview, call `stopPreview`. + * + * @note Call this method before you join the channel or after you leave the channel. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int stopPreview() = 0; - @note Call this method before joining a channel. - - @return - - 0: Success. - - < 0: Failure. - */ - virtual int stopPreview() = 0; - - /** Enables the audio module. + /** Enables the audio module. The audio mode is enabled by default. @@ -6103,29 +7464,31 @@ class IRtcEngine { virtual int enableAudio() = 0; /** Disables/Re-enables the local audio function. - - The audio function is enabled by default. This method disables or re-enables the local audio function, that is, to stop or restart local audio capturing. - - This method does not affect receiving or playing the remote audio streams,and enableLocalAudio(false) is applicable to scenarios where the user wants to - receive remote audio streams without sending any audio stream to other users in the channel. - - Once the local audio function is disabled or re-enabled, the SDK triggers the \ref agora::rtc::IRtcEngineEventHandler::onLocalAudioStateChanged "onLocalAudioStateChanged" callback, - which reports `LOCAL_AUDIO_STREAM_STATE_STOPPED(0)` or `LOCAL_AUDIO_STREAM_STATE_RECORDING(1)`. - - @note - - This method is different from the \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" method: - - \ref agora::rtc::IRtcEngine::enableLocalAudio "enableLocalAudio": Disables/Re-enables the local audio capturing and processing. - If you disable or re-enable local audio capturing using the `enableLocalAudio` method, the local user may hear a pause in the remote audio playback. - - \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream": Sends/Stops sending the local audio streams. - - You can call this method either before or after joining a channel. - - @param enabled Sets whether to disable/re-enable the local audio function: - - true: (Default) Re-enable the local audio function, that is, to start the local audio capturing device (for example, the microphone). - - false: Disable the local audio function, that is, to stop local audio capturing. - - @return - - 0: Success. - - < 0: Failure. + * + * The audio function is enabled by default. This method disables or re-enables the local audio function, that is, to stop or restart local audio capturing. + * + * This method does not affect receiving the remote audio streams,and enableLocalAudio(false) is applicable to scenarios where the user wants to + * receive remote audio streams without sending any audio stream to other users in the channel. + * + * Once the local audio function is disabled or re-enabled, the SDK triggers the \ref agora::rtc::IRtcEngineEventHandler::onLocalAudioStateChanged "onLocalAudioStateChanged" callback, + * which reports `LOCAL_AUDIO_STREAM_STATE_STOPPED(0)` or `LOCAL_AUDIO_STREAM_STATE_RECORDING(1)`. + * + * @note + * - This method is different from the \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" method: + * - \ref agora::rtc::IRtcEngine::enableLocalAudio "enableLocalAudio": Disables/Re-enables the local audio capturing and processing. + * If you disable or re-enable local audio capturing using the `enableLocalAudio` method, the local user may hear a pause in the remote audio playback. + * - \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream": Sends/Stops sending the local audio streams. + * - This method can be called either before or after you join a channel. Calling it before you + * join a channel can set the device state only, and it takes effect immediately after you join the + * channel. + * + * @param enabled Sets whether to disable/re-enable the local audio function: + * - true: (Default) Re-enable the local audio function, that is, to start the local audio capturing device (for example, the microphone). + * - false: Disable the local audio function, that is, to stop local audio capturing. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int enableLocalAudio(bool enabled) = 0; @@ -6148,8 +7511,8 @@ class IRtcEngine { - In the `COMMUNICATION` and `LIVE_BROADCASTING` profiles, the bitrate may be different from your settings due to network self-adaptation. - In scenarios requiring high-quality audio, for example, a music teaching scenario, we recommend setting profile as AUDIO_PROFILE_MUSIC_HIGH_QUALITY (4) and scenario as AUDIO_SCENARIO_GAME_STREAMING (3). - @param profile Sets the sample rate, bitrate, encoding mode, and the number of channels. See #AUDIO_PROFILE_TYPE. - @param scenario Sets the audio application scenario. See #AUDIO_SCENARIO_TYPE. + @param profile Sets the sample rate, bitrate, encoding mode, and the number of channels. See #AUDIO_PROFILE_TYPE. + @param scenario Sets the audio application scenario. See #AUDIO_SCENARIO_TYPE. Under different audio scenarios, the device uses different volume types. For details, see [What is the difference between the in-call volume and the media volume?](https://docs.agora.io/en/faq/system_volume). @@ -6161,33 +7524,42 @@ class IRtcEngine { /** * Stops or resumes publishing the local audio stream. * - * A successful \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" method call - * triggers the \ref agora::rtc::IRtcEngineEventHandler::onUserMuteAudio "onUserMuteAudio" callback on the remote client. + * As of v3.4.5, this method only sets the publishing state of the audio stream in the channel of IRtcEngine. + * + * A successful method call triggers the \ref IRtcEngineEventHandler::onUserMuteAudio "onUserMuteAudio" callback + * on the remote client. + * + * You can only publish the local stream in one channel at a time. If you create multiple channels, ensure that + * you only call \ref IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" (false) in one channel; + * otherwise, the method call fails, and the SDK returns `-5 (ERR_REFUSED)`. * * @note - * - When @p mute is set as @p true, this method does not affect any ongoing audio recording, because it does not disable the microphone. - * - You can call this method either before or after joining a channel. If you call \ref agora::rtc::IRtcEngine::setChannelProfile "setChannelProfile" - * after this method, the SDK resets whether or not to stop publishing the local audio according to the channel profile and user role. - * Therefore, we recommend calling this method after the `setChannelProfile` method. + * - This method does not change the usage state of the audio-capturing device. + * - Whether this method call takes effect is affected by the + * \ref IRtcEngine::joinChannel(const char* token, const char* channelId, const char* info, uid_t uid, const ChannelMediaOptions& options) "joinChannel" [2/2] + * and \ref IRtcEngine::setClientRole "setClientRole" methods. For details, see *Set the Publishing State*. * * @param mute Sets whether to stop publishing the local audio stream. * - true: Stop publishing the local audio stream. - * - false: (Default) Resumes publishing the local audio stream. + * - false: Resume publishing the local audio stream. * * @return * - 0: Success. * - < 0: Failure. + * - `-5 (ERR_REFUSED)`: The request is rejected. */ virtual int muteLocalAudioStream(bool mute) = 0; /** * Stops or resumes subscribing to the audio streams of all remote users. * - * As of v3.3.0, after successfully calling this method, the local user stops or resumes + * 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*. + * - As of v3.3.0, this method contains the function of \ref IRtcEngine::setDefaultMuteAllRemoteAudioStreams "setDefaultMuteAllRemoteAudioStreams". + * Agora recommends not calling `muteAllRemoteAudioStreams` and `setDefaultMuteAllRemoteAudioStreams` + * together; otherwise, the settings may not take effect. See *Set the Subscribing State*. * * @param mute Sets whether to stop subscribing to the audio streams of all remote users. * - true: Stop subscribing to the audio streams of all remote users. @@ -6219,25 +7591,27 @@ class IRtcEngine { * - 0: Success. * - < 0: Failure. */ - virtual int setDefaultMuteAllRemoteAudioStreams(bool mute) = 0; + virtual int setDefaultMuteAllRemoteAudioStreams(bool mute) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Adjusts the playback signal volume of a specified remote user. - - You can call this method as many times as necessary to adjust the playback volume of different remote users, or to repeatedly adjust the playback volume of the same remote user. - - @note - - Call this method after joining a channel. - - The playback volume here refers to the mixed volume of a specified remote user. - - This method can only adjust the playback volume of one specified remote user at a time. To adjust the playback volume of different remote users, call the method as many times, once for each remote user. - - @param uid The ID of the remote user. - @param volume The playback volume of the specified remote user. The value ranges from 0 to 100: - - 0: Mute. - - 100: Original volume. - - @return - - 0: Success. - - < 0: Failure. + * + * You can call this method as many times as necessary to adjust the playback volume of different remote users, or to repeatedly adjust the playback volume of the same remote user. + * + * @note + * - Call this method after joining a channel. + * - The playback volume here refers to the mixed volume of a specified remote user. + * - This method can only adjust the playback volume of one specified remote user at a time. To adjust the playback volume of different remote users, call the method as many times, once for each remote user. + * + * @param uid The ID of the remote user. + * @param volume The playback volume of the specified remote user. The value + * ranges between 0 and 400, including the following: + * - 0: Mute. + * - 100: (Default) Original volume. + * - 400: Four times the original volume with signal-clipping protection. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int adjustUserPlaybackSignalVolume(unsigned int uid, int volume) = 0; /** @@ -6259,25 +7633,29 @@ class IRtcEngine { virtual int muteRemoteAudioStream(uid_t userId, bool mute) = 0; /** Stops or resumes publishing the local video stream. * - * A successful \ref agora::rtc::IRtcEngine::muteLocalVideoStream "muteLocalVideoStream" method call - * triggers the \ref agora::rtc::IRtcEngineEventHandler::onUserMuteVideo "onUserMuteVideo" callback on - * the remote client. + * As of v3.4.5, this method only sets the publishing state of the video stream in the channel of IRtcEngine. + * + * A successful method call triggers the \ref IRtcEngineEventHandler::onUserMuteVideo "onUserMuteVideo" + * callback on the remote client. + * + * You can only publish the local stream in one channel at a time. If you create multiple channels, + * ensure that you only call \ref IRtcEngine::muteLocalVideoStream "muteLocalVideoStream" (false) in one channel; + * otherwise, the method call fails, and the SDK returns `-5 (ERR_REFUSED)`. * * @note - * - This method executes faster than the \ref IRtcEngine::enableLocalVideo "enableLocalVideo" method, - * which controls the sending of the local video stream. - * - When `mute` is set as `true`, this method does not affect any ongoing video recording, because it does not disable the camera. - * - You can call this method either before or after joining a channel. If you call \ref IRtcEngine::setChannelProfile "setChannelProfile" - * after this method, the SDK resets whether or not to stop publishing the local video according to the channel profile and user role. - * Therefore, Agora recommends calling this method after the `setChannelProfile` method. + * - This method does not change the usage state of the video-capturing device. + * - Whether this method call takes effect is affected by the + * \ref IRtcEngine::joinChannel(const char* token, const char* channelId, const char* info, uid_t uid, const ChannelMediaOptions& options) "joinChannel" [2/2] + * and \ref IRtcEngine::setClientRole "setClientRole" methods. For details, see *Set the Publishing State*. * * @param mute Sets whether to stop publishing the local video stream. * - true: Stop publishing the local video stream. - * - false: (Default) Resumes publishing the local video stream. + * - false: Resume publishing the local video stream. * * @return * - 0: Success. * - < 0: Failure. + * - `-5 (ERR_REFUSED)`: The request is rejected. */ virtual int muteLocalVideoStream(bool mute) = 0; /** Enables/Disables the local video capture. @@ -6304,7 +7682,7 @@ class IRtcEngine { /** * Stops or resumes subscribing to the video streams of all remote users. * - * As of v3.3.0, after successfully calling this method, the local user stops or resumes + * 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 @@ -6340,7 +7718,7 @@ class IRtcEngine { * - 0: Success. * - < 0: Failure. */ - virtual int setDefaultMuteAllRemoteVideoStreams(bool mute) = 0; + virtual int setDefaultMuteAllRemoteVideoStreams(bool mute) AGORA_DEPRECATED_ATTRIBUTE = 0; /** * Stops or resumes subscribing to the video stream of a specified user. * @@ -6412,6 +7790,22 @@ class IRtcEngine { */ virtual int setRemoteDefaultVideoStreamType(REMOTE_VIDEO_STREAM_TYPE streamType) = 0; + /** Turn WIFI acceleration on or off. + + @note + - This method is called before and after joining a channel. + - Users check the WIFI router app for information about acceleration. Therefore, if this interface is invoked, the caller accepts that the caller's name will be displayed to the user in the WIFI router application on behalf of the caller. + + @param enabled + - true：Turn WIFI acceleration on. + - false：Turn WIFI acceleration off. + + @return + - 0: Success. + - < 0: Failure. + */ + virtual int enableWirelessAccelerate(bool enabled) = 0; + /** Enables the reporting of users' volume indication. This method enables the SDK to regularly report the volume information of the local user who sends a stream and @@ -6436,7 +7830,8 @@ class IRtcEngine { virtual int enableAudioVolumeIndication(int interval, int smooth, bool report_vad) = 0; /** Starts an audio recording. - @deprecated + @deprecated Deprecated from v2.9.1. + Use \ref IRtcEngine::startAudioRecording(const AudioRecordingConfiguration&) "startAudioRecording" [3/3] instead. The SDK allows recording during a call. Supported formats: @@ -6456,11 +7851,12 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int startAudioRecording(const char* filePath, AUDIO_RECORDING_QUALITY_TYPE quality) = 0; + virtual int startAudioRecording(const char* filePath, AUDIO_RECORDING_QUALITY_TYPE quality) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Starts an audio recording on the client. * - * @deprecated + * @deprecated Deprecated from v3.4.0. Use + * \ref IRtcEngine::startAudioRecording(const AudioRecordingConfiguration&) "startAudioRecording" [3/3] instead. * * The SDK allows recording during a call. After successfully calling this method, you can record the audio of all the users in the channel and get an audio recording file. * Supported formats of the recording file are as follows: @@ -6484,24 +7880,41 @@ class IRtcEngine { * - 0: Success. * - < 0: Failure. */ - virtual int startAudioRecording(const char* filePath, int sampleRate, AUDIO_RECORDING_QUALITY_TYPE quality) = 0; - /** Starts an audio recording. - - The SDK allows recording during a call. - This method is usually called after the \ref agora::rtc::IRtcEngine::joinChannel "joinChannel" method. - The recording automatically stops when the \ref agora::rtc::IRtcEngine::leaveChannel "leaveChannel" method is called. - - @param config Sets the audio recording configuration. See #AudioRecordingConfiguration. - - @return - - 0: Success. - - < 0: Failure. + virtual int startAudioRecording(const char* filePath, int sampleRate, AUDIO_RECORDING_QUALITY_TYPE quality) AGORA_DEPRECATED_ATTRIBUTE = 0; + /** + * Starts an audio recording on the client. + * + * @since v3.4.0 + * + * The SDK allows recording audio during a call. After successfully calling + * this method, you can record the audio of users in the channel and get + * an audio recording file. Supported file formats are as follows: + * - WAV: High-fidelity files with typically larger file sizes. For example, + * if the sample rate is 32,000 Hz, the file size for a 10-minute recording + * is approximately 73 MB. + * - AAC: Low-fidelity files with typically smaller file sizes. For example, + * if the sample rate is 32,000 Hz and the recording quality is + * #AUDIO_RECORDING_QUALITY_MEDIUM, the file size for a 10-minute recording + * is approximately 2 MB. + * + * Once the user leaves the channel, the recording automatically stops. + * + * @note Call this method after joining a channel. + * + * @param config Recording configuration. See AudioRecordingConfiguration. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `-160(ERR_ALREADY_IN_RECORDING)`: The client is already recording + * audio. To start a new recording, + * call \ref IRtcEngine::stopAudioRecording "stopAudioRecording" to stop the + * current recording first, and then + * call \ref IRtcEngine::startAudioRecording(const AudioRecordingConfiguration&) "startAudioRecording". */ virtual int startAudioRecording(const AudioRecordingConfiguration& config) = 0; /** Stops an audio recording on the client. - You can call this method before calling the \ref agora::rtc::IRtcEngine::leaveChannel "leaveChannel" method else, the recording automatically stops when the \ref agora::rtc::IRtcEngine::leaveChannel "leaveChannel" method is called. - @return - 0: Success - < 0: Failure. @@ -6509,71 +7922,116 @@ class IRtcEngine { virtual int stopAudioRecording() = 0; /** Starts playing and mixing the music file. - - @deprecated Deprecated from v3.4.0. Using the following methods instead: - - \ref IRtcEngine::startAudioMixing(const char* filePath, bool loopback, bool replace, int cycle, int startPos = 0) - - This method mixes the specified local audio file with the audio stream from the microphone, or replaces the microphone's audio stream with the specified local audio file. You can choose whether the other user can hear the local audio playback and specify the number of playback loops. This method also supports online music playback. - - When the audio mixing file playback finishes after calling this method, the SDK triggers the \ref agora::rtc::IRtcEngineEventHandler::onAudioMixingFinished "onAudioMixingFinished" callback. - - A successful \ref agora::rtc::IRtcEngine::startAudioMixing "startAudioMixing" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (PLAY) callback on the local client. - - When the audio mixing file playback finishes, the SDK triggers the \ref agora::rtc::IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (STOPPED) callback on the local client. - @note - - Call this method after joining a channel, otherwise issues may occur. - - If the local audio mixing file does not exist, or if the SDK does not support the file format or cannot access the music file URL, the SDK returns #WARN_AUDIO_MIXING_OPEN_ERROR (701). - - If you want to play an online music file, ensure that the time interval between calling this method is more than 100 ms, or the #AUDIO_MIXING_ERROR_TOO_FREQUENT_CALL (702) error code occurs. - - @param filePath Pointer to the absolute path (including the suffixes of the filename) of the local or online audio file to mix, for example, `C:/music/audio.mp4`. Supported audio formats: 3GP, ASF, ADTS, AVI, MP3, MP4, MPEG-4, SAMI, and WAVE. For more information, see [Supported Media Formats in Media Foundation](https://docs.microsoft.com/en-us/windows/desktop/medfound/supported-media-formats-in-media-foundation). - @param loopback Sets which user can hear the audio mixing: - - true: Only the local user can hear the audio mixing. - - false: Both users can hear the audio mixing. - @param replace Sets the audio mixing content: - - true: Only publish the specified audio file. The audio stream from the microphone is not published. - - false: The local audio file is mixed with the audio stream from the microphone. - @param cycle Sets the number of playback loops: - - Positive integer: Number of playback loops. - - `-1`: Infinite playback loops. - - @return - - 0: Success. - - < 0: Failure. + * + * @deprecated Deprecated from v3.4.0. Use + * \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" [2/2] instead. + * + * This method mixes the specified local audio file with the audio stream from the microphone, or replaces the microphone's audio stream with the specified local audio file. You can choose whether the other user can hear the local audio playback and specify the number of playback loops. This method also supports online music playback. + * + * When the audio mixing file playback finishes after calling this method, the SDK triggers the \ref agora::rtc::IRtcEngineEventHandler::onAudioMixingFinished "onAudioMixingFinished" callback. + * + * A successful \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (PLAY) callback on the local client. + * + * When the audio mixing file playback finishes, the SDK triggers the \ref agora::rtc::IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (STOPPED) callback on the local client. + * + * @note + * - If the local audio mixing file does not exist, or if the SDK does not support the file format or cannot access the music file URL, the SDK returns #WARN_AUDIO_MIXING_OPEN_ERROR (701). + * - If you want to play an online music file, ensure that the time interval between calling this method is more than 100 ms, or the `AUDIO_MIXING_ERROR_TOO_FREQUENT_CALL(702)` error code occurs. + * - To avoid blocking, as of v3.4.5, this method changes from a synchronous call to an asynchronous call. + * - For the audio file formats supported by this method, see [What formats of audio files does the Agora RTC SDK support](https://docs.agora.io/en/faq/audio_format). + * + * @param filePath The absolute path or URL address (including the filename extensions) + * of the music file. For example: `C:\music\audio.mp4`. + * When you access a local file on Android, Agora recommends passing a URI address or the path starts + * with `/assets/` in this parameter. + * @param loopback Sets which user can hear the audio mixing: + * - true: Only the local user can hear the audio mixing. + * - false: Both users can hear the audio mixing. + * @param replace Sets the audio mixing content: + * - true: Only publish the specified audio file. The audio stream from the microphone is not published. + * - false: The local audio file is mixed with the audio stream from the microphone. + * @param cycle Sets the number of playback loops: + * - Positive integer: Number of playback loops. + * - `-1`: Infinite playback loops. + * + * @return + * - 0: Success. + * - < 0: Failure. */ - virtual int startAudioMixing(const char* filePath, bool loopback, bool replace, int cycle) = 0; - - /** Starts playing and mixing the music file. - - This method mixes the specified local audio file with the audio stream from the microphone, or replaces the microphone's audio stream with the specified local audio file. You can choose whether the other user can hear the local audio playback and specify the number of playback loops. This method also supports online music playback. - - When the audio mixing file playback finishes after calling this method, the SDK triggers the \ref agora::rtc::IRtcEngineEventHandler::onAudioMixingFinished "onAudioMixingFinished" callback. - - A successful \ref agora::rtc::IRtcEngine::startAudioMixing "startAudioMixing" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (PLAY) callback on the local client. - - When the audio mixing file playback finishes, the SDK triggers the \ref agora::rtc::IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (STOPPED) callback on the local client. - @note - - Call this method after joining a channel, otherwise issues may occur. - - If the local audio mixing file does not exist, or if the SDK does not support the file format or cannot access the music file URL, the SDK returns #WARN_AUDIO_MIXING_OPEN_ERROR (701). - - If you want to play an online music file, ensure that the time interval between calling this method is more than 100 ms, or the #AUDIO_MIXING_ERROR_TOO_FREQUENT_CALL (702) error code occurs. - - @param filePath Pointer to the absolute path (including the suffixes of the filename) of the local or online audio file to mix, for example, `C:/music/audio.mp4`. Supported audio formats: 3GP, ASF, ADTS, AVI, MP3, MP4, MPEG-4, SAMI, and WAVE. For more information, see [Supported Media Formats in Media Foundation](https://docs.microsoft.com/en-us/windows/desktop/medfound/supported-media-formats-in-media-foundation). - @param loopback Sets which user can hear the audio mixing: - - true: Only the local user can hear the audio mixing. - - false: Both users can hear the audio mixing. - @param replace Sets the audio mixing content: - - true: Only publish the specified audio file. The audio stream from the microphone is not published. - - false: The local audio file is mixed with the audio stream from the microphone. - @param cycle Sets the number of playback loops: - - Positive integer: Number of playback loops. - - `-1`: Infinite playback loops. - @param startPos start playback position. - - Min value is 0. - - Max value is file length, the unit is ms - @return - - 0: Success. - - < 0: Failure. + virtual int startAudioMixing(const char* filePath, bool loopback, bool replace, int cycle) AGORA_DEPRECATED_ATTRIBUTE = 0; + /** + * Starts playing and mixing the music file. + * + * @since v3.4.0 + * + * This method supports mixing or replacing local or online music file and + * audio collected by a microphone. After successfully playing the music + * file, the SDK triggers + * \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING,AUDIO_MIXING_REASON_STARTED_BY_USER). + * After completing playing the music file, the SDK triggers + * `onAudioMixingStateChanged(AUDIO_MIXING_STATE_STOPPED,AUDIO_MIXING_REASON_ALL_LOOPS_COMPLETED)`. + * + * @note + * - If you need to call + * \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" multiple times, + * ensure that the call interval is longer than 500 ms. + * - If the local music file does not exist, or if the SDK does not support + * the file format or cannot access the music file URL, the SDK returns + * #WARN_AUDIO_MIXING_OPEN_ERROR (701). + * - On Android: + * - To use this method, ensure that the Android device is v4.2 or later + * and the API version is v16 or later. + * - If you need to play an online music file, Agora does not recommend + * using the redirected URL address. Some Android devices may fail to open a redirected URL address. + * - If you call this method on an emulator, ensure that the music file is + * in the `/sdcard/` directory and the format is MP3. + * - To avoid blocking, as of v3.4.5, this method changes from a synchronous call to an asynchronous call. + * - For the audio file formats supported by this method, see [What formats of audio files does the Agora RTC SDK support](https://docs.agora.io/en/faq/audio_format). + * + * @param filePath The absolute path or URL address (including the filename extensions) + * of the music file. For example: `C:\music\audio.mp4`. + * When you access a local file on Android, Agora recommends passing a URI address or the path starts + * with `/assets/` in this parameter. + * @param loopback Whether to only play the music file on the local client: + * - true: Only play the music file on the local client so that only the local + * user can hear the music. + * - false: Publish the music file to remote clients so that both the local + * user and remote users can hear the music. + * @param replace Whether to replace the audio collected by the microphone + * with a music file: + * - true: Replace. Users can only hear music. + * - false: Do not replace. Users can hear both music and audio collected by + * the microphone. + * @param 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 the + * music file once. + * - `-1`: Play the music in an indefinite loop. + * @param startPos The playback position (ms) of the music file. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int startAudioMixing(const char* filePath, bool loopback, bool replace, int cycle, int startPos) = 0; + /** + * Sets the playback speed of the current music file. + * + * @since v3.5.1 + * + * @note Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" [2/2] + * and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + * + * @param speed The playback speed. Agora recommends that you limit this value to between 50 and 400, defined as follows: + * - 50: Half the original speed. + * - 100: The original speed. + * - 400: 4 times the original speed. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int setAudioMixingPlaybackSpeed(int speed) = 0; /** Stops playing and mixing the music file. Call this method when you are in a channel. @@ -6592,6 +8050,72 @@ class IRtcEngine { - < 0: Failure. */ virtual int pauseAudioMixing() = 0; + /** + * Specifies the playback track of the current music file. + * + * @since v3.5.1 + * + * After getting the audio track index of the current music file, call this + * method to specify any audio track to play. For example, if different tracks + * of a multitrack file store songs in different languages, you can call this + * method to set the language of the music file to play. + * + * @note + * - This method is for Android, iOS, and Windows only. + * - Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" [2/2] + * and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + * - 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). + * + * @param index The specified playback track. This parameter must be less than or equal to the return value + * of \ref IRtcEngine::getAudioTrackCount "getAudioTrackCount". + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int selectAudioTrack(int index) = 0; + /** + * Gets the audio track index of the current music file. + * + * @since v3.5.1 + * + * @note + * - This method is for Android, iOS, and Windows only. + * - Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" [2/2] + * and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + * - 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). + * + * @return + * - ≥ 0: The audio track index of the current music file, if this method call succeeds. + * - < 0: Failure. + */ + virtual int getAudioTrackCount() = 0; + /** + * Sets the channel mode of the current music file. + * + * @since v3.5.1 + * + * In a stereo music file, the left and right channels can store different audio data. + * According to your needs, you can set the channel mode to original mode, left channel mode, + * right channel mode, or mixed channel mode. For example, in the KTV scenario, the left + * channel of the music file stores the musical accompaniment, and the right channel + * stores the singing voice. If you only need to listen to the accompaniment, call this + * method to set the channel mode of the music file to left channel mode; if you need to + * listen to the accompaniment and the singing voice at the same time, call this method + * to set the channel mode to mixed channel mode. + * + * @note + * - Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" [2/2] + * and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + * - This method only applies to stereo audio files. + * + * @param mode The channel mode. See \ref agora::media::AUDIO_MIXING_DUAL_MONO_MODE "AUDIO_MIXING_DUAL_MONO_MODE". + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int setAudioMixingDualMonoMode(agora::media::AUDIO_MIXING_DUAL_MONO_MODE mode) = 0; /** Resumes playing and mixing the music file. Call this method when you are in a channel. @@ -6625,8 +8149,8 @@ class IRtcEngine { /** Adjusts the volume during audio mixing. @note - - Calling this method does not affect the volume of audio effect file playback invoked by the \ref agora::rtc::IRtcEngine::playEffect "playEffect" method. - - Call this method after calling \ref IRtcEngine::startAudioMixing "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + - Calling this method does not affect the volume of audio effect file playback invoked by the \ref IRtcEngine::playEffect(int,const char*,int,double,double,int,bool,int) "playEffect" method. + - Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. @param volume Audio mixing volume. The value ranges between 0 and 100 (default). @@ -6637,7 +8161,7 @@ class IRtcEngine { virtual int adjustAudioMixingVolume(int volume) = 0; /** Adjusts the audio mixing volume for local playback. - @note Call this method after calling \ref IRtcEngine::startAudioMixing "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + @note Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. @param volume Audio mixing volume for local playback. The value ranges between 0 and 100 (default). @@ -6646,13 +8170,13 @@ class IRtcEngine { - < 0: Failure. */ virtual int adjustAudioMixingPlayoutVolume(int volume) = 0; - /** Retrieves the audio mixing volume for local playback. + /** Gets the audio mixing volume for local playback. This method helps troubleshoot audio volume related issues. @note - Call this method when you are in a channel. - - Call this method after calling \ref IRtcEngine::startAudioMixing "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + - Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. @return - ≥ 0: The audio mixing volume, if this method call succeeds. The value range is [0,100]. @@ -6661,7 +8185,7 @@ class IRtcEngine { virtual int getAudioMixingPlayoutVolume() = 0; /** Adjusts the audio mixing volume for publishing (for remote users). - @note Call this method after calling \ref IRtcEngine::startAudioMixing "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + @note Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. @param volume Audio mixing volume for publishing. The value ranges between 0 and 100 (default). @@ -6670,13 +8194,13 @@ class IRtcEngine { - < 0: Failure. */ virtual int adjustAudioMixingPublishVolume(int volume) = 0; - /** Retrieves the audio mixing volume for publishing. + /** Gets the audio mixing volume for publishing. This method helps troubleshoot audio volume related issues. @note - Call this method when you are in a channel. - - Call this method after calling \ref IRtcEngine::startAudioMixing "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + - Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. @return - ≥ 0: The audio mixing volume for publishing, if this method call succeeds. The value range is [0,100]. @@ -6684,44 +8208,34 @@ class IRtcEngine { */ virtual int getAudioMixingPublishVolume() = 0; - /** Retrieves the duration (ms) of the music file. - @deprecated Deprecated from v3.4.0. Use the following methods instead: - \ref IRtcEngine::getAudioMixingDuration(const char* filePath = NULL) - @note - - Call this method when you are in a channel. - - Call this method after calling \ref IRtcEngine::startAudioMixing "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. - - @return - - ≥ 0: The audio mixing duration, if this method call succeeds. - - < 0: Failure. - */ - virtual int getAudioMixingDuration() = 0; - /** Retrieves the duration (ms) of the music file. - - @note - - Call this method when you are in a channel. - - Call this method after calling \ref IRtcEngine::startAudioMixing "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. - @param filePath - - Return the file length while it is being played - @return - - ≥ 0: The audio mixing duration, if this method call succeeds. - - < 0: Failure. + /** Gets the duration (ms) of the music file. + * + * @deprecated This method is deprecated as of v3.5.1. Use \ref IRtcEngine::getAudioFileInfo "getAudioFileInfo" instead. + * + * @note + * - Call this method when you are in a channel. + * - Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" + * and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + * + * @return + * - ≥ 0: The audio mixing duration, if this method call succeeds. + * - < 0: Failure. */ - virtual int getAudioMixingDuration(const char* filePath) = 0; - /** Retrieves the playback position (ms) of the music file. - - @note - - Call this method when you are in a channel. - - Call this method after calling \ref IRtcEngine::startAudioMixing "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. - - @return - - ≥ 0: The current playback position of the audio mixing, if this method call succeeds. - - < 0: Failure. + virtual int getAudioMixingDuration() AGORA_DEPRECATED_ATTRIBUTE = 0; + /** Gets the playback position (ms) of the music file. + * + * @note + * - Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + * - If you need to call `getAudioMixingCurrentPosition` multiple times, ensure that the call interval is longer than 500 ms. + * + * @return + * - ≥ 0: The current playback position (ms) of the music file, if this method call succeeds. 0 represents that the current music file does not start playing. + * - < 0: Failure. */ virtual int getAudioMixingCurrentPosition() = 0; /** Sets the playback position of the music file to a different starting position (the default plays from the beginning). - @note Call this method after calling \ref IRtcEngine::startAudioMixing "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + @note Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. @param pos The playback starting position (ms) of the music file. @@ -6735,7 +8249,7 @@ class IRtcEngine { * * When a local music file is mixed with a local human voice, call this method to set the pitch of the local music file only. * - * @note Call this method after calling \ref IRtcEngine::startAudioMixing "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. + * @note Call this method after calling \ref IRtcEngine::startAudioMixing(const char*,bool,bool,int,int) "startAudioMixing" and receiving the \ref IRtcEngineEventHandler::onAudioMixingStateChanged "onAudioMixingStateChanged" (AUDIO_MIXING_STATE_PLAYING) callback. * * @param pitch Sets the pitch of the local music file by chromatic scale. The default value is 0, * which means keeping the original pitch. The value ranges from -12 to 12, and the pitch value between @@ -6747,11 +8261,11 @@ class IRtcEngine { * - < 0: Failure. */ virtual int setAudioMixingPitch(int pitch) = 0; - /** Retrieves the volume of the audio effects. + /** Gets the volume of the audio effects. The value ranges between 0.0 and 100.0. - @note Ensure that this method is called after \ref IRtcEngine::playEffect "playEffect". + @note Ensure that this method is called after \ref IRtcEngine::playEffect(int,const char*,int,double,double,int,bool,int) "playEffect" . @return - ≥ 0: Volume of the audio effects, if this method call succeeds. @@ -6761,7 +8275,7 @@ class IRtcEngine { virtual int getEffectsVolume() = 0; /** Sets the volume of the audio effects. - @note Ensure that this method is called after \ref IRtcEngine::playEffect "playEffect". + @note Ensure that this method is called after \ref IRtcEngine::playEffect(int,const char*,int,double,double,int,bool,int) "playEffect" . @param volume Sets the volume of the audio effects. The value ranges between 0 and 100 (default). @@ -6772,7 +8286,7 @@ class IRtcEngine { virtual int setEffectsVolume(int volume) = 0; /** Sets the volume of a specified audio effect. - @note Ensure that this method is called after \ref IRtcEngine::playEffect "playEffect". + @note Ensure that this method is called after \ref IRtcEngine::playEffect(int,const char*,int,double,double,int,bool,int) "playEffect" . @param soundId ID of the audio effect. Each audio effect has a unique ID. @param volume Sets the volume of the specified audio effect. The value ranges between 0 and 100 (default). @@ -6808,72 +8322,98 @@ class IRtcEngine { */ virtual int enableFaceDetection(bool enable) = 0; #endif - /** Plays a specified local or online audio effect file. - @deprecated Deprecated from v3.4.0 Use the following methods instead: - - \ref IRtcEngine::playEffect(int soundId, const char* filePath, int loopCount, double pitch, double pan, int gain, bool publish = false, int startPos = 0) - - This method allows you to set the loop count, pitch, pan, and gain of the audio effect file, as well as whether the remote user can hear the audio effect. - - To play multiple audio effect files simultaneously, call this method multiple times with different soundIds and filePaths. We recommend playing no more than three audio effect files at the same time. - - @note - - If the audio effect is preloaded into the memory through the \ref IRtcEngine::preloadEffect "preloadEffect" method, the value of @p soundID must be the same as that in the *preloadEffect* method. - - Playing multiple online audio effect files simultaneously is not supported on macOS and Windows. - - Ensure that you call this method after joining a channel. - - @param soundId ID of the specified audio effect. Each audio effect has a unique ID. - @param filePath Specifies the absolute path (including the suffixes of the filename) to the local audio effect file or the URL of the online audio effect file, for example, c:/music/audio.mp4. Supported audio formats: mp3, mp4, m4a, aac, 3gp, mkv and wav. - @param loopCount Sets the number of times the audio effect loops: - - 0: Play the audio effect once. - - 1: Play the audio effect twice. - - -1: Play the audio effect in an indefinite loop until the \ref IRtcEngine::stopEffect "stopEffect" or \ref IRtcEngine::stopAllEffects "stopAllEffects" method is called. - @param pitch Sets the pitch of the audio effect. The value ranges between 0.5 and 2. The default value is 1 (no change to the pitch). The lower the value, the lower the pitch. - @param pan Sets the spatial position of the audio effect. The value ranges between -1.0 and 1.0: - - 0.0: The audio effect displays ahead. - - 1.0: The audio effect displays to the right. - - -1.0: The audio effect displays to the left. - @param gain Sets the volume of the audio effect. The value ranges between 0 and 100 (default). The lower the value, the lower the volume of the audio effect. - @param publish Sets whether or not to publish the specified audio effect to the remote stream: - - true: The locally played audio effect is published to the Agora Cloud and the remote users can hear it. - - false: The locally played audio effect is not published to the Agora Cloud and the remote users cannot hear it. - @return - - 0: Success. - - < 0: Failure. + * + * @deprecated Deprecated from v3.4.0. Use + * \ref IRtcEngine::playEffect(int,const char*,int,double,double,int,bool,int) "playEffect" [2/2] instead. + * + * This method allows you to set the loop count, pitch, pan, and gain of the audio effect file, as well as whether the remote user can hear the audio effect. + * + * To play multiple audio effect files simultaneously, call this method multiple times with different soundIds and filePaths. We recommend playing no more than three audio effect files at the same time. + * + * @note + * - If the audio effect is preloaded into the memory through the \ref IRtcEngine::preloadEffect "preloadEffect" method, the value of @p soundID must be the same as that in the *preloadEffect* method. + * - Playing multiple online audio effect files simultaneously is not supported on macOS and Windows. + * - Ensure that you call this method after joining a channel. + * - For the audio file formats supported by this method, see [What formats of audio files does the Agora RTC SDK support](https://docs.agora.io/en/faq/audio_format). + * + * @param soundId ID of the specified audio effect. Each audio effect has a unique ID. + * @param filePath The absolute path or URL address (including the filename extensions) + * of the music file. For example: `C:\music\audio.mp4`. + * When you access a local file on Android, Agora recommends passing a URI address or the path starts + * with `/assets/` in this parameter. + * @param loopCount Sets the number of times the audio effect loops: + * - 0: Play the audio effect once. + * - 1: Play the audio effect twice. + * - -1: Play the audio effect in an indefinite loop until the \ref IRtcEngine::stopEffect "stopEffect" or \ref IRtcEngine::stopAllEffects "stopAllEffects" method is called. + * @param pitch Sets the pitch of the audio effect. The value ranges between 0.5 and 2. The default value is 1 (no change to the pitch). The lower the value, the lower the pitch. + * @param pan Sets the spatial position of the audio effect. The value ranges between -1.0 and 1.0: + * - 0.0: The audio effect displays ahead. + * - 1.0: The audio effect displays to the right. + * - -1.0: The audio effect displays to the left. + * @param gain Sets the volume of the audio effect. The value ranges between 0 and 100 (default). The lower the value, the lower the volume of the audio effect. + * @param publish Sets whether to publish the specified audio effect to the remote stream: + * - true: The locally played audio effect is published to the Agora Cloud and the remote users can hear it. + * - false: The locally played audio effect is not published to the Agora Cloud and the remote users cannot hear it. + * @return + * - 0: Success. + * - < 0: Failure. */ - virtual int playEffect(int soundId, const char* filePath, int loopCount, double pitch, double pan, int gain, bool publish = false) = 0; - /** Plays a specified local or online audio effect file. - - This method allows you to set the loop count, pitch, pan, and gain of the audio effect file, as well as whether the remote user can hear the audio effect. - - To play multiple audio effect files simultaneously, call this method multiple times with different soundIds and filePaths. We recommend playing no more than three audio effect files at the same time. - - @note - - If the audio effect is preloaded into the memory through the \ref IRtcEngine::preloadEffect "preloadEffect" method, the value of @p soundID must be the same as that in the *preloadEffect* method. - - Playing multiple online audio effect files simultaneously is not supported on macOS and Windows. - - Ensure that you call this method after joining a channel. - - @param soundId ID of the specified audio effect. Each audio effect has a unique ID. - @param filePath Specifies the absolute path (including the suffixes of the filename) to the local audio effect file or the URL of the online audio effect file, for example, c:/music/audio.mp4. Supported audio formats: mp3, mp4, m4a, aac, 3gp, mkv and wav. - @param loopCount Sets the number of times the audio effect loops: - - 0: Play the audio effect once. - - 1: Play the audio effect twice. - - -1: Play the audio effect in an indefinite loop until the \ref IRtcEngine::stopEffect "stopEffect" or \ref IRtcEngine::stopAllEffects "stopAllEffects" method is called. - @param pitch Sets the pitch of the audio effect. The value ranges between 0.5 and 2. The default value is 1 (no change to the pitch). The lower the value, the lower the pitch. - @param pan Sets the spatial position of the audio effect. The value ranges between -1.0 and 1.0: - - 0.0: The audio effect displays ahead. - - 1.0: The audio effect displays to the right. - - -1.0: The audio effect displays to the left. - @param gain Sets the volume of the audio effect. The value ranges between 0 and 100 (default). The lower the value, the lower the volume of the audio effect. - @param publish Sets whether or not to publish the specified audio effect to the remote stream: - - true: The locally played audio effect is published to the Agora Cloud and the remote users can hear it. - - false: The locally played audio effect is not published to the Agora Cloud and the remote users cannot hear it. - @param startPos Set the play position when call this API - - Min 0, start play a url/file from start - - max value is the file length. the unit is ms - @return - - 0: Success. - - < 0: Failure. + virtual int playEffect(int soundId, const char* filePath, int loopCount, double pitch, double pan, int gain, bool publish = false) AGORA_DEPRECATED_ATTRIBUTE = 0; + /** + * Plays a specified local or online audio effect file. + * + * @since v3.4.0 + * + * To play multiple audio effect files at the same time, call this method + * multiple times with different `soundId` and `filePath` values. For the + * best user experience, Agora recommends playing no more than three audio + * effect files at the same time. + * + * After completing playing an audio effect file, the SDK triggers the + * \ref IRtcEngineEventHandler::onAudioEffectFinished "onAudioEffectFinished" + * callback. + * + * @note + * - Call this method after joining a channel. + * - For the audio file formats supported by this method, see [What formats of audio files does the Agora RTC SDK support](https://docs.agora.io/en/faq/audio_format). + * + * @param soundId Audio effect ID. The ID of each audio effect file is + * unique. If you preloaded an audio effect into memory by calling + * \ref IRtcEngine::preloadEffect "preloadEffect", ensure that this + * parameter is set to the same value as in `preloadEffect`. + * @param filePath The absolute path or URL address (including the filename extensions) + * of the music file. For example: `C:\music\audio.mp4`. + * If you preloaded an audio effect into memory by calling + * \ref IRtcEngine::preloadEffect "preloadEffect", ensure that this + * parameter is set to the same value as in `preloadEffect`. + * When you access a local file on Android, Agora recommends passing a URI address or the path starts + * with `/assets/` in this parameter. + * + * @param loopCount The number of times the audio effect loops: + * - ≥ 0: The number of loops. For example, `1` means loop one time, + * which means play the audio effect two times in total. + * - `-1`: Play the audio effect in an indefinite loop. + * @param pitch The pitch of the audio effect. The range is 0.5 to 2.0. + * The default value is 1.0, which means the original pitch. The lower the + * value, the lower the pitch. + * @param pan The spatial position of the audio effect. The range is `-1.0` + * to `1.0`. For example: + * - `-1.0`: The audio effect occurs on the left. + * - `0.0`: The audio effect occurs in the front. + * - `1.0`: The audio effect occurs on the right. + * @param gain The volume of the audio effect. The range is 0.0 to 100.0. + * The default value is 100.0, which means the original volume. The smaller + * the value, the less the gain. + * @param publish Whether to publish the audio effect to the remote users: + * - true: Publish. Both the local user and remote users can hear the audio + * effect. + * - false: Do not publish. Only the local user can hear the audio effect. + * @param startPos The playback position (ms) of the audio effect file. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int playEffect(int soundId, const char* filePath, int loopCount, double pitch, double pan, int gain, bool publish, int startPos) = 0; /** Stops playing a specified audio effect. @@ -6894,19 +8434,20 @@ class IRtcEngine { virtual int stopAllEffects() = 0; /** Preloads a specified audio effect file into the memory. - - @note This method does not support online audio effect files. - - To ensure smooth communication, limit the size of the audio effect file. We recommend using this method to preload the audio effect before calling the \ref IRtcEngine::joinChannel "joinChannel" method. - - Supported audio formats: mp3, aac, m4a, 3gp, and wav. - - @param soundId ID of the audio effect. Each audio effect has a unique ID. - @param filePath Pointer to the absolute path of the audio effect file. - - @return - - 0: Success. - - < 0: Failure. + * + * To ensure smooth communication, limit the size of the audio effect file. We recommend using this method to preload the audio effect before calling the \ref IRtcEngine::joinChannel "joinChannel" method. + * + * @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). + * + * @param soundId ID of the audio effect. Each audio effect has a unique ID. + * @param filePath The absolute path or URL address (including the filename extensions) + * of the music file. For example: `C:\music\audio.mp4`. + * When you access a local file on Android, Agora recommends passing a URI address or the path starts + * with `/assets/` in this parameter. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int preloadEffect(int soundId, const char* filePath) = 0; /** Releases a specified preloaded audio effect from the memory. @@ -6947,20 +8488,106 @@ class IRtcEngine { - < 0: Failure. */ virtual int resumeAllEffects() = 0; - - virtual int getEffectDuration(const char* filePath) = 0; - - virtual int setEffectPosition(int soundId, int pos) = 0; - - virtual int getEffectCurrentPosition(int soundId) = 0; - + /** + * Gets the duration of the audio effect file. + * + * @since v3.4.0 + * + * @note + * - Call this method after joining a channel. + * - For the audio file formats supported by this method, see [What formats of audio files does the Agora RTC SDK support](https://docs.agora.io/en/faq/audio_format). + * + * @param filePath The absolute path or URL address (including the filename extensions) + * of the music file. For example: `C:\music\audio.mp4`. + * When you access a local file on Android, Agora recommends passing a URI address or the path starts + * with `/assets/` in this parameter. + * + * @return + * - ≥ 0: A successful method call. Returns the total duration (ms) of + * the specified audio effect file. + * - < 0: Failure. + * - `-22(ERR_RESOURCE_LIMITED)`: Cannot find the audio effect file. Please + * set a correct `filePath`. + */ + virtual int getEffectDuration(const char* filePath) = 0; + /** + * Sets the playback position of an audio effect file. + * + * @since v3.4.0 + * + * After a successful setting, the local audio effect file starts playing at the specified position. + * + * @note Call this method after \ref IRtcEngine::playEffect(int,const char*,int,double,double,int,bool,int) "playEffect" . + * + * @param soundId Audio effect ID. Ensure that this parameter is set to the + * same value as in \ref IRtcEngine::playEffect(int,const char*,int,double,double,int,bool,int) "playEffect" . + * @param pos The playback position (ms) of the audio effect file. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `-22(ERR_RESOURCE_LIMITED)`: Cannot find the audio effect file. Please + * set a correct `soundId`. + */ + virtual int setEffectPosition(int soundId, int pos) = 0; + /** + * Gets the playback position of the audio effect file. + * + * @since v3.4.0 + * + * @note Call this method after \ref IRtcEngine::playEffect(int,const char*,int,double,double,int,bool,int) "playEffect" . + * + * @param soundId Audio effect ID. Ensure that this parameter is set to the + * same value as in \ref IRtcEngine::playEffect(int,const char*,int,double,double,int,bool,int) "playEffect" . + * + * @return + * - ≥ 0: A successful method call. Returns the playback position (ms) of + * the specified audio effect file. + * - < 0: Failure. + * - `-22(ERR_RESOURCE_LIMITED)`: Cannot find the audio effect file. Please + * set a correct `soundId`. + */ + virtual int getEffectCurrentPosition(int soundId) = 0; + + /** Gets the information of a specified audio file. + * + * @since v3.5.1 + * + * After calling this method successfully, the SDK triggers the + * \ref IRtcEngineEventHandler::onRequestAudioFileInfo "onRequestAudioFileInfo" + * callback to report the information of an audio file, such as audio duration. + * You can call this method multiple times to get the information of multiple audio files. + * + * @note + * - Call this method after joining a channel. + * - For the audio file formats supported by this method, see [What formats of audio files does the Agora RTC SDK support](https://docs.agora.io/en/faq/audio_format). + * + * @param filePath The file path: + * - Windows: The absolute path or URL address (including the filename extensions) of + * the audio file. For example: `C:\music\audio.mp4`. + * - Android: The file path, including the filename extensions. To access an online file, + * Agora supports using a URL address; to access a local file, Agora supports using a URI + * address, an absolute path, or a path that starts with `/assets/`. You might encounter + * permission issues if you use an absolute path to access a local file, so Agora recommends + * using a URI address instead. For example: `content://com.android.providers.media.documents/document/audio%3A14441`. + * - iOS or macOS: The absolute path or URL address (including the filename extensions) of the audio file. + * For example: `/var/mobile/Containers/Data/audio.mp4`. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int getAudioFileInfo(const char* filePath) = 0; + /** Enables or disables deep-learning noise reduction. + * + * @since v3.3.0 * * The SDK enables traditional noise reduction mode by default to reduce most of the stationary background noise. * If you need to reduce most of the non-stationary background noise, Agora recommends enabling deep-learning * noise reduction as follows: * - * 1. Integrate the dynamical library under the libs folder to your project: + * 1. Ensure that the dynamical library is integrated in your project: * - Android: `libagora_ai_denoise_extension.so` * - iOS: `AgoraAIDenoiseExtension.xcframework` * - macOS: `AgoraAIDenoiseExtension.framework` @@ -7000,7 +8627,7 @@ class IRtcEngine { Ensure that you call this method before joinChannel to enable stereo panning for remote users so that the local user can track the position of a remote user by calling \ref agora::rtc::IRtcEngine::setRemoteVoicePosition "setRemoteVoicePosition". - @param enabled Sets whether or not to enable stereo panning for remote users: + @param enabled Sets whether to enable stereo panning for remote users: - true: enables stereo panning. - false: disables stereo panning. @@ -7053,18 +8680,21 @@ class IRtcEngine { - < 0: Failure. */ virtual int setLocalVoiceEqualization(AUDIO_EQUALIZATION_BAND_FREQUENCY bandFrequency, int bandGain) = 0; - /** Sets the local voice reverberation. - - v2.4.0 adds the \ref agora::rtc::IRtcEngine::setLocalVoiceReverbPreset "setLocalVoiceReverbPreset" method, a more user-friendly method for setting the local voice reverberation. You can use this method to set the local reverberation effect, such as pop music, R&B, rock music, and hip-hop. - - @note You can call this method either before or after joining a channel. - - @param reverbKey Sets the reverberation key. See #AUDIO_REVERB_TYPE. - @param value Sets the value of the reverberation key. - - @return - - 0: Success. - - < 0: Failure. + /** Sets the local voice reverberation. + * + * As of v3.2.0, the SDK provides a more convenient method + * \ref IRtcEngine::setAudioEffectPreset "setAudioEffectPreset", which + * directly implements the popular music, R&B music, KTV and other preset + * reverb effects. + * + * @note You can call this method either before or after joining a channel. + * + * @param reverbKey Sets the reverberation key. See #AUDIO_REVERB_TYPE. + * @param value Sets the value of the reverberation key. See #AUDIO_REVERB_TYPE. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int setLocalVoiceReverb(AUDIO_REVERB_TYPE reverbKey, int value) = 0; /** Sets the local voice changer option. @@ -7089,17 +8719,14 @@ class IRtcEngine { - Do not use this method with \ref IRtcEngine::setLocalVoiceReverbPreset "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. - @param voiceChanger Sets the local voice changer option. The default value is #VOICE_CHANGER_OFF, which means the original voice. See details in #VOICE_CHANGER_PRESET - Gender-based beatification effect works best only when assigned a proper gender: - - For male: #GENERAL_BEAUTY_VOICE_MALE_MAGNETIC - - For female: #GENERAL_BEAUTY_VOICE_FEMALE_FRESH or #GENERAL_BEAUTY_VOICE_FEMALE_VITALITY - Failure to do so can lead to voice distortion. + @param voiceChanger Sets the local voice changer option. The default value is `VOICE_CHANGER_OFF`, + which means the original voice. See details in #VOICE_CHANGER_PRESET. @return - 0: Success. - < 0: Failure. Check if the enumeration is properly set. */ - virtual int setLocalVoiceChanger(VOICE_CHANGER_PRESET voiceChanger) = 0; + virtual int setLocalVoiceChanger(VOICE_CHANGER_PRESET voiceChanger) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Sets the local voice reverberation option, including the virtual stereo. * * @deprecated Deprecated from v3.2.0. Use \ref IRtcEngine::setAudioEffectPreset "setAudioEffectPreset" or @@ -7125,7 +8752,7 @@ class IRtcEngine { * - 0: Success. * - < 0: Failure. */ - virtual int setLocalVoiceReverbPreset(AUDIO_REVERB_PRESET reverbPreset) = 0; + virtual int setLocalVoiceReverbPreset(AUDIO_REVERB_PRESET reverbPreset) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Sets an SDK preset voice beautifier effect. * * @since v3.2.0 @@ -7372,8 +8999,8 @@ class IRtcEngine { * - 0: Success. * - < 0: Failure. */ - virtual int setLogFile(const char* filePath) = 0; - + virtual int setLogFile(const char* filePath) AGORA_DEPRECATED_ATTRIBUTE = 0; + /// @cond /** Specifies an SDK external log writer. The external log writer output all SDK operations during runtime if it exist. @@ -7398,6 +9025,7 @@ class IRtcEngine { - < 0: Failure. */ virtual int releaseLogWriter() = 0; + /// @endcond /** Sets the output log level of the SDK. @deprecated This method is deprecated from v3.3.0. Use `logConfig` in the \ref IRtcEngine::initialize "initialize" method instead. @@ -7415,7 +9043,7 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int setLogFilter(unsigned int filter) = 0; + virtual int setLogFilter(unsigned int filter) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Sets the size of a log file that the SDK outputs. * * @deprecated This method is deprecated from v3.3.0. Use `logConfig` in the \ref IRtcEngine::initialize "initialize" method instead. @@ -7437,7 +9065,8 @@ class IRtcEngine { * - 0: Success. * - < 0: Failure. */ - virtual int setLogFileSize(unsigned int fileSizeInKBytes) = 0; + virtual int setLogFileSize(unsigned int fileSizeInKBytes) AGORA_DEPRECATED_ATTRIBUTE = 0; + /// @cond /** Uploads all SDK log files. * * @since v3.3.0 @@ -7461,6 +9090,7 @@ class IRtcEngine { * - -12(ERR_TOO_OFTEN): The call frequency exceeds the limit. */ virtual int uploadLogFile(agora::util::AString& requestId) = 0; + /// @endcond /** @deprecated This method is deprecated, use the \ref IRtcEngine::setLocalRenderMode(RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode) "setLocalRenderMode" [2/2] method instead. Sets the local video display mode. @@ -7472,7 +9102,7 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int setLocalRenderMode(RENDER_MODE_TYPE renderMode) = 0; + virtual int setLocalRenderMode(RENDER_MODE_TYPE renderMode) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Updates the display mode of the local video view. @since v3.0.0 @@ -7503,7 +9133,7 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int setRemoteRenderMode(uid_t userId, RENDER_MODE_TYPE renderMode) = 0; + virtual int setRemoteRenderMode(uid_t userId, RENDER_MODE_TYPE renderMode) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Updates the display mode of the video view of a remote user. @since v3.0.0 @@ -7537,8 +9167,8 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int setLocalVideoMirrorMode(VIDEO_MIRROR_MODE_TYPE mirrorMode) = 0; - /** Sets the stream mode to the single-stream (default) or dual-stream mode. (`LIVE_BROADCASTING` only.) + virtual int setLocalVideoMirrorMode(VIDEO_MIRROR_MODE_TYPE mirrorMode) AGORA_DEPRECATED_ATTRIBUTE = 0; + /** Sets the stream mode to the single-stream (default) or dual-stream mode. If the dual-stream mode is enabled, the receiver can choose to receive the high stream (high-resolution and high-bitrate video stream), or the low stream (low-resolution and low-bitrate video stream). @@ -7547,6 +9177,10 @@ class IRtcEngine { @param enabled Sets the stream mode: - true: Dual-stream mode. - false: Single-stream mode. + + @return + - 0: Success. + - < 0: Failure. */ virtual int enableDualStreamMode(bool enabled) = 0; /** Sets the external audio source. @@ -7574,7 +9208,7 @@ class IRtcEngine { * it, and play it with the audio effects that you want. * * @note - * - Once you enable the external audio sink, the app will not retrieve any + * - Once you enable the external audio sink, the app will not get any * audio data from the * \ref agora::media::IAudioFrameObserver::onPlaybackAudioFrame "onPlaybackAudioFrame" callback. * - Ensure that you call this method before joining a channel. @@ -7644,62 +9278,71 @@ class IRtcEngine { - < 0: Failure. */ virtual int setMixedAudioFrameParameters(int sampleRate, int samplesPerCall) = 0; - /** Adjusts the capturing signal volume. - - @note You can call this method either before or after joining a channel. - - @param volume Volume. To avoid echoes and - improve call quality, Agora recommends setting the value of volume between - 0 and 100. If you need to set the value higher than 100, contact - support@agora.io first. - - 0: Mute. - - 100: Original volume. - - - @return - - 0: Success. - - < 0: Failure. + /** Adjusts the volume of the signal captured by the microphone. + * + * @note You can call this method either before or after joining a channel. + * + * @param volume The volume of the signal captured by the microphone. + * The value ranges between 0 and 400, including the following: + * - 0: Mute. + * - 100: (Default) Original volume. + * - 400: Four times the original volume with signal-clipping protection. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int adjustRecordingSignalVolume(int volume) = 0; /** Adjusts the playback signal volume of all remote users. - - @note - - This method adjusts the playback volume that is the mixed volume of all remote users. - - You can call this method either before or after joining a channel. - - (Since v2.3.2) To mute the local audio playback, call both the `adjustPlaybackSignalVolume` and \ref IRtcEngine::adjustAudioMixingVolume "adjustAudioMixingVolume" methods and set the volume as `0`. - - @param volume The playback volume of all remote users. To avoid echoes and - improve call quality, Agora recommends setting the value of volume between - 0 and 100. If you need to set the value higher than 100, contact - support@agora.io first. - - 0: Mute. - - 100: Original volume. - - @return - - 0: Success. - - < 0: Failure. + * + * @note + * - This method adjusts the playback volume that is the mixed volume of all + * remote users. + * - You can call this method either before or after joining a channel. + * - (Since v2.3.2) To mute the local audio playback, call both the + * `adjustPlaybackSignalVolume` and + * \ref IRtcEngine::adjustAudioMixingVolume "adjustAudioMixingVolume" + * methods and set the volume as `0`. + * + * @param volume The playback volume. The value ranges between 0 and 400, + * including the following: + * - 0: Mute. + * - 100: (Default) Original volume. + * - 400: Four times the original volume with signal-clipping protection. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int adjustPlaybackSignalVolume(int volume) = 0; - /** Adjusts the loopback signal volume. - - @note You can call this method either before or after joining a channel. - - @param volume Volume. To avoid quality issues, Agora recommends setting the value of volume - between 0 and 100. If you need to set the value higher than 100, contact support@agora.io first. - - 0: Mute. - - 100: Original volume. - - @return - - 0: Success. - - < 0: Failure. - */ + /** + * Adjusts the volume of the signal captured by the sound card. + * + * @since v3.4.0 + * + * After calling enableLoopbackRecording to enable loopback audio capturing, + * you can call this method to adjust the volume of the signal captured by + * the sound card. + * + * @note This method applies to Windows and macOS only. + * + * @param volume The volume of the signal captured by the sound card. + * The value ranges between 0 and 400, including the following: + * - 0: Mute. + * - 100: (Default) Original volume. + * - 400: Four times the original volume with signal-clipping protection. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ virtual int adjustLoopbackRecordingSignalVolume(int volume) = 0; /** @deprecated This method is deprecated. As of v3.0.0, the Native SDK automatically enables interoperability with the Web SDK, so you no longer need to call this method. Enables interoperability with the Agora Web SDK. @note - - This method applies only to the `LIVE_BROADCASTING` profile. In the `COMMUNICATION` profile, interoperability with the Agora Web SDK is enabled by default. + - This method applies to the `LIVE_BROADCASTING` profile. In the `COMMUNICATION` profile, interoperability with the Agora Web SDK is enabled by default. - If the channel has Web SDK users, ensure that you call this method, or the video of the Native user will be a black screen for the Web user. @param enabled Sets whether to enable/disable interoperability with the Agora Web SDK: @@ -7710,7 +9353,7 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int enableWebSdkInteroperability(bool enabled) = 0; + virtual int enableWebSdkInteroperability(bool enabled) AGORA_DEPRECATED_ATTRIBUTE = 0; // only for live broadcast /** **DEPRECATED** Sets the preferences for the high-quality video. (`LIVE_BROADCASTING` only). @@ -7793,60 +9436,56 @@ class IRtcEngine { */ virtual int switchCamera(CAMERA_DIRECTION direction) = 0; /// @endcond - /** Sets the default audio playback route. - - This method sets whether the received audio is routed to the earpiece or speakerphone by default before joining a channel. - If a user does not call this method, the audio is routed to the earpiece by default. If you need to change the default audio route after joining a channel, call the \ref IRtcEngine::setEnableSpeakerphone "setEnableSpeakerphone" method. - - The default setting for each profile: - - `COMMUNICATION`: In a voice call, the default audio route is the earpiece. In a video call, the default audio route is the speakerphone. If a user who is in the `COMMUNICATION` profile calls - the \ref IRtcEngine.disableVideo "disableVideo" method or if the user calls - the \ref IRtcEngine.muteLocalVideoStream "muteLocalVideoStream" and - \ref IRtcEngine.muteAllRemoteVideoStreams "muteAllRemoteVideoStreams" methods, the - default audio route switches back to the earpiece automatically. - - `LIVE_BROADCASTING`: Speakerphone. - - @note - - This method is for Android and iOS only. - - This method is applicable only to the `COMMUNICATION` profile. - - For iOS, this method only works in a voice call. - - Call this method before calling the \ref IRtcEngine::joinChannel "joinChannel" method. - - @param defaultToSpeaker Sets the default audio route: - - true: Route the audio to the speakerphone. If the playback device connects to the earpiece or Bluetooth, the audio cannot be routed to the speakerphone. - - false: (Default) Route the audio to the earpiece. If a headset is plugged in, the audio is routed to the headset. - - @return - - 0: Success. - - < 0: Failure. + /** + * Sets the default audio route. + * + * If the default audio route of the SDK (see *Set the Audio Route*) cannot meet your requirements, you can + * call this method to switch the default audio route. After successfully switching the audio route, the SDK + * triggers the \ref IRtcEngineEventHandler::onAudioRouteChanged "onAudioRouteChanged" callback to indicate the changes. + * + * @note + * - This method applies to Android and iOS only. + * - Call this method before calling \ref IRtcEngine::joinChannel "joinChannel". If you need to switch the audio + * route after joining a channel, call \ref IRtcEngine::setEnableSpeakerphone "setEnableSpeakerphone". + * - If the user uses an external audio playback device such as a Bluetooth or wired headset, this method does not + * take effect, and the SDK plays audio through the external device. When the user uses multiple external devices, + * the SDK plays audio through the last connected device. + * + * @param defaultToSpeaker Sets the default audio route as follows: + * - true: Set to the speakerphone. + * - false: Set to the earpiece. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int setDefaultAudioRouteToSpeakerphone(bool defaultToSpeaker) = 0; - /** Enables/Disables the audio playback route to the speakerphone. - - This method sets whether the audio is routed to the speakerphone or earpiece. - - See the default audio route explanation in the \ref IRtcEngine::setDefaultAudioRouteToSpeakerphone "setDefaultAudioRouteToSpeakerphone" method and check whether it is necessary to call this method. - - @note - - This method is for Android and iOS only. - - Ensure that you have successfully called the \ref IRtcEngine::joinChannel "joinChannel" method before calling this method. - - After calling this method, the SDK returns the \ref IRtcEngineEventHandler::onAudioRouteChanged "onAudioRouteChanged" callback to indicate the changes. - - This method does not take effect if a headset is used. - - Settings of \ref IRtcEngine::setAudioProfile "setAudioProfile" and \ref IRtcEngine::setChannelProfile "setChannelProfile" affect the call - result of `setEnableSpeakerphone`. The following are scenarios where `setEnableSpeakerphone` does not take effect: - - If you set `scenario` as `AUDIO_SCENARIO_GAME_STREAMING`, no user can change the audio playback route. - - If you set `scenario` as `AUDIO_SCENARIO_DEFAULT` or `AUDIO_SCENARIO_SHOWROOM`, the audience cannot change - the audio playback route. If there is only one broadcaster is in the channel, the broadcaster cannot change - the audio playback route either. - - If you set `scenario` as `AUDIO_SCENARIO_EDUCATION`, the audience cannot change the audio playback route. - - @param speakerOn Sets whether to route the audio to the speakerphone or earpiece: - - true: Route the audio to the speakerphone. If the playback device connects to the headset or Bluetooth, the audio cannot be routed to the speakerphone. - - false: Route the audio to the earpiece. If a headset is plugged in, the audio is routed to the headset. - - @return - - 0: Success. - - < 0: Failure. + /** + * Enables/Disables the audio route to the speakerphone. + * + * If the default audio route of the SDK (see *Set the Audio Route*) or the + * setting in \ref IRtcEngine::setDefaultAudioRouteToSpeakerphone "setDefaultAudioRouteToSpeakerphone" + * cannot meet your requirements, you can call this method to switch the current audio route. + * After successfully switching the audio route, the SDK triggers the + * \ref IRtcEngineEventHandler::onAudioRouteChanged "onAudioRouteChanged" callback to indicate the changes. + * + * This method only sets the audio route in the current channel and does not influence the default audio route. + * If the user leaves the current channel and joins another channel, the default audio route is used. + * + * @note + * - This method applies to Android and iOS only. + * - Call this method after calling joinChannel. + * - If the user uses an external audio playback device such as a Bluetooth or wired headset, this method + * does not take effect, and the SDK plays audio through the external device. When the user uses multiple external + * devices, the SDK plays audio through the last connected device. + * + * @param speakerOn Sets whether to enable the speakerphone or earpiece: + * - true: Enable the speakerphone. The audio route is the speakerphone. + * - false: Disable the speakerphone. The audio route is the earpiece. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int setEnableSpeakerphone(bool speakerOn) = 0; /** Enables in-ear monitoring (for Android and iOS only). @@ -7892,37 +9531,45 @@ class IRtcEngine { #endif #if (defined(__APPLE__) && TARGET_OS_IOS) - /** Sets the audio session’s operational restriction. - - The SDK and the app can both configure the audio session by default. The app may occasionally use other apps or third-party components to manipulate the audio session and restrict the SDK from doing so. This method allows the app to restrict the SDK’s manipulation of the audio session. - - You can call this method at any time to return the control of the audio sessions to the SDK. - - @note - - This method is for iOS only. - - This method restricts the SDK’s manipulation of the audio session. Any operation to the audio session relies solely on the app, other apps, or third-party components. - - You can call this method either before or after joining a channel. - - @param restriction The operational restriction (bit mask) of the SDK on the audio session. See #AUDIO_SESSION_OPERATION_RESTRICTION. - - @return - - 0: Success. - - < 0: Failure. + /** Sets the operational permission of the SDK on the audio session. + * + * The SDK and the app can both configure the audio session by default. If + * you need to only use the app to configure the audio session, this method + * restricts the operational permission of the SDK on the audio session. + * + * You can call this method either before or after joining a channel. Once + * you call this method to restrict the operational permission of the SDK + * on the audio session, the restriction takes effect when the SDK needs to + * change the audio session. + * + * @note + * - This method is for iOS only. + * - This method does not restrict the operational permission of the app on + * the audio session. + * + * @param restriction The operational permission of the SDK on the audio session. + * See #AUDIO_SESSION_OPERATION_RESTRICTION. This parameter is in bit mask + * format, and each bit corresponds to a permission. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int setAudioSessionOperationRestriction(AUDIO_SESSION_OPERATION_RESTRICTION restriction) = 0; #endif #if (defined(__APPLE__) && TARGET_OS_MAC && !TARGET_OS_IPHONE) || defined(_WIN32) + /** Enables loopback audio capturing. - If you enable loopback audio capturing, the output of the sound card is mixed into the audio stream sent to the other end. + If you enable loopback audio capturing, the output of the sound card is mixed into the audio stream sent to the other end. - @note You can call this method either before or after joining a channel. + @note You can call this method either before or after joining a channel. - @param enabled Sets whether to enable/disable loopback capturing. - - true: Enable loopback capturing. - - false: (Default) Disable loopback capturing. - @param deviceName Pointer to the device name of the sound card. The default value is NULL (the default sound card). + @param enabled Sets whether to enable/disable loopback capturing. + - true: Enable loopback capturing. + - false: (Default) Disable loopback capturing. + @param deviceName Pointer to the device name of the sound card. The default value is NULL (the default sound card). @note - This method is for macOS and Windows only. @@ -7930,15 +9577,50 @@ class IRtcEngine { */ virtual int enableLoopbackRecording(bool enabled, const char* deviceName = NULL) = 0; + /** + * Gets a list of shareable screens and windows. + * + * @since v3.5.2 + * + * You can call this method before sharing a screen or window to get a list of shareable screens and windows, which + * enables a user to use thumbnails in the list to easily choose a particular screen or window to share. This list + * also contains important information such as window ID and screen ID, with which you can + * call \ref IRtcEngine::startScreenCaptureByWindowId "startScreenCaptureByWindowId" or + * \ref IRtcEngine::startScreenCaptureByDisplayId "startScreenCaptureByDisplayId" to start the sharing. + * + * @note This method applies to macOS and Windows only. + * + * @param thumbSize The target size of the screen or window thumbnail. The width and height are in pixels. See SIZE. + * The SDK scales the original image to make the length of the longest side of the image the same as that of the + * target size without distorting the original image. For example, if the original image is 400 × 300 and `thumbSize` + * is 100 × 100, the actual size of the thumbnail is 100 × 75. If the target size is larger than the original size, + * the thumbnail is the original image and the SDK does not scale it. + * @param iconSize The target size of the icon corresponding to the application program. The width and height are in + * pixels. See SIZE. The SDK scales the original image to make the length of the longest side of the image the same + * as that of the target size without distorting the original image. For example, if the original image is 400 × 300 + * and `iconSize` is 100 × 100, the actual size of the icon is 100 × 75. If the target size is larger than the + * original size, the icon is the original image and the SDK does not scale it. + * @param includeScreen Whether the SDK returns screen information in addition to window information: + * - true: The SDK returns screen and window information. + * - false: The SDK returns window information only. + * + * @return IScreenCaptureSourceList + */ + virtual IScreenCaptureSourceList* getScreenCaptureSources(const SIZE& thumbSize, const SIZE& iconSize, const bool includeScreen) = 0; -#if (defined(__APPLE__) && TARGET_OS_MAC && !TARGET_OS_IPHONE) /** Shares the whole or part of a screen by specifying the display ID. * * @note - * - This method is for macOS only. + * - This method is for macOS and Windows only. * - Ensure that you call this method after joining a channel. * - * @param displayId The display ID of the screen to be shared. This parameter specifies which screen you want to share. + * @warning On Windows platforms, if the user device is connected to another display, to avoid screen sharing issues, + * use `startScreenCaptureByDisplayId` to start sharing instead of + * using \ref IRtcEngine::startScreenCaptureByScreenRect "startScreenCaptureByScreenRect". + * + * @param displayId The display ID of the screen to be shared. Use this parameter to specify which screen you want to + * share. For more information on how to get the display ID, see the advanced feature guide *Share the Screen* or get + * the display ID from `sourceId` returned by \ref IRtcEngine::getScreenCaptureSources "getScreenCaptureSources". * @param regionRect (Optional) Sets the relative location of the region to the screen. NIL means sharing the whole screen. See Rectangle. If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen. * @param 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 `videoDimension` to calculate the charges. * For details, see descriptions in ScreenCaptureParameters. @@ -7950,7 +9632,6 @@ class IRtcEngine { * - #ERR_INVALID_ARGUMENT: The argument is invalid. */ virtual int startScreenCaptureByDisplayId(unsigned int displayId, const Rectangle& regionRect, const ScreenCaptureParameters& captureParams) = 0; -#endif #if defined(_WIN32) /** Shares the whole or part of a screen by specifying the screen rect. @@ -7959,6 +9640,10 @@ class IRtcEngine { * - Ensure that you call this method after joining a channel. * - Applies to the Windows platform only. * + * @warning On Windows platforms, if the user device is connected to another display, to avoid screen sharing issues, + * use \ref IRtcEngine::startScreenCaptureByDisplayId "startScreenCaptureByDisplayId" to start sharing instead of + * using \ref IRtcEngine::startScreenCaptureByScreenRect "startScreenCaptureByScreenRect". + * * @param screenRect Sets the relative location of the screen to the virtual screen. For information on how to get screenRect, see the advanced guide *Share Screen*. * @param regionRect (Optional) Sets the relative location of the region to the screen. NULL means sharing the whole screen. See Rectangle. If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen. * @param captureParams The screen sharing encoding parameters. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. @@ -7967,7 +9652,7 @@ class IRtcEngine { * @return * - 0: Success. * - < 0: Failure: - * - #ERR_INVALID_ARGUMENT : The argument is invalid. + * - #ERR_INVALID_ARGUMENT: The argument is invalid. */ virtual int startScreenCaptureByScreenRect(const Rectangle& screenRect, const Rectangle& regionRect, const ScreenCaptureParameters& captureParams) = 0; #endif @@ -8192,10 +9877,8 @@ class IRtcEngine { - < 0: Failure. */ virtual int updateScreenCaptureRegion(const Rect* rect) = 0; - #endif -#if defined(_WIN32) /** Sets a custom video source. * * During real-time communication, the Agora SDK enables the default video input device, that is, the built-in camera to @@ -8211,9 +9894,8 @@ class IRtcEngine { * - false: The custom video source is not added to the SDK. */ virtual bool setVideoSource(IVideoSource* source) = 0; -#endif - /** Retrieves the current call ID. + /** Gets the current call ID. When a user joins a channel on a client, a @p callId is generated to identify the call from the client. Feedback methods, such as \ref IRtcEngine::rate "rate" and \ref IRtcEngine::complain "complain", must be called after the call ends to submit feedback to the SDK. @@ -8257,7 +9939,7 @@ class IRtcEngine { */ virtual int complain(const char* callId, const char* description) = 0; - /** Retrieves the SDK version number. + /** Gets the SDK version number. @param build Pointer to the build number. @return The version of the current SDK in the string format. For example, 2.3.1. @@ -8318,7 +10000,7 @@ class IRtcEngine { /** Stops the last-mile network probe test. */ virtual int stopLastmileProbeTest() = 0; - /** Retrieves the warning or error description. + /** Gets the warning or error description. @param code Warning code or error code returned in the \ref agora::rtc::IRtcEngineEventHandler::onWarning "onWarning" or \ref agora::rtc::IRtcEngineEventHandler::onError "onError" callback. @@ -8326,9 +10008,9 @@ class IRtcEngine { */ virtual const char* getErrorDescription(int code) = 0; - /** **DEPRECATED** Enables built-in encryption with an encryption password before users join a channel. + /** Enables built-in encryption with an encryption password before users join a channel. - Deprecated as of v3.1.0. Use the \ref agora::rtc::IRtcEngine::enableEncryption "enableEncryption" instead. + @deprecated Deprecated as of v3.1.0. Use the \ref agora::rtc::IRtcEngine::enableEncryption "enableEncryption" instead. All users in a channel must use the same encryption password. The encryption password is automatically cleared once a user leaves the channel. @@ -8344,9 +10026,9 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int setEncryptionSecret(const char* secret) = 0; + virtual int setEncryptionSecret(const char* secret) AGORA_DEPRECATED_ATTRIBUTE = 0; - /** **DEPRECATED** Sets the built-in encryption mode. + /** Sets the built-in encryption mode. @deprecated Deprecated as of v3.1.0. Use the \ref agora::rtc::IRtcEngine::enableEncryption "enableEncryption" instead. @@ -8368,7 +10050,7 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int setEncryptionMode(const char* encryptionMode) = 0; + virtual int setEncryptionMode(const char* encryptionMode) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Enables/Disables the built-in encryption. * @@ -8376,9 +10058,18 @@ class IRtcEngine { * * 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 a 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. + * After a user leaves the channel, the SDK automatically disables the built-in encryption. + * To re-enable the built-in encryption, call this method before the user joins the channel again. * - * @note If you enable the built-in encryption, you cannot use the RTMP or RTMPS streaming function. + * As of v3.4.5, Agora recommends using either the `AES_128_GCM2` or `AES_256_GCM2` encryption mode, + * both of which support adding a salt and are more secure. For details, see *Media Stream Encryption*. + * + * @warning All users in the same channel must use the same encryption mode, encryption key, and salt; otherwise, + * users cannot communicate with each other. + * + * @note + * - If you enable the built-in encryption, you cannot use the RTMP or RTMPS streaming function. + * - To enhance security, Agora recommends using a new key and salt every time you enable the media stream encryption. * * @param enabled Whether to enable the built-in encryption: * - true: Enable the built-in encryption. @@ -8401,7 +10092,7 @@ class IRtcEngine { @note - The size of the packet sent to the network after processing should not exceed 1200 bytes, otherwise, the packet may fail to be sent. - Ensure that both receivers and senders call this method, otherwise, you may meet undefined behaviors such as no voice and black screen. - - When you use CDN live streaming, recording or storage functions, Agora doesn't recommend calling this method. + - When you use CDN live streaming and recording functions, Agora doesn't recommend calling this method. - Call this method before joining a channel. @param observer Pointer to the registered packet observer. See IPacketObserver. @@ -8434,7 +10125,7 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int createDataStream(int* streamId, bool reliable, bool ordered) = 0; + virtual int createDataStream(int* streamId, bool reliable, bool ordered) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Creates a data stream. * * @since v3.3.0 @@ -8478,6 +10169,8 @@ class IRtcEngine { /** Publishes the local stream to a specified CDN live address. (CDN live only.) + @deprecated This method is deprecated as of v3.6.0. See [Release Notes](https://docs.agora.io/en/Interactive%20Broadcast/release_windows_video?platform=Windows) for an alternative solution. + The SDK returns the result of this method call in the \ref IRtcEngineEventHandler::onStreamPublished "onStreamPublished" callback. The \ref agora::rtc::IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onRtmpStreamingStateChanged "onRtmpStreamingStateChanged" callback on the local client to report the state of adding a local stream to the CDN. @@ -8498,10 +10191,12 @@ class IRtcEngine { - #ERR_INVALID_ARGUMENT (-2): The CDN streaming URL is NULL or has a string length of 0. - #ERR_NOT_INITIALIZED (-7): You have not initialized the RTC engine when publishing the stream. */ - virtual int addPublishStreamUrl(const char* url, bool transcodingEnabled) = 0; + virtual int addPublishStreamUrl(const char* url, bool transcodingEnabled) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Removes an RTMP or RTMPS stream from the CDN. (CDN live only.) + @deprecated This method is deprecated as of v3.6.0. See [Release Notes](https://docs.agora.io/en/Interactive%20Broadcast/release_windows_video?platform=Windows) for an alternative solution. + This method removes the CDN streaming URL (added by the \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method) from a CDN live stream. The SDK returns the result of this method call in the \ref IRtcEngineEventHandler::onStreamUnpublished "onStreamUnpublished" callback. The \ref agora::rtc::IRtcEngine::removePublishStreamUrl "removePublishStreamUrl" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onRtmpStreamingStateChanged "onRtmpStreamingStateChanged" callback on the local client to report the state of removing an RTMP or RTMPS stream from the CDN. @@ -8517,10 +10212,12 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int removePublishStreamUrl(const char* url) = 0; + virtual int removePublishStreamUrl(const char* url) AGORA_DEPRECATED_ATTRIBUTE = 0; /** Sets the video layout and audio settings for CDN live. (CDN live only.) + @deprecated This method is deprecated as of v3.6.0. See [Release Notes](https://docs.agora.io/en/Interactive%20Broadcast/release_windows_video?platform=Windows) for an alternative solution. + The SDK triggers the \ref agora::rtc::IRtcEngineEventHandler::onTranscodingUpdated "onTranscodingUpdated" callback when you call the `setLiveTranscoding` method to update the transcoding setting. @note @@ -8536,7 +10233,104 @@ class IRtcEngine { - 0: Success. - < 0: Failure. */ - virtual int setLiveTranscoding(const LiveTranscoding& transcoding) = 0; + virtual int setLiveTranscoding(const LiveTranscoding& transcoding) AGORA_DEPRECATED_ATTRIBUTE = 0; + /** + * Starts pushing media streams to a CDN without transcoding. + * + * @since v3.6.0 + * + * You can call this method to push a live audio-and-video stream to the specified CDN address. This method can push + * media streams to only one CDN address at a time, so if you need to push streams to multiple addresses, call this + * method multiple times. + * + * After you call this method, the SDK triggers the \ref IRtcEngineEventHandler::onRtmpStreamingStateChanged "onRtmpStreamingStateChanged" + * callback on the local client to report the state of the streaming. + * + * @note + * - Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in *Push Streams to CDN*. + * - Call this method after joining a channel. + * - Only hosts in the `LIVE_BROADCASTING` profile can call this method. + * - If you want to retry pushing streams after a failed push, make sure to call \ref IRtcEngine::stopRtmpStream "stopRtmpStream" first, + * then call this method to retry pushing streams; otherwise, the SDK returns the same error code as the last failed push. + * - If you want to push media streams in the RTMPS protocol to CDN, call \ref IRtcEngine::startRtmpStreamWithTranscoding "startRtmpStreamWithTranscoding" + * instead of \ref IRtcEngine::startRtmpStreamWithoutTranscoding "startRtmpStreamWithoutTranscoding". + * + * @param url The address of the CDN live streaming. The format is RTMP. The character length cannot exceed 1024 bytes. + * Special characters such as Chinese characters are not supported. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `ERR_INVALID_ARGUMENT(-2)`: url is null or the string length is 0. + * - `ERR_NOT_INITIALIZED(-7)`: The SDK is not initialized before calling this method. + */ + virtual int startRtmpStreamWithoutTranscoding(const char* url) = 0; + /** + * Starts pushing media streams to a CDN and sets the transcoding configuration. + * + * @since v3.6.0 + * + * You can call this method to push a live audio-and-video stream to the specified CDN address and set the transcoding + * configuration. This method can push media streams to only one CDN address at a time, so if you need to push streams to + * multiple addresses, call this method multiple times. + * + * After you call this method, the SDK triggers the \ref IRtcEngineEventHandler::onRtmpStreamingStateChanged "onRtmpStreamingStateChanged" + * callback on the local client to report the state of the streaming. + * + * @note + * - Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in *Push Streams to CDN*. + * - Call this method after joining a channel. + * - Only hosts in the `LIVE_BROADCASTING` profile can call this method. + * - If you want to retry pushing streams after a failed push, make sure to call \ref IRtcEngine::stopRtmpStream "stopRtmpStream" first, + * then call this method to retry pushing streams; otherwise, the SDK returns the same error code as the last failed push. + * - If you want to push media streams in the RTMPS protocol to CDN, call \ref IRtcEngine::startRtmpStreamWithTranscoding "startRtmpStreamWithTranscoding" + * instead of \ref IRtcEngine::startRtmpStreamWithoutTranscoding "startRtmpStreamWithoutTranscoding". + * + * @param url The address of the CDN live streaming. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. + * Special characters such as Chinese characters are not supported. + * @param transcoding The transcoding configuration for CDN live streaming. See LiveTranscoding. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `ERR_INVALID_ARGUMENT(-2)`: url is null or the string length is 0. + * - `ERR_NOT_INITIALIZED(-7)`: The SDK is not initialized before calling this method. + */ + virtual int startRtmpStreamWithTranscoding(const char* url, const LiveTranscoding& transcoding) = 0; + /** + * Updates the transcoding configuration. + * + * @since v3.6.0 + * + * After you start pushing media streams to CDN with transcoding, you can dynamically update the transcoding configuration according to the scenario. + * The SDK triggers the \ref IRtcEngineEventHandler::onTranscodingUpdated "onTranscodingUpdated" callback after the + * transcoding configuration is updated. + * + * @param transcoding The transcoding configuration for CDN live streaming. See LiveTranscoding. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int updateRtmpTranscoding(const LiveTranscoding& transcoding) = 0; + /** + * Stops pushing media streams to a CDN. + * + * @since v3.6.0 + * + * You can call this method to stop the live stream on the specified CDN address. + * This method can stop pushing media streams to only one CDN address at a time, so if you need to stop pushing streams to multiple addresses, call this method multiple times. + * + * After you call this method, the SDK triggers the \ref IRtcEngineEventHandler::onRtmpStreamingStateChanged "onRtmpStreamingStateChanged" callback on the local client to report the state of the streaming. + * + * @param url The address of the CDN live streaming. The format is RTMP or RTMPS. + * The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int stopRtmpStream(const char* url) = 0; /** **DEPRECATED** Adds a watermark image to the local video or CDN live stream. @@ -8562,29 +10356,31 @@ class IRtcEngine { virtual int addVideoWatermark(const RtcImage& watermark) = 0; /** Adds a watermark image to the local video. - - This method adds a PNG watermark image to the local video in the live streaming. Once the watermark image is added, all the audience in the channel (CDN audience included), - and the capturing device can see and capture it. Agora supports adding only one watermark image onto the local video, and the newly watermark image replaces the previous one. - - The watermark position depends on the settings in the \ref IRtcEngine::setVideoEncoderConfiguration "setVideoEncoderConfiguration" method: - - If the orientation mode of the encoding video is #ORIENTATION_MODE_FIXED_LANDSCAPE, or the landscape mode in #ORIENTATION_MODE_ADAPTIVE, the watermark uses the landscape orientation. - - If the orientation mode of the encoding video is #ORIENTATION_MODE_FIXED_PORTRAIT, or the portrait mode in #ORIENTATION_MODE_ADAPTIVE, the watermark uses the portrait orientation. - - When setting the watermark position, the region must be less than the dimensions set in the `setVideoEncoderConfiguration` method. Otherwise, the watermark image will be cropped. - - @note - - Ensure that you have called the \ref agora::rtc::IRtcEngine::enableVideo "enableVideo" method to enable the video module before calling this method. - - If you only want to add a watermark image to the local video for the audience in the CDN live streaming channel to see and capture, you can call this method or the \ref agora::rtc::IRtcEngine::setLiveTranscoding "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 \ref agora::rtc::IRtcEngine::startPreview "startPreview" method, you can use the `visibleInPreview` member in the WatermarkOptions class to set whether or not the watermark is visible in preview. - - If you have enabled the mirror mode for the local video, the watermark on the local video is also mirrored. To avoid mirroring the watermark, Agora recommends that you do not use the mirror and watermark functions for the local video at the same time. You can implement the watermark function in your application layer. - - @param 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. - @param options Pointer to the watermark's options to be added. See WatermarkOptions for more infomation. - - @return - - 0: Success. - - < 0: Failure. + * + * This method adds a PNG watermark image to the local video in the live streaming. Once the watermark image is added, all the audience in the channel (CDN audience included), + * and the capturing device can see and capture it. Agora supports adding only one watermark image onto the local video, and the newly watermark image replaces the previous one. + * + * The watermark position depends on the settings in the \ref IRtcEngine::setVideoEncoderConfiguration "setVideoEncoderConfiguration" method: + * - If the orientation mode of the encoding video is #ORIENTATION_MODE_FIXED_LANDSCAPE, or the landscape mode in #ORIENTATION_MODE_ADAPTIVE, the watermark uses the landscape orientation. + * - If the orientation mode of the encoding video is #ORIENTATION_MODE_FIXED_PORTRAIT, or the portrait mode in #ORIENTATION_MODE_ADAPTIVE, the watermark uses the portrait orientation. + * - When setting the watermark position, the region must be less than the dimensions set in the `setVideoEncoderConfiguration` method. Otherwise, the watermark image will be cropped. + * + * @note + * - Ensure that you have called the \ref agora::rtc::IRtcEngine::enableVideo "enableVideo" method to enable the video module before calling this method. + * - If you only want to add a watermark image to the local video for the audience in the CDN live streaming channel to see and capture, you can call this method or the \ref agora::rtc::IRtcEngine::setLiveTranscoding "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 \ref agora::rtc::IRtcEngine::startPreview "startPreview" method, you can use the `visibleInPreview` member in the WatermarkOptions class to set whether or not the watermark is visible in preview. + * - If you have enabled the mirror mode for the local video, the watermark on the local video is also mirrored. To avoid mirroring the watermark, Agora recommends that you do not use the mirror and watermark functions for the local video at the same time. You can implement the watermark function in your application layer. + * + * @param 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. + * On Android, Agora recommends passing a URI address or the path starts with `/assets/` in this parameter + * @param options Pointer to the watermark's options to be added. See WatermarkOptions for more infomation. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int addVideoWatermark(const char* watermarkUrl, const WatermarkOptions& options) = 0; @@ -8598,14 +10394,82 @@ class IRtcEngine { /** Enables/Disables image enhancement and sets the options. * - * @note Call this method after calling the \ref IRtcEngine::enableVideo "enableVideo" method. + * @note + * - Call this method after calling the \ref IRtcEngine::enableVideo "enableVideo" method. + * - On Android, this method applies to Android 5.0 or later. + * - Agora has updated the Agora image enhancement algorithm from v3.6.0 to enhance image enhancement effects and support sharpness adjustment. + * If you want to experience optimized image enhancement effects or set the sharpness, integrate the following dynamic library into the project before calling this method: + * - Android: `libagora_video_process_extension.so` + * - iOS: `AgoraVideoProcessExtension.xcframework` + * - macOS: `AgoraVideoProcessExtension.framework` + * - Windows: `libagora_video_process_extension.dll` + * + * @param enabled Determines whether to enable image enhancement: + * - true: Enables image enhancement. + * - false: Disables image enhancement. + * @param options The image enhancement option. See BeautyOptions. * - * @param enabled Sets whether or not to enable image enhancement: - * - true: enables image enhancement. - * - false: disables image enhancement. - * @param options Sets the image enhancement option. See BeautyOptions. + * @return + * - 0: Success. + * - < 0: Failure. + * - `-4(ERR_NOT_SUPPORTED)`: The system version is earlier than Android 5.0, which does not support this function. */ virtual int setBeautyEffectOptions(bool enabled, BeautyOptions options) = 0; + virtual int setLowlightEnhanceOptions(bool enabled, LowLightEnhanceOptions options) = 0; + virtual int setVideoDenoiserOptions(bool enabled, VideoDenoiserOptions options) = 0; + virtual int setColorEnhanceOptions(bool enabled, ColorEnhanceOptions options) = 0; + /** + * Enables/Disables the virtual background. (beta feature) + * + * Support for macOS and Windows as of v3.4.5 and Android and iOS as of v3.5.0. + * + * After enabling the virtual background feature, you can replace the original background image of the local user + * with a custom background image. After the replacement, all users in the channel can see the custom background + * image. You can find out from the + * \ref IRtcEngineEventHandler::onVirtualBackgroundSourceEnabled "onVirtualBackgroundSourceEnabled" callback + * whether the virtual background is successfully enabled or the cause of any errors. + * + * @note + * - Before calling this method, ensure that you have integrated the following dynamic library into your project: + * - Android: `libagora_segmentation_extension.so` + * - iOS: `AgoraVideoSegmentationExtension.xcframework` + * - macOS: `AgoraVideoSegmentationExtension.framework` + * - Windows: `libagora_segmentation_extension.dll` + * - Call this method after \ref IRtcEngine::enableVideo "enableVideo". + * - This functions requires a high-performance device. Agora recommends that you use this function on the + * following devices: + * - Android: Devices with the following chips: + * - Snapdragon 700 series 750G and later + * - Snapdragon 800 series 835 and later + * - Dimensity 700 series 720 and later + * - Kirin 800 series 810 and later + * - Kirin 900 series 980 and later + * - iOS: Devices with an A9 chip and better, as follows: + * - iPhone 6S and later + * - iPad Air (3rd generation) and later + * - iPad (5th generation) and later + * - iPad Pro (1st generation) and later + * - iPad mini (5th generation) and later + * - macOS and Windows: Devices with an i5 CPU and better + * - Agora recommends that you use this function in scenarios that meet the following conditions: + * - A high-definition camera device is used, and the environment is uniformly lit. + * - The captured video image is uncluttered, the user's portrait is half-length and largely unobstructed, and the + * background is a single color that differs from the color of the user's clothing. + * - The virtual background feature does not support video in the Texture format or video obtained from custom video capture by the Push method. + * + * @param enabled Sets whether to enable the virtual background: + * - true: Enable. + * - false: Disable. + * @param backgroundSource The custom background image. See VirtualBackgroundSource. + * Note: To adapt the resolution of the custom background image to the resolution of the SDK capturing video, + * the SDK scales and crops + * the custom background image while ensuring that the content of the custom background image is not distorted. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int enableVirtualBackground(bool enabled, VirtualBackgroundSource backgroundSource) = 0; /** Adds a voice or video stream URL address to the live streaming. @@ -8693,10 +10557,9 @@ class IRtcEngine { * "onChannelMediaRelayEvent" callback with the * #RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL (7) state code. * - * @note - * Call this method after the - * \ref startChannelMediaRelay() "startChannelMediaRelay" method to update - * the destination channel. + * @note Call this method after successfully calling the \ref startChannelMediaRelay() "startChannelMediaRelay" method + * and receiving the \ref IRtcEngineEventHandler::onChannelMediaRelayStateChanged "onChannelMediaRelayStateChanged" (RELAY_STATE_RUNNING, RELAY_OK) callback; + * otherwise, this method call fails. * * @param configuration The media stream relay configuration: * ChannelMediaRelayConfiguration. @@ -8706,6 +10569,47 @@ class IRtcEngine { * - < 0: Failure. */ virtual int updateChannelMediaRelay(const ChannelMediaRelayConfiguration& configuration) = 0; + + /** + * Pauses the media stream relay to all destination channels. + * + * @since v3.5.1 + * + * After the cross-channel media stream relay starts, you can call this method + * to pause relaying media streams to all destination channels; after the pause, + * if you want to resume the relay, call \ref IRtcEngine::resumeAllChannelMediaRelay "resumeAllChannelMediaRelay". + * + * After a successful method call, the SDK triggers the + * \ref IRtcEngineEventHandler::onChannelMediaRelayEvent "onChannelMediaRelayEvent" + * callback to report whether the media stream relay is successfully paused. + * + * @note Call this method after the \ref IRtcEngine::startChannelMediaRelay "startChannelMediaRelay" method. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int pauseAllChannelMediaRelay() = 0; + + /** Resumes the media stream relay to all destination channels. + * + * @since v3.5.1 + * + * After calling the \ref IRtcEngine::pauseAllChannelMediaRelay "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 + * \ref IRtcEngineEventHandler::onChannelMediaRelayEvent "onChannelMediaRelayEvent" + * callback to report whether the media stream relay is successfully resumed. + * + * @note Call this method after the \ref IRtcEngine::pauseAllChannelMediaRelay "pauseAllChannelMediaRelay" method. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int resumeAllChannelMediaRelay() = 0; + /** Stops the media stream relay. * * Once the relay stops, the host quits all the destination @@ -8764,81 +10668,88 @@ class IRtcEngine { @return #CONNECTION_STATE_TYPE. */ virtual CONNECTION_STATE_TYPE getConnectionState() = 0; - /// @cond - /** Enables/Disables the super-resolution algorithm for a remote user's video stream. + + /** Enables/Disables the super resolution feature for a remote user's video. (beta feature) * - * @since v3.2.0 + * @since v3.5.1 * - * The algorithm effectively improves the resolution of the specified remote user's video stream. When the original - * resolution of the remote video stream is a × b pixels, you can receive and render the stream at a higher - * resolution (2a × 2b pixels) by enabling the algorithm. + * This feature effectively boosts the resolution of a remote user's video seen by the local + * user. If the original resolution of a remote user's video is a × b, the local user's device + * can render the remote video at a resolution of 2a × 2b after you enable this feature. * * After calling this method, the SDK triggers the - * \ref IRtcEngineEventHandler::onUserSuperResolutionEnabled "onUserSuperResolutionEnabled" callback to report - * whether you have successfully enabled the super-resolution algorithm. - * - * @warning The super-resolution algorithm requires extra system resources. - * To balance the visual experience and system usage, the SDK poses the following restrictions: - * - The algorithm can only be used for a single user at a time. - * - On the Android platform, the original resolution of the remote video must not exceed 640 × 360 pixels. - * - On the iOS platform, the original resolution of the remote video must not exceed 640 × 480 pixels. - * If you exceed these limitations, the SDK triggers the \ref IRtcEngineEventHandler::onWarning "onWarning" - * callback with the corresponding warning codes: - * - #WARN_SUPER_RESOLUTION_STREAM_OVER_LIMITATION (1610): The origin resolution of the remote video is beyond the range where the super-resolution algorithm can be applied. - * - #WARN_SUPER_RESOLUTION_USER_COUNT_OVER_LIMITATION (1611): Another user is already using the super-resolution algorithm. - * - #WARN_SUPER_RESOLUTION_DEVICE_NOT_SUPPORTED (1612): The device does not support the super-resolution algorithm. + * \ref IRtcEngineEventHandler::onUserSuperResolutionEnabled "onUserSuperResolutionEnabled" + * callback to report whether you have successfully enabled super resolution. + * + * @warning The super resolution feature requires extra system resources. To balance the visual experience and system consumption, the SDK poses the following restrictions: + * - This feature can only be enabled for a single remote user. + * - The original resolution of the remote user's video cannot exceed a certain range. If the local user use super resolution on Android, + * the original resolution of the remote user's video cannot exceed 640 × 360 pixels; if the local user use super resolution on iOS, + * the original resolution of the remote user's video cannot exceed 640 × 480 pixels. + * + * @warning If you exceed these limitations, the SDK triggers the + * \ref IRtcEngineEventHandler::onWarning "onWarning" callback and returns the corresponding warning codes: + * - #WARN_SUPER_RESOLUTION_STREAM_OVER_LIMITATION (1610): The original resolution of the remote user's video is beyond + * the range where super resolution can be applied. + * - #WARN_SUPER_RESOLUTION_USER_COUNT_OVER_LIMITATION (1611): Super resolution is already being used to boost another + * remote user's video. + * - #WARN_SUPER_RESOLUTION_DEVICE_NOT_SUPPORTED (1612): The device does not support using super resolution. * * @note - * - This method applies to Android and iOS only. - * - Requirements for the user's device: - * - Android: The following devices are known to support the method: - * - VIVO: V1821A, NEX S, 1914A, 1916A, and 1824BA - * - OPPO: PCCM00 + * - This method is for Android and iOS only. + * - Before calling this method, ensure that you have integrated the following dynamic library into your project: + * - Android: `libagora_super_resolution_extension.so` + * - iOS: `AgoraSuperResolutionExtension.xcframework` + * - Because this method has certain system performance requirements, Agora recommends that you use the following devices or better: + * - Android: + * - VIVO: V1821A, NEX S, 1914A, 1916A, 1962A, 1824BA, X60, X60 Pro + * - OPPO: PCCM00, Find X3 * - OnePlus: A6000 - * - Xiaomi: Mi 8, Mi 9, MIX3, and Redmi K20 Pro - * - SAMSUNG: SM-G9600, SM-G9650, SM-N9600, SM-G9708, SM-G960U, and SM-G9750 - * - HUAWEI: SEA-AL00, ELE-AL00, VOG-AL00, YAL-AL10, HMA-AL00, and EVR-AN00 - * - iOS: This method is supported on devices running iOS 12.0 or later. The following - * device models are known to support the method: + * - Xiaomi: Mi 8, Mi 9, Mi 10, Mi 11, MIX3, Redmi K20 Pro + * - SAMSUNG: SM-G9600, SM-G9650, SM-N9600, SM-G9708, SM-G960U, SM-G9750, S20, S21 + * - HUAWEI: SEA-AL00, ELE-AL00, VOG-AL00, YAL-AL10, HMA-AL00, EVR-AN00, nova 4, nova 5 Pro, + * nova 6 5G, nova 7 5G, Mate 30, Mate 30 Pro, Mate 40, Mate 40 Pro, P40 P40 Pro, HUAWEI MediaPad M6, MatePad 10.8 + * - iOS (iOS 12.0 or later): * - iPhone XR * - iPhone XS * - iPhone XS Max * - iPhone 11 * - iPhone 11 Pro * - iPhone 11 Pro Max - * - iPad Pro 11-inch (3rd Generation) - * - iPad Pro 12.9-inch (3rd Generation) - * - iPad Air 3 (3rd Generation) - * - * @param userId The ID of the remote user. - * @param enable Whether to enable the super-resolution algorithm: - * - true: Enable the super-resolution algorithm. - * - false: Disable the super-resolution algorithm. + * - iPhone 12 + * - iPhone 12 mini + * - iPhone 12 Pro + * - iPhone 12 Pro Max + * - iPhone 12 SE (2nd generation) + * - iPad Pro 11-inch (3rd generation) + * - iPad Pro 12.9-inch (3rd generation) + * - iPad Air (3rd generation) + * - iPad Air (4th generation) + * + * @param userId The user ID of the remote user. + * @param enable Determines whether to enable super resolution for the remote user's video: + * - true: Enable super resolution. + * - false: Disable super resolution. * * @return * - 0: Success. * - < 0: Failure. - * - -158 (ERR_MODULE_SUPER_RESOLUTION_NOT_FOUND): You have not integrated the dynamic library for the super-resolution algorithm. + * - `-157 (ERR_MODULE_NOT_FOUND)`: The dynamic library for super resolution is not integrated. */ virtual int enableRemoteSuperResolution(uid_t userId, bool enable) = 0; - /// @endcond - - /** Registers the metadata observer. - - Registers the metadata observer. You need to implement the IMetadataObserver class and specify the metadata type in this method. A successful call of this method triggers the \ref agora::rtc::IMetadataObserver::getMaxMetadataSize "getMaxMetadataSize" callback. - This method enables you to add synchronized metadata in the video stream for more diversified interactive live streaming, such as sending shopping links, digital coupons, and online quizzes. + /** This method enables you to add synchronized metadata in the video stream for more diversified interactive live streaming, such as sending shopping links, digital coupons, and online quizzes. - @note - - Call this method before the joinChannel method. - - This method applies to the `LIVE_BROADCASTING` channel profile. + @note + - Call this method before the joinChannel method. + - This method applies to the `LIVE_BROADCASTING` channel profile. - @param observer The IMetadataObserver class. See the definition of IMetadataObserver for details. - @param type See \ref IMetadataObserver::METADATA_TYPE "METADATA_TYPE". The SDK supports VIDEO_METADATA (0) only for now. + @param observer The IMetadataObserver class. See the definition of IMetadataObserver for details. + @param type See \ref IMetadataObserver::METADATA_TYPE "METADATA_TYPE". The SDK supports VIDEO_METADATA (0) only for now. - @return - - 0: Success. - - < 0: Failure. - */ + @return + - 0: Success. + - < 0: Failure. + */ virtual int registerMediaMetadataObserver(IMetadataObserver* observer, IMetadataObserver::METADATA_TYPE type) = 0; /** Provides technical preview functionalities or special customizations by configuring the SDK with JSON options. @@ -8851,6 +10762,136 @@ class IRtcEngine { - < 0: Failure. */ virtual int setParameters(const char* parameters) = 0; + + // virtual int getMediaRecorder(IMediaRecorderObserver *observer, int sys_version = 0) = 0; + + // virtual int startRecording(const MediaRecorderConfiguration &config) = 0; + + // virtual int stopRecording() = 0; + + // virtual int releaseRecorder() = 0; + /** + * Customizes the local video renderer. (for Windows only) + * + * @since v3.5.0 + * + * During a real-time audio and video interaction, the Agora SDK enables the default renderer to render local video. + * If you want to customize the local video rendering, you can first customize the video renderer via the IVideoSink + * class, and then call this method to use the custom video renderer to render the local video. + * + * @note You can call this method either before or after joining a channel. + * + * @param videoSink The custom video renderer. See IVideoSink. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int setLocalVideoRenderer(IVideoSink* videoSink) = 0; + /** + * Customizes the remote video renderer. (for Windows only) + * + * @since v3.5.0 + * + * During a real-time audio and video interaction, the Agora SDK enables the default renderer to render remote video. + * If you want to customize the remote video rendering, you can first customize the video renderer via the IVideoSink + * class, and then call this method to use the custom video renderer to render the remote video. + * + * @note You can call this method either before or after joining a channel. + * + * @param uid The user ID of the remote user. + * @param videoSink The custom video renderer. See IVideoSink. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int setRemoteVideoRenderer(uid_t uid, IVideoSink* videoSink) = 0; + /// @cond + virtual int setLocalAccessPoint(const LocalAccessPointConfiguration& config) = 0; + /// @endcond +#if defined(__ANDROID__) || (defined(__APPLE__) && TARGET_OS_IOS) + /** + * Sets whether to enable the flash. + * + * @since v3.5.1 + * + * @note + * - Call this method after the camera is started. + * - This method is for Android and iOS only. + * - On iPads with system version 15, even if \ref IRtcEngine::isCameraTorchSupported "isCameraTorchSupported" + * returns true, you might fail to successfully enable the flash by calling `setCameraTorchOn` due to + * system issues. + * + * @param isOn Determines whether to enable the flash: + * - true: Enable the flash. + * - false: Disable the flash. + * + * @return + * - 0: Success + * - < 0: Failure + */ + virtual int setCameraTorchOn(bool isOn) = 0; + /** + * Checks whether the device supports enabling the flash. + * + * @since v3.5.1 + * + * The SDK uses the front camera by default, so if you call `isCameraTorchSupported` directly, + * you can find out from the return value whether the device supports enabling the flash + * when using the front camera. If you want to check whether the device supports enabling the + * flash when using the rear camera, call \ref IRtcEngine::switchCamera "switchCamera" + * to switch the camera used by the SDK to the rear camera, and then call `isCameraTorchSupported`. + * + * @note + * - Call this method after the camera is started. + * - This method is for Android and iOS only. + * - On iPads with system version 15, even if `isCameraTorchSupported` returns true, you might + * fail to successfully enable the flash by calling \ref IRtcEngine::setCameraTorchOn "setCameraTorchOn" + * due to system issues. + * + * + * @return + * - true: The device supports enabling the flash. + * - false: The device does not support enabling the flash. + */ + virtual bool isCameraTorchSupported() = 0; +#endif + + /** + * Takes a snapshot of a video stream. + * + * @since v3.5.2 + * + * This method takes a snapshot of a video stream from the specified user, generates a JPG image, + * and saves it to the specified path. + * + * The method is asynchronous, and the SDK has not taken the snapshot when the method call returns. + * After a successful method call, the SDK triggers the \ref IRtcEngineEventHandler::onSnapshotTaken "onSnapshotTaken" + * callback to report whether the snapshot is successfully taken as well as the details of the snapshot taken. + * + * @note + * - Call this method after joining a channel. + * - If the video of the specified user is pre-processed, for example, added with watermarks or image enhancement + * effects, the generated snapshot also includes the pre-processing effects. + * + * @param channel The channel name. + * @param uid The user ID of the user. Set `uid` as 0 if you want to take a snapshot of the local user's video. + * @param filePath The local path (including the filename extensions) of the snapshot. For example, + * `C:\Users\\AppData\Local\Agora\\example.jpg` on Windows, + * `/App Sandbox/Library/Caches/example.jpg` on iOS, `～/Library/Logs/example.jpg` on macOS, and + * `/storage/emulated/0/Android/data//files/example.jpg` on Android. Ensure that the path you specify + * exists and is writable. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int takeSnapshot(const char* channel, uid_t uid, const char* filePath) = 0; + + /// @cond + virtual int enableContentInspect(bool enabled, const ContentInspectConfig& config) = 0; + /// @endcond }; class IRtcEngineParameter { @@ -8926,7 +10967,7 @@ class IRtcEngineParameter { */ virtual int setObject(const char* key, const char* value) = 0; - /** Retrieves the bool value of a specified key in the JSON format. + /** Gets the bool value of a specified key in the JSON format. @param key Pointer to the name of the key. @param value Pointer to the retrieved value. @@ -8937,7 +10978,7 @@ class IRtcEngineParameter { */ virtual int getBool(const char* key, bool& value) = 0; - /** Retrieves the int value of the JSON format. + /** Gets the int value of the JSON format. @param key Pointer to the name of the key. @param value Pointer to the retrieved value. @@ -8948,7 +10989,7 @@ class IRtcEngineParameter { */ virtual int getInt(const char* key, int& value) = 0; - /** Retrieves the unsigned int value of a specified key in the JSON format. + /** Gets the unsigned int value of a specified key in the JSON format. @param key Pointer to the name of the key. @param value Pointer to the retrieved value. @@ -8958,7 +10999,7 @@ class IRtcEngineParameter { */ virtual int getUInt(const char* key, unsigned int& value) = 0; - /** Retrieves the double value of a specified key in the JSON format. + /** Gets the double value of a specified key in the JSON format. @param key Pointer to the name of the key. @param value Pointer to the retrieved value. @@ -8969,7 +11010,7 @@ class IRtcEngineParameter { */ virtual int getNumber(const char* key, double& value) = 0; - /** Retrieves the string value of a specified key in the JSON format. + /** Gets the string value of a specified key in the JSON format. @param key Pointer to the name of the key. @param value Pointer to the retrieved value. @@ -8980,7 +11021,7 @@ class IRtcEngineParameter { */ virtual int getString(const char* key, agora::util::AString& value) = 0; - /** Retrieves a child object value of a specified key in the JSON format. + /** Gets a child object value of a specified key in the JSON format. @param key Pointer to the name of the key. @param value Pointer to the retrieved value. @@ -8990,7 +11031,7 @@ class IRtcEngineParameter { */ virtual int getObject(const char* key, agora::util::AString& value) = 0; - /** Retrieves the array value of a specified key in the JSON format. + /** Gets the array value of a specified key in the JSON format. @param key Pointer to the name of the key. @param value Pointer to the retrieved value. @@ -9026,6 +11067,7 @@ class IRtcEngineParameter { virtual int convertPath(const char* filePath, agora::util::AString& value) = 0; }; +#if !defined(__ANDROID__) && !(defined(__APPLE__) && TARGET_OS_IPHONE) class AAudioDeviceManager : public agora::util::AutoPtr { public: AAudioDeviceManager(IRtcEngine* engine) { queryInterface(engine, AGORA_IID_AUDIO_DEVICE_MANAGER); } @@ -9035,8 +11077,9 @@ class AVideoDeviceManager : public agora::util::AutoPtr { public: AVideoDeviceManager(IRtcEngine* engine) { queryInterface(engine, AGORA_IID_VIDEO_DEVICE_MANAGER); } }; +#endif -class AParameter : public agora::util::AutoPtr { +class AGORA_CPP_API AParameter : public agora::util::AutoPtr { public: AParameter(IRtcEngine& engine) { initialize(&engine); } AParameter(IRtcEngine* engine) { initialize(engine); } @@ -9051,483 +11094,93 @@ class AParameter : public agora::util::AutoPtr { }; /** **DEPRECATED** The RtcEngineParameters class is deprecated, use the IRtcEngine class instead. */ -class RtcEngineParameters { +class AGORA_CPP_API RtcEngineParameters { public: RtcEngineParameters(IRtcEngine& engine) : m_parameter(&engine) {} RtcEngineParameters(IRtcEngine* engine) : m_parameter(engine) {} - int enableLocalVideo(bool enabled) { return setParameters("{\"rtc.video.capture\":%s,\"che.video.local.capture\":%s,\"che.video.local.render\":%s,\"che.video.local.send\":%s}", enabled ? "true" : "false", enabled ? "true" : "false", enabled ? "true" : "false", enabled ? "true" : "false"); } - - int muteLocalVideoStream(bool mute) { return setParameters("{\"rtc.video.mute_me\":%s,\"che.video.local.send\":%s}", mute ? "true" : "false", mute ? "false" : "true"); } - - int muteAllRemoteVideoStreams(bool mute) { return m_parameter ? m_parameter->setBool("rtc.video.mute_peers", mute) : -ERR_NOT_INITIALIZED; } - - int setDefaultMuteAllRemoteVideoStreams(bool mute) { return m_parameter ? m_parameter->setBool("rtc.video.set_default_mute_peers", mute) : -ERR_NOT_INITIALIZED; } - - int muteRemoteVideoStream(uid_t uid, bool mute) { return setObject("rtc.video.mute_peer", "{\"uid\":%u,\"mute\":%s}", uid, mute ? "true" : "false"); } - - int setPlaybackDeviceVolume(int volume) { // [0,255] - return m_parameter ? m_parameter->setInt("che.audio.output.volume", volume) : -ERR_NOT_INITIALIZED; - } - - int startAudioRecording(const char* filePath, AUDIO_RECORDING_QUALITY_TYPE quality) { return startAudioRecording(filePath, 32000, quality); } - - int startAudioRecording(const char* filePath, int sampleRate, AUDIO_RECORDING_QUALITY_TYPE quality) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; -#if defined(_WIN32) - util::AString path; - if (!m_parameter->convertPath(filePath, path)) - filePath = path->c_str(); - else - return -ERR_INVALID_ARGUMENT; -#endif - return setObject("che.audio.start_recording", "{\"filePath\":\"%s\",\"sampleRate\":%d,\"quality\":%d}", filePath, sampleRate, quality); - } - - int stopAudioRecording() { return setParameters("{\"che.audio.stop_recording\":true, \"che.audio.stop_nearend_recording\":true, \"che.audio.stop_farend_recording\":true}"); } - - int startAudioMixing(const char* filePath, bool loopback, bool replace, int cycle, int startPos = 0) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; -#if defined(_WIN32) - util::AString path; - if (!m_parameter->convertPath(filePath, path)) - filePath = path->c_str(); - else - return -ERR_INVALID_ARGUMENT; -#endif - return setObject("che.audio.start_file_as_playout", "{\"filePath\":\"%s\",\"loopback\":%s,\"replace\":%s,\"cycle\":%d, \"startPos\":%d}", filePath, loopback ? "true" : "false", replace ? "true" : "false", cycle, startPos); - } - - int stopAudioMixing() { return m_parameter ? m_parameter->setBool("che.audio.stop_file_as_playout", true) : -ERR_NOT_INITIALIZED; } - - int pauseAudioMixing() { return m_parameter ? m_parameter->setBool("che.audio.pause_file_as_playout", true) : -ERR_NOT_INITIALIZED; } - - int resumeAudioMixing() { return m_parameter ? m_parameter->setBool("che.audio.pause_file_as_playout", false) : -ERR_NOT_INITIALIZED; } - - int adjustAudioMixingVolume(int volume) { - int ret = adjustAudioMixingPlayoutVolume(volume); - if (ret == 0) { - adjustAudioMixingPublishVolume(volume); - } - return ret; - } - - int adjustAudioMixingPlayoutVolume(int volume) { return m_parameter ? m_parameter->setInt("che.audio.set_file_as_playout_volume", volume) : -ERR_NOT_INITIALIZED; } - - int getAudioMixingPlayoutVolume() { - int volume = 0; - int r = m_parameter ? m_parameter->getInt("che.audio.get_file_as_playout_volume", volume) : -ERR_NOT_INITIALIZED; - if (r == 0) r = volume; - return r; - } - - int adjustAudioMixingPublishVolume(int volume) { return m_parameter ? m_parameter->setInt("che.audio.set_file_as_playout_publish_volume", volume) : -ERR_NOT_INITIALIZED; } - - int getAudioMixingPublishVolume() { - int volume = 0; - int r = m_parameter ? m_parameter->getInt("che.audio.get_file_as_playout_publish_volume", volume) : -ERR_NOT_INITIALIZED; - if (r == 0) r = volume; - return r; - } - - int getAudioMixingDuration() { - int duration = 0; - int r = m_parameter ? m_parameter->getInt("che.audio.get_mixing_file_length_ms", duration) : -ERR_NOT_INITIALIZED; - if (r == 0) r = duration; - return r; - } - - int getAudioMixingCurrentPosition() { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - int pos = 0; - int r = m_parameter->getInt("che.audio.get_mixing_file_played_ms", pos); - if (r == 0) r = pos; - return r; - } - - int setAudioMixingPosition(int pos /*in ms*/) { return m_parameter ? m_parameter->setInt("che.audio.mixing.file.position", pos) : -ERR_NOT_INITIALIZED; } - - int setAudioMixingPitch(int pitch) { - if (!m_parameter) { - return -ERR_NOT_INITIALIZED; - } - if (pitch > 12 || pitch < -12) { - return -ERR_INVALID_ARGUMENT; - } - return m_parameter->setInt("che.audio.set_playout_file_pitch_semitones", pitch); - } - - int getEffectsVolume() { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - int volume = 0; - int r = m_parameter->getInt("che.audio.game_get_effects_volume", volume); - if (r == 0) r = volume; - return r; - } - - int setEffectsVolume(int volume) { return m_parameter ? m_parameter->setInt("che.audio.game_set_effects_volume", volume) : -ERR_NOT_INITIALIZED; } - - int setVolumeOfEffect(int soundId, int volume) { return setObject("che.audio.game_adjust_effect_volume", "{\"soundId\":%d,\"gain\":%d}", soundId, volume); } - - int playEffect(int soundId, const char* filePath, int loopCount, double pitch, double pan, int gain, bool publish = false) { -#if defined(_WIN32) - util::AString path; - if (!m_parameter->convertPath(filePath, path)) - filePath = path->c_str(); - else if (!filePath) - filePath = ""; -#endif - return setObject("che.audio.game_play_effect", "{\"soundId\":%d,\"filePath\":\"%s\",\"loopCount\":%d, \"pitch\":%lf,\"pan\":%lf,\"gain\":%d, \"send2far\":%d}", soundId, filePath, loopCount, pitch, pan, gain, publish); - } - - int stopEffect(int soundId) { return m_parameter ? m_parameter->setInt("che.audio.game_stop_effect", soundId) : -ERR_NOT_INITIALIZED; } - - int stopAllEffects() { return m_parameter ? m_parameter->setBool("che.audio.game_stop_all_effects", true) : -ERR_NOT_INITIALIZED; } - - int preloadEffect(int soundId, char* filePath) { return setObject("che.audio.game_preload_effect", "{\"soundId\":%d,\"filePath\":\"%s\"}", soundId, filePath); } - - int unloadEffect(int soundId) { return m_parameter ? m_parameter->setInt("che.audio.game_unload_effect", soundId) : -ERR_NOT_INITIALIZED; } - - int pauseEffect(int soundId) { return m_parameter ? m_parameter->setInt("che.audio.game_pause_effect", soundId) : -ERR_NOT_INITIALIZED; } - - int pauseAllEffects() { return m_parameter ? m_parameter->setBool("che.audio.game_pause_all_effects", true) : -ERR_NOT_INITIALIZED; } - - int resumeEffect(int soundId) { return m_parameter ? m_parameter->setInt("che.audio.game_resume_effect", soundId) : -ERR_NOT_INITIALIZED; } - - int resumeAllEffects() { return m_parameter ? m_parameter->setBool("che.audio.game_resume_all_effects", true) : -ERR_NOT_INITIALIZED; } - - int enableSoundPositionIndication(bool enabled) { return m_parameter ? m_parameter->setBool("che.audio.enable_sound_position", enabled) : -ERR_NOT_INITIALIZED; } - - int setRemoteVoicePosition(uid_t uid, double pan, double gain) { return setObject("che.audio.game_place_sound_position", "{\"uid\":%u,\"pan\":%lf,\"gain\":%lf}", uid, pan, gain); } - - int setLocalVoicePitch(double pitch) { return m_parameter ? m_parameter->setInt("che.audio.morph.pitch_shift", static_cast(pitch * 100)) : -ERR_NOT_INITIALIZED; } - - int setLocalVoiceEqualization(AUDIO_EQUALIZATION_BAND_FREQUENCY bandFrequency, int bandGain) { return setObject("che.audio.morph.equalization", "{\"index\":%d,\"gain\":%d}", static_cast(bandFrequency), bandGain); } - - int setLocalVoiceReverb(AUDIO_REVERB_TYPE reverbKey, int value) { return setObject("che.audio.morph.reverb", "{\"key\":%d,\"value\":%d}", static_cast(reverbKey), value); } - - int setLocalVoiceChanger(VOICE_CHANGER_PRESET voiceChanger) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - if (voiceChanger == 0x00000000) { - return m_parameter->setInt("che.audio.morph.voice_changer", static_cast(voiceChanger)); - } else if (voiceChanger > 0x00000000 && voiceChanger < 0x00100000) { - return m_parameter->setInt("che.audio.morph.voice_changer", static_cast(voiceChanger)); - } else if (voiceChanger > 0x00100000 && voiceChanger < 0x00200000) { - return m_parameter->setInt("che.audio.morph.voice_changer", static_cast(voiceChanger - 0x00100000 + 6)); - } else if (voiceChanger > 0x00200000 && voiceChanger < 0x00300000) { - return m_parameter->setInt("che.audio.morph.beauty_voice", static_cast(voiceChanger - 0x00200000)); - } else { - return -ERR_INVALID_ARGUMENT; - } - } - - int setLocalVoiceReverbPreset(AUDIO_REVERB_PRESET reverbPreset) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - if (reverbPreset == 0x00000000) { - return m_parameter->setInt("che.audio.morph.reverb_preset", static_cast(reverbPreset)); - } else if (reverbPreset > 0x00000000 && reverbPreset < 0x00100000) { - return m_parameter->setInt("che.audio.morph.reverb_preset", static_cast(reverbPreset + 8)); - } else if (reverbPreset > 0x00100000 && reverbPreset < 0x00200000) { - return m_parameter->setInt("che.audio.morph.reverb_preset", static_cast(reverbPreset - 0x00100000)); - } else if (reverbPreset > 0x00200000 && reverbPreset < 0x00200002) { - return m_parameter->setInt("che.audio.morph.virtual_stereo", static_cast(reverbPreset - 0x00200000)); - } else if (reverbPreset > (AUDIO_REVERB_PRESET)0x00300000 && reverbPreset < (AUDIO_REVERB_PRESET)0x00300002) - return setObject("che.audio.morph.electronic_voice", "{\"key\":%d,\"value\":%d}", 1, 4); - else if (reverbPreset > (AUDIO_REVERB_PRESET)0x00400000 && reverbPreset < (AUDIO_REVERB_PRESET)0x00400002) - return m_parameter->setInt("che.audio.morph.threedim_voice", 10); - else { - return -ERR_INVALID_ARGUMENT; - } - } - - int setAudioEffectPreset(AUDIO_EFFECT_PRESET preset) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - if (preset == AUDIO_EFFECT_OFF) { - return m_parameter->setInt("che.audio.morph.voice_changer", 0); - } - if (preset == ROOM_ACOUSTICS_KTV) { - return m_parameter->setInt("che.audio.morph.reverb_preset", 1); - } - if (preset == ROOM_ACOUSTICS_VOCAL_CONCERT) { - return m_parameter->setInt("che.audio.morph.reverb_preset", 2); - } - if (preset == ROOM_ACOUSTICS_STUDIO) { - return m_parameter->setInt("che.audio.morph.reverb_preset", 5); - } - if (preset == ROOM_ACOUSTICS_PHONOGRAPH) { - return m_parameter->setInt("che.audio.morph.reverb_preset", 8); - } - if (preset == ROOM_ACOUSTICS_VIRTUAL_STEREO) { - return m_parameter->setInt("che.audio.morph.virtual_stereo", 1); - } - if (preset == ROOM_ACOUSTICS_SPACIAL) { - return m_parameter->setInt("che.audio.morph.voice_changer", 15); - } - if (preset == ROOM_ACOUSTICS_ETHEREAL) { - return m_parameter->setInt("che.audio.morph.voice_changer", 5); - } - if (preset == ROOM_ACOUSTICS_3D_VOICE) { - return m_parameter->setInt("che.audio.morph.threedim_voice", 10); - } - if (preset == VOICE_CHANGER_EFFECT_UNCLE) { - return m_parameter->setInt("che.audio.morph.reverb_preset", 3); - } - if (preset == VOICE_CHANGER_EFFECT_OLDMAN) { - return m_parameter->setInt("che.audio.morph.voice_changer", 1); - } - if (preset == VOICE_CHANGER_EFFECT_BOY) { - return m_parameter->setInt("che.audio.morph.voice_changer", 2); - } - if (preset == VOICE_CHANGER_EFFECT_SISTER) { - return m_parameter->setInt("che.audio.morph.reverb_preset", 4); - } - if (preset == VOICE_CHANGER_EFFECT_GIRL) { - return m_parameter->setInt("che.audio.morph.voice_changer", 3); - } - if (preset == VOICE_CHANGER_EFFECT_PIGKING) { - return m_parameter->setInt("che.audio.morph.voice_changer", 4); - } - if (preset == VOICE_CHANGER_EFFECT_HULK) { - return m_parameter->setInt("che.audio.morph.voice_changer", 6); - } - if (preset == STYLE_TRANSFORMATION_RNB) { - return m_parameter->setInt("che.audio.morph.reverb_preset", 7); - } - if (preset == STYLE_TRANSFORMATION_POPULAR) { - return m_parameter->setInt("che.audio.morph.reverb_preset", 6); - } - if (preset == PITCH_CORRECTION) { - return setObject("che.audio.morph.electronic_voice", "{\"key\":%d,\"value\":%d}", 1, 4); - } - return -ERR_INVALID_ARGUMENT; - } - - int setVoiceBeautifierPreset(VOICE_BEAUTIFIER_PRESET preset) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - if (preset == VOICE_BEAUTIFIER_OFF) { - return m_parameter->setInt("che.audio.morph.voice_changer", 0); - } - if (preset == CHAT_BEAUTIFIER_MAGNETIC) { - return m_parameter->setInt("che.audio.morph.beauty_voice", 1); - } - if (preset == CHAT_BEAUTIFIER_FRESH) { - return m_parameter->setInt("che.audio.morph.beauty_voice", 2); - } - if (preset == CHAT_BEAUTIFIER_VITALITY) { - return m_parameter->setInt("che.audio.morph.beauty_voice", 3); - } - if (preset == SINGING_BEAUTIFIER) { - return setObject("che.audio.morph.beauty_sing", "{\"key\":%d,\"value\":%d}", 1, 1); - } - if (preset == TIMBRE_TRANSFORMATION_VIGOROUS) { - return m_parameter->setInt("che.audio.morph.voice_changer", 7); - } - if (preset == TIMBRE_TRANSFORMATION_DEEP) { - return m_parameter->setInt("che.audio.morph.voice_changer", 8); - } - if (preset == TIMBRE_TRANSFORMATION_MELLOW) { - return m_parameter->setInt("che.audio.morph.voice_changer", 9); - } - if (preset == TIMBRE_TRANSFORMATION_FALSETTO) { - return m_parameter->setInt("che.audio.morph.voice_changer", 10); - } - if (preset == TIMBRE_TRANSFORMATION_FULL) { - return m_parameter->setInt("che.audio.morph.voice_changer", 11); - } - if (preset == TIMBRE_TRANSFORMATION_CLEAR) { - return m_parameter->setInt("che.audio.morph.voice_changer", 12); - } - if (preset == TIMBRE_TRANSFORMATION_RESOUNDING) { - return m_parameter->setInt("che.audio.morph.voice_changer", 13); - } - if (preset == TIMBRE_TRANSFORMATION_RINGING) { - return m_parameter->setInt("che.audio.morph.voice_changer", 14); - } - return -ERR_INVALID_ARGUMENT; - } - - int setAudioEffectParameters(AUDIO_EFFECT_PRESET preset, int param1, int param2) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - if (preset == PITCH_CORRECTION) { - return setObject("che.audio.morph.electronic_voice", "{\"key\":%d,\"value\":%d}", param1, param2); - } - if (preset == ROOM_ACOUSTICS_3D_VOICE) { - return m_parameter->setInt("che.audio.morph.threedim_voice", param1); - } - return -ERR_INVALID_ARGUMENT; - } - - int setVoiceBeautifierParameters(VOICE_BEAUTIFIER_PRESET preset, int param1, int param2) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - if (preset == SINGING_BEAUTIFIER) { - return setObject("che.audio.morph.beauty_sing", "{\"key\":%d,\"value\":%d}", param1, param2); - } - return -ERR_INVALID_ARGUMENT; - } - - /** **DEPRECATED** Use \ref IRtcEngine::disableAudio "disableAudio" instead. Disables the audio function in the channel. - - @return - - 0: Success. - - < 0: Failure. - */ - int pauseAudio() { return m_parameter ? m_parameter->setBool("che.pause.audio", true) : -ERR_NOT_INITIALIZED; } - - int resumeAudio() { return m_parameter ? m_parameter->setBool("che.pause.audio", false) : -ERR_NOT_INITIALIZED; } - - int setHighQualityAudioParameters(bool fullband, bool stereo, bool fullBitrate) { return setObject("che.audio.codec.hq", "{\"fullband\":%s,\"stereo\":%s,\"fullBitrate\":%s}", fullband ? "true" : "false", stereo ? "true" : "false", fullBitrate ? "true" : "false"); } - - int adjustRecordingSignalVolume(int volume) { //[0, 400]: e.g. 50~0.5x 100~1x 400~4x - if (volume < 0) - volume = 0; - else if (volume > 400) - volume = 400; - return m_parameter ? m_parameter->setInt("che.audio.record.signal.volume", volume) : -ERR_NOT_INITIALIZED; - } - - int adjustPlaybackSignalVolume(int volume) { //[0, 400] - if (volume < 0) - volume = 0; - else if (volume > 400) - volume = 400; - return m_parameter ? m_parameter->setInt("che.audio.playout.signal.volume", volume) : -ERR_NOT_INITIALIZED; - } - - int enableAudioVolumeIndication(int interval, int smooth, bool report_vad) { // in ms: <= 0: disable, > 0: enable, interval in ms - if (interval < 0) interval = 0; - return setObject("che.audio.volume_indication", "{\"interval\":%d,\"smooth\":%d,\"vad\":%d}", interval, smooth, report_vad); - } - - int muteLocalAudioStream(bool mute) { return setParameters("{\"rtc.audio.mute_me\":%s,\"che.audio.mute_me\":%s}", mute ? "true" : "false", mute ? "true" : "false"); } - // mute/unmute all peers. unmute will clear all muted peers specified mutePeer() interface - - int muteRemoteAudioStream(uid_t uid, bool mute) { return setObject("rtc.audio.mute_peer", "{\"uid\":%u,\"mute\":%s}", uid, mute ? "true" : "false"); } - - int muteAllRemoteAudioStreams(bool mute) { return m_parameter ? m_parameter->setBool("rtc.audio.mute_peers", mute) : -ERR_NOT_INITIALIZED; } - - int setVoiceConversionPreset(VOICE_CONVERSION_PRESET preset) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - if (preset == VOICE_CONVERSION_OFF) { - return m_parameter->setInt("che.audio.morph.voice_changer", 0); - } - if (preset == VOICE_CHANGER_NEUTRAL) { - return m_parameter->setInt("che.audio.morph.vocal_changer", 1); - } - if (preset == VOICE_CHANGER_SWEET) { - return m_parameter->setInt("che.audio.morph.vocal_changer", 2); - } - if (preset == VOICE_CHANGER_SOLID) { - return m_parameter->setInt("che.audio.morph.vocal_changer", 3); - } - if (preset == VOICE_CHANGER_BASS) { - return m_parameter->setInt("che.audio.morph.vocal_changer", 4); - } - return -ERR_INVALID_ARGUMENT; - } - - int setDefaultMuteAllRemoteAudioStreams(bool mute) { return m_parameter ? m_parameter->setBool("rtc.audio.set_default_mute_peers", mute) : -ERR_NOT_INITIALIZED; } - - int setExternalAudioSource(bool enabled, int sampleRate, int channels) { - if (enabled) - return setParameters("{\"che.audio.external_capture\":true,\"che.audio.external_capture.push\":true,\"che.audio.set_capture_raw_audio_format\":{\"sampleRate\":%d,\"channelCnt\":%d,\"mode\":%d}}", sampleRate, channels, RAW_AUDIO_FRAME_OP_MODE_TYPE::RAW_AUDIO_FRAME_OP_MODE_READ_WRITE); - else - return setParameters("{\"che.audio.external_capture\":false,\"che.audio.external_capture.push\":false}"); - } - - int setExternalAudioSink(bool enabled, int sampleRate, int channels) { - if (enabled) - return setParameters("{\"che.audio.external_render\":true,\"che.audio.external_render.pull\":true,\"che.audio.set_render_raw_audio_format\":{\"sampleRate\":%d,\"channelCnt\":%d,\"mode\":%d}}", sampleRate, channels, RAW_AUDIO_FRAME_OP_MODE_TYPE::RAW_AUDIO_FRAME_OP_MODE_READ_ONLY); - else - return setParameters("{\"che.audio.external_render\":false,\"che.audio.external_render.pull\":false}"); - } - - int setLogFile(const char* filePath) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; -#if defined(_WIN32) - util::AString path; - if (!m_parameter->convertPath(filePath, path)) - filePath = path->c_str(); - else if (!filePath) - filePath = ""; -#endif - return m_parameter->setString("rtc.log_file", filePath); - } - - int setLogFilter(unsigned int filter) { return m_parameter ? m_parameter->setUInt("rtc.log_filter", filter & LOG_FILTER_MASK) : -ERR_NOT_INITIALIZED; } - - int setLogFileSize(unsigned int fileSizeInKBytes) { return m_parameter ? m_parameter->setUInt("rtc.log_size", fileSizeInKBytes) : -ERR_NOT_INITIALIZED; } - - int setLocalRenderMode(RENDER_MODE_TYPE renderMode) { return setRemoteRenderMode(0, renderMode); } - - int setRemoteRenderMode(uid_t uid, RENDER_MODE_TYPE renderMode) { return setParameters("{\"che.video.render_mode\":[{\"uid\":%u,\"renderMode\":%d}]}", uid, renderMode); } - - int setCameraCapturerConfiguration(const CameraCapturerConfiguration& config) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - if (config.preference == CAPTURER_OUTPUT_PREFERENCE_MANUAL) { - m_parameter->setInt("che.video.capture_width", config.captureWidth); - m_parameter->setInt("che.video.capture_height", config.captureHeight); - } - return m_parameter->setInt("che.video.camera_capture_mode", (int)config.preference); - } - - int enableDualStreamMode(bool enabled) { return setParameters("{\"rtc.dual_stream_mode\":%s,\"che.video.enableLowBitRateStream\":%d}", enabled ? "true" : "false", enabled ? 1 : 0); } - - int setRemoteVideoStreamType(uid_t uid, REMOTE_VIDEO_STREAM_TYPE streamType) { - return setParameters("{\"rtc.video.set_remote_video_stream\":{\"uid\":%u,\"stream\":%d}, \"che.video.setstream\":{\"uid\":%u,\"stream\":%d}}", uid, streamType, uid, streamType); - // return setObject("rtc.video.set_remote_video_stream", "{\"uid\":%u,\"stream\":%d}", uid, streamType); - } - - int setRemoteDefaultVideoStreamType(REMOTE_VIDEO_STREAM_TYPE streamType) { return m_parameter ? m_parameter->setInt("rtc.video.set_remote_default_video_stream_type", streamType) : -ERR_NOT_INITIALIZED; } - - int setRecordingAudioFrameParameters(int sampleRate, int channel, RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall) { return setObject("che.audio.set_capture_raw_audio_format", "{\"sampleRate\":%d,\"channelCnt\":%d,\"mode\":%d,\"samplesPerCall\":%d}", sampleRate, channel, mode, samplesPerCall); } - - int setPlaybackAudioFrameParameters(int sampleRate, int channel, RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall) { return setObject("che.audio.set_render_raw_audio_format", "{\"sampleRate\":%d,\"channelCnt\":%d,\"mode\":%d,\"samplesPerCall\":%d}", sampleRate, channel, mode, samplesPerCall); } - - int setMixedAudioFrameParameters(int sampleRate, int samplesPerCall) { return setObject("che.audio.set_mixed_raw_audio_format", "{\"sampleRate\":%d,\"samplesPerCall\":%d}", sampleRate, samplesPerCall); } - - int enableWebSdkInteroperability(bool enabled) { // enable interoperability with zero-plugin web sdk - return setParameters("{\"rtc.video.web_h264_interop_enable\":%s,\"che.video.web_h264_interop_enable\":%s}", enabled ? "true" : "false", enabled ? "true" : "false"); - } + int enableLocalVideo(bool enabled); + int muteLocalVideoStream(bool mute); + int muteAllRemoteVideoStreams(bool mute); + int setDefaultMuteAllRemoteVideoStreams(bool mute); + int muteRemoteVideoStream(uid_t uid, bool mute); + int setPlaybackDeviceVolume(int volume /* [0,255] */); + int startAudioRecording(const char* filePath, AUDIO_RECORDING_QUALITY_TYPE quality); + int startAudioRecording(const char* filePath, int sampleRate, AUDIO_RECORDING_QUALITY_TYPE quality); + int stopAudioRecording(); + int startAudioMixing(const char* filePath, bool loopback, bool replace, int cycle, int startPos = 0); + int stopAudioMixing(); + int pauseAudioMixing(); + int resumeAudioMixing(); + int adjustAudioMixingVolume(int volume); + int adjustAudioMixingPlayoutVolume(int volume); + int getAudioMixingPlayoutVolume(); + int adjustAudioMixingPublishVolume(int volume); + int getAudioMixingPublishVolume(); + int getAudioMixingDuration(); + int getAudioMixingCurrentPosition(); + int setAudioMixingPosition(int pos /*in ms*/); + int setAudioMixingPitch(int pitch); + int getEffectsVolume(); + int setEffectsVolume(int volume); + int setVolumeOfEffect(int soundId, int volume); + int playEffect(int soundId, const char* filePath, int loopCount, double pitch, double pan, int gain, bool publish = false); + int stopEffect(int soundId); + int stopAllEffects(); + int preloadEffect(int soundId, char* filePath); + int unloadEffect(int soundId); + int pauseEffect(int soundId); + int pauseAllEffects(); + int resumeEffect(int soundId); + int resumeAllEffects(); + int enableSoundPositionIndication(bool enabled); + int setRemoteVoicePosition(uid_t uid, double pan, double gain); + int setLocalVoicePitch(double pitch); + int setLocalVoiceEqualization(AUDIO_EQUALIZATION_BAND_FREQUENCY bandFrequency, int bandGain); + int setLocalVoiceReverb(AUDIO_REVERB_TYPE reverbKey, int value); + int setLocalVoiceChanger(VOICE_CHANGER_PRESET voiceChanger); + int setLocalVoiceReverbPreset(AUDIO_REVERB_PRESET reverbPreset); + int setAudioEffectPreset(AUDIO_EFFECT_PRESET preset); + int setVoiceBeautifierPreset(VOICE_BEAUTIFIER_PRESET preset); + int setAudioEffectParameters(AUDIO_EFFECT_PRESET preset, int param1, int param2); + int setVoiceBeautifierParameters(VOICE_BEAUTIFIER_PRESET preset, int param1, int param2); + int pauseAudio(); + int resumeAudio(); + int setHighQualityAudioParameters(bool fullband, bool stereo, bool fullBitrate); + int adjustRecordingSignalVolume(int volume /* [0, 400]: e.g. 50~0.5x 100~1x 400~4x */); + int adjustPlaybackSignalVolume(int volume /* [0, 400] */); + int enableAudioVolumeIndication(int interval, int smooth, bool report_vad); // in ms: <= 0: disable, > 0: enable, interval in ms + int muteLocalAudioStream(bool mute); + int muteRemoteAudioStream(uid_t uid, bool mute); + int muteAllRemoteAudioStreams(bool mute); + int setVoiceConversionPreset(VOICE_CONVERSION_PRESET preset); + int setDefaultMuteAllRemoteAudioStreams(bool mute); + int setExternalAudioSource(bool enabled, int sampleRate, int channels); + int setExternalAudioSink(bool enabled, int sampleRate, int channels); + int setLogFile(const char* filePath); + int setLogFilter(unsigned int filter); + int setLogFileSize(unsigned int fileSizeInKBytes); + int setLocalRenderMode(RENDER_MODE_TYPE renderMode); + int setRemoteRenderMode(uid_t uid, RENDER_MODE_TYPE renderMode); + int setCameraCapturerConfiguration(const CameraCapturerConfiguration& config); + int enableDualStreamMode(bool enabled); + int setRemoteVideoStreamType(uid_t uid, REMOTE_VIDEO_STREAM_TYPE streamType); + int setRemoteDefaultVideoStreamType(REMOTE_VIDEO_STREAM_TYPE streamType); + int setRecordingAudioFrameParameters(int sampleRate, int channel, RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall); + int setPlaybackAudioFrameParameters(int sampleRate, int channel, RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall); + int setMixedAudioFrameParameters(int sampleRate, int samplesPerCall); + int enableWebSdkInteroperability(bool enabled); // only for live broadcast - int setVideoQualityParameters(bool preferFrameRateOverImageQuality) { return setParameters("{\"rtc.video.prefer_frame_rate\":%s,\"che.video.prefer_frame_rate\":%s}", preferFrameRateOverImageQuality ? "true" : "false", preferFrameRateOverImageQuality ? "true" : "false"); } - - int setLocalVideoMirrorMode(VIDEO_MIRROR_MODE_TYPE mirrorMode) { - if (!m_parameter) return -ERR_NOT_INITIALIZED; - const char* value; - switch (mirrorMode) { - case VIDEO_MIRROR_MODE_AUTO: - value = "default"; - break; - case VIDEO_MIRROR_MODE_ENABLED: - value = "forceMirror"; - break; - case VIDEO_MIRROR_MODE_DISABLED: - value = "disableMirror"; - break; - default: - return -ERR_INVALID_ARGUMENT; - } - return m_parameter->setString("che.video.localViewMirrorSetting", value); - } - - int setLocalPublishFallbackOption(STREAM_FALLBACK_OPTIONS option) { return m_parameter ? m_parameter->setInt("rtc.local_publish_fallback_option", option) : -ERR_NOT_INITIALIZED; } - - int setRemoteSubscribeFallbackOption(STREAM_FALLBACK_OPTIONS option) { return m_parameter ? m_parameter->setInt("rtc.remote_subscribe_fallback_option", option) : -ERR_NOT_INITIALIZED; } - + int setVideoQualityParameters(bool preferFrameRateOverImageQuality); + int setLocalVideoMirrorMode(VIDEO_MIRROR_MODE_TYPE mirrorMode); + int setLocalPublishFallbackOption(STREAM_FALLBACK_OPTIONS option); + int setRemoteSubscribeFallbackOption(STREAM_FALLBACK_OPTIONS option); #if (defined(__APPLE__) && TARGET_OS_MAC && !TARGET_OS_IPHONE) || defined(_WIN32) - - int enableLoopbackRecording(bool enabled, const char* deviceName = NULL) { - if (!deviceName) { - return setParameters("{\"che.audio.loopback.recording\":%s}", enabled ? "true" : "false"); - } else { - return setParameters("{\"che.audio.loopback.deviceName\":\"%s\",\"che.audio.loopback.recording\":%s}", deviceName, enabled ? "true" : "false"); - } - } + int enableLoopbackRecording(bool enabled, const char* deviceName = NULL); #endif - - int setInEarMonitoringVolume(int volume) { return m_parameter ? m_parameter->setInt("che.audio.headset.monitoring.parameter", volume) : -ERR_NOT_INITIALIZED; } + int setInEarMonitoringVolume(int volume); protected: AParameter& parameter() { return m_parameter; } @@ -9547,11 +11200,275 @@ class RtcEngineParameters { va_end(args); return m_parameter ? m_parameter->setObject(key, buf) : -ERR_NOT_INITIALIZED; } - int stopAllRemoteVideo() { return m_parameter ? m_parameter->setBool("che.video.peer.stop_render", true) : -ERR_NOT_INITIALIZED; } private: AParameter m_parameter; }; +/** + * The format of the recording file. + * + * @since v3.5.2 + */ +enum MediaRecorderContainerFormat { + /** + * 1: (Default) MP4. + */ + FORMAT_MP4 = 1, + /** + * Reserved parameter. + */ + FORMAT_FLV = 2, +}; +/** + * The recording content. + * + * @since v3.5.2 + */ +enum MediaRecorderStreamType { + /** + * Only audio. + */ + STREAM_TYPE_AUDIO = 0x01, + /** + * Only video. + */ + STREAM_TYPE_VIDEO = 0x02, + /** + * (Default) Audio and video. + */ + STREAM_TYPE_BOTH = STREAM_TYPE_AUDIO | STREAM_TYPE_VIDEO, +}; +/** + * The current recording state. + * + * @since v3.5.2 + */ +enum RecorderState { + /** + * -1: An error occurs during the recording. See RecorderErrorCode for the reason. + */ + RECORDER_STATE_ERROR = -1, + /** + * 2: The audio and video recording is started. + */ + RECORDER_STATE_START = 2, + /** + * 3: The audio and video recording is stopped. + */ + RECORDER_STATE_STOP = 3, +}; +/** + * The reason for the state change + * + * @since v3.5.2 + */ +enum RecorderErrorCode { + /** + * 0: No error occurs. + */ + RECORDER_ERROR_NONE = 0, + /** + * 1: The SDK fails to write the recorded data to a file. + */ + RECORDER_ERROR_WRITE_FAILED = 1, + /** + * 2: The SDK does not detect audio and video streams to be recorded, or audio and video streams are interrupted for more than five seconds during recording. + */ + RECORDER_ERROR_NO_STREAM = 2, + /** + * 3: The recording duration exceeds the upper limit. + */ + RECORDER_ERROR_OVER_MAX_DURATION = 3, + /** + * 4: The recording configuration changes. + */ + RECORDER_ERROR_CONFIG_CHANGED = 4, + /** + * 5: The SDK detects audio and video streams from users using versions of the SDK earlier than v3.0.0 in + * the `COMMUNICATION` channel profile. + */ + RECORDER_ERROR_CUSTOM_STREAM_DETECTED = 5, +}; +/** + * Configurations for the local audio and video recording. + * + * @since v3.5.2 + */ +struct MediaRecorderConfiguration { + /** + * The absolute path (including the filename extensions) of the recording file. + * For example, `C:\Users\\AppData\Local\Agora\\example.mp4` on Windows, + * `/App Sandbox/Library/Caches/example.mp4` on iOS, `/Library/Logs/example.mp4` on macOS, and + * `/storage/emulated/0/Android/data//files/example.mp4` on Android. + * + * @note Ensure that the specified path exists and is writable. + */ + const char* storagePath; + /** + * The format of the recording file. See \ref agora::rtc::MediaRecorderContainerFormat "MediaRecorderContainerFormat". + */ + MediaRecorderContainerFormat containerFormat; + /** + * The recording content. See \ref agora::rtc::MediaRecorderStreamType "MediaRecorderStreamType". + */ + MediaRecorderStreamType streamType; + /** + * The maximum recording duration, in milliseconds. The default value is 120000. + */ + int maxDurationMs; + /** + * The interval (ms) of updating the recording information. The value range is + * [1000,10000]. Based on the set value of `recorderInfoUpdateInterval`, the + * SDK triggers the \ref IMediaRecorderObserver::onRecorderInfoUpdated "onRecorderInfoUpdated" + * callback to report the updated recording information. + */ + int recorderInfoUpdateInterval; + + MediaRecorderConfiguration() : storagePath(nullptr), containerFormat(FORMAT_MP4), streamType(STREAM_TYPE_BOTH), maxDurationMs(120000), recorderInfoUpdateInterval(0) {} + MediaRecorderConfiguration(const char* path, MediaRecorderContainerFormat format, MediaRecorderStreamType type, int duration, int interval) : storagePath(path), containerFormat(format), streamType(type), maxDurationMs(duration), recorderInfoUpdateInterval(interval) {} +}; +/** + * Information for the recording file. + * + * @since v3.5.2 + */ +struct RecorderInfo { + /** + * The absolute path of the recording file. + */ + const char* fileName; + /** + * The recording duration, in milliseconds. + */ + unsigned int durationMs; + /** + * The size in bytes of the recording file. + */ + unsigned int fileSize; + + RecorderInfo() = default; + RecorderInfo(const char* name, unsigned int dur, unsigned int size) : fileName(name), durationMs(dur), fileSize(size) {} +}; + +/** + * The IMediaRecorderObserver class. + * + * @since v3.5.2 + */ +class IMediaRecorderObserver { + public: + /** + * Occurs when the recording state changes. + * + * @since v3.5.2 + * + * When the local audio and video recording state changes, the SDK triggers this callback to report the current + * recording state and the reason for the change. + * + * @param state The current recording state. See \ref agora::rtc::RecorderState "RecorderState". + * @param error The reason for the state change. See \ref agora::rtc::RecorderErrorCode "RecorderErrorCode". + */ + virtual void onRecorderStateChanged(RecorderState state, RecorderErrorCode error) = 0; + /** + * Occurs when the recording information is updated. + * + * @since v3.5.2 + * + * After you successfully register this callback and enable the local audio and video recording, the SDK periodically triggers + * the `onRecorderInfoUpdated` callback based on the set value of `recorderInfoUpdateInterval`. This callback reports the + * filename, duration, and size of the current recording file. + * + * @param info Information for the recording file. See RecorderInfo. + * + */ + virtual void onRecorderInfoUpdated(const RecorderInfo& info){}; +}; +/** + * The IMediaRecorder class, for recording the audio and video on the client. IMediaRecorder can record the + * following content: + * - The audio captured by the local microphone and encoded in AAC format. + * - The video captured by the local camera and encoded by the SDK. + * + * @since v3.5.2 + * + * @note In the `COMMUNICATION` channel profile, this function is unavailable when there are users using versions of + * the SDK earlier than v3.0.0 in the channel. + */ +class IMediaRecorder { + public: + /** + * Gets the IMediaRecorder object. + * + * @since v3.5.2 + * + * @note Call this method after initializing the IRtcEngine object. + * + * @param engine IRtcEngine + * @param callback IMediaRecorderObserver + * + * @return IMediaRecorder + */ + AGORA_CPP_API static IMediaRecorder* getMediaRecorder(IRtcEngine* engine, IMediaRecorderObserver* callback); + /** + * Starts recording the local audio and video. + * + * @since v3.5.2 + * + * After successfully getting the object, you can call this method to enable the recording of the local audio and video. + * + * This method can record the following content: + * - The audio captured by the local microphone and encoded in AAC format. + * - The video captured by the local camera and encoded by the SDK. + * + * The SDK can generate a recording file only when it detects the recordable audio and video streams; when there are + * no audio and video streams to be recorded or the audio and video streams are interrupted for more than five + * seconds, the SDK stops recording and triggers the + * \ref IMediaRecorderObserver::onRecorderStateChanged "onRecorderStateChanged" (RECORDER_STATE_ERROR, RECORDER_ERROR_NO_STREAM) + * callback. + * + * @note Call this method after joining the channel. + * + * @param config The recording configurations. See MediaRecorderConfiguration. + * + * @return + * - 0(ERR_OK): Success. + * - < 0: Failure: + * - `-2(ERR_INVALID_ARGUMENT)`: The parameter is invalid. Ensure the following: + * - The specified path of the recording file exists and is writable. + * - The specified format of the recording file is supported. + * - The maximum recording duration is correctly set. + * - `-4(ERR_NOT_SUPPORTED)`: IRtcEngine does not support the request due to one of the following reasons: + * - The recording is ongoing. + * - The recording stops because an error occurs. + * - `-7(ERR_NOT_INITIALIZED)`: This method is called before the initialization of IRtcEngine. Ensure that you have + * called \ref IMediaRecorder::getMediaRecorder "getMediaRecorder" before calling `startRecording`. + */ + virtual int startRecording(const MediaRecorderConfiguration& config) = 0; + /** + * Stops recording the local audio and video. + * + * @since v3.5.2 + * + * @note Call this method after calling \ref IMediaRecorder::startRecording "startRecording". + * + * @return + * - 0(ERR_OK): Success. + * - < 0: Failure: + * - `-7(ERR_NOT_INITIALIZED)`: This method is called before the initialization of IRtcEngine. Ensure that you have + * called \ref IMediaRecorder::getMediaRecorder "getMediaRecorder" before calling `stopRecording`. + */ + virtual int stopRecording() = 0; + /** + * Releases the IMediaRecorder object. + * + * @since v3.5.2 + * + * This method releases the IRtcEngine object and all other resources used by the IMediaRecorder object. After calling + * this method, if you want to enable the recording again, you must call + * \ref IMediaRecorder::getMediaRecorder "getMediaRecorder" to get the IMediaRecorder object. + */ + virtual void releaseRecorder() = 0; +}; } // namespace rtc } // namespace agora diff --git a/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/IAgoraService.h b/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/IAgoraService.h index 61420d53f..555ed8866 100644 --- a/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/IAgoraService.h +++ b/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/IAgoraService.h @@ -34,7 +34,7 @@ class IAgoraService { */ virtual int initialize(const AgoraServiceContext& context) = 0; - /** Retrieves the SDK version number. + /** Gets the SDK version number. * @param build Build number. * @return The current SDK version in the string format. For example, 2.4.0 */ From 2ba5b9eb644ee6d0f7c95cae68005ab32f5262b0 Mon Sep 17 00:00:00 2001 From: Arlin Date: Fri, 11 Feb 2022 17:14:33 +0800 Subject: [PATCH 15/21] change api getChannelId to getId and adapt api startRtmpStream --- .../Advanced/JoinMultiChannel/JoinMultiChannel.swift | 8 ++++---- .../Examples/Advanced/RTMPStreaming/RTMPStreaming.swift | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/iOS/APIExample/Examples/Advanced/JoinMultiChannel/JoinMultiChannel.swift b/iOS/APIExample/Examples/Advanced/JoinMultiChannel/JoinMultiChannel.swift index e772d0bdb..635510bd2 100644 --- a/iOS/APIExample/Examples/Advanced/JoinMultiChannel/JoinMultiChannel.swift +++ b/iOS/APIExample/Examples/Advanced/JoinMultiChannel/JoinMultiChannel.swift @@ -184,7 +184,7 @@ extension JoinMultiChannelMain: AgoraRtcEngineDelegate { extension JoinMultiChannelMain: AgoraRtcChannelDelegate { func rtcChannelDidJoin(_ rtcChannel: AgoraRtcChannel, withUid uid: UInt, elapsed: Int) { - LogUtils.log(message: "Join \(rtcChannel.getChannelId() ?? "") with uid \(uid) elapsed \(elapsed)ms", level: .info) + LogUtils.log(message: "Join \(rtcChannel.getId() ?? "") with uid \(uid) elapsed \(elapsed)ms", level: .info) } /// callback when warning occured for a channel, warning can usually be ignored, still it's nice to check out /// what is happening @@ -193,7 +193,7 @@ extension JoinMultiChannelMain: AgoraRtcChannelDelegate /// cn: https://docs.agora.io/cn/Voice/API%20Reference/oc/Constants/AgoraWarningCode.html /// @param warningCode warning code of the problem func rtcChannel(_ rtcChannel: AgoraRtcChannel, didOccurWarning warningCode: AgoraWarningCode) { - LogUtils.log(message: "channel: \(rtcChannel.getChannelId() ?? ""), warning: \(warningCode.description)", level: .warning) + LogUtils.log(message: "channel: \(rtcChannel.getId() ?? ""), warning: \(warningCode.description)", level: .warning) } /// callback when error occured for a channel, you are recommended to display the error descriptions on demand @@ -222,7 +222,7 @@ extension JoinMultiChannelMain: AgoraRtcChannelDelegate videoCanvas.view = channel1 == rtcChannel ? channel1RemoteVideo.videoView : channel2RemoteVideo.videoView videoCanvas.renderMode = .hidden // set channelId so that it knows which channel the video belongs to - videoCanvas.channelId = rtcChannel.getChannelId() + videoCanvas.channelId = rtcChannel.getId() agoraKit.setupRemoteVideo(videoCanvas) } @@ -242,7 +242,7 @@ extension JoinMultiChannelMain: AgoraRtcChannelDelegate videoCanvas.view = nil videoCanvas.renderMode = .hidden // set channelId so that it knows which channel the video belongs to - videoCanvas.channelId = rtcChannel.getChannelId() + videoCanvas.channelId = rtcChannel.getId() agoraKit.setupRemoteVideo(videoCanvas) } } diff --git a/iOS/APIExample/Examples/Advanced/RTMPStreaming/RTMPStreaming.swift b/iOS/APIExample/Examples/Advanced/RTMPStreaming/RTMPStreaming.swift index 772c11d5c..7d48f0318 100644 --- a/iOS/APIExample/Examples/Advanced/RTMPStreaming/RTMPStreaming.swift +++ b/iOS/APIExample/Examples/Advanced/RTMPStreaming/RTMPStreaming.swift @@ -180,7 +180,7 @@ class RTMPStreamingMain: BaseViewController { // therefore we have to create a livetranscoding object and call before addPublishStreamUrl transcoding.size = CGSize(width: CANVAS_WIDTH, height: CANVAS_HEIGHT) agoraKit.setLiveTranscoding(transcoding) - agoraKit.startRtmpStreamWithTranscoding(rtmpURL, transcoding: transcoding) + agoraKit.startRtmpStream(withTranscoding: rtmpURL, transcoding: transcoding) } else{ agoraKit.startRtmpStreamWithoutTranscoding(rtmpURL) From 58d0c80ff01492273bb2b5c53d16bccf9a765d58 Mon Sep 17 00:00:00 2001 From: xianing Date: Mon, 14 Feb 2022 17:42:03 +0800 Subject: [PATCH 16/21] support switch camera on SuperResolution --- .../examples/advanced/SuperResolution.java | 16 ++++++++++++++-- .../res/layout/fragment_super_resolution.xml | 16 ++++++++++++++++ .../app/src/main/res/values-zh/strings.xml | 1 + .../app/src/main/res/values/strings.xml | 1 + 4 files changed, 32 insertions(+), 2 deletions(-) diff --git a/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/SuperResolution.java b/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/SuperResolution.java index df3d2c78e..63bff5263 100644 --- a/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/SuperResolution.java +++ b/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/SuperResolution.java @@ -50,7 +50,7 @@ public class SuperResolution extends BaseFragment implements View.OnClickListene private static final String TAG = SuperResolution.class.getSimpleName(); private FrameLayout fl_local, fl_remote; - private Button join, btnSuperResolution; + private Button join, btnSuperResolution, switchCamera; private EditText et_channel; private RtcEngine engine; private int myUid; @@ -73,9 +73,12 @@ public void onViewCreated(@NonNull View view, @Nullable Bundle savedInstanceStat join = view.findViewById(R.id.btn_join); btnSuperResolution = view.findViewById(R.id.btn_super_resolution); btnSuperResolution.setEnabled(false); + switchCamera = view.findViewById(R.id.btn_switch); + switchCamera.setEnabled(false); et_channel = view.findViewById(R.id.et_channel); view.findViewById(R.id.btn_join).setOnClickListener(this); view.findViewById(R.id.btn_super_resolution).setOnClickListener(this); + view.findViewById(R.id.btn_switch).setOnClickListener(this); fl_local = view.findViewById(R.id.fl_local); fl_remote = view.findViewById(R.id.fl_remote); } @@ -172,7 +175,13 @@ public void onClick(View v) } } else if(v.getId() == R.id.btn_super_resolution){ - engine.enableRemoteSuperResolution(remoteUid, !enableSuperResolution); + int ret = engine.enableRemoteSuperResolution(remoteUid, !enableSuperResolution); + if(ret!=0){ + Log.w(TAG, String.format("onWarning code %d ", ret)); + } + } + else if(v.getId() == R.id.btn_switch){ + engine.switchCamera(); } } @@ -259,6 +268,7 @@ private void joinChannel(String channelId) public void onWarning(int warn) { Log.w(TAG, String.format("onWarning code %d message %s", warn, RtcEngine.getErrorDescription(warn))); + showAlert(String.format("onWarning code %d message %s", warn, RtcEngine.getErrorDescription(warn))); } /**Reports an error during SDK runtime. @@ -421,6 +431,7 @@ public void onUserJoined(int uid, int elapsed) engine.setupRemoteVideo(new VideoCanvas(surfaceView, RENDER_MODE_HIDDEN, uid)); remoteUid = uid; btnSuperResolution.setEnabled(true); + switchCamera.setEnabled(true); }); } @@ -447,6 +458,7 @@ public void run() { remove the SurfaceView from its parent*/ engine.setupRemoteVideo(new VideoCanvas(null, RENDER_MODE_HIDDEN, uid)); btnSuperResolution.setEnabled(false); + switchCamera.setEnabled(false); } }); } diff --git a/Android/APIExample/app/src/main/res/layout/fragment_super_resolution.xml b/Android/APIExample/app/src/main/res/layout/fragment_super_resolution.xml index 06893e21e..71aef713f 100644 --- a/Android/APIExample/app/src/main/res/layout/fragment_super_resolution.xml +++ b/Android/APIExample/app/src/main/res/layout/fragment_super_resolution.xml @@ -45,6 +45,22 @@ android:enabled="false"/> + + + + + 肤色保护 屏幕共享 虚拟背景 + 摄像头切换 \ No newline at end of file diff --git a/Android/APIExample/app/src/main/res/values/strings.xml b/Android/APIExample/app/src/main/res/values/strings.xml index 7a9f60130..b92402148 100644 --- a/Android/APIExample/app/src/main/res/values/strings.xml +++ b/Android/APIExample/app/src/main/res/values/strings.xml @@ -185,4 +185,5 @@ Skin Protect Screen Share Virtual Background + switch camera From a5f201bbe92ac759c02b40bf4a55b4b7a96ff389 Mon Sep 17 00:00:00 2001 From: sbd021 Date: Mon, 21 Feb 2022 16:27:00 +0800 Subject: [PATCH 17/21] 3.6.1.1 windows x64 --- windows/.gitignore | 3 +- .../APIExample/APIExample/APIExample.vcxproj | 43 +++++++++++------ .../MediaPlayer/CAgoraMediaPlayer.cpp | 48 +++++++++---------- .../Advanced/MediaPlayer/CAgoraMediaPlayer.h | 19 ++++++-- .../AgoraRtcChannelPublishHelper.h | 8 ++-- .../APIExample/dsound/DSoundRender.cpp | 2 +- windows/APIExample/install.ps1 | 43 +++++++++++------ windows/APIExample/installThirdParty.bat | 2 +- 8 files changed, 104 insertions(+), 64 deletions(-) diff --git a/windows/.gitignore b/windows/.gitignore index 46405cfc5..8b4e2695e 100644 --- a/windows/.gitignore +++ b/windows/.gitignore @@ -258,4 +258,5 @@ libs/ ThirdParty/ -MediaPlayerPart/ \ No newline at end of file +MediaPlayerPart/ +MediaPlayerPart64/ \ No newline at end of file diff --git a/windows/APIExample/APIExample/APIExample.vcxproj b/windows/APIExample/APIExample/APIExample.vcxproj index 04de37f51..d9f29d604 100644 --- a/windows/APIExample/APIExample/APIExample.vcxproj +++ b/windows/APIExample/APIExample/APIExample.vcxproj @@ -23,7 +23,7 @@ {DB16CA2F-3910-4449-A5BD-6A602B33BE0F} MFCProj APIExample - 10.0.22000.0 + 10.0.17134.0 @@ -93,8 +93,8 @@ Level3 Disabled false - WIN32;_WINDOWS;_DEBUG;_CRT_SECURE_NO_WARNINGS;%(PreprocessorDefinitions); - $(SolutionDir)libs\include;$(solutionDir)ThirdParty\libYUV;$(ProjectDir);$(ProjectDir)RtcChannelHelperPlugin;$(solutionDir)MediaPlayerPart\include + WIN32;_WINDOWS;_DEBUG;_CRT_SECURE_NO_WARNINGS;%(PreprocessorDefinitions) + $(SolutionDir)libs\include;$(solutionDir)ThirdParty\libYUV;$(ProjectDir);$(ProjectDir)RtcChannelHelperPlugin;$(solutionDir)MediaPlayerPart\high_level_api\include MultiThreadedDLL @@ -118,7 +118,8 @@ if exist $(SolutionDir)libs (copy $(SolutionDir)libs\x86\*.dll $(SolutionDir)$(Configuration)) if exist zh-cn.ini (copy zh-cn.ini $(SolutionDir)$(Configuration)) if exist en.ini (copy en.ini $(SolutionDir)$(Configuration)) -if exist $(SolutionDir)MediaPlayerPart (copy $(SolutionDir)MediaPlayerPart\dll\AgoraMediaPlayer.dll $(SolutionDir)$(Configuration)) +if exist $(SolutionDir)MediaPlayerPart (copy $(SolutionDir)MediaPlayerPart\dll\AgoraMediaPlayer.dll $(SolutionDir)$(Configuration)) +if exist $(SolutionDir)MediaPlayerPart (copy $(SolutionDir)MediaPlayerPart\dll\libagora-player-ffmpeg.dll $(SolutionDir)$(Configuration)) @@ -135,18 +136,19 @@ if exist $(SolutionDir)MediaPlayerPart (copy $(SolutionDir)MediaPlayerPart\dll\A - Use + NotUsing Level3 Disabled true - _WINDOWS;_DEBUG;_CRT_SECURE_NO_WARNINGS;%(PreprocessorDefinitions);_WIN32_WINNT - $(SolutionDir)\libs\include;..\libs\include; + _WINDOWS;_DEBUG;_CRT_SECURE_NO_WARNINGS;%(PreprocessorDefinitions) + $(SolutionDir)libs\include;$(solutionDir)ThirdParty\libYUV;$(ProjectDir);$(ProjectDir)RtcChannelHelperPlugin;$(solutionDir)MediaPlayerPart64\high_level_api\include MultiThreadedDLL Windows - $(SolutionDir)\libs\x86_64 + $(SolutionDir)\libs\x86_64;$(SolutionDir)ThirdParty\libyuv\debug\x64;$(SolutionDir)ThirdParty\DShow\x64;$(SolutionDir)MediaPlayerPart64\lib libcmt.lib + AgoraMediaPlayer.lib;d3d9.lib;dsound.lib;winmm.lib;dxguid.lib false @@ -159,14 +161,20 @@ if exist $(SolutionDir)MediaPlayerPart (copy $(SolutionDir)MediaPlayerPart\dll\A $(IntDir);%(AdditionalIncludeDirectories) - if exist $(SolutionDir)\libs (copy $(SolutionDir)libs\x86_64\agora_rtc_sdk.dll $(SolutionDir)$(Platform)\$(Configuration)) + if exist $(SolutionDir)\libs (copy $(SolutionDir)libs\x86_64\*.dll $(SolutionDir)$(Platform)\$(Configuration)) if exist zh-cn.ini (copy zh-cn.ini $(SolutionDir)$(Platform)\$(Configuration)) if exist en.ini (copy en.ini $(SolutionDir)$(Platform)\$(Configuration)) +copy Advanced\MediaIOCustomVideoCaptrue\screen.yuv $(SolutionDir)$(Platform)\$(Configuration) +if exist $(SolutionDir)MediaPlayerPart64 (copy $(SolutionDir)MediaPlayerPart64\dll\AgoraMediaPlayer.dll $(SolutionDir)$(Platform)\$(Configuration)) +if exist $(SolutionDir)MediaPlayerPart64 (copy $(SolutionDir)MediaPlayerPart64\dll\libagora-player-ffmpeg.dll $(SolutionDir)$(Platform)\$(Configuration)) PerMonitorHighDPIAware + + $(SolutionDir)installThirdParty.bat x64 + @@ -215,22 +223,23 @@ if exist $(SolutionDir)MediaPlayerPart (copy $(SolutionDir)MediaPlayerPart\dll\A - Use + NotUsing Level3 MaxSpeed true true true - _WINDOWS;NDEBUG;_CRT_SECURE_NO_WARNINGS;%(PreprocessorDefinitions);_WIN32_WINNT - $(SolutionDir)libs\include + _WINDOWS;NDEBUG;_CRT_SECURE_NO_WARNINGS;%(PreprocessorDefinitions) + $(SolutionDir)libs\include;$(solutionDir)ThirdParty\libYUV;$(ProjectDir);$(ProjectDir)RtcChannelHelperPlugin;$(solutionDir)MediaPlayerPart64\high_level_api\include MultiThreadedDLL Windows true true - $(SolutionDir)\libs\x86_64 + $(SolutionDir)\libs\x86_64;$(SolutionDir)ThirdParty\libyuv\Release\x64;$(SolutionDir)ThirdParty\DShow\x64;$(SolutionDir)MediaPlayerPart64\lib libcmt.lib + AgoraMediaPlayer.lib;d3d9.lib;dsound.lib;winmm.lib;dxguid.lib false @@ -243,14 +252,20 @@ if exist $(SolutionDir)MediaPlayerPart (copy $(SolutionDir)MediaPlayerPart\dll\A $(IntDir);%(AdditionalIncludeDirectories) - if exist $(SolutionDir)\libs (copy $(SolutionDir)libs\x86_64\agora_rtc_sdk.dll $(SolutionDir)$(Platform)\$(Configuration)) + if exist $(SolutionDir)\libs (copy $(SolutionDir)libs\x86_64\*.dll $(SolutionDir)$(Platform)\$(Configuration)) if exist zh-cn.ini (copy zh-cn.ini $(SolutionDir)$(Platform)\$(Configuration)) if exist en.ini (copy en.ini $(SolutionDir)$(Platform)\$(Configuration)) +copy Advanced\MediaIOCustomVideoCaptrue\screen.yuv $(SolutionDir)$(Platform)\$(Configuration) +if exist $(SolutionDir)MediaPlayerPart64 (copy $(SolutionDir)MediaPlayerPart64\dll\AgoraMediaPlayer.dll $(SolutionDir)$(Platform)\$(Configuration)) +if exist $(SolutionDir)MediaPlayerPart64 (copy $(SolutionDir)MediaPlayerPart64\dll\libagora-player-ffmpeg.dll $(SolutionDir)$(Platform)\$(Configuration)) PerMonitorHighDPIAware + + $(SolutionDir)installThirdParty.bat x64 + diff --git a/windows/APIExample/APIExample/Advanced/MediaPlayer/CAgoraMediaPlayer.cpp b/windows/APIExample/APIExample/Advanced/MediaPlayer/CAgoraMediaPlayer.cpp index 79a66106b..b1c665523 100644 --- a/windows/APIExample/APIExample/Advanced/MediaPlayer/CAgoraMediaPlayer.cpp +++ b/windows/APIExample/APIExample/Advanced/MediaPlayer/CAgoraMediaPlayer.cpp @@ -427,9 +427,9 @@ LRESULT CAgoraMediaPlayer::OnmediaPlayerStateChanged(WPARAM wParam, LPARAM lPara { CString strState; CString strError; - switch ((agora::media::MEDIA_PLAYER_STATE)wParam) + switch ((agora::media::base::MEDIA_PLAYER_STATE)wParam) { - case agora::media::PLAYER_STATE_OPEN_COMPLETED: + case agora::media::base::PLAYER_STATE_OPEN_COMPLETED: strState = _T("PLAYER_STATE_OPEN_COMPLETED"); m_mediaPlayerState = mediaPLAYER_OPEN; m_btnPlay.EnableWindow(TRUE); @@ -438,25 +438,25 @@ LRESULT CAgoraMediaPlayer::OnmediaPlayerStateChanged(WPARAM wParam, LPARAM lPara m_sldVideo.SetRangeMax((int)duration); break; - case agora::media::PLAYER_STATE_OPENING: + case agora::media::base::PLAYER_STATE_OPENING: strState = _T("PLAYER_STATE_OPENING"); break; - case agora::media::PLAYER_STATE_IDLE: + case agora::media::base::PLAYER_STATE_IDLE: strState = _T("PLAYER_STATE_IDLE"); break; - case agora::media::PLAYER_STATE_PLAYING: + case agora::media::base::PLAYER_STATE_PLAYING: strState = _T("PLAYER_STATE_PLAYING"); break; - case agora::media::PLAYER_STATE_PLAYBACK_COMPLETED: + case agora::media::base::PLAYER_STATE_PLAYBACK_COMPLETED: strState = _T("PLAYER_STATE_PLAYBACK_COMPLETED"); break; - case agora::media::PLAYER_STATE_PAUSED: + case agora::media::base::PLAYER_STATE_PAUSED: strState = _T("PLAYER_STATE_PAUSED"); break; - case agora::media::PLAYER_STATE_STOPPED: + /*case agora::media::base::PLAYER_STATE_STOPPED: strState = _T("PLAYER_STATE_PAUSED"); - break; - case agora::media::PLAYER_STATE_FAILED: + break;*/ + case agora::media::base::PLAYER_STATE_FAILED: strState = _T("PLAYER_STATE_FAILED"); //call media player stop function m_mediaPlayer->stop(); @@ -466,42 +466,40 @@ LRESULT CAgoraMediaPlayer::OnmediaPlayerStateChanged(WPARAM wParam, LPARAM lPara break; } - switch ((agora::media::MEDIA_PLAYER_ERROR)lParam) + switch ((agora::media::base::MEDIA_PLAYER_ERROR)lParam) { - case agora::media::PLAYER_ERROR_URL_NOT_FOUND: + case agora::media::base::PLAYER_ERROR_URL_NOT_FOUND: strError = _T("PLAYER_ERROR_URL_NOT_FOUND"); break; - case agora::media::PLAYER_ERROR_NONE: + case agora::media::base::PLAYER_ERROR_NONE: strError = _T("PLAYER_ERROR_NONE"); break; - case agora::media::PLAYER_ERROR_CODEC_NOT_SUPPORTED: + case agora::media::base::PLAYER_ERROR_CODEC_NOT_SUPPORTED: strError = _T("PLAYER_ERROR_NONE"); break; - case agora::media::PLAYER_ERROR_INVALID_ARGUMENTS: + case agora::media::base::PLAYER_ERROR_INVALID_ARGUMENTS: strError = _T("PLAYER_ERROR_INVALID_ARGUMENTS"); break; - case agora::media::PLAY_ERROR_SRC_BUFFER_UNDERFLOW: - strError = _T("PLAY_ERROR_SRC_BUFFER_UNDERFLOW"); - break; - case agora::media::PLAYER_ERROR_INTERNAL: + + case agora::media::base::PLAYER_ERROR_INTERNAL: strError = _T("PLAYER_ERROR_INTERNAL"); break; - case agora::media::PLAYER_ERROR_INVALID_STATE: + case agora::media::base::PLAYER_ERROR_INVALID_STATE: strError = _T("PLAYER_ERROR_INVALID_STATE"); break; - case agora::media::PLAYER_ERROR_NO_RESOURCE: + case agora::media::base::PLAYER_ERROR_NO_RESOURCE: strError = _T("PLAYER_ERROR_NO_RESOURCE"); break; - case agora::media::PLAYER_ERROR_OBJ_NOT_INITIALIZED: + case agora::media::base::PLAYER_ERROR_OBJ_NOT_INITIALIZED: strError = _T("PLAYER_ERROR_OBJ_NOT_INITIALIZED"); break; - case agora::media::PLAYER_ERROR_INVALID_CONNECTION_STATE: + case agora::media::base::PLAYER_ERROR_INVALID_CONNECTION_STATE: strError = _T("PLAYER_ERROR_INVALID_CONNECTION_STATE"); break; - case agora::media::PLAYER_ERROR_UNKNOWN_STREAM_TYPE: + case agora::media::base::PLAYER_ERROR_UNKNOWN_STREAM_TYPE: strError = _T("PLAYER_ERROR_UNKNOWN_STREAM_TYPE"); break; - case agora::media::PLAYER_ERROR_VIDEO_RENDER_FAILED: + case agora::media::base::PLAYER_ERROR_VIDEO_RENDER_FAILED: strError = _T("PLAYER_ERROR_VIDEO_RENDER_FAILED"); break; } diff --git a/windows/APIExample/APIExample/Advanced/MediaPlayer/CAgoraMediaPlayer.h b/windows/APIExample/APIExample/Advanced/MediaPlayer/CAgoraMediaPlayer.h index d29a02899..70b7930c2 100644 --- a/windows/APIExample/APIExample/Advanced/MediaPlayer/CAgoraMediaPlayer.h +++ b/windows/APIExample/APIExample/Advanced/MediaPlayer/CAgoraMediaPlayer.h @@ -16,8 +16,8 @@ class AgoraMediaPlayerEvent : public AgoraRtcChannelPublishHelperObserver * @param state New player state * @param ec Player error message */ - virtual void onPlayerStateChanged(agora::media::MEDIA_PLAYER_STATE state, - agora::media::MEDIA_PLAYER_ERROR ec) + virtual void onPlayerStateChanged(agora::media::base::MEDIA_PLAYER_STATE state, + agora::media::base::MEDIA_PLAYER_ERROR ec) { ::PostMessage(m_hMsgHanlder, WM_MSGID(mediaPLAYER_STATE_CHANGED), (WPARAM)state, (LPARAM) ec); @@ -37,7 +37,7 @@ class AgoraMediaPlayerEvent : public AgoraRtcChannelPublishHelperObserver * * @param event */ - virtual void onPlayerEvent(agora::media::MEDIA_PLAYER_EVENT event) + virtual void onPlayerEvent(agora::media::base::MEDIA_PLAYER_EVENT event) { }; @@ -49,12 +49,23 @@ class AgoraMediaPlayerEvent : public AgoraRtcChannelPublishHelperObserver * @param data data * @param length data length */ - virtual void onMetadata(agora::media::MEDIA_PLAYER_METADATA_TYPE type, const uint8_t* data, + virtual void onMetadata(agora::media::base::MEDIA_PLAYER_METADATA_TYPE type, const uint8_t* data, uint32_t length) { } + virtual void onPreloadEvent(const char* src, media::base::PLAYER_PRELOAD_EVENT event)override { + + } + + virtual void onPlayBufferUpdated(int64_t playCachedBuffer) override { + + } + + virtual void onCompleted() override { + + } private: HWND m_hMsgHanlder; diff --git a/windows/APIExample/APIExample/RtcChannelHelperPlugin/AgoraRtcChannelPublishHelper.h b/windows/APIExample/APIExample/RtcChannelHelperPlugin/AgoraRtcChannelPublishHelper.h index cf08935e3..5cad80b99 100644 --- a/windows/APIExample/APIExample/RtcChannelHelperPlugin/AgoraRtcChannelPublishHelper.h +++ b/windows/APIExample/APIExample/RtcChannelHelperPlugin/AgoraRtcChannelPublishHelper.h @@ -16,8 +16,8 @@ class AgoraRtcChannelPublishHelperObserver : public agora::rtc::IMediaPlayerObse * @param state New player state * @param ec Player error message */ - virtual void onPlayerStateChanged(agora::media::MEDIA_PLAYER_STATE state, - agora::media::MEDIA_PLAYER_ERROR ec) + virtual void onPlayerStateChanged(agora::media::base::MEDIA_PLAYER_STATE state, + agora::media::base::MEDIA_PLAYER_ERROR ec) { } @@ -36,7 +36,7 @@ class AgoraRtcChannelPublishHelperObserver : public agora::rtc::IMediaPlayerObse * * @param event */ - virtual void onPlayerEvent(agora::media::MEDIA_PLAYER_EVENT event) + virtual void onPlayerEvent(agora::media::base::MEDIA_PLAYER_EVENT event) { }; @@ -48,7 +48,7 @@ class AgoraRtcChannelPublishHelperObserver : public agora::rtc::IMediaPlayerObse * @param data data * @param length data length */ - virtual void onMetadata(agora::media::MEDIA_PLAYER_METADATA_TYPE type, const uint8_t* data, + virtual void onMetadata(agora::media::base::MEDIA_PLAYER_METADATA_TYPE type, const uint8_t* data, uint32_t length) { diff --git a/windows/APIExample/APIExample/dsound/DSoundRender.cpp b/windows/APIExample/APIExample/dsound/DSoundRender.cpp index 8a0b1a2a3..3786ca241 100644 --- a/windows/APIExample/APIExample/dsound/DSoundRender.cpp +++ b/windows/APIExample/APIExample/dsound/DSoundRender.cpp @@ -79,7 +79,7 @@ void DSoundRender::Render(BYTE * buffer, int buffer_len) #ifdef _DEBUG TCHAR buffer[1024]; #ifdef _UNICODE - swprintf(buffer, _T("offset:%d ,data_len:%d\n"), offset, buffer_len); + swprintf_s(buffer, 1024, _T("offset:%d ,data_len:%d\n"), offset, buffer_len); #else sprintf(buffer, _T("offset:%d ,data_len:%d\n"), offset, buffer_len); #endif // _UNICODE diff --git a/windows/APIExample/install.ps1 b/windows/APIExample/install.ps1 index 94391de75..fb225abe9 100644 --- a/windows/APIExample/install.ps1 +++ b/windows/APIExample/install.ps1 @@ -1,10 +1,14 @@ $ThirdPartysrc = 'https://agora-adc-artifacts.oss-cn-beijing.aliyuncs.com/libs/ThirdParty.zip' $ThirdPartydes = 'ThirdParty.zip' -$agora_sdk = 'https://download.agora.io/sdk/release/Agora_Native_SDK_for_Windows_v3_6_1_FULL.zip' +$agora_sdk = 'https://download.agora.io/sdk/release/Agora_Native_SDK_for_Windows_v3_6_1_1_FULL.zip' +$agora_sdk = '' $agora_des = 'Agora_Native_SDK_for_Windows.zip' -$MediaPlayerSDK = 'https://download.agora.io/sdk/release/Agora_Media_Player_for_Windows_x86_32597_20200923_2306.zip' +$MediaPlayerSDK = 'https://download.agora.io/sdk/release/Agora_Media_Player_for_Windows_x86_rel.v1.3.0_63393_ffmpeg_player_lite_20210727_1117.zip' +$MediaPlayerSDK64 = 'https://download.agora.io/sdk/release/Agora_Media_Player_for_Windows_x64_rel.v1.3.0_63392_ffmpeg_player_lite_20210727_1117.zip' $MediaPlayerDes = 'MediaPlayerPartSave.zip' +$MediaPlayerDes64 = 'MediaPlayerPartSave.zip' +$arch = $args[0] if (-not (Test-Path ThirdParty)){ echo "download $ThirdPartydes" @@ -27,15 +31,26 @@ if (-not (Test-Path libs)){ Remove-Item Agora_Native_SDK_for_Windows_FULL -Recurse } - -if (-not (Test-Path MediaPlayerPart)){ - echo "download $MediaPlayerSDK" - mkdir MediaPlayerPart - (New-Object System.Net.WebClient).DownloadFile($MediaPlayerSDK,$MediaPlayerDes) - Unblock-File $MediaPlayerDes - Expand-Archive -Path $MediaPlayerDes -DestinationPath . -Force - Move-Item Agora_Media_Player_for_Windows_x86_tongjiangyong_32597_20200923_2306\sdk\* MediaPlayerPart - Remove-Item $MediaPlayerDes -Recurse - Remove-Item Agora_Media_Player_for_Windows_x86_tongjiangyong_32597_20200923_2306 -Recurse -} - +if($arch -eq 'x64'){ + if (-not (Test-Path MediaPlayerPart64)){ + echo "download $MediaPlayerSDK64" + mkdir MediaPlayerPart64 + (New-Object System.Net.WebClient).DownloadFile($MediaPlayerSDK64,$MediaPlayerDes) + Unblock-File $MediaPlayerDes + Expand-Archive -Path $MediaPlayerDes -DestinationPath . -Force + Move-Item Agora_Media_Player_for_Windows_x64_rel.v1.3.0_63392_ffmpeg_player_lite_20210727_1117\sdk\* MediaPlayerPart64 + Remove-Item $MediaPlayerDes -Recurse + Remove-Item Agora_Media_Player_for_Windows_x64_rel.v1.3.0_63392_ffmpeg_player_lite_20210727_1117 -Recurse + } +}else{ + if (-not (Test-Path MediaPlayerPart)){ + echo "download $MediaPlayerSDK" + mkdir MediaPlayerPart + (New-Object System.Net.WebClient).DownloadFile($MediaPlayerSDK,$MediaPlayerDes) + Unblock-File $MediaPlayerDes + Expand-Archive -Path $MediaPlayerDes -DestinationPath . -Force + Move-Item Agora_Media_Player_for_Windows_x86_rel.v1.3.0_63393_ffmpeg_player_lite_20210727_1117\sdk\* MediaPlayerPart + Remove-Item $MediaPlayerDes -Recurse + Remove-Item Agora_Media_Player_for_Windows_x86_rel.v1.3.0_63393_ffmpeg_player_lite_20210727_1117 -Recurse + } +} \ No newline at end of file diff --git a/windows/APIExample/installThirdParty.bat b/windows/APIExample/installThirdParty.bat index 003ad0881..568cb2f97 100644 --- a/windows/APIExample/installThirdParty.bat +++ b/windows/APIExample/installThirdParty.bat @@ -7,4 +7,4 @@ if not exist .\libs ( ) powershell.exe -command ^ - "& {set-executionpolicy Remotesigned -Scope Process; ./'install.ps1'}" + "& {set-executionpolicy Remotesigned -Scope Process; ./'install.ps1' '%1'}" From 08c043fb1d74c925823db41fce2ae3d6987f437c Mon Sep 17 00:00:00 2001 From: sbd021 Date: Mon, 21 Feb 2022 16:54:52 +0800 Subject: [PATCH 18/21] windows multiprocess 64 and update readme --- windows/APIExample/APIExample.sln | 6 +- .../APIExample/APIExample/APIExample.vcxproj | 5 +- .../ProcessScreenShare.vcxproj | 95 ++++++++++++++++++- windows/APIExample/installThirdParty_x64.bat | 10 ++ windows/APIExample/installThirdParty_x86.bat | 10 ++ windows/README.md | 4 +- windows/README.zh.md | 2 +- 7 files changed, 125 insertions(+), 7 deletions(-) create mode 100644 windows/APIExample/installThirdParty_x64.bat create mode 100644 windows/APIExample/installThirdParty_x86.bat diff --git a/windows/APIExample/APIExample.sln b/windows/APIExample/APIExample.sln index f4809a6b7..c0c9a6862 100644 --- a/windows/APIExample/APIExample.sln +++ b/windows/APIExample/APIExample.sln @@ -25,10 +25,12 @@ Global {DB16CA2F-3910-4449-A5BD-6A602B33BE0F}.Release|x64.Build.0 = Release|x64 {2B345C3C-4BEA-4DA3-B754-43F9AD219D4A}.Debug|Win32.ActiveCfg = Debug|Win32 {2B345C3C-4BEA-4DA3-B754-43F9AD219D4A}.Debug|Win32.Build.0 = Debug|Win32 - {2B345C3C-4BEA-4DA3-B754-43F9AD219D4A}.Debug|x64.ActiveCfg = Debug|Win32 + {2B345C3C-4BEA-4DA3-B754-43F9AD219D4A}.Debug|x64.ActiveCfg = Debug|x64 + {2B345C3C-4BEA-4DA3-B754-43F9AD219D4A}.Debug|x64.Build.0 = Debug|x64 {2B345C3C-4BEA-4DA3-B754-43F9AD219D4A}.Release|Win32.ActiveCfg = Release|Win32 {2B345C3C-4BEA-4DA3-B754-43F9AD219D4A}.Release|Win32.Build.0 = Release|Win32 - {2B345C3C-4BEA-4DA3-B754-43F9AD219D4A}.Release|x64.ActiveCfg = Release|Win32 + {2B345C3C-4BEA-4DA3-B754-43F9AD219D4A}.Release|x64.ActiveCfg = Debug|x64 + {2B345C3C-4BEA-4DA3-B754-43F9AD219D4A}.Release|x64.Build.0 = Debug|x64 EndGlobalSection GlobalSection(SolutionProperties) = preSolution HideSolutionNode = FALSE diff --git a/windows/APIExample/APIExample/APIExample.vcxproj b/windows/APIExample/APIExample/APIExample.vcxproj index d9f29d604..80db3b8fe 100644 --- a/windows/APIExample/APIExample/APIExample.vcxproj +++ b/windows/APIExample/APIExample/APIExample.vcxproj @@ -131,7 +131,7 @@ if exist $(SolutionDir)MediaPlayerPart (copy $(SolutionDir)MediaPlayerPart\dll\l $(IntDir)$(TargetName)$(TargetExt).embed.manifest.res - $(SolutionDir)installThirdParty.bat + $(SolutionDir)installThirdParty.bat x86 @@ -220,6 +220,9 @@ if exist $(SolutionDir)MediaPlayerPart (copy $(SolutionDir)MediaPlayerPart\dll\A PerMonitorHighDPIAware + + $(SolutionDir)installThirdParty) x86 + diff --git a/windows/APIExample/APIExample/Advanced/MultiVideoSource/ProcessScreenShare/ProcessScreenShare.vcxproj b/windows/APIExample/APIExample/Advanced/MultiVideoSource/ProcessScreenShare/ProcessScreenShare.vcxproj index 4cb80f7d5..4e3fb1d93 100644 --- a/windows/APIExample/APIExample/Advanced/MultiVideoSource/ProcessScreenShare/ProcessScreenShare.vcxproj +++ b/windows/APIExample/APIExample/Advanced/MultiVideoSource/ProcessScreenShare/ProcessScreenShare.vcxproj @@ -5,10 +5,18 @@ Debug Win32 + + Debug + x64 + Release Win32 + + Release + x64 + {2B345C3C-4BEA-4DA3-B754-43F9AD219D4A} @@ -24,6 +32,13 @@ Unicode Dynamic + + Application + true + v141 + Unicode + Dynamic + Application false @@ -32,26 +47,50 @@ Unicode Dynamic + + Application + false + v141 + true + Unicode + Dynamic + + + + + + + + true + $(VC_IncludePath);$(WindowsSDK_IncludePath); + $(VC_LibraryPath_x86);$(WindowsSDK_LibraryPath_x86); + + true $(VC_IncludePath);$(WindowsSDK_IncludePath);../../../sdk/include;../sdk/include;../openLive/ - $(VC_LibraryPath_x86);$(WindowsSDK_LibraryPath_x86);../../../sdk/lib;../sdk/lib; + $(VC_LibraryPath_x64);$(WindowsSDK_LibraryPath_x64);$(WindowsSdk_71A_LibraryPath_x64); false $(VC_IncludePath);$(WindowsSDK_IncludePath);$(WindowsSdk_71A_IncludePath);../../../sdk/include;../sdk/include;../openLive/ $(VC_LibraryPath_x86);$(WindowsSDK_LibraryPath_x86);$(WindowsSdk_71A_LibraryPath_x86);../../../sdk/lib;../sdk/lib; + + false + $(VC_IncludePath);$(WindowsSDK_IncludePath);$(WindowsSdk_71A_IncludePath);../../../sdk/include;../sdk/include;../openLive/ + $(VC_LibraryPath_x64);$(WindowsSDK_LibraryPath_x64);$(WindowsSdk_71A_LibraryPath_x64); + Use @@ -77,6 +116,30 @@ $(IntDir);%(AdditionalIncludeDirectories) + + + Use + Level3 + Disabled + WIN32;_WINDOWS;_DEBUG;%(PreprocessorDefinitions) + true + $(SolutionDir)libs\include;$(solutionDir)ThirdParty\libYUV;$(ProjectDir); + + + Windows + true + $(SolutionDir)libs\x86_64;$(SolutionDir)ThirdParty\libyuv\$(Configuration); + + + false + _DEBUG;%(PreprocessorDefinitions) + + + 0x0409 + _DEBUG;%(PreprocessorDefinitions) + $(IntDir);%(AdditionalIncludeDirectories) + + Level3 @@ -106,6 +169,34 @@ $(IntDir);%(AdditionalIncludeDirectories) + + + Level3 + Use + MaxSpeed + true + true + WIN32;_WINDOWS;NDEBUG;%(PreprocessorDefinitions) + true + $(SolutionDir)libs\include;$(solutionDir)ThirdParty\libYUV;$(ProjectDir); + + + Windows + true + true + true + $(SolutionDir)libs\x86_64;$(SolutionDir)ThirdParty\libyuv\$(Configuration);$(SolutionDir) + + + false + NDEBUG;%(PreprocessorDefinitions) + + + 0x0409 + NDEBUG;%(PreprocessorDefinitions) + $(IntDir);%(AdditionalIncludeDirectories) + + @@ -123,7 +214,9 @@ Create + Create Create + Create diff --git a/windows/APIExample/installThirdParty_x64.bat b/windows/APIExample/installThirdParty_x64.bat new file mode 100644 index 000000000..d76beb098 --- /dev/null +++ b/windows/APIExample/installThirdParty_x64.bat @@ -0,0 +1,10 @@ +cd /d %~dp0 + +if not exist .\libs ( + if exist ..\..\..\libs ( + echo d | xcopy ..\..\..\libs .\libs /Y /E /Q + ) +) + +powershell.exe -command ^ + "& {set-executionpolicy Remotesigned -Scope Process; ./'install.ps1' 'x64'}" diff --git a/windows/APIExample/installThirdParty_x86.bat b/windows/APIExample/installThirdParty_x86.bat new file mode 100644 index 000000000..40901bca5 --- /dev/null +++ b/windows/APIExample/installThirdParty_x86.bat @@ -0,0 +1,10 @@ +cd /d %~dp0 + +if not exist .\libs ( + if exist ..\..\..\libs ( + echo d | xcopy ..\..\..\libs .\libs /Y /E /Q + ) +) + +powershell.exe -command ^ + "& {set-executionpolicy Remotesigned -Scope Process; ./'install.ps1' 'x86'}" diff --git a/windows/README.md b/windows/README.md index b2e1021ce..d5aee1a12 100644 --- a/windows/README.md +++ b/windows/README.md @@ -50,9 +50,9 @@ The project uses a single program to combine a variety of functionalities. Each 1. Navigate to the **windows** folder and run following command to install project dependencies: ```shell - $ installThirdParty.bat + $ installThirdParty_x86.bat or installThirdParty_x64.bat. You can also go to next step. It will download depdencies when build solution. ``` - + **Note:** If you encounter ps1 script errors, you may need to update your powershell. diff --git a/windows/README.zh.md b/windows/README.zh.md index 41e8dd2bc..09edd9392 100644 --- a/windows/README.zh.md +++ b/windows/README.zh.md @@ -53,7 +53,7 @@ _[English](README.md) | 中文_ 1. 在 **windows** 目录下运行 `installThirdParty.bat` 文件安装依赖项: ```shell - $ installThirdParty.bat + $ installThirdParty_x86.bat 或者installThirdParty_x64.bat。也可以直接到下一步，当build solution的时候会直接下载依赖库。 ``` **注意:** From 13d284926956df230f48d1e68a606594999fa59c Mon Sep 17 00:00:00 2001 From: xianing Date: Wed, 23 Feb 2022 08:46:31 +0800 Subject: [PATCH 19/21] android ready for 3.6.2 --- Android/APIExample/lib-component/build.gradle | 1 + 1 file changed, 1 insertion(+) diff --git a/Android/APIExample/lib-component/build.gradle b/Android/APIExample/lib-component/build.gradle index 7f133c262..ac4ede6df 100644 --- a/Android/APIExample/lib-component/build.gradle +++ b/Android/APIExample/lib-component/build.gradle @@ -32,5 +32,6 @@ dependencies { api 'io.agora.rtc:full-sdk:3.6.2' api 'io.agora:player:1.3.0' + api 'io.agora.rtc:full-screen-sharing:3.6.2' } From 9707408c09f5b1c04ba64a73ccc1c8234a239959 Mon Sep 17 00:00:00 2001 From: xianing Date: Mon, 28 Feb 2022 21:52:20 +0800 Subject: [PATCH 20/21] new java video/audio raw data process --- .../io/agora/api/example/ExampleActivity.java | 4 - .../advanced/ProcessAudioRawData.java | 475 ------------------ .../examples/advanced/ProcessRawData.java | 362 ++++++++----- .../io/agora/api/example/utils/YUVUtils.java | 27 + .../res/layout/fragment_process_rawdata.xml | 17 +- .../main/res/layout/fragment_raw_audio.xml | 66 --- .../app/src/main/res/navigation/nav_graph.xml | 8 - .../app/src/main/res/values-zh/strings.xml | 1 + .../app/src/main/res/values/strings.xml | 1 + 9 files changed, 285 insertions(+), 676 deletions(-) delete mode 100755 Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/ProcessAudioRawData.java delete mode 100755 Android/APIExample/app/src/main/res/layout/fragment_raw_audio.xml diff --git a/Android/APIExample/app/src/main/java/io/agora/api/example/ExampleActivity.java b/Android/APIExample/app/src/main/java/io/agora/api/example/ExampleActivity.java index fa5cc0e30..2f0ddddcc 100644 --- a/Android/APIExample/app/src/main/java/io/agora/api/example/ExampleActivity.java +++ b/Android/APIExample/app/src/main/java/io/agora/api/example/ExampleActivity.java @@ -24,7 +24,6 @@ import io.agora.api.example.examples.advanced.MediaPlayerKit; import io.agora.api.example.examples.advanced.PlayAudioFiles; import io.agora.api.example.examples.advanced.PreCallTest; -import io.agora.api.example.examples.advanced.ProcessAudioRawData; import io.agora.api.example.examples.advanced.ProcessRawData; import io.agora.api.example.examples.advanced.PushExternalVideo; import io.agora.api.example.examples.advanced.ScreenShare; @@ -157,9 +156,6 @@ protected void onCreate(@Nullable Bundle savedInstanceState) { case R.id.action_mainFragment_senddatastream: fragment = new SendDataStream(); break; - case R.id.action_mainFragment_raw_audio: - fragment = new ProcessAudioRawData(); - break; case R.id.action_mainFragment_video_enhancement: fragment = new FaceBeauty(); break; diff --git a/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/ProcessAudioRawData.java b/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/ProcessAudioRawData.java deleted file mode 100755 index 8f8576503..000000000 --- a/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/ProcessAudioRawData.java +++ /dev/null @@ -1,475 +0,0 @@ -package io.agora.api.example.examples.advanced; - -import android.content.Context; -import android.os.Bundle; -import android.os.Handler; -import android.text.TextUtils; -import android.util.Log; -import android.view.LayoutInflater; -import android.view.View; -import android.view.ViewGroup; -import android.widget.Button; -import android.widget.CompoundButton; -import android.widget.EditText; -import android.widget.Switch; - -import androidx.annotation.NonNull; -import androidx.annotation.Nullable; - -import com.yanzhenjie.permission.AndPermission; -import com.yanzhenjie.permission.runtime.Permission; - -import java.io.IOException; -import java.io.InputStream; -import java.nio.ByteBuffer; - -import io.agora.api.example.R; -import io.agora.api.example.annotation.Example; -import io.agora.api.example.common.BaseFragment; -import io.agora.api.example.utils.CommonUtil; -import io.agora.rtc.AudioFrame; -import io.agora.rtc.Constants; -import io.agora.rtc.IAudioFrameObserver; -import io.agora.rtc.IRtcEngineEventHandler; -import io.agora.rtc.RtcEngine; -import io.agora.rtc.audio.AudioParams; -import io.agora.rtc.models.ChannelMediaOptions; - -import static io.agora.api.example.common.model.Examples.ADVANCED; -import static io.agora.rtc.IRtcEngineEventHandler.ClientRole.CLIENT_ROLE_BROADCASTER; - -/** - * This demo demonstrates how to make a one-to-one voice call - * - * @author cjw - */ -@Example( - index = 24, - group = ADVANCED, - name = R.string.item_raw_audio, - actionId = R.id.action_mainFragment_raw_audio, - tipsId = R.string.rawaudio -) -public class ProcessAudioRawData extends BaseFragment implements View.OnClickListener, CompoundButton.OnCheckedChangeListener { - private static final String TAG = ProcessAudioRawData.class.getSimpleName(); - private EditText et_channel; - private Button mute, join, speaker; - private Switch writeBackAudio; - private RtcEngine engine; - private int myUid; - private boolean joined = false; - private boolean isWriteBackAudio = false; - private static final Integer SAMPLE_RATE = 44100; - private static final Integer SAMPLE_NUM_OF_CHANNEL = 2; - private static final Integer BIT_PER_SAMPLE = 16; - private static final Integer SAMPLES_PER_CALL = 4410; - private static final String AUDIO_FILE = "output.raw"; - private InputStream inputStream; - - @Override - public void onCreate(@Nullable Bundle savedInstanceState) { - super.onCreate(savedInstanceState); - handler = new Handler(); - } - - @Nullable - @Override - public View onCreateView(@NonNull LayoutInflater inflater, @Nullable ViewGroup container, @Nullable Bundle savedInstanceState) { - View view = inflater.inflate(R.layout.fragment_raw_audio, container, false); - return view; - } - - @Override - public void onViewCreated(@NonNull View view, @Nullable Bundle savedInstanceState) { - super.onViewCreated(view, savedInstanceState); - join = view.findViewById(R.id.btn_join); - et_channel = view.findViewById(R.id.et_channel); - view.findViewById(R.id.btn_join).setOnClickListener(this); - mute = view.findViewById(R.id.btn_mute); - mute.setOnClickListener(this); - speaker = view.findViewById(R.id.btn_speaker); - speaker.setOnClickListener(this); - writeBackAudio = view.findViewById(R.id.audioWriteBack); - writeBackAudio.setOnCheckedChangeListener(this); - } - - @Override - public void onActivityCreated(@Nullable Bundle savedInstanceState) { - super.onActivityCreated(savedInstanceState); - // Check if the context is valid - Context context = getContext(); - if (context == null) { - return; - } - try { - /**Creates an RtcEngine instance. - * @param context The context of Android Activity - * @param appId The App ID issued to you by Agora. See - * How to get the App ID - * @param handler IRtcEngineEventHandler is an abstract class providing default implementation. - * The SDK uses this class to report to the app on SDK runtime events.*/ - String appId = getString(R.string.agora_app_id); - engine = RtcEngine.create(getContext().getApplicationContext(), appId, iRtcEngineEventHandler); - openAudioFile(); - } - catch (Exception e) { - e.printStackTrace(); - getActivity().onBackPressed(); - } - } - - @Override - public void onDestroy() { - super.onDestroy(); - /**leaveChannel and Destroy the RtcEngine instance*/ - if (engine != null) { - engine.leaveChannel(); - } - handler.post(RtcEngine::destroy); - engine = null; - closeAudioFile(); - } - - private void openAudioFile(){ - try { - inputStream = this.getResources().getAssets().open(AUDIO_FILE); - } catch (IOException e) { - e.printStackTrace(); - } - } - - private void closeAudioFile(){ - try { - inputStream.close(); - } catch (IOException e) { - e.printStackTrace(); - } - } - - private byte[] readBuffer(){ - int byteSize = SAMPLES_PER_CALL * BIT_PER_SAMPLE / 8; - byte[] buffer = new byte[byteSize]; - try { - if(inputStream.read(buffer) < 0){ - inputStream.reset(); - return readBuffer(); - } - } catch (IOException e) { - e.printStackTrace(); - } - return buffer; - } - - private byte[] audioAggregate(byte[] origin, byte[] buffer) { - byte[] output = new byte[origin.length]; - for (int i = 0; i < origin.length; i++) { - output[i] = (byte) ((int) origin[i] + (int) buffer[i] / 2); - } - return output; - } - - @Override - public void onClick(View v) { - if (v.getId() == R.id.btn_join) { - if (!joined) { - CommonUtil.hideInputBoard(getActivity(), et_channel); - // call when join button hit - String channelId = et_channel.getText().toString(); - // Check permission - if (AndPermission.hasPermissions(this, Permission.Group.STORAGE, Permission.Group.MICROPHONE, Permission.Group.CAMERA)) { - joinChannel(channelId); - return; - } - // Request permission - AndPermission.with(this).runtime().permission( - Permission.Group.STORAGE, - Permission.Group.MICROPHONE - ).onGranted(permissions -> - { - // Permissions Granted - joinChannel(channelId); - }).start(); - } else { - joined = false; - /**After joining a channel, the user must call the leaveChannel method to end the - * call before joining another channel. This method returns 0 if the user leaves the - * channel and releases all resources related to the call. This method call is - * asynchronous, and the user has not exited the channel when the method call returns. - * Once the user leaves the channel, the SDK triggers the onLeaveChannel callback. - * A successful leaveChannel method call triggers the following callbacks: - * 1:The local client: onLeaveChannel. - * 2:The remote client: onUserOffline, if the user leaving the channel is in the - * Communication channel, or is a BROADCASTER in the Live Broadcast profile. - * @returns 0: Success. - * < 0: Failure. - * PS: - * 1:If you call the destroy method immediately after calling the leaveChannel - * method, the leaveChannel process interrupts, and the SDK does not trigger - * the onLeaveChannel callback. - * 2:If you call the leaveChannel method during CDN live streaming, the SDK - * triggers the removeInjectStreamUrl method.*/ - engine.leaveChannel(); - join.setText(getString(R.string.join)); - speaker.setText(getString(R.string.speaker)); - speaker.setEnabled(false); - mute.setText(getString(R.string.closemicrophone)); - mute.setEnabled(false); - } - } else if (v.getId() == R.id.btn_mute) { - mute.setActivated(!mute.isActivated()); - mute.setText(getString(mute.isActivated() ? R.string.openmicrophone : R.string.closemicrophone)); - /**Turn off / on the microphone, stop / start local audio collection and push streaming.*/ - engine.muteLocalAudioStream(mute.isActivated()); - } else if (v.getId() == R.id.btn_speaker) { - speaker.setActivated(!speaker.isActivated()); - speaker.setText(getString(speaker.isActivated() ? R.string.earpiece : R.string.speaker)); - /**Turn off / on the speaker and change the audio playback route.*/ - engine.setEnableSpeakerphone(speaker.isActivated()); - } - } - - /** - * @param channelId Specify the channel name that you want to join. - * Users that input the same channel name join the same channel. - */ - private void joinChannel(String channelId) { - /** Sets the channel profile of the Agora RtcEngine. - CHANNEL_PROFILE_COMMUNICATION(0): (Default) The Communication profile. - Use this profile in one-on-one calls or group calls, where all users can talk freely. - CHANNEL_PROFILE_LIVE_BROADCASTING(1): The Live-Broadcast profile. Users in a live-broadcast - channel have a role as either broadcaster or audience. A broadcaster can both send and receive streams; - an audience can only receive streams.*/ - engine.setChannelProfile(Constants.CHANNEL_PROFILE_LIVE_BROADCASTING); - /**In the demo, the default is to enter as the anchor.*/ - engine.setClientRole(CLIENT_ROLE_BROADCASTER); - /**Please configure accessToken in the string_config file. - * A temporary token generated in Console. A temporary token is valid for 24 hours. For details, see - * https://docs.agora.io/en/Agora%20Platform/token?platform=All%20Platforms#get-a-temporary-token - * A token generated at the server. This applies to scenarios with high-security requirements. For details, see - * https://docs.agora.io/en/cloud-recording/token_server_java?platform=Java*/ - String accessToken = getString(R.string.agora_access_token); - if (TextUtils.equals(accessToken, "") || TextUtils.equals(accessToken, "<#YOUR ACCESS TOKEN#>")) { - accessToken = null; - } - /** Allows a user to join a channel. - if you do not specify the uid, we will generate the uid for you*/ - engine.enableAudioVolumeIndication(1000, 3, true); - - ChannelMediaOptions option = new ChannelMediaOptions(); - option.autoSubscribeAudio = true; - option.autoSubscribeVideo = true; - int res = engine.joinChannel(accessToken, channelId, "Extra Optional Data", 0, option); - if (res != 0) { - // Usually happens with invalid parameters - // Error code description can be found at: - // en: https://docs.agora.io/en/Voice/API%20Reference/java/classio_1_1agora_1_1rtc_1_1_i_rtc_engine_event_handler_1_1_error_code.html - // cn: https://docs.agora.io/cn/Voice/API%20Reference/java/classio_1_1agora_1_1rtc_1_1_i_rtc_engine_event_handler_1_1_error_code.html - showAlert(RtcEngine.getErrorDescription(Math.abs(res))); - Log.e(TAG, RtcEngine.getErrorDescription(Math.abs(res))); - return; - } - // Prevent repeated entry - join.setEnabled(false); - /** Registers the audio observer object. - * - * @param observer Audio observer object to be registered. See {@link IAudioFrameObserver IAudioFrameObserver}. Set the value as @p null to cancel registering, if necessary. - * @return - * - 0: Success. - * - < 0: Failure. - */ - engine.registerAudioFrameObserver(audioFrameObserver); - } - - /** - * IRtcEngineEventHandler is an abstract class providing default implementation. - * The SDK uses this class to report to the app on SDK runtime events. - */ - private final IRtcEngineEventHandler iRtcEngineEventHandler = new IRtcEngineEventHandler() { - - /**Reports a warning during SDK runtime. - * Warning code: https://docs.agora.io/en/Voice/API%20Reference/java/classio_1_1agora_1_1rtc_1_1_i_rtc_engine_event_handler_1_1_warn_code.html*/ - @Override - public void onWarning(int warn) { - Log.w(TAG, String.format("onWarning code %d message %s", warn, RtcEngine.getErrorDescription(warn))); - } - - /**Reports an error during SDK runtime. - * Error code: https://docs.agora.io/en/Voice/API%20Reference/java/classio_1_1agora_1_1rtc_1_1_i_rtc_engine_event_handler_1_1_error_code.html*/ - @Override - public void onError(int err) { - Log.e(TAG, String.format("onError code %d message %s", err, RtcEngine.getErrorDescription(err))); - showAlert(String.format("onError code %d message %s", err, RtcEngine.getErrorDescription(err))); - } - - /**Occurs when a user leaves the channel. - * @param stats With this callback, the application retrieves the channel information, - * such as the call duration and statistics.*/ - @Override - public void onLeaveChannel(RtcStats stats) { - super.onLeaveChannel(stats); - Log.i(TAG, String.format("local user %d leaveChannel!", myUid)); - showLongToast(String.format("local user %d leaveChannel!", myUid)); - } - - /**Occurs when the local user joins a specified channel. - * The channel name assignment is based on channelName specified in the joinChannel method. - * If the uid is not specified when joinChannel is called, the server automatically assigns a uid. - * @param channel Channel name - * @param uid User ID - * @param elapsed Time elapsed (ms) from the user calling joinChannel until this callback is triggered*/ - @Override - public void onJoinChannelSuccess(String channel, int uid, int elapsed) { - Log.i(TAG, String.format("onJoinChannelSuccess channel %s uid %d", channel, uid)); - showLongToast(String.format("onJoinChannelSuccess channel %s uid %d", channel, uid)); - myUid = uid; - joined = true; - handler.post(new Runnable() { - @Override - public void run() { - speaker.setEnabled(true); - mute.setEnabled(true); - join.setEnabled(true); - join.setText(getString(R.string.leave)); - writeBackAudio.setEnabled(true); - } - }); - } - - /**Since v2.9.0. - * This callback indicates the state change of the remote audio stream. - * PS: This callback does not work properly when the number of users (in the Communication profile) or - * broadcasters (in the Live-broadcast profile) in the channel exceeds 17. - * @param uid ID of the user whose audio state changes. - * @param state State of the remote audio - * REMOTE_AUDIO_STATE_STOPPED(0): The remote audio is in the default state, probably due - * to REMOTE_AUDIO_REASON_LOCAL_MUTED(3), REMOTE_AUDIO_REASON_REMOTE_MUTED(5), - * or REMOTE_AUDIO_REASON_REMOTE_OFFLINE(7). - * 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, - * probably due to REMOTE_AUDIO_REASON_NETWORK_RECOVERY(2), - * REMOTE_AUDIO_REASON_LOCAL_UNMUTED(4) or REMOTE_AUDIO_REASON_REMOTE_UNMUTED(6). - * REMOTE_AUDIO_STATE_FROZEN(3): The remote audio is frozen, probably due to - * REMOTE_AUDIO_REASON_NETWORK_CONGESTION(1). - * REMOTE_AUDIO_STATE_FAILED(4): The remote audio fails to start, probably due to - * REMOTE_AUDIO_REASON_INTERNAL(0). - * @param reason The reason of the remote audio state change. - * REMOTE_AUDIO_REASON_INTERNAL(0): Internal reasons. - * REMOTE_AUDIO_REASON_NETWORK_CONGESTION(1): Network congestion. - * REMOTE_AUDIO_REASON_NETWORK_RECOVERY(2): Network recovery. - * REMOTE_AUDIO_REASON_LOCAL_MUTED(3): The local user stops receiving the remote audio - * stream or disables the audio module. - * REMOTE_AUDIO_REASON_LOCAL_UNMUTED(4): The local user resumes receiving the remote audio - * stream or enables the audio module. - * REMOTE_AUDIO_REASON_REMOTE_MUTED(5): The remote user stops sending the audio stream or - * disables the audio module. - * REMOTE_AUDIO_REASON_REMOTE_UNMUTED(6): The remote user resumes sending the audio stream - * or enables the audio module. - * REMOTE_AUDIO_REASON_REMOTE_OFFLINE(7): The remote user leaves the channel. - * @param elapsed Time elapsed (ms) from the local user calling the joinChannel method - * until the SDK triggers this callback.*/ - @Override - public void onRemoteAudioStateChanged(int uid, int state, int reason, int elapsed) { - super.onRemoteAudioStateChanged(uid, state, reason, elapsed); - Log.i(TAG, "onRemoteAudioStateChanged->" + uid + ", state->" + state + ", reason->" + reason); - } - - /**Occurs when a remote user (Communication)/host (Live Broadcast) joins the channel. - * @param uid ID of the user whose audio state changes. - * @param elapsed Time delay (ms) from the local user calling joinChannel/setClientRole - * until this callback is triggered.*/ - @Override - public void onUserJoined(int uid, int elapsed) { - super.onUserJoined(uid, elapsed); - Log.i(TAG, "onUserJoined->" + uid); - showLongToast(String.format("user %d joined!", uid)); - } - - /**Occurs when a remote user (Communication)/host (Live Broadcast) leaves the channel. - * @param uid ID of the user whose audio state changes. - * @param reason Reason why the user goes offline: - * USER_OFFLINE_QUIT(0): The user left the current channel. - * USER_OFFLINE_DROPPED(1): The SDK timed out and the user dropped offline because no data - * packet was received within a certain period of time. If a 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): (Live broadcast only.) The client role switched from - * the host to the audience.*/ - @Override - public void onUserOffline(int uid, int reason) { - Log.i(TAG, String.format("user %d offline! reason:%d", uid, reason)); - showLongToast(String.format("user %d offline! reason:%d", uid, reason)); - } - - @Override - public void onActiveSpeaker(int uid) { - super.onActiveSpeaker(uid); - Log.i(TAG, String.format("onActiveSpeaker:%d", uid)); - } - }; - - private final IAudioFrameObserver audioFrameObserver = new IAudioFrameObserver() { - @Override - public boolean onRecordFrame(AudioFrame audioFrame) { - Log.i(TAG, "onRecordAudioFrame " + isWriteBackAudio); - if(isWriteBackAudio){ - ByteBuffer byteBuffer = audioFrame.samples; - byte[] buffer = readBuffer(); - byte[] origin = new byte[byteBuffer.remaining()]; - byteBuffer.get(origin); - byteBuffer.flip(); - byteBuffer.put(audioAggregate(origin, buffer), 0, byteBuffer.remaining()); - } - return true; - } - - @Override - public boolean onPlaybackFrame(AudioFrame audioFrame) { - return false; - } - - @Override - public boolean onPlaybackFrameBeforeMixing(AudioFrame audioFrame, int uid) { - return false; - } - - @Override - public boolean onMixedFrame(AudioFrame audioFrame) { - return false; - } - - @Override - public boolean isMultipleChannelFrameWanted() { - return false; - } - - @Override - public boolean onPlaybackFrameBeforeMixingEx(AudioFrame audioFrame, int uid, String channelId) { - return false; - } - - @Override - public int getObservedAudioFramePosition() { - return IAudioFrameObserver.POSITION_RECORD | IAudioFrameObserver.POSITION_MIXED; - } - - @Override - public AudioParams getRecordAudioParams() { - return new AudioParams(SAMPLE_RATE, SAMPLE_NUM_OF_CHANNEL, Constants.RAW_AUDIO_FRAME_OP_MODE_READ_WRITE, SAMPLES_PER_CALL); - } - - @Override - public AudioParams getPlaybackAudioParams() { - return new AudioParams(SAMPLE_RATE, SAMPLE_NUM_OF_CHANNEL, Constants.RAW_AUDIO_FRAME_OP_MODE_READ_ONLY, SAMPLES_PER_CALL); - } - - @Override - public AudioParams getMixedAudioParams() { - return new AudioParams(SAMPLE_RATE, SAMPLE_NUM_OF_CHANNEL, Constants.RAW_AUDIO_FRAME_OP_MODE_READ_ONLY, SAMPLES_PER_CALL); - } - }; - - @Override - public void onCheckedChanged(CompoundButton compoundButton, boolean b) { - isWriteBackAudio = b; - } -} diff --git a/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/ProcessRawData.java b/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/ProcessRawData.java index dfdaa5cb1..71452bfb6 100644 --- a/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/ProcessRawData.java +++ b/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/ProcessRawData.java @@ -1,8 +1,15 @@ package io.agora.api.example.examples.advanced; +import android.content.ContentResolver; +import android.content.ContentValues; import android.content.Context; import android.graphics.Bitmap; +import android.graphics.Matrix; +import android.net.Uri; +import android.os.Build; import android.os.Bundle; +import android.os.Environment; +import android.provider.MediaStore; import android.text.TextUtils; import android.util.Log; import android.view.LayoutInflater; @@ -10,8 +17,10 @@ import android.view.View; import android.view.ViewGroup; import android.widget.Button; +import android.widget.CompoundButton; import android.widget.EditText; import android.widget.FrameLayout; +import android.widget.Switch; import androidx.annotation.NonNull; import androidx.annotation.Nullable; @@ -19,19 +28,27 @@ import com.yanzhenjie.permission.AndPermission; import com.yanzhenjie.permission.runtime.Permission; +import java.io.File; +import java.io.IOException; +import java.io.InputStream; +import java.io.OutputStream; +import java.nio.ByteBuffer; + import io.agora.advancedvideo.rawdata.MediaDataAudioObserver; -import io.agora.advancedvideo.rawdata.MediaDataObserverPlugin; import io.agora.advancedvideo.rawdata.MediaDataVideoObserver; -import io.agora.advancedvideo.rawdata.MediaPreProcessing; import io.agora.api.example.MainApplication; import io.agora.api.example.R; import io.agora.api.example.annotation.Example; import io.agora.api.example.common.BaseFragment; import io.agora.api.example.utils.CommonUtil; import io.agora.api.example.utils.YUVUtils; +import io.agora.rtc.AudioFrame; import io.agora.rtc.Constants; +import io.agora.rtc.IAudioFrameObserver; import io.agora.rtc.IRtcEngineEventHandler; +import io.agora.rtc.IVideoFrameObserver; import io.agora.rtc.RtcEngine; +import io.agora.rtc.audio.AudioParams; import io.agora.rtc.models.ChannelMediaOptions; import io.agora.rtc.video.VideoCanvas; import io.agora.rtc.video.VideoEncoderConfiguration; @@ -39,10 +56,7 @@ import static io.agora.api.example.common.model.Examples.ADVANCED; import static io.agora.rtc.Constants.RAW_AUDIO_FRAME_OP_MODE_READ_ONLY; import static io.agora.rtc.video.VideoCanvas.RENDER_MODE_HIDDEN; -import static io.agora.rtc.video.VideoEncoderConfiguration.FRAME_RATE.FRAME_RATE_FPS_15; -import static io.agora.rtc.video.VideoEncoderConfiguration.ORIENTATION_MODE.ORIENTATION_MODE_ADAPTIVE; import static io.agora.rtc.video.VideoEncoderConfiguration.STANDARD_BITRATE; -import static io.agora.rtc.video.VideoEncoderConfiguration.VD_640x360; @Example( index = 10, @@ -51,17 +65,22 @@ actionId = R.id.action_mainFragment_to_ProcessRawData, tipsId = R.string.processrawdata ) -public class ProcessRawData extends BaseFragment implements View.OnClickListener, MediaDataVideoObserver, - MediaDataAudioObserver { +public class ProcessRawData extends BaseFragment implements View.OnClickListener, CompoundButton.OnCheckedChangeListener{ private static final String TAG = ProcessRawData.class.getSimpleName(); private FrameLayout fl_local, fl_remote; - private Button join, blurBtn; + private Button join, snapshot; + private Switch audioMixingBtn; private EditText et_channel; private RtcEngine engine; private int myUid; - private boolean joined = false, blur = true; - private MediaDataObserverPlugin mediaDataObserverPlugin; + private boolean joined = false, isSnapshot = false, audioMixing = false; + private static final Integer SAMPLE_RATE = 44100; + private static final Integer SAMPLE_NUM_OF_CHANNEL = 2; + private static final Integer BIT_PER_SAMPLE = 16; + private static final Integer SAMPLES_PER_CALL = 4410; + private static final String AUDIO_FILE = "output.raw"; + private InputStream inputStream; @Override public void onCreate(@Nullable Bundle savedInstanceState) { @@ -79,6 +98,7 @@ public void onCreate(@Nullable Bundle savedInstanceState) { * @param handler IRtcEngineEventHandler is an abstract class providing default implementation. * The SDK uses this class to report to the app on SDK runtime events.*/ engine = RtcEngine.create(context.getApplicationContext(), getString(R.string.agora_app_id), iRtcEngineEventHandler); + openAudioFile(); } catch (Exception e) { e.printStackTrace(); @@ -97,10 +117,12 @@ public View onCreateView(@NonNull LayoutInflater inflater, @Nullable ViewGroup c public void onViewCreated(@NonNull View view, @Nullable Bundle savedInstanceState) { super.onViewCreated(view, savedInstanceState); join = view.findViewById(R.id.btn_join); - blurBtn = view.findViewById(R.id.btn_blur); + snapshot = view.findViewById(R.id.btn_snapshot); + audioMixingBtn = view.findViewById(R.id.btn_audio_write_back); et_channel = view.findViewById(R.id.et_channel); join.setOnClickListener(this); - blurBtn.setOnClickListener(this); + snapshot.setOnClickListener(this); + audioMixingBtn.setOnCheckedChangeListener(this); fl_local = view.findViewById(R.id.fl_local); fl_remote = view.findViewById(R.id.fl_remote); } @@ -108,26 +130,63 @@ public void onViewCreated(@NonNull View view, @Nullable Bundle savedInstanceStat @Override public void onActivityCreated(@Nullable Bundle savedInstanceState) { super.onActivityCreated(savedInstanceState); - mediaDataObserverPlugin = MediaDataObserverPlugin.the(); - MediaPreProcessing.setCallback(mediaDataObserverPlugin); - MediaPreProcessing.setVideoCaptureByteBuffer(mediaDataObserverPlugin.byteBufferCapture); - mediaDataObserverPlugin.addVideoObserver(this); } @Override public void onDestroy() { - if (mediaDataObserverPlugin != null) { - mediaDataObserverPlugin.removeVideoObserver(this); - mediaDataObserverPlugin.removeAllBuffer(); - } - MediaPreProcessing.releasePoint(); + super.onDestroy(); /**leaveChannel and Destroy the RtcEngine instance*/ if (engine != null) { engine.leaveChannel(); } handler.post(RtcEngine::destroy); engine = null; - super.onDestroy(); + closeAudioFile(); + } + + private void openAudioFile(){ + try { + inputStream = this.getResources().getAssets().open(AUDIO_FILE); + } catch (IOException e) { + e.printStackTrace(); + } + } + + private void closeAudioFile(){ + try { + inputStream.close(); + } catch (IOException e) { + e.printStackTrace(); + } + } + + private byte[] readBuffer(){ + int byteSize = SAMPLES_PER_CALL * BIT_PER_SAMPLE / 8; + byte[] buffer = new byte[byteSize]; + try { + if(inputStream.read(buffer) < 0){ + inputStream.reset(); + return readBuffer(); + } + } catch (IOException e) { + e.printStackTrace(); + } + return buffer; + } + + private byte[] audioAggregate(byte[] origin, byte[] buffer) { + byte[] output = new byte[origin.length]; + for (int i = 0; i < origin.length; i++) { + output[i] = (byte) ((int) origin[i] + (int) buffer[i] / 2); + } + return output; + } + + @Override + public void onCheckedChanged(CompoundButton buttonView, boolean isChecked) { + if (buttonView.getId() == R.id.btn_audio_write_back) { + audioMixing = isChecked; + } } @Override @@ -174,14 +233,9 @@ public void onClick(View v) { engine.leaveChannel(); join.setText(getString(R.string.join)); } - } else if (v.getId() == R.id.btn_blur) { - if (!blur) { - blur = true; - blurBtn.setText(getString(R.string.blur)); - } else { - blur = false; - blurBtn.setText(getString(R.string.closeblur)); - } + } + else if (v.getId() == R.id.btn_snapshot) { + isSnapshot = true; } } @@ -252,6 +306,8 @@ private void joinChannel(String channelId) { */ engine.setMixedAudioFrameParameters(8000, 1024); + engine.registerVideoFrameObserver(iVideoFrameObserver); + /**Please configure accessToken in the string_config file. * A temporary token generated in Console. A temporary token is valid for 24 hours. For details, see * https://docs.agora.io/en/Agora%20Platform/token?platform=All%20Platforms#get-a-temporary-token @@ -278,6 +334,108 @@ private void joinChannel(String channelId) { } // Prevent repeated entry join.setEnabled(false); + /** Registers the audio observer object. + * + * @param observer Audio observer object to be registered. See {@link IAudioFrameObserver IAudioFrameObserver}. Set the value as @p null to cancel registering, if necessary. + * @return + * - 0: Success. + * - < 0: Failure. + */ + engine.registerAudioFrameObserver(audioFrameObserver); + } + + private final IVideoFrameObserver iVideoFrameObserver = new IVideoFrameObserver() { + @Override + public boolean onCaptureVideoFrame(VideoFrame videoFrame) { + if (!isSnapshot) { + return true; + } + Log.e(TAG, "onCaptureVideoFrame start blur"); + + byte[] i420 = YUVUtils.toWrappedI420(videoFrame.yBuffer, videoFrame.uBuffer, videoFrame.vBuffer, videoFrame.width, videoFrame.height); + int chromaWidth = (videoFrame.width + 1) / 2; + int chromaHeight = (videoFrame.height + 1) / 2; + int lengthY = videoFrame.width * videoFrame.height; + int lengthU = chromaWidth * chromaHeight; + int lengthV = lengthU; + int size = lengthY + lengthU + lengthV; + Bitmap bitmap = YUVUtils.i420ToBitmap(videoFrame.width, videoFrame.height, videoFrame.rotation, size, i420, videoFrame.yStride, videoFrame.uStride, videoFrame.vStride); + + Matrix matrix = new Matrix(); + matrix.setRotate(270); + Bitmap newBitmap = Bitmap.createBitmap(bitmap, 0, 0, videoFrame.width, videoFrame.height, matrix, false); + saveBitmap2Gallery(newBitmap); + + bitmap.recycle(); + isSnapshot = false; + return true; + } + + @Override + public boolean onRenderVideoFrame(int uid, VideoFrame videoFrame) { + return false; + } + }; + + + public void saveBitmap2Gallery(Bitmap bm){ + long currentTime = System.currentTimeMillis(); + + // name the file + String imageFileName = "IMG_AGORA_"+ currentTime + ".jpg"; + String imageFilePath; + if(Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) + imageFilePath = Environment.DIRECTORY_PICTURES + File.separator + "Agora" + File.separator; + else imageFilePath = Environment.getExternalStoragePublicDirectory(Environment.DIRECTORY_PICTURES).getAbsolutePath() + + File.separator + "Agora"+ File.separator; + + // write to file + + OutputStream outputStream; + ContentResolver resolver = requireContext().getContentResolver(); + ContentValues newScreenshot = new ContentValues(); + Uri insert; + newScreenshot.put(MediaStore.Images.ImageColumns.DATE_ADDED,currentTime); + newScreenshot.put(MediaStore.Images.ImageColumns.DISPLAY_NAME, imageFileName); + newScreenshot.put(MediaStore.Images.ImageColumns.MIME_TYPE, "image/jpg"); + newScreenshot.put(MediaStore.Images.ImageColumns.WIDTH, bm.getWidth()); + newScreenshot.put(MediaStore.Images.ImageColumns.HEIGHT, bm.getHeight()); + try { + if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) { + newScreenshot.put(MediaStore.Images.ImageColumns.RELATIVE_PATH,imageFilePath); + }else{ + // make sure the path is existed + File imageFileDir = new File(imageFilePath); + if(!imageFileDir.exists()){ + boolean mkdir = imageFileDir.mkdirs(); + if(!mkdir) { + showLongToast("save failed, error: cannot create folder. Make sure app has the permission."); + return; + } + } + newScreenshot.put(MediaStore.Images.ImageColumns.DATA, imageFilePath+imageFileName); + newScreenshot.put(MediaStore.Images.ImageColumns.TITLE, imageFileName); + } + + // insert a new image + insert = resolver.insert(MediaStore.Images.Media.EXTERNAL_CONTENT_URI, newScreenshot); + // write data + outputStream = resolver.openOutputStream(insert); + + bm.compress(Bitmap.CompressFormat.PNG, 80, outputStream); + outputStream.flush(); + outputStream.close(); + + newScreenshot.clear(); + newScreenshot.put(MediaStore.Images.ImageColumns.SIZE, new File(imageFilePath).length()); + resolver.update(insert, newScreenshot, null, null); + + showLongToast("save success, you can view it in gallery"); + } catch (Exception e) { + showLongToast("save failed, error: "+ e.getMessage()); + e.printStackTrace(); + } + } /** @@ -308,6 +466,8 @@ public void onLeaveChannel(RtcStats stats) { super.onLeaveChannel(stats); Log.i(TAG, String.format("local user %d leaveChannel!", myUid)); showLongToast(String.format("local user %d leaveChannel!", myUid)); + snapshot.setEnabled(false); + audioMixingBtn.setEnabled(false); } /**Occurs when the local user joins a specified channel. @@ -326,6 +486,8 @@ public void onJoinChannelSuccess(String channel, int uid, int elapsed) { @Override public void run() { join.setEnabled(true); + snapshot.setEnabled(true); + audioMixingBtn.setEnabled(true); join.setText(getString(R.string.leave)); } }); @@ -347,10 +509,6 @@ public void onUserJoined(int uid, int elapsed) { } handler.post(() -> { - if (mediaDataObserverPlugin != null) { - mediaDataObserverPlugin.addDecodeBuffer(uid); - } - /**Display remote video stream*/ // Create render view by RtcEngine SurfaceView surfaceView = RtcEngine.CreateRendererView(context); @@ -383,9 +541,6 @@ public void onUserOffline(int uid, int reason) { handler.post(new Runnable() { @Override public void run() { - if (mediaDataObserverPlugin != null) { - mediaDataObserverPlugin.removeDecodeBuffer(uid); - } /**Clear render view Note: The video will stay at its last frame, to completely remove it you will need to remove the SurfaceView from its parent*/ @@ -395,99 +550,64 @@ public void run() { } }; - @Override - public void onCaptureVideoFrame(byte[] data, int frameType, int width, int height, int bufferLength, int yStride, int uStride, int vStride, int rotation, long renderTimeMs) { - /**You can do some processing on the video frame here*/ - if (blur) { - return; + private final IAudioFrameObserver audioFrameObserver = new IAudioFrameObserver() { + @Override + public boolean onRecordFrame(AudioFrame audioFrame) { + Log.i(TAG, "onRecordAudioFrame " + audioMixing); + if(audioMixing){ + ByteBuffer byteBuffer = audioFrame.samples; + byte[] buffer = readBuffer(); + byte[] origin = new byte[byteBuffer.remaining()]; + byteBuffer.get(origin); + byteBuffer.flip(); + byteBuffer.put(audioAggregate(origin, buffer), 0, byteBuffer.remaining()); + } + return true; } - Log.e(TAG, "onCaptureVideoFrame start blur"); - Bitmap bitmap = YUVUtils.i420ToBitmap(width, height, rotation, bufferLength, data, yStride, uStride, vStride); - Bitmap bmp = YUVUtils.blur(getContext(), bitmap, 8f); - System.arraycopy(YUVUtils.bitmapToI420(width, height, bmp), 0, data, 0, bufferLength); - } - @Override - public void onRenderVideoFrame(int uid, byte[] data, int frameType, int width, int height, int bufferLength, int yStride, int uStride, int vStride, int rotation, long renderTimeMs) { - if (blur) { - return; + @Override + public boolean onPlaybackFrame(AudioFrame audioFrame) { + return false; } - Log.e(TAG, "onRenderVideoFrame start blur"); - Bitmap bmp = YUVUtils.blur(getContext(), YUVUtils.i420ToBitmap(width, height, rotation, bufferLength, data, yStride, uStride, vStride), 8f); - System.arraycopy(YUVUtils.bitmapToI420(width, height, bmp), 0, data, 0, bufferLength); - } - - @Override - public void onPreEncodeVideoFrame(byte[] data, int frameType, int width, int height, int bufferLength, int yStride, int uStride, int vStride, int rotation, long renderTimeMs) { - /**You can do some processing on the video frame here*/ - Log.e(TAG, "onPreEncodeVideoFrame0"); - } - /** - * Retrieves the recorded audio frame. - * @param audioFrameType only support FRAME_TYPE_PCM16 - * @param samples The number of samples per channel in the audio frame. - * @param bytesPerSample The number of bytes per audio sample, which is usually 16-bit (2-byte). - * @param channels The number of audio channels. - * 1: Mono - * 2: Stereo (the data is interleaved) - * @param samplesPerSec The sample rate. - * @param renderTimeMs The timestamp of the external audio frame. - * @param bufferLength audio frame size*/ - @Override - public void onRecordAudioFrame(byte[] data, int audioFrameType, int samples, int bytesPerSample, int channels, int samplesPerSec, long renderTimeMs, int bufferLength) { - - } - - /** - * Retrieves the audio playback frame for getting the audio. - * @param audioFrameType only support FRAME_TYPE_PCM16 - * @param samples The number of samples per channel in the audio frame. - * @param bytesPerSample The number of bytes per audio sample, which is usually 16-bit (2-byte). - * @param channels The number of audio channels. - * 1: Mono - * 2: Stereo (the data is interleaved) - * @param samplesPerSec The sample rate. - * @param renderTimeMs The timestamp of the external audio frame. - * @param bufferLength audio frame size*/ - @Override - public void onPlaybackAudioFrame(byte[] data, int audioFrameType, int samples, int bytesPerSample, int channels, int samplesPerSec, long renderTimeMs, int bufferLength) { + @Override + public boolean onPlaybackFrameBeforeMixing(AudioFrame audioFrame, int uid) { + return false; + } - } + @Override + public boolean onMixedFrame(AudioFrame audioFrame) { + return false; + } + @Override + public boolean isMultipleChannelFrameWanted() { + return false; + } - /** - * Retrieves the audio frame of a specified user before mixing. - * The SDK triggers this callback if isMultipleChannelFrameWanted returns false. - * @param uid remote user id - * @param audioFrameType only support FRAME_TYPE_PCM16 - * @param samples The number of samples per channel in the audio frame. - * @param bytesPerSample The number of bytes per audio sample, which is usually 16-bit (2-byte). - * @param channels The number of audio channels. - * 1: Mono - * 2: Stereo (the data is interleaved) - * @param samplesPerSec The sample rate. - * @param renderTimeMs The timestamp of the external audio frame. - * @param bufferLength audio frame size*/ - @Override - public void onPlaybackAudioFrameBeforeMixing(int uid, byte[] data, int audioFrameType, int samples, int bytesPerSample, int channels, int samplesPerSec, long renderTimeMs, int bufferLength) { + @Override + public boolean onPlaybackFrameBeforeMixingEx(AudioFrame audioFrame, int uid, String channelId) { + return false; + } - } + @Override + public int getObservedAudioFramePosition() { + return IAudioFrameObserver.POSITION_RECORD | IAudioFrameObserver.POSITION_MIXED; + } - /** - * Retrieves the mixed recorded and playback audio frame. - * @param audioFrameType only support FRAME_TYPE_PCM16 - * @param samples The number of samples per channel in the audio frame. - * @param bytesPerSample The number of bytes per audio sample, which is usually 16-bit (2-byte). - * @param channels The number of audio channels. - * 1: Mono - * 2: Stereo (the data is interleaved) - * @param samplesPerSec The sample rate. - * @param renderTimeMs The timestamp of the external audio frame. - * @param bufferLength audio frame size*/ - @Override - public void onMixedAudioFrame(byte[] data, int audioFrameType, int samples, int bytesPerSample, int channels, int samplesPerSec, long renderTimeMs, int bufferLength) { + @Override + public AudioParams getRecordAudioParams() { + return new AudioParams(SAMPLE_RATE, SAMPLE_NUM_OF_CHANNEL, Constants.RAW_AUDIO_FRAME_OP_MODE_READ_WRITE, SAMPLES_PER_CALL); + } - } + @Override + public AudioParams getPlaybackAudioParams() { + return new AudioParams(SAMPLE_RATE, SAMPLE_NUM_OF_CHANNEL, Constants.RAW_AUDIO_FRAME_OP_MODE_READ_ONLY, SAMPLES_PER_CALL); + } + @Override + public AudioParams getMixedAudioParams() { + return new AudioParams(SAMPLE_RATE, SAMPLE_NUM_OF_CHANNEL, Constants.RAW_AUDIO_FRAME_OP_MODE_READ_ONLY, SAMPLES_PER_CALL); + } + }; } diff --git a/Android/APIExample/app/src/main/java/io/agora/api/example/utils/YUVUtils.java b/Android/APIExample/app/src/main/java/io/agora/api/example/utils/YUVUtils.java index 41dd89583..e3da4472a 100644 --- a/Android/APIExample/app/src/main/java/io/agora/api/example/utils/YUVUtils.java +++ b/Android/APIExample/app/src/main/java/io/agora/api/example/utils/YUVUtils.java @@ -14,6 +14,7 @@ import java.io.ByteArrayOutputStream; import java.io.IOException; +import java.nio.ByteBuffer; public class YUVUtils { @@ -145,4 +146,30 @@ public static byte[] bitmapToI420(int inputWidth, int inputHeight, Bitmap scaled return yuv; } + public static byte[] toWrappedI420(ByteBuffer bufferY, + ByteBuffer bufferU, + ByteBuffer bufferV, + int width, + int height) { + int chromaWidth = (width + 1) / 2; + int chromaHeight = (height + 1) / 2; + int lengthY = width * height; + int lengthU = chromaWidth * chromaHeight; + int lengthV = lengthU; + + + int size = lengthY + lengthU + lengthV; + + byte[] out = new byte[size]; + + int readY = Math.min(lengthY, bufferY.remaining()); + bufferY.get(out, 0 , readY); + int readU = Math.min(lengthU, bufferU.remaining()); + bufferU.get(out, lengthY, readU); + int readV = Math.min(lengthV, bufferV.remaining()); + bufferV.get(out, lengthY + lengthU, readV); + + return out; + } + } diff --git a/Android/APIExample/app/src/main/res/layout/fragment_process_rawdata.xml b/Android/APIExample/app/src/main/res/layout/fragment_process_rawdata.xml index fc51abf6b..eb157c553 100644 --- a/Android/APIExample/app/src/main/res/layout/fragment_process_rawdata.xml +++ b/Android/APIExample/app/src/main/res/layout/fragment_process_rawdata.xml @@ -44,12 +44,25 @@ + android:enabled="false" + android:text="@string/snapshot" /> + + diff --git a/Android/APIExample/app/src/main/res/layout/fragment_raw_audio.xml b/Android/APIExample/app/src/main/res/layout/fragment_raw_audio.xml deleted file mode 100755 index 900f44df0..000000000 --- a/Android/APIExample/app/src/main/res/layout/fragment_raw_audio.xml +++ /dev/null @@ -1,66 +0,0 @@ - - - - - - - - - - - - - - - - - - diff --git a/Android/APIExample/app/src/main/res/navigation/nav_graph.xml b/Android/APIExample/app/src/main/res/navigation/nav_graph.xml index 09cca0722..ad54d7a5c 100755 --- a/Android/APIExample/app/src/main/res/navigation/nav_graph.xml +++ b/Android/APIExample/app/src/main/res/navigation/nav_graph.xml @@ -101,9 +101,6 @@ - @@ -265,9 +262,4 @@ android:name="io.agora.api.example.examples.advanced.FaceBeauty" android:label="VideoEnhance" tools:layout="@layout/fragment_video_enhancement" /> - diff --git a/Android/APIExample/app/src/main/res/values-zh/strings.xml b/Android/APIExample/app/src/main/res/values-zh/strings.xml index 01070df93..9bc7a825d 100644 --- a/Android/APIExample/app/src/main/res/values-zh/strings.xml +++ b/Android/APIExample/app/src/main/res/values-zh/strings.xml @@ -182,4 +182,5 @@ 屏幕共享 虚拟背景 摄像头切换 + 截屏 \ No newline at end of file diff --git a/Android/APIExample/app/src/main/res/values/strings.xml b/Android/APIExample/app/src/main/res/values/strings.xml index b92402148..e73d03eac 100644 --- a/Android/APIExample/app/src/main/res/values/strings.xml +++ b/Android/APIExample/app/src/main/res/values/strings.xml @@ -186,4 +186,5 @@ Screen Share Virtual Background switch camera + Snapshot From f37d4cb46d35ff572e95c2f3d8319f7e8bd789bb Mon Sep 17 00:00:00 2001 From: xianing Date: Sat, 12 Mar 2022 09:02:46 +0800 Subject: [PATCH 21/21] fix camera permission issue --- .../agora/api/example/examples/advanced/SuperResolution.java | 4 ++++ .../io/agora/api/example/examples/basic/JoinChannelAudio.java | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/SuperResolution.java b/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/SuperResolution.java index 63bff5263..48e40eec4 100644 --- a/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/SuperResolution.java +++ b/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/SuperResolution.java @@ -176,6 +176,10 @@ public void onClick(View v) } else if(v.getId() == R.id.btn_super_resolution){ int ret = engine.enableRemoteSuperResolution(remoteUid, !enableSuperResolution); + if(enableSuperResolution){ + enableSuperResolution = false; + btnSuperResolution.setText(getText(R.string.opensuperr)); + } if(ret!=0){ Log.w(TAG, String.format("onWarning code %d ", ret)); } diff --git a/Android/APIExample/app/src/main/java/io/agora/api/example/examples/basic/JoinChannelAudio.java b/Android/APIExample/app/src/main/java/io/agora/api/example/examples/basic/JoinChannelAudio.java index 78a4c2a13..45187ee4e 100755 --- a/Android/APIExample/app/src/main/java/io/agora/api/example/examples/basic/JoinChannelAudio.java +++ b/Android/APIExample/app/src/main/java/io/agora/api/example/examples/basic/JoinChannelAudio.java @@ -116,7 +116,7 @@ public void onClick(View v) { // call when join button hit String channelId = et_channel.getText().toString(); // Check permission - if (AndPermission.hasPermissions(this, Permission.Group.STORAGE, Permission.Group.MICROPHONE, Permission.Group.CAMERA)) { + if (AndPermission.hasPermissions(this, Permission.Group.STORAGE, Permission.Group.MICROPHONE)) { joinChannel(channelId); return; }