@tencentcloud/sdk-mcp 1.3.9 → 1.4.0

package/resource/doc/livekit/core-sdk/live/flutter/api-reference/BarrageStore.md

@@ -0,0 +1,158 @@
+## 简介
+
+**BarrageStore** 提供了一套完整的弹幕管理 API，包括发送文本弹幕、发送自定义弹幕和添加本地提示消息。
+通过该类，可以在直播间内实现弹幕互动功能。
+
+> **重要：**
+>
+
+> 使用 **create** 工厂方法创建 **BarrageStore** 实例，需要传入有效的直播间 ID。
+>
+
+> **说明：**
+>
+
+> 弹幕状态更新通过 **barrageState** 发布者传递。订阅它以接收房间内弹幕数据的实时更新。
+>
+
+## 功能特性
+- **文本弹幕**：支持发送纯文本弹幕消息。
+
+- **自定义弹幕**：支持发送自定义格式的弹幕（如带特效的弹幕）。
+
+- **本地提示**：支持添加仅本地可见的提示消息。
+
+## 可订阅数据
+
+**BarrageState** 的字段描述如下：
+| **属性名** | **类型** | **描述** |
+| --- | --- | --- |
+| messageList | ValueListenable<List<Barrage>> | 当前房间的弹幕消息列表，支持实时更新并可被订阅监听。 |
+
+## API 列表
+| **函数名** | **描述** |
+| --- | --- |
+| create | 创建弹幕管理实例。 |
+| sendTextMessage | 发送文本弹幕。 |
+| sendCustomMessage | 发送自定义弹幕。 |
+| appendLocalTip | 添加本地提示消息。 |
+
+### 创建实例
+
+#### create
+
+弹幕管理核心类，用于处理直播间/语音聊天房内的弹幕相关业务逻辑。
+``` dart
+static BarrageStore create(String liveID) {
+  return StoreFactory.shared.getStore<BarrageStore>(liveID: liveID);
+}
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**参数说明**
+| **参数名** | **类型** | **是否必填** | **描述** |
+| --- | --- | --- | --- |
+| liveID | String | 必填 | 直播间ID。 |
+
+### 发送弹幕
+
+#### sendTextMessage
+
+发送文本类型弹幕。
+``` dart
+Future<CompletionHandler> sendTextMessage({
+  required String text,
+  Map<String, String>? extensionInfo,
+});
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**参数说明**
+| **参数名** | **类型** | **是否必填** | **描述** |
+| --- | --- | --- | --- |
+| text | String | 必填 | 文本弹幕内容。 |
+| extensionInfo | Map<String,String>? | 必填 | 扩展信息，可包含自定义字段（如指定弹幕颜色、字体大小等）。 |
+
+#### sendCustomMessage
+
+发送自定义类型弹幕。
+``` dart
+Future<CompletionHandler> sendCustomMessage({
+  required String businessID,
+  required String data,
+});
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**参数说明**
+| **参数名** | **类型** | **是否必填** | **描述** |
+| --- | --- | --- | --- |
+| businessID | String | 必填 | 业务标识ID，用于区分不同业务场景的自定义弹幕。 |
+| data | String | 必填 | 自定义数据内容，通常为JSON格式字符串，用于传递业务自定义的数据。 |
+
+### 本地消息
+
+#### appendLocalTip
+
+添加本地提示消息（在本地添加提示或操作反馈消息，仅当前客户端可见）。
+``` dart
+void appendLocalTip(Barrage message);
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**注意事项**
+
+> **说明：**
+>
+
+> 该消息仅在本地显示，不会通过网络发送给其他用户。
+>
+
+**参数说明**
+| **参数名** | **类型** | **是否必填** | **描述** |
+| --- | --- | --- | --- |
+| message | Barrage | 必填 | 本地弹幕消息（如系统提示、操作反馈等，仅当前用户可见）。 |
+
+## 数据结构
+
+### BarrageType
+
+弹幕类型枚举，用于区分不同的弹幕消息种类。
+| **枚举值** | **值** | **说明** |
+| --- | --- | --- |
+| text | 0 | 文本类型弹幕，包含纯文字内容。 |
+| custom | 1 | 自定义类型弹幕，支持业务自定义数据格式（如带特效的弹幕、互动消息等）。 |
+
+### Barrage
+
+弹幕数据模型，包含单条弹幕的完整属性信息。
+| **属性** | **类型** | **说明** |
+| --- | --- | --- |
+| liveID | String | 弹幕所属直播间/语音聊天房的唯一标识ID。 |
+| sender | LiveUserInfo | 弹幕发送者的用户信息（如用户ID、昵称、头像等）。 |
+| sequence | int | 弹幕消息的唯一序列ID，用于消息排序和去重。 |
+| timestampInSecond | int | 弹幕发送时间戳（单位：秒），用于展示发送时间顺序。 |
+| messageType | BarrageType | 弹幕消息类型（文本或自定义）。 |
+| textContent | String | 文本类型弹幕的消息内容，即弹幕的文本内容。 |
+| extensionInfo | Map<String,String> | 弹幕扩展信息，可自定义字段（如显示样式、优先级等）。当 messageType 为 TEXT 时有效。 |
+| businessID | String | 自定义类型弹幕的业务标识ID，用于区分不同业务场景的自定义弹幕。 |
+| data | String | 自定义类型弹幕的具体数据内容（通常为JSON格式字符串），当 messageType 为 CUSTOM 时有效。 |
+
+### BarrageState
+
+弹幕状态，管理当前房间的弹幕数据状态。
+| **属性** | **类型** | **说明** |
+| --- | --- | --- |
+| messageList | ValueListenable<List<Barrage>> | 当前房间的弹幕消息列表，支持实时更新并可被订阅监听。 |

package/resource/doc/livekit/core-sdk/live/flutter/api-reference/BaseBeautyStore.md

@@ -0,0 +1,155 @@
+## 简介
+
+基础美颜功能通过简单易用的 API 实现实时美颜效果调节。**BaseBeautyStore** 提供了一套完整的接口来管理美颜效果的设置和状态订阅。
+
+> **说明：**
+>
+
+> 美颜状态更新通过 **baseBeautyState** 发布者传递。订阅它以接收有关美颜效果级别的实时更新。
+>
+
+## 功能特性
+- **磨皮效果**：支持 0-9 级别的磨皮效果调节。
+
+- **美白效果**：支持 0-9 级别的美白效果调节。
+
+- **红润效果**：支持 0-9 级别的红润效果调节。
+
+- **状态订阅**：实时订阅美颜状态变化，同步 UI 显示与实际效果。
+
+## 可订阅数据
+
+**BaseBeautyState** 的字段描述如下：
+| **属性名** | **类型** | **描述** |
+| --- | --- | --- |
+| smoothLevel | ValueListenable<double> | 磨皮级别，取值范围 [0-9]；0 表示关闭，9 表示效果最明显。 |
+| whitenessLevel | ValueListenable<double> | 美白级别，取值范围 [0-9]；0 表示关闭，9 表示效果最明显。 |
+| ruddyLevel | ValueListenable<double> | 红润级别，取值范围 [0-9]；0 表示关闭，9 表示效果最明显。 |
+
+## API 列表
+| **函数名** | **描述** |
+| --- | --- |
+| shared | 获取单例实例。 |
+| setSmoothLevel | 设置磨皮级别。 |
+| setWhitenessLevel | 设置美白级别。 |
+| setRuddyLevel | 设置红润级别。 |
+| reset | 重置为默认状态。 |
+
+### 获取实例
+
+#### shared
+
+获取单例实例。
+
+### 美颜调节
+
+#### setSmoothLevel
+
+设置磨皮级别
+``` dart
+void setSmoothLevel(double smoothLevel);
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**参数说明**
+| **参数名** | **类型** | **是否必填** | **描述** |
+| --- | --- | --- | --- |
+| smoothLevel | double | 必填 | 磨皮级别，取值范围 [0, 9]；0 表示关闭，9 表示效果最明显。 |
+
+#### setWhitenessLevel
+
+设置美白级别
+``` dart
+void setWhitenessLevel(double whitenessLevel);
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**参数说明**
+| **参数名** | **类型** | **是否必填** | **描述** |
+| --- | --- | --- | --- |
+| whitenessLevel | double | 必填 | 美白级别，取值范围 [0, 9]；0 表示关闭，9 表示效果最明显。 |
+
+#### setRuddyLevel
+
+设置红润级别
+``` dart
+void setRuddyLevel(double ruddyLevel);
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**参数说明**
+| **参数名** | **类型** | **是否必填** | **描述** |
+| --- | --- | --- | --- |
+| ruddyLevel | double | 必填 | 红润级别，取值范围 [0, 9]；0 表示关闭，9 表示效果最明显。 |
+
+#### reset
+
+将所有美颜参数（磨皮、美白、红润）重置为默认关闭状态（值为0）。
+``` dart
+void reset();
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+## 数据结构
+
+### BaseBeautyState
+
+基础美颜状态，管理磨皮、美白、红润等美颜效果的级别数据。支持订阅以同步 UI 显示与实际效果。
+| **属性** | **类型** | **说明** |
+| --- | --- | --- |
+| smoothLevel | ValueListenable<double> | 磨皮级别，取值范围 [0-9]；0 表示关闭，9 表示效果最明显。 |
+| whitenessLevel | ValueListenable<double> | 美白级别，取值范围 [0-9]；0 表示关闭，9 表示效果最明显。 |
+| ruddyLevel | ValueListenable<double> | 红润级别，取值范围 [0-9]；0 表示关闭，9 表示效果最明显。 |
+
+## 使用示例
+``` dart
+// 获取单例实例
+final store = BaseBeautyStore.shared;
+
+// 定义监听器
+late final VoidCallback smoothLevelListener = _onSmoothLevelChanged;
+late final VoidCallback whitenessLevelListener = _onWhitenessLevelChanged;
+late final VoidCallback ruddyLevelListener = _onRuddyLevelChanged;
+
+void _onSmoothLevelChanged() {
+    print('磨皮级别: ${store.baseBeautyState.smoothLevel.value}');
+}
+
+void _onWhitenessLevelChanged() {
+    print('美白级别: ${store.baseBeautyState.whitenessLevel.value}');
+}
+
+void _onRuddyLevelChanged() {
+    print('红润级别: ${store.baseBeautyState.ruddyLevel.value}');
+}
+
+// 订阅状态变化
+store.baseBeautyState.smoothLevel.addListener(smoothLevelListener);
+store.baseBeautyState.whitenessLevel.addListener(whitenessLevelListener);
+store.baseBeautyState.ruddyLevel.addListener(ruddyLevelListener);
+
+// 设置美颜效果
+store.setSmoothLevel(5.0);
+store.setWhitenessLevel(3.0);
+store.setRuddyLevel(2.0);
+
+// 重置所有美颜效果
+store.reset();
+
+// 取消订阅
+store.baseBeautyState.smoothLevel.removeListener(smoothLevelListener);
+store.baseBeautyState.whitenessLevel.removeListener(whitenessLevelListener);
+store.baseBeautyState.ruddyLevel.removeListener(ruddyLevelListener);
+```

package/resource/doc/livekit/core-sdk/live/flutter/api-reference/BattleStore.md

@@ -0,0 +1,304 @@
+## 简介
+
+PK 功能实现主播之间的实时互动对战。**BattleStore** 提供了一套全面的 API 来管理整个 PK 生命周期。
+
+> **重要：**
+>
+
+> 请始终使用工厂方法 **create(liveID:)** 并提供有效的直播间 ID 来创建 **BattleStore** 实例。不要尝试直接初始化。
+>
+
+> **说明：**
+>
+
+> PK 状态更新通过 **battleState** 发布者传递。订阅它以接收有关 PK 信息、参与用户和分数的实时更新。
+>
+
+> **警告：**
+>
+
+> 如果 PK 请求在指定的超时时间内未收到响应，将触发超时事件。请始终在 UI 中处理超时场景。
+>
+
+## 功能特性
+- **PK 请求管理**：主播可以发起 PK 请求，被邀请方可以接受或拒绝。
+
+- **状态管理**：实时跟踪 PK 信息、参与用户和分数。
+
+- **事件驱动架构**：提供完整的 PK 事件回调。
+
+- **超时处理**：为 PK 请求提供内置超时机制。
+
+## 可订阅数据
+
+**BattleState** 的字段描述如下：
+| **属性名** | **类型** | **描述** |
+| --- | --- | --- |
+| currentBattleInfo | ValueListenable<BattleInfo?> | 当前 PK 信息。 |
+| battleUsers | ValueListenable<List<SeatUserInfo>> | PK 用户列表。 |
+| battleScore | ValueListenable<Map<String,int>> | PK 分数的映射。 |
+
+## API 列表
+| **函数名** | **描述** |
+| --- | --- |
+| BattleStore.create | 创建 BattleStore 实例。 |
+| addBattleListener | 新增 PK 事件回调。 |
+| removeBattleListener | 移除 PK 事件回调。 |
+| requestBattle | 发起 PK 请求。 |
+| cancelBattleRequest | 取消 PK 请求。 |
+| acceptBattle | 接受 PK 请求。 |
+| rejectBattle | 拒绝 PK 请求。 |
+| exitBattle | 退出 PK。 |
+
+### 创建实例
+
+#### BattleStore.create
+
+创建 BattleStore 实例。
+
+### 观察状态和事件
+
+#### addBattleListener
+
+新增 PK 事件回调
+``` dart
+void addBattleListener(BattleListener listener);
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**参数说明**
+| **参数名** | **类型** | **是否必填** | **描述** |
+| --- | --- | --- | --- |
+| listener | BattleListener | 必填 | 监听器。 |
+
+#### removeBattleListener
+
+移除 PK 事件回调
+``` dart
+void removeBattleListener(BattleListener listener);
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**参数说明**
+| **参数名** | **类型** | **是否必填** | **描述** |
+| --- | --- | --- | --- |
+| listener | BattleListener | 必填 | 监听器。 |
+
+### PK 操作
+
+#### requestBattle
+
+发起 PK 请求
+``` dart
+Future<BattleRequestCompletionHandler> requestBattle({
+    required BattleConfig config,
+    required List<String> userIDList,
+    required int timeout,
+});
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**参数说明**
+| **参数名** | **类型** | **是否必填** | **描述** |
+| --- | --- | --- | --- |
+| config | BattleConfig | 必填 | PK 配置。 |
+| userIDList | List<String> | 必填 | 需要进入PK的用户 ID 列表。 |
+| timeout | int | 必填 | 请求超时时间。 |
+
+#### cancelBattleRequest
+
+取消PK请求
+``` dart
+Future<CompletionHandler> cancelBattleRequest({
+    required String battleID,
+    required List<String> userIDList,
+});
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**参数说明**
+| **参数名** | **类型** | **是否必填** | **描述** |
+| --- | --- | --- | --- |
+| battleID | String | 必填 | PK ID。 |
+| userIDList | List<String> | 必填 | 用户ID列表。 |
+
+#### acceptBattle
+
+接受PK请求
+``` dart
+Future<CompletionHandler> acceptBattle(String battleID);
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**参数说明**
+| **参数名** | **类型** | **是否必填** | **描述** |
+| --- | --- | --- | --- |
+| battleID | String | 必填 | PK ID。 |
+
+#### rejectBattle
+
+拒绝PK请求
+``` dart
+Future<CompletionHandler> rejectBattle(String battleID);
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**参数说明**
+| **参数名** | **类型** | **是否必填** | **描述** |
+| --- | --- | --- | --- |
+| battleID | String | 必填 | PK ID。 |
+
+#### exitBattle
+
+退出PK
+``` dart
+Future<CompletionHandler> exitBattle(String battleID);
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**参数说明**
+| **参数名** | **类型** | **是否必填** | **描述** |
+| --- | --- | --- | --- |
+| battleID | String | 必填 | PK ID。 |
+
+## 数据结构
+
+### BattleEndedReason
+
+正在 PK 中用户收到 PK 结束的原因。
+| **枚举值** | **值** | **说明** |
+| --- | --- | --- |
+| timeOver | 0 | PK 倒计时结束。 |
+| allMemberExit | 1 | 所有 PK 成员退出。 |
+
+### BattleListener
+
+收到 PK 相关的回调事件。
+
+**方法**
+| **方法名** | **说明** |
+| --- | --- |
+| onBattleStarted | 当PK正式开始时触发此回调，通知所有参与者PK已经开始。 |
+| onBattleEnded | 当PK结束时触发此回调。 |
+| onUserJoinBattle | 当有用户加入PK时触发此回调。 |
+| onUserExitBattle | 当有用户退出PK时触发此回调。 |
+| onBattleRequestReceived | 当收到PK请求时触发此回调。 |
+| onBattleRequestCancelled | 当PK请求被取消时触发此回调。 |
+| onBattleRequestTimeout | 当PK请求超时时触发此回调。 |
+| onBattleRequestAccept | 当PK请求被接受时触发此回调。 |
+| onBattleRequestReject | 当PK请求被拒绝时触发此回调。 |
+
+### BattleConfig
+
+发送 PK 请求时，设置的 PK 配置信息。
+| **属性** | **类型** | **说明** |
+| --- | --- | --- |
+| duration | int | PK 持续时间（单位：秒）。 |
+| needResponse | bool | 被邀请用户是否需要回复同意/拒绝。 |
+| extensionInfo | String | 扩展信息。 |
+
+### BattleInfo
+
+PK 信息。
+| **属性** | **类型** | **说明** |
+| --- | --- | --- |
+| battleID | String | PK ID。 |
+| config | BattleConfig | 发送 PK 请求时，设置的 PK 配置信息。 |
+| startTime | int | PK 开始标记时间戳（单位：秒）。 |
+| endTime | int | PK 结束标记时间戳（单位：秒）。 |
+
+### BattleState
+
+BattleStore 对外提供的 PK 相关状态数据。
+| **属性** | **类型** | **说明** |
+| --- | --- | --- |
+| currentBattleInfo | ValueListenable<BattleInfo?> | 当前 PK 信息。 |
+| battleUsers | ValueListenable<List<SeatUserInfo>> | PK 用户列表。 |
+| battleScore | ValueListenable<Map<String,int>> | PK 分数的映射。 |
+
+### BattleRequestCompletionHandler
+
+PK 请求完成处理器。
+
+Dart 中 PK 请求的完成处理器，包含 PK 请求的结果。
+
+**属性**
+| **属性** | **类型** | **说明** |
+| --- | --- | --- |
+| battleInfo | BattleInfo? | 成功时返回的 PK 信息。 |
+| resultMap | Map<String,int>? | PK 请求的响应结果映射。 |
+
+## 使用示例
+``` dart
+// 创建 store 实例
+final store = BattleStore.create('live_room_123');
+
+// 定义监听器
+late final VoidCallback battleInfoListener = _onBattleInfoChanged;
+late final VoidCallback battleUsersListener = _onBattleUsersChanged;
+
+void _onBattleInfoChanged() {
+    final battleInfo = store.battleState.currentBattleInfo.value;
+    if (battleInfo != null) {
+        print('当前 PK ID: ${battleInfo.battleID}');
+    }
+}
+
+void _onBattleUsersChanged() {
+    print('PK 用户数: ${store.battleState.battleUsers.value.length}');
+}
+
+// 订阅状态变化
+store.battleState.currentBattleInfo.addListener(battleInfoListener);
+store.battleState.battleUsers.addListener(battleUsersListener);
+
+// 添加 PK 事件监听器
+final battleListener = BattleListener(
+    onBattleStarted: (battleInfo, inviter, invitees) {
+        print('PK 开始，发起者: ${inviter.userName}');
+    },
+    onBattleEnded: (battleInfo, reason) {
+        print('PK 结束，原因: $reason');
+    },
+);
+store.addBattleListener(battleListener);
+
+// 发起 PK 请求
+final config = BattleConfig(duration: 300, needResponse: true);
+final result = await store.requestBattle(
+    config: config,
+    userIDList: ['user_456'],
+    timeout: 30,
+);
+if (result.code == 0) {
+    print('PK 请求成功: ${result.battleInfo?.battleID}');
+} else {
+    print('PK 请求失败: ${result.message}');
+}
+
+// 取消订阅
+store.battleState.currentBattleInfo.removeListener(battleInfoListener);
+store.battleState.battleUsers.removeListener(battleUsersListener);
+store.removeBattleListener(battleListener);
+```