@tencentcloud/sdk-mcp 1.3.9 → 1.4.0

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

@@ -0,0 +1,410 @@
+## 简介
+
+**DeviceStore** 提供了一套全面的 API 来管理音视频设备，包括麦克风、摄像头和屏幕分享等功能。
+
+> **重要：**
+>
+
+> 请使用 **shared** 单例获取 **DeviceStore** 实例。不要尝试直接初始化。
+>
+
+> **说明：**
+>
+
+> 设备状态更新通过 **state** 发布者传递。订阅它以接收有关麦克风、摄像头、网络等状态的实时更新。
+>
+
+## 功能特性
+- **麦克风管理**：打开/关闭麦克风，设置采集音量和输出音量。
+
+- **摄像头管理**：打开/关闭摄像头，切换前后摄像头，设置镜像和视频质量。
+
+- **音频路由**：切换扬声器和听筒。
+
+- **屏幕分享**：开启和关闭屏幕分享功能。
+
+- **网络状态**：实时监控网络质量信息。
+
+## 可订阅数据
+
+**DeviceState** 的字段描述如下：
+| **属性名** | **类型** | **描述** |
+| --- | --- | --- |
+| microphoneStatus | ValueListenable<DeviceStatus> | 麦克风状态。 |
+| microphoneLastError | ValueListenable<DeviceError> | 麦克风错误，用于出现报错时提取错误信息。 |
+| captureVolume | ValueListenable<int> | 采集音量，取值范围 [0, 100]。 |
+| currentMicVolume | ValueListenable<int> | 当前用户实际输出音量。 |
+| outputVolume | ValueListenable<int> | 最大输出音量，取值范围 [0, 100]。 |
+| cameraStatus | ValueListenable<DeviceStatus> | 摄像头状态。 |
+| cameraLastError | ValueListenable<DeviceError> | 摄像头错误，用于出现报错时提取错误信息。 |
+| isFrontCamera | ValueListenable<bool> | 是否为前置摄像头。 |
+| localMirrorType | ValueListenable<MirrorType> | 镜像状态。 |
+| localVideoQuality | ValueListenable<VideoQuality> | 本地视频质量。 |
+| currentAudioRoute | ValueListenable<AudioRoute> | 当前音频路由位置。 |
+| screenStatus | ValueListenable<DeviceStatus> | 屏幕分享状态。 |
+| networkInfo | ValueListenable<NetworkInfo> | 网络信息。 |
+
+## API 列表
+| **函数名** | **描述** |
+| --- | --- |
+| shared | 单例对象。 |
+| openLocalMicrophone(completion:) | 打开本地麦克风。 |
+| closeLocalMicrophone() | 关闭本地麦克风。 |
+| setCaptureVolume(volume:) | 设置采集音量。 |
+| setOutputVolume(_:) | 设置输出音量。 |
+| setAudioRoute(_:) | 设置音频路由。 |
+| startCameraTest(cameraView:completion:) | 开始摄像头测试。 |
+| stopCameraTest() | 停止摄像头测试。 |
+| openLocalCamera(isFront:completion:) | 打开本地摄像头。 |
+| closeLocalCamera() | 关闭本地摄像头。 |
+| switchCamera(isFront:) | 切换摄像头。 |
+| switchMirror(mirrorType:) | 切换镜像状态。 |
+| updateVideoQuality(_:) | 更新视频质量。 |
+| startScreenShare(appGroup:) | 开启屏幕分享。 |
+| stopScreenShare() | 关闭屏幕分享。 |
+| reset() | 重置为默认状态。 |
+
+### 获取实例
+
+#### shared
+
+单例对象。
+
+### 麦克风操作
+
+#### openLocalMicrophone
+
+打开本地麦克风
+``` dart
+Future<CompletionHandler> openLocalMicrophone();
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**参数说明**
+| **参数名** | **类型** | **是否必填** | **描述** |
+| --- | --- | --- | --- |
+| completion | CompletionClosure? | 必填 | 操作是否成功。 |
+
+#### closeLocalMicrophone
+
+关闭本地麦克风
+``` dart
+void closeLocalMicrophone();
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+#### setCaptureVolume
+
+设置采集音量
+``` dart
+void setCaptureVolume(int volume);
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**参数说明**
+| **参数名** | **类型** | **是否必填** | **描述** |
+| --- | --- | --- | --- |
+| volume | int | 必填 | 采集音量，取值范围 [0, 100]。 |
+
+#### setOutputVolume
+
+设置最大输出音量
+``` dart
+void setOutputVolume(int volume);
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**参数说明**
+| **参数名** | **类型** | **是否必填** | **描述** |
+| --- | --- | --- | --- |
+| volume | int | 必填 | 最大音量，取值范围 [0, 100]。 |
+
+### 音频路由
+
+#### setAudioRoute
+
+设置音频路由
+``` dart
+void setAudioRoute(AudioRoute route);
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**参数说明**
+| **参数名** | **类型** | **是否必填** | **描述** |
+| --- | --- | --- | --- |
+| route | AudioRoute | 必填 | 路由位置。 |
+
+### 摄像头操作
+
+#### startCameraTest(cameraView:completion:)
+
+开始摄像头测试。
+
+#### stopCameraTest()
+
+停止摄像头测试。
+
+#### openLocalCamera
+
+打开本地摄像头
+``` dart
+Future<CompletionHandler> openLocalCamera(bool isFront);
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**参数说明**
+| **参数名** | **类型** | **是否必填** | **描述** |
+| --- | --- | --- | --- |
+| isFront | bool | 必填 | 是否前置摄像头。 |
+| completion | CompletionClosure? | 必填 | 操作是否成功。 |
+
+#### closeLocalCamera
+
+关闭本地摄像头
+``` dart
+void closeLocalCamera();
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+#### switchCamera
+
+切换摄像头
+``` dart
+void switchCamera(bool isFront);
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**参数说明**
+| **参数名** | **类型** | **是否必填** | **描述** |
+| --- | --- | --- | --- |
+| isFront | bool | 必填 | 是否前置摄像头。 |
+
+#### switchMirror
+
+切换镜像状态
+``` dart
+void switchMirror(MirrorType mirrorType);
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**参数说明**
+| **参数名** | **类型** | **是否必填** | **描述** |
+| --- | --- | --- | --- |
+| mirrorType | MirrorType | 必填 | 镜像状态。 |
+
+#### updateVideoQuality
+
+更新视频质量
+``` dart
+void updateVideoQuality(VideoQuality quality);
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**参数说明**
+| **参数名** | **类型** | **是否必填** | **描述** |
+| --- | --- | --- | --- |
+| quality | VideoQuality | 必填 | 视频质量。 |
+
+### 屏幕分享
+
+#### startScreenShare
+
+开启屏幕分享
+``` dart
+void startScreenShare();
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+#### stopScreenShare
+
+关闭屏幕采集
+``` dart
+void stopScreenShare();
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+### 重置
+
+#### reset
+
+重置为默认状态
+``` dart
+void reset();
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+## 数据结构
+
+### DeviceType
+
+设备类型。
+| **枚举值** | **值** | **说明** |
+| --- | --- | --- |
+| microphone | 0 | 麦克风类型。 |
+| camera | 1 | 摄像头类型。 |
+| screenShare | 2 | 屏幕分享类型。 |
+
+### DeviceError
+
+设备相关错误码。
+| **枚举值** | **值** | **说明** |
+| --- | --- | --- |
+| noError | 0 | 操作成功。 |
+| noDeviceDetected | 1 | 未检测到设备。 |
+| noSystemPermission | 2 | 没有系统权限。 |
+| notSupportCapture | 3 | 不支持采集。 |
+| occupiedError | 4 | 设备已占用。 |
+| unknownError | 5 | 未知错误。 |
+
+### DeviceStatus
+
+设备开启状态。
+| **枚举值** | **值** | **说明** |
+| --- | --- | --- |
+| off | 0 | 关闭。 |
+| on | 1 | 开启。 |
+
+### AudioRoute
+
+音频路由。
+| **枚举值** | **值** | **说明** |
+| --- | --- | --- |
+| speakerphone | 0 | 扬声器，使用扬声器播放（即"免提"），扬声器位于手机底部，声音偏大，适合外放音乐。 |
+| earpiece | 1 | 听筒，使用听筒播放，听筒位于手机顶部，声音偏小，适合需要保护隐私的通话场景。 |
+
+### VideoQuality
+
+视频质量。
+| **枚举值** | **值** | **说明** |
+| --- | --- | --- |
+| quality360P | 1 | 360P。 |
+| quality540P | 2 | 540P。 |
+| quality720P | 3 | 720P。 |
+| quality1080P | 4 | 1080P。 |
+
+### NetworkQuality
+
+网络质量。
+| **枚举值** | **值** | **说明** |
+| --- | --- | --- |
+| unknown | 0 | 未知网络。 |
+| excellent | 1 | 极佳。 |
+| good | 2 | 良好。 |
+| poor | 3 | 较差。 |
+| bad | 4 | 差。 |
+| veryBad | 5 | 极差。 |
+| down | 6 | 中断。 |
+
+### MirrorType
+
+摄像头镜像状态。
+| **枚举值** | **值** | **说明** |
+| --- | --- | --- |
+| auto | 0 | 自动，前置摄像头镜像，后置摄像头不镜像。 |
+| enable | 1 | 前后摄像头均镜像。 |
+| disable | 2 | 前后摄像头均不镜像。 |
+
+### DeviceFocusOwner
+
+设备焦点。
+| **枚举值** | **说明** |
+| --- | --- |
+| call | 语音通话场景。 |
+| live | 直播场景。 |
+| none | 未设置。 |
+
+### NetworkInfo
+
+网络信息
+| **属性** | **类型** | **说明** |
+| --- | --- | --- |
+| userID | String | 用户唯一ID。 |
+| quality | NetworkQuality | 网络质量。 |
+| upLoss | int | 上行丢包率，取值范围 [0, 100]。 |
+| downLoss | int | 下行丢包率，取值范围 [0, 100]。 |
+| delay | int | 延迟（单位：毫秒）。 |
+
+### DeviceState
+
+设备状态。
+| **属性** | **类型** | **说明** |
+| --- | --- | --- |
+| microphoneStatus | ValueListenable<DeviceStatus> | 麦克风状态。 |
+| microphoneLastError | ValueListenable<DeviceError> | 麦克风错误，用于出现报错时提取错误信息。 |
+| captureVolume | ValueListenable<int> | 采集音量，取值范围 [0, 100]。 |
+| currentMicVolume | ValueListenable<int> | 当前用户实际输出音量。 |
+| outputVolume | ValueListenable<int> | 最大输出音量，取值范围 [0, 100]。 |
+| cameraStatus | ValueListenable<DeviceStatus> | 摄像头状态。 |
+| cameraLastError | ValueListenable<DeviceError> | 摄像头错误，用于出现报错时提取错误信息。 |
+| isFrontCamera | ValueListenable<bool> | 是否为前置摄像头。 |
+| localMirrorType | ValueListenable<MirrorType> | 镜像状态。 |
+| localVideoQuality | ValueListenable<VideoQuality> | 本地视频质量。 |
+| currentAudioRoute | ValueListenable<AudioRoute> | 当前音频路由位置。 |
+| screenStatus | ValueListenable<DeviceStatus> | 屏幕分享状态。 |
+| networkInfo | ValueListenable<NetworkInfo> | 网络信息。 |
+
+## 使用示例
+``` dart
+// 获取单例实例
+let store = DeviceStore.shared
+
+// 订阅状态变化
+store.state.subscribe { state in
+    print("麦克风状态: \(state.microphoneStatus)")
+    print("摄像头状态: \(state.cameraStatus)")
+    print("网络质量: \(state.networkInfo.quality)")
+}
+
+// 打开麦克风
+store.openLocalMicrophone { code, message in
+    if code == 0 {
+        print("麦克风打开成功")
+    }
+}
+
+// 打开前置摄像头
+store.openLocalCamera(isFront: true) { code, message in
+    if code == 0 {
+        print("摄像头打开成功")
+    }
+}
+```

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

@@ -0,0 +1,160 @@
+## 简介
+
+**GiftStore** 提供了一套完整的礼物管理 API，包括发送礼物、刷新礼物列表、设置语言和监听礼物事件。
+通过该类，可以在直播间内实现礼物互动功能。
+
+> **重要：**
+>
+
+> 使用 **GiftStore.create** 工厂方法创建 **GiftStore** 实例，需要传入有效的直播间 ID。
+>
+
+> **说明：**
+>
+
+> 礼物状态更新通过 **giftState** 发布者传递。订阅它以接收房间内礼物数据的实时更新。
+>
+
+## 功能特性
+- **礼物发送**：支持向当前房间发送指定礼物。
+
+- **礼物列表**：获取和刷新当前房间可用的礼物列表。
+
+- **语言设置**：设置礼物信息的展示语言。
+
+- **事件监听**：监听礼物接收事件。
+
+## 可订阅数据
+
+**GiftState** 的字段描述如下：
+| **属性名** | **类型** | **描述** |
+| --- | --- | --- |
+| usableGifts | ValueListenable<List<GiftCategory>> | 当前房间可用的所有礼物分类及礼物列表。 |
+
+## API 列表
+| **函数名** | **描述** |
+| --- | --- |
+| GiftStore.create | 创建礼物管理实例。 |
+| addGiftListener | 礼物事件回调。 |
+| removeGiftListener | 礼物事件回调。 |
+| sendGift | 发送礼物。 |
+| refreshUsableGifts | 刷新可用礼物列表。 |
+| setLanguage | 设置展示语言。 |
+
+### 创建实例
+
+#### GiftStore.create
+
+创建礼物管理实例。
+
+### 观察状态和事件
+
+#### addGiftListener
+
+礼物事件回调
+
+#### removeGiftListener
+
+礼物事件回调
+
+### 礼物操作
+
+#### sendGift
+
+向当前房间发送指定礼物
+``` dart
+Future<CompletionHandler> sendGift({
+  required String giftID,
+  required int count,
+});
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**参数说明**
+| **参数名** | **类型** | **是否必填** | **描述** |
+| --- | --- | --- | --- |
+| giftID | String | 必填 | 要发送的礼物唯一标识 ID。 |
+| count | int | 必填 | 单次发送的礼物数量。 |
+
+#### refreshUsableGifts
+
+手动刷新当前房间的可用礼物列表。
+``` dart
+Future<CompletionHandler> refreshUsableGifts();
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+#### setLanguage
+
+设置礼物信息的展示语言。
+``` dart
+void setLanguage(String language);
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**参数说明**
+| **参数名** | **类型** | **是否必填** | **描述** |
+| --- | --- | --- | --- |
+| language | String | 必填 | 语言代码（"zh-CN" 表示中文，"en" 表示英文），设置完成展示界面刷新后礼物名称、描述等会同步更新为对应语言。 |
+
+## 数据结构
+
+### Gift
+
+礼物数据模型，包含单个礼物的完整属性信息。
+| **属性** | **类型** | **说明** |
+| --- | --- | --- |
+| giftID | String | 礼物ID。 |
+| name | String | 礼物名称。 |
+| desc | String | 礼物描述。 |
+| iconURL | String | 礼物图标图片的网络 URL，用于加载礼物缩略图。 |
+| resourceURL | String | 礼物动效资源文件的网络 URL，用于加载礼物展示动效。 |
+| level | int | 礼物等级，用于区分礼物稀有度或价值层级。 |
+| coins | int | 礼物价格（金币）。 |
+| extensionInfo | Map<String,String> | 礼物扩展信息，可自定义字段（如特效类型、赠送限制等）。 |
+
+### GiftCategory
+
+礼物分类。
+| **属性** | **类型** | **说明** |
+| --- | --- | --- |
+| categoryID | String | 分类唯一标识 ID，用于区分不同礼物分类。 |
+| name | String | 分类展示名称，用于 UI 分类显示（如 "热门礼物"，"高级礼物"）。 |
+| desc | String | 分类描述信息，用于说明该分类的特点。 |
+| extensionInfo | Map<String,String> | 分类扩展信息，包含自定义字段（如排序权重、显示样式等）。 |
+| giftList | List<Gift> | 当前分类下的所有礼物列表。 |
+
+### GiftState
+
+礼物状态，管理当前房间的礼物数据状态，支持实时更新并可被订阅监听。
+| **属性** | **类型** | **说明** |
+| --- | --- | --- |
+| usableGifts | ValueListenable<List<GiftCategory>> | 当前房间可用的所有礼物分类及礼物列表。 |
+
+### GiftListener
+
+礼物事件，用于接收直播间/语音聊天房内的礼物动态。
+
+**方法**
+
+**onReceiveGift**: 收到新礼物消息的事件回调。当直播间/语音聊天房内有其他观众发送礼物时，会触发该事件并返回相关信息。
+``` dart
+void Function(String liveID, Gift gift, int count, LiveUserInfo sender)? onReceiveGift;
+
+GiftListener({this.onReceiveGift});
+```
+| **参数名** | **类型** | **说明** |
+| --- | --- | --- |
+| liveID | String | 直播间ID。 |
+| gift | Gift | 礼物信息。 |
+| count | int | 礼物数量。 |
+| sender | LiveUserInfo | 礼物发送者信息。 |

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

@@ -0,0 +1,51 @@
+## 简介
+
+**LikeStore** 提供了一套完整的点赞管理 API，包括发送点赞、监听点赞事件和获取点赞状态。通过该类，可以在直播间内实现点赞互动功能。
+
+> **重要：**
+>
+
+> 使用 **create** 工厂方法创建 **LikeStore** 实例，需要传入有效的直播间 ID。
+>
+
+> **说明：**
+>
+
+> 点赞状态更新通过 **likeState** 发布者传递。订阅它以接收房间内点赞数据的实时更新。
+>
+
+## 功能特性
+- **点赞发送**：支持向当前房间发送点赞。
+
+- **点赞状态**：获取当前房间的累计点赞数。
+
+- **事件监听**：监听点赞接收事件。
+
+## 数据结构
+
+### LikeState
+
+点赞状态，用于展示和订阅直播间/语音聊天房的点赞信息。
+| **属性** | **类型** | **说明** |
+| --- | --- | --- |
+| totalLikeCount | ValueListenable<int> | 当前直播间/语音聊天房的累计总点赞数，支持实时更新并可被订阅监听。 |
+
+### LikeListener
+
+点赞事件，用于接收直播间/语音聊天房内的点赞动态。
+
+此监听器用于接收直播间/语音聊天房内的点赞动态。
+
+**方法**
+
+**onReceiveLikesMessage**: 收到新点赞消息的事件回调。当直播间/语音聊天房内有其他观众发送点赞时，会触发该事件并返回相关信息。
+``` dart
+void Function(String liveID, int totalLikesReceived, LiveUserInfo sender)? onReceiveLikesMessage;
+
+LikeListener({this.onReceiveLikesMessage});
+```
+| **参数名** | **类型** | **说明** |
+| --- | --- | --- |
+| liveID | String | 直播间ID。 |
+| totalLikesReceived | int | 本次收到的新点赞数。 |
+| sender | LiveUserInfo | 点赞发送者信息。 |