@tencentcloud/sdk-mcp 1.3.8 → 1.4.0

package/resource/doc/livekit/core-sdk/voice/uni-app/voice-gift.md

@@ -0,0 +1,362 @@
+`GiftState` 是 `AtomicXCore` 中专门负责管理直播间礼物功能的模块。通过它，您可以为您的直播应用构建一套完整的礼物系统，实现丰富的营收和互动场景。
+| 礼物面板 | 弹幕礼物 | 全屏礼物 |
+| --- | --- | --- |
+|  |  |  |
+
+## 核心功能
+- **礼物列表获取**：从服务端拉取礼物面板所需的数据，包括礼物分类和礼物详情。
+
+- **发送礼物**：观众可以向主播发送选定的礼物，并附带数量。
+
+- **礼物事件广播**：实时接收房间内发生的礼物赠送事件，用于展示礼物动画和弹幕通知。
+
+## 实现步骤
+
+### 步骤1：组件集成
+
+> **说明：**
+>
+
+> 使用**礼物系统**要求开通TUILiveKit **多人连麦版**、**大规模直播版**，不同套餐中可配置的礼物数量有所不同，详细参见 功能与计费说明 中的**礼物系统**说明。
+>
+
+- **视频直播**：请参考 快速接入 集成 **AtomicXCore**，完成接入。
+
+- **语聊房**：请参考 快速接入 集成 **AtomicXCore**，完成接入。
+
+### 步骤2：初始化并监听礼物事件
+
+获取 `GiftState` 实例，并设置订阅者以接收礼物事件和礼物列表更新。
+
+#### 实现方式:
+1. **获取实例**：使用 `useGiftState(liveID)` 获取与当前直播间绑定的 `GiftState` 实例。
+
+2. **订阅事件**：使用 `addGiftListener` 以订阅 `'onReceiveGift'`事件。
+
+3. **监听状态**：监听 响应式数据`usableGifts `礼物列表，来驱动 `UI` 更新。
+
+#### 代码示例:
+``` typescript
+import { useGiftState } from "@/uni_modules/tuikit-atomic-x/state/GiftState";
+import { onMounted, watch } from 'vue';
+
+// liveID 是语聊房的唯一标识
+const liveID = 'your_live_id'; // 替换为实际的语聊房 liveID
+
+// 通过 liveID 获取 GiftState 的实例
+const { addGiftListener, usableGifts } = useGiftState(liveID);
+
+onMounted(() => {
+    addGiftListener(liveID, 'onReceiveGift', {
+       callback: (event) => {
+         const gift = JSON.parse(event)
+         console.log('收到礼物', gift)
+         // 在此进行礼物的处理逻辑，例如 svga 格式的礼物进行播放，其他格式的进行弹窗提示
+       }
+     })
+})
+
+// 监听 usableGifts 的实时变更，用于驱动 UI 变更
+watch(usableGifts, (newVal, oldVal) => {
+    console.log(newVal)
+})
+```
+
+#### 礼物列表结构体参数
+- `GiftCategory`**参数说明**
+
+| **参数** | **类型** | **描述** |
+| --- | --- | --- |
+| `categoryID` | `string` | 礼物分类的唯一 ID。 |
+| `name` | `string` | 礼物分类的显示名称。 |
+| `desc` | `string` | 礼物分类的描述信息。 |
+| `extensionInfo` | `[string: string]` | 扩展信息字段。 |
+| `giftList` | `[string]` | 该分类下包含的 Gift 礼物对象数组。 |
+
+- `Gift`** 参数说明**
+
+| **参数** | **类型** | **描述** |
+| --- | --- | --- |
+| `giftID` | `string` | 礼物的唯一 ID。 |
+| `name` | `string` | 礼物的显示名称。 |
+| `desc` | `string` | 礼物的描述信息。 |
+| `iconURL` | `string` | 礼物图标 URL。 |
+| `resourceURL` | `string` | 礼物动画资源 URL。 |
+| `level` | `number` | 礼物等级。 |
+| `coins` | `number` | 礼物价格。 |
+| `extensionInfo` | `[string: string]` | 扩展信息字段。 |
+
+### 步骤3：获取礼物列表
+
+调用 `refreshUsableGifts` 方法，从服务端拉取礼物数据。
+
+#### 实现方式:
+1. **调用接口**：在合适的时机（例如页面加载时）调用 `refreshUsableGifts()`。
+
+2. **处理回调**：可选地处理 `success`，`fail` 回调以获知拉取结果。
+
+3. **接收数据**：拉取成功后，通过步骤二中对 `usableGifts` 的监听，自动接收到更新后的 `usableGifts` 列表。
+
+#### 代码示例:
+``` typescript
+import { useGiftState } from "@/uni_modules/tuikit-atomic-x/state/GiftState";
+import { onMounted } from 'vue';
+
+// liveID 是语聊房的唯一标识
+const liveID = 'your_live_id'; // 替换为实际的语聊房 liveID
+
+// 通过 liveID 获取 GiftState 的实例
+const { addGiftListener, usableGifts } = useGiftState(liveID);
+
+onMounted(() => {
+    refreshUsableGifts({
+      liveID: 'xxx', // 当前直播间的 liveID
+      success: () => {
+        console.log('礼物列表拉取成功')
+        // 成功后，state 响应式数据会自动更新
+      },
+      faile: (error) => {
+        console.log('礼物列表拉取失败', error)
+      }
+    })
+})
+```
+
+### 步骤4：发送礼物
+
+当用户在礼物面板选择一个礼物并点击发送时，调用 `sendGift` 接口将礼物发送出去。
+
+#### 实现方式:
+1. **获取参数**：从 UI 获取用户选择的 `giftID` 和发送数量 `count`。
+
+2. **调用接口**：调用 `sendGift(giftID,count)`。
+
+3. **处理回调**：在 `fail` 回调中处理发送失败的情况（例如余额不足提示）；发送成功后的 UI 更新（动画、弹幕）应由 `'onReceiveGift'` 事件驱动。
+
+#### 代码示例:
+``` typescript
+
+import { useGiftState } from "@/uni_modules/tuikit-atomic-x/state/GiftState";
+
+// liveID 是语聊房的唯一标识
+const liveID = 'your_live_id'; // 替换为实际的语聊房 liveID
+
+// 通过 liveID 获取 GiftState 的实例
+const { sendGift } = useGiftState(liveID);
+
+// 用户发送一个礼物
+const sendGift = () => {
+    sendGift({
+      liveID: 'xxx', // 当前直播间 liveID
+      giftID: giftID,
+      count: 1,
+      success: () => {
+        console.log('礼物 ${giftID} 发送成功')
+      },
+      fail: (error) => {
+        console.log('礼物发送失败', error)
+        // 可以在此提示用户，例如“余额不足”或“网络错误”
+      },
+    })
+}
+```
+
+#### `sendGift`接口参数
+| **参数名** | **类型** | **描述** |
+| --- | --- | --- |
+| `liveID` | `string` | 当前直播间的`liveID`。 |
+| `giftID` | `string` | 要发送的礼物的唯一 ID。 |
+| `count` | `number` | 发送的数量。 |
+| `success` | `Function` | 发送成功的回调。 |
+| `fail` | `Function` | 发送失败的回调。 |
+
+## 功能进阶
+
+`GiftState` 的功能高度依赖于您的业务后台服务。本章将指导您如何通过服务端配置和客户端实现，构建功能丰富、体验卓越的礼物互动系统。
+
+### **礼物素材配置**
+
+您需要自定义直播间可用的礼物种类、分类、名称、图标、价格以及动画效果，以满足运营需求和品牌特色。
+
+#### **实现方式 **
+1. **服务端配置**：使用 LiveKit 服务端 REST API 管理礼物信息、分类、多语言等。请参考 [礼物配置指引文档](https://cloud.tencent.com/document/product/647/121321)。
+
+2. **客户端拉取**：在客户端调用 `refreshUsableGifts` 获取配置数据。
+
+3. **UI 展示**：使用拉取到的 `[GiftCategory]` 数据填充礼物面板。
+
+#### **配置时序图**
+
+#### **涉及 REST API 接口一览**
+| 接口分类 | 接口 | 请求示例 |
+| --- | --- | --- |
+| ​礼物管理​ | 添加礼物信息 | 请求示例 |
+| 删除礼物信息 | 请求示例 |  |
+| 查询礼物信息 | 请求示例 |  |
+| 礼物​分类管理​ | 添加礼物分类信息 | 请求示例 |
+| 删除指定礼物分类信息 | 请求示例 |  |
+| 获取指定礼物分类信息 | 请求示例 |  |
+| ​礼物关系管理​ | 添加指定礼物分类和礼物间的关系 | 请求示例 |
+| 删除指定礼物分类和礼物间的关系 | 请求示例 |  |
+| 获取指定礼物分类下的礼物关系 | 请求示例 |  |
+| ​礼物多语言​管理 | 添加礼物多语言信息 | 请求示例 |
+| 删除指定礼物多语言信息 | 请求示例 |  |
+| 获取礼物多语言信息 | 请求示例 |  |
+| 添加礼物分类多语言信息 | 请求示例 |  |
+| 删除指定礼物分类多语言信息 | 请求示例 |  |
+| 获取礼物分类多语言信息 | 请求示例 |  |
+
+### 计费与送礼扣费流程
+
+当观众赠送礼物时，需要确保其账户余额充足，并完成实际的扣费操作，然后才能触发礼物特效的播放和广播。
+
+#### 实现方式
+1. **后台配置回调**：在 LiveKit 后台配置您的自建计费系统的回调 URL。参考 回调配置文档。
+
+2. **客户端发送**：客户端调用 `sendGift`。
+
+3. **后台交互**：LiveKit 后台调用您的回调 URL，您的计费系统执行扣费并返回结果。
+
+4. **结果同步**：扣费成功，AtomicXCore 广播 `'onReceiveGift'` 事件。扣费失败，`sendGift` 的 `fail` 收到错误。
+
+#### 调用流程图
+
+#### 涉及 REST API 接口一览
+| 接口 | 说明 | 请求示例 |
+| --- | --- | --- |
+| 回调配置 - 发送礼物之前回调 | 客户后台可以通过该回调决定是否通过送礼前校验等场景 | 调用示例 |
+
+### 实现全屏礼物动画播放
+
+当直播间有用户（包括自己）发送了“火箭”、“嘉年华”等豪华礼物时，全屏播放一个酷炫的礼物动画（例如 SVGA 动画），营造热烈的氛围。
+
+#### 实现方式
+
+`AtomicXCore` 本身包含礼物动画播放器，您可以根据业务需求选择并集成第三方库。以下是两种方案的对比：
+| **对比项** | **内置方案 (SVGAPlayer)** | **高级方案 (TCEffectPlayerKit)** |
+| --- | --- | --- |
+| 计费 | 免费 | 付费 (需购买 License)，请参见 [付费指引](https://cloud.tencent.com/document/product/616/116461) |
+| 集成方式 | AtomicXCore 内置 | 需额外集成 TCEffectPlayerKit 并进行鉴权 |
+| 动画格式支持 | 仅支持 SVGA | SVGA、PAG、WebP、Lottie、MP4 等多种格式 |
+| 性能 | 建议 SVGA 文件 ≤ 10MB | 支持更大的动画文件，复杂特效/多动画并发/低端机表现更优 |
+| 推荐场景 | 礼物动画格式统一为 SVGA，且文件大小可控 | 需要支持多种动画格式，或对动画性能/设备兼容性有更高要求 |
+
+本章节主要演示基础方案的集成。如果您选择高级方案，请参考 [TCEffectPlayer 集成指引](https://cloud.tencent.com/document/product/616/116474)。
+
+#### 基础方案实现：使用 SVGAPlayer
+1. **使用 SVGAPlayer**：在您的项目中，引入 `svga-player `组件
+
+   ``` typescript
+   <svga-player :url="xxx"></svga-player>
+   ```
+2. **监听礼物事件**：使用 `addGiftListener` 以订阅 `'onReceiveGift'`事件。
+
+3. **解析并播放**：当收到 `'onReceiveGift'`事件时，检查 `gift.resourceURL`是否有效且指向一个 SVGA 文件。如果是，则将`gift.resourceURL`传给`svga-player` 进行播放
+
+#### 代码示例
+``` typescript
+<template>
+    <svga-player :url="giftUrl"></svga-player>
+</template>
+
+<script setup lang="ts">
+import { useGiftState } from "@/uni_modules/tuikit-atomic-x/state/GiftState";
+import { onMounted } from 'vue';
+
+// 通过 liveID 获取 GiftState 的实例
+const { addGiftListener } = useGiftState(liveID);
+const giftUrl = ref('')
+
+onMounted(() => {
+    addGiftListener(liveID, 'onReceiveGift', {
+       callback: (event) => {
+         const gift = JSON.parse(event)
+         if( gift.resourceURL ) {
+           giftUrl.value = gift.resourceURL
+         }
+       }
+     })
+})
+</script>
+
+```
+
+### 在弹幕区展示礼物赠送消息
+
+当有用户发送礼物时，不仅播放动画，同时在公屏弹幕区域显示一条系统消息，例如：“【观众昵称】送出了【礼物名称】x【数量】”，让所有观众都能看到。
+
+#### 实现方式
+1. **监听事件: **使用 `addGiftListener` 以订阅 `'onReceiveGift'`事件。
+
+2. **获取弹幕 State**：使用 `useBarrageState(liveID)`获取与当前房间绑定的实例。
+
+3. **拼接消息**：创建一条消息结构体，设置 `messageType = 'text'`，textContent 为拼接好的字符串（例如 “[`sender.userName`] 送出了 [`gift.name`] x [`count`]”）。
+
+4. **本地插入**：调用 `barrageState`的`appendLocalTip(message: giftTip) `将消息插入本地列表。
+
+#### 代码示例
+``` typescript
+import { useGiftState } from "@/uni_modules/tuikit-atomic-x/state/GiftState";
+import { useBarrageState } from "@/uni_modules/tuikit-atomic-x/state/BarrageState";
+import { onMounted } from 'vue';
+
+// 通过 liveID 获取 GiftState 的实例
+const { addGiftListener } = useGiftState(liveID);
+// 通过 liveID 获取 BarrageState 的实例
+const { appendLocalTip } = useBarrageState(liveID);
+
+onMounted(() => {
+    addGiftListener(liveID, 'onReceiveGift', {
+       callback: (event) => {
+         const gift = JSON.parse(event)
+         let giftTip = {}
+         const tipText = "${ gift.sender.userName } 送出了 ${gift.name} x ${gift.count}"
+         giftTip.messageType = 'text'
+         giftTip.textContent = tipText
+         appendLocalTip({
+           liveID: 'xxx', // 当前直播间 liveID
+           message: giftTip
+         })
+         if( gift.resourceURL ) {
+           giftUrl.value = gift.resourceURL
+         }
+       }
+     })
+})
+</script>
+```
+
+## API 文档
+
+关于 [GiftState](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-GiftState) 及其相关类的所有公开接口、属性和方法的详细信息，请参阅随 AtomicXCore 框架的官方 API 文档。本指南使用到的相关 Store 如下：
+| **State** | **功能描述** | **API 文档** |
+| --- | --- | --- |
+| GiftState | 礼物互动：获取礼物列表，发送 / 接收礼物，监听礼物事件（含发送者、礼物详情）。 | [API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-GiftState) |
+| BarrageState | 弹幕功能：发送文本 / 自定义弹幕，维护弹幕列表，实时监听弹幕状态。 | [API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-BarrageState) |
+
+## 常见问题
+
+### `GiftState` 的礼物列表是空的，我该怎么办？
+
+您必须主动调用 `refreshUsableGifts()`来从您的业务后台拉取礼物数据。这些礼物数据需要在您的业务后台通过服务端 REST API 进行配置。
+
+### 如何实现礼物的多语言展示（例如中文、英文）？
+
+`GiftState` 提供了 `setLanguage(language: string)`接口。您可以在 `refreshUsableGifts` 之前调用此方法，传入目标语言代码（例如 "en" 或 "zh-CN"）。服务端会根据此语言代码，返回对应语言的礼物名称和描述。
+
+### 我调用 sendGift 发送了礼物，礼物动画为什么重复播放了两次？
+
+`onReceiveGift` 事件是对房间内所有成员的广播（包括发送者自己）。如果您在 `sendGift` 的 `success` 成功回调里执行了一次UI操作，同时又在 `onReceiveGift` 订阅中执行了相同的 UI 操作，就会造成重复。
+- **实践教程**：UI 的更新（例如播放动画、弹幕提示）只在 `onReceiveGift` 事件的订阅中处理。`sendGift` 的 `success` 回调仅用于处理发送失败的逻辑（例如提示用户“发送失败”或“余额不足”）。
+
+### 礼物扣费逻辑在哪里实现？
+
+礼物扣费逻辑完全由您的自建计费系统负责。`AtomicXCore` 通过后台回调机制与您的计费系统对接。客户端调用 `sendGift` 触发回调，您的后台服务完成扣费后，将结果返回给 `AtomicXCore` 后台，从而决定礼物事件是否广播。
+
+### 送礼通知会被禁言或频控拦截吗？
+
+不会。送礼通知（`'onReceiveGift'`事件）不受禁言或消息频控影响，确保可靠投递。
+
+### 礼物动画播放卡顿怎么办？
+
+请检查您的 `SVGA` 文件大小，基础播放器建议不要超过 10MB。如果文件过大或动画复杂，您可以考虑集成 `TUILiveKit` 提供的高级特效播放器，以获得更优的性能表现。

package/resource/doc/livekit/core-sdk/voice/uni-app/voice-integration.md

@@ -0,0 +1,323 @@
+本文档将帮助开发者使用 `AtomicXCore SDK` 的 `LiveListState` 和 `LiveSeatState` 快速构建一个包含主播开播和观众进房功能的语聊房 `App`。
+
+## 准备工作
+
+### 步骤 1. 开通服务
+
+请参见 开通服务，获取体验版或付费版 SDK。
+
+### 步骤2. 导入 tuikit-atomic-x
+1. **安装组件**：打开 [AtomicXCore SDK](https://ext.dcloud.net.cn/plugin?id=25488) ，单击**下载插件并导入HBuilderX**，选择需要集成的项目并单击**确定**。
+
+2. **配置工程权限:  **请在应用的 manifest.json 文件的app-plus > distribute 节点下，确保添加了以下必要的权限：
+
+  - Android 平台（`android`节点）：在 `permissions` 数组中，请确保包含以下权限：
+
+      ``` json
+      "<uses-permission android:name=\"android.permission.RECORD_AUDIO\" />"
+      ```
+  - iOS 平台（ios 节点）：在 `privacyDescription` 对象中，请确保包含以下描述：
+
+      ``` json
+      "NSMicrophoneUsageDescription" : "应用需要访问您的麦克风以进行直播"
+      ```
+
+      在 `UIBackgroundModes` 数组中，添加 `audio` 以支持后台播放音频。
+
+      ``` json
+      "UIBackgroundModes" : [ "audio" ]
+      ```
+
+### 步骤 3. 完成登录
+
+在您的项目中调用 LoginState 中的 login 方法完成登录，**这是使用 **`AtomicXCore`** 所有功能的关键前提**。
+
+> **重要：**
+>
+
+> 推荐在您 App 自身的用户账户登录成功后，再调用 LoginState 中的 login 方法，以确保登录业务逻辑的清晰和一致。
+>
+
+``` typescript
+import { useLoginState } from "@/uni_modules/tuikit-atomic-x/state/LoginState";
+
+const { login } = useLoginState();
+
+const handleLogin = () => {
+    login({
+      sdkAppID: 1400000001,  // 替换为您的 SDKAppID
+      userID: "test_001",    // 替换为您的 UserID
+      userSig: "xxxxxxxxxx"  // 替换为您的 UserSig
+    })
+ }
+```
+
+**登录接口参数说明：**
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| sdkAppID | number | 从 [控制台](https://console.cloud.tencent.com/trtc)获取，通常是以 `140` 或 `160` 开头的 10 位整数。 |
+| userID | string | 当前用户的唯一 ID，仅包含英文字母、数字、连字符和下划线。为避免多端登录冲突，**请勿使用**`1`、`123`**等简单 ID**。 |
+| userSig | string | 用于腾讯云鉴权的票据。请注意：<br>- 开发环境：您可以采用本地 `GenerateTestUserSig.genTestSig` 函数生成 userSig 或者 通过 [UserSig 辅助工具](https://console.cloud.tencent.com/im/tool-usersig) 生成临时的 UserSig。<br>- 生产环境：为了防止密钥泄露，请务必采用服务端生成 UserSig 的方式。详细信息请参考 [服务端生成 UserSig](https://cloud.tencent.com/document/product/647/17275)。<br>更多信息请参见 [如何计算及使用 UserSig](https://cloud.tencent.com/document/product/647/17275)。 |
+
+## 搭建语音聊天室
+
+### 步骤1：实现房主创建语聊房
+
+房主开播流程如下，您只需执行以下几步操作，即可快速搭建一个语聊房。
+
+#### **1. 初始化麦位 **`State`
+
+在您的房主页面中，创建一个 `LiveSeatState` 实例。您需要监听响应式数据的变化，以实时获取麦位数据来渲染您的 `UI`。
+``` typescript
+import { watch } from 'vue';
+import { useLiveSeatState } from '@/uni_modules/tuikit-atomic-x/state/LiveSeatState';
+
+// 定义直播间 ID（需要与后续 createLive 中使用的 liveID 保持一致）
+const liveID = 'your_live_room_id'; // 替换为您的直播间 ID
+
+// 使用 liveID 获取 LiveSeatState 实例
+const { seatList } = useLiveSeatState(liveID);
+```
+
+#### **2. 打开麦克风**
+
+通过调用 `DeviceState` 的 `openLocalMicrophone` 接口打开麦克风，示例代码如下：
+``` typescript
+import { useDeviceState } from "@/uni_modules/tuikit-atomic-x/state/DeviceState";
+
+const { openLocalMicrophone } = useDeviceState();
+
+const openMic = () => {
+    openLocalMicrophone()
+}
+```
+
+#### **3. 开始语聊**
+
+通过调用 `LiveListState` 的 `createLive` 接口开始语聊房直播，完整示例代码如下：
+``` typescript
+import { useLiveListState } from '@/uni_modules/tuikit-atomic-x/state/LiveListState';
+
+// 获取 LiveListState 实例
+const { createLive } = useLiveListState();
+
+// 开始直播
+const startLive = () => {
+    createLive({
+      liveInfo: {
+        liveID: 'xxx', // 设置直播的房间 id
+        liveName: 'text', // 设置直播的房间名称
+        keepOwnerOnSeat: true, // 配置主播始终在麦位上
+        isSeatEnabled: true,
+        seatLayoutTemplateID: 70, // 麦位布局模板（例如 70 为 10 麦位模板）
+        seatMode: 'APPLY' // 上麦模式，例如申请上麦
+        maxSeatCount: 10 // 最大麦位数
+      },
+      success: () => {
+        console.log('创建直播间成功')
+        //您可以在这里进行页面的跳转
+      },
+      fail: (error) => {
+        console.log('创建直播间失败', error)
+      }
+    });
+  };
+```
+
+`LiveInfo`**参数说明:**
+| **参数名** | **类型** | **属性** | **描述** |
+| --- | --- | --- | --- |
+| `liveID` | `string` | 必填 | 直播间的唯一标识符 |
+| `liveName` | `string` | 选填 | 直播间的标题 |
+| `notice` | `string` | 选填 | 直播间的公告信息 |
+| `isMessageDisable` | `boolean` | 选填 | 是否禁言（`true`：是，`false`：否） |
+| `isPublicVisible` | `boolean` | 选填 | 是否公开可见（`true`：是，`false`：否） |
+| `isSeatEnabled` | `boolean` | 选填 | 是否启用麦位功能（`true`：是，`false`：否） |
+| `keepOwnerOnSeat` | `boolean` | 选填 | 是否保持房主在麦位上 |
+| `maxSeatCount` | `number` | 必填 | 最大麦位数量 |
+| `seatMode` | `string` | 选填 | 上麦模式（`'FREE'`：自由上麦，`'APPLY'`：申请上麦） |
+| `seatLayoutTemplateID` | `number` | 必填 | 麦位布局模板 `ID` |
+| `coverURL` | `string` | 选填 | 直播间的封面图片地址 |
+| `backgroundURL` | `string` | 选填 | 直播间的背景图片地址 |
+| `activityStatus` | `number` | 选填 | 直播活动状态 |
+| `isGiftEnabled` | `boolean` | 选填 | 是否启用礼物功能（`true`：是，`false`：否） |
+
+#### **4. 构建麦位 UI 界面**
+
+通过 `LiveSeatState` 实例，监听 `seatList` 的变化，以实时获取麦位数据来渲染您的界面 UI 。您可以在主播页通过以下方式监听数据：
+``` typescript
+import { watch } from 'vue';
+import { useLiveSeatState } from '@/uni_modules/tuikit-atomic-x/state/LiveSeatState';
+
+// 使用 liveID 获取 LiveSeatState 实例
+const { seatList } = useLiveSeatState(liveID);
+
+watch( seatList ,(newSeatList) => {
+    console.log('新的麦位列表', newSeatList)
+    // 用这个数据来维护您的 UI
+})
+```
+
+#### **5. 结束语聊**
+
+语聊结束后，房主可以调用 `LiveListState` 的 `endLive` 接口结束语聊，`SDK` 会处理停止推流和销毁房间的逻辑。
+``` typescript
+import { useLiveListState } from '@/uni_modules/tuikit-atomic-x/state/LiveListState';
+
+// 获取 LiveListState 实例
+const { endLive } = useLiveListState();
+
+// 结束直播
+const handleEndLive = () => {
+    endLive({
+      success: () => {
+        console.log('结束直播成功')
+        //您可以在这里进行页面的跳转
+      },
+      fail: (error) => {
+        console.log('结束直播失败', error)
+      }
+    });
+ }
+```
+
+### 步骤2：实现观众进入语聊房
+
+观众进房流程如下，通过简单几步操作，即可实现观众进入语聊房
+
+#### **1. 初始化麦位 **`State`
+
+在您的观众页面 中，创建 `LiveSeatState` 实例，并监听 `seatList` 的变化，以渲染麦位 `UI` 。
+``` typescript
+import { watch } from 'vue';
+import { useLiveSeatState } from '@/uni_modules/tuikit-atomic-x/state/LiveSeatState';
+
+// 观众进房前，需要先获取要加入的直播间 ID（liveID）。通常有以下几种方式：
+// 通过房间列表选择（可从 LiveListState 的 liveList 数据中获取）
+// 使用 liveID 获取 LiveSeatState 实例
+const { seatList } = useLiveSeatState(liveID);
+
+watch(seatList,(newSeatList) => {
+    console.log('新的麦位列表', newSeatList)
+    // 用这个数据来维护您的 UI
+})
+```
+
+#### **2. 进入语聊房**
+
+通过调用 `LiveListState` 的 `joinLive` 接口加入语聊房，完整示例代码如下：
+``` typescript
+import { useLiveListState } from '@/uni_modules/tuikit-atomic-x/state/LiveListState';
+
+// 获取 LiveListState 实例
+const { joinLive } = useLiveListState();
+
+// 加入直播
+const handleJoinLive = () => {
+    joinLive({
+      liveID: 'xxx', // 想要加入语聊房的 liveID
+      success: () => {
+        console.log('成功进入语聊房')
+        //您可以在这里进行页面的跳转
+      },
+      fail: (error) => {
+        console.log('进入语聊房失败', error)
+      }
+    });
+ }
+```
+
+#### **3. 构建麦位 UI 界面**
+
+观众构建麦位 UI的流程与主播完全一致，请参考主播 构建麦位 UI 界面
+
+#### **4. 退出语聊房**
+
+观众退出语聊房时，需要调用 `LiveListState` 的 `leaveLive` 接口来退出。
+``` typescript
+
+import { useLiveListState } from '@/uni_modules/tuikit-atomic-x/state/LiveListState';
+
+// 获取 LiveListState 实例
+const { leaveLive } = useLiveListState();
+
+// 退出语聊房
+const handleLeaveLive = () => {
+    leaveLive({
+      liveID: 'xxx', // 您当前加入语聊房的 liveID
+      success: () => {
+        console.log('退出语聊房成功')
+        //您可以在这里进行页面的跳转
+      },
+      fail: (error) => {
+        console.log('退出语聊房失败', error)
+      }
+    });
+ }
+```
+
+### 运行效果
+
+完成上述步骤后，即可完成一个最基础的语聊直播场景。您可以参考 丰富语聊场景 来完善语聊场景。
+
+## 功能进阶
+
+### **实现麦上用户说话音浪**
+
+在语聊房场景中，一个常见的需求是当麦上用户说话时，在其头像上显示一个波浪动画，以提示全房间用户“谁在说话”，`LiveSeatState` 提供了 `speakingUsers` 数据流，专门用于实现此功能。
+
+#### 实现效果
+
+在您构建的麦位 UI 界面中监听 `speakingUsers` 变化，并更新“正在说话”状态，代码示例如下
+``` typescript
+import { watch } from 'vue';
+import { useLiveSeatState } from '@/uni_modules/tuikit-atomic-x/state/LiveSeatState';
+
+// 使用 liveID 获取 LiveSeatState 实例
+const { speakingUsers } = useLiveSeatState(liveID);
+
+watch(speakingUsers,(newSpeaker) => {
+    console.log('正在说话的人', newSpeaker)
+    // 用这个数据和之前监听的 seatList 进行匹配来更新 UI
+})
+```
+
+## 丰富语音聊天室场景
+
+当您完成了基础的语音聊天室功能后，您可以参考以下功能指南来为语音聊天室添加丰富的互动玩法。
+| **语音聊天室功能** | **功能介绍** | **功能 State** | **实现指南** |
+| --- | --- | --- | --- |
+| **实现观众音频连麦** | 观众申请上麦，与主播进行实时音频互动。 | [CoGuestState](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-CoGuestState) | 实现观众连麦 |
+| **添加弹幕聊天功能** | 观众可以在语音聊天室发送和接收实时文字消息。 | [BarrageState](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-BarrageState) | 实现弹幕功能 |
+| **构建礼物赠送系统** | 观众可以向主播赠送虚拟礼物，增加互动和趣味性。 | [GiftState](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-GiftState) | 实现礼物功能 |
+| **添加设置音效功能** | 变声（童声 / 男声）、混响（KTV 等）、耳返调节，实时切换特效。 | [AudioEffectState](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-AudioEffectState) | 实现音效功能 |
+
+##  API 文档
+| **State** | **功能描述** | **API 文档** |
+| --- | --- | --- |
+| **LiveListState** | 语音聊天室全生命周期管理：创建 / 加入 / 离开 / 销毁房间，查询房间列表，修改语音聊天室信息（名称、公告等），监听语音聊天室状态（如被踢出、结束）。 | [API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-LiveListState) |
+| **DeviceState** | 音视频设备控制：麦克风（开关 / 音量），设备状态实时监听。 | [API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-DeviceState) |
+| **CoGuestState** | 观众连麦管理：连麦申请 / 邀请 / 同意 / 拒绝，连麦成员权限控制（麦克风），状态同步。 | [API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-CoGuestState) |
+| **CoHostState** | 主播跨房连线：支持多布局模板（动态网格等），发起 / 接受 / 拒绝连线，连麦主播互动管理。 | [API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-CoHostState) |
+| **GiftState** | 礼物互动：获取礼物列表，发送 / 接收礼物，监听礼物事件（含发送者、礼物详情）。 | [API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-GiftState) |
+| **BarrageState** | 弹幕功能：发送文本 / 自定义弹幕，维护弹幕列表，实时监听弹幕状态。 | [API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-BarrageState) |
+| **LikeState** | 点赞互动：发送点赞，监听点赞事件，同步总点赞数。 | [API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-LikeState) |
+| **LiveAudienceState** | 观众管理：获取实时观众列表（ ID / 名称 / 头像），统计观众数量，监听观众进出事件。 | [API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-LiveAudienceState) |
+| **AudioEffectState** | 音频特效：变声（童声 / 男声）、混响（ KTV 等）、耳返调节，实时切换特效。 | [API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-AudioEffectState) |
+
+## 常见问题
+
+### 代码变更后，没有效果或者编译报错？
+
+引入 uni_modules 后，需要重新制作自定义基座，详情参见 制作自定义基座流程。
+
+### 原生能力集成问题
+- 问题：插件调用失败或无响应。
+
+- 解决方案：
+
+  - 必须打包自定义基座：在开发调试原生插件时，不能使用标准基座，必须通过 `HBuilderX` > 运行 > 运行到手机或模拟器 > 制作自定义基座，然后选择这个自定义基座来运行。
+
+  - 检查权限：如本文档“准备工作”中所述，`manifest.json` manifest.json必须声明相机、麦克风等权限。
+
+  - 查看原生日志：这是终极调试手段。通过 `Android Studio (Logcat)` 或 `Xcode (Console)` 查看设备的原生日志，通常能发现最直接的错误信息。