hh_public / hhvDoctorSDK.ios

Go to a project
Toggle navigation Toggle navigation pinning
wangguolei
d88a5da9 1 parent 4cc01c45

remove pay

Inline Side-by-side
Showing 16 changed files with 1731 additions and 1170 deletions

Too many changes to show.
Reload with full diff Plain diff Email patch

To preserve performance only 16 of 16+ files are displayed.

1 Pod::Spec.new do |s| 1 Pod::Spec.new do |s|
2 s.name = "HHVDoctorSDK" 2 s.name = "HHVDoctorSDK"
3 - s.version = "3.1.4.062820" 3 + s.version = "3.1.2.080214"
4 s.summary = "和缓视频医生 SDK" 4 s.summary = "和缓视频医生 SDK"
5 5
6 s.description = <<-DESC 6 s.description = <<-DESC
No preview for this file type
This diff could not be displayed because it is too large.
This diff could not be displayed because it is too large.
1 -/* 1 +/**
2 * Module: TRTCCloudDelegate @ TXLiteAVSDK 2 * Module: TRTCCloudDelegate @ TXLiteAVSDK
3 - *  
4 - * Function: 腾讯云视频通话功能的事件回调接口  
5 - * 3 + * Function: 腾讯云实时音视频的事件回调接口
6 */ 4 */
7 - 5 +/// @defgroup TRTCCloudDelegate_ios TRTCCloudDelegate
  6 +/// 腾讯云实时音视频的事件回调接口
  7 +/// @{
8 #import <Foundation/Foundation.h> 8 #import <Foundation/Foundation.h>
9 #import "TRTCCloudDef.h" 9 #import "TRTCCloudDef.h"
10 #import "TXLiteAVCode.h" 10 #import "TXLiteAVCode.h"
@@ -14,58 +14,61 @@ NS_ASSUME_NONNULL_BEGIN @@ -14,58 +14,61 @@ NS_ASSUME_NONNULL_BEGIN
14 @class TRTCCloud; 14 @class TRTCCloud;
15 @class TRTCStatistics; 15 @class TRTCStatistics;
16 16
17 -  
18 -/// @defgroup TRTCCloudDelegate_ios TRTCCloudDelegate  
19 -/// 腾讯云视频通话功能的事件回调接口  
20 -/// @{  
21 @protocol TRTCCloudDelegate <NSObject> 17 @protocol TRTCCloudDelegate <NSObject>
22 @optional 18 @optional
23 19
24 ///////////////////////////////////////////////////////////////////////////////// 20 /////////////////////////////////////////////////////////////////////////////////
25 // 21 //
26 -// （一）错误事件和警告事件 22 +// 错误事件和警告事件
27 // 23 //
28 ///////////////////////////////////////////////////////////////////////////////// 24 /////////////////////////////////////////////////////////////////////////////////
29 /// @name 错误事件和警告事件 25 /// @name 错误事件和警告事件
30 /// @{ 26 /// @{
  27 +
31 /** 28 /**
32 - * 1.1 错误回调，表示 SDK 不可恢复的错误，一定要监听并分情况给用户适当的界面提示。 29 + * 1.1 错误事件回调
  30 + *
  31 + * 错误事件，表示 SDK 抛出的不可恢复的错误，比如进入房间失败或设备开启失败等。
  32 + * 参考文档：[错误码表](https://cloud.tencent.com/document/product/647/32257)
33 * 33 *
34 * @param errCode 错误码 34 * @param errCode 错误码
35 * @param errMsg 错误信息 35 * @param errMsg 错误信息
36 * @param extInfo 扩展信息字段，个别错误码可能会带额外的信息帮助定位问题 36 * @param extInfo 扩展信息字段，个别错误码可能会带额外的信息帮助定位问题
37 */ 37 */
38 -- (void)onError:(TXLiteAVError)errCode errMsg:(nullable NSString *)errMsg extInfo:(nullable NSDictionary*)extInfo; 38 +- (void)onError:(TXLiteAVError)errCode errMsg:(nullable NSString *)errMsg extInfo:(nullable NSDictionary *)extInfo;
39 39
40 /** 40 /**
41 - * 1.2 警告回调，用于告知您一些非严重性问题，例如出现了卡顿或者可恢复的解码失败。 41 + * 1.2 警告事件回调
  42 + *
  43 + * 警告事件，表示 SDK 抛出的提示性问题，比如视频出现卡顿或 CPU 使用率太高等。
  44 + * 参考文档：[错误码表](https://cloud.tencent.com/document/product/647/32257)
42 * 45 *
43 * @param warningCode 警告码 46 * @param warningCode 警告码
44 * @param warningMsg 警告信息 47 * @param warningMsg 警告信息
45 * @param extInfo 扩展信息字段，个别警告码可能会带额外的信息帮助定位问题 48 * @param extInfo 扩展信息字段，个别警告码可能会带额外的信息帮助定位问题
46 */ 49 */
47 -- (void)onWarning:(TXLiteAVWarning)warningCode warningMsg:(nullable NSString *)warningMsg extInfo:(nullable NSDictionary*)extInfo; 50 +- (void)onWarning:(TXLiteAVWarning)warningCode warningMsg:(nullable NSString *)warningMsg extInfo:(nullable NSDictionary *)extInfo;
48 51
49 /// @} 52 /// @}
50 -  
51 ///////////////////////////////////////////////////////////////////////////////// 53 /////////////////////////////////////////////////////////////////////////////////
52 // 54 //
53 -// （二）房间事件回调 55 +// 房间相关事件回调
54 // 56 //
55 ///////////////////////////////////////////////////////////////////////////////// 57 /////////////////////////////////////////////////////////////////////////////////
56 -/// @name 房间事件回调 58 +/// @name 房间相关事件回调
57 /// @{ 59 /// @{
  60 +
58 /** 61 /**
59 - * 2.1 已加入房间的回调 62 + * 2.1 进入房间成功与否的事件回调
60 * 63 *
61 - * 调用 TRTCCloud 中的 enterRoom() 接口执行进房操作后，会收到来自 SDK 的 onEnterRoom(result) 回调： 64 + * 调用 TRTCCloud 中的 enterRoom() 接口执行进房操作后，会收到来自 TRTCCloudDelegate 的 onEnterRoom(result) 回调：
  65 + * - 如果加入成功，回调 result 会是一个正数（result > 0），代表进入房间所消耗的时间，单位是毫秒（ms）。
  66 + * - 如果加入失败，回调 result 会是一个负数（result < 0），代表失败原因的错误码。
  67 + * 进房失败的错误码含义请参见[错误码表](https://cloud.tencent.com/document/product/647/32257)。
62 * 68 *
63 - * - 如果加入成功，result 会是一个正数（result > 0），代表加入房间的时间消耗，单位是毫秒（ms）。  
64 - * - 如果加入失败，result 会是一个负数（result < 0），代表进房失败的错误码。  
65 - * 进房失败的错误码含义请参见[错误码](https://cloud.tencent.com/document/product/647/32257)。  
66 - *  
67 - * @note 在 Ver6.6 之前的版本，只有进房成功会抛出 onEnterRoom(result) 回调，进房失败由 onError() 回调抛出。  
68 - * 在 Ver6.6 及之后改为：进房成功返回正的 result，进房失败返回负的 result，同时进房失败也会有 onError() 回调抛出。 69 + * @note
  70 + * 1. 在 Ver6.6 之前的版本，只有进房成功会抛出 onEnterRoom(result) 回调，进房失败由 onError() 回调抛出。
  71 + * 2. 在 Ver6.6 之后的版本：无论进房成功或失败，均会抛出 onEnterRoom(result) 回调，同时进房失败也会有 onError() 回调抛出。
69 * 72 *
70 * @param result result > 0 时为进房耗时（ms），result < 0 时为进房错误码。 73 * @param result result > 0 时为进房耗时（ms），result < 0 时为进房错误码。
71 */ 74 */
@@ -75,12 +78,12 @@ NS_ASSUME_NONNULL_BEGIN @@ -75,12 +78,12 @@ NS_ASSUME_NONNULL_BEGIN
75 * 2.2 离开房间的事件回调 78 * 2.2 离开房间的事件回调
76 * 79 *
77 * 调用 TRTCCloud 中的 exitRoom() 接口会执行退出房间的相关逻辑，例如释放音视频设备资源和编解码器资源等。 80 * 调用 TRTCCloud 中的 exitRoom() 接口会执行退出房间的相关逻辑，例如释放音视频设备资源和编解码器资源等。
78 - * 待资源释放完毕，SDK 会通过 onExitRoom() 回调通知到您。 81 + * 待 SDK 占用的所有资源释放完毕后，SDK 会抛出 onExitRoom() 回调通知到您。
79 * 82 *
80 - * 如果您要再次调用 enterRoom() 或者切换到其他的音视频 SDK，请等待 onExitRoom() 回调到来之后再执行相关操作。  
81 - * 否则可能会遇到音频设备（例如 iOS 里的 AudioSession）被占用等各种异常问题。 83 + * 如果您要再次调用 enterRoom() 或者切换到其他的音视频 SDK，请等待 onExitRoom() 回调到来后再执行相关操作。
  84 + * 否则可能会遇到例如摄像头、麦克风设备被强占等各种异常问题。
82 * 85 *
83 - * @param reason 离开房间原因，0：主动调用 exitRoom 退房；1：被服务器踢出当前房间；2：当前房间整个被解散。 86 + * @param reason 离开房间原因，0：主动调用 exitRoom 退出房间；1：被服务器踢出当前房间；2：当前房间整个被解散。
84 */ 87 */
85 - (void)onExitRoom:(NSInteger)reason; 88 - (void)onExitRoom:(NSInteger)reason;
86 89
@@ -96,320 +99,370 @@ NS_ASSUME_NONNULL_BEGIN @@ -96,320 +99,370 @@ NS_ASSUME_NONNULL_BEGIN
96 - (void)onSwitchRole:(TXLiteAVError)errCode errMsg:(nullable NSString *)errMsg; 99 - (void)onSwitchRole:(TXLiteAVError)errCode errMsg:(nullable NSString *)errMsg;
97 100
98 /** 101 /**
99 - * 2.4 请求跨房通话（主播 PK）的结果回调 102 + * 2.4 切换房间的结果回调
100 * 103 *
101 - * 调用 TRTCCloud 中的 connectOtherRoom() 接口会将两个不同房间中的主播拉通视频通话，也就是所谓的“主播PK”功能。  
102 - * 调用者会收到 onConnectOtherRoom() 回调来获知跨房通话是否成功，  
103 - * 如果成功，两个房间中的所有用户都会收到 PK 主播的 onUserVideoAvailable() 回调。 104 + * 调用 TRTCCloud 中的 switchRoom() 接口可以让用户快速地从一个房间切换到另一个房间，
  105 + * 待 SDK 切换完成后，会抛出 onSwitchRoom() 事件回调。
104 * 106 *
105 - * @param userId 要 PK 的目标主播 userid。  
106 * @param errCode 错误码，ERR_NULL 代表切换成功，其他请参见[错误码](https://cloud.tencent.com/document/product/647/32257)。 107 * @param errCode 错误码，ERR_NULL 代表切换成功，其他请参见[错误码](https://cloud.tencent.com/document/product/647/32257)。
107 * @param errMsg 错误信息。 108 * @param errMsg 错误信息。
108 */ 109 */
109 -- (void)onConnectOtherRoom:(NSString*)userId errCode:(TXLiteAVError)errCode errMsg:(nullable NSString *)errMsg; 110 +- (void)onSwitchRoom:(TXLiteAVError)errCode errMsg:(nullable NSString *)errMsg;
110 111
111 /** 112 /**
112 - * 2.5 结束跨房通话（主播 PK）的结果回调 113 + * 2.5 请求跨房通话的结果回调
  114 + *
  115 + * 调用 TRTCCloud 中的 connectOtherRoom() 接口会将两个不同房间中的主播拉通视频通话，也就是所谓的“主播PK”功能。
  116 + * 调用者会收到 onConnectOtherRoom() 回调来获知跨房通话是否成功，
  117 + * 如果成功，两个房间中的所有用户都会收到来自另一个房间中的 PK 主播的 onUserVideoAvailable() 回调。
  118 + *
  119 + * @param userId 要跨房通话的另一个房间中的主播的用户 ID。
  120 + * @param errCode 错误码，ERR_NULL 代表切换成功，其他请参见[错误码](https://cloud.tencent.com/document/product/647/32257)。
  121 + * @param errMsg 错误信息。
113 */ 122 */
114 -- (void)onDisconnectOtherRoom:(TXLiteAVError)errCode errMsg:(nullable NSString *)errMsg; 123 +- (void)onConnectOtherRoom:(NSString *)userId errCode:(TXLiteAVError)errCode errMsg:(nullable NSString *)errMsg;
115 124
116 /** 125 /**
117 - * 2.6 切换房间 (switchRoom) 的结果回调 126 + * 2.6 结束跨房通话的结果回调
118 */ 127 */
119 -- (void)onSwitchRoom:(TXLiteAVError)errCode errMsg:(nullable NSString *)errMsg; 128 +- (void)onDisconnectOtherRoom:(TXLiteAVError)errCode errMsg:(nullable NSString *)errMsg;
120 129
121 /// @} 130 /// @}
122 -  
123 ///////////////////////////////////////////////////////////////////////////////// 131 /////////////////////////////////////////////////////////////////////////////////
124 // 132 //
125 -// （三）成员事件回调 133 +// 用户相关事件回调
126 // 134 //
127 ///////////////////////////////////////////////////////////////////////////////// 135 /////////////////////////////////////////////////////////////////////////////////
128 -/// @name 成员事件回调 136 +/// @name 用户相关事件回调
129 /// @{ 137 /// @{
130 138
131 /** 139 /**
132 * 3.1 有用户加入当前房间 140 * 3.1 有用户加入当前房间
133 * 141 *
134 - * 出于性能方面的考虑，在两种不同的应用场景下，该通知的行为会有差别：  
135 - * - 通话场景（TRTCAppSceneVideoCall 和 TRTCAppSceneAudioCall）：该场景下用户没有角色的区别，任何用户进入房间都会触发该通知。  
136 - * - 直播场景（TRTCAppSceneLIVE 和 TRTCAppSceneVoiceChatRoom）：该场景不限制观众的数量，如果任何用户进出都抛出回调会引起很大的性能损耗，所以该场景下只有主播进入房间时才会触发该通知，观众进入房间不会触发该通知。 142 + * 出于性能方面的考虑，在 TRTC 两种不同的应用场景（即 AppScene，在 enterRoom 时通过第二个参数指定）下，该通知的行为会有差别：
  143 + * - 直播类场景（TRTCAppSceneLIVE 和 TRTCAppSceneVoiceChatRoom）：该场景下的用户区分主播和观众两种角色，只有主播进入房间时才会触发该通知，观众进入房间时不会触发该通知。
  144 + * - 通话类场景（TRTCAppSceneVideoCall 和 TRTCAppSceneAudioCall）：该场景下的用户没有角色的区分（可认为都是主播），任何用户进入房间都会触发该通知。
137 * 145 *
138 - *  
139 - * @note 注意 onRemoteUserEnterRoom 和 onRemoteUserLeaveRoom 只适用于维护当前房间里的“成员列表”，如果需要显示远程画面，建议使用监听 onUserVideoAvailable() 事件回调。  
140 - *  
141 - * @param userId 用户标识 146 + * @note
  147 + * 1. 事件回调 onRemoteUserEnterRoom 和 onRemoteUserLeaveRoom 只适用于维护当前房间里的“用户列表”，有此事件回调不代表一定有视频画面。
  148 + * 2. 如果需要显示远程画面，请监听代表某个用户是否有视频画面的 onUserVideoAvailable() 事件回调。
  149 + * @param userId 远端用户的用户标识
142 */ 150 */
143 - (void)onRemoteUserEnterRoom:(NSString *)userId; 151 - (void)onRemoteUserEnterRoom:(NSString *)userId;
144 152
145 /** 153 /**
146 * 3.2 有用户离开当前房间 154 * 3.2 有用户离开当前房间
147 * 155 *
148 - * 与 onRemoteUserEnterRoom 相对应，在两种不同的应用场景下，该通知的行为会有差别：  
149 - * - 通话场景（TRTCAppSceneVideoCall 和 TRTCAppSceneAudioCall）：该场景下用户没有角色的区别，任何用户的离开都会触发该通知。  
150 - * - 直播场景（TRTCAppSceneLIVE 和 TRTCAppSceneVoiceChatRoom）：只有主播离开房间时才会触发该通知，观众离开房间不会触发该通知。 156 + * 与 onRemoteUserEnterRoom 相对应，在两种不同的应用场景（即 AppScene，在 enterRoom 时通过第二个参数指定）下，该通知的行为会有差别：
  157 + * - 直播类场景（TRTCAppSceneLIVE 和 TRTCAppSceneVoiceChatRoom）：只有主播离开房间时才会触发该通知，观众离开房间不会触发该通知。
  158 + * - 通话类场景（TRTCAppSceneVideoCall 和 TRTCAppSceneAudioCall）：该场景下用户没有角色的区别，任何用户的离开都会触发该通知。
151 * 159 *
152 - * @param userId 用户标识  
153 - * @param reason 离开原因，0 表示用户主动退出房间，1 表示用户超时退出，2 表示被踢出房间。 160 + * @param userId 远端用户的用户标识
  161 + * @param reason 离开原因，0表示用户主动退出房间，1表示用户超时退出，2表示被踢出房间。
154 */ 162 */
155 - (void)onRemoteUserLeaveRoom:(NSString *)userId reason:(NSInteger)reason; 163 - (void)onRemoteUserLeaveRoom:(NSString *)userId reason:(NSInteger)reason;
156 164
157 /** 165 /**
158 - * 3.3 远端用户是否存在可播放的主路画面（一般用于摄像头） 166 + * 3.3 某远端用户发布/取消了主路视频画面
159 * 167 *
160 - * 当您收到 onUserVideoAvailable(userid, YES) 通知时，表示该路画面已经有可用的视频数据帧到达。  
161 - * 此时，您需要调用 startRemoteView(userid) 接口加载该用户的远程画面。  
162 - * 然后，您会收到名为 onFirstVideoFrame(userid) 的首帧画面渲染回调。 168 + * “主路画面”一般被用于承载摄像头画面。当您收到 onUserVideoAvailable(userId, true) 通知时，表示该路画面已经有可播放的视频帧到达。
  169 + * 此时，您需要调用 {@link startRemoteView} 接口订阅该用户的远程画面，订阅成功后，您会继续收到该用户的首帧画面渲染回调 onFirstVideoFrame(userid)。
163 * 170 *
164 - * 当您收到 onUserVideoAvailable(userid, NO) 通知时，表示该路远程画面已被关闭，  
165 - * 可能由于该用户调用了 muteLocalVideo() 或 stopLocalPreview()。 171 + * 当您收到 onUserVideoAvailable(userId, false) 通知时，表示该路远程画面已经被关闭，关闭的原因可能是该用户调用了 {@link muteLocalVideo} 或 {@link stopLocalPreview}。
166 * 172 *
167 - * @param userId 用户标识  
168 - * @param available 画面是否开启 173 + * @param userId 远端用户的用户标识
  174 + * @param available 该用户是否发布（或取消发布）了主路视频画面，true: 发布；false：取消发布。
169 */ 175 */
170 - (void)onUserVideoAvailable:(NSString *)userId available:(BOOL)available; 176 - (void)onUserVideoAvailable:(NSString *)userId available:(BOOL)available;
171 177
172 /** 178 /**
173 - * 3.4 远端用户是否存在可播放的辅路画面（一般用于屏幕分享） 179 + * 3.4 某远端用户发布/取消了辅路视频画面
174 * 180 *
175 - * @note 显示辅路画面使用的函数是 startRemoteSubStreamView() 而非 startRemoteView()。  
176 - * @param userId 用户标识  
177 - * @param available 屏幕分享是否开启 181 + * “辅路画面”一般被用于承载屏幕分享的画面。当您收到 onUserSubStreamAvailable(userId, true) 通知时，表示该路画面已经有可播放的视频帧到达。
  182 + * 此时，您需要调用 {@link startRemoteSubStreamView} 接口订阅该用户的远程画面，订阅成功后，您会继续收到该用户的首帧画面渲染回调 onFirstVideoFrame(userid)。
  183 + *
  184 + * @note 显示辅路画面使用的函数是 {@link startRemoteSubStreamView} 而非 {@link startRemoteView}。
  185 + *
  186 + * @param userId 远端用户的用户标识
  187 + * @param available 该用户是否发布（或取消发布）了辅路视频画面，true: 发布；false：取消发布。
178 */ 188 */
179 - (void)onUserSubStreamAvailable:(NSString *)userId available:(BOOL)available; 189 - (void)onUserSubStreamAvailable:(NSString *)userId available:(BOOL)available;
180 190
181 /** 191 /**
182 - * 3.5 远端用户是否存在可播放的音频数据 192 + * 3.5 某远端用户发布/取消了自己的音频
183 * 193 *
184 - * @param userId 用户标识  
185 - * @param available 声音是否开启 194 + * 当您收到 onUserAudioAvailable(userId, true) 通知时，表示该用户发布了自己的声音，此时 SDK 的表现为：
  195 + * - 在自动订阅模式下，您无需做任何操作，SDK 会自动播放该用户的声音。
  196 + * - 在手动订阅模式下，您可以通过 {@link muteRemoteAudio}(userid, false) 来播放该用户的声音。
  197 + *
  198 + * @note SDK 默认使用自动订阅模式，您可以通过 {@link setDefaultStreamRecvMode} 设置为手动订阅，但需要在您进入房间之前调用才生效。
  199 + *
  200 + * @param userId 远端用户的用户标识
  201 + * @param available 该用户是否发布（或取消发布）了自己的音频，true: 发布；false：取消发布。
186 */ 202 */
187 - (void)onUserAudioAvailable:(NSString *)userId available:(BOOL)available; 203 - (void)onUserAudioAvailable:(NSString *)userId available:(BOOL)available;
188 204
189 /** 205 /**
190 - * 3.6 开始渲染本地或远程用户的首帧画面 206 + * 3.6 SDK 开始渲染自己本地或远端用户的首帧画面
191 * 207 *
192 - * 如果 userId == nil，代表开始渲染本地采集的摄像头画面，需要您先调用 startLocalPreview 触发。  
193 - * 如果 userId != nil，代表开始渲染远程用户的首帧画面，需要您先调用 startRemoteView 触发。 208 + * SDK 会在渲染自己本地或远端用户的首帧画面时抛出该事件，您可以通过回调事件中的 userId 参数来判断事件来自于“本地”还是来自于“远端”。
  209 + * - 如果 userId 为空值，代表 SDK 已经开始渲染自己本地的视频画面，不过前提是您已经调用了 {@link startLocalPreview} 或 {@link startScreenCapture}。
  210 + * - 如果 userId 不为空，代表 SDK 已经开始渲染远端用户的视频画面，不过前提是您已经调用了 {@link startRemoteView} 订阅了该用户的视频画面。
194 * 211 *
195 - * @note 只有当您调用 startLocalPreivew()、startRemoteView() 或 startRemoteSubStreamView() 之后，才会触发该回调。 212 + * @note
  213 + * 1. 只有当您调用了 {@link startLocalPreview} 或 {@link startScreenCapture} 之后，才会触发自己本地的首帧画面事件回调。
  214 + * 2. 只有当您调用了 {@link startRemoteView} 或 {@link startRemoteSubStreamView} 之后，才会触发远端用户的首帧画面事件回调。
196 * 215 *
197 - * @param userId 本地或远程用户 ID，如果 userId == nil 代表本地，userId != nil 代表远程。  
198 - * @param streamType 视频流类型：摄像头或屏幕分享。  
199 - * @param width 画面宽度  
200 - * @param height 画面高度 216 + * @param userId 本地或远端的用户标识，如果 userId 为空值代表自己本地的首帧画面已到来，userId 不为空则代表远端用户的首帧画面已到来。
  217 + * @param streamType 视频流类型：主路（Main）一般用于承载摄像头画面，辅路（Sub）一般用于承载屏幕分享画面。
  218 + * @param width 画面的宽度。
  219 + * @param height 画面的高度。
201 */ 220 */
202 -- (void)onFirstVideoFrame:(NSString*)userId streamType:(TRTCVideoStreamType)streamType width:(int)width height:(int)height; 221 +- (void)onFirstVideoFrame:(NSString *)userId streamType:(TRTCVideoStreamType)streamType width:(int)width height:(int)height;
203 222
204 /** 223 /**
205 - * 3.7 开始播放远程用户的首帧音频（本地声音暂不通知） 224 + * 3.7 SDK 开始播放远端用户的首帧音频
206 * 225 *
207 - * @param userId 远程用户 ID。 226 + * SDK 会在播放远端用户的首帧音频时抛出该事件，本地音频的首帧事件暂不抛出。
  227 + *
  228 + * @param userId 远端用户的用户标识
208 */ 229 */
209 -- (void)onFirstAudioFrame:(NSString*)userId; 230 +- (void)onFirstAudioFrame:(NSString *)userId;
210 231
211 /** 232 /**
212 - * 3.8 首帧本地视频数据已经被送出 233 + * 3.8 自己本地的首个视频帧已被发布出去
213 * 234 *
214 - * SDK 会在 enterRoom() 并 startLocalPreview() 成功后开始摄像头采集，并将采集到的画面进行编码。  
215 - * 当 SDK 成功向云端送出第一帧视频数据后，会抛出这个回调事件。 235 + * 当您成功进入房间并通过 {@link startLocalPreview} 或 {@link startScreenCapture} 开启本地视频采集之后（开启采集和进入房间的先后顺序无影响），
  236 + * SDK 就会开始进行视频编码，并通过自身的网络模块向云端发布自己本地的视频数据。
  237 + * 当 SDK 成功地向云端送出自己的第一帧视频数据帧以后，就会抛出 onSendFirstLocalVideoFrame 事件回调。
216 * 238 *
217 - * @param streamType 视频流类型，主画面、小画面或辅流画面（屏幕分享） 239 + * @param streamType 视频流类型：主路（Main）一般用于承载摄像头画面，辅路（Sub）一般用于承载屏幕分享画面。
218 */ 240 */
219 -- (void)onSendFirstLocalVideoFrame: (TRTCVideoStreamType)streamType; 241 +- (void)onSendFirstLocalVideoFrame:(TRTCVideoStreamType)streamType;
220 242
221 /** 243 /**
222 - * 3.9 首帧本地音频数据已经被送出 244 + * 3.9 自己本地的首个音频帧已被发布出去
223 * 245 *
224 - * SDK 会在 enterRoom() 并 startLocalAudio() 成功后开始麦克风采集，并将采集到的声音进行编码。  
225 - * 当 SDK 成功向云端送出第一帧音频数据后，会抛出这个回调事件。 246 + * 当您成功进入房间并通过 {@link startLocalAudio} 开启本地音频采集之后（开启采集和进入房间的先后顺序无影响），
  247 + * SDK 就会开始进行音频编码，并通过自身的网络模块向云端发布自己本地的音频数据。
  248 + * 当 SDK 成功地向云端送出自己的第一帧音频数据帧以后，就会抛出 onSendFirstLocalAudioFrame 事件回调。
226 */ 249 */
227 - (void)onSendFirstLocalAudioFrame; 250 - (void)onSendFirstLocalAudioFrame;
228 251
229 /** 252 /**
230 - * 3.10 废弃接口：有主播加入当前房间  
231 - *  
232 - * 该回调接口可以被看作是 onRemoteUserEnterRoom 的废弃版本，不推荐使用。请使用 onUserVideoAvailable 或 onRemoteUserEnterRoom 进行替代。  
233 - *  
234 - * @note 该接口已被废弃，不推荐使用 253 + * 3.10 远端视频状态变化的事件回调
235 * 254 *
  255 + * 您可以通过此事件回调获取远端每一路画面的播放状态（包括 Playing、Loading 和 Stopped 三种状态），从而进行相应的 UI 展示。
236 * @param userId 用户标识 256 * @param userId 用户标识
  257 + * @param streamType 视频流类型：主路（Main）一般用于承载摄像头画面，辅路（Sub）一般用于承载屏幕分享画面。
  258 + * @param status 视频状态：包括 Playing、Loading 和 Stopped 三种状态。
  259 + * @param reason 视频状态改变的原因
  260 + * @param extrainfo 额外信息
237 */ 261 */
238 -- (void)onUserEnter:(NSString *)userId DEPRECATED_ATTRIBUTE;  
239 -  
240 -/**  
241 - * 3.11 废弃接口：有主播离开当前房间  
242 - *  
243 - * 该回调接口可以被看作是 onRemoteUserLeaveRoom 的废弃版本，不推荐使用。请使用 onUserVideoAvailable 或 onRemoteUserLeaveRoom 进行替代。  
244 - *  
245 - * @note 该接口已被废弃，不推荐使用  
246 - *  
247 - * @param userId 用户标识  
248 - * @param reason 离开原因。  
249 - */  
250 -- (void)onUserExit:(NSString *)userId reason:(NSInteger)reason DEPRECATED_ATTRIBUTE; 262 +- (void)onRemoteVideoStatusUpdated:(NSString *)userId streamType:(TRTCVideoStreamType)streamType streamStatus:(TRTCAVStatusType)status reason:(TRTCAVStatusChangeReason)reason extrainfo:(nullable NSDictionary *)info;
251 263
252 /// @} 264 /// @}
253 -  
254 ///////////////////////////////////////////////////////////////////////////////// 265 /////////////////////////////////////////////////////////////////////////////////
255 // 266 //
256 -// （四）统计和质量回调 267 +// 网络和技术指标统计回调
257 // 268 //
258 ///////////////////////////////////////////////////////////////////////////////// 269 /////////////////////////////////////////////////////////////////////////////////
259 -  
260 -/// @name 统计和质量回调 270 +/// @name 网络和技术指标统计回调
261 /// @{ 271 /// @{
262 272
263 /** 273 /**
264 - * 4.1 网络质量，该回调每2秒触发一次，统计当前网络的上行和下行质量 274 + * 4.1 网络质量的实时统计回调
  275 + *
  276 + * 该统计回调每间隔2秒抛出一次，用于通知 SDK 感知到的当前网络的上行和下行质量。
  277 + * SDK 会使用一组内嵌的自研算法对当前网络的延迟高低、带宽大小以及稳定情况进行评估，并计算出一个的评估结果：
  278 + * 如果评估结果为 1（Excellent） 代表当前的网络情况非常好，如果评估结果为 6（Down）代表当前网络无法支撑 TRTC 的正常通话。
265 * 279 *
266 - * @note userId == nil 代表自己当前的视频质量 280 + * @note 回调参数 localQuality 和 remoteQuality 中的 userId 如果为空置，代表本组数据统计的是自己本地的网络质量，否则是代表远端用户的网络质量。
267 * 281 *
268 * @param localQuality 上行网络质量 282 * @param localQuality 上行网络质量
269 * @param remoteQuality 下行网络质量 283 * @param remoteQuality 下行网络质量
270 */ 284 */
271 -- (void)onNetworkQuality: (TRTCQualityInfo*)localQuality remoteQuality:(NSArray<TRTCQualityInfo*>*)remoteQuality; 285 +- (void)onNetworkQuality:(TRTCQualityInfo *)localQuality remoteQuality:(NSArray<TRTCQualityInfo *> *)remoteQuality;
272 286
273 /** 287 /**
274 - * 4.2 技术指标统计回调 288 + * 4.2 音视频技术指标的实时统计回调
275 * 289 *
276 - * 如果您是熟悉音视频领域相关术语，可以通过这个回调获取 SDK 的所有技术指标。  
277 - * 如果您是首次开发音视频相关项目，可以只关注 onNetworkQuality 回调。 290 + * 该统计回调每间隔2秒抛出一次，用于通知 SDK 内部音频、视频以及网络相关的专业技术指标，这些信息在 {@link TRTCStatistics} 均有罗列：
  291 + * - 视频统计信息：视频的分辨率（resolution）、帧率（FPS）和比特率（bitrate）等信息。
  292 + * - 音频统计信息：音频的采样率（samplerate）、声道（channel）和比特率（bitrate）等信息。
  293 + * - 网络统计信息：SDK 和云端一次往返（SDK => Cloud => SDK）的网络耗时（rtt）、丢包率（loss）、上行流量（sentBytes）和下行流量（receivedBytes）等信息。
278 * 294 *
279 - * @param statistics 统计数据，包括本地和远程的  
280 - * @note 每2秒回调一次 295 + * @note 如果您只需要获知当前网络质量的好坏，并不需要花太多时间研究本统计回调，更推荐您使用 {@link onNetworkQuality} 来解决问题。
  296 + * @param statistics 统计数据，包括自己本地的统计信息和远端用户的统计信息，详情请参考 {@link TRTCStatistics}。
281 */ 297 */
282 -- (void)onStatistics: (TRTCStatistics *)statistics; 298 +- (void)onStatistics:(TRTCStatistics *)statistics;
283 299
284 /// @} 300 /// @}
285 -  
286 ///////////////////////////////////////////////////////////////////////////////// 301 /////////////////////////////////////////////////////////////////////////////////
287 // 302 //
288 -// （五）服务器事件回调 303 +// 与云端连接情况的事件回调
289 // 304 //
290 ///////////////////////////////////////////////////////////////////////////////// 305 /////////////////////////////////////////////////////////////////////////////////
291 -  
292 -/// @name 服务器事件回调 306 +/// @name 与云端连接情况的事件回调
293 /// @{ 307 /// @{
294 308
295 /** 309 /**
296 - * 5.1 SDK 跟服务器的连接断开 310 + * 5.1 SDK 与云端的连接已经断开
  311 + *
  312 + * SDK 会在跟云端的连接断开时抛出此事件回调，导致断开的原因大多是网络不可用或者网络切换所致，比如用户在通话中走进电梯时就可能会遇到此事件。
  313 + * 在抛出此事件之后，SDK 会努力跟云端重新建立连接，重连过程中会抛出 {@link onTryToReconnect}，连接恢复后会抛出 {@link onConnectionRecovery} 。
  314 + * 所以，SDK 会在如下三个连接相关的事件中按如下规律切换：
  315 + * <pre>
  316 + * [onConnectionLost] =====> [onTryToReconnect] =====> [onConnectionRecovery]
  317 + * /|\ |
  318 + * |------------------------------------------------------|
  319 + * </pre>
297 */ 320 */
298 - (void)onConnectionLost; 321 - (void)onConnectionLost;
299 322
300 /** 323 /**
301 - * 5.2 SDK 尝试重新连接到服务器 324 + * 5.2 SDK 正在尝试重新连接到云端
  325 + *
  326 + * SDK 会在跟云端的连接断开时抛出 {@link onConnectionLost}，之后会努力跟云端重新建立连接并抛出本事件，连接恢复后会抛出 {@link onConnectionRecovery}。
302 */ 327 */
303 - (void)onTryToReconnect; 328 - (void)onTryToReconnect;
304 329
305 /** 330 /**
306 - * 5.3 SDK 跟服务器的连接恢复 331 + * 5.3 SDK 与云端的连接已经恢复
  332 + *
  333 + * SDK 会在跟云端的连接断开时抛出 {@link onConnectionLost}，之后会努力跟云端重新建立连接并抛出{@link onTryToReconnect}，连接恢复后会抛出本事件回调。
307 */ 334 */
308 - (void)onConnectionRecovery; 335 - (void)onConnectionRecovery;
309 336
310 /// @} 337 /// @}
311 -  
312 ///////////////////////////////////////////////////////////////////////////////// 338 /////////////////////////////////////////////////////////////////////////////////
313 // 339 //
314 -// （六）硬件设备事件回调 340 +// 硬件设备相关事件回调
315 // 341 //
316 ///////////////////////////////////////////////////////////////////////////////// 342 /////////////////////////////////////////////////////////////////////////////////
317 -  
318 -/// @name 硬件设备事件回调 343 +/// @name 硬件设备相关事件回调
319 /// @{ 344 /// @{
320 345
321 /** 346 /**
322 * 6.1 摄像头准备就绪 347 * 6.1 摄像头准备就绪
  348 + *
  349 + * 当您调用 {@link startLocalPreivew} 之后，SDK 会尝试启动摄像头，如果摄像头能够启动成功就会抛出本事件。
  350 + * 如果启动失败，大概率是因为当前应用没有获得访问摄像头的权限，或者摄像头当前正在被其他程序独占使用中。
  351 + * 您可以通过捕获 {@link onError} 事件回调获知这些异常情况并通过 UI 界面提示用户。
323 */ 352 */
324 - (void)onCameraDidReady; 353 - (void)onCameraDidReady;
325 354
326 /** 355 /**
327 * 6.2 麦克风准备就绪 356 * 6.2 麦克风准备就绪
  357 + *
  358 + * 当您调用 {@link startLocalAudio} 之后，SDK 会尝试启动麦克风，如果麦克风能够启动成功就会抛出本事件。
  359 + * 如果启动失败，大概率是因为当前应用没有获得访问麦克风的权限，或者麦克风当前正在被其他程序独占使用中。
  360 + * 您可以通过捕获 {@link onError} 事件回调获知这些异常情况并通过 UI 界面提示用户。
328 */ 361 */
329 - (void)onMicDidReady; 362 - (void)onMicDidReady;
330 363
331 -#if TARGET_OS_IPHONE  
332 /** 364 /**
333 - * 6.3 音频路由发生变化（仅 iOS），音频路由即声音由哪里输出（扬声器或听筒） 365 + * 6.3 当前音频路由发生变化（仅适用于移动设备）
  366 + *
  367 + * 所谓“音频路由”，是指声音是从手机的扬声器还是从听筒中播放出来，音频路由变化也就是声音的播放位置发生了变化。
  368 + * - 当音频路由为听筒时，声音比较小，只有将耳朵凑近才能听清楚，隐私性较好，适合用于接听电话。
  369 + * - 当音频路由为扬声器时，声音比较大，不用将手机贴脸也能听清，因此可以实现“免提”的功能。
334 * 370 *
335 - * @param route 当前音频路由  
336 - * @param fromRoute 变更前的音频路由 371 + * @param route 音频路由，即声音由哪里输出（扬声器、听筒）。
  372 + * @param fromRoute 变更前的音频路由。
337 */ 373 */
  374 +#if TARGET_OS_IPHONE
338 - (void)onAudioRouteChanged:(TRTCAudioRoute)route fromRoute:(TRTCAudioRoute)fromRoute; 375 - (void)onAudioRouteChanged:(TRTCAudioRoute)route fromRoute:(TRTCAudioRoute)fromRoute;
339 #endif 376 #endif
340 377
341 /** 378 /**
342 - * 6.4 用于提示音量大小的回调，包括每个 userId 的音量和远端总音量 379 + * 6.4 音量大小的反馈回调
343 * 380 *
344 - * 您可以通过调用 TRTCCloud 中的 enableAudioVolumeEvaluation 接口来开关这个回调或者设置它的触发间隔。  
345 - * 需要注意的是，调用 enableAudioVolumeEvaluation 开启音量回调后，无论频道内是否有人说话，都会按设置的时间间隔调用这个回调;  
346 - * 如果没有人说话，则 userVolumes 为空，totalVolume 为 0。 381 + * SDK 可以评估每一路音频的音量大小，并每隔一段时间抛出该事件回调，您可以根据音量大小在 UI 上做出相应的提示，比如“波形图”或“音量槽”。
  382 + * 要完成这个功能， 您需要先调用 {@link enableAudioVolumeEvaluation} 开启这个能力并设定事件抛出的时间间隔。
  383 + * 需要补充说明的是，无论当前房间中是否有人说话，SDK 都会按照您设定的时间间隔定时抛出此事件回调，只不过当没有人说话时，userVolumes 为空，totalVolume 为 0。
347 * 384 *
348 - * @param userVolumes 所有正在说话的房间成员的音量，取值范围 0 - 100。  
349 - * @param totalVolume 所有远端成员的总音量, 取值范围 0 - 100。  
350 - * @note userId 为 nil 时表示自己的音量，userVolumes 内仅包含正在说话（音量不为 0 ）的用户音量信息。 385 + * @note userVolumes 为一个数组，对于数组中的每一个元素，当 userId 为空时表示本地麦克风采集的音量大小，当 userId 不为空时代表远端用户的音量大小。
  386 + *
  387 + * @param userVolumes 是一个数组，用于承载所有正在说话的用户的音量大小，取值范围 0 - 100。
  388 + * @param totalVolume 所有远端用户的总音量大小, 取值范围 0 - 100。
351 */ 389 */
352 - (void)onUserVoiceVolume:(NSArray<TRTCVolumeInfo *> *)userVolumes totalVolume:(NSInteger)totalVolume; 390 - (void)onUserVoiceVolume:(NSArray<TRTCVolumeInfo *> *)userVolumes totalVolume:(NSInteger)totalVolume;
353 391
354 -  
355 -#if !TARGET_OS_IPHONE && TARGET_OS_MAC  
356 /** 392 /**
357 - * 6.5 本地设备通断回调 393 + * 6.5 本地设备的通断状态发生变化（仅适用于桌面系统）
  394 + *
  395 + * 当本地设备（包括摄像头、麦克风以及扬声器）被插入或者拔出时，SDK 便会抛出此事件回调。
358 * 396 *
359 * @param deviceId 设备 ID 397 * @param deviceId 设备 ID
360 * @param deviceType 设备类型 398 * @param deviceType 设备类型
361 - * @param state 0：设备断开；1：设备连接 399 + * @param state 通断状态，0：设备断开；1：设备连接。
362 */ 400 */
  401 +#if !TARGET_OS_IPHONE && TARGET_OS_MAC
363 - (void)onDevice:(NSString *)deviceId type:(TRTCMediaDeviceType)deviceType stateChanged:(NSInteger)state; 402 - (void)onDevice:(NSString *)deviceId type:(TRTCMediaDeviceType)deviceType stateChanged:(NSInteger)state;
364 - 403 +#endif
365 404
366 /** 405 /**
367 - * 6.6 当前音频采集设备音量变化回调 406 + * 6.6 当前麦克风的系统采集音量发生变化
  407 + *
  408 + * 在 Mac 或 Windows 这样的桌面操作系统上，用户可以在设置中心找到声音相关的设置面板，并设置麦克风的采集音量大小。
  409 + * 用户将麦克风的采集音量设置得越大，麦克风采集到的声音的原始音量也就会越大，反之就会越小。
  410 + * 在有些型号的键盘以及笔记本电脑上，用户还可以通过按下“禁用麦克风”按钮（图标是一个话筒上上叠加了一道代表禁用的斜线）来将麦克风静音。
368 * 411 *
369 - * @note 使用 enableAudioVolumeEvaluation（interval>0）开启，（interval == 0）关闭 412 + * 当用户通过系统设置界面或者通过键盘上的快捷键设定操作系统的麦克风采集音量时，SDK 便会抛出此事件。
370 * 413 *
371 - * @param volume 音量 取值范围 0 - 100  
372 - * @param muted 当前采集音频设备是否被静音：YES 被静音了，NO 未被静音 414 + * @note 您需要调用 {@link enableAudioVolumeEvaluation} 接口并设定（interval>0）开启次事件回调，设定（interval == 0）关闭此事件回调。
  415 + *
  416 + * @param volume 系统采集音量，取值范围 0 - 100，用户可以在系统的声音设置面板上进行拖拽调整。
  417 + * @param muted 麦克风是否被用户禁用了：true 被禁用，false 被启用。
373 */ 418 */
  419 +#if !TARGET_OS_IPHONE && TARGET_OS_MAC
374 - (void)onAudioDeviceCaptureVolumeChanged:(NSInteger)volume muted:(BOOL)muted; 420 - (void)onAudioDeviceCaptureVolumeChanged:(NSInteger)volume muted:(BOOL)muted;
  421 +#endif
375 422
376 /** 423 /**
377 - * 6.7 当前音频播放设备音量变化回调 424 + * 6.7 当前系统的播放音量发生变化
  425 + *
  426 + * 在 Mac 或 Windows 这样的桌面操作系统上，用户可以在设置中心找到声音相关的设置面板，并设置系统的播放音量大小。
  427 + * 在有些型号的键盘以及笔记本电脑上，用户还可以通过按下“静音”按钮（图标是一个喇叭上叠加了一道代表禁用的斜线）来将系统静音。
  428 + *
  429 + * 当用户通过系统设置界面或者通过键盘上的快捷键设定操作系统的播放音量时，SDK 便会抛出此事件。
378 * 430 *
379 - * @note 使用 enableAudioVolumeEvaluation（interval>0）开启，（interval == 0）关闭 431 + * @note 您需要调用 {@link enableAudioVolumeEvaluation} 接口并设定（interval>0）开启次事件回调，设定（interval == 0）关闭此事件回调。
380 * 432 *
381 - * @param volume 音量 取值范围 0 - 100  
382 - * @param muted 当前音频播放设备是否被静音：YES 被静音了，NO 未被静音 433 + * @param volume 系统播放音量，取值范围 0 - 100，用户可以在系统的声音设置面板上进行拖拽调整。
  434 + * @param muted 系统是否被用户静音了：true 被静音，false 已恢复。
383 */ 435 */
  436 +#if !TARGET_OS_IPHONE && TARGET_OS_MAC
384 - (void)onAudioDevicePlayoutVolumeChanged:(NSInteger)volume muted:(BOOL)muted; 437 - (void)onAudioDevicePlayoutVolumeChanged:(NSInteger)volume muted:(BOOL)muted;
  438 +#endif
385 439
386 /** 440 /**
387 - * 6.8 系统声音采集结果回调 441 + * 6.8 系统声音采集是否被成功开启的事件回调（仅适用于 Mac 系统）
388 * 442 *
389 - * 系统声音采集接口 startSystemAudioLoopback 会触发这个回调 443 + * 在 Mac 系统上，您可以通过调用 {@link startSystemAudioLoopback} 为当前系统安装一个音频驱动，并让 SDK 通过该音频驱动捕获当前 Mac 系统播放出的声音。
  444 + * 当用于播片教学或音乐直播中，比如老师端可以使用此功能，让 SDK 能够采集老师所播放的电影中的声音，使同房间的学生端也能听到电影中的声音。
  445 + * SDK 会将统声音采集是否被成功开启的结果，通过本事件回调抛出，需要您关注参数中的错误码。
390 * 446 *
391 - * @param err ERR_NULL 表示成功，其余值表示失败 447 + * @param err ERR_NULL 表示成功，其余值表示失败。
392 */ 448 */
  449 +#if !TARGET_OS_IPHONE && TARGET_OS_MAC
393 - (void)onSystemAudioLoopbackError:(TXLiteAVError)err; 450 - (void)onSystemAudioLoopbackError:(TXLiteAVError)err;
394 -  
395 #endif 451 #endif
396 452
397 /// @} 453 /// @}
398 -  
399 -  
400 ///////////////////////////////////////////////////////////////////////////////// 454 /////////////////////////////////////////////////////////////////////////////////
401 // 455 //
402 -// （七）自定义消息的接收回调 456 +// 自定义消息的接收事件回调
403 // 457 //
404 ///////////////////////////////////////////////////////////////////////////////// 458 /////////////////////////////////////////////////////////////////////////////////
405 -  
406 -/// @name 自定义消息的接收回调 459 +/// @name 自定义消息的接收事件回调
407 /// @{ 460 /// @{
408 461
409 /** 462 /**
410 - * 7.1 收到自定义消息回调 463 + * 7.1 收到自定义消息的事件回调
411 * 464 *
412 - * 当房间中的某个用户使用 sendCustomCmdMsg 发送自定义消息时，房间中的其它用户可以通过 onRecvCustomCmdMsg 接口接收消息 465 + * 当房间中的某个用户使用 {@link sendCustomCmdMsg} 发送自定义 UDP 消息时，房间中的其它用户可以通过 onRecvCustomCmdMsg 事件回调接收到该条消息。
413 * 466 *
414 * @param userId 用户标识 467 * @param userId 用户标识
415 * @param cmdID 命令 ID 468 * @param cmdID 命令 ID
@@ -419,9 +472,9 @@ NS_ASSUME_NONNULL_BEGIN @@ -419,9 +472,9 @@ NS_ASSUME_NONNULL_BEGIN
419 - (void)onRecvCustomCmdMsgUserId:(NSString *)userId cmdID:(NSInteger)cmdID seq:(UInt32)seq message:(NSData *)message; 472 - (void)onRecvCustomCmdMsgUserId:(NSString *)userId cmdID:(NSInteger)cmdID seq:(UInt32)seq message:(NSData *)message;
420 473
421 /** 474 /**
422 - * 7.2 自定义消息丢失回调 475 + * 7.2 自定义消息丢失的事件回调
423 * 476 *
424 - * 实时音视频使用 UDP 通道，即使设置了可靠传输（reliable），也无法确保100@%不丢失，只是丢消息概率极低，能满足常规可靠性要求。 477 + * 当您使用 {@link sendCustomCmdMsg} 发送自定义 UDP 消息时，即使设置了可靠传输（reliable），也无法确保100@%不丢失，只是丢消息概率极低，能满足常规可靠性要求。
425 * 在发送端设置了可靠运输（reliable）后，SDK 都会通过此回调通知过去时间段内（通常为5s）传输途中丢失的自定义消息数量统计信息。 478 * 在发送端设置了可靠运输（reliable）后，SDK 都会通过此回调通知过去时间段内（通常为5s）传输途中丢失的自定义消息数量统计信息。
426 * 479 *
427 * @note 只有在发送端设置了可靠传输（reliable），接收方才能收到消息的丢失回调 480 * @note 只有在发送端设置了可靠传输（reliable），接收方才能收到消息的丢失回调
@@ -435,318 +488,401 @@ NS_ASSUME_NONNULL_BEGIN @@ -435,318 +488,401 @@ NS_ASSUME_NONNULL_BEGIN
435 /** 488 /**
436 * 7.3 收到 SEI 消息的回调 489 * 7.3 收到 SEI 消息的回调
437 * 490 *
438 - * 当房间中的某个用户使用 sendSEIMsg 发送数据时，房间中的其它用户可以通过 onRecvSEIMsg 接口接收数据。 491 + * 当房间中的某个用户使用 {@link sendSEIMsg} 借助视频数据帧发送 SEI 消息时，房间中的其它用户可以通过 onRecvSEIMsg 事件回调接收到该条消息。
439 * 492 *
440 * @param userId 用户标识 493 * @param userId 用户标识
441 * @param message 数据 494 * @param message 数据
442 */ 495 */
443 -- (void)onRecvSEIMsg:(NSString *)userId message:(NSData*)message; 496 +- (void)onRecvSEIMsg:(NSString *)userId message:(NSData *)message;
444 497
445 /// @} 498 /// @}
446 -  
447 ///////////////////////////////////////////////////////////////////////////////// 499 /////////////////////////////////////////////////////////////////////////////////
448 // 500 //
449 -// （八）CDN 旁路回调 501 +// CDN 相关事件回调
450 // 502 //
451 ///////////////////////////////////////////////////////////////////////////////// 503 /////////////////////////////////////////////////////////////////////////////////
452 -/// @name CDN 旁路转推回调 504 +/// @name CDN 相关事件回调
453 /// @{ 505 /// @{
454 - 506 +
455 /** 507 /**
456 - * 8.1 开始向腾讯云的直播 CDN 推流的回调，对应于 TRTCCloud 中的 startPublishing() 接口 508 + * 8.1 开始向腾讯云直播 CDN 上发布音视频流的事件回调
  509 + *
  510 + * 当您调用 {@link startPublishing} 开始向腾讯云直播 CDN 上发布音视频流时，SDK 会立刻将这一指令同步给云端服务器。
  511 + * 随后 SDK 会收到来自云端服务器的处理结果，并将指令的执行结果通过本事件回调通知给您。
457 * 512 *
458 * @param err 0表示成功，其余值表示失败 513 * @param err 0表示成功，其余值表示失败
459 * @param errMsg 具体错误原因 514 * @param errMsg 具体错误原因
460 */ 515 */
461 -- (void)onStartPublishing:(int)err errMsg:(NSString*)errMsg; 516 +- (void)onStartPublishing:(int)err errMsg:(NSString *)errMsg;
462 517
463 /** 518 /**
464 - * 8.2 停止向腾讯云的直播 CDN 推流的回调，对应于 TRTCCloud 中的 stopPublishing() 接口 519 + * 8.2 停止向腾讯云直播 CDN 上发布音视频流的事件回调
  520 + *
  521 + * 当您调用 {@link stopPublishing} 停止向腾讯云直播 CDN 上发布音视频流时，SDK 会立刻将这一指令同步给云端服务器。
  522 + * 随后 SDK 会收到来自云端服务器的处理结果，并将指令的执行结果通过本事件回调通知给您。
465 * 523 *
466 * @param err 0表示成功，其余值表示失败 524 * @param err 0表示成功，其余值表示失败
467 * @param errMsg 具体错误原因 525 * @param errMsg 具体错误原因
468 */ 526 */
469 -- (void)onStopPublishing:(int)err errMsg:(NSString*)errMsg; 527 +- (void)onStopPublishing:(int)err errMsg:(NSString *)errMsg;
470 528
471 /** 529 /**
472 - * 8.3 启动旁路推流到 CDN 完成的回调 530 + * 8.3 开始向非腾讯云 CDN 上发布音视频流的事件回调
473 * 531 *
474 - * 对应于 TRTCCloud 中的 startPublishCDNStream() 接口 532 + * 当您调用 {@link startPublishCDNStream} 开始向非腾讯云直播 CDN 上发布音视频流时，SDK 会立刻将这一指令同步给云端服务器。
  533 + * 随后 SDK 会收到来自云端服务器的处理结果，并将指令的执行结果通过本事件回调通知给您。
475 * 534 *
476 - * @note Start 回调如果成功，只能说明转推请求已经成功告知给腾讯云，如果目标 CDN 有异常，还是有可能会转推失败。 535 + * @note 当您收到成功的事件回调时，只是说明您的发布指令已经同步到腾讯云后台服务器，但如果目标 CDN 厂商的服务器不接收该条视频流，依然可能导致发布失败。
  536 + * @param err 0表示成功，其余值表示失败
  537 + * @param errMsg 具体错误原因
477 */ 538 */
478 - (void)onStartPublishCDNStream:(int)err errMsg:(NSString *)errMsg; 539 - (void)onStartPublishCDNStream:(int)err errMsg:(NSString *)errMsg;
479 540
480 /** 541 /**
481 - * 8.4 停止旁路推流到 CDN 完成的回调 542 + * 8.4 停止向非腾讯云 CDN 上发布音视频流的事件回调
482 * 543 *
483 - * 对应于 TRTCCloud 中的 stopPublishCDNStream() 接口 544 + * 当您调用 {@link stopPublishCDNStream} 开始向非腾讯云直播 CDN 上发布音视频流时，SDK 会立刻将这一指令同步给云端服务器。
  545 + * 随后 SDK 会收到来自云端服务器的处理结果，并将指令的执行结果通过本事件回调通知给您。
484 * 546 *
  547 + * @param err 0表示成功，其余值表示失败
  548 + * @param errMsg 具体错误原因
485 */ 549 */
486 - (void)onStopPublishCDNStream:(int)err errMsg:(NSString *)errMsg; 550 - (void)onStopPublishCDNStream:(int)err errMsg:(NSString *)errMsg;
487 551
488 /** 552 /**
489 - * 8.5 设置云端的混流转码参数的回调，对应于 TRTCCloud 中的 setMixTranscodingConfig() 接口 553 + * 8.5 设置云端混流的排版布局和转码参数的事件回调
490 * 554 *
491 - * @param err 0表示成功，其余值表示失败  
492 - * @param errMsg 具体错误原因 555 + * 当您调用 {@link setMixTranscodingConfig} 调整云端混流的排版布局和转码参数时，SDK 会立刻将这一调整指令同步给云端服务器。
  556 + * 随后 SDK 会收到来自云端服务器的处理结果，并将指令的执行结果通过本事件回调通知给您。
  557 + *
  558 + * @param err 错误码：0表示成功，其余值表示失败。
  559 + * @param errMsg 具体的错误原因。
493 */ 560 */
494 -- (void)onSetMixTranscodingConfig:(int)err errMsg:(NSString*)errMsg; 561 +- (void)onSetMixTranscodingConfig:(int)err errMsg:(NSString *)errMsg;
495 562
496 /// @} 563 /// @}
497 -  
498 ///////////////////////////////////////////////////////////////////////////////// 564 /////////////////////////////////////////////////////////////////////////////////
499 // 565 //
500 -// （九）音效回调 566 +// 屏幕分享相关事件回调
501 // 567 //
502 ///////////////////////////////////////////////////////////////////////////////// 568 /////////////////////////////////////////////////////////////////////////////////
503 -/// @name 音效回调 569 +/// @name 屏幕分享相关事件回调
504 /// @{ 570 /// @{
505 -/**  
506 - * 播放音效结束回调  
507 - *  
508 - * @param effectId 音效 ID  
509 - * @param code 0 表示播放正常结束；其他表示异常结束  
510 - * @note 该接口已不再维护，推荐使用 TXAudioEffectManager.startPlayMusic 及相关回调  
511 - */  
512 -- (void)onAudioEffectFinished:(int) effectId code:(int) code DEPRECATED_ATTRIBUTE;  
513 -/// @}  
514 -/////////////////////////////////////////////////////////////////////////////////  
515 -//  
516 -// （十）屏幕分享回调  
517 -//  
518 -/////////////////////////////////////////////////////////////////////////////////  
519 571
520 -/// @name 屏幕分享回调  
521 -/// @{  
522 /** 572 /**
523 - * 10.1 当屏幕分享开始时，SDK 会通过此回调通知 573 + * 9.1 屏幕分享开启的事件回调
  574 + *
  575 + * 当您通过 {@link startScreenCapture} 等相关接口启动屏幕分享时，SDK 便会抛出此事件回调。
524 */ 576 */
525 - (void)onScreenCaptureStarted; 577 - (void)onScreenCaptureStarted;
526 578
527 /** 579 /**
528 - * 10.2 当屏幕分享暂停时，SDK 会通过此回调通知 580 + * 9.2 屏幕分享暂停的事件回调
529 * 581 *
530 - * @param reason 原因，0：用户主动暂停；1：屏幕窗口不可见暂停 582 + * 当您通过 {@link pauseScreenCapture} 暂停屏幕分享时，SDK 便会抛出此事件回调。
  583 + * @param reason 原因。
  584 + * - 0：用户主动暂停。
  585 + * - 1：注意此字段的含义在 MAC 和 Windows 平台有稍微差异。屏幕窗口不可见暂停（Mac）。表示设置屏幕分享参数导致的暂停（Windows）。
  586 + * - 2：表示屏幕分享窗口被最小化导致的暂停（仅 Windows）。
  587 + * - 3：表示屏幕分享窗口被隐藏导致的暂停（仅 Windows）。
531 */ 588 */
532 - (void)onScreenCapturePaused:(int)reason; 589 - (void)onScreenCapturePaused:(int)reason;
533 590
534 /** 591 /**
535 - * 10.3 当屏幕分享恢复时，SDK 会通过此回调通知 592 + * 9.3 屏幕分享恢复的事件回调
536 * 593 *
537 - * @param reason 恢复原因，0：用户主动恢复；1：屏幕窗口恢复可见从而恢复分享 594 + * 当您通过 {@link resumeScreenCapture} 恢复屏幕分享时，SDK 便会抛出此事件回调。
  595 + * @param reason 恢复原因。
  596 + * - 0：用户主动恢复。
  597 + * - 1：注意此字段的含义在 MAC 和 Windows 平台有稍微差异。屏幕窗口恢复可见从而恢复分享（Mac）。屏幕分享参数设置完毕后自动恢复（Windows）
  598 + * - 2：表示屏幕分享窗口从最小化被恢复（仅 Windows）。
  599 + * - 3：表示屏幕分享窗口从隐藏被恢复（仅 Windows）。
538 */ 600 */
539 - (void)onScreenCaptureResumed:(int)reason; 601 - (void)onScreenCaptureResumed:(int)reason;
540 602
541 /** 603 /**
542 - * 10.4 当屏幕分享停止时，SDK 会通过此回调通知 604 + * 9.4 屏幕分享停止的事件回调
543 * 605 *
544 - * @param reason 停止原因，0：用户主动停止；1：屏幕窗口关闭导致停止 606 + * 当您通过 {@link stopScreenCapture} 停止屏幕分享时，SDK 便会抛出此事件回调。
  607 + * @param reason 停止原因，0：用户主动停止；1：屏幕窗口关闭导致停止；2：表示屏幕分享的显示屏状态变更（如接口被拔出、投影模式变更等）。
545 */ 608 */
546 - (void)onScreenCaptureStoped:(int)reason; 609 - (void)onScreenCaptureStoped:(int)reason;
547 -/// @}  
548 610
549 -#if TARGET_OS_IPHONE 611 +/// @}
550 ///////////////////////////////////////////////////////////////////////////////// 612 /////////////////////////////////////////////////////////////////////////////////
551 // 613 //
552 -// （十一）媒体录制回调 614 +// 本地录制和本地截图的事件回调
553 // 615 //
554 ///////////////////////////////////////////////////////////////////////////////// 616 /////////////////////////////////////////////////////////////////////////////////
555 -/// @name 媒体录制回调 617 +/// @name 本地录制和本地截图的事件回调
556 /// @{ 618 /// @{
  619 +
557 /** 620 /**
558 - * 11.1 媒体录制回调 621 + * 10.1 本地录制任务已经开始的事件回调
559 * 622 *
  623 + * 当您调用 {@link startLocalRecording} 启动本地媒体录制任务时，SDK 会抛出该事件回调，用于通知您录制任务是否已经顺利启动。
560 * @param errCode 错误码 0：初始化录制成功；-1：初始化录制失败；-2: 文件后缀名有误。 624 * @param errCode 错误码 0：初始化录制成功；-1：初始化录制失败；-2: 文件后缀名有误。
561 * @param storagePath 录制文件存储路径 625 * @param storagePath 录制文件存储路径
562 */ 626 */
  627 +#if TARGET_OS_IPHONE
563 - (void)onLocalRecordBegin:(NSInteger)errCode storagePath:(NSString *)storagePath; 628 - (void)onLocalRecordBegin:(NSInteger)errCode storagePath:(NSString *)storagePath;
  629 +#endif
564 630
565 /** 631 /**
566 - * 11.2 录制信息更新回调 632 + * 10.2 本地录制任务正在进行中的进展事件回调
567 * 633 *
  634 + * 当您调用 {@link startLocalRecording} 成功启动本地媒体录制任务后，SDK 变会定时地抛出本事件回调。
  635 + * 您可通过捕获该事件回调来获知录制任务的健康状况。
  636 + * 您可以在 {@link startLocalRecording} 时设定本事件回调的抛出间隔。
  637 + *
  638 + * @param duration 已经录制的累计时长，单位毫秒
568 * @param storagePath 录制文件存储路径 639 * @param storagePath 录制文件存储路径
569 - * @param duration 录制时长，单位毫秒  
570 */ 640 */
  641 +#if TARGET_OS_IPHONE
571 - (void)onLocalRecording:(NSInteger)duration storagePath:(NSString *)storagePath; 642 - (void)onLocalRecording:(NSInteger)duration storagePath:(NSString *)storagePath;
  643 +#endif
572 644
573 /** 645 /**
574 - * 11.2 录制任务已结束 646 + * 10.3 本地录制任务已经结束的事件回调
575 * 647 *
  648 + * 当您调用 {@link stopLocalRecording} 停止本地媒体录制任务时，SDK 会抛出该事件回调，用于通知您录制任务的最终结果。
576 * @param errCode 错误码 0：录制成功；-1：录制失败；-2：切换分辨率或横竖屏导致录制结束。 649 * @param errCode 错误码 0：录制成功；-1：录制失败；-2：切换分辨率或横竖屏导致录制结束。
577 * @param storagePath 录制文件存储路径 650 * @param storagePath 录制文件存储路径
578 */ 651 */
  652 +#if TARGET_OS_IPHONE
579 - (void)onLocalRecordComplete:(NSInteger)errCode storagePath:(NSString *)storagePath; 653 - (void)onLocalRecordComplete:(NSInteger)errCode storagePath:(NSString *)storagePath;
580 -///@}  
581 #endif 654 #endif
582 -@end  
583 -/// @}  
584 655
  656 +/// @}
585 ///////////////////////////////////////////////////////////////////////////////// 657 /////////////////////////////////////////////////////////////////////////////////
586 // 658 //
587 -// （十二）自定义视频渲染回调 659 +// 废弃的事件回调（建议使用对应的新回调）
588 // 660 //
589 ///////////////////////////////////////////////////////////////////////////////// 661 /////////////////////////////////////////////////////////////////////////////////
590 -#pragma mark - TRTCVideoRenderDelegate  
591 -/// @addtogroup TRTCCloudDelegate_ios 662 +/// @name 废弃的事件回调（建议使用对应的新回调）
592 /// @{ 663 /// @{
  664 +
593 /** 665 /**
594 - * 视频数据帧的自定义处理回调 666 + * 有主播加入当前房间（已废弃）
  667 + *
  668 + * @deprecated 新版本开始不推荐使用，建议使用 {@link onRemoteUserEnterRoom} 替代之。
595 */ 669 */
596 -@protocol TRTCVideoRenderDelegate <NSObject> 670 +- (void)onUserEnter:(NSString *)userId __attribute__((deprecated("use onRemoteUserLeaveRoom instead")));
  671 +
597 /** 672 /**
598 - * 自定义视频渲染回调 673 + * 有主播离开当前房间（已废弃）
599 * 674 *
600 - * @param frame 待渲染的视频帧信息  
601 - * @param userId 视频源的 userId，如果是本地视频回调（setLocalVideoRenderDelegate），该参数可以忽略  
602 - * @param streamType 视频源类型，例如，使用摄像头画面或屏幕分享画面等 675 + * @deprecated 新版本开始不推荐使用，建议使用 {@link onRemoteUserLeaveRoom} 替代之。
603 */ 676 */
604 -@optional  
605 -- (void) onRenderVideoFrame:(TRTCVideoFrame * _Nonnull)frame userId:(NSString* __nullable)userId streamType:(TRTCVideoStreamType)streamType; 677 +- (void)onUserExit:(NSString *)userId reason:(NSInteger)reason __attribute__((deprecated("use onRemoteUserLeaveRoom instead")));
  678 +
  679 +/**
  680 + * 音效播放已结束（已废弃）
  681 + *
  682 + * @deprecated 新版本开始不推荐使用，建议使用 {@link ITXAudioEffectManager} 接口替代之。
  683 + * 新的接口中不再区分背景音乐和音效，而是统一用 {@link startPlayMusic} 取代之。
  684 + */
  685 +- (void)onAudioEffectFinished:(int)effectId code:(int)code __attribute__((deprecated("use ITXAudioEffectManager.startPlayMusic instead")));
606 686
607 -@end 687 +/// @}
  688 +@end // End of class TRTCCloudDelegate
608 689
609 ///////////////////////////////////////////////////////////////////////////////// 690 /////////////////////////////////////////////////////////////////////////////////
610 // 691 //
611 -// （十三）第三方美颜回调 692 +// 视频数据自定义回调
612 // 693 //
613 ///////////////////////////////////////////////////////////////////////////////// 694 /////////////////////////////////////////////////////////////////////////////////
  695 +/// @name 视频数据自定义回调
  696 +/// @{
  697 +
  698 +@protocol TRTCVideoRenderDelegate <NSObject>
  699 +
  700 +/**
  701 + * 自定义视频渲染回调
  702 + *
  703 + * 当您设置了本地或者远端的视频自定义渲染回调之后，SDK 就会将原本要交给渲染控件进行渲染的视频帧通过此回调接口抛送给您，以便于您进行自定义渲染。
  704 + * @param frame 待渲染的视频帧信息
  705 + * @param userId 视频源的 userId，如果是本地视频回调（setLocalVideoRenderDelegate），该参数可以忽略
  706 + * @param streamType 频流类型：主路（Main）一般用于承载摄像头画面，辅路（Sub）一般用于承载屏幕分享画面。
  707 + */
  708 +@optional
  709 +- (void)onRenderVideoFrame:(TRTCVideoFrame *_Nonnull)frame userId:(NSString *__nullable)userId streamType:(TRTCVideoStreamType)streamType;
  710 +
  711 +@end // End of class TRTCVideoRenderDelegate
614 712
615 @protocol TRTCVideoFrameDelegate <NSObject> 713 @protocol TRTCVideoFrameDelegate <NSObject>
616 714
  715 +/**
  716 + * 用于对接第三方美颜组件的视频处理回调
  717 + *
  718 + * 如果您选购了第三方美颜组件，就需要在 TRTCCloud 中设置第三方美颜回调，之后 TRTC 就会将原本要进行预处理的视频帧通过此回调接口抛送给您。
  719 + * 之后您就可以将 TRTC 抛出的视频帧交给第三方美颜组件进行图像处理，由于抛出的数据是可读且可写的，因此第三方美颜的处理结果也可以同步给 TRTC 进行后续的编码和发送。
  720 + *
  721 + * @param srcFrame 用于承载 TRTC 采集到的摄像头画面
  722 + * @param dstFrame 用于接收第三方美颜处理过的视频画面
  723 + * @note 目前仅支持 OpenGL 纹理方案
  724 + *
  725 + * 情况一：美颜组件自身会产生新的纹理
  726 + * 如果您使用的美颜组件会在处理图像的过程中产生一帧全新的纹理（用于承载处理后的图像），那请您在回调函数中将 dstFrame.textureId 设置为新纹理的 ID：
  727 + * <pre>
  728 + * uint32_t onProcessVideoFrame(TRTCVideoFrame * _Nonnull)srcFrame dstFrame:(TRTCVideoFrame * _Nonnull)dstFrame{
  729 + * self.frameID += 1;
  730 + * dstFrame.pixelBuffer = [[FURenderer shareRenderer] renderPixelBuffer:srcFrame.pixelBuffer
  731 + * withFrameId:self.frameID
  732 + * items:self.renderItems
  733 + * itemCount:self.renderItems.count];
  734 + * return 0;
  735 + * }
  736 + * </pre>
  737 + *
  738 + *
  739 + * 情况二：美颜组件需要您提供目标纹理
  740 + * 如果您使用的第三方美颜模块并不生成新的纹理，而是需要您设置给该模块一个输入纹理和一个输出纹理，则可以考虑如下方案：
  741 + * ```ObjectiveC
  742 + * uint32_t onProcessVideoFrame(TRTCVideoFrame * _Nonnull)srcFrame dstFrame:(TRTCVideoFrame * _Nonnull)dstFrame{
  743 + * thirdparty_process(srcFrame.textureId, srcFrame.width, srcFrame.height, dstFrame.textureId);
  744 + * return 0;
  745 + * }
  746 + * ```
  747 + * ```java
  748 + * int onProcessVideoFrame(TRTCCloudDef.TRTCVideoFrame srcFrame, TRTCCloudDef.TRTCVideoFrame dstFrame) {
  749 + * thirdparty_process(srcFrame.texture.textureId, srcFrame.width, srcFrame.height, dstFrame.texture.textureId);
  750 + * return 0;
  751 + * }
  752 + * ```
  753 + */
617 @optional 754 @optional
  755 +- (uint32_t)onProcessVideoFrame:(TRTCVideoFrame *_Nonnull)srcFrame dstFrame:(TRTCVideoFrame *_Nonnull)dstFrame;
618 756
619 /** 757 /**
620 -* 第三方美颜的视频数据回调，需要使用 TRTCCloud 中的 setLocalVideoProcessDelegete 接口进行设置  
621 -*  
622 -* @param srcFrame 用于承载 TRTC 采集到的摄像头画面  
623 -* @param dstFrame 用于接收第三方美颜处理过的视频画面  
624 -* @note 目前仅支持 OpenGL 纹理方案  
625 -*  
626 -* 【使用相芯】  
627 -* 由于相芯的美颜模块会在处理图像的过程中产生一个全新的纹理，因此需要您在回调函数中将 dstFrame.textureId 设置为相芯处理后的新纹理。  
628 -* <pre>  
629 -* uint32_t onProcessVideoFrame(TRTCVideoFrame * _Nonnull)srcFrame dstFrame:(TRTCVideoFrame * _Nonnull)dstFrame  
630 -* {  
631 -* uint32_t dstTextureId = renderItemWithTexture(srcFrame.textureId, srcFrame.width, srcFrame.height);  
632 -* dstFrame.textureId = dstTextureId;  
633 -* return 0;  
634 -* }  
635 -* </pre>  
636 -*  
637 -* 【其他方案】  
638 -* 如果您使用的第三方美颜模块并不生成新的纹理，而是需要您设置给该模块一个输入纹理和一个输出纹理，则可以考虑如下方案：  
639 -* <pre>  
640 -* uint32_t onProcessVideoFrame(TRTCVideoFrame * _Nonnull)srcFrame dstFrame:(TRTCVideoFrame * _Nonnull)dstFrame  
641 -* {  
642 -* thirdparty_process(srcFrame.textureId, srcFrame.width, srcFrame.height, dstFrame.textureId);  
643 -* return 0;  
644 -* }  
645 -* </pre>  
646 -*  
647 -**/  
648 -- (uint32_t)onProcessVideoFrame:(TRTCVideoFrame * _Nonnull)srcFrame dstFrame:(TRTCVideoFrame * _Nonnull)dstFrame;  
649 -  
650 -/**  
651 - * SDK 内部的 OpenGL 环境的销毁通知 758 + * SDK 内部 OpenGL 环境被销的通知
652 */ 759 */
  760 +@optional
653 - (void)onGLContextDestory; 761 - (void)onGLContextDestory;
654 762
655 -@end 763 +@end // End of class TRTCVideoFrameDelegate
656 764
  765 +/// @}
657 ///////////////////////////////////////////////////////////////////////////////// 766 /////////////////////////////////////////////////////////////////////////////////
658 // 767 //
659 -// （十四）音频数据回调 768 +// 音频数据自定义回调
660 // 769 //
661 ///////////////////////////////////////////////////////////////////////////////// 770 /////////////////////////////////////////////////////////////////////////////////
662 -/**  
663 - * 声音数据帧的自定义处理回调  
664 - */ 771 +/// @name 音频数据自定义回调
  772 +/// @{
  773 +
665 @protocol TRTCAudioFrameDelegate <NSObject> 774 @protocol TRTCAudioFrameDelegate <NSObject>
666 @optional 775 @optional
667 776
668 /** 777 /**
669 * 本地麦克风采集到的原始音频数据回调 778 * 本地麦克风采集到的原始音频数据回调
670 * 779 *
671 - * @param frame 音频数据  
672 - * @note - 请不要在此回调函数中做任何耗时操作，建议直接拷贝到另一线程进行处理，否则会导致各种声音问题。  
673 - * @note - 此接口回调出的音频数据 **不包含** 背景音、音效、混响等前处理效果，延迟极低。  
674 - * - 此接口回调出的音频数据支持修改。 780 + * 当您设置完音频数据自定义回调之后，SDK 内部会把刚从麦克风采集到的原始音频数据，以 PCM 格式的形式通过本接口回调给您。
  781 + * - 此接口回调出的音频时间帧长固定为0.02s，格式为 PCM 格式。
  782 + * - 由时间帧长转化为字节帧长的公式为【采样率 × 时间帧长 × 声道数 × 采样点位宽】。
  783 + * - 以 TRTC 默认的音频录制格式48000采样率、单声道、16采样点位宽为例，字节帧长为【48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节】。
  784 + *
  785 + * @param frame PCM 格式的音频数据帧
  786 + * @note
  787 + * 1. 请不要在此回调函数中做任何耗时操作，由于 SDK 每隔 20ms 就要处理一帧音频数据，如果您的处理时间超过 20ms，就会导致声音异常。
  788 + * 2. 此接口回调出的音频数据是可读写的，也就是说您可以在回调函数中同步修改音频数据，但请保证处理耗时。
  789 + * 3. 此接口回调出的音频数据**不包含**背景音、音效、混响等前处理效果，延迟极低。
675 */ 790 */
676 -- (void) onCapturedRawAudioFrame:(TRTCAudioFrame *)frame; 791 +- (void)onCapturedRawAudioFrame:(TRTCAudioFrame *)frame;
677 792
678 /** 793 /**
679 * 本地采集并经过音频模块前处理后的音频数据回调 794 * 本地采集并经过音频模块前处理后的音频数据回调
680 * 795 *
681 - * @param frame 音频数据  
682 - * @note - 请不要在此回调函数中做任何耗时操作，建议直接拷贝到另一线程进行处理，否则会导致各种声音问题。  
683 - * @note - 此接口回调出的音频数据包含背景音、音效、混响等前处理效果，延迟较高。  
684 - * @note - 此接口回调出的音频数据支持修改。  
685 - * @note - 此接口回调出的音频时间帧长固定为 0.02s。  
686 - 由时间帧长转化为字节帧长的公式为【采样率 × 时间帧长 × 声道数 × 采样点位宽】。  
687 - 以SDK默认的音频录制格式 48000 采样率、单声道、16采样点位宽为例，字节帧长为【48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节】。 796 + * 当您设置完音频数据自定义回调之后，SDK 内部会把刚采集到并经过前处理(ANS、AEC、AGC）之后的数据，以 PCM 格式的形式通过本接口回调给您。
  797 + * - 此接口回调出的音频时间帧长固定为0.02s，格式为 PCM 格式。
  798 + * - 由时间帧长转化为字节帧长的公式为【采样率 × 时间帧长 × 声道数 × 采样点位宽】。
  799 + * - 以 TRTC 默认的音频录制格式48000采样率、单声道、16采样点位宽为例，字节帧长为【48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节】。
  800 + *
  801 + * 特殊说明：
  802 + * 您可以通过设置接口中的 `TRTCAudioFrame.extraData` 字段，达到传输信令的目的。
  803 + * 由于音频帧头部的数据块不能太大，建议您写入 `extraData` 时，尽量将信令控制在几个字节的大小，如果超过 100 个字节，写入的数据不会被发送。
  804 + * 房间内其他用户可以通过 {@link TRTCAudioFrameDelegate} 中的 `onRemoteUserAudioFrame` 中的 `TRTCAudioFrame.extraData` 字段回调接收数据。
  805 + *
  806 + * @param frame PCM 格式的音频数据帧
  807 + * @note
  808 + * 1. 请不要在此回调函数中做任何耗时操作，由于 SDK 每隔 20ms 就要处理一帧音频数据，如果您的处理时间超过 20ms，就会导致声音异常。
  809 + * 2. 此接口回调出的音频数据是可读写的，也就是说您可以在回调函数中同步修改音频数据，但请保证处理耗时。
  810 + * 3. 此接口回调出的数据已经经过了回声抑制（AEC）处理，但声音的延迟相比于 {@link onCapturedRawAudioFrame} 要高一些。
688 */ 811 */
689 -- (void) onLocalProcessedAudioFrame:(TRTCAudioFrame *)frame; 812 +- (void)onLocalProcessedAudioFrame:(TRTCAudioFrame *)frame;
690 813
691 /** 814 /**
692 - * 混音前的每一路远程用户的音频数据，即混音前的各路原始数据。例如，对某一路音频进行文字转换时，您必须使用该路音频的原始数据 815 + * 混音前的每一路远程用户的音频数据
  816 + *
  817 + * 当您设置完音频数据自定义回调之后，SDK 内部会把远端的每一路原始数据，在最终混音之前，以 PCM 格式的形式通过本接口回调给您。
  818 + * - 此接口回调出的音频时间帧长固定为0.02s，格式为 PCM 格式。
  819 + * - 由时间帧长转化为字节帧长的公式为【采样率 × 时间帧长 × 声道数 × 采样点位宽】。
  820 + * - 以 TRTC 默认的音频录制格式48000采样率、单声道、16采样点位宽为例，字节帧长为【48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节】。
693 * 821 *
694 - * @param frame 音频数据  
695 - * @param userId 用户标识  
696 - * @note - 此接口回调出的音频数据是只读的，不支持修改。 822 + * @param frame PCM 格式的音频数据帧
  823 + * @param userId 用户标识
  824 + * @note 此接口回调出的音频数据是只读的，不支持修改
697 */ 825 */
698 -- (void) onRemoteUserAudioFrame:(TRTCAudioFrame *)frame userId:(NSString *)userId; 826 +- (void)onRemoteUserAudioFrame:(TRTCAudioFrame *)frame userId:(NSString *)userId;
699 827
700 /** 828 /**
701 - * 各路音频数据混合后的音频数据 829 + * 将各路待播放音频混合之后并在最终提交系统播放之前的数据回调
  830 + *
  831 + * 当您设置完音频数据自定义回调之后，SDK 内部会把各路待播放的音频混合之后的音频数据，在提交系统播放之前，以 PCM 格式的形式通过本接口回调给您。
  832 + * - 此接口回调出的音频时间帧长固定为0.02s，格式为 PCM 格式。
  833 + * - 由时间帧长转化为字节帧长的公式为【采样率 × 时间帧长 × 声道数 × 采样点位宽】。
  834 + * - 以 TRTC 默认的音频录制格式48000采样率、单声道、16采样点位宽为例，字节帧长为【48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节】。
702 * 835 *
703 - * @param frame 音频数据  
704 - * @note - 请不要在此回调函数中做任何耗时操作，建议直接拷贝到另一线程进行处理，否则会导致各种声音问题。  
705 - * @note - 此接口回调出的音频数据支持修改。  
706 - * @note - 此接口回调出的音频时间帧长固定为 0.02s。  
707 - 由时间帧长转化为字节帧长的公式为【采样率 × 时间帧长 × 声道数 × 采样点位宽】。  
708 - 以SDK默认的音频播放格式 48000 采样率、双声道、16采样点位宽为例，字节帧长为【48000 × 0.02s × 2 × 16bit = 30720bit = 3840字节】。  
709 - * @note - 此接口回调出的音频数据是各路音频播放数据的混合,不包含耳返的音频数据。 836 + * @param frame PCM 格式的音频数据帧
  837 + * @note
  838 + * 1. 请不要在此回调函数中做任何耗时操作，由于 SDK 每隔 20ms 就要处理一帧音频数据，如果您的处理时间超过 20ms，就会导致声音异常。
  839 + * 2. 此接口回调出的音频数据是可读写的，也就是说您可以在回调函数中同步修改音频数据，但请保证处理耗时。
  840 + * 3. 此接口回调出的是对各路待播放音频数据的混合，但其中并不包含耳返的音频数据。
710 */ 841 */
711 -- (void) onMixedPlayAudioFrame:(TRTCAudioFrame *)frame; 842 +- (void)onMixedPlayAudioFrame:(TRTCAudioFrame *)frame;
712 843
713 /** 844 /**
714 -* SDK所有音频数据混合后的数据回调（包括采集音频数据和所有播放音频数据）  
715 -*  
716 -* @param frame 音频数据  
717 -* @note - 此接口回调出的音频数据不支持修改。  
718 -* @note - 此接口回调出的音频时间帧长固定为 0.02s。音频格式固定为48000采样率、单声道、16采样点位宽。  
719 - 由时间帧长转化为字节帧长的公式为【采样率 × 时间帧长 × 声道数 × 采样点位宽】。  
720 - 因此回调的字节帧长固定为【48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节】。  
721 -* @note - 此接口回调出的是SDK所有音频数据的混合数据，包括：经过特效（包括混响、变声等）处理后的本地麦克风采集数据，  
722 - 所有远程用户的数据，所有背景音和音效数据。不包括耳返数据。  
723 -*/  
724 -- (void) onMixedAllAudioFrame:(TRTCAudioFrame *)frame; 845 + * SDK 所有音频混合后的音频数据（包括采集到的和待播放的）
  846 + *
  847 + * 当您设置完音频数据自定义回调之后，SDK 内部会把所有采集到的和待播放的音频数据混合起来，以 PCM 格式的形式通过本接口回调给您，便于您进行自定义录制。
  848 + * - 此接口回调出的音频时间帧长固定为0.02s，格式为 PCM 格式。
  849 + * - 由时间帧长转化为字节帧长的公式为【采样率 × 时间帧长 × 声道数 × 采样点位宽】。
  850 + * - 以 TRTC 默认的音频录制格式48000采样率、单声道、16采样点位宽为例，字节帧长为【48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节】。
  851 + *
  852 + * @param frame PCM 格式的音频数据帧
  853 + * @note
  854 + * 1. 此接口回调出的是SDK所有音频数据的混合数据，包括：经过 3A 前处理、特效叠加以及背景音乐混音后的本地音频，所有远端音频，但不包括耳返音频。
  855 + * 2. 此接口回调出的音频数据不支持修改。
  856 + */
  857 +- (void)onMixedAllAudioFrame:(TRTCAudioFrame *)frame;
725 858
726 -@end 859 +@end // End of class TRTCAudioFrameDelegate
727 860
  861 +/// @}
728 ///////////////////////////////////////////////////////////////////////////////// 862 /////////////////////////////////////////////////////////////////////////////////
729 // 863 //
730 -// （十五）Log 信息回调 864 +// 更多事件回调接口
731 // 865 //
732 ///////////////////////////////////////////////////////////////////////////////// 866 /////////////////////////////////////////////////////////////////////////////////
733 -/**  
734 - * 日志相关回调  
735 - *  
736 - * 建议在比较早初始化的类中设置回调委托对象，例如 AppDelegate  
737 - */ 867 +/// @name 更多事件回调接口
  868 +/// @{
  869 +
738 @protocol TRTCLogDelegate <NSObject> 870 @protocol TRTCLogDelegate <NSObject>
  871 +
  872 +@optional
  873 +
739 /** 874 /**
740 - * 有日志打印时的回调 875 + * 本地 LOG 的打印回调
741 * 876 *
  877 + * 如果您希望捕获 SDK 的本地日志打印行为，可以通过设置日志回调，让 SDK 将要打印的日志都通过本回调接口抛送给您。
742 * @param log 日志内容 878 * @param log 日志内容
743 - * @param level 日志等级，参见 TRTCLogLevel  
744 - * @param module 值暂无具体意义，目前为固定值 TXLiteAVSDK 879 + * @param level 日志等级 参见 TRTC_LOG_LEVEL
  880 + * @param module 保留字段，暂无具体意义，目前为固定值 TXLiteAVSDK
745 */ 881 */
746 -@optional  
747 --(void) onLog:(nullable NSString*)log LogLevel:(TRTCLogLevel)level WhichModule:(nullable NSString*)module; 882 +- (void)onLog:(nullable NSString *)log LogLevel:(TRTCLogLevel)level WhichModule:(nullable NSString *)module;
748 883
749 -@end 884 +@end // End of class TRTCLogDelegate
750 /// @} 885 /// @}
751 -  
752 NS_ASSUME_NONNULL_END 886 NS_ASSUME_NONNULL_END
  887 +
  888 +/// @}
1 -  
2 -/*  
3 - * Module: TRTCStatistics @ TXLiteAVSDK  
4 - *  
5 - * Function: 腾讯云视频通话功能的质量统计相关接口  
6 - * 1 +/**
  2 + * Module: TRTC 音视频统计指标（只读）
  3 + * Function: TRTC SDK 会以两秒钟一次的频率向您汇报当前实时的音视频指标（帧率、码率、卡顿情况等）
7 */ 4 */
8 -///@addtogroup TRTCCloudDef_ios  
9 -///@{ 5 +/// @defgroup TRTCStatisic_ios TRTCStatisic
  6 +/// TRTC 音视频统计指标
  7 +/// @{
  8 +
  9 +/////////////////////////////////////////////////////////////////////////////////
  10 +//
  11 +// 本地的音视频统计指标
  12 +//
  13 +/////////////////////////////////////////////////////////////////////////////////
  14 +/// @name 本地的音视频统计指标
  15 +/// @{
10 16
11 -/// 自己本地的音视频统计信息  
12 @interface TRTCLocalStatistics : NSObject 17 @interface TRTCLocalStatistics : NSObject
13 18
14 -/// 视频宽度  
15 -@property (nonatomic, assign) uint32_t width; 19 +///【字段含义】本地视频的宽度，单位 px
  20 +@property(nonatomic, assign) uint32_t width;
16 21
17 -/// 视频高度  
18 -@property (nonatomic, assign) uint32_t height; 22 +///【字段含义】本地视频的高度，单位 px
  23 +@property(nonatomic, assign) uint32_t height;
19 24
20 -/// 帧率（fps）  
21 -@property (nonatomic, assign) uint32_t frameRate; 25 +///【字段含义】本地视频的帧率，即每秒钟会有多少视频帧，单位：FPS
  26 +@property(nonatomic, assign) uint32_t frameRate;
22 27
23 -/// 视频发送码率（Kbps）  
24 -@property (nonatomic, assign) uint32_t videoBitrate; 28 +///【字段含义】远端视频的码率，即每秒钟新产生视频数据的多少，单位 Kbps
  29 +@property(nonatomic, assign) uint32_t videoBitrate;
25 30
26 -/// 音频采样率（Hz）  
27 -@property (nonatomic, assign) uint32_t audioSampleRate; 31 +///【字段含义】远端音频的采样率，单位 Hz
  32 +@property(nonatomic, assign) uint32_t audioSampleRate;
28 33
29 -/// 音频发送码率（Kbps）  
30 -@property (nonatomic, assign) uint32_t audioBitrate; 34 +///【字段含义】本地音频的码率，即每秒钟新产生音频数据的多少，单位 Kbps
  35 +@property(nonatomic, assign) uint32_t audioBitrate;
31 36
32 -/// 流类型（大画面 | 小画面 | 辅路画面）  
33 -@property (nonatomic, assign) TRTCVideoStreamType streamType; 37 +///【字段含义】视频流类型（高清大画面|低清小画面|辅流画面）
  38 +@property(nonatomic, assign) TRTCVideoStreamType streamType;
34 39
35 -/// 音频设备采集状态，用于检测外接音频设备的健康度 40 +///【字段含义】音频设备采集状态（用于检测音频外设的健康度）
36 /// 0：采集设备状态正常；1：检测到长时间静音；2：检测到破音；3：检测到声音异常间断。 41 /// 0：采集设备状态正常；1：检测到长时间静音；2：检测到破音；3：检测到声音异常间断。
37 -@property (nonatomic, assign) uint32_t audioCaptureState; 42 +@property(nonatomic, assign) uint32_t audioCaptureState;
38 @end 43 @end
39 44
  45 +/// @}
  46 +/////////////////////////////////////////////////////////////////////////////////
  47 +//
  48 +// 远端的音视频统计指标
  49 +//
  50 +/////////////////////////////////////////////////////////////////////////////////
  51 +/// @name 远端的音视频统计指标
  52 +/// @{
40 53
41 -/// 远端成员的音视频统计信息  
42 @interface TRTCRemoteStatistics : NSObject 54 @interface TRTCRemoteStatistics : NSObject
43 55
44 -/// 用户 ID，指定是哪个用户的视频流  
45 -@property (nonatomic, retain) NSString* userId;  
46 -  
47 -/// 该线路的总丢包率（％）  
48 -/// 这个值越小越好，例如，丢包率为0表示网络很好。  
49 -/// 丢包率是该线路的 userId 从上行到服务器再到下行的总丢包率。  
50 -/// 如果 downLoss 为0，但是 finalLoss 不为0，说明该 userId 上行时出现了无法恢复的丢包。  
51 -@property (nonatomic, assign) uint32_t finalLoss; 56 +///【字段含义】用户 ID
  57 +@property(nonatomic, retain) NSString* userId;
52 58
53 -/// 视频宽度  
54 -@property (nonatomic, assign) uint32_t width; 59 +///【字段含义】该路音视频流的总丢包率（％）
  60 +/// finalLoss 代表该路音视频流历经“主播 => 云端 => 观众”这样一条完整的传输链路后，最终在观众端统计到的丢包率。
  61 +/// finalLoss 越小越好，丢包率为0即表示该路音视频流的所有数据均已经完整地到达了观众端。
  62 +///如果出现了 downLoss == 0 但 finalLoss != 0 的情况，说明该路音视频流在“云端=>观众”这一段链路上没有出现丢包，但是在“主播=>云端”这一段链路上出现了不可恢复的丢包。
  63 +@property(nonatomic, assign) uint32_t finalLoss;
55 64
56 -/// 视频高度  
57 -@property (nonatomic, assign) uint32_t height; 65 +///【字段含义】远端视频的宽度，单位 px
  66 +@property(nonatomic, assign) uint32_t width;
58 67
59 -/// 接收帧率（fps）  
60 -@property (nonatomic, assign) uint32_t frameRate; 68 +///【字段含义】远端视频的高度，单位 px
  69 +@property(nonatomic, assign) uint32_t height;
61 70
62 -/// 视频码率（Kbps）  
63 -@property (nonatomic, assign) uint32_t videoBitrate; 71 +///【字段含义】远端视频的帧率，单位：FPS
  72 +@property(nonatomic, assign) uint32_t frameRate;
64 73
65 -/// 音频采样率（Hz）  
66 -@property (nonatomic, assign) uint32_t audioSampleRate; 74 +///【字段含义】远端视频的码率，单位 Kbps
  75 +@property(nonatomic, assign) uint32_t videoBitrate;
67 76
68 -/// 音频码率（Kbps）  
69 -@property (nonatomic, assign) uint32_t audioBitrate; 77 +///【字段含义】本地音频的采样率，单位 Hz
  78 +@property(nonatomic, assign) uint32_t audioSampleRate;
70 79
71 -/// 播放时延（ms）  
72 -@property (nonatomic, assign) uint32_t jitterBufferDelay; 80 +///【字段含义】本地音频的码率，单位 Kbps
  81 +@property(nonatomic, assign) uint32_t audioBitrate;
73 82
74 -/// 端对端延迟（ms）  
75 -/// 该字段为全链路延迟统计，链路包含：采集->编码->网络传输->接收->缓冲->解码->播放  
76 -/// 延迟以 audio 为基准进行计算。需要本地和远端均为8.5版本以上时才生效  
77 -/// 若远端用户为低版本，对应延迟会回调为0，此时代表无效值  
78 -@property (nonatomic, assign) uint32_t point2PointDelay; 83 +///【字段含义】播放延迟，单位 ms
  84 +///为了避免网络抖动和网络包乱序导致的声音和画面卡顿，TRTC 会在播放端管理一个播放缓冲区，用于对接收到的网络数据包进行整理，
  85 +///该缓冲区的大小会根据当前的网络质量进行自适应调整，该缓冲区的大小折算成以毫秒为单位的时间长度，也就是 jitterBufferDelay。
  86 +@property(nonatomic, assign) uint32_t jitterBufferDelay;
79 87
80 -/// 音频播放卡顿累计时长（ms）  
81 -@property (nonatomic, assign) uint32_t audioTotalBlockTime; 88 +///【字段含义】端到端延迟，单位 ms
  89 +/// point2PointDelay 代表 “主播=>云端=>观众” 的延迟，更准确地说，它代表了“采集=>编码=>网络传输=>接收=>缓冲=>解码=>播放” 全链路的延迟。
  90 +/// point2PointDelay 需要本地和远端的 SDK 均为 8.5 及以上的版本才生效，若远端用户为 8.5 以前的版本，此数值会一直为0，代表无意义。
  91 +@property(nonatomic, assign) uint32_t point2PointDelay;
82 92
83 -/// 音频播放卡顿率，音频卡顿的累计时长占音频总播放时长的百分比 (%)  
84 -@property (nonatomic, assign) uint32_t audioBlockRate; 93 +///【字段含义】音频播放的累计卡顿时长，单位 ms
  94 +@property(nonatomic, assign) uint32_t audioTotalBlockTime;
85 95
86 -/// 视频播放卡顿累计时长（ms）  
87 -@property (nonatomic, assign) uint32_t videoTotalBlockTime; 96 +///【字段含义】音频播放卡顿率，单位 (%)
  97 +///音频播放卡顿率（audioBlockRate） = 音频播放的累计卡顿时长（audioTotalBlockTime） / 音频播放的总时长
  98 +@property(nonatomic, assign) uint32_t audioBlockRate;
88 99
89 -/// 音频播放卡顿率，视频卡顿累计时长占视频总播放时长的百分比（%）  
90 -@property (nonatomic, assign) uint32_t videoBlockRate; 100 +///【字段含义】视频播放的累计卡顿时长，单位 ms
  101 +@property(nonatomic, assign) uint32_t videoTotalBlockTime;
91 102
92 -/// 流类型（大画面 | 小画面 | 辅路画面）  
93 -@property (nonatomic, assign) TRTCVideoStreamType streamType; 103 +///【字段含义】视频播放卡顿率，单位 (%)
  104 +///视频播放卡顿率（videoBlockRate） = 视频播放的累计卡顿时长（videoTotalBlockTime） / 视频播放的总时长
  105 +@property(nonatomic, assign) uint32_t videoBlockRate;
94 106
  107 +///【字段含义】视频流类型（高清大画面|低清小画面|辅流画面）
  108 +@property(nonatomic, assign) TRTCVideoStreamType streamType;
95 @end 109 @end
96 110
  111 +/// @}
  112 +/////////////////////////////////////////////////////////////////////////////////
  113 +//
  114 +// 网络和性能的汇总统计指标
  115 +//
  116 +/////////////////////////////////////////////////////////////////////////////////
  117 +/// @name 网络和性能的汇总统计指标
  118 +/// @{
97 119
98 -/// 统计数据  
99 @interface TRTCStatistics : NSObject 120 @interface TRTCStatistics : NSObject
100 121
101 -/// C -> S 上行丢包率（％），  
102 -/// 该值越小越好，例如，丢包率为 0 表示网络很好，  
103 -/// 丢包率为 30@% 则意味着 SDK 向服务器发送的数据包中会有 30@% 丢失在上行传输中。  
104 -@property (nonatomic, assign) uint32_t upLoss; 122 +///【字段含义】当前应用的 CPU 使用率，单位 (%)
  123 +@property(nonatomic, assign) uint32_t appCpu;
  124 +
  125 +///【字段含义】当前系统的 CPU 使用率，单位 (%)
  126 +@property(nonatomic, assign) uint32_t systemCpu;
105 127
106 -/// S -> C 下行丢包率（％），  
107 -/// 该值越小越好，例如，丢包率为0表示网络很好，  
108 -/// 丢包率为 30@% 则意味着 SDK 向服务器发送的数据包中会有 30@% 丢失在下行传输中。  
109 -@property (nonatomic, assign) uint32_t downLoss; 128 +///【字段含义】从 SDK 到云端的上行丢包率，单位 (%)
  129 +///该数值越小越好，如果 upLoss 为 0%，则意味着上行链路的网络质量很好，上传到云端的数据包基本不发生丢失。
  130 +///如果 upLoss 为 30%，则意味着 SDK 向云端发送的音视频数据包中，会有 30% 丢失在传输链路中。
  131 +@property(nonatomic, assign) uint32_t upLoss;
110 132
111 -/// 当前 App 的 CPU 使用率（％）  
112 -@property (nonatomic, assign) uint32_t appCpu; 133 +///【字段含义】从云端到 SDK 的下行丢包率，单位 (%)
  134 +///该数值越小越好，如果 downLoss 为 0%，则意味着下行链路的网络质量很好，从云端接收的数据包基本不发生丢失。
  135 +///如果 downLoss 为 30%，则意味着云端向 SDK 传输的音视频数据包中，会有 30% 丢失在传输链路中。
  136 +@property(nonatomic, assign) uint32_t downLoss;
113 137
114 -/// 当前系统的 CPU 使用率（％）  
115 -@property (nonatomic, assign) uint32_t systemCpu; 138 +///【字段含义】从 SDK 到云端的往返延时，单位 ms
  139 +///该数值代表从 SDK 发送一个网络包到云端，再从云端回送一个网络包到 SDK 的总计耗时，也就是一个网络包经历 “SDK=>云端=>SDK” 的总耗时。
  140 +///该数值越小越好：如果 rtt < 50ms，意味着较低的音视频通话延迟；如果 rtt > 200ms，则意味着较高的音视频通话延迟。
  141 +///需要特别解释的是，rtt 代表 “SDK=>云端=>SDK” 的总耗时，所不需要区分 upRtt 和 downRtt。
  142 +@property(nonatomic, assign) uint32_t rtt;
116 143
117 -/// 延迟（毫秒），  
118 -/// 指 SDK 到腾讯云服务器的一次网络往返时间，该值越小越好。  
119 -/// 一般低于 50ms 的 rtt 相对理想，而高于 100ms 的 rtt 会引入较大的通话延时。  
120 -/// 由于数据上下行共享一条网络连接，所以 local 和 remote 的 rtt 相同。  
121 -@property (nonatomic, assign) uint32_t rtt; 144 +///【字段含义】从 SDK 到本地路由器的往返时延，单位 ms
  145 +///该数值代表从 SDK 发送一个网络包到本地路由器网关，再从网关回送一个网络包到 SDK 的总计耗时，也就是一个网络包经历 “SDK=>网关=>SDK” 的总耗时。
  146 +///该数值越小越好：如果 gatewayRtt < 50ms，意味着较低的音视频通话延迟；如果 gatewayRtt > 200ms，则意味着较高的音视频通话延迟。
  147 +///当网络类型为蜂窝网时，该值无效。
  148 +@property(nonatomic, assign) uint32_t gatewayRtt;
122 149
123 -/// 总接收字节数（包含信令及音视频）  
124 -@property (nonatomic, assign) uint64_t receivedBytes; 150 +///【字段含义】总发送字节数（包含信令数据和音视频数据），单位：字节数（Bytes）
  151 +@property(nonatomic, assign) uint64_t sentBytes;
125 152
126 -/// 总发送字节数（包含信令及音视频）  
127 -@property (nonatomic, assign) uint64_t sentBytes; 153 +///【字段含义】总接收字节数（包含信令数据和音视频数据），单位：字节数（Bytes）
  154 +@property(nonatomic, assign) uint64_t receivedBytes;
128 155
129 -/// 自己本地的音视频统计信息，可能有主画面、小画面以及辅路画面等多路的情况，因此是一个数组  
130 -@property (nonatomic, strong) NSArray<TRTCLocalStatistics*>* localStatistics; 156 +///【字段含义】本地的音视频统计信息
  157 +///由于本地可能有三路音视频流（即高清大画面，低清小画面，以及辅流画面），因此本地的音视频统计信息是一个数组。
  158 +@property(nonatomic, strong) NSArray<TRTCLocalStatistics*>* localStatistics;
  159 +
  160 +///【字段含义】远端的音视频统计信息
  161 +///因为同时可能有多个远端用户，而且每个远端用户同时可能有多路音视频流（即高清大画面，低清小画面，以及辅流画面），因此远端的音视频统计信息是一个数组。
  162 +@property(nonatomic, strong) NSArray<TRTCRemoteStatistics*>* remoteStatistics;
131 163
132 -/// 远端成员的音视频统计信息，可能有主画面、小画面以及辅路画面等多路的情况，因此是一个数组  
133 -@property (nonatomic, strong) NSArray<TRTCRemoteStatistics*>* remoteStatistics;  
134 @end 164 @end
135 -///@} 165 +/// @}
  166 +
  167 +/// @}
1 -/*  
2 -* Module: TXAudioEffectManager 音乐和人声设置类  
3 -*  
4 -* Function: 用于音乐、短音效和人声效果功能的使用  
5 -*  
6 -*/  
7 - 1 +/**
  2 + * Module: TRTC 背景音乐、短音效和人声特效的管理类
  3 + * Function: 用于对背景音乐、短音效和人声特效进行设置的管理类
  4 + */
  5 +/// @defgroup TXAudioEffectManager_ios TXAudioEffectManager
  6 +/// TRTC 背景音乐、短音效和人声特效的管理类
  7 +/// @{
8 #import <Foundation/Foundation.h> 8 #import <Foundation/Foundation.h>
9 9
10 -NS_ASSUME_NONNULL_BEGIN 10 +/////////////////////////////////////////////////////////////////////////////////
  11 +//
  12 +// 音效相关的枚举值定义
  13 +//
  14 +/////////////////////////////////////////////////////////////////////////////////
  15 +/// @name 音效相关的枚举值定义
  16 +/// @{
  17 +
  18 +/**
  19 + * 1.1 混响特效
  20 + *
  21 + * 混响特效可以作用于人声之上，通过声学算法对声音进行叠加处理，模拟出各种不同环境下的临场感受，目前支持如下几种混响效果：
  22 + * 0：关闭；1：KTV；2：小房间；3：大会堂；4：低沉；5：洪亮；6：金属声；7：磁性。
  23 + */
  24 +typedef NS_ENUM(NSInteger, TXVoiceReverbType) {
  25 + TXVoiceReverbType_0 = 0, ///< disable
  26 + TXVoiceReverbType_1 = 1, ///< KTV
  27 + TXVoiceReverbType_2 = 2, ///< small room
  28 + TXVoiceReverbType_3 = 3, ///< great hall
  29 + TXVoiceReverbType_4 = 4, ///< deep voice
  30 + TXVoiceReverbType_5 = 5, ///< loud voice
  31 + TXVoiceReverbType_6 = 6, ///< metallic sound
  32 + TXVoiceReverbType_7 = 7, ///< magnetic sound
  33 +};
  34 +
  35 +/**
  36 + * 1.2 变声特效
  37 + *
  38 + * 变声特效可以作用于人声之上，通过声学算法对人声进行二次处理，以获得与原始声音所不同的音色，目前支持如下几种变声特效：
  39 + * 0：关闭；1：熊孩子；2：萝莉；3：大叔；4：重金属；5：感冒；6：外语腔；7：困兽；8：肥宅；9：强电流；10：重机械；11：空灵。
  40 + */
  41 +typedef NS_ENUM(NSInteger, TXVoiceChangeType) {
  42 + TXVoiceChangeType_0 = 0, ///< disable
  43 + TXVoiceChangeType_1 = 1, ///< naughty kid
  44 + TXVoiceChangeType_2 = 2, ///< Lolita
  45 + TXVoiceChangeType_3 = 3, ///< uncle
  46 + TXVoiceChangeType_4 = 4, ///< heavy metal
  47 + TXVoiceChangeType_5 = 5, ///< catch cold
  48 + TXVoiceChangeType_6 = 6, ///< foreign accent
  49 + TXVoiceChangeType_7 = 7, ///< caged animal trapped beast
  50 + TXVoiceChangeType_8 = 8, ///< indoorsman
  51 + TXVoiceChangeType_9 = 9, ///< strong current
  52 + TXVoiceChangeType_10 = 10, ///< heavy machinery
  53 + TXVoiceChangeType_11 = 11, ///< intangible
  54 +};
  55 +
  56 +/// @}
  57 +/////////////////////////////////////////////////////////////////////////////////
  58 +//
  59 +// 背景音乐的播放事件回调
  60 +//
  61 +/////////////////////////////////////////////////////////////////////////////////
  62 +/// @name 背景音乐的事件回调接口
  63 +/// @{
  64 +
  65 +// Playback progress block of background music
11 66
  67 +///背景音乐开始播放
12 typedef void (^TXAudioMusicStartBlock)(NSInteger errCode); 68 typedef void (^TXAudioMusicStartBlock)(NSInteger errCode);
  69 +
  70 +///背景音乐的播放进度
13 typedef void (^TXAudioMusicProgressBlock)(NSInteger progressMs, NSInteger durationMs); 71 typedef void (^TXAudioMusicProgressBlock)(NSInteger progressMs, NSInteger durationMs);
  72 +
  73 +///背景音乐已经播放完毕
14 typedef void (^TXAudioMusicCompleteBlock)(NSInteger errCode); 74 typedef void (^TXAudioMusicCompleteBlock)(NSInteger errCode);
15 75
16 -@class TXAudioMusicParam;  
17 -typedef NS_ENUM(NSInteger, TXVoiceChangeType);  
18 -typedef NS_ENUM(NSInteger, TXVoiceReverbType); 76 +/// @}
  77 +/////////////////////////////////////////////////////////////////////////////////
  78 +//
  79 +// 背景音乐的播放控制信息
  80 +//
  81 +/////////////////////////////////////////////////////////////////////////////////
  82 +/// @name 背景音乐的播放控制信息
  83 +/// @{
19 84
  85 +/**
  86 + * 背景音乐的播放控制信息
  87 + *
  88 + * 该信息用于在接口 {@link startPlayMusic} 中指定背景音乐的相关信息，包括播放 ID、文件路径和循环次数等：
  89 + * 1. 如果要多次播放同一首背景音乐，请不要每次播放都分配一个新的 ID，我们推荐使用相同的 ID。
  90 + * 2. 若您希望同时播放多首不同的音乐，请为不同的音乐分配不同的 ID 进行播放。
  91 + * 3. 如果使用同一个 ID 播放不同音乐，SDK 会先停止播放旧的音乐，再播放新的音乐。
  92 + */
  93 +@interface TXAudioMusicParam : NSObject
  94 +
  95 +///【字段含义】音乐 ID <br/>
  96 +///【特殊说明】SDK 允许播放多路音乐，因此需要使用 ID 进行标记，用于控制音乐的开始、停止、音量等。
  97 +@property(nonatomic) int32_t ID;
  98 +
  99 +///【字段含义】音效文件的完整路径或 URL 地址。支持的音频格式包括 MP3、AAC、M4A、WAV
  100 +@property(nonatomic, copy) NSString *path;
  101 +
  102 +///【字段含义】音乐循环播放的次数 <br/>
  103 +///【推荐取值】取值范围为0 - 任意正整数，默认值：0。0表示播放音乐一次；1表示播放音乐两次；以此类推
  104 +@property(nonatomic) NSInteger loopCount;
  105 +
  106 +///【字段含义】是否将音乐传到远端 <br/>
  107 +///【推荐取值】YES：音乐在本地播放的同时，远端用户也能听到该音乐；NO：主播只能在本地听到该音乐，远端观众听不到。默认值：NO。
  108 +@property(nonatomic) BOOL publish;
  109 +
  110 +///【字段含义】播放的是否为短音乐文件 <br/>
  111 +///【推荐取值】YES：需要重复播放的短音乐文件；NO：正常的音乐文件。默认值：NO
  112 +@property(nonatomic) BOOL isShortFile;
  113 +
  114 +///【字段含义】音乐开始播放时间点，单位：毫秒。
  115 +@property(nonatomic) NSInteger startTimeMS;
  116 +
  117 +///【字段含义】音乐结束播放时间点，单位毫秒，0表示播放至文件结尾。
  118 +@property(nonatomic) NSInteger endTimeMS;
  119 +@end
  120 +/// @}
  121 +
  122 +// Definition of audio effect management module
20 @interface TXAudioEffectManager : NSObject 123 @interface TXAudioEffectManager : NSObject
21 124
22 -/// TXAudioEffectManager对象不可直接创建  
23 -/// 要通过 `TRTCCloud` 或 `TXLivePush` 的 `getAudioEffectManager` 接口获取 125 +/**
  126 + * TXAudioEffectManager对象不可直接被创建
  127 + * 要通过 `TRTCCloud` 或 `TXLivePush` 中的 `getAudioEffectManager` 接口获取
  128 + */
24 - (instancetype)init NS_UNAVAILABLE; 129 - (instancetype)init NS_UNAVAILABLE;
25 130
26 ///////////////////////////////////////////////////////////////////////////////// 131 /////////////////////////////////////////////////////////////////////////////////
27 // 132 //
28 -// （一）人声相关特效函数 133 +// 人声相关的特效接口
29 // 134 //
30 ///////////////////////////////////////////////////////////////////////////////// 135 /////////////////////////////////////////////////////////////////////////////////
31 -  
32 -/// @name 人声相关特效函数 136 +/// @name 人声相关的特效接口
33 /// @{ 137 /// @{
34 - 138 +
35 /** 139 /**
36 * 1.1 开启耳返 140 * 1.1 开启耳返
37 * 141 *
38 - * 开启后会在耳机里听到自己的声音。 142 + * 主播开启耳返后，可以在耳机里听到麦克风采集到的自己发出的声音，该特效适用于主播唱歌的应用场景中。
  143 + *
  144 + * 需要您注意的是，由于蓝牙耳机的硬件延迟非常高，所以在主播佩戴蓝牙耳机时无法开启此特效，请尽量在用户界面上提示主播佩戴有线耳机。
  145 + * 同时也需要注意，并非所有的手机开启此特效后都能达到优秀的耳返效果，我们已经对部分耳返效果不佳的手机屏蔽了该特效。
39 * 146 *
40 - * @note 仅在戴耳机时有效，暂时仅支持部分采集延迟较低的机型  
41 - * @param enable true：开启；false：关闭 147 + * @note 仅在主播佩戴耳机时才能开启此特效，同时请您提示主播佩戴有线耳机。
  148 + * @param enable true：开启；false：关闭。
42 */ 149 */
43 - (void)enableVoiceEarMonitor:(BOOL)enable; 150 - (void)enableVoiceEarMonitor:(BOOL)enable;
44 151
45 /** 152 /**
46 * 1.2 设置耳返音量 153 * 1.2 设置耳返音量
47 * 154 *
48 - * @param volume 音量大小，100为原始音量，范围是：[0 ~ 150]，默认值为100 155 + * 通过该接口您可以设置耳返特效中声音的音量大小。
49 * 156 *
50 - * @note 如果要将 volume 设置为大于100的数值，需要进行特殊配置，请联系技术支持。 157 + * @param volume 音量大小，取值范围为0 - 100，默认值：100。
  158 + * @note 如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。
51 */ 159 */
52 - (void)setVoiceEarMonitorVolume:(NSInteger)volume; 160 - (void)setVoiceEarMonitorVolume:(NSInteger)volume;
53 161
54 /** 162 /**
55 - * 1.3 设置人声的混响效果（KTV、小房间、大会堂、低沉、洪亮...） 163 + * 1.3 设置人声的混响效果
56 * 164 *
57 - * @note 设置的效果在退房后会失效，如果下次进房还需要对应特效，需要调用此接口再次设置。 165 + * 通过该接口您可以设置人声的混响效果，具体特效请参考枚举定义{@link TXVoiceReverbType}。
  166 + *
  167 + * @note 设置的效果在退出房间后会自动失效，如果下次进房还需要对应特效，需要调用此接口再次进行设置。
58 */ 168 */
59 - (void)setVoiceReverbType:(TXVoiceReverbType)reverbType; 169 - (void)setVoiceReverbType:(TXVoiceReverbType)reverbType;
60 170
61 /** 171 /**
62 - * 1.4 设置人声的变声特效（萝莉、大叔、重金属、外国人...） 172 + * 1.4 设置人声的变声特效
  173 + *
  174 + * 通过该接口您可以设置人声的变声特效，具体特效请参考枚举定义{@link TXVoiceChangeType}。
63 * 175 *
64 - * @note 设置的效果在退房后会失效，如果下次进房还需要对应特效，需要调用此接口再次设置。 176 + * @note 设置的效果在退出房间后会自动失效，如果下次进房还需要对应特效，需要调用此接口再次进行设置。
65 */ 177 */
66 - (void)setVoiceChangerType:(TXVoiceChangeType)changerType; 178 - (void)setVoiceChangerType:(TXVoiceChangeType)changerType;
67 179
68 /** 180 /**
69 - * 1.5 设置麦克风采集人声的音量 181 + * 1.5 设置语音音量
70 * 182 *
71 - * @param volume 音量大小，100为原始音量，范围是：[0 ~ 150]，默认值为100 183 + * 该接口可以设置语音音量的大小，一般配合音乐音量的设置接口 {@link setAllMusicVolume} 协同使用，用于调谐语音和音乐在混音前各自的音量占比。
72 * 184 *
73 - * @note 如果要将 volume 设置为大于100的数值，需要进行特殊配置，请联系技术支持。 185 + * @param volume 音量大小，取值范围为0 - 100，默认值：100。
  186 + * @note 如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。
74 */ 187 */
75 - (void)setVoiceVolume:(NSInteger)volume; 188 - (void)setVoiceVolume:(NSInteger)volume;
76 189
77 /// @} 190 /// @}
78 -  
79 ///////////////////////////////////////////////////////////////////////////////// 191 /////////////////////////////////////////////////////////////////////////////////
80 // 192 //
81 -// （二）背景音乐特效函数 193 +// 背景音乐的相关接口
82 // 194 //
83 ///////////////////////////////////////////////////////////////////////////////// 195 /////////////////////////////////////////////////////////////////////////////////
84 -  
85 -/// @name 人声相关特效函数 196 +/// @name 背景音乐的相关接口
86 /// @{ 197 /// @{
  198 +
87 /** 199 /**
88 * 2.1 开始播放背景音乐 200 * 2.1 开始播放背景音乐
89 * 201 *
90 * 每个音乐都需要您指定具体的 ID，您可以通过该 ID 对音乐的开始、停止、音量等进行设置。 202 * 每个音乐都需要您指定具体的 ID，您可以通过该 ID 对音乐的开始、停止、音量等进行设置。
91 * 203 *
92 - * @note 若您想同时播放多个音乐，请分配不同的 ID 进行播放。  
93 - * 如果使用同一个 ID 播放不同音乐，SDK 会先停止播放旧的音乐，再播放新的音乐。 204 + * @note
  205 + * 1. 如果要多次播放同一首背景音乐，请不要每次播放都分配一个新的 ID，我们推荐使用相同的 ID。
  206 + * 2. 若您希望同时播放多首不同的音乐，请为不同的音乐分配不同的 ID 进行播放。
  207 + * 3. 如果使用同一个 ID 播放不同音乐，SDK 会先停止播放旧的音乐，再播放新的音乐。
  208 + *
94 * @param musicParam 音乐参数 209 * @param musicParam 音乐参数
95 * @param startBlock 播放开始回调 210 * @param startBlock 播放开始回调
96 * @param progressBlock 播放进度回调 211 * @param progressBlock 播放进度回调
97 * @param completeBlock 播放结束回调 212 * @param completeBlock 播放结束回调
98 */ 213 */
99 -- (void)startPlayMusic:(TXAudioMusicParam *)musicParam  
100 - onStart:(TXAudioMusicStartBlock _Nullable)startBlock  
101 - onProgress:(TXAudioMusicProgressBlock _Nullable)progressBlock  
102 - onComplete:(TXAudioMusicCompleteBlock _Nullable)completeBlock; 214 +- (void)startPlayMusic:(TXAudioMusicParam *)musicParam onStart:(TXAudioMusicStartBlock _Nullable)startBlock onProgress:(TXAudioMusicProgressBlock _Nullable)progressBlock onComplete:(TXAudioMusicCompleteBlock _Nullable)completeBlock;
103 215
104 /** 216 /**
105 * 2.2 停止播放背景音乐 217 * 2.2 停止播放背景音乐
106 * 218 *
107 - * @param id 音乐 ID 219 + * @param id 音乐 ID
108 */ 220 */
109 - (void)stopPlayMusic:(int32_t)id; 221 - (void)stopPlayMusic:(int32_t)id;
110 222
111 /** 223 /**
112 * 2.3 暂停播放背景音乐 224 * 2.3 暂停播放背景音乐
113 * 225 *
114 - * @param id 音乐 ID 226 + * @param id 音乐 ID
115 */ 227 */
116 - (void)pausePlayMusic:(int32_t)id; 228 - (void)pausePlayMusic:(int32_t)id;
117 229
118 /** 230 /**
119 * 2.4 恢复播放背景音乐 231 * 2.4 恢复播放背景音乐
120 * 232 *
121 - * @param id 音乐 ID 233 + * @param id 音乐 ID
122 */ 234 */
123 - (void)resumePlayMusic:(int32_t)id; 235 - (void)resumePlayMusic:(int32_t)id;
124 236
125 /** 237 /**
126 - * 2.5 设置背景音乐的远端音量大小，即主播可以通过此接口设置远端观众能听到的背景音乐的音量大小。 238 + * 2.5 设置所有背景音乐的本地音量和远端音量的大小
127 * 239 *
128 - * @param id 音乐 ID  
129 - * @param volume 音量大小，100为原始音量，范围是：[0 ~ 150]，默认值为100 240 + * 该接口可以设置所有背景音乐的本地音量和远端音量。
  241 + * - 本地音量：即主播本地可以听到的背景音乐的音量大小。
  242 + * - 远端音量：即观众端可以听到的背景音乐的音量大小。
130 * 243 *
131 - * @note 如果要将 volume 设置为大于100的数值，需要进行特殊配置，请联系技术支持。 244 + * @param volume 音量大小，取值范围为0 - 100，默认值：100。
  245 + * @note 如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。
132 */ 246 */
133 -- (void)setMusicPublishVolume:(int32_t)id volume:(NSInteger)volume; 247 +- (void)setAllMusicVolume:(NSInteger)volume;
134 248
135 /** 249 /**
136 - * 2.6 设置背景音乐的本地音量大小，即主播可以通过此接口设置主播自己本地的背景音乐的音量大小。 250 + * 2.6 设置某一首背景音乐的远端音量的大小
137 * 251 *
138 - * @param id 音乐 ID  
139 - * @param volume 音量大小，100为原始音量，范围是：[0 ~ 150]，默认值为100 252 + * 该接口可以细粒度地控制每一首背景音乐的远端音量，也就是观众端可听到的背景音乐的音量大小。
140 * 253 *
141 - * @note 如果要将 volume 设置为大于100的数值，需要进行特殊配置，请联系技术支持。 254 + * @param id 音乐 ID
  255 + * @param volume 音量大小，取值范围为0 - 100；默认值：100
  256 + * @note 如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。
142 */ 257 */
143 -- (void)setMusicPlayoutVolume:(int32_t)id volume:(NSInteger)volume; 258 +- (void)setMusicPublishVolume:(int32_t)id volume:(NSInteger)volume;
144 259
145 /** 260 /**
146 - * 2.7 设置全局背景音乐的本地和远端音量的大小 261 + * 2.7 设置某一首背景音乐的本地音量的大小
147 * 262 *
148 - * @param volume 音量大小，100为原始音量，范围是：[0 ~ 150]，默认值为100 263 + * 该接口可以细粒度地控制每一首背景音乐的本地音量，也就是主播本地可以听到的背景音乐的音量大小。
149 * 264 *
150 - * @note 如果要将 volume 设置为大于100的数值，需要进行特殊配置，请联系技术支持。 265 + * @param id 音乐 ID
  266 + * @param volume 音量大小，取值范围为0 - 100，默认值：100。
  267 + * @note 如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。
151 */ 268 */
152 -- (void)setAllMusicVolume:(NSInteger)volume; 269 +- (void)setMusicPlayoutVolume:(int32_t)id volume:(NSInteger)volume;
153 270
154 /** 271 /**
155 * 2.8 调整背景音乐的音调高低 272 * 2.8 调整背景音乐的音调高低
@@ -168,7 +285,7 @@ typedef NS_ENUM(NSInteger, TXVoiceReverbType); @@ -168,7 +285,7 @@ typedef NS_ENUM(NSInteger, TXVoiceReverbType);
168 - (void)setMusicSpeedRate:(int32_t)id speedRate:(double)speedRate; 285 - (void)setMusicSpeedRate:(int32_t)id speedRate:(double)speedRate;
169 286
170 /** 287 /**
171 - * 2.10 获取背景音乐当前的播放进度（单位：毫秒） 288 + * 2.10 获取背景音乐的播放进度（单位：毫秒）
172 * 289 *
173 * @param id 音乐 ID 290 * @param id 音乐 ID
174 * @return 成功返回当前播放时间，单位：毫秒，失败返回-1 291 * @return 成功返回当前播放时间，单位：毫秒，失败返回-1
@@ -176,82 +293,25 @@ typedef NS_ENUM(NSInteger, TXVoiceReverbType); @@ -176,82 +293,25 @@ typedef NS_ENUM(NSInteger, TXVoiceReverbType);
176 - (NSInteger)getMusicCurrentPosInMS:(int32_t)id; 293 - (NSInteger)getMusicCurrentPosInMS:(int32_t)id;
177 294
178 /** 295 /**
179 - * 2.11 设置背景音乐的播放进度（单位：毫秒） 296 + * 2.11 获取景音乐的总时长（单位：毫秒）
180 * 297 *
181 - * @note 请尽量避免频繁地调用该接口，因为该接口可能会再次读写音乐文件，耗时稍高。  
182 - * 当配合进度条使用时，请在进度条拖动完毕的回调中调用，而避免在拖动过程中实时调用。  
183 - *  
184 - * @param id 音乐 ID  
185 - * @param pts 单位: 毫秒 298 + * @param path 音乐文件路径，如果 path 为空，那么返回当前正在播放的 music 时长。
  299 + * @return 成功返回时长，失败返回-1
186 */ 300 */
187 -- (void)seekMusicToPosInMS:(int32_t)id pts:(NSInteger)pts; 301 +- (NSInteger)getMusicDurationInMS:(NSString *)path;
188 302
189 /** 303 /**
190 - * 2.12 获取景音乐文件的总时长（单位：毫秒） 304 + * 2.12 设置背景音乐的播放进度（单位：毫秒）
191 * 305 *
192 - * @param path 音乐文件路径，如果 path 为空，那么返回当前正在播放的 music 时长。  
193 - * @return 成功返回时长，失败返回-1 306 + * @note 请尽量避免过度频繁地调用该接口，因为该接口可能会再次读写音乐文件，耗时稍高。
  307 + * 因此，当用户拖拽音乐的播放进度条时，请在用户完成拖拽操作后再调用本接口。
  308 + * 因为 UI 上的进度条控件往往会以很高的频率反馈用户的拖拽进度，如不做频率限制，会导致较差的用户体验。
  309 + *
  310 + * @param id 音乐 ID
  311 + * @param pts 单位: 毫秒
194 */ 312 */
195 -- (NSInteger)getMusicDurationInMS:(NSString *)path; 313 +- (void)seekMusicToPosInMS:(int32_t)id pts:(NSInteger)pts;
196 314
197 /// @} 315 /// @}
198 -  
199 -@end  
200 -  
201 -  
202 -@interface TXAudioMusicParam : NSObject  
203 -  
204 -/// 【字段含义】音乐 ID  
205 -/// 【特殊说明】SDK 允许播放多路音乐，因此需要音乐 ID 进行标记，用于控制音乐的开始、停止、音量等  
206 -@property (nonatomic) int32_t ID;  
207 -  
208 -/// 【字段含义】音乐文件的绝对路径  
209 -@property (nonatomic, copy) NSString *path;  
210 -  
211 -/// 【字段含义】音乐循环播放的次数  
212 -/// 【推荐取值】取值范围为0 - 任意正整数，默认值：0。0表示播放音乐一次；1表示播放音乐两次；以此类推  
213 -@property (nonatomic) NSInteger loopCount;  
214 -  
215 -/// 【字段含义】是否将音乐传到远端  
216 -/// 【推荐取值】YES：音乐在本地播放的同时，会上行至云端，因此远端用户也能听到该音乐；NO：音乐不会上行至云端，因此只能在本地听到该音乐。默认值：NO  
217 -@property (nonatomic) BOOL publish;  
218 -  
219 -/// 【字段含义】播放的是否为短音乐文件  
220 -/// 【推荐取值】YES：需要重复播放的短音乐文件；NO：正常的音乐文件。默认值：NO  
221 -@property (nonatomic) BOOL isShortFile;  
222 -  
223 -/// 【字段含义】音乐开始播放时间点，单位毫秒  
224 -@property (nonatomic) NSInteger startTimeMS;  
225 -  
226 -/// 【字段含义】音乐结束播放时间点，单位毫秒，0或者-1表示播放至文件结尾。  
227 -@property (nonatomic) NSInteger endTimeMS;  
228 -  
229 -@end  
230 -  
231 -typedef NS_ENUM(NSInteger, TXVoiceReverbType) {  
232 - TXVoiceReverbType_0 = 0, ///< 关闭混响  
233 - TXVoiceReverbType_1 = 1, ///< KTV  
234 - TXVoiceReverbType_2 = 2, ///< 小房间  
235 - TXVoiceReverbType_3 = 3, ///< 大会堂  
236 - TXVoiceReverbType_4 = 4, ///< 低沉  
237 - TXVoiceReverbType_5 = 5, ///< 洪亮  
238 - TXVoiceReverbType_6 = 6, ///< 金属声  
239 - TXVoiceReverbType_7 = 7, ///< 磁性  
240 -};  
241 -  
242 -typedef NS_ENUM(NSInteger, TXVoiceChangeType) {  
243 - TXVoiceChangeType_0 = 0, ///< 关闭变声  
244 - TXVoiceChangeType_1 = 1, ///< 熊孩子  
245 - TXVoiceChangeType_2 = 2, ///< 萝莉  
246 - TXVoiceChangeType_3 = 3, ///< 大叔  
247 - TXVoiceChangeType_4 = 4, ///< 重金属  
248 - TXVoiceChangeType_5 = 5, ///< 感冒  
249 - TXVoiceChangeType_6 = 6, ///< 外国人  
250 - TXVoiceChangeType_7 = 7, ///< 困兽  
251 - TXVoiceChangeType_8 = 8, ///< 死肥仔  
252 - TXVoiceChangeType_9 = 9, ///< 强电流  
253 - TXVoiceChangeType_10 = 10, ///< 重机械  
254 - TXVoiceChangeType_11 = 11, ///< 空灵  
255 -};  
256 -  
257 -NS_ASSUME_NONNULL_END 316 +@end // End of interface TXAudioEffectManager
  317 +/// @}
1 -/* 1 +/**
2 * Module: 美颜与图像处理参数设置类 2 * Module: 美颜与图像处理参数设置类
3 - *  
4 * Function: 修改美颜、滤镜、绿幕等参数 3 * Function: 修改美颜、滤镜、绿幕等参数
5 - *  
6 */ 4 */
7 -  
8 #import <Foundation/Foundation.h> 5 #import <Foundation/Foundation.h>
9 #import <TargetConditionals.h> 6 #import <TargetConditionals.h>
10 #if TARGET_OS_IPHONE 7 #if TARGET_OS_IPHONE
@@ -18,236 +15,287 @@ typedef NSImage TXImage; @@ -18,236 +15,287 @@ typedef NSImage TXImage;
18 NS_ASSUME_NONNULL_BEGIN 15 NS_ASSUME_NONNULL_BEGIN
19 16
20 /// @defgroup TXBeautyManager_ios TXBeautyManager 17 /// @defgroup TXBeautyManager_ios TXBeautyManager
21 -/// 美颜及动效参数管理 18 +/// 美颜与图像处理参数设置类
22 /// @{ 19 /// @{
23 20
24 /** 21 /**
25 * 美颜（磨皮）算法 22 * 美颜（磨皮）算法
26 - * SDK 内置了多种不同的磨皮算法，您可以选择最适合您产品定位的方案。 23 + * TRTC 内置多种不同的磨皮算法，您可以选择最适合您产品定位的方案。
27 */ 24 */
28 typedef NS_ENUM(NSInteger, TXBeautyStyle) { 25 typedef NS_ENUM(NSInteger, TXBeautyStyle) {
29 - TXBeautyStyleSmooth = 0, ///< 光滑，适用于美女秀场，效果比较明显。  
30 - TXBeautyStyleNature = 1, ///< 自然，磨皮算法更多地保留了面部细节，主观感受上会更加自然。  
31 - TXBeautyStylePitu = 2 ///< 由上海优图实验室提供的美颜算法，磨皮效果介于光滑和自然之间，比光滑保留更多皮肤细节，比自然磨皮程度更高。 26 +
  27 + ///光滑，算法比较激进，磨皮效果比较明显，适用于秀场直播。
  28 + TXBeautyStyleSmooth = 0,
  29 +
  30 + ///自然，算法更多地保留了面部细节，磨皮效果更加自然，适用于绝大多数直播场景。
  31 + TXBeautyStyleNature = 1,
  32 +
  33 + ///优图，由优图实验室提供，磨皮效果介于光滑和自然之间，比光滑保留更多皮肤细节，比自然磨皮程度更高。
  34 + TXBeautyStylePitu = 2
32 }; 35 };
33 36
34 -/// 美颜及动效参数管理  
35 @interface TXBeautyManager : NSObject 37 @interface TXBeautyManager : NSObject
36 38
37 /** 39 /**
38 * 设置美颜（磨皮）算法 40 * 设置美颜（磨皮）算法
39 * 41 *
40 - * SDK 内部集成了两套风格不同的磨皮算法，一套我们取名叫“光滑”，适用于美女秀场，效果比较明显。  
41 - * 另一套我们取名“自然”，磨皮算法更多地保留了面部细节，主观感受上会更加自然。 42 + * TRTC 内置多种不同的磨皮算法，您可以选择最适合您产品定位的方案：
42 * 43 *
43 - * @param beautyStyle 美颜风格，光滑或者自然，光滑风格磨皮更加明显，适合娱乐场景。 44 + * @param beautyStyle 美颜风格，TXBeautyStyleSmooth：光滑；TXBeautyStyleNature：自然；TXBeautyStylePitu：优图。
44 */ 45 */
45 - (void)setBeautyStyle:(TXBeautyStyle)beautyStyle; 46 - (void)setBeautyStyle:(TXBeautyStyle)beautyStyle;
46 47
47 /** 48 /**
48 * 设置美颜级别 49 * 设置美颜级别
49 - * @param level 美颜级别，取值范围0 - 9； 0表示关闭，1 - 9值越大，效果越明显。 50 + *
  51 + * @param beautyLevel 美颜级别，取值范围0 - 9； 0表示关闭，9表示效果最明显。
50 */ 52 */
51 -- (void)setBeautyLevel:(float)level; 53 +- (void)setBeautyLevel:(float)beautyLevel;
52 54
53 /** 55 /**
54 * 设置美白级别 56 * 设置美白级别
55 * 57 *
56 - * @param level 美白级别，取值范围0 - 9；0表示关闭，1 - 9值越大，效果越明显。 58 + * @param whitenessLevel 美白级别，取值范围0 - 9；0表示关闭，9表示效果最明显。
57 */ 59 */
58 -- (void)setWhitenessLevel:(float)level; 60 +- (void)setWhitenessLevel:(float)whitenessLevel;
59 61
60 /** 62 /**
61 * 开启清晰度增强 63 * 开启清晰度增强
62 - *  
63 - * @param enable YES：开启清晰度增强；NO：关闭清晰度增强。默认值：YES  
64 */ 64 */
65 - (void)enableSharpnessEnhancement:(BOOL)enable; 65 - (void)enableSharpnessEnhancement:(BOOL)enable;
66 66
67 /** 67 /**
68 * 设置红润级别 68 * 设置红润级别
69 * 69 *
70 - * @param level 红润级别，取值范围0 - 9；0表示关闭，1 - 9值越大，效果越明显。 70 + * @param ruddyLevel 红润级别，取值范围0 - 9；0表示关闭，9表示效果最明显。
71 */ 71 */
72 -- (void)setRuddyLevel:(float)level; 72 +- (void)setRuddyLevel:(float)ruddyLevel;
73 73
74 /** 74 /**
75 - * 设置指定素材滤镜特效 75 + * 设置色彩滤镜效果
76 * 76 *
77 - * @param image 指定素材，即颜色查找表图片。**必须使用 png 格式** 77 + * 色彩滤镜，是一副包含色彩映射关系的颜色查找表图片，您可以在我们提供的官方 Demo 中找到预先准备好的几张滤镜图片。
  78 + * SDK 会根据该查找表中的映射关系，对摄像头采集出的原始视频画面进行二次处理，以达到预期的滤镜效果。
  79 + * @param image 包含色彩映射关系的颜色查找表图片，必须是 png 格式。
78 */ 80 */
79 - (void)setFilter:(nullable TXImage *)image; 81 - (void)setFilter:(nullable TXImage *)image;
  82 +
80 /** 83 /**
81 - * 设置滤镜浓度 84 + * 设置色彩滤镜的强度
82 * 85 *
83 - * 在美女秀场等应用场景里，滤镜浓度的要求会比较高，以便更加突显主播的差异。  
84 - * 我们默认的滤镜浓度是0.5，如果您觉得滤镜效果不明显，可以使用下面的接口进行调节。 86 + * 该数值越高，色彩滤镜的作用强度越明显，经过滤镜处理后的视频画面跟原画面的颜色差异越大。
  87 + * 我默认的滤镜浓度是0.5，如果您觉得默认的滤镜效果不明显，可以设置为 0.5 以上的数字，最大值为1。
85 * 88 *
86 - * @param strength 从0到1，越大滤镜效果越明显，默认值为0.5。 89 + * @param strength 从0到1，数值越大滤镜效果越明显，默认值为0.5。
87 */ 90 */
88 - (void)setFilterStrength:(float)strength; 91 - (void)setFilterStrength:(float)strength;
89 92
90 /** 93 /**
91 * 设置绿幕背景视频，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效 94 * 设置绿幕背景视频，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
92 * 95 *
93 - * 此处的绿幕功能并非智能抠背，需要被拍摄者的背后有一块绿色的幕布来辅助产生特效 96 + * 此接口所开启的绿幕功能不具备智能去除背景的能力，需要被拍摄者的背后有一块绿色的幕布来辅助产生特效。
94 * 97 *
95 - * @param file 视频文件路径。支持 MP4; nil 表示关闭特效。 98 + * @param path MP4格式的视频文件路径; 设置空值表示关闭特效。
96 */ 99 */
97 -- (void)setGreenScreenFile:(nullable NSString *)file; 100 +- (void)setGreenScreenFile:(nullable NSString *)path;
98 101
99 -#if TARGET_OS_IPHONE  
100 /** 102 /**
101 * 设置大眼级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效 103 * 设置大眼级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
102 * 104 *
103 - * @param level 大眼级别，取值范围0 - 9；0表示关闭，1 - 9值越大，效果越明显。 105 + * @param eyeScaleLevel 大眼级别，取值范围0 - 9；0表示关闭，9表示效果最明显。
104 */ 106 */
105 -- (void)setEyeScaleLevel:(float)level; 107 +#if TARGET_OS_IPHONE
  108 +- (void)setEyeScaleLevel:(float)eyeScaleLevel;
  109 +#endif
106 110
107 /** 111 /**
108 * 设置瘦脸级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效 112 * 设置瘦脸级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
109 * 113 *
110 - * @param level 瘦脸级别，取值范围0 - 9；0表示关闭，1 - 9值越大，效果越明显。 114 + * @param faceSlimLevel 瘦脸级别，取值范围0 - 9；0表示关闭，9表示效果最明显。
111 */ 115 */
112 -- (void)setFaceSlimLevel:(float)level; 116 +#if TARGET_OS_IPHONE
  117 +- (void)setFaceSlimLevel:(float)faceSlimLevel;
  118 +#endif
113 119
114 /** 120 /**
115 - *设置 V 脸级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效 121 + * 设置 V 脸级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
116 * 122 *
117 - * @param level V脸级别，取值范围0 - 9；0表示关闭，1 - 9值越大，效果越明显。 123 + * @param faceVLevel V脸级别，取值范围0 - 9；0表示关闭，9表示效果最明显。
118 */ 124 */
119 -- (void)setFaceVLevel:(float)level; 125 +#if TARGET_OS_IPHONE
  126 +- (void)setFaceVLevel:(float)faceVLevel;
  127 +#endif
120 128
121 /** 129 /**
122 * 设置下巴拉伸或收缩，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效 130 * 设置下巴拉伸或收缩，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
123 * 131 *
124 - * @param level 下巴拉伸或收缩级别，取值范围-9 - 9；0 表示关闭，小于0表示收缩，大于0表示拉伸。 132 + * @param chinLevel 下巴拉伸或收缩级别，取值范围-9 - 9；0 表示关闭，小于0表示收缩，大于0表示拉伸。
125 */ 133 */
126 -- (void)setChinLevel:(float)level; 134 +#if TARGET_OS_IPHONE
  135 +- (void)setChinLevel:(float)chinLevel;
  136 +#endif
  137 +
127 /** 138 /**
128 * 设置短脸级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效 139 * 设置短脸级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
129 * 140 *
130 - * @param level 短脸级别，取值范围0 - 9；0表示关闭，1 - 9值越大，效果越明显。 141 + * @param faceShortLevel 短脸级别，取值范围0 - 9；0表示关闭，9表示效果最明显。
131 */ 142 */
132 -- (void)setFaceShortLevel:(float)level; 143 +#if TARGET_OS_IPHONE
  144 +- (void)setFaceShortLevel:(float)faceShortLevel;
  145 +#endif
133 146
134 /** 147 /**
135 * 设置窄脸级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效 148 * 设置窄脸级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
136 * 149 *
137 - * @param level 短脸级别，取值范围0 - 9；0表示关闭，1 - 9值越大，效果越明显。 150 + * @param level 窄脸级别，取值范围0 - 9；0表示关闭，9表示效果最明显。
138 */ 151 */
139 -- (void)setFaceNarrowLevel:(float)level; 152 +#if TARGET_OS_IPHONE
  153 +- (void)setFaceNarrowLevel:(float)faceNarrowLevel;
  154 +#endif
140 155
141 /** 156 /**
142 * 设置瘦鼻级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效 157 * 设置瘦鼻级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
143 * 158 *
144 - * @param level 瘦鼻级别，取值范围0 - 9；0表示关闭，1 - 9值越大，效果越明显。 159 + * @param noseSlimLevel 瘦鼻级别，取值范围0 - 9；0表示关闭，9表示效果最明显。
145 */ 160 */
146 -- (void)setNoseSlimLevel:(float)level; 161 +#if TARGET_OS_IPHONE
  162 +- (void)setNoseSlimLevel:(float)noseSlimLevel;
  163 +#endif
147 164
148 /** 165 /**
149 - * 设置亮眼 ，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效 166 + * 设置亮眼级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
150 * 167 *
151 - * @param level 亮眼级别，取值范围0 - 9；0表示关闭，1 - 9值越大，效果越明显。 168 + * @param eyeLightenLevel 亮眼级别，取值范围0 - 9；0表示关闭，9表示效果最明显。
152 */ 169 */
153 -- (void)setEyeLightenLevel:(float)level; 170 +#if TARGET_OS_IPHONE
  171 +- (void)setEyeLightenLevel:(float)eyeLightenLevel;
  172 +#endif
154 173
155 /** 174 /**
156 - * 设置白牙 ，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效 175 + * 设置牙齿美白级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
157 * 176 *
158 - * @param level 白牙级别，取值范围0 - 9；0表示关闭，1 - 9值越大，效果越明显。 177 + * @param toothWhitenLevel 白牙级别，取值范围0 - 9；0表示关闭，9表示效果最明显。
159 */ 178 */
160 -- (void)setToothWhitenLevel:(float)level; 179 +#if TARGET_OS_IPHONE
  180 +- (void)setToothWhitenLevel:(float)toothWhitenLevel;
  181 +#endif
161 182
162 /** 183 /**
163 - * 设置祛皱 ，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效 184 + * 设置祛皱级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
164 * 185 *
165 - * @param level 祛皱级别，取值范围0 - 9；0表示关闭，1 - 9值越大，效果越明显。 186 + * @param wrinkleRemoveLevel 祛皱级别，取值范围0 - 9；0表示关闭，9表示效果最明显。
166 */ 187 */
167 -- (void)setWrinkleRemoveLevel:(float)level; 188 +#if TARGET_OS_IPHONE
  189 +- (void)setWrinkleRemoveLevel:(float)wrinkleRemoveLevel;
  190 +#endif
168 191
169 /** 192 /**
170 - * 设置祛眼袋 ，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效 193 + * 设置祛眼袋级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
171 * 194 *
172 - * @param level 祛眼袋级别，取值范围0 - 9；0表示关闭，1 - 9值越大，效果越明显。 195 + * @param pounchRemoveLevel 祛眼袋级别，取值范围0 - 9；0表示关闭，9表示效果最明显。
173 */ 196 */
174 -- (void)setPounchRemoveLevel:(float)level; 197 +#if TARGET_OS_IPHONE
  198 +- (void)setPounchRemoveLevel:(float)pounchRemoveLevel;
  199 +#endif
175 200
176 /** 201 /**
177 - * 设置法令纹 ，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效 202 + * 设置法令纹去除级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
178 * 203 *
179 - * @param level 法令纹级别，取值范围0 - 9；0表示关闭，1 - 9值越大，效果越明显。 204 + * @param smileLinesRemoveLevel 法令纹级别，取值范围0 - 9；0表示关闭，9表示效果最明显。
180 */ 205 */
181 -- (void)setSmileLinesRemoveLevel:(float)level; 206 +#if TARGET_OS_IPHONE
  207 +- (void)setSmileLinesRemoveLevel:(float)smileLinesRemoveLevel;
  208 +#endif
182 209
183 /** 210 /**
184 - * 设置发际线 ，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效 211 + * 设置发际线调整级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
185 * 212 *
186 - * @param level 发际线级别，取值范围-9 - 9；0表示关闭，小于0表示抬高，大于0表示降低。 213 + * @param foreheadLevel 发际线级别，取值范围-9 - 9；0表示关闭，9表示效果最明显。
187 */ 214 */
188 -- (void)setForeheadLevel:(float)level; 215 +#if TARGET_OS_IPHONE
  216 +- (void)setForeheadLevel:(float)foreheadLevel;
  217 +#endif
189 218
190 /** 219 /**
191 - * 设置眼距 ，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效 220 + * 设置眼距，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
192 * 221 *
193 - * @param level 眼距级别，取值范围-9 - 9；0表示关闭，小于0表示拉伸，大于0表示收缩。 222 + * @param eyeDistanceLevel 眼距级别，取值范围-9 - 9；0表示关闭，小于0表示拉伸，大于0表示收缩。
194 */ 223 */
195 -- (void)setEyeDistanceLevel:(float)level; 224 +#if TARGET_OS_IPHONE
  225 +- (void)setEyeDistanceLevel:(float)eyeDistanceLevel;
  226 +#endif
196 227
197 /** 228 /**
198 - * 设置眼角 ，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效 229 + * 设置眼角调整级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
199 * 230 *
200 - * @param level 眼角级别，取值范围-9 - 9；0表示关闭，小于0表示降低，大于0表示抬高。 231 + * @param eyeAngleLevel 眼角调整级别，取值范围-9 - 9；0表示关闭，9表示效果最明显。
201 */ 232 */
202 -- (void)setEyeAngleLevel:(float)level; 233 +#if TARGET_OS_IPHONE
  234 +- (void)setEyeAngleLevel:(float)eyeAngleLevel;
  235 +#endif
203 236
204 /** 237 /**
205 - * 设置嘴型 ，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效 238 + * 设置嘴型调整级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
206 * 239 *
207 - * @param level 嘴型级别，取值范围-9 - 9；0表示关闭，小于0表示拉伸，大于0表示收缩。 240 + * @param mouthShapeLevel 嘴型级别，取值范围-9 - 9；0表示关闭，小于0表示拉伸，大于0表示收缩。
208 */ 241 */
209 -- (void)setMouthShapeLevel:(float)level; 242 +#if TARGET_OS_IPHONE
  243 +- (void)setMouthShapeLevel:(float)mouthShapeLevel;
  244 +#endif
210 245
211 /** 246 /**
212 - * 设置鼻翼 ，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效 247 + * 设置鼻翼调整级别，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
213 * 248 *
214 - * @param level 鼻翼级别，取值范围-9 - 9；0表示关闭，小于0表示拉伸，大于0表示收缩。 249 + * @param noseWingLevel 鼻翼调整级别，取值范围-9 - 9；0表示关闭，小于0表示拉伸，大于0表示收缩。
215 */ 250 */
216 -- (void)setNoseWingLevel:(float)level; 251 +#if TARGET_OS_IPHONE
  252 +- (void)setNoseWingLevel:(float)noseWingLevel;
  253 +#endif
217 254
218 /** 255 /**
219 - * 设置鼻子位置 ，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效  
220 - * @param level 鼻子位置级别，取值范围-9 - 9；0表示关闭，小于0表示抬高，大于0表示降低。 256 + * 设置鼻子位置，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
  257 + *
  258 + * @param nosePositionLevel 鼻子位置级别，取值范围-9 - 9；0表示关闭，小于0表示抬高，大于0表示降低。
221 */ 259 */
222 -- (void)setNosePositionLevel:(float)level; 260 +#if TARGET_OS_IPHONE
  261 +- (void)setNosePositionLevel:(float)nosePositionLevel;
  262 +#endif
223 263
224 /** 264 /**
225 - * 设置嘴唇厚度 ，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效  
226 - * @param level 嘴唇厚度级别，取值范围-9 - 9；0表示关闭，小于0表示拉伸，大于0表示收缩。 265 + * 设置嘴唇厚度，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
  266 + *
  267 + * @param lipsThicknessLevel 嘴唇厚度级别，取值范围-9 - 9；0表示关闭，小于0表示拉伸，大于0表示收缩。
227 */ 268 */
228 -- (void)setLipsThicknessLevel:(float)level; 269 +#if TARGET_OS_IPHONE
  270 +- (void)setLipsThicknessLevel:(float)lipsThicknessLevel;
  271 +#endif
229 272
230 /** 273 /**
231 * 设置脸型，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效 274 * 设置脸型，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
232 - * @param level 美型级别，取值范围0 - 9；0表示关闭，1 - 9值越大，效果越明显。 275 + *
  276 + * @param faceBeautyLevel 美型级别，取值范围0 - 9；0表示关闭，1 - 9值越大，效果越明显。
233 */ 277 */
234 -- (void)setFaceBeautyLevel:(float)level; 278 +#if TARGET_OS_IPHONE
  279 +- (void)setFaceBeautyLevel:(float)faceBeautyLevel;
  280 +#endif
235 281
236 /** 282 /**
237 * 选择 AI 动效挂件，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效 283 * 选择 AI 动效挂件，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
238 * 284 *
239 - * @param tmplName 动效名称  
240 - * @param tmplDir 动效所在目录 285 + * @param tmplName 动效挂件名称
  286 + * @param tmplDir 动效素材文件所在目录
241 */ 287 */
  288 +#if TARGET_OS_IPHONE
242 - (void)setMotionTmpl:(nullable NSString *)tmplName inDir:(nullable NSString *)tmplDir; 289 - (void)setMotionTmpl:(nullable NSString *)tmplName inDir:(nullable NSString *)tmplDir;
  290 +#endif
243 291
244 /** 292 /**
245 - * 设置动效静音，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效  
246 - * 293 + * 是否在动效素材播放时静音，该接口仅在 [企业版 SDK](https://cloud.tencent.com/document/product/647/32689#Enterprise) 中生效
247 * 有些挂件本身会有声音特效，通过此 API 可以关闭这些特效播放时所带的声音效果。 294 * 有些挂件本身会有声音特效，通过此 API 可以关闭这些特效播放时所带的声音效果。
248 * 295 *
249 * @param motionMute YES：静音；NO：不静音。 296 * @param motionMute YES：静音；NO：不静音。
250 */ 297 */
  298 +#if TARGET_OS_IPHONE
251 - (void)setMotionMute:(BOOL)motionMute; 299 - (void)setMotionMute:(BOOL)motionMute;
252 #endif 300 #endif
253 301
1 -/*  
2 -* Module: TXDeviceManager 设备管理类  
3 -*  
4 -* Function: 用于管理 iOS / Mac 的硬件设备  
5 -*  
6 -*/ 1 +/**
  2 + * Module: TRTC 音视频设备管理模块
  3 + * Function: 用于管理摄像头、麦克风和扬声器等音视频相关的硬件设备
  4 + */
  5 +/// @defgroup TXDeviceManager_ios TXDeviceManager
  6 +/// TRTC 音视频设备管理模块
  7 +/// @{
7 8
8 #import <Foundation/Foundation.h> 9 #import <Foundation/Foundation.h>
  10 +#if TARGET_OS_IPHONE
  11 +#import <UIKit/UIKit.h>
  12 +#elif TARGET_OS_MAC
  13 +#import <AppKit/AppKit.h>
  14 +#endif
9 15
10 -NS_ASSUME_NONNULL_BEGIN 16 +/////////////////////////////////////////////////////////////////////////////////
  17 +//
  18 +// 音视频设备相关的类型定义
  19 +//
  20 +/////////////////////////////////////////////////////////////////////////////////
  21 +/// @name 音视频设备相关的类型定义
  22 +/// @{
11 23
  24 +/**
  25 + * 系统音量类型（仅适用于移动设备）
  26 + *
  27 + * 现代智能手机中一般都具备两套系统音量类型，即“通话音量”和“媒体音量”。
  28 + * - 通话音量：手机专门为接打电话所设计的音量类型，自带回声抵消（AEC）功能，并且支持通过蓝牙耳机上的麦克风进行拾音，缺点是音质比较一般。
  29 + * 当您通过手机侧面的音量按键下调手机音量时，如果无法将其调至零（也就是无法彻底静音），说明您的手机当前出于通话音量。
  30 + * - 媒体音量：手机专门为音乐场景所设计的音量类型，无法使用系统的 AEC 功能，并且不支持通过蓝牙耳机的麦克风进行拾音，但具备更好的音乐播放效果。
  31 + * 当您通过手机侧面的音量按键下调手机音量时，如果能够将手机音量调至彻底静音，说明您的手机当前出于媒体音量。
  32 + *
  33 + * SDK 目前提供了三种系统音量类型的控制模式：自动切换模式、全程通话音量模式、全程媒体音量模式。
  34 + */
12 #if TARGET_OS_IPHONE 35 #if TARGET_OS_IPHONE
  36 +typedef NS_ENUM(NSInteger, TXSystemVolumeType) {
13 37
14 -/// 系统音量类型  
15 -typedef NS_ENUM(NSInteger, TXSystemVolumeType);  
16 -/// 声音播放模式（音频路由）  
17 -typedef NS_ENUM(NSInteger, TXAudioRoute); 38 + ///自动切换模式：
  39 + ///也被称为“麦上通话，麦下媒体”，即主播上麦时使用通话音量，观众不上麦则使用媒体音量，适合在线直播场景。
  40 + TXSystemVolumeTypeAuto = 0,
18 41
19 -#elif TARGET_OS_MAC 42 + ///全程媒体音量：
  43 + ///通话全程使用媒体音量，并不是非常常用的音量类型，适用于对音质要求比较苛刻的音乐场景中。
  44 + ///如果您的用户大都使用外接设备（比如外接声卡）为主，可以使用该模式，否则请慎用。
  45 + TXSystemVolumeTypeMedia = 1,
20 46
21 -/// 设备类型  
22 -typedef NS_ENUM(NSInteger, TXMediaDeviceType);  
23 -/// 设备描述  
24 -@class TXMediaDeviceInfo; 47 + ///全程通话音量：
  48 + ///该方案的优势在于用户在上下麦时音频模块无需切换工作模式，可以做到无缝上下麦，适合于用户需要频繁上下麦的应用场景。
  49 + TXSystemVolumeTypeVOIP = 2,
25 50
  51 +};
26 #endif 52 #endif
27 53
  54 +/**
  55 + * 音频路由（即声音的播放模式）
  56 + *
  57 + * 音频路由，即声音是从手机的扬声器还是从听筒中播放出来，因此该接口仅适用于手机等移动端设备。
  58 + * 手机有两个扬声器：一个是位于手机顶部的听筒，一个是位于手机底部的立体声扬声器。
  59 + * - 设置音频路由为听筒时，声音比较小，只有将耳朵凑近才能听清楚，隐私性较好，适合用于接听电话。
  60 + * - 设置音频路由为扬声器时，声音比较大，不用将手机贴脸也能听清，因此可以实现“免提”的功能。
  61 + */
  62 +#if TARGET_OS_IPHONE
  63 +typedef NS_ENUM(NSInteger, TXAudioRoute) {
28 64
29 -@interface TXDeviceManager : NSObject 65 + /// Speakerphone：使用扬声器播放（即“免提”），扬声器位于手机底部，声音偏大，适合外放音乐。
  66 + TXAudioRouteSpeakerphone = 0,
30 67
31 -- (instancetype)init NS_UNAVAILABLE; 68 + /// Earpiece：使用听筒播放，听筒位于手机顶部，声音偏小，适合需要保护隐私的通话场景。
  69 + TXAudioRouteEarpiece = 1,
32 70
33 -#if TARGET_OS_IPHONE 71 +};
  72 +#endif
34 73
35 /** 74 /**
36 - * 判断当前是否为前置摄像头 75 + * 设备类型（仅适用于桌面平台）
  76 + *
  77 + * 该枚举值用于定义三种类型的音视频设备，即摄像头、麦克风和扬声器，以便让一套设备管理接口可以操控三种不同类型的设备。
  78 + */
  79 +#if TARGET_OS_MAC && !TARGET_OS_IPHONE
  80 +typedef NS_ENUM(NSInteger, TXMediaDeviceType) {
  81 + TXMediaDeviceTypeUnknown = -1, ///< undefined device type
  82 + TXMediaDeviceTypeAudioInput = 0, ///< microphone
  83 + TXMediaDeviceTypeAudioOutput = 1, ///< speaker or earpiece
  84 + TXMediaDeviceTypeVideoCamera = 2, ///< camera
  85 +};
  86 +#endif
  87 +
  88 +/**
  89 + * 音视频设备的相关信息（仅适用于桌面平台）
  90 + *
  91 + * 该结构体用于描述一个音视频设备的关键信息，比如设备ID、设备名称等等，以便用户能够在用户界面上选择自己期望使用的音视频设备。
  92 + */
  93 +#if TARGET_OS_MAC && !TARGET_OS_IPHONE
  94 +@interface TXMediaDeviceInfo : NSObject
  95 +/// device type
  96 +@property(assign, nonatomic) TXMediaDeviceType type;
  97 +/// device id
  98 +@property(copy, nonatomic, nullable) NSString *deviceId;
  99 +/// device name
  100 +@property(copy, nonatomic, nullable) NSString *deviceName;
  101 +@end
  102 +#endif
  103 +/// @}
  104 +
  105 +@interface TXDeviceManager : NSObject
  106 +
  107 +/////////////////////////////////////////////////////////////////////////////////
  108 +//
  109 +// 移动端设备操作接口（iOS Android）
  110 +//
  111 +/////////////////////////////////////////////////////////////////////////////////
  112 +/// @name 移动端设备操作接口
  113 +/// @{
  114 +
  115 +/**
  116 + * 1.1 判断当前是否为前置摄像头（仅适用于移动端）
37 */ 117 */
  118 +#if TARGET_OS_IPHONE
38 - (BOOL)isFrontCamera; 119 - (BOOL)isFrontCamera;
39 120
40 /** 121 /**
41 - * 切换摄像头 122 + * 1.2 切换前置或后置摄像头（仅适用于移动端）
42 */ 123 */
43 - (NSInteger)switchCamera:(BOOL)frontCamera; 124 - (NSInteger)switchCamera:(BOOL)frontCamera;
44 125
45 /** 126 /**
46 - * 查询当前摄像头是否支持缩放 127 + * 1.3 查询当前摄像头是否支持缩放（仅适用于移动端）
47 */ 128 */
48 - (BOOL)isCameraZoomSupported; 129 - (BOOL)isCameraZoomSupported;
49 130
50 /** 131 /**
51 - * 查询当前摄像头支持的最大缩放比例 132 + * 1.3 获取摄像头的最大缩放倍数（仅适用于移动端）
52 */ 133 */
53 - (CGFloat)getCameraZoomMaxRatio; 134 - (CGFloat)getCameraZoomMaxRatio;
54 135
55 /** 136 /**
56 - * 设置当前摄像头的缩放比例 137 + * 1.4 设置摄像头的缩放倍数（仅适用于移动端）
57 * 138 *
58 * @param zoomRatio 取值范围1 - 5，取值为1表示最远视角（正常镜头），取值为5表示最近视角（放大镜头）。 139 * @param zoomRatio 取值范围1 - 5，取值为1表示最远视角（正常镜头），取值为5表示最近视角（放大镜头）。
59 - * 最大值推荐为5，若超过5，视频数据会变得模糊不清。默认值为1。  
60 */ 140 */
61 - (NSInteger)setCameraZoomRatio:(CGFloat)zoomRatio; 141 - (NSInteger)setCameraZoomRatio:(CGFloat)zoomRatio;
62 142
63 /** 143 /**
64 - * 查询是否支持自动识别人脸位置 144 + * 1.5 查询是否支持自动识别人脸位置（仅适用于移动端）
65 */ 145 */
66 - (BOOL)isAutoFocusEnabled; 146 - (BOOL)isAutoFocusEnabled;
67 147
68 /** 148 /**
69 - * 设置人脸自动识别 149 + * 1.6 开启自动对焦功能（仅适用于移动端）
70 * 150 *
71 - * @param enabled YES: 开启；NO：关闭，默认值：YES 151 + * 开启后，SDK 会自动检测画面中的人脸位置，并将摄像头的焦点始终对焦在人脸位置上。
72 */ 152 */
73 - (NSInteger)enableCameraAutoFocus:(BOOL)enabled; 153 - (NSInteger)enableCameraAutoFocus:(BOOL)enabled;
74 154
75 /** 155 /**
76 - * 设置摄像头焦点 156 + * 1.7 设置摄像头的对焦位置（仅适用于移动端）
77 * 157 *
78 - * @param position 对焦位置 158 + * 您可以通过该接口实现如下交互：
  159 + * 1. 在本地摄像头的预览画面上，允许用户单击操作。
  160 + * 2. 在用户的单击位置显示一个矩形方框，以示摄像头会在此处对焦。
  161 + * 3. 随后将用户点击位置的坐标通过本接口传递给 SDK，之后 SDK 会操控摄像头按照用户期望的位置进行对焦。
  162 + * @note 使用该接口的前提是先通过 {@link enableCameraAutoFocus} 关闭自动对焦功能。
  163 + * @param position 对焦位置，请传入期望对焦点的坐标值
  164 + * @return 0：操作成功；负数：操作失败。
79 */ 165 */
80 - (NSInteger)setCameraFocusPosition:(CGPoint)position; 166 - (NSInteger)setCameraFocusPosition:(CGPoint)position;
81 167
82 /** 168 /**
83 - * 查询是否支持开关闪光灯（手电筒模式） 169 + * 1.8 查询是否支持开启闪光灯（仅适用于移动端）
84 */ 170 */
85 - (BOOL)isCameraTorchSupported; 171 - (BOOL)isCameraTorchSupported;
86 172
87 /** 173 /**
88 - * 开关闪光灯  
89 - *  
90 - * enabled YES：开启；NO：关闭，默认值：NO 174 + * 1.8 开启/关闭闪光灯，也就是手电筒模式（仅适用于移动端）
91 */ 175 */
92 - (NSInteger)enableCameraTorch:(BOOL)enabled; 176 - (NSInteger)enableCameraTorch:(BOOL)enabled;
93 177
94 /** 178 /**
95 - * 设置通话时使用的系统音量类型  
96 - *  
97 - * @note  
98 - * 1. 需要在调用 startLocalAudio() 之前调用该接口。  
99 - * 2. 如无特殊需求，不推荐您自行设置，您只需通过 enterRoom 设置好适合您的场景，SDK 内部会自动选择相匹配的音量类型。 179 + * 1.9 设置音频路由（仅适用于移动端）
100 * 180 *
101 - * @param type 系统音量类型，参见 TXSystemVolumeType 说明。如无特殊需求，不推荐您自行设置。 181 + * 手机有两个音频播放设备：一个是位于手机顶部的听筒，一个是位于手机底部的立体声扬声器。
  182 + * 设置音频路由为听筒时，声音比较小，只有将耳朵凑近才能听清楚，隐私性较好，适合用于接听电话。
  183 + * 设置音频路由为扬声器时，声音比较大，不用将手机贴脸也能听清，因此可以实现“免提”的功能。
102 */ 184 */
103 -- (NSInteger)setSystemVolumeType:(TXSystemVolumeType)type; 185 +- (NSInteger)setAudioRoute:(TXAudioRoute)route;
104 186
105 /** 187 /**
106 - * 设置音频路由  
107 - *  
108 - * 微信和手机 QQ 视频通话功能的免提模式就是基于音频路由实现的。  
109 - * 一般手机都有两个扬声器，一个是位于顶部的听筒扬声器，声音偏小；一个是位于底部的立体声扬声器，声音偏大。  
110 - * 设置音频路由的作用就是决定声音使用哪个扬声器播放。  
111 - *  
112 - * @param route 音频路由，即声音由哪里输出（扬声器、听筒），默认值：TXAudioRouteSpeakerphone 188 + * 1.10 设置系统音量类型（仅适用于移动端）
113 */ 189 */
114 -- (NSInteger)setAudioRoute:(TXAudioRoute)route; 190 +- (NSInteger)setSystemVolumeType:(TXSystemVolumeType)type;
  191 +#endif
115 192
116 -#elif TARGET_OS_MAC 193 +/// @}
  194 +/////////////////////////////////////////////////////////////////////////////////
  195 +//
  196 +// 桌面端设备操作接口（Windows Mac）
  197 +//
  198 +/////////////////////////////////////////////////////////////////////////////////
  199 +/// @name 桌面端设备操作接口
  200 +/// @{
117 201
118 /** 202 /**
119 - * 获取设备列表  
120 - *  
121 - * @param type 设备类型 203 + * 2.1 获取设备列表（仅适用于桌面端）
122 */ 204 */
123 -- (NSArray<TXMediaDeviceInfo *> * _Nullable)getDevicesList:(TXMediaDeviceType)type; 205 +#if !TARGET_OS_IPHONE && TARGET_OS_MAC
  206 +- (NSArray<TXMediaDeviceInfo *> *_Nullable)getDevicesList:(TXMediaDeviceType)type;
124 207
125 /** 208 /**
126 - * 设置要使用的设备 209 + * 2.2 设置当前要使用的设备（仅适用于桌面端）
127 * 210 *
128 - * @param type 设备类型  
129 - * @param deviceId 从 getDevicesList 中得到的设备 ID 211 + * @param type 设备类型，详见 TXMediaDeviceType 定义。
  212 + * @param deviceId 设备ID，您可以通过接口 {@link getDevicesList} 获得设备 ID。
  213 + * @return 0：操作成功；负数：操作失败。
130 */ 214 */
131 - (NSInteger)setCurrentDevice:(TXMediaDeviceType)type deviceId:(NSString *)deviceId; 215 - (NSInteger)setCurrentDevice:(TXMediaDeviceType)type deviceId:(NSString *)deviceId;
132 216
133 /** 217 /**
134 - * 获取当前的设备信息  
135 - *  
136 - * @param type 设备类型 218 + * 2.3 获取当前正在使用的设备（仅适用于桌面端）
137 */ 219 */
138 -- (TXMediaDeviceInfo * _Nullable)getCurrentDevice:(TXMediaDeviceType)type; 220 +- (TXMediaDeviceInfo *_Nullable)getCurrentDevice:(TXMediaDeviceType)type;
139 221
140 /** 222 /**
141 - * 设置当前设备的音量 223 + * 2.4 设置当前设备的音量（仅适用于桌面端）
142 * 224 *
143 - * @param volume 音量值，范围0 - 100  
144 - * @param type 设备类型，仅支持 AudioInput 和 AudioOutput 类型。 225 + * 这里的音量指的是麦克风的采集音量或者扬声器的播放音量，摄像头是不支持设置音量的。
  226 + *
  227 + * @param volume 音量大小，取值范围为0 - 100，默认值：100。
  228 + * @note 如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。
145 */ 229 */
146 - (NSInteger)setCurrentDeviceVolume:(NSInteger)volume deviceType:(TXMediaDeviceType)type; 230 - (NSInteger)setCurrentDeviceVolume:(NSInteger)volume deviceType:(TXMediaDeviceType)type;
147 231
148 /** 232 /**
149 - * 获取当前设备的音量 233 + * 2.5 获取当前设备的音量（仅适用于桌面端）
150 * 234 *
151 - * @param type 设备类型，仅支持 AudioInput 和 AudioOutput 类型。 235 + * 这里的音量指的是麦克风的采集音量或者扬声器的播放音量，摄像头是不支持获取音量的。
152 */ 236 */
153 - (NSInteger)getCurrentDeviceVolume:(TXMediaDeviceType)type; 237 - (NSInteger)getCurrentDeviceVolume:(TXMediaDeviceType)type;
154 238
155 /** 239 /**
156 - * 设置当前设备的静音状态 240 + * 2.6 设置当前设备的静音状态（仅适用于桌面端）
157 * 241 *
158 - * @param mute 设置为 YES 时，麦克风设备静音  
159 - * @param type 设备类型，仅支持 AudioInput 和 AudioOutput 类型。 242 + * 这里的音量指的是麦克风和扬声器，摄像头是不支持静音操作的。
160 */ 243 */
161 - (NSInteger)setCurrentDeviceMute:(BOOL)mute deviceType:(TXMediaDeviceType)type; 244 - (NSInteger)setCurrentDeviceMute:(BOOL)mute deviceType:(TXMediaDeviceType)type;
162 245
163 /** 246 /**
164 - * 获取当前设备的静音状态 247 + * 2.7 获取当前设备的静音状态（仅适用于桌面端）
165 * 248 *
166 - * @param type 设备类型，仅支持 AudioInput 和 AudioOutput 类型。 249 + * 这里的音量指的是麦克风和扬声器，摄像头是不支持静音操作的。
167 */ 250 */
168 - (BOOL)getCurrentDeviceMute:(TXMediaDeviceType)type; 251 - (BOOL)getCurrentDeviceMute:(TXMediaDeviceType)type;
169 252
170 /** 253 /**
171 - * 开始摄像头测试 254 + * 2.8 开始摄像头测试（仅适用于桌面端）
172 * 255 *
173 - * @note 在测试过程中可以使用 setCurrentCameraDevice 接口切换摄像头。  
174 - * @param view 预览画面所在的父控件 256 + * @note 在测试过程中可以使用 {@link setCurrentDevice} 接口切换摄像头。
175 */ 257 */
176 - (NSInteger)startCameraDeviceTest:(NSView *)view; 258 - (NSInteger)startCameraDeviceTest:(NSView *)view;
177 259
178 /** 260 /**
179 - * 结束摄像头测试 261 + * 2.9 结束摄像头测试（仅适用于桌面端）
180 */ 262 */
181 - (NSInteger)stopCameraDeviceTest; 263 - (NSInteger)stopCameraDeviceTest;
182 264
183 /** 265 /**
184 - * 开始麦克风测试 266 + * 2.10 开始麦克风测试（仅适用于桌面端）
185 * 267 *
186 - * 该方法测试麦克风是否能正常工作，volume 的取值范围为0 - 100。 268 + * 该接口可以测试麦克风是否能正常工作，测试到的麦克风采集音量的大小，会以回调的形式通知给您，其中 volume 的取值范围为0 - 100。
  269 + * @param interval 麦克风音量的回调间隔。
187 */ 270 */
188 - (NSInteger)startMicDeviceTest:(NSInteger)interval testEcho:(void (^)(NSInteger volume))testEcho; 271 - (NSInteger)startMicDeviceTest:(NSInteger)interval testEcho:(void (^)(NSInteger volume))testEcho;
189 272
190 /** 273 /**
191 - * 结束麦克风测试 274 + * 2.11 结束麦克风测试（仅适用于桌面端）
192 */ 275 */
193 - (NSInteger)stopMicDeviceTest; 276 - (NSInteger)stopMicDeviceTest;
194 277
195 /** 278 /**
196 - * 开始扬声器测试 279 + * 2.12 开始扬声器测试（仅适用于桌面端）
197 * 280 *
198 - * 该方法播放指定的音频文件测试播放设备是否能正常工作。如果能听到声音，说明播放设备能正常工作。 281 + * 该接口通过播放指定的音频文件，用于测试播放设备是否能正常工作。如果用户在测试时能听到声音，说明播放设备能正常工作。
  282 + * @param filePath 声音文件的路径
199 */ 283 */
200 - (NSInteger)startSpeakerDeviceTest:(NSString *)audioFilePath onVolumeChanged:(void (^)(NSInteger volume, BOOL isLastFrame))volumeBlock; 284 - (NSInteger)startSpeakerDeviceTest:(NSString *)audioFilePath onVolumeChanged:(void (^)(NSInteger volume, BOOL isLastFrame))volumeBlock;
201 285
202 /** 286 /**
203 - * 结束扬声器测试 287 + * 2.13 结束扬声器测试（仅适用于桌面端）
204 */ 288 */
205 - (NSInteger)stopSpeakerDeviceTest; 289 - (NSInteger)stopSpeakerDeviceTest;
206 -  
207 #endif 290 #endif
208 291
  292 +/// @}
209 @end 293 @end
210 -  
211 -#if TARGET_OS_IPHONE  
212 -/**  
213 - * 系统音量类型  
214 - *  
215 - * 智能手机一般具备两种系统音量类型，即通话音量类型和媒体音量类型。  
216 - * - 通话音量：手机专门为通话场景设计的音量类型，使用手机自带的回声抵消功能，音质相比媒体音量类型较差，  
217 - * 无法通过音量按键将音量调成零，但是支持蓝牙耳机上的麦克风。  
218 - *  
219 - * - 媒体音量：手机专门为音乐场景设计的音量类型，音质相比于通话音量类型要好，通过通过音量按键可以将音量调成零。  
220 - * 使用媒体音量类型时，如果要开启回声抵消（AEC）功能，SDK 会开启内置的声学处理算法对声音进行二次处理。  
221 - * 在媒体音量模式下，蓝牙耳机无法使用自带的麦克风采集声音，只能使用手机上的麦克风进行声音采集。  
222 - *  
223 - * SDK 目前提供了三种系统音量类型的控制模式，分别为：  
224 - * - Auto：“麦上通话，麦下媒体”，即主播上麦时使用通话音量，观众不上麦则使用媒体音量，适合在线直播场景。  
225 - * 如果您在 enterRoom 时选择的场景为 TRTCAppSceneLIVE 或 TRTCAppSceneVoiceChatRoom，SDK 会自动选择该模式。  
226 - *  
227 - * - VOIP：全程使用通话音量，适合多人会议场景。  
228 - * 如果您在 enterRoom 时选择的场景为 TRTCAppSceneVideoCall 或 TRTCAppSceneAudioCall，SDK 会自动选择该模式。  
229 - *  
230 - * - Media：通话全程使用媒体音量，不常用，适合个别有特殊需求（如主播外接声卡）的应用场景。  
231 - *  
232 - */  
233 -typedef NS_ENUM(NSInteger, TXSystemVolumeType) {  
234 - TXSystemVolumeTypeAuto = 0,  
235 - TXSystemVolumeTypeMedia = 1,  
236 - TXSystemVolumeTypeVOIP = 2,  
237 -};  
238 -  
239 -  
240 -/**  
241 - * 声音播放模式（音频路由）  
242 - *  
243 - * 微信和手机 QQ 里的视频通话功能，都有一个免提模式，开启后就不用把手机贴在耳朵上，这个功能就是基于音频路由实现的。  
244 - * 一般手机都有两个扬声器，设置音频路由的作用就是要决定声音从哪个扬声器播放出来：  
245 - * - Speakerphone：扬声器，位于手机底部，声音偏大，适合外放音乐。  
246 - * - Earpiece：听筒，位于手机顶部，声音偏小，适合通话。  
247 - */  
248 -typedef NS_ENUM(NSInteger, TXAudioRoute) {  
249 - TXAudioRouteSpeakerphone = 0, ///< 扬声器  
250 - TXAudioRouteEarpiece = 1, ///< 听筒  
251 -};  
252 -  
253 -  
254 -#elif TARGET_OS_MAC  
255 -/**  
256 - * 设备类型（仅 Mac）  
257 - *  
258 - * 在 Mac 上，每一种类型的设备都可能有多个，TRTC SDK 的 Mac 版本提供了一系列函数用来操作这些设备。  
259 - */  
260 -typedef NS_ENUM(NSInteger, TXMediaDeviceType) {  
261 - TXMediaDeviceTypeUnknown = -1, ///< 未定义  
262 - TXMediaDeviceTypeAudioInput = 0, ///< 麦克风  
263 - TXMediaDeviceTypeAudioOutput = 1, ///< 扬声器或听筒  
264 - TXMediaDeviceTypeVideoCamera = 2, ///< 摄像头  
265 -};  
266 -  
267 -/**  
268 - * 设备描述  
269 - *  
270 - * 在 Mac 上，每一种类型的设备都可能有多个，TRTC SDK 的 Mac 版本提供了一系列函数用来操作这些设备。  
271 - */  
272 -@interface TXMediaDeviceInfo : NSObject  
273 -/// 设备类型  
274 -@property (assign, nonatomic) TXMediaDeviceType type;  
275 -/// 设备ID  
276 -@property (copy, nonatomic, nullable) NSString *deviceId;  
277 -/// 设备名称  
278 -@property (copy, nonatomic, nullable) NSString *deviceName;  
279 -@end  
280 -  
281 -#endif  
282 -  
283 -NS_ASSUME_NONNULL_END 294 +/// @}
@@ -188,6 +188,7 @@ typedef enum TXLiteAVError @@ -188,6 +188,7 @@ typedef enum TXLiteAVError
188 ERR_ROOM_REQUEST_CLOSE_VIDEO_TIMEOUT = -3313, ///< 请求关闭视频超时 188 ERR_ROOM_REQUEST_CLOSE_VIDEO_TIMEOUT = -3313, ///< 请求关闭视频超时
189 ERR_ROOM_REQUEST_SET_RECEIVE_TIMEOUT = -3314, ///< 请求接收视频项超时 189 ERR_ROOM_REQUEST_SET_RECEIVE_TIMEOUT = -3314, ///< 请求接收视频项超时
190 ERR_ROOM_REQUEST_TOKEN_INVALID_PARAMETER = -3315, ///< 请求 token 无效参数，请检查 TRTCParams.userSig 是否填写正确 190 ERR_ROOM_REQUEST_TOKEN_INVALID_PARAMETER = -3315, ///< 请求 token 无效参数，请检查 TRTCParams.userSig 是否填写正确
  191 + ERR_ROOM_REQUEST_EXIT_ROOM_WHEN_ENTERING_ROOM = -3341, ///< 进房尚未成功时，收到了退房请求
191 192
192 ERR_ROOM_REQUEST_AES_TOKEN_RETURN_ERROR = -3329, ///< 请求 AES TOKEN 时，server 返回的内容是空的 193 ERR_ROOM_REQUEST_AES_TOKEN_RETURN_ERROR = -3329, ///< 请求 AES TOKEN 时，server 返回的内容是空的
193 ERR_ACCIP_LIST_EMPTY = -3331, ///< 请求接口机 IP 返回的列表为空的 194 ERR_ACCIP_LIST_EMPTY = -3331, ///< 请求接口机 IP 返回的列表为空的
@@ -406,6 +407,8 @@ typedef enum TXLiteAVEvent @@ -406,6 +407,8 @@ typedef enum TXLiteAVEvent
406 EVT_MIC_RELEASE_SUCC = 2029, ///< 释放麦克风占用 407 EVT_MIC_RELEASE_SUCC = 2029, ///< 释放麦克风占用
407 EVT_AUDIO_DEVICE_ROUTE_CHANGED = 2030, ///< 音频设备的route发生改变，即当前的输入输出设备发生改变，比如耳机被拔出 408 EVT_AUDIO_DEVICE_ROUTE_CHANGED = 2030, ///< 音频设备的route发生改变，即当前的输入输出设备发生改变，比如耳机被拔出
408 EVT_PLAY_GET_FLVSESSIONKEY = 2031, ///< TXLivePlayer 接收到http响应头中的 flvSessionKey 信息 409 EVT_PLAY_GET_FLVSESSIONKEY = 2031, ///< TXLivePlayer 接收到http响应头中的 flvSessionKey 信息
  410 + EVT_AUDIO_SESSION_INTERRUPT = 2032, ///< Audio Session Interrupt事件
  411 +
409 412
410 EVT_ROOM_ENTER = 1018, ///< 进入房间成功 413 EVT_ROOM_ENTER = 1018, ///< 进入房间成功
411 EVT_ROOM_EXIT = 1019, ///< 退出房间 414 EVT_ROOM_EXIT = 1019, ///< 退出房间
@@ -30,6 +30,12 @@ typedef NS_ENUM(NSInteger, TX_Enum_Type_LogLevel) { @@ -30,6 +30,12 @@ typedef NS_ENUM(NSInteger, TX_Enum_Type_LogLevel) {
30 */ 30 */
31 - (void)onLog:(NSString*)log LogLevel:(int)level WhichModule:(NSString*)module; 31 - (void)onLog:(NSString*)log LogLevel:(int)level WhichModule:(NSString*)module;
32 32
  33 +/**
  34 + * @brief NTP 校时回调，调用 TXLiveBase updateNetworkTime 后会触发
  35 + * @param errCode 0：表示校时成功且偏差在30ms以内，1：表示校时成功但偏差可能在 30ms 以上，-1：表示校时失败
  36 + */
  37 +- (void)onUpdateNetworkTime:(int)errCode message:(NSString *)errMsg;
  38 +
33 @end 39 @end
34 40
35 @interface TXLiveBase : NSObject 41 @interface TXLiveBase : NSObject
@@ -50,9 +56,9 @@ typedef NS_ENUM(NSInteger, TX_Enum_Type_LogLevel) { @@ -50,9 +56,9 @@ typedef NS_ENUM(NSInteger, TX_Enum_Type_LogLevel) {
50 */ 56 */
51 + (int)setGlobalEnv:(const char *)env_config; 57 + (int)setGlobalEnv:(const char *)env_config;
52 58
53 -/** 设置log输出级别 59 +/**
  60 + * 设置 log 输出级别
54 * @param level 参见 LOGLEVEL 61 * @param level 参见 LOGLEVEL
55 - *  
56 */ 62 */
57 + (void)setLogLevel:(TX_Enum_Type_LogLevel)level; 63 + (void)setLogLevel:(TX_Enum_Type_LogLevel)level;
58 64
@@ -66,25 +72,56 @@ typedef NS_ENUM(NSInteger, TX_Enum_Type_LogLevel) { @@ -66,25 +72,56 @@ typedef NS_ENUM(NSInteger, TX_Enum_Type_LogLevel) {
66 72
67 + (void)setAudioSessionDelegate:(id<TXLiveAudioSessionDelegate>)delegate; 73 + (void)setAudioSessionDelegate:(id<TXLiveAudioSessionDelegate>)delegate;
68 74
69 -/// 获取SDK版本信息 75 +/**
  76 + * @brief 获取 SDK 版本信息
  77 + * @return SDK 版本信息
  78 + */
70 + (NSString *)getSDKVersionStr; 79 + (NSString *)getSDKVersionStr;
71 80
72 -///　 获取pitu版本信息 81 +/**
  82 + * @brief 获取 pitu 版本信息
  83 + * @return pitu 版本信息
  84 + */
73 + (NSString *)getPituSDKVersion; 85 + (NSString *)getPituSDKVersion;
74 86
75 -/// 设置appID，云控使用 87 +/**
  88 + * @brief 设置 appID，云控使用
  89 + */
76 + (void)setAppID:(NSString*)appID; 90 + (void)setAppID:(NSString*)appID;
77 91
78 -/// 设置sdk的licence下载url和key 92 +/**
  93 + * @brief 设置 sdk 的 Licence 下载 url 和 key
  94 + */
79 + (void)setLicenceURL:(NSString *)url key:(NSString *)key; 95 + (void)setLicenceURL:(NSString *)url key:(NSString *)key;
80 96
81 -/// 设置userId，用于数据上报 97 +/**
  98 + * @brief 设置 userId，用于数据上报
  99 + */
82 + (void)setUserId:(NSString *)userId; 100 + (void)setUserId:(NSString *)userId;
83 101
84 -/// 获取 Licence 信息 102 +/**
  103 + * @brief 获取 Licence 信息
  104 + * @return Licence 信息
  105 + */
85 + (NSString *)getLicenceInfo; 106 + (NSString *)getLicenceInfo;
86 107
87 -/// 设置HEVC外部解码器工厂实例 108 +/**
  109 + * @brief 设置 HEVC 外部解码器工厂实例
  110 + */
88 + (void)setExternalDecoderFactory:(id)decoderFactory; 111 + (void)setExternalDecoderFactory:(id)decoderFactory;
89 112
  113 +/**
  114 + * 启动 NTP 校时服务
  115 + *
  116 + * @return 0：启动成功；< 0：启动失败
  117 + */
  118 ++ (NSInteger)updateNetworkTime;
  119 +
  120 +/**
  121 + * 获取 NTP 时间戳（毫秒），请在收到 onUpdateNetworkTime 回调后使用
  122 + *
  123 + * @return NTP 时间戳（毫秒），若返回 0：未启动 NTP 校时或校时失败，请重启校时
  124 + */
  125 ++ (NSInteger)getNetworkTimestamp;
  126 +
90 @end 127 @end
@@ -73,6 +73,8 @@ enum EventID @@ -73,6 +73,8 @@ enum EventID
73 PLAY_EVT_STREAM_SWITCH_SUCC = EVT_PLAY_LIVE_STREAM_SWITCH_SUCC, ///< 直播，切流成功（切流可以播放不同画面大小的视频） 73 PLAY_EVT_STREAM_SWITCH_SUCC = EVT_PLAY_LIVE_STREAM_SWITCH_SUCC, ///< 直播，切流成功（切流可以播放不同画面大小的视频）
74 PLAY_EVT_GET_METADATA = EVT_PLAY_GET_METADATA, ///< TXLivePlayer 接收到视频流中的 metadata 头信息（一条视频流仅触发一次） 74 PLAY_EVT_GET_METADATA = EVT_PLAY_GET_METADATA, ///< TXLivePlayer 接收到视频流中的 metadata 头信息（一条视频流仅触发一次）
75 PLAY_EVT_GET_FLVSESSIONKEY = EVT_PLAY_GET_FLVSESSIONKEY, ///< TXLivePlayer 接收到http响应头中的 flvSessionKey 信息 75 PLAY_EVT_GET_FLVSESSIONKEY = EVT_PLAY_GET_FLVSESSIONKEY, ///< TXLivePlayer 接收到http响应头中的 flvSessionKey 信息
  76 + PLAY_EVT_AUDIO_SESSION_INTERRUPT = EVT_AUDIO_SESSION_INTERRUPT, ///< Audio Session Interrupt事件
  77 +
76 78
77 PLAY_ERR_NET_DISCONNECT = ERR_PLAY_LIVE_STREAM_NET_DISCONNECT, ///< 直播，网络断连,且经多次重连抢救无效,可以放弃治疗,更多重试请自行重启播放 79 PLAY_ERR_NET_DISCONNECT = ERR_PLAY_LIVE_STREAM_NET_DISCONNECT, ///< 直播，网络断连,且经多次重连抢救无效,可以放弃治疗,更多重试请自行重启播放
78 80
  1 +/**
  2 + * Module: TRTC 音视频统计指标（只读）
  3 + * Function: TRTC SDK 会以两秒钟一次的频率向您汇报当前实时的音视频指标（帧率、码率、卡顿情况等）
  4 + */
  5 +/// @defgroup TRTCStatistic_cplusplus TRTCStatisic
  6 +/// Tencent Cloud TRTC ：audio, video and network related statistical indicators
  7 +/// @{
  8 +
  9 +#ifndef __TRTCSTATISTIC_H__
  10 +#define __TRTCSTATISTIC_H__
  11 +namespace trtc {
  12 +
  13 +/////////////////////////////////////////////////////////////////////////////////
  14 +//
  15 +// 本地的音视频统计指标
  16 +//
  17 +/////////////////////////////////////////////////////////////////////////////////
  18 +/// @name 本地的音视频统计指标
  19 +/// @{
  20 +
  21 +struct TRTCLocalStatistics {
  22 + ///【字段含义】本地视频的宽度，单位 px
  23 + uint32_t width;
  24 +
  25 + ///【字段含义】本地视频的高度，单位 px
  26 + uint32_t height;
  27 +
  28 + ///【字段含义】本地视频的帧率，即每秒钟会有多少视频帧，单位：FPS
  29 + uint32_t frameRate;
  30 +
  31 + ///【字段含义】远端视频的码率，即每秒钟新产生视频数据的多少，单位 Kbps
  32 + uint32_t videoBitrate;
  33 +
  34 + ///【字段含义】远端音频的采样率，单位 Hz
  35 + uint32_t audioSampleRate;
  36 +
  37 + ///【字段含义】本地音频的码率，即每秒钟新产生音频数据的多少，单位 Kbps
  38 + uint32_t audioBitrate;
  39 +
  40 + ///【字段含义】视频流类型（高清大画面|低清小画面|辅流画面）
  41 + TRTCVideoStreamType streamType;
  42 +
  43 + ///【字段含义】音频设备采集状态（用于检测音频外设的健康度）
  44 + /// 0：采集设备状态正常；1：检测到长时间静音；2：检测到破音；3：检测到声音异常间断。
  45 + uint32_t audioCaptureState;
  46 +
  47 + TRTCLocalStatistics() : width(0), height(0), frameRate(0), videoBitrate(0), audioSampleRate(0), audioBitrate(0), streamType(TRTCVideoStreamTypeBig), audioCaptureState(0) {
  48 + }
  49 +};
  50 +
  51 +/// @}
  52 +/////////////////////////////////////////////////////////////////////////////////
  53 +//
  54 +// 远端的音视频统计指标
  55 +//
  56 +/////////////////////////////////////////////////////////////////////////////////
  57 +/// @name 远端的音视频统计指标
  58 +/// @{
  59 +
  60 +struct TRTCRemoteStatistics {
  61 + ///【字段含义】用户 ID
  62 + const char* userId;
  63 +
  64 + ///【字段含义】该路音视频流的总丢包率（％）
  65 + /// finalLoss 代表该路音视频流历经“主播 => 云端 => 观众”这样一条完整的传输链路后，最终在观众端统计到的丢包率。
  66 + /// finalLoss 越小越好，丢包率为0即表示该路音视频流的所有数据均已经完整地到达了观众端。
  67 + ///如果出现了 downLoss == 0 但 finalLoss != 0 的情况，说明该路音视频流在“云端=>观众”这一段链路上没有出现丢包，但是在“主播=>云端”这一段链路上出现了不可恢复的丢包。
  68 + uint32_t finalLoss;
  69 +
  70 + ///【字段含义】远端视频的宽度，单位 px
  71 + uint32_t width;
  72 +
  73 + ///【字段含义】远端视频的高度，单位 px
  74 + uint32_t height;
  75 +
  76 + ///【字段含义】远端视频的帧率，单位：FPS
  77 + uint32_t frameRate;
  78 +
  79 + ///【字段含义】远端视频的码率，单位 Kbps
  80 + uint32_t videoBitrate;
  81 +
  82 + ///【字段含义】本地音频的采样率，单位 Hz
  83 + uint32_t audioSampleRate;
  84 +
  85 + ///【字段含义】本地音频的码率，单位 Kbps
  86 + uint32_t audioBitrate;
  87 +
  88 + ///【字段含义】播放延迟，单位 ms
  89 + ///为了避免网络抖动和网络包乱序导致的声音和画面卡顿，TRTC 会在播放端管理一个播放缓冲区，用于对接收到的网络数据包进行整理，
  90 + ///该缓冲区的大小会根据当前的网络质量进行自适应调整，该缓冲区的大小折算成以毫秒为单位的时间长度，也就是 jitterBufferDelay。
  91 + uint32_t jitterBufferDelay;
  92 +
  93 + ///【字段含义】端到端延迟，单位 ms
  94 + /// point2PointDelay 代表 “主播=>云端=>观众” 的延迟，更准确地说，它代表了“采集=>编码=>网络传输=>接收=>缓冲=>解码=>播放” 全链路的延迟。
  95 + /// point2PointDelay 需要本地和远端的 SDK 均为 8.5 及以上的版本才生效，若远端用户为 8.5 以前的版本，此数值会一直为0，代表无意义。
  96 + uint32_t point2PointDelay;
  97 +
  98 + ///【字段含义】音频播放的累计卡顿时长，单位 ms
  99 + uint32_t audioTotalBlockTime;
  100 +
  101 + ///【字段含义】音频播放卡顿率，单位 (%)
  102 + ///音频播放卡顿率（audioBlockRate） = 音频播放的累计卡顿时长（audioTotalBlockTime） / 音频播放的总时长
  103 + uint32_t audioBlockRate;
  104 +
  105 + ///【字段含义】视频播放的累计卡顿时长，单位 ms
  106 + uint32_t videoTotalBlockTime;
  107 +
  108 + ///【字段含义】视频播放卡顿率，单位 (%)
  109 + ///视频播放卡顿率（videoBlockRate） = 视频播放的累计卡顿时长（videoTotalBlockTime） / 视频播放的总时长
  110 + uint32_t videoBlockRate;
  111 +
  112 + ///【字段含义】视频流类型（高清大画面|低清小画面|辅流画面）
  113 + TRTCVideoStreamType streamType;
  114 +
  115 + TRTCRemoteStatistics()
  116 + : userId(nullptr),
  117 + finalLoss(0),
  118 + width(0),
  119 + height(0),
  120 + frameRate(0),
  121 + videoBitrate(0),
  122 + audioSampleRate(0),
  123 + audioBitrate(0),
  124 + jitterBufferDelay(0),
  125 + point2PointDelay(0),
  126 + audioTotalBlockTime(0),
  127 + audioBlockRate(0),
  128 + videoTotalBlockTime(0),
  129 + videoBlockRate(0),
  130 + streamType(TRTCVideoStreamTypeBig) {
  131 + }
  132 +};
  133 +
  134 +/// @}
  135 +/////////////////////////////////////////////////////////////////////////////////
  136 +//
  137 +// 网络和性能的汇总统计指标
  138 +//
  139 +/////////////////////////////////////////////////////////////////////////////////
  140 +/// @name 网络和性能的汇总统计指标
  141 +/// @{
  142 +
  143 +struct TRTCStatistics {
  144 + ///【字段含义】当前应用的 CPU 使用率，单位 (%)
  145 + uint32_t appCpu;
  146 +
  147 + ///【字段含义】当前系统的 CPU 使用率，单位 (%)
  148 + uint32_t systemCpu;
  149 +
  150 + ///【字段含义】从 SDK 到云端的上行丢包率，单位 (%)
  151 + ///该数值越小越好，如果 upLoss 为 0%，则意味着上行链路的网络质量很好，上传到云端的数据包基本不发生丢失。
  152 + ///如果 upLoss 为 30%，则意味着 SDK 向云端发送的音视频数据包中，会有 30% 丢失在传输链路中。
  153 + uint32_t upLoss;
  154 +
  155 + ///【字段含义】从云端到 SDK 的下行丢包率，单位 (%)
  156 + ///该数值越小越好，如果 downLoss 为 0%，则意味着下行链路的网络质量很好，从云端接收的数据包基本不发生丢失。
  157 + ///如果 downLoss 为 30%，则意味着云端向 SDK 传输的音视频数据包中，会有 30% 丢失在传输链路中。
  158 + uint32_t downLoss;
  159 +
  160 + ///【字段含义】从 SDK 到云端的往返延时，单位 ms
  161 + ///该数值代表从 SDK 发送一个网络包到云端，再从云端回送一个网络包到 SDK 的总计耗时，也就是一个网络包经历 “SDK=>云端=>SDK” 的总耗时。
  162 + ///该数值越小越好：如果 rtt < 50ms，意味着较低的音视频通话延迟；如果 rtt > 200ms，则意味着较高的音视频通话延迟。
  163 + ///需要特别解释的是，rtt 代表 “SDK=>云端=>SDK” 的总耗时，所不需要区分 upRtt 和 downRtt。
  164 + uint32_t rtt;
  165 +
  166 + ///【字段含义】从 SDK 到本地路由器的往返时延，单位 ms
  167 + ///该数值代表从 SDK 发送一个网络包到本地路由器网关，再从网关回送一个网络包到 SDK 的总计耗时，也就是一个网络包经历 “SDK=>网关=>SDK” 的总耗时。
  168 + ///该数值越小越好：如果 gatewayRtt < 50ms，意味着较低的音视频通话延迟；如果 gatewayRtt > 200ms，则意味着较高的音视频通话延迟。
  169 + ///当网络类型为蜂窝网时，该值无效。
  170 + uint32_t gatewayRtt;
  171 +
  172 + ///【字段含义】总发送字节数（包含信令数据和音视频数据），单位：字节数（Bytes）
  173 + uint32_t sentBytes;
  174 +
  175 + ///【字段含义】总接收字节数（包含信令数据和音视频数据），单位：字节数（Bytes）
  176 + uint32_t receivedBytes;
  177 +
  178 + ///【字段含义】本地的音视频统计信息
  179 + ///由于本地可能有三路音视频流（即高清大画面，低清小画面，以及辅流画面），因此本地的音视频统计信息是一个数组。
  180 + TRTCLocalStatistics* localStatisticsArray;
  181 +
  182 + ///【字段含义】数组 localStatisticsArray 的大小
  183 + uint32_t localStatisticsArraySize;
  184 +
  185 + ///【字段含义】远端的音视频统计信息
  186 + ///因为同时可能有多个远端用户，而且每个远端用户同时可能有多路音视频流（即高清大画面，低清小画面，以及辅流画面），因此远端的音视频统计信息是一个数组。
  187 + TRTCRemoteStatistics* remoteStatisticsArray;
  188 +
  189 + ///【字段含义】数组 remoteStatisticsArray 的大小
  190 + uint32_t remoteStatisticsArraySize;
  191 +
  192 + 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) {
  193 + }
  194 +};
  195 +/// @}
  196 +
  197 +} // namespace trtc
  198 +#ifdef _WIN32
  199 +using namespace trtc;
  200 +#endif
  201 +#endif / *__TRTCSTATISTIC_H__* /
  202 +/// @}
  1 +/**
  2 + * Module: TRTC 背景音乐、短音效和人声特效的管理类
  3 + * Function: 用于对背景音乐、短音效和人声特效进行设置的管理类
  4 + */
  5 +/// @defgroup TXAudioEffectManager_cplusplus TXAudioEffectManager
  6 +/// Tencent Cloud Audio Effect Management Module
  7 +/// @{
  8 +
1 #ifndef __ITXAUDIOEFFECTMANAGER_H__ 9 #ifndef __ITXAUDIOEFFECTMANAGER_H__
2 #define __ITXAUDIOEFFECTMANAGER_H__ 10 #define __ITXAUDIOEFFECTMANAGER_H__
3 11
4 namespace trtc { 12 namespace trtc {
5 13
6 -/// @defgroup ITXAudioEffectManager_cplusplus ITXAudioEffectManager  
7 -/// 腾讯云视频通话功能音乐和人声设置接口 14 +class ITXMusicPlayObserver;
  15 +class AudioMusicParam;
  16 +
  17 +/////////////////////////////////////////////////////////////////////////////////
  18 +//
  19 +// 音效相关的枚举值定义
  20 +//
  21 +/////////////////////////////////////////////////////////////////////////////////
  22 +/// @name 音效相关的枚举值定义
8 /// @{ 23 /// @{
9 -enum TXVoiceReverbType  
10 -{  
11 - TXLiveVoiceReverbType_0 = 0, ///< 关闭混响  
12 - TXLiveVoiceReverbType_1 = 1, ///< KTV  
13 - TXLiveVoiceReverbType_2 = 2, ///< 小房间  
14 - TXLiveVoiceReverbType_3 = 3, ///< 大会堂  
15 - TXLiveVoiceReverbType_4 = 4, ///< 低沉  
16 - TXLiveVoiceReverbType_5 = 5, ///< 洪亮  
17 - TXLiveVoiceReverbType_6 = 6, ///< 金属声  
18 - TXLiveVoiceReverbType_7 = 7, ///< 磁性 24 +
  25 +/**
  26 + * 1.1 混响特效
  27 + *
  28 + * 混响特效可以作用于人声之上，通过声学算法对声音进行叠加处理，模拟出各种不同环境下的临场感受，目前支持如下几种混响效果：
  29 + * 0：关闭；1：KTV；2：小房间；3：大会堂；4：低沉；5：洪亮；6：金属声；7：磁性。
  30 + */
  31 +enum TXVoiceReverbType {
  32 + TXLiveVoiceReverbType_0 = 0, ///< disable
  33 + TXLiveVoiceReverbType_1 = 1, ///< KTV
  34 + TXLiveVoiceReverbType_2 = 2, ///< small room
  35 + TXLiveVoiceReverbType_3 = 3, ///< great hall
  36 + TXLiveVoiceReverbType_4 = 4, ///< deep voice
  37 + TXLiveVoiceReverbType_5 = 5, ///< loud voice
  38 + TXLiveVoiceReverbType_6 = 6, ///< metallic sound
  39 + TXLiveVoiceReverbType_7 = 7, ///< magnetic sound
19 }; 40 };
20 41
  42 +/// @}
  43 +/////////////////////////////////////////////////////////////////////////////////
  44 +//
  45 +// 背景音乐的播放事件回调
  46 +//
  47 +/////////////////////////////////////////////////////////////////////////////////
  48 +/// @name 背景音乐的事件回调接口
  49 +/// @{
  50 +
  51 +// Playback progress block of background music
21 class ITXMusicPlayObserver { 52 class ITXMusicPlayObserver {
22 -public:  
23 - virtual ~ITXMusicPlayObserver() {} 53 + public:
  54 + virtual ~ITXMusicPlayObserver() {
  55 + }
24 56
25 - /// 背景音乐开始播放  
26 - virtual void onStart(int id,int errCode) = 0; 57 + ///背景音乐开始播放
  58 + virtual void onStart(int id, int errCode) = 0;
27 59
28 - /// 背景音乐的播放进度  
29 - virtual void onPlayProgress(int id,long curPtsMS,long durationMS) = 0; 60 + ///背景音乐的播放进度
  61 + virtual void onPlayProgress(int id, long curPtsMS, long durationMS) = 0;
30 62
31 - /// 背景音乐已播放完毕  
32 - virtual void onComplete(int id,int errCode) = 0; 63 + ///背景音乐已经播放完毕
  64 + virtual void onComplete(int id, int errCode) = 0;
33 }; 65 };
34 66
  67 +/// @}
  68 +/////////////////////////////////////////////////////////////////////////////////
  69 +//
  70 +// 背景音乐的播放控制信息
  71 +//
  72 +/////////////////////////////////////////////////////////////////////////////////
  73 +/// @name 背景音乐的播放控制信息
  74 +/// @{
  75 +
  76 +/**
  77 + * 背景音乐的播放控制信息
  78 + *
  79 + * 该信息用于在接口 {@link startPlayMusic} 中指定背景音乐的相关信息，包括播放 ID、文件路径和循环次数等：
  80 + * 1. 如果要多次播放同一首背景音乐，请不要每次播放都分配一个新的 ID，我们推荐使用相同的 ID。
  81 + * 2. 若您希望同时播放多首不同的音乐，请为不同的音乐分配不同的 ID 进行播放。
  82 + * 3. 如果使用同一个 ID 播放不同音乐，SDK 会先停止播放旧的音乐，再播放新的音乐。
  83 + */
35 class AudioMusicParam { 84 class AudioMusicParam {
36 -public:  
37 - /// 【字段含义】音乐 ID  
38 - /// 【特殊说明】SDK 允许播放多路音乐，因此需要音乐 ID 进行标记，用于控制音乐的开始、停止、音量等 85 + public:
  86 + ///【字段含义】音乐 ID <br/>
  87 + ///【特殊说明】SDK 允许播放多路音乐，因此需要使用 ID 进行标记，用于控制音乐的开始、停止、音量等。
39 int id; 88 int id;
40 89
41 - /// 【字段含义】音乐文件的绝对路径 90 + ///【字段含义】音效文件的完整路径或 URL 地址。支持的音频格式包括 MP3、AAC、M4A、WAV
42 char* path; 91 char* path;
43 92
44 - /// 【字段含义】音乐循环播放的次数  
45 - /// 【推荐取值】取值范围为0 - 任意正整数，默认值：0。0表示播放音乐一次；1表示播放音乐两次；以此类推 93 + ///【字段含义】音乐循环播放的次数 <br/>
  94 + ///【推荐取值】取值范围为0 - 任意正整数，默认值：0。0表示播放音乐一次；1表示播放音乐两次；以此类推
46 int loopCount; 95 int loopCount;
47 96
48 - /// 【字段含义】是否将音乐传到远端  
49 - /// 【推荐取值】YES：音乐在本地播放的同时，会上行至云端，因此远端用户也能听到该音乐；NO：音乐不会上行至云端，因此只能在本地听到该音乐。默认值：NO 97 + ///【字段含义】是否将音乐传到远端 <br/>
  98 + ///【推荐取值】YES：音乐在本地播放的同时，远端用户也能听到该音乐；NO：主播只能在本地听到该音乐，远端观众听不到。默认值：NO。
50 bool publish; 99 bool publish;
51 100
52 - /// 【字段含义】播放的是否为短音乐文件  
53 - /// 【推荐取值】YES：需要重复播放的短音乐文件；NO：正常的音乐文件。默认值：NO 101 + ///【字段含义】播放的是否为短音乐文件 <br/>
  102 + ///【推荐取值】YES：需要重复播放的短音乐文件；NO：正常的音乐文件。默认值：NO
54 bool isShortFile; 103 bool isShortFile;
55 104
56 - /// 【字段含义】音乐开始播放时间点，单位毫秒 105 + ///【字段含义】音乐开始播放时间点，单位：毫秒。
57 long startTimeMS; 106 long startTimeMS;
58 107
59 - /// 【字段含义】音乐结束播放时间点，单位毫秒，0表示播放至文件结尾。 108 + ///【字段含义】音乐结束播放时间点，单位毫秒，0表示播放至文件结尾。
60 long endTimeMS; 109 long endTimeMS;
61 110
62 AudioMusicParam(int id_, char* path_) { 111 AudioMusicParam(int id_, char* path_) {
@@ -69,50 +118,57 @@ public: @@ -69,50 +118,57 @@ public:
69 endTimeMS = 0; 118 endTimeMS = 0;
70 } 119 }
71 }; 120 };
  121 +/// @}
72 122
  123 +// Definition of audio effect management module
  124 +class ITXAudioEffectManager {
  125 + protected:
  126 + ITXAudioEffectManager() {
  127 + }
  128 + virtual ~ITXAudioEffectManager() {
  129 + }
73 130
74 -class ITXAudioEffectManager  
75 -{  
76 -protected:  
77 - ITXAudioEffectManager() {}  
78 - virtual ~ITXAudioEffectManager() {}  
79 -  
80 -public:  
81 -/////////////////////////////////////////////////////////////////////////////////  
82 -//  
83 -// （一）人声相关特效函数  
84 -//  
85 -/////////////////////////////////////////////////////////////////////////////////  
86 -/// @name 人声相关特效函数  
87 -/// @{ 131 + public:
  132 + /////////////////////////////////////////////////////////////////////////////////
  133 + //
  134 + // 人声相关的特效接口
  135 + //
  136 + /////////////////////////////////////////////////////////////////////////////////
  137 + /// @name 人声相关的特效接口
  138 + /// @{
88 139
89 /** 140 /**
90 - * 1.1 设置人声的混响效果（KTV、小房间、大会堂、低沉、洪亮...） 141 + * 1.3 设置人声的混响效果
91 * 142 *
92 - * @note 设置的效果在退房后会失效，如果下次进房还需要对应特效，需要调用此接口再次设置。 143 + * 通过该接口您可以设置人声的混响效果，具体特效请参考枚举定义{@link TXVoiceReverbType}。
  144 + *
  145 + * @note 设置的效果在退出房间后会自动失效，如果下次进房还需要对应特效，需要调用此接口再次进行设置。
93 */ 146 */
94 virtual void setVoiceReverbType(TXVoiceReverbType type) = 0; 147 virtual void setVoiceReverbType(TXVoiceReverbType type) = 0;
95 148
96 /** 149 /**
97 - * 1.2 设置麦克风采集人声的音量 150 + * 1.5 设置语音音量
98 * 151 *
99 - * @param volume 音量大小，100为原始音量，取值范围为0 - 150；默认值：100 152 + * 该接口可以设置语音音量的大小，一般配合音乐音量的设置接口 {@link setAllMusicVolume} 协同使用，用于调谐语音和音乐在混音前各自的音量占比。
100 * 153 *
101 - * @note 如果要将 volume 设置为大于100的数值，需要进行特殊配置，请联系技术支持。 154 + * @param volume 音量大小，取值范围为0 - 100，默认值：100。
  155 + * @note 如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。
102 */ 156 */
103 virtual void setVoiceCaptureVolume(int volume) = 0; 157 virtual void setVoiceCaptureVolume(int volume) = 0;
104 -/// @}  
105 158
106 -/////////////////////////////////////////////////////////////////////////////////  
107 -//  
108 -// （二）背景音乐特效函数  
109 -//  
110 -///////////////////////////////////////////////////////////////////////////////// 159 + /// @}
  160 + /////////////////////////////////////////////////////////////////////////////////
  161 + //
  162 + // 背景音乐的相关接口
  163 + //
  164 + /////////////////////////////////////////////////////////////////////////////////
  165 + /// @name 背景音乐的相关接口
  166 + /// @{
111 167
112 -/// @name 背景音乐特效函数  
113 -/// @{  
114 /** 168 /**
115 - * 2.1 设置背景音乐的播放进度回调接口 169 + * 2.0 设置背景音乐的事件回调接口
  170 + *
  171 + * 请在播放背景音乐之前使用该接口设置播放事件回调，以便感知背景音乐的播放进度。
116 * 172 *
117 * @param musicId 音乐 ID 173 * @param musicId 音乐 ID
118 * @param observer 具体参考 ITXMusicPlayObserver 中定义接口 174 * @param observer 具体参考 ITXMusicPlayObserver 中定义接口
@@ -120,115 +176,127 @@ public: @@ -120,115 +176,127 @@ public:
120 virtual void setMusicObserver(int musicId, ITXMusicPlayObserver* observer) = 0; 176 virtual void setMusicObserver(int musicId, ITXMusicPlayObserver* observer) = 0;
121 177
122 /** 178 /**
123 - * 2.2 开始播放背景音乐 179 + * 2.1 开始播放背景音乐
124 * 180 *
125 * 每个音乐都需要您指定具体的 ID，您可以通过该 ID 对音乐的开始、停止、音量等进行设置。 181 * 每个音乐都需要您指定具体的 ID，您可以通过该 ID 对音乐的开始、停止、音量等进行设置。
126 * 182 *
127 - * @note 若您想同时播放多个音乐，请分配不同的 ID 进行播放。  
128 - * 如果使用同一个 ID 播放不同音乐，SDK 会先停止播放旧的音乐，再播放新的音乐。 183 + * @note
  184 + * 1. 如果要多次播放同一首背景音乐，请不要每次播放都分配一个新的 ID，我们推荐使用相同的 ID。
  185 + * 2. 若您希望同时播放多首不同的音乐，请为不同的音乐分配不同的 ID 进行播放。
  186 + * 3. 如果使用同一个 ID 播放不同音乐，SDK 会先停止播放旧的音乐，再播放新的音乐。
  187 + *
129 * @param musicParam 音乐参数 188 * @param musicParam 音乐参数
  189 + * @param startBlock 播放开始回调
  190 + * @param progressBlock 播放进度回调
  191 + * @param completeBlock 播放结束回调
130 */ 192 */
131 virtual void startPlayMusic(AudioMusicParam musicParam) = 0; 193 virtual void startPlayMusic(AudioMusicParam musicParam) = 0;
132 194
133 /** 195 /**
134 - * 2.3 停止播放背景音乐 196 + * 2.2 停止播放背景音乐
135 * 197 *
136 * @param id 音乐 ID 198 * @param id 音乐 ID
137 */ 199 */
138 virtual void stopPlayMusic(int id) = 0; 200 virtual void stopPlayMusic(int id) = 0;
139 201
140 /** 202 /**
141 - * 2.4 暂停播放背景音乐 203 + * 2.3 暂停播放背景音乐
142 * 204 *
143 * @param id 音乐 ID 205 * @param id 音乐 ID
144 */ 206 */
145 virtual void pausePlayMusic(int id) = 0; 207 virtual void pausePlayMusic(int id) = 0;
146 208
147 /** 209 /**
148 - * 2.5 恢复播放背景音乐 210 + * 2.4 恢复播放背景音乐
149 * 211 *
150 * @param id 音乐 ID 212 * @param id 音乐 ID
151 */ 213 */
152 virtual void resumePlayMusic(int id) = 0; 214 virtual void resumePlayMusic(int id) = 0;
153 215
154 /** 216 /**
155 - * 2.6 设置背景音乐的远端音量大小，即主播可以通过此接口设置远端观众能听到的背景音乐的音量大小。 217 + * 2.5 设置所有背景音乐的本地音量和远端音量的大小
156 * 218 *
157 - * @param id 音乐 ID  
158 - * @param volume 音量大小，100为原始音量，取值范围为0 - 150；默认值：100 219 + * 该接口可以设置所有背景音乐的本地音量和远端音量。
  220 + * - 本地音量：即主播本地可以听到的背景音乐的音量大小。
  221 + * - 远端音量：即观众端可以听到的背景音乐的音量大小。
159 * 222 *
160 - * @note 如果要将 volume 设置为大于100的数值，需要进行特殊配置，请联系技术支持。 223 + * @param volume 音量大小，取值范围为0 - 100，默认值：100。
  224 + * @note 如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。
161 */ 225 */
162 - virtual void setMusicPublishVolume(int id, int volume) = 0; 226 + virtual void setAllMusicVolume(int volume) = 0;
163 227
164 /** 228 /**
165 - * 2.7 设置背景音乐的本地音量大小，即主播可以通过此接口设置主播自己本地的背景音乐的音量大小。 229 + * 2.6 设置某一首背景音乐的远端音量的大小
166 * 230 *
167 - * @param id 音乐 ID  
168 - * @param volume 音量大小，100为原始音量，取值范围为0 - 150；默认值：100 231 + * 该接口可以细粒度地控制每一首背景音乐的远端音量，也就是观众端可听到的背景音乐的音量大小。
169 * 232 *
170 - * @note 如果要将 volume 设置为大于100的数值，需要进行特殊配置，请联系技术支持。 233 + * @param id 音乐 ID
  234 + * @param volume 音量大小，取值范围为0 - 100；默认值：100
  235 + * @note 如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。
171 */ 236 */
172 - virtual void setMusicPlayoutVolume(int id, int volume) = 0; 237 + virtual void setMusicPublishVolume(int id, int volume) = 0;
173 238
174 /** 239 /**
175 - * 2.8 设置全局背景音乐的本地和远端音量的大小 240 + * 2.7 设置某一首背景音乐的本地音量的大小
176 * 241 *
177 - * @param volume 音量大小，100为原始音量，取值范围为0 - 150；默认值：100 242 + * 该接口可以细粒度地控制每一首背景音乐的本地音量，也就是主播本地可以听到的背景音乐的音量大小。
178 * 243 *
179 - * @note 如果要将 volume 设置为大于100的数值，需要进行特殊配置，请联系技术支持。 244 + * @param id 音乐 ID
  245 + * @param volume 音量大小，取值范围为0 - 100，默认值：100。
  246 + * @note 如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。
180 */ 247 */
181 - virtual void setAllMusicVolume(int volume) = 0; 248 + virtual void setMusicPlayoutVolume(int id, int volume) = 0;
182 249
183 /** 250 /**
184 - * 2.9 调整背景音乐的音调高低 251 + * 2.8 调整背景音乐的音调高低
185 * 252 *
186 - * @param id 音乐 ID 253 + * @param id 音乐 ID
187 * @param pitch 音调，默认值是0.0f，范围是：[-1 ~ 1] 之间的浮点数； 254 * @param pitch 音调，默认值是0.0f，范围是：[-1 ~ 1] 之间的浮点数；
188 */ 255 */
189 virtual void setMusicPitch(int id, float pitch) = 0; 256 virtual void setMusicPitch(int id, float pitch) = 0;
190 257
191 /** 258 /**
192 - * 2.10 调整背景音乐的变速效果 259 + * 2.9 调整背景音乐的变速效果
193 * 260 *
194 - * @param id 音乐 ID 261 + * @param id 音乐 ID
195 * @param speedRate 速度，默认值是1.0f，范围是：[0.5 ~ 2] 之间的浮点数； 262 * @param speedRate 速度，默认值是1.0f，范围是：[0.5 ~ 2] 之间的浮点数；
196 */ 263 */
197 virtual void setMusicSpeedRate(int id, float speedRate) = 0; 264 virtual void setMusicSpeedRate(int id, float speedRate) = 0;
198 265
199 /** 266 /**
200 - * 2.11 获取背景音乐当前的播放进度（单位：毫秒） 267 + * 2.10 获取背景音乐的播放进度（单位：毫秒）
201 * 268 *
202 - * @param id 音乐 ID 269 + * @param id 音乐 ID
203 * @return 成功返回当前播放时间，单位：毫秒，失败返回-1 270 * @return 成功返回当前播放时间，单位：毫秒，失败返回-1
204 */ 271 */
205 virtual long getMusicCurrentPosInMS(int id) = 0; 272 virtual long getMusicCurrentPosInMS(int id) = 0;
206 273
207 /** 274 /**
208 - * 2.12 设置背景音乐的播放进度（单位：毫秒）  
209 - *  
210 - * @note 请尽量避免频繁地调用该接口，因为该接口可能会再次读写音乐文件，耗时稍高。  
211 - * 当配合进度条使用时，请在进度条拖动完毕的回调中调用，而避免在拖动过程中实时调用。 275 + * 2.11 获取景音乐的总时长（单位：毫秒）
212 * 276 *
213 - * @param id 音乐 ID  
214 - * @param pts 单位: 毫秒 277 + * @param path 音乐文件路径，如果 path 为空，那么返回当前正在播放的 music 时长。
  278 + * @return 成功返回时长，失败返回-1
215 */ 279 */
216 - virtual void seekMusicToPosInTime(int id, int pts) = 0; 280 + virtual long getMusicDurationInMS(char* path) = 0;
217 281
218 /** 282 /**
219 - * 2.13 获取景音乐文件的总时长（单位：毫秒） 283 + * 2.12 设置背景音乐的播放进度（单位：毫秒）
220 * 284 *
221 - * @param path 音乐文件路径，如果 path 为空，那么返回当前正在播放的 music 时长。  
222 - * @return 成功返回时长，失败返回-1 285 + * @note 请尽量避免过度频繁地调用该接口，因为该接口可能会再次读写音乐文件，耗时稍高。
  286 + * 因此，当用户拖拽音乐的播放进度条时，请在用户完成拖拽操作后再调用本接口。
  287 + * 因为 UI 上的进度条控件往往会以很高的频率反馈用户的拖拽进度，如不做频率限制，会导致较差的用户体验。
  288 + *
  289 + * @param id 音乐 ID
  290 + * @param pts 单位: 毫秒
223 */ 291 */
224 - virtual long getMusicDurationInMS(char* path) = 0; 292 + virtual void seekMusicToPosInTime(int id, int pts) = 0;
225 293
  294 + /// @}
226 }; 295 };
227 -/// @}  
228 -}  
229 - 296 +} // End of namespace trtc
230 #ifdef _WIN32 297 #ifdef _WIN32
231 using namespace trtc; 298 using namespace trtc;
232 #endif 299 #endif
233 -  
234 #endif /* __ITXAUDIOEFFECTMANAGER_H__ */ 300 #endif /* __ITXAUDIOEFFECTMANAGER_H__ */
  301 +
  302 +/// @}
  1 +/**
  2 + * Module: TRTC 音视频设备管理模块
  3 + * Function: 用于管理摄像头、麦克风和扬声器等音视频相关的硬件设备
  4 + */
  5 +/// @defgroup TXDeviceManager_cplusplus TXDeviceManager
  6 +/// Tencent Cloud Device Management Module
  7 +/// @{
  8 +
1 #ifndef __ITXDEVICEMANAGER_H__ 9 #ifndef __ITXDEVICEMANAGER_H__
2 #define __ITXDEVICEMANAGER_H__ 10 #define __ITXDEVICEMANAGER_H__
3 11
@@ -10,69 +18,95 @@ namespace trtc { @@ -10,69 +18,95 @@ namespace trtc {
10 18
11 class ITRTCVideoRenderCallback; 19 class ITRTCVideoRenderCallback;
12 20
13 -/// @defgroup ITXDeviceManager_cplusplus ITXDeviceManager  
14 -/// 腾讯云视频通话功能的设备管理接口类 21 +/////////////////////////////////////////////////////////////////////////////////
  22 +//
  23 +// 音视频设备相关的类型定义
  24 +//
  25 +/////////////////////////////////////////////////////////////////////////////////
  26 +/// @name 音视频设备相关的类型定义
15 /// @{ 27 /// @{
  28 +
16 /** 29 /**
17 - * 系统音量类型（仅适用于移动端设备）  
18 - *  
19 - * 智能手机一般具备两种系统音量类型，即通话音量类型和媒体音量类型。  
20 - * - 通话音量：手机专门为通话场景设计的音量类型，使用手机自带的回声抵消功能，音质相比媒体音量类型较差，  
21 - * 无法通过音量按键将音量调成零，但是支持蓝牙耳机上的麦克风。 30 + * 系统音量类型（仅适用于移动设备）
22 * 31 *
23 - * - 媒体音量：手机专门为音乐场景设计的音量类型，音质相比于通话音量类型要好，通过通过音量按键可以将音量调成零。  
24 - * 使用媒体音量类型时，如果要开启回声抵消（AEC）功能，SDK 会开启内置的声学处理算法对声音进行二次处理。  
25 - * 在媒体音量模式下，蓝牙耳机无法使用自带的麦克风采集声音，只能使用手机上的麦克风进行声音采集。  
26 - *  
27 - * SDK 目前提供了三种系统音量类型的控制模式，分别为：  
28 - * - Auto：“麦上通话，麦下媒体”，即主播上麦时使用通话音量，观众不上麦则使用媒体音量，适合在线直播场景。  
29 - * 如果您在 enterRoom 时选择的场景为 TRTCAppSceneLIVE 或 TRTCAppSceneVoiceChatRoom，SDK 会自动选择该模式。  
30 - *  
31 - * - VOIP：全程使用通话音量，适合多人会议场景。  
32 - * 如果您在 enterRoom 时选择的场景为 TRTCAppSceneVideoCall 或 TRTCAppSceneAudioCall，SDK 会自动选择该模式。  
33 - *  
34 - * - Media：通话全程使用媒体音量，不常用，适合个别有特殊需求（如主播外接声卡）的应用场景。 32 + * 现代智能手机中一般都具备两套系统音量类型，即“通话音量”和“媒体音量”。
  33 + * - 通话音量：手机专门为接打电话所设计的音量类型，自带回声抵消（AEC）功能，并且支持通过蓝牙耳机上的麦克风进行拾音，缺点是音质比较一般。
  34 + * 当您通过手机侧面的音量按键下调手机音量时，如果无法将其调至零（也就是无法彻底静音），说明您的手机当前出于通话音量。
  35 + * - 媒体音量：手机专门为音乐场景所设计的音量类型，无法使用系统的 AEC 功能，并且不支持通过蓝牙耳机的麦克风进行拾音，但具备更好的音乐播放效果。
  36 + * 当您通过手机侧面的音量按键下调手机音量时，如果能够将手机音量调至彻底静音，说明您的手机当前出于媒体音量。
35 * 37 *
  38 + * SDK 目前提供了三种系统音量类型的控制模式：自动切换模式、全程通话音量模式、全程媒体音量模式。
36 */ 39 */
37 -enum TXSystemVolumeType  
38 -{  
39 - /// “麦上通话，麦下媒体”，即主播上麦时使用通话音量，观众不上麦则使用媒体音量，适合在线直播场景。<br>  
40 - /// 如果您在 enterRoom 时选择的场景为 TRTCAppSceneLIVE 或 TRTCAppSceneVoiceChatRoom，SDK 会自动选择该模式。  
41 - TXSystemVolumeTypeAuto = 0,  
42 -  
43 - /// 通话全程使用媒体音量，不常用，适合个别有特殊需求（如主播外接声卡）的应用场景。  
44 - TXSystemVolumeTypeMedia = 1,  
45 -  
46 - /// 全程使用通话音量，适合多人会议场景。<br>  
47 - /// 如果您在 enterRoom 时选择的场景为 TRTCAppSceneVideoCall 或 TRTCAppSceneAudioCall 会自动选择该模式。  
48 - TXSystemVolumeTypeVOIP = 2, 40 +enum TXSystemVolumeType {
  41 +
  42 + ///自动切换模式：
  43 + ///也被称为“麦上通话，麦下媒体”，即主播上麦时使用通话音量，观众不上麦则使用媒体音量，适合在线直播场景。
  44 + TXSystemVolumeTypeAuto = 0,
  45 +
  46 + ///全程媒体音量：
  47 + ///通话全程使用媒体音量，并不是非常常用的音量类型，适用于对音质要求比较苛刻的音乐场景中。
  48 + ///如果您的用户大都使用外接设备（比如外接声卡）为主，可以使用该模式，否则请慎用。
  49 + TXSystemVolumeTypeMedia = 1,
  50 +
  51 + ///全程通话音量：
  52 + ///该方案的优势在于用户在上下麦时音频模块无需切换工作模式，可以做到无缝上下麦，适合于用户需要频繁上下麦的应用场景。
  53 + TXSystemVolumeTypeVOIP = 2,
  54 +
49 }; 55 };
50 56
51 /** 57 /**
52 - * 声音播放路由（仅适用于移动端设备） 58 + * 音频路由（即声音的播放模式）
53 * 59 *
54 - * 一般手机都有两个扬声器，设置音频路由的作用就是要决定声音从哪个扬声器播放出来：  
55 - * - Speakerphone：扬声器，位于手机底部，声音偏大，适合外放音乐。  
56 - * - Earpiece：听筒，位于手机顶部，声音偏小，适合通话。 60 + * 音频路由，即声音是从手机的扬声器还是从听筒中播放出来，因此该接口仅适用于手机等移动端设备。
  61 + * 手机有两个扬声器：一个是位于手机顶部的听筒，一个是位于手机底部的立体声扬声器。
  62 + * - 设置音频路由为听筒时，声音比较小，只有将耳朵凑近才能听清楚，隐私性较好，适合用于接听电话。
  63 + * - 设置音频路由为扬声器时，声音比较大，不用将手机贴脸也能听清，因此可以实现“免提”的功能。
57 */ 64 */
58 enum TXAudioRoute { 65 enum TXAudioRoute {
59 - TXAudioRouteSpeakerphone = 0, ///< 扬声器  
60 - TXAudioRouteEarpiece = 1, ///< 听筒 66 +
  67 + /// Speakerphone：使用扬声器播放（即“免提”），扬声器位于手机底部，声音偏大，适合外放音乐。
  68 + TXAudioRouteSpeakerphone = 0,
  69 +
  70 + /// Earpiece：使用听筒播放，听筒位于手机顶部，声音偏小，适合需要保护隐私的通话场景。
  71 + TXAudioRouteEarpiece = 1,
  72 +
61 }; 73 };
62 74
63 /** 75 /**
64 - * 设备类型 76 + * 设备类型（仅适用于桌面平台）
  77 + *
  78 + * 该枚举值用于定义三种类型的音视频设备，即摄像头、麦克风和扬声器，以便让一套设备管理接口可以操控三种不同类型的设备。
65 */ 79 */
66 -enum TXMediaDeviceType  
67 -{  
68 - TXMediaDeviceTypeUnknown = -1, ///< 未知类型  
69 - TXMediaDeviceTypeMic = 0, ///< 麦克风  
70 - TXMediaDeviceTypeSpeaker = 1, ///< 扬声器或听筒  
71 - TXMediaDeviceTypeCamera = 2, ///< 摄像头 80 +enum TXMediaDeviceType {
  81 + TXMediaDeviceTypeUnknown = -1, ///< undefined device type
  82 + TXMediaDeviceTypeMic = 0, ///< microphone
  83 + TXMediaDeviceTypeSpeaker = 1, ///< speaker or earpiece
  84 + TXMediaDeviceTypeCamera = 2, ///< camera
72 }; 85 };
73 86
74 /** 87 /**
75 - * 设备列表 88 + * 音视频设备的相关信息（仅适用于桌面平台）
  89 + *
  90 + * 该结构体用于描述一个音视频设备的关键信息，比如设备ID、设备名称等等，以便用户能够在用户界面上选择自己期望使用的音视频设备。
  91 + */
  92 +class ITXDeviceInfo {
  93 + protected:
  94 + virtual ~ITXDeviceInfo() {
  95 + }
  96 +
  97 + public:
  98 + /// device name (UTF-8)
  99 + virtual const char* getDeviceName() = 0;
  100 + /// device PID (UTF-8)
  101 + virtual const char* getDevicePID() = 0;
  102 + /// release function, don't use delete!!!
  103 + virtual void release() = 0;
  104 +};
  105 +
  106 +/**
  107 + * 设备信息列表（仅适用于桌面平台）
  108 + *
  109 + * 此结构体的作用相当于 std::vector<ITXDeviceInfo>，用于解决不同版本的 STL 容器的二进制兼容问题。
76 */ 110 */
77 class ITXDeviceCollection { 111 class ITXDeviceCollection {
78 protected: 112 protected:
@@ -80,323 +114,251 @@ class ITXDeviceCollection { @@ -80,323 +114,251 @@ class ITXDeviceCollection {
80 } 114 }
81 115
82 public: 116 public:
83 - /**  
84 - * @return 设备个数  
85 - */ 117 + /// Size of this list.
86 virtual uint32_t getCount() = 0; 118 virtual uint32_t getCount() = 0;
87 -  
88 - /**  
89 - * @return 设备名称，字符编码格式是UTF-8  
90 - */ 119 + /// device name (UTF-8)
91 virtual const char* getDeviceName(uint32_t index) = 0; 120 virtual const char* getDeviceName(uint32_t index) = 0;
92 -  
93 - /**  
94 - * @return 设备PID，字符编码格式是UTF-8  
95 - */ 121 + /// device PID (UTF-8)
96 virtual const char* getDevicePID(uint32_t index) = 0; 122 virtual const char* getDevicePID(uint32_t index) = 0;
97 -  
98 - /**  
99 - * @brief 遍历完设备后，调用release释放资源。  
100 - */ 123 + /// release function, don't use delete!!!
101 virtual void release() = 0; 124 virtual void release() = 0;
102 }; 125 };
  126 +/// @}
103 127
104 -/**  
105 - * 设备 Item 信息  
106 - */  
107 -class ITXDeviceInfo { 128 +class ITXDeviceManager {
108 protected: 129 protected:
109 - virtual ~ITXDeviceInfo() { 130 + ITXDeviceManager() {
  131 + }
  132 + virtual ~ITXDeviceManager() {
110 } 133 }
111 134
112 public: 135 public:
  136 +/////////////////////////////////////////////////////////////////////////////////
  137 +//
  138 +// 移动端设备操作接口（iOS Android）
  139 +//
  140 +/////////////////////////////////////////////////////////////////////////////////
  141 +/// @name 移动端设备操作接口
  142 +/// @{
  143 +
  144 +/**
  145 + * 1.1 判断当前是否为前置摄像头（仅适用于移动端）
  146 + */
  147 +#if __ANDROID__ || (__APPLE__ && TARGET_OS_IOS)
  148 + virtual bool isFrontCamera() = 0;
  149 +
113 /** 150 /**
114 - * @return 设备名称，字符编码格式是UTF-8 151 + * 1.2 切换前置或后置摄像头（仅适用于移动端）
115 */ 152 */
116 - virtual const char* getDeviceName() = 0; 153 + virtual int switchCamera(bool frontCamera) = 0;
117 154
118 /** 155 /**
119 - * @return 设备PID，字符编码格式是UTF-8 156 + * 1.3 获取摄像头的最大缩放倍数（仅适用于移动端）
120 */ 157 */
121 - virtual const char* getDevicePID() = 0; 158 + virtual float getCameraZoomMaxRatio() = 0;
  159 +
  160 + /**
  161 + * 1.4 设置摄像头的缩放倍数（仅适用于移动端）
  162 + *
  163 + * @param zoomRatio 取值范围1 - 5，取值为1表示最远视角（正常镜头），取值为5表示最近视角（放大镜头）。
  164 + */
  165 + virtual int setCameraZoomRatio(float zoomRatio) = 0;
122 166
123 /** 167 /**
124 - * @brief 获取完设备信息后，调用release释放资源。 168 + * 1.5 查询是否支持自动识别人脸位置（仅适用于移动端）
125 */ 169 */
126 - virtual void release() = 0;  
127 -}; 170 + virtual bool isAutoFocusEnabled() = 0;
128 171
129 -class ITXDeviceManager {  
130 -protected:  
131 - ITXDeviceManager() {}  
132 - virtual ~ITXDeviceManager() {} 172 + /**
  173 + * 1.6 开启自动对焦功能（仅适用于移动端）
  174 + *
  175 + * 开启后，SDK 会自动检测画面中的人脸位置，并将摄像头的焦点始终对焦在人脸位置上。
  176 + */
  177 + virtual int enableCameraAutoFocus(bool enabled) = 0;
133 178
134 -public:  
135 -  
136 -#if (__APPLE__ && TARGET_OS_MAC && !TARGET_OS_IPHONE) || _WIN32  
137 /** 179 /**
138 - * 获取设备列表 180 + * 1.7 设置摄像头的对焦位置（仅适用于移动端）
139 * 181 *
140 - * @param type 设备类型，指定需要获取哪种设备的列表。详见 TXMediaDeviceType 定义。 182 + * 您可以通过该接口实现如下交互：
  183 + * 1. 在本地摄像头的预览画面上，允许用户单击操作。
  184 + * 2. 在用户的单击位置显示一个矩形方框，以示摄像头会在此处对焦。
  185 + * 3. 随后将用户点击位置的坐标通过本接口传递给 SDK，之后 SDK 会操控摄像头按照用户期望的位置进行对焦。
  186 + * @note 使用该接口的前提是先通过 {@link enableCameraAutoFocus} 关闭自动对焦功能。
  187 + * @param position 对焦位置，请传入期望对焦点的坐标值
  188 + * @return 0：操作成功；负数：操作失败。
  189 + */
  190 + virtual int setCameraFocusPosition(float x, float y) = 0;
  191 +
  192 + /**
  193 + * 1.8 开启/关闭闪光灯，也就是手电筒模式（仅适用于移动端）
  194 + */
  195 + virtual int enableCameraTorch(bool enabled) = 0;
  196 +
  197 + /**
  198 + * 1.9 设置音频路由（仅适用于移动端）
141 * 199 *
142 - * @note - delete ITXDeviceCollection* 指针会导致编译错误，SDK 维护 ITXDeviceCollection 对象的生命周期  
143 - * - 使用完毕后请调用 release 方法释放资源  
144 - * - type 只支持 TXMediaDeviceTypeMic、TXMediaDeviceTypeSpeaker、TXMediaDeviceTypeCamera  
145 - * - 此接口只支持 Mac 和 Windows 平台 200 + * 手机有两个音频播放设备：一个是位于手机顶部的听筒，一个是位于手机底部的立体声扬声器。
  201 + * 设置音频路由为听筒时，声音比较小，只有将耳朵凑近才能听清楚，隐私性较好，适合用于接听电话。
  202 + * 设置音频路由为扬声器时，声音比较大，不用将手机贴脸也能听清，因此可以实现“免提”的功能。
  203 + */
  204 + virtual int setAudioRoute(TXAudioRoute route) = 0;
  205 +
  206 + /**
  207 + * 1.10 设置系统音量类型（仅适用于移动端）
146 */ 208 */
  209 + virtual int setSystemVolumeType(TXSystemVolumeType type) = 0;
  210 +#endif
  211 +
  212 +/// @}
  213 +/////////////////////////////////////////////////////////////////////////////////
  214 +//
  215 +// 桌面端设备操作接口（Windows Mac）
  216 +//
  217 +/////////////////////////////////////////////////////////////////////////////////
  218 +/// @name 桌面端设备操作接口
  219 +/// @{
  220 +
  221 +/**
  222 + * 2.1 获取设备列表（仅适用于桌面端）
  223 + *
  224 + * @param type 设备类型，指定需要获取哪种设备的列表。详见 TXMediaDeviceType 定义。
  225 + * @note
  226 + * - 使用完毕后请调用 release 方法释放资源，这样可以让 SDK 维护 ITXDeviceCollection 对象的生命周期。
  227 + * - 不要使用 delete 释放返回的 Collection 对象，delete ITXDeviceCollection* 指针会导致异常崩溃。
  228 + * - type 只支持 TXMediaDeviceTypeMic、TXMediaDeviceTypeSpeaker、TXMediaDeviceTypeCamera。
  229 + * - 此接口只支持 Mac 和 Windows 平台
  230 + */
  231 +#if (__APPLE__ && TARGET_OS_MAC && !TARGET_OS_IPHONE) || _WIN32
147 virtual ITXDeviceCollection* getDevicesList(TXMediaDeviceType type) = 0; 232 virtual ITXDeviceCollection* getDevicesList(TXMediaDeviceType type) = 0;
148 233
149 /** 234 /**
150 - * 指定当前设备 235 + * 2.2 设置当前要使用的设备（仅适用于桌面端）
151 * 236 *
152 - * @param type 设备类型，根据设备类型指定当前设备。详见 TXMediaDeviceType 定义。  
153 - * @param deviceId 从 getDevicesList 中得到的设备 ID  
154 - * @return 0：操作成功 负数：失败  
155 - * @note - type 只支持 TXMediaDeviceTypeMic、TXMediaDeviceTypeSpeaker、TXMediaDeviceTypeCamera  
156 - * - 此接口只支持 Mac 和 Windows 平台 237 + * @param type 设备类型，详见 TXMediaDeviceType 定义。
  238 + * @param deviceId 设备ID，您可以通过接口 {@link getDevicesList} 获得设备 ID。
  239 + * @return 0：操作成功；负数：操作失败。
157 */ 240 */
158 virtual int setCurrentDevice(TXMediaDeviceType type, const char* deviceId) = 0; 241 virtual int setCurrentDevice(TXMediaDeviceType type, const char* deviceId) = 0;
159 242
160 /** 243 /**
161 - * 获取当前使用的设备  
162 - *  
163 - * @param type 设备类型，根据设备类型获取当前设备信息。详见 TXMediaDeviceType 定义。  
164 - * @return ITRTCDeviceInfo 设备信息，能获取设备 ID 和设备名称  
165 - * @note 此接口只支持 Mac 和 Windows 平台 244 + * 2.3 获取当前正在使用的设备（仅适用于桌面端）
166 */ 245 */
167 virtual ITXDeviceInfo* getCurrentDevice(TXMediaDeviceType type) = 0; 246 virtual ITXDeviceInfo* getCurrentDevice(TXMediaDeviceType type) = 0;
168 247
169 /** 248 /**
170 - * 设置当前设备的音量 249 + * 2.4 设置当前设备的音量（仅适用于桌面端）
  250 + *
  251 + * 这里的音量指的是麦克风的采集音量或者扬声器的播放音量，摄像头是不支持设置音量的。
171 * 252 *
172 - * @param type 设备类型，根据设备类型获取当前设备音量。详见 TXMediaDeviceType 定义。  
173 - * @param volume 音量大小  
174 - * @return 0：操作成功 负数：失败  
175 - * @note - type 只支持 TXMediaDeviceTypeMic、TXMediaDeviceTypeSpeaker  
176 - * - 此接口只支持 Mac 和 Windows 平台 253 + * @param volume 音量大小，取值范围为0 - 100，默认值：100。
  254 + * @note 如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。
177 */ 255 */
178 virtual int setCurrentDeviceVolume(TXMediaDeviceType type, uint32_t volume) = 0; 256 virtual int setCurrentDeviceVolume(TXMediaDeviceType type, uint32_t volume) = 0;
179 257
180 /** 258 /**
181 - * 获取当前设备的音量 259 + * 2.5 获取当前设备的音量（仅适用于桌面端）
182 * 260 *
183 - * @param type 设备类型，根据设备类型获取当前设备音量。详见 TXMediaDeviceType 定义。  
184 - *  
185 - * @note - type 只支持 TXMediaDeviceTypeMic、TXMediaDeviceTypeSpeaker  
186 - * - 此接口只支持 Mac 和 Windows 平台 261 + * 这里的音量指的是麦克风的采集音量或者扬声器的播放音量，摄像头是不支持获取音量的。
187 */ 262 */
188 virtual uint32_t getCurrentDeviceVolume(TXMediaDeviceType type) = 0; 263 virtual uint32_t getCurrentDeviceVolume(TXMediaDeviceType type) = 0;
189 264
190 /** 265 /**
191 - * 设置当前设备是否静音 266 + * 2.6 设置当前设备的静音状态（仅适用于桌面端）
192 * 267 *
193 - * @param type 设备类型，根据设备类型设置当前设备状态。详见 TXMediaDeviceType 定义。  
194 - * @param mute 是否静音/禁画  
195 - * @return 0：操作成功 负数：失败  
196 - * @note - type 只支持 TXMediaDeviceTypeMic、TXMediaDeviceTypeSpeaker  
197 - * - 此接口只支持 Mac 和 Windows 平台 268 + * 这里的音量指的是麦克风和扬声器，摄像头是不支持静音操作的。
198 */ 269 */
199 virtual int setCurrentDeviceMute(TXMediaDeviceType type, bool mute) = 0; 270 virtual int setCurrentDeviceMute(TXMediaDeviceType type, bool mute) = 0;
200 271
201 /** 272 /**
202 - * 查询当前设备是否静音 273 + * 2.7 获取当前设备的静音状态（仅适用于桌面端）
203 * 274 *
204 - * @param type 设备类型，根据设备类型获取当前设备状态。详见 TXMediaDeviceType 定义。  
205 - * @return true : 当前设备已静音；false : 当前设备未静音  
206 - * @note type 只支持 TXMediaDeviceTypeMic、TXMediaDeviceTypeSpeaker 275 + * 这里的音量指的是麦克风和扬声器，摄像头是不支持静音操作的。
207 */ 276 */
208 virtual bool getCurrentDeviceMute(TXMediaDeviceType type) = 0; 277 virtual bool getCurrentDeviceMute(TXMediaDeviceType type) = 0;
209 278
210 /** 279 /**
211 - * 开始摄像头测试 280 + * 2.8 开始摄像头测试（仅适用于桌面端）
212 * 281 *
213 - * @param view 预览控件所在的父控件  
214 - * @return 0：操作成功 负数：失败  
215 - * @note - 在测试过程中可以使用 setCurrentCameraDevice 接口切换摄像头。  
216 - * - 此接口只支持 Mac 和 Windows 平台 282 + * @note 在测试过程中可以使用 {@link setCurrentDevice} 接口切换摄像头。
217 */ 283 */
218 virtual int startCameraDeviceTest(void* view) = 0; 284 virtual int startCameraDeviceTest(void* view) = 0;
219 285
220 -#ifdef _WIN32  
221 - /**  
222 - * 开始进行摄像头测试  
223 - * 会触发 onFirstVideoFrame 回调接口  
224 - *  
225 - * @param callback 摄像头预览自定义渲染画面回调  
226 - * @return 0：操作成功 负数：失败  
227 - * @note - 在测试过程中可以使用 setCurrentCameraDevice 接口切换摄像头。  
228 - * - 此接口只支持 Windows 平台  
229 - */  
230 - virtual int startCameraDeviceTest(ITRTCVideoRenderCallback* callback) = 0;  
231 -#endif  
232 -  
233 /** 286 /**
234 - * 结束摄像头测试  
235 - * @return 0：操作成功 负数：失败  
236 - * @note 此接口只支持 Mac 和 Windows 平台 287 + * 2.9 结束摄像头测试（仅适用于桌面端）
237 */ 288 */
238 virtual int stopCameraDeviceTest() = 0; 289 virtual int stopCameraDeviceTest() = 0;
239 290
240 /** 291 /**
241 - * 开始麦克风测试 292 + * 2.10 开始麦克风测试（仅适用于桌面端）
242 * 293 *
243 - * @param interval 音量回调间隔  
244 - * @return 0：操作成功 负数：失败  
245 - * @note 此接口只支持 Mac 和 Windows 平台 294 + * 该接口可以测试麦克风是否能正常工作，测试到的麦克风采集音量的大小，会以回调的形式通知给您，其中 volume 的取值范围为0 - 100。
  295 + * @param interval 麦克风音量的回调间隔。
246 */ 296 */
247 virtual int startMicDeviceTest(uint32_t interval) = 0; 297 virtual int startMicDeviceTest(uint32_t interval) = 0;
248 298
249 /** 299 /**
250 - * 结束麦克风测试  
251 - * @return 0：操作成功 负数：失败  
252 - * @note 此接口只支持 Mac 和 Windows 平台 300 + * 2.11 结束麦克风测试（仅适用于桌面端）
253 */ 301 */
254 virtual int stopMicDeviceTest() = 0; 302 virtual int stopMicDeviceTest() = 0;
255 303
256 /** 304 /**
257 - * 开始扬声器测试 305 + * 2.12 开始扬声器测试（仅适用于桌面端）
258 * 306 *
259 - * 该方法播放指定的音频文件测试播放设备是否能正常工作。如果能听到声音，说明播放设备能正常工作。 307 + * 该接口通过播放指定的音频文件，用于测试播放设备是否能正常工作。如果用户在测试时能听到声音，说明播放设备能正常工作。
260 * @param filePath 声音文件的路径 308 * @param filePath 声音文件的路径
261 - * @return 0：操作成功 负数：失败  
262 - * @note 此接口只支持 Mac 和 Windows 平台  
263 */ 309 */
264 virtual int startSpeakerDeviceTest(const char* filePath) = 0; 310 virtual int startSpeakerDeviceTest(const char* filePath) = 0;
265 311
266 /** 312 /**
267 - * 停止扬声器测试  
268 - * @return 0：操作成功 负数：失败  
269 - * @note 此接口只支持 Mac 和 Windows 平台 313 + * 2.13 结束扬声器测试（仅适用于桌面端）
270 */ 314 */
271 virtual int stopSpeakerDeviceTest() = 0; 315 virtual int stopSpeakerDeviceTest() = 0;
  316 +#endif
272 317
  318 +/**
  319 + * 2.14 开始摄像头测试（仅适用于 Windows 系统）
  320 + *
  321 + * 该接口支持自定义渲染，即您可以通过接 ITRTCVideoRenderCallback 回调接口接管摄像头的渲染画面。
  322 + */
273 #ifdef _WIN32 323 #ifdef _WIN32
274 - /**  
275 - * 设置 Windows 系统音量合成器中当前进程的音量  
276 - *  
277 - * @param volume 音量值，取值范围[0~100]  
278 - * @return 0:成功  
279 - */  
280 - virtual int setApplicationPlayVolume(int volume) = 0;  
281 -  
282 - /**  
283 - * 获取 Windows 系统音量合成器中当前进程的音量  
284 - *  
285 - * @return 返回音量值，取值范围[0~100]  
286 - */  
287 - virtual int getApplicationPlayVolume() = 0;  
288 -  
289 - /**  
290 - * 设置 Windows 系统音量合成器中当前进程的静音状态  
291 - *  
292 - * @param bMute 是否设置为静音状态  
293 - * @return 0 设置成功  
294 - */  
295 - virtual int setApplicationMuteState(bool bMute) = 0;  
296 -  
297 - /**  
298 - * 获取 Windows 系统音量合成器中当前进程的静音状态  
299 - *  
300 - * @return 返回静音状态  
301 - */  
302 - virtual bool getApplicationMuteState() = 0; 324 + virtual int startCameraDeviceTest(ITRTCVideoRenderCallback* callback) = 0;
303 #endif 325 #endif
304 -  
305 -#elif __ANDROID__ || (__APPLE__ && TARGET_OS_IOS)  
306 - /**  
307 - * 切换摄像头  
308 - *  
309 - * @param frontCamera YES：切换到前置摄像头 NO：切换到后置摄像头  
310 - * @return 0：操作成功 负数：失败  
311 - * @note 此接口只支持 Android 和 iOS 平台  
312 - */  
313 - virtual int switchCamera(bool frontCamera) = 0;  
314 -  
315 - /**  
316 - * 当前是否为前置摄像头  
317 - * @note 此接口只支持 Android 和 iOS 平台  
318 - */  
319 - virtual bool isFrontCamera() = 0;  
320 -  
321 - /**  
322 - * 获取摄像头最大缩放倍数  
323 - * @note 此接口只支持 Android 和 iOS 平台  
324 - */  
325 - virtual float getCameraZoomMaxRatio() = 0;  
326 326
327 - /**  
328 - * 设置摄像头缩放倍数  
329 - *  
330 - * @param zoomRatio 缩放倍数  
331 - * @return 0：操作成功 负数：失败  
332 - * @note 此接口只支持 Android 和 iOS 平台  
333 - */  
334 - virtual int setCameraZoomRatio(float zoomRatio) = 0;  
335 -  
336 - /**  
337 - * 设置是否自动识别人脸位置  
338 - *  
339 - * @param enabled YES：开启；NO：关闭，默认值：YES  
340 - * @return 0：操作成功 负数：失败  
341 - * @note 此接口只支持 Android 和 iOS 平台  
342 - */  
343 - virtual int enableCameraAutoFocus (bool enabled) = 0; 327 +/**
  328 + * 2.15 设置 Windows 系统音量合成器中当前进程的音量（仅适用于 Windows 系统）
  329 + */
  330 +#ifdef _WIN32
  331 + virtual int setApplicationPlayVolume(int volume) = 0;
  332 +#endif
344 333
345 - /**  
346 - * 查询是否支持自动识别人脸位置  
347 - * @note 此接口只支持 Android 和 iOS 平台  
348 - */  
349 - virtual bool isAutoFocusEnabled () = 0; 334 +/**
  335 + * 2.16 获取 Windows 系统音量合成器中当前进程的音量（仅适用于 Windows 系统）
  336 + */
  337 +#ifdef _WIN32
  338 + virtual int getApplicationPlayVolume() = 0;
  339 +#endif
350 340
351 - /**  
352 - * 设置摄像头焦点  
353 - *  
354 - * @param x 焦点横坐标  
355 - * @param y 焦点纵坐标  
356 - * @return 0：操作成功 负数：失败  
357 - * @note 此接口只支持 Android 和 iOS 平台  
358 - */  
359 - virtual int setCameraFocusPosition (float x, float y) = 0; 341 +/**
  342 + * 2.17 设置 Windows 系统音量合成器中当前进程的静音状态（仅适用于 Windows 系统）
  343 + */
  344 +#ifdef _WIN32
  345 + virtual int setApplicationMuteState(bool bMute) = 0;
  346 +#endif
360 347
361 - /**  
362 - * 设置是否开启闪光灯  
363 - *  
364 - * @param enabled YES：开启；NO：关闭，默认值：NO  
365 - * @return 0：操作成功 负数：失败  
366 - * @note 此接口只支持 Android 和 iOS 平台  
367 - */  
368 - virtual int enableCameraTorch (bool enabled) = 0; 348 +/**
  349 + * 2.18 获取 Windows 系统音量合成器中当前进程的静音状态（仅适用于 Windows 系统）
  350 + */
  351 +#ifdef _WIN32
  352 + virtual bool getApplicationMuteState() = 0;
  353 +#endif
369 354
370 - /**  
371 - * 设置通话时使用的系统音量类型  
372 - *  
373 - * @note  
374 - * 1. 需要在调用 startLocalAudio() 之前调用该接口。<br>  
375 - * 2. 如无特殊需求，不推荐您自行设置，您只需通过 enterRoom 设置好适合您的场景，SDK 内部会自动选择相匹配的音量类型。  
376 - *  
377 - * @param type 系统音量类型，如无特殊需求，不推荐您自行设置。  
378 - * @return 0：操作成功 负数：失败  
379 - * @note 此接口只支持 Android 和 iOS 平台  
380 - */  
381 - virtual int setSystemVolumeType (TXSystemVolumeType type) = 0; 355 + /// @}
  356 +}; // End of class ITXDeviceManager
  357 +} // namespace trtc
382 358
383 - /**  
384 - * 设置设置音频路由  
385 - *  
386 - * 微信和手机 QQ 视频通话功能的免提模式就是基于音频路由实现的。  
387 - * 一般手机都有两个扬声器，一个是位于顶部的听筒扬声器，声音偏小；一个是位于底部的立体声扬声器，声音偏大。  
388 - * 设置音频路由的作用就是决定声音使用哪个扬声器播放。  
389 - *  
390 - * @param route 音频路由，即声音由哪里输出（扬声器、听筒），默认值：TXAudioRouteSpeakerphone  
391 - * @return 0：操作成功 负数：失败  
392 - * @note 此接口只支持 Android 和 iOS 平台  
393 - */  
394 - virtual int setAudioRoute (TXAudioRoute route) = 0;  
395 - 359 +#ifdef _WIN32
  360 +using namespace trtc;
396 #endif 361 #endif
397 362
398 -}; 363 +#endif / *__ITXDEVICEMANAGER_H__* /
399 /// @} 364 /// @}
400 -}  
401 -  
402 -#endif /* ITXDeviceManager_h */