diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Config/DefaultEditor.ini b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Config/DefaultEditor.ini new file mode 100644 index 0000000..e69de29 diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Config/DefaultEngine.ini b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Config/DefaultEngine.ini new file mode 100644 index 0000000..ccb64eb --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Config/DefaultEngine.ini @@ -0,0 +1,17 @@ + + +[/Script/HardwareTargeting.HardwareTargetingSettings] +TargetedHardwareClass=Desktop +AppliedTargetedHardwareClass=Desktop +DefaultGraphicsPerformance=Maximum +AppliedDefaultGraphicsPerformance=Maximum + +[/Script/Engine.Engine] ++ActiveGameNameRedirects=(OldGameName="TP_Blank",NewGameName="/Script/NertcSampleCode") ++ActiveGameNameRedirects=(OldGameName="/Script/TP_Blank",NewGameName="/Script/NertcSampleCode") ++ActiveClassRedirects=(OldClassName="TP_BlankGameModeBase",NewClassName="NertcSampleCodeGameModeBase") + +[/Script/EngineSettings.GameMapsSettings] +EditorStartupMap=/Game/Home.Home +GameDefaultMap=/Game/Home.Home + diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Config/DefaultGame.ini b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Config/DefaultGame.ini new file mode 100644 index 0000000..aaf77d4 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Config/DefaultGame.ini @@ -0,0 +1,3 @@ + +[/Script/EngineSettings.GeneralProjectSettings] +ProjectID=2696690546CC2874D37E89AE01510A16 diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Content/Home.umap b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Content/Home.umap new file mode 100644 index 0000000..07f0fe9 Binary files /dev/null and b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Content/Home.umap differ diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Content/UI.uasset b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Content/UI.uasset new file mode 100644 index 0000000..e25cee3 Binary files /dev/null and b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Content/UI.uasset differ diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/NertcSampleCode.uproject b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/NertcSampleCode.uproject new file mode 100644 index 0000000..34f9e4d --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/NertcSampleCode.uproject @@ -0,0 +1,17 @@ +{ + "FileVersion": 3, + "EngineAssociation": "4.25", + "Category": "", + "Description": "", + "Modules": [ + { + "Name": "NertcSampleCode", + "Type": "Runtime", + "LoadingPhase": "Default", + "AdditionalDependencies": [ + "UMGEditor", + "UMG" + ] + } + ] +} \ No newline at end of file diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/NertcPlugin.uplugin b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/NertcPlugin.uplugin new file mode 100644 index 0000000..886b8c6 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/NertcPlugin.uplugin @@ -0,0 +1,33 @@ +{ + "FileVersion": 3, + "Version": 1, + "VersionName": "1.0", + "FriendlyName": "NertcPlugin", + "Description": "", + "Category": "Other", + "CreatedBy": "", + "CreatedByURL": "", + "DocsURL": "", + "MarketplaceURL": "", + "SupportURL": "", + "CanContainContent": true, + "IsBetaVersion": false, + "IsExperimentalVersion": false, + "Installed": false, + "Modules": [ + { + "Name": "NertcPlugin", + "Type": "Runtime", + "LoadingPhase": "Default", + "WhitelistPlatforms" : [ + "Win64", + "Mac", + "Android", + "IOS" + ], + "BlacklistPlatforms": [ + + ] + } + ] +} \ No newline at end of file diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Resources/Icon128.png b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Resources/Icon128.png new file mode 100644 index 0000000..1231d4a Binary files /dev/null and b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Resources/Icon128.png differ diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/NertcPlugin.Build.cs b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/NertcPlugin.Build.cs new file mode 100644 index 0000000..929ce0a --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/NertcPlugin.Build.cs @@ -0,0 +1,57 @@ +// Copyright Epic Games, Inc. All Rights Reserved. +using System.IO; +using UnrealBuildTool; + +public class NertcPlugin : ModuleRules +{ + public NertcPlugin(ReadOnlyTargetRules Target) : base(Target) + { + PCHUsage = ModuleRules.PCHUsageMode.UseExplicitOrSharedPCHs; + + PublicIncludePaths.AddRange( + new string[] { + // ... add public include paths required here ... + } + ); + + + PrivateIncludePaths.AddRange( + new string[] { + // ... add other private include paths required here ... + } + ); + + + PublicDependencyModuleNames.AddRange( + new string[] + { + "Core", + "Nertc", + "Projects" + // ... add other public dependencies that you statically link with here ... + } + ); + + + PrivateDependencyModuleNames.AddRange( + new string[] + { + "CoreUObject", + "Engine", + "Slate", + "SlateCore", + "UMG", + "AndroidPermission", + // ... add private dependencies that you statically link with here ... + } + ); + + + DynamicallyLoadedModuleNames.AddRange( + new string[] + { + // ... add any modules that your module loads dynamically here ... + } + ); + } +} diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcAudioDeviceManager.cpp b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcAudioDeviceManager.cpp new file mode 100644 index 0000000..b30ee7b --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcAudioDeviceManager.cpp @@ -0,0 +1,86 @@ +// Copyright Epic Games, Inc. All Rights Reserved. + +#include "NertcAudioDeviceManager.h" + +#include "Nertc/api/nertc_engine.h" +#include "Nertc/api/nertc_engine_ex.h" +#include "Nertc/api/nertc_audio_device_manager.h" + +#include + +namespace nertc { + NertcAudioDeviceManager::NertcAudioDeviceManager(nertc_audio_device_manager* manager) :m_nertc_audio_device_manager(manager){ + + } + IDeviceCollection* NertcAudioDeviceManager::enumerateRecordDevices() { + auto csdk_collection = nertc_audio_device_manager_enumerate_record_devices(m_nertc_audio_device_manager); + if (csdk_collection) { + return new NertcDeviceCollection(csdk_collection); + } + return nullptr; + } + int NertcAudioDeviceManager::setRecordDevice(const char device_id[kNERtcMaxDeviceIDLength]) { + return nertc_audio_device_manager_set_record_device(m_nertc_audio_device_manager, device_id); + } + int NertcAudioDeviceManager::getRecordDevice(char device_id[kNERtcMaxDeviceIDLength]) { + return nertc_audio_device_manager_get_record_device(m_nertc_audio_device_manager, device_id); + } + IDeviceCollection* NertcAudioDeviceManager::enumeratePlayoutDevices() { + auto csdk_collection = nertc_audio_device_manager_enumerate_playout_devices(m_nertc_audio_device_manager); + return new NertcDeviceCollection(csdk_collection); + } + int NertcAudioDeviceManager::setPlayoutDevice(const char device_id[kNERtcMaxDeviceIDLength]) { + return nertc_audio_device_manager_set_playout_device(m_nertc_audio_device_manager, device_id); + } + int NertcAudioDeviceManager::getPlayoutDevice(char device_id[kNERtcMaxDeviceIDLength]) { + return nertc_audio_device_manager_get_playout_device(m_nertc_audio_device_manager, device_id); + } + // Device volume manager + // The volume value: [0, 255] + int NertcAudioDeviceManager::setRecordDeviceVolume(uint32_t volume) { + return nertc_audio_device_manager_set_record_device_volume(m_nertc_audio_device_manager, volume); + } + int NertcAudioDeviceManager::getRecordDeviceVolume(uint32_t* volume) { + return nertc_audio_device_manager_get_record_device_volume(m_nertc_audio_device_manager, volume); + } + int NertcAudioDeviceManager::setPlayoutDeviceVolume(uint32_t volume) { + return nertc_audio_device_manager_set_playout_device_volume(m_nertc_audio_device_manager, volume); + } + int NertcAudioDeviceManager::getPlayoutDeviceVolume(uint32_t* volume) { + return nertc_audio_device_manager_get_playout_device_volume(m_nertc_audio_device_manager, volume); + } + + int NertcAudioDeviceManager::setPlayoutDeviceMute(bool mute) { + return nertc_audio_device_manager_set_playout_device_mute(m_nertc_audio_device_manager, mute); + } + int NertcAudioDeviceManager::getPlayoutDeviceMute(bool* mute) { + return nertc_audio_device_manager_get_playout_device_mute(m_nertc_audio_device_manager, mute); + } + int NertcAudioDeviceManager::setRecordDeviceMute(bool mute) { + return nertc_audio_device_manager_set_record_device_mute(m_nertc_audio_device_manager, mute); + } + int NertcAudioDeviceManager::getRecordDeviceMute(bool* mute) { + return nertc_audio_device_manager_get_record_device_mute(m_nertc_audio_device_manager, mute); + } + + // Device test + // NOTE: Recoding and loopback test can not being started at the same time + int NertcAudioDeviceManager::startRecordDeviceTest(uint64_t indication_interval) { + return nertc_audio_device_manager_start_record_device_test(m_nertc_audio_device_manager, indication_interval); + } + int NertcAudioDeviceManager::stopRecordDeviceTest() { + return nertc_audio_device_manager_stop_record_device_test(m_nertc_audio_device_manager); + } + int NertcAudioDeviceManager::startPlayoutDeviceTest(const char* test_audio_file_path) { + return nertc_audio_device_manager_start_playout_device_test(m_nertc_audio_device_manager, test_audio_file_path); + } + int NertcAudioDeviceManager::stopPlayoutDeviceTest() { + return nertc_audio_device_manager_stop_playout_device_test(m_nertc_audio_device_manager); + } + int NertcAudioDeviceManager::startAudioDeviceLoopbackTest(uint64_t indication_interval) { + return nertc_audio_device_manager_start_audio_device_loopback_test(m_nertc_audio_device_manager, indication_interval); + } + int NertcAudioDeviceManager::stopAudioDeviceLoopbackTest() { + return nertc_audio_device_manager_stop_audio_device_loopback_test(m_nertc_audio_device_manager); + } +} \ No newline at end of file diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcAudioDeviceManager.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcAudioDeviceManager.h new file mode 100644 index 0000000..7d8ca55 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcAudioDeviceManager.h @@ -0,0 +1,72 @@ +/** @file NertcAudioDeviceManager.h + * @brief The interface header file of audio device management of the NERTC UE SDK. + * All parameter descriptions of the NERTC UE SDK. All string-related parameters (char *) are encoded in UTF-8. + * @copyright (c) 2021 NetEase, Inc. All rights reserved. + */ + +#pragma once +#include "NertcDeviceCollection.h" +#include "INertcAudioDeviceManager.h" +#include +//#include "Nertc/include/nertc_engine_ex.h" + +struct nertc_audio_device_manager; +namespace nertc { +class NertcEngine; + +class NertcAudioDeviceManager:public IAudioDeviceManager { +public: + NertcAudioDeviceManager() = default; + NertcAudioDeviceManager(const NertcAudioDeviceManager& other) = delete; + NertcAudioDeviceManager(NertcAudioDeviceManager&& other) noexcept = delete; + NertcAudioDeviceManager& operator=(const NertcAudioDeviceManager& other) = delete; + NertcAudioDeviceManager& operator=(NertcAudioDeviceManager&& other) noexcept = delete; + virtual ~NertcAudioDeviceManager() = default; +private: + friend class NertcEngineEx; + NertcAudioDeviceManager(nertc_audio_device_manager* manager); +public: + +IDeviceCollection* enumerateRecordDevices() override; + +int setRecordDevice(const char device_id[kNERtcMaxDeviceIDLength]) override; + +int getRecordDevice(char device_id[kNERtcMaxDeviceIDLength]) override; + +IDeviceCollection* enumeratePlayoutDevices() override; + +int setPlayoutDevice(const char device_id[kNERtcMaxDeviceIDLength]) override; + +int getPlayoutDevice(char device_id[kNERtcMaxDeviceIDLength]) override; + +int setRecordDeviceVolume(uint32_t volume) override; + +int getRecordDeviceVolume(uint32_t* volume) override; + +int setPlayoutDeviceVolume(uint32_t volume) override; + +int getPlayoutDeviceVolume(uint32_t* volume) override; + +int setPlayoutDeviceMute(bool mute) override; + +int getPlayoutDeviceMute(bool* mute) override; + +int setRecordDeviceMute(bool mute) override; + +int getRecordDeviceMute(bool* mute) override; + +int startRecordDeviceTest(uint64_t indication_interval) override; + +int stopRecordDeviceTest() override; + +int startPlayoutDeviceTest(const char* test_audio_file_path) override; + +int stopPlayoutDeviceTest() override; + +int startAudioDeviceLoopbackTest(uint64_t indication_interval) override; + +int stopAudioDeviceLoopbackTest() override; +private: +nertc_audio_device_manager* m_nertc_audio_device_manager{ nullptr }; +}; +} \ No newline at end of file diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcAudioFrameObserver.cpp b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcAudioFrameObserver.cpp new file mode 100644 index 0000000..34cab99 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcAudioFrameObserver.cpp @@ -0,0 +1,59 @@ +// Copyright Epic Games, Inc. All Rights Reserved. + +#include "NertcEngineEx.h" +#include "NertcEngineUtil.h" +#include +namespace nertc { + static std::map g_engine_audio_observer_map; + namespace { + void on_audio_frame_did_record(void* self, struct nertc_audio_frame* frame) { + if (g_engine_audio_observer_map.find(self) == g_engine_audio_observer_map.end()) + return; + NERtcAudioFrame nertc_frame{}; + convertToNertcStruct(*frame, nertc_frame); + g_engine_audio_observer_map[self]->onAudioFrameDidRecord(&nertc_frame); + } + void on_audio_frame_will_playback(void* self, struct nertc_audio_frame* frame) { + if (g_engine_audio_observer_map.find(self) == g_engine_audio_observer_map.end()) + return; + NERtcAudioFrame nertc_frame{}; + convertToNertcStruct(*frame, nertc_frame); + g_engine_audio_observer_map[self]->onAudioFrameWillPlayback(&nertc_frame); + } + void on_mixed_audio_frame(void* self, struct nertc_audio_frame* frame) { + if (g_engine_audio_observer_map.find(self) == g_engine_audio_observer_map.end()) + return; + NERtcAudioFrame nertc_frame{}; + convertToNertcStruct(*frame, nertc_frame); + g_engine_audio_observer_map[self]->onMixedAudioFrame(&nertc_frame); + } + void on_playback_audio_frame_before_mixing(void* self, uint64_t user_id, struct nertc_audio_frame* frame, channel_id_t cid) { + if (g_engine_audio_observer_map.find(self) == g_engine_audio_observer_map.end()) + return; + NERtcAudioFrame nertc_frame{}; + convertToNertcStruct(*frame, nertc_frame); + g_engine_audio_observer_map[self]->onPlaybackAudioFrameBeforeMixing(user_id, &nertc_frame, cid); + } + } + void NertcEngineEx::clearCsdkAudioFrameObserver() { + //g_engine_audio_observer_map.erase(m_nertc_engine); + g_engine_audio_observer_map.clear(); + } + void NertcEngineEx::fillCsdkAudioFrameObserver(INERtcAudioFrameObserver* observer) { + g_engine_audio_observer_map[m_nertc_engine] = observer; + if (!m_nertc_audio_frame_observer) { + m_nertc_audio_frame_observer = new nertc_audio_frame_observer(); + } + if (!observer) { + *m_nertc_audio_frame_observer = nertc_audio_frame_observer{}; + } + m_nertc_audio_frame_observer->self = m_nertc_engine; + + m_nertc_audio_frame_observer->on_audio_frame_did_record = on_audio_frame_did_record; + m_nertc_audio_frame_observer->on_audio_frame_will_playback = on_audio_frame_will_playback; + m_nertc_audio_frame_observer->on_mixed_audio_frame = on_mixed_audio_frame; + m_nertc_audio_frame_observer->on_playback_audio_frame_before_mixing = on_playback_audio_frame_before_mixing; + } + + +} \ No newline at end of file diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcDeviceCollection.cpp b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcDeviceCollection.cpp new file mode 100644 index 0000000..7029064 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcDeviceCollection.cpp @@ -0,0 +1,48 @@ +// Copyright Epic Games, Inc. All Rights Reserved. + +#include "NertcDeviceCollection.h" +#include "Nertc/api/nertc_device_collection.h" +#include "NertcEngineUtil.h" +#include + +namespace nertc { + NertcDeviceCollection::NertcDeviceCollection(const NertcDeviceCollection& other):m_nertc_collection(other.m_nertc_collection) { + + } + NertcDeviceCollection::NertcDeviceCollection(nertc_device_collection* collection) :m_nertc_collection(collection) { + + } + NertcDeviceCollection::NertcDeviceCollection(NertcDeviceCollection&& other) noexcept :m_nertc_collection(std::exchange(other.m_nertc_collection, nullptr)) { + + } + NertcDeviceCollection& NertcDeviceCollection::operator=(const NertcDeviceCollection& other) { + return *this = NertcDeviceCollection(other); + } + NertcDeviceCollection& NertcDeviceCollection::operator=(NertcDeviceCollection&& other) noexcept { + std::swap(m_nertc_collection, other.m_nertc_collection); + return *this; + } + NertcDeviceCollection::~NertcDeviceCollection() { + if (!m_nertc_collection) { + nertc_device_collection_destroy(m_nertc_collection); + m_nertc_collection = nullptr; + } + }; + uint16_t NertcDeviceCollection::getCount() { + return nertc_device_collection_get_count(m_nertc_collection); + } + int NertcDeviceCollection::getDevice(uint16_t index, + char device_name[kNERtcMaxDeviceNameLength], + char device_id[kNERtcMaxDeviceIDLength]) { + return nertc_device_collection_get_device(m_nertc_collection, index, device_name, device_id); + } + int NertcDeviceCollection::getDeviceInfo(uint16_t index, NERtcDeviceInfo* device_info) { + nertc_device_info info{}; + + auto ret = nertc_device_collection_get_device_info(m_nertc_collection, index, &info); + if (device_info) { + convertToNertcStruct(info, *device_info); + } + return ret; + } +} \ No newline at end of file diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcDeviceCollection.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcDeviceCollection.h new file mode 100644 index 0000000..f55cd6a --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcDeviceCollection.h @@ -0,0 +1,38 @@ +/** + * @file NertcDeviceCollection.h + * @brief The interface header file of NERTC UE SDK device NERTC UE SDK device collection. + * All parameter descriptions of the NERTC SDK. All string-related parameters (char *) are encoded in UTF-8. + * @copyright (c) 2021, NetEase Inc. All rights reserved. + */ +#pragma once +#include "INertcDeviceCollection.h" +#include "Nertc/api/nertc_engine.h" +#include "Nertc/api/nertc_engine_ex.h" +#include + +struct nertc_device_collection; +namespace nertc { +class NertcAudioDeviceManager; +class NertcDeviceCollection:public IDeviceCollection { +public: +NertcDeviceCollection() = delete; +NertcDeviceCollection(const NertcDeviceCollection& other); +NertcDeviceCollection(NertcDeviceCollection&& other) noexcept; +NertcDeviceCollection& operator=(const NertcDeviceCollection& other); +NertcDeviceCollection& operator=(NertcDeviceCollection&& other) noexcept; +virtual ~NertcDeviceCollection(); +private: + friend class NertcAudioDeviceManager; + NertcDeviceCollection(nertc_device_collection* collection); +public: + +uint16_t getCount() override; + +int getDevice(uint16_t index, char device_name[kNERtcMaxDeviceNameLength], char device_id[kNERtcMaxDeviceIDLength]) override; + +int getDeviceInfo(uint16_t index, NERtcDeviceInfo* device_info) override; + +private: +nertc_device_collection* m_nertc_collection{ nullptr }; +}; +} \ No newline at end of file diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcEngineEvent.cpp b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcEngineEvent.cpp new file mode 100644 index 0000000..baf8d61 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcEngineEvent.cpp @@ -0,0 +1,365 @@ +// Copyright Epic Games, Inc. All Rights Reserved. + +#include "NertcEngineEx.h" +#include "NertcEngineUtil.h" + +#include "Nertc/api/nertc_engine_defines.h" +#include "Nertc/api/nertc_engine.h" +#include "Nertc/api/nertc_engine_events.h" + +#include +//#include +static std::map g_engine_handler_map; +namespace engine_sink { + ////////////////////////////////IRtcEngineEventHandler//////////////////////////////////// + void on_error(void* self, int error_code, const char* msg) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onError(error_code, msg); + } + + void on_warning(void* self, int warn_code, const char* msg) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onWarning(warn_code, msg); + } + void on_join_channel(void* self, channel_id_t cid, nertc_uid_t uid, nertc_error_code result, uint64_t elapsed) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onJoinChannel(cid, uid, (nertc::NERtcErrorCode)result, elapsed); + } + void on_reconnecting_start(void* self, channel_id_t cid, nertc_uid_t uid) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onReconnectingStart(cid, uid); + } + void on_connection_state_change(void* self, nertc_connection_state_type state, nertc_reason_connection_changed_type reason) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onConnectionStateChange((nertc::NERtcConnectionStateType)state, (nertc::NERtcReasonConnectionChangedType)reason); + } + void on_rejoin_channel(void* self, channel_id_t cid, nertc_uid_t uid, nertc_error_code result, uint64_t elapsed) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onRejoinChannel(cid, uid, (nertc::NERtcErrorCode)result, elapsed); + } + void on_leave_channel(void* self, nertc_error_code result, uint64_t channel_id) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onLeaveChannel((nertc::NERtcErrorCode)result, channel_id); + } + void on_disconnect(void* self, nertc_error_code reason) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onDisconnect((nertc::NERtcErrorCode)reason); + } + void on_client_role_changed(void* self, nertc_client_role old_role, nertc_client_role new_role) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onClientRoleChanged((nertc::NERtcClientRole)old_role, (nertc::NERtcClientRole)new_role); + } + void on_user_joined(void* self, nertc_uid_t uid, const char* user_name, const struct nertc_user_join_extra_info* custom_info) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + nertc::NERtcUserJoinExtraInfo extra_info; + if (custom_info) { + convertToNertcStruct(*custom_info, extra_info); + } + g_engine_handler_map[self]->onUserJoined(uid, user_name, extra_info); + } + void on_user_left(void* self, nertc_uid_t uid, nertc_session_leave_reason reason, const struct nertc_user_join_extra_info* custom_info) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + nertc::NERtcUserJoinExtraInfo extra_info; + if (custom_info) { + convertToNertcStruct(*custom_info, extra_info); + } + g_engine_handler_map[self]->onUserLeft(uid, (nertc::NERtcSessionLeaveReason)reason, extra_info); + } + void on_user_audio_start(void* self, nertc_audio_stream_type type, nertc_uid_t uid) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onUserAudioStart(nertc::NERtcAudioStreamType(type), uid); + } + void on_user_audio_stop(void* self, nertc_audio_stream_type type, nertc_uid_t uid) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onUserAudioStop(nertc::NERtcAudioStreamType(type), uid); + } + void on_user_video_start(void* self, nertc_video_stream_type type, nertc_uid_t uid, nertc_video_profile_type max_profile) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onUserVideoStart(nertc::NERtcVideoStreamType(type), uid, (nertc::NERtcVideoProfileType)max_profile); + } + void on_user_video_stop(void* self, nertc_video_stream_type type, nertc_uid_t uid) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onUserVideoStop(nertc::NERtcVideoStreamType(type), uid); + } + + ////////////////////////////////IRtcEngineEventHandlerEx//////////////////////////////////// + + void on_screen_capture_state_changed(void* self, nertc_screen_capture_status status) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onScreenCaptureStatusChanged((nertc::NERtcScreenCaptureStatus)status); + } + void on_user_video_profile_update(void* self, nertc_uid_t uid, nertc_video_profile_type max_profile) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onUserVideoProfileUpdate(uid, (nertc::NERtcVideoProfileType)max_profile); + } + void on_user_audio_mute(void* self, nertc_audio_stream_type type, nertc_uid_t uid, bool mute) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onUserAudioMute(nertc::NERtcAudioStreamType(type), uid, mute); + } + void on_user_video_mute(void* self, nertc_video_stream_type type, nertc_uid_t uid, bool mute) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onUserVideoMute(nertc::NERtcVideoStreamType(type), uid, mute); + } + void on_audio_device_state_changed(void* self, const char* device_id, nertc_audio_device_type device_type, nertc_audio_device_state device_state) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onAudioDeviceStateChanged(device_id, (nertc::NERtcAudioDeviceType)device_type, (nertc::NERtcAudioDeviceState)device_state); + } + void on_audio_default_device_changed(void* self, const char* device_id, nertc_audio_device_type device_type) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onAudioDefaultDeviceChanged(device_id, (nertc::NERtcAudioDeviceType)device_type); + } + void on_video_device_state_changed(void* self, const char* device_id, nertc_video_device_type device_type, nertc_video_device_state device_state) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onVideoDeviceStateChanged(device_id, (nertc::NERtcVideoDeviceType)device_type, (nertc::NERtcVideoDeviceState)device_state); + } + void on_camera_focus_changed(void* self, const struct nertc_camera_focus_and_exposure_info* info) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + nertc::NERtcCameraFocusAndExposureInfo nertc_info{}; + if (info) { + convertToNertcStruct(*info, nertc_info); + } + g_engine_handler_map[self]->onCameraFocusChanged(nertc_info); + } + void on_camera_exposure_changed(void* self, const struct nertc_camera_focus_and_exposure_info* info) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + nertc::NERtcCameraFocusAndExposureInfo nertc_info{}; + if (info) { + convertToNertcStruct(*info, nertc_info); + } + g_engine_handler_map[self]->onCameraExposureChanged(nertc_info); + } + void on_first_audio_data_received(void* self, nertc_audio_stream_type type, nertc_uid_t uid) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onFirstAudioDataReceived(nertc::NERtcAudioStreamType(type), uid); + } + void on_first_video_data_received(void* self, nertc_video_stream_type type, nertc_uid_t uid) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onFirstVideoDataReceived(nertc::NERtcVideoStreamType(type), uid); + } + void on_first_audio_frame_decoded(void* self, nertc_audio_stream_type type, nertc_uid_t uid) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onFirstAudioFrameDecoded(nertc::NERtcAudioStreamType(type), uid); + } + void on_first_video_frame_decoded(void* self, nertc_video_stream_type type, nertc_uid_t uid, uint32_t width, uint32_t height) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onFirstVideoFrameDecoded(nertc::NERtcVideoStreamType(type), uid, width, height); + } + + void on_capture_video_frame(void* self, + void* data, + nertc_video_type type, + uint32_t width, + uint32_t height, + uint32_t count, + uint32_t* offset, + uint32_t* stride, + nertc_video_rotation rotation) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onCaptureVideoFrame(data, (nertc::NERtcVideoType)type, width, height, count, offset, stride, (nertc::NERtcVideoRotation)rotation); + } + void on_audio_mixing_state_changed(void* self, nertc_audio_mixing_state state, nertc_audio_mixing_error_code error_code) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onAudioMixingStateChanged((nertc::NERtcAudioMixingState)state, (nertc::NERtcAudioMixingErrorCode)error_code); + } + void on_audio_mixing_timestamp_update(void* self, uint64_t timestamp_ms) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onAudioMixingTimestampUpdate(timestamp_ms); + } + void on_audio_effect_finished(void* self, uint32_t effect_id) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onAudioEffectFinished(effect_id); + } + void on_local_audio_volume_indication(void* self, int volume, bool enable_vad) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onLocalAudioVolumeIndication(volume, enable_vad); + } + void on_remote_audio_volume_indication(void* self, const struct nertc_audio_volume_info* speakers, uint32_t speaker_number, int total_volume) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + nertc::NERtcAudioVolumeInfo* nertc_speakers = nullptr; + auto windup_cb = convertToNertcStruct(speakers, speaker_number, nertc_speakers); + g_engine_handler_map[self]->onRemoteAudioVolumeIndication(nertc_speakers, speaker_number, total_volume); + windup_cb(); + } + void on_add_live_stream_task(void* self, const char* task_id, const char* url, int error_code) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onAddLiveStreamTask(task_id, url, error_code); + } + void on_update_live_stream_task(void* self, const char* task_id, const char* url, int error_code) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onUpdateLiveStreamTask(task_id, url, error_code); + } + void on_remove_live_stream_task(void* self, const char* task_id, int error_code) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onRemoveLiveStreamTask(task_id, error_code); + } + void on_live_stream_state_changed(void* self, const char* task_id, const char* url, nertc_live_stream_state_code state) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onLiveStreamStateChanged(task_id, url, (nertc::NERtcLiveStreamStateCode)state); + } + void on_audio_howling(void* self, bool howling) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onAudioHowling(howling); + } + void on_receive_sei_message(void* self, nertc_uid_t uid, const uint8_t* data, uint32_t dataSize) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onRecvSEIMsg(uid, data, dataSize); + } + void on_audio_recording(void* self, nertc_audio_recording_code code, const char* file_path) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onAudioRecording((nertc::NERtcAudioRecordingCode)code, file_path); + } + void on_media_relay_state_changed(void* self, nertc_channel_media_relay_state state, const char* channel_name) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onMediaRelayStateChanged((nertc::NERtcChannelMediaRelayState)state, channel_name); + } + void on_media_relay_event(void* self, nertc_channel_media_relay_event event, const char* channel_name, nertc_error_code error) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onMediaRelayEvent((nertc::NERtcChannelMediaRelayEvent)event, channel_name, (nertc::NERtcErrorCode)error); + } + void on_publish_fallback_to_audio_only(void* self, bool is_fallback, nertc_video_stream_type stream_type) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onPublishFallbackToAudioOnly(is_fallback, (nertc::NERtcVideoStreamType)stream_type); + } + void on_subscribe_fallback_to_audio_only(void* self, nertc_uid_t uid, bool is_fallback, nertc_video_stream_type stream_type) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onSubscribeFallbackToAudioOnly(uid, is_fallback, (nertc::NERtcVideoStreamType)stream_type); + } + void on_lastmile_quality(void* self, nertc_network_quality_type quality) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + g_engine_handler_map[self]->onLastmileQuality((nertc::NERtcNetworkQualityType)quality); + } + void on_lastmile_probe_result(void* self, const struct nertc_lastmile_probe_result* result) { + if (g_engine_handler_map.find(self) == g_engine_handler_map.end()) + return; + nertc::NERtcLastmileProbeResult nertc_result{}; + convertToNertcStruct(*result, nertc_result); + g_engine_handler_map[self]->onLastmileProbeResult(nertc_result); + } + /* + void on_client_virtual_human_data(void* self, nertc_uid_t uid, const uint8_t* data, uint32_t dataSize) { + } + void on_user_virtual_human_start(void* self, nertc_uid_t uid) { + } + void on_user_virtual_human_stop(void* self, nertc_uid_t uid) { + } + */ + +} +namespace nertc { + + void NertcEngineEx::fillCsdkEventHandler(IRtcEngineEventHandler* handler) { + g_engine_handler_map[m_nertc_engine] = handler; + if (!m_nertc_engine_event) { + m_nertc_engine_event = new nertc_engine_events{0}; + } + + if (!handler) { + //clear callback + *m_nertc_engine_event = nertc_engine_events{0}; + return; + } + m_nertc_engine_event->self = m_nertc_engine; + + m_nertc_engine_event->on_error = engine_sink::on_error; + m_nertc_engine_event->on_warning = engine_sink::on_warning; + m_nertc_engine_event->on_join_channel = engine_sink::on_join_channel; + m_nertc_engine_event->on_reconnecting_start = engine_sink::on_reconnecting_start; + m_nertc_engine_event->on_connection_state_change = engine_sink::on_connection_state_change; + m_nertc_engine_event->on_rejoin_channel = engine_sink::on_rejoin_channel; + m_nertc_engine_event->on_leave_channel = engine_sink::on_leave_channel; + m_nertc_engine_event->on_disconnect = engine_sink::on_disconnect; + m_nertc_engine_event->on_client_role_changed = engine_sink::on_client_role_changed; + m_nertc_engine_event->on_user_joined = engine_sink::on_user_joined; + m_nertc_engine_event->on_user_left = engine_sink::on_user_left; + m_nertc_engine_event->on_user_audio_start = engine_sink::on_user_audio_start; + m_nertc_engine_event->on_user_audio_stop = engine_sink::on_user_audio_stop; + //m_nertc_engine_event->on_user_video_start = engine_sink::on_user_video_start; + //m_nertc_engine_event->on_user_video_stop = engine_sink::on_user_video_stop; + + //m_nertc_engine_event->on_screen_capture_state_changed = engine_sink::on_screen_capture_state_changed; + //m_nertc_engine_event->on_user_video_profile_update = engine_sink::on_user_video_profile_update; + m_nertc_engine_event->on_user_audio_mute = engine_sink::on_user_audio_mute; + m_nertc_engine_event->on_audio_device_state_changed = engine_sink::on_audio_device_state_changed; + m_nertc_engine_event->on_audio_default_device_changed = engine_sink::on_audio_default_device_changed; + //m_nertc_engine_event->on_video_device_state_changed = engine_sink::on_video_device_state_changed; + //m_nertc_engine_event->on_camera_focus_changed = engine_sink::on_camera_focus_changed; + //m_nertc_engine_event->on_camera_exposure_changed = engine_sink::on_camera_exposure_changed; + m_nertc_engine_event->on_first_audio_data_received = engine_sink::on_first_audio_data_received; + //m_nertc_engine_event->on_first_video_data_received = engine_sink::on_first_video_data_received; + m_nertc_engine_event->on_first_audio_frame_decoded = engine_sink::on_first_audio_frame_decoded; + //m_nertc_engine_event->on_first_video_frame_decoded = engine_sink::on_first_video_frame_decoded; + //m_nertc_engine_event->on_capture_video_frame = engine_sink::on_capture_video_frame; + //m_nertc_engine_event->on_audio_mixing_state_changed = engine_sink::on_audio_mixing_state_changed; + //m_nertc_engine_event->on_audio_mixing_timestamp_update = engine_sink::on_audio_mixing_timestamp_update; + //m_nertc_engine_event->on_audio_effect_finished = engine_sink::on_audio_effect_finished; + m_nertc_engine_event->on_local_audio_volume_indication = engine_sink::on_local_audio_volume_indication; + m_nertc_engine_event->on_remote_audio_volume_indication = engine_sink::on_remote_audio_volume_indication; + //m_nertc_engine_event->on_add_live_stream_task = engine_sink::on_add_live_stream_task; + //m_nertc_engine_event->on_update_live_stream_task = engine_sink::on_update_live_stream_task; + //m_nertc_engine_event->on_remove_live_stream_task = engine_sink::on_remove_live_stream_task; + //m_nertc_engine_event->on_live_stream_state_changed = engine_sink::on_live_stream_state_changed; + m_nertc_engine_event->on_audio_howling = engine_sink::on_audio_howling; + //m_nertc_engine_event->on_receive_sei_message = engine_sink::on_receive_sei_message; + m_nertc_engine_event->on_audio_recording = engine_sink::on_audio_recording; + //m_nertc_engine_event->on_media_relay_state_changed = engine_sink::on_media_relay_state_changed; + //m_nertc_engine_event->on_media_relay_event = engine_sink::on_media_relay_event; + //m_nertc_engine_event->on_publish_fallback_to_audio_only = engine_sink::on_publish_fallback_to_audio_only; + //m_nertc_engine_event->on_subscribe_fallback_to_audio_only = engine_sink::on_subscribe_fallback_to_audio_only; + //m_nertc_engine_event->on_lastmile_quality = engine_sink::on_lastmile_quality; + //m_nertc_engine_event->on_lastmile_probe_result = engine_sink::on_lastmile_probe_result; + + //m_nertc_engine_event->on_client_virtual_human_data = engine_sink::on_client_virtual_human_data; + //m_nertc_engine_event->on_user_virtual_human_start = engine_sink::on_user_virtual_human_start; + //m_nertc_engine_event->on_user_virtual_human_stop = engine_sink::on_user_virtual_human_stop; + } + + void NertcEngineEx::clearCsdkEventHandler() { + g_engine_handler_map.clear(); + } +} \ No newline at end of file diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcEngineEx.cpp b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcEngineEx.cpp new file mode 100644 index 0000000..291cee1 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcEngineEx.cpp @@ -0,0 +1,324 @@ +// Copyright Epic Games, Inc. All Rights Reserved. + +#include "NertcEngineEx.h" +#include "NertcAudioDeviceManager.h" +#include "NertcEngineUtil.h" +#include "Nertc/api/nertc_engine.h" +#include "Nertc/api/nertc_engine_ex.h" +#include + +#if !WITH_EDITOR && PLATFORM_ANDROID +#include "Android/AndroidApplication.h" +#include "AndroidPermission/Classes/AndroidPermissionFunctionLibrary.h" +#include "AndroidPermission/Classes/AndroidPermissionCallbackProxy.h" +#include "Android/AndroidJni.h" +#endif + +namespace nertc { + IRtcEngineEx* createNERtcEngine() { + nertc_engine* csdk_nertc_engine = create_nertc_engine(); + if (csdk_nertc_engine) { + return new NertcEngineEx(csdk_nertc_engine); + } + return nullptr; + } + + NertcEngineEx::NertcEngineEx(const NertcEngineEx& other):m_nertc_engine(other.m_nertc_engine){ + + } + NertcEngineEx::NertcEngineEx(NertcEngineEx&& other)noexcept: m_nertc_engine(std::exchange(other.m_nertc_engine, nullptr)){ + + } + NertcEngineEx& NertcEngineEx::operator=(const NertcEngineEx& other) { + return *this = NertcEngineEx(other); + } + NertcEngineEx& NertcEngineEx::operator=(NertcEngineEx&& other) noexcept { + std::swap(m_nertc_engine, other.m_nertc_engine); + return *this; + } + NertcEngineEx::~NertcEngineEx(){ + ::destroy_nertc_engine(m_nertc_engine); + m_nertc_engine = nullptr; + if (m_nertc_audio_frame_observer) { + delete m_nertc_audio_frame_observer; + m_nertc_audio_frame_observer = nullptr; + } + if (m_nertc_media_stats_observer) { + delete m_nertc_media_stats_observer; + m_nertc_media_stats_observer = nullptr; + } + if (m_nertc_engine_event) { + delete m_nertc_engine_event; + m_nertc_engine_event = nullptr; + } + + clearCsdkAudioFrameObserver(); + clearCsdkMediaStatsObserver(); + clearCsdkEventHandler(); + } + NertcEngineEx::NertcEngineEx(nertc_engine* engine):m_nertc_engine(engine){ + + } + /////////////////////////////////////////////////////////////// + + int NertcEngineEx::initialize(const NERtcEngineContext& context) { + nertc_engine_context csdk_context{}; + csdk_context.app_key = context.app_key; + csdk_context.log_dir_path = context.log_dir_path; + csdk_context.log_level = (nertc_log_level)context.log_level; + csdk_context.log_file_max_size_kbytes = context.log_file_max_size_KBytes; + memcpy(csdk_context.server_config.channel_server, context.server_config.channel_server, kNERtcMaxURILength); + memcpy(csdk_context.server_config.statistics_server, context.server_config.statistics_server, kNERtcMaxURILength); + memcpy(csdk_context.server_config.statistics_dispatch_server, context.server_config.statistics_dispatch_server, kNERtcMaxURILength); + memcpy(csdk_context.server_config.statistics_backup_server, context.server_config.statistics_backup_server, kNERtcMaxURILength); + memcpy(csdk_context.server_config.room_server, context.server_config.room_server, kNERtcMaxURILength); + memcpy(csdk_context.server_config.compat_server, context.server_config.compat_server, kNERtcMaxURILength); + memcpy(csdk_context.server_config.nos_lbs_server, context.server_config.nos_lbs_server, kNERtcMaxURILength); + memcpy(csdk_context.server_config.nos_upload_sever, context.server_config.nos_upload_sever, kNERtcMaxURILength); + memcpy(csdk_context.server_config.nos_token_server, context.server_config.nos_token_server, kNERtcMaxURILength); + memcpy(csdk_context.server_config.cloud_proxy_server, context.server_config.cloud_proxy_server, kNERtcMaxURILength); + memcpy(csdk_context.server_config.websocket_proxy_server, context.server_config.websocket_proxy_server, kNERtcMaxURILength); + memcpy(csdk_context.server_config.quic_proxy_server, context.server_config.quic_proxy_server, kNERtcMaxURILength); + memcpy(csdk_context.server_config.media_proxy_server, context.server_config.media_proxy_server, kNERtcMaxURILength); + csdk_context.server_config.use_ipv6 = context.server_config.use_ipv6; + if (!m_nertc_engine_event) { + m_nertc_engine_event = new nertc_engine_events(); + } + fillCsdkEventHandler(context.event_handler); + csdk_context.events = *m_nertc_engine_event; + + auto ret = nertc_engine_init(m_nertc_engine, &csdk_context); + nertc_engine_set_parameters(m_nertc_engine, "{\"sdk.business.scenario.type\":14}"); + return ret; + } + + void NertcEngineEx::release(bool sync /*= false*/) { + nertc_engine_release(m_nertc_engine, sync); + } + int NertcEngineEx::setClientRole(NERtcClientRole role) { + return nertc_engine_set_client_role(m_nertc_engine, (nertc_client_role)role); + } + int NertcEngineEx::setChannelProfile(NERtcChannelProfileType profile) { + return nertc_engine_set_channel_profile(m_nertc_engine, (nertc_channel_profile_type)profile); + } + int NertcEngineEx::joinChannel(const char* token, const char* channel_name, uid_t uid, const NERtcJoinChannelOptions& channel_options) { + nertc_join_channel_options csdk_channel_options; + convertToCsdkStruct(channel_options, csdk_channel_options); + return nertc_engine_join_channel(m_nertc_engine, token, channel_name, uid, &csdk_channel_options); + } + int NertcEngineEx::switchChannel(const char* token, const char* channel_name, const NERtcJoinChannelOptions& channel_options) { + nertc_join_channel_options csdk_channel_options; + convertToCsdkStruct(channel_options, csdk_channel_options); + return nertc_engine_switch_channel(m_nertc_engine, token, channel_name, &csdk_channel_options); + } + int NertcEngineEx::switchChannelEx(const char* token, const char* channel_name, uid_t uid, const NERtcJoinChannelOptionsEx& channel_options) { + nertc_join_channel_options_ex csdk_channel_options; + convertToCsdkStruct(channel_options, csdk_channel_options); + return nertc_engine_switch_channel_ex(m_nertc_engine, token, channel_name, uid, &csdk_channel_options); + } + int NertcEngineEx::leaveChannel() { + return nertc_engine_leave_channel(m_nertc_engine); + } + int NertcEngineEx::queryInterface(NERtcInterfaceIdType iid, void** inter) { + void* csdk_manager_ptr{}; + csdk_manager_ptr = nertc_engine_query_interface(m_nertc_engine, (nertc_interface_id_type)iid); + if (!csdk_manager_ptr) { + *inter = nullptr; + return kNERtcErrFatal; + } + if (iid == kNERtcIIDAudioDeviceManager) { + *inter = new NertcAudioDeviceManager(static_cast(csdk_manager_ptr)); + return kNERtcNoError; + } + else { + //TODO + } + return *inter == nullptr ? kNERtcErrInvalidState : kNERtcNoError; + } + + int NertcEngineEx::enableLocalAudio(NERtcAudioStreamType type, bool enabled) { + return nertc_engine_enable_local_audio(m_nertc_engine, (nertc_audio_stream_type)type, enabled); + } + + /////////////////////////////////////////////////////////////// + NERtcConnectionStateType NertcEngineEx::getConnectionState() { + return (NERtcConnectionStateType)nertc_engine_get_connection_state(m_nertc_engine); + } + int NertcEngineEx::muteLocalAudioStream(NERtcAudioStreamType type, bool mute) { + return nertc_engine_mute_local_audio_stream(m_nertc_engine, nertc_audio_stream_type(type), mute); + } + int NertcEngineEx::setAudioProfile(NERtcAudioProfileType profile, NERtcAudioScenarioType scenario) { + return nertc_engine_set_audio_profile(m_nertc_engine, (nertc_audio_profile_type)profile, (nertc_audio_scenario_type)scenario); + } + int NertcEngineEx::setAudioEffectPreset(NERtcVoiceChangerType type) { + return nertc_engine_set_audio_effect_preset(m_nertc_engine, (nertc_voice_changer_type)type); + } + int NertcEngineEx::setVoiceBeautifierPreset(NERtcVoiceBeautifierType type) { + return nertc_engine_set_voice_beautifier_preset(m_nertc_engine, (nertc_voice_beautifier_type)type); + } + int NertcEngineEx::setLocalVoicePitch(double pitch) { + return nertc_engine_set_local_voice_pitch(m_nertc_engine, pitch); + } + int NertcEngineEx::setLocalVoiceEqualization(NERtcVoiceEqualizationBand band_frequency, int band_gain) { + return nertc_engine_set_local_voice_equalization(m_nertc_engine, (nertc_voice_equalization_band)band_frequency, band_gain); + } + int NertcEngineEx::subscribeRemoteAudioStream(NERtcAudioStreamType type, uid_t uid, bool subscribe) { + return nertc_engine_subscribe_remote_audio_stream(m_nertc_engine, nertc_audio_stream_type(type), uid, subscribe); + } + int NertcEngineEx::subscribeAllRemoteAudioStream(bool subscribe) { + return nertc_engine_subscribe_all_remote_audio_stream(m_nertc_engine, subscribe); + } + int NertcEngineEx::setPublishAudioAllowList(uid_t* uid_array, uint32_t size) { + return nertc_engine_set_audio_subscribe_only_by(m_nertc_engine, uid_array, size); + } + + int NertcEngineEx::setSubscribeAudioAllowList(uid_t* uid_array, uint32_t size) { + return nertc_engine_set_subscribe_audio_allow_list(m_nertc_engine, uid_array, size); + } + int NertcEngineEx::setSubscribeAudioBlockList(uid_t* uid_array, uint32_t size) { + return nertc_engine_set_subscribe_audio_block_list(m_nertc_engine, uid_array, size); + } + + int NertcEngineEx::setAudioSessionOperationRestriction(NERtcAudioSessionOperationRestriction restriction) { + return nertc_engine_set_audio_session_operation_restriction(m_nertc_engine, (nertc_audio_session_operation_restriction)restriction); + } + + int NertcEngineEx::setAudioFocusMode(NERtcAudioFocusMode focus_mode) { + return nertc_engine_set_audio_focus_mode(m_nertc_engine, (nertc_audio_focus_mode)focus_mode); + } + + int NertcEngineEx::setPlayoutDeviceMute(bool muted) { + return nertc_engine_set_playout_device_mute(m_nertc_engine, muted); + } + + int NertcEngineEx::getPlayoutDeviceMute(bool* muted) { + return nertc_engine_get_playout_device_mute(m_nertc_engine, muted); + } + + int NertcEngineEx::setParameters(const char* parameters) { + return nertc_engine_set_parameters(m_nertc_engine, parameters); + } + int NertcEngineEx::setAudioFrameObserver(INERtcAudioFrameObserver* observer) { + fillCsdkAudioFrameObserver(observer); + return nertc_engine_set_audio_frame_observer(m_nertc_engine, m_nertc_audio_frame_observer); + } + int NertcEngineEx::startAudioDump(NERtcAudioDumpType type) { + return nertc_engine_start_audio_dump(m_nertc_engine, nertc_audio_dump_type(type)); + } + int NertcEngineEx::stopAudioDump() { + return nertc_engine_stop_audio_dump(m_nertc_engine); + } + int NertcEngineEx::setLoudspeakerMode(bool enable) { + return nertc_engine_set_loudspeaker_mode(m_nertc_engine, enable); + } + + int NertcEngineEx::getLoudspeakerMode(bool* enabled) { + return nertc_engine_get_loudspeaker_mode(m_nertc_engine, enabled); + } + + int NertcEngineEx::setStatsObserver(IRtcMediaStatsObserver* observer) { + fillCsdkMediaStatsObserver(observer); + nertc_engine_set_stats_observer(m_nertc_engine, m_nertc_media_stats_observer); + return kNERtcNoError; + } + int NertcEngineEx::enableAudioVolumeIndication(bool enable, uint64_t interval, bool enable_vad) { + return nertc_engine_enable_audio_volume_indication(m_nertc_engine, enable, interval, enable_vad); + } + const char* NertcEngineEx::getVersion(int* build) { + return nertc_engine_get_version(m_nertc_engine); + } + const char* NertcEngineEx::getErrorDescription(int error_code) { + return nertc_engine_get_error_description(m_nertc_engine, error_code); + } + void NertcEngineEx::uploadSdkInfo() { + nertc_engine_upload_sdk_info(m_nertc_engine); + } + int NertcEngineEx::adjustRecordingSignalVolume(int volume) { + return nertc_engine_adjust_recording_signal_volume(m_nertc_engine, volume); + } + int NertcEngineEx::adjustPlaybackSignalVolume(int volume) { + return nertc_engine_adjust_playback_signal_volume(m_nertc_engine, volume); + } + int NertcEngineEx::enableMediaPublish(bool enabled, NERtcMediaPubType media_type) { + return nertc_engine_enable_media_publish(m_nertc_engine, enabled, (nertc_media_pub_type)media_type); + } + int NertcEngineEx::setRangeAudioMode(NERtcRangeAudioMode mode) { + return nertc_engine_set_range_audio_mode(m_nertc_engine, (nertc_range_audio_mode)mode); + } + int NertcEngineEx::setRangeAudioTeamID(int32_t team_id) { + return nertc_engine_set_range_audio_team_id(m_nertc_engine, team_id); + } + int NertcEngineEx::setAudioRecvRange(int audible_distance, + int conversational_distance, + NERtcDistanceRolloffModel roll_off) { + return nertc_engine_set_audio_recv_range(m_nertc_engine, audible_distance, conversational_distance, (nertc_distance_rolloff_model)roll_off); + } + int NertcEngineEx::updateSelfPosition(const NERtcPositionInfo& info) { + nertc_position_info csdk_info{}; + convertToCsdkStruct(info, csdk_info); + return nertc_engine_update_self_position(m_nertc_engine, &csdk_info); + } + int NertcEngineEx::initSpatializer() { + return nertc_engine_init_spatializer(m_nertc_engine); + } + int NertcEngineEx::enableSpatializer(bool enable) { + return nertc_engine_enable_spatializer(m_nertc_engine, enable); + } + int NertcEngineEx::getMicrophoneMode(bool* enabled) { + return nertc_engine_get_microphone_mode(m_nertc_engine,enabled); + } + int NertcEngineEx::getRecordingSignalVolume() { + int volume = 0; + nertc_engine_get_recording_signal_volume(m_nertc_engine, &volume); + return volume; + } + int NertcEngineEx::getPlaybackSignalVolume() { + int volume = 0; + nertc_engine_get_playback_signal_volume(m_nertc_engine, &volume); + return volume; + } + bool NertcEngineEx::checkMicPermision() { + bool enabled = false; + nertc_engine_check_mic_permision(m_nertc_engine,&enabled); + return enabled; + } + int NertcEngineEx::pauseAudio() { + return nertc_engine_pause_audio(m_nertc_engine); + } + int NertcEngineEx::resumeAudio() { + return nertc_engine_resume_audio(m_nertc_engine); + } + bool NertcEngineEx::isInChannel() { + return nertc_engine_is_in_channel(m_nertc_engine); + } + bool NertcEngineEx::acquireAndroidRecordingPermissions() { +#if PLATFORM_ANDROID + auto hasPermission = UAndroidPermissionFunctionLibrary::CheckPermission(TEXT("android.permission.RECORD_AUDIO")); + + if (hasPermission) { + return true; + } + + TArray Permissions; + Permissions.Add(TEXT("android.permission.RECORD_AUDIO")); + Permissions.Add(TEXT("android.permission.BLUETOOTH")); + Permissions.Add(TEXT("android.permission.BLUETOOTH_CONNECT")); + Permissions.Add(TEXT("android.permission.BROADCAST_STICKY")); + + UAndroidPermissionCallbackProxy* proxy = UAndroidPermissionFunctionLibrary::AcquirePermissions(Permissions); + if (!proxy) { + return false; + } + + proxy->OnPermissionsGrantedDelegate.BindLambda([this](const TArray& Permissions, const TArray& GrantResults) { + std::unique_lock lock(m_sleep_condition_mutex); + m_sleep_condition.notify_one(); + }); + + std::unique_lock lock(m_sleep_condition_mutex); + m_sleep_condition.wait(lock); + return UAndroidPermissionFunctionLibrary::CheckPermission(TEXT("android.permission.RECORD_AUDIO")); +#endif + return false; + } +} diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcEngineEx.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcEngineEx.h new file mode 100644 index 0000000..7262c5a --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcEngineEx.h @@ -0,0 +1,155 @@ +/** @file NertcEngineEx.h + * @brief The interface header file of expansion NERTC UE SDK. + * All parameter descriptions of the NERTC UE SDK. All string-related parameters (char *) are encoded in UTF-8. + * @copyright (c) 2015-2022, NetEase Inc. All rights reserved. + */ + +#pragma once + +#include "INertcEngineEx.h" +#include "INertcMediaStatsObserver.h" +#include +#include +#include + +struct nertc_engine; +struct nertc_engine_events; +struct nertc_media_stats_observer; +struct nertc_audio_frame_observer; + +namespace nertc { + class NertcEngineEx :public IRtcEngineEx { + public: + NertcEngineEx() = delete; + NertcEngineEx(const NertcEngineEx& other); + NertcEngineEx(NertcEngineEx&& other) noexcept; + NertcEngineEx& operator=(const NertcEngineEx& other); + NertcEngineEx& operator=(NertcEngineEx&& other) noexcept; + + virtual ~NertcEngineEx(); + NertcEngineEx(nertc_engine*); + public: + //////////////////////////////////////////////////////////////// + int initialize(const NERtcEngineContext& context) override; + + void release(bool sync = false) override; + + int setClientRole(NERtcClientRole role) override; + + int setChannelProfile(NERtcChannelProfileType profile) override; + + int joinChannel(const char* token, const char* channel_name, uid_t uid, const NERtcJoinChannelOptions& channel_options) override; + + int switchChannel(const char* token, const char* channel_name, const NERtcJoinChannelOptions& channel_options) override; + + int switchChannelEx(const char* token, const char* channel_name, uid_t uid, const NERtcJoinChannelOptionsEx& channel_options) override; + + int leaveChannel() override; + + int queryInterface(NERtcInterfaceIdType iid, void** inter) override; + + int enableLocalAudio(NERtcAudioStreamType type, bool enabled) override; + + ////////////////////////////////////////////////////////////// + NERtcConnectionStateType getConnectionState() override; + + int muteLocalAudioStream(NERtcAudioStreamType type, bool mute) override; + + int setAudioProfile(NERtcAudioProfileType profile, NERtcAudioScenarioType scenario) override; + + int setAudioEffectPreset(NERtcVoiceChangerType type) override; + + int setVoiceBeautifierPreset(NERtcVoiceBeautifierType type) override; + + int setLocalVoicePitch(double pitch) override; + + int setLocalVoiceEqualization(NERtcVoiceEqualizationBand band_frequency, int band_gain) override; + + int subscribeRemoteAudioStream(NERtcAudioStreamType stream_type, uid_t uid, bool subscribe) override; + + int subscribeAllRemoteAudioStream(bool subscribe) override; + + int setPublishAudioAllowList(uid_t* uid_array, uint32_t size) override; + + int setSubscribeAudioAllowList(uid_t* uid_array, uint32_t size) override; + + int setSubscribeAudioBlockList(uid_t* uid_array, uint32_t size) override; + + int setAudioSessionOperationRestriction(NERtcAudioSessionOperationRestriction restriction) override; + + int setAudioFocusMode(NERtcAudioFocusMode focus_mode) override; + + int setPlayoutDeviceMute(bool muted); + + int getPlayoutDeviceMute(bool* muted); + + int setParameters(const char* parameters) override; + + int setAudioFrameObserver(INERtcAudioFrameObserver* observer) override; + + int startAudioDump(NERtcAudioDumpType type) override; + + int stopAudioDump() override; + + int setLoudspeakerMode(bool enable) override; + + int getLoudspeakerMode(bool* enabled) override; + + int setStatsObserver(IRtcMediaStatsObserver* observer) override; + + int enableAudioVolumeIndication(bool enable, uint64_t interval, bool enable_vad) override; + + const char* getVersion(int* build) override; + + const char* getErrorDescription(int error_code) override; + + void uploadSdkInfo() override; + + int adjustRecordingSignalVolume(int volume) override; + + int adjustPlaybackSignalVolume(int volume) override; + + int enableMediaPublish(bool enabled, NERtcMediaPubType media_type) override; + + int setRangeAudioMode(NERtcRangeAudioMode mode) override; + + int setRangeAudioTeamID(int32_t team_id) override; + + int setAudioRecvRange(int audible_distance, int conversational_distance, NERtcDistanceRolloffModel roll_off) override; + + int updateSelfPosition(const NERtcPositionInfo& info) override; + + int initSpatializer() override; + + int enableSpatializer(bool enable) override; + + int getMicrophoneMode(bool* enabled) override; + + int getRecordingSignalVolume() override; + + int getPlaybackSignalVolume() override; + + bool checkMicPermision() override; + + int pauseAudio() override; + + int resumeAudio() override; + + bool isInChannel() override; + + bool acquireAndroidRecordingPermissions() override; + private: + void fillCsdkEventHandler(IRtcEngineEventHandler* handler); + void clearCsdkEventHandler(); + void fillCsdkAudioFrameObserver(INERtcAudioFrameObserver* observer); + void clearCsdkAudioFrameObserver(); + void fillCsdkMediaStatsObserver(IRtcMediaStatsObserver* observer); + void clearCsdkMediaStatsObserver(); + nertc_engine* m_nertc_engine{ nullptr }; + nertc_engine_events* m_nertc_engine_event{ nullptr }; + nertc_audio_frame_observer* m_nertc_audio_frame_observer{ nullptr }; + nertc_media_stats_observer* m_nertc_media_stats_observer{ nullptr }; + std::condition_variable_any m_sleep_condition; + std::recursive_mutex m_sleep_condition_mutex; + }; +} \ No newline at end of file diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcEngineUtil.cpp b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcEngineUtil.cpp new file mode 100644 index 0000000..5780bd1 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcEngineUtil.cpp @@ -0,0 +1,380 @@ +// Copyright Epic Games, Inc. All Rights Reserved. + +#include "NertcEngineUtil.h" + +namespace nertc { + //////////////////////////////csdk struct to nertc struce////////////////////////////// + void convertToCsdkStruct(const NERtcJoinChannelOptions& src, nertc_join_channel_options& dst) { + memcpy(dst.custom_info, src.custom_info, kNERtcCustomInfoLength); + dst.permission_key = src.permission_key; + dst.team_id = src.team_id; + dst.mode = (nertc_range_audio_mode)src.mode; + dst.audible_distance = src.audible_distance; + } + void convertToCsdkStruct(const NERtcJoinChannelOptionsEx& src, nertc_join_channel_options_ex& dst) { + memcpy(dst.custom_info, src.custom_info, kNERtcCustomInfoLength); + dst.permission_key = src.permission_key; + dst.team_id = src.team_id; + dst.mode = (nertc_range_audio_mode)src.mode; + dst.audible_distance = src.audible_distance; + } + void convertToCsdkStruct(const NERtcRectangle& src, nertc_rectangle& dst) { + dst.x = src.x; + dst.y = src.y; + dst.width = src.width; + dst.height = src.height; + } + void convertToCsdkStruct(const NERtcScreenCaptureParameters& src, nertc_screen_capture_parameters& dst){ + dst.profile = (nertc_screen_profile_type)src.profile; + dst.dimensions.width = src.dimensions.width; + dst.dimensions.height = src.dimensions.height; + dst.frame_rate = src.frame_rate; + dst.bitrate = src.bitrate; + dst.capture_mouse_cursor = src.capture_mouse_cursor; + dst.window_focus = src.window_focus; + dst.excluded_window_count = src.excluded_window_count; + dst.excluded_window_list = new source_id_t[src.excluded_window_count]; + for (int i = 0; i < src.excluded_window_count; i++) { + dst.excluded_window_list[i] = src.excluded_window_list[i]; + } + dst.prefer = (nertc_sub_stream_content_prefer)src.prefer; + //warn: need delete excluded_window_list + } + void convertToCsdkStruct(const NERtcVideoCanvas& src, nertc_video_canvas& dst){ + dst.cb = src.cb; + dst.user_data = src.user_data; + dst.window = src.window; + dst.scaling_mode = (nertc_video_scaling_mode)src.scaling_mode; + } + void convertToCsdkStruct(const NERtcCameraCaptureConfig& src, nertc_camera_capture_config& dst){ + //dst.preference = (nertc_camera_preference)src.preference; + dst.capture_width = src.capture_width; + dst.capture_height = src.capture_height; + } + void convertToCsdkStruct(const NERtcVideoConfig& src, nertc_video_config& dst){ + dst.max_profile = (nertc_video_profile_type)src.max_profile; + dst.width = src.width; + dst.height = src.height; + dst.crop_mode_ = (nertc_video_crop_mode)src.crop_mode; //TODO rename csdk + nertc sdk + dst.framerate = (nertc_video_framerate_type)src.framerate; + dst.min_framerate = (nertc_video_framerate_type)src.min_framerate; + dst.bitrate = src.bitrate; + dst.min_bitrate = src.min_bitrate; + dst.degradation_preference = (nertc_degradation_preference)src.degradation_preference; + dst.mirror_mode = (nertc_video_mirror_mode)src.mirror_mode; + dst.orientation_mode = (nertc_video_orientation_mode)src.orientation_mode; + } + void convertToCsdkStruct(const NERtcLiveStreamLayout& src, nertc_live_stream_layout& dst) { + + dst.width = src.width; + dst.height = src.height; + dst.background_color = src.background_color; + dst.user_count = src.user_count; + + dst.users = new nertc_live_stream_user_transcoding[src.user_count]; + for (unsigned int i = 0; i < src.user_count; i++) { + dst.users[i].uid = src.users[i].uid; + dst.users[i].video_push = src.users[i].video_push; + dst.users[i].adaption = (nertc_live_stream_video_scale_mode)src.users[i].adaption; + dst.users[i].x = src.users[i].x; + dst.users[i].y = src.users[i].y; + dst.users[i].width = src.users[i].width; + dst.users[i].height = src.users[i].height; + dst.users[i].audio_push = src.users[i].audio_push; + dst.users[i].z_order = src.users[i].z_order; + } + } + void convertToCsdkStruct(const NERtcLiveConfig& src, nertc_live_stream_config& dst) { + dst.audioCodecProfile = (nertc_live_stream_audio_sample_rate)src.audioCodecProfile; + dst.audio_bitrate = src.audio_bitrate; + dst.channels = src.channels; + dst.sampleRate = (nertc_live_stream_audio_sample_rate)src.sampleRate; + dst.single_video_passthrough = src.single_video_passthrough; + } + WindUpCallback convertToCsdkStruct(const NERtcLiveStreamTaskInfo& src, nertc_live_stream_task_info& dst){ + memcpy(dst.task_id, src.task_id, kNERtcMaxTaskIDLength); + memcpy(dst.stream_url, src.stream_url, kNERtcMaxURILength); + dst.server_record_enabled = src.server_record_enabled; + dst.ls_mode = (nertc_live_stream_mode)src.ls_mode; + convertToCsdkStruct(src.layout, dst.layout); + convertToCsdkStruct(src.config, dst.config); + memcpy(dst.extra_info, src.extra_info, kNERtcMaxSEIBufferLength); + + return [dst]() { + delete[] dst.layout.users; + }; + } + void convertToCsdkStruct(const NERtcVideoWatermarkConfig& src, nertc_video_watermark_config& dst){ + //TODO 后面升级到编码水印 + } + WindUpCallback convertToCsdkStruct(const NERtcChannelMediaRelayConfiguration& src, nertc_channel_media_relay_config& dst){ + auto convert_relay_info = [](const NERtcChannelMediaRelayInfo& src, nertc_channel_media_relay_info& dst) { + memcpy((void*)dst.channel_name, src.channel_name, kNERtcMaxChannelNameLength); + memcpy((void*)dst.channel_token, src.channel_token, kNERtcMaxChannelNameLength); + dst.uid = src.uid; + }; + dst.dest_count = src.dest_count; + + dst.dest_infos = new nertc_channel_media_relay_info[dst.dest_count]{}; + for(int i = 0; i < dst.dest_count; i++){ + convert_relay_info(src.dest_infos[i], dst.dest_infos[i]); + } + + dst.src_infos = new nertc_channel_media_relay_info{}; + convert_relay_info(*src.src_infos, *dst.src_infos); + + return [dst]() { + delete[] dst.dest_infos; + delete dst.src_infos; + }; + } + void convertToCsdkStruct(const NERtcVideoFrame& src, nertc_video_frame& dst){ + dst.buffer = src.buffer; + dst.format = (nertc_video_type)src.format; + dst.height = src.height; + dst.rotation = (nertc_video_rotation)src.rotation; + dst.timestamp = src.timestamp; + } + void convertToCsdkStruct(const NERtcAudioFrameRequestFormat& src, nertc_audio_frame_request_format& dst){ + dst.channels = src.channels; + dst.mode = (nertc_raw_audio_frame_op_mode_type)src.mode; + dst.sample_rate = src.sample_rate; + } + void convertToCsdkStruct(const NERtcCreateAudioMixingOption& src, nertc_create_audio_mixing_option& dst){ + memcpy(dst.path, src.path, kNERtcMaxURILength); + dst.loop_count = src.loop_count; + dst.playback_enabled = src.playback_enabled; + dst.playback_volume = src.playback_volume; + dst.send_enabled = src.send_enabled; + dst.send_volume = src.send_volume; + } + void convertToCsdkStruct(const NERtcCreateAudioEffectOption& src, nertc_create_audio_effect_option& dst){ + memcpy(dst.path, src.path, kNERtcMaxURILength); + dst.loop_count = src.loop_count; + dst.playback_enabled = src.playback_enabled; + dst.playback_volume = src.playback_volume; + dst.send_enabled = src.send_enabled; + dst.send_volume = src.send_volume; + } + void convertToCsdkStruct(const NERtcAudioFrame& src, nertc_audio_frame& dst){ + dst.data = src.data; + dst.format.type = (nertc_audio_type)src.format.type; + dst.format.channels = src.format.channels; + dst.format.sample_rate = src.format.sample_rate; + dst.format.bytes_per_sample = src.format.bytes_per_sample; + dst.format.samples_per_channel = src.format.samples_per_channel; + } + void convertToCsdkStruct(const NERtcEncryptionConfig& src, nertc_encryption_config& dst){ + memcpy(dst.key, src.key, kNERtcEncryptByteLength); + dst.mode = (nertc_encryption_mode)src.mode; + } + void convertToCsdkStruct(const NERtcLastmileProbeConfig& src, nertc_lastmile_probe_config& dst){ + dst.expected_downlink_bitratebps = src.expected_downlink_bitratebps; + dst.expected_uplink_bitratebps = src.expected_uplink_bitratebps; + dst.probe_downlink = src.probe_downlink; + dst.probe_uplink = src.probe_uplink; + } + void convertToCsdkStruct(const NERtcPositionInfo& src, nertc_position_info& dst){ + memcpy(dst.speaker_position, src.speaker_position, sizeof(src.speaker_position)); + memcpy(dst.speaker_quaternion, src.speaker_quaternion, sizeof(src.speaker_quaternion)); + memcpy(dst.head_position, src.head_position, sizeof(src.head_position)); + memcpy(dst.head_quaternion, src.head_quaternion, sizeof(src.head_quaternion)); + } + void convertToCsdkStruct(const NERtcSpatializerRoomProperty& src, nertc_spatializer_room_property& dst){ + dst.material = (nertc_spatializer_material_name)src.material; + dst.reflection_scalar = src.reflection_scalar; + dst.reverb_brightness = src.reverb_brightness; + dst.reverb_gain = src.reverb_gain; + dst.reverb_time = src.reverb_time; + dst.room_capacity = (nertc_spatializer_room_capacity)src.room_capacity; + } + + + //////////////////////////////nertc struct to csdk struce////////////////////////////// + void convertToNertcStruct(const nertc_device_info& src, NERtcDeviceInfo& dst) { + memcpy(dst.device_id, src.device_id, kNERtcMaxDeviceIDLength); + memcpy(dst.device_name, src.device_name, kNERtcMaxDeviceNameLength); + dst.transport_type = src.transport_type; + dst.suspected_unavailable = src.suspected_unavailable; + dst.system_default_device = src.system_default_device; + } + void convertToNertcStruct(const nertc_user_join_extra_info& src, NERtcUserJoinExtraInfo& dst) { + memcpy(dst.custom_info, src.custom_info, kNERtcCustomInfoLength); + } + WindUpCallback convertToNertcStruct(const nertc_audio_volume_info* src, uint32_t speaker_number, NERtcAudioVolumeInfo*& dst) { + if (!src) { + return []() {}; + } + dst = new NERtcAudioVolumeInfo[speaker_number]; + for (uint32_t i = 0; i < speaker_number; i++) { + dst[i].uid = src[i].uid; + dst[i].volume = src[i].volume; + dst[i].sub_stream_volume = src[i].sub_stream_volume; + } + return [dst]() { + delete[] dst; + }; + } + void convertToNertcStruct(const nertc_camera_focus_and_exposure_info& src, NERtcCameraFocusAndExposureInfo& dst) { + dst.center_x = src.center_x; + dst.center_y = src.center_y; + dst.left = src.left; + dst.top = src.top; + dst.right = src.right; + dst.bottom = src.bottom; + } + void convertToNertcStruct(const nertc_lastmile_probe_result& src, NERtcLastmileProbeResult& dst) { + dst.downlink_report.available_band_width = src.downlink_report.available_band_width; + dst.downlink_report.jitter = src.downlink_report.jitter; + dst.downlink_report.packet_loss_rate = src.downlink_report.packet_loss_rate; + + dst.rtt = src.rtt; + dst.state = (NERtcLastmileProbeResultState)src.state; + + dst.uplink_report.available_band_width = src.uplink_report.available_band_width; + dst.uplink_report.jitter = src.uplink_report.jitter; + dst.uplink_report.packet_loss_rate = src.uplink_report.packet_loss_rate; + } + void convertToNertcStruct(const nertc_audio_frame& src, NERtcAudioFrame& dst) { + dst.data = src.data; + dst.format.type = (NERtcAudioType)src.format.type; + dst.format.channels = src.format.channels; + dst.format.sample_rate = src.format.sample_rate; + dst.format.bytes_per_sample = src.format.bytes_per_sample; + dst.format.samples_per_channel = src.format.samples_per_channel; + } + void convertToNertcStruct(const nertc_stats& src, NERtcStats& dst) { + dst.cpu_app_usage = src.cpu_app_usage; + dst.cpu_idle_usage = src.cpu_idle_usage; + dst.cpu_total_usage = src.cpu_total_usage; + dst.memory_app_usage = src.memory_app_usage; + dst.memory_total_usage = src.memory_total_usage; + dst.memory_app_kbytes = src.memory_app_kbytes; + dst.total_duration = src.total_duration; + dst.tx_bytes = src.tx_bytes; + dst.rx_bytes = src.rx_bytes; + dst.tx_audio_bytes = src.tx_audio_bytes; + dst.tx_video_bytes = src.tx_video_bytes; + dst.rx_audio_bytes = src.rx_audio_bytes; + dst.rx_video_bytes = src.rx_video_bytes; + dst.tx_audio_kbitrate = src.tx_audio_kbitrate; + dst.rx_audio_kbitrate = src.rx_audio_kbitrate; + dst.tx_video_kbitrate = src.tx_video_kbitrate; + dst.rx_video_kbitrate = src.rx_video_kbitrate; + dst.up_rtt = src.up_rtt; + dst.down_rtt = src.down_rtt; + dst.tx_audio_packet_loss_rate = src.tx_audio_packet_loss_rate; + dst.tx_video_packet_loss_rate = src.tx_video_packet_loss_rate; + dst.tx_audio_packet_loss_sum = src.tx_audio_packet_loss_sum; + dst.tx_video_packet_loss_sum = src.tx_video_packet_loss_sum; + dst.tx_audio_jitter = src.tx_audio_jitter; + dst.tx_video_jitter = src.tx_video_jitter; + dst.rx_audio_packet_loss_rate = src.rx_audio_packet_loss_rate; + dst.rx_video_packet_loss_rate = src.rx_video_packet_loss_rate; + dst.rx_audio_packet_loss_sum = src.rx_audio_packet_loss_sum; + dst.rx_video_packet_loss_sum = src.rx_video_packet_loss_sum; + dst.rx_audio_jitter = src.rx_audio_jitter; + dst.rx_video_jitter = src.rx_video_jitter; + } + WindUpCallback convertToNertcStruct(const nertc_audio_send_stats& src, NERtcAudioSendStats& dst) { + dst.audio_layers_list = new NERtcAudioLayerSendStats[src.audio_layers_count]; + dst.audio_layers_count = src.audio_layers_count; + for (size_t i = 0; i < src.audio_layers_count; i++) { + dst.audio_layers_list[i].stream_type = (NERtcAudioStreamType)src.audio_layers_list[i].stream_type; + dst.audio_layers_list[i].num_channels = src.audio_layers_list[i].num_channels; + dst.audio_layers_list[i].sent_sample_rate = src.audio_layers_list[i].sent_sample_rate; + dst.audio_layers_list[i].sent_bitrate = src.audio_layers_list[i].sent_bitrate; + dst.audio_layers_list[i].audio_loss_rate = src.audio_layers_list[i].audio_loss_rate; + dst.audio_layers_list[i].rtt = src.audio_layers_list[i].rtt; + dst.audio_layers_list[i].volume = src.audio_layers_list[i].volume; + dst.audio_layers_list[i].cap_volume = src.audio_layers_list[i].cap_volume; + } + return [dst]() { + delete[] dst.audio_layers_list; + }; + } + WindUpCallback convertToNertcStruct(const nertc_audio_recv_stats* src, unsigned int user_count, NERtcAudioRecvStats*& dst) { + dst = new NERtcAudioRecvStats[user_count]; + for (size_t i = 0; i < user_count; i++) { + dst[i].uid = src[i].uid; + dst[i].audio_layers_list = new NERtcAudioLayerRecvStats[src[i].audio_layers_count]; + dst[i].audio_layers_count = src[i].audio_layers_count; + for (size_t j = 0; j < src[i].audio_layers_count; j++) { + dst[i].audio_layers_list[j].stream_type = (NERtcAudioStreamType)src[i].audio_layers_list[j].stream_type; + dst[i].audio_layers_list[j].received_bitrate = src[i].audio_layers_list[j].received_bitrate; + dst[i].audio_layers_list[j].total_frozen_time = src[i].audio_layers_list[j].total_frozen_time; + dst[i].audio_layers_list[j].frozen_rate = src[i].audio_layers_list[j].frozen_rate; + dst[i].audio_layers_list[j].audio_loss_rate = src[i].audio_layers_list[j].audio_loss_rate; + dst[i].audio_layers_list[j].volume = src[i].audio_layers_list[j].volume; + } + } + return [dst, user_count]() { + for (size_t i = 0; i < user_count; i++) { + delete[] dst[i].audio_layers_list; + } + delete[] dst; + }; + } + WindUpCallback convertToNertcStruct(const nertc_video_send_stats& src, NERtcVideoSendStats& dst) { + auto convertVideoLayerSendStats = [](const nertc_video_layer_send_stats& src, NERtcVideoLayerSendStats& dst) { + dst.layer_type = src.layer_type; + dst.width = src.width; + dst.height = src.height; + dst.capture_width = src.capture_width; + dst.capture_height = src.capture_height; + dst.capture_frame_rate = src.capture_frame_rate; + dst.render_frame_rate = src.render_frame_rate; + dst.encoder_frame_rate = src.encoder_frame_rate; + dst.sent_frame_rate = src.sent_frame_rate; + dst.sent_bitrate = src.sent_bitrate; + dst.target_bitrate = src.target_bitrate; + dst.encoder_bitrate = src.encoder_bitrate; + memcpy(dst.codec_name, src.codec_name, kNERtcMaxDeviceNameLength); + }; + dst.video_layers_count = src.video_layers_count; + dst.video_layers_list = new NERtcVideoLayerSendStats[dst.video_layers_count]{}; + for (int i = 0; i < dst.video_layers_count; i++) { + convertVideoLayerSendStats(src.video_layers_list[i], dst.video_layers_list[i]); + } + + return [dst]() { + delete[] dst.video_layers_list; + }; + } + WindUpCallback convertToNertcStruct(const nertc_video_recv_stats* src_list, unsigned int user_count, NERtcVideoRecvStats*& dst_list) { + auto convertVideoLayerRecvStats = [](const nertc_video_layer_recv_stats& src, NERtcVideoLayerRecvStats& dst) { + dst.layer_type = src.layer_type; + dst.width = src.width; + dst.height = src.height; + dst.received_bitrate = src.received_bitrate; + dst.received_frame_rate = src.received_frame_rate; + dst.decoder_frame_rate = src.decoder_frame_rate; + dst.render_frame_rate = src.render_frame_rate; + dst.packet_loss_rate = src.packet_loss_rate; + dst.total_frozen_time = src.total_frozen_time; + dst.frozen_rate = src.frozen_rate; + memcpy(dst.codec_name, src.codec_name, kNERtcMaxDeviceNameLength); + }; + dst_list = new NERtcVideoRecvStats[user_count]{}; + for (unsigned int i = 0; i < user_count; i++) { + dst_list[i].uid = src_list[i].uid; + dst_list[i].video_layers_count = src_list[i].video_layers_count; + dst_list[i].video_layers_list = new NERtcVideoLayerRecvStats[dst_list[i].video_layers_count]{}; + for (int j = 0; j < dst_list[j].video_layers_count; j++) { + convertVideoLayerRecvStats(src_list[i].video_layers_list[j], dst_list[i].video_layers_list[j]); + } + } + + return [dst_list, user_count]() { + for (unsigned int i = 0; i < user_count; i++) { + delete[] dst_list[i].video_layers_list; + } + delete[] dst_list; + }; + } + void convertToNertcStruct(const nertc_network_quality_info& src, NERtcNetworkQualityInfo& dst) { + dst.rx_quality = (NERtcNetworkQualityType)src.rx_quality; + dst.tx_quality = (NERtcNetworkQualityType)src.tx_quality; + dst.uid = src.uid; + } +} \ No newline at end of file diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcEngineUtil.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcEngineUtil.h new file mode 100644 index 0000000..d18971f --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcEngineUtil.h @@ -0,0 +1,42 @@ +#pragma once +#include "NertcEngineDefines.h" +#include "Nertc/api/nertc_engine_defines.h" +#include +namespace nertc { + using WindUpCallback = std::function; + //////////////////////////////csdk struct to nertc struce////////////////////////////// + void convertToCsdkStruct(const NERtcJoinChannelOptions& src, nertc_join_channel_options& dst); + void convertToCsdkStruct(const NERtcJoinChannelOptionsEx& src, nertc_join_channel_options_ex& dst); + void convertToCsdkStruct(const NERtcRectangle& src, nertc_rectangle& dst); + void convertToCsdkStruct(const NERtcScreenCaptureParameters& src, nertc_screen_capture_parameters& dst); + void convertToCsdkStruct(const NERtcVideoCanvas& src, nertc_video_canvas& dst); + void convertToCsdkStruct(const NERtcCameraCaptureConfig& src, nertc_camera_capture_config& dst); + void convertToCsdkStruct(const NERtcVideoConfig& src, nertc_video_config& dst); + WindUpCallback convertToCsdkStruct(const NERtcLiveStreamTaskInfo& src, nertc_live_stream_task_info& dst); + void convertToCsdkStruct(const NERtcVideoWatermarkConfig& src, nertc_video_watermark_config& dst); + WindUpCallback convertToCsdkStruct(const NERtcChannelMediaRelayConfiguration& src, nertc_channel_media_relay_config& dst); + void convertToCsdkStruct(const NERtcVideoFrame& src, nertc_video_frame& dst); + void convertToCsdkStruct(const NERtcAudioFrameRequestFormat& src, nertc_audio_frame_request_format& dst); + void convertToCsdkStruct(const NERtcCreateAudioMixingOption& src, nertc_create_audio_mixing_option& dst); + void convertToCsdkStruct(const NERtcCreateAudioEffectOption& src, nertc_create_audio_effect_option& dst); + void convertToCsdkStruct(const NERtcAudioFrame& src, nertc_audio_frame& dst); + void convertToCsdkStruct(const NERtcEncryptionConfig& src, nertc_encryption_config& dst); + void convertToCsdkStruct(const NERtcLastmileProbeConfig& src, nertc_lastmile_probe_config& dst); + void convertToCsdkStruct(const NERtcPositionInfo& src, nertc_position_info& dst); + void convertToCsdkStruct(const NERtcSpatializerRoomProperty& src, nertc_spatializer_room_property& dst); + + //////////////////////////////nertc struct to csdk struce////////////////////////////// + void convertToNertcStruct(const nertc_device_info& src, NERtcDeviceInfo& dst); + void convertToNertcStruct(const nertc_user_join_extra_info& src, NERtcUserJoinExtraInfo& dst); + WindUpCallback convertToNertcStruct(const nertc_audio_volume_info* src, uint32_t speaker_number, NERtcAudioVolumeInfo*& dst); + void convertToNertcStruct(const nertc_camera_focus_and_exposure_info& src, NERtcCameraFocusAndExposureInfo& dst); + void convertToNertcStruct(const nertc_lastmile_probe_result& src, NERtcLastmileProbeResult& dst); + void convertToNertcStruct(const nertc_audio_frame& src, NERtcAudioFrame& dst); + void convertToNertcStruct(const nertc_stats& src, NERtcStats& dst); + WindUpCallback convertToNertcStruct(const nertc_audio_send_stats& src, NERtcAudioSendStats& dst); + WindUpCallback convertToNertcStruct(const nertc_audio_recv_stats* src, unsigned int user_count, NERtcAudioRecvStats*& dst); + WindUpCallback convertToNertcStruct(const nertc_video_send_stats& src, NERtcVideoSendStats& dst); + WindUpCallback convertToNertcStruct(const nertc_video_recv_stats* src_list, unsigned int user_count, NERtcVideoRecvStats*& dst_list); + void convertToNertcStruct(const nertc_network_quality_info& src, NERtcNetworkQualityInfo& dst); + +} \ No newline at end of file diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcMediaStatsObserver.cpp b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcMediaStatsObserver.cpp new file mode 100644 index 0000000..c0ae63c --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcMediaStatsObserver.cpp @@ -0,0 +1,87 @@ +// Copyright Epic Games, Inc. All Rights Reserved. + +#include "NertcEngineEx.h" +#include "NertcEngineUtil.h" +#include "Nertc/api/nertc_media_stats_observer.h" +#include + +namespace nertc { + static std::map g_engine_media_stats_map; + namespace { + void on_rtc_stats(void* self, const struct nertc_stats* stats){ + if (g_engine_media_stats_map.find(self) == g_engine_media_stats_map.end()) + return; + NERtcStats nertc_stats{}; + convertToNertcStruct(*stats, nertc_stats); + g_engine_media_stats_map[self]->onRtcStats(nertc_stats); + } + void on_local_audio_stats(void* self, const struct nertc_audio_send_stats* stats) { + if (g_engine_media_stats_map.find(self) == g_engine_media_stats_map.end()) + return; + NERtcAudioSendStats nertc_stats{}; + auto wind_cb = convertToNertcStruct(*stats, nertc_stats); + g_engine_media_stats_map[self]->onLocalAudioStats(nertc_stats); + wind_cb(); + } + void on_remote_audio_stats(void* self, const struct nertc_audio_recv_stats* stats, unsigned int user_count) { + if (g_engine_media_stats_map.find(self) == g_engine_media_stats_map.end()) + return; + NERtcAudioRecvStats* nertc_stats; + auto wind_cb = convertToNertcStruct(stats, user_count, nertc_stats); + + g_engine_media_stats_map[self]->onRemoteAudioStats(nertc_stats, user_count); + wind_cb(); + } + void on_local_video_stats(void* self, const struct nertc_video_send_stats* stats) { + if (g_engine_media_stats_map.find(self) == g_engine_media_stats_map.end()) + return; + NERtcVideoSendStats nertc_stats{}; + auto wind_up_cb = convertToNertcStruct(*stats, nertc_stats); + g_engine_media_stats_map[self]->onLocalVideoStats(nertc_stats); + wind_up_cb(); + } + void on_remote_video_stats(void* self, const struct nertc_video_recv_stats* stats, unsigned int user_count) { + if (g_engine_media_stats_map.find(self) == g_engine_media_stats_map.end()) + return; + + NERtcVideoRecvStats* nertc_stats{}; + auto wind_up_cb = convertToNertcStruct(stats, user_count, nertc_stats); + g_engine_media_stats_map[self]->onRemoteVideoStats(nertc_stats, user_count); + wind_up_cb(); + } + void on_network_quality(void* self, const struct nertc_network_quality_info* infos, unsigned int user_count) { + if (g_engine_media_stats_map.find(self) == g_engine_media_stats_map.end()) + return; + NERtcNetworkQualityInfo* nertc_infos = new NERtcNetworkQualityInfo[user_count]; + for (unsigned int i = 0; i < user_count; i++) { + convertToNertcStruct(infos[i], nertc_infos[i]); + } + g_engine_media_stats_map[self]->onNetworkQuality(nertc_infos, user_count); + delete[] nertc_infos; + } + + } + void NertcEngineEx::fillCsdkMediaStatsObserver(IRtcMediaStatsObserver* observer) { + g_engine_media_stats_map[m_nertc_engine] = observer; + if (!m_nertc_media_stats_observer) { + m_nertc_media_stats_observer = new nertc_media_stats_observer(); + } + if (!observer) { + *m_nertc_media_stats_observer = nertc_media_stats_observer{}; + } + m_nertc_media_stats_observer->self = m_nertc_engine; + + m_nertc_media_stats_observer->on_rtc_stats = on_rtc_stats; + m_nertc_media_stats_observer->on_local_audio_stats = on_local_audio_stats; + m_nertc_media_stats_observer->on_remote_audio_stats = on_remote_audio_stats; + m_nertc_media_stats_observer->on_local_video_stats = on_local_video_stats; + m_nertc_media_stats_observer->on_remote_video_stats = on_remote_video_stats; + m_nertc_media_stats_observer->on_network_quality = on_network_quality; + + } + void NertcEngineEx::clearCsdkMediaStatsObserver() { + //g_engine_media_stats_map.erase(m_nertc_engine); + g_engine_media_stats_map.clear(); + } + +} \ No newline at end of file diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcPlugin.cpp b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcPlugin.cpp new file mode 100644 index 0000000..b017115 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Private/NertcPlugin.cpp @@ -0,0 +1,47 @@ +// Copyright Epic Games, Inc. All Rights Reserved. + +#include "NertcPlugin.h" +#include "Core.h" +#include "Modules/ModuleManager.h" +#include "Interfaces/IPluginManager.h" + +#define LOCTEXT_NAMESPACE "FNertcPluginModule" + +void FNertcPluginModule::StartupModule() +{ + // This code will execute after your module is loaded into memory; the exact timing is specified in the .uplugin file per-module + + // Get the base directory of this plugin + FString BaseDir = IPluginManager::Get().FindPlugin("NertcPlugin")->GetBaseDir(); + + NertcDllHandler = nullptr; +#if UE_EDITOR && PLATFORM_WINDOWS + // Add on the relative location of the third party dll and load it + // FString LibraryPath; + //LibraryPath = FPaths::Combine(*BaseDir, TEXT("Source/ThirdParty/Nertc/Win/x64/Release/nertc-c-sdk.dll")); + // NertcDllHandler = !LibraryPath.IsEmpty() ? FPlatformProcess::GetDllHandle(*LibraryPath) : nullptr; + // if (NertcDllHandler){ + // // Call the test function in the third party library that opens a message box + // }else{ + // FMessageDialog::Open(EAppMsgType::Ok, LOCTEXT("ThirdPartyLibraryError", "Failed to load example third party library")); + // } +#endif // PLATFORM_WINDOWS +} + +void FNertcPluginModule::ShutdownModule() +{ + // This function may be called during shutdown to clean up your module. For modules that support dynamic reloading, + // we call this function before unloading the module. + + // Free the dll handle +#if UE_EDITOR && PLATFORM_WINDOWS + /*if(NertcDllHandler != nullptr){ + FPlatformProcess::FreeDllHandle(NertcDllHandler); + NertcDllHandler = nullptr; + }*/ +#endif +} + +#undef LOCTEXT_NAMESPACE + +IMPLEMENT_MODULE(FNertcPluginModule, NertcPlugin) diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/INertcAudioDeviceManager.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/INertcAudioDeviceManager.h new file mode 100644 index 0000000..b9cbf92 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/INertcAudioDeviceManager.h @@ -0,0 +1,460 @@ +/** @file NertcAudioDeviceManager.h + * @brief The interface header file of audio device management of the NERTC UE SDK. + * All parameter descriptions of the NERTC UE SDK. All string-related parameters (char *) are encoded in UTF-8. + * @copyright (c) 2021 NetEase, Inc. All rights reserved. + */ + +#pragma once +#include "INertcDeviceCollection.h" +#include + +namespace nertc { +class IAudioDeviceManager { +public: + virtual ~IAudioDeviceManager() {} + /** + * @if English + * Gets the list of all the audio capture devices in the system. + *
The method returns an IDeviceCollection object that includes all the audio capture devices in the system. Enumerates + * capturing devices with the App through the IDeviceCollection object. + * @note After the method is used, the App needs to destroy the returned object by calling \ref IDeviceCollection::destroy + * "destroy" method. + * @return + * - Failure: Null. + * @endif + * @if Chinese + * 获取系统中所有的音频采集设备列表。 + *
该方法返回一个 IDeviceCollection 对象，包含系统中所有的音频采集设备。通过IDeviceCollection 对象，App + * 可以枚举音频采集设备。 + * @note 在使用结束后，App 需调用 \ref IDeviceCollection::destroy "destroy" 方法销毁返回的对象。 + * @return + * - 方法调用成功：一个 IDeviceCollection 对象，包含所有的音频采集设备。 + * - 方法调用失败：NULL。 + * @endif + * */ +virtual IDeviceCollection* enumerateRecordDevices() = 0; +/** + * @if English + * Specifies the audio capture device. + * @param device_id The device ID of the audio capture devices. Gets the ID through enumerateRecordDevices. Device swapping or + * plugging does not affect deviceId. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 指定音频采集设备。 + * @param device_id 音频采集设备的设备 ID。可通过 enumerateRecordDevices 获取。插拔设备不会影响 deviceId。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +virtual int setRecordDevice(const char device_id[kNERtcMaxDeviceIDLength]) = 0; +/** + * @if English + * Gets the ID of the audio capture device that is currently used. + * @param device_id The device ID of the audio capture devices. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 获取当前使用的音频采集设备 ID。 + * @param device_id 音频采集设备的设备 ID。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +virtual int getRecordDevice(char device_id[kNERtcMaxDeviceIDLength]) = 0; +/** + * @if English + * Gets the list of all playback devices in the system. + *
The method returns an IDeviceCollection object that includes all audio playback devices in the system. Enumerates + * playback devices with the App through the IDeviceCollection object. After the method is used, the App needs to destroy the + * returned object by calling the destroy method. + * @note The system must destroy the returned value by calling \ref IDeviceCollection::destroy "destroy" method. + * @return + * - Success: Gets an IDeviceCollection object that includes all audio playback devices. + * - Failure: Null. + * @endif + * @if Chinese + * 获取系统中所有的播放设备列表。 + *
该方法返回一个 IDeviceCollection 对象，包含系统中所有的播放设备。通过 IDeviceCollection 对象，App + * 可以枚举播放设备。在使用结束后，App 需调用 destroy 方法销毁返回的对象。 + * @note 程序必须调用 \ref IDeviceCollection::destroy "destroy" 方法销毁返回的值。 + * @return + * - 方法调用成功：一个 IDeviceCollection 对象，包含所有的音频播放设备。 + * - 方法调用失败：NULL。 + * @endif + * */ +virtual IDeviceCollection* enumeratePlayoutDevices() = 0; +/** + * @if English + * Specifies the audio playback device. + * @param device_id The device ID of audio playback devices. Gets the ID through \ref + * IAudioDeviceManager::enumeratePlayoutDevices "enumeratePlayoutDevices". Device swapping or plugging does not affect + * deviceId. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 指定播放设备。 + * @param device_id 音频播放设备的设备 ID。可以通过 \ref IAudioDeviceManager::enumeratePlayoutDevices + * "enumeratePlayoutDevices" 获取。插拔设备不会影响 deviceId。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +virtual int setPlayoutDevice(const char device_id[kNERtcMaxDeviceIDLength]) = 0; +/** + * @if English + * Gets the ID of the audio playback device that is currently used. + * @param device_id The ID of audio playback devices. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 获取当前使用的音频播放设备 ID。 + * @param device_id 音频播放设备的设备 ID。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +virtual int getPlayoutDevice(char device_id[kNERtcMaxDeviceIDLength]) = 0; + +/** + * @if English + * Sets the volume of the audio capture device. + * @param volume The volume of the audio capture device. Valid values: 0 to 255. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置音频采集设备音量。 + * @param volume 音频采集设备音量。取值范围为 0~255。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +virtual int setRecordDeviceVolume(uint32_t volume) = 0; +/** + * @if English + * Gets the volume of the audio capture device. + * @param volume The volume of the audio capture device. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 获取音频采集设备音量。 + * @param volume 音频采集设备音量。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +virtual int getRecordDeviceVolume(uint32_t* volume) = 0; +/** + * @if English + * Sets the volume of audio playback device. + * @param volume The volume of audio playback device. Valid values: 0 to 255. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置音频播放设备音量。 + * @param volume 音频播放设备音量。取值范围为 0~255。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +virtual int setPlayoutDeviceVolume(uint32_t volume) = 0; +/** + * @if English + * Gets the volume of audio playback device. + * @param volume The volume of audio playback device. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 获取音频播放设备音量。 + * @param volume 音频播放设备音量。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +virtual int getPlayoutDeviceVolume(uint32_t* volume) = 0; + +/** + * @if English + * Specifies to mute or unmute the audio playback device. + * @param mute indicates whether to unmute the audio playback device. + * - true: Specifies to mute the audio playback device. + * - false: Specifies to unmute the audio playback device. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 静音或取消静音音频播放设备。 + * @param mute 是否静音音频播放设备。 + * - true：静音音频播放设备。 + * - false：取消静音音频播放设备。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +virtual int setPlayoutDeviceMute(bool mute) = 0; + +/** + * @if English + * Confirms whether the audio playback device is muted. + * @param mute indicates the audio playback device is muted. + * - true: The device is muted. + * - false: The device is unmuted. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 获取音频播放设备静音状态。 + * @param mute 音频播放设备静音状态。 + * - true：静音状态。 + * - false：非静音状态。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +virtual int getPlayoutDeviceMute(bool* mute) = 0; +/** + * @if English + * Specifies to mute or unmute the audio playback device. + * @param mute indicates whether to unmute the audio playback device. + * - true: Specifies to mute the audio playback device. + * - false: Specifies to unmute the audio playback device. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 静音或取消静音音频采集设备。 + * @param mute 是否静音音频采集设备。 + * - true：静音音频采集设备。 + * - false：取消静音音频采集设备。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +virtual int setRecordDeviceMute(bool mute) = 0; + +/** + * @if English + * Confirms whether the audio playback device is muted. + * @param mute indicates the audio playback device is muted. + * - true: The device is muted. + * - false: The device is unmuted. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 获取音频采集设备静音状态。 + * @param mute 音频采集设备静音状态。 + * - true: 静音状态。 + * - false: 非静音状态。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +virtual int getRecordDeviceMute(bool* mute) = 0; + +/** + * @if English + * Starts the test of the audio capture device. + *
The method tests whether the audio capture device can work properly. + *
After calling the method, the SDK triggers \ref IRtcEngineEventHandlerEx::onLocalAudioVolumeIndication + * "onLocalAudioVolumeIndication" callback at the time interval set in this method, which reports the volume information of + * the capturing device. + * @note + * - Calls the method before a user needs to join a room. + * - The test of the audio capture device can automatically stop after a call starts. You can also manually stop the test by + * calling stopRecordDeviceTest. + * @param indication_interval indicates the time interval that SDK returns \ref + * IRtcEngineEventHandlerEx::onLocalAudioVolumeIndication "onLocalAudioVolumeIndication" callback. Unit: milliseconds. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 启动音频采集设备测试。 + *
该方法测试音频采集设备是否能正常工作。 + *
调用该方法后，SDK 会按设置的时间间隔触发 \ref IRtcEngineEventHandlerEx::onLocalAudioVolumeIndication + * "onLocalAudioVolumeIndication" 回调， 报告采集设备的音量信息。 + * @note + * - 该方法需在加入房间前调用。 + * - 音频采集设备测试会在通话开始后自动结束，您也可以手动调用 stopRecordDeviceTest 停止音频采集设备测试。 + * @param indication_interval SDK 返回 \ref IRtcEngineEventHandlerEx::onLocalAudioVolumeIndication + * "onLocalAudioVolumeIndication" 回调的时间间隔，单位为毫秒。 + * @return + * - 0: Success. + * - other: Failure. + * @endif + * */ +virtual int startRecordDeviceTest(uint64_t indication_interval) = 0; +/** + * @if English + * Stops the test of the audio capture device. + *
Uses the method to stop the test of the audio capture device. + * @note + * - Calls the method before a user needs to join a room. + * - The test of the audio capture device can automatically stop after a call starts. You can also manually stop the test by + * calling stopRecordDeviceTest. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 停止音频采集设备测试。 + *
该方法停止音频采集设备测试。 + * @note + * - 该方法需在加入房间前调用。 + * - 音频采集设备测试会在通话开始后自动结束，您也可以手动调用 stopRecordDeviceTest 停止音频采集设备测试。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +virtual int stopRecordDeviceTest() = 0; +/** + * @if English + * Starts the test of the audio capture device. + * The method tests whether the audio capture device can work properly. After the test is started, SDK plays the specified + * audio files. If the sound is successfully played, the playback device can work properly. After calling the method, the SDK + * triggers \ref IRtcEngineEventHandlerEx::onLocalAudioVolumeIndication "onLocalAudioVolumeIndication" callback per 100 ms, + * which reports the volume information of the playback device. + * @note + * - Calls the method before a user needs to join a room. + * - The test of the audio playback device can automatically stop after a call starts. You can also manually stop the test by + * calling stopRecordDeviceTest. + * - Supported file formats: wav, mp3, aac. + * @param test_audio_file_path The absolute path of audio files. The path string is encoded in UTF-8. + * @return + * - 0: Success. You can hear the audio of the set files. + * - Other values: Failure. + * @endif + * @if Chinese + * 启动音频播放设备测试。 + * 该方法测试音频播放设备是否能正常工作。启动测试后，SDK 播放指定的音频文件，测试者如果能听到声音，说明播放设备能正常工作。 + * 调用该方法后，SDK 会每隔 100 ms 触发一次 \ref IRtcEngineEventHandlerEx::onLocalAudioVolumeIndication + * "onLocalAudioVolumeIndication" 回调，报告播放设备的音量信息。 + * @note + * - 该方法需在加入房间前调用。 + * - 音频播放设备测试会在通话开始后自动结束，您也可以手动调用 stopPlayoutDeviceTest 停止音频播放设备测试。 + * - 支持文件格式包括 wav、mp3、aac。 + * @param test_audio_file_path 音频文件的绝对路径，路径字符串使用 UTF-8 编码格式。 + * @return + * - 0: 成功，并且可以听到所设置文件的声音。 + * - 其他：失败。 + * @endif + * */ +virtual int startPlayoutDeviceTest(const char* test_audio_file_path) = 0; +/** + * @if English + * Stops the test of the audio capture device. + * @note + * - Calls the method before a user needs to join a room. + * - The test of the audio playback device can automatically stop after a call starts. You can also manually stop the test by + calling stopRecordDeviceTest. + * @return + * - 0: Success. + * - Other values: Failure. + + * @endif + * @if Chinese + * 停止播放设备测试。 + * @note + * - 该方法需在加入房间前调用。 + * - 播放设备测试会在通话开始后自动结束，您也可以手动调用 stopPlayoutDeviceTest 停止播放设备测试。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +virtual int stopPlayoutDeviceTest() = 0; +/** + * @if English + * Starts the test of the audio device circuit. + *
The method tests whether the audio capturing and playback device can work properly. Once the test starts, the audio + capture device captures local audio, and then plays the local audio. The SDK triggers \ref + IRtcEngineEventHandlerEx::onLocalAudioVolumeIndication "onLocalAudioVolumeIndication" callback at the time interval set in + this method, which reports the volume information of the audio. + * @note + * - Calls the method before a user needs to join a room. + * - The test of the audio device circuit can automatically stop after a call starts. You can also manually stop the test by + calling stopRecordDeviceTest. + * - You can use the method locally to test the audio device, which does not require an Internet connection. + * @param indication_interval The time interval that SDK returns \ref IRtcEngineEventHandlerEx::onLocalAudioVolumeIndication + "onLocalAudioVolumeIndication" callback. Unit: milliseconds. + * @return + * - 0: Success. + * - Other values: Failure. + + * @endif + * @if Chinese + * 开始音频设备回路测试。 + *
该方法测试音频采集和播放设备是否能正常工作。一旦测试开始，音频采集设备会采集本地音频，然后使用音频播放设备播放出来。 + SDK 会按设置的时间间隔触发 \ref IRtcEngineEventHandlerEx::onLocalAudioVolumeIndication "onLocalAudioVolumeIndication" 回调， + 报告音量信息。 + * @note + * - 该方法需在加入房间前调用。 + * - 音频设备回路测试会在通话开始后自动结束，您也可以手动调用 stopAudioDeviceLoopbackTest 停止音频设备回路测试。 + * - 该方法仅在本地进行音频设备测试，不涉及网络连接。 + * @param indication_interval SDK 返回 \ref IRtcEngineEventHandlerEx::onLocalAudioVolumeIndication + "onLocalAudioVolumeIndication" 回调的 时间间隔，单位为毫秒。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +virtual int startAudioDeviceLoopbackTest(uint64_t indication_interval) = 0; +/** + * @if English + * Stops the test of the audio device circuit. + * @note + * - Calls the method before a user needs to join a room. + * - The test of the audio device circuit can automatically stop after a call starts. You can also manually stop the test by + calling stopRecordDeviceTest. + * @return + * - 0: Success. + * - Other values: Failure. + + * @endif + * @if Chinese + * 停止音频设备回路测试。 + * @note + * - 该方法需在加入房间前调用。 + * - 音频设备回路测试会在通话开始后自动结束，您也可以手动调用 stopAudioDeviceLoopbackTest 停止音频设备回路测试。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +virtual int stopAudioDeviceLoopbackTest() = 0; +}; +} \ No newline at end of file diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/INertcDeviceCollection.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/INertcDeviceCollection.h new file mode 100644 index 0000000..15d0c73 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/INertcDeviceCollection.h @@ -0,0 +1,81 @@ +/** + * @file NertcDeviceCollection.h + * @brief The interface header file of NERTC UE SDK device NERTC UE SDK device collection. + * All parameter descriptions of the NERTC SDK. All string-related parameters (char *) are encoded in UTF-8. + * @copyright (c) 2021, NetEase Inc. All rights reserved. + */ +#pragma once + +#include "NertcEngineDefines.h" +#include + +namespace nertc { +class IDeviceCollection { +public: + virtual ~IDeviceCollection(){} +/** + * @if English + * Gets the number of devices. + * @note You must call \ref IAudioDeviceManager::enumeratePlayoutDevices "enumeratePlayoutDevices" or \ref + * IAudioDeviceManager::enumerateRecordDevices "enumerateRecordDevices" before calling the method to get the number of playing + * and capturing devices. + * @return The number of capturing and playback devices. + * + * @endif + * @if Chinese + * 获取设备数量。 + * @note 调用此方法之前，必须调用 \ref IAudioDeviceManager::enumeratePlayoutDevices "enumeratePlayoutDevices" 或 \ref + * IAudioDeviceManager::enumerateRecordDevices "enumerateRecordDevices" 方法获取播放或采集设备数量。 + * @return 采集或播放设备数量。 + * @endif + */ +virtual uint16_t getCount() = 0; + +/** + * @if English + * Gets the device information of the specified index. + * @param index specifies the device information that you want to check. The value must be lower than the value returned by + * \ref IDeviceCollection::getCount "getCount". + * @param device_name Device name. + * @param device_id Device ID. + * @return + * - 0: Success. + * - Other values: Failure. + * + * @endif + * @if Chinese + * 获取指定 index 的设备信息。 + * @param index 指定想查询的设备信息。必须小于 \ref IDeviceCollection::getCount "getCount"返回的值。 + * @param device_name 设备名称。 + * @param device_id 设备 ID。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +virtual int getDevice(uint16_t index, char device_name[kNERtcMaxDeviceNameLength], char device_id[kNERtcMaxDeviceIDLength]) = 0; + +/** + * @if English + * Searches specified information about index-related devices. + * @note The link method of returnable devices and the non-useful status determined by the SDK. + * @param index specifies the device information that you want to check. + * @param device_info For information about device information, see \ref NERtcDeviceInfo "NERtcDeviceInfo". + * @return + * - 0: Success. + * - Other values: Failure. + * + * @endif + * @if Chinese + * 检索有关索引设备的指定信息。 + * @note 可返回设备的链接方式，和SDK判定的疑似不可用状态。 + * @param index 指定想查询的设备信息。 + * @param device_info 设备信息，详细信息请参考 \ref NERtcDeviceInfo "NERtcDeviceInfo"。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +virtual int getDeviceInfo(uint16_t index, NERtcDeviceInfo* device_info) = 0; +}; +} \ No newline at end of file diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/INertcEngine.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/INertcEngine.h new file mode 100644 index 0000000..bb9d336 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/INertcEngine.h @@ -0,0 +1,442 @@ +/** @file NertcEngine.h + * @brief The interface header file of NERTC UE SDK. + * All parameter descriptions of the NERTC UE SDK. All string-related parameters (char *) are encoded in UTF-8. + * @copyright (c) 2021, NetEase Inc. All rights reserved. + */ +#pragma once +#include "NertcBase.h" +#include "NertcBaseTypes.h" +#include "NertcEngineDefines.h" +#include "NertcErrorCode.h" +#include "NertcWarnCode.h" +#include "INertcEngineEventHandler.h" + +#include +#include + +namespace nertc { + +/** + * @if English + * RtcEngineContext definition. + * @endif + * @if Chinese + * RtcEngineContext 定义 + * @endif + */ +struct NERtcEngineContext { + /** + * @if English + * Users register the APP key of CommsEase. If you have no APP key in your developer kit, please apply to register a new APP + * key. + * @endif + * @if Chinese + * 用户注册云信的APP Key。如果你的开发包里面缺少 APP Key，请申请注册一个新的 APP Key。 + * @endif + */ +const char* app_key; + + /** + * @if English + * The full path of log content are encoded in UTF-8. + * @endif + * @if Chinese + * 日志目录的完整路径，采用 UTF-8 编码。 + * @endif + */ + const char* log_dir_path; + /** + * @if English + * The log level. The level is kNERtcLogLevelInfo by default. + * @endif + * @if Chinese + * 日志级别，默认级别为 kNERtcLogLevelInfo。 + * @endif + */ + NERtcLogLevel log_level; + + /** + * @if English + * The size of SDK-input log file. Unit: KB. If the value is set as 0, the size of log file is 20M by default. + * @endif + * @if Chinese + * 指定 SDK 输出日志文件的大小上限，单位为 KB。如果设置为 0，则默认为 20 M。 + * @endif + */ + uint32_t log_file_max_size_KBytes; + + /** + * @if English + * IRtcEngineEventHandler callback interface class is used to send callback event notifications to the app from SDK. + * @endif + * @if Chinese + * 用于 SDK 向 App 发送回调事件通知。 + * @endif + */ + IRtcEngineEventHandler* event_handler; + + + /** + * @if English + * The private server address. You need to set the value as empty by default. ** To use a private server, contact technical + * support for details. + * @endif + * @if Chinese + * 私有化服务器地址，默认需要置空。如需启用私有化功能，请联系技术支持获取详情。 + * @endif + */ + NERtcServerAddresses server_config; + +NERtcEngineContext() { +app_key = nullptr; +event_handler = nullptr; +log_dir_path = nullptr; +log_level = kNERtcLogLevelWarning; +log_file_max_size_KBytes = 0; +} +}; +class IRtcEngine { +public: + virtual ~IRtcEngine() {} + /** + * @if English + * Initializes the NERTC SDK service. + *
After calling the createNERtcEngine to create IRtcEngine object, you must call the method to initialize before calling + * other methods. After successfully initializing, the audio and video call mode is enabled by default. + * @warning + * - Callers must use the same AppKey to make audio or video calls. + * - One IRtcEngine instance object must share the same App Key. If you need to change the AppKey, you must first call \ref + * IRtcEngine::release "release" to destroy the current instance, and then call the method to create a new instance. + * @param[in] context The passed RTC engine context object. NERtcEngineContext. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 初始化 NERTC SDK 服务。 + *
在调用 createNERtcEngine() 方法创建 IRtcEngine + * 对象后，必须先调用该方法进行初始化，才能使用其他方法。初始化成功后，默认处于音视频通话模式。 + * @warning + * - 必须使用同一个 App Key 才能进行通话。 + * - 一个 IRtcEngine 实例对象只能使用一个 App Key。如需更换 App Key，必须先调用 \ref IRtcEngine::release "release" + * 方法销毁当前实例，再调用本方法重新创建实例。 + * @param[in] context 传入的RTC engine context对象: NERtcEngineContext. + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +virtual int initialize(const NERtcEngineContext& context) = 0; +/** + * @if English + * Destroys an NERtc instance to release resources. + *
This method releases all resources used by the NERTC SDK. In some cases, real-time audio and video communication is + * only needed upon your demands. If no RTC calls are required, you can call this method to release resources.
After you + * call the release method, other methods and callbacks supported by the SDK become unavailable. If you want to use RTC calls, + * you must create a new NERtc instance. + * @note If you need to use IRtcEngine instance again that cannot be initialized after release, you need to createNERtcEngine + * after destroyNERtcEngine. + * @param[in] sync The value is true by default, which can only be set to true. The default setting indicates synchronization + * call of the instance. You must return before you release the resources and return the IRtcEngine object resources.
App + * cannot call the interface in the callbacks returned by the SDK. If not, deadlock occurs and the SDK can only retrieve + * related object resources before the callback is returned. The SDK automatically detects the deadlock, and changes the + * deadlock to asynchronous call. However, the asynchronous call consumes extra time. + * @endif + * @if Chinese + * 销毁 NERtc 实例，释放资源。 + *
该方法释放 NERTC SDK 使用的所有资源。有些 App + * 只在用户需要时才进行实时音视频通信，不需要时则将资源释放出来用于其他操作，该方法适用于此类情况。
调用 release + * 方法后，您将无法再使用 SDK 的其它方法和回调。如需再次使用实时音视频通话功能，您必须重新创建一个新的 NERtc 实例。 + * @note 如果需要重新使用IRtcEngine，release 后不能再 initialize，需要 destroyNERtcEngine 后重新 createNERtcEngine。 + * @param[in] sync 默认为 true 且只能设置为 true，表示同步调用，等待 IRtcEngine 对象资源释放后再返回。
App 不应该在 SDK + * 产生的回调中调用该接口，否则由于 SDK 要等待回调返回才能回收相关的对象资源，会造成死锁。SDK + * 会自动检测这种死锁并转为异步调用，但是检测本身会消耗额外的时间。 + * @endif + */ +virtual void release(bool sync = false) = 0; +/** + * @if English + * Sets the role of a user in live streaming. + *
The method sets the role to host or audience. The permissions of a host and a viewer are different. + * - A host has the permissions to open or close a camera, publish streams, call methods related to publishing streams in + * interactive live streaming. The status of the host is visible to the users in the room when the host joins or leaves the + * room. + * - The audience has no permissions to open or close a camera, call methods related to publishing streams in interactive live + * streaming, and is invisible to other users in the room when the user that has the audience role joins or leaves the room. + * @note + * - By default, a user joins a room as a host. + * - Before a user joins a room, the user can call this method to change the client role to audience. Users can switch the + * role of a user through the interface after joining the room. + * - If the user switches the role to audience, the SDK automatically closes the audio and video devices. + * @param[in] role The role of a user. NERtcClientRole. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 在直播场景中设置用户角色。 + *
用户角色支持设置为主播或观众，主播和观众的权限不同。 + * - 主播：可以开关摄像头等设备、可以发布流、可以操作互动直播推流相关接口、上下线对其他房间内用户可见。 + * - 观众：不可以开关摄像头等设备、不可以发布流、不可以操作互动直播推流相关接口、上下线对其他房间内用户不可见。 + * @note + * - 默认情况下用户以主播角色加入房间。 + * - 在加入房间前，用户可以调用本接口切换本端角色为观众。在加入房间后，用户也可以通过本接口切换用户角色。 + * - 用户切换为观众角色时，SDK 会自动关闭音视频设备。 + * @param[in] role 用户角色。 NERtcClientRole + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +virtual int setClientRole(NERtcClientRole role) = 0; +/** + * @if English + * Sets a room scene. + *
You can set a room scene for a call or live event. Different QoS policies are applied to different scenes. + * @note You must set the profile after joining a call. The setting is invalid after the call ends. + * @param[in] profile Sets the room scene. For more information, see NERtcChannelProfileType. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置房间场景。 + *
房间场景可设置为通话或直播场景，不同的场景中 QoS 策略不同。 + * @note 必须在加入通话前设置，开始通话后设置无效，结束通话后保留之前的设置。 + * @param[in] profile 设置房间场景。详细信息请参考 NERtcChannelProfileType。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +virtual int setChannelProfile(NERtcChannelProfileType profile) = 0; +/** + * @if English + * Joins a channel of audio and video call. + *
If the specified room does not exist when you join the room, a room with the specified name is automatically created in +the server provided by CommsEase. + * - After you join a room by calling the relevant method supported by the SDK, users in the same room can make audio or video +calls. Users that join the same room can start a group chat. Apps that use different AppKeys cannot communicate with each +other. + * - After the method is called successfully, the onJoinChannel callback is locally triggered, and the onUserJoined callback +is remotely triggered. + * - If you join a room, you subscribe to the audio streams from other users in the same room by default. In this case, the +data usage is billed. To unsubscribe, you can call the setParameters method. + * - In live streaming, audiences can switch channels by calling switchChannel. + * @note The ID of each user must be unique. + * @param[in] token The certification signature used in authentication (NERTC Token). Valid values: + - Null. You can set the value to null in the debugging mode. This poses a security risk. We recommend that +you contact your business manager to change to the default safe mode before your product is officially launched. + - NERTC Token acquired. In safe mode, the acquired token must be specified. If the specified token is +invalid, users are unable to join a room. We recommend that you use the safe mode. + * @param[in] channel_name The name of the room. Users that use the same name can join the same room. The name must be of +STRING type and must be 1 to 64 characters in length. The following 89 characters are supported: a-z, A-Z, 0-9, space, +!#$%&()+-:;≤.,>? @[]^_{|}~”. + * @param[in] uid The unique identifier of a user. The uid of each user in a room must be unique. +
uid is optional. The default value is 0. If the uid is not specified (set to 0), the SDK automatically +assigns a random uid and returns the uid in the callback of onJoinChannel. The application layer must keep and maintain the +return value. The SDK does not maintain the return value. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 加入音视频房间。 + *
加入音视频房间时，如果指定房间尚未创建，云信服务器内部会自动创建一个同名房间。 + * - SDK 加入房间后，同一个房间内的用户可以互相通话，多个用户加入同一个房间，可以群聊。使用不同 App Key 的 App 之间不能互通。 + * - 成功调用该方加入房间后，本地会触发onJoinChannel回调，远端会触发onUserJoined回调。 + * - +用户成功加入房间后，默认订阅房间内所有其他用户的音频流，可能会因此产生用量并影响计费。如果想取消自动订阅，可以在通话前通过调用setParameters方法实现。 + * - 直播场景中的观众角色可以通过 switchChannel 快速切换房间。 + * @note 房间内每个用户的用户 ID 必须是唯一的。 + * @param[in] token 安全认证签名（NERTC Token）。可设置为： + - null。调试模式下可设置为 +null。安全性不高，建议在产品正式上线前在云信控制台中将鉴权方式恢复为默认的安全模式。 + - 已获取的NERTC Token。安全模式下必须设置为获取到的 Token 。若未传入正确的 Token +将无法进入房间。推荐使用安全模式。 + * @param[in] channel_name 房间名称，设置相同房间名称的用户会进入同一个通话房间。字符串格式，长度为1~ 64 +字节。支持以下89个字符：a-z, A-Z, 0-9, space, !#$%&()+-:;≤.,>? @[]^_{|}~” + * @param[in] uid 用户的唯一标识 id，房间内每个用户的 uid 必须是唯一的。 +
uid 可选，默认为 0。如果不指定（即设为 0），SDK 会自动分配一个随机 uid，并在 onJoinChannel +回调方法中返回，App 层必须记住该返回值并维护，SDK 不对该返回值进行维护。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 +* @endif +*/ +virtual int joinChannel(const char* token, const char* channel_name, uid_t uid, const NERtcJoinChannelOptions& channel_options) = 0; +/** + * @if English + * Switches to a room of audio and video call. + *
In live streaming, the audience can call this method to switch from the current room to another room. + *
After you switch to another room by calling the method, the local first receive the onLeaveChannel callback that the + user leaves the room, and then receives the + *
onJoinChanne callback that the user joins the new room. Remote clients receive the return from onUserLeave and + onUserJoined. + * @note + * - The method applies to only the live streaming. The role is the audience in the RTC room. The room scene is set to live + streaming by calling the setchannelprofile method, and the role of room members is set to audience by calling the + setClientRole method. + * - By default, after a room member switches to another room, the room member subscribes to audio streams from other members + of the new room. In this case, data usage is charged and billing is updated. If you want to unsubscribe to the previous audio + stream, you can call the subscribeRemoteAudio method with a value of false passed in. + * @param[in] token The certification signature used in authentication (NERTC Token). Valid values: + - Null. You can set the value to null in the debugging mode. We recommend you change to the default safe + mode before your product is officially launched. + - NERTC Token acquired. In safe mode, the acquired token must be specified. If the specified token is + invalid, users are unable to join a channel. We recommend that you use the safe mode. + * @param[in] channel_name The room name that a user wants to switch to. + + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 快速切换音视频房间。 + *
房间场景为直播场景时，房间中角色为观众的成员可以调用该方法从当前房间快速切换至另一个房间。 + *
成功调用该方切换房间后，本端会先收到离开房间的回调 onLeaveChannel，再收到成功加入新房间的回调 + onJoinChannel。远端用户会收到 onUserLeave 和 onUserJoined 的回调。 + * @note + * - 房间成员成功切换房间后，默认订阅房间内所有其他成员的音频流，因此产生用量并影响计费。如果想取消订阅，可以通过调用相应的 + subscribeRemoteAudio 方法传入 false 实现。 + * @param[in] token 安全认证签名（NERTC Token）。可设置为： + - null。调试模式下可设置为 null。建议在产品正式上线前在云信控制台中将鉴权方式恢复为默认的安全模式。 + - 已获取的NERTC Token。安全模式下必须设置为获取到的 Token 。若未传入正确的 Token + 将无法进入房间。推荐使用安全模式。 + * @param[in] channel_name 期望切换到的目标房间名称。 + + * @return + * -0: 方法调用成功 + * -其他：方法调用失败 + * @endif + */ +virtual int switchChannel(const char* token, const char* channel_name, const NERtcJoinChannelOptions& channel_options) = 0; +/** + * @if English + * Switches to a room of audio and video call. + *
In live streaming, the audience can call this method to switch from the current room to another room. + *
After you switch to another room by calling the method, the local first receive the onLeaveChannel callback that the + user leaves the room, and then receives the + *
onJoinChanne callback that the user joins the new room. Remote clients receive the return from onUserLeave and + onUserJoined. + * @note + * - Call this method to leave from the current room, and then join another room. + * - By default, after a room member switches to another room, the room member subscribes to audio streams from other members + of the new room. In this case, data usage is charged and billing is updated. If you want to unsubscribe to the previous audio + stream, you can call the subscribeRemoteAudio method with a value of false passed in. + * @param[in] token The certification signature used in authentication (NERTC Token). Valid values: + - Null. You can set the value to null in the debugging mode. We recommend you change to the default safe + mode before your product is officially launched. + - NERTC Token acquired. In safe mode, the acquired token must be specified. If the specified token is + invalid, users are unable to join a channel. We recommend that you use the safe mode. + * @param[in] channel_name The room name that a user wants to switch to. + * @param[in] uid The ID of user. + + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 快速切换音视频房间。 + *
调用该方法从当前房间leave，然后加入至另一个房间。 + *
成功调用该方切换房间后，本端会先收到离开房间的回调 onLeaveChannel，再收到成功加入新房间的回调 + onJoinChannel。远端用户会收到 onUserLeave 和 onUserJoined 的回调。 + * - 房间成员成功切换房间后，默认订阅房间内所有其他成员的音频流，因此产生用量并影响计费。如果想取消订阅，可以通过调用相应的 + subscribeRemoteAudio 方法传入 false 实现。 + * @param[in] token 安全认证签名（NERTC Token）。可设置为： + - null。调试模式下可设置为 null。建议在产品正式上线前在云信控制台中将鉴权方式恢复为默认的安全模式。 + - 已获取的NERTC Token。安全模式下必须设置为获取到的 Token 。若未传入正确的 Token + 将无法进入房间。推荐使用安全模式。 + * @param[in] channel_name 期望切换到的目标房间名称。 + * @param[in] uid 用户ID。 + + * @return + * -0: 方法调用成功 + * -其他：方法调用失败 + * @endif + */ +virtual int switchChannelEx(const char* token, const char* channel_name, uid_t uid, const NERtcJoinChannelOptionsEx& channel_options) = 0; +/** + * @if English + * Leaves the room. + *
Leaves a room for hang up or calls ended. + *
A user can call the leaveChannel method to end the call before the user makes another call. + *
After the method is called successfully, the onLeaveChannel callback is locally triggered, and the onUserLeave callback + * is remotely triggered. + * @note + * - The method is asynchronous call. Users cannot exit the room when the method is called and returned. After users exit the + * room, the SDK triggers the onLeaveChannel callback. + * - If you call leaveChannel method and instantly call release method, the SDK cannot trigger onLeaveChannel callback. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 离开房间。 + *
离开房间，即挂断或退出通话。 + *
结束通话时，必须调用leaveChannel结束通话，否则无法开始下一次通话。 + *
成功调用该方法离开房间后，本地会触发onLeaveChannel回调，远端会触发onUserLeave回调。 + * @note + * - 该方法是异步操作，调用返回时并没有真正退出房间。在真正退出房间后，SDK 会触发onLeaveChannel回调。 + * - 如果您调用了leaveChannel后立即调用release，SDK 将无法触发onLeaveChannel回调。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +virtual int leaveChannel() = 0; +/** + * @if English + * Gets the pointer of device administrators object. + * @param[in] iid The iid of interface preferred. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 获取设备管理员对象的指针。 + * @param[in] iid 想要获取的接口的iid. + * @param[in] inter 指向 DeviceManager 对象的指针。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +virtual int queryInterface(NERtcInterfaceIdType iid, void** inter) = 0; +/** + * @if English + * Enables or disables local audio capture. + *
The method can enable the local audio again to start local audio capture and processing. + *
The method does not affect receiving or playing remote audio and audio streams. + * @note The method is different from \ref IRtcEngineEx::muteLocalAudioStream "muteLocalAudioStream" in:. + * - \ref IRtcEngine::enableLocalAudio "enableLocalAudio": Enables local audio capture and processing. + * - \ref IRtcEngineEx::muteLocalAudioStream "muteLocalAudioStream": Stops or continues publishing local audio streams. + * @note The method enables the internal engine, which is still valid after you call \ref IRtcEngine::leaveChannel + * "leaveChannel". + * @param[in] enabled + * - true: Enables local audio feature again. You can enable local audio capture or processing by default. + * - false: Disables local audio feature again. You can stop local audio capture or processing. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 开启/关闭本地音频采集 + *
该方法可以重新开启本地语音功能，重新开始本地音频采集及处理。 + *
该方法不影响接收或播放远端音频流。 + * @note 该方法与 \ref IRtcEngineEx::muteLocalAudioStream "muteLocalAudioStream" 的区别在于: + * - \ref IRtcEngine::enableLocalAudio "enableLocalAudio": 开启本地语音采集及处理 + * - \ref IRtcEngineEx::muteLocalAudioStream "muteLocalAudioStream": 停止或继续发送本地音频流 + * @note 该方法设置内部引擎为启用状态，在 \ref IRtcEngine::leaveChannel "leaveChannel" 后仍然有效。 + * @param[in] type 音频流类型: + * @param[in] enabled + * - true: 重新开启本地语音功能，即开启本地语音采集或处理（默认） + * - false: 关闭本地语音功能，即停止本地语音采集或处理 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +virtual int enableLocalAudio(NERtcAudioStreamType type, bool enabled) = 0; +}; +} \ No newline at end of file diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/INertcEngineEventHandler.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/INertcEngineEventHandler.h new file mode 100644 index 0000000..5c22375 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/INertcEngineEventHandler.h @@ -0,0 +1,1397 @@ +/** + * @file nertc_engine_event_handler.h + * @brief The interface header file of expansion callback of the NERTC SDK. + * All parameter descriptions of the NERTC SDK. All string-related parameters (char *) are encoded in UTF-8. + * @copyright (c) 2021, NetEase Inc. All rights reserved. + */ + +#pragma once + +#include "NertcBaseTypes.h" +#include "NertcEngineDefines.h" +#include "NertcErrorCode.h" +#include "NertcWarnCode.h" + +/** + * @namespace nertc + * @brief namespace nertc + */ +namespace nertc { +/** + * @if English + * IRtcEngineEventHandler callback interface class is used to send callback event notifications to the app from SDK. The app + * gets event notifications from the SDK through inheriting the interface class. All methods in this interface class have their + * (empty) default implementations, and the application can inherit only some of the required events instead of all of them. + * When calling a callback method, the application must not implement time-consuming operations or call blocking-triggered APIs. + * For example, if you want to enable audio and video, the SDK may be affected in the runtime. + * @endif + * @if Chinese + * IRtcEngineEventHandler 回调接口类用于 SDK 向 App 发送回调事件通知，App 通过继承该接口类的方法获取 SDK 的事件通知。 + * 接口类的所有方法都有缺省（空）实现，App 可以根据需要只继承关心的事件。在回调方法中，App 不应该做耗时或者调用可能会引起阻塞的 + * API（如开启音频或视频等），否则可能影响 SDK 的运行。 + * @endif + */ +class IRtcEngineEventHandler { + public: + virtual ~IRtcEngineEventHandler() {} + + /** + * @if English + * Occurs when the error occurs. + *
The callback is triggered to report an error related to network or media during SDK runtime. In most cases, the SDK + * cannot fix the issue and resume running. The SDK requires the app to take action or informs the user of the issue. + * @param error_code The error code. For more information, see NERtcDMErrorCode. + * @param msg Error description. + * @endif + * @if Chinese + * 发生错误回调。 + *
该回调方法表示 SDK 运行时出现了（网络或媒体相关的）错误。通常情况下，SDK上报的错误意味着SDK无法自动恢复，需要 App + * 干预或提示用户。 + * @param error_code 错误码。详细信息请参考 NERtcDMErrorCode + * @param msg 错误描述。 + * @endif + */ + virtual void onError(int error_code, const char* msg) { + (void)error_code; + (void)msg; + } + + /** + * @if English + * Occurs when a warning occurs. + *
The callback is triggered to report a warning related to network or media during SDK runtime. In most cases, the app + * ignores the warning message and the SDK resumes running. + * @param warn_code The warning code. For more information, see {@link NERtcWarnCode}. + * @param msg The warning description. + * @endif + * @if Chinese + * 发生警告回调。 + *
该回调方法表示 SDK 运行时出现了（网络或媒体相关的）警告。通常情况下，SDK 上报的警告信息 App 可以忽略，SDK 会自动恢复。 + * @param warn_code 警告码。详细信息请参考 {@link NERtcWarnCode}。 + * @param msg 警告描述。 + * @endif + */ + virtual void onWarning(int warn_code, const char* msg) { + (void)warn_code; + (void)msg; + } + /** + * @if English + * Occurs when an API call finished. + *
This callback method indicates that the SDK has finished executing a user's API call. + * @param api_name The API name. + * @param error The execute result code. + * @param message The execute result message. + * @endif + * @if Chinese + * API调用结束回调。 + *
该回调方法表示 SDK 执行完了一个用户的API调用。 + * @param api_name API名称 + * @param error API执行结果错误码。 + * @param message API执行结果描述。 + * @endif + */ + virtual void onApiCallExecuted(const char* api_name, NERtcErrorCode error_code, const char* msg) { + (void)api_name; + (void)error_code; + (void)msg; + }; + +/** + * @if English + * Occurs when the hardware resources are released. + *
The SDK prompts whether hardware resources are successfully released. + * @param result The result. + * @endif + * @if Chinese + * 释放硬件资源的回调。 + *
SDK提示释放硬件资源是否成功。 + * @param result 返回结果。 + * @endif + */ + virtual void onReleasedHwResources(NERtcErrorCode result) { (void)result; } + + /** + * @if English + * Allows a user to join a room. The callback indicates that the client has already signed in. + * @param cid The ID of the room that the client joins. + * @param uid Specifies the ID of a user. If you specify the uid in the joinChannel method, a specificed ID is returned at + * the time. If not, the ID automatically assigned by the CommsEase’s server is returned. + * @param result Indicates the result. + * @param elapsed The time elapsed from calling the joinChannel method to the occurrence of this event. Unit: milliseconds. + * @endif + * @if Chinese + * 加入房间回调，表示客户端已经登入服务器。 + * @param cid 客户端加入的房间 ID。 + * @param uid 用户 ID。 如果在 joinChannel 方法中指定了 uid，此处会返回指定的 ID; 如果未指定 + * uid，此处将返回云信服务器自动分配的 ID。 + * @param result 返回结果。 + * @param elapsed 从 joinChannel 开始到发生此事件过去的时间，单位为毫秒。 + * @endif + */ + virtual void onJoinChannel(channel_id_t cid, uid_t uid, NERtcErrorCode result, uint64_t elapsed) { + (void)cid; + (void)uid; + (void)result; + (void)elapsed; + } + + /** + * @if English + * Triggers reconnection. + *
In some cases, a client may be disconnected from the server, the SDK starts reconnecting. The callback is triggered + * when the reconnection starts. + * @param cid Specifies the ID of a room. + * @param uid Specifies the ID of a user. + * @endif + * @if Chinese + * 触发重连。 + *
有时候由于网络原因，客户端可能会和服务器失去连接，SDK会进行自动重连，开始自动重连后触发此回调。 + * @param cid 房间 ID。 + * @param uid 用户 ID。 + * @endif + */ + virtual void onReconnectingStart(channel_id_t cid, uid_t uid) { + (void)cid; + (void)uid; + } + + /** + * @if English + * Occurs when the state of network connection is changed. + *
The callback is triggered when the state of network connection is changed. The callback returns the current state of + * network connection and the reason why the network state changes. + * @param state The state of current network connection. + * @param reason The reason why the network state changes. + * @endif + * @if Chinese + * 网络连接状态已改变回调。 + *
该回调在网络连接状态发生改变的时候触发，并告知用户当前的网络连接状态和引起网络状态改变的原因。 + * @param state 当前的网络连接状态。 + * @param reason 引起当前网络连接状态发生改变的原因。 + * @endif + */ + virtual void onConnectionStateChange(NERtcConnectionStateType state, NERtcReasonConnectionChangedType reason) { + (void)state; + (void)reason; + } + /** + * @if English + * Occurs when the network type is changed. + *
The callback is triggered when network is changed. The callback returns the current network type. + * @param new_type The new type of current network. + * @endif + * @if Chinese + * 网络类型已经改变的回调。 + *
该回调在网络发生改变的时候触发，并告知用户当前的网络类型。 + * @param new_type 当前的网络类型。 + * @endif + */ + virtual void onNetworkTypeChanged(NERtcNetworkType new_type) { + (void)new_type; + }; + /** + * @if English + * Occurs when a user rejoins a room. + *
If a client is disconnected from the server due to poor network quality, the SDK starts reconnecting. If the client and + * server are reconnected, the callback is triggered. + * @param cid The ID of the room that the client joins. + * @param uid The ID of a user. + * @param result The result. + * @param elapsed The time elapsed from reconnection to the occurrence of this event. Unit: milliseconds. + * @endif + * @if Chinese + * 重新加入房间回调。 + *
在弱网环境下，若客户端和服务器失去连接，SDK会自动重连。自动重连成功后触发此回调方法。 + * @param cid 客户端加入的房间 ID。 + * @param uid 用户 ID。 + * @param result 返回结果。 + * @param elapsed 从开始重连到发生此事件过去的时间，单位为毫秒。 + * @endif + */ + virtual void onRejoinChannel(channel_id_t cid, uid_t uid, NERtcErrorCode result, uint64_t elapsed) { + (void)cid; + (void)uid; + (void)result; + (void)elapsed; + } + + /** + * @if English + * Occurs when a user leaves a room. + *
After an app invokes the leaveChannel method, SDK prompts whether the app successfully leaves the room. + * @param result The result. + * @endif + * @if Chinese + * 退出房间回调。 + *
App 调用 leaveChannel 方法后，SDK 提示 App 退出房间是否成功。 + * @param result 返回结果。 + * @param channel_id 离开的channel的ID。 + * @endif + */ + virtual void onLeaveChannel(NERtcErrorCode result, uint64_t channel_id) { + (void)result; + (void)channel_id; +} + + /** + * @if English + * Network connection interruption. + * @note + * - The callback is triggered if the SDK fails to connect to the server three consecutive times after you successfully call + * the joinChannel method. + * - A client may be disconnected from the server in poor network connection. At this time, the SDK needs not automatically + * reconnecting until the SDK triggers the callback method. + * @param reason The reason why the network is disconnected. + * @endif + * @if Chinese + * 网络连接中断 + * @note + * - SDK 在调用 joinChannel 加入房间成功后，如果和服务器失去连接且连续 3 次重连失败，就会触发该回调。 + * - 由于非网络原因，客户端可能会和服务器失去连接，此时SDK无需自动重连，直接触发此回调方法。 + * @param reason 网络连接中断原因。 + * @endif + */ + virtual void onDisconnect(NERtcErrorCode reason) { (void)reason; } + + /** + * @if English + * Occurs when a user changes the role in live streaming. + *
After the local user joins a room, the user can call the \ref IRtcEngine::setClientRole "setClientRole" to change the + * role. Then, the callback is triggered. For example, you can switch the role from host to audience, or from audience to + * host. + * @note In live streaming, if you join a room and successfully call this method to change the role, the following callbacks + * are triggered. + * - If the role changes from host to audience, the onClientRoleChange is locally triggered, and the \ref + * nertc::IRtcEngineEventHandler::onUserLeft "onUserLeft" is remotely triggered. + * - If the role is changed from audience to host, the onClientRoleChange callback is locally triggered, and the \ref + * nertc::IRtcEngineEventHandler::onUserJoined "onUserJoined" is remotely triggered. + * @param oldRole The role before the user changes the role. + * @param newRole The role after the change. + * @endif + * @if Chinese + * 直播场景下用户角色已切换回调。 + *
本地用户加入房间后，通过 \ref IRtcEngine::setClientRole "setClientRole" + * 切换用户角色后会触发此回调。例如主播切换为观众、从观众切换为主播。 + * @note 直播场景下，如果您在加入房间后调用该方法切换用户角色，调用成功后，会触发以下回调： + * - 主播切观众，本端触发onClientRoleChanged回调，远端触发\ref nertc::IRtcEngineEventHandler::onUserLeft "onUserLeft"回调。 + * - 观众切主播，本端触发onClientRoleChanged回调，远端触发\ref nertc::IRtcEngineEventHandler::onUserJoined + * "onUserJoined"回调。 + * @param oldRole 切换前的角色。 + * @param newRole 切换后的角色。 + * @endif + */ + virtual void onClientRoleChanged(NERtcClientRole oldRole, NERtcClientRole newRole) { + (void)oldRole; + (void)newRole; + } + + /** + * @if English + * Occurs when a remote user joins the current room. + *
The callback prompts that a remote user joins the room and returns the ID of the user that joins the room. If the user + * ID already exists, the remote user also receives a message that the user already joins the room, which is returned by the + * callback. + * @param uid The ID of the user that joins the room. + * @param user_name The name of the remote user who joins the room. + * @endif + * @if Chinese + * 远端用户加入当前房间回调。 + *
该回调提示有远端用户加入了房间，并返回新加入用户的 + * ID；如果加入之前，已经有其他用户在房间中了，新加入的用户也会收到这些已有用户加入房间的回调。 + * @param uid 新加入房间的远端用户 ID。 + * @param user_name 新加入房间的远端用户名。 + * @param custom_info 该远端用户加入的额外信息。 + * @endif + */ + virtual void onUserJoined(uid_t uid, const char* user_name, const NERtcUserJoinExtraInfo& custom_info) { + (void)uid; + (void)user_name; + (void)custom_info; + } + + /** + * @if English + * Occurs when a remote user leaves a room. + *
A message is returned indicates that a remote user leaves the room or becomes disconnected. In most cases, a user + * leaves a room due to the following reasons: The user exit the room or connections time out. + * - When a user leaves a room, remote users will receive callback notifications that users leave the room. In this way, users + * can be specified to leave the room. + * - If the connection times out, and the user does not receive data packets for a time period of 40 to 50 seconds, then the + * user becomes disconnected. + * @param uid The ID of the user that leaves the room. + * @param reason The reason why remote user leaves. + * @endif + * @if Chinese + * 远端用户离开当前房间的回调。 + *
提示有远端用户离开了房间（或掉线）。通常情况下，用户离开房间有两个原因，即正常离开和超时掉线： + * - 正常离开的时候，远端用户会收到正常离开房间的回调提醒，判断用户离开房间。 + * - 超时掉线的依据是，在一定时间内（40~50s），用户没有收到对方的任何数据包，则判定为对方掉线。 + * @param uid 离开房间的远端用户 ID。 + * @param reason 远端用户离开原因。 + * @param custom_info 该远端用户离开的额外信息。 + * @endif + */ + virtual void onUserLeft(uid_t uid, NERtcSessionLeaveReason reason, const NERtcUserJoinExtraInfo& custom_info) { + (void)uid; + (void)reason; + (void)custom_info; + } + /** + * @if English + * Occurs when a remote user enables audio. + * @param uid The ID of a remote user. + * @endif + * @if Chinese + * 远端用户开启音频的回调。 + * @param type 远端用户流类型。 + * @param uid 远端用户ID。 + * @endif + */ + virtual void onUserAudioStart(NERtcAudioStreamType type, uid_t uid) { + (void)type; + (void)uid; + } + /** + * @if English + * Occurs when a remote user disables audio. + * @param uid The ID of a remote user. + * @endif + * @if Chinese + * 远端用户停用音频的回调。 + * @param uid 远端用户ID。 + * @endif + */ + virtual void onUserAudioStop(NERtcAudioStreamType type, uid_t uid) { + (void)type; + (void)uid; + } + /** + * @if English + * Occurs when a remote user enables video. + * @param uid The ID of a remote user. + * @param max_profile The resolution of video encoding measures the encoding quality. + * @endif + * @if Chinese + * 远端用户开启视频的回调。 + * @param type 远端用户流类型。 + * @param uid 远端用户ID。 + * @param max_profile 视频编码的分辨率，用于衡量编码质量。 + * @endif + */ + virtual void onUserVideoStart(NERtcVideoStreamType type, uid_t uid, NERtcVideoProfileType max_profile) { + (void)type; + (void)uid; + (void)max_profile; + } + /** + * @if English + * Occurs when a remote user disables video. + * @param uid The ID of a remote user. + * @endif + * @if Chinese + * 远端用户停用视频的回调。 + * @param type 远端用户流类型。 + * @param uid 远端用户ID。 + * @endif + */ + virtual void onUserVideoStop(NERtcVideoStreamType type, uid_t uid) { + (void)type; + (void)uid; +} +/** + * @if English + * Occurs when screen sharing is paused/resumed/started/ended. + *
The method applies to Windows only. + * @since V4.2.0 + * @param status Screen capture status. For more information, see #nertc_screen_capture_status_t. + * @endif + * @if Chinese + * 屏幕共享状态变化回调。 + *
该方法仅适用于 Windows 平台。 + * @since V4.2.0 + * @param status 屏幕共享状态。详细信息请参考 #nertc_screen_capture_status_t 。 + * @endif + */ + virtual void onScreenCaptureStatusChanged(NERtcScreenCaptureStatus status) {(void)status;} + /** + * @if English + * Occurs when video configurations of remote users are updated. + * @param uid The ID of a remote user. + * @param max_profile The resolution of video encoding measures the encoding quality. + * @endif + * @if Chinese + * @param uid 远端用户 ID。 + * @param max_profile 视频编码的分辨率，用于衡量编码质量。 + * @endif + */ + virtual void onUserVideoProfileUpdate(uid_t uid, NERtcVideoProfileType max_profile) { + (void)uid; + (void)max_profile; + } + /** + * @if English + * Callbacks that specify whether to mute remote users. + * @param uid The ID of a remote user. + * @param mute indicates whether to unmute the remote user. + * @endif + * @if Chinese + * 远端用户是否静音的回调。 + * @param type 音频流类型。 + * @param uid 远端用户ID。 + * @param mute 是否静音。 + * @endif + */ + virtual void onUserAudioMute(NERtcAudioStreamType stream_type, uid_t uid, bool mute) { + (void)stream_type; + (void)uid; + (void)mute; + } + /** + * @if English + * Occurs when a remote user stops or resumes sending video streams. + * @param uid The ID of a remote user. + * @param mute Whether to disable video streams. + * @endif + * @if Chinese + * 远端用户暂停或恢复发送视频流的回调。 + * @param type 视频流类型。 + * @param uid 远端用户ID。 + * @param mute 是否禁视频流。 + * @endif + */ + virtual void onUserVideoMute(NERtcVideoStreamType stream_type, uid_t uid, bool mute){ + (void)stream_type; + (void)uid; + (void)mute; + } + /** + * @if English + * Occurs when the audio routing changes. + * @param routing The current audio output routing. + * @endif + * @if Chinese + * 音频路由变化回调。 + * @param routing 当前音频输出路由。 + * @endif + */ + virtual void onAudioDeviceRoutingDidChange(NERtcAudioOutputRouting routing){ + (void)routing; + } + /** + * @if English + * Occurs when the state of the audio device changes. + * @param device_id Device ID. + * @param device_type The type of the device. For more information, see NERtcAudioDeviceType_t. + * @param device_state The state of the audio device. + * @endif + * @if Chinese + * 音频设备状态更改的回调。 + * @param device_id 设备ID。 + * @param device_type 音频设备类型。详细信息请参考 NERtcAudioDeviceType_t。 + * @param device_state 音频设备状态。 + * @endif + */ + virtual void onAudioDeviceStateChanged(const char* device_id,NERtcAudioDeviceType device_type, NERtcAudioDeviceState device_state) { + (void)device_id; + (void)device_type; + (void)device_state; + } + /** + * @if English + * Occurs when the default audio devices changes. + * @param device_id Device ID. + * @param device_type The type of the device. + * @endif + * @if Chinese + * 音频默认设备更改的回调。 + * @param device_id 设备ID。 + * @param device_type 音频设备类型。 + * @endif + */ + virtual void onAudioDefaultDeviceChanged(const char* device_id, NERtcAudioDeviceType device_type){ + (void)device_id; + (void)device_type; + } + /** + * @if English + * Occurs when the state of the video device is changed. + * @param device_id Device ID. + * @param device_type The type of the video device. + * @param device_state The state of the video device. + * @endif + * @if Chinese + * 视频设备状态已改变的回调。 + * @param device_id 设备ID。 + * @param device_type 视频设备类型。 + * @param device_state 视频设备状态。 + * @endif + */ + virtual void onVideoDeviceStateChanged(const char* device_id,NERtcVideoDeviceType device_type,NERtcVideoDeviceState device_state){ + (void)device_id; + (void)device_type; + (void)device_state; + } + /** + * @if English + * Occurs when the camera focus position changes. + * The callback indicates that the camera focus position changes. + * The callback is triggered if a local user calls the setCameraFocusPosition method to change the focus position. + * @note The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official + * website of CommsEase and replace the audio-only SDK. + * @param info The new focusposition. + * @endif + * @if Chinese + * 摄像头对焦区域已改变回调。 + * 该回调表示相机的对焦区域发生了改变。 + * 该回调是由本地用户调用 setCameraFocusPosition 方法改变对焦位置触发的。 + * @note 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。 + * @param info 新的对焦区域位置。 + * @endif + */ + virtual void onCameraFocusChanged(const NERtcCameraFocusAndExposureInfo& info){ + (void)info; + } + /** + * @if English + * Occurs when the camera exposure position changes. + * The callback is triggered if a local user calls the setCameraExposurePosition method to change the exposure position. + * @note The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official + * website of CommsEase and replace the audio-only SDK. + * @param info The new exposure position. + * @endif + * @if Chinese + * 摄像头曝光区域已改变回调。 + * 该回调是由本地用户调用 setCameraExposurePosition方法改变曝光位置触发的。 + * @note 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。 + * @param info 新的曝光区域位置信息。 + * @endif + */ + virtual void onCameraExposureChanged(const NERtcCameraFocusAndExposureInfo& info) { + (void)info; + } + /** + * @if English + * Occurs when the first audio frame from a remote user is received. + * @param uid The ID of a remote user whose audio streams are sent. + * @endif + * @if Chinese + * 已接收到远端音频首帧的回调。 + * @param type 音频流类型。 + * @param uid 远端用户 ID，指定是哪个用户的音频流。 + * @endif + */ + virtual void onFirstAudioDataReceived(NERtcAudioStreamType type, uid_t uid) { + (void)type; + (void)uid; + } + /** + * @if English + * Occurs when the first video frame from a remote user is displayed. + *
If the first video frame from a remote user is displayed in the view, the callback is triggered. + * @param uid The ID of a user whose audio streams are sent. + * @endif + * @if Chinese + * 已显示首帧远端视频的回调。 + * 第一帧远端视频显示在视图上时，触发此调用。 + * @param type 视频流类型。 + * @param uid 用户 ID，指定是哪个用户的视频流。 + * @endif + */ + virtual void onFirstVideoDataReceived(NERtcVideoStreamType type, uid_t uid){ + (void)uid; + (void)type; + } + /** + * @if English + * Occurs when the first audio frame from a remote user is decoded. + * @param uid The ID of a remote user whose audio streams are sent. + * @endif + * @if Chinese + * 已解码远端音频首帧的回调。 + * @param uid 远端用户 ID，指定是哪个用户的音频流。 + * @endif + */ + virtual void onFirstAudioFrameDecoded(NERtcAudioStreamType type, uid_t uid){ + (void)type; + (void)uid; + } + /** + * @if English + * Occurs when the remote video is received and decoded. + *
If the engine receives the first frame of remote video streams, the callback is triggered. + * @param uid The ID of a user whose audio streams are sent. + * @param width The width of video streams (px). + * @param height The height of video streams(px). + * @endif + * @if Chinese + * 已接收到远端视频并完成解码的回调。 + *
引擎收到第一帧远端视频流并解码成功时，触发此调用。 + * @param type 视频频流类型。 + * @param uid 用户 ID，指定是哪个用户的视频流。 + * @param width 视频流宽（px）。 + * @param height 视频流高（px）。 + * @endif + */ + virtual void onFirstVideoFrameDecoded(NERtcVideoStreamType type, uid_t uid, uint32_t width, uint32_t height){ + (void)type; + (void)uid; + (void)width; + (void)height; + } + /** + * @if English + * Occurs when video data are captured. + * @param data The video frame data. + * @param type The type of the video data. + * @param width The width of the video frame. + * @param height The height of the video frame. + * @param count Video plane count. + * @param offset Video offset. + * @param stride Video stride. + * @param rotation The video rotation angle. + * @endif + * @if Chinese + * 采集视频数据回调。 + + * @param data 采集视频数据。 + * @param type 视频类型。 + * @param width 视频宽度。 + * @param height 视频高度。 + * @param count 视频Plane Count。 + * @param offset 视频offset。 + * @param stride 视频stride。 + * @param rotation 视频旋转角度。 + * @endif + */ + void onCaptureVideoFrame( + void* data, + NERtcVideoType type, + uint32_t width, + uint32_t height, + uint32_t count, + uint32_t* offset, + uint32_t* stride, + NERtcVideoRotation rotation){ + (void)data; + (void)type; + (void)width; + (void)height; + (void)count; + (void)offset; + (void)stride; + (void)rotation; + } + /** + * @if English + * Occurs when the playback state of a local music file changes. + *
If you call the startAudioMixing method to play a mixing music file and the playback state changes, the callback is + * triggered. + * - If the playback of the music file ends normally, the state parameter returned in the response contains the corresponding + * status code kNERtcAudioMixingState_tFinished, and the error_code parameter contains kNERtcAudioMixingErrorOK. + * - If an error occurs in the playback, the kNERtcAudioMixingState_tFailed status code is returned, and the error_code + * parameter returned contains the corresponding reason. + * - If the local music file does not exist, the file format is not supported, or the URL of the online music file cannot be + * accessed, the error_code parameter returned contains kNERtcAudioMixingErrorCanNotOpen. + * @param state The playback state of the music file. For more information, see #NERtcAudioMixingState_t. + * @param error_code The error code. For more information, see #NERtcAudioMixingErrorCode_t. + * @endif + * @if Chinese + * 本地用户的音乐文件播放状态改变回调。 + *
调用 startAudioMixing 播放混音音乐文件后，当音乐文件的播放状态发生改变时，会触发该回调。 + * - 如果播放音乐文件正常结束，state 会返回相应的状态码 kNERtcAudioMixingState_tFinished，error_code 返回 + * kNERtcAudioMixingErrorOK。 + * - 如果播放出错，则返回状态码 kNERtcAudioMixingState_tFailed，error_code 返回相应的出错原因。 + * - 如果本地音乐文件不存在、文件格式不支持、无法访问在线音乐文件 URL，error_code都会返回 kNERtcAudioMixingErrorCanNotOpen。 + * @param state 音乐文件播放状态，详见 #NERtcAudioMixingState_t. + * @param error_code 错误码，详见 #NERtcAudioMixingErrorCode_t. + * @endif + */ + virtual void onAudioMixingStateChanged(NERtcAudioMixingState state, NERtcAudioMixingErrorCode error_code){ + (void)state; + (void)error_code; + } + /** + * @if English + * Occurs when the playback position of a local music file changes. + *
If you call the startAudioMixing method to play a mixing music file and the position of the playing operation changes, + * the callback is triggered. + * @param timestamp_ms The position of the music file playing. Unit: milliseconds. + * @endif + * @if Chinese + * 本地用户的音乐文件播放进度回调。 + *
调用 startAudioMixing 播放混音音乐文件后，当音乐文件的播放进度改变时，会触发该回调。 + * @param timestamp_ms 音乐文件播放进度，单位为毫秒 + * @endif + */ + virtual void onAudioMixingTimestampUpdate(uint64_t timestamp_ms){ + (void)timestamp_ms; + } + /** + * @if English + * Occurs when the playback position of a local effect file changes. + *
If you call the playEffect method to play a effect file and the position of the playing operation + * changes, the callback is triggered. + * @param effect_id The effect file id.f + * @param timestamp_ms The position of the music file playing. Unit: milliseconds. + * @endif + * @if Chinese + * 本地用户的指定音效文件播放进度回调。 + * - 调用 \ref nertc::IRtcEngineEx::playEffect "playEffect"播放音效文件后，SDK 会触发该回调，默认每 1s 返回一次。 + * @since V4.6.29 + * @par 使用前提 + * 请在 IRtcEngineEventHandlerEx 接口类中通过 \ref nertc::IRtcEngine::initialize "initialize" 接口设置回调监听。 + * @par 参数说明 + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
**参数名称****类型****描述**
effect_iduint32_t指定音效文件的 ID。每个音效均有唯一的 ID。
timestamp_msuint64_t指定音效文件的当前播放进度。单位为毫秒。
+ * @endif + */ + virtual void onAudioEffectTimestampUpdate(uint32_t effect_id, uint64_t timestamp_ms){ + (void)effect_id; + (void)timestamp_ms; + } + /** + * @if English + * Occurs when the playback of a music file ends. + *
After the audio effect ends the playback, the callback is triggered. + * @param effect_id The ID of the specified audio effect. Each audio effect has a unique ID. + * @endif + * @if Chinese + * 本地音效文件播放已结束回调。 + *
当播放音效结束后，会触发该回调。 + * @param effect_id 指定音效的 ID。每个音效均有唯一的 ID。 + * @endif + */ + virtual void onAudioEffectFinished(uint32_t effect_id){ + (void)effect_id; + } + /** + * @if English + * Occurs when the system prompts current local audio volume. + * - This callback is disabled by default. You can enable the callback by calling the \ref IRtcEngineEx::enableAudioVolumeIndication "enableAudioVolumeIndication" method. + * - After the callback is enabled, if a local user speaks, the SDK triggers the callback based on the time interval specified in the \ref IRtcEngineEx::enableAudioVolumeIndication "enableAudioVolumeIndication" method. + * - If a local user sets a mute by calling \ref IRtcEngineEx::muteLocalAudioStream "muteLocalAudioStream", the SDK sets the value of volume as 0, and calls back to the application layer. + * @param volume The volume of audio mixing. Value range: 0 to 100. + * @param enable_vad Whether human voice is detected. + * @endif + * @if Chinese + * 提示房间内本地用户瞬时音量的回调。 + * - 该回调默认禁用。可以通过 \ref IRtcEngineEx::enableAudioVolumeIndication "enableAudioVolumeIndication" 方法开启。 + * - 开启后，本地用户说话，SDK 会按 \ref IRtcEngineEx::enableAudioVolumeIndication "enableAudioVolumeIndication" 方法中设置的时间间隔触发该回调。 + * - 如果本地用户将自己静音（调用了 \ref IRtcEngineEx::muteLocalAudioStream "muteLocalAudioStream"），SDK 将音量设置为 0 后回调给应用层。 + * @param volume （混音后的）音量，取值范围为 [0,100]。 + * @param enable_vad 是否检测到人声。 + * @endif + */ + virtual void onLocalAudioVolumeIndication(int volume, bool enable_vad){ + (void)volume; + (void)enable_vad; + } + /** + * @if English + * Occurs when the system prompts the active speaker and the audio volume. + * By default, the callback is disabled. You can enable the callback by calling the enableAudioVolumeIndication method. After + * the callback is enabled, if a local user speaks, the SDK triggers the callback based on the time interval specified in the + * enableAudioVolumeIndication method. In the array of speakers returned: + * - If a uid is contained in the array returned in the last response but not in the array returned in the current response. + * The remote user with the uid does not speak by default. + * - If the volume is 0, the user does not speak. + * - If the array is empty, the remote user does not speak. + * @param speakers The array that contains the information about user IDs and volumes is NERtcAudioVolumeInfo. + * @param speaker_number The size of speakers array, which indicates the number of speakers. + * @param total_volume The total volume (after audio mixing). Value range: 0 to 100. + * @endif + * @if Chinese + * 提示房间内谁正在说话及说话者瞬时音量的回调。 + *
该回调默认为关闭状态。可以通过 enableAudioVolumeIndication 方法开启。开启后，无论房间内是否有人说话，SDK 都会按 + * enableAudioVolumeIndication 方法中设置的时间间隔触发该回调。
在返回的 speakers 数组中: + * - 如果有 uid 出现在上次返回的数组中，但不在本次返回的数组中，则默认该 uid 对应的远端用户没有说话。 + * - 如果volume 为 0，表示该用户没有说话。 + * - 如果speakers 数组为空，则表示此时远端没有人说话。 + * @param speakers 每个说话者的用户 ID 和音量信息的数组: NERtcAudioVolumeInfo + * @param speaker_number speakers 数组的大小，即说话者的人数。 + * @param total_volume （混音后的）总音量，取值范围为 [0,100]。 + * @endif + */ + virtual void onRemoteAudioVolumeIndication(const NERtcAudioVolumeInfo* speakers,uint32_t speaker_number,int total_volume){ + (void)speakers; + (void)speaker_number; + (void)total_volume; + } + /** + * @if English + * Notifies to add the result of live stream. + *
The callback asynchronously returns the callback result of \ref IRtcEngineEx::addLiveStreamTask "addLiveStreamTask". + * For information about actual pushing state, see \ref IRtcEngineEventHandlerEx::onLiveStreamState "onLiveStreamState". + * @param task_id The ID of a stream-push task. + * @param url Task ID. + * @param error_code The result. + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 通知添加直播任务结果。 + *
该回调异步返回 \ref IRtcEngineEx::addLiveStreamTask "addLiveStreamTask" 接口的调用结果；实际推流状态参考 \ref + * IRtcEngineEventHandlerEx::onLiveStreamState "onLiveStreamState" + * @param task_id 任务id + * @param url 推流地址 + * @param error_code 结果 + * - 0: 调用成功； + * - 其他: 调用失败。 + * @endif + */ + virtual void onAddLiveStreamTask(const char* task_id, const char* url, int error_code) { + (void)task_id; + (void)url; + (void)error_code; + } + /** + * @if English + * Notifies to Updates the result of live stream. + *
The callback asynchronously returns the callback result of ref IRtcEngineEx::addLiveStreamTask "addLiveStreamTask". For + * information about actual pushing state, see \ref IRtcEngineEventHandlerEx::onLiveStreamState "onLiveStreamState". + * @param task_id The ID of a stream-push task. + * @param url The URL for the streaming task. + * @param error_code The result. + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 通知更新直播任务结果。 + * 该回调异步返回 \ref IRtcEngineEx::updateLiveStreamTask "updateLiveStreamTask" 接口的调用结果；实际推流状态参考 \ref + * IRtcEngineEventHandlerEx::onLiveStreamState "onLiveStreamState" + * @param task_id 任务id + * @param url 推流地址 + * @param error_code 结果 + * - 0: 调用成功； + * - 其他: 调用失败。 + * @endif + */ + virtual void onUpdateLiveStreamTask(const char* task_id, const char* url, int error_code){ + (void)task_id; + (void)url; + (void)error_code; + } + /** + * @if English + * Notifies to delete the result of live stream. + *
The callback asynchronously returns the callback result of ref IRtcEngineEx::addLiveStreamTask "addLiveStreamTask". For + * information about actual pushing state, see \ref IRtcEngineEventHandlerEx::onLiveStreamState "onLiveStreamState". + * @param task_id The ID of a task. + * @param error_code The result. + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 通知删除直播任务结果。 + *
该回调异步返回 \ref IRtcEngineEx::removeLiveStreamTask "removeLiveStreamTask" 接口的调用结果；实际推流状态参考 \ref + * IRtcEngineEventHandlerEx::onLiveStreamState "onLiveStreamState" + * @param task_id 任务id + * @param error_code 结果 + * - 0: 调用成功； + * - 其他: 调用失败。 + * @endif + */ + virtual void onRemoveLiveStreamTask(const char* task_id, int error_code){ + (void)task_id; + (void)error_code; + } + /** + * @if English + * Notifies the status in live stream-pushing. + * @note The callback is valid in a call. + * @param task_id The ID of a task. + * @param url The URL for the streaming task. + * @param state #NERtcLiveStreamStateCode The state of live stream-pushing. + * - 505: Pushing. + * - 506: Pushing fails. + * - 511: Pushing ends. + * @endif + * @if Chinese + * 通知直播推流状态 + * @note 该回调在通话中有效。 + * @param task_id 任务id + * @param url 推流地址 + * @param state #NERtcLiveStreamStateCode, 直播推流状态 + * - 505: 推流中； + * - 506: 推流失败； + * - 511: 推流结束； + * @endif + */ + virtual void onLiveStreamStateChanged(const char* task_id, const char* url, NERtcLiveStreamStateCode state){ + (void)task_id; + (void)url; + (void)state; + } + /** + * @if English + * Occurs when howling is detected. + * When the distance between the sound source and the PA equipment is too close, howling may occur. The NERTC SDK supports the + * howling detection. When a howling signal is detected, the callback is automatically triggered until the howling stops. The + * application layer can prompt the user to mute the microphone or directly mute the microphone when the app receives the + * howling information returned by the callback. + * @note + * Howling detection is used in audio-only scenarios, such as audio chat rooms or online meetings. We recommend that you do + * not use howling detection in entertainment scenes that include background music. + * @param howling Whether a howling occurs. + * - true: Howling occurs. + * - false: Normal state. + * @endif + * @if Chinese + * 检测到啸叫回调。 + *
当声源与扩音设备之间因距离过近时，可能会产生啸叫。NERTC SDK + * 支持啸叫检测，当检测到有啸叫信号产生的时候，自动触发该回调直至啸叫停止。App + * 应用层可以在收到啸叫回调时，提示用户静音麦克风，或直接静音麦克风。 + * @note + * 啸叫检测功能一般用于语音聊天室或在线会议等纯人声环境，不推荐在包含背景音乐的娱乐场景中使用。 + * @param howling 是否出现啸叫 + * - true: 啸叫。 + * - false: 正常。 + * @endif + */ + virtual void onAudioHowling(bool howling){ + (void)howling; + } + /** + * @if English + * Occurs when the content of remote SEI is received. + *
After a remote client successfully sends SEI, the local client receives a message returned by the callback. + * @param[in] uid The ID of the user who sends the SEI. + * @param[in] data The received SEI data. + * @param[in] dataSize The size of received SEI data. + * @endif + * @if Chinese + * 收到远端流的 SEI 内容回调。 + *
当远端成功发送 SEI 后，本端会收到此回调。 + * @param[in] uid 发送该 sei 的用户 id + * @param[in] data 接收到的 sei 数据 + * @param[in] dataSize 接收到 sei 数据的大小 + * @endif + */ + virtual void onRecvSEIMsg(uid_t uid, const uint8_t* data, uint32_t dataSize){ + (void)uid; + (void)data; + (void)dataSize; + } + /** + * @if English + * Returns the audio recording state. + * @param code The status code of the audio recording. For more information, see NERtcAudioRecordingCode. + * @param file_path The path based on which the recording file is stored. + * @endif + * @if Chinese + * 音频录制状态回调。 + * @param code 音频录制状态码。详细信息请参考 NERtcAudioRecordingCode。 + * @param file_path 音频录制文件保存路径。 + * @endif + */ + virtual void onAudioRecording(NERtcAudioRecordingCode code, const char* file_path){ + (void)code; + (void)file_path; + } + /** + * @if English + * Occurs when the state of the media stream is relayed. + * @since V4.3.0 + * @param state The state of the media stream. + * @param channel_name The name of the destination room where the media streams are relayed. + * @endif + * @if Chinese + * 跨房间媒体流转发状态发生改变回调。 + * @since V4.3.0 + * @param state 当前跨房间媒体流转发状态。详细信息请参考 #NERtcChannelMediaRelayState + * @param channel_name 媒体流转发的目标房间名。 + * @endif + */ + virtual void onMediaRelayStateChanged(NERtcChannelMediaRelayState state, const char* channel_name){ + (void)state; + (void)channel_name; + } + /** + * @if English + * Occurs when events related to media stream relay are triggered. + * @since V4.3.0 + * @param event The media stream relay event. + * @param channel_name The name of the destination room where the media streams are relayed. + * @param error Specific error codes. + * @endif + * @if Chinese + * 媒体流相关转发事件回调。 + * @since V4.3.0 + * @param event 当前媒体流转发事件。详细信息请参考 #NERtcChannelMediaRelayEvent 。 + * @param channel_name 转发的目标房间名。 + * @param error 相关错误码。详细信息请参考 #NERtcErrorCode_t 。 + * @endif + */ + virtual void onMediaRelayEvent(NERtcChannelMediaRelayEvent event,const char* channel_name, NERtcErrorCode error){ + (void)event; + (void)channel_name; + (void)error; + } + /** + * @if English + * Occurs when the published local media stream falls back to an audio-only stream due to poor network conditions or switches + * back to audio and video stream after the network conditions improve.
If you call setLocalPublishFallbackOption and set + * option to #kNERtcStreamFallbackAudioOnly, this callback is triggered when the locally published stream falls back to + * audio-only mode due to poor uplink network conditions, or when the audio stream switches back to the audio and video stream + * after the uplink network conditions improve. + * @since V4.3.0 + * @param is_fallback The locally published stream falls back to audio-only mode or switches back to audio and video stream. + * - true: The published stream from a local client falls back to audio-only mode due to poor uplink network conditions. + * - false: The audio stream switches back to the audio and video stream after the upstream network condition improves. + * @param type The type of the video stream, such as mainstream and substream. + * @endif + * @if Chinese + * 本地发布流已回退为音频流、或已恢复为音视频流回调。 + *
如果您调用了设置本地推流回退选项 setLocalPublishFallbackOption 接口，并将 option 设置为 #kNERtcStreamFallbackAudioOnly + * 后，当上行网络环境不理想、本地发布的媒体流回退为音频流时，或当上行网络改善、媒体流恢复为音视频流时，会触发该回调。 + * @since V4.3.0 + * @param is_fallback 本地发布流已回退或已恢复。 + * - true： 由于网络环境不理想，发布的媒体流已回退为音频流。 + * - false：由于网络环境改善，从音频流恢复为音视频流。 + * @param type 对应的视频流类型，即主流或辅流。 + * @endif + */ + virtual void onPublishFallbackToAudioOnly(bool is_fallback, NERtcVideoStreamType type){ + (void)is_fallback; + (void)type; + } + /** + * @if English + * Occurs when the subscribed remote media stream falls back to an audio-only stream due to poor network conditions or + * switches back to the audio and video stream after the network condition improves.
If you call + * setLocalPublishFallbackOption and set option to #kNERtcStreamFallbackAudioOnly, this callback is triggered when the locally + * published stream falls back to audio-only mode due to poor uplink network conditions, or when the audio stream switches + * back to the audio and video stream after the uplink network condition improves. + * @since V4.3.0 + * @param uid The ID of a remote user. + * @param is_fallback The subscribed remote media stream falls back to audio-only mode or switches back to the audio and + * video stream. + * - true: The subscribed remote media stream falls back to audio-only mode due to poor downstream network conditions. + * - false: The subscribed remote media stream switches back to the audio and video stream after the downstream network + * condition improves. + * @param type The type of the video stream, such as mainstream and substream. + * @endif + * @if Chinese + * 订阅的远端流已回退为音频流、或已恢复为音视频流回调。 + *
如果你调用了设置远端订阅流回退选项 setRemoteSubscribeFallbackOption 接口并将 option 设置 #kNERtcStreamFallbackAudioOnly + * 后，当下行网络环境不理想、仅接收远端音频流时，或当下行网络改善、恢复订阅音视频流时，会触发该回调。 + * @since V4.3.0 + * @param uid 远端用户的 ID。 + * @param is_fallback 远端订阅流已回退或恢复： + * - true： 由于网络环境不理想，订阅的远端流已回退为音频流。 + * - false：由于网络环境改善，订阅的远端流从音频流恢复为音视频流。 + * @param type 对应的视频流类型，即主流或辅流。 + * @endif + */ + virtual void onSubscribeFallbackToAudioOnly(uid_t uid, bool is_fallback, NERtcVideoStreamType type){ + (void)uid; + (void)is_fallback; + (void)type; + } + /** + * @if English + * Reports the last mile network quality of the local user once every two seconds before the user joins the channel. + *
After the application calls the startLastmileProbeTest method, this callback reports once every five seconds the + * uplink and downlink last mile network conditions of the local user before the user joins the channel. + * @since V4.5.0 + * @param quality The last mile network quality. + * @endif + * @if Chinese + * 通话前网络上下行 last mile 质量状态回调。 + *
该回调描述本地用户在加入房间前的 last mile + * 网络探测的结果，以打分形式描述上下行网络质量的主观体验，您可以通过该回调预估本地用户在音视频通话中的网络体验。
在调用 + * startLastmileProbeTest 之后，SDK 会在约 5 秒内返回该回调。 + * @since V4.5.0 + * @param quality 网络上下行质量，基于上下行网络的丢包率和抖动计算，探测结果主要反映上行网络的状态。 + * @endif + */ + virtual void onLastmileQuality(NERtcNetworkQualityType quality){ + (void)quality; + } + /** + * @if English + * Reports the last-mile network probe result. + *
This callback describes a detailed last-mile network detection report of a local user before joining a channel. The + * report provides objective data about the upstream and downstream network quality, including network jitter and packet loss + * rate. You can use the report to objectively predict the network status of local users during an audio and video call. + *
The SDK triggers this callback within 30 seconds after the app calls the startLastmileProbeTest method. + * @since V4.5.0 + * @param result The uplink and downlink last-mile network probe test result. + * @endif + * @if Chinese + * 通话前网络上下行 Last mile 质量探测报告回调。 + *
该回调描述本地用户在加入房间前的 last mile + * 网络探测详细报告，报告中通过客观数据反馈上下行网络质量，包括网络抖动、丢包率等数据。您可以通过该回调客观预测本地用户在音视频通话中的网络状态。 + *
在调用 startLastmileProbeTest 之后，SDK 会在约 30 秒内返回该回调。 + * @since V4.5.0 + * @param result 上下行 Last mile 质量探测结果。 + * @endif + */ + virtual void onLastmileProbeResult(const NERtcLastmileProbeResult& result){ + (void)result; + } + /** + * @if English + * Audio/Video Callback when banned by server. + * @since v4.6.0 + * @param isAudioBannedByServer indicates whether to ban the audio. + * - true: banned + * - false unbanned + * @param isVideoBannedByServer indicates whether to ban the video. + * - true: banned + * - false unbanned + * @endif + * @if Chinese + * 服务端禁言音视频权限变化回调。 + * @since v4.6.0 + * @param is_audio_banned 是否禁用音频。 + * - true：禁用音频。 + * - false：取消禁用音频。 + * @param is_video_banned 是否禁用视频。 + * - true：禁用视频。 + * - false：取消禁用视频。 + * @endif + */ + virtual void onMediaRightChange(bool is_audio_banned, bool is_video_banned){ + (void)is_audio_banned; + (void)is_video_banned; + } + /** + * @if English + * Gets notified if the audio driver plug-in is installed (only for Mac) + *
You can call {@link checkNECastAudioDriver} to install the audio driver plug-in and capture and play audio data in the Mac system + * @param result indicates the result of audio driver plug-in installation. For more information, see {@link NERtcInstallCastAudioDriverResult}. + * @endif + * @if Chinese + * 收到检测安装声卡的内容回调（仅适用于 Mac 系统）。 + *
在 Mac 系统上，您可以通过调用 checkNECastAudioDriver 为当前系统安装一个音频驱动，并让 SDK 通过该音频驱动捕获当前 Mac 系统播放出的声音。 + * @param result 安装虚拟声卡的结果。详细信息请参考 {@link NERtcInstallCastAudioDriverResult}。 + * @endif + */ + virtual void onCheckNECastAudioDriverResult(NERtcInstallCastAudioDriverResult result){ + (void)result; + } + + /** + * @if English + * Reports whether the virtual background is successfully enabled. (beta feature) + * @since v4.6.0 + * After you call \ref IRtcEngine::enableVirtualBackground "enableVirtualBackground", the SDK triggers this callback + * to report whether the virtual background is successfully enabled. + * @note If the background image customized in the virtual background is in PNG or JPG format, the triggering of this + * callback is delayed until the image is read. + * @param enabled Whether the virtual background is successfully enabled: + * - true: The virtual background is successfully enabled. + * - false: The virtual background is not successfully enabled. + * @param reason The reason why the virtual background is not successfully enabled or the message that confirms + * success. See #NERtcVirtualBackgroundSourceStateReason. + * @endif + * @if Chinese + * 通知虚拟背景功能是否成功启用的回调。 + *
调用 \ref IRtcEngineEx::enableVirtualBackground "enableVirtualBackground" 方法后，SDK 返回此回调通知虚拟背景功能是否成功启用。 + * @since V4.6.0 + * @note 如果您设置虚拟背景为 PNG 或 JPG 格式的自定义图像，此回调会等到图像被完全读取后才会返回，因此会有一段时间的延迟。 + * @param enabled 是否成功启用虚拟背景。 + * - true：成功启用。 + * - false：未成功启用。 + * @param reason 虚拟背景功能未成功启用的原因或成功启用虚拟背景功能的通知。详细信息请参考 {@link NERtcVirtualBackgroundSourceStateReason}。 + * @endif + */ + virtual void onVirtualBackgroundSourceEnabled(bool enabled, NERtcVirtualBackgroundSourceStateReason reason){ + (void)enabled; + (void)reason; + } + + /** + * @if English + * Occurs when the local video watermark takes affect. + *
If you enables the local video watermark by calling \ref nertc::IRtcEngineEx::setLocalVideoWatermarkConfigs "setLocalVideoWatermarkConfigs", the SDK will trigger this callback. + * @since V4.6.10 + * @param videoStreamType Type of video stream, main stream or substream. For more information, see {@link video.NERtcVideoStreamType}. + * @param state Watermark status. For more information, see {@link NERtcConstants.NERtcLocalVideoWatermarkState}. + * @endif + * @if Chinese + * 本地视频水印生效结果回调。 + *
调用 \ref nertc::IRtcEngineEx::setLocalVideoWatermarkConfigs "setLocalVideoWatermarkConfigs" 接口启用本地视频水印后，SDK 会触发此回调。 + * @since V4.6.10 + * @param type 对应的视频流类型，即主流或辅流。详细信息请参考 {@link NERtcVideoStreamType}。 + * @param state 水印状态。详细信息请参考 {@link NERtcLocalVideoWatermarkState}。 + * @endif + */ + virtual void onLocalVideoWatermarkState(NERtcVideoStreamType type, NERtcLocalVideoWatermarkState state){ + (void)type; + (void)state; + } + + /** + * @if English + * The right key is about to expire. + * Because the PermissionKey has a certain time effect, if the PermissionKey is about to expire during a call, the SDK + * will trigger the callback in advance to remind the App to update the Token. + * When receiving the callback, the user needs to regenerate a new PermissionKey on the server, + * and then call ref IRtcEngineEx:: updatePermissionKey "updatePermissionKey" to transfer the newly generated PermissionKey to the SDK. + * @param key Permission key value. + * @param error Relevant error code. Please refer to # NERtcErrorCode for details. + * @param timeout Timeout, in seconds, valid when successful. + * @endif + * @if Chinese + * 权限密钥即将过期事件回调。 + * - 由于 PermissionKey 具有一定的时效，在通话过程中如果 PermissionKey 即将失效，SDK 会提前 30 秒触发该回调，提醒用户更新 PermissionKey。 + * @since V4.6.29 + * @par 使用前提 + * 请在 IRtcEngineEventHandlerEx 接口类中通过 \ref IRtcEngine::initialize "initialize" 接口设置回调监听。 + * @par 相关接口 + * 在收到此回调后可以调用 \ref IRtcEngineEx::updatePermissionKey "updatePermissionKey" 方法更新权限密钥。 + * @endif + */ + virtual void onPermissionKeyWillExpire(){} + + /** + * @if English + * Update authority key event callback. + * @param key Permission key value. + * @param error Relevant error code. Please refer to # NERtcErrorCode for details. + * @param timeout Timeout, in seconds, valid when successful. + * @endif + * @if Chinese + * 更新权限密钥事件回调。 + * - 调用 \ref IRtcEngineEx::updatePermissionKey "updatePermissionKey" 方法主动更新权限密钥后，SDK 会触发该回调，返回权限密钥更新的结果。 + * @since V4.6.29 + * @par 使用前提 + * 请在 IRtcEngineEventHandlerEx 接口类中通过 \ref IRtcEngine::initialize "initialize" 接口设置回调监听。 + * @par 参数说明 + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
**参数名称****类型****描述**
keyconst char*新的权限密钥。
error \ref nertc::NERtcErrorCode "NERtcErrorCode" 错误码。
  • kNERtcErrChannelPermissionKeyError（30901）：权限密钥错误。
  • kNERtcErrChannelPermissionKeyTimeout（30902）：权限密钥超时。
timeoutint更新后的权限密钥剩余有效时间。单位为秒。
+ * @endif + */ + virtual void onUpdatePermissionKey(const char* key, NERtcErrorCode error, int timeout){ + (void)key; + (void)error; + (void)timeout; + } + + /** + * @if English + * Occurs when a remote user send data by data channel. + * @param uid The ID of a remote user. + * @param data The received data channel data. + * @param size The size of received data channel data. + * @endif + * @if Chinese + * 远端用户通过数据通道发送数据的回调。 + * @param uid 远端用户ID。 + * @param source_id 远端source ID。 + * @param data 数据。 + * @param size 接收数据长度。 + * @endif + */ + virtual void onUserDataReceiveMessage(uid_t uid, const char* source_id, void* data, uint64_t size){ + (void)uid; + (void)data; + (void)size; + } + + /** + * @if English + * Occurs when a remote user enables data channel. + * @param uid The ID of a remote user. + * @since V5.0.0 + * @endif + * @if Chinese + * 远端用户开启数据通道的回调。 + * @param uid 远端用户ID。 + * @since V5.0.0 + * @endif + */ + virtual void onUserDataStart(uid_t uid){ + (void)uid; + } + + /** + * @if English + * Occurs when a remote user disables data channel. + * @param uid The ID of a remote user. + * @endif + * @if Chinese + * 远端用户停用数据通道的回调。 + * @param uid 远端用户ID。 + * @endif + */ + virtual void onUserDataStop(uid_t uid){ + (void)uid; + } + + /** + * @if English + * Occurs when a Remote user data channel status changed. + * @param uid The ID of a remote user. + * @param source_id The source id. + * @endif + * @if Chinese + * 远端用户数据通道状态变更回调。 + * @param uid 远端用户ID。 + * @param source_id 远端用户source ID。 + * @endif + */ + virtual void onUserDataStateChanged(uid_t uid, const char* source_id){ + (void)uid; + (void)source_id; + } + + /** + * @if English + * Occurs when a Remote user data channel buffer amount changed. + * @param uid The ID of a remote user. + * @param source_id The source id. + * @param previousAmount The amount before changed. + * @endif + * @if Chinese + * 远端用户数据通道buffer变更回调。 + * @param uid 远端用户ID。 + * @param source_id 远端用户source ID。 + * @param previousAmount 变更前大小。 + * @endif + */ + virtual void onUserDataBufferedAmountChanged(uid_t uid, const char* source_id, uint64_t previous_amount){ + (void)uid; + (void)source_id; + (void)previous_amount; + } +}; +} // namespace nertc diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/INertcEngineEx.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/INertcEngineEx.h new file mode 100644 index 0000000..9a21258 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/INertcEngineEx.h @@ -0,0 +1,795 @@ +/** @file NertcEngineEx.h + * @brief The interface header file of expansion NERTC UE SDK. + * All parameter descriptions of the NERTC UE SDK. All string-related parameters (char *) are encoded in UTF-8. + * @copyright (c) 2015-2022, NetEase Inc. All rights reserved. + */ + +#pragma once +#include "NertcBase.h" +#include "INertcEngine.h" +#include "INertcMediaStatsObserver.h" +#include + +namespace nertc { + +class IRtcEngineEx:public IRtcEngine { +public: + virtual ~IRtcEngineEx(){} +/** + * @if English + * Gets the current connection status. + * @return Returns the current network status. #NERtcConnectionStateType. + * @endif + * @if Chinese + * 获取当前网络状态。 + * @return 当前网络状态。#NERtcConnectionStateType. + * @endif + */ +virtual NERtcConnectionStateType getConnectionState() = 0; +/** + * @if English + * Enables or disabling publishing the local audio stream. The method is used to enable or disable publishing the local audio + * stream. + * @note + * - This method does not change the state of the audio-recording device because the audio-recording devices are not disabled. + * - The mute state is reset to unmuted after the call ends. + * @param[in] mute Mute or Unmute. + * - true: Mutes the local audio stream. + * - false: Unmutes the local audio stream (Default). + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 开关本地音频发送。该方法用于允许或禁止向网络发送本地音频流。 + * @note + * - 该方法不影响录音状态，因为并没有禁用录音设备。 + * - 静音状态会在通话结束后被重置为非静音 + * @param[in] type 音频流类型: + * @param[in] mute 静音/取消静音: + * - true: 静音本地音频 + * - false: 取消静音本地音频（默认） + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +virtual int muteLocalAudioStream(NERtcAudioStreamType type, bool mute) = 0; +/** + * @if English + * Sets the audio encoding profile. + * @note + * - Sets the method before calling the \ref IRtcEngine::joinChannel "joinChannel". Otherwise, the setting is invalid after + * \ref IRtcEngine::joinChannel "joinChannel". + * - In music scenarios, we recommend you to set the profile as kNERtcAudioProfileHighQuality. + * @param[in] profile Sets the sample rate, bitrate, encoding mode, and the number of channels. #NERtcAudioProfileType. + * @param[in] scenario Sets the type of an audio application scenario. #NERtcAudioScenarioType. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置音频编码属性。 + * @note + * - 该方法需要在 \ref IRtcEngine::joinChannel "joinChannel" 之前设置好， \ref IRtcEngine::joinChannel "joinChannel" + * 之后设置不生效。 + * - 音乐场景下，建议将 profile 设置为 kNERtcAudioProfileHighQuality。 + * @param[in] profile 设置采样率，码率，编码模式和声道数: #NERtcAudioProfileType 。 + * @param[in] scenario 设置音频应用场景: #NERtcAudioScenarioType 。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +virtual int setAudioProfile(NERtcAudioProfileType profile, NERtcAudioScenarioType scenario) = 0; + +/** + * @if English + * Sets the voice changer effect for the SDK-preset voice. + * The method can add multiple preset audio effects to original human voices and change audio profiles. + * @note + * - You can call this method either before or after joining a room. By default, the audio effect is disabled after the call + * ends. + * - The method conflicts with setLocalVoicePitch. After you call this method, the voice pitch is reset to the default + * value 1.0. + * @param[in] type The preset voice changer effect. By default, the audio effect is disabled. For more information, see + * nertc::NERtcVoiceChangerType. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置 SDK 预设的人声的变声音效。 + * 设置变声音效可以将人声原因调整为多种特殊效果，改变声音特性。 + * @note + * - 此方法在加入房间前后都能调用，通话结束后重置为默认关闭状态。 + * - 此方法和 setLocalVoicePitch 互斥，调用此方法后，本地语音语调会恢复为默认值 1.0。 + * @param[in] type 预设的变声音效。默认关闭变声音效。详细信息请参考 nertc::NERtcVoiceChangerType 。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +virtual int setAudioEffectPreset(NERtcVoiceChangerType type) = 0; + +/** + * @if English + * Sets an SDK-preset voice beautifier effect. + * The method can set a SDK-preset voice beautifier effect for a local user who sends an audio stream. + * @note By default, the method is reset as disabled after the call ends. + * @param[in] type The present voice beautifier effect. By default, the voice beautifier effect is disabled. For more + * information, see nertc::NERtcVoiceBeautifierType. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置 SDK 预设的美声效果。 + * 调用该方法可以为本地发流用户设置 SDK 预设的人声美声效果。 + * @note 通话结束后重置为默认关闭 + * @param[in] type 预设的美声效果模式。默认关闭美声效果。详细信息请参考 nertc::NERtcVoiceBeautifierType 。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +virtual int setVoiceBeautifierPreset(NERtcVoiceBeautifierType type) = 0; + +/** + * @if English + * Sets the voice pitch of a local voice. + * The method changes the voice pitch of the local speaker. + * @note + * - After the call ends, the setting changes back to the default value 1.0. + * - The method conflicts with setAudioEffectPreset. After you call this method, the preset voice beautifier effect will be + * removed. + * @param[in] pitch The voice frequency. Valid values: 0.5 to 2.0. Smaller values have lower pitches. The default + * value is 1, which That the pitch is not changed. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置本地语音音调。 + * 该方法改变本地说话人声音的音调。 + * @note + * - 通话结束后该设置会重置，默认为 1.0。 + * - 此方法与 setAudioEffectPreset 互斥，调用此方法后，已设置的变声效果会被取消。 + * @param[in] pitch 语音频率。可以在 [0.5, 2.0] 范围内设置。取值越小，则音调越低。默认值为 1.0，表示不需要修改音调。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +virtual int setLocalVoicePitch(double pitch) = 0; + +/** + * @if English + * Sets the local voice equalization effect. You can customize the center frequencies of the local voice effects. + * @note You can call this method either before or after joining a room. By default, the audio effect is disabled after the + * call ends. + * @param[in] band_frequency Sets the band frequency. Value range: 0 to 9. Those numbers represent the respective 10-band + * center frequencies of the voice effects, including 31, 62, 125, 250, 500, 1k, 2k, 4k, 8k, and 16k Hz. + * @param[in] band_gain Sets the gain of each band (dB). Value range: -15 to 15. The default value is 0. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置本地语音音效均衡，即自定义设置本地人声均衡波段的中心频率。 + * @note 该方法在加入房间前后都能调用，通话结束后重置为默认关闭状态。 + * @param[in] band_frequency 频谱子带索引，取值范围是 [0-9]，分别代表 10 个频带，对应的中心频率是 + * [31，62，125，250，500，1k，2k，4k，8k，16k] Hz。 + * @param[in] band_gain 每个 band 的增益，单位是 dB，每一个值的范围是 [-15，15]，默认值为 0。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +virtual int setLocalVoiceEqualization(NERtcVoiceEqualizationBand band_frequency, int band_gain) = 0; + +/** + * @if English + * Unsubscribes from or subscribes to audio streams from specified remote users. + *
After a user joins a channel, audio streams from all remote users are subscribed by default. You can call this method + * to unsubscribe from or subscribe to audio streams from all remote users. + * @note When the kNERtcKeyAutoSubscribeAudio is enabled by default, users cannot manually modify the state of audio + * subscription. + * @param[in] uid The user ID. + * @param[in] subscribe + * - true: Subscribes to specified audio streams (default). + * - false: Unsubscribes from specified audio streams. + * @return + * - 0: Success. + * - 30005: State exception that is caused by the invalid interface if users enable the automatic subscription. + * - Other values: Failure. + * @endif + * @if Chinese + * 取消或恢复订阅指定远端用户音频流。 + *
加入房间时，默认订阅所有远端用户的音频流，您可以通过此方法取消或恢复订阅指定远端用户的音频流。 + * @note 当kNERtcKeyAutoSubscribeAudio默认打开时，用户不能手动修改音频订阅状态 + * @param[in] stream_type 音频流类型: kNERtcAudioStreamTypeMain主流音频，kNERtcAudioStreamTypeSub辅流音频。 + * @param[in] uid 指定用户的 ID。 + * @param[in] subscribe 是否订阅远端用户音频流。 + * - true: 订阅指定音频流（默认）。 + * - false: 取消订阅指定音频流。 + * @return + * - 0: 方法调用成功。 + * - 30005: 状态异常，可能是自动订阅打开，导致该接口无效。 + * - 其他: 方法调用失败。 + * @endif + */ +virtual int subscribeRemoteAudioStream(NERtcAudioStreamType stream_type, uid_t uid, bool subscribe) = 0; + +/** + * @if English + * Unsubscribes or subscribes to audio streams from all remote users. + * @note + * - Call this method before or after joining the channel. + * @since V4.5.0 + * @param subscribe Whether to unsubscribe audio streams from all remote users. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 取消或恢复订阅所有远端用户的音频主流。 + *
加入房间时，默认订阅所有远端用户的音频主流，即 \ref nertc::IRtcEngineEx::setParameters "setParameters" 方法的 + * KEY_AUTO_SUBSCRIBE_AUDIO 参数默认设置为 true；只有当该参数的设置为 false 时，此接口的调用才会生效。 + * @since V4.5.0 + * @par 调用时机 + * 请在引擎初始化之后调用此接口，且该方法在加入房间前后均可调用。 + * @par 业务场景 + * 适用于重要会议需要一键全体静音的场景。 + * @note + * - 设置该方法的 subscribe 参数为 true 后，对后续加入房间的用户同样生效。 + * - 在开启自动订阅（默认）时，设置该方法的 subscribe 参数为 false 可以实现取消订阅所有远端用户的音频流，但此时无法再调用 \ref + * nertc::IRtcEngineEx::subscribeRemoteAudioStream "subscribeRemoteAudioStream" 方法单独订阅指定远端用户的音频流。 + * @par 参数说明 + * + * + * + * + * + * + * + * + * + * + * + *
**参数名称****类型****描述**
subscribebool是否订阅所有用户的音频主流：
  • true：订阅音频主流。
  • false：取消订阅音频主流。
+ * @par 示例代码 + * @code + * //订阅所有远端用户的音频主流 + * rtc_engine_->subscribeAllRemoteAudioStream(true); + * //取消订阅所有远端用户的音频主流 + * rtc_engine_->subscribeAllRemoteAudioStream(false); + * @endcode + * @return + * - 0（kNERtcNoError）：方法调用成功。 + * - 其他：方法调用失败。 + * - 30005（kNERtcErrInvalidState)：引擎未初始化。 + * - 30026：ASL 选路功能启用失败。 + * - 30400：Transceiver 未找到。 + * @endif + */ +virtual int subscribeAllRemoteAudioStream(bool subscribe) = 0; + +/** + * @if Chinese + * 你可以调用该方法指定音频流被谁订阅。 + * @note + * - 此接口需要在加入房间成功后调用。 + * - 对于调用接口时不在房间的 uid 不生效。 + * @since V5.4.101 + * @param[in] uid_array 只订阅此 用户uid列表 的音频。 + * @note 此列表为全量列表。如果列表为空或 null，取消订阅白名单。 + * @param[in] size uid_array 的数组长度。 + * @return + * - 0：方法调用成功。 + * - 其他：方法调用失败。 + * @endif + */ +virtual int setPublishAudioAllowList(uid_t* uid_array, uint32_t size) = 0; + +/** + * @if Chinese + * 你可以调用该方法指定只订阅的音频流。 + * @note + * - 此接口需要在加入房间成功后调用。 + * - 对于调用接口时不在房间的 uid 不生效。 + * @since V5.4.101 + * @param[in] uid_array 只订阅此 用户uid列表 的音频。 + * @note 此列表为全量列表。如果列表为空或 null，取消订阅白名单。 + * @param[in] size uid_array 的数组长度。 + * @return + * - 0：方法调用成功。 + * - 其他：方法调用失败。 + * @endif + */ +virtual int setSubscribeAudioAllowList(uid_t* uid_array, uint32_t size) = 0; + +/** + * @if Chinese + * 你可以调用该方法指定不订阅的音频流。 + * @note + * - 此接口需要在加入房间成功后调用。 + * - 对于调用接口时不在房间的 uid 不生效。 + * @since V5.4.101 + * @param[in] uid_array 不订阅此 用户uid列表 的音频。 + * @note 此列表为全量列表。如果列表为空或 null，取消订阅黑名单。 + * @param[in] size uid_array 的数组长度。 + * @return + * - 0：方法调用成功。 + * - 其他：方法调用失败。 + * @endif + */ +virtual int setSubscribeAudioBlockList(uid_t* uid_array, uint32_t size) = 0; + +/** + * @if English + * Sets permissions of the SDK over Audio Session. + *
This method is only applicable to the iOS platform. + *
This method controls the permissions of the SDK over Audio Session. By default, the SDK and the app have control over the + * Audio Session. However, in some cases, the app wants to restrict the SDK's permissions over Audio Session and uses other + * applications or third-party components to control Audio Session. The app can adjust the permissions of the SDK by calling + * this method.
You can call this method only before you join the room. + * @note If you call this method to restrict the SDK's permissions over Audio Session, the SDK cannot set Audio Session. You + * need to manage Audio Session or use a third-party component to operate Audio Session. + * @param restriction The restriction applied to the SDK for Audio Session. For more information, see {@link + * NERtcAudioSessionOperationRestriction}. + * @return The value returned. A value of 0 indicates that the operation is successful. + * @endif + * @if Chinese + * 设置 SDK 对 Audio Session 的控制权限。 + *
该方法仅适用于 iOS 平台。 + *
该方法限制 SDK 对 Audio Session 的操作权限。在默认情况下，SDK 和 App 对 Audio Session 都有控制权，但某些场景下，App + * 会希望限制 SDK 对 Audio Session 的控制权限，而使用其他应用或第三方组件对 Audio Session 进行操控。调用该方法可以实现该功能。 + *
该接口只能在入会之前调用。 + * @note 一旦调用该方法限制了 SDK 对 Audio Session 的控制权限， SDK 将无法对 Audio Session + * 进行相关设置，而需要用户自己或第三方组件进行维护。 + * @param restriction SDK 对 Audio Session 的控制权限。详细信息请参考 {@link NERtcAudioSessionOperationRestriction}。 + * @return 操作返回值，成功则返回 0 + * @endif + */ +virtual int setAudioSessionOperationRestriction(NERtcAudioSessionOperationRestriction restriction) = 0; + +/** + * @if English + * Sets the audio focus mode. + *
This method is only applicable to the Android platform. + * @return {@code 0} A value of 0 returned indicates that the method call is successful. Otherwise, the method call fails. + * @endif + * @if Chinese + * 设置音频焦点模式。 + *
该方法仅适用于 Android 平台。 + * @return {@code 0} 方法调用成功，其他失败。 + * @endif + */ +virtual int setAudioFocusMode(NERtcAudioFocusMode focus_mode) = 0; +/** + * @if English + * Mutes or unmutes the audio playback device. + * @param muted The option whether to mute the playback device. By default, the setting is unmuted. + * @return The value returned. A value of 0 indicates that the operation is successful. + * @endif + * @if Chinese + * 设置是否静音音频播放设备。 + * @param muted 是否静音播放设备。默认为不静音状态。 + * @return 操作返回值，成功则返回 0 + * @endif + */ +virtual int setPlayoutDeviceMute(bool muted) = 0; + +/** + * @if English + * Gets the mute status of the audio playback device. + * @param muted The option whether the device is muted. + * @return The value returned. A value of 0 indicates that the operation is successful. + * @endif + * @if Chinese + * 获取音频播放设备的静音状态。 + * @param muted 是否静音。 + * @return 操作返回值，成功则返回 0 + * @endif + */ +virtual int getPlayoutDeviceMute(bool* muted) = 0; + +/** + * @if English + * Sets parameters for audio and video calls. You can configure the SDK through JSON to provide features like technology + * review and special customization. Publicizes JSON options in a standardized way. + * @param[in] parameters Related parameters for audio and video calls whose format is the JSON string. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置音视频通话的相关参数。通过 JSON 配置 SDK 提供技术预览或特别定制功能。以标准化方式公开 JSON 选项。 + * @param[in] parameters 音视频通话的相关参数。 JSON 字符串形式。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +virtual int setParameters(const char* parameters) = 0; + +/** + * @if English + * Registers the audio observer object. + *
The method is used to set audio capture or play PCM data callbacks. You can use the method to process audios. You need + * to register callbacks with this method when engine needs to trigger callbacks of \ref + * nertc::INERtcAudioFrameObserver::onAudioFrameDidRecord "onAudioFrameDidRecord" or \ref + * nertc::INERtcAudioFrameObserver::onAudioFrameWillPlayback "onAudioFrameWillPlayback". + * @param observer The object instance. If you pass in NULL, you cancel the registration and clear the settings of + * NERtcAudioFrameRequestFormat. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 注册语音观测器对象。 + *
该方法用于设置音频采集和播放PCM回调，可用于声音处理等操作。当需要引擎给出 \ref + * nertc::INERtcAudioFrameObserver::onAudioFrameDidRecord "onAudioFrameDidRecord" 或 \ref + * nertc::INERtcAudioFrameObserver::onAudioFrameWillPlayback "onAudioFrameWillPlayback" 回调时，需要使用该方法注册回调。 + * @param observer 接口对象实例。如果传入 NULL，则取消注册，同时会清理NERtcAudioFrameRequestFormat相关设置。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +virtual int setAudioFrameObserver(INERtcAudioFrameObserver* observer) = 0; +/** + * @if English + * Starts recording an audio dump file. Audio dump files can be used to analyze audio issues. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 开始记录音频 dump。 音频 dump 可用于分析音频问题。 + * @param type 音频dump类型 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +virtual int startAudioDump(NERtcAudioDumpType type) = 0; +/** + * @if English + * Finishes recording an audio dump file. + * @return + - 0: Success. + - Other values: Failure. + * @endif + * @if Chinese + * 结束音频dump。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +virtual int stopAudioDump() = 0; + +/** + 设置音频播放扬声器模式（仅iOS/Android有效） + + @param enable 是否使用扬声器模式 + @return 操作返回值，成功则返回 0 + */ +virtual int setLoudspeakerMode( bool enable) = 0; + +/** + 获取目前是否使用扬声器模式（仅iOS/Android有效） + + @param enabled 是否正在使用扬声器模式 + @return + - 0: 方法调用成功； + - 其他: 方法调用失败。 + */ +virtual int getLoudspeakerMode(bool* enabled) = 0; + +/** + * @if English + * Registers a stats observer. + * @param[in] observer The stats observer. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 注册统计信息观测器。 + * @param[in] observer 统计信息观测器 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +virtual int setStatsObserver(IRtcMediaStatsObserver* observer) = 0; + +/** + * @if English + * Enables volume indication for the speaker. + *
The method allows the SDK to report to the app the information about the volume of the user that pushes local streams + * and the remote user (up to three users) that has the highest instantaneous volume. The information about the current + * speaker and the volume is reported.
If this method is enabled, when a user joins a room and pushes streams, the SDK + * triggers \ref IRtcEngineEventHandlerEx::onRemoteAudioVolumeIndication "onRemoteAudioVolumeIndication" based on the preset + * time intervals. + * @param enable Whether to prompt the speaker volume. + * @param interval The time interval at which volume prompt is displayed. Unit: milliseconds. The value must be the + * multiples of 100 milliseconds. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 启用说话者音量提示。 + *
该方法允许 SDK 定期向 App 反馈本地发流用户和瞬时音量最高的远端用户（最多 3 + * 位）的音量相关信息，即当前谁在说话以及说话者的音量。
启用该方法后，只要房间内有发流用户，无论是否有人说话，SDK + * 都会在加入房间后根据预设的时间间隔触发\ref IRtcEngineEventHandlerEx::onRemoteAudioVolumeIndication + * "onRemoteAudioVolumeIndication"回调。 + * @param enable 是否启用说话者音量提示。 + * @param interval 指定音量提示的时间间隔，单位为毫秒。必须设置为 100 毫秒的整数倍值。 + * @param enable_vad 是否启用本地采集人声监测。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +virtual int enableAudioVolumeIndication(bool enable, uint64_t interval, bool enable_vad) = 0; + +/** + * @if English + * Query the SDK version number. + * - You can call this method before or after you join a room. + * @param[out] build The compilation number. + * @return The version of the current SDK, whose format is string such as 1.0.0. + * @endif + * @if Chinese + * 查询 SDK 版本号。 + * 该方法在加入房间前后都能调用。 + * @return 当前的 SDK 版本号，格式为字符串，如1.0.0. + * @endif + */ +virtual const char* getVersion(int* build) = 0; +/** + * @if English + * Check the error description of specified error codes. + * @note The method is currently invalid. Returns the value of empty only. Please check returned error codes and specific + * error descriptions in the \ref IRtcEngineEventHandler::onError "onError" . + * @param[in] error_code #NERtcErrorCode. + * @return Detailed descriptions of error codes. + * @endif + * @if Chinese + * 查看指定错误码的错误描述。 + * @note 目前该方法无效，只返回空值。请在 \ref IRtcEngineEventHandler::onError "onError" 中查看返回的错误码及具体的错误描述。 + * @param[in] error_code #NERtcErrorCode 。 + * @return 详细错误码描述 + * @endif + */ +virtual const char* getErrorDescription(int error_code) = 0; +/** + * @if English + * Uploads the SDK information. + *
You can call the method only after joining a room. + *
The data that is published contains the log file and the audio dump file. + * @return void + * @endif + * @if Chinese + * 上传 SDK 信息。 + *
只能在加入房间后调用。 + *
上传的信息包括 log 和 Audio dump 等文件。 + * @return void + * @endif + */ +virtual void uploadSdkInfo() = 0; +/** + * @if English + * Adjusts the volume of captured signals. + * @note The method only adjusts the volume of captured signals in the application programs without modifying the volumes of the + * device. If you need to modify the volume of the device, see related interfaces of device management. + * @param[in] volume indicates the volume of the captured recording. Valid values: 0 to 400. Where: + * - 0: Mute. + * - 100: The original volume. + * - 400: The maximum value can be four times the original volume. The limit value is protected. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 调节采集信号音量。 + * @note 该方法仅调节应用程序中的采集信号音量，不修改设备音量。如果需要修改设备音量，请查看设备管理相关接口。 + * @param[in] volume 采集录音音量，取值范围为 [0, 400]。其中： + * - 0: 静音； + * - 100: 原始音量； + * - 400: 最大可为原始音量的 4 倍（自带溢出保护）。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +virtual int adjustRecordingSignalVolume(int volume) = 0; +/** + * @if English + * Adjusts the volume of the audio local playback. + * @note The method only adjusts the volume of captured signals in the application programs without modifying the volumes of the + * device. If you need to modify the volume of the device, see related interfaces of device management. + * @param[in] volume indicates the playback volume. Valid range: 0 to 400. Where: + * - 0: Mute. + * - 100: The original volume. + * - 400: The maximum value can be four times the original volume. The limit value is protected. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 调节本地播放音量。 + * @note 该方法仅调节应用程序中音量，不修改设备音量。如果需要修改设备音量，请查看设备管理相关接口。 + * @param[in] volume 播放音量。取值范围为 [0, 400]。其中： + * - 0: 静音； + * - 100: 原始音量； + * - 400: 最大可为原始音量的 4 倍（自带溢出保护）。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +virtual int adjustPlaybackSignalVolume(int volume) = 0; + + +/** + * @if English + * Publishes or unpublishes the local audio stream. + *
When a user joins a room, the feature is enabled by default. + *
The method does not affect receiving or playing the remote audio stream. The enableLocalAudio(false) method is suitable for scenarios where clients only receives remote media streams and does not publish any local streams. + * @note + * - The method controls data transmitted over the main stream + * - The method can be called before or after a user joins a room. + * @since V4.6.10 + * @param enabled specifies whether to publish the local audio stream. + * - true(default): publishes the local audio stream. + * - false: unpublishes the local audio stream. + * @param mediaType media type. Audio type is supported. + * @return + * - 0: success + * - Others: failure + * @endif + * @if Chinese + * 开启或关闭本地媒体流（主流）的发送。 + *
该方法用于开始或停止向网络发送本地音频或视频数据。 + *
该方法不影响接收或播放远端媒体流，也不会影响本地音频或视频的采集状态。 + * @since V4.6.10 + * @note + * - 该方法暂时仅支持控制音频流的发送。 + * - 该方法在加入房间前后均可调用。 + * - 停止发送媒体流的状态会在通话结束后被重置为允许发送。 + * - 成功调用该方法切换本地用户的发流状态后，房间内其他用户会收到 \ref IRtcEngineEventHandler::onUserAudioStart "onUserAudioStart"（开启发送音频）或 \ref IRtcChannelEventHandler::onUserAudioStop "onUserAudioStop"（停止发送音频）的回调。 + * @par 相关接口 + * - \ref IRtcEngineEx::muteLocalAudioStream "muteLocalAudioStream"： + * - 在需要开启本地音频采集（监测本地用户音量）但不发送音频流的情况下，您也可以调用 muteLocalAudioStream(true) 方法。 + * - 两者的差异在于，muteLocalAudioStream(true) 仍然保持与服务器的音频通道连接，而 enableMediaPub(false) 表示断开此通道，因此若您的实际业务场景为多人并发的大房间，建议您调用 enableMediaPub 方法。 + * @param enabled 是否发布本地媒体流。 + * - true（默认）：发布本地媒体流。 + * - false：不发布本地媒体流。 + * @param media_type 媒体发布类型，暂时仅支持音频。 + * @return + * - 0：方法调用成功。 + * - 其他：方法调用失败。 + * @endif + */ +virtual int enableMediaPublish(bool enabled, NERtcMediaPubType media_type) = 0; + +/** + * 设置范围语音模式 + * @note 此接口在加入房间前后均可调用。 + * @param mode 范围语音模式 + * @return 操作返回值，成功则返回 0 + */ +virtual int setRangeAudioMode(NERtcRangeAudioMode mode) = 0; + +/** + * 设置范围语音小队 + * @note 此接口在加入房间前后均可调用。 + * @param team_id 小队ID + * @return 操作返回值，成功则返回 0 + */ +virtual int setRangeAudioTeamID(int32_t team_id) = 0; + +/** + * 引擎3D音效算法距离范围设置 + * @note 依赖enableSpatializer接口开启，通话前调用 + * @param audible_distance 监听器能够听到扬声器并接收其文本消息的距离扬声器的最大距离。[0,1000] 默认值为 32。 + * @param conversational_distance 控制扬声器音频保持其原始音量的范围，超出该范围时，语音聊天的响度在被听到时开始淡出。 + * 默认值为 1。 + * @param roll_off:距离衰减模式 #NERtcDistanceRolloffModel ，默认值 #kNERtcDistanceRolloffNone + * @return + * - 0: 方法调用成功 + * - 其他: 调用失败 + */ +virtual int setAudioRecvRange(int audible_distance, int conversational_distance, NERtcDistanceRolloffModel roll_off) = 0; +/** + * 引擎3D音效算法中本人坐标方位更新接口 + * @note 依赖enableSpatializer接口开启，enableSpatializer接口关闭后重置设置 + * @param speaker_position 嘴巴位置信息，默认值{0,0,0} + * @param speaker_quaternion 嘴巴方向信息，四元组格式，默认值{0,0,0,0} + * @param head_position 耳朵位置信息，默认值{0,0,0} + * @param head_quaternion 耳朵方向信息，四元组格式，默认值{0,0,0,0} + * @return + * - 0: 方法调用成功 + * - 其他: 调用失败 + */ +virtual int updateSelfPosition(const NERtcPositionInfo& info) = 0; + +/** + * 初始化引擎3D音效算法 + * @note 此接口在加入房间前调用，退出房间后不重置 + * @return + * - 0: 方法调用成功 + * - 其他: 调用失败 + */ +virtual int initSpatializer() = 0; + +/** + * 引擎3D音效算法开关 + * @note 通话前调用，通话结束后不重置 + * @param enable 是否打开3D音效算法功能 + * @return + * - 0: 方法调用成功 + * - 其他: 调用失败 + */ +virtual int enableSpatializer(bool enable) = 0; + +/** + * 获取麦克风开关状态 + * @return 麦克风打开状态 + */ +virtual int getMicrophoneMode(bool* enabled) = 0; + +/** + * 获取麦克风音量 + * @return 麦克风音量 + */ +virtual int getRecordingSignalVolume() = 0; + +/** + * 获取扬声器音量 + * @return 扬声器音量 + */ +virtual int getPlaybackSignalVolume() = 0; + +/** + * 检查平台麦克风权限（移动端） + * @return 麦克风权限 + */ +virtual bool checkMicPermision() = 0; + +/** + * 暂停音频输入与输出 + @return + - 0: 方法调用成功； + - 其他: 方法调用失败。 + */ +virtual int pauseAudio() = 0; +/** + * 暂停音频输入与输出 + @return + - 0: 方法调用成功； + - 其他: 方法调用失败。 + */ +virtual int resumeAudio() = 0; +/** + * 检查是否已经在房间内 + @param enabled 输出结果，true:在房间内 false:不在房间内 + @return + - 0: 方法调用成功； + - 其他: 方法调用失败。 + */ +virtual bool isInChannel() = 0; +/** + * 安卓平台下请求录音权限、蓝牙权限 + */ +virtual bool acquireAndroidRecordingPermissions() = 0; +}; + + NERTC_UE_API IRtcEngineEx* NERTC_UE_CALL createNERtcEngine(); +} \ No newline at end of file diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/INertcMediaStatsObserver.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/INertcMediaStatsObserver.h new file mode 100644 index 0000000..17b6032 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/INertcMediaStatsObserver.h @@ -0,0 +1,95 @@ +/** @file nertc_engine_media_stats_observer.h + * @brief The interface header file of expansion callback of the NERTC SDK. + * All parameter descriptions of the NERTC SDK. All string-related parameters (char *) are encoded in UTF-8. + * @copyright (c) 2021, NetEase Inc. All rights reserved. + */ +#pragma once +#include "NertcEngineDefines.h" + +/** + * @namespace nertc + * @brief namespace nertc + */ +namespace nertc { +/** + * @if English + * The SDK reports stats to the application through IRtcMediaStatsObserver expansion callback interface class. + *
All methods in this interface class have their (empty) default implementations, and the application can inherit only some + * of the required events instead of all of them. When calling a callback method, the application must not implement + * time-consuming operations or call blocking-triggered APIs. For example, if you want to enable audio and video, the SDK may be + * affected in the runtime. + * @endif + * @if Chinese + * IRtcMediaStatsObserver 回调扩展接口类用于 SDK 向 App 上报统计信息。 + *
接口类的所有方法都有缺省（空）实现，App 可以根据需要只继承关心的事件。在回调方法中，App + * 不应该做耗时或者调用可能会引起阻塞的 API（如开启音频或视频等），否则可能影响 SDK 的运行。 + * @endif + */ +class IRtcMediaStatsObserver { + public: + virtual ~IRtcMediaStatsObserver() {} + + /** + * 当前通话统计回调。 + * SDK 定期向 App 报告当前通话的统计信息，每 2 秒触发一次。 + * + * @param stats NERTC 引擎统计数据: nertc_stats + */ + virtual void onRtcStats(const NERtcStats& stats) { (void)stats; } + + /** + * 本地音频流统计信息回调。 + * 该回调描述本地设备发送音频流的统计信息，每 2 秒触发一次。 + * + * @param stats 本地音频流统计信息。详见 nertc_audio_send_stats. + */ + virtual void onLocalAudioStats(const NERtcAudioSendStats& stats) { (void)stats; } + + /** + * 通话中远端音频流的统计信息回调。 + * 该回调描述远端用户在通话中端到端的音频流统计信息，每 2 秒触发一次。 + * + * @param stats 每个远端用户音频统计信息的数组。详见 nertc_audio_recv_stats. + * @param user_count stats 数组的大小。 + */ + virtual void onRemoteAudioStats(const NERtcAudioRecvStats* stats, unsigned int user_count) { + (void)stats; + (void)user_count; + } + + /** + * 本地视频流统计信息回调。 + * + * 该回调描述本地设备发送视频流的统计信息，每 2 秒触发一次。 + * + * @param stats 本地视频流统计信息。详见 nertc_video_send_stats. + */ + virtual void onLocalVideoStats(const NERtcVideoSendStats& stats) { (void)stats; } + + /** + * 通话中远端视频流的统计信息回调。 + * + * 该回调描述远端用户在通话中端到端的视频流统计信息，每 2 秒触发一次。 + * + * @param stats 每个远端用户视频统计信息的数组。详见 nertc_video_recv_stats. + * @param user_count stats 数组的大小。 + */ + virtual void onRemoteVideoStats(const NERtcVideoRecvStats* stats, unsigned int user_count) { + (void)stats; + (void)user_count; + } + + /** + * 通话中每个用户的网络上下行质量报告回调。 + * + * 该回调描述每个用户在通话中的网络状态，每 2 秒触发一次，只上报状态有变更的成员。 + * + * @param infos 每个用户 ID 和网络上下行质量信息的数组: nertc_network_quality_info + * @param user_count infos 数组的大小，即用户数。 + */ + virtual void onNetworkQuality(const NERtcNetworkQualityInfo* infos, unsigned int user_count) { + (void)infos; + (void)user_count; + } +}; +} // namespace nertc diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/NertcBase.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/NertcBase.h new file mode 100644 index 0000000..adb43f6 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/NertcBase.h @@ -0,0 +1,35 @@ +/** @file nertc_base.h + * @brief Defines macro output. The file only defines macro output instead of anything else. + * @copyright (c) 2015-2019, NetEase Inc. All rights reserved. + */ + +#ifndef NERTC_BASE_H +#define NERTC_BASE_H + +#if defined(_WIN32) +#ifndef WIN32_LEAN_AND_MEAN +#define WIN32_LEAN_AND_MEAN +#endif +#include +#define NERTC_UE_CALL __cdecl +#define NERTC_UE_API extern "C" __declspec(dllexport) +#elif defined(__APPLE__) +#define NERTC_UE_API __attribute__((visibility("default"))) extern "C" +#define NERTC_UE_CALL +#elif defined(__ANDROID__) || defined(__linux__) +#define NERTC_UE_API extern "C" __attribute__((visibility("default"))) +#define NERTC_UE_CALL +#else +#define NERTC_UE_API extern "C" +#define NERTC_UE_CALL +#endif + +#if defined __GNUC__ +#define NERTC_DEPRECATED __attribute__((deprecated)) +#elif defined(_MSC_VER) +#define NERTC_DEPRECATED __declspec(deprecated) +#else +#define NERTC_DEPRECATED +#endif + +#endif diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/NertcBaseTypes.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/NertcBaseTypes.h new file mode 100644 index 0000000..28b1cbf --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/NertcBaseTypes.h @@ -0,0 +1,84 @@ +/** @file nertc_base.h + * @brief The definition of SDK basic types. + * @copyright (c) 2021, NetEase Inc. All rights reserved. + */ + +#ifndef NERTC_BASE_TYPES_H +#define NERTC_BASE_TYPES_H + +#include + +#ifndef _MSC_VER +// stdint.h is part of C99 but MSVC doesn't have it. +#include // For intptr_t. +#endif + +/* define int types*/ +#if defined(__GNUC__) + +#ifndef _STDINT_H + +/* FreeBSD has these C99 int types defined in /sys/inttypes.h already */ +#ifndef _SYS_TYPES_H +typedef signed char int8_t; +typedef signed short int16_t; +typedef signed int int32_t; +typedef signed long long int64_t; +typedef unsigned char uint8_t; +typedef unsigned short uint16_t; +typedef unsigned int uint32_t; +typedef unsigned long long uint64_t; +#else +typedef u_int8_t uint8_t; +typedef u_int16_t uint16_t; +typedef u_int32_t uint32_t; +typedef u_int64_t uint64_t; +#endif // _SYS_TYPES_H + +#endif // _STDINT_H + +#elif defined(_MSC_VER) +typedef signed char int8_t; +typedef signed short int16_t; +typedef signed int int32_t; +typedef signed __int64 int64_t; +typedef unsigned char uint8_t; +typedef unsigned short uint16_t; +typedef unsigned int uint32_t; +typedef unsigned __int64 uint64_t; + +/* the following definitions are from VS2010's stdint.h */ +// #ifndef _INTPTR_T_DEFINED +// #define _INTPTR_T_DEFINED +// #ifdef _WIN64 +// typedef __int64 intptr_t; +// #else /* _WIN64 */ +// typedef _W64 int intptr_t; +// #endif /* _WIN64 */ +// #endif /* _INTPTR_T_DEFINED */ +// +// #ifndef _UINTPTR_T_DEFINED +// #define _UINTPTR_T_DEFINED +// #ifdef _WIN64 +// typedef unsigned __int64 uintptr_t; +// #else /* _WIN64 */ +// typedef _W64 unsigned int uintptr_t; +// #endif /* _WIN64 */ +// #endif /* _UINTPTR_T_DEFINED */ + +#endif // COMPILER_GCC/COMPILER_MSVC + +// const uint8_t kUint8Max = (( uint8_t) 0xFF); +// const uint16_t kUint16Max = ((uint16_t) 0xFFFF); +// const uint32_t kUint32Max = ((uint32_t) 0xFFFFFFFF); +// const uint64_t kUint64Max = ((uint64_t) GG_LONGLONG(0xFFFFFFFFFFFFFFFF)); +// const int8_t kInt8Min = (( int8_t) 0x80); +// const int8_t kInt8Max = (( int8_t) 0x7F); +// const int16_t kInt16Min = (( int16_t) 0x8000); +// const int16_t kInt16Max = (( int16_t) 0x7FFF); +// const int32_t kInt32Min = (( int32_t) 0x80000000); +// const int32_t kInt32Max = (( int32_t) 0x7FFFFFFF); +// const int64_t kInt64Min = (( int64_t) GG_LONGLONG(0x8000000000000000)); +// const int64_t kInt64Max = (( int64_t) GG_LONGLONG(0x7FFFFFFFFFFFFFFF)); + +#endif // NERTC_BASE_TYPES_H diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/NertcEngineDefines.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/NertcEngineDefines.h new file mode 100644 index 0000000..1c5eabe --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/NertcEngineDefines.h @@ -0,0 +1,8292 @@ +/** @file nertc_engine_defines.h + * @brief NERtc SDK definitions. + * @copyright (c) 2021, NetEase Inc. All rights reserved. + */ + +#pragma once + +#include "NertcBaseTypes.h" +/** + * @if English + * Video max plane count. + * @endif + * @if Chinese + * Video max plane count. + * @endif + */ +#define kNERtcMaxPlaneCount 4 +/** + * @if English + * The length of the encryption key. + * @endif + * @if Chinese + * 加密key的长度 + * @endif + */ +#define kNERtcEncryptByteLength 128 +/** + * @if Chinese + * 自定义信息的长度 + * @endif + */ +#define kNERtcCustomInfoLength 128 +/** + * @if English + * Maximum length of a room ID. + * @endif + * @if Chinese + * 房间ID最大长度 + * @endif + */ +#define kNERtcMaxChannelNameLength 128 +/** + * @if English + * maximum token length. + * @endif + * @if Chinese + * token最大长度 + * @endif + */ +#define kNERtcMaxTokenLength 256 +/** + * @if English + * Maximum length of a device ID. + * @endif + * @if Chinese + * 设备ID最大长度。 + * @endif + */ +#define kNERtcMaxDeviceIDLength 256 +/** + * @if English + * Maximum length of a device name. + * @endif + * @if Chinese + * 设备名最大长度。 + * @endif + */ +#define kNERtcMaxDeviceNameLength 256 +/** + * @if English + * Maximum length of the URI. + * @endif + * @if Chinese + * URI最大长度。 + * @endif + */ +#define kNERtcMaxURILength 256 +/** + * @if English + * Maximum length of the task ID. + * @endif + * @if Chinese + * 任务ID最大长度。 + * @endif + */ +#define kNERtcMaxTaskIDLength 64 +/** + * @if English + * Maximum length of the string buffer. + * @endif + * @if Chinese + * 字符串缓存区最大长度。 + * @endif + */ +#define kNERtcMaxBuffLength 1024 +/** + * @if English + * Maximum length of SEI information used in live streaming. Unit: bytes. + * @endif + * @if Chinese + * 直播推流中用到的SEI信息最大长度，单位：字节 + * @endif + */ +#define kNERtcMaxSEIBufferLength 4096 +/** + * @if English + * Device ID of an external video input source. After you enable external input, you must set this device ID using setDevice. + * @endif + * @if Chinese + * 外部视频输入源设备ID，开启外部输入之后，需要通过setDevice设置此设备ID。 + * @endif + */ +#define kNERtcExternalVideoDeviceID "nertc-video-external-device" +/** + * @if English + * The audio device automatically selects the ID. When the ID is set as the device, the SDK will automatically select the + * appropriate audio device based on the device management system settings. + * @endif + * @if Chinese + * 音频设备自动选择ID，设置该ID为设备时，SDK会根据设备插拔系统设置等自动选择合适音频设备。 + * @endif + */ +#define kNERtcAudioDeviceAutoID "nertc-audio-device-auto" + +/** + * @namespace nertc + * @brief namespace nertc + */ +namespace nertc { +/** + * @if English + * 64-bit unsigned integer. Recommended setting range: 1 to 2 63 -1, and make sure the number is unique. + * @endif + * @if Chinese + * 64位无符号整数。建议设置范围：1到 263-1，并保证唯一性。 + * @endif + */ +typedef uint64_t uid_t; +/** + * @if English + * 64-bit unsigned integer. Recommended setting range: 1 to 2 63 -1, and make sure the number is unique. + * @endif + * @if Chinese + * 64位无符号整数。建议设置范围：1到 263-1，并保证唯一性。 + * @endif + */ +typedef uint64_t channel_id_t; +/** + * @if English + * Identify the source of the screen capture from a window or screen. If the source is a window, the type will be converted to + * HWND on Windows, and it will be converted to the INT data type on macOS. If the source is screen, the source type will be + * converted to the INT data type. + * @endif + * @if Chinese + * 用于标识屏幕捕捉的源，代表某个窗口或屏幕。源为窗口时, Windows上该类型会转换为HWND, MAC上转换为整形。源为屏幕时会转换为整形。 + * @endif + */ +typedef void* source_id_t; + +/** + * @if English + * Interface ID type. + * + * @endif + * @if Chinese + * 接口ID类型。 + * @endif + */ +typedef enum { + /** + * @if English + * Get the interface ID of the audio device manager. + * @endif + * @if Chinese + * 获取音频设备管理器的接口ID + * @endif + */ + kNERtcIIDAudioDeviceManager = 1, + /** + * @if English + * Get the interface ID of the video device manager. + * @endif + * @if Chinese + * 获取视频设备管理器的接口ID + * @endif + */ + kNERtcIIDVideoDeviceManager = 2, +} NERtcInterfaceIdType; + +/** + * @if English + * Participant role type. + * @endif + * @if Chinese + * 参会者角色类型 + * @endif + */ +typedef enum { + /** + * @if English + * The host role in live streaming. The host has the permissions to open or close audio and video devices, such as a camera, + * publish streams, and configure streaming tasks in interactive live streaming. The status of the host is visible to the + * users in the room when the host joins or leaves the room. + * @endif + * @if Chinese + * （默认）直播模式中的主播，可以操作摄像头等音视频设备、发布流、配置互动直播推流任务、上下线对房间内其他用户可见。 + * @endif + */ + kNERtcClientRoleBroadcaster = 0, + /** + * @if English + * The audience role in live streaming. The audience can only receive audio and video streams, and cannot manage audio and + * video devices, and configure streaming tasks in interactive live streaming. The status of an audience is invisible to the + * users in the room when the audience joins or leaves the room. + * @endif + * @if Chinese + * 直播模式中的观众，观众只能接收音视频流，不支持操作音视频设备、配置互动直播推流任务、上下线不通知其他用户。 + * @endif + */ + kNERtcClientRoleAudience = 1, +} NERtcClientRole; + +/** + * @if English + * Scenario types. + * @endif + * @if Chinese + * 场景模式。 + * @endif + */ +typedef enum { + /** + * @if English + * Communication mode。 + * @endif + * @if Chinese + * 通话场景 + * @endif + */ + kNERtcChannelProfileCommunication = 0, + /** + * @if English + * Live streaming mode. + * @endif + * @if Chinese + * 直播推流场景 + * @endif + */ + kNERtcChannelProfileLiveBroadcasting = 1, +} NERtcChannelProfileType; + + +/** + * @if English + * Media priority type. + * @endif + * @if Chinese + * 媒体优先级类型。 + * @endif + */ +typedef enum { + /** + * @if English + * High priority + * @endif + * @if Chinese + * 高优先级 + * @endif + */ + kNERtcMediaPriorityHigh = 50, + /** + * @if English + * Normal priority (default) + * @endif + * @if Chinese + * （默认）普通优先级 + * @endif + */ + kNERtcMediaPriorityNormal = 100, +} NERtcMediaPriorityType; + +/** + * @if English + * Co-hosting method. + * @endif + * @if Chinese + * 连麦方式。 + * @endif + */ +typedef enum { + kNERtcLayoutFloatingRightVertical = 0, + kNERtcLayoutFloatingLeftVertical, + kNERtcLayoutSplitScreen, + kNERtcLayoutSplitScreenScaling, + kNERtcLayoutCustom, + kNERtcLayoutAudioOnly, +} NERtcLiveStreamLayoutMode; + +/** + * @if English + * Configuration of streaming tasks. + * @endif + * @if Chinese + * 直播推流任务的配置项。 + * @endif + */ +struct NERtcLiveStreamTaskOption { + /** + * @if English + * Streaming task ID, which is the unique identifier of a streaming task. You can use the ID to create and delete streaming + * tasks. + * @endif + * @if Chinese + * 推流任务ID，为推流任务的唯一标识，用于过程中增删任务操作。 + * @endif + */ + char task_id[kNERtcMaxTaskIDLength]; + /** + * @if English + * Live streaming URL address. + * @endif + * @if Chinese + * 直播推流地址。 + * @endif + */ + char stream_url[kNERtcMaxURILength]; + /** + * @if English + * Enable or disable server recording. The default value is false. + * @endif + * @if Chinese + * 服务器录制功能是否开启，默认值为 false。 + * @endif + */ + bool server_record_enabled; + /** + * @if English + * Co-hosting method. The default value is kNERtcLayoutFloatingRightVertical. + * @endif + * @if Chinese + * 连麦方式，默认值为 kNERtcLayoutFloatingRightVertical。 + * @endif + */ + NERtcLiveStreamLayoutMode layout_mode; + /** + * @if English + * Specify the main picture uid (optional). + * @endif + * @if Chinese + * 指定大画面uid（选填）。 + * @endif + */ + uid_t main_picture_account_id; + /** + * @if English + * Custom layout parameters in JSON format (optional). You need to set the layout parameters only when layout_mode is set to + * kNERtcLayoutCustom or kNERtcLayoutAudioOnly. + * @endif + * @if Chinese + * 自定义布局参数（选填），JSON 字符串格式, 只有当layout_mode为 kNERtcLayoutCustom 或 kNERtcLayoutAudioOnly时才需要设置。 + * @endif + */ + char layout_parameters[kNERtcMaxBuffLength]; +}; + +/** + * @if English + * Streaming mode in live streaming. + * @endif + * @if Chinese + * 直播推流模式 + * @endif + */ +typedef enum { + /** + * @if English + * Publish the video stream. + * @endif + * @if Chinese + * 推流带视频 + * @endif + */ + kNERtcLsModeVideo = 0, + /** + * @if English + * Publish audio-only stream. + * @endif + * @if Chinese + * 推流纯音频 + * @endif + */ + kNERtcLsModeAudio = 1, +} NERtcLiveStreamMode; + +/** + * @if English + * Video cropping mode in live streaming + * @endif + * @if Chinese + * 直播推流视频裁剪模式 + * @endif + */ +typedef enum { + /** + * @if English + * 0: Video dimensions are scaled proportionally. All video content is prioritized for display. If the video dimensions do not + * match the display window, the unfilled area of the window will be filled with the background color. + * @endif + * @if Chinese + * 0: 视频尺寸等比缩放。优先保证视频内容全部显示。因视频尺寸与显示视窗尺寸不一致造成的视窗未被填满的区域填充背景色。 + * @endif + */ + kNERtcLsModeVideoScaleFit = 0, + /** + * @if English + * 1: Video dimensions are scaled proportionally. The window is prioritized to be filled. The extra video due to the + * inconsistency between the video size and the display window size will be cropped off. + * @endif + * @if Chinese + * 1: 视频尺寸等比缩放。优先保证视窗被填满。因视频尺寸与显示视窗尺寸不一致而多出的视频将被截掉。 + * @endif + */ + kNERtcLsModeVideoScaleCropFill = 1, +} NERtcLiveStreamVideoScaleMode; + +/** + * @if English + * The member layout in live streaming. + * @endif + * @if Chinese + * 直播成员布局 + * @endif + */ +struct NERtcLiveStreamUserTranscoding { + /** + * @if English + * Pulls the video stream of the user with the specified uid into the live event. If you add multiple users, the uid must be + * unique. + * @endif + * @if Chinese + * 将指定uid对应用户的视频流拉入直播。如果添加多个 users，则 uid 不能重复。 + * @endif + */ + uid_t uid; + /** + * @if English + * Specifies whether to play back the specific video stream from the user to viewers in the live event. Valid values: + * - true: plays the video stream. + * - false: does not play the video stream. + * The setting becomes invalid when the streaming mode is set to kNERtcLsModeAudio. + * @endif + * @if Chinese + * 是否在直播中向观看者播放该用户的对应视频流。可设置为： + * - true：在直播中播放该用户的视频流。 + * - false：在直播中不播放该用户的视频流。 + * 推流模式为 kNERtcLsModeAudio 时无效。 + * @endif + */ + bool video_push; + /** + * @if English + * Adjustment between the video and the canvas in live streaming. For more information, see NERtcLiveStreamVideoScaleMode. + * @endif + * @if Chinese + * 直播推流视频和画布的调节属性。详细信息请参考 NERtcLiveStreamVideoScaleMode。 + * @endif + */ + NERtcLiveStreamVideoScaleMode adaption; + /** + * @if English + * The X parameter is used to set the horizontal coordinate value of the user image. You can specify a point in the canvas + * with X and Y coordinates. This point is used as the anchor of the upper left corner of the user image. + * - Value range: 0 to 1920. If the specified value is set to an odd value, the value is automatically rounded down to an even + * number. + * - If the user image exceeds the canvas, an error occurs when you call the method. + * @endif + * @if Chinese + * x 参数用于设置用户图像的横轴坐标值。通过 x 和 y 指定画布坐标中的一个点，该点将作为用户图像的左上角。 + * - 取值范围为 0~1920，若设置为奇数值，会自动向下取偶。 + * - 用户图像范围如果超出超出画布，调用方法时会报错。 + * @endif + */ + int x; + /** + * @if English + * The Y parameter is used to set the vertical coordinate value of the user image. You can specify a point in the canvas with + * X and Y coordinates. This point is used as the anchor of the upper left corner of the user image. + * - Value range: 0 to 1920. If the specified value is set to an odd value, the value is automatically rounded down to an even + * number. + * - If the user image exceeds the canvas, an error occurs when you call the method. + * @endif + * @if Chinese + * y参数用于设置用户图像的纵轴坐标值。通过 x 和 y 指定画布坐标中的一个点，该点将作为用户图像的左上角。 + * - 取值范围为 0~1920，若设置为奇数值，会自动向下取偶。 + * - 用户图像范围如果超出超出画布，调用方法时会报错。 + * @endif + */ + int y; + /** + * @if English + * The width of the user image in the canvas. + * - Value range: 0 to 1920. The default value is 0. If the specified value is set to an odd value, the value is automatically + * rounded down to an even number. + * - If the user image exceeds the canvas, an error occurs when you call the method. + * @endif + * @if Chinese + * 该用户图像在画布中的宽度。 + * - 取值范围为 0~1920，默认为0。若设置为奇数值，会自动向下取偶。 + * - 用户图像范围如果超出超出画布，调用方法时会报错。 + * + * @endif + */ + int width; + /** + * @if English + * The height of the user image in the canvas. + * - The X parameter is used to set the horizontal coordinate value of the user image. You can specify a point in the canvas + * with X and Y coordinates. This point is used as the anchor of the upper left corner of the user image. 0 to 1920. The + * default value is 0. If the specified value is set to an odd value, the value is automatically rounded down to an even + * number. + * - Value range: 0 to 1920. If the specified value is set to an odd value, the value is automatically rounded down to an even + * number. + * @endif + * @if Chinese + * 该用户图像在画布中的高度。 + * - 取值范围为 0~1920，默认为0。若设置为奇数值，会自动向下取偶。 + * - 用户图像范围如果超出超出画布，调用方法时会报错。 + * @endif + */ + int height; + /** + * @if English + * Specifies whether to mix the audio stream from the user in the live event. Valid values: + * - true: mixes the audio streams from users in a live event. + * - false: mutes the audio streams from users in a live event. + * @endif + * @if Chinese + * 是否在直播中混流该用户的对应音频流。可设置为： + * - true：在直播中混流该用户的对应音频流。 + * - false：在直播中将该用户设置为静音。 + * @endif + */ + bool audio_push; + /** + * @if English + * The layer number that is used to determine the rendering level. Value range: 0 to 100. A value of 0 indicates the bottom + * layer and 100 indicates the top layer.
The rendering area at the same level is overwritten based on the existing + * overlay strategy. Rendering is performed in the order of the array, and the index increases in ascending order. + * @endif + * @if Chinese + * 图层编号，用来决定渲染层级, 取值0-100，0位于最底层，100位于最顶层。 + * 相同层级的渲染区域按照现有的覆盖逻辑实现，即按照数组中顺序进行渲染，index 递增依次往上叠加。 + * @endif + */ + int z_order; +}; + +/** + * @if English + * Picture layout. + * @endif + * @if Chinese + * 图片布局 + * @endif + */ +struct NERtcLiveStreamImageInfo { + /** + * @if English + * The URL of the placeholder image. + * @endif + * @if Chinese + * 占位图片的URL。 + * @endif + */ + char url[kNERtcMaxURILength]; + /** + * @if English + * The X parameter is used to set the horizontal coordinate value of the canvas. + * You can specify a point in the canvas with X and Y coordinates. This point is used as the anchor of the upper left corner + * of the placeholder image. Value range: 0 to 1920. If the specified value is set to an odd value, the value is automatically + * rounded down to an even number. + * @endif + * @if Chinese + * x 参数用于设置画布的横轴坐标值。 + * 通过 x 和 y 指定画布坐标中的一个点，该点将作为占位图片的左上角。 + * 取值范围为 0~1920，若设置为奇数值，会自动向下取偶。 + * @endif + */ + int x; + /** + * @if English + * The Y parameter is used to set the vertical coordinate value of the canvas. + * - You can specify a point in the canvas with X and Y coordinates. This point is used as the anchor of the upper left corner + * of the placeholder image. + * - Value range: 0 to 1920. If the specified value is set to an odd value, the value is automatically rounded down to an even + * number. + * @endif + * @if Chinese + * y 参数用于设置画布的纵轴坐标值。 + * - 通过 x 和 y 指定画布坐标中的一个点，该点将作为占位图片的左上角。 + * - 取值范围为 0~1920，若设置为奇数值，会自动向下取偶。 + * @endif + */ + int y; + /** + * @if English + * The width of the placeholder image in the canvas. + *
Value range: 0 to 1920. If the specified value is set to an odd value, the value is automatically rounded down to an + * even number. + * @endif + * @if Chinese + * 该占位图片在画布中的宽度。 + *
取值范围为 0~1920，若设置为奇数值，会自动向下取偶。 + * @endif + */ + int width; + /** + * @if English + * The height of the placeholder image in the canvas. + *
Value range: 0 to 1920. If the specified value is set to an odd value, the value is automatically rounded down to an + * even number. + * @endif + * @if Chinese + * 该占位图片在画布中的高度。 + *
取值范围为 0~1920，若设置为奇数值，会自动向下取偶。 + * @endif + */ + int height; + /** + * @if Chinese + * 占位图的图层编号，用来决定渲染层级。 + *
取值范围为 0~100，默认为 0。 + * - 最小值为 0（默认值），表示该区域图像位于最底层。 + * - 最大值为 100，表示该区域图像位于最顶层。 + *
注意：相同层级的渲染区域会按照数组中顺序进行渲染，随着 index 递增，依次往上叠加。 + * @endif + */ + int z_order; +}; + + +/** + * @if English + * The live streaming layout. + * @endif + * @if Chinese + * 直播布局 + * @endif + */ +struct NERtcLiveStreamLayout { + /** + * @if English + * The width of the overall canvas. Unit: px. Value range: 0 to 1920. If the specified value is set to an odd value, the value + * is automatically rounded down to an even number. + * @endif + * @if Chinese + * 整体画布的宽度，单位为 px。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。 + * @endif + */ + int width; + /** + * @if English + * The height of the overall canvas. Unit: - true: 0 to 1920. If the specified value is set to an odd value, the value is + * automatically rounded down to an even number. + * @endif + * @if Chinese + * 整体画布的高度，单位为 px。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。 + * @endif + */ + int height; + /** + * @if English + * The background color of the canvas. The value of the background color is the sum of 256 x 256 x R + 256 x G + B. Enter the + * corresponding RGB values into this formula to calculate the value. If the value is unspecified, the default value is 0. + * @endif + * @if Chinese + * 画面背景颜色，格式为 256 x 256 x R + 256 x G + B的和。请将对应 RGB 的值分别带入此公式计算即可。若未设置，则默认为0。 + * @endif + */ + unsigned int background_color; + /** + * @if English + * The member layout in live streaming. + * @endif + * @if Chinese + * 成员布局个数。 + * @endif + */ + unsigned int user_count; + /** + * @if English + * The member layout array. For more information, see NERtcLiveStreamUserTranscoding. + * @endif + * @if Chinese + * 成员布局数组，详细信息请参考 NERtcLiveStreamUserTranscoding。 + * @endif + */ + NERtcLiveStreamUserTranscoding* users; + /** + * @if English + * For more information, see NERtcLiveStreamImageInfo. + * @endif + * @if Chinese + * 详细信息请参考 NERtcLiveStreamImageInfo。 + * @endif + */ + NERtcLiveStreamImageInfo* bg_image; + + /** + * @if English + * The member of picture layout. + * @endif + * @if Chinese + * 图片布局个数。 + * @endif + */ + int bg_image_count; +}; + +/** + * @if English + * Live streaming audio sample rate + * @endif + * @if Chinese + * 直播推流音频采样率 + * @endif + */ +typedef enum { + /** + * @if English + * The sample rate is 32 kHz. + * @endif + * @if Chinese + * 采样率为 32 kHz。 + * @endif + */ + kNERtcLiveStreamAudioSampleRate32000 = 32000, + /** + * @if English + * The sample rate is 44.1 kHz. + * @endif + * @if Chinese + * 采样率为 44.1 kHz。 + * @endif + */ + kNERtcLiveStreamAudioSampleRate44100 = 44100, + /** + * @if English + * (Default) The sample rate is 48 kHz. + * @endif + * @if Chinese + * （默认）采样率为 48 kHz。 + * @endif + */ + kNERtcLiveStreamAudioSampleRate48000 = 48000, +} NERtcLiveStreamAudioSampleRate; + +/** + * @if English + * Live streaming audio codec profile + * @endif + * @if Chinese + * 直播推流音频编码规格 + * @endif + */ +typedef enum { + /** + * @if English + * (Default) LC- AAC, the basic audio encoding profile. + * @endif + * @if Chinese + * （默认）LC-AAC 规格，表示基本音频编码规格。 + * @endif + */ + kNERtcLiveStreamAudioCodecProfileLCAAC = 0, + /** + * @if English + * HE-AAC, high-efficiency audio encoding profile. + * @endif + * @if Chinese + * HE-AAC 规格，表示高效音频编码规格。 + * @endif + */ + kNERtcLiveStreamAudioCodecProfileHEAAC = 1, +} NERtcLiveStreamAudioCodecProfile; + +/** + * @if English + * Streaming configuration. + * @endif + * @if Chinese + * 直播流配置 + * @endif + */ +struct NERtcLiveConfig { + /** + * @if English + * Enables or disables single video pass-through. By default, the setting is disabled. + * - If you enable video pass-through, and the room ingests only one video stream, then, the stream is not transcoded and does + * not follow the transcoding flow. The video stream is directly published to a CDN. + * - If multiple video streams from different room members are mixed into one video stream, this setting becomes invalid, and + * will not be restored when the stream is restored to the single stream. + * @endif + * @if Chinese + * 单路视频透传开关，默认为关闭状态。 + * - 开启后，如果房间中只有一路视频流输入， 则不对输入视频流进行转码，不遵循转码布局，直接推流 CDN。 + * - 如果有多个房间成员视频流混合为一路流，则该设置失效，并在恢复为一个成员画面（单路流）时也不会恢复。 + * @endif + */ + bool single_video_passthrough; + /** + * @if English + * The bitrate of the audio stream. + * - Unit: kbps. Valid values: 10 to 192. + * - We recommend that you set the bitrate to 64 or higher for voice scenarios and set 128 or higher for music scenarios. + * @endif + * @if Chinese + * 音频推流码率。 + * - 单位为 kbps，取值范围为 10~192。 + * - 语音场景建议设置为 64 及以上码率，音乐场景建议设置为 128 及以上码率。 + * @endif + */ + int audio_bitrate; + + /** + * @if English + * The sample rate of the audio stream. Unit: Hz. The default value is kNERtcLiveStreamAudioSampleRate48000, which indicates + * the sample rate of 48 kHz. + * @endif + * @if Chinese + * 音频推流采样率。单位为Hz。默认为 kNERtcLiveStreamAudioSampleRate48000，即采样率为 48 kHz。 + * @endif + */ + NERtcLiveStreamAudioSampleRate sampleRate; + + /** + * @if English + * The number of audio channels for publishing streams. The default value is 2, which represents the stereo sound. + * @endif + * @if Chinese + * 音频推流声道数，默认值为 2 双声道。 + * @endif + */ + int channels; + + /** + * @if English + * The audio encoding profile. The default value is NERtcLiveStreamAudioCodecProfileLCAAC, which is the basic encoding + * profile. + * - 0: LC-AAC, the basic encoding profile. + * - 1: HE-AAC, the high-efficiency audio encoding profile. + * @endif + * @if Chinese + * 音频编码规格。默认值 NERtcLiveStreamAudioCodecProfileLCAAC，普通编码规格。 + * - 0: LC-AAC 规格，表示基本音频编码规格 + * - 1: HE-AAC 规格，表示高效音频编码规格。 + * @endif + */ + NERtcLiveStreamAudioCodecProfile audioCodecProfile; +}; + +/** + * @if English + * Configuration of streaming tasks. + * @endif + * @if Chinese + * 直播推流任务的配置项。 + * @endif + */ +struct NERtcLiveStreamTaskInfo { + /** + * @if English + * The ID of a custom streaming task. The ID must be up to 64 characters in length and can contain letters, numbers, and + * underscores. The ID must be unique. + * @endif + * @if Chinese + * 自定义的推流任务 ID。字母、数字、下划线组成的 64 位以内的字符串。请保证此 ID 唯一。 + * @endif + */ + char task_id[kNERtcMaxTaskIDLength]; + /** + * @if English + * The streaming URL, such as rtmp://test.url. + *
The URL can be set to the value of the pushUrl response parameter of the server API used to create a room in NetEase + * CommsEase live streaming. + * @endif + * @if Chinese + * 推流地址，例如 rtmp://test.url。 + *
此处的推流地址可设置为网易云信直播产品中服务端 API创建房间的返回参数pushUrl。 + * @endif + */ + char stream_url[kNERtcMaxURILength]; + /** + * @if English + * Specifies whether to enable audio and video recording in the CDN relayed streaming. By default, the setting is disabled. + * @endif + * @if Chinese + * 旁路推流是否需要进行音视频录制。默认为关闭状态。 + * @endif + */ + bool server_record_enabled; + /** + * @if English + * The live streaming mode. For more information, see NERtcLiveStreamMode. + * @endif + * @if Chinese + * 直播推流模式。详细信息请参考 NERtcLiveStreamMode。 + * @endif + */ + NERtcLiveStreamMode ls_mode; + /** + * @if English + * Set the canvas layout of Interactive Live Streaming. For more information, see NERtcLiveStreamLayout. + * @endif + * @if Chinese + * 设置互动直播的画面布局。详细信息请参考 NERtcLiveStreamLayout。 + * @endif + */ + NERtcLiveStreamLayout layout; + /** + * @if English + * Settings such as encoding parameters of the audio and video streams. For more information, see NERtcLiveConfig. + * @endif + * @if Chinese + * 音视频流编码参数等设置。详细信息请参考 NERtcLiveConfig。 + * @endif + */ + NERtcLiveConfig config; + /** + * @if English + * SEI message + * @endif + * @if Chinese + * SEI信息 + * @endif + */ + char extra_info[kNERtcMaxSEIBufferLength]; +}; + +/** + * @if English + * Live streaming status code. + * @endif + * @if Chinese + * 直播推流状态。 + * @endif + */ +typedef enum { + /** + * @if English + * Publishing. + * @endif + * @if Chinese + * 推流中 + * @endif + */ + kNERtcLsStatePushing = 505, + /** + * @if English + * Publishing fails. + * @endif + * @if Chinese + * 互动直播推流失败 + * @endif + */ + kNERtcLsStatePushFail = 506, + /** + * @if English + * Publishing ends. + * @endif + * @if Chinese + * 推流结束 + * @endif + */ + kNERtcLsStatePushStopped = 511, + /** + * @if English + * Background image setting error. + * @endif + * @if Chinese + * 背景图片设置出错 + * @endif + */ + kNERtcLsStateImageError = 512, +} NERtcLiveStreamStateCode; + +/** + * @if English + * System ategory. + * @endif + * @if Chinese + * 系统分类。 + * @endif + */ +typedef enum { + /** + * @if English + * iOS universal device. + * @endif + * @if Chinese + * iOS 通用设备 + * @endif + */ + kNERtcOSiOS = 1, + /** + * @if English + * Android universal device. + * @endif + * @if Chinese + * Android 通用设备 + * @endif + */ + kNERtcOSAndroid = 2, + /** + * @if English + * PC设备 + * @endif + * @if Chinese + * PC device. + * @endif + */ + kNERtcOSPC = 3, + /** + * @if English + * WebRTC. + * @endif + * @if Chinese + * WebRTC + * @endif + */ + kNERtcOSWebRTC = 4, +} NERtcOSCategory; + +/** + * @if English + * Audio profile. Audio sample rate, bitrate, encoding mode, and the number of channels. + * @endif + * @if Chinese + * 音频属性。设置采样率，码率，编码模式和声道数。 + * @endif + */ +typedef enum { + /** + * @if English + * Default settings. kNERtcAudioProfileStandard in the speech scenarios. kNERtcAudioProfileHighQuality in the music scenarios. + * @endif + * @if Chinese + * 0: 默认设置。Speech 场景下为 kNERtcAudioProfileStandardExtend，Music 场景下为 kNERtcAudioProfileHighQuality。 + * @endif + */ + kNERtcAudioProfileDefault = 0, + /** + * @if English + * 1: Standard-quality audio encoding, 16000Hz, 20kbps. + * @endif + * @if Chinese + * 1: 普通质量的音频编码，16000Hz，20Kbps + * @endif + */ + kNERtcAudioProfileStandard = 1, + /** + * @if English + * 2: Standard-quality audio encoding, 16000Hz, 32kbps. + * @endif + * @if Chinese + * 2: 普通质量的音频编码，16000Hz，32Kbps + * @endif + */ + kNERtcAudioProfileStandardExtend = 2, + /** + * @if English + * 3: Medium-quality audio encoding, 48000Hz, 32kbps. + * @endif + * @if Chinese + * 3: 中等质量的音频编码，48000Hz，32Kbps + * @endif + */ + kNERtcAudioProfileMiddleQuality = 3, + /** + * @if English + * 4: Medium-quality stereo encoding, 48000Hz * 2, 64kbps. + * @endif + * @if Chinese + * 4: 中等质量的立体声编码，48000Hz * 2，64Kbps + * @endif + */ + kNERtcAudioProfileMiddleQualityStereo = 4, + /** + * @if English + * 5: High-quality audio encoding, 48000Hz, 64kbps. + * @endif + * @if Chinese + * 5: 高质量的音频编码，48000Hz，64Kbps + * @endif + */ + kNERtcAudioProfileHighQuality = 5, + /** + * @if English + * 6: High-quality stereo encoding, 48000Hz * 2, 128kbps. + * @endif + * @if Chinese + * 6: 高质量的立体声编码，48000Hz * 2，128Kbps + * @endif + */ + kNERtcAudioProfileHighQualityStereo = 6, +} NERtcAudioProfileType; + + +/** + * @if English + * Audio application scenarios. Different audio scenarios use different audio capture modes and playback modes. + * @endif + * @if Chinese + * 音频应用场景。不同的场景设置对应不同的音频采集模式、播放模式。 + * @endif + */ +typedef enum { + /** + * @if English + * 0: Default settings. + * - kNERtcAudioScenarioSpeech in kNERtcChannelProfileCommunication. + * - kNERtcAudioScenarioMusic in kNERtcChannelProfileLiveBroadcasting. + * @endif + * @if Chinese + * 0: 默认设置 + * - kNERtcChannelProfileCommunication下为kNERtcAudioScenarioSpeech， + * - kNERtcChannelProfileLiveBroadcasting下为kNERtcAudioScenarioMusic。 + * @endif + */ + kNERtcAudioScenarioDefault = 0, + /** + * @if English + * 1: Voice scenarios. Set NERtcAudioProfileType to kNERtcAudioProfileMiddleQuality or lower. + * @endif + * @if Chinese + * 1: 语音场景. NERtcAudioProfileType 推荐使用 kNERtcAudioProfileMiddleQuality 及以下 + * @endif + */ + kNERtcAudioScenarioSpeech = 1, + /** + * @if English + * 2: Music scenarios. Set NERtcAudioProfileType to kNERtcAudioProfileMiddleQualityStereo or above. + * @endif + * @if Chinese + * 2: 音乐场景。NERtcAudioProfileType 推荐使用 kNERtcAudioProfileMiddleQualityStereo 及以上 + * @endif + */ + kNERtcAudioScenarioMusic = 2, + /** + * @if English + * 3: Chatroom scenario. Set NERtcAudioProfileType to kNERtcAudioProfileHighQuality or above. + * @endif + * @if Chinese + * 3: 语聊房场景 (只适用于移动端）。NERtcAudioProfileType 推荐使用 kNERtcAudioProfileHighQuality 及以上 + * @endif + */ + kNERtcAudioScenarioChatroom = 3, +} NERtcAudioScenarioType; + +/** + * @if English + * The preset value of the voice changer. + * @endif + * @if Chinese + * 变声 预设值 + * @endif + */ +typedef enum { + /** + * @if English + * By default, the setting is disabled. + * @endif + * @if Chinese + * 默认关闭 + * @endif + */ + kNERtcVoiceChangerOff = 0, + /** + * @if English + * A robot voice. + * @endif + * @if Chinese + * 机器人 + * @endif + */ + kNERtcVoiceChangerRobot = 1, + /** + * @if English + * A giant voice. + * @endif + * @if Chinese + * 巨人 + * @endif + */ + kNERtcVoiceChangerGaint = 2, + /** + * @if English + * A horror voice. + * @endif + * @if Chinese + * 恐怖 + * @endif + */ + kNERtcVoiceChangerHorror = 3, + /** + * @if English + * A maturity voice. + * @endif + * @if Chinese + * 成熟 + * @endif + */ + kNERtcVoiceChangerMature = 4, + /** + * @if English + * From a male voice to a female voice. + * @endif + * @if Chinese + * 男变女 + * @endif + */ + kNERtcVoiceChangerManToWoman = 5, + /** + * @if English + * From a female voice to a male voice. + * @endif + * @if Chinese + * 女变男 + * @endif + */ + kNERtcVoiceChangerWomanToMan = 6, + /** + * @if English + * From a male voice to a loli voice. + * @endif + * @if Chinese + * 男变萝莉 + * @endif + */ + kNERtcVoiceChangerManToLoli = 7, + /** + * @if English + * From a female voice to a loli voice. + * @endif + * @if Chinese + * 女变萝莉 + * @endif + */ + kNERtcVoiceChangerWomanToLoli = 8, +} NERtcVoiceChangerType; + +/** + * @if English + * Preset voice beautifier effect. + * @endif + * @if Chinese + * 预设的美声效果 + * @endif + */ +typedef enum { + /** + * @if English + * By default, the setting is disabled. + * @endif + * @if Chinese + * 默认关闭 + * @endif + */ + kNERtcVoiceBeautifierOff = 0, + /** + * @if English + * A muffled effect. + * @endif + * @if Chinese + * 低沉 + * @endif + */ + kNERtcVoiceBeautifierMuffled = 1, + /** + * @if English + * A mellow effect. + * @endif + * @if Chinese + * 圆润 + * @endif + */ + kNERtcVoiceBeautifierMellow = 2, + /** + * @if English + * A clear effect. + * @endif + * @if Chinese + * 清澈 + * @endif + */ + kNERtcVoiceBeautifierClear = 3, + /** + * @if English + * A magnetic effect. + * @endif + * @if Chinese + * 磁性 + * @endif + */ + kNERtcVoiceBeautifierMagnetic = 4, + /** + * @if English + * A recording studio effect. + * @endif + * @if Chinese + * 录音棚 + * @endif + */ + kNERtcVoiceBeautifierRecordingstudio = 5, + /** + * @if English + * A nature effect. + * @endif + * @if Chinese + * 天籁 + * @endif + */ + kNERtcVoiceBeautifierNature = 6, + /** + * @if English + * A KTV effect. + * @endif + * @if Chinese + * KTV + * @endif + */ + kNERtcVoiceBeautifierKTV = 7, + /** + * @if English + * A remote effect. + * @endif + * @if Chinese + * 悠远 + * @endif + */ + kNERtcVoiceBeautifierRemote = 8, + /** + * @if English + * A church effect. + * @endif + * @if Chinese + * 教堂 + * @endif + */ + kNERtcVoiceBeautifierChurch = 9, + /** + * @if English + * A bedroom effect. + * @endif + * @if Chinese + * 卧室 + * @endif + */ + kNERtcVoiceBeautifierBedroom = 10, + /** + * @if English + * A live effect. + * @endif + * @if Chinese + * Live + * @endif + */ + kNERtcVoiceBeautifierLive = 11, +} NERtcVoiceBeautifierType; + +/** + * @if English + * The center frequency of the sound equalization band. + * @endif + * @if Chinese + * 音效均衡波段的中心频率 + * @endif + */ +typedef enum { + /** + * @if English + * 31 Hz + * @endif + * @if Chinese + * 31 Hz + * @endif + */ + kNERtcVoiceEqualizationBand_31 = 0, + /** + * @if English + * 62 Hz. + * @endif + * @if Chinese + * 62 Hz + * @endif + */ + kNERtcVoiceEqualizationBand_62 = 1, + /** + * @if English + * 125 Hz. + * @endif + * @if Chinese + * 125 Hz + * @endif + */ + kNERtcVoiceEqualizationBand_125 = 2, + /** + * @if English + * 250 Hz. + * @endif + * @if Chinese + * 250 Hz + * @endif + */ + kNERtcVoiceEqualizationBand_250 = 3, + /** + * @if English + * 500 Hz. + * @endif + * @if Chinese + * 500 Hz + * @endif + */ + kNERtcVoiceEqualizationBand_500 = 4, + /** + * @if English + * 1 kHz. + * @endif + * @if Chinese + * 1 kHz + * @endif + */ + kNERtcVoiceEqualizationBand_1K = 5, + /** + * @if English + * 2 kHz. + * @endif + * @if Chinese + * 2 kHz + * @endif + */ + kNERtcVoiceEqualizationBand_2K = 6, + /** + * @if English + * 4 kHz. + * @endif + * @if Chinese + * 4 kHz + * @endif + */ + kNERtcVoiceEqualizationBand_4K = 7, + /** + * @if English + * 8 kHz. + * @endif + * @if Chinese + * 8 kHz + * @endif + */ + kNERtcVoiceEqualizationBand_8K = 8, + /** + * @if English + * 16 kHz. + * @endif + * @if Chinese + * 16 kHz + * @endif + */ + kNERtcVoiceEqualizationBand_16K = 9, +} NERtcVoiceEqualizationBand; + +/** + * @if English + * The camera capture preference. + * @endif + * @if Chinese + * 设置摄像头的采集偏好。 + * @endif + */ +typedef enum { + /** + * @if English + * 0：(default) Prioritizes the system performance. The SDK chooses the dimension and frame rate of the local camera capture + * closest to those set by setVideoConfig. + * @endif + * @if Chinese + * （默认）优先保证设备性能。SDK 根据设备性能，参考用户在 setVideoConfig + * 中设置编码器的分辨率和帧率，选择最接近的摄像头输出参数。在这种情况下，预览质量接近于编码器的输出质量。 + * @endif + */ + kNERtcCameraOutputDefault = 0, + /** + * @if English + * Prioritizes the local preview quality. The SDK chooses higher camera output parameters to improve the local video preview + * quality. This option requires extra CPU and RAM usage for video pre-processing. + * @endif + * @if Chinese + * 优先保证视频预览质量。SDK 自动设置画质较高的摄像头输出参数，提高预览画面质量。此时会消耗更多的 CPU 及内存做视频前处理。 + * @endif + */ + kNERtcCameraOutputQuality = 1, + /** + * @if English + * Allows you to customize the width and height of the video image captured by the local camera. + * @endif + * @if Chinese + * 采用用户自定义设置的摄像头输出参数。此时用户可以通过 NERtcCameraCaptureConfig 中的 captureWidth 和 captureHeight + * 设置本地摄像头采集的视频宽高。 + * @endif + */ + kNERtcCameraOutputManual = 2, +} NERtcCameraPreference; + +/** + * @if English + * The camera capturer configuration. + * @endif + * @if Chinese + * 摄像头采集配置。 + * @endif + */ +struct NERtcCameraCaptureConfig { + /** + * @if English + * The camera capture preference. + * @endif + * @if Chinese + * 摄像头采集偏好。 + * @endif + */ + NERtcCameraPreference preference; + /** + * @if English + * The width (px) of the video image captured by the local camera. + *
The video encoding resolution is expressed in width x height. It is used to set the video encoding resolution and + * measure the encoding quality. + * - capture_width: the pixels of the video frame on the horizontal axis, that is, the custom width. + * - capture_height： the pixels of the video frame on the horizontal axis, that is, the custom height. + * @note + * - To customize the width of the video image, set preference as kNERtcCameraOutputManual first, and then use captureWidth + * and captureHeight. + * - In manual mode, if the specified collection size is smaller than the encoding size, the encoding parameters will be + * aligned down to the collection size range. + * @endif + * @if Chinese + * 本地采集的视频宽度，单位为 px。 + *
视频编码分辨率以宽 x 高表示，用于设置视频编码分辨率，以衡量编码质量。 + * - captureWidth 表示视频帧在横轴上的像素，即自定义宽。 + * - captureHeight 表示视频帧在横轴上的像素，即自定义高。 + * @note + * - 如果您需要自定义本地采集的视频尺寸，请先将 preference 设为 kNERtcCameraOutputManual，再通过 captureWidth 和 captureHeight + * 设置采集的视频宽度。 + * - 手动模式下，如果指定的采集宽高小于编码宽高，编码参数会被下调对齐到采集的尺寸范围内。 + * @endif + */ + int capture_width; + /** + * @if English + * The height (px) of the video image captured by the local camera. + *
The video encoding resolution is expressed in width x height. It is used to set the video encoding resolution and + * measure the encoding quality. + * - capture_width: the pixels of the video frame on the horizontal axis, that is, the custom width. + * - capture_height： the pixels of the video frame on the horizontal axis, that is, the custom height. + * @note + * - To customize the width of the video image, set preference as CAPTURE_PREFERENCE_MANUAL first, and then use captureWidth + * and captureHeight. + * - In manual mode, if the specified collection size is smaller than the encoding size, the encoding parameters will be + * aligned down to the collection size range. + * @endif + * @if Chinese + * 本地采集的视频高度，单位为 px。 + *
视频编码分辨率以宽 x 高表示，用于设置视频编码分辨率，以衡量编码质量。 + * - captureWidth 表示视频帧在横轴上的像素，即自定义宽。 + * - captureHeight 表示视频帧在横轴上的像素，即自定义高。 + * @note + * - 如果您需要自定义本地采集的视频尺寸，请先将 preference 设为 kNERtcCameraOutputManual，再通过 captureWidth 和 captureHeight + * 设置采集的视频宽度。 + * - 手动模式下，如果指定的采集宽高小于编码宽高，编码参数会被下调对齐到采集的尺寸范围内。 + * @endif + */ + int capture_height; +}; + +/** + * @if English + * Video encoding configuration. The resolution used to measure encoding quality. + * @note kNERtcVideoProfileFake: + * - The peer sends a 16*16 fakeVideo (SEI delivered in audio-only streams), which is an internal behavior of the SDK. The view + * is not displayed at this time (the client receives only black frames). + * - Therefore, this setting is not actively applied. If you select the setting, the SDK applies the setting to the standard. + * @endif + * @if Chinese + * 视频编码配置。用于衡量编码质量。 + * @note + * kNERtcVideoProfileFake: + * - 表示对端发送 16*16 的 fakeVideo，即纯音频下发送 SEI，属于 SDK 内部行为，此时收到的是黑色帧，不需要显示 view。 + * - 因此这个档位不主动使用，属于被动接受，如果主动使用，SDK 内部会按 standard 处理。 + * @endif + */ +typedef enum { + /** + * @if English + * LD160x90/120, 15fps + * @endif + * @if Chinese + * 普清（160x90/120, 15fps） + * @endif + */ + kNERtcVideoProfileLowest = 0, + /** + * @if English + * LD 320x180/240, 15fps + * @endif + * @if Chinese + * 标清（320x180/240, 15fps） + * @endif + */ + kNERtcVideoProfileLow = 1, + /** + * @if English + * SD 640x360/480, 30fps + * @endif + * @if Chinese + * 高清（640x360/480, 30fps） + * @endif + */ + kNERtcVideoProfileStandard = 2, + /** + * @if English + * HD (1280 x 720, 30 fps) + * @endif + * @if Chinese + * 超清（1280x720, 30fps） + * @endif + */ + kNERtcVideoProfileHD720P = 3, + /** + * @if English + * 1080p (1920x1080, 30fps) + * @endif + * @if Chinese + * 1080P（1920x1080, 30fps） + * @endif + */ + kNERtcVideoProfileHD1080P = 4, + /** + * @if English + * None + * @endif + * @if Chinese + * 无效果。 + * @endif + */ + kNERtcVideoProfileNone = 5, + kNERtcVideoProfileMAX = kNERtcVideoProfileHD1080P, + /** + * @if English + * FakeVideo logo, only displayed in the callback. Do not use the setting. Otherwise, the SDK applies the logo based on + * kNERtcVideoProfileStandard.
When the remote client sends the SEI in the audio-only state, the local client receives the + * message returned by the onUserVideoStart callback from the remote client. The maxProfile parameter is + * kNERtcVideoProfileFake, which indicates that the remote client sends a 16*16 FakeVideo. At this time, if the local client + * needs to receive the remote SEI, you only need to subscribe to the remote video, without setting the remote canvas. + * @endif + * @if Chinese + * FakeVideo标识，仅在回调中显示。请勿主动设置，否则 SDK 会按照 STANDARD 处理。 + *
当远端在纯音频状态发送 SEI 时，本端将会收到远端的onUserVideoStart回调，其中 max_profile 参数为 kNERtcVideoProfileFake + * ， 表示对端发送 16*16 的 FakeVideo，此时如果本端需要接收远端的SEI信息，只需要订阅一下远端的视频即可，无须设置远端画布。 + * @endif + */ + kNERtcVideoProfileFake = 6, +} NERtcVideoProfileType; + +/** + * @if English + * The video stream type. + * @endif + * @if Chinese + * 视频流类型。 + * @note 大流的分辨率及参数配置高，小流的分辨率及参数配置低。 + * @endif + */ +typedef enum { + /** + * @if English + * The default high-resolution stream. + * @endif + * @if Chinese + * 默认大流 + * @endif + */ + kNERtcRemoteVideoStreamTypeHigh = 0, + /** + * @if English + * The low-resolution stream + * @endif + * @if Chinese + * 小流 + * @endif + */ + kNERtcRemoteVideoStreamTypeLow = 1, + /** + * @if English + * Unsubscribed. + * @endif + * @if Chinese + * 不订阅 + * @endif + */ + kNERtcRemoteVideoStreamTypeNone = 2, +} NERtcRemoteVideoStreamType; + +/** + * @if English + * Audio device type. + * @endif + * @if Chinese + * 音频设备类型。 + * @endif + */ +typedef enum { + /** + * @if English + * Unknown audio device. + * @endif + * @if Chinese + * 未知音频设备 + * @endif + */ + kNERtcAudioDeviceUnknown = 0, + /** + * @if English + * Audio capture device. + * @endif + * @if Chinese + * 音频采集设备 + * @endif + */ + kNERtcAudioDeviceRecord, + /** + * @if English + * Audio playback device. + * @endif + * @if Chinese + * 音频播放设备 + * @endif + */ + kNERtcAudioDevicePlayout, +} NERtcAudioDeviceType; + +/** + * @if English + * Audio device status types. + * @endif + * @if Chinese + * 音频设备类型状态。 + * @endif + */ +typedef enum { + /** + * @if English + * The audio device is activated. + * @endif + * @if Chinese + * 音频设备已激活 + * @endif + */ + kNERtcAudioDeviceActive = 0, + /** + * @if English + * The audio device is not activated. + * @endif + * @if Chinese + * 音频设备未激活 + * @endif + */ + kNERtcAudioDeviceUnactive, +} NERtcAudioDeviceState; + +/** + * @if English + * Audio device types. + *@endif + *@if Chinese + * 音频设备连接类型。 + * @endif + */ +typedef enum { + /** + * @if English + * Unknown device. + * @endif + * @if Chinese + * 未知设备 + * @endif + */ + kNERtcAudioDeviceTransportTypeUnknown = 0, + /** + * @if English + * Bluetooth device. + * @endif + * @if Chinese + * 蓝牙设备 + * @endif + */ + kNERtcAudioDeviceTransportTypeBluetooth = 1, + /** + * @if English + * Bluetooth stereo device. + * @endif + * @if Chinese + * 蓝牙立体声设备 + * @endif + */ + kNERtcAudioDeviceTransportTypeBluetoothA2DP = 2, + /** + * @if English + * Bluetooth low energy device. + * @endif + * @if Chinese + * 蓝牙低功耗设备 + * @endif + */ + kNERtcAudioDeviceTransportTypeBluetoothLE = 3, + /** + * @if English + * USB device. + * @endif + * @if Chinese + * USB设备 + * @endif + */ + kNERtcAudioDeviceTransportTypeUSB = 4, + /** + * @if English + * HDMI device. + * @endif + * @if Chinese + * HDMI设备 + * @endif + */ + kNERtcAudioDeviceTransportTypeHDMI = 5, + /** + * @if English + * Built-in device. + * @endif + * @if Chinese + * 内置设备 + * @endif + */ + kNERtcAudioDeviceTransportTypeBuiltIn = 6, + /** + * @if English + * Thunderbolt interface device. + * @endif + * @if Chinese + * 雷电接口设备 + * @endif + */ + kNERtcAudioDeviceTransportTypeThunderbolt = 7, + /** + * @if English + * AirPlay device. + * @endif + * @if Chinese + * AirPlay设备 + * @endif + */ + kNERtcAudioDeviceTransportTypeAirPlay = 8, + /** + * @if English + * Virtual device. + * @endif + * @if Chinese + * 虚拟设备 + * @endif + */ + kNERtcAudioDeviceTransportTypeVirtual = 9, + /** + * @if English + * Other devices. + * @endif + * @if Chinese + * 其他设备 + * @endif + */ + kNERtcAudioDeviceTransportTypeOther = 10, +} NERtcAudioDeviceTransportType; + +/** + * @if English + * Camera device type. + * @endif + * @if Chinese + * 摄像头设备链接类型。 + * @endif + */ +typedef enum { + /** + * @if English + * Unknown device. + * @endif + * @if Chinese + * 未知设备 + * @endif + */ + kNERtcVideoDeviceTransportTypeUnknown = 0, + /** + * @if English + * USB设备 + * @endif + * @if Chinese + * USB device. + * @endif + */ + kNERtcVideoDeviceTransportTypeUSB = 1, + /** + * @if English + * Virtual device. + * @endif + * @if Chinese + * 虚拟设备 + * @endif + */ + kNERtcVideoDeviceTransportTypeVirtual = 2, + /** + * @if English + * Other device. + * @endif + * @if Chinese + * 其他设备 + * @endif + */ + kNERtcVideoDeviceTransportTypeOther = 3, +} NERtcVideoDeviceTransportType; + +/** + * @if English + * Device details. + * @endif + * @if Chinese + * 设备详细信息。 + * @endif + */ +struct NERtcDeviceInfo { + /** + * @if English + * Device ID + * @endif + * @if Chinese + * 设备ID + * @endif + */ + char device_id[kNERtcMaxDeviceIDLength]; + /** + * @if English + * Device name + * @endif + * @if Chinese + * 设备名称 + * @endif + */ + char device_name[kNERtcMaxDeviceNameLength]; + /** + * @if English + * Device types, including NERtcAudioDeviceTransportType and NERtcVideoDeviceTransportType + * @endif + * @if Chinese + * 设备链接类型，分别指向NERtcAudioDeviceTransportType及NERtcVideoDeviceTransportType + * @endif + */ + int transport_type; + /** + * @if English + * Determines whether it is a non-recommended device + * @endif + * @if Chinese + * 是否是不推荐设备 + * @endif + */ + bool suspected_unavailable; + /** + * @if English + * Determines whether it is the system default device + * @endif + * @if Chinese + * 是否是系统默认设备 + * @endif + */ + bool system_default_device; +}; + +/** + * @if English + * Video device types. + * @endif + * @if Chinese + * 视频设备类型。 + * @endif + */ +typedef enum { + /** + * @if English + * Unknown video device. + * @endif + * @if Chinese + * Video capture device. + * @endif + */ + kNERtcVideoDeviceUnknown = 0, + /** + * @if English + * Video capture device. + * @endif + * @if Chinese + * 视频采集设备 + * @endif + */ + kNERtcVideoDeviceCapture, +} NERtcVideoDeviceType; + +/** + * @if English + * Video device status types. + * @endif + * @if Chinese + * 视频设备类型状态。 + * @endif + */ +typedef enum { + /** + * @if English + * The video device is added. + * @endif + * @if Chinese + * 视频设备已添加 + * @endif + */ + kNERtcVideoDeviceAdded = 0, + /** + * @if English + * The video device is removed. + * @endif + * @if Chinese + * 视频设备已拔除 + * @endif + */ + kNERtcVideoDeviceRemoved, +} NERtcVideoDeviceState; + +/** + * @if English + * @enum NERtcVideoScalingMode Set the video scaling mode. + * @endif + * @if Chinese + * @enum NERtcVideoScalingMode 设置视频缩放模式。 + * @endif + */ +typedef enum { + /** + * @if English + * 0: adaptive to the video. The video size is scaled proportionally. All video content is prioritized for display. If the + * video size does not match the display window size, the unfilled area of the window is be filled with the background color. + * @endif + * @if Chinese + * 0：适应视频，视频尺寸等比缩放。优先保证视频内容全部显示。若视频尺寸与显示视窗尺寸不一致，视窗未被填满的区域填充背景色。 + * @endif + */ + kNERtcVideoScaleFit = 0, + /** + * @if English + * 1: The video size is scaled non-proportionally. Ensure that all video content is displayed and the window is filled. + * @endif + * @if Chinese + * 1：视频尺寸非等比缩放。保证视频内容全部显示，且填满视窗。 + * @endif + */ + kNERtcVideoScaleFullFill = 1, + /** + * @if English + * 2: adaptive to the area. The video size is scaled proportionally. Ensure that all areas are filled, and the extra part of + * the video will be cropped. + * @endif + * @if Chinese + * 2：适应区域，视频尺寸等比缩放。保证所有区域被填满，视频超出部分会被裁剪。 + * @endif + */ + kNERtcVideoScaleCropFill = 2, +} NERtcVideoScalingMode; + +/** + * @if English + * @enum NERtcVideoMirrorMode Video mirror mode. + * @endif + * @if Chinese + * @enum NERtcVideoMirrorMode 视频镜像模式。 + * @endif + */ +typedef enum { + /** + * @if English + * 0: The mirror mode is enabled in Windows and macOS SDKs. + * @endif + * @if Chinese + * 0: Windows/macOS SDK 启用镜像模式。 + * @endif + */ + kNERtcVideoMirrorModeAuto = 0, + /** + * @if English + * 1: Enables mirror mode. + * @endif + * @if Chinese + * 1: 启用镜像模式。 + * @endif + */ + kNERtcVideoMirrorModeEnabled = 1, + /** + * @if English + * 2: Disables mirroring mode (default). + * @endif + * @if Chinese + * 2: （默认）关闭镜像模式。 + * @endif + */ + kNERtcVideoMirrorModeDisabled = 2, +} NERtcVideoMirrorMode; + +/** + * @if English + * @enum NERtcVideoOutputOrientationMode The video orientation mode. + * @endif + * @if Chinese + * @enum NERtcVideoOutputOrientationMode 视频旋转的方向模式。 + * @endif + */ +typedef enum { + + /** + * @if English + * (default) The direction of the video output by the SDK in this mode is consistent with the direction of the captured video. + * The receiver rotates the video based on the received video rotation information.
This mode is suitable for scenarios + * where the receiver can adjust the video direction. + * - If the captured video is in landscape mode, the output video is also in landscape mode. + * - If the captured video is in portrait mode, the output video is also in portrait mode. + * @endif + * @if Chinese + * （默认）该模式下 SDK 输出的视频方向与采集到的视频方向一致。接收端会根据收到的视频旋转信息对视频进行旋转。 + *
该模式适用于接收端可以调整视频方向的场景。 + * - 如果采集的视频是横屏模式，则输出的视频也是横屏模式。 + * - 如果采集的视频是竖屏模式，则输出的视频也是竖屏模式。 + * @endif + */ + kNERtcVideoOutputOrientationModeAdaptative = 0, + + /** + * @if English + * In this mode, the SDK always outputs videos in landscape mode. If the captured video is in portrait mode, the video encoder + * crops the video.
This mode is suitable for scenes where the receiver cannot adjust the video direction, such as CDN + * relayed streaming. + * @endif + * @if Chinese + * 该模式下 SDK 固定输出横屏模式的视频。如果采集到的视频是竖屏模式，则视频编码器会对其进行裁剪。 + *
该模式适用于接收端无法调整视频方向的场景，例如旁路推流。 + * @endif + */ + kNERtcVideoOutputOrientationModeFixedLandscape = 1, + + /** + * @if English + * In this mode, the SDK always outputs videos in portrait mode. If the captured video is in landscape mode, the video encoder + * crops the video.
This mode is suitable for scenes where the receiver cannot adjust the video direction, such as CDN + * relayed streaming. + * @endif + * @if Chinese + * 该模式下 SDK 固定输出竖屏模式的视频，如果采集到的视频是横屏模式，则视频编码器会对其进行裁剪。 + *
该模式适用于接收端无法调整视频方向的场景，例如旁路推流。 + * @endif + */ + kNERtcVideoOutputOrientationModeFixedPortrait = 2, + +} NERtcVideoOutputOrientationMode; +/** + * @if English + * The state of network connection + * @endif + * @if Chinese + * 连接状态 + * @endif + */ +typedef enum { + /** + * @if English + * The client is disconnected. + * @endif + * @if Chinese + * 未加入房间。 + * @endif + */ + kNERtcConnectionStateDisconnected = 1, + /** + * @if English + * The client is connecting to the room server. + * @endif + * @if Chinese + * 正在加入房间。 + * @endif + */ + kNERtcConnectionStateConnecting = 2, + /** + * @if English + * The client is connected to the room server. + * @endif + * @if Chinese + * 加入房间成功。 + * @endif + */ + kNERtcConnectionStateConnected = 3, + /** + * @if English + * The client is reconnecting to the room server. + * @endif + * @if Chinese + * 正在尝试重新加入房间。 + * @endif + */ + kNERtcConnectionStateReconnecting = 4, + /** + * @if English + * The client fails to connect to the room server. + * @endif + * @if Chinese + * 加入房间失败。 + * @endif + */ + kNERtcConnectionStateFailed = 5, +} NERtcConnectionStateType; + +/** + * @if English + * The reason for the connection state change. + * @endif + * @if Chinese + * 连接状态变更原因 + * @endif + */ +typedef enum { + /** + * @if English + * kNERtcConnectionStateDisconnected The client leaves the room. + * @endif + * @if Chinese + * kNERtcConnectionStateDisconnected 离开房间 + * @endif + */ + kNERtcReasonConnectionChangedLeaveChannel = 1, + /** + * @if English + * kNERtcConnectionStateDisconnected The room is closed. + * @endif + * @if Chinese + * kNERtcConnectionStateDisconnected 房间被关闭 + * @endif + */ + kNERtcReasonConnectionChangedChannelClosed = 2, + /** + * @if English + * kNERtcConnectionStateDisconnected The user is removed from the room. + * @endif + * @if Chinese + * kNERtcConnectionStateDisconnected 用户被踢 + * @endif + */ + kNERtcReasonConnectionChangedBeKicked = 3, + /** + * @if English + * kNERtcConnectionStateDisconnected The service times out. + * @endif + * @if Chinese + * kNERtcConnectionStateDisconnected 服务超时 + * @endif + */ + kNERtcReasonConnectionChangedTimeOut = 4, + /** + * @if English + * kNERtcConnectionStateConnecting The user joins the room. + * @endif + * @if Chinese + * kNERtcConnectionStateConnected 加入房间 + * @endif + */ + kNERtcReasonConnectionChangedJoinChannel = 5, + /** + * @if English + * kNERtcConnectionStateConnected The user has joined the room. + * @endif + * @if Chinese + * kNERtcConnectionStateConnected 加入房间成功 + * @endif + */ + kNERtcReasonConnectionChangedJoinSucceed = 6, + /** + * @if English + * kNERtcConnectionStateConnected The user rejoins the room successfully (reconnection). + * @endif + * @if Chinese + * kNERtcConnectionStateConnected 重新加入房间成功（重连） + * @endif + */ + kNERtcReasonConnectionChangedReJoinSucceed = 7, + /** + * @if English + * kNERtcConnectionStateReconnecting The media stream gets disconnected. + * @endif + * @if Chinese + * kNERtcConnectionStateReconnecting 媒体连接断开 + * @endif + */ + kNERtcReasonConnectionChangedMediaConnectionDisconnected = 8, + /** + * @if English + * kNERtcConnectionStateReconnecting The signaling channel gets disconnected. + * @endif + * @if Chinese + * kNERtcConnectionStateReconnecting 信令连接断开 + * @endif + */ + kNERtcReasonConnectionChangedSignalDisconnected = 9, + /** + * @if English + * kNERtcConnectionStateFailed The request to join the room fails. + * @endif + * @if Chinese + * kNERtcConnectionStateFailed 请求房间失败 + * @endif + */ + kNERtcReasonConnectionChangedRequestChannelFailed = 10, + /** + * @if English + * kNERtcConnectionStateFailed The user fails to join the room. + * @endif + * @if Chinese + * kNERtcConnectionStateFailed 加入房间失败 + * @endif + */ + kNERtcReasonConnectionChangedJoinChannelFailed = 11, + /** + * @if English + * kNERtcConnectionStateReconnecting The server IP is reallocated. + * @endif + * @if Chinese + * kNERtcConnectionStateReconnecting 重新分配了服务端IP + * @endif + */ + kNERtcReasonConnectionChangedReDispatch = 12, + /** + * @if English + * Start connecting to server using the cloud proxy. + * @endif + * @if Chinese + * 开始使用云代理进行连接。 + * @endif + */ + kNERtcReasonConnectionChangedSettingProxyServer = 13 +} NERtcReasonConnectionChangedType; + +/** + * @if English + * Audio volume information. An array that contains the user ID and volume information of each speaker. + * @endif + * @if Chinese + * 声音音量信息。一个数组，包含每个说话者的用户 ID 和音量信息。 + * @endif + */ +struct NERtcAudioVolumeInfo { + /** + * @if English + * The user ID of the speaker. If the returned uid is 0, the user refers to the local user by default. + * @endif + * @if Chinese + * 说话者的用户 ID。如果返回的 uid 为 0，则默认为本地用户。 + * @endif + */ + uid_t uid; + /** + * @if English + * The speaker's volume, the value range is from 0 (lowest) to 100 (highest). + * @endif + * @if Chinese + * 说话者的音量，范围为 0（最低）- 100（最高）。 + * @endif + */ + unsigned int volume; + /** + * @if Chinese + * 远端用户音频辅流的音量，取值范围为 [0,100] 。 + *
如果 sub_stream_volume 为 0，表示该用户未发布音频辅流或音频辅流没有音量。 + * @endif + */ + unsigned int sub_stream_volume; +}; + +/** + * @if English + * Stats related to calls. + * @endif + * @if Chinese + * 通话相关的统计信息。 + * @endif + */ +struct NERtcStats { + /** + * @if English + * The CPU usage occupied by the app (%). + * @endif + * @if Chinese + * 当前 App 的 CPU 使用率 (%)。 + * @endif + */ + uint32_t cpu_app_usage; + /** + * @if English + * The CPU idle rate of the current system (%). + * @endif + * @if Chinese + * 当前系统的 CPU 空闲率 (%)。 + * @endif + */ + uint32_t cpu_idle_usage; + /** + * @if English + * The current system CPU usage (%). + * @endif + * @if Chinese + * 当前系统的 CPU 使用率 (%)。 + * @endif + */ + uint32_t cpu_total_usage; + /** + * @if English + * The current memory usage occupied by the app (%). + * @endif + * @if Chinese + * 当前App的内存使用率 (%)。 + * @endif + */ + uint32_t memory_app_usage; + /** + * @if English + * The current system memory usage (%). + * @endif + * @if Chinese + * 当前系统的内存使用率 (%)。 + * @endif + */ + uint32_t memory_total_usage; + /** + * @if English + * The current memory used by the app (KB). + * @endif + * @if Chinese + * 当前App的内存使用量 (KB)。 + * @endif + */ + uint32_t memory_app_kbytes; + /** + * @if English + * Call duration in seconds. + * @endif + * @if Chinese + * 通话时长（秒）。 + * @endif + */ + int total_duration; + /** + * @if English + * The number of bytes sent. This is the cumulative value. (bytes) + * @endif + * @if Chinese + * 发送字节数，累计值。(bytes) + * @endif + */ + uint64_t tx_bytes; + /** + * @if English + * The number of bytes received. This is the cumulative value. (bytes) + * @endif + * @if Chinese + * 接收字节数，累计值。(bytes) + * @endif + */ + uint64_t rx_bytes; + /** + * @if English + * The number of audio bytes sent. This is the cumulative value. (bytes) + * @endif + * @if Chinese + * 音频发送字节数，累计值。(bytes) + * @endif + */ + uint64_t tx_audio_bytes; + /** + * @if English + * The number of video bytes sent. This is the cumulative value. (bytes) + * @endif + * @if Chinese + * 视频发送字节数，累计值。(bytes) + * @endif + */ + uint64_t tx_video_bytes; + /** + * @if English + * The number of audio bytes received. This is the cumulative value. (bytes) + * @endif + * @if Chinese + * 音频接收字节数，累计值。(bytes) + * @endif + */ + uint64_t rx_audio_bytes; + /** + * @if English + * The number of video bytes received. This is the cumulative value. (bytes) + * @endif + * @if Chinese + * 视频接收字节数，累计值。(bytes) + * @endif + */ + uint64_t rx_video_bytes; + /** + * @if English + * Audio bitrate for publishing. (kbps) + * @endif + * @if Chinese + * 音频发送码率。(kbps) + * @endif + */ + int tx_audio_kbitrate; + /** + * @if English + * Audio bitrate for subscribed streams. (kbps) + * @endif + * @if Chinese + * 音频接收码率。(kbps) + * @endif + */ + int rx_audio_kbitrate; + /** + * @if English + * Video bitrate for publishing. (kbps) + * @endif + * @if Chinese + * 视频发送码率。(kbps) + * @endif + */ + int tx_video_kbitrate; + /** + * @if English + * Video bitrate for subscribed streams. (kbps) + * @endif + * @if Chinese + * 视频接收码率。(kbps) + * @endif + */ + int rx_video_kbitrate; + /** + * @if English + * Average uplink round trip time. (ms) + * @endif + * @if Chinese + * 上行平均往返时延rtt(ms) + * @endif + */ + int up_rtt; + /** + * @if English + * Average downlink round-trip time. (ms) + * @endif + * @if Chinese + * 下行平均往返时延rtt(ms) + * @endif + */ + int down_rtt; + /** + * @if English + * The actual uplink packet loss rate of the local audio stream. (%) + * @endif + * @if Chinese + * 本地上行音频实际丢包率。(%) + * @endif + */ + int tx_audio_packet_loss_rate; + /** + * @if English + * The actual uplink packet loss rate of the local video stream. (%) + * @endif + * @if Chinese + * 本地上行视频实际丢包率。(%) + * @endif + */ + int tx_video_packet_loss_rate; + /** + * @if English + * The actual number of lost packets for local upstream audio. + * @endif + * @if Chinese + * 本地上行音频实际丢包数。 + * @endif + */ + int tx_audio_packet_loss_sum; + /** + * @if English + * Actual number of lost packets for local upstream video. + * @endif + * @if Chinese + * 本地上行视频实际丢包数。 + * @endif + */ + int tx_video_packet_loss_sum; + /** + * @if English + * Local upstream audio jitter calculation. (ms) + * @endif + * @if Chinese + * 本地上行音频抖动计算。(ms) + * @endif + */ + int tx_audio_jitter; + /** + * @if English + * Local uplink video jitter calculation. (ms) + * @endif + * @if Chinese + * 本地上行视频抖动计算。(ms) + * @endif + */ + int tx_video_jitter; + /** + * @if English + * Actual packet loss of local downlink audio stream. (%) + * @endif + * @if Chinese + * 本地下行音频实际丢包率。(%) + * @endif + */ + int rx_audio_packet_loss_rate; + /** + * @if English + * Actual local downstream video packet loss rate. (%) + * @endif + * @if Chinese + * 本地下行视频实际丢包率。(%) + * @endif + */ + int rx_video_packet_loss_rate; + /** + * @if English + * Actual number of lost packets for local downstream audio. + * @endif + * @if Chinese + * 本地下行音频实际丢包数。 + * @endif + */ + int rx_audio_packet_loss_sum; + /** + * @if English + * Actual number of lost packets for local downstream video. + * @endif + * @if Chinese + * 本地下行视频实际丢包数。 + * @endif + */ + int rx_video_packet_loss_sum; + /** + * @if English + * Local downstream audio jitter calculation. (ms) + * @endif + * @if Chinese + * 本地下行音频抖动计算。(ms) + * @endif + */ + int rx_audio_jitter; + /** + * @if English + * Local downstream video jitter calculation. (ms) + * @endif + * @if Chinese + * 本地下行视频抖动计算。(ms) + * @endif + */ + int rx_video_jitter; +}; + +/** + * @if English + * Stats of each local video stream. + * @endif + * @if Chinese + * 本地视频单条流上传统计信息。 + * @endif + */ +struct NERtcVideoLayerSendStats { + /** + * @if English + * Stream type: 1. mainstream. 2. substream. + * @endif + * @if Chinese + * 流类型： 1、主流，2、辅流。 + * @endif + */ + int layer_type; + /** + * @if English + * Video stream width (pixels). + * @endif + * @if Chinese + * 视频流宽（像素）。 + * @endif + */ + int width; + /** + * @if English + * Video stream height (pixels). + * @endif + * @if Chinese + * 视频流高（像素）。 + * @endif + */ + int height; + /** + * @if English + * @endif + * @if Chinese + * 视频采集宽（像素）。 + * @endif + */ + int capture_width; + /** + * @if English + * @endif + * @if Chinese + * 视频采集高（像素）。 + * @endif + */ + int capture_height; + /** + * @if English + * Video capture frame rate. + * @endif + * @if Chinese + * 视频采集帧率。 + * @endif + */ + int capture_frame_rate; + /** + * @if English + * Video rendering frame rate. + * @endif + * @if Chinese + * 视频渲染帧率。 + * @endif + */ + int render_frame_rate; + /** + * @if English + * Encoding frame rate. + * @endif + * @if Chinese + * 编码帧率。 + * @endif + */ + int encoder_frame_rate; + /** + * @if English + * Publishing frame rate. + * @endif + * @if Chinese + * 发送帧率。 + * @endif + */ + int sent_frame_rate; + /** + * @if English + * Publishing bitrate(kbps). + * @endif + * @if Chinese + * 发送码率(Kbps)。 + * @endif + */ + int sent_bitrate; + /** + * @if English + * Encoder expected bitrate (kbps). + * @endif + * @if Chinese + * 编码器目标码率(Kbps)。 + * @endif + */ + int target_bitrate; + /** + * @if English + * Encoder actual bitrate (kbps). + * @endif + * @if Chinese + * 编码器实际编码码率(Kbps)。 + * @endif + */ + int encoder_bitrate; + /** + * @if English + * The name of the video encoder. + * @endif + * @if Chinese + * 视频编码器名字。 + * @endif + */ + char codec_name[kNERtcMaxDeviceNameLength]; +}; + +/** + * @if English + * The stats of the uplink local video stream. + * @endif + * @if Chinese + * 本地视频流上传统计信息。 + * @endif + */ +struct NERtcVideoSendStats { + /** + * @if English + * Video stream information array. + * @endif + * @if Chinese + * 视频流信息数组。 + * @endif + */ + NERtcVideoLayerSendStats* video_layers_list; + /** + * @if English + * The number of video streams. + * @endif + * @if Chinese + * 视频流条数。 + * @endif + */ + int video_layers_count; +}; + +/** + * @if English + * The stats of each remote video stream. + * @endif + * @if Chinese + * 远端视频单条流的统计信息。 + * @endif + */ +struct NERtcVideoLayerRecvStats { + /** + * @if English + * Stream type: 1. mainstream. 2. substream. + * @endif + * @if Chinese + * 流类型： 1、主流，2、辅流。 + * @endif + */ + int layer_type; + /** + * @if English + * Video stream width (pixels). + * @endif + * @if Chinese + * 视频流宽（像素）。 + * @endif + */ + int width; + /** + * @if English + * Video stream height (pixels). + * @endif + * @if Chinese + * 视频流高（像素）。 + * @endif + */ + int height; + /** + * @if English + * The bitrate of the received stream (kbps). + * @endif + * @if Chinese + * 接收到的码率(Kbps)。 + * @endif + */ + int received_bitrate; + /** + * @if English + * The frame rate of the received stream (fps). + * @endif + * @if Chinese + * 接收到的帧率 (fps)。 + * @endif + */ + int received_frame_rate; + /** + * @if English + * Decoding frame rate (fps). + * @endif + * @if Chinese + * 解码帧率 (fps)。 + * @endif + */ + int decoder_frame_rate; + /** + * @if English + * Rendering frame rate (fps). + * @endif + * @if Chinese + * 渲染帧率 (fps)。 + * @endif + */ + int render_frame_rate; + /** + * @if English + * Downlink packet loss rate (%). + * @endif + * @if Chinese + * 下行丢包率(%)。 + * @endif + */ + int packet_loss_rate; + /** + * @if English + * The downlink video freeze cumulative time (ms). + * @endif + * @if Chinese + * 用户的下行视频卡顿累计时长(ms)。 + * @endif + */ + int total_frozen_time; + /** + * @if English + * The average freeze rate of the user's downlink video stream (%). + * @endif + * @if Chinese + * 用户的下行视频平均卡顿率(%)。 + * @endif + */ + int frozen_rate; + /** + * @if English + * The codec name. + * @endif + * @if Chinese + * 视频解码器名字。 + * @endif + */ + char codec_name[kNERtcMaxDeviceNameLength]; +}; + +/** + * @if English + * Remote video stream stats. + * @endif + * @if Chinese + * 远端视频流的统计信息。 + * @endif + */ +struct NERtcVideoRecvStats { + /** + * @if English + * The user ID used to identify the video stream. + * @endif + * @if Chinese + * 用户 ID，指定是哪个用户的视频流。 + * @endif + */ + uid_t uid; + /** + * @if English + * Video stream information array. + * @endif + * @if Chinese + * 视频流信息数组。 + * @endif + */ + NERtcVideoLayerRecvStats* video_layers_list; + /** + * @if English + * The number of video streams. + * @endif + * @if Chinese + * 视频流条数。 + * @endif + */ + int video_layers_count; +}; + +/** + * @if English + * Audio stream type. + * @endif + * @if Chinese + * 音频流类型。 + * @endif + */ +typedef enum{ + /** + * @if English + * Main stream. + * @endif + * @if Chinese + * 主流。 + * @endif + */ + kNERtcAudioStreamTypeMain = 0, + + /** + * @if English + * Substream. + * @endif + * @if Chinese + * 辅流。 + * @endif + */ + kNERtcAudioStreamTypeSub = 1, +}NERtcAudioStreamType; + +struct NERtcAudioLayerSendStats { + /** + * @if English + * Audio stream tyepe. + * @endif + * @if Chinese + * 音频流通道类型。 + * @endif + */ + NERtcAudioStreamType stream_type; + /** + * @if English + * The number of channels currently collected. + * @endif + * @if Chinese + * 当前采集声道数。 + * @endif + */ + int num_channels; + /** + * @if English + * The sample rate of local uplink audio stream. + * @endif + * @if Chinese + * 本地上行音频采样率。 + * @endif + */ + int sent_sample_rate; + /** + * @if English + * Publishing bitrate after last report (kbps). + * @endif + * @if Chinese + * （上次统计后）发送码率(Kbps)。 + * @endif + */ + int sent_bitrate; + /** + * @if English + * Audio packet loss rate in a specific time (%). + * @endif + * @if Chinese + * 特定时间内的音频丢包率 (%)。 + * @endif + */ + int audio_loss_rate; + /** + * @if English + * Round trip time. + * @endif + * @if Chinese + * RTT。 + * @endif + */ + int64_t rtt; + /** + * @if English + * Volume range: 0 (lowest) to 100 (highest). + * @endif + * @if Chinese + * 音量，范围为 0（最低）- 100（最高）。 + * @endif + */ + unsigned int volume; + /** + * @if English + * @endif + * @if Chinese + * 采集音量，范围为 0（最低）- 100（最高）。 + * @endif + */ + unsigned int cap_volume; +}; +/** + * @if English + * The local audio stream stats. + * @endif + * @if Chinese + * 本地音频流上传统计信息。 + * @endif + */ +struct NERtcAudioSendStats { + /** + * @if English + * Audio stream information array. + * @endif + * @if Chinese + * 音频流信息数组。 + * @endif + */ + NERtcAudioLayerSendStats* audio_layers_list; + /** + * @if English + * The number of audio streams. + * @endif + * @if Chinese + * 音频流条数。 + * @endif + */ + int audio_layers_count; +}; + +/** + * @if English + * The stats of each remote audio stream. + * @endif + * @if Chinese + * 远端用户单条音频流统计。 + * @endif + */ +struct NERtcAudioLayerRecvStats { + /** + * @if English + * Audio stream type. + * @endif + * @if Chinese + * 音频频流通道类型。 + * @endif + */ + NERtcAudioStreamType stream_type; + /** + * @if English + * The bitrate of the received audio stream after the last report (kbps). + * @endif + * @if Chinese + * （上次统计后）接收到的码率(Kbps)。 + * @endif + */ + int received_bitrate; + /** + * @if English + * The user's downlink audio freeze cumulative time (ms). + * @endif + * @if Chinese + * 用户的下行音频卡顿累计时长(ms)。 + * @endif + */ + int total_frozen_time; + /** + * @if English + * The user's downstream audio average freeze rate (%). + * @endif + * @if Chinese + * 用户的下行音频平均卡顿率(%)。 + * @endif + */ + int frozen_rate; + /** + * @if English + * Audio packet loss rate in a specific time (%). + * @endif + * @if Chinese + * 特定时间内的音频丢包率 (%)。 + * @endif + */ + int audio_loss_rate; + /** + * @if English + * Volume range: 0 (lowest) to 100 (highest). + * @endif + * @if Chinese + * 音量，范围为 0（最低）- 100（最高）。 + * @endif + */ + unsigned int volume; +}; +/** + * @if English + * The stats of the audio stream from a remote user. + * @endif + * @if Chinese + * 远端用户的音频统计。 + * @endif + */ +struct NERtcAudioRecvStats { + /** + * @if English + * The user ID used to identify the audio stream. + * @endif + * @if Chinese + * 用户 ID，指定是哪个用户的音频流。 + * @endif + */ + uid_t uid; + /** + * @if English + * Audio stream information array. + * @endif + * @if Chinese + * 音频流信息数组。 + * @endif + */ + NERtcAudioLayerRecvStats* audio_layers_list; + /** + * @if English + * The number of audio streams. + * @endif + * @if Chinese + * 音频流条数。 + * @endif + */ + int audio_layers_count; +}; + +/** + * @if English + * @enum NERtcNetworkQualityType Network quality type. + * @endif + * @if Chinese + * @enum NERtcNetworkQualityType 网络质量类型。 + * @endif + */ +typedef enum { + /** + * @if English + * 0: Unknown network quality. + * @endif + * @if Chinese + * 0: 网络质量未知。 + * @endif + */ + kNERtcNetworkQualityUnknown = 0, + /** + * @if English + * 1: Excellent network quality. + * @endif + * @if Chinese + * 1: 网络质量极好。 + * @endif + */ + kNERtcNetworkQualityExcellent = 1, + /** + * @if English + * 2: Good network quality is close to the excellent level but has the bitrate is lower an excellent network. + * @endif + * @if Chinese + * 2: 用户主观感觉和 `kNERtcNetworkQualityExcellent` 类似，但码率可能略低于 `kNERtcNetworkQualityExcellent`。 + * @endif + */ + kNERtcNetworkQualityGood = 2, + /** + * @if English + * 3: Poor network does not affect communication. + * @endif + * @if Chinese + * 3: 用户主观感受有瑕疵但不影响沟通。 + * @endif + */ + kNERtcNetworkQualityPoor = 3, + /** + * @if English + * 4: Users can communicate with each other without smoothness. + * @endif + * @if Chinese + * 4: 勉强能沟通但不顺畅。 + * @endif + */ + kNERtcNetworkQualityBad = 4, + /** + * @if English + * 5: The network quality is very poor. Basically users are unable to communicate. + * @endif + * @if Chinese + * 5: 网络质量非常差，基本不能沟通。 + * @endif + */ + kNERtcNetworkQualityVeryBad = 5, + /** + * @if English + * 6: Users are unable to communicate with each other. + * @endif + * @if Chinese + * 6: 完全无法沟通。 + * @endif + */ + kNERtcNetworkQualityDown = 6, +} NERtcNetworkQualityType; + +/** + * @if English + * Network quality stats. + * @endif + * @if Chinese + * 网络质量统计信息。 + * @endif + */ +struct NERtcNetworkQualityInfo { + /** + * @if English + * The user ID used to identify the network quality stats. + * @endif + * @if Chinese + * 用户 ID，指定是哪个用户的网络质量统计。 + * @endif + */ + uid_t uid; + /** + * @if English + * The uplink network quality. For more information, see #NERtcNetworkQualityType. + * @endif + * @if Chinese + * 该用户的上行网络质量，详见 #NERtcNetworkQualityType. + * @endif + */ + NERtcNetworkQualityType tx_quality; + /** + * @if English + * The downlink network quality. For more information, see #NERtcNetworkQualityType. + * @endif + * @if Chinese + * 该用户的下行网络质量，详见 #NERtcNetworkQualityType. + * @endif + */ + NERtcNetworkQualityType rx_quality; +}; + +/** + * @if English + * @enum NERtcVideoCropMode Video cropping mode. + * @endif + * @if Chinese + * @enum NERtcVideoCropMode 视频画面裁剪模式。 + * @endif + */ +typedef enum { + /** + * @if English + * Device Default + * @endif + * @if Chinese + * 设备默认裁剪模式。 + * @endif + */ + kNERtcVideoCropModeDefault = 0, + /** + * @if English + * 16:9 + * @endif + * @if Chinese + * 16:9 + * @endif + */ + kNERtcVideoCropMode16x9 = 1, + /** + * @if English + * 4:3 + * @endif + * @if Chinese + * 4:3 + * @endif + */ + kNERtcVideoCropMode4x3 = 2, + /** + * @if English + * 1:1 + * @endif + * @if Chinese + * 1:1 + * @endif + */ + kNERtcVideoCropMode1x1 = 3, +} NERtcVideoCropMode; + +/** + * @if English + * @enum NERtcVideoFramerateType Video frame rate. + * @endif + * @if Chinese + * @enum NERtcVideoFramerateType 视频帧率。 + * @endif + */ +typedef enum { + /** + * @if English + * default frame rate + * @endif + * @if Chinese + * 默认帧率 + * @endif + */ + kNERtcVideoFramerateFpsDefault = 0, + /** + * @if English + * 7 frames per second + * @endif + * @if Chinese + * 7帧每秒 + * @endif + */ + kNERtcVideoFramerateFps_7 = 7, + /** + * @if English + * 10 frames per second + * @endif + * @if Chinese + * 10帧每秒 + * @endif + */ + kNERtcVideoFramerateFps_10 = 10, + /** + * @if English + * 15 frames per second + * @endif + * @if Chinese + * 15帧每秒 + * @endif + */ + kNERtcVideoFramerateFps_15 = 15, + /** + * @if English + * 24 frames per second + * @endif + * @if Chinese + * 24帧每秒 + * @endif + */ + kNERtcVideoFramerateFps_24 = 24, + /** + * @if English + * 30 frames per second + * @endif + * @if Chinese + * 30帧每秒 + * @endif + */ + kNERtcVideoFramerateFps_30 = 30, + /** + * @if English + * 60 frames per second + * @endif + * @if Chinese + * 60帧每秒 + * @endif + */ + kNERtcVideoFramerateFps_60 = 60, +} NERtcVideoFramerateType; + +/** + * @if English + * @enum NERtcDegradationPreference Video encoding strategy. + * @endif + * @if Chinese + * NERtcDegradationPreference 视频编码策略。 + * @endif + */ +typedef enum { + /** + * @if English + * - By default, adjust the adaptation preference based on scenarios. + * - In communication scenes, select kNERtcDegradationBalanced mode to maintain a balance between the frame rate and video + * quality. + * - In live streaming scenes, select kNERtcDegradationMaintainQuality mode and reduce the frame rate to ensure video quality. + * @endif + * @if Chinese + * - （默认）根据场景模式调整适应性偏好。 + * - 通信场景中，选择kNERtcDegradationBalanced 模式，在编码帧率和视频质量之间保持平衡。 + * - 直播场景中，选择kNERtcDegradationMaintainQuality 模式，降低编码帧率以保证视频质量。 + * @endif + */ + kNERtcDegradationDefault = 0, + /** + * @if English + * Smooth streams come first. Reduce video quality to ensure the frame rate. In a weak network environment, you can reduce the + * video quality to ensure a smooth video playback. In this case, the image quality is reduced and the pictures become + * blurred, but the video can be kept smooth. + * @endif + * @if Chinese + * 流畅优先，降低视频质量以保证编码帧率。在弱网环境下，降低视频清晰度以保证视频流畅，此时画质降低，画面会变得模糊，但可以保持视频流畅。 + * @endif + */ + kNERtcDegradationMaintainFramerate = 1, + /** + * @if English + * Clarity is prioritized. Reduce the frame rate to ensure video quality. In a weak network environment, you can reduce the + * video frame rate to ensure that the video is clear. In this case, a certain amount of freezes may occur at this time. + * @endif + * @if Chinese + * 清晰优先，降低编码帧率以保证视频质量。在弱网环境下，降低视频帧率以保证视频清晰，此时可能会出现一定卡顿。 + * @endif + */ + kNERtcDegradationMaintainQuality = 2, + /** + * @if English + * Maintain a balance between the frame rate and video quality. + * @endif + * @if Chinese + * 在编码帧率和视频质量之间保持平衡。 + * @endif + */ + kNERtcDegradationBalanced = 3, +} NERtcDegradationPreference; + +/** + * @if English + * The video encoding profile configuration. + * @endif + * @if Chinese + * 视频编码属性配置。 + * @endif + */ +struct NERtcVideoConfig { + /** + * @if English + * The resolution of video encoding used to measure encoding quality. For more information, see NERtcVideoProfileType + * @endif + * @if Chinese + * 视频编码的分辨率，用于衡量编码质量。详细信息请参考 NERtcVideoProfileType。 + * @endif + */ + NERtcVideoProfileType max_profile; + /** + * @if English + * Video encoding resolution, an indicator of encoding quality, is represented by width x height. You can select this profile + * or maxProfile.
The width represents the pixels of the video frame on the horizontal axis. You can enter a custom width. + * - If you set the value to a negative number, the maxProfile setting is used. + * - If you need to customize the resolution, set this profile, and maxProfile becomes invalid. + * If the width and height of the custom video input are invalid, the width and height are automatically scaled based on + * maxProfile. + * @endif + * @if Chinese + * 视频编码分辨率，衡量编码质量，以宽x高表示。与maxProfile属性二选一。 + *
width表示视频帧在横轴上的像素，即自定义宽。 + * - 设置为负数时表示采用 max_profile 档位。 + * - 如果需要自定义分辨率场景，则设置此属性，maxProfile属性失效。 + * 自定义视频输入width和height无效，会自动根据 maxProfile 缩放。 + * @endif + */ + uint32_t width; + /** + * @if English + * Video encoding resolution, an indicator of encoding quality, is represented by width x height. You can select this profile + * or maxProfile.
The height represents the pixels of the video frame on the vertical axis. You can enter a custom height. + * - If you set the value to a negative number, the maxProfile setting is used. + * - If you need to customize the resolution, set this profile, and maxProfile becomes invalid. + * If the width and height of the custom video input are invalid, the width and height are automatically scaled based on + * maxProfile. + * @endif + * @if Chinese + * 视频编码分辨率，衡量编码质量，以宽x高表示。与maxProfile属性二选一。 + *
height表示视频帧在纵轴上的像素，即自定义高。 + * - 设置为负数时表示采用 max_profile 档位。 + * - 如果需要自定义分辨率场景，则设置此属性，maxProfile属性失效。 + *
自定义视频输入width和height无效，会自动根据 maxProfile 缩放。 + * @endif + */ + uint32_t height; + /** + * @if English + * Video crop mode, aspect ratio. The default value is kNERtcVideoCropModeDefault. For more information, see + * NERtcVideoCropMode. + * @endif + * @if Chinese + * 视频裁剪模式，宽高比。默认为 kNERtcVideoCropModeDefault。详细信息请参考 NERtcVideoCropMode。 + * @endif + */ + NERtcVideoCropMode crop_mode; + /** + * @if English + * The frame rate of the mainstream video encoding. For more information, see NERtcVideoFramerateType. By default, the frame + * rate is determined based on maxProfile. + * - max_profile >= STANDARD. frameRate = FRAME_RATE_FPS_30. + * - max_profile < STANDARD. frameRate = FRAME_RATE_FPS_15. + * @endif + * @if Chinese + * 主流的视频编码的帧率。详细信息请参考 NERtcVideoFramerateType。默认根据设置的maxProfile决定帧率。 + * - max_profile >= STANDARD，frameRate = FRAME_RATE_FPS_30。 + * - max_profile < STANDARD，frameRate = FRAME_RATE_FPS_15。 + * @endif + */ + NERtcVideoFramerateType framerate; + /** + * @if English + * The minimum frame rate for video encoding. The default value is 0, which indicates that the minimum frame rate is used by + * default + * @endif + * @if Chinese + * 视频编码的最小帧率。默认为 0，表示使用默认最小帧率 + * @endif + */ + NERtcVideoFramerateType min_framerate; + /** + * @if English + * Video encoding bitrate (kbps), use the default value if the setting is set to 0. + * @endif + * @if Chinese + * 视频编码码率kbps，取0时使用默认值 + * @endif + */ + uint32_t bitrate; + /** + * @if English + * The minimum bitrate of video encoding in kbps. You can manually set the required minimum bitrate based on your business + * requirements. If the bitrate is set to 0, the SDK computes and processes automatically. + * @endif + * @if Chinese + * 视频编码的最小码率，单位为 Kbps。您可以根据场景需要，手动设置想要的最小码率，若设置为0，SDK 将会自行计算处理。 + * @endif + */ + uint32_t min_bitrate; + /** + * @if English + * Video encoding degradation preference when the bandwidth is limited. For more information, see NERtcDegradationPreference. + * @endif + * @if Chinese + * 带宽受限时的视频编码降级偏好。详细信息请参考 NERtcDegradationPreference。 + * @endif + */ + NERtcDegradationPreference degradation_preference; + /** + * @if English + * Set the mirror mode for the local video encoding. The mirror mode is used for publishing the local video stream. The + * setting only affects the video picture seen by remote users. + * @endif + * @if Chinese + * 设置本地视频编码的镜像模式，即本地发送视频的镜像模式，只影响远端用户看到的视频画面。 + * @endif + */ + NERtcVideoMirrorMode mirror_mode; + /** + * @if English + * Set the orientation mode of the local video encoding, The orientation mode is used for publishing the local video stream, + * which only affects the video picture seen by remote users. + * @endif + * @if Chinese + * 设置本地视频编码的方向模式，即本地发送视频的方向模式，只影响远端用户看到的视频画面。 + * @endif + */ + NERtcVideoOutputOrientationMode orientation_mode; +}; + +/** + * @if English + * Video frame rate callback. + * @param uid The user ID + * @param data The data pointer + * @param type The data type NERtcVideoType + * @param width The width + * @param height The height + * @param count The number of data types, including the number of offset and stride. + * @param offset The data offset of each type + * @param stride The data step of each type + * @param rotation Screen rotation angle NERtcVideoRotation + * @param user_data User transparent transmission data + * + * @endif + * @if Chinese + * 视频帧数据回调 + * @param uid 用户id + * @param data 数据指针 + * @param type 数据类型NERtcVideoType + * @param width 宽度 + * @param height 高度 + * @param count 数据类型个数，即offset及stride的数目 + * @param offset 每类数据偏移 + * @param stride 每类数据步进 + * @param rotation 画面旋转角度NERtcVideoRotation + * @param user_data 用户透传数据 + * @endif + */ +typedef void (*onFrameDataCallback)(uid_t uid, + void* data, + uint32_t type, + uint32_t width, + uint32_t height, + uint32_t count, + uint32_t offset[4], + uint32_t stride[4], + uint32_t rotation, + void* user_data); + +/** + * @if English + * Configuration parameters for screen sharing encoding. + * @endif + * @if Chinese + * 屏幕共享编码参数配置。 + * @endif + */ +typedef enum { + /** + * @if English + * 640x480, 5fps. + * @endif + * @if Chinese + * 640x480, 5fps + * @endif + */ + kNERtcScreenProfile480P = 0, + /** + * @if English + * 1280x720, 5fps. + * @endif + * @if Chinese + * 1280x720, 5fps + * @endif + */ + kNERtcScreenProfileHD720P = 1, + /** + * @if English + * 1920x1080, 5fps. This is the default value. + * @endif + * @if Chinese + * 1920x1080, 5fps。默认 + * @endif + */ + kNERtcScreenProfileHD1080P = 2, + /** + * @if English + * Custom. + * @endif + * @if Chinese + * 自定义 + * @endif + */ + kNERtcScreenProfileCustom = 3, + /** + * @if English + * None + * @endif + * @if Chinese + * 无效果。 + * @endif + */ + kNERtcScreenProfileNone = 4, + /** + * @if English + * 1920x1080, 5fps. This is the default value. + * @endif + * @if Chinese + * 1920x1080, 5fps。 + * @endif + */ + kNERtcScreenProfileMAX = kNERtcScreenProfileHD1080P, +} NERtcScreenProfileType; + + +/** + * @if English + * Screen sharing status. + * @endif + * @if Chinese + * 屏幕分享状态 + * @endif + */ +typedef enum { + /** + * @if English + * Starts screen sharing. + * @endif + * @if Chinese + * 开始屏幕共享。 + * @endif + */ + kNERtcScreenCaptureStatusStart = 1, + + /** + * @if English + * Pauses screen sharing. + * @endif + * @if Chinese + * 暂停屏幕共享。 + * @endif + */ + kNERtcScreenCaptureStatusPause = 2, + + /** + * @if English + * Resumes screen sharing. + * @endif + * @if Chinese + * 恢复屏幕共享。 + * @endif + */ + kNERtcScreenCaptureStatusResume = 3, + + /** + * @if English + * Stops screen sharing. + * @endif + * @if Chinese + * 停止屏幕共享。 + * @endif + */ + kNERtcScreenCaptureStatusStop = 4, + + /** + * @if English + * The target window for screen sharing is covered. + * @endif + * @if Chinese + * 屏幕分享的目标窗口被覆盖。 + * @note 在 Windows 平台中，某些窗口在被屏蔽之后，如果被置于图层最上层，此窗口图像可能会黑屏。此时会触发 + * onScreenCaptureStatus.kScreenCaptureStatusCovered 回调，建议应用层在触发此回调时提醒用户将待分享的窗口置于最上层。 + * @endif + */ + kNERtcScreenCaptureStatusCovered = 5 +} NERtcScreenCaptureStatus; + +/** + * @if English + * The position of the area to be shared with respect to the entire screen or window. If you leave the setting empty, the entire + * screen or window is shared. + * @endif + * @if Chinese + * 待共享区域相对于整个屏幕或窗口的位置，如不填，则表示共享整个屏幕或窗口。 + * @endif + */ +struct NERtcRectangle { + /** + * @if English + * The horizontal offset of the upper left corner. + * @endif + * @if Chinese + * 左上角的横向偏移。 + * @endif + */ + int x; + /** + * @if English + * The vertical offset of the upper left corner. + * @endif + * @if Chinese + * 左上角的纵向偏移。 + * @endif + */ + int y; + /** + * @if English + * The width of the area to be shared. + * @endif + * @if Chinese + * 待共享区域的宽。 + * @endif + */ + int width; + /** + * @if English + * The height of the area to be shared. + * @endif + * @if Chinese + * 待共享区域的高。 + * @endif + */ + int height; +}; + +/** + * @if English + * Video dimensions. + * @endif + * @if Chinese + * 视频尺寸。 + * @endif + */ +struct NERtcVideoDimensions { + /** + * @if English + * The width + * @endif + * @if Chinese + * 宽度 + * @endif + */ + int width; + /** + * @if English + * The height + * @endif + * @if Chinese + * 高度 + * @endif + */ + int height; +}; + +/** + * @if English + * Encoding strategy preference for screen sharing. + * - kNERtcSubStreamContentPreferMotion: The content type is animation. When the shared content is a video, movie, or game, We + * recommend that you select this content type.If a user sets the content type to animation, the user-defined frame rate is + * applied. + * - kNERtcSubStreamContentPreferDetails: The content type is details. When the shared content is an image or text, We recommend + * that you select this content type. When the user sets the content type to details, the user is allowed to set up to 10 + * frames. If the setting exceeds 10 frames, 10 frames are applied. + * @endif + * @if Chinese + * 屏幕共享功能的编码策略倾向。 + * - kNERtcSubStreamContentPreferMotion: + * 内容类型为动画。当共享的内容是视频、电影或游戏时，推荐选择该内容类型。当用户设置内容类型为动画时，按用户设置的帧率处理。 + * - kNERtcSubStreamContentPreferDetails: + * 内容类型为细节。当共享的内容是图片或文字时，推荐选择该内容类型。当用户设置内容类型为细节时，最高允许用户设置到10帧，设置超过 + * 10 帧时，不生效，按 10 帧处理。 + * @endif + */ +typedef enum { + /** + * @if English + * The animation mode. + * @endif + * @if Chinese + * 动画模式。 + * @endif + */ + kNERtcSubStreamContentPreferMotion = 0, + /** + * @if English + * The details mode. + * @endif + * @if Chinese + * 细节模式。 + * @endif + */ + kNERtcSubStreamContentPreferDetails = 1, +} NERtcSubStreamContentPrefer; + +/** + * @if English + * Configuration parameters for screen sharing encoding. The setting is used to measure encoding quality. + * @endif + * @if Chinese + * 屏幕共享编码参数配置。用于衡量编码质量。 + * @endif + */ +struct NERtcScreenCaptureParameters { + /** + * @if English + * Configuration parameters for screen sharing encoding. + * @endif + * @if Chinese + * 屏幕共享编码参数配置。 + * @endif + */ + NERtcScreenProfileType profile; + /** + * @if English + * The maximum pixel value sent by screen sharing video. The value is valid in kNERtcScreenProfileCustom. + * @endif + * @if Chinese + * 屏幕共享视频发送的最大像素值，kNERtcScreenProfileCustom下生效。 + * @endif + */ + NERtcVideoDimensions dimensions; + /** + * @if English + * The frame rate of the shared video.The value is valid in kNERtcScreenProfileCustom, and the unit is fps. The default value + * is 5. A value more than 15 is not recommended. + * @endif + * @if Chinese + * 共享视频的帧率，kNERtcScreenProfileCustom下生效，单位为 fps；默认值为 5，建议不要超过 15。 + * @endif + */ + int frame_rate; + /** + * @if English + * The bitrate of the shared video in kbps. The default value is 0, which indicates that the SDK calculates a reasonable value + * based on the resolution of the current shared screen. + * @endif + * @if Chinese + * 共享视频的码率，单位为 kbps；默认值为 0，表示 SDK 根据当前共享屏幕的分辨率计算出一个合理的值。 + * @endif + */ + int bitrate; + /** + * @if English + * Determines whether to capture the mouse during screen sharing. + * @endif + * @if Chinese + * 是否采集鼠标用于屏幕共享。 + * @endif + */ + bool capture_mouse_cursor; + /** + * @if English + * Determing whether to bing the window to the front when you call the startScreenCaptureByWindowId method to share a window. + * @endif + * @if Chinese + * 调用 startScreenCaptureByWindowId 方法共享窗口时，是否将该窗口前置。 + * @endif + */ + bool window_focus; + /** + * @if English + * ID list of windows to be blocked. + * @endif + * @if Chinese + * 待屏蔽窗口的 ID 列表。 + * @endif + */ + source_id_t* excluded_window_list; + /** + * @if English + * The number of windows to be blocked. + * @endif + * @if Chinese + * 待屏蔽窗口的数量。 + * @endif + */ + int excluded_window_count; + /** + * @if English + * Encoding strategy preference. + * @endif + * @if Chinese + * 编码策略倾向。 + * @endif + */ + NERtcSubStreamContentPrefer prefer; + + /** + * @if English + * Video encoding degradation preference when the bandwidth is limited. For more information, see + * NERtcDegradationPreference. + * @endif + * @if Chinese + * 带宽受限时的视频编码降级偏好。详细信息请参考 NERtcDegradationPreference。 + * @endif + */ + NERtcDegradationPreference degradation_preference; +}; + +/** + * @if English + * Configuration of the video display. + * @endif + * @if Chinese + * 视频显示设置 + * @endif + */ +struct NERtcVideoCanvas { + /** + * @if English + * Specifies whether to use an external renderer. The default value is NO. If you want to use an external renderer, you can + * associate the renderer by calling externalVideoRender with the SDK. if not, you can associate the renderer based on the + * container with the SDK. Switching between the internal rendering and external rendering during a call is not supported. + * @endif + * @if Chinese + * 是否使用外部渲染器，默认 NO + * 不使用，若使用SDK内部会根据externalVideoRender来进行绑定，若不使用SDK内部根据container来进行绑定。暂不支持在通话中切换内部渲染与外部渲染。 + * @endif + */ + bool use_external_render; + /** + * @if English + * Data callbacks. For more information, see onFrameDataCallback. + *
In macosx, you must set video_use_exnternal_render in NERtcEngineContext to true. + * @endif + * @if Chinese + * 数据回调。详细信息请参考 onFrameDataCallback。 + *
在 macosx中，需要设置 NERtcEngineContex t的 video_use_exnternal_render 为 true 才有效。 + * @endif + */ + onFrameDataCallback cb; + /** + * @if English + * The user data returned by the callback for the data transparent transmission. + * In macosx, you must set video_use_exnternal_render in NERtcEngineContext to true. + * @endif + * @if Chinese + * 数据回调的用户透传数据。 + *
在 macosx中，需要设置 NERtcEngineContex t的 video_use_exnternal_render 为 true 才有效。 + * @endif + */ + void* user_data; + /** + * @if English + * Rendering window handle. + * In macosx, you must set video_use_exnternal_render in NERtcEngineContext to false. + * @endif + * @if Chinese + * 渲染窗口句柄。 + *
在 macosx中，需要设置 NERtcEngineContex t的 video_use_exnternal_render 为 false 才有效。 + * + * @endif + */ + void* window; + /** + * @if English + * Video display mode. For more information, see NERtcVideoCropMode. + * @endif + * @if Chinese + * 视频显示模式，详细信息请参考 NERtcVideoScalingMode。 + * @endif + */ + NERtcVideoScalingMode scaling_mode; + + /** + * @if Chinese + * 背景颜色，格式为 0xRRGGBB，默认为黑色即 0x000000 + * @endif + */ + uint32_t background_color; +}; + +/** + * @if English + * Recording type. + * @endif + * @if Chinese + * 录制类型。 + * @endif + */ +typedef enum { + /** + * @if English + * Composite and individual stream recording. + * @endif + * @if Chinese + * 参与合流+单流录制。 + * @endif + */ + kNERtcRecordTypeAll = 0, + /** + * @if English + * Composite recording mode. + * @endif + * @if Chinese + * 参与合流录制模式。 + * @endif + */ + kNERtcRecordTypeMix = 1, + /** + * @if English + * individual recording mode. + * @endif + * @if Chinese + * 参与单流录制模式。 + * @endif + */ + kNERtcRecordTypeSingle = 2, + +} NERtcRecordType; + +/** + * @if English + * Audio type. + * @endif + * @if Chinese + * 音频类型。 + * @endif + */ +typedef enum { + /** + * @if English + * PCM audio format. + * @endif + * @if Chinese + * PCM 音频格式。 + * @endif + */ + kNERtcAudioTypePCM16 = 0, +} NERtcAudioType; + +/** + * @if English + * Audio frame request data read and write mode. + * @endif + * @if Chinese + * 音频帧请求数据的读写模式。 + * @endif + */ +typedef enum { + /** + * @if English + * Read-only mode + * @endif + * @if Chinese + * 返回数据只读模式 + * @endif + */ + kNERtcRawAudioFrameOpModeReadOnly = 0, + /** + * @if English + * Read and write mode + * @endif + * @if Chinese + * 返回数据可读写 + * @endif + */ + kNERtcRawAudioFrameOpModeReadWrite, +} NERtcRawAudioFrameOpModeType; + +/** + * @if English + * The audio frame request format. + * @endif + * @if Chinese + * 音频帧请求格式。 + * @endif + */ +struct NERtcAudioFrameRequestFormat { + /** + * @if English + * the number of channels. If the audio is a stereo sound, the data is interleaved. mono: 1. stereo: 2. + * @endif + * @if Chinese + * 音频声道数量。如果是立体声，数据是交叉的。单声道: 1；双声道 : 2。 + * @endif + */ + uint32_t channels; + /** + * @if English + * The sample rate. + * @endif + * @if Chinese + * 采样率。 + * @endif + */ + uint32_t sample_rate; + /** + * @if English + * Read and write mode. + * @endif + * @if Chinese + * 读写模式 + * @endif + */ + NERtcRawAudioFrameOpModeType mode; +}; + +/** + * @if English + * The audio format. + * @endif + * @if Chinese + * 音频格式。 + * @endif + */ +struct NERtcAudioFormat { + /** + * @if English + * Audio type. + * @endif + * @if Chinese + * 音频类型。 + * @endif + */ + NERtcAudioType type; + /** + * @if English + * the number of channels. If the audio is a stereo sound, the data interleaved. mono: 1. stereo: 2. + * @endif + * @if Chinese + * 音频声道数量。如果是立体声，数据是交叉的。单声道: 1；双声道 : 2。 + * @endif + */ + uint32_t channels; + /** + * @if English + * The sample rate. + * @endif + * @if Chinese + * 采样率。 + * @endif + */ + uint32_t sample_rate; + /** + * @if English + * The number of bytes per sample. For PCM, 16 bits are used, which means 2 bytes. + * @endif + * @if Chinese + * 每个采样点的字节数。对于 PCM 来说，一般使用 16 bit，即两个字节。 + * @endif + */ + uint32_t bytes_per_sample; + /** + * @if English + * The number of samples per room. + * @endif + * @if Chinese + * 每个房间的样本数量。 + * @endif + */ + uint32_t samples_per_channel; +}; + +/** + * @if English + * The audio frame. + * @endif + * @if Chinese + * 音频帧。 + * @endif + */ +struct NERtcAudioFrame { + /** + * @if English + * Audio format. + * @endif + * @if Chinese + * 音频格式。 + * @endif + */ + NERtcAudioFormat format; + /** + * @if English + * Data buffer. The valid data length: samples_per_channel * channels * bytes_per_sample. + * @endif + * @if Chinese + * 数据缓冲区。有效数据长度为：samples_per_channel * channels * bytes_per_sample。 + * @endif + */ + void* data; +}; + +/** + * @if English + * Audio payload type. + * @endif + * @if Chinese + * 音频payload类型。 + * @endif + */ +typedef enum { + /** + * @if English + * OPUS audio payload type. + * @endif + * @if Chinese + * OPUS音频格式。 + * @endif + */ + kNERtcAudioPayloadTypeOPUS = 111, +} NERtcAudioPayloadType; + +/** + * @if English + * Audio encoded frame of external input. + * @endif + * @if Chinese + * 外部输入的编码后音频帧。 + * @endif + */ +struct NERtcAudioEncodedFrame { + /** + * @if English + * The audio encoded frame data. + * @endif + * @if Chinese + * 编码后音频帧数据。 + * @endif + */ + unsigned char* data; + /** + * @if English + * The audio encoded frame timestamp. Unit: microseconds. + * @endif + * @if Chinese + * 时间戳, 单位为微妙。 + * @endif + */ + int64_t timestamp_us; + /** + * @if English + * The audio encoded frame samplerate. + * @endif + * @if Chinese + * 音频采样率。 + * @endif + */ + int sample_rate; + /** + * @if English + * The audio encoded frame channels. + * @endif + * @if Chinese + * 音频声道数。 + * @endif + */ + int channels; + /** + * @if English + * The audio encoded frame samples per channel. + * @endif + * @if Chinese + * 该编码片段中每个声道的样本数。 + * @endif + */ + int samples_per_channel; + /** + * @if English + * The audio encoded frame data length. + * @endif + * @if Chinese + * 编码后音频帧数据长度。 + * @endif + */ + int encoded_len; + /** + * @if English + * The audio encoded timestmap, Unit: number of samples, such as 0, 960, 1920 ... increase. + * @endif + * @if Chinese + * 编码时间, 单位为样本数, 如0、960、1920...递增。 + * @endif + */ + int encoded_timestamp; + /** + * @if English + * The audio encoded frame payload type. For more information, see NERtcAudioPayloadType. + * @endif + * @if Chinese + * 编码后音频帧payload类型，详细信息请参考 NERtcAudioPayloadType。 + * @endif + */ + NERtcAudioPayloadType payload_type; + + /** + * @if Chinese + * 音频数据音量标记，有效值[0,100]，用于后台ASL选路时参考。默认100。 + * @endif + */ + uint8_t rms_level; +}; +/** + * @if English + * The voice observer object. + *
Some APIs allow you to modify the content that void *data points to in the frame. However, you cannot modify the format. + * If you need to modify the format, you must call the corresponding setting interface. + * @endif + * @if Chinese + * 语音观测器对象。 + *
部分接口允许修改 frame 里 void *data 所指向的内容，但不允许修改 format。如果对 format 有要求，需调用相应设置接口。 + * @endif + */ +class INERtcAudioFrameObserver { + public: + virtual ~INERtcAudioFrameObserver() {} + /** + * @if English + * Occurs when the audio data is captured. The callback is used to process the audio data. + * @note + * - The returned audio data has read and write permissions. + * - The callback is triggered when an operation is driven by the local audio data. + * @param frame The audio frame. + * @endif + * @if Chinese + * 采集音频数据回调，用于声音处理等操作。 + * @note + * - 返回音频数据支持读/写。 + * - 有本地音频数据驱动就会回调。 + * @param frame 音频帧。 + * @endif + */ + virtual void onAudioFrameDidRecord(NERtcAudioFrame* frame) = 0; + /** + * @if English + * Occurs when the audio substream data is captured. The callback is used to process the audio data. + * @note + * - The returned audio data has read and write permissions. + * - The callback is triggered when an operation is driven by the local audio data. + * @param frame The audio frame. + * @endif + * @if Chinese + * 辅流采集音频数据回调。 + *
通过 \ref IRtcEngineEx::setAudioFrameObserver "setAudioFrameObserver" 接口设置回调监听，当辅流设备工作时，会触发该回调。此外您可以通过 \ref IRtcEngineEx::setRecordingAudioFrameParameters "setRecordingAudioFrameParameters" 接口设置回调数据格式。 + * @par 业务场景 + * 通过该回调数据可以获取辅流采集数据，也可以通过回调数据做音频前处理（变声、音效处理等）。 + * @since V4.6.20 + * @note + * - 有本地音频辅流据驱动就会返回该回调。 + * - 返回音频数据支持读/写。 + * - 该接口返回的数据格式，需要以返回数据 NERtcAudioFrame 中的 NERtcAudioFormat 为准。 + * @par 参数说明 + * + * + * + * + * + * + * + * + * + * + * + *
**参数名称****类型****描述**
frame \ref nertc::NERtcAudioFrame "NERtcAudioFrame"音频帧。包含数据格式及数据内容。
+ * @endif + */ + virtual void onSubstreamAudioFrameDidRecord(NERtcAudioFrame *frame); + /** + * @if English + * Occurs when the audio data is played back. The callback is used to process the audio data. + * @note + * - The returned audio data has read and write permissions. + * - The callback is triggered when an operation is driven by the local audio data. + * @param frame The audio frame. + * @endif + * @if Chinese + * 播放音频数据回调，用于声音处理等操作。 + * @note + * - 返回音频数据支持读/写。 + * - 有本地音频数据驱动就会回调。 + * @param frame 音频帧。 + * @endif + */ + virtual void onAudioFrameWillPlayback(NERtcAudioFrame* frame) = 0; + /** + * @if English + * Gets the raw audio data of the local user and all remote users after mixing. + * @note + * - The returned audio data is read-only. + * - The callback is triggered when an operation is driven by the local audio data. + * @param frame The audio frame. + * @endif + * @if Chinese + * 获取本地用户和所有远端用户混音后的原始音频数据。 + * @note + * - 返回音频数据只读。 + * - 有本地音频数据驱动就会回调。 + * @param frame 音频帧。 + * @endif + */ + virtual void onMixedAudioFrame(NERtcAudioFrame* frame) = 0; + /** + * @if English + * Gets the raw audio data of a specified remote user before audio mixing. + *
After the audio observer is registered, if the remote audio is subscribed by default and the remote user + * enables the audio, the SDK triggers this callback when the audio data before audio mixing is captured, and the + * audio data is returned to the user. + * @note The returned audio data is read-only. + * @deprecated This API is about to be deprecated. Use \ref + * nertc::INERtcAudioFrameObserver::onPlaybackAudioFrameBeforeMixing(uint64_t userID, NERtcAudioFrame* frame, + * channel_id_t cid) "onPlaybackAudioFrameBeforeMixing"[2/2] instead. In multi-channel scenarios, channelId is used + * to identify different channels. + * @param userID The ID of a remote user. + * @param frame The audio frame. + * @endif + * @if Chinese + * 获取单个远端用户混音前的音频数据。 + *
成功注册音频观测器后，如果订阅了远端音频（默认订阅）且远端用户开启音频后，SDK + * 会在捕捉到混音前的音频数据时，触发该回调，将音频数据回调给用户。 + * @note 返回音频数据只读。 + * @deprecated 即将废弃，请改用接口 \ref nertc::INERtcAudioFrameObserver::onPlaybackAudioFrameBeforeMixing(uint64_t + * userID, NERtcAudioFrame* frame, channel_id_t cid) + * "onPlaybackAudioFrameBeforeMixing"[2/2]。在多房间场景下，此接口可通过 cid 识别不同房间。 + * @param userID 用户 ID。 + * @param frame 音频帧。 + * @endif + */ + virtual void onPlaybackAudioFrameBeforeMixing(uint64_t userID, NERtcAudioFrame* frame, channel_id_t cid) = 0; + + /** + * @if English + * Gets the audio substream data from a specified remote user before mixing audio. + *
After the audio observer is registered, the SDK will get the audio data from a specified remote user before + * mixing if the remote audio substream is subscribed to and the remote user publishes the audio substream. + * @note The returned audio data can only be read. + * @param userID A remote user ID. + * @param frame audio frame data. + * @param cid Room ID. For multiple rooms, channelId is used to identify the rooms. + * @endif + * @if Chinese + * 获取指定远端用户混音前的辅流音频数据。 + *
成功注册音频观测器后，如果订阅了远端辅流音频（默认订阅）且远端用户开启辅流音频后，SDK + * 会在捕捉到混音前的辅流音频数据时，触发该回调，将辅流音频数据回调给用户。 + * @note 返回音频数据只读。 + * @param userID 用户ID。 + * @param frame 音频帧。 + * @param cid 房间 ID。在多房间场景下，cid 用于识别不同的房间。 + * @endif + */ + virtual void onPlaybackSubstreamAudioFrameBeforeMixing(uint64_t userID, NERtcAudioFrame* frame, channel_id_t cid) = 0; +}; + +/** + * @if English + * The video type. + * @endif + * @if Chinese + * 视频类型。 + * @endif + */ +typedef enum { + /** + * @if English + * I420 video format. + * @endif + * @if Chinese + * I420 视频格式。 + * @endif + */ + kNERtcVideoTypeI420 = 0, + /** + * @if English + * NV12 video format. + * @endif + * @if Chinese + * NV12 视频格式。 + * @endif + */ + kNERtcVideoTypeNV12 = 1, + /** + * @if English + * NV21 video format. + * @endif + * @if Chinese + * NV21 视频格式。 + * @endif + */ + kNERtcVideoTypeNV21 = 2, + /** + * @if English + * BGRA video format. + * @endif + * @if Chinese + * BGRA 视频格式。 + * @endif + */ + kNERtcVideoTypeBGRA = 3, + /** + * @if English + * ARGB video format. + * @endif + * @if Chinese + * BGRA 视频格式。 + * @endif + */ + kNERtcVideoTypeARGB = 4, + /** + * @if English + * oc capture native video format. External video input is not allowed. + * @endif + * @if Chinese + * oc capture native视频格式。不支持外部视频输入 + * @endif + */ + kNERtcVideoTypeCVPixelBuffer = 5, +} NERtcVideoType; + +/** + * @if English + * The angle to which the video rotates. + * @endif + * @if Chinese + * 视频旋转角度。 + * @endif + */ +typedef enum { + /** + * @if English + * 0 度。 + * @endif + * @if Chinese + * 0° + * @endif + */ + kNERtcVideoRotation_0 = 0, + /** + * @if English + * 90° + * @endif + * @if Chinese + * 90 度。 + * @endif + */ + kNERtcVideoRotation_90 = 90, + /** + * @if English + * 180° + * @endif + * @if Chinese + * 180 度。 + * @endif + */ + kNERtcVideoRotation_180 = 180, + /** + * @if English + * 270° + * @endif + * @if Chinese + * 270 度。 + * @endif + */ + kNERtcVideoRotation_270 = 270, +} NERtcVideoRotation; + +/** + * @if English + * Video frame of external input. + * @endif + * @if Chinese + * 外部输入的视频桢。 + * @endif + */ +struct NERtcVideoFrame { + /** + * @if English + * The video frame format. For more information, see NERtcVideoType. + * @endif + * @if Chinese + * 视频帧格式，详细信息请参考 NERtcVideoType。 + * @endif + */ + NERtcVideoType format; + /** + * @if English + * The video timestamp. Unit: milliseconds. + * @endif + * @if Chinese + * 视频时间戳，单位为毫秒。 + * @endif + */ + uint64_t timestamp; + /** + * @if English + * Video frame width. + * @endif + * @if Chinese + * 视频桢宽度 + * @endif + */ + uint32_t width; + /** + * @if English + * Video frame height. + * @endif + * @if Chinese + * 视频桢宽高 + * @endif + */ + uint32_t height; + /** + * @if Chinese + * 数据类型个数，即offset及stride的数目 + * @endif + */ + int count; + /** + * @if English + * offset of Video frame data . + * @endif + * @if Chinese + * 每类数据偏移 + * @endif + */ + uint32_t offset[4]; + /** + * @if English + * stride of Video frame data . + * @endif + * @if Chinese + * 每类数据步进 + * @endif + */ + uint32_t stride[4]; + /** + * @if English + * For more information about video rotation angle, see #NERtcVideoRotation. + * @endif + * @if Chinese + * 视频旋转角度 详见: #NERtcVideoRotation + * @endif + */ + NERtcVideoRotation rotation; + /** + * @if English + * Video frame data. + * @endif + * @if Chinese + * 视频桢数据 + * @endif + */ + void* buffer; + /** + * @if English + * The length of Video frame data. + * @endif + * @if Chinese + * 视频桢数据长度 + * @endif + */ + int64_t buffer_length; +}; +/** + * @if English + * The video codec type. + * @endif + * @if Chinese + * 视频编解码器类型。 + * @endif + */ +typedef enum { + /** + * @if English + * The H264 codec + * @endif + * @if Chinese + * H264 编解码器。 + * @endif + */ + kNERtcVideoCodecTypeH264 = 3, +} NertcVideoCodecType; + +/** + * @if English + * The video encoded frame type. + * @endif + * @if Chinese + * 视频编码帧类型。 + * @endif + */ +typedef enum { + /** + * @if English + * The IDR frame + * @endif + * @if Chinese + * IDR 帧。 + * @endif + */ + kNERtcNalFrameTypeIDR = 1, + /** + * @if English + * I frame. + * @endif + * @if Chinese + * I 帧。 + * @endif + */ + kNERtcNalFrameTypeI = 2, + /** + * @if English + * P frame. + * @endif + * @if Chinese + * P 帧。 + * @endif + */ + kNERtcNalFrameTypeP = 3, +} NERtcNalFrameType; + +/** + * @if English + * Video encoded frame of external input. + * @endif + * @if Chinese + * 外部输入的编码后视频帧。 + * @endif + */ +struct NERtcVideoEncodedFrame { + /** + * @if English + * The video codec type. For more information, see NERtcVideoCodecType. + * @endif + * @if Chinese + * 视频编解码器类型，详细信息请参考 NERtcVideoCodecType。 + * @endif + */ + NertcVideoCodecType codec_type; + /** + * @if English + * The video encoded frame type. For more information, see NERtcNalFrameType. + * @endif + * @if Chinese + * 编码后视频帧类型，详细信息请参考 NERtcNalFrameType。 + * @endif + */ + NERtcNalFrameType frame_type; + /** + * @if English + * The nal count of video encoded frame. + * @endif + * @if Chinese + * 编码后视频帧nal个数。 + * @endif + */ + int nal_count; + /** + * @if English + * The nal length of video encoded frame + * @endif + * @if Chinese + * 编码后视频帧nal的长度。 + * @endif + */ + int* nal_length; + /** + * @if English + * The nal length of video encoded frame + * @endif + * @if Chinese + * 编码后视频帧数据，包括所有nal的数据。 + * @endif + */ + unsigned char* nal_data; + /** + * @if English + * The video encoded frame timestamp. Unit: microseconds. + * @endif + * @if Chinese + * 时间戳，机器时间，单位为微秒。 + * @endif + */ + int64_t timestamp_us; + /** + * @if English + * The video encoded frame width. + * @endif + * @if Chinese + * 视频宽。 + * @endif + */ + int width; + /** + * @if English + * The video encoded frame height. + * @endif + * @if Chinese + * 视频高。 + * @endif + */ + int height; +}; + +/** + * @if English + * The reasons why the user leaves. + * @endif + * @if Chinese + * 用户离开原因。 + * @endif + */ +typedef enum { + /** + * @if English + * A user leaves the room normally. + * @endif + * @if Chinese + * 正常离开。 + * @endif + */ + kNERtcSessionLeaveNormal = 0, + /** + * @if English + * The user is disconnected and leaves the room. + * @endif + * @if Chinese + * 用户断线导致离开。 + * @endif + */ + kNERtcSessionLeaveForFailOver = 1, + /** + * @if English + * The user leaves the room because the session fails over. + * @endif + * @if Chinese + * 用户 Failover 过程中产生的 leave。 + * @endif + */ + kNERtcSessionLeaveUpdate = 2, + /** + * @if English + * The user is removed from the room. + * @endif + * @if Chinese + * 用户被踢导致离开。 + * @endif + */ + kNERtcSessionLeaveForKick = 3, + /** + * @if English + * The user is disconnected due to connection timeout. + * @endif + * @if Chinese + * 用户超时导致离开。 + * @endif + */ + kNERtcSessionLeaveTimeOut = 4, +} NERtcSessionLeaveReason; + +/** + * @if English + * The playback state of the music file. + * @endif + * @if Chinese + * 音乐文件播放状态。 + * + * @endif + */ +typedef enum { + /** + * @if English + * The playback ends. + * @endif + * @if Chinese + * 音乐文件播放结束。 + * @endif + */ + kNERtcAudioMixingStateFinished = 0, + /** + * @if English + * The playback fails because an error occurs. For more information, see #NERtcAudioMixingErrorCode. + * @endif + * @if Chinese + * 音乐文件报错。详见: #NERtcAudioMixingErrorCode + * @endif + */ + kNERtcAudioMixingStateFailed = 1, +} NERtcAudioMixingState; + +/** + * @if English + * Configuration items for audio mixing. + * @endif + * @if Chinese + * 创建混音的配置项 + * @endif + */ +struct NERtcCreateAudioMixingOption { + /** + * @if English + * The path of the audio file. The local absolute paths or URL addresses are supported. + * - The path must include the file name and extension, such as "D:\\audio_files\\test.mp3". + * - Supported audio formats: MP3, M4A, AAC, 3GP, WMA, and WAV. + * @endif + * @if Chinese + * 待播放的音乐文件路径，支持本地绝对路径或 URL 地址。 + * - 需精确到文件名及后缀，例如 “D:\\audio_files\\test.mp3”。 + * - 支持的音乐文件类型包括 MP3、M4A、AAC、3GP、WMA 和 WAV 格式。 + * @endif + */ + char path[kNERtcMaxURILength]; + /** + * @if English + * The number of loops for mixing audio playback: + * -1: (Default) plays the audio effect for one time. + * -≤ 0: plays in an infinite loop, until stops by calling pauseAudioMixing or stopAudioMixing. + * @endif + * @if Chinese + * 伴音循环播放的次数： + * - 1：（默认）播放音效一次。 + * - ≤ 0：无限循环播放，直至调用 pauseAudioMixing 后暂停，或调用 stopAudioMixing 后停止。 + * @endif + */ + int loop_count; + /** + * @if English + * Specifies whether to send the mixing audio to the remote client. The default value is true. The remote user can hear the + * mixing audio after the remote user subscribes to the local audio stream. + * @endif + * @if Chinese + * 是否将伴音发送远端，默认为 true，即远端用户订阅本端音频流后可听到该伴音。 + * @endif + */ + bool send_enabled; + /** + * @if English + * Indicates the publishing volume of a music file. Valid values: 0 to 100. The default value is 100, which indicates that the + * original volume of the file is used. + * @note If you modify the volume setting during a call, this setting will be used by default when you call the method again + * during the current call. + * @endif + * @if Chinese + * 乐文件的发送音量，取值范围为 0~100。默认为 100，表示使用文件的原始音量。 + * @note 若您在通话中途修改了音量设置，则当前通话中再次调用时默认沿用此设置。 + * @endif + */ + uint32_t send_volume; + /** + * @if English + * Specifies whether to play back the mixing audio on the local client. The default value is true. The local users can hear + * the mixing audio. + * @endif + * @if Chinese + * 是否本地播放伴音。默认为 true，即本地用户可以听到该伴音。 + * @endif + */ + bool playback_enabled; + /** + * @if English + * Indicates the playback volume of a music file. Valid values: 0 to 100. The default value is 100, which indicates that the + * original volume of the file is used. + * @note If you modify the volume setting during a call, this setting will be used by default when you call the method again + * during the current call. + * @endif + * @if Chinese + * 音乐文件的播放音量，取值范围为 0~100。默认为 100，表示使用文件的原始音量。 + * @note 若您在通话中途修改了音量设置，则当前通话中再次调用时默认沿用此设置。 + * @endif + */ + uint32_t playback_volume; + /** + * @if English + * The start of a playback position. Unit: milliseconds. Default value: 0. + * @endif + * @if Chinese + * 音乐文件开始播放的时间，UTC 时间戳，即从1970 年 1 月 1 日 0 点 0 分 0 秒开始到事件发生时的毫秒数。默认值为 + * 0，表示立即播放。 + * @endif + */ + uint64_t start_timestamp; + + /** + * @if English + * Specifies if a mixing audio uses a mainstream or substream. The default value is mainstream. + * @endif + * @if Chinese + * 伴音跟随音频主流还是辅流，默认跟随主流。 + * @endif + */ + NERtcAudioStreamType send_with_audio_type; + + /** + * @if English + * Audio playback progress callback interval, unit: ms, value range: 100~10000, default: 1000ms + * @endif + * @if Chinese + * 伴音播放进度回调间隔，单位ms，取值范围为 100~10000, 默认1000ms + * @endif + */ + uint32_t progress_interval; +}; + +/** + * @if English + * Configuration items for audio effects. + * @endif + * @if Chinese + * 创建音效的配置项 + * @endif + */ +struct NERtcCreateAudioEffectOption { + /** + * @if English + * The path of the audio effect file. The local absolute paths or URL addresses are supported. + * - The path must include the file name and extension, such as "D:\\audio_files\\test.mp3". + * - Supported audio formats: MP3, M4A、AAC, 3GP, WMA, and WAV. + * @endif + * @if Chinese + * 待播放的音效文件路径，支持本地绝对路径或 URL 地址。 + * - 需精确到文件名及后缀，例如 “D:\\audio_files\\test.mp3”。 + * - 支持的音效文件类型包括 MP3、M4A、AAC、3GP、WMA 和 WAV 格式。 + * @endif + */ + char path[kNERtcMaxURILength]; + /** + * @if English + * The number of loops the audio effect is played: + * -1: (Default) plays the audio effect for one time. + * -≤ 0: Play sound effects in an infinite loop until you stop the playback by calling stopEffect or stopAllEffects. + * @endif + * @if Chinese + * 音效循环播放的次数： + * - 1：（默认）播放音效一次。 + * - ≤ 0：无限循环播放音效，直至调用 stopEffect 或 stopAllEffects 后停止。 + * @endif + */ + int loop_count; + /** + * @if English + * Specifies whether to send the mixing audio to the remote client. The default value is true. The remote user can hear the + * mixing audio after the remote user subscribes to the local audio stream. + * @endif + * @if Chinese + * 是否将伴音发送远端，默认为 true，即远端用户订阅本端音频流后可听到该伴音。 + * @endif + */ + bool send_enabled; + /** + * @if English + * Indicates the publishing volume of a music file. Valid values: 0 to 100. The default value is 100, which indicates that the + * original volume of the file is used. + * @note If you modify the volume setting during a call, this setting will be used by default when you call the method again + * during the current call. + * @endif + * @if Chinese + * 音乐文件的发送音量，取值范围为 0~100。默认为 100，表示使用文件的原始音量。 + * @note 若您在通话中途修改了音量设置，则当前通话中再次调用时默认沿用此设置。 + * @endif + */ + uint32_t send_volume; + /** + * @if English + * Specifies whether to play back. The default value is true. You can play back the local audio file. + * @endif + * @if Chinese + * 是否可播放。默认为 true，即可在本地播放该音效。 + * @endif + */ + bool playback_enabled; + /** + * @if English + * Indicates the playback volume of a music file. Valid values: 0 to 100. The default value is 100, which indicates that the + * original volume of the file is used. + * @note If you modify the volume setting during a call, this setting will be used by default when you call the method again + * during the current call. + * @endif + * @if Chinese + * 音乐文件的播放音量，取值范围为 0~100。默认为 100，表示使用文件的原始音量。 + * @note 若您在通话中途修改了音量设置，则当前通话中再次调用时默认沿用此设置。 + * @endif + */ + uint32_t playback_volume; + /** + * @if English + * The start of a playback position. Unit: milliseconds. Default value: 0. + * @endif + * @if Chinese + * 音乐文件开始播放的时间，UTC 时间戳，即从1970 年 1 月 1 日 0 点 0 分 0 秒开始到事件发生时的毫秒数。默认值为 + * 0，表示立即播放。 + * @endif + */ + uint64_t start_timestamp; + + /** + * @if English + * Specifies if a mixing audio uses a mainstream or substream. The default value is mainstream. + * @endif + * @if Chinese + * 伴音跟随音频主流还是辅流，默认跟随主流。 + * @endif + */ + NERtcAudioStreamType send_with_audio_type; + + /** + * @if English + * Audio playback progress callback interval, unit: ms, value range: 100~10000, default: 1000ms + * @endif + * @if Chinese + * 伴音播放进度回调间隔，单位ms，取值范围为 100~10000, 默认1000ms + * @endif + */ + uint32_t progress_interval; +}; + +/** + * @if English + * The video stream type. + * @endif + * @if Chinese + * 视频流类型 + * @endif + */ +typedef enum { + /** + * @if English + * mainstream. + * @endif + * @if Chinese + * 主流 + * @endif + */ + kNERTCVideoStreamMain = 0, + /** + * @if English + * Substream. + * @endif + * @if Chinese + * 辅流 + * @endif + */ + kNERTCVideoStreamSub = 1, + /** + * @if English + * Reserved parameter. Ignore this parameter. + * @endif + * @if Chinese + * 预留参数，无需关注。 + * @endif + */ + kNERTCVideoStreamCount, +} NERtcVideoStreamType; + +/** + * @if English + * Status during media stream relay. + * @endif + * @if Chinese + * 媒体流转发状态 + * @endif + */ +typedef enum { + /** + * @if English + * Initial state. After a successful call of stopChannelMediaRelay method to stop cross-room media streaming. + * @endif + * @if Chinese + * 初始状态。在成功调用 stopChannelMediaRelay 停止跨房间媒体流转发后， onMediaRelayStateChanged 会回调该状态。 + * @endif + */ + kNERtcChannelMediaRelayStateIdle = 0, + /** + * @if English + * The SDK tries to relay cross-room media streams. + * @endif + * @if Chinese + * SDK 尝试跨房间转发媒体流。 + * @endif + */ + kNERtcChannelMediaRelayStateConnecting = 1, + /** + * @if English + * Sets the host role of source channel into the target room. + * @endif + * @if Chinese + * 源房间主播角色成功加入目标房间。 + * @endif + */ + kNERtcChannelMediaRelayStateRunning = 2, + /** + * @if English + * Failure occurs. See the error messages prompted by error of onMediaRelayEvent. + * @endif + * @if Chinese + * 发生异常，详见 onMediaRelayEvent 的 error 中提示的错误信息。 + * @endif + */ + kNERtcChannelMediaRelayStateFailure = 3, +} NERtcChannelMediaRelayState; + +/** + * @if English + * Events related to the media stream relay. + * @endif + * @if Chinese + * 媒体流转发回调事件。 + * @endif + */ +typedef enum { + /** + * @if English + * Current media stream relay gets disconnected. + * @endif + * @if Chinese + * 媒体流转发停止。 + * @endif + */ + kNERtcChannelMediaRelayEventDisconnect = 0, + /** + * @if English + * Starts to relay media streams. + * @endif + * @if Chinese + * SDK 正在连接服务器，开始尝试转发媒体流。 + * @endif + */ + kNERtcChannelMediaRelayEventConnecting = 1, + /** + * @if English + * The media stream relay gets connected to the server. + * @endif + * @if Chinese + * 连接服务器成功。 + * @endif + */ + kNERtcChannelMediaRelayEventConnected = 2, + /** + * @if English + * The video stream is relayed to the destination room. + * @endif + * @if Chinese + * 视频音频媒体流成功转发到目标房间。 + * @endif + */ + kNERtcChannelMediaRelayEventVideoSentToDestChannelSuccess = 3, + /** + * @if English + * The audio stream is relayed to the destination room. + * @endif + * @if Chinese + * 音频媒体流成功转发到目标房间。 + * @endif + */ + kNERtcChannelMediaRelayEventAudioSentToDestChannelSuccess = 4, + /** + * @if English + * Other streams such as screen sharing stream are relayed to the destination room. + * @endif + * @if Chinese + * 媒体流屏幕共享等其他流成功转发到目标房间。 + * @endif + */ + kNERtcChannelMediaRelayEventOtherStreamSentToDestChannelSuccess = 5, + /** + * @if English + * Fails to relay media streams. Possible reasons： + * - kNERtcErrChannelReserveErrorParam(414) + * - kNERtcErrChannelMediaRelayInvalidState(30110) + * - kNERtcErrChannelMediaRelayPermissionDenied(30111) + * - kNERtcErrChannelMediaRelayStopFailed(30112) + * @endif + * @if Chinese + * 媒体流转发失败。原因包括： + * - kNERtcErrChannelReserveErrorParam(414)：请求参数错误。 + * - kNERtcErrChannelMediaRelayInvalidState(30110)：重复调用 startChannelMediaRelay。 + * - kNERtcErrChannelMediaRelayPermissionDenied(30111)：媒体流转发权限不足。例如调用 startChannelMediaRelay + * 的房间成员为主播角色、或房间为双人通话房间，不支持转发媒体流。 + * - kNERtcErrChannelMediaRelayStopFailed(30112)：调用 stopChannelMediaRelay 前，未调用 startChannelMediaRelay。 + * @endif + */ + kNERtcChannelMediaRelayEventFailure = 100, +} NERtcChannelMediaRelayEvent; + +/** + * @if English + * Data structure related to media stream relay. + * @endif + * @if Chinese + * 媒体流转发相关的数据结构。 + * @endif + */ +struct NERtcChannelMediaRelayInfo { + /** + * @if English + * The name of the destination room to which the media stream is relayed. + * @endif + * @if Chinese + * 房间名。 + * @endif + */ + const char channel_name[kNERtcMaxChannelNameLength]; + /** + * @if English + * The token used to connect to the destination room. + * @endif + * @if Chinese + * 能加入房间的 Token。 + * @endif + */ + const char channel_token[kNERtcMaxTokenLength]; + /** + * @if English + * The user ID used in the destination room. This ID can be different from the ID used in the current room. + * @endif + * @if Chinese + * 用户 ID。 + * @endif + */ + uid_t uid; +}; + +/** + * @if English + * Configurations for media stream relay. + * @endif + * @if Chinese + * 跨房间媒体流转发相关参数配置。 + * @endif + */ +struct NERtcChannelMediaRelayConfiguration { + /** + * @if English + * The information about the current room. + * - `channelName`: Source channel name. + * - `channel_token`: Token with access to source channel. + * - `uid`: Identifies the UID of relaying media streams in the source channel. + * @endif + * @if Chinese + * 源房间信息，包括： + * - `channel_name`：源房间名。默认值为 nil，表示 SDK 填充当前的房间名。 + * - `channel_token`：能加入源房间的 Token。 + * - `uid`：标识源房间中的转发媒体流的 UID。 + * @endif + */ + NERtcChannelMediaRelayInfo* src_infos; + /** + * @if English + * The configuration of the destination room. + * - `channelName`：Destination channel names. + * - `channel_token`：Token with access to target channels. + * - `uid`：Identifies the UID of relaying media stream in the target channel. Do not set this parameter as the UID of the + * host in the destination room. The parameter is different from all UIDs in the target channel. + * @endif + * @if Chinese + * 目标房间信息，包括： + * - `channelName`：目标房间的房间名。 + * - `channel_token`：可以加入目标房间的 Token。 + * - `uid`：标识目标房间中的转发媒体流的 UID。请确保不要将该参数设为目标房间的主播的 UID，并与目标房间中的 所有 UID 都不同。 + * @endif + */ + NERtcChannelMediaRelayInfo* dest_infos; + /** + * @if English + * The number of destination rooms. The default value is 0. + * @endif + * @if Chinese + * 目标房间数量。默认为 0。 + * @endif + */ + int dest_count; +}; + +/** + * @if English + * Video watermark status. + * @endif + * @if Chinese + * 视频水印状态。 + * @endif + */ +typedef enum { + /** + * @if Chinese + * 水印设置成功。 + * @endif + */ + kNERtcLocalWatermarkStateSetSuccess, + /** + * @if English + * The device does not support video watermarks. + * @endif + * @if Chinese + * 设备不支持。 + * @endif + */ + kNERtcLocalWatermarkStateDeviceNotSupported, + /** + * @if English + * The image format is not supported. + * @endif + * @if Chinese + * 图片格式不支持。 + * @endif + */ + kNERtcLocalWatermarkStateImgFormatNotSupported, + /** + * @if English + * Image number error. + * @endif + * @if Chinese + * 图片数量设置错误。 + * @endif + */ + kNERtcLocalWatermarkStateImgNumError, + /** + * @if English + * Image resolution error. + * @endif + * @if Chinese + * 图片分辨率设置错误。 + * @endif + */ + kNERtcLocalWatermarkStateImgSizeError, + /** + * @if Chinese + * 播放帧率设置错误。 + * @endif + */ + kNERtcLocalWatermarkStateFPSError, + /** + * @if English + * Font error. + * @endif + * @if Chinese + * 字体设置错误。 + * @endif + */ + kNERtcLocalWatermarkStateFontError, + /** + * @if Chinese + * 整体水印透明度设置错误。 + * @endif + */ + kNERtcLocalWatermarkStateWmAlphaError, + /** + * @if Chinese + * 文本内容为空。 + * @endif + */ + kNERtcLocalWatermarkStateTextContentEmptyError, + /** + * @if English + * Watermark canceled. + * @endif + * @if Chinese + * 取消水印。 + * @endif + */ + kNERtcLocalWatermarkStateCancel = 20 +} NERtcLocalVideoWatermarkState; + +/** + * @if English + * Sets the parameters for image watermarks. + *
You can add up to 4 picture watermarks. + * @endif + * @if Chinese + * 图片水印设置参数。 + *
最多可以添加 4 个图片水印。 + * @endif + */ +struct NERtcVideoWatermarkImageConfig { + /** + * @if English + * Watermark image path. The setting is invalid if left empty. + * @endif + * @if Chinese + * 水印图片路径。空时无效。 + * @endif + */ + char* image_paths[10]; + /** + * @if English + * The alpha channel of the watermark background color. + * @endif + * @if Chinese + * 水印框内背景颜色透明度 + * @endif + */ + int wm_alpha; + /** + * @if English + * The width of the watermark frame. Unit: pixels. The default value is 0, which indicates no watermark frame. + * @endif + * @if Chinese + * 水印框的宽度。单位为像素（pixel），默认值为 0，表示没有水印框。 + * @endif + */ + int wm_width; + /** + * @if English + * The height of the watermark frame. Unit: pixels. The default value is 0, which indicates no watermark frame. + * @endif + * @if Chinese + * 水印框的高度。单位为像素（pixel），默认值为 0，表示没有水印框。 + * @endif + */ + int wm_height; + /** + * @if English + * The horizontal distance between the upper left corner of the watermark and the upper left corner of the video canvas. Unit: + * pixels. The default value is 0. + * @endif + * @if Chinese + * 水印图片左上角与视频画布左上角的水平距离。单位为像素（pixel），默认值为 0。 + * @endif + */ + int offset_x; + /** + * @if English + * The vertical distance between the upper left corner of the watermark and the upper left corner of the video canvas. Unit: + * pixels. The default value is 0. + * @endif + * @if Chinese + * 水印图片左上角与视频画布左上角的垂直距离。单位为像素（pixel），默认值为 0。 + * @endif + */ + int offset_y; + /** + * @if English + * The frame rate. The default value is 0 fps, which indicates that the images are not flipped automatically. Images are + * displayed in static single frames. Note: The frame rate for clients on Windows does not exceed 20 fps. + * @endif + * @if Chinese + * 播放帧率。默认 0 帧/秒，即不自动切换图片，图片单帧静态显示。注意：Windows端帧率不超过 20 fps。 + * @endif + */ + int fps; + /** + * @if English + * Specifies whether to loop. By default, loop is enabled. If the value is set to false, the watermarks disappear when the + * playback is complete. + * @endif + * @if Chinese + * 是否设置循环。默认循环，设置为 false 后水印数组播放完毕后消失。 + * @endif + */ + bool loop; +}; + +/** + * @if English + * Parameters for text watermarks. + *
You can add up to 10 text watermarks. + * @endif + * @if Chinese + * 文字水印设置参数。 + *
最多可添加 10 个文字水印。 + * @endif + */ +struct NERtcVideoWatermarkTextConfig { + /** + * @if English + * The text content. + * @note + * - The length of the string is unlimited. The final display is affected by the font size and the size of the watermark + * frame. The part beyond the watermark frame is not displayed. + * - If the width of the watermark frame is set, when the length of the text content exceeds the width of the watermark frame, + * the text automatically wraps. If the text exceeds the height of the watermark frame, the excess part is not displayed. + * - When the width and height of the watermark frame are not set, the text does not wrap, and the part beyond the watermark + * frame is not be displayed. + * @endif + * @if Chinese + * 文字内容。 + * @note + * - 字符串长度无限制。最终显示受字体大小和水印框大小的影响。超出水印框的部分不显示。 + * - 如果设置了水印框宽度，当文字内容长度超过水印框宽度时，会自动换行，如果超出水印框高度，超出部分不显示。 + * - 未设置水印框宽度和高度时，文字不换行，超出水印框的部分不显示。 + * @endif + */ + char content[kNERtcMaxBuffLength]; + /** + * @if Chinese + * 字体名称。 + * @endif + */ + char font_name[kNERtcMaxURILength]; + /** + * @if English + * The font color. ARGB format. + * @endif + * @if Chinese + * 字体颜色。ARGB 格式。 + * @endif + */ + int font_color; + /** + * @if English + * The font size. The default value is 10, equivalent to 10 x 15 lb on a 144 dpi device. + * @endif + * @if Chinese + * 字体大小。默认值为 10，相当于 144 dpi 设备上的 10 x 15 磅。 + * @endif + */ + int font_size; + /** + * @if English + * The background color in the watermark frame. ARGB format. Transparency setting is supported. + * @endif + * @if Chinese + * 水印框内背景颜色。ARGB格式，支持透明度设置。 + * @endif + */ + int wm_color; + /** + * @if English + * The alpha channel of the watermark background color. + * @endif + * @if Chinese + * 水印框内背景颜色透明度 + * @endif + */ + int wm_alpha; + /** + * @if English + * The width of the watermark frame. Unit: pixels. The default value is 0, which indicates no watermark frame. + * @endif + * @if Chinese + * 水印框的宽度。单位为像素（pixel），默认值为 0，表示没有水印框。 + * @endif + */ + int wm_width; + /** + * @if English + * The height of the watermark frame. Unit: pixels. The default value is 0, which indicates no watermark frame. + * @endif + * @if Chinese + * 水印框的高度。单位为像素（pixel），默认值为 0，表示没有水印框。 + * @endif + */ + int wm_height; + /** + * @if English + * The horizontal distance between the upper left corner of the watermark and the upper left corner of the video canvas. Unit: + * pixels. + * @endif + * @if Chinese + * 水印左上角与视频画布左上角的水平距离。单位为像素（pixel）。 + * @endif + */ + int offset_x; + /** + * @if English + * The vertical distance between the upper left corner of the watermark and the upper left corner of the video canvas. Unit: + * pixels. + * @endif + * @if Chinese + * 水印左上角与视频画布左上角的垂直距离。单位为像素（pixel）。 + * @endif + */ + int offset_y; +}; + +/** + * @if English + * Sets a timestamp watermark. + * - You can add only 1 timestamp watermark. + * - The time of the timestamp watermark is the same as the current time and changes in real time. + * @endif + * @if Chinese + * 时间戳水印设置。 + * - 只能添加 1 个时间戳水印。 + * - 时间戳水印的时间和当前时间相同，且实时变化。 + * @endif + */ +struct NERtcVideoWatermarkTimestampConfig { + /** + * @if Chinese + * 字体名称。 + * @endif + */ + char font_name[kNERtcMaxURILength]; + /** + * @if English + * The font color. ARGB format. + * @endif + * @if Chinese + * 水印左上角与视频画布左上角的水平距离。单位为像素（pixel）。 + * @endif + */ + int font_color; + /** + * @if English + * The font size. The default value is 10, equivalent to 10 x 15 lb on a 144 dpi device. + * @endif + * @if Chinese + * 字体颜色。ARGB 格式。 + * @endif + */ + int font_size; + /** + * @if English + * The background color in the watermark frame. ARGB format. Transparency setting is supported. + * @endif + * @if Chinese + * 水印框内背景颜色。ARGB格式，支持透明度设置。 + * @endif + */ + int wm_color; + /** + * @if English + * The alpha channel of the watermark background color. + * @endif + * @if Chinese + * 水印框内背景颜色透明度 + * @endif + */ + int wm_alpha; + /** + * @if English + * The width of the watermark frame. Unit: pixels. The default value is 0, which indicates no watermark frame. + * @endif + * @if Chinese + * 水印框的宽度。单位为像素（pixel），默认值为 0，表示没有水印框。 + * @endif + */ + int wm_width; + /** + * @if English + * The height of the watermark frame. Unit: pixels. The default value is 0, which indicates no watermark frame. + * @endif + * @if Chinese + * 水印框的高度。单位为像素（pixel），默认值为 0，表示没有水印框。 + * @endif + */ + int wm_height; + /** + * @if English + * The horizontal distance between the upper left corner of the watermark and the upper left corner of the video canvas. Unit: + * pixels. + * @endif + * @if Chinese + * 水印左上角与视频画布左上角的水平距离。单位为像素（pixel）。 + * @endif + */ + int offset_x; + /** + * @if English + * The vertical distance between the upper left corner of the watermark and the upper left corner of the video canvas. Unit: + * pixels. + * @endif + * @if Chinese + * 水印左上角与视频画布左上角的垂直距离。单位为像素（pixel）。 + * @endif + */ + int offset_y; +}; + +/** + * @if English + * Video watermark settings. Three types of watermarks are supported. You can select one of the three types. + * @endif + * @if Chinese + * 视频水印设置，目前支持三种类型的水印，但只能其中选择一种水印生效。 + * @endif + */ +struct NERtcVideoWatermarkConfig { + /** + * @if English + * Video watermark type enumerations + * @endif + * @if Chinese + * 视频水印类型枚举。 + * @endif + */ + typedef enum { + /** + * @if English + * Image watermark. + * @endif + * @if Chinese + * 图片水印。 + * @endif + */ + kNERtcWatermarkTypeImage = 0, + /** + * @if English + * Text watermark. + * @endif + * @if Chinese + * 文字水印。 + * @endif + */ + kNERtcWatermarkTypeText, + /** + * @if English + * Timestamp watermark. + * @endif + * @if Chinese + * 时间戳水印。 + * @endif + */ + kNERtcWatermarkTypeTimestamp + }NERtcWatermarkType; + + NERtcWatermarkType watermark_type; + NERtcVideoWatermarkImageConfig image_watermarks; + NERtcVideoWatermarkTextConfig text_watermarks; + NERtcVideoWatermarkTimestampConfig timestamp_watermark; +}; + +class NERtcTakeSnapshotCallback { + public: + virtual ~NERtcTakeSnapshotCallback() {} + /* + * Returns the screenshot result. + * @param errorCode The error code. For more information, see {@link NERtcErrorCode}. + * @param image The screenshot. Images on macOS are in CGImageRef format. + * @endif + * @if Chinese + * 截图结果回调。 + * @param errorCode 错误码。详细信息请参考 {@link NERtcErrorCode}。 + * @param image 截图图片。默认为图片文件所在路径。 + * @endif + */ + virtual void onTakeSnapshotCallback(uid_t uid, NERtcVideoStreamType stream_type, int error_code, void* image) = 0; +}; + +/** + * @if English + * Log levels. + * @endif + * @if Chinese + * 日志级别。 + * @endif + * */ +typedef enum { + /** + * @if English + * Fatal. + * @endif + * @if Chinese + * Fatal 级别日志信息。 + * @endif + */ + kNERtcLogLevelFatal = 0, + /** + * @if English + * Error. + * @endif + * @if Chinese + * Error 级别日志信息。 + * @endif + */ + kNERtcLogLevelError = 1, + /** + * @if English + * Warning. The default log level. + * @endif + * @if Chinese + * Warning 级别日志信息。默认级别 + * @endif + */ + kNERtcLogLevelWarning = 2, + /** + * @if English + * Info. + * @endif + * @if Chinese + * Info 级别日志信息。 + * @endif + */ + kNERtcLogLevelInfo = 3, + /** + * @if English + * Detail Info. + * @endif + * @if Chinese + * Detail Info 级别日志信息。 + * @endif + */ + kNERtcLogLevelDetailInfo = 4, + /** + * @if English + * Verbos. + * @endif + * @if Chinese + * Verbos 级别日志信息。 + * @endif + */ + kNERtcLogLevelVerbos = 5, + /** + * @if English + * Debug. To get the complete log file, set the log level to this option. + * @endif + * @if Chinese + * Debug 级别日志信息。如果你想获取最完整的日志，可以将日志级别设为该等级。 + * @endif + */ + kNERtcLogLevelDebug = 6, + /** + * @if English + * No logs. + * @endif + * @if Chinese + * 不输出日志信息。 + * @endif + */ + kNERtcLogLevelOff = 7, +} NERtcLogLevel; + +/** + * @if English + * Video delivery strategy after publishing. + * @endif + * @if Chinese + * 视频推流后发送策略。 + * @endif + * */ +typedef enum { + /** + * @if English + * The client does not actively send the data stream. The stream is sent if the stream is subscribed. + * @endif + * @if Chinese + * 不主动发送数据流，被订阅后发送。 + * @endif + */ + kNERtcSendOnPubNone = 0, + /** + * @if English + * The client actively sends the mainstream. + * @endif + * @if Chinese + * 主动发送大流。 + * @endif + */ + kNERtcSendOnPubHigh = 1, + /** + * @if English + * The client actively sends the substream. + * @endif + * @if Chinese + * 主动发送小流。 + * @endif + */ + kNERtcSendOnPubLow = 1 << 1, + /** + * @if English + * The client actively sends the mainstream and the substream. + * @endif + * @if Chinese + * 主动发送大小流。 + * @endif + */ + kNERtcSendOnPubAll = kNERtcSendOnPubLow | kNERtcSendOnPubHigh, +} NERtcSendOnPubType; + +/** + * @if English + * Configures private servers. + * @note To use private servers, contact technical support for help. + * @endif + * @if Chinese + * 私有化服务器配置项 + * @note 如需启用私有化功能，请联系技术支持获取详情。 + * @endif + */ +struct NERtcServerAddresses { + /** + * @if English + * 获取通道信息服务器 + * @endif + * @if Chinese + * The channel server. + * @endif + */ + char channel_server[kNERtcMaxURILength]; + /** + * @if English + * The stats server. + * @endif + * @if Chinese + * 统计上报服务器 + * @endif + */ + char statistics_server[kNERtcMaxURILength]; + /** + * @if English + * The stats dispatch server. + * @endif + * @if Chinese + * 统计调度服务器 + * @endif + */ + char statistics_dispatch_server[kNERtcMaxURILength]; + /** + * @if English + * The stats backup server. + * @endif + * @if Chinese + * 统计备份服务器 + * @endif + */ + char statistics_backup_server[kNERtcMaxURILength]; + /** + * @if English + * The roomServer server. + * @endif + * @if Chinese + * roomServer服务器 + * @endif + */ + char room_server[kNERtcMaxURILength]; + /** + * @if English + * The compatibility configuration server. + * @endif + * @if Chinese + * 兼容性配置服务器 + * @endif + */ + char compat_server[kNERtcMaxURILength]; + /** + * @if English + * The NOS domain name resolution server. + * @endif + * @if Chinese + * nos 域名解析服务器 + * @endif + */ + char nos_lbs_server[kNERtcMaxURILength]; + /** + * @if English + * The default NOS upload server. + * @endif + * @if Chinese + * 默认nos 上传服务器 + * @endif + */ + char nos_upload_sever[kNERtcMaxURILength]; + /** + * @if English + * The NOS token server. + * @endif + * @if Chinese + * 获取NOS token 服务器 + * @endif + */ + char nos_token_server[kNERtcMaxURILength]; + /** + * @if English + * The cloud proxy server. + * @endif + */ + char cloud_proxy_server[kNERtcMaxURILength]; + /** + * @if English + * The websocket proxy server. + * @endif + */ + char websocket_proxy_server[kNERtcMaxURILength]; + /** + * @if English + * The quic proxy server. + * @endif + */ + char quic_proxy_server[kNERtcMaxURILength]; + /** + * @if English + * The media proxy server. + * @endif + */ + char media_proxy_server[kNERtcMaxURILength]; + /** + * @if English + * Specifies whether to use Ipv6. The default value is false. + * @endif + * @if Chinese + * 是否使用IPv6（默认false) + * @endif + */ + bool use_ipv6; + + NERtcServerAddresses() : use_ipv6(false) { + memset(channel_server, 0, sizeof(channel_server)); + memset(statistics_server, 0, sizeof(statistics_server)); + memset(statistics_dispatch_server, 0, sizeof(statistics_dispatch_server)); + memset(statistics_backup_server, 0, sizeof(statistics_backup_server)); + memset(room_server, 0, sizeof(room_server)); + memset(compat_server, 0, sizeof(compat_server)); + memset(nos_lbs_server, 0, sizeof(nos_lbs_server)); + memset(nos_upload_sever, 0, sizeof(nos_upload_sever)); + memset(nos_token_server, 0, sizeof(nos_token_server)); + memset(cloud_proxy_server, 0, sizeof(cloud_proxy_server)); + memset(websocket_proxy_server, 0, sizeof(websocket_proxy_server)); + memset(quic_proxy_server, 0, sizeof(quic_proxy_server)); + memset(media_proxy_server, 0, sizeof(media_proxy_server)); + } +}; + +/** + * @if English + * Recording audio quality. + * @endif + * @if Chinese + * 录音音质 + * @endif + */ +typedef enum { + /** + * @if English + * Low quality + * @endif + * @if Chinese + * 低音质 + * @endif + */ + kNERtcAudioRecordingQualityLow = 0, + /** + * @if English + * medium quality + * @endif + * @if Chinese + * 中音质 + * @endif + */ + kNERtcAudioRecordingQualityMedium = 1, + /** + * @if English + * High quality + * @endif + * @if Chinese + * 高音质 + * @endif + */ + kNERtcAudioRecordingQualityHigh = 2, +} NERtcAudioRecordingQuality; + +typedef enum { + // 录制本地和所有远端用户混音后的音频（默认） + kNERtcAudioRecordingPositionMixedRecordingAndPlayback = 0, + // 仅录制本地用户的音频 + kNERtcAudioRecordingPositionRecording = 1, + // 仅录制所有远端用户的音频 + kNERtcAudioRecordingPositionMixedPlayback = 2 +} NERtcAudioRecordingPosition; + +typedef enum { + // 音频录制缓存时间为0，实时写文件（默认） + kNERtcAudioRecordingCycleTime0 = 0, + // 音频录制缓存时间为10s，StopAudioRectording()后，将缓存都写到文件，文件数据时间跨度为: [0,10s] + kNERtcAudioRecordingCycleTime10 = 10, + // 音频录制缓存时间为60s，StopAudioRectording()后，将缓存都写到文件，文件数据时间跨度为: [0,60s] + kNERtcAudioRecordingCycleTime60 = 60, + // 音频录制缓存时间为360s，StopAudioRectording()后，将缓存都写到文件，文件数据时间跨度为: [0,360s] + kNERtcAudioRecordingCycleTime360 = 360, + // 音频录制缓存时间为900s，StopAudioRectording()后，将缓存都写到文件，文件数据时间跨度为: [0,900s] + kNERtcAudioRecordingCycleTime900 = 900 +} NERtcAudioRecordingCycleTime; + +struct NERtcAudioRecordingConfiguration { + // 录音文件在本地保存的绝对路径，需要精确到文件名及格式。例如：sdcard/xxx/audio.aac。请确保指定的路径存在并且可写。目前仅支持 + // WAV 或 AAC 文件格式。 + char file_path[kNERtcMaxURILength]; + + // 录音采样率（Hz），可以设为 16000、32000（默认）、44100 或 48000。 + int sample_rate; + + // 录音音质，只在 AAC 格式下有效。详细信息请参考 {@link NERtcAudioRecordingQuality}。 + NERtcAudioRecordingQuality quality; + + // 录音文件所包含的内容。详细信息请参考 {@link NERtcAudioRecordingPosition}。 + NERtcAudioRecordingPosition position; + + // 录制过程中，循环缓存的最大时间长度，单位(s)。详细信息请参考 {@link NERtcAudioRecordingCycleTime}。 + NERtcAudioRecordingCycleTime cycle_time; +}; + +/** + * @if English + * The error code of recording callbacks. + * @endif + * @if Chinese + * 录音回调事件错误码 + * @endif + */ +typedef enum { + /** + * @if English + * Unsupported recording file format. + * @endif + * @if Chinese + * 不支持的录音文件格式。 + * @endif + */ + kNERtcAudioRecordErrorSuffix = 1, + /** + * @if English + * fails to create a recording file. Reasons: + * - The application does not have the write permissions. + * - The file path does not exist. + * @endif + * @if Chinese + * 无法创建录音文件，原因通常包括： + * - 应用没有磁盘写入权限。 + * - 文件路径不存在。 + * @endif + */ + kNERtcAudioRecordOpenFileFailed = 2, + /** + * @if English + * Starts recording. + * @endif + * @if Chinese + * 开始录制。 + * @endif + */ + kNERtcAudioRecordStart = 3, + /** + * @if English + * An error occurs during recording. The typical reason is that the disk space is full and cannot be written. + * @endif + * @if Chinese + * 录制错误。原因通常为磁盘空间已满，无法写入。 + * @endif + */ + kNERtcAudioRecordError = 4, + /** + * @if English + * Recording is complete. + * @endif + * @if Chinese + * 完成录制。 + * @endif + */ + kNERtcAudioRecordFinish = 5, +} NERtcAudioRecordingCode; + +/** + * @if English + * Fallback options when the uplink and downlink connections are weak. + * @endif + * @if Chinese + * 上行、下行弱网时的回退选项。 + * @endif + */ +typedef enum { + /** + * @if English + * If the uplink or downlink network is unstable, the audio and video streams will not fall back, but the quality of the audio + * and video streams cannot be guaranteed. + * @note This option is only valid for the setLocalPublishFallbackOption method, and invalid for the + * setRemoteSubscribeFallbackOption method. + * @endif + * @if Chinese + * 上行或下行网络较弱时，不对音视频流作回退处理，但不能保证音视频流的质量。 + * @note 该选项只对 setLocalPublishFallbackOption 方法有效，对 setRemoteSubscribeFallbackOption 方法无效。 + * @endif + */ + kNERtcStreamFallbackDisabled = 0, + + /** + * @if English + * In an unstable downlink network, the SDK only receives low-definition streams that have low resolution and bitrate. + * @note This option is only valid for the setRemoteSubscribeFallbackOption method, and invalid for the + * setLocalPublishFallbackOption method. + * @endif + * @if Chinese + * 在下行网络条件较差的情况下，SDK 将只接收视频小流，即低分辨率、低码率视频流。 + * @note 该选项只对 setRemoteSubscribeFallbackOption 方法有效，对 setLocalPublishFallbackOption 方法无效。 + * @endif + */ + kNERtcStreamFallbackVideoStreamLow = 1, + + /** + * @if English + * - In an unstable uplink network, only the audio stream is published. + * - In an unstable downlink network, first try to receive only low-definition streams, which have low resolution and bitrate. + * If the video stream cannot be displayed due to network quality, then the stream falls back to the audio stream. + * @endif + * @if Chinese + * - 上行网络较弱时，只发布音频流。 + * - 下行网络较弱时，先尝试只接收视频小流，即低分辨率、低码率视频流。如果网络环境无法显示视频，则再回退到只接收音频流。 + * @endif + */ + kNERtcStreamFallbackAudioOnly = 2, +} NERtcStreamFallbackOption; + +/** + * @if English + * Media stream encryption mode. + * @endif + * @if Chinese + * 媒体流加密模式。 + * @endif + * */ +typedef enum { + /** + * @if English + * 128-bit SM4 encryption, ECB mode. + * @endif + * @if Chinese + * 128 位 SM4 加密，ECB 模式。 + * @endif + */ + kNERtcGMCryptoSM4ECB = 0, +} NERtcEncryptionMode; + +/** + * @if English + * Media stream encryption scheme. + * @endif + * @if Chinese + * 媒体流加密方案。 + * @endif + */ +struct NERtcEncryptionConfig { + /** + * @if English + * Media stream encryption mode. For more information, see NERtcEncryptionMode. + * @endif + * @if Chinese + * 媒体流加密模式。详细信息请参考 NERtcEncryptionMode。 + * @endif + */ + NERtcEncryptionMode mode; + /** + * @if English + * Media stream encryption key. The key is of string type. We recommend that you set the key to a string that contains only + * letters. + * @endif + * @if Chinese + * 媒体流加密密钥。字符串类型，推荐设置为英文字符串。 + * @endif + */ + char key[kNERtcEncryptByteLength]; +}; + +/** + * @if English + * Configurations of the last-mile network probe test. + * @endif + * @if Chinese + * Last mile 网络探测配置。 + * @endif + */ +struct NERtcLastmileProbeConfig { + /** + * @if English + * Sets whether to test the uplink network. + *
Some users, for example, the audience in a kNERtcChannelProfileLiveBroadcasting channel, do not need such a test。 + * - true: test. + * - false: do not test. + * @endif + * @if Chinese + * 是否探测上行网络。 + *
不发流的用户，例如直播房间中的普通观众，无需进行上行网络探测。 + * - true: 探测。 + * - false: 不探测。 + * @endif + */ + bool probe_uplink; + /** + * @if English + * Sets whether to test the downlink network: + * - true: test. + * - false: do not test. + * @endif + * @if Chinese + * 是否探测下行网络。 + * - true: 探测。 + * - false: 不探测。 + * @endif + */ + bool probe_downlink; + /** + * @if English + * The expected maximum sending bitrate (bps) of the local user. + *
The value ranges between 100000 and 5000000. + *
We recommend setting this parameter according to the bitrate value set by setVideoConfig. + * @endif + * @if Chinese + * 本端期望的最高发送码率。 + *
单位为 bps，范围为 [100000, 5000000]。 + *
推荐参考 setVideoConfig 中的码率值设置该参数的值。 + * @endif + */ + uint32_t expected_uplink_bitratebps; + /** + * @if English + * The expected maximum receiving bitrate (bps) of the local user. The value ranges between 100000 and 5000000. + * @endif + * @if Chinese + * 本端期望的最高接收码率。 + *
单位为 bps，范围为 [100000, 5000000]。 + * @endif + */ + uint32_t expected_downlink_bitratebps; +}; + +/** + * @if English + * States of the last-mile network probe test. + * @endif + * @if Chinese + * Last mile 质量探测结果的状态。 + * @endif + */ +typedef enum { + /** + * @if English + * The last-mile network probe test is complete. + * @endif + * @if Chinese + * 表示本次 last mile 质量探测的结果是完整的。 + * @endif + */ + kNERtcLastmileProbeResultComplete = 1, + /** + * @if English + * The last-mile network probe test is incomplete and the bandwidth estimation is not available, probably due to limited test + * resources. + * @endif + * @if Chinese + * 表示本次 last mile 质量探测未进行带宽预测，因此结果不完整。通常原因为测试资源暂时受限。 + * @endif + */ + kNERtcLastmileProbeResultIncompleteNoBwe = 2, + /** + * @if English + * The last-mile network probe test is not carried out, probably due to poor network conditions. + * @endif + * @if Chinese + * 未进行 last mile 质量探测。通常原因为网络连接中断。 + * @endif + */ + kNERtcLastmileProbeResultUnavailable = 3, +} NERtcLastmileProbeResultState; + +/** + * @if English + * The uplink or downlink last-mile network probe test result. + * @endif + * @if Chinese + * 单向 Last mile 网络质量探测结果报告。 + * @endif + */ +struct NERtcLastmileProbeOneWayResult { + /** + * @if English + * The network jitter (ms). + * @endif + * @if Chinese + * 网络抖动，单位为毫秒 (ms)。 + * @endif + */ + uint32_t jitter = 0; + /** + * @if English + * The packet loss rate (%). + * @endif + * @if Chinese + * 丢包率（%）。 + * @endif + */ + uint32_t packet_loss_rate = 0; + /** + * @if English + * The available band width (bps). + * @endif + * @if Chinese + * 可用网络带宽预估，单位为 bps。 + * @endif + */ + uint32_t available_band_width = 0; +}; + +/** + * @if English + * The uplink and downlink last-mile network probe test result. + * @endif + * @if Chinese + * 上下行 Last mile 网络质量探测结果。 + * @endif + */ +struct NERtcLastmileProbeResult { + /** + * @if English + * The round-trip delay time (ms). + * @endif + * @if Chinese + * 往返时延，单位为毫秒（ms）。 + * @endif + */ + uint32_t rtt = 0; + /** + * @if English + * The state of the probe test. + * @endif + * @if Chinese + * Last mile 质量探测结果的状态。 + * @endif + */ + NERtcLastmileProbeResultState state = kNERtcLastmileProbeResultComplete; + /** + * @if English + * The uplink last-mile network probe test result. + * @endif + * @if Chinese + * 上行网络质量报告。 + * @endif + */ + NERtcLastmileProbeOneWayResult uplink_report; + /** + * @if English + * The downlink last-mile network probe test result. + * @endif + * @if Chinese + * 下行网络质量报告。 + * @endif + */ + NERtcLastmileProbeOneWayResult downlink_report; +}; +typedef enum { + /** + * @if English + * 0: Do not use the cloud proxy. + * @endif + * @if Chinese + * 0：关闭已设置的云代理。 + * @endif + */ + kNERtcTransportTypeNoneProxy = 0, + /** + * @if English + * 1: Sets the cloud proxy for the UDP protocol. + * @endif + * @if Chinese + * 1: 开启 UDP 协议的云代理。 + * @endif + */ + kNERtcTransportTypeUDPProxy = 1, +} NERtcTransportType; + +/** + * @if English + * Install audio driver plug-in result (only for Mac system) + * @endif + * @if Chinese + * 安装音频驱动插件结果（仅适用于 Mac 系统） + * @endif + */ +typedef enum { + /** + * @if English + * Install audio driver plug-in success. + * @endif + * @if Chinese + * 安装音频驱动插件成功 + * @endif + */ + kNERtcInstallCastAudioDriverSuccess = 0, + /** + * @if English + * Install audio driver plug-in because unauthorized. + * @endif + * @if Chinese + * 安装音频驱动插件未授 + * @endif + */ + kNERtcInstallCastAudioDriverNotAuthorized = 1, + /** + * @if English + * Install audio driver plug-in fail. + * @endif + * @if Chinese + * 安装音频驱动插件失败 + * @endif + */ + kNERtcInstallCastAudioDriverFailed = 2, +} NERtcInstallCastAudioDriverResult; +/** + * @if English + * The reason why the virtual background is not successfully enabled or the message that confirms success. + * @since v4.6.0 + * @endif + * @if Chinese + * 虚拟背景未成功启用的原因或确认成功的信息。 + * @since v4.6.0 + * @endif + */ +typedef enum{ + /** + * @if English + * 0: The virtual background is successfully enabled. + * @endif + * @if Chinese + * 0: 虚拟背景开启成功。 + * @endif + */ + kNERtcVirtualBackgroundSourceStateReasonSuccess = 0, + /** + * @if English + * 1: The custom background image does not exist. Please check the value of `source` in VirtualBackgroundSource. + * @endif + * @if Chinese + * 1：自定义背景图片不存在。 请检查 VirtualBackgroundSource 中 `source` 的值。 + * @endif + */ + kNERtcVirtualBackgroundSourceStateReasonImageNotExist = 1, + /** + * @if English + * 2: The image format of the custom background image is invalid. Please check the value of `source` in + * VirtualBackgroundSource. + * @endif + * @if Chinese + * 2：自定义背景图片的图片格式无效。 请检查 VirtualBackgroundSource 中 `source` 的值。 + * @endif + */ + kNERtcVirtualBackgroundSourceStateReasonImageFormatNotSupported = 2, + /** + * @if English + * 3: The color format of the custom background image is invalid. Please check the value of `color` in + * VirtualBackgroundSource. + * @endif + * @if Chinese + * 3：自定义背景图片的颜色格式无效。 请检查 VirtualBackgroundSource 中 `color` 的值。 + * @endif + */ + kNERtcVirtualBackgroundSourceStateReasonColorFormatNotSupported = 3, + /** + * @if English + * 4: The device does not support using the virtual background. + * @endif + * @if Chinese + * 4：该设备不支持使用虚拟背景。 + * @endif + */ + kNERtcVirtualBackgroundSourceStateReasonDeviceNotSupported = 4 +} NERtcVirtualBackgroundSourceStateReason; + +/** + * @if English + * The custom background image. + * @since v4.6.0 + * @endif + * @if Chinese + * 自定义背景图像。 + * @since v4.6.0 + * @endif + */ +struct NERtcVirtualBackgroundSource { + /** + * @if English + * The type of the custom background image. + * @since v4.6.0 + * @endif + * @if Chinese + * 自定义背景图片的类型。 + * @since v4.6.0 + * @endif + */ + typedef enum { + /** + * @if English + * 1: (Default) The background image is a solid color. + * @endif + * @if Chinese + * 1：（默认）背景图像为纯色。 + * @endif + */ + kNERtcBackgroundColor = 1, + + /** + * @if English + * The background image is a file in PNG or JPG format. + * @endif + * @if Chinese + * 背景图像只支持 PNG 或 JPG 格式的文件。 + * @endif + */ + kNERtcBackgroundImage, + }NERtcBackgroundSourceType; + + /** + * @if English + * The type of the custom background image. See #NERtcBackgroundSourceType. + * @endif + * @if Chinese + * 自定义背景图片的类型。 请参阅#NERtcBackgroundSourceType。 + * @endif + */ + NERtcBackgroundSourceType background_source_type; + + /** + * @if English + * 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 `kNERtcBackgroundColor`. + * @endif + * @if Chinese + * 自定义背景图像的颜色。格式为RGB定义的十六进制整数，不带#号， + * 例如 0xFFB6C1 代表浅粉色。默认值为 0xFFFFFF，表示白色。取值范围是 [0x000000,0xFFFFFF]。如果该值无效， + * SDK 将原始背景图片替换为白色的图片 + * @note 该参数仅在自定义背景图片类型为`kNERtcBackgroundColor`时生效。 + * @endif + */ + unsigned int color; + + /** + * @if English + * The local absolute path of the custom background image. PNG and JPG formats are supported. + * @note This parameter takes effect only when the type of the custom background image is `kNERtcBackgroundImage`. + * @endif + * @if Chinese + * 自定义背景图片的本地绝对路径。支持 PNG 和 JPG 格式。 + * @note 该参数仅在自定义背景图片类型为`kNERtcBackgroundImage`时生效。 + * @endif + */ + char source[kNERtcMaxURILength]; +}; + +/** + 音频dump类型 + */ +typedef enum { + /** + * @if Chinese + * 仅输出.dump文件（默认） + * @since v4.6.0 + * @endif + */ + kNERtcAudioDumpTypePCM = 0, + /** + * @if Chinese + * 输出.dump和.wav文件 + * @since v4.6.0 + * @endif + */ + kNERtcAudioDumpTypeAll = 1, + /** + * @if Chinese + * 仅输出.wav文件 + * @since v4.6.0 + * @endif + */ + kNERtcAudioDumpTypeWAV = 2 +} NERtcAudioDumpType; + +/** 混响参数 */ +struct NERtcReverbParam { + /** + * @if English + * Wet sound signal. Value range: 0 ~ 1. The default value is 0.0f. + * @endif + * @if Chinese + * 湿信号，取值范围为 0 ~ 1，默认值为 0.0f。 + * @endif + */ + float wet_gain; + /** + * @if English + * Dry sound signal. Value range: 0 ~ 1. The default value is 1.0f. + * @endif + * @if Chinese + * 干信号，取值范围为 0 ~ 1，默认值为 1.0f。 + * @endif + */ + float dry_gain; + /** + * @if English + * Reverb damping. Value range: 0 ~ 1. The default value is 1.0f. + * @endif + * @if Chinese + * 混响阻尼，取值范围为 0 ~ 1，默认值为 1.0f。 + * @endif + */ + float damping; + /** + * @if English + * Room size. Value range: 0.1 ~ 2. The default value is 0.1f. + * @endif + * @if Chinese + * 房间大小，取值范围为 0.1 ~ 2，默认值为 0.1f。 + * @endif + */ + float room_size; + /** + * @if English + * Decay time. Value range: 0.1 ~ 20. The default value is 0.1f. + * @endif + * @if Chinese + * 持续强度（余响），取值范围为 0.1 ~ 20，默认值为 0.1f。 + * @endif + */ + float decay_time; + /** + * @if English + * Pre-delay. Value range: 0 ~ 1. The default value is 0.0f. + * @endif + * @if Chinese + * 延迟长度，取值范围为 0 ~ 1，默认值为 0.0f。 + * @endif + */ + float predelay; +}; + +typedef enum { + /** + * @if Chinese + * 默认模式 + * @note + * - 设置后玩家附近一定范围的人都能听到该玩家讲话，如果范围内也有玩家设置为此模式，则也可以互相通话。 + * - TeamID相同的队友可以互相听到 + * @endif + */ + kNERtcRangeAudioModeDefault = 0, + /** + * @if Chinese + * 小组模式 + * @note 仅TeamID相同的队友可以互相听到 + * @endif + */ + kNERtcRangeAudioModeTeam = 1, +} NERtcRangeAudioMode; + +/** + * @if Chinese + * 加入音视频房间时的一些可选信息。 + * @endif + */ +struct NERtcJoinChannelOptions { + /** + * @if Chinese + * 自定义信息，最长支持 127 个字符。 + * @endif + */ + char custom_info[kNERtcCustomInfoLength]; + /** + * @if Chinese + * 权限密钥。能控制通话时长及媒体权限能力。 + * @endif + */ + char* permission_key; + /** + * @if Chinese + * 小队号 + * @endif + */ + int32_t team_id; + /** + * @if Chinese + * 语音模式。 + * @endif + */ + NERtcRangeAudioMode mode; + /** + * @if Chinese + * 语音接收范围。 + * @endif + */ + int audible_distance; + + NERtcJoinChannelOptions() : permission_key(NULL), team_id(-1), mode(kNERtcRangeAudioModeDefault), audible_distance(-1) { + memset(custom_info, 0, sizeof(custom_info)); + } +}; + +/** + * @if Chinese + * 加入音视频房间时的一些可选信息。 + * @endif + */ +struct NERtcJoinChannelOptionsEx { + /** + * @if Chinese + * 自定义信息，最长支持 127 个字符。 + * @endif + */ + char custom_info[kNERtcCustomInfoLength]; + /** + * @if Chinese + * 权限密钥。能控制通话时长及媒体权限能力。 + * @endif + */ + char* permission_key; + /** + * @if Chinese + * 小队号 + * @endif + */ + int32_t team_id; + /** + * @if Chinese + * 语音模式。 + * @endif + */ + NERtcRangeAudioMode mode; + /** + * @if Chinese + * 语音接收范围。 + * @endif + */ + int audible_distance; + + NERtcJoinChannelOptionsEx() : permission_key(NULL), team_id(-1), mode(kNERtcRangeAudioModeDefault), audible_distance(-1) { + memset(custom_info, 0, sizeof(custom_info)); + } +}; + +/** onUserJoined 回调的一些可选信息 */ +struct NERtcUserJoinExtraInfo { + /** + * 自定义信息， 来源于远端用户joinChannel时填的 {@link NERtcJoinChannelOptions#custom_info}参数，默认为空字符串。 + */ + char custom_info[kNERtcCustomInfoLength]; +}; + +/** + * @if English + * @since v4.6.10 + * Media pub type. + * @endif + * @if Chinese + * @since v4.6.10 + * 媒体 pub 类型。 + * @endif + */ +typedef enum { + /** + * @if English + * Audio pub type. + * @endif + * @if Chinese + * 音频 pub 类型。 + * @endif + */ + NERtcMediaPubTypeAudio +} NERtcMediaPubType; + +/** + * @if English + * Beauty types + * @endif + * @if Chinese + * 美颜类型。 + * @endif + */ +typedef enum { + /** + * @if English + * Applies bright teeth. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 美牙。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyWhiteTeeth = 0, + + /** + * @if English + * Applies bright eyes. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 亮眼。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyLightEye, + + /** + * @if English + * Whitening. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 美白。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyWhiten, + + /** + * @if English + * Smoothing. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 磨皮。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautySmooth, + + /** + * @if English + * Applies a small nose. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 小鼻。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautySmallNose, + + /** + * @if English + * Adjusts the eye distance. The default value of intensity is 0.5. + * @endif + * @if Chinese + * 眼距调整。强度默认值为 0.5。 + * @endif + */ + kNERtcBeautyEyeDis, + + /** + * @if English + * Adjusts the eye angle. The default value of intensity is 0.5. + * @endif + * @if Chinese + * 眼角调整。强度默认值为 0.5。 + * @endif + */ + kNERtcBeautyEyeAngle, + + /** + * @if English + * Adjusts the mouth shape. The default value of intensity is 0.5. + * @endif + * @if Chinese + * 嘴型调整。强度默认值为 0.5。 + * @endif + */ + kNERtcBeautyMouth, + + /** + * @if English + * Applies big eyes. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 大眼。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyBigEye, + + /** + * @if English + * Applies a small face. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 小脸。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautySmallFace, + + /** + * @if English + * Adjusts the jaw. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 下巴调整。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyJaw, + + /** + * @if English + * Applies a thin face. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 瘦脸。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyThinFace, + + /** + * @if English + * Applies a ruddy face. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 红润。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyFaceRuddy, + + /** + * @if English + * Applies a long nose. The default value of intensity is 0.5. + * @endif + * @if Chinese + * 长鼻。强度默认值为 0.5。 + * @endif + */ + kNERtcBeautyLongNose, + + /** + * @if English + * Adjusts the philtrum. The default value of intensity is 0.5. + * @endif + * @if Chinese + * 人中。强度默认值为 0.5。 + * @endif + */ + kNERtcBeautyRenZhong, + + /** + * @if English + * Adjusts the mouth angle. The default value of intensity is 0.5. + * @endif + * @if Chinese + * 嘴角。强度默认值为 0.5。 + * @endif + */ + kNERtcBeautyMouthAngle, + + /** + * @if English + * Applies round eyes. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 圆眼。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyRoundEye, + + /** + * @if English + * Adjusts the eye corners. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 开眼角。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyOpenEyeAngle, + + /** + * @if English + * Applies a V-shaped face. The default value of intensity is 0.0. + * @endif + * @if Chinese + * V 脸。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyVFace, + + /** + * @if English + * Applies a thin jaw. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 瘦下颚。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyThinUnderjaw, + + /** + * @if English + * Applies a narrow face. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 窄脸。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyNarrowFace, + + /** + * @if English + * Adjusts the cheekbone. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 瘦颧骨。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyCheekBone, + + /** + * @if English + * Sharpens the face. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 锐化。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyFaceSharpen, + + /** + * @if English + * @endif + * @if Chinese + * 调整嘴巴宽度。强度默认值为 0.5。 + * @endif + */ + kNERtcBeautyMouthWider, + + /** + * @if English + * @endif + * @if Chinese + * 祛抬头纹。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyForeheadWrinkles, + + /** + * @if English + * @endif + * @if Chinese + * 祛黑眼圈。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyDarkCircles, + + /** + * @if English + * @endif + * @if Chinese + * 祛法令纹。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautySmileLines, + + /** + * @if English + * @endif + * @if Chinese + * 短脸。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyShortFace +} NERtcBeautyEffectType; +/** + * 空间音效房间大小 + */ +typedef enum { + /** + * 小房间 + */ + kNERtcSpatializerRoomCapacitySmall = 0, + + /** + * 中等大小房间 + */ + kNERtcSpatializerRoomCapacityMedium = 1, + + /** + * 大房间 + */ + kNERtcSpatializerRoomCapacityLarge = 2, + + /** + * 巨大房间 + */ + kNERtcSpatializerRoomCapacityHuge = 3, + + /** + * 无房间效果 + */ + kNERtcSpatializerRoomCapacityNone = 4 +} NERtcSpatializerRoomCapacity; +/** + * 空间音效中房间材质名称 + */ +typedef enum { + /** + * 透明的 + */ + kNERtcSpatializerMaterialTransparent = 0, + /** + * 声学天花板，未开放 + */ + kNERtcSpatializerMaterialAcousticCeilingTiles, + /** + * 砖块，未开放 + */ + kNERtcSpatializerMaterialBrickBare, + /** + * 涂漆的砖块，未开放 + */ + kNERtcSpatializerMaterialBrickPainted, + /** + * 粗糙的混凝土块，未开放 + */ + kNERtcSpatializerMaterialConcreteBlockCoarse, + /** + * 涂漆的混凝土块，未开放 + */ + kNERtcSpatializerMaterialConcreteBlockPainted, + /** + * 厚重的窗帘 + */ + kNERtcSpatializerMaterialCurtainHeavy, + /** + * 隔音的玻璃纤维，未开放 + */ + kNERtcSpatializerMaterialFiberGlassInsulation, + /** + * 薄的的玻璃，未开放 + */ + kNERtcSpatializerMaterialGlassThin, + /** + * 茂密的草地，未开放 + */ + kNERtcSpatializerMaterialGlassThick, + /** + * 草地 + */ + kNERtcSpatializerMaterialGrass, + /** + * 铺装了油毡的混凝土，未开放 + */ + kNERtcSpatializerMaterialLinoleumOnConcrete, + /** + * 大理石 + */ + kNERtcSpatializerMaterialMarble, + /** + * 金属，未开放 + */ + kNERtcSpatializerMaterialMetal, + /** + * 镶嵌木板的混凝土，未开放 + */ + kNERtcSpatializerMaterialParquetOnConcrete, + /** + * 石膏，未开放 + */ + kNERtcSpatializerMaterialPlasterRough, + /** + * 粗糙石膏，未开放 + */ + kNERtcSpatializerMaterialPlasterSmooth, + /** + * 光滑石膏，未开放 + */ + kNERtcSpatializerMaterialPlywoodPanel, + /** + * 木板，未开放 + */ + kNERtcSpatializerMaterialPolishedConcreteOrTile, + /** + * 石膏灰胶纸板，未开放 + */ + kNERtcSpatializerMaterialSheetrock, + /** + * 水面或者冰面，未开放 + */ + kNERtcSpatializerMaterialWaterOrIceSurface, + /** + * 木头天花板，未开放 + */ + kNERtcSpatializerMaterialWoodCeiling, + /** + * 木头枪板，未开放 + */ + kNERtcSpatializerMaterialWoodPanel, + /** + * 均匀分布，未开放 + */ + kNERtcSpatializerMaterialUniform +} NERtcSpatializerMaterialName; + +/** + * 空间音效渲染模式 + */ +typedef enum { + /** + * 立体声 panning + */ + kNERtcSpatializerRenderStereoPanning = 0, + /** + * 低复杂度双耳渲染(Binaural) + */ + kNERtcSpatializerRenderBinauralLowQuality, + /** + * 中复杂度双耳渲染(Binaural) + */ + kNERtcSpatializerRenderBinauralMediumQuality, + /** + * 高复杂度双耳渲染(Binaural) + */ + kNERtcSpatializerRenderBinauralHighQuality, + /** + * 仅房间音效 + */ + kNERtcSpatializerRenderRoomEffectsOnly +} NERtcSpatializerRenderMode; + +/** + * 空间音效衰减模式 + */ +typedef enum { + /** + * 指数衰减模式 + */ + kNERtcDistanceRolloffLogarithmic = 0, + /** + * 线性衰减模式 + */ + kNERtcDistanceRolloffLinear, + /** + * 无衰减 + */ + kNERtcDistanceRolloffNone, +} NERtcDistanceRolloffModel; + +/** 3D音效算法中坐标信息。*/ +struct NERtcPositionInfo { + /** + 发声坐标，三个值分别表示x-左右，y-上下，z-前后 + */ + float speaker_position[3]; + /** + 发声旋转角度四元数,设置为0 + */ + float speaker_quaternion[4]; + /** + 头部听觉坐标，三个值分别表示x-左右，y-上下，z-前后 + */ + float head_position[3]; + /** + 头部听觉旋转方向，表示头部的朝向，四元组格式 + */ + float head_quaternion[4]; + NERtcPositionInfo() { + memset(speaker_position, 0, sizeof(speaker_position)); + memset(speaker_quaternion, 0, sizeof(speaker_quaternion)); + memset(head_position, 0, sizeof(head_position)); + memset(head_quaternion, 0, sizeof(head_quaternion)); + } +}; + +/** 3D音效房间属性设置。*/ +struct NERtcSpatializerRoomProperty { + /** + * 房间大小 #NERtcSpatializerRoomCapacity ，默认值 #kNERtcSpatializerRoomCapacitySmall + */ + NERtcSpatializerRoomCapacity room_capacity; + /** + * 房间材质 #NERtcSpatializerMaterialName ，默认值 #kNERtcSpatializerMaterialTransparent + */ + NERtcSpatializerMaterialName material; + /** + * 反射系数的比例因子，默认值1.0, 取值范围[1.0 30] + */ + float reflection_scalar; + /** + * 混响增益比例因子，默认值1.0, 取值范围[1.0 10] + */ + float reverb_gain; + /** + * 混响时间比例因子，RT60会和该值相乘，默认值1.0(无效果), 取值范围[1.0 30] + */ + float reverb_time; + /** + * 混响亮度，该值为正且增加时，增加高频成分，该值为负数时衰减高频成分，默认值0.0(无效果), 取值范围[-30 30] + */ + float reverb_brightness; +}; + + +/** + * @if English + * Configure the SDK using a JSON file to provide technical preview or special custom functionalities. Standardize JSON options. + * For more information, see setParameters. * + * @endif + * @if Chinese + * 通过 JSON 配置 SDK 提供技术预览或特别定制功能。以标准化方式公开 JSON 选项。详见 API setParameters。 + * @endif + */ +/** + * @if English + * bool value. True: Record the presenter. False: Do not record the presenter. The setting is valid before the call. + * @endif + * @if Chinese + * bool value. true: 录制主讲人, false: 不是录制主讲人。通话前设置有效。 + * @endif + */ +#define kNERtcKeyRecordHostEnabled "record_host_enabled" +/** + * @if English + * bool value, which determines whether to enable server audio recording. The default value is false. The setting is valid + * before the call. + * @endif + * @if Chinese + * bool value，启用服务器音频录制。默认值 false。通话前设置有效。 + * @endif + */ +#define kNERtcKeyRecordAudioEnabled "record_audio_enabled" +/** + * @if English + * bool value, which determines whether to enable server video recording. The default value is false. The setting is valid + * before the call. + * @endif + * @if Chinese + * bool value，启用服务器视频录制。默认值 false。通话前设置有效。 + * @endif + */ +#define kNERtcKeyRecordVideoEnabled "record_video_enabled" +/** + * @if English + * int value, NERtcRecordType. The setting is valid before the call. + * @endif + * @if Chinese + * int value, NERtcRecordType。通话前设置有效。 + * @endif + */ +#define kNERtcKeyRecordType "record_type" +/** + * @if English + * bool value, which determines whether to automatically subscribe to the audio stream when other users open the audio. The + * default value is true. The setting is valid before the call. + * @endif + * @if Chinese + * bool value，其他用户打开音频时，自动订阅。默认值 true。通话前设置有效。 + * @endif + */ +#define kNERtcKeyAutoSubscribeAudio "auto_subscribe_audio" +/** + * @if English + * bool value, which determines whether to manually subscribe to the audio stream when other users open the audio on ASL mode. The + * default value is false. The setting is valid before the call. + * @endif + * @if Chinese + * bool value，在ASL模式下手动订阅音频。默认值 false。通话前设置有效。 + * @endif + */ +#define kNERtcKeyEnableAudioASLManualSubscribe "enable_audio_asl_manual_subscribe" +/** + * @if English + * bool value, which determines whether to enable CDN relayed streaming. The default value is true. The setting is valid before + * the call. + * @endif + * @if Chinese + * bool value，开启旁路直播。默认值 false。通话前设置有效。 + * @endif + */ +#define kNERtcKeyPublishSelfStreamEnabled "publish_self_stream_enabled" +/** + * @if English + * int value, NERtcLogLevel, SDK outputs logs that are of less than or equal to this level. The default is kNERtcLogLevelInfo. + * @endif + * @if Chinese + * int value, NERtcLogLevel，SDK 输出小于或等于该级别的 log，默认为 kNERtcLogLevelInfo。 + * @endif + */ +#define kNERtcKeyLogLevel "log_level" +/** + * @if English + * bool value. Disable or enable AEC. The default value is true. + * @endif + * @if Chinese + * bool value. AEC 开关，默认值 true。 + * @endif + */ +#define kNERtcKeyAudioProcessingAECEnable "audio_processing_aec_enable" +/** + * @if English + * bool value. Enable or disable low level AEC. The default value is false, The option takes effect only of + * kNERtcKeyAudioProcessingAECEnable is enabled. + * @endif + * @if Chinese + * bool value. low level AEC 开关，默认值 false，需要 kNERtcKeyAudioProcessingAECEnable 打开才生效。 + * @endif + */ +#define kNERtcKeyAudioAECLowLevelEnable "audio_aec_low_level_enable" +/** + * @if English + * bool value. Enable or disable AGC. The default value is true. + * @endif + * @if Chinese + * bool value. AGC 开关，默认值 true。 + * @endif + */ +#define kNERtcKeyAudioProcessingAGCEnable "audio_processing_agc_enable" +/** + * @if English + * bool value. Enable or disable NS. The default value is true. + * @endif + * @if Chinese + * bool value. NS 开关，默认值 true。 + * @endif + */ +#define kNERtcKeyAudioProcessingNSEnable "audio_processing_ns_enable" +/** + * @if English + * bool value. Enable or disable AI NS. We recommend that you modify this option before calls. The default value is false. + * @endif + * @if Chinese + * bool value. AI NS 开关，建议通话前修改，默认值 false。 + * @endif + */ +#define kNERtcKeyAudioProcessingAINSEnable "audio_processing_ai_ns_enable" +/** + * @if English + * bool value. Enable or disable the audio mixing. The default value is false. + * @endif + * @if Chinese + * bool value. 输入混音开关，默认值 false。 + * @endif + */ +#define kNERtcKeyAudioProcessingExternalAudioMixEnable "audio_processing_external_audiomix_enable" +/** + * @if English + * bool value, which determines whether to use an earphone. true: uses an earphone. false: does not use an earphone. The default + * value is false. + * @endif + * @if Chinese + * bool value. 通知 SDK 是否使用耳机， true: 使用耳机, false: 不使用耳机，默认值 false。 + * @endif + */ +#define kNERtcKeyAudioProcessingEarphone "audio_processing_earphone" +/** + * @if English + * int value. NERtcSendOnPubType. Sets the video sending strategy, and sends the mainstream by calling kNERtcSendOnPubHigh by + * default. The setting is valid before the call. + * @endif + * @if Chinese + * int value. NERtcSendOnPubType；设置视频发送策略，默认发送大流 kNERtcSendOnPubHigh。通话前设置有效。 + * @endif + */ +#define kNERtcKeyVideoSendOnPubType "video_sendonpub_type" +/** + * @if English + * bool value. Enable or disable the 1v1 mode. The default value is disabled. The setting is valid before the call. + * @endif + * @if Chinese + * bool value. 1v1 模式开关，默认关闭。通话前设置有效。 + * @endif + */ +#define kNERtcKeyChannel1V1ModeEnabled "channel_1v1_mode_enabled" +/** + * @if English + * string value. APP identification, used to identify the user's product name. + * @endif + * @if Chinese + * string value. APP 标识，用于后台识别用户产品名称。 + * @endif + */ +#define kNERtcKeyExtraInfo "extra_info" +/** + * @if English + * int value. Automatic audio device selection policy. The default value is 0. + * - 0: Default device priority + * - 1: Available device priority + * @endif + * @if Chinese + * 音频设备自动选择策略。int 类型。默认值为 0。 + * - 0：优先选择默认设备。 + * - 1：优先选择可用设备。 + * @endif + */ +#define kNERtcKeyAudioDeviceAutoSelectType "audio_device_auto_select_type" +/** + * @if English + * Whether to return original volume when the local user is muted. Boolean value, default: false. + * - true：Return the original volume in `onLocalAudioVolumeIndication`. + * - false：Return the recording volume(0) in `onLocalAudioVolumeIndication`. + * @endif + * @if Chinese + * 本地用户静音时是否返回原始音量。 布尔值，默认值为 false。 + * - true：返回 `onLocalAudioVolumeIndication` 中的原始音量。 + * - false：返回 `onLocalAudioVolumeIndication` 中的录音音量，静音时为 0。 + * @endif + */ +#define kNERtcKeyEnableReportVolumeWhenMute "enable_report_volume_when_mute" +/** + * @if English + * BOOL - Specifies whether to enable the callback to return captured video data. This enables developers to get the raw video data. You can clear the video data by calling destroyEngine. The default value is NO. + * @endif + * @if Chinese + * 是否需要开启视频数据采集回调，开启后开发者可以获取到原始视频数据。 + *
布尔值，默认值 NO。 + *
开启后如果需要关闭，需要通过调用 destroyEngine 来清除。 + * @endif + */ +#define kNERtcKeyEnableVideoCaptureObserver "enable_video_capture_observer" +/** + * @if English + * BOOL - Specifies whether to prefer using hardware to encode video data. The default value is YES. We recommend that you set + * this value before you call setupEngineWithContext to initialize the INERtcEngine instance. Otherwise, the setting is applied + * the next time. + * @endif + * @if Chinese + * 是否优先使用硬件编码视频数据。 + *
布尔值，默认值 YES。 + *
请在初始化（setupEngineWithContext）之前设置该参数，否则该参数会在下次初始化之后生效。 + * @endif + */ +#define kNERtcKeyVideoPreferHWEncode "video_prefer_hw_encode" +/** + * @if English + * BOOL - Specifies whether to prefer using hardware to decode video data. The default value is true. We recommend that you set + * this value before you call setupEngineWithContext to initialize the INERtcEngine instance. Otherwise, the setting is applied + * the next time. + * @endif + * @if Chinese + * 是否优先使用硬件解码视频数据。 + *
布尔值，默认值 true。 + *
请在初始化（setupEngineWithContext）之前设置该参数，否则该参数会在下次初始化之后生效。 + * @endif + */ +#define kNERtcKeyVideoPreferHWDecode "video_prefer_hw_decode" + +/** + * 是否使用动态token加入通话。 布尔值，默认值为 false。 + * @note 默认不使用动态token，该功能需要在通话前调用 + * - true：使用动态token。 + * - false：不使用动态token。 + */ +#define kNERtcKeyEnableDynamicToken "enable_dynamic_token" +/** + * @if English + * BOOL - Specifies whether to turn on the rear camera if the camera is enabled for the first time. The default value is false. + * It's available only on iOS platform. + * @endif + * @if Chinese + * 第一次开启摄像头时，是否使用后摄像头。仅iOS平台有效。 + *
布尔值，默认值 false，即不使用后置摄像头。 + * @endif + */ +#define kNERtcKeyVideoStartWithBackCamera "video_start_with_back_camera" +/** + * @if English + * BOOL - Specifies whether to use metal rendering first. Otherwise, OpenGL rendering is applied. The default value is + * false. It's available only on iOS platform. + * @endif + * @if Chinese + * 是否优先使用 Metal 渲染。 + *
布尔值，默认值 false，即使用OpenGL 渲染。仅iOS平台有效。 + * @endif + */ +#define kNERtcKeyVideoPreferMetalRender "video_prefer_metal_render" +/** + * @if English + * BOOL -- Specifies whether to disable switching to the speakerphone when the system switches to the earpieces. The + * default value is false. If the value is set to true, the SDK is not allowed to switch to the speakerphone when the system + * switches to earpieces. Users need to handle the earpieces switching event.It's available only on iOS platform. + * @endif + * @if Chinese + * 当系统切换听筒或扬声器时，SDK 是否以系统设置为准。仅iOS平台有效。 + *
布尔值，默认为 false。 + * - true： 以系统设置为准。例如当系统切换为听筒时，应用的音频播放则自动转为听筒，开发者需要自行处理该切换事件。 + * - false： 以 SDK 设置为准，SDK 不允许用户通过系统变更音频播放路由为听筒或扬声器。例如当 SDK + * 设置为扬声器时，即使系统切换为听筒模式，SDK 也会自动将系统修改回扬声器模式。 + * @endif + */ +#define kNERtcKeyDisableOverrideSpeakerOnReceiver "disable_override_speaker_on_receiver" +/** + * @if English + * BOOL - Specifies whether to use echo reduction when the system sets the headset. The default value is false. If the value is + * set to YES, the SDK does not use the echo reduction in headset mode. The setting affects the audio quality of the headset + * in some mobile models.It's available only on iOS platform. + * @endif + * @if Chinese + * 设置耳机时不使用软件回声消除功能，默认值 false。如设置YES 则SDK在耳机模式下不使用软件回声消除功能，会对某些机型下 + * 耳机的音质效果有影响。仅iOS平台有效。 + * @endif + */ +#define kNERtcKeyDisableSWAECOnHeadset "disable_sw_aec_on_headset" +/** + * @if English + * Whether to enable bluetooth SCO.The default value is true.It's available only on Android platform. + * @endif + * @if Chinese + * 是否关闭蓝牙SCO.默认打开。仅Android平台有效。 + * @endif + */ +#define kNERtcKeyEnableAudioBluetoothSCO "enable_audio_bluetooth_sco" +/** + * @if English + * Whether to preview the front camera with mirror mode. Default: true. The setting enables the mirror mode.It's available only + * on Android platform. + * @endif + * @if Chinese + * 前置摄像头预览是否采用镜像模式。默认为 true，开启镜像模式。仅Android平台有效。 + * @endif + */ +#define kNERtcKeyEnableVideoMirrorWithFrontCamera "enable_video_mirror_with_front_camera" +/** + * @if English + * Video camera type.The default value is 1.It's available only on Android platform. + * @endif + * @if Chinese + * 摄像头类型。默认值为1.取值范围为0(unknown), 1, 2.仅Android平台有效。 + * @endif + */ +#define kNERtcKeyVideoCameraType "video_camera_type" + +/** + * @if English + * Returns a bitmap file path when you take snapshot.The default value is false. + * @endif + * @if Chinese + * 调用TakeSnapshot截图时返回图片文件路径。默认值为false。 + * @endif + */ +#define kNERtcKeyEnableSnapshotWithFile "enable_snapshot_with_file" + +/** +* @if English +* Specifies whether to automatically subscribe to video streams when other users turn on video. +* The default value is NO. +* @note +* You can change the subscription stautus. Local subscription status will not be affected if remote users resume +sending the video stream; but local settings will resume to be default if remote users rejoin the room. +* This method is only valid for windows. +* The setting is applied before you make a call. The setting is invalid if you specify the value during the call. +* @endif +* @if Chinese +* 是否订阅其他用户的视频流。 +*
布尔值，默认值为 false。 +* @note +- 订阅状态可以更改。远端用户重新发布推流视频，不影响本地用户的订阅状态；但远端用户退出房间重进后，本地恢复默认设置。 +- 该接口仅 windows 下有效。 +- 请在加入房间前设置该参数，通话中设置无效。 +* @endif +*/ +#define kNERtcKeyAutoSubscribeVideo "auto_subscribe_video" + +/** +* @if English +* BOOL - Specifies whether to automatically subscribe to data channel when other users turn on data channel. The setting is +* applied before you make a call. The setting is invalid If you specify the value during the call. The default value is NO. +* Note: The key of subscribeRemoteData must be set to NO if you use the method to control the data in your business. +* @endif +* @if Chinese +* 是否自动订阅其他用户的数据通道。 +*
布尔值，默认为 NO，即非自动订阅。 +* @note +* - 请在加入房间前设置该参数，通话中设置无效。 +* - 如果业务场景中使用 subscribeData 控制数据订阅，则该 Key 必须设置为 NO。 +* @endif +*/ +#define kNERtcKeyAutoSubscribeData "auto_subscribe_data" + +/** +* @if English +* Specifies whether to disable video decoder, the default value is false. +* When disable video decoder (true), the SDK will not decode the remote video and therefore will not render the received remote +* video. This parameter must be set before IRtcEngine::initialize and becomes invalid after the SDK is released. Usually used +* with IRtcEngineEx::setPreDecodeObserver. +* @since 4.6.25 +* @endif +* @if Chinese +* 指定是否关闭视频解码器，默认不关闭（false）。 +* 关闭（true）后 SDK 将不会解码远端视频，因此也不会渲染接收到的远端视频。 +* 需要在初始化 IRtcEngine::initialize 前设置，释放 SDK 后失效。 +* 一般配合 IRtcEngineEx::setPreDecodeObserver 使用。 +* @since 4.6.25 +* @endif +*/ +#define kNERtcKeyDisableVideoDecoder "disable_video_decoder" + +/** +* @if Chinese +* 切换SDK内部渲染模式 +*
int，默认值0。 +* - 0：选择默认渲染(win:d3d,Mac:metal)。 +* - 1：Mac下使用OpenGL。 +* - 2：Mac下使用Metal。 +* - 3：windows下使用SDL2。 +* @endif +*/ +#define kNERtcKeyVideoRenderType "sdk.prefer.video.render" + +/** 音频设备错误码。*/ +typedef enum{ + kNERtcAudioDeviceNoError = 0, + kNERtcAudioDeviceErrorInitRecording, + kNERtcAudioDeviceErrorStartRecording, + kNERtcAudioDeviceErrorStopRecording, + kNERtcAudioDeviceErrorInitPlayout, + kNERtcAudioDeviceErrorStartPlayout, + kNERtcAudioDeviceErrorStopplayout, + kNERtcAudioDeviceErrorCaptureThreadStop, + kNERtcAudioDeviceErrorPlayoutThreadStop, + kNERtcAudioDeviceErrorCaptureSampleRate, + kNERtcAudioDeviceErrorPlayoutSampleRate, + kNERtcAudioDeviceErrorConfigSession, + kNERtcAudioDeviceErrorCodeReporter +}NERtcAudioDeviceError; + +/** 视频设备错误码。*/ +typedef enum { + kNERtcVideoDeviceErrorNoFrame = 0, + kNERtcVideoDeviceErrorNotAvailableInBackground, + kNERtcVideoDeviceErrorUsingByAnotherClient, + kNERtcVideoDeviceErrorNotAvailableWithMultipleForegroundApps, +} NERtcVideoDeviceError; + +/** 音频路由 仅iOS和Android有效*/ +typedef enum { + /** + * @if English + * Default + * @endif + * @if Chinese + * 系统默认 + * @endif + */ + kNERtcAudioOutputRoutingDefault = 0, + /** + * @if English + * Headset + * @endif + * @if Chinese + * 耳机 + * @endif + */ + kNERtcAudioOutputRoutingHeadset, + /** + * @if English + * Earpiece + * @endif + * @if Chinese + * 听筒 + * @endif + */ + kNERtcAudioOutputRoutingEarpiece, + /** + * @if English + * Loudspeaker + * @endif + * @if Chinese + * 扬声器 + * @endif + */ + kNERtcAudioOutputRoutingLoudspeaker, + /** + * @if English + * Bluetooth + * @endif + * @if Chinese + * 蓝牙外设 + * @endif + */ + kNERtcAudioOutputRoutingBluetooth, +} NERtcAudioOutputRouting; + +/** 网络类型 */ +typedef enum { + kNERtcNetworkTypeUnknown = 0, + kNERtcNetworkTypeEthernet, + kNERtcNetworkTypeWifi, + kNERtcNetworkType2G, + kNERtcNetworkType3G, + kNERtcNetworkType4G, + kNERtcNetworkType5G, + kNERtcNetworkTypeWWAN, + kNERtcNetworkTypeBluetooth, + kNERtcNetworkTypeNone +} NERtcNetworkType; + +struct NERtcCameraFocusAndExposureInfo { + float center_x; + float center_y; + int32_t left; + int32_t top; + int32_t right; + int32_t bottom; +}; +/** + * @if English + * Audio session control permissions + *
The SDK has the permissions of Audio Session. + * @endif + * @if Chinese + * 音频会话控制权限。 + *
SDK 对 Audio Session 的控制权限。 + * @endif + */ +typedef enum { + /** + * @if English + * The SDK has full permissions and can control the Audio Session + * @endif + * @if Chinese + * 没有限制，SDK 可以完全控制 Audio Session 操作。 + * @endif + */ + kNERtcAudioSessionOperationRestrictionNone = 0, + /** + * @if English + * If you restrict the SDK to perform operations on the Audio Session, the SDK cannot configure the Audio Session + * @endif + * @if Chinese + * 限制 SDK 对 Audio Session 进行任何操作，SDK 将不能再对 Audio Session 进行任何配置。 + * @endif + */ + kNERtcAudioSessionOperationRestrictionAll, + /** + * @if English + * When a user leaves the room, the SDK will keep the Audio Session active. + * @endif + * @if Chinese + * 离开房间时，SDK 会保持 Audio Session 处于活动状态。 + * @endif + */ + kNERtcAudioSessionOperationRestrictionDeactivateSession, +} NERtcAudioSessionOperationRestriction; + +/** + * @if English + * Audio focus mode（Android only）. + * @endif + * @if Chinese + * 音频焦点模式（Android only）。 + * @endif + */ +typedef enum { + /** + * @if English + * No request for audio focus. + * @endif + * @if Chinese + * 不请求音频焦点。 + * @endif + */ + kNERtcAudioFocusOff = 0, + /** + * @if English + * Gains the audio focus in a long period. + * @endif + * @if Chinese + * 长时间获得焦点。 + * @endif + */ + kNERtcAudioFocusGain = 1, + + /** + * @if English + * Gains transient audio focus. Release the focus after losing it. Such as notification sounds. + * @endif + * @if Chinese + * 短暂性获得焦点，用完应立即释放，比如notification sounds。 + * @endif + */ + kNERtcAudioFocusGainTransient = 2, + + /** + * @if English + * Temporary requests for lowering the volume of other audio applications. Mixable playback is supportable. + * @endif + * @if Chinese + * 临时请求, 降低其他音频应用的声音，可混音播放。 + * @endif + */ + kNERtcAudioFocusGainTransientMayDuck = 3, + + /** + * @if English + * Gains transient audio focus to enable recording or audio recognition. + * @endif + * @if Chinese + * 短暂性获得焦点，录音或者语音识别。 + * @endif + */ + kNERtcAudioFocusGainTransientExclisive = 4, +}NERtcAudioFocusMode; + +/** +* @if English +* Position of a specified camera. +* @endif +* @if Chinese +* 指定的摄像头位置。 +* @endif +*/ +typedef enum { + /** + * @if English + * Front camera. + * @endif + * @if Chinese + * 前置摄像头。 + * @endif + */ + kNERtcCameraPositionBack = 0, + + /** + * @if English + * Rear camera. + * @endif + * @if Chinese + * 后置摄像头。 + * @endif + */ + kNERtcCameraPositionFront +}NERtcCameraPosition; + +/** + * @if Chinese + * 二维坐标点。 + * @endif + */ +struct NERtcPoint { + /** + * @if Chinese + * x 轴坐标。 + * @endif + */ + float x; + /** + * @if Chinese + * y轴坐标值。 + * @endif + */ + float y; +}; +/** + * @if English + * Video correction configuration + * @endif + * @if Chinese + * 视频图像畸变矫正相关设置。 + * @endif + */ +struct NERtcVideoCorrectionConfiguration { + /** + * @if Chinese + * 矫正区域的左上顶点（x 和 y 的取值范围为 0 ~ 1 的浮点数） + * @endif + */ + NERtcPoint top_left; + /** + * @if Chinese + * 矫正区域的右上顶点（x 和 y 的取值范围为 0 ~ 1 的浮点数） + * @endif + */ + NERtcPoint top_right; + /** + * @if Chinese + * 矫正区域的左下顶点（x 和 y 的取值范围为 0 ~ 1 的浮点数） + * @endif + */ + NERtcPoint bottom_left; + /** + * @if Chinese + * 矫正区域的右下顶点（x 和 y 的取值范围为 0 ~ 1 的浮点数） + * @endif + */ + NERtcPoint bottom_right; + /** + * @if Chinese + * 画布宽度（单位 px，使用外部视频渲染时需要传递） + * @endif + */ + float canvas_width; + /** + * @if Chinese + * 画布高度（单位 px，使用外部视频渲染时需要传递） + * @endif + */ + float canvas_height; + /** + * @if Chinese + * 是否镜像显示（使用外部视频渲染时需要传递） + * @endif + */ + bool enable_mirror; +}; +}// namespace nertc diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/NertcErrorCode.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/NertcErrorCode.h new file mode 100644 index 0000000..bee7816 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/NertcErrorCode.h @@ -0,0 +1,983 @@ +/** @file NERtcErrorCode.h + * @brief The definition of error codes of NERtc SDK. + * @copyright (c) 2021, NetEase Inc. All rights reserved. + */ + +#pragma once + +/** + * @namespace nertc + * @brief namespace nertc + */ +namespace nertc { +/** + * @if English + * Error codes. + *
Error codes are returned when a problem that cannot be recovered without app intervention has occurred. + * @endif + * @if Chinese + * 错误代码。 + *
错误代码意味着 SDK 遇到不可恢复的错误，需要应用程序干预。 + * @endif + */ +typedef enum { + /** + * @if English + * No errors. + * @endif + * @if Chinese + * 没有错误 + * @endif + */ + kNERtcNoError = 0, + //Error codes are returned when resources are wrongly assigned. Such kind of error code is not returned when the SDK sends the normal permissions. + /** + * @if English + * No permissions. Possible reasons: + * - Audio and Video Call is not enabled, whose trial period is overdue or fees are not renewed. + * - Token is not specified in safe mode when joining a channel. + * - Other permission-related problems. + * @endif + * @if Chinese + * - 权限不足。原因包括： + * - 未开通音视频通话 2.0 服务，或试用期已过、未及时续费等。 + * - 安全模式下加入房间时未设置 Token。 + * - 其他权限问题。 + * @endif + */ + kNERtcErrChannelReservePermissionDenied = 403, + /** + * @if English + * Request timeouts. + * @endif + * @if Chinese + * 请求超时 + * @endif + */ + kNERtcErrChannelReserveTimeOut = 408, + /** + * @if English + * Error codes are returned when parameters are requested in the server. + * @endif + * @if Chinese + * 服务器请求参数错误 + * @endif + */ + kNERtcErrChannelReserveErrorParam = 414, + /** + * @if English + * Invalid APP KEY. + * @endif + * @if Chinese + * 非法的APP KEY + * @endif + */ + kNERtcErrChannelReserveErrorAppKey = 417, + /** + * @if English + * Unknown errors are returned when channels are assigned in the server. + * @endif + * @if Chinese + * 分配房间服务器未知错误 + * @endif + */ + kNERtcErrChannelReserveServerFail = 500, + /** + * @if English + * Only two users are supported in the same channel. If the third user wants to share the same channel name, assign another channel. + * @endif + * @if Chinese + * 只支持两个用户, 有第三个人试图使用相同的房间名分配房间 + * @endif + */ + kNERtcErrChannelReserveMoreThanTwoUser = 600, + /** + * @if Chinese + * 权限密钥错误 + * @endif + */ + kNERtcErrChannelPermissionKeyError = 901, + /** + * @if Chinese + * 权限密钥超时 + * @endif + */ + kNERtcErrChannelPermissionKeyTimeout = 902, + + //livestream task + /** + * @if English + * Invalid permission that is replaced by following operations. + * @endif + * @if Chinese + * task请求无效，被后续操作覆盖 + * @endif + */ + kNERtcErrLsTaskRequestInvalid = 1301, + /** + * @if English + * Parameter format error. + * @endif + * @if Chinese + * task参数格式错误 + * @endif + */ + kNERtcErrLsTaskIsInvaild = 1400, + /** + * @if English + * Exited the channel. + * @endif + * @if Chinese + * 房间已经退出 + * @endif + */ + kNERtcErrLsTaskRoomExited = 1401, + /** + * @if English + * Streaming tasks are over the limit. + * @endif + * @if Chinese + * 推流任务超出上限 + * @endif + */ + kNERtcErrLsTaskNumLimit = 1402, + /** + * @if English + * Duplicates ID of streaming tasks. + * @endif + * @if Chinese + * 推流ID重复 + * @endif + */ + kNERtcErrLsTaskDuplicateId = 1403, + /** + * @if English + * No ID task or no channels. + * @endif + * @if Chinese + * taskId任务不存在，或房间不存在 + * @endif + */ + kNERtcErrLsTaskNotFound = 1404, + /** + * @if English + * Permission failures. + * @endif + * @if Chinese + * 请求失败 + * @endif + */ + kNERtcErrLsTaskRequestErr = 1417, + /** + * @if English + * Internal errors in the server. + * @endif + * @if Chinese + * 服务器内部错误 + * @endif + */ + kNERtcErrLsTaskInternalServerErr = 1500, + /** + * @if English + * Layout parameter errors. + * @endif + * @if Chinese + * 布局参数错误 + * @endif + */ + kNERtcErrLsTaskInvalidLayout = 1501, + /** + * @if English + * Image errors of users. + * @endif + * @if Chinese + * 用户图片错误 + * @endif + */ + kNERtcErrLsTaskUserPicErr = 1512, + /** + * @if Chinese + * 没有发布权限 + * @endif + */ + kNERtcErrChannelNoPublishPermission = 1620, + /** + * @if Chinese + * 没有订阅权限 + * @endif + */ + kNERtcErrChannelNoSubscribePermission = 2803, + /** + * @if Chinese + * 加入房间的人数达到限制 + * @endif + */ + kNERtcErrServerPersonsInRoomReachedTheLimit = 4003, + + /** + * @if English + * Common errors. + * @endif + * @if Chinese + * 通用错误 + * @endif + */ + kNERtcErrFatal = 30001, + /** + * @if English + * Out of memory. + * @endif + * @if Chinese + * 内存耗尽 + * @endif + */ + kNERtcErrOutOfMemory = 30002, + /** + * @if English + * Invalid parameters. + * @endif + * @if Chinese + * 错误的参数 + * @endif + */ + kNERtcErrInvalidParam = 30003, + /** + * @if English + * Unsupported operation. + * @endif + * @if Chinese + * 不支持的操作 + * @endif + */ + kNERtcErrNotSupported = 30004, + /** + * @if English + * Unsupported operations in the current state. + * @endif + * @if Chinese + * 当前状态不支持的操作 + * @endif + */ + kNERtcErrInvalidState = 30005, + /** + * @if English + * Depleted resources. + * @endif + * @if Chinese + * 资源耗尽 + * @endif + */ + kNERtcErrLackOfResource = 30006, + /** + * @if English + * Invalid index. + * @endif + * @if Chinese + * 非法 index + * @endif + */ + kNERtcErrInvalidIndex = 30007, + /** + * @if English + * Device is not found. + * @endif + * @if Chinese + * 设备未找到 + * @endif + */ + kNERtcErrDeviceNotFound = 30008, + /** + * @if English + * Invalid device ID. + * @endif + * @if Chinese + * 非法设备 ID + * @endif + */ + kNERtcErrInvalidDeviceSourceID = 30009, + /** + * @if English + * Invalid profile type of video. + * @endif + * @if Chinese + * 非法的视频 profile type + * @endif + */ + kNERtcErrInvalidVideoProfile = 30010, + /** + * @if English + * Device creation errors. + * @endif + * @if Chinese + * 设备创建错误 + * @endif + */ + kNERtcErrCreateDeviceSourceFail = 30011, + /** + * @if English + * Invalid rendering device. + * @endif + * @if Chinese + * 非法的渲染容器 + * @endif + */ + kNERtcErrInvalidRender = 30012, + /** + * @if English + * Device is already enabled. + * @endif + * @if Chinese + * 设备已经打开 + * @endif + */ + kNERtcErrDevicePreviewAlreadyStarted = 30013, + /** + * @if English + * Transmission error. + * @endif + * @if Chinese + * 传输错误 + * @endif + */ + kNERtcErrTransmitPendding = 30014, + /** + * @if English + * Server connection error. + * @endif + * @if Chinese + * 连接服务器错误 + * @endif + */ + kNERtcErrConnectFail = 30015, + /** + * @if English + * Fails to create Audio dump file. + * @endif + * @if Chinese + * 创建Audio dump文件失败 + * @endif + */ + kNERtcErrCreateDumpFileFail = 30016, + /** + * @if English + * Fails to enable Audio dump file. + * @endif + * @if Chinese + * 开启Audio dump失败 + * @endif + */ + kNERtcErrStartDumpFail = 30017, + /** + * @if English + * Fails to enable desktop screen recording if camera is started at the same time. + * @endif + * @if Chinese + * 启动桌面录屏失败，不能与camera同时启动 + * @endif + */ + kNERtcErrDesktopCaptureInvalidState = 30020, + /** + * @if English + * Parameters are invalid when the desktop screen recording is implemented. + * @endif + * @if Chinese + * 桌面录屏传入参数无效 + * @endif + */ + kNERtcErrDesktopCaptureInvalidParam = 30021, + /** + * @if English + * Desktop screen recording is not ready. + * @endif + * @if Chinese + * 桌面录屏未就绪 + * @endif + */ + kNERtcErrDesktopCaptureNotReady = 30022, + /** + * @if English + * Selected device is occupied. + * @endif + * @if Chinese + * 所选设备已被占用 + * @endif + */ + kNERtcErrDeviceOccupied = 30027, + /** + * @if English + * Repeatedly joins the channel. + * @endif + * @if Chinese + * 重复加入房间 + * @endif + */ + kNERtcErrChannelAlreadyJoined = 30100, + /** + * @if English + * Does not join the channel. + * @endif + * @if Chinese + * 尚未加入房间 + * @endif + */ + kNERtcErrChannelNotJoined = 30101, + /** + * @if English + * Repeatedly leaves the channel. + * @endif + * @if Chinese + * 重复离开房间 + * @endif + */ + kNERtcErrChannelRepleatedlyLeave = 30102, + /** + * @if English + * Fails to join the channel. + * @endif + * @if Chinese + * 加入房间操作失败 + * @endif + */ + kNERtcErrRequestJoinChannelFail = 30103, + /** + * @if English + * Session is not found. + * @endif + * @if Chinese + * 会话未找到 + * @endif + */ + kNERtcErrSessionNotFound = 30104, + /** + * @if English + * The user is not found. + * @endif + * @if Chinese + * 用户未找到 + * @endif + */ + kNERtcErrUserNotFound = 30105, + /** + * @if English + * Invalid user ID. + * @endif + * @if Chinese + * 非法的用户 ID + * @endif + */ + kNERtcErrInvalidUserID = 30106, + /** + * @if English + * Users do not connect the multi-media data. + * @endif + * @if Chinese + * 用户多媒体数据未连接 + * @endif + */ + kNERtcErrMediaNotStarted = 30107, + /** + * @if English + * Source is not found. + * @endif + * @if Chinese + * source 未找到 + * @endif + */ + kNERtcErrSourceNotFound = 30108, + /** + * @if English + * Invalid state of switching channels. + * @endif + * @if Chinese + * 切换房间状态无效 + * @endif + */ + kNERtcErrSwitchChannelInvalidState = 30109, + /** + * @if English + * Invalid state of relaying media streams. + * @endif + * @if Chinese + * 重复调用 startChannelMediaRelay。 + * @endif + */ + kNERtcErrChannelMediaRelayInvalidState = 30110, + /** + * @if English + * Invalid permissions of relaying streams. Check whether the mode is set as audience mode or 1v1 mode. + * @endif + * @if Chinese + * 媒体流转发权限不足。例如调用 startChannelMediaRelay 的房间成员为主播角色、或房间为双人通话房间，不支持转发媒体流。 + * @endif + */ + kNERtcErrChannelMediaRelayPermissionDenied = 30111, + /** + * @if English + * If you fail to stop relaying media streams, check whether the media stream forwarding is enabled. + * @endif + * @if Chinese + * 调用 stopChannelMediaRelay 前，未调用 startChannelMediaRelay。 + * @endif + */ + kNERtcErrChannelMediaRelayStopFailed = 30112, + /** + * @if English + * If you set the different encryption password of media streams from other members in the room, you fail to join the room. + * Sets new encryption password thorough enableEncryption. + * @endif + * @if Chinese + * 设置的媒体流加密密钥与房间中其他成员不一致，加入房间失败。请通过 enableEncryption 重新设置加密密钥。 + * @endif + */ + kNERtcErrEncryptNotSuitable = 30113, + /** + * @if English + * User permkey auth failed. + * @endif + * @if Chinese + * 用户权限验证错误 + * @endif + */ + kNERtcErrUserPermKeyAuthFailed = 30121, + + kNERtcErrSEIExceedMaxDataLimit = 30122, /** SEI 超过最大数据限制 */ + /** + * @if Chinese + * 数据通道发送大小超过最大限制 + * @endif + */ + kNERtcErrDataChannelExceedMaxDataLimit = 30123, + /** + * @if English + * Connection is not found. + * @endif + * @if Chinese + * 连接未找到 + * @endif + */ + kNERtcErrConnectionNotFound = 30200, + /** + * @if English + * Media streams are not found. + * @endif + * @if Chinese + * 媒体流未找到 + * @endif + */ + kNERtcErrStreamNotFound = 30201, + /** + * @if English + * Fails to join the track. + * @endif + * @if Chinese + * 加入 track 失败 + * @endif + */ + kNERtcErrAddTrackFail = 30202, + /** + * @if English + * Track is not found. + * @endif + * @if Chinese + * track 未找到 + * @endif + */ + kNERtcErrTrackNotFound = 30203, + /** + * @if English + * Media disconnection. + * @endif + * @if Chinese + * 媒体连接断开 + * @endif + */ + kNERtcErrMediaConnectionDisconnected = 30204, + /** + * @if English + * Signalling disconnection. + * @endif + * @if Chinese + * 信令连接断开 + * @endif + */ + kNERtcErrSignalDisconnected = 30205, + /** + * @if English + * The user is removed from the room. + * @endif + * @if Chinese + * 被踢出房间 + * @endif + */ + kNERtcErrServerKicked = 30206, + /** + * @if English + * Removed for the channel is already disabled. + * @endif + * @if Chinese + * 因房间已关闭而被踢出 + * @endif + */ + kNERtcErrKickedForRoomClosed = 30207, + /** + * @if English + * A room is closed when a user switches to another room. + * @endif + * @if Chinese + * 因为切换房间的操作房间被关闭 + * @endif + */ + kNERtcErrChannelLeaveBySwitchAction = 30208, + /** + * @if English + * A room is closed due to duplicates user IDs + * @endif + * @if Chinese + * 因为有重复 uid 登录导致房间被关闭 + * @endif + */ + kNERtcErrChannelLeaveByDuplicateUidLogin = 30209, + + /** + * @if English + * No permission of audio devices. + * @endif + * @if Chinese + * 没有音频设备权限 + * @endif + */ + kNERtcRuntimeErrADMNoAuthorize = 40000, + /** + * @if English + * Audio device module: Errors occur when initializing recording devices. Please check whether the recording device can work properly or have limited permissions, or try reconnecting to rejoin the room. + * @endif + * @if Chinese + * 音频设备模块：初始化录音设备时出现错误。请检查录音设备是否正常或者权限限制，或者尝试重新进入房间。 + * @endif + */ + kNERtcRuntimeErrADMInitRecording = 40001, + /** + * @if English + * Audio device module: Errors occur when enabling recording devices. Please check whether the recording device can work properly, or try reconnecting to rejoin the room. + * @endif + * @if Chinese + * 音频设备模块：启动录音设备出现错误。请检查录音设备是否正常，或者尝试重新进入房间。 + * @endif + */ + kNERtcRuntimeErrADMStartRecording = 40002, + /** + * @if English + * Audio device module: Errors occur when running recording devices. Please check whether the recording device can work properly, or try reconnecting to rejoin the room. + * @endif + * @if Chinese + * 音频设备模块：运行时录音错误。请检查录音设备是否正常，或者尝试重新进入房间。 + * @endif + */ + kNERtcRuntimeErrADMStopRecording = 40003, + /** + * @if English + * Audio device module: Errors occur when initializing playback devices. Please check whether the playback device can work properly or have limited permissions, or try reconnecting to rejoin the room. + * @endif + * @if Chinese + * 音频设备模块：初始化播放设备出现错误。请检查播放设备是否异常或者权限限制，或者尝试重新进入房间。 + * @endif + */ + kNERtcRuntimeErrADMInitPlayout = 40004, + /** + * @if English + * Audio device module: Errors occur when enabling playback devices. Please check whether the playback device can work properly, or try reconnecting to rejoin the room. + * @endif + * @if Chinese + * 音频设备模块：启动播放设备出现错误。请检查播放设备是否正常，或者尝试重新进入房间。 + * @endif + */ + kNERtcRuntimeErrADMStartPlayout = 40005, + /** + * @if English + * Audio device module: Errors occur when running playback devices. Please check whether the playback device can work properly, or try reconnecting to rejoin the room. + * @endif + * @if Chinese + * 音频设备模块：运行时播放出现错误。请检查播放设备是否正常，或者尝试重新进入房间。 + * @endif + */ + kNERtcRuntimeErrADMStopPlayout = 40006, + + /** 音频采集设备运行异常 */ + kNERtcRuntimeErrADMRecordingFailed = 40007, + /** 音频播放设备运行异常 */ + kNERtcRuntimeErrADMPlayoutFailed = 40008, + + /** + * @if English + * No permission of video devices. + * @endif + * @if Chinese + * 没有视频设备权限 + * @endif + */ + kNERtcRuntimeErrVDMNoAuthorize = 50000, + /** + * @if English + * Use substream without the screen-sharing stream + * @endif + * @if Chinese + * 非屏幕共享使用辅流 + * @endif + */ + + kNERtcRuntimeErrVDMNotScreenUseSubStream = 50001, + /** 摄像头断开 */ + kNERtcRuntimeErrVDMCameraDisconnect = 50303, + /** 摄像头死机*/ + kNERtcRuntimeErrVDMCameraFreezed = 50304, + /** 未知摄像头错误 */ + kNERtcRuntimeErrVDMCameraUnknownError = 50305, + /** 摄像头无数据帧。请检查摄像头或者切换摄像头 */ + kNERtcRuntimeErrVDMCameraNoFrame = 50306, + /** 摄像头启动失败。请检查摄像头是否存在或被占用 */ + kNERtcRuntimeErrVDMCameraCreateFail = 50307, + /** + * @if English + * No permission of video recording. + * @endif + * @if Chinese + * 没有录制视频权限 + * @endif + */ + kNERtcRuntimeErrScreenCaptureNoAuthorize = 50400, +} NERtcErrorCode; + +/** + * @if English + * @enum NERtcRoomServerErrorCode The related error codes of room server. TODO:NERtcErrorCode. + * + * @endif + * @if Chinese + * @enum NERtcRoomServerErrorCode room server相关错误码。TODO：NERtcErrorCode + * @endif + */ +typedef enum { + /** + * @if English + * Successful operation. + * @endif + * @if Chinese + * 操作成功 + * @endif + */ + kNERtcRoomServerErrOK = 200, + /** + * @if English + * Authentication error. + * @endif + * @if Chinese + * 认证错误 + * @endif + */ + kNERtcRoomServerErrAuthError = 401, + /** + * @if English + * Channel is not found. + * @endif + * @if Chinese + * 房间不存在 + * @endif + */ + kNERtcRoomServerErrChannelNotExist = 404, + /** + * @if English + * The uid of the channel is not found. + * @endif + * @if Chinese + * 房间下的uid不存在 + * @endif + */ + kNERtcRoomServerErrUidNotExist = 405, + /** + * @if English + * Request data error. + * @endif + * @if Chinese + * 请求数据不对 + * @endif + */ + kNERtcRoomServerErrDataError = 417, + /** + * @if English + * Internal error that request error occurs in the TurnServer. + * @endif + * @if Chinese + * 内部错误（TurnServer请求异常） + * @endif + */ + kNERtcRoomServerErrUnknown = 500, + /** + * @if English + * Internal errors in the server. + * @endif + * @if Chinese + * 服务器内部错误 + * @endif + */ + kNERtcRoomServerErrServerError = 600, + /** + * @if English + * Invalid operation. + * @endif + * @if Chinese + * 无效的操作 + * @endif + */ + kNERtcRoomServerErrInvilid = 11403, +} NERtcRoomServerErrorCode; + +/** @enum nertc_audio_mixing_error_code 混音音乐文件错误码。 +*/ +typedef enum { + /** + * @if English + * No error. + * @endif + * @if Chinese + * 没有错误。 + * @endif + */ + kNERtcAudioMixingErrorOK = 0, + /** + * @if English + * Common error. + * @endif + * @if Chinese + * 通用错误。 + * @endif + */ + kNERtcAudioMixingErrorFatal = 1, + /** + * @if English + * Audio mixing is not enabled normally. + * @endif + * @if Chinese + * 伴音不能正常打开 + * @endif + */ + kNERtcAudioMixingErrorCanNotOpen, + /** + * @if English + * Audio decoding error. + * @endif + * @if Chinese + * 音频解码错误 + * @endif + */ + kNERtcAudioMixingErrorDecode, + /** + * @if English + * Interruption codes in the operation. + * @endif + * @if Chinese + * 操作中断码 + * @endif + */ + kNERtcAudioMixingErrorInterrupt, + /** + * @if English + * 404 file not found，only for http / https. + * @endif + * @if Chinese + * 404 file not found，only for http / + * @endif + */ + kNERtcAudioMixingErrorHttpNotFound, + /** + * @if English + * Fails to enable streams/files. + * @endif + * @if Chinese + * 打开流 / 文件失败 + * @endif + */ + kNERtcAudioMixingErrorOpen, + /** + * @if English + * Decoding information failures or timeouts. + * @endif + * @if Chinese + * 获取解码信息失败 / 超时 + * @endif + */ + kNERtcAudioMixingErrorNInfo, + /** + * @if English + * No audio streams. + * @endif + * @if Chinese + * 无音频流 + * @endif + */ + kNERtcAudioMixingErrorNStream, + /** + * @if English + * No decoder. + * @endif + * @if Chinese + * 无解码器 + * @endif + */ + kNERtcAudioMixingErrorNCodec, + /** + * @if English + * No memory. + * @endif + * @if Chinese + * 无内存 + * @endif + */ + kNERtcAudioMixingErrorNMem, + /** + * @if English + * Failures or timeouts of enabling decoders. + * @endif + * @if Chinese + * 解码器打开失败 / 超时 + * @endif + */ + kNERtcAudioMixingErrorCodecOpen, + /** + * @if English + * Invalid audio parameters such as channels and sample rate. + * @endif + * @if Chinese + * 无效音频参数（声道、采样率） + * @endif + */ + kNERtcAudioMixingErrorInvalidInfo, + /** + * @if English + * Streams/files enabling timeouts. + * @endif + * @if Chinese + * 打开流 / 文件超时 + * @endif + */ + kNERtcAudioMixingErrorOpenTimeout, + /** + * @if English + * Network io timeouts. + * @endif + * @if Chinese + * 网络io超时 + * @endif + */ + kNERtcAudioMixingErrorIoTimeout, + /** + * @if English + * Network io errors. + * @endif + * @if Chinese + * 网络io错误 + * @endif + */ + kNERtcAudioMixingErrorIo, +} NERtcAudioMixingErrorCode; + +} // namespace nertc diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/NertcPlugin.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/NertcPlugin.h new file mode 100644 index 0000000..78d0f26 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/NertcPlugin.h @@ -0,0 +1,18 @@ +// Copyright Epic Games, Inc. All Rights Reserved. + +#pragma once + +#include "Modules/ModuleManager.h" + +class FNertcPluginModule : public IModuleInterface +{ +public: + + /** IModuleInterface implementation */ + virtual void StartupModule() override; + virtual void ShutdownModule() override; + +private: + /** Handle to the test dll we will load */ + void* NertcDllHandler; +}; diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/NertcWarnCode.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/NertcWarnCode.h new file mode 100644 index 0000000..0408d17 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/NertcPlugin/Public/NertcWarnCode.h @@ -0,0 +1,58 @@ +/** @file nertc_warn_code.h + * @brief The definition of error codes of NERtc SDK. + * @copyright (c) 2021 NetEase, Inc. All rights reserved. + */ + +#pragma once + +/** + * @namespace nertc + * @brief namespace nertc + */ +namespace nertc { +/** + * @if English + * Warning code. + * If the warning code occurs, the SDK reports an error that is likely to be solved. The warning code just informs you of the + * SDK status. In most cases, the application programs can pass the warning code. + * @endif + * @if Chinese + * 警告代码。 + * 警告代码意味着 SDK 遇到问题，但有可能恢复，警告代码仅起告知作用，一般情况下应用程序可以忽略警告代码。 + * @endif + */ +typedef enum +{ + /** + * @if English + * No warning. + * @endif + * @if Chinese + * 未发生警告。 + * @endif + */ + kLiteSDKNoWarning = 0, + /** + * @if English + * The Client has no capability of device encoding and decoding to match that of the channel. For example, the device cannot encode in VP8 and other formats. Therefore, you may cannot implement video encoding and decoding in the channel. The local side may cannot display some remote video screens and the remote side may cannot display local screens. + * @endif + * @if Chinese + * 当前客户端设备视频编解码能力与房间不匹配，例如设备不支持 VP8 等编码类型。在此房间中可能无法成功进行视频编解码，即本端可能无法正常显示某些远端的视频画面，同样远端也可能无法显示本端画面。 + * @endif + */ + kNERtcWarningChannelAbilityNotMatch = 406, + /** + * @if English + * audio asl fallback + * @endif + * @if Chinese + * 音频自动选路回退 + * @endif + */ + kNERtcWarningASLAudioFallback = 407, + + + +} NERtcWarnCode; + +} // namespace nertc diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/Nertc.Build.cs b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/Nertc.Build.cs new file mode 100644 index 0000000..6b5095c --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/Nertc.Build.cs @@ -0,0 +1,135 @@ +using System; +using System.IO; +using UnrealBuildTool; +using System.Collections.Generic; +using System.Linq; + +public class Nertc : ModuleRules +{ + public Nertc(ReadOnlyTargetRules Target) : base(Target) + { + Console.WriteLine("#### Engine Version : " + Target.Version.MajorVersion + "." + Target.Version.MinorVersion); + Console.WriteLine("#### Target : " + Target.Platform); + Type = ModuleType.External; + if (Target.Platform == UnrealTargetPlatform.Win64) + { + LoadWindowsLibrary(Path.Combine(ModuleDirectory, "Win", "x64", "Release")); + } + else if (Target.Platform == UnrealTargetPlatform.Win32) + { + //LoadWindowsLibrary(Path.Combine(ModuleDirectory, "Win", "Release", "x86")); + } + else if (Target.Platform == UnrealTargetPlatform.Android) + { + LoadAndroidLibrary(Path.Combine(ModuleDirectory, "Android", "Release")); + } + else if (Target.Platform == UnrealTargetPlatform.IOS) + { + LoadIOSLibrary(Path.Combine(ModuleDirectory, "IOS", "Release")); + } + else if (Target.Platform == UnrealTargetPlatform.Mac) + { + LoadMacLibrary(Path.Combine(ModuleDirectory, "MAc", "Release")); + } + } + public void LoadMacLibrary(string librarypath) + { + string[] dirstr = Directory.GetDirectories(librarypath); + for (int i = 0; i < dirstr.Length; i++) + { + string frameworkName = Path.GetFileName(dirstr[i]); + if (frameworkName.Contains(".framework")) + { + PublicFrameworks.Add(Path.Combine(librarypath, frameworkName)); + } + Console.WriteLine("PublicFrameworks Add " + frameworkName); + } + } + + public void LoadIOSLibrary(string librarypath) + { + var fileNames = GetAllFileNames(librarypath); + for (int i = 0; i < fileNames.Count; i++) + { + Console.WriteLine("#### i: " + fileNames[i]); + string filename = fileNames[i]; + string extension = Path.GetExtension(filename); + if (extension == ".zip") + { + string filenamWithoutExtension = Path.GetFileNameWithoutExtension(filename); + string filenamWithoutFrameWork = Path.GetFileNameWithoutExtension(filenamWithoutExtension); + PublicAdditionalFrameworks.Add(new Framework(filenamWithoutFrameWork, Path.Combine(librarypath, filename), "")); + } + Console.WriteLine("PublicAdditionalFrameworks Add " + filename); + } + + string pluginPath = Path.Combine(ModuleDirectory,Target.RelativeEnginePath); + Console.WriteLine("pluginPath:" + pluginPath); + Console.WriteLine("librarypath:" + librarypath); + AdditionalPropertiesForReceipt.Add("IOSPlugin", Path.Combine(librarypath, "APL_IOS.xml")); + PublicFrameworks.AddRange(new string[] { "CoreML", "VideoToolbox", "Accelerate", "CFNetwork", "OpenGLES", "CoreTelephony" }); + } + + private string soFormatStr = " "; + public void LoadAndroidLibrary(string librarypath) + { + string xmlTemplateData = File.ReadAllText(Path.Combine(librarypath, "APL_armv7Template.xml")); + string[] Architectures = { "armeabi-v7a", "arm64-v8a" }; + string sopathwrite = ""; + for (int i = 0; i < Architectures.Length; i++) + { + string architecturespath = Path.Combine(librarypath, Architectures[i]); + List fileNames = GetAllFileNames(architecturespath); + for (int j = 0; j < fileNames.Count; j++) + { + string filename = fileNames[j]; + string extension = Path.GetExtension(filename); + if (extension == ".so") + { + string sopath = string.Format(soFormatStr, filename); + if(!sopathwrite.Contains(sopath)) + { + sopathwrite += sopath + "\r\n"; + } + PublicAdditionalLibraries.Add(Path.Combine(architecturespath, filename)); + Console.WriteLine("PublicAdditionalLibraries " + filename); + } + } + } + sopathwrite += " " + "\r\n"; + xmlTemplateData = xmlTemplateData.Replace("", sopathwrite); + File.WriteAllText(Path.Combine(librarypath, "APL_armv7.xml"), xmlTemplateData); + AdditionalPropertiesForReceipt.Add("AndroidPlugin", Path.Combine(librarypath, "APL_armv7.xml")); + } + public void LoadWindowsLibrary(string librarypath) + { + List fileNames = GetAllFileNames(librarypath); + for (int i = 0; i < fileNames.Count; i++) + { + string filename = fileNames[i]; + + string extension = Path.GetExtension(filename); + if (extension == ".lib") + { + PublicAdditionalLibraries.Add(Path.Combine(librarypath, filename)); + Console.WriteLine("AdditionalLibraries Add" + filename); + } + else if (extension == ".dll") + { + PublicDelayLoadDLLs.Add(Path.Combine(librarypath, filename)); + Console.WriteLine("DelayLoadDLL Add" + filename); + } + + RuntimeDependencies.Add(Path.Combine("$(ProjectDir)/Binaries/", Target.Platform + "", filename), Path.Combine(librarypath, filename)); + + Console.WriteLine("RuntimeDependencies Add" + filename); + } + } + + List GetAllFileNames(string path, string pattern = "*") + { + List folder = new DirectoryInfo(path).GetFiles(pattern).ToList(); + + return folder.Select(x => x.Name).ToList(); + } +} diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_audio_device_manager.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_audio_device_manager.h new file mode 100644 index 0000000..7377102 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_audio_device_manager.h @@ -0,0 +1,461 @@ +#ifndef NERTC_AUDIO_DEVICE_MANAGER_H +#define NERTC_AUDIO_DEVICE_MANAGER_H + +#include "nertc_device_collection.h" + +NERTC_BEGIN_DECLS + + /** + * @if English + * Gets the list of all the audio capture devices in the system. + *
The method returns an IDeviceCollection object that includes all the audio capture devices in the system. Enumerates + * capturing devices with the App through the IDeviceCollection object. + * @note After the method is used, the App needs to destroy the returned object by calling \ref IDeviceCollection::destroy + * "destroy" method. + * @return + * - Failure: Null. + * @endif + * @if Chinese + * 获取系统中所有的音频采集设备列表。 + *
该方法返回一个 IDeviceCollection 对象，包含系统中所有的音频采集设备。通过IDeviceCollection 对象，App + * 可以枚举音频采集设备。 + * @note 在使用结束后，App 需调用 \ref IDeviceCollection::destroy "destroy" 方法销毁返回的对象。 + * @return + * - 方法调用成功：一个 IDeviceCollection 对象，包含所有的音频采集设备。 + * - 方法调用失败：NULL。 + * @endif + * */ +NERTC_API struct nertc_device_collection* NERTC_CALL nertc_audio_device_manager_enumerate_record_devices(struct nertc_audio_device_manager* self); +/** + * @if English + * Specifies the audio capture device. + * @param device_id The device ID of the audio capture devices. Gets the ID through enumerateRecordDevices. Device swapping or + * plugging does not affect deviceId. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 指定音频采集设备。 + * @param device_id 音频采集设备的设备 ID。可通过 enumerateRecordDevices 获取。插拔设备不会影响 deviceId。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +NERTC_API int NERTC_CALL nertc_audio_device_manager_set_record_device(struct nertc_audio_device_manager* self,const char* device_id); +/** + * @if English + * Gets the ID of the audio capture device that is currently used. + * @param device_id The device ID of the audio capture devices. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 获取当前使用的音频采集设备 ID。 + * @param device_id 音频采集设备的设备 ID。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +NERTC_API int NERTC_CALL nertc_audio_device_manager_get_record_device(struct nertc_audio_device_manager* self, char* device_id); +/** + * @if English + * Gets the list of all playback devices in the system. + *
The method returns an IDeviceCollection object that includes all audio playback devices in the system. Enumerates + * playback devices with the App through the IDeviceCollection object. After the method is used, the App needs to destroy the + * returned object by calling the destroy method. + * @note The system must destroy the returned value by calling \ref IDeviceCollection::destroy "destroy" method. + * @return + * - Success: Gets an IDeviceCollection object that includes all audio playback devices. + * - Failure: Null. + * @endif + * @if Chinese + * 获取系统中所有的播放设备列表。 + *
该方法返回一个 IDeviceCollection 对象，包含系统中所有的播放设备。通过 IDeviceCollection 对象，App + * 可以枚举播放设备。在使用结束后，App 需调用 destroy 方法销毁返回的对象。 + * @note 程序必须调用 \ref IDeviceCollection::destroy "destroy" 方法销毁返回的值。 + * @return + * - 方法调用成功：一个 IDeviceCollection 对象，包含所有的音频播放设备。 + * - 方法调用失败：NULL。 + * @endif + * */ +NERTC_API struct nertc_device_collection* NERTC_CALL nertc_audio_device_manager_enumerate_playout_devices(struct nertc_audio_device_manager* self); +/** + * @if English + * Specifies the audio playback device. + * @param device_id The device ID of audio playback devices. Gets the ID through \ref + * IAudioDeviceManager::enumeratePlayoutDevices "enumeratePlayoutDevices". Device swapping or plugging does not affect + * deviceId. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 指定播放设备。 + * @param device_id 音频播放设备的设备 ID。可以通过 \ref IAudioDeviceManager::enumeratePlayoutDevices + * "enumeratePlayoutDevices" 获取。插拔设备不会影响 deviceId。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +NERTC_API int NERTC_CALL nertc_audio_device_manager_set_playout_device(struct nertc_audio_device_manager* self,const char* device_id); +/** + * @if English + * Gets the ID of the audio playback device that is currently used. + * @param device_id The ID of audio playback devices. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 获取当前使用的音频播放设备 ID。 + * @param device_id 音频播放设备的设备 ID。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +NERTC_API int NERTC_CALL nertc_audio_device_manager_get_playout_device(struct nertc_audio_device_manager* self,char* device_id); + +/** + * @if English + * Sets the volume of the audio capture device. + * @param volume The volume of the audio capture device. Valid values: 0 to 255. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置音频采集设备音量。 + * @param volume 音频采集设备音量。取值范围为 0~255。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +NERTC_API int NERTC_CALL nertc_audio_device_manager_set_record_device_volume(struct nertc_audio_device_manager* self,uint32_t volume); +/** + * @if English + * Gets the volume of the audio capture device. + * @param volume The volume of the audio capture device. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 获取音频采集设备音量。 + * @param volume 音频采集设备音量。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +NERTC_API int NERTC_CALL nertc_audio_device_manager_get_record_device_volume(struct nertc_audio_device_manager* self,uint32_t* volume); +/** + * @if English + * Sets the volume of audio playback device. + * @param volume The volume of audio playback device. Valid values: 0 to 255. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置音频播放设备音量。 + * @param volume 音频播放设备音量。取值范围为 0~255。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +NERTC_API int NERTC_CALL nertc_audio_device_manager_set_playout_device_volume(struct nertc_audio_device_manager* self,uint32_t volume); +/** + * @if English + * Gets the volume of audio playback device. + * @param volume The volume of audio playback device. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 获取音频播放设备音量。 + * @param volume 音频播放设备音量。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +NERTC_API int NERTC_CALL nertc_audio_device_manager_get_playout_device_volume(struct nertc_audio_device_manager* self, + uint32_t* volume); + +/** + * @if English + * Specifies to mute or unmute the audio playback device. + * @param mute indicates whether to unmute the audio playback device. + * - true: Specifies to mute the audio playback device. + * - false: Specifies to unmute the audio playback device. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 静音或取消静音音频播放设备。 + * @param mute 是否静音音频播放设备。 + * - true：静音音频播放设备。 + * - false：取消静音音频播放设备。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +NERTC_API int NERTC_CALL nertc_audio_device_manager_set_playout_device_mute(struct nertc_audio_device_manager* self, bool mute); + +/** + * @if English + * Confirms whether the audio playback device is muted. + * @param mute indicates the audio playback device is muted. + * - true: The device is muted. + * - false: The device is unmuted. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 获取音频播放设备静音状态。 + * @param mute 音频播放设备静音状态。 + * - true：静音状态。 + * - false：非静音状态。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +NERTC_API int NERTC_CALL nertc_audio_device_manager_get_playout_device_mute(struct nertc_audio_device_manager* self,bool* mute); + +/** + * @if English + * Specifies to mute or unmute the audio playback device. + * @param mute indicates whether to unmute the audio playback device. + * - true: Specifies to mute the audio playback device. + * - false: Specifies to unmute the audio playback device. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 静音或取消静音音频采集设备。 + * @param mute 是否静音音频采集设备。 + * - true：静音音频采集设备。 + * - false：取消静音音频采集设备。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +NERTC_API int NERTC_CALL nertc_audio_device_manager_set_record_device_mute(struct nertc_audio_device_manager* self, bool mute); + +/** + * @if English + * Confirms whether the audio playback device is muted. + * @param mute indicates the audio playback device is muted. + * - true: The device is muted. + * - false: The device is unmuted. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 获取音频采集设备静音状态。 + * @param mute 音频采集设备静音状态。 + * - true: 静音状态。 + * - false: 非静音状态。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +NERTC_API int NERTC_CALL nertc_audio_device_manager_get_record_device_mute(struct nertc_audio_device_manager* self, bool* mute); + +/** + * @if English + * Starts the test of the audio capture device. + *
The method tests whether the audio capture device can work properly. + *
After calling the method, the SDK triggers \ref IRtcEngineEventHandlerEx::onLocalAudioVolumeIndication + * "onLocalAudioVolumeIndication" callback at the time interval set in this method, which reports the volume information of + * the capturing device. + * @note + * - Calls the method before a user needs to join a room. + * - The test of the audio capture device can automatically stop after a call starts. You can also manually stop the test by + * calling stopRecordDeviceTest. + * @param indication_interval indicates the time interval that SDK returns \ref + * IRtcEngineEventHandlerEx::onLocalAudioVolumeIndication "onLocalAudioVolumeIndication" callback. Unit: milliseconds. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 启动音频采集设备测试。 + *
该方法测试音频采集设备是否能正常工作。 + *
调用该方法后，SDK 会按设置的时间间隔触发 \ref IRtcEngineEventHandlerEx::onLocalAudioVolumeIndication + * "onLocalAudioVolumeIndication" 回调， 报告采集设备的音量信息。 + * @note + * - 该方法需在加入房间前调用。 + * - 音频采集设备测试会在通话开始后自动结束，您也可以手动调用 stopRecordDeviceTest 停止音频采集设备测试。 + * @param indication_interval SDK 返回 \ref IRtcEngineEventHandlerEx::onLocalAudioVolumeIndication + * "onLocalAudioVolumeIndication" 回调的时间间隔，单位为毫秒。 + * @return + * - 0: Success. + * - other: Failure. + * @endif + * */ +NERTC_API int NERTC_CALL nertc_audio_device_manager_start_record_device_test(struct nertc_audio_device_manager *self, uint64_t indication_interval); + +/** + * @if English + * Stops the test of the audio capture device. + *
Uses the method to stop the test of the audio capture device. + * @note + * - Calls the method before a user needs to join a room. + * - The test of the audio capture device can automatically stop after a call starts. You can also manually stop the test by + * calling stopRecordDeviceTest. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 停止音频采集设备测试。 + *
该方法停止音频采集设备测试。 + * @note + * - 该方法需在加入房间前调用。 + * - 音频采集设备测试会在通话开始后自动结束，您也可以手动调用 stopRecordDeviceTest 停止音频采集设备测试。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +NERTC_API int NERTC_CALL nertc_audio_device_manager_stop_record_device_test(struct nertc_audio_device_manager* self); + +/** + * @if English + * Starts the test of the audio capture device. + * The method tests whether the audio capture device can work properly. After the test is started, SDK plays the specified + * audio files. If the sound is successfully played, the playback device can work properly. After calling the method, the SDK + * triggers \ref IRtcEngineEventHandlerEx::onLocalAudioVolumeIndication "onLocalAudioVolumeIndication" callback per 100 ms, + * which reports the volume information of the playback device. + * @note + * - Calls the method before a user needs to join a room. + * - The test of the audio playback device can automatically stop after a call starts. You can also manually stop the test by + * calling stopRecordDeviceTest. + * - Supported file formats: wav, mp3, aac. + * @param test_audio_file_path The absolute path of audio files. The path string is encoded in UTF-8. + * @return + * - 0: Success. You can hear the audio of the set files. + * - Other values: Failure. + * @endif + * @if Chinese + * 启动音频播放设备测试。 + * 该方法测试音频播放设备是否能正常工作。启动测试后，SDK 播放指定的音频文件，测试者如果能听到声音，说明播放设备能正常工作。 + * 调用该方法后，SDK 会每隔 100 ms 触发一次 \ref IRtcEngineEventHandlerEx::onLocalAudioVolumeIndication + * "onLocalAudioVolumeIndication" 回调，报告播放设备的音量信息。 + * @note + * - 该方法需在加入房间前调用。 + * - 音频播放设备测试会在通话开始后自动结束，您也可以手动调用 stopPlayoutDeviceTest 停止音频播放设备测试。 + * - 支持文件格式包括 wav、mp3、aac。 + * @param test_audio_file_path 音频文件的绝对路径，路径字符串使用 UTF-8 编码格式。 + * @return + * - 0: 成功，并且可以听到所设置文件的声音。 + * - 其他：失败。 + * @endif + * */ +NERTC_API int NERTC_CALL nertc_audio_device_manager_start_playout_device_test(struct nertc_audio_device_manager* self,const char* test_audio_file_path); + +/** + * @if English + * Stops the test of the audio capture device. + * @note + * - Calls the method before a user needs to join a room. + * - The test of the audio playback device can automatically stop after a call starts. You can also manually stop the test by + calling stopRecordDeviceTest. + * @return + * - 0: Success. + * - Other values: Failure. + + * @endif + * @if Chinese + * 停止播放设备测试。 + * @note + * - 该方法需在加入房间前调用。 + * - 播放设备测试会在通话开始后自动结束，您也可以手动调用 stopPlayoutDeviceTest 停止播放设备测试。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +NERTC_API int NERTC_CALL nertc_audio_device_manager_stop_playout_device_test(struct nertc_audio_device_manager* self); + +/** + * @if English + * Starts the test of the audio device circuit. + *
The method tests whether the audio capturing and playback device can work properly. Once the test starts, the audio + capture device captures local audio, and then plays the local audio. The SDK triggers \ref + IRtcEngineEventHandlerEx::onLocalAudioVolumeIndication "onLocalAudioVolumeIndication" callback at the time interval set in + this method, which reports the volume information of the audio. + * @note + * - Calls the method before a user needs to join a room. + * - The test of the audio device circuit can automatically stop after a call starts. You can also manually stop the test by + calling stopRecordDeviceTest. + * - You can use the method locally to test the audio device, which does not require an Internet connection. + * @param indication_interval The time interval that SDK returns \ref IRtcEngineEventHandlerEx::onLocalAudioVolumeIndication + "onLocalAudioVolumeIndication" callback. Unit: milliseconds. + * @return + * - 0: Success. + * - Other values: Failure. + + * @endif + * @if Chinese + * 开始音频设备回路测试。 + *
该方法测试音频采集和播放设备是否能正常工作。一旦测试开始，音频采集设备会采集本地音频，然后使用音频播放设备播放出来。 + SDK 会按设置的时间间隔触发 \ref IRtcEngineEventHandlerEx::onLocalAudioVolumeIndication "onLocalAudioVolumeIndication" 回调， + 报告音量信息。 + * @note + * - 该方法需在加入房间前调用。 + * - 音频设备回路测试会在通话开始后自动结束，您也可以手动调用 stopAudioDeviceLoopbackTest 停止音频设备回路测试。 + * - 该方法仅在本地进行音频设备测试，不涉及网络连接。 + * @param indication_interval SDK 返回 \ref IRtcEngineEventHandlerEx::onLocalAudioVolumeIndication + "onLocalAudioVolumeIndication" 回调的 时间间隔，单位为毫秒。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +NERTC_API int NERTC_CALL nertc_audio_device_manager_start_audio_device_loopback_test(struct nertc_audio_device_manager* self,uint64_t indication_interval); +/** + * @if English + * Stops the test of the audio device circuit. + * @note + * - Calls the method before a user needs to join a room. + * - The test of the audio device circuit can automatically stop after a call starts. You can also manually stop the test by + calling stopRecordDeviceTest. + * @return + * - 0: Success. + * - Other values: Failure. + + * @endif + * @if Chinese + * 停止音频设备回路测试。 + * @note + * - 该方法需在加入房间前调用。 + * - 音频设备回路测试会在通话开始后自动结束，您也可以手动调用 stopAudioDeviceLoopbackTest 停止音频设备回路测试。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + * */ +NERTC_API int NERTC_CALL nertc_audio_device_manager_stop_audio_device_loopback_test(struct nertc_audio_device_manager* self); + +NERTC_END_DECLS + +#endif //NERTC_AUDIO_DEVICE_MANAGER_H diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_channel.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_channel.h new file mode 100644 index 0000000..e0a3de0 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_channel.h @@ -0,0 +1,2003 @@ +/** @file nertc_channel.h + * @brief NERTC SDK IRtcChannel接口头文件。 + * NERTC SDK所有接口参数说明: 所有与字符串相关的参数(char *)全部为UTF-8编码。 + * @copyright (c) 2015-2021, NetEase Inc. All rights reserved + * @date 2021/05/10 + */ + +#ifndef NERTC_CHANNEL_H +#define NERTC_CHANNEL_H + +#include "nertc_channel_events.h" + + +NERTC_BEGIN_DECLS + +/** + * @if English + * Gets the engine object. + * @since V4.5.0 + * @endif + * @if Chinese + * 获取channel关联的nertc_engine实例 + * @since V4.5.0 + * @endif + */ +NERTC_API struct nertc_engine* NERTC_CALL nertc_channel_get_engine(struct nertc_channel* self); + +/** + * @if English + * Destroys an IRtcChannel instance to release resources. + * @since V4.5.0 + * @endif + * @if Chinese + * 销毁 IRtcChannel 实例，释放资源。 + * @since V4.5.0 + * @endif + */ +NERTC_API void NERTC_CALL nertc_channel_destroy(struct nertc_channel* self); + +/** + * @if English + * Gets the current channel name. + * @since V4.5.0 + * @return + * - Success: Return IRtcChannel channel name. + * - Fail: Return nothing. + * @endif + * @if Chinese + * 获取当前房间名。 + * @since V4.5.0 + * @return + *- 成功：当前IRtcChannel房间名。 + *- 失败：返回空。 + * @endif + */ +NERTC_API const char* NERTC_CALL nertc_channel_get_channel_name(struct nertc_channel* self); + +/** + * @if English + * Sets the event handler of the IRtcChannel. + *
You can set the event handler to monitor the channel event of IRtcChannel, and receive user video information in the + * channel. + * @since V4.5.0 + * @param[in] handler Event handler. + * @return + * - Success: Return IRtcChannel channel name. + * - Fail: Return nothing. + * @endif + * @if Chinese + * 设置 IRtcChannel 对象的事件句柄。 + *
你可以通过设置的事件句柄，监听当前IRtcChannel对象对应房间的事件，并接收房间中用户视频信息等。 + * @since V4.5.0 + * @param[in] handler 事件监听句柄对象 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_set_channel_event_handler(struct nertc_channel* self, struct nertc_channel_events* handler); + +/** + * @if English + * Joins a channel of audio and video call. + * @note + * - The user ID for each user in the channel must be unique, and the uid in the current IRtcChannel will reuse the UID in the +IRtcEngine channel. + * - The channel name is the channel_id of IRtcChannel specified when created. + * @since V4.5.0 + * @param[in] token The certification signature used in authentication (NERTC Token). Valid values: + - Null. You can set the value to null in the debugging mode. This poses a security risk. We recommend that +you contact your business manager to change to the default safe mode before your product is officially launched. + - NERTC Token acquired. In safe mode, the acquired token must be specified. If the specified token is +invalid, users are unable to join a room. We recommend that you use the safe mode. + * @param[in] uid The unique identifier of a user. The uid of each user in a room must be unique. +
uid is optional. The default value is 0. If the uid is not specified (set to 0), the SDK automatically +assigns a random uid and returns the uid in the callback of onJoinChannel. The application layer must keep and maintain the +return value. The SDK does not maintain the return value. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 加入音视频房间。 + * @note + * - 房间内每个用户的用户 ID 必须是唯一的，当前 IRtcChannel 中的 uid 复用 IRtcEngine 房间中的 uid。 + * - 房间名对应 IRtcChannel 创建时的 channel_id。 + * @since V4.5.0 + * @param[in] token 安全认证签名（NERTC Token）。可设置为： + - null。调试模式下可设置为 +null。安全性不高，建议在产品正式上线前在云信控制台中将鉴权方式恢复为默认的安全模式。 + - 已获取的NERTC Token。安全模式下必须设置为获取到的 Token 。若未传入正确的 Token +将无法进入房间。推荐使用安全模式。 + * @param[in] uid 用户的唯一标识 id，房间内每个用户的 uid 必须是唯一的。 +
uid 可选，默认为 0。如果不指定（即设为 0），SDK 会自动分配一个随机 uid，并在 onJoinChannel +回调方法中返回，App 层必须记住该返回值并维护，SDK 不对该返回值进行维护。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 +* @endif +*/ +NERTC_API int NERTC_CALL nertc_channel_join_channel(struct nertc_channel* self, + const char* token, + nertc_uid_t uid, + struct nertc_join_channel_options* channel_options); + +/** + * @if English + * Leaves the room. + *
Leaves a room for hang up or calls ended. + *
A user can call the leaveChannel method to end the call before the user makes another call. + *
After the method is called successfully, the onLeaveChannel callback is locally triggered, and the onUserLeave callback + * is remotely triggered. + * @note + * - The method is asynchronous call. Users cannot exit the room when the method is called and returned. After users exit the + * room, the SDK triggers the onLeaveChannel callback. + * - If you call leaveChannel method and instantly call release method, the SDK cannot trigger onLeaveChannel callback. + * @since V4.5.0 + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 离开房间。 + *
离开房间，即挂断或退出通话。 + *
结束通话时，必须调用leaveChannel结束通话，否则无法开始下一次通话。 + *
成功调用该方法离开房间后，本地会触发onLeaveChannel回调，远端会触发onUserLeave回调。 + * @note + * - 该方法是异步操作，调用返回时并没有真正退出房间。在真正退出房间后，SDK 会触发onLeaveChannel回调。 + * - 如果您调用了leaveChannel后立即调用release，SDK 将无法触发onLeaveChannel回调。 + * @since V4.5.0 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_leave_channel(struct nertc_channel* self); + +/** + * @if English + * Registers a stats observer. + * @since V4.5.0 + * @param[in] observer The stats observer. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 注册统计信息观测器。 + * @since V4.5.0 + * @param[in] observer 统计信息观测器 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_set_stats_observer(struct nertc_channel* self, struct nertc_media_stats_observer* observer); + +/** + * @if English + * @deprecated This method is deprecated. + * Enables volume indication for the speaker. + *
The method allows the SDK to report to the app the information about the volume of the user that pushes local streams + * and the remote user (up to three users) that has the highest instantaneous volume. The information about the current + * speaker and the volume is reported.
If this method is enabled, when a user joins a room and pushes streams, the SDK + * triggers \ref IRtcEngineEventHandlerEx::onRemoteAudioVolumeIndication "onRemoteAudioVolumeIndication" based on the preset + * time intervals. + * @param enable Whether to prompt the speaker volume. + * @param interval The time interval at which volume prompt is displayed. Unit: milliseconds. The value must be the + * multiples of 100 milliseconds. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * @deprecated 这个方法已废弃。 + * 启用说话者音量提示。 + *
通过此接口可以实现允许 SDK 定期向 App 反馈房间内发音频流的用户和瞬时音量最高的远端用户（最多 3 + * 位，包括本端）的音量相关信息，即当前谁在说话以及说话者的音量。 + * @since V3.5.0 + * @par 调用时机 + * 请在引擎初始化之后调用此接口，且该方法在加入房间前后均可调用。 + * @par 业务场景 + * 适用于通过发言者的人声相关信息做出 UI 上的音量展示的场景，或根据发言者的音量大小进行视图布局的动态调整。 + * @note + * 该方法在 leaveChannel 后设置失效，将恢复至默认。如果您离开房间后重新加入房间，需要重新调用本接口。 + * @par 参数说明 + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
**参数名称****类型****描述**
enablebool是否启用说话者音量提示：
  • true：启用说话者音量提示。
  • false：关闭说话者音量提示。
intervaluint64_t指定音量提示的时间间隔。单位为毫秒。必须设置为 100 毫秒的整数倍值，建议设置为 200 毫秒以上。
+ * @par 示例代码 + * @code + * //设置间隔为500ms的人声音量提示 + * rtc_engine_->enableAudioVolumeIndication(true, 500); + * @endcode + * @par 相关回调 + * 启用该方法后，只要房间内有发流用户，无论是否有人说话，SDK 都会在加入房间后根据预设的时间间隔触发 \ref + * IRtcEngineEventHandlerEx::onRemoteAudioVolumeIndication "onRemoteAudioVolumeIndication" 回调。 + * @par 相关接口 + * 若您希望在返回音量相关信息的同时检测是否有真实人声存在，请调用 \ref nertc::IRtcEngineEx::enableAudioVolumeIndication(bool + * enable, uint64_t interval, bool enable_vad) "enableAudioVolumeIndication" 方法。 + * @return + * - 0（kNERtcNoError）：方法调用成功。 + * - 其他：方法调用失败。 + * - 30003（kNERtcErrInvalidParam）：参数错误，比如时间间隔小于 100ms。 + * - 30005（kNERtcErrInvalidState）：状态错误，比如引擎未初始化。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_enable_audio_volume_indication(struct nertc_channel* self, + bool enable, + uint64_t interval, + bool enable_vad); + +/** + * @if English + * Enables or disables local audio capture. + *
The method can enable the local audio again to start local audio capture and processing. + *
The method does not affect receiving or playing remote audio and audio streams. + * @note The method is different from \ref IRtcEngineEx::muteLocalAudioStream "muteLocalAudioStream" in:. + * - \ref IRtcEngine::enableLocalAudio "enableLocalAudio": Enables local audio capture and processing. + * - \ref IRtcEngineEx::muteLocalAudioStream "muteLocalAudioStream": Stops or continues publishing local audio streams. + * @note The method enables the internal engine, which is still valid after you call \ref IRtcEngine::leaveChannel + * "leaveChannel". + * @since V4.5.0 + * @param[in] enabled + * - true: Enables local audio feature again. You can enable local audio capture or processing by default. + * - false: Disables local audio feature again. You can stop local audio capture or processing. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 开启/关闭本地音频采集 + *
该方法可以重新开启本地语音功能，重新开始本地音频采集及处理。 + *
该方法不影响接收或播放远端音频流。 + * @note 该方法与 \ref IRtcEngineEx::muteLocalAudioStream "muteLocalAudioStream" 的区别在于: + * - \ref IRtcEngine::enableLocalAudio "enableLocalAudio": 开启本地语音采集及处理 + * - \ref IRtcEngineEx::muteLocalAudioStream "muteLocalAudioStream": 停止或继续发送本地音频流 + * @note 该方法设置内部引擎为启用状态，在 \ref IRtcEngine::leaveChannel "leaveChannel" 后仍然有效。 + * @since V4.5.0 + * @param[in] enabled + * - true: 重新开启本地语音功能，即开启本地语音采集或处理（默认） + * - false: 关闭本地语音功能，即停止本地语音采集或处理 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_enable_local_audio(struct nertc_channel* self, nertc_audio_stream_type stream_type, bool enabled); + +/** + * @if English + * Enables or disabling publishing the local audio stream. The method is used to enable or disable publishing the local audio + * stream. + * @note + * - This method does not change the state of the audio-recording device because the audio-recording devices are not disabled. + * - The mute state is reset to unmuted after the call ends. + * @since V4.5.0 + * @param[in] mute Mute or Unmute. + * - true: Mutes the local audio stream. + * - false: Unmutes the local audio stream (Default). + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 开关本地音频发送。该方法用于允许或禁止向网络发送本地音频流。 + * @note + * - 该方法不影响录音状态，因为并没有禁用录音设备。 + * - 静音状态会在通话结束后被重置为非静音 + * @since V4.5.0 + * @param[in] mute 静音/取消静音: + * - true: 静音本地音频 + * - false: 取消静音本地音频（默认） + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_mute_local_audio_stream(struct nertc_channel* self, nertc_audio_stream_type stream_type, bool mute); + +/** + * @if English + * Enables or disables local audio capture and rendering. + *
The method enables local video capture. + * @note + * - You can call this method before or after you join a room. + * - The method enables the internal engine, which is still valid after you call \ref IRtcEngine::leaveChannel "leaveChannel". + * - After local video capture is successfully enabled or disabled, the onUserVideoStop or onUserVideoStart callback is + * remotely triggered. + * @since V4.5.0 + * @param[in] enabled Whether to enable local video capture and rendering. + * - true: Enables the local video capture and rendering. + * - false: Disables the local camera device. After local video capture is disabled, remote users cannot receive video streams + * from local users. However, local users can still receive video streams from remote users. If the setting is false, the + * local camera is not required to call the method. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 开启或关闭本地视频采集和渲染。 + *
该方法启用本地视频采集功能。 + * @note + * - 该方法在加入房间前和加入房间后均可调用。 + * - 该方法设置内部引擎为启用状态，在 \ref IRtcEngine::leaveChannel "leaveChannel" 后仍然有效。 + * - 成功启用或禁用本地视频采集和渲染后，远端会触发 onUserVideoStop 或 onUserVideoStart 回调。 + * @since V4.5.0 + * @param[in] enabled 是否启用本地视频采集和渲染: + * - true: 开启本地视频采集和渲染 (默认)； + * - false: 关闭使用本地摄像头设备。关闭后，远端用户会接收不到本地用户的视频流；但本地用户依然可以接收远端用户的视频流。设置为 + * false 时，该方法不需要本地有摄像头。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_enable_local_video(struct nertc_channel* self, nertc_video_stream_type stream_type, bool enabled); + +/** + * @if English + * Stops or resumes sending the local video stream. + *
If the method is called Successfully, onUserVideoMute is triggered remotely. + * @note + * - When you call the method to disable video streams, the SDK doesn’t send local video streams but the camera is still + * working. + * - The method can be called before or after a user joins a room. + * - If you stop publishing the local video stream by calling this method, the option is reset to the default state that + * allows the app to publish the local video stream. + * - \ref nertc::IRtcEngine::enableLocalVideo "enableLocalVideo" (false) is different from \ref + * nertc::IRtcEngine::enableLocalVideo "enableLocalVideo" (false). The enableLocalVideo(false) method turns off local camera + * devices. The muteLocalVideoStreamvideo method does not affect local video capture, or disable cameras, and responds faster. + * @since V4.5.0 + * @param[in] mute + * - true: Not publishing local video streams. + * - false: Publishing local video streams (default). + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 取消或恢复发布本地视频流。 + *
成功调用该方法后，远端会触发 onUserVideoMute 回调。 + * @note + * - 调用该方法禁视频流时，SDK 不再发送本地视频流，但摄像头仍然处于工作状态。 + * - 该方法在加入房间前后均可调用。 + * - 若调用该方法取消发布本地视频流，通话结束后会被重置为默认状态，即默认发布本地视频流。 + * - 该方法与 \ref nertc::IRtcEngine::enableLocalVideo "enableLocalVideo" (false) 的区别在于， \ref + * nertc::IRtcEngine::enableLocalVideo "enableLocalVideo" (false) + * 会关闭本地摄像头设备，muteLocalVideoStream不影响本地视频流采集，不禁用摄像头，且响应速度更快。 + * @since V4.5.0 + * @param[in] mute + * - true: 不发送本地视频流 + * - false: 发送本地视频流（默认） + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_mute_local_video_stream(struct nertc_channel* self, nertc_video_stream_type stream_type, bool mute); + +/** + * @if English + * Shares screens through specifying regions. Shares a certain screen or part of region of a screen. Users need to specify the + * screen region they wants to share in the method.
When calling the method, you need to specify the screen region to be + * shared, and share the overall frame of the screen or designated regions.
If you join a room and successfully call this + * method to enable the substream, the onUserSubStreamVideoStart and setExcludeWindowList callback is remotely triggered. + * @note + * - The method applies to Windows only. + * - The method enables video substreams. + * @since V4.5.0 + * @param screen_rect The relative position of the screen to virtual screens that is shared. + * @param region_rect The relative position of shared screen to the full screen. If you set the shared region beyond the + * frame of the screen, only content within the screen is shared. If you set the value of width or height as 0, the full + * screen is shared. + * @param capture_params The configurations of screen sharing. + * @return + * - 0: Success. + * - Other values: Failure. + * + * @endif + * @if Chinese + * 开启屏幕共享，共享范围为指定屏幕的指定区域。 + *
调用该方法时，可以选择共享整个虚拟屏、指定屏幕，或虚拟屏、整个屏幕的某些区域范围。 + *
此方法调用成功后，远端触发 onUserSubStreamVideoStart 和 setExcludeWindowList 回调。 + * @note + * - 该方法仅适用于 Windows。macOS 平台请使用方法 startScreenCaptureByDisplayId。 + * - 该方法需要在加入房间后调用。 + * @since V4.5.0 + * @param screen_rect 指定待共享的屏幕相对于虚拟屏的位置。 + * @param region_rect + * 指定待共享区域相对于整个屏幕屏幕的位置。如果设置的共享区域超出了屏幕的边界，则只共享屏幕内的内容；如果将 width 或 height + * 设为 0, 则共享整个屏幕。 + * @param capture_params 屏幕共享的编码参数配置。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_start_screen_capture_by_screen_rect(struct nertc_channel* self,const struct nertc_rectangle* screen_rect,const struct nertc_rectangle* region_rect,const struct nertc_screen_capture_parameters* capture_params); + +/** + * @if English + * Enables screen sharing by specifying the ID of the screen. The content of screen sharing is sent by substreams. + *
If you join a room and call this method to enable the substream, the onUserSubStreamVideoStart and + onScreenCaptureStatus callback is remotely triggered. + * @note + * - The method applies to only macOS. + * - The method enables video substreams. + * @since V4.5.0 + * @param display_id The ID of the screen to be shared. Developers need to specify the screen they share through the + parameters. + * @param region_rect The relative position of shared screen to the full screen. + * @param capture_params The configurations of screen sharing. + * @return + * - 0: Success. + * - Other values: Failure. + + * @endif + * @if Chinese + * 通过指定屏幕 ID 开启屏幕共享，屏幕共享内容以辅流形式发送。 + *
此方法调用成功后，远端触发 onUserSubStreamVideoStart 回调。 + * @note + * - 该方法仅适用于 macOS。Windows 平台请使用方法 startScreenCaptureByScreenRect。 + * - 该方法需要在加入房间后设置。 + * @since V4.5.0 + * @param display_id 指定待共享的屏幕 ID。开发者需要自行实现枚举屏幕 ID 的方法，并通过该参数指定需要共享的屏幕。 + * @param region_rect + 指定待共享的区域相对于整个窗口的位置。如果设置的共享区域超出了窗口的边界，则只共享窗口内的内容；如果宽或高为 + 0，则共享整个窗口。 + * @param capture_params 屏幕共享的参数配置，包括码率、帧率、编码策略、屏蔽窗口列表等。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_start_screen_capture_by_display_id(struct nertc_channel* self,uint64_t display_id,const struct nertc_rectangle* region_rect,const struct nertc_screen_capture_parameters* capture_params); + +/** + * @if English + * Enables screen sharing by specifying the ID of the window. The content of screen sharing is sent by substreams. + *
If you join a room and call this method to enable the substream, the onUserSubStreamVideoStart and setExcludeWindowList + * callback is remotely triggered. + * @note + * - The method applies to Windows only and macOS. + * - The method enables video substreams. + * @since V4.5.0 + * @param window_id The ID of the window to be shared. + * @param region_rect The relative position of shared screen to the full screen. + * @param capture_params The configurations of screen sharing. + * @return + * - 0: Success. + * - Other values: Failure. + * + * @endif + * @if Chinese + * 通过指定窗口 ID 开启屏幕共享，屏幕共享内容以辅流形式发送。 + *
调用该方法时需要指定待共享的屏幕 ID，共享该屏幕的整体画面或指定区域。 + *
此方法调用成功后： + * - Windows 平台远端触发 onUserSubStreamVideoStop 和 onScreenCaptureStatus 回调。 + * - macOS 平台远端触发 onUserSubStreamVideoStop 回调。 + * @note + * - 该方法适用于 Windows 和 macOS。 + * - 该方法需要在加入房间后调用。 + * @since V4.5.0 + * @param window_id 指定待共享的窗口 ID。 + * @param region_rect + * 指定待共享的区域相对于整个窗口的位置。如果设置的共享区域超出了窗口的边界，则只共享指定区域中窗口内的内容；如果宽或高为 + * 0，则共享整个窗口。 + * @param capture_params 屏幕共享的参数配置，包括码率、帧率、编码策略、屏蔽窗口列表等。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_start_screen_capture_by_window_id(struct nertc_channel* self,void* window_id,const struct nertc_rectangle* region_rect,const struct nertc_screen_capture_parameters* capture_params); + +/** + * @if English + * When sharing a screen or window, updates the shared region. + * @since V4.5.0 + * @param region_rect The relative position of shared screen to the full screen. If you set the shared region beyond the + * frame of the screen, only content within the screen is shared. If you set width or height as 0, the full screen is shared. + * @return + * - 0: Success. + * - Other values: Failure. + * + * @endif + * @if Chinese + * 在共享屏幕或窗口时，更新共享的区域。 + *
在 Windows 平台中，远端会触发 onScreenCaptureStatus 回调。 + * @since V4.5.0 + * @param region_rect + * 指定待共享的区域相对于整个窗口或屏幕的位置。如果设置的共享区域超出了边界，则只共享指定区域中，窗口或屏幕内的内容；如果宽或高为 + * 0，则共享整个窗口或屏幕。 + * @return + * - 0: 方法调用成功。 + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_update_screen_capture_region(struct nertc_channel* self,const struct nertc_rectangle* region_rect); + +/** +* @if English +* Displays or hides the pointer during screen sharing. +* @since V4.6.10 +* @param bool specifies whether to display the pointer. +* - true: displays the pointer. +* - false: hides the pointer. +* @return +* - 0: success +* - Others: failure +* @endif +* @if Chinese +* 在共享屏幕或窗口时，更新是否显示鼠标。 +* @since V4.6.10 +* @param capture_cursor 屏幕共享时是否捕捉鼠标光标。 +* - true：共享屏幕时显示鼠标。 +* - false：共享屏幕时不显示鼠标。 +* @return +* - 0: 方法调用成功。 +* - 其他: 方法调用失败 +* @endif +*/ +NERTC_API int NERTC_CALL nertc_channel_set_screen_capture_mouse_cursor(struct nertc_channel* self, bool capture_cursor); + +/** + * @if English + * Stops screen sharing. + *
If you use the method to disable the substream after joining a room, the onUserSubStreamVideoStop callback is remotely + * triggered. + * @since V4.5.0 + * @return + * - 0: Success. + * - Other values: Failure. + * + * @endif + * @if Chinese + * 停止屏幕共享。 + *
此方法调用成功后： + * - Windows 平台远端触发 onUserSubStreamVideoStop 和 onScreenCaptureStatus 回调。 + * - macOS 平台远端触发 onUserSubStreamVideoStop 回调。 + * @since V4.5.0 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_stop_screen_capture(struct nertc_channel* self); + +/** + * @if English + * Pauses screen sharing. + * @since V4.5.0 + * @return + * - 0: Success. + * - Other values: Failure. + * + * @endif + * @if Chinese + * 暂停屏幕共享。 + * - 暂停屏幕共享后，共享区域内会持续显示暂停前的最后一帧画面，直至通过 resumeScreenCapture 恢复屏幕共享。 + * - 在 Windows 平台中，远端会触发 onScreenCaptureStatus 回调。 + *

@since V4.5.0 + * @return + * - 0: 方法调用成功 + * - 其他: 方法调用失败 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_pause_screen_capture(struct nertc_channel* self); + +/** + * @if English + * Resumes screen sharing. + * @since V4.5.0 + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 恢复屏幕共享。 + *
在 Windows 平台中，远端会触发 onScreenCaptureStatus 回调。 + * @since V4.5.0 + * @return + * - 0: 方法调用成功 + * - 其他: 方法调用失败 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_resume_screen_capture(struct nertc_channel* self); + +/** + * @if English + * Sets the window list that need to be blocked in capturing screens. The method can be dynamically called in the capturing. + * @since V4.5.0 + * @param window_list The ID of the screen to be blocked. + * @param count The number of windows that are needed to be blocked. + * @return + * - 0: Success. + * - Other values: Failure. + * + * @endif + * @if Chinese + * 设置共享整个屏幕或屏幕指定区域时，需要屏蔽的窗口列表。 + *
开启屏幕共享时，可以通过 NERtcScreenCaptureParameters 设置需要屏蔽的窗口列表；在 Windows + * 平台中，开发者可以在开启屏幕共享后，通过此方法动态调整需要屏蔽的窗口列表。被屏蔽的窗口不会显示在屏幕共享区域中。 + * @note + * - 在 Windows 平台中，该接口在屏幕共享过程中可动态调用；在 macOS 平台中，该接口需要在开启屏幕共享之前，即 + * startScreenCaptureByDisplayId 之前调用。 + * - 在 Windows 平台中，某些窗口在被屏蔽之后，如果被置于图层最上层，此窗口图像可能会黑屏。此时会触发 + * onScreenCaptureStatus.kScreenCaptureStatusCovered 回调，建议应用层在触发此回调时提醒用户将待分享的窗口置于最上层。 + * @since V4.5.0 + * @param window_list 需要屏蔽的窗口 ID 列表。 + * @param count 需屏蔽的窗口的数量。 + * @return + * - 0: 方法调用成功 + * - 其他: 方法调用失败 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_set_exclude_window_list(struct nertc_channel* self, source_id_t* window_list, int count); + +/** + * @if Chinese + * 更新屏幕共享参数。 + *
开始共享屏幕或窗口后，动态更新采集帧率，目标码率，编码分辨率等屏幕共享相关参数。 + * @since V4.6.20 + * @par 调用时机 + * 请在加入房间并成功开启屏幕共享后调用该方法。 + * @note + * - 调用该方法会重新启动屏幕共享，因此建议不要频繁调用。 + * - + * 可以通过该方法动态设置是否捕捉鼠标（capture_mouse_cursor）和设置排除窗口（excluded_window_list，excluded_window_count），同时这两项设置也可以通过 + * \ref IRtcEngineEx::setScreenCaptureMouseCursor "setScreenCaptureMouseCursor" 和 \ref IRtcEngineEx::setExcludeWindowList + * "setExcludeWindowList" 方法实现。 + * @par 参数说明 + * + * + * + * + * + * + * + * + * + * + * + *
**参数名称****类型****描述**
captureParams \ref nertc::NERtcScreenCaptureParameters "NERtcScreenCaptureParameters"屏幕共享编码参数配置。
+ * @par 示例代码 + * @code + * //调用该方法时，需要维护一个 nertc::NERtcScreenCaptureParameters captureParams 变量记录当前设置。更新设置的时候： + * nertc::NERtcScreenCaptureParameters captureParams; + * captureParams.field1 = new_value1; + * captureParams.field2 = new_value2; + * ... + * updateScreenCaptureParameters(captureParams); + * @endcode + * @par 相关回调 + * 成功调用该方法后，会触发 \ref IRtcChannelEventHandler::onScreenCaptureStatus "onScreenCaptureStatus" 回调。 + * @return + * - 0（kNERtcNoError）：方法调用成功。 + * - 其他：方法调用失败。 + * - 30005（kErrorErrInvalidState）：多房间状态错误。 + * - 30021（kNERtcErrDesktopCaptureInvalidParam）：传入的参数无效。 + * - 30101（kNERtcErrChannelNotJoined）：未加入房间。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_update_screen_capture_parameters(struct nertc_channel* self, const struct nertc_screen_capture_parameters* capture_params); + +/** + * @if English + * Sets local views. + *
This method is used to set the display information about the local video. The method is applicable for only local + * users. Remote users are not affected.
Apps can call this API operation to associate with the view that plays local + * video streams. During application development, in most cases, before joining a room, you must first call this method to set + * the local video view after the SDK is initialized. + * @note If you use external rendering on the Mac platform, you must set the rendering before the SDK is initialized. + * @since V4.5.0 + * @param[in] canvas The video canvas information. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置本地视图。 + *
该方法设置本地视频显示信息。只影响本地用户看到的视频画面，不影响远端。 + *
App 通过调用此接口绑定本地视频流的显示视窗(view)。 在 App + * 开发中，通常在初始化后调用该方法进行本地视频设置，然后再加入房间。 + * @since V4.5.0 + * @note mac端若使用外部渲染，必须在 SDK 初始化时设置。 + * @param[in] canvas 视频画布信息 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_setup_local_video_canvas(struct nertc_channel* self, nertc_video_stream_type type, struct nertc_video_canvas* canvas); + +/** + * @if English + * Sets the display mode for local substreams video of screen sharing. + * This method is used to set the display mode about the local view. The application can repeatedly call the method to change + * the display mode. + * @note You must set the local canvas for local substreams through setupLocalSubStreamVideoCanvas. + * @since V4.5.0 + * @param[in] scaling_mode The video display mode. #NERtcVideoScalingMode. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置本地视图显示模式。 + * 该方法设置本地视图显示模式。 App 可以多次调用此方法更改显示模式。 + * @note 在打开屏幕共享前必须设置本地辅流画布。 + * @since V4.5.0 + * @param[in] scaling_mode 视频显示模式: #NERtcVideoScalingMode + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_set_local_render_mode(struct nertc_channel* self, nertc_video_stream_type type, nertc_video_scaling_mode scaling_mode); + +/** + * @if English + * Sets the mirror mode of the local video. + * The method is used to set whether to enable the mirror mode for the local video. The mirror code determines whether to flip + * the screen view right or left. Mirror mode for local videos only affects what local users view. The views of remote users + * are not affected. App can repeatedly call this method to modify the mirror mode. + * @since V4.5.0 + * @param[in] mirror_mode The video mirror mode. For more information, see {@link NERtcVideoMirrorMode}. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置本地视频镜像模式。 + * 该方法用于设置本地视频是否开启镜像模式，即画面是否左右翻转。 + * 本地的视频镜像模式仅影响本地用户所见，不影响远端用户所见。App 可以多次调用此方法更改镜像模式。 + * @since V4.5.0 + * @param[in] mirror_mode 视频镜像模式。详细信息请参考 {@link NERtcVideoMirrorMode}。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_set_local_video_mirror_mode(struct nertc_channel* self, nertc_video_stream_type type, nertc_video_mirror_mode mirror_mode); + +/** + * @if English + * Sets views for remote users. + *
This method is used to associate remote users with display views and configure the rendering mode and mirror mode for + * remote views that are displayed locally. The method affects only video display viewed by local users. + * @note + * - You need to specify the uid of remote video when the interface is called. In general cases, the uid can be set before + * users join the room. + * - If the user ID is not retrieved, the App calls this method after the onUserJoined event is triggered. To disassociate a + * specified user from a view, you can leave the canvas parameter empty. + * - After a user leaves the room, the association between a remote user and the view is cleared. + * @since V4.5.0 + * @param[in] uid The ID of a remote user. + * @param[in] canvas The video canvas information. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置远端用户视图。 + *
该方法绑定远端用户和显示视图，并设置远端用户视图在本地显示时的渲染模式和镜像模式，只影响本地用户看到的视频画面。 + * @note + * - 调用该接口时需要指定远端视频的 uid，一般可以在用户加入后设置好。 + * - 如果 App 无法事先知道对方的用户 ID，可以在 APP 收到 onUserJoined 事件时设置。- 解除某个用户的绑定视图可以把 canvas + * 设置为空。 + * - 退出房间后，SDK 会清除远程用户和视图的绑定关系。 + * @since V4.5.0 + * @param[in] uid 远端用户 ID。 + * @param[in] canvas 视频画布信息 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_setup_remote_video_canvas(struct nertc_channel* self,nertc_uid_t uid,nertc_video_stream_type type, struct nertc_video_canvas* canvas); + +/** + * @if English + * Sets display mode for remote views. + * This method is used to set the display mode for the remote view. App can repeatedly call this method to modify the display + * mode. + * @since V4.5.0 + * @param[in] uid The ID of a remote user. + * @param[in] scaling_mode The video display mode. #NERtcVideoScalingMode. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置远端视图显示模式。 + * 该方法设置远端视图显示模式。App 可以多次调用此方法更改显示模式。 + * @since V4.5.0 + * @param[in] uid 远端用户 ID。 + * @param[in] scaling_mode 视频显示模式: #NERtcVideoScalingMode + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_set_remote_render_mode(struct nertc_channel* self, nertc_uid_t uid, nertc_video_stream_type type, nertc_video_scaling_mode scaling_mode); + +/** + * @if English + * Sets the role of a user in live streaming. + *
The method sets the role to host or audience. The permissions of a host and a viewer are different. + * - A host has the permissions to open or close a camera, publish streams, call methods related to publishing streams in + * interactive live streaming. The status of the host is visible to the users in the room when the host joins or leaves the + * room. + * - The audience has no permissions to open or close a camera, call methods related to publishing streams in interactive live + * streaming, and is invisible to other users in the room when the user that has the audience role joins or leaves the room. + *

@since V4.5.0 + * @note + * - By default, a user joins a room as a host. + * - Before a user joins a room, the user can call this method to change the client role to audience. Users can switch the + * role of a user through the interface after joining the room. + * - If the user switches the role to audience, the SDK automatically closes the audio and video devices. + * @param[in] role The role of a user. NERtcClientRole. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 在直播场景中设置用户角色。 + *
用户角色支持设置为主播或观众，主播和观众的权限不同。 + * - 主播：可以开关摄像头等设备、可以发布流、可以操作互动直播推流相关接口、上下线对其他房间内用户可见。 + * - 观众：不可以开关摄像头等设备、不可以发布流、不可以操作互动直播推流相关接口、上下线对其他房间内用户不可见。 + *

@note + * - 默认情况下用户以主播角色加入房间。 + * - 在加入房间前，用户可以调用本接口切换本端角色为观众。在加入房间后，用户也可以通过本接口切换用户角色。 + * - 用户切换为观众角色时，SDK 会自动关闭音视频设备。 + * @since V4.5.0 + * @param[in] role 用户角色。 NERtcClientRole + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_set_client_role(struct nertc_channel* self, nertc_client_role role); + +/** + * @if English + * Sets the priority of media streams from a local user. + *
If a user has a high priority, the media stream from the user also has a high priority. In unreliable network + connections, the SDK guarantees the quality the media stream from users with a high priority. + * @note + * - You must call the method before you call joinChannel. + * - After switching channels, media priority changes to the default value of normal priority. + * - An RTC room has only one user that has a high priority. We recommend that only one user in a room call the + setLocalMediaPriority method to set the local media stream a high priority. Otherwise, you need to enable the preempt mode to + ensure the high priority of the local media stream. + * @since V4.5.0 + * @param priority The priority of the local media stream. The default value is #kNERtcMediaPriorityNormal. For more + information, see #NERtcMediaPriorityType. + * @param is_preemptive specifies whether to enable the preempt mode. The default value is false, which indicates that the + preempt mode is disabled. + - If the preempt mode is enabled, the local media stream preempts the high priority over other users. + The priority of the media stream whose priority is taken becomes normal. After the user whose priority is taken leaves the + room, other users still keep the normal priority. + - If the preempt mode is disabled, and a user in the room has a high priority. After that, the high + priority of the local client remains invalid and is still normal. + * @return + - 0: Success. + - Other values: Failure. + * @endif + * @if Chinese + * 设置本地用户的媒体流优先级。 + *
如果某个用户的优先级为高，那么该用户媒体流的优先级就会高于其他用户，弱网环境下 SDK + 会优先保证其他用户收到的、高优先级用户的媒体流的质量。 + * @note + * - 请在加入房间（joinChannel）前调用此方法。 + * - 快速切换房间 （switchChannel） 后，媒体优先级会恢复为默认值，即普通优先级。 + * - 一个音视频房间中只有一个高优先级的用户。建议房间中只有一位用户调用 setLocalMediaPriority + 将本端媒体流设为高优先级，否则需要开启抢占模式，保证本地用户的高优先级设置生效。 + * @since V4.5.0 + * @param priority 本地用户的媒体流优先级，默认为 #kNERtcMediaPriorityNormal 。详细信息请参考 #NERtcMediaPriorityType 。 + * @param is_preemptive 是否开启抢占模式。默认为 false，即不开启。 + - + 抢占模式开启后，本地用户可以抢占其他用户的高优先级，被抢占的用户的媒体优先级变为普通优先级，在抢占者退出房间后，其他用户的优先级仍旧维持普通优先级。 + - 抢占模式关闭时，如果房间中已有高优先级用户，则本地用户的高优先级设置不生效，仍旧为普通优先级。 + * @return + - 0: 方法调用成功； + - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_set_local_media_priority(struct nertc_channel* self,nertc_media_priority_type priority,bool is_preemptive); + +/** + * @if English + * Gets the current connection status. + * @since V4.5.0 + * @return Returns the current network status. #NERtcConnectionStateType. + * @endif + * @if Chinese + * 获取当前网络状态。 + * @since V4.5.0 + * @return 当前网络状态。#NERtcConnectionStateType. + * @endif + */ +NERTC_API nertc_connection_state_type NERTC_CALL nertc_channel_get_connection_state(struct nertc_channel* self); + +/** + * @if English + * Sets the camera capturer configuration. + *
For a video call or live streaming, generally the SDK controls the camera output parameters. By default, the SDK + * matches the most appropriate resolution based on the user's setVideoConfig configuration. When the default camera capture + * settings do not meet special requirements, we recommend using this method to set the camera capturer configuration: + * - If you want better quality for the local video preview, we recommend setting config as kNERtcCameraOutputQuality. The SDK + * sets the camera output parameters with higher picture quality. + * - To customize the width and height of the video image captured by the local camera, set the camera capture configuration + * as kNERtcCameraOutputManual.

@note + * - Call this method before or after joining the channel. The setting takes effect immediately without restarting the camera. + * - Higher collection parameters means higher performance consumption, such as CPU and memory usage, especially when video + * pre-processing is enabled. + * @since V4.5.0 + * @param config The camera capturer configuration. + * @return {@code 0} A value of 0 returned indicates that the method call is successful. Otherwise, the method call fails. + * @endif + * @if Chinese + * 设置本地摄像头的采集偏好等配置。 + *
在视频通话或直播中，SDK 自动控制摄像头的输出参数。默认情况下，SDK 根据用户的 setVideoConfig + * 配置匹配最合适的分辨率进行采集。但是在部分业务场景中，如果采集画面质量无法满足实际需求，可以调用该接口调整摄像头的采集配置。 + * - 需要采集并预览高清画质时，可以将采集偏好设置为 kNERtcCameraOutputQuality，此时 SDK + * 会自动设置较高的摄像头输出参数，本地采集与预览画面比编码参数更加清晰。 + * - 需要自定义设置摄像头采集的视频尺寸时，请通过参数 preference 将采集偏好设为 kNERtcCameraOutputManual，并通过 + * NERtcCameraPreference 中的 captureWidth 和 captureHeight 自定义设置本地摄像头采集的视频宽高。

@note + * - 该方法可以在加入房间前后动态调用，设置成功后立即生效，无需重启摄像头。 + * - 设置更高的采集参数会导致更大的性能消耗，例如 CPU 和内存占用等，尤其是在开启视频前处理的场景下。 + * @since V4.5.0 + * @param config 摄像头采集配置。详细说明请参考 nertc::NERtcCameraCaptureConfig 。 + * @return {@code 0} 方法调用成功，其他调用失败 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_set_camera_capture_config(struct nertc_channel* self, nertc_video_stream_type stream_type, const struct nertc_camera_capture_config* config); + +/** + * @if English + * Sets local video parameters. + *
You can call this method before or after you join the room. + * @note + * - Each profile has a set of video parameters, such as resolution, frame rate, and bitrate. All the specified values of the + * parameters are the maximum values in optimal conditions. If the video engine cannot use the maximum value of resolution, + * due to poor network performance, the value closest to the maximum value is taken. + * - This method is a full parameter configuration method. If this method is invoked repeatedly, the SDK refreshes all + * previous parameter configurations and uses the latest parameter. Therefore, you need to set all parameters each time you + * modify the configuration, otherwise, unconfigured parameters will be set to the default value. + * - Since V4.5.0, 'setVideoConfig' method takes effect in real time. In previous versions, the setting takes effect the next + * time local video is enabled. + * @since V4.5.0 + * @param[in] config Sets the video encoding parameters. For more information, see {@link NERtcVideoConfig}. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置本地视频主流的编码属性。 + *
可以在加入房间前或加入房间后调用。 + * @note + * - 每个属性对应一套视频参数，例如分辨率、帧率、码率等。 + * 所有设置的参数均为理想情况下的最大值。当视频引擎因网络环境等原因无法达到设置的分辨率的最大值时，会取最接近最大值的那个值。 + * - setVideoConfig 为全量参数配置接口，重复调用此接口时，SDK + * 会刷新此前的所有参数配置，以最新的传参为准。所以每次修改配置时都需要设置所有参数，未设置的参数将取默认值。 + * - V4.5.0 开始，`setVideoConfig` 方法实时生效；此前的版本中，`setVideoConfig` 方法设置成功后，下次开启本端视频时生效。 + * @since V4.5.0 + * @param[in] config 视频编码属性配置，详细信息请参考 {@link NERtcVideoConfig}。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_set_video_config(struct nertc_channel* self, nertc_video_stream_type stream_type, const struct nertc_video_config* config); + +/** + * @if English + * Specifies whether to enable or disable the dual stream mode. + *
The method sets the single-stream mode or dual-stream mode. If the dual-stream mode is enabled, the receiver can choose + * to receive the high-quality stream or low-quality stream video. The high-quality stream has a high resolution and high + * bitrate. The low-quality stream has a low resolution and low bitrate. + * @note + * - The method applies to camera data only. Video streams from external input and screen sharing are not affected. + * - You can call this method before or after you join a room. After the method is set, it can take effect after restarting + * the camera. + * @since V4.5.0 + * @param[in] enable Whether to enable dual-stream mode. + * - true: Enables the dual-stream mode. This is the default value. + * - false: Disables the dual-stream mode. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置是否开启视频大小流模式。 + *
该方法设置单流或者双流模式。发送端开启双流模式后，接收端可以选择接收大流还是小流。其中，大流指高分辨率、高码率的视频流，小流指低分辨率、低码率的视频流。 + * @note + * - 该方法只对摄像头数据生效，自定义输入、屏幕共享等视频流无效。 + * - 该方法在加入房间前后都能调用。设置后，会在摄像头重启后生效。 + * @since V4.5.0 + * @param[in] enable 指定是否开启双流模式。 + * - true: （默认）开启双流模式。 + * - false: 关闭双流模式。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_enable_dual_stream_mode(struct nertc_channel* self, bool enable); + +/** + * @if English + * Unsubscribes from or subscribes to audio streams from specified remote users. + *
After a user joins a channel, audio streams from all remote users are subscribed by default. You can call this method + * to unsubscribe from or subscribe to audio streams from all remote users. + * @note When the kNERtcKeyAutoSubscribeAudio is enabled by default, users cannot manually modify the state of audio + * subscription. + * @since V4.5.0 + * @param[in] uid The user ID. + * @param[in] subscribe + * - true: Subscribes to specified audio streams (default). + * - false: Unsubscribes from specified audio streams. + * @return + * - 0: Success. + * - 30005: State exception that is caused by the invalid interface if users enable the automatic subscription. + * - Other values: Failure. + * @endif + * @if Chinese + * 取消或恢复订阅指定远端用户音频流。 + *
加入房间时，默认订阅所有远端用户的音频流，您可以通过此方法取消或恢复订阅指定远端用户的音频流。 + * @note 当kNERtcKeyAutoSubscribeAudio默认打开时，用户不能手动修改音频订阅状态 + * @since V4.5.0 + * @param[in] uid 指定用户的 ID。 + * @param[in] subscribe 是否订阅远端用户音频流。 + * - true: 订阅指定音频流（默认）。 + * - false: 取消订阅指定音频流。 + * @return + * - 0: 方法调用成功。 + * - 30005: 状态异常，可能是自动订阅打开，导致该接口无效。 + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_subscribe_remote_audio_stream(struct nertc_channel* self, nertc_audio_stream_type stream_type, nertc_uid_t uid, bool subscribe); + +/** + * @if English + * Unsubscribes or subscribes to audio streams from all remote users. + * @note + * - When joins a room, local user subscribe audio streams from all remote users by default. Under the circumstances, do not + * call subscribeAllRemoteAudioStream (YES) to subscribe audio streams again. + * - You can call this method before joining a channel. + * @since V4.5.0 + * @param subscribe Whether to unsubscribe audio streams from all remote users. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 取消或恢复订阅所有远端用户音频流。 + * @note + * - 加入房间时，默认订阅所有远端用户的音频，此时请勿调用 subscribeAllRemoteAudioStream(YES) 重复订阅所有远端用户的音频流。 + * - 该方法需要在加入房间后调用，对后续加入的用户也同样生效。 + * @since V4.5.0 + * @param subscribe 是否取消订阅所有远端用户的音频流。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_subscribe_all_remote_audio_stream(struct nertc_channel* self, bool subscribe); + +/** + * @if English + * Sets the local audio stream can be subscribed by specified participants in a room. + *
All participants in the room can subscribe to the local audio stream by default. + * @note + * - The API must be called after a user joins a room. + * - The API cannot be called by user IDs out of the room. + * @since V4.6.10 + * @param[in] uidArray The list of user IDs that can subscribe to the local audio stream. + * @note The list contains all participants in a room. If the value is empty or null, all participants can subscribe to the + * local audio stream. + * @param[in] size The length of the uid_array array. + * @return + * - 0: success + * - Others: failure. + * @endif + * @if Chinese + * 设置自己的音频只能被房间内指定的人订阅。 + *
默认房间所有其他人都可以订阅自己的音频。 + * @note + * - 此接口需要在加入房间成功后调用。 + * - 对于调用接口时不在房间的 uid 不生效。 + * @since V4.6.10 + * @param[in] uid_array 可订阅自己音频的用户uid 列表。 + * @note 此列表为全量列表。如果列表为空或 null，表示其他所有人均可订阅自己的音频。 + * @param[in] size uid_array 的数组长度。 + * @return + * - 0：方法调用成功。 + * - 其他：方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_set_audio_subscribe_only_by(struct nertc_channel* self,nertc_uid_t* uid_array, uint32_t size); + +/** + * @if Chinese + * 你可以调用该方法指定只订阅的音频流。 + * @note + * - 此接口需要在加入房间成功后调用。 + * - 对于调用接口时不在房间的 uid 不生效。 + * @since V5.4.101 + * @param[in] uid_array 只订阅此 用户uid列表 的音频。 + * @note 此列表为全量列表。如果列表为空或 null，取消订阅白名单。 + * @param[in] size uid_array 的数组长度。 + * @return + * - 0：方法调用成功。 + * - 其他：方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_set_subscribe_audio_allow_list(struct nertc_channel* self, nertc_uid_t* uid_array, uint32_t size); + +/** + * @if Chinese + * 你可以调用该方法指定不订阅的音频流。 + * @note + * - 此接口需要在加入房间成功后调用。 + * - 对于调用接口时不在房间的 uid 不生效。 + * @since V5.4.101 + * @param[in] uid_array 不订阅此 用户uid列表 的音频。 + * @note 此列表为全量列表。如果列表为空或 null，取消订阅黑名单。 + * @param[in] size uid_array 的数组长度。 + * @return + * - 0：方法调用成功。 + * - 其他：方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_set_subscribe_audio_block_list(struct nertc_channel* self, nertc_uid_t* uid_array, uint32_t size); + + +/** + * @if English + * Subscribes or unsubscribes video streams from specified remote users. + * - After a user joins a room, the video streams from remote users are not subscribed by default. If you want to view video + * streams from specified remote users, you can call this method to subscribe to the video streams from the user when the user + * joins the room or publishes the video streams. + * - This method can be called only if a user joins a room. + * @since V4.5.0 + * @param[in] uid The user ID. + * @param[in] type The type of the subscribed video streams. #NERtcRemoteVideoStreamType. + * @param[in] subscribe + * - true: Subscribes to specified video streams. This is the default value. + * - false: Not subscribing to specified video streams. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 订阅或取消订阅指定远端用户的视频流。 + * - + * 用户加入房间之后，默认不订阅远端用户的视频流，如果希望看到指定远端用户的视频，可以在监听到对方加入房间或发布视频流之后，通过此方法订阅该用户的视频流。 + * - 该方法需要在加入房间后调用。 + * @since V4.5.0 + * @param[in] uid 指定用户的用户 ID。 + * @param[in] type 订阅的视频流类型。 #NERtcRemoteVideoStreamType + * @param[in] subscribe + * - true: （默认）订阅指定视频流。 + * - false: 不订阅指定视频流。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_subscribe_remote_video_stream(struct nertc_channel* self, + nertc_uid_t uid, + nertc_video_stream_type stream_type, + nertc_remote_video_stream_type type, + bool subscribe); + +/** + * @if English + * After the method is successfully called, the current user can receive the notification about the status of the live stream. + * @note + * - The method is applicable to only live streaming. + * - You can call the method in a room. The method is valid in calls. + * - Only one address for the relayed stream is added in each call. You need to call the method for multiple times if you want + * to push many streams. An RTC room with the same channelid can create three different streaming tasks. + * - After the method is successfully called, the current user will receive related-status notifications of the live stream. + * @since V4.5.0 + * @param[in] info indicates information of live task. For more information, see \ref NERtcLiveStreamTaskInfo + * "NERtcLiveStreamTaskInfo". + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 添加房间推流任务，成功添加后当前用户可以收到该直播流的状态通知。 + * @note + * - 该方法仅适用直播场景。 + * - 请在房间内调用该方法，该方法在通话中有效。 + * - 该方法每次只能增加一路旁路推流地址。如需推送多路流，则需多次调用该方法。同一个音视频房间（即同一个 channelid）可以创建 3 + * 个不同的推流任务。 + * - 成功添加推流任务后，当前用户会收到该直播流的相关状态通知。 + * @since V4.5.0 + * @param[in] info 直播任务信息。详细信息请参考 \ref NERtcLiveStreamTaskInfo "NERtcLiveStreamTaskInfo" + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_add_live_stream_task(struct nertc_channel* self,const struct nertc_live_stream_task_info* info); + +/** + * @if English + * Updates and modifies a push task in a room. + * @note + * - The method is applicable to only live streaming. + * - You can call the method in a room. The method is valid in calls. + * @since V4.5.0 + * @param[in] info indicates information of live task. For more information, see \ref NERtcLiveStreamTaskInfo + * "NERtcLiveStreamTaskInfo". + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 更新修改房间推流任务。 + * @note + * - 该方法仅适用直播场景。 + * - 请在房间内调用该方法，该方法在通话中有效。 + * @since V4.5.0 + * @param[in] info 直播任务信息。详细信息请参考 \ref NERtcLiveStreamTaskInfo "NERtcLiveStreamTaskInfo" + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_update_live_stream_task(struct nertc_channel* self,const struct nertc_live_stream_task_info* info); + +/** + * @if English + * Deletes a push task. + * @note + * - The method is applicable to only live streaming. + * - You can call the method in a room. The method is valid in calls. + * - When calls stop and all members in the room leave the room, the SDK automatically deletes the streaming task. If some + * users are still in the room, users who create the streaming task need to delete the streaming task. + * @since V4.5.0 + * @param[in] task_id The ID of a live streaming task. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 删除房间推流任务。 + * @note + * - 该方法仅适用直播场景。 + * - 请在房间内调用该方法，该方法在通话中有效。 + * - 通话结束，房间成员全部离开房间后，推流任务会自动删除。如果房间内还有用户存在，则需要创建推流任务的用户删除推流任务。 + * @since V4.5.0 + * @param[in] task_id 直播任务 ID。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_remove_live_stream_task(struct nertc_channel* self, const char* task_id); + +/** + * @if English + * Sends SEI messages. + *
While the local video stream is pushed, SEI data is also sent to sync some additional information. After SEI data is + * sent, the receiver can retrieve the content by listening on \ref IRtcEngineEventHandlerEx::onRecvSEIMsg callback. + * - Condition: After the video stream (mainstream) is enabled, the function can be invoked. + * - Data size limits: The SEI data can contain a maximum of 4,096 bytes in size. Sending an SEI message fails if the data + * exceeds the size limit. If a large amount of data is sent, the video bitrate rises. This degrades the video quality or + * causes broken video frames. + * - Frequency limit: we recommend that the maximum video frame rate does not exceed 10 fps. + * - Time to take effect: After the method is called, the SEI data is sent from the next frame in the fastest fashion or after + * the next 5 frames at the slowest pace.

@note + * - The SEI data is transmitted together with the video stream. Frame loss may occur in poor network connection. The SEI data + * will also get lost. We recommend that you send the data many times within the transmission frequency limits. In this way, + * the receiver can get the data. + * - By default, the SEI is transmitted by using the mainstream channel. + * @since V4.5.0 + * @param data The custom SEI frame data. + * @param length The custom SEI data size whose maximum value does not exceed 4096 bytes. + * @param type The type of the stream channel with which the SEI data is transmitted. For more information, see + * #NERtcVideoStreamType. + * @return The value returned. A value of 0 That the operation is successful. + * - Success: Successfully joins the queue to be sent. The data are sent after the closest video frame. + * - failure: Date are limitedly sent for the high sent frequency and the overloaded queue. Or, the maximum data size exceeds + * 4k. + * @endif + * @if Chinese + * 发送媒体补充增强信息（SEI）。 + *
在本端推流传输视频流数据同时，发送流媒体补充增强信息来同步一些其他附加信息。当推流方发送 SEI 后，拉流方可通过监听 \ref + * IRtcEngineEventHandlerEx::onRecvSEIMsg 的回调获取 SEI 内容。 + * - 调用时机：视频流（主流）开启后，可调用此函数。 + * - 数据长度限制： SEI 最大数据长度为 4096 + * 字节，超限会发送失败。如果频繁发送大量数据会导致视频码率增大，可能会导致视频画质下降甚至卡顿。 + * - 发送频率限制：最高为视频发送的帧率，建议不超过 10 次/秒。 + * - 生效时间：调用本接口之后，最快在下一帧视频数据帧之后发送 SEI 数据，最慢在接下来的 5 帧视频之后发送。 + *

@note + * - SEI 数据跟随视频帧发送，由于在弱网环境下可能丢帧，SEI + * 数据也可能随之丢失，所以建议在发送频率限制之内多次发送，保证接收端收到的概率。 + * - 调用本接口时，默认使用主流通道发送 SEI。 + * @since V4.5.0 + * @param data 自定义 SEI 数据。 + * @param length 自定义 SEI 数据长度，最大不超过 4096 字节。 + * @param type 发送 SEI 时，使用的流通道类型。详细信息请参考 #NERtcVideoStreamType 。 + * @return 操作返回值，成功则返回 0 + * - 成功: 成功进入待发送队列，会在最近的视频帧之后发送该数据 + * - 失败: 数据被限制发送，可能发送的频率太高，队列已经满了，或者数据大小超过最大值 4k + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_send_sei_msg(struct nertc_channel* self,const unsigned char* data,int length,nertc_video_stream_type type); + +/** + * @if English + * Takes a local video snapshot. + *
The takeLocalSnapshot method takes a local video snapshot on the local substream or local mainstream, and call \ref + * NERtcTakeSnapshotCallback "NERtcTakeSnapshotCallback::onTakeSnapshotResult" callback to return data of snapshot screen. + * @note + * - Before you call the method to capture the snapshot from the mainstream, you must first call startVideoPreview or + * enableLocalVideo, and joinChannel. + * - Before you call the method to capture the snapshot from the substream, you must first call startScreenCapture, and + * joinChannel. + * - You can set text, timestamp, and image watermarks at the same time. If different types of watermarks overlap, the layers + * override previous layers following image, text, and timestamp. + * @since V4.5.0 + * @param stream_type The video stream type of the snapshot. You can set the value to mainstream or substream. For more + * information, see #NERtcVideoStreamType. + * @param callback The snapshot callback. For information, see \ref NERtcTakeSnapshotCallback. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 本地视频画面截图。 + *
调用 takeLocalSnapshot 截取本地主流或本地辅流的视频画面，并通过 \ref NERtcTakeSnapshotCallback + * "NERtcTakeSnapshotCallback::onTakeSnapshotResult" 回调返回截图画面的数据。 + * @note + * - 本地主流截图，需要在 startPreview 或者 enableLocalVideo 并 joinChannel 成功之后调用。 + * - 本地辅流截图，需要在 startScreenCapture 并 joinChannel 成功之后调用。 + * - 同时设置文字、时间戳或图片水印时，如果不同类型的水印位置有重叠，会按照图片、文本、时间戳的顺序进行图层覆盖。 + * @since V4.5.0 + * @param stream_type 截图的视频流类型。支持设置为主流或辅流。详细信息请参考 #NERtcVideoStreamType 。 + * @param callback 截图回调。详细信息请参考 \ref NERtcTakeSnapshotCallback 。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_take_local_snapshot(struct nertc_channel* self, + nertc_video_stream_type stream_type, + on_take_snapshot_callback callback); + +/** + * @if English + * Takes a snapshot of a remote video. + *
You can call takeRemoteSnapshot to specify the uid of video screen of remote mainstreams and substreams, and returns + * screenshot data of \ref NERtcTakeSnapshotCallback "NERtcTakeSnapshotCallback::onTakeSnapshotResult" callback. + * @note + * - You need to call takeRemoteSnapshot after receiving callbacks of onUserVideoStart and onUserSubStreamVideoStart. + * - You can set text, timestamp, and image watermarks at the same time. If different types of watermarks overlap, the layers + * override previous layers following image, text, and timestamp. + * @since V4.5.0 + * @param uid The ID of a remote user. + * @param stream_type The video stream type of the snapshot. You can set the value to mainstream or substream. For more + * information, see #NERtcVideoStreamType. + * @param callback The snapshot callback. For information, see \ref NERtcTakeSnapshotCallback. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 远端视频画面截图。 + *
调用 takeRemoteSnapshot 截取指定 uid 远端主流和远端辅流的视频画面，并通过 \ref NERtcTakeSnapshotCallback + * "NERtcTakeSnapshotCallback::onTakeSnapshotResult" 回调返回截图画面的数据。 + * @note + * - takeRemoteSnapshot 需要在收到 onUserVideoStart 与 onUserSubStreamVideoStart 回调之后调用。 + * - 同时设置文字、时间戳或图片水印时，如果不同类型的水印位置有重叠，会按照图片、文本、时间戳的顺序进行图层覆盖。 + * @since V4.5.0 + * @param uid 远端用户 ID。 + * @param stream_type 截图的视频流类型。支持设置为主流或辅流。详细信息请参考 #NERtcVideoStreamType 。 + * @param callback 截图回调。详细信息请参考 \ref NERtcTakeSnapshotCallback 。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_take_remote_snapshot(struct nertc_channel* self, + nertc_uid_t uid, + nertc_video_stream_type stream_type, + on_take_snapshot_callback callback); + +/** + * @if English + * Adjusts the volume of captured signals. + * @note The method only adjusts the volume of captured signals in the application programs without modifying the volumes of the + * device. If you need to modify the volume of the device, see related interfaces of device management. + * @param[in] volume indicates the volume of the captured recording. Valid values: 0 to 400. Where: + * - 0: Mute. + * - 100: The original volume. + * - 400: The maximum value can be four times the original volume. The limit value is protected. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 调节采集信号音量。 + * @note 该方法仅调节应用程序中的采集信号音量，不修改设备音量。如果需要修改设备音量，请查看设备管理相关接口。 + * @param[in] volume 采集录音音量，取值范围为 [0, 400]。其中： + * - 0: 静音； + * - 100: 原始音量； + * - 400: 最大可为原始音量的 4 倍（自带溢出保护）。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_adjust_recording_signal_volume(struct nertc_channel* self, int volume); + +/** + * @if English + * Adjusts the volume of the audio local playback. + * @note The method only adjusts the volume of captured signals in the application programs without modifying the volumes of the + * device. If you need to modify the volume of the device, see related interfaces of device management. + * @param[in] volume indicates the playback volume. Valid range: 0 to 400. Where: + * - 0: Mute. + * - 100: The original volume. + * - 400: The maximum value can be four times the original volume. The limit value is protected. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 调节本地播放音量。 + * @note 该方法仅调节应用程序中音量，不修改设备音量。如果需要修改设备音量，请查看设备管理相关接口。 + * @param[in] volume 播放音量。取值范围为 [0, 400]。其中： + * - 0: 静音； + * - 100: 原始音量； + * - 400: 最大可为原始音量的 4 倍（自带溢出保护）。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_adjust_playback_signal_volume(struct nertc_channel* self, int volume); + +/** + * @if English + * Adjusts the volume of local signal playback from a specified remote user. + *
After you join the room, you can call the method to adjust the volume of local audio playback from different remote + users or repeatedly adjust the volume of audio playback from a specified remote user. + * @note + * - You can call this method after joining a room. + * - The method is valid in the current call. If a remote user exits the room and rejoins the room again, the setting is still + valid until the call ends. + * - The method adjusts the volume of the mixing audio published by a specified remote user. The volume of one remote user can + be adjusted. If you want to adjust multiple remote users, you need to call the method for the required times. + * @since V4.5.0 + * @param uid The ID of a remote user. + * @param volume Playback volume: 0 to 100. + - 0: Mute. + - 100: The original volume. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 调节本地播放的指定远端用户的信号音量。 + *
加入房间后，您可以多次调用该方法设置本地播放的不同远端用户的音量；也可以反复调节本地播放的某个远端用户的音量。 + * @note + * - 请在成功加入房间后调用该方法。 + * - 该方法在本次通话中有效。如果远端用户中途退出房间，则再次加入此房间时仍旧维持该设置，通话结束后设置失效。 + * - + 该方法调节的是本地播放的指定远端用户混音后的音量，且每次只能调整一位远端用户。若需调整多位远端用户在本地播放的音量，则需多次调用该方法。 + * @since V4.5.0 + * @param uid 远端用户 ID。 + * @param volume 播放音量，取值范围为 [0,100]。 + - 0：静音。 + - 100：原始音量。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_adjust_user_playback_signal_volume(struct nertc_channel* self, nertc_uid_t uid, int volume); + +/** + * @if Chinese + * 调节本地播放的指定房间的所有远端用户的信号音量。 + *
通过此接口可以实现在通话过程中随时调节指定房间内的所有远端用户在本地播放的混音音量。 + * @since V4.6.50 + * @par 调用时机 + * 请在引擎初始化之后调用此接口，该方法在加入房间前后都可调用。 + * @note + * - 该方法设置内部引擎为启用状态，在 leaveChannel 后失效，但在本次通话过程中有效 + * @par 参数说明 + * + * + * + * + * + * + * + * + * + * + * + *
**参数名称****类型****描述**
volumeuint64_t播放音量，取值范围为 [0,400]。
  • 0：静音。
  • 100：原始音量。
  • 400：最大可为原始音量的 4 + * 倍（自带溢出保护）。
+ * @return + * - 0（kNERtcNoError）：方法调用成功。 + * - 其他：方法调用失败。 + * - 30005（kNERtcErrInvalidState）：状态错误，比如引擎未初始化。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_adjust_channel_playback_signal_volume(struct nertc_channel* self, uint32_t volume); + +/** + * @if English + * Starts to relay media streams across rooms. + * - The method can invite co-hosts across rooms. Media streams from up to four rooms can be relayed. A room can receive + * multiple relayed media streams. + * - After you call this method, the SDK triggers `onMediaRelayStateChanged` and `onMediaRelayEvent`. The return reports the + * status and events about the current relayed media streams across rooms. + * @note + * - You can call this method after joining a room. Before you call the method, you must set the destination room in the + * `NERtcChannelMediaRelayConfiguration` parameter in `dest_infos`. + * - The method is applicable only to the host in live streaming. + * - If you want to call the method again, you must first call the `stopChannelMediaRelay` method to exit the current relaying + * status. + * - If you succeed in relaying the media stream across rooms, and want to change the destination room, for example, add or + * remove the destination room, you can call `updateChannelMediaRelay` to update the information about the destination room. + * @since V4.5.0 + * @param config specifies the configuration for the media stream relay across rooms. For more information, see + * #NERtcChannelMediaRelayConfiguration. + * @return {@code 0} A value of 0 returned indicates that the method call is successful. Otherwise, the method call fails. + * @endif + * @if Chinese + * 开始跨房间媒体流转发。 + * - 该方法可用于实现跨房间连麦等场景。支持同时转发到 4 个房间，同一个房间可以有多个转发进来的媒体流。 + * - 成功调用该方法后，SDK 会触发 `onMediaRelayStateChanged` 和 `onMediaRelayEvent` + * 回调，并在回调中报告当前的跨房间媒体流转发状态和事件。 + * @note + * - 请在成功加入房间后调用该方法。调用此方法前需要通过 `NERtcChannelMediaRelayConfiguration` 中的 `dest_infos` 设置目标房间。 + * - 该方法仅对直播场景下的主播角色有效。 + * - 成功调用该方法后，若您想再次调用该方法，必须先调用 `stopChannelMediaRelay` 方法退出当前的转发状态。 + * - 成功开始跨房间转发媒体流后，如果您需要修改目标房间，例如添加或删减目标房间等，可以调用方法 `updateChannelMediaRelay` + * 更新目标房间信息。 + * @since V4.5.0 + * @param config 跨房间媒体流转发参数配置信息。 + * @return 成功返回0，其他则失败 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_start_channel_media_relay(struct nertc_channel* self,const struct nertc_channel_media_relay_config* config); + +/** + * @if English + * Updates the information of the destination room for the media stream relay. + *
You can call this method to relay the media stream to multiple rooms or exit the current room. + * - You can call this method to change the destination room, for example, add or remove the destination room. + * - After you call this method, the SDK triggers `onMediaRelayStateChange` and `onMediaRelayEvent`. The return reports the + * status and events about the current relayed media streams across rooms. + * @note Before you call the method, you must join the room and call `startChannelMediaRelay` to relay the media stream across + * rooms. Before you call the method, you must set the destination room in the `NERtcChannelMediaRelayConfiguration` parameter + * in `dest_infos`. + * @since V4.5.0 + * @param config The configuration for destination rooms. + * @return A value of 0 returned indicates that the method call is successful. Otherwise, the method call fails. + * @endif + * @if Chinese + * 更新媒体流转发的目标房间。 + *
成功开始跨房间转发媒体流后，如果你希望将流转发到多个目标房间，或退出当前的转发房间，可以调用该方法。 + * - 成功开始跨房间转发媒体流后，如果您需要修改目标房间，例如添加或删减目标房间等，可以调用此方法。 + * - 成功调用该方法后，SDK 会触发 `onMediaRelayStateChange` 和 `onMediaRelayEvent` + * 回调，并在回调中报告当前的跨房间媒体流转发状态和事件。 + * @note 请在加入房间并成功调用 `startChannelMediaRelay` 开始跨房间媒体流转发后，调用此方法。调用此方法前需要通过 + * `NERtcChannelMediaRelayConfiguration` 中的 `dest_infos` 设置目标房间。 + * @since V4.5.0 + * @param config 目标房间配置信息 + * @return 成功返回0，其他则失败 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_update_channel_media_relay(struct nertc_channel* self,const struct nertc_channel_media_relay_config* config); + +/** + * @if English + * Stops relaying media streams. + *
If the host leaves the room, media stream replay across rooms automatically stops. You can also call + * stopChannelMediaRelay. In this case, the host exits all destination rooms. + * - If you call this method, the SDK triggers the `onMediaRelayStateChange` callback. If `NERtcChannelMediaRelayStateIdle` is + * returned, the media stream relay stops. + * - If the method call failed, the SDK triggers the `onMediaRelayStateChange` callback that returns the status code + * `NERtcChannelMediaRelayStateFailure`. + * @since V4.5.0 + * @return A value of 0 returned indicates that the method call is successful. Otherwise, the method call fails. + * @endif + * @if Chinese + * 停止跨房间媒体流转发。 + *
主播离开房间时，跨房间媒体流转发自动停止，您也可以在需要的时候随时调用 `stopChannelMediaRelay` + * 方法，此时主播会退出所有目标房间。 + * - 成功调用该方法后，SDK 会触发 `onMediaRelayStateChange` 回调。如果报告 + * `NERtcChannelMediaRelayStateIdle`，则表示已停止转发媒体流。 + * - 如果该方法调用不成功，SDK 会触发 `onMediaRelayStateChange` 回调，并报告状态码 `NERtcChannelMediaRelayStateFailure`。 + * @since V4.5.0 + * @return 成功返回0，其他则失败 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_stop_channel_media_relay(struct nertc_channel* self); + +/** + * @if English + * Sets the fallback option for the published local video stream based on the network conditions. + *
The quality of the published local audio and video streams is degraded with poor quality network connections. After + * calling this method and setting the option to #kNERtcStreamFallbackAudioOnly: + * - With unreliable upstream network connections and the quality of audio and video streams is downgraded, the SDK + * automatically disables video stream or stops receiving video streams. In this way, the communication quality is guaranteed. + * - The SDK monitors the network performance and recover audio and video streams if the network quality improves. + * - If the locally published audio and video stream falls back to audio stream, or recovers to audio and video stream, the + * SDK triggers the onLocalPublishFallbackToAudioOnly callback.

@note You must call the method before you call joinChannel. + * @since V4.5.0 + * @param option The fallback option of publishing audio and video streams. The fallback kNERtcStreamFallbackAudioOnly is + * disabled by default. For more information, see nertc::NERTCStreamFallbackOption. + * @return {@code 0} A value of 0 returned indicates that the method call is successful. Otherwise, the method call fails. + * @endif + * @if Chinese + * 设置弱网条件下发布的音视频流回退选项。 + *
在网络不理想的环境下，发布的音视频质量都会下降。使用该接口并将 option 设置为 #kNERtcStreamFallbackAudioOnly 后： + * - SDK 会在上行弱网且音视频质量严重受影响时，自动关断视频流，尽量保证音频质量。 + * - 同时 SDK 会持续监控网络质量，并在网络质量改善时恢复音视频流。 + * - 当本地发布的音视频流回退为音频流时，或由音频流恢复为音视频流时，SDK 会触发本地发布的媒体流已回退为音频流 + * onLocalPublishFallbackToAudioOnly 回调。

@note 请在加入房间（joinChannel）前调用此方法。 + * @since V4.5.0 + * @param option 发布音视频流的回退选项，默认为不开启回退 kNERtcStreamFallbackAudioOnly。详细信息请参考 + * nertc::NERTCStreamFallbackOption 。 + * @return {@code 0} 方法调用成功，其他调用失败 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_set_local_publish_fallback_option(struct nertc_channel* self,nertc_stream_fallback_option option); + +/** + * @if English + * Sets the fallback option for the subscribed remote audio and video stream with poor network connections. + *
The quality of the subscribed audio and video streams is degraded with unreliable network connections. You can use the + * interface to set the option as #kNERtcStreamFallbackVideoStreamLow or #kNERtcStreamFallbackAudioOnly. + * - In unreliable downstream network connections, the SDK switches to receive a low-quality video stream or stops receiving + * video streams. In this way, the communication quality is maintained or improved. + * - The SDK monitors the network quality and resumes the video stream when the network condition improves. + * - If the subscribed remote video stream falls back to audio only, or the audio-only stream switches back to the video + * stream, the SDK triggers the onRemoteSubscribeFallbackToAudioOnly callback.

@note You must call the method before you + * call joinChannel. + * @since V4.5.0 + * @param option The fallback option for the subscribed remote audio and video stream. With unreliable network connections, + * the stream falls back to a low-quality video stream of kNERtcStreamFallbackVideoStreamLow. For more information, see + * nertc::NERTCStreamFallbackOption . + * @return {@code 0} A value of 0 returned indicates that the method call is successful. Otherwise, the method call fails. + * @endif + * @if Chinese + * 设置弱网条件下订阅的音视频流回退选项。 + *
弱网环境下，订阅的音视频质量会下降。使用该接口并将 option 设置为 #kNERtcStreamFallbackVideoStreamLow 或者 + * #kNERtcStreamFallbackAudioOnly 后： + * - SDK 会在下行弱网且音视频质量严重受影响时，将视频流切换为小流，或关断视频流，从而保证或提高通信质量。 + * - SDK 会持续监控网络质量，并在网络质量改善时自动恢复音视频流。 + * - 当远端订阅流回退为音频流时，或由音频流恢复为音视频流时，SDK 会触发远端订阅流已回退为音频流 + * onRemoteSubscribeFallbackToAudioOnly 回调。

@note 请在加入房间（joinChannel）前调用此方法。 + * @since V4.5.0 + * @param option 订阅音视频流的回退选项，默认为弱网时回退到视频小流 kNERtcStreamFallbackVideoStreamLow。详细信息请参考 + * nertc::NERTCStreamFallbackOption 。 + * @return {@code 0} 方法调用成功，其他调用失败 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_set_remote_subscribe_fallback_option(struct nertc_channel* self, nertc_stream_fallback_option option); + +/** + * @if English + * Sets a remote audio stream to high priority + * Sets a remote audio streams to high priority during automatic stream subscription. Users can hear the audio stream with high + * priority. + * @note + * - The priority of a remote audio stream must be set during a call and automatic stream subscription must be enabled (by + * default) + * - Only one audio stream can be set to high priority. The subsequent call will override the previous setting. + * - The priority of the audio stream will be reset after the call ends + * @param[in] enabled sets or cancels high priority to a remote audio stream. + * - true: sets high priority to a remote audio stream. + * - false: cancels high priority of a remote audio stream. + * @param[in] uid User ID + * @return + * - 0: success； + * - Other values: failure + * @endif + * @if Chinese + * 设置远端用户音频流为高优先级。 + * 支持在音频自动订阅的情况下，设置某一个远端用户的音频为最高优先级，可以优先听到该用户的音频。 + * @note + * - 该接口需要通话中设置，并需要自动订阅打开（默认打开）。 + * - 该接口只能设置一个用户的优先级，后设置的会覆盖之前的设置。 + * - 该接口通话结束后，优先级设置重置。 + * @param[in] enabled 是否设置音频订阅优先级。 + * - true：设置音频订阅优先级。 + * - false：取消设置音频订阅优先级。 + * @param[in] uid 用户 ID + * @return + * - 0: 方法调用成功。 + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_set_remote_high_priority_audio_stream(struct nertc_channel* self, bool enabled, nertc_uid_t uid); + +/** +* @if English +* Enables or disables the external video source. +*
When you enable the external video source through the method, you need to set kNERtcExternalVideoDeviceID as the ID of +* external video source with IVideoDeviceManager::setDevice kNERtcExternalVideoDeviceID method. +* @note The method enables the internal engine, which is still valid after you call \ref IRtcEngine::leaveChannel +* "leaveChannel". +* @param[in] enabled Specifies whether input external video source data. +* - true: Enables external video source. +* - false: Disables the external video source (default). +* @return +* - 0: Success. +* - Other values: Failure. +* @endif +* @if Chinese +* 开启或关闭外部视频源数据输入。 +*
通过该方法启用外部视频数据输入功能时，需要通过 IVideoDeviceManager::setDevice 设置 kNERtcExternalVideoDeviceID +* 为外部视频输入源 ID。 +* @note 该方法设置内部引擎为启用状态，在 \ref IRtcEngine::leaveChannel "leaveChannel" 后仍然有效。 +* @param[in] type 视频流通道类型 #NERtcVideoStreamType +* - kNERTCVideoStreamMain，打开或关闭主流通道的外部源 +* - kNERTCVideoStreamSub， 打开或关闭辅流通道的外部源 +* @param[in] enabled 是否外部视频源数据输入: +* - true: 开启外部视频源数据输入； +* - false: 关闭外部视频源数据输入 (默认)。 +* @return +* - 0: 方法调用成功； +* - 其他: 方法调用失败。 +* @endif +*/ +NERTC_API int NERTC_CALL nertc_channel_set_external_video_source(struct nertc_channel* self, nertc_video_stream_type type, bool enabled); + +/** + * @if English + * Pushes the external video frames. + *
The method actively pushes the data of video frames that are encapsulated with the NERtcVideoFrame class to the SDK. + * Make sure that you have already called setExternalVideoSource with a value of true before you call this method. Otherwise, + * an error message is repeatedly prompted if you call the method. + * @note The method enables the internal engine, which is invalid after you call \ref IRtcEngine::leaveChannel "leaveChannel". + * @param[in] type The video frame format. + * @param[in] frame The video frame data. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 推送外部视频帧。 + *
该方法主动将视频帧数据用 NERtcVideoFrame 类封装后传递给 SDK。 请确保在你调用本方法前已调用 + * setExternalVideoSource，并将参数设为 true，否则调用本方法后会一直报错。 + * @note 该方法设置内部引擎为启用状态，在 \ref IRtcEngine::leaveChannel "leaveChannel" 后不再有效。 + * @param[in] type 视频帧数据格式。 + * @param[in] frame 视频帧数据。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_push_external_video_frame(struct nertc_channel* self, + nertc_video_stream_type type, + struct nertc_video_frame* frame); + +/** + * @if English + * Publishes or unpublishes the local audio stream. + *
When a user joins a room, the feature is enabled by default. + *
The method does not affect receiving or playing the remote audio stream. The enableLocalAudio(false) method is suitable + * for scenarios where clients only receives remote media streams and does not publish any local streams. + * @note + * - The method controls data transmitted over the main stream + * - The method can be called before or after a user joins a room. + * @since V4.6.10 + * @param enabled specifies whether to publish the local audio stream. + * - true(default): publishes the local audio stream. + * - false: unpublishes the local audio stream. + * @param mediaType media type. Audio type is supported. + * @return + * - 0: success + * - Others: failure + * @endif + * @if Chinese + * 开启或关闭本地媒体流（主流）的发送。 + *
该方法用于开始或停止向网络发送本地音频或视频数据。 + *
该方法不影响接收或播放远端媒体流，也不会影响本地音频或视频的采集状态。 + * @since V4.6.10 + * @note + * - 该方法暂时仅支持控制音频流的发送。 + * - 该方法在加入房间前后均可调用。 + * - 停止发送媒体流的状态会在通话结束后被重置为允许发送。 + * - 成功调用该方法切换本地用户的发流状态后，房间内其他用户会收到 \ref IRtcChannelEventHandler::onUserAudioStart + * "onUserAudioStart"（开启发送音频）或 \ref IRtcChannelEventHandler::onUserAudioStop "onUserAudioStop"（停止发送音频）的回调。 + * @par 相关接口 + * - \ref IRtcChannel::muteLocalAudioStream "muteLocalAudioStream"： + * - 在需要开启本地音频采集（监测本地用户音量）但不发送音频流的情况下，您也可以调用 muteLocalAudioStream(true) 方法。 + * - 两者的差异在于， muteLocalAudioStream(true) 仍然保持与服务器的音频通道连接，而 enableMediaPub(false) + * 表示断开此通道，因此若您的实际业务场景为多人并发的大房间，建议您调用 enableMediaPub 方法。 + * @param enabled 是否发布本地媒体流。 + * - true（默认）：发布本地媒体流。 + * - false：不发布本地媒体流。 + * @param media_type 媒体发布类型，暂时仅支持音频。 + * @return + * - 0：方法调用成功。 + * - 其他：方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_enable_media_publish(struct nertc_channel* self, + bool enabled, + nertc_media_pub_type media_type); + +/** + * @if Chinese + * 更新权限密钥。 + * - 通过本接口可以实现当用户权限被变更，或者收到权限密钥即将过期的回调 \ref + * nertc::IRtcChannelEventHandler::onPermissionKeyWillExpire() "onPermissionKeyWillExpire" 时，更新权限密钥。 + * @since V4.6.29 + * @par 使用前提 + * 请确保已开通高级 Token 鉴权功能，具体请联系网易云信商务经理。 + * @par 调用时机 + * 请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。 + * @par 业务场景 + * 适用于变更指定用户加入、创建房间或上下麦时发布流相关权限的场景。 + * @par 参数说明 + * + * + * + * + * + * + * + * + * + * + * + *
**参数名称****类型****描述**
keyconst char*新的权限密钥。
+ * @par 示例代码 + * @code + * if (rtc_engine_) { + * std::string key;//向服务器请求得到的权限key，具体请参考官方文档的高级 Token 鉴权章节。 + * rtc_engine_->updatePermissionKey(key.c_str())); if (kNERtcNoError != res) { + * } + * @endcode + * @par 相关回调 + * 调用此接口成功更新权限密钥后会触发 \ref nertc::IRtcChannelEventHandler::onUpdatePermissionKey() "onUpdatePermissionKey" + * 回调。 + * @return + * - 0（kNERtcNoError）：方法调用成功。 + * - 其他：方法调用失败。 + * - 30003（kNERtcErrInvalidParam）：参数错误，比如 key 无效。 + * - 30005（kNERtcErrInvalidState)：当前状态不支持的操作，比如引擎尚未初始化。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_update_permission_key(struct nertc_channel* self, const char* key); +/** + * @if Chinese + * 上报自定义事件 + * @param event_name 事件名 不能为空 + * @param custom_identify 自定义标识，比如产品或业务类型，如不需要填null + * @param parameters 参数键值对 ，参数值支持String 及java基本类型(int 、bool....) ， 如不需要填null + * @return 操作返回值，成功则返回 0 + * @endif + */ +NERTC_API int NERTC_CALL nertc_channel_report_custom_event(struct nertc_channel* self, + const char* event_name, + const char* custom_identify, + const char* parameters); + +/** + * 设置范围语音模式 + * @note 此接口在加入房间前后均可调用。 + * @param mode 范围语音模式 + * @return 操作返回值，成功则返回 0 + */ +NERTC_API int NERTC_CALL nertc_channel_set_range_audio_mode(struct nertc_channel* self, nertc_range_audio_mode mode); + +/** + * 设置范围语音小队 + * @note 此接口在加入房间前后均可调用。 + * @param team_id 小队ID + * @return 操作返回值，成功则返回 0 + */ +NERTC_API int NERTC_CALL nertc_channel_set_range_audio_team_id(struct nertc_channel* self, int32_t team_id); + +/** + * 引擎3D音效算法距离范围设置 + * @param audible_distance 监听器能够听到扬声器并接收其文本消息的距离扬声器的最大距离。无默认值, 有效范围[1, ∞)。 + * @param conversational_distance 控制扬声器音频保持其原始音量的范围，超出该范围时，语音聊天的响度在被听到时开始淡出。 + * 默认值为 1。 + * @param roll_off:距离衰减模式 #NERtcDistanceRolloffModel ，默认值 #kNERtcDistanceRolloffNone + * @return + * - 0: 方法调用成功 + * - 其他: 调用失败 + */ +NERTC_API int NERTC_CALL nertc_channel_set_audio_recv_range(struct nertc_channel* self, int audible_distance, int conversational_distance, nertc_distance_rolloff_model roll_off); + +/** + * 引擎3D音效算法中本人坐标方位更新接口 + * @note 依赖enableSpatializer接口开启，enableSpatializer接口关闭后重置设置 + * @param speaker_position 嘴巴位置信息，默认值{0,0,0} + * @param speaker_quaternion 嘴巴方向信息，四元组格式，默认值{0,0,0,0} + * @param head_position 耳朵位置信息，默认值{0,0,0} + * @param head_quaternion 耳朵方向信息，四元组格式，默认值{0,0,0,0} + * @return + * - 0: 方法调用成功 + * - 其他: 调用失败 + */ +NERTC_API int NERTC_CALL nertc_channel_update_self_position(struct nertc_channel* self, const struct nertc_position_info* info); + +/** + * 引擎3D音效算法中房间混响效果开关 + * @note 依赖enableSpatializer接口开启 + * @param enable 混响效果开关，默认值关闭 + * @return + * - 0: 方法调用成功 + * - 其他: 调用失败 + */ +NERTC_API int NERTC_CALL nertc_channel_enable_spatializer_room_effects(struct nertc_channel* self, bool enable); +/** + * 引擎3D音效算法中房间混响属性 + * @note 依赖enableSpatializer接口开启 + * @param room_property 房间属性 #NERtcSpatializerRoomProperty + * @return + * - 0: 方法调用成功 + * - 其他: 调用失败 + */ +NERTC_API int NERTC_CALL nertc_channel_set_spatializer_room_property(struct nertc_channel* self, const struct nertc_spatializer_room_property* room_property); + +/** + * 引擎3D音效算法中渲染模式 + * @note 依赖enableSpatializer接口开启 + * @param mode 渲染模式 #NERtcSpatializerRenderMode ，默认值 #kNERtcSpatializerRenderBinauralHighQuality + * @return + * - 0: 方法调用成功 + * - 其他: 调用失败 + */ +NERTC_API int NERTC_CALL nertc_channel_set_spatializer_render_mode(struct nertc_channel* self, nertc_spatializer_render_mode mode); + +/** + * 初始化引擎3D音效算法 + * @note 此接口在加入房间前调用，退出房间后不重置 + * @return + * - 0: 方法调用成功 + * - 其他: 调用失败 + */ +NERTC_API int NERTC_CALL nertc_channel_init_spatializer(struct nertc_channel* self); + +/** + * 引擎3D音效算法开关 + * @note 通话前调用，通话结束后不重置 + * @param enable 是否打开3D音效算法功能 + * @return + * - 0: 方法调用成功 + * - 其他: 调用失败 + */ +NERTC_API int NERTC_CALL nertc_channel_enable_spatializer(struct nertc_channel* self, bool enable); + +NERTC_END_DECLS +#endif diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_channel_events.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_channel_events.h new file mode 100644 index 0000000..8d7c9ef --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_channel_events.h @@ -0,0 +1,763 @@ +/** @file nertc_channel_event_handler.h + * @brief NERTC SDK IRtcChannel回调接口头文件。 + * NERTC SDK所有接口参数说明: 所有与字符串相关的参数(char *)全部为UTF-8编码。 + * @copyright (c) 2015-2021, NetEase Inc. All rights reserved + * @date 2021/05/10 + */ + +#ifndef NERTC_CHANNEL_EVENTS_H +#define NERTC_CHANNEL_EVENTS_H + +#include "nertc_engine_defines.h" +#include "nertc_error_code.h" +#include "nertc_warn_code.h" + +NERTC_BEGIN_DECLS +/** + * @if English + * IRtcChannelEventHandler callback interface class is used to send IRtcChannel callback event notifications to the app from + * SDK. The app gets IRtcChannel event notifications from the SDK through inheriting the interface class.
All methods in + * this interface class have their (empty) default implementations, and the application can inherit only some of the required + * events instead of all of them. When calling a callback method, the application must not implement time-consuming operations + * or call blocking-triggered APIs. For example, if you want to enable audio and video, the SDK may be affected in the runtime. + * @since V4.5.0 + * @endif + * @if Chinese + * IRtcChannelEventHandler 回调接口类用于 SDK 向 App 发送IRtcChannel回调事件通知，App 通过继承该接口类的方法获取 SDK + * IRtcChannel的事件通知。
接口类的所有方法都有缺省（空）实现，App 可以根据需要只继承关心的事件。在回调方法中，App + * 不应该做耗时或者调用可能会引起阻塞的 API（如开启音频或视频等），否则可能影响 SDK 的运行。 + * @endif + */ +struct nertc_channel_events { + struct nertc_channel* self; + /** + * @if English + * Occurs when the error occurs. + *
The callback is triggered to report an error related to network or media during SDK runtime. In most cases, the SDK + * cannot fix the issue and resume running. The SDK requires the app to take action or informs the user of the issue. + * @param error_code The error code. For more information, see NERtcDMErrorCode. + * @param msg Error description. + * @since V4.5.0 + * @endif + * @if Chinese + * 发生错误回调。 + *
该回调方法表示 SDK 运行时出现了（网络或媒体相关的）错误。通常情况下，SDK上报的错误意味着SDK无法自动恢复，需要 App + * 干预或提示用户。 + * @param error_code 错误码。详细信息请参考 NERtcDMErrorCode + * @param msg 错误描述。 + * @endif + */ + void (NERTC_CALL *on_error)(void* self, int error_code, const char* msg); + /** + * @if English + * Occurs when a warning occurs. + *
The callback is triggered to report a warning related to network or media during SDK runtime. In most cases, the app + * ignores the warning message and the SDK resumes running. + * @param warn_code The warning code. For more information, see {@link NERtcWarnCode}. + * @param msg The warning description. + * @since V4.5.0 + * @endif + * @if Chinese + * 发生警告回调。 + *
该回调方法表示 SDK 运行时出现了（网络或媒体相关的）警告。通常情况下，SDK 上报的警告信息 App 可以忽略，SDK 会自动恢复。 + * @param warn_code 警告码。详细信息请参考 {@link NERtcWarnCode}。 + * @param msg 警告描述。 + * @endif + */ + void (NERTC_CALL *on_warning)(void* self, int warn_code, const char* msg); + /** + * @if English + * Occurs when an API call finished. + *
This callback method indicates that the SDK has finished executing a user's API call. + * @param api_name The API name. + * @param error The execute result code. + * @param message The execute result message. + * @endif + * @if Chinese + * API调用结束回调。 + *
该回调方法表示 SDK 执行完了一个用户的API调用。 + * @param api_name API名称 + * @param error API执行结果错误码。 + * @param message API执行结果描述。 + * @endif + */ + void (NERTC_CALL *on_api_call_executed)(void* self, const char* api_name, nertc_error_code error, const char* message); + /** + * @if English + * Allows a user to join a room. The callback indicates that the client has already signed in. + * @param cid The ID of the room that the client joins. + * @param uid Specifies the ID of a user. If you specify the uid in the joinChannel method, a specificed ID is returned at + * the time. If not, the ID automatically assigned by the CommsEase’s server is returned. + * @param result Indicates the result. + * @param elapsed The time elapsed from calling the joinChannel method to the occurrence of this event. Unit: milliseconds. + * @since V4.5.0 + * @endif + * @if Chinese + * 加入房间回调，表示客户端已经登入服务器。 + * @param cid 客户端加入的房间 ID。 + * @param uid 用户 ID。 如果在 joinChannel 方法中指定了 uid，此处会返回指定的 ID; 如果未指定 + * uid，此处将返回云信服务器自动分配的 ID。 + * @param result 返回结果。 + * @param elapsed 从 joinChannel 开始到发生此事件过去的时间，单位为毫秒。 + * @endif + */ + void (NERTC_CALL *on_join_channel)(void* self, channel_id_t cid, nertc_uid_t uid, nertc_error_code result, uint64_t elapsed); + /** + * @if English + * Triggers reconnection. + *
In some cases, a client may be disconnected from the server, the SDK starts reconnecting. The callback is triggered + * when the reconnection starts. + * @param cid Specifies the ID of a room. + * @param uid Specifies the ID of a user. + * @endif + * @if Chinese + * 触发重连。 + *
有时候由于网络原因，客户端可能会和服务器失去连接，SDK会进行自动重连，开始自动重连后触发此回调。 + * @param cid 房间 ID。 + * @param uid 用户 ID。 + * @endif + */ + void (NERTC_CALL *on_reconnecting_start)(void* self, channel_id_t cid, nertc_uid_t uid); + /** + * @if English + * Occurs when the state of network connection is changed. + *
The callback is triggered when the state of network connection is changed. The callback returns the current state of + * network connection and the reason why the network state changes. + * @param state The state of current network connection. + * @param reason The reason why the network state changes. + * @since V4.5.0 + * @endif + * @if Chinese + * 网络连接状态已改变回调。 + *
该回调在网络连接状态发生改变的时候触发，并告知用户当前的网络连接状态和引起网络状态改变的原因。 + * @param state 当前的网络连接状态。 + * @param reason 引起当前网络连接状态发生改变的原因。 + * @endif + */ + void (NERTC_CALL *on_connection_state_change)(void* self,nertc_connection_state_type state,nertc_reason_connection_changed_type reason); + /** + * @if English + * Occurs when a user rejoins a room. + *
If a client is disconnected from the server due to poor network quality, the SDK starts reconnecting. If the client and + * server are reconnected, the callback is triggered. + * @param cid The ID of the room that the client joins. + * @param uid The ID of a user. + * @param result The result. + * @param elapsed The time elapsed from reconnection to the occurrence of this event. Unit: milliseconds. + * @since V4.5.0 + * @endif + * @if Chinese + * 重新加入房间回调。 + *
在弱网环境下，若客户端和服务器失去连接，SDK会自动重连。自动重连成功后触发此回调方法。 + * @param cid 客户端加入的房间 ID。 + * @param uid 用户 ID。 + * @param result 返回结果。 + * @param elapsed 从开始重连到发生此事件过去的时间，单位为毫秒。 + * @endif + */ + void (NERTC_CALL *on_rejoin_channel)(void* self, channel_id_t cid, nertc_uid_t uid, nertc_error_code result, uint64_t elapsed); + /** + * @if English + * Occurs when a user leaves a room. + *
After an app invokes the leaveChannel method, SDK prompts whether the app successfully leaves the room. + * @param result The result. + * @since V4.5.0 + * @endif + * @if Chinese + * 退出房间回调。 + *
App 调用 leaveChannel 方法后，SDK 提示 App 退出房间是否成功。 + * @param result 返回结果。 + * @endif + */ + void (NERTC_CALL *on_leave_channel)(void* self, nertc_error_code result); + /** + * @if English + * Network connection interruption. + * @note + * - The callback is triggered if the SDK fails to connect to the server three consecutive times after you successfully call + * the joinChannel method. + * - A client may be disconnected from the server in poor network connection. At this time, the SDK needs not automatically + * reconnecting until the SDK triggers the callback method. + * @param reason The reason why the network is disconnected. + * @since V4.5.0 + * @endif + * @if Chinese + * 网络连接中断 + * @note + * - SDK 在调用 joinChannel 加入房间成功后，如果和服务器失去连接且连续 3 次重连失败，就会触发该回调。 + * - 由于非网络原因，客户端可能会和服务器失去连接，此时SDK无需自动重连，直接触发此回调方法。 + * @param reason 网络连接中断原因。 + * @endif + */ + void (NERTC_CALL *on_disconnect)(void* self, nertc_error_code reason); + /** + * @if English + * Occurs when a user changes the role in live streaming. + *
After the local user joins a room, the user can call the \ref IRtcEngine::setClientRole "setClientRole" to change the + * role. Then, the callback is triggered. For example, you can switch the role from host to audience, or from audience to + * host. + * @note In live streaming, if you join a room and successfully call this method to change the role, the following callbacks + * are triggered. + * - If the role changes from host to audience, the onClientRoleChange is locally triggered, and the \ref + * nertc::IRtcEngineEventHandler::onUserLeft "onUserLeft" is remotely triggered. + * - If the role is changed from audience to host, the onClientRoleChange callback is locally triggered, and the \ref + * nertc::IRtcEngineEventHandler::onUserJoined "onUserJoined" is remotely triggered. + * @param oldRole The role before the user changes the role. + * @param newRole The role after the change. + * @since V4.5.0 + * @endif + * @if Chinese + * 直播场景下用户角色已切换回调。 + *
本地用户加入房间后，通过 \ref IRtcEngine::setClientRole "setClientRole" + * 切换用户角色后会触发此回调。例如主播切换为观众、从观众切换为主播。 + * @note 直播场景下，如果您在加入房间后调用该方法切换用户角色，调用成功后，会触发以下回调： + * - 主播切观众，本端触发onClientRoleChanged回调，远端触发\ref nertc::IRtcEngineEventHandler::onUserLeft "onUserLeft"回调。 + * - 观众切主播，本端触发onClientRoleChanged回调，远端触发\ref nertc::IRtcEngineEventHandler::onUserJoined + * "onUserJoined"回调。 + * @param oldRole 切换前的角色。 + * @param newRole 切换后的角色。 + * @endif + */ + void (NERTC_CALL *on_client_role_changed)(void* self, nertc_client_role old_role, nertc_client_role new_role); + /** + * @if English + * Occurs when a remote user joins the current room. + *
The callback prompts that a remote user joins the room and returns the ID of the user that joins the room. If the user + * ID already exists, the remote user also receives a message that the user already joins the room, which is returned by the + * callback. + * @param uid The ID of the user that joins the room. + * @param user_name The name of the remote user who joins the room. + * @since V4.5.0 + * @endif + * @if Chinese + * 远端用户加入当前房间回调。 + *
该回调提示有远端用户加入了房间，并返回新加入用户的 + * ID；如果加入之前，已经有其他用户在房间中了，新加入的用户也会收到这些已有用户加入房间的回调。 + * @param uid 新加入房间的远端用户 ID。 + * @param user_name 新加入房间的远端用户名。 + * @param custom_info 该远端用户加入的额外信息。 + * @endif + */ + void (NERTC_CALL *on_user_joined)(void* self, nertc_uid_t uid, const char* user_name, const struct nertc_user_join_extra_info* custom_info); + /** + * @if English + * Occurs when a remote user leaves a room. + *
A message is returned indicates that a remote user leaves the room or becomes disconnected. In most cases, a user + * leaves a room due to the following reasons: The user exit the room or connections time out. + * - When a user leaves a room, remote users will receive callback notifications that users leave the room. In this way, users + * can be specified to leave the room. + * - If the connection times out, and the user does not receive data packets for a time period of 40 to 50 seconds, then the + * user becomes disconnected. + * @param uid The ID of the user that leaves the room. + * @param reason The reason why remote user leaves. + * @since V4.5.0 + * @endif + * @if Chinese + * 远端用户离开当前房间的回调。 + *
提示有远端用户离开了房间（或掉线）。通常情况下，用户离开房间有两个原因，即正常离开和超时掉线： + * - 正常离开的时候，远端用户会收到正常离开房间的回调提醒，判断用户离开房间。 + * - 超时掉线的依据是，在一定时间内（40~50s），用户没有收到对方的任何数据包，则判定为对方掉线。 + * @param uid 离开房间的远端用户 ID。 + * @param reason 远端用户离开原因。 + * @param custom_info 该远端用户离开的额外信息。 + * @endif + */ + void (NERTC_CALL *on_user_left)(void* self, nertc_uid_t uid, nertc_session_leave_reason reason, const struct nertc_user_join_extra_info* custom_info); + /** + * @if English + * Occurs when a remote user enables audio. + * @param uid The ID of a remote user. + * @since V4.5.0 + * @endif + * @if Chinese + * 远端用户开启音频的回调。 + * @param stream_type 音频流类型。@since 4.6.10 + * @param uid 远端用户ID。 + * @endif + */ + void (NERTC_CALL *on_user_audio_start)(void* self, nertc_audio_stream_type type, nertc_uid_t uid); + /** + * @if English + * Occurs when a remote user disables audio. + * @param uid The ID of a remote user. + * @since V4.5.0 + * @endif + * @if Chinese + * 远端用户停用音频的回调。 + * @param stream_type 音频流类型。@since 4.6.10 + * @param uid 远端用户ID。 + * @endif + */ + void (NERTC_CALL *on_user_audio_stop)(void* self, nertc_audio_stream_type type, nertc_uid_t uid); + /** + * @if English + * Callbacks that specify whether to mute remote users. + * @param uid The ID of a remote user. + * @param mute Whether to unmute the remote user. + * @since V4.5.0 + * @endif + * @if Chinese + * 远端用户是否静音的回调。 + * @param type 音频流类型。 + * @param uid 远端用户ID。 + * @param mute 是否静音。 + * @endif + */ + void (NERTC_CALL *on_user_audio_mute)(void* self, nertc_audio_stream_type type, nertc_uid_t uid, bool mute); + /** + * @if English + * Occurs when a remote user enables video. + * @param uid The ID of a remote user. + * @param max_profile The resolution of video encoding measures the encoding quality. + * @since V4.5.0 + * @endif + * @if Chinese + * 远端用户开启视频的回调。 + * @param type 远端用户流类型。 + * @param uid 远端用户ID。 + * @param max_profile 视频编码的分辨率，用于衡量编码质量。 + * @endif + */ + void (NERTC_CALL *on_user_video_start)(void* self, nertc_video_stream_type type, nertc_uid_t uid, nertc_video_profile_type max_profile); + /** + * @if English + * Occurs when a remote user disables video. + * @param uid The ID of a remote user. + * @since V4.5.0 + * @endif + * @if Chinese + * 远端用户停用视频的回调。 + * @param type 远端用户流类型。 + * @param uid 远端用户ID。 + * @endif + */ + void (NERTC_CALL *on_user_video_stop)(void* self, nertc_video_stream_type type, nertc_uid_t uid); + /** + * @if English + * Occurs when a remote user stops or resumes sending video streams. + * @param uid The ID of a remote user. + * @param mute Whether to disable video streams. + * @since V4.5.0 + * @endif + * @if Chinese + * 远端用户暂停或恢复发送视频流的回调。 + * @param type 视频流类型。 + * @param uid 远端用户ID。 + * @param mute 是否禁视频流。 + * @endif + */ + void (NERTC_CALL *on_user_video_mute)(void* self, nertc_video_stream_type type, nertc_uid_t uid, bool mute); + /** + * @if English + * Occurs when screen sharing is paused/resumed/started/ended. + *
The method applies to Windows only. + * @since V4.5.0 + * @since V4.5.0 + * @endif + * @if Chinese + * 屏幕共享状态变化回调。 + *
该方法仅适用于 Windows 平台。 + * @since V4.5.0 + * @endif + */ + void (NERTC_CALL *on_screen_capture_state_changed)(void* self, nertc_screen_capture_status status); + /** + * @if English + * Occurs when video configurations of remote users are updated. + * @param uid The ID of a remote user. + * @param max_profile The resolution of video encoding measures the encoding quality. + * @endif + * @if Chinese + * @param uid 远端用户 ID。 + * @param max_profile 视频编码的分辨率，用于衡量编码质量。 + * @endif + */ + void (NERTC_CALL *on_user_video_profile_update)(void* self, nertc_uid_t uid, nertc_video_profile_type max_profile); + /** + * @if English + * Occurs when the first audio frame from a remote user is received. + * @param uid The ID of a remote user whose audio streams are sent. + * @since V4.5.0 + * @endif + * @if Chinese + * 已接收到远端音频首帧的回调。 + * @param type 音频流类型。 + * @param uid 远端用户 ID，指定是哪个用户的音频流。 + * @endif + */ + void (NERTC_CALL *on_first_audio_data_received)(void* self, nertc_audio_stream_type type, nertc_uid_t uid); + /** + * @if English + * Occurs when the first video frame from a remote user is displayed. + *
If the first video frame from a remote user is displayed in the view, the callback is triggered. + * @param uid The ID of a user whose audio streams are sent. + * @since V4.5.0 + * @endif + * @if Chinese + * 已显示首帧远端视频的回调。 + * 第一帧远端视频显示在视图上时，触发此调用。 + * @param type 视频流类型。 + * @param uid 用户 ID，指定是哪个用户的视频流。 + * @endif + */ + void (NERTC_CALL *on_first_video_data_received)(void* self, nertc_video_stream_type type, nertc_uid_t uid); + /** + * @if English + * Occurs when the first audio frame from a remote user is decoded. + * @param uid The ID of a remote user whose audio streams are sent. + * @since V4.5.0 + * @endif + * @if Chinese + * 已解码远端音频首帧的回调。 + * @param type 音频流类型。 + * @param uid 远端用户 ID，指定是哪个用户的音频流。 + * @endif + */ + void (NERTC_CALL *on_first_audio_frame_decoded)(void* self, nertc_audio_stream_type type, nertc_uid_t uid); + /** + * @if English + * Occurs when the remote video is received and decoded. + *
If the engine receives the first frame of remote video streams, the callback is triggered. + * @param uid The ID of a user whose audio streams are sent. + * @param width The width of video streams (px). + * @param height The height of video streams(px). + * @since V4.5.0 + * @endif + * @if Chinese + * 已接收到远端视频并完成解码的回调。 + *
引擎收到第一帧远端视频流并解码成功时，触发此调用。 + * @param type 视频流类型。 + * @param uid 用户 ID，指定是哪个用户的视频流。 + * @param width 视频流宽（px）。 + * @param height 视频流高（px）。 + * @endif + */ + void (NERTC_CALL *on_first_video_frame_decoded)(void* self, nertc_video_stream_type type, nertc_uid_t uid, uint32_t width, uint32_t height); + /** + * @if English + * Occurs when the system prompts current local audio volume. + * - This callback is disabled by default. You can enable the callback by calling the \ref + * IRtcEngineEx::enableAudioVolumeIndication "enableAudioVolumeIndication" method. + * - After the callback is enabled, if a local user speaks, the SDK triggers the callback based on the time interval specified + * in the \ref IRtcEngineEx::enableAudioVolumeIndication "enableAudioVolumeIndication" method. + * - If a local user sets a mute by calling \ref IRtcEngineEx::muteLocalAudioStream "muteLocalAudioStream", the SDK sets the + * value of volume as 0, and calls back to the application layer. + * @param volume The volume of audio mixing. Value range: 0 to 100. + * @since V4.5.0 + * @endif + * @if Chinese + * 提示房间内本地用户瞬时音量的回调。 + * - 该回调默认禁用。可以通过 \ref IRtcEngineEx::enableAudioVolumeIndication "enableAudioVolumeIndication" 方法开启。 + * - 开启后，本地用户说话，SDK 会按 \ref IRtcEngineEx::enableAudioVolumeIndication "enableAudioVolumeIndication" + * 方法中设置的时间间隔触发该回调。 + * - 如果本地用户将自己静音（调用了 \ref IRtcEngineEx::muteLocalAudioStream "muteLocalAudioStream"），SDK 将音量设置为 0 + * 后回调给应用层。 + * @param volume （混音后的）音量，取值范围为 [0,100]。 + * @param enable_vad 是否检测到人声。 + * @endif + */ + void (NERTC_CALL *on_local_audio_volume_indication)(void* self, int volume, bool enable_vad); + /** + * @if English + * Occurs when the system prompts the active speaker and the audio volume. + *
By default, the callback is disabled. You can enable the callback by calling the enableAudioVolumeIndication method. + * After the callback is enabled, if a local user speaks, the SDK triggers the callback based on the time interval specified + * in the enableAudioVolumeIndication method.
In the array of speakers returned: + * - If a uid is contained in the array returned in the last response but not in the array returned in the current response. + * The remote user with the uid does not speak by default. + * - If the volume is 0, the user does not speak. + * - If the array is empty, the remote user does not speak. + * @param speakers The array that contains the information about user IDs and volumes is NERtcAudioVolumeInfo. + * @param speaker_number The size of speakers array, which indicates the number of speakers. + * @param total_volume The total volume (after audio mixing). Value range: 0 to 100. + * @since V4.5.0 + * @endif + * @if Chinese + * 提示房间内谁正在说话及说话者瞬时音量的回调。 + *
该回调默认为关闭状态。可以通过 enableAudioVolumeIndication 方法开启。开启后，无论房间内是否有人说话，SDK 都会按 + * enableAudioVolumeIndication 方法中设置的时间间隔触发该回调。
在返回的 speakers 数组中: + * - 如果有 uid 出现在上次返回的数组中，但不在本次返回的数组中，则默认该 uid 对应的远端用户没有说话。 + * - 如果volume 为 0，表示该用户没有说话。 + * - 如果speakers 数组为空，则表示此时远端没有人说话。 + * @param speakers 每个说话者的用户 ID 和音量信息的数组: NERtcAudioVolumeInfo + * @param speaker_number speakers 数组的大小，即说话者的人数。 + * @param total_volume （混音后的）总音量，取值范围为 [0,100]。 + * @endif + */ + void (NERTC_CALL *on_remote_audio_volume_indication)(void* self,const struct nertc_audio_volume_info* speakers,uint32_t speaker_number,int total_volume); + /** + * @if English + * Notifies to add the result of live stream. + *
The callback asynchronously returns the callback result of \ref IRtcEngineEx::addLiveStreamTask "addLiveStreamTask". + * For information about actual pushing state, see \ref IRtcEngineEventHandlerEx::onLiveStreamState "onLiveStreamState". + * @param task_id The ID of a stream-push task. + * @param url Task ID. + * @param error_code The result. + * - 0: Success. + * - Other values: Failure. + * @since V4.5.0 + * @endif + * @if Chinese + * 通知添加直播任务结果。 + *
该回调异步返回 \ref IRtcEngineEx::addLiveStreamTask "addLiveStreamTask" 接口的调用结果；实际推流状态参考 \ref + * IRtcEngineEventHandlerEx::onLiveStreamState "onLiveStreamState" + * @param task_id 任务id + * @param url 推流地址 + * @param error_code 结果 + * - 0: 调用成功； + * - 其他: 调用失败。 + * @endif + */ + void (NERTC_CALL *on_add_live_stream_task)(void* self, const char* task_id, const char* url, int error_code); + /** + * @if English + * Notifies to Updates the result of live stream. + *
The callback asynchronously returns the callback result of ref IRtcEngineEx::addLiveStreamTask "addLiveStreamTask". For + * information about actual pushing state, see \ref IRtcEngineEventHandlerEx::onLiveStreamState "onLiveStreamState". + * @param task_id The ID of a stream-push task. + * @param url The URL for the streaming task. + * @param error_code The result. + * - 0: Success. + * - Other values: Failure. + * @since V4.5.0 + * @endif + * @if Chinese + * 通知更新直播任务结果。 + * 该回调异步返回 \ref IRtcEngineEx::updateLiveStreamTask "updateLiveStreamTask" 接口的调用结果；实际推流状态参考 \ref + * IRtcEngineEventHandlerEx::onLiveStreamState "onLiveStreamState" + * @param task_id 任务id + * @param url 推流地址 + * @param error_code 结果 + * - 0: 调用成功； + * - 其他: 调用失败。 + * @endif + */ + void (NERTC_CALL *on_update_live_stream_task)(void* self, const char* task_id, const char* url, int error_code); + /** + * @if English + * Notifies to delete the result of live stream. + *
The callback asynchronously returns the callback result of ref IRtcEngineEx::addLiveStreamTask "addLiveStreamTask". For + * information about actual pushing state, see \ref IRtcEngineEventHandlerEx::onLiveStreamState "onLiveStreamState". + * @param task_id The ID of a task. + * @param error_code The result. + * - 0: Success. + * - Other values: Failure. + * @since V4.5.0 + * @endif + * @if Chinese + * 通知删除直播任务结果。 + *
该回调异步返回 \ref IRtcEngineEx::removeLiveStreamTask "removeLiveStreamTask" 接口的调用结果；实际推流状态参考 \ref + * IRtcEngineEventHandlerEx::onLiveStreamState "onLiveStreamState" + * @param task_id 任务id + * @param error_code 结果 + * - 0: 调用成功； + * - 其他: 调用失败。 + * @endif + */ + void (NERTC_CALL *on_remove_live_stream_task)(void* self, const char* task_id, int error_code); + /** + * @if English + * Notifies the status in live stream-pushing. + * @note The callback is valid in a call. + * @param task_id The ID of a task. + * @param url The URL for the streaming task. + * @param state #NERtcLiveStreamStateCode The state of live stream-pushing. + * - 505: Pushing. + * - 506: Pushing fails. + * - 511: Pushing ends. + * @since V4.5.0 + * @endif + * @if Chinese + * 通知直播推流状态 + * @note 该回调在通话中有效。 + * @param task_id 任务id + * @param url 推流地址 + * @param state #NERtcLiveStreamStateCode, 直播推流状态 + * - 505: 推流中； + * - 506: 推流失败； + * - 511: 推流结束； + * @endif + */ + void (NERTC_CALL *on_live_stream_state_changed)(void* self, const char* task_id, const char* url, nertc_live_stream_state_code state); + /** + * @if English + * Occurs when the content of remote SEI is received. + *
After a remote client successfully sends SEI, the local client receives a message returned by the callback. + * @param[in] uid The ID of the user who sends the SEI. + * @param[in] data The received SEI data. + * @param[in] dataSize The size of received SEI data. + * @since V4.5.0 + * @endif + * @if Chinese + * 收到远端流的 SEI 内容回调。 + *
当远端成功发送 SEI 后，本端会收到此回调。 + * @param[in] uid 发送该 sei 的用户 id + * @param[in] data 接收到的 sei 数据 + * @param[in] dataSize 接收到 sei 数据的大小 + * @endif + */ + void (NERTC_CALL *on_receive_sei_message)(void* self, nertc_uid_t uid, const uint8_t* data, uint32_t dataSize); + /** + * @if English + * Occurs when the state of the media stream is relayed. + * @since V4.5.0 + * @param state The state of the media stream. + * @param channel_name The name of the destination room where the media streams are relayed. + * @endif + * @if Chinese + * 跨房间媒体流转发状态发生改变回调。 + * @since V4.5.0 + * @param state 当前跨房间媒体流转发状态。详细信息请参考 #NERtcChannelMediaRelayState + * @param channel_name 媒体流转发的目标房间名。 + * @endif + */ + void (NERTC_CALL *on_media_relay_state_changed)(void* self, nertc_channel_media_relay_state state, const char* channel_name); + /** + * @if English + * Occurs when events related to media stream relay are triggered. + * @since V4.5.0 + * @param event The media stream relay event. + * @param channel_name The name of the destination room where the media streams are relayed. + * @param error Specific error codes. + * @endif + * @if Chinese + * 媒体流相关转发事件回调。 + * @since V4.5.0 + * @param event 当前媒体流转发事件。详细信息请参考 #NERtcChannelMediaRelayEvent 。 + * @param channel_name 转发的目标房间名。 + * @param error 相关错误码。详细信息请参考 #NERtcErrorCode 。 + * @endif + */ + void (NERTC_CALL *on_media_relay_event)(void* self,nertc_channel_media_relay_event event,const char* channel_name,nertc_error_code error); + /** + * @if English + * Occurs when the published local media stream falls back to an audio-only stream due to poor network conditions or switches + * back to audio and video stream after the network conditions improve.
If you call setLocalPublishFallbackOption and set + * option to #kNERtcStreamFallbackAudioOnly, this callback is triggered when the locally published stream falls back to + * audio-only mode due to poor uplink network conditions, or when the audio stream switches back to the audio and video stream + * after the uplink network conditions improve. + * @since V4.5.0 + * @param is_fallback The locally published stream falls back to audio-only mode or switches back to audio and video stream. + * - true: The published stream from a local client falls back to audio-only mode due to poor uplink network conditions. + * - false: The audio stream switches back to the audio and video stream after the upstream network condition improves. + * @param type The type of the video stream, such as mainstream and substream. + * @since V4.5.0 + * @endif + * @if Chinese + * 本地发布流已回退为音频流、或已恢复为音视频流回调。 + *
如果您调用了设置本地推流回退选项 setLocalPublishFallbackOption 接口，并将 option 设置为 #kNERtcStreamFallbackAudioOnly + * 后，当上行网络环境不理想、本地发布的媒体流回退为音频流时，或当上行网络改善、媒体流恢复为音视频流时，会触发该回调。 + * @since V4.5.0 + * @param is_fallback 本地发布流已回退或已恢复。 + * - true： 由于网络环境不理想，发布的媒体流已回退为音频流。 + * - false：由于网络环境改善，从音频流恢复为音视频流。 + * @param type 对应的视频流类型，即主流或辅流。 + * @endif + */ + void (NERTC_CALL *on_publish_fallback_to_audio_only)(void* self, bool is_fallback, nertc_video_stream_type stream_type); + /** + * @if English + * Occurs when the subscribed remote media stream falls back to an audio-only stream due to poor network conditions or + * switches back to the audio and video stream after the network condition improves.
If you call + * setLocalPublishFallbackOption and set option to #kNERtcStreamFallbackAudioOnly, this callback is triggered when the locally + * published stream falls back to audio-only mode due to poor uplink network conditions, or when the audio stream switches + * back to the audio and video stream after the uplink network condition improves. + * @since V4.5.0 + * @param uid The ID of a remote user. + * @param is_fallback The subscribed remote media stream falls back to audio-only mode or switches back to the audio and + * video stream. + * - true: The subscribed remote media stream falls back to audio-only mode due to poor downstream network conditions. + * - false: The subscribed remote media stream switches back to the audio and video stream after the downstream network + * condition improves. + * @param stream_type The type of the video stream, such as mainstream and substream. + * @since V4.5.0 + * @endif + * @if Chinese + * 订阅的远端流已回退为音频流、或已恢复为音视频流回调。 + *
如果你调用了设置远端订阅流回退选项 setRemoteSubscribeFallbackOption 接口并将 option 设置 #kNERtcStreamFallbackAudioOnly + * 后，当下行网络环境不理想、仅接收远端音频流时，或当下行网络改善、恢复订阅音视频流时，会触发该回调。 + * @since V4.5.0 + * @param uid 远端用户的 ID。 + * @param is_fallback 远端订阅流已回退或恢复： + * - true： 由于网络环境不理想，订阅的远端流已回退为音频流。 + * - false：由于网络环境改善，订阅的远端流从音频流恢复为音视频流。 + * @param stream_type 对应的视频流类型，即主流或辅流。 + * @endif + */ + void (NERTC_CALL *on_subscribe_fallback_to_audio_only)(void* self,nertc_uid_t uid,bool is_fallback,nertc_video_stream_type stream_type); + /** + * @if English + * Audio/Video Callback when banned by server. + * @since v4.6.0 + * @param isAudioBannedByServer indicates whether to ban the audio. + * - true: banned + * - false unbanned + * @param isVideoBannedByServer indicates whether to ban the video. + * - true: banned + * - false unbanned + * @endif + * @if Chinese + * 服务端禁言音视频权限变化回调。 + * @since v4.6.0 + * @param is_audio_banned 是否禁用音频。 + * - true：禁用音频。 + * - false：取消禁用音频。 + * @param is_video_banned 是否禁用视频。 + * - true：禁用视频。 + * - false：取消禁用视频。 + * @endif + */ + void (NERTC_CALL *on_media_right_changed)(void* self, bool is_audio_banned, bool is_video_banned); + /** + * @if Chinese + * 权限密钥即将过期事件回调。 + * - 由于 PermissionKey 具有一定的时效，在通话过程中如果 PermissionKey 即将失效，SDK 会提前 30 秒触发该回调，提醒用户更新 + * PermissionKey。 + * @since V4.6.29 + * @par 使用前提 + * 请在 IRtcChannelEventHandler 接口类中通过 \ref IRtcChannel::setChannelEventHandler "setChannelEventHandler" + * 接口设置回调监听。 + * @par 相关接口 + * 在收到此回调后可以调用 \ref nertc::IRtcEngineEx::updatePermissionKey "updatePermissionKey" 方法更新权限密钥。 + * @endif + */ + void (NERTC_CALL *on_permission_key_will_expire)(void* self); + /** + * @if Chinese + * 更新权限密钥事件回调。 + * - 调用 \ref IRtcChannel::updatePermissionKey "updatePermissionKey" 方法主动更新权限密钥后，SDK + * 会触发该回调，返回权限密钥更新的结果。 + * @since V4.6.29 + * @par 使用前提 + * 请在 IRtcChannelEventHandler 接口类中通过 \ref IRtcChannel::setChannelEventHandler "setChannelEventHandler" + * 接口设置回调监听。 + * @par 参数说明 + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
**参数名称****类型****描述**
keyconst char*新的权限密钥。
error_code \ref nertc::NERtcErrorCode "NERtcErrorCode" 错误码。
  • kNERtcErrChannelPermissionKeyError：权限密钥错误。
  • kNERtcErrChannelPermissionKeyTimeout：权限密钥超时。
timeoutint更新后的权限密钥剩余有效时间。单位为秒。
+ * @endif + */ + void (NERTC_CALL *on_update_permission_key)(void* self, const char* key, nertc_error_code error_code, int timeout); +}; + +NERTC_END_DECLS +#endif diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_device_collection.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_device_collection.h new file mode 100644 index 0000000..0e1b6b5 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_device_collection.h @@ -0,0 +1,85 @@ +#ifndef NERTC_DEVICE_COLLECTION_H +#define NERTC_DEVICE_COLLECTION_H + +#include "nertc_engine_defines.h" + +NERTC_BEGIN_DECLS +/** + * @if English + * Gets the number of devices. + * @note You must call \ref IAudioDeviceManager::enumeratePlayoutDevices "enumeratePlayoutDevices" or \ref + * IAudioDeviceManager::enumerateRecordDevices "enumerateRecordDevices" before calling the method to get the number of playing + * and capturing devices. + * @return The number of capturing and playback devices. + * + * @endif + * @if Chinese + * 获取设备数量。 + * @note 调用此方法之前，必须调用 \ref IAudioDeviceManager::enumeratePlayoutDevices "enumeratePlayoutDevices" 或 \ref + * IAudioDeviceManager::enumerateRecordDevices "enumerateRecordDevices" 方法获取播放或采集设备数量。 + * @return 采集或播放设备数量。 + * @endif + */ +NERTC_API uint16_t NERTC_CALL nertc_device_collection_get_count(struct nertc_device_collection* self); + +/** + * @if English + * Gets the device information of the specified index. + * @param index specifies the device information that you want to check. The value must be lower than the value returned by + * \ref IDeviceCollection::getCount "getCount". + * @param device_name Device name. + * @param device_id Device ID. + * @return + * - 0: Success. + * - Other values: Failure. + * + * @endif + * @if Chinese + * 获取指定 index 的设备信息。 + * @param index 指定想查询的设备信息。必须小于 \ref IDeviceCollection::getCount "getCount"返回的值。 + * @param device_name 设备名称。 + * @param device_id 设备 ID。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_device_collection_get_device(struct nertc_device_collection* self,uint16_t index,char* device_name,char* device_id); + +/** + * @if English + * Searches specified information about index-related devices. + * @note The link method of returnable devices and the non-useful status determined by the SDK. + * @param index specifies the device information that you want to check. + * @param device_info For information about device information, see \ref NERtcDeviceInfo "NERtcDeviceInfo". + * @return + * - 0: Success. + * - Other values: Failure. + * + * @endif + * @if Chinese + * 检索有关索引设备的指定信息。 + * @note 可返回设备的链接方式，和SDK判定的疑似不可用状态。 + * @param index 指定想查询的设备信息。 + * @param device_info 设备信息，详细信息请参考 \ref NERtcDeviceInfo "NERtcDeviceInfo"。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_device_collection_get_device_info(struct nertc_device_collection* self,uint16_t index,struct nertc_device_info* device_info); + +/** + * @if English + * Releases all IDeviceCollection resources. + * + * @endif + * @if Chinese + * 释放所有 IDeviceCollection 资源。 + * @endif + */ +NERTC_API void NERTC_CALL nertc_device_collection_destroy(struct nertc_device_collection* self); + +NERTC_END_DECLS + +#endif //NERTC_DEVICE_COLLECTION_H diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_engine.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_engine.h new file mode 100644 index 0000000..526f261 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_engine.h @@ -0,0 +1,667 @@ +#ifndef NERTC_ENGINE_H +#define NERTC_ENGINE_H + +#include "nertc_engine_events.h" +#include "nertc_media_stats_observer.h" + +NERTC_BEGIN_DECLS + +/** + * @if English + * RtcEngineContext definition. + * @endif + * @if Chinese + * RtcEngineContext 定义 + * @endif + */ +struct nertc_engine_context{ + /** + * @if English + * Users register the APP key of CommsEase. If you have no APP key in your developer kit, please apply to register a new APP + * key. + * @endif + * @if Chinese + * 用户注册云信的APP Key。如果你的开发包里面缺少 APP Key，请申请注册一个新的 APP Key。 + * @endif + */ + const char* app_key; + /** + * @if English + * The full path of log content are encoded in UTF-8. + * @endif + * @if Chinese + * 日志目录的完整路径，采用 UTF-8 编码。 + * @endif + */ + const char* log_dir_path; + + /** + * @if English + * The log level. The level is kNERtcLogLevelInfo by default. + * @endif + * @if Chinese + * 日志级别，默认级别为 kNERtcLogLevelInfo。 + * @endif + */ + nertc_log_level log_level; + + /** + * @if English + * The size of SDK-input log file. Unit: KB. If the value is set as 0, the size of log file is 20M by default. + * @endif + * @if Chinese + * 指定 SDK 输出日志文件的大小上限，单位为 KB。如果设置为 0，则默认为 20 M。 + * @endif + */ + uint32_t log_file_max_size_kbytes; + + /** + * @if English + * IRtcEngineEventHandler callback interface class is used to send callback event notifications to the app from SDK. + * @endif + * @if Chinese + * 用于 SDK 向 App 发送回调事件通知。 + * @endif + */ + struct nertc_engine_events events; + + /** + * @if English + * The private server address. You need to set the value as empty by default. ** To use a private server, contact technical + * support for details. + * @endif + * @if Chinese + * 私有化服务器地址，默认需要置空。如需启用私有化功能，请联系技术支持获取详情。 + * @endif + */ + struct nertc_server_addresses server_config; +}; + +/** + * @if English + * Creates an RTC engine object and returns the pointer. + * @note Only one nertc_engine object is supported at the same time. You must release an nertc_engine before creating a new + * instance. + * @return The pointer of the RTC engine object. + * @endif + * @if Chinese + * 创建 RTC 引擎对象并返回指针。 + * @note 同时只支持一个nertc_engine对象，新创建前必须先释放前一个nertc_engine。 + * @return RTC 引擎对象的指针。 + * @endif + */ +NERTC_API struct nertc_engine* NERTC_CALL create_nertc_engine(); + +/** + * @if English + * Destroys RTC engine object. + * @note Call \ref nertc_engine_release "release" first before releasing. + * @endif + * @if Chinese + * 销毁 RTC 引擎对象。 + * @note 释放前需要先调用\ref nertc_engine_release "release" + * @endif + */ +NERTC_API void NERTC_CALL destroy_nertc_engine(struct nertc_engine* engine); + + /** + * @if English + * Initializes the NERTC SDK service. + *
After calling the createNERtcEngine to create IRtcEngine object, you must call the method to initialize before calling + * other methods. After successfully initializing, the audio and video call mode is enabled by default. + * @warning + * - Callers must use the same AppKey to make audio or video calls. + * - One IRtcEngine instance object must share the same App Key. If you need to change the AppKey, you must first call \ref + * IRtcEngine::release "release" to destroy the current instance, and then call the method to create a new instance. + * @param[in] context The passed RTC engine context object. NERtcEngineContext. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 初始化 NERTC SDK 服务。 + *
在调用 createNERtcEngine() 方法创建 IRtcEngine + * 对象后，必须先调用该方法进行初始化，才能使用其他方法。初始化成功后，默认处于音视频通话模式。 + * @warning + * - 必须使用同一个 App Key 才能进行通话。 + * - 一个 IRtcEngine 实例对象只能使用一个 App Key。如需更换 App Key，必须先调用 \ref IRtcEngine::release "release" + * 方法销毁当前实例，再调用本方法重新创建实例。 + * @param[in] context 传入的RTC engine context对象: NERtcEngineContext. + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_init(struct nertc_engine* self, const struct nertc_engine_context* param); + +/** + * @if English + * Destroys an NERtc instance to release resources. + *
This method releases all resources used by the NERTC SDK. In some cases, real-time audio and video communication is + * only needed upon your demands. If no RTC calls are required, you can call this method to release resources.
After you + * call the release method, other methods and callbacks supported by the SDK become unavailable. If you want to use RTC calls, + * you must create a new NERtc instance. + * @note If you need to use IRtcEngine instance again that cannot be initialized after release, you need to createNERtcEngine + * after destroyNERtcEngine. + * @param[in] sync The value is true by default, which can only be set to true. The default setting indicates synchronization + * call of the instance. You must return before you release the resources and return the IRtcEngine object resources.
App + * cannot call the interface in the callbacks returned by the SDK. If not, deadlock occurs and the SDK can only retrieve + * related object resources before the callback is returned. The SDK automatically detects the deadlock, and changes the + * deadlock to asynchronous call. However, the asynchronous call consumes extra time. + * @endif + * @if Chinese + * 销毁 NERtc 实例，释放资源。 + *
该方法释放 NERTC SDK 使用的所有资源。有些 App + * 只在用户需要时才进行实时音视频通信，不需要时则将资源释放出来用于其他操作，该方法适用于此类情况。
调用 release + * 方法后，您将无法再使用 SDK 的其它方法和回调。如需再次使用实时音视频通话功能，您必须重新创建一个新的 NERtc 实例。 + * @note 如果需要重新使用IRtcEngine，release 后不能再 initialize，需要 destroyNERtcEngine 后重新 createNERtcEngine。 + * @param[in] sync 默认为 true 且只能设置为 true，表示同步调用，等待 IRtcEngine 对象资源释放后再返回。
App 不应该在 SDK + * 产生的回调中调用该接口，否则由于 SDK 要等待回调返回才能回收相关的对象资源，会造成死锁。SDK + * 会自动检测这种死锁并转为异步调用，但是检测本身会消耗额外的时间。 + * @endif + */ +NERTC_API void NERTC_CALL nertc_engine_release(struct nertc_engine* self, bool sync); + +/** + * @if English + * Sets the role of a user in live streaming. + *
The method sets the role to host or audience. The permissions of a host and a viewer are different. + * - A host has the permissions to open or close a camera, publish streams, call methods related to publishing streams in + * interactive live streaming. The status of the host is visible to the users in the room when the host joins or leaves the + * room. + * - The audience has no permissions to open or close a camera, call methods related to publishing streams in interactive live + * streaming, and is invisible to other users in the room when the user that has the audience role joins or leaves the room. + * @note + * - By default, a user joins a room as a host. + * - Before a user joins a room, the user can call this method to change the client role to audience. Users can switch the + * role of a user through the interface after joining the room. + * - If the user switches the role to audience, the SDK automatically closes the audio and video devices. + * @param[in] role The role of a user. NERtcClientRole. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 在直播场景中设置用户角色。 + *
用户角色支持设置为主播或观众，主播和观众的权限不同。 + * - 主播：可以开关摄像头等设备、可以发布流、可以操作互动直播推流相关接口、上下线对其他房间内用户可见。 + * - 观众：不可以开关摄像头等设备、不可以发布流、不可以操作互动直播推流相关接口、上下线对其他房间内用户不可见。 + * @note + * - 默认情况下用户以主播角色加入房间。 + * - 在加入房间前，用户可以调用本接口切换本端角色为观众。在加入房间后，用户也可以通过本接口切换用户角色。 + * - 用户切换为观众角色时，SDK 会自动关闭音视频设备。 + * @param[in] role 用户角色。 NERtcClientRole + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_client_role(struct nertc_engine* self, nertc_client_role role); + +/** + * @if English + * Sets a room scene. + *
You can set a room scene for a call or live event. Different QoS policies are applied to different scenes. + * @note You must set the profile after joining a call. The setting is invalid after the call ends. + * @param[in] profile Sets the room scene. For more information, see NERtcChannelProfileType. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置房间场景。 + *
房间场景可设置为通话或直播场景，不同的场景中 QoS 策略不同。 + * @note 必须在加入通话前设置，开始通话后设置无效，结束通话后保留之前的设置。 + * @param[in] profile 设置房间场景。详细信息请参考 NERtcChannelProfileType。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_channel_profile(struct nertc_engine* self, nertc_channel_profile_type profile); + +/** + * @if English + * Joins a channel of audio and video call. + *
If the specified room does not exist when you join the room, a room with the specified name is automatically created in +the server provided by CommsEase. + * - After you join a room by calling the relevant method supported by the SDK, users in the same room can make audio or video +calls. Users that join the same room can start a group chat. Apps that use different AppKeys cannot communicate with each +other. + * - After the method is called successfully, the onJoinChannel callback is locally triggered, and the onUserJoined callback +is remotely triggered. + * - If you join a room, you subscribe to the audio streams from other users in the same room by default. In this case, the +data usage is billed. To unsubscribe, you can call the setParameters method. + * - In live streaming, audiences can switch channels by calling switchChannel. + * @note The ID of each user must be unique. + * @param[in] token The certification signature used in authentication (NERTC Token). Valid values: + - Null. You can set the value to null in the debugging mode. This poses a security risk. We recommend that +you contact your business manager to change to the default safe mode before your product is officially launched. + - NERTC Token acquired. In safe mode, the acquired token must be specified. If the specified token is +invalid, users are unable to join a room. We recommend that you use the safe mode. + * @param[in] channel_name The name of the room. Users that use the same name can join the same room. The name must be of +STRING type and must be 1 to 64 characters in length. The following 89 characters are supported: a-z, A-Z, 0-9, space, +!#$%&()+-:;≤.,>? @[]^_{|}~”. + * @param[in] uid The unique identifier of a user. The uid of each user in a room must be unique. +
uid is optional. The default value is 0. If the uid is not specified (set to 0), the SDK automatically +assigns a random uid and returns the uid in the callback of onJoinChannel. The application layer must keep and maintain the +return value. The SDK does not maintain the return value. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 加入音视频房间。 + *
加入音视频房间时，如果指定房间尚未创建，云信服务器内部会自动创建一个同名房间。 + * - SDK 加入房间后，同一个房间内的用户可以互相通话，多个用户加入同一个房间，可以群聊。使用不同 App Key 的 App 之间不能互通。 + * - 成功调用该方加入房间后，本地会触发onJoinChannel回调，远端会触发onUserJoined回调。 + * - +用户成功加入房间后，默认订阅房间内所有其他用户的音频流，可能会因此产生用量并影响计费。如果想取消自动订阅，可以在通话前通过调用setParameters方法实现。 + * - 直播场景中的观众角色可以通过 switchChannel 快速切换房间。 + * @note 房间内每个用户的用户 ID 必须是唯一的。 + * @param[in] token 安全认证签名（NERTC Token）。可设置为： + - null。调试模式下可设置为 +null。安全性不高，建议在产品正式上线前在云信控制台中将鉴权方式恢复为默认的安全模式。 + - 已获取的NERTC Token。安全模式下必须设置为获取到的 Token 。若未传入正确的 Token +将无法进入房间。推荐使用安全模式。 + * @param[in] channel_name 房间名称，设置相同房间名称的用户会进入同一个通话房间。字符串格式，长度为1~ 64 +字节。支持以下89个字符：a-z, A-Z, 0-9, space, !#$%&()+-:;≤.,>? @[]^_{|}~” + * @param[in] uid 用户的唯一标识 id，房间内每个用户的 uid 必须是唯一的。 +
uid 可选，默认为 0。如果不指定（即设为 0），SDK 会自动分配一个随机 uid，并在 onJoinChannel +回调方法中返回，App 层必须记住该返回值并维护，SDK 不对该返回值进行维护。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 +* @endif +*/ +NERTC_API int NERTC_CALL nertc_engine_join_channel(struct nertc_engine* self, + const char* token, + const char* channel_name, + nertc_uid_t uid, + struct nertc_join_channel_options* channel_options); + +/** + * @if English + * Switches to a room of audio and video call. + *
In live streaming, the audience can call this method to switch from the current room to another room. + *
After you switch to another room by calling the method, the local first receive the onLeaveChannel callback that the + user leaves the room, and then receives the + *
onJoinChanne callback that the user joins the new room. Remote clients receive the return from onUserLeave and + onUserJoined. + * @note + * - The method applies to only the live streaming. The role is the audience in the RTC room. The room scene is set to live + streaming by calling the setchannelprofile method, and the role of room members is set to audience by calling the + setClientRole method. + * - By default, after a room member switches to another room, the room member subscribes to audio streams from other members + of the new room. In this case, data usage is charged and billing is updated. If you want to unsubscribe to the previous audio + stream, you can call the subscribeRemoteAudio method with a value of false passed in. + * @param[in] token The certification signature used in authentication (NERTC Token). Valid values: + - Null. You can set the value to null in the debugging mode. We recommend you change to the default safe + mode before your product is officially launched. + - NERTC Token acquired. In safe mode, the acquired token must be specified. If the specified token is + invalid, users are unable to join a channel. We recommend that you use the safe mode. + * @param[in] channel_name The room name that a user wants to switch to. + + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 快速切换音视频房间。 + *
房间场景为直播场景时，房间中角色为观众的成员可以调用该方法从当前房间快速切换至另一个房间。 + *
成功调用该方切换房间后，本端会先收到离开房间的回调 onLeaveChannel，再收到成功加入新房间的回调 + onJoinChannel。远端用户会收到 onUserLeave 和 onUserJoined 的回调。 + * @note + * - 该方法仅适用于直播场景中，角色为观众的音视频房间成员。即已通过接口 setchannelprofile 设置房间场景为直播，通过 + setClientRole 设置房间成员的角色为观众。 + * - 房间成员成功切换房间后，默认订阅房间内所有其他成员的音频流，因此产生用量并影响计费。如果想取消订阅，可以通过调用相应的 + subscribeRemoteAudio 方法传入 false 实现。 + * @param[in] token 安全认证签名（NERTC Token）。可设置为： + - null。调试模式下可设置为 null。建议在产品正式上线前在云信控制台中将鉴权方式恢复为默认的安全模式。 + - 已获取的NERTC Token。安全模式下必须设置为获取到的 Token 。若未传入正确的 Token + 将无法进入房间。推荐使用安全模式。 + * @param[in] channel_name 期望切换到的目标房间名称。 + + * @return + * -0: 方法调用成功 + * -其他：方法调用失败 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_switch_channel(struct nertc_engine* self, + const char* token, + const char* channel_name, + struct nertc_join_channel_options* channel_options); +/** + * @if English + * Switches to a room of audio and video call. + *
In live streaming, the audience can call this method to switch from the current room to another room. + *
After you switch to another room by calling the method, the local first receive the onLeaveChannel callback that the + user leaves the room, and then receives the + *
onJoinChanne callback that the user joins the new room. Remote clients receive the return from onUserLeave and + onUserJoined. + * @note + * - Call this method to leave from the current room, and then join another room. + * - By default, after a room member switches to another room, the room member subscribes to audio streams from other members + of the new room. In this case, data usage is charged and billing is updated. If you want to unsubscribe to the previous audio + stream, you can call the subscribeRemoteAudio method with a value of false passed in. + * @param[in] token The certification signature used in authentication (NERTC Token). Valid values: + - Null. You can set the value to null in the debugging mode. We recommend you change to the default safe + mode before your product is officially launched. + - NERTC Token acquired. In safe mode, the acquired token must be specified. If the specified token is + invalid, users are unable to join a channel. We recommend that you use the safe mode. + * @param[in] channel_name The room name that a user wants to switch to. + * @param[in] uid The ID of user. + + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 快速切换音视频房间。 + *
调用该方法从当前房间leave，然后加入至另一个房间。 + *
成功调用该方切换房间后，本端会先收到离开房间的回调 onLeaveChannel，再收到成功加入新房间的回调 + onJoinChannel。远端用户会收到 onUserLeave 和 onUserJoined 的回调。 + * - 房间成员成功切换房间后，默认订阅房间内所有其他成员的音频流，因此产生用量并影响计费。如果想取消订阅，可以通过调用相应的 + subscribeRemoteAudio 方法传入 false 实现。 + * @param[in] token 安全认证签名（NERTC Token）。可设置为： + - null。调试模式下可设置为 null。建议在产品正式上线前在云信控制台中将鉴权方式恢复为默认的安全模式。 + - 已获取的NERTC Token。安全模式下必须设置为获取到的 Token 。若未传入正确的 Token + 将无法进入房间。推荐使用安全模式。 + * @param[in] channel_name 期望切换到的目标房间名称。 + * @param[in] uid 用户ID。 + + * @return + * -0: 方法调用成功 + * -其他：方法调用失败 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_switch_channel_ex(struct nertc_engine* self, + const char* token, + const char* channel_name, + nertc_uid_t uid, + struct nertc_join_channel_options_ex* channel_options_ex); + +/** + * @if English + * Leaves the room. + *
Leaves a room for hang up or calls ended. + *
A user can call the leaveChannel method to end the call before the user makes another call. + *
After the method is called successfully, the onLeaveChannel callback is locally triggered, and the onUserLeave callback + * is remotely triggered. + * @note + * - The method is asynchronous call. Users cannot exit the room when the method is called and returned. After users exit the + * room, the SDK triggers the onLeaveChannel callback. + * - If you call leaveChannel method and instantly call release method, the SDK cannot trigger onLeaveChannel callback. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 离开房间。 + *
离开房间，即挂断或退出通话。 + *
结束通话时，必须调用leaveChannel结束通话，否则无法开始下一次通话。 + *
成功调用该方法离开房间后，本地会触发onLeaveChannel回调，远端会触发onUserLeave回调。 + * @note + * - 该方法是异步操作，调用返回时并没有真正退出房间。在真正退出房间后，SDK 会触发onLeaveChannel回调。 + * - 如果您调用了leaveChannel后立即调用release，SDK 将无法触发onLeaveChannel回调。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_leave_channel(struct nertc_engine* self); + +/** + * @if English + * Gets the pointer of device administrators object. + * @param[in] iid The iid of interface preferred. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 获取设备管理员对象的指针。 + * @param[in] iid 想要获取的接口的iid. + * @param[in] inter 指向 DeviceManager 对象的指针。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API void* NERTC_CALL nertc_engine_query_interface(struct nertc_engine* self,nertc_interface_id_type iid); + +/** + * @if English + * Enables or disables local audio capture. + *
The method can enable the local audio again to start local audio capture and processing. + *
The method does not affect receiving or playing remote audio and audio streams. + * @note The method is different from \ref IRtcEngineEx::muteLocalAudioStream "muteLocalAudioStream" in:. + * - \ref IRtcEngine::enableLocalAudio "enableLocalAudio": Enables local audio capture and processing. + * - \ref IRtcEngineEx::muteLocalAudioStream "muteLocalAudioStream": Stops or continues publishing local audio streams. + * @note The method enables the internal engine, which is still valid after you call \ref IRtcEngine::leaveChannel + * "leaveChannel". + * @param[in] enabled + * - true: Enables local audio feature again. You can enable local audio capture or processing by default. + * - false: Disables local audio feature again. You can stop local audio capture or processing. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 开启/关闭本地音频采集 + *
该方法可以重新开启本地语音功能，重新开始本地音频采集及处理。 + *
该方法不影响接收或播放远端音频流。 + * @note 该方法与 \ref IRtcEngineEx::muteLocalAudioStream "muteLocalAudioStream" 的区别在于: + * - \ref IRtcEngine::enableLocalAudio "enableLocalAudio": 开启本地语音采集及处理 + * - \ref IRtcEngineEx::muteLocalAudioStream "muteLocalAudioStream": 停止或继续发送本地音频流 + * @note 该方法设置内部引擎为启用状态，在 \ref IRtcEngine::leaveChannel "leaveChannel" 后仍然有效。 + * @param[in] type 音频流类型: + * @param[in] enabled + * - true: 重新开启本地语音功能，即开启本地语音采集或处理（默认） + * - false: 关闭本地语音功能，即停止本地语音采集或处理 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_enable_local_audio(struct nertc_engine* self, nertc_audio_stream_type stream_type, bool enabled); + +/** + * @if English + * Sets local views. + *
This method is used to set the display information about the local video. The method is applicable for only local + * users. Remote users are not affected.
Apps can call this API operation to associate with the view that plays local + * video streams. During application development, in most cases, before joining a room, you must first call this method to set + * the local video view after the SDK is initialized. + * @note If you use external rendering on the Mac platform, you must set the rendering before the SDK is initialized. + * @param[in] canvas The video canvas information. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置本地视图。 + *
该方法设置本地视频显示信息。只影响本地用户看到的视频画面，不影响远端。 + *
App 通过调用此接口绑定本地视频流的显示视窗(view)。 在 App + * 开发中，通常在初始化后调用该方法进行本地视频设置，然后再加入房间。 + * @note mac端若使用外部渲染，必须在 SDK 初始化时设置。 + * @param[in] canvas 视频画布信息 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_setup_local_video_canvas(struct nertc_engine* self, + nertc_video_stream_type type, + struct nertc_video_canvas* canvas); + +/** + * @if English + * Sets views for remote users. + *
This method is used to associate remote users with display views and configure the rendering mode and mirror mode for + * remote views that are displayed locally. The method affects only video display viewed by local users. + * @note + * - You need to specify the uid of remote video when the interface is called. In general cases, the uid can be set before + * users join the room. + * - If the user ID is not retrieved, the App calls this method after the onUserJoined event is triggered. To disassociate a + * specified user from a view, you can leave the canvas parameter empty. + * - After a user leaves the room, the association between a remote user and the view is cleared. + * @param[in] uid The ID of a remote user. + * @param[in] canvas The video canvas information. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置远端用户视图。 + *
该方法绑定远端用户和显示视图，并设置远端用户视图在本地显示时的渲染模式和镜像模式，只影响本地用户看到的视频画面。 + * @note + * - 调用该接口时需要指定远端视频的 uid，一般可以在用户加入后设置好。 + * - 如果 App 无法事先知道对方的用户 ID，可以在 APP 收到 onUserJoined 事件时设置。- 解除某个用户的绑定视图可以把 canvas + * 设置为空。 + * - 退出房间后，SDK 会清除远程用户和视图的绑定关系。 + * @param[in] uid 远端用户 ID。 + * @param[in] canvas 视频画布信息 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_setup_remote_video_canvas(struct nertc_engine* self, + nertc_uid_t uid, + nertc_video_stream_type type, + struct nertc_video_canvas* canvas); + +/** + * @if English + * Enables or disables local audio capture and rendering. + *
The method enables local video capture. + * @note + * - You can call this method before or after you join a room. + * - The method enables the internal engine, which is still valid after you call \ref IRtcEngine::leaveChannel "leaveChannel". + * - After local video capture is successfully enabled or disabled, the onUserVideoStop or onUserVideoStart callback is + * remotely triggered. + * @param[in] enabled Whether to enable local video capture and rendering. + * - true: Enables the local video capture and rendering. + * - false: Disables the local camera device. After local video capture is disabled, remote users cannot receive video streams + * from local users. However, local users can still receive video streams from remote users. If the setting is false, the + * local camera is not required to call the method. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 开启或关闭本地视频采集和渲染。 + *
该方法启用本地视频采集功能。 + * @note + * - 该方法在加入房间前和加入房间后均可调用。 + * - 该方法设置内部引擎为启用状态，在 \ref IRtcEngine::leaveChannel "leaveChannel" 后仍然有效。 + * - 成功启用或禁用本地视频采集和渲染后，远端会触发 onUserVideoStop 或 onUserVideoStart 回调。 + * @param[in] enabled 是否启用本地视频采集和渲染: + * - true: 开启本地视频采集和渲染 (默认)； + * - false: 关闭使用本地摄像头设备。关闭后，远端用户会接收不到本地用户的视频流；但本地用户依然可以接收远端用户的视频流。设置为 + * false 时，该方法不需要本地有摄像头。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_enable_local_video(struct nertc_engine* self, nertc_video_stream_type stream_type, bool enabled); + +/** + * @if English + * Subscribes or unsubscribes video streams from specified remote users. + * - After a user joins a room, the video streams from remote users are not subscribed by default. If you want to view video + * streams from specified remote users, you can call this method to subscribe to the video streams from the user when the user + * joins the room or publishes the video streams. + * - This method can be called only if a user joins a room. + * @param[in] uid The user ID. + * @param[in] type The type of the subscribed video streams. #NERtcRemoteVideoStreamType. + * @param[in] subscribe + * - true: Subscribes to specified video streams. This is the default value. + * - false: Not subscribing to specified video streams. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 订阅或取消订阅指定远端用户的视频流。 + * - + * 用户加入房间之后，默认不订阅远端用户的视频流，如果希望看到指定远端用户的视频，可以在监听到对方加入房间或发布视频流之后，通过此方法订阅该用户的视频流。 + * - 该方法需要在加入房间后调用。 + * @param[in] uid 指定用户的用户 ID。 + * @param[in] type 订阅的视频流类型。 #NERtcRemoteVideoStreamType + * @param[in] subscribe + * - true: （默认）订阅指定视频流。 + * - false: 不订阅指定视频流。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ + +NERTC_API int NERTC_CALL nertc_engine_subscribe_remote_video_stream(struct nertc_engine* self, + nertc_uid_t uid, + nertc_video_stream_type type, + nertc_remote_video_stream_type stream_type, + bool subscribe); + +/** + * @if English + * Switches between the front and rear cameras. + *
Make sure that you call this method after the camera starts. For example, you can call this method after you call + * startPreview or joinChannel. + * @note The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official + * website of CommsEase and replace the audio-only SDK. + * @return The value returned. A value of 0 indicates that the operation is successful. + * @endif + * @if Chinese + * 切换前置/后置摄像头。 + *
该方法需要在相机启动后调用，例如调用 startPreview 或 joinChannel 后。 + * @note 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。 + * @return 操作返回值，成功则返回 0 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_switch_camera(struct nertc_engine* self); + +/** + * @if English + * @endif + * @if Chinese + * 指定前置/后置摄像头。 + *
该方法需要在相机启动后调用，例如调用 StartPreview 或 joinChannel 后。 + * @note 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。 + * @since V4.6.10 + * @param position 摄像头类型。详细信息请参考 {@link RtcCameraPosition}。该参数为必填参数，若未赋值，SDK 会报错。 + * @return + * - 0：方法调用成功。 + * - 其他：方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_switch_camera_with_position(struct nertc_engine* self, nertc_camera_position position); +/** + * @if English + * Gets the current camera direction. + * - This method is used to check whether the current camera is front-facing or rear. + * - Call this method after enabling the local camera. That said, you can call this method before calling startVideoPreview or + * joinChannel, depending on which method you use to turn on your local camera.（only for Android） + * @since V4.5.0 + * @return + * - {@code 0}：The rear camera. + * - Others：The front camera. + * @endif + * @if Chinese + * 查看当前摄像头配置。 + * - 该方法用于查看当前使用的摄像头为前置摄像头还是后置摄像头。 + * - 该方法需要在相机启动后调用，例如调用 startVideoPreview 或 joinChannel 后。（仅Android有效） + * @since V4.5.0 + * @return + * - {@code 0}：后置摄像头 + * - 其他值：前置摄像头 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_get_current_camera(struct nertc_engine* self); + +NERTC_END_DECLS + +#endif // NERTC_ENGINE_H diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_engine_defines.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_engine_defines.h new file mode 100644 index 0000000..fba5b36 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_engine_defines.h @@ -0,0 +1,8203 @@ +#ifndef NERTC_DEFINES_H +#define NERTC_DEFINES_H + +#ifdef __cplusplus +#include +#else +#include +#endif + +#ifdef __cplusplus +#define NERTC_BEGIN_DECLS extern "C" { +#define NERTC_END_DECLS } +#else +#define NERTC_BEGIN_DECLS +#define NERTC_END_DECLS +#endif + +#ifdef WIN32 +#define NERTC_API __declspec(dllexport) +#define NERTC_CALL __cdecl +#else +#define NERTC_API __attribute__ ((visibility ("default"))) +#define NERTC_CALL +#endif +/** + * @if English + * Video max plane count. + * @endif + * @if Chinese + * Video max plane count. + * @endif + */ +#define kNERtcMaxPlaneCount 4 +/** + * @if English + * The length of the encryption key. + * @endif + * @if Chinese + * 加密key的长度 + * @endif + */ +#define kNERtcEncryptByteLength 128 +/** + * @if Chinese + * 自定义信息的长度 + * @endif + */ +#define kNERtcCustomInfoLength 128 +/** + * @if English + * Maximum length of a room ID. + * @endif + * @if Chinese + * 房间ID最大长度 + * @endif + */ +#define kNERtcMaxChannelNameLength 128 +/** + * @if English + * maximum token length. + * @endif + * @if Chinese + * token最大长度 + * @endif + */ +#define kNERtcMaxTokenLength 256 +/** + * @if English + * Maximum length of a device ID. + * @endif + * @if Chinese + * 设备ID最大长度。 + * @endif + */ +#define kNERtcMaxDeviceIDLength 256 +/** + * @if English + * Maximum length of a device name. + * @endif + * @if Chinese + * 设备名最大长度。 + * @endif + */ +#define kNERtcMaxDeviceNameLength 256 +/** + * @if English + * Maximum length of the URI. + * @endif + * @if Chinese + * URI最大长度。 + * @endif + */ +#define kNERtcMaxURILength 256 +/** + * @if English + * Maximum length of the task ID. + * @endif + * @if Chinese + * 任务ID最大长度。 + * @endif + */ +#define kNERtcMaxTaskIDLength 64 +/** + * @if English + * Maximum length of the string buffer. + * @endif + * @if Chinese + * 字符串缓存区最大长度。 + * @endif + */ +#define kNERtcMaxBuffLength 1024 +/** + * @if English + * Maximum length of SEI information used in live streaming. Unit: bytes. + * @endif + * @if Chinese + * 直播推流中用到的SEI信息最大长度，单位：字节 + * @endif + */ +#define kNERtcMaxSEIBufferLength 4096 +/** + * @if English + * Device ID of an external video input source. After you enable external input, you must set this device ID using setDevice. + * @endif + * @if Chinese + * 外部视频输入源设备ID，开启外部输入之后，需要通过setDevice设置此设备ID。 + * @endif + */ +#define kNERtcExternalVideoDeviceID "nertc-video-external-device" +/** + * @if English + * The audio device automatically selects the ID. When the ID is set as the device, the SDK will automatically select the + * appropriate audio device based on the device management system settings. + * @endif + * @if Chinese + * 音频设备自动选择ID，设置该ID为设备时，SDK会根据设备插拔系统设置等自动选择合适音频设备。 + * @endif + */ +#define kNERtcAudioDeviceAutoID "nertc-audio-device-auto" + +/** + * @if English + * 64-bit unsigned integer. Recommended setting range: 1 to 2 63 -1, and make sure the number is unique. + * @endif + * @if Chinese + * 64位无符号整数。建议设置范围：1到 263-1，并保证唯一性。 + * @endif + */ +typedef uint64_t nertc_uid_t; +/** + * @if English + * 64-bit unsigned integer. Recommended setting range: 1 to 2 63 -1, and make sure the number is unique. + * @endif + * @if Chinese + * 64位无符号整数。建议设置范围：1到 263-1，并保证唯一性。 + * @endif + */ +typedef uint64_t channel_id_t; +/** + * @if English + * Identify the source of the screen capture from a window or screen. If the source is a window, the type will be converted to + * HWND on Windows, and it will be converted to the INT data type on macOS. If the source is screen, the source type will be + * converted to the INT data type. + * @endif + * @if Chinese + * 用于标识屏幕捕捉的源，代表某个窗口或屏幕。源为窗口时, Windows上该类型会转换为HWND, MAC上转换为整形。源为屏幕时会转换为整形。 + * @endif + */ +typedef void* source_id_t; + + +/** + * @if English + * Interface ID type. + * + * @endif + * @if Chinese + * 接口ID类型。 + * @endif + */ +typedef enum { + /** + * @if English + * Get the interface ID of the audio device manager. + * @endif + * @if Chinese + * 获取音频设备管理器的接口ID + * @endif + */ + kNERtcIIDAudioDeviceManager = 1, + /** + * @if English + * Get the interface ID of the video device manager. + * @endif + * @if Chinese + * 获取视频设备管理器的接口ID + * @endif + */ + kNERtcIIDVideoDeviceManager = 2, +} nertc_interface_id_type; + +/** + * @if English + * Participant role type. + * @endif + * @if Chinese + * 参会者角色类型 + * @endif + */ +typedef enum { + /** + * @if English + * The host role in live streaming. The host has the permissions to open or close audio and video devices, such as a camera, + * publish streams, and configure streaming tasks in interactive live streaming. The status of the host is visible to the + * users in the room when the host joins or leaves the room. + * @endif + * @if Chinese + * （默认）直播模式中的主播，可以操作摄像头等音视频设备、发布流、配置互动直播推流任务、上下线对房间内其他用户可见。 + * @endif + */ + kNERtcClientRoleBroadcaster = 0, + /** + * @if English + * The audience role in live streaming. The audience can only receive audio and video streams, and cannot manage audio and + * video devices, and configure streaming tasks in interactive live streaming. The status of an audience is invisible to the + * users in the room when the audience joins or leaves the room. + * @endif + * @if Chinese + * 直播模式中的观众，观众只能接收音视频流，不支持操作音视频设备、配置互动直播推流任务、上下线不通知其他用户。 + * @endif + */ + kNERtcClientRoleAudience = 1, +} nertc_client_role; + +/** + * @if English + * Scenario types. + * @endif + * @if Chinese + * 场景模式。 + * @endif + */ +typedef enum { + /** + * @if English + * Communication mode。 + * @endif + * @if Chinese + * 通话场景 + * @endif + */ + kNERtcChannelProfileCommunication = 0, + /** + * @if English + * Live streaming mode. + * @endif + * @if Chinese + * 直播推流场景 + * @endif + */ + kNERtcChannelProfileLiveBroadcasting = 1, +} nertc_channel_profile_type; + + +/** + * @if English + * Media priority type. + * @endif + * @if Chinese + * 媒体优先级类型。 + * @endif + */ +typedef enum { + /** + * @if English + * High priority + * @endif + * @if Chinese + * 高优先级 + * @endif + */ + kNERtcMediaPriorityHigh = 50, + /** + * @if English + * Normal priority (default) + * @endif + * @if Chinese + * （默认）普通优先级 + * @endif + */ + kNERtcMediaPriorityNormal = 100, +} nertc_media_priority_type; + +/** + * @if English + * Co-hosting method. + * @endif + * @if Chinese + * 连麦方式。 + * @endif + */ +typedef enum { + kNERtcLayoutFloatingRightVertical = 0, + kNERtcLayoutFloatingLeftVertical, + kNERtcLayoutSplitScreen, + kNERtcLayoutSplitScreenScaling, + kNERtcLayoutCustom, + kNERtcLayoutAudioOnly, +} nertc_live_stream_layout_mode; + +/** + * @if English + * Configuration of streaming tasks. + * @endif + * @if Chinese + * 直播推流任务的配置项。 + * @endif + */ +struct nertc_live_stream_task_option { + /** + * @if English + * Streaming task ID, which is the unique identifier of a streaming task. You can use the ID to create and delete streaming + * tasks. + * @endif + * @if Chinese + * 推流任务ID，为推流任务的唯一标识，用于过程中增删任务操作。 + * @endif + */ + char task_id[kNERtcMaxTaskIDLength]; + /** + * @if English + * Live streaming URL address. + * @endif + * @if Chinese + * 直播推流地址。 + * @endif + */ + char stream_url[kNERtcMaxURILength]; + /** + * @if English + * Enable or disable server recording. The default value is false. + * @endif + * @if Chinese + * 服务器录制功能是否开启，默认值为 false。 + * @endif + */ + bool server_record_enabled; + /** + * @if English + * Co-hosting method. The default value is kNERtcLayoutFloatingRightVertical. + * @endif + * @if Chinese + * 连麦方式，默认值为 kNERtcLayoutFloatingRightVertical。 + * @endif + */ + nertc_live_stream_layout_mode layout_mode; + /** + * @if English + * Specify the main picture uid (optional). + * @endif + * @if Chinese + * 指定大画面uid（选填）。 + * @endif + */ + nertc_uid_t main_picture_account_id; + /** + * @if English + * Custom layout parameters in JSON format (optional). You need to set the layout parameters only when layout_mode is set to + * kNERtcLayoutCustom or kNERtcLayoutAudioOnly. + * @endif + * @if Chinese + * 自定义布局参数（选填），JSON 字符串格式, 只有当layout_mode为 kNERtcLayoutCustom 或 kNERtcLayoutAudioOnly时才需要设置。 + * @endif + */ + char layout_parameters[kNERtcMaxBuffLength]; +}; + +/** + * @if English + * Streaming mode in live streaming. + * @endif + * @if Chinese + * 直播推流模式 + * @endif + */ +typedef enum { + /** + * @if English + * Publish the video stream. + * @endif + * @if Chinese + * 推流带视频 + * @endif + */ + kNERtcLsModeVideo = 0, + /** + * @if English + * Publish audio-only stream. + * @endif + * @if Chinese + * 推流纯音频 + * @endif + */ + kNERtcLsModeAudio = 1, +} nertc_live_stream_mode; + +/** + * @if English + * Video cropping mode in live streaming + * @endif + * @if Chinese + * 直播推流视频裁剪模式 + * @endif + */ +typedef enum { + /** + * @if English + * 0: Video dimensions are scaled proportionally. All video content is prioritized for display. If the video dimensions do not + * match the display window, the unfilled area of the window will be filled with the background color. + * @endif + * @if Chinese + * 0: 视频尺寸等比缩放。优先保证视频内容全部显示。因视频尺寸与显示视窗尺寸不一致造成的视窗未被填满的区域填充背景色。 + * @endif + */ + kNERtcLsModeVideoScaleFit = 0, + /** + * @if English + * 1: Video dimensions are scaled proportionally. The window is prioritized to be filled. The extra video due to the + * inconsistency between the video size and the display window size will be cropped off. + * @endif + * @if Chinese + * 1: 视频尺寸等比缩放。优先保证视窗被填满。因视频尺寸与显示视窗尺寸不一致而多出的视频将被截掉。 + * @endif + */ + kNERtcLsModeVideoScaleCropFill = 1, +} nertc_live_stream_video_scale_mode; + +/** + * @if English + * The member layout in live streaming. + * @endif + * @if Chinese + * 直播成员布局 + * @endif + */ +struct nertc_live_stream_user_transcoding { + /** + * @if English + * Pulls the video stream of the user with the specified uid into the live event. If you add multiple users, the uid must be + * unique. + * @endif + * @if Chinese + * 将指定uid对应用户的视频流拉入直播。如果添加多个 users，则 uid 不能重复。 + * @endif + */ + nertc_uid_t uid; + /** + * @if English + * Specifies whether to play back the specific video stream from the user to viewers in the live event. Valid values: + * - true: plays the video stream. + * - false: does not play the video stream. + * The setting becomes invalid when the streaming mode is set to kNERtcLsModeAudio. + * @endif + * @if Chinese + * 是否在直播中向观看者播放该用户的对应视频流。可设置为： + * - true：在直播中播放该用户的视频流。 + * - false：在直播中不播放该用户的视频流。 + * 推流模式为 kNERtcLsModeAudio 时无效。 + * @endif + */ + bool video_push; + /** + * @if English + * Adjustment between the video and the canvas in live streaming. For more information, see NERtcLiveStreamVideoScaleMode. + * @endif + * @if Chinese + * 直播推流视频和画布的调节属性。详细信息请参考 NERtcLiveStreamVideoScaleMode。 + * @endif + */ + nertc_live_stream_video_scale_mode adaption; + /** + * @if English + * The X parameter is used to set the horizontal coordinate value of the user image. You can specify a point in the canvas + * with X and Y coordinates. This point is used as the anchor of the upper left corner of the user image. + * - Value range: 0 to 1920. If the specified value is set to an odd value, the value is automatically rounded down to an even + * number. + * - If the user image exceeds the canvas, an error occurs when you call the method. + * @endif + * @if Chinese + * x 参数用于设置用户图像的横轴坐标值。通过 x 和 y 指定画布坐标中的一个点，该点将作为用户图像的左上角。 + * - 取值范围为 0~1920，若设置为奇数值，会自动向下取偶。 + * - 用户图像范围如果超出超出画布，调用方法时会报错。 + * @endif + */ + int x; + /** + * @if English + * The Y parameter is used to set the vertical coordinate value of the user image. You can specify a point in the canvas with + * X and Y coordinates. This point is used as the anchor of the upper left corner of the user image. + * - Value range: 0 to 1920. If the specified value is set to an odd value, the value is automatically rounded down to an even + * number. + * - If the user image exceeds the canvas, an error occurs when you call the method. + * @endif + * @if Chinese + * y参数用于设置用户图像的纵轴坐标值。通过 x 和 y 指定画布坐标中的一个点，该点将作为用户图像的左上角。 + * - 取值范围为 0~1920，若设置为奇数值，会自动向下取偶。 + * - 用户图像范围如果超出超出画布，调用方法时会报错。 + * @endif + */ + int y; + /** + * @if English + * The width of the user image in the canvas. + * - Value range: 0 to 1920. The default value is 0. If the specified value is set to an odd value, the value is automatically + * rounded down to an even number. + * - If the user image exceeds the canvas, an error occurs when you call the method. + * @endif + * @if Chinese + * 该用户图像在画布中的宽度。 + * - 取值范围为 0~1920，默认为0。若设置为奇数值，会自动向下取偶。 + * - 用户图像范围如果超出超出画布，调用方法时会报错。 + * + * @endif + */ + int width; + /** + * @if English + * The height of the user image in the canvas. + * - The X parameter is used to set the horizontal coordinate value of the user image. You can specify a point in the canvas + * with X and Y coordinates. This point is used as the anchor of the upper left corner of the user image. 0 to 1920. The + * default value is 0. If the specified value is set to an odd value, the value is automatically rounded down to an even + * number. + * - Value range: 0 to 1920. If the specified value is set to an odd value, the value is automatically rounded down to an even + * number. + * @endif + * @if Chinese + * 该用户图像在画布中的高度。 + * - 取值范围为 0~1920，默认为0。若设置为奇数值，会自动向下取偶。 + * - 用户图像范围如果超出超出画布，调用方法时会报错。 + * @endif + */ + int height; + /** + * @if English + * Specifies whether to mix the audio stream from the user in the live event. Valid values: + * - true: mixes the audio streams from users in a live event. + * - false: mutes the audio streams from users in a live event. + * @endif + * @if Chinese + * 是否在直播中混流该用户的对应音频流。可设置为： + * - true：在直播中混流该用户的对应音频流。 + * - false：在直播中将该用户设置为静音。 + * @endif + */ + bool audio_push; + /** + * @if English + * The layer number that is used to determine the rendering level. Value range: 0 to 100. A value of 0 indicates the bottom + * layer and 100 indicates the top layer.
The rendering area at the same level is overwritten based on the existing + * overlay strategy. Rendering is performed in the order of the array, and the index increases in ascending order. + * @endif + * @if Chinese + * 图层编号，用来决定渲染层级, 取值0-100，0位于最底层，100位于最顶层。 + * 相同层级的渲染区域按照现有的覆盖逻辑实现，即按照数组中顺序进行渲染，index 递增依次往上叠加。 + * @endif + */ + int z_order; +}; + +/** + * @if English + * Picture layout. + * @endif + * @if Chinese + * 图片布局 + * @endif + */ +struct nertc_live_stream_image_info { + /** + * @if English + * The URL of the placeholder image. + * @endif + * @if Chinese + * 占位图片的URL。 + * @endif + */ + char url[kNERtcMaxURILength]; + /** + * @if English + * The X parameter is used to set the horizontal coordinate value of the canvas. + * You can specify a point in the canvas with X and Y coordinates. This point is used as the anchor of the upper left corner + * of the placeholder image. Value range: 0 to 1920. If the specified value is set to an odd value, the value is automatically + * rounded down to an even number. + * @endif + * @if Chinese + * x 参数用于设置画布的横轴坐标值。 + * 通过 x 和 y 指定画布坐标中的一个点，该点将作为占位图片的左上角。 + * 取值范围为 0~1920，若设置为奇数值，会自动向下取偶。 + * @endif + */ + int x; + /** + * @if English + * The Y parameter is used to set the vertical coordinate value of the canvas. + * - You can specify a point in the canvas with X and Y coordinates. This point is used as the anchor of the upper left corner + * of the placeholder image. + * - Value range: 0 to 1920. If the specified value is set to an odd value, the value is automatically rounded down to an even + * number. + * @endif + * @if Chinese + * y 参数用于设置画布的纵轴坐标值。 + * - 通过 x 和 y 指定画布坐标中的一个点，该点将作为占位图片的左上角。 + * - 取值范围为 0~1920，若设置为奇数值，会自动向下取偶。 + * @endif + */ + int y; + /** + * @if English + * The width of the placeholder image in the canvas. + *
Value range: 0 to 1920. If the specified value is set to an odd value, the value is automatically rounded down to an + * even number. + * @endif + * @if Chinese + * 该占位图片在画布中的宽度。 + *
取值范围为 0~1920，若设置为奇数值，会自动向下取偶。 + * @endif + */ + int width; + /** + * @if English + * The height of the placeholder image in the canvas. + *
Value range: 0 to 1920. If the specified value is set to an odd value, the value is automatically rounded down to an + * even number. + * @endif + * @if Chinese + * 该占位图片在画布中的高度。 + *
取值范围为 0~1920，若设置为奇数值，会自动向下取偶。 + * @endif + */ + int height; + /** + * @if Chinese + * 占位图的图层编号，用来决定渲染层级。 + *
取值范围为 0~100，默认为 0。 + * - 最小值为 0（默认值），表示该区域图像位于最底层。 + * - 最大值为 100，表示该区域图像位于最顶层。 + *
注意：相同层级的渲染区域会按照数组中顺序进行渲染，随着 index 递增，依次往上叠加。 + * @endif + */ + int z_order; +}; + + +/** + * @if English + * The live streaming layout. + * @endif + * @if Chinese + * 直播布局 + * @endif + */ +struct nertc_live_stream_layout { + /** + * @if English + * The width of the overall canvas. Unit: px. Value range: 0 to 1920. If the specified value is set to an odd value, the value + * is automatically rounded down to an even number. + * @endif + * @if Chinese + * 整体画布的宽度，单位为 px。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。 + * @endif + */ + int width; + /** + * @if English + * The height of the overall canvas. Unit: - true: 0 to 1920. If the specified value is set to an odd value, the value is + * automatically rounded down to an even number. + * @endif + * @if Chinese + * 整体画布的高度，单位为 px。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。 + * @endif + */ + int height; + /** + * @if English + * The background color of the canvas. The value of the background color is the sum of 256 x 256 x R + 256 x G + B. Enter the + * corresponding RGB values into this formula to calculate the value. If the value is unspecified, the default value is 0. + * @endif + * @if Chinese + * 画面背景颜色，格式为 256 x 256 x R + 256 x G + B的和。请将对应 RGB 的值分别带入此公式计算即可。若未设置，则默认为0。 + * @endif + */ + unsigned int background_color; + /** + * @if English + * The member layout in live streaming. + * @endif + * @if Chinese + * 成员布局个数。 + * @endif + */ + unsigned int user_count; + /** + * @if English + * The member layout array. For more information, see NERtcLiveStreamUserTranscoding. + * @endif + * @if Chinese + * 成员布局数组，详细信息请参考 NERtcLiveStreamUserTranscoding。 + * @endif + */ + nertc_live_stream_user_transcoding* users; + /** + * @if English + * For more information, see NERtcLiveStreamImageInfo. + * @endif + * @if Chinese + * 详细信息请参考 NERtcLiveStreamImageInfo。 + * @endif + */ + nertc_live_stream_image_info* bg_image; + + /** + * @if English + * The member of picture layout. + * @endif + * @if Chinese + * 图片布局个数。 + * @endif + */ + int bg_image_count; +}; + +/** + * @if English + * Live streaming audio sample rate + * @endif + * @if Chinese + * 直播推流音频采样率 + * @endif + */ +typedef enum { + /** + * @if English + * The sample rate is 32 kHz. + * @endif + * @if Chinese + * 采样率为 32 kHz。 + * @endif + */ + kNERtcLiveStreamAudioSampleRate32000 = 32000, + /** + * @if English + * The sample rate is 44.1 kHz. + * @endif + * @if Chinese + * 采样率为 44.1 kHz。 + * @endif + */ + kNERtcLiveStreamAudioSampleRate44100 = 44100, + /** + * @if English + * (Default) The sample rate is 48 kHz. + * @endif + * @if Chinese + * （默认）采样率为 48 kHz。 + * @endif + */ + kNERtcLiveStreamAudioSampleRate48000 = 48000, +} nertc_live_stream_audio_sample_rate; + + +/** + * @if English + * Live streaming audio codec profile + * @endif + * @if Chinese + * 直播推流音频编码规格 + * @endif + */ +typedef enum { + /** + * @if English + * (Default) LC- AAC, the basic audio encoding profile. + * @endif + * @if Chinese + * （默认）LC-AAC 规格，表示基本音频编码规格。 + * @endif + */ + kNERtcLiveStreamAudioCodecProfileLCAAC = 0, + /** + * @if English + * HE-AAC, high-efficiency audio encoding profile. + * @endif + * @if Chinese + * HE-AAC 规格，表示高效音频编码规格。 + * @endif + */ + kNERtcLiveStreamAudioCodecProfileHEAAC = 1, +} nertc_live_stream_audio_codec_profile; + +/** + * @if English + * Streaming configuration. + * @endif + * @if Chinese + * 直播流配置 + * @endif + */ +struct nertc_live_stream_config { + /** + * @if English + * Enables or disables single video pass-through. By default, the setting is disabled. + * - If you enable video pass-through, and the room ingests only one video stream, then, the stream is not transcoded and does + * not follow the transcoding flow. The video stream is directly published to a CDN. + * - If multiple video streams from different room members are mixed into one video stream, this setting becomes invalid, and + * will not be restored when the stream is restored to the single stream. + * @endif + * @if Chinese + * 单路视频透传开关，默认为关闭状态。 + * - 开启后，如果房间中只有一路视频流输入， 则不对输入视频流进行转码，不遵循转码布局，直接推流 CDN。 + * - 如果有多个房间成员视频流混合为一路流，则该设置失效，并在恢复为一个成员画面（单路流）时也不会恢复。 + * @endif + */ + bool single_video_passthrough; + /** + * @if English + * The bitrate of the audio stream. + * - Unit: kbps. Valid values: 10 to 192. + * - We recommend that you set the bitrate to 64 or higher for voice scenarios and set 128 or higher for music scenarios. + * @endif + * @if Chinese + * 音频推流码率。 + * - 单位为 kbps，取值范围为 10~192。 + * - 语音场景建议设置为 64 及以上码率，音乐场景建议设置为 128 及以上码率。 + * @endif + */ + int audio_bitrate; + + /** + * @if English + * The sample rate of the audio stream. Unit: Hz. The default value is kNERtcLiveStreamAudioSampleRate48000, which indicates + * the sample rate of 48 kHz. + * @endif + * @if Chinese + * 音频推流采样率。单位为Hz。默认为 kNERtcLiveStreamAudioSampleRate48000，即采样率为 48 kHz。 + * @endif + */ + nertc_live_stream_audio_sample_rate sampleRate; + + /** + * @if English + * The number of audio channels for publishing streams. The default value is 2, which represents the stereo sound. + * @endif + * @if Chinese + * 音频推流声道数，默认值为 2 双声道。 + * @endif + */ + int channels; + + /** + * @if English + * The audio encoding profile. The default value is NERtcLiveStreamAudioCodecProfileLCAAC, which is the basic encoding + * profile. + * - 0: LC-AAC, the basic encoding profile. + * - 1: HE-AAC, the high-efficiency audio encoding profile. + * @endif + * @if Chinese + * 音频编码规格。默认值 NERtcLiveStreamAudioCodecProfileLCAAC，普通编码规格。 + * - 0: LC-AAC 规格，表示基本音频编码规格 + * - 1: HE-AAC 规格，表示高效音频编码规格。 + * @endif + */ + nertc_live_stream_audio_sample_rate audioCodecProfile; +}; + +/** + * @if English + * Configuration of streaming tasks. + * @endif + * @if Chinese + * 直播推流任务的配置项。 + * @endif + */ +struct nertc_live_stream_task_info { + /** + * @if English + * The ID of a custom streaming task. The ID must be up to 64 characters in length and can contain letters, numbers, and + * underscores. The ID must be unique. + * @endif + * @if Chinese + * 自定义的推流任务 ID。字母、数字、下划线组成的 64 位以内的字符串。请保证此 ID 唯一。 + * @endif + */ + char task_id[kNERtcMaxTaskIDLength]; + /** + * @if English + * The streaming URL, such as rtmp://test.url. + *
The URL can be set to the value of the pushUrl response parameter of the server API used to create a room in NetEase + * CommsEase live streaming. + * @endif + * @if Chinese + * 推流地址，例如 rtmp://test.url。 + *
此处的推流地址可设置为网易云信直播产品中服务端 API创建房间的返回参数pushUrl。 + * @endif + */ + char stream_url[kNERtcMaxURILength]; + /** + * @if English + * Specifies whether to enable audio and video recording in the CDN relayed streaming. By default, the setting is disabled. + * @endif + * @if Chinese + * 旁路推流是否需要进行音视频录制。默认为关闭状态。 + * @endif + */ + bool server_record_enabled; + /** + * @if English + * The live streaming mode. For more information, see NERtcLiveStreamMode. + * @endif + * @if Chinese + * 直播推流模式。详细信息请参考 NERtcLiveStreamMode。 + * @endif + */ + nertc_live_stream_mode ls_mode; + /** + * @if English + * Set the canvas layout of Interactive Live Streaming. For more information, see NERtcLiveStreamLayout. + * @endif + * @if Chinese + * 设置互动直播的画面布局。详细信息请参考 NERtcLiveStreamLayout。 + * @endif + */ + nertc_live_stream_layout layout; + /** + * @if English + * Settings such as encoding parameters of the audio and video streams. For more information, see NERtcLiveConfig. + * @endif + * @if Chinese + * 音视频流编码参数等设置。详细信息请参考 NERtcLiveConfig。 + * @endif + */ + nertc_live_stream_config config; + /** + * @if English + * SEI message + * @endif + * @if Chinese + * SEI信息 + * @endif + */ + char extra_info[kNERtcMaxSEIBufferLength]; +}; + +/** + * @if English + * Live streaming status code. + * @endif + * @if Chinese + * 直播推流状态。 + * @endif + */ +typedef enum { + /** + * @if English + * Publishing. + * @endif + * @if Chinese + * 推流中 + * @endif + */ + kNERtcLsStatePushing = 505, + /** + * @if English + * Publishing fails. + * @endif + * @if Chinese + * 互动直播推流失败 + * @endif + */ + kNERtcLsStatePushFail = 506, + /** + * @if English + * Publishing ends. + * @endif + * @if Chinese + * 推流结束 + * @endif + */ + kNERtcLsStatePushStopped = 511, + /** + * @if English + * Background image setting error. + * @endif + * @if Chinese + * 背景图片设置出错 + * @endif + */ + kNERtcLsStateImageError = 512, +} nertc_live_stream_state_code; + +/** + * @if English + * System ategory. + * @endif + * @if Chinese + * 系统分类。 + * @endif + */ +typedef enum { + /** + * @if English + * iOS universal device. + * @endif + * @if Chinese + * iOS 通用设备 + * @endif + */ + kNERtcOSiOS = 1, + /** + * @if English + * Android universal device. + * @endif + * @if Chinese + * Android 通用设备 + * @endif + */ + kNERtcOSAndroid = 2, + /** + * @if English + * PC设备 + * @endif + * @if Chinese + * PC device. + * @endif + */ + kNERtcOSPC = 3, + /** + * @if English + * WebRTC. + * @endif + * @if Chinese + * WebRTC + * @endif + */ + kNERtcOSWebRTC = 4, +} nertc_os_category; + +/** + * @if English + * Audio profile. Audio sample rate, bitrate, encoding mode, and the number of channels. + * @endif + * @if Chinese + * 音频属性。设置采样率，码率，编码模式和声道数。 + * @endif + */ +typedef enum { + /** + * @if English + * Default settings. kNERtcAudioProfileStandard in the speech scenarios. kNERtcAudioProfileHighQuality in the music scenarios. + * @endif + * @if Chinese + * 0: 默认设置。Speech 场景下为 kNERtcAudioProfileStandardExtend，Music 场景下为 kNERtcAudioProfileHighQuality。 + * @endif + */ + kNERtcAudioProfileDefault = 0, + /** + * @if English + * 1: Standard-quality audio encoding, 16000Hz, 20kbps. + * @endif + * @if Chinese + * 1: 普通质量的音频编码，16000Hz，20Kbps + * @endif + */ + kNERtcAudioProfileStandard = 1, + /** + * @if English + * 2: Standard-quality audio encoding, 16000Hz, 32kbps. + * @endif + * @if Chinese + * 2: 普通质量的音频编码，16000Hz，32Kbps + * @endif + */ + kNERtcAudioProfileStandardExtend = 2, + /** + * @if English + * 3: Medium-quality audio encoding, 48000Hz, 32kbps. + * @endif + * @if Chinese + * 3: 中等质量的音频编码，48000Hz，32Kbps + * @endif + */ + kNERtcAudioProfileMiddleQuality = 3, + /** + * @if English + * 4: Medium-quality stereo encoding, 48000Hz * 2, 64kbps. + * @endif + * @if Chinese + * 4: 中等质量的立体声编码，48000Hz * 2，64Kbps + * @endif + */ + kNERtcAudioProfileMiddleQualityStereo = 4, + /** + * @if English + * 5: High-quality audio encoding, 48000Hz, 64kbps. + * @endif + * @if Chinese + * 5: 高质量的音频编码，48000Hz，64Kbps + * @endif + */ + kNERtcAudioProfileHighQuality = 5, + /** + * @if English + * 6: High-quality stereo encoding, 48000Hz * 2, 128kbps. + * @endif + * @if Chinese + * 6: 高质量的立体声编码，48000Hz * 2，128Kbps + * @endif + */ + kNERtcAudioProfileHighQualityStereo = 6, +} nertc_audio_profile_type; + + +/** + * @if English + * Audio application scenarios. Different audio scenarios use different audio capture modes and playback modes. + * @endif + * @if Chinese + * 音频应用场景。不同的场景设置对应不同的音频采集模式、播放模式。 + * @endif + */ +typedef enum { + /** + * @if English + * 0: Default settings. + * - kNERtcAudioScenarioSpeech in kNERtcChannelProfileCommunication. + * - kNERtcAudioScenarioMusic in kNERtcChannelProfileLiveBroadcasting. + * @endif + * @if Chinese + * 0: 默认设置 + * - kNERtcChannelProfileCommunication下为kNERtcAudioScenarioSpeech， + * - kNERtcChannelProfileLiveBroadcasting下为kNERtcAudioScenarioMusic。 + * @endif + */ + kNERtcAudioScenarioDefault = 0, + /** + * @if English + * 1: Voice scenarios. Set NERtcAudioProfileType to kNERtcAudioProfileMiddleQuality or lower. + * @endif + * @if Chinese + * 1: 语音场景. NERtcAudioProfileType 推荐使用 kNERtcAudioProfileMiddleQuality 及以下 + * @endif + */ + kNERtcAudioScenarioSpeech = 1, + /** + * @if English + * 2: Music scenarios. Set NERtcAudioProfileType to kNERtcAudioProfileMiddleQualityStereo or above. + * @endif + * @if Chinese + * 2: 音乐场景。NERtcAudioProfileType 推荐使用 kNERtcAudioProfileMiddleQualityStereo 及以上 + * @endif + */ + kNERtcAudioScenarioMusic = 2, + /** + * @if English + * 3: Chatroom scenario. Set NERtcAudioProfileType to kNERtcAudioProfileHighQuality or above. + * @endif + * @if Chinese + * 3: 语聊房场景 (只适用于移动端）。NERtcAudioProfileType 推荐使用 kNERtcAudioProfileHighQuality 及以上 + * @endif + */ + kNERtcAudioScenarioChatroom = 3, +} nertc_audio_scenario_type; + +/** + * @if English + * The preset value of the voice changer. + * @endif + * @if Chinese + * 变声 预设值 + * @endif + */ +typedef enum { + /** + * @if English + * By default, the setting is disabled. + * @endif + * @if Chinese + * 默认关闭 + * @endif + */ + kNERtcVoiceChangerOff = 0, + /** + * @if English + * A robot voice. + * @endif + * @if Chinese + * 机器人 + * @endif + */ + kNERtcVoiceChangerRobot = 1, + /** + * @if English + * A giant voice. + * @endif + * @if Chinese + * 巨人 + * @endif + */ + kNERtcVoiceChangerGaint = 2, + /** + * @if English + * A horror voice. + * @endif + * @if Chinese + * 恐怖 + * @endif + */ + kNERtcVoiceChangerHorror = 3, + /** + * @if English + * A maturity voice. + * @endif + * @if Chinese + * 成熟 + * @endif + */ + kNERtcVoiceChangerMature = 4, + /** + * @if English + * From a male voice to a female voice. + * @endif + * @if Chinese + * 男变女 + * @endif + */ + kNERtcVoiceChangerManToWoman = 5, + /** + * @if English + * From a female voice to a male voice. + * @endif + * @if Chinese + * 女变男 + * @endif + */ + kNERtcVoiceChangerWomanToMan = 6, + /** + * @if English + * From a male voice to a loli voice. + * @endif + * @if Chinese + * 男变萝莉 + * @endif + */ + kNERtcVoiceChangerManToLoli = 7, + /** + * @if English + * From a female voice to a loli voice. + * @endif + * @if Chinese + * 女变萝莉 + * @endif + */ + kNERtcVoiceChangerWomanToLoli = 8, +} nertc_voice_changer_type; + +/** + * @if English + * Preset voice beautifier effect. + * @endif + * @if Chinese + * 预设的美声效果 + * @endif + */ +typedef enum { + /** + * @if English + * By default, the setting is disabled. + * @endif + * @if Chinese + * 默认关闭 + * @endif + */ + kNERtcVoiceBeautifierOff = 0, + /** + * @if English + * A muffled effect. + * @endif + * @if Chinese + * 低沉 + * @endif + */ + kNERtcVoiceBeautifierMuffled = 1, + /** + * @if English + * A mellow effect. + * @endif + * @if Chinese + * 圆润 + * @endif + */ + kNERtcVoiceBeautifierMellow = 2, + /** + * @if English + * A clear effect. + * @endif + * @if Chinese + * 清澈 + * @endif + */ + kNERtcVoiceBeautifierClear = 3, + /** + * @if English + * A magnetic effect. + * @endif + * @if Chinese + * 磁性 + * @endif + */ + kNERtcVoiceBeautifierMagnetic = 4, + /** + * @if English + * A recording studio effect. + * @endif + * @if Chinese + * 录音棚 + * @endif + */ + kNERtcVoiceBeautifierRecordingstudio = 5, + /** + * @if English + * A nature effect. + * @endif + * @if Chinese + * 天籁 + * @endif + */ + kNERtcVoiceBeautifierNature = 6, + /** + * @if English + * A KTV effect. + * @endif + * @if Chinese + * KTV + * @endif + */ + kNERtcVoiceBeautifierKTV = 7, + /** + * @if English + * A remote effect. + * @endif + * @if Chinese + * 悠远 + * @endif + */ + kNERtcVoiceBeautifierRemote = 8, + /** + * @if English + * A church effect. + * @endif + * @if Chinese + * 教堂 + * @endif + */ + kNERtcVoiceBeautifierChurch = 9, + /** + * @if English + * A bedroom effect. + * @endif + * @if Chinese + * 卧室 + * @endif + */ + kNERtcVoiceBeautifierBedroom = 10, + /** + * @if English + * A live effect. + * @endif + * @if Chinese + * Live + * @endif + */ + kNERtcVoiceBeautifierLive = 11, +} nertc_voice_beautifier_type; + +/** + * @if English + * The center frequency of the sound equalization band. + * @endif + * @if Chinese + * 音效均衡波段的中心频率 + * @endif + */ +typedef enum { + /** + * @if English + * 31 Hz + * @endif + * @if Chinese + * 31 Hz + * @endif + */ + kNERtcVoiceEqualizationBand_31 = 0, + /** + * @if English + * 62 Hz. + * @endif + * @if Chinese + * 62 Hz + * @endif + */ + kNERtcVoiceEqualizationBand_62 = 1, + /** + * @if English + * 125 Hz. + * @endif + * @if Chinese + * 125 Hz + * @endif + */ + kNERtcVoiceEqualizationBand_125 = 2, + /** + * @if English + * 250 Hz. + * @endif + * @if Chinese + * 250 Hz + * @endif + */ + kNERtcVoiceEqualizationBand_250 = 3, + /** + * @if English + * 500 Hz. + * @endif + * @if Chinese + * 500 Hz + * @endif + */ + kNERtcVoiceEqualizationBand_500 = 4, + /** + * @if English + * 1 kHz. + * @endif + * @if Chinese + * 1 kHz + * @endif + */ + kNERtcVoiceEqualizationBand_1K = 5, + /** + * @if English + * 2 kHz. + * @endif + * @if Chinese + * 2 kHz + * @endif + */ + kNERtcVoiceEqualizationBand_2K = 6, + /** + * @if English + * 4 kHz. + * @endif + * @if Chinese + * 4 kHz + * @endif + */ + kNERtcVoiceEqualizationBand_4K = 7, + /** + * @if English + * 8 kHz. + * @endif + * @if Chinese + * 8 kHz + * @endif + */ + kNERtcVoiceEqualizationBand_8K = 8, + /** + * @if English + * 16 kHz. + * @endif + * @if Chinese + * 16 kHz + * @endif + */ + kNERtcVoiceEqualizationBand_16K = 9, +} nertc_voice_equalization_band; + +/** + * @if English + * The camera capturer configuration. + * @endif + * @if Chinese + * 摄像头采集配置。 + * @endif + */ +struct nertc_camera_capture_config { + /** + * @if English + * The width (px) of the video image captured by the local camera. + *
The video encoding resolution is expressed in width x height. It is used to set the video encoding resolution and + * measure the encoding quality. + * - capture_width: the pixels of the video frame on the horizontal axis, that is, the custom width. + * - capture_height： the pixels of the video frame on the horizontal axis, that is, the custom height. + * @note + * - To customize the width of the video image, set preference as kNERtcCameraOutputManual first, and then use captureWidth + * and captureHeight. + * - In manual mode, if the specified collection size is smaller than the encoding size, the encoding parameters will be + * aligned down to the collection size range. + * @endif + * @if Chinese + * 本地采集的视频宽度，单位为 px。 + *
视频编码分辨率以宽 x 高表示，用于设置视频编码分辨率，以衡量编码质量。 + * - captureWidth 表示视频帧在横轴上的像素，即自定义宽。 + * - captureHeight 表示视频帧在横轴上的像素，即自定义高。 + * @note + * - 如果您需要自定义本地采集的视频尺寸，请先将 preference 设为 kNERtcCameraOutputManual，再通过 captureWidth 和 captureHeight + * 设置采集的视频宽度。 + * - 手动模式下，如果指定的采集宽高小于编码宽高，编码参数会被下调对齐到采集的尺寸范围内。 + * @endif + */ + int capture_width; + /** + * @if English + * The height (px) of the video image captured by the local camera. + *
The video encoding resolution is expressed in width x height. It is used to set the video encoding resolution and + * measure the encoding quality. + * - capture_width: the pixels of the video frame on the horizontal axis, that is, the custom width. + * - capture_height： the pixels of the video frame on the horizontal axis, that is, the custom height. + * @note + * - To customize the width of the video image, set preference as CAPTURE_PREFERENCE_MANUAL first, and then use captureWidth + * and captureHeight. + * - In manual mode, if the specified collection size is smaller than the encoding size, the encoding parameters will be + * aligned down to the collection size range. + * @endif + * @if Chinese + * 本地采集的视频高度，单位为 px。 + *
视频编码分辨率以宽 x 高表示，用于设置视频编码分辨率，以衡量编码质量。 + * - captureWidth 表示视频帧在横轴上的像素，即自定义宽。 + * - captureHeight 表示视频帧在横轴上的像素，即自定义高。 + * @note + * - 如果您需要自定义本地采集的视频尺寸，请先将 preference 设为 kNERtcCameraOutputManual，再通过 captureWidth 和 captureHeight + * 设置采集的视频宽度。 + * - 手动模式下，如果指定的采集宽高小于编码宽高，编码参数会被下调对齐到采集的尺寸范围内。 + * @endif + */ + int capture_height; +}; + +/** + * @if English + * Video encoding configuration. The resolution used to measure encoding quality. + * @note kNERtcVideoProfileFake: + * - The peer sends a 16*16 fakeVideo (SEI delivered in audio-only streams), which is an internal behavior of the SDK. The view + * is not displayed at this time (the client receives only black frames). + * - Therefore, this setting is not actively applied. If you select the setting, the SDK applies the setting to the standard. + * @endif + * @if Chinese + * 视频编码配置。用于衡量编码质量。 + * @note + * kNERtcVideoProfileFake: + * - 表示对端发送 16*16 的 fakeVideo，即纯音频下发送 SEI，属于 SDK 内部行为，此时收到的是黑色帧，不需要显示 view。 + * - 因此这个档位不主动使用，属于被动接受，如果主动使用，SDK 内部会按 standard 处理。 + * @endif + */ +typedef enum { + /** + * @if English + * LD160x90/120, 15fps + * @endif + * @if Chinese + * 普清（160x90/120, 15fps） + * @endif + */ + kNERtcVideoProfileLowest = 0, + /** + * @if English + * LD 320x180/240, 15fps + * @endif + * @if Chinese + * 标清（320x180/240, 15fps） + * @endif + */ + kNERtcVideoProfileLow = 1, + /** + * @if English + * SD 640x360/480, 30fps + * @endif + * @if Chinese + * 高清（640x360/480, 30fps） + * @endif + */ + kNERtcVideoProfileStandard = 2, + /** + * @if English + * HD (1280 x 720, 30 fps) + * @endif + * @if Chinese + * 超清（1280x720, 30fps） + * @endif + */ + kNERtcVideoProfileHD720P = 3, + /** + * @if English + * 1080p (1920x1080, 30fps) + * @endif + * @if Chinese + * 1080P（1920x1080, 30fps） + * @endif + */ + kNERtcVideoProfileHD1080P = 4, + /** + * @if English + * None + * @endif + * @if Chinese + * 无效果。 + * @endif + */ + kNERtcVideoProfileNone = 5, + kNERtcVideoProfileMAX = kNERtcVideoProfileHD1080P, + /** + * @if English + * FakeVideo logo, only displayed in the callback. Do not use the setting. Otherwise, the SDK applies the logo based on + * kNERtcVideoProfileStandard.
When the remote client sends the SEI in the audio-only state, the local client receives the + * message returned by the onUserVideoStart callback from the remote client. The maxProfile parameter is + * kNERtcVideoProfileFake, which indicates that the remote client sends a 16*16 FakeVideo. At this time, if the local client + * needs to receive the remote SEI, you only need to subscribe to the remote video, without setting the remote canvas. + * @endif + * @if Chinese + * FakeVideo标识，仅在回调中显示。请勿主动设置，否则 SDK 会按照 STANDARD 处理。 + *
当远端在纯音频状态发送 SEI 时，本端将会收到远端的onUserVideoStart回调，其中 max_profile 参数为 kNERtcVideoProfileFake + * ， 表示对端发送 16*16 的 FakeVideo，此时如果本端需要接收远端的SEI信息，只需要订阅一下远端的视频即可，无须设置远端画布。 + * @endif + */ + kNERtcVideoProfileFake = 6, +} nertc_video_profile_type; + +/** + * @if English + * The video stream type. + * @endif + * @if Chinese + * 视频流类型。 + * @note 大流的分辨率及参数配置高，小流的分辨率及参数配置低。 + * @endif + */ +typedef enum { + /** + * @if English + * The default high-resolution stream. + * @endif + * @if Chinese + * 默认大流 + * @endif + */ + kNERtcRemoteVideoStreamTypeHigh = 0, + /** + * @if English + * The low-resolution stream + * @endif + * @if Chinese + * 小流 + * @endif + */ + kNERtcRemoteVideoStreamTypeLow = 1, + /** + * @if English + * Unsubscribed. + * @endif + * @if Chinese + * 不订阅 + * @endif + */ + kNERtcRemoteVideoStreamTypeNone = 2, +} nertc_remote_video_stream_type; + +/** + * @if English + * Audio device type. + * @endif + * @if Chinese + * 音频设备类型。 + * @endif + */ +typedef enum { + /** + * @if English + * Unknown audio device. + * @endif + * @if Chinese + * 未知音频设备 + * @endif + */ + kNERtcAudioDeviceUnknown = 0, + /** + * @if English + * Audio capture device. + * @endif + * @if Chinese + * 音频采集设备 + * @endif + */ + kNERtcAudioDeviceRecord, + /** + * @if English + * Audio playback device. + * @endif + * @if Chinese + * 音频播放设备 + * @endif + */ + kNERtcAudioDevicePlayout, +} nertc_audio_device_type; + +/** + * @if English + * Audio device status types. + * @endif + * @if Chinese + * 音频设备类型状态。 + * @endif + */ +typedef enum { + /** + * @if English + * The audio device is activated. + * @endif + * @if Chinese + * 音频设备已激活 + * @endif + */ + kNERtcAudioDeviceActive = 0, + /** + * @if English + * The audio device is not activated. + * @endif + * @if Chinese + * 音频设备未激活 + * @endif + */ + kNERtcAudioDeviceUnactive, +} nertc_audio_device_state; + +/** + * @if English + * Audio device types. + *@endif + *@if Chinese + * 音频设备连接类型。 + * @endif + */ +typedef enum { + /** + * @if English + * Unknown device. + * @endif + * @if Chinese + * 未知设备 + * @endif + */ + kNERtcAudioDeviceTransportTypeUnknown = 0, + /** + * @if English + * Bluetooth device. + * @endif + * @if Chinese + * 蓝牙设备 + * @endif + */ + kNERtcAudioDeviceTransportTypeBluetooth = 1, + /** + * @if English + * Bluetooth stereo device. + * @endif + * @if Chinese + * 蓝牙立体声设备 + * @endif + */ + kNERtcAudioDeviceTransportTypeBluetoothA2DP = 2, + /** + * @if English + * Bluetooth low energy device. + * @endif + * @if Chinese + * 蓝牙低功耗设备 + * @endif + */ + kNERtcAudioDeviceTransportTypeBluetoothLE = 3, + /** + * @if English + * USB device. + * @endif + * @if Chinese + * USB设备 + * @endif + */ + kNERtcAudioDeviceTransportTypeUSB = 4, + /** + * @if English + * HDMI device. + * @endif + * @if Chinese + * HDMI设备 + * @endif + */ + kNERtcAudioDeviceTransportTypeHDMI = 5, + /** + * @if English + * Built-in device. + * @endif + * @if Chinese + * 内置设备 + * @endif + */ + kNERtcAudioDeviceTransportTypeBuiltIn = 6, + /** + * @if English + * Thunderbolt interface device. + * @endif + * @if Chinese + * 雷电接口设备 + * @endif + */ + kNERtcAudioDeviceTransportTypeThunderbolt = 7, + /** + * @if English + * AirPlay device. + * @endif + * @if Chinese + * AirPlay设备 + * @endif + */ + kNERtcAudioDeviceTransportTypeAirPlay = 8, + /** + * @if English + * Virtual device. + * @endif + * @if Chinese + * 虚拟设备 + * @endif + */ + kNERtcAudioDeviceTransportTypeVirtual = 9, + /** + * @if English + * Other devices. + * @endif + * @if Chinese + * 其他设备 + * @endif + */ + kNERtcAudioDeviceTransportTypeOther = 10, +} nertc_audio_device_transport_type; + +/** + * @if English + * Camera device type. + * @endif + * @if Chinese + * 摄像头设备链接类型。 + * @endif + */ +typedef enum { + /** + * @if English + * Unknown device. + * @endif + * @if Chinese + * 未知设备 + * @endif + */ + kNERtcVideoDeviceTransportTypeUnknown = 0, + /** + * @if English + * USB设备 + * @endif + * @if Chinese + * USB device. + * @endif + */ + kNERtcVideoDeviceTransportTypeUSB = 1, + /** + * @if English + * Virtual device. + * @endif + * @if Chinese + * 虚拟设备 + * @endif + */ + kNERtcVideoDeviceTransportTypeVirtual = 2, + /** + * @if English + * Other device. + * @endif + * @if Chinese + * 其他设备 + * @endif + */ + kNERtcVideoDeviceTransportTypeOther = 3, +} nertc_video_device_transport_type; + +/** + * @if English + * Device details. + * @endif + * @if Chinese + * 设备详细信息。 + * @endif + */ +struct nertc_device_info { + /** + * @if English + * Device ID + * @endif + * @if Chinese + * 设备ID + * @endif + */ + char device_id[kNERtcMaxDeviceIDLength]; + /** + * @if English + * Device name + * @endif + * @if Chinese + * 设备名称 + * @endif + */ + char device_name[kNERtcMaxDeviceNameLength]; + /** + * @if English + * Device types, including NERtcAudioDeviceTransportType and NERtcVideoDeviceTransportType + * @endif + * @if Chinese + * 设备链接类型，分别指向NERtcAudioDeviceTransportType及NERtcVideoDeviceTransportType + * @endif + */ + int transport_type; + /** + * @if English + * Determines whether it is a non-recommended device + * @endif + * @if Chinese + * 是否是不推荐设备 + * @endif + */ + bool suspected_unavailable; + /** + * @if English + * Determines whether it is the system default device + * @endif + * @if Chinese + * 是否是系统默认设备 + * @endif + */ + bool system_default_device; +}; + +/** + * @if English + * Video device types. + * @endif + * @if Chinese + * 视频设备类型。 + * @endif + */ +typedef enum { + /** + * @if English + * Unknown video device. + * @endif + * @if Chinese + * Video capture device. + * @endif + */ + kNERtcVideoDeviceUnknown = 0, + /** + * @if English + * Video capture device. + * @endif + * @if Chinese + * 视频采集设备 + * @endif + */ + kNERtcVideoDeviceCapture, +} nertc_video_device_type; + +/** + * @if English + * Video device status types. + * @endif + * @if Chinese + * 视频设备类型状态。 + * @endif + */ +typedef enum { + /** + * @if English + * The video device is added. + * @endif + * @if Chinese + * 视频设备已添加 + * @endif + */ + kNERtcVideoDeviceAdded = 0, + /** + * @if English + * The video device is removed. + * @endif + * @if Chinese + * 视频设备已拔除 + * @endif + */ + kNERtcVideoDeviceRemoved, +} nertc_video_device_state; + +/** + * @if English + * @enum NERtcVideoScalingMode Set the video scaling mode. + * @endif + * @if Chinese + * @enum NERtcVideoScalingMode 设置视频缩放模式。 + * @endif + */ +typedef enum { + /** + * @if English + * 0: adaptive to the video. The video size is scaled proportionally. All video content is prioritized for display. If the + * video size does not match the display window size, the unfilled area of the window is be filled with the background color. + * @endif + * @if Chinese + * 0：适应视频，视频尺寸等比缩放。优先保证视频内容全部显示。若视频尺寸与显示视窗尺寸不一致，视窗未被填满的区域填充背景色。 + * @endif + */ + kNERtcVideoScaleFit = 0, + /** + * @if English + * 1: The video size is scaled non-proportionally. Ensure that all video content is displayed and the window is filled. + * @endif + * @if Chinese + * 1：视频尺寸非等比缩放。保证视频内容全部显示，且填满视窗。 + * @endif + */ + kNERtcVideoScaleFullFill = 1, + /** + * @if English + * 2: adaptive to the area. The video size is scaled proportionally. Ensure that all areas are filled, and the extra part of + * the video will be cropped. + * @endif + * @if Chinese + * 2：适应区域，视频尺寸等比缩放。保证所有区域被填满，视频超出部分会被裁剪。 + * @endif + */ + kNERtcVideoScaleCropFill = 2, +} nertc_video_scaling_mode; + +/** + * @if English + * @enum NERtcVideoMirrorMode Video mirror mode. + * @endif + * @if Chinese + * @enum NERtcVideoMirrorMode 视频镜像模式。 + * @endif + */ +typedef enum { + /** + * @if English + * 0: The mirror mode is enabled in Windows and macOS SDKs. + * @endif + * @if Chinese + * 0: Windows/macOS SDK 启用镜像模式。 + * @endif + */ + kNERtcVideoMirrorModeAuto = 0, + /** + * @if English + * 1: Enables mirror mode. + * @endif + * @if Chinese + * 1: 启用镜像模式。 + * @endif + */ + kNERtcVideoMirrorModeEnabled = 1, + /** + * @if English + * 2: Disables mirroring mode (default). + * @endif + * @if Chinese + * 2: （默认）关闭镜像模式。 + * @endif + */ + kNERtcVideoMirrorModeDisabled = 2, +} nertc_video_mirror_mode; + +/** + * @if English + * @enum NERtcVideoOutputOrientationMode The video orientation mode. + * @endif + * @if Chinese + * @enum NERtcVideoOutputOrientationMode 视频旋转的方向模式。 + * @endif + */ +typedef enum { + + /** + * @if English + * (default) The direction of the video output by the SDK in this mode is consistent with the direction of the captured video. + * The receiver rotates the video based on the received video rotation information.
This mode is suitable for scenarios + * where the receiver can adjust the video direction. + * - If the captured video is in landscape mode, the output video is also in landscape mode. + * - If the captured video is in portrait mode, the output video is also in portrait mode. + * @endif + * @if Chinese + * （默认）该模式下 SDK 输出的视频方向与采集到的视频方向一致。接收端会根据收到的视频旋转信息对视频进行旋转。 + *
该模式适用于接收端可以调整视频方向的场景。 + * - 如果采集的视频是横屏模式，则输出的视频也是横屏模式。 + * - 如果采集的视频是竖屏模式，则输出的视频也是竖屏模式。 + * @endif + */ + kNERtcVideoOutputOrientationModeAdaptative = 0, + + /** + * @if English + * In this mode, the SDK always outputs videos in landscape mode. If the captured video is in portrait mode, the video encoder + * crops the video.
This mode is suitable for scenes where the receiver cannot adjust the video direction, such as CDN + * relayed streaming. + * @endif + * @if Chinese + * 该模式下 SDK 固定输出横屏模式的视频。如果采集到的视频是竖屏模式，则视频编码器会对其进行裁剪。 + *
该模式适用于接收端无法调整视频方向的场景，例如旁路推流。 + * @endif + */ + kNERtcVideoOutputOrientationModeFixedLandscape = 1, + + /** + * @if English + * In this mode, the SDK always outputs videos in portrait mode. If the captured video is in landscape mode, the video encoder + * crops the video.
This mode is suitable for scenes where the receiver cannot adjust the video direction, such as CDN + * relayed streaming. + * @endif + * @if Chinese + * 该模式下 SDK 固定输出竖屏模式的视频，如果采集到的视频是横屏模式，则视频编码器会对其进行裁剪。 + *
该模式适用于接收端无法调整视频方向的场景，例如旁路推流。 + * @endif + */ + kNERtcVideoOutputOrientationModeFixedPortrait = 2, + +} nertc_video_orientation_mode; +/** + * @if English + * The state of network connection + * @endif + * @if Chinese + * 连接状态 + * @endif + */ +typedef enum { + /** + * @if English + * The client is disconnected. + * @endif + * @if Chinese + * 未加入房间。 + * @endif + */ + kNERtcConnectionStateDisconnected = 1, + /** + * @if English + * The client is connecting to the room server. + * @endif + * @if Chinese + * 正在加入房间。 + * @endif + */ + kNERtcConnectionStateConnecting = 2, + /** + * @if English + * The client is connected to the room server. + * @endif + * @if Chinese + * 加入房间成功。 + * @endif + */ + kNERtcConnectionStateConnected = 3, + /** + * @if English + * The client is reconnecting to the room server. + * @endif + * @if Chinese + * 正在尝试重新加入房间。 + * @endif + */ + kNERtcConnectionStateReconnecting = 4, + /** + * @if English + * The client fails to connect to the room server. + * @endif + * @if Chinese + * 加入房间失败。 + * @endif + */ + kNERtcConnectionStateFailed = 5, +} nertc_connection_state_type; + +/** + * @if English + * The reason for the connection state change. + * @endif + * @if Chinese + * 连接状态变更原因 + * @endif + */ +typedef enum { + /** + * @if English + * kNERtcConnectionStateDisconnected The client leaves the room. + * @endif + * @if Chinese + * kNERtcConnectionStateDisconnected 离开房间 + * @endif + */ + kNERtcReasonConnectionChangedLeaveChannel = 1, + /** + * @if English + * kNERtcConnectionStateDisconnected The room is closed. + * @endif + * @if Chinese + * kNERtcConnectionStateDisconnected 房间被关闭 + * @endif + */ + kNERtcReasonConnectionChangedChannelClosed = 2, + /** + * @if English + * kNERtcConnectionStateDisconnected The user is removed from the room. + * @endif + * @if Chinese + * kNERtcConnectionStateDisconnected 用户被踢 + * @endif + */ + kNERtcReasonConnectionChangedBeKicked = 3, + /** + * @if English + * kNERtcConnectionStateDisconnected The service times out. + * @endif + * @if Chinese + * kNERtcConnectionStateDisconnected 服务超时 + * @endif + */ + kNERtcReasonConnectionChangedTimeOut = 4, + /** + * @if English + * kNERtcConnectionStateConnecting The user joins the room. + * @endif + * @if Chinese + * kNERtcConnectionStateConnected 加入房间 + * @endif + */ + kNERtcReasonConnectionChangedJoinChannel = 5, + /** + * @if English + * kNERtcConnectionStateConnected The user has joined the room. + * @endif + * @if Chinese + * kNERtcConnectionStateConnected 加入房间成功 + * @endif + */ + kNERtcReasonConnectionChangedJoinSucceed = 6, + /** + * @if English + * kNERtcConnectionStateConnected The user rejoins the room successfully (reconnection). + * @endif + * @if Chinese + * kNERtcConnectionStateConnected 重新加入房间成功（重连） + * @endif + */ + kNERtcReasonConnectionChangedReJoinSucceed = 7, + /** + * @if English + * kNERtcConnectionStateReconnecting The media stream gets disconnected. + * @endif + * @if Chinese + * kNERtcConnectionStateReconnecting 媒体连接断开 + * @endif + */ + kNERtcReasonConnectionChangedMediaConnectionDisconnected = 8, + /** + * @if English + * kNERtcConnectionStateReconnecting The signaling channel gets disconnected. + * @endif + * @if Chinese + * kNERtcConnectionStateReconnecting 信令连接断开 + * @endif + */ + kNERtcReasonConnectionChangedSignalDisconnected = 9, + /** + * @if English + * kNERtcConnectionStateFailed The request to join the room fails. + * @endif + * @if Chinese + * kNERtcConnectionStateFailed 请求房间失败 + * @endif + */ + kNERtcReasonConnectionChangedRequestChannelFailed = 10, + /** + * @if English + * kNERtcConnectionStateFailed The user fails to join the room. + * @endif + * @if Chinese + * kNERtcConnectionStateFailed 加入房间失败 + * @endif + */ + kNERtcReasonConnectionChangedJoinChannelFailed = 11, + /** + * @if English + * kNERtcConnectionStateReconnecting The server IP is reallocated. + * @endif + * @if Chinese + * kNERtcConnectionStateReconnecting 重新分配了服务端IP + * @endif + */ + kNERtcReasonConnectionChangedReDispatch = 12, + /** + * @if English + * Start connecting to server using the cloud proxy. + * @endif + * @if Chinese + * 开始使用云代理进行连接。 + * @endif + */ + kNERtcReasonConnectionChangedSettingProxyServer = 13 +} nertc_reason_connection_changed_type; + +/** + * @if English + * Audio volume information. An array that contains the user ID and volume information of each speaker. + * @endif + * @if Chinese + * 声音音量信息。一个数组，包含每个说话者的用户 ID 和音量信息。 + * @endif + */ +struct nertc_audio_volume_info { + /** + * @if English + * The user ID of the speaker. If the returned uid is 0, the user refers to the local user by default. + * @endif + * @if Chinese + * 说话者的用户 ID。如果返回的 uid 为 0，则默认为本地用户。 + * @endif + */ + nertc_uid_t uid; + /** + * @if English + * The speaker's volume, the value range is from 0 (lowest) to 100 (highest). + * @endif + * @if Chinese + * 说话者的音量，范围为 0（最低）- 100（最高）。 + * @endif + */ + unsigned int volume; + /** + * @if Chinese + * 远端用户音频辅流的音量，取值范围为 [0,100] 。 + *
如果 sub_stream_volume 为 0，表示该用户未发布音频辅流或音频辅流没有音量。 + * @endif + */ + unsigned int sub_stream_volume; +}; + +/** + * @if English + * Stats related to calls. + * @endif + * @if Chinese + * 通话相关的统计信息。 + * @endif + */ +struct nertc_stats { + /** + * @if English + * The CPU usage occupied by the app (%). + * @endif + * @if Chinese + * 当前 App 的 CPU 使用率 (%)。 + * @endif + */ + uint32_t cpu_app_usage; + /** + * @if English + * The CPU idle rate of the current system (%). + * @endif + * @if Chinese + * 当前系统的 CPU 空闲率 (%)。 + * @endif + */ + uint32_t cpu_idle_usage; + /** + * @if English + * The current system CPU usage (%). + * @endif + * @if Chinese + * 当前系统的 CPU 使用率 (%)。 + * @endif + */ + uint32_t cpu_total_usage; + /** + * @if English + * The current memory usage occupied by the app (%). + * @endif + * @if Chinese + * 当前App的内存使用率 (%)。 + * @endif + */ + uint32_t memory_app_usage; + /** + * @if English + * The current system memory usage (%). + * @endif + * @if Chinese + * 当前系统的内存使用率 (%)。 + * @endif + */ + uint32_t memory_total_usage; + /** + * @if English + * The current memory used by the app (KB). + * @endif + * @if Chinese + * 当前App的内存使用量 (KB)。 + * @endif + */ + uint32_t memory_app_kbytes; + /** + * @if English + * Call duration in seconds. + * @endif + * @if Chinese + * 通话时长（秒）。 + * @endif + */ + int total_duration; + /** + * @if English + * The number of bytes sent. This is the cumulative value. (bytes) + * @endif + * @if Chinese + * 发送字节数，累计值。(bytes) + * @endif + */ + uint64_t tx_bytes; + /** + * @if English + * The number of bytes received. This is the cumulative value. (bytes) + * @endif + * @if Chinese + * 接收字节数，累计值。(bytes) + * @endif + */ + uint64_t rx_bytes; + /** + * @if English + * The number of audio bytes sent. This is the cumulative value. (bytes) + * @endif + * @if Chinese + * 音频发送字节数，累计值。(bytes) + * @endif + */ + uint64_t tx_audio_bytes; + /** + * @if English + * The number of video bytes sent. This is the cumulative value. (bytes) + * @endif + * @if Chinese + * 视频发送字节数，累计值。(bytes) + * @endif + */ + uint64_t tx_video_bytes; + /** + * @if English + * The number of audio bytes received. This is the cumulative value. (bytes) + * @endif + * @if Chinese + * 音频接收字节数，累计值。(bytes) + * @endif + */ + uint64_t rx_audio_bytes; + /** + * @if English + * The number of video bytes received. This is the cumulative value. (bytes) + * @endif + * @if Chinese + * 视频接收字节数，累计值。(bytes) + * @endif + */ + uint64_t rx_video_bytes; + /** + * @if English + * Audio bitrate for publishing. (kbps) + * @endif + * @if Chinese + * 音频发送码率。(kbps) + * @endif + */ + int tx_audio_kbitrate; + /** + * @if English + * Audio bitrate for subscribed streams. (kbps) + * @endif + * @if Chinese + * 音频接收码率。(kbps) + * @endif + */ + int rx_audio_kbitrate; + /** + * @if English + * Video bitrate for publishing. (kbps) + * @endif + * @if Chinese + * 视频发送码率。(kbps) + * @endif + */ + int tx_video_kbitrate; + /** + * @if English + * Video bitrate for subscribed streams. (kbps) + * @endif + * @if Chinese + * 视频接收码率。(kbps) + * @endif + */ + int rx_video_kbitrate; + /** + * @if English + * Average uplink round trip time. (ms) + * @endif + * @if Chinese + * 上行平均往返时延rtt(ms) + * @endif + */ + int up_rtt; + /** + * @if English + * Average downlink round-trip time. (ms) + * @endif + * @if Chinese + * 下行平均往返时延rtt(ms) + * @endif + */ + int down_rtt; + /** + * @if English + * The actual uplink packet loss rate of the local audio stream. (%) + * @endif + * @if Chinese + * 本地上行音频实际丢包率。(%) + * @endif + */ + int tx_audio_packet_loss_rate; + /** + * @if English + * The actual uplink packet loss rate of the local video stream. (%) + * @endif + * @if Chinese + * 本地上行视频实际丢包率。(%) + * @endif + */ + int tx_video_packet_loss_rate; + /** + * @if English + * The actual number of lost packets for local upstream audio. + * @endif + * @if Chinese + * 本地上行音频实际丢包数。 + * @endif + */ + int tx_audio_packet_loss_sum; + /** + * @if English + * Actual number of lost packets for local upstream video. + * @endif + * @if Chinese + * 本地上行视频实际丢包数。 + * @endif + */ + int tx_video_packet_loss_sum; + /** + * @if English + * Local upstream audio jitter calculation. (ms) + * @endif + * @if Chinese + * 本地上行音频抖动计算。(ms) + * @endif + */ + int tx_audio_jitter; + /** + * @if English + * Local uplink video jitter calculation. (ms) + * @endif + * @if Chinese + * 本地上行视频抖动计算。(ms) + * @endif + */ + int tx_video_jitter; + /** + * @if English + * Actual packet loss of local downlink audio stream. (%) + * @endif + * @if Chinese + * 本地下行音频实际丢包率。(%) + * @endif + */ + int rx_audio_packet_loss_rate; + /** + * @if English + * Actual local downstream video packet loss rate. (%) + * @endif + * @if Chinese + * 本地下行视频实际丢包率。(%) + * @endif + */ + int rx_video_packet_loss_rate; + /** + * @if English + * Actual number of lost packets for local downstream audio. + * @endif + * @if Chinese + * 本地下行音频实际丢包数。 + * @endif + */ + int rx_audio_packet_loss_sum; + /** + * @if English + * Actual number of lost packets for local downstream video. + * @endif + * @if Chinese + * 本地下行视频实际丢包数。 + * @endif + */ + int rx_video_packet_loss_sum; + /** + * @if English + * Local downstream audio jitter calculation. (ms) + * @endif + * @if Chinese + * 本地下行音频抖动计算。(ms) + * @endif + */ + int rx_audio_jitter; + /** + * @if English + * Local downstream video jitter calculation. (ms) + * @endif + * @if Chinese + * 本地下行视频抖动计算。(ms) + * @endif + */ + int rx_video_jitter; +}; + +/** + * @if English + * Stats of each local video stream. + * @endif + * @if Chinese + * 本地视频单条流上传统计信息。 + * @endif + */ +struct nertc_video_layer_send_stats { + /** + * @if English + * Stream type: 1. mainstream. 2. substream. + * @endif + * @if Chinese + * 流类型： 1、主流，2、辅流。 + * @endif + */ + int layer_type; + /** + * @if English + * Video stream width (pixels). + * @endif + * @if Chinese + * 视频流宽（像素）。 + * @endif + */ + int width; + /** + * @if English + * Video stream height (pixels). + * @endif + * @if Chinese + * 视频流高（像素）。 + * @endif + */ + int height; + /** + * @if English + * @endif + * @if Chinese + * 视频采集宽（像素）。 + * @endif + */ + int capture_width; + /** + * @if English + * @endif + * @if Chinese + * 视频采集高（像素）。 + * @endif + */ + int capture_height; + /** + * @if English + * Video capture frame rate. + * @endif + * @if Chinese + * 视频采集帧率。 + * @endif + */ + int capture_frame_rate; + /** + * @if English + * Video rendering frame rate. + * @endif + * @if Chinese + * 视频渲染帧率。 + * @endif + */ + int render_frame_rate; + /** + * @if English + * Encoding frame rate. + * @endif + * @if Chinese + * 编码帧率。 + * @endif + */ + int encoder_frame_rate; + /** + * @if English + * Publishing frame rate. + * @endif + * @if Chinese + * 发送帧率。 + * @endif + */ + int sent_frame_rate; + /** + * @if English + * Publishing bitrate(kbps). + * @endif + * @if Chinese + * 发送码率(Kbps)。 + * @endif + */ + int sent_bitrate; + /** + * @if English + * Encoder expected bitrate (kbps). + * @endif + * @if Chinese + * 编码器目标码率(Kbps)。 + * @endif + */ + int target_bitrate; + /** + * @if English + * Encoder actual bitrate (kbps). + * @endif + * @if Chinese + * 编码器实际编码码率(Kbps)。 + * @endif + */ + int encoder_bitrate; + /** + * @if English + * The name of the video encoder. + * @endif + * @if Chinese + * 视频编码器名字。 + * @endif + */ + char codec_name[kNERtcMaxDeviceNameLength]; +}; + +/** + * @if English + * The stats of the uplink local video stream. + * @endif + * @if Chinese + * 本地视频流上传统计信息。 + * @endif + */ +struct nertc_video_send_stats { + /** + * @if English + * Video stream information array. + * @endif + * @if Chinese + * 视频流信息数组。 + * @endif + */ + nertc_video_layer_send_stats* video_layers_list; + /** + * @if English + * The number of video streams. + * @endif + * @if Chinese + * 视频流条数。 + * @endif + */ + int video_layers_count; +}; + +/** + * @if English + * The stats of each remote video stream. + * @endif + * @if Chinese + * 远端视频单条流的统计信息。 + * @endif + */ +struct nertc_video_layer_recv_stats { + /** + * @if English + * Stream type: 1. mainstream. 2. substream. + * @endif + * @if Chinese + * 流类型： 1、主流，2、辅流。 + * @endif + */ + int layer_type; + /** + * @if English + * Video stream width (pixels). + * @endif + * @if Chinese + * 视频流宽（像素）。 + * @endif + */ + int width; + /** + * @if English + * Video stream height (pixels). + * @endif + * @if Chinese + * 视频流高（像素）。 + * @endif + */ + int height; + /** + * @if English + * The bitrate of the received stream (kbps). + * @endif + * @if Chinese + * 接收到的码率(Kbps)。 + * @endif + */ + int received_bitrate; + /** + * @if English + * The frame rate of the received stream (fps). + * @endif + * @if Chinese + * 接收到的帧率 (fps)。 + * @endif + */ + int received_frame_rate; + /** + * @if English + * Decoding frame rate (fps). + * @endif + * @if Chinese + * 解码帧率 (fps)。 + * @endif + */ + int decoder_frame_rate; + /** + * @if English + * Rendering frame rate (fps). + * @endif + * @if Chinese + * 渲染帧率 (fps)。 + * @endif + */ + int render_frame_rate; + /** + * @if English + * Downlink packet loss rate (%). + * @endif + * @if Chinese + * 下行丢包率(%)。 + * @endif + */ + int packet_loss_rate; + /** + * @if English + * The downlink video freeze cumulative time (ms). + * @endif + * @if Chinese + * 用户的下行视频卡顿累计时长(ms)。 + * @endif + */ + int total_frozen_time; + /** + * @if English + * The average freeze rate of the user's downlink video stream (%). + * @endif + * @if Chinese + * 用户的下行视频平均卡顿率(%)。 + * @endif + */ + int frozen_rate; + /** + * @if English + * The codec name. + * @endif + * @if Chinese + * 视频解码器名字。 + * @endif + */ + char codec_name[kNERtcMaxDeviceNameLength]; +}; + +/** + * @if English + * Remote video stream stats. + * @endif + * @if Chinese + * 远端视频流的统计信息。 + * @endif + */ +struct nertc_video_recv_stats { + /** + * @if English + * The user ID used to identify the video stream. + * @endif + * @if Chinese + * 用户 ID，指定是哪个用户的视频流。 + * @endif + */ + nertc_uid_t uid; + /** + * @if English + * Video stream information array. + * @endif + * @if Chinese + * 视频流信息数组。 + * @endif + */ + nertc_video_layer_recv_stats* video_layers_list; + /** + * @if English + * The number of video streams. + * @endif + * @if Chinese + * 视频流条数。 + * @endif + */ + int video_layers_count; +}; + +/** + * @if English + * Audio stream type. + * @endif + * @if Chinese + * 音频流类型。 + * @endif + */ +enum nertc_audio_stream_type{ + /** + * @if English + * Main stream. + * @endif + * @if Chinese + * 主流。 + * @endif + */ + kNERtcAudioStreamTypeMain = 0, + + /** + * @if English + * Substream. + * @endif + * @if Chinese + * 辅流。 + * @endif + */ + kNERtcAudioStreamTypeSub = 1, +}; +struct nertc_audio_layer_send_stats { + /** + * @if English + * Audio stream tyepe. + * @endif + * @if Chinese + * 音频流通道类型。 + * @endif + */ + nertc_audio_stream_type stream_type; + /** + * @if English + * The number of channels currently collected. + * @endif + * @if Chinese + * 当前采集声道数。 + * @endif + */ + int num_channels; + /** + * @if English + * The sample rate of local uplink audio stream. + * @endif + * @if Chinese + * 本地上行音频采样率。 + * @endif + */ + int sent_sample_rate; + /** + * @if English + * Publishing bitrate after last report (kbps). + * @endif + * @if Chinese + * （上次统计后）发送码率(Kbps)。 + * @endif + */ + int sent_bitrate; + /** + * @if English + * Audio packet loss rate in a specific time (%). + * @endif + * @if Chinese + * 特定时间内的音频丢包率 (%)。 + * @endif + */ + int audio_loss_rate; + /** + * @if English + * Round trip time. + * @endif + * @if Chinese + * RTT。 + * @endif + */ + int64_t rtt; + /** + * @if English + * Volume range: 0 (lowest) to 100 (highest). + * @endif + * @if Chinese + * 音量，范围为 0（最低）- 100（最高）。 + * @endif + */ + unsigned int volume; + /** + * @if English + * @endif + * @if Chinese + * 采集音量，范围为 0（最低）- 100（最高）。 + * @endif + */ + unsigned int cap_volume; +}; +/** + * @if English + * The local audio stream stats. + * @endif + * @if Chinese + * 本地音频流上传统计信息。 + * @endif + */ +struct nertc_audio_send_stats { + /** + * @if English + * Audio stream information array. + * @endif + * @if Chinese + * 音频流信息数组。 + * @endif + */ + nertc_audio_layer_send_stats* audio_layers_list; + /** + * @if English + * The number of audio streams. + * @endif + * @if Chinese + * 音频流条数。 + * @endif + */ + int audio_layers_count; +}; + +/** + * @if English + * The stats of each remote audio stream. + * @endif + * @if Chinese + * 远端用户单条音频流统计。 + * @endif + */ +struct nertc_audio_layer_recv_stats { + /** + * @if English + * Audio stream type. + * @endif + * @if Chinese + * 音频频流通道类型。 + * @endif + */ + nertc_audio_stream_type stream_type; + /** + * @if English + * The bitrate of the received audio stream after the last report (kbps). + * @endif + * @if Chinese + * （上次统计后）接收到的码率(Kbps)。 + * @endif + */ + int received_bitrate; + /** + * @if English + * The user's downlink audio freeze cumulative time (ms). + * @endif + * @if Chinese + * 用户的下行音频卡顿累计时长(ms)。 + * @endif + */ + int total_frozen_time; + /** + * @if English + * The user's downstream audio average freeze rate (%). + * @endif + * @if Chinese + * 用户的下行音频平均卡顿率(%)。 + * @endif + */ + int frozen_rate; + /** + * @if English + * Audio packet loss rate in a specific time (%). + * @endif + * @if Chinese + * 特定时间内的音频丢包率 (%)。 + * @endif + */ + int audio_loss_rate; + /** + * @if English + * Volume range: 0 (lowest) to 100 (highest). + * @endif + * @if Chinese + * 音量，范围为 0（最低）- 100（最高）。 + * @endif + */ + unsigned int volume; +}; +/** + * @if English + * The stats of the audio stream from a remote user. + * @endif + * @if Chinese + * 远端用户的音频统计。 + * @endif + */ +struct nertc_audio_recv_stats { + /** + * @if English + * The user ID used to identify the audio stream. + * @endif + * @if Chinese + * 用户 ID，指定是哪个用户的音频流。 + * @endif + */ + nertc_uid_t uid; + /** + * @if English + * Audio stream information array. + * @endif + * @if Chinese + * 音频流信息数组。 + * @endif + */ + nertc_audio_layer_recv_stats* audio_layers_list; + /** + * @if English + * The number of audio streams. + * @endif + * @if Chinese + * 音频流条数。 + * @endif + */ + int audio_layers_count; +}; + +/** + * @if English + * @enum NERtcNetworkQualityType Network quality type. + * @endif + * @if Chinese + * @enum NERtcNetworkQualityType 网络质量类型。 + * @endif + */ +typedef enum { + /** + * @if English + * 0: Unknown network quality. + * @endif + * @if Chinese + * 0: 网络质量未知。 + * @endif + */ + kNERtcNetworkQualityUnknown = 0, + /** + * @if English + * 1: Excellent network quality. + * @endif + * @if Chinese + * 1: 网络质量极好。 + * @endif + */ + kNERtcNetworkQualityExcellent = 1, + /** + * @if English + * 2: Good network quality is close to the excellent level but has the bitrate is lower an excellent network. + * @endif + * @if Chinese + * 2: 用户主观感觉和 `kNERtcNetworkQualityExcellent` 类似，但码率可能略低于 `kNERtcNetworkQualityExcellent`。 + * @endif + */ + kNERtcNetworkQualityGood = 2, + /** + * @if English + * 3: Poor network does not affect communication. + * @endif + * @if Chinese + * 3: 用户主观感受有瑕疵但不影响沟通。 + * @endif + */ + kNERtcNetworkQualityPoor = 3, + /** + * @if English + * 4: Users can communicate with each other without smoothness. + * @endif + * @if Chinese + * 4: 勉强能沟通但不顺畅。 + * @endif + */ + kNERtcNetworkQualityBad = 4, + /** + * @if English + * 5: The network quality is very poor. Basically users are unable to communicate. + * @endif + * @if Chinese + * 5: 网络质量非常差，基本不能沟通。 + * @endif + */ + kNERtcNetworkQualityVeryBad = 5, + /** + * @if English + * 6: Users are unable to communicate with each other. + * @endif + * @if Chinese + * 6: 完全无法沟通。 + * @endif + */ + kNERtcNetworkQualityDown = 6, +} nertc_network_quality_type; + +/** + * @if English + * Network quality stats. + * @endif + * @if Chinese + * 网络质量统计信息。 + * @endif + */ +struct nertc_network_quality_info { + /** + * @if English + * The user ID used to identify the network quality stats. + * @endif + * @if Chinese + * 用户 ID，指定是哪个用户的网络质量统计。 + * @endif + */ + nertc_uid_t uid; + /** + * @if English + * The uplink network quality. For more information, see #NERtcNetworkQualityType. + * @endif + * @if Chinese + * 该用户的上行网络质量，详见 #NERtcNetworkQualityType. + * @endif + */ + nertc_network_quality_type tx_quality; + /** + * @if English + * The downlink network quality. For more information, see #NERtcNetworkQualityType. + * @endif + * @if Chinese + * 该用户的下行网络质量，详见 #NERtcNetworkQualityType. + * @endif + */ + nertc_network_quality_type rx_quality; +}; + +/** + * @if English + * @enum NERtcVideoCropMode Video cropping mode. + * @endif + * @if Chinese + * @enum NERtcVideoCropMode 视频画面裁剪模式。 + * @endif + */ +typedef enum { + /** + * @if English + * Device Default + * @endif + * @if Chinese + * 设备默认裁剪模式。 + * @endif + */ + kNERtcVideoCropModeDefault = 0, + /** + * @if English + * 16:9 + * @endif + * @if Chinese + * 16:9 + * @endif + */ + kNERtcVideoCropMode16x9 = 1, + /** + * @if English + * 4:3 + * @endif + * @if Chinese + * 4:3 + * @endif + */ + kNERtcVideoCropMode4x3 = 2, + /** + * @if English + * 1:1 + * @endif + * @if Chinese + * 1:1 + * @endif + */ + kNERtcVideoCropMode1x1 = 3, +} nertc_video_crop_mode; + +/** + * @if English + * @enum NERtcVideoFramerateType Video frame rate. + * @endif + * @if Chinese + * @enum NERtcVideoFramerateType 视频帧率。 + * @endif + */ +typedef enum { + /** + * @if English + * default frame rate + * @endif + * @if Chinese + * 默认帧率 + * @endif + */ + kNERtcVideoFramerateFpsDefault = 0, + /** + * @if English + * 7 frames per second + * @endif + * @if Chinese + * 7帧每秒 + * @endif + */ + kNERtcVideoFramerateFps_7 = 7, + /** + * @if English + * 10 frames per second + * @endif + * @if Chinese + * 10帧每秒 + * @endif + */ + kNERtcVideoFramerateFps_10 = 10, + /** + * @if English + * 15 frames per second + * @endif + * @if Chinese + * 15帧每秒 + * @endif + */ + kNERtcVideoFramerateFps_15 = 15, + /** + * @if English + * 24 frames per second + * @endif + * @if Chinese + * 24帧每秒 + * @endif + */ + kNERtcVideoFramerateFps_24 = 24, + /** + * @if English + * 30 frames per second + * @endif + * @if Chinese + * 30帧每秒 + * @endif + */ + kNERtcVideoFramerateFps_30 = 30, + /** + * @if English + * 60 frames per second + * @endif + * @if Chinese + * 60帧每秒 + * @endif + */ + kNERtcVideoFramerateFps_60 = 60, +} nertc_video_framerate_type; + +/** + * @if English + * @enum NERtcDegradationPreference Video encoding strategy. + * @endif + * @if Chinese + * NERtcDegradationPreference 视频编码策略。 + * @endif + */ +typedef enum { + /** + * @if English + * - By default, adjust the adaptation preference based on scenarios. + * - In communication scenes, select kNERtcDegradationBalanced mode to maintain a balance between the frame rate and video + * quality. + * - In live streaming scenes, select kNERtcDegradationMaintainQuality mode and reduce the frame rate to ensure video quality. + * @endif + * @if Chinese + * - （默认）根据场景模式调整适应性偏好。 + * - 通信场景中，选择kNERtcDegradationBalanced 模式，在编码帧率和视频质量之间保持平衡。 + * - 直播场景中，选择kNERtcDegradationMaintainQuality 模式，降低编码帧率以保证视频质量。 + * @endif + */ + kNERtcDegradationDefault = 0, + /** + * @if English + * Smooth streams come first. Reduce video quality to ensure the frame rate. In a weak network environment, you can reduce the + * video quality to ensure a smooth video playback. In this case, the image quality is reduced and the pictures become + * blurred, but the video can be kept smooth. + * @endif + * @if Chinese + * 流畅优先，降低视频质量以保证编码帧率。在弱网环境下，降低视频清晰度以保证视频流畅，此时画质降低，画面会变得模糊，但可以保持视频流畅。 + * @endif + */ + kNERtcDegradationMaintainFramerate = 1, + /** + * @if English + * Clarity is prioritized. Reduce the frame rate to ensure video quality. In a weak network environment, you can reduce the + * video frame rate to ensure that the video is clear. In this case, a certain amount of freezes may occur at this time. + * @endif + * @if Chinese + * 清晰优先，降低编码帧率以保证视频质量。在弱网环境下，降低视频帧率以保证视频清晰，此时可能会出现一定卡顿。 + * @endif + */ + kNERtcDegradationMaintainQuality = 2, + /** + * @if English + * Maintain a balance between the frame rate and video quality. + * @endif + * @if Chinese + * 在编码帧率和视频质量之间保持平衡。 + * @endif + */ + kNERtcDegradationBalanced = 3, +} nertc_degradation_preference; + +/** + * @if English + * The video encoding profile configuration. + * @endif + * @if Chinese + * 视频编码属性配置。 + * @endif + */ +struct nertc_video_config { + /** + * @if English + * The resolution of video encoding used to measure encoding quality. For more information, see NERtcVideoProfileType + * @endif + * @if Chinese + * 视频编码的分辨率，用于衡量编码质量。详细信息请参考 NERtcVideoProfileType。 + * @endif + */ + nertc_video_profile_type max_profile; + /** + * @if English + * Video encoding resolution, an indicator of encoding quality, is represented by width x height. You can select this profile + * or maxProfile.
The width represents the pixels of the video frame on the horizontal axis. You can enter a custom width. + * - If you set the value to a negative number, the maxProfile setting is used. + * - If you need to customize the resolution, set this profile, and maxProfile becomes invalid. + * If the width and height of the custom video input are invalid, the width and height are automatically scaled based on + * maxProfile. + * @endif + * @if Chinese + * 视频编码分辨率，衡量编码质量，以宽x高表示。与maxProfile属性二选一。 + *
width表示视频帧在横轴上的像素，即自定义宽。 + * - 设置为负数时表示采用 max_profile 档位。 + * - 如果需要自定义分辨率场景，则设置此属性，maxProfile属性失效。 + * 自定义视频输入width和height无效，会自动根据 maxProfile 缩放。 + * @endif + */ + uint32_t width; + /** + * @if English + * Video encoding resolution, an indicator of encoding quality, is represented by width x height. You can select this profile + * or maxProfile.
The height represents the pixels of the video frame on the vertical axis. You can enter a custom height. + * - If you set the value to a negative number, the maxProfile setting is used. + * - If you need to customize the resolution, set this profile, and maxProfile becomes invalid. + * If the width and height of the custom video input are invalid, the width and height are automatically scaled based on + * maxProfile. + * @endif + * @if Chinese + * 视频编码分辨率，衡量编码质量，以宽x高表示。与maxProfile属性二选一。 + *
height表示视频帧在纵轴上的像素，即自定义高。 + * - 设置为负数时表示采用 max_profile 档位。 + * - 如果需要自定义分辨率场景，则设置此属性，maxProfile属性失效。 + *
自定义视频输入width和height无效，会自动根据 maxProfile 缩放。 + * @endif + */ + uint32_t height; + /** + * @if English + * Video crop mode, aspect ratio. The default value is kNERtcVideoCropModeDefault. For more information, see + * NERtcVideoCropMode. + * @endif + * @if Chinese + * 视频裁剪模式，宽高比。默认为 kNERtcVideoCropModeDefault。详细信息请参考 NERtcVideoCropMode。 + * @endif + */ + nertc_video_crop_mode crop_mode_; + /** + * @if English + * The frame rate of the mainstream video encoding. For more information, see NERtcVideoFramerateType. By default, the frame + * rate is determined based on maxProfile. + * - max_profile >= STANDARD. frameRate = FRAME_RATE_FPS_30. + * - max_profile < STANDARD. frameRate = FRAME_RATE_FPS_15. + * @endif + * @if Chinese + * 主流的视频编码的帧率。详细信息请参考 NERtcVideoFramerateType。默认根据设置的maxProfile决定帧率。 + * - max_profile >= STANDARD，frameRate = FRAME_RATE_FPS_30。 + * - max_profile < STANDARD，frameRate = FRAME_RATE_FPS_15。 + * @endif + */ + nertc_video_framerate_type framerate; + /** + * @if English + * The minimum frame rate for video encoding. The default value is 0, which indicates that the minimum frame rate is used by + * default + * @endif + * @if Chinese + * 视频编码的最小帧率。默认为 0，表示使用默认最小帧率 + * @endif + */ + nertc_video_framerate_type min_framerate; + /** + * @if English + * Video encoding bitrate (kbps), use the default value if the setting is set to 0. + * @endif + * @if Chinese + * 视频编码码率kbps，取0时使用默认值 + * @endif + */ + uint32_t bitrate; + /** + * @if English + * The minimum bitrate of video encoding in kbps. You can manually set the required minimum bitrate based on your business + * requirements. If the bitrate is set to 0, the SDK computes and processes automatically. + * @endif + * @if Chinese + * 视频编码的最小码率，单位为 Kbps。您可以根据场景需要，手动设置想要的最小码率，若设置为0，SDK 将会自行计算处理。 + * @endif + */ + uint32_t min_bitrate; + /** + * @if English + * Video encoding degradation preference when the bandwidth is limited. For more information, see NERtcDegradationPreference. + * @endif + * @if Chinese + * 带宽受限时的视频编码降级偏好。详细信息请参考 NERtcDegradationPreference。 + * @endif + */ + nertc_degradation_preference degradation_preference; + /** + * @if English + * Set the mirror mode for the local video encoding. The mirror mode is used for publishing the local video stream. The + * setting only affects the video picture seen by remote users. + * @endif + * @if Chinese + * 设置本地视频编码的镜像模式，即本地发送视频的镜像模式，只影响远端用户看到的视频画面。 + * @endif + */ + nertc_video_mirror_mode mirror_mode; + /** + * @if English + * Set the orientation mode of the local video encoding, The orientation mode is used for publishing the local video stream, + * which only affects the video picture seen by remote users. + * @endif + * @if Chinese + * 设置本地视频编码的方向模式，即本地发送视频的方向模式，只影响远端用户看到的视频画面。 + * @endif + */ + nertc_video_orientation_mode orientation_mode; +}; + +/** + * @if English + * Video frame rate callback. + * @param uid The user ID + * @param data The data pointer + * @param type The data type NERtcVideoType + * @param width The width + * @param height The height + * @param count The number of data types, including the number of offset and stride. + * @param offset The data offset of each type + * @param stride The data step of each type + * @param rotation Screen rotation angle NERtcVideoRotation + * @param user_data User transparent transmission data + * + * @endif + * @if Chinese + * 视频帧数据回调 + * @param uid 用户id + * @param data 数据指针 + * @param type 数据类型NERtcVideoType + * @param width 宽度 + * @param height 高度 + * @param count 数据类型个数，即offset及stride的数目 + * @param offset 每类数据偏移 + * @param stride 每类数据步进 + * @param rotation 画面旋转角度NERtcVideoRotation + * @param user_data 用户透传数据 + * @endif + */ +typedef void (NERTC_CALL *on_frame_data_callback)(nertc_uid_t uid, + void* data, + uint32_t type, + uint32_t width, + uint32_t height, + uint32_t count, + uint32_t offset[4], + uint32_t stride[4], + uint32_t rotation, + void* user_data); + +/** + * @if English + * Configuration parameters for screen sharing encoding. + * @endif + * @if Chinese + * 屏幕共享编码参数配置。 + * @endif + */ +typedef enum { + /** + * @if English + * 640x480, 5fps. + * @endif + * @if Chinese + * 640x480, 5fps + * @endif + */ + kNERtcScreenProfile480P = 0, + /** + * @if English + * 1280x720, 5fps. + * @endif + * @if Chinese + * 1280x720, 5fps + * @endif + */ + kNERtcScreenProfileHD720P = 1, + /** + * @if English + * 1920x1080, 5fps. This is the default value. + * @endif + * @if Chinese + * 1920x1080, 5fps。默认 + * @endif + */ + kNERtcScreenProfileHD1080P = 2, + /** + * @if English + * Custom. + * @endif + * @if Chinese + * 自定义 + * @endif + */ + kNERtcScreenProfileCustom = 3, + /** + * @if English + * None + * @endif + * @if Chinese + * 无效果。 + * @endif + */ + kNERtcScreenProfileNone = 4, + /** + * @if English + * 1920x1080, 5fps. This is the default value. + * @endif + * @if Chinese + * 1920x1080, 5fps。 + * @endif + */ + kNERtcScreenProfileMAX = kNERtcScreenProfileHD1080P, +} nertc_screen_profile_type; + + +/** + * @if English + * Screen sharing status. + * @endif + * @if Chinese + * 屏幕分享状态 + * @endif + */ +typedef enum { + /** + * @if English + * Starts screen sharing. + * @endif + * @if Chinese + * 开始屏幕共享。 + * @endif + */ + kNERtcScreenCaptureStatusStart = 1, + + /** + * @if English + * Pauses screen sharing. + * @endif + * @if Chinese + * 暂停屏幕共享。 + * @endif + */ + kNERtcScreenCaptureStatusPause = 2, + + /** + * @if English + * Resumes screen sharing. + * @endif + * @if Chinese + * 恢复屏幕共享。 + * @endif + */ + kNERtcScreenCaptureStatusResume = 3, + + /** + * @if English + * Stops screen sharing. + * @endif + * @if Chinese + * 停止屏幕共享。 + * @endif + */ + kNERtcScreenCaptureStatusStop = 4, + + /** + * @if English + * The target window for screen sharing is covered. + * @endif + * @if Chinese + * 屏幕分享的目标窗口被覆盖。 + * @note 在 Windows 平台中，某些窗口在被屏蔽之后，如果被置于图层最上层，此窗口图像可能会黑屏。此时会触发 + * onScreenCaptureStatus.kScreenCaptureStatusCovered 回调，建议应用层在触发此回调时提醒用户将待分享的窗口置于最上层。 + * @endif + */ + kNERtcScreenCaptureStatusCovered = 5 +} nertc_screen_capture_status; + +/** + * @if English + * The position of the area to be shared with respect to the entire screen or window. If you leave the setting empty, the entire + * screen or window is shared. + * @endif + * @if Chinese + * 待共享区域相对于整个屏幕或窗口的位置，如不填，则表示共享整个屏幕或窗口。 + * @endif + */ +struct nertc_rectangle { + /** + * @if English + * The horizontal offset of the upper left corner. + * @endif + * @if Chinese + * 左上角的横向偏移。 + * @endif + */ + int x; + /** + * @if English + * The vertical offset of the upper left corner. + * @endif + * @if Chinese + * 左上角的纵向偏移。 + * @endif + */ + int y; + /** + * @if English + * The width of the area to be shared. + * @endif + * @if Chinese + * 待共享区域的宽。 + * @endif + */ + int width; + /** + * @if English + * The height of the area to be shared. + * @endif + * @if Chinese + * 待共享区域的高。 + * @endif + */ + int height; +}; + +/** + * @if English + * Video dimensions. + * @endif + * @if Chinese + * 视频尺寸。 + * @endif + */ +struct nertc_video_dimensions { + /** + * @if English + * The width + * @endif + * @if Chinese + * 宽度 + * @endif + */ + int width; + /** + * @if English + * The height + * @endif + * @if Chinese + * 高度 + * @endif + */ + int height; +}; + +/** + * @if English + * Encoding strategy preference for screen sharing. + * - kNERtcSubStreamContentPreferMotion: The content type is animation. When the shared content is a video, movie, or game, We + * recommend that you select this content type.If a user sets the content type to animation, the user-defined frame rate is + * applied. + * - kNERtcSubStreamContentPreferDetails: The content type is details. When the shared content is an image or text, We recommend + * that you select this content type. When the user sets the content type to details, the user is allowed to set up to 10 + * frames. If the setting exceeds 10 frames, 10 frames are applied. + * @endif + * @if Chinese + * 屏幕共享功能的编码策略倾向。 + * - kNERtcSubStreamContentPreferMotion: + * 内容类型为动画。当共享的内容是视频、电影或游戏时，推荐选择该内容类型。当用户设置内容类型为动画时，按用户设置的帧率处理。 + * - kNERtcSubStreamContentPreferDetails: + * 内容类型为细节。当共享的内容是图片或文字时，推荐选择该内容类型。当用户设置内容类型为细节时，最高允许用户设置到10帧，设置超过 + * 10 帧时，不生效，按 10 帧处理。 + * @endif + */ +typedef enum { + /** + * @if English + * The animation mode. + * @endif + * @if Chinese + * 动画模式。 + * @endif + */ + kNERtcSubStreamContentPreferMotion = 0, + /** + * @if English + * The details mode. + * @endif + * @if Chinese + * 细节模式。 + * @endif + */ + kNERtcSubStreamContentPreferDetails = 1, +} nertc_sub_stream_content_prefer; + +/** + * @if English + * Configuration parameters for screen sharing encoding. The setting is used to measure encoding quality. + * @endif + * @if Chinese + * 屏幕共享编码参数配置。用于衡量编码质量。 + * @endif + */ +struct nertc_screen_capture_parameters { + /** + * @if English + * Configuration parameters for screen sharing encoding. + * @endif + * @if Chinese + * 屏幕共享编码参数配置。 + * @endif + */ + nertc_screen_profile_type profile; + /** + * @if English + * The maximum pixel value sent by screen sharing video. The value is valid in kNERtcScreenProfileCustom. + * @endif + * @if Chinese + * 屏幕共享视频发送的最大像素值，kNERtcScreenProfileCustom下生效。 + * @endif + */ + nertc_video_dimensions dimensions; + /** + * @if English + * The frame rate of the shared video.The value is valid in kNERtcScreenProfileCustom, and the unit is fps. The default value + * is 5. A value more than 15 is not recommended. + * @endif + * @if Chinese + * 共享视频的帧率，kNERtcScreenProfileCustom下生效，单位为 fps；默认值为 5，建议不要超过 15。 + * @endif + */ + int frame_rate; + /** + * @if English + * The bitrate of the shared video in kbps. The default value is 0, which indicates that the SDK calculates a reasonable value + * based on the resolution of the current shared screen. + * @endif + * @if Chinese + * 共享视频的码率，单位为 kbps；默认值为 0，表示 SDK 根据当前共享屏幕的分辨率计算出一个合理的值。 + * @endif + */ + int bitrate; + /** + * @if English + * Determines whether to capture the mouse during screen sharing. + * @endif + * @if Chinese + * 是否采集鼠标用于屏幕共享。 + * @endif + */ + bool capture_mouse_cursor; + /** + * @if English + * Determing whether to bing the window to the front when you call the startScreenCaptureByWindowId method to share a window. + * @endif + * @if Chinese + * 调用 startScreenCaptureByWindowId 方法共享窗口时，是否将该窗口前置。 + * @endif + */ + bool window_focus; + /** + * @if English + * ID list of windows to be blocked. + * @endif + * @if Chinese + * 待屏蔽窗口的 ID 列表。 + * @endif + */ + source_id_t* excluded_window_list; + /** + * @if English + * The number of windows to be blocked. + * @endif + * @if Chinese + * 待屏蔽窗口的数量。 + * @endif + */ + int excluded_window_count; + /** + * @if English + * Encoding strategy preference. + * @endif + * @if Chinese + * 编码策略倾向。 + * @endif + */ + nertc_sub_stream_content_prefer prefer; + + /** + * @if English + * Video encoding degradation preference when the bandwidth is limited. For more information, see + * nertc_degradation_preference. + * @endif + * @if Chinese + * 带宽受限时的视频编码降级偏好。详细信息请参考 NERtcDegradationPreference。 + * @endif + */ + nertc_degradation_preference degradation_preference; +}; + +/** + * @if English + * Configuration of the video display. + * @endif + * @if Chinese + * 视频显示设置 + * @endif + */ +struct nertc_video_canvas { + /** + * @if English + * Specifies whether to use an external renderer. The default value is NO. If you want to use an external renderer, you can + * associate the renderer by calling externalVideoRender with the SDK. if not, you can associate the renderer based on the + * container with the SDK. Switching between the internal rendering and external rendering during a call is not supported. + * @endif + * @if Chinese + * 是否使用外部渲染器，默认 NO + * 不使用，若使用SDK内部会根据externalVideoRender来进行绑定，若不使用SDK内部根据container来进行绑定。暂不支持在通话中切换内部渲染与外部渲染。 + * @endif + */ + bool use_external_render; + /** + * @if English + * Data callbacks. For more information, see onFrameDataCallback. + *
In macosx, you must set video_use_exnternal_render in NERtcEngineContext to true. + * @endif + * @if Chinese + * 数据回调。详细信息请参考 onFrameDataCallback。 + *
在 macosx中，需要设置 NERtcEngineContex t的 video_use_exnternal_render 为 true 才有效。 + * @endif + */ + on_frame_data_callback cb; + /** + * @if English + * The user data returned by the callback for the data transparent transmission. + * In macosx, you must set video_use_exnternal_render in NERtcEngineContext to true. + * @endif + * @if Chinese + * 数据回调的用户透传数据。 + *
在 macosx中，需要设置 NERtcEngineContex t的 video_use_exnternal_render 为 true 才有效。 + * @endif + */ + void* user_data; + /** + * @if English + * Rendering window handle. + * In macosx, you must set video_use_exnternal_render in NERtcEngineContext to false. + * @endif + * @if Chinese + * 渲染窗口句柄。 + *
在 macosx中，需要设置 NERtcEngineContex t的 video_use_exnternal_render 为 false 才有效。 + * + * @endif + */ + void* window; + /** + * @if English + * Video display mode. For more information, see NERtcVideoCropMode. + * @endif + * @if Chinese + * 视频显示模式，详细信息请参考 NERtcVideoScalingMode。 + * @endif + */ + nertc_video_scaling_mode scaling_mode; + + /** + * @if Chinese + * 背景颜色，格式为 0xRRGGBB，默认为黑色即 0x000000 + * @endif + */ + uint32_t background_color; +}; + +/** + * @if English + * Recording type. + * @endif + * @if Chinese + * 录制类型。 + * @endif + */ +typedef enum { + /** + * @if English + * Composite and individual stream recording. + * @endif + * @if Chinese + * 参与合流+单流录制。 + * @endif + */ + kNERtcRecordTypeAll = 0, + /** + * @if English + * Composite recording mode. + * @endif + * @if Chinese + * 参与合流录制模式。 + * @endif + */ + kNERtcRecordTypeMix = 1, + /** + * @if English + * individual recording mode. + * @endif + * @if Chinese + * 参与单流录制模式。 + * @endif + */ + kNERtcRecordTypeSingle = 2, + +} nertc_record_type; + +/** + * @if English + * Audio type. + * @endif + * @if Chinese + * 音频类型。 + * @endif + */ +typedef enum { + /** + * @if English + * PCM audio format. + * @endif + * @if Chinese + * PCM 音频格式。 + * @endif + */ + kNERtcAudioTypePCM16 = 0, +} nertc_audio_type; + +/** + * @if English + * Audio frame request data read and write mode. + * @endif + * @if Chinese + * 音频帧请求数据的读写模式。 + * @endif + */ +typedef enum { + /** + * @if English + * Read-only mode + * @endif + * @if Chinese + * 返回数据只读模式 + * @endif + */ + kNERtcRawAudioFrameOpModeReadOnly = 0, + /** + * @if English + * Read and write mode + * @endif + * @if Chinese + * 返回数据可读写 + * @endif + */ + kNERtcRawAudioFrameOpModeReadWrite, +} nertc_raw_audio_frame_op_mode_type; + +/** + * @if English + * The audio frame request format. + * @endif + * @if Chinese + * 音频帧请求格式。 + * @endif + */ +struct nertc_audio_frame_request_format { + /** + * @if English + * the number of channels. If the audio is a stereo sound, the data is interleaved. mono: 1. stereo: 2. + * @endif + * @if Chinese + * 音频声道数量。如果是立体声，数据是交叉的。单声道: 1；双声道 : 2。 + * @endif + */ + uint32_t channels; + /** + * @if English + * The sample rate. + * @endif + * @if Chinese + * 采样率。 + * @endif + */ + uint32_t sample_rate; + /** + * @if English + * Read and write mode. + * @endif + * @if Chinese + * 读写模式 + * @endif + */ + nertc_raw_audio_frame_op_mode_type mode; +}; + +/** + * @if English + * The audio format. + * @endif + * @if Chinese + * 音频格式。 + * @endif + */ +struct nertc_audio_format { + /** + * @if English + * Audio type. + * @endif + * @if Chinese + * 音频类型。 + * @endif + */ + nertc_audio_type type; + /** + * @if English + * the number of channels. If the audio is a stereo sound, the data interleaved. mono: 1. stereo: 2. + * @endif + * @if Chinese + * 音频声道数量。如果是立体声，数据是交叉的。单声道: 1；双声道 : 2。 + * @endif + */ + uint32_t channels; + /** + * @if English + * The sample rate. + * @endif + * @if Chinese + * 采样率。 + * @endif + */ + uint32_t sample_rate; + /** + * @if English + * The number of bytes per sample. For PCM, 16 bits are used, which means 2 bytes. + * @endif + * @if Chinese + * 每个采样点的字节数。对于 PCM 来说，一般使用 16 bit，即两个字节。 + * @endif + */ + uint32_t bytes_per_sample; + /** + * @if English + * The number of samples per room. + * @endif + * @if Chinese + * 每个房间的样本数量。 + * @endif + */ + uint32_t samples_per_channel; +}; + +/** + * @if English + * The audio frame. + * @endif + * @if Chinese + * 音频帧。 + * @endif + */ +struct nertc_audio_frame { + /** + * @if English + * Audio format. + * @endif + * @if Chinese + * 音频格式。 + * @endif + */ + nertc_audio_format format; + /** + * @if English + * Data buffer. The valid data length: samples_per_channel * channels * bytes_per_sample. + * @endif + * @if Chinese + * 数据缓冲区。有效数据长度为：samples_per_channel * channels * bytes_per_sample。 + * @endif + */ + void* data; +}; + +/** + * @if English + * Audio payload type. + * @endif + * @if Chinese + * 音频payload类型。 + * @endif + */ +typedef enum { + /** + * @if English + * OPUS audio payload type. + * @endif + * @if Chinese + * OPUS音频格式。 + * @endif + */ + kNERtcAudioPayloadTypeOPUS = 111, +} nertc_audio_payload_type; + +/** + * @if English + * Audio encoded frame of external input. + * @endif + * @if Chinese + * 外部输入的编码后音频帧。 + * @endif + */ +struct nertc_audio_encoded_frame { + /** + * @if English + * The audio encoded frame data. + * @endif + * @if Chinese + * 编码后音频帧数据。 + * @endif + */ + unsigned char* data; + /** + * @if English + * The audio encoded frame timestamp. Unit: microseconds. + * @endif + * @if Chinese + * 时间戳, 单位为微妙。 + * @endif + */ + int64_t timestamp_us; + /** + * @if English + * The audio encoded frame samplerate. + * @endif + * @if Chinese + * 音频采样率。 + * @endif + */ + int sample_rate; + /** + * @if English + * The audio encoded frame channels. + * @endif + * @if Chinese + * 音频声道数。 + * @endif + */ + int channels; + /** + * @if English + * The audio encoded frame samples per channel. + * @endif + * @if Chinese + * 该编码片段中每个声道的样本数。 + * @endif + */ + int samples_per_channel; + /** + * @if English + * The audio encoded frame data length. + * @endif + * @if Chinese + * 编码后音频帧数据长度。 + * @endif + */ + int encoded_len; + /** + * @if English + * The audio encoded timestmap, Unit: number of samples, such as 0, 960, 1920 ... increase. + * @endif + * @if Chinese + * 编码时间, 单位为样本数, 如0、960、1920...递增。 + * @endif + */ + int encoded_timestamp; + /** + * @if English + * The audio encoded frame payload type. For more information, see NERtcAudioPayloadType. + * @endif + * @if Chinese + * 编码后音频帧payload类型，详细信息请参考 NERtcAudioPayloadType。 + * @endif + */ + nertc_audio_payload_type payload_type; + + /** + * @if Chinese + * 音频数据音量标记，有效值[0,100]，用于后台ASL选路时参考。默认100。 + * @endif + */ + uint8_t rms_level; +}; + +struct nertc_audio_frame_observer { + void *self; + + /** + * @if English + * Occurs when the audio data is captured. The callback is used to process the audio data. + * @note + * - The returned audio data has read and write permissions. + * - The callback is triggered when an operation is driven by the local audio data. + * @param frame The audio frame. + * @endif + * @if Chinese + * 采集音频数据回调，用于声音处理等操作。 + * @note + * - 返回音频数据支持读/写。 + * - 有本地音频数据驱动就会回调。 + * @param frame 音频帧。 + * @endif + */ + void (NERTC_CALL *on_audio_frame_did_record)(void *self, struct nertc_audio_frame *frame); + + /** + * @if English + * Occurs when the audio substream data is captured. The callback is used to process the audio data. + * @note + * - The returned audio data has read and write permissions. + * - The callback is triggered when an operation is driven by the local audio data. + * @param frame The audio frame. + * @endif + * @if Chinese + * 辅流采集音频数据回调。 + *
通过 \ref IRtcEngineEx::setAudioFrameObserver "setAudioFrameObserver" 接口设置回调监听，当辅流设备工作时，会触发该回调。此外您可以通过 \ref IRtcEngineEx::setRecordingAudioFrameParameters "setRecordingAudioFrameParameters" 接口设置回调数据格式。 + * @par 业务场景 + * 通过该回调数据可以获取辅流采集数据，也可以通过回调数据做音频前处理（变声、音效处理等）。 + * @since V4.6.20 + * @note + * - 有本地音频辅流据驱动就会返回该回调。 + * - 返回音频数据支持读/写。 + * - 该接口返回的数据格式，需要以返回数据 NERtcAudioFrame 中的 NERtcAudioFormat 为准。 + * @par 参数说明 + * + * + * + * + * + * + * + * + * + * + * + *
**参数名称****类型****描述**
frame \ref nertc::NERtcAudioFrame "NERtcAudioFrame"音频帧。包含数据格式及数据内容。
+ * @endif + */ + void (NERTC_CALL *on_substream_audio_frame_did_record)(void *self, struct nertc_audio_frame *frame); + + /** + * @if English + * Occurs when the audio data is played back. The callback is used to process the audio data. + * @note + * - The returned audio data has read and write permissions. + * - The callback is triggered when an operation is driven by the local audio data. + * @param frame The audio frame. + * @endif + * @if Chinese + * 播放音频数据回调，用于声音处理等操作。 + * @note + * - 返回音频数据支持读/写。 + * - 有本地音频数据驱动就会回调。 + * @param frame 音频帧。 + * @endif + */ + void (NERTC_CALL *on_audio_frame_will_playback)(void *self, struct nertc_audio_frame *frame); + + /** + * @if English + * Gets the raw audio data of the local user and all remote users after mixing. + * @note + * - The returned audio data is read-only. + * - The callback is triggered when an operation is driven by the local audio data. + * @param frame The audio frame. + * @endif + * @if Chinese + * 获取本地用户和所有远端用户混音后的原始音频数据。 + * @note + * - 返回音频数据只读。 + * - 有本地音频数据驱动就会回调。 + * @param frame 音频帧。 + * @endif + */ + void (NERTC_CALL *on_mixed_audio_frame)(void *self, struct nertc_audio_frame *frame); + + /** + * @if English + * Gets the raw audio data of a specified remote user before audio mixing. + *
After the audio observer is registered, if the remote audio is subscribed by default and the remote user + * enables the audio, the SDK triggers this callback when the audio data before audio mixing is captured, and the + * audio data is returned to the user. + * @note The returned audio data is read-only. + * @deprecated This API is about to be deprecated. Use \ref + * nertc::INERtcAudioFrameObserver::onPlaybackAudioFrameBeforeMixing(uint64_t userID, NERtcAudioFrame* frame, + * channel_id_t cid) "onPlaybackAudioFrameBeforeMixing"[2/2] instead. In multi-channel scenarios, channelId is used + * to identify different channels. + * @param userID The ID of a remote user. + * @param frame The audio frame. + * @endif + * @if Chinese + * 获取单个远端用户混音前的音频数据。 + *
成功注册音频观测器后，如果订阅了远端音频（默认订阅）且远端用户开启音频后，SDK + * 会在捕捉到混音前的音频数据时，触发该回调，将音频数据回调给用户。 + * @note 返回音频数据只读。 + * @deprecated 即将废弃，请改用接口 \ref nertc::INERtcAudioFrameObserver::onPlaybackAudioFrameBeforeMixing(uint64_t + * userID, NERtcAudioFrame* frame, channel_id_t cid) + * "onPlaybackAudioFrameBeforeMixing"[2/2]。在多房间场景下，此接口可通过 cid 识别不同房间。 + * @param userID 用户 ID。 + * @param frame 音频帧。 + * @endif + */ + void (NERTC_CALL *on_playback_audio_frame_before_mixing)(void *self, uint64_t user_id, struct nertc_audio_frame *frame, channel_id_t cid); + + /** + * @if English + * Gets the audio substream data from a specified remote user before mixing audio. + *
After the audio observer is registered, the SDK will get the audio data from a specified remote user before + * mixing if the remote audio substream is subscribed to and the remote user publishes the audio substream. + * @note The returned audio data can only be read. + * @param userID A remote user ID. + * @param frame audio frame data. + * @param cid Room ID. For multiple rooms, channelId is used to identify the rooms. + * @endif + * @if Chinese + * 获取指定远端用户混音前的辅流音频数据。 + *
成功注册音频观测器后，如果订阅了远端辅流音频（默认订阅）且远端用户开启辅流音频后，SDK + * 会在捕捉到混音前的辅流音频数据时，触发该回调，将辅流音频数据回调给用户。 + * @note 返回音频数据只读。 + * @param userID 用户ID。 + * @param frame 音频帧。 + * @param cid 房间 ID。在多房间场景下，cid 用于识别不同的房间。 + * @endif + */ + void (NERTC_CALL *on_playback_substream_audio_frame_before_mixing)(void *self, uint64_t user_id, struct nertc_audio_frame *frame, channel_id_t cid); +}; + +/** + * @if English + * The video type. + * @endif + * @if Chinese + * 视频类型。 + * @endif + */ +typedef enum { + /** + * @if English + * I420 video format. + * @endif + * @if Chinese + * I420 视频格式。 + * @endif + */ + kNERtcVideoTypeI420 = 0, + /** + * @if English + * NV12 video format. + * @endif + * @if Chinese + * NV12 视频格式。 + * @endif + */ + kNERtcVideoTypeNV12 = 1, + /** + * @if English + * NV21 video format. + * @endif + * @if Chinese + * NV21 视频格式。 + * @endif + */ + kNERtcVideoTypeNV21 = 2, + /** + * @if English + * BGRA video format. + * @endif + * @if Chinese + * BGRA 视频格式。 + * @endif + */ + kNERtcVideoTypeBGRA = 3, + /** + * @if English + * ARGB video format. + * @endif + * @if Chinese + * BGRA 视频格式。 + * @endif + */ + kNERtcVideoTypeARGB = 4, + /** + * @if English + * oc capture native video format. External video input is not allowed. + * @endif + * @if Chinese + * oc capture native视频格式。不支持外部视频输入 + * @endif + */ + kNERtcVideoTypeCVPixelBuffer = 5, +} nertc_video_type; + +/** + * @if English + * The angle to which the video rotates. + * @endif + * @if Chinese + * 视频旋转角度。 + * @endif + */ +typedef enum { + /** + * @if English + * 0 度。 + * @endif + * @if Chinese + * 0° + * @endif + */ + kNERtcVideoRotation_0 = 0, + /** + * @if English + * 90° + * @endif + * @if Chinese + * 90 度。 + * @endif + */ + kNERtcVideoRotation_90 = 90, + /** + * @if English + * 180° + * @endif + * @if Chinese + * 180 度。 + * @endif + */ + kNERtcVideoRotation_180 = 180, + /** + * @if English + * 270° + * @endif + * @if Chinese + * 270 度。 + * @endif + */ + kNERtcVideoRotation_270 = 270, +} nertc_video_rotation; + +/** + * @if English + * Video frame of external input. + * @endif + * @if Chinese + * 外部输入的视频桢。 + * @endif + */ +struct nertc_video_frame { + /** + * @if English + * The video frame format. For more information, see NERtcVideoType. + * @endif + * @if Chinese + * 视频帧格式，详细信息请参考 NERtcVideoType。 + * @endif + */ + nertc_video_type format; + /** + * @if English + * The video timestamp. Unit: milliseconds. + * @endif + * @if Chinese + * 视频时间戳，单位为毫秒。 + * @endif + */ + uint64_t timestamp; + /** + * @if English + * Video frame width. + * @endif + * @if Chinese + * 视频桢宽度 + * @endif + */ + uint32_t width; + /** + * @if English + * Video frame height. + * @endif + * @if Chinese + * 视频桢宽高 + * @endif + */ + uint32_t height; + /** + * @if Chinese + * 数据类型个数，即offset及stride的数目 + * @endif + */ + int count; + /** + * @if English + * offset of Video frame data . + * @endif + * @if Chinese + * 每类数据偏移 + * @endif + */ + uint32_t offset[4]; + /** + * @if English + * stride of Video frame data . + * @endif + * @if Chinese + * 每类数据步进 + * @endif + */ + uint32_t stride[4]; + /** + * @if English + * For more information about video rotation angle, see #NERtcVideoRotation. + * @endif + * @if Chinese + * 视频旋转角度 详见: #NERtcVideoRotation + * @endif + */ + nertc_video_rotation rotation; + /** + * @if English + * Video frame data. + * @endif + * @if Chinese + * 视频桢数据 + * @endif + */ + void* buffer; + /** + * @if English + * The length of Video frame data. + * @endif + * @if Chinese + * 视频桢数据长度 + * @endif + */ + int64_t buffer_length; +}; + +/** + * @if English + * The video codec type. + * @endif + * @if Chinese + * 视频编解码器类型。 + * @endif + */ +typedef enum { + /** + * @if English + * The H264 codec + * @endif + * @if Chinese + * H264 编解码器。 + * @endif + */ + kNERtcVideoCodecTypeH264 = 3, +} nertc_video_codec_type; + +/** + * @if English + * The video encoded frame type. + * @endif + * @if Chinese + * 视频编码帧类型。 + * @endif + */ +typedef enum { + /** + * @if English + * The IDR frame + * @endif + * @if Chinese + * IDR 帧。 + * @endif + */ + kNERtcNalFrameTypeIDR = 1, + /** + * @if English + * I frame. + * @endif + * @if Chinese + * I 帧。 + * @endif + */ + kNERtcNalFrameTypeI = 2, + /** + * @if English + * P frame. + * @endif + * @if Chinese + * P 帧。 + * @endif + */ + kNERtcNalFrameTypeP = 3, +} nertc_nal_frame_type; + +/** + * @if English + * Video encoded frame of external input. + * @endif + * @if Chinese + * 外部输入的编码后视频帧。 + * @endif + */ +struct nertc_video_encoded_frame { + /** + * @if English + * The video codec type. For more information, see NERtcVideoCodecType. + * @endif + * @if Chinese + * 视频编解码器类型，详细信息请参考 NERtcVideoCodecType。 + * @endif + */ + nertc_video_codec_type codec_type; + /** + * @if English + * The video encoded frame type. For more information, see NERtcNalFrameType. + * @endif + * @if Chinese + * 编码后视频帧类型，详细信息请参考 NERtcNalFrameType。 + * @endif + */ + nertc_nal_frame_type frame_type; + /** + * @if English + * The nal count of video encoded frame. + * @endif + * @if Chinese + * 编码后视频帧nal个数。 + * @endif + */ + int nal_count; + /** + * @if English + * The nal length of video encoded frame + * @endif + * @if Chinese + * 编码后视频帧nal的长度。 + * @endif + */ + int* nal_length; + /** + * @if English + * The nal length of video encoded frame + * @endif + * @if Chinese + * 编码后视频帧数据，包括所有nal的数据。 + * @endif + */ + unsigned char* nal_data; + /** + * @if English + * The video encoded frame timestamp. Unit: microseconds. + * @endif + * @if Chinese + * 时间戳，机器时间，单位为微秒。 + * @endif + */ + int64_t timestamp_us; + /** + * @if English + * The video encoded frame width. + * @endif + * @if Chinese + * 视频宽。 + * @endif + */ + int width; + /** + * @if English + * The video encoded frame height. + * @endif + * @if Chinese + * 视频高。 + * @endif + */ + int height; +}; + +/** + * @if English + * The reasons why the user leaves. + * @endif + * @if Chinese + * 用户离开原因。 + * @endif + */ +typedef enum { + /** + * @if English + * A user leaves the room normally. + * @endif + * @if Chinese + * 正常离开。 + * @endif + */ + kNERtcSessionLeaveNormal = 0, + /** + * @if English + * The user is disconnected and leaves the room. + * @endif + * @if Chinese + * 用户断线导致离开。 + * @endif + */ + kNERtcSessionLeaveForFailOver = 1, + /** + * @if English + * The user leaves the room because the session fails over. + * @endif + * @if Chinese + * 用户 Failover 过程中产生的 leave。 + * @endif + */ + kNERtcSessionLeaveUpdate = 2, + /** + * @if English + * The user is removed from the room. + * @endif + * @if Chinese + * 用户被踢导致离开。 + * @endif + */ + kNERtcSessionLeaveForKick = 3, + /** + * @if English + * The user is disconnected due to connection timeout. + * @endif + * @if Chinese + * 用户超时导致离开。 + * @endif + */ + kNERtcSessionLeaveTimeOut = 4, +} nertc_session_leave_reason; + +/** + * @if English + * The playback state of the music file. + * @endif + * @if Chinese + * 音乐文件播放状态。 + * + * @endif + */ +typedef enum { + /** + * @if English + * The playback ends. + * @endif + * @if Chinese + * 音乐文件播放结束。 + * @endif + */ + kNERtcAudioMixingStateFinished = 0, + /** + * @if English + * The playback fails because an error occurs. For more information, see #NERtcAudioMixingErrorCode. + * @endif + * @if Chinese + * 音乐文件报错。详见: #NERtcAudioMixingErrorCode + * @endif + */ + kNERtcAudioMixingStateFailed = 1, +} nertc_audio_mixing_state; + +/** + * @if English + * Configuration items for audio mixing. + * @endif + * @if Chinese + * 创建混音的配置项 + * @endif + */ +struct nertc_create_audio_mixing_option { + /** + * @if English + * The path of the audio file. The local absolute paths or URL addresses are supported. + * - The path must include the file name and extension, such as "D:\\audio_files\\test.mp3". + * - Supported audio formats: MP3, M4A, AAC, 3GP, WMA, and WAV. + * @endif + * @if Chinese + * 待播放的音乐文件路径，支持本地绝对路径或 URL 地址。 + * - 需精确到文件名及后缀，例如 “D:\\audio_files\\test.mp3”。 + * - 支持的音乐文件类型包括 MP3、M4A、AAC、3GP、WMA 和 WAV 格式。 + * @endif + */ + char path[kNERtcMaxURILength]; + /** + * @if English + * The number of loops for mixing audio playback: + * -1: (Default) plays the audio effect for one time. + * -≤ 0: plays in an infinite loop, until stops by calling pauseAudioMixing or stopAudioMixing. + * @endif + * @if Chinese + * 伴音循环播放的次数： + * - 1：（默认）播放音效一次。 + * - ≤ 0：无限循环播放，直至调用 pauseAudioMixing 后暂停，或调用 stopAudioMixing 后停止。 + * @endif + */ + int loop_count; + /** + * @if English + * Specifies whether to send the mixing audio to the remote client. The default value is true. The remote user can hear the + * mixing audio after the remote user subscribes to the local audio stream. + * @endif + * @if Chinese + * 是否将伴音发送远端，默认为 true，即远端用户订阅本端音频流后可听到该伴音。 + * @endif + */ + bool send_enabled; + /** + * @if English + * Indicates the publishing volume of a music file. Valid values: 0 to 100. The default value is 100, which indicates that the + * original volume of the file is used. + * @note If you modify the volume setting during a call, this setting will be used by default when you call the method again + * during the current call. + * @endif + * @if Chinese + * 乐文件的发送音量，取值范围为 0~100。默认为 100，表示使用文件的原始音量。 + * @note 若您在通话中途修改了音量设置，则当前通话中再次调用时默认沿用此设置。 + * @endif + */ + uint32_t send_volume; + /** + * @if English + * Specifies whether to play back the mixing audio on the local client. The default value is true. The local users can hear + * the mixing audio. + * @endif + * @if Chinese + * 是否本地播放伴音。默认为 true，即本地用户可以听到该伴音。 + * @endif + */ + bool playback_enabled; + /** + * @if English + * Indicates the playback volume of a music file. Valid values: 0 to 100. The default value is 100, which indicates that the + * original volume of the file is used. + * @note If you modify the volume setting during a call, this setting will be used by default when you call the method again + * during the current call. + * @endif + * @if Chinese + * 音乐文件的播放音量，取值范围为 0~100。默认为 100，表示使用文件的原始音量。 + * @note 若您在通话中途修改了音量设置，则当前通话中再次调用时默认沿用此设置。 + * @endif + */ + uint32_t playback_volume; + /** + * @if English + * The start of a playback position. Unit: milliseconds. Default value: 0. + * @endif + * @if Chinese + * 音乐文件开始播放的时间，UTC 时间戳，即从1970 年 1 月 1 日 0 点 0 分 0 秒开始到事件发生时的毫秒数。默认值为 + * 0，表示立即播放。 + * @endif + */ + uint64_t start_timestamp; + + /** + * @if English + * Specifies if a mixing audio uses a mainstream or substream. The default value is mainstream. + * @endif + * @if Chinese + * 伴音跟随音频主流还是辅流，默认跟随主流。 + * @endif + */ + nertc_audio_stream_type send_with_audio_type; + + /** + * @if English + * Audio playback progress callback interval, unit: ms, value range: 100~10000, default: 1000ms + * @endif + * @if Chinese + * 伴音播放进度回调间隔，单位ms，取值范围为 100~10000, 默认1000ms + * @endif + */ + uint32_t progress_interval; +}; + +/** + * @if English + * Configuration items for audio effects. + * @endif + * @if Chinese + * 创建音效的配置项 + * @endif + */ +struct nertc_create_audio_effect_option { + /** + * @if English + * The path of the audio effect file. The local absolute paths or URL addresses are supported. + * - The path must include the file name and extension, such as "D:\\audio_files\\test.mp3". + * - Supported audio formats: MP3, M4A、AAC, 3GP, WMA, and WAV. + * @endif + * @if Chinese + * 待播放的音效文件路径，支持本地绝对路径或 URL 地址。 + * - 需精确到文件名及后缀，例如 “D:\\audio_files\\test.mp3”。 + * - 支持的音效文件类型包括 MP3、M4A、AAC、3GP、WMA 和 WAV 格式。 + * @endif + */ + char path[kNERtcMaxURILength]; + /** + * @if English + * The number of loops the audio effect is played: + * -1: (Default) plays the audio effect for one time. + * -≤ 0: Play sound effects in an infinite loop until you stop the playback by calling stopEffect or stopAllEffects. + * @endif + * @if Chinese + * 音效循环播放的次数： + * - 1：（默认）播放音效一次。 + * - ≤ 0：无限循环播放音效，直至调用 stopEffect 或 stopAllEffects 后停止。 + * @endif + */ + int loop_count; + /** + * @if English + * Specifies whether to send the mixing audio to the remote client. The default value is true. The remote user can hear the + * mixing audio after the remote user subscribes to the local audio stream. + * @endif + * @if Chinese + * 是否将伴音发送远端，默认为 true，即远端用户订阅本端音频流后可听到该伴音。 + * @endif + */ + bool send_enabled; + /** + * @if English + * Indicates the publishing volume of a music file. Valid values: 0 to 100. The default value is 100, which indicates that the + * original volume of the file is used. + * @note If you modify the volume setting during a call, this setting will be used by default when you call the method again + * during the current call. + * @endif + * @if Chinese + * 音乐文件的发送音量，取值范围为 0~100。默认为 100，表示使用文件的原始音量。 + * @note 若您在通话中途修改了音量设置，则当前通话中再次调用时默认沿用此设置。 + * @endif + */ + uint32_t send_volume; + /** + * @if English + * Specifies whether to play back. The default value is true. You can play back the local audio file. + * @endif + * @if Chinese + * 是否可播放。默认为 true，即可在本地播放该音效。 + * @endif + */ + bool playback_enabled; + /** + * @if English + * Indicates the playback volume of a music file. Valid values: 0 to 100. The default value is 100, which indicates that the + * original volume of the file is used. + * @note If you modify the volume setting during a call, this setting will be used by default when you call the method again + * during the current call. + * @endif + * @if Chinese + * 音乐文件的播放音量，取值范围为 0~100。默认为 100，表示使用文件的原始音量。 + * @note 若您在通话中途修改了音量设置，则当前通话中再次调用时默认沿用此设置。 + * @endif + */ + uint32_t playback_volume; + /** + * @if English + * The start of a playback position. Unit: milliseconds. Default value: 0. + * @endif + * @if Chinese + * 音乐文件开始播放的时间，UTC 时间戳，即从1970 年 1 月 1 日 0 点 0 分 0 秒开始到事件发生时的毫秒数。默认值为 + * 0，表示立即播放。 + * @endif + */ + uint64_t start_timestamp; + + /** + * @if English + * Specifies if a mixing audio uses a mainstream or substream. The default value is mainstream. + * @endif + * @if Chinese + * 伴音跟随音频主流还是辅流，默认跟随主流。 + * @endif + */ + nertc_audio_stream_type send_with_audio_type; + + /** + * @if English + * Audio playback progress callback interval, unit: ms, value range: 100~10000, default: 1000ms + * @endif + * @if Chinese + * 伴音播放进度回调间隔，单位ms，取值范围为 100~10000, 默认1000ms + * @endif + */ + uint32_t progress_interval; +}; + +/** + * @if English + * The video stream type. + * @endif + * @if Chinese + * 视频流类型 + * @endif + */ +typedef enum { + /** + * @if English + * mainstream. + * @endif + * @if Chinese + * 主流 + * @endif + */ + kNERTCVideoStreamMain = 0, + /** + * @if English + * Substream. + * @endif + * @if Chinese + * 辅流 + * @endif + */ + kNERTCVideoStreamSub = 1, + /** + * @if English + * Reserved parameter. Ignore this parameter. + * @endif + * @if Chinese + * 预留参数，无需关注。 + * @endif + */ + kNERTCVideoStreamCount, +} nertc_video_stream_type; + +/** + * @if English + * Status during media stream relay. + * @endif + * @if Chinese + * 媒体流转发状态 + * @endif + */ +typedef enum { + /** + * @if English + * Initial state. After a successful call of stopChannelMediaRelay method to stop cross-room media streaming. + * @endif + * @if Chinese + * 初始状态。在成功调用 stopChannelMediaRelay 停止跨房间媒体流转发后， onMediaRelayStateChanged 会回调该状态。 + * @endif + */ + kNERtcChannelMediaRelayStateIdle = 0, + /** + * @if English + * The SDK tries to relay cross-room media streams. + * @endif + * @if Chinese + * SDK 尝试跨房间转发媒体流。 + * @endif + */ + kNERtcChannelMediaRelayStateConnecting = 1, + /** + * @if English + * Sets the host role of source channel into the target room. + * @endif + * @if Chinese + * 源房间主播角色成功加入目标房间。 + * @endif + */ + kNERtcChannelMediaRelayStateRunning = 2, + /** + * @if English + * Failure occurs. See the error messages prompted by error of onMediaRelayEvent. + * @endif + * @if Chinese + * 发生异常，详见 onMediaRelayEvent 的 error 中提示的错误信息。 + * @endif + */ + kNERtcChannelMediaRelayStateFailure = 3, +} nertc_channel_media_relay_state; + +/** + * @if English + * Events related to the media stream relay. + * @endif + * @if Chinese + * 媒体流转发回调事件。 + * @endif + */ +typedef enum { + /** + * @if English + * Current media stream relay gets disconnected. + * @endif + * @if Chinese + * 媒体流转发停止。 + * @endif + */ + kNERtcChannelMediaRelayEventDisconnect = 0, + /** + * @if English + * Starts to relay media streams. + * @endif + * @if Chinese + * SDK 正在连接服务器，开始尝试转发媒体流。 + * @endif + */ + kNERtcChannelMediaRelayEventConnecting = 1, + /** + * @if English + * The media stream relay gets connected to the server. + * @endif + * @if Chinese + * 连接服务器成功。 + * @endif + */ + kNERtcChannelMediaRelayEventConnected = 2, + /** + * @if English + * The video stream is relayed to the destination room. + * @endif + * @if Chinese + * 视频音频媒体流成功转发到目标房间。 + * @endif + */ + kNERtcChannelMediaRelayEventVideoSentToDestChannelSuccess = 3, + /** + * @if English + * The audio stream is relayed to the destination room. + * @endif + * @if Chinese + * 音频媒体流成功转发到目标房间。 + * @endif + */ + kNERtcChannelMediaRelayEventAudioSentToDestChannelSuccess = 4, + /** + * @if English + * Other streams such as screen sharing stream are relayed to the destination room. + * @endif + * @if Chinese + * 媒体流屏幕共享等其他流成功转发到目标房间。 + * @endif + */ + kNERtcChannelMediaRelayEventOtherStreamSentToDestChannelSuccess = 5, + /** + * @if English + * Fails to relay media streams. Possible reasons： + * - kNERtcErrChannelReserveErrorParam(414) + * - kNERtcErrChannelMediaRelayInvalidState(30110) + * - kNERtcErrChannelMediaRelayPermissionDenied(30111) + * - kNERtcErrChannelMediaRelayStopFailed(30112) + * @endif + * @if Chinese + * 媒体流转发失败。原因包括： + * - kNERtcErrChannelReserveErrorParam(414)：请求参数错误。 + * - kNERtcErrChannelMediaRelayInvalidState(30110)：重复调用 startChannelMediaRelay。 + * - kNERtcErrChannelMediaRelayPermissionDenied(30111)：媒体流转发权限不足。例如调用 startChannelMediaRelay + * 的房间成员为主播角色、或房间为双人通话房间，不支持转发媒体流。 + * - kNERtcErrChannelMediaRelayStopFailed(30112)：调用 stopChannelMediaRelay 前，未调用 startChannelMediaRelay。 + * @endif + */ + kNERtcChannelMediaRelayEventFailure = 100, +} nertc_channel_media_relay_event; + +/** + * @if English + * Data structure related to media stream relay. + * @endif + * @if Chinese + * 媒体流转发相关的数据结构。 + * @endif + */ +struct nertc_channel_media_relay_info { + /** + * @if English + * The name of the destination room to which the media stream is relayed. + * @endif + * @if Chinese + * 房间名。 + * @endif + */ + char channel_name[kNERtcMaxChannelNameLength]; + /** + * @if English + * The token used to connect to the destination room. + * @endif + * @if Chinese + * 能加入房间的 Token。 + * @endif + */ + char channel_token[kNERtcMaxTokenLength]; + /** + * @if English + * The user ID used in the destination room. This ID can be different from the ID used in the current room. + * @endif + * @if Chinese + * 用户 ID。 + * @endif + */ + nertc_uid_t uid; +}; + +/** + * @if English + * Configurations for media stream relay. + * @endif + * @if Chinese + * 跨房间媒体流转发相关参数配置。 + * @endif + */ +struct nertc_channel_media_relay_config { + /** + * @if English + * The information about the current room. + * - `channelName`: Source channel name. + * - `channel_token`: Token with access to source channel. + * - `uid`: Identifies the UID of relaying media streams in the source channel. + * @endif + * @if Chinese + * 源房间信息，包括： + * - `channel_name`：源房间名。默认值为 nil，表示 SDK 填充当前的房间名。 + * - `channel_token`：能加入源房间的 Token。 + * - `uid`：标识源房间中的转发媒体流的 UID。 + * @endif + */ + nertc_channel_media_relay_info* src_infos; + /** + * @if English + * The configuration of the destination room. + * - `channelName`：Destination channel names. + * - `channel_token`：Token with access to target channels. + * - `uid`：Identifies the UID of relaying media stream in the target channel. Do not set this parameter as the UID of the + * host in the destination room. The parameter is different from all UIDs in the target channel. + * @endif + * @if Chinese + * 目标房间信息，包括： + * - `channelName`：目标房间的房间名。 + * - `channel_token`：可以加入目标房间的 Token。 + * - `uid`：标识目标房间中的转发媒体流的 UID。请确保不要将该参数设为目标房间的主播的 UID，并与目标房间中的 所有 UID 都不同。 + * @endif + */ + nertc_channel_media_relay_info* dest_infos; + /** + * @if English + * The number of destination rooms. The default value is 0. + * @endif + * @if Chinese + * 目标房间数量。默认为 0。 + * @endif + */ + int dest_count; +}; + +/** + * @if English + * Video watermark status. + * @endif + * @if Chinese + * 视频水印状态。 + * @endif + */ +typedef enum { + /** + * @if Chinese + * 水印设置成功。 + * @endif + */ + kNERtcLocalWatermarkStateSetSuccess, + /** + * @if English + * The device does not support video watermarks. + * @endif + * @if Chinese + * 设备不支持。 + * @endif + */ + kNERtcLocalWatermarkStateDeviceNotSupported, + /** + * @if English + * The image format is not supported. + * @endif + * @if Chinese + * 图片格式不支持。 + * @endif + */ + kNERtcLocalWatermarkStateImgFormatNotSupported, + /** + * @if English + * Image number error. + * @endif + * @if Chinese + * 图片数量设置错误。 + * @endif + */ + kNERtcLocalWatermarkStateImgNumError, + /** + * @if English + * Image resolution error. + * @endif + * @if Chinese + * 图片分辨率设置错误。 + * @endif + */ + kNERtcLocalWatermarkStateImgSizeError, + /** + * @if Chinese + * 播放帧率设置错误。 + * @endif + */ + kNERtcLocalWatermarkStateFPSError, + /** + * @if English + * Font error. + * @endif + * @if Chinese + * 字体设置错误。 + * @endif + */ + kNERtcLocalWatermarkStateFontError, + /** + * @if Chinese + * 整体水印透明度设置错误。 + * @endif + */ + kNERtcLocalWatermarkStateWmAlphaError, + /** + * @if Chinese + * 文本内容为空。 + * @endif + */ + kNERtcLocalWatermarkStateTextContentEmptyError, + /** + * @if English + * Watermark canceled. + * @endif + * @if Chinese + * 取消水印。 + * @endif + */ + kNERtcLocalWatermarkStateCancel = 20 +} nertc_local_video_watermark_state; + +/** + * @if English + * Sets the parameters for image watermarks. + *
You can add up to 4 picture watermarks. + * @endif + * @if Chinese + * 图片水印设置参数。 + *
最多可以添加 4 个图片水印。 + * @endif + */ +struct nertc_video_watermark_image_config { + /** + * @if English + * Watermark image path. The setting is invalid if left empty. + * @endif + * @if Chinese + * 水印图片路径。空时无效。 + * @endif + */ + char* image_paths[10]; + /** + * @if English + * The alpha channel of the watermark background color. + * @endif + * @if Chinese + * 水印框内背景颜色透明度 + * @endif + */ + int wm_alpha; + /** + * @if English + * The width of the watermark frame. Unit: pixels. The default value is 0, which indicates no watermark frame. + * @endif + * @if Chinese + * 水印框的宽度。单位为像素（pixel），默认值为 0，表示没有水印框。 + * @endif + */ + int wm_width; + /** + * @if English + * The height of the watermark frame. Unit: pixels. The default value is 0, which indicates no watermark frame. + * @endif + * @if Chinese + * 水印框的高度。单位为像素（pixel），默认值为 0，表示没有水印框。 + * @endif + */ + int wm_height; + /** + * @if English + * The horizontal distance between the upper left corner of the watermark and the upper left corner of the video canvas. Unit: + * pixels. The default value is 0. + * @endif + * @if Chinese + * 水印图片左上角与视频画布左上角的水平距离。单位为像素（pixel），默认值为 0。 + * @endif + */ + int offset_x; + /** + * @if English + * The vertical distance between the upper left corner of the watermark and the upper left corner of the video canvas. Unit: + * pixels. The default value is 0. + * @endif + * @if Chinese + * 水印图片左上角与视频画布左上角的垂直距离。单位为像素（pixel），默认值为 0。 + * @endif + */ + int offset_y; + /** + * @if English + * The frame rate. The default value is 0 fps, which indicates that the images are not flipped automatically. Images are + * displayed in static single frames. Note: The frame rate for clients on Windows does not exceed 20 fps. + * @endif + * @if Chinese + * 播放帧率。默认 0 帧/秒，即不自动切换图片，图片单帧静态显示。注意：Windows端帧率不超过 20 fps。 + * @endif + */ + int fps; + /** + * @if English + * Specifies whether to loop. By default, loop is enabled. If the value is set to false, the watermarks disappear when the + * playback is complete. + * @endif + * @if Chinese + * 是否设置循环。默认循环，设置为 false 后水印数组播放完毕后消失。 + * @endif + */ + bool loop; +}; + +/** + * @if English + * Parameters for text watermarks. + *
You can add up to 10 text watermarks. + * @endif + * @if Chinese + * 文字水印设置参数。 + *
最多可添加 10 个文字水印。 + * @endif + */ +struct nertc_video_watermark_text_config { + /** + * @if English + * The text content. + * @note + * - The length of the string is unlimited. The final display is affected by the font size and the size of the watermark + * frame. The part beyond the watermark frame is not displayed. + * - If the width of the watermark frame is set, when the length of the text content exceeds the width of the watermark frame, + * the text automatically wraps. If the text exceeds the height of the watermark frame, the excess part is not displayed. + * - When the width and height of the watermark frame are not set, the text does not wrap, and the part beyond the watermark + * frame is not be displayed. + * @endif + * @if Chinese + * 文字内容。 + * @note + * - 字符串长度无限制。最终显示受字体大小和水印框大小的影响。超出水印框的部分不显示。 + * - 如果设置了水印框宽度，当文字内容长度超过水印框宽度时，会自动换行，如果超出水印框高度，超出部分不显示。 + * - 未设置水印框宽度和高度时，文字不换行，超出水印框的部分不显示。 + * @endif + */ + char content[kNERtcMaxBuffLength]; + /** + * @if Chinese + * 字体名称。 + * @endif + */ + char font_name[kNERtcMaxURILength]; + /** + * @if English + * The font color. ARGB format. + * @endif + * @if Chinese + * 字体颜色。ARGB 格式。 + * @endif + */ + int font_color; + /** + * @if English + * The font size. The default value is 10, equivalent to 10 x 15 lb on a 144 dpi device. + * @endif + * @if Chinese + * 字体大小。默认值为 10，相当于 144 dpi 设备上的 10 x 15 磅。 + * @endif + */ + int font_size; + /** + * @if English + * The background color in the watermark frame. ARGB format. Transparency setting is supported. + * @endif + * @if Chinese + * 水印框内背景颜色。ARGB格式，支持透明度设置。 + * @endif + */ + int wm_color; + /** + * @if English + * The alpha channel of the watermark background color. + * @endif + * @if Chinese + * 水印框内背景颜色透明度 + * @endif + */ + int wm_alpha; + /** + * @if English + * The width of the watermark frame. Unit: pixels. The default value is 0, which indicates no watermark frame. + * @endif + * @if Chinese + * 水印框的宽度。单位为像素（pixel），默认值为 0，表示没有水印框。 + * @endif + */ + int wm_width; + /** + * @if English + * The height of the watermark frame. Unit: pixels. The default value is 0, which indicates no watermark frame. + * @endif + * @if Chinese + * 水印框的高度。单位为像素（pixel），默认值为 0，表示没有水印框。 + * @endif + */ + int wm_height; + /** + * @if English + * The horizontal distance between the upper left corner of the watermark and the upper left corner of the video canvas. Unit: + * pixels. + * @endif + * @if Chinese + * 水印左上角与视频画布左上角的水平距离。单位为像素（pixel）。 + * @endif + */ + int offset_x; + /** + * @if English + * The vertical distance between the upper left corner of the watermark and the upper left corner of the video canvas. Unit: + * pixels. + * @endif + * @if Chinese + * 水印左上角与视频画布左上角的垂直距离。单位为像素（pixel）。 + * @endif + */ + int offset_y; +}; + +/** + * @if English + * Sets a timestamp watermark. + * - You can add only 1 timestamp watermark. + * - The time of the timestamp watermark is the same as the current time and changes in real time. + * @endif + * @if Chinese + * 时间戳水印设置。 + * - 只能添加 1 个时间戳水印。 + * - 时间戳水印的时间和当前时间相同，且实时变化。 + * @endif + */ +struct nertc_video_watermark_timestamp_config { + /** + * @if Chinese + * 字体名称。 + * @endif + */ + char font_name[kNERtcMaxURILength]; + /** + * @if English + * The font color. ARGB format. + * @endif + * @if Chinese + * 水印左上角与视频画布左上角的水平距离。单位为像素（pixel）。 + * @endif + */ + int font_color; + /** + * @if English + * The font size. The default value is 10, equivalent to 10 x 15 lb on a 144 dpi device. + * @endif + * @if Chinese + * 字体颜色。ARGB 格式。 + * @endif + */ + int font_size; + /** + * @if English + * The background color in the watermark frame. ARGB format. Transparency setting is supported. + * @endif + * @if Chinese + * 水印框内背景颜色。ARGB格式，支持透明度设置。 + * @endif + */ + int wm_color; + /** + * @if English + * The alpha channel of the watermark background color. + * @endif + * @if Chinese + * 水印框内背景颜色透明度 + * @endif + */ + int wm_alpha; + /** + * @if English + * The width of the watermark frame. Unit: pixels. The default value is 0, which indicates no watermark frame. + * @endif + * @if Chinese + * 水印框的宽度。单位为像素（pixel），默认值为 0，表示没有水印框。 + * @endif + */ + int wm_width; + /** + * @if English + * The height of the watermark frame. Unit: pixels. The default value is 0, which indicates no watermark frame. + * @endif + * @if Chinese + * 水印框的高度。单位为像素（pixel），默认值为 0，表示没有水印框。 + * @endif + */ + int wm_height; + /** + * @if English + * The horizontal distance between the upper left corner of the watermark and the upper left corner of the video canvas. Unit: + * pixels. + * @endif + * @if Chinese + * 水印左上角与视频画布左上角的水平距离。单位为像素（pixel）。 + * @endif + */ + int offset_x; + /** + * @if English + * The vertical distance between the upper left corner of the watermark and the upper left corner of the video canvas. Unit: + * pixels. + * @endif + * @if Chinese + * 水印左上角与视频画布左上角的垂直距离。单位为像素（pixel）。 + * @endif + */ + int offset_y; +}; + +/** + * @if English + * Video watermark settings. Three types of watermarks are supported. You can select one of the three types. + * @endif + * @if Chinese + * 视频水印设置，目前支持三种类型的水印，但只能其中选择一种水印生效。 + * @endif + */ +struct nertc_video_watermark_config { + /** + * @if English + * Video watermark type enumerations + * @endif + * @if Chinese + * 视频水印类型枚举。 + * @endif + */ + typedef enum { + /** + * @if English + * Image watermark. + * @endif + * @if Chinese + * 图片水印。 + * @endif + */ + kNERtcWatermarkTypeImage = 0, + /** + * @if English + * Text watermark. + * @endif + * @if Chinese + * 文字水印。 + * @endif + */ + kNERtcWatermarkTypeText, + /** + * @if English + * Timestamp watermark. + * @endif + * @if Chinese + * 时间戳水印。 + * @endif + */ + kNERtcWatermarkTypeTimestamp + }nertc_watermark_type; + + nertc_watermark_type watermark_type; + nertc_video_watermark_image_config image_watermarks; + nertc_video_watermark_text_config text_watermarks; + nertc_video_watermark_timestamp_config timestamp_watermark; +}; + +/* + * Returns the screenshot result. + * @param errorCode The error code. For more information, see {@link NERtcErrorCode}. + * @param image The screenshot. Images on macOS are in CGImageRef format. + * @endif + * @if Chinese + * 截图结果回调。 + * @param errorCode 错误码。详细信息请参考 {@link NERtcErrorCode}。 + * @param image 截图图片。默认为图片文件所在路径。 + * @endif + */ +typedef void (NERTC_CALL *on_take_snapshot_callback)(void* self, nertc_uid_t uid, nertc_video_stream_type stream_type, int error_code, void* image); + +/** + * @if English + * Log levels. + * @endif + * @if Chinese + * 日志级别。 + * @endif + * */ +typedef enum { + /** + * @if English + * Fatal. + * @endif + * @if Chinese + * Fatal 级别日志信息。 + * @endif + */ + kNERtcLogLevelFatal = 0, + /** + * @if English + * Error. + * @endif + * @if Chinese + * Error 级别日志信息。 + * @endif + */ + kNERtcLogLevelError = 1, + /** + * @if English + * Warning. The default log level. + * @endif + * @if Chinese + * Warning 级别日志信息。默认级别 + * @endif + */ + kNERtcLogLevelWarning = 2, + /** + * @if English + * Info. + * @endif + * @if Chinese + * Info 级别日志信息。 + * @endif + */ + kNERtcLogLevelInfo = 3, + /** + * @if English + * Detail Info. + * @endif + * @if Chinese + * Detail Info 级别日志信息。 + * @endif + */ + kNERtcLogLevelDetailInfo = 4, + /** + * @if English + * Verbos. + * @endif + * @if Chinese + * Verbos 级别日志信息。 + * @endif + */ + kNERtcLogLevelVerbos = 5, + /** + * @if English + * Debug. To get the complete log file, set the log level to this option. + * @endif + * @if Chinese + * Debug 级别日志信息。如果你想获取最完整的日志，可以将日志级别设为该等级。 + * @endif + */ + kNERtcLogLevelDebug = 6, + /** + * @if English + * No logs. + * @endif + * @if Chinese + * 不输出日志信息。 + * @endif + */ + kNERtcLogLevelOff = 7, +} nertc_log_level; + +/** + * @if English + * Video delivery strategy after publishing. + * @endif + * @if Chinese + * 视频推流后发送策略。 + * @endif + * */ +typedef enum { + /** + * @if English + * The client does not actively send the data stream. The stream is sent if the stream is subscribed. + * @endif + * @if Chinese + * 不主动发送数据流，被订阅后发送。 + * @endif + */ + kNERtcSendOnPubNone = 0, + /** + * @if English + * The client actively sends the mainstream. + * @endif + * @if Chinese + * 主动发送大流。 + * @endif + */ + kNERtcSendOnPubHigh = 1, + /** + * @if English + * The client actively sends the substream. + * @endif + * @if Chinese + * 主动发送小流。 + * @endif + */ + kNERtcSendOnPubLow = 1 << 1, + /** + * @if English + * The client actively sends the mainstream and the substream. + * @endif + * @if Chinese + * 主动发送大小流。 + * @endif + */ + kNERtcSendOnPubAll = kNERtcSendOnPubLow | kNERtcSendOnPubHigh, +} nertc_send_on_pub_type; + +/** + * @if English + * Configures private servers. + * @note To use private servers, contact technical support for help. + * @endif + * @if Chinese + * 私有化服务器配置项 + * @note 如需启用私有化功能，请联系技术支持获取详情。 + * @endif + */ +struct nertc_server_addresses { + /** + * @if English + * 获取通道信息服务器 + * @endif + * @if Chinese + * The channel server. + * @endif + */ + char channel_server[kNERtcMaxURILength]; + /** + * @if English + * The stats server. + * @endif + * @if Chinese + * 统计上报服务器 + * @endif + */ + char statistics_server[kNERtcMaxURILength]; + /** + * @if English + * The stats dispatch server. + * @endif + * @if Chinese + * 统计调度服务器 + * @endif + */ + char statistics_dispatch_server[kNERtcMaxURILength]; + /** + * @if English + * The stats backup server. + * @endif + * @if Chinese + * 统计备份服务器 + * @endif + */ + char statistics_backup_server[kNERtcMaxURILength]; + /** + * @if English + * The roomServer server. + * @endif + * @if Chinese + * roomServer服务器 + * @endif + */ + char room_server[kNERtcMaxURILength]; + /** + * @if English + * The compatibility configuration server. + * @endif + * @if Chinese + * 兼容性配置服务器 + * @endif + */ + char compat_server[kNERtcMaxURILength]; + /** + * @if English + * The NOS domain name resolution server. + * @endif + * @if Chinese + * nos 域名解析服务器 + * @endif + */ + char nos_lbs_server[kNERtcMaxURILength]; + /** + * @if English + * The default NOS upload server. + * @endif + * @if Chinese + * 默认nos 上传服务器 + * @endif + */ + char nos_upload_sever[kNERtcMaxURILength]; + /** + * @if English + * The NOS token server. + * @endif + * @if Chinese + * 获取NOS token 服务器 + * @endif + */ + char nos_token_server[kNERtcMaxURILength]; + /** + * @if English + * The cloud proxy server. + * @endif + */ + char cloud_proxy_server[kNERtcMaxURILength]; + /** + * @if English + * The websocket proxy server. + * @endif + */ + char websocket_proxy_server[kNERtcMaxURILength]; + /** + * @if English + * The quic proxy server. + * @endif + */ + char quic_proxy_server[kNERtcMaxURILength]; + /** + * @if English + * The media proxy server. + * @endif + */ + char media_proxy_server[kNERtcMaxURILength]; + /** + * @if English + * Specifies whether to use Ipv6. The default value is false. + * @endif + * @if Chinese + * 是否使用IPv6（默认false) + * @endif + */ + bool use_ipv6; +}; + +/** + * @if English + * Recording audio quality. + * @endif + * @if Chinese + * 录音音质 + * @endif + */ +typedef enum { + /** + * @if English + * Low quality + * @endif + * @if Chinese + * 低音质 + * @endif + */ + kNERtcAudioRecordingQualityLow = 0, + /** + * @if English + * medium quality + * @endif + * @if Chinese + * 中音质 + * @endif + */ + kNERtcAudioRecordingQualityMedium = 1, + /** + * @if English + * High quality + * @endif + * @if Chinese + * 高音质 + * @endif + */ + kNERtcAudioRecordingQualityHigh = 2, +} nertc_audio_recording_quality; + +typedef enum { + // 录制本地和所有远端用户混音后的音频（默认） + kNERtcAudioRecordingPositionMixedRecordingAndPlayback = 0, + // 仅录制本地用户的音频 + kNERtcAudioRecordingPositionRecording = 1, + // 仅录制所有远端用户的音频 + kNERtcAudioRecordingPositionMixedPlayback = 2 +} nertc_audio_recording_position; + +typedef enum { + // 音频录制缓存时间为0，实时写文件（默认） + kNERtcAudioRecordingCycleTime0 = 0, + // 音频录制缓存时间为10s，StopAudioRectording()后，将缓存都写到文件，文件数据时间跨度为: [0,10s] + kNERtcAudioRecordingCycleTime10 = 10, + // 音频录制缓存时间为60s，StopAudioRectording()后，将缓存都写到文件，文件数据时间跨度为: [0,60s] + kNERtcAudioRecordingCycleTime60 = 60, + // 音频录制缓存时间为360s，StopAudioRectording()后，将缓存都写到文件，文件数据时间跨度为: [0,360s] + kNERtcAudioRecordingCycleTime360 = 360, + // 音频录制缓存时间为900s，StopAudioRectording()后，将缓存都写到文件，文件数据时间跨度为: [0,900s] + kNERtcAudioRecordingCycleTime900 = 900 +} nertc_audio_recording_cycle_time; + +struct nertc_audio_recording_configuration { + // 录音文件在本地保存的绝对路径，需要精确到文件名及格式。例如：sdcard/xxx/audio.aac。请确保指定的路径存在并且可写。目前仅支持 + // WAV 或 AAC 文件格式。 + char file_path[kNERtcMaxURILength]; + + // 录音采样率（Hz），可以设为 16000、32000（默认）、44100 或 48000。 + int sample_rate; + + // 录音音质，只在 AAC 格式下有效。详细信息请参考 {@link NERtcAudioRecordingQuality}。 + nertc_audio_recording_quality quality; + + // 录音文件所包含的内容。详细信息请参考 {@link NERtcAudioRecordingPosition}。 + nertc_audio_recording_position position; + + // 录制过程中，循环缓存的最大时间长度，单位(s)。详细信息请参考 {@link NERtcAudioRecordingCycleTime}。 + nertc_audio_recording_cycle_time cycle_time; +}; + +/** + * @if English + * The error code of recording callbacks. + * @endif + * @if Chinese + * 录音回调事件错误码 + * @endif + */ +typedef enum { + /** + * @if English + * Unsupported recording file format. + * @endif + * @if Chinese + * 不支持的录音文件格式。 + * @endif + */ + kNERtcAudioRecordErrorSuffix = 1, + /** + * @if English + * fails to create a recording file. Reasons: + * - The application does not have the write permissions. + * - The file path does not exist. + * @endif + * @if Chinese + * 无法创建录音文件，原因通常包括： + * - 应用没有磁盘写入权限。 + * - 文件路径不存在。 + * @endif + */ + kNERtcAudioRecordOpenFileFailed = 2, + /** + * @if English + * Starts recording. + * @endif + * @if Chinese + * 开始录制。 + * @endif + */ + kNERtcAudioRecordStart = 3, + /** + * @if English + * An error occurs during recording. The typical reason is that the disk space is full and cannot be written. + * @endif + * @if Chinese + * 录制错误。原因通常为磁盘空间已满，无法写入。 + * @endif + */ + kNERtcAudioRecordError = 4, + /** + * @if English + * Recording is complete. + * @endif + * @if Chinese + * 完成录制。 + * @endif + */ + kNERtcAudioRecordFinish = 5, +} nertc_audio_recording_code; + +/** + * @if English + * Fallback options when the uplink and downlink connections are weak. + * @endif + * @if Chinese + * 上行、下行弱网时的回退选项。 + * @endif + */ +typedef enum { + /** + * @if English + * If the uplink or downlink network is unstable, the audio and video streams will not fall back, but the quality of the audio + * and video streams cannot be guaranteed. + * @note This option is only valid for the setLocalPublishFallbackOption method, and invalid for the + * setRemoteSubscribeFallbackOption method. + * @endif + * @if Chinese + * 上行或下行网络较弱时，不对音视频流作回退处理，但不能保证音视频流的质量。 + * @note 该选项只对 setLocalPublishFallbackOption 方法有效，对 setRemoteSubscribeFallbackOption 方法无效。 + * @endif + */ + kNERtcStreamFallbackDisabled = 0, + + /** + * @if English + * In an unstable downlink network, the SDK only receives low-definition streams that have low resolution and bitrate. + * @note This option is only valid for the setRemoteSubscribeFallbackOption method, and invalid for the + * setLocalPublishFallbackOption method. + * @endif + * @if Chinese + * 在下行网络条件较差的情况下，SDK 将只接收视频小流，即低分辨率、低码率视频流。 + * @note 该选项只对 setRemoteSubscribeFallbackOption 方法有效，对 setLocalPublishFallbackOption 方法无效。 + * @endif + */ + kNERtcStreamFallbackVideoStreamLow = 1, + + /** + * @if English + * - In an unstable uplink network, only the audio stream is published. + * - In an unstable downlink network, first try to receive only low-definition streams, which have low resolution and bitrate. + * If the video stream cannot be displayed due to network quality, then the stream falls back to the audio stream. + * @endif + * @if Chinese + * - 上行网络较弱时，只发布音频流。 + * - 下行网络较弱时，先尝试只接收视频小流，即低分辨率、低码率视频流。如果网络环境无法显示视频，则再回退到只接收音频流。 + * @endif + */ + kNERtcStreamFallbackAudioOnly = 2, +} nertc_stream_fallback_option; + +/** + * @if English + * Media stream encryption mode. + * @endif + * @if Chinese + * 媒体流加密模式。 + * @endif + * */ +typedef enum { + /** + * @if English + * 128-bit SM4 encryption, ECB mode. + * @endif + * @if Chinese + * 128 位 SM4 加密，ECB 模式。 + * @endif + */ + kNERtcGMCryptoSM4ECB = 0, +} nertc_encryption_mode; + +/** + * @if English + * Media stream encryption scheme. + * @endif + * @if Chinese + * 媒体流加密方案。 + * @endif + */ +struct nertc_encryption_config { + /** + * @if English + * Media stream encryption mode. For more information, see NERtcEncryptionMode. + * @endif + * @if Chinese + * 媒体流加密模式。详细信息请参考 NERtcEncryptionMode。 + * @endif + */ + nertc_encryption_mode mode; + /** + * @if English + * Media stream encryption key. The key is of string type. We recommend that you set the key to a string that contains only + * letters. + * @endif + * @if Chinese + * 媒体流加密密钥。字符串类型，推荐设置为英文字符串。 + * @endif + */ + char key[kNERtcEncryptByteLength]; +}; + +/** + * @if English + * Configurations of the last-mile network probe test. + * @endif + * @if Chinese + * Last mile 网络探测配置。 + * @endif + */ +struct nertc_lastmile_probe_config { + /** + * @if English + * Sets whether to test the uplink network. + *
Some users, for example, the audience in a kNERtcChannelProfileLiveBroadcasting channel, do not need such a test。 + * - true: test. + * - false: do not test. + * @endif + * @if Chinese + * 是否探测上行网络。 + *
不发流的用户，例如直播房间中的普通观众，无需进行上行网络探测。 + * - true: 探测。 + * - false: 不探测。 + * @endif + */ + bool probe_uplink; + /** + * @if English + * Sets whether to test the downlink network: + * - true: test. + * - false: do not test. + * @endif + * @if Chinese + * 是否探测下行网络。 + * - true: 探测。 + * - false: 不探测。 + * @endif + */ + bool probe_downlink; + /** + * @if English + * The expected maximum sending bitrate (bps) of the local user. + *
The value ranges between 100000 and 5000000. + *
We recommend setting this parameter according to the bitrate value set by setVideoConfig. + * @endif + * @if Chinese + * 本端期望的最高发送码率。 + *
单位为 bps，范围为 [100000, 5000000]。 + *
推荐参考 setVideoConfig 中的码率值设置该参数的值。 + * @endif + */ + uint32_t expected_uplink_bitratebps; + /** + * @if English + * The expected maximum receiving bitrate (bps) of the local user. The value ranges between 100000 and 5000000. + * @endif + * @if Chinese + * 本端期望的最高接收码率。 + *
单位为 bps，范围为 [100000, 5000000]。 + * @endif + */ + uint32_t expected_downlink_bitratebps; +}; + +/** + * @if English + * States of the last-mile network probe test. + * @endif + * @if Chinese + * Last mile 质量探测结果的状态。 + * @endif + */ +typedef enum { + /** + * @if English + * The last-mile network probe test is complete. + * @endif + * @if Chinese + * 表示本次 last mile 质量探测的结果是完整的。 + * @endif + */ + kNERtcLastmileProbeResultComplete = 1, + /** + * @if English + * The last-mile network probe test is incomplete and the bandwidth estimation is not available, probably due to limited test + * resources. + * @endif + * @if Chinese + * 表示本次 last mile 质量探测未进行带宽预测，因此结果不完整。通常原因为测试资源暂时受限。 + * @endif + */ + kNERtcLastmileProbeResultIncompleteNoBwe = 2, + /** + * @if English + * The last-mile network probe test is not carried out, probably due to poor network conditions. + * @endif + * @if Chinese + * 未进行 last mile 质量探测。通常原因为网络连接中断。 + * @endif + */ + kNERtcLastmileProbeResultUnavailable = 3, +} nertc_lastmile_probe_result_state; + +/** + * @if English + * The uplink or downlink last-mile network probe test result. + * @endif + * @if Chinese + * 单向 Last mile 网络质量探测结果报告。 + * @endif + */ +struct nertc_lastmile_probe_one_way_result { + /** + * @if English + * The network jitter (ms). + * @endif + * @if Chinese + * 网络抖动，单位为毫秒 (ms)。 + * @endif + */ + uint32_t jitter; + /** + * @if English + * The packet loss rate (%). + * @endif + * @if Chinese + * 丢包率（%）。 + * @endif + */ + uint32_t packet_loss_rate; + /** + * @if English + * The available band width (bps). + * @endif + * @if Chinese + * 可用网络带宽预估，单位为 bps。 + * @endif + */ + uint32_t available_band_width; +}; + +/** + * @if English + * The uplink and downlink last-mile network probe test result. + * @endif + * @if Chinese + * 上下行 Last mile 网络质量探测结果。 + * @endif + */ +struct nertc_lastmile_probe_result { + /** + * @if English + * The round-trip delay time (ms). + * @endif + * @if Chinese + * 往返时延，单位为毫秒（ms）。 + * @endif + */ + uint32_t rtt; + /** + * @if English + * The state of the probe test. + * @endif + * @if Chinese + * Last mile 质量探测结果的状态。 + * @endif + */ + nertc_lastmile_probe_result_state state; + /** + * @if English + * The uplink last-mile network probe test result. + * @endif + * @if Chinese + * 上行网络质量报告。 + * @endif + */ + nertc_lastmile_probe_one_way_result uplink_report; + /** + * @if English + * The downlink last-mile network probe test result. + * @endif + * @if Chinese + * 下行网络质量报告。 + * @endif + */ + nertc_lastmile_probe_one_way_result downlink_report; +}; +typedef enum { + /** + * @if English + * 0: Do not use the cloud proxy. + * @endif + * @if Chinese + * 0：关闭已设置的云代理。 + * @endif + */ + kNERtcTransportTypeNoneProxy = 0, + /** + * @if English + * 1: Sets the cloud proxy for the UDP protocol. + * @endif + * @if Chinese + * 1: 开启 UDP 协议的云代理。 + * @endif + */ + kNERtcTransportTypeUDPProxy = 1, +} nertc_transport_type; + +/** + * @if English + * Install audio driver plug-in result (only for Mac system) + * @endif + * @if Chinese + * 安装音频驱动插件结果（仅适用于 Mac 系统） + * @endif + */ +typedef enum { + /** + * @if English + * Install audio driver plug-in success. + * @endif + * @if Chinese + * 安装音频驱动插件成功 + * @endif + */ + kNERtcInstallCastAudioDriverSuccess = 0, + /** + * @if English + * Install audio driver plug-in because unauthorized. + * @endif + * @if Chinese + * 安装音频驱动插件未授 + * @endif + */ + kNERtcInstallCastAudioDriverNotAuthorized = 1, + /** + * @if English + * Install audio driver plug-in fail. + * @endif + * @if Chinese + * 安装音频驱动插件失败 + * @endif + */ + kNERtcInstallCastAudioDriverFailed = 2, +} nertc_install_cast_audio_driver_result; +/** + * @if English + * The reason why the virtual background is not successfully enabled or the message that confirms success. + * @since v4.6.0 + * @endif + * @if Chinese + * 虚拟背景未成功启用的原因或确认成功的信息。 + * @since v4.6.0 + * @endif + */ +typedef enum{ + /** + * @if English + * 0: The virtual background is successfully enabled. + * @endif + * @if Chinese + * 0: 虚拟背景开启成功。 + * @endif + */ + kNERtcVirtualBackgroundSourceStateReasonSuccess = 0, + /** + * @if English + * 1: The custom background image does not exist. Please check the value of `source` in VirtualBackgroundSource. + * @endif + * @if Chinese + * 1：自定义背景图片不存在。 请检查 VirtualBackgroundSource 中 `source` 的值。 + * @endif + */ + kNERtcVirtualBackgroundSourceStateReasonImageNotExist = 1, + /** + * @if English + * 2: The image format of the custom background image is invalid. Please check the value of `source` in + * VirtualBackgroundSource. + * @endif + * @if Chinese + * 2：自定义背景图片的图片格式无效。 请检查 VirtualBackgroundSource 中 `source` 的值。 + * @endif + */ + kNERtcVirtualBackgroundSourceStateReasonImageFormatNotSupported = 2, + /** + * @if English + * 3: The color format of the custom background image is invalid. Please check the value of `color` in + * VirtualBackgroundSource. + * @endif + * @if Chinese + * 3：自定义背景图片的颜色格式无效。 请检查 VirtualBackgroundSource 中 `color` 的值。 + * @endif + */ + kNERtcVirtualBackgroundSourceStateReasonColorFormatNotSupported = 3, + /** + * @if English + * 4: The device does not support using the virtual background. + * @endif + * @if Chinese + * 4：该设备不支持使用虚拟背景。 + * @endif + */ + kNERtcVirtualBackgroundSourceStateReasonDeviceNotSupported = 4 +} nertc_virtual_background_source_state_reason; + +/** + * @if English + * The custom background image. + * @since v4.6.0 + * @endif + * @if Chinese + * 自定义背景图像。 + * @since v4.6.0 + * @endif + */ +struct nertc_virtual_background_source { + /** + * @if English + * The type of the custom background image. + * @since v4.6.0 + * @endif + * @if Chinese + * 自定义背景图片的类型。 + * @since v4.6.0 + * @endif + */ + typedef enum { + /** + * @if English + * 1: (Default) The background image is a solid color. + * @endif + * @if Chinese + * 1：（默认）背景图像为纯色。 + * @endif + */ + kNERtcBackgroundColor = 1, + + /** + * @if English + * The background image is a file in PNG or JPG format. + * @endif + * @if Chinese + * 背景图像只支持 PNG 或 JPG 格式的文件。 + * @endif + */ + kNERtcBackgroundImage, + }nertc_background_source_type; + + /** + * @if English + * The type of the custom background image. See #NERtcBackgroundSourceType. + * @endif + * @if Chinese + * 自定义背景图片的类型。 请参阅#NERtcBackgroundSourceType。 + * @endif + */ + nertc_background_source_type background_source_type; + + /** + * @if English + * 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 `kNERtcBackgroundColor`. + * @endif + * @if Chinese + * 自定义背景图像的颜色。格式为RGB定义的十六进制整数，不带#号， + * 例如 0xFFB6C1 代表浅粉色。默认值为 0xFFFFFF，表示白色。取值范围是 [0x000000,0xFFFFFF]。如果该值无效， + * SDK 将原始背景图片替换为白色的图片 + * @note 该参数仅在自定义背景图片类型为`kNERtcBackgroundColor`时生效。 + * @endif + */ + unsigned int color; + + /** + * @if English + * The local absolute path of the custom background image. PNG and JPG formats are supported. + * @note This parameter takes effect only when the type of the custom background image is `kNERtcBackgroundImage`. + * @endif + * @if Chinese + * 自定义背景图片的本地绝对路径。支持 PNG 和 JPG 格式。 + * @note 该参数仅在自定义背景图片类型为`kNERtcBackgroundImage`时生效。 + * @endif + */ + char source[kNERtcMaxURILength]; +}; + +/** + 音频dump类型 + */ +typedef enum { + /** + * @if Chinese + * 仅输出.dump文件（默认） + * @since v4.6.0 + * @endif + */ + kNERtcAudioDumpTypePCM = 0, + /** + * @if Chinese + * 输出.dump和.wav文件 + * @since v4.6.0 + * @endif + */ + kNERtcAudioDumpTypeAll = 1, + /** + * @if Chinese + * 仅输出.wav文件 + * @since v4.6.0 + * @endif + */ + kNERtcAudioDumpTypeWAV = 2 +} nertc_audio_dump_type; + +/** 混响参数 */ +struct nertc_reverb_param { + /** + * @if English + * Wet sound signal. Value range: 0 ~ 1. The default value is 0.0f. + * @endif + * @if Chinese + * 湿信号，取值范围为 0 ~ 1，默认值为 0.0f。 + * @endif + */ + float wet_gain; + /** + * @if English + * Dry sound signal. Value range: 0 ~ 1. The default value is 1.0f. + * @endif + * @if Chinese + * 干信号，取值范围为 0 ~ 1，默认值为 1.0f。 + * @endif + */ + float dry_gain; + /** + * @if English + * Reverb damping. Value range: 0 ~ 1. The default value is 1.0f. + * @endif + * @if Chinese + * 混响阻尼，取值范围为 0 ~ 1，默认值为 1.0f。 + * @endif + */ + float damping; + /** + * @if English + * Room size. Value range: 0.1 ~ 2. The default value is 0.1f. + * @endif + * @if Chinese + * 房间大小，取值范围为 0.1 ~ 2，默认值为 0.1f。 + * @endif + */ + float room_size; + /** + * @if English + * Decay time. Value range: 0.1 ~ 20. The default value is 0.1f. + * @endif + * @if Chinese + * 持续强度（余响），取值范围为 0.1 ~ 20，默认值为 0.1f。 + * @endif + */ + float decay_time; + /** + * @if English + * Pre-delay. Value range: 0 ~ 1. The default value is 0.0f. + * @endif + * @if Chinese + * 延迟长度，取值范围为 0 ~ 1，默认值为 0.0f。 + * @endif + */ + float predelay; +}; + +typedef enum { + /** + * 默认模式 + */ + kNERtcRangeAudioModeDefault = 0, + /** + * 小组模式 + */ + kNERtcRangeAudioModeTeam = 1, +} nertc_range_audio_mode; + +/** + * @if Chinese + * 加入音视频房间时的一些可选信息。 + * @endif + */ +struct nertc_join_channel_options { + /** + * @if Chinese + * 自定义信息，最长支持 127 个字符。 + * @endif + */ + char custom_info[kNERtcCustomInfoLength]; + /** + * @if Chinese + * 权限密钥。能控制通话时长及媒体权限能力。 + * @endif + */ + char* permission_key; + + /** + * @if Chinese + * 小队号 + * @endif + */ + int32_t team_id; + /** + * @if Chinese + * 语音模式。 + * @endif + */ + nertc_range_audio_mode mode; + /** + * @if Chinese + * 语音接收范围。 + * @endif + */ + int audible_distance; +}; + +struct nertc_join_channel_options_ex { + /** + * @if Chinese + * 自定义信息，最长支持 127 个字符。 + * @endif + */ + char custom_info[kNERtcCustomInfoLength]; + /** + * @if Chinese + * 权限密钥。能控制通话时长及媒体权限能力。 + * @endif + */ + char* permission_key; + /** + * @if Chinese + * 小队号 + * @endif + */ + int32_t team_id; + /** + * @if Chinese + * 语音模式。 + * @endif + */ + nertc_range_audio_mode mode; + /** + * @if Chinese + * 语音接收范围。 + * @endif + */ + int audible_distance; +}; + +/** onUserJoined 回调的一些可选信息 */ +struct nertc_user_join_extra_info { + /** + * 自定义信息， 来源于远端用户joinChannel时填的 {@link NERtcJoinChannelOptions#custom_info}参数，默认为空字符串。 + */ + char custom_info[kNERtcCustomInfoLength]; +}; + +/** + * @if English + * @since v4.6.10 + * Media pub type. + * @endif + * @if Chinese + * @since v4.6.10 + * 媒体 pub 类型。 + * @endif + */ +typedef enum { + /** + * @if English + * Audio pub type. + * @endif + * @if Chinese + * 音频 pub 类型。 + * @endif + */ + NERtcMediaPubTypeAudio +} nertc_media_pub_type; + +/** + * @if English + * Beauty types + * @endif + * @if Chinese + * 美颜类型。 + * @endif + */ +typedef enum { + /** + * @if English + * Applies bright teeth. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 美牙。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyWhiteTeeth = 0, + + /** + * @if English + * Applies bright eyes. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 亮眼。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyLightEye, + + /** + * @if English + * Whitening. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 美白。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyWhiten, + + /** + * @if English + * Smoothing. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 磨皮。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautySmooth, + + /** + * @if English + * Applies a small nose. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 小鼻。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautySmallNose, + + /** + * @if English + * Adjusts the eye distance. The default value of intensity is 0.5. + * @endif + * @if Chinese + * 眼距调整。强度默认值为 0.5。 + * @endif + */ + kNERtcBeautyEyeDis, + + /** + * @if English + * Adjusts the eye angle. The default value of intensity is 0.5. + * @endif + * @if Chinese + * 眼角调整。强度默认值为 0.5。 + * @endif + */ + kNERtcBeautyEyeAngle, + + /** + * @if English + * Adjusts the mouth shape. The default value of intensity is 0.5. + * @endif + * @if Chinese + * 嘴型调整。强度默认值为 0.5。 + * @endif + */ + kNERtcBeautyMouth, + + /** + * @if English + * Applies big eyes. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 大眼。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyBigEye, + + /** + * @if English + * Applies a small face. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 小脸。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautySmallFace, + + /** + * @if English + * Adjusts the jaw. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 下巴调整。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyJaw, + + /** + * @if English + * Applies a thin face. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 瘦脸。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyThinFace, + + /** + * @if English + * Applies a ruddy face. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 红润。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyFaceRuddy, + + /** + * @if English + * Applies a long nose. The default value of intensity is 0.5. + * @endif + * @if Chinese + * 长鼻。强度默认值为 0.5。 + * @endif + */ + kNERtcBeautyLongNose, + + /** + * @if English + * Adjusts the philtrum. The default value of intensity is 0.5. + * @endif + * @if Chinese + * 人中。强度默认值为 0.5。 + * @endif + */ + kNERtcBeautyRenZhong, + + /** + * @if English + * Adjusts the mouth angle. The default value of intensity is 0.5. + * @endif + * @if Chinese + * 嘴角。强度默认值为 0.5。 + * @endif + */ + kNERtcBeautyMouthAngle, + + /** + * @if English + * Applies round eyes. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 圆眼。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyRoundEye, + + /** + * @if English + * Adjusts the eye corners. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 开眼角。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyOpenEyeAngle, + + /** + * @if English + * Applies a V-shaped face. The default value of intensity is 0.0. + * @endif + * @if Chinese + * V 脸。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyVFace, + + /** + * @if English + * Applies a thin jaw. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 瘦下颚。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyThinUnderjaw, + + /** + * @if English + * Applies a narrow face. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 窄脸。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyNarrowFace, + + /** + * @if English + * Adjusts the cheekbone. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 瘦颧骨。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyCheekBone, + + /** + * @if English + * Sharpens the face. The default value of intensity is 0.0. + * @endif + * @if Chinese + * 锐化。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyFaceSharpen, + + /** + * @if English + * @endif + * @if Chinese + * 调整嘴巴宽度。强度默认值为 0.5。 + * @endif + */ + kNERtcBeautyMouthWider, + + /** + * @if English + * @endif + * @if Chinese + * 祛抬头纹。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyForeheadWrinkles, + + /** + * @if English + * @endif + * @if Chinese + * 祛黑眼圈。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyDarkCircles, + + /** + * @if English + * @endif + * @if Chinese + * 祛法令纹。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautySmileLines, + + /** + * @if English + * @endif + * @if Chinese + * 短脸。强度默认值为 0.0。 + * @endif + */ + kNERtcBeautyShortFace +} nertc_beauty_effect_type; +/** + * 空间音效房间大小 + */ +typedef enum { + /** + * 小房间 + */ + kNERtcSpatializerRoomCapacitySmall = 0, + + /** + * 中等大小房间 + */ + kNERtcSpatializerRoomCapacityMedium = 1, + + /** + * 大房间 + */ + kNERtcSpatializerRoomCapacityLarge = 2, + + /** + * 巨大房间 + */ + kNERtcSpatializerRoomCapacityHuge = 3, + + /** + * 无房间效果 + */ + kNERtcSpatializerRoomCapacityNone = 4 +} nertc_spatializer_room_capacity; +/** + * 空间音效中房间材质名称 + */ +typedef enum { + /** + * 透明的 + */ + kNERtcSpatializerMaterialTransparent = 0, + /** + * 声学天花板，未开放 + */ + kNERtcSpatializerMaterialAcousticCeilingTiles, + /** + * 砖块，未开放 + */ + kNERtcSpatializerMaterialBrickBare, + /** + * 涂漆的砖块，未开放 + */ + kNERtcSpatializerMaterialBrickPainted, + /** + * 粗糙的混凝土块，未开放 + */ + kNERtcSpatializerMaterialConcreteBlockCoarse, + /** + * 涂漆的混凝土块，未开放 + */ + kNERtcSpatializerMaterialConcreteBlockPainted, + /** + * 厚重的窗帘 + */ + kNERtcSpatializerMaterialCurtainHeavy, + /** + * 隔音的玻璃纤维，未开放 + */ + kNERtcSpatializerMaterialFiberGlassInsulation, + /** + * 薄的的玻璃，未开放 + */ + kNERtcSpatializerMaterialGlassThin, + /** + * 茂密的草地，未开放 + */ + kNERtcSpatializerMaterialGlassThick, + /** + * 草地 + */ + kNERtcSpatializerMaterialGrass, + /** + * 铺装了油毡的混凝土，未开放 + */ + kNERtcSpatializerMaterialLinoleumOnConcrete, + /** + * 大理石 + */ + kNERtcSpatializerMaterialMarble, + /** + * 金属，未开放 + */ + kNERtcSpatializerMaterialMetal, + /** + * 镶嵌木板的混凝土，未开放 + */ + kNERtcSpatializerMaterialParquetOnConcrete, + /** + * 石膏，未开放 + */ + kNERtcSpatializerMaterialPlasterRough, + /** + * 粗糙石膏，未开放 + */ + kNERtcSpatializerMaterialPlasterSmooth, + /** + * 光滑石膏，未开放 + */ + kNERtcSpatializerMaterialPlywoodPanel, + /** + * 木板，未开放 + */ + kNERtcSpatializerMaterialPolishedConcreteOrTile, + /** + * 石膏灰胶纸板，未开放 + */ + kNERtcSpatializerMaterialSheetrock, + /** + * 水面或者冰面，未开放 + */ + kNERtcSpatializerMaterialWaterOrIceSurface, + /** + * 木头天花板，未开放 + */ + kNERtcSpatializerMaterialWoodCeiling, + /** + * 木头枪板，未开放 + */ + kNERtcSpatializerMaterialWoodPanel, + /** + * 均匀分布，未开放 + */ + kNERtcSpatializerMaterialUniform +} nertc_spatializer_material_name; + +/** + * 空间音效渲染模式 + */ +typedef enum { + /** + * 立体声 panning + */ + kNERtcSpatializerRenderStereoPanning = 0, + /** + * 低复杂度双耳渲染(Binaural) + */ + kNERtcSpatializerRenderBinauralLowQuality, + /** + * 中复杂度双耳渲染(Binaural) + */ + kNERtcSpatializerRenderBinauralMediumQuality, + /** + * 高复杂度双耳渲染(Binaural) + */ + kNERtcSpatializerRenderBinauralHighQuality, + /** + * 仅房间音效 + */ + kNERtcSpatializerRenderRoomEffectsOnly +} nertc_spatializer_render_mode; + +/** + * 空间音效衰减模式 + */ +typedef enum { + /** + * 指数衰减模式 + */ + kNERtcDistanceRolloffLogarithmic = 0, + /** + * 线性衰减模式 + */ + kNERtcDistanceRolloffLinear, + /** + * 无衰减 + */ + kNERtcDistanceRolloffNone, +} nertc_distance_rolloff_model; + +/** 3D音效算法中坐标信息。*/ +struct nertc_position_info { + /** + 发声坐标，三个值分别表示x-左右，y-上下，z-前后 + */ + float speaker_position[3]; + /** + 发声旋转角度四元数,设置为0 + */ + float speaker_quaternion[4]; + /** + 头部听觉坐标，三个值分别表示x-左右，y-上下，z-前后 + */ + float head_position[3]; + /** + 头部听觉旋转方向，表示头部的朝向，四元组格式 + */ + float head_quaternion[4]; +}; + +/** 3D音效房间属性设置。*/ +struct nertc_spatializer_room_property { + /** + * 房间大小 #NERtcSpatializerRoomCapacity ，默认值 #kNERtcSpatializerRoomCapacitySmall + */ + nertc_spatializer_room_capacity room_capacity; + /** + * 房间材质 #NERtcSpatializerMaterialName ，默认值 #kNERtcSpatializerMaterialTransparent + */ + nertc_spatializer_material_name material; + /** + * 反射系数的比例因子，默认值1.0, 取值范围[1.0 30] + */ + float reflection_scalar; + /** + * 混响增益比例因子，默认值1.0, 取值范围[1.0 10] + */ + float reverb_gain; + /** + * 混响时间比例因子，RT60会和该值相乘，默认值1.0(无效果), 取值范围[1.0 30] + */ + float reverb_time; + /** + * 混响亮度，该值为正且增加时，增加高频成分，该值为负数时衰减高频成分，默认值0.0(无效果), 取值范围[-30 30] + */ + float reverb_brightness; +}; + + +/** + * @if English + * Configure the SDK using a JSON file to provide technical preview or special custom functionalities. Standardize JSON options. + * For more information, see setParameters. * + * @endif + * @if Chinese + * 通过 JSON 配置 SDK 提供技术预览或特别定制功能。以标准化方式公开 JSON 选项。详见 API setParameters。 + * @endif + */ +/** + * @if English + * bool value. True: Record the presenter. False: Do not record the presenter. The setting is valid before the call. + * @endif + * @if Chinese + * bool value. true: 录制主讲人, false: 不是录制主讲人。通话前设置有效。 + * @endif + */ +#define kNERtcKeyRecordHostEnabled "record_host_enabled" +/** + * @if English + * bool value, which determines whether to enable server audio recording. The default value is false. The setting is valid + * before the call. + * @endif + * @if Chinese + * bool value，启用服务器音频录制。默认值 false。通话前设置有效。 + * @endif + */ +#define kNERtcKeyRecordAudioEnabled "record_audio_enabled" +/** + * @if English + * bool value, which determines whether to enable server video recording. The default value is false. The setting is valid + * before the call. + * @endif + * @if Chinese + * bool value，启用服务器视频录制。默认值 false。通话前设置有效。 + * @endif + */ +#define kNERtcKeyRecordVideoEnabled "record_video_enabled" +/** + * @if English + * int value, NERtcRecordType. The setting is valid before the call. + * @endif + * @if Chinese + * int value, NERtcRecordType。通话前设置有效。 + * @endif + */ +#define kNERtcKeyRecordType "record_type" +/** + * @if English + * bool value, which determines whether to automatically subscribe to the audio stream when other users open the audio. The + * default value is true. The setting is valid before the call. + * @endif + * @if Chinese + * bool value，其他用户打开音频时，自动订阅。默认值 true。通话前设置有效。 + * @endif + */ +#define kNERtcKeyAutoSubscribeAudio "auto_subscribe_audio" +/** + * @if English + * bool value, which determines whether to manually subscribe to the audio stream when other users open the audio on ASL mode. The + * default value is false. The setting is valid before the call. + * @endif + * @if Chinese + * bool value，在ASL模式下手动订阅音频。默认值 false。通话前设置有效。 + * @endif + */ +#define kNERtcKeyEnableAudioASLManualSubscribe "enable_audio_asl_manual_subscribe" +/** + * @if English + * bool value, which determines whether to enable CDN relayed streaming. The default value is true. The setting is valid before + * the call. + * @endif + * @if Chinese + * bool value，开启旁路直播。默认值 false。通话前设置有效。 + * @endif + */ +#define kNERtcKeyPublishSelfStreamEnabled "publish_self_stream_enabled" +/** + * @if English + * int value, NERtcLogLevel, SDK outputs logs that are of less than or equal to this level. The default is kNERtcLogLevelInfo. + * @endif + * @if Chinese + * int value, NERtcLogLevel，SDK 输出小于或等于该级别的 log，默认为 kNERtcLogLevelInfo。 + * @endif + */ +#define kNERtcKeyLogLevel "log_level" +/** + * @if English + * bool value. Disable or enable AEC. The default value is true. + * @endif + * @if Chinese + * bool value. AEC 开关，默认值 true。 + * @endif + */ +#define kNERtcKeyAudioProcessingAECEnable "audio_processing_aec_enable" +/** + * @if English + * bool value. Enable or disable low level AEC. The default value is false, The option takes effect only of + * kNERtcKeyAudioProcessingAECEnable is enabled. + * @endif + * @if Chinese + * bool value. low level AEC 开关，默认值 false，需要 kNERtcKeyAudioProcessingAECEnable 打开才生效。 + * @endif + */ +#define kNERtcKeyAudioAECLowLevelEnable "audio_aec_low_level_enable" +/** + * @if English + * bool value. Enable or disable AGC. The default value is true. + * @endif + * @if Chinese + * bool value. AGC 开关，默认值 true。 + * @endif + */ +#define kNERtcKeyAudioProcessingAGCEnable "audio_processing_agc_enable" +/** + * @if English + * bool value. Enable or disable NS. The default value is true. + * @endif + * @if Chinese + * bool value. NS 开关，默认值 true。 + * @endif + */ +#define kNERtcKeyAudioProcessingNSEnable "audio_processing_ns_enable" +/** + * @if English + * bool value. Enable or disable AI NS. We recommend that you modify this option before calls. The default value is false. + * @endif + * @if Chinese + * bool value. AI NS 开关，建议通话前修改，默认值 false。 + * @endif + */ +#define kNERtcKeyAudioProcessingAINSEnable "audio_processing_ai_ns_enable" +/** + * @if English + * bool value. Enable or disable the audio mixing. The default value is false. + * @endif + * @if Chinese + * bool value. 输入混音开关，默认值 false。 + * @endif + */ +#define kNERtcKeyAudioProcessingExternalAudioMixEnable "audio_processing_external_audiomix_enable" +/** + * @if English + * bool value, which determines whether to use an earphone. true: uses an earphone. false: does not use an earphone. The default + * value is false. + * @endif + * @if Chinese + * bool value. 通知 SDK 是否使用耳机， true: 使用耳机, false: 不使用耳机，默认值 false。 + * @endif + */ +#define kNERtcKeyAudioProcessingEarphone "audio_processing_earphone" +/** + * @if English + * int value. NERtcSendOnPubType. Sets the video sending strategy, and sends the mainstream by calling kNERtcSendOnPubHigh by + * default. The setting is valid before the call. + * @endif + * @if Chinese + * int value. NERtcSendOnPubType；设置视频发送策略，默认发送大流 kNERtcSendOnPubHigh。通话前设置有效。 + * @endif + */ +#define kNERtcKeyVideoSendOnPubType "video_sendonpub_type" +/** + * @if English + * bool value. Enable or disable the 1v1 mode. The default value is disabled. The setting is valid before the call. + * @endif + * @if Chinese + * bool value. 1v1 模式开关，默认关闭。通话前设置有效。 + * @endif + */ +#define kNERtcKeyChannel1V1ModeEnabled "channel_1v1_mode_enabled" +/** + * @if English + * string value. APP identification, used to identify the user's product name. + * @endif + * @if Chinese + * string value. APP 标识，用于后台识别用户产品名称。 + * @endif + */ +#define kNERtcKeyExtraInfo "extra_info" +/** + * @if English + * int value. Automatic audio device selection policy. The default value is 0. + * - 0: Default device priority + * - 1: Available device priority + * @endif + * @if Chinese + * 音频设备自动选择策略。int 类型。默认值为 0。 + * - 0：优先选择默认设备。 + * - 1：优先选择可用设备。 + * @endif + */ +#define kNERtcKeyAudioDeviceAutoSelectType "audio_device_auto_select_type" +/** + * @if English + * Whether to return original volume when the local user is muted. Boolean value, default: false. + * - true：Return the original volume in `onLocalAudioVolumeIndication`. + * - false：Return the recording volume(0) in `onLocalAudioVolumeIndication`. + * @endif + * @if Chinese + * 本地用户静音时是否返回原始音量。 布尔值，默认值为 false。 + * - true：返回 `onLocalAudioVolumeIndication` 中的原始音量。 + * - false：返回 `onLocalAudioVolumeIndication` 中的录音音量，静音时为 0。 + * @endif + */ +#define kNERtcKeyEnableReportVolumeWhenMute "enable_report_volume_when_mute" +/** + * @if English + * BOOL - Specifies whether to enable the callback to return captured video data. This enables developers to get the raw video + * data. You can clear the video data by calling destroyEngine. The default value is NO. + * @endif + * @if Chinese + * 是否需要开启视频数据采集回调，开启后开发者可以获取到原始视频数据。 + *
布尔值，默认值 NO。 + *
开启后如果需要关闭，需要通过调用 destroyEngine 来清除。 + * @endif + */ +#define kNERtcKeyEnableVideoCaptureObserver "enable_video_capture_observer" +/** + * @if English + * BOOL - Specifies whether to prefer using hardware to encode video data. The default value is YES. We recommend that you set + * this value before you call setupEngineWithContext to initialize the INERtcEngine instance. Otherwise, the setting is applied + * the next time. + * @endif + * @if Chinese + * 是否优先使用硬件编码视频数据。 + *
布尔值，默认值 YES。 + *
请在初始化（setupEngineWithContext）之前设置该参数，否则该参数会在下次初始化之后生效。 + * @endif + */ +#define kNERtcKeyVideoPreferHWEncode "video_prefer_hw_encode" +/** + * @if English + * BOOL - Specifies whether to prefer using hardware to decode video data. The default value is true. We recommend that you set + * this value before you call setupEngineWithContext to initialize the INERtcEngine instance. Otherwise, the setting is applied + * the next time. + * @endif + * @if Chinese + * 是否优先使用硬件解码视频数据。 + *
布尔值，默认值 true。 + *
请在初始化（setupEngineWithContext）之前设置该参数，否则该参数会在下次初始化之后生效。 + * @endif + */ +#define kNERtcKeyVideoPreferHWDecode "video_prefer_hw_decode" + +/** + * 是否使用动态token加入通话。 布尔值，默认值为 false。 + * @note 默认不使用动态token，该功能需要在通话前调用 + * - true：使用动态token。 + * - false：不使用动态token。 + */ +#define kNERtcKeyEnableDynamicToken "enable_dynamic_token" +/** + * @if English + * BOOL - Specifies whether to turn on the rear camera if the camera is enabled for the first time. The default value is false. + * It's available only on iOS platform. + * @endif + * @if Chinese + * 第一次开启摄像头时，是否使用后摄像头。仅iOS平台有效。 + *
布尔值，默认值 false，即不使用后置摄像头。 + * @endif + */ +#define kNERtcKeyVideoStartWithBackCamera "video_start_with_back_camera" +/** + * @if English + * BOOL - Specifies whether to use metal rendering first. Otherwise, OpenGL rendering is applied. The default value is + * false. It's available only on iOS platform. + * @endif + * @if Chinese + * 是否优先使用 Metal 渲染。 + *
布尔值，默认值 false，即使用OpenGL 渲染。仅iOS平台有效。 + * @endif + */ +#define kNERtcKeyVideoPreferMetalRender "video_prefer_metal_render" +/** + * @if English + * BOOL -- Specifies whether to disable switching to the speakerphone when the system switches to the earpieces. The + * default value is false. If the value is set to true, the SDK is not allowed to switch to the speakerphone when the system + * switches to earpieces. Users need to handle the earpieces switching event.It's available only on iOS platform. + * @endif + * @if Chinese + * 当系统切换听筒或扬声器时，SDK 是否以系统设置为准。仅iOS平台有效。 + *
布尔值，默认为 false。 + * - true： 以系统设置为准。例如当系统切换为听筒时，应用的音频播放则自动转为听筒，开发者需要自行处理该切换事件。 + * - false： 以 SDK 设置为准，SDK 不允许用户通过系统变更音频播放路由为听筒或扬声器。例如当 SDK + * 设置为扬声器时，即使系统切换为听筒模式，SDK 也会自动将系统修改回扬声器模式。 + * @endif + */ +#define kNERtcKeyDisableOverrideSpeakerOnReceiver "disable_override_speaker_on_receiver" +/** + * @if English + * BOOL - Specifies whether to use echo reduction when the system sets the headset. The default value is false. If the value is + * set to YES, the SDK does not use the echo reduction in headset mode. The setting affects the audio quality of the headset + * in some mobile models.It's available only on iOS platform. + * @endif + * @if Chinese + * 设置耳机时不使用软件回声消除功能，默认值 false。如设置YES 则SDK在耳机模式下不使用软件回声消除功能，会对某些机型下 + * 耳机的音质效果有影响。仅iOS平台有效。 + * @endif + */ +#define kNERtcKeyDisableSWAECOnHeadset "disable_sw_aec_on_headset" +/** + * @if English + * Whether to enable bluetooth SCO.The default value is true.It's available only on Android platform. + * @endif + * @if Chinese + * 是否关闭蓝牙SCO.默认打开。仅Android平台有效。 + * @endif + */ +#define kNERtcKeyEnableAudioBluetoothSCO "enable_audio_bluetooth_sco" +/** + * @if English + * Whether to preview the front camera with mirror mode. Default: true. The setting enables the mirror mode.It's available only + * on Android platform. + * @endif + * @if Chinese + * 前置摄像头预览是否采用镜像模式。默认为 true，开启镜像模式。仅Android平台有效。 + * @endif + */ +#define kNERtcKeyEnableVideoMirrorWithFrontCamera "enable_video_mirror_with_front_camera" +/** + * @if English + * Video camera type.The default value is 1.It's available only on Android platform. + * @endif + * @if Chinese + * 摄像头类型。默认值为1.取值范围为0(unknown), 1, 2.仅Android平台有效。 + * @endif + */ +#define kNERtcKeyVideoCameraType "video_camera_type" + +/** + * @if English + * Returns a bitmap file path when you take snapshot.The default value is false. + * @endif + * @if Chinese + * 调用TakeSnapshot截图时返回图片文件路径。默认值为false。 + * @endif + */ +#define kNERtcKeyEnableSnapshotWithFile "enable_snapshot_with_file" + +/** +* @if English +* Specifies whether to automatically subscribe to video streams when other users turn on video. +* The default value is NO. +* @note +* You can change the subscription stautus. Local subscription status will not be affected if remote users resume +sending the video stream; but local settings will resume to be default if remote users rejoin the room. +* This method is only valid for windows. +* The setting is applied before you make a call. The setting is invalid if you specify the value during the call. +* @endif +* @if Chinese +* 是否订阅其他用户的视频流。 +*
布尔值，默认值为 false。 +* @note +- 订阅状态可以更改。远端用户重新发布推流视频，不影响本地用户的订阅状态；但远端用户退出房间重进后，本地恢复默认设置。 +- 该接口仅 windows 下有效。 +- 请在加入房间前设置该参数，通话中设置无效。 +* @endif +*/ +#define kNERtcKeyAutoSubscribeVideo "auto_subscribe_video" + +/** +* @if English +* BOOL - Specifies whether to automatically subscribe to data channel when other users turn on data channel. The setting is +* applied before you make a call. The setting is invalid If you specify the value during the call. The default value is NO. +* Note: The key of subscribeRemoteData must be set to NO if you use the method to control the data in your business. +* @endif +* @if Chinese +* 是否自动订阅其他用户的数据通道。 +*
布尔值，默认为 NO，即非自动订阅。 +* @note +* - 请在加入房间前设置该参数，通话中设置无效。 +* - 如果业务场景中使用 subscribeData 控制数据订阅，则该 Key 必须设置为 NO。 +* @endif +*/ +#define kNERtcKeyAutoSubscribeData "auto_subscribe_data" + +/** +* @if English +* Specifies whether to disable video decoder, the default value is false. +* When disable video decoder (true), the SDK will not decode the remote video and therefore will not render the received remote +* video. This parameter must be set before IRtcEngine::initialize and becomes invalid after the SDK is released. Usually used +* with IRtcEngineEx::setPreDecodeObserver. +* @since 4.6.25 +* @endif +* @if Chinese +* 指定是否关闭视频解码器，默认不关闭（false）。 +* 关闭（true）后 SDK 将不会解码远端视频，因此也不会渲染接收到的远端视频。 +* 需要在初始化 IRtcEngine::initialize 前设置，释放 SDK 后失效。 +* 一般配合 IRtcEngineEx::setPreDecodeObserver 使用。 +* @since 4.6.25 +* @endif +*/ +#define kNERtcKeyDisableVideoDecoder "disable_video_decoder" + +/** +* @if Chinese +* 切换SDK内部渲染模式 +*
int，默认值0。 +* - 0：选择默认渲染(win:d3d,Mac:metal)。 +* - 1：Mac下使用OpenGL。 +* - 2：Mac下使用Metal。 +* - 3：windows下使用SDL2。 +* @endif +*/ +#define kNERtcKeyVideoRenderType "sdk.prefer.video.render" + +/** 音频设备错误码。*/ +typedef enum{ + kNERtcAudioDeviceNoError = 0, + kNERtcAudioDeviceErrorInitRecording, + kNERtcAudioDeviceErrorStartRecording, + kNERtcAudioDeviceErrorStopRecording, + kNERtcAudioDeviceErrorInitPlayout, + kNERtcAudioDeviceErrorStartPlayout, + kNERtcAudioDeviceErrorStopplayout, + kNERtcAudioDeviceErrorCaptureThreadStop, + kNERtcAudioDeviceErrorPlayoutThreadStop, + kNERtcAudioDeviceErrorCaptureSampleRate, + kNERtcAudioDeviceErrorPlayoutSampleRate, + kNERtcAudioDeviceErrorConfigSession, + kNERtcAudioDeviceErrorCodeReporter +}nertc_audio_device_error; + +/** 视频设备错误码。*/ +typedef enum { + kNERtcVideoDeviceErrorNoFrame = 0, + kNERtcVideoDeviceErrorNotAvailableInBackground, + kNERtcVideoDeviceErrorUsingByAnotherClient, + kNERtcVideoDeviceErrorNotAvailableWithMultipleForegroundApps, +} nertc_video_device_error; + +/** 音频路由 仅iOS和Android有效*/ +typedef enum { + /** + * @if English + * Default + * @endif + * @if Chinese + * 系统默认 + * @endif + */ + kNERtcAudioOutputRoutingDefault = 0, + /** + * @if English + * Headset + * @endif + * @if Chinese + * 耳机 + * @endif + */ + kNERtcAudioOutputRoutingHeadset, + /** + * @if English + * Earpiece + * @endif + * @if Chinese + * 听筒 + * @endif + */ + kNERtcAudioOutputRoutingEarpiece, + /** + * @if English + * Loudspeaker + * @endif + * @if Chinese + * 扬声器 + * @endif + */ + kNERtcAudioOutputRoutingLoudspeaker, + /** + * @if English + * Bluetooth + * @endif + * @if Chinese + * 蓝牙外设 + * @endif + */ + kNERtcAudioOutputRoutingBluetooth, +} nertc_audio_output_routing; + +/** 网络类型 */ +typedef enum { + kNERtcNetworkTypeUnknown = 0, + kNERtcNetworkTypeEthernet, + kNERtcNetworkTypeWifi, + kNERtcNetworkType2G, + kNERtcNetworkType3G, + kNERtcNetworkType4G, + kNERtcNetworkType5G, + kNERtcNetworkTypeWWAN, + kNERtcNetworkTypeBluetooth, + kNERtcNetworkTypeNone +} nertc_network_type; + +struct nertc_camera_focus_and_exposure_info { + float center_x; + float center_y; + int32_t left; + int32_t top; + int32_t right; + int32_t bottom; +}; +/** + * @if English + * Audio session control permissions + *
The SDK has the permissions of Audio Session. + * @endif + * @if Chinese + * 音频会话控制权限。 + *
SDK 对 Audio Session 的控制权限。 + * @endif + */ +typedef enum { + /** + * @if English + * The SDK has full permissions and can control the Audio Session + * @endif + * @if Chinese + * 没有限制，SDK 可以完全控制 Audio Session 操作。 + * @endif + */ + kNERtcAudioSessionOperationRestrictionNone = 0, + /** + * @if English + * If you restrict the SDK to perform operations on the Audio Session, the SDK cannot configure the Audio Session + * @endif + * @if Chinese + * 限制 SDK 对 Audio Session 进行任何操作，SDK 将不能再对 Audio Session 进行任何配置。 + * @endif + */ + kNERtcAudioSessionOperationRestrictionAll, + /** + * @if English + * When a user leaves the room, the SDK will keep the Audio Session active. + * @endif + * @if Chinese + * 离开房间时，SDK 会保持 Audio Session 处于活动状态。 + * @endif + */ + kNERtcAudioSessionOperationRestrictionDeactivateSession, +} nertc_audio_session_operation_restriction; + +/** + * @if English + * Audio focus mode（Android only）. + * @endif + * @if Chinese + * 音频焦点模式（Android only）。 + * @endif + */ +typedef enum { + /** + * @if English + * No request for audio focus. + * @endif + * @if Chinese + * 不请求音频焦点。 + * @endif + */ + kNERtcAudioFocusOff = 0, + /** + * @if English + * Gains the audio focus in a long period. + * @endif + * @if Chinese + * 长时间获得焦点。 + * @endif + */ + kNERtcAudioFocusGain = 1, + + /** + * @if English + * Gains transient audio focus. Release the focus after losing it. Such as notification sounds. + * @endif + * @if Chinese + * 短暂性获得焦点，用完应立即释放，比如notification sounds。 + * @endif + */ + kNERtcAudioFocusGainTransient = 2, + + /** + * @if English + * Temporary requests for lowering the volume of other audio applications. Mixable playback is supportable. + * @endif + * @if Chinese + * 临时请求, 降低其他音频应用的声音，可混音播放。 + * @endif + */ + kNERtcAudioFocusGainTransientMayDuck = 3, + + /** + * @if English + * Gains transient audio focus to enable recording or audio recognition. + * @endif + * @if Chinese + * 短暂性获得焦点，录音或者语音识别。 + * @endif + */ + kNERtcAudioFocusGainTransientExclisive = 4, +}nertc_audio_focus_mode; + +/** +* @if English +* Position of a specified camera. +* @endif +* @if Chinese +* 指定的摄像头位置。 +* @endif +*/ +typedef enum { + /** + * @if English + * Front camera. + * @endif + * @if Chinese + * 前置摄像头。 + * @endif + */ + kNERtcCameraPositionBack = 0, + + /** + * @if English + * Rear camera. + * @endif + * @if Chinese + * 后置摄像头。 + * @endif + */ + kNERtcCameraPositionFront +}nertc_camera_position; + +/** + * @if Chinese + * 二维坐标点。 + * @endif + */ +struct nertc_point { + /** + * @if Chinese + * x 轴坐标。 + * @endif + */ + float x; + /** + * @if Chinese + * y轴坐标值。 + * @endif + */ + float y; +}; +/** + * @if English + * Video correction configuration + * @endif + * @if Chinese + * 视频图像畸变矫正相关设置。 + * @endif + */ +struct nertc_video_correction_configuration { + /** + * @if Chinese + * 矫正区域的左上顶点（x 和 y 的取值范围为 0 ~ 1 的浮点数） + * @endif + */ + nertc_point top_left; + /** + * @if Chinese + * 矫正区域的右上顶点（x 和 y 的取值范围为 0 ~ 1 的浮点数） + * @endif + */ + nertc_point top_right; + /** + * @if Chinese + * 矫正区域的左下顶点（x 和 y 的取值范围为 0 ~ 1 的浮点数） + * @endif + */ + nertc_point bottom_left; + /** + * @if Chinese + * 矫正区域的右下顶点（x 和 y 的取值范围为 0 ~ 1 的浮点数） + * @endif + */ + nertc_point bottom_right; + /** + * @if Chinese + * 画布宽度（单位 px，使用外部视频渲染时需要传递） + * @endif + */ + float canvas_width; + /** + * @if Chinese + * 画布高度（单位 px，使用外部视频渲染时需要传递） + * @endif + */ + float canvas_height; + /** + * @if Chinese + * 是否镜像显示（使用外部视频渲染时需要传递） + * @endif + */ + bool enable_mirror; +}; +#endif // NERTC_DEFINES_H diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_engine_events.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_engine_events.h new file mode 100644 index 0000000..e70365c --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_engine_events.h @@ -0,0 +1,1161 @@ +#ifndef NERTC_ENGINE_EVENTS_H +#define NERTC_ENGINE_EVENTS_H + +#include "nertc_engine_defines.h" +#include "nertc_error_code.h" +#include "nertc_warn_code.h" + +NERTC_BEGIN_DECLS + +struct nertc_engine_events { + struct nertc_engine* self; + /** + * @if English + * Occurs when the error occurs. + *
The callback is triggered to report an error related to network or media during SDK runtime. In most cases, the SDK + * cannot fix the issue and resume running. The SDK requires the app to take action or informs the user of the issue. + * @param error_code The error code. For more information, see NERtcDMErrorCode. + * @param msg Error description. + * @endif + * @if Chinese + * 发生错误回调。 + *
该回调方法表示 SDK 运行时出现了（网络或媒体相关的）错误。通常情况下，SDK上报的错误意味着SDK无法自动恢复，需要 App + * 干预或提示用户。 + * @param error_code 错误码。详细信息请参考 NERtcDMErrorCode + * @param msg 错误描述。 + * @endif + */ + void (NERTC_CALL *on_error)(void* self,int error_code, const char* msg); + /** + * @if English + * Occurs when a warning occurs. + *
The callback is triggered to report a warning related to network or media during SDK runtime. In most cases, the app + * ignores the warning message and the SDK resumes running. + * @param warn_code The warning code. For more information, see {@link NERtcWarnCode}. + * @param msg The warning description. + * @endif + * @if Chinese + * 发生警告回调。 + *
该回调方法表示 SDK 运行时出现了（网络或媒体相关的）警告。通常情况下，SDK 上报的警告信息 App 可以忽略，SDK 会自动恢复。 + * @param warn_code 警告码。详细信息请参考 {@link NERtcWarnCode}。 + * @param msg 警告描述。 + * @endif + */ + void (NERTC_CALL *on_warning)(void* self, int warn_code, const char* msg); + /** + * @if English + * Occurs when an API call finished. + *
This callback method indicates that the SDK has finished executing a user's API call. + * @param api_name The API name. + * @param error The execute result code. + * @param message The execute result message. + * @endif + * @if Chinese + * API调用结束回调。 + *
该回调方法表示 SDK 执行完了一个用户的API调用。 + * @param api_name API名称 + * @param error API执行结果错误码。 + * @param message API执行结果描述。 + * @endif + */ + void (NERTC_CALL *on_api_call_executed)(void* self, const char* api_name, nertc_error_code error_code, const char* msg); + /** + * @if English + * Allows a user to join a room. The callback indicates that the client has already signed in. + * @param cid The ID of the room that the client joins. + * @param uid Specifies the ID of a user. If you specify the uid in the joinChannel method, a specificed ID is returned at + * the time. If not, the ID automatically assigned by the CommsEase’s server is returned. + * @param result Indicates the result. + * @param elapsed The time elapsed from calling the joinChannel method to the occurrence of this event. Unit: milliseconds. + * @endif + * @if Chinese + * 加入房间回调，表示客户端已经登入服务器。 + * @param cid 客户端加入的房间 ID。 + * @param uid 用户 ID。 如果在 joinChannel 方法中指定了 uid，此处会返回指定的 ID; 如果未指定 + * uid，此处将返回云信服务器自动分配的 ID。 + * @param result 返回结果。 + * @param elapsed 从 joinChannel 开始到发生此事件过去的时间，单位为毫秒。 + * @endif + */ + void (NERTC_CALL *on_join_channel)(void* self, channel_id_t cid, nertc_uid_t uid, nertc_error_code result, uint64_t elapsed); + /** + * @if English + * Triggers reconnection. + *
In some cases, a client may be disconnected from the server, the SDK starts reconnecting. The callback is triggered + * when the reconnection starts. + * @param cid Specifies the ID of a room. + * @param uid Specifies the ID of a user. + * @endif + * @if Chinese + * 触发重连。 + *
有时候由于网络原因，客户端可能会和服务器失去连接，SDK会进行自动重连，开始自动重连后触发此回调。 + * @param cid 房间 ID。 + * @param uid 用户 ID。 + * @endif + */ + void (NERTC_CALL *on_reconnecting_start)(void* self, channel_id_t cid, nertc_uid_t uid); + /** + * @if English + * Occurs when the state of network connection is changed. + *
The callback is triggered when the state of network connection is changed. The callback returns the current state of + * network connection and the reason why the network state changes. + * @param state The state of current network connection. + * @param reason The reason why the network state changes. + * @endif + * @if Chinese + * 网络连接状态已改变回调。 + *
该回调在网络连接状态发生改变的时候触发，并告知用户当前的网络连接状态和引起网络状态改变的原因。 + * @param state 当前的网络连接状态。 + * @param reason 引起当前网络连接状态发生改变的原因。 + * @endif + */ + void (NERTC_CALL *on_connection_state_change)(void* self, nertc_connection_state_type state, nertc_reason_connection_changed_type reason); + /** + * @if English + * Occurs when the network type is changed. + *
The callback is triggered when network is changed. The callback returns the current network type. + * @param new_type The new type of current network. + * @endif + * @if Chinese + * 网络类型已经改变的回调。 + *
该回调在网络发生改变的时候触发，并告知用户当前的网络类型。 + * @param new_type 当前的网络类型。 + * @endif + */ + void (NERTC_CALL *on_network_type_changed)(void* self, nertc_network_type new_type); + /** + * @if English + * Occurs when a user rejoins a room. + *
If a client is disconnected from the server due to poor network quality, the SDK starts reconnecting. If the client and + * server are reconnected, the callback is triggered. + * @param cid The ID of the room that the client joins. + * @param uid The ID of a user. + * @param result The result. + * @param elapsed The time elapsed from reconnection to the occurrence of this event. Unit: milliseconds. + * @endif + * @if Chinese + * 重新加入房间回调。 + *
在弱网环境下，若客户端和服务器失去连接，SDK会自动重连。自动重连成功后触发此回调方法。 + * @param cid 客户端加入的房间 ID。 + * @param uid 用户 ID。 + * @param result 返回结果。 + * @param elapsed 从开始重连到发生此事件过去的时间，单位为毫秒。 + * @endif + */ + void (NERTC_CALL *on_rejoin_channel)(void* self, channel_id_t cid, nertc_uid_t uid, nertc_error_code result, uint64_t elapsed); + /** + * @if English + * Occurs when a user leaves a room. + *
After an app invokes the leaveChannel method, SDK prompts whether the app successfully leaves the room. + * @param result The result. + * @endif + * @if Chinese + * 退出房间回调。 + *
App 调用 leaveChannel 方法后，SDK 提示 App 退出房间是否成功。 + * @param result 返回结果。 + * @param channel_id 离开的channel的ID。 + * @endif + */ + void (NERTC_CALL *on_leave_channel)(void* self, nertc_error_code result, uint64_t channel_id); + /** + * @if English + * Network connection interruption. + * @note + * - The callback is triggered if the SDK fails to connect to the server three consecutive times after you successfully call + * the joinChannel method. + * - A client may be disconnected from the server in poor network connection. At this time, the SDK needs not automatically + * reconnecting until the SDK triggers the callback method. + * @param reason The reason why the network is disconnected. + * @endif + * @if Chinese + * 网络连接中断 + * @note + * - SDK 在调用 joinChannel 加入房间成功后，如果和服务器失去连接且连续 3 次重连失败，就会触发该回调。 + * - 由于非网络原因，客户端可能会和服务器失去连接，此时SDK无需自动重连，直接触发此回调方法。 + * @param reason 网络连接中断原因。 + * @endif + */ + void (NERTC_CALL *on_disconnect)(void* self, nertc_error_code reason); + /** + * @if English + * Occurs when a user changes the role in live streaming. + *
After the local user joins a room, the user can call the \ref IRtcEngine::setClientRole "setClientRole" to change the + * role. Then, the callback is triggered. For example, you can switch the role from host to audience, or from audience to + * host. + * @note In live streaming, if you join a room and successfully call this method to change the role, the following callbacks + * are triggered. + * - If the role changes from host to audience, the onClientRoleChange is locally triggered, and the \ref + * nertc::IRtcEngineEventHandler::onUserLeft "onUserLeft" is remotely triggered. + * - If the role is changed from audience to host, the onClientRoleChange callback is locally triggered, and the \ref + * nertc::IRtcEngineEventHandler::onUserJoined "onUserJoined" is remotely triggered. + * @param oldRole The role before the user changes the role. + * @param newRole The role after the change. + * @endif + * @if Chinese + * 直播场景下用户角色已切换回调。 + *
本地用户加入房间后，通过 \ref IRtcEngine::setClientRole "setClientRole" + * 切换用户角色后会触发此回调。例如主播切换为观众、从观众切换为主播。 + * @note 直播场景下，如果您在加入房间后调用该方法切换用户角色，调用成功后，会触发以下回调： + * - 主播切观众，本端触发onClientRoleChanged回调，远端触发\ref nertc::IRtcEngineEventHandler::onUserLeft "onUserLeft"回调。 + * - 观众切主播，本端触发onClientRoleChanged回调，远端触发\ref nertc::IRtcEngineEventHandler::onUserJoined + * "onUserJoined"回调。 + * @param oldRole 切换前的角色。 + * @param newRole 切换后的角色。 + * @endif + */ + void (NERTC_CALL *on_client_role_changed)(void* self, nertc_client_role old_role, nertc_client_role new_role); + /** + * @if English + * Occurs when a remote user joins the current room. + *
The callback prompts that a remote user joins the room and returns the ID of the user that joins the room. If the user + * ID already exists, the remote user also receives a message that the user already joins the room, which is returned by the + * callback. + * @param uid The ID of the user that joins the room. + * @param user_name The name of the remote user who joins the room. + * @endif + * @if Chinese + * 远端用户加入当前房间回调。 + *
该回调提示有远端用户加入了房间，并返回新加入用户的 + * ID；如果加入之前，已经有其他用户在房间中了，新加入的用户也会收到这些已有用户加入房间的回调。 + * @param uid 新加入房间的远端用户 ID。 + * @param user_name 新加入房间的远端用户名。 + * @param custom_info 该远端用户加入的额外信息。 + * @endif + */ + void (NERTC_CALL *on_user_joined)(void* self, nertc_uid_t uid, const char* user_name, const struct nertc_user_join_extra_info* custom_info); + /** + * @if English + * Occurs when a remote user leaves a room. + *
A message is returned indicates that a remote user leaves the room or becomes disconnected. In most cases, a user + * leaves a room due to the following reasons: The user exit the room or connections time out. + * - When a user leaves a room, remote users will receive callback notifications that users leave the room. In this way, users + * can be specified to leave the room. + * - If the connection times out, and the user does not receive data packets for a time period of 40 to 50 seconds, then the + * user becomes disconnected. + * @param uid The ID of the user that leaves the room. + * @param reason The reason why remote user leaves. + * @endif + * @if Chinese + * 远端用户离开当前房间的回调。 + *
提示有远端用户离开了房间（或掉线）。通常情况下，用户离开房间有两个原因，即正常离开和超时掉线： + * - 正常离开的时候，远端用户会收到正常离开房间的回调提醒，判断用户离开房间。 + * - 超时掉线的依据是，在一定时间内（40~50s），用户没有收到对方的任何数据包，则判定为对方掉线。 + * @param uid 离开房间的远端用户 ID。 + * @param reason 远端用户离开原因。 + * @param custom_info 该远端用户离开的额外信息。 + * @endif + */ + void (NERTC_CALL *on_user_left)(void* self, nertc_uid_t uid, nertc_session_leave_reason reason, const struct nertc_user_join_extra_info* custom_info); + /** + * @if English + * Occurs when a remote user enables audio. + * @param uid The ID of a remote user. + * @endif + * @if Chinese + * 远端用户开启音频的回调。 + * @param type 远端用户流类型。 + * @param uid 远端用户ID。 + * @endif + */ + void (NERTC_CALL *on_user_audio_start)(void* self, nertc_audio_stream_type type, nertc_uid_t uid); + /** + * @if English + * Occurs when a remote user disables audio. + * @param uid The ID of a remote user. + * @endif + * @if Chinese + * 远端用户停用音频的回调。 + * @param uid 远端用户ID。 + * @endif + */ + void (NERTC_CALL *on_user_audio_stop)(void* self, nertc_audio_stream_type type, nertc_uid_t uid); + /** + * @if English + * Occurs when a remote user enables video. + * @param uid The ID of a remote user. + * @param max_profile The resolution of video encoding measures the encoding quality. + * @endif + * @if Chinese + * 远端用户开启视频的回调。 + * @param type 远端用户流类型。 + * @param uid 远端用户ID。 + * @param max_profile 视频编码的分辨率，用于衡量编码质量。 + * @endif + */ + void (NERTC_CALL *on_user_video_start)(void* self, nertc_video_stream_type type, nertc_uid_t uid, nertc_video_profile_type max_profile); + /** + * @if English + * Occurs when a remote user disables video. + * @param uid The ID of a remote user. + * @endif + * @if Chinese + * 远端用户停用视频的回调。 + * @param type 远端用户流类型。 + * @param uid 远端用户ID。 + * @endif + */ + void (NERTC_CALL *on_user_video_stop)(void* self, nertc_video_stream_type type, nertc_uid_t uid); + /** + * @if English + * Occurs when screen sharing is paused/resumed/started/ended. + *
The method applies to Windows only. + * @since V4.2.0 + * @param status Screen capture status. For more information, see #nertc_screen_capture_status_t. + * @endif + * @if Chinese + * 屏幕共享状态变化回调。 + *
该方法仅适用于 Windows 平台。 + * @since V4.2.0 + * @param status 屏幕共享状态。详细信息请参考 #nertc_screen_capture_status_t 。 + * @endif + */ + void (NERTC_CALL *on_screen_capture_state_changed)(void* self, nertc_screen_capture_status status); + /** + * @if English + * Occurs when video configurations of remote users are updated. + * @param uid The ID of a remote user. + * @param max_profile The resolution of video encoding measures the encoding quality. + * @endif + * @if Chinese + * @param uid 远端用户 ID。 + * @param max_profile 视频编码的分辨率，用于衡量编码质量。 + * @endif + */ + void (NERTC_CALL *on_user_video_profile_update)(void* self, nertc_uid_t uid, nertc_video_profile_type max_profile); + /** + * @if English + * Callbacks that specify whether to mute remote users. + * @param uid The ID of a remote user. + * @param mute indicates whether to unmute the remote user. + * @endif + * @if Chinese + * 远端用户是否静音的回调。 + * @param type 音频流类型。 + * @param uid 远端用户ID。 + * @param mute 是否静音。 + * @endif + */ + void (NERTC_CALL *on_user_audio_mute)(void* self, nertc_audio_stream_type type, nertc_uid_t uid, bool mute); + /** + * @if English + * Occurs when a remote user stops or resumes sending video streams. + * @param uid The ID of a remote user. + * @param mute Whether to disable video streams. + * @endif + * @if Chinese + * 远端用户暂停或恢复发送视频流的回调。 + * @param type 视频流类型。 + * @param uid 远端用户ID。 + * @param mute 是否禁视频流。 + * @endif + */ + void (NERTC_CALL *on_user_video_mute)(void* self, nertc_video_stream_type type, nertc_uid_t uid, bool mute); + /** + * @if English + * Occurs when the audio routing changes. + * @param routing The current audio output routing. + * @endif + * @if Chinese + * 音频路由变化回调。 + * @param routing 当前音频输出路由。 + * @endif + */ + void (NERTC_CALL *on_audio_device_routing_did_change)(void* self, nertc_audio_output_routing routing); + /** + * @if English + * Occurs when the state of the audio device changes. + * @param device_id Device ID. + * @param device_type The type of the device. For more information, see nertc_audio_device_type_t. + * @param device_state The state of the audio device. + * @endif + * @if Chinese + * 音频设备状态更改的回调。 + * @param device_id 设备ID。 + * @param device_type 音频设备类型。详细信息请参考 nertc_audio_device_type_t。 + * @param device_state 音频设备状态。 + * @endif + */ + void (NERTC_CALL *on_audio_device_state_changed)(void* self,const char* device_id,nertc_audio_device_type device_type,nertc_audio_device_state device_state); + /** + * @if English + * Occurs when the default audio devices changes. + * @param device_id Device ID. + * @param device_type The type of the device. + * @endif + * @if Chinese + * 音频默认设备更改的回调。 + * @param device_id 设备ID。 + * @param device_type 音频设备类型。 + * @endif + */ + void (NERTC_CALL *on_audio_default_device_changed)(void* self, const char* device_id, nertc_audio_device_type device_type); + /** + * @if English + * Occurs when the state of the video device is changed. + * @param device_id Device ID. + * @param device_type The type of the video device. + * @param device_state The state of the video device. + * @endif + * @if Chinese + * 视频设备状态已改变的回调。 + * @param device_id 设备ID。 + * @param device_type 视频设备类型。 + * @param device_state 视频设备状态。 + * @endif + */ + void (NERTC_CALL *on_video_device_state_changed)(void* self,const char* device_id,nertc_video_device_type device_type,nertc_video_device_state device_state); + /** + * @if English + * Occurs when the camera focus position changes. + * The callback indicates that the camera focus position changes. + * The callback is triggered if a local user calls the setCameraFocusPosition method to change the focus position. + * @note The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official + * website of CommsEase and replace the audio-only SDK. + * @param info The new focusposition. + * @endif + * @if Chinese + * 摄像头对焦区域已改变回调。 + * 该回调表示相机的对焦区域发生了改变。 + * 该回调是由本地用户调用 setCameraFocusPosition 方法改变对焦位置触发的。 + * @note 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。 + * @param info 新的对焦区域位置。 + * @endif + */ + void (NERTC_CALL *on_camera_focus_changed)(void* self, const struct nertc_camera_focus_and_exposure_info* info); + /** + * @if English + * Occurs when the camera exposure position changes. + * The callback is triggered if a local user calls the setCameraExposurePosition method to change the exposure position. + * @note The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official + * website of CommsEase and replace the audio-only SDK. + * @param info The new exposure position. + * @endif + * @if Chinese + * 摄像头曝光区域已改变回调。 + * 该回调是由本地用户调用 setCameraExposurePosition方法改变曝光位置触发的。 + * @note 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。 + * @param info 新的曝光区域位置信息。 + * @endif + */ + void (NERTC_CALL *on_camera_exposure_changed)(void* self, const struct nertc_camera_focus_and_exposure_info* info); + /** + * @if English + * Occurs when the first audio frame from a remote user is received. + * @param uid The ID of a remote user whose audio streams are sent. + * @endif + * @if Chinese + * 已接收到远端音频首帧的回调。 + * @param type 音频流类型。 + * @param uid 远端用户 ID，指定是哪个用户的音频流。 + * @endif + */ + void (NERTC_CALL *on_first_audio_data_received)(void* self, nertc_audio_stream_type type, nertc_uid_t uid); + /** + * @if English + * Occurs when the first video frame from a remote user is displayed. + *
If the first video frame from a remote user is displayed in the view, the callback is triggered. + * @param uid The ID of a user whose audio streams are sent. + * @endif + * @if Chinese + * 已显示首帧远端视频的回调。 + * 第一帧远端视频显示在视图上时，触发此调用。 + * @param type 视频流类型。 + * @param uid 用户 ID，指定是哪个用户的视频流。 + * @endif + */ + void (NERTC_CALL *on_first_video_data_received)(void* self, nertc_video_stream_type type, nertc_uid_t uid); + /** + * @if English + * Occurs when the first audio frame from a remote user is decoded. + * @param uid The ID of a remote user whose audio streams are sent. + * @endif + * @if Chinese + * 已解码远端音频首帧的回调。 + * @param uid 远端用户 ID，指定是哪个用户的音频流。 + * @endif + */ + void (NERTC_CALL *on_first_audio_frame_decoded)(void* self, nertc_audio_stream_type type, nertc_uid_t uid); + /** + * @if English + * Occurs when the remote video is received and decoded. + *
If the engine receives the first frame of remote video streams, the callback is triggered. + * @param uid The ID of a user whose audio streams are sent. + * @param width The width of video streams (px). + * @param height The height of video streams(px). + * @endif + * @if Chinese + * 已接收到远端视频并完成解码的回调。 + *
引擎收到第一帧远端视频流并解码成功时，触发此调用。 + * @param type 视频频流类型。 + * @param uid 用户 ID，指定是哪个用户的视频流。 + * @param width 视频流宽（px）。 + * @param height 视频流高（px）。 + * @endif + */ + void (NERTC_CALL *on_first_video_frame_decoded)(void* self, nertc_video_stream_type type, nertc_uid_t uid, uint32_t width, uint32_t height); + /** + * @if English + * Occurs when video data are captured. + * @param data The video frame data. + * @param type The type of the video data. + * @param width The width of the video frame. + * @param height The height of the video frame. + * @param count Video plane count. + * @param offset Video offset. + * @param stride Video stride. + * @param rotation The video rotation angle. + * @endif + * @if Chinese + * 采集视频数据回调。 + + * @param data 采集视频数据。 + * @param type 视频类型。 + * @param width 视频宽度。 + * @param height 视频高度。 + * @param count 视频Plane Count。 + * @param offset 视频offset。 + * @param stride 视频stride。 + * @param rotation 视频旋转角度。 + * @endif + */ + void (NERTC_CALL *on_capture_video_frame)(void* self, + void* data, + nertc_video_type type, + uint32_t width, + uint32_t height, + uint32_t count, + uint32_t* offset, + uint32_t* stride, + nertc_video_rotation rotation); + /** + * @if English + * Occurs when the playback state of a local music file changes. + *
If you call the startAudioMixing method to play a mixing music file and the playback state changes, the callback is + * triggered. + * - If the playback of the music file ends normally, the state parameter returned in the response contains the corresponding + * status code knertc_audio_mixing_state_tFinished, and the error_code parameter contains kNERtcAudioMixingErrorOK. + * - If an error occurs in the playback, the knertc_audio_mixing_state_tFailed status code is returned, and the error_code + * parameter returned contains the corresponding reason. + * - If the local music file does not exist, the file format is not supported, or the URL of the online music file cannot be + * accessed, the error_code parameter returned contains kNERtcAudioMixingErrorCanNotOpen. + * @param state The playback state of the music file. For more information, see #nertc_audio_mixing_state_t. + * @param error_code The error code. For more information, see #nertc_audio_mixing_error_code_t. + * @endif + * @if Chinese + * 本地用户的音乐文件播放状态改变回调。 + *
调用 startAudioMixing 播放混音音乐文件后，当音乐文件的播放状态发生改变时，会触发该回调。 + * - 如果播放音乐文件正常结束，state 会返回相应的状态码 knertc_audio_mixing_state_tFinished，error_code 返回 + * kNERtcAudioMixingErrorOK。 + * - 如果播放出错，则返回状态码 knertc_audio_mixing_state_tFailed，error_code 返回相应的出错原因。 + * - 如果本地音乐文件不存在、文件格式不支持、无法访问在线音乐文件 URL，error_code都会返回 kNERtcAudioMixingErrorCanNotOpen。 + * @param state 音乐文件播放状态，详见 #nertc_audio_mixing_state_t. + * @param error_code 错误码，详见 #nertc_audio_mixing_error_code_t. + * @endif + */ + void (NERTC_CALL *on_audio_mixing_state_changed)(void* self, + nertc_audio_mixing_state state, + nertc_audio_mixing_error_code error_code); + /** + * @if English + * Occurs when the playback position of a local music file changes. + *
If you call the startAudioMixing method to play a mixing music file and the position of the playing operation changes, + * the callback is triggered. + * @param timestamp_ms The position of the music file playing. Unit: milliseconds. + * @endif + * @if Chinese + * 本地用户的音乐文件播放进度回调。 + *
调用 startAudioMixing 播放混音音乐文件后，当音乐文件的播放进度改变时，会触发该回调。 + * @param timestamp_ms 音乐文件播放进度，单位为毫秒 + * @endif + */ + void (NERTC_CALL *on_audio_mixing_timestamp_update)(void* self, uint64_t timestamp_ms); + /** + * @if English + * Occurs when the playback position of a local effect file changes. + *
If you call the playEffect method to play a effect file and the position of the playing operation + * changes, the callback is triggered. + * @param effect_id The effect file id.f + * @param timestamp_ms The position of the music file playing. Unit: milliseconds. + * @endif + * @if Chinese + * 本地用户的指定音效文件播放进度回调。 + * - 调用 \ref nertc::IRtcEngineEx::playEffect "playEffect"播放音效文件后，SDK 会触发该回调，默认每 1s 返回一次。 + * @since V4.6.29 + * @par 使用前提 + * 请在 IRtcEngineEventHandlerEx 接口类中通过 \ref nertc::IRtcEngine::initialize "initialize" 接口设置回调监听。 + * @par 参数说明 + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
**参数名称****类型****描述**
effect_iduint32_t指定音效文件的 ID。每个音效均有唯一的 ID。
timestamp_msuint64_t指定音效文件的当前播放进度。单位为毫秒。
+ * @endif + */ + void (NERTC_CALL *on_audio_effect_timestamp_update)(void* self, uint32_t effect_id, uint64_t timestamp_ms); + /** + * @if English + * Occurs when the playback of a music file ends. + *
After the audio effect ends the playback, the callback is triggered. + * @param effect_id The ID of the specified audio effect. Each audio effect has a unique ID. + * @endif + * @if Chinese + * 本地音效文件播放已结束回调。 + *
当播放音效结束后，会触发该回调。 + * @param effect_id 指定音效的 ID。每个音效均有唯一的 ID。 + * @endif + */ + void (NERTC_CALL *on_audio_effect_finished)(void* self, uint32_t effect_id); + /** + * @if English + * Occurs when the system prompts current local audio volume. + * - This callback is disabled by default. You can enable the callback by calling the \ref IRtcEngineEx::enableAudioVolumeIndication "enableAudioVolumeIndication" method. + * - After the callback is enabled, if a local user speaks, the SDK triggers the callback based on the time interval specified in the \ref IRtcEngineEx::enableAudioVolumeIndication "enableAudioVolumeIndication" method. + * - If a local user sets a mute by calling \ref IRtcEngineEx::muteLocalAudioStream "muteLocalAudioStream", the SDK sets the value of volume as 0, and calls back to the application layer. + * @param volume The volume of audio mixing. Value range: 0 to 100. + * @param enable_vad Whether human voice is detected. + * @endif + * @if Chinese + * 提示房间内本地用户瞬时音量的回调。 + * - 该回调默认禁用。可以通过 \ref IRtcEngineEx::enableAudioVolumeIndication "enableAudioVolumeIndication" 方法开启。 + * - 开启后，本地用户说话，SDK 会按 \ref IRtcEngineEx::enableAudioVolumeIndication "enableAudioVolumeIndication" 方法中设置的时间间隔触发该回调。 + * - 如果本地用户将自己静音（调用了 \ref IRtcEngineEx::muteLocalAudioStream "muteLocalAudioStream"），SDK 将音量设置为 0 后回调给应用层。 + * @param volume （混音后的）音量，取值范围为 [0,100]。 + * @param enable_vad 是否检测到人声。 + * @endif + */ + void (NERTC_CALL *on_local_audio_volume_indication)(void* self, int volume, bool enable_vad); + /** + * @if English + * Occurs when the system prompts the active speaker and the audio volume. + * By default, the callback is disabled. You can enable the callback by calling the enableAudioVolumeIndication method. After + * the callback is enabled, if a local user speaks, the SDK triggers the callback based on the time interval specified in the + * enableAudioVolumeIndication method. In the array of speakers returned: + * - If a uid is contained in the array returned in the last response but not in the array returned in the current response. + * The remote user with the uid does not speak by default. + * - If the volume is 0, the user does not speak. + * - If the array is empty, the remote user does not speak. + * @param speakers The array that contains the information about user IDs and volumes is nertc_audio_volume_info. + * @param speaker_number The size of speakers array, which indicates the number of speakers. + * @param total_volume The total volume (after audio mixing). Value range: 0 to 100. + * @endif + * @if Chinese + * 提示房间内谁正在说话及说话者瞬时音量的回调。 + *
该回调默认为关闭状态。可以通过 enableAudioVolumeIndication 方法开启。开启后，无论房间内是否有人说话，SDK 都会按 + * enableAudioVolumeIndication 方法中设置的时间间隔触发该回调。
在返回的 speakers 数组中: + * - 如果有 uid 出现在上次返回的数组中，但不在本次返回的数组中，则默认该 uid 对应的远端用户没有说话。 + * - 如果volume 为 0，表示该用户没有说话。 + * - 如果speakers 数组为空，则表示此时远端没有人说话。 + * @param speakers 每个说话者的用户 ID 和音量信息的数组: nertc_audio_volume_info + * @param speaker_number speakers 数组的大小，即说话者的人数。 + * @param total_volume （混音后的）总音量，取值范围为 [0,100]。 + * @endif + */ + void (NERTC_CALL *on_remote_audio_volume_indication)(void* self,const struct nertc_audio_volume_info* speakers,uint32_t speaker_number,int total_volume); + /** + * @if English + * Notifies to add the result of live stream. + *
The callback asynchronously returns the callback result of \ref IRtcEngineEx::addLiveStreamTask "addLiveStreamTask". + * For information about actual pushing state, see \ref IRtcEngineEventHandlerEx::onLiveStreamState "onLiveStreamState". + * @param task_id The ID of a stream-push task. + * @param url Task ID. + * @param error_code The result. + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 通知添加直播任务结果。 + *
该回调异步返回 \ref IRtcEngineEx::addLiveStreamTask "addLiveStreamTask" 接口的调用结果；实际推流状态参考 \ref + * IRtcEngineEventHandlerEx::onLiveStreamState "onLiveStreamState" + * @param task_id 任务id + * @param url 推流地址 + * @param error_code 结果 + * - 0: 调用成功； + * - 其他: 调用失败。 + * @endif + */ + void (NERTC_CALL *on_add_live_stream_task)(void* self, const char* task_id, const char* url, int error_code); + /** + * @if English + * Notifies to Updates the result of live stream. + *
The callback asynchronously returns the callback result of ref IRtcEngineEx::addLiveStreamTask "addLiveStreamTask". For + * information about actual pushing state, see \ref IRtcEngineEventHandlerEx::onLiveStreamState "onLiveStreamState". + * @param task_id The ID of a stream-push task. + * @param url The URL for the streaming task. + * @param error_code The result. + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 通知更新直播任务结果。 + * 该回调异步返回 \ref IRtcEngineEx::updateLiveStreamTask "updateLiveStreamTask" 接口的调用结果；实际推流状态参考 \ref + * IRtcEngineEventHandlerEx::onLiveStreamState "onLiveStreamState" + * @param task_id 任务id + * @param url 推流地址 + * @param error_code 结果 + * - 0: 调用成功； + * - 其他: 调用失败。 + * @endif + */ + void (NERTC_CALL *on_update_live_stream_task)(void* self, const char* task_id, const char* url, int error_code); + /** + * @if English + * Notifies to delete the result of live stream. + *
The callback asynchronously returns the callback result of ref IRtcEngineEx::addLiveStreamTask "addLiveStreamTask". For + * information about actual pushing state, see \ref IRtcEngineEventHandlerEx::onLiveStreamState "onLiveStreamState". + * @param task_id The ID of a task. + * @param error_code The result. + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 通知删除直播任务结果。 + *
该回调异步返回 \ref IRtcEngineEx::removeLiveStreamTask "removeLiveStreamTask" 接口的调用结果；实际推流状态参考 \ref + * IRtcEngineEventHandlerEx::onLiveStreamState "onLiveStreamState" + * @param task_id 任务id + * @param error_code 结果 + * - 0: 调用成功； + * - 其他: 调用失败。 + * @endif + */ + void (NERTC_CALL *on_remove_live_stream_task)(void* self, const char* task_id, int error_code); + /** + * @if English + * Notifies the status in live stream-pushing. + * @note The callback is valid in a call. + * @param task_id The ID of a task. + * @param url The URL for the streaming task. + * @param state #nertc_live_stream_state_code_t The state of live stream-pushing. + * - 505: Pushing. + * - 506: Pushing fails. + * - 511: Pushing ends. + * @endif + * @if Chinese + * 通知直播推流状态 + * @note 该回调在通话中有效。 + * @param task_id 任务id + * @param url 推流地址 + * @param state #nertc_live_stream_state_code_t, 直播推流状态 + * - 505: 推流中； + * - 506: 推流失败； + * - 511: 推流结束； + * @endif + */ + void (NERTC_CALL *on_live_stream_state_changed)(void* self, const char* task_id, const char* url, nertc_live_stream_state_code state); + /** + * @if English + * Occurs when howling is detected. + * When the distance between the sound source and the PA equipment is too close, howling may occur. The NERTC SDK supports the + * howling detection. When a howling signal is detected, the callback is automatically triggered until the howling stops. The + * application layer can prompt the user to mute the microphone or directly mute the microphone when the app receives the + * howling information returned by the callback. + * @note + * Howling detection is used in audio-only scenarios, such as audio chat rooms or online meetings. We recommend that you do + * not use howling detection in entertainment scenes that include background music. + * @param howling Whether a howling occurs. + * - true: Howling occurs. + * - false: Normal state. + * @endif + * @if Chinese + * 检测到啸叫回调。 + *
当声源与扩音设备之间因距离过近时，可能会产生啸叫。NERTC SDK + * 支持啸叫检测，当检测到有啸叫信号产生的时候，自动触发该回调直至啸叫停止。App + * 应用层可以在收到啸叫回调时，提示用户静音麦克风，或直接静音麦克风。 + * @note + * 啸叫检测功能一般用于语音聊天室或在线会议等纯人声环境，不推荐在包含背景音乐的娱乐场景中使用。 + * @param howling 是否出现啸叫 + * - true: 啸叫。 + * - false: 正常。 + * @endif + */ + void (NERTC_CALL *on_audio_howling)(void* self, bool howling); + /** + * @if English + * Occurs when the content of remote SEI is received. + *
After a remote client successfully sends SEI, the local client receives a message returned by the callback. + * @param[in] uid The ID of the user who sends the SEI. + * @param[in] data The received SEI data. + * @param[in] dataSize The size of received SEI data. + * @endif + * @if Chinese + * 收到远端流的 SEI 内容回调。 + *
当远端成功发送 SEI 后，本端会收到此回调。 + * @param[in] uid 发送该 sei 的用户 id + * @param[in] data 接收到的 sei 数据 + * @param[in] dataSize 接收到 sei 数据的大小 + * @endif + */ + void (NERTC_CALL *on_receive_sei_message)(void* self, nertc_uid_t uid, const uint8_t* data, uint32_t dataSize); + /** + * @if English + * Returns the audio recording state. + * @param code The status code of the audio recording. For more information, see NERtcAudioRecordingCode. + * @param file_path The path based on which the recording file is stored. + * @endif + * @if Chinese + * 音频录制状态回调。 + * @param code 音频录制状态码。详细信息请参考 NERtcAudioRecordingCode。 + * @param file_path 音频录制文件保存路径。 + * @endif + */ + void (NERTC_CALL *on_audio_recording)(void* self, nertc_audio_recording_code code, const char* file_path); + /** + * @if English + * Occurs when the state of the media stream is relayed. + * @since V4.3.0 + * @param state The state of the media stream. + * @param channel_name The name of the destination room where the media streams are relayed. + * @endif + * @if Chinese + * 跨房间媒体流转发状态发生改变回调。 + * @since V4.3.0 + * @param state 当前跨房间媒体流转发状态。详细信息请参考 #nertc_channel_media_relay_state_t + * @param channel_name 媒体流转发的目标房间名。 + * @endif + */ + void (NERTC_CALL *on_media_relay_state_changed)(void* self,nertc_channel_media_relay_state state, const char* channel_name); + /** + * @if English + * Occurs when events related to media stream relay are triggered. + * @since V4.3.0 + * @param event The media stream relay event. + * @param channel_name The name of the destination room where the media streams are relayed. + * @param error Specific error codes. + * @endif + * @if Chinese + * 媒体流相关转发事件回调。 + * @since V4.3.0 + * @param event 当前媒体流转发事件。详细信息请参考 #nertc_channel_media_relay_event_t 。 + * @param channel_name 转发的目标房间名。 + * @param error 相关错误码。详细信息请参考 #nertc_error_code_t 。 + * @endif + */ + void (NERTC_CALL *on_media_relay_event)(void* self,nertc_channel_media_relay_event event,const char* channel_name, nertc_error_code error); + /** + * @if English + * Occurs when the published local media stream falls back to an audio-only stream due to poor network conditions or switches + * back to audio and video stream after the network conditions improve.
If you call setLocalPublishFallbackOption and set + * option to #kNERtcStreamFallbackAudioOnly, this callback is triggered when the locally published stream falls back to + * audio-only mode due to poor uplink network conditions, or when the audio stream switches back to the audio and video stream + * after the uplink network conditions improve. + * @since V4.3.0 + * @param is_fallback The locally published stream falls back to audio-only mode or switches back to audio and video stream. + * - true: The published stream from a local client falls back to audio-only mode due to poor uplink network conditions. + * - false: The audio stream switches back to the audio and video stream after the upstream network condition improves. + * @param type The type of the video stream, such as mainstream and substream. + * @endif + * @if Chinese + * 本地发布流已回退为音频流、或已恢复为音视频流回调。 + *
如果您调用了设置本地推流回退选项 setLocalPublishFallbackOption 接口，并将 option 设置为 #kNERtcStreamFallbackAudioOnly + * 后，当上行网络环境不理想、本地发布的媒体流回退为音频流时，或当上行网络改善、媒体流恢复为音视频流时，会触发该回调。 + * @since V4.3.0 + * @param is_fallback 本地发布流已回退或已恢复。 + * - true： 由于网络环境不理想，发布的媒体流已回退为音频流。 + * - false：由于网络环境改善，从音频流恢复为音视频流。 + * @param type 对应的视频流类型，即主流或辅流。 + * @endif + */ + void (NERTC_CALL *on_publish_fallback_to_audio_only)(void* self, bool is_fallback, nertc_video_stream_type type); + /** + * @if English + * Occurs when the subscribed remote media stream falls back to an audio-only stream due to poor network conditions or + * switches back to the audio and video stream after the network condition improves.
If you call + * setLocalPublishFallbackOption and set option to #kNERtcStreamFallbackAudioOnly, this callback is triggered when the locally + * published stream falls back to audio-only mode due to poor uplink network conditions, or when the audio stream switches + * back to the audio and video stream after the uplink network condition improves. + * @since V4.3.0 + * @param uid The ID of a remote user. + * @param is_fallback The subscribed remote media stream falls back to audio-only mode or switches back to the audio and + * video stream. + * - true: The subscribed remote media stream falls back to audio-only mode due to poor downstream network conditions. + * - false: The subscribed remote media stream switches back to the audio and video stream after the downstream network + * condition improves. + * @param type The type of the video stream, such as mainstream and substream. + * @endif + * @if Chinese + * 订阅的远端流已回退为音频流、或已恢复为音视频流回调。 + *
如果你调用了设置远端订阅流回退选项 setRemoteSubscribeFallbackOption 接口并将 option 设置 #kNERtcStreamFallbackAudioOnly + * 后，当下行网络环境不理想、仅接收远端音频流时，或当下行网络改善、恢复订阅音视频流时，会触发该回调。 + * @since V4.3.0 + * @param uid 远端用户的 ID。 + * @param is_fallback 远端订阅流已回退或恢复： + * - true： 由于网络环境不理想，订阅的远端流已回退为音频流。 + * - false：由于网络环境改善，订阅的远端流从音频流恢复为音视频流。 + * @param type 对应的视频流类型，即主流或辅流。 + * @endif + */ + void (NERTC_CALL *on_subscribe_fallback_to_audio_only)(void* self, + nertc_uid_t uid, + bool is_fallback, + nertc_video_stream_type type); + /** + * @if English + * Reports the last mile network quality of the local user once every two seconds before the user joins the channel. + *
After the application calls the startLastmileProbeTest method, this callback reports once every five seconds the + * uplink and downlink last mile network conditions of the local user before the user joins the channel. + * @since V4.5.0 + * @param quality The last mile network quality. + * @endif + * @if Chinese + * 通话前网络上下行 last mile 质量状态回调。 + *
该回调描述本地用户在加入房间前的 last mile + * 网络探测的结果，以打分形式描述上下行网络质量的主观体验，您可以通过该回调预估本地用户在音视频通话中的网络体验。
在调用 + * startLastmileProbeTest 之后，SDK 会在约 5 秒内返回该回调。 + * @since V4.5.0 + * @param quality 网络上下行质量，基于上下行网络的丢包率和抖动计算，探测结果主要反映上行网络的状态。 + * @endif + */ + void (NERTC_CALL *on_lastmile_quality)(void* self, nertc_network_quality_type quality); + /** + * @if English + * Reports the last-mile network probe result. + *
This callback describes a detailed last-mile network detection report of a local user before joining a channel. The + * report provides objective data about the upstream and downstream network quality, including network jitter and packet loss + * rate. You can use the report to objectively predict the network status of local users during an audio and video call. + *
The SDK triggers this callback within 30 seconds after the app calls the startLastmileProbeTest method. + * @since V4.5.0 + * @param result The uplink and downlink last-mile network probe test result. + * @endif + * @if Chinese + * 通话前网络上下行 Last mile 质量探测报告回调。 + *
该回调描述本地用户在加入房间前的 last mile + * 网络探测详细报告，报告中通过客观数据反馈上下行网络质量，包括网络抖动、丢包率等数据。您可以通过该回调客观预测本地用户在音视频通话中的网络状态。 + *
在调用 startLastmileProbeTest 之后，SDK 会在约 30 秒内返回该回调。 + * @since V4.5.0 + * @param result 上下行 Last mile 质量探测结果。 + * @endif + */ + void (NERTC_CALL *on_lastmile_probe_result)(void* self, const struct nertc_lastmile_probe_result* result); + /** + * @if English + * Audio/Video Callback when banned by server. + * @since v4.6.0 + * @param isAudioBannedByServer indicates whether to ban the audio. + * - true: banned + * - false unbanned + * @param isVideoBannedByServer indicates whether to ban the video. + * - true: banned + * - false unbanned + * @endif + * @if Chinese + * 服务端禁言音视频权限变化回调。 + * @since v4.6.0 + * @param is_audio_banned 是否禁用音频。 + * - true：禁用音频。 + * - false：取消禁用音频。 + * @param is_video_banned 是否禁用视频。 + * - true：禁用视频。 + * - false：取消禁用视频。 + * @endif + */ + void (NERTC_CALL *on_media_right_changed)(void* self, bool is_audio_banned, bool is_video_banned); + /** + * @if English + * Gets notified if the audio driver plug-in is installed (only for Mac) + *
You can call {@link checkNECastAudioDriver} to install the audio driver plug-in and capture and play audio data in the Mac system + * @param result indicates the result of audio driver plug-in installation. For more information, see {@link NERtcInstallCastAudioDriverResult}. + * @endif + * @if Chinese + * 收到检测安装声卡的内容回调（仅适用于 Mac 系统）。 + *
在 Mac 系统上，您可以通过调用 checkNECastAudioDriver 为当前系统安装一个音频驱动，并让 SDK 通过该音频驱动捕获当前 Mac 系统播放出的声音。 + * @param result 安装虚拟声卡的结果。详细信息请参考 {@link NERtcInstallCastAudioDriverResult}。 + * @endif + */ + void (NERTC_CALL *on_check_necast_audio_driver_result)(void* self, nertc_install_cast_audio_driver_result result); + + /** + * @if English + * Reports whether the virtual background is successfully enabled. (beta feature) + * @since v4.6.0 + * After you call \ref IRtcEngine::enableVirtualBackground "enableVirtualBackground", the SDK triggers this callback + * to report whether the virtual background is successfully enabled. + * @note If the background image customized in the virtual background is in PNG or JPG format, the triggering of this + * callback is delayed until the image is read. + * @param enabled Whether the virtual background is successfully enabled: + * - true: The virtual background is successfully enabled. + * - false: The virtual background is not successfully enabled. + * @param reason The reason why the virtual background is not successfully enabled or the message that confirms + * success. See #NERtcVirtualBackgroundSourceStateReason. + * @endif + * @if Chinese + * 通知虚拟背景功能是否成功启用的回调。 + *
调用 \ref IRtcEngineEx::enableVirtualBackground "enableVirtualBackground" 方法后，SDK 返回此回调通知虚拟背景功能是否成功启用。 + * @since V4.6.0 + * @note 如果您设置虚拟背景为 PNG 或 JPG 格式的自定义图像，此回调会等到图像被完全读取后才会返回，因此会有一段时间的延迟。 + * @param enabled 是否成功启用虚拟背景。 + * - true：成功启用。 + * - false：未成功启用。 + * @param reason 虚拟背景功能未成功启用的原因或成功启用虚拟背景功能的通知。详细信息请参考 {@link NERtcVirtualBackgroundSourceStateReason}。 + * @endif + */ + void (NERTC_CALL *on_virtual_background_source_enabled)(void* self, bool enabled, nertc_virtual_background_source_state_reason reason); + + /** + * @if English + * Occurs when the local video watermark takes affect. + *
If you enables the local video watermark by calling \ref nertc::IRtcEngineEx::setLocalVideoWatermarkConfigs "setLocalVideoWatermarkConfigs", the SDK will trigger this callback. + * @since V4.6.10 + * @param videoStreamType Type of video stream, main stream or substream. For more information, see {@link video.NERtcVideoStreamType}. + * @param state Watermark status. For more information, see {@link NERtcConstants.NERtcLocalVideoWatermarkState}. + * @endif + * @if Chinese + * 本地视频水印生效结果回调。 + *
调用 \ref nertc::IRtcEngineEx::setLocalVideoWatermarkConfigs "setLocalVideoWatermarkConfigs" 接口启用本地视频水印后，SDK 会触发此回调。 + * @since V4.6.10 + * @param type 对应的视频流类型，即主流或辅流。详细信息请参考 {@link NERtcVideoStreamType}。 + * @param state 水印状态。详细信息请参考 {@link NERtcLocalVideoWatermarkState}。 + * @endif + */ + void (NERTC_CALL *on_local_video_watermark_state)(void* self, nertc_video_stream_type type, nertc_local_video_watermark_state state); + + /** + * @if English + * The right key is about to expire. + * Because the PermissionKey has a certain time effect, if the PermissionKey is about to expire during a call, the SDK + * will trigger the callback in advance to remind the App to update the Token. + * When receiving the callback, the user needs to regenerate a new PermissionKey on the server, + * and then call ref IRtcEngineEx:: updatePermissionKey "updatePermissionKey" to transfer the newly generated PermissionKey to the SDK. + * @param key Permission key value. + * @param error Relevant error code. Please refer to # NERtcErrorCode for details. + * @param timeout Timeout, in seconds, valid when successful. + * @endif + * @if Chinese + * 权限密钥即将过期事件回调。 + * - 由于 PermissionKey 具有一定的时效，在通话过程中如果 PermissionKey 即将失效，SDK 会提前 30 秒触发该回调，提醒用户更新 PermissionKey。 + * @since V4.6.29 + * @par 使用前提 + * 请在 IRtcEngineEventHandlerEx 接口类中通过 \ref IRtcEngine::initialize "initialize" 接口设置回调监听。 + * @par 相关接口 + * 在收到此回调后可以调用 \ref IRtcEngineEx::updatePermissionKey "updatePermissionKey" 方法更新权限密钥。 + * @endif + */ + void (NERTC_CALL *on_permission_key_will_expire)(void* self); + + /** + * @if English + * Update authority key event callback. + * @param key Permission key value. + * @param error Relevant error code. Please refer to # NERtcErrorCode for details. + * @param timeout Timeout, in seconds, valid when successful. + * @endif + * @if Chinese + * 更新权限密钥事件回调。 + * - 调用 \ref IRtcEngineEx::updatePermissionKey "updatePermissionKey" 方法主动更新权限密钥后，SDK 会触发该回调，返回权限密钥更新的结果。 + * @since V4.6.29 + * @par 使用前提 + * 请在 IRtcEngineEventHandlerEx 接口类中通过 \ref IRtcEngine::initialize "initialize" 接口设置回调监听。 + * @par 参数说明 + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
**参数名称****类型****描述**
keyconst char*新的权限密钥。
error \ref nertc::NERtcErrorCode "NERtcErrorCode" 错误码。
  • kNERtcErrChannelPermissionKeyError（30901）：权限密钥错误。
  • kNERtcErrChannelPermissionKeyTimeout（30902）：权限密钥超时。
timeoutint更新后的权限密钥剩余有效时间。单位为秒。
+ * @endif + */ + void (NERTC_CALL *on_update_permission_key)(void* self, const char* key, nertc_error_code error, int timeout); + + /** + * @if English + * Occurs when a remote user send data by data channel. + * @param uid The ID of a remote user. + * @param data The received data channel data. + * @param size The size of received data channel data. + * @endif + * @if Chinese + * 远端用户通过数据通道发送数据的回调。 + * @param uid 远端用户ID。 + * @param source_id 远端source ID。 + * @param data 数据。 + * @param size 接收数据长度。 + * @endif + */ + void (NERTC_CALL *on_user_data_receive_message)(void* self, nertc_uid_t uid, const char* source_id, void* data, uint64_t size); + + /** + * @if English + * Occurs when a remote user enables data channel. + * @param uid The ID of a remote user. + * @since V5.0.0 + * @endif + * @if Chinese + * 远端用户开启数据通道的回调。 + * @param uid 远端用户ID。 + * @since V5.0.0 + * @endif + */ + void (NERTC_CALL *on_user_data_start)(void* self, nertc_uid_t uid); + + /** + * @if English + * Occurs when a remote user disables data channel. + * @param uid The ID of a remote user. + * @endif + * @if Chinese + * 远端用户停用数据通道的回调。 + * @param uid 远端用户ID。 + * @endif + */ + void (NERTC_CALL *on_user_data_stop)(void* self, nertc_uid_t uid); + + /** + * @if English + * Occurs when a Remote user data channel status changed. + * @param uid The ID of a remote user. + * @param source_id The source id. + * @endif + * @if Chinese + * 远端用户数据通道状态变更回调。 + * @param uid 远端用户ID。 + * @param source_id 远端用户source ID。 + * @endif + */ + void (NERTC_CALL *on_user_data_state_changed)(void* self, nertc_uid_t uid, const char* source_id); + + /** + * @if English + * Occurs when a Remote user data channel buffer amount changed. + * @param uid The ID of a remote user. + * @param source_id The source id. + * @param previousAmount The amount before changed. + * @endif + * @if Chinese + * 远端用户数据通道buffer变更回调。 + * @param uid 远端用户ID。 + * @param source_id 远端用户source ID。 + * @param previousAmount 变更前大小。 + * @endif + */ + void (NERTC_CALL *on_user_data_buffered_amount_changed)(void* self, nertc_uid_t uid, const char* source_id, uint64_t previous_amount); +}; + +NERTC_END_DECLS + +#endif // NERTC_ENGINE_EVENTS_H diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_engine_ex.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_engine_ex.h new file mode 100644 index 0000000..55e9d63 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_engine_ex.h @@ -0,0 +1,4779 @@ +#ifndef NERTC_ENGINE_EX_H +#define NERTC_ENGINE_EX_H + +#include "nertc_engine_defines.h" +#include "nertc_media_stats_observer.h" +#include "nertc_engine_predecode_observer.h" +#include "nertc_engine_video_encoder_qos_observer.h" + +NERTC_BEGIN_DECLS + +/** + * @if English + * Create an IRtcChannel. + * @param[in] channel_name The name of the room. Users that use the same name can join the same room. The name must be of + * STRING type and must be 1 to 64 characters in length. The following 89 characters are supported: a-z, A-Z, 0-9, space, + * !#$%&()+-:;≤.,>? @[]^_{|}~”. + * @return IRtcChannel pointer + * - 0: 方法调用失败。 + * @endif + * @if Chinese + * 创建一个 IRtcChannel 对象 + * @param[in] channel_name 房间名。设置相同房间名称的用户会进入同一个通话房间。字符串格式，长度为1~ 64 + * 字节。支持以下89个字符：a-z, A-Z, 0-9, space, !#$%&()+-:;≤.,>? @[]^_{|}~” + * @return 返回 IRtcChannel 对象指针 + * - 0: 方法调用失败。 + * @endif + */ + NERTC_API struct nertc_channel* NERTC_CALL nertc_engine_create_channel(struct nertc_engine* self, const char* channel_name); + +/** + * @if English + * Gets the current connection status. + * @return Returns the current network status. #NERtcConnectionStateType. + * @endif + * @if Chinese + * 获取当前网络状态。 + * @return 当前网络状态。#NERtcConnectionStateType. + * @endif + */ +NERTC_API nertc_connection_state_type NERTC_CALL nertc_engine_get_connection_state(struct nertc_engine* self); + +/** + * @if English + * Enables or disabling publishing the local audio stream. The method is used to enable or disable publishing the local audio + * stream. + * @note + * - This method does not change the state of the audio-recording device because the audio-recording devices are not disabled. + * - The mute state is reset to unmuted after the call ends. + * @param[in] mute Mute or Unmute. + * - true: Mutes the local audio stream. + * - false: Unmutes the local audio stream (Default). + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 开关本地音频发送。该方法用于允许或禁止向网络发送本地音频流。 + * @note + * - 该方法不影响录音状态，因为并没有禁用录音设备。 + * - 静音状态会在通话结束后被重置为非静音 + * @param[in] type 音频流类型: + * @param[in] mute 静音/取消静音: + * - true: 静音本地音频 + * - false: 取消静音本地音频（默认） + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_mute_local_audio_stream(struct nertc_engine* self, nertc_audio_stream_type type, bool mute); + +/** + * @if English + * Sets the audio encoding profile. + * @note + * - Sets the method before calling the \ref IRtcEngine::joinChannel "joinChannel". Otherwise, the setting is invalid after + * \ref IRtcEngine::joinChannel "joinChannel". + * - In music scenarios, we recommend you to set the profile as kNERtcAudioProfileHighQuality. + * @param[in] profile Sets the sample rate, bitrate, encoding mode, and the number of channels. #NERtcAudioProfileType. + * @param[in] scenario Sets the type of an audio application scenario. #NERtcAudioScenarioType. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置音频编码属性。 + * @note + * - 该方法需要在 \ref IRtcEngine::joinChannel "joinChannel" 之前设置好， \ref IRtcEngine::joinChannel "joinChannel" + * 之后设置不生效。 + * - 音乐场景下，建议将 profile 设置为 kNERtcAudioProfileHighQuality。 + * @param[in] profile 设置采样率，码率，编码模式和声道数: #NERtcAudioProfileType 。 + * @param[in] scenario 设置音频应用场景: #NERtcAudioScenarioType 。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_audio_profile(struct nertc_engine* self, nertc_audio_profile_type profile, nertc_audio_scenario_type scenario); + +/** + * @if English + * Sets the voice changer effect for the SDK-preset voice. + * The method can add multiple preset audio effects to original human voices and change audio profiles. + * @note + * - You can call this method either before or after joining a room. By default, the audio effect is disabled after the call + * ends. + * - The method conflicts with setLocalVoicePitch. After you call this method, the voice pitch is reset to the default + * value 1.0. + * @param[in] type The preset voice changer effect. By default, the audio effect is disabled. For more information, see + * nertc::NERtcVoiceChangerType. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置 SDK 预设的人声的变声音效。 + * 设置变声音效可以将人声原因调整为多种特殊效果，改变声音特性。 + * @note + * - 此方法在加入房间前后都能调用，通话结束后重置为默认关闭状态。 + * - 此方法和 setLocalVoicePitch 互斥，调用此方法后，本地语音语调会恢复为默认值 1.0。 + * @param[in] type 预设的变声音效。默认关闭变声音效。详细信息请参考 nertc::NERtcVoiceChangerType 。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_audio_effect_preset(struct nertc_engine* self, nertc_voice_changer_type type); + +/** + * @if English + * Sets an SDK-preset voice beautifier effect. + * The method can set a SDK-preset voice beautifier effect for a local user who sends an audio stream. + * @note By default, the method is reset as disabled after the call ends. + * @param[in] type The present voice beautifier effect. By default, the voice beautifier effect is disabled. For more + * information, see nertc::NERtcVoiceBeautifierType. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置 SDK 预设的美声效果。 + * 调用该方法可以为本地发流用户设置 SDK 预设的人声美声效果。 + * @note 通话结束后重置为默认关闭 + * @param[in] type 预设的美声效果模式。默认关闭美声效果。详细信息请参考 nertc::NERtcVoiceBeautifierType 。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_voice_beautifier_preset(struct nertc_engine* self, nertc_voice_beautifier_type type); + +/** + * @if English + * Sets the voice pitch of a local voice. + * The method changes the voice pitch of the local speaker. + * @note + * - After the call ends, the setting changes back to the default value 1.0. + * - The method conflicts with setAudioEffectPreset. After you call this method, the preset voice beautifier effect will be + * removed. + * @param[in] pitch The voice frequency. Valid values: 0.5 to 2.0. Smaller values have lower pitches. The default + * value is 1, which That the pitch is not changed. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置本地语音音调。 + * 该方法改变本地说话人声音的音调。 + * @note + * - 通话结束后该设置会重置，默认为 1.0。 + * - 此方法与 setAudioEffectPreset 互斥，调用此方法后，已设置的变声效果会被取消。 + * @param[in] pitch 语音频率。可以在 [0.5, 2.0] 范围内设置。取值越小，则音调越低。默认值为 1.0，表示不需要修改音调。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_local_voice_pitch(struct nertc_engine* self, double pitch); + +/** + * @if English + * Sets the local voice equalization effect. You can customize the center frequencies of the local voice effects. + * @note You can call this method either before or after joining a room. By default, the audio effect is disabled after the + * call ends. + * @param[in] band_frequency Sets the band frequency. Value range: 0 to 9. Those numbers represent the respective 10-band + * center frequencies of the voice effects, including 31, 62, 125, 250, 500, 1k, 2k, 4k, 8k, and 16k Hz. + * @param[in] band_gain Sets the gain of each band (dB). Value range: -15 to 15. The default value is 0. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置本地语音音效均衡，即自定义设置本地人声均衡波段的中心频率。 + * @note 该方法在加入房间前后都能调用，通话结束后重置为默认关闭状态。 + * @param[in] band_frequency 频谱子带索引，取值范围是 [0-9]，分别代表 10 个频带，对应的中心频率是 + * [31，62，125，250，500，1k，2k，4k，8k，16k] Hz。 + * @param[in] band_gain 每个 band 的增益，单位是 dB，每一个值的范围是 [-15，15]，默认值为 0。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_local_voice_equalization(struct nertc_engine* self, nertc_voice_equalization_band band_frequency, int band_gain); + +/** + * @if English + * Unsubscribes from or subscribes to audio streams from specified remote users. + *
After a user joins a channel, audio streams from all remote users are subscribed by default. You can call this method + * to unsubscribe from or subscribe to audio streams from all remote users. + * @note When the kNERtcKeyAutoSubscribeAudio is enabled by default, users cannot manually modify the state of audio + * subscription. + * @param[in] uid The user ID. + * @param[in] subscribe + * - true: Subscribes to specified audio streams (default). + * - false: Unsubscribes from specified audio streams. + * @return + * - 0: Success. + * - 30005: State exception that is caused by the invalid interface if users enable the automatic subscription. + * - Other values: Failure. + * @endif + * @if Chinese + * 取消或恢复订阅指定远端用户音频流。 + *
加入房间时，默认订阅所有远端用户的音频流，您可以通过此方法取消或恢复订阅指定远端用户的音频流。 + * @note 当kNERtcKeyAutoSubscribeAudio默认打开时，用户不能手动修改音频订阅状态 + * @param[in] stream_type 音频流类型: kNERtcAudioStreamTypeMain主流音频，kNERtcAudioStreamTypeSub辅流音频。 + * @param[in] uid 指定用户的 ID。 + * @param[in] subscribe 是否订阅远端用户音频流。 + * - true: 订阅指定音频流（默认）。 + * - false: 取消订阅指定音频流。 + * @return + * - 0: 方法调用成功。 + * - 30005: 状态异常，可能是自动订阅打开，导致该接口无效。 + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_subscribe_remote_audio_stream(struct nertc_engine* self, nertc_audio_stream_type stream_type, nertc_uid_t uid, bool subscribe); + +/** + * @if English + * Unsubscribes or subscribes to audio streams from all remote users. + * @note + * - Call this method before or after joining the channel. + * @since V4.5.0 + * @param subscribe Whether to unsubscribe audio streams from all remote users. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 取消或恢复订阅所有远端用户的音频主流。 + *
加入房间时，默认订阅所有远端用户的音频主流，即 \ref nertc::IRtcEngineEx::setParameters "setParameters" 方法的 + * KEY_AUTO_SUBSCRIBE_AUDIO 参数默认设置为 true；只有当该参数的设置为 false 时，此接口的调用才会生效。 + * @since V4.5.0 + * @par 调用时机 + * 请在引擎初始化之后调用此接口，且该方法在加入房间前后均可调用。 + * @par 业务场景 + * 适用于重要会议需要一键全体静音的场景。 + * @note + * - 设置该方法的 subscribe 参数为 true 后，对后续加入房间的用户同样生效。 + * - 在开启自动订阅（默认）时，设置该方法的 subscribe 参数为 false 可以实现取消订阅所有远端用户的音频流，但此时无法再调用 \ref + * nertc::IRtcEngineEx::subscribeRemoteAudioStream "subscribeRemoteAudioStream" 方法单独订阅指定远端用户的音频流。 + * @par 参数说明 + * + * + * + * + * + * + * + * + * + * + * + *
**参数名称****类型****描述**
subscribebool是否订阅所有用户的音频主流：
  • true：订阅音频主流。
  • false：取消订阅音频主流。
+ * @par 示例代码 + * @code + * //订阅所有远端用户的音频主流 + * rtc_engine_->subscribeAllRemoteAudioStream(true); + * //取消订阅所有远端用户的音频主流 + * rtc_engine_->subscribeAllRemoteAudioStream(false); + * @endcode + * @return + * - 0（kNERtcNoError）：方法调用成功。 + * - 其他：方法调用失败。 + * - 30005（kNERtcErrInvalidState)：引擎未初始化。 + * - 30026：ASL 选路功能启用失败。 + * - 30400：Transceiver 未找到。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_subscribe_all_remote_audio_stream(struct nertc_engine* self, bool subscribe); + +/** + * @if English + * Sets the local audio stream can be subscribed by specified participants in a room. + *
All participants in the room can subscribe to the local audio stream by default. + * @note + * - The API must be called after a user joins a room. + * - The API cannot be called by user IDs out of the room. + * @since V4.6.10 + * @param[in] uidArray The list of user IDs that can subscribe to the local audio stream. + * @note The list contains all participants in a room. If the value is empty or null, all participants can subscribe to the + * local audio stream. + * @param[in] size The length of the uid_array array. + * @return + * - 0: success + * - Others: failure. + * @endif + * @if Chinese + * 设置自己的音频只能被房间内指定的人订阅。 + *
默认房间所有其他人都可以订阅自己的音频。 + * @note + * - 此接口需要在加入房间成功后调用。 + * - 对于调用接口时不在房间的 uid 不生效。 + * @since V4.6.10 + * @param[in] uid_array 可订阅自己音频的用户uid 列表。 + * @note 此列表为全量列表。如果列表为空或 null，表示其他所有人均可订阅自己的音频。 + * @param[in] size uid_array 的数组长度。 + * @return + * - 0：方法调用成功。 + * - 其他：方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_audio_subscribe_only_by(struct nertc_engine* self, nertc_uid_t* uid_array, uint32_t size); + +/** + * @if Chinese + * 你可以调用该方法指定只订阅的音频流。 + * @note + * - 此接口需要在加入房间成功后调用。 + * - 对于调用接口时不在房间的 uid 不生效。 + * @since V5.4.101 + * @param[in] uid_array 只订阅此 用户uid列表 的音频。 + * @note 此列表为全量列表。如果列表为空或 null，取消订阅白名单。 + * @param[in] size uid_array 的数组长度。 + * @return + * - 0：方法调用成功。 + * - 其他：方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_subscribe_audio_allow_list(struct nertc_engine* self, nertc_uid_t* uid_array, uint32_t size); + +/** + * @if Chinese + * 你可以调用该方法指定不订阅的音频流。 + * @note + * - 此接口需要在加入房间成功后调用。 + * - 对于调用接口时不在房间的 uid 不生效。 + * @since V5.4.101 + * @param[in] uid_array 不订阅此 用户uid列表 的音频。 + * @note 此列表为全量列表。如果列表为空或 null，取消订阅黑名单。 + * @param[in] size uid_array 的数组长度。 + * @return + * - 0：方法调用成功。 + * - 其他：方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_subscribe_audio_block_list(struct nertc_engine* self, nertc_uid_t* uid_array, uint32_t size); + +/** + * @if English + * Synchronizes the local time with the server time + * @since V4.6.10 + * @param enable specifies whether to enable precise synchronization of the local time with the server time + * - true: enables the precise synchronization + * - false: disables the precise synchronization. + * @return + * - 0: success + * - Others: failure + * @endif + * @if Chinese + * 开启精准对齐。 + * 通过此接口可以实现精准对齐功能，对齐本地系统与服务端的时间。 + * @since V4.6.10 + * @par 调用时机 + * 请在引擎初始化之后调用此接口，且该方法仅可在加入房间前调用。 + * @par 业务场景 + * 适用于 KTV 实时合唱的场景。 + * @par 参数说明 + * + * + * + * + * + * + * + * + * + * + * + *
**参数名称****类型****描述**
enablebool是否开启精准对齐功能：
  • true：开启精准对齐功能。
  • false：关闭精准对齐功能。
+ * @par 示例代码 + * @code + * if (nrtc_engine_) { + * nrtc_engine_->setStreamAlignmentProperty(truetrue); + * } + * @endcode + * @par 相关接口 + * 可以调用 \ref nertc::IRtcEngineEx::getNtpTimeOffset "getNtpTimeOffset" 方法获取本地系统时间与服务端时间的差值。 + * @return 无返回值。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_stream_alignment_property(struct nertc_engine* self, bool enable); + +/** + * @if English + * Gets the difference between the local time and the server time. + *
The method can sync the time between the client and server. To get the current server time, call + * (System.currentTimeMillis() - offset). + * @since V4.6.10 + * @return Difference between the local time and the server time. Unit: milliseconds(ms). If a user fails to join a room, a + * value of 0 is returned. + * @endif + * @if Chinese + * 获取本地系统时间与服务端时间差值。 + *
可以用于做时间对齐，通过 (毫秒级系统时间 - offset) 可能得到当前服务端时间。 + * @since V4.6.10 + * @return 本地与服务端时间差值，单位为毫秒（ms）。如果没有成功加入音视频房间，返回 0。 + * @endif + */ +NERTC_API int64_t NERTC_CALL nertc_engine_get_ntp_time_offset(struct nertc_engine* self); +/** + * @if English + * Sets permissions of the SDK over Audio Session. + *
This method is only applicable to the iOS platform. + *
This method controls the permissions of the SDK over Audio Session. By default, the SDK and the app have control over the + * Audio Session. However, in some cases, the app wants to restrict the SDK's permissions over Audio Session and uses other + * applications or third-party components to control Audio Session. The app can adjust the permissions of the SDK by calling + * this method.
You can call this method only before you join the room. + * @note If you call this method to restrict the SDK's permissions over Audio Session, the SDK cannot set Audio Session. You + * need to manage Audio Session or use a third-party component to operate Audio Session. + * @param restriction The restriction applied to the SDK for Audio Session. For more information, see {@link + * NERtcAudioSessionOperationRestriction}. + * @return The value returned. A value of 0 indicates that the operation is successful. + * @endif + * @if Chinese + * 设置 SDK 对 Audio Session 的控制权限。 + *
该方法仅适用于 iOS 平台。 + *
该方法限制 SDK 对 Audio Session 的操作权限。在默认情况下，SDK 和 App 对 Audio Session 都有控制权，但某些场景下，App + * 会希望限制 SDK 对 Audio Session 的控制权限，而使用其他应用或第三方组件对 Audio Session 进行操控。调用该方法可以实现该功能。 + *
该接口只能在入会之前调用。 + * @note 一旦调用该方法限制了 SDK 对 Audio Session 的控制权限， SDK 将无法对 Audio Session + * 进行相关设置，而需要用户自己或第三方组件进行维护。 + * @param restriction SDK 对 Audio Session 的控制权限。详细信息请参考 {@link NERtcAudioSessionOperationRestriction}。 + * @return 操作返回值，成功则返回 0 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_audio_session_operation_restriction(struct nertc_engine* self, nertc_audio_session_operation_restriction restriction); + +/** + * @if English + * Sets the audio focus mode. + *
This method is only applicable to the Android platform. + * @return {@code 0} A value of 0 returned indicates that the method call is successful. Otherwise, the method call fails. + * @endif + * @if Chinese + * 设置音频焦点模式。 + *
该方法仅适用于 Android 平台。 + * @return {@code 0} 方法调用成功，其他失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_audio_focus_mode(struct nertc_engine* self, nertc_audio_focus_mode focus_mode); +/** + * @if English + * Mutes or unmutes the audio playback device. + * @param muted The option whether to mute the playback device. By default, the setting is unmuted. + * @return The value returned. A value of 0 indicates that the operation is successful. + * @endif + * @if Chinese + * 设置是否静音音频播放设备。 + * @param muted 是否静音播放设备。默认为不静音状态。 + * @return 操作返回值，成功则返回 0 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_playout_device_mute(struct nertc_engine* self, bool muted); + +/** + * @if English + * Gets the mute status of the audio playback device. + * @param muted The option whether the device is muted. + * @return The value returned. A value of 0 indicates that the operation is successful. + * @endif + * @if Chinese + * 获取音频播放设备的静音状态。 + * @param muted 是否静音。 + * @return 操作返回值，成功则返回 0 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_get_playout_device_mute(struct nertc_engine* self, bool* muted); + +/** + * @if English + * Mutes or unmutes the audio capture device. + * @param muted The option whether to mute the audio capture device. The default setting is unmuted. + * @return The value returned. A value of 0 indicates that the operation is successful. + * @endif + * @if Chinese + * 设置是否静音音频采集设备。 + * @param muted 是否静音音频采集设备。默认为不静音。 + * @return 操作返回值，成功则返回 0 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_record_device_mute(struct nertc_engine* self, bool muted); + +/** + * @if English + * Checks whether the audio capture device is muted. + * @param muted The option whether the device is muted. + * @return The value returned. A value of 0 indicates that the operation is successful. + * @endif + * @if Chinese + * 查询当前音频采集设备是否静音。 + * @param muted 是否静音。 + * @return 操作返回值，成功则返回 0 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_get_record_device_mute(struct nertc_engine* self, bool* muted); + +/** + * @if English + * Checks whether the camera zooming feature is supported. + *
Make sure that you call this method after the camera starts. For example, you can call this method after you call + * startPreview or joinChannel. + * @note The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official + * website of CommsEase and replace the audio-only SDK. + * @return YES: The camera zooming feature is supported. NO: The camera zooming feature is not supported. + * @endif + * @if Chinese + * 检测设备当前使用的摄像头是否支持缩放功能。 + *
该方法需要在相机启动后调用，例如调用 startPreview 或 joinChannel 后。 + * @note 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。 + * @return YES 表示支持，NO 表示支持。 + * @endif + */ +NERTC_API bool NERTC_CALL nertc_engine_is_camera_zoom_supported(struct nertc_engine* self); + +/** + * @if English + * Checks whether the camera flash feature is supported. + * @note + * - In most cases, the app opens the front camera by default. If the front camera does not support the flash feature and you + * call the method, a value of NO is returned. If you want to check whether the rear camera supports the flash feature, before + * you call this method, you must first call switchCamera to switch the camera. + * - Make sure that you call this method after the camera starts. For example, you can call this method after you call + * startPreview or joinChannel. + * - The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official + * website of CommsEase and replace the audio-only SDK. + * @return YES: The camera flash feature is supported. NO: The camera flash feature is not supported. + * @endif + * @if Chinese + * 检测设备是否支持闪光灯常亮。 + * @note + * - 一般情况下，App 默认开启前置摄像头，因此如果设备前置摄像头不支持闪光灯，直接使用该方法会返回 + * NO。如果需要检查后置摄像头是否支持闪光灯，需要先使用switchCamera切换摄像头，再使用该方法。 + * - 该方法需要在相机启动后调用，例如调用 startPreview 或 joinChannel 后。 + * - 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。 + * @return YES 表示支持，NO 表示不支持。 + * @endif + */ +NERTC_API bool NERTC_CALL nertc_engine_is_camera_torch_supported(struct nertc_engine* self); + +/** + * @if English + * Checks whether the camera manual focus feature is supported. + * @note + * - Make sure that you call this method after the camera starts. For example, you can call this method after you call + * startPreview or joinChannel. + * - The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official + * website of CommsEase and replace the audio-only SDK. + * @return YES: The camera manual focus feature is supported. NO: The camera manual focus feature is not supported. + * @endif + * @if Chinese + * 检测设备是否支持手动对焦功能。 + * @note + * - 该方法需要在相机启动后调用，例如调用 startPreview 或 joinChannel 后。 + * - 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。 + * @return YES 表示支持，NO 表示不支持。 + * @endif + */ +NERTC_API bool NERTC_CALL nertc_engine_is_camera_focus_supported(struct nertc_engine* self); + +/** + * @if English + * Checks whether the camera exposure feature is supported. + * @note + * - Make sure that you call this method after the camera starts. For example, you can call this method after you call + * startPreview or joinChannel. + * - The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official + * website of CommsEase and replace the audio-only SDK. + * @return YES: The camera exposure feature is supported. NO: The camera exposure feature is not supported. + * @endif + * @if Chinese + * 检测设备是否支持手动曝光功能。 + * @note + * - 该方法需要在相机启动后调用，例如调用 startPreview 或 joinChannel 后。 + * - 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。 + * @return YES 表示支持，NO 表示不支持。 + * @endif + */ +NERTC_API bool NERTC_CALL nertc_engine_is_camera_exposure_position_supported(struct nertc_engine* self); + +/** + * @if English + * Sets the camera exposure position. + *
After you call the method, the onCameraExposureChanged callback is triggered on the local client. + * @note + * - Make sure that you call this method after the camera starts. For example, you can call this method after you call + * startPreview or joinChannel. + * - The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official + * website of CommsEase and replace the audio-only SDK. + * @param positionInView The exposure position point. + * @return The value returned. A value of 0 indicates that the operation is successful. + * @endif + * @if Chinese + * 设置当前摄像头手动曝光位置。 + *
成功调用该方法后，本地会触发 onCameraExposureChanged 回调。 + * @note + * - 该方法需要在相机启动后调用，例如调用 startPreview 或 joinChannel 后。 + * - 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。 + * @param positionInView 曝光位置点。 + * @return 操作返回值，成功则返回 0 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_camera_exposure_position(struct nertc_engine* self, float pointX, float pointY); + +/** + * @if English + * Enables or disables the camera flash feature. + * @note + * - Make sure that you call this method after the camera starts. For example, you can call this method after you call + * startPreview or joinChannel. + * - The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official + * website of CommsEase and replace the audio-only SDK. + * @param on YES: turn on. NO: turn off. + * @return The value returned. A value of 0 indicates that the operation is successful. + * @endif + * @if Chinese + * 设置是否打开闪光灯。 + * @note + * - 该方法需要在相机启动后调用，例如调用 startPreview 或 joinChannel 后。 + * - 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。 + * @param on YES 表示开启；NO 表示关闭。 + * @return 操作返回值，成功则返回 0 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_camera_torch_on(struct nertc_engine* self, bool on); + +/** + * @if English + * Check whether the flash is turned on on the device. + * @note The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official + * website of CommsEase and replace the audio-only SDK. + * @return YES: turned on; NO: turned off. + * @endif + * @if Chinese + * 查询设备是否开启了闪光灯。 + * @note 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。 + * @return YES 表示开启；NO 表示关闭。 + * @endif + */ +NERTC_API bool NERTC_CALL nertc_engine_is_camera_torch_on(struct nertc_engine* self); + +/** + * @if English + * Sets the current camera zoom ratio. + * @note + * - Make sure that you call this method after the camera starts. For example, you can call this method after you call + * startPreview or joinChannel. + * - Before you call this method, we recommend that you view the maximum zoom ratio supported by the camera by calling + * getCameraMaxZoom and set a zooming ratio as required. + * - The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official + * website of CommsEase and replace the audio-only SDK. + * @param factor The zoom ratio supported by the camera. + * @return The value returned. A value of 0 indicates that the operation is successful. + * @endif + * @if Chinese + * 设置当前摄像头缩放比例。 + * @note + * - 该方法需要在相机启动后调用，例如调用 startPreview 或 joinChannel 后。 + * - 建议在调用本接口前，先通过 getCameraMaxZoom 查看摄像头支持的最大缩放比例，并根据实际需求合理设置需要的缩放比例。 + * - 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。 + * @param factor 摄像头缩放比例。 + * @return 操作返回值，成功则返回 0 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_camera_zoom_factor(struct nertc_engine* self, float factor); + + /** + * @if English + * Gets the zoom ratio supported by the current camera. + * @return The current zoom ratio is returned. + * @endif + * @if Chinese + * 获取当前摄像头缩放比例。 + * @return 当前缩放比例。 + * @endif + */ +NERTC_API float NERTC_CALL nertc_engine_get_camera_current_zoom(struct nertc_engine* self); + +/** + * @if English + * Gets maximum zoom ratio supported by the camera. + * @note + * - Make sure that you call this method after the camera starts. For example, you can call this method after you call + * startPreview or joinChannel. + * - The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official + * website of CommsEase and replace the audio-only SDK. + * @return The maximum zoom ratio is returned. + * @endif + * @if Chinese + * 获取摄像头支持最大缩放比例。 + * @note + * - 该方法需要在相机启动后调用，例如调用 startPreview 或 joinChannel 后。 + * - 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。 + * @return 最大缩放比例。 + * @endif + */ +NERTC_API float NERTC_CALL nertc_engine_max_camera_zoom_scale(struct nertc_engine* self); + +/** + * @if English + * Sets the camera manual focus position. + *
After you call the method, the onNERtcCameraFocusChanged callback is triggered on the local client. + * @note + * - Make sure that you call this method after the camera starts. For example, you can call this method after you call + * startPreview or joinChannel. + * - The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official + * website of CommsEase and replace the audio-only SDK. + * @param focusX The horizontal coordinate of the touch point in the view. Value range: 0 to 1. + * @param focusY The vertical coordinate of the touch point in the view. Value range: 0 to 1. + * @return The value returned. A value of 0 indicates that the operation is successful. + * @endif + * @if Chinese + * 设置手动对焦位置。 + *
成功调用该方法后，本地会触发 onNERtcCameraFocusChanged 回调。 + * @note + * - 该方法需要在相机启动后调用，例如调用 startPreview 或 joinChannel 后。 + * - 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。 + * @param focusX 触摸点相对于视图的横坐标，范围为 0~1。 + * @param focusY 触摸点相对于视图的纵坐标，范围为 0~1。 + * @return 操作返回值，成功则返回 0 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_camera_focus_position(struct nertc_engine* self, float x, float y); + +/** +* @if Chinese +* 设置本地摄像头的视频主流或辅流采集配置。 +*
通过此接口可以设置本地摄像头采集的主流或辅流视频宽度、高度、旋转角度等。 +* @since V4.6.20 +* @par 调用时机 +* 请在初始化后调用该方法，且该方法在加入房间前后均可调用。 +* @par 业务场景 +* 在视频通话或直播中，SDK 自动控制摄像头的输出参数。默认情况下，SDK +* 会根据用户该接口的配置匹配最合适的分辨率进行采集。但是在部分业务场景中，如果采集画面质量无法满足实际需求，可以调用该接口调整摄像头的采集配置。 +* @note +* - 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。 +* - 调用该接口设置成功后，会自动重启摄像头采集模块。 +* @par 参数说明 +* +* +* +* +* +* +* +* +* +* +* +* +* +* +* +* +*
**参数名称****类型****描述**
type \ref nertc::NERtcVideoStreamType "NERtcVideoStreamType"视频通道类型：
  • kNERtcVideoStreamMain：主流。
  • kNERtcVideoStreamSub：辅流。
captureConfig \ref nertc::NERtcCameraCaptureConfig "NERtcCameraCaptureConfig"本地摄像头采集配置。
+* @par 示例代码 +* @code +* //设置本地摄像头主流采集配置 +* nertc::NERtcVideoStreamType type = nertc::NERtcVideoStreamType::kNERTCVideoStreamMain; +* nertc::NERtcCameraCaptureConfig video_config_ = {}; +* video_config_.captureWidth = 1920; // 编码分辨率的宽 +* video_config_.captureHeight = 1080; // 编码分辨率的高 +* setCameraCaptureConfig(type, video_config_); +* //设置本地摄像头辅流采集配置 +* nertc::NERtcVideoStreamType type = nertc::NERtcVideoStreamType::kNERTCVideoStreamSub; +* nertc::NERtcCameraCaptureConfig video_config_ = {}; +* video_config_.captureWidth = 1920; // 编码分辨率的宽 +* video_config_.captureHeight = 1080; // 编码分辨率的高 +* setCameraCaptureConfig(type, video_config_); +* @endcode +* @return +* - 0（kNERtcNoError）：方法调用成功。 +* - 其他：方法调用失败。 +* @endif +*/ +NERTC_API int NERTC_CALL nertc_engine_set_camera_capture_config(struct nertc_engine* self, nertc_video_stream_type stream_type,const struct nertc_camera_capture_config* config); + +/** +* @if Chinese +* 设置视频编码属性。 +*
通过此接口可以设置视频主流或辅流的编码分辨率、裁剪模式、码率、帧率、带宽受限时的视频编码降级偏好、编码的镜像模式、编码的方向模式参数，详细信息请参考[设置视频属性](https://doc.yunxin.163.com/docs/jcyOTA0ODM/zYwMTQyNzE)。 +* @since V4.6.20 +* @par 调用时机 +* 请在初始化后调用该方法，且该方法在加入房间前后均可调用。 +* @note +* - 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。 +* - +* 每个属性对应一套视频参数，例如分辨率、帧率、码率等。所有设置的参数均为理想情况下的最大值。当视频引擎因网络环境等原因无法达到设置的分辨率、帧率或码率的最大值时，会取最接近最大值的那个值。 +* - 此接口为全量参数配置接口，重复调用此接口时，SDK +* 会刷新此前的所有参数配置，以最新的传参为准。所以每次修改配置时都需要设置所有参数，未设置的参数将取默认值。 +* @par 参数说明 +* +* +* +* +* +* +* +* +* +* +* +* +* +* +* +* +*
**参数名称****类型****描述**
type \ref nertc::NERtcVideoStreamType "NERtcVideoStreamType"视频通道类型：
  • kNERTCVideoStreamMain：主流。
  • kNERTCVideoStreamSub：辅流。
config \ref nertc::NERtcVideoConfig "NERtcVideoConfig"视频编码属性配置。
+* @par 示例代码 +* @code +* nertc::NERtcVideoConfig video_config_ = {}; +* video_config_.width = 1920; // 编码分辨率的宽 +* video_config_.height = 1080; // 编码分辨率的高 +* video_config_.mirror_mode = nertc::kNERtcVideoMirrorModeAuto; // 视频镜像模式 +* video_config_.orientation_mode = nertc::kNERtcVideoOutputOrientationModeAdaptative; // 视频旋转的方向模式。 +* video_config_.max_profile = nertc::kNERtcVideoProfileHD1080P; // 视频编码配置 +* video_config_.crop_mode_ = nertc::kNERtcVideoCropModeDefault;//裁剪模式 +* video_config_.bitrate = 0; // 视频编码的码率 +* video_config_.min_bitrate = 0;//视频编码的最小码率 +* video_config_.framerate = 30; // 视频编码的帧率 +* video_config_.min_framerate = 2;// 视频编码的最小帧率 +* video_config_.degradation_preference = nertc::kNERtcDegradationDefault;// 带宽受限时的视频编码降级偏好 +* setVideoConfig(nertc::kNERTCVideoStreamMain, video_config_); +* @endcode +* @return +* - 0（kNERtcNoError）：方法调用成功。 +* - 其他：方法调用失败。 +* - 30005（kNERtcErrInvalidState）：引擎尚未初始化。 +* - 30300：Transiver 未找到。 +* @endif +*/ +NERTC_API int NERTC_CALL nertc_engine_set_video_config(struct nertc_engine* self, nertc_video_stream_type stream_type, const struct nertc_video_config* config); + +/** + * @if English + * Specifies whether to enable or disable the dual stream mode. + *
The method sets the single-stream mode or dual-stream mode. If the dual-stream mode is enabled, the receiver can choose + * to receive the high-quality stream or low-quality stream video. The high-quality stream has a high resolution and high + * bitrate. The low-quality stream has a low resolution and low bitrate. + * @note + * - The method applies to camera data only. Video streams from external input and screen sharing are not affected. + * - You can call this method before or after you join a room. After the method is set, it can take effect after restarting + * the camera. + * @param[in] enable Whether to enable dual-stream mode. + * - true: Enables the dual-stream mode. This is the default value. + * - false: Disables the dual-stream mode. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置是否开启视频大小流模式。 + *
该方法设置单流或者双流模式。发送端开启双流模式后，接收端可以选择接收大流还是小流。其中，大流指高分辨率、高码率的视频流，小流指低分辨率、低码率的视频流。 + * @note + * - 该方法只对摄像头数据生效，自定义输入、屏幕共享等视频流无效。 + * - 该方法在加入房间前后都能调用。设置后，会在摄像头重启后生效。 + * @param[in] enable 指定是否开启双流模式。 + * - true: （默认）开启双流模式。 + * - false: 关闭双流模式。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_enable_dual_stream_mode(struct nertc_engine* self, bool enable); + +/** + * @if English + * Sets the display mode for local substreams video of screen sharing. + * This method is used to set the display mode about the local view. The application can repeatedly call the method to change + * the display mode. + * @note You must set the local canvas for local substreams through setupLocalSubStreamVideoCanvas. + * @param[in] scaling_mode The video display mode. #NERtcVideoScalingMode. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置本地视图显示模式。 + * 该方法设置本地视图显示模式。 App 可以多次调用此方法更改显示模式。 + * @note 在打开屏幕共享前必须设置本地辅流画布。 + * @param[in] scaling_mode 视频显示模式: #NERtcVideoScalingMode + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_local_render_mode(struct nertc_engine* self, nertc_video_stream_type type, nertc_video_scaling_mode scaling_mode); + +/** + * @if English + * Sets the mirror mode of the local video. + * The method is used to set whether to enable the mirror mode for the local video. The mirror code determines whether to flip + * the screen view right or left. Mirror mode for local videos only affects what local users view. The views of remote users + * are not affected. App can repeatedly call this method to modify the mirror mode. + * @param[in] mirror_mode The video mirror mode. For more information, see {@link NERtcVideoMirrorMode}. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置本地视频镜像模式。 + * 该方法用于设置本地视频是否开启镜像模式，即画面是否左右翻转。 + * 本地的视频镜像模式仅影响本地用户所见，不影响远端用户所见。App 可以多次调用此方法更改镜像模式。 + * @param[in] mirror_mode 视频镜像模式。详细信息请参考 {@link NERtcVideoMirrorMode}。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_local_video_mirror_mode(struct nertc_engine* self, nertc_video_stream_type type, nertc_video_mirror_mode mirror_mode); + +/** + * @if English + * Sets display mode for remote views. + * This method is used to set the display mode for the remote view. App can repeatedly call this method to modify the display + * mode. + * @param[in] uid The ID of a remote user. + * @param[in] scaling_mode The video display mode. #NERtcVideoScalingMode. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置远端视图显示模式。 + * 该方法设置远端视图显示模式。App 可以多次调用此方法更改显示模式。 + * @param[in] uid 远端用户 ID。 + * @param[in] scaling_mode 视频显示模式: #NERtcVideoScalingMode + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_remote_render_mode(struct nertc_engine* self, nertc_uid_t uid, nertc_video_stream_type type, nertc_video_scaling_mode scaling_mode); + +/** + * @if English + * Enables video preview. + *
The method is used to enable local video preview before you join a room. Prerequisites for calling the API: + * - Calls \ref IRtcEngine::setupLocalVideoCanvas "setupLocalVideoCanvas" to set preview window. + * @note After the local video preview is enabled, you must first disable the local preview and call \ref + * IRtcEngineEx::stopVideoPreview "stopVideoPreview" before joining the room. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 开启视频预览。 + *
该方法用于在进入房间前启动本地视频预览。调用该 API 前，必须: + * - 调用 \ref IRtcEngine::setupLocalVideoCanvas "setupLocalVideoCanvas" 设置预览窗口； + * @note 启用了本地视频预览后，在进入房间前，本地预览必须先关闭，需要先调用 \ref IRtcEngineEx::stopVideoPreview + * "stopVideoPreview" 。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_start_video_preview(struct nertc_engine* self, nertc_video_stream_type type); + +/** + * @if English + * Stops video preview. + * @note This method needs to be called before a user joins a room. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 停止视频预览。 + * @note 该方法需要在加入房间前调用。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_stop_video_preview(struct nertc_engine* self, nertc_video_stream_type type); + +/** + * @if English + * Enables or disables publishing the local video stream. + *
If the method is called Successfully, onUserVideoMute is triggered remotely. + * @note + * - When you call the method to disable video streams, the SDK doesn’t send local video streams but the camera is still + * working. + * - The method can be called before or after a user joins a room. + * - If you stop publishing the local video stream by calling this method, the option is reset to the default state that + * allows the app to publish the local video stream. + * - \ref nertc::IRtcEngine::enableLocalVideo "enableLocalVideo" (false) is different from \ref + * nertc::IRtcEngine::enableLocalVideo "enableLocalVideo" (false). The enableLocalVideo(false) method turns off local camera + * devices. The muteLocalVideoStreamvideo method does not affect local video capture, or disable cameras, and responds faster. + * @param[in] mute + * - true: Not publishing local video streams. + * - false: Publishing local video streams (default). + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 取消或恢复发布本地视频流。 + *
成功调用该方法后，远端会触发 onUserVideoMute 回调。 + * @note + * - 调用该方法禁视频流时，SDK 不再发送本地视频流，但摄像头仍然处于工作状态。 + * - 该方法在加入房间前后均可调用。 + * - 若调用该方法取消发布本地视频流，通话结束后会被重置为默认状态，即默认发布本地视频流。 + * - 该方法与 \ref nertc::IRtcEngine::enableLocalVideo "enableLocalVideo" (false) 的区别在于， \ref + * nertc::IRtcEngine::enableLocalVideo "enableLocalVideo" (false) + * 会关闭本地摄像头设备，muteLocalVideoStream不影响本地视频流采集，不禁用摄像头，且响应速度更快。 + * @param[in] mute + * - true: 不发送本地视频流 + * - false: 发送本地视频流（默认） + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_mute_local_video_stream(struct nertc_engine* self, nertc_video_stream_type stream_type, bool mute); + +/** + * @if English + * Sets the priority of media streams from a local user. + *
If a user has a high priority, the media stream from the user also has a high priority. In unreliable network + connections, the SDK guarantees the quality the media stream from users with a high priority. + * @note + * - You must call the method before you call joinChannel. + * - After switching channels, media priority changes to the default value of normal priority. + * - An RTC room has only one user that has a high priority. We recommend that only one user in a room call the + setLocalMediaPriority method to set the local media stream a high priority. Otherwise, you need to enable the preempt mode to + ensure the high priority of the local media stream. + * @param priority The priority of the local media stream. The default value is #kNERtcMediaPriorityNormal. For more + information, see #NERtcMediaPriorityType. + * @param is_preemptive specifies whether to enable the preempt mode. The default value is false, which indicates that the + preempt mode is disabled. + - If the preempt mode is enabled, the local media stream preempts the high priority over other users. + The priority of the media stream whose priority is taken becomes normal. After the user whose priority is taken leaves the + room, other users still keep the normal priority. + - If the preempt mode is disabled, and a user in the room has a high priority. After that, the high + priority of the local client remains invalid and is still normal. + * @return + - 0: Success. + - Other values: Failure. + * @endif + * @if Chinese + * 设置本地用户的媒体流优先级。 + *
如果某个用户的优先级为高，那么该用户媒体流的优先级就会高于其他用户，弱网环境下 SDK + 会优先保证其他用户收到的、高优先级用户的媒体流的质量。 + * @note + * - 请在加入房间（joinChannel）前调用此方法。 + * - 快速切换房间 （switchChannel） 后，媒体优先级会恢复为默认值，即普通优先级。 + * - 一个音视频房间中只有一个高优先级的用户。建议房间中只有一位用户调用 setLocalMediaPriority + 将本端媒体流设为高优先级，否则需要开启抢占模式，保证本地用户的高优先级设置生效。 + * @param priority 本地用户的媒体流优先级，默认为 #kNERtcMediaPriorityNormal 。详细信息请参考 #NERtcMediaPriorityType 。 + * @param is_preemptive 是否开启抢占模式。默认为 false，即不开启。 + - + 抢占模式开启后，本地用户可以抢占其他用户的高优先级，被抢占的用户的媒体优先级变为普通优先级，在抢占者退出房间后，其他用户的优先级仍旧维持普通优先级。 + - 抢占模式关闭时，如果房间中已有高优先级用户，则本地用户的高优先级设置不生效，仍旧为普通优先级。 + * @return + - 0: 方法调用成功； + - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_local_media_priority(struct nertc_engine* self, nertc_media_priority_type priority, bool is_preemptive); + +/** + * @if English + * Sets parameters for audio and video calls. You can configure the SDK through JSON to provide features like technology + * review and special customization. Publicizes JSON options in a standardized way. + * @param[in] parameters Related parameters for audio and video calls whose format is the JSON string. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置音视频通话的相关参数。通过 JSON 配置 SDK 提供技术预览或特别定制功能。以标准化方式公开 JSON 选项。 + * @param[in] parameters 音视频通话的相关参数。 JSON 字符串形式。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_parameters(struct nertc_engine* self, const char* parameters); + +/** + * @if English + * Sets the audio recording format. + *
The method is used to set audio recording format of \ref nertc::INERtcAudioFrameObserver::onAudioFrameDidRecord + * "onAudioFrameDidRecord" callback. + * @note + * - The method can be called before or after a user joins a room. + * - Stops listening and sets the value as empty. + * @param format The sample rate and channels of data returned in the *onAudioFrameDidRecord*. A value of NULL is allowed. + * The default value is NULL. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置录制的声音格式。 + *
该方法设置 \ref nertc::INERtcAudioFrameObserver::onAudioFrameDidRecord "onAudioFrameDidRecord" 回调的录制声音格式。 + * @note + * - 该方法在加入房间前后均可设置或修改。 + * - 取消监听，重置为空。 + * @param format 指定 *onAudioFrameDidRecord* 中返回数据的采样率和数据的通道数。允许传入 NULL，默认为 NULL。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_recording_audio_frame_parameters(struct nertc_engine* self, const struct nertc_audio_frame_request_format* format); + +/** + * @if English + * Sets the audio playback format. + *
The method is used to set audio recording format of \ref nertc::INERtcAudioFrameObserver::onAudioFrameDidRecord + * "onAudioFrameDidRecord" callback. + * @note + * - The method can be called or modified before or after a user joins a room. + * - Stops listening and sets the value as empty. + * @param format The sample rate and channels of data returned in the *onAudioFrameWillPlayback*. A value of NULL is allowed. + * The default value is NULL. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置播放的声音格式。 + *
该方法设置 \ref nertc::INERtcAudioFrameObserver::onAudioFrameWillPlayback "onAudioFrameWillPlayback" + * 回调的播放声音格式。 + * @note + * - 该方法在加入房间前后均可设置或修改。 + * - 取消监听，重置为空。 + * @param format 指定 *onAudioFrameWillPlayback* 中返回数据的采样率和数据的通道数。允许传入 NULL，默认为 NULL。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_playback_audio_frame_parameters(struct nertc_engine* self, const struct nertc_audio_frame_request_format* format); + +/** + * @if English + * Sets the sample rate of audio mixing stream after the audio is recording and playback. + *
The method is used to set audio recording format of \ref nertc::INERtcAudioFrameObserver::onMixedAudioFrame + * "onMixedAudioFrame" . + * @note + * - The method can be called before or after a user joins a room. + * - Currently supports setting the sample rate only. + * - If you do not call the interface to set the data format, the sample rate in the callback return the default value set by + * the SDK. + * @param sample_rate The sample rate of data returned in *onMixedAudioFrame*. Only 8000, 16000, 32000, 44100, and 48000 + * are supported. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置录制和播放声音混音后的采样率。 + *
该方法设置 \ref nertc::INERtcAudioFrameObserver::onMixedAudioFrame "onMixedAudioFrame" 回调的声音格式。 + * @note + * - 该方法在加入房间前后均可设置或修改。 + * - 目前只支持设置采样率。 + * - 未调用该接口设置数据格式时，回调中的采样率返回 SDK 默认值。 + * @param sample_rate 指定 *onMixedAudioFrame* 中返回数据的采样率。仅支持 8000， 16000， 32000， 44100或48000。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_mixed_audio_frame_parameters(struct nertc_engine* self, int sample_rate); + +/** + * @if English + * Registers the audio observer object. + *
The method is used to set audio capture or play PCM data callbacks. You can use the method to process audios. You need + * to register callbacks with this method when engine needs to trigger callbacks of \ref + * nertc::INERtcAudioFrameObserver::onAudioFrameDidRecord "onAudioFrameDidRecord" or \ref + * nertc::INERtcAudioFrameObserver::onAudioFrameWillPlayback "onAudioFrameWillPlayback". + * @param observer The object instance. If you pass in NULL, you cancel the registration and clear the settings of + * NERtcAudioFrameRequestFormat. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 注册语音观测器对象。 + *
该方法用于设置音频采集和播放PCM回调，可用于声音处理等操作。当需要引擎给出 \ref + * nertc::INERtcAudioFrameObserver::onAudioFrameDidRecord "onAudioFrameDidRecord" 或 \ref + * nertc::INERtcAudioFrameObserver::onAudioFrameWillPlayback "onAudioFrameWillPlayback" 回调时，需要使用该方法注册回调。 + * @param observer 接口对象实例。如果传入 NULL，则取消注册，同时会清理NERtcAudioFrameRequestFormat相关设置。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_audio_frame_observer(struct nertc_engine* self, struct nertc_audio_frame_observer* observer); + +/** + * @if English + * Starts recording an audio dump file. Audio dump files can be used to analyze audio issues. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 开始记录音频 dump。 音频 dump 可用于分析音频问题。 + * @param type 音频dump类型 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_start_audio_dump(struct nertc_engine* self, nertc_audio_dump_type type); + +/** + * @if English + * Finishes recording an audio dump file. + * @return + - 0: Success. + - Other values: Failure. + * @endif + * @if Chinese + * 结束音频dump。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_stop_audio_dump(struct nertc_engine* self); + +/** + 设置音频播放扬声器模式（仅iOS/Android有效） + + @param enable 是否使用扬声器模式 + @return 操作返回值，成功则返回 0 + */ +NERTC_API int NERTC_CALL nertc_engine_set_loudspeaker_mode(struct nertc_engine* self, bool enable); + +/** + 获取目前是否使用扬声器模式（仅iOS/Android有效） + + @param enabled 是否正在使用扬声器模式 + @return + - 0: 方法调用成功； + - 其他: 方法调用失败。 + */ +NERTC_API int NERTC_CALL nertc_engine_get_loudspeaker_mode(struct nertc_engine* self, bool* enabled); + +/** + * @if English + * Starts playing a music file. + *
This method mixes the specified local or online audio file with the audio stream captured by the audio devices. + * - Supported audio formats: MP3, M4A, AAC, 3GP, WMA, and WAV. Files that are stored in local or online URLs are supported. + * - After you successfully call the method, if the playback status is changed, the local triggers \ref + * nertc::IRtcEngineEventHandlerEx::onAudioMixingStateChanged "onAudioMixingStateChanged" callbacks. + * @note + * - You can call this method after joining a room. + * - Since V4.3.0, if you call this method to play a music file during a call, and manually set the playback volume of the + * audio mixing and the sent volume, the setting is used when you call the method again during the current call. + * @param[in] option Options of creating audio mixing configurations that include types, full path or URL. For more + * information, see {@link NERtcCreateAudioMixingOption}. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 开始播放音乐文件。 + *
该方法指定本地或在线音频文件来和录音设备采集的音频流进行混音。 + * - 支持的音乐文件类型包括 MP3、M4A、AAC、3GP、WMA 和 WAV 格式，支持本地文件或在线 URL。 + * - 成功调用该方法后，如果播放状态改变，本地会触发 \ref nertc::IRtcEngineEventHandlerEx::onAudioMixingStateChanged + * "onAudioMixingStateChanged" 回调。 + * @note + * - 请在加入房间后调用该方法。 + * - 从 V4.3.0 版本开始， + * 若您在通话中途调用此接口播放音乐文件时，手动设置了伴音播放音量或发送音量，则当前通话中再次调用时默认沿用此设置。 + * - 在 V4.4.0 版本中，开启或关闭本地音频采集的操作不影响音乐文件在远端的播放，即 enableLocalAudio(false) + * 后仍旧可以发送伴音。在其他版本中，必须开启音频采集才能发送伴音。 + * @param[in] option 创建混音任务配置的选项，包括混音任务类型、混音文件全路径或URL等。详细信息请参考 {@link + * NERtcCreateAudioMixingOption}。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_start_audio_mixing(struct nertc_engine* self, struct nertc_create_audio_mixing_option* option); + +/** + * @if English + * Stops playing music files or audio mixing. + *
The method stops playing the audio mixing. You can call the method when you are in a room. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 停止播放音乐文件及混音。 + *
该方法停止播放伴奏。请在房间内调用该方法。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_stop_audio_mixing(struct nertc_engine* self); + +/** + * @if English + * Stops playing music files or audio mixing. + *
The method pauses playing audio mixing. You can call the method when you are in a room. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 暂停播放音乐文件及混音。 + *
该方法暂停播放伴奏。请在房间内调用该方法。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_pause_audio_mixing(struct nertc_engine* self); + +/** + * @if English + * Resumes playing the audio mixing. + *
The method resumes audio mixing, and continues playing the audio mixing. You can call the method when you are in a + * room. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 恢复播放伴奏。 + *
该方法恢复混音，继续播放伴奏。请在房间内调用该方法。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_resume_audio_mixing(struct nertc_engine* self); + +/** + * @if English + * Adjusts the audio mixing volume for publishing. + *
The method adjusts the volume for publishing of the audio mixing in the audio mixing. You can call the method when you + * are in a room. + * @param[in] volume The audio mixing volume for publishing. Valid values: 0 to 100. The default value of 100 represents + * the original volume. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 调节伴奏发送音量。 + *
该方法调节混音里伴奏的发送音量大小。请在房间内调用该方法。 + * @param[in] volume 伴奏发送音量。取值范围为 0~100。默认 100 为原始文件音量。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_audio_mixing_send_volume(struct nertc_engine* self, uint32_t volume); + +/** + * @if English + * Gets the volume for publishing of audio mixing. + *
The method gets the volume for publishing of the audio mixing in the audio mixing. You can call the method when you are + * in a room. + * @param[out] volume The volume for publishing of the audio mixing. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 获取伴奏发送音量。 + *
该方法获取混音里伴奏的发送音量大小。请在房间内调用该方法。 + * @param[out] volume 伴奏发送音量。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_get_audio_mixing_send_volume(struct nertc_engine* self, uint32_t* volume); + +/** + * @if English + * Adjusts the playback volume of the audio mixing. + *
The method adjusts the playback volume of the audio mixing in the audio mixing. You can call the method when you are in + * a room. + * @param[in] volume The volume range of the audio mixing is 0 to 100. The default value of 100 represents the original + * volume. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 调节伴奏播放音量。 + *
该方法调节混音里伴奏的播放音量大小。请在房间内调用该方法。 + * @param[in] volume 伴奏音量范围为 0~100。默认 100 为原始文件音量。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_audio_mixing_playback_volume(struct nertc_engine* self, uint32_t volume); + +/** + * @if English + * Gets the playback volume of the audio mixing. + *
The method gets the playback volume of the audio mixing in the audio mixing. You can call the method when you are in a + * room. + * @param[out] volume The volume of the audio mixing. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 获取伴奏播放音量。 + *
该方法获取混音里伴奏的播放音量大小。请在房间内调用该方法。 + * @param[out] volume 伴奏播放音量。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_get_audio_mixing_playback_volume(struct nertc_engine* self, uint32_t* volume); + +/** + * @if English + * Gets the duration of the audio mixing. + *
The method gets the duration of the audio mixing. Unit: milliseconds. You can call the method when you are in a room. + * @param[out] duration The duration of the audio mixing. Unit: milliseconds. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 获取伴奏时长。 + *
该方法获取伴奏时长，单位为毫秒。请在房间内调用该方法。 + * @param[out] duration 伴奏时长，单位为毫秒。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_get_audio_mixing_duration(struct nertc_engine* self, uint64_t* duration); + +/** + * @if English + * Gets the playback position of the music file. + *
The method gets the playback position of the music file. Unit: milliseconds. You can call the method when you are in a + * room. + * @param[out] position The playback position of the audio mixing file. Unit: milliseconds. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 获取音乐文件的播放进度。 + *
该方法获取当前伴奏播放进度，单位为毫秒。请在房间内调用该方法。 + * @param[out] position 伴奏播放进度，单位为毫秒。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_get_audio_mixing_current_position(struct nertc_engine* self, uint64_t* position); + +/** + * @if English + * Sets the playback position of the music file to a different starting position. + *
The method sets the playback position of the music file to a different starting position. The method allows you to play + * the music file from the position based on your requirements rather than from the beginning of the music file. + * @param[in] seek_position The playback position of the music file. Unit: milliseconds. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置音乐文件的播放位置。 + *
该方法可以设置音频文件的播放位置，这样你可以根据实际情况播放文件，而非从头到尾播放整个文件。 + * @param[in] seek_position 进度条位置，单位为毫秒。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_audio_mixing_position(struct nertc_engine* self, uint64_t seek_position); + +/** + * @if Chinese + * 设置当前伴音文件的音调。 + * - 通过此接口可以实现当本地人声和播放的音乐文件混音时，仅调节音乐文件的音调。 + * @since V4.6.29 + * @par 使用前提 + * 请先调用 \ref nertc::IRtcEngineEx::startAudioMixing "startAudioMixing" 方法开启伴音。 + * @par 调用时机 + * 请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。 + * @par 业务场景 + * 适用于 K 歌中为了匹配人声，调节背景音乐音高的场景。 + * @note + * 当前伴音任务结束后，此接口的设置会恢复至默认。 + * @par 参数说明 + * + * + * + * + * + * + * + * + * + * + * + *
**参数名称****类型****描述**
pitchint32_t当前伴音文件的音调。默认值为 0，即不调整音调，取值范围为 -12 ~ + * 12，按半音音阶调整。每相邻两个值的音高距离相差半音；取值的绝对值越大，音调升高或降低得越多。
+ * @par 示例代码 + * @code + * int pitch = 0; + * rtc_engine_->setAudioMixingPitch(pitch); + * @endcode + * @par 相关接口 + * 可以调用 \ref nertc::IRtcEngineEx::getAudioMixingPitch "getAudioMixingPitch" 方法获取伴音文件的音调。 + * @return + * - 0（kNERtcNoError）：方法调用成功。 + * - 其他：方法调用失败。 + * - 30003（kNERtcErrInvalidParam）：参数有误，比如 pitch 超出范围。 + * - 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如找不到对应的伴音任务或引擎尚未初始化。 + * - 30101（kNERtcErrChannelNotJoined）：尚未加入房间。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_audio_mixing_pitch(struct nertc_engine* self, int32_t pitch); + +/** + * @if Chinese + * 获取当前伴音文件的音调。 + * @since V4.6.29 + * @par 使用前提 + * 请先调用 \ref nertc::IRtcEngineEx::startAudioMixing "startAudioMixing" 方法开启伴音。 + * @par 调用时机 + * 请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。 + * @par 参数说明 + * + * + * + * + * + * + * + * + * + * + * + *
**参数名称****类型****描述**
pitchint32_t*当前伴音文件的音调。默认值为 0，即不调整音调，取值范围为 -12 ~ + * 12，按半音音阶调整。每相邻两个值的音高距离相差半音；取值的绝对值越大，音调升高或降低得越多。
+ * @par 示例代码 + * @code + * int pitch = 0; + * rtc_engine_->getAudioMixingPitch(&pitch); + * @endcode + * @return + * - 0（kNERtcNoError）：方法调用成功。 + * - 其他：方法调用失败。 + * - 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如找不到对应的伴音任务或引擎尚未初始化。 + * - 30101（kNERtcErrChannelNotJoined）：尚未加入房间。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_get_audio_mixing_pitch(struct nertc_engine* self, int32_t* pitch); + +/** + * @if English + * Plays a specified audio effect file. + * - After the method is successfully called, if the playback ends, the onAudioEffectFinished callback is triggered. + * - Supported audio formats: MP3, M4A, AAC, 3GP, WMA, and WAV. Files that are stored in local or online URLs are supported. + * @note + * - You can call this method after joining a room. + * - You can call the method for multiple times. You can play multiple audio effect files simultaneously by passing in + * different effect_ids and options. Various audio effects are mixed. To gain optimal user experience, we recommend you to + * play no more than three audio effect files at the same time. + * @param[in] effect_id The ID of the specified audio effect. Each audio effect has a unique ID. + * @param[in] option The options of creating audio effect files configurations including types, full path or URL of + * audio mixing files. For more information, see {@link NERtcCreateAudioEffectOption}. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 播放指定音效文件。 + * - 成功调用该方法后，如果播放结束，本地会触发 onAudioEffectFinished 回调。 + * - 支持的音效文件类型包括 MP3、M4A、AAC、3GP、WMA 和 WAV 格式，支持本地文件和在线 URL。 + * @note + * - 请在加入房间后调用该方法。 + * - 您可以多次调用该方法，通过传入不同的音效文件的effect_id 和 option + * ，同时播放多个音效文件，实现音效叠加。为获得最佳用户体验，建议同时播放的音效文件不超过 3 个。 + * @param[in] effect_id 指定音效的 ID。每个音效均有唯一的 ID。 + * @param[in] option 创建音效任务配置的选项，包括混音任务类型、混音文件全路径或 URL 等。详细说明请参考 {@link + * NERtcCreateAudioEffectOption}。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_play_effect(struct nertc_engine* self, uint32_t effect_id, struct nertc_create_audio_effect_option* option); + +/** + * @if English + * Stops playing a specified audio effect file. + *
You can call the method when you are in a room. + * @param[in] effect_id The ID of the specified audio effect. Each audio effect has a unique ID. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 停止播放指定音效文件。 + *
请在房间内调用该方法。 + * @param[in] effect_id 指定音效的 ID。每个音效均有唯一的 ID。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_stop_effect(struct nertc_engine* self, uint32_t effect_id); + +/** + * @if English + * Stops playing all audio effects. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 停止播放所有音效文件。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_stop_all_effects(struct nertc_engine* self); + +/** + * @if English + * Pauses playing all audio effects. + *
You can call the method when you are in a room. + * @param[in] effect_id The ID of the specified audio effect. Each audio effect has a unique ID. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 暂停音效文件播放。 + *
请在房间内调用该方法。 + * @param[in] effect_id 指定音效的 ID。每个音效均有唯一的 ID。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_pause_effect(struct nertc_engine* self, uint32_t effect_id); + +/** + * @if English + * Resumes playing a specified audio effect. + *
You can call the method when you are in a room. + * @param[in] effect_id The ID of the specified audio effect. Each audio effect has a unique ID. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 恢复播放指定音效文件。 + *
请在房间内调用该方法。 + * @param[in] effect_id 指定音效的 ID。每个音效均有唯一的 ID。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_resume_effect(struct nertc_engine* self, uint32_t effect_id); + +/** + * @if English + * Pauses all audio effect files. + *
You can call the method when you are in a room. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 暂停所有音效文件播放。 + *
请在房间内调用该方法。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_pause_all_effects(struct nertc_engine* self); + +/** + * @if English + * Resumes playing all audio effects files. + *
You can call the method when you are in a room. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 恢复播放所有音效文件。 + *
请在房间内调用该方法。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_resume_all_effects(struct nertc_engine* self); + +/** + * @if English + * Adjusts the audio effect volume for publishing. + * The method adjusts the audio effect volume for publishing. You can call the method when you are in a room. + * @param[in] effect_id The ID of the specified audio effect. Each audio effect has a unique ID. + * @param[in] volume The audio effect volume. Value range: 0 to 100. The default value of 100 represents the + * original volume. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 调节音效发送音量。 + * 该方法调节音效的发送音量大小。请在房间内调用该方法。 + * @param[in] effect_id 指定音效的 ID。每个音效均有唯一的 ID。 + * @param[in] volume 音效音量范围为 0~100。默认 100 为原始文件音量。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_effect_send_volume(struct nertc_engine* self, uint32_t effect_id, uint32_t volume); + +/** + * @if English + * Gets the audio effect volume for publishing. + * The method gets the audio effect volume for publishing. You can call the method when you are in a room. + * @param[in] effect_id The ID of the specified audio effect. Each audio effect has a unique ID. + * @param[out] volume The audio effect volume for publishing. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 获取音效发送音量。 + * 该方法获取音效的发送音量大小。请在房间内调用该方法。 + * @param[in] effect_id 指定音效的 ID。每个音效均有唯一的 ID。 + * @param[out] volume 音效发送音量。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_get_effect_send_volume(struct nertc_engine* self, uint32_t effect_id, uint32_t* volume); + +/** + * @if English + * Sets the playback volume of an audio effect file. + * You can call this method after joining a room. + * @param[in] effect_id The ID of the specified audio effect. Each audio effect has a unique ID. + * @param[in] volume The audio effect volume for publishing. Valid values: 0 to 100. The default value is 100. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置音效文件播放音量。 + * 请在加入房间后调用该方法。 + * @param[in] effect_id 指定音效的 ID。每个音效均有唯一的 ID。 + * @param[in] volume 音效播放音量。范围为0~100，默认为100。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_effect_playback_volume(struct nertc_engine* self, uint32_t effect_id, uint32_t volume); + +/** + * @if English + * Gets the playback volume of the audio effects files. + *
You can call this method after joining a room. + * @param[in] effect_id The ID of the specified audio effect. Each audio effect has a unique ID. + * @param[out] volume The audio effect playback volume. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 获取音效文件播放音量。 + *
请在加入房间后调用该方法。 + * @param[in] effect_id 指定音效的 ID。每个音效均有唯一的 ID。 + * @param[out] volume 音效播放音量。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_get_effect_playback_volume(struct nertc_engine* self, uint32_t effect_id, uint32_t* volume); + +/** + * @if Chinese + * 设置指定音效文件的音调。 + * - 通过此接口可以实现当本地人声和播放的音乐文件混音时，仅调节音乐文件的音调。 + * @since V4.6.29 + * @par 使用前提 + * 请先调用 \ref nertc::IRtcEngineEx::playEffect "playEffect" 方法播放音效。 + * @par 调用时机 + * 请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。 + * @par 业务场景 + * 适用于 K 歌中为了匹配人声，调节背景音乐音高的场景。 + * @note + * 当前音效任务结束后，此接口的设置会恢复至默认。 + * @par 参数说明 + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
**参数名称****类型****描述**
effect_iduint32_t指定音效文件的 ID。每个音效文件均对应唯一的 ID。
pitchint32_t指定音效文件的音调。默认值为 0，即不调整音调，取值范围为 -12 ~ + * 12，按半音音阶调整。每相邻两个值的音高距离相差半音；取值的绝对值越大，音调升高或降低得越多。
+ * @par 示例代码 + * @code + * uint32 effect_id = 7788; + * int32_t pitch = 0; + * rtc_engine_->setEffectPitch(effect_id, pitch); + * @endcode + * @par 相关接口 + * 可以调用 \ref nertc::IRtcEngineEx::getEffectPitch "getEffectPitch" 方法获取指定音效文件的音调。 + * @return + * - 0（kNERtcNoError）：方法调用成功。 + * - 其他：方法调用失败。 + * - 30003（kNERtcErrInvalidParam）：参数有误，比如 pitch 超出范围。 + * - 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如找不到对应的音效任务或引擎尚未初始化。 + * - 30101（kNERtcErrChannelNotJoined）：尚未加入房间。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_effect_pitch(struct nertc_engine* self, uint32_t effect_id, int32_t pitch); + +/** + * @if Chinese + * 获取指定音效文件的音调。 + * @since V4.6.29 + * @par 使用前提 + * 请先调用 \ref nertc::IRtcEngineEx::playEffect "playEffect" 方法播放音效。 + * @par 调用时机 + * 请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。 + * @par 参数说明 + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
**参数名称****类型****描述**
effect_iduint32_t指定音效文件的 ID。每个音效文件均对应唯一的 ID。
pitchint32_t指定音效文件的音调。默认值为 0，即不调整音调，取值范围为 -12 ~ + * 12，按半音音阶调整。每相邻两个值的音高距离相差半音；取值的绝对值越大，音调升高或降低得越多。
+ * @par 示例代码 + * @code + * uint32 effect_id = 7788; + * int32_t pitch = 0; + * rtc_engine_->getEffectPitch(effect_id, &pitch); + * @endcode + * @return + * - 0（kNERtcNoError）：方法调用成功。 + * - 其他：方法调用失败。 + * - 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如找不到对应的音效任务或引擎尚未初始化。 + * - 30101（kNERtcErrChannelNotJoined）：尚未加入房间。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_get_effect_pitch(struct nertc_engine* self, uint32_t effect_id, int32_t* pitch); + +/** + * @if English + * Set the playback position of the sound effect file. + * This method can set the playback position of the sound effect file, so that you can play the file according to the + * actual situation, rather than playing the entire file from beginning to end. + * @param effect_id Effect ID。 + * @param timestamp_ms The playback position of the sound effect file, in milliseconds. + * @return + * - 0: success + * - Others: failure + * @endif + * @if Chinese + * 设置指定音效文件的播放位置。 + * - 通过此接口可以实现根据实际情况播放音效文件，而非从头到尾播放整个文件。 + * @since V4.6.29 + * @par 使用前提 + * 请先调用 \ref nertc::IRtcEngineEx::playEffect "playEffect" 方法播放音效。 + * @par 调用时机 + * 请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。 + * @par 参数说明 + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
**参数名称****类型****描述**
effect_iduint32_t指定音效文件的 ID。每个音效文件均对应唯一的 ID。
timestamp_msuint64_t指定音效文件的起始播放位置。单位为毫秒。
+ * @par 示例代码 + * @code + * uint32_t effect_id = 7788; + * uint64_t timestamp_ms = 0; + * rtc_engine_->setEffectPosition(effect_id, timestamp_ms); + * @endcode + * @par 相关接口 + * - \ref nertc::IRtcEngineEx::getEffectCurrentPosition "getEffectCurrentPosition"：获取指定音效文件的当前播放位置。 + * - \ref nertc::IRtcEngineEventHandlerEx::onAudioEffectTimestampUpdate + * "onAudioEffectTimestampUpdate"：注册此回调实时获取指定音效文件的当前播放进度，默认为每隔 1s 返回一次。 + * @return + * - 0（kNERtcNoError）：方法调用成功。 + * - 其他：方法调用失败。 + * - 30001（kNERtcErrFatal）：接口操作失败或未找到对应的音效任务。 + * - 30003（kNERtcErrInvalidParam）：参数错误，比如 effect_id 不正确。 + * - 30101（kNERtcErrChannelNotJoined）：尚未加入房间。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_effect_position(struct nertc_engine* self, uint32_t effect_id, uint64_t timestamp_ms); + +/** + * @if English + * Get the playback progress of the sound effect. + * This method obtains the current sound effect playback progress in milliseconds. + * @note Please call this method in the room. + * @param effect_id Effect ID。 + * @param timestamp_ms The playback position of the sound effect file, in milliseconds. + * @return + * - 0: success + * - Others: failure + * @endif + * @if Chinese + * 获取指定音效文件的播放进度。 + * @since V4.6.29 + * @par 使用前提 + * 请先调用 \ref nertc::IRtcEngineEx::playEffect "playEffect" 方法播放音效。 + * @par 调用时机 + * 请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。 + * @par 参数说明 + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
**参数名称****类型****描述**
effect_iduint32_t指定音效文件的 ID。每个音效文件均对应唯一的 ID。
timestamp_msuint64_t*指定音效文件的当前播放位置。单位为毫秒。
+ * @par 示例代码 + * @code + * uint32 effect_id = 7788; + * int32_t pitch = 0; + * rtc_engine_->getEffectCurrentPosition(effect_id, ×tamp_ms); + * @endcode + * @return + * - 0（kNERtcNoError）：方法调用成功。 + * - 其他：方法调用失败。 + * - 30001（kNERtcErrFatal）：接口操作失败或未找到对应的音效任务。 + * - 30003（kNERtcErrInvalidParam）：参数错误，比如 effect_id 不正确。 + * - 30101（kNERtcErrChannelNotJoined）：尚未加入房间。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_get_effect_current_position(struct nertc_engine* self, uint32_t effect_id, uint64_t* timestamp_ms); + +/** + * @if English + * Get the duration of the sound effect file. + * This method obtains the duration of the sound effect file, in milliseconds. + * @note Please call this method in the room. + * @param effect_id Effect ID。 + * @param timestamp_ms The playback position of the sound effect file, in milliseconds. + * @return + * - 0: success + * - Others: failure + * @endif + * @if Chinese + * 获取指定音效文件的时长。 + * @since V4.6.29 + * @par 使用前提 + * 请先调用 \ref nertc::IRtcEngineEx::playEffect "playEffect" 方法播放音效。 + * @par 调用时机 + * 请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。 + * @par 参数说明 + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
**参数名称****类型****描述**
effect_iduint32_t指定音效文件的 ID。每个音效文件均对应唯一的 ID。
duration_msuint64_t*指定音效文件的时长。单位为毫秒。
+ * @par 示例代码 + * @code + * uint32 effect_id = 7788; + * int32_t pitch = 0; + * rtc_engine_->getEffectDuration(effect_id, &duration_ms); + * @endcode + * @return + * - 0（kNERtcNoError）：方法调用成功。 + * - 其他：方法调用失败。 + * - 30001（kNERtcErrFatal）：接口操作失败或未找到对应的音效任务。 + * - 30003（kNERtcErrInvalidParam）：参数错误，比如 effect_id 不正确。 + * - 30101（kNERtcErrChannelNotJoined）：尚未加入房间。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_get_effect_duration(struct nertc_engine* self, uint32_t effect_id, uint64_t* duration_ms); + +/** + * @if English + * Enables or disables in-ear monitoring. + * @note + * - You can call the method when you are in a room. + * - After in-ear monitoring is enabled, you must wear a headset or earpieces to use the in-ear monitoring feature. We + * recommend that you listen for changes of playback devices through \ref IRtcEngineEventHandlerEx::onAudioDeviceStateChanged + * "onAudioDeviceStateChanged" and \ref IRtcEngineEventHandlerEx::onAudioDefaultDeviceChanged "onAudioDefaultDeviceChanged". + * Only when the device changes to headset, you can enable in-ear monitoring. + * @param[in] enabled Enabled or disabled. + * @param[in] volume The volume of ear-monitoring. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 开启或关闭耳返。 + * @note + * - 请在房间内调用该方法。 + * - 开启耳返功能后，必须连接上耳机或耳麦，才能正常使用耳返功能。建议通过 \ref + * IRtcEngineEventHandlerEx::onAudioDeviceStateChanged "onAudioDeviceStateChanged" 及 \ref + * IRtcEngineEventHandlerEx::onAudioDefaultDeviceChanged "onAudioDefaultDeviceChanged" + * 监听播放设备的变化，当监听到播放设备切换为耳机时才开启耳返。 + * @param[in] enabled 开启或关闭。 + * @param[in] volume 耳返音量。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_enable_earback(struct nertc_engine* self, bool enabled, uint32_t volume); + +/** + * @if English + * Sets the volume for in-ear monitoring. + * You can call the method when you are in a room. + * @param[in] volume The volume of ear-monitoring. Valid values: to 100. The default value is 100. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置耳返音量。 + * 请在房间内调用该方法。 + * @param[in] volume 耳返音量。可设置为 0~100，默认为 100。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_earback_volume(struct nertc_engine* self, uint32_t volume); + +/** + * @if English + * Enables or disables local audio capture through the sound card. + * @since V4.4.0 + * After the feature is enabled, the audio played by the sound card is integrated into local video streams. In this way, you can + publish the audio to the remote side. + * @note + * - The method applies to only macOS and Windows. + * - The capture feature is not supported on the macOS by default. If you need to enable the feature, the app needs to enable a + virtual sound card and name the sound card as device_name to pass in the SDK. We recommend that you can use Soundflower as + virtual sound card to deliver better audio effect. + * - You can call this method before or after you join a room. + * @param[in] enabled Specifies whether to enable the capture feature through the sound card. + - true: Enables audio capture through the sound card. + - false: Disables audio capture through the sound card (default). + * @param[in] device_name The device name of the sound card. The name is set as NULL by default, which indicates capturing + through the current sound card.
The parameter applies to macOS platform only.
If users use virtual sound cards such as + “Soundflower”, you can set the sound card name of virtual card as parameter. In this way, the SDK finds the corresponding + device of virtual sound cards and starts capturing. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 开启或关闭声卡采集。 + * @since V4.4.0 + * 启用声卡采集功能后，声卡播放的声音会被合到本地音频流中，从而可以发送到远端。 + * @note + * - 该方法仅适用于 macOS 和 Windows 平台。 + * - 该方法在加入房间前后都能调用。 + * - 您不能同时使用音频自播放和音频共享功能，否则会导致加入音视频通话房间后，无法听到对端用户的音频和本地共享音频的声音。 + * - macOS 系统默认声卡不支持采集功能，如需开启此功能需要 App 自己启用一个虚拟声卡，并将该虚拟声卡的名字作为 device_name 传入 + SDK。 网易云信建议使用 Soundflower 作为虚拟声卡，以获得更好的音频效果。 + * @param[in] enabled 是否开启声卡采集功能。 + - true: 开启声卡采集。 + - false: （默认）关闭声卡采集。 + * @param[in] device_name 声卡的设备名。默认设为 NULL，即使用当前声卡采集。
该参数仅适用于 macOS + 平台。
如果用户使用虚拟声卡，如 “Soundflower”，可以将虚拟声卡名称 “Soundflower” 作为参数，SDK + 会找到对应的虚拟声卡设备，并开始采集。 + * @return + * - 0: 方法调用成功 + * - 其他: 方法调用失败 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_enable_loopback_recording(struct nertc_engine* self, bool enabled, const char* device_name); + +/** + * @if English + * Adjusts the volume of captured signals of sound cards. + * @since V4.4.0 + * After calling sound card capturing by calling \ref nertc::IRtcEngineEx::enableLoopbackRecording "enableLoopbackRecording", + * you can call the method to adjust the volume of captured signals of sound cards. + * @param[in] volume The captured signals volume through sound cards. Value range: 0 to 100. The default value of 100 + * represents the original volume. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 调节声卡采集信号音量。 + * @since V4.4.0 + * 调用 \ref nertc::IRtcEngineEx::enableLoopbackRecording "enableLoopbackRecording" + * 开启声卡采集后，你可以调用该方法调节声卡采集的信号音量。 + * @param[in] volume 声卡采集信号音量。取值范围为 [0,100]。默认值为 100，表示原始音量。 + * @return + * - 0: 方法调用成功 + * - 其他: 方法调用失败 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_adjust_loopback_recording_signal_volume(struct nertc_engine* self, int volume); + +/** + * @if English + * Registers a stats observer. + * @param[in] observer The stats observer. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 注册统计信息观测器。 + * @param[in] observer 统计信息观测器 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API void NERTC_CALL nertc_engine_set_stats_observer(struct nertc_engine* self, struct nertc_media_stats_observer* observer); + +/** + * @if English + * Registers a video encoder qos observer. + * @note The observer must be set after the SDK is initialized and becomes invalid after the SDK is released. + * @since V4.6.25 + * @param[in] observer The object instance. If you pass in NULL, you cancel the registration. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 注册视频编码 QoS 信息监听器。 + * - 通过此接口可以设置 \ref nertc::INERtcVideoEncoderQosObserver::onRequestSendKeyFrame "onRequestSendKeyFrame"、 \ref + * nertc::INERtcVideoEncoderQosObserver::onVideoCodecUpdated "onVideoCodecUpdated"、 \ref + * nertc::INERtcVideoEncoderQosObserver::onBitrateUpdated "onBitrateUpdated" + * 回调监听，并通过返回的相关视频编码数据调整视频编码策略。 + * @since V4.6.29 + * @par 调用时机 + * 请在引擎初始化之后调用此接口，且该方法在加入房间前后均可调用。 + * @par 业务场景 + * 适用于需要自行处理视频数据的采集与编码的场景。 + * @note + * 该方法设置内部引擎为启用状态，在 \ref IRtcEngine::leaveChannel "leaveChannel" + * 后仍然有效；如果需要关闭该功能，需要在下次通话前调用此接口关闭视频编码 QoS 信息监听。 + * @par 参数说明 + * + * + * + * + * + * + * + * + * + * + * + *
**参数名称****类型****描述**
observerINERtcVideoEncoderQosObserver *接口对象实例。可以传 NULL 表示取消注册。
+ * @par 示例代码 + * @code + * auto ret = rtc_engine_->setVideoEncoderQosObserver(observer); // observer为观测器实例地址 + * if (ret != nertc::kNERtcNoError) { + * // 错误处理 + * } + * @endcode + * @par 相关回调 + * \ref nertc::INERtcVideoEncoderQosObserver::onRequestSendKeyFrame "onRequestSendKeyFrame"：I 帧请求回调。 + * \ref nertc::INERtcVideoEncoderQosObserver::onBitrateUpdated "onBitrateUpdated"：码率信息回调。 + * \ref nertc::INERtcVideoEncoderQosObserver::onVideoCodecUpdated "onVideoCodecUpdated"：视频编码器类型信息回调。 + * @return + * - 0（kNERtcNoError）：方法调用成功。 + * - 其他：方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_video_encoder_qos_observer(struct nertc_engine* self, struct nertc_video_encoder_qos_observer* observer); + +/** + * @if English + * Registers the pre decode observer object. + * @note The observer must be set after the SDK is initialized and becomes invalid after the SDK is released. + * @since V4.6.25 + * @param[in] observer The object instance. If you pass in NULL, you cancel the registration. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 注册解码前媒体数据观测器。 + * - 通过此接口可以设置 \ref nertc::INERtcPreDecodeObserver::onFrame "onFrame" 回调监听，返回相关解码前媒体数据。 + * @since V4.6.29 + * @par 使用前提 + * 若您需要接收未解码的视频数据，建议先调用 \ref IRtcEngineEx::setParameters "setParameters" 接口关闭 SDK 的视频解码功能。 + * @par 调用时机 + * 请在引擎初始化之后调用此接口，且该方法在加入房间前后均可调用。 + * @par 业务场景 + * 适用于需要自行处理音、视频数据的解码与渲染的场景。 + * @note + * 目前仅支持传输 OPUS 格式的音频数据和 H.264 格式的视频数据。 + * @par 参数说明 + * + * + * + * + * + * + * + * + * + * + * + *
**参数名称****类型****描述**
observerINERtcPreDecodeObserver *接口对象实例。可以传 NULL 表示取消注册。
+ * @par 示例代码 + * @code + * auto ret = rtc_engine_->setPreDecodeObserver(observer); //observer为观测器实例地址 + * if (ret != nertc::kNERtcNoError) { + * // 错误处理 + * } logDebug(">>>setPreDecodeObserver [0x%x] successful", enable ? this : nullptr); + * @endcode + * @par 相关回调 + * \ref nertc::INERtcPreDecodeObserver::onFrame "onFrame"：返回相关解码前媒体数据，包括用户的 UID、媒体数据类型、数据长度等。 + * @return + * - 0（OK）：方法调用成功。 + * - 其他：方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_pre_decode_observer(struct nertc_engine* self, struct nertc_pre_decode_frame_observer* observer); + +/** + * @if English + * Enables volume indication for the speaker. + *
The method allows the SDK to report to the app the information about the volume of the user that pushes local streams + * and the remote user (up to three users) that has the highest instantaneous volume. The information about the current + * speaker and the volume is reported.
If this method is enabled, when a user joins a room and pushes streams, the SDK + * triggers \ref IRtcEngineEventHandlerEx::onRemoteAudioVolumeIndication "onRemoteAudioVolumeIndication" based on the preset + * time intervals. + * @param enable Whether to prompt the speaker volume. + * @param interval The time interval at which volume prompt is displayed. Unit: milliseconds. The value must be the + * multiples of 100 milliseconds. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 启用说话者音量提示。 + *
该方法允许 SDK 定期向 App 反馈本地发流用户和瞬时音量最高的远端用户（最多 3 + * 位）的音量相关信息，即当前谁在说话以及说话者的音量。
启用该方法后，只要房间内有发流用户，无论是否有人说话，SDK + * 都会在加入房间后根据预设的时间间隔触发\ref IRtcEngineEventHandlerEx::onRemoteAudioVolumeIndication + * "onRemoteAudioVolumeIndication"回调。 + * @param enable 是否启用说话者音量提示。 + * @param interval 指定音量提示的时间间隔，单位为毫秒。必须设置为 100 毫秒的整数倍值。 + * @param enable_vad 是否启用本地采集人声监测。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_enable_audio_volume_indication(struct nertc_engine* self, bool enable, uint64_t interval, bool enable_vad); + +/** + * @if English + * Shares screens through specifying regions. Shares a certain screen or part of region of a screen. Users need to specify the + * screen region they wants to share in the method.
When calling the method, you need to specify the screen region to be + * shared, and share the overall frame of the screen or designated regions.
If you join a room and successfully call this + * method to enable the substream, the onUserSubStreamVideoStart and setExcludeWindowList callback is remotely triggered. + * @note + * - The method applies to Windows only. + * - The method enables video substreams. + * @param screen_rect The relative position of the screen to virtual screens that is shared. + * @param region_rect The relative position of shared screen to the full screen. If you set the shared region beyond the + * frame of the screen, only content within the screen is shared. If you set the value of width or height as 0, the full + * screen is shared. + * @param capture_params The configurations of screen sharing. + * @return + * - 0: Success. + * - Other values: Failure. + * + * @endif + * @if Chinese + * 开启屏幕共享，共享范围为指定屏幕的指定区域。 + *
调用该方法时，可以选择共享整个虚拟屏、指定屏幕，或虚拟屏、整个屏幕的某些区域范围。 + *
此方法调用成功后，远端触发 onUserSubStreamVideoStart 和 setExcludeWindowList 回调。 + * @note + * - 该方法仅适用于 Windows。macOS 平台请使用方法 startScreenCaptureByDisplayId。 + * - 该方法需要在加入房间后调用。 + * @param screen_rect 指定待共享的屏幕相对于虚拟屏的位置。 + * @param region_rect + * 指定待共享区域相对于整个屏幕屏幕的位置。如果设置的共享区域超出了屏幕的边界，则只共享屏幕内的内容；如果将 width 或 height + * 设为 0, 则共享整个屏幕。 + * @param capture_params 屏幕共享的编码参数配置。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_start_screen_capture_by_screen_rect(struct nertc_engine* self, + const struct nertc_rectangle* screen_rect, + const struct nertc_rectangle* region_rect, + const struct nertc_screen_capture_parameters* capture_params); + +/** + * @if English + * Enables screen sharing by specifying the ID of the screen. The content of screen sharing is sent by substreams. + *
If you join a room and call this method to enable the substream, the onUserSubStreamVideoStart and + onScreenCaptureStatus callback is remotely triggered. + * @note + * - The method applies to only macOS. + * - The method enables video substreams. + * @param display_id The ID of the screen to be shared. Developers need to specify the screen they share through the + parameters. + * @param region_rect The relative position of shared screen to the full screen. + * @param capture_params The configurations of screen sharing. + * @return + * - 0: Success. + * - Other values: Failure. + + * @endif + * @if Chinese + * 通过指定屏幕 ID 开启屏幕共享，屏幕共享内容以辅流形式发送。 + *
此方法调用成功后，远端触发 onUserSubStreamVideoStart 回调。 + * @note + * - 该方法仅适用于 macOS。Windows 平台请使用方法 startScreenCaptureByScreenRect。 + * - 该方法需要在加入房间后设置。 + * @param display_id 指定待共享的屏幕 ID。开发者需要自行实现枚举屏幕 ID 的方法，并通过该参数指定需要共享的屏幕。 + * @param region_rect + 指定待共享的区域相对于整个窗口的位置。如果设置的共享区域超出了窗口的边界，则只共享窗口内的内容；如果宽或高为 + 0，则共享整个窗口。 + * @param capture_params 屏幕共享的参数配置，包括码率、帧率、编码策略、屏蔽窗口列表等。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_start_screen_capture_by_display_id(struct nertc_engine* self, + uint64_t display_id, + const struct nertc_rectangle* region_rect, + const struct nertc_screen_capture_parameters* capture_params); + +/** + * @if English + * Enables screen sharing by specifying the ID of the window. The content of screen sharing is sent by substreams. + *
If you join a room and call this method to enable the substream, the onUserSubStreamVideoStart and setExcludeWindowList + * callback is remotely triggered. + * @note + * - The method applies to Windows only and macOS. + * - The method enables video substreams. + * @param window_id The ID of the window to be shared. + * @param region_rect The relative position of shared screen to the full screen. + * @param capture_params The configurations of screen sharing. + * @return + * - 0: Success. + * - Other values: Failure. + * + * @endif + * @if Chinese + * 通过指定窗口 ID 开启屏幕共享，屏幕共享内容以辅流形式发送。 + *
调用该方法时需要指定待共享的屏幕 ID，共享该屏幕的整体画面或指定区域。 + *
此方法调用成功后： + * - Windows 平台远端触发 onUserSubStreamVideoStop 和 onScreenCaptureStatus 回调。 + * - macOS 平台远端触发 onUserSubStreamVideoStop 回调。 + * @note + * - 该方法适用于 Windows 和 macOS。 + * - 该方法需要在加入房间后调用。 + * @param window_id 指定待共享的窗口 ID。 + * @param region_rect + * 指定待共享的区域相对于整个窗口的位置。如果设置的共享区域超出了窗口的边界，则只共享指定区域中窗口内的内容；如果宽或高为 + * 0，则共享整个窗口。 + * @param capture_params 屏幕共享的参数配置，包括码率、帧率、编码策略、屏蔽窗口列表等。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_start_screen_capture_by_window_id(struct nertc_engine* self, + void* window_id, + const struct nertc_rectangle* region_rect, + const struct nertc_screen_capture_parameters* capture_params); + + +/** + * @if English + * When sharing a screen or window, updates the shared region. + * @param region_rect The relative position of shared screen to the full screen. If you set the shared region beyond the + * frame of the screen, only content within the screen is shared. If you set width or height as 0, the full screen is shared. + * @return + * - 0: Success. + * - Other values: Failure. + * + * @endif + * @if Chinese + * 在共享屏幕或窗口时，更新共享的区域。 + *
在 Windows 平台中，远端会触发 onScreenCaptureStatus 回调。 + * @param region_rect + * 指定待共享的区域相对于整个窗口或屏幕的位置。如果设置的共享区域超出了边界，则只共享指定区域中，窗口或屏幕内的内容；如果宽或高为 + * 0，则共享整个窗口或屏幕。 + * @return + * - 0: 方法调用成功。 + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_update_screen_capture_region(struct nertc_engine* self, const struct nertc_rectangle* region_rect); + +/** + * @if English + * Displays or hides the pointer during screen sharing. + * @since V4.6.10 + * @param bool specifies whether to display the pointer. + * - true: displays the pointer. + * - false: hides the pointer. + * @return + * - 0: success + * - Others: failure + * @endif + * @if Chinese + * 在共享屏幕或窗口时，更新是否显示鼠标。 + * @since V4.6.10 + * @param capture_cursor 屏幕共享时是否捕捉鼠标光标。 + * - true：共享屏幕时显示鼠标。 + * - false：共享屏幕时不显示鼠标。 + * @return + * - 0: 方法调用成功。 + * - 其他: 方法调用失败 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_screen_capture_mouse_cursor(struct nertc_engine* self, bool capture_cursor); + +/** + * @if English + * Stops screen sharing. + *
If you use the method to disable the substream after joining a room, the onUserSubStreamVideoStop callback is remotely + * triggered. + * @return + * - 0: Success. + * - Other values: Failure. + * + * @endif + * @if Chinese + * 停止屏幕共享。 + *
此方法调用成功后： + * - Windows 平台远端触发 onUserSubStreamVideoStop 和 onScreenCaptureStatus 回调。 + * - macOS 平台远端触发 onUserSubStreamVideoStop 回调。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_stop_screen_capture(struct nertc_engine* self); + +/** + * @if English + * Pauses screen sharing. + * @return + * - 0: Success. + * - Other values: Failure. + * + * @endif + * @if Chinese + * 暂停屏幕共享。 + * - 暂停屏幕共享后，共享区域内会持续显示暂停前的最后一帧画面，直至通过 resumeScreenCapture 恢复屏幕共享。 + * - 在 Windows 平台中，远端会触发 onScreenCaptureStatus 回调。 + * @return + * - 0: 方法调用成功 + * - 其他: 方法调用失败 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_pause_screen_capture(struct nertc_engine* self); + +/** + * @if English + * Resumes screen sharing. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 恢复屏幕共享。 + *
在 Windows 平台中，远端会触发 onScreenCaptureStatus 回调。 + * @return + * - 0: 方法调用成功 + * - 其他: 方法调用失败 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_resume_screen_capture(struct nertc_engine* self); + +/** + * @if English + * Sets the window list that need to be blocked in capturing screens. The method can be dynamically called in the capturing. + * @since V4.2.0 + * @param window_list The ID of the screen to be blocked. + * @param count The number of windows that are needed to be blocked. + * @return + * - 0: Success. + * - Other values: Failure. + * + * @endif + * @if Chinese + * 设置共享整个屏幕或屏幕指定区域时，需要屏蔽的窗口列表。 + *
开启屏幕共享时，可以通过 NERtcScreenCaptureParameters 设置需要屏蔽的窗口列表；在 Windows + * 平台中，开发者可以在开启屏幕共享后，通过此方法动态调整需要屏蔽的窗口列表。被屏蔽的窗口不会显示在屏幕共享区域中。 + * @note + * - 在 Windows 平台中，该接口在屏幕共享过程中可动态调用；在 macOS 平台中，该接口需要在开启屏幕共享之前，即 + * startScreenCaptureByDisplayId 之前调用。 + * - 在 Windows 平台中，某些窗口在被屏蔽之后，如果被置于图层最上层，此窗口图像可能会黑屏。此时会触发 + * onScreenCaptureStatus.kScreenCaptureStatusCovered 回调，建议应用层在触发此回调时提醒用户将待分享的窗口置于最上层。 + * @since V4.2.0 + * @param window_list 需要屏蔽的窗口 ID 列表。 + * @param count 需屏蔽的窗口的数量。 + * @return + * - 0: 方法调用成功 + * - 其他: 方法调用失败 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_exclude_window_list(struct nertc_engine* self, source_id_t* window_list, int count); +/** + * @if Chinese + * 更新屏幕共享参数。 + *
开始共享屏幕或窗口后，动态更新采集帧率，目标码率，编码分辨率等屏幕共享相关参数。 + * @since V4.6.20 + * @par 调用时机 + * 请在加入房间并成功开启屏幕共享后调用该方法。 + * @note + * - 调用该方法会重新启动屏幕共享，因此建议不要频繁调用。 + * - + * 可以通过该方法动态设置是否捕捉鼠标（capture_mouse_cursor）和设置排除窗口（excluded_window_list，excluded_window_count），同时这两项设置也可以通过 + * \ref IRtcEngineEx::setScreenCaptureMouseCursor "setScreenCaptureMouseCursor" 和 \ref IRtcEngineEx::setExcludeWindowList + * "setExcludeWindowList" 方法实现。 + * @par 参数说明 + * + * + * + * + * + * + * + * + * + * + * + *
**参数名称****类型****描述**
capture_params \ref nertc::NERtcScreenCaptureParameters "NERtcScreenCaptureParameters"屏幕共享编码参数配置。
+ * @par 示例代码 + * @code + * //调用该方法时，需要维护一个 nertc::NERtcScreenCaptureParameters captureParams 变量记录当前设置。更新设置的时候： + * nertc::NERtcScreenCaptureParameters captureParams; + * captureParams.field1 = new_value1; + * captureParams.field2 = new_value2; + * ... + * updateScreenCaptureParameters(captureParams); + * @endcode + * @par 相关回调 + * 成功调用该方法后，会触发 \ref IRtcChannelEventHandler::onScreenCaptureStatus "onScreenCaptureStatus" 回调。 + * @return + * - 0（kNERtcNoError）：方法调用成功。 + * - 其他：方法调用失败。 + * - 30005（kErrorErrInvalidState）：多房间状态错误。 + * - 30021（kNERtcErrDesktopCaptureInvalidParam）：传入的参数无效。 + * - 30101（kNERtcErrChannelNotJoined）：未加入房间。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_update_screen_capture_parameters(struct nertc_engine* self, const struct nertc_screen_capture_parameters* capture_params); + +/** + * @if English + * Enables or disables the external video source. + *
When you enable the external video source through the method, you need to set kNERtcExternalVideoDeviceID as the ID of + * external video source with IVideoDeviceManager::setDevice kNERtcExternalVideoDeviceID method. + * @note The method enables the internal engine, which is still valid after you call \ref IRtcEngine::leaveChannel + * "leaveChannel". + * @param[in] enabled Specifies whether input external video source data. + * - true: Enables external video source. + * - false: Disables the external video source (default). + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 开启或关闭外部视频源数据输入。 + *
通过该方法启用外部视频数据输入功能时，需要通过 IVideoDeviceManager::setDevice 设置 kNERtcExternalVideoDeviceID + * 为外部视频输入源 ID。 + * @note 该方法设置内部引擎为启用状态，在 \ref IRtcEngine::leaveChannel "leaveChannel" 后仍然有效。 + * 请务必保证视频主流和辅流输入通道各最多只能有一种视频输入源，其中屏幕共享只能通过辅流通道开启，因此： + * - 若您开启了辅流形式的屏幕共享，请使用主流通道输入外部视频源数据，即设置 type 参数为 kNERTCVideoStreamMain。 + * - 若您已调用 \ref nertc::IRtcEngine::enableLocalVideo(NERtcVideoStreamType type, bool enabled) "enableLocalVideo"方法开启本地主流视频采集，请勿再调用此接口创建主流形式的外部视频源输入，辅流通道同理。 + * @param[in] type 视频通道类型: + * @param[in] enabled 是否外部视频源数据输入: + * - true: 开启外部视频源数据输入； + * - false: 关闭外部视频源数据输入 (默认)。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_external_video_source(struct nertc_engine* self, nertc_video_stream_type type, bool enabled); + +/** + * @if English + * Pushes the external video frames. + *
The method actively pushes the data of video frames that are encapsulated with the NERtcVideoFrame class to the SDK. + * Make sure that you have already called setExternalVideoSource with a value of true before you call this method. Otherwise, + * an error message is repeatedly prompted if you call the method. + * @note The method enables the internal engine, which is invalid after you call \ref IRtcEngine::leaveChannel "leaveChannel". + * @param[in] frame The video frame data. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 推送辅流的外部视频帧。 + *
该方法主动将视频帧数据用 NERtcVideoFrame 类封装后传递给 SDK。 请确保在你调用本方法前已调用 + * setExternalVideoSource，并将参数设为 true，否则调用本方法后会一直报错。 + * @note 该方法设置内部引擎为启用状态，在 \ref IRtcEngine::leaveChannel "leaveChannel" 后不再有效。 + * @param[in] type 视频通道类型。 + * @param[in] frame 视频帧数据。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_push_external_video_frame(struct nertc_engine* self, nertc_video_stream_type type, struct nertc_video_frame* frame); + +/** + * @if English + * Pushes the external video encoded frames. + *
The method actively pushes the data of video encoded frames that are encapsulated with the NERtcVideoEncodedFrame class + * to the SDK. Make sure that you have already called setExternalVideoSource with a value of true before you call this method. + * Otherwise, an error message is repeatedly prompted if you call the method.
Make sure that you have already called + * enableDualStreamMode with a value of false before you call this method. Otherwise, the peer may not receive video. + * @note The method enables the internal engine, which is invalid after you call \ref IRtcEngine::leaveChannel "leaveChannel". + * @since V4.6.25 + * @param[in] encoded_frame The video encoded frame data. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 推送外部视频编码帧。 + * - 通过此接口可以实现通过主流或辅流视频通道推送外部视频编码后的数据。 + * @since V4.6.29 + * @par 使用前提 + * 该方法仅在设置 \ref IRtcEngineEx::setExternalVideoSource(NERtcVideoStreamType type, bool enabled) "setExternalVideoSource" + * 接口的 enable 参数为 true 后调用有效。 + * @par 调用时机 + * 请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。 + * @par 业务场景 + * 适用于需要自行处理视频数据的采集与编码的场景。 + * @note + * - 目前仅支持传输 H.264 格式的视频数据。 + * - 该方法设置内部引擎为启用状态，在 \ref IRtcEngine::leaveChannel "leaveChannel" 后设置会重置为默认状态。 + * - 建议先调用 \ref IRtcEngineEx#enableDualStreamMode "enableDualStreamMode"} + * 方法关闭视频大小流功能，否则远端可能无法正常接收下行流。 + * - 建议不要同时调用 \ref IRtcEngineEx::pushExternalVideoFrame "pushExternalVideoFrame" 方法。 + * - 外部视频源数据的输入通道、本地视频采集通道与外部视频编码帧数据的推送通道必须同为主流或者辅流通道，否则 SDK 会报错。 + * @par 参数说明 + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
**参数名称****类型****描述**
encoded_frameNERtcVideoEncodedFrame*编码后的视频帧数据。
type \ref nertc::NERtcVideoStreamType "NERtcVideoStreamType"视频通道类型：
  • kNERTCVideoStreamMain：主流。
  • kNERTCVideoStreamSub：辅流。
+ * @par 示例代码 + * @code + * nertc::NERtcVideoEncodedFrame frame; + * memset(&frame, 0, sizeof(frame)); + * frame.codec_type = nertc::kNERtcVideoCodecTypeH264; // H264类型，详见NERtcVideoCodecType + * frame.frame_type = nertc::kNERtcNalFrameTypeIDR; // IDR帧，详见NERtcNalFrameType + * frame.nal_count = nalCnt; // nal个数 + * frame.nal_length = nalLen; // 每个nal对应的长度数组 + * frame.nal_data = data; // nal数据 + * frame.timestamp_us = TimeMicros(); // 机器时间，us + * frame.width = width; // 视频宽 + * frame.height = height; // 视频高 + * auto ret = rtc_engine_->pushExternalVideoEncodedFrame(&frame); + * if (ret != nertc::kNERtcNoError) { + * // 错误处理 + * } + * @endcode + * @par 相关接口 + * 可以调用 \ref IRtcEngineEx::setVideoEncoderQosObserver "setVideoEncoderQosObserver" 接口设置视频编码 QoS + * 信息监听器，通过回调的数据信息调整编码策略。 + * @return + * - 0（kNERtcNoError）：方法调用成功。 + * - 其他：方法调用失败。 + * - 11403（kNERtcErrInvalid）：无效操作，比如未开启外部视频输入。 + * - 30003（kNERtcErrInvalidParam）：参数错误，比如传入对象为空。 + * - 30005（kNERtcErrInvalidState）：状态错误，比如引擎未初始化或视频未开启。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_push_external_video_encoded_frame(struct nertc_engine* self, + nertc_video_stream_type type, + struct nertc_video_encoded_frame* encoded_frame); + +/** + * @if English + * Enables or disables the external audio stream source. + *
After you call the method, the setting becomes invalid if you choose audio input device or a sudden restart occurs. + * After the method is called, you can call pushExternalAudioFrame to send the pulse-code modulation (PCM) data. + * @note + * - You can call this method before joining a room. + * - The method enables the internal engine. After enabled, the virtual component works instead of the physical microphones. + * The setting remains unchanged after the leaveChannel method is called. If you want to disable the feature, you must disable + * the setting before next call starts. + * - After you enable the external audio data input, some functionalities of the speakerphone supported by the SDK are + * replaced by the external audio source. Settings that are applied to the microphones become invalid or do not take effect in + * calls. For example, you can hear the external data input when you use loopback for testing. + * @param[in] enabled Specifies whether to input external data. + * - true: Enables external data input. + * - false: Disables the external data input(default). + * @param[in] sample_rate The sample rate of data. You need to input following data in the same sample rate. Note: If you + * call the method to disable the functionality, you can pass in a random valid value. In this case, the setting does not take + * effect. + * @param[in] channels The number of channels. You need to input following data in the same number of channels. Note: If + * you call the method to disable the functionality, you can pass in a random valid value. In this case, the setting does not + * take effect. Valid values: + * - 1: Mono sound. + * - 2: Stereo sound. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 开启或关闭外部音频源数据输入。 + *
当该方法调用成功后，音频输入设备选择和异常重启会失效。调用成功后可以使用 pushExternalAudioFrame 接口发送音频 PCM 数据。 + * @note + * - 请在加入房间前调用该方法。 + * - + * 该方法设置内部引擎为启用状态，启动时将用虚拟设备代替麦克风工作，在leaveChannel后仍然有效。如果需要关闭该功能，需要在下次通话前调用接口关闭外部音频数据输入功能。 + * - 启用外部音频数据输入功能后，SDK 内部实现部分麦克风由外部输入数据代替，麦克风相关的设置会失败或不在通话中生效。例如进行 + * loopback 检测时，会听到输入的外部数据。 + * @param[in] enabled 是否外部数据输入: + * - true: 开启外部数据输入； + * - false: 关闭外部数据输入 (默认)。 + * @param[in] sample_rate 数据采样率，后续数据传入需要按该格式传入。 + * 注意：调用接口关闭功能时可传入任意合法值，此时设置不会生效。 + * @param[in] channels 数据声道数，后续数据传入需要按该格式传入。注意：调用接口关闭功能时可传入任意合法值，此时设置不会生效。 + * 可设置为： + * - 1：单声道。 + * 2：双声道。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_external_audio_source(struct nertc_engine* self, nertc_audio_stream_type type, bool enabled, int sample_rate, int channels); + +/** + * @if English + * Pushes the external audio data input. + *
Pushes the audio frame data captured from the external audio source to the internal audio engine. If you enable the + * external audio data source by calling setExternalAudioSource, you can use pushExternalAudioFrame to send audio PCM data. + * @note + * - This method can be called only if a user joins a room. + * - We recommend that you set the duration of data frames to match a cycle of 10 ms. + * - External input data frame consists of the data duration and call duration. + * - The method becomes invalid if the audio input device is turned off. For example, disable local audio, end calls, and shut + * off the microphone test before calls. + * @param[in] frame The data of frame cannot exceed 7680 bytes in length. + * - External input data frame consists of the data duration and call duration. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 推送外部音频数据输入。 + *
将外部音频数据帧推送给内部引擎。 通过 setExternalAudioSource 启用外部音频数据输入功能成功后，可以使用 + * pushExternalAudioFrame 接口发送音频 PCM 数据。 + * @note + * - 该方法需要在加入房间后调用。 + * - 数据帧时长建议匹配 10ms 周期。 + * - 外部输入数据帧，数据时长和调用周期时长一致。 + * - 该方法在音频输入设备关闭后不再生效。例如关闭本地音频、通话结束、通话前麦克风设备测试关闭等情况下，该设置不再生效。 + * @param[in] frame 帧数据，数据长度不能超过7680: + * - 外部输入数据帧，数据时长和调用周期时长一致。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_push_external_audio_frame(struct nertc_engine* self, nertc_audio_stream_type type, struct nertc_audio_frame* frame); + +/** + * @if English + * Pushes the external audio encoded data input. + *
Pushes the audio encoded frame data from the external to the internal audio engine. If you enable the external audio data + * source by calling setExternalAudioSource, you can use pushExternalAudioEncodedFrame to send audio encoded data. + * @note + * - This method can be called only if a user joins a room. + * - The method becomes invalid if the audio input device is turned off. For example, disable local audio, end calls. + * @since V4.6.25 + * @param[in] encoded_frame External input enocde data frame. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 推送外部音频主流编码帧。 + * - 通过此接口可以实现通过主流音频通道推送外部音频编码后的数据。 + * @since V4.6.29 + * @par 使用前提 + * 该方法仅在设置 \ref nertc::IRtcEngineEx::setExternalAudioSource "setExternalAudioSource" 接口的 enabled 参数为 true + * 后调用有效。 + * @par 调用时机 + * 请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。 + * @par 业务场景 + * 适用于需要自行处理音频数据的采集与编码的场景。 + * @note + * - 目前仅支持传输 OPUS 格式的音频数据。 + * - 建议不要同时调用 \ref nertc::IRtcEngineEx::pushExternalAudioFrame "pushExternalAudioFrame" 方法。 + * - 该方法在音频输入设备关闭后，例如在关闭本地音频、通话结束、通话前麦克风设备测试关闭等情况下，设置会恢复至默认。 + * @par 参数说明 + * + * + * + * + * + * + * + * + * + * + * + *
**参数名称****类型****描述**
encoded_frameNERtcAudioEncodedFrame*编码后的音频帧数据。
+ * @par 示例代码 + * @code + * int timediff = 20; // opus need 20ms + * uint64_t encoded_audio_ts = 0; + * nertc::NERtcAudioEncodedFrame audioFrame; + * memset(&audioFrame, 0, sizeof(audioFrame)); + * audioFrame.sample_rate = sample_rate; //采样率 + * audioFrame.channels = channels; // 声道数 + * audioFrame.samples_per_channel = sample_rate / 1000 * timediff; //每声道采样数 + * audioFrame.payload_type = nertc::kNERtcAudioPayloadTypeOPUS; // OPUS, 参考NERtcAudioPayloadType + * audioFrame.encoded_len = len; // 编码后数据长度 + * audioFrame.data = data; // 编码后数据 + * audioFrame.timestamp_us = TimeMicros(); // 机器时间，us + * audioFrame.encoded_timestamp = encoded_audio_ts; // 编码时间, 单位为样本数 + * encoded_audio_ts += audioFrame.samples_per_channel; + * auto ret = rtc_engine_->pushExternalAudioEncodedFrame(&audioFrame); + * if (ret != nertc::kNERtcNoError) { + * // 错误处理 + * } + * @endcode + * @return + * - 0（kNERtcNoError）：方法调用成功。 + * - 其他：方法调用失败。 + * - 30001（kNERtcErrFatal）：未开启外部音频输入。 + * - 30003（kNERtcErrInvalidParam）：参数错误，比如传入对象为空。 + * - 30005（kNERtcErrInvalidState）：状态错误，比如尚未加入房间或未开启本地音频。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_push_external_audio_encoded_frame(struct nertc_engine* self, nertc_audio_stream_type type, struct nertc_audio_encoded_frame* encoded_frame); + +/** + * @if English + * Sets external audio rendering. + *
The method is suitable for scenarios that require personalized audio rendering. By default, the setting is disabled. If + * you choose an audio playback device or a sudden restart occurs, the setting becomes invalid. After you call the method, you + * can use pullExternalAudioFrame to get audio PCM data. + * @note + * - You can call this method before joining a room. + * - The method enables the internal engine. The virtual component works instead of the physical speaker. The setting remains + * valid after you call the leaveChannel method. If you want to disable the functionality, you must disable the functionality + * before the next call starts. + * - After you enable the external audio rendering, some functionalities of the speakerphone supported by the SDK are replaced + * by the external audio source. Settings that are applied to the speakerphone become invalid or do not take effect in calls. + * For example, external rendering is required to play the external audio when you use loopback for testing. + * @param[in] enabled Specifies whether to output external data. + * - true: Enables external data rendering. + * - false: Disables the external data rendering (default). + * @param[in] sample_rate The sample rate of data. You need to input following data in the same sample rate. + * Note: If you call the method to disable the functionality, you can pass in a random valid value. In this case, the setting + * does not take effect. + * @param[in] channels The number of data channels. You need to return following data in the same number of channels. + * Note: If you call the method to disable the functionality, you can pass in a random valid value. In this case, the setting + * does not take effect. Valid values: + * - 1: Mono sound. + * - 2: Stereo sound. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 设置外部音频渲染。 + *
该方法适用于需要自行渲染音频的场景。默认为关闭状态。当该方法调用成功后，音频播放设备选择和异常重启失效。 + * 调用成功后可以使用 pullExternalAudioFrame 接口获取音频 PCM 数据。 + * @note + * - 请在加入房间前调用该方法。 + * - + * 该方法设置内部引擎为启用状态，启动时将用虚拟设备代替扬声器工作，在leaveChannel后仍然有效。如果需要关闭该功能，需要在下次通话前调用接口关闭外部音频数据渲染功能。 + * - 启用外部音频渲染功能后，SDK 内部实现部分扬声器由外部输入数据代替，扬声器相关的设置会失败或不在通话中生效。例如进行 + * loopback 检测时，需要由外部渲染播放。 + * @param[in] enabled 是否外部数据输出: + * - true: 开启外部数据渲染； + * - false: 关闭外部数据渲染 (默认)。 + * @param[in] sample_rate 数据采样率，后续数据按该格式返回。 + * 注意：调用接口关闭功能时可传入任意合法值，此时设置不会生效。 + * @param[in] channels 数据声道数，后续数据按该格式返回。 + * 注意：调用接口关闭功能时可传入任意合法值，此时设置不会生效。 + * 可设置为： + * - 1：单声道。 + * - 2：双声道。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_external_audio_render(struct nertc_engine* self, bool enabled, int sample_rate, int channels); + +/** + * @if English + * Pulls the external audio data. + *
The method pulls the audio data from the internal audio engine. After you enable the external audio data rendering + * functionality by calling setExternalAudioRender, you can use pullExternalAudioFrame to get the audio PCM data. + * @note + * - This method can be called only if a user joins a room. + * - We recommend that you set the duration of data frames to match a cycle of 10 ms. + * - The method becomes invalid if the audio rendering device is turned off. In this case, no data is returned. For example, + * calls end, and the speakerphone is shut off before calls. + * @param[out] data Data pointer. The SDK internally copies data into data. + * @param[in] len The size of the audio data that are pulled. Unit: bytes. + * - We recommend that the duration of the audio data at least last 10 ms, and the data size cannot exceed 7,680 bytes. + * - Formula: len = sampleRate/1000 × 2 × channels × duration of the audio data in milliseconds. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 拉取外部音频数据。 + *
该方法将从内部引擎拉取音频数据。 通过 setExternalAudioRender 启用外部音频数据渲染功能成功后，可以使用 + * pullExternalAudioFrame 接口获取音频 PCM 数据。 + * @note + * - 该方法需要在加入房间后调用。 + * - 数据帧时长建议匹配 10ms 周期。 + * - 该方法在音频渲染设备关闭后不再生效，此时会返回空数据。例如通话结束、通话前扬声器设备测试关闭等情况下，该设置不再生效。 + * @param[out] data 数据指针，SDK内部会将数据拷贝到data中。 + * @param[in] len 待拉取音频数据的字节数，单位为 byte。 + * - 建议音频数据的时长至少为 10 毫秒，数据长度不能超过 7680字节。 + * - 计算公式为： len = sampleRate/1000 × 2 × channels × 音频数据时长（毫秒）。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_pull_external_audio_frame(struct nertc_engine* self, void* data, int length); + +/** + * @if English + * Query the SDK version number. + * - You can call this method before or after you join a room. + * @param[out] build The compilation number. + * @return The version of the current SDK, whose format is string such as 1.0.0. + * @endif + * @if Chinese + * 查询 SDK 版本号。 + * 该方法在加入房间前后都能调用。 + * @return 当前的 SDK 版本号，格式为字符串，如1.0.0. + * @endif + */ +NERTC_API const char* NERTC_CALL nertc_engine_get_version(struct nertc_engine* self); + +/** + * @if English + * Check the error description of specified error codes. + * @note The method is currently invalid. Returns the value of empty only. Please check returned error codes and specific + * error descriptions in the \ref IRtcEngineEventHandler::onError "onError" . + * @param[in] error_code #NERtcErrorCode. + * @return Detailed descriptions of error codes. + * @endif + * @if Chinese + * 查看指定错误码的错误描述。 + * @note 目前该方法无效，只返回空值。请在 \ref IRtcEngineEventHandler::onError "onError" 中查看返回的错误码及具体的错误描述。 + * @param[in] error_code #NERtcErrorCode 。 + * @return 详细错误码描述 + * @endif + */ +NERTC_API const char* NERTC_CALL nertc_engine_get_error_description(struct nertc_engine* self, int error_code); + +/** + * @if English + * Uploads the SDK information. + *
You can call the method only after joining a room. + *
The data that is published contains the log file and the audio dump file. + * @return void + * @endif + * @if Chinese + * 上传 SDK 信息。 + *
只能在加入房间后调用。 + *
上传的信息包括 log 和 Audio dump 等文件。 + * @return void + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_upload_sdk_info(struct nertc_engine* self); + +/** + * @if English + * After the method is successfully called, the current user can receive the notification about the status of the live stream. + * @note + * - The method is applicable to only live streaming. + * - You can call the method in a room. The method is valid in calls. + * - Only one address for the relayed stream is added in each call. You need to call the method for multiple times if you want + * to push many streams. An RTC room with the same channelid can create three different streaming tasks. + * - After the method is successfully called, the current user will receive related-status notifications of the live stream. + * @param[in] info indicates information of live task. For more information, see \ref NERtcLiveStreamTaskInfo + * "NERtcLiveStreamTaskInfo". + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 添加房间推流任务，成功添加后当前用户可以收到该直播流的状态通知。 + * @note + * - 该方法仅适用直播场景。 + * - 请在房间内调用该方法，该方法在通话中有效。 + * - 该方法每次只能增加一路旁路推流地址。如需推送多路流，则需多次调用该方法。同一个音视频房间（即同一个 channelid）可以创建 3 + * 个不同的推流任务。 + * - 成功添加推流任务后，当前用户会收到该直播流的相关状态通知。 + * @param[in] info 直播任务信息。详细信息请参考 \ref NERtcLiveStreamTaskInfo "NERtcLiveStreamTaskInfo" + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_add_live_stream_task(struct nertc_engine* self, const struct nertc_live_stream_task_info* info); + +/** + * @if English + * Updates and modifies a push task in a room. + * @note + * - The method is applicable to only live streaming. + * - You can call the method in a room. The method is valid in calls. + * @param[in] info indicates information of live task. For more information, see \ref NERtcLiveStreamTaskInfo + * "NERtcLiveStreamTaskInfo". + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 更新修改房间推流任务。 + * @note + * - 该方法仅适用直播场景。 + * - 请在房间内调用该方法，该方法在通话中有效。 + * @param[in] info 直播任务信息。详细信息请参考 \ref NERtcLiveStreamTaskInfo "NERtcLiveStreamTaskInfo" + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_update_live_stream_task(struct nertc_engine* self, const struct nertc_live_stream_task_info* info); + +/** + * @if English + * Deletes a push task. + * @note + * - The method is applicable to only live streaming. + * - You can call the method in a room. The method is valid in calls. + * - When calls stop and all members in the room leave the room, the SDK automatically deletes the streaming task. If some + * users are still in the room, users who create the streaming task need to delete the streaming task. + * @param[in] task_id The ID of a live streaming task. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 删除房间推流任务。 + * @note + * - 该方法仅适用直播场景。 + * - 请在房间内调用该方法，该方法在通话中有效。 + * - 通话结束，房间成员全部离开房间后，推流任务会自动删除。如果房间内还有用户存在，则需要创建推流任务的用户删除推流任务。 + * @param[in] task_id 直播任务 ID。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_remove_live_stream_task(struct nertc_engine* self, const char* task_id); + +/** + * @if English + * Sends SEI messages. + *
While the local video stream is pushed, SEI data is also sent to sync some additional information. After SEI data is + * sent, the receiver can retrieve the content by listening on \ref IRtcEngineEventHandlerEx::onRecvSEIMsg callback. + * - Condition: After the video stream (mainstream) is enabled, the function can be invoked. + * - Data size limits: The SEI data can contain a maximum of 4,096 bytes in size. Sending an SEI message fails if the data + * exceeds the size limit. If a large amount of data is sent, the video bitrate rises. This degrades the video quality or + * causes broken video frames. + * - Frequency limit: we recommend that the maximum video frame rate does not exceed 10 fps. + * - Time to take effect: After the method is called, the SEI data is sent from the next frame in the fastest fashion or after + * the next 5 frames at the slowest pace. + * @note + * - The SEI data is transmitted together with the video stream. Frame loss may occur in poor network connection. The SEI data + * will also get lost. We recommend that you send the data many times within the transmission frequency limits. In this way, + * the receiver can get the data. + * - By default, the SEI is transmitted by using the mainstream channel. + * @param data The custom SEI frame data. + * @param length The custom SEI data size whose maximum value does not exceed 4096 bytes. + * @param type The type of the stream channel with which the SEI data is transmitted. For more information, see + * #NERtcVideoStreamType. + * @return The value returned. A value of 0 That the operation is successful. + * - Success: Successfully joins the queue to be sent. The data are sent after the closest video frame. + * - failure: Date are limitedly sent for the high sent frequency and the overloaded queue. Or, the maximum data size exceeds + * 4k. + * @endif + * @if Chinese + * 发送媒体补充增强信息（SEI）。 + *
在本端推流传输视频流数据同时，发送流媒体补充增强信息来同步一些其他附加信息。当推流方发送 SEI 后，拉流方可通过监听 \ref + * IRtcEngineEventHandlerEx::onRecvSEIMsg 的回调获取 SEI 内容。 + * - 调用时机：视频流（主流）开启后，可调用此函数。 + * - 数据长度限制： SEI 最大数据长度为 4096 + * 字节，超限会发送失败。如果频繁发送大量数据会导致视频码率增大，可能会导致视频画质下降甚至卡顿。 + * - 发送频率限制：最高为视频发送的帧率，建议不超过 10 次/秒。 + * - 生效时间：调用本接口之后，最快在下一帧视频数据帧之后发送 SEI 数据，最慢在接下来的 5 帧视频之后发送。 + * @note + * - SEI 数据跟随视频帧发送，由于在弱网环境下可能丢帧，SEI + * 数据也可能随之丢失，所以建议在发送频率限制之内多次发送，保证接收端收到的概率。 + * - 调用本接口时，默认使用主流通道发送 SEI。 + * @param data 自定义 SEI 数据。 + * @param length 自定义 SEI 数据长度，最大不超过 4096 字节。 + * @param type 发送 SEI 时，使用的流通道类型。详细信息请参考 #NERtcVideoStreamType 。 + * @return 操作返回值，成功则返回 0 + * - 成功: 成功进入待发送队列，会在最近的视频帧之后发送该数据 + * - 失败: 数据被限制发送，可能发送的频率太高，队列已经满了，或者数据大小超过最大值 4k + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_send_sei_msg(struct nertc_engine* self, const unsigned char* data, int length, nertc_video_stream_type type); + +/** + * @if English + * Set the video watermark, the watermark will take effect in the local preview and sending process. + * @param enabled add or remove watermark + * @param type The type of video streams. You can set the value to mainstream or substream. For more information, see + #NERtcVideoStreamType.。 + * @param config The configuration of the watermark for the canvas. You can set text watermark, image watermark, and timestamp + watermark. A value of null is set to remove the watermark. + * For more information, see \ref NERtcVideoWatermarkConfig. + * @return + - 0: Success. + - Other values: Failure. + * @endif + * @if Chinese + * 设置视频水印，水印在本地预览及发送过程中均生效。 + * @note 设置水印后，建议关注水印状态回调 \ref nertc::IRtcEngineEventHandlerEx::onLocalVideoWatermarkState + "onLocalVideoWatermarkState"。 + * @since V4.6.10 + * @param enabled 添加或删除水印。 + * - true：添加水印。 + * - false：删除水印。 + * @param type 视频流类型。支持设置为主流或辅流。详细信息请参考 #NERtcVideoStreamType 。 + * @param config 视频水印配置。支持设置文字水印、图片水印和时间戳水印。详细信息请参考 \ref nertc::NERtcVideoWatermarkConfig + "NERtcVideoWatermarkConfig" 。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_local_video_watermark_configs(struct nertc_engine* self, + bool enabled, + nertc_video_stream_type type, + const nertc_video_watermark_config* config); + +/** + * @if English + * Takes a local video snapshot. + *
The takeLocalSnapshot method takes a local video snapshot on the local substream or local mainstream, and call \ref + * NERtcTakeSnapshotCallback "NERtcTakeSnapshotCallback::onTakeSnapshotResult" callback to return data of snapshot screen. + * @note + * - Before you call the method to capture the snapshot from the mainstream, you must first call startVideoPreview or + * enableLocalVideo, and joinChannel. + * - Before you call the method to capture the snapshot from the substream, you must first call startScreenCapture, and + * joinChannel. + * - You can set text, timestamp, and image watermarks at the same time. If different types of watermarks overlap, the layers + * override previous layers following image, text, and timestamp. + * @param stream_type The video stream type of the snapshot. You can set the value to mainstream or substream. For more + * information, see #NERtcVideoStreamType. + * @param callback The snapshot callback. For information, see \ref NERtcTakeSnapshotCallback. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 本地视频画面截图。 + *
调用 takeLocalSnapshot 截取本地主流或本地辅流的视频画面，并通过 \ref NERtcTakeSnapshotCallback + * "NERtcTakeSnapshotCallback::onTakeSnapshotResult" 回调返回截图画面的数据。 + * @note + * - 本地主流截图，需要在 startPreview 或者 enableLocalVideo 并 joinChannel 成功之后调用。 + * - 本地辅流截图，需要在 startScreenCapture 并 joinChannel 成功之后调用。 + * - 同时设置文字、时间戳或图片水印时，如果不同类型的水印位置有重叠，会按照图片、文本、时间戳的顺序进行图层覆盖。 + * @param stream_type 截图的视频流类型。支持设置为主流或辅流。详细信息请参考 #NERtcVideoStreamType 。 + * @param callback 截图回调。详细信息请参考 \ref NERtcTakeSnapshotCallback 。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_take_local_snapshot(struct nertc_engine* self, nertc_video_stream_type stream_type, on_take_snapshot_callback callback); + + /** + * @if English + * Takes a snapshot of a remote video. + *
You can call takeRemoteSnapshot to specify the uid of video screen of remote mainstreams and substreams, and returns + * screenshot data of \ref NERtcTakeSnapshotCallback "NERtcTakeSnapshotCallback::onTakeSnapshotResult" callback. + * @note + * - You need to call takeRemoteSnapshot after receiving callbacks of onUserVideoStart and onUserSubStreamVideoStart. + * - You can set text, timestamp, and image watermarks at the same time. If different types of watermarks overlap, the layers + * override previous layers following image, text, and timestamp. + * @param uid The ID of a remote user. + * @param stream_type The video stream type of the snapshot. You can set the value to mainstream or substream. For more + * information, see #NERtcVideoStreamType. + * @param callback The snapshot callback. For information, see \ref NERtcTakeSnapshotCallback. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 远端视频画面截图。 + *
调用 takeRemoteSnapshot 截取指定 uid 远端主流和远端辅流的视频画面，并通过 \ref NERtcTakeSnapshotCallback + * "NERtcTakeSnapshotCallback::onTakeSnapshotResult" 回调返回截图画面的数据。 + * @note + * - takeRemoteSnapshot 需要在收到 onUserVideoStart 与 onUserSubStreamVideoStart 回调之后调用。 + * - 同时设置文字、时间戳或图片水印时，如果不同类型的水印位置有重叠，会按照图片、文本、时间戳的顺序进行图层覆盖。 + * @param uid 远端用户 ID。 + * @param stream_type 截图的视频流类型。支持设置为主流或辅流。详细信息请参考 #NERtcVideoStreamType 。 + * @param callback 截图回调。详细信息请参考 \ref NERtcTakeSnapshotCallback 。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_take_remote_snapshot(struct nertc_engine* self, nertc_uid_t uid, nertc_video_stream_type stream_type, on_take_snapshot_callback callback); + + /** + * @if English + * Starts an audio recording on a client. + *
After calling the method, the client records the audio streams that are mixed by all users, and stores the streams in a + local file. The onAudioRecording() callback is triggered when the recording starts or ends. + *
If you specify a type of audio quality, the recording file is saved in different formats. + * - WAV file is large with high quality. + * - AAC file is small with low quality. + * @note + * - You must call the method after calling the method after joining a room. + * - A client can only run a recording task. If you repeatedly call the startAudioRecording method, the current recording task + stops and a new recording task starts. + * - If the current user leaves the room, the audio recording automatically stops. You can call the stopAudioRecording method + to manually stop recording during calls. + * @param file_path The absolute path where the recording file is saved. The file name and format must be accurate. For + example, sdcard/xxx/audio.aac. + - Make sure that the specified path is valid and has the write permission. + - Only WAV or AAC files are supported. + * @param sample_rate The audio sample rate (Hz). Valid values: 16000, 32000, 44100, and 48000. The default value is 32000. + * @param quality The audio quality. The parameter is valid only the audio file is in AAC format. For more information, + see NERtcAudioRecordingQuality. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 开始客户端录音。 + *
调用该方法后，客户端会录制房间内所有用户混音后的音频流，并将其保存在本地一个录音文件中。录制开始或结束时，自动触发 + onAudioRecording() 回调。 + *
指定的录音音质不同，录音文件会保存为不同格式： + * - WAV：音质保真度高，文件大。 + * - AAC：音质保真度低，文件小。 + * @note + * - 请在加入房间后调用此方法。 + * - 客户端只能同时运行一个录音任务，正在录音时，如果重复调用 + startAudioRecording，会结束当前录制任务，并重新开始新的录音任务。 + * - 当前用户离开房间时，自动停止录音。您也可以在通话中随时调用 stopAudioRecording 手动停止录音。 + * @param file_path 录音文件在本地保存的绝对路径，需要精确到文件名及格式。例如：sdcard/xxx/audio.aac。 + - 请确保指定的路径存在并且可写。 + - 目前仅支持 WAV 或 AAC 文件格式。 + * @param sample_rate 录音采样率（Hz），可以设为 16000、32000（默认）、44100 或 48000。 + * @param quality 录音音质，只在 AAC 格式下有效。详细说明请参考 NERtcAudioRecordingQuality。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ + NERTC_API int NERTC_CALL nertc_engine_start_audio_recording(struct nertc_engine* self, const char* file_path, int32_t sample_rate, nertc_audio_recording_quality quality); + /** + * @if English + * Starts an audio recording from a client. + *
The method records the mixing audio from all room members in the room, and store the recording file locally. The + * onAudioRecording() callback is triggered when the recording starts or ends.
If you specify a type of audio quality, the + * recording file is saved in different formats. + * - A WAV file is large with high quality + * - An AAC file is small with low quality. + * @note + * - You must call the method after you call joinChannel. + * - A client can only run a recording task. If you repeatedly call the startAudioRecordingWithConfig method, the current + * recording task stops and a new recording task starts. + * - If the current user leaves the room, audio recording automatically stops. You can call the stopAudioRecording method to + * manually stop recording during calls. + * @param filePath The file path where the recording file is stored. The file name and format are required. For example, + * sdcard/xxx/audio.aac. + * - Make sure that the path is valid and has the write permissions. + * - Only WAV or AAC files are supported. + * @param sampleRate The recording sample rate. Valid values: 16000, 32000, 44100, and 48000. The default value is 32000. + * @param quality The audio quality. The parameter is valid only the recording file is in AAC format. For more information, + * see {@link NERtcAudioRecordingQuality}. + * @param position The recording object. For more information, see {@link NERtcAudioRecordingPosition}。 + * @param cycleTime The maximum number of seconds for loop caching. You can set the value to 0, 10, 60, 360, and 900. The + * default value is 0. The write operation runs in real time. + * @return + * - 0: success + * - Others: failure + * @endif + * @if Chinese + * 开始客户端录音。 + * 调用该方法后，客户端会录制房间内所有用户混音后的音频流，并将其保存在本地一个录音文件中。录制开始或结束时，自动触发 + * onAudioRecording() 回调。 指定的录音音质不同，录音文件会保存为不同格式： + * - WAV：音质保真度高，文件大。 + * - AAC：音质保真度低，文件小。 + * @note + * - 请在加入房间后调用此方法。 + * - 客户端只能同时运行一个录音任务，正在录音时，如果重复调用 + * startAudioRecordingWithConfig，会结束当前录制任务，并重新开始新的录音任务。 + * - 当前用户离开房间时，自动停止录音。您也可以在通话中随时调用 stopAudioRecording 手动停止录音。 + * @since V4.6.0 + * @param filePath 录音文件在本地保存的绝对路径，需要精确到文件名及格式。例如：sdcard/xxx/audio.aac。 + * - 请确保指定的路径存在并且可写。 + * - 目前仅支持 WAV 或 AAC 文件格式。 + * @param sampleRate 录音采样率（Hz），可以设为 16000、32000（默认）、44100 或 48000。 + * @param quality 录音音质，只在 AAC 格式下有效。详细信息请参考 \ref nertc::NERtcAudioRecordingQuality + * "NERtcAudioRecordingQuality" 。 + * @param position 录音对象。详细信息请参考 \ref nertc::NERtcAudioRecordingPosition "NERtcAudioRecordingPosition"。 + * @param cycleTime 循环缓存的最大时长跨度。该参数单位为秒，可以设为 0、10、60、360、900，默认值为 0，即实时写文件。 + * @return + * - 0：方法调用成功。 + * - 其他：方法调用失败。 + * @endif + */ + NERTC_API int NERTC_CALL nertc_engine_start_audio_recording_with_config(struct nertc_engine* self, const struct nertc_audio_recording_configuration* config); + + /** + * @if English + * Stops the audio recording on the client. + *
If the local client leaves the room, audio recording automatically stops. You can call the stopAudioRecording method to + * manually stop recording during calls at any time. + * @note You must call this method before you call leaveChannel. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 停止客户端录音。 + *
本端离开房间时自动停止录音，您也可以在通话中随时调用 stopAudioRecording 手动停止录音。 + * @note 该接口需要在 leaveChannel 之前调用。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_stop_audio_recording(struct nertc_engine* self); + +/** + * @if English + * Adjusts the volume of captured signals. + * @note The method only adjusts the volume of captured signals in the application programs without modifying the volumes of the + * device. If you need to modify the volume of the device, see related interfaces of device management. + * @param[in] volume indicates the volume of the captured recording. Valid values: 0 to 400. Where: + * - 0: Mute. + * - 100: The original volume. + * - 400: The maximum value can be four times the original volume. The limit value is protected. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 调节采集信号音量。 + * @note 该方法仅调节应用程序中的采集信号音量，不修改设备音量。如果需要修改设备音量，请查看设备管理相关接口。 + * @param[in] volume 采集录音音量，取值范围为 [0, 400]。其中： + * - 0: 静音； + * - 100: 原始音量； + * - 400: 最大可为原始音量的 4 倍（自带溢出保护）。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_adjust_recording_signal_volume(struct nertc_engine* self, int volume); + +/** + * @if English + * Adjusts the volume of the audio local playback. + * @note The method only adjusts the volume of captured signals in the application programs without modifying the volumes of the + * device. If you need to modify the volume of the device, see related interfaces of device management. + * @param[in] volume indicates the playback volume. Valid range: 0 to 400. Where: + * - 0: Mute. + * - 100: The original volume. + * - 400: The maximum value can be four times the original volume. The limit value is protected. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 调节本地播放音量。 + * @note 该方法仅调节应用程序中音量，不修改设备音量。如果需要修改设备音量，请查看设备管理相关接口。 + * @param[in] volume 播放音量。取值范围为 [0, 400]。其中： + * - 0: 静音； + * - 100: 原始音量； + * - 400: 最大可为原始音量的 4 倍（自带溢出保护）。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_adjust_playback_signal_volume(struct nertc_engine* self, int volume); + + +/** + * @if English + * Adjusts the volume of local signal playback from a specified remote user. + *
After you join the room, you can call the method to adjust the volume of local audio playback from different remote + users or repeatedly adjust the volume of audio playback from a specified remote user. + * @note + * - You can call this method after joining a room. + * - The method is valid in the current call. If a remote user exits the room and rejoins the room again, the setting is still + valid until the call ends. + * - The method adjusts the volume of the mixing audio published by a specified remote user. The volume of one remote user can + be adjusted. If you want to adjust multiple remote users, you need to call the method for the required times. + * @param uid The ID of a remote user. + * @param volume Playback volume: 0 to 100. + - 0: Mute. + - 100: The original volume. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 调节本地播放的指定远端用户的信号音量。 + *
加入房间后，您可以多次调用该方法设置本地播放的不同远端用户的音量；也可以反复调节本地播放的某个远端用户的音量。 + * @note + * - 请在成功加入房间后调用该方法。 + * - 该方法在本次通话中有效。如果远端用户中途退出房间，则再次加入此房间时仍旧维持该设置，通话结束后设置失效。 + * - + 该方法调节的是本地播放的指定远端用户混音后的音量，且每次只能调整一位远端用户。若需调整多位远端用户在本地播放的音量，则需多次调用该方法。 + * @param uid 远端用户 ID。 + * @param volume 播放音量，取值范围为 [0,100]。 + - 0：静音。 + - 100：原始音量。 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_adjust_user_playback_signal_volume(struct nertc_engine* self, nertc_uid_t uid, int volume); + +/** + * @if Chinese + * 调节本地播放的指定房间的所有远端用户的信号音量。 + *
通过此接口可以实现在通话过程中随时调节指定房间内的所有远端用户在本地播放的混音音量。 + * @since V4.6.50 + * @par 调用时机 + * 请在引擎初始化之后调用此接口，该方法在加入房间前后都可调用。 + * @note + * - 该方法设置内部引擎为启用状态，在 leaveChannel 后失效，但在本次通话过程中有效 + * @par 参数说明 + * + * + * + * + * + * + * + * + * + * + * + *
**参数名称****类型****描述**
volumeuint64_t播放音量，取值范围为 [0,400]。
  • 0：静音。
  • 100：原始音量。
  • 400：最大可为原始音量的 4 + * 倍（自带溢出保护）。
+ * @return + * - 0（kNERtcNoError）：方法调用成功。 + * - 其他：方法调用失败。 + * - 30005（kNERtcErrInvalidState）：状态错误，比如引擎未初始化。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_adjust_channel_playback_signal_volume(struct nertc_engine* self, uint32_t volume); + +/** + * @if English + * Starts to relay media streams across rooms. + * - The method can invite co-hosts across rooms. Media streams from up to four rooms can be relayed. A room can receive + * multiple relayed media streams. + * - After you call this method, the SDK triggers `onMediaRelayStateChange` and `onMediaRelayEvent`. The return reports the + * status and events about the current relayed media streams across rooms. + * @note - You can call this method after joining a room. Before you call the method, you must set the destination room in the + * `NERtcChannelMediaRelayConfiguration` parameter in `dest_infos`. + * - The method is applicable only to the host in live streaming. + * - If you want to call the method again, you must first call the `stopChannelMediaRelay` method to exit the current relaying + * status. + * - If you succeed in relaying the media stream across rooms, and want to change the destination room, for example, add or + * remove the destination room, you can call `updateChannelMediaRelay` to update the information about the destination room. + * @since V4.3.0 + * @param config specifies the configuration for the media stream relay across rooms. For more information, see {@link + * NERtcMediaRelayParam.ChannelMediaRelayConfiguration}。 + * @return {@code 0} A value of 0 returned indicates that the method call is successful. Otherwise, the method call fails. + * @endif + * @if Chinese + * 开始跨房间媒体流转发。 + * - 该方法可用于实现跨房间连麦等场景。支持同时转发到 4 个房间，同一个房间可以有多个转发进来的媒体流。 + * - 成功调用该方法后，SDK 会触发 `onMediaRelayStateChange` 和 `onMediaRelayEvent` + * 回调，并在回调中报告当前的跨房间媒体流转发状态和事件。 + * @note + * - 请在成功加入房间后调用该方法。调用此方法前需要通过 `NERtcChannelMediaRelayConfiguration` 中的 `dest_infos` 设置目标房间。 + * - 该方法仅对直播场景下的主播角色有效。 + * - 成功调用该方法后，若您想再次调用该方法，必须先调用 `stopChannelMediaRelay` 方法退出当前的转发状态。 + * - 成功开始跨房间转发媒体流后，如果您需要修改目标房间，例如添加或删减目标房间等，可以调用方法 `updateChannelMediaRelay` + * 更新目标房间信息。 + * @since V4.3.0 + * @param config 跨房间媒体流转发参数配置信息。 + * @return 成功返回0，其他则失败 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_start_channel_media_relay(struct nertc_engine* self, const struct nertc_channel_media_relay_config* config); + +/** + * @if English + * Updates the information of the destination room for the media stream relay. + *
You can call this method to relay the media stream to multiple rooms or exit the current room. + * - You can call this method to change the destination room, for example, add or remove the destination room. + * - After you call this method, the SDK triggers `onMediaRelayStateChange` and `onMediaRelayEvent`. The return reports the + * status and events about the current relayed media streams across rooms. + * @note Before you call the method, you must join the room and call `startChannelMediaRelay` to relay the media stream across + * rooms. Before you call the method, you must set the destination room in the `NERtcChannelMediaRelayConfiguration` parameter + * in `dest_infos`. + * @since V4.3.0 + * @param config The configuration for destination rooms. + * @return A value of 0 returned indicates that the method call is successful. Otherwise, the method call fails. + * @endif + * @if Chinese + * 更新媒体流转发的目标房间。 + *
成功开始跨房间转发媒体流后，如果你希望将流转发到多个目标房间，或退出当前的转发房间，可以调用该方法。 + * - 成功开始跨房间转发媒体流后，如果您需要修改目标房间，例如添加或删减目标房间等，可以调用此方法。 + * - 成功调用该方法后，SDK 会触发 `onMediaRelayStateChange` 和 `onMediaRelayEvent` + * 回调，并在回调中报告当前的跨房间媒体流转发状态和事件。 + * @note 请在加入房间并成功调用 `startChannelMediaRelay` 开始跨房间媒体流转发后，调用此方法。调用此方法前需要通过 + * `NERtcChannelMediaRelayConfiguration` 中的 `dest_infos` 设置目标房间。 + * @since V4.3.0 + * @param config 目标房间配置信息 + * @return 成功返回0，其他则失败 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_update_channel_media_relay(struct nertc_engine* self, const struct nertc_channel_media_relay_config* config); + +/** + * @if English + * Stops relaying media streams. + *
If the host leaves the room, media stream replay across rooms automatically stops. You can also call + * stopChannelMediaRelay. In this case, the host exits all destination rooms. + * - If you call this method, the SDK triggers the `onMediaRelayStateChange` callback. If `NERtcChannelMediaRelayStateIdle` is + * returned, the media stream relay stops. + * - If the method call failed, the SDK triggers the `onMediaRelayStateChange` callback that returns the status code + * `NERtcChannelMediaRelayStateFailure`. + * @since V4.3.0 + * @return A value of 0 returned indicates that the method call is successful. Otherwise, the method call fails. + * @endif + * @if Chinese + * 停止跨房间媒体流转发。 + *
主播离开房间时，跨房间媒体流转发自动停止，您也可以在需要的时候随时调用 `stopChannelMediaRelay` + * 方法，此时主播会退出所有目标房间。 + * - 成功调用该方法后，SDK 会触发 `onMediaRelayStateChange` 回调。如果报告 + * `NERtcChannelMediaRelayStateIdle`，则表示已停止转发媒体流。 + * - 如果该方法调用不成功，SDK 会触发 `onMediaRelayStateChange` 回调，并报告状态码 `NERtcChannelMediaRelayStateFailure`。 + * @since V4.3.0 + * @return 成功返回0，其他则失败 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_stop_channel_media_relay(struct nertc_engine* self); + +/** + * @if English + * Sets the fallback option for the published local video stream based on the network conditions. + *
The quality of the published local audio and video streams is degraded with poor quality network connections. After + * calling this method and setting the option to #kNERtcStreamFallbackAudioOnly: + * - With unreliable upstream network connections and the quality of audio and video streams is downgraded, the SDK + * automatically disables video stream or stops receiving video streams. In this way, the communication quality is guaranteed. + * - The SDK monitors the network performance and recover audio and video streams if the network quality improves. + * - If the locally published audio and video stream falls back to audio stream, or recovers to audio and video stream, the + * SDK triggers the onLocalPublishFallbackToAudioOnly callback. + * @note You must call the method before you call joinChannel. + * @since V4.3.0 + * @param option The fallback option of publishing audio and video streams. The fallback kNERtcStreamFallbackAudioOnly is + * disabled by default. For more information, see nertc::NERTCStreamFallbackOption . + * @return {@code 0} A value of 0 returned indicates that the method call is successful. Otherwise, the method call fails. + * @endif + * @if Chinese + * 设置弱网条件下发布的音视频流回退选项。 + *
在网络不理想的环境下，发布的音视频质量都会下降。使用该接口并将 option 设置为 #kNERtcStreamFallbackAudioOnly 后： + * - SDK 会在上行弱网且音视频质量严重受影响时，自动关断视频流，尽量保证音频质量。 + * - 同时 SDK 会持续监控网络质量，并在网络质量改善时恢复音视频流。 + * - 当本地发布的音视频流回退为音频流时，或由音频流恢复为音视频流时，SDK 会触发本地发布的媒体流已回退为音频流 + * onLocalPublishFallbackToAudioOnly 回调。 + * @note 请在加入房间（joinChannel）前调用此方法。 + * @since V4.3.0 + * @param option 发布音视频流的回退选项，默认为不开启回退 kNERtcStreamFallbackAudioOnly。详细信息请参考 + * nertc::NERTCStreamFallbackOption 。 + * @return {@code 0} 方法调用成功，其他调用失败 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_local_publish_fallback_option(struct nertc_engine* self, nertc_stream_fallback_option option); + +/** + * @if English + * Sets the fallback option for the subscribed remote audio and video stream with poor network connections. + *
The quality of the subscribed audio and video streams is degraded with unreliable network connections. You can use the + * interface to set the option as #kNERtcStreamFallbackVideoStreamLow or #kNERtcStreamFallbackAudioOnly. + * - In unreliable downstream network connections, the SDK switches to receive a low-quality video stream or stops receiving + * video streams. In this way, the communication quality is maintained or improved. + * - The SDK monitors the network quality and resumes the video stream when the network condition improves. + * - If the subscribed remote video stream falls back to audio only, or the audio-only stream switches back to the video + * stream, the SDK triggers the onRemoteSubscribeFallbackToAudioOnly callback. + * @note You must call the method before you call joinChannel. + * @since V4.3.0 + * @param option The fallback option for the subscribed remote audio and video stream. With unreliable network connections, + * the stream falls back to a low-quality video stream of kNERtcStreamFallbackVideoStreamLow. For more information, see + * nertc::NERTCStreamFallbackOption . + * @return {@code 0} A value of 0 returned indicates that the method call is successful. Otherwise, the method call fails. + * @endif + * @if Chinese + * 设置弱网条件下订阅的音视频流回退选项。 + *
弱网环境下，订阅的音视频质量会下降。使用该接口并将 option 设置为 #kNERtcStreamFallbackVideoStreamLow 或者 + * #kNERtcStreamFallbackAudioOnly 后： + * - SDK 会在下行弱网且音视频质量严重受影响时，将视频流切换为小流，或关断视频流，从而保证或提高通信质量。 + * - SDK 会持续监控网络质量，并在网络质量改善时自动恢复音视频流。 + * - 当远端订阅流回退为音频流时，或由音频流恢复为音视频流时，SDK 会触发远端订阅流已回退为音频流 + * onRemoteSubscribeFallbackToAudioOnly 回调。 + * @note 请在加入房间（joinChannel）前调用此方法。 + * @since V4.3.0 + * @param option 订阅音视频流的回退选项，默认为弱网时回退到视频小流 kNERtcStreamFallbackVideoStreamLow。详细信息请参考 + * nertc::NERTCStreamFallbackOption 。 + * @return {@code 0} 方法调用成功，其他调用失败 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_remote_subscribe_fallback_option(struct nertc_engine* self, nertc_stream_fallback_option option); + +/** + * @if English + * Enables or disables AI super resolution. + * @since V4.4.0 + * @note + * - Please contact our technical support to enable AI super resolution before you perform the feature. + * - AI super resolution is only valid when you enable the following types of video streams: + * - Video streams that are received from local 360P. + * - High stream video of mainstream that are captured by the camera. AI super resolution is currently unsupported to resume + * low streams or substreams of screen sharing. + * @param enable Whether to enable AI super resolution. By default, the setting is disabled. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 启用或停止 AI 超分。 + * @since V4.4.0 + * @note + * - 使用 AI 超分功能之前，请联系技术支持开通 AI 超分功能。 + * - AI 超分仅对以下类型的视频流有效： + * - 必须为本端接收到第一路 360P 的视频流。 + * - 必须为摄像头采集到的主流大流视频。AI 超分功能暂不支持复原重建小流和屏幕共享辅流。 + * @param enable 是否启用 AI 超分。默认为关闭状态。 + * @return + * - 0: 方法调用成功 + * - 其他: 调用失败 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_enable_super_resolution(struct nertc_engine* self, bool enable); + +/** + * @if English + * Enables or disables media stream encryption. + * @since V4.4.0 + * In scenes where high safety is required such as financial sectors, you can set encryption modes of media streams with the + * method before joining the room. + * @note + * - Please calls the method before you join the room. The encryption mode and private key cannot be changed after you join + * the room. The SDK will automatically disable encryption after users leave the room. If you need to enable encryption again, + * users need to call the method before joining the room. + * - In the same room, all users who enable media stream encryption must share the same encryption mode and private keys. If + * not, members who use different private keys will report kNERtcErrEncryptNotSuitable (30113). + * - For safety, we recommend that you use a new private key every time you enable media stream encryption. + * @param enable whether to enable media stream encryption. + * - true: Enabled. + * - false: Disabled. This is the default value. + * @param config specifies encryption plan for media streams. For more information, see nertc::NERtcEncryptionConfig. + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 开启或关闭媒体流加密。 + * @since V4.4.0 + * 在金融行业等安全性要求较高的场景下，您可以在加入房间前通过此方法设置媒体流加密模式。 + * @note + * - 请在加入房间前调用该方法，加入房间后无法修改加密模式与密钥。用户离开房间后，SDK + * 会自动关闭加密。如需重新开启加密，需要在用户再次加入房间前调用此方法。 + * - 同一房间内，所有开启媒体流加密的用户必须使用相同的加密模式和密钥，否则使用不同密钥的成员加入房间时会报错 + * kNERtcErrEncryptNotSuitable（30113）。 + * - 安全起见，建议每次启用媒体流加密时都更换新的密钥。 + * @param enable 是否开启媒体流加密。 + * - true: 开启 + * - false:（默认）关闭 + * @param config 媒体流加密方案。详细信息请参考 nertc::NERtcEncryptionConfig 。 + * @return + * - 0: 方法调用成功 + * - 其他: 调用失败 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_enable_encryption(struct nertc_engine* self, bool enable, struct nertc_encryption_config* config); + +/** + * @if English + * Starts the last-mile network probe test. + *
This method starts the last-mile network probe test before joining a channel to get the uplink and downlink last mile + * network statistics, including the bandwidth, packet loss, jitter, and round-trip time (RTT).This method is used to detect + * network quality before a call. Before a user joins a room, you can use this method to estimate the subjective experience + * and objective network status of a local user during an audio and video call. Once this method is enabled, the SDK returns + * the following callbacks: + * - `onLastmileQuality`: the SDK triggers this callback within five seconds depending on the network conditions. This + * callback rates the network conditions with a score and is more closely linked to the user experience. + * - `onLastmileProbeResult`: the SDK triggers this callback within 30 seconds depending on the network conditions. This + * callback returns the real-time statistics of the network conditions and is more objective. + * @note + * - You can call this method before joining a channel(joinChannel). + * - Do not call other methods before receiving the onLastmileQuality and onLastmileProbeResult callbacks. Otherwise, the + * callbacks may be interrupted. + * @since V4.5.0 + * @param config Sets the configurations of the last-mile network probe test. + * @endif + * @if Chinese + * 开始通话前网络质量探测。 + *
启用该方法后，SDK + * 会通过回调方式反馈上下行网络的质量状态与质量探测报告，包括带宽、丢包率、网络抖动和往返时延等数据。一般用于通话前的网络质量探测场景，用户加入房间之前可以通过该方法预估音视频通话中本地用户的主观体验和客观网络状态。 + *
相关回调如下： + * - `onLastmileQuality`：网络质量状态回调，以打分形式描述上下行网络质量的主观体验。该回调视网络情况在约 5 秒内返回。 + * - `onLastmileProbeResult`：网络质量探测报告回调，报告中通过客观数据反馈上下行网络质量。该回调视网络情况在约 30 秒内返回。 + * @note + * - 请在加入房间（joinChannel）前调用此方法。 + * - 调用该方法后，在收到 `onLastmileQuality` 和 `onLastmileProbeResult` 回调之前请不要调用其他方法，否则可能会由于 API + * 操作过于频繁导致此方法无法执行。 + * @since V4.5.0 + * @param config Last mile 网络探测配置。 + * @return + * - 0: 方法调用成功 + * - 其他: 调用失败 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_start_lastmile_probe_test(struct nertc_engine* self, const struct nertc_lastmile_probe_config* config); + +/** + * @if English + * Stops the last-mile network probe test. + * @since V4.5.0 + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 停止通话前网络质量探测。 + * @since V4.5.0 + * @return + * - 0: 方法调用成功 + * - 其他: 调用失败 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_stop_lastmile_probe_test(struct nertc_engine* self); + +/** + * @if English + * Sets a remote audio stream to high priority + * Sets a remote audio streams to high priority during automatic stream subscription. Users can hear the audio stream with high priority. + * @note + * - The priority of a remote audio stream must be set during a call and automatic stream subscription must be enabled (by default) + * - Only one audio stream can be set to high priority. The subsequent call will override the previous setting. + * - The priority of the audio stream will be reset after the call ends + * @param[in] enabled sets or cancels high priority to a remote audio stream. + * - true: sets high priority to a remote audio stream. + * - false: cancels high priority of a remote audio stream. + * @param[in] uid User ID + * @return + * - 0: success； + * - Other values: failure + * @endif + * @if Chinese + * 设置远端用户音频流为高优先级。 + * 支持在音频自动订阅的情况下，设置某一个远端用户的音频为最高优先级，可以优先听到该用户的音频。 + * @note + * - 该接口需要通话中设置，并需要自动订阅打开（默认打开）。 + * - 该接口只能设置一个用户的优先级，后设置的会覆盖之前的设置。 + * - 该接口通话结束后，优先级设置重置。 + * @param[in] enabled 是否设置音频订阅优先级。 + * - true：设置音频订阅优先级。 + * - false：取消设置音频订阅优先级。 + * @param[in] uid 用户 ID + * @return + * - 0: 方法调用成功。 + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_remote_high_priority_audio_stream(struct nertc_engine* self, bool enabled, nertc_uid_t uid); + +/** + * @if English + * Check audio driver plug-in insall success or not (only for Mac system) + * This method will detect whether the computer has the latest version of the virtual sound card installed. If it is not installed, and the NERTCPrivilegedTask library has been integrated in the application, the interface will pop up the virtual sound card installation dialog box, which is convenient for users to install. + * @since V4.6.0 + * @return + * - 0: The computer does not have a NetEase virtual sound card installed or the virtual sound card is not the latest version + * - 1: The computer has installed the latest version of NetEase virtual sound card + * @endif + * @if Chinese + * 检测虚拟声卡是否安装（仅适用于 Mac 系统）。 + * 该接口会检测电脑是否安装最新版本的虚拟声卡。如果未安装，并且应用中已集成NERTCPrivilegedTask库，该接口会弹出安装虚拟声卡对话框，方便用户安装。 + * @since V4.6.0 + * @return + * - 0: 电脑未安装网易虚拟声卡或虚拟声卡不是最新版本 + * - 1: 电脑已安装最新版本的网易虚拟声卡 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_check_necast_audio_driver(struct nertc_engine* self); +/** + * @if English + * Check if video correction is enabled + * @since V4.6.0 + * @note + * - If you use a camera to shoot an object, a mapping process from 3D to 2D images is implemented. the image of an object is + * deformed when the position of the camera changes. + * - If you enable video correction with appropriate parameters, video images can be restored by algorithms. + * - To use video correction, the rendering mode of the local canvas must be set to fit. Video frames keeps aspect ratio + * unchanged and are all displayed in the current view. Otherwise, video correction may not take effect. + * - If the parameters of video correction are applied, the local and remote video frames are all corrected + * @param enable Enables or disables local video correction. + * - true：enabled + * - false (default): disabled + * @return + * - 0: success. + * - Others: failure + * @endif + * @if Chinese + * 是否启用视频图像畸变矫正。 + * @since V4.6.0 + * @note + * - + * 当使用相机去拍摄物体时，存在着一个从三维世界到二维图像的映射过程，这个过程中由于相机位置的变化和移动，会对拍摄物体的成像产生一定的形变影响。 + * - 开启该功能时，根据合适的参数，可以通过算法把这个形变进行复原。 + * - 使用该功能时，本地画布的渲染模式需要为 fit（即视频帧保持自身比例不变全部显示在当前视图中），否则矫正功能可能不会正常生效。 + * - 矫正参数生效后，本地画面和对端看到的画面，均会是矫正以后的画面。 + * @param enable 是否开启视频图像矫正。 + * - true：开启视频图像矫正。 + * - false（默认）：关闭视频图像矫正。 + * @return + * - 0：方法调用成功。 + * - 其他：方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_enable_video_correction(struct nertc_engine* self, bool enable); + +/** + * @if English + * Sets the parameters for video correction. + * @since V4.6.0 + * @note + * - The first 4 parameters of the config schema represent coordinates of areas to be corrected on the screen. The x and y + * coordinates of each point ranges from 0 to 1. + * - The last 3 parameters are required only if external video rendering is used. + * - You can pass nill in config. If config is set to nil, the SDK clears previous configurations for video correction. The + * video graph will be restored to the state without correction. + * @param config Correction parameters. For more information, see {@link NERtcVideoCorrectionConfiguration}. + * @return + * - 0: success. + * - Others: failure + * @endif + * @if Chinese + * 设置视频图像矫正参数。 + * @since V4.6.0 + * @note + * - 矫正参数结构体的前 4 个参数，代表了待矫正区域相对于屏幕上视图的坐标，每个坐标点的 x 和 y 的取值范围均为 0 ~ 1 的浮点数。 + * - 矫正参数结构体的后 3 个参数只有在使用了外部视频渲染功能时才需要传入。 + * - config 可以传入 nil，清空之前设置过的矫正参数，将画面恢复至矫正之前的效果。 + * @param config 视频图像矫正相关参数。详细说明请参考 {@link NERtcVideoCorrectionConfiguration}。 + * @return + * - 0：方法调用成功。 + * - 其他：方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_video_correction_config(struct nertc_engine* self, struct nertc_video_correction_configuration* config); + +/** + * @if English + * Enables/Disables the virtual background. + * + * After enabling the virtual background feature, you can replace the original background image of the local user + * with a custom background image. After the replacement, all users in the channel can see the custom background + * image. You can find out from the + * RtcEngineEventHandlerEx::onVirtualBackgroundSourceEnabled "onVirtualBackgroundSourceEnabled" callback + * whether the virtual background is successfully enabled or the cause of any errors. + * - macOS and Windows: Devices with an i5 CPU and better + * - Recommends that you use this function in scenarios that meet the following conditions: + * - A high-definition camera device is used, and the environment is uniformly lit. + * - The captured video image is uncluttered, the user's portrait is half-length and largely unobstructed, and the + * background is a single color that differs from the color of the user's clothing. + * - The virtual background feature does not support video in the Texture format or video obtained from custom video capture by the Push method. + * @since V4.6.0 + * @param enabled Sets whether to enable the virtual background: + * - true: Enable. + * - false: Disable. + * @param backgroundSource The custom background image. See VirtualBackgroundSource. + * Note: To adapt the resolution of the custom background image to the resolution of the SDK capturing video, + * the SDK scales and crops + * the custom background image while ensuring that the content of the custom background image is not distorted. + * @return + * - 0: Success. + * - < 0: Failure. + * @endif + * @if Chinese + * 启用/禁用虚拟背景。 + * 启用虚拟背景功能后，您可以使用自定义背景图片替换本地用户的原始背景图片。 + * 替换后，频道内所有用户都可以看到自定义背景图片。 + * @since V4.6.0 + * @note + * - 您可以通过 \ref nertc::IRtcEngineEventHandlerEx::onVirtualBackgroundSourceEnabled "onVirtualBackgroundSourceEnabled" 回调查看虚拟背景是否开启成功或出错原因。 + * - 建议您使用配备 i5 CPU 及更高性能的设备。 + * - 建议您在满足以下条件的场景中使用该功能： + * - 采用高清摄像设备，环境光线均匀。 + * - 捕获的视频图像整洁，用户肖像半长且基本无遮挡，并且背景是与用户衣服颜色不同的单一颜色。 + * - 虚拟背景功能不支持 Texture 格式的视频或通过 Push 方法从自定义视频捕获中获取的视频。 + * @param background_source 自定义背景图片。请参阅 {@link VirtualBackgroundSource}。 + * @return + * - 0：方法调用成功。 + * - < 0: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_enable_virtual_background(struct nertc_engine* self, bool enabled, struct nertc_virtual_background_source* background_source); + +/** + * @if English + * Sets the Agora cloud proxy service. + *
When the user's firewall restricts the IP address and port, refer to Use Cloud Proxy to add the specific IP addresses and ports to the firewall whitelist; then, call this method to enable the cloud proxy and set the proxyType parameter as NERtcTransportTypeUDPProxy(1), which is the cloud proxy for the UDP protocol. + * - After a successfully cloud proxy connection, the SDK triggers the `onNERtcEngineConnectionStateChangeWithState(kNERtcConnectionStateConnecting, kNERtcReasonConnectionChangedSettingProxyServer)` callback. + * - To disable the cloud proxy that has been set, call setCloudProxy(NERtcTransportTypeNoneProxy). + * @note We recommend that you call this method before joining the channel or after leaving the channel. + * @param proxyType The cloud proxy type. For more information, see {@link NERtcTransportType}. This parameter is required, and the SDK reports an error if you do not pass in a value. + * @return A value of 0 returned indicates that the method call is successful. Otherwise, the method call fails. + * @endif + * @if Chinese + * 开启并设置云代理服务。 + *
在内网环境下，如果用户防火墙开启了网络限制，请参考《使用云代理》将指定 IP 地址和端口号加入防火墙白名单，然后调用此方法开启云代理，并将 proxyType 参数设置为 NERtcTransportTypeUDPProxy(1)，即指定使用 UDP 协议的云代理。 + * - 成功连接云代理后，SDK 会触发 `onNERtcEngineConnectionStateChangeWithState(kNERtcConnectionStateConnecting, kNERtcReasonConnectionChangedSettingProxyServer)` 回调。 + * - 如果需要关闭已设置的云代理，请调用 `setCloudProxy(NERtcTransportTypeNoneProxy)`。 + * @note 请在加入房间前调用此方法。 + * @param proxyType 云代理类型。详细信息请参考 {@link NERtcTransportType}。该参数为必填参数，若未赋值，SDK 会报错。 + * @return {@code 0} 方法调用成功，其他失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_cloud_proxy(struct nertc_engine* self, nertc_transport_type proxy_type); + +/** + * @if English + * Enables or disables local data channel. + * @note + * - You can call this method after you join a room. + * - After local data channel successfully enabled or disabled, the onUserDataStop or onUserDataStart + * @param[in] enabled Whether to enable local data channel. + * - true: Enables local data channel. + * - false: Disables local data channel + * @since V5.0.0 + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 开启或关闭本地数据通道。 + * @note + * - 该方法加入房间后才可调用。 + * - 成功启用或禁用本地数据通道后，远端会触发 onUserDataStop 或 onUserDataStart 回调。 + * @param[in] enabled 是否启用本地数据通道: + * - true: 开启本地数据通道； + * - false: 关闭本地数据通道。 + * @since V5.0.0 + * @return + * - 0: 方法调用成功； + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_enable_local_data(struct nertc_engine* self, bool enabled); + +/** + * @if English + * Unsubscribes from or subscribes to data channel from specified remote users. + *
After a user joins a channel, data channel streams from all remote users are subscribed by default. You can call this method to unsubscribe from or subscribe to data channel streams from all remote users. + * @note When the kNERtcKeyAutoSubscribeData is enabled by default, users cannot manually modify the state of data channel subscription. + * @param[in] uid The user ID. + * @param[in] subscribe + * - true: Subscribes to specified data channel streams (default). + * - false: Unsubscribes from specified data channel streams. + * @since V5.0.0 + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 取消或恢复订阅指定远端用户数据通道流。 + *
加入房间时，默认订阅所有远端用户的数据通道流，您可以通过此方法取消或恢复订阅指定远端用户的数据通道流。 + * @note 当kNERtcKeyAutoSubscribeData默认打开时，用户不能手动修改数据通道订阅状态 + * @param[in] uid 指定用户的 ID。 + * @param[in] subscribe 是否订阅远端用户数据通道流。 + * - true: 订阅指定数据通道流（默认）。 + * - false: 取消订阅指定数据通道流。 + * @since V5.0.0 + * @return + * - 0: 方法调用成功。 + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_subscribe_remote_data(struct nertc_engine* self, nertc_uid_t uid, bool subscribe); + +/** + * @if English + * Send data by data channel. + * @param[in] pData The custom data channel frame data.。 + * @param[in] size The custom data channel data size whose maximum value does not exceed 128k bytes. + * @since V5.0.0 + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 通过数据通道发送数据。 + * @param[in] data 自定义数据。 + * @param[in] size 自定义数据长度, 最大不超过128k。 + * @since V5.0.0 + * @return + * - 0: 方法调用成功。 + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_send_data(struct nertc_engine* self, void* data, uint64_t size); + +/** + * @if English + * Enables the beauty module. + * - The API starts the beauty engine. If beauty is not needed, you can call `stopBeauty` to end the beauty module, destroy the beauty engine and release resources. + * - When the beauty module is enabled, no beauty effect is applied by default. You must set beauty effects or filters by calling `setBeautyEffect` or other filters and stickers methods. + * @note + * - The method must be called before `enableLocalVideo`. + * - The method is only supported on Windows + * @since V4.2.202 + * @param file_path the absolute path of a file. For example, xxx\data\beauty\nebeauty in the Windows operating system.. + * @return + * - 0: success. + * - 30001 (kNERtcErrFatal): failure. + * - 30004 (kNERtcErrNotSupported): beauty is not supported. + * @endif + * @if Chinese + * 开启美颜功能模块。 + * - 调用此接口后，开启美颜引擎。如果后续不再需要使用美颜功能，可以调用 `stopBeauty` 结束美颜功能模块，销毁美颜引擎并释放资源。 + * - 开启美颜功能模块后，默认无美颜效果，您需要通过 `setBeautyEffect` 或其他滤镜、贴纸相关接口设置美颜或滤镜效果。 + * @note + * - 该方法需要在 `enableLocalVideo` 之前设置。 + * - 该方法仅适用于 Windows 平台。 + * @since V4.2.202 + * @param file_path 文件文件绝对路径。（例：windows环境下传入xxx\data\beauty\nebeauty） + * @return + * - 0: 方法调用成功。 + * - 30001（kNERtcErrFatal）：方法调用失败。 + * - 30004（kNERtcErrNotSupported）：不支持美颜功能。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_start_beauty(struct nertc_engine* self, const char* file_path); + +/** + * @if English + * Stops the beauty module. + * @note The method is only supported on Windows + *
If the beauty module is not needed, you can call `stopBeauty` to stop the module. The SDK will automatically destroy the beauty engine and release the resources. + * @since V4.2.202 + * @return + * - 0: success + * - Others: failure + * @endif + * @if Chinese + * 结束美颜功能模块。 + *
如果后续不再需要使用美颜功能，可以调用 `stopBeauty` 结束美颜功能模块，SDK 会自动销毁美颜引擎并释放资源。 + * @note 该方法仅适用于 Windows 平台。 + * @since V4.2.202 + * @return + * - 0：方法调用成功。 + * - 其他：方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_stop_beauty(struct nertc_engine* self); + +/** +* @if English +* Pauses or resumes the beauty effect +*
The beauty effect is paused, including the global beauty effect, filters, stickers, and makeups, until the effect is resumed. +* @note +* - The method is only supported on Windows. +* - Beauty effect is enabled by default. If you want to temporarily disable the beauty effect, call this method after invoking {@link NERtcEx#startBeauty()}. +* @since V4.2.202 +* @param enabled specifies whether to resume the beauty effect. +* - true (default): resumes the beauty effect. +* - false: pauses the beauty effect. +* @return +* - 0: success +* - Others: failure +* @endif +* @if Chinese +* 暂停或恢复美颜效果。 +*
暂停美颜效果后，包括全局美颜、滤镜、贴纸和美妆在内的所有美颜效果都会暂时关闭，直至重新恢复美颜效果。 +* @note +* - 该方法仅适用于 Windows 平台。 +* - 美颜效果默认开启。若您需要临时关闭美颜功能，需要在 `startBeauty` 之后调用该方法。 +* @since V4.2.202 +* @param enabled 是否恢复美颜效果。 +* - true：恢复美颜效果。 +* - false：暂停美颜效果。 +* @return +* - 0：方法调用成功。 +* - 其他：方法调用失败。 +* @endif +*/ +NERTC_API int NERTC_CALL nertc_engine_enable_beauty(struct nertc_engine* self, bool enabled); + +/** + * @if English + * This method is deprecated. + * @endif + * @if Chinese + * 启用美颜时，启用或关闭镜像模式。 + * + * - 美颜功能启用时，此接口用于开启或关闭镜像模式。默认为关闭状态。美颜功能暂停或结束后，此接口不再生效。 + * - 启用镜像模式之后，本端画面会呈现为左右翻转的视觉效果。 + * - 该方法已废弃。 + * + * @since V4.2.202 + * @param enabled 美颜时是否启用镜像模式。默认为 `true`，表示美颜时启用镜像模式。`false` 表示美颜时取消镜像模式。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_enable_beauty_mirror_mode(struct nertc_engine* self, bool enabled); + +/** + * @if English + * Gets the intensity setting of a specified beauty type. + *
The method is used to get the intensity setting of a specified beauty type after you set a beauty effect with intensity using `setBeautyEffect`. + * @note The method is only supported on Windows. + * @since V4.2.202 + * @param type Beauty type. + * @return + * - 0: success + * - Others: failure + * @endif + * @if Chinese + * 获取指定美颜类型的强度设置。 + *
通过接口 `setBeautyEffect` 设置美颜效果及强度后，可以通过此接口查看指定美颜效果的强度设置。 + * @note 该方法仅适用于 Windows 平台。 + * @since V4.2.202 + * @param type 美颜类型。 + * @return + * - 0：方法调用成功。 + * - 其他：方法调用失败。 + * @endif + */ +NERTC_API float NERTC_CALL nertc_engine_get_beauty_effect(struct nertc_engine* self, nertc_beauty_effect_type type); + +/** + * @if English + * Sets the beauty type and intensity. + * - The method can set various types of beauty effects, such as smoothing, whitening, and big eyes. + * - Multiple method calls can apply multiple global effects. Filters, stickers, and makeups can be added in the same way. + * @note The method is only supported on Windows. + * @since V4.2.202 + * @param type Beauty type. For more information, see {@link NERtcBeautyEffectType}. + * @param value Beauty intensity. Value range: [0, 1]. The default values of effects are different. + * @return + * - 0: success + * - Others: failure + * @endif + * @if Chinese + * 设置指定美颜类型的强度。 + * - 此方法可用于设置磨皮、美白、大眼等多种全局美颜类型。 + * - 多次调用此接口可以叠加多种全局美颜效果，也可以通过相关方法叠加滤镜、贴纸、美妆等自定义效果。 + * @note 该方法仅适用于 Windows 平台。 + * @since V4.2.202 + * @param type 美颜类型。详细信息请参考 {@link NERtcBeautyEffectType}。 + * @param level 对应美颜类型的强度。取值范围为 [0, 1]，各种美颜效果的默认值不同。 + * @return + * - 0: 方法调用成功。 + * - 其他: 方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_beauty_effect(struct nertc_engine* self, nertc_beauty_effect_type type, float level); + +/** +* @if English +* Add filters. +*
The API is used to load filter assets and add related filter effects. To change a filter, call this method for a new filter. +* @note +* - The method is only supported on Windows. +* - Before applying filters, stickers, and makeups, you must prepare beauty assets or models. +* - A filter effect can be applied together with global beauty effects, stickers, and makeups. However, multiple filters cannot be applied at the same time. +* @since V4.2.202 +* @param file_path The path of the filter assets or models. +* @return +* - 0: success +* - Others: failure +* @endif +* @if Chinese +* 添加滤镜效果。 +*
此接口用于加载滤镜资源，并添加对应的滤镜效果。需要更换滤镜时，重复调用此接口使用新的滤镜资源即可。 +* @note +* - 该方法仅适用于 Windows 平台。 +* - 使用滤镜、贴纸和美妆等自定义美颜效果之前，需要先准备好对应的美颜资源或模型。 +* - 滤镜效果可以和全局美颜、贴纸、美妆等效果互相叠加，但是不支持叠加多个滤镜。 +* @since V4.2.202 +* @param file_path 滤镜资源或模型所在的绝对路径。 +* @return +* - 0：方法调用成功。 +* - 其他：方法调用失败。 +* @endif +*/ +NERTC_API int NERTC_CALL nertc_engine_add_beauty_filter(struct nertc_engine* self, const char* file_path); + +/** +* @if English +* Removes a filter effect. +* @note The method is only supported on Windows. +* @since V4.2.202 +* @return +* - 0: success +* - Others: failure +* @endif +* @if Chinese +* 取消滤镜效果。 +* @note 该方法仅适用于 Windows 平台。 +* @since V4.2.202 +* @return +* - 0：方法调用成功。 +* - 其他：方法调用失败。 +* @endif +*/ +NERTC_API int NERTC_CALL nertc_engine_remove_beauty_filter(struct nertc_engine* self); + +/** + * @if English + * Sets the filter intensity + * A larger value indicates more intensity. You can adjust a custom value based on business requirements. + * @note + * - The method is only supported on Windows + * - The setting takes effect when it is applied. The intensity remains if a filter is changes. You can adjust the intensity by setting this property. + * @since V4.2.202 + * @param level Filter intensity. Value range: 0 - 1. Default value: 0.5. + * @return + * - 0: success + * - Others: failure + * @endif + * @if Chinese + * 设置滤镜强度。 + * 取值越大，滤镜强度越大，开发者可以根据业务需求自定义设置滤镜强度。 + * @note + * - 该方法仅适用于 Windows 平台。 + * - 滤镜强度设置实时生效，更换滤镜后需要重新设置滤镜强度，否则强度取默认值。 + * @since V4.2.202 + * @param level 滤镜强度。取值范围为 [0 - 1]，默认值为 0.5。 + * @return + * - 0：方法调用成功。 + * - 其他：方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_beauty_filter_level(struct nertc_engine* self, float level); + +/** +* @if English +* Adds a sticker (beta). +*
The API is used to load sticker assets and add related sticker effects. To change a sticker, call this method for a new sticker. +* @note +* - The method is only supported on Windows +* - Before applying filters, stickers, and makeups, you must prepare beauty assets or models. +* - A sticker effect can be applied together with global beauty effects, stickers, and makeups. However, multiple stickers cannot be applied at the same time. +* @since V4.2.202 +* @param file_path The path of the sticker assets or models. +* @return +* - 0: success +* - Others: failure +* @endif +* @if Chinese +* （此接口为 beta 版本）添加贴纸效果。 +*
此接口用于加载贴纸资源，添加对应的贴纸效果。需要更换贴纸时，重复调用此接口使用新的贴纸资源即可。 +* @note +* - 该方法仅适用于 Windows 平台。 +* - 使用滤镜、贴纸和美妆等自定义美颜效果之前，需要先准备好对应的美颜资源或模型。 +* - 贴纸效果可以和全局美颜、滤镜、美妆等效果互相叠加，但是不支持叠加多个贴纸。 +* @since V4.2.202 +* @param file_path 贴纸资源或模型所在的绝对路径。 +* @return +* - 0：方法调用成功。 +* - 其他：方法调用失败。 +* @endif +*/ +NERTC_API int NERTC_CALL nertc_engine_add_beauty_sticker(struct nertc_engine* self, const char* file_path); + +/** +* @if English +* Removes a sticker (beta). +* @note The method is only supported on Windows +* @since V4.2.202 +* @return +* - 0: success +* - Others: failure +* @endif +* @if Chinese +* （此接口为 beta 版本）取消贴纸效果。 +* @note 该方法仅适用于 Windows 平台。 +* @since V4.2.202 +* @return +* - 0：方法调用成功。 +* - 其他：方法调用失败。 +* @endif +*/ +NERTC_API int NERTC_CALL nertc_engine_remove_beauty_sticker(struct nertc_engine* self); + +/** + * @if English + * Adds a makeup effect (beta). + *
The API is used to load makeup assets and add related sticker effects. To change a makeup effect, call this method for a new makeup effect. + * @note + * - The method is only supported on Windows + * - Before applying filters, stickers, and makeups, you must prepare beauty assets or models. + * - A makeup effect can be applied together with global beauty effects, stickers, and makeups. However, multiple makeup effects cannot be applied at the same time. + * @since V4.2.202 + * @param path The path of the makeup assets or models. + * @return + * - 0: success + * - Others: failure + * @endif + * @if Chinese + * （此接口为 beta 版本）添加美妆效果。 + * 此接口用于加载美妆模型，添加对应的美妆效果。需要更换美妆效果时，重复调用此接口使用新的美妆模型即可。 + * @note + * - 该方法仅适用于 Windows 平台。 + * - 使用滤镜、贴纸和美妆等自定义美颜效果之前，需要先准备好对应的美颜资源或模型。 + * - 美妆效果可以和全局美颜、滤镜、贴纸等效果互相叠加，但是不支持叠加多个美妆效果。 + * @since V4.2.202 + * @param file_path 美妆模型所在的绝对路径。 + * @return + * - 0：方法调用成功。 + * - 其他：方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_add_beauty_makeup(struct nertc_engine* self, const char* file_path); + +/** + * @if English + * Removes a makeup effect (beta). + * @note The method is only supported on Windows + * @since V4.2.202 + * @return + * - 0: success + * - Others: failure + * @endif + * @if Chinese + * （此接口为 beta 版本）取消美妆效果。 + * @note 该方法仅适用于 Windows 平台。 + * @since V4.2.202 + * @return + * - 0：方法调用成功。 + * - 其他：方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_remove_beauty_makeup(struct nertc_engine* self); + +/** + * @if English + * Sets the reverb effect for the local audio stream. + * @note The method can be called before or after a user joins a room. The setting will be reset to the default value after a call ends. + * @since V4.6.10 + * @param param For more information, see {@link NERtcReverbParam}. + * @return + * - 0: success + * - Others: failure + * @endif + * @if Chinese + * 设置本地语音混响效果。 + * @note 该方法在加入房间前后都能调用，通话结束后重置为默认的关闭状态。 + * @since V4.6.10 + * @param param 详细信息请参考 {@link NERtcReverbParam}。 + * @return + * - 0：方法调用成功。 + * - 其他：方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_set_local_voice_reverb_param(struct nertc_engine* self, const struct nertc_reverb_param* param); + +/** + * @if English + * Publishes or unpublishes the local audio stream. + *
When a user joins a room, the feature is enabled by default. + *
The method does not affect receiving or playing the remote audio stream. The enableLocalAudio(false) method is suitable for scenarios where clients only receives remote media streams and does not publish any local streams. + * @note + * - The method controls data transmitted over the main stream + * - The method can be called before or after a user joins a room. + * @since V4.6.10 + * @param enabled specifies whether to publish the local audio stream. + * - true(default): publishes the local audio stream. + * - false: unpublishes the local audio stream. + * @param mediaType media type. Audio type is supported. + * @return + * - 0: success + * - Others: failure + * @endif + * @if Chinese + * 开启或关闭本地媒体流（主流）的发送。 + *
该方法用于开始或停止向网络发送本地音频或视频数据。 + *
该方法不影响接收或播放远端媒体流，也不会影响本地音频或视频的采集状态。 + * @since V4.6.10 + * @note + * - 该方法暂时仅支持控制音频流的发送。 + * - 该方法在加入房间前后均可调用。 + * - 停止发送媒体流的状态会在通话结束后被重置为允许发送。 + * - 成功调用该方法切换本地用户的发流状态后，房间内其他用户会收到 \ref IRtcEngineEventHandler::onUserAudioStart "onUserAudioStart"（开启发送音频）或 \ref IRtcChannelEventHandler::onUserAudioStop "onUserAudioStop"（停止发送音频）的回调。 + * @par 相关接口 + * - \ref IRtcEngineEx::muteLocalAudioStream "muteLocalAudioStream"： + * - 在需要开启本地音频采集（监测本地用户音量）但不发送音频流的情况下，您也可以调用 muteLocalAudioStream(true) 方法。 + * - 两者的差异在于，muteLocalAudioStream(true) 仍然保持与服务器的音频通道连接，而 enableMediaPub(false) 表示断开此通道，因此若您的实际业务场景为多人并发的大房间，建议您调用 enableMediaPub 方法。 + * @param enabled 是否发布本地媒体流。 + * - true（默认）：发布本地媒体流。 + * - false：不发布本地媒体流。 + * @param media_type 媒体发布类型，暂时仅支持音频。 + * @return + * - 0：方法调用成功。 + * - 其他：方法调用失败。 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_enable_media_publish(struct nertc_engine* self, bool enabled, nertc_media_pub_type media_type); + +/** +* @if English +* Update the permission key. It needs to be set during the call. See ref onUpdatePermissionKey for asynchronous results. +* @param key New Permission Key +* @return +* - 0: success +* - Others: failure +* @endif +* @if Chinese +* 更新权限密钥。 +* - 通过本接口可以实现当用户权限被变更，或者收到权限密钥即将过期的回调 \ref IRtcEngineEventHandlerEx::onPermissionKeyWillExpire() "onPermissionKeyWillExpire" 时，更新权限密钥。 +* @since V4.6.29 +* @par 使用前提 +* 请确保已开通高级 Token 鉴权功能，具体请联系网易云信商务经理。 +* @par 调用时机 +* 请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。 +* @par 业务场景 +* 适用于变更指定用户加入、创建房间或上下麦时发布流相关权限的场景。 +* @par 参数说明 +* +* +* +* +* +* +* +* +* +* +* +*
**参数名称****类型****描述**
keyconst char*新的权限密钥。
+* @par 示例代码 +* @code +* if (rtc_engine_) { +* std::string key;//向服务器请求得到的权限key，具体请参考高级 Token 鉴权 +* rtc_engine_->updatePermissionKey(key.c_str())); if (kNERtcNoError != res) { +* } +* @endcode +* @par 相关回调 +* 调用此接口成功更新权限密钥后会触发 \ref IRtcEngineEventHandlerEx::onUpdatePermissionKey() "onUpdatePermissionKey" 回调。 +* @return +* - 0（kNERtcNoError）：方法调用成功。 +* - 其他：方法调用失败。 +* - 30003（kNERtcErrInvalidParam）：参数错误，比如 key 无效。 +* - 30005（kNERtcErrInvalidState)：当前状态不支持的操作，比如引擎尚未初始化。 +* @endif +*/ +NERTC_API int NERTC_CALL nertc_engine_update_permission_key(struct nertc_engine* self, const char* key); + +/** + * @if Chinese + * 上报自定义事件 + * @param event_name 事件名 不能为空 + * @param custom_identify 自定义标识，比如产品或业务类型，如不需要填null + * @param parameters 参数键值对 ，参数值支持String 及java基本类型(int 、bool....) ， 如不需要填null + * @return 操作返回值，成功则返回 0 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_report_custom_event(struct nertc_engine* self, const char* event_name, const char* custom_identify, const char* parameters); + +/** + * 引擎3D音效算法距离范围设置 + * @note 依赖enableSpatializer接口开启，通话前调用 + * @param audible_distance 监听器能够听到扬声器并接收其文本消息的距离扬声器的最大距离。[0,1000] 默认值为 32。 + * @param conversational_distance 控制扬声器音频保持其原始音量的范围，超出该范围时，语音聊天的响度在被听到时开始淡出。 + * 默认值为 1。 + * @param roll_off:距离衰减模式 #NERtcDistanceRolloffModel ，默认值 #kNERtcDistanceRolloffNone + * @return + * - 0: 方法调用成功 + * - 其他: 调用失败 + */ + +/** + * 设置范围语音模式 + * @note 此接口在加入房间前后均可调用。 + * @param mode 范围语音模式 + * @return 操作返回值，成功则返回 0 + */ +NERTC_API int NERTC_CALL nertc_engine_set_range_audio_mode(struct nertc_engine* self, nertc_range_audio_mode mode); + +/** + * 设置范围语音小队 + * @note 此接口在加入房间前后均可调用。 + * @param team_id 小队ID + * @return 操作返回值，成功则返回 0 + */ +NERTC_API int NERTC_CALL nertc_engine_set_range_audio_team_id(struct nertc_engine* self, int32_t team_id); + +/** + * 引擎3D音效算法距离范围设置 + * @param audible_distance 监听器能够听到扬声器并接收其文本消息的距离扬声器的最大距离。无默认值, 有效范围[1, ∞)。 + * @param conversational_distance 控制扬声器音频保持其原始音量的范围，超出该范围时，语音聊天的响度在被听到时开始淡出。 + * 默认值为 1。 + * @param roll_off:距离衰减模式 #NERtcDistanceRolloffModel ，默认值 #kNERtcDistanceRolloffNone + * @return + * - 0: 方法调用成功 + * - 其他: 调用失败 + */ +NERTC_API int NERTC_CALL nertc_engine_set_audio_recv_range(struct nertc_engine* self, int audible_distance, int conversational_distance, nertc_distance_rolloff_model roll_off); + +/** + * 引擎3D音效算法中本人坐标方位更新接口 + * @param speaker_position 嘴巴位置信息，默认值{0,0,0} + * @param speaker_quaternion 嘴巴方向信息，四元组格式，默认值{0,0,0,0} + * @param head_position 耳朵位置信息，默认值{0,0,0} + * @param head_quaternion 耳朵方向信息，四元组格式，默认值{0,0,0,0} + * @return + * - 0: 方法调用成功 + * - 其他: 调用失败 + */ +NERTC_API int NERTC_CALL nertc_engine_update_self_position(struct nertc_engine* self, const struct nertc_position_info* info); + +/** + * 引擎3D音效算法中房间混响效果开关 + * @note 依赖enableSpatializer接口开启 + * @param enable 混响效果开关，默认值关闭 + * @return + * - 0: 方法调用成功 + * - 其他: 调用失败 + */ +NERTC_API int NERTC_CALL nertc_engine_enable_spatializer_room_effects(struct nertc_engine* self, bool enable); +/** + * 引擎3D音效算法中房间混响属性 + * @note 依赖enableSpatializer接口开启 + * @param room_property 房间属性 #NERtcSpatializerRoomProperty + * @return + * - 0: 方法调用成功 + * - 其他: 调用失败 + */ +NERTC_API int NERTC_CALL nertc_engine_set_spatializer_room_property(struct nertc_engine* self, const struct nertc_spatializer_room_property* room_property); + +/** + * 引擎3D音效算法中渲染模式 + * @note 依赖enableSpatializer接口开启 + * @param mode 渲染模式 #NERtcSpatializerRenderMode ，默认值 #kNERtcSpatializerRenderBinauralHighQuality + * @return + * - 0: 方法调用成功 + * - 其他: 调用失败 + */ +NERTC_API int NERTC_CALL nertc_engine_set_spatializer_render_mode(struct nertc_engine* self, nertc_spatializer_render_mode mode); + +/** + * 初始化引擎3D音效算法 + * @note 此接口在加入房间前调用，退出房间后不重置 + * @return + * - 0: 方法调用成功 + * - 其他: 调用失败 + */ +NERTC_API int NERTC_CALL nertc_engine_init_spatializer(struct nertc_engine* self); + +/** + * 引擎3D音效算法开关 + * @note 通话前调用，通话结束后不重置 + * @param enable 是否打开3D音效算法功能 + * @return + * - 0: 方法调用成功 + * - 其他: 调用失败 + */ +NERTC_API int NERTC_CALL nertc_engine_enable_spatializer(struct nertc_engine* self, bool enable); +/** + * @if English + * Convert I420 to RGBA + * @since V4.5.0 + * @return + * - 0: Success. + * - Other values: Failure. + * @endif + * @if Chinese + * 将I420格式转换为RGBA格式 + * @since V4.5.0 + * @return + * - 0: 方法调用成功 + * - 其他: 调用失败 + * @endif + */ +NERTC_API int NERTC_CALL nertc_engine_convert_i420_to_rgba(const uint8_t* src_y, + int src_stride_y, + const uint8_t* src_u, + int src_stride_u, + const uint8_t* src_v, + int src_stride_v, + uint8_t* dst_rgba, + int dst_stride_rgba, + int width, + int height); + + +/** + @param enabled 麦克风是否打开 + @return + - 0: 方法调用成功； + - 其他: 方法调用失败。 + */ +NERTC_API int NERTC_CALL nertc_engine_get_microphone_mode(struct nertc_engine* self, bool *enabled); +/** + @param volume 麦克风音量 + @return + - 0: 方法调用成功； + - 其他: 方法调用失败。 + */ +NERTC_API int NERTC_CALL nertc_engine_get_recording_signal_volume(struct nertc_engine* self, int *volume); +/** + @param volume 扬声器音量 + @return + - 0: 方法调用成功； + - 其他: 方法调用失败。 + */ +NERTC_API int NERTC_CALL nertc_engine_get_playback_signal_volume(struct nertc_engine* self, int *volume); +/** + * 检查平台麦克风权限（移动端） + @param enabled 麦克风是否有权限 + @return + - 0: 方法调用成功； + - 其他: 方法调用失败。 + */ +NERTC_API int NERTC_CALL nertc_engine_check_mic_permision(struct nertc_engine* self, bool *enabled); +/** + * 暂停音频输入与输出 + @return + - 0: 方法调用成功； + - 其他: 方法调用失败。 + */ +NERTC_API int NERTC_CALL nertc_engine_pause_audio(struct nertc_engine* self); +/** + * 恢复音频输入与输出 + @return + - 0: 方法调用成功； + - 其他: 方法调用失败。 + */ +NERTC_API int NERTC_CALL nertc_engine_resume_audio(struct nertc_engine* self); +/** + * 检查是否已经在房间内 + @return + - true: 在房间内； + - false: 不在房间内。 + */ +NERTC_API bool NERTC_CALL nertc_engine_is_in_channel(struct nertc_engine* self); + +NERTC_END_DECLS + +#endif // NERTC_ENGINE_EX_H diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_engine_predecode_observer.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_engine_predecode_observer.h new file mode 100644 index 0000000..ecd6604 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_engine_predecode_observer.h @@ -0,0 +1,248 @@ +/** @file nertc_engine_predecode_observer.h + * @brief The interface header file of expansion callback of the NERTC SDK. + * All parameter descriptions of the NERTC SDK. All string-related parameters (char *) are encoded in UTF-8. + * @copyright (c) 2022, NetEase Inc. All rights reserved. + */ + +#ifndef NERTC_ENGINE_PREDECODE_OBSERVER_H +#define NERTC_ENGINE_PREDECODE_OBSERVER_H + +#include "nertc_engine_defines.h" + +/** + * @if English + * The pre decode media type. + * @endif + * @if Chinese + * 解码前媒体类型。 + * @endif + */ +typedef enum { + /** + * @if English + * Audio media type. + * @endif + * @if Chinese + * Audio 媒体类型。 + * @endif + */ + kNERtcPreDecodeMediaTypeAudio = 0, + /** + * @if English + * Video media type. + * @endif + * @if Chinese + * Video 媒体类型。 + * @endif + */ + kNERtcPreDecodeMediaTypeVideo = 1, + /** + * @if English + * Unknown media type. + * @endif + * @if Chinese + * Unknown 媒体类型。 + * @endif + */ + kNERtcPreDecodeMediaTypeUnknown = 100, +} nertc_pre_decode_media_type; + +/** + * @if English + * The pre decode video info. + * @endif + * @if Chinese + * 解码前视频详细信息。 + * @endif + */ +struct nertc_pre_decode_video_info { + /** + * @if English + * The video frame width. + * @endif + * @if Chinese + * 视频帧宽。 + * @endif + */ + uint32_t width; + /** + * @if English + * The video frame height. + * @endif + * @if Chinese + * 视频帧高。 + * @endif + */ + uint32_t height; + /** + * @if English + * The video frame is key frame or not. + * @endif + * @if Chinese + * 视频是否为关键帧。 + * @endif + */ + bool is_key_frame; +}; + +/** + * @if English + * The pre decode audio info. + * @endif + * @if Chinese + * 解码前音频详细信息。 + * @endif + */ +struct nertc_pre_decode_audio_info { + /* @if English + * The audio data interval per frame. Unit: milliseconds. + * @endif + * @if Chinese + * 每帧音频数据时间间隔, 单位为毫秒。 + * @endif + */ + uint32_t per_time_ms; + /** + * @if English + * The opus audio data byte. + * @endif + * @if Chinese + * Opus音频数据TOC字节。 + * @endif + */ + uint8_t toc; +}; + +/** + * @if English + * The pre decode frame info + * @endif + * @if Chinese + * 解码前帧信息 + * @endif + */ +struct nertc_pre_decode_frame_info { + /** + * @if English + * The pre decode media type. + * @endif + * @if Chinese + * 解码前媒体类型。 + * @endif + */ + nertc_pre_decode_media_type media_type; + /** + * @if English + * User id. + * @endif + * @if Chinese + * 用户id。 + * @endif + */ + uint64_t uid; + /** + * @if English + * Timestamp. Unit: milliseconds. + * @endif + * @if Chinese + * 解码前媒体时间戳，单位为毫秒。 + * @endif + */ + int64_t timestamp_ms; + /** + * @if English + * The pre decode data. + * @endif + * @if Chinese + * 解码前媒体数据。 + * @endif + */ + uint8_t* data; + /** + * @if English + * The pre decode data length. + * @endif + * @if Chinese + * 解码前媒体有效数据长度。 + * @endif + */ + int length; + /** + * @if English + * Codec name. + * @endif + * @if Chinese + * 编码器名称。 + * @endif + */ + const char* codec; + /** + * @if English + * The pre decode frame is main stream or sub stream. + * @endif + * @if Chinese + * 解码前媒体数据是否为主流或辅流。 + * @endif + */ + bool is_main_stream; + /** + * @if English + * The pre decode video info, which is valid for {@link media_type} equal kNERtcPreDecodeMediaTypeVideo. + * @endif + * @if Chinese + * 解码前音频详细信息, 仅 {@link media_type} 为 kNERtcPreDecodeMediaTypeVideo 时有效。 + * @endif + */ + nertc_pre_decode_video_info video_info; + /** + * @if English + * The pre decode audio info, which is valid for {@link media_type} equal kNERtcPreDecodeMediaType. + * @endif + * @if Chinese + * 解码前音频详细信息, 仅 {@link media_type} 为 kNERtcPreDecodeMediaType 时有效。 + * @endif + */ + nertc_pre_decode_audio_info audio_info; +}; + +/** + * @if English + * The predecode media data observer object. + * @endif + * @if Chinese + * 解码前媒体数据观测器。 + * @endif + */ +struct nertc_pre_decode_frame_observer { + void* self; + /** + * @if English + * Occurs when the predecode media data is comming. + * @param pre_decode_frame The predecode media frame. + * @endif + * @if Chinese + * 解码前媒体数据回调。 + * - 调用 \ref nertc::IRtcEngineEx::setPreDecodeObserver "setPreDecodeObserver" + * 方法注册解码前媒体数据观测器后，SDK会触发该回调，可以通过返回的用户 UID、媒体数据类型、数据长度等信息对媒体数据自行编码。 + * @since V4.6.29 + * @par 使用前提 + * 请通过 \ref nertc::IRtcEngineEx::setPreDecodeObserver "setPreDecodeObserver" 接口设置回调监听。 + * @par 参数说明 + * + * + * + * + * + * + * + * + * + * + * + *
**参数名称****类型****描述**
pre_decode_frameNERtcPreDecodeFrameInfo*解码前媒体数据。
+ * @endif + */ + void (NERTC_CALL *on_frame)(void* self, struct nertc_pre_decode_frame_info* pre_decode_frame); +}; + +#endif \ No newline at end of file diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_engine_video_encoder_qos_observer.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_engine_video_encoder_qos_observer.h new file mode 100644 index 0000000..b972363 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_engine_video_encoder_qos_observer.h @@ -0,0 +1,119 @@ +/** @file nertc_engine_video_encoder_qos_observer.h +* @brief The interface header file of expansion callback of the NERTC SDK. +* All parameter descriptions of the NERTC SDK. All string-related parameters (char *) are encoded in UTF-8. +* @copyright (c) 2022, NetEase Inc. All rights reserved. +*/ + +#ifndef NERTC_ENGINE_VIDEO_ENCODER_QOS_OBSERVER_H +#define NERTC_ENGINE_VIDEO_ENCODER_QOS_OBSERVER_H + +#include "nertc_engine_defines.h" + +/** + * @if English + * The SDK reports video encoder qos to the application through INERtcVideoEncoderQosObserver expansion callback interface class. + * @endif + * @if Chinese + * INERtcVideoEncoderQosObserver 回调扩展接口类用于 SDK 向 App 上报视频编码qos信息。 + * @endif + */ +struct nertc_video_encoder_qos_observer { + void* self; + /** + * @if English + * The video I frame request callback. + * @param frame The video stream type. + * @endif + * @if Chinese + * I 帧请求事件回调。 + * - 调用 \ref IRtcEngineEx::setVideoEncoderQosObserver "setVideoEncoderQosObserver" 方法注册解码前媒体数据观测器后，SDK 可能会在推送外部视频编码帧后触发该回调，此时请及时发送相应的 IDR 帧，否则对端无法渲染视频画面。 + * @since V4.6.29 + * @par 使用前提 + * 请在 INERtcVideoEncoderQosObserver 接口类中通过 \ref IRtcEngineEx::setVideoEncoderQosObserver "setVideoEncoderQosObserver" 接口设置回调监听。 + * @par 参数说明 + * + * + * + * + * + * + * + * + * + * + * + *
**参数名称****类型****描述**
video_stream_type \ref nertc::NERtcVideoStreamType "NERtcVideoStreamType"视频通道类型：
  • kNERtcVideoStreamMain：主流。
  • kNERtcVideoStreamSub：辅流。
+ * @endif + */ + void (NERTC_CALL *on_request_send_key_frame)(void* self, nertc_video_stream_type stream_type); + + /** + * @if English + * The video bitrate info. + * @param bitrate_bps The video bitrate. Unit: bps。 + * @param video_stream_type The video stream type. + * @endif + * @if Chinese + * 视频码率信息回调。 + * - 调用 \ref IRtcEngineEx::setVideoEncoderQosObserver "setVideoEncoderQosObserver" 方法注册解码前媒体数据观测器后，SDK 可能会在推送外部视频编码帧后触发该回调，此时可以调整对应的码率，防止出现超编，引发视频异常。 + * @since V4.6.29 + * @par 使用前提 + * 请在 INERtcVideoEncoderQosObserver 接口类中通过 \ref IRtcEngineEx::setVideoEncoderQosObserver "setVideoEncoderQosObserver" 接口设置回调监听。 + * @par 参数说明 + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
**参数名称****类型****描述**
bitrate_bps uint32_t码率。单位为 kbps。
video_stream_type \ref nertc::NERtcVideoStreamType "NERtcVideoStreamType"视频通道类型：
  • kNERtcVideoStreamMain：主流。
  • kNERtcVideoStreamSub：辅流。
+ * @endif + */ + void (NERTC_CALL *on_bitrate_updated)(void* self, uint32_t bps, nertc_video_stream_type stream_type); + + /** + * @if English + * The video codec info callback. + * @param video_codec_type The video codec type. + * @param video_stream_type The video stream type. + * @endif + * @if Chinese + * 视频编码器类型信息回调。 + * - 调用 \ref IRtcEngineEx::setVideoEncoderQosObserver "setVideoEncoderQosObserver" 方法注册解码前媒体数据观测器后，SDK 默认会在推送外部视频编码帧后触发一次该回调；后续若编码器类型发生变更时会再次触发此回调，此时请重置您的编码器。 + * @since V4.6.29 + * @par 使用前提 + * 请在 INERtcVideoEncoderQosObserver 接口类中通过 \ref IRtcEngineEx::setVideoEncoderQosObserver "setVideoEncoderQosObserver" 接口设置回调监听。 + * @par 参数说明 + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
**参数名称****类型****描述**
video_codec_type \ref nertc::NERtcVideoCodecType "NERtcVideoCodecType"视频编码器类型：
  • kNERtcVideoCodecTypeH264(3)：H.264 编码器。
video_stream_type \ref nertc::NERtcVideoStreamType "NERtcVideoStreamType"视频通道类型：
  • kNERtcVideoStreamMain：主流。
  • kNERtcVideoStreamSub：辅流。
+ * @endif + */ + void (NERTC_CALL *on_video_codec_updated)(void* self, nertc_video_codec_type codec_type, nertc_video_stream_type stream_type); +}; + +#endif diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_error_code.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_error_code.h new file mode 100644 index 0000000..9599b8c --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_error_code.h @@ -0,0 +1,977 @@ +#ifndef NERTC_ERROR_CODE_H +#define NERTC_ERROR_CODE_H + +#include "nertc_engine_defines.h" + +/** + * @if English + * Error codes. + *
Error codes are returned when a problem that cannot be recovered without app intervention has occurred. + * @endif + * @if Chinese + * 错误代码。 + *
错误代码意味着 SDK 遇到不可恢复的错误，需要应用程序干预。 + * @endif + */ +typedef enum { + /** + * @if English + * No errors. + * @endif + * @if Chinese + * 没有错误 + * @endif + */ + kNERtcNoError = 0, + //Error codes are returned when resources are wrongly assigned. Such kind of error code is not returned when the SDK sends the normal permissions. + /** + * @if English + * No permissions. Possible reasons: + * - Audio and Video Call is not enabled, whose trial period is overdue or fees are not renewed. + * - Token is not specified in safe mode when joining a channel. + * - Other permission-related problems. + * @endif + * @if Chinese + * - 权限不足。原因包括： + * - 未开通音视频通话 2.0 服务，或试用期已过、未及时续费等。 + * - 安全模式下加入房间时未设置 Token。 + * - 其他权限问题。 + * @endif + */ + kNERtcErrChannelReservePermissionDenied = 403, + /** + * @if English + * Request timeouts. + * @endif + * @if Chinese + * 请求超时 + * @endif + */ + kNERtcErrChannelReserveTimeOut = 408, + /** + * @if English + * Error codes are returned when parameters are requested in the server. + * @endif + * @if Chinese + * 服务器请求参数错误 + * @endif + */ + kNERtcErrChannelReserveErrorParam = 414, + /** + * @if English + * Invalid APP KEY. + * @endif + * @if Chinese + * 非法的APP KEY + * @endif + */ + kNERtcErrChannelReserveErrorAppKey = 417, + /** + * @if English + * Unknown errors are returned when channels are assigned in the server. + * @endif + * @if Chinese + * 分配房间服务器未知错误 + * @endif + */ + kNERtcErrChannelReserveServerFail = 500, + /** + * @if English + * Only two users are supported in the same channel. If the third user wants to share the same channel name, assign another channel. + * @endif + * @if Chinese + * 只支持两个用户, 有第三个人试图使用相同的房间名分配房间 + * @endif + */ + kNERtcErrChannelReserveMoreThanTwoUser = 600, + /** + * @if Chinese + * 权限密钥错误 + * @endif + */ + kNERtcErrChannelPermissionKeyError = 901, + /** + * @if Chinese + * 权限密钥超时 + * @endif + */ + kNERtcErrChannelPermissionKeyTimeout = 902, + + //livestream task + /** + * @if English + * Invalid permission that is replaced by following operations. + * @endif + * @if Chinese + * task请求无效，被后续操作覆盖 + * @endif + */ + kNERtcErrLsTaskRequestInvalid = 1301, + /** + * @if English + * Parameter format error. + * @endif + * @if Chinese + * task参数格式错误 + * @endif + */ + kNERtcErrLsTaskIsInvaild = 1400, + /** + * @if English + * Exited the channel. + * @endif + * @if Chinese + * 房间已经退出 + * @endif + */ + kNERtcErrLsTaskRoomExited = 1401, + /** + * @if English + * Streaming tasks are over the limit. + * @endif + * @if Chinese + * 推流任务超出上限 + * @endif + */ + kNERtcErrLsTaskNumLimit = 1402, + /** + * @if English + * Duplicates ID of streaming tasks. + * @endif + * @if Chinese + * 推流ID重复 + * @endif + */ + kNERtcErrLsTaskDuplicateId = 1403, + /** + * @if English + * No ID task or no channels. + * @endif + * @if Chinese + * taskId任务不存在，或房间不存在 + * @endif + */ + kNERtcErrLsTaskNotFound = 1404, + /** + * @if English + * Permission failures. + * @endif + * @if Chinese + * 请求失败 + * @endif + */ + kNERtcErrLsTaskRequestErr = 1417, + /** + * @if English + * Internal errors in the server. + * @endif + * @if Chinese + * 服务器内部错误 + * @endif + */ + kNERtcErrLsTaskInternalServerErr = 1500, + /** + * @if English + * Layout parameter errors. + * @endif + * @if Chinese + * 布局参数错误 + * @endif + */ + kNERtcErrLsTaskInvalidLayout = 1501, + /** + * @if English + * Image errors of users. + * @endif + * @if Chinese + * 用户图片错误 + * @endif + */ + kNERtcErrLsTaskUserPicErr = 1512, + /** + * @if Chinese + * 没有发布权限 + * @endif + */ + kNERtcErrChannelNoPublishPermission = 1620, + /** + * @if Chinese + * 没有订阅权限 + * @endif + */ + kNERtcErrChannelNoSubscribePermission = 2803, + /** + * @if Chinese + * 加入房间的人数达到限制 + * @endif + */ + kNERtcErrServerPersonsInRoomReachedTheLimit = 4003, + + /** + * @if English + * Common errors. + * @endif + * @if Chinese + * 通用错误 + * @endif + */ + kNERtcErrFatal = 30001, + /** + * @if English + * Out of memory. + * @endif + * @if Chinese + * 内存耗尽 + * @endif + */ + kNERtcErrOutOfMemory = 30002, + /** + * @if English + * Invalid parameters. + * @endif + * @if Chinese + * 错误的参数 + * @endif + */ + kNERtcErrInvalidParam = 30003, + /** + * @if English + * Unsupported operation. + * @endif + * @if Chinese + * 不支持的操作 + * @endif + */ + kNERtcErrNotSupported = 30004, + /** + * @if English + * Unsupported operations in the current state. + * @endif + * @if Chinese + * 当前状态不支持的操作 + * @endif + */ + kNERtcErrInvalidState = 30005, + /** + * @if English + * Depleted resources. + * @endif + * @if Chinese + * 资源耗尽 + * @endif + */ + kNERtcErrLackOfResource = 30006, + /** + * @if English + * Invalid index. + * @endif + * @if Chinese + * 非法 index + * @endif + */ + kNERtcErrInvalidIndex = 30007, + /** + * @if English + * Device is not found. + * @endif + * @if Chinese + * 设备未找到 + * @endif + */ + kNERtcErrDeviceNotFound = 30008, + /** + * @if English + * Invalid device ID. + * @endif + * @if Chinese + * 非法设备 ID + * @endif + */ + kNERtcErrInvalidDeviceSourceID = 30009, + /** + * @if English + * Invalid profile type of video. + * @endif + * @if Chinese + * 非法的视频 profile type + * @endif + */ + kNERtcErrInvalidVideoProfile = 30010, + /** + * @if English + * Device creation errors. + * @endif + * @if Chinese + * 设备创建错误 + * @endif + */ + kNERtcErrCreateDeviceSourceFail = 30011, + /** + * @if English + * Invalid rendering device. + * @endif + * @if Chinese + * 非法的渲染容器 + * @endif + */ + kNERtcErrInvalidRender = 30012, + /** + * @if English + * Device is already enabled. + * @endif + * @if Chinese + * 设备已经打开 + * @endif + */ + kNERtcErrDevicePreviewAlreadyStarted = 30013, + /** + * @if English + * Transmission error. + * @endif + * @if Chinese + * 传输错误 + * @endif + */ + kNERtcErrTransmitPendding = 30014, + /** + * @if English + * Server connection error. + * @endif + * @if Chinese + * 连接服务器错误 + * @endif + */ + kNERtcErrConnectFail = 30015, + /** + * @if English + * Fails to create Audio dump file. + * @endif + * @if Chinese + * 创建Audio dump文件失败 + * @endif + */ + kNERtcErrCreateDumpFileFail = 30016, + /** + * @if English + * Fails to enable Audio dump file. + * @endif + * @if Chinese + * 开启Audio dump失败 + * @endif + */ + kNERtcErrStartDumpFail = 30017, + /** + * @if English + * Fails to enable desktop screen recording if camera is started at the same time. + * @endif + * @if Chinese + * 启动桌面录屏失败，不能与camera同时启动 + * @endif + */ + kNERtcErrDesktopCaptureInvalidState = 30020, + /** + * @if English + * Parameters are invalid when the desktop screen recording is implemented. + * @endif + * @if Chinese + * 桌面录屏传入参数无效 + * @endif + */ + kNERtcErrDesktopCaptureInvalidParam = 30021, + /** + * @if English + * Desktop screen recording is not ready. + * @endif + * @if Chinese + * 桌面录屏未就绪 + * @endif + */ + kNERtcErrDesktopCaptureNotReady = 30022, + /** + * @if English + * Selected device is occupied. + * @endif + * @if Chinese + * 所选设备已被占用 + * @endif + */ + kNERtcErrDeviceOccupied = 30027, + /** + * @if English + * Repeatedly joins the channel. + * @endif + * @if Chinese + * 重复加入房间 + * @endif + */ + kNERtcErrChannelAlreadyJoined = 30100, + /** + * @if English + * Does not join the channel. + * @endif + * @if Chinese + * 尚未加入房间 + * @endif + */ + kNERtcErrChannelNotJoined = 30101, + /** + * @if English + * Repeatedly leaves the channel. + * @endif + * @if Chinese + * 重复离开房间 + * @endif + */ + kNERtcErrChannelRepleatedlyLeave = 30102, + /** + * @if English + * Fails to join the channel. + * @endif + * @if Chinese + * 加入房间操作失败 + * @endif + */ + kNERtcErrRequestJoinChannelFail = 30103, + /** + * @if English + * Session is not found. + * @endif + * @if Chinese + * 会话未找到 + * @endif + */ + kNERtcErrSessionNotFound = 30104, + /** + * @if English + * The user is not found. + * @endif + * @if Chinese + * 用户未找到 + * @endif + */ + kNERtcErrUserNotFound = 30105, + /** + * @if English + * Invalid user ID. + * @endif + * @if Chinese + * 非法的用户 ID + * @endif + */ + kNERtcErrInvalidUserID = 30106, + /** + * @if English + * Users do not connect the multi-media data. + * @endif + * @if Chinese + * 用户多媒体数据未连接 + * @endif + */ + kNERtcErrMediaNotStarted = 30107, + /** + * @if English + * Source is not found. + * @endif + * @if Chinese + * source 未找到 + * @endif + */ + kNERtcErrSourceNotFound = 30108, + /** + * @if English + * Invalid state of switching channels. + * @endif + * @if Chinese + * 切换房间状态无效 + * @endif + */ + kNERtcErrSwitchChannelInvalidState = 30109, + /** + * @if English + * Invalid state of relaying media streams. + * @endif + * @if Chinese + * 重复调用 startChannelMediaRelay。 + * @endif + */ + kNERtcErrChannelMediaRelayInvalidState = 30110, + /** + * @if English + * Invalid permissions of relaying streams. Check whether the mode is set as audience mode or 1v1 mode. + * @endif + * @if Chinese + * 媒体流转发权限不足。例如调用 startChannelMediaRelay 的房间成员为主播角色、或房间为双人通话房间，不支持转发媒体流。 + * @endif + */ + kNERtcErrChannelMediaRelayPermissionDenied = 30111, + /** + * @if English + * If you fail to stop relaying media streams, check whether the media stream forwarding is enabled. + * @endif + * @if Chinese + * 调用 stopChannelMediaRelay 前，未调用 startChannelMediaRelay。 + * @endif + */ + kNERtcErrChannelMediaRelayStopFailed = 30112, + /** + * @if English + * If you set the different encryption password of media streams from other members in the room, you fail to join the room. + * Sets new encryption password thorough enableEncryption. + * @endif + * @if Chinese + * 设置的媒体流加密密钥与房间中其他成员不一致，加入房间失败。请通过 enableEncryption 重新设置加密密钥。 + * @endif + */ + kNERtcErrEncryptNotSuitable = 30113, + /** + * @if English + * User permkey auth failed. + * @endif + * @if Chinese + * 用户权限验证错误 + * @endif + */ + kNERtcErrUserPermKeyAuthFailed = 30121, + + kNERtcErrSEIExceedMaxDataLimit = 30122, /** SEI 超过最大数据限制 */ + /** + * @if Chinese + * 数据通道发送大小超过最大限制 + * @endif + */ + kNERtcErrDataChannelExceedMaxDataLimit = 30123, + /** + * @if English + * Connection is not found. + * @endif + * @if Chinese + * 连接未找到 + * @endif + */ + kNERtcErrConnectionNotFound = 30200, + /** + * @if English + * Media streams are not found. + * @endif + * @if Chinese + * 媒体流未找到 + * @endif + */ + kNERtcErrStreamNotFound = 30201, + /** + * @if English + * Fails to join the track. + * @endif + * @if Chinese + * 加入 track 失败 + * @endif + */ + kNERtcErrAddTrackFail = 30202, + /** + * @if English + * Track is not found. + * @endif + * @if Chinese + * track 未找到 + * @endif + */ + kNERtcErrTrackNotFound = 30203, + /** + * @if English + * Media disconnection. + * @endif + * @if Chinese + * 媒体连接断开 + * @endif + */ + kNERtcErrMediaConnectionDisconnected = 30204, + /** + * @if English + * Signalling disconnection. + * @endif + * @if Chinese + * 信令连接断开 + * @endif + */ + kNERtcErrSignalDisconnected = 30205, + /** + * @if English + * The user is removed from the room. + * @endif + * @if Chinese + * 被踢出房间 + * @endif + */ + kNERtcErrServerKicked = 30206, + /** + * @if English + * Removed for the channel is already disabled. + * @endif + * @if Chinese + * 因房间已关闭而被踢出 + * @endif + */ + kNERtcErrKickedForRoomClosed = 30207, + /** + * @if English + * A room is closed when a user switches to another room. + * @endif + * @if Chinese + * 因为切换房间的操作房间被关闭 + * @endif + */ + kNERtcErrChannelLeaveBySwitchAction = 30208, + /** + * @if English + * A room is closed due to duplicates user IDs + * @endif + * @if Chinese + * 因为有重复 uid 登录导致房间被关闭 + * @endif + */ + kNERtcErrChannelLeaveByDuplicateUidLogin = 30209, + + /** + * @if English + * No permission of audio devices. + * @endif + * @if Chinese + * 没有音频设备权限 + * @endif + */ + kNERtcRuntimeErrADMNoAuthorize = 40000, + /** + * @if English + * Audio device module: Errors occur when initializing recording devices. Please check whether the recording device can work properly or have limited permissions, or try reconnecting to rejoin the room. + * @endif + * @if Chinese + * 音频设备模块：初始化录音设备时出现错误。请检查录音设备是否正常或者权限限制，或者尝试重新进入房间。 + * @endif + */ + kNERtcRuntimeErrADMInitRecording = 40001, + /** + * @if English + * Audio device module: Errors occur when enabling recording devices. Please check whether the recording device can work properly, or try reconnecting to rejoin the room. + * @endif + * @if Chinese + * 音频设备模块：启动录音设备出现错误。请检查录音设备是否正常，或者尝试重新进入房间。 + * @endif + */ + kNERtcRuntimeErrADMStartRecording = 40002, + /** + * @if English + * Audio device module: Errors occur when running recording devices. Please check whether the recording device can work properly, or try reconnecting to rejoin the room. + * @endif + * @if Chinese + * 音频设备模块：运行时录音错误。请检查录音设备是否正常，或者尝试重新进入房间。 + * @endif + */ + kNERtcRuntimeErrADMStopRecording = 40003, + /** + * @if English + * Audio device module: Errors occur when initializing playback devices. Please check whether the playback device can work properly or have limited permissions, or try reconnecting to rejoin the room. + * @endif + * @if Chinese + * 音频设备模块：初始化播放设备出现错误。请检查播放设备是否异常或者权限限制，或者尝试重新进入房间。 + * @endif + */ + kNERtcRuntimeErrADMInitPlayout = 40004, + /** + * @if English + * Audio device module: Errors occur when enabling playback devices. Please check whether the playback device can work properly, or try reconnecting to rejoin the room. + * @endif + * @if Chinese + * 音频设备模块：启动播放设备出现错误。请检查播放设备是否正常，或者尝试重新进入房间。 + * @endif + */ + kNERtcRuntimeErrADMStartPlayout = 40005, + /** + * @if English + * Audio device module: Errors occur when running playback devices. Please check whether the playback device can work properly, or try reconnecting to rejoin the room. + * @endif + * @if Chinese + * 音频设备模块：运行时播放出现错误。请检查播放设备是否正常，或者尝试重新进入房间。 + * @endif + */ + kNERtcRuntimeErrADMStopPlayout = 40006, + + /** 音频采集设备运行异常 */ + kNERtcRuntimeErrADMRecordingFailed = 40007, + /** 音频播放设备运行异常 */ + kNERtcRuntimeErrADMPlayoutFailed = 40008, + + /** + * @if English + * No permission of video devices. + * @endif + * @if Chinese + * 没有视频设备权限 + * @endif + */ + kNERtcRuntimeErrVDMNoAuthorize = 50000, + /** + * @if English + * Use substream without the screen-sharing stream + * @endif + * @if Chinese + * 非屏幕共享使用辅流 + * @endif + */ + + kNERtcRuntimeErrVDMNotScreenUseSubStream = 50001, + /**< 摄像头断开 */ + kNERtcRuntimeErrVDMCameraDisconnect = 50303, + /**< 摄像头死机*/ + kNERtcRuntimeErrVDMCameraFreezed = 50304, + /**< 未知摄像头错误 */ + kNERtcRuntimeErrVDMCameraUnknownError = 50305, + /**< 摄像头无数据帧。请检查摄像头或者切换摄像头 */ + kNERtcRuntimeErrVDMCameraNoFrame = 50306, + /**< 摄像头启动失败。请检查摄像头是否存在或被占用 */ + kNERtcRuntimeErrVDMCameraCreateFail = 50307, + /** + * @if English + * No permission of video recording. + * @endif + * @if Chinese + * 没有录制视频权限 + * @endif + */ + kNERtcRuntimeErrScreenCaptureNoAuthorize = 50400, +} nertc_error_code; + +/** + * @if English + * @enum NERtcRoomServerErrorCode The related error codes of room server. TODO:NERtcErrorCode. + * + * @endif + * @if Chinese + * @enum NERtcRoomServerErrorCode room server相关错误码。TODO：NERtcErrorCode + * @endif + */ +typedef enum { + /** + * @if English + * Successful operation. + * @endif + * @if Chinese + * 操作成功 + * @endif + */ + kNERtcRoomServerErrOK = 200, + /** + * @if English + * Authentication error. + * @endif + * @if Chinese + * 认证错误 + * @endif + */ + kNERtcRoomServerErrAuthError = 401, + /** + * @if English + * Channel is not found. + * @endif + * @if Chinese + * 房间不存在 + * @endif + */ + kNERtcRoomServerErrChannelNotExist = 404, + /** + * @if English + * The uid of the channel is not found. + * @endif + * @if Chinese + * 房间下的uid不存在 + * @endif + */ + kNERtcRoomServerErrUidNotExist = 405, + /** + * @if English + * Request data error. + * @endif + * @if Chinese + * 请求数据不对 + * @endif + */ + kNERtcRoomServerErrDataError = 417, + /** + * @if English + * Internal error that request error occurs in the TurnServer. + * @endif + * @if Chinese + * 内部错误（TurnServer请求异常） + * @endif + */ + kNERtcRoomServerErrUnknown = 500, + /** + * @if English + * Internal errors in the server. + * @endif + * @if Chinese + * 服务器内部错误 + * @endif + */ + kNERtcRoomServerErrServerError = 600, + /** + * @if English + * Invalid operation. + * @endif + * @if Chinese + * 无效的操作 + * @endif + */ + kNERtcRoomServerErrInvilid = 11403, +} nertc_room_server_error_code; + +/** @enum nertc_audio_mixing_error_code 混音音乐文件错误码。 +*/ +typedef enum { + /** + * @if English + * No error. + * @endif + * @if Chinese + * 没有错误。 + * @endif + */ + kNERtcAudioMixingErrorOK = 0, + /** + * @if English + * Common error. + * @endif + * @if Chinese + * 通用错误。 + * @endif + */ + kNERtcAudioMixingErrorFatal = 1, + /** + * @if English + * Audio mixing is not enabled normally. + * @endif + * @if Chinese + * 伴音不能正常打开 + * @endif + */ + kNERtcAudioMixingErrorCanNotOpen, + /** + * @if English + * Audio decoding error. + * @endif + * @if Chinese + * 音频解码错误 + * @endif + */ + kNERtcAudioMixingErrorDecode, + /** + * @if English + * Interruption codes in the operation. + * @endif + * @if Chinese + * 操作中断码 + * @endif + */ + kNERtcAudioMixingErrorInterrupt, + /** + * @if English + * 404 file not found，only for http / https. + * @endif + * @if Chinese + * 404 file not found，only for http / + * @endif + */ + kNERtcAudioMixingErrorHttpNotFound, + /** + * @if English + * Fails to enable streams/files. + * @endif + * @if Chinese + * 打开流 / 文件失败 + * @endif + */ + kNERtcAudioMixingErrorOpen, + /** + * @if English + * Decoding information failures or timeouts. + * @endif + * @if Chinese + * 获取解码信息失败 / 超时 + * @endif + */ + kNERtcAudioMixingErrorNInfo, + /** + * @if English + * No audio streams. + * @endif + * @if Chinese + * 无音频流 + * @endif + */ + kNERtcAudioMixingErrorNStream, + /** + * @if English + * No decoder. + * @endif + * @if Chinese + * 无解码器 + * @endif + */ + kNERtcAudioMixingErrorNCodec, + /** + * @if English + * No memory. + * @endif + * @if Chinese + * 无内存 + * @endif + */ + kNERtcAudioMixingErrorNMem, + /** + * @if English + * Failures or timeouts of enabling decoders. + * @endif + * @if Chinese + * 解码器打开失败 / 超时 + * @endif + */ + kNERtcAudioMixingErrorCodecOpen, + /** + * @if English + * Invalid audio parameters such as channels and sample rate. + * @endif + * @if Chinese + * 无效音频参数（声道、采样率） + * @endif + */ + kNERtcAudioMixingErrorInvalidInfo, + /** + * @if English + * Streams/files enabling timeouts. + * @endif + * @if Chinese + * 打开流 / 文件超时 + * @endif + */ + kNERtcAudioMixingErrorOpenTimeout, + /** + * @if English + * Network io timeouts. + * @endif + * @if Chinese + * 网络io超时 + * @endif + */ + kNERtcAudioMixingErrorIoTimeout, + /** + * @if English + * Network io errors. + * @endif + * @if Chinese + * 网络io错误 + * @endif + */ + kNERtcAudioMixingErrorIo, +} nertc_audio_mixing_error_code; + + +#endif //NERTC_ERROR_CODE_H diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_media_stats_observer.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_media_stats_observer.h new file mode 100644 index 0000000..8f462d7 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_media_stats_observer.h @@ -0,0 +1,64 @@ +#ifndef NERTC_MEDIA_STATS_OBSERVER_H +#define NERTC_MEDIA_STATS_OBSERVER_H + +#include "nertc_engine_defines.h" + +struct nertc_media_stats_observer { + void *self; + + /** + * 当前通话统计回调。 + * SDK 定期向 App 报告当前通话的统计信息，每 2 秒触发一次。 + * + * @param stats NERTC 引擎统计数据: nertc_stats + */ + void (NERTC_CALL *on_rtc_stats)(void *self, const struct nertc_stats *stats); + + /** + * 本地音频流统计信息回调。 + * 该回调描述本地设备发送音频流的统计信息，每 2 秒触发一次。 + * + * @param stats 本地音频流统计信息。详见 nertc_audio_send_stats. + */ + void (NERTC_CALL *on_local_audio_stats)(void *self, const struct nertc_audio_send_stats *stats); + + /** + * 通话中远端音频流的统计信息回调。 + * 该回调描述远端用户在通话中端到端的音频流统计信息，每 2 秒触发一次。 + * + * @param stats 每个远端用户音频统计信息的数组。详见 nertc_audio_recv_stats. + * @param user_count stats 数组的大小。 + */ + void (NERTC_CALL *on_remote_audio_stats)(void *self, const struct nertc_audio_recv_stats *stats, unsigned int user_count); + + /** + * 本地视频流统计信息回调。 + * + * 该回调描述本地设备发送视频流的统计信息，每 2 秒触发一次。 + * + * @param stats 本地视频流统计信息。详见 nertc_video_send_stats. + */ + void (NERTC_CALL *on_local_video_stats)(void *self, const struct nertc_video_send_stats *stats); + + /** + * 通话中远端视频流的统计信息回调。 + * + * 该回调描述远端用户在通话中端到端的视频流统计信息，每 2 秒触发一次。 + * + * @param stats 每个远端用户视频统计信息的数组。详见 nertc_video_recv_stats. + * @param user_count stats 数组的大小。 + */ + void (NERTC_CALL *on_remote_video_stats)(void *self, const struct nertc_video_recv_stats *stats, unsigned int user_count); + + /** + * 通话中每个用户的网络上下行质量报告回调。 + * + * 该回调描述每个用户在通话中的网络状态，每 2 秒触发一次，只上报状态有变更的成员。 + * + * @param infos 每个用户 ID 和网络上下行质量信息的数组: nertc_network_quality_info + * @param user_count infos 数组的大小，即用户数。 + */ + void (NERTC_CALL *on_network_quality)(void *self, const struct nertc_network_quality_info *infos, unsigned int user_count); +}; + +#endif //NERTC_MEDIA_STATS_OBSERVER_H diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_video_device_manager.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_video_device_manager.h new file mode 100644 index 0000000..57ea8cd --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_video_device_manager.h @@ -0,0 +1,141 @@ +#ifndef NERTC_VIDEO_MANAGER_H +#define NERTC_VIDEO_MANAGER_H + +#include "nertc_engine_defines.h" + +NERTC_BEGIN_DECLS +/** + * @if English + * Gets the list of all video capturing devices in the system. + *
The method returns an IDeviceCollection object that includes all Video capturing devices in the system. Enumerates + * capturing devices with the App through the IDeviceCollection object. + * @note + * After the method is used, the App needs to destroy the returned object. + * @return + * - Success: An IDeviceCollection object includes all Video capturing devices. + * - Failure: Null. + * @endif + * @if Chinese + * 获取系统中所有的视频采集设备列表。 + *
该方法返回一个 IDeviceCollection 对象，包含系统中所有的音频采集设备。通过IDeviceCollection 对象，App + * 可以枚举视频采集设备。 + * @note + * 在使用结束后，App 需调用 destroy 方法销毁返回的对象。 + * @return + * - 方法调用成功：一个 IDeviceCollection 对象，包含所有的视频采集设备。 + * - 方法调用失败：NULL 。 + * @endif + */ +NERTC_API struct nertc_device_collection* NERTC_CALL nertc_video_device_manager_enumerate_capture_devices(struct nertc_video_device_manager* self); +/** +* @if Chinese +* 指定视频采集设备。 +*
通过本接口可以实现为主流或辅流视频通道选择视频采集设备。 +* @since V4.6.20 +* @par 使用前提 +* 请在通过 \ref IRtcEngineEx::startVideoPreview(NERtcVideoStreamType type) "startVideoPreview" 接口开启视频预览后调用该方法。 +* @par 调用时机 +* 请在初始化后调用该方法。 +* @note +* 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。 +* @par 参数说明 +* +* +* +* +* +* +* +* +* +* +* +* +* +* +* +* +*
**参数名称****类型****描述**
device_idconst char [kNERtcMaxDeviceIDLength]视频采集设备的设备 ID。可以通过 \ref IVideoDeviceManager::enumerateCaptureDevices "enumerateCaptureDevices" +* 接口获取。
typesee #NERtcVideoStreamType视频通道类型：
  • kNERTCVideoStreamMain（默认）：主流。
  • kNERTCVideoStreamSub：辅流。
+* @par 示例代码 +* @code +* //先获取主流通道的视频管理对象 +* nertc::IVideoDeviceManager * manager = nullptr; +* rtcEngine->queryInterface(nertc::kNERtcIIDVideoDeviceManager, &(void*)manager); +* std::string deviceID = ...;//通过 enumerateCaptureDevices 获取 +* nertc::NERtcVideoStreamType type = nertc::kNERTCVideoStreamMain; +* //设置主流通道的视频设备ID +* videoManager->setDevice(deviceID, type); +* //先获取辅流通道的视频管理对象 +* nertc::IVideoDeviceManager * manager = nullptr; +* rtcEngine->queryInterface(nertc::kNERtcIIDVideoDeviceManager, &(void*)manager); +* std::string deviceID = ...;//通过 enumerateCaptureDevices 获取 +* nertc::NERtcVideoStreamType type = nertc::kNERTCVideoStreamSub; +* //设置辅流通道的视频设备ID +* videoManager->setDevice(deviceID, type); +* @endcode +* @return +* - 0（kNERtcNoError）：方法调用成功。 +* - 其他：方法调用失败。 +* - 30003（kNERtcErrInvalidParam）：参数错误，比如 deviceID 设置错误。 +* - 30004（kNERtcErrNotSupported）：不支持的操作，比如使用的是纯音频 SDK。 +* - 30008（kNERtcErrDeviceNotFound）：未找到设备。 +* - 30009（kNERtcErrInvalidDeviceSourceID）：非法的设备，比如设置的 deviceID 字符串含有非法字符。 +* @endif +*/ +NERTC_API int NERTC_CALL nertc_video_device_manager_set_device(struct nertc_video_device_manager* self, nertc_video_stream_type type, const char* device_id); + +/** +* @if Chinese +* 获取当前使用的视频采集设备信息。 +*
通过本接口可以实现获取主流或辅流视频通道已选择的视频采集设备信息。 +* @since V4.6.20 +* @par 使用前提 +* 请在通过 \ref IVideoDeviceManager::setDevice "setDevice" 接口设置视频采集设备后调用该方法，否则返回空。 +* @par 调用时机 +* 请在初始化后调用该方法。 +* @note +* 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。 +* @par 参数说明 +* +* +* +* +* +* +* +* +* +* +* +* +* +* +* +* +*
**参数名称****类型****描述**
device_idconst char [kNERtcMaxDeviceIDLength]视频采集设备的设备 ID。可以通过 \ref IVideoDeviceManager::enumerateCaptureDevices "enumerateCaptureDevices" +* 接口获取。
typesee #NERtcVideoStreamType视频通道类型：
  • kNERTCVideoStreamMain（默认）：主流。
  • kNERTCVideoStreamSub：辅流。
+* @par 示例代码 +* @code +* //获取主流视频通道的设备信息 +* std::string device_id = "\\?\usb#vid_046d&pid_081b&mi_00#7&1f6973a&0&0000#{65e8773d-8f56-11d0-a3b9-00a0c9223196}\global"; // +* 可以通过 IVideoDeviceManager 接口获取device_id nertc::NERtcVideoStreamType type = +* nertc::NERtcVideoStreamType::kNERTCVideoStreamMain; setDevice(device_id.c_str(), type); +* //获取辅流通道的设备信息 +* std::string device_id = "\\?\usb#vid_046d&pid_081b&mi_00#7&1f6973a&0&0000#{65e8773d-8f56-11d0-a3b9-00a0c9223196}\global"; // +* 可以通过 IVideoDeviceManager 接口获取device_id nertc::NERtcVideoStreamType type = +* nertc::NERtcVideoStreamType::kNERTCVideoStreamSub setDevice(device_id.c_str(), type); +* @endcode +* @return +* - 0（kNERtcNoError）：方法调用成功。 +* - 其他：方法调用失败。 +* - 30004（kNERtcErrNotSupported）：不支持的操作，比如使用的是纯音频 SDK。 +* @endif +*/ +NERTC_API int NERTC_CALL nertc_video_device_manager_get_device(struct nertc_video_device_manager* self, nertc_video_stream_type type, char* device_id); + +NERTC_END_DECLS + +#endif // NERTC_VIDEO_MANAGER_H diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_warn_code.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_warn_code.h new file mode 100644 index 0000000..0b0b5e1 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Plugins/NertcPlugin/Source/ThirdParty/Nertc/api/nertc_warn_code.h @@ -0,0 +1,51 @@ + +#ifndef NERTC_WARN_CODE_H +#define NERTC_WARN_CODE_H + +#include "nertc_engine_defines.h" + +/** + * @if English + * Warning code. + * If the warning code occurs, the SDK reports an error that is likely to be solved. The warning code just informs you of the + * SDK status. In most cases, the application programs can pass the warning code. + * @endif + * @if Chinese + * 警告代码。 + * 警告代码意味着 SDK 遇到问题，但有可能恢复，警告代码仅起告知作用，一般情况下应用程序可以忽略警告代码。 + * @endif + */ +typedef enum +{ + /** + * @if English + * No warning. + * @endif + * @if Chinese + * 未发生警告。 + * @endif + */ + kLiteSDKNoWarning = 0, + /** + * @if English + * The Client has no capability of device encoding and decoding to match that of the channel. For example, the device cannot encode in VP8 and other formats. Therefore, you may cannot implement video encoding and decoding in the channel. The local side may cannot display some remote video screens and the remote side may cannot display local screens. + * @endif + * @if Chinese + * 当前客户端设备视频编解码能力与房间不匹配，例如设备不支持 VP8 等编码类型。在此房间中可能无法成功进行视频编解码，即本端可能无法正常显示某些远端的视频画面，同样远端也可能无法显示本端画面。 + * @endif + */ + kNERtcWarningChannelAbilityNotMatch = 406, + /** + * @if English + * audio asl fallback + * @endif + * @if Chinese + * 音频自动选路回退 + * @endif + */ + kNERtcWarningASLAudioFallback = 407, + + +} nertc_warn_code; + +#endif // ! NERTC_WARN_CODE_H diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Source/NertcSampleCode.Target.cs b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Source/NertcSampleCode.Target.cs new file mode 100644 index 0000000..8576c02 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Source/NertcSampleCode.Target.cs @@ -0,0 +1,14 @@ +// Copyright Epic Games, Inc. All Rights Reserved. + +using UnrealBuildTool; +using System.Collections.Generic; + +public class NertcSampleCodeTarget : TargetRules +{ + public NertcSampleCodeTarget( TargetInfo Target) : base(Target) + { + Type = TargetType.Game; + DefaultBuildSettings = BuildSettingsVersion.V2; + ExtraModuleNames.AddRange( new string[] { "NertcSampleCode" } ); + } +} diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Source/NertcSampleCode/NertcSampleCode.Build.cs b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Source/NertcSampleCode/NertcSampleCode.Build.cs new file mode 100644 index 0000000..633b587 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Source/NertcSampleCode/NertcSampleCode.Build.cs @@ -0,0 +1,23 @@ +// Copyright Epic Games, Inc. All Rights Reserved. + +using UnrealBuildTool; + +public class NertcSampleCode : ModuleRules +{ + public NertcSampleCode(ReadOnlyTargetRules Target) : base(Target) + { + PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs; + + PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore", "NertcPlugin" }); + + PrivateDependencyModuleNames.AddRange(new string[] { }); + + // Uncomment if you are using Slate UI + // PrivateDependencyModuleNames.AddRange(new string[] { "Slate", "SlateCore" }); + + // Uncomment if you are using online features + // PrivateDependencyModuleNames.Add("OnlineSubsystem"); + + // To include OnlineSubsystemSteam, add it to the plugins section in your uproject file with the Enabled attribute set to true + } +} diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Source/NertcSampleCode/NertcSampleCode.cpp b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Source/NertcSampleCode/NertcSampleCode.cpp new file mode 100644 index 0000000..2d521f6 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Source/NertcSampleCode/NertcSampleCode.cpp @@ -0,0 +1,6 @@ +// Copyright Epic Games, Inc. All Rights Reserved. + +#include "NertcSampleCode.h" +#include "Modules/ModuleManager.h" + +IMPLEMENT_PRIMARY_GAME_MODULE( FDefaultGameModuleImpl, NertcSampleCode, "NertcSampleCode" ); diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Source/NertcSampleCode/NertcSampleCode.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Source/NertcSampleCode/NertcSampleCode.h new file mode 100644 index 0000000..73cb863 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Source/NertcSampleCode/NertcSampleCode.h @@ -0,0 +1,6 @@ +// Copyright Epic Games, Inc. All Rights Reserved. + +#pragma once + +#include "CoreMinimal.h" + diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Source/NertcSampleCode/NertcSampleCodeGameModeBase.cpp b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Source/NertcSampleCode/NertcSampleCodeGameModeBase.cpp new file mode 100644 index 0000000..764f4d3 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Source/NertcSampleCode/NertcSampleCodeGameModeBase.cpp @@ -0,0 +1,5 @@ +// Copyright Epic Games, Inc. All Rights Reserved. + + +#include "NertcSampleCodeGameModeBase.h" + diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Source/NertcSampleCode/NertcSampleCodeGameModeBase.h b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Source/NertcSampleCode/NertcSampleCodeGameModeBase.h new file mode 100644 index 0000000..cc34b12 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Source/NertcSampleCode/NertcSampleCodeGameModeBase.h @@ -0,0 +1,17 @@ +// Copyright Epic Games, Inc. All Rights Reserved. + +#pragma once + +#include "CoreMinimal.h" +#include "GameFramework/GameModeBase.h" +#include "NertcSampleCodeGameModeBase.generated.h" + +/** + * + */ +UCLASS() +class NERTCSAMPLECODE_API ANertcSampleCodeGameModeBase : public AGameModeBase +{ + GENERATED_BODY() + +}; diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Source/NertcSampleCode/NertcUserWidget.cpp b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Source/NertcSampleCode/NertcUserWidget.cpp new file mode 100644 index 0000000..d47ca08 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Source/NertcSampleCode/NertcUserWidget.cpp @@ -0,0 +1,81 @@ +// Fill out your copyright notice in the Description page of Project Settings. + + +#include "NertcUserWidget.h" +#include + +const std::string g_appKey = "your appkey"; +const std::string g_logPath = "your log path"; +const std::string g_channelName = "your channel name"; +const uint64_t g_userID = 123; //your userID + +void UNertcUserWidget::NativeConstruct() +{ + Super::NativeConstruct(); + InitNertcEngine(g_appKey, g_logPath); +} + +void UNertcUserWidget::NativeDestruct() { + ReleaseNertcEngine(); + Super::NativeDestruct(); +} + +void UNertcUserWidget::InitNertcEngine(std::string appKey, std::string logPath) { + nertc_engine_ = nertc::createNERtcEngine(); + + if (!nertc_engine_) + return; + + nertc::NERtcEngineContext context{}; + context.app_key = appKey.c_str(); + //¼صȷYourProjectClass̳IRtcEngineEventHandler + context.event_handler = this; + context.log_dir_path = logPath.c_str(); + context.log_level = kNERtcLogLevelInfo; + + auto ret = nertc_engine_->initialize(context); + if (ret != 0) { + ReleaseNertcEngine(); + return; + } + + //ϷģʽøõƵ ѡ + nertc_engine_->setParameters("{\"sdk.enable.plugin.game.mode\":true}"); + + //ȡƵmanagerڲٿƵ豸 ѡ + nertc_engine_->queryInterface(nertc::kNERtcIIDAudioDeviceManager, (void**)(&audio_device_manager_)); + if (!audio_device_manager_) { + return; + } + + //ý״̬صȷYourProjectClass̳IRtcMediaStatsObserver ѡ + nertc_engine_->setStatsObserver(this); +} +void UNertcUserWidget::ReleaseNertcEngine() { + if (!nertc_engine_) + return; + nertc_engine_->release(); + delete nertc_engine_; + nertc_engine_ = nullptr; +} +void UNertcUserWidget::OnJoinChannelClicked() { + nertc_engine_->joinChannel("", g_channelName.c_str(), g_userID, NERtcJoinChannelOptions{}); +} + +void UNertcUserWidget::OnLeaveChannelClicked() { + nertc_engine_->leaveChannel(); +} + +void UNertcUserWidget::onJoinChannel(channel_id_t cid, nertc::uid_t uid, NERtcErrorCode result, uint64_t elapsed) { + std::cout << "onJoinChannel"< +#include "NertcUserWidget.generated.h" + +/** + * + */ +using namespace nertc; +UCLASS() +class NERTCSAMPLECODE_API UNertcUserWidget : public UUserWidget, public IRtcEngineEventHandler, public IRtcMediaStatsObserver +{ + GENERATED_BODY() +public: + void NativeConstruct() override; + void NativeDestruct() override; + + void InitNertcEngine(std::string appKey, std::string logPath); + void ReleaseNertcEngine(); + + UFUNCTION(BlueprintCallable) + void OnJoinChannelClicked(); + + UFUNCTION(BlueprintCallable) + void OnLeaveChannelClicked(); + +public: + //дonJoinChannel麯joinChannelSDKԶøú֪ͨ + void onJoinChannel(channel_id_t cid, nertc::uid_t uid, NERtcErrorCode result, uint64_t elapsed) override; + //дonConnectionStateChange麯״̬ʱSDKԶøú + void onConnectionStateChange(NERtcConnectionStateType state, NERtcReasonConnectionChangedType reason)override; + //дonLeaveChannel麯뿪SDKԶøú + void onLeaveChannel(NERtcErrorCode result, uint64_t channel_id) override; + //setStatsObserver֮SDKᶨڻصonRtcStatsSDKڲݣCPUʹʵȣ֪ͨ + void onRtcStats(const NERtcStats& stats) override; + +private: + //SDKָ + nertc::IRtcEngineEx* nertc_engine_; + //Ƶ豸ָ + nertc::IAudioDeviceManager* audio_device_manager_; +}; diff --git a/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Source/NertcSampleCodeEditor.Target.cs b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Source/NertcSampleCodeEditor.Target.cs new file mode 100644 index 0000000..91b5452 --- /dev/null +++ b/One-to-One-Video/NERtcSample-1to1-Windows-Unreal/Source/NertcSampleCodeEditor.Target.cs @@ -0,0 +1,14 @@ +// Copyright Epic Games, Inc. All Rights Reserved. + +using UnrealBuildTool; +using System.Collections.Generic; + +public class NertcSampleCodeEditorTarget : TargetRules +{ + public NertcSampleCodeEditorTarget( TargetInfo Target) : base(Target) + { + Type = TargetType.Editor; + DefaultBuildSettings = BuildSettingsVersion.V2; + ExtraModuleNames.AddRange( new string[] { "NertcSampleCode" } ); + } +}