diff --git a/HHVDoctorSDK.podspec b/HHVDoctorSDK.podspec
index c2f140a..a6e0543 100644
--- a/HHVDoctorSDK.podspec
+++ b/HHVDoctorSDK.podspec
@@ -1,6 +1,6 @@
Pod::Spec.new do |s|
s.name = "HHVDoctorSDK"
- s.version = "3.1.4.081015"
+ s.version = "3.1.4.081216"
s.summary = "和缓视频医生 SDK"
s.description = <<-DESC
diff --git a/HHVDoctorSDK/.DS_Store b/HHVDoctorSDK/.DS_Store
index 18f45f9..5cb814d 100644
Binary files a/HHVDoctorSDK/.DS_Store and b/HHVDoctorSDK/.DS_Store differ
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/ITRTCAudioPacketListener.h b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/ITRTCAudioPacketListener.h
new file mode 100644
index 0000000..f20fec9
--- /dev/null
+++ b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/ITRTCAudioPacketListener.h
@@ -0,0 +1,30 @@
+/*
+* Module: 网络音频包UDT自定义数据回调
+*
+* Function: 给客户回调发送前、接收后的 UDT 自定义数据
+*
+*/
+#ifndef LITEAV_ITRTCAUDIOPACKETLISTENER_H
+#define LITEAV_ITRTCAUDIOPACKETLISTENER_H
+
+#include <stdio.h>
+#include "TXLiteAVBuffer.h"
+
+namespace liteav {
+ struct TRTCAudioPacket {
+ const char *userId;
+ liteav::TXLiteAVBuffer* extraData;
+ };
+
+ class ITRTCAudioPacketListener {
+ public:
+ virtual ~ITRTCAudioPacketListener() {}
+ /*网络层接收到音频数据包*/
+ virtual bool onRecvAudioPacket(TRTCAudioPacket &data) { return false; }
+ /*网络层即将发送的音频数据包*/
+ virtual bool onSendAudioPacket(TRTCAudioPacket &data) { return false; }
+ };
+}
+
+
+#endif //LITEAV_ITRTCAUDIOPACKETLISTENER_H
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TRTCCloud.h b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TRTCCloud.h
index 0e3a2f0..9a15658 100644
--- a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TRTCCloud.h
+++ b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TRTCCloud.h
@@ -1,11 +1,8 @@
-/*
+/**
* Module: TRTCCloud @ TXLiteAVSDK
- *
- * Function: 腾讯云视频通话功能的主要接口类
- *
- * Version: 8.6.10094
+ * Function: 腾讯云 TRTC 主功能接口
+ * Version: 9.0.10433
*/
-
#import <Foundation/Foundation.h>
#import <VideoToolbox/VideoToolbox.h>
#import "TRTCCloudDelegate.h"
@@ -15,1264 +12,1236 @@
#import "TXDeviceManager.h"
/// @defgroup TRTCCloud_ios TRTCCloud
-/// 腾讯云视频通话功能的主要接口类
+/// 腾讯云 TRTC 主功能接口
/// @{
@interface TRTCCloud : NSObject
-// 请使用 +sharedIntance 方法
-+ (instancetype)new __attribute__((unavailable("Use +sharedInstance instead")));
++ (instancetype)new __attribute__((unavailable("Use +sharedInstance instead")));
- (instancetype)init __attribute__((unavailable("Use +sharedInstance instead")));
-
/////////////////////////////////////////////////////////////////////////////////
//
-// SDK 基础函数
+// 创建实例和事件回调
//
/////////////////////////////////////////////////////////////////////////////////
-
-/// @name 创建与销毁
+/// @name 创建实例和事件回调
/// @{
/**
-* 创建 TRTCCloud 单例
-*/
+ * 1.1 创建 TRTCCloud 实例（单例模式）
+ */
+ (instancetype)sharedInstance;
/**
-* 销毁 TRTCCloud 单例
-*/
+ * 1.2 销毁 TRTCCloud 实例（单例模式）
+ */
+ (void)destroySharedIntance;
/**
-* 设置回调接口 TRTCCloudDelegate
-*
-* 您可以通过 TRTCCloudDelegate 获得来自 SDK 的各种状态通知，详见 TRTCCloudDelegate.h 中的定义
-*/
-@property (nonatomic, weak) id<TRTCCloudDelegate> delegate;
+ * 1.3 设置 TRTC 事件回调
+ *
+ * 您可以通过 {@link TRTCCloudDelegate} 获得来自 SDK 的各类事件通知（比如：错误码，警告码，音视频状态参数等）。
+ */
+@property(nonatomic, weak) id<TRTCCloudDelegate> delegate;
/**
-* 设置驱动 TRTCCloudDelegate 回调的队列
-*
-* SDK 默认会采用 Main Queue 作为驱动 TRTCCloudDelegate。如果您不指定自己的 delegateQueue，
-* SDK 的 TRTCCloudDelegate 回调都将由 Main Queue 来调用。此时您在 TRTCCloudDelegate 的回调函数里操作 UI 是线程安全的。
-*/
-@property (nonatomic, strong) dispatch_queue_t delegateQueue;
+ * 1.4 设置驱动 TRTCCloudDelegate 事件回调的队列
+ *
+ * 如果您不指定自己的 delegateQueue，SDK 默认会采用 MainQueue 作为驱动 {@link TRTCCloudDelegate} 事件回调的队列。
+ * 也就是当您不设置 delegateQueue 属性时，{@link TRTCCloudDelegate} 中的所有回调函数都是由 MainQueue 来驱动的。
+ * @note 如果您指定了自己的 delegateQueue，请不要在 {@link TRTCCloudDelegate} 回调函数中操作 UI，否则会引发线程安全问题。
+ */
+@property(nonatomic, strong) dispatch_queue_t delegateQueue;
/// @}
-
/////////////////////////////////////////////////////////////////////////////////
//
-// （一）房间相关接口函数
+// 房间相关接口函数
//
/////////////////////////////////////////////////////////////////////////////////
-#pragma mark - 房间相关接口函数
/// @name 房间相关接口函数
/// @{
/**
- * 1.1 进入房间
+ * 2.1 进入房间
*
- * 调用接口后，您会收到来自 TRTCCloudDelegate 中的 onEnterRoom(result) 回调:
- * - 如果加入成功，result 会是一个正数（result > 0），表示加入房间的时间消耗，单位是毫秒（ms）。
- * - 如果加入失败，result 会是一个负数（result < 0），表示进房失败的错误码。
+ * TRTC 的所有用户都需要进入房间才能“发布”或“订阅”音视频流，“发布”是指将自己的音频和视频推送到云端，“订阅”是指从云端拉取房间里其他用户的音视频流。
+ * 调用该接口时，您需要指定您的应用场景 {@link TRTCAppScene} 以获取最佳的音视频传输体验，这些场景可以分成两大类：
*
- * 进房失败的错误码含义请参见[错误码](https://cloud.tencent.com/document/product/647/32257)。
+ * 【直播场景（Live）】
+ * - 包括 {@link TRTCAppSceneLIVE} 和 {@link TRTCAppSceneVoiceChatRoom}：
+ * - 此类场景下，每一个房间最多同时容纳 10 万人，但需要您通过 {@link TRTCParams} 中的 “role” 字段设定用户是“主播”（{@link TRTCRoleAnchor}）还是“观众”（{@link TRTCRoleAudience}）。
+ * - 主播可以“发布”自己的音视频流，观众只能“订阅”别人的音视频流，每一个用户都可以在主播和观众两种角色间通过 {@link switchRole} 接口进行切换。
+ * - 适用于[视频低延时直播]、[十万人互动课堂]、[直播PK]、[音乐直播间]、[在线K歌]、[远程培训]、[超大型会议]等业务形态。
*
- * - 【视频通话】{@link TRTCAppSceneVideoCall}：<br>
- * 能力：支持720P、1080P高清画质，单个房间最多支持300人同时在线，最高支持50人同时发言。<br>
- * 适用：[1对1视频通话]、[300人视频会议]、[在线问诊]、[视频聊天]、[远程面试]等。<br>
- * - 【语音通话】{@link TRTCAppSceneAudioCall}：<br>
- * 能力：支持 48kHz，支持双声道。单个房间最多支持300人同时在线，最高支持50人同时发言。<br>
- * 适用：[[1对1语音通话]、[300人语音会议]、[语音聊天]、[语音会议]、[在线狼人杀]等。<br>
- * - 【连麦直播】{@link TRTCAppSceneLIVE}：<br>
- * 能力：支持平滑上下麦，切换过程无需等待，主播延时小于300ms；支持十万级别观众同时播放，播放延时低至1000ms。<br>
- * 适用：[视频低延时直播]、[十万人互动课堂]、[视频直播 PK]、[视频相亲房]、[互动课堂]、[远程培训]、[超大型会议]等。<br>
- * - 【语聊房】{@link TRTCAppSceneVoiceChatRoom}：<br>
- * 能力：支持平滑上下麦，切换过程无需等待，主播延时小于300ms；支持十万级别观众同时播放，播放延时低至1000ms。<br>
- * 适用：[语聊房]、[语音直播连麦]、[K 歌房]、[FM 电台]等。<br>
+ * 【实时场景（RTC）】
+ * - 包括 {@link TRTCAppSceneVideoCall} 和 {@link TRTCAppSceneAudioCall}：
+ * - 此类场景下，每一个房间最多同时容纳 300 人在线，最高支持 50 人同时发言。
+ * - 适用于 [1对1视频通话]、[300人视频会议]、[在线问诊]、[语音聊天]、[教育小班课]、[远程面试]、[在线狼人杀]等业务形态。
*
- * @param param 进房参数，请参考 TRTCParams
- * @param scene 应用场景，目前支持视频通话（VideoCall）、连麦直播（Live）、语音通话（AudioCall）、语聊房（VoiceChatRoom）四种场景。
+ * 调用该接口后，您会收到来自 {@link TRTCCloudDelegate} 中的 onEnterRoom(result) 回调:
+ * - 如果进房成功，参数 result 会是一个正数（result > 0），表示从函数调用到进入房间所花费的时间，单位是毫秒（ms）。
+ * - 如果进房失败，参数 result 会是一个负数（result < 0），表示进房失败的[错误码](https://cloud.tencent.com/document/product/647/32257)。
*
+ * @param param 进房参数，用于指定用户的身份、角色和安全票据等信息，详情请参考 {@link TRTCParams} 。
+ * @param scene 应用场景，用于指定您的业务场景，同一个房间内的所有用户需要设定相同的 {@link TRTCAppScene}。
* @note
- * 1. 当 scene 选择为 TRTCAppSceneLIVE 或 TRTCAppSceneVoiceChatRoom 时，您必须通过 TRTCParams 中的 role 字段指定当前用户的角色。<br>
- * 2. 不管进房是否成功，enterRoom 都必须与 exitRoom 配对使用，在调用 exitRoom 前再次调用 enterRoom 函数会导致不可预期的错误问题。
+ * 1. 同一个房间内的所有用户需要设定相同的 scene。不同的 scene 会导致偶现的异常问题。
+ * 2. 当您指定参数 scene 为 {@link TRTCAppSceneLIVE} 或 {@link TRTCAppSceneVoiceChatRoom} 时，您必须通过 {@link TRTCParams} 中的 “role” 字段为当前用户设定他/她在房间中的角色。
+ * 3. 请您尽量保证 {@link enterRoom} 与 {@link exitRoom} 前后配对使用，即保证”先退出前一个房间再进入下一个房间”，否则会导致很多异常问题。
*/
- (void)enterRoom:(TRTCParams *)param appScene:(TRTCAppScene)scene;
/**
- * 1.2 离开房间
- *
- * 调用 exitRoom() 接口会执行退出房间的相关逻辑，例如释放音视频设备资源和编解码器资源等。
- * 待资源释放完毕，SDK 会通过 TRTCCloudDelegate 中的 onExitRoom() 回调通知到您。
+ * 2.2 离开房间
*
- * 如果您要再次调用 enterRoom() 或者切换到其他的音视频 SDK，请等待 onExitRoom() 回调到来之后再执行相关操作。
- * 否则可能会遇到摄像头或麦克风（例如 iOS 里的 AudioSession）被占用等各种异常问题。
+ * 调用该接口会让用户离开自己所在的音视频房间，并释放摄像头、麦克风、扬声器等设备资源。
+ * 等资源释放完毕之后，SDK 会通过 {@link TRTCCloudDelegate} 中的 onExitRoom() 回调向您通知。
+ * 如果您要再次调用 {@link enterRoom} 或者切换到其他的供应商的 SDK，建议等待 onExitRoom() 回调到来之后再执行之后的操作，以避免摄像头或麦克风被占用的问题。
*/
- (void)exitRoom;
-
/**
- * 1.3 切换角色，仅适用于直播场景（TRTCAppSceneLIVE 和 TRTCAppSceneVoiceChatRoom）
- *
- * 在直播场景下，一个用户可能需要在“观众”和“主播”之间来回切换。
- * 您可以在进房前通过 TRTCParams 中的 role 字段确定角色，也可以通过 switchRole 在进房后切换角色。
+ * 2.3 切换角色
*
- * @param role 目标角色，默认为主播：
- * - {@link TRTCRoleAnchor} 主播，可以上行视频和音频，一个房间里最多支持50个主播同时上行音视频。
- * - {@link TRTCRoleAudience} 观众，只能观看，不能上行视频和音频，一个房间里的观众人数没有上限。
+ * 调用本接口可以实现用户在“主播”和“观众”两种角色之间来回切换。
+ * 由于视频直播和语音聊天室需要支持多达10万名观众同时观看，所以设定了“只有主播才能发布自己的音视频”的规则。
+ * 因此，当有些观众希望发布自己的音视频流（以便能跟主播互动）时，就需要先把自己的角色切换成“主播”。
+ * 您可以在进入房间时通过 {@link TRTCParams} 中的 role 字段事先确定用户的角色，也可以在进入房间后通过 switchRole 接口动态切换角色。
+ * @param role 角色，默认为“主播”：
+ * - {@link TRTCRoleAnchor} ：主播，可以发布自己的音视频，同一个房间里最多支持50个主播同时发布音视频。
+ * - {@link TRTCRoleAudience} ：观众，不能发布自己的音视频流，只能观看房间中其他主播的音视频。如果要发布自己的音视频，需要先通过 {@link switchRole} 切换成“主播”，同一个房间内同时最多可以容纳 10 万名观众。
+ * @note
+ * 1. 该接口仅适用于视频直播（{@link TRTCAppSceneLIVE}）和语音聊天室（{@link TRTCAppSceneVoiceChatRoom}）这两个场景。
+ * 2. 如果您在 {@link enterRoom} 时指定的 scene 为 {@link TRTCAppSceneVideoCall} 或 {@link TRTCAppSceneAudioCall}，请不要调用这个接口。
*/
--(void)switchRole:(TRTCRoleType)role;
-
+- (void)switchRole:(TRTCRoleType)role;
/**
- * 1.4 请求跨房通话（主播 PK）
+ * 2.4 切换房间
*
- * TRTC 中两个不同音视频房间中的主播，可以通过“跨房通话”功能拉通连麦通话功能。使用此功能时，
- * 两个主播无需退出各自原来的直播间即可进行“连麦 PK”。
+ * 使用该接口可以让用户可以快速从一个房间切换到另一个房间。
+ * - 如果用户的身份是“观众”，该接口的调用效果等同于 exitRoom(当前房间) + enterRoom（新的房间）。
+ * - 如果用户的身份是“主播”，该接口在切换房间的同时还会保持自己的音视频发布状态，因此在房间切换过程中，摄像头的预览和声音的采集都不会中断。
*
- * 例如：当房间“001”中的主播 A 通过 connectOtherRoom() 跟房间“002”中的主播 B 拉通跨房通话后，
- * 房间“001”中的用户都会收到主播 B 的 onUserEnter(B) 回调和 onUserVideoAvailable(B,YES) 回调。
- * 房间“002”中的用户都会收到主播 A 的 onUserEnter(A) 回调和 onUserVideoAvailable(A,YES) 回调。
+ * 该接口适用于在线教育场景中，监课老师在多个房间中进行快速切换的场景。在该场景下使用 switchRoom 可以获得比 exitRoom+enterRoom 更好的流畅性和更少的代码量。
+ * 接口调用结果会通过 {@link TRTCCloudDelegate} 中的 onSwitchRoom(errCode, errMsg) 回调。
*
- * 简言之，跨房通话的本质，就是把两个不同房间中的主播相互分享，让每个房间里的观众都能看到两个主播。
+ * @param config 房间参数，详情请参考 {@link TRTCSwitchRoomConfig} 。
+ * @note 由于对老版本 SDK 兼容的需求，参数 config 中同时包含 roomId 与 strRoomId 两个参数，这两个参数的填写格外讲究，请注意如下事项：
+ * 1. 若您选用 strRoomId，则 roomId 需要填写为0。若两者都填，将优先选用 roomId。
+ * 2. 所有房间需要同时使用 strRoomId 或同时使用 roomId，不可混用，否则将会出现很多预期之外的 bug。
+ */
+- (void)switchRoom:(TRTCSwitchRoomConfig *)config;
+
+/**
+ * 2.5 请求跨房通话
+ *
+ * 默认情况下，只有同一个房间中的用户之间可以进行音视频通话，不同的房间之间的音视频流是相互隔离的。
+ * 但您可以通过调用该接口，将另一个房间中某个主播音视频流发布到自己所在的房间中，与此同时，该接口也会将自己的音视频流发布到目标主播的房间中。
+ * 也就是说，您可以使用该接口让身处两个不同房间中的主播进行跨房间的音视频流分享，从而让每个房间中的观众都能观看到这两个主播的音视频。该功能可以用来实现主播之间的 PK 功能。
+ * 跨房通话的请求结果会通过 {@link TRTCCloudDelegate} 中的 onConnectOtherRoom() 回调通知给您。
+ * 例如：当房间“101”中的主播 A 通过 connectOtherRoom() 跟房间“102”中的主播 B 建立跨房通话后，
+ * - 房间“101”中的用户都会收到主播 B 的 onRemoteUserEnterRoom(B) 和 onUserVideoAvailable(B,YES) 这两个事件回调，即房间“101”中的用户都可以订阅主播 B 的音视频。
+ * - 房间“102”中的用户都会收到主播 A 的 onRemoteUserEnterRoom(A) 和 onUserVideoAvailable(A,YES) 这两个事件回调，即房间“102”中的用户都可以订阅主播 A 的音视频。
*
* <pre>
- * 房间 001 房间 002
+ * 房间 101 房间 102
* ------------- ------------
* 跨房通话前：| 主播 A | | 主播 B |
* | 观众 U V W | | 观众 X Y Z |
* ------------- ------------
*
- * 房间 001 房间 002
+ * 房间 101 房间 102
* ------------- ------------
* 跨房通话后：| 主播 A B | | 主播 B A |
* | 观众 U V W | | 观众 X Y Z |
* ------------- ------------
* </pre>
+ * 跨房通话的参数考虑到后续扩展字段的兼容性问题，暂时采用了 JSON 格式的参数：
*
- * 跨房通话的参数考虑到后续扩展字段的兼容性问题，暂时采用了 JSON 格式的参数，要求至少包含两个字段：
- * - roomId：房间“001”中的主播 A 要跟房间“002”中的主播 B 连麦，主播 A 调用 connectOtherRoom() 时 roomId 应指定为“002”。
- * - userId：房间“001”中的主播 A 要跟房间“002”中的主播 B 连麦，主播 A 调用 connectOtherRoom() 时 userId 应指定为 B 的 userId。
- *
- * 跨房通话的请求结果会通过 TRTCCloudDelegate 中的 onConnectOtherRoom() 回调通知给您。
- *
+ * 【情况一：数字房间号】
+ * 如果房间“101”中的主播 A 要跟房间“102”中的主播 B 连麦，那么主播 A 调用该接口时需要传入：{"roomId": 102, "userId": "userB"}
+ * 示例代码如下：
* <pre>
- * NSMutableDictionary * jsonDict = [[NSMutableDictionary alloc] init];
- * [jsonDict setObject:@(002) forKey:@"roomId"];
+ * NSMutableDictionaryjsonDict = [[NSMutableDictionary alloc] init];
+ * [jsonDict setObject:@(102) forKey:@"roomId"];
* [jsonDict setObject:@"userB" forKey:@"userId"];
* NSData* jsonData = [NSJSONSerialization dataWithJSONObject:jsonDict options:NSJSONWritingPrettyPrinted error:nil];
* NSString* jsonString = [[NSString alloc] initWithData:jsonData encoding:NSUTF8StringEncoding];
* [trtc connectOtherRoom:jsonString];
* </pre>
*
- * @param param JSON 字符串连麦参数，roomId 代表目标房间号，userId 代表目标用户 ID。
+ * 【情况二：字符串房间号】
+ * 如果您使用的是字符串房间号，务必请将 json 中的 “roomId” 替换成 “strRoomId”: {"strRoomId": "102", "userId": "userB"}
+ * 示例代码如下：
+ * <pre>
+ * NSMutableDictionaryjsonDict = [[NSMutableDictionary alloc] init];
+ * [jsonDict setObject:@"102" forKey:@"strRoomId"];
+ * [jsonDict setObject:@"userB" forKey:@"userId"];
+ * NSData* jsonData = [NSJSONSerialization dataWithJSONObject:jsonDict options:NSJSONWritingPrettyPrinted error:nil];
+ * NSString* jsonString = [[NSString alloc] initWithData:jsonData encoding:NSUTF8StringEncoding];
+ * [trtc connectOtherRoom:jsonString];
+ * </pre>
*
- **/
+ * @param param 需要你传入 JSON 格式的字符串参数，roomId 代表数字格式的房间号，strRoomId 代表字符串格式的房间号，userId 代表目标主播的用户ID。
+ */
- (void)connectOtherRoom:(NSString *)param;
/**
- * 1.5 退出跨房通话
+ * 2.6 退出跨房通话
*
- * 跨房通话的退出结果会通过 TRTCCloudDelegate 中的 onDisconnectOtherRoom() 回调通知给您。
- **/
+ * 退出结果会通过 {@link TRTCCloudDelegate} 中的 onDisconnectOtherRoom() 回调通知给您。
+ */
- (void)disconnectOtherRoom;
/**
- * 1.6 设置音视频数据接收模式，需要在进房前设置才能生效
- *
- * 为实现进房秒开的绝佳体验，SDK 默认进房后自动接收音视频。即在您进房成功的同时，您将立刻收到远端所有用户的音视频数据。
- * 若您没有调用 startRemoteView，视频数据将自动超时取消。
- * 若您主要用于语音聊天等没有自动接收视频数据需求的场景，您可以根据实际需求选择接收模式，以免产生预期之外的视频时长费用。
+ * 2.7 设置订阅模式（需要在进入房前设置才能生效）
*
- * @param autoRecvAudio YES：自动接收音频数据；NO：需要调用 muteRemoteAudio 进行请求或取消。默认值：YES
- * @param autoRecvVideo YES：自动接收视频数据；NO：需要调用 startRemoteView/stopRemoteView 进行请求或取消。默认值：YES
+ * 您可以通过该接口在“自动订阅”和“手动订阅”两种模式下进行切换：
+ * - 自动订阅：默认模式，用户在进入房间后会立刻接收到该房间中的音视频流，音频会自动播放，视频会自动开始解码（依然需要您通过 startRemoteView 接口绑定渲染控件）。
+ * - 手动订阅：在用户进入房间后，需要手动调用 {@startRemoteView} 接口才能启动视频流的订阅和解码，需要手动调用 {@muteRemoteAudio} (false) 接口才能启动声音的播放。
*
- * @note 需要在进房前设置才能生效。
- **/
+ * 在绝大多数场景下，用户进入房间后都会订阅房间中所有主播的音视频流，因此 TRTC 默认采用了自动订阅模式，以求得最佳的“秒开体验”。
+ * 如果您的应用场景中每个房间同时会有很多路音视频流在发布，而每个用户只想选择性地订阅其中的 1-2 路，则推荐使用“手动订阅”模式以节省流量费用。
+ * @param autoRecvAudio YES：自动订阅音频；NO：需手动调用 muteRemoteAudio(false) 订阅音频。默认值：YES。
+ * @param autoRecvVideo YES：自动订阅视频；NO：需手动调用 startRemoteView 订阅视频。默认值：YES。
+ * @note
+ * 1. 需要在进入房间（enterRoom）前调用该接口，设置才能生效。
+ * 2. 在自动订阅模式下，如果用户在进入房间后没有调用 {@startRemoteView} 订阅视频流，SDK 会自动停止订阅视频流，以便达到节省流量的目的。
+ */
- (void)setDefaultStreamRecvMode:(BOOL)autoRecvAudio video:(BOOL)autoRecvVideo;
/**
-* 1.7 创建子 TRTCCloud 实例
-*
-* 子 TRTCCloud 实例用于进入其他房间，观看其他房间主播的音视频流，还可以在不同的房间之间切换推送音视频流。
-*
-* 此接口主要应用于类似超级小班课这种需要进入多个房间推拉流的场景。
-*
-* <pre>
-* TRTCCloud *mainCloud = [TRTCCloud sharedInstance];
-* // 1、mainCloud 进房并开始推送音视频流。
-* // 2、创建子 TRTCCloud 实例并进入其他房间。
-* TRTCCloud *subCloud = [mainCloud createSubCloud];
-* [subCloud enterRoom:params appScene:scene)];
-*
-* // 3、切换房间推送音视频流。
-* // 3.1、mainCloud 停止推送音视频流。
-* [mainCloud switchRole:TRTCRoleAudience];
-* [mainCloud muteLocalVideo:true];
-* [mainCloud muteLocalAudio:true];
-* // 3.2、subCLoud 推送音视频流。
-* [subCloud switchRole:TRTCRoleAnchor];
-* [subCloud muteLocalVideo:false];
-* [subCloud muteLocalAudio:false];
-*
-* // 4、subCLoud 退房。
-* [subCloud exitRoom];
-*
-* // 5、销毁 subCLoud。
-* [mainCloud destroySubCloud:subCloud];
-* </pre>
-*
-* @return 子 TRTCCloud 实例
-* @note
-* - 同一个用户，可以使用同一个 userId 进入多个不同 roomId 的房间。
-* - 两台手机不可以同时使用同一个 userId 进入同一个 roomId 的房间。
-* - 通过 createSubCloud 接口创建出来的子房间 TRTCCloud 实例有一个能力限制：不能调用子实例中与本地音视频
-* 相关的接口（除了 switchRole、muteLocalVideo 和 muteLocalAudio 之外）， 设置美颜等接口请使用
-* 原 TRTCCloud 实例对象。
-* - 同一个用户，同时只能在一个 TRTCCloud 实例中推流，在不同房间同时推流会引发云端的状态混乱，导致各种 bug。
-*/
-- (TRTCCloud *)createSubCloud;
-
-/**
- * 1.8 销毁子 TRTCCloud 实例
+ * 2.8 创建子房间示例（用于多房间并发观看）
+ *
+ * TRTCCloud 一开始被设计成单例模式，限制了多房间并发观看的能力。
+ * 通过调用该接口，您可以创建出多个 TRTCCloud 实例，以便同时进入多个不同的房间观看音视频流。
+ * 但需要注意的是，由于摄像头和麦克风还是只有一份，因此您只能同时在一个 TRTCCloud 实例中以“主播”的身份存在，也就是您只能同时在一个 TRTCCloud 实例中发布自己的音视频流。
+ * 该功能主要用于在线教育场景中一种被称为“超级小班课”的业务场景中，用于解决“每个 TRTC 的房间中最多只能有 50 人同时发布自己音视频流”的限制。
+ * 示例代码如下：
+ * <pre>
+ * TRTCCloud *mainCloud = [TRTCCloud sharedInstance];
+ * [mainCloud enterRoom:params1 appScene:TRTCAppSceneLIVE)];
+ * //...
+ * //Switch the role from "anchor" to "audience" in your own room
+ * [mainCloud switchRole:TRTCRoleAudience];
+ * [mainCloud muteLocalVideo:true];
+ * [mainCloud muteLocalAudio:true];
+ * //...
+ * //Use subcloud to enter another room and switch the role from "audience" to "anchor"
+ * TRTCCloud *subCloud = [mainCloud createSubCloud];
+ * [subCloud enterRoom:params2 appScene:TRTCAppSceneLIVE)];
+ * [subCloud switchRole:TRTCRoleAnchor];
+ * [subCloud muteLocalVideo:false];
+ * [subCloud muteLocalAudio:false];
+ * //...
+ * //Exit from new room and release it.
+ * [subCloud exitRoom];
+ * [mainCloud destroySubCloud:subCloud];
+ * </pre>
+ *
+ * @note
+ * - 同一个用户，可以使用同一个 userId 进入多个不同 roomId 的房间。
+ * - 两台不同的终端设备不可以同时使用同一个 userId 进入同一个 roomId 的房间。
+ * - 同一个用户，同时只能在一个 TRTCCloud 实例中推流，在不同房间同时推流会引发云端的状态混乱，导致各种 bug。
+ * - 通过 createSubCloud 接口创建出来的 TRTCCloud 实例有一个能力限制：不能调用子实例中与本地音视频相关的接口（除 switchRole、muteLocalVideo 和 muteLocalAudio 之外）， 设置美颜等接口请使用原 TRTCCloud 实例对象。
+ * @return 子 TRTCCloud 实例
*/
-- (void)destroySubCloud:(TRTCCloud *)subCloud;
+- (TRTCCloud *)createSubCloud;
/**
- * 1.9 切换房间
- *
- * 调用接口后，会退出原来的房间，并且停止原来房间的音视频数据发送和所有远端用户的音视频播放，但不会停止本地视频的预览。
- * 进入新房间成功后，会自动恢复原来的音视频数据发送状态。
+ * 2.9 销毁子房间示例
*
- * 接口调用结果会通过 TRTCCloudDelegate 中的 onSwitchRoom(errCode, errMsg) 回调。
+ * @param subCloud
*/
-- (void)switchRoom:(TRTCSwitchRoomConfig *)config;
-
-/// @}
+- (void)destroySubCloud:(TRTCCloud *)subCloud;
/////////////////////////////////////////////////////////////////////////////////
//
-// （二）CDN 相关接口函数
+// CDN 相关接口函数
//
/////////////////////////////////////////////////////////////////////////////////
-#pragma mark - CDN 相关接口函数
-
-/// @name CDN 相关接口函数
-/// @{
/**
- * 2.1 开始向腾讯云的直播 CDN 推流
- *
- * 该接口会指定当前用户的音视频流在腾讯云 CDN 所对应的 StreamId，进而可以指定当前用户的 CDN 播放地址。
+ * 3.1 开始向腾讯云直播 CDN 上发布音视频流
*
- * 例如：如果我们采用如下代码设置当前用户的主画面 StreamId 为 user_stream_001，那么该用户主画面对应的 CDN 播放地址为：
+ * 该接口会向 TRTC 服务器发送指令，要求其将当前用户的音视频流旁路到直播 CDN 上。
+ * 您可以通过参数 streamId 设定直播流的 StreamId，从而可以指定该用户的音视频流对应在直播 CDN 上的播放地址。
+ * 例如：您可以通过该接口将当前用户的直播流 ID 指定为 user_stream_001，那么该用户音视频流对应的 CDN 播放地址为：
* “http://yourdomain/live/user_stream_001.flv”，其中 yourdomain 为您自己备案的播放域名，
- * 您可以在直播[控制台](https://console.cloud.tencent.com/live) 配置您的播放域名，腾讯云不提供默认的播放域名。
- *
+ * 您可以在[直播控制台](https://console.cloud.tencent.com/live) 配置您的播放域名，腾讯云不提供默认的播放域名。
* <pre>
- * TRTCCloud *trtcCloud = [TRTCCloud sharedInstance];
- * [trtcCloud enterRoom:params appScene:TRTCAppSceneLIVE];
- * [trtcCloud startLocalPreview:frontCamera view:localView];
- * [trtcCloud startLocalAudio];
- * [trtcCloud startPublishing: @"user_stream_001" type:TRTCVideoStreamTypeBig];
- *
+ * TRTCCloud *trtcCloud = [TRTCCloud sharedInstance];
+ * [trtcCloud enterRoom:params appScene:TRTCAppSceneLIVE];
+ * [trtcCloud startLocalPreview:frontCamera view:localView];
+ * [trtcCloud startLocalAudio];
+ * [trtcCloud startPublishing: @"user_stream_001" type:TRTCVideoStreamTypeBig];
* </pre>
*
* 您也可以在设置 enterRoom 的参数 TRTCParams 时指定 streamId, 而且我们更推荐您采用这种方案。
- *
* @param streamId 自定义流 ID。
- * @param type 仅支持TRTCVideoStreamTypeBig 和 TRTCVideoStreamTypeSub。
- * @note 您需要先在实时音视频 [控制台](https://console.cloud.tencent.com/rav/) 中的功能配置页开启“启用旁路推流”才能生效。
- * - 若您选择“指定流旁路”，则您可以通过该接口将对应音视频流推送到腾讯云 CDN 且指定为填写的流 ID。
- * - 若您选择“全局自动旁路”，则您可以通过该接口调整默认的流 ID。
-*/
-- (void)startPublishing:(NSString *)streamId type:(TRTCVideoStreamType)type;
+ * @param streamType 仅支持 {@link TRTCVideoStreamTypeBig} 和 {@link TRTCVideoStreamTypeSub}。
+ * @note 您需要提前在 [实时音视频控制台](https://console.cloud.tencent.com/trtc/) 中的功能配置页面上开启“启用旁路推流”才能生效。
+ * - 若您选择“指定流旁路”，则您可以通过该接口将对应音视频流推送到腾讯云 CDN 且指定为填写的流 ID。
+ * - 若您选择“全局自动旁路”，则您可以通过该接口调整默认的流 ID。
+ */
+- (void)startPublishing:(NSString *)streamId type:(TRTCVideoStreamType)streamType;
/**
- * 2.2 停止向腾讯云的直播 CDN 推流
+ * 3.2 停止向腾讯云直播 CDN 上发布音视频流
*/
- (void)stopPublishing;
/**
- * 2.3 开始向友商云的直播 CDN 转推
+ * 3.3 开始向非腾讯云 CDN 上发布音视频流
*
- * 该接口跟 startPublishing() 类似，但 startPublishCDNStream() 支持向非腾讯云的直播 CDN 转推。
- * @param param CDN 转推参数，请参考 TRTCCloudDef.h 中关于 TRTCPublishCDNParam 的介绍。
- * @note 使用 startPublishing() 绑定腾讯云直播 CDN 不收取额外的费用，但使用 startPublishCDNStream() 绑定非腾讯云直播 CDN 需要收取转推费用。
+ * 该接口跟 startPublishing 功能类似，不同之处在于，startPublishing 仅支持向腾讯云的 CDN 发布，而本接口支持向非腾讯云的直播 CDN 上转推音视频流。
+ * @param param CDN 转推参数，详情请参考 {@link TRTCPublishCDNParam}
+ * @note
+ * - 使用 startPublishing 接口向腾讯云的直播 CDN 上发布音视频流不会收取额外费用
+ * - 使用 startPublishCDNStream 接口向非腾讯云的直播 CDN 上发布音视频流，需要收取额外的转推带宽费用。
*/
-- (void)startPublishCDNStream:(TRTCPublishCDNParam*)param;
+- (void)startPublishCDNStream:(TRTCPublishCDNParam *)param;
/**
- * 2.4 停止向非腾讯云地址转推
+ * 3.4 停止向非腾讯云 CDN 上发布音视频流
*/
- (void)stopPublishCDNStream;
/**
- * 2.5 设置云端的混流转码参数
- *
- * 如果您在实时音视频 [控制台](https://console.cloud.tencent.com/trtc/) 中的功能配置页开启了“启用旁路直播”功能，
- * 房间里的每一路画面都会有一个默认的直播 [CDN 地址](https://cloud.tencent.com/document/product/647/16826)。
- *
- * 一个直播间中可能有不止一位主播，而且每个主播都有自己的画面和声音，但对于 CDN 观众来说，他们只需要一路直播流，
- * 所以您需要将多路音视频流混成一路标准的直播流，这就需要混流转码。
- *
- * 当您调用 setMixTranscodingConfig() 接口时，SDK 会向腾讯云的转码服务器发送一条指令，目的是将房间里的多路音视频流混合为一路,
- * 您可以通过 mixUsers 参数来调整每一路画面的位置，以及是否只混合声音，也可以通过 videoWidth、videoHeight、videoBitrate 等参数控制混合音视频流的编码参数。
+ * 3.5 设置云端混流的排版布局和转码参数
*
+ * 在一个直播间中可能同时会有多个主播发布自己的音视频流，但对于直播 CDN 上的观众而言，只需要观看一条 HTTP-FLV 或 HLS 格式的视频流即可。
+ * 当您调用本接口函数时，SDK 会向腾讯云的 TRTC 混流服务器发送一条指令，混流服务器会将房间里的多路音视频流混合成一路。
+ * 您可以通过 {@link TRTCTranscodingConfig} 参数来调整每一路画面的排版布局，也可以设置混合后的音视频流的各项编码参数。
+ * 参考文档：[云端混流转码](https://cloud.tencent.com/document/product/647/16827)。
* <pre>
- * 【画面1】=> 解码 ====> \
- * \
- * 【画面2】=> 解码 => 画面混合 => 编码 => 【混合后的画面】
- * /
- * 【画面3】=> 解码 ====> /
- *
- * 【声音1】=> 解码 ====> \
- * \
- * 【声音2】=> 解码 => 声音混合 => 编码 => 【混合后的声音】
- * /
- * 【声音3】=> 解码 ====> /
+ * 【画面1】=> 解码 ====> \\
+ * \\
+ * 【画面2】=> 解码 => 画面混合 => 编码 => 【混合后的画面】
+ * //
+ * 【画面3】=> 解码 ====> //
+ *
+ * 【声音1】=> 解码 ====> \\
+ * \\
+ * 【声音2】=> 解码 => 声音混合 => 编码 => 【混合后的声音】
+ * //
+ * 【声音3】=> 解码 ====> //
* </pre>
- *
- * 参考文档：[云端混流转码](https://cloud.tencent.com/document/product/647/16827)。
- *
- * @param config 请参考 TRTCCloudDef.h 中关于 TRTCTranscodingConfig 的介绍。如果传入 nil 则取消云端混流转码。
+ * @param config 如果 config 不为空，则开启云端混流，如果 config 为空则停止云端混流。详情请参考 {@link TRTCTranscodingConfig} 。
* @note 关于云端混流的注意事项：
- * - 云端转码会引入一定的 CDN 观看延时，大概会增加1 - 2秒。
- * - 调用该函数的用户，会将连麦中的多路画面混合到自己当前这路画面或者 config 中指定的 streamId 上。
- * - 请注意，若您还在房间中且不再需要混流，请务必传入 nil 进行取消，因为当您发起混流后，云端混流模块就会开始工作，不及时取消混流可能会引起不必要的计费损失。
- * - 请放心，您退房时会自动取消混流状态。
+ * - 调用该接口的用户，如果没设定 config 参数中的 streamId 字段，TRTC 会将房间中的多路画面混合到当前用户所对应的音视频流上，即 A + B => A。
+ * - 调用该接口的用户，如果设定了 config 参数中的 streamId 字段，TRTC 会将房间中的多路画面混合到您指定的 streamId 上，即 A + B => streamId。
+ * - 请注意，若您还在房间中且不再需要混流，请务必再次调用本接口并将 config 设置为空以进行取消，不及时取消混流可能会引起不必要的计费损失。
+ * - 请放心，当您退房时 TRTC 会自动取消混流状态。
*/
-- (void)setMixTranscodingConfig:(TRTCTranscodingConfig*)config;
-
+- (void)setMixTranscodingConfig:(TRTCTranscodingConfig *)config;
/// @}
-
/////////////////////////////////////////////////////////////////////////////////
//
-// （三）视频相关接口函数
+// 视频相关接口函数
//
/////////////////////////////////////////////////////////////////////////////////
-#pragma mark - 视频相关接口函数
-/// @name 视频相关接口函数
+/// @name 视频相关接口函数
/// @{
-#if TARGET_OS_IPHONE
/**
- * 3.1 开启本地视频的预览画面 (iOS 版本)
+ * 4.1 开启本地摄像头的预览画面（移动端）
*
* 在 enterRoom 之前调用此函数，SDK 只会开启摄像头，并一直等到您调用 enterRoom 之后才开始推流。
* 在 enterRoom 之后调用此函数，SDK 会开启摄像头并自动开始视频推流。
- * 当开始渲染首帧摄像头画面时，您会收到 TRTCCloudDelegate 中的 onFirstVideoFrame(nil) 回调。
- *
- * @note 如果希望开播前预览摄像头画面并通过 BeautyManager 调节美颜参数，您可以：
- * - 方案一：在调用 enterRoom 之前调用 startLocalPreview
- * - 方案二：在调用 enterRoom 之后调用 startLocalPreview + muteLocalVideo(true)
+ * 当开始渲染首帧摄像头画面时，您会收到 {@link TRTCCloudDelegate} 中的 onCameraDidReady 回调通知。
* @param frontCamera YES：前置摄像头；NO：后置摄像头。
* @param view 承载视频画面的控件
+ * @note 如果希望开播前预览摄像头画面并通过 BeautyManager 调节美颜参数，您可以：
+ * - 方案一：在调用 enterRoom 之前调用 startLocalPreview
+ * - 方案二：在调用 enterRoom 之后调用 startLocalPreview + muteLocalVideo(true)
*/
+#if TARGET_OS_IPHONE
- (void)startLocalPreview:(BOOL)frontCamera view:(TXView *)view;
-#elif TARGET_OS_MAC
+#endif
+
/**
- * 3.1 开启本地视频的预览画面 (Mac 版本)
+ * 4.2 开启本地摄像头的预览画面（桌面端）
*
- * 在调用该方法前，可以先调用 setCurrentCameraDevice 选择使用 Mac 自带摄像头或外接摄像头。
+ * 在调用该接口之前，您可以先调用 setCurrentCameraDevice 选择使用 Mac 自带摄像头或外接摄像头。
* 在 enterRoom 之前调用此函数，SDK 只会开启摄像头，并一直等到您调用 enterRoom 之后才开始推流。
* 在 enterRoom 之后调用此函数，SDK 会开启摄像头并自动开始视频推流。
- * 当开始渲染首帧摄像头画面时，您会收到 TRTCCloudDelegate 中的 onFirstVideoFrame(nil) 回调。
- *
- * @note 如果希望开播前预览摄像头画面并通过 BeautyManager 调节美颜参数，您可以：
- * - 方案一：在调用 enterRoom 之前调用 startLocalPreview
- * - 方案二：在调用 enterRoom 之后调用 startLocalPreview + muteLocalVideo(true)
- *
+ * 当开始渲染首帧摄像头画面时，您会收到 {@link TRTCCloudDelegate} 中的 onCameraDidReady 回调通知。
* @param view 承载视频画面的控件
+ * @note 如果希望开播前预览摄像头画面并通过 BeautyManager 调节美颜参数，您可以：
+ * - 方案一：在调用 enterRoom 之前调用 startLocalPreview
+ * - 方案二：在调用 enterRoom 之后调用 startLocalPreview + muteLocalVideo(true)
*/
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
- (void)startLocalPreview:(TXView *)view;
#endif
/**
- * 3.2 更新本地视频预览画面的窗口
- *
- * @param view 承载视频画面的控件
+ * 4.3 更新本地摄像头的预览画面
*/
- (void)updateLocalView:(TXView *)view;
/**
- * 3.3 停止本地视频采集及预览
+ * 4.4 停止摄像头预览
*/
- (void)stopLocalPreview;
/**
- * 3.4 暂停/恢复推送本地的视频数据
- *
- * 当暂停推送本地视频后，房间里的其它成员将会收到 onUserVideoAvailable(userId, NO) 回调通知
- * 当恢复推送本地视频后，房间里的其它成员将会收到 onUserVideoAvailable(userId, YES) 回调通知
+ * 4.5 暂停/恢复发布本地的视频流
*
- * @param mute YES：暂停；NO：恢复
+ * 该接口可以暂停（或恢复）发布本地的视频画面，暂停之后，同一房间中的其他用户将无法继续看到自己画面。
+ * 该接口在指定 TRTCVideoStreamTypeBig 时等效于 start/stopLocalPreview 这两个接口，但具有更好的响应速度。
+ * 因为 start/stopLocalPreview 需要打开和关闭摄像头，而打开和关闭摄像头都是硬件设备相关的操作，非常耗时。
+ * 相比之下，muteLocalVideo 只需要在软件层面对数据流进行暂停或者放行即可，因此效率更高，也更适合需要频繁打开关闭的场景。
+ * 当暂停/恢复发布指定 TRTCVideoStreamTypeBig 后，同一房间中的其他用户将会收到 onUserVideoAvailable 回调通知。
+ * 当暂停/恢复发布指定 TRTCVideoStreamTypeSub 后，同一房间中的其他用户将会收到 onUserSubStreamAvailable 回调通知。
+ * @param streamType 要暂停/恢复的视频流类型（仅支持 {@link TRTCVideoStreamTypeBig} 和 {@link TRTCVideoStreamTypeSub}）
+ * @param mute true：暂停；false：恢复。
*/
-- (void)muteLocalVideo:(BOOL)mute;
+- (void)muteLocalVideo:(TRTCVideoStreamType)streamType mute:(BOOL)mute;
/**
- * 3.5 设置暂停推送本地视频时要推送的图片
+ * 4.6 设置本地画面被暂停期间的替代图片
*
- * 当暂停推送本地视频后，会继续推送该接口设置的图片
- *
- * @param image 设置要推送的图片。 nil 表示不推送
- * @param fps 设置推送图片帧率，最小值为5，最大值为10，默认5。
+ * 当您调用 muteLocalVideo(true) 暂停本地画面时，您可以通过调用本接口设置一张替代图片，设置后，房间中的其他用户会看到这张替代图片，而不是黑屏画面。
+ * @param image 设置替代图片，空值代表在 muteLocalVideo 之后不再发送视频流数据，默认值为空。
+ * @param fps 设置替代图片帧率，最小值为5，最大值为10，默认5。
*/
- (void)setVideoMuteImage:(TXImage *)image fps:(NSInteger)fps;
/**
- * 3.6 开始拉取并显示指定用户的远端画面
+ * 4.7 订阅远端用户的视频流，并绑定视频渲染控件
*
- * 该函数会拉取指定 userid 的视频流显示在您指定的 view 控件上，您可以通过 setRemoteRenderParams:streamType:params: 设置显示模式。
- * - 如果您提前知道房间中某个 userid 正在推流，可以直接调用 startRemoteView 显示该用户的远端画面。
- * - 如果您不知道房间中有哪些用户开启了视频，可以在 enterRoom 后等待来自 SDK 的 onUserVideoAvailable(userId, true) 回调通知。
- * 调用 startRemoteView 只是启动拉取，此时画面还需要加载，当加载完毕后 TRTCCloudListener 会通过 onFirstVideoFrame(userId) 通知您。
+ * 调用该接口可以让 SDK 拉取指定 userid 的视频流，并渲染到参数 view 指定的渲染控件上。您可以通过 {@link setRemoteRenderParams} 设置画面的显示模式。
+ * - 如果您已经知道房间中有视频流的用户的 userid，可以直接调用 startRemoteView 订阅该用户的画面。
+ * - 如果您不知道房间中有哪些用户在发布视频，您可以在 enterRoom 之后等待来自 {@link onUserVideoAvailable} 的通知。
*
- * @param userId 指定远端用户的 userId
+ * 调用本接口只是启动视频流的拉取，此时画面还需要加载和缓冲，当缓冲完毕后您会收到来自 {@link onFirstVideoFrame} 的通知。
+ * @param userId 指定远端用户的 ID。
* @param streamType 指定要观看 userId 的视频流类型：
- * - 高清大画面：TRTCVideoStreamTypeBig
- * - 低清小画面：TRTCVideoStreamTypeSmall
- * - 辅流（屏幕分享）：TRTCVideoStreamTypeSub
- * @param view 承载视频画面的控件
+ * - 高清大画面：{@link TRTCVideoStreamTypeBig}
+ * - 低清小画面：{@link TRTCVideoStreamTypeSmall}（需要远端用户通过 {@link enableEncSmallVideoStream} 开启双路编码后才有效果）
+ * - 辅流画面（常用于屏幕分享）：{@link TRTCVideoStreamTypeSub}
+ *
+ * @param view 用于承载视频画面的渲染控件
* @note 注意几点规则需要您关注：
- * 1. SDK 支持同时观看某 userid 的大画面和辅路，或者小画面和辅路，但不支持同时观看大画面和小画面。
- * 2. 只有当指定的 userid 通过 enableEncSmallVideoStream 开启双路编码后，才能观看该用户的小画面。
- * 3. 如果该用户的小画面不存在，则默认切换到大画面。
+ * 1. SDK 支持同时观看某 userid 的大画面和辅路画面，或者同时观看某 userid 的小画面和辅路画面，但不支持同时观看大画面和小画面。
+ * 2. 只有当指定的 userid 通过 {@link enableEncSmallVideoStream} 开启双路编码后，才能观看该用户的小画面。
+ * 3. 当指定的 userid 的小画面不存在时，SDK 默认切换到该用户的大画面。
*/
- (void)startRemoteView:(NSString *)userId streamType:(TRTCVideoStreamType)streamType view:(TXView *)view;
/**
-* 3.7 更新远端视频画面的窗口
-*
-* @param view 承载视频画面的控件
-* @param type 要设置预览窗口的流类型(TRTCVideoStreamTypeBig、TRTCVideoStreamTypeSub)
-* @param userId 对方的用户标识
-*/
-- (void)updateRemoteView:(TXView *)view streamType:(TRTCVideoStreamType)type forUser:(NSString *)userId;
+ * 4.8 更新远端用户的视频渲染控件
+ *
+ * 该接口可用于更新远端视频画面的渲染控件，常被用于切换显示区域的交互场景中。
+ * @param view 承载视频画面的控件
+ * @param streamType 要设置预览窗口的流类型（仅支持 {@link TRTCVideoStreamTypeBig} 和 {@link TRTCVideoStreamTypeSub}）
+ * @param userId 指定远端用户的 ID。
+ */
+- (void)updateRemoteView:(TXView *)view streamType:(TRTCVideoStreamType)streamType forUser:(NSString *)userId;
/**
- * 3.8 停止显示远端视频画面，同时不再拉取该远端用户的视频数据流
+ * 4.9 停止订阅远端用户的视频流，并释放渲染控件
*
- * 调用此接口后，SDK 会停止接收该用户的远程视频流，同时会清理相关的视频显示资源。
- *
- * @param userId 指定远端用户的 userId
- * @param streamType 指定要停止观看的 userId 的视频流类型：
- * - 高清大画面：TRTCVideoStreamTypeBig
- * - 低清小画面：TRTCVideoStreamTypeSmall
- * - 辅流（屏幕分享）：TRTCVideoStreamTypeSub
-
+ * 调用此接口会让 SDK 停止接收该用户的视频流，并释放该路视频流的解码和渲染资源。
+ * @param userId 指定远端用户的 ID。
+ * @param streamType 指定要观看 userId 的视频流类型：
+ * - 高清大画面：{@link TRTCVideoStreamTypeBig}
+ * - 低清小画面：{@link TRTCVideoStreamTypeSmall}
+ * - 辅流画面（常用于屏幕分享）：{@link TRTCVideoStreamTypeSub}
*/
- (void)stopRemoteView:(NSString *)userId streamType:(TRTCVideoStreamType)streamType;
/**
- * 3.9 停止显示所有远端视频画面，同时不再拉取远端用户的视频数据流
+ * 4.10 停止订阅所有远端用户的视频流，并释放全部渲染资源
*
- * @note 如果有屏幕分享的画面在显示，则屏幕分享的画面也会一并被关闭。
+ * 调用此接口会让 SDK 停止接收所有来自远端的视频流，并释放全部的解码和渲染资源。
+ * @note 如果当前有正在显示的辅路画面（屏幕分享）也会一并被停止。
*/
- (void)stopAllRemoteView;
/**
- * 3.10 暂停/恢复接收指定的远端视频流
+ * 4.11 暂停/恢复订阅远端用户的视频流
*
- * 该接口仅暂停/恢复接收指定的远端用户的视频流，但并不释放显示资源，视频画面会冻屏在 mute 前的最后一帧。
- *
- * @param userId 对方的用户标识
- * @param mute 是否暂停接收
- * @note 您在 enterRoom 之前或之后调用此 API 均会进入屏蔽状态，屏蔽状态在您调用 exitRoom 之后会被重置为 false。
+ * 该接口仅暂停/恢复接收指定用户的视频流，但并不释放显示资源，视频画面会被冻屏在接口调用时的最后一帧。
+ * @param userId 指定远端用户的 ID。
+ * @param streamType 要暂停/恢复的视频流类型（仅支持 {@link TRTCVideoStreamTypeBig} 和 {@link TRTCVideoStreamTypeSub}）。
+ * @param mute 是否暂停接收。
+ * @note 该接口支持您在进入房间（enterRoom）前调用，暂停状态会在退出房间（exitRoom）在之后会被重置。
*/
-- (void)muteRemoteVideoStream:(NSString*)userId mute:(BOOL)mute;
+- (void)muteRemoteVideoStream:(NSString *)userId streamType:(TRTCVideoStreamType)streamType mute:(BOOL)mute;
/**
- * 3.11 暂停/恢复接收所有远端视频流
+ * 4.12 暂停/恢复订阅所有远端用户的视频流
*
- * 该接口仅暂停/恢复接收所有远端用户的视频流，但并不释放显示资源，视频画面会冻屏在 mute 前的最后一帧。
- *
- * @param mute 是否暂停接收
- * @note 您在 enterRoom 之前或之后调用此 API 均会进入屏蔽状态，屏蔽状态在您调用 exitRoom 之后会被重置为 false。
+ * 该接口仅暂停/恢复接收所有用户的视频流，但并不释放显示资源，视频画面会被冻屏在接口调用时的最后一帧。
+ * @param mute 是否暂停接收
+ * @note 该接口支持您在进入房间（enterRoom）前调用，暂停状态会在退出房间（exitRoom）在之后会被重置。
*/
- (void)muteAllRemoteVideoStreams:(BOOL)mute;
/**
- * 3.12 设置视频编码器相关参数
+ * 4.13 设置视频编码器的编码参数
*
- * 该设置决定了远端用户看到的画面质量（同时也是云端录制出的视频文件的画面质量）
- *
- * @param param 视频编码参数，详情请参考 TRTCCloudDef.h 中的 TRTCVideoEncParam 定义
+ * 该设置能够决定远端用户看到的画面质量，同时也能决定云端录制出的视频文件的画面质量。
+ * @param param 用于设置视频编码器的相关参数，详情请参考 {@link TRTCVideoEncParam}。
*/
-- (void)setVideoEncoderParam:(TRTCVideoEncParam*)param;
+- (void)setVideoEncoderParam:(TRTCVideoEncParam *)param;
/**
- * 3.13 设置网络流控相关参数
- *
- * 该设置决定 SDK 在各种网络环境下的调控策略（例如弱网下选择“保清晰”或“保流畅”）
+ * 4.14 设置网络质量控制的相关参数
*
- * @param param 网络流控参数，详情请参考 TRTCCloudDef.h 中的 TRTCNetworkQosParam 定义
+ * 该设置决定在差网络环境下的质量调控策略，如“画质优先”或“流畅优先”等策略。
+ * @param param 用于设置网络质量控制的相关参数，详情请参考 {@link TRTCNetworkQosParam}。
*/
-- (void)setNetworkQosParam:(TRTCNetworkQosParam*)param;
+- (void)setNetworkQosParam:(TRTCNetworkQosParam *)param;
/**
- * 3.14 本地图像的渲染设置
+ * 4.15 设置本地画面的渲染参数
*
- * @param type 视频线路，可以设置为主路（TRTCVideoStreamTypeBig）或者辅路（TRTCVideoStreamTypeSub）
- * @param params 参见 TRTCCouldDef.h 中对 TRTCRenderParams 的定义
+ * 可设置的参数包括有：画面的旋转角度、填充模式以及左右镜像等。
+ * @param params 画面渲染参数，详情请参考 {@link TRTCRenderParams}。
*/
- (void)setLocalRenderParams:(TRTCRenderParams *)params;
/**
- * 3.15 远端图像的渲染设置
+ * 4.16 设置远端画面的渲染模式
*
- * @param userId 用户 ID
- * @param type 视频线路，可以设置为主路（TRTCVideoStreamTypeBig）或者辅路（TRTCVideoStreamTypeSub）
- * @param params 参见 TRTCCouldDef.h 中对 TRTCRenderParams 的定义
+ * 可设置的参数包括有：画面的旋转角度、填充模式以及左右镜像等。
+ * @param userId 指定远端用户的 ID。
+ * @param streamType 可以设置为主路画面（TRTCVideoStreamTypeBig）或辅路画面（TRTCVideoStreamTypeSub）
+ * @param params 画面渲染参数，详情请参考 {@link TRTCRenderParams}。
*/
-- (void)setRemoteRenderParams:(NSString *)userId streamType:(TRTCVideoStreamType)type params:(TRTCRenderParams *)params;
+- (void)setRemoteRenderParams:(NSString *)userId streamType:(TRTCVideoStreamType)streamType params:(TRTCRenderParams *)params;
/**
- * 3.16 设置视频编码输出的画面方向，即设置远端用户观看到的和服务器录制的画面方向
- *
- * 在 iPad、iPhone 等设备180度旋转时，由于摄像头的采集方向没有变，所以对方看到的画面是上下颠倒的，
- * 在这种情况下，您可以通过该接口将 SDK 输出到对方的画面旋转180度，这样可以可以确保对方看到的画面依然正常。
+ * 4.17 设置视频编码器输出的画面方向
*
- * @param rotation 目前支持0和180两个旋转角度，默认值：TRTCVideoRotation_0
+ * 该设置不影响本地画面的预览方向，但会影响房间中其他用户所观看到（以及云端录制文件）的画面方向。
+ * 当用户将手机或 Pad 上下颠倒时，由于摄像头的采集方向没有变，所以房间中其他用户所看到的画面会变成上下颠倒的，
+ * 在这种情况下，您可以通过调用该接口将 SDK 编码出的画面方向旋转180度，如此一来，房间中其他用户所看到的画面可保持正常的方向。
+ * 如果您希望实现上述这种友好的交互体验，我们更推荐您直接调用 {@link setGSensorMode} 实现更加智能的方向适配，无需您手动调用本接口。
+ * @param rotation 目前支持0和180两个旋转角度，默认值：TRTCVideoRotation_0，即不旋转。
*/
- (void)setVideoEncoderRotation:(TRTCVideoRotation)rotation;
/**
- * 3.17 设置编码器输出的画面镜像模式
- *
- * 该接口不改变本地摄像头的预览画面，但会改变另一端用户看到的（以及服务器录制的）画面效果。
+ * 4.18 设置编码器输出的画面镜像模式
*
- * @param mirror 是否开启远端镜像，YES：开启远端画面镜像；NO：关闭远端画面镜像，默认值：NO。
+ * 该设置不影响本地画面的镜像模式，但会影响房间中其他用户所观看到（以及云端录制文件）的镜像模式。
+ * @param mirror 是否开启远端镜像，true：开启远端画面镜像；false：关闭远端画面镜像，默认值：false。
*/
- (void)setVideoEncoderMirror:(BOOL)mirror;
/**
- * 3.18 设置重力感应的适应模式
+ * 4.19 设置重力感应的适配模式
*
- * @param mode 重力感应模式，详情请参考 TRTCGSensorMode 的定义，默认值：TRTCGSensorMode_UIAutoLayout
+ * 您可以通过本接口实现如下这种友好的交互体验：
+ * 当用户将手机或 Pad 上下颠倒时，由于摄像头的采集方向没有变，所以房间中其他用户所看到的画面会变成上下颠倒的，
+ * 在这种情况下，您可以通过调用该接口让 SDK 根据设备陀螺仪的朝向自动调整本地画面和编码器输出画面的旋转方向，以使远端观众可以看到正常朝向的画面。
+ * @param mode 重力感应模式，详情请参考 {@link TRTCGSensorMode}，默认值：TRTCGSensorMode_UIAutoLayout。
*/
-- (void)setGSensorMode:(TRTCGSensorMode) mode;
+- (void)setGSensorMode:(TRTCGSensorMode)mode;
/**
- * 3.19 开启大小画面双路编码模式
- *
- * 如果当前用户是房间中的主要角色（例如主播、老师、主持人等），并且使用 PC 或者 Mac 环境，可以开启该模式。
- * 开启该模式后，当前用户会同时输出【高清大画面】和【低清小画面】两路视频流（但只有一路音频流）。
- * 对于开启该模式的当前用户，会占用更多的网络带宽，并且会更加消耗 CPU 计算资源。
- *
- * 对于同一房间的远程观众而言：
- * - 如果下行网络很好，可以选择观看【高清大画面】
- * - 如果下行网络较差，可以选择观看【低清小画面】
+ * 4.20 开启大小画面双路编码模式
*
- * @note 双路编码开启后，会消耗更多的 CPU 和 网络带宽，所以对于 iMac、Windows 或者高性能 Pad 可以考虑开启，但请不要在手机端开启。
- *
- * @param enable 是否开启小画面编码，默认值：NO
+ * 开启双路编码模式后，当前用户的编码器会同时输出【高清大画面】和【低清小画面】两路视频流（但只有一路音频流）。
+ * 如此以来，房间中的其他用户就可以根据自身的网络情况或屏幕大小选择订阅【高清大画面】或是【低清小画面】。
+ * @note 双路编码开启后，会消耗更多的 CPU 和 网络带宽，所以 Mac、Windows 或者高性能 Pad 可以考虑开启，不建议手机端开启。
+ * @param enable 是否开启小画面编码，默认值：false
* @param smallVideoEncParam 小流的视频参数
- * @return 0：成功；-1：大画面已经是最低画质
+ * @return 0：成功；-1：当前大画面已被设置为较低画质，开启双路编码已无必要。
*/
-- (int)enableEncSmallVideoStream:(BOOL)enable withQuality:(TRTCVideoEncParam*)smallVideoEncParam;
+- (int)enableEncSmallVideoStream:(BOOL)enable withQuality:(TRTCVideoEncParam *)smallVideoEncParam;
/**
- * 3.20 切换指定远端用户的大小画面
- * @note
- * 1. 此功能需要该 userId 通过 enableEncSmallVideoStream 提前开启双路编码模式。
- * 如果该 userId 没有开启双路编码模式，则此操作将无任何反应。
- * 2. 在不通过此接口进行设置的情况下，startRemoteView 默认观看的画面为大画面。
- *
- * @param userId 用于指定要观看的 userId
- * @param type 视频流类型，即选择看大画面或小画面，默认为大画面
- */
-- (void)setRemoteVideoStreamType:(NSString*)userId type:(TRTCVideoStreamType)type;
-
-/**
-* 3.21 视频画面截图
-*
-* 截取本地、远程主路和远端辅流的视频画面，并通过 UIImage(iOS) 或 NSImage(macOS) 对象返回给您。
-*
-* @param userId 用户 ID，nil 表示截取本地视频画面。
-* @param type 视频流类型，支持主路画面（TRTCVideoStreamTypeBig，一般用于摄像头）和 辅路画面（TRTCVideoStreamTypeSub，一般用于屏幕分享）。
-* @prara sourceType 截图画面来源，支持视频流（TRTCSnapshotSourceTypeStream）和视频渲染画面（TRTCSnapshotSourceTypeView）
-* @param completionBlock 画面截取后的回调。
-*
-* @note 设置 userId = nil，代表截取当前用户的本地画面，目前本地画面仅支持截取主路画面（TRTCVideoStreamTypeBig）。
-*/
-- (void)snapshotVideo:(NSString *)userId
- type:(TRTCVideoStreamType)type
- sourceType:(TRTCSnapshotSourceType)sourceType
- completionBlock:(void (^)(TXImage *image))completionBlock;
+ * 4.21 切换指定远端用户的大小画面
+ *
+ * 当房间中某个主播开启了双路编码之后，房间中其他用户通过 {@link startRemoteView} 订阅到的画面默认会是【高清大画面】。
+ * 您可以通过此接口选定希望订阅的画面是大画面还是小画面，该接口在 {@link startRemoteView} 之前和之后调用均可生效。
+ * @note 此功能需要目标用户已经通过 {@link enableEncSmallVideoStream} 提前开启了双路编码模式，否则此调用无实际效果。
+ * @param userId 指定远端用户的 ID。
+ * @param streamType 视频流类型，即选择看大画面还是小画面，默认为大画面。
+ */
+- (void)setRemoteVideoStreamType:(NSString *)userId type:(TRTCVideoStreamType)streamType;
-/// @}
+/**
+ * 4.22 视频画面截图
+ *
+ * 您可以通过本接口截取本地的视频画面，远端用户的主路画面以及远端用户的辅路（屏幕分享）画面。
+ * @param userId 用户 ID，如指定空置表示截取本地的视频画面。
+ * @param streamType 视频流类型，可选择截取主路画面（{@link TRTCVideoStreamTypeBig}，常用于摄像头）或辅路画面（{@link TRTCVideoStreamTypeSub}，常用于屏幕分享）。
+ * @param sourceType 画面来源，可选择截取视频流画面（{@link TRTCSnapshotSourceTypeStream}）或视频渲染画面（{@link TRTCSnapshotSourceTypeView}），前者一般更清晰。
+ * @note Windows 平台目前仅支持截取 {@link TRTCSnapshotSourceTypeStream} 来源的视频画面。
+ */
+- (void)snapshotVideo:(NSString *)userId type:(TRTCVideoStreamType)streamType sourceType:(TRTCSnapshotSourceType)sourceType completionBlock:(void (^)(TXImage *image))completionBlock;
+/// @}
/////////////////////////////////////////////////////////////////////////////////
//
-// （四）音频相关接口函数
+// 音频相关接口函数
//
/////////////////////////////////////////////////////////////////////////////////
-#pragma mark - 音频相关接口函数
-/// @name 音频相关接口函数
+/// @name 音频相关接口函数
/// @{
/**
- * 4.1 开启本地音频的采集和上行
- *
- * SDK 默认不采集声音，您需要调用该函数启动麦克风采集，并将音频数据传输给房间里的其他用户。
+ * 5.1 开启本地音频的采集和发布
*
+ * SDK 默认不开启麦克风，当用户需要发布本地音频时，需要调用该接口开启麦克风采集，并将音频编码并发布到当前的房间中。
+ * 开启本地音频的采集和发布后，房间中的其他用户会收到 {@link onUserAudioAvailable}(userId, true) 的通知。
* @param quality 声音音质
- * - {@link TRTCCloudDef#TRTCAudioQualitySpeech}， 流畅：采样率：16k；单声道；音频裸码率：16kbps；适合语音通话为主的场景，比如在线会议，语音通话。
- * - {@link TRTCCloudDef#TRTCAudioQualityDefault}，默认：采样率：48k；单声道；音频裸码率：50kbps；SDK 默认的音频质量，如无特殊需求推荐选择之。
- * - {@link TRTCCloudDef#TRTCAudioQualityMusic}，高音质：采样率：48k；双声道 + 全频带；音频裸码率：128kbps；适合需要高保真传输音乐的场景，比如K歌、音乐直播等。
- *
- * @note 该函数会检查麦克风的使用权限，如果当前 App 没有麦克风权限，SDK 会向用户申请开启。
+ * - {@link TRTCAudioQualitySpeech}，流畅：采样率：16k；单声道；音频裸码率：16kbps；适合语音通话为主的场景，比如在线会议，语音通话。
+ * - {@link TRTCAudioQualityDefault}，默认：采样率：48k；单声道；音频裸码率：50kbps；SDK 默认的音频质量，如无特殊需求推荐选择之。
+ * - {@link TRTCAudioQualityMusic}，高音质：采样率：48k；双声道 + 全频带；音频裸码率：128kbps；适合需要高保真传输音乐的场景，比如在线K歌、音乐直播等。
+ * @note 该函数会检查麦克风的使用权限，如果当前 App 没有麦克风权限，SDK 会自动向用户申请麦克风使用权限。
*/
- (void)startLocalAudio:(TRTCAudioQuality)quality;
/**
- * 4.2 关闭本地音频的采集和上行
+ * 5.2 停止本地音频的采集和发布
*
- * 当关闭本地音频的采集和上行，房间里的其它成员会收到 onUserAudioAvailable(NO) 回调通知。
+ * 停止本地音频的采集和发布后，房间中的其他用户会收到 {@link onUserAudioAvailable}(userId, false) 的通知。
*/
- (void)stopLocalAudio;
/**
- * 4.3 静音/取消静音本地的音频
- *
- * 当静音本地音频后，房间里的其它成员会收到 onUserAudioAvailable(userId, NO) 回调通知。
- * 当取消静音本地音频后，房间里的其它成员会收到 onUserAudioAvailable(userId, YES) 回调通知。
- *
- * 与 stopLocalAudio 不同之处在于，muteLocalAudio:YES 并不会停止发送音视频数据，而是继续发送码率极低的静音包。
- * 由于 MP4 等视频文件格式，对于音频的连续性是要求很高的，使用 stopLocalAudio 会导致录制出的 MP4 不易播放。
- * 因此在对录制质量要求很高的场景中，建议选择 muteLocalAudio，从而录制出兼容性更好的 MP4 文件。
+ * 5.3 暂停/恢复发布本地的音频流
*
- * @param mute YES：静音；NO：取消静音
+ * 当您暂停发布本地音频流之后，房间中的其他他用户会收到 {@link onUserAudioAvailable}(userId, false) 的通知。
+ * 当您恢复发布本地音频流之后，房间中的其他他用户会收到 {@link onUserAudioAvailable}(userId, true) 的通知。
+ * 与 {@link stopLocalAudio} 的不同之处在于，muteLocalAudio(true) 并不会释放麦克风权限，而是继续发送码率极低的静音包。
+ * 这对于需要云端录制的场景非常适用，因为 MP4 等格式的视频文件，对于音频数据的连续性要求很高，使用 {@link stopLocalAudio} 会导致录制出的 MP4 文件不易播放。
+ * 因此在对录制文件的质量要求较高的场景中，建议选择 muteLocalAudio 而不建议使用 stopLocalAudio。
+ * @param mute true：静音；false：恢复。
*/
- (void)muteLocalAudio:(BOOL)mute;
/**
- * 4.4 静音/取消静音指定的远端用户的声音
+ * 5.4 暂停/恢复播放远端的音频流
*
- * @param userId 对方的用户 ID
- * @param mute YES：静音；NO：取消静音
- *
- * @note 静音时会停止接收该用户的远端音频流并停止播放，取消静音时会自动拉取该用户的远端音频流并进行播放。
- * 您在 enterRoom 之前或之后调用此 API 均会进入屏蔽状态，屏蔽状态在您调用 exitRoom 之后会被重置为 false。
+ * 当您静音某用户的远端音频时，SDK 会停止播放指定用户的声音，同时也会停止拉取该用户的音频数据数据。
+ * @param userId 用于指定远端用户的 ID。
+ * @param mute true：静音；false：取消静音。
+ * @note 在进入房间（enterRoom）之前或之后调用本接口均生效，静音状态在退出房间（exitRoom） 之后会被重置为 false。
*/
- (void)muteRemoteAudio:(NSString *)userId mute:(BOOL)mute;
/**
- * 4.5 静音/取消静音所有用户的声音
- *
- * @param mute YES：静音；NO：取消静音
+ * 5.5 暂停/恢复播放所有远端用户的音频流
*
- * @note 静音时会停止接收所有用户的远端音频流并停止播放，取消静音时会自动拉取所有用户的远端音频流并进行播放。
- * 您在 enterRoom 之前或之后调用此 API 均会进入屏蔽状态，屏蔽状态在您调用 exitRoom 之后会被重置为 false。
+ * 当您静音所有用户的远端音频时，SDK 会停止播放所有来自远端的音频流，同时也会停止拉取所有用户的音频数据。
+ * @param mute true：静音；false：取消静音。
+ * @note 在进入房间（enterRoom）之前或之后调用本接口均生效，静音状态在退出房间（exitRoom） 之后会被重置为 false。
*/
- (void)muteAllRemoteAudio:(BOOL)mute;
/**
- * 4.6 设置音频路由
- *
- * 微信和手机 QQ 视频通话功能的免提模式就是基于音频路由实现的。
- * 一般手机都有两个扬声器，一个是位于顶部的听筒扬声器，声音偏小；一个是位于底部的立体声扬声器，声音偏大。
- * 设置音频路由的作用就是决定声音使用哪个扬声器播放。
+ * 5.6 设置音频路由
*
- * @param route 音频路由，即声音由哪里输出（扬声器、听筒），默认值：TRTCAudioModeSpeakerphone
+ * 设置“音频路由”，即设置声音是从手机的扬声器还是从听筒中播放出来，因此该接口仅适用于手机等移动端设备。
+ * 手机有两个扬声器：一个是位于手机顶部的听筒，一个是位于手机底部的立体声扬声器。
+ * 设置音频路由为听筒时，声音比较小，只有将耳朵凑近才能听清楚，隐私性较好，适合用于接听电话。
+ * 设置音频路由为扬声器时，声音比较大，不用将手机贴脸也能听清，因此可以实现“免提”的功能。
+ * @param route 音频路由，即声音由哪里输出（扬声器、听筒），默认值：TRTCAudioModeSpeakerphone。
*/
- (void)setAudioRoute:(TRTCAudioRoute)route;
/**
- * 4.7 设置某个远程用户的播放音量
+ * 5.7 设定某一个远端用户的声音播放音量
*
- * @param userId 远程用户 ID
- * @param volume 音量大小，100为原始音量，范围是：[0 ~ 150]，默认值为100
- *
- * @note 如果要将 volume 设置为大于100的数值，需要进行特殊配置，请联系技术支持。
+ * 您可以通过 setRemoteAudioVolume(userId, 0) 将某一个远端用户的声音静音。
+ * @param userId 用于指定远端用户的 ID。
+ * @param volume 音量大小，取值范围为0 - 100，默认值：100。
+ * @note 如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。
*/
- (void)setRemoteAudioVolume:(NSString *)userId volume:(int)volume;
/**
- * 4.8 设置 SDK 采集音量。
- *
- * @param volume 音量大小，100为原始音量，范围是：[0 ~ 150]，默认值为100
+ * 5.8 设定本地音频的采集音量
*
- * @note 如果要将 volume 设置为大于100的数值，需要进行特殊配置，请联系技术支持。
+ * @param volume 音量大小，取值范围为0 - 100；默认值：100
+ * @note 如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。
*/
- (void)setAudioCaptureVolume:(NSInteger)volume;
/**
- * 4.9 获取 SDK 采集音量
+ * 5.9 获取本地音频的采集音量
*/
- (NSInteger)getAudioCaptureVolume;
/**
- * 4.10 设置 SDK 播放音量。
+ * 5.10 设定远端音频的播放音量
*
- * @param volume 音量大小，100为原始音量，范围是：[0 ~ 150]，默认值为100
+ * 该接口会控制 SDK 最终交给系统播放的声音音量，调节效果会影响到本地音频录制文件的音量大小，但不会影响到耳返的音量大小。
*
- * @note
- * 1. 该函数会控制最终交给系统播放的声音音量，会影响录制本地音频文件的音量大小，但不会影响耳返的音量。<br>
- * 2. 如果要将 volume 设置为大于100的数值，需要进行特殊配置，请联系技术支持。
+ * @param volume 音量大小，取值范围为0 - 100，默认值：100。
+ * @note 如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。
*/
- (void)setAudioPlayoutVolume:(NSInteger)volume;
/**
- * 4.11 获取 SDK 播放音量
+ * 5.11 获取远端音频的播放音量
*/
- (NSInteger)getAudioPlayoutVolume;
/**
- * 4.12 启用音量大小提示
- *
- * 开启此功能后，SDK 会在 onUserVoiceVolume() 中反馈对每一路声音音量大小值的评估。
- * 如需打开此功能，请在 startLocalAudio() 之前调用。
+ * 5.12 启用音量大小提示
*
- * @note Demo 中有一个音量大小的提示条，就是基于这个接口实现的。
- * @param interval 设置 onUserVoiceVolume 回调的触发间隔，单位为ms，最小间隔为100ms，如果小于等于0则会关闭回调，建议设置为300ms；
+ * 开启此功能后，SDK 会在 {@link TRTCCloudDelegate} 中的 {@link onUserVoiceVolume} 回调中反馈远端音频的音量大小。
+ * @note 如需打开此功能，请在 startLocalAudio 之前调用才可以生效。
+ * @param interval 设置 onUserVoiceVolume 回调的触发间隔，单位为ms，最小间隔为100ms，如果小于等于 0 则会关闭回调，建议设置为300ms；
*/
- (void)enableAudioVolumeEvaluation:(NSUInteger)interval;
/**
- * 4.13 开始录音
+ * 5.13 开始录音
*
- * 该方法调用后， SDK 会将通话过程中的所有音频（包括本地音频，远端音频，BGM 等）录制到一个文件里。
- * 无论是否进房，调用该接口都生效。
- * 如果调用 exitRoom 时还在录音，录音会自动停止。
- *
- * @param param 录音参数，请参考 TRTCAudioRecordingParams
- * @return 0：成功；-1：录音已开始；-2：文件或目录创建失败；-3：后缀指定的音频格式不支持
+ * 当您调用改接口后， SDK 会将本地和远端的所有音频（包括本地音频，远端音频，背景音乐和音效等）混合并录制到一个本地文件中。
+ * 该接口在进入房间前后调用均可生效，如果录制任务在退出房间前尚未通过 stopAudioRecording 停止，则退出房间后录制任务会自动被停止。
+ * @param param 录音参数，请参考 {@link TRTCAudioRecordingParams}
+ * @return 0：成功；-1：录音已开始；-2：文件或目录创建失败；-3：后缀指定的音频格式不支持。
*/
-- (int)startAudioRecording:(TRTCAudioRecordingParams*) param;
+- (int)startAudioRecording:(TRTCAudioRecordingParams *)param;
/**
- * 4.14 停止录音
+ * 5.14 停止录音
*
- * 如果调用 exitRoom 时还在录音，录音会自动停止。
+ * 如果录制任务在退出房间前尚未通过本接口停止，则退出房间后录音任务会自动被停止。
*/
- (void)stopAudioRecording;
-#if TARGET_OS_IPHONE
/**
- * 4.15 开启本地媒体录制(iOS)
- *
- * 开启后把直播过程中的音视频数据录制存储到本地文件。
- * 应用场景:
- * 1. 不推流情况下，通过调用 startLocalPreview 预览画面后，进行录制。
- * 2. 在推流的同时进行录制，把直播的全程录制保存到本地文件。
- *
- * @param params 录制参数，请参考 {@link TRTCCloudDef#TRTCLocalRecordingParams}
+ * 5.15 开启本地媒体录制
*
+ * 开启后把直播过程中的音视和视频内容录制到本地的一个文件中。
+ * @param params 录制参数，请参考 {@link TRTCLocalRecordingParams}
*/
+#if TARGET_OS_IPHONE
- (void)startLocalRecording:(TRTCLocalRecordingParams *)params;
-
-/**
- * 4.16 停止录制
- *
- * 如果调用 exitRoom 时还在录制，录制会自动停止。
- */
-- (void)stopLocalRecording;
#endif
-#if !TARGET_OS_IPHONE && TARGET_OS_MAC
-
-/**
- * 4.17 开始录制系统声音，仅适用 Mac 平台
- *
- * 开启系统声卡采集，并将其混入上行音频流中，从而可以直播当前 Mac 系统的声音（如电影播出的声音）。
- *
- * @note
- * 1. 此功能需要为用户的 Mac 系统安装虚拟音频设备插件，安装完成后，SDK 会从已经安装的虚拟音频设备中采集声音。
- * 2. SDK 会自动从网络上下载合适的插件进行安装，但是下载速度可能比较慢，如果您希望加速这个过程，可以将虚拟音频插件文件打包到您 App Bundle 的 Resources 目录下。
- *
- */
-- (void)startSystemAudioLoopback;
-
/**
- * 4.18 停止录制系统声音，仅适用 Mac 平台
- */
-- (void)stopSystemAudioLoopback;
-
-/**
- * 4.19 设置系统声音采集的音量，仅适用 Mac 平台
- *
- * @param volume 设置的音量大小，范围是：[0 ~ 150]，默认值为100
+ * 5.16 停止本地媒体录制
*
+ * 如果录制任务在退出房间前尚未通过本接口停止，则退出房间后录音任务会自动被停止。
*/
-- (void)setSystemAudioLoopbackVolume:(uint32_t)volume;
-
+#if TARGET_OS_IPHONE
+- (void)stopLocalRecording;
#endif
/// @}
-
-
-
/////////////////////////////////////////////////////////////////////////////////
//
-// （五）设备管理相关接口
+// 设备管理相关接口
//
/////////////////////////////////////////////////////////////////////////////////
-#pragma mark - 设备管理接口
-/// @name 设备管理接口
+/// @name 设备管理相关接口
/// @{
/**
- * 5.1 获取设备管理类 TXDeviceManager
+ * 6.1 获取设备管理类（TXDeviceManager）
*/
- (TXDeviceManager *)getDeviceManager;
-/// @}
-
+/// @}
/////////////////////////////////////////////////////////////////////////////////
//
-// （六）美颜特效和图像水印
+// 美颜特效和图像水印
//
/////////////////////////////////////////////////////////////////////////////////
-#pragma mark - 美颜特效和变脸特效
-/// @name 美颜特效和变脸特效
+/// @name 美颜特效和图像水印
/// @{
/**
- * 6.1 获取美颜管理对象
+ * 7.1 获取美颜管理类（TXBeautyManager）
*
* 通过美颜管理，您可以使用以下功能：
- * - 设置"美颜风格"、“美白”、“红润”、“大眼”、“瘦脸”、“V脸”、“下巴”、“短脸”、“小鼻”、“亮眼”、“白牙”、“祛眼袋”、“祛皱纹”、“祛法令纹”等美容效果。
- * - 调整“发际线”、“眼间距”、“眼角”、“嘴形”、“鼻翼”、“鼻子位置”、“嘴唇厚度”、“脸型”
- * - 设置人脸挂件（素材）等动态效果
- * - 添加美妆
- * - 进行手势识别
+ * - 设置"磨皮"、“美白”、“红润”等美颜特效。
+ * - 设置“大眼”、“瘦脸”、“V脸”、“下巴”、“短脸”、“小鼻”、“亮眼”、“白牙”、“祛眼袋”、“祛皱纹”、“祛法令纹”等修脸特效。
+ * - 设置“发际线”、“眼间距”、“眼角”、“嘴形”、“鼻翼”、“鼻子位置”、“嘴唇厚度”、“脸型”等修脸特效。
+ * - 设置"眼影"、“腮红”等美妆特效。
+ * - 设置动态贴纸和人脸挂件等动画特效。
*/
- (TXBeautyManager *)getBeautyManager;
/**
- * 6.2 添加水印
+ * 7.2 添加水印
*
- * 水印的位置是通过 rect 来指定的，rect 的格式为 (x，y，width，height)
+ * 水印的位置是通过 rect 参数来指定的，rect 是一个四元组参数，其格式为 (x，y，width，height)
* - x：水印的坐标，取值范围为0 - 1的浮点数。
* - y：水印的坐标，取值范围为0 - 1的浮点数。
* - width：水印的宽度，取值范围为0 - 1的浮点数。
* - height：是不用设置的，SDK 内部会根据水印图片的宽高比自动计算一个合适的高度。
*
- * 例如，如果当前编码分辨率是540 × 960，rect 设置为（0.1，0.1，0.2，0.0）。
- * 那么水印的左上坐标点就是（540 × 0.1，960 × 0.1）即（54，96），水印的宽度是 540 × 0.2 = 108px，高度自动计算。
+ * 参数设置举例：
+ * 如果当前视频的编码分辨率是 540 × 960，且 rect 参数被您设置为（0.1，0.1，0.2，0.0），
+ * 那么水印的左上坐标点就是（540 × 0.1，960 × 0.1）即（54，96），水印的宽度是 540 × 0.2 = 108px，水印的高度会根据水印图片的宽高比由 SDK 自动算出。
*
- * @param image 水印图片，**必须使用透明底的 png 格式**
- * @param streamType 如果要给辅路画面（TRTCVideoStreamTypeSub，一般用于屏幕分享）也设置水印，需要调用两次的 setWatermark。
+ * @param image 水印图片，**必须使用透明底色的 png 格式**
+ * @param streamType 指定给哪一路画面设置水印，详情请参考{@link TRTCVideoStreamType}。
* @param rect 水印相对于编码分辨率的归一化坐标，x，y，width，height 取值范围0 - 1。
+ * @note 如果您要给主画面（一般为摄像头）和辅路画面（一般用作屏幕分享）同时设置水印，需要调用该接口两次，并设定不同的 streamType。
*/
-- (void)setWatermark:(TXImage*)image streamType:(TRTCVideoStreamType)streamType rect:(CGRect)rect;
+- (void)setWatermark:(TXImage *)image streamType:(TRTCVideoStreamType)streamType rect:(CGRect)rect;
/// @}
-
-
/////////////////////////////////////////////////////////////////////////////////
//
-// （七）音乐特效和人声特效
+// 背景音乐和声音特效
//
/////////////////////////////////////////////////////////////////////////////////
-#pragma mark - 音乐特效和人声特效
-/// @name 音乐特效和人声特效
+/// @name 背景音乐和声音特效
/// @{
/**
-* 7.1 获取音效管理类 TXAudioEffectManager
-*
-* 该模块是整个 SDK 的音效管理模块，支持如下功能：
-* - 耳机耳返：麦克风捕捉的声音实时通过耳机播放。
-* - 混响效果：KTV、小房间、大会堂、低沉、洪亮...
-* - 变声特效：萝莉、大叔、重金属、外国人...
-* - 背景音乐：支持在线音乐和本地音乐，支持变速、变调等特效、支持原生和伴奏并播放和循环播放。
-* - 短音效：鼓掌声、欢笑声等简短的音效文件，对于小于10秒的文件，请将 isShortFile 参数设置为 YES。
-*/
+ * 8.1 获取音效管理类（TXAudioEffectManager）
+ *
+ * TXAudioEffectManager 是音效管理接口，您可以通过该接口实现如下功能：
+ * - 背景音乐：支持在线音乐和本地音乐，支持变速、变调等特效、支持原生和伴奏并播放和循环播放。
+ * - 耳机耳返：麦克风捕捉的声音实时通过耳机播放，常用于音乐直播。
+ * - 混响效果：KTV、小房间、大会堂、低沉、洪亮...
+ * - 变声特效：萝莉、大叔、重金属...
+ * - 短音效：鼓掌声、欢笑声等简短的音效文件（对于小于10秒的文件，请将 isShortFile 参数设置为 true）。
+ */
- (TXAudioEffectManager *)getAudioEffectManager;
-/// @}
-
-/////////////////////////////////////////////////////////////////////////////////
-//
-// （八）屏幕分享相关接口函数
-//
-/////////////////////////////////////////////////////////////////////////////////
-#pragma mark - 屏幕分享相关接口函数
-/// @name 屏幕分享相关接口函数
-/// @{
-
-#if TARGET_OS_IPHONE
/**
- * 8.1 开始应用内的屏幕分享（该接口仅支持 iOS 13.0 及以上的 iPhone 和 iPad）
- *
- * iPhone 屏幕分享的推荐配置参数：
- * - 分辨率(videoResolution): 1280 x 720
- * - 帧率(videoFps): 10 FPS
- * - 码率(videoBitrate): 1600 kbps
- * - 分辨率自适应(enableAdjustRes): NO
+ * 8.2 开启系统声音采集（仅适用于 Mac 系统）
*
- * @param encParams 设置屏幕分享时的编码参数，推荐采用上述推荐配置，如果您指定 encParams 为 nil，则使用您调用 startScreenCapture 之前的编码参数设置。
+ * 该接口会从电脑的声卡中采集音频数据，并将其混入到 SDK 当前的音频数据流中，从而使房间中的其他用户也能听到主播的电脑所播放出的声音。
+ * 在线教育场景中，老师可以使用此功能让 SDK 采集教学影片中的声音，并广播给同房间中的学生。
+ * 音乐直播场景中，主播可以使用此功能让 SDK 采集音乐播放器中的音乐，从而为自己的直播间增加背景音乐。
+ * @note
+ * 1. 此功能需要为用户的 Mac 系统安装虚拟音频设备插件，安装完成后，SDK 会从已经安装的虚拟音频设备中采集声音。
+ * 2. SDK 会自动从网络上下载合适的插件进行安装，但是下载速度可能比较慢，如果您希望加速这个过程，可以将虚拟音频插件文件打包到您 App Bundle 的 Resources 目录下。
*/
-- (void)startScreenCaptureInApp:(TRTCVideoEncParam *)encParams API_AVAILABLE(ios(13.0));
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
+- (void)startSystemAudioLoopback;
+#endif
/**
- * 8.2 开始全系统的屏幕分享（该接口支持 iOS 11.0 及以上的 iPhone 和 iPad）
- *
- * 该接口支持共享整个 iOS 系统的屏幕，可以实现类似腾讯会议的全系统级的屏幕分享。
- * 但是实现复杂度要比 startScreenCaptureInApp 略繁琐一些，需要参考文档为 App 实现一个 Replaykit 扩展模块。
- *
- * 参考文档：[屏幕录制]https://cloud.tencent.com/document/product/647/32249
- *
- * iPhone 屏幕分享的推荐配置参数：
- * - 分辨率(videoResolution): 1280 x 720
- * - 帧率(videoFps): 10 FPS
- * - 码率(videoBitrate): 1600 kbps
- * - 分辨率自适应(enableAdjustRes): NO
+ * 8.3 停止系统声音采集（仅适用于桌面系统）
+ */
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
+- (void)stopSystemAudioLoopback;
+#endif
+
+/**
+ * 8.4 设置系统声音的采集音量
*
- * @param encParams 设置屏幕分享时的编码参数，推荐采用上述推荐配置，如果您指定 encParams 为 nil，则使用您调用 startScreenCapture 之前的编码参数设置。
- * @param appGroup 主 App 与 Broadcast 共享的 Application Group Identifier，可以指定为 nil，但按照文档设置会使功能更加可靠。
+ * @param volume 设置的音量大小，范围是：[0 ~ 150]，默认值为100。
*/
-- (void)startScreenCaptureByReplaykit:(TRTCVideoEncParam *)encParams
- appGroup:(NSString *)appGroup API_AVAILABLE(ios(11.0));
+- (void)setSystemAudioLoopbackVolume:(uint32_t)volume;
+
+/// @}
+/////////////////////////////////////////////////////////////////////////////////
+//
+// 屏幕分享相关接口
+//
+/////////////////////////////////////////////////////////////////////////////////
+/// @name 屏幕分享相关接口
+/// @{
/**
- * 8.3 开始应用内的屏幕分享（该接口仅支持 iOS 13.0 及以上的 iPhone 和 iPad）
+ * 9.1 开始应用内的屏幕分享（仅支持 iOS 13.0 及以上系统）
*
- * iPhone 屏幕分享的推荐配置参数：
- * - 分辨率(videoResolution): 1280 x 720
- * - 帧率(videoFps): 10 FPS
- * - 码率(videoBitrate): 1600 kbps
- * - 分辨率自适应(enableAdjustRes): NO
+ * 该接口会抓取当前应用内的实时屏幕内容并将其分享给同房间中的其他用户，适用于 13.0 以上的 iOS 系统。
+ * 如果您希望抓取整个 iOS 系统的屏幕内容（而不受当前应用的限制），推荐使用 {@link startScreenCaptureByReplaykit}。
+ * iPhone 推荐的屏幕分享视频编码参数（{@link TRTCVideoEncParam}）：
+ * - 分辨率(videoResolution): 1280 x 720
+ * - 帧率(videoFps): 10 FPS
+ * - 码率(videoBitrate): 1600 kbps
+ * - 分辨率自适应(enableAdjustRes): NO
*
* @param streamType 屏幕分享使用的线路，可以设置为主路（TRTCVideoStreamTypeBig）或者辅路（TRTCVideoStreamTypeSub）。
- * @param encParams 设置屏幕分享时的编码参数，推荐采用上述推荐配置，如果您指定 encParams 为 nil，则使用您调用 startScreenCapture 之前的编码参数设置。
+ * @param encParams 设置屏幕分享时的视频编码参数，推荐采用上述推荐配置。
+ * 如果您指定 encParams 为 nil，SDK 会使用您在调用 startScreenCapture 接口之前所设置的视频编码参数。
*/
+#if TARGET_OS_IPHONE
- (void)startScreenCaptureInApp:(TRTCVideoStreamType)streamType encParam:(TRTCVideoEncParam *)encParams API_AVAILABLE(ios(13.0));
+#endif
/**
- * 8.4 开始全系统的屏幕分享（该接口支持 iOS 11.0 及以上的 iPhone 和 iPad）
- *
- * 该接口支持共享整个 iOS 系统的屏幕，可以实现类似腾讯会议的全系统级的屏幕分享。
- * 但是实现复杂度要比 startScreenCaptureInApp 略繁琐一些，需要参考文档为 App 实现一个 Replaykit 扩展模块。
- *
- * 参考文档：[屏幕录制]https://cloud.tencent.com/document/product/647/32249
+ * 9.1 开始全系统的屏幕分享（仅支持 iOS 11.0 及以上系统）
*
- * iPhone 屏幕分享的推荐配置参数：
- * - 分辨率(videoResolution): 1280 x 720
- * - 帧率(videoFps): 10 FPS
- * - 码率(videoBitrate): 1600 kbps
- * - 分辨率自适应(enableAdjustRes): NO
+ * 该接口支持抓取整个 iOS 系统的屏幕，可以实现类似腾讯会议的全系统级的屏幕分享。
+ * 但对接步骤要比 {@link startScreenCaptureInApp} 略繁琐一些，需要为您的应用实现一个 Replaykit 扩展模块。
+ * 参考文档：[实时屏幕分享(iOS)](https://cloud.tencent.com/document/product/647/45750)
+ * iPhone 推荐的屏幕分享视频编码参数（{@link TRTCVideoEncParam}）：
+ * - 分辨率(videoResolution): 1280 x 720
+ * - 帧率(videoFps): 10 FPS
+ * - 码率(videoBitrate): 1600 kbps
+ * - 分辨率自适应(enableAdjustRes): NO
*
- * @param streamType 屏幕分享使用的线路，可以设置为主路（TRTCVideoStreamTypeBig）或者辅路（TRTCVideoStreamTypeSub），默认使用辅路。
- * @param encParams 设置屏幕分享时的编码参数，推荐采用上述推荐配置，如果您指定 encParams 为 nil，则使用您调用 startScreenCapture 之前的编码参数设置。
- * @param appGroup 主 App 与 Broadcast 共享的 Application Group Identifier，可以指定为 nil，但按照文档设置会使功能更加可靠。
+ * @param streamType 屏幕分享使用的线路，可以设置为主路（TRTCVideoStreamTypeBig）或者辅路（TRTCVideoStreamTypeSub）。
+ * @param encParams 设置屏幕分享时的视频编码参数，推荐采用上述推荐配置。如果您指定 encParams 为 nil，SDK 会使用您在调用 startScreenCapture 接口之前所设置的视频编码参数。
+ * @param appGroup 用于指定您的应用与录屏进程共享的 Application Group Identifier，您可以指定该参数为 nil，但推荐您按照文档指示进行设置，从而获得更好的可靠性。
*/
-- (void)startScreenCaptureByReplaykit:(TRTCVideoStreamType)streamType encParam:(TRTCVideoEncParam *)encParams
- appGroup:(NSString *)appGroup API_AVAILABLE(ios(11.0));
-
-#elif TARGET_OS_MAC
+#if TARGET_OS_IPHONE
+- (void)startScreenCaptureByReplaykit:(TRTCVideoStreamType)streamType encParam:(TRTCVideoEncParam *)encParams appGroup:(NSString *)appGroup API_AVAILABLE(ios(11.0));
+#endif
/**
- * 8.3 开始桌面端屏幕分享（该接口仅支持 Mac OS 桌面系统）
+ * 9.1 开始桌面端屏幕分享（该接口仅支持桌面系统）
*
- * @param view 渲染控件所在的父控件，可以设置为 nil，表示不显示屏幕分享的预览效果。
- * @param streamType 屏幕分享使用的线路，可以设置为主路（TRTCVideoStreamTypeBig）或者辅路（TRTCVideoStreamTypeSub），默认使用辅路。
+ * 该接口可以抓取整个 Mac OS 系统的屏幕内容，或抓取您指定的某个应用的窗口内容，并将其分享给同房间中的其他用户。
+ * @param view 渲染控件所在的父控件，可以设置为空值，表示不显示屏幕分享的预览效果。
+ * @param streamType 屏幕分享使用的线路，可以设置为主路（TRTCVideoStreamTypeBig）或者辅路（TRTCVideoStreamTypeSub），推荐使用辅路。
* @param encParam 屏幕分享的画面编码参数，SDK 会优先使用您通过此接口设置的编码参数：
- * - 如果 encParam 设置为 nil，且您已通过 setSubStreamEncoderParam 设置过辅路视频编码参数，SDK 将使用您设置过的辅路编码参数进行屏幕分享。
- * - 如果 encParam 设置为 nil，且您未通过 setSubStreamEncoderParam 设置过辅路视频编码参数，SDK 将自适应选择最佳的编码参数进行屏幕分享。
+ * - 如果您设置 encParam 为 nil，且您已通过 setSubStreamEncoderParam 设置过辅路视频编码参数，SDK 将使用您设置过的辅路编码参数进行屏幕分享。
+ * - 如果您设置 encParam 为 nil，且您未通过 setSubStreamEncoderParam 设置过辅路视频编码参数，SDK 将自动选择一个最佳的编码参数进行屏幕分享。
*
- * @note 一个用户同时最多只能上传一条主路（TRTCVideoStreamTypeBig）画面和一条辅路（TRTCVideoStreamTypeSub）画面，
- * 默认情况下，屏幕分享使用辅路画面，如果使用主路画面，建议您提前停止摄像头采集（stopLocalPreview）避免相互冲突。
+ * @note
+ * 1. 同一个用户同时最多只能发布一路主路（{@link TRTCVideoStreamTypeBig}）画面和一路辅路（{@link TRTCVideoStreamTypeSub}）画面。
+ * 2. 默认情况下，屏幕分享使用辅路画面。如果使用主路做屏幕分享，您需要提前停止摄像头采集（{@link stopLocalPreview}）以避免相互冲突。
+ * 3. 同一个房间中同时只能有一个用户使用辅路做屏幕分享，也就是说，同一个房间中同时只允许一个用户开启辅路。
+ * 4. 当房间中已经有其他用户在使用辅路分享屏幕时，此时调用该接口会收到来自 {@link TRTCCloudDelegate} 的 onError(ERR_SERVER_CENTER_ANOTHER_USER_PUSH_SUB_VIDEO) 回调。
*/
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
- (void)startScreenCapture:(NSView *)view streamType:(TRTCVideoStreamType)streamType encParam:(TRTCVideoEncParam *)encParam;
#endif
/**
- * 8.4 停止屏幕采集
- *
- * @return 0：成功；<0：失败
+ * 9.2 停止屏幕分享
*/
- (int)stopScreenCapture API_AVAILABLE(ios(11.0));
/**
- * 8.5 暂停屏幕分享
- *
- * @return 0：成功；<0：失败
+ * 9.3 暂停屏幕分享
*/
- (int)pauseScreenCapture API_AVAILABLE(ios(11.0));
/**
- * 8.6 恢复屏幕分享
- *
- * @return 0：成功；<0：失败
+ * 9.4 恢复屏幕分享
*/
- (int)resumeScreenCapture API_AVAILABLE(ios(11.0));
-#if !TARGET_OS_IPHONE && TARGET_OS_MAC
/**
- * 8.7 枚举可分享的屏幕窗口，仅支持 Mac OS 平台，建议在 startScreenCapture 之前调用
- *
- * 如果您要给您的 App 增加屏幕分享功能，一般需要先显示一个窗口选择界面，这样用户可以选择希望分享的窗口。
- * 通过下列函数，您可以获得可分享窗口的 ID、类型、窗口名称以及缩略图。
- * 获取上述信息后，您就可以实现一个窗口选择界面。您也可以使用 Demo 源码中已经实现好的窗口选择界面。
- *
- * @note 返回的列表中包括屏幕和应用窗口，屏幕会在列表的前面几个元素中。
+ * 9.5 枚举可分享的屏幕和窗口（该接口仅支持 Mac OS 系统）
*
+ * 当您在对接桌面端系统的屏幕分享功能时，一般都需要展示一个选择分享目标的界面，这样用户能够使用这个界面选择是分享整个屏幕还是某个窗口。
+ * 通过本接口，您就可以查询到当前系统中可用于分享的窗口的 ID、名称以及缩略图。我们在 Demo 中提供了一份默认的界面实现供您参考。
+ * @note 返回的列表中包含屏幕和应用窗口，屏幕是列表中的第一个元素。如果用户有多个显示器，那么每个显示器都是一个分享目标。
* @param thumbnailSize 指定要获取的窗口缩略图大小，缩略图可用于绘制在窗口选择界面上
* @param iconSize 指定要获取的窗口图标大小
* @return 窗口列表包括屏幕
*/
-- (NSArray<TRTCScreenCaptureSourceInfo*>*)getScreenCaptureSourcesWithThumbnailSize:(CGSize)thumbnailSize iconSize:(CGSize)iconSize;
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
+- (NSArray<TRTCScreenCaptureSourceInfo *> *)getScreenCaptureSourcesWithThumbnailSize:(CGSize)thumbnailSize iconSize:(CGSize)iconSize;
+#endif
/**
- * 8.8 设置屏幕分享参数，仅支持 Mac OS 平台，该方法在屏幕分享过程中也可以调用
- *
- * 如果您期望在屏幕分享的过程中，切换想要分享的窗口，可以再次调用这个函数，无需重新开启屏幕分享。
+ * 9.6 选取要分享的屏幕或窗口（该接口仅支持 Mac OS 系统）
*
+ * 当您通过 getScreenCaptureSources 获取到可以分享的屏幕和窗口之后，您可以调用该接口选定期望分享的目标屏幕或目标窗口。
+ * 在屏幕分享的过程中，您也可以随时调用该接口以切换分享目标。
* @param screenSource 指定分享源
- * @param rect 指定捕获的区域
+ * @param rect 指定捕获的区域（设定该参数为 CGRectZero：当分享目标是某个窗口时则分享整个窗口，当分享目标是桌面时则分享整个桌面）
* @param capturesCursor 是否捕获鼠标光标
* @param highlight 是否高亮正在分享的窗口
- * @note 当 rect 传递 CGRectZero 时：若分享目标是某一个 Mac 窗口时则默认分享整个窗口，当分享目标是 Mac 桌面时则默认分享整个桌面
- *
*/
-- (void)selectScreenCaptureTarget:(TRTCScreenCaptureSourceInfo *)screenSource
- rect:(CGRect)rect
- capturesCursor:(BOOL)capturesCursor
- highlight:(BOOL)highlight;
-
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
+- (void)selectScreenCaptureTarget:(TRTCScreenCaptureSourceInfo *)screenSource rect:(CGRect)rect capturesCursor:(BOOL)capturesCursor highlight:(BOOL)highlight;
#endif
/**
- * 8.9 设置辅路视频的编码器参数，适用 iOS、Mac 平台
- * - setVideoEncoderParam() 用于设置主路画面（TRTCVideoStreamTypeBig，一般用于摄像头）的编码参数。
- * - setSubStreamEncoderParam() 用于设置辅路画面（TRTCVideoStreamTypeSub，一般用于屏幕分享或者自定义辅路）的编码参数。
- * 该设置决定远端用户看到的画面质量，同时也是云端录制出的视频文件的画面质量。
+ * 9.7 设置屏幕分享（即辅路）的视频编码参数（该接口仅支持桌面系统）
+ *
+ * 该接口可以设定远端用户所看到的屏幕分享（即辅路）的画面质量，同时也能决定云端录制出的视频文件中屏幕分享的画面质量。
+ * 请注意如下两个接口的差异：
+ * - {@link setVideoEncoderParam} 用于设置主路画面（{@link TRTCVideoStreamTypeBig}，一般用于摄像头）的视频编码参数。
+ * - {@link setSubStreamEncoderParam} 用于设置辅路画面（{@link TRTCVideoStreamTypeSub}，一般用于屏幕分享）的视频编码参数。
*
- * @param param 辅流编码参数，详情请参考 TRTCCloudDef.h 中的 TRTCVideoEncParam 定义
- * @note 即使使用主路传输屏幕分享的数据（在调用 startScreenCapture 时设置 type = TRTCVideoStreamTypeBig），依然要使用此接口更新屏幕分享或者自定义辅路的编码参数。
+ * @param param 辅流编码参数，详情请参考 {@link TRTCVideoEncParam}。
+ * @note 即使您使用主路传输屏幕分享（在调用 startScreenCapture 时设置 type=TRTCVideoStreamTypeBig），依然要使用 {@link setSubStreamEncoderParam} 设定屏幕分享的编码参数，而不要使用 {@link setVideoEncoderParam} 。
*/
- (void)setSubStreamEncoderParam:(TRTCVideoEncParam *)param;
-
-#if !TARGET_OS_IPHONE && TARGET_OS_MAC
-
/**
- * 8.10 设置屏幕分享的混音音量大小，仅适用 Mac 平台
+ * 9.8 设置屏幕分享时的混音音量大小（该接口仅支持桌面系统）
*
- * 数值越高，辅路音量的占比越高，麦克风音量占比越小。不推荐将该参数值设置过大，数值太大容易压制麦克风的声音。
- *
- * @param volume 设置的音量大小，范围0 - 100
+ * 这个数值越高，屏幕分享音量的占比就越高，麦克风音量占比就越小，所以不推荐设置得太大，否则麦克风的声音就被压制了。
+ * @param volume 设置的混音音量大小，范围0 - 100。
*/
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
- (void)setSubStreamMixVolume:(NSInteger)volume;
+#endif
/**
- * 8.11 将指定窗口加入屏幕分享的排除列表中，加入排除列表中的窗口不会被分享出去，仅适用 Mac 平台
+ * 9.9 将指定窗口加入屏幕分享的排除列表中（该接口仅支持桌面系统）
*
+ * 加入排除列表中的窗口不会被分享出去，常见的用法是将某个应用的窗口加入到排除列表中以避免隐私问题。
* 支持启动屏幕分享前设置过滤窗口，也支持屏幕分享过程中动态添加过滤窗口。
- *
- * @param windowID 不希望分享出去的窗口ID
+ * @param windowID 不希望分享出去的窗口
+ * @note
+ * 1. 该接口只有在 {@link TRTCScreenCaptureSourceInfo} 中的 type 指定为 {@link TRTCScreenCaptureSourceTypeScreen} 时生效，即只有在分享整个屏幕内容时，排除指定窗口的功能才生效。
+ * 2. 使用该接口添加到排除列表中的窗口会在退出房间后被 SDK 自动清除。
+ * 3. Mac 平台下请传入窗口 ID（即 CGWindowID），您可以通过 {@link TRTCScreenCaptureSourceInfo} 中的 sourceId 成员获得。
*/
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
- (void)addExcludedShareWindow:(NSInteger)windowID;
+#endif
/**
- * 8.12 将指定窗口从屏幕分享的排除列表中移除，仅适用 Mac 平台
+ * 9.10 将指定窗口从屏幕分享的排除列表中移除（该接口仅支持桌面系统）
*
- * @param windowID 不希望分享出去的窗口ID
+ * @param windowID
*/
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
- (void)removeExcludedShareWindow:(NSInteger)windowID;
+#endif
/**
- * 8.13 将所有窗口从屏幕分享的排除列表中移除，仅适用 Mac 平台
+ * 9.11 将所有窗口从屏幕分享的排除列表中移除（该接口仅支持桌面系统）
*/
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
- (void)removeAllExcludedShareWindows;
+#endif
/**
- * 8.14 将指定窗口加入窗口分享的包含列表中，加入包含列表中的窗口会被一起分享出去，仅适用 Mac 平台
+ * 9.12 将指定窗口加入屏幕分享的包含列表中（该接口仅支持桌面系统）
*
- * 支持启动屏幕分享前设置指定窗口，也支持屏幕分享过程中动态添加指定窗口。
- *
- * @param windowID 希望分享出去的窗口ID
+ * 该接口只有在 {@link TRTCScreenCaptureSourceInfo} 中的 type 指定为 {@link TRTCScreenCaptureSourceTypeWindow} 时生效。即只有在分享窗口内容时，额外包含指定窗口的功能才生效。
+ * 您在 {@link startScreenCapture} 之前和之后调用均可。
+ * @param windowID 希望被分享出去的窗口（Windows 平台下为窗口句柄： HWND）
+ * @note 通过该方法添加到包含列表中的窗口，会在退出房间后被 SDK 自动清除。
*/
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
- (void)addIncludedShareWindow:(NSInteger)windowID;
+#endif
/**
- * 8.15 将指定窗口从窗口分享的包含列表中移除，仅适用 Mac 平台
+ * 9.13 将指定窗口从屏幕分享的包含列表中移除（该接口仅支持桌面系统）
*
- * @param windowID 不希望分享出去的窗口ID
+ * 该接口只有在 {@link TRTCScreenCaptureSourceInfo} 中的 type 指定为 {@link TRTCScreenCaptureSourceTypeWindow} 时生效。
+ * 即只有在分享窗口内容时，额外包含指定窗口的功能才生效。
+ * @param windowID 希望被分享出去的窗口（Mac 平台: 窗口 ID；Windows 平台： HWND）
*/
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
- (void)removeIncludedShareWindow:(NSInteger)windowID;
+#endif
/**
- * 8.16 将所有窗口从窗口分享的包含列表中移除，仅适用 Mac 平台
+ * 9.14 将全部窗口从屏幕分享的包含列表中移除（该接口仅支持桌面系统）
+ *
+ * 该接口只有在 {@link TRTCScreenCaptureSourceInfo} 中的 type 指定为 {@link TRTCScreenCaptureSourceTypeWindow} 时生效。
+ * 即只有在分享窗口内容时，额外包含指定窗口的功能才生效。
*/
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
- (void)removeAllIncludedShareWindows;
-
#endif
-/// @}
+/// @}
/////////////////////////////////////////////////////////////////////////////////
//
-// （九）自定义采集和渲染
+// 自定义采集和自定义渲染
//
/////////////////////////////////////////////////////////////////////////////////
-#pragma mark - 自定义采集和渲染
-/// @name 自定义采集和渲染
+/// @name 自定义采集和自定义渲染
/// @{
+
/**
- * 9.1 启用自定义视频采集模式
+ * 10.1 启用/关闭视频自定义采集模式
*
- * 开启该模式后，SDK 不再运行原有视频流上的采集流程，只保留编码和发送能力。
- * 您需要用 sendCustomVideoData:frame: 不断地向 SDK 指定 streamType 塞入自己采集的视频画面。
- *
- * @param streamType 视频流类型：
- * - 高清大画面：TRTCVideoStreamTypeBig
- * - 辅流：TRTCVideoStreamTypeSub
- * @param enable 是否启用，默认值：NO
+ * 开启该模式后，SDK 不在运行原有的视频采集流程，即不再继续从摄像头采集数据和美颜，而是只保留视频编码和发送能力。
+ * 您需要通过 {@link sendCustomVideoData} 不断地向 SDK 塞入自己采集的视频画面。
+ * @param streamType 用于指定视频流类型，{@link TRTCVideoStreamTypeBig}：高清大画面；{@link TRTCVideoStreamTypeSub}：辅路画面。
+ * @param enable 是否启用，默认值：false。
*/
- (void)enableCustomVideoCapture:(TRTCVideoStreamType)streamType enable:(BOOL)enable;
/**
- * 9.2 向 SDK 中指定 streamType 投送自己采集的视频数据
+ * 10.2 向 SDK 投送自己采集的视频帧
*
- * TRTCVideoFrame 推荐下列填写方式（其他字段不需要填写）：
- * - pixelFormat：推荐选择 TRTCVideoPixelFormat_NV12。
- * - bufferType：推荐选择 TRTCVideoBufferType_PixelBuffer。
- * - pixelBuffer：iOS/Mac 平台上常用的视频数据格式。
+ * 使用此接口可以向 SDK 投送自己采集的视频帧，SDK 会将视频帧进行编码并通过自身的网络模块传输出去。
+ * 参数 {@link TRTCVideoFrame} 推荐下列填写方式（其他字段不需要填写）：
+ * - pixelFormat：推荐选择 {@link TRTCVideoPixelFormat_NV12}。
+ * - bufferType：推荐选择 {@link TRTCVideoBufferType_PixelBuffer}。
+ * - pixelBuffer：iOS/Mac OS 平台上常用的视频数据格式。
* - data：视频裸数据格式，bufferType 为 NSData 时使用。
- * - timestamp：时间戳，单位毫秒（ms）。如果 timestamp 间隔不均匀，会严重影响音画同步和录制出的 MP4 质量。
+ * - timestamp：时间戳，单位为毫秒（ms），请使用视频帧在采集时被记录下来的时间戳（可以在采集到一帧视频帧之后，通过调用 {@link generateCustomPTS} 获取时间戳）。
* - width：视频图像长度，bufferType 为 NSData 时填写。
* - height：视频图像宽度，bufferType 为 NSData 时填写。
*
* 参考文档：[自定义采集和渲染](https://cloud.tencent.com/document/product/647/34066)。
- *
- * @param streamType 自定义视频流类型：
- * - 高清大画面：TRTCVideoStreamTypeBig
- * - 辅流：TRTCVideoStreamTypeSub
+ * @param streamType 用于指定视频流类型，{@link TRTCVideoStreamTypeBig}：高清大画面；{@link TRTCVideoStreamTypeSub}：辅路画面。
* @param frame 视频数据，支持 PixelBuffer NV12，BGRA 以及 I420 格式数据。
- * @note - SDK 内部有帧率控制逻辑，目标帧率以您在 setVideoEncoderParam (高清大画面) 或者 setSubStreamEncoderParam (辅流) 中设置的为准。
- * @note - 可以设置 frame 中的 timestamp 为 0，相当于让 SDK 自己设置时间戳，但请“均匀”地控制 sendCustomVideoData 的调用间隔，否则会导致视频帧率不稳定。
+ * @note
+ * 1. 推荐您在采集到的一帧视频帧后，即调用 {@link generateCustomPTS} 接口获取该帧的 timestamp 数值，这样可以获得最佳的音画同步效果。
+ * 2. SDK 最终编码出的视频帧率并不是由您调用本接口的频率决定的，而是由您在 {@link setVideoEncoderParam} 中所设置的 FPS 决定的。
+ * 3. 请尽量保持本接口的调用间隔是均匀的，否则会导致编码器输出帧率不稳或者音画不同步等问题。
*/
- (void)sendCustomVideoData:(TRTCVideoStreamType)streamType frame:(TRTCVideoFrame *)frame;
/**
- * 9.3 第三方美颜的视频数据回调
+ * 10.3 启用音频自定义采集模式
*
- * 设置此方法后，SDK 内部会在本地渲染前，把采集到的视频纹理回调出来，用于第三方美颜处理。
- *
- * @param delegate 自定义预处理回调，详见 {@link TRTCVideoFrameDelegate}
- * @param pixelFormat 指定回调的像素格式
- * @param bufferType 指定回调的数据格式
- * @return 0：成功；<0：错误
+ * 开启该模式后，SDK 不在运行原有的音频采集流程，即不再继续从麦克风采集音频数据，而是只保留音频编码和发送能力。
+ * 您需要通过 {@link sendCustomAudioData} 不断地向 SDK 塞入自己采集的音频数据。
+ * @param enable 是否启用，默认值：false。
+ * @note 由于回声抵消（AEC）需要严格的控制声音采集和播放的时间，所以开启自定义音频采集后，AEC 能力可能会失效。
*/
-- (int)setLocalVideoProcessDelegete:(id<TRTCVideoFrameDelegate>)delegate pixelFormat:(TRTCVideoPixelFormat)pixelFormat bufferType:(TRTCVideoBufferType)bufferType;
+- (void)enableCustomAudioCapture:(BOOL)enable;
/**
- * 9.4 设置本地视频的自定义渲染回调
+ * 10.4 向 SDK 投送自己采集的音频数据
*
- * 设置此方法后，SDK 内部会跳过原来的渲染流程，并把采集到的数据回调出来，您需要自己完成画面渲染。
- * - pixelFormat 指定回调的数据格式，例如 NV12、i420 以及 32BGRA。
- * - bufferType 指定 buffer 的类型，直接使用 PixelBuffer 效率最高；使用 NSData 相当于让 SDK 在内部做了一次内存转换，因此会有额外的性能损耗。
+ * 参数 {@link TRTCAudioFrame} 推荐下列填写方式（其他字段不需要填写）：
+ * - audioFormat：音频数据格式，仅支持 TRTCAudioFrameFormatPCM。
+ * - data：音频帧 buffer。音频帧数据只支持 PCM 格式，支持[5ms ~ 100ms]帧长，推荐使用 20ms 帧长，长度计算方法：【48000采样率、单声道的帧长度：48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节】。
+ * - sampleRate：采样率，支持：16000、24000、32000、44100、48000。
+ * - channel：声道数（如果是立体声，数据是交叉的），单声道：1； 双声道：2。
+ * - timestamp：时间戳，单位为毫秒（ms），请使用音频帧在采集时被记录下来的时间戳（可以在采集到一帧音频帧之后，通过调用 {@link generateCustomPTS} 获取时间戳）。
*
- * @param delegate 自定义渲染回调
- * @param pixelFormat 指定回调的像素格式
- * @param bufferType PixelBuffer：可以直接使用 imageWithCVImageBuffer 转成 UIImage；NSData：经过内存整理的视频数据。
- * @return 0：成功；<0：错误
+ * 参考文档：[自定义采集和渲染](https://cloud.tencent.com/document/product/647/34066)。
+ * @param frame 音频数据
+ * @note 请您精准地按每帧时长的间隔调用本接口，数据投送间隔不均匀时极易触发声音卡顿。
*/
-- (int)setLocalVideoRenderDelegate:(id<TRTCVideoRenderDelegate>)delegate pixelFormat:(TRTCVideoPixelFormat)pixelFormat bufferType:(TRTCVideoBufferType)bufferType;
+- (void)sendCustomAudioData:(TRTCAudioFrame *)frame;
+
+/**
+ * 10.5 启用/关闭自定义音轨
+ *
+ * 开启后，您可以通过本接口向 SDK 混入一条自定义的音轨。通过两个布尔型参数，您可以控制该音轨是否要在远端和本地播放。
+ * @param enablePublish 控制混入的音轨是否要在远端播放，默认值：false。
+ * @param enablePlayout 控制混入的音轨是否要在本地播放，默认值：false。
+ * @note 如果您指定参数 enablePublish 和 enablePlayout 均为 false，代表完全关闭您的自定义音轨。
+ */
+- (void)enableMixExternalAudioFrame:(BOOL)enablePublish playout:(BOOL)enablePlayout;
/**
- * 9.5 设置远端视频的自定义渲染回调
+ * 10.6 向 SDK 混入自定义音轨
*
- * 此方法同 setLocalVideoRenderDelegate，区别在于一个是本地画面的渲染回调， 一个是远程画面的渲染回调。
+ * 调用该接口之前，您需要先通过 {@link enableMixExternalAudioFrame} 开启自定义音轨，之后就可以通过本接口将自己的音轨以 PCM 格式混入到 SDK 中。
+ * 理想情况下，我们期望您的代码能够以非常均匀的速度向 SDK 提供音轨数据。但我们也非常清楚，完美的调用间隔是一个巨大的挑战。
+ * 所以 SDK 内部会开启一个音轨数据的缓冲区，该缓冲区的作用类似一个“蓄水池”，它能够暂存您传入的音轨数据，平抑由于接口调用间隔的抖动问题。
+ * 本接口的返回值代表这个音轨缓冲区的大小，单位是毫秒（ms），比如：如果该接口返回 50，则代表当前的音轨缓冲区有 50ms 的音轨数据。因此只要您在 50ms 内再次调用本接口，SDK 就能保证您混入的音轨数据是连续的。
+ * 当您调用该接口后，如果发现返回值 > 100ms，则可以等待一帧音频帧的播放时间之后再次调用；如果返回值 < 100ms，则代表缓冲区比较小，您可以再次混入一些音轨数据以确保音轨缓冲区的大小维持在“安全水位”以上。
+ * 参数 {@link TRTCAudioFrame} 推荐下列填写方式（其他字段不需要填写）：
+ * - data：音频帧 buffer。音频帧数据只支持 PCM 格式，支持[5ms ~ 100ms]帧长，推荐使用 20ms 帧长，长度计算方法：【48000采样率、单声道的帧长度：48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节】。
+ * - sampleRate：采样率，支持：16000、24000、32000、44100、48000。
+ * - channel：声道数（如果是立体声，数据是交叉的），单声道：1； 双声道：2。
+ * - timestamp：时间戳，单位为毫秒（ms），请使用音频帧在采集时被记录下来的时间戳（可以在获得一帧音频帧之后，通过调用 {@link generateCustomPTS} 获得时间戳）。
*
- * @note 调用此函数之前，需要先调用 startRemoteView 来获取远端用户的视频流（view 设置为 nil 即可），否则不会有数据回调出来。
+ * @param frame 音频数据
*
- * @param userId 指定目标 userId。
- * @param delegate 自定义渲染的回调。
- * @param pixelFormat 指定回调的像素格式。
- * @param bufferType PixelBuffer：可以直接使用 imageWithCVImageBuffer 转成 UIImage；NSData：经过内存整理的视频数据。
- * @return 0：成功；<0：错误
+ * @return >= 0 缓冲的长度，单位：ms。< 0 错误（-1 未启用 mixExternalAudioFrame）
+ *
+ * @note 请您精准地按每帧时长的间隔调用本接口，数据投送间隔不均匀时极易触发声音卡顿。
*/
-- (int)setRemoteVideoRenderDelegate:(NSString*)userId delegate:(id<TRTCVideoRenderDelegate>)delegate pixelFormat:(TRTCVideoPixelFormat)pixelFormat bufferType:(TRTCVideoBufferType)bufferType;
+- (int)mixExternalAudioFrame:(TRTCAudioFrame *)frame;
/**
- * 9.6 启用音频自定义采集模式
+ * 10.7 设置推流时混入外部音频的推流音量和播放音量
*
- * 开启该模式后，SDK 不在运行原有的音频采集流程，只保留编码和发送能力。
- * 您需要用 sendCustomAudioData() 不断地向 SDK 塞入自己采集的音频数据。
+ * @param publishVolume 设置的推流音量大小，范围0 - 100, -1表示不改变
+ * @param playoutVolume 设置的播放音量大小，范围0 - 100, -1表示不改变
+ */
+- (void)setMixExternalAudioVolume:(NSInteger)publishVolume playoutVolume:(NSInteger)playoutVolume;
+
+/**
+ * 10.8 生成自定义采集时的时间戳
*
- * @note 由于回声抵消（AEC）需要严格的控制声音采集和播放的时间，所以开启自定义音频采集后，AEC 能力可能会失效。
+ * 本接口仅适用于自定义采集模式，用于解决音视频帧的采集时间（capture time）和投送时间（send time）不一致所导致的音画不同步问题。
+ * 当您通过 {@link sendCustomVideoData} 或 {@link sendCustomAudioData} 等接口进行自定义视频或音频采集时，请按照如下操作使用该接口：
+ * 1. 首先，在采集到一帧视频或音频帧时，通过调用本接口获得当时的 PTS 时间戳。
+ * 2. 之后可以将该视频或音频帧送入您使用的前处理模块（如第三方美颜组件，或第三方音效组件）。
+ * 3. 在真正调用 {@link sendCustomVideoData} 或 {@link sendCustomAudioData} 进行投送时，请将该帧在采集时记录的 PTS 时间戳赋值给 {@link TRTCVideoFrame} 或 {@link TRTCAudioFrame} 中的 timestamp 字段。
*
- * @param enable 是否启用, true：启用；false：关闭，默认值：NO
+ * @return 时间戳（单位：ms）
*/
-- (void)enableCustomAudioCapture:(BOOL)enable;
++ (uint64_t)generateCustomPTS;
/**
- * 9.7 向 SDK 投送自己采集的音频数据
+ * 10.9 设置第三方美颜的视频数据回调
*
- * TRTCAudioFrame 推荐如下填写方式：
- *
- * - data：音频帧 buffer。音频帧数据只支持 PCM 格式，支持[5ms ~ 100ms]帧长，推荐使用20 ms帧长，【48000采样率、单声道的帧长度：48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节】。
- * - sampleRate：采样率，支持：16000、24000、32000、44100、48000。
- * - channel：声道数（如果是立体声，数据是交叉的），单声道：1； 双声道：2。
- * - timestamp：时间戳，单位毫秒（ms）。如果 timestamp 间隔不均匀，会严重影响音画同步和录制出的 MP4 质量。
+ * 设置该回调之后，SDK 会把采集到的视频帧通过您设置的 delegate 回调出来，用于第三方美颜组件进行二次处理，之后 SDK 会将处理后的视频帧进行编码和发送。
+ * @param delegate 自定义预处理回调，详见 {@link TRTCVideoFrameDelegate}
+ * @param pixelFormat 指定回调的像素格式，目前仅支持 {@link TRTCVideoPixelFormat_Texture_2D}
+ * @param bufferType 指定回调的数据格式，目前仅支持 {@link TRTCVideoBufferType_Texture}
+ * @return 0：成功；<0：错误
+ */
+- (int)setLocalVideoProcessDelegete:(id<TRTCVideoFrameDelegate>)delegate pixelFormat:(TRTCVideoPixelFormat)pixelFormat bufferType:(TRTCVideoBufferType)bufferType;
+
+/**
+ * 10.10 设置本地视频自定义渲染回调
*
+ * 设置该回调之后，SDK 内部会跳过原来的渲染流程，并把采集到的数据回调出来，您需要自己完成画面渲染。
+ * - pixelFormat 指定回调的数据格式，例如 NV12、i420 以及 32BGRA。
+ * - bufferType 指定 buffer 的类型，直接使用 PixelBuffer 效率最高；使用 NSData 相当于让 SDK 在内部做了一次内存转换，因此会有额外的性能损耗。
* 参考文档：[自定义采集和渲染](https://cloud.tencent.com/document/product/647/34066)。
- *
- * @param frame 音频数据
- * @note 可以设置 frame 中的 timestamp 为 0，相当于让 SDK 自己设置时间戳，但请“均匀”地控制 sendCustomAudioData 的调用间隔，否则会导致声音断断续续。
+ * @param delegate 自定义渲染回调
+ * @param pixelFormat 指定回调的像素格式
+ * @param bufferType PixelBuffer：可以直接使用 imageWithCVImageBuffer 转成 UIImage；NSData：经过内存整理的视频数据。
+ * @return 0：成功；<0：错误
*/
-- (void)sendCustomAudioData:(TRTCAudioFrame *)frame;
+- (int)setLocalVideoRenderDelegate:(id<TRTCVideoRenderDelegate>)delegate pixelFormat:(TRTCVideoPixelFormat)pixelFormat bufferType:(TRTCVideoBufferType)bufferType;
/**
- * 9.8 设置音频数据回调
+ * 10.11 设置远端视频自定义渲染回调
*
- * 设置此方法，SDK 内部会把音频数据（PCM 格式）回调出来，包括：
- * - onCapturedRawAudioFrame：本地麦克风采集到的原始音频数据回调
- * - onLocalProcessedAudioFrame：本地采集并经过音频模块前处理后的音频数据回调
- * - onRemoteUserAudioFrame：混音前的每一路远程用户的音频数据
- * - onMixedPlayAudioFrame：各路音频数据混合后送入扬声器播放的音频数据
+ * 设置该回调之后，SDK 内部会跳过原来的渲染流程，并把采集到的数据回调出来，您需要自己完成画面渲染。
+ * - pixelFormat 指定回调的数据格式，例如 NV12、i420 以及 32BGRA。
+ * - bufferType 指定 buffer 的类型，直接使用 PixelBuffer 效率最高；使用 NSData 相当于让 SDK 在内部做了一次内存转换，因此会有额外的性能损耗。
*
- * @param delegate 音频数据回调，delegate = nil 则停止回调数据
+ * 参考文档：[自定义采集和渲染](https://cloud.tencent.com/document/product/647/34066)。
+ * @note 调用此函数之前，需要先调用 startRemoteView(nil) 来获取远端用户的视频流（view 设置为 nil 即可），否则不会有数据回调出来。
+ * @param userId 指定远端用户的 ID
+ * @param delegate 自定义渲染回调
+ * @param pixelFormat 指定回调的像素格式
+ * @param bufferType PixelBuffer：可以直接使用 imageWithCVImageBuffer 转成 UIImage；NSData：经过内存整理的视频数据。
+ * @return 0：成功；<0：错误
*/
-- (void)setAudioFrameDelegate:(id<TRTCAudioFrameDelegate>)delegate;
+- (int)setRemoteVideoRenderDelegate:(NSString *)userId delegate:(id<TRTCVideoRenderDelegate>)delegate pixelFormat:(TRTCVideoPixelFormat)pixelFormat bufferType:(TRTCVideoBufferType)bufferType;
/**
- * 9.9 生成自定义采集时间戳
+ * 10.12 设置音频数据自定义回调
*
- * 此函数仅适合自定义视频采集时使用，当您的 App 自己或由第三方美颜 SDK 调用摄像头 API 采集视频时，由于可能引入一些耗时的外部操作（比如美颜），这会导致视频的节奏和 SDK 内部的音频节奏不一致，进而导致音画不同步。
- * 为避免发生音画不同步的问题，请按照如下步骤正确使用该接口：
- * 1. 在调用系统相机 API 采集到一帧视频时，额外调用一次 generateCustomPTS 获得 pts 时间戳。
- * 2. 在调用 sendCustomVideoData: 时，将该帧采集时记录的 pts 时间戳赋值给入参 TRTCVideoFrame 中的 timestamp 字段。
+ * 设置该回调之后，SDK 内部会把音频数据（PCM 格式）回调出来，包括：
+ * - {@link onCapturedRawAudioFrame}：本地麦克风采集到的原始音频数据回调
+ * - {@link onLocalProcessedAudioFrame}：本地采集并经过音频模块前处理后的音频数据回调
+ * - {@link onRemoteUserAudioFrame}：混音前的每一路远程用户的音频数据
+ * - {@link onMixedPlayAudioFrame}：将各路音频混合之后并最终要由系统播放出的音频数据回调
*
- * @return 时间戳（单位：ms）
+ * @note 设置回调为空即代表停止自定义音频回调，反之，设置回调不为空则代表启动自定义音频回调。
*/
-+ (uint64_t)generateCustomPTS;
+- (void)setAudioFrameDelegate:(id<TRTCAudioFrameDelegate>)delegate;
/**
- * 9.10 设置本地麦克风采集回调出来的 AudioFrame 格式
+ * 10.13 设置本地麦克风采集出的原始音频帧回调格式
*
- * 设置 onCapturedRawAudioFrame 回调出来的 AudioFrame 的格式
+ * 本接口用于设置 {@link onCapturedRawAudioFrame} 回调出来的 AudioFrame 的格式:
* - sampleRate：采样率，支持：16000、32000、44100、48000。
* - channel：声道数（如果是立体声，数据是交叉的），单声道：1； 双声道：2。
* - samplesPerCall：采样点数，定义回调数据帧长。帧长必须为 10ms 的整数倍。
- * 如果希望用毫秒数计算回调帧长，则将毫秒数转换成采样点数的公式为：采样点数 = 毫秒数 * 采样率 / 1000；
- * 举例：48000 采样率希望回调 20ms 帧长的数据，则采样点数应该填: 960 = 20 * 48000 / 1000；
- * 注意，最终回调的帧长度是以字节为单位，采样点数转换成字节数的计算公式为：字节数 = 采样点数 * channel * 2（位宽）
- * 举例：48000 采样率，双声道，20ms 帧长，采样点数为 960，字节数为 3840 = 960 * 2 * 2
*
+ * 如果希望用毫秒数计算回调帧长，则将毫秒数转换成采样点数的公式为：采样点数 = 毫秒数 * 采样率 / 1000；
+ * 举例：48000 采样率希望回调 20ms 帧长的数据，则采样点数应该填: 960 = 20 * 48000 / 1000；
+ * 注意，最终回调的帧长度是以字节为单位，采样点数转换成字节数的计算公式为：字节数 = 采样点数 * channel * 2（位宽）
+ * 举例：48000 采样率，双声道，20ms 帧长，采样点数为 960，字节数为 3840 = 960 * 2 * 2
* @param format 音频数据回调格式。
* @return 0：成功；<0：错误
*/
- (int)setCapturedRawAudioFrameDelegateFormat:(TRTCAudioFrameDelegateFormat *)format;
/**
- * 9.11 设置本地采集并经过音频模块前处理后的音频数据回调出来的 AudioFrame 格式
+ * 10.14 设置经过前处理后的本地音频帧回调格式
*
- * 设置 onLocalProcessedAudioFrame 回调出来的AudioFrame的格式
- * - sampleRate：采样率，支持：16000、32000、44100、48000。
- * - channel：声道数（如果是立体声，数据是交叉的），单声道：1； 双声道：2。
+ * 本接口用于设置 {@link onLocalProcessedAudioFrame} 回调出来的 AudioFrame 的格式:
+ * - sampleRate：采样率，支持：16000、32000、44100、48000。
+ * - channel：声道数（如果是立体声，数据是交叉的），单声道：1； 双声道：2。
* - samplesPerCall：采样点数，定义回调数据帧长。帧长必须为 10ms 的整数倍。
- * 如果希望用毫秒数计算回调帧长，则将毫秒数转换成采样点数的公式为：采样点数 = 毫秒数 * 采样率 / 1000；
- * 举例：48000 采样率希望回调20ms帧长的数据，则采样点数应该填: 960 = 20 * 48000 / 1000；
- * 注意，最终回调的帧长度是以字节为单位，采样点数转换成字节数的计算公式为：字节数 = 采样点数 * channel * 2（位宽）
- * 举例：48000 采样率，双声道，20ms 帧长，采样点数为 960，字节数为 3840 = 960 * 2 * 2
+ *
+ * 如果希望用毫秒数计算回调帧长，则将毫秒数转换成采样点数的公式为：采样点数 = 毫秒数 * 采样率 / 1000；
+ * 举例：48000 采样率希望回调20ms帧长的数据，则采样点数应该填: 960 = 20 * 48000 / 1000；
+ * 注意，最终回调的帧长度是以字节为单位，采样点数转换成字节数的计算公式为：字节数 = 采样点数 * channel * 2（位宽）
+ * 举例：48000 采样率，双声道，20ms 帧长，采样点数为 960，字节数为 3840 = 960 * 2 * 2
*
* @param format 音频数据回调格式。
* @return 0：成功；<0：错误
@@ -1280,1054 +1249,918 @@
- (int)setLocalProcessedAudioFrameDelegateFormat:(TRTCAudioFrameDelegateFormat *)format;
/**
- * 9.12 设置送入扬声器播放的音频数据回调的 AudioFrame 格式
+ * 10.15 设置最终要由系统播放出的音频帧回调格式
*
- * 设置 onMixedPlayAudioFrame 回调出来的 AudioFrame 格式
+ * 本接口用于设置 {@link onMixedPlayAudioFrame} 回调出来的 AudioFrame 的格式:
* - sampleRate：采样率，支持：16000、32000、44100、48000。
* - channel：声道数（如果是立体声，数据是交叉的），单声道：1； 双声道：2。
* - samplesPerCall：采样点数，定义回调数据帧长。帧长必须为 10ms 的整数倍。
- * 如果希望用毫秒数计算回调帧长，则将毫秒数转换成采样点数的公式为：采样点数 = 毫秒数 * 采样率 / 1000；
- * 举例：48000 采样率希望回调 20ms 帧长的数据，则采样点数应该填: 960 = 20 * 48000 / 1000；
- * 注意，最终回调的帧长度是以字节为单位，采样点数转换成字节数的计算公式为：字节数 = 采样点数 * channel * 2（位宽）
- * 举例：48000 采样率，双声道，20ms 帧长，采样点数为 960，字节数为3840 = 960 * 2 * 2
*
+ * 如果希望用毫秒数计算回调帧长，则将毫秒数转换成采样点数的公式为：采样点数 = 毫秒数 * 采样率 / 1000；
+ * 举例：48000 采样率希望回调20ms帧长的数据，则采样点数应该填: 960 = 20 * 48000 / 1000；
+ * 注意，最终回调的帧长度是以字节为单位，采样点数转换成字节数的计算公式为：字节数 = 采样点数 * channel * 2（位宽）
+ * 举例：48000 采样率，双声道，20ms 帧长，采样点数为 960，字节数为 3840 = 960 * 2 * 2
* @param format 音频数据回调格式。
* @return 0：成功；<0：错误
*/
- (int)setMixedPlayAudioFrameDelegateFormat:(TRTCAudioFrameDelegateFormat *)format;
/**
- * 9.13 控制外部音频是否要混入推流和混入播放
+ * 10.16 开启音频自定义播放
*
- * 您可以通过 mixExternalAudioFrame: 增加一路音频混合到推流的音频流，同时可以支持在本地播放
- *
- * @param enablePublish 是否混入推流 YES：混入推流；NO：不混入推流，默认值：NO
- * @param enablePlayout 是否混入本地播放 YES：混入播放；NO：不混入播放，默认值：NO
- * @note enablePublish = NO， enablePlayout = NO 时，表示完全关闭这个额外的音频流，即不推流，也不播放
+ * 如果您需要外接一些特定的音频设备，或者希望自己掌控音频的播放逻辑，您可以通过该接口启用音频自定义播放。
+ * 启用音频自定义播放后，SDK 将不再调用系统的音频接口播放数据，您需要通过 {@link getCustomAudioRenderingFrame} 获取 SDK 要播放的音频帧并自行播放。
+ * @param enable 是否启用音频自定义播放，默认为关闭状态。
+ * @note 需要您在进入房间前设置才能生效，暂不支持进入房间后再设置。
*/
-- (void)enableMixExternalAudioFrame:(BOOL)enablePublish playout:(BOOL)enablePlayout;
+- (void)enableCustomAudioRendering:(BOOL)enable;
/**
- * 9.14 向 SDK 投送自己附加的音频数据
+ * 10.17 获取可播放的音频数据
*
- * TRTCAudioFrame 推荐如下填写方式：
- * - data：音频帧 buffer。音频帧数据只支持 PCM 格式，支持[5ms ~ 100ms]帧长，推荐使用20 ms帧长，【48000采样率、单声道的帧长度：48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节】。
- * - sampleRate：采样率，支持：16000、24000、32000、44100、48000。
- * - channel：声道数（如果是立体声，数据是交叉的），单声道：1； 双声道：2。
- * - timestamp：时间戳，单位毫秒（ms）。如果 timestamp 间隔不均匀，会严重影响音画同步和录制出的 MP4 质量。
+ * 调用该接口之前，您需要先通过 {@link enableCustomAudioRendering} 开启音频自定义播放。
+ * 参数 {@link TRTCAudioFrame} 推荐下列填写方式（其他字段不需要填写）：
+ * - sampleRate：采样率，必填，支持 16000、24000、32000、44100、48000。
+ * - channel：声道数，必填，单声道请填1，双声道请填2，双声道时数据是交叉的。
+ * - data：用于获取音频数据的 buffer。需要您根据一阵音频帧的帧长度分配好 date 的内存大小。
+ * 获取的 PCM 数据支持 10ms 或 20ms 两种帧长，推荐使用 20ms 的帧长。
+ * 计算公式为：48000采样率、单声道、且播放时长为 20ms 的一帧音频帧的 buffer 大小为 48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节。
+ *
+ * @param audioFrame 音频数据帧。
+ * @note
+ * 1. 参数 audioFrame 中的 sampleRate、channel 需提前设置好，同时分配好所需读取帧长的 data 空间。
+ * 2. SDK 内部会根据 sampleRate 和 channel 自动填充 data 数据。
+ * 3. 建议由系统的音频播放线程直接驱动该函数的调用，在播放完一帧音频之后，即调用该接口获取下一帧可播放的音频数据。
*
- * @param frame 音频数据
- * @note 可以设置 frame 中的 timestamp 为 0，相当于让 SDK 自己设置时间戳，但请“均匀”地控制 mixExternalAudioFrame 的调用间隔，否则会导致声音断断续续。
*/
-- (void)mixExternalAudioFrame:(TRTCAudioFrame *)frame;
-/// @}
+- (void)getCustomAudioRenderingFrame:(TRTCAudioFrame *)audioFrame;
+/// @}
/////////////////////////////////////////////////////////////////////////////////
//
-// （十）自定义消息发送
+// 自定义消息发送接口
//
/////////////////////////////////////////////////////////////////////////////////
-#pragma mark - 自定义消息发送
-/// @name 自定义消息发送
+/// @name 自定义消息发送接口
/// @{
/**
- * 10.1 发送自定义消息给房间内所有用户
- *
- * 该接口可以借助音视频数据通道向当前房间里的其他用户广播您自定义的数据，但因为复用了音视频数据通道，
- * 请务必严格控制自定义消息的发送频率和消息体的大小，否则会影响音视频数据的质量控制逻辑，造成不确定性的问题。
+ * 11.1 使用 UDP 通道发送自定义消息给房间内所有用户
*
- * @param cmdID 消息 ID，取值范围为1 - 10
- * @param data 待发送的消息，最大支持 1KB（1000 字节）的数据大小
- * @param reliable 是否可靠发送，可靠发送的代价是会引入一定的延时，因为接收端要暂存一段时间的数据来等待重传
- * @param ordered 是否要求有序，即是否要求接收端接收的数据顺序和发送端发送的顺序一致，这会带来一定的接收延时，因为在接收端需要暂存并排序这些消息。
- * @return YES：消息已经发出；NO：消息发送失败。
- *
- * @note 本接口有以下限制：
- * - 发送消息到房间内所有用户（暂时不支持 Web/小程序端），每秒最多能发送30条消息。
- * - 每个包最大为 1KB，超过则很有可能会被中间路由器或者服务器丢弃。
- * - 每个客户端每秒最多能发送总计 8KB 数据。
- * - 将 reliable 和 ordered 同时设置为 YES 或 NO，暂不支持交叉设置。
- * - 强烈建议不同类型的消息使用不同的 cmdID，这样可以在要求有序的情况下减小消息时延。
+ * 该接口可以让您借助 TRTC 的 UDP 通道，向当前房间里的其他用户广播自定义数据，已达到传输信令的目的。
+ * TRTC 中的 UDP 通道原本设计用来传输音视频数据的，该接口的原理是将您要发送的信令伪装成音视频数据包，与原本要发送的音视频数据一并发送出去。
+ * 房间中的其他用户可以通过 {@link TRTCCloudDelegate} 中的 onRecvCustomCmdMsg 回调接收消息。
+ * @param cmdID 消息 ID，取值范围为1 - 10。
+ * @param data 待发送的消息，单个消息的最大长度被限制为 1KB。
+ * @param reliable 是否可靠发送，可靠发送可以获得更高的发送成功率，但可靠发送比不可靠发送会带来更大的接收延迟。
+ * @param ordered 是否要求有序，即是否要求接收端的数据包顺序和发送端的数据包顺序一致（这会带来一定的接收延时）。
+ * @return true：消息已经发出；false：消息发送失败。
+ * @note
+ * 1. 发送消息到房间内所有用户（暂时不支持 Web/小程序端），每秒最多能发送30条消息。
+ * 2. 每个包最大为 1KB，超过则很有可能会被中间路由器或者服务器丢弃。
+ * 3. 每个客户端每秒最多能发送总计 8KB 数据。
+ * 4. 请将 reliable 和 ordered 同时设置为 true 或同时设置为 flase，暂不支持交叉设置。
+ * 5. 强烈建议您将不同类型的消息设定为不同的 cmdID，这样可以在要求有序的情况下减小消息时延。
*/
- (BOOL)sendCustomCmdMsg:(NSInteger)cmdID data:(NSData *)data reliable:(BOOL)reliable ordered:(BOOL)ordered;
/**
- * 10.2 将小数据量的自定义数据嵌入视频帧中
- *
- * 与 sendCustomCmdMsg 的原理不同，sendSEIMsg 是将数据直接塞入视频数据头中。因此，即使视频帧被旁路到了直播 CDN 上，
- * 这些数据也会一直存在。由于需要把数据嵌入视频帧中，建议尽量控制数据大小，推荐使用几个字节大小的数据。
- *
- * 最常见的用法是把自定义的时间戳（timstamp）用 sendSEIMsg 嵌入视频帧中，实现消息和画面的完美对齐。
+ * 11.2 使用 SEI 通道发送自定义消息给房间内所有用户
*
+ * 该接口可以让您借助 TRTC 的 SEI 通道，向当前房间里的其他用户广播自定义数据，已达到传输信令的目的。
+ * 视频帧的头部有一个叫做 SEI 的头部数据块，该接口的原理就是利用这个被称为 SEI 的头部数据块，将您要发送的自定义信令嵌入其中，使其同视频帧一并发送出去。
+ * 因此，与 {@link sendCustomCmdMsg} 相比，SEI 通道传输的信令具有更好的兼容性：信令可以伴随着视频帧一直传输到直播 CDN 上。
+ * 不过，由于视频帧头部的数据块不能太大，建议您使用该接口时，尽量将信令控制在几个字节的大小。
+ * 最常见的用法是把自定义的时间戳（timestamp）用本接口嵌入视频帧中，实现消息和画面的完美对齐（比如：教育场景下的课件和视频信号的对齐）。
+ * 房间中的其他用户可以通过 {@link TRTCCloudDelegate} 中的 onRecvSEIMsg 回调接收消息。
* @param data 待发送的数据，最大支持 1KB（1000字节）的数据大小
* @param repeatCount 发送数据次数
* @return YES：消息已通过限制，等待后续视频帧发送；NO：消息被限制发送
- *
* @note 本接口有以下限制：
- * - 数据在接口调用完后不会被即时发送出去，而是从下一帧视频帧开始带在视频帧中发送。
- * - 发送消息到房间内所有用户，每秒最多能发送 30 条消息（与 sendCustomCmdMsg 共享限制）。
- * - 每个包最大为 1KB，若发送大量数据，会导致视频码率增大，可能导致视频画质下降甚至卡顿（与 sendCustomCmdMsg 共享限制）。
- * - 每个客户端每秒最多能发送总计8KB数据（与 sendCustomCmdMsg 共享限制）。
- * - 若指定多次发送（repeatCount > 1），则数据会被带在后续的连续 repeatCount 个视频帧中发送出去，同样会导致视频码率增大。
- * - 如果 repeatCount > 1，多次发送，接收消息 onRecvSEIMsg 回调也可能会收到多次相同的消息，需要去重。
+ * 1. 数据在接口调用完后不会被即时发送出去，而是从下一帧视频帧开始带在视频帧中发送。
+ * 2. 发送消息到房间内所有用户，每秒最多能发送 30 条消息（与 sendCustomCmdMsg 共享限制）。
+ * 3. 每个包最大为 1KB，若发送大量数据，会导致视频码率增大，可能导致视频画质下降甚至卡顿（与 sendCustomCmdMsg 共享限制）。
+ * 4. 每个客户端每秒最多能发送总计8KB数据（与 sendCustomCmdMsg 共享限制）。
+ * 5. 若指定多次发送（repeatCount > 1），则数据会被带在后续的连续 repeatCount 个视频帧中发送出去，同样会导致视频码率增大。
+ * 6. 如果 repeatCount > 1，多次发送，接收消息 onRecvSEIMsg 回调也可能会收到多次相同的消息，需要去重。
*/
-- (BOOL)sendSEIMsg:(NSData *)data repeatCount:(int)repeatCount;
+- (BOOL)sendSEIMsg:(NSData *)data repeatCount:(int)repeatCount;
/// @}
-
-
/////////////////////////////////////////////////////////////////////////////////
//
-// （十一）设备和网络测试
+// 网络测试接口
//
/////////////////////////////////////////////////////////////////////////////////
-#pragma mark - 设备和网络测试
-/// @name 设备和网络测试
+/// @name 网络测试接口
/// @{
/**
- * 11.1 开始进行网络测速（视频通话期间请勿测试，以免影响通话质量）
+ * 12.1 开始进行网络测速（进入房间前使用）
*
- * 测速结果将会用于优化 SDK 接下来的服务器选择策略，因此推荐您在用户首次通话前先进行一次测速，这将有助于我们选择最佳的服务器。
- * 同时，如果测试结果非常不理想，您可以通过醒目的 UI 提示用户选择更好的网络。
- *
- * @note 测速本身会消耗一定的流量，所以也会产生少量额外的流量费用。
- *
- * @param sdkAppId 应用标识
- * @param userId 用户标识
- * @param userSig 用户签名
- * @param completion 测试回调，会分多次回调
+ * TRTC 由于涉及的是对传输时延要求很苛刻的实时音视频传输服务，因此对网络的稳定性要求会比较高。
+ * 很多用户在网络环境达不到 TRTC 的最低使用门槛时，直接进入房间可能会导致非常不好的用户体验。
+ * 推荐的做法是在用户进入房间前进行网络测速，当用户网络较差时通过 UI 交互提醒用户切换到更加稳定的网络（比如 WiFi 切换到 4G ）后再进入房间。
+ * @note
+ * 1. 测速本身会消耗一定的流量，所以也会产生少量额外的流量费用。
+ * 2. 请在进入房间前进行测速，在房间中测速会影响正常的音视频传输效果，而且由于干扰过多，测速结果也不准确。
+ * @param sdkAppId 应用标识，请参考 {@link TRTCParams} 中的相关说明。
+ * @param userId 用户标识，请参考 {@link TRTCParams} 中的相关说明。
+ * @param userSig 用户签名，请参考 {@link TRTCParams} 中的相关说明。
*/
-- (void)startSpeedTest:(uint32_t)sdkAppId userId:(NSString *)userId userSig:(NSString *)userSig completion:(void(^)(TRTCSpeedTestResult* result, NSInteger completedCount, NSInteger totalCount))completion;
+- (void)startSpeedTest:(uint32_t)sdkAppId userId:(NSString *)userId userSig:(NSString *)userSig completion:(void (^)(TRTCSpeedTestResult *result, NSInteger completedCount, NSInteger totalCount))completion;
/**
- * 11.2 停止服务器测速
+ * 12.2 停止网络测速
*/
- (void)stopSpeedTest;
/// @}
-
/////////////////////////////////////////////////////////////////////////////////
//
-// （十二）Log 相关接口函数
+// 调试相关接口
//
/////////////////////////////////////////////////////////////////////////////////
-/// @name Log 相关接口函数
+/// @name 调试相关接口
/// @{
-#pragma mark - LOG 相关接口函数
/**
- * 12.1 获取 SDK 版本信息
+ * 13.1 获取 SDK 版本信息
*/
+ (NSString *)getSDKVersion;
/**
- * 12.2 设置 Log 输出级别
+ * 13.2 设置 Log 输出级别
*
- * @param level 参见 TRTCLogLevel，默认值：TRTC_LOG_LEVEL_NULL
+ * @param level 参见 {@link TRTCLogLevel}，默认值：{@link TRTCLogLevelNone}
*/
+ (void)setLogLevel:(TRTCLogLevel)level;
/**
- * 12.3 启用或禁用控制台日志打印
+ * 13.3 启用/禁用控制台日志打印
*
- * @param enabled 指定是否启用，默认为禁止状态
+ * @param enabled 指定是否启用，默认:禁止状态
*/
+ (void)setConsoleEnabled:(BOOL)enabled;
/**
- * 12.4 启用或禁用 Log 的本地压缩。
+ * 13.4 启用/禁用日志的本地压缩
*
* 开启压缩后，Log 存储体积明显减小，但需要腾讯云提供的 Python 脚本解压后才能阅读。
* 禁用压缩后，Log 采用明文存储，可以直接用记事本打开阅读，但占用空间较大。
- *
- * @param enabled 指定是否启用，默认为启动状态
+ * @param enabled 指定是否启用，默认为启动状态
*/
+ (void)setLogCompressEnabled:(BOOL)enabled;
/**
- * 12.5 修改日志保存路径
+ * 13.5 设置本地日志的保存路径
+ *
+ * 通过该接口您可以更改 SDK 本地日志的默认存储路径，SDK 默认的本地日志的存储位置：
+ * - Windows 平台：在 C:/Users/[系统用户名]/AppData/Roaming/liteav/log，即 %appdata%/liteav/log 下。
+ * - iOS 或 Mac 平台：在 sandbox Documents/log 下。
+ * - Android 平台：在 /app私有目录/files/log/liteav/ 下。
*
- * @note 日志文件默认保存在 sandbox Documents/log 下，如需修改，必须在所有方法前调用。
- * @param path 存储日志路径
+ * @note 请务必在所有其他接口之前调用，并且保证您指定的目录是存在的，并且您的应用程序拥有对该目录的读写权限。
+ * @param path 存储日志的路径
*/
+ (void)setLogDirPath:(NSString *)path;
/**
- * 12.6 设置日志回调
+ * 13.6 设置日志回调
*/
+ (void)setLogDelegate:(id<TRTCLogDelegate>)logDelegate;
/**
- * 12.7 显示仪表盘
+ * 13.7 显示仪表盘
*
- * 仪表盘是状态统计和事件消息浮层 view，方便调试。
- * @param showType 0：不显示；1：显示精简版；2：显示全量版
+ * “仪表盘”是位于视频渲染控件之上的一个半透明的调试信息浮层，用于展示音视频信息和事件信息，便于对接和调试。
+ * @param showType 0：不显示；1：显示精简版（仅显示音视频信息）；2：显示完整版（包含音视频信息和事件信息）。
*/
- (void)showDebugView:(NSInteger)showType;
/**
- * 12.8 设置仪表盘的边距
+ * 13.8 设置仪表盘的边距
*
- * 必须在 showDebugView 调用前设置才会生效
+ * 用于调整仪表盘在视频渲染控件中的位置，必须在 showDebugView 之前调用才能生效。
* @param userId 用户 ID
- * @param margin 仪表盘内边距，注意这里是基于 parentView 的百分比，margin 的取值范围是0 - 1
+ * @param margin 仪表盘内边距，注意这里是基于 parentView 的百分比，margin 的取值范围是0 - 1。
*/
- (void)setDebugViewMargin:(NSString *)userId margin:(TXEdgeInsets)margin;
-
/**
- * 12.9 调用实验性 API 接口
- *
- * @note 该接口用于调用一些实验性功能
- * @param jsonStr 接口及参数描述的 JSON 字符串
+ * 13.9 调用实验性接口
*/
-- (void)callExperimentalAPI:(NSString*)jsonStr;
+- (void)callExperimentalAPI:(NSString *)jsonStr;
/// @}
-
/////////////////////////////////////////////////////////////////////////////////
//
-// （十三）弃用接口（建议使用对应的新接口）
+// 弃用接口（建议使用对应的新接口）
//
/////////////////////////////////////////////////////////////////////////////////
-#pragma mark - 弃用接口（建议使用对应的新接口）
-/// @name 弃用接口（建议使用对应的新接口）
+/// @name 弃用接口（建议使用对应的新接口）
/// @{
/**
* 设置麦克风的音量大小
*
- * @deprecated v6.9 版本弃用
- * 播放背景音乐混音时使用，用来控制麦克风音量大小。
- *
- * @param volume 音量大小，100 为原始音量，范围是：[0 ~ 150]，默认值为 100
- *
- * @note 如果要将 volume 设置为大于 100 的数值，需要进行特殊配置，请联系技术支持。
+ * @deprecated v6.9 版本开始不推荐使用，建议使用 {@link setAudioCaptureVolume} 替代之。
*/
- (void)setMicVolumeOnMixing:(NSInteger)volume __attribute__((deprecated("use setAudioCaptureVolume instead")));
/**
* 设置美颜、美白以及红润效果级别
*
- * SDK 内部集成两套风格不同的磨皮算法，一套我们取名叫“光滑”，适用于美女秀场，效果比较明显。
- * 另一套我们取名“自然”，磨皮算法更多地保留了面部细节，主观感受上会更加自然。
- *
- * @deprecated v6.9 版本弃用，请使用 TXBeautyManager 设置美颜功能
- * @param beautyStyle 美颜风格，光滑或者自然，光滑风格磨皮更加明显，适合娱乐场景。
- * @param beautyLevel 美颜级别，取值范围 0 - 9； 0表示关闭，1 - 9 值越大，效果越明显。
- * @param whitenessLevel 美白级别，取值范围 0 - 9；0表示关闭，1 - 9 值越大，效果越明显。
- * @param ruddinessLevel 红润级别，取值范围 0 - 9；0表示关闭，1 - 9 值越大，效果越明显。
+ * @deprecated v6.9 版本开始不推荐使用，建议使用 {@link getBeautyManager} 替代之。
*/
-- (void)setBeautyStyle:(TRTCBeautyStyle)beautyStyle beautyLevel:(NSInteger)beautyLevel
- whitenessLevel:(NSInteger)whitenessLevel ruddinessLevel:(NSInteger)ruddinessLevel
- __attribute__((deprecated("use getBeautyManager instead")));
+- (void)setBeautyStyle:(TRTCBeautyStyle)beautyStyle beautyLevel:(NSInteger)beautyLevel whitenessLevel:(NSInteger)whitenessLevel ruddinessLevel:(NSInteger)ruddinessLevel __attribute__((deprecated("use getBeautyManager instead")));
-#if TARGET_OS_IPHONE
/**
- * 设置大眼级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
+ * 设置大眼级别
*
- * @deprecated v6.9 版本弃用，请使用 TXBeautyManager 设置美颜功能
- * @param eyeScaleLevel 大眼级别，取值范围 0 - 9；0表示关闭，1 - 9 值越大，效果越明显。
+ * @deprecated v6.9 版本开始不推荐使用，建议使用 {@link getBeautyManager} 替代之。
*/
+#if TARGET_OS_IPHONE
- (void)setEyeScaleLevel:(float)eyeScaleLevel __attribute__((deprecated("use getBeautyManager instead")));
+#endif
/**
- * 设置瘦脸级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
+ * 设置瘦脸级别
*
- * @deprecated v6.9 版本弃用，请使用 TXBeautyManager 设置美颜功能
- * @param faceScaleLevel 瘦脸级别，取值范围 0 - 9；0表示关闭，1 - 9 值越大，效果越明显。
+ * @deprecated v6.9 版本开始不推荐使用，建议使用 {@link getBeautyManager} 替代之。
*/
+#if TARGET_OS_IPHONE
- (void)setFaceScaleLevel:(float)faceScaleLevel __attribute__((deprecated("use getBeautyManager instead")));
+#endif
/**
- * 14.5设置 V 脸级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
+ * 设置 V 脸级别
*
- * @deprecated v6.9 版本弃用，请使用 TXBeautyManager 设置美颜功能
- * @param faceVLevel V脸级别，取值范围 0 - 9；0表示关闭，1 - 9 值越大，效果越明显。
+ * @deprecated v6.9 版本开始不推荐使用，建议使用 {@link getBeautyManager} 替代之。
*/
+#if TARGET_OS_IPHONE
- (void)setFaceVLevel:(float)faceVLevel __attribute__((deprecated("use getBeautyManager instead")));
+#endif
/**
- * 设置下巴拉伸或收缩，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
+ * 设置下巴拉伸或收缩幅度
*
- * @deprecated v6.9 版本弃用，请使用 TXBeautyManager 设置美颜功能
- * @param chinLevel 下巴拉伸或收缩级别，取值范围 -9 - 9；0 表示关闭，小于 0 表示收缩，大于 0 表示拉伸。
+ * @deprecated v6.9 版本开始不推荐使用，建议使用 {@link getBeautyManager} 替代之。
*/
+#if TARGET_OS_IPHONE
- (void)setChinLevel:(float)chinLevel __attribute__((deprecated("use getBeautyManager instead")));
+#endif
/**
- * 设置短脸级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
+ * 设置短脸级别
*
- * @deprecated v6.9 版本弃用，请使用 TXBeautyManager 设置美颜功能
- * @param faceShortlevel 短脸级别，取值范围 0 - 9；0 表示关闭，1 - 9 值越大，效果越明显。
+ * @deprecated v6.9 版本开始不推荐使用，建议使用 {@link getBeautyManager} 替代之。
*/
+#if TARGET_OS_IPHONE
- (void)setFaceShortLevel:(float)faceShortlevel __attribute__((deprecated("use getBeautyManager instead")));
+#endif
/**
- * 设置瘦鼻级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
+ * 设置瘦鼻级别
*
- * @deprecated v6.9 版本弃用，请使用 TXBeautyManager 设置美颜功能
- * @param noseSlimLevel 瘦鼻级别，取值范围 0 - 9；0 表示关闭，1 - 9 值越大，效果越明显。
+ * @deprecated v6.9 版本开始不推荐使用，建议使用 {@link getBeautyManager} 替代之。
*/
+#if TARGET_OS_IPHONE
- (void)setNoseSlimLevel:(float)noseSlimLevel __attribute__((deprecated("use getBeautyManager instead")));
+#endif
/**
- * 选择使用哪一款 AI 动效挂件，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
+ * 设置动效贴纸
*
- * @deprecated v6.9 版本弃用，请使用 TXBeautyManager 设置美颜功能
- * @param tmplPath 动效文件路径
+ * @deprecated v6.9 版本开始不推荐使用，建议使用 {@link getBeautyManager} 替代之。
*/
+#if TARGET_OS_IPHONE
- (void)selectMotionTmpl:(NSString *)tmplPath __attribute__((deprecated("use getBeautyManager instead")));
+#endif
/**
- * 设置动效静音，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
- *
- * 部分挂件本身会有声音特效，通过此 API 可以关闭特效播放时所带的声音效果。
+ * 设置动效静音
*
- * @deprecated v6.9 版本弃用，请使用 TXBeautyManager 设置美颜功能
- * @param motionMute YES：静音；NO：不静音。
+ * @deprecated v6.9 版本开始不推荐使用，建议使用 {@link getBeautyManager} 替代之。
*/
+#if TARGET_OS_IPHONE
- (void)setMotionMute:(BOOL)motionMute __attribute__((deprecated("use getBeautyManager instead")));
+#endif
-#elif TARGET_OS_MAC
/**
* 启动屏幕分享
*
- * @deprecated v7.2 版本弃用，请使用 startScreenCapture:streamType:encParam: 启动屏幕分享
- * @param view 渲染控件所在的父控件
+ * @deprecated v7.2 版本开始不推荐使用，建议使用 startScreenCapture:streamType:encParam: 替代之。
*/
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
- (void)startScreenCapture:(NSView *)view __attribute__((deprecated("use startScreenCapture:streamType:encParam: instead")));
-
#endif
/**
- * 设置指定素材滤镜特效
+ * 设置色彩滤镜效果
*
- * @deprecated v7.2 版本弃用，请使用 TXBeautyManager 设置素材滤镜
- * @param image 指定素材，即颜色查找表图片。**必须使用 png 格式**
+ * @deprecated v7.2 版本开始不推荐使用，建议使用 {@link getBeautyManager} 替代之。
*/
- (void)setFilter:(TXImage *)image __attribute__((deprecated("use getBeautyManager instead")));
/**
- * 设置滤镜浓度
- *
- * 在美女秀场等应用场景里，滤镜浓度的要求会比较高，以便更加突显主播的差异。
- * 我们默认的滤镜浓度是0.5，如果您觉得滤镜效果不明显，可以使用下面的接口进行调节。
+ * 设置色彩滤镜浓度
*
- * @deprecated v7.2 版本弃用，请使用 TXBeautyManager setFilterStrength 接口
- * @param concentration 从 0 到 1，越大滤镜效果越明显，默认值为0.5。
+ * @deprecated v7.2 版本开始不推荐使用，建议使用 {@link getBeautyManager} 替代之。
*/
- (void)setFilterConcentration:(float)concentration __attribute__((deprecated("use getBeautyManager instead")));
/**
- * 设置绿幕背景视频（企业版有效，其它版本设置此参数无效）
+ * 设置绿幕背景视频
*
- * 此处的绿幕功能并非智能抠背，需要被拍摄者的背后有一块绿色的幕布来辅助产生特效
- *
- * @deprecated v7.2 版本弃用，请使用 TXBeautyManager 设置绿幕背景视频
- * @param file 视频文件路径。支持 MP4; nil 表示关闭特效。
+ * @deprecated v7.2 版本开始不推荐使用，建议使用 {@link getBeautyManager} 替代之。
*/
- (void)setGreenScreenFile:(NSURL *)file __attribute__((deprecated("use getBeautyManager instead")));
/**
* 启动播放背景音乐
*
- * @deprecated v7.3 版本弃用，请使用 TXAudioEffectManager startPlayMusic 接口，支持并发播放多个 BGM
- * @param path 音乐文件路径，支持的文件格式：aac, mp3, m4a。
- * @param beginNotify 音乐播放开始的回调通知
- * @param progressNotify 音乐播放的进度通知，单位毫秒
- * @param completeNotify 音乐播放结束的回调通知
+ * @deprecated v7.3 版本开始不推荐使用，建议使用 {@link getAudioEffectManager} 替代之。
*/
-- (void) playBGM:(NSString *)path
- withBeginNotify:(void (^)(NSInteger errCode))beginNotify
-withProgressNotify:(void (^)(NSInteger progressMS, NSInteger durationMS))progressNotify
- andCompleteNotify:(void (^)(NSInteger errCode))completeNotify
- __attribute__((deprecated("use getAudioEffectManager instead")));
+- (void)playBGM:(NSString *)path
+ withBeginNotify:(void (^)(NSInteger errCode))beginNotify
+ withProgressNotify:(void (^)(NSInteger progressMS, NSInteger durationMS))progressNotify
+ andCompleteNotify:(void (^)(NSInteger errCode))completeNotify __attribute__((deprecated("use getAudioEffectManager instead")));
/**
* 停止播放背景音乐
*
- * @deprecated v7.3 版本弃用，请使用 TXAudioEffectManager stopPlayMusic 接口
+ * @deprecated v7.3 版本开始不推荐使用，建议使用 {@link getAudioEffectManager} 替代之。
*/
- (void)stopBGM __attribute__((deprecated("use getAudioEffectManager instead")));
/**
- * 暂停播放背景音乐
+ * 停止播放背景音乐
*
- * @deprecated v7.3 版本弃用，请使用 TXAudioEffectManager pausePlayMusic 接口
+ * @deprecated v7.3 版本开始不推荐使用，建议使用 {@link getAudioEffectManager} 替代之。
*/
- (void)pauseBGM __attribute__((deprecated("use getAudioEffectManager instead")));
/**
- * 继续播放背景音乐
+ * 停止播放背景音乐
*
- * @deprecated v7.3 版本弃用，请使用 TXAudioEffectManager resumePlayMusic 接口
+ * @deprecated v7.3 版本开始不推荐使用，建议使用 {@link getAudioEffectManager} 替代之。
*/
- (void)resumeBGM __attribute__((deprecated("use getAudioEffectManager instead")));
/**
- * 获取音乐文件总时长，单位毫秒
+ * 获取背景音乐总时长（单位：毫秒）
*
- * @deprecated v7.3 版本弃用，请使用 TXAudioEffectManager getMusicDurationInMS 接口
- * @param path 音乐文件路径，如果 path 为空，那么返回当前正在播放的 music 时长。
- * @return 成功返回时长，失败返回 -1
+ * @deprecated v7.3 版本开始不推荐使用，建议使用 {@link TXAudioEffectManager#getMusicDurationInMS} 替代之。
*/
-- (NSInteger)getBGMDuration:(NSString *)path __attribute__((deprecated("use getAudioEffectManager instead")));
+- (NSInteger)getBGMDuration:(NSString *)path __attribute__((deprecated("use TXAudioEffectManager#getMusicDurationInMS instead")));
/**
- * 设置 BGM 播放进度
+ * 设置背景音乐的播放进度
*
- * @deprecated v7.3 版本弃用，请使用 TXAudioEffectManager seekMusicToPosInMS 接口
- * @param pos 单位毫秒
- * @return 0：成功；-1：失败
+ * @deprecated v7.3 版本开始不推荐使用，建议使用 {@link TXAudioEffectManager#seekMusicToPosInMS} 替代之。
*/
-- (int)setBGMPosition:(NSInteger)pos __attribute__((deprecated("use getAudioEffectManager instead")));
+- (int)setBGMPosition:(NSInteger)pos __attribute__((deprecated("use TXAudioEffectManager#seekMusicToPosInMS instead")));
/**
- * 设置背景音乐播放音量的大小
- *
- * @deprecated v7.3 版本弃用，请使用 TXAudioEffectManager setMusicVolume 接口
- * 播放背景音乐混音时使用，用来控制背景音乐播放音量的大小，
- * 该接口会同时控制远端播放音量的大小和本地播放音量的大小，
- * 因此调用该接口后，setBGMPlayoutVolume 和 setBGMPublishVolume 设置的音量值会被覆盖
+ * 设置背景音乐的音量大小
*
- * @param volume 音量大小，100 为原始音量，范围是：[0 ~ 150]，默认值为 100
- *
- * @note 如果要将 volume 设置为大于100的数值，需要进行特殊配置，请联系技术支持。
+ * @deprecated v7.3 版本开始不推荐使用，建议使用 {@link TXAudioEffectManager#setMusicVolume} 替代之。
*/
-- (void)setBGMVolume:(NSInteger)volume __attribute__((deprecated("use getAudioEffectManager instead")));
+- (void)setBGMVolume:(NSInteger)volume __attribute__((deprecated("use TXAudioEffectManager#setMusicVolume instead")));
/**
- * 设置背景音乐本地播放音量的大小
- *
- * @deprecated v7.3 版本弃用，请使用 TXAudioEffectManager setMusicPlayoutVolume 接口
- * 播放背景音乐混音时使用，用来控制背景音乐在本地播放时的音量大小。
+ * 设置背景音乐的本地播放音量
*
- * @param volume 音量大小，100 为原始音量，范围是：[0 ~ 150]，默认值为 100
- *
- * @note 如果要将 volume 设置为大于 100 的数值，需要进行特殊配置，请联系技术支持。
+ * @deprecated v7.3 版本开始不推荐使用，建议使用 {@link TXAudioEffectManager#setMusicPlayoutVolume} 替代之。
*/
-- (void)setBGMPlayoutVolume:(NSInteger)volume __attribute__((deprecated("use getAudioEffectManager instead")));
+- (void)setBGMPlayoutVolume:(NSInteger)volume __attribute__((deprecated("use TXAudioEffectManager#setMusicPlayoutVolume instead")));
/**
- * 设置背景音乐远端播放音量的大小
- *
- * @deprecated v7.3 版本弃用，请使用 TXAudioEffectManager setMusicPublishVolume 接口
- * 播放背景音乐混音时使用，用来控制背景音乐在远端播放时的音量大小。
+ * 设置背景音乐的远端播放音量
*
- * @param volume 音量大小，100 为原始音量，范围是：[0 ~ 150]，默认值为 100
- *
- * @note 如果要将 volume 设置为大于 100 的数值，需要进行特殊配置，请联系技术支持。
+ * @deprecated v7.3 版本开始不推荐使用，建议使用 {@link TXAudioEffectManager#setBGMPublishVolume} 替代之。
*/
-- (void)setBGMPublishVolume:(NSInteger)volume __attribute__((deprecated("use getAudioEffectManager instead")));
+- (void)setBGMPublishVolume:(NSInteger)volume __attribute__((deprecated("use TXAudioEffectManager#setBGMPublishVolume instead")));
/**
- * 设置混响效果，目前仅支持 iOS
+ * 设置混响效果
*
- * @deprecated v7.3 版本弃用，请使用 TXAudioEffectManager setVoiceReverbType 接口
- * @param reverbType 混响类型，详情请参见 TXReverbType
+ * @deprecated v7.3 版本开始不推荐使用，建议使用 {@link TXAudioEffectManager#setVoiceReverbType} 替代之。
*/
-- (void)setReverbType:(TRTCReverbType)reverbType __attribute__((deprecated("use getAudioEffectManager instead")));
+- (void)setReverbType:(TRTCReverbType)reverbType __attribute__((deprecated("use TXAudioEffectManager#setVoiceReverbType instead")));
/**
- * 设置变声类型，目前仅支持 iOS
+ * 设置变声类型
*
- * @deprecated v7.3 版本弃用，请使用 TXAudioEffectManager setVoiceChangerType 接口
- * @param voiceChangerType 变声类型，详情请参见 TXVoiceChangerType
+ * @deprecated v7.3 版本开始不推荐使用，建议使用 {@link TXAudioEffectManager#setVoiceChangerType} 替代之。
*/
-- (void)setVoiceChangerType:(TRTCVoiceChangerType)voiceChangerType __attribute__((deprecated("use getAudioEffectManager instead")));
+- (void)setVoiceChangerType:(TRTCVoiceChangerType)voiceChangerType __attribute__((deprecated("use TXAudioEffectManager#setVoiceChangerType instead")));
/**
* 播放音效
*
- * @deprecated v7.3 版本弃用，请使用 TXAudioEffectManager startPlayMusic 接口
- * 每个音效都需要您指定具体的 ID，您可以通过该 ID 对音效的开始、停止、音量等进行设置。
- * 支持的文件格式：aac, mp3, m4a。
- *
- * @note 若您想同时播放多个音效，请分配不同的 ID 进行播放。因为使用同一个 ID 播放不同音效，SDK 会先停止播放旧的音效，再播放新的音效。
- *
- * @param effect 音效
+ * @deprecated v7.3 版本开始不推荐使用，建议使用 {@link TXAudioEffectManager#startPlayMusic} 替代之。
*/
-- (void)playAudioEffect:(TRTCAudioEffectParam*)effect __attribute__((deprecated("use getAudioEffectManager instead")));
+- (void)playAudioEffect:(TRTCAudioEffectParam *)effect __attribute__((deprecated("use TXAudioEffectManager#startPlayMusic instead")));
/**
* 设置音效音量
*
- * @deprecated v7.3 版本弃用，请使用 TXAudioEffectManager setMusicPublishVolume / setMusicPlayoutVolume 接口
- * @note 该操作会覆盖通过 setAllAudioEffectsVolume 指定的整体音效音量。
- *
- * @param effectId 音效 ID
- * @param volume 音量大小，100 为原始音量，范围是：[0 ~ 150]，默认值为 100
- *
- * @note 如果要将 volume 设置为大于 100 的数值，需要进行特殊配置，请联系技术支持。
+ * @deprecated v7.3 版本开始不推荐使用，建议使用 {@link TXAudioEffectManager#setMusicPublishVolume} 和{@link TXAudioEffectManager#setMusicPlayoutVolume} 替代之。
*/
-- (void)setAudioEffectVolume:(int)effectId volume:(int) volume __attribute__((deprecated("use getAudioEffectManager instead")));
+- (void)setAudioEffectVolume:(int)effectId volume:(int)volume __attribute__((deprecated("use setMusicPublishVolume/setMusicPlayoutVolume instead")));
/**
- * 停止音效
+ * 停止播放音效
*
- * @deprecated v7.3 版本弃用，请使用 TXAudioEffectManager stopPlayMusic 接口
- * @param effectId 音效 ID
+ * @deprecated v7.3 版本开始不推荐使用，建议使用 {@link TXAudioEffectManager#stopPlayMusic} 替代之。
*/
-- (void)stopAudioEffect:(int)effectId __attribute__((deprecated("use getAudioEffectManager instead")));
+- (void)stopAudioEffect:(int)effectId __attribute__((deprecated("use TXAudioEffectManager#stopPlayMusic instead")));
/**
* 停止所有音效
*
- * @deprecated v7.3 版本弃用，请使用 TXAudioEffectManager stopPlayMusic 接口
+ * @deprecated v7.3 版本开始不推荐使用，建议使用 {@link TXAudioEffectManager#stopPlayMusic} 替代之。
*/
-- (void)stopAllAudioEffects __attribute__((deprecated("use getAudioEffectManager instead")));
+- (void)stopAllAudioEffects __attribute__((deprecated("use TXAudioEffectManager#stopPlayMusic instead")));
/**
* 设置所有音效音量
*
- * @deprecated v7.3 版本弃用，请使用 TXAudioEffectManager setMusicPublishVolume / setMusicPlayoutVolume 接口
- * @note 该操作会覆盖通过 setAudioEffectVolume 指定的单独音效音量。
- *
- * @param volume 音量大小，100 为原始音量，范围是：[0 ~ 150]，默认值为 100
- *
- * @note 如果要将 volume 设置为大于 100 的数值，需要进行特殊配置，请联系技术支持。
+ * @deprecated v7.3 版本开始不推荐使用，建议使用 {@link TXAudioEffectManager#setMusicPublishVolume} 和{@link TXAudioEffectManager#setMusicPlayoutVolume} 替代之。
*/
-- (void)setAllAudioEffectsVolume:(int)volume __attribute__((deprecated("use getAudioEffectManager instead")));
+- (void)setAllAudioEffectsVolume:(int)volume __attribute__((deprecated("use setMusicPublishVolume/setMusicPlayoutVolume instead")));
/**
* 暂停音效
*
- * @deprecated v7.3 版本弃用，请使用 TXAudioEffectManager pausePlayMusic 接口
- * @param effectId 音效 ID
+ * @deprecated v7.3 版本开始不推荐使用，建议使用 {@link TXAudioEffectManager#pauseAudioEffect} 替代之。
*/
-- (void)pauseAudioEffect:(int)effectId __attribute__((deprecated("use getAudioEffectManager instead")));
+- (void)pauseAudioEffect:(int)effectId __attribute__((deprecated("use TXAudioEffectManager#pauseAudioEffect instead")));
/**
- * 恢复音效
+ * 暂停音效
*
- * @deprecated v7.3 版本弃用，请使用 TXAudioEffectManager resumePlayMusic 接口
- * @param effectId 音效 ID
+ * @deprecated v7.3 版本开始不推荐使用，建议使用 {@link TXAudioEffectManager#resumePlayMusic} 替代之。
*/
-- (void)resumeAudioEffect:(int)effectId __attribute__((deprecated("use getAudioEffectManager instead")));
+- (void)resumeAudioEffect:(int)effectId __attribute__((deprecated("use TXAudioEffectManager#resumePlayMusic instead")));
-#if TARGET_OS_IPHONE
/**
- * 开启耳返
- *
- * @deprecated v7.3 版本弃用，请使用 TXAudioEffectManager setVoiceEarMonitor 接口
- * 开启后会在耳机里听到自己的声音。
+ * 开启（或关闭）耳返
*
- * @note 仅在戴耳机时有效
- *
- * @param enable YES：开启；NO：关闭，默认值：NO
+ * @deprecated v7.3 版本开始不推荐使用，建议使用 {@link TXAudioEffectManager#setVoiceEarMonitor} 替代之。
*/
-- (void)enableAudioEarMonitoring:(BOOL)enable __attribute__((deprecated("use getAudioEffectManager instead")));
+#if TARGET_OS_IPHONE
+- (void)enableAudioEarMonitoring:(BOOL)enable __attribute__((deprecated("use TXAudioEffectManager#setVoiceEarMonitor instead")));
#endif
/**
* 开始显示远端视频画面
*
- * @deprecated v8.0 版本弃用，请使用 startRemoteView:streamType:view 接口
- * 在收到 SDK 的 onUserVideoAvailable(userid, YES) 通知时，可以获知该远程用户开启了视频，
- * 此后调用 startRemoteView(userid) 接口加载该用户的远程画面，此时可以用 loading 动画优化加载过程中的等待体验。
- * 待该用户的首帧画面开始显示时，您会收到 onFirstVideoFrame(userId) 事件回调。
- *
- * @param userId 对方的用户标识
- * @param view 承载视频画面的控件
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link startRemoteView:streamType:view} 替代之。
*/
- (void)startRemoteView:(NSString *)userId view:(TXView *)view __attribute__((deprecated("use startRemoteView:streamType:view: instead")));
/**
* 停止显示远端视频画面，同时不再拉取该远端用户的视频数据流
*
- * @deprecated v8.0 版本弃用，请使用 stopRemoteView:streamType: 接口
- * 调用此接口后，SDK 会停止接收该用户的远程视频流，同时会清理相关的视频显示资源。
- *
- * @param userId 对方的用户标识
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link stopRemoteView:streamType:} 替代之。
*/
- (void)stopRemoteView:(NSString *)userId __attribute__((deprecated("use stopRemoteView:streamType: instead")));
/**
* 设置远端图像的渲染模式
*
- * @deprecated v8.0 版本弃用，请使用 setRemoteRenderParams:streamType:params: 接口
- * @param userId 用户 ID
- * @param mode 填充（画面可能会被拉伸裁剪）或适应（画面可能会有黑边），默认值：TRTCVideoFillMode_Fill
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link setRemoteRenderParams:streamType:params:} 替代之。
*/
-- (void)setRemoteViewFillMode:(NSString*)userId mode:(TRTCVideoFillMode)mode __attribute__((deprecated("use setRemoteRenderParams:streamType:params: instead")));
-
+- (void)setRemoteViewFillMode:(NSString *)userId mode:(TRTCVideoFillMode)mode __attribute__((deprecated("use setRemoteRenderParams:streamType:params: instead")));
/**
* 设置远端图像的顺时针旋转角度
*
- * @deprecated v8.0 版本弃用，请使用 setRemoteRenderParams:streamType:params: 接口
- * @param userId 用户 ID
- * @param rotation 支持90、180以及270旋转角度，默认值：TRTCVideoRotation_0
- */
-- (void)setRemoteViewRotation:(NSString*)userId rotation:(TRTCVideoRotation)rotation __attribute__((deprecated("use setRemoteRenderParams:streamType:params: instead")));
-
-/**
- * 开始显示远端用户的辅路画面（TRTCVideoStreamTypeSub，一般用于屏幕分享）
- *
- * @deprecated v8.0 版本弃用，请使用 startRemoteView:streamType:view 接口
- * - startRemoteView() 用于显示主路画面（TRTCVideoStreamTypeBig，一般用于摄像头）。
- * - startRemoteSubStreamView() 用于显示辅路画面（TRTCVideoStreamTypeSub，一般用于屏幕分享）。
- *
- * @param userId 对方的用户标识
- * @param view 渲染控件
- * @note 请在 onUserSubStreamAvailable 回调后再调用这个接口。
- */
-- (void)startRemoteSubStreamView:(NSString *)userId view:(TXView *)view __attribute__((deprecated("use startRemoteView:type:view: instead")));
-
-/**
- * 停止显示远端用户的辅路画面（TRTCVideoStreamTypeSub，一般用于屏幕分享）。
- *
- * @deprecated v8.0 版本弃用，请使用 stopRemoteView:streamType: 接口
- * @param userId 对方的用户标识
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link setRemoteRenderParams:streamType:params:} 替代之。
*/
-- (void)stopRemoteSubStreamView:(NSString *)userId __attribute__((deprecated("use stopRemoteView:streamType: instead")));
+- (void)setRemoteViewRotation:(NSString *)userId rotation:(TRTCVideoRotation)rotation __attribute__((deprecated("use setRemoteRenderParams:streamType:params: instead")));
/**
* 设置本地图像的渲染模式
*
- * @deprecated v8.0 版本弃用，请使用 setLocalRenderParams: 接口
- * @param mode 填充（画面可能会被拉伸裁剪）或适应（画面可能会有黑边），默认值：TRTCVideoFillMode_Fill
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link setLocalRenderParams} 替代之。
*/
-- (void)setLocalViewFillMode:(TRTCVideoFillMode)mode __attribute__((deprecated("use setLocalRenderParams: instead")));
+- (void)setLocalViewFillMode:(TRTCVideoFillMode)mode __attribute__((deprecated("use setLocalRenderParams instead")));
/**
* 设置本地图像的顺时针旋转角度
*
- * @deprecated v8.0 版本弃用，请使用 setLocalRenderParams: 接口
- * @param rotation 支持90、180以及270旋转角度，默认值：TRTCVideoRotation_0
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link setLocalRenderParams} 替代之。
*/
-- (void)setLocalViewRotation:(TRTCVideoRotation)rotation __attribute__((deprecated("use setLocalRenderParams: instead")));
+- (void)setLocalViewRotation:(TRTCVideoRotation)rotation __attribute__((deprecated("use setLocalRenderParams instead")));
-#if TARGET_OS_IPHONE
/**
- * 设置本地摄像头预览画面的镜像模式（iOS）
+ * 设置本地摄像头预览画面的镜像模式
*
- * @deprecated v8.0 版本弃用，请使用 setLocalRenderParams: 接口
- * @param mirror 镜像模式，默认值：TRTCLocalVideoMirrorType_Auto
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link setLocalRenderParams} 替代之。
*/
+#if TARGET_OS_IPHONE
- (void)setLocalViewMirror:(TRTCLocalVideoMirrorType)mirror __attribute__((deprecated("use setLocalRenderParams: instead")));
#elif TARGET_OS_MAC
+- (void)setLocalViewMirror:(BOOL)mirror __attribute__((deprecated("use setLocalRenderParams: instead")));
+#endif
/**
- * 设置本地摄像头预览画面的镜像模式（Mac）
+ * 开始显示远端用户的辅路画面
*
- * @deprecated v8.0 版本弃用，请使用 setLocalRenderParams: 接口
- * @param mirror 镜像模式，默认值：YES
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link startRemoteView:streamType:view} 替代之。
*/
-- (void)setLocalViewMirror:(BOOL)mirror __attribute__((deprecated("use setLocalRenderParams: instead")));
-#endif
+- (void)startRemoteSubStreamView:(NSString *)userId view:(TXView *)view __attribute__((deprecated("use startRemoteView:type:view: instead")));
/**
- * 设置辅路画面（TRTCVideoStreamTypeSub，一般用于屏幕分享）的显示模式
+ * 停止显示远端用户的辅路画面
*
- * @deprecated v8.0 版本弃用，请使用 setRemoteRenderParams:streamType:params: 接口
- * - setRemoteViewFillMode() 用于设置远端主路画面（TRTCVideoStreamTypeBig，一般用于摄像头）的显示模式。
- * - setRemoteSubStreamViewFillMode() 用于设置远端辅路画面（TRTCVideoStreamTypeSub，一般用于屏幕分享）的显示模式。
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link stopRemoteView:streamType:} 替代之。
+ */
+- (void)stopRemoteSubStreamView:(NSString *)userId __attribute__((deprecated("use stopRemoteView:streamType: instead")));
+
+/**
+ * 设置辅路画面的填充模式
*
- * @param userId 用户的 ID
- * @param mode 填充（画面可能会被拉伸裁剪）或适应（画面可能会有黑边），默认值：TRTCVideoFillMode_Fit
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link setRemoteRenderParams:streamType:params:} 替代之。
*/
- (void)setRemoteSubStreamViewFillMode:(NSString *)userId mode:(TRTCVideoFillMode)mode __attribute__((deprecated("use setRemoteRenderParams:streamType:params: instead")));
/**
- * 设置辅路画面（TRTCVideoStreamTypeSub，一般用于屏幕分享）的顺时针旋转角度
+ * 设置辅路画面的顺时针旋转角度
*
- * @deprecated v8.0 版本弃用，请使用 setRemoteRenderParams:streamType:params: 接口
- * - setRemoteViewRotation() 用于设置远端主路画面（TRTCVideoStreamTypeBig，一般用于摄像头）的旋转角度。
- * - setRemoteSubStreamViewRotation() 用于设置远端辅路画面（TRTCVideoStreamTypeSub，一般用于屏幕分享）的旋转角度。
- *
- * @param userId 用户 ID
- * @param rotation 支持 90、180、270 旋转角度
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link setRemoteRenderParams:streamType:params:} 替代之。
*/
-- (void)setRemoteSubStreamViewRotation:(NSString*)userId rotation:(TRTCVideoRotation)rotation __attribute__((deprecated("use setRemoteRenderParams:streamType:params: instead")));
+- (void)setRemoteSubStreamViewRotation:(NSString *)userId rotation:(TRTCVideoRotation)rotation __attribute__((deprecated("use setRemoteRenderParams:streamType:params: instead")));
/**
- * 设定观看方优先选择的视频质量
+ * 设定优先观看大画面还是小画面
*
- * @deprecated v8.0 版本弃用，请使用 startRemoteView:streamType:view: 接口
- * 低端设备推荐优先选择低清晰度的小画面。
- * 如果对方没有开启双路视频模式，则此操作无效。
- *
- * @param type 默认观看大画面或小画面，默认为大画面
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link startRemoteView:streamType:view:} 替代之。
*/
-- (void)setPriorRemoteVideoStreamType:(TRTCVideoStreamType)type __attribute__((deprecated("use startRemoteView:streamType:view: instead")));
+- (void)setPriorRemoteVideoStreamType:(TRTCVideoStreamType)streamType __attribute__((deprecated("use startRemoteView:streamType:view: instead")));
/**
* 设置音频质量
*
- * @deprecated v8.0 版本弃用，请使用 startLocalAudio(quality) 接口
- * 主播端的音质越高，观众端的听感越好，但传输所依赖的带宽也就越高，在带宽有限的场景下也更容易出现卡顿。
- *
- * - {@link TRTCCloudDef#TRTCAudioQualitySpeech}， 流畅：采样率：16k；单声道；音频裸码率：16kbps；适合语音通话为主的场景，比如在线会议，语音通话。
- * - {@link TRTCCloudDef#TRTCAudioQualityDefault}，默认：采样率：48k；单声道；音频裸码率：50kbps；SDK 默认的音频质量，如无特殊需求推荐选择之。
- * - {@link TRTCCloudDef#TRTCAudioQualityMusic}，高音质：采样率：48k；双声道 + 全频带；音频裸码率：128kbps；适合需要高保真传输音乐的场景，比如K歌、音乐直播等。
- * @note 该方法需要在 startLocalAudio 之前进行设置，否则不会生效。
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link startLocalAudio:}(quality) 替代之。
*/
- (void)setAudioQuality:(TRTCAudioQuality)quality __attribute__((deprecated("use startLocalAudio(quality) instead")));
/**
- * 开启本地音频的采集和上行
- *
- * @deprecated v8.0 版本弃用，请使用 startLocalAudio(quality) 接口
- * 该函数会启动麦克风采集，并将音频数据传输给房间里的其他用户。
- * SDK 不会默认开启本地音频采集和上行，您需要调用该函数开启，否则房间里的其他用户将无法听到您的声音。
+ * 设置音频质量
*
- * @note 该函数会检查麦克风的使用权限，如果当前 App 没有麦克风权限，SDK 会向用户申请开启。
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link startLocalAudio:}(quality) 替代之。
*/
- (void)startLocalAudio __attribute__((deprecated("use startLocalAudio(quality) instead")));
-#if TARGET_OS_IPHONE
-
/**
* 切换摄像头
*
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager switchCamera 接口
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 switchCamera 接口替代之。
*/
-- (void)switchCamera __attribute__((deprecated("use getDeviceManager instead")));
+#if TARGET_OS_IPHONE
+- (void)switchCamera __attribute__((deprecated("use TXDeviceManager#switchCamera instead")));
+#endif
/**
* 查询当前摄像头是否支持缩放
*
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager isCameraZoomSupported 接口
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 isCameraZoomSupported 接口替代之。
*/
-- (BOOL)isCameraZoomSupported __attribute__((deprecated("use getDeviceManager instead")));
+#if TARGET_OS_IPHONE
+- (BOOL)isCameraZoomSupported __attribute__((deprecated("use TXDeviceManager#isCameraZoomSupported instead")));
+#endif
/**
- * 查询是否支持开关闪光灯（手电筒模式）
+ * 设置摄像头缩放倍数（焦距）
*
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager isCameraTorchSupported 接口
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 setCameraZoomRatio 接口替代之。
*/
-- (BOOL)isCameraTorchSupported __attribute__((deprecated("use getDeviceManager instead")));
-
+#if TARGET_OS_IPHONE
+- (void)setZoom:(CGFloat)distance __attribute__((deprecated("use TXDeviceManager#setCameraZoomRatio instead")));
+#endif
/**
- * 查询是否支持设置焦点
+ * 查询是否支持开关闪光灯
*
- * @deprecated v8.0 版本弃用
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 isCameraTorchSupported 接口替代之。
*/
-- (BOOL)isCameraFocusPositionInPreviewSupported __attribute__((deprecated));
+#if TARGET_OS_IPHONE
+- (BOOL)isCameraTorchSupported __attribute__((deprecated("use TXDeviceManager#isCameraTorchSupported instead")));
+#endif
/**
- * 设置摄像头焦点
+ * 开关/关闭闪光灯
*
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager setCameraFocusPosition 接口
- * @param touchPoint 对焦位置
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 enableCameraTorch 接口替代之。
*/
-- (void)setFocusPosition:(CGPoint)touchPoint __attribute__((deprecated("use getDeviceManager instead")));
+#if TARGET_OS_IPHONE
+- (BOOL)enbaleTorch:(BOOL)enable __attribute__((deprecated("use TXDeviceManager#enableCameraTorch instead")));
+#endif
/**
- * 查询是否支持自动识别人脸位置
+ * 查询摄像头是否支持设置焦点
*
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager isAutoFocusEnabled 接口
+ * @deprecated v8.0 版本开始不推荐使用。
*/
-- (BOOL)isCameraAutoFocusFaceModeSupported __attribute__((deprecated("use getDeviceManager instead")));
+#if TARGET_OS_IPHONE
+- (BOOL)isCameraFocusPositionInPreviewSupported __attribute__((deprecated));
+#endif
/**
- * 自动识别人脸位置
+ * 设置摄像头焦点坐标位置
*
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager enableCameraAutoFocus 接口
- * @param enable YES：开启；NO：关闭，默认值：YES
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 setCameraFocusPosition 接口替代之。
*/
-- (void)enableAutoFaceFoucs:(BOOL)enable __attribute__((deprecated("use getDeviceManager instead")));
+#if TARGET_OS_IPHONE
+- (void)setFocusPosition:(CGPoint)touchPoint __attribute__((deprecated("use TXDeviceManager#setCameraFocusPosition instead")));
+#endif
/**
- * 设置摄像头缩放因子（焦距）
- *
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager setCameraZoomRatio 接口
- * 取值范围1 - 5，取值为 1 表示最远视角（正常镜头），取值为 5 表示最近视角（放大镜头）。
- * 最大值推荐为 5，若超过 5，视频数据会变得模糊不清。
+ * 查询是否支持自动识别人脸位置
*
- * @param distance 取值范围为1 - 5，数值越大，焦距越远
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 isAutoFocusEnabled 接口替代之。
*/
-- (void)setZoom:(CGFloat)distance __attribute__((deprecated("use getDeviceManager instead")));
+#if TARGET_OS_IPHONE
+- (BOOL)isCameraAutoFocusFaceModeSupported __attribute__((deprecated("use TXDeviceManager#isAutoFocusEnabled instead")));
+#endif
/**
- * 开关闪光灯
+ * 开启/关闭人脸跟踪对焦
*
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager enableCameraTorch 接口
- * @param enable YES：开启；NO：关闭，默认值：NO
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 enableCameraAutoFocus 接口替代之。
*/
-- (BOOL)enbaleTorch:(BOOL)enable __attribute__((deprecated("use getDeviceManager instead")));
-
+#if TARGET_OS_IPHONE
+- (void)enableAutoFaceFoucs:(BOOL)enable __attribute__((deprecated("use TXDeviceManager#enableCameraAutoFocus instead")));
#endif
/**
- * 设置通话时使用的系统音量类型
- *
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager setSystemVolumeType 接口
- * 智能手机一般具备两种系统音量类型，即通话音量类型和媒体音量类型。
- * - 通话音量：手机专门为通话场景设计的音量类型，使用手机自带的回声抵消功能，音质相比媒体音量类型较差，
- * 无法通过音量按键将音量调成零，但是支持蓝牙耳机上的麦克风。
- *
- * - 媒体音量：手机专门为音乐场景设计的音量类型，音质相比于通话音量类型要好，通过通过音量按键可以将音量调成零。
- * 使用媒体音量类型时，如果要开启回声抵消（AEC）功能，SDK 会开启内置的声学处理算法对声音进行二次处理。
- * 在媒体音量模式下，蓝牙耳机无法使用自带的麦克风采集声音，只能使用手机上的麦克风进行声音采集。
- *
- * SDK 目前提供了三种系统音量类型的控制模式，分别为：
- * - {@link TRTCSystemVolumeTypeAuto}：
- * “麦上通话，麦下媒体”，即主播上麦时使用通话音量，观众不上麦则使用媒体音量，适合在线直播场景。
- * 如果您在 enterRoom 时选择的场景为 {@link TRTCAppSceneLIVE} 或 {@link TRTCAppSceneVoiceChatRoom}，SDK 会自动选择该模式。
- *
- * - {@link TRTCSystemVolumeTypeVOIP}：
- * 通话全程使用通话音量，适合多人会议场景。
- * 如果您在 enterRoom 时选择的场景为 {@link TRTCAppSceneVideoCall} 或 {@link TRTCAppSceneAudioCall}，SDK 会自动选择该模式。
- *
- * - {@link TRTCSystemVolumeTypeMedia}：
- * 通话全程使用媒体音量，不常用，适合个别有特殊需求（如主播外接声卡）的应用场景。
- *
- * @note
- * 1. 需要在调用 startLocalAudio() 之前调用该接口。<br>
- * 2. 如无特殊需求，不推荐您自行设置，您只需通过 enterRoom 设置好适合您的场景，SDK 内部会自动选择相匹配的音量类型。
+ * 开始进行摄像头测试
*
- * @param type 系统音量类型，如无特殊需求，不推荐您自行设置。
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 startCameraDeviceTest 接口替代之。
*/
-- (void)setSystemVolumeType:(TRTCSystemVolumeType)type __attribute__((deprecated("use getDeviceManager instead")));
-
#if !TARGET_OS_IPHONE && TARGET_OS_MAC
+- (void)startCameraDeviceTestInView:(NSView *)view __attribute__((deprecated("use TXDeviceManager#startCameraDeviceTest instead")));
+#endif
/**
* 开始进行摄像头测试
*
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager startCameraDeviceTest 接口
- * @note 在测试过程中可以使用 setCurrentCameraDevice 接口切换摄像头。
- * @param view 预览控件所在的父控件
- */
-- (void)startCameraDeviceTestInView:(NSView *)view __attribute__((deprecated("use getDeviceManager instead")));
-
-/**
- * 结束视频测试预览
- *
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager stopCameraDeviceTest 接口
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 stopCameraDeviceTest 接口替代之。
*/
-- (void)stopCameraDeviceTest __attribute__((deprecated("use getDeviceManager instead")));
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
+- (void)stopCameraDeviceTest __attribute__((deprecated("use TXDeviceManager#stopCameraDeviceTest instead")));
+#endif
/**
* 开始进行麦克风测试
*
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager startMicDeviceTest 接口
- * 该方法测试麦克风是否能正常工作，volume 的取值范围为0 - 100。
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 startMicDeviceTest 接口替代之。
*/
-- (void)startMicDeviceTest:(NSInteger)interval testEcho:(void (^)(NSInteger volume))testEcho __attribute__((deprecated("use getDeviceManager instead")));
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
+- (void)startMicDeviceTest:(NSInteger)interval testEcho:(void (^)(NSInteger volume))testEcho __attribute__((deprecated("use TXDeviceManager#startMicDeviceTest instead")));
+#endif
/**
- * 停止麦克风测试
+ * 开始进行麦克风测试
*
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager stopMicDeviceTest 接口
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 stopMicDeviceTest 接口替代之。
*/
-- (void)stopMicDeviceTest __attribute__((deprecated("use getDeviceManager instead")));
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
+- (void)stopMicDeviceTest __attribute__((deprecated("use TXDeviceManager#stopMicDeviceTest instead")));
+#endif
/**
- * 开始扬声器测试
+ * 开始进行扬声器测试
*
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager startSpeakerDeviceTest 接口
- * 该方法播放指定的音频文件测试播放设备是否能正常工作。如果能听到声音，说明播放设备能正常工作。
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 startSpeakerDeviceTest 接口替代之。
*/
-- (void)startSpeakerDeviceTest:(NSString*)audioFilePath onVolumeChanged:(void (^)(NSInteger volume, BOOL isLastFrame))volumeBlock __attribute__((deprecated("use getDeviceManager instead")));
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
+- (void)startSpeakerDeviceTest:(NSString *)audioFilePath onVolumeChanged:(void (^)(NSInteger volume, BOOL isLastFrame))volumeBlock __attribute__((deprecated("use TXDeviceManager#startSpeakerDeviceTest instead")));
+#endif
/**
- * 停止扬声器测试
+ * 停止进行扬声器测试
*
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager stopSpeakerDeviceTest 接口
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 stopSpeakerDeviceTest 接口替代之。
*/
-- (void)stopSpeakerDeviceTest __attribute__((deprecated("use getDeviceManager instead")));
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
+- (void)stopSpeakerDeviceTest __attribute__((deprecated("use TXDeviceManager#stopSpeakerDeviceTest instead")));
+#endif
/**
* 获取麦克风设备列表
*
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager getDevicesList:type: 接口
- * Mac 主机本身自带一个质量很好的麦克风，但它也允许用户外接其他的麦克风，而且很多 USB 摄像头上也自带麦克风。
- * 如果您希望用户选择自己外接的麦克风，可以提供一个多麦克风选择的功能。
- *
- * @return 麦克风设备列表，第一项为当前系统默认设备
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 getDevicesList 接口替代之。
*/
-- (NSArray<TRTCMediaDeviceInfo*>*)getMicDevicesList __attribute__((deprecated("use getDeviceManager instead")));
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
+- (NSArray<TRTCMediaDeviceInfo *> *)getMicDevicesList __attribute__((deprecated("use TXDeviceManager#getDevicesList instead")));
+#endif
/**
* 获取当前的麦克风设备
*
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager getCurrentDevice 接口
- * @return 当前麦克风设备信息
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 getCurrentDevice 接口替代之。
*/
-- (TRTCMediaDeviceInfo*)getCurrentMicDevice __attribute__((deprecated("use getDeviceManager instead")));
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
+- (TRTCMediaDeviceInfo *)getCurrentMicDevice __attribute__((deprecated("use TXDeviceManager#getCurrentDevice instead")));
+#endif
/**
- * 设置要使用的麦克风
+ * 选定当前使用的麦克风
*
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager setCurrentDevice 接口
- * @param deviceId 从 getMicDevicesList 中得到的设备 ID
- * @return 0：成功；<0：失败
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 setCurrentDevice 接口替代之。
*/
-- (int)setCurrentMicDevice:(NSString*)deviceId __attribute__((deprecated("use getDeviceManager instead")));
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
+- (int)setCurrentMicDevice:(NSString *)deviceId __attribute__((deprecated("use TXDeviceManager#setCurrentDevice instead")));
+#endif
/**
- * 获取当前麦克风设备音量
+ * 获取当前麦克风的设备音量
*
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager getCurrentDeviceVolume 接口
- * @return 麦克风音量
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 getCurrentDeviceVolume 接口替代之。
*/
-- (float)getCurrentMicDeviceVolume __attribute__((deprecated("use getDeviceManager instead")));
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
+- (float)getCurrentMicDeviceVolume __attribute__((deprecated("use TXDeviceManager#getCurrentDeviceVolume instead")));
+#endif
/**
- * 设置麦克风设备的音量
- *
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager setCurrentDeviceVolume 接口
- * 该接口的功能是调节系统采集音量，如果用户直接调节 Mac 系统设置的采集音量时，该接口的设置结果会被用户的操作所覆盖。
+ * 设置当前麦克风的设备音量
*
- * @param volume 麦克风音量值，范围0 - 100
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 setCurrentDeviceVolume 接口替代之。
*/
-- (void)setCurrentMicDeviceVolume:(NSInteger)volume __attribute__((deprecated("use getDeviceManager instead")));
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
+- (void)setCurrentMicDeviceVolume:(NSInteger)volume __attribute__((deprecated("use TXDeviceManager#setCurrentDeviceVolume instead")));
+#endif
/**
- * 设置系统当前麦克风设备的静音状态
+ * 获取系统当前麦克风设备是否静音
*
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager setCurrentDeviceMute 接口
- * @param mute 设置为 YES 时，麦克风设备静音
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 getCurrentDeviceMute 接口替代之。
*/
-- (void)setCurrentMicDeviceMute:(BOOL)mute __attribute__((deprecated("use getDeviceManager instead")));
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
+- (BOOL)getCurrentMicDeviceMute __attribute__((deprecated("use TXDeviceManager#getCurrentDeviceMute instead")));
+#endif
/**
- * 获取系统当前麦克风设备是否静音
+ * 设置系统当前麦克风设备的静音状态
*
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager getCurrentDeviceMute 接口
- * @return 静音状态
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 setCurrentDeviceMute 接口替代之。
*/
-- (BOOL)getCurrentMicDeviceMute __attribute__((deprecated("use getDeviceManager instead")));
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
+- (void)setCurrentMicDeviceMute:(BOOL)mute __attribute__((deprecated("use TXDeviceManager#setCurrentDeviceMute instead")));
+#endif
/**
* 获取扬声器设备列表
*
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager getDevicesList:type: 接口
- * @return 扬声器设备列表，第一项为当前系统默认设备
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 getDevicesList 接口替代之。
*/
-- (NSArray<TRTCMediaDeviceInfo*>*)getSpeakerDevicesList __attribute__((deprecated("use getDeviceManager instead")));
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
+- (NSArray<TRTCMediaDeviceInfo *> *)getSpeakerDevicesList __attribute__((deprecated("use TXDeviceManager#getDevicesList instead")));
+#endif
/**
* 获取当前的扬声器设备
*
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager getCurrentDevice 接口
- * @return 当前扬声器设备信息
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 getCurrentDevice 接口替代之。
*/
-- (TRTCMediaDeviceInfo*)getCurrentSpeakerDevice __attribute__((deprecated("use getDeviceManager instead")));
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
+- (TRTCMediaDeviceInfo *)getCurrentSpeakerDevice __attribute__((deprecated("use TXDeviceManager#getCurrentDevice instead")));
+#endif
/**
* 设置要使用的扬声器
*
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager setCurrentDevice 接口
- * @param deviceId 从 getSpeakerDevicesList 中得到的设备 ID
- * @return 0：成功；<0：失败
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 setCurrentDevice 接口替代之。
*/
-- (int)setCurrentSpeakerDevice:(NSString*)deviceId __attribute__((deprecated("use getDeviceManager instead")));
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
+- (int)setCurrentSpeakerDevice:(NSString *)deviceId __attribute__((deprecated("use TXDeviceManager#setCurrentDevice instead")));
+#endif
/**
- * 当前扬声器设备音量
+ * 获取当前扬声器的设备音量
*
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager getCurrentDeviceVolume 接口
- * @return 扬声器音量
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 getCurrentDeviceVolume 接口替代之。
*/
-- (float)getCurrentSpeakerDeviceVolume __attribute__((deprecated("use getDeviceManager instead")));
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
+- (float)getCurrentSpeakerDeviceVolume __attribute__((deprecated("use TXDeviceManager#getCurrentDeviceVolume instead")));
+#endif
/**
- * 设置当前扬声器音量
+ * 设置当前扬声器的设备音量
*
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager setCurrentDeviceVolume 接口
- * 该接口的功能是调节系统播放音量，如果用户直接调节 Mac 系统设置的播放音量时，该接口的设置结果会被用户的操作所覆盖。
- *
- * @param volume 设置的扬声器音量，范围0 - 100
- * @return 0：成功；<0：失败
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 setCurrentDeviceVolume 接口替代之。
*/
-- (int)setCurrentSpeakerDeviceVolume:(NSInteger)volume __attribute__((deprecated("use getDeviceManager instead")));
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
+- (int)setCurrentSpeakerDeviceVolume:(NSInteger)volume __attribute__((deprecated("use TXDeviceManager#setCurrentDeviceVolume instead")));
+#endif
/**
- * 设置系统当前扬声器设备的静音状态
+ * 获取系统当前扬声器设备是否静音
*
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager setCurrentDeviceMute 接口
- * @param mute 设置为 YES 时，扬声器设备静音
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 getCurrentDeviceMute 接口替代之。
*/
-- (void)setCurrentSpeakerDeviceMute:(BOOL)mute __attribute__((deprecated("use getDeviceManager instead")));
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
+- (BOOL)getCurrentSpeakerDeviceMute __attribute__((deprecated("use TXDeviceManager#getCurrentDeviceMute instead")));
+#endif
/**
- * 获取系统当前扬声器设备是否静音
+ * 设置系统当前扬声器设备的静音状态
*
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager getCurrentDeviceMute 接口
- * @return 静音状态
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 setCurrentDeviceMute 接口替代之。
*/
-- (BOOL)getCurrentSpeakerDeviceMute __attribute__((deprecated("use getDeviceManager instead")));
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
+- (void)setCurrentSpeakerDeviceMute:(BOOL)mute __attribute__((deprecated("use TXDeviceManager#setCurrentDeviceMute instead")));
+#endif
/**
* 获取摄像头设备列表
*
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager getDevicesList 接口
- * Mac 主机本身自带一个摄像头，也允许插入 USB 摄像头。
- * 如果您希望用户选择自己外接的摄像头，可以提供一个多摄像头选择的功能。
- *
- * @return 摄像头设备列表，第一项为当前系统默认设备
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 getDevicesList 接口替代之。
*/
-- (NSArray<TRTCMediaDeviceInfo *> *)getCameraDevicesList __attribute__((deprecated("use getDeviceManager instead")));
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
+- (NSArray<TRTCMediaDeviceInfo *> *)getCameraDevicesList __attribute__((deprecated("use TXDeviceManager#getDevicesList instead")));
+#endif
/**
* 获取当前使用的摄像头
*
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager getCurrentDevice 接口
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 getCurrentDevice 接口替代之。
*/
-- (TRTCMediaDeviceInfo *)getCurrentCameraDevice __attribute__((deprecated("use getDeviceManager instead")));
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
+- (TRTCMediaDeviceInfo *)getCurrentCameraDevice __attribute__((deprecated("use TXDeviceManager#getCurrentDevice instead")));
+#endif
/**
- * 设置要使用的摄像头
+ * 选定当前要使用的摄像头
*
- * @deprecated v8.0 版本弃用，请使用 TXDeviceManager setCurrentDevice 接口
- * @param deviceId 从 getCameraDevicesList 中得到的设备 ID
- * @return 0：成功；-1：失败
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 setCurrentDevice 接口替代之。
*/
-- (int)setCurrentCameraDevice:(NSString *)deviceId __attribute__((deprecated("use getDeviceManager instead")));
-
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
+- (int)setCurrentCameraDevice:(NSString *)deviceId __attribute__((deprecated("use TXDeviceManager#setCurrentDevice instead")));
#endif
/**
- * 设置要使用的摄像头
+ * 设置系统音量类型
+ *
+ * @deprecated v8.0 版本开始不推荐使用，建议使用 {@link TXDeviceManager} 中的 setSystemVolumeType 接口替代之。
+ */
+- (void)setSystemVolumeType:(TRTCSystemVolumeType)type __attribute__((deprecated("use getDeviceManager instead")));
+
+/**
+ * 视频截图
*
- * @deprecated v8.2 版本弃用，请使用 snapshotVideo:type:sourceType:completionBlock 接口
+ * @deprecated v8.2 版本开始不推荐使用，建议使用 snapshotVideo:type:sourceType:completionBlock 替代之。
*/
-- (void)snapshotVideo:(NSString *)userId
- type:(TRTCVideoStreamType)type
- completionBlock:(void (^)(TXImage *image))completionBlock __attribute__((deprecated("use snapshotVideo:type:sourceType:completionBlock instead")));
+- (void)snapshotVideo:(NSString *)userId type:(TRTCVideoStreamType)streamType completionBlock:(void (^)(TXImage *image))completionBlock __attribute__((deprecated("use snapshotVideo:type:sourceType:completionBlock instead")));
/**
* 启用视频自定义采集模式
*
- * @deprecated v8.5 版本弃用，请使用 enableCustomVideoCapture:enable: 接口
- * 开启该模式后，SDK 不再运行原有的视频采集流程，只保留编码和发送能力。
- * 您需要用 sendCustomVideoData() 不断地向 SDK 塞入自己采集的视频画面。
+ * @deprecated v8.5 版本开始不推荐使用，建议使用 enableCustomVideoCapture(streamType,enable) 接口替代之。
+ */
+- (void)enableCustomVideoCapture:(BOOL)enable __attribute__((deprecated("use enableCustomVideoCapture:enable instead")));
+
+/**
+ * 投送自己采集的视频数据
*
- * @param enable 是否启用，默认值：NO
+ * @deprecated v8.5 版本开始不推荐使用，建议使用 sendCustomVideoData(streamType, TRTCVideoFrame) 接口替代之。
*/
-- (void)enableCustomVideoCapture:(BOOL)enable __attribute__((deprecated("use enableCustomVideoCapture:enable: instead")));
+- (void)sendCustomVideoData:(TRTCVideoFrame *)frame __attribute__((deprecated("use sendCustomVideoData:frame: instead")));
/**
- * 向 SDK 投送自己采集的视频数据
+ * 开始应用内的屏幕分享（iOS）
*
- * @deprecated v8.5 版本弃用，请使用 sendCustomVideoData:frame: 接口
- * TRTCVideoFrame 推荐下列填写方式（其他字段不需要填写）：
- * - pixelFormat：推荐选择 TRTCVideoPixelFormat_NV12。
- * - bufferType：推荐选择 TRTCVideoBufferType_PixelBuffer。
- * - pixelBuffer：iOS 平台上常用的视频数据格式。
- * - data：视频裸数据格式，bufferType 为 NSData 时使用。
- * - timestamp：如果 timestamp 间隔不均匀，会严重影响音画同步和录制出的 MP4 质量。
- * - width：视频图像长度，bufferType 为 NSData 时填写。
- * - height：视频图像宽度，bufferType 为 NSData 时填写。
+ * @deprecated v8.6 版本开始不推荐使用，建议使用 startScreenCaptureInApp:encParam: 接口替代之。
+ */
+- (void)startScreenCaptureInApp:(TRTCVideoEncParam *)encParams __attribute__((deprecated("use startScreenCaptureInApp:encParam: instead")));
+
+/**
+ * 开始全系统的屏幕分享（iOS）
*
- * 参考文档：[自定义采集和渲染](https://cloud.tencent.com/document/product/647/34066)。
+ * @deprecated v8.6 版本开始不推荐使用，建议使用 startScreenCaptureByReplaykit:encParam:appGroup:接口替代之。
+ */
+- (void)startScreenCaptureByReplaykit:(TRTCVideoEncParam *)encParams appGroup:(NSString *)appGroup __attribute__((deprecated("use startScreenCaptureByReplaykit:encParam:appGroup: instead")));
+
+/**
+ * 暂停/恢复发布本地的视频流
*
- * @param frame 视频数据，支持 PixelBuffer NV12，BGRA 以及 I420 格式数据。
- * @note - SDK 内部有帧率控制逻辑，目标帧率以您在 setVideoEncoderParam 中设置的为准，太快会自动丢帧，太慢则会自动补帧。
- * @note - 可以设置 frame 中的 timestamp 为 0，相当于让 SDK 自己设置时间戳，但请“均匀”地控制 sendCustomVideoData 的调用间隔，否则会导致视频帧率不稳定。
+ * @deprecated v8.9 版本开始不推荐使用，建议使用 muteLocalVideo(streamType, mute) 接口替代之。
+ */
+- (void)muteLocalVideo:(BOOL)mute __attribute__((deprecated("use muteLocalVideo:streamType:mute: instead")));
+
+/**
+ * 暂停 / 恢复订阅远端用户的视频流
*
+ * @deprecated v8.9 版本开始不推荐使用，建议使用 muteRemoteVideoStream(userId, streamType, mute) 接口替代之。
*/
-- (void)sendCustomVideoData:(TRTCVideoFrame *)frame __attribute__((deprecated("use sendCustomVideoData:frame: instead")));
+- (void)muteRemoteVideoStream:(NSString *)userId mute:(BOOL)mute __attribute__((deprecated("use muteRemoteVideoStream:userid,streamType:mute: instead")));
/// @}
-
@end
-///@}
+/// @}
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TRTCCloudDef.h b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TRTCCloudDef.h
index a2ab1f4..095985c 100644
--- a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TRTCCloudDef.h
+++ b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TRTCCloudDef.h
@@ -1,11 +1,31 @@
-/*
+/**
* Module: TRTC 关键类型定义
- *
* Function: 分辨率、质量等级等枚举和常量值的定义
- *
*/
-
+/// @defgroup TRTCCloudDef_ios 关键类型定义
+/// 腾讯云实时音视频的关键类型定义
+/// @{
#import <Foundation/Foundation.h>
+
+/////////////////////////////////////////////////////////////////////////////////
+//
+// 渲染控件
+//
+/////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * [VIEW] 用于渲染视频画面的渲染控件
+ *
+ * TRTC 中有很多需要操控视频画面的接口，这些接口都需要您指定视频渲染控件。
+ * - 在 iOS 系统中，您可以直接使用 UIView 作为视频渲染控件，SDK 会在您提供的 UIView 上绘制视频画面。
+ * - 在 Mac 系统中，您可以直接使用 NSView 作为视频渲染控件，SDK 会在您提供的 NSView 上绘制视频画面。
+ * 示例代码如下：
+ * <pre>
+ * UIView *videoView = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 360, 640)];
+ * [self.view addSubview:videoView];
+ * [trtcCloud startLocalPreview:YES view:_localView];
+ * </pre>
+ */
#if TARGET_OS_IPHONE || TARGET_OS_SIMULATOR
#import <UIKit/UIKit.h>
typedef UIView TXView;
@@ -19,276 +39,427 @@ typedef NSEdgeInsets TXEdgeInsets;
#endif
#import "TXDeviceManager.h"
-///@defgroup TRTCCloudDef_ios 关键类型定义
-///腾讯云视频通话功能的关键类型定义
-///@{
-
/////////////////////////////////////////////////////////////////////////////////
//
-// 【（一）视频相关枚举值定义】
+// 视频相关枚举值定义
//
/////////////////////////////////////////////////////////////////////////////////
/**
* 1.1 视频分辨率
*
- * 此处仅定义横屏分辨率，如需使用竖屏分辨率（例如360 × 640），需要同时指定 TRTCVideoResolutionMode 为 Portrait。
+ * 此处仅定义横屏分辨率（如 640 × 360），如需使用竖屏分辨率（如360 × 640），需要同时指定 TRTCVideoResolutionMode 为 Portrait。
*/
typedef NS_ENUM(NSInteger, TRTCVideoResolution) {
- // 宽高比1:1
- TRTCVideoResolution_120_120 = 1, ///< [C] 建议码率 VideoCall:80kbps LIVE:120kbps
- TRTCVideoResolution_160_160 = 3, ///< [C] 建议码率 VideoCall:100kbps LIVE:150kbps
- TRTCVideoResolution_270_270 = 5, ///< [C] 建议码率 VideoCall:200kbps LIVE:120kbps
- TRTCVideoResolution_480_480 = 7, ///< [C] 建议码率 VideoCall:350kbps LIVE:120kbps
-
- // 宽高比4:3
- TRTCVideoResolution_160_120 = 50, ///< [C] 建议码率 VideoCall:100kbps LIVE:150kbps
- TRTCVideoResolution_240_180 = 52, ///< [C] 建议码率 VideoCall:150kbps LIVE:225kbps
- TRTCVideoResolution_280_210 = 54, ///< [C] 建议码率 VideoCall:200kbps LIVE:300kbps
- TRTCVideoResolution_320_240 = 56, ///< [C] 建议码率 VideoCall:250kbps LIVE:375kbps
- TRTCVideoResolution_400_300 = 58, ///< [C] 建议码率 VideoCall:300kbps LIVE:450kbps
- TRTCVideoResolution_480_360 = 60, ///< [C] 建议码率 VideoCall:400kbps LIVE:600kbps
- TRTCVideoResolution_640_480 = 62, ///< [C] 建议码率 VideoCall:600kbps LIVE:900kbps
- TRTCVideoResolution_960_720 = 64, ///< [C] 建议码率 VideoCall:1000kbps LIVE:1500kbps
-
- // 宽高比16:9
- TRTCVideoResolution_160_90 = 100, ///< [C] 建议码率 VideoCall:150kbps LIVE:250kbps
- TRTCVideoResolution_256_144 = 102, ///< [C] 建议码率 VideoCall:200kbps LIVE:300kbps
- TRTCVideoResolution_320_180 = 104, ///< [C] 建议码率 VideoCall:250kbps LIVE:400kbps
- TRTCVideoResolution_480_270 = 106, ///< [C] 建议码率 VideoCall:350kbps LIVE:550kbps
- TRTCVideoResolution_640_360 = 108, ///< [C] 建议码率 VideoCall:550kbps LIVE:900kbps
- TRTCVideoResolution_960_540 = 110, ///< [C] 建议码率 VideoCall:850kbps LIVE:1300kbps
- TRTCVideoResolution_1280_720 = 112, ///< [C] 建议码率 VideoCall:1200kbps LIVE:1800kbps
- TRTCVideoResolution_1920_1080 = 114, ///< [S] 建议码率 VideoCall:2000kbps LIVE:3000kbps
+
+ ///宽高比 1:1；分辨率 120x120；建议码率（VideoCall）80kbps; 建议码率（LIVE）120kbps。
+ TRTCVideoResolution_120_120 = 1,
+
+ ///宽高比 1:1 分辨率 160x160；建议码率（VideoCall）100kbps; 建议码率（LIVE）150kbps。
+ TRTCVideoResolution_160_160 = 3,
+
+ ///宽高比 1:1；分辨率 270x270；建议码率（VideoCall）200kbps; 建议码率（LIVE）300kbps。
+ TRTCVideoResolution_270_270 = 5,
+
+ ///宽高比 1:1；分辨率 480x480；建议码率（VideoCall）350kbps; 建议码率（LIVE）500kbps。
+ TRTCVideoResolution_480_480 = 7,
+
+ ///宽高比4:3；分辨率 160x120；建议码率（VideoCall）100kbps; 建议码率（LIVE）150kbps。
+ TRTCVideoResolution_160_120 = 50,
+
+ ///宽高比 4:3；分辨率 240x180；建议码率（VideoCall）150kbps; 建议码率（LIVE）250kbps。
+ TRTCVideoResolution_240_180 = 52,
+
+ ///宽高比 4:3；分辨率 280x210；建议码率（VideoCall）200kbps; 建议码率（LIVE）300kbps。
+ TRTCVideoResolution_280_210 = 54,
+
+ ///宽高比 4:3；分辨率 320x240；建议码率（VideoCall）250kbps; 建议码率（LIVE）375kbps。
+ TRTCVideoResolution_320_240 = 56,
+
+ ///宽高比 4:3；分辨率 400x300；建议码率（VideoCall）300kbps; 建议码率（LIVE）450kbps。
+ TRTCVideoResolution_400_300 = 58,
+
+ ///宽高比 4:3；分辨率 480x360；建议码率（VideoCall）400kbps; 建议码率（LIVE）600kbps。
+ TRTCVideoResolution_480_360 = 60,
+
+ ///宽高比 4:3；分辨率 640x480；建议码率（VideoCall）600kbps; 建议码率（LIVE）900kbps。
+ TRTCVideoResolution_640_480 = 62,
+
+ ///宽高比 4:3；分辨率 960x720；建议码率（VideoCall）1000kbps; 建议码率（LIVE）1500kbps。
+ TRTCVideoResolution_960_720 = 64,
+
+ ///宽高比 16:9；分辨率 160x90；建议码率（VideoCall）150kbps; 建议码率（LIVE）250kbps。
+ TRTCVideoResolution_160_90 = 100,
+
+ ///宽高比 16:9；分辨率 256x144；建议码率（VideoCall）200kbps; 建议码率（LIVE）300kbps。
+ TRTCVideoResolution_256_144 = 102,
+
+ ///宽高比 16:9；分辨率 320x180；建议码率（VideoCall）250kbps; 建议码率（LIVE）400kbps。
+ TRTCVideoResolution_320_180 = 104,
+
+ ///宽高比 16:9；分辨率 480x270；建议码率（VideoCall）350kbps; 建议码率（LIVE）550kbps。
+ TRTCVideoResolution_480_270 = 106,
+
+ ///宽高比 16:9；分辨率 640x360；建议码率（VideoCall）500kbps; 建议码率（LIVE）900kbps。
+ TRTCVideoResolution_640_360 = 108,
+
+ ///宽高比 16:9；分辨率 960x540；建议码率（VideoCall）850kbps; 建议码率（LIVE）1300kbps。
+ TRTCVideoResolution_960_540 = 110,
+
+ ///宽高比 16:9；分辨率 1280x720；建议码率（VideoCall）1200kbps; 建议码率（LIVE）1800kbps。
+ TRTCVideoResolution_1280_720 = 112,
+
+ ///宽高比 16:9；分辨率 1920x1080；建议码率（VideoCall）2000kbps; 建议码率（LIVE）3000kbps。
+ TRTCVideoResolution_1920_1080 = 114,
+
};
/**
* 1.2 视频宽高比模式
*
- * - 横屏分辨率：TRTCVideoResolution_640_360 + TRTCVideoResolutionModeLandscape = 640 × 360
- * - 竖屏分辨率：TRTCVideoResolution_640_360 + TRTCVideoResolutionModePortrait = 360 × 640
+ * TRTCVideoResolution 中仅定义了横屏分辨率（如 640 × 360），如需使用竖屏分辨率（如360 × 640），需要同时指定 TRTCVideoResolutionMode 为 Portrait。
*/
typedef NS_ENUM(NSInteger, TRTCVideoResolutionMode) {
- TRTCVideoResolutionModeLandscape = 0, ///< 横屏分辨率
- TRTCVideoResolutionModePortrait = 1, ///< 竖屏分辨率
-};
+ ///横屏分辨率，例如：TRTCVideoResolution_640_360 + TRTCVideoResolutionModeLandscape = 640 × 360。
+ TRTCVideoResolutionModeLandscape = 0,
+
+ ///竖屏分辨率，例如：TRTCVideoResolution_640_360 + TRTCVideoResolutionModePortrait = 360 × 640。
+ TRTCVideoResolutionModePortrait = 1,
+
+};
/**
* 1.3 视频流类型
*
- * TRTC 内部有三种不同的音视频流，分别是：
- * - 主画面：最常用的一条线路，一般用来传输摄像头的视频数据。
- * - 小画面：跟主画面的内容相同，但是分辨率和码率更低。
- * - 辅流画面：一般用于屏幕分享，以及远程播片（例如老师放一段视频给学生）。
- *
- * @note - 如果主播的上行网络和性能比较好，则可以同时送出大小两路画面。
- * @note - SDK 不支持单独开启小画面，小画面必须依附于主画面而存在。
+ * TRTC 内部有三种不同的视频流，分别是：
+ * - 高清大画面：一般用来传输摄像头的视频数据。
+ * - 低清小画面：小画面和大画面的内容相互，但是分辨率和码率都比大画面低，因此清晰度也更低。
+ * - 辅流画面：一般用于屏幕分享，同一时间在同一个房间中只允许一个用户发布辅流视频，其他用户必须要等该用户关闭之后才能发布自己的辅流。
+ * @note 不支持单独开启低清小画面，小画面必须依附于大画面而存在，SDK 会自动设定低清小画面的分辨率和码率。
*/
-
typedef NS_ENUM(NSInteger, TRTCVideoStreamType) {
- TRTCVideoStreamTypeBig = 0, ///< 主画面视频流
- TRTCVideoStreamTypeSmall = 1, ///< 小画面视频流
- TRTCVideoStreamTypeSub = 2, ///< 辅流（屏幕分享）
+
+ ///高清大画面，一般用来传输摄像头的视频数据。
+ TRTCVideoStreamTypeBig = 0,
+
+ ///低清小画面：小画面和大画面的内容相互，但是分辨率和码率都比大画面低，因此清晰度也更低。
+ TRTCVideoStreamTypeSmall = 1,
+
+ ///辅流画面：一般用于屏幕分享，同一时间在同一个房间中只允许一个用户发布辅流视频，其他用户必须要等该用户关闭之后才能发布自己的辅流。
+ TRTCVideoStreamTypeSub = 2,
};
/**
* 1.4 视频画面填充模式
*
- * 如果画面的显示分辨率不等于画面的原始分辨率，就需要您设置画面的填充模式:
- * - TRTCVideoFillMode_Fill，图像铺满屏幕，超出显示视窗的视频部分将被裁剪，画面显示可能不完整。
- * - TRTCVideoFillMode_Fit，图像长边填满屏幕，短边区域会被填充黑色，画面的内容完整。
+ * 如果视频显示区域的宽高比不等于视频内容的宽高比时，就需要您指定画面的填充模式:
*/
typedef NS_ENUM(NSInteger, TRTCVideoFillMode) {
- TRTCVideoFillMode_Fill = 0, ///< 图像铺满屏幕，超出显示视窗的视频部分将被裁剪
- TRTCVideoFillMode_Fit = 1, ///< 图像长边填满屏幕，短边区域会被填充黑色
+
+ ///填充模式：即将画面内容居中等比缩放以充满整个显示区域，超出显示区域的部分将会被裁剪掉，此模式下画面可能不完整。
+ TRTCVideoFillMode_Fill = 0,
+
+ ///适应模式：即按画面长边进行缩放以适应显示区域，短边部分会被填充为黑色，此模式下图像完整但可能留有黑边。
+ TRTCVideoFillMode_Fit = 1,
+
};
/**
* 1.5 视频画面旋转方向
*
- * TRTC SDK 提供了对本地和远程画面的旋转角度设置 API，下列的旋转角度都是指顺时针方向的。
+ * TRTC 提供了对本地和远程画面的旋转角度设置 API，下列的旋转角度都是指顺时针方向的。
*/
typedef NS_ENUM(NSInteger, TRTCVideoRotation) {
- TRTCVideoRotation_0 = 0, ///< 不旋转
- TRTCVideoRotation_90 = 1, ///< 顺时针旋转90度
- TRTCVideoRotation_180 = 2, ///< 顺时针旋转180度
- TRTCVideoRotation_270 = 3, ///< 顺时针旋转270度
+
+ ///不旋转
+ TRTCVideoRotation_0 = 0,
+
+ ///顺时针旋转90度
+ TRTCVideoRotation_90 = 1,
+
+ ///顺时针旋转180度
+ TRTCVideoRotation_180 = 2,
+
+ ///顺时针旋转270度
+ TRTCVideoRotation_270 = 3,
+
};
/**
* 1.6 美颜（磨皮）算法
*
- * TRTC SDK 内置多种不同的磨皮算法，您可以选择最适合您产品定位的方案。
+ * TRTC 内置多种不同的磨皮算法，您可以选择最适合您产品定位的方案。
*/
typedef NS_ENUM(NSInteger, TRTCBeautyStyle) {
- TRTCBeautyStyleSmooth = 0, ///< 光滑，适用于美女秀场，效果比较明显。
- TRTCBeautyStyleNature = 1, ///< 自然，磨皮算法更多地保留了面部细节，主观感受上会更加自然。
- TRTCBeautyStylePitu = 2, ///< 由上海优图实验室提供的美颜算法，磨皮效果介于光滑和自然之间，比光滑保留更多皮肤细节，比自然磨皮程度更高。
+
+ ///光滑，算法比较激进，磨皮效果比较明显，适用于秀场直播。
+ TRTCBeautyStyleSmooth = 0,
+
+ ///自然，算法更多地保留了面部细节，磨皮效果更加自然，适用于绝大多数直播场景。
+ TRTCBeautyStyleNature = 1,
+
+ ///优图，由优图实验室提供，磨皮效果介于光滑和自然之间，比光滑保留更多皮肤细节，比自然磨皮程度更高。
+ TRTCBeautyStylePitu = 2,
+
};
/**
* 1.7 视频像素格式
*
- * TRTC SDK 提供针对视频的自定义采集和自定义渲染功能，在自定义采集功能中，您可以用下列枚举值描述您采集的视频像素格式。
- * 在自定义渲染功能中，您可以指定您期望 SDK 回调的视频像素格式。
+ * TRTC 提供针对视频的自定义采集和自定义渲染功能：
+ * - 在自定义采集功能中，您可以用下列枚举值描述您采集的视频像素格式。
+ * - 在自定义渲染功能中，您可以指定您期望 SDK 回调出的视频像素格式。
*/
typedef NS_ENUM(NSInteger, TRTCVideoPixelFormat) {
- TRTCVideoPixelFormat_Unknown = 0, ///< 未知
- TRTCVideoPixelFormat_I420 = 1, ///< YUV420P I420
- TRTCVideoPixelFormat_NV12 = 5, ///< YUV420SP NV12
- TRTCVideoPixelFormat_32BGRA = 6, ///< BGRA8888
- TRTCVideoPixelFormat_Texture_2D = 7, ///< Texture
+
+ ///未定义的格式
+ TRTCVideoPixelFormat_Unknown = 0,
+
+ /// YUV420P(I420) 格式
+ TRTCVideoPixelFormat_I420 = 1,
+
+ /// OpenGL 2D 纹理格式
+ TRTCVideoPixelFormat_Texture_2D = 7,
+
+ /// BGRA 格式
+ TRTCVideoPixelFormat_32BGRA = 6,
+
+ /// YUV420SP（NV12）格式
+ TRTCVideoPixelFormat_NV12 = 5,
+
};
/**
- * 1.8 视频数据包装格式
+ * 1.8 视频数据传递方式
*
- * 在自定义采集和自定义渲染功能，您需要用到下列枚举值来指定您希望以什么类型的容器来包装视频数据。
- * - PixelBuffer：直接使用效率最高，iOS 系统提供了众多 API 获取或处理 PixelBuffer。
- * - NSData：仅用于自定义渲染，SDK 帮您做了一次 PixelBuffer 到 NSData 的内存拷贝工作，会有一定的性能消耗。
+ * 在自定义采集和自定义渲染功能，您需要用到下列枚举值来指定您希望以什么方式传递视频数据：
+ * - 方案一：使用内存 Buffer 传递视频数据，该方案在 iOS 效率尚可，但在 Android 系统上效率较差，Windows 暂时仅支持内存 Buffer 的传递方式。
+ * - 方案二：使用 Texture 纹理传递视频数据，该方案在 iOS 和 Android 系统下均有较高的效率，Windows 暂不支持，需要您有一定的 OpenGL 编程基础。
*/
typedef NS_ENUM(NSInteger, TRTCVideoBufferType) {
- TRTCVideoBufferType_Unknown = 0, ///< 未知
- TRTCVideoBufferType_PixelBuffer = 1, ///< 直接使用效率最高，iOS 系统提供了众多 API 获取或处理 PixelBuffer。
- TRTCVideoBufferType_NSData = 2, ///< 仅用于自定义渲染，SDK 帮您做了一次 PixelBuffer 到 NSData 的内存拷贝工作，会有一定的性能消耗。
- TRTCVideoBufferType_Texture = 3, ///< 用于自定义渲染的 texture
+
+ ///未定义的传递方式
+ TRTCVideoBufferType_Unknown = 0,
+
+ ///使用内存 Buffer 传递视频数据，iOS: PixelBuffer；Android: 用于 JNI 层的 Direct Buffer；Win: 内存数据块。
+ TRTCVideoBufferType_PixelBuffer = 1,
+
+ ///使用内存 Buffer 传递视频数据，iOS: 经过一次额外整理后更加紧凑的 NSData 类型的内存块；Android: 用于 JAVA 层的 byte[]。
+ ///该传递的方式的性能是几种方案中效率较差的一种。
+ TRTCVideoBufferType_NSData = 2,
+
+ ///使用 Texture 纹理传递视频数据
+ TRTCVideoBufferType_Texture = 3,
+
};
/**
- * 1.9 本地视频预览镜像类型
+ * 1.9 视频的镜像类型
*
- * iOS 的本地画面提供下列设置模式
+ * 视频的镜像是指对视频内容进行左右翻转，尤其是对本地的摄像头预览视频，开启镜像后能给主播带来熟悉的“照镜子”体验。
*/
typedef NS_ENUM(NSUInteger, TRTCVideoMirrorType) {
- TRTCVideoMirrorTypeAuto = 0, ///< 前置摄像头镜像，后置摄像头不镜像
- TRTCVideoMirrorTypeEnable = 1, ///< 前后置摄像头画面均镜像
- TRTCVideoMirrorTypeDisable = 2, ///< 前后置摄像头画面均不镜像
-};
-/**
- * 1.10 视频截图来源
- */
-typedef NS_ENUM(NSUInteger, TRTCSnapshotSourceType) {
- TRTCSnapshotSourceTypeStream = 0, ///< 从视频流上截取视频画面
- TRTCSnapshotSourceTypeView = 1, ///< 从渲染 View 上截取视频画面
+ ///自动模式：如果正使用前置摄像头则开启镜像，如果是后置摄像头则不开启镜像（仅适用于移动设备）。
+ TRTCVideoMirrorTypeAuto = 0,
+
+ ///强制开启镜像，不论当前使用的是前置摄像头还是后置摄像头。
+ TRTCVideoMirrorTypeEnable = 1,
+
+ ///强制关闭镜像，不论当前使用的是前置摄像头还是后置摄像头。
+ TRTCVideoMirrorTypeDisable = 2,
+
};
+/// Old version of TRTCVideoMirrorType, reserved for compatibility with older interface.
+typedef NS_ENUM(NSUInteger, TRTCLocalVideoMirrorType) {
+ TRTCLocalVideoMirrorType_Auto = TRTCVideoMirrorTypeAuto,
+ TRTCLocalVideoMirrorType_Enable = TRTCVideoMirrorTypeEnable,
+ TRTCLocalVideoMirrorType_Disable = TRTCVideoMirrorTypeDisable,
+} __attribute__((deprecated("use TRTCVideoMirrorType instead")));
+
/**
- * 1.12 视频渲染设置
+ * 1.10 本地视频截图的数据源
+ *
+ * SDK 支持从如下两种数据源中截取图片并保存成本地文件：
+ * - 视频流：从视频流中截取原生的视频内容，截取的内容不受渲染控件的显示控制。
+ * - 渲染层：从渲染控件中截取显示的视频内容，可以做到用户所见即所得的效果，但如果显示区域过小，截取出的图片也会很小。
*/
-@interface TRTCRenderParams : NSObject
+typedef NS_ENUM(NSUInteger, TRTCSnapshotSourceType) {
-/// 【字段含义】画面朝向
-/// 【推荐取值】支持90、180以及270旋转角度，默认值：TRTCVideoRotation_0
-@property (nonatomic) TRTCVideoRotation rotation;
+ ///从视频流中截取原生的视频内容，截取的内容不受渲染控件的显示控制。
+ TRTCSnapshotSourceTypeStream = 0,
-/// 【字段含义】画面填充模式
-/// 【推荐取值】填充（画面可能会被拉伸裁剪）或适应（画面可能会有黑边），默认值：TRTCVideoFillMode_Fill
-@property (nonatomic) TRTCVideoFillMode fillMode;
+ ///从渲染控件中截取显示的视频内容，可以做到用户所见即所得的效果，但如果显示区域过小，截取出的图片也会很小。
+ TRTCSnapshotSourceTypeView = 1,
-/// 【字段含义】画面镜像模式
-/// 【推荐取值】默认值：TRTCVideoMirrorType_Auto
-@property (nonatomic) TRTCVideoMirrorType mirrorType;
+};
-@end
/////////////////////////////////////////////////////////////////////////////////
//
-// 【（二）网络相关枚举值定义】
-//
+// 网络相关枚举值定义
+//
/////////////////////////////////////////////////////////////////////////////////
/**
* 2.1 应用场景
*
- * TRTC 可用于视频会议和在线直播等多种应用场景，针对不同的应用场景，TRTC SDK 的内部会进行不同的优化配置：
- * - TRTCAppSceneVideoCall ：视频通话场景，适合[1对1视频通话]、[300人视频会议]、[在线问诊]、[视频聊天]、[远程面试]等。
- * - TRTCAppSceneLIVE ：视频互动直播，适合[视频低延时直播]、[十万人互动课堂]、[视频直播 PK]、[视频相亲房]、[互动课堂]、[远程培训]、[超大型会议]等。
- * - TRTCAppSceneAudioCall ：语音通话场景，适合[1对1语音通话]、[300人语音会议]、[语音聊天]、[语音会议]、[在线狼人杀]等。
- * - TRTCAppSceneVoiceChatRoom：语音互动直播，适合：[语音低延时直播]、[语音直播连麦]、[语聊房]、[K 歌房]、[FM 电台]等。
+ * TRTC 针对常见的音视频应用场景都进行了定向优化，以满足各种垂直场景下的差异化要求，主要场景可以分为如下两类：
+ * - 直播（LIVE）场景：包括 LIVE 和 VoiceChatRoom，前者是音频+视频，后者是纯音频。
+ * 直播场景下，用户被分成“主播”和“观众”两种角色，单个房间中同时最多支持10万人在线，适合于观众人数众多的直播场景。
+ * - 实时（RTC）场景：包括 VideoCall 和 AudioCall，前者是音频+视频，后者是纯音频。
+ * 实时场景下，用户没有角色的差异，但单个房间中同时最多支持 300 人在线，适合于小范围实时通信的场景。
*/
typedef NS_ENUM(NSInteger, TRTCAppScene) {
- /// 视频通话场景，支持720P、1080P高清画质，单个房间最多支持300人同时在线，最高支持50人同时发言。<br>
- /// 适合：[1对1视频通话]、[300人视频会议]、[在线问诊]、[视频聊天]、[远程面试]等。
- TRTCAppSceneVideoCall = 0,
-
- /// 视频互动直播，支持平滑上下麦，切换过程无需等待，主播延时小于300ms；支持十万级别观众同时播放，播放延时低至1000ms。<br>
- /// 适合：[视频低延时直播]、[十万人互动课堂]、[视频直播 PK]、[视频相亲房]、[互动课堂]、[远程培训]、[超大型会议]等。<br>
- /// 注意：此场景下，您必须通过 TRTCParams 中的 role 字段指定当前用户的角色。
- TRTCAppSceneLIVE = 1,
-
- /// 语音通话场景，支持 48kHz，支持双声道。单个房间最多支持300人同时在线，最高支持50人同时发言。<br>
- /// 适合：[1对1语音通话]、[300人语音会议]、[语音聊天]、[语音会议]、[在线狼人杀]等。
- TRTCAppSceneAudioCall = 2,
-
- /// 语音互动直播，支持平滑上下麦，切换过程无需等待，主播延时小于300ms；支持十万级别观众同时播放，播放延时低至1000ms。<br>
- /// 适合：[语音低延时直播]、[语音直播连麦]、[语聊房]、[K 歌房]、[FM 电台]等。<br>
- /// 注意：此场景下，您必须通过 TRTCParams 中的 role 字段指定当前用户的角色。
- TRTCAppSceneVoiceChatRoom = 3,
+
+ ///视频通话场景，支持720P、1080P高清画质，单个房间最多支持300人同时在线，最高支持50人同时发言。
+ ///适用于[1对1视频通话]、[300人视频会议]、[在线问诊]、[教育小班课]、[远程面试]等业务场景。
+ TRTCAppSceneVideoCall = 0,
+
+ ///视频互动直播，支持平滑上下麦，切换过程无需等待，主播延时小于300ms；支持十万级别观众同时播放，播放延时低至1000ms。
+ ///适用于[低延时互动直播]、[大班课]、[主播PK]、[视频相亲]、[在线互动课堂]、[远程培训]、[超大型会议]等业务场景。
+ ///@note 此场景下，您必须通过 TRTCParams 中的 role 字段指定当前用户的角色。
+ TRTCAppSceneLIVE = 1,
+
+ ///语音通话场景，默认采用 SPEECH 音质，单个房间最多支持300人同时在线，最高支持50人同时发言。
+ ///适用于[1对1语音通话]、[300人语音会议]、[语音聊天]、[语音会议]、[在线狼人杀]等业务场景。
+ TRTCAppSceneAudioCall = 2,
+
+ ///语音互动直播，支持平滑上下麦，切换过程无需等待，主播延时小于300ms；支持十万级别观众同时播放，播放延时低至1000ms。
+ ///适用于[语音俱乐部]、[在线K歌房]、[音乐直播间]、[FM电台]等业务场景。
+ ///@note 此场景下，您必须通过 TRTCParams 中的 role 字段指定当前用户的角色。
+ TRTCAppSceneVoiceChatRoom = 3,
+
};
/**
- * 2.2 角色，仅适用于直播场景（TRTCAppSceneLIVE 和 TRTCAppSceneVoiceChatRoom）
+ * 2.2 角色
*
- * 在直播场景中，多数用户仅为观众，个别用户是主播，这种角色区分有利于 TRTC 进行更好的定向优化。
- *
- * - Anchor：主播，可以上行视频和音频，一个房间里最多支持50个主播同时上行音视频。
- * - Audience：观众，只能观看，不能上行视频和音频，一个房间里的观众人数没有上限。
+ * 仅适用于直播类场景（即 TRTCAppSceneLIVE 和 TRTCAppSceneVoiceChatRoom），把用户区分成两种不同的身份：
+ * - 主播：可以随时发布自己的音视频流，但人数有限制，同一个房间中最多只允许 50 个主播同时发布自己的音视频流。
+ * - 观众：只能观看其他用户的音视频流，要发布音视频流，需要先通过 {@link switchRole} 切换成主播，同一个房间中最多能容纳10万观众。
*/
typedef NS_ENUM(NSInteger, TRTCRoleType) {
- TRTCRoleAnchor = 20, ///< 主播
- TRTCRoleAudience = 21, ///< 观众
+
+ ///主播：可以随时发布自己的音视频流，但人数有限制，同一个房间中最多只允许 50 个主播同时发布自己的音视频流。
+ TRTCRoleAnchor = 20,
+
+ ///观众：只能观看其他用户的音视频流，要发布音视频流，需要先通过 {@link switchRole} 切换成主播，同一个房间中最多能容纳10万观众。
+ TRTCRoleAudience = 21,
+
};
/**
- * 2.3 流控模式
- *
- * TRTC SDK 内部需要时刻根据网络情况调整内部的编解码器和网络模块，以便能够对网络的变化做出反应。
- * 为了支持快速算法升级，SDK 内部设置了两种不同的流控模式：
- * - ModeServer：云端控制，默认模式，推荐选择。
- * - ModeClient：本地控制，用于 SDK 开发内部调试，客户请勿使用。
- *
- * @note 推荐您使用云端控制，这样每当我们升级 Qos 算法时，您无需升级 SDK 即可体验更好的效果。
+ * 2.3 流控模式（已废弃）
*/
-typedef NS_ENUM(NSInteger, TRTCQosControlMode)
-{
- TRTCQosControlModeClient, ///< 客户端控制（用于 SDK 开发内部调试，客户请勿使用）
- TRTCQosControlModeServer, ///< 云端控制 （默认）
+typedef NS_ENUM(NSInteger, TRTCQosControlMode) {
+
+ ///本地控制，用于 SDK 开发内部调试，客户请勿使用。
+ TRTCQosControlModeClient = 0,
+
+ ///云端控制，默认模式，推荐选择。
+ TRTCQosControlModeServer = 1,
+
};
/**
* 2.4 画质偏好
*
- * 指当 TRTC SDK 在遇到弱网络环境时，您期望“保清晰”或“保流畅”，两种模式均会优先保障声音数据的传输。
- *
- * - Smooth：弱网下优先流畅性，当用户网络较差的时候画面也会比较模糊。
- * - Clear：默认值，弱网下优先清晰度，当用户网络较差的时候会出现卡顿，但画面清晰度不会大幅缩水。
+ * TRTC 在弱网络环境下有两种调控模式：“优先保证画面清晰”或“优先保证画面流畅”，两种模式均会优先保障声音数据的传输。
*/
-typedef NS_ENUM(NSInteger, TRTCVideoQosPreference)
-{
- TRTCVideoQosPreferenceSmooth = 1, ///< 弱网下保流畅
- TRTCVideoQosPreferenceClear = 2, ///< 弱网下保清晰，默认值
+typedef NS_ENUM(NSInteger, TRTCVideoQosPreference) {
+
+ ///流畅优先：即当前网络不足以传输既清晰又流畅的画面时，优先保证画面的流畅性，代价就是画面会比较模糊且伴随有较多的马赛克。
+ TRTCVideoQosPreferenceSmooth = 1,
+
+ ///清晰优先（默认值）：即当前网络不足以传输既清晰又流畅的画面时，优先保证画面的清晰度，代价就是画面会比较卡顿。
+ TRTCVideoQosPreferenceClear = 2,
+
};
/**
* 2.5 网络质量
*
- * TRTC SDK 对网络质量定义了六种不同的级别，Excellent 表示最好，Down 表示不可用。
+ * TRTC 会每隔两秒对当前的网络质量进行评估，评估结果为六个等级：Excellent 表示最好，Down 表示最差。
*/
typedef NS_ENUM(NSInteger, TRTCQuality) {
- TRTCQuality_Unknown = 0, ///< 未定义
- TRTCQuality_Excellent = 1, ///< 最好
- TRTCQuality_Good = 2, ///< 好
- TRTCQuality_Poor = 3, ///< 一般
- TRTCQuality_Bad = 4, ///< 差
- TRTCQuality_Vbad = 5, ///< 很差
- TRTCQuality_Down = 6, ///< 不可用
+
+ ///未定义
+ TRTCQuality_Unknown = 0,
+
+ ///当前网络非常好
+ TRTCQuality_Excellent = 1,
+
+ ///当前网络比较好
+ TRTCQuality_Good = 2,
+
+ ///当前网络一般
+ TRTCQuality_Poor = 3,
+
+ ///当前网络较差
+ TRTCQuality_Bad = 4,
+
+ ///当前网络很差
+ TRTCQuality_Vbad = 5,
+
+ ///当前网络不满足 TRTC 的最低要求
+ TRTCQuality_Down = 6,
+
+};
+
+/**
+ * 2.6 视频状态类型
+ *
+ * 该枚举类型用于视频状态变化回调接口{@link onRemoteVideoStatusUpdated}，用于指定当前的视频状态。
+ */
+typedef NS_ENUM(NSUInteger, TRTCAVStatusType) {
+
+ ///停止播放
+ TRTCAVStatusStopped = 0,
+
+ ///正在播放
+ TRTCAVStatusPlaying = 1,
+
+ ///正在加载
+ TRTCAVStatusLoading = 2,
+
+};
+
+/**
+ * 2.7 视频状态变化原因类型
+ *
+ * 该枚举类型用于视频状态变化回调接口{@link onRemoteVideoStatusUpdated}，用于指定当前的视频状态原因。
+ */
+typedef NS_ENUM(NSUInteger, TRTCAVStatusChangeReason) {
+
+ ///缺省值
+ TRTCAVStatusChangeReasonInternal = 0,
+
+ ///网络缓冲
+ TRTCAVStatusChangeReasonBufferingBegin = 1,
+
+ ///结束缓冲
+ TRTCAVStatusChangeReasonBufferingEnd = 2,
+
+ ///本地启动视频流播放
+ TRTCAVStatusChangeReasonLocalStarted = 3,
+
+ ///本地停止视频流播放
+ TRTCAVStatusChangeReasonLocalStopped = 4,
+
+ ///远端视频流开始（或继续）
+ TRTCAVStatusChangeReasonRemoteStarted = 5,
+
+ ///远端视频流停止（或中断
+ TRTCAVStatusChangeReasonRemoteStopped = 6,
+
};
/////////////////////////////////////////////////////////////////////////////////
//
-// 【（三）声音相关枚举值定义】
+// 音频相关枚举值定义
//
/////////////////////////////////////////////////////////////////////////////////
@@ -298,115 +469,171 @@ typedef NS_ENUM(NSInteger, TRTCQuality) {
* 音频采样率用来衡量声音的保真程度，采样率越高保真程度越好，如果您的应用场景有音乐的存在，推荐使用 TRTCAudioSampleRate48000。
*/
typedef NS_ENUM(NSInteger, TRTCAudioSampleRate) {
- TRTCAudioSampleRate16000 = 16000, ///< 16k采样率
- TRTCAudioSampleRate32000 = 32000, ///< 32采样率
- TRTCAudioSampleRate44100 = 44100, ///< 44.1k采样率
- TRTCAudioSampleRate48000 = 48000, ///< 48k采样率
+
+ /// 16k采样率
+ TRTCAudioSampleRate16000 = 16000,
+
+ /// 32k采样率
+ TRTCAudioSampleRate32000 = 32000,
+
+ /// 44.1k采样率
+ TRTCAudioSampleRate44100 = 44100,
+
+ /// 48k采样率
+ TRTCAudioSampleRate48000 = 48000,
+
};
/**
* 3.2 声音音质
*
- * 音频音质用来衡量声音的保真程度，TRTCAudioQualitySpeech 适用于通话场景，TRTCAudioQualityMusic 适用于高音质音乐场景。
+ * TRTC 提供了三种精心校调好的模式，用来满足各种垂直场景下对音质的差异化追求：
+ * - 人声模式（Speech）：适用于以人声沟通为主的应用场景，该模式下音频传输的抗性较强，TRTC 会通过各种人声处理技术保障在弱网络环境下的流畅度最佳。
+ * - 音乐模式（Music）：适用于对声乐要求很苛刻的场景，该模式下音频传输的数据量很大，TRTC 会通过各项技术确保音乐信号在各频段均能获得高保真的细节还原度。
+ * - 默认模式（Default）：介于 Speech 和 Music 之间的档位，对音乐的还原度比人声模式要好，但传输数据量比音乐模式要低很多，对各种场景均有不错的适应性。
*/
typedef NS_ENUM(NSInteger, TRTCAudioQuality) {
- /// 流畅音质：采样率：16k；单声道；音频裸码率：16kbps；适合语音通话为主的场景，比如在线会议，语音通话。
+
+ ///人声模式：采样率：16k；单声道；编码码率：16kbps；具备几个模式中最强的网络抗性，适合语音通话为主的场景，比如在线会议，语音通话等。
TRTCAudioQualitySpeech = 1,
- /// 默认音质：采样率：48k；单声道；音频裸码率：50kbps；SDK 默认的音频质量，如无特殊需求推荐选择之。
+
+ ///默认模式：采样率：48k；单声道；编码码率：50kbps；介于 Speech 和 Music 之间的档位，SDK 默认档位，推荐选择。
TRTCAudioQualityDefault = 2,
- /// 高音质：采样率：48k；双声道 + 全频带；音频裸码率：128kbps；适合需要高保真传输音乐的场景，比如K歌、音乐直播等。
+
+ ///音乐模式：采样率：48k；全频带立体声；编码码率：128kbps；适合需要高保真传输音乐的场景，比如在线K歌、音乐直播等。
TRTCAudioQualityMusic = 3,
+
};
/**
- * 3.3 声音播放模式（音频路由）
+ * 3.3 音频路由（即声音的播放模式）
*
- * 微信和手机 QQ 里的视频通话功能，都有一个免提模式，开启后就不用把手机贴在耳朵上，这个功能就是基于音频路由实现的。
- * 一般手机都有两个扬声器，设置音频路由的作用就是要决定声音从哪个扬声器播放出来：
- * - Speakerphone：扬声器，位于手机底部，声音偏大，适合外放音乐。
- * - Earpiece：听筒，位于手机顶部，声音偏小，适合通话。
+ * 音频路由，即声音是从手机的扬声器还是从听筒中播放出来，因此该接口仅适用于手机等移动端设备。
+ * 手机有两个扬声器：一个是位于手机顶部的听筒，一个是位于手机底部的立体声扬声器。
+ * - 设置音频路由为听筒时，声音比较小，只有将耳朵凑近才能听清楚，隐私性较好，适合用于接听电话。
+ * - 设置音频路由为扬声器时，声音比较大，不用将手机贴脸也能听清，因此可以实现“免提”的功能。
*/
typedef NS_ENUM(NSInteger, TRTCAudioRoute) {
- TRTCAudioModeSpeakerphone = 0, ///< 扬声器
- TRTCAudioModeEarpiece = 1, ///< 听筒
+
+ /// Speakerphone：使用扬声器播放（即“免提”），扬声器位于手机底部，声音偏大，适合外放音乐。
+ TRTCAudioModeSpeakerphone = 0,
+
+ /// Earpiece：使用听筒播放，听筒位于手机顶部，声音偏小，适合需要保护隐私的通话场景。
+ TRTCAudioModeEarpiece = 1,
+
};
/**
* 3.4 声音混响模式
*
- * 该枚举值应用于直播场景中的混响模式，主要用于秀场直播中。
+ * 该枚举值应用于设定直播场景中的混响模式，常用于秀场直播中。
*/
typedef NS_ENUM(NSInteger, TRTCReverbType) {
- TRTCReverbType_0 = 0, ///< 关闭混响
- TRTCReverbType_1 = 1, ///< KTV
- TRTCReverbType_2 = 2, ///< 小房间
- TRTCReverbType_3 = 3, ///< 大会堂
- TRTCReverbType_4 = 4, ///< 低沉
- TRTCReverbType_5 = 5, ///< 洪亮
- TRTCReverbType_6 = 6, ///< 金属声
- TRTCReverbType_7 = 7, ///< 磁性
+
+ ///关闭混响
+ TRTCReverbType_0 = 0,
+
+ /// KTV
+ TRTCReverbType_1 = 1,
+
+ ///小房间
+ TRTCReverbType_2 = 2,
+
+ ///大会堂
+ TRTCReverbType_3 = 3,
+
+ ///低沉
+ TRTCReverbType_4 = 4,
+
+ ///洪亮
+ TRTCReverbType_5 = 5,
+
+ ///金属声
+ TRTCReverbType_6 = 6,
+
+ ///磁性
+ TRTCReverbType_7 = 7,
+
};
/**
- * 3.5 变声模式
+ * 3.5 变声类型
*
- * 该枚举值应用于直播场景中的变声模式，主要用于秀场直播中。
+ * 该枚举值应用于设定直播场景中的变声模式，常用于秀场直播中。
*/
typedef NS_ENUM(NSInteger, TRTCVoiceChangerType) {
- TRTCVoiceChangerType_0 = 0, ///< 关闭变声
- TRTCVoiceChangerType_1 = 1, ///< 熊孩子
- TRTCVoiceChangerType_2 = 2, ///< 萝莉
- TRTCVoiceChangerType_3 = 3, ///< 大叔
- TRTCVoiceChangerType_4 = 4, ///< 重金属
- TRTCVoiceChangerType_5 = 5, ///< 感冒
- TRTCVoiceChangerType_6 = 6, ///< 外国人
- TRTCVoiceChangerType_7 = 7, ///< 困兽
- TRTCVoiceChangerType_8 = 8, ///< 死肥仔
- TRTCVoiceChangerType_9 = 9, ///< 强电流
- TRTCVoiceChangerType_10 = 10, ///< 重机械
- TRTCVoiceChangerType_11 = 11, ///< 空灵
+
+ ///关闭变声
+ TRTCVoiceChangerType_0 = 0,
+
+ ///熊孩子
+ TRTCVoiceChangerType_1 = 1,
+
+ ///萝莉
+ TRTCVoiceChangerType_2 = 2,
+
+ ///大叔
+ TRTCVoiceChangerType_3 = 3,
+
+ ///重金属
+ TRTCVoiceChangerType_4 = 4,
+
+ ///感冒
+ TRTCVoiceChangerType_5 = 5,
+
+ ///外国人
+ TRTCVoiceChangerType_6 = 6,
+
+ ///困兽
+ TRTCVoiceChangerType_7 = 7,
+
+ ///死肥仔
+ TRTCVoiceChangerType_8 = 8,
+
+ ///强电流
+ TRTCVoiceChangerType_9 = 9,
+
+ ///重机械
+ TRTCVoiceChangerType_10 = 10,
+
+ ///空灵
+ TRTCVoiceChangerType_11 = 11,
+
};
/**
- * 3.6 系统音量类型
- *
- * 智能手机一般具备两种系统音量类型，即通话音量类型和媒体音量类型。
- * - 通话音量：手机专门为通话场景设计的音量类型，使用手机自带的回声抵消功能，音质相比媒体音量类型较差，
- * 无法通过音量按键将音量调成零，但是支持蓝牙耳机上的麦克风。
- *
- * - 媒体音量：手机专门为音乐场景设计的音量类型，音质相比于通话音量类型要好，通过通过音量按键可以将音量调成零。
- * 使用媒体音量类型时，如果要开启回声抵消（AEC）功能，SDK 会开启内置的声学处理算法对声音进行二次处理。
- * 在媒体音量模式下，蓝牙耳机无法使用自带的麦克风采集声音，只能使用手机上的麦克风进行声音采集。
- *
- * SDK 目前提供了三种系统音量类型的控制模式，分别为：
- * - Auto：“麦上通话，麦下媒体”，即主播上麦时使用通话音量，观众不上麦则使用媒体音量，适合在线直播场景。
- * 如果您在 enterRoom 时选择的场景为 TRTCAppSceneLIVE 或 TRTCAppSceneVoiceChatRoom，SDK 会自动选择该模式。
- *
- * - VOIP：全程使用通话音量，适合多人会议场景。
- * 如果您在 enterRoom 时选择的场景为 TRTCAppSceneVideoCall 或 TRTCAppSceneAudioCall，SDK 会自动选择该模式。
- *
- * - Media：通话全程使用媒体音量，不常用，适合个别有特殊需求（如主播外接声卡）的应用场景。
+ * 3.6 系统音量类型（仅适用于移动设备）
*
+ * 现代智能手机中一般都具备两套系统音量类型，即“通话音量”和“媒体音量”。
+ * - 通话音量：手机专门为接打电话所设计的音量类型，自带回声抵消（AEC）功能，并且支持通过蓝牙耳机上的麦克风进行拾音，缺点是音质比较一般。
+ * 当您通过手机侧面的音量按键下调手机音量时，如果无法将其调至零（也就是无法彻底静音），说明您的手机当前处于通话音量。
+ * - 媒体音量：手机专门为音乐场景所设计的音量类型，无法使用系统的 AEC 功能，并且不支持通过蓝牙耳机的麦克风进行拾音，但具备更好的音乐播放效果。
+ * 当您通过手机侧面的音量按键下调手机音量时，如果能够将手机音量调至彻底静音，说明您的手机当前处于媒体音量。
+ * SDK 目前提供了三种系统音量类型的控制模式：自动切换模式、全程通话音量模式、全程媒体音量模式。
*/
typedef NS_ENUM(NSInteger, TRTCSystemVolumeType) {
- /// “麦上通话，麦下媒体”，即主播上麦时使用通话音量，观众不上麦则使用媒体音量，适合在线直播场景。<br>
- /// 如果您在 enterRoom 时选择的场景为 TRTCAppSceneLIVE 或 TRTCAppSceneVoiceChatRoom，SDK 会自动选择该模式。
- TRTCSystemVolumeTypeAuto = 0,
-
- /// 通话全程使用媒体音量，不常用，适合个别有特殊需求（如主播外接声卡）的应用场景。
- TRTCSystemVolumeTypeMedia = 1,
-
- /// 全程使用通话音量，适合多人会议场景。<br>
- /// 如果您在 enterRoom 时选择的场景为 TRTCAppSceneVideoCall 或 TRTCAppSceneAudioCall 会自动选择该模式。
- TRTCSystemVolumeTypeVOIP = 2,
-};
-#pragma mark -
+ ///自动切换模式：
+ ///也被称为“麦上通话，麦下媒体”，即主播上麦时使用通话音量，观众不上麦则使用媒体音量，适合在线直播场景。
+ ///如果您在 enterRoom 时选择的场景为 TRTCAppSceneLIVE 或 TRTCAppSceneVoiceChatRoom，SDK 会自动使用该模式。
+ TRTCSystemVolumeTypeAuto = 0,
+
+ ///全程媒体音量：
+ ///通话全程使用媒体音量，并不是非常常用的音量类型，适用于对音质要求比较苛刻的音乐场景中。
+ ///如果您的用户大都使用外接设备（比如外接声卡）为主，可以使用该模式，否则请慎用。
+ TRTCSystemVolumeTypeMedia = 1,
+
+ ///全程通话音量：
+ ///该方案的优势在于用户在上下麦时音频模块无需切换工作模式，可以做到无缝上下麦，适合于用户需要频繁上下麦的应用场景。
+ ///如果您在 enterRoom 时选择的场景为 TRTCAppSceneVideoCall 或 TRTCAppSceneAudioCall，SDK 会自动使用该模式。
+ TRTCSystemVolumeTypeVOIP = 2,
+
+};
/////////////////////////////////////////////////////////////////////////////////
//
-// 【（四）更多枚举值定义】
-//
+// 更多枚举值定义
+//
/////////////////////////////////////////////////////////////////////////////////
/**
@@ -415,669 +642,759 @@ typedef NS_ENUM(NSInteger, TRTCSystemVolumeType) {
* 不同的日志等级定义了不同的详实程度和日志数量，推荐一般情况下将日志等级设置为：TRTCLogLevelInfo。
*/
typedef NS_ENUM(NSInteger, TRTCLogLevel) {
- TRTCLogLevelVerbose = 0, ///< 输出所有级别的 Log
- TRTCLogLevelDebug = 1, ///< 输出 DEBUG，INFO，WARNING，ERROR 和 FATAL 级别的 Log
- TRTCLogLevelInfo = 2, ///< 输出 INFO，WARNING，ERROR 和 FATAL 级别的 Log
- TRTCLogLevelWarn = 3, ///< 只输出WARNING，ERROR 和 FATAL 级别的 Log
- TRTCLogLevelError = 4, ///< 只输出ERROR 和 FATAL 级别的 Log
- TRTCLogLevelFatal = 5, ///< 只输出 FATAL 级别的 Log
- TRTCLogLevelNone = 6, ///< 不输出任何 SDK Log
+
+ ///输出所有级别的 Log
+ TRTCLogLevelVerbose = 0,
+
+ ///输出 DEBUG，INFO，WARNING，ERROR 和 FATAL 级别的 Log
+ TRTCLogLevelDebug = 1,
+
+ ///输出 INFO，WARNING，ERROR 和 FATAL 级别的 Log
+ TRTCLogLevelInfo = 2,
+
+ ///输出WARNING，ERROR 和 FATAL 级别的 Log
+ TRTCLogLevelWarn = 3,
+
+ ///输出ERROR 和 FATAL 级别的 Log
+ TRTCLogLevelError = 4,
+
+ ///仅输出 FATAL 级别的 Log
+ TRTCLogLevelFatal = 5,
+
+ ///不输出任何 SDK Log
+ TRTCLogLevelNone = 6,
+
};
/**
- * 4.2 重力感应开关
- *
- * 此配置仅适用于 iOS 和 iPad 等移动设备：
- * - Disable：Mac 平台的默认值，视频上行的画面（也就是房间里的其它用户看到的当前用户的画面）不会跟随重力感应方向而自动调整。
- * - UIAutoLayout：iPhone 和 iPad 平台的默认值，视频上行的画面（也就是房间里的其它用户看到的当前用户的画面）会跟随当前界面的状态栏方向而自动调整。
- * - UIFixLayout：待废弃，效果等同于 UIAutoLayout。
+ * 4.2 重力感应开关（仅适用于移动端）
*/
typedef NS_ENUM(NSInteger, TRTCGSensorMode) {
- TRTCGSensorMode_Disable = 0, ///< 关闭重力感应，Mac 平台的默认值。
- TRTCGSensorMode_UIAutoLayout = 1, ///< 开启重力感应，iPhone 和 iPad 平台的默认值。
- TRTCGSensorMode_UIFixLayout = 2 ///< 待废弃，效果等同于 UIAutoLayout。
-};
-#if TARGET_OS_MAC && !TARGET_OS_IPHONE
-#pragma mark -
+ ///不适配重力感应
+ ///该模式是桌面平台上的默认值，该模式下，当前用户发布出去的视频画面不受重力感应方向变化的影响。
+ TRTCGSensorMode_Disable = 0,
+
+ ///适配重力感应
+ ///该模式是移动平台上的默认值，该模式下，当前用户发布出去的视频画面会跟随设备的重力感应方向进行相应的调整，同时本地预览画面保持方向不变。
+ /// SDK 目前支持的一种适配模式是：当手机或 Pad 上下颠倒时，为了保证远端用户看到的画面方向正常，SDK 会自动将发布出去的画面上下旋转180度。
+ ///如果您的 APP 的界面层开启了重力感应自适应，推荐使用 UIFixLayout 模式。
+ TRTCGSensorMode_UIAutoLayout = 1,
+
+ ///适配重力感应
+ ///该模式下，当前用户发布出去的视频画面会跟随设备的重力感应方向进行相应的调整，同时本地预览画面也会进行相应的旋转适配。
+ ///目前支持的一种特性是：当手机或 Pad 上下颠倒时，为了保证远端用户看到的画面方向正常，SDK 会自动将发布出去的画面上下旋转180度。
+ ///如果您的 APP 的界面层不支持重力感应自适应，并且希望 SDK 的视频画面能够适配重力感应方向，推荐使用 UIFixLayout 模式。
+ TRTCGSensorMode_UIFixLayout = 2,
+
+};
/**
- * 4.3 屏幕分享目标类型（仅 Mac）
- *
- * 该枚举值主要用于 SDK 区分屏幕分享的目标（某一个窗口或整个屏幕）。
+ * 4.3 屏幕分享的目标类型（仅适用于桌面端）
*/
typedef NS_ENUM(NSInteger, TRTCScreenCaptureSourceType) {
- TRTCScreenCaptureSourceTypeUnknown = -1, ///< 未定义
- TRTCScreenCaptureSourceTypeWindow = 0, ///< 该分享目标是某一个Mac窗口
- TRTCScreenCaptureSourceTypeScreen = 1, ///< 该分享目标是整个Mac桌面
-};
-#endif
-#pragma mark -
+ ///未定义
+ TRTCScreenCaptureSourceTypeUnknown = -1,
+
+ ///该分享目标是某一个应用的窗口
+ TRTCScreenCaptureSourceTypeWindow = 0,
+
+ ///该分享目标是某一台显示器的屏幕
+ TRTCScreenCaptureSourceTypeScreen = 1,
+
+};
/**
- * 4.4 混流参数配置模式
+ * 4.4 云端混流的排版模式
*
+ * TRTC 的云端混流服务能够将房间中的多路音视频流混合成一路，因此您需要指定画面的排版方案，我们提供了如下几种排版模式：
*/
typedef NS_ENUM(NSInteger, TRTCTranscodingConfigMode) {
- /// 非法值
- TRTCTranscodingConfigMode_Unknown = 0,
-
- /// 全手动模式，灵活性最高，可以自由组合出各种混流方案，但易用性最差。
- /// 此模式下，您需要填写 TRTCTranscodingConfig 中的所有参数，并需要监听 TRTCCloudDelegate 中的 onUserVideoAvailable() 和 onUserAudioAvailable() 回调，
- /// 以便根据当前房间中各个上麦用户的音视频状态不断地调整 mixUsers 参数，否则会导致混流失败。
- TRTCTranscodingConfigMode_Manual = 1,
-
- /// 纯音频模式，适用于语音通话（AudioCall）和语音聊天室（VoiceChatRoom）等纯音频场景。
- /// 只需要在进房后通过 setMixTranscodingConfig() 接口设置一次，之后 SDK 就会自动把房间内所有上麦用户的声音混流到当前用户的直播流上。
- /// 此模式下，您无需设置 TRTCTranscodingConfig 中的 mixUsers 参数，只需设置 audioSampleRate、audioBitrate 和 audioChannels 等参数。
- TRTCTranscodingConfigMode_Template_PureAudio = 2,
-
- /// 预排版模式，通过占位符提前对各路画面进行排布
- /// 此模式下，您依然需要设置 mixUsers 参数，但可以将 userId 设置为占位符，可选的占位符有：
+
+ ///未定义
+ TRTCTranscodingConfigMode_Unknown = 0,
+
+ ///全手动排版模式
+ ///该模式下，您需要指定每一路画面的精确排版位置。该模式的自由度最高，但易用性也最差：
+ ///- 您需要填写 TRTCTranscodingConfig 中的所有参数，包括每一路画面（TRTCMixUser）的位置坐标。
+ ///- 您需要监听 TRTCCloudDelegate 中的 onUserVideoAvailable() 和 onUserAudioAvailable() 事件回调，并根据当前房间中各个麦上用户的音视频状态不断地调整 mixUsers 参数。
+ TRTCTranscodingConfigMode_Manual = 1,
+
+ ///纯音频模式
+ ///该模式适用于语音通话（AudioCall）和语音聊天室（VoiceChatRoom）等纯音频的应用场景。
+ ///- 您只需要在进入房间后，通过 setMixTranscodingConfig() 接口设置一次，之后 SDK 就会自动把房间内所有上麦用户的声音混流到当前用户的直播流上。
+ ///- 您无需设置 TRTCTranscodingConfig 中的 mixUsers 参数，只需设置 audioSampleRate、audioBitrate 和 audioChannels 等参数即可。
+ TRTCTranscodingConfigMode_Template_PureAudio = 2,
+
+ ///预排版模式
+ ///最受欢迎的排版模式，因为该模式支持您通过占位符提前对各路画面的位置进行设定，之后 SDK 会自动根据房间中画面的路数动态进行适配调整。
+ ///此模式下，您依然需要设置 mixUsers 参数，但可以将 userId 设置为“占位符”，可选的占位符有：
/// - "$PLACE_HOLDER_REMOTE$" : 指代远程用户的画面，可以设置多个。
/// - "$PLACE_HOLDER_LOCAL_MAIN$" ： 指代本地摄像头画面，只允许设置一个。
/// - "$PLACE_HOLDER_LOCAL_SUB$" : 指代本地屏幕分享画面，只允许设置一个。
- /// 但是您可以不需要监听 TRTCCloudDelegate 中的 onUserVideoAvailable() 和 onUserAudioAvailable() 回调进行实时调整，
- /// 只需要在进房成功后调用一次 setMixTranscodingConfig() 即可，之后 SDK 会自动将真实的 userId 补位到您设置的占位符上。
- TRTCTranscodingConfigMode_Template_PresetLayout = 3,
-
- /// 屏幕分享模式，适用于在线教育场景等以屏幕分享为主的应用场景，仅支持 Windows 和 Mac 两个平台的 SDK。
- /// SDK 会先根据您（通过 videoWidth 和 videoHeight 参数）设置的目标分辨率构建一张画布，
- /// 当老师未开启屏幕分享时，SDK 会将摄像头画面等比例拉伸绘制到该画布上；当老师开启屏幕分享之后，SDK 会将屏幕分享画面绘制到同样的画布上。
- /// 这样操作的目的是为了确保混流模块的输出分辨率一致，避免课程回放和网页观看的花屏问题（网页播放器不支持可变分辨率）。
- /// 同时，连麦学生的声音会被默认混合到老师的音视频流中。
- ///
- /// 由于教学模式下的视频内容以屏幕分享为主，因此同时传输摄像头画面和屏幕分享画面是非常浪费带宽的。
- /// 推荐的做法是直接将摄像头画面通过 setLocalVideoRenderCallback 接口自定义绘制到当前屏幕上。
- /// 在该模式下，您无需设置 TRTCTranscodingConfig 中的 mixUsers 参数，SDK 不会混合学生的画面，以免干扰屏幕分享的效果。
- ///
- /// 您可以将 TRTCTranscodingConfig 中的 width × height 设为 0px × 0px，SDK 会自动根据用户当前屏幕的宽高比计算出一个合适的分辨率：
- /// - 如果老师当前屏幕宽度 <= 1920px，SDK 会使用老师当前屏幕的实际分辨率。
- /// - 如果老师当前屏幕宽度 > 1920px，SDK 会根据当前屏幕宽高比，选择 1920x1080(16:9)、1920x1200(16:10)、1920x1440(4:3) 三种分辨率中的一种。
+ ///此模式下，您不需要监听 TRTCCloudDelegate 中的 onUserVideoAvailable() 和 onUserAudioAvailable() 回调进行实时调整，
+ ///只需要在进房成功后调用一次 setMixTranscodingConfig() 即可，之后 SDK 会自动将真实的 userId 补位到您设置的占位符上。
+ TRTCTranscodingConfigMode_Template_PresetLayout = 3,
+
+ ///屏幕分享模式
+ ///适用于在线教育场景等以屏幕分享为主的应用场景，仅支持 Windows 和 Mac 两个平台的 SDK。
+ ///该模式下，SDK 会先根据您通过 videoWidth 和 videoHeight 参数设置的目标分辨率构建一张画布，
+ ///- 当老师未开启屏幕分享时，SDK 会将老师的摄像头画面等比例拉伸绘制到该画布上；
+ ///- 当老师开启屏幕分享之后，SDK 会将屏幕分享画面绘制到同样的画布上。
+ ///此种排版模式的目的是为了确保混流模块的输出分辨率一致，避免课程回放和网页观看的花屏问题（网页播放器不支持可变分辨率）。
+ ///同时，连麦学生的声音也会被默认混合到老师的音视频流中。
+ ///< br>
+ ///由于教学模式下的视频内容以屏幕分享为主，因此同时传输摄像头画面和屏幕分享画面是非常浪费带宽的。
+ ///推荐的做法是直接将摄像头画面通过 setLocalVideoRenderCallback 接口自定义绘制到当前屏幕上。
+ ///在该模式下，您无需设置 TRTCTranscodingConfig 中的 mixUsers 参数，SDK 不会混合学生的画面，以免干扰屏幕分享的效果。
+ ///< br>
+ ///您可以将 TRTCTranscodingConfig 中的 width × height 设为 0px × 0px，SDK 会自动根据用户当前屏幕的宽高比计算出一个合适的分辨率：
+ ///- 如果老师当前屏幕宽度 <= 1920px，SDK 会使用老师当前屏幕的实际分辨率。
+ ///- 如果老师当前屏幕宽度 > 1920px，SDK 会根据当前屏幕宽高比，选择 1920x1080(16:9)、1920x1200(16:10)、1920x1440(4:3) 三种分辨率中的一种。
TRTCTranscodingConfigMode_Template_ScreenSharing = 4,
+
};
/**
- * 4.5 媒体录制类型
+ * 4.5 媒体录制类型
+ *
+ * 该枚举类型用于本地媒体录制接口{@link startLocalRecording}，用于指定是录制音视频文件还是纯音频文件。
*/
typedef NS_ENUM(NSUInteger, TRTCRecordType) {
- TRTCRecordTypeAudio = 0, ///< 仅录制音频
- TRTCRecordTypeVideo = 1, ///< 仅录制视频
- TRTCRecordTypeBoth = 2, ///< 同时录制音频、视频
+
+ ///仅录制音频
+ TRTCRecordTypeAudio = 0,
+
+ ///仅录制视频
+ TRTCRecordTypeVideo = 1,
+
+ ///同时录制音频和视频
+ TRTCRecordTypeBoth = 2,
+
};
/**
* 4.6 混流输入类型
- *
*/
typedef NS_ENUM(NSUInteger, TRTCMixInputType) {
- /// 不指定，根据 pureAudio 值决定混流输入类型
- TRTCMixInputTypeUndefined = 0,
- /// 混入音视频
- TRTCMixInputTypeAudioVideo = 1,
- /// 只混入视频
- TRTCMixInputTypePureVideo = 2,
- /// 只混入音频
- TRTCMixInputTypePureAudio = 3,
+
+ ///不指定，SDK 会根据另一个参数 pureAudio 的数值决定混流输入类型
+ TRTCMixInputTypeUndefined = 0,
+
+ ///混入音频和视频
+ TRTCMixInputTypeAudioVideo = 1,
+
+ ///只混入视频
+ TRTCMixInputTypePureVideo = 2,
+
+ ///只混入音频
+ TRTCMixInputTypePureAudio = 3,
+
+};
+
+/**
+ * 4.7 设备类型（仅适用于桌面平台）
+ *
+ * 该枚举值用于定义三种类型的音视频设备，即摄像头、麦克风和扬声器，以便让一套设备管理接口可以操控三种不同类型的设备。
+ * 自 Ver8.0 版本开始，TRTC 在 TXDeviceManager 中重新定义了 “TXMediaDeviceType” 用于替换老版本中的 “TRTCMediaDeviceType”，
+ * 此处仅保留 “TRTCMediaDeviceType” 的定义，用于兼容老版本的客户代码。
+ */
+#if TARGET_OS_MAC && !TARGET_OS_IPHONE
+typedef NS_ENUM(NSInteger, TRTCMediaDeviceType) {
+ TRTCMediaDeviceTypeUnknown = -1, ///< undefined device type
+ TRTCMediaDeviceTypeAudioInput = 0, ///< microphone
+ TRTCMediaDeviceTypeAudioOutput = 1, ///< speaker
+ TRTCMediaDeviceTypeVideoCamera = 2, ///< camera
+ TRTCMediaDeviceTypeVideoWindow = 3, ///< windows(for screen share)
+ TRTCMediaDeviceTypeVideoScreen = 4, ///< screen (for screen share)
+} __attribute__((deprecated("use TXDeviceManager#TXMediaDeviceType instead")));
+
+typedef TXMediaDeviceInfo TRTCMediaDeviceInfo __attribute__((deprecated("use TXDeviceManager#TXMediaDeviceInfo instead")));
+#endif
+
+/**
+ * 4.11 音频录制内容类型
+ *
+ * 该枚举类型用于音频录制接口{@link startAudioRecording}，用于指定录制音频的内容。
+ */
+typedef NS_ENUM(NSUInteger, TRTCAudioRecordingContent) {
+
+ ///录制本地和远端所有音频
+ TRTCAudioRecordingContentAll = 0,
+
+ ///仅录制本地音频
+ TRTCAudioRecordingContentLocal = 1,
+
+ ///仅录制远端音频
+ TRTCAudioRecordingContentRemote = 2,
+
};
/////////////////////////////////////////////////////////////////////////////////
//
-// 【（五）TRTC 核心类型定义】
-//
+// TRTC 核心类型定义
+//
/////////////////////////////////////////////////////////////////////////////////
-#pragma mark -
-/**
- * 5.1 进房相关参数
+/**
+ * 5.1 进房参数
*
- * 只有该参数填写正确，才能顺利调用 enterRoom 进入 roomId 或者 strRoomId 所指定的音视频房间。
+ * 作为 TRTC SDK 的进房参数，只有该参数填写正确，才能顺利进入 roomId 或者 strRoomId 所指定的音视频房间。
+ * 由于历史原因，TRTC 支持数字和字符串两种类型的房间号，分别是 roomId 和 strRoomId。
+ * 请注意：不要混用 roomId 和 strRoomId，因为它们之间是不互通的，比如数字 123 和字符串 “123” 在 TRTC 看来是两个完全不同的房间。
*/
@interface TRTCParams : NSObject
-///【字段含义】应用标识 [必填]，腾讯云基于 sdkAppId 完成计费统计。
-///【推荐取值】在 [实时音视频控制台](https://console.cloud.tencent.com/rav/) 创建应用后可以在账号信息页面中得到该 ID
-@property (nonatomic, assign) UInt32 sdkAppId;
+///【字段含义】应用标识（必填），腾讯云基于 sdkAppId 完成计费统计。
+///【推荐取值】在 [实时音视频控制台](https://console.cloud.tencent.com/rav/) 创建应用后可以在账号信息页面中得到该 ID。
+@property(nonatomic, assign) UInt32 sdkAppId;
-///【字段含义】用户标识 [必填]，当前用户的 userId，相当于登录用户名。
-///【推荐取值】限制长度为32字节，只允许包含大小写英文字母（a-zA-Z）、数字（0-9）及下划线和连词符。
-@property (nonatomic, copy, nonnull) NSString* userId;
+///【字段含义】用户标识（必填），当前用户的 userId，相当于用户名，使用 UTF-8 编码。
+///【推荐取值】如果一个用户在您的帐号系统中的 ID 为“mike”，则 userId 即可设置为“mike”。
+@property(nonatomic, copy, nonnull) NSString *userId;
-///【字段含义】用户签名 [必填]，当前 userId 对应的验证签名，相当于登录密码。
+///【字段含义】用户签名（必填），当前 userId 对应的验证签名，相当于使用云服务的登录密码。
///【推荐取值】具体计算方法请参见 [如何计算UserSig](https://cloud.tencent.com/document/product/647/17275)。
-@property (nonatomic, copy, nonnull) NSString* userSig;
+@property(nonatomic, copy, nonnull) NSString *userSig;
-///【字段含义】数字房间号码，在同一个房间里的用户（userId）可以彼此看到对方并进行视频通话
+///【字段含义】数字房间号，在同一个房间里的用户（userId）可以彼此看到对方并进行音视频通话。
///【推荐取值】取值范围：1 - 4294967294。
-///【特别说明】roomId 与 strRoomId 必填一个，若您选用 strRoomId，则 roomId 需要填写为0。若两者都填，将优先选用 roomId。
-/// 请注意，同一个 sdkAppId 互通时，请务必选用同一种房间号码类型，避免影响互通。
-@property (nonatomic, assign) UInt32 roomId;
+///【特别说明】roomId 与 strRoomId 是互斥的，若您选用 strRoomId，则 roomId 需要填写为0。若两者都填，SDK 将优先选用 roomId。
+///【请您注意】不要混用 roomId 和 strRoomId，因为它们之间是不互通的，比如数字 123 和字符串 “123” 在 TRTC 看来是两个完全不同的房间。
+@property(nonatomic, assign) UInt32 roomId;
-///【字段含义】字符串房间号码，在同一个房间里的用户（userId）可以彼此看到对方并进行视频通话。
+///【字段含义】字符串房间号，在同一个房间里的用户（userId）可以彼此看到对方并进行音视频通话。
+///【特别说明】roomId 与 strRoomId 是互斥的，若您选用 strRoomId，则 roomId 需要填写为0。若两者都填，SDK 将优先选用 roomId。
+///【请您注意】不要混用 roomId 和 strRoomId，因为它们之间是不互通的，比如数字 123 和字符串 “123” 在 TRTC 看来是两个完全不同的房间。
///【推荐取值】限制长度为64字节。以下为支持的字符集范围（共 89 个字符）:
-/// -大小写英文字母（a-zA-Z）；
-/// -数字（0-9）；
-/// -空格、"!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、" {"、"}"、"|"、"~"、","。
-///【特别说明】roomId 与 strRoomId 必填一个，若您选用 strRoomId，则 roomId 需要填写为0。若两者都填，将优先选用 roomId。
-/// 请注意，同一个 sdkAppId 互通时，请务必选用同一种房间号码类型，避免影响互通。
-@property (nonatomic, copy, nonnull) NSString* strRoomId;
-
-///【字段含义】直播场景下的角色，仅适用于直播场景（TRTCAppSceneLIVE 和 TRTCAppSceneVoiceChatRoom），通话场景下指定无效。
-///【推荐取值】默认值：主播（TRTCRoleAnchor）
-@property (nonatomic, assign) TRTCRoleType role;
-
-///【字段含义】绑定腾讯云直播 CDN 流 ID[非必填]，设置之后，您就可以在腾讯云直播 CDN 上通过标准直播方案（FLV或HLS）播放该用户的音视频流。
-///【推荐取值】限制长度为64字节，可以不填写，一种推荐的方案是使用 “sdkappid_roomid_userid_main” 作为 streamid，这样比较好辨认且不会在您的多个应用中发生冲突。
-///【特殊说明】要使用腾讯云直播 CDN，您需要先在[控制台](https://console.cloud.tencent.com/trtc/) 中的功能配置页开启“启用旁路推流”开关。
+/// - 大小写英文字母（a-zA-Z）；
+/// - 数字（0-9）；
+/// - 空格、"!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、" {"、"}"、"|"、"~"、","。
+@property(nonatomic, copy, nonnull) NSString *strRoomId;
+
+///【字段含义】直播场景下的角色，仅适用于直播场景（{@link TRTCAppSceneLIVE} 和{@link TRTCAppSceneVoiceChatRoom}），通话场景下指定该参数是无效的。
+///【推荐取值】默认值：主播（{@link TRTCRoleAnchor}）。
+@property(nonatomic, assign) TRTCRoleType role;
+
+///【字段含义】用于指定在腾讯云直播平台上的 streamId（选填），设置之后，您可以在腾讯云直播 CDN 上通过标准拉流方案（FLV或HLS）播放该用户的音视频流。
+///【推荐取值】限制长度为64字节，可以不填写，一种推荐的方案是使用 “sdkappid_roomid_userid_main” 作为 streamid，这中命名方式容易辨认且不会在您的多个应用中发生冲突。
+///【特殊说明】要使用腾讯云直播 CDN，您需要先在[控制台](https://console.cloud.tencent.com/trtc/) 中的功能配置页开启“启动自动旁路直播”开关。
///【参考文档】[CDN 旁路直播](https://cloud.tencent.com/document/product/647/16826)。
-@property (nonatomic, copy, nullable) NSString* streamId;
-
-///【字段含义】云端录制开关，用于指定是否要在云端将该用户的音视频流录制成指定格式的文件。
-/// 方案一：手动录制
-/// - 需要在“[控制台](https://console.cloud.tencent.com/trtc) => 应用管理 => 云端录制配置”中开启云端录制。
-/// - 设置“录制形式”为“手动录制”。
-/// - 设置手动录制后，在一个 TRTC 房间中只有设置了 userDefineRecordId 参数的用户才会在云端录制出视频文件，不指定该参数的用户不会产生录制行为。
-/// - 文件会以 “userDefineRecordId_起始时间_结束时间” 的格式命名。
-///
-/// 方案二：自动录制
-/// - 需要在“[控制台](https://console.cloud.tencent.com/trtc) => 应用管理 => 云端录制配置”中开启云端录制。
-/// - 设置“录制形式”为“自动录制”。
-/// - 设置自动录制后，在一个 TRTC 房间中的任何一个有音视频上行的用户，均会在云端录制出视频文件。
-/// - 文件会以 “userDefineRecordId_起始时间_结束时间” 的格式命名，如果不指定 userDefineRecordId，则文件会以 streamid 命名。
-///
-///【推荐取值】限制长度为64字节，只允许包含大小写英文字母（a-zA-Z）、数字（0-9）及下划线和连词符。
-///【参考文档】[云端录制](https://cloud.tencent.com/document/product/647/16823)。
-@property (nonatomic, copy, nullable) NSString* userDefineRecordId;
+@property(nonatomic, copy, nullable) NSString *streamId;
-///【字段含义】房间签名 [非必填]，当您希望某个房间只能让特定的 userId 进入时，需要使用 privateMapKey 进行权限保护。
+///【字段含义】云端录制开关（选填），用于指定是否要在云端将该用户的音视频流录制下来。
+///【参考文档】[云端录制](https://cloud.tencent.com/document/product/647/16823)。
+///【推荐取值】限制长度为64字节，只允许包含大小写英文字母（a-zA-Z）、数字（0-9）及下划线和连词符。
+/// <p>
+/// 方案一：手动录制方案：
+/// 1. 在“[控制台](https://console.cloud.tencent.com/trtc) => 应用管理 => 云端录制配置”中开启云端录制。
+/// 2. 设置“录制形式”为“手动录制”。
+/// 3. 设置手动录制后，在一个 TRTC 房间中只有设置了 userDefineRecordId 参数的用户才会在云端录制出视频文件，不指定该参数的用户不会产生录制行为。
+/// 4. 云端会以 “userDefineRecordId_起始时间_结束时间” 的格式命名录制下来的文件。
+/// <p>
+/// 方案二：自动录制方案：
+/// 1. 需要在“[控制台](https://console.cloud.tencent.com/trtc) => 应用管理 => 云端录制配置”中开启云端录制。
+/// 2. 设置“录制形式”为“自动录制”。
+/// 3. 设置自动录制后，在一个 TRTC 房间中的任何一个有音视频上行的用户，均会在云端录制出视频文件。
+/// 4. 文件会以 “userDefineRecordId_起始时间_结束时间” 的格式命名，如果不指定 userDefineRecordId，则文件会以 “streamId_起始时间_结束时间” 命名。
+/// <br>
+@property(nonatomic, copy, nullable) NSString *userDefineRecordId;
+
+///【字段含义】用于权限控制的权限票据（选填），当您希望某个房间只能让特定的 userId 进入时，需要使用 privateMapKey 进行权限保护。
///【推荐取值】仅建议有高级别安全需求的客户使用，更多详情请参见 [进房权限保护](https://cloud.tencent.com/document/product/647/32240)。
-@property (nonatomic, copy, nullable) NSString* privateMapKey;
+@property(nonatomic, copy, nullable) NSString *privateMapKey;
-///【字段含义】业务数据 [非必填]，部分高级特性才需要用到此字段。
-///【推荐取值】不建议使用
-@property (nonatomic, copy, nullable) NSString* bussInfo;
+///【字段含义】业务数据字段（选填），部分高级特性才需要用到此字段。
+///【推荐取值】请不要自行设置该字段。
+@property(nonatomic, copy, nullable) NSString *bussInfo;
@end
-/// 回调音频帧数据格式
-@interface TRTCAudioFrameDelegateFormat : NSObject
-/// 采样率，可以是16000 32000 44100 48000
-@property (nonatomic, assign) TRTCAudioSampleRate sampleRate;
-/// 声道数，可以是1或者2
-@property (nonatomic, assign) int channels;
-/// 采样点数，必须是 sampleRate/100 的整数倍
-@property (nonatomic, assign) int samplesPerCall;
-@end
-
-#pragma mark -
-
-/**
+/**
* 5.2 视频编码参数
*
- * 该设置决定远端用户看到的画面质量（同时也是云端录制出的视频文件的画面质量）。
+ * 该设置决定远端用户看到的画面质量，同时也决定了云端录制出的视频文件的画面质量。
*/
@interface TRTCVideoEncParam : NSObject
-///【字段含义】视频分辨率
-///【推荐取值】
-/// - 视频通话建议选择360 × 640及以下分辨率，resMode 选择 Portrait。
-/// - 手机直播建议选择540 × 960，resMode 选择 Portrait。
-/// - Windows 和 Mac 建议选择640 × 360 及以上分辨率，resMode 选择 Landscape。
-///【特别说明】 TRTCVideoResolution 默认只有横屏模式的分辨率，例如640 × 360。
-/// 如需使用竖屏分辨率，请指定 resMode 为 Portrait，例如640 × 360结合 Portrait 则为360 × 640。
-@property (nonatomic, assign) TRTCVideoResolution videoResolution;
+///【字段含义】 视频分辨率
+///【特别说明】如需使用竖屏分辨率，请指定 resMode 为 Portrait，例如： 640 × 360 + Portrait = 360 × 640。
+///【推荐取值】
+/// - 手机视频通话：建议选择 360 × 640 及以下分辨率，resMode 选择 Portrait，即竖屏分辨率。
+/// - 手机在线直播：建议选择 540 × 960，resMode 选择 Portrait，即竖屏分辨率。
+/// - 桌面平台（Win + Mac）：建议选择 640 × 360 及以上分辨率，resMode 选择 Landscape，即横屏分辨率。
+@property(nonatomic, assign) TRTCVideoResolution videoResolution;
-///【字段含义】分辨率模式（横屏分辨率 - 竖屏分辨率）
-///【推荐取值】手机直播建议选择 Portrait，Windows 和 Mac 建议选择 Landscape。
-///【特别说明】如果 videoResolution 指定分辨率 640 × 360，resMode 指定模式为 Portrait，则最终编码出的分辨率为360 × 640。
-@property (nonatomic, assign) TRTCVideoResolutionMode resMode;
+///【字段含义】分辨率模式（横屏分辨率 or 竖屏分辨率）
+///【推荐取值】手机平台（iOS、Android）建议选择 Portrait，桌面平台（Windows、Mac）建议选择 Landscape。
+///【特别说明】如需使用竖屏分辨率，请指定 resMode 为 Portrait，例如： 640 × 360 + Portrait = 360 × 640。
+@property(nonatomic, assign) TRTCVideoResolutionMode resMode;
///【字段含义】视频采集帧率
-///【推荐取值】15fps或20fps，5fps以下，卡顿感明显。10fps以下，会有轻微卡顿感。20fps以上，则过于浪费（电影的帧率为24fps）。
-///【特别说明】很多 Android 手机的前置摄像头并不支持15fps以上的采集帧率，部分过于突出美颜功能的 Android 手机前置摄像头的采集帧率可能低于10fps。
-@property (nonatomic, assign) int videoFps;
+///【推荐取值】15fps或20fps。5fps以下，卡顿感明显。10fps以下，会有轻微卡顿感。20fps以上，会浪费带宽（电影的帧率为24fps）。
+///【特别说明】部分 Android 手机的前置摄像头并不支持15fps以上的采集帧率，部分主打美颜功能的 Android 手机的前置摄像头的采集帧率可能低于10fps。
+@property(nonatomic, assign) int videoFps;
-///【字段含义】目标视频码率，SDK 会按照目标码率进行编码，只有在网络不佳的情况下才会主动降低视频码率。
+///【字段含义】目标视频码率，SDK 会按照目标码率进行编码，只有在弱网络环境下才会主动降低视频码率。
///【推荐取值】请参考本 TRTCVideoResolution 在各档位注释的最佳码率，也可以在此基础上适当调高。
-/// 比如 TRTCVideoResolution_1280_720 对应 1200kbps 的目标码率，您也可以设置为 1500kbps 用来获得更好的清晰度观感。
-///【特别说明】SDK 会努力按照 videoBitrate 指定的码率进行编码，只有在网络不佳的情况下才会主动降低视频码率，最低会降至 minVideoBitrate 所设定的数值。
-/// 如果您追求“允许卡顿但要保持清晰”的效果，可以设置 minVideoBitrate 为 videoBitrate 的 60%；
-/// 如果您追求“允许模糊但要保持流畅”的效果，可以设置 minVideoBitrate 为 200kbps；
-/// 如果您将 videoBitrate 和 minVideoBitrate 设置为同一个值，等价于关闭 SDK 的自适应调节能力。
-@property (nonatomic, assign) int videoBitrate;
-
-///【字段含义】最低视频码率，SDK 会在网络不佳的情况下主动降低视频码率，最低会降至 minVideoBitrate 所设定的数值。
-///【推荐取值】
-/// - 如果您追求“允许卡顿但要保持清晰”的效果，可以设置 minVideoBitrate 为 videoBitrate 的 60%；
-/// - 如果您追求“允许模糊但要保持流畅”的效果，可以设置 minVideoBitrate 为 200kbps；
-/// - 如果您将 videoBitrate 和 minVideoBitrate 设置为同一个值，等价于关闭 SDK 的自适应调节能力；
-/// - 默认值：0，此时最低码率由 SDK 根据分辨率情况，自动设置合适的数值。
-///【特别说明】
-/// - 当您把分辨率设置的比较高时，minVideoBitrate 不适合设置的太低，否则会出现画面模糊和大范围的马赛克宏块。
-/// 比如把分辨率设置为 720p，把码率设置为 200kbps，那么编码出的画面将会出现大范围区域性马赛克。
-@property (nonatomic, assign) int minVideoBitrate;
-
-///【字段含义】是否允许 SDK 动态调整分辨率，开启后会对云端录制产生影响。
-///【推荐取值】
-/// - 需要开启云端录制的场景建议设置为 NO，中途视频分辨率发生变化后，云端录制出的 MP4 在一般的播放器上都无法正常播放。
-/// - 视频通话模式，若无需云端录制，可以设置为 YES，此时 SDK 会根据当前待带宽情况自动选择合适的分辨率（仅针对 TRTCVideoStreamTypeBig 生效）。
-/// - 默认值：NO。
-///【特别说明】如有云端录制需求，请设置为 NO。
-@property (nonatomic, assign) BOOL enableAdjustRes;
+/// 比如：TRTCVideoResolution_1280_720 对应 1200kbps 的目标码率，您也可以设置为 1500kbps 用来获得更好的观感清晰度。
+///【特别说明】您可以通过同时设置 videoBitrate 和 minVideoBitrate 两个参数，用于约束 SDK 对视频码率的调整范围：
+/// - 如果您追求“弱网络下允许卡顿但要保持清晰”的效果，可以设置 minVideoBitrate 为 videoBitrate 的 60%；
+/// - 如果您追求“弱网络下允许模糊但要保持流畅”的效果，可以设置 minVideoBitrate 为一个较低的数值（比如 100kbps）；
+/// - 如果您将 videoBitrate 和 minVideoBitrate 设置为同一个值，等价于关闭 SDK 对视频码率的自适应调节能力。
+@property(nonatomic, assign) int videoBitrate;
+
+///【字段含义】最低视频码率，SDK 会在网络不佳的情况下主动降低视频码率以保持流畅度，最低会降至 minVideoBitrate 所设定的数值。
+///【特别说明】 默认值：0，此时最低码率由 SDK 会根据您指定的分辨率，自动计算出合适的数值。
+///【推荐取值】您可以通过同时设置 videoBitrate 和 minVideoBitrate 两个参数，用于约束 SDK 对视频码率的调整范围：
+/// - 如果您追求“弱网络下允许卡顿但要保持清晰”的效果，可以设置 minVideoBitrate 为 videoBitrate 的 60%；
+/// - 如果您追求“弱网络下允许模糊但要保持流畅”的效果，可以设置 minVideoBitrate 为一个较低的数值（比如 100kbps）；
+/// - 如果您将 videoBitrate 和 minVideoBitrate 设置为同一个值，等价于关闭 SDK 对视频码率的自适应调节能力。
+@property(nonatomic, assign) int minVideoBitrate;
+
+///【字段含义】是否允许动态调整分辨率（开启后会对云端录制产生影响）。
+///【推荐取值】该功能适用于不需要云端录制的场景，开启后 SDK 会根据当前网络情况，智能选择出一个合适的分辨率，避免出现“大分辨率+小码率”的低效编码模式。
+///【特别说明】默认值：关闭。如有云端录制的需求，请不要开启此功能，因为如果视频分辨率发生变化后，云端录制出的 MP4 在普通的播放器上无法正常播放。
+@property(nonatomic, assign) BOOL enableAdjustRes;
@end
-#pragma mark -
-
-/**
- * 5.3 网络流控相关参数
+/**
+ * 5.3 网络流控（Qos）参数集
*
- * 网络流控相关参数，该设置决定 SDK 在各种网络环境下的调控方向（例如弱网下选择“保清晰”或“保流畅”）
+ * 网络流控相关参数，该设置决定 SDK 在弱网络环境下的调控策略（例如：“清晰优先”或“流畅优先”）
*/
@interface TRTCNetworkQosParam : NSObject
-///【字段含义】弱网下是“保清晰”或“保流畅”
-///【特别说明】
-/// - 弱网下保流畅：在遭遇弱网环境时，画面会变得模糊，且出现较多马赛克，但可以保持流畅不卡顿
-/// - 弱网下保清晰：在遭遇弱网环境时，画面会尽可能保持清晰，但可能会更容易出现卡顿
-@property (nonatomic, assign) TRTCVideoQosPreference preference;
+///【字段含义】清晰优先还是流畅优先
+///【推荐取值】清晰优先
+///【特别说明】该参数主要影响 TRTC 在较差网络环境下的音视频表现：
+/// - 流畅优先：即当前网络不足以传输既清晰又流畅的画面时，优先保证画面的流畅性，代价就是画面会比较模糊且伴随有较多的马赛克。
+/// - 清晰优先（默认值）：即当前网络不足以传输既清晰又流畅的画面时，优先保证画面的清晰度，代价就是画面会比较卡顿。
+@property(nonatomic, assign) TRTCVideoQosPreference preference;
-///【字段含义】视频分辨率（云端控制 - 客户端控制）
+///【字段含义】流控模式（已废弃）
///【推荐取值】云端控制
-///【特别说明】
-/// - Server 模式（默认）：云端控制模式，若无特殊原因，请直接使用该模式
-/// - Client 模式：客户端控制模式，用于 SDK 开发内部调试，客户请勿使用
-@property (nonatomic, assign) TRTCQosControlMode controlMode;
+///【特别说明】请设置为云端控制模式（TRTCQosControlModeServer）
+@property(nonatomic, assign) TRTCQosControlMode controlMode;
@end
-#pragma mark -
-
-/**
- * 5.4 网络质量
+/**
+ * 5.4 视频画面的渲染参数
*
- * 表示网络质量的好坏，通过这个数值，您可以在 UI 界面上用图标表征 userId 的通话线路质量
+ * 您可以通过设置此参数来控制画面的旋转角度、填充模式和左右镜像模式。
*/
-@interface TRTCQualityInfo : NSObject
-/// 用户 ID
-@property (nonatomic, copy, nullable) NSString* userId;
-/// 网络质量
-@property (nonatomic, assign) TRTCQuality quality;
-@end
+@interface TRTCRenderParams : NSObject
-#pragma mark -
+///【字段含义】图像的顺时针旋转角度
+///【推荐取值】支持90、180以及270旋转角度，默认值：{@link TRTCVideoRotation_0}
+@property(nonatomic) TRTCVideoRotation rotation;
-/**
- * 5.5 音量大小
+///【字段含义】画面填充模式
+///【推荐取值】填充（画面可能会被拉伸裁剪）或适应（画面可能会有黑边），默认值：{@link TRTCVideoFillMode_Fill}
+@property(nonatomic) TRTCVideoFillMode fillMode;
+
+///【字段含义】画面镜像模式
+///【推荐取值】默认值：{@link TRTCVideoMirrorType_Auto}
+@property(nonatomic) TRTCVideoMirrorType mirrorType;
+
+@end
+
+/**
+ * 5.5 网络质量
*
- * 表示语音音量的评估大小，通过这个数值，您可以在 UI 界面上用图标表征 userId 是否有在说话
+ * 表征网络质量的好坏，您可以通过该数值在用户界面上展示每个用户的网络质量。
*/
-@interface TRTCVolumeInfo : NSObject <NSCopying>
-/// 说话者的 userId, nil 为自己
-@property (strong, nonatomic, nullable) NSString *userId;
-/// 说话者的音量, 取值范围0 - 100
-@property (assign, nonatomic) NSUInteger volume;
-@end
+@interface TRTCQualityInfo : NSObject
-#if TARGET_OS_MAC && !TARGET_OS_IPHONE
-#pragma mark -
+///用户 ID
+@property(nonatomic, copy, nullable) NSString *userId;
+
+///网络质量
+@property(nonatomic, assign) TRTCQuality quality;
+@end
/**
- * 5.6 屏幕分享目标信息（仅 Mac）
+ * 5.6 音量大小
*
- * 如果您要给您的 App 增加屏幕分享功能，一般需要先显示一个窗口选择界面，用户才可以选择希望分享的窗口。
- * TRTCScreenCaptureSourceInfo 主要用于定义分享窗口的 ID、类型、窗口名称以及缩略图。
+ * 表征语音音量的评估值，您可以通过该数值在用户界面上展示每个用户的音量大小。
*/
-@interface TRTCScreenCaptureSourceInfo : NSObject
-/// 分享类型：需要某个窗口或整个屏幕
-@property (assign, nonatomic) TRTCScreenCaptureSourceType type;
-/// 窗口ID
-@property (copy, nonatomic, nullable) NSString * sourceId;
-/// 窗口名称
-@property (copy, nonatomic, nullable) NSString * sourceName;
-/// 窗口属性
-@property (nonatomic, strong, nullable) NSDictionary * extInfo;
-/// 窗口缩略图
-@property (nonatomic, readonly, nullable) NSImage *thumbnail;
-/// 窗口小图标
-@property (nonatomic, readonly, nullable) NSImage *icon;
-@end
-#endif
+@interface TRTCVolumeInfo : NSObject
+
+///说话者的 userId, 如果 userId 为空则代表是当前用户自己。
+@property(nonatomic, copy, nullable) NSString *userId;
-#pragma mark -
+///说话者的音量大小, 取值范围[0 - 100]。
+@property(assign, nonatomic) NSUInteger volume;
+
+@end
/**
* 5.7 网络测速结果
*
- * 您可以在用户进入房间前通过 TRTCCloud 的 startSpeedTest 接口进行测速 （注意：请不要在通话中调用），
+ * 您可以在用户进入房间前通过 {@link startSpeedTest} 接口进行测速（注意：请不要在通话中调用），
* 测速结果会每2 - 3秒钟返回一次，每次返回一个 IP 地址的测试结果。
- *
- * @note - quality 是内部通过评估算法测算出的网络质量，loss 越低，rtt 越小，得分便越高。
- * @note - upLostRate 是指上行丢包率。例如，0.3表示每向服务器发送10个数据包可能会在中途丢失3个。
- * @note - downLostRate 是指下行丢包率。例如，0.2表示每从服务器收取10个数据包可能会在中途丢失2个。
- * @note - rtt 是指当前设备到腾讯云服务器的一次网络往返时间，该值越小越好，正常数值范围是10ms - 100ms
*/
@interface TRTCSpeedTestResult : NSObject
-/// 服务器 IP 地址
-@property (strong, nonatomic, nonnull) NSString *ip;
+///服务器 IP 地址
+@property(strong, nonatomic, nonnull) NSString *ip;
-/// 网络质量，内部通过评估算法测算出的网络质量，loss 越低，rtt 越小，得分便越高。
-@property (nonatomic) TRTCQuality quality;
+///内部通过评估算法测算出的网络质量，网络质量越好得分越高。
+@property(nonatomic) TRTCQuality quality;
-/// 上行丢包率，范围是0 - 1.0，例如，0.3表示每向服务器发送10个数据包可能会在中途丢失3个。
-@property (nonatomic) float upLostRate;
+///上行丢包率，取值范围是 [0 - 1.0]，例如 0.3 表示每向服务器发送10个数据包可能会在中途丢失3个。
+@property(nonatomic) float upLostRate;
-/// 下行丢包率，范围是0 - 1.0，例如，0.2表示每从服务器收取10个数据包可能会在中途丢失2个。
-@property (nonatomic) float downLostRate;
+///下行丢包率，取值范围是 [0 - 1.0]，例如 0.2 表示每从服务器收取10个数据包可能会在中途丢失2个。
+@property(nonatomic) float downLostRate;
-/// 延迟（毫秒），指当前设备到腾讯云服务器的一次网络往返时间，该值越小越好，正常数值范围是10ms - 100ms
-@property (nonatomic) uint32_t rtt;
+///延迟（毫秒），指当前设备到 TRTC 服务器的一次网络往返时间，该值越小越好，正常数值范围是10ms - 100ms。
+@property(nonatomic) uint32_t rtt;
@end
-#pragma mark -
-
/**
- * 5.8 视频帧信息
+ * 5.9 视频帧信息
*
- * TRTCVideoFrame 用来描述一帧视频画面的裸数据，它可以是一帧编码前的画面，也可以是一帧解码后的画面。
+ * TRTCVideoFrame 用来描述一帧视频画面的裸数据，也就是编码前或者解码后的视频画面数据。
*/
@interface TRTCVideoFrame : NSObject
-///【字段含义】视频像素格式
-///【推荐取值】TRTCVideoPixelFormat_NV12
-@property (nonatomic, assign) TRTCVideoPixelFormat pixelFormat;
+///【字段含义】视频的像素格式
+@property(nonatomic, assign) TRTCVideoPixelFormat pixelFormat;
///【字段含义】视频数据结构类型
-///【推荐取值】TRTCVideoBufferType_PixelBuffer
-@property (nonatomic, assign) TRTCVideoBufferType bufferType;
+@property(nonatomic, assign) TRTCVideoBufferType bufferType;
-///【字段含义】bufferType 为 TRTCVideoBufferType_PixelBuffer 时的视频数据。
-@property (nonatomic, assign, nullable) CVPixelBufferRef pixelBuffer;
+///【字段含义】bufferType 为 {@link TRTCVideoBufferType_PixelBuffer} 时的视频数据，承载 iOS 平台专用的 PixelBuffer。
+@property(nonatomic, assign, nullable) CVPixelBufferRef pixelBuffer;
-///【字段含义】bufferType 为 TRTCVideoBufferType_NSData 时的视频数据。
-@property (nonatomic, retain, nullable) NSData* data;
+///【字段含义】bufferType 为 {@link TRTCVideoBufferType_NSData} 时的视频数据，承载 NSData 类型的内存数据块。
+@property(nonatomic, retain, nullable) NSData *data;
-///【字段含义】视频帧的时间戳，单位毫秒
-///【推荐取值】自定义视频采集时可以设置为0，若该参数为0，SDK 会自定填充 timestamp 字段，但请“均匀”地控制 sendCustomVideoData 的调用间隔。
-@property (nonatomic, assign) uint64_t timestamp;
+///【字段含义】视频纹理 ID,bufferType 为 {@link TRTCVideoBufferType_Texture} 时的视频数据，承载用于 OpenGL 渲染的纹理数据。
+@property(nonatomic, assign) GLuint textureId;
///【字段含义】视频宽度
-///【推荐取值】自定义视频采集时不需要填写。
-@property (nonatomic, assign) uint32_t width;
+@property(nonatomic, assign) uint32_t width;
///【字段含义】视频高度
-///【推荐取值】自定义视频采集时不需要填写。
-@property (nonatomic, assign) uint32_t height;
+@property(nonatomic, assign) uint32_t height;
-///【字段含义】视频像素的顺时针旋转角度
-@property (nonatomic, assign) TRTCVideoRotation rotation;
+///【字段含义】视频帧的时间戳，单位毫秒
+///【推荐取值】自定义视频采集时可以设置为0。若该参数为0，SDK 会自定填充 timestamp 字段，但请“均匀”地控制 sendCustomVideoData 的调用间隔。
+@property(nonatomic, assign) uint64_t timestamp;
-///【字段含义】视频纹理ID
-@property (nonatomic, assign) GLuint textureId;
+///【字段含义】视频像素的顺时针旋转角度
+@property(nonatomic, assign) TRTCVideoRotation rotation;
@end
-/**
- * 5.9 音频帧数据
+/**
+ * 5.10 音频帧数据
*/
-#pragma mark -
-/// 音频帧数据
@interface TRTCAudioFrame : NSObject
-/// 音频数据
-@property (nonatomic, retain, nonnull) NSData * data;
-/// 采样率
-@property (nonatomic, assign) TRTCAudioSampleRate sampleRate;
-/// 声道数
-@property (nonatomic, assign) int channels;
-/// 时间戳，单位ms
-@property (nonatomic, assign) uint64_t timestamp;
+
+///【字段含义】音频数据
+@property(nonatomic, retain, nonnull) NSData *data;
+
+///【字段含义】采样率
+@property(nonatomic, assign) TRTCAudioSampleRate sampleRate;
+
+///【字段含义】声道数
+@property(nonatomic, assign) int channels;
+
+///【字段含义】时间戳，单位ms
+@property(nonatomic, assign) uint64_t timestamp;
+
+///【字段含义】音频额外数据，远端用户通过 `onLocalProcessedAudioFrame` 写入的数据会通过该字段回调
+@property(nonatomic, retain, nullable) NSData *extraData;
@end
-/**
- * 5.10 云端混流中每一路子画面的位置信息
+/**
+ * 5.11 云端混流中各路画面的描述信息
*
- * TRTCMixUser 用于指定每一路（即每一个 userId）视频画面的具体摆放位置
+ * TRTCMixUser 用于指定云端混流中每一路视频画面的位置、大小、图层以及流类型等信息。
*/
@interface TRTCMixUser : NSObject
-/// 【字段含义】参与混流的 userId
-@property(nonatomic, copy, nonnull) NSString * userId;
-/// 【字段含义】混流的房间， 可填 nil 表示是自己所在的房间
-@property (nonatomic, copy, nullable) NSString * roomID;
-/// 【字段含义】图层位置坐标以及大小，左上角为坐标原点(0,0) （绝对像素值）
+
+///【字段含义】用户 ID
+@property(nonatomic, copy, nonnull) NSString *userId;
+
+///【字段含义】该路音视频流所在的房间号（设置为空值代表当前用户所在的房间号）
+@property(nonatomic, copy, nullable) NSString *roomID;
+
+///【字段含义】指定该路画面的坐标区域（单位：像素）
@property(nonatomic, assign) CGRect rect;
-/// 【字段含义】图层层次（1 - 15）不可重复
+
+///【字段含义】指定该路画面的层级（取值范围：1 - 15，不可重复）
@property(nonatomic, assign) int zOrder;
-/// 【字段含义】参与混合的是主路画面（TRTCVideoStreamTypeBig）或屏幕分享（TRTCVideoStreamTypeSub）画面
-@property (nonatomic) TRTCVideoStreamType streamType;
-/// 【字段含义】该用户是不是只开启了音频
-/// 【推荐取值】默认值：NO
-/// 【特别说明】废弃，推荐使用 inputType
-@property (nonatomic, assign) BOOL pureAudio;
-/// 【字段含义】该用户的输入流类型（该字段是对 pureAudio 字段的升级）
-/// 【推荐取值】
-/// - 默认值：TRTCMixInputTypeUndefined
-/// - 如果您没有对 pureAudio 字段进行设置，您可以根据实际需要设置该字段
-/// - 如果您已经设置了 pureAudio 为 YES，请设置该字段为 TRTCMixInputTypeUndefined
-@property (nonatomic, assign) TRTCMixInputType inputType;
+
+///【字段含义】指定该路画面是主路画面（{@link TRTCVideoStreamTypeBig}）还是辅路画面（{@link TRTCVideoStreamTypeSub}）。
+@property(nonatomic) TRTCVideoStreamType streamType;
+
+///【字段含义】指定该路流是不是只混合声音
+///【推荐取值】默认值：NO
+///【特别说明】已废弃，推荐使用8.5版本开始新引入的字段：inputType。
+@property(nonatomic, assign) BOOL pureAudio;
+
+///【字段含义】指定该路流的混合内容（只混合音频、只混合视频、混合音频和视频），该字段是对 pureAudio 字段的升级。
+///【推荐取值】默认值：TRTCMixInputTypeUndefined，代表参考 pureAudio 的取值。
+/// - 如果您是第一次使用 TRTC，之前并没有对 pureAudio 字段进行过设置，您可以根据实际需要设置该字段，不建议您再设置 pureAudio。
+/// - 如果您之前在老版本中已经使用了 pureAudio 字段，并期望保持其设置，则可以将 inputType 设置为 TRTCMixInputTypeUndefined。
+@property(nonatomic, assign) TRTCMixInputType inputType;
@end
-
+
/**
- * 5.11 云端混流（转码）配置
+ * 5.12 云端混流的排版布局和转码参数
*
- * 包括最终编码质量和各路画面的摆放位置
+ * 用于指定混流时各路画面的排版位置信息和云端转码的编码参数。
*/
@interface TRTCTranscodingConfig : NSObject
-///【字段含义】转码config模式
-@property(nonatomic, assign) TRTCTranscodingConfigMode mode;
+///【字段含义】排版模式
+///【推荐取值】请根据您的业务场景要求自行选择，预排版模式是适用性较好的一种模式。
+@property(nonatomic, assign) TRTCTranscodingConfigMode mode;
-///【字段含义】腾讯云直播 AppID
-///【推荐取值】请在 [实时音视频控制台](https://console.cloud.tencent.com/rav) 选择已经创建的应用，单击【帐号信息】后，在“直播信息”中获取
-@property (nonatomic) int appId;
+///【字段含义】腾讯云直播服务的 AppID
+///【推荐取值】请在 [实时音视频控制台](https://console.cloud.tencent.com/trtc) 依次单击【应用管理】=>【应用信息】，并在【旁路直播信息】中获取 appid。
+@property(nonatomic) int appId;
-///【字段含义】腾讯云直播 bizid
-///【推荐取值】请在 [实时音视频控制台](https://console.cloud.tencent.com/rav) 选择已经创建的应用，单击【帐号信息】后，在“直播信息”中获取
-@property (nonatomic) int bizId;
+///【字段含义】腾讯云直播服务的 bizid
+///【推荐取值】请在 [实时音视频控制台](https://console.cloud.tencent.com/trtc) 依次单击【应用管理】=>【应用信息】，并在【旁路直播信息】中获取 bizid。
+@property(nonatomic) int bizId;
-///【字段含义】最终转码后的视频分辨率的宽度。
-///【推荐取值】推荐值：360px ，如果你是纯音频推流，请将 width × height 设为 0px × 0px，否则混流后会携带一条画布背景的视频流。
-@property(nonatomic, assign) int videoWidth;
+///【字段含义】指定云端转码的目标分辨率（宽度）
+///【推荐取值】单位：像素值，推荐值：360，如果你只混合音频流，请将 width 和 height 均设置位 0，否则混流转码后的直播流中会有黑色背景。
+@property(nonatomic, assign) int videoWidth;
-///【字段含义】最终转码后的视频分辨率的高度。
-///【推荐取值】推荐值：640px ，如果你是纯音频推流，请将 width × height 设为 0px × 0px，否则混流后会携带一条画布背景的视频流。
-@property(nonatomic, assign) int videoHeight;
+///【字段含义】指定云端转码的目标分辨率（高度）
+///【推荐取值】单位：像素值，推荐值：640，如果你只混合音频流，请将 width 和 height 均设置位 0，否则混流转码后的直播流中会有黑色背景。
+@property(nonatomic, assign) int videoHeight;
-///【字段含义】最终转码后的视频分辨率的码率（kbps）。
-///【推荐取值】如果填0，后台会根据videoWidth和videoHeight来估算码率，您也可以参考枚举定义TRTCVideoResolution_640_480的注释。
-@property(nonatomic, assign) int videoBitrate;
+///【字段含义】指定云端转码的目标视频码率（kbps）
+///【推荐取值】如果填0，TRTC 会根据 videoWidth 和 videoHeight 估算出一个合理的码率值，您也可以参考视频分辨率枚举定义中所推荐的码率值（见注释部分）。
+@property(nonatomic, assign) int videoBitrate;
-///【字段含义】最终转码后的视频分辨率的帧率（FPS）。
+///【字段含义】指定云端转码的目标视频帧率（FPS）
///【推荐取值】默认值：15fps，取值范围是 (0,30]。
-@property(nonatomic, assign) int videoFramerate;
+@property(nonatomic, assign) int videoFramerate;
-///【字段含义】最终转码后的视频分辨率的关键帧间隔（又称为 GOP）。
+///【字段含义】指定云端转码的目标视频关键帧间隔（GOP）
///【推荐取值】默认值：2，单位为秒，取值范围是 [1,8]。
-@property(nonatomic, assign) int videoGOP;
+@property(nonatomic, assign) int videoGOP;
-///【字段含义】混合后画面的底色颜色，默认为黑色，格式为十六进制数字，比如：“0x61B9F1” 代表 RGB 分别为(97,158,241)。
-///【推荐取值】默认值：0x000000，黑色
+///【字段含义】指定混合画面的底色颜色
+///【推荐取值】默认值：0x000000 代表黑色。格式为十六进制数字，比如：“0x61B9F1” 代表 RGB 分别为(97,158,241)。
@property(nonatomic, assign) int backgroundColor;
-///【字段含义】混合后画面的背景图。
-///【推荐取值】默认值：nil，即不设置背景图
-///【特别说明】背景图需要您事先在 “[控制台](https://console.cloud.tencent.com/trtc) => 应用管理 => 功能配置 => 素材管理” 中上传，
-/// 上传成功后可以获得对应的“图片ID”，然后将“图片ID”转换成字符串类型并设置到 backgroundImage 里即可。
-/// 例如：假设“图片ID” 为 63，可以设置 backgroundImage = @"63";
+///【字段含义】指定混合画面的背景图片
+///【推荐取值】默认值：空值，即不设置背景图片。
+///【特别说明】背景图需要您事先在 “[控制台](https://console.cloud.tencent.com/trtc) => 应用管理 => 功能配置 => 素材管理” 中单击【新增图片】按钮进行上传。
+/// 上传成功后可以获得对应的“图片ID”，然后将“图片ID”转换成字符串类型并设置到 backgroundImage 里即可。
+/// 例如：假设“图片ID” 为 63，可以设置 backgroundImage = @"63";
@property(nonatomic, copy, nullable) NSString *backgroundImage;
-///【字段含义】最终转码后的音频采样率。
+///【字段含义】指定云端转码的目标音频采样率
///【推荐取值】默认值：48000Hz。支持12000HZ、16000HZ、22050HZ、24000HZ、32000HZ、44100HZ、48000HZ。
-@property(nonatomic, assign) int audioSampleRate;
+@property(nonatomic, assign) int audioSampleRate;
-///【字段含义】最终转码后的音频码率。
+///【字段含义】指定云端转码的目标音频码率
///【推荐取值】默认值：64kbps，取值范围是 [32，192]。
-@property(nonatomic, assign) int audioBitrate;
+@property(nonatomic, assign) int audioBitrate;
-///【字段含义】最终转码后的音频声道数
-///【推荐取值】默认值：1。取值范围为 [1,2] 中的整型。
-@property(nonatomic, assign) int audioChannels;
+///【字段含义】指定云端转码的音频声道数
+///【推荐取值】默认值：1，代表单声道。可设定的数值只有两个数字：1-单声道，2-双声道。
+@property(nonatomic, assign) int audioChannels;
-///【字段含义】每一路子画面的位置信息
-@property(nonatomic, copy, nonnull) NSArray<TRTCMixUser *> * mixUsers;
+///【字段含义】指定云端混流中每一路视频画面的位置、大小、图层以及流类型等信息
+///【推荐取值】该字段是一个 TRTCMixUser 类型的数组，数组中的每一个元素都用来代表每一路画面的信息。
+@property(nonatomic, copy, nonnull) NSArray<TRTCMixUser *> *mixUsers;
///【字段含义】输出到 CDN 上的直播流 ID
-/// 如不设置该参数，SDK 会执行默认逻辑，即房间里的多路流会混合到该接口调用者的视频流上，也就是 A+B =>A；
-/// 如果设置该参数，SDK 会将房间里的多路流混合到您指定的直播流 ID 上，也就是 A+B =>C。
-///【推荐取值】默认值：nil，即房间里的多路流会混合到该接口调用者的视频流上。
+///【推荐取值】默认值：空值，即房间里的多路音视频流最终会混合到接口调用者的那一路音视频流上。
+/// - 如不设置该参数，SDK 会执行默认逻辑，即房间里的多路音视频流会混合到该接口调用者的那一路音视频流上，也就是 A + B => A。
+/// - 如您设置该参数，SDK 会将房间里的多路音视频流混合到您指定的直播流上，也就是 A + B => C（C 代表您指定的 streamId）。
@property(nonatomic, copy, nullable) NSString *streamId;
@end
-#pragma mark -
-
-/**
- * 5.12 CDN 旁路推流参数
+/**
+ * 5.13 向非腾讯云 CDN 上发布音视频流时需设置的转推参数
+ *
+ * TRTC 的后台服务支持通过标准 RTMP 协议，将其中的音视频流发布到第三方直播 CDN 服务商。
+ * 如果您使用腾讯云直播 CDN 服务，可无需关注此参数，直接使用 {@link startPublish} 接口即可。
*/
@interface TRTCPublishCDNParam : NSObject
-/// 腾讯云 AppID，请在 [实时音视频控制台](https://console.cloud.tencent.com/rav) 选择已经创建的应用，单击【帐号信息】，在“直播信息”中获取
-@property (nonatomic) int appId;
-/// 腾讯云直播 bizid，请在 [实时音视频控制台](https://console.cloud.tencent.com/rav) 选择已经创建的应用，单击【帐号信息】，在“直播信息”中获取
-@property (nonatomic) int bizId;
+///【字段含义】腾讯云直播服务的 AppID
+///【推荐取值】请在 [实时音视频控制台](https://console.cloud.tencent.com/trtc) 依次单击【应用管理】=>【应用信息】，并在【旁路直播信息】中获取 appid。
+@property(nonatomic) int appId;
+
+///【字段含义】腾讯云直播服务的 bizid
+///【推荐取值】请在 [实时音视频控制台](https://console.cloud.tencent.com/trtc) 依次单击【应用管理】=>【应用信息】，并在【旁路直播信息】中获取 bizid。
+@property(nonatomic) int bizId;
+
+///【字段含义】指定该路音视频流在第三方直播服务商的推流地址（RTMP 格式）
+///【推荐取值】各家服务商的推流地址规则差异较大，请根据目标服务商的要求填写合法的推流 URL，TRTC 的后台服务器会按照您填写的 URL 向第三方服务商推送标准格式音视频流。
+///【特别说明】推流 URL 必须为 RTMP 格式，必须符合您的目标直播服务商的规范要求，否则目标服务商会拒绝来自 TRTC 后台服务的推流请求。
+@property(nonatomic, strong, nonnull) NSString *url;
-/// 旁路转推的 URL
-@property (nonatomic, strong, nonnull) NSString * url;
@end
/**
- * 5.13 录音参数
+ * 5.14 本地音频文件的录制参数
*
- * 请正确填写参数，确保录音文件顺利生成。
+ * 该参数用于在音频录制接口 {@link startAudioRecording} 中指定录制参数。
*/
@interface TRTCAudioRecordingParams : NSObject
-///【字段含义】文件路径（必填），录音文件的保存路径。该路径需要用户自行指定，请确保路径存在且可写。
-///【特别说明】该路径需精确到文件名及格式后缀，格式后缀决定录音文件的格式，目前支持的格式有 PCM、WAV 和 AAC。
-/// 例如，指定路径为 path/to/audio.aac，则会生成一个 AAC 格式的文件。
-/// 请指定一个有读写权限的合法路径，否则录音文件无法生成。
-@property (nonatomic, strong, nonnull) NSString * filePath;
+///【字段含义】录音文件的保存路径（必填）。
+///【特别说明】该路径需精确到文件名及格式后缀，格式后缀用于决定录音文件的格式，目前支持的格式有 PCM、WAV 和 AAC。
+/// 例如：假如您指定路径为 "mypath/record/audio.aac"，代表您希望 SDK 生成一个 AAC 格式的音频录制文件。
+/// 请您指定一个有读写权限的合法路径，否则录音文件无法生成。
+@property(nonatomic, strong, nonnull) NSString *filePath;
+
+///【字段含义】音频录制内容类型。
+///【特别说明】默认录制所有本地和远端音频。
+@property(nonatomic, assign) TRTCAudioRecordingContent recordingContent;
+
@end
/**
- * 5.14 音效
+ * 5.15 本地媒体文件的录制参数
*
+ * 该参数用于在本地媒体文件的录制接口 {@link startLocalRecording} 中指定录制相关参数。
+ * 接口 startLocalRecording 是接口 startAudioRecording 的能力加强版本，前者可以录制视频文件，后者只能录制音频文件。
+ */
+@interface TRTCLocalRecordingParams : NSObject
+
+///【字段含义】录制的文件地址（必填），请确保路径有读写权限且合法，否则录制文件无法生成。
+///【特别说明】该路径需精确到文件名及格式后缀，格式后缀用于决定录制出的文件格式，目前支持的格式暂时只有 MP4。
+/// 例如：假如您指定路径为 "mypath/record/test.mp4"，代表您希望 SDK 生成一个 MP4 格式的本地视频文件。
+/// 请您指定一个有读写权限的合法路径，否则录制文件无法生成。
+@property(nonatomic, copy, nonnull) NSString *filePath;
+
+///【字段含义】媒体录制类型，默认值：TRTCRecordTypeBoth，即同时录制音频和视频。
+@property(nonatomic, assign) TRTCRecordType recordType;
+
+///【字段含义】interval 录制信息更新频率，单位毫秒，有效范围：1000-10000。默认值为-1，表示不回调。
+@property(nonatomic, assign) int interval;
+
+@end
+
+/**
+ * 5.16 音效参数（已废弃）
+ *
+ * TRTC 中的“音效”特指一些短暂的音频文件，通常仅有几秒钟的播放时间，比如“鼓掌声”、“欢笑声”等。
+ * 该参数用于在早期版本的音效播放接口 {@link TRTCCloud#playAudioEffect} 中指定音效文件（即短音频文件）的路径和播放次数等。
+ * 在 7.3 版本以后，音效接口已被新的接口 {@link TXAudioEffectManager#startPlayMusic} 所取代。
+ * 您在指定 startPlayMusic 的参数 {@link TXAudioMusicParam} 时，如果将 “isShortFile” 设置为 true，即为“音效”文件。
*/
@interface TRTCAudioEffectParam : NSObject
-+ (_Nonnull instancetype)new __attribute__((unavailable("Use -initWith:(int)effectId path:(NSString * )path instead")));
++ (_Nonnull instancetype)new __attribute__((unavailable("Use -initWith:(int)effectId path:(NSString * )path instead")));
- (_Nonnull instancetype)init __attribute__((unavailable("Use -initWith:(int)effectId path:(NSString *)path instead")));
-/// 【字段含义】音效 ID
-/// 【特别说明】SDK 允许播放多路音效，因此需要音效 ID 进行标记，用于控制音效的开始、停止、音量等
+///【字段含义】音效 ID
+///【特别说明】SDK 允许播放多路音效，因此需要音效 ID 进行标记，用于控制音效的开始、停止、音量等。
@property(nonatomic, assign) int effectId;
-/// 【字段含义】音效文件路径，支持的文件格式：aac, mp3, m4a。
-@property(nonatomic, copy, nonnull) NSString * path;
+///【字段含义】音效文件路径，支持的文件格式：aac, mp3, m4a。
+@property(nonatomic, copy, nonnull) NSString *path;
-/// 【字段含义】循环播放次数
-/// 【推荐取值】取值范围为0 - 任意正整数，默认值：0。0表示播放音效一次；1表示播放音效两次；以此类推
+///【字段含义】循环播放次数
+///【推荐取值】取值范围为0 - 任意正整数，默认值：0，表示播放音效一次；1表示播放音效两次；以此类推。
@property(nonatomic, assign) int loopCount;
-/// 【字段含义】音效是否上行
-/// 【推荐取值】YES：音效在本地播放的同时，会上行至云端，因此远端用户也能听到该音效；NO：音效不会上行至云端，因此只能在本地听到该音效。默认值：NO
+///【字段含义】音效是否上行
+///【推荐取值】YES：音效在本地播放的同时，会上行至云端，因此远端用户也能听到该音效；NO：音效不会上行至云端，因此只能在本地听到该音效。默认值：NO
@property(nonatomic, assign) BOOL publish;
-/// 【字段含义】音效音量
-/// 【推荐取值】取值范围为0 - 100；默认值：100
+///【字段含义】音效音量
+///【推荐取值】取值范围为0 - 100；默认值：100
@property(nonatomic, assign) int volume;
-- (_Nonnull instancetype)initWith:(int)effectId path:(NSString * _Nonnull)path;
+- (_Nonnull instancetype)initWith:(int)effectId path:(NSString *_Nonnull)path;
@end
-#pragma mark -
/**
- * 5.15 切换房间
+ * 5.17 房间切换参数
+ *
+ * 该参数用于切换房间接口{@link switchRoom}，可以让用户从一个房间快速切换到另一个房间。
*/
@interface TRTCSwitchRoomConfig : NSObject
-///【字段含义】数字房间号码 [选填]，在同一个房间内的用户可以看到彼此并进行视频通话。
+///【字段含义】数字房间号码 [选填]，在同一个房间内的用户可以看到彼此并能够进行音视频通话。
///【推荐取值】取值范围：1 - 4294967294。
///【特别说明】roomId 和 strRoomId 必须并且只能填一个。若两者都填，则优先选择 roomId。
-@property (nonatomic, assign) UInt32 roomId;
+@property(nonatomic, assign) UInt32 roomId;
-///【字段含义】字符串房间号码 [选填]，在同一个房间内的用户可以看到彼此并进行视频通话。
+///【字段含义】字符串房间号码 [选填]，在同一个房间内的用户可以看到彼此并能够进行音视频通话。
///【特别说明】roomId 和 strRoomId 必须并且只能填一个。若两者都填，则优先选择 roomId。
-@property (nonatomic, copy, nullable) NSString *strRoomId;
+@property(nonatomic, copy, nullable) NSString *strRoomId;
-///【字段含义】用户签名 [选填]，当前 userId 对应的验证签名，相当于登录密码。不填时，SDK 会继续使用旧的 userSig，
-/// 但用户必须保证旧的 userSig 仍在有效期内，否则会造成进房失败等后果。
-///【推荐取值】具体计算方法请参见 [如何计算UserSig](https://cloud.tencent.com/document/product/647/17275)。
-@property (nonatomic, copy, nullable) NSString *userSig;
+///【字段含义】用户签名 [选填]，当前 userId 对应的验证签名，相当于登录密码。
+/// 如果您在切换房间时不指定新计算出的 userSig，SDK 会继续使用您在进入房间时（enterRoom）时所指定的 userSig。
+/// 这就需要您必须保证旧的 userSig 在切换房间的那一刻仍在签名允许的效期内，否则会导致房间切换失败。
+///【推荐取值】具体计算方法请参考 [如何计算UserSig](https://cloud.tencent.com/document/product/647/17275)。
+@property(nonatomic, copy, nullable) NSString *userSig;
-///【字段含义】房间签名 [选填]，当您希望某个房间只能让特定的 userId 进入时，需要使用 privateMapKey 进行权限保护。
+///【字段含义】用于权限控制的权限票据（选填），当您希望某个房间只能让特定的 userId 进入时，需要使用 privateMapKey 进行权限保护。
///【推荐取值】仅建议有高级别安全需求的客户使用，更多详情请参见 [进房权限保护](https://cloud.tencent.com/document/product/647/32240)。
-@property (nonatomic, copy, nullable) NSString *privateMapKey;
+@property(nonatomic, copy, nullable) NSString *privateMapKey;
@end
-
-typedef NS_ENUM(NSUInteger, TRTCLocalVideoMirrorType) {
- TRTCLocalVideoMirrorType_Auto = TRTCVideoMirrorTypeAuto,
- TRTCLocalVideoMirrorType_Enable = TRTCVideoMirrorTypeEnable,
- TRTCLocalVideoMirrorType_Disable = TRTCVideoMirrorTypeDisable,
-} __attribute__((deprecated("use TRTCVideoMirrorType instead")));
-
/**
- * 5.16 本地媒体文件录制参数
+ * 5.18 音频自定义回调的格式参数
*
- * 请正确填写参数，确保录制文件顺利生成。
+ * 该参数用于在音频自定义回调相关的接口中，设置 SDK 回调出来的音频数据的相关格式（包括采样率、声道数等）。
*/
-@interface TRTCLocalRecordingParams : NSObject
+@interface TRTCAudioFrameDelegateFormat : NSObject
-///【字段含义】文件路径（必填），录制的文件地址，请自行指定，确保路径有读写权限且合法，否则录制文件无法生成。
-///【特别说明】该路径需精确到文件名及格式后缀，格式后缀决定录制文件的格式，目前支持的格式只有 mp4。
-/// iOS建议在沙盒目录 Document或Library/Caches 中指定存放路径。
-///【示例代码】在cache目录下录制 example.mp4 文件
-/// NSArray * path = NSSearchPathForDirectoriesInDomains(NSCachesDirectory, NSUserDomainMask, YES);
-/// NSString * cachePath = [path lastObject];
-/// NSString * filePath = [cachePath stringByAppendingPathComponent:@"example.mp4"];
-@property(nonatomic, copy, nonnull) NSString *filePath;
+///【字段含义】采样率
+///【推荐取值】默认值：48000Hz。支持 16000, 32000, 44100, 48000。
+@property(nonatomic, assign) TRTCAudioSampleRate sampleRate;
-///【字段含义】媒体录制类型，默认值：TRTCRecordTypeBoth，为同时录制音频和视频。
-@property(nonatomic, assign) TRTCRecordType recordType;
+///【字段含义】声道数
+///【推荐取值】默认值：1，代表单声道。可设定的数值只有两个数字：1-单声道，2-双声道。
+@property(nonatomic, assign) int channels;
-///interval 录制信息更新频率，单位毫秒，有效范围：1000-10000。默认值为-1，表示不回调。
-@property(nonatomic, assign) int interval;
+///【字段含义】采样点数
+///【推荐取值】取值必须是 sampleRate/100 的整数倍。
+@property(nonatomic, assign) int samplesPerCall;
@end
-#if TARGET_OS_MAC && !TARGET_OS_IPHONE
-#pragma mark -
/**
- * 设备类型（仅 Mac）
+ * 5.20 屏幕分享的目标信息（仅适用于桌面系统）
*
- * @deprecated
- * 在 Mac 上，每一种类型的设备都可能有多个，TRTC SDK 的 Mac 版本提供了一系列函数用来操作这些设备。
+ * 在用户进行屏幕分享时，可以选择抓取整个桌面，也可以仅抓取某个程序的窗口。
+ * TRTCScreenCaptureSourceInfo 用于描述待分享目标的信息，包括 ID、名称、缩略图等，该结构体中的字段信息均是只读的。
*/
-typedef NS_ENUM(NSInteger, TRTCMediaDeviceType) {
- TRTCMediaDeviceTypeUnknown = -1, ///< 未定义
-
- TRTCMediaDeviceTypeAudioInput = 0, ///< 麦克风
- TRTCMediaDeviceTypeAudioOutput = 1, ///< 扬声器或听筒
- TRTCMediaDeviceTypeVideoCamera = 2, ///< 摄像头
+#if TARGET_OS_MAC && !TARGET_OS_IPHONE
+@interface TRTCScreenCaptureSourceInfo : NSObject
- TRTCMediaDeviceTypeVideoWindow = 3, ///< 某个窗口（用于屏幕分享）
- TRTCMediaDeviceTypeVideoScreen = 4, ///< 整个屏幕（用于屏幕分享）
-} __attribute__((deprecated("use TXMediaDeviceType instead")));
+///【字段含义】采集源类型（是分享整个屏幕？还是分享某个窗口？）
+@property(assign, nonatomic) TRTCScreenCaptureSourceType type;
-/**
- * 媒体设备描述
- *
- * @deprecated
- * 在 Mac 上，每一种类型的设备都可能有多个，TRTC SDK 的 Mac 版本提供了一系列函数用来操作这些设备。
- */
-typedef TXMediaDeviceInfo TRTCMediaDeviceInfo __attribute__((deprecated("use TXMediaDeviceInfo instead")));
+///【字段含义】采集源的ID，对于窗口，该字段代表窗口的 ID；对于屏幕，该字段代表显示器的 ID。
+@property(copy, nonatomic, nullable) NSString *sourceId;
+///【字段含义】采集源名称（采用 UTF8 编码）
+@property(copy, nonatomic, nullable) NSString *sourceName;
+
+///【字段含义】窗口的扩展信息
+@property(nonatomic, strong, nullable) NSDictionary *extInfo;
+
+///【字段含义】分享窗口的缩略图
+@property(nonatomic, readonly, nullable) NSImage *thumbnail;
+
+///【字段含义】分享窗口的图标
+@property(nonatomic, readonly, nullable) NSImage *icon;
+
+@end
#endif
/// @}
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TRTCCloudDelegate.h b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TRTCCloudDelegate.h
index 842c86d..5351514 100644
--- a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TRTCCloudDelegate.h
+++ b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TRTCCloudDelegate.h
@@ -1,10 +1,10 @@
-/*
+/**
* Module: TRTCCloudDelegate @ TXLiteAVSDK
- *
- * Function: 腾讯云视频通话功能的事件回调接口
- *
+ * Function: 腾讯云实时音视频的事件回调接口
*/
-
+/// @defgroup TRTCCloudDelegate_ios TRTCCloudDelegate
+/// 腾讯云实时音视频的事件回调接口
+/// @{
#import <Foundation/Foundation.h>
#import "TRTCCloudDef.h"
#import "TXLiteAVCode.h"
@@ -14,58 +14,61 @@ NS_ASSUME_NONNULL_BEGIN
@class TRTCCloud;
@class TRTCStatistics;
-
-/// @defgroup TRTCCloudDelegate_ios TRTCCloudDelegate
-/// 腾讯云视频通话功能的事件回调接口
-/// @{
@protocol TRTCCloudDelegate <NSObject>
@optional
/////////////////////////////////////////////////////////////////////////////////
//
-// （一）错误事件和警告事件
+// 错误和警告事件
//
/////////////////////////////////////////////////////////////////////////////////
-/// @name 错误事件和警告事件
+/// @name 错误和警告事件
/// @{
+
/**
- * 1.1 错误回调，表示 SDK 不可恢复的错误，一定要监听并分情况给用户适当的界面提示。
+ * 1.1 错误事件回调
+ *
+ * 错误事件，表示 SDK 抛出的不可恢复的错误，比如进入房间失败或设备开启失败等。
+ * 参考文档：[错误码表](https://cloud.tencent.com/document/product/647/32257)
*
* @param errCode 错误码
* @param errMsg 错误信息
* @param extInfo 扩展信息字段，个别错误码可能会带额外的信息帮助定位问题
*/
-- (void)onError:(TXLiteAVError)errCode errMsg:(nullable NSString *)errMsg extInfo:(nullable NSDictionary*)extInfo;
+- (void)onError:(TXLiteAVError)errCode errMsg:(nullable NSString *)errMsg extInfo:(nullable NSDictionary *)extInfo;
/**
- * 1.2 警告回调，用于告知您一些非严重性问题，例如出现了卡顿或者可恢复的解码失败。
+ * 1.2 警告事件回调
+ *
+ * 警告事件，表示 SDK 抛出的提示性问题，比如视频出现卡顿或 CPU 使用率太高等。
+ * 参考文档：[错误码表](https://cloud.tencent.com/document/product/647/32257)
*
* @param warningCode 警告码
* @param warningMsg 警告信息
* @param extInfo 扩展信息字段，个别警告码可能会带额外的信息帮助定位问题
*/
-- (void)onWarning:(TXLiteAVWarning)warningCode warningMsg:(nullable NSString *)warningMsg extInfo:(nullable NSDictionary*)extInfo;
+- (void)onWarning:(TXLiteAVWarning)warningCode warningMsg:(nullable NSString *)warningMsg extInfo:(nullable NSDictionary *)extInfo;
/// @}
-
/////////////////////////////////////////////////////////////////////////////////
//
-// （二）房间事件回调
+// 房间相关事件回调
//
/////////////////////////////////////////////////////////////////////////////////
-/// @name 房间事件回调
+/// @name 房间相关事件回调
/// @{
+
/**
- * 2.1 已加入房间的回调
+ * 2.1 进入房间成功与否的事件回调
*
- * 调用 TRTCCloud 中的 enterRoom() 接口执行进房操作后，会收到来自 SDK 的 onEnterRoom(result) 回调：
+ * 调用 TRTCCloud 中的 enterRoom() 接口执行进房操作后，会收到来自 TRTCCloudDelegate 的 onEnterRoom(result) 回调：
+ * - 如果加入成功，回调 result 会是一个正数（result > 0），代表进入房间所消耗的时间，单位是毫秒（ms）。
+ * - 如果加入失败，回调 result 会是一个负数（result < 0），代表失败原因的错误码。
+ * 进房失败的错误码含义请参见[错误码表](https://cloud.tencent.com/document/product/647/32257)。
*
- * - 如果加入成功，result 会是一个正数（result > 0），代表加入房间的时间消耗，单位是毫秒（ms）。
- * - 如果加入失败，result 会是一个负数（result < 0），代表进房失败的错误码。
- * 进房失败的错误码含义请参见[错误码](https://cloud.tencent.com/document/product/647/32257)。
- *
- * @note 在 Ver6.6 之前的版本，只有进房成功会抛出 onEnterRoom(result) 回调，进房失败由 onError() 回调抛出。
- * 在 Ver6.6 及之后改为：进房成功返回正的 result，进房失败返回负的 result，同时进房失败也会有 onError() 回调抛出。
+ * @note
+ * 1. 在 Ver6.6 之前的版本，只有进房成功会抛出 onEnterRoom(result) 回调，进房失败由 onError() 回调抛出。
+ * 2. 在 Ver6.6 之后的版本：无论进房成功或失败，均会抛出 onEnterRoom(result) 回调，同时进房失败也会有 onError() 回调抛出。
*
* @param result result > 0 时为进房耗时（ms），result < 0 时为进房错误码。
*/
@@ -75,12 +78,12 @@ NS_ASSUME_NONNULL_BEGIN
* 2.2 离开房间的事件回调
*
* 调用 TRTCCloud 中的 exitRoom() 接口会执行退出房间的相关逻辑，例如释放音视频设备资源和编解码器资源等。
- * 待资源释放完毕，SDK 会通过 onExitRoom() 回调通知到您。
+ * 待 SDK 占用的所有资源释放完毕后，SDK 会抛出 onExitRoom() 回调通知到您。
*
- * 如果您要再次调用 enterRoom() 或者切换到其他的音视频 SDK，请等待 onExitRoom() 回调到来之后再执行相关操作。
- * 否则可能会遇到音频设备（例如 iOS 里的 AudioSession）被占用等各种异常问题。
+ * 如果您要再次调用 enterRoom() 或者切换到其他的音视频 SDK，请等待 onExitRoom() 回调到来后再执行相关操作。
+ * 否则可能会遇到例如摄像头、麦克风设备被强占等各种异常问题。
*
- * @param reason 离开房间原因，0：主动调用 exitRoom 退房；1：被服务器踢出当前房间；2：当前房间整个被解散。
+ * @param reason 离开房间原因，0：主动调用 exitRoom 退出房间；1：被服务器踢出当前房间；2：当前房间整个被解散。
*/
- (void)onExitRoom:(NSInteger)reason;
@@ -96,320 +99,370 @@ NS_ASSUME_NONNULL_BEGIN
- (void)onSwitchRole:(TXLiteAVError)errCode errMsg:(nullable NSString *)errMsg;
/**
- * 2.4 请求跨房通话（主播 PK）的结果回调
+ * 2.4 切换房间的结果回调
*
- * 调用 TRTCCloud 中的 connectOtherRoom() 接口会将两个不同房间中的主播拉通视频通话，也就是所谓的“主播PK”功能。
- * 调用者会收到 onConnectOtherRoom() 回调来获知跨房通话是否成功，
- * 如果成功，两个房间中的所有用户都会收到 PK 主播的 onUserVideoAvailable() 回调。
+ * 调用 TRTCCloud 中的 switchRoom() 接口可以让用户快速地从一个房间切换到另一个房间，
+ * 待 SDK 切换完成后，会抛出 onSwitchRoom() 事件回调。
*
- * @param userId 要 PK 的目标主播 userid。
* @param errCode 错误码，ERR_NULL 代表切换成功，其他请参见[错误码](https://cloud.tencent.com/document/product/647/32257)。
* @param errMsg 错误信息。
*/
-- (void)onConnectOtherRoom:(NSString*)userId errCode:(TXLiteAVError)errCode errMsg:(nullable NSString *)errMsg;
+- (void)onSwitchRoom:(TXLiteAVError)errCode errMsg:(nullable NSString *)errMsg;
/**
- * 2.5 结束跨房通话（主播 PK）的结果回调
+ * 2.5 请求跨房通话的结果回调
+ *
+ * 调用 TRTCCloud 中的 connectOtherRoom() 接口会将两个不同房间中的主播拉通视频通话，也就是所谓的“主播PK”功能。
+ * 调用者会收到 onConnectOtherRoom() 回调来获知跨房通话是否成功，
+ * 如果成功，两个房间中的所有用户都会收到来自另一个房间中的 PK 主播的 onUserVideoAvailable() 回调。
+ *
+ * @param userId 要跨房通话的另一个房间中的主播的用户 ID。
+ * @param errCode 错误码，ERR_NULL 代表切换成功，其他请参见[错误码](https://cloud.tencent.com/document/product/647/32257)。
+ * @param errMsg 错误信息。
*/
-- (void)onDisconnectOtherRoom:(TXLiteAVError)errCode errMsg:(nullable NSString *)errMsg;
+- (void)onConnectOtherRoom:(NSString *)userId errCode:(TXLiteAVError)errCode errMsg:(nullable NSString *)errMsg;
/**
- * 2.6 切换房间 (switchRoom) 的结果回调
+ * 2.6 结束跨房通话的结果回调
*/
-- (void)onSwitchRoom:(TXLiteAVError)errCode errMsg:(nullable NSString *)errMsg;
+- (void)onDisconnectOtherRoom:(TXLiteAVError)errCode errMsg:(nullable NSString *)errMsg;
/// @}
-
/////////////////////////////////////////////////////////////////////////////////
//
-// （三）成员事件回调
+// 用户相关事件回调
//
/////////////////////////////////////////////////////////////////////////////////
-/// @name 成员事件回调
+/// @name 用户相关事件回调
/// @{
/**
* 3.1 有用户加入当前房间
*
- * 出于性能方面的考虑，在两种不同的应用场景下，该通知的行为会有差别：
- * - 通话场景（TRTCAppSceneVideoCall 和 TRTCAppSceneAudioCall）：该场景下用户没有角色的区别，任何用户进入房间都会触发该通知。
- * - 直播场景（TRTCAppSceneLIVE 和 TRTCAppSceneVoiceChatRoom）：该场景不限制观众的数量，如果任何用户进出都抛出回调会引起很大的性能损耗，所以该场景下只有主播进入房间时才会触发该通知，观众进入房间不会触发该通知。
+ * 出于性能方面的考虑，在 TRTC 两种不同的应用场景（即 AppScene，在 enterRoom 时通过第二个参数指定）下，该通知的行为会有差别：
+ * - 直播类场景（TRTCAppSceneLIVE 和 TRTCAppSceneVoiceChatRoom）：该场景下的用户区分主播和观众两种角色，只有主播进入房间时才会触发该通知，观众进入房间时不会触发该通知。
+ * - 通话类场景（TRTCAppSceneVideoCall 和 TRTCAppSceneAudioCall）：该场景下的用户没有角色的区分（可认为都是主播），任何用户进入房间都会触发该通知。
*
- *
- * @note 注意 onRemoteUserEnterRoom 和 onRemoteUserLeaveRoom 只适用于维护当前房间里的“成员列表”，如果需要显示远程画面，建议使用监听 onUserVideoAvailable() 事件回调。
- *
- * @param userId 用户标识
+ * @note
+ * 1. 事件回调 onRemoteUserEnterRoom 和 onRemoteUserLeaveRoom 只适用于维护当前房间里的“用户列表”，有此事件回调不代表一定有视频画面。
+ * 2. 如果需要显示远程画面，请监听代表某个用户是否有视频画面的 onUserVideoAvailable() 事件回调。
+ * @param userId 远端用户的用户标识
*/
- (void)onRemoteUserEnterRoom:(NSString *)userId;
/**
* 3.2 有用户离开当前房间
*
- * 与 onRemoteUserEnterRoom 相对应，在两种不同的应用场景下，该通知的行为会有差别：
- * - 通话场景（TRTCAppSceneVideoCall 和 TRTCAppSceneAudioCall）：该场景下用户没有角色的区别，任何用户的离开都会触发该通知。
- * - 直播场景（TRTCAppSceneLIVE 和 TRTCAppSceneVoiceChatRoom）：只有主播离开房间时才会触发该通知，观众离开房间不会触发该通知。
+ * 与 onRemoteUserEnterRoom 相对应，在两种不同的应用场景（即 AppScene，在 enterRoom 时通过第二个参数指定）下，该通知的行为会有差别：
+ * - 直播类场景（TRTCAppSceneLIVE 和 TRTCAppSceneVoiceChatRoom）：只有主播离开房间时才会触发该通知，观众离开房间不会触发该通知。
+ * - 通话类场景（TRTCAppSceneVideoCall 和 TRTCAppSceneAudioCall）：该场景下用户没有角色的区别，任何用户的离开都会触发该通知。
*
- * @param userId 用户标识
- * @param reason 离开原因，0 表示用户主动退出房间，1 表示用户超时退出，2 表示被踢出房间。
+ * @param userId 远端用户的用户标识
+ * @param reason 离开原因，0表示用户主动退出房间，1表示用户超时退出，2表示被踢出房间。
*/
- (void)onRemoteUserLeaveRoom:(NSString *)userId reason:(NSInteger)reason;
/**
- * 3.3 远端用户是否存在可播放的主路画面（一般用于摄像头）
+ * 3.3 某远端用户发布/取消了主路视频画面
*
- * 当您收到 onUserVideoAvailable(userid, YES) 通知时，表示该路画面已经有可用的视频数据帧到达。
- * 此时，您需要调用 startRemoteView(userid) 接口加载该用户的远程画面。
- * 然后，您会收到名为 onFirstVideoFrame(userid) 的首帧画面渲染回调。
+ * “主路画面”一般被用于承载摄像头画面。当您收到 onUserVideoAvailable(userId, true) 通知时，表示该路画面已经有可播放的视频帧到达。
+ * 此时，您需要调用 {@link startRemoteView} 接口订阅该用户的远程画面，订阅成功后，您会继续收到该用户的首帧画面渲染回调 onFirstVideoFrame(userid)。
*
- * 当您收到 onUserVideoAvailable(userid, NO) 通知时，表示该路远程画面已被关闭，
- * 可能由于该用户调用了 muteLocalVideo() 或 stopLocalPreview()。
+ * 当您收到 onUserVideoAvailable(userId, false) 通知时，表示该路远程画面已经被关闭，关闭的原因可能是该用户调用了 {@link muteLocalVideo} 或 {@link stopLocalPreview}。
*
- * @param userId 用户标识
- * @param available 画面是否开启
+ * @param userId 远端用户的用户标识
+ * @param available 该用户是否发布（或取消发布）了主路视频画面，true: 发布；false：取消发布。
*/
- (void)onUserVideoAvailable:(NSString *)userId available:(BOOL)available;
/**
- * 3.4 远端用户是否存在可播放的辅路画面（一般用于屏幕分享）
+ * 3.4 某远端用户发布/取消了辅路视频画面
*
- * @note 显示辅路画面使用的函数是 startRemoteSubStreamView() 而非 startRemoteView()。
- * @param userId 用户标识
- * @param available 屏幕分享是否开启
+ * “辅路画面”一般被用于承载屏幕分享的画面。当您收到 onUserSubStreamAvailable(userId, true) 通知时，表示该路画面已经有可播放的视频帧到达。
+ * 此时，您需要调用 {@link startRemoteSubStreamView} 接口订阅该用户的远程画面，订阅成功后，您会继续收到该用户的首帧画面渲染回调 onFirstVideoFrame(userid)。
+ *
+ * @note 显示辅路画面使用的函数是 {@link startRemoteSubStreamView} 而非 {@link startRemoteView}。
+ *
+ * @param userId 远端用户的用户标识
+ * @param available 该用户是否发布（或取消发布）了辅路视频画面，true: 发布；false：取消发布。
*/
- (void)onUserSubStreamAvailable:(NSString *)userId available:(BOOL)available;
/**
- * 3.5 远端用户是否存在可播放的音频数据
+ * 3.5 某远端用户发布/取消了自己的音频
*
- * @param userId 用户标识
- * @param available 声音是否开启
+ * 当您收到 onUserAudioAvailable(userId, true) 通知时，表示该用户发布了自己的声音，此时 SDK 的表现为：
+ * - 在自动订阅模式下，您无需做任何操作，SDK 会自动播放该用户的声音。
+ * - 在手动订阅模式下，您可以通过 {@link muteRemoteAudio}(userid, false) 来播放该用户的声音。
+ *
+ * @note SDK 默认使用自动订阅模式，您可以通过 {@link setDefaultStreamRecvMode} 设置为手动订阅，但需要在您进入房间之前调用才生效。
+ *
+ * @param userId 远端用户的用户标识
+ * @param available 该用户是否发布（或取消发布）了自己的音频，true: 发布；false：取消发布。
*/
- (void)onUserAudioAvailable:(NSString *)userId available:(BOOL)available;
/**
- * 3.6 开始渲染本地或远程用户的首帧画面
+ * 3.6 SDK 开始渲染自己本地或远端用户的首帧画面
*
- * 如果 userId == nil，代表开始渲染本地采集的摄像头画面，需要您先调用 startLocalPreview 触发。
- * 如果 userId != nil，代表开始渲染远程用户的首帧画面，需要您先调用 startRemoteView 触发。
+ * SDK 会在渲染自己本地或远端用户的首帧画面时抛出该事件，您可以通过回调事件中的 userId 参数来判断事件来自于“本地”还是来自于“远端”。
+ * - 如果 userId 为空值，代表 SDK 已经开始渲染自己本地的视频画面，不过前提是您已经调用了 {@link startLocalPreview} 或 {@link startScreenCapture}。
+ * - 如果 userId 不为空，代表 SDK 已经开始渲染远端用户的视频画面，不过前提是您已经调用了 {@link startRemoteView} 订阅了该用户的视频画面。
*
- * @note 只有当您调用 startLocalPreivew()、startRemoteView() 或 startRemoteSubStreamView() 之后，才会触发该回调。
+ * @note
+ * 1. 只有当您调用了 {@link startLocalPreview} 或 {@link startScreenCapture} 之后，才会触发自己本地的首帧画面事件回调。
+ * 2. 只有当您调用了 {@link startRemoteView} 或 {@link startRemoteSubStreamView} 之后，才会触发远端用户的首帧画面事件回调。
*
- * @param userId 本地或远程用户 ID，如果 userId == nil 代表本地，userId != nil 代表远程。
- * @param streamType 视频流类型：摄像头或屏幕分享。
- * @param width 画面宽度
- * @param height 画面高度
+ * @param userId 本地或远端的用户标识，如果 userId 为空值代表自己本地的首帧画面已到来，userId 不为空则代表远端用户的首帧画面已到来。
+ * @param streamType 视频流类型：主路（Main）一般用于承载摄像头画面，辅路（Sub）一般用于承载屏幕分享画面。
+ * @param width 画面的宽度。
+ * @param height 画面的高度。
*/
-- (void)onFirstVideoFrame:(NSString*)userId streamType:(TRTCVideoStreamType)streamType width:(int)width height:(int)height;
+- (void)onFirstVideoFrame:(NSString *)userId streamType:(TRTCVideoStreamType)streamType width:(int)width height:(int)height;
/**
- * 3.7 开始播放远程用户的首帧音频（本地声音暂不通知）
+ * 3.7 SDK 开始播放远端用户的首帧音频
*
- * @param userId 远程用户 ID。
+ * SDK 会在播放远端用户的首帧音频时抛出该事件，本地音频的首帧事件暂不抛出。
+ *
+ * @param userId 远端用户的用户标识
*/
-- (void)onFirstAudioFrame:(NSString*)userId;
+- (void)onFirstAudioFrame:(NSString *)userId;
/**
- * 3.8 首帧本地视频数据已经被送出
+ * 3.8 自己本地的首个视频帧已被发布出去
*
- * SDK 会在 enterRoom() 并 startLocalPreview() 成功后开始摄像头采集，并将采集到的画面进行编码。
- * 当 SDK 成功向云端送出第一帧视频数据后，会抛出这个回调事件。
+ * 当您成功进入房间并通过 {@link startLocalPreview} 或 {@link startScreenCapture} 开启本地视频采集之后（开启采集和进入房间的先后顺序无影响），
+ * SDK 就会开始进行视频编码，并通过自身的网络模块向云端发布自己本地的视频数据。
+ * 当 SDK 成功地向云端送出自己的第一帧视频数据帧以后，就会抛出 onSendFirstLocalVideoFrame 事件回调。
*
- * @param streamType 视频流类型，主画面、小画面或辅流画面（屏幕分享）
+ * @param streamType 视频流类型：主路（Main）一般用于承载摄像头画面，辅路（Sub）一般用于承载屏幕分享画面。
*/
-- (void)onSendFirstLocalVideoFrame: (TRTCVideoStreamType)streamType;
+- (void)onSendFirstLocalVideoFrame:(TRTCVideoStreamType)streamType;
/**
- * 3.9 首帧本地音频数据已经被送出
+ * 3.9 自己本地的首个音频帧已被发布出去
*
- * SDK 会在 enterRoom() 并 startLocalAudio() 成功后开始麦克风采集，并将采集到的声音进行编码。
- * 当 SDK 成功向云端送出第一帧音频数据后，会抛出这个回调事件。
+ * 当您成功进入房间并通过 {@link startLocalAudio} 开启本地音频采集之后（开启采集和进入房间的先后顺序无影响），
+ * SDK 就会开始进行音频编码，并通过自身的网络模块向云端发布自己本地的音频数据。
+ * 当 SDK 成功地向云端送出自己的第一帧音频数据帧以后，就会抛出 onSendFirstLocalAudioFrame 事件回调。
*/
- (void)onSendFirstLocalAudioFrame;
/**
- * 3.10 废弃接口：有主播加入当前房间
- *
- * 该回调接口可以被看作是 onRemoteUserEnterRoom 的废弃版本，不推荐使用。请使用 onUserVideoAvailable 或 onRemoteUserEnterRoom 进行替代。
- *
- * @note 该接口已被废弃，不推荐使用
+ * 3.10 远端视频状态变化的事件回调
*
+ * 您可以通过此事件回调获取远端每一路画面的播放状态（包括 Playing、Loading 和 Stopped 三种状态），从而进行相应的 UI 展示。
* @param userId 用户标识
+ * @param streamType 视频流类型：主路（Main）一般用于承载摄像头画面，辅路（Sub）一般用于承载屏幕分享画面。
+ * @param status 视频状态：包括 Playing、Loading 和 Stopped 三种状态。
+ * @param reason 视频状态改变的原因
+ * @param extrainfo 额外信息
*/
-- (void)onUserEnter:(NSString *)userId DEPRECATED_ATTRIBUTE;
-
-/**
- * 3.11 废弃接口：有主播离开当前房间
- *
- * 该回调接口可以被看作是 onRemoteUserLeaveRoom 的废弃版本，不推荐使用。请使用 onUserVideoAvailable 或 onRemoteUserLeaveRoom 进行替代。
- *
- * @note 该接口已被废弃，不推荐使用
- *
- * @param userId 用户标识
- * @param reason 离开原因。
- */
-- (void)onUserExit:(NSString *)userId reason:(NSInteger)reason DEPRECATED_ATTRIBUTE;
+- (void)onRemoteVideoStatusUpdated:(NSString *)userId streamType:(TRTCVideoStreamType)streamType streamStatus:(TRTCAVStatusType)status reason:(TRTCAVStatusChangeReason)reason extrainfo:(nullable NSDictionary *)info;
/// @}
-
/////////////////////////////////////////////////////////////////////////////////
//
-// （四）统计和质量回调
+// 网络和技术指标统计回调
//
/////////////////////////////////////////////////////////////////////////////////
-
-/// @name 统计和质量回调
+/// @name 网络和技术指标统计回调
/// @{
/**
- * 4.1 网络质量，该回调每2秒触发一次，统计当前网络的上行和下行质量
+ * 4.1 网络质量的实时统计回调
+ *
+ * 该统计回调每间隔2秒抛出一次，用于通知 SDK 感知到的当前网络的上行和下行质量。
+ * SDK 会使用一组内嵌的自研算法对当前网络的延迟高低、带宽大小以及稳定情况进行评估，并计算出一个的评估结果：
+ * 如果评估结果为 1（Excellent） 代表当前的网络情况非常好，如果评估结果为 6（Down）代表当前网络无法支撑 TRTC 的正常通话。
*
- * @note userId == nil 代表自己当前的视频质量
+ * @note 回调参数 localQuality 和 remoteQuality 中的 userId 如果为空置，代表本组数据统计的是自己本地的网络质量，否则是代表远端用户的网络质量。
*
* @param localQuality 上行网络质量
* @param remoteQuality 下行网络质量
*/
-- (void)onNetworkQuality: (TRTCQualityInfo*)localQuality remoteQuality:(NSArray<TRTCQualityInfo*>*)remoteQuality;
+- (void)onNetworkQuality:(TRTCQualityInfo *)localQuality remoteQuality:(NSArray<TRTCQualityInfo *> *)remoteQuality;
/**
- * 4.2 技术指标统计回调
+ * 4.2 音视频技术指标的实时统计回调
*
- * 如果您是熟悉音视频领域相关术语，可以通过这个回调获取 SDK 的所有技术指标。
- * 如果您是首次开发音视频相关项目，可以只关注 onNetworkQuality 回调。
+ * 该统计回调每间隔2秒抛出一次，用于通知 SDK 内部音频、视频以及网络相关的专业技术指标，这些信息在 {@link TRTCStatistics} 均有罗列：
+ * - 视频统计信息：视频的分辨率（resolution）、帧率（FPS）和比特率（bitrate）等信息。
+ * - 音频统计信息：音频的采样率（samplerate）、声道（channel）和比特率（bitrate）等信息。
+ * - 网络统计信息：SDK 和云端一次往返（SDK => Cloud => SDK）的网络耗时（rtt）、丢包率（loss）、上行流量（sentBytes）和下行流量（receivedBytes）等信息。
*
- * @param statistics 统计数据，包括本地和远程的
- * @note 每2秒回调一次
+ * @note 如果您只需要获知当前网络质量的好坏，并不需要花太多时间研究本统计回调，更推荐您使用 {@link onNetworkQuality} 来解决问题。
+ * @param statistics 统计数据，包括自己本地的统计信息和远端用户的统计信息，详情请参考 {@link TRTCStatistics}。
*/
-- (void)onStatistics: (TRTCStatistics *)statistics;
+- (void)onStatistics:(TRTCStatistics *)statistics;
/// @}
-
/////////////////////////////////////////////////////////////////////////////////
//
-// （五）服务器事件回调
+// 与云端连接情况的事件回调
//
/////////////////////////////////////////////////////////////////////////////////
-
-/// @name 服务器事件回调
+/// @name 与云端连接情况的事件回调
/// @{
/**
- * 5.1 SDK 跟服务器的连接断开
+ * 5.1 SDK 与云端的连接已经断开
+ *
+ * SDK 会在跟云端的连接断开时抛出此事件回调，导致断开的原因大多是网络不可用或者网络切换所致，比如用户在通话中走进电梯时就可能会遇到此事件。
+ * 在抛出此事件之后，SDK 会努力跟云端重新建立连接，重连过程中会抛出 {@link onTryToReconnect}，连接恢复后会抛出 {@link onConnectionRecovery} 。
+ * 所以，SDK 会在如下三个连接相关的事件中按如下规律切换：
+ * <pre>
+ * [onConnectionLost] =====> [onTryToReconnect] =====> [onConnectionRecovery]
+ * /|\ |
+ * |------------------------------------------------------|
+ * </pre>
*/
- (void)onConnectionLost;
/**
- * 5.2 SDK 尝试重新连接到服务器
+ * 5.2 SDK 正在尝试重新连接到云端
+ *
+ * SDK 会在跟云端的连接断开时抛出 {@link onConnectionLost}，之后会努力跟云端重新建立连接并抛出本事件，连接恢复后会抛出 {@link onConnectionRecovery}。
*/
- (void)onTryToReconnect;
/**
- * 5.3 SDK 跟服务器的连接恢复
+ * 5.3 SDK 与云端的连接已经恢复
+ *
+ * SDK 会在跟云端的连接断开时抛出 {@link onConnectionLost}，之后会努力跟云端重新建立连接并抛出{@link onTryToReconnect}，连接恢复后会抛出本事件回调。
*/
- (void)onConnectionRecovery;
/// @}
-
/////////////////////////////////////////////////////////////////////////////////
//
-// （六）硬件设备事件回调
+// 硬件设备相关事件回调
//
/////////////////////////////////////////////////////////////////////////////////
-
-/// @name 硬件设备事件回调
+/// @name 硬件设备相关事件回调
/// @{
/**
* 6.1 摄像头准备就绪
+ *
+ * 当您调用 {@link startLocalPreivew} 之后，SDK 会尝试启动摄像头，如果摄像头能够启动成功就会抛出本事件。
+ * 如果启动失败，大概率是因为当前应用没有获得访问摄像头的权限，或者摄像头当前正在被其他程序独占使用中。
+ * 您可以通过捕获 {@link onError} 事件回调获知这些异常情况并通过 UI 界面提示用户。
*/
- (void)onCameraDidReady;
/**
* 6.2 麦克风准备就绪
+ *
+ * 当您调用 {@link startLocalAudio} 之后，SDK 会尝试启动麦克风，如果麦克风能够启动成功就会抛出本事件。
+ * 如果启动失败，大概率是因为当前应用没有获得访问麦克风的权限，或者麦克风当前正在被其他程序独占使用中。
+ * 您可以通过捕获 {@link onError} 事件回调获知这些异常情况并通过 UI 界面提示用户。
*/
- (void)onMicDidReady;
-#if TARGET_OS_IPHONE
/**
- * 6.3 音频路由发生变化（仅 iOS），音频路由即声音由哪里输出（扬声器或听筒）
+ * 6.3 当前音频路由发生变化（仅适用于移动设备）
+ *
+ * 所谓“音频路由”，是指声音是从手机的扬声器还是从听筒中播放出来，音频路由变化也就是声音的播放位置发生了变化。
+ * - 当音频路由为听筒时，声音比较小，只有将耳朵凑近才能听清楚，隐私性较好，适合用于接听电话。
+ * - 当音频路由为扬声器时，声音比较大，不用将手机贴脸也能听清，因此可以实现“免提”的功能。
*
- * @param route 当前音频路由
- * @param fromRoute 变更前的音频路由
+ * @param route 音频路由，即声音由哪里输出（扬声器、听筒）。
+ * @param fromRoute 变更前的音频路由。
*/
+#if TARGET_OS_IPHONE
- (void)onAudioRouteChanged:(TRTCAudioRoute)route fromRoute:(TRTCAudioRoute)fromRoute;
#endif
/**
- * 6.4 用于提示音量大小的回调，包括每个 userId 的音量和远端总音量
+ * 6.4 音量大小的反馈回调
*
- * 您可以通过调用 TRTCCloud 中的 enableAudioVolumeEvaluation 接口来开关这个回调或者设置它的触发间隔。
- * 需要注意的是，调用 enableAudioVolumeEvaluation 开启音量回调后，无论频道内是否有人说话，都会按设置的时间间隔调用这个回调;
- * 如果没有人说话，则 userVolumes 为空，totalVolume 为 0。
+ * SDK 可以评估每一路音频的音量大小，并每隔一段时间抛出该事件回调，您可以根据音量大小在 UI 上做出相应的提示，比如“波形图”或“音量槽”。
+ * 要完成这个功能， 您需要先调用 {@link enableAudioVolumeEvaluation} 开启这个能力并设定事件抛出的时间间隔。
+ * 需要补充说明的是，无论当前房间中是否有人说话，SDK 都会按照您设定的时间间隔定时抛出此事件回调，只不过当没有人说话时，userVolumes 为空，totalVolume 为 0。
*
- * @param userVolumes 所有正在说话的房间成员的音量，取值范围 0 - 100。
- * @param totalVolume 所有远端成员的总音量, 取值范围 0 - 100。
- * @note userId 为 nil 时表示自己的音量，userVolumes 内仅包含正在说话（音量不为 0 ）的用户音量信息。
+ * @note userVolumes 为一个数组，对于数组中的每一个元素，当 userId 为空时表示本地麦克风采集的音量大小，当 userId 不为空时代表远端用户的音量大小。
+ *
+ * @param userVolumes 是一个数组，用于承载所有正在说话的用户的音量大小，取值范围 0 - 100。
+ * @param totalVolume 所有远端用户的总音量大小, 取值范围 0 - 100。
*/
- (void)onUserVoiceVolume:(NSArray<TRTCVolumeInfo *> *)userVolumes totalVolume:(NSInteger)totalVolume;
-
-#if !TARGET_OS_IPHONE && TARGET_OS_MAC
/**
- * 6.5 本地设备通断回调
+ * 6.5 本地设备的通断状态发生变化（仅适用于桌面系统）
+ *
+ * 当本地设备（包括摄像头、麦克风以及扬声器）被插入或者拔出时，SDK 便会抛出此事件回调。
*
* @param deviceId 设备 ID
* @param deviceType 设备类型
- * @param state 0：设备断开；1：设备连接
+ * @param state 通断状态，0：设备断开；1：设备连接。
*/
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
- (void)onDevice:(NSString *)deviceId type:(TRTCMediaDeviceType)deviceType stateChanged:(NSInteger)state;
-
+#endif
/**
- * 6.6 当前音频采集设备音量变化回调
+ * 6.6 当前麦克风的系统采集音量发生变化
+ *
+ * 在 Mac 或 Windows 这样的桌面操作系统上，用户可以在设置中心找到声音相关的设置面板，并设置麦克风的采集音量大小。
+ * 用户将麦克风的采集音量设置得越大，麦克风采集到的声音的原始音量也就会越大，反之就会越小。
+ * 在有些型号的键盘以及笔记本电脑上，用户还可以通过按下“禁用麦克风”按钮（图标是一个话筒上上叠加了一道代表禁用的斜线）来将麦克风静音。
*
- * @note 使用 enableAudioVolumeEvaluation（interval>0）开启，（interval == 0）关闭
+ * 当用户通过系统设置界面或者通过键盘上的快捷键设定操作系统的麦克风采集音量时，SDK 便会抛出此事件。
*
- * @param volume 音量 取值范围 0 - 100
- * @param muted 当前采集音频设备是否被静音：YES 被静音了，NO 未被静音
+ * @note 您需要调用 {@link enableAudioVolumeEvaluation} 接口并设定（interval>0）开启次事件回调，设定（interval == 0）关闭此事件回调。
+ *
+ * @param volume 系统采集音量，取值范围 0 - 100，用户可以在系统的声音设置面板上进行拖拽调整。
+ * @param muted 麦克风是否被用户禁用了：true 被禁用，false 被启用。
*/
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
- (void)onAudioDeviceCaptureVolumeChanged:(NSInteger)volume muted:(BOOL)muted;
+#endif
/**
- * 6.7 当前音频播放设备音量变化回调
+ * 6.7 当前系统的播放音量发生变化
+ *
+ * 在 Mac 或 Windows 这样的桌面操作系统上，用户可以在设置中心找到声音相关的设置面板，并设置系统的播放音量大小。
+ * 在有些型号的键盘以及笔记本电脑上，用户还可以通过按下“静音”按钮（图标是一个喇叭上叠加了一道代表禁用的斜线）来将系统静音。
+ *
+ * 当用户通过系统设置界面或者通过键盘上的快捷键设定操作系统的播放音量时，SDK 便会抛出此事件。
*
- * @note 使用 enableAudioVolumeEvaluation（interval>0）开启，（interval == 0）关闭
+ * @note 您需要调用 {@link enableAudioVolumeEvaluation} 接口并设定（interval>0）开启次事件回调，设定（interval == 0）关闭此事件回调。
*
- * @param volume 音量 取值范围 0 - 100
- * @param muted 当前音频播放设备是否被静音：YES 被静音了，NO 未被静音
+ * @param volume 系统播放音量，取值范围 0 - 100，用户可以在系统的声音设置面板上进行拖拽调整。
+ * @param muted 系统是否被用户静音了：true 被静音，false 已恢复。
*/
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
- (void)onAudioDevicePlayoutVolumeChanged:(NSInteger)volume muted:(BOOL)muted;
+#endif
/**
- * 6.8 系统声音采集结果回调
+ * 6.8 系统声音采集是否被成功开启的事件回调（仅适用于 Mac 系统）
*
- * 系统声音采集接口 startSystemAudioLoopback 会触发这个回调
+ * 在 Mac 系统上，您可以通过调用 {@link startSystemAudioLoopback} 为当前系统安装一个音频驱动，并让 SDK 通过该音频驱动捕获当前 Mac 系统播放出的声音。
+ * 当用于播片教学或音乐直播中，比如老师端可以使用此功能，让 SDK 能够采集老师所播放的电影中的声音，使同房间的学生端也能听到电影中的声音。
+ * SDK 会将统声音采集是否被成功开启的结果，通过本事件回调抛出，需要您关注参数中的错误码。
*
- * @param err ERR_NULL 表示成功，其余值表示失败
+ * @param err ERR_NULL 表示成功，其余值表示失败。
*/
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
- (void)onSystemAudioLoopbackError:(TXLiteAVError)err;
-
#endif
/// @}
-
-
/////////////////////////////////////////////////////////////////////////////////
//
-// （七）自定义消息的接收回调
+// 自定义消息的接收事件回调
//
/////////////////////////////////////////////////////////////////////////////////
-
-/// @name 自定义消息的接收回调
+/// @name 自定义消息的接收事件回调
/// @{
/**
- * 7.1 收到自定义消息回调
+ * 7.1 收到自定义消息的事件回调
*
- * 当房间中的某个用户使用 sendCustomCmdMsg 发送自定义消息时，房间中的其它用户可以通过 onRecvCustomCmdMsg 接口接收消息
+ * 当房间中的某个用户使用 {@link sendCustomCmdMsg} 发送自定义 UDP 消息时，房间中的其它用户可以通过 onRecvCustomCmdMsg 事件回调接收到该条消息。
*
* @param userId 用户标识
* @param cmdID 命令 ID
@@ -419,9 +472,9 @@ NS_ASSUME_NONNULL_BEGIN
- (void)onRecvCustomCmdMsgUserId:(NSString *)userId cmdID:(NSInteger)cmdID seq:(UInt32)seq message:(NSData *)message;
/**
- * 7.2 自定义消息丢失回调
+ * 7.2 自定义消息丢失的事件回调
*
- * 实时音视频使用 UDP 通道，即使设置了可靠传输（reliable），也无法确保100@%不丢失，只是丢消息概率极低，能满足常规可靠性要求。
+ * 当您使用 {@link sendCustomCmdMsg} 发送自定义 UDP 消息时，即使设置了可靠传输（reliable），也无法确保100@%不丢失，只是丢消息概率极低，能满足常规可靠性要求。
* 在发送端设置了可靠运输（reliable）后，SDK 都会通过此回调通知过去时间段内（通常为5s）传输途中丢失的自定义消息数量统计信息。
*
* @note 只有在发送端设置了可靠传输（reliable），接收方才能收到消息的丢失回调
@@ -435,318 +488,401 @@ NS_ASSUME_NONNULL_BEGIN
/**
* 7.3 收到 SEI 消息的回调
*
- * 当房间中的某个用户使用 sendSEIMsg 发送数据时，房间中的其它用户可以通过 onRecvSEIMsg 接口接收数据。
+ * 当房间中的某个用户使用 {@link sendSEIMsg} 借助视频数据帧发送 SEI 消息时，房间中的其它用户可以通过 onRecvSEIMsg 事件回调接收到该条消息。
*
* @param userId 用户标识
* @param message 数据
*/
-- (void)onRecvSEIMsg:(NSString *)userId message:(NSData*)message;
+- (void)onRecvSEIMsg:(NSString *)userId message:(NSData *)message;
/// @}
-
/////////////////////////////////////////////////////////////////////////////////
//
-// （八）CDN 旁路回调
+// CDN 相关事件回调
//
/////////////////////////////////////////////////////////////////////////////////
-/// @name CDN 旁路转推回调
+/// @name CDN 相关事件回调
/// @{
-
+
/**
- * 8.1 开始向腾讯云的直播 CDN 推流的回调，对应于 TRTCCloud 中的 startPublishing() 接口
+ * 8.1 开始向腾讯云直播 CDN 上发布音视频流的事件回调
+ *
+ * 当您调用 {@link startPublishing} 开始向腾讯云直播 CDN 上发布音视频流时，SDK 会立刻将这一指令同步给云端服务器。
+ * 随后 SDK 会收到来自云端服务器的处理结果，并将指令的执行结果通过本事件回调通知给您。
*
* @param err 0表示成功，其余值表示失败
* @param errMsg 具体错误原因
*/
-- (void)onStartPublishing:(int)err errMsg:(NSString*)errMsg;
+- (void)onStartPublishing:(int)err errMsg:(NSString *)errMsg;
/**
- * 8.2 停止向腾讯云的直播 CDN 推流的回调，对应于 TRTCCloud 中的 stopPublishing() 接口
+ * 8.2 停止向腾讯云直播 CDN 上发布音视频流的事件回调
+ *
+ * 当您调用 {@link stopPublishing} 停止向腾讯云直播 CDN 上发布音视频流时，SDK 会立刻将这一指令同步给云端服务器。
+ * 随后 SDK 会收到来自云端服务器的处理结果，并将指令的执行结果通过本事件回调通知给您。
*
* @param err 0表示成功，其余值表示失败
* @param errMsg 具体错误原因
*/
-- (void)onStopPublishing:(int)err errMsg:(NSString*)errMsg;
+- (void)onStopPublishing:(int)err errMsg:(NSString *)errMsg;
/**
- * 8.3 启动旁路推流到 CDN 完成的回调
+ * 8.3 开始向非腾讯云 CDN 上发布音视频流的事件回调
*
- * 对应于 TRTCCloud 中的 startPublishCDNStream() 接口
+ * 当您调用 {@link startPublishCDNStream} 开始向非腾讯云直播 CDN 上发布音视频流时，SDK 会立刻将这一指令同步给云端服务器。
+ * 随后 SDK 会收到来自云端服务器的处理结果，并将指令的执行结果通过本事件回调通知给您。
*
- * @note Start 回调如果成功，只能说明转推请求已经成功告知给腾讯云，如果目标 CDN 有异常，还是有可能会转推失败。
+ * @note 当您收到成功的事件回调时，只是说明您的发布指令已经同步到腾讯云后台服务器，但如果目标 CDN 厂商的服务器不接收该条视频流，依然可能导致发布失败。
+ * @param err 0表示成功，其余值表示失败
+ * @param errMsg 具体错误原因
*/
- (void)onStartPublishCDNStream:(int)err errMsg:(NSString *)errMsg;
/**
- * 8.4 停止旁路推流到 CDN 完成的回调
+ * 8.4 停止向非腾讯云 CDN 上发布音视频流的事件回调
*
- * 对应于 TRTCCloud 中的 stopPublishCDNStream() 接口
+ * 当您调用 {@link stopPublishCDNStream} 开始向非腾讯云直播 CDN 上发布音视频流时，SDK 会立刻将这一指令同步给云端服务器。
+ * 随后 SDK 会收到来自云端服务器的处理结果，并将指令的执行结果通过本事件回调通知给您。
*
+ * @param err 0表示成功，其余值表示失败
+ * @param errMsg 具体错误原因
*/
- (void)onStopPublishCDNStream:(int)err errMsg:(NSString *)errMsg;
/**
- * 8.5 设置云端的混流转码参数的回调，对应于 TRTCCloud 中的 setMixTranscodingConfig() 接口
+ * 8.5 设置云端混流的排版布局和转码参数的事件回调
*
- * @param err 0表示成功，其余值表示失败
- * @param errMsg 具体错误原因
+ * 当您调用 {@link setMixTranscodingConfig} 调整云端混流的排版布局和转码参数时，SDK 会立刻将这一调整指令同步给云端服务器。
+ * 随后 SDK 会收到来自云端服务器的处理结果，并将指令的执行结果通过本事件回调通知给您。
+ *
+ * @param err 错误码：0表示成功，其余值表示失败。
+ * @param errMsg 具体的错误原因。
*/
-- (void)onSetMixTranscodingConfig:(int)err errMsg:(NSString*)errMsg;
+- (void)onSetMixTranscodingConfig:(int)err errMsg:(NSString *)errMsg;
/// @}
-
/////////////////////////////////////////////////////////////////////////////////
//
-// （九）音效回调
+// 屏幕分享相关事件回调
//
/////////////////////////////////////////////////////////////////////////////////
-/// @name 音效回调
+/// @name 屏幕分享相关事件回调
/// @{
-/**
- * 播放音效结束回调
- *
- * @param effectId 音效 ID
- * @param code 0 表示播放正常结束；其他表示异常结束
- * @note 该接口已不再维护，推荐使用 TXAudioEffectManager.startPlayMusic 及相关回调
- */
-- (void)onAudioEffectFinished:(int) effectId code:(int) code DEPRECATED_ATTRIBUTE;
-/// @}
-/////////////////////////////////////////////////////////////////////////////////
-//
-// （十）屏幕分享回调
-//
-/////////////////////////////////////////////////////////////////////////////////
-/// @name 屏幕分享回调
-/// @{
/**
- * 10.1 当屏幕分享开始时，SDK 会通过此回调通知
+ * 9.1 屏幕分享开启的事件回调
+ *
+ * 当您通过 {@link startScreenCapture} 等相关接口启动屏幕分享时，SDK 便会抛出此事件回调。
*/
- (void)onScreenCaptureStarted;
/**
- * 10.2 当屏幕分享暂停时，SDK 会通过此回调通知
+ * 9.2 屏幕分享暂停的事件回调
*
- * @param reason 原因，0：用户主动暂停；1：屏幕窗口不可见暂停
+ * 当您通过 {@link pauseScreenCapture} 暂停屏幕分享时，SDK 便会抛出此事件回调。
+ * @param reason 原因。
+ * - 0：用户主动暂停。
+ * - 1：注意此字段的含义在 MAC 和 Windows 平台有稍微差异。屏幕窗口不可见暂停（Mac）。表示设置屏幕分享参数导致的暂停（Windows）。
+ * - 2：表示屏幕分享窗口被最小化导致的暂停（仅 Windows）。
+ * - 3：表示屏幕分享窗口被隐藏导致的暂停（仅 Windows）。
*/
- (void)onScreenCapturePaused:(int)reason;
/**
- * 10.3 当屏幕分享恢复时，SDK 会通过此回调通知
+ * 9.3 屏幕分享恢复的事件回调
*
- * @param reason 恢复原因，0：用户主动恢复；1：屏幕窗口恢复可见从而恢复分享
+ * 当您通过 {@link resumeScreenCapture} 恢复屏幕分享时，SDK 便会抛出此事件回调。
+ * @param reason 恢复原因。
+ * - 0：用户主动恢复。
+ * - 1：注意此字段的含义在 MAC 和 Windows 平台有稍微差异。屏幕窗口恢复可见从而恢复分享（Mac）。屏幕分享参数设置完毕后自动恢复（Windows）
+ * - 2：表示屏幕分享窗口从最小化被恢复（仅 Windows）。
+ * - 3：表示屏幕分享窗口从隐藏被恢复（仅 Windows）。
*/
- (void)onScreenCaptureResumed:(int)reason;
/**
- * 10.4 当屏幕分享停止时，SDK 会通过此回调通知
+ * 9.4 屏幕分享停止的事件回调
*
- * @param reason 停止原因，0：用户主动停止；1：屏幕窗口关闭导致停止
+ * 当您通过 {@link stopScreenCapture} 停止屏幕分享时，SDK 便会抛出此事件回调。
+ * @param reason 停止原因，0：用户主动停止；1：屏幕窗口关闭导致停止；2：表示屏幕分享的显示屏状态变更（如接口被拔出、投影模式变更等）。
*/
- (void)onScreenCaptureStoped:(int)reason;
-/// @}
-#if TARGET_OS_IPHONE
+/// @}
/////////////////////////////////////////////////////////////////////////////////
//
-// （十一）媒体录制回调
+// 本地录制和本地截图的事件回调
//
/////////////////////////////////////////////////////////////////////////////////
-/// @name 媒体录制回调
+/// @name 本地录制和本地截图的事件回调
/// @{
+
/**
- * 11.1 媒体录制回调
+ * 10.1 本地录制任务已经开始的事件回调
*
+ * 当您调用 {@link startLocalRecording} 启动本地媒体录制任务时，SDK 会抛出该事件回调，用于通知您录制任务是否已经顺利启动。
* @param errCode 错误码 0：初始化录制成功；-1：初始化录制失败；-2: 文件后缀名有误。
* @param storagePath 录制文件存储路径
*/
+#if TARGET_OS_IPHONE
- (void)onLocalRecordBegin:(NSInteger)errCode storagePath:(NSString *)storagePath;
+#endif
/**
- * 11.2 录制信息更新回调
+ * 10.2 本地录制任务正在进行中的进展事件回调
*
+ * 当您调用 {@link startLocalRecording} 成功启动本地媒体录制任务后，SDK 变会定时地抛出本事件回调。
+ * 您可通过捕获该事件回调来获知录制任务的健康状况。
+ * 您可以在 {@link startLocalRecording} 时设定本事件回调的抛出间隔。
+ *
+ * @param duration 已经录制的累计时长，单位毫秒
* @param storagePath 录制文件存储路径
- * @param duration 录制时长，单位毫秒
*/
+#if TARGET_OS_IPHONE
- (void)onLocalRecording:(NSInteger)duration storagePath:(NSString *)storagePath;
+#endif
/**
- * 11.2 录制任务已结束
+ * 10.3 本地录制任务已经结束的事件回调
*
+ * 当您调用 {@link stopLocalRecording} 停止本地媒体录制任务时，SDK 会抛出该事件回调，用于通知您录制任务的最终结果。
* @param errCode 错误码 0：录制成功；-1：录制失败；-2：切换分辨率或横竖屏导致录制结束。
* @param storagePath 录制文件存储路径
*/
+#if TARGET_OS_IPHONE
- (void)onLocalRecordComplete:(NSInteger)errCode storagePath:(NSString *)storagePath;
-///@}
#endif
-@end
-/// @}
+/// @}
/////////////////////////////////////////////////////////////////////////////////
//
-// （十二）自定义视频渲染回调
+// 废弃的事件回调（建议使用对应的新回调）
//
/////////////////////////////////////////////////////////////////////////////////
-#pragma mark - TRTCVideoRenderDelegate
-/// @addtogroup TRTCCloudDelegate_ios
+/// @name 废弃的事件回调（建议使用对应的新回调）
/// @{
+
/**
- * 视频数据帧的自定义处理回调
+ * 有主播加入当前房间（已废弃）
+ *
+ * @deprecated 新版本开始不推荐使用，建议使用 {@link onRemoteUserEnterRoom} 替代之。
*/
-@protocol TRTCVideoRenderDelegate <NSObject>
+- (void)onUserEnter:(NSString *)userId __attribute__((deprecated("use onRemoteUserLeaveRoom instead")));
+
/**
- * 自定义视频渲染回调
+ * 有主播离开当前房间（已废弃）
*
- * @param frame 待渲染的视频帧信息
- * @param userId 视频源的 userId，如果是本地视频回调（setLocalVideoRenderDelegate），该参数可以忽略
- * @param streamType 视频源类型，例如，使用摄像头画面或屏幕分享画面等
+ * @deprecated 新版本开始不推荐使用，建议使用 {@link onRemoteUserLeaveRoom} 替代之。
*/
-@optional
-- (void) onRenderVideoFrame:(TRTCVideoFrame * _Nonnull)frame userId:(NSString* __nullable)userId streamType:(TRTCVideoStreamType)streamType;
+- (void)onUserExit:(NSString *)userId reason:(NSInteger)reason __attribute__((deprecated("use onRemoteUserLeaveRoom instead")));
+
+/**
+ * 音效播放已结束（已废弃）
+ *
+ * @deprecated 新版本开始不推荐使用，建议使用 {@link ITXAudioEffectManager} 接口替代之。
+ * 新的接口中不再区分背景音乐和音效，而是统一用 {@link startPlayMusic} 取代之。
+ */
+- (void)onAudioEffectFinished:(int)effectId code:(int)code __attribute__((deprecated("use ITXAudioEffectManager.startPlayMusic instead")));
-@end
+/// @}
+@end // End of class TRTCCloudDelegate
/////////////////////////////////////////////////////////////////////////////////
//
-// （十三）第三方美颜回调
+// 视频数据自定义回调
//
/////////////////////////////////////////////////////////////////////////////////
+/// @name 视频数据自定义回调
+/// @{
+
+@protocol TRTCVideoRenderDelegate <NSObject>
+
+/**
+ * 自定义视频渲染回调
+ *
+ * 当您设置了本地或者远端的视频自定义渲染回调之后，SDK 就会将原本要交给渲染控件进行渲染的视频帧通过此回调接口抛送给您，以便于您进行自定义渲染。
+ * @param frame 待渲染的视频帧信息
+ * @param userId 视频源的 userId，如果是本地视频回调（setLocalVideoRenderDelegate），该参数可以忽略
+ * @param streamType 频流类型：主路（Main）一般用于承载摄像头画面，辅路（Sub）一般用于承载屏幕分享画面。
+ */
+@optional
+- (void)onRenderVideoFrame:(TRTCVideoFrame *_Nonnull)frame userId:(NSString *__nullable)userId streamType:(TRTCVideoStreamType)streamType;
+
+@end // End of class TRTCVideoRenderDelegate
@protocol TRTCVideoFrameDelegate <NSObject>
+/**
+ * 用于对接第三方美颜组件的视频处理回调
+ *
+ * 如果您选购了第三方美颜组件，就需要在 TRTCCloud 中设置第三方美颜回调，之后 TRTC 就会将原本要进行预处理的视频帧通过此回调接口抛送给您。
+ * 之后您就可以将 TRTC 抛出的视频帧交给第三方美颜组件进行图像处理，由于抛出的数据是可读且可写的，因此第三方美颜的处理结果也可以同步给 TRTC 进行后续的编码和发送。
+ *
+ * @param srcFrame 用于承载 TRTC 采集到的摄像头画面
+ * @param dstFrame 用于接收第三方美颜处理过的视频画面
+ * @note 目前仅支持 OpenGL 纹理方案（ PC 仅支持 TRTCVideoBufferType_Buffer 格式）。
+ *
+ * 情况一：美颜组件自身会产生新的纹理
+ * 如果您使用的美颜组件会在处理图像的过程中产生一帧全新的纹理（用于承载处理后的图像），那请您在回调函数中将 dstFrame.textureId 设置为新纹理的 ID：
+ * <pre>
+ * uint32_t onProcessVideoFrame(TRTCVideoFrame * _Nonnull)srcFrame dstFrame:(TRTCVideoFrame * _Nonnull)dstFrame{
+ * self.frameID += 1;
+ * dstFrame.pixelBuffer = [[FURenderer shareRenderer] renderPixelBuffer:srcFrame.pixelBuffer
+ * withFrameId:self.frameID
+ * items:self.renderItems
+ * itemCount:self.renderItems.count];
+ * return 0;
+ * }
+ * </pre>
+ *
+ *
+ * 情况二：美颜组件需要您提供目标纹理
+ * 如果您使用的第三方美颜模块并不生成新的纹理，而是需要您设置给该模块一个输入纹理和一个输出纹理，则可以考虑如下方案：
+ * ```ObjectiveC
+ * uint32_t onProcessVideoFrame(TRTCVideoFrame * _Nonnull)srcFrame dstFrame:(TRTCVideoFrame * _Nonnull)dstFrame{
+ * thirdparty_process(srcFrame.textureId, srcFrame.width, srcFrame.height, dstFrame.textureId);
+ * return 0;
+ * }
+ * ```
+ * ```java
+ * int onProcessVideoFrame(TRTCCloudDef.TRTCVideoFrame srcFrame, TRTCCloudDef.TRTCVideoFrame dstFrame) {
+ * thirdparty_process(srcFrame.texture.textureId, srcFrame.width, srcFrame.height, dstFrame.texture.textureId);
+ * return 0;
+ * }
+ * ```
+ */
@optional
+- (uint32_t)onProcessVideoFrame:(TRTCVideoFrame *_Nonnull)srcFrame dstFrame:(TRTCVideoFrame *_Nonnull)dstFrame;
/**
-* 第三方美颜的视频数据回调，需要使用 TRTCCloud 中的 setLocalVideoProcessDelegete 接口进行设置
-*
-* @param srcFrame 用于承载 TRTC 采集到的摄像头画面
-* @param dstFrame 用于接收第三方美颜处理过的视频画面
-* @note 目前仅支持 OpenGL 纹理方案
-*
-* 【使用相芯】
-* 由于相芯的美颜模块会在处理图像的过程中产生一个全新的纹理，因此需要您在回调函数中将 dstFrame.textureId 设置为相芯处理后的新纹理。
-* <pre>
-* uint32_t onProcessVideoFrame(TRTCVideoFrame * _Nonnull)srcFrame dstFrame:(TRTCVideoFrame * _Nonnull)dstFrame
-* {
-* uint32_t dstTextureId = renderItemWithTexture(srcFrame.textureId, srcFrame.width, srcFrame.height);
-* dstFrame.textureId = dstTextureId;
-* return 0;
-* }
-* </pre>
-*
-* 【其他方案】
-* 如果您使用的第三方美颜模块并不生成新的纹理，而是需要您设置给该模块一个输入纹理和一个输出纹理，则可以考虑如下方案：
-* <pre>
-* uint32_t onProcessVideoFrame(TRTCVideoFrame * _Nonnull)srcFrame dstFrame:(TRTCVideoFrame * _Nonnull)dstFrame
-* {
-* thirdparty_process(srcFrame.textureId, srcFrame.width, srcFrame.height, dstFrame.textureId);
-* return 0;
-* }
-* </pre>
-*
-**/
-- (uint32_t)onProcessVideoFrame:(TRTCVideoFrame * _Nonnull)srcFrame dstFrame:(TRTCVideoFrame * _Nonnull)dstFrame;
-
-/**
- * SDK 内部的 OpenGL 环境的销毁通知
+ * SDK 内部 OpenGL 环境被销的通知
*/
+@optional
- (void)onGLContextDestory;
-@end
+@end // End of class TRTCVideoFrameDelegate
+/// @}
/////////////////////////////////////////////////////////////////////////////////
//
-// （十四）音频数据回调
+// 音频数据自定义回调
//
/////////////////////////////////////////////////////////////////////////////////
-/**
- * 声音数据帧的自定义处理回调
- */
+/// @name 音频数据自定义回调
+/// @{
+
@protocol TRTCAudioFrameDelegate <NSObject>
@optional
/**
* 本地麦克风采集到的原始音频数据回调
*
- * @param frame 音频数据
- * @note - 请不要在此回调函数中做任何耗时操作，建议直接拷贝到另一线程进行处理，否则会导致各种声音问题。
- * @note - 此接口回调出的音频数据 **不包含** 背景音、音效、混响等前处理效果，延迟极低。
- * - 此接口回调出的音频数据支持修改。
+ * 当您设置完音频数据自定义回调之后，SDK 内部会把刚从麦克风采集到的原始音频数据，以 PCM 格式的形式通过本接口回调给您。
+ * - 此接口回调出的音频时间帧长固定为0.02s，格式为 PCM 格式。
+ * - 由时间帧长转化为字节帧长的公式为【采样率 × 时间帧长 × 声道数 × 采样点位宽】。
+ * - 以 TRTC 默认的音频录制格式48000采样率、单声道、16采样点位宽为例，字节帧长为【48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节】。
+ *
+ * @param frame PCM 格式的音频数据帧
+ * @note
+ * 1. 请不要在此回调函数中做任何耗时操作，由于 SDK 每隔 20ms 就要处理一帧音频数据，如果您的处理时间超过 20ms，就会导致声音异常。
+ * 2. 此接口回调出的音频数据是可读写的，也就是说您可以在回调函数中同步修改音频数据，但请保证处理耗时。
+ * 3. 此接口回调出的音频数据**不包含**背景音、音效、混响等前处理效果，延迟极低。
*/
-- (void) onCapturedRawAudioFrame:(TRTCAudioFrame *)frame;
+- (void)onCapturedRawAudioFrame:(TRTCAudioFrame *)frame;
/**
* 本地采集并经过音频模块前处理后的音频数据回调
*
- * @param frame 音频数据
- * @note - 请不要在此回调函数中做任何耗时操作，建议直接拷贝到另一线程进行处理，否则会导致各种声音问题。
- * @note - 此接口回调出的音频数据包含背景音、音效、混响等前处理效果，延迟较高。
- * @note - 此接口回调出的音频数据支持修改。
- * @note - 此接口回调出的音频时间帧长固定为 0.02s。
- 由时间帧长转化为字节帧长的公式为【采样率 × 时间帧长 × 声道数 × 采样点位宽】。
- 以SDK默认的音频录制格式 48000 采样率、单声道、16采样点位宽为例，字节帧长为【48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节】。
+ * 当您设置完音频数据自定义回调之后，SDK 内部会把刚采集到并经过前处理(ANS、AEC、AGC）之后的数据，以 PCM 格式的形式通过本接口回调给您。
+ * - 此接口回调出的音频时间帧长固定为0.02s，格式为 PCM 格式。
+ * - 由时间帧长转化为字节帧长的公式为【采样率 × 时间帧长 × 声道数 × 采样点位宽】。
+ * - 以 TRTC 默认的音频录制格式48000采样率、单声道、16采样点位宽为例，字节帧长为【48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节】。
+ *
+ * 特殊说明：
+ * 您可以通过设置接口中的 `TRTCAudioFrame.extraData` 字段，达到传输信令的目的。
+ * 由于音频帧头部的数据块不能太大，建议您写入 `extraData` 时，尽量将信令控制在几个字节的大小，如果超过 100 个字节，写入的数据不会被发送。
+ * 房间内其他用户可以通过 {@link TRTCAudioFrameDelegate} 中的 `onRemoteUserAudioFrame` 中的 `TRTCAudioFrame.extraData` 字段回调接收数据。
+ *
+ * @param frame PCM 格式的音频数据帧
+ * @note
+ * 1. 请不要在此回调函数中做任何耗时操作，由于 SDK 每隔 20ms 就要处理一帧音频数据，如果您的处理时间超过 20ms，就会导致声音异常。
+ * 2. 此接口回调出的音频数据是可读写的，也就是说您可以在回调函数中同步修改音频数据，但请保证处理耗时。
+ * 3. 此接口回调出的数据已经经过了回声抑制（AEC）处理，但声音的延迟相比于 {@link onCapturedRawAudioFrame} 要高一些。
*/
-- (void) onLocalProcessedAudioFrame:(TRTCAudioFrame *)frame;
+- (void)onLocalProcessedAudioFrame:(TRTCAudioFrame *)frame;
/**
- * 混音前的每一路远程用户的音频数据，即混音前的各路原始数据。例如，对某一路音频进行文字转换时，您必须使用该路音频的原始数据
+ * 混音前的每一路远程用户的音频数据
+ *
+ * 当您设置完音频数据自定义回调之后，SDK 内部会把远端的每一路原始数据，在最终混音之前，以 PCM 格式的形式通过本接口回调给您。
+ * - 此接口回调出的音频时间帧长固定为0.02s，格式为 PCM 格式。
+ * - 由时间帧长转化为字节帧长的公式为【采样率 × 时间帧长 × 声道数 × 采样点位宽】。
+ * - 以 TRTC 默认的音频录制格式48000采样率、单声道、16采样点位宽为例，字节帧长为【48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节】。
*
- * @param frame 音频数据
- * @param userId 用户标识
- * @note - 此接口回调出的音频数据是只读的，不支持修改。
+ * @param frame PCM 格式的音频数据帧
+ * @param userId 用户标识
+ * @note 此接口回调出的音频数据是只读的，不支持修改
*/
-- (void) onRemoteUserAudioFrame:(TRTCAudioFrame *)frame userId:(NSString *)userId;
+- (void)onRemoteUserAudioFrame:(TRTCAudioFrame *)frame userId:(NSString *)userId;
/**
- * 各路音频数据混合后的音频数据
+ * 将各路待播放音频混合之后并在最终提交系统播放之前的数据回调
+ *
+ * 当您设置完音频数据自定义回调之后，SDK 内部会把各路待播放的音频混合之后的音频数据，在提交系统播放之前，以 PCM 格式的形式通过本接口回调给您。
+ * - 此接口回调出的音频时间帧长固定为0.02s，格式为 PCM 格式。
+ * - 由时间帧长转化为字节帧长的公式为【采样率 × 时间帧长 × 声道数 × 采样点位宽】。
+ * - 以 TRTC 默认的音频录制格式48000采样率、单声道、16采样点位宽为例，字节帧长为【48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节】。
*
- * @param frame 音频数据
- * @note - 请不要在此回调函数中做任何耗时操作，建议直接拷贝到另一线程进行处理，否则会导致各种声音问题。
- * @note - 此接口回调出的音频数据支持修改。
- * @note - 此接口回调出的音频时间帧长固定为 0.02s。
- 由时间帧长转化为字节帧长的公式为【采样率 × 时间帧长 × 声道数 × 采样点位宽】。
- 以SDK默认的音频播放格式 48000 采样率、双声道、16采样点位宽为例，字节帧长为【48000 × 0.02s × 2 × 16bit = 30720bit = 3840字节】。
- * @note - 此接口回调出的音频数据是各路音频播放数据的混合,不包含耳返的音频数据。
+ * @param frame PCM 格式的音频数据帧
+ * @note
+ * 1. 请不要在此回调函数中做任何耗时操作，由于 SDK 每隔 20ms 就要处理一帧音频数据，如果您的处理时间超过 20ms，就会导致声音异常。
+ * 2. 此接口回调出的音频数据是可读写的，也就是说您可以在回调函数中同步修改音频数据，但请保证处理耗时。
+ * 3. 此接口回调出的是对各路待播放音频数据的混合，但其中并不包含耳返的音频数据。
*/
-- (void) onMixedPlayAudioFrame:(TRTCAudioFrame *)frame;
+- (void)onMixedPlayAudioFrame:(TRTCAudioFrame *)frame;
/**
-* SDK所有音频数据混合后的数据回调（包括采集音频数据和所有播放音频数据）
-*
-* @param frame 音频数据
-* @note - 此接口回调出的音频数据不支持修改。
-* @note - 此接口回调出的音频时间帧长固定为 0.02s。音频格式固定为48000采样率、单声道、16采样点位宽。
- 由时间帧长转化为字节帧长的公式为【采样率 × 时间帧长 × 声道数 × 采样点位宽】。
- 因此回调的字节帧长固定为【48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节】。
-* @note - 此接口回调出的是SDK所有音频数据的混合数据，包括：经过特效（包括混响、变声等）处理后的本地麦克风采集数据，
- 所有远程用户的数据，所有背景音和音效数据。不包括耳返数据。
-*/
-- (void) onMixedAllAudioFrame:(TRTCAudioFrame *)frame;
+ * SDK 所有音频混合后的音频数据（包括采集到的和待播放的）
+ *
+ * 当您设置完音频数据自定义回调之后，SDK 内部会把所有采集到的和待播放的音频数据混合起来，以 PCM 格式的形式通过本接口回调给您，便于您进行自定义录制。
+ * - 此接口回调出的音频时间帧长固定为0.02s，格式为 PCM 格式。
+ * - 由时间帧长转化为字节帧长的公式为【采样率 × 时间帧长 × 声道数 × 采样点位宽】。
+ * - 以 TRTC 默认的音频录制格式48000采样率、单声道、16采样点位宽为例，字节帧长为【48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节】。
+ *
+ * @param frame PCM 格式的音频数据帧
+ * @note
+ * 1. 此接口回调出的是SDK所有音频数据的混合数据，包括：经过 3A 前处理、特效叠加以及背景音乐混音后的本地音频，所有远端音频，但不包括耳返音频。
+ * 2. 此接口回调出的音频数据不支持修改。
+ */
+- (void)onMixedAllAudioFrame:(TRTCAudioFrame *)frame;
-@end
+@end // End of class TRTCAudioFrameDelegate
+/// @}
/////////////////////////////////////////////////////////////////////////////////
//
-// （十五）Log 信息回调
+// 更多事件回调接口
//
/////////////////////////////////////////////////////////////////////////////////
-/**
- * 日志相关回调
- *
- * 建议在比较早初始化的类中设置回调委托对象，例如 AppDelegate
- */
+/// @name 更多事件回调接口
+/// @{
+
@protocol TRTCLogDelegate <NSObject>
+
+@optional
+
/**
- * 有日志打印时的回调
+ * 本地 LOG 的打印回调
*
+ * 如果您希望捕获 SDK 的本地日志打印行为，可以通过设置日志回调，让 SDK 将要打印的日志都通过本回调接口抛送给您。
* @param log 日志内容
- * @param level 日志等级，参见 TRTCLogLevel
- * @param module 值暂无具体意义，目前为固定值 TXLiteAVSDK
+ * @param level 日志等级 参见 TRTC_LOG_LEVEL
+ * @param module 保留字段，暂无具体意义，目前为固定值 TXLiteAVSDK
*/
-@optional
--(void) onLog:(nullable NSString*)log LogLevel:(TRTCLogLevel)level WhichModule:(nullable NSString*)module;
+- (void)onLog:(nullable NSString *)log LogLevel:(TRTCLogLevel)level WhichModule:(nullable NSString *)module;
-@end
+@end // End of class TRTCLogDelegate
/// @}
-
NS_ASSUME_NONNULL_END
+
+/// @}
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TRTCStatistics.h b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TRTCStatistics.h
index adbca9e..0021634 100644
--- a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TRTCStatistics.h
+++ b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TRTCStatistics.h
@@ -1,135 +1,177 @@
-
-/*
- * Module: TRTCStatistics @ TXLiteAVSDK
- *
- * Function: 腾讯云视频通话功能的质量统计相关接口
- *
+/**
+ * Module: TRTC 音视频统计指标（只读）
+ * Function: TRTC SDK 会以两秒钟一次的频率向您汇报当前实时的音视频指标（帧率、码率、卡顿情况等）
*/
-///@addtogroup TRTCCloudDef_ios
-///@{
+/// @defgroup TRTCStatisic_ios TRTCStatisic
+/// TRTC 音视频统计指标
+/// @{
+
+/////////////////////////////////////////////////////////////////////////////////
+//
+// 本地的音视频统计指标
+//
+/////////////////////////////////////////////////////////////////////////////////
+/// @name 本地的音视频统计指标
+/// @{
-/// 自己本地的音视频统计信息
@interface TRTCLocalStatistics : NSObject
-/// 视频宽度
-@property (nonatomic, assign) uint32_t width;
+///【字段含义】本地视频的宽度，单位 px
+@property(nonatomic, assign) uint32_t width;
-/// 视频高度
-@property (nonatomic, assign) uint32_t height;
+///【字段含义】本地视频的高度，单位 px
+@property(nonatomic, assign) uint32_t height;
-/// 帧率（fps）
-@property (nonatomic, assign) uint32_t frameRate;
+///【字段含义】本地视频的帧率，即每秒钟会有多少视频帧，单位：FPS
+@property(nonatomic, assign) uint32_t frameRate;
-/// 视频发送码率（Kbps）
-@property (nonatomic, assign) uint32_t videoBitrate;
+///【字段含义】远端视频的码率，即每秒钟新产生视频数据的多少，单位 Kbps
+@property(nonatomic, assign) uint32_t videoBitrate;
-/// 音频采样率（Hz）
-@property (nonatomic, assign) uint32_t audioSampleRate;
+///【字段含义】远端音频的采样率，单位 Hz
+@property(nonatomic, assign) uint32_t audioSampleRate;
-/// 音频发送码率（Kbps）
-@property (nonatomic, assign) uint32_t audioBitrate;
+///【字段含义】本地音频的码率，即每秒钟新产生音频数据的多少，单位 Kbps
+@property(nonatomic, assign) uint32_t audioBitrate;
-/// 流类型（大画面 | 小画面 | 辅路画面）
-@property (nonatomic, assign) TRTCVideoStreamType streamType;
+///【字段含义】视频流类型（高清大画面|低清小画面|辅流画面）
+@property(nonatomic, assign) TRTCVideoStreamType streamType;
-/// 音频设备采集状态，用于检测外接音频设备的健康度
+///【字段含义】音频设备采集状态（用于检测音频外设的健康度）
/// 0：采集设备状态正常；1：检测到长时间静音；2：检测到破音；3：检测到声音异常间断。
-@property (nonatomic, assign) uint32_t audioCaptureState;
+@property(nonatomic, assign) uint32_t audioCaptureState;
@end
+/// @}
+/////////////////////////////////////////////////////////////////////////////////
+//
+// 远端的音视频统计指标
+//
+/////////////////////////////////////////////////////////////////////////////////
+/// @name 远端的音视频统计指标
+/// @{
-/// 远端成员的音视频统计信息
@interface TRTCRemoteStatistics : NSObject
-/// 用户 ID，指定是哪个用户的视频流
-@property (nonatomic, retain) NSString* userId;
+///【字段含义】用户 ID
+@property(nonatomic, retain) NSString* userId;
+
+///【字段含义】音频流的总丢包率（％）
+/// audioPacketLoss 代表音频流历经“主播 => 云端 => 观众”这样一条完整的传输链路后，最终在观众端统计到的丢包率。
+/// audioPacketLoss 越小越好，丢包率为0即表示该路音频流的所有数据均已经完整地到达了观众端。
+///如果出现了 downLoss == 0 但 audioPacketLoss != 0 的情况，说明该路音频流在“云端=>观众”这一段链路上没有出现丢包，但是在“主播=>云端”这一段链路上出现了不可恢复的丢包。
+@property(nonatomic, assign) uint32_t audioPacketLoss;
-/// 该线路的总丢包率（％）
-/// 这个值越小越好，例如，丢包率为0表示网络很好。
-/// 丢包率是该线路的 userId 从上行到服务器再到下行的总丢包率。
-/// 如果 downLoss 为0，但是 finalLoss 不为0，说明该 userId 上行时出现了无法恢复的丢包。
-@property (nonatomic, assign) uint32_t finalLoss;
+///【字段含义】该路视频流的总丢包率（％）
+/// videoPacketLoss 代表该路视频流历经“主播 => 云端 => 观众”这样一条完整的传输链路后，最终在观众端统计到的丢包率。
+/// videoPacketLoss 越小越好，丢包率为0即表示该路视频流的所有数据均已经完整地到达了观众端。
+///如果出现了 downLoss == 0 但 videoPacketLoss != 0 的情况，说明该路视频流在“云端=>观众”这一段链路上没有出现丢包，但是在“主播=>云端”这一段链路上出现了不可恢复的丢包。
+@property(nonatomic, assign) uint32_t videoPacketLoss;
-/// 视频宽度
-@property (nonatomic, assign) uint32_t width;
+///【字段含义】远端视频的宽度，单位 px
+@property(nonatomic, assign) uint32_t width;
-/// 视频高度
-@property (nonatomic, assign) uint32_t height;
+///【字段含义】远端视频的高度，单位 px
+@property(nonatomic, assign) uint32_t height;
-/// 接收帧率（fps）
-@property (nonatomic, assign) uint32_t frameRate;
+///【字段含义】远端视频的帧率，单位：FPS
+@property(nonatomic, assign) uint32_t frameRate;
-/// 视频码率（Kbps）
-@property (nonatomic, assign) uint32_t videoBitrate;
+///【字段含义】远端视频的码率，单位 Kbps
+@property(nonatomic, assign) uint32_t videoBitrate;
-/// 音频采样率（Hz）
-@property (nonatomic, assign) uint32_t audioSampleRate;
+///【字段含义】本地音频的采样率，单位 Hz
+@property(nonatomic, assign) uint32_t audioSampleRate;
-/// 音频码率（Kbps）
-@property (nonatomic, assign) uint32_t audioBitrate;
+///【字段含义】本地音频的码率，单位 Kbps
+@property(nonatomic, assign) uint32_t audioBitrate;
-/// 播放时延（ms）
-@property (nonatomic, assign) uint32_t jitterBufferDelay;
+///【字段含义】播放延迟，单位 ms
+///为了避免网络抖动和网络包乱序导致的声音和画面卡顿，TRTC 会在播放端管理一个播放缓冲区，用于对接收到的网络数据包进行整理，
+///该缓冲区的大小会根据当前的网络质量进行自适应调整，该缓冲区的大小折算成以毫秒为单位的时间长度，也就是 jitterBufferDelay。
+@property(nonatomic, assign) uint32_t jitterBufferDelay;
-/// 端对端延迟（ms）
-/// 该字段为全链路延迟统计，链路包含：采集->编码->网络传输->接收->缓冲->解码->播放
-/// 延迟以 audio 为基准进行计算。需要本地和远端均为8.5版本以上时才生效
-/// 若远端用户为低版本，对应延迟会回调为0，此时代表无效值
-@property (nonatomic, assign) uint32_t point2PointDelay;
+///【字段含义】端到端延迟，单位 ms
+/// point2PointDelay 代表 “主播=>云端=>观众” 的延迟，更准确地说，它代表了“采集=>编码=>网络传输=>接收=>缓冲=>解码=>播放” 全链路的延迟。
+/// point2PointDelay 需要本地和远端的 SDK 均为 8.5 及以上的版本才生效，若远端用户为 8.5 以前的版本，此数值会一直为0，代表无意义。
+@property(nonatomic, assign) uint32_t point2PointDelay;
-/// 音频播放卡顿累计时长（ms）
-@property (nonatomic, assign) uint32_t audioTotalBlockTime;
+///【字段含义】音频播放的累计卡顿时长，单位 ms
+@property(nonatomic, assign) uint32_t audioTotalBlockTime;
-/// 音频播放卡顿率，音频卡顿的累计时长占音频总播放时长的百分比 (%)
-@property (nonatomic, assign) uint32_t audioBlockRate;
+///【字段含义】音频播放卡顿率，单位 (%)
+///音频播放卡顿率（audioBlockRate） = 音频播放的累计卡顿时长（audioTotalBlockTime） / 音频播放的总时长
+@property(nonatomic, assign) uint32_t audioBlockRate;
-/// 视频播放卡顿累计时长（ms）
-@property (nonatomic, assign) uint32_t videoTotalBlockTime;
+///【字段含义】视频播放的累计卡顿时长，单位 ms
+@property(nonatomic, assign) uint32_t videoTotalBlockTime;
-/// 音频播放卡顿率，视频卡顿累计时长占视频总播放时长的百分比（%）
-@property (nonatomic, assign) uint32_t videoBlockRate;
+///【字段含义】视频播放卡顿率，单位 (%)
+///视频播放卡顿率（videoBlockRate） = 视频播放的累计卡顿时长（videoTotalBlockTime） / 视频播放的总时长
+@property(nonatomic, assign) uint32_t videoBlockRate;
-/// 流类型（大画面 | 小画面 | 辅路画面）
-@property (nonatomic, assign) TRTCVideoStreamType streamType;
+///【字段含义】该路音视频流的总丢包率（％）
+///已废弃，不推荐使用；建议使用 audioPacketLoss、videoPacketLoss 替代
+@property(nonatomic, assign) uint32_t finalLoss __attribute__((deprecated("Use audioPacketLoss and videoPacketLoss instead.")));
+///【字段含义】视频流类型（高清大画面|低清小画面|辅流画面）
+@property(nonatomic, assign) TRTCVideoStreamType streamType;
@end
+/// @}
+/////////////////////////////////////////////////////////////////////////////////
+//
+// 网络和性能的汇总统计指标
+//
+/////////////////////////////////////////////////////////////////////////////////
+/// @name 网络和性能的汇总统计指标
+/// @{
-/// 统计数据
@interface TRTCStatistics : NSObject
-/// C -> S 上行丢包率（％），
-/// 该值越小越好，例如，丢包率为 0 表示网络很好，
-/// 丢包率为 30@% 则意味着 SDK 向服务器发送的数据包中会有 30@% 丢失在上行传输中。
-@property (nonatomic, assign) uint32_t upLoss;
+///【字段含义】当前应用的 CPU 使用率，单位 (%)
+@property(nonatomic, assign) uint32_t appCpu;
+
+///【字段含义】当前系统的 CPU 使用率，单位 (%)
+@property(nonatomic, assign) uint32_t systemCpu;
-/// S -> C 下行丢包率（％），
-/// 该值越小越好，例如，丢包率为0表示网络很好，
-/// 丢包率为 30@% 则意味着 SDK 向服务器发送的数据包中会有 30@% 丢失在下行传输中。
-@property (nonatomic, assign) uint32_t downLoss;
+///【字段含义】从 SDK 到云端的上行丢包率，单位 (%)
+///该数值越小越好，如果 upLoss 为 0%，则意味着上行链路的网络质量很好，上传到云端的数据包基本不发生丢失。
+///如果 upLoss 为 30%，则意味着 SDK 向云端发送的音视频数据包中，会有 30% 丢失在传输链路中。
+@property(nonatomic, assign) uint32_t upLoss;
-/// 当前 App 的 CPU 使用率（％）
-@property (nonatomic, assign) uint32_t appCpu;
+///【字段含义】从云端到 SDK 的下行丢包率，单位 (%)
+///该数值越小越好，如果 downLoss 为 0%，则意味着下行链路的网络质量很好，从云端接收的数据包基本不发生丢失。
+///如果 downLoss 为 30%，则意味着云端向 SDK 传输的音视频数据包中，会有 30% 丢失在传输链路中。
+@property(nonatomic, assign) uint32_t downLoss;
-/// 当前系统的 CPU 使用率（％）
-@property (nonatomic, assign) uint32_t systemCpu;
+///【字段含义】从 SDK 到云端的往返延时，单位 ms
+///该数值代表从 SDK 发送一个网络包到云端，再从云端回送一个网络包到 SDK 的总计耗时，也就是一个网络包经历 “SDK=>云端=>SDK” 的总耗时。
+///该数值越小越好：如果 rtt < 50ms，意味着较低的音视频通话延迟；如果 rtt > 200ms，则意味着较高的音视频通话延迟。
+///需要特别解释的是，rtt 代表 “SDK=>云端=>SDK” 的总耗时，所不需要区分 upRtt 和 downRtt。
+@property(nonatomic, assign) uint32_t rtt;
-/// 延迟（毫秒），
-/// 指 SDK 到腾讯云服务器的一次网络往返时间，该值越小越好。
-/// 一般低于 50ms 的 rtt 相对理想，而高于 100ms 的 rtt 会引入较大的通话延时。
-/// 由于数据上下行共享一条网络连接，所以 local 和 remote 的 rtt 相同。
-@property (nonatomic, assign) uint32_t rtt;
+///【字段含义】从 SDK 到本地路由器的往返时延，单位 ms
+///该数值代表从 SDK 发送一个网络包到本地路由器网关，再从网关回送一个网络包到 SDK 的总计耗时，也就是一个网络包经历 “SDK=>网关=>SDK” 的总耗时。
+///该数值越小越好：如果 gatewayRtt < 50ms，意味着较低的音视频通话延迟；如果 gatewayRtt > 200ms，则意味着较高的音视频通话延迟。
+///当网络类型为蜂窝网时，该值无效。
+@property(nonatomic, assign) uint32_t gatewayRtt;
-/// 总接收字节数（包含信令及音视频）
-@property (nonatomic, assign) uint64_t receivedBytes;
+///【字段含义】总发送字节数（包含信令数据和音视频数据），单位：字节数（Bytes）
+@property(nonatomic, assign) uint64_t sentBytes;
-/// 总发送字节数（包含信令及音视频）
-@property (nonatomic, assign) uint64_t sentBytes;
+///【字段含义】总接收字节数（包含信令数据和音视频数据），单位：字节数（Bytes）
+@property(nonatomic, assign) uint64_t receivedBytes;
-/// 自己本地的音视频统计信息，可能有主画面、小画面以及辅路画面等多路的情况，因此是一个数组
-@property (nonatomic, strong) NSArray<TRTCLocalStatistics*>* localStatistics;
+///【字段含义】本地的音视频统计信息
+///由于本地可能有三路音视频流（即高清大画面，低清小画面，以及辅流画面），因此本地的音视频统计信息是一个数组。
+@property(nonatomic, strong) NSArray<TRTCLocalStatistics*>* localStatistics;
+
+///【字段含义】远端的音视频统计信息
+///因为同时可能有多个远端用户，而且每个远端用户同时可能有多路音视频流（即高清大画面，低清小画面，以及辅流画面），因此远端的音视频统计信息是一个数组。
+@property(nonatomic, strong) NSArray<TRTCRemoteStatistics*>* remoteStatistics;
-/// 远端成员的音视频统计信息，可能有主画面、小画面以及辅路画面等多路的情况，因此是一个数组
-@property (nonatomic, strong) NSArray<TRTCRemoteStatistics*>* remoteStatistics;
@end
-///@}
+/// @}
+
+/// @}
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXAudioCustomProcessDelegate.h b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXAudioCustomProcessDelegate.h
old mode 100755
new mode 100644
index 9155c38..9155c38
--- a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXAudioCustomProcessDelegate.h
+++ b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXAudioCustomProcessDelegate.h
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXAudioEffectManager.h b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXAudioEffectManager.h
old mode 100755
new mode 100644
index 4c0de36..1ad0a1a
--- a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXAudioEffectManager.h
+++ b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXAudioEffectManager.h
@@ -1,155 +1,275 @@
-/*
-* Module: TXAudioEffectManager 音乐和人声设置类
-*
-* Function: 用于音乐、短音效和人声效果功能的使用
-*
-*/
-
+/**
+ * Module: TRTC 背景音乐、短音效和人声特效的管理类
+ * Function: 用于对背景音乐、短音效和人声特效进行设置的管理类
+ */
+/// @defgroup TXAudioEffectManager_ios TXAudioEffectManager
+/// TRTC 背景音乐、短音效和人声特效的管理类
+/// @{
#import <Foundation/Foundation.h>
-NS_ASSUME_NONNULL_BEGIN
+/////////////////////////////////////////////////////////////////////////////////
+//
+// 音效相关的枚举值定义
+//
+/////////////////////////////////////////////////////////////////////////////////
+/// @name 音效相关的枚举值定义
+/// @{
+
+/**
+ * 1.1 混响特效
+ *
+ * 混响特效可以作用于人声之上，通过声学算法对声音进行叠加处理，模拟出各种不同环境下的临场感受，目前支持如下几种混响效果：
+ * 0：关闭；1：KTV；2：小房间；3：大会堂；4：低沉；5：洪亮；6：金属声；7：磁性；8：空灵；9：录音棚；10：悠扬。
+ */
+typedef NS_ENUM(NSInteger, TXVoiceReverbType) {
+ TXVoiceReverbType_0 = 0, ///< disable
+ TXVoiceReverbType_1 = 1, ///< KTV
+ TXVoiceReverbType_2 = 2, ///< small room
+ TXVoiceReverbType_3 = 3, ///< great hall
+ TXVoiceReverbType_4 = 4, ///< deep voice
+ TXVoiceReverbType_5 = 5, ///< loud voice
+ TXVoiceReverbType_6 = 6, ///< metallic sound
+ TXVoiceReverbType_7 = 7, ///< magnetic sound
+ TXVoiceReverbType_8 = 8, ///< ethereal
+ TXVoiceReverbType_9 = 9, ///< studio
+ TXVoiceReverbType_10 = 10, ///< melodious
+};
+
+/**
+ * 1.2 变声特效
+ *
+ * 变声特效可以作用于人声之上，通过声学算法对人声进行二次处理，以获得与原始声音所不同的音色，目前支持如下几种变声特效：
+ * 0：关闭；1：熊孩子；2：萝莉；3：大叔；4：重金属；5：感冒；6：外语腔；7：困兽；8：肥宅；9：强电流；10：重机械；11：空灵。
+ */
+typedef NS_ENUM(NSInteger, TXVoiceChangeType) {
+ TXVoiceChangeType_0 = 0, ///< disable
+ TXVoiceChangeType_1 = 1, ///< naughty kid
+ TXVoiceChangeType_2 = 2, ///< Lolita
+ TXVoiceChangeType_3 = 3, ///< uncle
+ TXVoiceChangeType_4 = 4, ///< heavy metal
+ TXVoiceChangeType_5 = 5, ///< catch cold
+ TXVoiceChangeType_6 = 6, ///< foreign accent
+ TXVoiceChangeType_7 = 7, ///< caged animal trapped beast
+ TXVoiceChangeType_8 = 8, ///< indoorsman
+ TXVoiceChangeType_9 = 9, ///< strong current
+ TXVoiceChangeType_10 = 10, ///< heavy machinery
+ TXVoiceChangeType_11 = 11, ///< intangible
+};
+
+/// @}
+/////////////////////////////////////////////////////////////////////////////////
+//
+// 背景音乐的播放事件回调
+//
+/////////////////////////////////////////////////////////////////////////////////
+/// @name 背景音乐的事件回调接口
+/// @{
+
+// Playback progress block of background music
+///背景音乐开始播放
typedef void (^TXAudioMusicStartBlock)(NSInteger errCode);
+
+///背景音乐的播放进度
typedef void (^TXAudioMusicProgressBlock)(NSInteger progressMs, NSInteger durationMs);
+
+///背景音乐已经播放完毕
typedef void (^TXAudioMusicCompleteBlock)(NSInteger errCode);
-@class TXAudioMusicParam;
-typedef NS_ENUM(NSInteger, TXVoiceChangeType);
-typedef NS_ENUM(NSInteger, TXVoiceReverbType);
+/// @}
+/////////////////////////////////////////////////////////////////////////////////
+//
+// 背景音乐的播放控制信息
+//
+/////////////////////////////////////////////////////////////////////////////////
+/// @name 背景音乐的播放控制信息
+/// @{
+/**
+ * 背景音乐的播放控制信息
+ *
+ * 该信息用于在接口 {@link startPlayMusic} 中指定背景音乐的相关信息，包括播放 ID、文件路径和循环次数等：
+ * 1. 如果要多次播放同一首背景音乐，请不要每次播放都分配一个新的 ID，我们推荐使用相同的 ID。
+ * 2. 若您希望同时播放多首不同的音乐，请为不同的音乐分配不同的 ID 进行播放。
+ * 3. 如果使用同一个 ID 播放不同音乐，SDK 会先停止播放旧的音乐，再播放新的音乐。
+ */
+@interface TXAudioMusicParam : NSObject
+
+///【字段含义】音乐 ID <br/>
+///【特殊说明】SDK 允许播放多路音乐，因此需要使用 ID 进行标记，用于控制音乐的开始、停止、音量等。
+@property(nonatomic) int32_t ID;
+
+///【字段含义】音效文件的完整路径或 URL 地址。支持的音频格式包括 MP3、AAC、M4A、WAV
+@property(nonatomic, copy) NSString *path;
+
+///【字段含义】音乐循环播放的次数 <br/>
+///【推荐取值】取值范围为0 - 任意正整数，默认值：0。0表示播放音乐一次；1表示播放音乐两次；以此类推
+@property(nonatomic) NSInteger loopCount;
+
+///【字段含义】是否将音乐传到远端 <br/>
+///【推荐取值】YES：音乐在本地播放的同时，远端用户也能听到该音乐；NO：主播只能在本地听到该音乐，远端观众听不到。默认值：NO。
+@property(nonatomic) BOOL publish;
+
+///【字段含义】播放的是否为短音乐文件 <br/>
+///【推荐取值】YES：需要重复播放的短音乐文件；NO：正常的音乐文件。默认值：NO
+@property(nonatomic) BOOL isShortFile;
+
+///【字段含义】音乐开始播放时间点，单位：毫秒。
+@property(nonatomic) NSInteger startTimeMS;
+
+///【字段含义】音乐结束播放时间点，单位毫秒，0表示播放至文件结尾。
+@property(nonatomic) NSInteger endTimeMS;
+@end
+/// @}
+
+// Definition of audio effect management module
@interface TXAudioEffectManager : NSObject
-/// TXAudioEffectManager对象不可直接创建
-/// 要通过 `TRTCCloud` 或 `TXLivePush` 的 `getAudioEffectManager` 接口获取
+/**
+ * TXAudioEffectManager对象不可直接被创建
+ * 要通过 `TRTCCloud` 或 `TXLivePush` 中的 `getAudioEffectManager` 接口获取
+ */
- (instancetype)init NS_UNAVAILABLE;
/////////////////////////////////////////////////////////////////////////////////
//
-// （一）人声相关特效函数
+// 人声相关的特效接口
//
/////////////////////////////////////////////////////////////////////////////////
-
-/// @name 人声相关特效函数
+/// @name 人声相关的特效接口
/// @{
-
+
/**
* 1.1 开启耳返
*
- * 开启后会在耳机里听到自己的声音。
+ * 主播开启耳返后，可以在耳机里听到麦克风采集到的自己发出的声音，该特效适用于主播唱歌的应用场景中。
+ *
+ * 需要您注意的是，由于蓝牙耳机的硬件延迟非常高，所以在主播佩戴蓝牙耳机时无法开启此特效，请尽量在用户界面上提示主播佩戴有线耳机。
+ * 同时也需要注意，并非所有的手机开启此特效后都能达到优秀的耳返效果，我们已经对部分耳返效果不佳的手机屏蔽了该特效。
*
- * @note 仅在戴耳机时有效，暂时仅支持部分采集延迟较低的机型
- * @param enable true：开启；false：关闭
+ * @note 仅在主播佩戴耳机时才能开启此特效，同时请您提示主播佩戴有线耳机。
+ * @param enable true：开启；false：关闭。
*/
- (void)enableVoiceEarMonitor:(BOOL)enable;
/**
* 1.2 设置耳返音量
*
- * @param volume 音量大小，100为原始音量，范围是：[0 ~ 150]，默认值为100
+ * 通过该接口您可以设置耳返特效中声音的音量大小。
*
- * @note 如果要将 volume 设置为大于100的数值，需要进行特殊配置，请联系技术支持。
+ * @param volume 音量大小，取值范围为0 - 100，默认值：100。
+ * @note 如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。
*/
- (void)setVoiceEarMonitorVolume:(NSInteger)volume;
/**
- * 1.3 设置人声的混响效果（KTV、小房间、大会堂、低沉、洪亮...）
+ * 1.3 设置人声的混响效果
*
- * @note 设置的效果在退房后会失效，如果下次进房还需要对应特效，需要调用此接口再次设置。
+ * 通过该接口您可以设置人声的混响效果，具体特效请参考枚举定义{@link TXVoiceReverbType}。
+ *
+ * @note 设置的效果在退出房间后会自动失效，如果下次进房还需要对应特效，需要调用此接口再次进行设置。
*/
- (void)setVoiceReverbType:(TXVoiceReverbType)reverbType;
/**
- * 1.4 设置人声的变声特效（萝莉、大叔、重金属、外国人...）
+ * 1.4 设置人声的变声特效
+ *
+ * 通过该接口您可以设置人声的变声特效，具体特效请参考枚举定义{@link TXVoiceChangeType}。
*
- * @note 设置的效果在退房后会失效，如果下次进房还需要对应特效，需要调用此接口再次设置。
+ * @note 设置的效果在退出房间后会自动失效，如果下次进房还需要对应特效，需要调用此接口再次进行设置。
*/
- (void)setVoiceChangerType:(TXVoiceChangeType)changerType;
/**
- * 1.5 设置麦克风采集人声的音量
+ * 1.5 设置语音音量
*
- * @param volume 音量大小，100为原始音量，范围是：[0 ~ 150]，默认值为100
+ * 该接口可以设置语音音量的大小，一般配合音乐音量的设置接口 {@link setAllMusicVolume} 协同使用，用于调谐语音和音乐在混音前各自的音量占比。
*
- * @note 如果要将 volume 设置为大于100的数值，需要进行特殊配置，请联系技术支持。
+ * @param volume 音量大小，取值范围为0 - 100，默认值：100。
+ * @note 如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。
*/
- (void)setVoiceVolume:(NSInteger)volume;
/// @}
-
/////////////////////////////////////////////////////////////////////////////////
//
-// （二）背景音乐特效函数
+// 背景音乐的相关接口
//
/////////////////////////////////////////////////////////////////////////////////
-
-/// @name 人声相关特效函数
+/// @name 背景音乐的相关接口
/// @{
+
/**
* 2.1 开始播放背景音乐
*
* 每个音乐都需要您指定具体的 ID，您可以通过该 ID 对音乐的开始、停止、音量等进行设置。
*
- * @note 若您想同时播放多个音乐，请分配不同的 ID 进行播放。
- * 如果使用同一个 ID 播放不同音乐，SDK 会先停止播放旧的音乐，再播放新的音乐。
+ * @note
+ * 1. 如果要多次播放同一首背景音乐，请不要每次播放都分配一个新的 ID，我们推荐使用相同的 ID。
+ * 2. 若您希望同时播放多首不同的音乐，请为不同的音乐分配不同的 ID 进行播放。
+ * 3. 如果使用同一个 ID 播放不同音乐，SDK 会先停止播放旧的音乐，再播放新的音乐。
+ *
* @param musicParam 音乐参数
* @param startBlock 播放开始回调
* @param progressBlock 播放进度回调
* @param completeBlock 播放结束回调
*/
-- (void)startPlayMusic:(TXAudioMusicParam *)musicParam
- onStart:(TXAudioMusicStartBlock _Nullable)startBlock
- onProgress:(TXAudioMusicProgressBlock _Nullable)progressBlock
- onComplete:(TXAudioMusicCompleteBlock _Nullable)completeBlock;
+- (void)startPlayMusic:(TXAudioMusicParam *)musicParam onStart:(TXAudioMusicStartBlock _Nullable)startBlock onProgress:(TXAudioMusicProgressBlock _Nullable)progressBlock onComplete:(TXAudioMusicCompleteBlock _Nullable)completeBlock;
/**
* 2.2 停止播放背景音乐
*
- * @param id 音乐 ID
+ * @param id 音乐 ID
*/
- (void)stopPlayMusic:(int32_t)id;
/**
* 2.3 暂停播放背景音乐
*
- * @param id 音乐 ID
+ * @param id 音乐 ID
*/
- (void)pausePlayMusic:(int32_t)id;
/**
* 2.4 恢复播放背景音乐
*
- * @param id 音乐 ID
+ * @param id 音乐 ID
*/
- (void)resumePlayMusic:(int32_t)id;
/**
- * 2.5 设置背景音乐的远端音量大小，即主播可以通过此接口设置远端观众能听到的背景音乐的音量大小。
+ * 2.5 设置所有背景音乐的本地音量和远端音量的大小
*
- * @param id 音乐 ID
- * @param volume 音量大小，100为原始音量，范围是：[0 ~ 150]，默认值为100
+ * 该接口可以设置所有背景音乐的本地音量和远端音量。
+ * - 本地音量：即主播本地可以听到的背景音乐的音量大小。
+ * - 远端音量：即观众端可以听到的背景音乐的音量大小。
*
- * @note 如果要将 volume 设置为大于100的数值，需要进行特殊配置，请联系技术支持。
+ * @param volume 音量大小，取值范围为0 - 100，默认值：100。
+ * @note 如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。
*/
-- (void)setMusicPublishVolume:(int32_t)id volume:(NSInteger)volume;
+- (void)setAllMusicVolume:(NSInteger)volume;
/**
- * 2.6 设置背景音乐的本地音量大小，即主播可以通过此接口设置主播自己本地的背景音乐的音量大小。
+ * 2.6 设置某一首背景音乐的远端音量的大小
*
- * @param id 音乐 ID
- * @param volume 音量大小，100为原始音量，范围是：[0 ~ 150]，默认值为100
+ * 该接口可以细粒度地控制每一首背景音乐的远端音量，也就是观众端可听到的背景音乐的音量大小。
*
- * @note 如果要将 volume 设置为大于100的数值，需要进行特殊配置，请联系技术支持。
+ * @param id 音乐 ID
+ * @param volume 音量大小，取值范围为0 - 100；默认值：100
+ * @note 如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。
*/
-- (void)setMusicPlayoutVolume:(int32_t)id volume:(NSInteger)volume;
+- (void)setMusicPublishVolume:(int32_t)id volume:(NSInteger)volume;
/**
- * 2.7 设置全局背景音乐的本地和远端音量的大小
+ * 2.7 设置某一首背景音乐的本地音量的大小
*
- * @param volume 音量大小，100为原始音量，范围是：[0 ~ 150]，默认值为100
+ * 该接口可以细粒度地控制每一首背景音乐的本地音量，也就是主播本地可以听到的背景音乐的音量大小。
*
- * @note 如果要将 volume 设置为大于100的数值，需要进行特殊配置，请联系技术支持。
+ * @param id 音乐 ID
+ * @param volume 音量大小，取值范围为0 - 100，默认值：100。
+ * @note 如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。
*/
-- (void)setAllMusicVolume:(NSInteger)volume;
+- (void)setMusicPlayoutVolume:(int32_t)id volume:(NSInteger)volume;
/**
* 2.8 调整背景音乐的音调高低
@@ -168,7 +288,7 @@ typedef NS_ENUM(NSInteger, TXVoiceReverbType);
- (void)setMusicSpeedRate:(int32_t)id speedRate:(double)speedRate;
/**
- * 2.10 获取背景音乐当前的播放进度（单位：毫秒）
+ * 2.10 获取背景音乐的播放进度（单位：毫秒）
*
* @param id 音乐 ID
* @return 成功返回当前播放时间，单位：毫秒，失败返回-1
@@ -176,82 +296,25 @@ typedef NS_ENUM(NSInteger, TXVoiceReverbType);
- (NSInteger)getMusicCurrentPosInMS:(int32_t)id;
/**
- * 2.11 设置背景音乐的播放进度（单位：毫秒）
+ * 2.11 获取景音乐的总时长（单位：毫秒）
*
- * @note 请尽量避免频繁地调用该接口，因为该接口可能会再次读写音乐文件，耗时稍高。
- * 当配合进度条使用时，请在进度条拖动完毕的回调中调用，而避免在拖动过程中实时调用。
- *
- * @param id 音乐 ID
- * @param pts 单位: 毫秒
+ * @param path 音乐文件路径，如果 path 为空，那么返回当前正在播放的 music 时长。
+ * @return 成功返回时长，失败返回-1
*/
-- (void)seekMusicToPosInMS:(int32_t)id pts:(NSInteger)pts;
+- (NSInteger)getMusicDurationInMS:(NSString *)path;
/**
- * 2.12 获取景音乐文件的总时长（单位：毫秒）
+ * 2.12 设置背景音乐的播放进度（单位：毫秒）
*
- * @param path 音乐文件路径，如果 path 为空，那么返回当前正在播放的 music 时长。
- * @return 成功返回时长，失败返回-1
+ * @note 请尽量避免过度频繁地调用该接口，因为该接口可能会再次读写音乐文件，耗时稍高。
+ * 因此，当用户拖拽音乐的播放进度条时，请在用户完成拖拽操作后再调用本接口。
+ * 因为 UI 上的进度条控件往往会以很高的频率反馈用户的拖拽进度，如不做频率限制，会导致较差的用户体验。
+ *
+ * @param id 音乐 ID
+ * @param pts 单位: 毫秒
*/
-- (NSInteger)getMusicDurationInMS:(NSString *)path;
+- (void)seekMusicToPosInMS:(int32_t)id pts:(NSInteger)pts;
/// @}
-
-@end
-
-
-@interface TXAudioMusicParam : NSObject
-
-/// 【字段含义】音乐 ID
-/// 【特殊说明】SDK 允许播放多路音乐，因此需要音乐 ID 进行标记，用于控制音乐的开始、停止、音量等
-@property (nonatomic) int32_t ID;
-
-/// 【字段含义】音乐文件的绝对路径
-@property (nonatomic, copy) NSString *path;
-
-/// 【字段含义】音乐循环播放的次数
-/// 【推荐取值】取值范围为0 - 任意正整数，默认值：0。0表示播放音乐一次；1表示播放音乐两次；以此类推
-@property (nonatomic) NSInteger loopCount;
-
-/// 【字段含义】是否将音乐传到远端
-/// 【推荐取值】YES：音乐在本地播放的同时，会上行至云端，因此远端用户也能听到该音乐；NO：音乐不会上行至云端，因此只能在本地听到该音乐。默认值：NO
-@property (nonatomic) BOOL publish;
-
-/// 【字段含义】播放的是否为短音乐文件
-/// 【推荐取值】YES：需要重复播放的短音乐文件；NO：正常的音乐文件。默认值：NO
-@property (nonatomic) BOOL isShortFile;
-
-/// 【字段含义】音乐开始播放时间点，单位毫秒
-@property (nonatomic) NSInteger startTimeMS;
-
-/// 【字段含义】音乐结束播放时间点，单位毫秒，0或者-1表示播放至文件结尾。
-@property (nonatomic) NSInteger endTimeMS;
-
-@end
-
-typedef NS_ENUM(NSInteger, TXVoiceReverbType) {
- TXVoiceReverbType_0 = 0, ///< 关闭混响
- TXVoiceReverbType_1 = 1, ///< KTV
- TXVoiceReverbType_2 = 2, ///< 小房间
- TXVoiceReverbType_3 = 3, ///< 大会堂
- TXVoiceReverbType_4 = 4, ///< 低沉
- TXVoiceReverbType_5 = 5, ///< 洪亮
- TXVoiceReverbType_6 = 6, ///< 金属声
- TXVoiceReverbType_7 = 7, ///< 磁性
-};
-
-typedef NS_ENUM(NSInteger, TXVoiceChangeType) {
- TXVoiceChangeType_0 = 0, ///< 关闭变声
- TXVoiceChangeType_1 = 1, ///< 熊孩子
- TXVoiceChangeType_2 = 2, ///< 萝莉
- TXVoiceChangeType_3 = 3, ///< 大叔
- TXVoiceChangeType_4 = 4, ///< 重金属
- TXVoiceChangeType_5 = 5, ///< 感冒
- TXVoiceChangeType_6 = 6, ///< 外国人
- TXVoiceChangeType_7 = 7, ///< 困兽
- TXVoiceChangeType_8 = 8, ///< 死肥仔
- TXVoiceChangeType_9 = 9, ///< 强电流
- TXVoiceChangeType_10 = 10, ///< 重机械
- TXVoiceChangeType_11 = 11, ///< 空灵
-};
-
-NS_ASSUME_NONNULL_END
+@end // End of interface TXAudioEffectManager
+/// @}
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXAudioRawDataDelegate.h b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXAudioRawDataDelegate.h
old mode 100755
new mode 100644
index 9d834fe..9d834fe
--- a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXAudioRawDataDelegate.h
+++ b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXAudioRawDataDelegate.h
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXBeautyManager.h b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXBeautyManager.h
index da026e1..f5d733b 100644
--- a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXBeautyManager.h
+++ b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXBeautyManager.h
@@ -1,10 +1,7 @@
-/*
+/**
* Module: 美颜与图像处理参数设置类
- *
* Function: 修改美颜、滤镜、绿幕等参数
- *
*/
-
#import <Foundation/Foundation.h>
#import <TargetConditionals.h>
#if TARGET_OS_IPHONE
@@ -18,236 +15,287 @@ typedef NSImage TXImage;
NS_ASSUME_NONNULL_BEGIN
/// @defgroup TXBeautyManager_ios TXBeautyManager
-/// 美颜及动效参数管理
+/// 美颜与图像处理参数设置类
/// @{
/**
* 美颜（磨皮）算法
- * SDK 内置了多种不同的磨皮算法，您可以选择最适合您产品定位的方案。
+ * TRTC 内置多种不同的磨皮算法，您可以选择最适合您产品定位的方案。
*/
typedef NS_ENUM(NSInteger, TXBeautyStyle) {
- TXBeautyStyleSmooth = 0, ///< 光滑，适用于美女秀场，效果比较明显。
- TXBeautyStyleNature = 1, ///< 自然，磨皮算法更多地保留了面部细节，主观感受上会更加自然。
- TXBeautyStylePitu = 2 ///< 由上海优图实验室提供的美颜算法，磨皮效果介于光滑和自然之间，比光滑保留更多皮肤细节，比自然磨皮程度更高。
+
+ ///光滑，算法比较激进，磨皮效果比较明显，适用于秀场直播。
+ TXBeautyStyleSmooth = 0,
+
+ ///自然，算法更多地保留了面部细节，磨皮效果更加自然，适用于绝大多数直播场景。
+ TXBeautyStyleNature = 1,
+
+ ///优图，由优图实验室提供，磨皮效果介于光滑和自然之间，比光滑保留更多皮肤细节，比自然磨皮程度更高。
+ TXBeautyStylePitu = 2
};
-/// 美颜及动效参数管理
@interface TXBeautyManager : NSObject
/**
* 设置美颜（磨皮）算法
*
- * SDK 内部集成了两套风格不同的磨皮算法，一套我们取名叫“光滑”，适用于美女秀场，效果比较明显。
- * 另一套我们取名“自然”，磨皮算法更多地保留了面部细节，主观感受上会更加自然。
+ * TRTC 内置多种不同的磨皮算法，您可以选择最适合您产品定位的方案：
*
- * @param beautyStyle 美颜风格，光滑或者自然，光滑风格磨皮更加明显，适合娱乐场景。
+ * @param beautyStyle 美颜风格，TXBeautyStyleSmooth：光滑；TXBeautyStyleNature：自然；TXBeautyStylePitu：优图。
*/
- (void)setBeautyStyle:(TXBeautyStyle)beautyStyle;
/**
* 设置美颜级别
- * @param level 美颜级别，取值范围0 - 9； 0表示关闭，1 - 9值越大，效果越明显。
+ *
+ * @param beautyLevel 美颜级别，取值范围0 - 9； 0表示关闭，9表示效果最明显。
*/
-- (void)setBeautyLevel:(float)level;
+- (void)setBeautyLevel:(float)beautyLevel;
/**
* 设置美白级别
*
- * @param level 美白级别，取值范围0 - 9；0表示关闭，1 - 9值越大，效果越明显。
+ * @param whitenessLevel 美白级别，取值范围0 - 9；0表示关闭，9表示效果最明显。
*/
-- (void)setWhitenessLevel:(float)level;
+- (void)setWhitenessLevel:(float)whitenessLevel;
/**
* 开启清晰度增强
- *
- * @param enable YES：开启清晰度增强；NO：关闭清晰度增强。默认值：YES
*/
- (void)enableSharpnessEnhancement:(BOOL)enable;
/**
* 设置红润级别
*
- * @param level 红润级别，取值范围0 - 9；0表示关闭，1 - 9值越大，效果越明显。
+ * @param ruddyLevel 红润级别，取值范围0 - 9；0表示关闭，9表示效果最明显。
*/
-- (void)setRuddyLevel:(float)level;
+- (void)setRuddyLevel:(float)ruddyLevel;
/**
- * 设置指定素材滤镜特效
+ * 设置色彩滤镜效果
*
- * @param image 指定素材，即颜色查找表图片。**必须使用 png 格式**
+ * 色彩滤镜，是一副包含色彩映射关系的颜色查找表图片，您可以在我们提供的官方 Demo 中找到预先准备好的几张滤镜图片。
+ * SDK 会根据该查找表中的映射关系，对摄像头采集出的原始视频画面进行二次处理，以达到预期的滤镜效果。
+ * @param image 包含色彩映射关系的颜色查找表图片，必须是 png 格式。
*/
- (void)setFilter:(nullable TXImage *)image;
+
/**
- * 设置滤镜浓度
+ * 设置色彩滤镜的强度
*
- * 在美女秀场等应用场景里，滤镜浓度的要求会比较高，以便更加突显主播的差异。
- * 我们默认的滤镜浓度是0.5，如果您觉得滤镜效果不明显，可以使用下面的接口进行调节。
+ * 该数值越高，色彩滤镜的作用强度越明显，经过滤镜处理后的视频画面跟原画面的颜色差异越大。
+ * 我默认的滤镜浓度是0.5，如果您觉得默认的滤镜效果不明显，可以设置为 0.5 以上的数字，最大值为1。
*
- * @param strength 从0到1，越大滤镜效果越明显，默认值为0.5。
+ * @param strength 从0到1，数值越大滤镜效果越明显，默认值为0.5。
*/
- (void)setFilterStrength:(float)strength;
/**
* 设置绿幕背景视频，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
*
- * 此处的绿幕功能并非智能抠背，需要被拍摄者的背后有一块绿色的幕布来辅助产生特效
+ * 此接口所开启的绿幕功能不具备智能去除背景的能力，需要被拍摄者的背后有一块绿色的幕布来辅助产生特效。
*
- * @param file 视频文件路径。支持 MP4; nil 表示关闭特效。
+ * @param path MP4格式的视频文件路径; 设置空值表示关闭特效。
*/
-- (void)setGreenScreenFile:(nullable NSString *)file;
+- (void)setGreenScreenFile:(nullable NSString *)path;
-#if TARGET_OS_IPHONE
/**
* 设置大眼级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
*
- * @param level 大眼级别，取值范围0 - 9；0表示关闭，1 - 9值越大，效果越明显。
+ * @param eyeScaleLevel 大眼级别，取值范围0 - 9；0表示关闭，9表示效果最明显。
*/
-- (void)setEyeScaleLevel:(float)level;
+#if TARGET_OS_IPHONE
+- (void)setEyeScaleLevel:(float)eyeScaleLevel;
+#endif
/**
* 设置瘦脸级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
*
- * @param level 瘦脸级别，取值范围0 - 9；0表示关闭，1 - 9值越大，效果越明显。
+ * @param faceSlimLevel 瘦脸级别，取值范围0 - 9；0表示关闭，9表示效果最明显。
*/
-- (void)setFaceSlimLevel:(float)level;
+#if TARGET_OS_IPHONE
+- (void)setFaceSlimLevel:(float)faceSlimLevel;
+#endif
/**
- *设置 V 脸级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
+ * 设置 V 脸级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
*
- * @param level V脸级别，取值范围0 - 9；0表示关闭，1 - 9值越大，效果越明显。
+ * @param faceVLevel V脸级别，取值范围0 - 9；0表示关闭，9表示效果最明显。
*/
-- (void)setFaceVLevel:(float)level;
+#if TARGET_OS_IPHONE
+- (void)setFaceVLevel:(float)faceVLevel;
+#endif
/**
* 设置下巴拉伸或收缩，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
*
- * @param level 下巴拉伸或收缩级别，取值范围-9 - 9；0 表示关闭，小于0表示收缩，大于0表示拉伸。
+ * @param chinLevel 下巴拉伸或收缩级别，取值范围-9 - 9；0 表示关闭，小于0表示收缩，大于0表示拉伸。
*/
-- (void)setChinLevel:(float)level;
+#if TARGET_OS_IPHONE
+- (void)setChinLevel:(float)chinLevel;
+#endif
+
/**
* 设置短脸级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
*
- * @param level 短脸级别，取值范围0 - 9；0表示关闭，1 - 9值越大，效果越明显。
+ * @param faceShortLevel 短脸级别，取值范围0 - 9；0表示关闭，9表示效果最明显。
*/
-- (void)setFaceShortLevel:(float)level;
+#if TARGET_OS_IPHONE
+- (void)setFaceShortLevel:(float)faceShortLevel;
+#endif
/**
* 设置窄脸级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
*
- * @param level 短脸级别，取值范围0 - 9；0表示关闭，1 - 9值越大，效果越明显。
+ * @param level 窄脸级别，取值范围0 - 9；0表示关闭，9表示效果最明显。
*/
-- (void)setFaceNarrowLevel:(float)level;
+#if TARGET_OS_IPHONE
+- (void)setFaceNarrowLevel:(float)faceNarrowLevel;
+#endif
/**
* 设置瘦鼻级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
*
- * @param level 瘦鼻级别，取值范围0 - 9；0表示关闭，1 - 9值越大，效果越明显。
+ * @param noseSlimLevel 瘦鼻级别，取值范围0 - 9；0表示关闭，9表示效果最明显。
*/
-- (void)setNoseSlimLevel:(float)level;
+#if TARGET_OS_IPHONE
+- (void)setNoseSlimLevel:(float)noseSlimLevel;
+#endif
/**
- * 设置亮眼 ，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
+ * 设置亮眼级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
*
- * @param level 亮眼级别，取值范围0 - 9；0表示关闭，1 - 9值越大，效果越明显。
+ * @param eyeLightenLevel 亮眼级别，取值范围0 - 9；0表示关闭，9表示效果最明显。
*/
-- (void)setEyeLightenLevel:(float)level;
+#if TARGET_OS_IPHONE
+- (void)setEyeLightenLevel:(float)eyeLightenLevel;
+#endif
/**
- * 设置白牙 ，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
+ * 设置牙齿美白级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
*
- * @param level 白牙级别，取值范围0 - 9；0表示关闭，1 - 9值越大，效果越明显。
+ * @param toothWhitenLevel 白牙级别，取值范围0 - 9；0表示关闭，9表示效果最明显。
*/
-- (void)setToothWhitenLevel:(float)level;
+#if TARGET_OS_IPHONE
+- (void)setToothWhitenLevel:(float)toothWhitenLevel;
+#endif
/**
- * 设置祛皱 ，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
+ * 设置祛皱级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
*
- * @param level 祛皱级别，取值范围0 - 9；0表示关闭，1 - 9值越大，效果越明显。
+ * @param wrinkleRemoveLevel 祛皱级别，取值范围0 - 9；0表示关闭，9表示效果最明显。
*/
-- (void)setWrinkleRemoveLevel:(float)level;
+#if TARGET_OS_IPHONE
+- (void)setWrinkleRemoveLevel:(float)wrinkleRemoveLevel;
+#endif
/**
- * 设置祛眼袋 ，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
+ * 设置祛眼袋级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
*
- * @param level 祛眼袋级别，取值范围0 - 9；0表示关闭，1 - 9值越大，效果越明显。
+ * @param pounchRemoveLevel 祛眼袋级别，取值范围0 - 9；0表示关闭，9表示效果最明显。
*/
-- (void)setPounchRemoveLevel:(float)level;
+#if TARGET_OS_IPHONE
+- (void)setPounchRemoveLevel:(float)pounchRemoveLevel;
+#endif
/**
- * 设置法令纹 ，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
+ * 设置法令纹去除级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
*
- * @param level 法令纹级别，取值范围0 - 9；0表示关闭，1 - 9值越大，效果越明显。
+ * @param smileLinesRemoveLevel 法令纹级别，取值范围0 - 9；0表示关闭，9表示效果最明显。
*/
-- (void)setSmileLinesRemoveLevel:(float)level;
+#if TARGET_OS_IPHONE
+- (void)setSmileLinesRemoveLevel:(float)smileLinesRemoveLevel;
+#endif
/**
- * 设置发际线 ，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
+ * 设置发际线调整级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
*
- * @param level 发际线级别，取值范围-9 - 9；0表示关闭，小于0表示抬高，大于0表示降低。
+ * @param foreheadLevel 发际线级别，取值范围-9 - 9；0表示关闭，9表示效果最明显。
*/
-- (void)setForeheadLevel:(float)level;
+#if TARGET_OS_IPHONE
+- (void)setForeheadLevel:(float)foreheadLevel;
+#endif
/**
- * 设置眼距 ，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
+ * 设置眼距，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
*
- * @param level 眼距级别，取值范围-9 - 9；0表示关闭，小于0表示拉伸，大于0表示收缩。
+ * @param eyeDistanceLevel 眼距级别，取值范围-9 - 9；0表示关闭，小于0表示拉伸，大于0表示收缩。
*/
-- (void)setEyeDistanceLevel:(float)level;
+#if TARGET_OS_IPHONE
+- (void)setEyeDistanceLevel:(float)eyeDistanceLevel;
+#endif
/**
- * 设置眼角 ，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
+ * 设置眼角调整级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
*
- * @param level 眼角级别，取值范围-9 - 9；0表示关闭，小于0表示降低，大于0表示抬高。
+ * @param eyeAngleLevel 眼角调整级别，取值范围-9 - 9；0表示关闭，9表示效果最明显。
*/
-- (void)setEyeAngleLevel:(float)level;
+#if TARGET_OS_IPHONE
+- (void)setEyeAngleLevel:(float)eyeAngleLevel;
+#endif
/**
- * 设置嘴型 ，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
+ * 设置嘴型调整级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
*
- * @param level 嘴型级别，取值范围-9 - 9；0表示关闭，小于0表示拉伸，大于0表示收缩。
+ * @param mouthShapeLevel 嘴型级别，取值范围-9 - 9；0表示关闭，小于0表示拉伸，大于0表示收缩。
*/
-- (void)setMouthShapeLevel:(float)level;
+#if TARGET_OS_IPHONE
+- (void)setMouthShapeLevel:(float)mouthShapeLevel;
+#endif
/**
- * 设置鼻翼 ，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
+ * 设置鼻翼调整级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
*
- * @param level 鼻翼级别，取值范围-9 - 9；0表示关闭，小于0表示拉伸，大于0表示收缩。
+ * @param noseWingLevel 鼻翼调整级别，取值范围-9 - 9；0表示关闭，小于0表示拉伸，大于0表示收缩。
*/
-- (void)setNoseWingLevel:(float)level;
+#if TARGET_OS_IPHONE
+- (void)setNoseWingLevel:(float)noseWingLevel;
+#endif
/**
- * 设置鼻子位置 ，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
- * @param level 鼻子位置级别，取值范围-9 - 9；0表示关闭，小于0表示抬高，大于0表示降低。
+ * 设置鼻子位置，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
+ *
+ * @param nosePositionLevel 鼻子位置级别，取值范围-9 - 9；0表示关闭，小于0表示抬高，大于0表示降低。
*/
-- (void)setNosePositionLevel:(float)level;
+#if TARGET_OS_IPHONE
+- (void)setNosePositionLevel:(float)nosePositionLevel;
+#endif
/**
- * 设置嘴唇厚度 ，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
- * @param level 嘴唇厚度级别，取值范围-9 - 9；0表示关闭，小于0表示拉伸，大于0表示收缩。
+ * 设置嘴唇厚度，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
+ *
+ * @param lipsThicknessLevel 嘴唇厚度级别，取值范围-9 - 9；0表示关闭，小于0表示拉伸，大于0表示收缩。
*/
-- (void)setLipsThicknessLevel:(float)level;
+#if TARGET_OS_IPHONE
+- (void)setLipsThicknessLevel:(float)lipsThicknessLevel;
+#endif
/**
* 设置脸型，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
- * @param level 美型级别，取值范围0 - 9；0表示关闭，1 - 9值越大，效果越明显。
+ *
+ * @param faceBeautyLevel 美型级别，取值范围0 - 9；0表示关闭，1 - 9值越大，效果越明显。
*/
-- (void)setFaceBeautyLevel:(float)level;
+#if TARGET_OS_IPHONE
+- (void)setFaceBeautyLevel:(float)faceBeautyLevel;
+#endif
/**
* 选择 AI 动效挂件，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
*
- * @param tmplName 动效名称
- * @param tmplDir 动效所在目录
+ * @param tmplName 动效挂件名称
+ * @param tmplDir 动效素材文件所在目录
*/
+#if TARGET_OS_IPHONE
- (void)setMotionTmpl:(nullable NSString *)tmplName inDir:(nullable NSString *)tmplDir;
+#endif
/**
- * 设置动效静音，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
- *
+ * 是否在动效素材播放时静音，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
* 有些挂件本身会有声音特效，通过此 API 可以关闭这些特效播放时所带的声音效果。
*
* @param motionMute YES：静音；NO：不静音。
*/
+#if TARGET_OS_IPHONE
- (void)setMotionMute:(BOOL)motionMute;
#endif
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXDeviceManager.h b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXDeviceManager.h
old mode 100755
new mode 100644
index a3068e7..55039fb
--- a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXDeviceManager.h
+++ b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXDeviceManager.h
@@ -1,283 +1,294 @@
-/*
-* Module: TXDeviceManager 设备管理类
-*
-* Function: 用于管理 iOS / Mac 的硬件设备
-*
-*/
+/**
+ * Module: TRTC 音视频设备管理模块
+ * Function: 用于管理摄像头、麦克风和扬声器等音视频相关的硬件设备
+ */
+/// @defgroup TXDeviceManager_ios TXDeviceManager
+/// TRTC 音视频设备管理模块
+/// @{
#import <Foundation/Foundation.h>
+#if TARGET_OS_IPHONE
+#import <UIKit/UIKit.h>
+#elif TARGET_OS_MAC
+#import <AppKit/AppKit.h>
+#endif
-NS_ASSUME_NONNULL_BEGIN
+/////////////////////////////////////////////////////////////////////////////////
+//
+// 音视频设备相关的类型定义
+//
+/////////////////////////////////////////////////////////////////////////////////
+/// @name 音视频设备相关的类型定义
+/// @{
+/**
+ * 系统音量类型（仅适用于移动设备）
+ *
+ * 现代智能手机中一般都具备两套系统音量类型，即“通话音量”和“媒体音量”。
+ * - 通话音量：手机专门为接打电话所设计的音量类型，自带回声抵消（AEC）功能，并且支持通过蓝牙耳机上的麦克风进行拾音，缺点是音质比较一般。
+ * 当您通过手机侧面的音量按键下调手机音量时，如果无法将其调至零（也就是无法彻底静音），说明您的手机当前出于通话音量。
+ * - 媒体音量：手机专门为音乐场景所设计的音量类型，无法使用系统的 AEC 功能，并且不支持通过蓝牙耳机的麦克风进行拾音，但具备更好的音乐播放效果。
+ * 当您通过手机侧面的音量按键下调手机音量时，如果能够将手机音量调至彻底静音，说明您的手机当前出于媒体音量。
+ *
+ * SDK 目前提供了三种系统音量类型的控制模式：自动切换模式、全程通话音量模式、全程媒体音量模式。
+ */
#if TARGET_OS_IPHONE
+typedef NS_ENUM(NSInteger, TXSystemVolumeType) {
-/// 系统音量类型
-typedef NS_ENUM(NSInteger, TXSystemVolumeType);
-/// 声音播放模式（音频路由）
-typedef NS_ENUM(NSInteger, TXAudioRoute);
+ ///自动切换模式：
+ ///也被称为“麦上通话，麦下媒体”，即主播上麦时使用通话音量，观众不上麦则使用媒体音量，适合在线直播场景。
+ TXSystemVolumeTypeAuto = 0,
-#elif TARGET_OS_MAC
+ ///全程媒体音量：
+ ///通话全程使用媒体音量，并不是非常常用的音量类型，适用于对音质要求比较苛刻的音乐场景中。
+ ///如果您的用户大都使用外接设备（比如外接声卡）为主，可以使用该模式，否则请慎用。
+ TXSystemVolumeTypeMedia = 1,
-/// 设备类型
-typedef NS_ENUM(NSInteger, TXMediaDeviceType);
-/// 设备描述
-@class TXMediaDeviceInfo;
+ ///全程通话音量：
+ ///该方案的优势在于用户在上下麦时音频模块无需切换工作模式，可以做到无缝上下麦，适合于用户需要频繁上下麦的应用场景。
+ TXSystemVolumeTypeVOIP = 2,
+};
#endif
+/**
+ * 音频路由（即声音的播放模式）
+ *
+ * 音频路由，即声音是从手机的扬声器还是从听筒中播放出来，因此该接口仅适用于手机等移动端设备。
+ * 手机有两个扬声器：一个是位于手机顶部的听筒，一个是位于手机底部的立体声扬声器。
+ * - 设置音频路由为听筒时，声音比较小，只有将耳朵凑近才能听清楚，隐私性较好，适合用于接听电话。
+ * - 设置音频路由为扬声器时，声音比较大，不用将手机贴脸也能听清，因此可以实现“免提”的功能。
+ */
+#if TARGET_OS_IPHONE
+typedef NS_ENUM(NSInteger, TXAudioRoute) {
-@interface TXDeviceManager : NSObject
+ /// Speakerphone：使用扬声器播放（即“免提”），扬声器位于手机底部，声音偏大，适合外放音乐。
+ TXAudioRouteSpeakerphone = 0,
-- (instancetype)init NS_UNAVAILABLE;
+ /// Earpiece：使用听筒播放，听筒位于手机顶部，声音偏小，适合需要保护隐私的通话场景。
+ TXAudioRouteEarpiece = 1,
-#if TARGET_OS_IPHONE
+};
+#endif
/**
- * 判断当前是否为前置摄像头
+ * 设备类型（仅适用于桌面平台）
+ *
+ * 该枚举值用于定义三种类型的音视频设备，即摄像头、麦克风和扬声器，以便让一套设备管理接口可以操控三种不同类型的设备。
+ */
+#if TARGET_OS_MAC && !TARGET_OS_IPHONE
+typedef NS_ENUM(NSInteger, TXMediaDeviceType) {
+ TXMediaDeviceTypeUnknown = -1, ///< undefined device type
+ TXMediaDeviceTypeAudioInput = 0, ///< microphone
+ TXMediaDeviceTypeAudioOutput = 1, ///< speaker or earpiece
+ TXMediaDeviceTypeVideoCamera = 2, ///< camera
+};
+#endif
+
+/**
+ * 音视频设备的相关信息（仅适用于桌面平台）
+ *
+ * 该结构体用于描述一个音视频设备的关键信息，比如设备ID、设备名称等等，以便用户能够在用户界面上选择自己期望使用的音视频设备。
+ */
+#if TARGET_OS_MAC && !TARGET_OS_IPHONE
+@interface TXMediaDeviceInfo : NSObject
+/// device type
+@property(assign, nonatomic) TXMediaDeviceType type;
+/// device id
+@property(copy, nonatomic, nullable) NSString *deviceId;
+/// device name
+@property(copy, nonatomic, nullable) NSString *deviceName;
+@end
+#endif
+/// @}
+
+@interface TXDeviceManager : NSObject
+
+/////////////////////////////////////////////////////////////////////////////////
+//
+// 移动端设备操作接口（iOS Android）
+//
+/////////////////////////////////////////////////////////////////////////////////
+/// @name 移动端设备操作接口
+/// @{
+
+/**
+ * 1.1 判断当前是否为前置摄像头（仅适用于移动端）
*/
+#if TARGET_OS_IPHONE
- (BOOL)isFrontCamera;
/**
- * 切换摄像头
+ * 1.2 切换前置或后置摄像头（仅适用于移动端）
*/
- (NSInteger)switchCamera:(BOOL)frontCamera;
/**
- * 查询当前摄像头是否支持缩放
+ * 1.3 查询当前摄像头是否支持缩放（仅适用于移动端）
*/
- (BOOL)isCameraZoomSupported;
/**
- * 查询当前摄像头支持的最大缩放比例
+ * 1.3 获取摄像头的最大缩放倍数（仅适用于移动端）
*/
- (CGFloat)getCameraZoomMaxRatio;
/**
- * 设置当前摄像头的缩放比例
+ * 1.4 设置摄像头的缩放倍数（仅适用于移动端）
*
* @param zoomRatio 取值范围1 - 5，取值为1表示最远视角（正常镜头），取值为5表示最近视角（放大镜头）。
- * 最大值推荐为5，若超过5，视频数据会变得模糊不清。默认值为1。
*/
- (NSInteger)setCameraZoomRatio:(CGFloat)zoomRatio;
/**
- * 查询是否支持自动识别人脸位置
+ * 1.5 查询是否支持自动识别人脸位置（仅适用于移动端）
*/
- (BOOL)isAutoFocusEnabled;
/**
- * 设置人脸自动识别
+ * 1.6 开启自动对焦功能（仅适用于移动端）
*
- * @param enabled YES: 开启；NO：关闭，默认值：YES
+ * 开启后，SDK 会自动检测画面中的人脸位置，并将摄像头的焦点始终对焦在人脸位置上。
*/
- (NSInteger)enableCameraAutoFocus:(BOOL)enabled;
/**
- * 设置摄像头焦点
+ * 1.7 设置摄像头的对焦位置（仅适用于移动端）
*
- * @param position 对焦位置
+ * 您可以通过该接口实现如下交互：
+ * 1. 在本地摄像头的预览画面上，允许用户单击操作。
+ * 2. 在用户的单击位置显示一个矩形方框，以示摄像头会在此处对焦。
+ * 3. 随后将用户点击位置的坐标通过本接口传递给 SDK，之后 SDK 会操控摄像头按照用户期望的位置进行对焦。
+ * @note 使用该接口的前提是先通过 {@link enableCameraAutoFocus} 关闭自动对焦功能。
+ * @param position 对焦位置，请传入期望对焦点的坐标值
+ * @return 0：操作成功；负数：操作失败。
*/
- (NSInteger)setCameraFocusPosition:(CGPoint)position;
/**
- * 查询是否支持开关闪光灯（手电筒模式）
+ * 1.8 查询是否支持开启闪光灯（仅适用于移动端）
*/
- (BOOL)isCameraTorchSupported;
/**
- * 开关闪光灯
- *
- * enabled YES：开启；NO：关闭，默认值：NO
+ * 1.8 开启/关闭闪光灯，也就是手电筒模式（仅适用于移动端）
*/
- (NSInteger)enableCameraTorch:(BOOL)enabled;
/**
- * 设置通话时使用的系统音量类型
- *
- * @note
- * 1. 需要在调用 startLocalAudio() 之前调用该接口。
- * 2. 如无特殊需求，不推荐您自行设置，您只需通过 enterRoom 设置好适合您的场景，SDK 内部会自动选择相匹配的音量类型。
+ * 1.9 设置音频路由（仅适用于移动端）
*
- * @param type 系统音量类型，参见 TXSystemVolumeType 说明。如无特殊需求，不推荐您自行设置。
+ * 手机有两个音频播放设备：一个是位于手机顶部的听筒，一个是位于手机底部的立体声扬声器。
+ * 设置音频路由为听筒时，声音比较小，只有将耳朵凑近才能听清楚，隐私性较好，适合用于接听电话。
+ * 设置音频路由为扬声器时，声音比较大，不用将手机贴脸也能听清，因此可以实现“免提”的功能。
*/
-- (NSInteger)setSystemVolumeType:(TXSystemVolumeType)type;
+- (NSInteger)setAudioRoute:(TXAudioRoute)route;
/**
- * 设置音频路由
- *
- * 微信和手机 QQ 视频通话功能的免提模式就是基于音频路由实现的。
- * 一般手机都有两个扬声器，一个是位于顶部的听筒扬声器，声音偏小；一个是位于底部的立体声扬声器，声音偏大。
- * 设置音频路由的作用就是决定声音使用哪个扬声器播放。
- *
- * @param route 音频路由，即声音由哪里输出（扬声器、听筒），默认值：TXAudioRouteSpeakerphone
+ * 1.10 设置系统音量类型（仅适用于移动端）
*/
-- (NSInteger)setAudioRoute:(TXAudioRoute)route;
+- (NSInteger)setSystemVolumeType:(TXSystemVolumeType)type;
+#endif
-#elif TARGET_OS_MAC
+/// @}
+/////////////////////////////////////////////////////////////////////////////////
+//
+// 桌面端设备操作接口（Windows Mac）
+//
+/////////////////////////////////////////////////////////////////////////////////
+/// @name 桌面端设备操作接口
+/// @{
/**
- * 获取设备列表
- *
- * @param type 设备类型
+ * 2.1 获取设备列表（仅适用于桌面端）
*/
-- (NSArray<TXMediaDeviceInfo *> * _Nullable)getDevicesList:(TXMediaDeviceType)type;
+#if !TARGET_OS_IPHONE && TARGET_OS_MAC
+- (NSArray<TXMediaDeviceInfo *> *_Nullable)getDevicesList:(TXMediaDeviceType)type;
/**
- * 设置要使用的设备
+ * 2.2 设置当前要使用的设备（仅适用于桌面端）
*
- * @param type 设备类型
- * @param deviceId 从 getDevicesList 中得到的设备 ID
+ * @param type 设备类型，详见 TXMediaDeviceType 定义。
+ * @param deviceId 设备ID，您可以通过接口 {@link getDevicesList} 获得设备 ID。
+ * @return 0：操作成功；负数：操作失败。
*/
- (NSInteger)setCurrentDevice:(TXMediaDeviceType)type deviceId:(NSString *)deviceId;
/**
- * 获取当前的设备信息
- *
- * @param type 设备类型
+ * 2.3 获取当前正在使用的设备（仅适用于桌面端）
*/
-- (TXMediaDeviceInfo * _Nullable)getCurrentDevice:(TXMediaDeviceType)type;
+- (TXMediaDeviceInfo *_Nullable)getCurrentDevice:(TXMediaDeviceType)type;
/**
- * 设置当前设备的音量
+ * 2.4 设置当前设备的音量（仅适用于桌面端）
*
- * @param volume 音量值，范围0 - 100
- * @param type 设备类型，仅支持 AudioInput 和 AudioOutput 类型。
+ * 这里的音量指的是麦克风的采集音量或者扬声器的播放音量，摄像头是不支持设置音量的。
+ *
+ * @param volume 音量大小，取值范围为0 - 100，默认值：100。
+ * @note 如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。
*/
- (NSInteger)setCurrentDeviceVolume:(NSInteger)volume deviceType:(TXMediaDeviceType)type;
/**
- * 获取当前设备的音量
+ * 2.5 获取当前设备的音量（仅适用于桌面端）
*
- * @param type 设备类型，仅支持 AudioInput 和 AudioOutput 类型。
+ * 这里的音量指的是麦克风的采集音量或者扬声器的播放音量，摄像头是不支持获取音量的。
*/
- (NSInteger)getCurrentDeviceVolume:(TXMediaDeviceType)type;
/**
- * 设置当前设备的静音状态
+ * 2.6 设置当前设备的静音状态（仅适用于桌面端）
*
- * @param mute 设置为 YES 时，麦克风设备静音
- * @param type 设备类型，仅支持 AudioInput 和 AudioOutput 类型。
+ * 这里的音量指的是麦克风和扬声器，摄像头是不支持静音操作的。
*/
- (NSInteger)setCurrentDeviceMute:(BOOL)mute deviceType:(TXMediaDeviceType)type;
/**
- * 获取当前设备的静音状态
+ * 2.7 获取当前设备的静音状态（仅适用于桌面端）
*
- * @param type 设备类型，仅支持 AudioInput 和 AudioOutput 类型。
+ * 这里的音量指的是麦克风和扬声器，摄像头是不支持静音操作的。
*/
- (BOOL)getCurrentDeviceMute:(TXMediaDeviceType)type;
/**
- * 开始摄像头测试
+ * 2.8 开始摄像头测试（仅适用于桌面端）
*
- * @note 在测试过程中可以使用 setCurrentCameraDevice 接口切换摄像头。
- * @param view 预览画面所在的父控件
+ * @note 在测试过程中可以使用 {@link setCurrentDevice} 接口切换摄像头。
*/
- (NSInteger)startCameraDeviceTest:(NSView *)view;
/**
- * 结束摄像头测试
+ * 2.9 结束摄像头测试（仅适用于桌面端）
*/
- (NSInteger)stopCameraDeviceTest;
/**
- * 开始麦克风测试
+ * 2.10 开始麦克风测试（仅适用于桌面端）
*
- * 该方法测试麦克风是否能正常工作，volume 的取值范围为0 - 100。
+ * 该接口可以测试麦克风是否能正常工作，测试到的麦克风采集音量的大小，会以回调的形式通知给您，其中 volume 的取值范围为0 - 100。
+ * @param interval 麦克风音量的回调间隔。
*/
- (NSInteger)startMicDeviceTest:(NSInteger)interval testEcho:(void (^)(NSInteger volume))testEcho;
/**
- * 结束麦克风测试
+ * 2.11 结束麦克风测试（仅适用于桌面端）
*/
- (NSInteger)stopMicDeviceTest;
/**
- * 开始扬声器测试
+ * 2.12 开始扬声器测试（仅适用于桌面端）
*
- * 该方法播放指定的音频文件测试播放设备是否能正常工作。如果能听到声音，说明播放设备能正常工作。
+ * 该接口通过播放指定的音频文件，用于测试播放设备是否能正常工作。如果用户在测试时能听到声音，说明播放设备能正常工作。
+ * @param filePath 声音文件的路径
*/
- (NSInteger)startSpeakerDeviceTest:(NSString *)audioFilePath onVolumeChanged:(void (^)(NSInteger volume, BOOL isLastFrame))volumeBlock;
/**
- * 结束扬声器测试
+ * 2.13 结束扬声器测试（仅适用于桌面端）
*/
- (NSInteger)stopSpeakerDeviceTest;
-
#endif
+/// @}
@end
-
-#if TARGET_OS_IPHONE
-/**
- * 系统音量类型
- *
- * 智能手机一般具备两种系统音量类型，即通话音量类型和媒体音量类型。
- * - 通话音量：手机专门为通话场景设计的音量类型，使用手机自带的回声抵消功能，音质相比媒体音量类型较差，
- * 无法通过音量按键将音量调成零，但是支持蓝牙耳机上的麦克风。
- *
- * - 媒体音量：手机专门为音乐场景设计的音量类型，音质相比于通话音量类型要好，通过通过音量按键可以将音量调成零。
- * 使用媒体音量类型时，如果要开启回声抵消（AEC）功能，SDK 会开启内置的声学处理算法对声音进行二次处理。
- * 在媒体音量模式下，蓝牙耳机无法使用自带的麦克风采集声音，只能使用手机上的麦克风进行声音采集。
- *
- * SDK 目前提供了三种系统音量类型的控制模式，分别为：
- * - Auto：“麦上通话，麦下媒体”，即主播上麦时使用通话音量，观众不上麦则使用媒体音量，适合在线直播场景。
- * 如果您在 enterRoom 时选择的场景为 TRTCAppSceneLIVE 或 TRTCAppSceneVoiceChatRoom，SDK 会自动选择该模式。
- *
- * - VOIP：全程使用通话音量，适合多人会议场景。
- * 如果您在 enterRoom 时选择的场景为 TRTCAppSceneVideoCall 或 TRTCAppSceneAudioCall，SDK 会自动选择该模式。
- *
- * - Media：通话全程使用媒体音量，不常用，适合个别有特殊需求（如主播外接声卡）的应用场景。
- *
- */
-typedef NS_ENUM(NSInteger, TXSystemVolumeType) {
- TXSystemVolumeTypeAuto = 0,
- TXSystemVolumeTypeMedia = 1,
- TXSystemVolumeTypeVOIP = 2,
-};
-
-
-/**
- * 声音播放模式（音频路由）
- *
- * 微信和手机 QQ 里的视频通话功能，都有一个免提模式，开启后就不用把手机贴在耳朵上，这个功能就是基于音频路由实现的。
- * 一般手机都有两个扬声器，设置音频路由的作用就是要决定声音从哪个扬声器播放出来：
- * - Speakerphone：扬声器，位于手机底部，声音偏大，适合外放音乐。
- * - Earpiece：听筒，位于手机顶部，声音偏小，适合通话。
- */
-typedef NS_ENUM(NSInteger, TXAudioRoute) {
- TXAudioRouteSpeakerphone = 0, ///< 扬声器
- TXAudioRouteEarpiece = 1, ///< 听筒
-};
-
-
-#elif TARGET_OS_MAC
-/**
- * 设备类型（仅 Mac）
- *
- * 在 Mac 上，每一种类型的设备都可能有多个，TRTC SDK 的 Mac 版本提供了一系列函数用来操作这些设备。
- */
-typedef NS_ENUM(NSInteger, TXMediaDeviceType) {
- TXMediaDeviceTypeUnknown = -1, ///< 未定义
- TXMediaDeviceTypeAudioInput = 0, ///< 麦克风
- TXMediaDeviceTypeAudioOutput = 1, ///< 扬声器或听筒
- TXMediaDeviceTypeVideoCamera = 2, ///< 摄像头
-};
-
-/**
- * 设备描述
- *
- * 在 Mac 上，每一种类型的设备都可能有多个，TRTC SDK 的 Mac 版本提供了一系列函数用来操作这些设备。
- */
-@interface TXMediaDeviceInfo : NSObject
-/// 设备类型
-@property (assign, nonatomic) TXMediaDeviceType type;
-/// 设备ID
-@property (copy, nonatomic, nullable) NSString *deviceId;
-/// 设备名称
-@property (copy, nonatomic, nullable) NSString *deviceName;
-@end
-
-#endif
-
-NS_ASSUME_NONNULL_END
+/// @}
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiteAVBuffer.h b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiteAVBuffer.h
old mode 100755
new mode 100644
index 5ca84ea..5ca84ea
--- a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiteAVBuffer.h
+++ b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiteAVBuffer.h
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiteAVCode.h b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiteAVCode.h
index b806455..2867fa5 100644
--- a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiteAVCode.h
+++ b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiteAVCode.h
@@ -188,6 +188,7 @@ typedef enum TXLiteAVError
ERR_ROOM_REQUEST_CLOSE_VIDEO_TIMEOUT = -3313, ///< 请求关闭视频超时
ERR_ROOM_REQUEST_SET_RECEIVE_TIMEOUT = -3314, ///< 请求接收视频项超时
ERR_ROOM_REQUEST_TOKEN_INVALID_PARAMETER = -3315, ///< 请求 token 无效参数，请检查 TRTCParams.userSig 是否填写正确
+ ERR_ROOM_REQUEST_EXIT_ROOM_WHEN_ENTERING_ROOM = -3341, ///< 进房尚未成功时，收到了退房请求
ERR_ROOM_REQUEST_AES_TOKEN_RETURN_ERROR = -3329, ///< 请求 AES TOKEN 时，server 返回的内容是空的
ERR_ACCIP_LIST_EMPTY = -3331, ///< 请求接口机 IP 返回的列表为空的
@@ -406,6 +407,8 @@ typedef enum TXLiteAVEvent
EVT_MIC_RELEASE_SUCC = 2029, ///< 释放麦克风占用
EVT_AUDIO_DEVICE_ROUTE_CHANGED = 2030, ///< 音频设备的route发生改变，即当前的输入输出设备发生改变，比如耳机被拔出
EVT_PLAY_GET_FLVSESSIONKEY = 2031, ///< TXLivePlayer 接收到http响应头中的 flvSessionKey 信息
+ EVT_AUDIO_SESSION_INTERRUPT = 2032, ///< Audio Session Interrupt事件
+
EVT_ROOM_ENTER = 1018, ///< 进入房间成功
EVT_ROOM_EXIT = 1019, ///< 退出房间
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiteAVEncodedDataProcessingListener.h b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiteAVEncodedDataProcessingListener.h
old mode 100755
new mode 100644
index 33e79d2..33e79d2
--- a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiteAVEncodedDataProcessingListener.h
+++ b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiteAVEncodedDataProcessingListener.h
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiteAVSDK.h b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiteAVSDK.h
old mode 100755
new mode 100644
index eddca64..eddca64
--- a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiteAVSDK.h
+++ b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiteAVSDK.h
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiveAudioSessionDelegate.h b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiveAudioSessionDelegate.h
old mode 100755
new mode 100644
index 2d6ed36..b59fcb7
--- a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiveAudioSessionDelegate.h
+++ b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiveAudioSessionDelegate.h
@@ -35,6 +35,9 @@
@optional
- (BOOL)overrideOutputAudioPort:(AVAudioSessionPortOverride)portOverride error:(NSError **)outError;
+@optional
+- (BOOL)setPreferredInput:(nullable AVAudioSessionPortDescription *)inPort error:(NSError **)outError;
+
#endif
@end
#endif /* TXLiveAudioSessionDelegate_h */
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiveBase.h b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiveBase.h
index 3bf1326..7497a4f 100644
--- a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiveBase.h
+++ b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiveBase.h
@@ -30,6 +30,12 @@ typedef NS_ENUM(NSInteger, TX_Enum_Type_LogLevel) {
*/
- (void)onLog:(NSString*)log LogLevel:(int)level WhichModule:(NSString*)module;
+/**
+ * @brief NTP 校时回调，调用 TXLiveBase updateNetworkTime 后会触发
+ * @param errCode 0：表示校时成功且偏差在30ms以内，1：表示校时成功但偏差可能在 30ms 以上，-1：表示校时失败
+ */
+- (void)onUpdateNetworkTime:(int)errCode message:(NSString *)errMsg;
+
@end
@interface TXLiveBase : NSObject
@@ -50,9 +56,9 @@ typedef NS_ENUM(NSInteger, TX_Enum_Type_LogLevel) {
*/
+ (int)setGlobalEnv:(const char *)env_config;
-/** 设置log输出级别
+/**
+ * 设置 log 输出级别
* @param level 参见 LOGLEVEL
- *
*/
+ (void)setLogLevel:(TX_Enum_Type_LogLevel)level;
@@ -66,25 +72,56 @@ typedef NS_ENUM(NSInteger, TX_Enum_Type_LogLevel) {
+ (void)setAudioSessionDelegate:(id<TXLiveAudioSessionDelegate>)delegate;
-/// 获取SDK版本信息
+/**
+ * @brief 获取 SDK 版本信息
+ * @return SDK 版本信息
+ */
+ (NSString *)getSDKVersionStr;
-/// 获取pitu版本信息
+/**
+ * @brief 获取 pitu 版本信息
+ * @return pitu 版本信息
+ */
+ (NSString *)getPituSDKVersion;
-/// 设置appID，云控使用
+/**
+ * @brief 设置 appID，云控使用
+ */
+ (void)setAppID:(NSString*)appID;
-/// 设置sdk的licence下载url和key
+/**
+ * @brief 设置 sdk 的 Licence 下载 url 和 key
+ */
+ (void)setLicenceURL:(NSString *)url key:(NSString *)key;
-/// 设置userId，用于数据上报
+/**
+ * @brief 设置 userId，用于数据上报
+ */
+ (void)setUserId:(NSString *)userId;
-/// 获取 Licence 信息
+/**
+ * @brief 获取 Licence 信息
+ * @return Licence 信息
+ */
+ (NSString *)getLicenceInfo;
-/// 设置HEVC外部解码器工厂实例
+/**
+ * @brief 设置 HEVC 外部解码器工厂实例
+ */
+ (void)setExternalDecoderFactory:(id)decoderFactory;
+/**
+ * 启动 NTP 校时服务
+ *
+ * @return 0：启动成功；< 0：启动失败
+ */
++ (NSInteger)updateNetworkTime;
+
+/**
+ * 获取 NTP 时间戳（毫秒），请在收到 onUpdateNetworkTime 回调后使用
+ *
+ * @return NTP 时间戳（毫秒），若返回 0：未启动 NTP 校时或校时失败，请重启校时
+ */
++ (NSInteger)getNetworkTimestamp;
+
@end
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLivePlayListener.h b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLivePlayListener.h
old mode 100755
new mode 100644
index 03e8629..03e8629
--- a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLivePlayListener.h
+++ b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLivePlayListener.h
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLivePlayer.h b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLivePlayer.h
index 97414d8..80f5b16 100644
--- a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLivePlayer.h
+++ b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLivePlayer.h
@@ -198,6 +198,14 @@ typedef NS_ENUM(NSInteger, TX_Enum_PlayType) {
*/
- (void)snapshot:(void (^)(TXImage *))snapshotCompletionBlock;
+/**
+ * 3.4 获取当前渲染帧 pts
+ *
+ * @return 0：当前未处于正在播放状态（例如：未起播）
+ * >0：当前渲染视频帧的 pts，处于正在播放状态 (单位: 毫秒)
+ */
+- (uint64_t)getCurrentRenderPts;
+
/// @}
/////////////////////////////////////////////////////////////////////////////////
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiveRecordListener.h b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiveRecordListener.h
old mode 100755
new mode 100644
index fd86b08..fd86b08
--- a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiveRecordListener.h
+++ b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiveRecordListener.h
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiveRecordTypeDef.h b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiveRecordTypeDef.h
old mode 100755
new mode 100644
index 7159c30..7159c30
--- a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiveRecordTypeDef.h
+++ b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiveRecordTypeDef.h
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiveSDKEventDef.h b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiveSDKEventDef.h
index dac1575..e89f121 100644
--- a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiveSDKEventDef.h
+++ b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiveSDKEventDef.h
@@ -73,6 +73,8 @@ enum EventID
PLAY_EVT_STREAM_SWITCH_SUCC = EVT_PLAY_LIVE_STREAM_SWITCH_SUCC, ///< 直播，切流成功（切流可以播放不同画面大小的视频）
PLAY_EVT_GET_METADATA = EVT_PLAY_GET_METADATA, ///< TXLivePlayer 接收到视频流中的 metadata 头信息（一条视频流仅触发一次）
PLAY_EVT_GET_FLVSESSIONKEY = EVT_PLAY_GET_FLVSESSIONKEY, ///< TXLivePlayer 接收到http响应头中的 flvSessionKey 信息
+ PLAY_EVT_AUDIO_SESSION_INTERRUPT = EVT_AUDIO_SESSION_INTERRUPT, ///< Audio Session Interrupt事件
+
PLAY_ERR_NET_DISCONNECT = ERR_PLAY_LIVE_STREAM_NET_DISCONNECT, ///< 直播，网络断连,且经多次重连抢救无效,可以放弃治疗,更多重试请自行重启播放
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiveSDKTypeDef.h b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiveSDKTypeDef.h
old mode 100755
new mode 100644
index ed121da..ed121da
--- a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiveSDKTypeDef.h
+++ b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXLiveSDKTypeDef.h
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXVideoCustomProcessDelegate.h b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXVideoCustomProcessDelegate.h
old mode 100755
new mode 100644
index 98be4fa..98be4fa
--- a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXVideoCustomProcessDelegate.h
+++ b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/TXVideoCustomProcessDelegate.h
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/cpp_interface/ITRTCCloud.h b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/cpp_interface/ITRTCCloud.h
index 13c09b8..bbde76a 100644
--- a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/cpp_interface/ITRTCCloud.h
+++ b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/cpp_interface/ITRTCCloud.h
@@ -1,25 +1,10 @@
+/**
+ * Module: TRTCCloud @ TXLiteAVSDK
+ * Function: 腾讯云 TRTC 主功能接口
+ * Version: 9.0.10433
+ */
#ifndef __ITRTCCLOUD_H__
#define __ITRTCCLOUD_H__
-/*
- * Module: ITRTCCloud @ TXLiteAVSDK
- *
- * SDK VERSION 8.6.10094
- *
- * Function: 腾讯云视频通话功能的主要接口类
- *
- * 创建/使用/销毁 ITRTCCloud 对象的示例代码：
- * <pre>
- * ITRTCCloud *trtcCloud = getTRTCShareInstance();
- * if(trtcCloud) {
- * std::string version(trtcCloud->getSDKVersion());
- * }
- * //
- * //
- * destroyTRTCShareInstance();
- * trtcCloud = nullptr;
- * </pre>
- */
-
#include "TRTCCloudCallback.h"
#include "TRTCTypeDef.h"
#include "ITXAudioEffectManager.h"
@@ -27,46 +12,40 @@
#ifdef _WIN32
#include "IDeprecatedTRTCCloud.h"
#include "TXLiteAVBase.h"
-#endif // _WIN32
-
+#endif
-namespace trtc {
+/// @defgroup TRTCCloud_cplusplus TRTCCloud
+/// 腾讯云 TRTC 主功能接口
+/// @{
+namespace liteav {
class ITRTCCloud;
}
-/// @defgroup ITRTCCloud_cplusplus ITRTCCloud
-/// 腾讯云视频通话功能的主要接口类
-/// @{
+/// Export the following C-style interface to facilitate “LoadLibrary()”
+/// You can use the following methods to create and destroy TRTCCloud instance：
+/// <pre>
+/// ITRTCCloud *trtcCloud = getTRTCShareInstance();
+/// if(trtcCloud) {
+/// std::string version(trtcCloud->getSDKVersion());
+/// }
+/// //
+/// //
+/// destroyTRTCShareInstance();
+/// trtcCloud = nullptr;
+/// </pre>
+///
extern "C" {
- /// @name 创建与销毁 ITRTCCloud 单例
- /// @{
-
+/// @name Exported C function
+/// @{
#ifdef __ANDROID__
- /**
- * @brief 用于动态加载 dll 时，获取 ITRTCCloud 对象指针。
- *
- * @return 返回 ITRTCCloud 单例对象的指针，注意：delete ITRTCCloud* 会编译错误，需要调用 destroyTRTCCloud 释放单例指针对象。
- * @param context Android 上下文，内部会转为 ApplicationContext 用于系统 API 调用，如果传入的 context 为空，内部会自动获取当前进程的 ApplicationContext
- * @note 本接口仅适用于 Android 平台
- */
- TRTC_API trtc::ITRTCCloud* getTRTCShareInstance(void *context);
+TRTC_API liteav::ITRTCCloud* getTRTCShareInstance(void* context);
#else
- /**
- * @brief 用于动态加载 dll 时，获取 ITRTCCloud 对象指针。
- *
- * @return 返回 ITRTCCloud 单例对象的指针，注意：delete ITRTCCloud* 会编译错误，需要调用 destroyTRTCCloud 释放单例指针对象。
- * @note 本接口适用于 Windows、Mac、iOS 平台
- */
- TRTC_API trtc::ITRTCCloud* getTRTCShareInstance();
+TRTC_API liteav::ITRTCCloud* getTRTCShareInstance();
#endif
- /**
- * @brief 释放 ITRTCCloud 单例对象。
- */
- TRTC_API void destroyTRTCShareInstance();
- /// @}
+TRTC_API void destroyTRTCShareInstance();
+/// @}
}
-
-namespace trtc {
+namespace liteav {
class ITRTCCloud
#ifdef _WIN32
@@ -76,735 +55,738 @@ class ITRTCCloud
protected:
virtual ~ITRTCCloud(){};
-public:
- /////////////////////////////////////////////////////////////////////////////////
- //
+ public:
+/////////////////////////////////////////////////////////////////////////////////
+//
+// 创建实例和事件回调
+//
+/////////////////////////////////////////////////////////////////////////////////
+/// @name 创建实例和事件回调
+/// @{
+
+/**
+ * 1.1 创建 TRTCCloud 实例（单例模式）
+ *
+ * @param context 仅适用于 Android 平台，SDK 内部会将其转化为 Android 平台的 ApplicationContext 用于调用 Androud System API。
+ * 如果传入的 context 参数为空，SDK 内部会自动获取当前进程的 ApplicationContext。
+ * @note
+ * 1. 如果您使用 delete ITRTCCloud* 会导致编译错误，请使用 destroyTRTCCloud 释放对象指针。
+ * 2. 在 Windows、Mac 和 iOS 平台上，请调用 getTRTCShareInstance() 接口。
+ * 3. 在 Android 平台上，请调用 getTRTCShareInstance(void *context) 接口。
+ */
+#ifdef __ANDROID__
+ TRTC_API static liteav::ITRTCCloud* getTRTCShareInstance(void* context);
+#else
+ TRTC_API static liteav::ITRTCCloud* getTRTCShareInstance();
+#endif
- // 设置 TRTCCloudCallback 回调
- //
- /////////////////////////////////////////////////////////////////////////////////
- /// @name 设置 ITRTCCloudCallback 回调
- /// @{
/**
- * 设置回调接口 ITRTCCloudCallback
- *
- * 您可以通过 ITRTCCloudCallback 获得来自 SDK 的各种状态通知，详见 ITRTCCloudCallback.h 中的定义
+ * 1.2 销毁 TRTCCloud 实例（单例模式）
+ */
+ TRTC_API static void destroyTRTCShareInstance();
+
+ /**
+ * 1.3 设置 TRTC 事件回调
*
- * @param callback 事件回调指针
+ * 您可以通过 {@link TRTCCloudDelegate} 获得来自 SDK 的各类事件通知（比如：错误码，警告码，音视频状态参数等）。
*/
virtual void addCallback(ITRTCCloudCallback* callback) = 0;
/**
- * 移除事件回调
+ * 1.4 移除 TRTC 事件回调
*
- * @param callback 事件回调指针
+ * @param callback
*/
virtual void removeCallback(ITRTCCloudCallback* callback) = 0;
- /// @}
+ /// @}
/////////////////////////////////////////////////////////////////////////////////
//
- // （一）房间相关接口函数
+ // 房间相关接口函数
//
/////////////////////////////////////////////////////////////////////////////////
/// @name 房间相关接口函数
/// @{
+
/**
- * 1.1 进入房间
+ * 2.1 进入房间
*
- * 调用接口后，您会收到来自 ITRTCCloudCallback 中的 onEnterRoom(result) 回调:
- * - 如果加入成功，result 会是一个正数（result > 0），表示加入房间的时间消耗，单位是毫秒（ms）。
- * - 如果加入失败，result 会是一个负数（result < 0），表示进房失败的错误码。
+ * TRTC 的所有用户都需要进入房间才能“发布”或“订阅”音视频流，“发布”是指将自己的音频和视频推送到云端，“订阅”是指从云端拉取房间里其他用户的音视频流。
+ * 调用该接口时，您需要指定您的应用场景 {@link TRTCAppScene} 以获取最佳的音视频传输体验，这些场景可以分成两大类：
*
- * 进房失败的错误码含义请参见[错误码](https://cloud.tencent.com/document/product/647/32257)。
+ * 【直播场景（Live）】
+ * - 包括 {@link TRTCAppSceneLIVE} 和 {@link TRTCAppSceneVoiceChatRoom}：
+ * - 此类场景下，每一个房间最多同时容纳 10 万人，但需要您通过 {@link TRTCParams} 中的 “role” 字段设定用户是“主播”（{@link TRTCRoleAnchor}）还是“观众”（{@link TRTCRoleAudience}）。
+ * - 主播可以“发布”自己的音视频流，观众只能“订阅”别人的音视频流，每一个用户都可以在主播和观众两种角色间通过 {@link switchRole} 接口进行切换。
+ * - 适用于[视频低延时直播]、[十万人互动课堂]、[直播PK]、[音乐直播间]、[在线K歌]、[远程培训]、[超大型会议]等业务形态。
*
- * - {@link TRTCAppSceneVideoCall}：<br>
- * 视频通话场景，支持720P、1080P高清画质，单个房间最多支持300人同时在线，最高支持50人同时发言。<br>
- * 适合：[1对1视频通话]、[300人视频会议]、[在线问诊]、[远程面试]等。<br>
- * - {@link TRTCAppSceneAudioCall}：<br>
- * 语音通话场景，支持 48kHz，支持双声道。单个房间最多支持300人同时在线，最高支持50人同时发言。<br>
- * 适合：[1对1语音通话]、[300人语音会议]、[在线狼人杀]、[语音聊天室]等。<br>
- * - {@link TRTCAppSceneLIVE}：<br>
- * 视频互动直播，支持平滑上下麦，切换过程无需等待，主播延时小于300ms；支持十万级别观众同时播放，播放延时低至1000ms。<br>
- * 适合：[在线互动课堂]、[互动直播]、[视频相亲]、[远程培训]、[超大型会议]等。<br>
- * - {@link TRTCAppSceneVoiceChatRoom}：<br>
- * 语音互动直播，支持平滑上下麦，切换过程无需等待，主播延时小于300ms；支持十万级别观众同时播放，播放延时低至1000ms。<br>
- * 适合：[语聊房]、[K 歌房]、[FM 电台]等。<br>
+ * 【实时场景（RTC）】
+ * - 包括 {@link TRTCAppSceneVideoCall} 和 {@link TRTCAppSceneAudioCall}：
+ * - 此类场景下，每一个房间最多同时容纳 300 人在线，最高支持 50 人同时发言。
+ * - 适用于 [1对1视频通话]、[300人视频会议]、[在线问诊]、[语音聊天]、[教育小班课]、[远程面试]、[在线狼人杀]等业务形态。
*
- * @param param 进房参数，请参考 trtc::TRTCParams
- * @param scene 应用场景，目前支持视频通话（VideoCall）、在线直播（Live）、语音通话（AudioCall）、语音聊天室（VoiceChatRoom）四种场景。
+ * 调用该接口后，您会收到来自 {@link TRTCCloudDelegate} 中的 onEnterRoom(result) 回调:
+ * - 如果进房成功，参数 result 会是一个正数（result > 0），表示从函数调用到进入房间所花费的时间，单位是毫秒（ms）。
+ * - 如果进房失败，参数 result 会是一个负数（result < 0），表示进房失败的[错误码](https://cloud.tencent.com/document/product/647/32257)。
*
+ * @param param 进房参数，用于指定用户的身份、角色和安全票据等信息，详情请参考 {@link TRTCParams} 。
+ * @param scene 应用场景，用于指定您的业务场景，同一个房间内的所有用户需要设定相同的 {@link TRTCAppScene}。
* @note
- * 1. 当 scene 选择为 TRTCAppSceneLIVE 或 TRTCAppSceneVoiceChatRoom 时，您必须通过 TRTCParams 中的 role 字段指定当前用户的角色。<br>
- * 2. 不管进房是否成功，enterRoom 都必须与 exitRoom 配对使用，在调用 exitRoom 前再次调用 enterRoom 函数会导致不可预期的错误问题。
+ * 1. 同一个房间内的所有用户需要设定相同的 scene。不同的 scene 会导致偶现的异常问题。
+ * 2. 当您指定参数 scene 为 {@link TRTCAppSceneLIVE} 或 {@link TRTCAppSceneVoiceChatRoom} 时，您必须通过 {@link TRTCParams} 中的 “role” 字段为当前用户设定他/她在房间中的角色。
+ * 3. 请您尽量保证 {@link enterRoom} 与 {@link exitRoom} 前后配对使用，即保证”先退出前一个房间再进入下一个房间”，否则会导致很多异常问题。
*/
- virtual void enterRoom(const TRTCParams& params, TRTCAppScene scene) = 0;
+ virtual void enterRoom(const TRTCParams& param, TRTCAppScene scene) = 0;
/**
- * 1.2 离开房间
+ * 2.2 离开房间
*
- * 调用 exitRoom() 接口会执行退出房间的相关逻辑，例如释放音视频设备资源和编解码器资源等。
- * 待资源释放完毕，SDK 会通过 ITRTCCloudCallback 中的 onExitRoom() 回调通知您。
- *
- * 如果您要再次调用 enterRoom() 或者切换到其他的音视频 SDK，请等待 onExitRoom() 回调到来后再执行相关操作。
- * 否则可能会遇到如摄像头、麦克风设备被强占等各种异常问题。
+ * 调用该接口会让用户离开自己所在的音视频房间，并释放摄像头、麦克风、扬声器等设备资源。
+ * 等资源释放完毕之后，SDK 会通过 {@link TRTCCloudDelegate} 中的 onExitRoom() 回调向您通知。
+ * 如果您要再次调用 {@link enterRoom} 或者切换到其他的供应商的 SDK，建议等待 onExitRoom() 回调到来之后再执行之后的操作，以避免摄像头或麦克风被占用的问题。
*/
virtual void exitRoom() = 0;
/**
- * 1.3 切换角色，仅适用于直播场景（TRTCAppSceneLIVE 和 TRTCAppSceneVoiceChatRoom）
- *
- * 在直播场景下，一个用户可能需要在“观众”和“主播”之间来回切换。
- * 您可以在进房前通过 TRTCParams 中的 role 字段确定角色，也可以通过 switchRole 在进房后切换角色。
+ * 2.3 切换角色
*
- * @param role 目标角色，默认为主播：
- * - {@link TRTCRoleAnchor} 主播，可以上行视频和音频，一个房间里最多支持50个主播同时上行音视频。
- * - {@link TRTCRoleAudience} 观众，只能观看，不能上行视频和音频，一个房间里的观众人数没有上限。
+ * 调用本接口可以实现用户在“主播”和“观众”两种角色之间来回切换。
+ * 由于视频直播和语音聊天室需要支持多达10万名观众同时观看，所以设定了“只有主播才能发布自己的音视频”的规则。
+ * 因此，当有些观众希望发布自己的音视频流（以便能跟主播互动）时，就需要先把自己的角色切换成“主播”。
+ * 您可以在进入房间时通过 {@link TRTCParams} 中的 role 字段事先确定用户的角色，也可以在进入房间后通过 switchRole 接口动态切换角色。
+ * @param role 角色，默认为“主播”：
+ * - {@link TRTCRoleAnchor} ：主播，可以发布自己的音视频，同一个房间里最多支持50个主播同时发布音视频。
+ * - {@link TRTCRoleAudience} ：观众，不能发布自己的音视频流，只能观看房间中其他主播的音视频。如果要发布自己的音视频，需要先通过 {@link switchRole} 切换成“主播”，同一个房间内同时最多可以容纳 10 万名观众。
+ * @note
+ * 1. 该接口仅适用于视频直播（{@link TRTCAppSceneLIVE}）和语音聊天室（{@link TRTCAppSceneVoiceChatRoom}）这两个场景。
+ * 2. 如果您在 {@link enterRoom} 时指定的 scene 为 {@link TRTCAppSceneVideoCall} 或 {@link TRTCAppSceneAudioCall}，请不要调用这个接口。
*/
virtual void switchRole(TRTCRoleType role) = 0;
/**
- * 1.4 请求跨房通话（主播 PK）
+ * 2.4 切换房间
*
- * TRTC 中两个不同音视频房间中的主播，可以通过“跨房通话”功能拉通连麦通话功能。使用此功能时，
- * 两个主播无需退出各自原来的直播间即可进行“连麦 PK”。
+ * 使用该接口可以让用户可以快速从一个房间切换到另一个房间。
+ * - 如果用户的身份是“观众”，该接口的调用效果等同于 exitRoom(当前房间) + enterRoom（新的房间）。
+ * - 如果用户的身份是“主播”，该接口在切换房间的同时还会保持自己的音视频发布状态，因此在房间切换过程中，摄像头的预览和声音的采集都不会中断。
*
- * 例如：当房间“001”中的主播 A 通过 connectOtherRoom() 跟房间“002”中的主播 B 拉通跨房通话后，
- * 房间“001”中的用户都会收到主播 B 的 onUserEnter(B) 回调和 onUserVideoAvailable(B,true) 回调。
- * 房间“002”中的用户都会收到主播 A 的 onUserEnter(A) 回调和 onUserVideoAvailable(A,true) 回调。
+ * 该接口适用于在线教育场景中，监课老师在多个房间中进行快速切换的场景。在该场景下使用 switchRoom 可以获得比 exitRoom+enterRoom 更好的流畅性和更少的代码量。
+ * 接口调用结果会通过 {@link TRTCCloudDelegate} 中的 onSwitchRoom(errCode, errMsg) 回调。
*
- * 简言之，跨房通话的本质，就是把两个不同房间中的主播相互分享，让每个房间里的观众都能看到两个主播。
+ * @param config 房间参数，详情请参考 {@link TRTCSwitchRoomConfig} 。
+ * @note 由于对老版本 SDK 兼容的需求，参数 config 中同时包含 roomId 与 strRoomId 两个参数，这两个参数的填写格外讲究，请注意如下事项：
+ * 1. 若您选用 strRoomId，则 roomId 需要填写为0。若两者都填，将优先选用 roomId。
+ * 2. 所有房间需要同时使用 strRoomId 或同时使用 roomId，不可混用，否则将会出现很多预期之外的 bug。
+ */
+ virtual void switchRoom(const TRTCSwitchRoomConfig& config) = 0;
+
+ /**
+ * 2.5 请求跨房通话
+ *
+ * 默认情况下，只有同一个房间中的用户之间可以进行音视频通话，不同的房间之间的音视频流是相互隔离的。
+ * 但您可以通过调用该接口，将另一个房间中某个主播音视频流发布到自己所在的房间中，与此同时，该接口也会将自己的音视频流发布到目标主播的房间中。
+ * 也就是说，您可以使用该接口让身处两个不同房间中的主播进行跨房间的音视频流分享，从而让每个房间中的观众都能观看到这两个主播的音视频。该功能可以用来实现主播之间的 PK 功能。
+ * 跨房通话的请求结果会通过 {@link TRTCCloudDelegate} 中的 onConnectOtherRoom() 回调通知给您。
+ * 例如：当房间“101”中的主播 A 通过 connectOtherRoom() 跟房间“102”中的主播 B 建立跨房通话后，
+ * - 房间“101”中的用户都会收到主播 B 的 onRemoteUserEnterRoom(B) 和 onUserVideoAvailable(B,YES) 这两个事件回调，即房间“101”中的用户都可以订阅主播 B 的音视频。
+ * - 房间“102”中的用户都会收到主播 A 的 onRemoteUserEnterRoom(A) 和 onUserVideoAvailable(A,YES) 这两个事件回调，即房间“102”中的用户都可以订阅主播 A 的音视频。
*
* <pre>
- * 房间 001 房间 002
+ * 房间 101 房间 102
* ------------- ------------
* 跨房通话前：| 主播 A | | 主播 B |
* | 观众 U V W | | 观众 X Y Z |
* ------------- ------------
*
- * 房间 001 房间 002
+ * 房间 101 房间 102
* ------------- ------------
* 跨房通话后：| 主播 A B | | 主播 B A |
* | 观众 U V W | | 观众 X Y Z |
* ------------- ------------
* </pre>
+ * 跨房通话的参数考虑到后续扩展字段的兼容性问题，暂时采用了 JSON 格式的参数：
*
- * 跨房通话的参数考虑到后续扩展字段的兼容性问题，暂时采用了 JSON 格式的参数，要求至少包含两个字段：
- * - roomId：房间“001”中的主播 A 要跟房间“002”中的主播 B 连麦，主播 A 调用 connectOtherRoom() 时 roomId 应指定为“002”。
- * - userId：房间“001”中的主播 A 要跟房间“002”中的主播 B 连麦，主播 A 调用 connectOtherRoom() 时 userId 应指定为 B 的 userId。
- *
- * 跨房通话的请求结果会通过 ITRTCCloudCallback 中的 onConnectOtherRoom() 回调通知给您。
- *
+ * 【情况一：数字房间号】
+ * 如果房间“101”中的主播 A 要跟房间“102”中的主播 B 连麦，那么主播 A 调用该接口时需要传入：{"roomId": 102, "userId": "userB"}
+ * 示例代码如下：
* <pre>
- * //此处用到 jsoncpp 库来格式化 JSON 字符串
* Json::Value jsonObj;
- * jsonObj["roomId"] = 002;
+ * jsonObj["roomId"] = 102;
* jsonObj["userId"] = "userB";
* Json::FastWriter writer;
* std::string params = writer.write(jsonObj);
* trtc.ConnectOtherRoom(params.c_str());
* </pre>
*
- * @note 如果进房时，使用的是字符串房间号码，上面的 roomId 也需要相应改为 strRoomId。
+ * 【情况二：字符串房间号】
+ * 如果您使用的是字符串房间号，务必请将 json 中的 “roomId” 替换成 “strRoomId”: {"strRoomId": "102", "userId": "userB"}
+ * 示例代码如下：
* <pre>
- * //此处用到 jsoncpp 库来格式化 JSON 字符串
* Json::Value jsonObj;
- * jsonObj["strRoomId"] = "002";
+ * jsonObj["strRoomId"] = "102";
* jsonObj["userId"] = "userB";
* Json::FastWriter writer;
* std::string params = writer.write(jsonObj);
* trtc.ConnectOtherRoom(params.c_str());
* </pre>
*
- * @param params JSON 字符串连麦参数，roomId 代表目标房间号，userId 代表目标用户 ID。
- *
+ * @param param 需要你传入 JSON 格式的字符串参数，roomId 代表数字格式的房间号，strRoomId 代表字符串格式的房间号，userId 代表目标主播的用户ID。
*/
- virtual void connectOtherRoom(const char* params) = 0;
+ virtual void connectOtherRoom(const char* param) = 0;
/**
- * 1.5 关闭跨房连麦
+ * 2.6 退出跨房通话
*
- * 跨房通话的退出结果会通过 ITRTCCloudCallback 中的 onDisconnectOtherRoom() 回调通知给您。
+ * 退出结果会通过 {@link TRTCCloudDelegate} 中的 onDisconnectOtherRoom() 回调通知给您。
*/
virtual void disconnectOtherRoom() = 0;
/**
- * 1.6 设置音视频数据接收模式，需要在进房前设置才能生效
- *
- * 为实现进房秒开的绝佳体验，SDK 默认进房后自动接收音视频。即在您进房成功的同时，您将立刻收到远端所有用户的音视频数据。
- * 若您没有调用 startRemoteView，视频数据将自动超时取消。
- * 若您主要用于语音聊天等没有自动接收视频数据需求的场景，您可以根据实际需求选择接收模式，以免产生预期之外的视频时长费用。
+ * 2.7 设置订阅模式（需要在进入房前设置才能生效）
*
- * @param autoRecvAudio true：自动接收音频数据；false：需要调用 muteRemoteAudio 进行请求或取消。默认值：true
- * @param autoRecvVideo true：自动接收视频数据；false：需要调用 startRemoteView/stopRemoteView 进行请求或取消。默认值：true
+ * 您可以通过该接口在“自动订阅”和“手动订阅”两种模式下进行切换：
+ * - 自动订阅：默认模式，用户在进入房间后会立刻接收到该房间中的音视频流，音频会自动播放，视频会自动开始解码（依然需要您通过 startRemoteView 接口绑定渲染控件）。
+ * - 手动订阅：在用户进入房间后，需要手动调用 {@startRemoteView} 接口才能启动视频流的订阅和解码，需要手动调用 {@muteRemoteAudio} (false) 接口才能启动声音的播放。
*
- * @note 需要在进房前设置才能生效。
+ * 在绝大多数场景下，用户进入房间后都会订阅房间中所有主播的音视频流，因此 TRTC 默认采用了自动订阅模式，以求得最佳的“秒开体验”。
+ * 如果您的应用场景中每个房间同时会有很多路音视频流在发布，而每个用户只想选择性地订阅其中的 1-2 路，则推荐使用“手动订阅”模式以节省流量费用。
+ * @param autoRecvAudio YES：自动订阅音频；NO：需手动调用 muteRemoteAudio(false) 订阅音频。默认值：YES。
+ * @param autoRecvVideo YES：自动订阅视频；NO：需手动调用 startRemoteView 订阅视频。默认值：YES。
+ * @note
+ * 1. 需要在进入房间（enterRoom）前调用该接口，设置才能生效。
+ * 2. 在自动订阅模式下，如果用户在进入房间后没有调用 {@startRemoteView} 订阅视频流，SDK 会自动停止订阅视频流，以便达到节省流量的目的。
*/
virtual void setDefaultStreamRecvMode(bool autoRecvAudio, bool autoRecvVideo) = 0;
-#if _WIN32||__APPLE__
- /**
- * 1.7 创建子 TRTCCloud 实例
- *
- * 子 TRTCCloud 实例用于进入其他房间，观看其他房间主播的音视频流，还可以在不同的房间之间切换推送音视频流。
- *
- * 此接口主要应用于类似超级小班课这种需要进入多个房间推拉流的场景。
- *
- * <pre>
- * ITRTCCloud *mainCloud = getTRTCShareInstance();
- * // 1、mainCloud 进房并开始推送音视频流。
- * // 2、创建子 TRTCCloud 实例并进入其他房间。
- * ITRTCCloud *subCloud = mainCloud->createSubCloud();
- * subCloud->enterRoom(params, scene);
- *
- * // 3、切换房间推送音视频流。
- * // 3.1、mainCloud 停止推送音视频流。
- * mainCloud->switchRole(TRTCRoleAudience);
- * mainCloud->muteLocalVideo(true);
- * mainCloud->muteLocalAudio(true);
- * // 3.2、subCLoud 推送音视频流。
- * subCloud->switchRole(TRTCRoleAnchor);
- * subCloud->muteLocalVideo(false);
- * subCloud->muteLocalAudio(false);
- *
- * // 4、subCLoud 退房。
- * subCloud->exitRoom();
- *
- * // 5、销毁 subCLoud。
- * mainCloud->destroySubCloud(subCloud);
- * </pre>
- *
- * @return 子 TRTCCloud 实例
- * @note
- * - 此方法目前仅支持 Windows、iOS、Mac 平台
- * - 同一个用户，可以使用同一个 userId 进入多个不同 roomId 的房间。
- * - 两台手机不可以同时使用同一个 userId 进入同一个 roomId 的房间。
- * - 通过 createSubCloud 接口创建出来的子房间 TRTCCloud 实例有一个能力限制：不能调用子实例中与本地音视频
- * 相关的接口（除了 switchRole、muteLocalVideo 和 muteLocalAudio 之外）， 设置美颜等接口请使用
- * 原 TRTCCloud 实例对象。
- * - 同一个用户，同时只能在一个 TRTCCloud 实例中推流，在不同房间同时推流会引发云端的状态混乱，导致各种 bug。
- */
+/**
+ * 2.8 创建子房间示例（用于多房间并发观看）
+ *
+ * TRTCCloud 一开始被设计成单例模式，限制了多房间并发观看的能力。
+ * 通过调用该接口，您可以创建出多个 TRTCCloud 实例，以便同时进入多个不同的房间观看音视频流。
+ * 但需要注意的是，由于摄像头和麦克风还是只有一份，因此您只能同时在一个 TRTCCloud 实例中以“主播”的身份存在，也就是您只能同时在一个 TRTCCloud 实例中发布自己的音视频流。
+ * 该功能主要用于在线教育场景中一种被称为“超级小班课”的业务场景中，用于解决“每个 TRTC 的房间中最多只能有 50 人同时发布自己音视频流”的限制。
+ * 示例代码如下：
+ * <pre>
+ * ITRTCCloud *mainCloud = getTRTCShareInstance();
+ * mainCloud->enterRoom(params1, TRTCAppSceneLIVE);
+ * //...
+ * //Switch the role from "anchor" to "audience" in your own room
+ * mainCloud->switchRole(TRTCRoleAudience);
+ * mainCloud->muteLocalVideo(true);
+ * mainCloud->muteLocalAudio(true);
+ * //...
+ * //Use subcloud to enter another room and switch the role from "audience" to "anchor"
+ * ITRTCCloud *subCloud = mainCloud->createSubCloud();
+ * subCloud->enterRoom(params2, TRTCAppSceneLIVE);
+ * subCloud->switchRole(TRTCRoleAnchor);
+ * subCloud->muteLocalVideo(false);
+ * subCloud->muteLocalAudio(false);
+ * //...
+ * //Exit from new room and release it.
+ * subCloud->exitRoom();
+ * mainCloud->destroySubCloud(subCloud);
+ * </pre>
+ *
+ * @note
+ * - 同一个用户，可以使用同一个 userId 进入多个不同 roomId 的房间。
+ * - 两台不同的终端设备不可以同时使用同一个 userId 进入同一个 roomId 的房间。
+ * - 同一个用户，同时只能在一个 TRTCCloud 实例中推流，在不同房间同时推流会引发云端的状态混乱，导致各种 bug。
+ * - 通过 createSubCloud 接口创建出来的 TRTCCloud 实例有一个能力限制：不能调用子实例中与本地音视频相关的接口（除 switchRole、muteLocalVideo 和 muteLocalAudio 之外）， 设置美颜等接口请使用原 TRTCCloud 实例对象。
+ * @return 子 TRTCCloud 实例
+ */
+#if _WIN32 || __APPLE__
virtual ITRTCCloud* createSubCloud() = 0;
+#endif
- /**
- * 1.8 销毁子 TRTCCloud 实例
- *
- * @note 此方法目前仅支持 Windows、iOS、Mac 平台
- */
- virtual void destroySubCloud(ITRTCCloud *cloud) = 0;
+/**
+ * 2.9 销毁子房间示例
+ *
+ * @param subCloud
+ */
+#if _WIN32 || __APPLE__
+ virtual void destroySubCloud(ITRTCCloud* subCloud) = 0;
#endif
-
- /**
- * 1.9 切换房间
- *
- * 调用该接口后，用户会先退出原来的房间并快速进入 TRTCSwitchRoomConfig 中指定的新房间:
- * 相比于直接调用 exitRoom + enterRoom 的方式，switchRoom 接口对主播更加友好，因为 switchRoom
- * 不会停止主播端视频的采集和预览。
- * 接口调用结果会通过 ITRTCCloudCallback 中的 onSwitchRoom(errCode, errMsg) 回调通知给您。
- *
- * @param config 房间切换参数，请参考 {@link TRTCSwitchRoomConfig}
- */
- virtual void switchRoom(const TRTCSwitchRoomConfig& config) = 0;
- /// @}
/////////////////////////////////////////////////////////////////////////////////
//
- // （二）CDN 相关接口函数
+ // CDN 相关接口函数
//
/////////////////////////////////////////////////////////////////////////////////
- /// @name CDN 相关接口函数
- /// @{
+
/**
- * 2.1 开始向腾讯云的直播 CDN 推流
- *
- * 该接口会指定当前用户的音视频流在腾讯云 CDN 所对应的 StreamId，进而可以指定当前用户的 CDN 播放地址。
+ * 3.1 开始向腾讯云直播 CDN 上发布音视频流
*
- * 例如：如果我们采用如下代码设置当前用户的主画面 StreamId 为 user_stream_001，那么该用户主画面对应的 CDN 播放地址为：
+ * 该接口会向 TRTC 服务器发送指令，要求其将当前用户的音视频流旁路到直播 CDN 上。
+ * 您可以通过参数 streamId 设定直播流的 StreamId，从而可以指定该用户的音视频流对应在直播 CDN 上的播放地址。
+ * 例如：您可以通过该接口将当前用户的直播流 ID 指定为 user_stream_001，那么该用户音视频流对应的 CDN 播放地址为：
* “http://yourdomain/live/user_stream_001.flv”，其中 yourdomain 为您自己备案的播放域名，
- * 您可以在直播[控制台](https://console.cloud.tencent.com/live) 配置您的播放域名，腾讯云不提供默认的播放域名。
- *
- * <pre>
- * ITRTCCloud *trtcCloud = getTRTCShareInstance();
- * trtcCloud->enterRoom(params, TRTCAppSceneLIVE);
- * trtcCloud->startLocalPreview(TXView);
- * trtcCloud->startLocalAudio(TRTCAudioQuality);
- * trtcCloud->startPublishing("user_stream_001", TRTCVideoStreamTypeBig);
- * </pre>
- *
+ * 您可以在[直播控制台](https://console.cloud.tencent.com/live) 配置您的播放域名，腾讯云不提供默认的播放域名。
* 您也可以在设置 enterRoom 的参数 TRTCParams 时指定 streamId, 而且我们更推荐您采用这种方案。
- *
* @param streamId 自定义流 ID。
- * @param type 仅支持 TRTCVideoStreamTypeBig 和 TRTCVideoStreamTypeSub。
- * @note 您需要先在实时音视频 [控制台](https://console.cloud.tencent.com/rav/) 中的功能配置页开启“启用旁路推流”才能生效。
- * - 若您选择“指定流旁路”，则您可以通过该接口将对应音视频流推送到腾讯云 CDN 且指定为填写的流 ID。
- * - 若您选择“全局自动旁路”，则您可以通过该接口调整默认的流 ID。
+ * @param streamType 仅支持 {@link TRTCVideoStreamTypeBig} 和 {@link TRTCVideoStreamTypeSub}。
+ * @note 您需要提前在 [实时音视频控制台](https://console.cloud.tencent.com/trtc/) 中的功能配置页面上开启“启用旁路推流”才能生效。
+ * - 若您选择“指定流旁路”，则您可以通过该接口将对应音视频流推送到腾讯云 CDN 且指定为填写的流 ID。
+ * - 若您选择“全局自动旁路”，则您可以通过该接口调整默认的流 ID。
*/
- virtual void startPublishing(const char* streamId, TRTCVideoStreamType type) = 0;
+ virtual void startPublishing(const char* streamId, TRTCVideoStreamType streamType) = 0;
/**
- * 2.2 停止向腾讯云的直播 CDN 推流
+ * 3.2 停止向腾讯云直播 CDN 上发布音视频流
*/
virtual void stopPublishing() = 0;
/**
- * 2.3 开始向友商云的直播 CDN 转推
+ * 3.3 开始向非腾讯云 CDN 上发布音视频流
*
- * 该接口跟 startPublishing() 类似，但 startPublishCDNStream() 支持向非腾讯云的直播 CDN 转推。
- * @param param CDN 转推参数，请参考 TRTCTypeDef.h 中关于 TRTCPublishCDNParam 的介绍。
- * @note 使用 startPublishing() 绑定腾讯云直播 CDN 不收取额外的费用，但使用 startPublishCDNStream() 绑定非腾讯云直播 CDN 需要收取转推费用。
+ * 该接口跟 startPublishing 功能类似，不同之处在于，startPublishing 仅支持向腾讯云的 CDN 发布，而本接口支持向非腾讯云的直播 CDN 上转推音视频流。
+ * @param param CDN 转推参数，详情请参考 {@link TRTCPublishCDNParam}
+ * @note
+ * - 使用 startPublishing 接口向腾讯云的直播 CDN 上发布音视频流不会收取额外费用
+ * - 使用 startPublishCDNStream 接口向非腾讯云的直播 CDN 上发布音视频流，需要收取额外的转推带宽费用。
*/
virtual void startPublishCDNStream(const TRTCPublishCDNParam& param) = 0;
/**
- * 2.4 停止向非腾讯云地址转推
- */
+ * 3.4 停止向非腾讯云 CDN 上发布音视频流
+ */
virtual void stopPublishCDNStream() = 0;
/**
- * 2.5 设置云端的混流转码参数
- *
- * 如果您在实时音视频 [控制台](https://console.cloud.tencent.com/trtc/) 中的功能配置页开启了“启动自动旁路直播”功能，
- * 房间里的每一路画面都会有一个默认的直播 [CDN 地址](https://cloud.tencent.com/document/product/647/16826)。
- *
- * 一个直播间中可能有不止一位主播，而且每个主播都有自己的画面和声音，但对于 CDN 观众来说，他们只需要一路直播流，
- * 所以您需要将多路音视频流混成一路标准的直播流，这就需要混流转码。
- *
- * 当您调用 setMixTranscodingConfig() 接口时，SDK 会向腾讯云的转码服务器发送一条指令，目的是将房间里的多路音视频流混合为一路,
- * 您可以通过 mixUsers 参数来调整每一路画面的位置，以及是否只混合声音，也可以通过 videoWidth、videoHeight、videoBitrate 等参数控制混合音视频流的编码参数。
+ * 3.5 设置云端混流的排版布局和转码参数
*
+ * 在一个直播间中可能同时会有多个主播发布自己的音视频流，但对于直播 CDN 上的观众而言，只需要观看一条 HTTP-FLV 或 HLS 格式的视频流即可。
+ * 当您调用本接口函数时，SDK 会向腾讯云的 TRTC 混流服务器发送一条指令，混流服务器会将房间里的多路音视频流混合成一路。
+ * 您可以通过 {@link TRTCTranscodingConfig} 参数来调整每一路画面的排版布局，也可以设置混合后的音视频流的各项编码参数。
+ * 参考文档：[云端混流转码](https://cloud.tencent.com/document/product/647/16827)。
* <pre>
- * 【画面1】=> 解码 ====> \
- * \
- * 【画面2】=> 解码 => 画面混合 => 编码 => 【混合后的画面】
- * /
- * 【画面3】=> 解码 ====> /
- *
- * 【声音1】=> 解码 ====> \
- * \
- * 【声音2】=> 解码 => 声音混合 => 编码 => 【混合后的声音】
- * /
- * 【声音3】=> 解码 ====> /
+ * 【画面1】=> 解码 ====> \\
+ * \\
+ * 【画面2】=> 解码 => 画面混合 => 编码 => 【混合后的画面】
+ * //
+ * 【画面3】=> 解码 ====> //
+ *
+ * 【声音1】=> 解码 ====> \\
+ * \\
+ * 【声音2】=> 解码 => 声音混合 => 编码 => 【混合后的声音】
+ * //
+ * 【声音3】=> 解码 ====> //
* </pre>
- *
- * 参考文档：[云端混流转码](https://cloud.tencent.com/document/product/647/16827)。
- *
- * @param config 请参考 TRTCTypeDef.h 中关于 TRTCTranscodingConfig 的介绍。如果传入 nullptr 则取消云端混流转码。
+ * @param config 如果 config 不为空，则开启云端混流，如果 config 为空则停止云端混流。详情请参考 {@link TRTCTranscodingConfig} 。
* @note 关于云端混流的注意事项：
- * - 云端转码会引入一定的 CDN 观看延时，大概会增加1 - 2秒。
- * - 调用该函数的用户，会将连麦中的多路画面混合到自己当前这路画面或者 config 中指定的 streamId 上。
- * - 请注意，若您还在房间中且不再需要混流，请务必传入 nullptr 进行取消，因为当您发起混流后，云端混流模块就会开始工作，不及时取消混流可能会引起不必要的计费损失。
- * - 请放心，您退房时会自动取消混流状态。
+ * - 调用该接口的用户，如果没设定 config 参数中的 streamId 字段，TRTC 会将房间中的多路画面混合到当前用户所对应的音视频流上，即 A + B => A。
+ * - 调用该接口的用户，如果设定了 config 参数中的 streamId 字段，TRTC 会将房间中的多路画面混合到您指定的 streamId 上，即 A + B => streamId。
+ * - 请注意，若您还在房间中且不再需要混流，请务必再次调用本接口并将 config 设置为空以进行取消，不及时取消混流可能会引起不必要的计费损失。
+ * - 请放心，当您退房时 TRTC 会自动取消混流状态。
*/
virtual void setMixTranscodingConfig(TRTCTranscodingConfig* config) = 0;
- /// @}
- /////////////////////////////////////////////////////////////////////////////////
- //
- // （三）视频相关接口函数
- //
- /////////////////////////////////////////////////////////////////////////////////
- /// @name 视频相关接口函数
- /// @{
+/// @}
+/////////////////////////////////////////////////////////////////////////////////
+//
+// 视频相关接口函数
+//
+/////////////////////////////////////////////////////////////////////////////////
+/// @name 视频相关接口函数
+/// @{
+
+/**
+ * 4.1 开启本地摄像头的预览画面（移动端）
+ *
+ * 在 enterRoom 之前调用此函数，SDK 只会开启摄像头，并一直等到您调用 enterRoom 之后才开始推流。
+ * 在 enterRoom 之后调用此函数，SDK 会开启摄像头并自动开始视频推流。
+ * 当开始渲染首帧摄像头画面时，您会收到 {@link TRTCCloudDelegate} 中的 onCameraDidReady 回调通知。
+ * @param frontCamera YES：前置摄像头；NO：后置摄像头。
+ * @param view 承载视频画面的控件
+ * @note 如果希望开播前预览摄像头画面并通过 BeautyManager 调节美颜参数，您可以：
+ * - 方案一：在调用 enterRoom 之前调用 startLocalPreview
+ * - 方案二：在调用 enterRoom 之后调用 startLocalPreview + muteLocalVideo(true)
+ */
+#if TARGET_PLATFORM_PHONE
+ virtual void startLocalPreview(bool frontCamera, TXView view) = 0;
+#endif
+
+/**
+ * 4.2 开启本地摄像头的预览画面（桌面端）
+ *
+ * 在调用该接口之前，您可以先调用 setCurrentCameraDevice 选择使用 Mac 自带摄像头或外接摄像头。
+ * 在 enterRoom 之前调用此函数，SDK 只会开启摄像头，并一直等到您调用 enterRoom 之后才开始推流。
+ * 在 enterRoom 之后调用此函数，SDK 会开启摄像头并自动开始视频推流。
+ * 当开始渲染首帧摄像头画面时，您会收到 {@link TRTCCloudDelegate} 中的 onCameraDidReady 回调通知。
+ * @param view 承载视频画面的控件
+ * @note 如果希望开播前预览摄像头画面并通过 BeautyManager 调节美颜参数，您可以：
+ * - 方案一：在调用 enterRoom 之前调用 startLocalPreview
+ * - 方案二：在调用 enterRoom 之后调用 startLocalPreview + muteLocalVideo(true)
+ */
#if TARGET_PLATFORM_DESKTOP
- /**
- * 3.1 开启本地视频的预览画面(Windows、 Mac版本)
- *
- * 这个接口会启动默认的摄像头，可以通过 ITXDeviceManager::setCurrentDevice 接口选用其他摄像头
- * 当开始渲染首帧摄像头画面时，您会收到 ITRTCCloudCallback 中的 onFirstVideoFrame(nullptr) 回调。
- *
- * @param rendView 承载预览画面的控件
- */
- virtual void startLocalPreview(TXView rendView) = 0;
-#elif TARGET_PLATFORM_PHONE
- /**
- * 3.2 开启本地视频的预览画面 (iOS、 Android版本)
- * 在 enterRoom 之前调用此函数，SDK 只会开启摄像头，并一直等到您调用 enterRoom 之后才开始推流。
- * 在 enterRoom 之后调用此函数，SDK 会开启摄像头并自动开始视频推流。
- * 当开始渲染首帧摄像头画面时，您会收到 ITRTCCloudCallback 中的 onFirstVideoFrame(null) 回调。
- *
- * @note 如果希望开播前预览摄像头画面并调节美颜参数，您可以：
- * - 方案一：在调用 enterRoom 之前调用 startLocalPreview
- * - 方案二：在调用 enterRoom 之后调用 startLocalPreview + muteLocalVideo(true)
- * @param frontCamera YES：前置摄像头；NO：后置摄像头。
- * @param rendView 承载视频画面的控件
- */
- virtual void startLocalPreview(bool frontCamera, TXView rendView) = 0;
+ virtual void startLocalPreview(TXView view) = 0;
#endif
/**
- * 3.3 更新本地视频预览画面的窗口
- *
- * @param rendView 承载预览画面的控件
+ * 4.3 更新本地摄像头的预览画面
*/
- virtual void updateLocalView(TXView rendView) = 0;
+ virtual void updateLocalView(TXView view) = 0;
/**
- * 3.4 停止本地视频采集及预览
+ * 4.4 停止摄像头预览
*/
virtual void stopLocalPreview() = 0;
/**
- * 3.5 暂停/恢复推送本地的视频数据
- *
- * 当暂停推送本地视频后，房间里的其它成员将会收到 onUserVideoAvailable(userId, false) 回调通知
- * 当恢复推送本地视频后，房间里的其它成员将会收到 onUserVideoAvailable(userId, true) 回调通知
+ * 4.5 暂停/恢复发布本地的视频流
*
- * @param mute true：暂停；false：恢复
+ * 该接口可以暂停（或恢复）发布本地的视频画面，暂停之后，同一房间中的其他用户将无法继续看到自己画面。
+ * 该接口在指定 TRTCVideoStreamTypeBig 时等效于 start/stopLocalPreview 这两个接口，但具有更好的响应速度。
+ * 因为 start/stopLocalPreview 需要打开和关闭摄像头，而打开和关闭摄像头都是硬件设备相关的操作，非常耗时。
+ * 相比之下，muteLocalVideo 只需要在软件层面对数据流进行暂停或者放行即可，因此效率更高，也更适合需要频繁打开关闭的场景。
+ * 当暂停/恢复发布指定 TRTCVideoStreamTypeBig 后，同一房间中的其他用户将会收到 onUserVideoAvailable 回调通知。
+ * 当暂停/恢复发布指定 TRTCVideoStreamTypeSub 后，同一房间中的其他用户将会收到 onUserSubStreamAvailable 回调通知。
+ * @param streamType 要暂停/恢复的视频流类型（仅支持 {@link TRTCVideoStreamTypeBig} 和 {@link TRTCVideoStreamTypeSub}）
+ * @param mute true：暂停；false：恢复。
*/
- virtual void muteLocalVideo(bool mute) = 0;
+ virtual void muteLocalVideo(TRTCVideoStreamType streamType, bool mute) = 0;
/**
- * 3.6 开始拉取并显示指定用户的远端画面
+ * 4.7 订阅远端用户的视频流，并绑定视频渲染控件
*
- * 该函数会拉取指定 userid 的视频流显示在您指定的 view 控件上，您可以通过 setRemoteRenderParams 设置显示模式。
- * - 如果您提前知道房间中某个 userid 正在推流，可以直接调用 startRemoteView 显示该用户的远端画面。
- * - 如果您不知道房间中有哪些用户开启了视频，可以在 enterRoom 后等待来自 SDK 的 onUserVideoAvailable(userId, true) 回调通知。
- * 调用 startRemoteView 只是启动拉取，此时画面还需要加载，当加载完毕后 ITRTCCloudCallback 会通过 onFirstVideoFrame(userId) 通知您。
+ * 调用该接口可以让 SDK 拉取指定 userid 的视频流，并渲染到参数 view 指定的渲染控件上。您可以通过 {@link setRemoteRenderParams} 设置画面的显示模式。
+ * - 如果您已经知道房间中有视频流的用户的 userid，可以直接调用 startRemoteView 订阅该用户的画面。
+ * - 如果您不知道房间中有哪些用户在发布视频，您可以在 enterRoom 之后等待来自 {@link onUserVideoAvailable} 的通知。
*
- * @param userId 指定远端用户的 userId
+ * 调用本接口只是启动视频流的拉取，此时画面还需要加载和缓冲，当缓冲完毕后您会收到来自 {@link onFirstVideoFrame} 的通知。
+ * @param userId 指定远端用户的 ID。
* @param streamType 指定要观看 userId 的视频流类型：
- * - 高清大画面：({@link TRTCVideoStreamTypeBig})
- * - 低清大画面：({@link TRTCVideoStreamTypeSmall})
- * - 辅流（屏幕分享）：({@link TRTCVideoStreamTypeSub})
- * @param rendView 承载视频画面的控件
+ * - 高清大画面：{@link TRTCVideoStreamTypeBig}
+ * - 低清小画面：{@link TRTCVideoStreamTypeSmall}（需要远端用户通过 {@link enableEncSmallVideoStream} 开启双路编码后才有效果）
+ * - 辅流画面（常用于屏幕分享）：{@link TRTCVideoStreamTypeSub}
*
- * @note 注意几点规则需要您关注：<br>
- * 1. SDK 支持同时观看某 userid 的大画面和辅路，或者小画面和辅路，但不支持同时观看大画面和小画面。<br>
- * 2. 只有当指定的 userid 通过 enableEncSmallVideoStream 开启双路编码后，才能观看该用户的小画面。<br>
- * 3. 如果该用户的小画面不存在，则默认切换到大画面。
+ * @param view 用于承载视频画面的渲染控件
+ * @note 注意几点规则需要您关注：
+ * 1. SDK 支持同时观看某 userid 的大画面和辅路画面，或者同时观看某 userid 的小画面和辅路画面，但不支持同时观看大画面和小画面。
+ * 2. 只有当指定的 userid 通过 {@link enableEncSmallVideoStream} 开启双路编码后，才能观看该用户的小画面。
+ * 3. 当指定的 userid 的小画面不存在时，SDK 默认切换到该用户的大画面。
*/
- virtual void startRemoteView(const char* userId, TRTCVideoStreamType streamType, TXView rendView) = 0;
+ virtual void startRemoteView(const char* userId, TRTCVideoStreamType streamType, TXView view) = 0;
/**
- * 3.7 更新远端视频渲染的窗口
+ * 4.8 更新远端用户的视频渲染控件
*
- * @param userId 对方的用户标识
- * @param streamType 要设置预览窗口的流类型(TRTCVideoStreamTypeBig、TRTCVideoStreamTypeSub)
- * @param rendView 承载预览画面的控件
+ * 该接口可用于更新远端视频画面的渲染控件，常被用于切换显示区域的交互场景中。
+ * @param view 承载视频画面的控件
+ * @param streamType 要设置预览窗口的流类型（仅支持 {@link TRTCVideoStreamTypeBig} 和 {@link TRTCVideoStreamTypeSub}）
+ * @param userId 指定远端用户的 ID。
*/
- virtual void updateRemoteView(const char* userId, TRTCVideoStreamType streamType, TXView rendView) = 0;
+ virtual void updateRemoteView(const char* userId, TRTCVideoStreamType streamType, TXView view) = 0;
/**
- * 3.8 停止显示远端视频画面，同时不再拉取该远端用户的视频数据流
- *
- * 调用此接口后，SDK 会停止接收该用户的远程视频流，同时会清理相关的视频显示资源。
+ * 4.9 停止订阅远端用户的视频流，并释放渲染控件
*
- * @param userId 指定远端用户的 userId
- * @param streamType 指定要停止观看的 userId 的视频流类型：
- * - 高清大画面：({@link TRTCVideoStreamTypeBig})
- * - 低清大画面：({@link TRTCVideoStreamTypeSmall})
- * - 辅流（屏幕分享）：({@link TRTCVideoStreamTypeSub})
+ * 调用此接口会让 SDK 停止接收该用户的视频流，并释放该路视频流的解码和渲染资源。
+ * @param userId 指定远端用户的 ID。
+ * @param streamType 指定要观看 userId 的视频流类型：
+ * - 高清大画面：{@link TRTCVideoStreamTypeBig}
+ * - 低清小画面：{@link TRTCVideoStreamTypeSmall}
+ * - 辅流画面（常用于屏幕分享）：{@link TRTCVideoStreamTypeSub}
*/
virtual void stopRemoteView(const char* userId, TRTCVideoStreamType streamType) = 0;
/**
- * 3.9 停止显示所有远端视频画面，同时不再拉取远端用户的视频数据流
+ * 4.10 停止订阅所有远端用户的视频流，并释放全部渲染资源
*
- * @note 如果有屏幕分享的画面在显示，则屏幕分享的画面也会一并被关闭。
+ * 调用此接口会让 SDK 停止接收所有来自远端的视频流，并释放全部的解码和渲染资源。
+ * @note 如果当前有正在显示的辅路画面（屏幕分享）也会一并被停止。
*/
virtual void stopAllRemoteView() = 0;
/**
- * 3.10 暂停/恢复接收指定的远端视频流
- *
- * 该接口仅暂停/恢复接收指定的远端用户的视频流，但并不释放显示资源，所以如果暂停，视频画面会冻屏在 mute 前的最后一帧。
+ * 4.11 暂停/恢复订阅远端用户的视频流
*
- * @param userId 对方的用户标识
- * @param mute 是否暂停接收
- * @note 您在 enterRoom 之前或之后调用此 API 均能生效，在您调用 exitRoom 之后会被重置为 false。
+ * 该接口仅暂停/恢复接收指定用户的视频流，但并不释放显示资源，视频画面会被冻屏在接口调用时的最后一帧。
+ * @param userId 指定远端用户的 ID。
+ * @param streamType 要暂停/恢复的视频流类型（仅支持 {@link TRTCVideoStreamTypeBig} 和 {@link TRTCVideoStreamTypeSub}）。
+ * @param mute 是否暂停接收。
+ * @note 该接口支持您在进入房间（enterRoom）前调用，暂停状态会在退出房间（exitRoom）在之后会被重置。
*/
- virtual void muteRemoteVideoStream(const char* userId, bool mute) = 0;
+ virtual void muteRemoteVideoStream(const char* userId, TRTCVideoStreamType streamType, bool mute) = 0;
/**
- * 3.11 暂停/恢复接收所有远端视频流
- *
- * 该接口仅暂停/恢复接收所有远端用户的视频流，但并不释放显示资源，所以如果暂停，视频画面会冻屏在 mute 前的最后一帧。
+ * 4.12 暂停/恢复订阅所有远端用户的视频流
*
- * @param mute 是否暂停接收
- * @note 您在 enterRoom 之前或之后调用此 API 均能生效，在您调用 exitRoom 之后会被重置为 false。
+ * 该接口仅暂停/恢复接收所有用户的视频流，但并不释放显示资源，视频画面会被冻屏在接口调用时的最后一帧。
+ * @param mute 是否暂停接收
+ * @note 该接口支持您在进入房间（enterRoom）前调用，暂停状态会在退出房间（exitRoom）在之后会被重置。
*/
virtual void muteAllRemoteVideoStreams(bool mute) = 0;
/**
- * 3.12 设置视频编码器相关参数
- *
- * 该设置决定了远端用户看到的画面质量（同时也是云端录制出的视频文件的画面质量）
+ * 4.13 设置视频编码器的编码参数
*
- * @param params 视频编码参数，详情请参考 TRTCTypeDef.h 中的 TRTCVideoEncParam 定义
+ * 该设置能够决定远端用户看到的画面质量，同时也能决定云端录制出的视频文件的画面质量。
+ * @param param 用于设置视频编码器的相关参数，详情请参考 {@link TRTCVideoEncParam}。
*/
- virtual void setVideoEncoderParam(const TRTCVideoEncParam& params) = 0;
+ virtual void setVideoEncoderParam(const TRTCVideoEncParam& param) = 0;
/**
- * 3.13 设置网络流控相关参数
+ * 4.14 设置网络质量控制的相关参数
*
- * 该设置决定了 SDK 在各种网络环境下的调控策略（例如弱网下是“保清晰”还是“保流畅”）
- *
- * @param params 网络流控参数，详情请参考 TRTCTypeDef.h 中的 TRTCNetworkQosParam 定义
+ * 该设置决定在差网络环境下的质量调控策略，如“画质优先”或“流畅优先”等策略。
+ * @param param 用于设置网络质量控制的相关参数，详情请参考 {@link TRTCNetworkQosParam}。
*/
- virtual void setNetworkQosParam(const TRTCNetworkQosParam& params) = 0;
+ virtual void setNetworkQosParam(const TRTCNetworkQosParam& param) = 0;
/**
- * 3.14 设置本地图像（主流）的渲染参数
+ * 4.15 设置本地画面的渲染参数
*
- * @param params 本地图像的参数，详情请参考 TRTCTypeDef.h 中的 TRTCRenderParams 定义
+ * 可设置的参数包括有：画面的旋转角度、填充模式以及左右镜像等。
+ * @param params 画面渲染参数，详情请参考 {@link TRTCRenderParams}。
*/
- virtual void setLocalRenderParams(const TRTCRenderParams ¶ms) = 0;
+ virtual void setLocalRenderParams(const TRTCRenderParams& params) = 0;
/**
- * 3.15 设置视频编码输出的画面方向，即设置远端用户观看到的和服务器录制的画面方向
+ * 4.16 设置远端画面的渲染模式
*
- * @param rotation 目前支持 TRTCVideoRotation0 和 TRTCVideoRotation180 旋转角度，默认值：TRTCVideoRotation0
+ * 可设置的参数包括有：画面的旋转角度、填充模式以及左右镜像等。
+ * @param userId 指定远端用户的 ID。
+ * @param streamType 可以设置为主路画面（TRTCVideoStreamTypeBig）或辅路画面（TRTCVideoStreamTypeSub）
+ * @param params 画面渲染参数，详情请参考 {@link TRTCRenderParams}。
*/
- virtual void setVideoEncoderRotation(TRTCVideoRotation rotation) = 0;
+ virtual void setRemoteRenderParams(const char* userId, TRTCVideoStreamType streamType, const TRTCRenderParams& params) = 0;
/**
- * 3.16 设置编码器输出的画面镜像模式
- *
- * 该接口不改变本地摄像头的预览画面，但会改变另一端用户看到的（以及服务器录制的）画面效果。
+ * 4.17 设置视频编码器输出的画面方向
*
- * @param mirror 是否开启远端镜像, true：远端画面镜像；false：远端画面非镜像。默认值：false
+ * 该设置不影响本地画面的预览方向，但会影响房间中其他用户所观看到（以及云端录制文件）的画面方向。
+ * 当用户将手机或 Pad 上下颠倒时，由于摄像头的采集方向没有变，所以房间中其他用户所看到的画面会变成上下颠倒的，
+ * 在这种情况下，您可以通过调用该接口将 SDK 编码出的画面方向旋转180度，如此一来，房间中其他用户所看到的画面可保持正常的方向。
+ * 如果您希望实现上述这种友好的交互体验，我们更推荐您直接调用 {@link setGSensorMode} 实现更加智能的方向适配，无需您手动调用本接口。
+ * @param rotation 目前支持0和180两个旋转角度，默认值：TRTCVideoRotation_0，即不旋转。
*/
- virtual void setVideoEncoderMirror(bool mirror) = 0;
+ virtual void setVideoEncoderRotation(TRTCVideoRotation rotation) = 0;
/**
- * 3.17 设置远端图像的渲染模式
+ * 4.18 设置编码器输出的画面镜像模式
*
- * @param userId 对应的远端视频流用户ID
- * @param streamType 远端图像的视频流类型，详见 TRTCVideoStreamType 定义
- * @param param 远端图像的参数，详情请参考 TRTCTypeDef.h 中的 TRTCRenderParams 定义
+ * 该设置不影响本地画面的镜像模式，但会影响房间中其他用户所观看到（以及云端录制文件）的镜像模式。
+ * @param mirror 是否开启远端镜像，true：开启远端画面镜像；false：关闭远端画面镜像，默认值：false。
*/
- virtual void setRemoteRenderParams(const char* userId, TRTCVideoStreamType streamType, const TRTCRenderParams ¶ms) = 0;
+ virtual void setVideoEncoderMirror(bool mirror) = 0;
/**
- * 3.18 开启大小画面双路编码模式
- *
- * 如果当前用户是房间中的主要角色（例如主播、老师、主持人等），并且使用 PC 或者 Mac 环境，可以开启该模式。
- * 开启该模式后，当前用户会同时输出【高清】和【低清】两路视频流（但只有一路音频流）。
- * 对于开启该模式的当前用户，会占用更多的网络带宽，并且会更加消耗 CPU 计算资源。
- *
- * 对于同一房间的远程观众而言：
- * - 如果用户的下行网络很好，可以选择观看【高清】画面
- * - 如果用户的下行网络较差，可以选择观看【低清】画面
+ * 4.20 开启大小画面双路编码模式
*
+ * 开启双路编码模式后，当前用户的编码器会同时输出【高清大画面】和【低清小画面】两路视频流（但只有一路音频流）。
+ * 如此以来，房间中的其他用户就可以根据自身的网络情况或屏幕大小选择订阅【高清大画面】或是【低清小画面】。
+ * @note 双路编码开启后，会消耗更多的 CPU 和 网络带宽，所以 Mac、Windows 或者高性能 Pad 可以考虑开启，不建议手机端开启。
* @param enable 是否开启小画面编码，默认值：false
- * @param smallVideoParam 小流的视频参数
+ * @param smallVideoEncParam 小流的视频参数
+ * @return 0：成功；-1：当前大画面已被设置为较低画质，开启双路编码已无必要。
*/
- virtual void enableSmallVideoStream(bool enable, const TRTCVideoEncParam& smallVideoParam) = 0;
+ virtual void enableSmallVideoStream(bool enable, const TRTCVideoEncParam& smallVideoEncParam) = 0;
/**
- * 3.19 选定观看指定 userId 的大画面还是小画面
- *
- * 此功能需要该 userId 通过 enableEncSmallVideoStream 提前开启双路编码模式。
- * 如果该 userId 没有开启双路编码模式，则此操作无效。
+ * 4.21 切换指定远端用户的大小画面
*
- * @param userId 用户 ID
- * @param type 视频流类型，即选择看大画面还是小画面，默认为 TRTCVideoStreamTypeBig
+ * 当房间中某个主播开启了双路编码之后，房间中其他用户通过 {@link startRemoteView} 订阅到的画面默认会是【高清大画面】。
+ * 您可以通过此接口选定希望订阅的画面是大画面还是小画面，该接口在 {@link startRemoteView} 之前和之后调用均可生效。
+ * @note 此功能需要目标用户已经通过 {@link enableEncSmallVideoStream} 提前开启了双路编码模式，否则此调用无实际效果。
+ * @param userId 指定远端用户的 ID。
+ * @param streamType 视频流类型，即选择看大画面还是小画面，默认为大画面。
*/
- virtual void setRemoteVideoStreamType(const char* userId, TRTCVideoStreamType type) = 0;
+ virtual void setRemoteVideoStreamType(const char* userId, TRTCVideoStreamType streamType) = 0;
+/**
+ * 4.22 视频画面截图
+ *
+ * 您可以通过本接口截取本地的视频画面，远端用户的主路画面以及远端用户的辅路（屏幕分享）画面。
+ * @param userId 用户 ID，如指定空置表示截取本地的视频画面。
+ * @param streamType 视频流类型，可选择截取主路画面（{@link TRTCVideoStreamTypeBig}，常用于摄像头）或辅路画面（{@link TRTCVideoStreamTypeSub}，常用于屏幕分享）。
+ * @param sourceType 画面来源，可选择截取视频流画面（{@link TRTCSnapshotSourceTypeStream}）或视频渲染画面（{@link TRTCSnapshotSourceTypeView}），前者一般更清晰。
+ * @note Windows 平台目前仅支持截取 {@link TRTCSnapshotSourceTypeStream} 来源的视频画面。
+ */
#if _WIN32 || __APPLE__
- /**
- * 3.20 视频画面截图
- *
- * 截取本地主路、本地辅路、远程主路和远端辅流的视频画面，并通过 ITRTCCloudCallback 的 onSnapshotComplete 回调返回截图画面的数据给您。
- *
- * @param userId 用户 ID，空字符串表示截取本地画面
- * @param streamType 视频流类型，支持摄像头画面（{@link TRTCVideoStreamTypeBig}）和屏幕分享画面（{@link TRTCVideoStreamTypeSub}）
- * @param sourceType 视频截图来源类型，Windows 端只支持 {@link TRTCSnapshotSourceTypeStream}
- */
virtual void snapshotVideo(const char* userId, TRTCVideoStreamType streamType, TRTCSnapshotSourceType sourceType) = 0;
#endif
- /// @}
+ /// @}
/////////////////////////////////////////////////////////////////////////////////
//
- // （四）音频相关接口函数
+ // 音频相关接口函数
//
/////////////////////////////////////////////////////////////////////////////////
- /// @name 音频相关接口函数
+ /// @name 音频相关接口函数
/// @{
+
/**
- * 4.1 开启本地音频的采集和上行
+ * 5.1 开启本地音频的采集和发布
*
- * 该函数会启动麦克风采集，并将音频数据传输给房间里的其他用户。
- * SDK 并不会默认开启本地的音频上行，也就说，如果您不调用这个函数，房间里的其他用户就听不到您的声音。
- * @param quality 声音质量，参见 TRTCAudioQuality
- * @note TRTC SDK 并不会默认打开本地的麦克风采集。
+ * SDK 默认不开启麦克风，当用户需要发布本地音频时，需要调用该接口开启麦克风采集，并将音频编码并发布到当前的房间中。
+ * 开启本地音频的采集和发布后，房间中的其他用户会收到 {@link onUserAudioAvailable}(userId, true) 的通知。
+ * @param quality 声音音质
+ * - {@link TRTCAudioQualitySpeech}，流畅：采样率：16k；单声道；音频裸码率：16kbps；适合语音通话为主的场景，比如在线会议，语音通话。
+ * - {@link TRTCAudioQualityDefault}，默认：采样率：48k；单声道；音频裸码率：50kbps；SDK 默认的音频质量，如无特殊需求推荐选择之。
+ * - {@link TRTCAudioQualityMusic}，高音质：采样率：48k；双声道 + 全频带；音频裸码率：128kbps；适合需要高保真传输音乐的场景，比如在线K歌、音乐直播等。
+ * @note 该函数会检查麦克风的使用权限，如果当前 App 没有麦克风权限，SDK 会自动向用户申请麦克风使用权限。
*/
virtual void startLocalAudio(TRTCAudioQuality quality) = 0;
/**
- * 4.2 关闭本地音频的采集和上行
+ * 5.2 停止本地音频的采集和发布
*
- * 当关闭本地音频的采集和上行，房间里的其它成员会收到 onUserAudioAvailable(false) 回调通知。
+ * 停止本地音频的采集和发布后，房间中的其他用户会收到 {@link onUserAudioAvailable}(userId, false) 的通知。
*/
virtual void stopLocalAudio() = 0;
/**
- * 4.3 静音/取消静音本地的音频
- *
- * 当静音本地音频后，房间里的其它成员会收到 onUserAudioAvailable(userId, false) 回调通知。
- * 当取消静音本地音频后，房间里的其它成员会收到 onUserAudioAvailable(userId, true) 回调通知。
+ * 5.3 暂停/恢复发布本地的音频流
*
- * 与 stopLocalAudio 不同之处在于，muteLocalAudio(true) 并不会停止发送音视频数据，而是继续发送码率极低的静音包。
- * 由于 MP4 等视频文件格式，对于音频的连续性是要求很高的，使用 stopLocalAudio 会导致录制出的 MP4 不易播放。
- * 因此在对录制质量要求很高的场景中，建议选择 muteLocalAudio，从而录制出兼容性更好的 MP4 文件。
- *
- * @param mute true：静音；false：取消静音
+ * 当您暂停发布本地音频流之后，房间中的其他他用户会收到 {@link onUserAudioAvailable}(userId, false) 的通知。
+ * 当您恢复发布本地音频流之后，房间中的其他他用户会收到 {@link onUserAudioAvailable}(userId, true) 的通知。
+ * 与 {@link stopLocalAudio} 的不同之处在于，muteLocalAudio(true) 并不会释放麦克风权限，而是继续发送码率极低的静音包。
+ * 这对于需要云端录制的场景非常适用，因为 MP4 等格式的视频文件，对于音频数据的连续性要求很高，使用 {@link stopLocalAudio} 会导致录制出的 MP4 文件不易播放。
+ * 因此在对录制文件的质量要求较高的场景中，建议选择 muteLocalAudio 而不建议使用 stopLocalAudio。
+ * @param mute true：静音；false：恢复。
*/
virtual void muteLocalAudio(bool mute) = 0;
/**
- * 4.4 静音/取消静音指定的远端用户的声音
- *
- * @param userId 用户 ID
- * @param mute true：静音；false：取消静音
+ * 5.4 暂停/恢复播放远端的音频流
*
- * @note
- * - 静音时会停止接收该用户的远端音频流并停止播放，取消静音时会自动拉取该用户的远端音频流并进行播放。
- * - 您在 enterRoom 之前或之后调用此 API 均能生效，在您调用 exitRoom 之后会被重置为 false。
+ * 当您静音某用户的远端音频时，SDK 会停止播放指定用户的声音，同时也会停止拉取该用户的音频数据数据。
+ * @param userId 用于指定远端用户的 ID。
+ * @param mute true：静音；false：取消静音。
+ * @note 在进入房间（enterRoom）之前或之后调用本接口均生效，静音状态在退出房间（exitRoom） 之后会被重置为 false。
*/
virtual void muteRemoteAudio(const char* userId, bool mute) = 0;
/**
- * 4.5 静音/取消静音所有用户的声音
- *
- * @param mute true：静音；false：取消静音
+ * 5.5 暂停/恢复播放所有远端用户的音频流
*
- * @note
- * - 静音时会停止接收所有用户的远端音频流并停止播放，取消静音时会自动拉取所有用户的远端音频流并进行播放。
- * - 您在 enterRoom 之前或之后调用此 API 均能生效，在您调用 exitRoom 之后会被重置为 false。
+ * 当您静音所有用户的远端音频时，SDK 会停止播放所有来自远端的音频流，同时也会停止拉取所有用户的音频数据。
+ * @param mute true：静音；false：取消静音。
+ * @note 在进入房间（enterRoom）之前或之后调用本接口均生效，静音状态在退出房间（exitRoom） 之后会被重置为 false。
*/
virtual void muteAllRemoteAudio(bool mute) = 0;
/**
- * 4.6 设置某个远程用户的播放音量
+ * 5.7 设定某一个远端用户的声音播放音量
*
- * @param userId 远程用户 ID
- * @param volume 音量大小，100为原始音量，范围是：[0 ~ 150]，默认值为100
- *
- * @note 如果要将 volume 设置为大于100的数值，需要进行特殊配置，请联系技术支持。
+ * 您可以通过 setRemoteAudioVolume(userId, 0) 将某一个远端用户的声音静音。
+ * @param userId 用于指定远端用户的 ID。
+ * @param volume 音量大小，取值范围为0 - 100，默认值：100。
+ * @note 如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。
*/
- virtual void setRemoteAudioVolume(const char *userId, int volume) = 0;
+ virtual void setRemoteAudioVolume(const char* userId, int volume) = 0;
/**
- * 4.7 设置 SDK 采集音量。
- *
- * @param volume 音量大小，100为原始音量，范围是：[0 ~ 150]，默认值为100
+ * 5.8 设定本地音频的采集音量
*
- * @note 如果要将 volume 设置为大于100的数值，需要进行特殊配置，请联系技术支持。
+ * @param volume 音量大小，取值范围为0 - 100；默认值：100
+ * @note 如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。
*/
virtual void setAudioCaptureVolume(int volume) = 0;
/**
- * 4.8 获取 SDK 采集音量
+ * 5.9 获取本地音频的采集音量
*/
virtual int getAudioCaptureVolume() = 0;
/**
- * 4.9 设置 SDK 播放音量。
+ * 5.10 设定远端音频的播放音量
*
- * @param volume 音量大小，100为原始音量，范围是：[0 ~ 150]，默认值为100
+ * 该接口会控制 SDK 最终交给系统播放的声音音量，调节效果会影响到本地音频录制文件的音量大小，但不会影响到耳返的音量大小。
*
- * @note
- * 1. 该函数会控制最终交给系统播放的声音音量，会影响录制本地音频文件的音量大小，但不会影响耳返的音量。<br>
- * 2. 如果要将 volume 设置为大于100的数值，需要进行特殊配置，请联系技术支持。
+ * @param volume 音量大小，取值范围为0 - 100，默认值：100。
+ * @note 如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。
*/
virtual void setAudioPlayoutVolume(int volume) = 0;
/**
- * 4.10 获取 SDK 播放音量
+ * 5.11 获取远端音频的播放音量
*/
virtual int getAudioPlayoutVolume() = 0;
/**
- * 4.11 启用或关闭音量大小提示
- *
- * 开启此功能后，SDK 会在 onUserVoiceVolume() 中反馈对每一路声音音量大小值的评估。
- * 我们在 Demo 中有一个音量大小的提示条，就是基于这个接口实现的。
- * 如希望打开此功能，请在 startLocalAudio() 之前调用。
+ * 5.12 启用音量大小提示
*
- * @param interval 设置 onUserVoiceVolume 回调的触发间隔，单位为ms，最小间隔为100ms，如果小于等于0则会关闭回调，建议设置为300ms
+ * 开启此功能后，SDK 会在 {@link TRTCCloudDelegate} 中的 {@link onUserVoiceVolume} 回调中反馈远端音频的音量大小。
+ * @note 如需打开此功能，请在 startLocalAudio 之前调用才可以生效。
+ * @param interval 设置 onUserVoiceVolume 回调的触发间隔，单位为ms，最小间隔为100ms，如果小于等于 0 则会关闭回调，建议设置为300ms；
*/
virtual void enableAudioVolumeEvaluation(uint32_t interval) = 0;
/**
- * 4.12 开始录音
+ * 5.13 开始录音
*
- * 该方法调用后， SDK 会将通话过程中的所有音频(包括本地音频，远端音频，BGM等)录制到一个文件里。
- * 无论是否进房，调用该接口都生效。
- * 如果调用 exitRoom 时还在录音，录音会自动停止。
- *
- * @param audioRecordingParams 录音参数，请参考 TRTCAudioRecordingParams
- * @return 0：成功；-1：录音已开始；-2：文件或目录创建失败；-3：后缀指定的音频格式不支持
+ * 当您调用改接口后， SDK 会将本地和远端的所有音频（包括本地音频，远端音频，背景音乐和音效等）混合并录制到一个本地文件中。
+ * 该接口在进入房间前后调用均可生效，如果录制任务在退出房间前尚未通过 stopAudioRecording 停止，则退出房间后录制任务会自动被停止。
+ * @param param 录音参数，请参考 {@link TRTCAudioRecordingParams}
+ * @return 0：成功；-1：录音已开始；-2：文件或目录创建失败；-3：后缀指定的音频格式不支持。
*/
- virtual int startAudioRecording(const TRTCAudioRecordingParams& audioRecordingParams) = 0;
+ virtual int startAudioRecording(const TRTCAudioRecordingParams& param) = 0;
/**
- * 4.13 停止录音
+ * 5.14 停止录音
*
- * 如果调用 exitRoom 时还在录音，录音会自动停止。
+ * 如果录制任务在退出房间前尚未通过本接口停止，则退出房间后录音任务会自动被停止。
*/
virtual void stopAudioRecording() = 0;
+
+/**
+ * 5.15 开启本地媒体录制
+ *
+ * 开启后把直播过程中的音视和视频内容录制到本地的一个文件中。
+ * @param params 录制参数，请参考 {@link TRTCLocalRecordingParams}
+ */
#if _WIN32
- /**
- * 4.14 开启本地录制
- *
- * 开启后把直播过程中的音视频数据录制存储到本地文件。
- * 应用场景:
- * 1. 不推流情况下，通过调用 startLocalPreview 预览画面后，进行录制。
- * 2. 在推流的同时进行录制，把直播的全程录制保存到本地文件。
- *
- * @param params 录制参数，请参考 {@link TRTCLocalRecordingParams}
- *
- */
virtual void startLocalRecording(const TRTCLocalRecordingParams& params) = 0;
- /**
- * 4.15 停止本地录制
- *
- * 如果调用 exitRoom 时还在录制，录制会自动停止。
- */
+#endif
+
+/**
+ * 5.16 停止本地媒体录制
+ *
+ * 如果录制任务在退出房间前尚未通过本接口停止，则退出房间后录音任务会自动被停止。
+ */
+#if _WIN32
virtual void stopLocalRecording() = 0;
#endif
- /// @}
+ /// @}
/////////////////////////////////////////////////////////////////////////////////
//
- // （五）设备相关接口函数
+ // 设备管理相关接口
//
/////////////////////////////////////////////////////////////////////////////////
- /// @name 设备相关接口函数
+ /// @name 设备管理相关接口
/// @{
+
/**
- * 5.1 获取设备管理模块
- *
- * @return ITXDeviceManager 设备管理类
+ * 6.1 获取设备管理类（TXDeviceManager）
*/
- virtual ITXDeviceManager *getDeviceManager() = 0;
- /// @}
+ virtual ITXDeviceManager* getDeviceManager() = 0;
+ /// @}
/////////////////////////////////////////////////////////////////////////////////
//
- // （六）美颜特效和图像水印
+ // 美颜特效和图像水印
//
/////////////////////////////////////////////////////////////////////////////////
- /// @name 美颜特效和图像水印
+ /// @name 美颜特效和图像水印
/// @{
+
/**
- * 6.1 设置美颜、美白、红润效果级别
- *
- * SDK 内部集成了两套风格不同的磨皮算法，一套我们取名叫“光滑”，适用于美女秀场，效果比较明显。
- * 另一套我们取名“自然”，磨皮算法更多地保留了面部细节，主观感受上会更加自然。
+ * 7.1 设置美颜、美白、红润等特效
*
- * @param style 美颜风格，光滑或者自然，光滑风格磨皮更加明显，适合娱乐场景。
- * @param beautyLevel 美颜级别，取值范围0 - 9，0表示关闭，1 - 9值越大，效果越明显
- * @param whitenessLevel 美白级别，取值范围0 - 9，0表示关闭，1 - 9值越大，效果越明显
- * @param ruddinessLevel 红润级别，取值范围0 - 9，0表示关闭，1 - 9值越大，效果越明显，该参数暂未生效
+ * SDK 内部集成了两套风格不同的磨皮算法：
+ * -“光滑”：算法比较激进，磨皮效果比较明显，适用于秀场直播。
+ * -“自然”：算法更多地保留了面部细节，磨皮效果更加自然，适用于绝大多数直播场景。
+ * @param style 磨皮算法，有“光滑”和“自然”两种算法。
+ * @param beautyLevel 美颜级别，取值范围0 - 9，0表示关闭，1 - 9值越大，效果越明显。
+ * @param whitenessLevel 美白级别，取值范围0 - 9，0表示关闭，1 - 9值越大，效果越明显。
+ * @param ruddinessLevel 红润级别，取值范围0 - 9，0表示关闭，1 - 9值越大，效果越明显。
*/
virtual void setBeautyStyle(TRTCBeautyStyle style, uint32_t beautyLevel, uint32_t whitenessLevel, uint32_t ruddinessLevel) = 0;
/**
- * 6.2 设置水印
+ * 7.2 添加水印
*
* 水印的位置是通过 xOffset, yOffset, fWidthRatio 来指定的。
* - xOffset：水印的坐标，取值范围为0 - 1的浮点数。
@@ -819,590 +801,653 @@ public:
* @param xOffset 水印显示的左上角 x 轴偏移
* @param yOffset 水印显示的左上角 y 轴偏移
* @param fWidthRatio 水印显示的宽度占画面宽度比例（水印按该参数等比例缩放显示）
- * @note 只支持主路视频流
+ * @note 本接口只支持给主路视频添加图片水印
*/
virtual void setWaterMark(TRTCVideoStreamType streamType, const char* srcData, TRTCWaterMarkSrcType srcType, uint32_t nWidth, uint32_t nHeight, float xOffset, float yOffset, float fWidthRatio) = 0;
- /// @}
+ /// @}
/////////////////////////////////////////////////////////////////////////////////
//
- // （七）音乐特效和人声特效
+ // 背景音乐和声音特效
//
/////////////////////////////////////////////////////////////////////////////////
- /// @name 音乐特效和人声特效
+ /// @name 背景音乐和声音特效
/// @{
+
/**
- * 7.1 获取音效管理类 ITXAudioEffectManager
+ * 8.1 获取音效管理类（TXAudioEffectManager）
*
- * 该模块是整个 SDK 的音效管理模块，支持如下功能：
- * - 耳机耳返：麦克风捕捉的声音实时通过耳机播放。
- * - 混响效果：KTV、小房间、大会堂、低沉、洪亮...
- * - 变声特效：萝莉、大叔、重金属、外国人...
+ * TXAudioEffectManager 是音效管理接口，您可以通过该接口实现如下功能：
* - 背景音乐：支持在线音乐和本地音乐，支持变速、变调等特效、支持原生和伴奏并播放和循环播放。
- * - 短音效：鼓掌声、欢笑声等简短的音效文件，对于小于10秒的文件，请将 isShortFile 参数设置为 YES。
+ * - 耳机耳返：麦克风捕捉的声音实时通过耳机播放，常用于音乐直播。
+ * - 混响效果：KTV、小房间、大会堂、低沉、洪亮...
+ * - 变声特效：萝莉、大叔、重金属...
+ * - 短音效：鼓掌声、欢笑声等简短的音效文件（对于小于10秒的文件，请将 isShortFile 参数设置为 true）。
*/
virtual ITXAudioEffectManager* getAudioEffectManager() = 0;
+/**
+ * 8.2 开启系统声音采集（仅适用于桌面系统）
+ *
+ * 该接口会从电脑的声卡中采集音频数据，并将其混入到 SDK 当前的音频数据流中，从而使房间中的其他用户也能听到主播的电脑所播放出的声音。
+ * 在线教育场景中，老师可以使用此功能让 SDK 采集教学影片中的声音，并广播给同房间中的学生。
+ * 音乐直播场景中，主播可以使用此功能让 SDK 采集音乐播放器中的音乐，从而为自己的直播间增加背景音乐。
+ * @param deviceName
+ * - 您可以指定该参数为空置（nullptr），代表让 SDK 采集整个系统的声音。
+ * @note
+ * 在 Windows 平台下，您也可以将参数 deviceName 设置为某个应用程序的可执行文件（如 QQMuisc.exe）的绝对路径，此时 SDK 只会采集该应用程序的声音（仅支持 32 位版本的 SDK）。
+ * 您也可以指定该参数为某个扬声器设备的名称来采集特定扬声器声音（通过接口 {@link TXDeviceManager} 中的 getDevicesList 接口，可以获取类型为 {@link TXMediaDeviceTypeSpeaker} 的扬声器设备）。
+ */
#if TARGET_PLATFORM_DESKTOP
- /**
- * 7.2 打开系统声音采集
- *
- * 开启后可以采集整个操作系统的播放声音（path 为空）或某一个播放器（path 不为空）的声音，
- * 并将其混入到当前麦克风采集的声音中一起发送到云端。
- *
- *
- * @param path
- * - path 为空，代表采集整个操作系统的声音。( Windows 平台)
- * - path 填写 exe 程序（如 QQ音乐）所在的路径，将会启动此程序并只采集此程序的声音。( Windows 平台，采集程序声音仅支持32位 SDK )
- * - path 默认为空，其他值未定义。（ Mac 平台）
- *
- * @note 此接口目前仅适用于 Windows 、 Mac 平台
- */
- virtual void startSystemAudioLoopback(const char* path = nullptr) = 0;
+ virtual void startSystemAudioLoopback(const char* deviceName = nullptr) = 0;
+#endif
- /**
- * 7.3 关闭系统声音采集。
- *
- * @note 此接口目前仅适用于 Windows 、 Mac 平台
- */
+/**
+ * 8.3 停止系统声音采集（仅适用于桌面系统）
+ */
+#if TARGET_PLATFORM_DESKTOP
virtual void stopSystemAudioLoopback() = 0;
+#endif
- /**
- * 7.4 设置系统声音采集的音量。
- *
- * @param volume 音量大小，100为原始音量，取值0 - 150，默认值为100
- *
- * @note
- * 1. 此接口目前仅适用于 Windows 、 Mac 平台。<br>
- * 2. 如果要将 volume 设置为大于100的数值，需要进行特殊配置，请联系技术支持。
- */
+/**
+ * 8.4 设置系统声音的采集音量
+ *
+ * @param volume 设置的音量大小，范围是：[0 ~ 150]，默认值为100。
+ */
+#if TARGET_PLATFORM_DESKTOP || TARGET_OS_IPHONE
virtual void setSystemAudioLoopbackVolume(uint32_t volume) = 0;
#endif
- /// @}
- /////////////////////////////////////////////////////////////////////////////////
- //
- // （八）屏幕分享相关接口函数
- //
- /////////////////////////////////////////////////////////////////////////////////
- /// @name 屏幕分享相关接口函数
- /// @{
+/// @}
+/////////////////////////////////////////////////////////////////////////////////
+//
+// 屏幕分享相关接口
+//
+/////////////////////////////////////////////////////////////////////////////////
+/// @name 屏幕分享相关接口
+/// @{
+
+/**
+ * 9.1 开始桌面端屏幕分享（该接口仅支持桌面系统）
+ *
+ * 该接口可以抓取整个 Mac OS 系统的屏幕内容，或抓取您指定的某个应用的窗口内容，并将其分享给同房间中的其他用户。
+ * @param view 渲染控件所在的父控件，可以设置为空值，表示不显示屏幕分享的预览效果。
+ * @param streamType 屏幕分享使用的线路，可以设置为主路（TRTCVideoStreamTypeBig）或者辅路（TRTCVideoStreamTypeSub），推荐使用辅路。
+ * @param encParam 屏幕分享的画面编码参数，SDK 会优先使用您通过此接口设置的编码参数：
+ * - 如果您设置 encParam 为 nil，且您已通过 setSubStreamEncoderParam 设置过辅路视频编码参数，SDK 将使用您设置过的辅路编码参数进行屏幕分享。
+ * - 如果您设置 encParam 为 nil，且您未通过 setSubStreamEncoderParam 设置过辅路视频编码参数，SDK 将自动选择一个最佳的编码参数进行屏幕分享。
+ *
+ * @note
+ * 1. 同一个用户同时最多只能发布一路主路（{@link TRTCVideoStreamTypeBig}）画面和一路辅路（{@link TRTCVideoStreamTypeSub}）画面。
+ * 2. 默认情况下，屏幕分享使用辅路画面。如果使用主路做屏幕分享，您需要提前停止摄像头采集（{@link stopLocalPreview}）以避免相互冲突。
+ * 3. 同一个房间中同时只能有一个用户使用辅路做屏幕分享，也就是说，同一个房间中同时只允许一个用户开启辅路。
+ * 4. 当房间中已经有其他用户在使用辅路分享屏幕时，此时调用该接口会收到来自 {@link TRTCCloudDelegate} 的 onError(ERR_SERVER_CENTER_ANOTHER_USER_PUSH_SUB_VIDEO) 回调。
+ */
#if TARGET_PLATFORM_DESKTOP
- /**
- * 8.1 启动屏幕分享
- *
- * @param rendView 承载预览画面的控件，可以设置为 nullptr，表示不显示屏幕分享的预览效果。
- * @param type 屏幕分享使用的线路，可以设置为主路（TRTCVideoStreamTypeBig）或者辅路（TRTCVideoStreamTypeSub），默认使用辅路。
- * @param params 屏幕分享的画面编码参数，SDK 会优先使用您通过此接口设置的编码参数：
- * - 如果 params 设置为 nullptr，且您已通过 setSubStreamEncoderParam 设置过辅路视频编码参数，SDK 将使用您设置过的辅路编码参数进行屏幕分享。
- * - 如果 params 设置为 nullptr，且您未通过 setSubStreamEncoderParam 设置过辅路视频编码参数，SDK 将自适应选择最佳的编码参数进行屏幕分享。
- *
- * @note 一个用户同时最多只能上传一条主路（TRTCVideoStreamTypeBig）画面和一条辅路（TRTCVideoStreamTypeSub）画面，
- * 默认情况下，屏幕分享使用辅路画面，如果使用主路画面，建议您提前停止摄像头采集（stopLocalPreview）避免相互冲突。
- */
- virtual void startScreenCapture(TXView rendView, TRTCVideoStreamType type, TRTCVideoEncParam* params) = 0;
+ virtual void startScreenCapture(TXView view, TRTCVideoStreamType streamType, TRTCVideoEncParam* encParam) = 0;
+#endif
- /**
- * 8.2 停止屏幕采集
- */
+/**
+ * 9.2 停止屏幕分享
+ */
+#if TARGET_PLATFORM_DESKTOP
virtual void stopScreenCapture() = 0;
+#endif
- /**
- * 8.3 暂停屏幕分享
- */
+/**
+ * 9.3 暂停屏幕分享
+ */
+#if TARGET_PLATFORM_DESKTOP
virtual void pauseScreenCapture() = 0;
+#endif
- /**
- * 8.4 恢复屏幕分享
- */
+/**
+ * 9.4 恢复屏幕分享
+ */
+#if TARGET_PLATFORM_DESKTOP
virtual void resumeScreenCapture() = 0;
+#endif
- /**
- * 8.5 枚举可分享的屏幕窗口，建议在 startScreenCapture 之前调用
- *
- * 如果您要给您的 App 增加屏幕分享功能，一般需要先显示一个窗口选择界面，这样用户可以选择希望分享的窗口。
- * 通过如下函数，您可以获得可分享窗口的 ID、类型、窗口名称以及缩略图。
- * 拿到这些信息后，您就可以实现一个窗口选择界面，当然，您也可以使用我们在 Demo 源码中已经实现好的一个界面。
- *
- * @note
- * - 返回的列表中包括屏幕和应用窗口，屏幕会在列表的前面几个元素中。
- * - delete ITRTCScreenCaptureSourceList* 指针会导致编译错误，SDK 维护 ITRTCScreenCaptureSourceList 对象的生命周期。
- * - 获取完屏幕窗口列表后请手动调用 ITRTCScreenCaptureSourceList 的 release 方法释放资源，否则可能会引起内存泄漏。
- * - Windows 平台 v8.3 版本后获取窗口列表默认携带最小化窗口，且最小化窗口的缩略图数据默认填充窗口图标数据
- *
- * @param thumbSize 指定要获取的窗口缩略图大小，缩略图可用于绘制在窗口选择界面上
- * @param iconSize 指定要获取的窗口图标大小
- *
- * @return 窗口列表包括屏幕
- */
- virtual ITRTCScreenCaptureSourceList* getScreenCaptureSources(const SIZE &thumbSize, const SIZE &iconSize) = 0;
+/**
+ * 9.5 枚举可分享的屏幕和窗口（该接口仅支持桌面系统）
+ *
+ * 当您在对接桌面端系统的屏幕分享功能时，一般都需要展示一个选择分享目标的界面，这样用户能够使用这个界面选择是分享整个屏幕还是某个窗口。
+ * 通过本接口，您就可以查询到当前系统中可用于分享的窗口的 ID、名称以及缩略图。我们在 Demo 中提供了一份默认的界面实现供您参考。
+ * @note
+ * 1. 返回的列表中包含屏幕和应用窗口，屏幕是列表中的第一个元素。如果用户有多个显示器，那么每个显示器都是一个分享目标。
+ * 2. 请不要使用 delete ITRTCScreenCaptureSourceList* 删除 SourceList，这很容易导致崩溃，请使用 ITRTCScreenCaptureSourceList 中的 release 方法释放列表。
+ * @param thumbnailSize 指定要获取的窗口缩略图大小，缩略图可用于绘制在窗口选择界面上
+ * @param iconSize 指定要获取的窗口图标大小
+ * @return 窗口列表包括屏幕
+ */
+#if TARGET_PLATFORM_DESKTOP
+ virtual ITRTCScreenCaptureSourceList* getScreenCaptureSources(const SIZE& thumbnailSize, const SIZE& iconSize) = 0;
+#endif
- /**
- * 8.6 设置屏幕分享参数，该方法在屏幕分享过程中也可以调用
- *
- * 如果您期望在屏幕分享的过程中，切换想要分享的窗口，可以再次调用这个函数而不需要重新开启屏幕分享。
- *
- * 支持如下四种情况：
- * - 共享整个屏幕：sourceInfoList 中 type 为 Screen 的 source，captureRect 设为 { 0, 0, 0, 0 }
- * - 共享指定区域：sourceInfoList 中 type 为 Screen 的 source，captureRect 设为非 nullptr，例如 { 100, 100, 300, 300 }
- * - 共享整个窗口：sourceInfoList 中 type 为 Window 的 source，captureRect 设为 { 0, 0, 0, 0 }
- * - 共享窗口区域：sourceInfoList 中 type 为 Window 的 source，captureRect 设为非 nullptr，例如 { 100, 100, 300, 300 }
- *
- *
- * @param source 指定分享源
- * @param captureRect 指定捕获的区域
- * @param property 指定屏幕分享目标的属性，包括捕获鼠标，高亮捕获窗口等，详情参考TRTCScreenCaptureProperty 定义
- * @note 设置高亮边框颜色、宽度参数在 Mac 平台不生效
- *
- */
- virtual void selectScreenCaptureTarget(const TRTCScreenCaptureSourceInfo &source, const RECT& captureRect, const TRTCScreenCaptureProperty &property) = 0;
+/**
+ * 9.6 选取要分享的屏幕或窗口（该接口仅支持桌面系统）
+ *
+ * 当您通过 getScreenCaptureSources 获取到可以分享的屏幕和窗口之后，您可以调用该接口选定期望分享的目标屏幕或目标窗口。
+ * 在屏幕分享的过程中，您也可以随时调用该接口以切换分享目标。
+ * 支持如下四种情况：
+ * - 共享整个屏幕：sourceInfoList 中 type 为 Screen 的 source，captureRect 设为 { 0, 0, 0, 0 }
+ * - 共享指定区域：sourceInfoList 中 type 为 Screen 的 source，captureRect 设为非 nullptr，例如 { 100, 100, 300, 300 }
+ * - 共享整个窗口：sourceInfoList 中 type 为 Window 的 source，captureRect 设为 { 0, 0, 0, 0 }
+ * - 共享窗口区域：sourceInfoList 中 type 为 Window 的 source，captureRect 设为非 nullptr，例如 { 100, 100, 300, 300 }
+ * @param source 指定分享源
+ * @param captureRect 指定捕获的区域
+ * @param property 指定屏幕分享目标的属性，包括捕获鼠标，高亮捕获窗口等，详情参考TRTCScreenCaptureProperty 定义
+ * @note 设置高亮边框颜色、宽度参数在 Mac 平台不生效。
+ */
+#if TARGET_PLATFORM_DESKTOP
+ virtual void selectScreenCaptureTarget(const TRTCScreenCaptureSourceInfo& source, const RECT& captureRect, const TRTCScreenCaptureProperty& property) = 0;
+#endif
- /**
- * 8.7 设置屏幕分享的编码器参数
- * - setVideoEncoderParam() 用于设置远端主路画面（TRTCVideoStreamTypeBig，一般用于摄像头）的编码参数。
- * - setSubStreamEncoderParam() 用于设置远端辅路画面（TRTCVideoStreamTypeSub，一般用于屏幕分享）的编码参数。
- * 该设置决定远端用户看到的画面质量，同时也是云端录制出的视频文件的画面质量。
- *
- * @param params 辅流编码参数，详情请参考 TRTCTypeDef.h 中的 TRTCVideoEncParam 定义
- * @note 即使使用主路传输屏幕分享的数据（在调用 startScreenCapture 时设置 type=TRTCVideoStreamTypeBig），依然要使用此接口更新屏幕分享的编码参数。
- */
- virtual void setSubStreamEncoderParam(const TRTCVideoEncParam& params) = 0;
+/**
+ * 9.7 设置屏幕分享（即辅路）的视频编码参数（该接口仅支持桌面系统）
+ *
+ * 该接口可以设定远端用户所看到的屏幕分享（即辅路）的画面质量，同时也能决定云端录制出的视频文件中屏幕分享的画面质量。
+ * 请注意如下两个接口的差异：
+ * - {@link setVideoEncoderParam} 用于设置主路画面（{@link TRTCVideoStreamTypeBig}，一般用于摄像头）的视频编码参数。
+ * - {@link setSubStreamEncoderParam} 用于设置辅路画面（{@link TRTCVideoStreamTypeSub}，一般用于屏幕分享）的视频编码参数。
+ *
+ * @param param 辅流编码参数，详情请参考 {@link TRTCVideoEncParam}。
+ * @note 即使您使用主路传输屏幕分享（在调用 startScreenCapture 时设置 type=TRTCVideoStreamTypeBig），依然要使用 {@link setSubStreamEncoderParam} 设定屏幕分享的编码参数，而不要使用 {@link setVideoEncoderParam} 。
+ */
+#if TARGET_PLATFORM_DESKTOP
+ virtual void setSubStreamEncoderParam(const TRTCVideoEncParam& param) = 0;
+#endif
- /**
- * 8.8 设置屏幕分享的混音音量大小
- *
- * 这个数值越高，屏幕分享音量的占比就越高，麦克风音量占比就越小，所以不推荐设置得太大，否则麦克风的声音就被压制了。
- *
- * @param volume 设置的混音音量大小，范围0 - 100
- */
+/**
+ * 9.8 设置屏幕分享时的混音音量大小（该接口仅支持桌面系统）
+ *
+ * 这个数值越高，屏幕分享音量的占比就越高，麦克风音量占比就越小，所以不推荐设置得太大，否则麦克风的声音就被压制了。
+ * @param volume 设置的混音音量大小，范围0 - 100。
+ */
+#if TARGET_PLATFORM_DESKTOP
virtual void setSubStreamMixVolume(uint32_t volume) = 0;
+#endif
- /**
- * 8.9 将指定窗口加入屏幕分享的排除列表中，加入排除列表中的窗口不会被分享出去
- *
- * 支持启动屏幕分享前设置过滤窗口，也支持屏幕分享过程中动态添加过滤窗口。
- *
- * @param window 不希望分享出去的窗口
- * @note
- * - 该方法只有在 TRTCScreenCaptureSourceInfo 中的 type 指定为 TRTCScreenCaptureSourceTypeScreen 时生效，即分享屏幕时生效
- * - 该方法添加的窗口列表会在退房后清除
- * - Mac 平台下请传入窗口 ID（即 CGWindowID），您可以通过 TRTCScreenCaptureSourceInfo 中的 sourceId 成员获得。
- */
- virtual void addExcludedShareWindow(TXView window) = 0;
+/**
+ * 9.9 将指定窗口加入屏幕分享的排除列表中（该接口仅支持桌面系统）
+ *
+ * 加入排除列表中的窗口不会被分享出去，常见的用法是将某个应用的窗口加入到排除列表中以避免隐私问题。
+ * 支持启动屏幕分享前设置过滤窗口，也支持屏幕分享过程中动态添加过滤窗口。
+ * @param windowID 不希望分享出去的窗口
+ * @note
+ * 1. 该接口只有在 {@link TRTCScreenCaptureSourceInfo} 中的 type 指定为 {@link TRTCScreenCaptureSourceTypeScreen} 时生效，即只有在分享整个屏幕内容时，排除指定窗口的功能才生效。
+ * 2. 使用该接口添加到排除列表中的窗口会在退出房间后被 SDK 自动清除。
+ * 3. Mac 平台下请传入窗口 ID（即 CGWindowID），您可以通过 {@link TRTCScreenCaptureSourceInfo} 中的 sourceId 成员获得。
+ */
+#if TARGET_PLATFORM_DESKTOP
+ virtual void addExcludedShareWindow(TXView windowID) = 0;
+#endif
- /**
- * 8.10 将指定窗口从屏幕分享的排除列表中移除
- *
- * @param window 不希望分享出去的窗口
- *
- * @note
- * - 该方法只有在 TRTCScreenCaptureSourceInfo 中的 type 指定为 TRTCScreenCaptureSourceTypeScreen 时生效，即分享屏幕时生效
- * - Mac 平台下请传入窗口 ID（即 CGWindowID），您可以通过 TRTCScreenCaptureSourceInfo 中的 sourceId 成员获得。
- */
- virtual void removeExcludedShareWindow(TXView window) = 0;
+/**
+ * 9.10 将指定窗口从屏幕分享的排除列表中移除（该接口仅支持桌面系统）
+ *
+ * @param windowID
+ */
+#if TARGET_PLATFORM_DESKTOP
+ virtual void removeExcludedShareWindow(TXView windowID) = 0;
+#endif
- /**
- * 8.11 将所有窗口从屏幕分享的排除列表中移除
- *
- * @note 该方法只有在 TRTCScreenCaptureSourceInfo 中的 type 指定为 TRTCScreenCaptureSourceTypeScreen 时生效，即分享屏幕时生效
- */
+/**
+ * 9.11 将所有窗口从屏幕分享的排除列表中移除（该接口仅支持桌面系统）
+ */
+#if TARGET_PLATFORM_DESKTOP
virtual void removeAllExcludedShareWindow() = 0;
+#endif
- /**
- * 8.12 将指定窗口加入屏幕分享的包含列表中，加入包含列表中的窗口如果在采集窗口区域内会被分享出去
- *
- * 支持启动屏幕分享前设置包含的窗口，也支持屏幕分享过程中动态添加包含的窗口。
- *
- * @param window 希望被分享出去的窗口
- * @note
- * - 该方法只有在 TRTCScreenCaptureSourceInfo 中的 type 指定为 TRTCScreenCaptureSourceTypeWindow 时生效，即分享窗口时生效
- * - 该方法添加的窗口列表会在退房后清除
- * - Mac 平台下请传入窗口 ID（即 CGWindowID），您可以通过 TRTCScreenCaptureSourceInfo 中的 sourceId 成员获得
- */
- virtual void addIncludedShareWindow(TXView window) = 0;
+/**
+ * 9.12 将指定窗口加入屏幕分享的包含列表中（该接口仅支持桌面系统）
+ *
+ * 该接口只有在 {@link TRTCScreenCaptureSourceInfo} 中的 type 指定为 {@link TRTCScreenCaptureSourceTypeWindow} 时生效。即只有在分享窗口内容时，额外包含指定窗口的功能才生效。
+ * 您在 {@link startScreenCapture} 之前和之后调用均可。
+ * @param windowID 希望被分享出去的窗口（Windows 平台下为窗口句柄： HWND）
+ * @note 通过该方法添加到包含列表中的窗口，会在退出房间后被 SDK 自动清除。
+ */
+#if TARGET_PLATFORM_DESKTOP
+ virtual void addIncludedShareWindow(TXView windowID) = 0;
+#endif
- /**
- * 8.13 将指定窗口从屏幕分享的包含列表中移除
- *
- * @param window 希望被分享出去的窗口
- * @note
- * - 该方法只有在 TRTCScreenCaptureSourceInfo 中的 type 指定为 TRTCScreenCaptureSourceTypeWindow 时生效，即分享窗口时生效
- * - Mac 平台下请传入窗口 ID（即 CGWindowID），您可以通过 TRTCScreenCaptureSourceInfo 中的 sourceId 成员获得
- */
- virtual void removeIncludedShareWindow(TXView window) = 0;
+/**
+ * 9.13 将指定窗口从屏幕分享的包含列表中移除（该接口仅支持桌面系统）
+ *
+ * 该接口只有在 {@link TRTCScreenCaptureSourceInfo} 中的 type 指定为 {@link TRTCScreenCaptureSourceTypeWindow} 时生效。
+ * 即只有在分享窗口内容时，额外包含指定窗口的功能才生效。
+ * @param windowID 希望被分享出去的窗口（Mac 平台: 窗口 ID；Windows 平台： HWND）
+ */
+#if TARGET_PLATFORM_DESKTOP
+ virtual void removeIncludedShareWindow(TXView windowID) = 0;
+#endif
- /**
- * 8.14 将所有窗口从屏幕分享的包含列表中移除
- *
- * @note 该方法只有在 TRTCScreenCaptureSourceInfo 中的 type 指定为 TRTCScreenCaptureSourceTypeWindow 时生效，即分享窗口时生效
- */
+/**
+ * 9.14 将全部窗口从屏幕分享的包含列表中移除（该接口仅支持桌面系统）
+ *
+ * 该接口只有在 {@link TRTCScreenCaptureSourceInfo} 中的 type 指定为 {@link TRTCScreenCaptureSourceTypeWindow} 时生效。
+ * 即只有在分享窗口内容时，额外包含指定窗口的功能才生效。
+ */
+#if TARGET_PLATFORM_DESKTOP
virtual void removeAllIncludedShareWindow() = 0;
#endif
- /// @}
+ /// @}
/////////////////////////////////////////////////////////////////////////////////
//
- // （九）自定义采集和渲染
+ // 自定义采集和自定义渲染
//
/////////////////////////////////////////////////////////////////////////////////
- /// @name 自定义采集和渲染
+ /// @name 自定义采集和自定义渲染
/// @{
-#ifdef _WIN32
+
/**
- * 9.1 启用视频自定义采集模式
+ * 10.1 启用/关闭视频自定义采集模式
*
- * 开启该模式后，SDK 不再运行原有视频流上的采集流程，只保留编码和发送能力。
- * 您需要用 sendCustomVideoData() 不断地向 SDK 塞入自己采集的视频画面。
- *
- * @param type 视频流类型：
- * - 高清大画面：({@link TRTCVideoStreamTypeBig})
- * - 辅流（屏幕分享）：({@link TRTCVideoStreamTypeSub})
- * @param enable 是否启用，默认值：false
+ * 开启该模式后，SDK 不在运行原有的视频采集流程，即不再继续从摄像头采集数据和美颜，而是只保留视频编码和发送能力。
+ * 您需要通过 {@link sendCustomVideoData} 不断地向 SDK 塞入自己采集的视频画面。
+ * @param streamType 用于指定视频流类型，{@link TRTCVideoStreamTypeBig}：高清大画面；{@link TRTCVideoStreamTypeSub}：辅路画面。
+ * @param enable 是否启用，默认值：false。
*/
- virtual void enableCustomVideoCapture(TRTCVideoStreamType type, bool enable) = 0;
+ virtual void enableCustomVideoCapture(TRTCVideoStreamType streamType, bool enable) = 0;
- /**
- * 9.2 向 SDK 投送自己采集的视频数据
+ /**
+ * 10.2 向 SDK 投送自己采集的视频帧
*
- * TRTCVideoFrame 推荐如下填写方式（其他字段不需要填写）：
- * - pixelFormat： Windows、Android 平台仅支持 TRTCVideoPixelFormat_I420
- * iOS、Mac 平台支持 TRTCVideoPixelFormat_I420 和 TRTCVideoPixelFormat_BGRA32
- * - bufferType：仅支持 TRTCVideoBufferType_Buffer。
- * - data：视频帧 buffer。
- * - length：视频帧数据长度，I420 格式下，其值等于：width × height × 3 / 2。
- * - width：视频图像长度。
- * - height：视频图像宽度。
- * - timestamp：时间戳，单位毫秒（ms）。如果 timestamp 间隔不均匀，会严重影响音画同步和录制出的 MP4 质量。
+ * 使用此接口可以向 SDK 投送自己采集的视频帧，SDK 会将视频帧进行编码并通过自身的网络模块传输出去。
+ * 参数 {@link TRTCVideoFrame} 推荐下列填写方式（其他字段不需要填写）：
+ * - pixelFormat：Windows 和 Android 平台仅支持 {@link TRTCVideoPixelFormat_I420}，iOS 和 Mac平台支持 {@link TRTCVideoPixelFormat_I420} 和 {@link TRTCVideoPixelFormat_BGRA32}。
+ * - bufferType：推荐选择 {@link TRTCVideoBufferType_Buffer}。
+ * - data：用于承载视频帧数据的 buffer。
+ * - length：视频帧数据长度，如果 pixelFormat 设定为 I420 格式，length 可以按照如下公式计算：length = width × height × 3 / 2。
+ * - width：视频图像的宽度，如 640 px。
+ * - height：视频图像的高度，如 480 px。
+ * - timestamp：时间戳，单位为毫秒（ms），请使用视频帧在采集时被记录下来的时间戳（可以在采集到一帧视频帧之后，通过调用 {@link generateCustomPTS} 获取时间戳）。
*
* 参考文档：[自定义采集和渲染](https://cloud.tencent.com/document/product/647/34066)。
- * @param type 指定视频流类型：
- * - 高清大画面：({@link TRTCVideoStreamTypeBig})
- * - 辅流（屏幕分享）：({@link TRTCVideoStreamTypeSub})
+ * @param streamType 用于指定视频流类型，{@link TRTCVideoStreamTypeBig}：高清大画面；{@link TRTCVideoStreamTypeSub}：辅路画面。
* @param frame 视频数据，支持 I420 格式数据。
- * @note - SDK 内部有帧率控制逻辑，目标帧率以您在 setVideoEncoderParam (高清大画面) 或者 setSubStreamEncoderParam (辅流) 中设置的为准。
- * - 可以设置 frame 中的 timestamp 为 0，相当于让 SDK 自己设置时间戳，但请“均匀”地控制 sendCustomVideoData 的调用间隔，否则会导致视频帧率不稳定。
- * - Windows 平台目前仅支持传入 TRTCVideoPixelFormat_I420 格式的视频帧
+ * @note
+ * 1. 推荐您在采集到的一帧视频帧后，即调用 {@link generateCustomPTS} 接口获取该帧的 timestamp 数值，这样可以获得最佳的音画同步效果。
+ * 2. SDK 最终编码出的视频帧率并不是由您调用本接口的频率决定的，而是由您在 {@link setVideoEncoderParam} 中所设置的 FPS 决定的。
+ * 3. 请尽量保持本接口的调用间隔是均匀的，否则会导致编码器输出帧率不稳或者音画不同步等问题。
+ * 4. iOS 和 Mac平台目前支持传入 {@link TRTCVideoPixelFormat_I420} 或 {@link TRTCVideoPixelFormat_BGRA32} 格式的视频帧。
+ * 5. Windows 和 Android 平台目前仅支持传入 {@link TRTCVideoPixelFormat_I420} 格式的视频帧。
*/
- virtual void sendCustomVideoData(TRTCVideoStreamType type, TRTCVideoFrame* frame) = 0;
-#else
+ virtual void sendCustomVideoData(TRTCVideoStreamType streamType, TRTCVideoFrame* frame) = 0;
+
/**
- * 9.1 启用视频自定义采集模式
+ * 10.3 启用音频自定义采集模式
*
- * 开启该模式后，SDK 不再运行原有的视频采集流程，只保留编码和发送能力。
- * 您需要用 sendCustomVideoData() 不断地向 SDK 塞入自己采集的视频画面。
- *
- * @param enable 是否启用，默认值：false
+ * 开启该模式后，SDK 不在运行原有的音频采集流程，即不再继续从麦克风采集音频数据，而是只保留音频编码和发送能力。
+ * 您需要通过 {@link sendCustomAudioData} 不断地向 SDK 塞入自己采集的音频数据。
+ * @param enable 是否启用，默认值：false。
+ * @note 由于回声抵消（AEC）需要严格的控制声音采集和播放的时间，所以开启自定义音频采集后，AEC 能力可能会失效。
*/
- virtual void enableCustomVideoCapture(bool enable) = 0;
+ virtual void enableCustomAudioCapture(bool enable) = 0;
/**
- * 9.2 向 SDK 投送自己采集的视频数据
+ * 10.4 向 SDK 投送自己采集的音频数据
*
- * TRTCVideoFrame 推荐如下填写方式（其他字段不需要填写）：
- * - pixelFormat： Windows、Android 平台仅支持 TRTCVideoPixelFormat_I420
- * iOS、Mac 平台支持 TRTCVideoPixelFormat_I420 和 TRTCVideoPixelFormat_BGRA32
- * - bufferType：仅支持 TRTCVideoBufferType_Buffer。
- * - data：视频帧 buffer。
- * - length：视频帧数据长度，I420 格式下，其值等于：width × height × 3 / 2。
- * - width：视频图像长度。
- * - height：视频图像宽度。
- * - timestamp：时间戳，单位毫秒（ms）。如果 timestamp 间隔不均匀，会严重影响音画同步和录制出的 MP4 质量。
+ * 参数 {@link TRTCAudioFrame} 推荐下列填写方式（其他字段不需要填写）：
+ * - audioFormat：音频数据格式，仅支持 TRTCAudioFrameFormatPCM。
+ * - data：音频帧 buffer。音频帧数据只支持 PCM 格式，支持[5ms ~ 100ms]帧长，推荐使用 20ms 帧长，长度计算方法：【48000采样率、单声道的帧长度：48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节】。
+ * - sampleRate：采样率，支持：16000、24000、32000、44100、48000。
+ * - channel：声道数（如果是立体声，数据是交叉的），单声道：1； 双声道：2。
+ * - timestamp：时间戳，单位为毫秒（ms），请使用音频帧在采集时被记录下来的时间戳（可以在采集到一帧音频帧之后，通过调用 {@link generateCustomPTS} 获取时间戳）。
*
* 参考文档：[自定义采集和渲染](https://cloud.tencent.com/document/product/647/34066)。
- *
- * @param frame 视频数据，支持 I420 格式数据。
- * @note - SDK 内部有帧率控制逻辑，目标帧率以您在 setVideoEncoderParam 中设置的为准，太快会自动丢帧，太慢则会自动补帧。
- * - 可以设置 frame 中的 timestamp 为 0，相当于让 SDK 自己设置时间戳，但请“均匀”地控制 sendCustomVideoData 的调用间隔，否则会导致视频帧率不稳定。
- * - iOS、Mac平台目前仅支持传入 TRTCVideoPixelFormat_I420 或 TRTCVideoPixelFormat_BGRA32 格式的视频帧
- * - Android 平台目前仅支持传入 TRTCVideoPixelFormat_I420 格式的视频帧
+ * @param frame 音频数据
+ * @note 请您精准地按每帧时长的间隔调用本接口，数据投送间隔不均匀时极易触发声音卡顿。
*/
- virtual void sendCustomVideoData(TRTCVideoFrame* frame) = 0;
-#endif
-
+ virtual void sendCustomAudioData(TRTCAudioFrame* frame) = 0;
+
/**
- * 9.3 启用音频自定义采集模式
- * 开启该模式后，SDK 停止运行原有的音频采集流程，只保留编码和发送能力。
- * 您需要用 sendCustomAudioData() 不断地向 SDK 塞入自己采集的音频数据。
+ * 10.5 启用/关闭自定义音轨
*
- * @param enable 是否启用，默认值：false
+ * 开启后，您可以通过本接口向 SDK 混入一条自定义的音轨。通过两个布尔型参数，您可以控制该音轨是否要在远端和本地播放。
+ * @param enablePublish 控制混入的音轨是否要在远端播放，默认值：false。
+ * @param enablePlayout 控制混入的音轨是否要在本地播放，默认值：false。
+ * @note 如果您指定参数 enablePublish 和 enablePlayout 均为 false，代表完全关闭您的自定义音轨。
*/
- virtual void enableCustomAudioCapture(bool enable) = 0;
-
+ virtual void enableMixExternalAudioFrame(bool enablePublish, bool enablePlayout) = 0;
+
/**
- * 9.4 向 SDK 投送自己采集的音频数据
+ * 10.6 向 SDK 混入自定义音轨
*
- * TRTCAudioFrame 推荐如下填写方式：
- * - audioFormat：音频数据格式，仅支持 TRTCAudioFrameFormatPCM。
- * - data：音频帧 buffer。
- * - length：音频帧数据长度，支持[5ms ~ 100ms]帧长，推荐使用20 ms帧长，【48000采样率、单声道的帧长度：48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节】。
+ * 调用该接口之前，您需要先通过 {@link enableMixExternalAudioFrame} 开启自定义音轨，之后就可以通过本接口将自己的音轨以 PCM 格式混入到 SDK 中。
+ * 理想情况下，我们期望您的代码能够以非常均匀的速度向 SDK 提供音轨数据。但我们也非常清楚，完美的调用间隔是一个巨大的挑战。
+ * 所以 SDK 内部会开启一个音轨数据的缓冲区，该缓冲区的作用类似一个“蓄水池”，它能够暂存您传入的音轨数据，平抑由于接口调用间隔的抖动问题。
+ * 本接口的返回值代表这个音轨缓冲区的大小，单位是毫秒（ms），比如：如果该接口返回 50，则代表当前的音轨缓冲区有 50ms 的音轨数据。因此只要您在 50ms 内再次调用本接口，SDK 就能保证您混入的音轨数据是连续的。
+ * 当您调用该接口后，如果发现返回值 > 100ms，则可以等待一帧音频帧的播放时间之后再次调用；如果返回值 < 100ms，则代表缓冲区比较小，您可以再次混入一些音轨数据以确保音轨缓冲区的大小维持在“安全水位”以上。
+ * 参数 {@link TRTCAudioFrame} 推荐下列填写方式（其他字段不需要填写）：
+ * - data：音频帧 buffer。音频帧数据只支持 PCM 格式，支持[5ms ~ 100ms]帧长，推荐使用 20ms 帧长，长度计算方法：【48000采样率、单声道的帧长度：48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节】。
* - sampleRate：采样率，支持：16000、24000、32000、44100、48000。
* - channel：声道数（如果是立体声，数据是交叉的），单声道：1； 双声道：2。
- * - timestamp：时间戳，单位毫秒（ms）。如果 timestamp 间隔不均匀，会严重影响音画同步和录制出的 MP4 质量。
- *
- * 参考文档：[自定义采集和渲染](https://cloud.tencent.com/document/product/647/34066)。
+ * - timestamp：时间戳，单位为毫秒（ms），请使用音频帧在采集时被记录下来的时间戳（可以在获得一帧音频帧之后，通过调用 {@link generateCustomPTS} 获得时间戳）。
*
* @param frame 音频数据
- * @note 可以设置 frame 中的 timestamp 为 0，相当于让 SDK 自己设置时间戳，但请“均匀”地控制 sendCustomAudioData 的调用间隔，否则会导致声音断断续续。
+ *
+ * @return >= 0 缓冲的长度，单位：ms。< 0 错误（-1 未启用 mixExternalAudioFrame）
+ *
+ * @note 请您精准地按每帧时长的间隔调用本接口，数据投送间隔不均匀时极易触发声音卡顿。
*/
- virtual void sendCustomAudioData(TRTCAudioFrame* frame) = 0;
-#ifdef _WIN32
+ virtual int mixExternalAudioFrame(TRTCAudioFrame* frame) = 0;
+
/**
- * 9.5 控制外部音频是否要混入推流和混入播放
- *
- * 通过 mixExternalAudioFrame() 增加一路音频混合到推流的音频流，同时可以支持本地播放
+ * 10.7 设置推流时混入外部音频的推流音量和播放音量
*
- * @param enablePublish 是否混入推流 true：混入推流；false：不混入推流，默认值：false
- * @param enablePlayout 是否混入本地播放 true：混入播放；false：不混入播放，默认值：false
- * @note enablePublish = false， enablePlayout = false 时，表示完全关闭这个额外的音频流，即不推流，也不播放
+ * @param publishVolume 设置的推流音量大小，范围0 - 100, -1表示不改变
+ * @param playoutVolume 设置的播放音量大小，范围0 - 100, -1表示不改变
*/
- virtual void enableMixExternalAudioFrame(bool enablePublish, bool enablePlayout) = 0;
+ virtual void setMixExternalAudioVolume(int publishVolume, int playoutVolume) = 0;
/**
- * 9.6 向 SDK 发送自定义辅流音频数据
+ * 10.8 生成自定义采集时的时间戳
*
- * TRTCAudioFrame 推荐如下填写方式（其他字段不需要填写）：
- * - audioFormat：仅支持 TRTCAudioFrameFormatPCM。
- * - data：音频帧 buffer。
- * - length：音频帧数据长度，推荐每帧20ms采样数。【PCM格式、48000采样率、单声道的帧长度：48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节】。
- * - sampleRate：采样率，仅支持48000。
- * - channel：频道数量（如果是立体声，数据是交叉的），单声道：1； 双声道：2。
- * - timestamp：时间戳，单位毫秒（ms）。如果 timestamp 间隔不均匀，会严重影响音画同步和录制出的 MP4 质量。
+ * 本接口仅适用于自定义采集模式，用于解决音视频帧的采集时间（capture time）和投送时间（send time）不一致所导致的音画不同步问题。
+ * 当您通过 {@link sendCustomVideoData} 或 {@link sendCustomAudioData} 等接口进行自定义视频或音频采集时，请按照如下操作使用该接口：
+ * 1. 首先，在采集到一帧视频或音频帧时，通过调用本接口获得当时的 PTS 时间戳。
+ * 2. 之后可以将该视频或音频帧送入您使用的前处理模块（如第三方美颜组件，或第三方音效组件）。
+ * 3. 在真正调用 {@link sendCustomVideoData} 或 {@link sendCustomAudioData} 进行投送时，请将该帧在采集时记录的 PTS 时间戳赋值给 {@link TRTCVideoFrame} 或 {@link TRTCAudioFrame} 中的 timestamp 字段。
*
- * @param frame 音频数据
- * @note 可以设置 frame 中的 timestamp 为 0，相当于让 SDK 自己设置时间戳，但请“均匀”地控制 mixExternalAudioFrame 的调用间隔，否则会导致声音断断续续。
+ * @return 时间戳（单位：ms）
*/
- virtual void mixExternalAudioFrame(TRTCAudioFrame* frame) = 0;
-#endif
+ virtual uint64_t generateCustomPTS() = 0;
+
+ /**
+ * 10.9 设置第三方美颜的视频数据回调
+ *
+ * 设置该回调之后，SDK 会把采集到的视频帧通过您设置的 callback 回调出来，用于第三方美颜组件进行二次处理，之后 SDK 会将处理后的视频帧进行编码和发送。
+ * @param pixelFormat 指定回调的像素格式，出于数据处理效率的考虑，目前仅支持 OpenGL 纹理格式数据。
+ * @param bufferType 指定视频数据结构类型，出于数据处理效率的考虑，目前仅支持 OpenGL 纹理格式数据。
+ * @param callback 自定义渲染回调，详见 {@link ITRTCVideoFrameCallback}
+ * @return 0：成功；<0：错误
+ */
+ virtual int setLocalVideoProcessCallback(TRTCVideoPixelFormat pixelFormat, TRTCVideoBufferType bufferType, ITRTCVideoFrameCallback* callback) = 0;
+
/**
- * 9.7 设置本地视频自定义渲染
+ * 10.10 设置本地视频自定义渲染回调
+ *
+ * 设置该回调之后，SDK 内部会跳过原来的渲染流程，并把采集到的数据回调出来，您需要自己完成画面渲染。
+ * - 您可以通过调用 setLocalVideoRenderCallback(TRTCVideoPixelFormat_Unknown, TRTCVideoBufferType_Unknown, nullptr) 停止回调。
+ * - iOS、Mac、Windows 平台目前仅支持回调 {@link TRTCVideoPixelFormat_I420} 或 {@link TRTCVideoPixelFormat_BGRA32} 像素格式的视频帧。
+ * - Android 平台目前仅支持传入 {@link TRTCVideoPixelFormat_I420} 像素格式的视频帧。
*
- * @note - 设置此方法，SDK 内部会把采集到的数据回调出来，SDK 跳过 TXView 渲染逻辑
- * - 调用 setLocalVideoRenderCallback(TRTCVideoPixelFormat_Unknown, TRTCVideoBufferType_Unknown, nullptr) 停止回调。
- * - iOS、Mac、Windows 平台目前仅支持回调 TRTCVideoPixelFormat_I420 或 TRTCVideoPixelFormat_BGRA32 像素格式的视频帧
- * - Android 平台目前仅支持回调 TRTCVideoPixelFormat_I420 或 TRTCVideoPixelFormat_RGBA32 像素格式的视频帧
* @param pixelFormat 指定回调的像素格式
- * @param bufferType 指定视频数据结构类型，目前只支持 TRTCVideoBufferType_Buffer
+ * @param bufferType 指定视频数据结构类型，目前只支持 {@link TRTCVideoBufferType_Buffer}
* @param callback 自定义渲染回调
* @return 0：成功；<0：错误
*/
virtual int setLocalVideoRenderCallback(TRTCVideoPixelFormat pixelFormat, TRTCVideoBufferType bufferType, ITRTCVideoRenderCallback* callback) = 0;
/**
- * 9.8 设置远端视频自定义渲染
+ * 10.11 设置远端视频自定义渲染回调
*
- * 此方法同 setLocalVideoRenderDelegate，区别在于一个是本地画面的渲染回调， 一个是远程画面的渲染回调。
+ * 设置该回调之后，SDK 内部会跳过原来的渲染流程，并把采集到的数据回调出来，您需要自己完成画面渲染。
+ * - 您可以通过调用 setLocalVideoRenderCallback(TRTCVideoPixelFormat_Unknown, TRTCVideoBufferType_Unknown, nullptr) 停止回调。
+ * - iOS、Mac、Windows 平台目前仅支持回调 {@link TRTCVideoPixelFormat_I420} 或 {@link TRTCVideoPixelFormat_BGRA32} 像素格式的视频帧。
+ * - Android 平台目前仅支持传入 {@link TRTCVideoPixelFormat_I420} 像素格式的视频帧。
*
- * @note - 设置此方法，SDK 内部会把远端的数据解码后回调出来，SDK 跳过 TXView 渲染逻辑
- * - 调用 setRemoteVideoRenderCallback(userId, TRTCVideoPixelFormat_Unknown, TRTCVideoBufferType_Unknown, nullptr) 停止回调。
- * - iOS、Mac、Windows 平台目前仅支持回调 TRTCVideoPixelFormat_I420 或 TRTCVideoPixelFormat_BGRA32 像素格式的视频帧
- * - Android 平台目前仅支持回调 TRTCVideoPixelFormat_I420 或 TRTCVideoPixelFormat_RGBA32 像素格式的视频帧
- * @param userId 用户标识
- * @param pixelFormat 指定回调的像素格式
- * @param bufferType 指定视频数据结构类型，目前只支持 TRTCVideoBufferType_Buffer
+ * @note 实际使用时，需要先调用 startRemoteView(userid, nullptr) 来获取远端用户的视频流（view 设置为 nullptr 即可），否则不会有数据回调出来。
+ * @param userId 远端用户id
+ * @param pixelFormat 指定回调的像素格式
+ * @param bufferType 指定视频数据结构类型，目前只支持 {@link TRTCVideoBufferType_Buffer}
* @param callback 自定义渲染回调
* @return 0：成功；<0：错误
*/
virtual int setRemoteVideoRenderCallback(const char* userId, TRTCVideoPixelFormat pixelFormat, TRTCVideoBufferType bufferType, ITRTCVideoRenderCallback* callback) = 0;
/**
- * 9.9 设置音频数据回调
+ * 10.12 设置音频数据自定义回调
*
- * 设置此方法，SDK 内部会把声音模块的数据（PCM 格式）回调出来，包括：
- * - onCapturedAudioFrame：本机麦克风采集到的音频数据
- * - onPlayAudioFrame：混音前的每一路远程用户的音频数据
- * - onMixedPlayAudioFrame：各路音频数据混合后送入扬声器播放的音频数据
+ * 设置该回调之后，SDK 内部会把音频数据（PCM 格式）回调出来，包括：
+ * - {@link onCapturedRawAudioFrame}：本地麦克风采集到的原始音频数据回调
+ * - {@link onLocalProcessedAudioFrame}：本地采集并经过音频模块前处理后的音频数据回调
+ * - {@link onRemoteUserAudioFrame}：混音前的每一路远程用户的音频数据
+ * - {@link onMixedPlayAudioFrame}：将各路音频混合之后并最终要由系统播放出的音频数据回调
*
- * @param callback 声音帧数据（PCM 格式）的回调，callback = nullptr 则停止回调数据
- * @return 0：成功；<0：错误
+ * @note 设置回调为空即代表停止自定义音频回调，反之，设置回调不为空则代表启动自定义音频回调。
*/
virtual int setAudioFrameCallback(ITRTCAudioFrameCallback* callback) = 0;
+
+ /**
+ * 10.16 开启音频自定义播放
+ *
+ * 如果您需要外接一些特定的音频设备，或者希望自己掌控音频的播放逻辑，您可以通过该接口启用音频自定义播放。
+ * 启用音频自定义播放后，SDK 将不再调用系统的音频接口播放数据，您需要通过 {@link getCustomAudioRenderingFrame} 获取 SDK 要播放的音频帧并自行播放。
+ * @param enable 是否启用音频自定义播放，默认为关闭状态。
+ * @note 需要您在进入房间前设置才能生效，暂不支持进入房间后再设置。
+ */
+ virtual void enableCustomAudioRendering(bool enable) = 0;
+
/**
- * 9.8 生成自定义采集时间戳
+ * 10.17 获取可播放的音频数据
*
- * 此函数仅适合自定义视频采集时使用，当您的 App 自己或由第三方美颜 SDK 调用摄像头 API 采集视频时，由于可能引入一些耗时的外部操作（比如美颜），这会导致视频的节奏和 SDK 内部的音频节奏不一致，进而导致音画不同步。
- * 为避免发生音画不同步的问题，请按照如下步骤正确使用该接口：
- * 1. 在调用系统相机 API 采集到一帧视频时，额外调用一次 generateCustomPTS() 获得 pts 时间戳。
- * 2. 在调用 {@link sendCustomVideoData()} 时，将该帧采集时记录的 pts 时间戳赋值给入参 TRTCVideoFrame 中的 timestamp 字段。
+ * 调用该接口之前，您需要先通过 {@link enableCustomAudioRendering} 开启音频自定义播放。
+ * 参数 {@link TRTCAudioFrame} 推荐下列填写方式（其他字段不需要填写）：
+ * - sampleRate：采样率，必填，支持 16000、24000、32000、44100、48000。
+ * - channel：声道数，必填，单声道请填1，双声道请填2，双声道时数据是交叉的。
+ * - data：用于获取音频数据的 buffer。需要您根据一阵音频帧的帧长度分配好 date 的内存大小。
+ * 获取的 PCM 数据支持 10ms 或 20ms 两种帧长，推荐使用 20ms 的帧长。
+ * 计算公式为：48000采样率、单声道、且播放时长为 20ms 的一帧音频帧的 buffer 大小为 48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节。
+ *
+ * @param audioFrame 音频数据帧。
+ * @note
+ * 1. 参数 audioFrame 中的 sampleRate、channel 需提前设置好，同时分配好所需读取帧长的 data 空间。
+ * 2. SDK 内部会根据 sampleRate 和 channel 自动填充 data 数据。
+ * 3. 建议由系统的音频播放线程直接驱动该函数的调用，在播放完一帧音频之后，即调用该接口获取下一帧可播放的音频数据。
*
- * @return 时间戳（单位：ms）
*/
- virtual uint64_t generateCustomPTS() = 0;
- /// @}
+ virtual void getCustomAudioRenderingFrame(TRTCAudioFrame* audioFrame) = 0;
+ /// @}
/////////////////////////////////////////////////////////////////////////////////
//
- // （十）自定义消息发送
+ // 自定义消息发送接口
//
/////////////////////////////////////////////////////////////////////////////////
- /// @name 自定义消息发送
+ /// @name 自定义消息发送接口
/// @{
+
/**
- * 10.1 发送自定义消息给房间内所有用户
- *
- * 该接口可以借助音视频数据通道向当前房间里的其他用户广播您自定义的数据，但因为复用了音视频数据通道，
- * 请务必严格控制自定义消息的发送频率和消息体的大小，否则会影响音视频数据的质量控制逻辑，造成不确定性的问题。
- *
- * @param cmdId 消息 ID，取值范围为1 - 10
- * @param data 待发送的消息，最大支持1KB（1000字节）的数据大小
- * @param dataSize 待发送的数据大小
- * @param reliable 是否可靠发送，可靠发送的代价是会引入一定的延时，因为接收端要暂存一段时间的数据来等待重传
- * @param ordered 是否要求有序，即是否要求接收端接收的数据顺序和发送端发送的顺序一致，这会带来一定的接收延时，因为在接收端需要暂存并排序这些消息
- * @return true：消息已经发出；false：消息发送失败
+ * 11.1 使用 UDP 通道发送自定义消息给房间内所有用户
*
- * @note 本接口有以下限制：
- * - 发送消息到房间内所有用户（暂时不支持 Web/小程序端），每秒最多能发送30条消息。
- * - 每个包最大为1KB，超过则很有可能会被中间路由器或者服务器丢弃。
- * - 每个客户端每秒最多能发送总计8KB数据。
- * - 将 reliable 和 ordered 同时设置为 true 或 false，暂不支持交叉设置。
- * - 强烈建议不同类型的消息使用不同的 cmdID，这样可以在要求有序的情况下减小消息时延。
+ * 该接口可以让您借助 TRTC 的 UDP 通道，向当前房间里的其他用户广播自定义数据，已达到传输信令的目的。
+ * TRTC 中的 UDP 通道原本设计用来传输音视频数据的，该接口的原理是将您要发送的信令伪装成音视频数据包，与原本要发送的音视频数据一并发送出去。
+ * 房间中的其他用户可以通过 {@link TRTCCloudDelegate} 中的 onRecvCustomCmdMsg 回调接收消息。
+ * @param cmdID 消息 ID，取值范围为1 - 10。
+ * @param data 待发送的消息，单个消息的最大长度被限制为 1KB。
+ * @param reliable 是否可靠发送，可靠发送可以获得更高的发送成功率，但可靠发送比不可靠发送会带来更大的接收延迟。
+ * @param ordered 是否要求有序，即是否要求接收端的数据包顺序和发送端的数据包顺序一致（这会带来一定的接收延时）。
+ * @return true：消息已经发出；false：消息发送失败。
+ * @note
+ * 1. 发送消息到房间内所有用户（暂时不支持 Web/小程序端），每秒最多能发送30条消息。
+ * 2. 每个包最大为 1KB，超过则很有可能会被中间路由器或者服务器丢弃。
+ * 3. 每个客户端每秒最多能发送总计 8KB 数据。
+ * 4. 请将 reliable 和 ordered 同时设置为 true 或同时设置为 flase，暂不支持交叉设置。
+ * 5. 强烈建议您将不同类型的消息设定为不同的 cmdID，这样可以在要求有序的情况下减小消息时延。
*/
virtual bool sendCustomCmdMsg(uint32_t cmdId, const uint8_t* data, uint32_t dataSize, bool reliable, bool ordered) = 0;
/**
- * 10.2 将小数据量的自定义数据嵌入视频帧中
- *
- * 跟 sendCustomCmdMsg 的原理不同，sendSEIMsg 是将数据直接塞入视频数据头中。因此，即使视频帧被旁路到了直播 CDN 上，
- * 这些数据也会一直存在。但是由于要把数据嵌入视频帧中，所以数据本身不能太大，推荐几个字节就好。
- *
- * 最常见的用法是把自定义的时间戳（timstamp）用 sendSEIMsg 嵌入视频帧中，这种方案的最大好处就是可以实现消息和画面的完美对齐。
- *
- * @param data 待发送的数据，最大支持1kb（1000字节）的数据大小
- * @param dataSize 待发送的数据大小
- * @param repeatCount 发送数据次数
- * @return true：消息已通过限制，等待后续视频帧发送；false:消息被限制发送
+ * 11.2 使用 SEI 通道发送自定义消息给房间内所有用户
*
+ * 该接口可以让您借助 TRTC 的 SEI 通道，向当前房间里的其他用户广播自定义数据，已达到传输信令的目的。
+ * 视频帧的头部有一个叫做 SEI 的头部数据块，该接口的原理就是利用这个被称为 SEI 的头部数据块，将您要发送的自定义信令嵌入其中，使其同视频帧一并发送出去。
+ * 因此，与 {@link sendCustomCmdMsg} 相比，SEI 通道传输的信令具有更好的兼容性：信令可以伴随着视频帧一直传输到直播 CDN 上。
+ * 不过，由于视频帧头部的数据块不能太大，建议您使用该接口时，尽量将信令控制在几个字节的大小。
+ * 最常见的用法是把自定义的时间戳（timestamp）用本接口嵌入视频帧中，实现消息和画面的完美对齐（比如：教育场景下的课件和视频信号的对齐）。
+ * 房间中的其他用户可以通过 {@link TRTCCloudDelegate} 中的 onRecvSEIMsg 回调接收消息。
+ * @param data 待发送的数据，最大支持 1KB（1000字节）的数据大小
+ * @param repeatCount 发送数据次数
+ * @return YES：消息已通过限制，等待后续视频帧发送；NO：消息被限制发送
* @note 本接口有以下限制：
- * - 数据在接口调用完后不会被即时发送出去，而是从下一帧视频帧开始带在视频帧中发送。
- * - 发送消息到房间内所有用户，每秒最多能发送30条消息（与 sendCustomCmdMsg 共享限制）。
- * - 每个包最大为1KB，若发送大量数据，会导致视频码率增大，可能导致视频画质下降甚至卡顿（与 sendCustomCmdMsg 共享限制）。
- * - 每个客户端每秒最多能发送总计8KB数据（与 sendCustomCmdMsg 共享限制）。
- * - 若指定多次发送（repeatCount > 1），则数据会被带在后续的连续 repeatCount 个视频帧中发送出去，同样会导致视频码率增大。
- * - 如果 repeatCount > 1，多次发送，接收消息 onRecvSEIMsg 回调也可能会收到多次相同的消息，需要去重。
+ * 1. 数据在接口调用完后不会被即时发送出去，而是从下一帧视频帧开始带在视频帧中发送。
+ * 2. 发送消息到房间内所有用户，每秒最多能发送 30 条消息（与 sendCustomCmdMsg 共享限制）。
+ * 3. 每个包最大为 1KB，若发送大量数据，会导致视频码率增大，可能导致视频画质下降甚至卡顿（与 sendCustomCmdMsg 共享限制）。
+ * 4. 每个客户端每秒最多能发送总计8KB数据（与 sendCustomCmdMsg 共享限制）。
+ * 5. 若指定多次发送（repeatCount > 1），则数据会被带在后续的连续 repeatCount 个视频帧中发送出去，同样会导致视频码率增大。
+ * 6. 如果 repeatCount > 1，多次发送，接收消息 onRecvSEIMsg 回调也可能会收到多次相同的消息，需要去重。
*/
virtual bool sendSEIMsg(const uint8_t* data, uint32_t dataSize, int32_t repeatCount) = 0;
- /// @}
+ /// @}
/////////////////////////////////////////////////////////////////////////////////
//
- // （十一）设备和网络测试
+ // 网络测试接口
//
/////////////////////////////////////////////////////////////////////////////////
- /// @name 设备和网络测试
+ /// @name 网络测试接口
/// @{
+
/**
- * 11.1 开始进行网络测速（视频通话期间请勿测试，以免影响通话质量）
- *
- * 测速结果将会用于优化 SDK 接下来的服务器选择策略，因此推荐您在用户首次通话前先进行一次测速，这将有助于我们选择最佳的服务器。
- * 同时，如果测试结果非常不理想，您可以通过醒目的 UI 提示用户选择更好的网络。
- *
- * @note 测速本身会消耗一定的流量，所以也会产生少量额外的流量费用。
+ * 12.1 开始进行网络测速（进入房间前使用）
*
- * @param sdkAppId 应用标识
- * @param userId 用户标识
- * @param userSig 用户签名
+ * TRTC 由于涉及的是对传输时延要求很苛刻的实时音视频传输服务，因此对网络的稳定性要求会比较高。
+ * 很多用户在网络环境达不到 TRTC 的最低使用门槛时，直接进入房间可能会导致非常不好的用户体验。
+ * 推荐的做法是在用户进入房间前进行网络测速，当用户网络较差时通过 UI 交互提醒用户切换到更加稳定的网络（比如 WiFi 切换到 4G ）后再进入房间。
+ * @note
+ * 1. 测速本身会消耗一定的流量，所以也会产生少量额外的流量费用。
+ * 2. 请在进入房间前进行测速，在房间中测速会影响正常的音视频传输效果，而且由于干扰过多，测速结果也不准确。
+ * @param sdkAppId 应用标识，请参考 {@link TRTCParams} 中的相关说明。
+ * @param userId 用户标识，请参考 {@link TRTCParams} 中的相关说明。
+ * @param userSig 用户签名，请参考 {@link TRTCParams} 中的相关说明。
*/
virtual void startSpeedTest(uint32_t sdkAppId, const char* userId, const char* userSig) = 0;
/**
- * 11.2 停止网络测速
+ * 12.2 停止网络测速
*/
virtual void stopSpeedTest() = 0;
- /// @}
+ /// @}
/////////////////////////////////////////////////////////////////////////////////
//
- // （十二）LOG 相关接口函数
+ // 调试相关接口
//
/////////////////////////////////////////////////////////////////////////////////
- /// @name LOG 相关接口函数
+ /// @name 调试相关接口
/// @{
+
/**
- * 12.1 获取 SDK 版本信息
- *
- * @return UTF-8 编码的版本号。
+ * 13.1 获取 SDK 版本信息
*/
virtual const char* getSDKVersion() = 0;
/**
- * 12.2 设置 Log 输出级别
+ * 13.2 设置 Log 输出级别
*
- * @param level 参见 TRTCLogLevel，默认值：TRTCLogLevelNone
+ * @param level 参见 {@link TRTCLogLevel}，默认值：{@link TRTCLogLevelNone}
*/
virtual void setLogLevel(TRTCLogLevel level) = 0;
/**
- * 12.3 启用或禁用控制台日志打印
+ * 13.3 启用/禁用控制台日志打印
*
- * @param enabled 指定是否启用，默认为禁止状态
+ * @param enabled 指定是否启用，默认:禁止状态
*/
virtual void setConsoleEnabled(bool enabled) = 0;
/**
- * 12.4 启用或禁用 Log 的本地压缩
- *
- * 开启压缩后，Log 存储体积明显减小，但需要腾讯云提供的 Python 脚本解压后才能阅读。
- * 禁用压缩后，Log 采用明文存储，可以直接用记事本打开阅读，但占用空间较大。
+ * 13.4 启用/禁用日志的本地压缩
*
- * @param enabled 指定是否启用，默认为禁止状态
+ * 开启压缩后，Log 存储体积明显减小，但需要腾讯云提供的 Python 脚本解压后才能阅读。
+ * 禁用压缩后，Log 采用明文存储，可以直接用记事本打开阅读，但占用空间较大。
+ * @param enabled 指定是否启用，默认为启动状态
*/
virtual void setLogCompressEnabled(bool enabled) = 0;
/**
- * 12.5 设置日志保存路径
+ * 13.5 设置本地日志的保存路径
+ *
+ * 通过该接口您可以更改 SDK 本地日志的默认存储路径，SDK 默认的本地日志的存储位置：
+ * - Windows 平台：在 C:/Users/[系统用户名]/AppData/Roaming/liteav/log，即 %appdata%/liteav/log 下。
+ * - iOS 或 Mac 平台：在 sandbox Documents/log 下。
+ * - Android 平台：在 /app私有目录/files/log/liteav/ 下。
*
- * @note 日志文件默认保存位置：
- * - Windows 平台：在 C:/Users/[系统用户名]/AppData/Roaming/Tencent/liteav/log，即 %appdata%/Tencent/liteav/log 下
- * - iOS 或 Mac 平台：在 sandbox Documents/log 下
- * - Android 平台：在 /app私有目录/files/log/tencent/liteav/ 下
- * @note 如需修改，必须在所有方法前调用，并且保证目录存在及应用有目录的读写权限。
- * @param path 存储日志的文件夹，请使用 UTF-8 编码
+ * @note 请务必在所有其他接口之前调用，并且保证您指定的目录是存在的，并且您的应用程序拥有对该目录的读写权限。
+ * @param path 存储日志的路径
*/
virtual void setLogDirPath(const char* path) = 0;
/**
- * 12.6 设置日志回调
- *
- * @param callback 日志回调
+ * 13.6 设置日志回调
*/
virtual void setLogCallback(ITRTCLogCallback* callback) = 0;
/**
- * 12.7 显示仪表盘
- *
- * 仪表盘是状态统计和事件消息浮层 view，方便调试。
+ * 13.7 显示仪表盘
*
- * @param showType 0：不显示；1：显示精简版；2：显示全量版，默认为不显示
+ * “仪表盘”是位于视频渲染控件之上的一个半透明的调试信息浮层，用于展示音视频信息和事件信息，便于对接和调试。
+ * @param showType 0：不显示；1：显示精简版（仅显示音视频信息）；2：显示完整版（包含音视频信息和事件信息）。
*/
virtual void showDebugView(int showType) = 0;
/**
- * 12.8 调用实验性 API 接口
- *
- * @note 该接口用于调用一些实验性功能
- * @param jsonStr 接口及参数描述的 JSON 字符串
+ * 13.9 调用实验性接口
*/
- virtual void callExperimentalAPI(const char *jsonStr) = 0;
- /// @}
+ virtual void callExperimentalAPI(const char* jsonStr) = 0;
+
+/// @}
+/////////////////////////////////////////////////////////////////////////////////
+//
+// 弃用接口（建议使用对应的新接口）
+//
+/////////////////////////////////////////////////////////////////////////////////
+/// @name 弃用接口（建议使用对应的新接口）
+/// @{
+
+/**
+ * 启用视频自定义采集模式
+ *
+ * @deprecated v8.5 版本开始不推荐使用，建议使用 enableCustomVideoCapture(streamType,enable) 接口替代之。
+ */
+#ifndef _WIN32
+ virtual void enableCustomVideoCapture(bool enable) = 0;
+#endif
+
+/**
+ * 投送自己采集的视频数据
+ *
+ * @deprecated v8.5 版本开始不推荐使用，建议使用 sendCustomVideoData(streamType, TRTCVideoFrame) 接口替代之。
+ */
+#ifndef _WIN32
+ virtual void sendCustomVideoData(TRTCVideoFrame* frame) = 0;
+#endif
+
+/**
+ * 暂停/恢复发布本地的视频流
+ *
+ * @deprecated v8.9 版本开始不推荐使用，建议使用 muteLocalVideo(streamType, mute) 接口替代之。
+ */
+#ifndef _WIN32
+ virtual void muteLocalVideo(bool mute) = 0;
+#endif
+
+/**
+ * 暂停 / 恢复订阅远端用户的视频流
+ *
+ * @deprecated v8.9 版本开始不推荐使用，建议使用 muteRemoteVideoStream(userId, streamType, mute) 接口替代之。
+ */
+#ifndef _WIN32
+ virtual void muteRemoteVideoStream(const char* userId, bool mute) = 0;
+#endif
- /////////////////////////////////////////////////////////////////////////////////
- //
- // （十三）Windows 专有废弃方法
- //
- /////////////////////////////////////////////////////////////////////////////////
- /// @name Windows 专有废弃方法
- /// @{
#ifdef _WIN32
+ using IDeprecatedTRTCCloud::enableCustomVideoCapture;
+ using IDeprecatedTRTCCloud::muteLocalVideo;
+ using IDeprecatedTRTCCloud::muteRemoteVideoStream;
+ using IDeprecatedTRTCCloud::selectScreenCaptureTarget;
+ using IDeprecatedTRTCCloud::sendCustomVideoData;
using IDeprecatedTRTCCloud::startLocalAudio;
using IDeprecatedTRTCCloud::startRemoteView;
using IDeprecatedTRTCCloud::startScreenCapture;
using IDeprecatedTRTCCloud::stopRemoteView;
- using IDeprecatedTRTCCloud::selectScreenCaptureTarget;
- using IDeprecatedTRTCCloud::enableCustomVideoCapture;
- using IDeprecatedTRTCCloud::sendCustomVideoData;
-#endif // _WIN32
+#endif
/// @}
};
+} // namespace liteav
/// @}
-}
#endif /* __ITRTCCLOUD_H__ */
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/cpp_interface/ITRTCStatistics.h b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/cpp_interface/ITRTCStatistics.h
new file mode 100644
index 0000000..5834638
--- /dev/null
+++ b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/cpp_interface/ITRTCStatistics.h
@@ -0,0 +1,216 @@
+/**
+ * Module: TRTC 音视频统计指标（只读）
+ * Function: TRTC SDK 会以两秒钟一次的频率向您汇报当前实时的音视频指标（帧率、码率、卡顿情况等）
+ */
+/// @defgroup TRTCStatistic_cplusplus TRTCStatisic
+/// Tencent Cloud TRTC ：audio, video and network related statistical indicators
+/// @{
+
+#ifndef __TRTCSTATISTIC_H__
+#define __TRTCSTATISTIC_H__
+namespace liteav {
+
+/////////////////////////////////////////////////////////////////////////////////
+//
+// 本地的音视频统计指标
+//
+/////////////////////////////////////////////////////////////////////////////////
+/// @name 本地的音视频统计指标
+/// @{
+
+struct TRTCLocalStatistics {
+ ///【字段含义】本地视频的宽度，单位 px
+ uint32_t width;
+
+ ///【字段含义】本地视频的高度，单位 px
+ uint32_t height;
+
+ ///【字段含义】本地视频的帧率，即每秒钟会有多少视频帧，单位：FPS
+ uint32_t frameRate;
+
+ ///【字段含义】远端视频的码率，即每秒钟新产生视频数据的多少，单位 Kbps
+ uint32_t videoBitrate;
+
+ ///【字段含义】远端音频的采样率，单位 Hz
+ uint32_t audioSampleRate;
+
+ ///【字段含义】本地音频的码率，即每秒钟新产生音频数据的多少，单位 Kbps
+ uint32_t audioBitrate;
+
+ ///【字段含义】视频流类型（高清大画面|低清小画面|辅流画面）
+ TRTCVideoStreamType streamType;
+
+ ///【字段含义】音频设备采集状态（用于检测音频外设的健康度）
+ /// 0：采集设备状态正常；1：检测到长时间静音；2：检测到破音；3：检测到声音异常间断。
+ uint32_t audioCaptureState;
+
+ TRTCLocalStatistics() : width(0), height(0), frameRate(0), videoBitrate(0), audioSampleRate(0), audioBitrate(0), streamType(TRTCVideoStreamTypeBig), audioCaptureState(0) {
+ }
+};
+
+/// @}
+/////////////////////////////////////////////////////////////////////////////////
+//
+// 远端的音视频统计指标
+//
+/////////////////////////////////////////////////////////////////////////////////
+/// @name 远端的音视频统计指标
+/// @{
+
+struct TRTCRemoteStatistics {
+ ///【字段含义】用户 ID
+ const char* userId;
+
+ ///【字段含义】音频流的总丢包率（％）
+ /// audioPacketLoss 代表音频流历经“主播 => 云端 => 观众”这样一条完整的传输链路后，最终在观众端统计到的丢包率。
+ /// audioPacketLoss 越小越好，丢包率为0即表示该路音频流的所有数据均已经完整地到达了观众端。
+ ///如果出现了 downLoss == 0 但 audioPacketLoss != 0 的情况，说明该路音频流在“云端=>观众”这一段链路上没有出现丢包，但是在“主播=>云端”这一段链路上出现了不可恢复的丢包。
+ uint32_t audioPacketLoss;
+
+ ///【字段含义】该路视频流的总丢包率（％）
+ /// videoPacketLoss 代表该路视频流历经“主播 => 云端 => 观众”这样一条完整的传输链路后，最终在观众端统计到的丢包率。
+ /// videoPacketLoss 越小越好，丢包率为0即表示该路视频流的所有数据均已经完整地到达了观众端。
+ ///如果出现了 downLoss == 0 但 videoPacketLoss != 0 的情况，说明该路视频流在“云端=>观众”这一段链路上没有出现丢包，但是在“主播=>云端”这一段链路上出现了不可恢复的丢包。
+ uint32_t videoPacketLoss;
+
+ ///【字段含义】远端视频的宽度，单位 px
+ uint32_t width;
+
+ ///【字段含义】远端视频的高度，单位 px
+ uint32_t height;
+
+ ///【字段含义】远端视频的帧率，单位：FPS
+ uint32_t frameRate;
+
+ ///【字段含义】远端视频的码率，单位 Kbps
+ uint32_t videoBitrate;
+
+ ///【字段含义】本地音频的采样率，单位 Hz
+ uint32_t audioSampleRate;
+
+ ///【字段含义】本地音频的码率，单位 Kbps
+ uint32_t audioBitrate;
+
+ ///【字段含义】播放延迟，单位 ms
+ ///为了避免网络抖动和网络包乱序导致的声音和画面卡顿，TRTC 会在播放端管理一个播放缓冲区，用于对接收到的网络数据包进行整理，
+ ///该缓冲区的大小会根据当前的网络质量进行自适应调整，该缓冲区的大小折算成以毫秒为单位的时间长度，也就是 jitterBufferDelay。
+ uint32_t jitterBufferDelay;
+
+ ///【字段含义】端到端延迟，单位 ms
+ /// point2PointDelay 代表 “主播=>云端=>观众” 的延迟，更准确地说，它代表了“采集=>编码=>网络传输=>接收=>缓冲=>解码=>播放” 全链路的延迟。
+ /// point2PointDelay 需要本地和远端的 SDK 均为 8.5 及以上的版本才生效，若远端用户为 8.5 以前的版本，此数值会一直为0，代表无意义。
+ uint32_t point2PointDelay;
+
+ ///【字段含义】音频播放的累计卡顿时长，单位 ms
+ uint32_t audioTotalBlockTime;
+
+ ///【字段含义】音频播放卡顿率，单位 (%)
+ ///音频播放卡顿率（audioBlockRate） = 音频播放的累计卡顿时长（audioTotalBlockTime） / 音频播放的总时长
+ uint32_t audioBlockRate;
+
+ ///【字段含义】视频播放的累计卡顿时长，单位 ms
+ uint32_t videoTotalBlockTime;
+
+ ///【字段含义】视频播放卡顿率，单位 (%)
+ ///视频播放卡顿率（videoBlockRate） = 视频播放的累计卡顿时长（videoTotalBlockTime） / 视频播放的总时长
+ uint32_t videoBlockRate;
+
+ ///【字段含义】该路音视频流的总丢包率（％）
+ ///已废弃，不推荐使用；建议使用 audioPacketLoss、videoPacketLoss 替代
+ uint32_t finalLoss;
+
+ ///【字段含义】视频流类型（高清大画面|低清小画面|辅流画面）
+ TRTCVideoStreamType streamType;
+
+ TRTCRemoteStatistics()
+ : userId(nullptr),
+ audioPacketLoss(0),
+ videoPacketLoss(0),
+ width(0),
+ height(0),
+ frameRate(0),
+ videoBitrate(0),
+ audioSampleRate(0),
+ audioBitrate(0),
+ jitterBufferDelay(0),
+ point2PointDelay(0),
+ audioTotalBlockTime(0),
+ audioBlockRate(0),
+ videoTotalBlockTime(0),
+ videoBlockRate(0),
+ finalLoss(0),
+ streamType(TRTCVideoStreamTypeBig) {
+ }
+};
+
+/// @}
+/////////////////////////////////////////////////////////////////////////////////
+//
+// 网络和性能的汇总统计指标
+//
+/////////////////////////////////////////////////////////////////////////////////
+/// @name 网络和性能的汇总统计指标
+/// @{
+
+struct TRTCStatistics {
+ ///【字段含义】当前应用的 CPU 使用率，单位 (%)
+ uint32_t appCpu;
+
+ ///【字段含义】当前系统的 CPU 使用率，单位 (%)
+ uint32_t systemCpu;
+
+ ///【字段含义】从 SDK 到云端的上行丢包率，单位 (%)
+ ///该数值越小越好，如果 upLoss 为 0%，则意味着上行链路的网络质量很好，上传到云端的数据包基本不发生丢失。
+ ///如果 upLoss 为 30%，则意味着 SDK 向云端发送的音视频数据包中，会有 30% 丢失在传输链路中。
+ uint32_t upLoss;
+
+ ///【字段含义】从云端到 SDK 的下行丢包率，单位 (%)
+ ///该数值越小越好，如果 downLoss 为 0%，则意味着下行链路的网络质量很好，从云端接收的数据包基本不发生丢失。
+ ///如果 downLoss 为 30%，则意味着云端向 SDK 传输的音视频数据包中，会有 30% 丢失在传输链路中。
+ uint32_t downLoss;
+
+ ///【字段含义】从 SDK 到云端的往返延时，单位 ms
+ ///该数值代表从 SDK 发送一个网络包到云端，再从云端回送一个网络包到 SDK 的总计耗时，也就是一个网络包经历 “SDK=>云端=>SDK” 的总耗时。
+ ///该数值越小越好：如果 rtt < 50ms，意味着较低的音视频通话延迟；如果 rtt > 200ms，则意味着较高的音视频通话延迟。
+ ///需要特别解释的是，rtt 代表 “SDK=>云端=>SDK” 的总耗时，所不需要区分 upRtt 和 downRtt。
+ uint32_t rtt;
+
+ ///【字段含义】从 SDK 到本地路由器的往返时延，单位 ms
+ ///该数值代表从 SDK 发送一个网络包到本地路由器网关，再从网关回送一个网络包到 SDK 的总计耗时，也就是一个网络包经历 “SDK=>网关=>SDK” 的总耗时。
+ ///该数值越小越好：如果 gatewayRtt < 50ms，意味着较低的音视频通话延迟；如果 gatewayRtt > 200ms，则意味着较高的音视频通话延迟。
+ ///当网络类型为蜂窝网时，该值无效。
+ uint32_t gatewayRtt;
+
+ ///【字段含义】总发送字节数（包含信令数据和音视频数据），单位：字节数（Bytes）
+ uint32_t sentBytes;
+
+ ///【字段含义】总接收字节数（包含信令数据和音视频数据），单位：字节数（Bytes）
+ uint32_t receivedBytes;
+
+ ///【字段含义】本地的音视频统计信息
+ ///由于本地可能有三路音视频流（即高清大画面，低清小画面，以及辅流画面），因此本地的音视频统计信息是一个数组。
+ TRTCLocalStatistics* localStatisticsArray;
+
+ ///【字段含义】数组 localStatisticsArray 的大小
+ uint32_t localStatisticsArraySize;
+
+ ///【字段含义】远端的音视频统计信息
+ ///因为同时可能有多个远端用户，而且每个远端用户同时可能有多路音视频流（即高清大画面，低清小画面，以及辅流画面），因此远端的音视频统计信息是一个数组。
+ TRTCRemoteStatistics* remoteStatisticsArray;
+
+ ///【字段含义】数组 remoteStatisticsArray 的大小
+ uint32_t remoteStatisticsArraySize;
+
+ TRTCStatistics() : upLoss(0), downLoss(0), appCpu(0), systemCpu(0), rtt(0), gatewayRtt(0), receivedBytes(0), sentBytes(0), localStatisticsArray(nullptr), localStatisticsArraySize(0), remoteStatisticsArray(nullptr), remoteStatisticsArraySize(0) {
+ }
+};
+/// @}
+
+} // namespace liteav
+
+#ifdef _WIN32
+using namespace liteav;
+#endif
+
+#endif / *__TRTCSTATISTIC_H__* /
+/// @}
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/cpp_interface/ITXAudioEffectManager.h b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/cpp_interface/ITXAudioEffectManager.h
old mode 100755
new mode 100644
index 082860d..68e9ae6
--- a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/cpp_interface/ITXAudioEffectManager.h
+++ b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/cpp_interface/ITXAudioEffectManager.h
@@ -1,62 +1,114 @@
+/**
+ * Module: TRTC 背景音乐、短音效和人声特效的管理类
+ * Function: 用于对背景音乐、短音效和人声特效进行设置的管理类
+ */
+/// @defgroup TXAudioEffectManager_cplusplus TXAudioEffectManager
+/// Tencent Cloud Audio Effect Management Module
+/// @{
+
#ifndef __ITXAUDIOEFFECTMANAGER_H__
#define __ITXAUDIOEFFECTMANAGER_H__
-namespace trtc {
+namespace liteav {
+
+class ITXMusicPlayObserver;
+class AudioMusicParam;
-/// @defgroup ITXAudioEffectManager_cplusplus ITXAudioEffectManager
-/// 腾讯云视频通话功能音乐和人声设置接口
+/////////////////////////////////////////////////////////////////////////////////
+//
+// 音效相关的枚举值定义
+//
+/////////////////////////////////////////////////////////////////////////////////
+/// @name 音效相关的枚举值定义
/// @{
-enum TXVoiceReverbType
-{
- TXLiveVoiceReverbType_0 = 0, ///< 关闭混响
- TXLiveVoiceReverbType_1 = 1, ///< KTV
- TXLiveVoiceReverbType_2 = 2, ///< 小房间
- TXLiveVoiceReverbType_3 = 3, ///< 大会堂
- TXLiveVoiceReverbType_4 = 4, ///< 低沉
- TXLiveVoiceReverbType_5 = 5, ///< 洪亮
- TXLiveVoiceReverbType_6 = 6, ///< 金属声
- TXLiveVoiceReverbType_7 = 7, ///< 磁性
+
+/**
+ * 1.1 混响特效
+ *
+ * 混响特效可以作用于人声之上，通过声学算法对声音进行叠加处理，模拟出各种不同环境下的临场感受，目前支持如下几种混响效果：
+ * 0：关闭；1：KTV；2：小房间；3：大会堂；4：低沉；5：洪亮；6：金属声；7：磁性；8：空灵；9：录音棚；10：悠扬。
+ */
+enum TXVoiceReverbType {
+ TXLiveVoiceReverbType_0 = 0, ///< disable
+ TXLiveVoiceReverbType_1 = 1, ///< KTV
+ TXLiveVoiceReverbType_2 = 2, ///< small room
+ TXLiveVoiceReverbType_3 = 3, ///< great hall
+ TXLiveVoiceReverbType_4 = 4, ///< deep voice
+ TXLiveVoiceReverbType_5 = 5, ///< loud voice
+ TXLiveVoiceReverbType_6 = 6, ///< metallic sound
+ TXLiveVoiceReverbType_7 = 7, ///< magnetic sound
+ TXLiveVoiceReverbType_8 = 8, ///< ethereal
+ TXLiveVoiceReverbType_9 = 9, ///< studio
+ TXLiveVoiceReverbType_10 = 10, ///< melodious
};
+/// @}
+/////////////////////////////////////////////////////////////////////////////////
+//
+// 背景音乐的播放事件回调
+//
+/////////////////////////////////////////////////////////////////////////////////
+/// @name 背景音乐的事件回调接口
+/// @{
+
+// Playback progress block of background music
class ITXMusicPlayObserver {
-public:
- virtual ~ITXMusicPlayObserver() {}
+ public:
+ virtual ~ITXMusicPlayObserver() {
+ }
- /// 背景音乐开始播放
- virtual void onStart(int id,int errCode) = 0;
+ ///背景音乐开始播放
+ virtual void onStart(int id, int errCode) = 0;
- /// 背景音乐的播放进度
- virtual void onPlayProgress(int id,long curPtsMS,long durationMS) = 0;
+ ///背景音乐的播放进度
+ virtual void onPlayProgress(int id, long curPtsMS, long durationMS) = 0;
- /// 背景音乐已播放完毕
- virtual void onComplete(int id,int errCode) = 0;
+ ///背景音乐已经播放完毕
+ virtual void onComplete(int id, int errCode) = 0;
};
+/// @}
+/////////////////////////////////////////////////////////////////////////////////
+//
+// 背景音乐的播放控制信息
+//
+/////////////////////////////////////////////////////////////////////////////////
+/// @name 背景音乐的播放控制信息
+/// @{
+
+/**
+ * 背景音乐的播放控制信息
+ *
+ * 该信息用于在接口 {@link startPlayMusic} 中指定背景音乐的相关信息，包括播放 ID、文件路径和循环次数等：
+ * 1. 如果要多次播放同一首背景音乐，请不要每次播放都分配一个新的 ID，我们推荐使用相同的 ID。
+ * 2. 若您希望同时播放多首不同的音乐，请为不同的音乐分配不同的 ID 进行播放。
+ * 3. 如果使用同一个 ID 播放不同音乐，SDK 会先停止播放旧的音乐，再播放新的音乐。
+ */
class AudioMusicParam {
-public:
- /// 【字段含义】音乐 ID
- /// 【特殊说明】SDK 允许播放多路音乐，因此需要音乐 ID 进行标记，用于控制音乐的开始、停止、音量等
+ public:
+ ///【字段含义】音乐 ID <br/>
+ ///【特殊说明】SDK 允许播放多路音乐，因此需要使用 ID 进行标记，用于控制音乐的开始、停止、音量等。
int id;
- /// 【字段含义】音乐文件的绝对路径
+ ///【字段含义】音效文件的完整路径或 URL 地址。支持的音频格式包括 MP3、AAC、M4A、WAV
char* path;
- /// 【字段含义】音乐循环播放的次数
- /// 【推荐取值】取值范围为0 - 任意正整数，默认值：0。0表示播放音乐一次；1表示播放音乐两次；以此类推
+ ///【字段含义】音乐循环播放的次数 <br/>
+ ///【推荐取值】取值范围为0 - 任意正整数，默认值：0。0表示播放音乐一次；1表示播放音乐两次；以此类推
int loopCount;
- /// 【字段含义】是否将音乐传到远端
- /// 【推荐取值】YES：音乐在本地播放的同时，会上行至云端，因此远端用户也能听到该音乐；NO：音乐不会上行至云端，因此只能在本地听到该音乐。默认值：NO
+ ///【字段含义】是否将音乐传到远端 <br/>
+ ///【推荐取值】YES：音乐在本地播放的同时，远端用户也能听到该音乐；NO：主播只能在本地听到该音乐，远端观众听不到。默认值：NO。
bool publish;
- /// 【字段含义】播放的是否为短音乐文件
- /// 【推荐取值】YES：需要重复播放的短音乐文件；NO：正常的音乐文件。默认值：NO
+ ///【字段含义】播放的是否为短音乐文件 <br/>
+ ///【推荐取值】YES：需要重复播放的短音乐文件；NO：正常的音乐文件。默认值：NO
bool isShortFile;
- /// 【字段含义】音乐开始播放时间点，单位毫秒
+ ///【字段含义】音乐开始播放时间点，单位：毫秒。
long startTimeMS;
- /// 【字段含义】音乐结束播放时间点，单位毫秒，0表示播放至文件结尾。
+ ///【字段含义】音乐结束播放时间点，单位毫秒，0表示播放至文件结尾。
long endTimeMS;
AudioMusicParam(int id_, char* path_) {
@@ -69,50 +121,57 @@ public:
endTimeMS = 0;
}
};
+/// @}
+// Definition of audio effect management module
+class ITXAudioEffectManager {
+ protected:
+ ITXAudioEffectManager() {
+ }
+ virtual ~ITXAudioEffectManager() {
+ }
-class ITXAudioEffectManager
-{
-protected:
- ITXAudioEffectManager() {}
- virtual ~ITXAudioEffectManager() {}
-
-public:
-/////////////////////////////////////////////////////////////////////////////////
-//
-// （一）人声相关特效函数
-//
-/////////////////////////////////////////////////////////////////////////////////
-/// @name 人声相关特效函数
-/// @{
+ public:
+ /////////////////////////////////////////////////////////////////////////////////
+ //
+ // 人声相关的特效接口
+ //
+ /////////////////////////////////////////////////////////////////////////////////
+ /// @name 人声相关的特效接口
+ /// @{
/**
- * 1.1 设置人声的混响效果（KTV、小房间、大会堂、低沉、洪亮...）
+ * 1.3 设置人声的混响效果
*
- * @note 设置的效果在退房后会失效，如果下次进房还需要对应特效，需要调用此接口再次设置。
+ * 通过该接口您可以设置人声的混响效果，具体特效请参考枚举定义{@link TXVoiceReverbType}。
+ *
+ * @note 设置的效果在退出房间后会自动失效，如果下次进房还需要对应特效，需要调用此接口再次进行设置。
*/
virtual void setVoiceReverbType(TXVoiceReverbType type) = 0;
/**
- * 1.2 设置麦克风采集人声的音量
+ * 1.5 设置语音音量
*
- * @param volume 音量大小，100为原始音量，取值范围为0 - 150；默认值：100
+ * 该接口可以设置语音音量的大小，一般配合音乐音量的设置接口 {@link setAllMusicVolume} 协同使用，用于调谐语音和音乐在混音前各自的音量占比。
*
- * @note 如果要将 volume 设置为大于100的数值，需要进行特殊配置，请联系技术支持。
+ * @param volume 音量大小，取值范围为0 - 100，默认值：100。
+ * @note 如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。
*/
virtual void setVoiceCaptureVolume(int volume) = 0;
-/// @}
-/////////////////////////////////////////////////////////////////////////////////
-//
-// （二）背景音乐特效函数
-//
-/////////////////////////////////////////////////////////////////////////////////
+ /// @}
+ /////////////////////////////////////////////////////////////////////////////////
+ //
+ // 背景音乐的相关接口
+ //
+ /////////////////////////////////////////////////////////////////////////////////
+ /// @name 背景音乐的相关接口
+ /// @{
-/// @name 背景音乐特效函数
-/// @{
/**
- * 2.1 设置背景音乐的播放进度回调接口
+ * 2.0 设置背景音乐的事件回调接口
+ *
+ * 请在播放背景音乐之前使用该接口设置播放事件回调，以便感知背景音乐的播放进度。
*
* @param musicId 音乐 ID
* @param observer 具体参考 ITXMusicPlayObserver 中定义接口
@@ -120,115 +179,132 @@ public:
virtual void setMusicObserver(int musicId, ITXMusicPlayObserver* observer) = 0;
/**
- * 2.2 开始播放背景音乐
+ * 2.1 开始播放背景音乐
*
* 每个音乐都需要您指定具体的 ID，您可以通过该 ID 对音乐的开始、停止、音量等进行设置。
*
- * @note 若您想同时播放多个音乐，请分配不同的 ID 进行播放。
- * 如果使用同一个 ID 播放不同音乐，SDK 会先停止播放旧的音乐，再播放新的音乐。
+ * @note
+ * 1. 如果要多次播放同一首背景音乐，请不要每次播放都分配一个新的 ID，我们推荐使用相同的 ID。
+ * 2. 若您希望同时播放多首不同的音乐，请为不同的音乐分配不同的 ID 进行播放。
+ * 3. 如果使用同一个 ID 播放不同音乐，SDK 会先停止播放旧的音乐，再播放新的音乐。
+ *
* @param musicParam 音乐参数
+ * @param startBlock 播放开始回调
+ * @param progressBlock 播放进度回调
+ * @param completeBlock 播放结束回调
*/
virtual void startPlayMusic(AudioMusicParam musicParam) = 0;
/**
- * 2.3 停止播放背景音乐
+ * 2.2 停止播放背景音乐
*
* @param id 音乐 ID
*/
virtual void stopPlayMusic(int id) = 0;
/**
- * 2.4 暂停播放背景音乐
+ * 2.3 暂停播放背景音乐
*
* @param id 音乐 ID
*/
virtual void pausePlayMusic(int id) = 0;
/**
- * 2.5 恢复播放背景音乐
+ * 2.4 恢复播放背景音乐
*
* @param id 音乐 ID
*/
virtual void resumePlayMusic(int id) = 0;
/**
- * 2.6 设置背景音乐的远端音量大小，即主播可以通过此接口设置远端观众能听到的背景音乐的音量大小。
+ * 2.5 设置所有背景音乐的本地音量和远端音量的大小
*
- * @param id 音乐 ID
- * @param volume 音量大小，100为原始音量，取值范围为0 - 150；默认值：100
+ * 该接口可以设置所有背景音乐的本地音量和远端音量。
+ * - 本地音量：即主播本地可以听到的背景音乐的音量大小。
+ * - 远端音量：即观众端可以听到的背景音乐的音量大小。
*
- * @note 如果要将 volume 设置为大于100的数值，需要进行特殊配置，请联系技术支持。
+ * @param volume 音量大小，取值范围为0 - 100，默认值：100。
+ * @note 如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。
*/
- virtual void setMusicPublishVolume(int id, int volume) = 0;
+ virtual void setAllMusicVolume(int volume) = 0;
/**
- * 2.7 设置背景音乐的本地音量大小，即主播可以通过此接口设置主播自己本地的背景音乐的音量大小。
+ * 2.6 设置某一首背景音乐的远端音量的大小
*
- * @param id 音乐 ID
- * @param volume 音量大小，100为原始音量，取值范围为0 - 150；默认值：100
+ * 该接口可以细粒度地控制每一首背景音乐的远端音量，也就是观众端可听到的背景音乐的音量大小。
*
- * @note 如果要将 volume 设置为大于100的数值，需要进行特殊配置，请联系技术支持。
+ * @param id 音乐 ID
+ * @param volume 音量大小，取值范围为0 - 100；默认值：100
+ * @note 如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。
*/
- virtual void setMusicPlayoutVolume(int id, int volume) = 0;
+ virtual void setMusicPublishVolume(int id, int volume) = 0;
/**
- * 2.8 设置全局背景音乐的本地和远端音量的大小
+ * 2.7 设置某一首背景音乐的本地音量的大小
*
- * @param volume 音量大小，100为原始音量，取值范围为0 - 150；默认值：100
+ * 该接口可以细粒度地控制每一首背景音乐的本地音量，也就是主播本地可以听到的背景音乐的音量大小。
*
- * @note 如果要将 volume 设置为大于100的数值，需要进行特殊配置，请联系技术支持。
+ * @param id 音乐 ID
+ * @param volume 音量大小，取值范围为0 - 100，默认值：100。
+ * @note 如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。
*/
- virtual void setAllMusicVolume(int volume) = 0;
+ virtual void setMusicPlayoutVolume(int id, int volume) = 0;
/**
- * 2.9 调整背景音乐的音调高低
+ * 2.8 调整背景音乐的音调高低
*
- * @param id 音乐 ID
+ * @param id 音乐 ID
* @param pitch 音调，默认值是0.0f，范围是：[-1 ~ 1] 之间的浮点数；
*/
virtual void setMusicPitch(int id, float pitch) = 0;
/**
- * 2.10 调整背景音乐的变速效果
+ * 2.9 调整背景音乐的变速效果
*
- * @param id 音乐 ID
+ * @param id 音乐 ID
* @param speedRate 速度，默认值是1.0f，范围是：[0.5 ~ 2] 之间的浮点数；
*/
virtual void setMusicSpeedRate(int id, float speedRate) = 0;
/**
- * 2.11 获取背景音乐当前的播放进度（单位：毫秒）
+ * 2.10 获取背景音乐的播放进度（单位：毫秒）
*
- * @param id 音乐 ID
+ * @param id 音乐 ID
* @return 成功返回当前播放时间，单位：毫秒，失败返回-1
*/
virtual long getMusicCurrentPosInMS(int id) = 0;
/**
- * 2.12 设置背景音乐的播放进度（单位：毫秒）
- *
- * @note 请尽量避免频繁地调用该接口，因为该接口可能会再次读写音乐文件，耗时稍高。
- * 当配合进度条使用时，请在进度条拖动完毕的回调中调用，而避免在拖动过程中实时调用。
+ * 2.11 获取景音乐的总时长（单位：毫秒）
*
- * @param id 音乐 ID
- * @param pts 单位: 毫秒
+ * @param path 音乐文件路径，如果 path 为空，那么返回当前正在播放的 music 时长。
+ * @return 成功返回时长，失败返回-1
*/
- virtual void seekMusicToPosInTime(int id, int pts) = 0;
+ virtual long getMusicDurationInMS(char* path) = 0;
/**
- * 2.13 获取景音乐文件的总时长（单位：毫秒）
+ * 2.12 设置背景音乐的播放进度（单位：毫秒）
*
- * @param path 音乐文件路径，如果 path 为空，那么返回当前正在播放的 music 时长。
- * @return 成功返回时长，失败返回-1
+ * @note 请尽量避免过度频繁地调用该接口，因为该接口可能会再次读写音乐文件，耗时稍高。
+ * 因此，当用户拖拽音乐的播放进度条时，请在用户完成拖拽操作后再调用本接口。
+ * 因为 UI 上的进度条控件往往会以很高的频率反馈用户的拖拽进度，如不做频率限制，会导致较差的用户体验。
+ *
+ * @param id 音乐 ID
+ * @param pts 单位: 毫秒
*/
- virtual long getMusicDurationInMS(char* path) = 0;
+ virtual void seekMusicToPosInTime(int id, int pts) = 0;
+ /// @}
};
-/// @}
-}
+} // End of namespace liteav
+
+// 9.0 开始 C++ 接口将声明在 liteav 命名空间下，为兼容之前的使用方式，将 trtc 作为 liteav 的别名
+namespace trtc = liteav;
#ifdef _WIN32
-using namespace trtc;
+using namespace liteav;
#endif
#endif /* __ITXAUDIOEFFECTMANAGER_H__ */
+
+/// @}
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/cpp_interface/ITXDeviceManager.h b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/cpp_interface/ITXDeviceManager.h
index d00b0f3..1ccca88 100644
--- a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/cpp_interface/ITXDeviceManager.h
+++ b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/cpp_interface/ITXDeviceManager.h
@@ -1,3 +1,11 @@
+/**
+ * Module: TRTC 音视频设备管理模块
+ * Function: 用于管理摄像头、麦克风和扬声器等音视频相关的硬件设备
+ */
+/// @defgroup TXDeviceManager_cplusplus TXDeviceManager
+/// Tencent Cloud Device Management Module
+/// @{
+
#ifndef __ITXDEVICEMANAGER_H__
#define __ITXDEVICEMANAGER_H__
@@ -6,73 +14,144 @@
#include <TargetConditionals.h>
#endif
-namespace trtc {
+namespace liteav {
class ITRTCVideoRenderCallback;
-/// @defgroup ITXDeviceManager_cplusplus ITXDeviceManager
-/// 腾讯云视频通话功能的设备管理接口类
+/////////////////////////////////////////////////////////////////////////////////
+//
+// 音视频设备相关的类型定义
+//
+/////////////////////////////////////////////////////////////////////////////////
+/// @name 音视频设备相关的类型定义
/// @{
+
/**
- * 系统音量类型（仅适用于移动端设备）
- *
- * 智能手机一般具备两种系统音量类型，即通话音量类型和媒体音量类型。
- * - 通话音量：手机专门为通话场景设计的音量类型，使用手机自带的回声抵消功能，音质相比媒体音量类型较差，
- * 无法通过音量按键将音量调成零，但是支持蓝牙耳机上的麦克风。
+ * 系统音量类型（仅适用于移动设备）
*
- * - 媒体音量：手机专门为音乐场景设计的音量类型，音质相比于通话音量类型要好，通过通过音量按键可以将音量调成零。
- * 使用媒体音量类型时，如果要开启回声抵消（AEC）功能，SDK 会开启内置的声学处理算法对声音进行二次处理。
- * 在媒体音量模式下，蓝牙耳机无法使用自带的麦克风采集声音，只能使用手机上的麦克风进行声音采集。
+ * 现代智能手机中一般都具备两套系统音量类型，即“通话音量”和“媒体音量”。
+ * - 通话音量：手机专门为接打电话所设计的音量类型，自带回声抵消（AEC）功能，并且支持通过蓝牙耳机上的麦克风进行拾音，缺点是音质比较一般。
+ * 当您通过手机侧面的音量按键下调手机音量时，如果无法将其调至零（也就是无法彻底静音），说明您的手机当前出于通话音量。
+ * - 媒体音量：手机专门为音乐场景所设计的音量类型，无法使用系统的 AEC 功能，并且不支持通过蓝牙耳机的麦克风进行拾音，但具备更好的音乐播放效果。
+ * 当您通过手机侧面的音量按键下调手机音量时，如果能够将手机音量调至彻底静音，说明您的手机当前出于媒体音量。
*
- * SDK 目前提供了三种系统音量类型的控制模式，分别为：
- * - Auto：“麦上通话，麦下媒体”，即主播上麦时使用通话音量，观众不上麦则使用媒体音量，适合在线直播场景。
- * 如果您在 enterRoom 时选择的场景为 TRTCAppSceneLIVE 或 TRTCAppSceneVoiceChatRoom，SDK 会自动选择该模式。
+ * SDK 目前提供了三种系统音量类型的控制模式：自动切换模式、全程通话音量模式、全程媒体音量模式。
+ */
+enum TXSystemVolumeType {
+
+ ///自动切换模式：
+ ///也被称为“麦上通话，麦下媒体”，即主播上麦时使用通话音量，观众不上麦则使用媒体音量，适合在线直播场景。
+ TXSystemVolumeTypeAuto = 0,
+
+ ///全程媒体音量：
+ ///通话全程使用媒体音量，并不是非常常用的音量类型，适用于对音质要求比较苛刻的音乐场景中。
+ ///如果您的用户大都使用外接设备（比如外接声卡）为主，可以使用该模式，否则请慎用。
+ TXSystemVolumeTypeMedia = 1,
+
+ ///全程通话音量：
+ ///该方案的优势在于用户在上下麦时音频模块无需切换工作模式，可以做到无缝上下麦，适合于用户需要频繁上下麦的应用场景。
+ TXSystemVolumeTypeVOIP = 2,
+
+};
+
+/**
+ * 音频路由（即声音的播放模式）
*
- * - VOIP：全程使用通话音量，适合多人会议场景。
- * 如果您在 enterRoom 时选择的场景为 TRTCAppSceneVideoCall 或 TRTCAppSceneAudioCall，SDK 会自动选择该模式。
+ * 音频路由，即声音是从手机的扬声器还是从听筒中播放出来，因此该接口仅适用于手机等移动端设备。
+ * 手机有两个扬声器：一个是位于手机顶部的听筒，一个是位于手机底部的立体声扬声器。
+ * - 设置音频路由为听筒时，声音比较小，只有将耳朵凑近才能听清楚，隐私性较好，适合用于接听电话。
+ * - 设置音频路由为扬声器时，声音比较大，不用将手机贴脸也能听清，因此可以实现“免提”的功能。
+ */
+enum TXAudioRoute {
+
+ /// Speakerphone：使用扬声器播放（即“免提”），扬声器位于手机底部，声音偏大，适合外放音乐。
+ TXAudioRouteSpeakerphone = 0,
+
+ /// Earpiece：使用听筒播放，听筒位于手机顶部，声音偏小，适合需要保护隐私的通话场景。
+ TXAudioRouteEarpiece = 1,
+
+};
+
+/**
+ * 设备类型（仅适用于桌面平台）
*
- * - Media：通话全程使用媒体音量，不常用，适合个别有特殊需求（如主播外接声卡）的应用场景。
+ * 该枚举值用于定义三种类型的音视频设备，即摄像头、麦克风和扬声器，以便让一套设备管理接口可以操控三种不同类型的设备。
+ */
+enum TXMediaDeviceType {
+ TXMediaDeviceTypeUnknown = -1, ///< undefined device type
+ TXMediaDeviceTypeMic = 0, ///< microphone
+ TXMediaDeviceTypeSpeaker = 1, ///< speaker or earpiece
+ TXMediaDeviceTypeCamera = 2, ///< camera
+};
+
+/**
+ * 摄像头采集偏好
*
+ * 该枚举类型用于摄像头采集参数设置。
*/
-enum TXSystemVolumeType
-{
- /// “麦上通话，麦下媒体”，即主播上麦时使用通话音量，观众不上麦则使用媒体音量，适合在线直播场景。<br>
- /// 如果您在 enterRoom 时选择的场景为 TRTCAppSceneLIVE 或 TRTCAppSceneVoiceChatRoom，SDK 会自动选择该模式。
- TXSystemVolumeTypeAuto = 0,
-
- /// 通话全程使用媒体音量，不常用，适合个别有特殊需求（如主播外接声卡）的应用场景。
- TXSystemVolumeTypeMedia = 1,
-
- /// 全程使用通话音量，适合多人会议场景。<br>
- /// 如果您在 enterRoom 时选择的场景为 TRTCAppSceneVideoCall 或 TRTCAppSceneAudioCall 会自动选择该模式。
- TXSystemVolumeTypeVOIP = 2,
+#ifdef _WIN32
+enum TXCameraCaptureMode {
+
+ ///自动调整采集参数。
+ /// SDK 根据实际的采集设备性能及网络情况，选择合适的摄像头输出参数，在设备性能及视频预览质量之间，维持平衡。
+ TXCameraResolutionStrategyAuto = 0,
+
+ ///优先保证设备性能。
+ /// SDK 根据用户设置编码器的分辨率和帧率，选择最接近的摄像头输出参数，从而保证设备性能。
+ TXCameraResolutionStrategyPerformance = 1,
+
+ ///优先保证视频预览质量。
+ /// SDK选择较高的摄像头输出参数，从而提高预览视频的质量。在这种情况下，会消耗更多的 CPU 及内存做视频前处理。
+ TXCameraResolutionStrategyHighQuality = 2,
+
+ ///允许用户设置本地摄像头采集的视频宽高。
+ TXCameraCaptureManual = 3,
+
};
/**
- * 声音播放路由（仅适用于移动端设备）
+ * 摄像头采集参数
*
- * 一般手机都有两个扬声器，设置音频路由的作用就是要决定声音从哪个扬声器播放出来：
- * - Speakerphone：扬声器，位于手机底部，声音偏大，适合外放音乐。
- * - Earpiece：听筒，位于手机顶部，声音偏小，适合通话。
+ * 该设置能决定本地预览图像画质。
*/
-enum TXAudioRoute {
- TXAudioRouteSpeakerphone = 0, ///< 扬声器
- TXAudioRouteEarpiece = 1, ///< 听筒
+struct TXCameraCaptureParam {
+ ///【字段含义】摄像头采集偏好
+ TXCameraCaptureMode mode;
+
+ ///【字段含义】采集图像长度
+ int width;
+
+ ///【字段含义】采集图像宽度
+ int height;
+
+ TXCameraCaptureParam() : mode(TXCameraResolutionStrategyAuto), width(640), height(360) {
+ }
};
+#endif
/**
- * 设备类型
+ * 音视频设备的相关信息（仅适用于桌面平台）
+ *
+ * 该结构体用于描述一个音视频设备的关键信息，比如设备ID、设备名称等等，以便用户能够在用户界面上选择自己期望使用的音视频设备。
*/
-enum TXMediaDeviceType
-{
- TXMediaDeviceTypeUnknown = -1, ///< 未知类型
- TXMediaDeviceTypeMic = 0, ///< 麦克风
- TXMediaDeviceTypeSpeaker = 1, ///< 扬声器或听筒
- TXMediaDeviceTypeCamera = 2, ///< 摄像头
+class ITXDeviceInfo {
+ protected:
+ virtual ~ITXDeviceInfo() {
+ }
+
+ public:
+ /// device name (UTF-8)
+ virtual const char* getDeviceName() = 0;
+ /// device PID (UTF-8)
+ virtual const char* getDevicePID() = 0;
+ /// release function, don't use delete!!!
+ virtual void release() = 0;
};
/**
- * 设备列表
+ * 设备信息列表（仅适用于桌面平台）
+ *
+ * 此结构体的作用相当于 std::vector<ITXDeviceInfo>，用于解决不同版本的 STL 容器的二进制兼容问题。
*/
class ITXDeviceCollection {
protected:
@@ -80,323 +159,261 @@ class ITXDeviceCollection {
}
public:
- /**
- * @return 设备个数
- */
+ /// Size of this list.
virtual uint32_t getCount() = 0;
-
- /**
- * @return 设备名称，字符编码格式是UTF-8
- */
+ /// device name (UTF-8)
virtual const char* getDeviceName(uint32_t index) = 0;
-
- /**
- * @return 设备PID，字符编码格式是UTF-8
- */
+ /// device PID (UTF-8)
virtual const char* getDevicePID(uint32_t index) = 0;
-
- /**
- * @brief 遍历完设备后，调用release释放资源。
- */
+ /// release function, don't use delete!!!
virtual void release() = 0;
};
+/// @}
-/**
- * 设备 Item 信息
- */
-class ITXDeviceInfo {
+class ITXDeviceManager {
protected:
- virtual ~ITXDeviceInfo() {
+ ITXDeviceManager() {
+ }
+ virtual ~ITXDeviceManager() {
}
public:
+/////////////////////////////////////////////////////////////////////////////////
+//
+// 移动端设备操作接口（iOS Android）
+//
+/////////////////////////////////////////////////////////////////////////////////
+/// @name 移动端设备操作接口
+/// @{
+
+/**
+ * 1.1 判断当前是否为前置摄像头（仅适用于移动端）
+ */
+#if __ANDROID__ || (__APPLE__ && TARGET_OS_IOS)
+ virtual bool isFrontCamera() = 0;
+
/**
- * @return 设备名称，字符编码格式是UTF-8
+ * 1.2 切换前置或后置摄像头（仅适用于移动端）
*/
- virtual const char* getDeviceName() = 0;
+ virtual int switchCamera(bool frontCamera) = 0;
/**
- * @return 设备PID，字符编码格式是UTF-8
+ * 1.3 获取摄像头的最大缩放倍数（仅适用于移动端）
*/
- virtual const char* getDevicePID() = 0;
+ virtual float getCameraZoomMaxRatio() = 0;
/**
- * @brief 获取完设备信息后，调用release释放资源。
+ * 1.4 设置摄像头的缩放倍数（仅适用于移动端）
+ *
+ * @param zoomRatio 取值范围1 - 5，取值为1表示最远视角（正常镜头），取值为5表示最近视角（放大镜头）。
*/
- virtual void release() = 0;
-};
+ virtual int setCameraZoomRatio(float zoomRatio) = 0;
-class ITXDeviceManager {
-protected:
- ITXDeviceManager() {}
- virtual ~ITXDeviceManager() {}
+ /**
+ * 1.5 查询是否支持自动识别人脸位置（仅适用于移动端）
+ */
+ virtual bool isAutoFocusEnabled() = 0;
+
+ /**
+ * 1.6 开启自动对焦功能（仅适用于移动端）
+ *
+ * 开启后，SDK 会自动检测画面中的人脸位置，并将摄像头的焦点始终对焦在人脸位置上。
+ */
+ virtual int enableCameraAutoFocus(bool enabled) = 0;
-public:
-
-#if (__APPLE__ && TARGET_OS_MAC && !TARGET_OS_IPHONE) || _WIN32
/**
- * 获取设备列表
+ * 1.7 设置摄像头的对焦位置（仅适用于移动端）
*
- * @param type 设备类型，指定需要获取哪种设备的列表。详见 TXMediaDeviceType 定义。
+ * 您可以通过该接口实现如下交互：
+ * 1. 在本地摄像头的预览画面上，允许用户单击操作。
+ * 2. 在用户的单击位置显示一个矩形方框，以示摄像头会在此处对焦。
+ * 3. 随后将用户点击位置的坐标通过本接口传递给 SDK，之后 SDK 会操控摄像头按照用户期望的位置进行对焦。
+ * @note 使用该接口的前提是先通过 {@link enableCameraAutoFocus} 关闭自动对焦功能。
+ * @param position 对焦位置，请传入期望对焦点的坐标值
+ * @return 0：操作成功；负数：操作失败。
+ */
+ virtual int setCameraFocusPosition(float x, float y) = 0;
+
+ /**
+ * 1.8 开启/关闭闪光灯，也就是手电筒模式（仅适用于移动端）
+ */
+ virtual int enableCameraTorch(bool enabled) = 0;
+
+ /**
+ * 1.9 设置音频路由（仅适用于移动端）
*
- * @note - delete ITXDeviceCollection* 指针会导致编译错误，SDK 维护 ITXDeviceCollection 对象的生命周期
- * - 使用完毕后请调用 release 方法释放资源
- * - type 只支持 TXMediaDeviceTypeMic、TXMediaDeviceTypeSpeaker、TXMediaDeviceTypeCamera
- * - 此接口只支持 Mac 和 Windows 平台
+ * 手机有两个音频播放设备：一个是位于手机顶部的听筒，一个是位于手机底部的立体声扬声器。
+ * 设置音频路由为听筒时，声音比较小，只有将耳朵凑近才能听清楚，隐私性较好，适合用于接听电话。
+ * 设置音频路由为扬声器时，声音比较大，不用将手机贴脸也能听清，因此可以实现“免提”的功能。
+ */
+ virtual int setAudioRoute(TXAudioRoute route) = 0;
+
+ /**
+ * 1.10 设置系统音量类型（仅适用于移动端）
*/
+ virtual int setSystemVolumeType(TXSystemVolumeType type) = 0;
+#endif
+
+/// @}
+/////////////////////////////////////////////////////////////////////////////////
+//
+// 桌面端设备操作接口（Windows Mac）
+//
+/////////////////////////////////////////////////////////////////////////////////
+/// @name 桌面端设备操作接口
+/// @{
+
+/**
+ * 2.1 获取设备列表（仅适用于桌面端）
+ *
+ * @param type 设备类型，指定需要获取哪种设备的列表。详见 TXMediaDeviceType 定义。
+ * @note
+ * - 使用完毕后请调用 release 方法释放资源，这样可以让 SDK 维护 ITXDeviceCollection 对象的生命周期。
+ * - 不要使用 delete 释放返回的 Collection 对象，delete ITXDeviceCollection* 指针会导致异常崩溃。
+ * - type 只支持 TXMediaDeviceTypeMic、TXMediaDeviceTypeSpeaker、TXMediaDeviceTypeCamera。
+ * - 此接口只支持 Mac 和 Windows 平台
+ */
+#if (__APPLE__ && TARGET_OS_MAC && !TARGET_OS_IPHONE) || _WIN32
virtual ITXDeviceCollection* getDevicesList(TXMediaDeviceType type) = 0;
/**
- * 指定当前设备
+ * 2.2 设置当前要使用的设备（仅适用于桌面端）
*
- * @param type 设备类型，根据设备类型指定当前设备。详见 TXMediaDeviceType 定义。
- * @param deviceId 从 getDevicesList 中得到的设备 ID
- * @return 0：操作成功 负数：失败
- * @note - type 只支持 TXMediaDeviceTypeMic、TXMediaDeviceTypeSpeaker、TXMediaDeviceTypeCamera
- * - 此接口只支持 Mac 和 Windows 平台
+ * @param type 设备类型，详见 TXMediaDeviceType 定义。
+ * @param deviceId 设备ID，您可以通过接口 {@link getDevicesList} 获得设备 ID。
+ * @return 0：操作成功；负数：操作失败。
*/
virtual int setCurrentDevice(TXMediaDeviceType type, const char* deviceId) = 0;
/**
- * 获取当前使用的设备
- *
- * @param type 设备类型，根据设备类型获取当前设备信息。详见 TXMediaDeviceType 定义。
- * @return ITRTCDeviceInfo 设备信息，能获取设备 ID 和设备名称
- * @note 此接口只支持 Mac 和 Windows 平台
+ * 2.3 获取当前正在使用的设备（仅适用于桌面端）
*/
virtual ITXDeviceInfo* getCurrentDevice(TXMediaDeviceType type) = 0;
/**
- * 设置当前设备的音量
+ * 2.4 设置当前设备的音量（仅适用于桌面端）
*
- * @param type 设备类型，根据设备类型获取当前设备音量。详见 TXMediaDeviceType 定义。
- * @param volume 音量大小
- * @return 0：操作成功 负数：失败
- * @note - type 只支持 TXMediaDeviceTypeMic、TXMediaDeviceTypeSpeaker
- * - 此接口只支持 Mac 和 Windows 平台
+ * 这里的音量指的是麦克风的采集音量或者扬声器的播放音量，摄像头是不支持设置音量的。
+ *
+ * @param volume 音量大小，取值范围为0 - 100，默认值：100。
+ * @note 如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。
*/
virtual int setCurrentDeviceVolume(TXMediaDeviceType type, uint32_t volume) = 0;
/**
- * 获取当前设备的音量
- *
- * @param type 设备类型，根据设备类型获取当前设备音量。详见 TXMediaDeviceType 定义。
+ * 2.5 获取当前设备的音量（仅适用于桌面端）
*
- * @note - type 只支持 TXMediaDeviceTypeMic、TXMediaDeviceTypeSpeaker
- * - 此接口只支持 Mac 和 Windows 平台
+ * 这里的音量指的是麦克风的采集音量或者扬声器的播放音量，摄像头是不支持获取音量的。
*/
virtual uint32_t getCurrentDeviceVolume(TXMediaDeviceType type) = 0;
/**
- * 设置当前设备是否静音
+ * 2.6 设置当前设备的静音状态（仅适用于桌面端）
*
- * @param type 设备类型，根据设备类型设置当前设备状态。详见 TXMediaDeviceType 定义。
- * @param mute 是否静音/禁画
- * @return 0：操作成功 负数：失败
- * @note - type 只支持 TXMediaDeviceTypeMic、TXMediaDeviceTypeSpeaker
- * - 此接口只支持 Mac 和 Windows 平台
+ * 这里的音量指的是麦克风和扬声器，摄像头是不支持静音操作的。
*/
virtual int setCurrentDeviceMute(TXMediaDeviceType type, bool mute) = 0;
/**
- * 查询当前设备是否静音
+ * 2.7 获取当前设备的静音状态（仅适用于桌面端）
*
- * @param type 设备类型，根据设备类型获取当前设备状态。详见 TXMediaDeviceType 定义。
- * @return true : 当前设备已静音；false : 当前设备未静音
- * @note type 只支持 TXMediaDeviceTypeMic、TXMediaDeviceTypeSpeaker
+ * 这里的音量指的是麦克风和扬声器，摄像头是不支持静音操作的。
*/
virtual bool getCurrentDeviceMute(TXMediaDeviceType type) = 0;
/**
- * 开始摄像头测试
+ * 2.8 开始摄像头测试（仅适用于桌面端）
*
- * @param view 预览控件所在的父控件
- * @return 0：操作成功 负数：失败
- * @note - 在测试过程中可以使用 setCurrentCameraDevice 接口切换摄像头。
- * - 此接口只支持 Mac 和 Windows 平台
+ * @note 在测试过程中可以使用 {@link setCurrentDevice} 接口切换摄像头。
*/
virtual int startCameraDeviceTest(void* view) = 0;
-#ifdef _WIN32
/**
- * 开始进行摄像头测试
- * 会触发 onFirstVideoFrame 回调接口
- *
- * @param callback 摄像头预览自定义渲染画面回调
- * @return 0：操作成功 负数：失败
- * @note - 在测试过程中可以使用 setCurrentCameraDevice 接口切换摄像头。
- * - 此接口只支持 Windows 平台
- */
- virtual int startCameraDeviceTest(ITRTCVideoRenderCallback* callback) = 0;
-#endif
-
- /**
- * 结束摄像头测试
- * @return 0：操作成功 负数：失败
- * @note 此接口只支持 Mac 和 Windows 平台
+ * 2.9 结束摄像头测试（仅适用于桌面端）
*/
virtual int stopCameraDeviceTest() = 0;
/**
- * 开始麦克风测试
+ * 2.10 开始麦克风测试（仅适用于桌面端）
*
- * @param interval 音量回调间隔
- * @return 0：操作成功 负数：失败
- * @note 此接口只支持 Mac 和 Windows 平台
+ * 该接口可以测试麦克风是否能正常工作，测试到的麦克风采集音量的大小，会以回调的形式通知给您，其中 volume 的取值范围为0 - 100。
+ * @param interval 麦克风音量的回调间隔。
*/
virtual int startMicDeviceTest(uint32_t interval) = 0;
/**
- * 结束麦克风测试
- * @return 0：操作成功 负数：失败
- * @note 此接口只支持 Mac 和 Windows 平台
+ * 2.11 结束麦克风测试（仅适用于桌面端）
*/
virtual int stopMicDeviceTest() = 0;
/**
- * 开始扬声器测试
+ * 2.12 开始扬声器测试（仅适用于桌面端）
*
- * 该方法播放指定的音频文件测试播放设备是否能正常工作。如果能听到声音，说明播放设备能正常工作。
+ * 该接口通过播放指定的音频文件，用于测试播放设备是否能正常工作。如果用户在测试时能听到声音，说明播放设备能正常工作。
* @param filePath 声音文件的路径
- * @return 0：操作成功 负数：失败
- * @note 此接口只支持 Mac 和 Windows 平台
*/
virtual int startSpeakerDeviceTest(const char* filePath) = 0;
/**
- * 停止扬声器测试
- * @return 0：操作成功 负数：失败
- * @note 此接口只支持 Mac 和 Windows 平台
+ * 2.13 结束扬声器测试（仅适用于桌面端）
*/
virtual int stopSpeakerDeviceTest() = 0;
+#endif
+/**
+ * 2.14 开始摄像头测试（仅适用于 Windows 系统）
+ *
+ * 该接口支持自定义渲染，即您可以通过接 ITRTCVideoRenderCallback 回调接口接管摄像头的渲染画面。
+ */
+#ifdef _WIN32
+ virtual int startCameraDeviceTest(ITRTCVideoRenderCallback* callback) = 0;
+#endif
+
+/**
+ * 2.15 设置 Windows 系统音量合成器中当前进程的音量（仅适用于 Windows 系统）
+ */
#ifdef _WIN32
- /**
- * 设置 Windows 系统音量合成器中当前进程的音量
- *
- * @param volume 音量值，取值范围[0~100]
- * @return 0:成功
- */
virtual int setApplicationPlayVolume(int volume) = 0;
+#endif
- /**
- * 获取 Windows 系统音量合成器中当前进程的音量
- *
- * @return 返回音量值，取值范围[0~100]
- */
+/**
+ * 2.16 获取 Windows 系统音量合成器中当前进程的音量（仅适用于 Windows 系统）
+ */
+#ifdef _WIN32
virtual int getApplicationPlayVolume() = 0;
+#endif
- /**
- * 设置 Windows 系统音量合成器中当前进程的静音状态
- *
- * @param bMute 是否设置为静音状态
- * @return 0 设置成功
- */
+/**
+ * 2.17 设置 Windows 系统音量合成器中当前进程的静音状态（仅适用于 Windows 系统）
+ */
+#ifdef _WIN32
virtual int setApplicationMuteState(bool bMute) = 0;
+#endif
- /**
- * 获取 Windows 系统音量合成器中当前进程的静音状态
- *
- * @return 返回静音状态
- */
+/**
+ * 2.18 获取 Windows 系统音量合成器中当前进程的静音状态（仅适用于 Windows 系统）
+ */
+#ifdef _WIN32
virtual bool getApplicationMuteState() = 0;
#endif
-
-#elif __ANDROID__ || (__APPLE__ && TARGET_OS_IOS)
- /**
- * 切换摄像头
- *
- * @param frontCamera YES：切换到前置摄像头 NO：切换到后置摄像头
- * @return 0：操作成功 负数：失败
- * @note 此接口只支持 Android 和 iOS 平台
- */
- virtual int switchCamera(bool frontCamera) = 0;
-
- /**
- * 当前是否为前置摄像头
- * @note 此接口只支持 Android 和 iOS 平台
- */
- virtual bool isFrontCamera() = 0;
-
- /**
- * 获取摄像头最大缩放倍数
- * @note 此接口只支持 Android 和 iOS 平台
- */
- virtual float getCameraZoomMaxRatio() = 0;
-
- /**
- * 设置摄像头缩放倍数
- *
- * @param zoomRatio 缩放倍数
- * @return 0：操作成功 负数：失败
- * @note 此接口只支持 Android 和 iOS 平台
- */
- virtual int setCameraZoomRatio(float zoomRatio) = 0;
-
- /**
- * 设置是否自动识别人脸位置
- *
- * @param enabled YES：开启；NO：关闭，默认值：YES
- * @return 0：操作成功 负数：失败
- * @note 此接口只支持 Android 和 iOS 平台
- */
- virtual int enableCameraAutoFocus (bool enabled) = 0;
- /**
- * 查询是否支持自动识别人脸位置
- * @note 此接口只支持 Android 和 iOS 平台
- */
- virtual bool isAutoFocusEnabled () = 0;
-
- /**
- * 设置摄像头焦点
- *
- * @param x 焦点横坐标
- * @param y 焦点纵坐标
- * @return 0：操作成功 负数：失败
- * @note 此接口只支持 Android 和 iOS 平台
- */
- virtual int setCameraFocusPosition (float x, float y) = 0;
+/**
+ * 2.19 设置摄像头采集偏好
+ */
+#ifdef _WIN32
+ virtual void setCameraCapturerParam(const TXCameraCaptureParam& params) = 0;
+#endif
- /**
- * 设置是否开启闪光灯
- *
- * @param enabled YES：开启；NO：关闭，默认值：NO
- * @return 0：操作成功 负数：失败
- * @note 此接口只支持 Android 和 iOS 平台
- */
- virtual int enableCameraTorch (bool enabled) = 0;
+ /// @}
+}; // End of class ITXDeviceManager
+} // namespace liteav
- /**
- * 设置通话时使用的系统音量类型
- *
- * @note
- * 1. 需要在调用 startLocalAudio() 之前调用该接口。<br>
- * 2. 如无特殊需求，不推荐您自行设置，您只需通过 enterRoom 设置好适合您的场景，SDK 内部会自动选择相匹配的音量类型。
- *
- * @param type 系统音量类型，如无特殊需求，不推荐您自行设置。
- * @return 0：操作成功 负数：失败
- * @note 此接口只支持 Android 和 iOS 平台
- */
- virtual int setSystemVolumeType (TXSystemVolumeType type) = 0;
+// 9.0 开始 C++ 接口将声明在 liteav 命名空间下，为兼容之前的使用方式，将 trtc 作为 liteav 的别名
+namespace trtc = liteav;
- /**
- * 设置设置音频路由
- *
- * 微信和手机 QQ 视频通话功能的免提模式就是基于音频路由实现的。
- * 一般手机都有两个扬声器，一个是位于顶部的听筒扬声器，声音偏小；一个是位于底部的立体声扬声器，声音偏大。
- * 设置音频路由的作用就是决定声音使用哪个扬声器播放。
- *
- * @param route 音频路由，即声音由哪里输出（扬声器、听筒），默认值：TXAudioRouteSpeakerphone
- * @return 0：操作成功 负数：失败
- * @note 此接口只支持 Android 和 iOS 平台
- */
- virtual int setAudioRoute (TXAudioRoute route) = 0;
-
+#ifdef _WIN32
+using namespace liteav;
#endif
-};
+#endif / *__ITXDEVICEMANAGER_H__* /
/// @}
-}
-
-#endif /* ITXDeviceManager_h */
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/cpp_interface/TRTCCloudCallback.h b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/cpp_interface/TRTCCloudCallback.h
index 4f0ab84..e140296 100644
--- a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/cpp_interface/TRTCCloudCallback.h
+++ b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/cpp_interface/TRTCCloudCallback.h
@@ -1,74 +1,77 @@
- /*
- * Module: TRTCCloudCallback @ TXLiteAVSDK
- *
- * Function: 腾讯云视频通话功能的回调接口类，若想从C++代码中获取到TRTC SDK的回调，请继承此类并调用 ITRTCCloud::addCallback(TRTCCloudCallback* callback)设置观察者
- *
+/**
+ * Module: TRTCCloudDelegate @ TXLiteAVSDK
+ * Function: 腾讯云实时音视频的事件回调接口
*/
-
+/// @defgroup TRTCCloudCallback_cplusplus TRTCCloudCallback
+/// 腾讯云实时音视频的事件回调接口
+/// @{
#ifndef __TRTCCLOUDCALLBACK_H__
#define __TRTCCLOUDCALLBACK_H__
#include "TRTCTypeDef.h"
#include "ITXDeviceManager.h"
#include "TXLiteAVCode.h"
+#include "ITRTCStatistics.h"
-namespace trtc {
+namespace liteav {
-/// @defgroup TRTCCloudCallback_cplusplus TRTCCloudCallback
-/// 腾讯云视频通话功能的回调接口类
-/// @{
-/**
- * 腾讯云视频通话功能的回调接口类
- */
-class ITRTCCloudCallback
-{
-public:
- virtual ~ITRTCCloudCallback() {}
+class ITRTCCloudCallback {
+ public:
+ virtual ~ITRTCCloudCallback() {
+ }
/////////////////////////////////////////////////////////////////////////////////
//
- // （一）错误事件和警告事件
+ // 错误和警告事件
//
/////////////////////////////////////////////////////////////////////////////////
- /// @name 错误事件和警告事件
+ /// @name 错误和警告事件
/// @{
+
/**
- * 1.1 错误回调：SDK 不可恢复的错误，一定要监听，并分情况给用户适当的界面提示。
+ * 1.1 错误事件回调
+ *
+ * 错误事件，表示 SDK 抛出的不可恢复的错误，比如进入房间失败或设备开启失败等。
+ * 参考文档：[错误码表](https://cloud.tencent.com/document/product/647/32257)
*
- * @param errCode 错误码
- * @param errMsg 错误信息
- * @param extraInfo 扩展信息字段，个别错误码可能会带额外的信息帮助定位问题
+ * @param errCode 错误码
+ * @param errMsg 错误信息
+ * @param extInfo 扩展信息字段，个别错误码可能会带额外的信息帮助定位问题
*/
virtual void onError(TXLiteAVError errCode, const char* errMsg, void* extraInfo) = 0;
/**
- * 1.2 警告回调：用于告知您一些非严重性问题，例如出现了卡顿或者可恢复的解码失败。
+ * 1.2 警告事件回调
+ *
+ * 警告事件，表示 SDK 抛出的提示性问题，比如视频出现卡顿或 CPU 使用率太高等。
+ * 参考文档：[错误码表](https://cloud.tencent.com/document/product/647/32257)
*
* @param warningCode 警告码
* @param warningMsg 警告信息
- * @param extraInfo 扩展信息字段，个别警告码可能会带额外的信息帮助定位问题
+ * @param extInfo 扩展信息字段，个别警告码可能会带额外的信息帮助定位问题
*/
virtual void onWarning(TXLiteAVWarning warningCode, const char* warningMsg, void* extraInfo) = 0;
- /// @}
+ /// @}
/////////////////////////////////////////////////////////////////////////////////
//
- // （二）房间事件回调
+ // 房间相关事件回调
//
/////////////////////////////////////////////////////////////////////////////////
- /// @name 房间事件回调
+ /// @name 房间相关事件回调
/// @{
+
/**
- * 2.1 已加入房间的回调
+ * 2.1 进入房间成功与否的事件回调
*
- * 调用 TRTCCloud 中的 enterRoom() 接口执行进房操作后，会收到来自 SDK 的 onEnterRoom(result) 回调：
+ * 调用 TRTCCloud 中的 enterRoom() 接口执行进房操作后，会收到来自 TRTCCloudDelegate 的 onEnterRoom(result) 回调：
+ * - 如果加入成功，回调 result 会是一个正数（result > 0），代表进入房间所消耗的时间，单位是毫秒（ms）。
+ * - 如果加入失败，回调 result 会是一个负数（result < 0），代表失败原因的错误码。
+ * 进房失败的错误码含义请参见[错误码表](https://cloud.tencent.com/document/product/647/32257)。
*
- * - 如果加入成功，result 会是一个正数（result > 0），代表加入房间的时间消耗，单位是毫秒（ms）。
- * - 如果加入失败，result 会是一个负数（result < 0），代表进房失败的错误码。
- * 进房失败的错误码含义请参见[错误码](https://cloud.tencent.com/document/product/647/32257)。
- *
- * @note 在 Ver6.6 之前的版本，只有进房成功会抛出 onEnterRoom(result) 回调，进房失败由 onError() 回调抛出。
- * 在 Ver6.6 及之后改为：进房成功返回正的 result，进房失败返回负的 result，同时进房失败也会有 onError() 回调抛出。
+ * @note
+ * 1. 在 Ver6.6 之前的版本，只有进房成功会抛出 onEnterRoom(result) 回调，进房失败由 onError() 回调抛出。
+ * 2. 在 Ver6.6 之后的版本：无论进房成功或失败，均会抛出 onEnterRoom(result) 回调，同时进房失败也会有 onError() 回调抛出。
*
* @param result result > 0 时为进房耗时（ms），result < 0 时为进房错误码。
*/
@@ -78,12 +81,12 @@ public:
* 2.2 离开房间的事件回调
*
* 调用 TRTCCloud 中的 exitRoom() 接口会执行退出房间的相关逻辑，例如释放音视频设备资源和编解码器资源等。
- * 待资源释放完毕，SDK 会通过 onExitRoom() 回调通知到您。
+ * 待 SDK 占用的所有资源释放完毕后，SDK 会抛出 onExitRoom() 回调通知到您。
*
* 如果您要再次调用 enterRoom() 或者切换到其他的音视频 SDK，请等待 onExitRoom() 回调到来后再执行相关操作。
* 否则可能会遇到例如摄像头、麦克风设备被强占等各种异常问题。
*
- * @param reason 离开房间原因，0：主动调用 exitRoom 退房；1：被服务器踢出当前房间；2：当前房间整个被解散。
+ * @param reason 离开房间原因，0：主动调用 exitRoom 退出房间；1：被服务器踢出当前房间；2：当前房间整个被解散。
*/
virtual void onExitRoom(int reason) = 0;
@@ -96,318 +99,437 @@ public:
* @param errCode 错误码，ERR_NULL 代表切换成功，其他请参见[错误码](https://cloud.tencent.com/document/product/647/32257)。
* @param errMsg 错误信息。
*/
- virtual void onSwitchRole(TXLiteAVError errCode, const char* errMsg) {}
+ virtual void onSwitchRole(TXLiteAVError errCode, const char* errMsg) {
+ }
+
+ /**
+ * 2.4 切换房间的结果回调
+ *
+ * 调用 TRTCCloud 中的 switchRoom() 接口可以让用户快速地从一个房间切换到另一个房间，
+ * 待 SDK 切换完成后，会抛出 onSwitchRoom() 事件回调。
+ *
+ * @param errCode 错误码，ERR_NULL 代表切换成功，其他请参见[错误码](https://cloud.tencent.com/document/product/647/32257)。
+ * @param errMsg 错误信息。
+ */
+ virtual void onSwitchRoom(TXLiteAVError errCode, const char* errMsg) {
+ }
/**
- * 2.4 请求跨房通话（主播 PK）的结果回调
+ * 2.5 请求跨房通话的结果回调
*
* 调用 TRTCCloud 中的 connectOtherRoom() 接口会将两个不同房间中的主播拉通视频通话，也就是所谓的“主播PK”功能。
* 调用者会收到 onConnectOtherRoom() 回调来获知跨房通话是否成功，
- * 如果成功，两个房间中的所有用户都会收到 PK 主播的 onUserVideoAvailable() 回调。
+ * 如果成功，两个房间中的所有用户都会收到来自另一个房间中的 PK 主播的 onUserVideoAvailable() 回调。
*
- * @param userId 要 PK 的目标主播 userId。
+ * @param userId 要跨房通话的另一个房间中的主播的用户 ID。
* @param errCode 错误码，ERR_NULL 代表切换成功，其他请参见[错误码](https://cloud.tencent.com/document/product/647/32257)。
* @param errMsg 错误信息。
*/
- virtual void onConnectOtherRoom(const char* userId, TXLiteAVError errCode, const char* errMsg) {}
+ virtual void onConnectOtherRoom(const char* userId, TXLiteAVError errCode, const char* errMsg) {
+ }
/**
- * 2.5 结束跨房通话（主播 PK）的结果回调
+ * 2.6 结束跨房通话的结果回调
*/
- virtual void onDisconnectOtherRoom(TXLiteAVError errCode, const char* errMsg) {}
+ virtual void onDisconnectOtherRoom(TXLiteAVError errCode, const char* errMsg) {
+ }
- /**
- * 2.6 切换房间 (switchRoom) 的结果回调
- */
- virtual void onSwitchRoom(TXLiteAVError errCode, const char* errMsg) {}
/// @}
-
/////////////////////////////////////////////////////////////////////////////////
//
- // （三）成员事件回调
+ // 用户相关事件回调
//
/////////////////////////////////////////////////////////////////////////////////
- /// @name 成员事件回调
+ /// @name 用户相关事件回调
/// @{
+
/**
* 3.1 有用户加入当前房间
*
- * 出于性能方面的考虑，在两种不同的应用场景下，该通知的行为会有差别：
- * - 通话场景（TRTCAppSceneVideoCall 和 TRTCAppSceneAudioCall）：该场景下用户没有角色的区别，任何用户进入房间都会触发该通知。
- * - 直播场景（TRTCAppSceneLIVE 和 TRTCAppSceneVoiceChatRoom）：该场景不限制观众的数量，如果任何用户进出都抛出回调会引起很大的性能损耗，所以该场景下只有主播进入房间时才会触发该通知，观众进入房间不会触发该通知。
- *
+ * 出于性能方面的考虑，在 TRTC 两种不同的应用场景（即 AppScene，在 enterRoom 时通过第二个参数指定）下，该通知的行为会有差别：
+ * - 直播类场景（TRTCAppSceneLIVE 和 TRTCAppSceneVoiceChatRoom）：该场景下的用户区分主播和观众两种角色，只有主播进入房间时才会触发该通知，观众进入房间时不会触发该通知。
+ * - 通话类场景（TRTCAppSceneVideoCall 和 TRTCAppSceneAudioCall）：该场景下的用户没有角色的区分（可认为都是主播），任何用户进入房间都会触发该通知。
*
- * @note 注意 onRemoteUserEnterRoom 和 onRemoteUserLeaveRoom 只适用于维护当前房间里的“成员列表”，如果需要显示远程画面，建议使用监听 onUserVideoAvailable() 事件回调。
- *
- * @param userId 用户标识
+ * @note
+ * 1. 事件回调 onRemoteUserEnterRoom 和 onRemoteUserLeaveRoom 只适用于维护当前房间里的“用户列表”，有此事件回调不代表一定有视频画面。
+ * 2. 如果需要显示远程画面，请监听代表某个用户是否有视频画面的 onUserVideoAvailable() 事件回调。
+ * @param userId 远端用户的用户标识
*/
- virtual void onRemoteUserEnterRoom(const char* userId) {}
+ virtual void onRemoteUserEnterRoom(const char* userId) {
+ }
/**
* 3.2 有用户离开当前房间
*
- * 与 onRemoteUserEnterRoom 相对应，在两种不同的应用场景下，该通知的行为会有差别：
- * - 通话场景（TRTCAppSceneVideoCall 和 TRTCAppSceneAudioCall）：该场景下用户没有角色的区别，任何用户的离开都会触发该通知。
- * - 直播场景（TRTCAppSceneLIVE 和 TRTCAppSceneVoiceChatRoom）：只有主播离开房间时才会触发该通知，观众离开房间不会触发该通知。
+ * 与 onRemoteUserEnterRoom 相对应，在两种不同的应用场景（即 AppScene，在 enterRoom 时通过第二个参数指定）下，该通知的行为会有差别：
+ * - 直播类场景（TRTCAppSceneLIVE 和 TRTCAppSceneVoiceChatRoom）：只有主播离开房间时才会触发该通知，观众离开房间不会触发该通知。
+ * - 通话类场景（TRTCAppSceneVideoCall 和 TRTCAppSceneAudioCall）：该场景下用户没有角色的区别，任何用户的离开都会触发该通知。
*
- * @param userId 用户标识
+ * @param userId 远端用户的用户标识
* @param reason 离开原因，0表示用户主动退出房间，1表示用户超时退出，2表示被踢出房间。
*/
- virtual void onRemoteUserLeaveRoom(const char* userId, int reason) {}
+ virtual void onRemoteUserLeaveRoom(const char* userId, int reason) {
+ }
/**
- * 3.3 用户是否开启摄像头视频
+ * 3.3 某远端用户发布/取消了主路视频画面
*
- * 当您收到 onUserVideoAvailable(userId, YES) 通知时，表示该路画面已经有可用的视频数据帧到达。
- * 此时，您需要调用 startRemoteView(userId) 接口加载该用户的远程画面。
- * 然后，您还会收到名为 onFirstVideoFrame(userId) 的首帧画面渲染回调。
+ * “主路画面”一般被用于承载摄像头画面。当您收到 onUserVideoAvailable(userId, true) 通知时，表示该路画面已经有可播放的视频帧到达。
+ * 此时，您需要调用 {@link startRemoteView} 接口订阅该用户的远程画面，订阅成功后，您会继续收到该用户的首帧画面渲染回调 onFirstVideoFrame(userid)。
*
- * 当您收到 onUserVideoAvailable(userId, NO) 通知时，表示该路远程画面已被关闭，
- * 可能由于该用户调用了 muteLocalVideo() 或 stopLocalPreview()。
+ * 当您收到 onUserVideoAvailable(userId, false) 通知时，表示该路远程画面已经被关闭，关闭的原因可能是该用户调用了 {@link muteLocalVideo} 或 {@link stopLocalPreview}。
*
- * @param userId 用户标识
- * @param available 画面是否开启
+ * @param userId 远端用户的用户标识
+ * @param available 该用户是否发布（或取消发布）了主路视频画面，true: 发布；false：取消发布。
*/
- virtual void onUserVideoAvailable(const char* userId, bool available) {}
+ virtual void onUserVideoAvailable(const char* userId, bool available) {
+ }
/**
- * 3.4 用户是否开启屏幕分享
+ * 3.4 某远端用户发布/取消了辅路视频画面
*
- * @param userId 用户标识
- * @param available 屏幕分享是否开启
+ * “辅路画面”一般被用于承载屏幕分享的画面。当您收到 onUserSubStreamAvailable(userId, true) 通知时，表示该路画面已经有可播放的视频帧到达。
+ * 此时，您需要调用 {@link startRemoteSubStreamView} 接口订阅该用户的远程画面，订阅成功后，您会继续收到该用户的首帧画面渲染回调 onFirstVideoFrame(userid)。
+ *
+ * @note 显示辅路画面使用的函数是 {@link startRemoteSubStreamView} 而非 {@link startRemoteView}。
+ *
+ * @param userId 远端用户的用户标识
+ * @param available 该用户是否发布（或取消发布）了辅路视频画面，true: 发布；false：取消发布。
*/
- virtual void onUserSubStreamAvailable(const char* userId, bool available) {}
+ virtual void onUserSubStreamAvailable(const char* userId, bool available) {
+ }
/**
- * 3.5 用户是否开启音频上行
+ * 3.5 某远端用户发布/取消了自己的音频
*
- * @param userId 用户标识
- * @param available 声音是否开启
+ * 当您收到 onUserAudioAvailable(userId, true) 通知时，表示该用户发布了自己的声音，此时 SDK 的表现为：
+ * - 在自动订阅模式下，您无需做任何操作，SDK 会自动播放该用户的声音。
+ * - 在手动订阅模式下，您可以通过 {@link muteRemoteAudio}(userid, false) 来播放该用户的声音。
+ *
+ * @note SDK 默认使用自动订阅模式，您可以通过 {@link setDefaultStreamRecvMode} 设置为手动订阅，但需要在您进入房间之前调用才生效。
+ *
+ * @param userId 远端用户的用户标识
+ * @param available 该用户是否发布（或取消发布）了自己的音频，true: 发布；false：取消发布。
*/
- virtual void onUserAudioAvailable(const char* userId, bool available) {}
+ virtual void onUserAudioAvailable(const char* userId, bool available) {
+ }
/**
- * 3.6 开始渲染本地或远程用户的首帧画面
+ * 3.6 SDK 开始渲染自己本地或远端用户的首帧画面
*
- * 如果 userId 为 null，表示开始渲染本地采集的摄像头画面，需要您先调用 startLocalPreview 触发。
- * 如果 userId 不为 null，表示开始渲染远程用户的首帧画面，需要您先调用 startRemoteView 触发。
+ * SDK 会在渲染自己本地或远端用户的首帧画面时抛出该事件，您可以通过回调事件中的 userId 参数来判断事件来自于“本地”还是来自于“远端”。
+ * - 如果 userId 为空值，代表 SDK 已经开始渲染自己本地的视频画面，不过前提是您已经调用了 {@link startLocalPreview} 或 {@link startScreenCapture}。
+ * - 如果 userId 不为空，代表 SDK 已经开始渲染远端用户的视频画面，不过前提是您已经调用了 {@link startRemoteView} 订阅了该用户的视频画面。
*
- * @note 只有当您调用 startLocalPreview()、startRemoteView() 或 startRemoteSubStreamView() 之后，才会触发该回调。
+ * @note
+ * 1. 只有当您调用了 {@link startLocalPreview} 或 {@link startScreenCapture} 之后，才会触发自己本地的首帧画面事件回调。
+ * 2. 只有当您调用了 {@link startRemoteView} 或 {@link startRemoteSubStreamView} 之后，才会触发远端用户的首帧画面事件回调。
*
- * @param userId 本地或远程用户 ID，如果 userId == null 代表本地，userId != null 代表远程。
- * @param streamType 视频流类型：摄像头或屏幕分享。
- * @param width 画面宽度
- * @param height 画面高度
+ * @param userId 本地或远端的用户标识，如果 userId 为空值代表自己本地的首帧画面已到来，userId 不为空则代表远端用户的首帧画面已到来。
+ * @param streamType 视频流类型：主路（Main）一般用于承载摄像头画面，辅路（Sub）一般用于承载屏幕分享画面。
+ * @param width 画面的宽度。
+ * @param height 画面的高度。
*/
- virtual void onFirstVideoFrame(const char* userId, const TRTCVideoStreamType streamType, const int width, const int height) {}
+ virtual void onFirstVideoFrame(const char* userId, const TRTCVideoStreamType streamType, const int width, const int height) {
+ }
/**
- * 3.7 开始播放远程用户的首帧音频（本地声音暂不通知）
+ * 3.7 SDK 开始播放远端用户的首帧音频
+ *
+ * SDK 会在播放远端用户的首帧音频时抛出该事件，本地音频的首帧事件暂不抛出。
*
- * @param userId 远程用户 ID。
+ * @param userId 远端用户的用户标识
*/
- virtual void onFirstAudioFrame(const char* userId) {}
+ virtual void onFirstAudioFrame(const char* userId) {
+ }
/**
- * 3.8 首帧本地视频数据已经被送出
+ * 3.8 自己本地的首个视频帧已被发布出去
*
- * SDK 会在 enterRoom() 并 startLocalPreview() 成功后开始摄像头采集，并将采集到的画面进行编码。
- * 当 SDK 成功向云端送出第一帧视频数据后，会抛出这个回调事件。
+ * 当您成功进入房间并通过 {@link startLocalPreview} 或 {@link startScreenCapture} 开启本地视频采集之后（开启采集和进入房间的先后顺序无影响），
+ * SDK 就会开始进行视频编码，并通过自身的网络模块向云端发布自己本地的视频数据。
+ * 当 SDK 成功地向云端送出自己的第一帧视频数据帧以后，就会抛出 onSendFirstLocalVideoFrame 事件回调。
*
- * @param streamType 视频流类型，主画面、小画面或辅流画面（屏幕分享）
+ * @param streamType 视频流类型：主路（Main）一般用于承载摄像头画面，辅路（Sub）一般用于承载屏幕分享画面。
*/
- virtual void onSendFirstLocalVideoFrame(const TRTCVideoStreamType streamType) {}
+ virtual void onSendFirstLocalVideoFrame(const TRTCVideoStreamType streamType) {
+ }
/**
- * 3.9 首帧本地音频数据已经被送出
+ * 3.9 自己本地的首个音频帧已被发布出去
*
- * SDK 会在 enterRoom() 并 startLocalAudio() 成功后开始麦克风采集，并将采集到的声音进行编码。
- * 当 SDK 成功向云端送出第一帧音频数据后，会抛出这个回调事件。
+ * 当您成功进入房间并通过 {@link startLocalAudio} 开启本地音频采集之后（开启采集和进入房间的先后顺序无影响），
+ * SDK 就会开始进行音频编码，并通过自身的网络模块向云端发布自己本地的音频数据。
+ * 当 SDK 成功地向云端送出自己的第一帧音频数据帧以后，就会抛出 onSendFirstLocalAudioFrame 事件回调。
*/
- virtual void onSendFirstLocalAudioFrame() {}
- /// @}
+ virtual void onSendFirstLocalAudioFrame() {
+ }
+
+ /**
+ * 3.10 远端视频状态变化的事件回调
+ *
+ * 您可以通过此事件回调获取远端每一路画面的播放状态（包括 Playing、Loading 和 Stopped 三种状态），从而进行相应的 UI 展示。
+ * @param userId 用户标识
+ * @param streamType 视频流类型：主路（Main）一般用于承载摄像头画面，辅路（Sub）一般用于承载屏幕分享画面。
+ * @param status 视频状态：包括 Playing、Loading 和 Stopped 三种状态。
+ * @param reason 视频状态改变的原因
+ * @param extrainfo 额外信息
+ */
+ virtual void onRemoteVideoStatusUpdated(const char* userId, TRTCVideoStreamType streamType, TRTCAVStatusType status, TRTCAVStatusChangeReason reason, void* extrainfo) {
+ }
+ /// @}
/////////////////////////////////////////////////////////////////////////////////
//
- // （四）统计和质量回调
+ // 网络和技术指标统计回调
//
/////////////////////////////////////////////////////////////////////////////////
- /// @name 统计和质量回调
+ /// @name 网络和技术指标统计回调
/// @{
+
/**
- * 4.1 网络质量：该回调每2秒触发一次，统计当前网络的上行和下行质量
+ * 4.1 网络质量的实时统计回调
+ *
+ * 该统计回调每间隔2秒抛出一次，用于通知 SDK 感知到的当前网络的上行和下行质量。
+ * SDK 会使用一组内嵌的自研算法对当前网络的延迟高低、带宽大小以及稳定情况进行评估，并计算出一个的评估结果：
+ * 如果评估结果为 1（Excellent） 代表当前的网络情况非常好，如果评估结果为 6（Down）代表当前网络无法支撑 TRTC 的正常通话。
*
- * @note userId == null 代表自己当前的视频质量
+ * @note 回调参数 localQuality 和 remoteQuality 中的 userId 如果为空置，代表本组数据统计的是自己本地的网络质量，否则是代表远端用户的网络质量。
*
* @param localQuality 上行网络质量
* @param remoteQuality 下行网络质量
- * @param remoteQualityCount 下行网络质量的数组大小
*/
- virtual void onNetworkQuality(TRTCQualityInfo localQuality, TRTCQualityInfo* remoteQuality, uint32_t remoteQualityCount) {}
+ virtual void onNetworkQuality(TRTCQualityInfo localQuality, TRTCQualityInfo* remoteQuality, uint32_t remoteQualityCount) {
+ }
/**
- * 4.2 技术指标统计回调
+ * 4.2 音视频技术指标的实时统计回调
*
- * 如果您是熟悉音视频领域相关术语，可以通过这个回调获取 SDK 的所有技术指标。
- * 如果您是首次开发音视频相关项目，可以只关注 onNetworkQuality 回调。
+ * 该统计回调每间隔2秒抛出一次，用于通知 SDK 内部音频、视频以及网络相关的专业技术指标，这些信息在 {@link TRTCStatistics} 均有罗列：
+ * - 视频统计信息：视频的分辨率（resolution）、帧率（FPS）和比特率（bitrate）等信息。
+ * - 音频统计信息：音频的采样率（samplerate）、声道（channel）和比特率（bitrate）等信息。
+ * - 网络统计信息：SDK 和云端一次往返（SDK => Cloud => SDK）的网络耗时（rtt）、丢包率（loss）、上行流量（sentBytes）和下行流量（receivedBytes）等信息。
*
- * @param statis 统计数据，包括本地和远程的
- * @note 每2秒回调一次
+ * @note 如果您只需要获知当前网络质量的好坏，并不需要花太多时间研究本统计回调，更推荐您使用 {@link onNetworkQuality} 来解决问题。
+ * @param statistics 统计数据，包括自己本地的统计信息和远端用户的统计信息，详情请参考 {@link TRTCStatistics}。
*/
- virtual void onStatistics(const TRTCStatistics& statis) {}
- /// @}
-
+ virtual void onStatistics(const TRTCStatistics& statistics) {
+ }
+ /// @}
/////////////////////////////////////////////////////////////////////////////////
//
- // （五）服务器事件回调
+ // 与云端连接情况的事件回调
//
/////////////////////////////////////////////////////////////////////////////////
-
- /// @name 服务器事件回调
+ /// @name 与云端连接情况的事件回调
/// @{
+
/**
- * 5.1 SDK 跟服务器的连接断开
+ * 5.1 SDK 与云端的连接已经断开
+ *
+ * SDK 会在跟云端的连接断开时抛出此事件回调，导致断开的原因大多是网络不可用或者网络切换所致，比如用户在通话中走进电梯时就可能会遇到此事件。
+ * 在抛出此事件之后，SDK 会努力跟云端重新建立连接，重连过程中会抛出 {@link onTryToReconnect}，连接恢复后会抛出 {@link onConnectionRecovery} 。
+ * 所以，SDK 会在如下三个连接相关的事件中按如下规律切换：
+ * <pre>
+ * [onConnectionLost] =====> [onTryToReconnect] =====> [onConnectionRecovery]
+ * /|\ |
+ * |------------------------------------------------------|
+ * </pre>
*/
- virtual void onConnectionLost() {}
+ virtual void onConnectionLost() {
+ }
/**
- * 5.2 SDK 尝试重新连接到服务器
+ * 5.2 SDK 正在尝试重新连接到云端
+ *
+ * SDK 会在跟云端的连接断开时抛出 {@link onConnectionLost}，之后会努力跟云端重新建立连接并抛出本事件，连接恢复后会抛出 {@link onConnectionRecovery}。
*/
- virtual void onTryToReconnect() {}
+ virtual void onTryToReconnect() {
+ }
/**
- * 5.3 SDK 跟服务器的连接恢复
+ * 5.3 SDK 与云端的连接已经恢复
+ *
+ * SDK 会在跟云端的连接断开时抛出 {@link onConnectionLost}，之后会努力跟云端重新建立连接并抛出{@link onTryToReconnect}，连接恢复后会抛出本事件回调。
*/
- virtual void onConnectionRecovery() {}
+ virtual void onConnectionRecovery() {
+ }
/**
- * 5.4 服务器测速的回调，SDK 对多个服务器 IP 做测速，每个 IP 的测速结果通过这个回调通知
+ * 5.4 服务器测速的结果回调
*
+ * 当您调用 {@link startSpeedTest} 启动服务器测速后，SDK 多次抛出测速的结果回调。
+ * SDK 会对多台云端服务器的 IP 进行测速，每个 IP 对应的测速结果都会通过本回调接口通知给您。
* @param currentResult 当前完成的测速结果
* @param finishedCount 已完成测速的服务器数量
* @param totalCount 需要测速的服务器总数量
*/
- virtual void onSpeedTest(const TRTCSpeedTestResult& currentResult, uint32_t finishedCount, uint32_t totalCount) {}
- /// @}
+ virtual void onSpeedTest(const TRTCSpeedTestResult& currentResult, uint32_t finishedCount, uint32_t totalCount) {
+ }
+ /// @}
/////////////////////////////////////////////////////////////////////////////////
//
- // （六）硬件设备事件回调
+ // 硬件设备相关事件回调
//
/////////////////////////////////////////////////////////////////////////////////
- /// @name 硬件设备事件回调
+ /// @name 硬件设备相关事件回调
/// @{
+
/**
* 6.1 摄像头准备就绪
+ *
+ * 当您调用 {@link startLocalPreivew} 之后，SDK 会尝试启动摄像头，如果摄像头能够启动成功就会抛出本事件。
+ * 如果启动失败，大概率是因为当前应用没有获得访问摄像头的权限，或者摄像头当前正在被其他程序独占使用中。
+ * 您可以通过捕获 {@link onError} 事件回调获知这些异常情况并通过 UI 界面提示用户。
*/
- virtual void onCameraDidReady() {}
+ virtual void onCameraDidReady() {
+ }
/**
* 6.2 麦克风准备就绪
- */
- virtual void onMicDidReady() {}
-
- /**
- * 6.3 用于提示音量大小的回调,包括每个 userId 的音量和远端总音量
- *
- * 您可以通过调用 TRTCCloud 中的 enableAudioVolumeEvaluation 接口来开关这个回调或者设置它的触发间隔。
- * 需要注意的是，调用 enableAudioVolumeEvaluation 开启音量回调后，无论频道内是否有人说话，都会按设置的时间间隔调用这个回调，
- * 如果没有人说话，则 userVolumes 为空，totalVolume 为0。
*
- * @param userVolumes 所有正在说话的房间成员的音量，取值范围0 - 100。
- * @param userVolumesCount 房间成员数量
- * @param totalVolume 所有远端成员的总音量, 取值范围0 - 100。
- * @note userId 为 null 时表示自己的音量，userVolumes 内仅包含正在说话（音量不为0）的用户音量信息。
+ * 当您调用 {@link startLocalAudio} 之后，SDK 会尝试启动麦克风，如果麦克风能够启动成功就会抛出本事件。
+ * 如果启动失败，大概率是因为当前应用没有获得访问麦克风的权限，或者麦克风当前正在被其他程序独占使用中。
+ * 您可以通过捕获 {@link onError} 事件回调获知这些异常情况并通过 UI 界面提示用户。
*/
- virtual void onUserVoiceVolume(TRTCVolumeInfo* userVolumes, uint32_t userVolumesCount, uint32_t totalVolume) {}
+ virtual void onMicDidReady() {
+ }
-#if TARGET_PLATFORM_DESKTOP
/**
- * 6.4 本地设备通断回调
+ * 6.4 音量大小的反馈回调
*
- * @param deviceId 设备 ID
- * @param type 设备类型
- * @param state 事件类型
- */
- virtual void onDeviceChange(const char* deviceId, TRTCDeviceType type, TRTCDeviceState state) {}
-
- /**
- * 6.5 麦克风测试音量回调
+ * SDK 可以评估每一路音频的音量大小，并每隔一段时间抛出该事件回调，您可以根据音量大小在 UI 上做出相应的提示，比如“波形图”或“音量槽”。
+ * 要完成这个功能， 您需要先调用 {@link enableAudioVolumeEvaluation} 开启这个能力并设定事件抛出的时间间隔。
+ * 需要补充说明的是，无论当前房间中是否有人说话，SDK 都会按照您设定的时间间隔定时抛出此事件回调，只不过当没有人说话时，userVolumes 为空，totalVolume 为 0。
*
- * 麦克风测试接口 startMicDeviceTest 会触发这个回调
+ * @note userVolumes 为一个数组，对于数组中的每一个元素，当 userId 为空时表示本地麦克风采集的音量大小，当 userId 不为空时代表远端用户的音量大小。
*
- * @param volume 音量值，取值范围0 - 100
+ * @param userVolumes 是一个数组，用于承载所有正在说话的用户的音量大小，取值范围 0 - 100。
+ * @param totalVolume 所有远端用户的总音量大小, 取值范围 0 - 100。
*/
- virtual void onTestMicVolume(uint32_t volume) {}
+ virtual void onUserVoiceVolume(TRTCVolumeInfo* userVolumes, uint32_t userVolumesCount, uint32_t totalVolume) {
+ }
- /**
- * 6.6 扬声器测试音量回调
- *
- * 扬声器测试接口 startSpeakerDeviceTest 会触发这个回调
- *
- * @param volume 音量值，取值范围0 - 100
- */
- virtual void onTestSpeakerVolume(uint32_t volume) {}
+/**
+ * 6.5 本地设备的通断状态发生变化（仅适用于桌面系统）
+ *
+ * 当本地设备（包括摄像头、麦克风以及扬声器）被插入或者拔出时，SDK 便会抛出此事件回调。
+ *
+ * @param deviceId 设备 ID
+ * @param deviceType 设备类型
+ * @param state 通断状态，0：设备已添加；1：设备已被移除；1：设备已启用。
+ */
+#if TARGET_PLATFORM_DESKTOP
+ virtual void onDeviceChange(const char* deviceId, TRTCDeviceType type, TRTCDeviceState state) {
+ }
+#endif
- /**
- * 6.7 当前音频采集设备音量变化通知
- *
- * @note 使用 enableAudioVolumeEvaluation（interval>0）开启，（interval==0）关闭
- *
- * @param volume 音量值，取值范围0 - 100
- * @param muted 当前采集音频设备是否被静音，true：静音；false：取消静音
- */
- virtual void onAudioDeviceCaptureVolumeChanged(uint32_t volume, bool muted) {}
+/**
+ * 6.6 当前麦克风的系统采集音量发生变化
+ *
+ * 在 Mac 或 Windows 这样的桌面操作系统上，用户可以在设置中心找到声音相关的设置面板，并设置麦克风的采集音量大小。
+ * 用户将麦克风的采集音量设置得越大，麦克风采集到的声音的原始音量也就会越大，反之就会越小。
+ * 在有些型号的键盘以及笔记本电脑上，用户还可以通过按下“禁用麦克风”按钮（图标是一个话筒上上叠加了一道代表禁用的斜线）来将麦克风静音。
+ *
+ * 当用户通过系统设置界面或者通过键盘上的快捷键设定操作系统的麦克风采集音量时，SDK 便会抛出此事件。
+ *
+ * @note 您需要调用 {@link enableAudioVolumeEvaluation} 接口并设定（interval>0）开启次事件回调，设定（interval == 0）关闭此事件回调。
+ *
+ * @param volume 系统采集音量，取值范围 0 - 100，用户可以在系统的声音设置面板上进行拖拽调整。
+ * @param muted 麦克风是否被用户禁用了：true 被禁用，false 被启用。
+ */
+#if TARGET_PLATFORM_DESKTOP
+ virtual void onAudioDeviceCaptureVolumeChanged(uint32_t volume, bool muted) {
+ }
+#endif
- /**
- * 6.8 当前音频播放设备音量变化通知
- *
- * @note 使用 enableAudioVolumeEvaluation（interval>0）开启，（interval==0）关闭
- *
- * @param volume 音量值，取值范围0 - 100
- * @param muted 当前音频播放设备是否被静音，true：静音；false：取消静音
- */
- virtual void onAudioDevicePlayoutVolumeChanged(uint32_t volume, bool muted) {}
+/**
+ * 6.7 当前系统的播放音量发生变化
+ *
+ * 在 Mac 或 Windows 这样的桌面操作系统上，用户可以在设置中心找到声音相关的设置面板，并设置系统的播放音量大小。
+ * 在有些型号的键盘以及笔记本电脑上，用户还可以通过按下“静音”按钮（图标是一个喇叭上叠加了一道代表禁用的斜线）来将系统静音。
+ *
+ * 当用户通过系统设置界面或者通过键盘上的快捷键设定操作系统的播放音量时，SDK 便会抛出此事件。
+ *
+ * @note 您需要调用 {@link enableAudioVolumeEvaluation} 接口并设定（interval>0）开启次事件回调，设定（interval == 0）关闭此事件回调。
+ *
+ * @param volume 系统播放音量，取值范围 0 - 100，用户可以在系统的声音设置面板上进行拖拽调整。
+ * @param muted 系统是否被用户静音了：true 被静音，false 已恢复。
+ */
+#if TARGET_PLATFORM_DESKTOP
+ virtual void onAudioDevicePlayoutVolumeChanged(uint32_t volume, bool muted) {
+ }
#endif
-
+
+/**
+ * 6.8 系统声音采集是否被成功开启的事件回调（仅适用于 Mac 系统）
+ *
+ * 在 Mac 系统上，您可以通过调用 {@link startSystemAudioLoopback} 为当前系统安装一个音频驱动，并让 SDK 通过该音频驱动捕获当前 Mac 系统播放出的声音。
+ * 当用于播片教学或音乐直播中，比如老师端可以使用此功能，让 SDK 能够采集老师所播放的电影中的声音，使同房间的学生端也能听到电影中的声音。
+ * SDK 会将统声音采集是否被成功开启的结果，通过本事件回调抛出，需要您关注参数中的错误码。
+ *
+ * @param err ERR_NULL 表示成功，其余值表示失败。
+ */
#if TARGET_PLATFORM_MAC
- /**
- * 6.9 系统声音采集结果回调
- *
- * 系统声音采集接口 startSystemAudioLoopback 会触发这个回调
- *
- * @param errCode ERR_NULL 表示成功，其余值表示失败
- */
- virtual void onSystemAudioLoopbackError(TXLiteAVError errCode) {}
+ virtual void onSystemAudioLoopbackError(TXLiteAVError errCode) {
+ }
+#endif
+
+/**
+ * 6.9 测试麦克风时的音量回调
+ *
+ * 当您调用 {@link startMicDeviceTest} 测试麦克风是否正常工作时，SDK 会不断地抛出此回调，参数中的 volume 代表当前麦克风采集到的音量大小。
+ * 如果在测试期间 volume 出现了大小波动的情况，说明麦克风状态健康；如果 volume 的数值始终是 0，说明麦克风的状态异常，需要提示用户进行更换。
+ *
+ * @param volume 麦克风采集到的音量值，取值范围0 - 100
+ */
+#if TARGET_PLATFORM_DESKTOP
+ virtual void onTestMicVolume(uint32_t volume) {
+ }
#endif
- /// @}
+/**
+ * 6.10 测试扬声器时的音量回调
+ *
+ * 当您调用 {@link startSpeakerDeviceTest} 测试扬声器是否正常工作时，SDK 会不断地抛出此回调。
+ * 参数中的 volume 代表的是 SDK 提交给系统扬声器去播放的声音的音量值大小，如果该数值持续变化，但用户反馈听不到声音，则说明扬声器状态异常。
+ *
+ * @param volume SDK 提交给扬声器去播放的声音的音量，取值范围0 - 100
+ */
+#if TARGET_PLATFORM_DESKTOP
+ virtual void onTestSpeakerVolume(uint32_t volume) {
+ }
+#endif
+
+ /// @}
/////////////////////////////////////////////////////////////////////////////////
//
- // （七）自定义消息的接收回调
+ // 自定义消息的接收事件回调
//
/////////////////////////////////////////////////////////////////////////////////
- /// @name 自定义消息的接收回调
+ /// @name 自定义消息的接收事件回调
/// @{
+
/**
- * 7.1 收到自定义消息回调
+ * 7.1 收到自定义消息的事件回调
*
- * 当房间中的某个用户使用 sendCustomCmdMsg 发送自定义消息时，房间中的其它用户可以通过 onRecvCustomCmdMsg 接口接收消息
+ * 当房间中的某个用户使用 {@link sendCustomCmdMsg} 发送自定义 UDP 消息时，房间中的其它用户可以通过 onRecvCustomCmdMsg 事件回调接收到该条消息。
*
* @param userId 用户标识
* @param cmdID 命令 ID
* @param seq 消息序号
* @param message 消息数据
- * @param messageSize 消息数据大小
*/
- virtual void onRecvCustomCmdMsg(const char* userId, int32_t cmdID, uint32_t seq, const uint8_t* message, uint32_t messageSize) {}
+ virtual void onRecvCustomCmdMsg(const char* userId, int32_t cmdID, uint32_t seq, const uint8_t* message, uint32_t messageSize) {
+ }
/**
- * 7.2 自定义消息丢失回调
+ * 7.2 自定义消息丢失的事件回调
*
- * 实时音视频使用 UDP 通道，即使设置了可靠传输（reliable）也无法确保100@%不丢失，只是丢消息概率极低，能满足常规可靠性要求。
- * 在发送端设置了可靠传输（reliable）后，SDK 都会通过此回调通知过去时间段内（通常为5s）传输途中丢失的自定义消息数量统计信息。
+ * 当您使用 {@link sendCustomCmdMsg} 发送自定义 UDP 消息时，即使设置了可靠传输（reliable），也无法确保100@%不丢失，只是丢消息概率极低，能满足常规可靠性要求。
+ * 在发送端设置了可靠运输（reliable）后，SDK 都会通过此回调通知过去时间段内（通常为5s）传输途中丢失的自定义消息数量统计信息。
*
* @note 只有在发送端设置了可靠传输（reliable），接收方才能收到消息的丢失回调
* @param userId 用户标识
@@ -415,347 +537,448 @@ public:
* @param errCode 错误码
* @param missed 丢失的消息数量
*/
- virtual void onMissCustomCmdMsg(const char* userId, int32_t cmdID, int32_t errCode, int32_t missed) {}
+ virtual void onMissCustomCmdMsg(const char* userId, int32_t cmdID, int32_t errCode, int32_t missed) {
+ }
/**
* 7.3 收到 SEI 消息的回调
*
- * 当房间中的某个用户使用 sendSEIMsg 发送数据时，房间中的其它用户可以通过 onRecvSEIMsg 接口接收数据。
+ * 当房间中的某个用户使用 {@link sendSEIMsg} 借助视频数据帧发送 SEI 消息时，房间中的其它用户可以通过 onRecvSEIMsg 事件回调接收到该条消息。
*
* @param userId 用户标识
* @param message 数据
- * @param messageSize 数据大小
*/
- virtual void onRecvSEIMsg(const char* userId, const uint8_t* message, uint32_t messageSize) {};
- /// @}
+ virtual void onRecvSEIMsg(const char* userId, const uint8_t* message, uint32_t messageSize){};
+ /// @}
/////////////////////////////////////////////////////////////////////////////////
//
- // （八）CDN 旁路转推回调
+ // CDN 相关事件回调
//
/////////////////////////////////////////////////////////////////////////////////
- /// @name CDN 旁路转推回调
+ /// @name CDN 相关事件回调
/// @{
+
/**
- * 8.1 开始向腾讯云的直播 CDN 推流的回调，对应于 TRTCCloud 中的 startPublishing() 接口
+ * 8.1 开始向腾讯云直播 CDN 上发布音视频流的事件回调
+ *
+ * 当您调用 {@link startPublishing} 开始向腾讯云直播 CDN 上发布音视频流时，SDK 会立刻将这一指令同步给云端服务器。
+ * 随后 SDK 会收到来自云端服务器的处理结果，并将指令的执行结果通过本事件回调通知给您。
*
* @param err 0表示成功，其余值表示失败
* @param errMsg 具体错误原因
*/
- virtual void onStartPublishing(int err, const char *errMsg) {};
+ virtual void onStartPublishing(int err, const char* errMsg){};
/**
- * 8.2 停止向腾讯云的直播 CDN 推流的回调，对应于 TRTCCloud 中的 stopPublishing() 接口
+ * 8.2 停止向腾讯云直播 CDN 上发布音视频流的事件回调
+ *
+ * 当您调用 {@link stopPublishing} 停止向腾讯云直播 CDN 上发布音视频流时，SDK 会立刻将这一指令同步给云端服务器。
+ * 随后 SDK 会收到来自云端服务器的处理结果，并将指令的执行结果通过本事件回调通知给您。
*
* @param err 0表示成功，其余值表示失败
* @param errMsg 具体错误原因
*/
- virtual void onStopPublishing(int err, const char *errMsg) {};
+ virtual void onStopPublishing(int err, const char* errMsg){};
/**
- * 8.3 启动旁路推流到 CDN 完成的回调
+ * 8.3 开始向非腾讯云 CDN 上发布音视频流的事件回调
*
- * 对应于 TRTCCloud 中的 startPublishCDNStream() 接口
+ * 当您调用 {@link startPublishCDNStream} 开始向非腾讯云直播 CDN 上发布音视频流时，SDK 会立刻将这一指令同步给云端服务器。
+ * 随后 SDK 会收到来自云端服务器的处理结果，并将指令的执行结果通过本事件回调通知给您。
*
- * @note Start 回调如果成功，只能说明转推请求已经成功告知给腾讯云，如果目标 CDN 有异常，还是有可能会转推失败。
+ * @note 当您收到成功的事件回调时，只是说明您的发布指令已经同步到腾讯云后台服务器，但如果目标 CDN 厂商的服务器不接收该条视频流，依然可能导致发布失败。
+ * @param err 0表示成功，其余值表示失败
+ * @param errMsg 具体错误原因
*/
- virtual void onStartPublishCDNStream(int errCode, const char* errMsg) {};
+ virtual void onStartPublishCDNStream(int errCode, const char* errMsg){};
/**
- * 8.4 停止旁路推流到 CDN 完成的回调
+ * 8.4 停止向非腾讯云 CDN 上发布音视频流的事件回调
*
- * 对应于 TRTCCloud 中的 stopPublishCDNStream() 接口
+ * 当您调用 {@link stopPublishCDNStream} 开始向非腾讯云直播 CDN 上发布音视频流时，SDK 会立刻将这一指令同步给云端服务器。
+ * 随后 SDK 会收到来自云端服务器的处理结果，并将指令的执行结果通过本事件回调通知给您。
*
+ * @param err 0表示成功，其余值表示失败
+ * @param errMsg 具体错误原因
*/
- virtual void onStopPublishCDNStream(int errCode, const char* errMsg) {};
+ virtual void onStopPublishCDNStream(int errCode, const char* errMsg){};
/**
- * 8.5 设置云端的混流转码参数的回调，对应于 TRTCCloud 中的 setMixTranscodingConfig() 接口
+ * 8.5 设置云端混流的排版布局和转码参数的事件回调
*
- * @param errCode 0表示成功，其余值表示失败
- * @param errMsg 具体错误原因
+ * 当您调用 {@link setMixTranscodingConfig} 调整云端混流的排版布局和转码参数时，SDK 会立刻将这一调整指令同步给云端服务器。
+ * 随后 SDK 会收到来自云端服务器的处理结果，并将指令的执行结果通过本事件回调通知给您。
+ *
+ * @param err 错误码：0表示成功，其余值表示失败。
+ * @param errMsg 具体的错误原因。
*/
- virtual void onSetMixTranscodingConfig(int errCode, const char* errMsg) {};
- /// @}
+ virtual void onSetMixTranscodingConfig(int err, const char* errMsg){};
+ /// @}
/////////////////////////////////////////////////////////////////////////////////
//
- // （九）屏幕分享回调
- //
+ // 屏幕分享相关事件回调
//
/////////////////////////////////////////////////////////////////////////////////
- /// @name 屏幕分享回调
+ /// @name 屏幕分享相关事件回调
/// @{
-#ifdef _WIN32
- /**
- * 9.1 当屏幕分享窗口被遮挡无法正常捕获时，SDK 会通过此回调通知，可在此回调里通知用户移开遮挡窗口
- * 目前只支持Windows平台
- */
- virtual void onScreenCaptureCovered() {};
-#endif
- /**
- * 9.2 当屏幕分享开始时，SDK 会通过此回调通知
- */
- virtual void onScreenCaptureStarted() {};
/**
- * 9.3 当屏幕分享暂停时，SDK 会通过此回调通知
+ * 9.1 屏幕分享开启的事件回调
*
- * @param reason 停止原因，0：表示用户主动暂停；1：表示设置屏幕分享参数导致的暂停；2：表示屏幕分享窗口被最小化导致的暂停；3：表示屏幕分享窗口被隐藏导致的暂停
+ * 当您通过 {@link startScreenCapture} 等相关接口启动屏幕分享时，SDK 便会抛出此事件回调。
*/
- virtual void onScreenCapturePaused(int reason) {};
+ virtual void onScreenCaptureStarted(){};
/**
- * 9.4 当屏幕分享恢复时，SDK 会通过此回调通知
+ * 9.2 屏幕分享暂停的事件回调
*
- * @param reason 停止原因，0：表示用户主动恢复，1：表示屏幕分享参数设置完毕后自动恢复；2：表示屏幕分享窗口从最小化被恢复；3：表示屏幕分享窗口从隐藏被恢复
+ * 当您通过 {@link pauseScreenCapture} 暂停屏幕分享时，SDK 便会抛出此事件回调。
+ * @param reason 原因。
+ * - 0：用户主动暂停。
+ * - 1：注意此字段的含义在 MAC 和 Windows 平台有稍微差异。屏幕窗口不可见暂停（Mac）。表示设置屏幕分享参数导致的暂停（Windows）。
+ * - 2：表示屏幕分享窗口被最小化导致的暂停（仅 Windows）。
+ * - 3：表示屏幕分享窗口被隐藏导致的暂停（仅 Windows）。
*/
- virtual void onScreenCaptureResumed(int reason) {};
+ virtual void onScreenCapturePaused(int reason){};
/**
- * 9.5 当屏幕分享停止时，SDK 会通过此回调通知
+ * 9.3 屏幕分享恢复的事件回调
*
- * @param reason 停止原因，0：表示用户主动停止；1：表示屏幕分享窗口被关闭
+ * 当您通过 {@link resumeScreenCapture} 恢复屏幕分享时，SDK 便会抛出此事件回调。
+ * @param reason 恢复原因。
+ * - 0：用户主动恢复。
+ * - 1：注意此字段的含义在 MAC 和 Windows 平台有稍微差异。屏幕窗口恢复可见从而恢复分享（Mac）。屏幕分享参数设置完毕后自动恢复（Windows）
+ * - 2：表示屏幕分享窗口从最小化被恢复（仅 Windows）。
+ * - 3：表示屏幕分享窗口从隐藏被恢复（仅 Windows）。
*/
- virtual void onScreenCaptureStoped(int reason) {};
- /// @}
+ virtual void onScreenCaptureResumed(int reason){};
-
- /////////////////////////////////////////////////////////////////////////////////
- //
- // （十）截图回调
- //
- /////////////////////////////////////////////////////////////////////////////////
- /// @name 截图回调
- /// @{
- /**
- * 10.1 截图完成时回调
- *
- * @param userId 用户 ID，空字符串表示截取本地画面
- * @param type 视频流类型
- * @param data 截图数据，为 nullptr 表示截图失败
- * @param length 截图数据长度，对于BGRA32而言，length = width * height * 4
- * @param width 截图画面的宽度
- * @param height 截图画面的高度
- * @param format 截图数据格式，目前只支持 TRTCVideoPixelFormat_BGRA32
- */
- virtual void onSnapshotComplete(const char* userId, TRTCVideoStreamType type, char* data,
- uint32_t length, uint32_t width, uint32_t height,
- TRTCVideoPixelFormat format) {
- }
- /// @}
- /////////////////////////////////////////////////////////////////////////////////
- //
- // （十一）本地录制回调
- //
- /////////////////////////////////////////////////////////////////////////////////
- /// @name 本地录制回调
- /// @{
/**
- * 11.1 录制任务已经开始
+ * 9.4 屏幕分享停止的事件回调
*
- * @param errCode 错误码 0：初始化录制成功；-1：初始化录制失败；-2: 文件后缀名有误。
-
- * @param storagePath 录制文件存储路径
+ * 当您通过 {@link stopScreenCapture} 停止屏幕分享时，SDK 便会抛出此事件回调。
+ * @param reason 停止原因，0：用户主动停止；1：屏幕窗口关闭导致停止；2：表示屏幕分享的显示屏状态变更（如接口被拔出、投影模式变更等）。
*/
- virtual void onLocalRecordBegin(int errCode, const char* storagePath) {}
+ virtual void onScreenCaptureStoped(int reason){};
- /**
- * 11.2 录制任务进行中
- * @param duration 已经录制的累计时长，单位毫秒
- * @param storagePath 录制文件存储路径
- */
- virtual void onLocalRecording(long duration, const char* storagePath) {}
- /**
- * 11.3 录制任务已结束
- *
- * @param errCode 错误码 0：录制成功；-1：录制失败；-2：切换分辨率或横竖屏导致录制结束。
+/**
+ * 9.5 屏幕分享的目标窗口被遮挡的事件回调（仅适用于 Windows 操作系统）
+ *
+ * 当屏幕分享的目标窗口被遮挡无法正常捕获时，SDK 会抛出此事件回调，你可以在捕获到该事件回调后，通过 UI 上的一些变化来提示用户移开遮盖窗口。
+ */
+#ifdef _WIN32
+ virtual void onScreenCaptureCovered(){};
+#endif
- * @param storagePath 录制文件存储路径
- */
- virtual void onLocalRecordComplete(int errCode, const char* storagePath) {}
/// @}
-
/////////////////////////////////////////////////////////////////////////////////
//
- // （十二）Windows 专有废弃方法
+ // 本地录制和本地截图的事件回调
//
/////////////////////////////////////////////////////////////////////////////////
- /// @name Windows 专有废弃方法
+ /// @name 本地录制和本地截图的事件回调
/// @{
-#ifdef _WIN32
+
/**
- * 11.1 废弃接口：有主播加入当前房间
+ * 10.1 本地录制任务已经开始的事件回调
*
- * 该回调接口可以被看作是 onRemoteUserEnterRoom 的废弃版本，不推荐使用。请使用 onUserVideoAvailable 或 onRemoteUserEnterRoom 进行替代。
- *
- * @note 该接口已被废弃，不推荐使用
- *
- * @param userId 用户标识
+ * 当您调用 {@link startLocalRecording} 启动本地媒体录制任务时，SDK 会抛出该事件回调，用于通知您录制任务是否已经顺利启动。
+ * @param errCode 错误码 0：初始化录制成功；-1：初始化录制失败；-2: 文件后缀名有误。
+ * @param storagePath 录制文件存储路径
*/
- virtual __declspec(deprecated("use onRemoteUserEnterRoom instead"))
- void onUserEnter(const char* userId) {}
+ virtual void onLocalRecordBegin(int errCode, const char* storagePath) {
+ }
/**
- * 11.2 废弃接口：有主播离开当前房间
- *
- * 该回调接口可以被看作是 onRemoteUserLeaveRoom 的废弃版本，不推荐使用。请使用 onUserVideoAvailable 或 onRemoteUserLeaveRoom 进行替代。
+ * 10.2 本地录制任务正在进行中的进展事件回调
*
- * @note 该接口已被废弃，不推荐使用
+ * 当您调用 {@link startLocalRecording} 成功启动本地媒体录制任务后，SDK 变会定时地抛出本事件回调。
+ * 您可通过捕获该事件回调来获知录制任务的健康状况。
+ * 您可以在 {@link startLocalRecording} 时设定本事件回调的抛出间隔。
*
- * @param userId 用户标识
- * @param reason 离开原因。
+ * @param duration 已经录制的累计时长，单位毫秒
+ * @param storagePath 录制文件存储路径
*/
- virtual __declspec(deprecated("use onRemoteUserLeaveRoom instead"))
- void onUserExit(const char* userId, int reason) {}
+ virtual void onLocalRecording(long duration, const char* storagePath) {
+ }
/**
- * 11.3 废弃接口：播放音效结束回调
+ * 10.3 本地录制任务已经结束的事件回调
*
- * @param effectId 音效id
- * @param code 0表示播放正常结束；其他表示异常结束
+ * 当您调用 {@link stopLocalRecording} 停止本地媒体录制任务时，SDK 会抛出该事件回调，用于通知您录制任务的最终结果。
+ * @param errCode 错误码 0：录制成功；-1：录制失败；-2：切换分辨率或横竖屏导致录制结束。
+ * @param storagePath 录制文件存储路径
*/
- virtual __declspec(deprecated("use ITXAudioEffectManager.startPlayMusic instead"))
- void onAudioEffectFinished(int effectId, int code) {};
+ virtual void onLocalRecordComplete(int errCode, const char* storagePath) {
+ }
/**
- * 11.4 废弃接口：开始播放背景音乐
+ * 10.4 本地截图完成的事件回调
*
- * @param errCode 错误码
+ * @param userId 用户标识，如果 userId 为空字符串，则代表截取的是本地画面。
+ * @param type 视频流类型
+ * @param data 截图数据，为 nullptr 表示截图失败
+ * @param length 截图数据长度，对于BGRA32而言，length = width * height * 4
+ * @param width 截图画面的宽度
+ * @param height 截图画面的高度
+ * @param format 截图数据格式，目前只支持 TRTCVideoPixelFormat_BGRA32
*/
- virtual __declspec(deprecated("use ITXAudioEffectManager.ITXMusicPlayObserver instead"))
- void onPlayBGMBegin(TXLiteAVError errCode) {}
+ virtual void onSnapshotComplete(const char* userId, TRTCVideoStreamType type, char* data, uint32_t length, uint32_t width, uint32_t height, TRTCVideoPixelFormat format) {
+ }
- /**
- * 11.5 废弃接口：播放背景音乐的进度
- *
- * @param progressMS 已播放时间
- * @param durationMS 总时间
- */
- virtual __declspec(deprecated("use ITXAudioEffectManager.ITXMusicPlayObserver instead"))
- void onPlayBGMProgress(uint32_t progressMS, uint32_t durationMS) {}
+/// @}
+/////////////////////////////////////////////////////////////////////////////////
+//
+// 废弃的事件回调（建议使用对应的新回调）
+//
+/////////////////////////////////////////////////////////////////////////////////
+/// @name 废弃的事件回调（建议使用对应的新回调）
+/// @{
+
+/**
+ * 有主播加入当前房间（已废弃）
+ *
+ * @deprecated 新版本开始不推荐使用，建议使用 {@link onRemoteUserEnterRoom} 替代之。
+ */
+#ifdef _WIN32
+ virtual __declspec(deprecated("use onRemoteUserEnterRoom instead")) void onUserEnter(const char* userId) {
+ }
+#endif
+
+/**
+ * 有主播离开当前房间（已废弃）
+ *
+ * @deprecated 新版本开始不推荐使用，建议使用 {@link onRemoteUserLeaveRoom} 替代之。
+ */
+#ifdef _WIN32
+ virtual __declspec(deprecated("use onRemoteUserLeaveRoom instead")) void onUserExit(const char* userId, int reason) {
+ }
+#endif
+
+/**
+ * 音效播放已结束（已废弃）
+ *
+ * @deprecated 新版本开始不推荐使用，建议使用 {@link ITXAudioEffectManager} 接口替代之。
+ * 新的接口中不再区分背景音乐和音效，而是统一用 {@link startPlayMusic} 取代之。
+ */
+#ifdef _WIN32
+ virtual __declspec(deprecated("use ITXAudioEffectManager.ITXMusicPlayObserver instead")) void onAudioEffectFinished(int effectId, int code){};
+#endif
+
+/**
+ * 开始播放背景音乐（已废弃）
+ *
+ * @deprecated 新版本开始不推荐使用，建议使用 {@link ITXMusicPlayObserver} 接口替代之。
+ * 新的接口中不再区分背景音乐和音效，而是统一用 {@link startPlayMusic} 取代之。
+ */
+#ifdef _WIN32
+ virtual __declspec(deprecated("use ITXAudioEffectManager.ITXMusicPlayObserver instead")) void onPlayBGMBegin(TXLiteAVError errCode) {
+ }
+#endif
+
+/**
+ * 背景音乐的播放进度回调（已废弃）
+ *
+ * @deprecated 新版本开始不推荐使用，建议使用 {@link ITXMusicPlayObserver} 接口替代之。
+ * 新的接口中不再区分背景音乐和音效，而是统一用 {@link startPlayMusic} 取代之。
+ */
+#ifdef _WIN32
+ virtual __declspec(deprecated("use ITXAudioEffectManager.ITXMusicPlayObserver instead")) void onPlayBGMProgress(uint32_t progressMS, uint32_t durationMS) {
+ }
+#endif
+
+/**
+ * 背景音乐播放已经结束（已废弃）
+ *
+ * @deprecated 新版本开始不推荐使用，建议使用 {@link ITXMusicPlayObserver} 接口替代之。
+ * 新的接口中不再区分背景音乐和音效，而是统一用 {@link startPlayMusic} 取代之。
+ */
+#ifdef _WIN32
+ virtual __declspec(deprecated("use ITXAudioEffectManager.ITXMusicPlayObserver instead")) void onPlayBGMComplete(TXLiteAVError errCode) {
+ }
+#endif
- /**
- * 11.6 废弃接口：播放背景音乐结束
- *
- * @param errCode 错误码
- */
- virtual __declspec(deprecated("use ITXAudioEffectManager.ITXMusicPlayObserver instead"))
- void onPlayBGMComplete(TXLiteAVError errCode) {}
-#endif // _WIN32
/// @}
-};
+}; // End of interface ITRTCCloudCallback
/////////////////////////////////////////////////////////////////////////////////
//
-// （十三）自定义视频渲染回调
+// 视频数据自定义回调
//
/////////////////////////////////////////////////////////////////////////////////
+/// @name 视频数据自定义回调
+/// @{
+
+class ITRTCVideoRenderCallback {
+ public:
+ virtual ~ITRTCVideoRenderCallback() {
+ }
+
+ /**
+ * 自定义视频渲染回调
+ *
+ * 当您设置了本地或者远端的视频自定义渲染回调之后，SDK 就会将原本要交给渲染控件进行渲染的视频帧通过此回调接口抛送给您，以便于您进行自定义渲染。
+ * @param frame 待渲染的视频帧信息
+ * @param userId 视频源的 userId，如果是本地视频回调（setLocalVideoRenderDelegate），该参数可以忽略
+ * @param streamType 频流类型：主路（Main）一般用于承载摄像头画面，辅路（Sub）一般用于承载屏幕分享画面。
+ */
+ virtual void onRenderVideoFrame(const char* userId, TRTCVideoStreamType streamType, TRTCVideoFrame* frame) {
+ }
+
+}; // End of interface ITRTCVideoRenderCallback
+
+class ITRTCVideoFrameCallback {
+ public:
+ virtual ~ITRTCVideoFrameCallback() {
+ }
-/// 自定义视频渲染回调
-class ITRTCVideoRenderCallback
-{
-public:
- virtual ~ITRTCVideoRenderCallback() {}
/**
- * 12.1 自定义视频渲染回调
+ * 用于对接第三方美颜组件的视频处理回调
+ *
+ * 如果您选购了第三方美颜组件，就需要在 TRTCCloud 中设置第三方美颜回调，之后 TRTC 就会将原本要进行预处理的视频帧通过此回调接口抛送给您。
+ * 之后您就可以将 TRTC 抛出的视频帧交给第三方美颜组件进行图像处理，由于抛出的数据是可读且可写的，因此第三方美颜的处理结果也可以同步给 TRTC 进行后续的编码和发送。
*
- * 可以通过 setLocalVideoRenderCallback 和 setRemoteVideoRenderCallback 接口设置自定义渲染回调
+ * @param srcFrame 用于承载 TRTC 采集到的摄像头画面
+ * @param dstFrame 用于接收第三方美颜处理过的视频画面
+ * @note 目前仅支持 OpenGL 纹理方案（ PC 仅支持 TRTCVideoBufferType_Buffer 格式）。
*
- * @param userId 用户标识
- * @param streamType 流类型：即摄像头还是屏幕分享
- * @param frame 视频帧数据
+ * 情况一：美颜组件自身会产生新的纹理
+ * 如果您使用的美颜组件会在处理图像的过程中产生一帧全新的纹理（用于承载处理后的图像），那请您在回调函数中将 dstFrame.textureId 设置为新纹理的 ID：
*
- * @note - 在iOS和Mac平台上回调的视频帧为TRTCVideoBufferType_Buffer类型
+ * 情况二：美颜组件需要您提供目标纹理
+ * 如果您使用的第三方美颜模块并不生成新的纹理，而是需要您设置给该模块一个输入纹理和一个输出纹理，则可以考虑如下方案：
+ * ```ObjectiveC
+ * uint32_t onProcessVideoFrame(TRTCVideoFrame * _Nonnull)srcFrame dstFrame:(TRTCVideoFrame * _Nonnull)dstFrame{
+ * thirdparty_process(srcFrame.textureId, srcFrame.width, srcFrame.height, dstFrame.textureId);
+ * return 0;
+ * }
+ * ```
+ * ```java
+ * int onProcessVideoFrame(TRTCCloudDef.TRTCVideoFrame srcFrame, TRTCCloudDef.TRTCVideoFrame dstFrame) {
+ * thirdparty_process(srcFrame.texture.textureId, srcFrame.width, srcFrame.height, dstFrame.texture.textureId);
+ * return 0;
+ * }
+ * ```
*/
- virtual void onRenderVideoFrame(const char* userId, TRTCVideoStreamType streamType, TRTCVideoFrame* frame) {}
-};
+ virtual int onProcessVideoFrame(TRTCVideoFrame* srcFrame, TRTCVideoFrame* dstFrame) {
+ return 0;
+ }
+}; // End of class ITRTCVideoFrameCallback
+
+/// @}
/////////////////////////////////////////////////////////////////////////////////
//
-// （十四）音频数据回调
+// 音频数据自定义回调
//
/////////////////////////////////////////////////////////////////////////////////
+/// @name 音频数据自定义回调
+/// @{
+
+class ITRTCAudioFrameCallback {
+ public:
+ virtual ~ITRTCAudioFrameCallback() {
+ }
-/// 音频数据回调
-class ITRTCAudioFrameCallback
-{
-public:
- virtual ~ITRTCAudioFrameCallback() {}
/**
- * 13.1 本地麦克风采集到的音频数据回调
+ * 本地麦克风采集到的原始音频数据回调
*
- * @param frame 音频数据
- * @note - 请不要在此回调函数中做任何耗时操作，建议直接拷贝到另一线程进行处理，否则会导致各种声音问题。
- * @note - 此接口回调出的音频数据支持修改。
- * @note - 此接口回调出的音频时间帧长固定为0.02s。
- 由时间帧长转化为字节帧长的公式为【采样率 × 时间帧长 × 声道数 × 采样点位宽】。
- 以SDK默认的音频录制格式48000采样率、单声道、16采样点位宽为例，字节帧长为【48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节】。
- * @note - 此接口回调出的音频数据包含背景音、音效、混响等前处理效果。
+ * 当您设置完音频数据自定义回调之后，SDK 内部会把刚从麦克风采集到的原始音频数据，以 PCM 格式的形式通过本接口回调给您。
+ * - 此接口回调出的音频时间帧长固定为0.02s，格式为 PCM 格式。
+ * - 由时间帧长转化为字节帧长的公式为【采样率 × 时间帧长 × 声道数 × 采样点位宽】。
+ * - 以 TRTC 默认的音频录制格式48000采样率、单声道、16采样点位宽为例，字节帧长为【48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节】。
+ *
+ * @param frame PCM 格式的音频数据帧
+ * @note
+ * 1. 请不要在此回调函数中做任何耗时操作，由于 SDK 每隔 20ms 就要处理一帧音频数据，如果您的处理时间超过 20ms，就会导致声音异常。
+ * 2. 此接口回调出的音频数据是可读写的，也就是说您可以在回调函数中同步修改音频数据，但请保证处理耗时。
+ * 3. 此接口回调出的音频数据**不包含**背景音、音效、混响等前处理效果，延迟极低。
*/
- virtual void onCapturedAudioFrame(TRTCAudioFrame *frame) {};
+ virtual void onCapturedRawAudioFrame(TRTCAudioFrame* frame){};
-#if TARGET_PLATFORM_PHONE
/**
- * 13.2 本地采集并经过音频模块前处理后的音频数据回调
+ * 本地采集并经过音频模块前处理后的音频数据回调
+ *
+ * 当您设置完音频数据自定义回调之后，SDK 内部会把刚采集到并经过前处理(ANS、AEC、AGC）之后的数据，以 PCM 格式的形式通过本接口回调给您。
+ * - 此接口回调出的音频时间帧长固定为0.02s，格式为 PCM 格式。
+ * - 由时间帧长转化为字节帧长的公式为【采样率 × 时间帧长 × 声道数 × 采样点位宽】。
+ * - 以 TRTC 默认的音频录制格式48000采样率、单声道、16采样点位宽为例，字节帧长为【48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节】。
*
- * @param frame 音频数据
- * @note - 请不要在此回调函数中做任何耗时操作，建议直接拷贝到另一线程进行处理，否则会导致各种声音问题。
- * @note - 此接口回调出的音频数据包含背景音、音效、混响等前处理效果，延迟较高。
- * @note - 此接口回调出的音频数据支持修改。
- * @note - 此接口回调出的音频时间帧长固定为0.02s。
- 由时间帧长转化为字节帧长的公式为【采样率 × 时间帧长 × 声道数 × 采样点位宽】。
- 以SDK默认的音频录制格式48000采样率、单声道、16采样点位宽为例，字节帧长为【48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节】。
+ * 特殊说明：
+ * 您可以通过设置接口中的 `TRTCAudioFrame.extraData` 字段，达到传输信令的目的。
+ * 由于音频帧头部的数据块不能太大，建议您写入 `extraData` 时，尽量将信令控制在几个字节的大小，如果超过 100 个字节，写入的数据不会被发送。
+ * 房间内其他用户可以通过 {@link TRTCAudioFrameDelegate} 中的 `onRemoteUserAudioFrame` 中的 `TRTCAudioFrame.extraData` 字段回调接收数据。
+ *
+ * @param frame PCM 格式的音频数据帧
+ * @note
+ * 1. 请不要在此回调函数中做任何耗时操作，由于 SDK 每隔 20ms 就要处理一帧音频数据，如果您的处理时间超过 20ms，就会导致声音异常。
+ * 2. 此接口回调出的音频数据是可读写的，也就是说您可以在回调函数中同步修改音频数据，但请保证处理耗时。
+ * 3. 此接口回调出的数据已经经过了回声抑制（AEC）处理，但声音的延迟相比于 {@link onCapturedRawAudioFrame} 要高一些。
*/
- virtual void onLocalProcessedAudioFrame(TRTCAudioFrame *frame) {};
-#endif
+ virtual void onLocalProcessedAudioFrame(TRTCAudioFrame* frame){};
/**
- * 13.3 混音前的每一路远程用户的音频数据（例如您要对某一路的语音进行文字转换，必须要使用这里的原始数据，而不是混音之后的数据）
+ * 混音前的每一路远程用户的音频数据
+ *
+ * 当您设置完音频数据自定义回调之后，SDK 内部会把远端的每一路原始数据，在最终混音之前，以 PCM 格式的形式通过本接口回调给您。
+ * - 此接口回调出的音频时间帧长固定为0.02s，格式为 PCM 格式。
+ * - 由时间帧长转化为字节帧长的公式为【采样率 × 时间帧长 × 声道数 × 采样点位宽】。
+ * - 以 TRTC 默认的音频录制格式48000采样率、单声道、16采样点位宽为例，字节帧长为【48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节】。
*
- * @param frame 音频数据
- * @param userId 用户标识
- * @note - 请不要在此回调函数中做任何耗时操作，建议直接拷贝到另一线程进行处理，否则会导致各种声音问题。
- * - 此接口回调出的音频数据是只读的，不支持修改。
+ * @param frame PCM 格式的音频数据帧
+ * @param userId 用户标识
+ * @note 此接口回调出的音频数据是只读的，不支持修改
*/
- virtual void onPlayAudioFrame(TRTCAudioFrame *frame, const char* userId) {};
+ virtual void onPlayAudioFrame(TRTCAudioFrame* frame, const char* userId){};
/**
- * 13.4 各路音频数据混合后送入喇叭播放的音频数据
+ * 将各路待播放音频混合之后并在最终提交系统播放之前的数据回调
+ *
+ * 当您设置完音频数据自定义回调之后，SDK 内部会把各路待播放的音频混合之后的音频数据，在提交系统播放之前，以 PCM 格式的形式通过本接口回调给您。
+ * - 此接口回调出的音频时间帧长固定为0.02s，格式为 PCM 格式。
+ * - 由时间帧长转化为字节帧长的公式为【采样率 × 时间帧长 × 声道数 × 采样点位宽】。
+ * - 以 TRTC 默认的音频录制格式48000采样率、单声道、16采样点位宽为例，字节帧长为【48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节】。
*
- * @param frame 音频数据
- * @note - 请不要在此回调函数中做任何耗时操作，建议直接拷贝到另一线程进行处理，否则会导致各种声音问题。
- * @note - 此接口回调出的音频数据支持修改。
- * @note - 此接口回调出的音频时间帧长固定为0.02s。
- 由时间帧长转化为字节帧长的公式为【采样率 × 时间帧长 × 声道数 × 采样点位宽】。
- 以SDK默认的音频播放格式48000采样率、双声道、16采样点位宽为例，字节帧长为【48000 × 0.02s × 2 × 16bit = 30720bit = 3840字节】。
- * @note - 此接口回调出的音频数据是各路音频播放数据的混合,不包含耳返的音频数据。
+ * @param frame PCM 格式的音频数据帧
+ * @note
+ * 1. 请不要在此回调函数中做任何耗时操作，由于 SDK 每隔 20ms 就要处理一帧音频数据，如果您的处理时间超过 20ms，就会导致声音异常。
+ * 2. 此接口回调出的音频数据是可读写的，也就是说您可以在回调函数中同步修改音频数据，但请保证处理耗时。
+ * 3. 此接口回调出的是对各路待播放音频数据的混合，但其中并不包含耳返的音频数据。
*/
- virtual void onMixedPlayAudioFrame(TRTCAudioFrame *frame) {};
-};
+ virtual void onMixedPlayAudioFrame(TRTCAudioFrame* frame){};
+}; // End of interface ITRTCAudioFrameCallback
+
+/// @}
/////////////////////////////////////////////////////////////////////////////////
//
-// （十五）Log 信息回调
+// 更多事件回调接口
//
/////////////////////////////////////////////////////////////////////////////////
+/// @name 更多事件回调接口
+/// @{
+
+class ITRTCLogCallback {
+ public:
+ virtual ~ITRTCLogCallback() {
+ }
-/// 日志相关回调
-class ITRTCLogCallback
-{
-public:
- virtual ~ITRTCLogCallback() {}
/**
- * 14.1 有日志打印时的回调
+ * 本地 LOG 的打印回调
*
+ * 如果您希望捕获 SDK 的本地日志打印行为，可以通过设置日志回调，让 SDK 将要打印的日志都通过本回调接口抛送给您。
* @param log 日志内容
- * @param level 日志等级 参见 TRTCLogLevel
- * @param module 暂无具体意义，目前为固定值 TXLiteAVSDK
+ * @param level 日志等级 参见 TRTC_LOG_LEVEL
+ * @param module 保留字段，暂无具体意义，目前为固定值 TXLiteAVSDK
*/
- virtual void onLog(const char* log, TRTCLogLevel level, const char* module) {}
-};
+ virtual void onLog(const char* log, TRTCLogLevel level, const char* module) {
+ }
-/// @}
-}
+}; // End of interface ITRTCLogCallback
-#endif /* __TRTCENGINECALLBACK_H__ */
+/// @}
+} /* namespace liteav*/
+#endif /* __TRTCCLOUDCALLBACK_H__ */
+/// @}
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/cpp_interface/TRTCTypeDef.h b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/cpp_interface/TRTCTypeDef.h
index e4f83cc..a42a3f7 100644
--- a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/cpp_interface/TRTCTypeDef.h
+++ b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/cpp_interface/TRTCTypeDef.h
@@ -1,10 +1,10 @@
-/*
+/**
* Module: TRTC 关键类型定义
- *
* Function: 分辨率、质量等级等枚举和常量值的定义
- *
*/
-
+/// @defgroup TRTCCloudDef_cplusplus 关键类型定义
+/// 腾讯云实时音视频的关键类型定义
+/// @{
#ifndef __TRTCTYPEDEF_H__
#define __TRTCTYPEDEF_H__
@@ -31,799 +31,1052 @@
#define TRTC_API
#endif
-#define TARGET_PLATFORM_DESKTOP (__APPLE__ && TARGET_OS_MAC && !TARGET_OS_IPHONE) || _WIN32
-#define TARGET_PLATFORM_PHONE __ANDROID__ || (__APPLE__ && TARGET_OS_IOS)
-#define TARGET_PLATFORM_MAC __APPLE__ && TARGET_OS_MAC && !TARGET_OS_IPHONE
+#define TARGET_PLATFORM_DESKTOP ((__APPLE__ && TARGET_OS_MAC && !TARGET_OS_IPHONE) || _WIN32)
+#define TARGET_PLATFORM_PHONE (__ANDROID__ || (__APPLE__ && TARGET_OS_IOS))
+#define TARGET_PLATFORM_MAC (__APPLE__ && TARGET_OS_MAC && !TARGET_OS_IPHONE)
+
+namespace liteav {
-namespace trtc {
+/// @{
+
+#ifndef _WIN32
+struct RECT {
+ int left = 0;
+ int top = 0;
+ int right = 0;
+ int bottom = 0;
+};
+struct SIZE {
+ long width = 0;
+ long height = 0;
+};
+#endif
+
+/////////////////////////////////////////////////////////////////////////////////
+//
+// 渲染控件
+//
+/////////////////////////////////////////////////////////////////////////////////
/**
- * 渲染控件
+ * [VIEW] 用于渲染视频画面的渲染控件
*
- * TXView 根据编译平台的不同，做不同的类型转换，来保证兼容性
- * Windows 平台：请传入渲染控件的 HWND;
- * iOS 平台：请传入 UIView 对象的指针（需强转为 void * 类型）;
- * Mac 平台：请传入 NSView 对象的指针（需强转为 void * 类型）;
- * Android 平台：请传入指向 TXCloudVideoView 对象的 jobject 指针（需强转为 void * 类型）;
+ * TRTC 中有很多需要操控视频画面的接口，这些接口都需要您指定视频渲染控件，SDK 为不同的终端平台提供了配套的渲染控件。
+ * 由于全平台 C++ 接口需要使用统一的参数类型，所以您需要在调用这些接口时，将渲染控件统一转换成 TXView 类型的指针：
+ * - iOS 平台：您可以使用 UIView 对象作为渲染控件，在调用 C++ 接口时请传入 UIView 对象的指针（需强转为 void* 类型）。
+ * - Mac 平台：您可以使用 NSView 对象作为渲染控件，在调用 C++ 接口时请传入 NSView 对象的指针（需强转为 void* 类型）。
+ * - Android 平台：在调用 C++ 接口时请传入指向 TXCloudVideoView 对象的 jobject 指针（需强转为 void* 类型）。
+ * - Windows 平台：您可以使用窗口句柄 HWND 作为渲染控件，在调用 C++ 接口时需要将 HWND 强转为 void* 类型。
*
- * iOS、Windows、Mac 代码示例：
- * <pre>
- * //以基于 QT 通过 C++ 接口进行 iOS、Windows、Mac 开发，调用 startRemoteView 为例
- * QWidget *videoView; //此处省略设置 videoView 属性的代码
- * getTRTCShareInstance()->startRemoteView(userId, TRTCVideoStreamTypeBig, reinterpret_cast<TXView>(videoView->winId()));
+ * 代码示例一：在 QT 下使用 C++ 全平台接口
* <pre>
+ * QWidget *videoView;
+ * // The relevant code for setting the videoView is omitted here...
+ * getTRTCShareInstance()->startLocalPreview(reinterpret_cast<TXView>(videoView->winId()));
+ * </pre>
*
- * Android 代码示例：
+ * 代码示例二：在 Android 平台下，通过 JNI 调用 C++ 全平台接口
* <pre>
- * //以基于 Android Studio 通过 C++ 接口进行 Android 开发，调用 startRemoteView 为例
- * //声明 native 方法，形参类型为 TXCloudVideoView
- * native void nativeStartRemoteView(String userId, int streamType, TXCloudVideoView view);
- * //在 native 方法的实现中，C++ 层可以获取到 jobject 类型的 TXCloudVideoView 对象
- * Java_com_example_test_MainActivity_nativeStartRemoteView(JNIEnv *env, jobject thiz, jstring user_id, jint stream_type, jobject view) {
+ * native void nativeStartLocalPreview(String userId, int streamType, TXCloudVideoView view);
+ * //...
+ * Java_com_example_test_MainActivity_nativeStartRemoteView(JNIEnv *env, jobject thiz, jstring user_id, jint stream_type, jobject view) {
* const char *user_id_chars = env->GetStringUTFChars(user_id, nullptr);
- * trtc_cloud->startRemoteView(user_id_chars, (trtc::TRTCVideoStreamType)stream_type, view);
+ * trtc_cloud->startRemoteView(user_id_chars, (liteav::TRTCVideoStreamType)stream_type, view);
* env->ReleaseStringUTFChars(user_id, user_id_chars);
- * }
- * <pre>
+ * }
+ * </pre>
*/
#ifdef _WIN32
+// Windows: HWND
typedef HWND TXView;
#else
-typedef void * TXView;
+// iOS: UIView; Mac OS: NSView; Android: jobject of TXCloudVideoView
+typedef void *TXView;
#endif
-/**
- * 窗口尺寸和位置结构体
- */
-#ifndef _WIN32
-struct RECT {
- int left = 0;
- int top = 0;
- int right = 0;
- int bottom = 0;
-};
-
-struct SIZE
-{
- long width = 0;
- long height = 0;
-};
-#endif
-
-/// @defgroup TRTCTypeDef_cplusplus 关键类型定义
-/// 腾讯云视频通话功能的关键类型定义
-/// @{
/////////////////////////////////////////////////////////////////////////////////
//
-// 【（一）视频相关枚举值定义】
+// 视频相关枚举值定义
//
/////////////////////////////////////////////////////////////////////////////////
/**
* 1.1 视频分辨率
*
- * 此处仅定义横屏分辨率，如需使用竖屏分辨率（例如360 × 640），需要同时指定 TRTCVideoResolutionMode 为 Portrait。
+ * 此处仅定义横屏分辨率（如 640 × 360），如需使用竖屏分辨率（如360 × 640），需要同时指定 TRTCVideoResolutionMode 为 Portrait。
*/
-enum TRTCVideoResolution
-{
- // 宽高比1:1
- TRTCVideoResolution_120_120 = 1, ///< [C] 建议码率80kbps
- TRTCVideoResolution_160_160 = 3, ///< [C] 建议码率100kbps
- TRTCVideoResolution_270_270 = 5, ///< [C] 建议码率200kbps
- TRTCVideoResolution_480_480 = 7, ///< [C] 建议码率350kbps
-
- // 宽高比4:3
- TRTCVideoResolution_160_120 = 50, ///< [C] 建议码率100kbps
- TRTCVideoResolution_240_180 = 52, ///< [C] 建议码率150kbps
- TRTCVideoResolution_280_210 = 54, ///< [C] 建议码率200kbps
- TRTCVideoResolution_320_240 = 56, ///< [C] 建议码率250kbps
- TRTCVideoResolution_400_300 = 58, ///< [C] 建议码率300kbps
- TRTCVideoResolution_480_360 = 60, ///< [C] 建议码率400kbps
- TRTCVideoResolution_640_480 = 62, ///< [C] 建议码率600kbps
- TRTCVideoResolution_960_720 = 64, ///< [C] 建议码率1000kbps
-
- // 宽高比16:9
- TRTCVideoResolution_160_90 = 100, ///< [C] 建议码率150kbps
- TRTCVideoResolution_256_144 = 102, ///< [C] 建议码率200kbps
- TRTCVideoResolution_320_180 = 104, ///< [C] 建议码率250kbps
- TRTCVideoResolution_480_270 = 106, ///< [C] 建议码率350kbps
- TRTCVideoResolution_640_360 = 108, ///< [C] 建议码率550kbps
- TRTCVideoResolution_960_540 = 110, ///< [C] 建议码率850kbps
- TRTCVideoResolution_1280_720 = 112, ///< [C] 摄像头采集 - 建议码率1200kbps
- ///< [S] 屏幕分享 - 建议码率：低清：1000kbps 高清：1600kbps
- TRTCVideoResolution_1920_1080 = 114, ///< [S] 屏幕分享 - 建议码率2000kbps
+enum TRTCVideoResolution {
+
+ ///宽高比 1:1；分辨率 120x120；建议码率（VideoCall）80kbps; 建议码率（LIVE）120kbps。
+ TRTCVideoResolution_120_120 = 1,
+
+ ///宽高比 1:1 分辨率 160x160；建议码率（VideoCall）100kbps; 建议码率（LIVE）150kbps。
+ TRTCVideoResolution_160_160 = 3,
+
+ ///宽高比 1:1；分辨率 270x270；建议码率（VideoCall）200kbps; 建议码率（LIVE）300kbps。
+ TRTCVideoResolution_270_270 = 5,
+
+ ///宽高比 1:1；分辨率 480x480；建议码率（VideoCall）350kbps; 建议码率（LIVE）500kbps。
+ TRTCVideoResolution_480_480 = 7,
+
+ ///宽高比4:3；分辨率 160x120；建议码率（VideoCall）100kbps; 建议码率（LIVE）150kbps。
+ TRTCVideoResolution_160_120 = 50,
+
+ ///宽高比 4:3；分辨率 240x180；建议码率（VideoCall）150kbps; 建议码率（LIVE）250kbps。
+ TRTCVideoResolution_240_180 = 52,
+
+ ///宽高比 4:3；分辨率 280x210；建议码率（VideoCall）200kbps; 建议码率（LIVE）300kbps。
+ TRTCVideoResolution_280_210 = 54,
+
+ ///宽高比 4:3；分辨率 320x240；建议码率（VideoCall）250kbps; 建议码率（LIVE）375kbps。
+ TRTCVideoResolution_320_240 = 56,
+
+ ///宽高比 4:3；分辨率 400x300；建议码率（VideoCall）300kbps; 建议码率（LIVE）450kbps。
+ TRTCVideoResolution_400_300 = 58,
+
+ ///宽高比 4:3；分辨率 480x360；建议码率（VideoCall）400kbps; 建议码率（LIVE）600kbps。
+ TRTCVideoResolution_480_360 = 60,
+
+ ///宽高比 4:3；分辨率 640x480；建议码率（VideoCall）600kbps; 建议码率（LIVE）900kbps。
+ TRTCVideoResolution_640_480 = 62,
+
+ ///宽高比 4:3；分辨率 960x720；建议码率（VideoCall）1000kbps; 建议码率（LIVE）1500kbps。
+ TRTCVideoResolution_960_720 = 64,
+
+ ///宽高比 16:9；分辨率 160x90；建议码率（VideoCall）150kbps; 建议码率（LIVE）250kbps。
+ TRTCVideoResolution_160_90 = 100,
+
+ ///宽高比 16:9；分辨率 256x144；建议码率（VideoCall）200kbps; 建议码率（LIVE）300kbps。
+ TRTCVideoResolution_256_144 = 102,
+
+ ///宽高比 16:9；分辨率 320x180；建议码率（VideoCall）250kbps; 建议码率（LIVE）400kbps。
+ TRTCVideoResolution_320_180 = 104,
+
+ ///宽高比 16:9；分辨率 480x270；建议码率（VideoCall）350kbps; 建议码率（LIVE）550kbps。
+ TRTCVideoResolution_480_270 = 106,
+
+ ///宽高比 16:9；分辨率 640x360；建议码率（VideoCall）500kbps; 建议码率（LIVE）900kbps。
+ TRTCVideoResolution_640_360 = 108,
+
+ ///宽高比 16:9；分辨率 960x540；建议码率（VideoCall）850kbps; 建议码率（LIVE）1300kbps。
+ TRTCVideoResolution_960_540 = 110,
+
+ ///宽高比 16:9；分辨率 1280x720；建议码率（VideoCall）1200kbps; 建议码率（LIVE）1800kbps。
+ TRTCVideoResolution_1280_720 = 112,
+
+ ///宽高比 16:9；分辨率 1920x1080；建议码率（VideoCall）2000kbps; 建议码率（LIVE）3000kbps。
+ TRTCVideoResolution_1920_1080 = 114,
+
};
/**
- * 1.2 视频分辨率模式
+ * 1.2 视频宽高比模式
*
- * - 横屏分辨率：TRTCVideoResolution_640_360 + TRTCVideoResolutionModeLandscape = 640 × 360
- * - 竖屏分辨率：TRTCVideoResolution_640_360 + TRTCVideoResolutionModePortrait = 360 × 640
+ * TRTCVideoResolution 中仅定义了横屏分辨率（如 640 × 360），如需使用竖屏分辨率（如360 × 640），需要同时指定 TRTCVideoResolutionMode 为 Portrait。
*/
-enum TRTCVideoResolutionMode
-{
- TRTCVideoResolutionModeLandscape = 0, ///< 横屏分辨率
- TRTCVideoResolutionModePortrait = 1, ///< 竖屏分辨率
+enum TRTCVideoResolutionMode {
+
+ ///横屏分辨率，例如：TRTCVideoResolution_640_360 + TRTCVideoResolutionModeLandscape = 640 × 360。
+ TRTCVideoResolutionModeLandscape = 0,
+
+ ///竖屏分辨率，例如：TRTCVideoResolution_640_360 + TRTCVideoResolutionModePortrait = 360 × 640。
+ TRTCVideoResolutionModePortrait = 1,
+
};
/**
* 1.3 视频流类型
*
- * TRTC 内部有三种不同的音视频流，分别为：
- * - 主画面：最常用的一条线路，一般用来传输摄像头的视频数据。
- * - 小画面：跟主画面的内容相同，但是分辨率和码率更低。
- * - 辅流画面：一般用于屏幕分享或远程播片（例如老师播放视频给学生观看）。
- *
- * @note - 如果主播的上行网络和性能比较好，则可以同时送出大小两路画面。
- * @note - SDK 不支持单独开启小画面，小画面必须依附于主画面而存在。
+ * TRTC 内部有三种不同的视频流，分别是：
+ * - 高清大画面：一般用来传输摄像头的视频数据。
+ * - 低清小画面：小画面和大画面的内容相互，但是分辨率和码率都比大画面低，因此清晰度也更低。
+ * - 辅流画面：一般用于屏幕分享，同一时间在同一个房间中只允许一个用户发布辅流视频，其他用户必须要等该用户关闭之后才能发布自己的辅流。
+ * @note 不支持单独开启低清小画面，小画面必须依附于大画面而存在，SDK 会自动设定低清小画面的分辨率和码率。
*/
-enum TRTCVideoStreamType
-{
- TRTCVideoStreamTypeBig = 0, ///< 主画面视频流
- TRTCVideoStreamTypeSmall = 1, ///< 小画面视频流
- TRTCVideoStreamTypeSub = 2, ///< 辅流（屏幕分享）
+enum TRTCVideoStreamType {
+
+ ///高清大画面，一般用来传输摄像头的视频数据。
+ TRTCVideoStreamTypeBig = 0,
+
+ ///低清小画面：小画面和大画面的内容相互，但是分辨率和码率都比大画面低，因此清晰度也更低。
+ TRTCVideoStreamTypeSmall = 1,
+
+ ///辅流画面：一般用于屏幕分享，同一时间在同一个房间中只允许一个用户发布辅流视频，其他用户必须要等该用户关闭之后才能发布自己的辅流。
+ TRTCVideoStreamTypeSub = 2,
+
};
/**
* 1.4 视频画面填充模式
*
- * 如果画面的显示分辨率不等于画面的原始分辨率，就需要您设置画面的填充模式:
- * - TRTCVideoFillMode_Fill，图像铺满屏幕，超出显示视窗的视频部分将被裁剪，画面显示可能不完整。
- * - TRTCVideoFillMode_Fit，图像长边填满屏幕，短边区域会被填充黑色，但画面的内容肯定是完整的。
+ * 如果视频显示区域的宽高比不等于视频内容的宽高比时，就需要您指定画面的填充模式:
*/
-enum TRTCVideoFillMode
-{
- /// 图像铺满屏幕，超出显示视窗的视频部分将被裁剪
+enum TRTCVideoFillMode {
+
+ ///填充模式：即将画面内容居中等比缩放以充满整个显示区域，超出显示区域的部分将会被裁剪掉，此模式下画面可能不完整。
TRTCVideoFillMode_Fill = 0,
- /// 图像长边填满屏幕，短边区域会被填充黑色
+
+ ///适应模式：即按画面长边进行缩放以适应显示区域，短边部分会被填充为黑色，此模式下图像完整但可能留有黑边。
TRTCVideoFillMode_Fit = 1,
+
};
/**
* 1.5 视频画面旋转方向
*
- * TRTC SDK 提供了对本地和远程画面的旋转角度设置 API，下列的旋转角度都是指顺时针方向的。
- *
+ * TRTC 提供了对本地和远程画面的旋转角度设置 API，下列的旋转角度都是指顺时针方向的。
*/
-enum TRTCVideoRotation
-{
- TRTCVideoRotation0 = 0, ///< 顺时针旋转0度
- TRTCVideoRotation90 = 1, ///< 顺时针旋转90度
- TRTCVideoRotation180 = 2, ///< 顺时针旋转180度
- TRTCVideoRotation270 = 3, ///< 顺时针旋转270度
+enum TRTCVideoRotation {
+
+ ///不旋转
+ TRTCVideoRotation0 = 0,
+
+ ///顺时针旋转90度
+ TRTCVideoRotation90 = 1,
+
+ ///顺时针旋转180度
+ TRTCVideoRotation180 = 2,
+
+ ///顺时针旋转270度
+ TRTCVideoRotation270 = 3,
+
};
/**
* 1.6 美颜（磨皮）算法
*
- * TRTC SDK 内置多种不同的磨皮算法，您可以选择最适合您产品定位的方案。
+ * TRTC 内置多种不同的磨皮算法，您可以选择最适合您产品定位的方案。
*/
-enum TRTCBeautyStyle
-{
- TRTCBeautyStyleSmooth = 0, ///< 光滑，适用于美女秀场，效果比较明显。
- TRTCBeautyStyleNature = 1, ///< 自然，磨皮算法更多地保留了面部细节，主观感受上会更加自然。
+enum TRTCBeautyStyle {
+
+ ///光滑，算法比较激进，磨皮效果比较明显，适用于秀场直播。
+ TRTCBeautyStyleSmooth = 0,
+
+ ///自然，算法更多地保留了面部细节，磨皮效果更加自然，适用于绝大多数直播场景。
+ TRTCBeautyStyleNature = 1,
+
};
/**
* 1.7 视频像素格式
*
- * TRTC SDK 提供针对视频的自定义采集和自定义渲染功能，在自定义采集功能中，您可以用下列枚举值描述您采集的视频像素格式。
- * 在自定义渲染功能中，您可以指定您期望 SDK 回调的视频像素格式。
+ * TRTC 提供针对视频的自定义采集和自定义渲染功能：
+ * - 在自定义采集功能中，您可以用下列枚举值描述您采集的视频像素格式。
+ * - 在自定义渲染功能中，您可以指定您期望 SDK 回调出的视频像素格式。
*/
-enum TRTCVideoPixelFormat
-{
+enum TRTCVideoPixelFormat {
+
+ ///未定义的格式
TRTCVideoPixelFormat_Unknown = 0,
- TRTCVideoPixelFormat_I420 = 1, ///< I420
- TRTCVideoPixelFormat_Texture_2D = 2, ///< OpenGL 2D 纹理
- TRTCVideoPixelFormat_BGRA32 = 3, ///< BGRA32
- TRTCVideoPixelFormat_RGBA32 = 5, ///< RGBA32
-};
+ /// YUV420P(I420) 格式
+ TRTCVideoPixelFormat_I420 = 1,
+
+ /// OpenGL 2D 纹理格式
+ TRTCVideoPixelFormat_Texture_2D = 2,
+
+ /// BGRA 格式
+ TRTCVideoPixelFormat_BGRA32 = 3,
+
+ /// RGBA 格式
+ TRTCVideoPixelFormat_RGBA32 = 5,
+
+};
/**
- * 1.8 视频数据包装格式
+ * 1.8 视频数据传递方式
+ *
+ * 在自定义采集和自定义渲染功能，您需要用到下列枚举值来指定您希望以什么方式传递视频数据：
+ * - 方案一：使用内存 Buffer 传递视频数据，该方案在 iOS 效率尚可，但在 Android 系统上效率较差，Windows 暂时仅支持内存 Buffer 的传递方式。
+ * - 方案二：使用 Texture 纹理传递视频数据，该方案在 iOS 和 Android 系统下均有较高的效率，Windows 暂不支持，需要您有一定的 OpenGL 编程基础。
*/
-enum TRTCVideoBufferType
-{
+enum TRTCVideoBufferType {
+
+ ///未定义的传递方式
TRTCVideoBufferType_Unknown = 0,
- TRTCVideoBufferType_Buffer = 1, ///< 二进制Buffer类型
- TRTCVideoBufferType_Texture = 3, ///< 纹理类型
+
+ ///使用内存 Buffer 传递视频数据，iOS: PixelBuffer；Android: 用于 JNI 层的 Direct Buffer；Win: 内存数据块。
+ TRTCVideoBufferType_Buffer = 1,
+
+ ///使用 Texture 纹理传递视频数据
+ TRTCVideoBufferType_Texture = 3,
+
};
/**
- * 1.9 画面渲染镜像类型
+ * 1.9 视频的镜像类型
*
- * TRTC 的画面镜像提供下列设置模式
+ * 视频的镜像是指对视频内容进行左右翻转，尤其是对本地的摄像头预览视频，开启镜像后能给主播带来熟悉的“照镜子”体验。
*/
-enum TRTCVideoMirrorType
-{
+enum TRTCVideoMirrorType {
+
+///自动模式：如果正使用前置摄像头则开启镜像，如果是后置摄像头则不开启镜像（仅适用于移动设备）。
#if TARGET_PLATFORM_PHONE
- TRTCVideoMirrorType_Auto = 0, ///< 只适用于移动端，本地预览时，前置摄像头镜像，后置摄像头不镜像
+ TRTCVideoMirrorType_Auto = 0,
#endif
- TRTCVideoMirrorType_Enable = 1, ///< 所有画面均镜像
- TRTCVideoMirrorType_Disable = 2, ///< 所有画面均不镜像
+
+ ///强制开启镜像，不论当前使用的是前置摄像头还是后置摄像头。
+ TRTCVideoMirrorType_Enable = 1,
+
+ ///强制关闭镜像，不论当前使用的是前置摄像头还是后置摄像头。
+ TRTCVideoMirrorType_Disable = 2,
+
};
/**
- * 1.10 视频截图来源
+ * 1.10 本地视频截图的数据源
+ *
+ * SDK 支持从如下两种数据源中截取图片并保存成本地文件：
+ * - 视频流：从视频流中截取原生的视频内容，截取的内容不受渲染控件的显示控制。
+ * - 渲染层：从渲染控件中截取显示的视频内容，可以做到用户所见即所得的效果，但如果显示区域过小，截取出的图片也会很小。
*/
-enum TRTCSnapshotSourceType
-{
- TRTCSnapshotSourceTypeStream = 0, ///< 从视频流上截取视频画面
- TRTCSnapshotSourceTypeView = 1, ///< 从渲染 View 上截取视频画面
+enum TRTCSnapshotSourceType {
+
+ ///从视频流中截取原生的视频内容，截取的内容不受渲染控件的显示控制。
+ TRTCSnapshotSourceTypeStream = 0,
+
+ ///从渲染控件中截取显示的视频内容，可以做到用户所见即所得的效果，但如果显示区域过小，截取出的图片也会很小。
+ TRTCSnapshotSourceTypeView = 1,
+
};
/////////////////////////////////////////////////////////////////////////////////
//
-// 【（二）网络相关枚举值定义】
+// 网络相关枚举值定义
//
/////////////////////////////////////////////////////////////////////////////////
/**
* 2.1 应用场景
*
- * TRTC 可用于视频会议和在线直播等多种应用场景，针对不同的应用场景，TRTC SDK 的内部会进行不同的优化配置：
- * - TRTCAppSceneVideoCall ：视频通话场景，适合[1对1视频通话]、[300人视频会议]、[在线问诊]、[视频聊天]、[远程面试]等。
- * - TRTCAppSceneLIVE ：视频互动直播，适合[视频低延时直播]、[十万人互动课堂]、[视频直播 PK]、[视频相亲房]、[互动课堂]、[远程培训]、[超大型会议]等。
- * - TRTCAppSceneAudioCall ：语音通话场景，适合[1对1语音通话]、[300人语音会议]、[语音聊天]、[语音会议]、[在线狼人杀]等。
- * - TRTCAppSceneVoiceChatRoom：语音互动直播，适合：[语音低延时直播]、[语音直播连麦]、[语聊房]、[K 歌房]、[FM 电台]等。
+ * TRTC 针对常见的音视频应用场景都进行了定向优化，以满足各种垂直场景下的差异化要求，主要场景可以分为如下两类：
+ * - 直播（LIVE）场景：包括 LIVE 和 VoiceChatRoom，前者是音频+视频，后者是纯音频。
+ * 直播场景下，用户被分成“主播”和“观众”两种角色，单个房间中同时最多支持10万人在线，适合于观众人数众多的直播场景。
+ * - 实时（RTC）场景：包括 VideoCall 和 AudioCall，前者是音频+视频，后者是纯音频。
+ * 实时场景下，用户没有角色的差异，但单个房间中同时最多支持 300 人在线，适合于小范围实时通信的场景。
*/
-enum TRTCAppScene
-{
- /// 视频通话场景，支持720P、1080P高清画质，单个房间最多支持300人同时在线，最高支持50人同时发言。<br>
- /// 适合：[1对1视频通话]、[300人视频会议]、[在线问诊]、[视频聊天]、[远程面试]等。
- TRTCAppSceneVideoCall = 0,
-
- /// 视频互动直播，支持平滑上下麦，切换过程无需等待，主播延时小于300ms；支持十万级别观众同时播放，播放延时低至1000ms。<br>
- /// 适合：[视频低延时直播]、[十万人互动课堂]、[视频直播 PK]、[视频相亲房]、[互动课堂]、[远程培训]、[超大型会议]等。<br>
- /// 注意：此场景下，您必须通过 TRTCParams 中的 role 字段指定当前用户的角色。
- TRTCAppSceneLIVE = 1,
-
- /// 语音通话场景，支持 48kHz，支持双声道。单个房间最多支持300人同时在线，最高支持50人同时发言。<br>
- /// 适合：[1对1语音通话]、[300人语音会议]、[语音聊天]、[语音会议]、[在线狼人杀]等。
- TRTCAppSceneAudioCall = 2,
-
- /// 语音互动直播，支持平滑上下麦，切换过程无需等待，主播延时小于300ms；支持十万级别观众同时播放，播放延时低至1000ms。<br>
- /// 适合：[语音低延时直播]、[语音直播连麦]、[语聊房]、[K 歌房]、[FM 电台]等。<br>
- /// 注意：此场景下，您必须通过 TRTCParams 中的 role 字段指定当前用户的角色。
+enum TRTCAppScene {
+
+ ///视频通话场景，支持720P、1080P高清画质，单个房间最多支持300人同时在线，最高支持50人同时发言。
+ ///适用于[1对1视频通话]、[300人视频会议]、[在线问诊]、[教育小班课]、[远程面试]等业务场景。
+ TRTCAppSceneVideoCall = 0,
+
+ ///视频互动直播，支持平滑上下麦，切换过程无需等待，主播延时小于300ms；支持十万级别观众同时播放，播放延时低至1000ms。
+ ///适用于[低延时互动直播]、[大班课]、[主播PK]、[视频相亲]、[在线互动课堂]、[远程培训]、[超大型会议]等业务场景。
+ ///@note 此场景下，您必须通过 TRTCParams 中的 role 字段指定当前用户的角色。
+ TRTCAppSceneLIVE = 1,
+
+ ///语音通话场景，默认采用 SPEECH 音质，单个房间最多支持300人同时在线，最高支持50人同时发言。
+ ///适用于[1对1语音通话]、[300人语音会议]、[语音聊天]、[语音会议]、[在线狼人杀]等业务场景。
+ TRTCAppSceneAudioCall = 2,
+
+ ///语音互动直播，支持平滑上下麦，切换过程无需等待，主播延时小于300ms；支持十万级别观众同时播放，播放延时低至1000ms。
+ ///适用于[语音俱乐部]、[在线K歌房]、[音乐直播间]、[FM电台]等业务场景。
+ ///@note 此场景下，您必须通过 TRTCParams 中的 role 字段指定当前用户的角色。
TRTCAppSceneVoiceChatRoom = 3,
+
};
/**
- * 2.2 角色，仅适用于直播场景（TRTCAppSceneLIVE 和 TRTCAppSceneVoiceChatRoom）
- *
- * 在直播场景中，多数用户仅为观众，个别用户是主播，这种角色区分有利于 TRTC 进行更好的定向优化。
+ * 2.2 角色
*
- * - Anchor：主播，可以上行视频和音频，一个房间里最多支持50个主播同时上行音视频。
- * - Audience：观众，只能观看，不能上行视频和音频，一个房间里的观众人数没有上限。
+ * 仅适用于直播类场景（即 TRTCAppSceneLIVE 和 TRTCAppSceneVoiceChatRoom），把用户区分成两种不同的身份：
+ * - 主播：可以随时发布自己的音视频流，但人数有限制，同一个房间中最多只允许 50 个主播同时发布自己的音视频流。
+ * - 观众：只能观看其他用户的音视频流，要发布音视频流，需要先通过 {@link switchRole} 切换成主播，同一个房间中最多能容纳10万观众。
*/
-enum TRTCRoleType
-{
- TRTCRoleAnchor = 20, ///< 主播
- TRTCRoleAudience = 21, ///< 观众
+enum TRTCRoleType {
+
+ ///主播：可以随时发布自己的音视频流，但人数有限制，同一个房间中最多只允许 50 个主播同时发布自己的音视频流。
+ TRTCRoleAnchor = 20,
+
+ ///观众：只能观看其他用户的音视频流，要发布音视频流，需要先通过 {@link switchRole} 切换成主播，同一个房间中最多能容纳10万观众。
+ TRTCRoleAudience = 21,
+
};
/**
- * 2.3 流控模式
- *
- * TRTC SDK 内部需要时刻根据网络情况调整内部的编解码器和网络模块，以便能够对网络的变化做出反应。
- * 为了支持快速算法升级，SDK 内部设置了两种不同的流控模式：
- * - ModeServer：云端控制，默认模式，推荐选择。
- * - ModeClient：本地控制，用于 SDK 开发内部调试，客户请勿使用。
- *
- * @note 推荐您使用云端控制，这样每当我们升级 Qos 算法时，您无需升级 SDK 即可体验更好的效果。
+ * 2.3 流控模式（已废弃）
*/
-enum TRTCQosControlMode
-{
- TRTCQosControlModeClient, ///< 客户端控制（用于 SDK 开发内部调试，客户请勿使用）
- TRTCQosControlModeServer, ///< 云端控制 （默认）
+enum TRTCQosControlMode {
+
+ ///本地控制，用于 SDK 开发内部调试，客户请勿使用。
+ TRTCQosControlModeClient = 0,
+
+ ///云端控制，默认模式，推荐选择。
+ TRTCQosControlModeServer = 1,
+
};
/**
* 2.4 画质偏好
*
- * 指当 TRTC SDK 在遇到弱网络环境时，您期望“保清晰”或“保流畅”：
- *
- * - Smooth：弱网下保流畅。即在遭遇弱网环境时首先确保声音的流畅和优先发送，画面会变得模糊且会有较多马赛克，但可以保持流畅不卡顿。
- * - Clear：弱网下保清晰。即在遭遇弱网环境时，画面会尽可能保持清晰，但可能会更容易出现卡顿。
+ * TRTC 在弱网络环境下有两种调控模式：“优先保证画面清晰”或“优先保证画面流畅”，两种模式均会优先保障声音数据的传输。
*/
-enum TRTCVideoQosPreference
-{
- TRTCVideoQosPreferenceSmooth = 1, ///< 弱网下保流畅
- TRTCVideoQosPreferenceClear = 2, ///< 弱网下保清晰
+enum TRTCVideoQosPreference {
+
+ ///流畅优先：即当前网络不足以传输既清晰又流畅的画面时，优先保证画面的流畅性，代价就是画面会比较模糊且伴随有较多的马赛克。
+ TRTCVideoQosPreferenceSmooth = 1,
+
+ ///清晰优先（默认值）：即当前网络不足以传输既清晰又流畅的画面时，优先保证画面的清晰度，代价就是画面会比较卡顿。
+ TRTCVideoQosPreferenceClear = 2,
+
};
/**
* 2.5 网络质量
*
- * TRTC SDK 对网络质量定义了六种不同的级别，Excellent 表示最好，Down 表示不可用。
+ * TRTC 会每隔两秒对当前的网络质量进行评估，评估结果为六个等级：Excellent 表示最好，Down 表示最差。
*/
-enum TRTCQuality
-{
- TRTCQuality_Unknown = 0, ///< 未定义
- TRTCQuality_Excellent = 1, ///< 最好
- TRTCQuality_Good = 2, ///< 好
- TRTCQuality_Poor = 3, ///< 一般
- TRTCQuality_Bad = 4, ///< 差
- TRTCQuality_Vbad = 5, ///< 很差
- TRTCQuality_Down = 6, ///< 不可用
+enum TRTCQuality {
+
+ ///未定义
+ TRTCQuality_Unknown = 0,
+
+ ///当前网络非常好
+ TRTCQuality_Excellent = 1,
+
+ ///当前网络比较好
+ TRTCQuality_Good = 2,
+
+ ///当前网络一般
+ TRTCQuality_Poor = 3,
+
+ ///当前网络较差
+ TRTCQuality_Bad = 4,
+
+ ///当前网络很差
+ TRTCQuality_Vbad = 5,
+
+ ///当前网络不满足 TRTC 的最低要求
+ TRTCQuality_Down = 6,
+
};
/**
- * 2.6 混流输入类型
+ * 2.6 视频状态类型
+ *
+ * 该枚举类型用于视频状态变化回调接口{@link onRemoteVideoStatusUpdated}，用于指定当前的视频状态。
*/
-enum TRTCMixInputType
-{
- /// 不指定，根据pureAudio值决定混流类型
- TRTCMixInputTypeUndefined = 0,
- /// 混入音视频
- TRTCMixInputTypeAudioVideo = 1,
- /// 只混入视频
- TRTCMixInputTypePureVideo = 2,
- /// 只混入音频
- TRTCMixInputTypePureAudio = 3,
-};
+enum TRTCAVStatusType {
-/////////////////////////////////////////////////////////////////////////////////
-//
-// 【（三）声音相关枚举值定义】
-//
-/////////////////////////////////////////////////////////////////////////////////
+ ///停止播放
+ TRTCAVStatusStopped = 0,
+
+ ///正在播放
+ TRTCAVStatusPlaying = 1,
+
+ ///正在加载
+ TRTCAVStatusLoading = 2,
+
+};
/**
- * 3.1 音频帧的格式
+ * 2.7 视频状态变化原因类型
*
+ * 该枚举类型用于视频状态变化回调接口{@link onRemoteVideoStatusUpdated}，用于指定当前的视频状态原因。
*/
-enum TRTCAudioFrameFormat
-{
- TRTCAudioFrameFormatNone = 0,
- TRTCAudioFrameFormatPCM, ///< PCM，每个采样点占16bit数据量。
+enum TRTCAVStatusChangeReason {
+
+ ///缺省值
+ TRTCAVStatusChangeReasonInternal = 0,
+
+ ///网络缓冲
+ TRTCAVStatusChangeReasonBufferingBegin = 1,
+
+ ///结束缓冲
+ TRTCAVStatusChangeReasonBufferingEnd = 2,
+
+ ///本地启动视频流播放
+ TRTCAVStatusChangeReasonLocalStarted = 3,
+
+ ///本地停止视频流播放
+ TRTCAVStatusChangeReasonLocalStopped = 4,
+
+ ///远端视频流开始（或继续）
+ TRTCAVStatusChangeReasonRemoteStarted = 5,
+
+ ///远端视频流停止（或中断
+ TRTCAVStatusChangeReasonRemoteStopped = 6,
+
};
+/////////////////////////////////////////////////////////////////////////////////
+//
+// 音频相关枚举值定义
+//
+/////////////////////////////////////////////////////////////////////////////////
+
/**
* 3.2 声音音质
*
- * 音频音质用来衡量声音的保真程度，TRTCAudioQualitySpeech 适用于通话场景，TRTCAudioQualityMusic 适用于高音质音乐场景。
+ * TRTC 提供了三种精心校调好的模式，用来满足各种垂直场景下对音质的差异化追求：
+ * - 人声模式（Speech）：适用于以人声沟通为主的应用场景，该模式下音频传输的抗性较强，TRTC 会通过各种人声处理技术保障在弱网络环境下的流畅度最佳。
+ * - 音乐模式（Music）：适用于对声乐要求很苛刻的场景，该模式下音频传输的数据量很大，TRTC 会通过各项技术确保音乐信号在各频段均能获得高保真的细节还原度。
+ * - 默认模式（Default）：介于 Speech 和 Music 之间的档位，对音乐的还原度比人声模式要好，但传输数据量比音乐模式要低很多，对各种场景均有不错的适应性。
*/
-enum TRTCAudioQuality
-{
- /// 流畅音质：采样率：16k；单声道；音频裸码率：16kbps；适合语音通话为主的场景，比如在线会议，语音通话。
+enum TRTCAudioQuality {
+
+ ///人声模式：采样率：16k；单声道；编码码率：16kbps；具备几个模式中最强的网络抗性，适合语音通话为主的场景，比如在线会议，语音通话等。
TRTCAudioQualitySpeech = 1,
- /// 默认音质：采样率：48k；单声道；音频裸码率：50kbps；SDK 默认的音频质量，如无特殊需求推荐选择之。
+
+ ///默认模式：采样率：48k；单声道；编码码率：50kbps；介于 Speech 和 Music 之间的档位，SDK 默认档位，推荐选择。
TRTCAudioQualityDefault = 2,
- /// 高音质：采样率：48k；双声道 + 全频带；音频裸码率：128kbps；适合需要高保真传输音乐的场景，比如K歌、音乐直播等。
+
+ ///音乐模式：采样率：48k；全频带立体声；编码码率：128kbps；适合需要高保真传输音乐的场景，比如在线K歌、音乐直播等。
TRTCAudioQualityMusic = 3,
+
+};
+
+/**
+ * 3.7 音频帧的内容格式
+ */
+enum TRTCAudioFrameFormat {
+
+ /// None
+ TRTCAudioFrameFormatNone = 0,
+
+ /// PCM 格式的音频数据
+ TRTCAudioFrameFormatPCM,
+
};
/////////////////////////////////////////////////////////////////////////////////
//
-// 【（四）更多枚举值定义】
+// 更多枚举值定义
//
/////////////////////////////////////////////////////////////////////////////////
/**
* 4.1 Log 级别
+ *
+ * 不同的日志等级定义了不同的详实程度和日志数量，推荐一般情况下将日志等级设置为：TRTCLogLevelInfo。
+ */
+enum TRTCLogLevel {
+
+ ///输出所有级别的 Log
+ TRTCLogLevelVerbose = 0,
+
+ ///输出 DEBUG，INFO，WARNING，ERROR 和 FATAL 级别的 Log
+ TRTCLogLevelDebug = 1,
+
+ ///输出 INFO，WARNING，ERROR 和 FATAL 级别的 Log
+ TRTCLogLevelInfo = 2,
+
+ ///输出WARNING，ERROR 和 FATAL 级别的 Log
+ TRTCLogLevelWarn = 3,
+
+ ///输出ERROR 和 FATAL 级别的 Log
+ TRTCLogLevelError = 4,
+
+ ///仅输出 FATAL 级别的 Log
+ TRTCLogLevelFatal = 5,
+
+ ///不输出任何 SDK Log
+ TRTCLogLevelNone = 6,
+
+};
+
+/**
+ * 4.3 屏幕分享的目标类型（仅适用于桌面端）
+ */
+enum TRTCScreenCaptureSourceType {
+
+ ///未定义
+ TRTCScreenCaptureSourceTypeUnknown = -1,
+
+ ///该分享目标是某一个应用的窗口
+ TRTCScreenCaptureSourceTypeWindow = 0,
+
+ ///该分享目标是某一台显示器的屏幕
+ TRTCScreenCaptureSourceTypeScreen = 1,
+
+ ///该分享目标是用户自定义的数据源
+ TRTCScreenCaptureSourceTypeCustom = 2,
+
+};
+
+/**
+ * 4.4 云端混流的排版模式
+ *
+ * TRTC 的云端混流服务能够将房间中的多路音视频流混合成一路，因此您需要指定画面的排版方案，我们提供了如下几种排版模式：
+ */
+enum TRTCTranscodingConfigMode {
+
+ ///未定义
+ TRTCTranscodingConfigMode_Unknown = 0,
+
+ ///全手动排版模式
+ ///该模式下，您需要指定每一路画面的精确排版位置。该模式的自由度最高，但易用性也最差：
+ ///- 您需要填写 TRTCTranscodingConfig 中的所有参数，包括每一路画面（TRTCMixUser）的位置坐标。
+ ///- 您需要监听 TRTCCloudDelegate 中的 onUserVideoAvailable() 和 onUserAudioAvailable() 事件回调，并根据当前房间中各个麦上用户的音视频状态不断地调整 mixUsers 参数。
+ TRTCTranscodingConfigMode_Manual = 1,
+
+ ///纯音频模式
+ ///该模式适用于语音通话（AudioCall）和语音聊天室（VoiceChatRoom）等纯音频的应用场景。
+ ///- 您只需要在进入房间后，通过 setMixTranscodingConfig() 接口设置一次，之后 SDK 就会自动把房间内所有上麦用户的声音混流到当前用户的直播流上。
+ ///- 您无需设置 TRTCTranscodingConfig 中的 mixUsers 参数，只需设置 audioSampleRate、audioBitrate 和 audioChannels 等参数即可。
+ TRTCTranscodingConfigMode_Template_PureAudio = 2,
+
+ ///预排版模式
+ ///最受欢迎的排版模式，因为该模式支持您通过占位符提前对各路画面的位置进行设定，之后 SDK 会自动根据房间中画面的路数动态进行适配调整。
+ ///此模式下，您依然需要设置 mixUsers 参数，但可以将 userId 设置为“占位符”，可选的占位符有：
+ /// - "$PLACE_HOLDER_REMOTE$" : 指代远程用户的画面，可以设置多个。
+ /// - "$PLACE_HOLDER_LOCAL_MAIN$" ： 指代本地摄像头画面，只允许设置一个。
+ /// - "$PLACE_HOLDER_LOCAL_SUB$" : 指代本地屏幕分享画面，只允许设置一个。
+ ///此模式下，您不需要监听 TRTCCloudDelegate 中的 onUserVideoAvailable() 和 onUserAudioAvailable() 回调进行实时调整，
+ ///只需要在进房成功后调用一次 setMixTranscodingConfig() 即可，之后 SDK 会自动将真实的 userId 补位到您设置的占位符上。
+ TRTCTranscodingConfigMode_Template_PresetLayout = 3,
+
+ ///屏幕分享模式
+ ///适用于在线教育场景等以屏幕分享为主的应用场景，仅支持 Windows 和 Mac 两个平台的 SDK。
+ ///该模式下，SDK 会先根据您通过 videoWidth 和 videoHeight 参数设置的目标分辨率构建一张画布，
+ ///- 当老师未开启屏幕分享时，SDK 会将老师的摄像头画面等比例拉伸绘制到该画布上；
+ ///- 当老师开启屏幕分享之后，SDK 会将屏幕分享画面绘制到同样的画布上。
+ ///此种排版模式的目的是为了确保混流模块的输出分辨率一致，避免课程回放和网页观看的花屏问题（网页播放器不支持可变分辨率）。
+ ///同时，连麦学生的声音也会被默认混合到老师的音视频流中。
+ ///< br>
+ ///由于教学模式下的视频内容以屏幕分享为主，因此同时传输摄像头画面和屏幕分享画面是非常浪费带宽的。
+ ///推荐的做法是直接将摄像头画面通过 setLocalVideoRenderCallback 接口自定义绘制到当前屏幕上。
+ ///在该模式下，您无需设置 TRTCTranscodingConfig 中的 mixUsers 参数，SDK 不会混合学生的画面，以免干扰屏幕分享的效果。
+ ///< br>
+ ///您可以将 TRTCTranscodingConfig 中的 width × height 设为 0px × 0px，SDK 会自动根据用户当前屏幕的宽高比计算出一个合适的分辨率：
+ ///- 如果老师当前屏幕宽度 <= 1920px，SDK 会使用老师当前屏幕的实际分辨率。
+ ///- 如果老师当前屏幕宽度 > 1920px，SDK 会根据当前屏幕宽高比，选择 1920x1080(16:9)、1920x1200(16:10)、1920x1440(4:3) 三种分辨率中的一种。
+ TRTCTranscodingConfigMode_Template_ScreenSharing = 4,
+
+};
+
+/**
+ * 4.5 媒体录制类型
+ *
+ * 该枚举类型用于本地媒体录制接口{@link startLocalRecording}，用于指定是录制音视频文件还是纯音频文件。
*/
-enum TRTCLogLevel
-{
- TRTCLogLevelVerbose = 0, ///< 输出所有级别的 Log
- TRTCLogLevelDebug = 1, ///< 输出 DEBUG，INFO，WARNING，ERROR 和 FATAL 级别的 Log
- TRTCLogLevelInfo = 2, ///< 输出 INFO，WARNING，ERROR 和 FATAL 级别的 Log
- TRTCLogLevelWarn = 3, ///< 只输出WARNING，ERROR 和 FATAL 级别的 Log
- TRTCLogLevelError = 4, ///< 只输出ERROR 和 FATAL 级别的 Log
- TRTCLogLevelFatal = 5, ///< 只输出 FATAL 级别的 Log
- TRTCLogLevelNone = 6, ///< 不输出任何 SDK Log
+enum TRTCLocalRecordType {
+
+ ///仅录制音频
+ TRTCLocalRecordType_Audio = 0,
+
+ ///仅录制视频
+ TRTCLocalRecordType_Video = 1,
+
+ ///同时录制音频和视频
+ TRTCLocalRecordType_Both = 2,
+
};
/**
- * 4.2 设备操作
+ * 4.6 混流输入类型
*/
-enum TRTCDeviceState
-{
- TRTCDeviceStateAdd = 0, ///< 添加设备
- TRTCDeviceStateRemove = 1, ///< 移除设备
- TRTCDeviceStateActive = 2, ///< 设备已启用
+enum TRTCMixInputType {
+
+ ///不指定，SDK 会根据另一个参数 pureAudio 的数值决定混流输入类型
+ TRTCMixInputTypeUndefined = 0,
+
+ ///混入音频和视频
+ TRTCMixInputTypeAudioVideo = 1,
+
+ ///只混入视频
+ TRTCMixInputTypePureVideo = 2,
+
+ ///只混入音频
+ TRTCMixInputTypePureAudio = 3,
+
};
/**
- * 4.3 设备类型
+ * 4.7 设备类型（仅适用于桌面平台）
*
- * 以下定义仅用于兼容原有接口，具体定义参见 ITXDeviceManager.h 文件
+ * 该枚举值用于定义三种类型的音视频设备，即摄像头、麦克风和扬声器，以便让一套设备管理接口可以操控三种不同类型的设备。
+ * 自 Ver8.0 版本开始，TRTC 在 TXDeviceManager 中重新定义了 “TXMediaDeviceType” 用于替换老版本中的 “TRTCMediaDeviceType”，
+ * 此处仅保留 “TRTCMediaDeviceType” 的定义，用于兼容老版本的客户代码。
*/
typedef TXMediaDeviceType TRTCDeviceType;
-#define TRTCDeviceTypeUnknow TXMediaDeviceTypeUnknown
-#define TRTCDeviceTypeMic TXMediaDeviceTypeMic
+#define TRTCDeviceTypeUnknow TXMediaDeviceTypeUnknown
+#define TRTCDeviceTypeMic TXMediaDeviceTypeMic
#define TRTCDeviceTypeSpeaker TXMediaDeviceTypeSpeaker
-#define TRTCDeviceTypeCamera TXMediaDeviceTypeCamera
+#define TRTCDeviceTypeCamera TXMediaDeviceTypeCamera
+
+/**
+ * 4.8 水印图片的源类型
+ */
+enum TRTCWaterMarkSrcType {
+
+ ///图片文件路径，支持 BMP、GIF、JPEG、PNG、TIFF、Exif、WMF 和 EMF 文件格式
+ TRTCWaterMarkSrcTypeFile = 0,
+
+ /// BGRA32格式内存块
+ TRTCWaterMarkSrcTypeBGRA32 = 1,
+
+ /// RGBA32格式内存块
+ TRTCWaterMarkSrcTypeRGBA32 = 2,
+
+};
/**
- * 4.4 水印图片的源类型
+ * 4.9 设备操作
+ *
+ * 该枚举值用于本地设备的状态变化通知{@link onDeviceChange}。
*/
-enum TRTCWaterMarkSrcType
-{
- TRTCWaterMarkSrcTypeFile = 0, ///< 图片文件路径，支持 BMP、GIF、JPEG、PNG、TIFF、Exif、WMF 和 EMF 文件格式
- TRTCWaterMarkSrcTypeBGRA32 = 1, ///< BGRA32格式内存块
- TRTCWaterMarkSrcTypeRGBA32 = 2, ///< RGBA32格式内存块
+enum TRTCDeviceState {
+
+ ///设备已被插入
+ TRTCDeviceStateAdd = 0,
+
+ ///设备已被移除
+ TRTCDeviceStateRemove = 1,
+
+ ///设备已启用
+ TRTCDeviceStateActive = 2,
+
};
/**
- * 4.5 屏幕分享目标信息
+ * 4.11 音频录制内容类型
+ *
+ * 该枚举类型用于音频录制接口{@link startAudioRecording}，用于指定录制音频的内容。
*/
-enum TRTCScreenCaptureSourceType
-{
- TRTCScreenCaptureSourceTypeUnknown = -1,
- TRTCScreenCaptureSourceTypeWindow = 0, ///< 该分享目标是某一个窗口
- TRTCScreenCaptureSourceTypeScreen = 1, ///< 该分享目标是整个桌面
- TRTCScreenCaptureSourceTypeCustom = 2,
+enum TRTCAudioRecordingContent {
+
+ ///录制本地和远端所有音频
+ TRTCAudioRecordingContentAll = 0,
+
+ ///仅录制本地音频
+ TRTCAudioRecordingContentLocal = 1,
+
+ ///仅录制远端音频
+ TRTCAudioRecordingContentRemote = 2,
+
};
/////////////////////////////////////////////////////////////////////////////////
//
-// 【（五）TRTC 核心类型定义】
+// TRTC 核心类型定义
//
/////////////////////////////////////////////////////////////////////////////////
/**
- * 5.1 进房相关参数
+ * 5.1 进房参数
*
- * 只有该参数填写正确，才能顺利调用 enterRoom 进入 roomId 所指定的音视频房间。
+ * 作为 TRTC SDK 的进房参数，只有该参数填写正确，才能顺利进入 roomId 或者 strRoomId 所指定的音视频房间。
+ * 由于历史原因，TRTC 支持数字和字符串两种类型的房间号，分别是 roomId 和 strRoomId。
+ * 请注意：不要混用 roomId 和 strRoomId，因为它们之间是不互通的，比如数字 123 和字符串 “123” 在 TRTC 看来是两个完全不同的房间。
*/
-struct TRTCParams
-{
-
- ///【字段含义】应用标识（必填），腾讯视频云基于 sdkAppId 完成计费统计。
- ///【推荐取值】在 [实时音视频控制台](https://console.cloud.tencent.com/rav/) 创建应用后可在帐号信息页面中得到该 ID。
+struct TRTCParams {
+ ///【字段含义】应用标识（必填），腾讯云基于 sdkAppId 完成计费统计。
+ ///【推荐取值】在 [实时音视频控制台](https://console.cloud.tencent.com/rav/) 创建应用后可以在账号信息页面中得到该 ID。
uint32_t sdkAppId;
///【字段含义】用户标识（必填），当前用户的 userId，相当于用户名，使用 UTF-8 编码。
- ///【推荐取值】如果一个用户在您的帐号系统中的 ID 为“abc”，则 userId 即可设置为“abc”。
- const char * userId;
+ ///【推荐取值】如果一个用户在您的帐号系统中的 ID 为“mike”，则 userId 即可设置为“mike”。
+ const char *userId;
- ///【字段含义】用户签名（必填），当前 userId 对应的验证签名，相当于登录密码。
+ ///【字段含义】用户签名（必填），当前 userId 对应的验证签名，相当于使用云服务的登录密码。
///【推荐取值】具体计算方法请参见 [如何计算UserSig](https://cloud.tencent.com/document/product/647/17275)。
- const char * userSig;
+ const char *userSig;
- ///【字段含义】房间号码（必填），在同一个房间内的用户可以看到彼此并进行视频通话。
- ///【推荐取值】您可以自定义设置该参数值，但不可重复。如果您的用户帐号 ID （userId）为数字类型，可直接使用创建者的用户 ID 作为 roomId。
+ ///【字段含义】数字房间号，在同一个房间里的用户（userId）可以彼此看到对方并进行音视频通话。
+ ///【推荐取值】取值范围：1 - 4294967294。
+ ///【特别说明】roomId 与 strRoomId 是互斥的，若您选用 strRoomId，则 roomId 需要填写为0。若两者都填，SDK 将优先选用 roomId。
+ ///【请您注意】不要混用 roomId 和 strRoomId，因为它们之间是不互通的，比如数字 123 和字符串 “123” 在 TRTC 看来是两个完全不同的房间。
uint32_t roomId;
- ///【字段含义】字符串房间号码，在同一个房间里的用户（userId）可以彼此看到对方并进行视频通话。
+ ///【字段含义】字符串房间号，在同一个房间里的用户（userId）可以彼此看到对方并进行音视频通话。
+ ///【特别说明】roomId 与 strRoomId 是互斥的，若您选用 strRoomId，则 roomId 需要填写为0。若两者都填，SDK 将优先选用 roomId。
+ ///【请您注意】不要混用 roomId 和 strRoomId，因为它们之间是不互通的，比如数字 123 和字符串 “123” 在 TRTC 看来是两个完全不同的房间。
///【推荐取值】限制长度为64字节。以下为支持的字符集范围（共 89 个字符）:
- /// -大小写英文字母（a-zA-Z）；
- /// -数字（0-9）；
- /// -空格、"!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、" {"、"}"、"|"、"~"、","。
- ///【特殊说明】roomId 与 strRoomId 必填一个，若您选用 strRoomId，则 roomId 需要填写为0。若两者都填，将优先选用 roomId。
- const char* strRoomId;
-
- ///【字段含义】直播场景下的角色，仅适用于直播场景（TRTCAppSceneLIVE 和 TRTCAppSceneVoiceChatRoom），视频通话场景下指定无效。
- ///【推荐取值】默认值：主播（TRTCRoleAnchor）
+ /// - 大小写英文字母（a-zA-Z）；
+ /// - 数字（0-9）；
+ /// - 空格、"!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、" {"、"}"、"|"、"~"、","。
+ const char *strRoomId;
+
+ ///【字段含义】直播场景下的角色，仅适用于直播场景（{@link TRTCAppSceneLIVE} 和{@link TRTCAppSceneVoiceChatRoom}），通话场景下指定该参数是无效的。
+ ///【推荐取值】默认值：主播（{@link TRTCRoleAnchor}）。
TRTCRoleType role;
- ///【字段含义】绑定腾讯云直播 CDN 流 ID[非必填]，设置之后，您就可以在腾讯云直播 CDN 上通过标准直播方案（FLV或HLS）播放该用户的音视频流。
- ///【推荐取值】限制长度为64字节，可以不填写，一种推荐的方案是使用 “sdkappid_roomid_userid_main” 作为 streamid，这样比较好辨认且不会在您的多个应用中发生冲突。
+ ///【字段含义】用于指定在腾讯云直播平台上的 streamId（选填），设置之后，您可以在腾讯云直播 CDN 上通过标准拉流方案（FLV或HLS）播放该用户的音视频流。
+ ///【推荐取值】限制长度为64字节，可以不填写，一种推荐的方案是使用 “sdkappid_roomid_userid_main” 作为 streamid，这中命名方式容易辨认且不会在您的多个应用中发生冲突。
///【特殊说明】要使用腾讯云直播 CDN，您需要先在[控制台](https://console.cloud.tencent.com/trtc/) 中的功能配置页开启“启动自动旁路直播”开关。
///【参考文档】[CDN 旁路直播](https://cloud.tencent.com/document/product/647/16826)。
- const char * streamId;
+ const char *streamId;
- ///【字段含义】设置云端录制完成后的回调消息中的 "userdefinerecordid" 字段内容，便于您更方便的识别录制回调。
- ///【推荐取值】限制长度为64字节，只允许包含大小写英文字母（a-zA-Z）、数字（0-9）及下划线和连词符。
+ ///【字段含义】云端录制开关（选填），用于指定是否要在云端将该用户的音视频流录制下来。
///【参考文档】[云端录制](https://cloud.tencent.com/document/product/647/16823)。
- const char * userDefineRecordId;
-
- ///【字段含义】房间签名（非必填），当您希望某个房间只能让特定的 userId 进入时，需要使用 privateMapKey 进行权限保护。
+ ///【推荐取值】限制长度为64字节，只允许包含大小写英文字母（a-zA-Z）、数字（0-9）及下划线和连词符。
+ /// <p>
+ /// 方案一：手动录制方案：
+ /// 1. 在“[控制台](https://console.cloud.tencent.com/trtc) => 应用管理 => 云端录制配置”中开启云端录制。
+ /// 2. 设置“录制形式”为“手动录制”。
+ /// 3. 设置手动录制后，在一个 TRTC 房间中只有设置了 userDefineRecordId 参数的用户才会在云端录制出视频文件，不指定该参数的用户不会产生录制行为。
+ /// 4. 云端会以 “userDefineRecordId_起始时间_结束时间” 的格式命名录制下来的文件。
+ /// <p>
+ /// 方案二：自动录制方案：
+ /// 1. 需要在“[控制台](https://console.cloud.tencent.com/trtc) => 应用管理 => 云端录制配置”中开启云端录制。
+ /// 2. 设置“录制形式”为“自动录制”。
+ /// 3. 设置自动录制后，在一个 TRTC 房间中的任何一个有音视频上行的用户，均会在云端录制出视频文件。
+ /// 4. 文件会以 “userDefineRecordId_起始时间_结束时间” 的格式命名，如果不指定 userDefineRecordId，则文件会以 “streamId_起始时间_结束时间” 命名。
+ /// <br>
+ const char *userDefineRecordId;
+
+ ///【字段含义】用于权限控制的权限票据（选填），当您希望某个房间只能让特定的 userId 进入时，需要使用 privateMapKey 进行权限保护。
///【推荐取值】仅建议有高级别安全需求的客户使用，更多详情请参见 [进房权限保护](https://cloud.tencent.com/document/product/647/32240)。
- const char * privateMapKey;
-
- ///【字段含义】业务数据（非必填），部分高级特性才需要使用该字段。
- ///【推荐取值】不建议使用
- const char * businessInfo;
-
-
- TRTCParams()
- : sdkAppId(0)
- , roomId(0)
- , strRoomId(nullptr)
- , userId(nullptr)
- , userSig(nullptr)
- , role(TRTCRoleAnchor)
- , privateMapKey(nullptr)
- , businessInfo(nullptr)
- , userDefineRecordId(nullptr)
- , streamId(nullptr)
- {
+ const char *privateMapKey;
+ ///【字段含义】业务数据字段（选填），部分高级特性才需要用到此字段。
+ ///【推荐取值】请不要自行设置该字段。
+ const char *businessInfo;
+ TRTCParams() : sdkAppId(0), roomId(0), strRoomId(nullptr), userId(nullptr), userSig(nullptr), role(TRTCRoleAnchor), privateMapKey(nullptr), businessInfo(nullptr), userDefineRecordId(nullptr), streamId(nullptr) {
}
};
/**
* 5.2 视频编码参数
*
- * 该设置决定了远端用户看到的画面质量（同时也是云端录制出的视频文件的画面质量）。
+ * 该设置决定远端用户看到的画面质量，同时也决定了云端录制出的视频文件的画面质量。
*/
-struct TRTCVideoEncParam
-{
+struct TRTCVideoEncParam {
///【字段含义】 视频分辨率
+ ///【特别说明】如需使用竖屏分辨率，请指定 resMode 为 Portrait，例如： 640 × 360 + Portrait = 360 × 640。
///【推荐取值】
- /// - 视频通话建议选择 360 × 640 及以下分辨率，resMode 选择 Portrait。
- /// - 手机直播建议选择 540 × 960，resMode 选择 Portrait。
- /// - Windows 和 Mac 建议选择 640 × 360 及以上分辨率，resMode 选择 Landscape。
- ///【特别说明】
- /// TRTCVideoResolution 默认只能横屏模式的分辨率，例如 640 × 360。
- /// 如需使用竖屏分辨率，请指定 resMode 为 Portrait，例如 640 × 360 结合 Portrait 则为 360 × 640。
+ /// - 手机视频通话：建议选择 360 × 640 及以下分辨率，resMode 选择 Portrait，即竖屏分辨率。
+ /// - 手机在线直播：建议选择 540 × 960，resMode 选择 Portrait，即竖屏分辨率。
+ /// - 桌面平台（Win + Mac）：建议选择 640 × 360 及以上分辨率，resMode 选择 Landscape，即横屏分辨率。
TRTCVideoResolution videoResolution;
- ///【字段含义】分辨率模式（横屏分辨率 - 竖屏分辨率）
- ///【推荐取值】手机直播建议选择 Portrait，Windows 和 Mac 建议选择 Landscape。
- ///【特别说明】如果 videoResolution 指定分辨率 640 × 360，resMode 指定模式为 Portrait，则最终编码出的分辨率为360 × 640。
+ ///【字段含义】分辨率模式（横屏分辨率 or 竖屏分辨率）
+ ///【推荐取值】手机平台（iOS、Android）建议选择 Portrait，桌面平台（Windows、Mac）建议选择 Landscape。
+ ///【特别说明】如需使用竖屏分辨率，请指定 resMode 为 Portrait，例如： 640 × 360 + Portrait = 360 × 640。
TRTCVideoResolutionMode resMode;
///【字段含义】视频采集帧率
- ///【推荐取值】15fps 或 20fps。5fps 以下，卡顿感明显。10fps 以下，会有轻微卡顿感。20fps 以上，则过于浪费（电影的帧率为 24fps）。
- ///【特别说明】很多 Android 手机的前置摄像头并不支持 15fps 以上的采集帧率，部分过于突出美颜功能的 Android 手机前置摄像头的采集帧率可能低于 10fps。
+ ///【推荐取值】15fps或20fps。5fps以下，卡顿感明显。10fps以下，会有轻微卡顿感。20fps以上，会浪费带宽（电影的帧率为24fps）。
+ ///【特别说明】部分 Android 手机的前置摄像头并不支持15fps以上的采集帧率，部分主打美颜功能的 Android 手机的前置摄像头的采集帧率可能低于10fps。
uint32_t videoFps;
- ///【字段含义】视频上行码率
- ///【推荐取值】推荐设置请参考本文件前半部分 TRTCVideoResolution 定义处的注释说明
- ///【特别说明】码率太低会导致视频中出现大量马赛克
+ ///【字段含义】目标视频码率，SDK 会按照目标码率进行编码，只有在弱网络环境下才会主动降低视频码率。
+ ///【推荐取值】请参考本 TRTCVideoResolution 在各档位注释的最佳码率，也可以在此基础上适当调高。
+ /// 比如：TRTCVideoResolution_1280_720 对应 1200kbps 的目标码率，您也可以设置为 1500kbps 用来获得更好的观感清晰度。
+ ///【特别说明】您可以通过同时设置 videoBitrate 和 minVideoBitrate 两个参数，用于约束 SDK 对视频码率的调整范围：
+ /// - 如果您追求“弱网络下允许卡顿但要保持清晰”的效果，可以设置 minVideoBitrate 为 videoBitrate 的 60%；
+ /// - 如果您追求“弱网络下允许模糊但要保持流畅”的效果，可以设置 minVideoBitrate 为一个较低的数值（比如 100kbps）；
+ /// - 如果您将 videoBitrate 和 minVideoBitrate 设置为同一个值，等价于关闭 SDK 对视频码率的自适应调节能力。
uint32_t videoBitrate;
- ///【字段含义】最低视频码率，SDK 会在网络不佳的情况下主动降低视频码率，最低会降至
- /// minVideoBitrate 所设定的数值。 【推荐取值】
- /// - 如果您追求“允许卡顿但要保持清晰”的效果，可以设置 minVideoBitrate 为 videoBitrate 的
- /// 60%；
- /// - 如果您追求“允许模糊但要保持流畅”的效果，可以设置 minVideoBitrate 为 200kbps；
- /// - 如果您将 videoBitrate 和 minVideoBitrate 设置为同一个值，等价于关闭 SDK
- /// 的自适应调节能力；
- /// - 默认值：0，此时最低码率由 SDK 根据分辨率情况，自动设置合适的数值。
- ///【特别说明】
- /// - 当您把分辨率设置的比较高时，minVideoBitrate
- /// 不适合设置的太低，否则会出现画面模糊和大范围的马赛克宏块。
- /// 比如把分辨率设置为 720p，把码率设置为
- /// 200kbps，那么编码出的画面将会出现大范围区域性马赛克。
+ ///【字段含义】最低视频码率，SDK 会在网络不佳的情况下主动降低视频码率以保持流畅度，最低会降至 minVideoBitrate 所设定的数值。
+ ///【特别说明】 默认值：0，此时最低码率由 SDK 会根据您指定的分辨率，自动计算出合适的数值。
+ ///【推荐取值】您可以通过同时设置 videoBitrate 和 minVideoBitrate 两个参数，用于约束 SDK 对视频码率的调整范围：
+ /// - 如果您追求“弱网络下允许卡顿但要保持清晰”的效果，可以设置 minVideoBitrate 为 videoBitrate 的 60%；
+ /// - 如果您追求“弱网络下允许模糊但要保持流畅”的效果，可以设置 minVideoBitrate 为一个较低的数值（比如 100kbps）；
+ /// - 如果您将 videoBitrate 和 minVideoBitrate 设置为同一个值，等价于关闭 SDK 对视频码率的自适应调节能力。
uint32_t minVideoBitrate;
- ///【字段含义】是否允许调整分辨率
- ///【推荐取值】
- /// - 手机直播建议选择 false。
- /// - 视频通话模式，若更关注流畅性，建议选择 true，此时若遇到带宽有限的弱网，SDK 会自动降低分辨率以保障更好的流畅度（仅针对 TRTCVideoStreamTypeBig 生效）。
- /// - 默认值：false。
- ///【特别说明】若有录制需求，选择 true 时，请确保通话过程中，调整分辨率不会影响您的录制效果。
+ ///【字段含义】是否允许动态调整分辨率（开启后会对云端录制产生影响）。
+ ///【推荐取值】该功能适用于不需要云端录制的场景，开启后 SDK 会根据当前网络情况，智能选择出一个合适的分辨率，避免出现“大分辨率+小码率”的低效编码模式。
+ ///【特别说明】默认值：关闭。如有云端录制的需求，请不要开启此功能，因为如果视频分辨率发生变化后，云端录制出的 MP4 在普通的播放器上无法正常播放。
bool enableAdjustRes;
- TRTCVideoEncParam()
- : videoResolution(TRTCVideoResolution_640_360)
- , resMode(TRTCVideoResolutionModeLandscape)
- , videoFps(15)
- , videoBitrate(550)
- , enableAdjustRes(false)
- , minVideoBitrate(0)
- {
-
+ TRTCVideoEncParam() : videoResolution(TRTCVideoResolution_640_360), resMode(TRTCVideoResolutionModeLandscape), videoFps(15), videoBitrate(550), enableAdjustRes(false), minVideoBitrate(0) {
}
};
/**
- * 5.3 画面渲染参数
+ * 5.3 网络流控（Qos）参数集
*
- * 您可以通过设置此参数来控制画面的旋转、填充、镜像模式
+ * 网络流控相关参数，该设置决定 SDK 在弱网络环境下的调控策略（例如：“清晰优先”或“流畅优先”）
*/
-struct TRTCRenderParams {
- TRTCVideoRotation rotation; ///< 视频画面旋转方向，默认值为 TRTCVideoRotation0
- TRTCVideoFillMode fillMode; ///< 视频画面填充模式，默认值为 TRTCVideoFillMode_Fit
- TRTCVideoMirrorType mirrorType; ///< 视频画面镜像模式，默认值为 TRTCVideoMirrorType_Disable
-
- TRTCRenderParams()
- : rotation(TRTCVideoRotation0)
- , fillMode(TRTCVideoFillMode_Fit)
- , mirrorType(TRTCVideoMirrorType_Disable) {
+struct TRTCNetworkQosParam {
+ ///【字段含义】清晰优先还是流畅优先
+ ///【推荐取值】清晰优先
+ ///【特别说明】该参数主要影响 TRTC 在较差网络环境下的音视频表现：
+ /// - 流畅优先：即当前网络不足以传输既清晰又流畅的画面时，优先保证画面的流畅性，代价就是画面会比较模糊且伴随有较多的马赛克。
+ /// - 清晰优先（默认值）：即当前网络不足以传输既清晰又流畅的画面时，优先保证画面的清晰度，代价就是画面会比较卡顿。
+ TRTCVideoQosPreference preference;
+
+ ///【字段含义】流控模式（已废弃）
+ ///【推荐取值】云端控制
+ ///【特别说明】请设置为云端控制模式（TRTCQosControlModeServer）
+ TRTCQosControlMode controlMode;
+
+ TRTCNetworkQosParam() : preference(TRTCVideoQosPreferenceClear), controlMode(TRTCQosControlModeServer) {
}
};
/**
- * 5.4 网络流控相关参数
+ * 5.4 视频画面的渲染参数
*
- * 网络流控相关参数，该设置决定了SDK在各种网络环境下的调控方向（比如弱网下是“保清晰”或“保流畅”）
+ * 您可以通过设置此参数来控制画面的旋转角度、填充模式和左右镜像模式。
*/
-struct TRTCNetworkQosParam
-{
- ///【字段含义】弱网下是“保清晰”或“保流畅”
- ///【特别说明】
- /// - 弱网下保流畅：在遭遇弱网环境时，画面会变得模糊，且出现较多马赛克，但可以保持流畅不卡顿。
- /// - 弱网下保清晰：在遭遇弱网环境时，画面会尽可能保持清晰，但可能容易出现卡顿
- TRTCVideoQosPreference preference;
+struct TRTCRenderParams {
+ ///【字段含义】图像的顺时针旋转角度
+ ///【推荐取值】支持90、180以及270旋转角度，默认值：{@link TRTCVideoRotation_0}
+ TRTCVideoRotation rotation;
- ///【字段含义】视频分辨率（云端控制 - 客户端控制）
- ///【推荐取值】云端控制
- ///【特别说明】
- /// - Server 模式（默认）：云端控制模式，若无特殊原因，请直接使用该模式
- /// - Client 模式：客户端控制模式，用于 SDK 开发内部调试，客户请勿使用
- TRTCQosControlMode controlMode;
+ ///【字段含义】画面填充模式
+ ///【推荐取值】填充（画面可能会被拉伸裁剪）或适应（画面可能会有黑边），默认值：{@link TRTCVideoFillMode_Fill}
+ TRTCVideoFillMode fillMode;
- TRTCNetworkQosParam()
- : preference(TRTCVideoQosPreferenceClear)
- , controlMode(TRTCQosControlModeServer)
- {
+ ///【字段含义】画面镜像模式
+ ///【推荐取值】默认值：{@link TRTCVideoMirrorType_Auto}
+ TRTCVideoMirrorType mirrorType;
+ TRTCRenderParams() : rotation(TRTCVideoRotation0), fillMode(TRTCVideoFillMode_Fit), mirrorType(TRTCVideoMirrorType_Disable) {
}
};
/**
* 5.5 网络质量
*
- * 表示网络质量的好坏，通过这个数值，您可以在 UI 界面上用图标表征 userId 的通话线路质量
+ * 表征网络质量的好坏，您可以通过该数值在用户界面上展示每个用户的网络质量。
*/
-struct TRTCQualityInfo
-{
- const char * userId; ///< 用户标识
- TRTCQuality quality; ///< 网络质量
+struct TRTCQualityInfo {
+ ///用户 ID
+ const char *userId;
- TRTCQualityInfo()
- : userId(nullptr)
- , quality(TRTCQuality_Unknown)
- {
+ ///网络质量
+ TRTCQuality quality;
+ TRTCQualityInfo() : userId(nullptr), quality(TRTCQuality_Unknown) {
}
};
/**
* 5.6 音量大小
*
- * 表示语音音量的评估大小，通过这个数值，您可以在 UI 界面上用图标表征 userId 是否有在说话。
+ * 表征语音音量的评估值，您可以通过该数值在用户界面上展示每个用户的音量大小。
*/
-struct TRTCVolumeInfo
-{
- /// 说话者的 userId，字符编码格式为 UTF-8
- const char * userId;
- /// 说话者的音量， 取值范围 0 - 100
- uint32_t volume;
+struct TRTCVolumeInfo {
+ ///说话者的 userId, 如果 userId 为空则代表是当前用户自己。
+ const char *userId;
- TRTCVolumeInfo()
- : userId(nullptr)
- , volume(0)
- {
+ ///说话者的音量大小, 取值范围[0 - 100]。
+ uint32_t volume;
+ TRTCVolumeInfo() : userId(nullptr), volume(0) {
}
};
-
/**
- * 5.7 视频帧数据
+ * 5.7 网络测速结果
*
+ * 您可以在用户进入房间前通过 {@link startSpeedTest} 接口进行测速（注意：请不要在通话中调用），
+ * 测速结果会每2 - 3秒钟返回一次，每次返回一个 IP 地址的测试结果。
*/
-struct TRTCVideoFrame
-{
- TRTCVideoPixelFormat videoFormat; ///< 视频帧的格式
- TRTCVideoBufferType bufferType; ///< 视频数据结构类型
- char * data; ///< 视频数据，字段 bufferType 是 LiteAVVideoBufferType_Buffer 时生效
- int textureId; ///< 视频纹理 ID，字段 bufferType 是 LiteAVVideoBufferType_Texture 时生效
- uint32_t length; ///< 视频数据的长度，单位是字节，对于 i420 而言， length = width * height * 3 / 2，对于BGRA32而言， length = width * height * 4
- uint32_t width; ///< 画面的宽度
- uint32_t height; ///< 画面的高度
- uint64_t timestamp; ///< 时间戳，单位 ms
- TRTCVideoRotation rotation; ///< 画面旋转角度
-
- TRTCVideoFrame()
- : videoFormat(TRTCVideoPixelFormat_Unknown)
- , bufferType(TRTCVideoBufferType_Unknown)
- , data(nullptr)
- , textureId(-1)
- , length(0)
- , width(640)
- , height(360)
- , timestamp(0)
- , rotation(TRTCVideoRotation0)
- {
+struct TRTCSpeedTestResult {
+ ///服务器 IP 地址
+ const char *ip;
+
+ ///内部通过评估算法测算出的网络质量，网络质量越好得分越高。
+ TRTCQuality quality;
+
+ ///上行丢包率，取值范围是 [0 - 1.0]，例如 0.3 表示每向服务器发送10个数据包可能会在中途丢失3个。
+ float upLostRate;
+
+ ///下行丢包率，取值范围是 [0 - 1.0]，例如 0.2 表示每从服务器收取10个数据包可能会在中途丢失2个。
+ float downLostRate;
+
+ ///延迟（毫秒），指当前设备到 TRTC 服务器的一次网络往返时间，该值越小越好，正常数值范围是10ms - 100ms。
+ int rtt;
+ TRTCSpeedTestResult() : ip(nullptr), quality(TRTCQuality_Unknown), upLostRate(0.0f), downLostRate(0.0f), rtt(0) {
}
};
/**
- * 5.8 音频帧数据
+ * 5.9 视频帧信息
*
+ * TRTCVideoFrame 用来描述一帧视频画面的裸数据，也就是编码前或者解码后的视频画面数据。
*/
-struct TRTCAudioFrame
-{
- TRTCAudioFrameFormat audioFormat; ///< 音频帧的格式
- char * data; ///< 音频数据
- uint32_t length; ///< 音频数据的长度
- uint32_t sampleRate; ///< 采样率
- uint32_t channel; ///< 声道数
- uint64_t timestamp; ///< 时间戳，单位 ms
-
- TRTCAudioFrame()
- : audioFormat(TRTCAudioFrameFormatNone)
- , data(nullptr)
- , length(0)
- , sampleRate(48000)
- , channel(1)
- , timestamp(0)
- {
+struct TRTCVideoFrame {
+ ///【字段含义】视频的像素格式
+ TRTCVideoPixelFormat videoFormat;
+
+ ///【字段含义】视频数据结构类型
+ TRTCVideoBufferType bufferType;
+
+ ///【字段含义】bufferType 为 {@link TRTCVideoBufferType_Buffer} 时的视频数据，承载用于 C++ 层的内存数据块。
+ char *data;
+
+ ///【字段含义】视频纹理 ID,bufferType 为 {@link TRTCVideoBufferType_Texture} 时的视频数据，承载用于 OpenGL 渲染的纹理数据。
+ int textureId;
+
+ ///【字段含义】视频数据的长度，单位是字节。对于 i420 而言：length = width * height * 3 / 2；对于 BGRA32 而言：length = width * height * 4。
+ uint32_t length;
+
+ ///【字段含义】视频宽度
+ uint32_t width;
+
+ ///【字段含义】视频高度
+ uint32_t height;
+
+ ///【字段含义】视频帧的时间戳，单位毫秒
+ ///【推荐取值】自定义视频采集时可以设置为0。若该参数为0，SDK 会自定填充 timestamp 字段，但请“均匀”地控制 sendCustomVideoData 的调用间隔。
+ uint64_t timestamp;
+
+ ///【字段含义】视频像素的顺时针旋转角度
+ TRTCVideoRotation rotation;
+ TRTCVideoFrame() : videoFormat(TRTCVideoPixelFormat_Unknown), bufferType(TRTCVideoBufferType_Unknown), data(nullptr), textureId(-1), length(0), width(640), height(360), timestamp(0), rotation(TRTCVideoRotation0) {
}
};
/**
- * 5.9 网络测速结果
- *
- * 您可以在用户进入房间前通过 TRTCCloud 的 startSpeedTest 接口进行测速 （注意：请不要在通话中调用），
- * 测速结果会每2 - 3秒钟返回一次，每次返回一个 IP 地址的测试结果。
- *
- * @note - quality 是内部通过评估算法测算出的网络质量，loss 越低，rtt 越小，得分便越高。
- * @note - upLostRate 是指上行丢包率。例如，0.3表示每向服务器发送10个数据包可能会在中途丢失3个。
- * @note - downLostRate 是指下行丢包率。例如，0.2表示每从服务器收取10个数据包可能会在中途丢失2个。
- * @note - rtt 是指当前设备到腾讯云服务器的一次网络往返时间，该值越小越好，正常数值范围是10ms - 100ms
+ * 5.10 音频帧数据
*/
-struct TRTCSpeedTestResult
-{
- /// 服务器 IP 地址
- const char * ip;
+struct TRTCAudioFrame {
+ ///【字段含义】音频帧的格式
+ TRTCAudioFrameFormat audioFormat;
- /// 网络质量，内部通过评估算法测算出的网络质量，loss 越低，rtt 越小，得分便越高
- TRTCQuality quality;
+ ///【字段含义】音频数据
+ char *data;
- /// 上行丢包率，范围是0 - 1.0，例如，0.3表示每向服务器发送10个数据包可能会在中途丢失3个。
- float upLostRate;
+ ///【字段含义】音频数据的长度
+ uint32_t length;
- /// 下行丢包率，范围是0 - 1.0，例如，0.2表示每从服务器收取10个数据包可能会在中途丢失2个。
- float downLostRate;
+ ///【字段含义】采样率
+ uint32_t sampleRate;
- /// 延迟（毫秒），指当前设备到腾讯云服务器的一次网络往返时间，该值越小越好，正常数值范围是10ms - 100ms
- int rtt;
+ ///【字段含义】声道数
+ uint32_t channel;
- TRTCSpeedTestResult()
- : ip(nullptr)
- , quality(TRTCQuality_Unknown)
- , upLostRate(0.0f)
- , downLostRate(0.0f)
- , rtt(0)
- {
+ ///【字段含义】时间戳，单位ms
+ uint64_t timestamp;
+ TRTCAudioFrame() : audioFormat(TRTCAudioFrameFormatNone), data(nullptr), length(0), sampleRate(48000), channel(1), timestamp(0) {
}
};
/**
- * 5.10 云端混流中每一路子画面的位置信息
+ * 5.11 云端混流中各路画面的描述信息
*
- * TRTCMixUser 用于指定每一路（即每一个 userId）视频画面的具体摆放位置
+ * TRTCMixUser 用于指定云端混流中每一路视频画面的位置、大小、图层以及流类型等信息。
*/
-struct TRTCMixUser
-{
- ///【字段含义】参与混流的 userId
- const char * userId;
+struct TRTCMixUser {
+ ///【字段含义】用户 ID
+ const char *userId;
- ///【字段含义】参与混流的 roomId，跨房流传入的实际 roomId，当前房间流传入 roomId = nullptr
- const char * roomId;
+ ///【字段含义】该路音视频流所在的房间号（设置为空值代表当前用户所在的房间号）
+ const char *roomId;
- ///【字段含义】图层位置坐标以及大小，左上角为坐标原点(0,0) （绝对像素值）
+ ///【字段含义】指定该路画面的坐标区域（单位：像素）
RECT rect;
- ///【字段含义】图层层次（1 - 15）不可重复
+ ///【字段含义】指定该路画面的层级（取值范围：1 - 15，不可重复）
int zOrder;
- ///【字段含义】该用户是不是只开启了音频
+ ///【字段含义】指定该路画面是主路画面（{@link TRTCVideoStreamTypeBig}）还是辅路画面（{@link TRTCVideoStreamTypeSub}）。
+ TRTCVideoStreamType streamType;
+
+ ///【字段含义】指定该路流是不是只混合声音
///【推荐取值】默认值：NO
- ///【特别说明】废弃，推荐使用 inputType
+ ///【特别说明】已废弃，推荐使用8.5版本开始新引入的字段：inputType。
bool pureAudio;
- ///【字段含义】参与混合的是主路画面（TRTCVideoStreamTypeBig）或屏幕分享（TRTCVideoStreamTypeSub）画面
- TRTCVideoStreamType streamType;
-
- /// 【字段含义】该用户的输入流类型（该字段是对 pureAudio 字段的升级）
- /// 【推荐取值】
- /// - 默认值：TRTCMixInputTypeUndefined
- /// - 如果您没有对 pureAudio 字段进行设置，您可以根据实际需要设置该字段
- /// - 如果您已经设置了 pureAudio 为 YES，请设置该字段为 TRTCMixInputTypeUndefined
+ ///【字段含义】指定该路流的混合内容（只混合音频、只混合视频、混合音频和视频），该字段是对 pureAudio 字段的升级。
+ ///【推荐取值】默认值：TRTCMixInputTypeUndefined，代表参考 pureAudio 的取值。
+ /// - 如果您是第一次使用 TRTC，之前并没有对 pureAudio 字段进行过设置，您可以根据实际需要设置该字段，不建议您再设置 pureAudio。
+ /// - 如果您之前在老版本中已经使用了 pureAudio 字段，并期望保持其设置，则可以将 inputType 设置为 TRTCMixInputTypeUndefined。
TRTCMixInputType inputType;
-
- TRTCMixUser()
- : userId(nullptr)
- , roomId(nullptr)
- , rect()
- , zOrder(0)
- , pureAudio(false)
- , streamType(TRTCVideoStreamTypeBig)
- , inputType(TRTCMixInputTypeUndefined)
- {
+
+ TRTCMixUser() : userId(nullptr), roomId(nullptr), rect(), zOrder(0), pureAudio(false), streamType(TRTCVideoStreamTypeBig), inputType(TRTCMixInputTypeUndefined) {
rect.left = 0;
rect.top = 0;
rect.right = 0;
@@ -832,197 +1085,181 @@ struct TRTCMixUser
};
/**
- * 5.11 混流参数配置模式
+ * 5.12 云端混流的排版布局和转码参数
*
+ * 用于指定混流时各路画面的排版位置信息和云端转码的编码参数。
*/
-enum TRTCTranscodingConfigMode {
- /// 非法值
- TRTCTranscodingConfigMode_Unknown = 0,
-
- /// 全手动模式，灵活性最高，可以自由组合出各种混流方案，但易用性最差。
- /// 此模式下，您需要填写 TRTCTranscodingConfig 中的所有参数，并需要监听 TRTCCloudDelegate 中的 onUserVideoAvailable() 和 onUserAudioAvailable() 回调，
- /// 以便根据当前房间中各个上麦用户的音视频状态不断地调整 mixUsers 参数，否则会导致混流失败。
- TRTCTranscodingConfigMode_Manual = 1,
-
- /// 纯音频模式，适用于语音通话（AudioCall）和语音聊天室（VoiceChatRoom）等纯音频场景。
- /// 只需要在进房后通过 setMixTranscodingConfig() 接口设置一次，之后 SDK 就会自动把房间内所有上麦用户的声音混流到当前用户的直播流上。
- /// 此模式下，您无需设置 TRTCTranscodingConfig 中的 mixUsers 参数，只需设置 audioSampleRate、audioBitrate 和 audioChannels 等参数。
- TRTCTranscodingConfigMode_Template_PureAudio = 2,
-
- /// 预排版模式，通过占位符提前对各路画面进行排布
- /// 此模式下，您依然需要设置 mixUsers 参数，但可以将 userId 设置为占位符，可选的占位符有：
- /// - "$PLACE_HOLDER_REMOTE$" : 指代远程用户的画面，可以设置多个。
- /// - "$PLACE_HOLDER_LOCAL_MAIN$" ： 指代本地摄像头画面，只允许设置一个。
- /// - "$PLACE_HOLDER_LOCAL_SUB$" : 指代本地屏幕分享画面，只允许设置一个。
- /// 但是您可以不需要监听 TRTCCloudDelegate 中的 onUserVideoAvailable() 和 onUserAudioAvailable() 回调进行实时调整，
- /// 只需要在进房成功后调用一次 setMixTranscodingConfig() 即可，之后 SDK 会自动将真实的 userId 补位到您设置的占位符上。
- TRTCTranscodingConfigMode_Template_PresetLayout = 3,
-
- /// 屏幕分享模式，适用于在线教育场景等以屏幕分享为主的应用场景，仅支持 Windows 和 Mac 两个平台的 SDK。
- /// SDK 会先根据您（通过 videoWidth 和 videoHeight 参数）设置的目标分辨率构建一张画布，
- /// 当老师未开启屏幕分享时，SDK 会将摄像头画面等比例拉伸绘制到该画布上；当老师开启屏幕分享之后，SDK 会将屏幕分享画面绘制到同样的画布上。
- /// 这样操作的目的是为了确保混流模块的输出分辨率一致，避免课程回放和网页观看的花屏问题（网页播放器不支持可变分辨率）。
- ///
- /// 由于教学模式下的视频内容以屏幕分享为主，因此同时传输摄像头画面和屏幕分享画面是非常浪费带宽的。
- /// 推荐的做法是直接将摄像头画面通过 setLocalVideoRenderCallback 接口自定义绘制到当前屏幕上。
- /// 在该模式下，您无需设置 TRTCTranscodingConfig 中的 mixUsers 参数，SDK 不会混合学生的画面，以免干扰屏幕分享的效果。
- ///
- /// 您可以将 TRTCTranscodingConfig 中的 width × height 设为 0px × 0px，SDK 会自动根据用户当前屏幕的宽高比计算出一个合适的分辨率：
- /// - 如果老师当前屏幕宽度 <= 1920px，SDK 会使用老师当前屏幕的实际分辨率。
- /// - 如果老师当前屏幕宽度 > 1920px，SDK 会根据当前屏幕宽高比，选择 1920x1080(16:9)、1920x1200(16:10)、1920x1440(4:3) 三种分辨率中的一种。
- TRTCTranscodingConfigMode_Template_ScreenSharing = 4,
-};
-
-/**
- * 5.12 云端混流（转码）配置
- *
- * 包括最终编码质量和各路画面的摆放位置
- */
-struct TRTCTranscodingConfig
-{
- ///【字段含义】转码 config 模式
+struct TRTCTranscodingConfig {
+ ///【字段含义】排版模式
+ ///【推荐取值】请根据您的业务场景要求自行选择，预排版模式是适用性较好的一种模式。
TRTCTranscodingConfigMode mode;
- ///【字段含义】腾讯云直播 AppID
- ///【推荐取值】请在 [实时音视频控制台](https://console.cloud.tencent.com/rav) 选择已经创建的应用，单击【帐号信息】后，在“直播信息”中获取
+ ///【字段含义】腾讯云直播服务的 AppID
+ ///【推荐取值】请在 [实时音视频控制台](https://console.cloud.tencent.com/trtc) 依次单击【应用管理】=>【应用信息】，并在【旁路直播信息】中获取 appid。
uint32_t appId;
- ///【字段含义】腾讯云直播 bizid
- ///【推荐取值】请在 [实时音视频控制台](https://console.cloud.tencent.com/rav) 选择已经创建的应用，单击【帐号信息】后，在“直播信息”中获取
+ ///【字段含义】腾讯云直播服务的 bizid
+ ///【推荐取值】请在 [实时音视频控制台](https://console.cloud.tencent.com/trtc) 依次单击【应用管理】=>【应用信息】，并在【旁路直播信息】中获取 bizid。
uint32_t bizId;
- ///【字段含义】最终转码后的视频分辨率的宽度。
- ///【推荐取值】推荐值：360px ，如果你是纯音频推流，请将 width × height 设为 0px × 0px，否则混流后会携带一条画布背景的视频流。
+ ///【字段含义】指定云端转码的目标分辨率（宽度）
+ ///【推荐取值】单位：像素值，推荐值：360，如果你只混合音频流，请将 width 和 height 均设置位 0，否则混流转码后的直播流中会有黑色背景。
uint32_t videoWidth;
- ///【字段含义】最终转码后的视频分辨率的高度。
- ///【推荐取值】推荐值：640px ，如果你是纯音频推流，请将 width × height 设为 0px × 0px，否则混流后会携带一条画布背景的视频流。
+ ///【字段含义】指定云端转码的目标分辨率（高度）
+ ///【推荐取值】单位：像素值，推荐值：640，如果你只混合音频流，请将 width 和 height 均设置位 0，否则混流转码后的直播流中会有黑色背景。
uint32_t videoHeight;
- ///【字段含义】最终转码后的视频分辨率的码率（kbps）。
- ///【推荐取值】如果填0，后台会根据videoWidth和videoHeight来估算码率，您也可以参考枚举定义TRTCVideoResolution_640_480的注释。
+ ///【字段含义】指定云端转码的目标视频码率（kbps）
+ ///【推荐取值】如果填0，TRTC 会根据 videoWidth 和 videoHeight 估算出一个合理的码率值，您也可以参考视频分辨率枚举定义中所推荐的码率值（见注释部分）。
uint32_t videoBitrate;
- ///【字段含义】最终转码后的视频分辨率的帧率（FPS）。
+ ///【字段含义】指定云端转码的目标视频帧率（FPS）
///【推荐取值】默认值：15fps，取值范围是 (0,30]。
uint32_t videoFramerate;
- ///【字段含义】最终转码后的视频分辨率的关键帧间隔（又称为 GOP）。
+ ///【字段含义】指定云端转码的目标视频关键帧间隔（GOP）
///【推荐取值】默认值：2，单位为秒，取值范围是 [1,8]。
uint32_t videoGOP;
- ///【字段含义】混合后画面的底色颜色，默认为黑色，格式为十六进制数字，比如：“0x61B9F1” 代表 RGB 分别为(97,158,241)。
- ///【推荐取值】默认值：0x000000，黑色
+ ///【字段含义】指定混合画面的底色颜色
+ ///【推荐取值】默认值：0x000000 代表黑色。格式为十六进制数字，比如：“0x61B9F1” 代表 RGB 分别为(97,158,241)。
uint32_t backgroundColor;
- ///【字段含义】混合后画面的背景图。
- ///【推荐取值】默认值：null，即不设置背景图
- ///【特别说明】背景图需要您事先在 “[控制台](https://console.cloud.tencent.com/trtc) => 应用管理 => 功能配置 => 素材管理” 中上传， <br>
- /// 上传成功后可以获得对应的“图片ID”，然后将“图片ID”转换成字符串类型并设置到 backgroundImage 里即可。 <br>
- /// 例如：假设“图片ID” 为 63，可以设置 backgroundImage = "63"; <br>
- const char * backgroundImage;
+ ///【字段含义】指定混合画面的背景图片
+ ///【推荐取值】默认值：空值，即不设置背景图片。
+ ///【特别说明】背景图需要您事先在 “[控制台](https://console.cloud.tencent.com/trtc) => 应用管理 => 功能配置 => 素材管理” 中单击【新增图片】按钮进行上传。
+ /// 上传成功后可以获得对应的“图片ID”，然后将“图片ID”转换成字符串类型并设置到 backgroundImage 里即可。
+ /// 例如：假设“图片ID” 为 63，可以设置 backgroundImage = @"63";
+ const char *backgroundImage;
- ///【字段含义】最终转码后的音频采样率。
+ ///【字段含义】指定云端转码的目标音频采样率
///【推荐取值】默认值：48000Hz。支持12000HZ、16000HZ、22050HZ、24000HZ、32000HZ、44100HZ、48000HZ。
uint32_t audioSampleRate;
- ///【字段含义】最终转码后的音频码率。
+ ///【字段含义】指定云端转码的目标音频码率
///【推荐取值】默认值：64kbps，取值范围是 [32，192]。
uint32_t audioBitrate;
- ///【字段含义】最终转码后的音频声道数
- ///【推荐取值】默认值：1。取值范围为 [1,2] 中的整型。
+ ///【字段含义】指定云端转码的音频声道数
+ ///【推荐取值】默认值：1，代表单声道。可设定的数值只有两个数字：1-单声道，2-双声道。
uint32_t audioChannels;
- ///【字段含义】每一路子画面的位置信息
- TRTCMixUser * mixUsersArray;
+ ///【字段含义】指定云端混流中每一路视频画面的位置、大小、图层以及流类型等信息
+ ///【推荐取值】该字段是一个 TRTCMixUser 类型的数组，数组中的每一个元素都用来代表每一路画面的信息。
+ TRTCMixUser *mixUsersArray;
- ///【字段含义】 数组 mixUsersArray 的大小
+ ///【字段含义】 数组 mixUsersArray 的元素个数
uint32_t mixUsersArraySize;
///【字段含义】输出到 CDN 上的直播流 ID
- /// 如不设置该参数，SDK 会执行默认逻辑，即房间里的多路流会混合到该接口调用者的视频流上，也就是 A+B =>A；
- /// 如果设置该参数，SDK 会将房间里的多路流混合到您指定的直播流 ID 上，也就是 A+B =>C。
- ///【推荐取值】默认值：null，即房间里的多路流会混合到该接口调用者的视频流上。
- const char * streamId;
+ ///【推荐取值】默认值：空值，即房间里的多路音视频流最终会混合到接口调用者的那一路音视频流上。
+ /// - 如不设置该参数，SDK 会执行默认逻辑，即房间里的多路音视频流会混合到该接口调用者的那一路音视频流上，也就是 A + B => A。
+ /// - 如您设置该参数，SDK 会将房间里的多路音视频流混合到您指定的直播流上，也就是 A + B => C（C 代表您指定的 streamId）。
+ const char *streamId;
TRTCTranscodingConfig()
- : mode(TRTCTranscodingConfigMode_Unknown)
- , appId(0)
- , bizId(0)
- , videoWidth(0)
- , videoHeight(0)
- , videoBitrate(0)
- , videoFramerate(15)
- , videoGOP(2)
- , audioSampleRate(48000)
- , audioBitrate(64)
- , audioChannels(1)
- , mixUsersArray(nullptr)
- , mixUsersArraySize(0)
- , backgroundColor(0)
- , backgroundImage(nullptr)
- , streamId(nullptr)
- {}
+ : mode(TRTCTranscodingConfigMode_Unknown),
+ appId(0),
+ bizId(0),
+ videoWidth(0),
+ videoHeight(0),
+ videoBitrate(0),
+ videoFramerate(15),
+ videoGOP(2),
+ audioSampleRate(48000),
+ audioBitrate(64),
+ audioChannels(1),
+ mixUsersArray(nullptr),
+ mixUsersArraySize(0),
+ backgroundColor(0),
+ backgroundImage(nullptr),
+ streamId(nullptr) {
+ }
};
/**
- * 5.13 CDN 旁路推流参数
+ * 5.13 向非腾讯云 CDN 上发布音视频流时需设置的转推参数
+ *
+ * TRTC 的后台服务支持通过标准 RTMP 协议，将其中的音视频流发布到第三方直播 CDN 服务商。
+ * 如果您使用腾讯云直播 CDN 服务，可无需关注此参数，直接使用 {@link startPublish} 接口即可。
*/
-struct TRTCPublishCDNParam
-{
- /// 腾讯云 AppID，请在 [实时音视频控制台](https://console.cloud.tencent.com/rav) 选择已经创建的应用，单击【帐号信息】，在“直播信息”中获取
+struct TRTCPublishCDNParam {
+ ///【字段含义】腾讯云直播服务的 AppID
+ ///【推荐取值】请在 [实时音视频控制台](https://console.cloud.tencent.com/trtc) 依次单击【应用管理】=>【应用信息】，并在【旁路直播信息】中获取 appid。
uint32_t appId;
- /// 腾讯云直播 bizid，请在 [实时音视频控制台](https://console.cloud.tencent.com/rav) 选择已经创建的应用，单击【帐号信息】，在“直播信息”中获取
+ ///【字段含义】腾讯云直播服务的 bizid
+ ///【推荐取值】请在 [实时音视频控制台](https://console.cloud.tencent.com/trtc) 依次单击【应用管理】=>【应用信息】，并在【旁路直播信息】中获取 bizid。
uint32_t bizId;
- /// 旁路转推的 URL
- const char * url;
-
- TRTCPublishCDNParam()
- : url(nullptr)
- , appId(0)
- , bizId(0)
- {
+ ///【字段含义】指定该路音视频流在第三方直播服务商的推流地址（RTMP 格式）
+ ///【推荐取值】各家服务商的推流地址规则差异较大，请根据目标服务商的要求填写合法的推流 URL，TRTC 的后台服务器会按照您填写的 URL 向第三方服务商推送标准格式音视频流。
+ ///【特别说明】推流 URL 必须为 RTMP 格式，必须符合您的目标直播服务商的规范要求，否则目标服务商会拒绝来自 TRTC 后台服务的推流请求。
+ const char *url;
+ TRTCPublishCDNParam() : url(nullptr), appId(0), bizId(0) {
}
};
/**
- * 5.14 录音参数
+ * 5.14 本地音频文件的录制参数
*
- * 请正确填写参数，确保录音文件顺利生成。
+ * 该参数用于在音频录制接口 {@link startAudioRecording} 中指定录制参数。
*/
struct TRTCAudioRecordingParams {
+ ///【字段含义】录音文件的保存路径（必填）。
+ ///【特别说明】该路径需精确到文件名及格式后缀，格式后缀用于决定录音文件的格式，目前支持的格式有 PCM、WAV 和 AAC。
+ /// 例如：假如您指定路径为 "mypath/record/audio.aac"，代表您希望 SDK 生成一个 AAC 格式的音频录制文件。
+ /// 请您指定一个有读写权限的合法路径，否则录音文件无法生成。
+ const char *filePath;
- ///【字段含义】文件路径（必填），录音文件的保存路径。该路径需要用户自行指定，请确保路径存在且可写。
- ///【特别说明】该路径需精确到文件名及格式后缀，格式后缀决定录音文件的格式，目前支持的格式有 PCM、WAV 和 AAC。
- /// 例如，指定路径为 path/to/audio.aac，则会生成一个 AAC 格式的文件。
- /// 请指定一个有读写权限的合法路径，否则录音文件无法生成。
- const char * filePath;
-
- TRTCAudioRecordingParams()
- : filePath(nullptr)
- {
+ ///【字段含义】音频录制内容类型。
+ ///【特别说明】默认录制所有本地和远端音频。
+ TRTCAudioRecordingContent recordingContent;
+ TRTCAudioRecordingParams() : filePath(nullptr), recordingContent(TRTCAudioRecordingContentAll) {
}
};
/**
- * 5.15 音效
+ * 5.15 本地媒体文件的录制参数
+ *
+ * 该参数用于在本地媒体文件的录制接口 {@link startLocalRecording} 中指定录制相关参数。
+ * 接口 startLocalRecording 是接口 startAudioRecording 的能力加强版本，前者可以录制视频文件，后者只能录制音频文件。
*/
-struct TRTCAudioEffectParam {
+struct TRTCLocalRecordingParams {
+ ///【字段含义】录制的文件地址（必填），请确保路径有读写权限且合法，否则录制文件无法生成。
+ ///【特别说明】该路径需精确到文件名及格式后缀，格式后缀用于决定录制出的文件格式，目前支持的格式暂时只有 MP4。
+ /// 例如：假如您指定路径为 "mypath/record/test.mp4"，代表您希望 SDK 生成一个 MP4 格式的本地视频文件。
+ /// 请您指定一个有读写权限的合法路径，否则录制文件无法生成。
+ const char *filePath = "";
+
+ ///【字段含义】媒体录制类型，默认值：TRTCRecordTypeBoth，即同时录制音频和视频。
+ TRTCLocalRecordType recordType = TRTCLocalRecordType_Both;
+
+ ///【字段含义】interval 录制信息更新频率，单位毫秒，有效范围：1000-10000。默认值为-1，表示不回调。
+ int interval = -1;
+};
- ///【字段含义】音效 ID，
- ///【特殊说明】SDK 允许播放多路音效，因此需要音效 ID 进行标记，用于控制音效的开始、停止、音量等
+/**
+ * 5.16 音效参数（已废弃）
+ *
+ * TRTC 中的“音效”特指一些短暂的音频文件，通常仅有几秒钟的播放时间，比如“鼓掌声”、“欢笑声”等。
+ * 该参数用于在早期版本的音效播放接口 {@link TRTCCloud#playAudioEffect} 中指定音效文件（即短音频文件）的路径和播放次数等。
+ * 在 7.3 版本以后，音效接口已被新的接口 {@link TXAudioEffectManager#startPlayMusic} 所取代。
+ * 您在指定 startPlayMusic 的参数 {@link TXAudioMusicParam} 时，如果将 “isShortFile” 设置为 true，即为“音效”文件。
+ */
+struct TRTCAudioEffectParam {
+ ///【字段含义】音效 ID
+ ///【特别说明】SDK 允许播放多路音效，因此需要音效 ID 进行标记，用于控制音效的开始、停止、音量等。
int effectId;
- ///【字段含义】音效路径，支持的文件格式：aac, mp3。
- const char * path;
+ ///【字段含义】音效文件路径，支持的文件格式：aac, mp3, m4a。
+ const char *path;
///【字段含义】循环播放次数
- ///【推荐取值】取值范围为0 - 任意正整数，默认值：0。0表示播放音效一次；1表示播放音效两次；以此类推
+ ///【推荐取值】取值范围为0 - 任意正整数，默认值：0，表示播放音效一次；1表示播放音效两次；以此类推。
int loopCount;
///【字段含义】音效是否上行
@@ -1033,366 +1270,147 @@ struct TRTCAudioEffectParam {
///【推荐取值】取值范围为0 - 100；默认值：100
int volume;
- TRTCAudioEffectParam(const int _effectId, const char *_path)
- : loopCount(0)
- , publish(false)
- , volume(100)
- {
+ TRTCAudioEffectParam(const int _effectId, const char *_path) : loopCount(0), publish(false), volume(100) {
effectId = _effectId;
path = _path;
}
};
/**
- * 5.16 切换房间参数
+ * 5.17 房间切换参数
+ *
+ * 该参数用于切换房间接口{@link switchRoom}，可以让用户从一个房间快速切换到另一个房间。
*/
struct TRTCSwitchRoomConfig {
- ///【字段含义】数字房间号码 [选填]，在同一个房间内的用户可以看到彼此并进行视频通话。
+ ///【字段含义】数字房间号码 [选填]，在同一个房间内的用户可以看到彼此并能够进行音视频通话。
///【推荐取值】取值范围：1 - 4294967294。
///【特别说明】roomId 和 strRoomId 必须并且只能填一个。若两者都填，则优先选择 roomId。
uint32_t roomId;
- ///【字段含义】字符串房间号码 [选填]，在同一个房间内的用户可以看到彼此并进行视频通话。
+ ///【字段含义】字符串房间号码 [选填]，在同一个房间内的用户可以看到彼此并能够进行音视频通话。
///【特别说明】roomId 和 strRoomId 必须并且只能填一个。若两者都填，则优先选择 roomId。
const char *strRoomId;
- ///【字段含义】用户签名 [选填]，当前 userId 对应的验证签名，相当于登录密码。不填时，SDK 会继续使用旧的 userSig，
- /// 但用户必须保证旧的 userSig 仍在有效期内，否则会造成进房失败等后果。
- ///【推荐取值】具体计算方法请参见 [如何计算UserSig](https://cloud.tencent.com/document/product/647/17275)。
+ ///【字段含义】用户签名 [选填]，当前 userId 对应的验证签名，相当于登录密码。
+ /// 如果您在切换房间时不指定新计算出的 userSig，SDK 会继续使用您在进入房间时（enterRoom）时所指定的 userSig。
+ /// 这就需要您必须保证旧的 userSig 在切换房间的那一刻仍在签名允许的效期内，否则会导致房间切换失败。
+ ///【推荐取值】具体计算方法请参考 [如何计算UserSig](https://cloud.tencent.com/document/product/647/17275)。
const char *userSig;
- ///【字段含义】房间签名 [选填]，当您希望某个房间只能让特定的 userId 进入时，需要使用 privateMapKey 进行权限保护。
+ ///【字段含义】用于权限控制的权限票据（选填），当您希望某个房间只能让特定的 userId 进入时，需要使用 privateMapKey 进行权限保护。
///【推荐取值】仅建议有高级别安全需求的客户使用，更多详情请参见 [进房权限保护](https://cloud.tencent.com/document/product/647/32240)。
const char *privateMapKey;
- TRTCSwitchRoomConfig()
- : roomId(0)
- , strRoomId(nullptr)
- , userSig(nullptr)
- , privateMapKey(nullptr)
- {
-
+ TRTCSwitchRoomConfig() : roomId(0), strRoomId(nullptr), userSig(nullptr), privateMapKey(nullptr) {
}
};
/**
- * 5.17 自己本地的音视频统计信息
+ * 5.20 屏幕分享的目标信息（仅适用于桌面系统）
+ *
+ * 在用户进行屏幕分享时，可以选择抓取整个桌面，也可以仅抓取某个程序的窗口。
+ * TRTCScreenCaptureSourceInfo 用于描述待分享目标的信息，包括 ID、名称、缩略图等，该结构体中的字段信息均是只读的。
*/
-struct TRTCLocalStatistics
-{
- uint32_t width; ///< 视频宽度
-
- uint32_t height; ///< 视频高度
-
- uint32_t frameRate; ///< 帧率（fps）
-
- uint32_t videoBitrate; ///< 视频发送码率（Kbps）
-
- uint32_t audioSampleRate; ///< 音频采样率（Hz）
-
- uint32_t audioBitrate; ///< 音频发送码率（Kbps）
-
- TRTCVideoStreamType streamType; ///< 流类型（大画面 | 小画面 | 辅路画面）
-
- /// 音频设备采集状态，用于检测外接音频设备的健康度
- /// 0：采集设备状态正常；1：检测到长时间静音；2：检测到破音；3：检测到声音异常间断。
- uint32_t audioCaptureState;
-
- TRTCLocalStatistics()
- : width(0)
- , height(0)
- , frameRate(0)
- , videoBitrate(0)
- , audioSampleRate(0)
- , audioBitrate(0)
- , streamType(TRTCVideoStreamTypeBig)
- , audioCaptureState(0)
- {
-
- }
+// Structure for storing window thumbnails and icons.
+struct TRTCImageBuffer {
+ const char *buffer; ///< image content in BGRA format
+ uint32_t length; ///< buffer size
+ uint32_t width; ///< image width
+ uint32_t height; ///< image height
+ TRTCImageBuffer() : buffer(nullptr), length(0), width(0), height(0){};
};
-/**
- * 5.18 远端成员的音视频统计信息
- */
-struct TRTCRemoteStatistics
-{
- /// 用户 ID，指定是哪个用户的视频流
- const char * userId;
-
- /// 该线路的总丢包率（％）
- /// 这个值越小越好，例如，丢包率为0表示网络很好。
- /// 丢包率是该线路的 userId 从上行到服务器再到下行的总丢包率。
- /// 如果 downLoss 为0，但是 finalLoss 不为0，说明该 userId 上行时出现了无法恢复的丢包。
- uint32_t finalLoss;
-
- /// 视频宽度
- uint32_t width;
- /// 视频高度
- uint32_t height;
-
- /// 接收帧率（fps）
- uint32_t frameRate;
-
- /// 视频码率（Kbps）
- uint32_t videoBitrate;
-
- /// 音频采样率（Hz）
- uint32_t audioSampleRate;
-
- /// 音频码率（Kbps）
- uint32_t audioBitrate;
-
- /// 播放时延（ms）
- uint32_t jitterBufferDelay;
-
- /// 端对端延迟（ms）
- /// 该字段为全链路延迟统计，链路包含：采集->编码->网络传输->接收->缓冲->解码->播放
- /// 延迟以 audio 为基准进行计算。需要本地和远端均为8.5版本以上时才生效
- /// 若远端用户为低版本，对应延迟会回调为0，此时代表无效值
- uint32_t point2PointDelay;
+struct TRTCScreenCaptureSourceInfo {
+ ///【字段含义】采集源类型（是分享整个屏幕？还是分享某个窗口？）
+ TRTCScreenCaptureSourceType type;
- /// 音频播放卡顿累计时长（ms）
- uint32_t audioTotalBlockTime;
+ ///【字段含义】采集源的ID，对于窗口，该字段代表窗口的 ID；对于屏幕，该字段代表显示器的 ID。
+ TXView sourceId;
- /// 音频播放卡顿率，音频卡顿累计时长占音频总播放时长的百分比 (%)
- uint32_t audioBlockRate;
+ ///【字段含义】采集源名称（采用 UTF8 编码）
+ const char *sourceName;
- /// 视频播放卡顿累计时长（ms）
- uint32_t videoTotalBlockTime;
+ ///【字段含义】分享窗口的缩略图
+ TRTCImageBuffer thumbBGRA;
- /// 视频播放卡顿率，视频卡顿累计时长占音频总播放时长的百分比（%）
- uint32_t videoBlockRate;
+ ///【字段含义】分享窗口的图标
+ TRTCImageBuffer iconBGRA;
- /// 流类型（大画面 | 小画面 | 辅路画面）
- TRTCVideoStreamType streamType;
+ ///【字段含义】是否为最小化窗口
+ bool isMinimizeWindow;
- TRTCRemoteStatistics()
- : userId(nullptr)
- , finalLoss(0)
- , width(0)
- , height(0)
- , frameRate(0)
- , videoBitrate(0)
- , audioSampleRate(0)
- , audioBitrate(0)
- , jitterBufferDelay(0)
- , point2PointDelay(0)
- , audioTotalBlockTime(0)
- , audioBlockRate(0)
- , videoTotalBlockTime(0)
- , videoBlockRate(0)
- , streamType(TRTCVideoStreamTypeBig)
- {
+ ///【字段含义】是否为主显示屏（适用于多显示器的情况）
+ bool isMainScreen;
- }
+ TRTCScreenCaptureSourceInfo() : type(TRTCScreenCaptureSourceTypeUnknown), sourceId(nullptr), sourceName(nullptr), isMinimizeWindow(false), isMainScreen(false){};
};
/**
- * 5.19 统计数据
- */
-struct TRTCStatistics
-{
-
- /// C -> S 上行丢包率（％），
- /// 该值越小越好，例如，丢包率为0表示网络很好，
- /// 丢包率为30@%则意味着 SDK 向服务器发送的数据包中会有30@%丢失在上行传输中。
- uint32_t upLoss;
-
- /// S -> C 下行丢包率（％），
- /// 该值越小越好，例如，丢包率为0表示网络很好，
- /// 丢包率为30@%则意味着 SDK 向服务器发送的数据包中会有30@%丢失在下行传输中。
- uint32_t downLoss;
-
- /// 当前 App 的 CPU 使用率（％）
- uint32_t appCpu;
-
- /// 当前系统的 CPU 使用率（％）
- uint32_t systemCpu;
-
- /// 延迟（毫秒），
- /// 指 SDK 到腾讯云服务器的一次网络往返时间，该值越小越好。
- /// 一般低于 50ms 的 rtt 相对理想，而高于 100ms 的 rtt 会引入较大的通话延时。
- /// 由于数据上下行共享一条网络连接，所以 local 和 remote 的 rtt 相同。
- uint32_t rtt;
-
- /// 总接收字节数（包含信令和音视频）
- uint32_t receivedBytes;
-
- /// 总发送字节总数（包含信令和音视频）
- uint32_t sentBytes;
-
- /// 本地的音视频统计信息，可能有主画面、小画面以及辅路画面等多路的情况，因此是一个数组
- TRTCLocalStatistics * localStatisticsArray;
-
- /// 数组 localStatisticsArray 的大小
- uint32_t localStatisticsArraySize;
-
- /// 远端成员的音视频统计信息，可能有主画面、小画面以及辅路画面等多路的情况，因此是一个数组
- TRTCRemoteStatistics * remoteStatisticsArray;
-
- /// 数组 remoteStatisticsArray 的大小
- uint32_t remoteStatisticsArraySize;
-
- TRTCStatistics()
- : upLoss(0)
- , downLoss(0)
- , appCpu(0)
- , systemCpu(0)
- , rtt(0)
- , receivedBytes(0)
- , sentBytes(0)
- , localStatisticsArray(nullptr)
- , localStatisticsArraySize(0)
- , remoteStatisticsArray(nullptr)
- , remoteStatisticsArraySize(0)
- {
-
- }
-};
-
-/**
- * 5.20 用于存储屏幕分享窗口缩略图和图标的结构体
- */
-struct TRTCImageBuffer
-{
- const char * buffer; ///< 图内容
- uint32_t length; ///< 图缓存大小
- uint32_t width; ///< 图宽
- uint32_t height; ///< 图高
- TRTCImageBuffer()
- : buffer(nullptr)
- , length(0)
- , width(0)
- , height(0)
- {};
-};
-
-/**
- * 5.21 屏幕分享窗口信息
+ * 5.21 可分享的屏幕和窗口的列表
*
- * 您可以通过 getScreenCaptureSources() 枚举可共享的窗口列表，列表通过 ITRTCScreenCaptureSourceList 返回
+ * 此结构体的作用相当于 std::vector<TRTCScreenCaptureSourceInfo>，用于解决不同版本的 STL 容器的二进制兼容问题。
*/
-struct TRTCScreenCaptureSourceInfo {
- TRTCScreenCaptureSourceType type; ///< 采集源类型
- TXView sourceId; ///< 采集源 ID；对于窗口，该字段指示窗口句柄；对于屏幕，该字段指示屏幕 ID
- const char * sourceName; ///< 采集源名称，UTF8 编码
- TRTCImageBuffer thumbBGRA; ///< 缩略图内容
- TRTCImageBuffer iconBGRA; ///< 图标内容
- bool isMinimizeWindow; ///< 是否为最小化窗口，通过 getScreenCaptureSources 获取列表时的窗口状态，仅采集源为 Window 时才可用
- bool isMainScreen; ///< 是否为主屏，是否为主屏，仅采集源类型为 Screen 时才可用
- TRTCScreenCaptureSourceInfo()
- : type(TRTCScreenCaptureSourceTypeUnknown)
- , sourceId(nullptr)
- , sourceName(nullptr)
- , isMinimizeWindow(false)
- , isMainScreen(false)
- {};
-};
+class ITRTCScreenCaptureSourceList {
+ protected:
+ virtual ~ITRTCScreenCaptureSourceList() {
+ }
-/**
- * 5.22 屏幕分享窗口列表
- */
-class ITRTCScreenCaptureSourceList
-{
-protected:
- virtual ~ITRTCScreenCaptureSourceList() {}
-public:
+ public:
/**
- * @return 窗口个数
+ * Size of this list.
*/
virtual uint32_t getCount() = 0;
/**
- * @return 窗口信息
+ * Get element(TRTCScreenCaptureSourceInfo) by index.
*/
virtual TRTCScreenCaptureSourceInfo getSourceInfo(uint32_t index) = 0;
/**
- * @brief 遍历完窗口列表后，调用 release 释放资源。
+ * Don't use delete!!!
*/
virtual void release() = 0;
};
/**
- * 5.23 屏幕分享参数
+ * 5.22 屏幕分享的进阶控制参数
*
- * 您可以通过设置结构体内的参数控制屏幕分享边框的颜色、宽度、是否采集鼠标等参数
+ * 该参数用于屏幕分享相关的接口{@link selectScreenCaptureTarget}，用于在指定分享目标时设定一系列进阶控制参数。
+ * 比如：是否采集鼠标、是否要采集子窗口、是否要在被分享目标周围绘制一个边框等。
*/
struct TRTCScreenCaptureProperty {
- bool enableCaptureMouse; ///< 是否采集目标内容时顺带采集鼠标，默认为 true
- bool enableHighLight; ///< 是否高亮正在共享的窗口，默认为 true
- bool enableHighPerformance; ///< 是否开启高性能模式（只会在分享屏幕时会生效），开启后屏幕采集性能最佳，但无法过滤远端的高亮边框，默认为 true
- int highLightColor; ///< 指定高亮边框颜色，RGB 格式，传入 0 时采用默认颜色，默认颜色为 #8CBF26
- int highLightWidth; ///< 指定高亮边框的宽度，传入0时采用默认描边宽度，默认宽度为 5，最大值为 50
- bool enableCaptureChildWindow; ///< 窗口采集时是否采集子窗口（与采集窗口具有 Owner 或 Popup 属性），默认为 false
-
- TRTCScreenCaptureProperty()
- : enableCaptureMouse(true)
- , enableHighLight(true)
- , enableHighPerformance(true)
- , highLightColor(0)
- , highLightWidth(0)
- , enableCaptureChildWindow(false)
- {
+ ///【字段含义】是否采集目标内容的同时采集鼠标，默认为 true。
+ bool enableCaptureMouse;
- }
-};
+ ///【字段含义】是否高亮正在共享的窗口（在被分享目标周围绘制一个边框），默认为 true。
+ bool enableHighLight;
-/**
- * 5.24 设备列表和设备 Item 信息
- *
- * 以下定义仅用于兼容原有接口，具体定义参见 ITXDeviceManager.h 文件
- */
-typedef ITXDeviceCollection ITRTCDeviceCollection;
-typedef ITXDeviceInfo ITRTCDeviceInfo;
-/**
- * 5.25 本地录制参数
- *
- */
-enum TRTCLocalRecordType {
- /// 仅录制音频
- TRTCLocalRecordType_Audio = 0,
+ ///【字段含义】是否开启高性能模式（只会在分享屏幕时会生效），默认为 true。
+ ///【特殊说明】开启后屏幕采集性能最佳，但会丧失抗遮挡能力，如果您同时开启 enableHighLight + enableHighPerformance，远端用户可以看到高亮的边框。
+ bool enableHighPerformance;
- /// 仅录制视频
- TRTCLocalRecordType_Video = 1,
+ ///【字段含义】指定高亮边框的颜色，RGB 格式，传入 0 时代表采用默认颜色，默认颜色为 #8CBF26。
+ int highLightColor;
- /// 同时录制音频、视频
- TRTCLocalRecordType_Both = 2,
+ ///【字段含义】指定高亮边框的宽度，传入0时采用默认描边宽度，默认宽度为 5px，您可以设置的最大值为 50。
+ int highLightWidth;
+ ///【字段含义】窗口采集时是否采集子窗口（需要子窗口与被采集窗口具有 Owner 或 Popup 属性），默认为 false。
+ bool enableCaptureChildWindow;
+ TRTCScreenCaptureProperty() : enableCaptureMouse(true), enableHighLight(true), enableHighPerformance(true), highLightColor(0), highLightWidth(0), enableCaptureChildWindow(false) {
+ }
};
-struct TRTCLocalRecordingParams {
- ///【字段含义】文件路径（必填），录制的文件地址，请自行指定，确保路径有读写权限且合法，否则录制文件无法生成。
- ///【特别说明】该路径需精确到文件名及格式后缀，格式后缀决定录制文件的格式，目前支持的格式只有 mp4。
- /// Windows建议在应用的私有数据目录中指定存放路径。
- ///【示例代码】在 %appdata%\\test 目录下录制 example.mp4 文件
- /// std::string filePath;
- /// std::wstring path;
- /// wchar_t fullPath[MAX_PATH] = { 0 };
- /// ::SHGetFolderPathW(NULL, CSIDL_APPDATA, NULL, 0, fullPath);
- /// path=fullPath;
- /// path += L"\\test\\example.mp4";
- /// filePath = txf_wstr2utf8(path);
- const char *filePath;
-
- ///【字段含义】媒体录制类型，默认为同时录制音频和视频。
- TRTCLocalRecordType recordType;
-
- ///interval 录制中事件（onLocalRecordDoing）的回调频率，单位毫秒，有效范围：1000-10000，默认为 -1 表示不回调
- int interval;
-
- TRTCLocalRecordingParams()
- : filePath(nullptr)
- , recordType(TRTCLocalRecordType_Both)
- , interval(-1)
- {
+typedef ITXDeviceCollection ITRTCDeviceCollection;
+typedef ITXDeviceInfo ITRTCDeviceInfo;
- }
-};
/// @}
-} // namespace trtc
+} // namespace liteav
+
+// 9.0 开始 C++ 接口将声明在 liteav 命名空间下，为兼容之前的使用方式，将 trtc 作为 liteav 的别名
+namespace trtc = liteav;
#ifdef _WIN32
-using namespace trtc;
+using namespace liteav;
#endif
#endif / *__TRTCCLOUDDEF_H__ * /
+/// @}
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/cpp_interface/TXLiteAVCode.h b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/cpp_interface/TXLiteAVCode.h
index b806455..2867fa5 100644
--- a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/cpp_interface/TXLiteAVCode.h
+++ b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Headers/cpp_interface/TXLiteAVCode.h
@@ -188,6 +188,7 @@ typedef enum TXLiteAVError
ERR_ROOM_REQUEST_CLOSE_VIDEO_TIMEOUT = -3313, ///< 请求关闭视频超时
ERR_ROOM_REQUEST_SET_RECEIVE_TIMEOUT = -3314, ///< 请求接收视频项超时
ERR_ROOM_REQUEST_TOKEN_INVALID_PARAMETER = -3315, ///< 请求 token 无效参数，请检查 TRTCParams.userSig 是否填写正确
+ ERR_ROOM_REQUEST_EXIT_ROOM_WHEN_ENTERING_ROOM = -3341, ///< 进房尚未成功时，收到了退房请求
ERR_ROOM_REQUEST_AES_TOKEN_RETURN_ERROR = -3329, ///< 请求 AES TOKEN 时，server 返回的内容是空的
ERR_ACCIP_LIST_EMPTY = -3331, ///< 请求接口机 IP 返回的列表为空的
@@ -406,6 +407,8 @@ typedef enum TXLiteAVEvent
EVT_MIC_RELEASE_SUCC = 2029, ///< 释放麦克风占用
EVT_AUDIO_DEVICE_ROUTE_CHANGED = 2030, ///< 音频设备的route发生改变，即当前的输入输出设备发生改变，比如耳机被拔出
EVT_PLAY_GET_FLVSESSIONKEY = 2031, ///< TXLivePlayer 接收到http响应头中的 flvSessionKey 信息
+ EVT_AUDIO_SESSION_INTERRUPT = 2032, ///< Audio Session Interrupt事件
+
EVT_ROOM_ENTER = 1018, ///< 进入房间成功
EVT_ROOM_EXIT = 1019, ///< 退出房间
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Info.plist b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Info.plist
index 13bd72e..fdbe740 100644
Binary files a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Info.plist and b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Info.plist differ
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Modules/module.modulemap b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Modules/module.modulemap
index 920e668..c5fe93e 100644
--- a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Modules/module.modulemap
+++ b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/Modules/module.modulemap
@@ -3,6 +3,7 @@ framework module TXLiteAVSDK_TRTC {
exclude header "TXLiteAVEncodedDataProcessingListener.h"
exclude header "TXLiteAVBuffer.h"
exclude header "cpp_interface/ITRTCCloud.h"
+ exclude header "cpp_interface/ITRTCStatistics.h"
exclude header "cpp_interface/ITXAudioEffectManager.h"
exclude header "cpp_interface/ITXDeviceManager.h"
exclude header "cpp_interface/TRTCCloudCallback.h"
diff --git a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/TXLiteAVSDK_TRTC b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/TXLiteAVSDK_TRTC
index 610cbe2..f377fa2 100644
Binary files a/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/TXLiteAVSDK_TRTC and b/HHVDoctorSDK/TXLiteAVSDK_TRTC.framework/TXLiteAVSDK_TRTC differ