diff --git a/.github/ci/build/build_windows.bat b/.github/ci/build/build_windows.bat index a848d9a6c..a9d61c84e 100644 --- a/.github/ci/build/build_windows.bat +++ b/.github/ci/build/build_windows.bat @@ -36,6 +36,8 @@ REM pr: output test.zip to workspace dir REM others: Rename the zip package name yourself, But need copy it to workspace dir REM ################################## +setlocal EnableDelayedExpansion + echo compile_project: %compile_project% echo Package_Publish: %Package_Publish% echo is_tag_fetch: %is_tag_fetch% @@ -62,13 +64,7 @@ if not "%SDK_VER%"=="%BRANCH_VER%" ( echo Version validated: %BRANCH_VER% :skip_version_validation -REM If sdk_url has a value, replace the URL in install.ps1 -if not "%sdk_url%"=="" ( - if not "%sdk_url%"=="none" ( - echo "Replacing SDK URL in install.ps1" - powershell -Command "(Get-Content windows\APIExample\install.ps1) -replace '\$agora_sdk = ''.*''', ('$agora_sdk = ''' + '%sdk_url%' + '''') | Set-Content windows\APIExample\install.ps1" - ) -) +REM Keep install.ps1 unchanged. If sdk_url is provided, later prepare a local ../../sdk folder for compile. REM Check compress_apiexample parameter if "%compress_apiexample%"=="" set compress_apiexample=false @@ -78,42 +74,43 @@ REM Check compile_project parameter if "%compile_project%"=="" set compile_project=false echo compile_project: %compile_project% -REM Package APIExample code (only when compress_apiexample=true) -REM Run before compile so package content is not affected by compile +set "effective_sdk_url=%sdk_url%" set result_zip=APIExample_result.zip set des_path=%WORKSPACE%\Agora_Native_SDK_for_Windows_v%SDK_VER%_APIExample_%BUILD_NUMBER%.zip +set "need_sdk=false" + +if "%compress_apiexample%"=="true" set "need_sdk=true" +if "%compile_project%"=="true" set "need_sdk=true" + +if "%need_sdk%"=="true" ( + call :RESOLVE_SDK_URL + if errorlevel 1 exit /b 1 + + echo "Downloading SDK package: !effective_sdk_url!" + call :DOWNLOAD_AND_EXTRACT_SDK "!effective_sdk_url!" + if errorlevel 1 exit /b 1 +) else ( + echo "Skipping SDK download (no compile/package requested)" +) + +REM Package before compile so package contents are not affected by build outputs. if "%compress_apiexample%"=="true" ( - echo "Packaging APIExample code..." - - REM Compress windows\APIExample (code only) to zip - echo "Compressing APIExample code package..." - del /F /Q %result_zip% 2>nul - 7z a -tzip %result_zip% -r windows\APIExample - if errorlevel 1 ( - echo 7z compression failed! - exit /b 1 - ) - - REM Copy to WORKSPACE with new naming format - echo "Copying %result_zip% to %des_path%" - copy %result_zip% %des_path% - if errorlevel 1 ( - echo copy failed! - exit /b 1 - ) - - REM Clean up temporary zip in repo root - del /F %result_zip% - - echo "Complete: APIExample code package created" + echo "Packaging APIExample with SDK..." + call :PACKAGE_APIEXAMPLE_WITH_SDK "!sdk_extract_dir!" + if errorlevel 1 exit /b 1 + echo "Complete: APIExample package with SDK created" dir %WORKSPACE%\ ) else ( - echo "Skipping APIExample code packaging (compress_apiexample=false)" + echo "Skipping APIExample packaging (compress_apiexample=false)" ) -REM Compile project to generate executable (only when compile_project=true) if "%compile_project%"=="true" ( echo "Compiling project to generate executable..." + call :COPY_EXTRACTED_SDK_TO_REPO_ROOT "!sdk_extract_dir!" + if errorlevel 1 ( + echo Preparing repo root sdk folder failed! + exit /b 1 + ) cd windows\APIExample call cloud_build.bat if %ERRORLEVEL% NEQ 0 ( @@ -123,4 +120,104 @@ if "%compile_project%"=="true" ( cd ..\.. ) else ( echo "Skipping project compilation (compile_project=false)" -) \ No newline at end of file +) +goto :eof + +:RESOLVE_SDK_URL +if not "!effective_sdk_url!"=="" ( + if /I not "!effective_sdk_url!"=="none" exit /b 0 +) +for /f "tokens=*" %%a in ('powershell -Command "(Get-Content 'windows\APIExample\install.ps1' -Raw) -match '\$agora_sdk = ''([^'']+)''' | Out-Null; $matches[1]"') do set "effective_sdk_url=%%a" +if "!effective_sdk_url!"=="" ( + echo Effective SDK URL is empty! + exit /b 1 +) +exit /b 0 + +:DOWNLOAD_AND_EXTRACT_SDK +set "download_sdk_url=%~1" +set "DOWNLOAD_SDK_URL=%download_sdk_url%" +for /f "usebackq tokens=*" %%a in (`powershell -Command "[System.IO.Path]::GetFileName($env:DOWNLOAD_SDK_URL)"`) do set "sdk_zip_name=%%a" +if "!sdk_zip_name!"=="" ( + echo SDK zip file name parse failed! + exit /b 1 +) + +set "sdk_extract_dir=Agora_Native_SDK_for_Windows_FULL" +if exist "!sdk_extract_dir!" rmdir /S /Q "!sdk_extract_dir!" +del /F /Q "!sdk_zip_name!" 2>nul +del /F /Q %result_zip% 2>nul + +curl "!download_sdk_url!" -o "!sdk_zip_name!" +if errorlevel 1 ( + echo SDK download failed! + exit /b 1 +) + +echo "Extracting SDK package..." +7z x ".\!sdk_zip_name!" -y +if errorlevel 1 ( + echo SDK extraction failed! + exit /b 1 +) + +if not exist "!sdk_extract_dir!" ( + echo Extracted SDK folder "!sdk_extract_dir!" not found! + exit /b 1 +) + +if exist "!sdk_extract_dir!\demo" rmdir /S /Q "!sdk_extract_dir!\demo" +if exist "!sdk_extract_dir!\commits" del /F /Q "!sdk_extract_dir!\commits" +if exist "!sdk_extract_dir!\package_size_report.txt" del /F /Q "!sdk_extract_dir!\package_size_report.txt" +exit /b 0 + +:PACKAGE_APIEXAMPLE_WITH_SDK +set "package_sdk_extract_dir=%~1" +if not exist "!package_sdk_extract_dir!\samples" mkdir "!package_sdk_extract_dir!\samples" +if exist "!package_sdk_extract_dir!\samples\API-example" rmdir /S /Q "!package_sdk_extract_dir!\samples\API-example" +mkdir "!package_sdk_extract_dir!\samples\API-example" + +del /F /Q windows\APIExample\ci.py 2>nul + +xcopy /Y /E windows\APIExample "!package_sdk_extract_dir!\samples\API-example" +xcopy /Y windows\README.md "!package_sdk_extract_dir!\samples\API-example\" +xcopy /Y windows\README.zh.md "!package_sdk_extract_dir!\samples\API-example\" + +if exist "!package_sdk_extract_dir!\samples\API-example\APIExample\APIExample" ( + rmdir /S /Q "!package_sdk_extract_dir!\samples\API-example\APIExample\APIExample" +) + +echo "Compressing APIExample package with SDK..." +7z a -tzip %result_zip% -r "!package_sdk_extract_dir!" +if errorlevel 1 ( + echo 7z compression failed! + exit /b 1 +) + +echo "Copying %result_zip% to %des_path%" +copy %result_zip% %des_path% +if errorlevel 1 ( + echo copy failed! + exit /b 1 +) + +del /F /Q %result_zip% 2>nul +exit /b 0 + +:COPY_EXTRACTED_SDK_TO_REPO_ROOT +set "copy_sdk_extract_dir=%~1" +if not exist "!copy_sdk_extract_dir!\sdk\x86" ( + echo Extracted SDK folder "!copy_sdk_extract_dir!" is invalid! + exit /b 1 +) + +if exist "sdk" rmdir /S /Q sdk +mkdir sdk +xcopy /Y /E "!copy_sdk_extract_dir!\sdk\x86" "sdk\x86\" +xcopy /Y /E "!copy_sdk_extract_dir!\sdk\x86_64" "sdk\x86_64\" +xcopy /Y /E "!copy_sdk_extract_dir!\sdk\high_level_api" "sdk\high_level_api\" +if errorlevel 1 ( + echo Copying extracted SDK into repo root sdk folder failed! + exit /b 1 +) +exit /b 0 diff --git a/Android/APIExample-Audio/app/src/main/res/values-zh/strings.xml b/Android/APIExample-Audio/app/src/main/res/values-zh/strings.xml new file mode 100644 index 000000000..97acd2154 --- /dev/null +++ b/Android/APIExample-Audio/app/src/main/res/values-zh/strings.xml @@ -0,0 +1,90 @@ + + + Shengwang API Example(Audio) + 频道ID + 加入 + 播放 + 暂停 + 离开 + 停止 + 听筒 + 扬声器 + 打开麦克风 + 关闭麦克风 + + + 设置 + SDK版本 + V%s + 混音音量 + 3D音效环绕周期 + 下一步 + 发布麦克风 + 发布本地音频 + + 音频互动直播 + 音频互动直播(Token验证) + 通话前质量检测 + 快速切换频道 + 音频文件混音 + 美声与音效 + 自定义音频采集 + 自定义音频渲染 + 原始音频数据 + 空间音效 + 请授予权限 + 此示例演示在使用RTC通话中音频路由对第三方播放器的影响。 + 此示例演示了如何使用SDK加入频道进行纯语音通话的功能。 + 此示例演示了如何使用SDK加入带Token的频道进行纯语音通话的功能。 + 此示例演示了如何使用SDK在进入频道前检测网络质量状况。 + 此示例演示了在语音通话过程中使用MediaOption控制发布麦克风和自采集音频流的功能。 + 此示例演示了在语音通话过程中如何自定义远端音频流渲染器的功能。 + 此示例演示了在音视频通话过程中播放并管理audio effect和audio mixing文件。 + 此示例演示了在音视频通话过程中如何使用API提供的一些人声效果，或使用API自行组合出想要的人声效果。 + 此示例演示了在音频通话过程中如何通过回调获取裸数据的功能。 + 此示例演示了音频通话过程中如何使用虚拟节拍器。 + 音频回写 + 此示例演示了如何使用空间音效。 + 开始 + 点击开始 + 恢复播放 + 混音发布音量 + 混音播放音量 + 音效音量 + 请插入耳机体验3d音频效果 + + 虚拟节拍器 + Beats per Measure + Beats per Minute + Token无效 + Token已过期 + + 私有云 + IP地址 + 请输入IP地址 + 日志上报 + 日志服务域名/IP + 请输入日志服务域名/IP + 日志服务端口 + 请输入日志服务端口 + 日志服务路径 + 请输入日志服务路径 + 使用Https + 音频频谱 + + 区域 + + 音障 + 房间 + 静音 + 保存 + AppID为空！ + 默认 + 扬声器 + 听筒 + 耳机 + 耳机(TypeC) + 蓝牙耳机 + 请打开通知权限，防止后台录音中断 + 此示例演示了如何使用SDK进行语音通话的功能。 + \ No newline at end of file diff --git a/Android/APIExample-Audio/gradle.properties b/Android/APIExample-Audio/gradle.properties index be8a46849..092d496f9 100644 --- a/Android/APIExample-Audio/gradle.properties +++ b/Android/APIExample-Audio/gradle.properties @@ -23,4 +23,4 @@ android.nonFinalResIds=false # read enable simple filter section on README first before set this flag to TRUE simpleFilter = false -rtc_sdk_version = 4.6.3 \ No newline at end of file +rtc_sdk_version = 4.5.3 \ No newline at end of file diff --git a/Android/APIExample-Compose/gradle.properties b/Android/APIExample-Compose/gradle.properties index 6ba5018a5..5457a934a 100644 --- a/Android/APIExample-Compose/gradle.properties +++ b/Android/APIExample-Compose/gradle.properties @@ -22,4 +22,4 @@ kotlin.code.style=official # thereby reducing the size of the R class for that library android.nonTransitiveRClass=true -rtc_sdk_version = 4.6.3 \ No newline at end of file +rtc_sdk_version = 4.5.3 \ No newline at end of file diff --git a/Android/APIExample/README.md b/Android/APIExample/README.md index 4b4feb347..393b1219a 100644 --- a/Android/APIExample/README.md +++ b/Android/APIExample/README.md @@ -37,14 +37,15 @@ You are all set. Now connect your Android device and run the project. ### Beauty Configuration -> Third Part Beauty case use -> the [Agora Beauty API Library](https://github.com/AgoraIO-Community/BeautyAPI) +This project contains two types of beauty examples: -This project contains third-party beauty integration examples, which cannot be enabled by default -without configuring resources and certificates. The resource certificate configuration method is as -follows: +- Agora Beauty, which is self-developed by Agora. +- Third-party beauty integration examples, such as FaceUnity. -#### Agora +Some beauty examples cannot be enabled by default without configuring resources and certificates. +The configuration methods are as follows: + +#### Agora Beauty 1. Contact Agora technical support to obtain beauty resources 2. Put the beauty resources in the corresponding path @@ -53,7 +54,10 @@ follows: |------------------------|----------------------------------| | beauty resources | app/src/main/assets/beauty_agora | -#### FaceUnity +#### Third-party Beauty (FaceUnity) + +> The FaceUnity integration example is based on the +> [Agora Beauty API Library](https://github.com/AgoraIO-Community/BeautyAPI) 1. Contact FaceUnity customer service to obtain beauty resources and certificates 2. Put the beauty resource and certificate in the corresponding path diff --git a/Android/APIExample/README.zh.md b/Android/APIExample/README.zh.md index 67fde8368..0418f647b 100644 --- a/Android/APIExample/README.zh.md +++ b/Android/APIExample/README.zh.md @@ -37,9 +37,12 @@ ### 美颜配置 -> 第三方美颜集成使用了[美颜场景化API库](https://github.com/AgoraIO-Community/BeautyAPI) +本项目包含两类美颜示例： -本项目包含第三方美颜集成示例，在没有配置资源和证书的情况下，默认是无法启用的。资源证书配置方法如下： +- 声网美颜，为声网自研能力。 +- 第三方美颜集成示例，例如相芯美颜。 + +部分美颜示例在没有配置资源和证书的情况下默认无法启用，配置方法如下： #### 声网美颜 @@ -50,7 +53,9 @@ |------|----------------------------------| | 美颜资源 | app/src/main/assets/beauty_agora | -#### 相芯美颜 +#### 第三方美颜（相芯） + +> 相芯美颜集成示例基于[美颜场景化 API 库](https://github.com/AgoraIO-Community/BeautyAPI) 1. 联系相芯客服获取美颜资源以及证书 2. 将美颜资源及证书放到对应路径下 diff --git a/Android/APIExample/agora-simple-filter/src/main/cpp/AgoraRtcKit/AgoraBase.h b/Android/APIExample/agora-simple-filter/src/main/cpp/AgoraRtcKit/AgoraBase.h index 69f80bed6..235d9b2c4 100644 --- a/Android/APIExample/agora-simple-filter/src/main/cpp/AgoraRtcKit/AgoraBase.h +++ b/Android/APIExample/agora-simple-filter/src/main/cpp/AgoraRtcKit/AgoraBase.h @@ -262,15 +262,19 @@ class AList { } // namespace util /** - * @brief The channel profile. + * The channel profile. */ enum CHANNEL_PROFILE_TYPE { /** - * 0: Communication. Use this profile when there are only two users in the channel. + * 0: Communication. + * + * This profile prioritizes smoothness and applies to the one-to-one scenario. */ CHANNEL_PROFILE_COMMUNICATION = 0, /** - * 1: Live streaming. Use this profile when there are more than two users in the channel. + * 1: (Default) Live Broadcast. + * + * This profile prioritizes supporting a large audience in a live broadcast channel. */ CHANNEL_PROFILE_LIVE_BROADCASTING = 1, /** @@ -279,8 +283,8 @@ enum CHANNEL_PROFILE_TYPE { */ CHANNEL_PROFILE_GAME __deprecated = 2, /** - * Cloud gaming. The scenario is optimized for latency. Use this profile if the use case requires - * frequent interactions between users. + * 3: Cloud Gaming. + * * @deprecated This profile is deprecated. */ CHANNEL_PROFILE_CLOUD_GAMING __deprecated = 3, @@ -403,6 +407,10 @@ enum WARN_CODE_TYPE { * 1032: Audio Device Module: The playback audio volume is too low. */ WARN_ADM_PLAYOUT_AUDIO_LOWLEVEL = 1032, + /** + * 1033: Audio device module: The audio capturing device is occupied. + */ + WARN_ADM_RECORD_IS_OCCUPIED = 1033, /** * 1040: Audio device module: An exception occurs with the audio drive. * Choose one of the following solutions: @@ -447,75 +455,59 @@ enum WARN_CODE_TYPE { }; /** - * @brief Error codes. - * - * @details - * An error code indicates that the SDK encountered an unrecoverable error that requires application - * intervention. For example, an error is returned when the camera fails to open, and the app needs - * to inform the user that the camera cannot be used. - * + * The error codes. */ enum ERROR_CODE_TYPE { /** - * 0: No error. + * 0: No error occurs. */ ERR_OK = 0, // 1~1000 /** - * 1: General error with no classified reason. Try calling the method again. + * 1: A general error occurs (no specified reason). */ ERR_FAILED = 1, /** - * 2: An invalid parameter is used. For example, the specified channel name includes illegal - * characters. Reset the parameter. + * 2: The argument is invalid. For example, the specific channel name + * includes illegal characters. */ ERR_INVALID_ARGUMENT = 2, /** - * 3: The SDK is not ready. Possible reasons include the following: - * - The initialization of `IRtcEngine` fails. Reinitialize the `IRtcEngine`. - * - No user has joined the channel when the method is called. Check the code logic. - * - The user has not left the channel when the `rate` or `complain` method is called. Check the - * code logic. - * - The audio module is disabled. - * - The program is not complete. + * 3: The SDK module is not ready. Choose one of the following solutions: + * - Check the audio device. + * - Check the completeness of the app. + * - Reinitialize the RTC engine. */ ERR_NOT_READY = 3, /** - * 4: The `IRtcEngine` does not support the request. Possible reasons include the following: - * - The built-in encryption mode is incorrect, or the SDK fails to load the external encryption - * library. Check the encryption mode setting, or reload the external encryption library. + * 4: The SDK does not support this function. */ ERR_NOT_SUPPORTED = 4, /** - * 5: The request is rejected. Possible reasons include the following: - * - The `IRtcEngine` initialization fails. Reinitialize the `IRtcEngine`. - * - The channel name is set as the empty string `""` when joining the channel. Reset the channel - * name. - * - When the `joinChannelEx` method is called to join multiple channels, the specified channel name - * is already in use. Reset the channel name. + * 5: The request is rejected. */ ERR_REFUSED = 5, /** - * 6: The buffer size is insufficient to store the returned data. + * 6: The buffer size is not big enough to store the returned data. */ ERR_BUFFER_TOO_SMALL = 6, /** - * 7: A method is called before the initialization of `IRtcEngine`. Ensure that the `IRtcEngine` - * object is initialized before using this method. + * 7: The SDK is not initialized before calling this method. */ ERR_NOT_INITIALIZED = 7, /** - * 8: Invalid state. + * 8: The state is invalid. */ ERR_INVALID_STATE = 8, /** - * 9: Permission to access is not granted. Check whether your app has access to the audio and video - * device. + * 9: No permission. This is for internal use only, and does + * not return to the app through any method or callback. */ ERR_NO_PERMISSION = 9, /** - * 10: A timeout occurs. Some API calls require the SDK to return the execution result. This error - * occurs if the SDK takes too long (more than 10 seconds) to return the result. + * 10: An API timeout occurs. Some API methods require the SDK to return the + * execution result, and this error occurs if the request takes too long + * (more than 10 seconds) for the SDK to process. */ ERR_TIMEDOUT = 10, /** @@ -541,112 +533,126 @@ enum ERROR_CODE_TYPE { */ ERR_NET_DOWN = 14, /** - * 17: The request to join the channel is rejected. Possible reasons include the following: - * - The user is already in the channel. Agora recommends that you use the - * `onConnectionStateChanged` callback to see whether the user is in the channel. Do not call this - * method to join the channel unless you receive the `CONNECTION_STATE_DISCONNECTED` (1) state. - * - After calling `startEchoTest` for the call test, the user tries to join the channel without - * calling `stopEchoTest` to end the current test. To join a channel, the call test must be ended by - * calling `stopEchoTest`. + * 17: The request to join the channel is rejected. This error usually occurs + * when the user is already in the channel, and still calls the method to join + * the channel, for example, \ref agora::rtc::IRtcEngine::joinChannel "joinChannel()". */ ERR_JOIN_CHANNEL_REJECTED = 17, /** - * 18: Fails to leave the channel. Possible reasons include the following: - * - The user has left the channel before calling the `leaveChannel(const LeaveChannelOptions& - * options)` method. Stop calling this - * method to clear this error. - * - The user calls the `leaveChannel(const LeaveChannelOptions& options)` method to leave the - * channel before joining the channel. - * In this case, no extra operation is needed. + * 18: The request to leave the channel is rejected. This error usually + * occurs when the user has already left the channel, and still calls the + * method to leave the channel, for example, \ref agora::rtc::IRtcEngine::leaveChannel + * "leaveChannel". */ ERR_LEAVE_CHANNEL_REJECTED = 18, /** - * 19: Resources are already in use. + * 19: The resources have been occupied and cannot be reused. */ ERR_ALREADY_IN_USE = 19, /** - * 20: The request is abandoned by the SDK, possibly because the request has been sent too - * frequently. + * 20: The SDK gives up the request due to too many requests. This is for + * internal use only, and does not return to the app through any method or callback. */ ERR_ABORTED = 20, /** - * 21: The `IRtcEngine` fails to initialize and has crashed because of specific Windows firewall - * settings. + * 21: On Windows, specific firewall settings can cause the SDK to fail to + * initialize and crash. */ ERR_INIT_NET_ENGINE = 21, /** - * 22: The SDK fails to allocate resources because your app uses too many system resources or system - * resources are insufficient. + * 22: The app uses too much of the system resource and the SDK + * fails to allocate any resource. */ ERR_RESOURCE_LIMITED = 22, /** - * 23: The function is prohibited. Please allow it in the console, or contact the Agora technical support. - * @technical preview - */ - ERR_FUNC_IS_PROHIBITED = 23, - /** - * 101: The specified App ID is invalid. Rejoin the channel with a valid App ID. + * 101: The App ID is invalid, usually because the data format of the App ID is incorrect. + * + * Solution: Check the data format of your App ID. Ensure that you use the correct App ID to + * initialize the Agora service. */ ERR_INVALID_APP_ID = 101, /** - * 102: The specified channel name is invalid. A possible reason is that the parameter's data type - * is incorrect. Rejoin the channel with a valid channel name. + * 102: The specified channel name is invalid. Please try to rejoin the + * channel with a valid channel name. */ ERR_INVALID_CHANNEL_NAME = 102, /** - * 103: Fails to get server resources in the specified region. Try another region when initializing - * `IRtcEngine`. + * 103: Fails to get server resources in the specified region. Please try to + * specify another region when calling \ref agora::rtc::IRtcEngine::initialize + * "initialize". */ ERR_NO_SERVER_RESOURCES = 103, /** - * 109: The current token has expired. Apply for a new token on the server and call `renewToken`. + * 109: The token has expired, usually for the following reasons: + * - Timeout for token authorization: Once a token is generated, you must use it to access the + * Agora service within 24 hours. Otherwise, the token times out and you can no longer use it. + * - The token privilege expires: To generate a token, you need to set a timestamp for the token + * privilege to expire. For example, If you set it as seven days, the token expires seven days + * after its usage. In that case, you can no longer access the Agora service. The users cannot + * make calls, or are kicked out of the channel. + * + * Solution: Regardless of whether token authorization times out or the token privilege expires, + * you need to generate a new token on your server, and try to join the channel. */ ERR_TOKEN_EXPIRED = 109, /** - * 110: Invalid token. Typical reasons include the following: - * - App Certificate is enabled in Agora Console, but the code still uses App ID for authentication. - * Once App Certificate is enabled for a project, you must use token-based authentication. - * - The `uid` used to generate the token is not the same as the `uid` used to join the channel. + * 110: The token is invalid, usually for one of the following reasons: + * - Did not provide a token when joining a channel in a situation where the project has enabled + * the App Certificate. + * - Tried to join a channel with a token in a situation where the project has not enabled the App + * Certificate. + * - The App ID, user ID and channel name that you use to generate the token on the server do not + * match those that you use when joining a channel. + * + * Solution: + * - Before joining a channel, check whether your project has enabled the App certificate. If yes, + * you must provide a token when joining a channel; if no, join a channel without a token. + * - When using a token to join a channel, ensure that the App ID, user ID, and channel name that + * you use to generate the token is the same as the App ID that you use to initialize the Agora + * service, and the user ID and channel name that you use to join the channel. */ ERR_INVALID_TOKEN = 110, /** - * 111: The network connection is interrupted. The SDK triggers this callback when it loses - * connection with the server for more than four seconds after the connection is established. + * 111: The internet connection is interrupted. This applies to the Agora Web + * SDK only. */ ERR_CONNECTION_INTERRUPTED = 111, // only used in web sdk /** - * 112: The network connection is lost. Occurs when the SDK cannot reconnect to Agora's edge server - * 10 seconds after its connection to the server is interrupted. + * 112: The internet connection is lost. This applies to the Agora Web SDK + * only. */ ERR_CONNECTION_LOST = 112, // only used in web sdk /** - * 113: The user is not in the channel when calling the `sendStreamMessage` method. + * 113: The user is not in the channel when calling the + * \ref agora::rtc::IRtcEngine::sendStreamMessage "sendStreamMessage()" method. */ ERR_NOT_IN_CHANNEL = 113, /** - * 114: The data size exceeds 1 KB when calling the `sendStreamMessage` method. + * 114: The data size is over 1024 bytes when the user calls the + * \ref agora::rtc::IRtcEngine::sendStreamMessage "sendStreamMessage()" method. */ ERR_SIZE_TOO_LARGE = 114, /** - * 115: The data bitrate exceeds 6 KB/s when calling the `sendStreamMessage` method. + * 115: The bitrate of the sent data exceeds the limit of 6 Kbps when the + * user calls the \ref agora::rtc::IRtcEngine::sendStreamMessage "sendStreamMessage()". */ ERR_BITRATE_LIMIT = 115, /** - * 116: More than five data streams are created when calling the `createDataStream(int* streamId, - * const DataStreamConfig& config)` method. + * 116: Too many data streams (over 5) are created when the user + * calls the \ref agora::rtc::IRtcEngine::createDataStream "createDataStream()" method. */ ERR_TOO_MANY_DATA_STREAMS = 116, /** - * 117: The data stream transmission times out. + * 117: A timeout occurs for the data stream transmission. */ ERR_STREAM_MESSAGE_TIMEOUT = 117, /** - * 119: Switching roles fails, try rejoining the channel. + * 119: Switching the user role fails. Please try to rejoin the channel. */ ERR_SET_CLIENT_ROLE_NOT_AUTHORIZED = 119, /** - * 120: Media streams decryption fails. The user might use an incorrect password to join the - * channel. Check the entered password, or tell the user to try rejoining the channel. + * 120: MediaStream decryption fails. The user may have tried to join the channel with a wrong + * password. Check your settings or try rejoining the channel. */ ERR_DECRYPTION_FAILED = 120, /** @@ -654,16 +660,18 @@ enum ERROR_CODE_TYPE { */ ERR_INVALID_USER_ID = 121, /** - * 122: Data streams decryption fails. The user might use an incorrect password to join the channel. - * Check the entered password, or tell the user to try rejoining the channel. + * 122: DataStream decryption fails. The peer may have tried to join the channel with a wrong + * password, or did't enable datastream encryption */ ERR_DATASTREAM_DECRYPTION_FAILED = 122, /** - * 123: The user is banned from the server. + * 123: The app is banned by the server. */ ERR_CLIENT_IS_BANNED_BY_SERVER = 123, /** - * 130: The SDK does not support pushing encrypted streams to CDN. + * 130: Encryption is enabled when the user calls the + * \ref agora::rtc::IRtcEngine::addPublishStreamUrl "addPublishStreamUrl()" method + * (CDN live streaming does not support encrypted streams). */ ERR_ENCRYPTED_STREAM_NOT_ALLOWED_PUBLISH = 130, @@ -673,7 +681,8 @@ enum ERROR_CODE_TYPE { ERR_LICENSE_CREDENTIAL_INVALID = 131, /** - * 134: The user account is invalid, possibly because it contains invalid parameters. + * 134: The user account is invalid, usually because the data format of the user account is + * incorrect. */ ERR_INVALID_USER_ACCOUNT = 134, @@ -700,49 +709,9 @@ enum ERROR_CODE_TYPE { ERR_CERT_REQUEST = 168, // PcmSend Error num - /** - * 200: Unsupported PCM format. - */ ERR_PCMSEND_FORMAT = 200, // unsupport pcm format - /** - * 201: Buffer overflow, the PCM send rate too quickly. - */ ERR_PCMSEND_BUFFEROVERFLOW = 201, // buffer overflow, the pcm send rate too quickly - /// @cond - // RDT error code: 250~270 - /** - * 250: The user does not exist - * @technical preview - */ - ERR_RDT_USER_NOT_EXIST = 250, - /** - * 251: The RDT state with the user is not ready - * @technical preview - */ - ERR_RDT_USER_NOT_READY = 251, - /** - * 252: The RDT data stream is blocked - * @technical preview - */ - ERR_RDT_DATA_BLOCKED = 252, - /** - * 253: The RDT CMD stream exceeds the limit (size <= 256 Bytes, freq <= 100/sec) - * @technical preview - */ - ERR_RDT_CMD_EXCEED_LIMIT = 253, - /** - * 254: The RDT DATA stream exceeds the limit (size <= 128 KBytes, speed <= 4 Mbps) - * @technical preview - */ - ERR_RDT_DATA_EXCEED_LIMIT = 254, - /** - * 255: The RDT encryption error. The SDK Failed to process RDT data encryption/decryption - * @technical preview - */ - ERR_RDT_ENCRYPTION = 255, - /// @endcond - /// @cond // signaling: 400~600 ERR_LOGIN_ALREADY_LOGIN = 428, @@ -750,43 +719,43 @@ enum ERROR_CODE_TYPE { /// @endcond // 1001~2000 /** - * 1001: The SDK fails to load the media engine. + * 1001: Fails to load the media engine. */ ERR_LOAD_MEDIA_ENGINE = 1001, /** - * 1005: A general error occurs (no specified reason). Check whether the audio device is already in - * use by another app, or try rejoining the channel. + * 1005: Audio device module: A general error occurs in the Audio Device Module (no specified + * reason). Check if the audio device is used by another app, or try + * rejoining the channel. */ ERR_ADM_GENERAL_ERROR = 1005, /** - * 1008: An error occurs when initializing the playback device. Check whether the playback device is - * already in use by another app, or try rejoining the channel. + * 1008: Audio Device Module: An error occurs in initializing the playback + * device. */ ERR_ADM_INIT_PLAYOUT = 1008, /** - * 1009: An error occurs when starting the playback device. Check the playback device. + * 1009: Audio Device Module: An error occurs in starting the playback device. */ ERR_ADM_START_PLAYOUT = 1009, /** - * 1010: An error occurs when stopping the playback device. + * 1010: Audio Device Module: An error occurs in stopping the playback device. */ ERR_ADM_STOP_PLAYOUT = 1010, /** - * 1011: An error occurs when initializing the recording device. Check the recording device, or try - * rejoining the channel. + * 1011: Audio Device Module: An error occurs in initializing the recording + * device. */ ERR_ADM_INIT_RECORDING = 1011, /** - * 1012: An error occurs when starting the recording device. Check the recording device. + * 1012: Audio Device Module: An error occurs in starting the recording device. */ ERR_ADM_START_RECORDING = 1012, /** - * 1013: An error occurs when stopping the recording device. + * 1013: Audio Device Module: An error occurs in stopping the recording device. */ ERR_ADM_STOP_RECORDING = 1013, /** - * 1501: Permission to access the camera is not granted. Check whether permission to access the - * camera permission is granted. + * 1501: Video Device Module: The camera is not authorized. */ ERR_VDM_CAMERA_NOT_AUTHORIZED = 1501, }; @@ -819,11 +788,11 @@ enum LICENSE_ERROR_TYPE { }; /** - * @brief The operation permissions of the SDK on the audio session. + * The operational permission of the SDK on the audio session. */ enum AUDIO_SESSION_OPERATION_RESTRICTION { /** - * 0: No restriction, the SDK can change the audio session. + * 0: No restriction; the SDK can change the audio session. */ AUDIO_SESSION_OPERATION_RESTRICTION_NONE = 0, /** @@ -835,13 +804,13 @@ enum AUDIO_SESSION_OPERATION_RESTRICTION { */ AUDIO_SESSION_OPERATION_RESTRICTION_CONFIGURE_SESSION = 1 << 1, /** - * 4: The SDK keeps the audio session active when the user leaves the channel, for example, to play - * an audio file in the background. + * 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, /** - * 128: Completely restricts the operation permissions of the SDK on the audio session; the SDK - * cannot change the audio session. + * 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, }; @@ -850,7 +819,7 @@ typedef const char* user_id_t; typedef void* view_t; /** - * @brief The information of the user. + * The definition of the UserInfo struct. */ struct UserInfo { /** @@ -879,18 +848,17 @@ typedef util::AList UserList; namespace rtc { /** - * @brief Reasons for a user being offline. + * Reasons for a user being offline. */ enum USER_OFFLINE_REASON_TYPE { /** - * 0: The user quits the call. + * 0: The user leaves the current channel. */ USER_OFFLINE_QUIT = 0, /** - * 1: The SDK times out and the user drops offline because no data packet is received within a - * certain period of time. - * @note If the user quits the call and the message is not passed to the SDK (due to an unreliable - * channel), the SDK assumes the user dropped offline. + * 1: The SDK times out and the user drops 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 that the user drops offline. */ USER_OFFLINE_DROPPED = 1, /** @@ -899,32 +867,14 @@ enum USER_OFFLINE_REASON_TYPE { USER_OFFLINE_BECOME_AUDIENCE = 2, }; -/** - * @brief The interface class. - */ enum INTERFACE_ID_TYPE { - /** - * 1: The `IAudioDeviceManager` interface class. - */ AGORA_IID_AUDIO_DEVICE_MANAGER = 1, - /** - * 2: The `IVideoDeviceManager` interface class. - */ AGORA_IID_VIDEO_DEVICE_MANAGER = 2, - /** - * This interface class is deprecated. - */ AGORA_IID_PARAMETER_ENGINE = 3, - /** - * 4: The `IMediaEngine` interface class. - */ AGORA_IID_MEDIA_ENGINE = 4, AGORA_IID_AUDIO_ENGINE = 5, AGORA_IID_VIDEO_ENGINE = 6, AGORA_IID_RTC_CONNECTION = 7, - /** - * This interface class is deprecated. - */ AGORA_IID_SIGNALING_ENGINE = 8, AGORA_IID_MEDIA_ENGINE_REGULATOR = 9, AGORA_IID_LOCAL_SPATIAL_AUDIO = 11, @@ -935,7 +885,7 @@ enum INTERFACE_ID_TYPE { }; /** - * @brief Network quality types. + * The network quality types. */ enum QUALITY_TYPE { /** @@ -944,15 +894,16 @@ enum QUALITY_TYPE { */ QUALITY_UNKNOWN __deprecated = 0, /** - * 1: The network quality is excellent. + * 1: The quality is excellent. */ QUALITY_EXCELLENT = 1, /** - * 2: The network quality is quite good, but the bitrate may be slightly lower than excellent. + * 2: The quality is quite good, but the bitrate may be slightly + * lower than excellent. */ QUALITY_GOOD = 2, /** - * 3: Users can feel the communication is slightly impaired. + * 3: Users can feel the communication slightly impaired. */ QUALITY_POOR = 3, /** @@ -960,11 +911,11 @@ enum QUALITY_TYPE { */ QUALITY_BAD = 4, /** - * 5: The quality is so bad that users can barely communicate. + * 5: Users can barely communicate. */ QUALITY_VBAD = 5, /** - * 6: The network is down and users cannot communicate at all. + * 6: Users cannot communicate at all. */ QUALITY_DOWN = 6, /** @@ -972,7 +923,7 @@ enum QUALITY_TYPE { */ QUALITY_UNSUPPORTED = 7, /** - * 8: The last-mile network probe test is in progress. + * 8: Detecting the network quality. */ QUALITY_DETECTING = 8, }; @@ -996,29 +947,29 @@ enum FIT_MODE_TYPE { }; /** - * @brief The clockwise rotation of the video. + * The rotation information. */ enum VIDEO_ORIENTATION { /** - * 0: (Default) No rotation. + * 0: Rotate the video by 0 degree clockwise. */ VIDEO_ORIENTATION_0 = 0, /** - * 90: 90 degrees. + * 90: Rotate the video by 90 degrees clockwise. */ VIDEO_ORIENTATION_90 = 90, /** - * 180: 180 degrees. + * 180: Rotate the video by 180 degrees clockwise. */ VIDEO_ORIENTATION_180 = 180, /** - * 270: 270 degrees. + * 270: Rotate the video by 270 degrees clockwise. */ VIDEO_ORIENTATION_270 = 270 }; /** - * @brief The video frame rate. + * The video frame rate. */ enum FRAME_RATE { /** @@ -1046,8 +997,7 @@ enum FRAME_RATE { */ FRAME_RATE_FPS_30 = 30, /** - * 60: 60 fps. - * @note For Windows and macOS only. + * 60: 60 fps. Applies to Windows and macOS only. */ FRAME_RATE_FPS_60 = 60, }; @@ -1061,97 +1011,85 @@ enum FRAME_HEIGHT { }; /** - * @brief The video frame type. + * Types of the video frame. */ enum VIDEO_FRAME_TYPE { - /** - * 0: A black frame. - */ + /** 0: A black frame. */ VIDEO_FRAME_TYPE_BLANK_FRAME = 0, - /** - * 3: Key frame. - */ + /** 3: Key frame. */ VIDEO_FRAME_TYPE_KEY_FRAME = 3, - /** - * 4: Delta frame. - */ + /** 4: Delta frame. */ VIDEO_FRAME_TYPE_DELTA_FRAME = 4, - /** - * 5: The B frame. - */ + /** 5: The B frame.*/ VIDEO_FRAME_TYPE_B_FRAME = 5, - /** - * 6: A discarded frame. - */ + /** 6: A discarded frame. */ VIDEO_FRAME_TYPE_DROPPABLE_FRAME = 6, - /** - * Unknown frame. - */ + /** Unknown frame. */ VIDEO_FRAME_TYPE_UNKNOW }; /** - * @brief Video output orientation mode. + * Video output orientation modes. */ enum ORIENTATION_MODE { /** - * 0: (Default) The output video always follows the orientation of the captured video. The receiver - * takes the rotational information passed on from the video encoder. This mode applies to scenarios - * where video orientation can be adjusted on the receiver. + * 0: The output video always follows the orientation of the captured video. The receiver takes + * the rotational information passed on from the video encoder. This mode applies to scenarios + * where video orientation can be adjusted on the receiver: * - If the captured video is in landscape mode, the output video is in landscape mode. * - If the captured video is in portrait mode, the output video is in portrait mode. */ ORIENTATION_MODE_ADAPTIVE = 0, /** - * 1: In this mode, the SDK always outputs videos in landscape (horizontal) mode. If the captured - * video is in portrait mode, the video encoder crops it to fit the output. Applies to situations - * where the receiving end cannot process the rotational information. For example, CDN live - * streaming. + * 1: Landscape mode. In this mode, the SDK always outputs videos in landscape (horizontal) mode. + * If the captured video is in portrait mode, the video encoder crops it to fit the output. + * Applies to situations where the receiving end cannot process the rotational information. For + * example, CDN live streaming. */ ORIENTATION_MODE_FIXED_LANDSCAPE = 1, /** - * 2: In this mode, the SDK always outputs video in portrait (portrait) mode. If the captured video - * is in landscape mode, the video encoder crops it to fit the output. Applies to situations where - * the receiving end cannot process the rotational information. For example, CDN live streaming. + * 2: Portrait mode. In this mode, the SDK always outputs video in portrait (portrait) mode. If + * the captured video is in landscape mode, the video encoder crops it to fit the output. Applies + * to situations where the receiving end cannot process the rotational information. For example, + * CDN live streaming. */ ORIENTATION_MODE_FIXED_PORTRAIT = 2, }; /** - * @brief Video degradation preferences when the bandwidth is a constraint. + * (For future use) Video degradation preferences under limited bandwidth. */ enum DEGRADATION_PREFERENCE { /** - * -1: (Default) Automatic mode. The SDK will automatically select MAINTAIN_FRAMERATE, - * MAINTAIN_BALANCED or MAINTAIN_RESOLUTION based on the video scenario you set, in order to achieve - * the best overall quality of experience (QoE). - */ + * -1: (Default) SDK uses degradation preference according to setVideoScenario API settings, real-time network state and other relevant data information. + * If API setVideoScenario set video scenario to APPLICATION_SCENARIO_LIVESHOW, then MAINTAIN_BALANCED is used. If not, then MAINTAIN_RESOLUTION is used. + * Also if network state has changed, SDK may change this parameter between MAINTAIN_FRAMERATE、MAINTAIN_BALANCED and MAINTAIN_RESOLUTION automatically to get the best QOE. + * We recommend using this option. + */ MAINTAIN_AUTO = -1, /** - * 0: Prefers to reduce the video frame rate while maintaining video resolution during video - * encoding under limited bandwidth. This degradation preference is suitable for scenarios where - * video quality is prioritized. + * 0: (Deprecated) 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. */ MAINTAIN_QUALITY = 0, /** - * 1: Reduces the video resolution 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. + * 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: Reduces the video frame rate and video resolution simultaneously during video encoding under - * limited bandwidth. The MAINTAIN_BALANCED has a lower reduction than MAINTAIN_QUALITY and - * MAINTAIN_FRAMERATE, and this preference is suitable for scenarios where both smoothness and video - * quality are a priority. - * @note The resolution of the video sent may change, so remote users need to handle this issue. See - * `onVideoSizeChanged`. + * 2: Reduces the video frame rate and video quality simultaneously during video encoding under + * limited bandwidth. MAINTAIN_BALANCED has a lower reduction than MAINTAIN_RESOLUTION and + * MAINTAIN_FRAMERATE, and this preference is suitable for scenarios where both smoothness and + * video quality are a priority. */ MAINTAIN_BALANCED = 2, /** - * 3: Reduces the video frame rate while maintaining the video resolution during video encoding - * under limited bandwidth. This degradation preference is suitable for scenarios where video - * quality is prioritized. + * 3: Degrade framerate in order to maintain resolution. */ MAINTAIN_RESOLUTION = 3, /** @@ -1161,15 +1099,15 @@ enum DEGRADATION_PREFERENCE { }; /** - * @brief The video dimension. + * The definition of the VideoDimensions struct. */ struct VideoDimensions { /** - * The width (pixels) of the video. + * The width of the video, in pixels. */ int width; /** - * The height (pixels) of the video. + * The height of the video, in pixels. */ int height; VideoDimensions() : width(640), height(480) {} @@ -1206,57 +1144,38 @@ const int DEFAULT_MIN_BITRATE = -1; const int DEFAULT_MIN_BITRATE_EQUAL_TO_TARGET_BITRATE = -2; /** - * @brief The highest frame rate supported by the screen sharing device. + * screen sharing supported capability level. */ enum SCREEN_CAPTURE_FRAMERATE_CAPABILITY { - /** - * 0: The device supports the frame rate of up to 15 fps. - */ SCREEN_CAPTURE_FRAMERATE_CAPABILITY_15_FPS = 0, - /** - * 1: The device supports the frame rate of up to 30 fps. - */ SCREEN_CAPTURE_FRAMERATE_CAPABILITY_30_FPS = 1, - /** - * 2: The device supports the frame rate of up to 60 fps. - */ SCREEN_CAPTURE_FRAMERATE_CAPABILITY_60_FPS = 2, }; /** - * @brief The level of the codec capability. + * Video codec capability levels. */ enum VIDEO_CODEC_CAPABILITY_LEVEL { - /** - * -1: Unsupported video type. Currently, only H.264 and H.265 formats are supported. If the video - * is in another format, this value will be returned. - */ + /** No specified level */ CODEC_CAPABILITY_LEVEL_UNSPECIFIED = -1, - /** - * 5: Supports encoding and decoding videos up to 1080p and 30 fps. - */ + /** Only provide basic support for the codec type */ CODEC_CAPABILITY_LEVEL_BASIC_SUPPORT = 5, - /** - * 10: Supports encoding and decoding videos up to1080p and 30 fps. - */ + /** Can process 1080p video at a rate of approximately 30 fps. */ CODEC_CAPABILITY_LEVEL_1080P30FPS = 10, - /** - * 20: Support encoding and decoding videos up to 1080p and 60 fps. - */ + /** Can process 1080p video at a rate of approximately 60 fps. */ CODEC_CAPABILITY_LEVEL_1080P60FPS = 20, - /** - * 30: Support encoding and decoding videos up to 4K and 30 fps. - */ + /** Can process 4k video at a rate of approximately 30 fps. */ CODEC_CAPABILITY_LEVEL_4K60FPS = 30, }; /** - * @brief Video codec types. + * The video codec types. */ enum VIDEO_CODEC_TYPE { /** - * 0: (Default) Unspecified codec format. The SDK automatically matches the appropriate codec format - * based on the current video stream's resolution and device performance. + * 0: (Default) SDK will automatically adjust the codec type according to country and region or real-time network state and other relevant data information. + * Also if network state is changed, SDK may change codec automatically to get the best QOE. + * We recommend use this option. */ VIDEO_CODEC_NONE = 0, /** @@ -1281,7 +1200,7 @@ enum VIDEO_CODEC_TYPE { * 7: Generic H264. * @deprecated This codec type is deprecated. */ - VIDEO_CODEC_GENERIC_H264 = 7, + VIDEO_CODEC_GENERIC_H264 __deprecated = 7, /** * 12: AV1. * @technical preview @@ -1298,26 +1217,23 @@ enum VIDEO_CODEC_TYPE { }; /** - * @brief The camera focal length types. - * - * @note This enumeration class applies to Android and iOS only. - * + * Camera focal length type. */ enum CAMERA_FOCAL_LENGTH_TYPE { /** - * 0: (Default) Standard lens. + * By default, there are no wide-angle and ultra-wide-angle properties. */ CAMERA_FOCAL_LENGTH_DEFAULT = 0, /** - * 1: Wide-angle lens. + * Lens with focal length from 24mm to 35mm. */ CAMERA_FOCAL_LENGTH_WIDE_ANGLE = 1, /** - * 2: Ultra-wide-angle lens. + * Lens with focal length of less than 24mm. */ CAMERA_FOCAL_LENGTH_ULTRA_WIDE = 2, /** - * 3: (For iOS only) Telephoto lens. + * Telephoto lens. */ CAMERA_FOCAL_LENGTH_TELEPHOTO = 3, }; @@ -1415,7 +1331,7 @@ struct SenderOptions { }; /** - * @brief The codec type of audio. + * Audio codec types. */ enum AUDIO_CODEC_TYPE { /** @@ -1439,11 +1355,11 @@ enum AUDIO_CODEC_TYPE { /** 7: AAC. */ // AUDIO_CODEC_AAC = 7, /** - * 8: LC-AAC. + * 8: AAC LC. */ AUDIO_CODEC_AACLC = 8, /** - * 9: HE-AAC. + * 9: HE AAC. */ AUDIO_CODEC_HEAAC = 9, /** @@ -1465,80 +1381,80 @@ enum AUDIO_CODEC_TYPE { }; /** - * @brief Audio encoding type. + * Audio encoding types of the audio encoded frame observer. */ enum AUDIO_ENCODING_TYPE { /** - * 0x010101: AAC encoding format, 16000 Hz sampling rate, bass quality. A file with an audio - * duration of 10 minutes is approximately 1.2 MB after encoding. + * AAC encoding format, 16000 Hz sampling rate, bass quality. A file with an audio duration of 10 + * minutes is approximately 1.2 MB after encoding. */ AUDIO_ENCODING_TYPE_AAC_16000_LOW = 0x010101, /** - * 0x010102: AAC encoding format, 16000 Hz sampling rate, medium sound quality. A file with an audio + * AAC encoding format, 16000 Hz sampling rate, medium sound quality. A file with an audio * duration of 10 minutes is approximately 2 MB after encoding. */ AUDIO_ENCODING_TYPE_AAC_16000_MEDIUM = 0x010102, /** - * 0x010201: AAC encoding format, 32000 Hz sampling rate, bass quality. A file with an audio - * duration of 10 minutes is approximately 1.2 MB after encoding. + * AAC encoding format, 32000 Hz sampling rate, bass quality. A file with an audio duration of 10 + * minutes is approximately 1.2 MB after encoding. */ AUDIO_ENCODING_TYPE_AAC_32000_LOW = 0x010201, /** - * 0x010202: AAC encoding format, 32000 Hz sampling rate, medium sound quality. A file with an audio + * AAC encoding format, 32000 Hz sampling rate, medium sound quality. A file with an audio * duration of 10 minutes is approximately 2 MB after encoding. */ AUDIO_ENCODING_TYPE_AAC_32000_MEDIUM = 0x010202, /** - * 0x010203: AAC encoding format, 32000 Hz sampling rate, high sound quality. A file with an audio - * duration of 10 minutes is approximately 3.5 MB after encoding. + * AAC encoding format, 32000 Hz sampling rate, high sound quality. A file with an audio duration + * of 10 minutes is approximately 3.5 MB after encoding. */ AUDIO_ENCODING_TYPE_AAC_32000_HIGH = 0x010203, /** - * 0x010302: AAC encoding format, 48000 Hz sampling rate, medium sound quality. A file with an audio + * AAC encoding format, 48000 Hz sampling rate, medium sound quality. A file with an audio * duration of 10 minutes is approximately 2 MB after encoding. */ AUDIO_ENCODING_TYPE_AAC_48000_MEDIUM = 0x010302, /** - * 0x010303: AAC encoding format, 48000 Hz sampling rate, high sound quality. A file with an audio - * duration of 10 minutes is approximately 3.5 MB after encoding. + * AAC encoding format, 48000 Hz sampling rate, high sound quality. A file with an audio duration + * of 10 minutes is approximately 3.5 MB after encoding. */ AUDIO_ENCODING_TYPE_AAC_48000_HIGH = 0x010303, /** - * 0x020101: OPUS encoding format, 16000 Hz sampling rate, bass quality. A file with an audio - * duration of 10 minutes is approximately 2 MB after encoding. + * OPUS encoding format, 16000 Hz sampling rate, bass quality. A file with an audio duration of 10 + * minutes is approximately 2 MB after encoding. */ AUDIO_ENCODING_TYPE_OPUS_16000_LOW = 0x020101, /** - * 0x020102: OPUS encoding format, 16000 Hz sampling rate, medium sound quality. A file with an - * audio duration of 10 minutes is approximately 2 MB after encoding. + * OPUS encoding format, 16000 Hz sampling rate, medium sound quality. A file with an audio + * duration of 10 minutes is approximately 2 MB after encoding. */ AUDIO_ENCODING_TYPE_OPUS_16000_MEDIUM = 0x020102, /** - * 0x020302: OPUS encoding format, 48000 Hz sampling rate, medium sound quality. A file with an - * audio duration of 10 minutes is approximately 2 MB after encoding. + * OPUS encoding format, 48000 Hz sampling rate, medium sound quality. A file with an audio + * duration of 10 minutes is approximately 2 MB after encoding. */ AUDIO_ENCODING_TYPE_OPUS_48000_MEDIUM = 0x020302, /** - * 0x020303: OPUS encoding format, 48000 Hz sampling rate, high sound quality. A file with an audio - * duration of 10 minutes is approximately 3.5 MB after encoding. + * OPUS encoding format, 48000 Hz sampling rate, high sound quality. A file with an audio duration + * of 10 minutes is approximately 3.5 MB after encoding. */ AUDIO_ENCODING_TYPE_OPUS_48000_HIGH = 0x020303, }; /** - * @brief The adaptation mode of the watermark. + * The adaptation mode of the watermark. */ enum WATERMARK_FIT_MODE { /** - * 0: Use the `positionInLandscapeMode` and `positionInPortraitMode` values you set in - * `WatermarkOptions`. The settings in `WatermarkRatio` are invalid. + * Use the `positionInLandscapeMode` and `positionInPortraitMode` values you set in + * #WatermarkOptions. The settings in `WatermarkRatio` are invalid. */ - FIT_MODE_COVER_POSITION = 0, + FIT_MODE_COVER_POSITION, /** - * 1: Use the value you set in `WatermarkRatio`. The settings in `positionInLandscapeMode` and + * Use the value you set in `WatermarkRatio`. The settings in `positionInLandscapeMode` and * `positionInPortraitMode` in `WatermarkOptions` are invalid. */ - FIT_MODE_USE_IMAGE_RATIO = 1, + FIT_MODE_USE_IMAGE_RATIO }; /** @@ -1562,7 +1478,7 @@ struct EncodedAudioFrameAdvancedSettings { }; /** - * @brief Audio information after encoding. + * The definition of the EncodedAudioFrameInfo struct. */ struct EncodedAudioFrameInfo { EncodedAudioFrameInfo() @@ -1580,23 +1496,25 @@ struct EncodedAudioFrameInfo { advancedSettings(rhs.advancedSettings), captureTimeMs(rhs.captureTimeMs) {} /** - * Audio Codec type: `AUDIO_CODEC_TYPE`. + * The audio codec: #AUDIO_CODEC_TYPE. */ AUDIO_CODEC_TYPE codec; /** - * Audio sample rate (Hz). + * The sample rate (Hz) of the audio frame. */ int sampleRateHz; /** - * The number of audio samples per channel. + * The number of samples per audio channel. + * + * If this value is not set, it is 1024 for AAC, or 960 for OPUS by default. */ int samplesPerChannel; /** - * The number of audio channels. + * The number of audio channels of the audio frame. */ int numberOfChannels; /** - * This function is currently not supported. + * The advanced settings of the audio frame. */ EncodedAudioFrameAdvancedSettings advancedSettings; @@ -1655,86 +1573,78 @@ enum H264PacketizeMode { }; /** - * @brief The type of video streams. + * Video stream types. */ enum VIDEO_STREAM_TYPE { /** - * 0: High-quality video stream, that is, a video stream with the highest resolution and bitrate. + * 0: The high-quality video stream, which has the highest resolution and bitrate. */ VIDEO_STREAM_HIGH = 0, /** - * 1: Low-quality video stream, that is, a video stream with the lowest resolution and bitrate. + * 1: The low-quality video stream, which has the lowest resolution and bitrate. */ VIDEO_STREAM_LOW = 1, /** - * 4. Video stream layer 1. The resolution of this quality level is only lower than that of - * VIDEO_STREAM_HIGH. + * 4: The video stream of layer_1, which has a lower resolution and bitrate than VIDEO_STREAM_HIGH. */ VIDEO_STREAM_LAYER_1 = 4, /** - * 5: Video stream layer 2. The resolution of this quality level is only lower than that of - * VIDEO_STREAM_LAYER_1. + * 5: The video stream of layer_2, which has a lower resolution and bitrate than VIDEO_STREAM_LAYER_1. */ VIDEO_STREAM_LAYER_2 = 5, /** - * 6: Video stream layer 3. The resolution of this quality level is only lower than that of - * VIDEO_STREAM_LAYER_2. + * 6: The video stream of layer_3, which has a lower resolution and bitrate than VIDEO_STREAM_LAYER_2. */ VIDEO_STREAM_LAYER_3 = 6, /** - * 7: Video stream layer 4. The resolution of this quality level is only lower than that of - * VIDEO_STREAM_LAYER_3. + * 7: The video stream of layer_4, which has a lower resolution and bitrate than VIDEO_STREAM_LAYER_3. */ VIDEO_STREAM_LAYER_4 = 7, /** - * 8: Video stream layer 5. The resolution of this quality level is only lower than that of - * VIDEO_STREAM_LAYER_4. + * 8: The video stream of layer_5, which has a lower resolution and bitrate than VIDEO_STREAM_LAYER_4. */ VIDEO_STREAM_LAYER_5 = 8, /** - * 9: Video stream layer 6. The resolution of this quality level is only lower than that of - * VIDEO_STREAM_LAYER_5. + * 9: The video stream of layer_6, which has a lower resolution and bitrate than VIDEO_STREAM_LAYER_5. */ VIDEO_STREAM_LAYER_6 = 9, }; -/** - * @brief Video subscription options. - */ struct VideoSubscriptionOptions { /** - * The video stream type that you want to subscribe to. The default value is VIDEO_STREAM_HIGH, - * indicating that the high-quality video streams are subscribed. See `VIDEO_STREAM_TYPE`. + * The type of the video stream to subscribe to. + * + * The default value is `VIDEO_STREAM_HIGH`, which means the high-quality + * video stream. */ Optional type; /** - * Whether to subscribe to encoded video frames only: - * - `true`: Subscribe to the encoded video data (structured data) only; the SDK does not decode or - * render raw video data. - * - `false`: (Default) Subscribe to both raw video data and encoded video data. + * Whether to subscribe to encoded video data only: + * - `true`: Subscribe to encoded video data only. + * - `false`: (Default) Subscribe to decoded video data. */ Optional encodedFrameOnly; VideoSubscriptionOptions() {} }; -/** - * @brief The maximum length of the user account. +/** The maximum length of the user account. */ enum MAX_USER_ACCOUNT_LENGTH_TYPE { - /** - * The maximum length of the user account is 256 bytes. + /** The maximum length of the user account is 256 bytes. */ MAX_USER_ACCOUNT_LENGTH = 256 }; /** - * @brief Information about externally encoded video frames. + * The definition of the EncodedVideoFrameInfo struct, which contains the information of the + * external encoded video frame. */ struct EncodedVideoFrameInfo { EncodedVideoFrameInfo() - : codecType(VIDEO_CODEC_H264), + : uid(0), + codecType(VIDEO_CODEC_H264), width(0), height(0), framesPerSecond(0), @@ -1747,7 +1657,8 @@ struct EncodedVideoFrameInfo { presentationMs(-1) {} EncodedVideoFrameInfo(const EncodedVideoFrameInfo& rhs) - : codecType(rhs.codecType), + : uid(rhs.uid), + codecType(rhs.codecType), width(rhs.width), height(rhs.height), framesPerSecond(rhs.framesPerSecond), @@ -1761,6 +1672,7 @@ struct EncodedVideoFrameInfo { EncodedVideoFrameInfo& operator=(const EncodedVideoFrameInfo& rhs) { if (this == &rhs) return *this; + uid = rhs.uid; codecType = rhs.codecType; width = rhs.width; height = rhs.height; @@ -1776,47 +1688,51 @@ struct EncodedVideoFrameInfo { } /** - * The codec type of the local video stream. See `VIDEO_CODEC_TYPE`. The default value is - * `VIDEO_CODEC_H264 (2)`. + * ID of the user that pushes the the external encoded video frame.. + */ + uid_t uid; + /** + * The codec type of the local video stream. See #VIDEO_CODEC_TYPE. The default value is + * `VIDEO_CODEC_H265 (3)`. */ VIDEO_CODEC_TYPE codecType; /** - * Width (pixel) of the video frame. + * The width (px) of the video frame. */ int width; /** - * Height (pixel) of the video frame. + * The height (px) of the video frame. */ int height; /** * The number of video frames per second. - * When this parameter is not `0`, you can use it to calculate the Unix timestamp of externally + * When this parameter is not 0, you can use it to calculate the Unix timestamp of the external * encoded video frames. */ int framesPerSecond; /** - * The video frame type. See `VIDEO_FRAME_TYPE`. + * The video frame type: #VIDEO_FRAME_TYPE. */ VIDEO_FRAME_TYPE frameType; /** - * The rotation information of the video frame. See `VIDEO_ORIENTATION`. + * The rotation information of the video frame: #VIDEO_ORIENTATION. */ VIDEO_ORIENTATION rotation; /** - * Reserved for future use. + * The track ID of the video frame. */ int trackId; // This can be reserved for multiple video tracks, we need to create different ssrc // and additional payload for later implementation. /** - * The Unix timestamp (ms) for capturing the external encoded video frames. + * This is a input parameter which means the timestamp for capturing the video. */ int64_t captureTimeMs; /** - * The Unix timestamp (ms) for decoding the external encoded video frames. + * The timestamp for decoding the video. */ int64_t decodeTimeMs; /** - * The type of video streams. See `VIDEO_STREAM_TYPE`. + * The stream type of video frame. */ VIDEO_STREAM_TYPE streamType; @@ -1825,104 +1741,96 @@ struct EncodedVideoFrameInfo { }; /** - * @brief Compression preference for video encoding. + * Video compression preference. */ enum COMPRESSION_PREFERENCE { /** - * -1: (Default) Automatic mode. The SDK will automatically select PREFER_LOW_LATENCY or - * PREFER_QUALITY based on the video scenario you set to achieve the best user experience. - */ + * (Default) SDK uses compression preference according to setVideoScenario API settings, real-time network state and other relevant data information. + * If API setVideoScenario set video scenario to APPLICATION_SCENARIO_LIVESHOW, then PREFER_QUALITY is used. If not, then PREFER_LOW_LATENCY is used. + * Also if network state has changed, SDK may change this parameter between PREFER_QUALITY and PREFER_LOW_LATENCY automatically to get the best QOE. + * We recommend using this option. + */ PREFER_COMPRESSION_AUTO = -1, /** - * 0: Low latency preference. The SDK compresses video frames to reduce latency. This preference is - * suitable for scenarios where smoothness is prioritized and reduced video quality is acceptable. - */ + * Prefer low latency, usually used in real-time communication where low latency is the number one priority. + */ PREFER_LOW_LATENCY = 0, /** - * 1: High quality preference. The SDK compresses video frames while maintaining video quality. This - * preference is suitable for scenarios where video quality is prioritized. - */ + * Prefer quality in sacrifice of a degree of latency, usually around 30ms ~ 150ms, depends target fps + */ PREFER_QUALITY = 1, }; /** - * @brief Video encoder preference. + * The video encoder type preference. */ enum ENCODING_PREFERENCE { /** - * -1: Adaptive preference. The SDK automatically selects the optimal encoding type for encoding - * based on factors such as platform and device type. + *Default . */ PREFER_AUTO = -1, /** - * 0: Software coding preference. The SDK prefers software encoders for video encoding. + * Software encoding. */ PREFER_SOFTWARE = 0, /** - * 1: Hardware encoding preference. The SDK prefers a hardware encoder for video encoding. When the - * device does not support hardware encoding, the SDK automatically uses software encoding and - * reports the currently used video encoder type through `hwEncoderAccelerating` in the - * `onLocalVideoStats` callback. + * Hardware encoding */ PREFER_HARDWARE = 1, }; /** - * @brief Advanced options for video encoding. + * The definition of the AdvanceOptions struct. */ struct AdvanceOptions { /** - * Video encoder preference. See `ENCODING_PREFERENCE`. + * The video encoder type preference.. */ ENCODING_PREFERENCE encodingPreference; /** - * Compression preference for video encoding. See `COMPRESSION_PREFERENCE`. + * Video compression preference. */ COMPRESSION_PREFERENCE compressionPreference; /** - * Whether to encode and send the Alpha data present in the video frame to the remote end: - * - `true`: Encode and send Alpha data. - * - `false`: (Default) Do not encode and send Alpha data. - */ + * Whether to encode and send the alpha data to the remote when alpha data is present. + * The default value is false. + */ bool encodeAlpha; - AdvanceOptions() : encodingPreference(PREFER_AUTO), + AdvanceOptions() : encodingPreference(PREFER_AUTO), compressionPreference(PREFER_COMPRESSION_AUTO), encodeAlpha(false) {} - AdvanceOptions(ENCODING_PREFERENCE encoding_preference, + AdvanceOptions(ENCODING_PREFERENCE encoding_preference, COMPRESSION_PREFERENCE compression_preference, - bool encode_alpha) : + bool encode_alpha) : encodingPreference(encoding_preference), compressionPreference(compression_preference), encodeAlpha(encode_alpha) {} bool operator==(const AdvanceOptions& rhs) const { - return encodingPreference == rhs.encodingPreference && + return encodingPreference == rhs.encodingPreference && compressionPreference == rhs.compressionPreference && encodeAlpha == rhs.encodeAlpha; } }; /** - * @brief Video mirror mode. + * Video mirror mode types. */ enum VIDEO_MIRROR_MODE_TYPE { /** - * 0: The SDK determines the mirror mode. - * - For the mirror mode of the local video view: If you use a front camera, the SDK enables the - * mirror mode by default; if you use a rear camera, the SDK disables the mirror mode by default. - * - For the remote user: The mirror mode is disabled by default. + * 0: The mirror mode determined by the SDK. */ VIDEO_MIRROR_MODE_AUTO = 0, /** - * 1: Enable mirror mode. + * 1: Enable the mirror mode. */ VIDEO_MIRROR_MODE_ENABLED = 1, /** - * 2: Disable mirror mode. + * 2: Disable the mirror mode. */ VIDEO_MIRROR_MODE_DISABLED = 2, }; @@ -1953,7 +1861,7 @@ enum VIDEO_MODULE_TYPE { /** Video render module */ VIDEO_MODULE_RENDERER = 5, }; - + enum HDR_CAPABILITY { /** The result of static check is not reliable, by defualt*/ HDR_CAPABILITY_UNKNOWN = -1, @@ -1963,49 +1871,26 @@ enum HDR_CAPABILITY { HDR_CAPABILITY_SUPPORTED = 1, }; -/** - * @brief The bit mask of the codec type. - */ +/** Supported codec type bit mask. */ enum CODEC_CAP_MASK { - /** - * (0): The device does not support encoding or decoding. - */ + /** 0: No codec support. */ CODEC_CAP_MASK_NONE = 0, - /** - * (1 << 0): The device supports hardware decoding. - */ + /** bit 1: Hardware decoder support flag. */ CODEC_CAP_MASK_HW_DEC = 1 << 0, - /** - * (1 << 1): The device supports hardware encoding. - */ + /** bit 2: Hardware encoder support flag. */ CODEC_CAP_MASK_HW_ENC = 1 << 1, - /** - * (1 << 2): The device supports software decoding. - */ + /** bit 3: Software decoder support flag. */ CODEC_CAP_MASK_SW_DEC = 1 << 2, - /** - * (1 << 3): The device supports software ecoding. - */ + /** bit 4: Software encoder support flag. */ CODEC_CAP_MASK_SW_ENC = 1 << 3, }; -/** - * @brief The level of the codec capability. - */ struct CodecCapLevels { - /** - * Hardware decoding capability level, which represents the device's ability to perform hardware - * decoding on videos of different quality. See `VIDEO_CODEC_CAPABILITY_LEVEL`. - */ VIDEO_CODEC_CAPABILITY_LEVEL hwDecodingLevel; - /** - * Software decoding capability level, which represents the device's ability to perform software - * decoding on videos of different quality. See `VIDEO_CODEC_CAPABILITY_LEVEL`. - */ VIDEO_CODEC_CAPABILITY_LEVEL swDecodingLevel; CodecCapLevels() @@ -2013,103 +1898,136 @@ struct CodecCapLevels { swDecodingLevel(CODEC_CAPABILITY_LEVEL_UNSPECIFIED) {} }; -/** - * @brief The codec capability of the SDK. - */ +/** The codec support information. */ struct CodecCapInfo { - /** - * The video codec types. See `VIDEO_CODEC_TYPE`. - */ + /** The codec type: #VIDEO_CODEC_TYPE. */ VIDEO_CODEC_TYPE codecType; - /** - * Bit mask of the codec types in SDK. See `CODEC_CAP_MASK`. - */ + /** The codec support flag. */ int codecCapMask; - /** - * Codec capability of the SDK. See `CodecCapLevels`. - */ + /** The codec capability level, estimated based on the device hardware.*/ CodecCapLevels codecLevels; CodecCapInfo() : codecType(VIDEO_CODEC_NONE), codecCapMask(0) {} }; -/** - * @brief Focal length information supported by the camera, including the camera direction and focal - * length type. - * - * @note This enumeration class applies to Android and iOS only. - * +/** FocalLengthInfo contains the IDs of the front and rear cameras, along with the wide-angle types. */ struct FocalLengthInfo { - /** - * The camera direction. See `CAMERA_DIRECTION`. - */ + /** The camera direction. */ int cameraDirection; - /** - * The focal length type. See `CAMERA_FOCAL_LENGTH_TYPE`. - */ + /** Camera focal segment type. */ CAMERA_FOCAL_LENGTH_TYPE focalLengthType; }; /** - * @brief Video encoder configurations. + * The definition of the VideoEncoderConfiguration struct. */ struct VideoEncoderConfiguration { /** - * The codec type of the local video stream. See `VIDEO_CODEC_TYPE`. + * The video encoder code type: #VIDEO_CODEC_TYPE. */ VIDEO_CODEC_TYPE codecType; /** - * The dimensions of the encoded video (px). See `VideoDimensions`. This parameter measures the - * video encoding quality in the format of length × width. The default value is 960 × 540. You can - * set a custom value. + * The video dimension: VideoDimensions. */ VideoDimensions dimensions; /** - * The frame rate (fps) of the encoding video frame. The default value is 15. See `FRAME_RATE`. + * The frame rate of the video. You can set it manually, or choose one from #FRAME_RATE. */ int frameRate; /** - * The encoding bitrate (Kbps) of the video. This parameter does not need to be set; keeping the - * default value `STANDARD_BITRATE` is sufficient. The SDK automatically matches the most suitable - * bitrate based on the video resolution and frame rate you have set. For the correspondence between - * video resolution and frame rate, see `Video profile`. - * - STANDARD_BITRATE (0): (Recommended) Standard bitrate mode. - * - COMPATIBLE_BITRATE (-1): Adaptive bitrate mode. In general, Agora suggests that you do not use - * this value. + * The bitrate (Kbps) of the video. + * + * Refer to the **Video Bitrate Table** below and set your bitrate. If you set a bitrate beyond + * the proper range, the SDK automatically adjusts it to a value within the range. You can also + * choose from the following options: + * + * - #STANDARD_BITRATE: (Recommended) Standard bitrate mode. In this mode, the bitrates differ + * between the Live Broadcast and Communication profiles: + * - In the Communication profile, the video bitrate is the same as the base bitrate. + * - In the Live Broadcast profile, the video bitrate is twice the base bitrate. + * - #COMPATIBLE_BITRATE: Compatible bitrate mode. The compatible bitrate mode. In this mode, the + * bitrate stays the same regardless of the profile. If you choose this mode for the Live + * Broadcast profile, the video frame rate may be lower than the set value. + * + * Agora uses different video codecs for different profiles to optimize the user experience. For + * example, the communication profile prioritizes the smoothness while the live-broadcast profile + * prioritizes the video quality (a higher bitrate). Therefore, We recommend setting this + * parameter as #STANDARD_BITRATE. + * + * | Resolution | Frame Rate (fps) | Base Bitrate (Kbps) | Live Bitrate (Kbps)| + * |------------------------|------------------|---------------------|--------------------| + * | 160 * 120 | 15 | 65 | 110 | + * | 120 * 120 | 15 | 50 | 90 | + * | 320 * 180 | 15 | 140 | 240 | + * | 180 * 180 | 15 | 100 | 160 | + * | 240 * 180 | 15 | 120 | 200 | + * | 320 * 240 | 15 | 200 | 300 | + * | 240 * 240 | 15 | 140 | 240 | + * | 424 * 240 | 15 | 220 | 370 | + * | 640 * 360 | 15 | 400 | 680 | + * | 360 * 360 | 15 | 260 | 440 | + * | 640 * 360 | 30 | 600 | 1030 | + * | 360 * 360 | 30 | 400 | 670 | + * | 480 * 360 | 15 | 320 | 550 | + * | 480 * 360 | 30 | 490 | 830 | + * | 640 * 480 | 15 | 500 | 750 | + * | 480 * 480 | 15 | 400 | 680 | + * | 640 * 480 | 30 | 750 | 1130 | + * | 480 * 480 | 30 | 600 | 1030 | + * | 848 * 480 | 15 | 610 | 920 | + * | 848 * 480 | 30 | 930 | 1400 | + * | 640 * 480 | 10 | 400 | 600 | + * | 960 * 540 | 15 | 750 | 1100 | + * | 960 * 540 | 30 | 1110 | 1670 | + * | 1280 * 720 | 15 | 1130 | 1600 | + * | 1280 * 720 | 30 | 1710 | 2400 | + * | 960 * 720 | 15 | 910 | 1280 | + * | 960 * 720 | 30 | 1380 | 2000 | + * | 1920 * 1080 | 15 | 2080 | 2500 | + * | 1920 * 1080 | 30 | 3150 | 3780 | + * | 1920 * 1080 | 60 | 4780 | 5730 | + * | 2560 * 1440 | 30 | 4850 | 4850 | + * | 2560 * 1440 | 60 | 7350 | 7350 | + * | 3840 * 2160 | 30 | 8910 | 8910 | + * | 3840 * 2160 | 60 | 13500 | 13500 | */ int bitrate; /** - * The minimum encoding bitrate (Kbps) of the video. - * The SDK automatically adjusts the encoding bitrate to adapt to the network conditions. Using a - * value greater than the default value forces the video encoder to output high-quality images but - * may cause more packet loss and sacrifice the smoothness of the video transmission. Unless you - * have special requirements for image quality, Agora does not recommend changing this value. - * @note This parameter only applies to the interactive streaming profile. + * The minimum encoding bitrate (Kbps). + * + * The Agora SDK automatically adjusts the encoding bitrate to adapt to the + * network conditions. + * + * Using a value greater than the default value forces the video encoder to + * output high-quality images but may cause more packet loss and hence + * sacrifice the smoothness of the video transmission. That said, unless you + * have special requirements for image quality, Agora does not recommend + * changing this value. + * + * @note + * This parameter applies to the live-broadcast profile only. */ int minBitrate; /** - * The orientation mode of the encoded video. See `ORIENTATION_MODE`. + * The video orientation mode: #ORIENTATION_MODE. */ ORIENTATION_MODE orientationMode; /** - * Video degradation preference under limited bandwidth. See `DEGRADATION_PREFERENCE`. - * @note When this parameter is set to MAINTAIN_FRAMERATE (1) or MAINTAIN_BALANCED (2), - * `orientationMode` needs to be set to ORIENTATION_MODE_ADAPTIVE (0) at the same time, otherwise - * the setting will not take effect. + * The video degradation preference under limited bandwidth: #DEGRADATION_PREFERENCE. */ DEGRADATION_PREFERENCE degradationPreference; /** - * Sets the mirror mode of the published local video stream. It only affects the video that the - * remote user sees. See `VIDEO_MIRROR_MODE_TYPE`. - * @note By default, the video is not mirrored. + * The mirror mode is disabled by default + * If mirror_type is set to VIDEO_MIRROR_MODE_ENABLED, then the video frame would be mirrored + * before encoding. */ VIDEO_MIRROR_MODE_TYPE mirrorMode; /** - * Advanced options for video encoding. See `AdvanceOptions`. + * The advanced options for the video encoder configuration. See AdvanceOptions. */ AdvanceOptions advanceOptions; @@ -2170,34 +2088,26 @@ struct VideoEncoderConfiguration { }; /** - * @brief The configurations for the data stream. - * - * @details - * The following table shows the SDK behaviors under different parameter settings: - * | `syncWithAudio` | `ordered` | SDK behaviors | - * | --------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - * | `false` | `false` | The SDK triggers the `onStreamMessage` callback immediately after the receiver receives a data packet. | - * | `true` | `false` | If the data packet delay is within the audio delay, the SDK triggers the onStreamMessage callback when the synchronized audio packet is played out. If the data packet delay exceeds the audio delay, the SDK triggers the onStreamMessage callback as soon as the data packet is received. | - * | `false` | `true` | If the delay of a data packet is less than five seconds, the SDK corrects the order of the data packet. If the delay of a data packet exceeds five seconds, the SDK discards the data packet. | - * | `true` | `true` | If the delay of the data packet is within the range of the audio delay, the SDK corrects the order of the data packet. If the delay of a data packet exceeds the audio delay, the SDK discards this data packet. | - * + * The configurations for the data stream. */ struct DataStreamConfig { /** * Whether to synchronize the data packet with the published audio packet. - * - `true`: Synchronize the data packet with the audio packet. This setting is suitable for special - * scenarios such as lyrics synchronization. - * - `false`: Do not synchronize the data packet with the audio packet. This setting is suitable for - * scenarios where data packets need to arrive at the receiving end immediately. + * - `true`: Synchronize the data packet with the audio packet. + * - `false`: Do not synchronize the data packet with the audio packet. + * * When you set the data packet to synchronize with the audio, then if the data packet delay is * within the audio delay, the SDK triggers the `onStreamMessage` callback when the synchronized - * audio packet is played out. + * audio packet is played out. Do not set this parameter as true if you need the receiver to + * receive the data packet immediately. Agora recommends that you set this parameter to `true` + * only when you need to implement specific functions, for example lyric synchronization. */ bool syncWithAudio; /** * Whether the SDK guarantees that the receiver receives the data in the sent order. * - `true`: Guarantee that the receiver receives the data in the sent order. * - `false`: Do not guarantee that the receiver receives the data in the sent order. + * * Do not set this parameter as `true` if you need the receiver to receive the data packet * immediately. */ @@ -2205,42 +2115,38 @@ struct DataStreamConfig { }; /** - * @brief The mode in which the video stream is sent. + * The definition of SIMULCAST_STREAM_MODE */ enum SIMULCAST_STREAM_MODE { - /** - * -1: By default, do not send the low-quality video stream until a subscription request for the - * low-quality video stream is received from the receiving end, then automatically start sending - * low-quality video stream. + /* + * disable simulcast stream until receive request for enable simulcast stream by other broadcaster */ AUTO_SIMULCAST_STREAM = -1, - /** - * 0: Never send low-quality video stream. + /* + * disable simulcast stream */ DISABLE_SIMULCAST_STREAM = 0, - /** - * 1: Always send low-quality video stream. + /* + * always enable simulcast stream */ ENABLE_SIMULCAST_STREAM = 1, }; /** - * @brief The configuration of the low-quality video stream. + * The configuration of the low-quality video stream. */ struct SimulcastStreamConfig { /** - * The video dimension. See `VideoDimensions`. The default value is 50% of the high-quality video - * stream. + * The video frame dimension: VideoDimensions. The default value is 160 × 120. */ VideoDimensions dimensions; /** - * Video bitrate (Kbps). The default value is -1. This parameter does not need to be set. The SDK - * automatically matches the most suitable bitrate based on the video resolution and frame rate you - * set. + * The video bitrate (Kbps), represented by an instantaneous value. The default value of the log + * level is 5. */ int kBitrate; /** - * The frame rate (fps) of the local video. The default value is 5. + * The capture frame rate (fps) of the local video. The default value is 5. */ int framerate; SimulcastStreamConfig() : dimensions(160, 120), kBitrate(65), framerate(5) {} @@ -2251,93 +2157,70 @@ struct SimulcastStreamConfig { }; /** - * @brief Configure video streams of different quality levels. - * - * @since v4.6.0 + * The configuration of the multi-layer video stream. */ struct SimulcastConfig { /** - * @brief Index of video streams of different quality levels. + * The index of multi-layer video stream */ enum StreamLayerIndex { /** - * （0）: Video stream layer_1, with lower resolution and bitrate than VIDEO_STREAM_HIGH. + * 0: video stream index of layer_1 */ STREAM_LAYER_1 = 0, /** - * （1）: Video stream layer_2, with lower resolution and bitrate than VIDEO_STREAM_LAYER_1. + * 1: video stream index of layer_2 */ STREAM_LAYER_2 = 1, /** - * （2）: Video stream layer_3, with lower resolution and bitrate than VIDEO_STREAM_LAYER_2. + * 2: video stream index of layer_3 */ STREAM_LAYER_3 = 2, /** - * （3）: Video stream layer_4, with lower resolution and bitrate than VIDEO_STREAM_LAYER_3. + * 3: video stream index of layer_4 */ STREAM_LAYER_4 = 3, /** - * （4）: Video stream layer_5, with lower resolution and bitrate than VIDEO_STREAM_LAYER_4. + * 4: video stream index of layer_5 */ STREAM_LAYER_5 = 4, /** - * （5）: Video stream layer_6, with lower resolution and bitrate than VIDEO_STREAM_LAYER_5. + * 5: video stream index of layer_6 */ STREAM_LAYER_6 = 5, /** - * （6）: Low-quality video stream, with the lowest resolution and bitrate. + * 6: video stream index of low */ STREAM_LOW = 6, /** - * （7）: Maximum number of video stream layers. + * 7: max count of video stream layers */ STREAM_LAYER_COUNT_MAX = 7 }; - /** - * @brief Configures the parameters of a specific layer in multi-quality video streams. - * - * @details - * Used to configure the resolution, frame rate, and enable status of a specific layer in - * multi-quality video streams. - * - */ struct StreamLayerConfig { /** - * Video frame size. Default is 0. See `VideoDimensions`. + * The video frame dimension. The default value is 0. */ VideoDimensions dimensions; /** - * Frame rate (fps) of the local video capture. Default is 0. + * The capture frame rate (fps) of the local video. The default value is 0. */ int framerate; /** - * Whether to enable the video stream for the corresponding layer. Default is false. - * - `true`: Enables the video stream for the corresponding layer. - * - `false`: (Default) Disables the video stream for the corresponding layer. + * Whether to enable the corresponding layer of video stream. The default value is false. */ bool enable; StreamLayerConfig() : dimensions(0, 0), framerate(0), enable(false) {} }; /** - * Configurations for multi-layer streaming: `StreamLayerConfig`. + * The array of StreamLayerConfig, which contains STREAM_LAYER_COUNT_MAX layers of video stream at most. */ StreamLayerConfig configs[STREAM_LAYER_COUNT_MAX]; - /** - * Whether to enable fallback publishing: - * - `true`: Enable fallback publishing. When the device performance or network is poor at the - * publishing end, the SDK will dynamically disable multiple video streams of different quality - * levels, from layer1 to layer6. At least the video streams of the highest and lowest quality are - * retained to maintain basic video continuity. - * - `false`: (Default) Disable fallback publishing. - */ - bool publish_fallback_enable; - - SimulcastConfig(): publish_fallback_enable(false) {} }; /** - * @brief The location of the target area relative to the screen or window. If you do not set this - * parameter, the SDK selects the whole screen or window. + * The location of the target area relative to the screen or window. If you do not set this parameter, + * the SDK selects the whole screen or window. */ struct Rectangle { /** @@ -2349,11 +2232,11 @@ struct Rectangle { */ int y; /** - * The width of the target area. + * The width of the region. */ int width; /** - * The height of the target area. + * The height of the region. */ int height; @@ -2362,28 +2245,26 @@ struct Rectangle { }; /** - * @brief The position and size of the watermark on the screen. + * The position and size of the watermark on the screen. * - * @details * The position and size of the watermark on the screen are determined by `xRatio`, `yRatio`, and * `widthRatio`: - * - ( `xRatio`, `yRatio` ) refers to the coordinates of the upper left corner of the watermark, - * which determines the distance from the upper left corner of the watermark to the upper left - * corner of the screen. - * - The `widthRatio` determines the width of the watermark. - * + * - (`xRatio`, `yRatio`) refers to the coordinates of the upper left corner of the watermark, which + * determines the distance from the upper left corner of the watermark to the upper left corner of + * the screen. The `widthRatio` determines the width of the watermark. */ struct WatermarkRatio { /** * The x-coordinate of the upper left corner of the watermark. The horizontal position relative to - * the origin, where the upper left corner of the screen is the origin, and the x-coordinate is the - * upper left corner of the watermark. The value range is [0.0,1.0], and the default value is 0. + * the origin, where the upper left corner of the screen is the origin, and the x-coordinate is + * the upper left corner of the watermark. The value range is [0.0,1.0], and the default value is + * 0. */ float xRatio; /** - * The y-coordinate of the upper left corner of the watermark. The vertical position relative to the - * origin, where the upper left corner of the screen is the origin, and the y-coordinate is the - * upper left corner of the screen. The value range is [0.0,1.0], and the default value is 0. + * The y-coordinate of the upper left corner of the watermark. The vertical position relative to + * the origin, where the upper left corner of the screen is the origin, and the y-coordinate is + * the upper left corner of the screen. The value range is [0.0,1.0], and the default value is 0. */ float yRatio; /** @@ -2399,401 +2280,206 @@ struct WatermarkRatio { }; /** - * @brief Watermark image configurations. - * - * @details - * Configuration options for setting the watermark image to be added. - * + * Configurations of the watermark image. */ struct WatermarkOptions { /** - * Whether the watermark is visible in the local preview view: - * - `true`: (Default) The watermark is visible in the local preview view. - * - `false`: The watermark is not visible in the local preview view. + * Whether or not the watermark image is visible in the local video preview: + * - true: (Default) The watermark image is visible in preview. + * - false: The watermark image is not visible in preview. */ bool visibleInPreview; /** - * When the adaptation mode of the watermark is FIT_MODE_COVER_POSITION, it is used to set the area - * of the watermark image in landscape mode. See `Rectangle`. + * When the adaptation mode of the watermark is `FIT_MODE_COVER_POSITION`, it is used to set the + * area of the watermark image in landscape mode. See #FIT_MODE_COVER_POSITION for details. */ Rectangle positionInLandscapeMode; /** - * When the adaptation mode of the watermark is FIT_MODE_COVER_POSITION, it is used to set the area - * of the watermark image in portrait mode. See `Rectangle`. + * When the adaptation mode of the watermark is `FIT_MODE_COVER_POSITION`, it is used to set the + * area of the watermark image in portrait mode. See #FIT_MODE_COVER_POSITION for details. */ Rectangle positionInPortraitMode; /** - * When the watermark adaptation mode is FIT_MODE_USE_IMAGE_RATIO, this parameter is used to set the - * watermark coordinates. See `WatermarkRatio`. + * When the watermark adaptation mode is `FIT_MODE_USE_IMAGE_RATIO`, this parameter is used to set + * the watermark coordinates. See WatermarkRatio for details. */ WatermarkRatio watermarkRatio; /** - * The adaptation mode of the watermark. See `WATERMARK_FIT_MODE`. + * The adaptation mode of the watermark. See #WATERMARK_FIT_MODE for details. */ WATERMARK_FIT_MODE mode; - /** - * Layer order of the watermark image. The default value is 0. - */ - int zOrder; WatermarkOptions() : visibleInPreview(true), positionInLandscapeMode(0, 0, 0, 0), positionInPortraitMode(0, 0, 0, 0), - mode(FIT_MODE_COVER_POSITION), - zOrder(0) {} + mode(FIT_MODE_COVER_POSITION) {} }; /** - * @brief Type of watermark source. - * - * @since 4.6.0 + * @brief Defines how data is transmitted across multiple network paths. */ -enum WATERMARK_SOURCE_TYPE { +enum MultipathMode { + + /** + * Duplicate mode, the same piece of data is redundantly transmitted over all available paths. + * @technical preview + */ + Duplicate= 0, + /** + * Dynamic mode, the data is transmitted only over the path that the internal algorithm determines to be optimal for transmission quality. + */ + Dynamic +}; + +/** + * @brief Defines the types of network paths used in multipath transmission. + */ +enum MultipathType { /** - * (0): The watermark source is an image. + * The local area network (LAN) path. */ - IMAGE = 0, + LAN = 0, /** - * (1): The watermark source is a buffer. + * The Wi-Fi path. */ - BUFFER = 1, + WIFI, /** - * 2: The watermark source is a literal. - * - * @note This is only supported in linux platform. + * The mobile network path. */ - LITERAL = 2, + Mobile, /** - * 3: The watermark source is a timestamp. - * - * @note This is only supported in linux platform. + * An unknown or unspecified network path. */ - TIMESTAMPS = 3, + Unknown = 99 }; /** - * @brief The definition of the WatermarkTimestamp struct. - * - * @since 4.6.0 - * @note This is only supported in linux platform. + * @brief Contains statistics for a specific network path in multipath transmission. */ -struct WatermarkTimestamp{ - /** - * The font size of the timestamp. The default value is 10. - */ - int fontSize; +struct PathStats { /** - * The path of the font file for the timestamp. The default value is NULL. - * The font file should be a .ttf file. If not set, the SDK uses the system default font if available. - * - * @note If used asynchronously, copy the path to memory that will not be released. + * The type of the path. */ - const char* fontFilePath; + MultipathType type; /** - * The stroke width of the timestamp. The default value is 1. + * The transmission bitrate of the path. */ - int strokeWidth; + int txKBitRate; /** - * The format of the timestamp. The default is '%F %X'. - * The format follows the standard C library function strftime. You can find in the website: - * https://cplusplus.com/reference/ctime/strftime/?kw=strftime - * - * @note If used asynchronously, copy the format string to memory that will not be released. + * The receiving bitrate of the path. */ - const char* format; - - WatermarkTimestamp() : fontSize(10), fontFilePath(NULL), strokeWidth(1), format(NULL) {} + int rxKBitRate; + PathStats() : type(Unknown), txKBitRate(0), rxKBitRate(0) {} + PathStats(MultipathType t, int tx, int rx) : type(t), txKBitRate(tx), rxKBitRate(rx) {} }; + /** - * @brief The definition of the WatermarkLiteral struct. - * - * @since 4.6.0 - * @note This is only supported in linux platform.. + * @brief Aggregates statistics for all network paths used in multipath transmission. */ -struct WatermarkLiteral { - - /** - * The font size of the literal. The default value is 10. - */ - int fontSize; +struct MultipathStats { /** - * The stroke width of the literal. The default value is 1. + * The number of bytes transmitted over the LAN path. */ - int strokeWidth; + uint32_t lanTxBytes; /** - * The literal content of the watermark. The default value is NULL. - * - * @note If used asynchronously, copy the string to memory that will not be released. + * The number of bytes received over the LAN path. */ - const char* wmLiteral; + uint32_t lanRxBytes; /** - * The path of the font file for the literal. The default value is NULL. - * The font file should be a .ttf file. If not set, the SDK uses the system default font if available. - * - * @note If used asynchronously, copy the string to memory that will not be released. + * The number of bytes transmitted over the Wi-Fi path. */ - const char* fontFilePath; - - WatermarkLiteral() : wmLiteral(NULL), fontFilePath(NULL), fontSize(10), strokeWidth(1) {} -}; - -/** - * @brief Configures the format, size, and pixel buffer of the watermark image. - * - * @since 4.6.0 - * - * @details - * Defines the buffer data structure of the watermark image, including image width, height, format, - * length, and image data buffer. - * - */ -struct WatermarkBuffer { - + uint32_t wifiTxBytes; /** - * Width of the watermark buffer, in pixels. + * The number of bytes received over the Wi-Fi path. */ - int width; + uint32_t wifiRxBytes; /** - * Height of the watermark buffer, in pixels. + * The number of bytes transmitted over the mobile network path. */ - int height; + uint32_t mobileTxBytes; /** - * Length of the watermark buffer, in bytes. + * The number of bytes received over the mobile network path. */ - int length; + uint32_t mobileRxBytes; /** - * Format of the watermark buffer. See `VIDEO_PIXEL_FORMAT`. Default is VIDEO_PIXEL_I420. Currently - * supported formats include: VIDEO_PIXEL_I420, VIDEO_PIXEL_RGBA, VIDEO_PIXEL_BGRA, and - * VIDEO_PIXEL_NV21. + * The number of active paths. */ - media::base::VIDEO_PIXEL_FORMAT format; - + int activePathNum; /** - * Buffer data of the watermark. + * “An array of statistics for each active path. */ - const uint8_t* buffer; - - WatermarkBuffer() : buffer(NULL), width(0), height(0), length(0), format(media::base::VIDEO_PIXEL_I420) {} + const PathStats* pathStats; + MultipathStats() + : lanTxBytes(0), + lanRxBytes(0), + wifiTxBytes(0), + wifiRxBytes(0), + mobileTxBytes(0), + mobileRxBytes(0), + activePathNum(0), + pathStats(nullptr) {} }; /** - * @brief Used to configure watermark-related information. - * - * @since 4.6.0 + * The definition of the RtcStats struct. */ -struct WatermarkConfig { +struct RtcStats { /** - * Unique identifier for the watermark. It is recommended to use a UUID. + * The call duration (s), represented by an aggregate value. */ - const char* id; + unsigned int duration; /** - * Type of the watermark. See `WATERMARK_SOURCE_TYPE`. - */ - WATERMARK_SOURCE_TYPE type; - union { - /** - * Buffer of the watermark. See `WatermarkBuffer`. - */ - WatermarkBuffer buffer; - /** - * The watermark timestamp. See WatermarkTimestamp. - * - * @note This is only supported in linux platform. - */ - WatermarkTimestamp timestamp; - /** - * The watermark literal. See WatermarkLiteral. - * - * @note This is only supported in linux platform. - */ - WatermarkLiteral literal; - /** - * URL of the watermark image file. Default value is NULL. - */ - const char* imageUrl; - }; - - /** - * Options for the watermark. See `WatermarkOptions`. - */ - WatermarkOptions options; - - WatermarkConfig() : id(NULL), type(IMAGE), imageUrl(NULL) {} -}; - -/** - * @brief The transmission mode of data over multiple network paths. - * - * @since 4.6.0 - */ -enum MultipathMode { - /** - * Duplicate mode, the same piece of data is redundantly transmitted over all available paths. - * @technical preview - */ - Duplicate= 0, - /** - * (1): Dynamic transmission mode. The SDK dynamically selects the optimal path for data - * transmission based on the current network conditions to improve transmission performance. - */ - Dynamic -}; - -/** - * @brief Network path types used in multipath transmission. - * - * @since 4.6.0 - */ -enum MultipathType { - /** - * (0): Local Area Network (LAN) path. - */ - LAN = 0, - /** - * (1): Wi-Fi path. - */ - WIFI, - /** - * (2): Mobile network path. - */ - Mobile, - /** - * (99): Unknown or unspecified network path. - */ - Unknown = 99 -}; - -/** - * @brief Statistical information about a specific network path. - * - * @since 4.6.0 - */ -struct PathStats { - /** - * Types of network path. See `MultipathType`. - */ - MultipathType type; - /** - * The transmission bitrate of the path in Kbps. - */ - int txKBitRate; - /** - * The receiving bitrate of the path in Kbps. - */ - int rxKBitRate; - PathStats() : type(Unknown), txKBitRate(0), rxKBitRate(0) {} - PathStats(MultipathType t, int tx, int rx) : type(t), txKBitRate(tx), rxKBitRate(rx) {} -}; - -/** - * @brief Aggregates statistics of each network path in multipath transmission. - * - * @since 4.6.0 - */ -struct MultipathStats { - /** - * The total number of bytes sent over the LAN path. - */ - uint32_t lanTxBytes; - /** - * The total number of bytes received over the LAN path. - */ - uint32_t lanRxBytes; - /** - * The total number of bytes sent over the Wi-Fi path. - */ - uint32_t wifiTxBytes; - /** - * The total number of bytes received over the Wi-Fi path. - */ - uint32_t wifiRxBytes; - /** - * The total number of bytes sent over the mobile network path. - */ - uint32_t mobileTxBytes; - /** - * The total number of bytes received over the mobile network path. - */ - uint32_t mobileRxBytes; - /** - * The number of active transmission paths. - */ - int activePathNum; - /** - * An array of statistics for each active transmission path. See `PathStats`. - */ - const PathStats* pathStats; - MultipathStats() - : lanTxBytes(0), - lanRxBytes(0), - wifiTxBytes(0), - wifiRxBytes(0), - mobileTxBytes(0), - mobileRxBytes(0), - activePathNum(0), - pathStats(nullptr) {} -}; - -/** - * @brief Statistics of a call session. - */ -struct RtcStats { - /** - * Call duration of the local user in seconds, represented by an aggregate value. - */ - unsigned int duration; - /** - * The number of bytes sent. + * The total number of bytes transmitted, represented by an aggregate value. */ unsigned int txBytes; /** - * The number of bytes received. + * The total number of bytes received, represented by an aggregate value. */ unsigned int rxBytes; /** - * The total number of audio bytes sent, represented by an aggregate value. + * The total number of audio bytes sent (bytes), represented by an aggregate value. */ unsigned int txAudioBytes; /** - * The total number of video bytes sent, represented by an aggregate value. + * The total number of video bytes sent (bytes), represented by an aggregate value. */ unsigned int txVideoBytes; /** - * The total number of audio bytes received, represented by an aggregate value. + * The total number of audio bytes received (bytes), represented by an aggregate value. */ unsigned int rxAudioBytes; /** - * The total number of video bytes received, represented by an aggregate value. + * The total number of video bytes received (bytes), represented by an aggregate value. */ unsigned int rxVideoBytes; /** - * The actual bitrate (Kbps) while sending the local video stream. + * The transmission bitrate (Kbps), represented by an instantaneous value. */ unsigned short txKBitRate; /** - * The receiving bitrate (Kbps). + * The receiving bitrate (Kbps), represented by an instantaneous value. */ unsigned short rxKBitRate; /** - * The bitrate (Kbps) of receiving the audio. + * Audio receiving bitrate (Kbps), represented by an instantaneous value. */ unsigned short rxAudioKBitRate; /** - * The bitrate (Kbps) of sending the audio packet. + * The audio transmission bitrate (Kbps), represented by an instantaneous value. */ unsigned short txAudioKBitRate; /** - * The bitrate (Kbps) of receiving the video. + * The video receive bitrate (Kbps), represented by an instantaneous value. */ unsigned short rxVideoKBitRate; /** - * The bitrate (Kbps) of sending the video. + * The video transmission bitrate (Kbps), represented by an instantaneous value. */ unsigned short txVideoKBitRate; /** - * The client-to-server delay (milliseconds). + * The VOS client-server latency (ms). */ unsigned short lastmileDelay; /** @@ -2801,49 +2487,49 @@ struct RtcStats { */ unsigned int userCount; /** - * Application CPU usage (%). + * The app CPU usage (%). * @note * - The value of `cpuAppUsage` is always reported as 0 in the `onLeaveChannel` callback. - * - As of Android 8.1, you cannot get the CPU usage from this attribute due to system limitations. + * - As of Android 8.1, you cannot get the CPU usage from this attribute due to system + * limitations. */ double cpuAppUsage; /** * The system CPU usage (%). + * * For Windows, in the multi-kernel environment, this member represents the average CPU usage. The * value = (100 - System Idle Progress in Task Manager)/100. * @note * - The value of `cpuTotalUsage` is always reported as 0 in the `onLeaveChannel` callback. - * - As of Android 8.1, you cannot get the CPU usage from this attribute due to system limitations. + * - 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 (ms) from the client to the local router. - * @note - * This property 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, `technical support`. - * On Android, to get `gatewayRtt`, ensure that you add the `android.permission.ACCESS_WIFI_STATE` - * permission after `` in the `AndroidManifest.xml` file in your project. + * The round-trip time delay from the client to the local router. + * @note On Android, to get `gatewayRtt`, ensure that you add the + * `android.permission.ACCESS_WIFI_STATE` permission after `` in the + * `AndroidManifest.xml` file in your project. */ int gatewayRtt; /** - * The memory ratio occupied by the app (%). + * The memory usage ratio of the app (%). * @note This value is for reference only. Due to system limitations, you may not get this value. */ double memoryAppUsageRatio; /** - * The memory occupied by the system (%). + * The memory usage ratio of the system (%). * @note This value is for reference only. Due to system limitations, you may not get this value. */ double memoryTotalUsageRatio; /** - * The memory size occupied by the app (KB). + * The memory usage of the app (KB). * @note This value is for reference only. Due to system limitations, you may not get this value. */ int memoryAppUsageInKbytes; /** - * The duration (ms) between the SDK starts connecting and the connection is established. If the - * value reported is 0, it means invalid. + * The time elapsed from the when the app starts connecting to an Agora channel + * to when the connection is established. 0 indicates that this member does not apply. */ int connectTimeMs; /** @@ -2892,22 +2578,13 @@ struct RtcStats { */ int firstVideoKeyFrameRenderedDurationAfterUnmute; /** - * The packet loss rate (%) from the client to the Agora server before applying the anti-packet-loss - * algorithm. + * The packet loss rate of sender(broadcaster). */ int txPacketLossRate; /** - * The packet loss rate (%) from the Agora server to the client before using the anti-packet-loss - * method. + * The packet loss rate of receiver(audience). */ int rxPacketLossRate; - /** - * The local network acceleration state. - * A value of 1 indicates that local network acceleration is active, while 0 indicates it is inactive. - * @technical preview - */ - int lanAccelerateState; - RtcStats() : duration(0), txBytes(0), @@ -2941,46 +2618,45 @@ struct RtcStats { firstVideoKeyFrameDecodedDurationAfterUnmute(0), firstVideoKeyFrameRenderedDurationAfterUnmute(0), txPacketLossRate(0), - rxPacketLossRate(0), - lanAccelerateState(0) {} + rxPacketLossRate(0) {} }; /** - * @brief The user role in the interactive live streaming. + * User role types. */ enum CLIENT_ROLE_TYPE { /** - * 1: Host. A host can both send and receive streams. + * 1: Broadcaster. A broadcaster can both send and receive streams. */ CLIENT_ROLE_BROADCASTER = 1, /** - * 2: (Default) Audience. An audience member can only receive streams. + * 2: Audience. An audience member can only receive streams. */ CLIENT_ROLE_AUDIENCE = 2, }; /** - * @brief Quality change of the local video in terms of target frame rate and target bit rate since - * last count. + * Quality change of the local video in terms of target frame rate and target bit rate since last + * count. */ enum QUALITY_ADAPT_INDICATION { /** - * 0: The local video quality stays the same. + * 0: The quality of the local video stays the same. */ ADAPT_NONE = 0, /** - * 1: The local video quality improves because the network bandwidth increases. + * 1: The quality improves because the network bandwidth increases. */ ADAPT_UP_BANDWIDTH = 1, /** - * 2: The local video quality deteriorates because the network bandwidth decreases. + * 2: The quality worsens because the network bandwidth decreases. */ ADAPT_DOWN_BANDWIDTH = 2, }; /** - * @brief The latency level of an audience member in interactive live streaming. This enum takes - * effect only when the user role is set to CLIENT_ROLE_AUDIENCE . + * The latency level of an audience member in interactive live streaming. This enum takes effect + * only when the user role is set to `CLIENT_ROLE_AUDIENCE`. */ enum AUDIENCE_LATENCY_LEVEL_TYPE { /** @@ -2988,13 +2664,13 @@ enum AUDIENCE_LATENCY_LEVEL_TYPE { */ AUDIENCE_LATENCY_LEVEL_LOW_LATENCY = 1, /** - * 2: (Default) Ultra low latency. + * 2: Ultra low latency. */ AUDIENCE_LATENCY_LEVEL_ULTRA_LOW_LATENCY = 2, }; /** - * @brief Setting of user role properties. + * The detailed options of a user. */ struct ClientRoleOptions { /** @@ -3007,25 +2683,21 @@ struct ClientRoleOptions { }; /** - * @brief The Quality of Experience (QoE) of the local user when receiving a remote audio stream. + * Quality of experience (QoE) of the local user when receiving a remote audio stream. */ enum EXPERIENCE_QUALITY_TYPE { - /** - * 0: The QoE of the local user is good. - */ + /** 0: QoE of the local user is good. */ EXPERIENCE_QUALITY_GOOD = 0, - /** - * 1: The QoE of the local user is poor. - */ + /** 1: QoE of the local user is poor. */ EXPERIENCE_QUALITY_BAD = 1, }; /** - * @brief Reasons why the QoE of the local user when receiving a remote audio stream is poor. + * Reasons why the QoE of the local user when receiving a remote audio stream is poor. */ enum EXPERIENCE_POOR_REASON { /** - * 0: No reason, indicating a good QoE of the local user. + * 0: No reason, indicating good QoE of the local user. */ EXPERIENCE_REASON_NONE = 0, /** @@ -3041,47 +2713,42 @@ enum EXPERIENCE_POOR_REASON { */ WIRELESS_SIGNAL_POOR = 4, /** - * 8: The local user enables both Wi-Fi and bluetooth, and their signals interfere with each other. - * As a result, audio transmission quality is undermined. + * 8: The local user enables both Wi-Fi and bluetooth, and their signals interfere with each + * other. As a result, audio transmission quality is undermined. */ WIFI_BLUETOOTH_COEXIST = 8, }; /** - * @brief AI noise suppression modes. + * Audio AINS mode */ enum AUDIO_AINS_MODE { /** - * 0: (Default) Balance mode. This mode allows for a balanced performance on noice suppression and - * time delay. + * AINS mode with soft suppression level. */ AINS_MODE_BALANCED = 0, /** - * 1: Aggressive mode. In scenarios where high performance on noise suppression is required, such as - * live streaming outdoor events, this mode reduces nosie more dramatically, but may sometimes - * affect the original character of the audio. + * AINS mode with high suppression level. */ AINS_MODE_AGGRESSIVE = 1, /** - * 2: Aggressive mode with low latency. The noise suppression delay of this mode is about only half - * of that of the balance and aggressive modes. It is suitable for scenarios that have high - * requirements on noise suppression with low latency, such as sing together online in real time. + * AINS mode with high suppression level and ultra-low-latency */ AINS_MODE_ULTRALOWLATENCY = 2 }; /** - * @brief The audio profile. + * Audio profile types. */ enum AUDIO_PROFILE_TYPE { /** * 0: The default audio profile. - * - For the interactive streaming profile: A sample rate of 48 kHz, music encoding, mono, and a - * bitrate of up to 64 Kbps. - * - For the communication profile: + * - 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. + * Kbps. of up to 16 Kbps. + * - For the Live-broadcast profile: A sample rate of 48 kHz, music encoding, mono, and a bitrate + * of up to 64 Kbps. */ AUDIO_PROFILE_DEFAULT = 0, /** @@ -3093,9 +2760,10 @@ enum AUDIO_PROFILE_TYPE { */ AUDIO_PROFILE_MUSIC_STANDARD = 2, /** - * 3: A sample rate of 48 kHz, music encoding, stereo, and a bitrate of up to 80 Kbps. To implement - * stereo audio, you also need to call `setAdvancedAudioOptions` and set `audioProcessingChannels` - * to `AUDIO_PROCESSING_STEREO` in `AdvancedAudioOptions`. + * 3: A sample rate of 48 kHz, music encoding, stereo, and a bitrate of up to 80 Kbps. + * + * To implement stereo audio, you also need to call `setAdvancedAudioOptions` and set + * `audioProcessingChannels` to `AUDIO_PROCESSING_STEREO` in `AdvancedAudioOptions`. */ AUDIO_PROFILE_MUSIC_STANDARD_STEREO = 3, /** @@ -3103,37 +2771,38 @@ enum AUDIO_PROFILE_TYPE { */ AUDIO_PROFILE_MUSIC_HIGH_QUALITY = 4, /** - * 5: A sample rate of 48 kHz, music encoding, stereo, and a bitrate of up to 128 Kbps. To implement - * stereo audio, you also need to call `setAdvancedAudioOptions` and set `audioProcessingChannels` - * to `AUDIO_PROCESSING_STEREO` in `AdvancedAudioOptions`. + * 5: A sample rate of 48 kHz, music encoding, stereo, and a bitrate of up to 128 Kbps. + * + * To implement stereo audio, you also need to call `setAdvancedAudioOptions` and set + * `audioProcessingChannels` to `AUDIO_PROCESSING_STEREO` in `AdvancedAudioOptions`. */ AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO = 5, /** - * 6: A sample rate of 16 kHz, audio encoding, mono, and Acoustic Echo Cancellation (AEC) enabled. + * 6: A sample rate of 16 kHz, audio encoding, mono, and Acoustic Echo Cancellation (AES) enabled. */ AUDIO_PROFILE_IOT = 6, - /** - * Enumerator boundary. - */ AUDIO_PROFILE_NUM = 7 }; /** - * @brief The audio scenarios. + * The audio scenario. */ enum AUDIO_SCENARIO_TYPE { /** - * 0: (Default) Automatic scenario match, where the SDK chooses the appropriate audio quality - * according to the user role and audio route. + * 0: Automatic scenario, where the SDK chooses the appropriate audio quality according to the + * user role and audio route. */ AUDIO_SCENARIO_DEFAULT = 0, /** - * 3: High-quality audio scenario, where users mainly play music. For example, instrument tutoring. + * 3: (Recommended) The live gaming scenario, which needs to enable gaming + * audio effects in the speaker. Choose this scenario to achieve high-fidelity + * music playback. */ AUDIO_SCENARIO_GAME_STREAMING = 3, /** - * 5: Chatroom scenario, where users need to frequently switch the user role or mute and unmute the - * microphone. For example, education scenarios. + * 5: The chatroom scenario, which needs to keep recording when setClientRole to audience. + * Normally, app developer can also use mute api to achieve the same result, + * and we implement this 'non-orthogonal' behavior only to make API backward compatible. */ AUDIO_SCENARIO_CHATROOM = 5, /** @@ -3142,27 +2811,26 @@ enum AUDIO_SCENARIO_TYPE { */ AUDIO_SCENARIO_CHORUS = 7, /** - * 8: Meeting scenario that mainly contains the human voice. + * 8: Meeting */ AUDIO_SCENARIO_MEETING = 8, /** * 9: AI Server. - * @technical preview + * @technical preview */ AUDIO_SCENARIO_AI_SERVER = 9, /** - * 10: AI conversation scenario, which is only applicable to scenarios where the user interacts with - * the conversational AI agent created by `Conversational AI Engine`. + * 10: AI Client. */ AUDIO_SCENARIO_AI_CLIENT = 10, /** - * The number of enumerations. + * 11: The number of enumerations. */ AUDIO_SCENARIO_NUM = 11, }; /** - * @brief The format of the video frame. + * The format of the video frame. */ struct VideoFormat { OPTIONAL_ENUM_SIZE_T{ @@ -3175,15 +2843,15 @@ struct VideoFormat { }; /** - * The width (px) of the video frame. The default value is 960. + * The width (px) of the video. */ int width; // Number of pixels. /** - * The height (px) of the video frame. The default value is 540. + * The height (px) of the video. */ int height; // Number of pixels. /** - * The video frame rate (fps). The default value is 15. + * The video frame rate (fps). */ int fps; VideoFormat() : width(FRAME_WIDTH_960), height(FRAME_HEIGHT_540), fps(FRAME_RATE_FPS_15) {} @@ -3205,114 +2873,73 @@ struct VideoFormat { }; /** - * @brief The content hint for screen sharing. + * Video content hints. */ enum VIDEO_CONTENT_HINT { /** - * (Default) No content hint. + * (Default) No content hint. In this case, the SDK balances smoothness with sharpness. */ CONTENT_HINT_NONE, /** - * Motion-intensive content. Choose this option if you prefer smoothness or when you are sharing a - * video clip, movie, or video game. + * Choose this option if you prefer smoothness or when + * you are sharing motion-intensive content such as a video clip, movie, or video game. + * + * */ CONTENT_HINT_MOTION, /** - * Motionless content. Choose this option if you prefer sharpness or when you are sharing a picture, - * PowerPoint slides, or texts. + * Choose this option if you prefer sharpness or when you are + * sharing montionless content such as a picture, PowerPoint slide, ot text. + * */ CONTENT_HINT_DETAILS }; /** - * @brief The screen sharing scenario. + * The screen sharing scenario. */ enum SCREEN_SCENARIO_TYPE { /** - * 1: (Default) Document. This scenario prioritizes the video quality of screen sharing and reduces - * the latency of the shared video for the receiver. If you share documents, slides, and tables, you - * can set this scenario. + * 1: Document. This scenario prioritizes the video quality of screen sharing and reduces the + * latency of the shared video for the receiver. If you share documents, slides, and tables, + * you can set this scenario. */ SCREEN_SCENARIO_DOCUMENT = 1, /** - * 2: Game. This scenario prioritizes the smoothness of screen sharing. If you share games, you can - * set this scenario. + * 2: Game. This scenario prioritizes the smoothness of screen sharing. If you share games, you + * can set this scenario. */ SCREEN_SCENARIO_GAMING = 2, /** - * 3: Video. This scenario prioritizes the smoothness of screen sharing. If you share movies or live - * videos, you can set this scenario. + * 3: Video. This scenario prioritizes the smoothness of screen sharing. If you share movies or + * live videos, you can set this scenario. */ SCREEN_SCENARIO_VIDEO = 3, /** - * 4: Remote control. This scenario prioritizes the video quality of screen sharing and reduces the - * latency of the shared video for the receiver. If you share the device desktop being remotely - * controlled, you can set this scenario. + * 4: Remote control. This scenario prioritizes the video quality of screen sharing and reduces + * the latency of the shared video for the receiver. If you share the device desktop being + * remotely controlled, you can set this scenario. */ SCREEN_SCENARIO_RDC = 4, }; /** - * @brief The video application scenarios. + * The video application scenario type. */ enum VIDEO_APPLICATION_SCENARIO_TYPE { /** - * 0: (Default) The general scenario. + * 0: Default Scenario. */ APPLICATION_SCENARIO_GENERAL = 0, /** - * 1: The meeting scenario. - * `APPLICATION_SCENARIO_MEETING` (1) is suitable for meeting scenarios. The SDK automatically - * enables the following strategies: - * - In meeting scenarios where low-quality video streams are required to have a high bitrate, the - * SDK automatically enables multiple technologies used to deal with network congestions, to enhance - * the performance of the low-quality streams and to ensure the smooth reception by subscribers. - * - The SDK monitors the number of subscribers to the high-quality video stream in real time and - * dynamically adjusts its configuration based on the number of subscribers. - * - If nobody subscribers to the high-quality stream, the SDK automatically reduces its bitrate - * and frame rate to save upstream bandwidth. - * - If someone subscribes to the high-quality stream, the SDK resets the high-quality stream to - * the `VideoEncoderConfiguration` configuration used in the most recent calling of - * `setVideoEncoderConfiguration`. If no configuration has been set by the user previously, the - * following values are used: - * - Resolution: (Windows and macOS) 1280 × 720; (Android and iOS) 960 × 540 - * - Frame rate: 15 fps - * - Bitrate: (Windows and macOS) 1600 Kbps; (Android and iOS) 1000 Kbps - * - The SDK monitors the number of subscribers to the low-quality video stream in real time and - * dynamically enables or disables it based on the number of subscribers. - * - If nobody subscribes to the low-quality stream, the SDK automatically disables it to save - * upstream bandwidth. - * - If someone subscribes to the low-quality stream, the SDK enables the low-quality stream and - * resets it to the `SimulcastStreamConfig` configuration used in the most recent calling of - * `setDualStreamMode(SIMULCAST_STREAM_MODE mode, const SimulcastStreamConfig& streamConfig)`. If no - * configuration has been set by the user previously, the following - * values are used: - * - Resolution: 480 × 272 - * - Frame rate: 15 fps - * - Bitrate: 500 Kbps - * @note If the user has called `setDualStreamMode(SIMULCAST_STREAM_MODE mode, const - * SimulcastStreamConfig& streamConfig)` to set that never send low-quality video - * stream ( `DISABLE_SIMULCAST_STREAM` ), the dynamic adjustment of the low-quality stream in - * meeting scenarios will not take effect. + * 1: Meeting Scenario. This scenario is the best QoE practice of meeting application. */ APPLICATION_SCENARIO_MEETING = 1, /** - * 2: 1v1 video call scenario. - * `APPLICATION_SCENARIO_1V1` (2) This is applicable to the `one to one live` scenario. To meet the - * requirements for low latency and high-quality video in this scenario, the SDK optimizes its - * strategies, improving performance in terms of video quality, first frame rendering, latency on - * mid-to-low-end devices, and smoothness under weak network conditions. - * @note This enumeration value is only applicable to the broadcaster vs. broadcaster scenario. + * 2: Video Call Scenario. This scenario is used to optimize the video experience in video application, like 1v1 video call. */ APPLICATION_SCENARIO_1V1 = 2, /** - * 3. Live show scenario. - * `APPLICATION_SCENARIO_LIVESHOW` (3) This is applicable to the `show room` scenario. In this - * scenario, fast video rendering and high image quality are crucial. The SDK implements several - * performance optimizations, including automatically enabling accelerated audio and video frame - * rendering to minimize first-frame latency (no need to call `enableInstantMediaRendering` ), and - * B-frame encoding to achieve better image quality and bandwidth efficiency. The SDK also provides - * enhanced video quality and smooth playback, even in poor network conditions or on lower-end - * devices. + * 3: Live Show Scenario. This scenario is used to optimize the video experience in video live show. */ APPLICATION_SCENARIO_LIVESHOW = 3, }; @@ -3341,57 +2968,39 @@ enum VIDEO_QOE_PREFERENCE_TYPE { }; /** - * @brief The brightness level of the video image captured by the local camera. + * The brightness level of the video image captured by the local camera. */ enum CAPTURE_BRIGHTNESS_LEVEL_TYPE { - /** - * -1: The SDK does not detect the brightness level of the video image. Wait a few seconds to get - * the brightness level from `captureBrightnessLevel` in the next callback. + /** -1: The SDK does not detect the brightness level of the video image. + * Wait a few seconds to get the brightness level from `CAPTURE_BRIGHTNESS_LEVEL_TYPE` in the next + * callback. */ CAPTURE_BRIGHTNESS_LEVEL_INVALID = -1, - /** - * 0: The brightness level of the video image is normal. + /** 0: The brightness level of the video image is normal. */ CAPTURE_BRIGHTNESS_LEVEL_NORMAL = 0, - /** - * 1: The brightness level of the video image is too bright. + /** 1: The brightness level of the video image is too bright. */ CAPTURE_BRIGHTNESS_LEVEL_BRIGHT = 1, - /** - * 2: The brightness level of the video image is too dark. + /** 2: The brightness level of the video image is too dark. */ CAPTURE_BRIGHTNESS_LEVEL_DARK = 2, }; -/** - * @brief Camera stabilization modes. - * - * @details - * The camera stabilization effect increases in the order of 1 < 2 < 3, and the latency will also - * increase accordingly. - * - */ enum CAMERA_STABILIZATION_MODE { - /** - * -1: (Default) Camera stabilization mode off. + /** The camera stabilization mode is disabled. */ CAMERA_STABILIZATION_MODE_OFF = -1, - /** - * 0: Automatic camera stabilization. The system automatically selects a stabilization mode based on - * the status of the camera. However, the latency is relatively high in this mode, so it is - * recommended not to use this enumeration. + /** device choose stabilization mode automatically. */ CAMERA_STABILIZATION_MODE_AUTO = 0, - /** - * 1: (Recommended) Level 1 camera stabilization. + /** stabilization mode level 1. */ CAMERA_STABILIZATION_MODE_LEVEL_1 = 1, - /** - * 2: Level 2 camera stabilization. + /** stabilization mode level 2. */ CAMERA_STABILIZATION_MODE_LEVEL_2 = 2, - /** - * 3: Level 3 camera stabilization. + /** stabilization mode level 3. */ CAMERA_STABILIZATION_MODE_LEVEL_3 = 3, /** The maximum level of the camera stabilization mode. @@ -3400,7 +3009,7 @@ enum CAMERA_STABILIZATION_MODE { }; /** - * @brief The state of the local audio. + * Local audio states. */ enum LOCAL_AUDIO_STREAM_STATE { /** @@ -3408,7 +3017,7 @@ enum LOCAL_AUDIO_STREAM_STATE { */ LOCAL_AUDIO_STREAM_STATE_STOPPED = 0, /** - * 1: The local audio capturing device starts successfully. + * 1: The capturing device starts successfully. */ LOCAL_AUDIO_STREAM_STATE_RECORDING = 1, /** @@ -3422,7 +3031,7 @@ enum LOCAL_AUDIO_STREAM_STATE { }; /** - * @brief Reasons for local audio state changes. + * Local audio state error codes. */ enum LOCAL_AUDIO_STREAM_REASON { /** @@ -3435,56 +3044,43 @@ enum LOCAL_AUDIO_STREAM_REASON { */ LOCAL_AUDIO_STREAM_REASON_FAILURE = 1, /** - * 2: No permission to use the local audio capturing device. Remind your users to grant permission. + * 2: No permission to use the local audio device. Remind your users to grant permission. */ LOCAL_AUDIO_STREAM_REASON_DEVICE_NO_PERMISSION = 2, /** - * 3: (Android and iOS only) The local audio capture device is already in use. Remind your users to - * check whether another application occupies the microphone. Local audio capture automatically - * resumes after the microphone is idle for about five seconds. You can also try to rejoin the - * channel after the microphone is idle. + * 3: (Android and iOS only) The local audio capture device is used. Remind your users to check + * whether another application occupies the microphone. Local audio capture automatically resume + * after the microphone is idle for about five seconds. You can also try to rejoin the channel + * after the microphone is idle. */ LOCAL_AUDIO_STREAM_REASON_DEVICE_BUSY = 3, /** - * 4: The local audio capture fails. + * 4: The local audio capture failed. */ LOCAL_AUDIO_STREAM_REASON_RECORD_FAILURE = 4, /** - * 5: The local audio encoding fails. + * 5: The local audio encoding failed. */ LOCAL_AUDIO_STREAM_REASON_ENCODE_FAILURE = 5, - /** - * 6: (Windows and macOS only) No local audio capture device. Remind your users to check whether the - * microphone is connected to the device properly in the control panel of the device or if the - * microphone is working properly. + /** 6: The SDK cannot find the local audio recording device. */ LOCAL_AUDIO_STREAM_REASON_NO_RECORDING_DEVICE = 6, - /** - * 7: (Windows and macOS only) No local audio capture device. Remind your users to check whether the - * speaker is connected to the device properly in the control panel of the device or if the speaker - * is working properly. + /** 7: The SDK cannot find the local audio playback device. */ LOCAL_AUDIO_STREAM_REASON_NO_PLAYOUT_DEVICE = 7, /** - * 8: (Android and iOS only) The local audio capture is interrupted by a system call, smart - * assistants, or alarm clock. Prompt your users to end the phone call, smart assistants, or alarm - * clock if the local audio capture is required. + * 8: The local audio capturing is interrupted by the system call. */ LOCAL_AUDIO_STREAM_REASON_INTERRUPTED = 8, - /** - * 9: (Windows only) The ID of the local audio-capture device is invalid. Prompt the user to check - * the audio capture device ID. + /** 9: An invalid audio capture device ID. */ LOCAL_AUDIO_STREAM_REASON_RECORD_INVALID_ID = 9, - /** - * 10: (Windows only) The ID of the local audio-playback device is invalid. Prompt the user to check - * the audio playback device ID. + /** 10: An invalid audio playback device ID. */ LOCAL_AUDIO_STREAM_REASON_PLAYOUT_INVALID_ID = 10, }; -/** - * @brief Local video state types. +/** Local video state types. */ enum LOCAL_VIDEO_STREAM_STATE { /** @@ -3492,8 +3088,8 @@ enum LOCAL_VIDEO_STREAM_STATE { */ LOCAL_VIDEO_STREAM_STATE_STOPPED = 0, /** - * 1: The local video capturing device starts successfully. The SDK also reports this state when you - * call `startScreenCaptureByWindowId` to share a maximized window. + * 1: The local video capturing device starts successfully. The SDK also reports this state when + * you call `startScreenCaptureByWindowId` to share a maximized window. */ LOCAL_VIDEO_STREAM_STATE_CAPTURING = 1, /** @@ -3530,7 +3126,7 @@ enum LOCAL_VIDEO_EVENT_TYPE { }; /** - * @brief Reasons for local video state changes. + * Local video state error codes. */ enum LOCAL_VIDEO_STREAM_REASON { /** @@ -3542,34 +3138,35 @@ enum LOCAL_VIDEO_STREAM_REASON { */ LOCAL_VIDEO_STREAM_REASON_FAILURE = 1, /** - * 2: No permission to use the local video capturing device. Prompt the user to grant permissions + * 2: No permission to use the local video capturing device. Remind the user to grant permission * and rejoin the channel. */ LOCAL_VIDEO_STREAM_REASON_DEVICE_NO_PERMISSION = 2, /** - * 3: The local video capturing device is in use. Prompt the user to check if the camera is being - * used by another app, or try to rejoin the channel. + * 3: The local video capturing device is in use. Remind the user to check whether another + * application occupies the camera. */ LOCAL_VIDEO_STREAM_REASON_DEVICE_BUSY = 3, /** - * 4: The local video capture fails. Prompt the user to check whether the video capture device is - * working properly, whether the camera is used by another app, or try to rejoin the channel. + * 4: The local video capture fails. Remind the user to check whether the video capture device + * is working properly or the camera is occupied by another application, and then to rejoin the + * channel. */ LOCAL_VIDEO_STREAM_REASON_CAPTURE_FAILURE = 4, /** - * 5: The local video encoding fails. + * 5: The local video encoder is not supported. */ LOCAL_VIDEO_STREAM_REASON_CODEC_NOT_SUPPORT = 5, /** - * 6: (iOS only) The app is in the background. Prompt the user that video capture cannot be + * 6: (iOS only) The app is in the background. Remind the user that video capture cannot be * performed normally when the app is in the background. */ LOCAL_VIDEO_STREAM_REASON_CAPTURE_INBACKGROUND = 6, /** - * 7: (iOS only) The current app window is running in Slide Over, Split View, or Picture in Picture - * mode, and another app is occupying the camera. Prompt the user that the app cannot capture video - * properly when it is running in Slide Over, Split View, or Picture in Picture mode and another app - * is occupying the camera. + * 7: (iOS only) The current application window is running in Slide Over, Split View, or Picture + * in Picture mode, and another app is occupying the camera. Remind the user that the application + * cannot capture video properly when the app is running in Slide Over, Split View, or Picture in + * Picture mode and another app is occupying the camera. */ LOCAL_VIDEO_STREAM_REASON_CAPTURE_MULTIPLE_FOREGROUND_APPS = 7, /** @@ -3579,28 +3176,23 @@ enum LOCAL_VIDEO_STREAM_REASON { */ LOCAL_VIDEO_STREAM_REASON_DEVICE_NOT_FOUND = 8, /** - * 9: (macOS and Windows only) The video capture device currently in use is disconnected (such as - * being unplugged). + * 9: (macOS and Windows only) The video capture device currently in use is disconnected (such as being + * unplugged). */ LOCAL_VIDEO_STREAM_REASON_DEVICE_DISCONNECTED = 9, /** - * 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. + * 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. */ LOCAL_VIDEO_STREAM_REASON_DEVICE_INVALID_ID = 10, /** - * 14: (Android only) Video capture is interrupted. Possible reasons include the following: - * - The camera is being used by another app. Prompt the user to check if the camera is being used - * by another app. - * - The current app has been switched to the background. You can use foreground services to notify - * the operating system and ensure that the app can still collect video when it switches to the - * background. + * 14: (Android only) Video capture was interrupted, possibly due to the camera being occupied + * or some policy reasons such as background termination. */ LOCAL_VIDEO_STREAM_REASON_DEVICE_INTERRUPT = 14, /** - * 15: (Android only) The video capture device encounters an error. Prompt the user to close and - * restart the camera to restore functionality. If this operation does not solve the problem, check - * if the camera has a hardware failure. + * 15: (Android only) The device may need to be shut down and restarted to restore camera + * function, or there may be a persistent hardware problem. */ LOCAL_VIDEO_STREAM_REASON_DEVICE_FATAL_ERROR = 15, /** @@ -3608,97 +3200,70 @@ enum LOCAL_VIDEO_STREAM_REASON { */ LOCAL_VIDEO_STREAM_REASON_DEVICE_SYSTEM_PRESSURE = 101, /** - * 11: (macOS and Windows only) The shared window is minimized when you call the - * `startScreenCaptureByWindowId` method to share a window. The SDK cannot share a minimized window. - * Please prompt the user to unminimize the shared window. + * 11: (macOS only) The shared window is minimized when you call `startScreenCaptureByWindowId` + * to share a window. The SDK cannot share a minimized window. You can cancel the minimization + * of this window at the application layer, for example by maximizing this window. */ LOCAL_VIDEO_STREAM_REASON_SCREEN_CAPTURE_WINDOW_MINIMIZED = 11, /** - * 12: (macOS and Windows only) The error code indicates that a window shared by the window ID has - * been closed or a full-screen window shared by the window ID has exited full-screen mode. After - * exiting full-screen mode, remote users cannot see the shared window. To prevent remote users from - * seeing a black screen, Agora recommends that you immediately stop screen sharing. - * Common scenarios reporting this error code: - * - The local user closes the shared window. - * - The local user shows some slides in full-screen mode first, and then shares the windows of the - * slides. After the user exits full-screen mode, the SDK reports this error code. - * - The local user watches a web video or reads a web document in full-screen mode first, and then - * shares the window of the web video or document. After the user exits full-screen mode, the SDK - * reports this error code. + * 12: (macOS and Windows only) The error code indicates that a window shared by the window ID + * has been closed or a full-screen window shared by the window ID has exited full-screen mode. + * After exiting full-screen mode, remote users cannot see the shared window. To prevent remote + * users from seeing a black screen, Agora recommends that you immediately stop screen sharing. + * + * Common scenarios for reporting this error code: + * - When the local user closes the shared window, the SDK reports this error code. + * - The local user shows some slides in full-screen mode first, and then shares the windows of + * the slides. After the user exits full-screen mode, the SDK reports this error code. + * - The local user watches a web video or reads a web document in full-screen mode first, and + * then shares the window of the web video or document. After the user exits full-screen mode, + * the SDK reports this error code. */ LOCAL_VIDEO_STREAM_REASON_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. - */ + /** 13: The local screen capture window is occluded. */ LOCAL_VIDEO_STREAM_REASON_SCREEN_CAPTURE_WINDOW_OCCLUDED = 13, /** 20: The local screen capture window is not supported. */ LOCAL_VIDEO_STREAM_REASON_SCREEN_CAPTURE_WINDOW_NOT_SUPPORTED = 20, - /** - * 21: (Windows and Android only) The currently captured window has no data. - */ + /** 21: The screen capture fails. */ LOCAL_VIDEO_STREAM_REASON_SCREEN_CAPTURE_FAILURE = 21, - /** - * 22: (Windows and macOS only) No permission for screen capture. - */ + /** 22: No permision to capture screen. */ LOCAL_VIDEO_STREAM_REASON_SCREEN_CAPTURE_NO_PERMISSION = 22, /** - * 24: (Windows only) An unexpected error occurred during screen sharing (possibly due to window - * blocking failure), resulting in decreased performance, but the screen sharing process itself was - * not affected. - * @note During screen sharing, if blocking a specific window fails due to device driver issues, the - * SDK will report this event and automatically fall back to sharing the entire screen. If your use - * case requires masking specific windows to protect privacy, we recommend listening for this event - * and implementing additional privacy protection mechanisms when it is triggered. + * 24: (Windows Only) An unexpected error (possibly due to window block failure) occurs during the + * screen sharing process, resulting in performance degradation. However, the screen sharing + * process itself is functioning normally. */ LOCAL_VIDEO_STREAM_REASON_SCREEN_CAPTURE_AUTO_FALLBACK = 24, - /** - * 25: (Windows only) The window for the current screen capture is hidden and not visible on the - * current screen. - */ + /** 25: (Windows only) The local screen capture window is currently hidden and not visible on the + desktop. */ LOCAL_VIDEO_STREAM_REASON_SCREEN_CAPTURE_WINDOW_HIDDEN = 25, - /** - * 26: (Windows only) The window for screen capture has been restored from hidden state. - */ + /** 26: (Windows only) The local screen capture window is recovered from its hidden state. */ LOCAL_VIDEO_STREAM_REASON_SCREEN_CAPTURE_WINDOW_RECOVER_FROM_HIDDEN = 26, - /** - * 27: (macOS and Windows only) The window for screen capture has been restored from the minimized - * state. - */ + /** 27: (Windows and macOS only) The window is recovered from miniminzed */ LOCAL_VIDEO_STREAM_REASON_SCREEN_CAPTURE_WINDOW_RECOVER_FROM_MINIMIZED = 27, /** - * 28: (Windows only) Screen capture has been paused. Common scenarios reporting this error code: - * The current screen may have been switched to a secure desktop, such as a UAC dialog box or - * Winlogon desktop. + * 28: The screen capture paused. + * + * Common scenarios for reporting this error code: + * - When the desktop switch to the secure desktop such as UAC dialog or the Winlogon desktop on + * Windows platform, the SDK reports this error code. */ LOCAL_VIDEO_STREAM_REASON_SCREEN_CAPTURE_PAUSED = 28, - /** - * 29: (Windows only) Screen capture has resumed from paused state. - */ + /** 29: The screen capture is resumed. */ LOCAL_VIDEO_STREAM_REASON_SCREEN_CAPTURE_RESUMED = 29, - /** - * 30: (Windows and macOS only) The displayer used for screen capture is disconnected. The current - * screen sharing has been paused. Prompt the user to restart the screen sharing. - */ + /** 30: The shared display has been disconnected */ LOCAL_VIDEO_STREAM_REASON_SCREEN_CAPTURE_DISPLAY_DISCONNECTED = 30, - /* 30: (HMOS only) ScreenCapture stopped by user */ - LOCAL_VIDEO_STREAM_REASON_SCREEN_CAPTURE_STOPPED_BY_USER = 31, - /* 31: (HMOS only) ScreenCapture interrupted by other screen capture */ - LOCAL_VIDEO_STREAM_REASON_SCREEN_CAPTURE_INTERRUPTED_BY_OTHER = 32, - /* 32: (HMOS only) ScreenCapture stopped by SIM call */ - LOCAL_VIDEO_STREAM_REASON_SCREEN_CAPTURE_STOPPED_BY_CALL = 33, - /** 34: (Windows only) Some windows of the exclude window list failed to be excluded from the screen capture. */ - LOCAL_VIDEO_STREAM_REASON_SCREEN_CAPTURE_EXCLUDE_WINDOW_FAILED = 34, + }; /** - * @brief Remote audio states. + * Remote audio states. */ enum REMOTE_AUDIO_STATE { /** - * 0: The local audio is in the initial state. The SDK reports this state in the case of - * `REMOTE_AUDIO_REASON_LOCAL_MUTED`, `REMOTE_AUDIO_REASON_REMOTE_MUTED` or - * `REMOTE_AUDIO_REASON_REMOTE_OFFLINE`. + * 0: The remote audio is in the default state. The SDK reports this state in the case of + * `REMOTE_AUDIO_REASON_LOCAL_MUTED(3)`, `REMOTE_AUDIO_REASON_REMOTE_MUTED(5)`, or + * `REMOTE_AUDIO_REASON_REMOTE_OFFLINE(7)`. */ REMOTE_AUDIO_STATE_STOPPED = 0, // Default state, audio is started or remote user disabled/muted audio stream @@ -3707,30 +3272,30 @@ enum REMOTE_AUDIO_STATE { */ REMOTE_AUDIO_STATE_STARTING = 1, // The first audio frame packet has been received /** - * 2: The remote audio stream is decoded and plays normally. The SDK reports this state in the case - * of `REMOTE_AUDIO_REASON_NETWORK_RECOVERY`, `REMOTE_AUDIO_REASON_LOCAL_UNMUTED` or - * `REMOTE_AUDIO_REASON_REMOTE_UNMUTED`. + * 2: The remote audio stream is decoded and plays normally. The SDK reports this state in the + * case of `REMOTE_AUDIO_REASON_NETWORK_RECOVERY(2)`, `REMOTE_AUDIO_REASON_LOCAL_UNMUTED(4)`, or + * `REMOTE_AUDIO_REASON_REMOTE_UNMUTED(6)`. */ REMOTE_AUDIO_STATE_DECODING = 2, // The first remote audio frame has been decoded or fronzen state ends /** * 3: The remote audio is frozen. The SDK reports this state in the case of - * `REMOTE_AUDIO_REASON_NETWORK_CONGESTION`. + * `REMOTE_AUDIO_REASON_NETWORK_CONGESTION(1)`. */ REMOTE_AUDIO_STATE_FROZEN = 3, // Remote audio is frozen, probably due to network issue /** * 4: The remote audio fails to start. The SDK reports this state in the case of - * `REMOTE_AUDIO_REASON_INTERNAL`. + * `REMOTE_AUDIO_REASON_INTERNAL(0)`. */ REMOTE_AUDIO_STATE_FAILED = 4, // Remote audio play failed }; /** - * @brief The reason for the remote audio state change. + * Reasons for the remote audio state change. */ enum REMOTE_AUDIO_STATE_REASON { /** - * 0: The SDK reports this reason when the audio state changes. + * 0: The SDK reports this reason when the video state changes. */ REMOTE_AUDIO_REASON_INTERNAL = 0, /** @@ -3742,19 +3307,23 @@ enum REMOTE_AUDIO_STATE_REASON { */ REMOTE_AUDIO_REASON_NETWORK_RECOVERY = 2, /** - * 3: The local user stops receiving the remote audio stream or disables the audio module. + * 3: The local user stops receiving the remote audio stream or + * disables the audio module. */ REMOTE_AUDIO_REASON_LOCAL_MUTED = 3, /** - * 4: The local user resumes receiving the remote audio stream or enables the audio module. + * 4: The local user resumes receiving the remote audio stream or + * enables the audio module. */ REMOTE_AUDIO_REASON_LOCAL_UNMUTED = 4, /** - * 5: The remote user stops sending the audio stream or disables the audio module. + * 5: The remote user stops sending the audio stream or disables the + * audio module. */ REMOTE_AUDIO_REASON_REMOTE_MUTED = 5, /** - * 6: The remote user resumes sending the audio stream or enables the audio module. + * 6: The remote user resumes sending the audio stream or enables the + * audio module. */ REMOTE_AUDIO_REASON_REMOTE_UNMUTED = 6, /** @@ -3772,13 +3341,14 @@ enum REMOTE_AUDIO_STATE_REASON { }; /** - * @brief The state of the remote video stream. + * The state of the remote video. */ enum REMOTE_VIDEO_STATE { /** - * 0: The remote video is in the initial state. The SDK reports this state in the case of - * `REMOTE_VIDEO_STATE_REASON_LOCAL_MUTED`, `REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED`, or - * `REMOTE_VIDEO_STATE_REASON_REMOTE_OFFLINE`. + * 0: The remote video is in the default state. The SDK reports this state in the case of + * `REMOTE_VIDEO_STATE_REASON_LOCAL_MUTED (3)`, `REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED (5)`, + * `REMOTE_VIDEO_STATE_REASON_REMOTE_OFFLINE (7)`, or `REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK + * (8)`. */ REMOTE_VIDEO_STATE_STOPPED = 0, /** @@ -3786,25 +3356,23 @@ enum REMOTE_VIDEO_STATE { */ REMOTE_VIDEO_STATE_STARTING = 1, /** - * 2: The remote video stream is decoded and plays normally. The SDK reports this state in the case - * of `REMOTE_VIDEO_STATE_REASON_NETWORK_RECOVERY`, `REMOTE_VIDEO_STATE_REASON_LOCAL_UNMUTED`, - * `REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED`, or - * `REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK_RECOVERY`. + * 2: The remote video stream is decoded and plays normally. The SDK reports this state in the + * case of `REMOTE_VIDEO_STATE_REASON_NETWORK_RECOVERY (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_DECODING = 2, - /** - * 3: The remote video is frozen. The SDK reports this state in the case of - * `REMOTE_VIDEO_STATE_REASON_NETWORK_CONGESTION` or `REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK`. + /** 3: The remote video is frozen, probably due to + * #REMOTE_VIDEO_STATE_REASON_NETWORK_CONGESTION (1). */ REMOTE_VIDEO_STATE_FROZEN = 3, - /** - * 4: The remote video fails to start. The SDK reports this state in the case of - * `REMOTE_VIDEO_STATE_REASON_INTERNAL`. + /** 4: The remote video fails to start. The SDK reports this state in the case of + * `REMOTE_VIDEO_STATE_REASON_INTERNAL (0)`. */ REMOTE_VIDEO_STATE_FAILED = 4, }; /** - * @brief The reason for the remote video state change. + * The reason for the remote video state change. */ enum REMOTE_VIDEO_STATE_REASON { /** @@ -3816,7 +3384,7 @@ enum REMOTE_VIDEO_STATE_REASON { */ REMOTE_VIDEO_STATE_REASON_NETWORK_CONGESTION = 1, /** - * 2: Network is recovered. + * 2: Network recovery. */ REMOTE_VIDEO_STATE_REASON_NETWORK_RECOVERY = 2, /** @@ -3839,14 +3407,12 @@ enum REMOTE_VIDEO_STATE_REASON { * 7: The remote user leaves the channel. */ REMOTE_VIDEO_STATE_REASON_REMOTE_OFFLINE = 7, - /** - * 8: The remote audio-and-video stream falls back to the audio-only stream due to poor network - * conditions. + /** 8: The remote audio-and-video stream falls back to the audio-only stream + * due to poor network conditions. */ REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK = 8, - /** - * 9: The remote audio-only stream switches back to the audio-and-video stream after the network - * conditions improve. + /** 9: The remote audio-only stream switches back to the audio-and-video + * stream after the network conditions improve. */ REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK_RECOVERY = 9, /** (Internal use only) 10: The remote video stream type change to low stream type @@ -3855,13 +3421,11 @@ enum REMOTE_VIDEO_STATE_REASON { /** (Internal use only) 11: The remote video stream type change to high stream type */ REMOTE_VIDEO_STATE_REASON_VIDEO_STREAM_TYPE_CHANGE_TO_HIGH = 11, - /** - * 12: (iOS only) The remote user's app has switched to the background. + /** (iOS only) 12: The app of the remote user is in background. */ REMOTE_VIDEO_STATE_REASON_SDK_IN_BACKGROUND = 12, - /** - * 13: The local video decoder does not support decoding the remote video stream. + /** 13: The remote video stream is not supported by the decoder */ REMOTE_VIDEO_STATE_REASON_CODEC_NOT_SUPPORT = 13, @@ -3969,22 +3533,19 @@ enum REMOTE_VIDEO_DOWNSCALE_LEVEL { }; /** - * @brief The volume information of users. + * The volume information of users. */ struct AudioVolumeInfo { /** - * The user ID. - * - In the local user's callback, `uid` is 0. - * - In the remote users' callback, `uid` is the user ID of a remote user whose instantaneous volume - * is the highest. + * User ID of the speaker. + * - In the local user's callback, `uid` = 0. + * - In the remote users' callback, `uid` is the user ID of a remote user whose instantaneous + * volume is one of the three highest. */ uid_t uid; /** * The volume of the user. The value ranges between 0 (the lowest volume) and 255 (the highest - * volume). If the local user enables audio capturing and calls `muteLocalAudioStream` and set it as - * `true` to mute, the value of `volume` indicates the volume of locally captured audio signal. If - * the user calls `startAudioMixing(const char* filePath, bool loopback, int cycle, int startPos)`, - * the value of `volume` indicates the volume after audio + * volume). If the user calls `startAudioMixing`, the value of volume is the volume after audio * mixing. */ unsigned int volume; // [0,255] @@ -3995,14 +3556,14 @@ struct AudioVolumeInfo { * @note * - The `vad` parameter does not report the voice activity status of remote users. In a remote * user's callback, the value of `vad` is always 1. - * - To use this parameter, you must set `reportVad` to `true` when calling + * - To use this parameter, you must set `reportVad` to true when calling * `enableAudioVolumeIndication`. */ unsigned int vad; /** - * The voice pitch of the local user. The value ranges between 0.0 and 4000.0. - * @note The `voicePitch` parameter does not report the voice pitch of remote users. In the remote - * users' callback, the value of `voicePitch` is always 0.0. + * The voice pitch (Hz) of the local user. The value ranges between 0.0 and 4000.0. + * @note The `voicePitch` parameter does not report the voice pitch of remote users. In the + * remote users' callback, the value of `voicePitch` is always 0.0. */ double voicePitch; @@ -4010,13 +3571,10 @@ struct AudioVolumeInfo { }; /** - * @brief The audio device information. - * - * @note This class is for Android only. - * + * The audio device information. */ struct DeviceInfo { - /** + /* * Whether the audio device supports ultra-low-latency capture and playback: * - `true`: The device supports ultra-low-latency capture and playback. * - `false`: The device does not support ultra-low-latency capture and playback. @@ -4033,13 +3591,13 @@ class IPacketObserver { public: virtual ~IPacketObserver() {} /** - * @brief Configurations for the `Packet` instance. + * The definition of the Packet struct. */ struct Packet { /** * The buffer address of the sent or received data. - * @note Agora recommends setting `buffer` to a value larger than 2048 bytes. Otherwise, you may - * encounter undefined behaviors (such as crashes). + * @note Agora recommends setting `buffer` to a value larger than 2048 bytes. Otherwise, you + * may encounter undefined behaviors (such as crashes). */ const unsigned char* buffer; /** @@ -4050,70 +3608,62 @@ class IPacketObserver { Packet() : buffer(OPTIONAL_NULLPTR), size(0) {} }; /** - * @brief Occurs when the local user sends an audio packet. - * - * @param packet The sent audio packet, see `Packet`. - * - * @return - * - `true`: The audio packet is sent successfully. - * - `false`: The audio packet is discarded. + * Occurs when the SDK is ready to send the audio packet. + * @param packet The audio packet to be sent: Packet. + * @return Whether to send the audio packet: + * - true: Send the packet. + * - false: Do not send the packet, in which case the audio packet will be discarded. */ virtual bool onSendAudioPacket(Packet& packet) = 0; /** - * @brief Occurs when the local user sends a video packet. - * - * @param packet The sent video packet, see `Packet`. - * - * @return - * - `true`: The video packet is sent successfully. - * - `false`: The video packet is discarded. + * Occurs when the SDK is ready to send the video packet. + * @param packet The video packet to be sent: Packet. + * @return Whether to send the video packet: + * - true: Send the packet. + * - false: Do not send the packet, in which case the audio packet will be discarded. */ virtual bool onSendVideoPacket(Packet& packet) = 0; /** - * @brief Occurs when the local user receives an audio packet. - * - * @param packet The received audio packet, see `Packet`. - * - * @return - * - `true`: The audio packet is received successfully. - * - `false`: The audio packet is discarded. + * Occurs when the audio packet is received. + * @param packet The received audio packet: Packet. + * @return Whether to process the audio packet: + * - true: Process the packet. + * - false: Do not process the packet, in which case the audio packet will be discarded. */ virtual bool onReceiveAudioPacket(Packet& packet) = 0; /** - * @brief Occurs when the local user receives a video packet. - * - * @param packet The received video packet, see `Packet`. - * - * @return - * - `true`: The video packet is received successfully. - * - `false`: The video packet is discarded. + * Occurs when the video packet is received. + * @param packet The received video packet: Packet. + * @return Whether to process the audio packet: + * - true: Process the packet. + * - false: Do not process the packet, in which case the video packet will be discarded. */ virtual bool onReceiveVideoPacket(Packet& packet) = 0; }; /** - * @brief The audio sampling rate of the stream to be pushed to the CDN. + * Audio sample rate types. */ enum AUDIO_SAMPLE_RATE_TYPE { /** - * 32000: 32 kHz + * 32000: 32 KHz. */ AUDIO_SAMPLE_RATE_32000 = 32000, /** - * 44100: 44.1 kHz + * 44100: 44.1 KHz. */ AUDIO_SAMPLE_RATE_44100 = 44100, /** - * 48000: (Default) 48 kHz + * 48000: 48 KHz. */ AUDIO_SAMPLE_RATE_48000 = 48000, }; /** - * @brief The codec type of the output video. + * The codec type of the output video. */ enum VIDEO_CODEC_TYPE_FOR_STREAM { /** - * 1: (Default) H.264. + * 1: H.264. */ VIDEO_CODEC_H264_FOR_STREAM = 1, /** @@ -4123,31 +3673,30 @@ enum VIDEO_CODEC_TYPE_FOR_STREAM { }; /** - * @brief Video codec profile types. + * Video codec profile types. */ enum VIDEO_CODEC_PROFILE_TYPE { /** - * 66: Baseline video codec profile; generally used for video calls on mobile phones. + * 66: Baseline video codec profile. Generally used in video calls on mobile phones. */ VIDEO_CODEC_PROFILE_BASELINE = 66, /** - * 77: Main video codec profile; generally used in mainstream electronics such as MP4 players, + * 77: Main video codec profile. Generally used in mainstream electronics, such as MP4 players, * portable video players, PSP, and iPads. */ VIDEO_CODEC_PROFILE_MAIN = 77, /** - * 100: (Default) High video codec profile; generally used in high-resolution live streaming or - * television. + * 100: High video codec profile. Generally used in high-resolution broadcasts or television. */ VIDEO_CODEC_PROFILE_HIGH = 100, }; /** - * @brief Self-defined audio codec profile. + * Self-defined audio codec profile. */ enum AUDIO_CODEC_PROFILE_TYPE { /** - * 0: (Default) LC-AAC. + * 0: LC-AAC. */ AUDIO_CODEC_PROFILE_LC_AAC = 0, /** @@ -4155,13 +3704,13 @@ enum AUDIO_CODEC_PROFILE_TYPE { */ AUDIO_CODEC_PROFILE_HE_AAC = 1, /** - * 2: HE-AAC v2. + * 2: HE-AAC v2. */ AUDIO_CODEC_PROFILE_HE_AAC_V2 = 2, }; /** - * @brief Local audio statistics. + * Local audio statistics. */ struct LocalAudioStats { /** @@ -4186,7 +3735,7 @@ struct LocalAudioStats { */ unsigned short txPacketLossRate; /** - * The audio device module delay (ms) when playing or recording audio. + * The audio delay of the device, contains record and playout delay */ int audioDeviceDelay; /** @@ -4194,26 +3743,27 @@ struct LocalAudioStats { */ int audioPlayoutDelay; /** - * The ear monitor delay (ms), which is the delay from microphone input to headphone output. + * The signal delay estimated from audio in-ear monitoring (ms). */ int earMonitorDelay; /** - * Acoustic echo cancellation (AEC) module estimated delay (ms), which is the signal delay between - * when audio is played locally before being locally captured. + * The signal delay estimated during the AEC process from nearin and farin (ms). */ int aecEstimatedDelay; }; /** - * @brief States of the Media Push. + * States of the Media Push. */ enum RTMP_STREAM_PUBLISH_STATE { /** - * 0: The Media Push has not started or has ended. + * 0: The Media Push has not started or has ended. This state is also triggered after you remove a + * RTMP or RTMPS stream from the CDN by calling `removePublishStreamUrl`. */ RTMP_STREAM_PUBLISH_STATE_IDLE = 0, /** - * 1: The streaming server and CDN server are being connected. + * 1: The SDK is connecting to Agora's streaming server and the CDN server. This state is + * triggered after you call the `addPublishStreamUrl` method. */ RTMP_STREAM_PUBLISH_STATE_CONNECTING = 1, /** @@ -4222,37 +3772,42 @@ enum RTMP_STREAM_PUBLISH_STATE { */ RTMP_STREAM_PUBLISH_STATE_RUNNING = 2, /** - * 3: The RTMP or RTMPS streaming is recovering. When exceptions occur to the CDN, or the streaming - * is interrupted, the SDK tries to resume RTMP or RTMPS streaming and returns this state. - * - If the SDK successfully resumes the streaming, RTMP_STREAM_PUBLISH_STATE_RUNNING (2) returns. + * 3: The RTMP or RTMPS streaming is recovering. When exceptions occur to the CDN, or the + * streaming is interrupted, the SDK tries to resume RTMP or RTMPS streaming and returns this + * state. + * - If the SDK successfully resumes the streaming, #RTMP_STREAM_PUBLISH_STATE_RUNNING (2) + * returns. * - If the streaming does not resume within 60 seconds or server errors occur, - * RTMP_STREAM_PUBLISH_STATE_FAILURE (4) returns. If you feel that 60 seconds is too long, you can - * also actively try to reconnect. + * #RTMP_STREAM_PUBLISH_STATE_FAILURE (4) returns. You can also reconnect to the server by calling + * the `removePublishStreamUrl` and `addPublishStreamUrl` methods. */ RTMP_STREAM_PUBLISH_STATE_RECOVERING = 3, /** - * 4: The RTMP or RTMPS streaming fails. After a failure, you can troubleshoot the cause of the - * error through the returned error code. + * 4: The RTMP or RTMPS streaming fails. See the `errCode` parameter for the detailed error + * information. You can also call the `addPublishStreamUrl` method to publish the RTMP or RTMPS + * streaming again. */ RTMP_STREAM_PUBLISH_STATE_FAILURE = 4, /** - * 5: The SDK is disconnecting from the Agora streaming server and CDN. When you call - * `stopRtmpStream` to stop the Media Push normally, the SDK reports the Media Push state as - * `RTMP_STREAM_PUBLISH_STATE_DISCONNECTING` and `RTMP_STREAM_PUBLISH_STATE_IDLE` in sequence. + * 5: The SDK is disconnecting to Agora's streaming server and the CDN server. This state is + * triggered after you call the `removePublishStreamUrl` method. */ RTMP_STREAM_PUBLISH_STATE_DISCONNECTING = 5, }; /** - * @brief Reasons for changes in the status of RTMP or RTMPS streaming. + * Error codes of the RTMP or RTMPS streaming. */ enum RTMP_STREAM_PUBLISH_REASON { /** - * 0: The RTMP or RTMPS streaming has not started or has ended. + * 0: The RTMP or RTMPS streaming publishes successfully. */ RTMP_STREAM_PUBLISH_REASON_OK = 0, /** - * 1: Invalid argument used. Check the parameter setting. + * 1: Invalid argument used. If, for example, you do not call the `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_REASON_INVALID_ARGUMENT = 1, /** @@ -4260,11 +3815,13 @@ enum RTMP_STREAM_PUBLISH_REASON { */ RTMP_STREAM_PUBLISH_REASON_ENCRYPTED_STREAM_NOT_ALLOWED = 2, /** - * 3: Timeout for the RTMP or RTMPS streaming. + * 3: Timeout for the RTMP or RTMPS streaming. Call the `addPublishStreamUrl` method to publish + * the streaming again. */ RTMP_STREAM_PUBLISH_REASON_CONNECTION_TIMEOUT = 3, /** - * 4: An error occurs in Agora's streaming server. + * 4: An error occurs in Agora's streaming server. Call the `addPublishStreamUrl` method to + * publish the streaming again. */ RTMP_STREAM_PUBLISH_REASON_INTERNAL_SERVER_ERROR = 4, /** @@ -4280,8 +3837,7 @@ enum RTMP_STREAM_PUBLISH_REASON { */ RTMP_STREAM_PUBLISH_REASON_REACH_LIMIT = 7, /** - * 8: The host manipulates other hosts' URLs. For example, the host updates or stops other hosts' - * streams. Check your app logic. + * 8: The host manipulates other hosts' URLs. Check your app logic. */ RTMP_STREAM_PUBLISH_REASON_NOT_AUTHORIZED = 8, /** @@ -4289,19 +3845,20 @@ enum RTMP_STREAM_PUBLISH_REASON { */ RTMP_STREAM_PUBLISH_REASON_STREAM_NOT_FOUND = 9, /** - * 10: 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_REASON_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. + * 11: The user role is not host, so the user cannot use the CDN live streaming function. Check + * your application code logic. */ RTMP_STREAM_PUBLISH_REASON_NOT_BROADCASTER = 11, // Note: match to ERR_PUBLISH_STREAM_NOT_BROADCASTER in AgoraBase.h /** - * 13: The `updateRtmpTranscoding` method is called to update the transcoding configuration in a - * scenario where there is streaming without transcoding. Check your application code logic. + * 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. */ RTMP_STREAM_PUBLISH_REASON_TRANSCODING_NO_MIX_STREAM = 13, // Note: match to ERR_PUBLISH_STREAM_TRANSCODING_NO_MIX_STREAM in AgoraBase.h @@ -4314,28 +3871,25 @@ enum RTMP_STREAM_PUBLISH_REASON { */ RTMP_STREAM_PUBLISH_REASON_INVALID_APPID = 15, // Note: match to ERR_PUBLISH_STREAM_APPID_INVALID in AgoraBase.h - /** - * 16: Your project does not have permission to use streaming services. - */ + /** invalid privilege. */ RTMP_STREAM_PUBLISH_REASON_INVALID_PRIVILEGE = 16, /** - * 100: The streaming has been stopped normally. After you stop the Media Push, the SDK returns this - * value. + * 100: The streaming has been stopped normally. After you call `removePublishStreamUrl` to stop + * streaming, the SDK returns this value. */ RTMP_STREAM_UNPUBLISH_REASON_OK = 100, }; -/** - * @brief Events during the Media Push. - */ +/** Events during the RTMP or RTMPS streaming. */ enum RTMP_STREAMING_EVENT { /** - * 1: An error occurs when you add a background image or a watermark image in the Media Push. + * 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 Media Push. If you want to start new streaming, - * use a new streaming URL. + * 2: The streaming URL is already being used for CDN live streaming. If you want to start new + * streaming, use a new streaming URL. */ RTMP_STREAMING_EVENT_URL_ALREADY_IN_USE = 2, /** @@ -4343,52 +3897,48 @@ enum RTMP_STREAMING_EVENT { */ RTMP_STREAMING_EVENT_ADVANCED_FEATURE_NOT_SUPPORT = 3, /** - * 4: Reserved. + * 4: Client request too frequently. */ RTMP_STREAMING_EVENT_REQUEST_TOO_OFTEN = 4, }; /** - * @brief Image properties. - * - * @details - * This class sets the properties of the watermark and background images in the live video. - * + * Image properties. */ typedef struct RtcImage { /** - * The HTTP/HTTPS URL address of the image in the live video. The maximum length of this parameter - * is 1024 bytes. + *The HTTP/HTTPS URL address of the image in the live video. The maximum length of this parameter + *is 1024 bytes. */ const char* url; /** - * The x-coordinate (px) of the image on the video frame (taking the upper left corner of the video - * frame as the origin). + * The x coordinate (pixel) of the image on the video frame (taking the upper left corner of the + * video frame as the origin). */ int x; /** - * The y-coordinate (px) of the image on the video frame (taking the upper left corner of the video - * frame as the origin). + * The y coordinate (pixel) of the image on the video frame (taking the upper left corner of the + * video frame as the origin). */ int y; /** - * The width (px) of the image on the video frame. + * The width (pixel) of the image on the video frame. */ int width; /** - * The height (px) of the image on the video frame. + * The height (pixel) of the image on the video frame. */ int height; /** - * The layer index of the watermark or background image. When you use the watermark array to add a - * watermark or multiple watermarks, you must pass a value to `zOrder` in the range [1,255]; - * otherwise, the SDK reports an error. In other cases, `zOrder` can optionally be passed in the + * The layer index of the watermark or background image. When you use the watermark array to add + * a watermark or multiple watermarks, you must pass a value to `zOrder` in the range [1,255]; + * otherwise, the SDK reports an error. In other cases, zOrder can optionally be passed in the * range [0,255], with 0 being the default value. 0 means the bottom layer and 255 means the top * layer. */ int zOrder; - /** - * The transparency of the watermark or background image. The range of the value is [0.0,1.0]: + /** The transparency level of the image. The value ranges between 0.0 and 1.0: + * * - 0.0: Completely transparent. * - 1.0: (Default) Opaque. */ @@ -4397,12 +3947,10 @@ typedef struct RtcImage { RtcImage() : url(OPTIONAL_NULLPTR), x(0), y(0), width(0), height(0), zOrder(0), alpha(1.0) {} } RtcImage; /** - * @brief The configuration for advanced features of the RTMP or RTMPS streaming with transcoding. + * The configuration for advanced features of the RTMP or RTMPS streaming with transcoding. * - * @details * If you want to enable the advanced features of streaming with transcoding, contact - * `support@agora.io`. - * + * support@agora.io. */ struct LiveStreamAdvancedFeature { LiveStreamAdvancedFeature() : featureName(OPTIONAL_NULLPTR), opened(false) {} @@ -4421,66 +3969,63 @@ struct LiveStreamAdvancedFeature { /** * Whether to enable the advanced features of streaming with transcoding: - * - `true`: Enable the advanced features. - * - `false`: (Default) Do not enable the advanced features. + * - `true`: Enable the advanced feature. + * - `false`: (Default) Disable the advanced feature. */ bool opened; }; /** - * @brief Connection states. + * Connection state types. */ enum CONNECTION_STATE_TYPE { /** * 1: The SDK is disconnected from the Agora edge server. The state indicates the SDK is in one of * the following phases: - * - Theinitial state before calling the `joinChannel(const char* token, const char* channelId, - * uid_t uid, const ChannelMediaOptions& options)` method. - * - The app calls the `leaveChannel()` method. + * - The initial state before calling the `joinChannel` method. + * - The app calls the `leaveChannel` method. */ CONNECTION_STATE_DISCONNECTED = 1, /** * 2: The SDK is connecting to the Agora edge server. This state indicates that the SDK is - * establishing a connection with the specified channel after the app calls `joinChannel(const char* - * token, const char* channelId, uid_t uid, const ChannelMediaOptions& options)`. - * - If the SDK successfully joins the channel, it triggers the `onConnectionStateChanged` callback - * and the connection state switches to CONNECTION_STATE_CONNECTED. + * establishing a connection with the specified channel after the app calls `joinChannel`. + * - If the SDK successfully joins the channel, it triggers the `onConnectionStateChanged` + * callback and the connection state switches to `CONNECTION_STATE_CONNECTED`. * - After the connection is established, the SDK also initializes the media and triggers * `onJoinChannelSuccess` when everything is ready. */ CONNECTION_STATE_CONNECTING = 2, /** - * 3: The SDK is connected to the Agora edge server. This state also indicates that the user has - * joined a channel and can now publish or subscribe to a media stream in the channel. If the - * connection to the channel is lost because, for example, if the network is down or switched, the - * SDK automatically tries to reconnect and triggers `onConnectionStateChanged` callback, notifying - * that the current network state becomes CONNECTION_STATE_RECONNECTING. + * 3: The SDK is connected to the Agora edge server. This state also indicates that the user + * has joined a channel and can now publish or subscribe to a media stream in the channel. + * If the connection to the Agora edge server is lost because, for example, the network is down + * or switched, the SDK automatically tries to reconnect and triggers `onConnectionStateChanged` + * that indicates the connection state switches to `CONNECTION_STATE_RECONNECTING`. */ CONNECTION_STATE_CONNECTED = 3, /** - * 4: The SDK keeps reconnecting to the Agora edge server. The SDK keeps rejoining the channel after - * being disconnected from a joined channel because of network issues. - * - If the SDK cannot rejoin the channel within 10 seconds, it triggers `onConnectionLost`, stays - * in the CONNECTION_STATE_RECONNECTING state, and keeps rejoining the channel. - * - If the SDK fails to rejoin the channel 20 minutes after being disconnected from the Agora edge - * server, the SDK triggers the `onConnectionStateChanged` callback, switches to the - * CONNECTION_STATE_FAILED state, and stops rejoining the channel. + * 4: The SDK keeps reconnecting to the Agora edge server. The SDK keeps rejoining the channel + * after being disconnected from a joined channel because of network issues. + * - If the SDK cannot rejoin the channel within 10 seconds, it triggers `onConnectionLost`, + * stays in the `CONNECTION_STATE_RECONNECTING` state, and keeps rejoining the channel. + * - If the SDK fails to rejoin the channel 20 minutes after being disconnected from the Agora + * edge server, the SDK triggers the `onConnectionStateChanged` callback, switches to the + * `CONNECTION_STATE_FAILED` state, and stops rejoining the channel. */ CONNECTION_STATE_RECONNECTING = 4, /** * 5: The SDK fails to connect to the Agora edge server or join the channel. This state indicates - * that the SDK stops trying to rejoin the channel. You must call `leaveChannel()` to leave the + * that the SDK stops trying to rejoin the channel. You must call `leaveChannel` to leave the * channel. - * - You can call `joinChannel(const char* token, const char* channelId, uid_t uid, const - * ChannelMediaOptions& options)` to rejoin the channel. - * - If the SDK is banned from joining the channel by the Agora edge server through the RESTful API, - * the SDK triggers the `onConnectionStateChanged` callback. + * - You can call `joinChannel` to rejoin the channel. + * - If the SDK is banned from joining the channel by the Agora edge server through the RESTful + * API, the SDK triggers the `onConnectionStateChanged` callback. */ CONNECTION_STATE_FAILED = 5, }; /** - * @brief Transcoding configurations of each host. + * Transcoding configurations of each host. */ struct TranscodingUser { /** @@ -4511,13 +4056,12 @@ struct TranscodingUser { * The layer index number of the host's video. The value range is [0, 100]. * - 0: (Default) The host's video is the bottom layer. * - 100: The host's video is the top layer. - * @note - * - If the value is less than 0 or greater than 100, `ERR_INVALID_ARGUMENT` error is returned. - * - Setting zOrder to 0 is supported. + * + * If the value is beyond this range, the SDK reports the error code `ERR_INVALID_ARGUMENT`. */ int zOrder; /** - * The transparency of the host's video. The value range is [0.0,1.0]. + * The transparency of the host's video. The value range is [0.0, 1.0]. * - 0.0: Completely transparent. * - 1.0: (Default) Opaque. */ @@ -4525,8 +4069,8 @@ struct TranscodingUser { /** * The audio channel used by the host's audio in the output audio. The default value is 0, and the * value range is [0, 5]. - * - `0`: (Recommended) The defaut setting, which supports dual channels at most and depends on the - * upstream of the host. + * - `0`: (Recommended) The defaut setting, which supports dual channels at most and depends on + * the upstream of the host. * - `1`: The host's audio uses the FL audio channel. If the host's upstream uses multiple audio * channels, the Agora server mixes them into mono first. * - `2`: The host's audio uses the FC audio channel. If the host's upstream uses multiple audio @@ -4537,8 +4081,9 @@ struct TranscodingUser { * channels, the Agora server mixes them into mono first. * - `5`: The host's audio uses the BR audio channel. If the host's upstream uses multiple audio * channels, the Agora server mixes them into mono first. - * - `0xFF` or a value greater than `5`: The host's audio is muted, and the Agora server removes the + * - `0xFF` or a value greater than 5: The host's audio is muted, and the Agora server removes the * host's audio. + * * @note If the value is not `0`, a special player is required. */ int audioChannel; @@ -4548,125 +4093,108 @@ struct TranscodingUser { }; /** - * @brief Transcoding configurations for Media Push. + * Transcoding configurations for Media Push. */ struct LiveTranscoding { - /** - * The width of the video in pixels. The default value is 360. - * - 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. + /** The width of the video in pixels. The default value is 360. + * - 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, 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. + /** The height of the video in pixels. The default value is 640. + * - 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; - /** - * The encoding bitrate (Kbps) of the video. This parameter does not need to be set; keeping the - * default value `STANDARD_BITRATE` is sufficient. The SDK automatically matches the most suitable - * bitrate based on the video resolution and frame rate you have set. For the correspondence between - * video resolution and frame rate, see `Video profile`. - */ + /** Bitrate of the CDN live output video stream. The default value is 400 Kbps. + + Set this parameter according to the Video Bitrate Table. If you set a bitrate beyond the proper + range, the SDK automatically adapts it to a value within the range. + */ int videoBitrate; - /** - * Frame rate (fps) of the output video stream set for Media Push. The default value is 15. The - * value range is (0,30]. - * @note The Agora server adjusts any value over 30 to 30. - */ + /** Frame rate of the output video stream set for the CDN live streaming. The default value is 15 + fps, and the value range is (0,30]. + + @note The Agora server adjusts any value over 30 to 30. + */ int videoFramerate; - /** - * Deprecated - * This member is deprecated. - * Latency mode: - * - `true`: Low latency with unassured quality. - * - `false`: (Default) High latency with assured quality. + /** **DEPRECATED** Latency mode: + + - true: Low latency with unassured quality. + - false: (Default) High latency with assured quality. */ bool lowLatency; - /** - * GOP (Group of Pictures) in fps of the video frames for Media Push. The default value is 30. + /** Video GOP in frames. The default value is 30 fps. */ int videoGop; - /** - * Video codec profile type for Media Push. Set it as 66, 77, or 100 (default). See - * `VIDEO_CODEC_PROFILE_TYPE` for details. - * @note If you set this parameter to any other value, Agora adjusts it to the default value. - */ + /** Self-defined video codec profile: #VIDEO_CODEC_PROFILE_TYPE. + + @note If you set this parameter to other values, Agora adjusts it to the default value of 100. + */ VIDEO_CODEC_PROFILE_TYPE videoCodecProfile; - /** - * The background color in RGB hex value. Value only. Do not include a preceeding #. For example, + /** The background color in RGB hex value. Value only. Do not include a preceeding #. For example, * 0xFFB6C1 (light pink). The default value is 0x000000 (black). */ unsigned int backgroundColor; - /** - * Video codec profile types for Media Push. See `VIDEO_CODEC_TYPE_FOR_STREAM`. - */ + /** Video codec profile types for Media Push. See VIDEO_CODEC_TYPE_FOR_STREAM. */ VIDEO_CODEC_TYPE_FOR_STREAM videoCodecType; - /** - * The number of users in the Media Push. The value range is [0,17]. + /** The number of users in the live interactive streaming. + * The value range is [0, 17]. */ unsigned int userCount; - /** - * Manages the user layout configuration in the Media Push. Agora supports a maximum of 17 + /** Manages the user layout configuration in the Media Push. Agora supports a maximum of 17 * transcoding users in a Media Push channel. See `TranscodingUser`. */ TranscodingUser* transcodingUsers; - /** - * Reserved property. Extra user-defined information to send SEI for the H.264/H.265 video stream to - * the CDN live client. Maximum length: 4096 bytes. For more information on SEI, see SEI-related - * questions. + /** Reserved property. Extra user-defined information to send SEI for the H.264/H.265 video stream + to the CDN live client. Maximum length: 4096 Bytes. + + For more information on SEI frame, see [SEI-related questions](https://docs.agora.io/en/faq/sei). */ const char* transcodingExtraInfo; - /** - * Deprecated - * Obsolete and not recommended for use. - * The metadata sent to the CDN client. + /** **DEPRECATED** The metadata sent to the CDN live client. */ const char* metadata; - /** - * The watermark on the live video. The image format needs to be PNG. See `RtcImage`. - * You can add one watermark, or add multiple watermarks using an array. This parameter is used with - * `watermarkCount`. - */ + /** The watermark on the live video. The image format needs to be PNG. See `RtcImage`. + + You can add one watermark, or add multiple watermarks using an array. This parameter is used with + `watermarkCount`. + */ RtcImage* watermark; /** - * The number of watermarks on the live video. The total number of watermarks and background images - * can range from 0 to 10. This parameter is used with `watermark`. + * The number of watermarks on the live video. The total number of watermarks and background + * images can range from 0 to 10. This parameter is used with `watermark`. */ unsigned int watermarkCount; - /** - * The number of background images on the live video. The image format needs to be PNG. See + /** The number of background images on the live video. The image format needs to be PNG. See * `RtcImage`. - * You can add a background image or use an array to add multiple background images. This parameter - * is used with `backgroundImageCount`. + * + * You can add a background image or use an array to add multiple background images. This + * parameter is used with `backgroundImageCount`. */ RtcImage* backgroundImage; /** - * The number of background images on the live video. The total number of watermarks and background - * images can range from 0 to 10. This parameter is used with `backgroundImage`. + * The number of background images on the live video. The total number of watermarks and + * background images can range from 0 to 10. This parameter is used with `backgroundImage`. */ unsigned int backgroundImageCount; - /** - * The audio sampling rate (Hz) of the output media stream. See `AUDIO_SAMPLE_RATE_TYPE`. + /** The audio sampling rate (Hz) of the output media stream. See #AUDIO_SAMPLE_RATE_TYPE. */ AUDIO_SAMPLE_RATE_TYPE audioSampleRate; - /** - * Bitrate (Kbps) of the audio output stream for Media Push. The default value is 48, and the + /** Bitrate (Kbps) of the audio output stream for Media Push. The default value is 48, and the * highest value is 128. */ int audioBitrate; - /** - * The number of audio channels for Media Push. Agora recommends choosing 1 (mono), or 2 (stereo) + /** The number of audio channels for Media Push. Agora recommends choosing 1 (mono), or 2 (stereo) * audio channels. Special players are required if you choose 3, 4, or 5. * - 1: (Default) Mono. * - 2: Stereo. @@ -4675,18 +4203,15 @@ struct LiveTranscoding { * - 5: Five audio channels. */ int audioChannels; - /** - * Audio codec profile type for Media Push. See `AUDIO_CODEC_PROFILE_TYPE`. + /** Audio codec profile type for Media Push. See #AUDIO_CODEC_PROFILE_TYPE. */ AUDIO_CODEC_PROFILE_TYPE audioCodecProfile; - /** - * Advanced features of the Media Push with transcoding. See `LiveStreamAdvancedFeature`. + /** Advanced features of the RTMP or RTMPS streaming with transcoding. See + * LiveStreamAdvancedFeature. */ LiveStreamAdvancedFeature* advancedFeatures; - /** - * The number of enabled advanced features. The default value is 0. - */ + /** The number of enabled advanced features. The default value is 0. */ unsigned int advancedFeatureCount; LiveTranscoding() @@ -4716,66 +4241,65 @@ struct LiveTranscoding { }; /** - * @brief The video streams for local video mixing. + * The video streams for the video mixing on the local client. */ struct TranscodingVideoStream { /** - * The video source type for local video mixing. See `VIDEO_SOURCE_TYPE`. + * The source type of video for the video mixing on the local client. See #VIDEO_SOURCE_TYPE. */ VIDEO_SOURCE_TYPE sourceType; /** - * The user ID of the remote user. - * @note Use this parameter only when the source type is `VIDEO_SOURCE_REMOTE` for local video - * mixing. + * The ID of the remote user. + * @note Use this parameter only when the source type of the video for the video mixing on the + * local client is `VIDEO_SOURCE_REMOTE`. */ uid_t remoteUserUid; /** - * The file path of local images. - * Examples: - * - Windows: `C:\\Users\\{username}\\Pictures\\image.png` - * @note Use this parameter only when the source type is the image for local video mixing. + * The URL of the image. + * @note Use this parameter only when the source type of the video for the video mixing on the + * local client is `RTC_IMAGE`. */ const char* imageUrl; /** - * (Optional) Media player ID. Use the parameter only when you set `sourceType` to - * `VIDEO_SOURCE_MEDIA_PLAYER`. + * MediaPlayer id if sourceType is MEDIA_PLAYER_SOURCE. */ int mediaPlayerId; /** - * The relative lateral displacement of the top left corner of the video for local video mixing to - * the origin (the top left corner of the canvas). + * The horizontal displacement of the top-left corner of the video for the video mixing on the + * client relative to the top-left corner (origin) of the canvas for this video mixing. */ int x; /** - * The relative longitudinal displacement of the top left corner of the captured video to the origin - * (the top left corner of the canvas). + * The vertical displacement of the top-left corner of the video for the video mixing on the + * client relative to the top-left corner (origin) of the canvas for this video mixing. */ int y; /** - * The width (px) of the video for local video mixing on the canvas. + * The width (px) of the video for the video mixing on the local client. */ int width; /** - * The height (px) of the video for local video mixing on the canvas. + * The height (px) of the video for the video mixing on the local client. */ int height; /** - * The number of the layer to which the video for the local video mixing belongs. The value range is - * [0, 100]. + * The number of the layer to which the video for the video mixing on the local client belongs. + * The value range is [0,100]. * - 0: (Default) The layer is at the bottom. * - 100: The layer is at the top. */ int zOrder; /** - * The transparency of the video for local video mixing. The value range is [0.0, 1.0]. 0.0 - * indicates that the video is completely transparent, and 1.0 indicates that it is opaque. + * The transparency of the video for the video mixing on the local client. The value range is + * [0.0,1.0]. 0.0 means the transparency is completely transparent. 1.0 means the transparency is + * opaque. */ double alpha; /** - * Whether to mirror the video for the local video mixing. - * - `true`: Mirror the video for the local video mixing. - * - `false`: (Default) Do not mirror the video for the local video mixing. - * @note This parameter only takes effect on video source types that are cameras. + * Whether to mirror the video for the video mixing on the local client. + * - true: Mirroring. + * - false: (Default) Do not mirror. + * @note The paramter only works for videos with the source type `CAMERA`. */ bool mirror; @@ -4793,7 +4317,7 @@ struct TranscodingVideoStream { }; /** - * @brief The configuration of the video mixing on the local client. + * The configuration of the video mixing on the local client. */ struct LocalTranscoderConfiguration { /** @@ -4801,12 +4325,12 @@ struct LocalTranscoderConfiguration { */ unsigned int streamCount; /** - * The video streams for local video mixing. See `TranscodingVideoStream`. + * The video streams for the video mixing on the local client. See TranscodingVideoStream. */ TranscodingVideoStream* videoInputStreams; /** - * The encoding configuration of the mixed video stream after the local video mixing. See - * `VideoEncoderConfiguration`. + * The encoding configuration of the mixed video stream after the video mixing on the local + * client. See VideoEncoderConfiguration. */ VideoEncoderConfiguration videoOutputConfiguration; /** @@ -4826,71 +4350,55 @@ struct LocalTranscoderConfiguration { syncWithPrimaryCamera(true) {} }; -/** - * @brief The error code of the local video mixing failure. - */ enum VIDEO_TRANSCODER_ERROR { /** - * 1: The selected video source has not started video capture. You need to create a video track for - * it and start video capture. + * The video track of the video source is not started. */ VT_ERR_VIDEO_SOURCE_NOT_READY = 1, /** - * 2: The video source type is invalid. You need to re-specify the supported video source type. + * The video source type is not supported. */ VT_ERR_INVALID_VIDEO_SOURCE_TYPE = 2, /** - * 3: The image path is invalid. You need to re-specify the correct image path. + * The image url is not correctly of image source. */ VT_ERR_INVALID_IMAGE_PATH = 3, /** - * 4: The image format is invalid. Make sure the image format is one of PNG, JPEG, or GIF. + * The image format not the type png/jpeg/gif of image source. */ VT_ERR_UNSUPPORT_IMAGE_FORMAT = 4, /** - * 5: The video encoding resolution after video mixing is invalid. + * The layout is invalid such as width is zero. */ VT_ERR_INVALID_LAYOUT = 5, /** - * 20: Unknown internal error. + * Internal error. */ VT_ERR_INTERNAL = 20 }; /** - * @brief The source of the audio streams that are mixed locally. + * The audio streams for the video mixing on the local client. */ struct MixedAudioStream { /** - * The type of the audio source. See `AUDIO_SOURCE_TYPE`. + * The source type of audio for the audio mixing on the local client. See #AUDIO_SOURCE_TYPE. */ AUDIO_SOURCE_TYPE sourceType; /** - * The user ID of the remote user. - * @note Set this parameter if the source type of the locally mixed audio steams is - * AUDIO_SOURCE_REMOTE_USER. + * The ID of the remote user. + * @note Use this parameter only when the source type is `AUDIO_SOURCE_REMOTE`. */ uid_t remoteUserUid; /** - * The channel name. This parameter signifies the channel in which users engage in real-time audio - * and video interaction. Under the premise of the same App ID, users who fill in the same channel - * ID enter the same channel for audio and video interaction. The string length must be less than 64 - * bytes. Supported characters (89 characters in total): - * - All lowercase English letters: a to z. - * - All uppercase English letters: A to Z. - * - All numeric characters: 0 to 9. - * - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", - * "^", "_", "{", "}", "|", "~", "," - * @note Set this parameter if the source type of the locally mixed audio streams is - * AUDIO_SOURCE_REMOTE_CHANNEL or AUDIO_SOURCE_REMOTE_USER. + * The channel ID of the remote user. + * @note Use this parameter only when the source type is `AUDIO_SOURCE_REMOTE`. */ const char* channelId; /** - * The audio track ID. Set this parameter to the custom audio track ID returned in - * `createCustomAudioTrack`. - * @note Set this parameter if the source type of the locally mixed audio steams is - * AUDIO_SOURCE_CUSTOM. + * The track ID of the local track. + * @note Use this parameter only when the source type is `AUDIO_SOURCE_REMOTE`. */ track_id_t trackId; @@ -4918,24 +4426,22 @@ struct MixedAudioStream { }; /** - * @brief The configurations for mixing the lcoal audio. + * The configuration of the audio mixing on the local client. */ struct LocalAudioMixerConfiguration { /** - * The number of the audio streams that are mixed locally. + * The number of the audio streams for the audio mixing on the local client. */ unsigned int streamCount; /** - * The source of the audio streams that are mixed locally. See `MixedAudioStream`. + * The source of the streams to mixed; */ MixedAudioStream* audioInputStreams; /** - * Whether the mxied audio stream uses the timestamp of the audio frames captured by the local - * microphone. - * - `true`: (Default) Yes. Set to this value if you want all locally captured audio streams - * synchronized. - * - `false`: No. The SDK uses the timestamp of the audio frames at the time when they are mixed. + * Whether to use the timestamp follow the local mic's audio frame. + * - true: (Default) Use the timestamp of the captured audio frame as the timestamp of the mixed audio frame. + * - false: Do not use the timestamp of the captured audio frame as the timestamp of the mixed audio frame. Instead, use the timestamp when the mixed audio frame is constructed. */ bool syncWithLocalMic; @@ -4943,36 +4449,37 @@ struct LocalAudioMixerConfiguration { }; /** - * @brief Configurations of the last-mile network test. + * Configurations of the last-mile network test. */ struct LastmileProbeConfig { /** - * Sets whether to test the uplink network. Some users, for example, the audience members in a - * LIVE_BROADCASTING channel, do not need such a test. - * - `true`: Test the uplink network. - * - `false`: Do not test the uplink network. + * Determines whether to test the uplink network. Some users, for example, + * the audience in a live broadcast channel, do not need such a test: + * - true: Test. + * - false: Do not test. */ bool probeUplink; /** - * Sets whether to test the downlink network: - * - `true`: Test the downlink network. - * - `false`: Do not test the downlink network. + * Determines whether to test the downlink network: + * - true: Test. + * - false: Do not test. */ bool probeDownlink; /** - * The expected maximum uplink bitrate (bps) of the local user. The value range is [100000, - * 5000000]. Agora recommends referring to `setVideoEncoderConfiguration` to set the value. + * The expected maximum sending bitrate (bps) of the local user. The value range is [100000, + * 5000000]. We recommend setting this parameter according to the bitrate value set by + * `setVideoEncoderConfiguration`. */ unsigned int expectedUplinkBitrate; /** - * The expected maximum downlink bitrate (bps) of the local user. The value range is + * The expected maximum receiving bitrate (bps) of the local user. The value range is * [100000,5000000]. */ unsigned int expectedDownlinkBitrate; }; /** - * @brief The status of the last-mile probe test. + * The status of the last-mile network tests. */ enum LASTMILE_PROBE_RESULT_STATE { /** @@ -4981,18 +4488,18 @@ enum LASTMILE_PROBE_RESULT_STATE { LASTMILE_PROBE_RESULT_COMPLETE = 1, /** * 2: The last-mile network probe test is incomplete because the bandwidth estimation is not - * available due to limited test resources. One possible reason is that testing resources are - * temporarily limited. + * available due to limited test resources. */ LASTMILE_PROBE_RESULT_INCOMPLETE_NO_BWE = 2, /** - * 3: The last-mile network probe test is not carried out. Probably due to poor network conditions. + * 3: The last-mile network probe test is not carried out, probably due to poor network + * conditions. */ LASTMILE_PROBE_RESULT_UNAVAILABLE = 3 }; /** - * @brief Results of the uplink or downlink last-mile network test. + * Results of the uplink or downlink last-mile network test. */ struct LastmileProbeOneWayResult { /** @@ -5012,19 +4519,19 @@ struct LastmileProbeOneWayResult { }; /** - * @brief Results of the uplink and downlink last-mile network tests. + * Results of the uplink and downlink last-mile network tests. */ struct LastmileProbeResult { /** - * The status of the last-mile network tests. See `LASTMILE_PROBE_RESULT_STATE`. + * The status of the last-mile network tests. See #LASTMILE_PROBE_RESULT_STATE. */ LASTMILE_PROBE_RESULT_STATE state; /** - * Results of the uplink last-mile network test. See `LastmileProbeOneWayResult`. + * Results of the uplink last-mile network test. For details, see LastmileProbeOneWayResult. */ LastmileProbeOneWayResult uplinkReport; /** - * Results of the downlink last-mile network test. See `LastmileProbeOneWayResult`. + * Results of the downlink last-mile network test. For details, see LastmileProbeOneWayResult. */ LastmileProbeOneWayResult downlinkReport; /** @@ -5036,11 +4543,11 @@ struct LastmileProbeResult { }; /** - * @brief Reasons causing the change of the connection state. + * Reasons causing the change of the connection state. */ enum CONNECTION_CHANGED_REASON_TYPE { /** - * 0: The SDK is connecting to the Agora edge server. + * 0: The SDK is connecting to the server. */ CONNECTION_CHANGED_CONNECTING = 0, /** @@ -5048,18 +4555,17 @@ enum CONNECTION_CHANGED_REASON_TYPE { */ CONNECTION_CHANGED_JOIN_SUCCESS = 1, /** - * 2: The connection between the SDK and the Agora edge server is interrupted. + * 2: The connection between the SDK and the server is interrupted. */ CONNECTION_CHANGED_INTERRUPTED = 2, /** - * 3: The connection between the SDK and the Agora edge server is banned by the Agora edge server. - * For example, when a user is kicked out of the channel, this status will be returned. + * 3: The connection between the SDK and the server is banned by the server. This error occurs + * when the user is kicked out of the channel by the server. */ CONNECTION_CHANGED_BANNED_BY_SERVER = 3, /** * 4: The SDK fails to join the channel. When the SDK fails to join the channel for more than 20 - * minutes, this code will be returned and the SDK stops reconnecting to the channel. You need to - * prompt the user to try to switch to another network and rejoin the channel. + * minutes, this error occurs and the SDK stops reconnecting to the channel. */ CONNECTION_CHANGED_JOIN_FAILED = 4, /** @@ -5067,51 +4573,37 @@ enum CONNECTION_CHANGED_REASON_TYPE { */ CONNECTION_CHANGED_LEAVE_CHANNEL = 5, /** - * 6: The App ID is invalid. You need to rejoin the channel with a valid APP ID and make sure the - * App ID you are using is consistent with the one generated in the Agora Console. + * 6: The connection fails because the App ID is not valid. */ CONNECTION_CHANGED_INVALID_APP_ID = 6, /** - * 7: Invalid channel name. Rejoin the channel with a valid channel name. A valid channel name is a - * string of up to 64 bytes in length. Supported characters (89 characters in total): - * - All lowercase English letters: a to z. - * - All uppercase English letters: A to Z. - * - All numeric characters: 0 to 9. - * - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", - * "^", "_", "{", "}", "|", "~", "," + * 7: The connection fails because the channel name is not valid. Please rejoin the channel with a + * valid channel name. */ CONNECTION_CHANGED_INVALID_CHANNEL_NAME = 7, /** - * 8: Invalid token. Possible reasons are as follows: - * - The App Certificate for the project is enabled in Agora Console, but you do not pass in a token - * when joining a channel. - * - The uid specified when calling `joinChannel(const char* token, const char* channelId, uid_t - * uid, const ChannelMediaOptions& options)` to join the channel is inconsistent with the - * uid passed in when generating the token. - * - The generated token and the token used to join the channel are not consistent. - * Ensure the following: - * - When your project enables App Certificate, you need to pass in a token to join a channel. - * - The user ID specified when generating the token is consistent with the user ID used when - * joining the channel. - * - The generated token is the same as the token passed in to join the channel. + * 8: The connection fails because the token is not valid. Typical reasons include: + * - The App Certificate for the project is enabled in Agora Console, but you do not use a token + * when joining the channel. If you enable the App Certificate, you must use a token to join the + * channel. + * - The `uid` specified when calling `joinChannel` to join the channel is inconsistent with the + * `uid` passed in when generating the token. */ CONNECTION_CHANGED_INVALID_TOKEN = 8, /** - * 9: The token currently being used has expired. You need to generate a new token on your server - * and rejoin the channel with the new token. + * 9: The connection fails because the token has expired. */ CONNECTION_CHANGED_TOKEN_EXPIRED = 9, /** - * 10: The connection is rejected by server. Possible reasons are as follows: - * - The user is already in the channel and still calls a method, for example, `joinChannel(const - * char* token, const char* channelId, uid_t uid, const ChannelMediaOptions& options)`, - * to join the channel. Stop calling this method to clear this error. - * - The user tries to join a channel while a test call is in progress. The user needs to join the - * channel after the call test ends. + * 10: The connection is rejected by the server. Typical reasons include: + * - The user is already in the channel and still calls a method, for example, `joinChannel`, to + * join the channel. Stop calling this method to clear this error. + * - The user tries to join the channel when conducting a pre-call test. The user needs to call + * the channel after the call test ends. */ CONNECTION_CHANGED_REJECTED_BY_SERVER = 10, /** - * 11: The connection state changed to reconnecting because the SDK has set a proxy server. + * 11: The connection changes to reconnecting because the SDK has set a proxy server. */ CONNECTION_CHANGED_SETTING_PROXY_SERVER = 11, /** @@ -5119,17 +4611,17 @@ enum CONNECTION_CHANGED_REASON_TYPE { */ CONNECTION_CHANGED_RENEW_TOKEN = 12, /** - * 13: Client IP address changed. If you receive this code multiple times, You need to prompt the - * user to switch networks and try joining the channel again. + * 13: The IP address of the client has changed, possibly because the network type, IP address, or + * port has been changed. */ CONNECTION_CHANGED_CLIENT_IP_ADDRESS_CHANGED = 13, /** * 14: Timeout for the keep-alive of the connection between the SDK and the Agora edge server. The - * SDK tries to reconnect to the server automatically. + * connection state changes to CONNECTION_STATE_RECONNECTING. */ CONNECTION_CHANGED_KEEP_ALIVE_TIMEOUT = 14, /** - * 15: The user has rejoined the channel successfully. + * 15: The SDK has rejoined the channel successfully. */ CONNECTION_CHANGED_REJOIN_SUCCESS = 15, /** @@ -5137,19 +4629,19 @@ enum CONNECTION_CHANGED_REASON_TYPE { */ CONNECTION_CHANGED_LOST = 16, /** - * 17: The connection state changes due to the echo test. + * 17: The change of connection state is caused by echo test. */ CONNECTION_CHANGED_ECHO_TEST = 17, /** - * 18: The local IP address was changed by the user. + * 18: The local IP Address is changed by user. */ CONNECTION_CHANGED_CLIENT_IP_ADDRESS_CHANGED_BY_USER = 18, /** - * 19: The user joined the same channel from different devices with the same UID. + * 19: The connection is failed due to join the same channel on another device with the same uid. */ CONNECTION_CHANGED_SAME_UID_LOGIN = 19, /** - * 20: The number of hosts in the channel has reached the upper limit. + * 20: The connection is failed due to too many broadcasters in the channel. */ CONNECTION_CHANGED_TOO_MANY_BROADCASTERS = 20, @@ -5172,55 +4664,105 @@ enum CONNECTION_CHANGED_REASON_TYPE { }; /** - * @brief The reason for a user role switch failure. + * The reason of changing role's failure. */ enum CLIENT_ROLE_CHANGE_FAILED_REASON { /** - * 1: The number of hosts in the channel exceeds the limit. - * @note This enumerator is reported only when the support for 128 users is enabled. The maximum - * number of hosts is based on the actual number of hosts configured when you enable the 128-user - * feature. + * 1: Too many broadcasters in the channel. */ CLIENT_ROLE_CHANGE_FAILED_TOO_MANY_BROADCASTERS = 1, /** - * 2: The request is rejected by the Agora server. Agora recommends you prompt the user to try to - * switch their user role again. + * 2: The operation of changing role is not authorized. */ CLIENT_ROLE_CHANGE_FAILED_NOT_AUTHORIZED = 2, /** - * 3: The request is timed out. Agora recommends you prompt the user to check the network connection - * and try to switch their user role again. + * 3: The operation of changing role is timeout. * @deprecated This reason is deprecated. */ CLIENT_ROLE_CHANGE_FAILED_REQUEST_TIME_OUT __deprecated = 3, /** - * 4: The SDK is disconnected from the Agora edge server. You can troubleshoot the failure through - * the `reason` reported by `onConnectionStateChanged`. + * 4: The operation of changing role is interrupted since we lost connection with agora service. * @deprecated This reason is deprecated. */ CLIENT_ROLE_CHANGE_FAILED_CONNECTION_FAILED __deprecated = 4, }; /** - * @brief Network type. + * The reason of notifying the user of a message. */ -enum NETWORK_TYPE { +enum WLACC_MESSAGE_REASON { /** - * -1: The network type is unknown. + * WIFI signal is weak. */ - NETWORK_TYPE_UNKNOWN = -1, + WLACC_MESSAGE_REASON_WEAK_SIGNAL = 0, /** - * 0: The SDK disconnects from the network. + * Channel congestion. */ - NETWORK_TYPE_DISCONNECTED = 0, + WLACC_MESSAGE_REASON_CHANNEL_CONGESTION = 1, +}; + +/** + * Suggest an action for the user. + */ +enum WLACC_SUGGEST_ACTION { /** - * 1: The network type is LAN. + * Please get close to AP. */ - NETWORK_TYPE_LAN = 1, + WLACC_SUGGEST_ACTION_CLOSE_TO_WIFI = 0, /** - * 2: The network type is Wi-Fi (including hotspots). + * The user is advised to connect to the prompted SSID. */ - NETWORK_TYPE_WIFI = 2, + WLACC_SUGGEST_ACTION_CONNECT_SSID = 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; +}; + +/** + * The network type. + */ +enum NETWORK_TYPE { + /** + * -1: The network type is unknown. + */ + NETWORK_TYPE_UNKNOWN = -1, + /** + * 0: The SDK disconnects from the network. + */ + NETWORK_TYPE_DISCONNECTED = 0, + /** + * 1: The network type is LAN. + */ + NETWORK_TYPE_LAN = 1, + /** + * 2: The network type is Wi-Fi (including hotspots). + */ + NETWORK_TYPE_WIFI = 2, /** * 3: The network type is mobile 2G. */ @@ -5240,95 +4782,91 @@ enum NETWORK_TYPE { }; /** - * @brief Setting mode of the view. + * The mode of setting up video views. */ enum VIDEO_VIEW_SETUP_MODE { /** - * 0: (Default) Clear all added views and replace with a new view. + * 0: replace one view */ VIDEO_VIEW_SETUP_REPLACE = 0, /** - * 1: Adds a view. + * 1: add one view */ VIDEO_VIEW_SETUP_ADD = 1, /** - * 2: Deletes a view. - * @note When you no longer need to use a certain view, it is recommended to delete the view by - * setting `setupMode` to VIDEO_VIEW_SETUP_REMOVE, otherwise it may lead to leak of rendering - * resources. + * 2: remove one view */ VIDEO_VIEW_SETUP_REMOVE = 2, }; /** - * @brief Attributes of the video canvas object. + * Attributes of video canvas object. */ struct VideoCanvas { /** - * User ID that publishes the video source. + * The user id of local video. */ uid_t uid; /** - * The ID of the user who publishes a specific sub-video stream within the mixed video stream. + * The uid of video stream composing the video stream from transcoder which will be drawn on this + * video canvas. */ uid_t subviewUid; /** - * The video display window. - * @note In one `VideoCanvas`, you can only choose to set either `view` or `surfaceTexture`. If both - * are set, only the settings in `view` take effect. + * Video display window. */ view_t view; /** - * The background color of the video canvas in RGBA format. The default value is 0x00000000, which - * represents black. + * A RGBA value indicates background color of the render view. Defaults to 0x00000000. */ uint32_t backgroundColor; /** - * The rendering mode of the video. See `RENDER_MODE_TYPE`. + * The video render mode. See \ref agora::media::base::RENDER_MODE_TYPE "RENDER_MODE_TYPE". + * The default value is RENDER_MODE_HIDDEN. */ media::base::RENDER_MODE_TYPE renderMode; /** - * The mirror mode of the view. See `VIDEO_MIRROR_MODE_TYPE`. + * The video mirror mode. See \ref VIDEO_MIRROR_MODE_TYPE "VIDEO_MIRROR_MODE_TYPE". + * The default value is VIDEO_MIRROR_MODE_AUTO. * @note - * - For the mirror mode of the local video view: If you use a front camera, the SDK enables the - * mirror mode by default; if you use a rear camera, the SDK disables the mirror mode by default. + * - For the mirror mode of the local video view: + * If you use a front camera, the SDK enables the mirror mode by default; + * if you use a rear camera, the SDK disables the mirror mode by default. * - For the remote user: The mirror mode is disabled by default. */ VIDEO_MIRROR_MODE_TYPE mirrorMode; /** - * Setting mode of the view. See `VIDEO_VIEW_SETUP_MODE`. + * The mode of setting up video view. See \ref VIDEO_VIEW_SETUP_MODE "VIDEO_VIEW_SETUP_MODE" + * The default value is VIDEO_VIEW_SETUP_REPLACE. */ VIDEO_VIEW_SETUP_MODE setupMode; /** - * The type of the video source. See `VIDEO_SOURCE_TYPE`. + * The video source type. See \ref VIDEO_SOURCE_TYPE "VIDEO_SOURCE_TYPE". + * The default value is VIDEO_SOURCE_CAMERA_PRIMARY. */ VIDEO_SOURCE_TYPE sourceType; /** - * The ID of the media player. You can get the Device ID by calling `getMediaPlayerId`. + * The media player id of AgoraMediaPlayer. It should set this parameter when the + * sourceType is VIDEO_SOURCE_MEDIA_PLAYER to show the video that AgoraMediaPlayer is playing. + * You can get this value by calling the method \ref getMediaPlayerId(). */ int mediaPlayerId; /** - * (Optional) Display area of the video frame, see `Rectangle`. `width` and `height` represent the - * video pixel width and height of the area. The default value is null (width or height is 0), which - * means that the actual resolution of the video frame is displayed. + * If you want to display a certain part of a video frame, you can set + * this value to crop the video frame to show. + * The default value is empty(that is, if it has zero width or height), which means no cropping. */ Rectangle cropArea; /** - * (Optional) Whether to enable alpha mask rendering: - * - `true`: Enable alpha mask rendering. - * - `false`: (Default) Disable alpha mask rendering. - * Alpha mask rendering can create images with transparent effects and extract portraits from - * videos. When used in combination with other methods, you can implement effects such as - * portrait-in-picture and watermarking. - * @note - * - The receiver can render alpha channel information only when the sender enables alpha - * transmission. - * - To enable alpha transmission, `technical support`. + * Whether to apply alpha mask to the video frame if exsit: + * true: Apply alpha mask to video frame. + * false: (Default) Do not apply alpha mask to video frame. */ bool enableAlphaMask; /** - * The observation position of the video frame in the video link. See `VIDEO_MODULE_POSITION`. + * The video frame position in pipeline. See \ref VIDEO_MODULE_POSITION "VIDEO_MODULE_POSITION". + * The default value is POSITION_POST_CAPTURER. */ media::base::VIDEO_MODULE_POSITION position; @@ -5390,55 +4928,41 @@ struct VideoCanvas { position(media::base::POSITION_POST_CAPTURER) {} }; -/** - * @brief Image enhancement options. +/** Image enhancement options. */ struct BeautyOptions { - /** - * @brief The contrast level. + /** The contrast level. */ enum LIGHTENING_CONTRAST_LEVEL { - /** - * 0: Low contrast level. - */ + /** Low contrast level. */ LIGHTENING_CONTRAST_LOW = 0, - /** - * 1: (Default) Normal contrast level. - */ + /** (Default) Normal contrast level. */ LIGHTENING_CONTRAST_NORMAL = 1, - /** - * 2: High contrast level. - */ + /** High contrast level. */ LIGHTENING_CONTRAST_HIGH = 2, }; - /** - * The contrast level, used with the `lighteningLevel` parameter. The larger the value, the greater - * the contrast between light and dark. See `LIGHTENING_CONTRAST_LEVEL`. + /** The contrast level, used with the `lighteningLevel` parameter. The larger the value, the + * greater the contrast between light and dark. See #LIGHTENING_CONTRAST_LEVEL. */ LIGHTENING_CONTRAST_LEVEL lighteningContrastLevel; - /** - * The brightening level, in the range [0.0,1.0], where 0.0 means the original brightening. The - * default value is 0.0. The higher the value, the greater the degree of brightening. - */ + /** The brightness level. The value ranges from 0.0 (original) to 1.0. The default value is 0.0. + * The greater the value, the greater the degree of whitening. */ float lighteningLevel; - /** - * The smoothness level, in the range [0.0,1.0], where 0.0 means the original smoothness. The - * default value is 0.0. The greater the value, the greater the smoothness level. + /** The value ranges from 0.0 (original) to 1.0. The default value is 0.0. The greater the value, + * the greater the degree of skin grinding. */ float smoothnessLevel; - /** - * The redness level, in the range [0.0,1.0], where 0.0 means the original redness. The default - * value is 0.0. The larger the value, the greater the redness level. + /** The redness level. The value ranges from 0.0 (original) to 1.0. The default value is 0.0. The + * larger the value, the greater the rosy degree. */ float rednessLevel; - /** - * The sharpness level, in the range [0.0,1.0], where 0.0 means the original sharpness. The default - * value is 0.0. The larger the value, the greater the sharpness level. + /** The sharpness level. The value ranges from 0.0 (original) to 1.0. The default value is 0.0. + * The larger the value, the greater the sharpening degree. */ float sharpnessLevel; @@ -5458,338 +4982,332 @@ struct BeautyOptions { sharpnessLevel(0) {} }; -/** - * @brief Filter effect options. +/** + * @brief Face shape area options. This structure defines options for facial adjustments on different facial areas. * * @since v4.4.0 */ struct FaceShapeAreaOptions { /** - * @brief Chooses the specific facial areas that need to be adjusted. + * @brief The specific facial area to be adjusted. * * @since v4.4.0 */ enum FACE_SHAPE_AREA { - /** - * -1: (Default) Invalid area; facial enhancement effects do not take effect. - */ + /** (Default) Invalid area. */ FACE_SHAPE_AREA_NONE = -1, - /** - * (100): Head, used to achieve a smaller head effect. The value range is 0 to 100, and the default - * value is 50. The larger the value, the more noticeable the adjustment. + /** + * Head Scale, reduces the size of the head. + * The value range is [0, 100]. The default value is 50. + * The larger the value, the stronger the head reduction effect. */ FACE_SHAPE_AREA_HEADSCALE = 100, - /** - * (101): Forehead, used to adjust the hairline height. The range is [0, 100], with a default value - * of 0. The larger the value, the more noticeable the adjustment. + /** + * Forehead, adjusts the size of the forehead. + * The value range is [0, 100]. The default value is 0. + * The larger the value, the stronger the forehead effect. */ FACE_SHAPE_AREA_FOREHEAD = 101, - /** - * (102): Face contour, used to achieve a slimmer face effect. The range is [0, 100], with a default - * value of 0. The larger the value, the more noticeable the adjustment. + /** + * Face Contour, slims the facial contour. + * The value range is [0, 100]. The default value is 0. + * The larger the value, the stronger the facial contour reduction effect. */ FACE_SHAPE_AREA_FACECONTOUR = 102, - /** - * (103): Face length, used to achieve a longer face effect. The range is [-100, 100], with a - * default value of 0. The greater the absolute value, the more noticeable the adjustment. Negative - * values indicate the opposite direction. + /** + * Face Length, adjusts the length of the face. + * The value range is [-100, 100]. The default value is 0. + * The larger the absolute value, the stronger the face length effect, negative values indicate the opposite direction. */ FACE_SHAPE_AREA_FACELENGTH = 103, - /** - * (104): Face width, used to achieve a narrower face effect. The range is [0, 100], with a default - * value of 0. The larger the value, the more noticeable the adjustment. + /** + * Face Width, narrows the width of the face. + * The value range is [0, 100]. The default value is 0. + * The larger the value, the stronger the face width reduction effect. */ FACE_SHAPE_AREA_FACEWIDTH = 104, - /** - * (105): Cheekbone, used to adjust cheekbone width. The range is [0, 100], with a default value of - * 0. The larger the value, the more noticeable the adjustment.The larger the value, the more - * noticeable the adjustment. + /** + * Cheekbone, adjusts the size of the cheekbone. + * The value range is [0, 100]. The default value is 0. + * The larger the value, the stronger the cheekbone effect. */ FACE_SHAPE_AREA_CHEEKBONE = 105, - /** - * (106): Cheek, used to adjust cheek width. The range is [0, 100], with a default value of 0. The - * larger the value, the more noticeable the adjustment. + /** + * Cheek, adjusts the size of the cheek. + * The value range is [0, 100]. The default value is 0. + * The larger the value, the stronger the cheek effect. */ FACE_SHAPE_AREA_CHEEK = 106, - /** - * (107): Adjustment of the mandible. The range is [0, 100], with a default value of 0. The larger - * the value, the more noticeable the adjustment. + /** + * Mandible, slims the mandible. + * The value range is [0, 100]. The default value is 0. + * The larger the value, the stronger the mandible effect. * @since v4.6.0 */ FACE_SHAPE_AREA_MANDIBLE = 107, - /** - * (108): Chin, used to adjust chin length. The range is [-100, 100], with a default value of 0. The - * greater the absolute value, the more noticeable the adjustment. Negative values indicate the - * opposite direction. - */ + /** + * Chin, adjusts the length of the chin. + * The value range is [-100, 100]. The default value is 0. + * The larger the absolute value, the stronger the chin effect, negative values indicate the opposite direction. + */ FACE_SHAPE_AREA_CHIN = 108, - /** - * (200): Eyes, used to achieve a larger eye effect. The value range is 0 to 100, and the default - * value is 50. The larger the value, the more noticeable the adjustment. + /** + * Eye Scale, adjusts the size of the eyes. + * The value range is [0, 100]. The default value is 50. + * The larger the value, the stronger the eye size effect. */ FACE_SHAPE_AREA_EYESCALE = 200, - /** - * (201): Eye distance adjustment. The range is [-100, 100], with a default value of 0. The greater - * the absolute value, the more noticeable the adjustment. Negative values indicate the opposite - * direction. + /** + * Eye Distance, adjusts the distance between the two eyes. + * The value range is [-100, 100]. The default value is 0. + * The larger the absolute value, the stronger the eye distance effect, negative values indicate the opposite direction. * @since v4.6.0 */ FACE_SHAPE_AREA_EYEDISTANCE = 201, - /** - * (202): Eye position adjustment. The range is [-100, 100], with a default value of 0. The greater - * the absolute value, the more noticeable the adjustment. Negative values indicate the opposite - * direction. + /** + * Eye Position, adjusts the upper and lower position of the eyes. + * The value range is [-100, 100]. The default value is 0. + * The larger the absolute value, the stronger the eye position effect, negative values indicate the opposite direction. * @since v4.6.0 */ FACE_SHAPE_AREA_EYEPOSITION = 202, - /** - * (203): Lower eyelid adjustment.(203): Lower eyelid adjustment. The range is [0, 100], with a - * default value of 0. The larger the value, the more noticeable the adjustment. + /** + * Lower Eyelid, adjusts the downward position of the eyelids. + * The value range is [0, 100]. The default value is 0. + * The larger the value, the stronger the lower eyelid effect. * @since v4.6.0 */ FACE_SHAPE_AREA_LOWEREYELID = 203, - /** - * (204): Pupil size adjustment. The range is [0, 100], with a default value of 0. The larger the - * value, the more noticeable the adjustment. + /** + * Eye Pupils, adjusts the size of the pupils. + * The value range is [0, 100]. The default value is 0. + * The larger the value, the stronger the eye pupils effect. * @since v4.6.0 */ FACE_SHAPE_AREA_EYEPUPILS = 204, - /** - * (205): Inner eye corner adjustment. The range is [-100, 100], with a default value of 0. The - * greater the absolute value, the more noticeable the adjustment. Negative values indicate the - * opposite direction. + /** + * Eye Inner Corner, adjusts the inner corners of the eyes. + * The value range is [-100, 100]. The default value is 0. + * The larger the absolute value, the stronger the eye inner corner effect, negative values indicate the opposite direction. * @since v4.6.0 */ FACE_SHAPE_AREA_EYEINNERCORNER = 205, - /** - * (206): Outer eye corner adjustment. The range is [-100, 100], with a default value of 0. The - * greater the absolute value, the more noticeable the adjustment. Negative values indicate the - * opposite direction. + /** + * Eye Outer Corner, adjusts the outer corners of the eyes. + * The value range is [-100, 100]. The default value is 0. + * The larger the absolute value, the stronger the eye outer corner effect, negative values indicate the opposite direction. * @since v4.6.0 */ FACE_SHAPE_AREA_EYEOUTERCORNER = 206, - /** - * (300): Nose length, used to achieve a longer nose effect. The range is [-100, 100], with a - * default value of 0. + /** + * Nose Length, adjusts the length of the nose. + * The value range is [-100, 100]. The default value is 0. */ FACE_SHAPE_AREA_NOSELENGTH = 300, - /** - * (301): Nose width, used to achieve a slimmer nose effect. The range is [0, 100], with a default - * value of 0. The larger the value, the more noticiable the effect of narrowing the nose. + /** + * Nose Width, adjusts the width of the nose. + * The value range is [0, 100]. The default value is 0. + * The larger the value, the stronger the nose width effect. * @since v4.6.0 */ FACE_SHAPE_AREA_NOSEWIDTH = 301, - /** - * (302): Nose wing adjustment. The value range is 0 to 100, and the default value is 10. The larger - * the value, the more noticeable the adjustment. + /** + * Nose Wing, adjusts the size of the nose wings. + * The value range is [0, 100]. The default value is 10. + * The larger the value, the stronger the nose wing effect. * @since v4.6.0 */ FACE_SHAPE_AREA_NOSEWING = 302, - /** - * (303): Nose root adjustment. The range is [0, 100], with a default value of 0. The larger the - * value, the more noticeable the adjustment. + /** + * Nose Root, adjusts the size of the nose root. + * The value range is [0, 100]. The default value is 0. + * The larger the value, the stronger the nose root effect. * @since v4.6.0 */ FACE_SHAPE_AREA_NOSEROOT = 303, - /** - * (304): Nose bridge adjustment. The value range is 0 to 100, and the default value is 50. The - * larger the value, the more noticeable the adjustment. + /** + * Nose Bridge, adjusts the size of the nose bridge. + * The value range is [0, 100]. The default value is 50. + * The larger the value, the stronger the nose bridge effect. * @since v4.6.0 */ FACE_SHAPE_AREA_NOSEBRIDGE = 304, - /** - * (305): Nose tip adjustment. The value range is 0 to 100, and the default value is 50. The larger - * the value, the more noticeable the adjustment. + /** + * Nose Tip, adjusts the size of the nose tip. + * The value range is [0, 100]. The default value is 50. + * The larger the value, the stronger the nose tip effect. * @since v4.6.0 */ FACE_SHAPE_AREA_NOSETIP = 305, - /** - * (306): Overall nose adjustment. The range is [-100, 100], with a default value of 50. The greater - * the absolute value, the more noticeable the adjustment. Negative values indicate the opposite - * direction. + /** + * Nose General, adjusts the overall size of the nose. + * The value range is [-100, 100]. The default value is 50. + * The larger the absolute value, the stronger the nose general effect, negative values indicate the opposite direction. * @since v4.6.0 */ FACE_SHAPE_AREA_NOSEGENERAL = 306, - /** - * (400): Mouth, used to achieve a larger mouth effect. The range is [-100, 100], with a default - * value of 20. The greater the absolute value, the more noticeable the adjustment. Negative values - * indicate the opposite direction. + /** + * Mouth Scale, adjusts the size of the mouth. + * The value range is [-100, 100]. The default value is 20. + * The larger the absolute value, the stronger the mouth size effect, negative values indicate the opposite direction. * @since v4.6.0 */ FACE_SHAPE_AREA_MOUTHSCALE = 400, - /** - * (401): Mouth position adjustment. The range is [0, 100], with a default value of 0. The larger - * the value, the more noticeable the adjustment. + /** + * Mouth Position, adjusts the position of the mouth. + * The value range is [0, 100]. The default value is 0. + * The larger the value, the stronger the mouth position effect. * @since v4.6.0 */ FACE_SHAPE_AREA_MOUTHPOSITION = 401, - /** - * (402): Mouth smile adjustment. The value range is [0,1], and the default value is 0. The larger - * the value, the more noticeable the adjustment. + /** + * Mouth Smile, adjusts the degree of the mouth's smile. + * The value range is [0, 100]. The default value is 30. + * The larger the value, the stronger the mouth smile effect. * @since v4.6.0 */ FACE_SHAPE_AREA_MOUTHSMILE = 402, - /** - * (403): Lip shape adjustment. The range is [0, 100], with a default value of 0. The larger the - * value, the more noticeable the adjustment. - * @note v.4.6.0. + /** + * Mouth Lip, adjusts the size of the lips. + * The value range is [0, 100]. The default value is 0. + * The larger the value, the stronger the mouth lip effect. * @since v4.6.0 */ FACE_SHAPE_AREA_MOUTHLIP = 403, - /** - * (500): Eyebrow position adjustment. The range is [-100, 100], with a default value of 0. The - * greater the absolute value, the more noticeable the adjustment. Negative values indicate the - * opposite direction. + /** + * Eyebrow Position, adjusts the position of the eyebrows. + * The value range is [-100, 100]. The default value is 0. + * The larger the absolute value, the stronger the eyebrow position effect, negative values indicate the opposite direction. * @since v4.6.0 */ FACE_SHAPE_AREA_EYEBROWPOSITION = 500, - /** - * (501): Eyebrow thickness adjustment. The range is [-100, 100], with a default value of 0. The - * larger the value, the more noticeable the adjustment. + /** + * Eyebrow Thickness, adjusts the thickness of the eyebrows. + * The value range is [-100, 100]. The default value is 0. + * The larger the value, the stronger the eyebrow thickness effect. * @since v4.6.0 */ FACE_SHAPE_AREA_EYEBROWTHICKNESS = 501, }; - - /** - * Facial enhancement areas: `FACE_SHAPE_AREA` - */ + + /** The specific facial area to be adjusted, See #FACE_SHAPE_AREA. + */ FACE_SHAPE_AREA shapeArea; - /** - * The intensity of the enhancement. The definition of enhancement intensity varies according to the - * different face areas, such as its orientation, range, and preset value. See `FACE_SHAPE_AREA`. + /** + * The intensity of the pinching effect applied to the specified facial area. */ int shapeIntensity; - + FaceShapeAreaOptions(FACE_SHAPE_AREA shapeArea, int areaIntensity) : shapeArea(shapeArea), shapeIntensity(areaIntensity) {} FaceShapeAreaOptions() : shapeArea(FACE_SHAPE_AREA_NONE), shapeIntensity(0) {} }; -/** - * @brief The facial enhancement style options. +/** @brief Face shape beauty options. This structure defines options for facial adjustments of different facial styles. * * @since v4.4.0 */ struct FaceShapeBeautyOptions { /** - * @brief The facial enhancement style options. + * @brief The face shape beauty style options. * * @since v4.4.0 */ enum FACE_SHAPE_BEAUTY_STYLE { /** - * 0: (Default) Feminine style. + * (Default) Female face shape style. */ FACE_SHAPE_BEAUTY_STYLE_FEMALE = 0, /** - * 1: Masculine style. + * Male face shape style. */ FACE_SHAPE_BEAUTY_STYLE_MALE = 1, /** - * 2: The natural style beauty effect only makes minimal adjustments to facial features. + * A natural-looking face shape style that applies minimal modification to facial features. * @since v4.6.0 */ FACE_SHAPE_BEAUTY_STYLE_NATURAL = 2, }; - - /** - * Facial enhancement style options: `FACE_SHAPE_BEAUTY_STYLE`. - */ + + /** The face shape style, See #FACE_SHAPE_BEAUTY_STYLE. + */ FACE_SHAPE_BEAUTY_STYLE shapeStyle; - - /** - * The intensity of the facial enhancement style, with a value range oof [0.0,1.0]. The default - * value is 0.0, which means no face enhancement effect. The higher the value, the more obvious the - * facial enhancement effect. - */ + + /** The intensity of the pinching effect applied to the specified facial style. The value ranges from 0 (original) to 100. The default value is 0. The greater the value, the stronger the intensity applied to face pinching. + */ int styleIntensity; - + FaceShapeBeautyOptions(FACE_SHAPE_BEAUTY_STYLE shapeStyle, int styleIntensity) : shapeStyle(shapeStyle), styleIntensity(styleIntensity) {} FaceShapeBeautyOptions() : shapeStyle(FACE_SHAPE_BEAUTY_STYLE_FEMALE), styleIntensity(50) {} }; -/** - * @brief Filter effect options. +/** Filter effect options. This structure defines options for filter effect. * * @since v4.4.1 */ struct FilterEffectOptions { /** - * The absolute path to the local cube map texture file, which can be used to customize the filter - * effect. The specified .cude file should strictly follow the Cube LUT Format Specification; - * otherwise, the filter options do not take effect. The following is a sample of the .cude file: - * ``` + * The local absolute path of the custom 3D Cube path. Only cube format is supported. + * The cube file must strictly comply with the Cube LUT Specification; otherwise, the filter effects will not take effect. + * + * The following is an example of the Cube file format. The cube file starts with `LUT_3D_SIZE`, which indicates the cube size. In filter effects, the cube size is limited to 32. + * LUT_3D_SIZE 32 * 0.0039215689 0 0.0039215682 * 0.0086021447 0.0037950677 0 - * ... * 0.0728652592 0.0039215689 0 - * ``` - * @note - * - The identifier `LUT_3D_SIZE` on the first line of the cube map file represents the size of the - * three-dimensional lookup table. The LUT size for filter effect can only be set to 32. - * - The SDK provides a built-in `built_in_whiten_filter.cube` file. You can pass the absolute path - * of this file to get the whitening filter effect. + * ... + * + * The SDK provides a built-in cube named `built_in_whiten.cube` for whitening. To use this cube, specify the path to `built_in_whiten_filter` */ const char * path; - + /** - * The intensity of the filter effect, with a range value of [0.0,1.0], in which 0.0 represents no - * filter effect. The default value is 0.5. The higher the value, the stronger the filter effect. + * The intensity of specified filter effect. The value ranges from 0.0 to 1.0. The default value is 0.5. The greater the value, the stronger the intensity of the filter. */ float strength; - + FilterEffectOptions(const char * lut3dPath, float filterStrength) : path(lut3dPath), strength(filterStrength) {} FilterEffectOptions() : path(OPTIONAL_NULLPTR), strength(0.5) {} }; -/** - * @brief The low-light enhancement options. - */ struct LowlightEnhanceOptions { /** - * @brief The low-light enhancement mode. + * The low-light enhancement mode. */ enum LOW_LIGHT_ENHANCE_MODE { - /** - * 0: (Default) Automatic mode. The SDK automatically enables or disables the low-light enhancement - * feature according to the ambient light to compensate for the lighting level or prevent - * overexposure, as necessary. - */ + /** 0: (Default) Automatic mode. The SDK automatically enables or disables the low-light + enhancement feature according to the ambient light to compensate for the lighting level or + prevent overexposure, as necessary. */ LOW_LIGHT_ENHANCE_AUTO = 0, - /** - * 1: Manual mode. Users need to enable or disable the low-light enhancement feature manually. - */ + /** Manual mode. Users need to enable or disable the low-light enhancement feature manually. */ LOW_LIGHT_ENHANCE_MANUAL = 1, }; /** - * @brief The low-light enhancement level. + * The low-light enhancement level. */ enum LOW_LIGHT_ENHANCE_LEVEL { /** - * 0: (Default) Promotes video quality during low-light enhancement. It processes the brightness, - * details, and noise of the video image. The performance consumption is moderate, the processing - * speed is moderate, and the overall video quality is optimal. + * 0: (Default) Promotes video quality during low-light enhancement. It processes the + * brightness, details, and noise of the video image. The performance consumption is moderate, + * the processing speed is moderate, and the overall video quality is optimal. */ LOW_LIGHT_ENHANCE_LEVEL_HIGH_QUALITY = 0, /** - * 1: Promotes performance during low-light enhancement. It processes the brightness and details of + * Promotes performance during low-light enhancement. It processes the brightness and details of * the video image. The processing speed is faster. */ LOW_LIGHT_ENHANCE_LEVEL_FAST = 1, }; - /** - * The low-light enhancement mode. See `LOW_LIGHT_ENHANCE_MODE`. + /** The low-light enhancement mode. See #LOW_LIGHT_ENHANCE_MODE. */ LOW_LIGHT_ENHANCE_MODE mode; - /** - * The low-light enhancement level. See `LOW_LIGHT_ENHANCE_LEVEL`. + /** The low-light enhancement level. See #LOW_LIGHT_ENHANCE_LEVEL. */ LOW_LIGHT_ENHANCE_LEVEL level; @@ -5800,51 +5318,45 @@ struct LowlightEnhanceOptions { : mode(LOW_LIGHT_ENHANCE_AUTO), level(LOW_LIGHT_ENHANCE_LEVEL_HIGH_QUALITY) {} }; /** - * @brief Video noise reduction options. + * The video noise reduction options. * * @since v4.0.0 */ struct VideoDenoiserOptions { - /** - * @brief Video noise reduction mode. + /** The video noise reduction mode. */ enum VIDEO_DENOISER_MODE { - /** - * 0: (Default) Automatic mode. The SDK automatically enables or disables the video noise reduction - * feature according to the ambient light. - */ + /** 0: (Default) Automatic mode. The SDK automatically enables or disables the video noise + reduction feature according to the ambient light. */ VIDEO_DENOISER_AUTO = 0, - /** - * 1: Manual mode. Users need to enable or disable the video noise reduction feature manually. - */ + /** Manual mode. Users need to enable or disable the video noise reduction feature manually. */ VIDEO_DENOISER_MANUAL = 1, }; /** - * @brief Video noise reduction level. + * The video noise reduction level. */ enum VIDEO_DENOISER_LEVEL { /** - * 0: (Default) Promotes video quality during video noise reduction. balances performance - * consumption and video noise reduction quality. The performance consumption is moderate, the video - * noise reduction speed is moderate, and the overall video quality is optimal. + * 0: (Default) Promotes video quality during video noise reduction. `HIGH_QUALITY` balances + * performance consumption and video noise reduction quality. The performance consumption is + * moderate, the video noise reduction speed is moderate, and the overall video quality is + * optimal. */ VIDEO_DENOISER_LEVEL_HIGH_QUALITY = 0, /** - * 1: Promotes reducing performance consumption during video noise reduction. It prioritizes - * reducing performance consumption over video noise reduction quality. The performance consumption - * is lower, and the video noise reduction speed is faster. To avoid a noticeable shadowing effect - * (shadows trailing behind moving objects) in the processed video, Agora recommends that you use - * this setting when the camera is fixed. + * Promotes reducing performance consumption during video noise reduction. `FAST` prioritizes + * reducing performance consumption over video noise reduction quality. The performance + * consumption is lower, and the video noise reduction speed is faster. To avoid a noticeable + * shadowing effect (shadows trailing behind moving objects) in the processed video, Agora + * recommends that you use `FAST` when the camera is fixed. */ VIDEO_DENOISER_LEVEL_FAST = 1, }; - /** - * Video noise reduction mode. See `VIDEO_DENOISER_MODE`. + /** The video noise reduction mode. See #VIDEO_DENOISER_MODE. */ VIDEO_DENOISER_MODE mode; - /** - * Video noise reduction level. See `VIDEO_DENOISER_LEVEL`. + /** The video noise reduction level. See #VIDEO_DENOISER_LEVEL. */ VIDEO_DENOISER_LEVEL level; @@ -5854,27 +5366,22 @@ struct VideoDenoiserOptions { VideoDenoiserOptions() : mode(VIDEO_DENOISER_AUTO), level(VIDEO_DENOISER_LEVEL_HIGH_QUALITY) {} }; -/** - * @brief The color enhancement options. +/** The color enhancement options. * * @since v4.0.0 */ struct ColorEnhanceOptions { - /** - * The level of color enhancement. The value range is [0.0, 1.0]. `0.0` is the default value, which - * means no color enhancement is applied to the video. The higher the value, the higher the level of - * color enhancement. The default value is `0.5`. + /** The level of color enhancement. The value range is [0.0,1.0]. `0.0` is the default value, + * which means no color enhancement is applied to the video. The higher the value, the higher the + * level of color enhancement. */ float strengthLevel; - /** - * The level of skin tone protection. The value range is [0.0, 1.0]. `0.0` means no skin tone - * protection. The higher the value, the higher the level of skin tone protection. The default value - * is `1.0`. - * - When the level of color enhancement is higher, the portrait skin tone can be significantly - * distorted, so you need to set the level of skin tone protection. - * - When the level of skin tone protection is higher, the color enhancement effect can be slightly - * reduced. + /** The level of skin tone protection. The value range is [0.0,1.0]. `0.0` means no skin tone + * protection. The higher the value, the higher the level of skin tone protection. The default + * value is `1.0`. When the level of color enhancement is higher, the portrait skin tone can be + * significantly distorted, so you need to set the level of skin tone protection; when the level + * of skin tone protection is higher, the color enhancement effect can be slightly reduced. * Therefore, to get the best color enhancement effect, Agora recommends that you adjust * `strengthLevel` and `skinProtectLevel` to get the most appropriate values. */ @@ -5887,90 +5394,76 @@ struct ColorEnhanceOptions { }; /** - * @brief The custom background. + * The custom background image. */ struct VirtualBackgroundSource { - /** - * @brief The custom background. + /** The type of the custom background source. */ enum BACKGROUND_SOURCE_TYPE { /** - * 0: Process the background as alpha data without replacement, only separating the portrait and the - * background. After setting this value, you can call `startLocalVideoTranscoder` to implement the - * picture-in-picture effect. + * 0: Enable segementation with the captured video frame without replacing the background. */ BACKGROUND_NONE = 0, /** - * 1: (Default) The background image is a solid color. + * 1: (Default) The background source is a solid color. */ BACKGROUND_COLOR = 1, /** - * 2: The background is an image in PNG or JPG format. + * The background source is a file in PNG or JPG format. */ BACKGROUND_IMG = 2, /** - * 3: The background is a blurred version of the original background. - */ + * The background source is the blurred original video frame. + * */ BACKGROUND_BLUR = 3, /** - * 4: The background is a local video in MP4, AVI, MKV, FLV, or other supported formats. - */ + * The background source is a file in MP4, AVI, MKV, FLV format. + * */ BACKGROUND_VIDEO = 4, }; - /** - * @brief The degree of blurring applied to the custom background image. + /** The degree of blurring applied to the background source. */ 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. - */ + /** 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, - /** - * 2: The degree of blurring applied to the custom background image is medium. It is difficult for - * the user to recognize details in the background. - */ + /** 2: 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 = 2, - /** - * 3: (Default) The degree of blurring applied to the custom background image is high. The user can - * barely see any distinguishing features in the background. - */ + /** 3: (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 = 3, }; - /** - * The custom background. See `BACKGROUND_SOURCE_TYPE`. + /** The type of the custom background image. See #BACKGROUND_SOURCE_TYPE. */ BACKGROUND_SOURCE_TYPE background_source_type; /** - * The type of the custom background image. The color of the custom background image. The format is - * a hexadecimal integer defined by RGB, without the # sign, such as 0xFFB6C1 for light pink. The - * default value is 0xFFFFFF, which signifies white. The value range is [0x000000, 0xffffff]. If the - * value is invalid, the SDK replaces the original background image with a white background image. - * @note - * This parameter is only applicable to custom backgrounds of the following types: - * - BACKGROUND_COLOR: The background image is a solid-colored image of the color passed in by the - * parameter. - * - BACKGROUND_IMG: If the image in `source` has a transparent background, the transparent - * background will be filled with the color passed in by the parameter. + * 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. Supports PNG, JPG, MP4, AVI, MKV, and FLV - * formats. If the path is invalid, the SDK will use either the original background image or the - * solid color image specified by `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 or BACKGROUND_VIDEO. + * `BACKGROUND_IMG`. */ const char* source; - /** - * The degree of blurring applied to the custom background image. See `BACKGROUND_BLUR_DEGREE`. + /** 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. + * `BACKGROUND_BLUR`. */ BACKGROUND_BLUR_DEGREE blur_degree; @@ -5981,67 +5474,21 @@ struct VirtualBackgroundSource { blur_degree(BLUR_DEGREE_HIGH) {} }; -/** - * @brief Processing properties for background images. - */ struct SegmentationProperty { - /** - * @brief The type of algorithms to user for background processing. - */ enum SEG_MODEL_TYPE { - /** - * 1: (Default) Use the algorithm suitable for all scenarios. - */ + SEG_MODEL_AI = 1, - /** - * 2: Use the algorithm designed specifically for scenarios with a green screen background. - */ SEG_MODEL_GREEN = 2 }; - /** - * @brief Screen color type. - */ - enum SCREEN_COLOR_TYPE { - /** - * (0): Automatically selects screen color. - */ - SCREEN_COLOR_AUTO = 0, - /** - * (1): Green screen. - */ - SCREEN_COLOR_GREEN = 1, - /** - * (2): Blue screen. - */ - SCREEN_COLOR_BLUE = 2 - }; - - /** - * The type of algorithms to user for background processing. See `SEG_MODEL_TYPE`. - */ SEG_MODEL_TYPE modelType; - /** - * The accuracy range for recognizing background colors in the image. The value range is [0,1], and - * the default value is 0.5. The larger the value, the wider the range of identifiable shades of - * pure color. When the value of this parameter is too large, the edge of the portrait and the pure - * color in the portrait range are also detected. Agora recommends that you dynamically adjust the - * value of this parameter according to the actual effect. - * @note This parameter only takes effect when `modelType` is set to `SEG_MODEL_GREEN`. - */ float greenCapacity; - /** - * The screen color. See `SCREEN_COLOR_TYPE`. - */ - SCREEN_COLOR_TYPE screenColorType; - - SegmentationProperty() : modelType(SEG_MODEL_AI), greenCapacity(0.5), screenColorType(SCREEN_COLOR_AUTO) {} + SegmentationProperty() : modelType(SEG_MODEL_AI), greenCapacity(0.5) {} }; -/** - * @brief The type of the audio track. +/** The type of custom audio track */ enum AUDIO_TRACK_TYPE { /** @@ -6049,39 +5496,33 @@ enum AUDIO_TRACK_TYPE { */ AUDIO_TRACK_INVALID = -1, /** - * 0: Mixable audio tracks. This type of audio track supports mixing with other audio streams (such - * as audio streams captured by microphone) and playing locally or publishing to channels after - * mixing. The latency of mixable audio tracks is higher than that of direct audio tracks. + * 0: Mixable audio track + * You can push more than one mixable Audio tracks into one RTC connection(channel id + uid), + * and SDK will mix these tracks into one audio track automatically. + * However, compare to direct audio track, mixable track might cause extra 30ms+ delay. */ AUDIO_TRACK_MIXABLE = 0, /** - * 1: Direct audio tracks. This type of audio track will replace the audio streams captured by the - * microphone and does not support mixing with other audio streams. The latency of direct audio - * tracks is lower than that of mixable audio tracks. - * @note If `AUDIO_TRACK_DIRECT` is specified for this parameter, you must set - * `publishMicrophoneTrack` to `false` in `ChannelMediaOptions` when calling `joinChannel(const - * char* token, const char* channelId, uid_t uid, const ChannelMediaOptions& options)` to - * join the channel; otherwise, joining the channel fails and returns the error code -2. + * 1: Direct audio track + * You can only push one direct (non-mixable) audio track into one RTC connection(channel id + + * uid). Compare to mixable stream, you can have lower lantency using direct audio track. */ AUDIO_TRACK_DIRECT = 1, }; -/** - * @brief The configuration of custom audio tracks. +/** The configuration of custom audio track */ struct AudioTrackConfig { /** - * Whether to enable the local audio-playback device: - * - `true`: (Default) Enable the local audio-playback device. - * - `false`: Do not enable the local audio-playback device. + * Enable local playback, enabled by default + * true: (Default) Enable local playback + * false: Do not enable local playback */ bool enableLocalPlayback; /** - * Whether to enable audio processing module: - * - `true`Enable the audio processing module to apply the Automatic Echo Cancellation (AEC), - * Automatic Noise Suppression (ANS), and Automatic Gain Control (AGC) effects. - * - `false`: (Default) Do not enable the audio processing module. - * @note This parameter only takes effect on AUDIO_TRACK_DIRECT in custom audio capturing. + * Whether to enable APM (AEC/ANS/AGC) processing when the trackType is AUDIO_TRACK_DIRECT. + * false: (Default) Do not enable APM processing. + * true: Enable APM processing. */ bool enableAudioProcessing; @@ -6106,199 +5547,213 @@ struct AudioTrackConfig { * | |--------------------|-----------------------------| | | * | | 0x3: voice changer | 0x1: voice transform | | | */ -/** - * @brief The options for SDK preset voice beautifier effects. +/** The options for SDK preset voice beautifier effects. */ enum VOICE_BEAUTIFIER_PRESET { - /** - * Turn off voice beautifier effects and use the original voice. + /** Turn off voice beautifier effects and use the original voice. */ VOICE_BEAUTIFIER_OFF = 0x00000000, - /** - * A more magnetic voice. - * @note Agora recommends using this enumerator to process a male-sounding voice; otherwise, you may - * experience vocal distortion. + /** A more magnetic voice. + * + * @note Agora recommends using this enumerator to process a male-sounding voice; otherwise, you + * may experience vocal distortion. */ CHAT_BEAUTIFIER_MAGNETIC = 0x01010100, - /** - * A fresher voice. + /** A fresher voice. + * * @note Agora recommends using this enumerator to process a female-sounding voice; otherwise, you * may experience vocal distortion. */ CHAT_BEAUTIFIER_FRESH = 0x01010200, - /** - * A more vital voice. + /** A more vital voice. + * * @note Agora recommends using this enumerator to process a female-sounding voice; otherwise, you * may experience vocal distortion. */ CHAT_BEAUTIFIER_VITALITY = 0x01010300, /** * Singing beautifier effect. - * - If you call `setVoiceBeautifierPreset` ( SINGING_BEAUTIFIER ), you can beautify a male-sounding + * - If you call `setVoiceBeautifierPreset`(SINGING_BEAUTIFIER), you can beautify a male-sounding * voice and add a reverberation effect that sounds like singing in a small room. Agora recommends - * using this enumerator to process a male-sounding voice; otherwise, you might experience vocal - * distortion. - * - If you call `setVoiceBeautifierParameters` ( SINGING_BEAUTIFIER, param1, param2), you can - * beautify a male or female-sounding voice and add a reverberation effect. + * not using `setVoiceBeautifierPreset`(SINGING_BEAUTIFIER) to process a female-sounding voice; + * otherwise, you may experience vocal distortion. + * - If you call `setVoiceBeautifierParameters`(SINGING_BEAUTIFIER, param1, param2), you can + * beautify a male- or female-sounding voice and add a reverberation effect. */ SINGING_BEAUTIFIER = 0x01020100, - /** - * A more vigorous voice. + /** A more vigorous voice. */ TIMBRE_TRANSFORMATION_VIGOROUS = 0x01030100, - /** - * A deep voice. + /** A deeper voice. */ TIMBRE_TRANSFORMATION_DEEP = 0x01030200, - /** - * A mellower voice. + /** A mellower voice. */ TIMBRE_TRANSFORMATION_MELLOW = 0x01030300, - /** - * Falsetto. + /** A falsetto voice. */ TIMBRE_TRANSFORMATION_FALSETTO = 0x01030400, - /** - * A fuller voice. + /** A fuller voice. */ TIMBRE_TRANSFORMATION_FULL = 0x01030500, - /** - * A clearer voice. + /** A clearer voice. */ TIMBRE_TRANSFORMATION_CLEAR = 0x01030600, - /** - * A more resounding voice. + /** A more resounding voice. */ TIMBRE_TRANSFORMATION_RESOUNDING = 0x01030700, - /** - * A more ringing voice. + /** A more ringing voice. */ TIMBRE_TRANSFORMATION_RINGING = 0x01030800, /** * A ultra-high quality voice, which makes the audio clearer and restores more details. - * - To achieve better audio effect quality, Agora recommends that you set the `profile` of - * `setAudioProfile(AUDIO_PROFILE_TYPE profile)` to `AUDIO_PROFILE_MUSIC_HIGH_QUALITY` (4) or - * `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO` (5) and `scenario` to `AUDIO_SCENARIO_GAME_STREAMING` - * (3) before calling `setVoiceBeautifierPreset`. - * - If you have an audio capturing device that can already restore audio details to a high degree, - * Agora recommends that you do not enable ultra-high quality; otherwise, the SDK may over-restore - * audio details, and you may not hear the anticipated voice effect. + * - To achieve better audio effect quality, Agora recommends that you call `setAudioProfile` + * and set the `profile` to `AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4)` or + * `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)` and `scenario` to + * `AUDIO_SCENARIO_HIGH_DEFINITION(6)` before calling `setVoiceBeautifierPreset`. + * - If you have an audio capturing device that can already restore audio details to a high + * degree, Agora recommends that you do not enable ultra-high quality; otherwise, the SDK may + * over-restore audio details, and you may not hear the anticipated voice effect. */ ULTRA_HIGH_QUALITY_VOICE = 0x01040100 }; -/** - * @brief Preset audio effects. +/** Preset voice effects. * - * @details - * To get better audio effects, Agora recommends calling `setAudioProfile(AUDIO_PROFILE_TYPE profile, AUDIO_SCENARIO_TYPE scenario)` and setting the `profile` parameter as recommended below before using the preset audio effects. - * | Preset audio effects | `profile` | - * | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | - * | - ROOM_ACOUSTICS_VIRTUAL_STEREO - ROOM_ACOUSTICS_3D_VOICE - ROOM_ACOUSTICS_VIRTUAL_SURROUND_SOUND | `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO` or `AUDIO_PROFILE_MUSIC_STANDARD_STEREO` | - * | Other preset audio effects (except for `AUDIO_EFFECT_OFF` ) | `AUDIO_PROFILE_MUSIC_HIGH_QUALITY` or `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO` | + * For better voice effects, Agora recommends setting the `profile` parameter of `setAudioProfile` + * to `AUDIO_PROFILE_MUSIC_HIGH_QUALITY` or `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO` before using + * the following presets: * + * - `ROOM_ACOUSTICS_KTV` + * - `ROOM_ACOUSTICS_VOCAL_CONCERT` + * - `ROOM_ACOUSTICS_STUDIO` + * - `ROOM_ACOUSTICS_PHONOGRAPH` + * - `ROOM_ACOUSTICS_SPACIAL` + * - `ROOM_ACOUSTICS_ETHEREAL` + * - `ROOM_ACOUSTICS_CHORUS` + * - `VOICE_CHANGER_EFFECT_UNCLE` + * - `VOICE_CHANGER_EFFECT_OLDMAN` + * - `VOICE_CHANGER_EFFECT_BOY` + * - `VOICE_CHANGER_EFFECT_SISTER` + * - `VOICE_CHANGER_EFFECT_GIRL` + * - `VOICE_CHANGER_EFFECT_PIGKING` + * - `VOICE_CHANGER_EFFECT_HULK` + * - `PITCH_CORRECTION` */ enum AUDIO_EFFECT_PRESET { - /** - * Turn off voice effects, that is, use the original voice. + /** Turn off voice effects, that is, use the original voice. */ AUDIO_EFFECT_OFF = 0x00000000, - /** - * The voice effect typical of a KTV venue. + /** The voice effect typical of a KTV venue. */ ROOM_ACOUSTICS_KTV = 0x02010100, - /** - * The voice effect typical of a concert hall. + /** The voice effect typical of a concert hall. */ ROOM_ACOUSTICS_VOCAL_CONCERT = 0x02010200, - /** - * The voice effect typical of a recording studio. + /** The voice effect typical of a recording studio. */ ROOM_ACOUSTICS_STUDIO = 0x02010300, - /** - * The voice effect typical of a vintage phonograph. + /** The voice effect typical of a vintage phonograph. */ ROOM_ACOUSTICS_PHONOGRAPH = 0x02010400, - /** - * The virtual stereo effect, which renders monophonic audio as stereo audio. + /** The virtual stereo effect, which renders monophonic audio as stereo audio. + * + * @note Before using this preset, set the `profile` parameter of `setAudioProfile` + * to `AUDIO_PROFILE_MUSIC_STANDARD_STEREO(3)` or `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)`; + * otherwise, the preset setting is invalid. */ ROOM_ACOUSTICS_VIRTUAL_STEREO = 0x02010500, - /** - * A more spatial voice effect. + /** A more spatial voice effect. */ ROOM_ACOUSTICS_SPACIAL = 0x02010600, - /** - * A more ethereal voice effect. + /** A more ethereal voice effect. */ ROOM_ACOUSTICS_ETHEREAL = 0x02010700, - /** - * A 3D voice effect that makes the voice appear to be moving around the user. The default cycle - * period is 10 seconds. After setting this effect, you can call `setAudioEffectParameters` to - * modify the movement period. - * @note If the 3D voice effect is enabled, users need to use stereo audio playback devices to hear + /** A 3D voice effect that makes the voice appear to be moving around the user. The default cycle + * period of the 3D voice effect is 10 seconds. To change the cycle period, call + * `setAudioEffectParameters` after this method. + * + * @note + * - Before using this preset, set the `profile` parameter of `setAudioProfile` to + * `AUDIO_PROFILE_MUSIC_STANDARD_STEREO` or `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO`; otherwise, + * the preset setting is invalid. + * - If the 3D voice effect is enabled, users need to use stereo audio playback devices to hear * the anticipated voice effect. */ ROOM_ACOUSTICS_3D_VOICE = 0x02010800, - /** - * Virtual surround sound, that is, the SDK generates a simulated surround sound field on the basis - * of stereo channels, thereby creating a surround sound effect. - * @note If the virtual surround sound is enabled, users need to use stereo audio playback devices - * to hear the anticipated audio effect. + /** virtual suround sound. + * + * @note + * - Agora recommends using this enumerator to process virtual suround sound; otherwise, you may + * not hear the anticipated voice effect. + * - To achieve better audio effect quality, Agora recommends calling \ref + * IRtcEngine::setAudioProfile "setAudioProfile" and setting the `profile` parameter to + * `AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4)` or `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)` before + * setting this enumerator. */ ROOM_ACOUSTICS_VIRTUAL_SURROUND_SOUND = 0x02010900, - /** - * The audio effect of chorus. Agora recommends using this effect in chorus scenarios to enhance the - * sense of depth and dimension in the vocals. + /** The voice effect for chorus. + * + * @note: To achieve better audio effect quality, Agora recommends calling \ref + * IRtcEngine::setAudioProfile "setAudioProfile" and setting the `profile` parameter to + * `AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4)` or `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)` before + * setting this enumerator. */ ROOM_ACOUSTICS_CHORUS = 0x02010D00, - /** - * A middle-aged man's voice. - * @note Agora recommends using this preset to process a male-sounding voice; otherwise, you may not - * hear the anticipated voice effect. + /** A middle-aged man's voice. + * + * @note + * Agora recommends using this enumerator to process a male-sounding voice; otherwise, you may + * not hear the anticipated voice effect. */ VOICE_CHANGER_EFFECT_UNCLE = 0x02020100, - /** - * An older man's voice. - * @note Agora recommends using this preset to process a male-sounding voice; otherwise, you may not - * hear the anticipated voice effect. + /** A senior man's voice. + * + * @note Agora recommends using this enumerator to process a male-sounding voice; otherwise, you + * may not hear the anticipated voice effect. */ VOICE_CHANGER_EFFECT_OLDMAN = 0x02020200, - /** - * A boy's voice. - * @note Agora recommends using this preset to process a male-sounding voice; otherwise, you may not - * hear the anticipated voice effect. + /** A boy's voice. + * + * @note Agora recommends using this enumerator to process a male-sounding voice; otherwise, you + * may not hear the anticipated voice effect. */ VOICE_CHANGER_EFFECT_BOY = 0x02020300, - /** - * A young woman's voice. - * @note Agora recommends using this preset to process a female-sounding voice; otherwise, you may + /** A young woman's voice. + * + * @note + * - Agora recommends using this enumerator to process a female-sounding voice; otherwise, you may * not hear the anticipated voice effect. */ VOICE_CHANGER_EFFECT_SISTER = 0x02020400, - /** - * A girl's voice. - * @note Agora recommends using this preset to process a female-sounding voice; otherwise, you may - * not hear the anticipated voice effect. + /** A girl's voice. + * + * @note Agora recommends using this enumerator to process a female-sounding voice; otherwise, you + * may not hear the anticipated voice effect. */ VOICE_CHANGER_EFFECT_GIRL = 0x02020500, - /** - * The voice of Pig King, a character in Journey to the West who has a voice like a growling bear. + /** The voice of Pig King, a character in Journey to the West who has a voice like a growling + * bear. */ VOICE_CHANGER_EFFECT_PIGKING = 0x02020600, - /** - * The Hulk's voice. + /** The Hulk's voice. */ VOICE_CHANGER_EFFECT_HULK = 0x02020700, - /** - * The voice effect typical of R&B music. + /** An audio effect typical of R&B music. + * + * @note Before using this preset, set the `profile` parameter of `setAudioProfile` to + - `AUDIO_PROFILE_MUSIC_HIGH_QUALITY` or `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO`; otherwise, + * the preset setting is invalid. */ STYLE_TRANSFORMATION_RNB = 0x02030100, - /** - * The voice effect typical of popular music. + /** The voice effect typical of popular music. + * + * @note Before using this preset, set the `profile` parameter of `setAudioProfile` to + - `AUDIO_PROFILE_MUSIC_HIGH_QUALITY` or `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO`; otherwise, + * the preset setting is invalid. */ STYLE_TRANSFORMATION_POPULAR = 0x02030200, - /** - * A pitch correction effect that corrects the user's pitch based on the pitch of the natural C + /** A pitch correction effect that corrects the user's pitch based on the pitch of the natural C * major scale. After setting this voice effect, you can call `setAudioEffectParameters` to adjust * the basic mode of tuning and the pitch of the main tone. */ @@ -6309,31 +5764,25 @@ enum AUDIO_EFFECT_PRESET { */ }; -/** - * @brief The options for SDK preset voice conversion effects. +/** The options for SDK preset voice conversion. */ enum VOICE_CONVERSION_PRESET { - /** - * Turn off voice conversion effects and use the original voice. + /** Turn off voice conversion and use the original voice. */ VOICE_CONVERSION_OFF = 0x00000000, - /** - * A gender-neutral voice. To avoid audio distortion, ensure that you use this enumerator to process - * a female-sounding voice. + /** A gender-neutral voice. To avoid audio distortion, ensure that you use this enumerator to + * process a female-sounding voice. */ VOICE_CHANGER_NEUTRAL = 0x03010100, - /** - * A sweet voice. To avoid audio distortion, ensure that you use this enumerator to process a + /** A sweet voice. To avoid audio distortion, ensure that you use this enumerator to process a * female-sounding voice. */ VOICE_CHANGER_SWEET = 0x03010200, - /** - * A steady voice. To avoid audio distortion, ensure that you use this enumerator to process a + /** A steady voice. To avoid audio distortion, ensure that you use this enumerator to process a * male-sounding voice. */ VOICE_CHANGER_SOLID = 0x03010300, - /** - * A deep voice. To avoid audio distortion, ensure that you use this enumerator to process a + /** A deep voice. To avoid audio distortion, ensure that you use this enumerator to process a * male-sounding voice. */ VOICE_CHANGER_BASS = 0x03010400, @@ -6373,95 +5822,74 @@ enum VOICE_CONVERSION_PRESET { }; -/** - * @brief Preset headphone equalizer types. +/** The options for SDK preset headphone equalizer. */ enum HEADPHONE_EQUALIZER_PRESET { - /** - * The headphone equalizer is disabled, and the original audio is heard. + /** Turn off headphone EQ and use the original voice. */ HEADPHONE_EQUALIZER_OFF = 0x00000000, - /** - * An equalizer is used for headphones. + /** For over-ear headphones. */ HEADPHONE_EQUALIZER_OVEREAR = 0x04000001, - /** - * An equalizer is used for in-ear headphones. + /** For in-ear headphones. */ HEADPHONE_EQUALIZER_INEAR = 0x04000002 }; -/** - * @brief Voice AI tuner sound types. +/** The options for SDK voice AI tuner. */ enum VOICE_AI_TUNER_TYPE { - /** - * 0: Mature male voice. A deep and magnetic male voice. + /** Uncle, deep and magnetic male voice. */ VOICE_AI_TUNER_MATURE_MALE, - /** - * 1: Fresh male voice. A fresh and slightly sweet male voice. + /** Fresh male, refreshing and sweet male voice. */ VOICE_AI_TUNER_FRESH_MALE, - /** - * 2: Elegant female voice. A deep and charming female voice. + /** Big sister, deep and charming female voice. */ VOICE_AI_TUNER_ELEGANT_FEMALE, - /** - * 3: Sweet female voice. A high-pitched and cute female voice. + /** Lolita, high-pitched and cute female voice. */ VOICE_AI_TUNER_SWEET_FEMALE, - /** - * 4: Warm male singing. A warm and melodious male voice. + /** Warm man singing, warm and melodic male voice that is suitable for male lyrical songs. */ VOICE_AI_TUNER_WARM_MALE_SINGING, - /** - * 5: Gentle female singing. A soft and delicate female voice. + /** Gentle female singing, soft and delicate female voice that is suitable for female lyrical songs. */ VOICE_AI_TUNER_GENTLE_FEMALE_SINGING, - /** - * 6: Husky male singing. A unique husky male voice. + /** Smoky uncle singing, unique husky male voice that is suitable for rock or blues songs. */ VOICE_AI_TUNER_HUSKY_MALE_SINGING, - /** - * 7: Warm elegant female singing. A warm and mature female voice. + /** Warm big sister singing, warm and mature female voice that is suitable for emotionally powerful songs. */ VOICE_AI_TUNER_WARM_ELEGANT_FEMALE_SINGING, - /** - * 8: Powerful male singing. A strong and powerful male voice. + /** Forceful male singing, strong and powerful male voice that is suitable for passionate songs. */ VOICE_AI_TUNER_POWERFUL_MALE_SINGING, - /** - * 9: Dreamy female singing. A dreamy and soft female voice. + /** Dreamy female singing, dreamlike and soft female voice that is suitable for airy and dream-like songs. */ VOICE_AI_TUNER_DREAMY_FEMALE_SINGING, }; /** - * @brief The audio configuration for the shared screen stream. - * - * @details - * Only available where `captureAudio` is `true`. - * + * The audio configuration for the shared screen stream. */ struct ScreenAudioParameters { /** - * Audio sample rate (Hz). + * The audio sample rate (Hz). The default value is `48000`. */ int sampleRate; /** - * The number of audio channels. The default value is 2, which means stereo. + * The number of audio channels. The default value is `2`, indicating dual channels. */ int channels; /** - * The volume of the captured system audio. The value range is [0, 100]. The default value is 100. + * The volume of the captured system audio. The value range is [0,100]. The default value is + * `100`. */ int captureSignalVolume; #if defined(__APPLE__) && !TARGET_OS_IOS - /** - * @technical preview - */ bool excludeCurrentProcessAudio = true; ScreenAudioParameters(): sampleRate(48000), channels(2), captureSignalVolume(100) {} #else @@ -6470,7 +5898,7 @@ struct ScreenAudioParameters { }; /** - * @brief Screen sharing configurations. + * Screen sharing configurations. */ struct ScreenCaptureParameters { @@ -6479,60 +5907,45 @@ struct ScreenCaptureParameters { * - `true`: Capture. * - `false`: (Default) Do not capture. * - * @note + * **Note** * Due to system limitations, capturing system audio is only available for Android API level 29 * and later (that is, Android 10 and later). */ bool captureAudio; /** * The audio configuration for the shared screen stream. - * @note This parameter only takes effect when `captureAudio` is `true`. - * See `ScreenAudioParameters`. */ ScreenAudioParameters audioParams; /** - * The video encoding resolution of the screen sharing stream. See `VideoDimensions`. The default - * value is 1920 × 1080, that is, 2,073,600 pixels. Agora uses the value of this parameter to - * calculate the charges. - * If the screen dimensions are different from the value of this parameter, Agora applies the - * following strategies for encoding. Suppose `dimensions` is set to 1920 × 1080: - * - If the value of the screen dimensions is lower than that of `dimensions`, for example, 1000 × - * 1000 pixels, the SDK uses the screen dimensions, that is, 1000 × 1000 pixels, for encoding. - * - If the value of the screen dimensions is higher than that of `dimensions`, for example, 2000 × - * 1500, the SDK uses the maximum value under `dimensions` with the aspect ratio of the screen - * dimension (4:3) for encoding, that is, 1440 × 1080. - * @note - * When setting the encoding resolution in the scenario of sharing documents ( - * SCREEN_SCENARIO_DOCUMENT ), choose one of the following two methods: - * - If you require the best image quality, it is recommended to set the encoding resolution to be - * the same as the capture resolution. - * - If you wish to achieve a relative balance between image quality, bandwidth, and system - * performance, then: - * - When the capture resolution is greater than 1920 × 1080, it is recommended that the encoding - * resolution is not less than 1920 × 1080. - * - When the capture resolution is less than 1920 × 1080, it is recommended that the encoding - * resolution is not less than 1280 × 720. + * On Windows and macOS, it represents the video encoding resolution of the shared screen stream. + * See `VideoDimensions`. The default value is 1920 x 1080, that is, 2,073,600 pixels. Agora uses + * the value of this parameter to calculate the charges. + * + * If the aspect ratio is different between the encoding dimensions and screen dimensions, Agora + * applies the following algorithms for encoding. Suppose dimensions are 1920 x 1080: + * - If the value of the screen dimensions is lower than that of dimensions, for example, + * 1000 x 1000 pixels, the SDK uses 1000 x 1000 pixels for encoding. + * - If the value of the screen dimensions is higher than that of dimensions, for example, + * 2000 x 1500, the SDK uses the maximum value under dimensions with the aspect ratio of + * the screen dimension (4:3) for encoding, that is, 1440 x 1080. */ VideoDimensions dimensions; /** - * On Windows and macOS, this represents the video encoding frame rate (fps) of the screen sharing - * stream. The frame rate (fps) of the shared region. The default value is 5. Agora does not - * recommend setting this to a value greater than 15. + * On Windows and macOS, it represents the video encoding frame rate (fps) of the shared screen + * stream. The frame rate (fps) of the shared region. The default value is 5. We do not recommend + * setting this to a value greater than 15. */ int frameRate; /** - * On Windows and macOS, this represents the video encoding bitrate of the screen sharing stream. + * On Windows and macOS, it represents the video encoding bitrate of the shared screen stream. * The bitrate (Kbps) of the shared region. The default value is 0 (the SDK works out a bitrate * according to the dimensions of the current screen). */ int bitrate; - /** - * Whether to capture the mouse in screen sharing: + /** Whether to capture the mouse in screen sharing: * - `true`: (Default) Capture the mouse. * - `false`: Do not capture the mouse. - * @note Due to macOS system restrictions, setting this parameter to `false` is ineffective during - * screen sharing (it has no impact when sharing a window). */ bool captureMouseCursor; /** @@ -6540,42 +5953,35 @@ struct ScreenCaptureParameters { * to share it: * - `true`: Bring the window to the front. * - `false`: (Default) Do not bring the window to the front. - * @note Due to macOS system limitations, when setting this member to bring the window to the front, - * if the current app has multiple windows, only the main window will be brought to the front. */ bool windowFocus; /** - * The ID list of the windows to be blocked. When calling `startScreenCaptureByDisplayId` to start + * A list of IDs of windows to be blocked. When calling `startScreenCaptureByDisplayId` to start * screen sharing, you can use this parameter to block a specified window. When calling * `updateScreenCaptureParameters` to update screen sharing configurations, you can use this - * parameter to dynamically block a specified window. + * parameter to dynamically block the specified windows during screen sharing. */ view_t* excludeWindowList; /** - * The number of windows to be excluded. - * @note On the Windows platform, the maximum value of this parameter is 24; if this value is - * exceeded, excluding the window fails. + * The number of windows to be blocked. */ int excludeWindowCount; - /** - * (For macOS and Windows only) The width (px) of the border. The default value is 5, and the value - * range is (0, 50]. - * @note This parameter only takes effect when `highLighted` is set to `true`. + /** The width (px) of the border. Defaults to 0, and the value range is [0,50]. + * */ int highLightWidth; - /** - * (For macOS and Windows only) - * - On Windows platforms, the color of the border in ARGB format. The default value is 0xFF8CBF26. - * - On macOS, `COLOR_CLASS` refers to `NSColor`. + /** The color of the border in RGBA format. The default value is 0xFF8CBF26. + * */ unsigned int highLightColor; - /** - * (For macOS and Windows only) Whether to place a border around the shared window or screen: - * - `true`: Place a border. - * - `false`: (Default) Do not place a border. + /** Whether to place a border around the shared window or screen: + * - true: Place a border. + * - false: (Default) Do not place a border. + * * @note When you share a part of a window or screen, the SDK places a border around the entire - * window or screen if you set this parameter to `true`. + * window or screen if you set `enableHighLight` as true. + * */ bool enableHighLight; @@ -6654,12 +6060,12 @@ struct ScreenCaptureParameters { }; /** - * @brief Recording quality. + * Audio recording quality. */ 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. The sample rate is 32 kHz, and the file size is around 1.2 MB after 10 minutes + * of recording. */ AUDIO_RECORDING_QUALITY_LOW = 0, /** @@ -6668,19 +6074,18 @@ enum AUDIO_RECORDING_QUALITY_TYPE { */ 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. The sample rate is 32 kHz, and the file size is around 3.75 MB after 10 + * minutes of recording. */ AUDIO_RECORDING_QUALITY_HIGH = 2, /** - * 3: Ultra high quality. The sample rate is 32 kHz, and the file size is around 7.5 MB after 10 - * minutes of recording. + * 3: Ultra high audio recording quality. */ AUDIO_RECORDING_QUALITY_ULTRA_HIGH = 3, }; /** - * @brief Recording content. Set in `startAudioRecording [3/3]`. + * Recording content. Set in `startAudioRecording`. */ enum AUDIO_FILE_RECORDING_TYPE { /** @@ -6698,7 +6103,7 @@ enum AUDIO_FILE_RECORDING_TYPE { }; /** - * @brief Audio profile. + * Audio encoded frame observer position. */ enum AUDIO_ENCODED_FRAME_OBSERVER_POSITION { /** @@ -6716,12 +6121,12 @@ enum AUDIO_ENCODED_FRAME_OBSERVER_POSITION { }; /** - * @brief Recording configurations. + * Recording configuration. */ struct AudioRecordingConfiguration { /** * The absolute path (including the filename extensions) of the recording file. For example: - * `C:\music\audio.aac`. + * `C:\music\audio.mp4`. * @note Ensure that the directory for the log files exists and is writable. */ const char* filePath; @@ -6738,7 +6143,7 @@ struct AudioRecordingConfiguration { * - 44100 * - 48000 * @note If you set this parameter to 44100 or 48000, Agora recommends recording WAV files, or AAC - * files with `quality` set as AUDIO_RECORDING_QUALITY_MEDIUM or AUDIO_RECORDING_QUALITY_HIGH for + * files with quality to be `AUDIO_RECORDING_QUALITY_MEDIUM` or `AUDIO_RECORDING_QUALITY_HIGH` for * better recording quality. */ int sampleRate; @@ -6753,17 +6158,9 @@ struct AudioRecordingConfiguration { AUDIO_RECORDING_QUALITY_TYPE quality; /** - * The audio channel of recording: The parameter supports the following values: - * - 1: (Default) Mono. - * - 2: Stereo. - * @note - * The actual recorded audio channel is related to the audio channel that you capture. - * - If the captured audio is mono and `recordingChannel` is `2`, the recorded audio is the - * dual-channel data that is copied from mono data, not stereo. - * - If the captured audio is dual channel and `recordingChannel` is `1`, the recorded audio is the - * mono data that is mixed by dual-channel data. - * The integration scheme also affects the final recorded audio channel. If you need to record in - * stereo, contact `technical support`. + * Recording channel. The following values are supported: + * - (Default) 1 + * - 2 */ int recordingChannel; @@ -6804,15 +6201,15 @@ struct AudioRecordingConfiguration { }; /** - * @brief Observer settings for the encoded audio. + * Observer settings for the encoded audio. */ struct AudioEncodedFrameObserverConfig { /** - * Audio profile. See `AUDIO_ENCODED_FRAME_OBSERVER_POSITION`. + * Audio profile. For details, see `AUDIO_ENCODED_FRAME_OBSERVER_POSITION`. */ AUDIO_ENCODED_FRAME_OBSERVER_POSITION postionType; /** - * Audio encoding type. See `AUDIO_ENCODING_TYPE`. + * Audio encoding type. For details, see `AUDIO_ENCODING_TYPE`. */ AUDIO_ENCODING_TYPE encodingType; @@ -6826,49 +6223,46 @@ struct AudioEncodedFrameObserverConfig { class IAudioEncodedFrameObserver { public: /** - * @brief Gets the encoded audio data of the local user. + * Gets the encoded audio data of the local user. * - * @details * After calling `registerAudioEncodedFrameObserver` and setting the encoded audio as - * AUDIO_ENCODED_FRAME_OBSERVER_POSITION_RECORD, you can get the encoded audio data of the local + * `AUDIO_ENCODED_FRAME_OBSERVER_POSITION_RECORD`, you can get the encoded audio data of the local * user from this callback. * - * @param frameBuffer The audio buffer. - * @param length The data length (byte). - * @param audioEncodedFrameInfo Audio information after encoding. See `EncodedAudioFrameInfo`. - * + * @param frameBuffer The pointer to the audio frame buffer. + * @param length The data length (byte) of the audio frame. + * @param audioEncodedFrameInfo Audio information after encoding. For details, see + * `EncodedAudioFrameInfo`. */ virtual void onRecordAudioEncodedFrame(const uint8_t* frameBuffer, int length, const EncodedAudioFrameInfo& audioEncodedFrameInfo) = 0; /** - * @brief Gets the encoded audio data of all remote users. + * Gets the encoded audio data of all remote users. * - * @details * After calling `registerAudioEncodedFrameObserver` and setting the encoded audio as - * AUDIO_ENCODED_FRAME_OBSERVER_POSITION_PLAYBACK, you can get encoded audio data of all remote + * `AUDIO_ENCODED_FRAME_OBSERVER_POSITION_PLAYBACK`, you can get encoded audio data of all remote * users through this callback. * - * @param frameBuffer The audio buffer. - * @param length The data length (byte). - * @param audioEncodedFrameInfo Audio information after encoding. See `EncodedAudioFrameInfo`. - * + * @param frameBuffer The pointer to the audio frame buffer. + * @param length The data length (byte) of the audio frame. + * @param audioEncodedFrameInfo Audio information after encoding. For details, see + * `EncodedAudioFrameInfo`. */ virtual void onPlaybackAudioEncodedFrame(const uint8_t* frameBuffer, int length, const EncodedAudioFrameInfo& audioEncodedFrameInfo) = 0; /** - * @brief Gets the mixed and encoded audio data of the local and all remote users. + * Gets the mixed and encoded audio data of the local and all remote users. * - * @details * After calling `registerAudioEncodedFrameObserver` and setting the audio profile as - * AUDIO_ENCODED_FRAME_OBSERVER_POSITION_MIXED, you can get the mixed and encoded audio data of the - * local and all remote users through this callback. - * - * @param frameBuffer The audio buffer. - * @param length The data length (byte). - * @param audioEncodedFrameInfo Audio information after encoding. See `EncodedAudioFrameInfo`. + * `AUDIO_ENCODED_FRAME_OBSERVER_POSITION_MIXED`, you can get the mixed and encoded audio data of + * the local and all remote users through this callback. * + * @param frameBuffer The pointer to the audio frame buffer. + * @param length The data length (byte) of the audio frame. + * @param audioEncodedFrameInfo Audio information after encoding. For details, see + * `EncodedAudioFrameInfo`. */ virtual void onMixedAudioEncodedFrame(const uint8_t* frameBuffer, int length, const EncodedAudioFrameInfo& audioEncodedFrameInfo) = 0; @@ -6876,9 +6270,7 @@ class IAudioEncodedFrameObserver { virtual ~IAudioEncodedFrameObserver() {} }; -/** - * @brief The region for connection, which is the region where the server the SDK connects to is - * located. +/** The region for connection, which is the region where the server the SDK connects to is located. */ enum AREA_CODE { /** @@ -6906,7 +6298,7 @@ enum AREA_CODE { */ AREA_CODE_IN = 0x00000020, /** - * Global. + * (Default) Global. */ AREA_CODE_GLOB = (0xFFFFFFFF) }; @@ -6951,102 +6343,83 @@ enum AREA_CODE_EX { }; /** - * @brief The error code of the channel media relay. + * The error code of the channel media replay. */ enum CHANNEL_MEDIA_RELAY_ERROR { - /** - * 0: No error. + /** 0: No error. */ RELAY_OK = 0, - /** - * 1: An error occurs in the server response. + /** 1: An error occurs in the server response. */ RELAY_ERROR_SERVER_ERROR_RESPONSE = 1, - /** - * 2: No server response. - * This error may be caused by poor network connections. If this error occurs when initiating a - * channel media relay, you can try again later; if this error occurs during channel media relay, - * you can call `leaveChannel(const LeaveChannelOptions& options)` to leave the channel. - * This error can also occur if the channel media relay service is not enabled in the project. You - * can contact `technical support` to enable the service. + /** 2: No server response. You can call the `leaveChannel` method to leave the channel. + * + * This error can also occur if your project has not enabled co-host token authentication. You can + * contact technical support to enable the service for cohosting across channels before starting a + * channel media relay. */ RELAY_ERROR_SERVER_NO_RESPONSE = 2, - /** - * 3: The SDK fails to access the service, probably due to limited resources of the server. + /** 3: The SDK fails to access the service, probably due to limited resources of the server. */ RELAY_ERROR_NO_RESOURCE_AVAILABLE = 3, - /** - * 4: Fails to send the relay request. + /** 4: Fails to send the relay request. */ RELAY_ERROR_FAILED_JOIN_SRC = 4, - /** - * 5: Fails to accept the relay request. + /** 5: Fails to accept the relay request. */ RELAY_ERROR_FAILED_JOIN_DEST = 5, - /** - * 6: The server fails to receive the media stream. + /** 6: The server fails to receive the media stream. */ RELAY_ERROR_FAILED_PACKET_RECEIVED_FROM_SRC = 6, - /** - * 7: The server fails to send the media stream. + /** 7: The server fails to send the media stream. */ RELAY_ERROR_FAILED_PACKET_SENT_TO_DEST = 7, - /** - * 8: The SDK disconnects from the server due to poor network connections. You can call - * `leaveChannel(const LeaveChannelOptions& options)` to leave the channel. + /** 8: The SDK disconnects from the server due to poor network connections. You can call the + * `leaveChannel` method to leave the channel. */ RELAY_ERROR_SERVER_CONNECTION_LOST = 8, - /** - * 9: An internal error occurs in the server. + /** 9: An internal error occurs in the server. */ RELAY_ERROR_INTERNAL_ERROR = 9, - /** - * 10: The token of the source channel has expired. + /** 10: The token of the source channel has expired. */ RELAY_ERROR_SRC_TOKEN_EXPIRED = 10, - /** - * 11: The token of the destination channel has expired. + /** 11: The token of the destination channel has expired. */ RELAY_ERROR_DEST_TOKEN_EXPIRED = 11, }; /** - * @brief The state code of the channel media relay. + * The state code of the channel media relay. */ enum CHANNEL_MEDIA_RELAY_STATE { - /** - * 0: The initial state. After you successfully stop the channel media relay by calling + /** 0: The initial state. After you successfully stop the channel media relay by calling * `stopChannelMediaRelay`, the `onChannelMediaRelayStateChanged` callback returns this state. */ RELAY_STATE_IDLE = 0, - /** - * 1: The SDK tries to relay the media stream to the destination channel. + /** 1: The SDK tries to relay the media stream to the destination channel. */ RELAY_STATE_CONNECTING = 1, - /** - * 2: The SDK successfully relays the media stream to the destination channel. + /** 2: The SDK successfully relays the media stream to the destination channel. */ RELAY_STATE_RUNNING = 2, - /** - * 3: An error occurs. See `code` in `onChannelMediaRelayStateChanged` for the error code. + /** 3: An error occurs. See `code` in `onChannelMediaRelayStateChanged` for the error code. */ RELAY_STATE_FAILURE = 3, }; -/** - * @brief Channel media information. +/** The definition of ChannelMediaInfo. */ struct ChannelMediaInfo { - /** - * The user ID. + /** The user ID. */ uid_t uid; - /** - * The channel name. + /** The channel name. The default value is NULL, which means that the SDK + * applies the current channel name. */ const char* channelName; - /** - * The token that enables the user to join the channel. + /** The token that enables the user to join the channel. The default value + * is NULL, which means that the SDK applies the current token. */ const char* token; @@ -7054,45 +6427,41 @@ struct ChannelMediaInfo { ChannelMediaInfo(const char* c, const char* t, uid_t u) : uid(u), channelName(c), token(t) {} }; -/** - * @brief Configuration of cross channel media relay. +/** The definition of ChannelMediaRelayConfiguration. */ struct ChannelMediaRelayConfiguration { - /** - * The information of the source channel. See `ChannelMediaInfo`. It contains the following members: - * - `channelName`: The name of the source channel. The default value is `NULL`, which means the SDK - * applies the name of the current channel. - * - `token`: The `token` for joining the source channel. This token is generated with the - * `channelName` and `uid` you set in `srcInfo`. - * - If you have not enabled the App Certificate, set this parameter as the default value `NULL`, - * which means the SDK applies the App ID. - * - If you have enabled the App Certificate, you must use the `token` generated with the + /** The information of the source channel `ChannelMediaInfo`. It contains the following members: + * - `channelName`: The name of the source channel. The default value is `NULL`, which means the + * SDK applies the name of the current channel. + * - `uid`: The unique ID to identify the relay stream in the source channel. The default value is + * 0, which means the SDK generates a random UID. You must set it as 0. + * - `token`: The token for joining the source channel. It is generated with the `channelName` and + * `uid` you set in `srcInfo`. + * - If you have not enabled the App Certificate, set this parameter as the default value + * `NULL`, which means the SDK applies the App ID. + * - If you have enabled the App Certificate, you must use the token generated with the * `channelName` and `uid`, and the `uid` must be set as 0. - * - `uid`: The unique user ID to identify the relay stream in the source channel. Agora recommends - * leaving the default value of 0 unchanged. */ ChannelMediaInfo* srcInfo; - /** - * The information of the target channel `ChannelMediaInfo`. It contains the following members: - * - `channelName`: The name of the target channel. - * - `token`: The `token` for joining the target channel. It is generated with the `channelName` and - * `uid` you set in `destInfos`. - * - If you have not enabled the App Certificate, set this parameter as the default value `NULL`, + /** The information of the destination channel `ChannelMediaInfo`. It contains the following + * members: + * - `channelName`: The name of the destination channel. + * - `uid`: The unique ID to identify the relay stream in the destination channel. The value + * ranges from 0 to (2^32-1). To avoid UID conflicts, this `UID` must be different from any + * other `UID` in the destination channel. The default value is 0, which means the SDK generates + * a random `UID`. Do not set this parameter as the `UID` of the host in the destination channel, + * and ensure that this `UID` is different from any other `UID` in the channel. + * - `token`: The token for joining the destination channel. It is generated with the + * `channelName` and `uid` you set in `destInfos`. + * - If you have not enabled the App Certificate, set this parameter as the default value NULL, * which means the SDK applies the App ID. - * - If you have enabled the App Certificate, you must use the `token` generated with the + * If you have enabled the App Certificate, you must use the token generated with the * `channelName` and `uid`. - * - `uid`: The unique user ID to identify the relay stream in the target channel. The value ranges - * from 0 to (2 32-1). To avoid user ID conflicts, this user ID must be different from any other - * user ID in the target channel. The default value is 0, which means the SDK generates a random - * UID. - * @note If the token of any target channel expires, the whole media relay stops; hence Agora - * recommends that you specify the same expiration time for the tokens of all the target channels. */ ChannelMediaInfo* destInfos; - /** - * The number of target channels. The default value is 0, and the value range is from 0 to 6. Ensure - * that the value of this parameter corresponds to the number of `ChannelMediaInfo` structs you - * define in `destInfo`. + /** The number of destination channels. The default value is 0, and the value range is from 0 to + * 6. Ensure that the value of this parameter corresponds to the number of `ChannelMediaInfo` + * structs you define in `destInfo`. */ int destCount; @@ -7101,7 +6470,7 @@ struct ChannelMediaRelayConfiguration { }; /** - * @brief The uplink network information. + * The uplink network information. */ struct UplinkNetworkInfo { /** @@ -7232,82 +6601,66 @@ struct DownlinkNetworkInfo { }; /** - * @brief The built-in encryption mode. + * The built-in encryption mode. * - * @details * Agora recommends using AES_128_GCM2 or AES_256_GCM2 encrypted mode. These two modes support the * use of salt for higher security. - * */ enum ENCRYPTION_MODE { - /** - * 1: 128-bit AES encryption, XTS mode. + /** 1: 128-bit AES encryption, XTS mode. */ AES_128_XTS = 1, - /** - * 2: 128-bit AES encryption, ECB mode. + /** 2: 128-bit AES encryption, ECB mode. */ AES_128_ECB = 2, - /** - * 3: 256-bit AES encryption, XTS mode. + /** 3: 256-bit AES encryption, XTS mode. */ AES_256_XTS = 3, - /** - * 4: 128-bit SM4 encryption, ECB mode. + /** 4: 128-bit SM4 encryption, ECB mode. */ SM4_128_ECB = 4, - /** - * 5: 128-bit AES encryption, GCM mode. + /** 5: 128-bit AES encryption, GCM mode. */ AES_128_GCM = 5, - /** - * 6: 256-bit AES encryption, GCM mode. + /** 6: 256-bit AES encryption, GCM mode. */ AES_256_GCM = 6, - /** - * 7: (Default) 128-bit AES encryption, GCM mode. This encryption mode requires the setting of salt - * (`encryptionKdfSalt`). + /** 7: (Default) 128-bit AES encryption, GCM mode. This encryption mode requires the setting of + * salt (`encryptionKdfSalt`). */ AES_128_GCM2 = 7, - /** - * 8: 256-bit AES encryption, GCM mode. This encryption mode requires the setting of salt + /** 8: 256-bit AES encryption, GCM mode. This encryption mode requires the setting of salt * (`encryptionKdfSalt`). */ AES_256_GCM2 = 8, - /** - * Enumerator boundary. + /** Enumerator boundary. */ MODE_END, }; -/** - * @brief Built-in encryption configurations. - */ +/** Built-in encryption configurations. */ struct EncryptionConfig { /** - * The built-in encryption mode. See `ENCRYPTION_MODE`. Agora recommends using `AES_128_GCM2` or - * `AES_256_GCM2` encrypted mode. These two modes support the use of salt for higher security. + * The built-in encryption mode. See #ENCRYPTION_MODE. Agora recommends using `AES_128_GCM2` + * or `AES_256_GCM2` encrypted mode. These two modes support the use of salt for higher security. */ ENCRYPTION_MODE encryptionMode; /** * 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 `-2`. + * + * @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; /** * Salt, 32 bytes in length. Agora recommends that you use OpenSSL to generate salt on the server - * side. See Media Stream Encryption for details. - * @note This parameter takes effect only in `AES_128_GCM2` or `AES_256_GCM2` encrypted mode. In - * this case, ensure that this parameter is not `0`. + * side. + * + * @note This parameter takes effect only in `AES_128_GCM2` or `AES_256_GCM2` encrypted mode. + * In this case, ensure that this parameter is not 0. */ uint8_t encryptionKdfSalt[32]; - /** - * Whether to enable data stream encryption: - * - `true`: Enable data stream encryption. - * - `false`: (Default) Disable data stream encryption. - */ bool datastreamEncryptionEnabled; EncryptionConfig() @@ -7344,8 +6697,7 @@ struct EncryptionConfig { /// @endcond }; -/** - * @brief Encryption error type. +/** Encryption error type. */ enum ENCRYPTION_ERROR_TYPE { /** @@ -7353,21 +6705,21 @@ enum ENCRYPTION_ERROR_TYPE { */ ENCRYPTION_ERROR_INTERNAL_FAILURE = 0, /** - * 1: Media stream decryption error. Ensure that the receiver and the sender use the same encryption - * mode and key. + * 1: MediaStream decryption errors. Ensure that the receiver and the sender use the same + * encryption mode and key. */ ENCRYPTION_ERROR_DECRYPTION_FAILURE = 1, /** - * 2: Media stream encryption error. + * 2: MediaStream encryption errors. */ ENCRYPTION_ERROR_ENCRYPTION_FAILURE = 2, /** - * 3: Data stream decryption error. Ensure that the receiver and the sender use the same encryption - * mode and key. + * 3: DataStream decryption errors. Ensure that the receiver and the sender use the same + * encryption mode and key. */ ENCRYPTION_ERROR_DATASTREAM_DECRYPTION_FAILURE = 3, /** - * 4: Data stream encryption error. + * 4: DataStream encryption errors. */ ENCRYPTION_ERROR_DATASTREAM_ENCRYPTION_FAILURE = 4, }; @@ -7378,54 +6730,7 @@ enum UPLOAD_ERROR_REASON { UPLOAD_SERVER_ERROR = 2, }; -/** - * @brief Represents the error codes after calling `renewToken`. - * - * @since 4.6.0 - */ -enum RENEW_TOKEN_ERROR_CODE { - /** - * (0): Token updated successfully. - */ - RENEW_TOKEN_SUCCESS = 0, - /** - * (1): Token update failed due to an unknown server error. It is recommended to check the - * parameters used to generate the Token, regenerate the Token, and retry `renewToken`. - */ - RENEW_TOKEN_FAILURE = 1, - /** - * (2): Token update failed because the provided Token has expired. It is recommended to generate a - * new Token with a longer expiration time and retry `renewToken`. - */ - RENEW_TOKEN_TOKEN_EXPIRED = 2, - /** - * (3): Token update failed because the provided Token is invalid. Common reasons include: the - * project has enabled App Certificate in the Agora Console but did not use a Token when joining the - * channel; the uid specified in `joinChannel` is inconsistent with the uid used when generating the - * Token; the channel name specified in `joinChannel` is inconsistent with the one used when - * generating the Token. It is recommended to check the Token generation process, generate a new - * Token, and retry `renewToken`. - */ - RENEW_TOKEN_INVALID_TOKEN = 3, - /** - * (4): Token update failed because the channel name in the Token does not match the current - * channel. It is recommended to check the channel name, generate a new Token, and retry - * `renewToken`. - */ - RENEW_TOKEN_INVALID_CHANNEL_NAME = 4, - /** - * (5): Token update failed because the App ID in the Token does not match the current App ID. It is - * recommended to check the App ID, generate a new Token, and retry `renewToken`. - */ - RENEW_TOKEN_INCONSISTENT_APPID = 5, - /** - * (6): The previous Token update request was canceled due to a new request being initiated. - */ - RENEW_TOKEN_CANCELED_BY_NEW_REQUEST = 6, -}; - -/** - * @brief The type of the device permission. +/** The type of the device permission. */ enum PERMISSION_TYPE { /** @@ -7437,34 +6742,29 @@ enum PERMISSION_TYPE { */ CAMERA = 1, - /** - * (For Android only) 2: Permission for screen sharing. - */ SCREEN_CAPTURE = 2, }; /** - * @brief The subscribing state. + * The subscribing state. */ enum STREAM_SUBSCRIBE_STATE { /** - * 0: The initial publishing state after joining the channel. + * 0: The initial subscribing state after joining the channel. */ SUB_STATE_IDLE = 0, /** * 1: Fails to subscribe to the remote stream. Possible reasons: * - The remote user: - * - Calls `muteLocalAudioStream` (`true`) or `muteLocalVideoStream` (`true`) to stop sending - * local media stream. - * - Calls `disableAudio` or `disableVideo` to disable the local audio or video module. - * - Calls `enableLocalAudio` ( false ) or `enableLocalVideo` ( false ) to disable local audio or + * - Calls `muteLocalAudioStream(true)` or `muteLocalVideoStream(true)` to stop sending local + * media stream. + * - Calls `disableAudio` or `disableVideo `to disable the local audio or video module. + * - Calls `enableLocalAudio(false)` or `enableLocalVideo(false)` to disable the local audio or * video capture. * - The role of the remote user is audience. * - The local user calls the following methods to stop receiving remote streams: - * - Call `muteRemoteAudioStream` ( true ) or `muteAllRemoteAudioStreams` ( true ) to stop - * receiving the remote audio stream. - * - Call `muteRemoteVideoStream` ( true ) or `muteAllRemoteVideoStreams` ( true ) to stop - * receiving the remote video stream. + * - Calls `muteRemoteAudioStream(true)`, `muteAllRemoteAudioStreams(true)` to stop receiving the remote audio streams. + * - Calls `muteRemoteVideoStream(true)`, `muteAllRemoteVideoStreams(true)` to stop receiving the remote video streams. */ SUB_STATE_NO_SUBSCRIBED = 1, /** @@ -7472,13 +6772,13 @@ enum STREAM_SUBSCRIBE_STATE { */ SUB_STATE_SUBSCRIBING = 2, /** - * 3: The remote stream is received, and the subscription is successful. + * 3: Subscribes to and receives the remote stream successfully. */ SUB_STATE_SUBSCRIBED = 3 }; /** - * @brief The publishing state. + * The publishing state. */ enum STREAM_PUBLISH_STATE { /** @@ -7487,12 +6787,12 @@ enum STREAM_PUBLISH_STATE { PUB_STATE_IDLE = 0, /** * 1: Fails to publish the local stream. Possible reasons: - * - The local user calls `muteLocalAudioStream` (`true`) or `muteLocalVideoStream` (`true`) to stop - * sending local media streams. + * - The local user calls `muteLocalAudioStream(true)` or `muteLocalVideoStream(true)` to stop + * sending the local media stream. * - The local user calls `disableAudio` or `disableVideo` to disable the local audio or video * module. - * - The local user calls `enableLocalAudio` (`false`) or `enableLocalVideo` (`false`) to disable - * the local audio or video capture. + * - The local user calls `enableLocalAudio(false)` or `enableLocalVideo(false)` to disable the + * local audio or video capture. * - The role of the local user is audience. */ PUB_STATE_NO_PUBLISHED = 1, @@ -7507,49 +6807,14 @@ enum STREAM_PUBLISH_STATE { }; /** - * @brief The configuration of the audio and video call loop test. + * The EchoTestConfiguration struct. */ 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 loop test: - * - `true`: (Default) Enable the audio device. To test the audio device, set this parameter as - * true. - * - `false`: Disable the audio device. - */ bool enableAudio; - /** - * Whether to enable the video device for the loop test: - * - `true`: (Default) Enable the video device. To test the video device, set this parameter as - * true. - * - `false`: Disable 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 . - */ 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; - /** - * Set the time interval or delay for returning the results of the audio and video loop test. The - * value range is [2,10], in seconds, with the default value being 2 seconds. - * - For audio loop tests, the test results will be returned according to the time interval you set. - * - For video loop tests, the video will be displayed in a short time, after which the delay will - * gradually increase until it reaches the delay you set. - */ int intervalInSeconds; EchoTestConfiguration(view_t v, bool ea, bool ev, const char* t, const char* c, const int is) @@ -7565,7 +6830,7 @@ struct EchoTestConfiguration { }; /** - * @brief The information of the user. + * The information of the user. */ struct UserInfo { /** @@ -7573,7 +6838,7 @@ struct UserInfo { */ uid_t uid; /** - * User account. The maximum data length is `MAX_USER_ACCOUNT_LENGTH_TYPE`. + * The user account. The maximum data length is `MAX_USER_ACCOUNT_LENGTH_TYPE`. */ char userAccount[MAX_USER_ACCOUNT_LENGTH]; @@ -7581,26 +6846,26 @@ struct UserInfo { }; /** - * @brief The audio filter types of in-ear monitoring. + * The audio filter of in-ear monitoring. */ enum EAR_MONITORING_FILTER_TYPE { /** - * 1<<0: No audio filter added to in-ear monitoring. + * 1: Do not add an audio filter to the in-ear monitor. */ EAR_MONITORING_FILTER_NONE = (1 << 0), /** - * 1<<1: Add vocal effects audio filter to in-ear monitoring. If you implement functions such as - * voice beautifier and audio effect, users can hear the voice after adding these effects. + * 2: Enable audio filters to the in-ear monitor. If you implement functions such as voice + * beautifier and audio effect, users can hear the voice after adding these effects. */ EAR_MONITORING_FILTER_BUILT_IN_AUDIO_FILTERS = (1 << 1), /** - * 1<<2: Add noise suppression audio filter to in-ear monitoring. + * 4: Enable noise suppression to the in-ear monitor. */ EAR_MONITORING_FILTER_NOISE_SUPPRESSION = (1 << 2), /** - * 1<<15: Reuse the audio filter that has been processed on the sending end for in-ear monitoring. - * This enumerator reduces CPU usage while increasing in-ear monitoring latency, which is suitable - * for latency-tolerant scenarios requiring low CPU consumption. + * 32768: Enable audio filters by reuse post-processing filter to the in-ear monitor. + * This bit is intended to be used in exclusive mode, which means, if this bit is set, all other + * bits will be disregarded. */ EAR_MONITORING_FILTER_REUSE_POST_PROCESSING_FILTER = (1 << 15), }; @@ -7635,26 +6900,52 @@ enum THREAD_PRIORITY_TYPE { CRITICAL = 5, }; -#if defined(__ANDROID__) || (defined(__APPLE__) && TARGET_OS_IOS) || defined(__OHOS__) +#if defined(__ANDROID__) || (defined(__APPLE__) && (TARGET_OS_IOS || (defined(TARGET_OS_VISION) && TARGET_OS_VISION))) /** - * @brief The video configuration for the shared screen stream. + * The video configuration for the shared screen stream. */ struct ScreenVideoParameters { /** - * The video encoding dimension. The default value is 1280 × 720. + * The dimensions of the video encoding resolution. The default value is `1280` x `720`. + * For recommended values, see [Recommended video + * profiles](https://docs.agora.io/en/Interactive%20Broadcast/game_streaming_video_profile?platform=Android#recommended-video-profiles). + * If the aspect ratio is different between width and height and the screen, the SDK adjusts the + * video encoding resolution according to the following rules (using an example where `width` × + * `height` is 1280 × 720): + * - When the width and height of the screen are both lower than `width` and `height`, the SDK + * uses the resolution of the screen for video encoding. For example, if the screen is 640 × + * 360, The SDK uses 640 × 360 for video encoding. + * - When either the width or height of the screen is higher than `width` or `height`, the SDK + * uses the maximum values that do not exceed those of `width` and `height` while maintaining + * the aspect ratio of the screen for video encoding. For example, if the screen is 2000 × 1500, + * the SDK uses 960 × 720 for video encoding. + * + * @note + * - The billing of the screen sharing stream is based on the values of width and height. + * When you do not pass in these values, Agora bills you at 1280 × 720; + * when you pass in these values, Agora bills you at those values. + * For details, see [Pricing for Real-time + * Communication](https://docs.agora.io/en/Interactive%20Broadcast/billing_rtc). + * - This value does not indicate the orientation mode of the output ratio. + * For how to set the video orientation, see `ORIENTATION_MODE`. + * - Whether the SDK can support a resolution at 720P depends on the performance of the device. + * If you set 720P but the device cannot support it, the video frame rate can be lower. */ VideoDimensions dimensions; /** - * The video encoding frame rate (fps). The default value is 15. + * The video encoding frame rate (fps). The default value is `15`. + * For recommended values, see [Recommended video + * profiles](https://docs.agora.io/en/Interactive%20Broadcast/game_streaming_video_profile?platform=Android#recommended-video-profiles). */ int frameRate = 15; /** - * The video encoding bitrate (Kbps). + * The video encoding bitrate (Kbps). For recommended values, see [Recommended video + * profiles](https://docs.agora.io/en/Interactive%20Broadcast/game_streaming_video_profile?platform=Android#recommended-video-profiles). */ int bitrate; - /** - * The content hint for screen sharing. See `VIDEO_CONTENT_HINT`. + /* + * The content hint of the screen sharing: */ VIDEO_CONTENT_HINT contentHint = VIDEO_CONTENT_HINT::CONTENT_HINT_MOTION; @@ -7662,140 +6953,105 @@ struct ScreenVideoParameters { }; /** - * @brief Screen sharing configurations. + * The configuration of the screen sharing */ struct ScreenCaptureParameters2 { /** * Determines whether to capture system audio during screen sharing: - * - `true`: Capture system audio. - * - `false`: (Default) Do not capture system audio. - * @note - * - Due to system limitations, capturing system audio is only applicable to Android API level 29 + * - `true`: Capture. + * - `false`: (Default) Do not capture. + * + * **Note** + * Due to system limitations, capturing system audio is only available for Android API level 29 * and later (that is, Android 10 and later). - * - To improve the success rate of capturing system audio during screen sharing, ensure that you - * have called the `setAudioScenario` method and set the audio scenario to - * `AUDIO_SCENARIO_GAME_STREAMING`. */ bool captureAudio = false; /** - * The audio configuration for the shared screen stream. See `ScreenAudioParameters`. - * @note This parameter only takes effect when `captureAudio` is `true`. + * The audio configuration for the shared screen stream. */ ScreenAudioParameters audioParams; /** - * Whether to capture the screen when screen sharing: - * - `true`: (Default) Capture the screen. - * - `false`: Do not capture the screen. - * @note Due to system limitations, the capture screen is only applicable to Android API level 21 - * and above, that is, Android 5 and above. + * Determines whether to capture the screen during screen sharing: + * - `true`: (Default) Capture. + * - `false`: Do not capture. + * + * **Note** + * Due to system limitations, screen capture is only available for Android API level 21 and later + * (that is, Android 5 and later). */ bool captureVideo = true; /** - * The video configuration for the shared screen stream. See `ScreenVideoParameters`. - * @note This parameter only takes effect when `captureVideo` is `true`. + * The video configuration for the shared screen stream. */ ScreenVideoParameters videoParams; }; #endif /** - * @brief The rendering state of the media frame. + * The tracing event of media rendering. */ enum MEDIA_TRACE_EVENT { /** - * 0: The video frame has been rendered. + * 0: The media frame has been rendered. */ MEDIA_TRACE_EVENT_VIDEO_RENDERED = 0, /** - * 1: The video frame has been decoded. + * 1: The media frame has been decoded. */ MEDIA_TRACE_EVENT_VIDEO_DECODED, }; /** - * @brief Indicators during video frame rendering progress. + * The video rendering tracing result */ struct VideoRenderingTracingInfo { /** - * The time interval (ms) from `startMediaRenderingTracing` to SDK triggering the - * `onVideoRenderingTracingResult` callback. Agora recommends you call `startMediaRenderingTracing` - * before joining a channel. + * Elapsed time from the start tracing time to the time when the tracing event occurred. */ int elapsedTime; /** - * The time interval (ms) from `startMediaRenderingTracing` to `joinChannel(const char* token, const - * char* channelId, const char* info, uid_t uid)` or `joinChannel(const char* token, const char* - * channelId, uid_t uid, const ChannelMediaOptions& options)` - * . A negative number indicates that `startMediaRenderingTracing` is called after calling - * `joinChannel(const char* token, const char* channelId, uid_t uid, const ChannelMediaOptions& - * options)`. + * Elapsed time from the start tracing time to the time when join channel. + * + * **Note** + * If the start tracing time is behind the time when join channel, this value will be negative. */ int start2JoinChannel; /** - * The time interval (ms) from `joinChannel(const char* token, const char* channelId, const char* - * info, uid_t uid)` or `joinChannel(const char* token, const char* channelId, uid_t uid, const - * ChannelMediaOptions& options)` to successfully joining - * the channel. + * Elapsed time from joining channel to finishing joining channel. */ int join2JoinSuccess; /** - * - If the local user calls `startMediaRenderingTracing` before successfully joining the channel, - * this value is the time interval (ms) from the local user successfully joining the channel to the - * remote user joining the channel. - * - If the local user calls `startMediaRenderingTracing` after successfully joining the channel, - * the value is the time interval (ms) from `startMediaRenderingTracing` to when the remote user - * joins the channel. - * @note - * - If the local user calls `startMediaRenderingTracing` after the remote user joins the channel, - * the value is 0 and meaningless. - * - In order to reduce the time of rendering the first frame for remote users, Agora recommends - * that the local user joins the channel when the remote user is in the channel to reduce this - * value. + * Elapsed time from finishing joining channel to remote user joined. + * + * **Note** + * If the start tracing time is after the time finishing join channel, this value will be + * the elapsed time from the start tracing time to remote user joined. The minimum value is 0. */ int joinSuccess2RemoteJoined; /** - * - If the local user calls `startMediaRenderingTracing` before the remote user joins the channel, - * this value is the time interval (ms) from when the remote user joins the channel to when the - * local user sets the remote view. - * - If the local user calls `startMediaRenderingTracing` after the remote user joins the channel, - * this value is the time interval (ms) from calling `startMediaRenderingTracing` to setting the - * remote view. - * @note - * - If the local user calls `startMediaRenderingTracing` after setting the remote view, the value - * is 0 and has no effect. - * - In order to reduce the time of rendering the first frame for remote users, Agora recommends - * that the local user sets the remote view before the remote user joins the channel, or sets the - * remote view immediately after the remote user joins the channel to reduce this value. + * Elapsed time from remote user joined to set the view. + * + * **Note** + * If the start tracing time is after the time when remote user joined, this value will be + * the elapsed time from the start tracing time to set the view. The minimum value is 0. */ int remoteJoined2SetView; /** - * - If the local user calls `startMediaRenderingTracing` before the remote user joins the channel, - * this value is the time interval (ms) from the remote user joining the channel to subscribing to - * the remote video stream. - * - If the local user calls `startMediaRenderingTracing` after the remote user joins the channel, - * this value is the time interval (ms) from `startMediaRenderingTracing` to subscribing to the - * remote video stream. - * @note - * - If the local user calls `startMediaRenderingTracing` after subscribing to the remote video - * stream, the value is 0 and has no effect. - * - In order to reduce the time of rendering the first frame for remote users, Agora recommends - * that after the remote user joins the channel, the local user immediately subscribes to the remote - * video stream to reduce this value. + * Elapsed time from remote user joined to the time subscribing remote video stream. + * + * **Note** + * If the start tracing time is after the time when remote user joined, this value will be + * the elapsed time from the start tracing time to the time subscribing remote video stream. + * The minimum value is 0. */ int remoteJoined2UnmuteVideo; /** - * - If the local user calls `startMediaRenderingTracing` before the remote user joins the channel, - * this value is the time interval (ms) from when the remote user joins the channel to when the - * local user receives the remote video stream. - * - If the local user calls `startMediaRenderingTracing` after the remote user joins the channel, - * this value is the time interval (ms) from `startMediaRenderingTracing` to receiving the remote - * video stream. - * @note - * - If the local user calls `startMediaRenderingTracing` after receiving the remote video stream, - * the value is 0 and has no effect. - * - In order to reduce the time of rendering the first frame for remote users, Agora recommends - * that the remote user publishes video streams immediately after joining the channel, and the local - * user immediately subscribes to remote video streams to reduce this value. + * Elapsed time from remote user joined to the remote video packet received. + * + * **Note** + * If the start tracing time is after the time when remote user joined, this value will be + * the elapsed time from the start tracing time to the time subscribing remote video stream. + * The minimum value is 0. */ int remoteJoined2PacketReceived; }; @@ -7811,41 +7067,29 @@ enum CONFIG_FETCH_TYPE { CONFIG_FETCH_TYPE_JOIN_CHANNEL = 2, }; -/** - * @brief Connection mode with the Agora Private Media Server. - */ +/** The local proxy mode type. */ enum LOCAL_PROXY_MODE { - /** - * 0: The SDK first tries to connect to the specified Agora Private Media Server; if it fails, it - * connects to the Agora SD-RTN™. + /** 0: Connect local proxy with high priority, if not connected to local proxy, fallback to sdrtn. */ ConnectivityFirst = 0, - /** - * 1: The SDK only tries to connect to the specified Agora Private Media Server. + /** 1: Only connect local proxy */ LocalOnly = 1, }; -/** - * @brief Configuration information for the log server. - */ struct LogUploadServerInfo { - /** - * Domain name of the log server. + /** Log upload server domain */ const char* serverDomain; - /** - * Storage path for logs on the server. + /** Log upload server path */ const char* serverPath; - /** - * Port of the log server. + /** Log upload server port */ int serverPort; - /** - * Whether the log server uses HTTPS protocol: - * - `true`: Uses HTTPS. - * - `false`: Uses HTTP. + /** Whether to use HTTPS request: + - true: Use HTTPS request + - fasle: Use HTTP request */ bool serverHttps; @@ -7855,55 +7099,34 @@ struct LogUploadServerInfo { : serverDomain(domain), serverPath(path), serverPort(port), serverHttps(https) {} }; -/** - * @brief Advanced options for the Local Access Point. - */ struct AdvancedConfigInfo { - /** - * Custom log upload server. By default, the SDK uploads logs to the Agora log server. You can use - * this parameter to change the log upload server. See `LogUploadServerInfo`. + /** Log upload server */ LogUploadServerInfo logUploadServer; }; -/** - * @brief Configuration for the Local Access Point. - */ struct LocalAccessPointConfiguration { - /** - * Internal IP address list of the Local Access Point. Either ipList or domainList must be - * specified. + /** Local access point IP address list. */ const char** ipList; - /** - * Number of internal IP addresses for the Local Access Point. This value must match the number of - * IP addresses you provide. + /** The number of local access point IP address. */ int ipListSize; - /** - * Domain name list of the Local Access Point. The SDK resolves the IP addresses of the Local Access - * Point from the provided domain names. The DNS resolution timeout is 10 seconds. Either ipList or - * domainList must be specified. If you specify both IP addresses and domain names, the SDK merges - * and deduplicates the resolved IP addresses and the specified IP addresses, then randomly selects - * one for load balancing. + /** Local access point domain list. */ const char** domainList; - /** - * Number of domain names for the Local Access Point. This value must match the number of domain - * names you provide. + /** The number of local access point domain. */ int domainListSize; - /** - * Domain name for internal certificate verification. If left empty, the SDK uses the default domain - * name `secure-edge.local` for certificate verification. + /** Certificate domain name installed on specific local access point. pass "" means using sni + * domain on specific local access point SNI(Server Name Indication) is an extension to the TLS + * protocol. */ const char* verifyDomainName; - /** - * Connection mode. See `LOCAL_PROXY_MODE`. + /** Local proxy connection mode, connectivity first or local only. */ LOCAL_PROXY_MODE mode; - /** - * Advanced options for the Local Access Point. See `AdvancedConfigInfo`. + /** Local proxy connection, advanced Config info. */ AdvancedConfigInfo advancedConfig; /** @@ -7922,30 +7145,21 @@ struct LocalAccessPointConfiguration { disableAut(true) {} }; -/** - * @brief Type of video stream to be recorded. - */ enum RecorderStreamType { - /** - * 0: (Default) Video stream in the channel. - */ RTC, - /** - * 1: Local preview video stream before joining the channel. - */ PREVIEW, }; /** - * @brief The information about the media streams to be recorded. + * The information about recorded media streams. */ struct RecorderStreamInfo { /** - * The name of the channel in which the media streams publish. + * The channel ID of the audio/video stream needs to be recorded. */ const char* channelId; /** - * The ID of the user whose media streams you want to record. + * The user ID. */ uid_t uid; /** @@ -7958,63 +7172,6 @@ struct RecorderStreamInfo { RecorderStreamInfo(const char* channelId, uid_t uid, RecorderStreamType type) : channelId(channelId), uid(uid), type(type) {} }; - -/** - * @brief Reliable Data Transmission Tunnel message stream type - * - * @technical preview - */ -enum RdtStreamType { - /** - * Command stream type. - * Characterized by: reliability, high priority, and not affected by congestion control. - * Transmission limits: a maximum of 256 bytes per packet, and 100 packets per second. - */ - RDT_STREAM_CMD, - /** - * Data stream type. - * Characterized by: reliability, low priority, and affected by congestion control. - * Transmission limits: a maximum of 128 KBytes per packet, with a rate of 4 Mbps. - */ - RDT_STREAM_DATA, - /** - * Reliable Data Transmission stream type count - */ - RDT_STREAM_COUNT, -}; - -/** - * @brief Reliable Data Transmission tunnel state - * - * @technical preview - */ -enum RdtState { - /** - * The RDT tunnel is in the initial or is closed. - */ - RDT_STATE_CLOSED, - /** - * The RDT tunnel is open, and data can only be sent in this state. - */ - RDT_STATE_OPENED, - /** - * The send buffer of the RDT tunnel is full. RDT_STREAM_DATA cannot be sent, - * but RDT_STREAM_CMD can be sent, as the latter is not affected by congestion control. - */ - RDT_STATE_BLOCKED, - /** - * The RDT tunnel is in a suspended state because SDK has disconnected. - * It will automatically resume to the RDT_STATE_OPENED state after rejoining the channel. - */ - RDT_STATE_PENDING, - /** - * The RDT channel is broken, and the data being sent and received will be cleared. - * It will automatically resume to the RDT_STATE_OPENED state later. - * Reason for occurrence: The remote user actively called the API to leave the - * channel and then rejoined the channel, without being detected by this end. - */ - RDT_STATE_BROKEN, -}; } // namespace rtc namespace base { @@ -8051,128 +7208,77 @@ class LicenseCallback { } // namespace base /** - * @brief The spatial audio parameters. + * Spatial audio parameters */ struct SpatialAudioParams { /** - * The azimuth angle of the remote user or media player relative to the local user. The value range - * is [0,360], and the unit is degrees, The values are as follows: - * - 0: (Default) 0 degrees, which means directly in front on the horizontal plane. - * - 90: 90 degrees, which means directly to the left on the horizontal plane. - * - 180: 180 degrees, which means directly behind on the horizontal plane. - * - 270: 270 degrees, which means directly to the right on the horizontal plane. - * - 360: 360 degrees, which means directly in front on the horizontal plane. + * Speaker azimuth in a spherical coordinate system centered on the listener. */ Optional speaker_azimuth; /** - * The elevation angle of the remote user or media player relative to the local user. The value - * range is [-90,90], and the unit is degrees, The values are as follows: - * - 0: (Default) 0 degrees, which means that the horizontal plane is not rotated. - * - -90: -90 degrees, which means that the horizontal plane is rotated 90 degrees downwards. - * - 90: 90 degrees, which means that the horizontal plane is rotated 90 degrees upwards. + * Speaker elevation in a spherical coordinate system centered on the listener. */ Optional speaker_elevation; /** - * The distance of the remote user or media player relative to the local user. The value range is - * [1,50], and the unit is meters. The default value is 1 meter. + * Distance between speaker and listener. */ Optional speaker_distance; /** - * The orientation of the remote user or media player relative to the local user. The value range is - * [0,180], and the unit is degrees, The values are as follows: - * - 0: (Default) 0 degrees, which means that the sound source and listener face the same direction. - * - 180: 180 degrees, which means that the sound source and listener face each other. + * Speaker orientation [0-180], 0 degree is the same with listener orientation. */ Optional speaker_orientation; /** - * Whether to enable audio blurring: - * - `true`: Enable audio blurring. - * - `false`: (Default) Disable audio blurring. + * Enable blur or not for the speaker. */ Optional enable_blur; /** - * Whether to enable air absorption, that is, to simulate the sound attenuation effect of sound - * transmitting in the air; under a certain transmission distance, the attenuation speed of - * high-frequency sound is fast, and the attenuation speed of low-frequency sound is slow. - * - `true`: (Default) Enable air absorption. Make sure that the value of `speaker_attenuation` is - * not `0`; otherwise, this setting does not take effect. - * - `false`: Disable air absorption. + * Enable air absorb or not for the speaker. */ Optional enable_air_absorb; /** - * The sound attenuation coefficient of the remote user or media player. The value range is [0,1]. - * The values are as follows: - * - 0: Broadcast mode, where the volume and timbre are not attenuated with distance, and the volume - * and timbre heard by local users do not change regardless of distance. - * - (0,0.5): Weak attenuation mode, where the volume and timbre only have a weak attenuation during - * the propagation, and the sound can travel farther than that in a real environment. - * `enable_air_absorb` needs to be enabled at the same time. - * - 0.5: (Default) Simulates the attenuation of the volume in the real environment; the effect is - * equivalent to not setting the `speaker_attenuation` parameter. - * - (0.5,1]: Strong attenuation mode, where volume and timbre attenuate rapidly during the - * propagation. `enable_air_absorb` needs to be enabled at the same time. + * Speaker attenuation factor. */ Optional speaker_attenuation; /** - * Whether to enable the Doppler effect: When there is a relative displacement between the sound - * source and the receiver of the sound source, the tone heard by the receiver changes. - * - `true`: Enable the Doppler effect. - * - `false`: (Default) Disable the Doppler effect. - * @note - * - This parameter is suitable for scenarios where the sound source is moving at high speed (for - * example, racing games). It is not recommended for common audio and video interactive scenarios - * (for example, voice chat, co-streaming, or online KTV). - * - When this parameter is enabled, Agora recommends that you set a regular period (such as 30 ms), - * and then call the `updatePlayerPositionInfo`, `updateSelfPosition`, and `updateRemotePosition` - * methods to continuously update the relative distance between the sound source and the receiver. - * The following factors can cause the Doppler effect to be unpredictable or the sound to be - * jittery: the period of updating the distance is too long, the updating period is irregular, or - * the distance information is lost due to network packet loss or delay. + * Enable doppler factor. */ Optional enable_doppler; }; /** - * @brief Layout information of a specific sub-video stream within the mixed stream. + * Layout info of video stream which compose a transcoder video stream. */ struct VideoLayout { /** - * The channel name to which the sub-video stream belongs. + * Channel Id from which this video stream come from. */ const char* channelId; /** - * User ID who published this sub-video stream. + * User id of video stream. */ rtc::uid_t uid; /** - * Reserved for future use. + * User account of video stream. */ user_id_t strUid; /** - * X-coordinate (px) of the sub-video stream on the mixing canvas. The relative lateral displacement - * of the top left corner of the video for video mixing to the origin (the top left corner of the - * canvas). + * x coordinate of video stream on a transcoded video stream canvas. */ uint32_t x; /** - * Y-coordinate (px) of the sub-video stream on the mixing canvas. The relative longitudinal - * displacement of the top left corner of the captured video to the origin (the top left corner of - * the canvas). + * y coordinate of video stream on a transcoded video stream canvas. */ uint32_t y; /** - * Width (px) of the sub-video stream. + * width of video stream on a transcoded video stream canvas. */ uint32_t width; /** - * Heitht (px) of the sub-video stream. + * height of video stream on a transcoded video stream canvas. */ uint32_t height; /** - * Status of the sub-video stream on the video mixing canvas. - * - 0: Normal. The sub-video stream has been rendered onto the mixing canvas. - * - 1: Placeholder image. The sub-video stream has no video frames and is displayed as a - * placeholder on the mixing canvas. - * - 2: Black image. The sub-video stream is replaced by a black image. + * video state of video stream on a transcoded video stream canvas. + * 0 for normal video , 1 for placeholder image showed , 2 for black image. */ uint32_t videoState; @@ -8241,7 +7347,7 @@ AGORA_API int AGORA_CALL getAgoraCertificateVerifyResult(const char* credential_ AGORA_API void setAgoraLicenseCallback(agora::base::LicenseCallback* callback); /** - * @brief Gets the LicenseCallback pointer if already setup, + * @brief Get the LicenseCallback pointer if already setup, * otherwise, return null. * * @return a pointer of agora::base::LicenseCallback diff --git a/Android/APIExample/agora-simple-filter/src/main/cpp/AgoraRtcKit/AgoraExtensions.h b/Android/APIExample/agora-simple-filter/src/main/cpp/AgoraRtcKit/AgoraExtensions.h deleted file mode 100644 index 4c18c2932..000000000 --- a/Android/APIExample/agora-simple-filter/src/main/cpp/AgoraRtcKit/AgoraExtensions.h +++ /dev/null @@ -1,501 +0,0 @@ -#pragma once -#include "NGIAgoraMediaNode.h" - -namespace agora { -namespace rtc { -/** - * The `IAudioFilter` class. - * - * This class is the intermediate node for audio, which reads audio frames from the underlying - * pipeline and writes audio frames back after adaptation. - */ -class IAudioFilter : public IAudioFilterBase { - public: - /** - * Enables or disables the audio filter. - * @param enable Whether to enable the audio filter: - * - `true`: Enable the audio filter. - * - `false`: Do not enable the audio filter. - */ - virtual void setEnabled(bool enable) = 0; - /** - * Checks whether the audio filter is enabled. - * @return - * - `true`: The audio filter is enabled. - * - `false`: The audio filter is not enabled. - */ - virtual bool isEnabled() const = 0; - /** - * Sets a private property in the `IAudioFilter` class. - * - * @param key The pointer to the property name. - * @param buf The pointer to the buffer of this private property. - * @param buf_size The buffer size of this private property. - * @return - * - The actual size of the private property, if the method call succeeds. - * - -1, if the method call fails. - */ - virtual int setProperty(const char* key, const void* buf, int buf_size) = 0; - /** - * Gets a private property in the `IAudioFilter` class. - * - * @param name The pointer to the property name. - * @param buf The pointer to the buffer of this private property. - * @param buf_size The buffer size of this private property. - * @return - * - The actual size of the private property, if the method call succeeds. - * - -1, if the method call fails. - */ - virtual int getProperty(const char* key, void* buf, int buf_size) const = 0; - /** - * Gets the name of the `IAudioFilter` class. - * - * @return - * - The name of the audio filter, if the method call succeeds. - * - An empty string, if the method call fails. - */ - virtual const char * getName() const = 0; - - /** - * Get the sample rate supported by the audio filter, the framework will resample - * the audio data and then pass it to the audio filter. If the user does not - * overwrite, resampling will not be done by default. - * @return - * - 0: Audio data will not be resampled. - * - > 0: Audio data will be resampled to this sample rate. - */ - virtual int getPreferredSampleRate() { return 0; }; - - /** - * Get the channel number supported by the audio filter, the framework will resample - * the audio data and then pass it to the audio filter. If the user does not - * overwrite, resampling will not be done by default. - * @return - * - 0: Audio data will not be resampled. - * - > 0: Audio data will be resampled to this sample rate. - */ - virtual int getPreferredChannelNumbers() { return 0; }; - - protected: - ~IAudioFilter() {} -}; - -class IAudioFilterV2 : public IAudioFilter { -public: - class Control : public RefCountInterface { - public: - /** - * @brief Post an event and notify the end users. - * @param key '\0' ended string that describes the key of the event - * @param value '\0' ended string that describes the value of the event - */ - virtual int postEvent(const char* key, const char* value) = 0; - /** - * @brief print log to the SDK. - * @param level Log level @ref agora::commons::LOG_LEVEL - * @param format log formatter string - * @param ... variadic arguments - */ - virtual void printLog(commons::LOG_LEVEL level, const char* format, ...) = 0; - }; -public: - /** - * @brief AgoraSDK set IAudioFilterV2::Control to filter - * @param control IAudioFilterV2::Control - */ - virtual void setExtensionControl(agora::agora_refptr control) = 0; -}; -/** - * The IExtensionVideoFilter class. - * - * This class defines the interfaces that a external video extension provider can implement - * so as to be loaded by SDK as an "3rd party extension" for video pre- or post- processing. - */ -class IExtensionVideoFilter : public IVideoFilter { - public: - enum ProcessMode { - kSync, // Indicates that video frame data will be exchanged via "adaptVideoFrame" - kAsync, // Indicates that video frame data will be exchanged via "pendVideoFrame" & "deliverVideoFrame" - }; - - enum ProcessResult { - kSuccess, // Video frame data is successfully processed - kBypass, // Video frame data should bypass the current filter and flow to its successsors - kDrop, // Video Frame data should be discarded - }; - - /** - * The IExtensionVideoFilter::Control class. - * - * This class defines the interfaces that the extension filter can leverage to interact with the SDK. - * The "IExtensionVideoFilter::Control" object will be passed to the filter when SDK invoke the filter's - * "start" interface. - */ - class Control : public RefCountInterface { - public: - /** - * @brief Filter can invoke this function to deliver the processed frame to SDK if the Process Mode is - * designated as "kAsync" by the filter via "getProcessMode". - * @param frame the processed video frame - * @return see @ref ProcessResult - */ - virtual ProcessResult deliverVideoFrame(agora::agora_refptr frame) = 0; - /** - * @brief Filter can invoke this function to get the IVideoFrameMemoryPool object if a new IVideoFrame - * data object is needed. - */ - virtual agora::agora_refptr getMemoryPool() = 0; - /** - * @brief Post an event and notify the end users. - * @param key '\0' ended string that describes the key of the event - * @param value '\0' ended string that describes the value of the event - */ - virtual int postEvent(const char* key, const char* value) = 0; - /** - * @brief print log to the SDK. - * @param level Log level @ref agora::commons::LOG_LEVEL - * @param format log formatter string - * @param ... variadic arguments - */ - virtual void printLog(commons::LOG_LEVEL level, const char* format, ...) = 0; - /** - * @brief Ask SDK to disable the current filter if a fatal error is detected - * @param error error code - * @param msg error message - */ - virtual void disableMe(int error, const char* msg) = 0; - }; - - /** - * @brief SDK will invoke this API first to get the filter's requested process mode @ref ProcessMode - * @param mode [out] filter assign its desired the process mode @ref ProcessMode - * @param independent_thread deprecated. SDK will ignore this parameter. - * @note If the filter implementation is not thread sensitive, we recommend to set the boolean to "false" to reduce thread context - * switching. - */ - virtual void getProcessMode(ProcessMode& mode, bool& independent_thread) = 0; - - /** - * @brief SDK will invoke this API before feeding video frame data to the filter. Filter can perform its initialization/preparation job - * in this step. - * - * @param control object to @ref IExtensionFilter::Control that pass to the filter which can be used for future interaction with the SDK - * @return error code - */ - virtual int start(agora::agora_refptr control) = 0; - /** - * @brief SDK will invoke this API when the data stream is about to stop. Filter can perform cleanup jobs in this step - * - * @return error code - */ - virtual int stop() = 0; - /** - * @brief SDK will invoke this API every time before sending data to the filter. Filter can desigante the type @ref VideoFrameInfo::Type - * and format @ref MemPixelBuffer::Format of the next frame. SDK will then try to perform type / format conversion before sending data to - * the filter. - * - * @param type requested type of the next frame - * @param format requested formant of the next frame - */ - virtual void getVideoFormatWanted(VideoFrameData::Type& type, RawPixelBuffer::Format& format) = 0; - /** - * @brief SDK will invoke this API to send video frame to the filter if process mode is "Async". Filter invokes control's "deliverFrame" - * to send back the frame after processing. - * - * @param frame frame pending for processing - */ - virtual ProcessResult pendVideoFrame(agora::agora_refptr frame) { - return OPTIONAL_PROCESSRESULT_SPECIFIER kBypass; - } - /** - * @brief SDK will invoke this API to send video frame to the filter if process mode is "Sync". - * - * @param frame frame pending for processing - */ - virtual ProcessResult adaptVideoFrame(agora::agora_refptr in, agora::agora_refptr& out) { - return OPTIONAL_PROCESSRESULT_SPECIFIER kBypass; - } - /* Occurs each time needs to get rotation apply. - * - * @return Determines whether to rotate. - * - true: need to rotate. - * - false: no rotate. - */ - virtual bool getRotationApplied() { return false; } - - // NOTE: The following two interfaces should never be overriden! - virtual bool isExtensionFilter() { return true; } - virtual bool adaptVideoFrame( - const media::base::VideoFrame& capturedFrame, - media::base::VideoFrame& adaptedFrame) { - return -ERR_NOT_SUPPORTED; - } -}; - -class IExtensionVideoSink : public IVideoSinkBase { -}; - -class ILipSyncFilter : public RefCountInterface { - public: - enum ProcessResult { - kSuccess, // Video frame data is successfully processed - kBypass, // Video frame data should bypass the current filter and flow to its successsors - kDrop, // Video Frame data should be discarded - }; - - class Control : public RefCountInterface { - public: - /** - * @brief Post an event and notify the end users. - * @param key '\0' ended string that describes the key of the event - * @param value '\0' ended string that describes the value of the event - */ - virtual int postEvent(const char* key, const char* value) = 0; - /** - * @brief print log to the SDK. - * @param level Log level @ref agora::commons::LOG_LEVEL - * @param format log formatter string - * @param ... variadic arguments - */ - virtual void printLog(commons::LOG_LEVEL level, const char* format, ...) = 0; - /** - * @brief Ask SDK to disable the current filter if a fatal error is detected - * @param error error code - * @param msg error message - */ - virtual void disableMe(int error, const char* msg) = 0; - /** - * @brief report counter to the SDK. - * @param counter_id counter id - * @param value counter value - */ - virtual void ReportCounter(int32_t counter_id, int32_t value) = 0; - /** - * @brief get stats to the SDK. - * @param counter_id counter id - */ - virtual int GetStats(int32_t counter_id) = 0; - }; - - virtual int start(agora::agora_refptr control) = 0; - - virtual int stop() = 0; - - virtual int setProperty(const char* key, const void* buf, size_t buf_size) { return -1; } - /** - * Convert the audio frame to face info. - * @param inAudioFrame The reference to the audio frame that you want to convert. - * @param outFaceInfo The reference to the face info. - * @return see @ref ProcessResult - */ - virtual ProcessResult convertAudioFrameToFaceInfo(const agora::media::base::AudioPcmFrame& inAudioFrame, char* outFaceInfo) { - return kBypass; - } -}; - -class ExtensionVideoCodecSettings { - public: - // Structure to hold settings for the video encoder. - struct VideoEncoderSettings { - uint32_t framerate = 0; // The frame rate of the video in frames per second (fps). - uint32_t bitrate_kbps = 0; // The bitrate of the video in kilobits per second (kbps). - uint32_t key_frame_interval = 0; // The interval between key frames in seconds (time between I-frames). - }; - // Structure to hold settings for the video decoder. - struct VideoDecoderSettings { - media::base::VIDEO_PIXEL_FORMAT prefer_data_format; // The preferred pixel format for the decoded video. - }; - - uint16_t width = 0; // The width of the video frame in pixels. - uint16_t height = 0; // The height of the video frame in pixels. - VideoEncoderSettings encoder_settings; // An instance of VideoEncoderSettings to configure the encoder. - VideoDecoderSettings decoder_settings; // An instance of VideoDecoderSettings to configure the decoder. -}; - -class ExtensionEncodedImage { -public: - size_t length = 0; // The length of the encoded image data (in bytes). - uint8_t* buffer = nullptr; // Pointer to the buffer holding the encoded image data (raw bytes). - VIDEO_FRAME_TYPE frame_type = VIDEO_FRAME_TYPE_DELTA_FRAME; // The type of the video frame (e.g., key frame, delta frame). - uint32_t pts_ms = 0; // Presentation timestamp (PTS) in milliseconds, indicating when the frame should be displayed. - uint32_t dts_ms = 0; // Decoding timestamp (DTS) in milliseconds, indicating when the frame should be decoded. - uint32_t width = 0; // The width of the video frame in pixels. - uint32_t height = 0; // The height of the video frame in pixels. -}; - -class IExtensionDecoderCallback { - public: - // Destructor for the IExtensionDecoderCallback class. - virtual ~IExtensionDecoderCallback() {} - /** - * Called when a video frame has been successfully decoded. - * @param frame A reference to the decoded video frame. - * @param extended_info_json A JSON formatted string containing additional information about the decoded frame. - */ - virtual void onDecodedFrame(agora_refptr frame, const char* extended_info_json) = 0; - /** - * Logs messages at various log levels. - * @param level The log level indicating the severity of the message (e.g., INFO, WARNING, ERROR). - * @param format A format string for the log message, similar to printf formatting. - * @param ... Additional arguments to format the log message. - */ - virtual void printLog(commons::LOG_LEVEL level, const char* format, ...) = 0; -}; - -class IExtensionEncoderCallback { - public: - // Destructor for the IExtensionEncoderCallback class. - virtual ~IExtensionEncoderCallback() {} - /** - * Called when a video frame has been successfully encoded. - * @param img A pointer to the encoded image data. - * @param extended_info_json A JSON formatted string containing additional information about the encoded frame. - */ - virtual void onEncodedImage(const ExtensionEncodedImage* img, const char* extended_info_json) = 0; - /** - * Logs messages at various log levels. - * @param level The log level indicating the severity of the message (e.g., INFO, WARNING, ERROR). - * @param format A format string for the log message, similar to printf formatting. - * @param ... Additional arguments to format the log message. - */ - virtual void printLog(commons::LOG_LEVEL level, const char* format, ...) = 0; -}; - -class IExtensionVideoEncoder : public RefCountInterface { - public: - /** - * Initializes the video encoder with the specified codec settings. - * @param codec_settings The video codec settings that define how the video should be encoded. - * @return - * - 0: Initialization succeeded. - * - < 0: Initialization failed, possibly due to invalid settings or internal errors. - */ - virtual int initVideoEncoder(ExtensionVideoCodecSettings codec_settings) = 0; - /** - * Registers a callback function to handle encoding events or notifications. - * @param callback A pointer to the encoder callback interface. - * @return - * - 0: Registration succeeded. - * - < 0: Registration failed, possibly due to an invalid callback pointer. - */ - virtual int32_t registerEncoderCallback(IExtensionEncoderCallback* callback) = 0; - /** - * Encodes a video frame. - * @param frame A reference to the video frame to be encoded. - * @param frame_type The type of the video frame (e.g., keyframe, delta frame). - * @return - * - 0: Encoding succeeded. - * - < 0: Encoding failed, possibly due to invalid frame data or internal errors. - */ - virtual int encode(agora_refptr frame, VIDEO_FRAME_TYPE frame_type) = 0; - /** - * Releases the resources used by the video encoder. - * @return - * - 0: Release succeeded. - * - < 0: Release failed, possibly due to the encoder not being initialized or internal errors. - */ - virtual int32_t releaseVideoEncoder() = 0; - /** - * Sets the rates for the encoder, specifying the target bitrate and framerate. - * @param bitrate_kbps The target bitrate in kilobits per second. - * @param framerate The target framerate in frames per second. - * @return - * - 0: Rate allocation succeeded. - * - < 0: Rate allocation failed, possibly due to invalid parameters or internal errors. - */ - virtual int32_t setRates(uint32_t bitrate_kbps, uint32_t framerate) = 0; - /** - * Queries the supported codec data formats. - * @param data_format A pointer to an array where supported pixel formats will be filled. - * @param size An input/output parameter; initially holds the size of the array, and will be updated with the actual number of formats filled. - */ - virtual void querySupportCodecDataFormat(media::base::VIDEO_PIXEL_FORMAT* data_format, int& size) = 0; - /** - * Sets a advanced codec property in the `IExtensionVideoEncoder` class. - * - * @param key The pointer to the property name. - * @param buf The pointer to the buffer of this private property. - * @param buf_size The buffer size of this private property. - * @return - * - The actual size of the private property, if the method call succeeds. - * - -1, if the method call fails. - */ - virtual int setAdvancedCodecProperty(const char* key, const char* json_value) = 0; - /** - * Gets a advanced codec property in the `IExtensionVideoEncoder` class. - * - * @param name The pointer to the property name. - * @param buf The pointer to the buffer of this advanced codec property. - * @param buf_size The buffer size of this advanced codec property. - * @return - * - The actual size of the advanced codec property, if the method call succeeds. - * - -1, if the method call fails. - */ - virtual int getAdvancedCodecProperty(const char* key, char* json_value, int& length) const = 0; -}; - -class IExtensionVideoDecoder : public RefCountInterface { - public: - /** - * Initializes the video decoder with the specified codec settings. - * @param codec_settings The video codec settings that specify how the video should be decoded. - * @return - * - 0: Initialization succeeded. - * - < 0: Initialization failed, possibly due to invalid settings or internal errors. - */ - virtual int initVideoDecoder(const ExtensionVideoCodecSettings& codec_settings) = 0; - /** - * Decodes a frame of encoded video data. - * @param data The encoded video data to be decoded. - * @return - * - 0: Decoding succeeded. - * - < 0: Decoding failed, possibly due to unsupported data format or internal errors. - */ - virtual int decode(const ExtensionEncodedImage& data) = 0; - /** - * Registers a callback function to handle decoded video frames. - * @param callback A pointer to the decoder callback interface. - * @return - * - 0: Registration succeeded. - * - < 0: Registration failed, possibly due to an invalid callback pointer. - */ - virtual int32_t registerDecoderCallback(IExtensionDecoderCallback* callback) = 0; - /** - * Releases the resources used by the video decoder. - * @return - * - 0: Release succeeded. - * - < 0: Release failed, possibly due to the decoder not being initialized or internal errors. - */ - virtual int32_t releaseVideoDecoder() = 0; - /** - * Queries the supported codec data formats. - * @param data_format A pointer to an array where supported pixel formats will be filled. - * @param size An input/output parameter; initially holds the size of the array, and will be updated with the actual number of formats filled. - */ - virtual void querySupportCodecDataFormat(media::base::VIDEO_PIXEL_FORMAT* data_format, int& size) = 0; - - /** - * Sets a advanced codec property in the `IExtensionVideoDecoder` class. - * - * @param key The pointer to the property name. - * @param buf The pointer to the buffer of this private property. - * @param buf_size The buffer size of this private property. - * @return - * - The actual size of the private property, if the method call succeeds. - * - -1, if the method call fails. - */ - virtual int setAdvancedCodecProperty(const char* key, const char* json_value) = 0; - /** - * Gets a advanced codec property in the `IExtensionVideoDecoder` class. - * - * @param name The pointer to the property name. - * @param buf The pointer to the buffer of this advanced codec property. - * @param buf_size The buffer size of this advanced codec property. - * @return - * - The actual size of the advanced codec property, if the method call succeeds. - * - -1, if the method call fails. - */ - virtual int getAdvancedCodecProperty(const char* key, char* json_value, int& length) const = 0; -}; -} -} diff --git a/Android/APIExample/agora-simple-filter/src/main/cpp/AgoraRtcKit/AgoraMediaBase.h b/Android/APIExample/agora-simple-filter/src/main/cpp/AgoraRtcKit/AgoraMediaBase.h index 8e25b24c5..6da9d7931 100644 --- a/Android/APIExample/agora-simple-filter/src/main/cpp/AgoraRtcKit/AgoraMediaBase.h +++ b/Android/APIExample/agora-simple-filter/src/main/cpp/AgoraRtcKit/AgoraMediaBase.h @@ -36,25 +36,26 @@ static const unsigned int DUMMY_CONNECTION_ID = (std::numeric_limits