@tencentcloud/sdk-mcp 1.3.9 → 1.4.0

package/resource/doc/livekit/{voice → core-sdk/voice}/flutter/voice-co-guest-interaction.md

@@ -1,8 +1,5 @@
 **AtomicXCore** 提供了 [CoGuestStore](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_co_guest_store/CoGuestStore-class.html) 和 [LiveSeatStore](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_seat_store/LiveSeatStore-class.html) 模块，用于管理观众连麦的完整业务流程。用户无需关心复杂的状态同步和信令交互，只需调用几个简单的方法，即可为您的直播添加强大的观众与主播音视频互动功能。本文档将指导您如何使用 `CoGuestStore` 和 `LiveSeatStore` 在 Flutter 应用中快速实现语音连麦功能。
 
-![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100032457995/7dd898d8df3411f08a7a52540099c741.png)
-
-
 ## 核心场景
 
 `CoGuestStore` 和 `LiveSeatStore` 支持以下几个主流的场景：
@@ -12,22 +9,20 @@
 
 - **主播管理麦位**：主播可以对麦位上的用户进行强制下麦、闭麦、锁麦等操作。
 
-
 ## 实现步骤
 
 ### 步骤1：组件集成
 
-请参考 [快速接入](https://write.woa.com/document/197478016886185984) 集成 **AtomicXCore**。
+请参考 快速接入 集成 **AtomicXCore**。
 
 > **说明：**
-> 
+>
 
 > 在开始实现连麦功能之前，您需要获取 `liveId`（直播间唯一标识），用于区分不同的直播房间。获取方式如下
-> 
+>
 > - **主播端**：通过 `LiveListStore.shared.createLive(liveInfo)` 创建直播时指定。
 > - **观众端**：通过`LiveListState.liveList.value`中的 `liveInfo` 获取，或由主播分享直播间 ID 获取。
 
-
 ### 步骤2：实现观众申请上麦
 
 #### 观众端实现
@@ -35,21 +30,20 @@
 观众端的核心任务是**发起申请、接收结果**和**主动下麦**。
 1. **发起连麦申请**
 
-
    当用户点击界面上的"申请连麦"按钮时，调用 `applyForSeat` 方法。
 
    ``` java
    import 'package:atomic_x_core/atomicxcore.dart';
-   
+
    final String liveId = "房间ID";
    late CoGuestStore guestStore;
-   
+
    @override
    void initState() {
      super.initState();
      guestStore = CoGuestStore.create(liveId);
    }
-   
+
    // 用户点击"申请连麦"
    Future<void> requestToConnect() async {
      // seatIndex: 麦位索引，从 0 开始,表示要申请的麦位位置。0 表示第一个麦位。可通过 LiveSeatState.seatList.value 查看麦位状态,选择空闲的麦位
@@ -69,12 +63,11 @@
    ```
 2. **监听主播的处理结果**
 
-
    通过添加 `GuestListener`，您可以接收到主播的处理结果。
 
    ``` java
    late GuestListener _guestListener;
-   
+
    // 在您的 Widget 初始化时订阅事件
    void subscribeGuestEvents() {
      _guestListener = GuestListener(
@@ -94,7 +87,7 @@
      );
      guestStore.addGuestListener(_guestListener);
    }
-   
+
    @override
    void dispose() {
      guestStore.removeGuestListener(_guestListener);
@@ -103,7 +96,6 @@
    ```
 3. **主动下麦**
 
-
    当连麦观众想结束互动时，调用 `disconnect` 方法即可返回普通观众状态。
 
    ``` java
@@ -119,7 +111,6 @@
    ```
 4. **(可选) 取消申请**
 
-
    如果观众在主播处理前想撤回申请，可以调用 `cancelApplication`。
 
    ``` java
@@ -139,21 +130,20 @@
 作为主播，您的核心任务是**接收申请、展示申请列表**和**处理申请**。
 1. **监听新的连麦申请**
 
-
    通过添加 `HostListener`，您可以在有新观众申请时立即收到通知，并给出提示。
 
    ``` java
    import 'package:atomic_x_core/atomicxcore.dart';
-   
+
    final String liveId = "房间ID";
    late CoGuestStore guestStore;
    late HostListener _hostListener;
-   
+
    @override
    void initState() {
      super.initState();
      guestStore = CoGuestStore.create(liveId);
-   
+
      // 订阅主播事件
      _hostListener = HostListener(
        onGuestApplicationReceived: (guestUser) {
@@ -163,7 +153,7 @@
      );
      guestStore.addHostListener(_hostListener);
    }
-   
+
    @override
    void dispose() {
      guestStore.removeHostListener(_hostListener);
@@ -172,23 +162,22 @@
    ```
 2. **展示申请列表**
 
-
    `CoGuestStore` 的 `coGuestState` 会实时维护当前的申请者列表，您可以订阅它来刷新您的 UI。
 
    ``` java
    late final VoidCallback _applicantsListener = _onApplicantsChanged;
-   
+
    // 订阅状态变更
    void subscribeApplicants() {
      guestStore.coGuestState.applicants.addListener(_applicantsListener);
    }
-   
+
    void _onApplicantsChanged() {
      final applicants = guestStore.coGuestState.applicants.value;
      debugPrint('当前申请人数: ${applicants.length}');
      // 在此刷新您的"申请者列表" UI
    }
-   
+
    @override
    void dispose() {
      guestStore.coGuestState.applicants.removeListener(_applicantsListener);
@@ -197,7 +186,6 @@
    ```
 3. **处理连麦申请**
 
-
    当您在列表中选择一位观众并点击"同意"或"拒绝"时，调用相应的方法。
 
    ``` java
@@ -208,7 +196,7 @@
        debugPrint('已同意 $userId 的申请，对方正在上麦');
      }
    }
-   
+
    // 主播点击"拒绝"按钮
    Future<void> reject(String userId) async {
      final result = await guestStore.rejectApplication(userId);
@@ -223,7 +211,6 @@
 #### 主播端实现
 1. **向观众发起邀请**
 
-
    当主播在观众列表中选择某人并点击"邀请连麦"时，调用 `inviteToSeat` 方法。
 
    ``` java
@@ -243,7 +230,6 @@
    ```
 2. **监听观众的回应**
 
-
    通过 `HostListener` 监听 `onHostInvitationResponded` 事件。
 
    ``` java
@@ -262,7 +248,6 @@
 #### 观众端实现
 1. **接收主播的邀请**
 
-
    通过 `GuestListener` 监听 `onHostInvitationReceived` 事件。
 
    ``` java
@@ -277,12 +262,11 @@
    ```
 2. **响应邀请**
 
-
    当用户在弹出的对话框中做出选择后，调用相应的方法。
 
    ``` java
    final String inviterId = "发起邀请的主播 ID"; // 从 onHostInvitationReceived 事件中获取
-   
+
    // 用户点击"接受"
    Future<void> accept() async {
      final result = await guestStore.acceptInvitation(inviterId);
@@ -293,7 +277,7 @@
        DeviceStore.shared.openLocalMicrophone();
      }
    }
-   
+
    // 用户点击"拒绝"
    Future<void> reject() async {
      await guestStore.rejectInvitation(inviterId);
@@ -311,7 +295,6 @@
 
 - **LiveSeatStore**：管理麦位业务（即音频流）。`muteMicrophone` 静音，停止向远端发送本地的音频流，但麦克风设备本身仍在运行；`unmuteMicrophone` 解除静音，恢复向远端发送音频流。
 
-
    **推荐的工作流程**：您应该遵循"设备只开一次，麦上只用静音切换"的原则
 
 1. **上麦时**：当观众成功上麦，调用一次 `openLocalMicrophone` 来启动设备。
@@ -320,7 +303,6 @@
 
 3. **下麦时**：当用户下麦（例如调用 `disconnect`），调用 `closeLocalMicrophone` 来释放设备。
 
-
 ### 麦上用户自行开/关麦
 
 麦上用户（包括主播自己）可以通过 `LiveSeatStore` 提供的接口来控制自己的麦克风静音状态。
@@ -330,7 +312,6 @@
 
 2. **解除静音**：调用 `unmuteMicrophone()` 方法。
 
-
 #### 示例代码：
 ``` java
 final seatStore = LiveSeatStore.create(liveId);
@@ -351,7 +332,6 @@ await seatStore.unmuteMicrophone(); // 解除静音
 
 3. **用户自行开麦**：用户在收到"解除锁定"的通知后，必须主动调用 `LiveSeatStore` 的 `unmuteMicrophone()` 方法解除静音，才能让房间内其他人听到自己的声音。
 
-
 #### 示例代码：
 
 ##### 主播端：
@@ -403,52 +383,15 @@ void dispose() {
 ```
 
 #### closeRemoteMicrophone 接口参数：
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >**参数**</td>
-
-<td rowspan="1" colSpan="1" >**类型**</td>
-
-<td rowspan="1" colSpan="1" >**描述**</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`userID`</td>
-
-<td rowspan="1" colSpan="1" >`String`</td>
-
-<td rowspan="1" colSpan="1" >被操作的用户 `userID`。</td>
-</tr>
-</table>
-
+| **参数** | **类型** | **描述** |
+| --- | --- | --- |
+| `userID` | `String` | 被操作的用户 `userID`。 |
 
 #### openRemoteMicrophone 接口参数：
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >**参数**</td>
-
-<td rowspan="1" colSpan="1" >**类型**</td>
-
-<td rowspan="1" colSpan="1" >**描述**</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`userID`</td>
-
-<td rowspan="1" colSpan="1" >`String`</td>
-
-<td rowspan="1" colSpan="1" >被操作的用户 `userID`。</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`policy`</td>
-
-<td rowspan="1" colSpan="1" >`DeviceControlPolicy`</td>
-
-<td rowspan="1" colSpan="1" >打开麦克风的策略。</td>
-</tr>
-</table>
-
+| **参数** | **类型** | **描述** |
+| --- | --- | --- |
+| `userID` | `String` | 被操作的用户 `userID`。 |
+| `policy` | `DeviceControlPolicy` | 打开麦克风的策略。 |
 
 ### 主播将麦上用户踢下麦位
 
@@ -457,7 +400,6 @@ void dispose() {
 
 2. **监听事件通知**：被踢下麦的用户会收到 `GuestListener` 中的 `onKickedOffSeat` 事件通知。
 
-
 #### 示例代码：
 ``` java
 // 假设要踢走 "userB"
@@ -479,24 +421,9 @@ _guestListener = GuestListener(
 ```
 
 #### kickUserOutOfSeat 接口参数：
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >**参数**</td>
-
-<td rowspan="1" colSpan="1" >**类型**</td>
-
-<td rowspan="1" colSpan="1" >**描述**</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`userID`</td>
-
-<td rowspan="1" colSpan="1" >`String`</td>
-
-<td rowspan="1" colSpan="1" >被踢下麦的用户 `userID`。</td>
-</tr>
-</table>
-
+| **参数** | **类型** | **描述** |
+| --- | --- | --- |
+| `userID` | `String` | 被踢下麦的用户 `userID`。 |
 
 ### 主播锁定和解锁麦位
 
@@ -507,7 +434,6 @@ _guestListener = GuestListener(
 
 2. **解锁麦位**：调用 `unlockSeat` 可以解锁麦位，解锁后该麦位可以再次被占用。
 
-
 #### 示例代码：
 ``` java
 // 锁定 2 号麦位
@@ -524,55 +450,24 @@ if (result2.isSuccess) {
 ```
 
 #### lockSeat 接口参数：
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >**参数**</td>
-
-<td rowspan="1" colSpan="1" >**类型**</td>
-
-<td rowspan="1" colSpan="1" >**描述**</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`seatIndex`</td>
-
-<td rowspan="1" colSpan="1" >`int`</td>
-
-<td rowspan="1" colSpan="1" >需要锁定的麦位索引。</td>
-</tr>
-</table>
-
+| **参数** | **类型** | **描述** |
+| --- | --- | --- |
+| `seatIndex` | `int` | 需要锁定的麦位索引。 |
 
 #### unlockSeat 接口参数：
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >**参数**</td>
-
-<td rowspan="1" colSpan="1" >**类型**</td>
-
-<td rowspan="1" colSpan="1" >**描述**</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`seatIndex`</td>
-
-<td rowspan="1" colSpan="1" >`int`</td>
-
-<td rowspan="1" colSpan="1" >需要解锁的麦位索引。</td>
-</tr>
-</table>
-
+| **参数** | **类型** | **描述** |
+| --- | --- | --- |
+| `seatIndex` | `int` | 需要解锁的麦位索引。 |
 
 ### 移动麦位
 
 主播和普通上麦用户可以调用 `moveUserToSeat` 移动麦位。
 
 #### 实现方式：
-1. **主播移动麦位**：主播可以调用此接口将任意用户移动到指定麦位。此时 `userID` 传入目标用户的 ID，`targetIndex` 是目标麦位索引，`policy` 参数来指定如果目标麦位有人时的移动策略，详细参见 [接口参数](https://write.woa.com/#moveusertoseat-.E6.8E.A5.E5.8F.A3.E5.8F.82.E6.95.B0.EF.BC.9A) 说明。
+1. **主播移动麦位**：主播可以调用此接口将任意用户移动到指定麦位。此时 `userID` 传入目标用户的 ID，`targetIndex` 是目标麦位索引，`policy` 参数来指定如果目标麦位有人时的移动策略，详细参见 接口参数 说明。
 
 2. **普通上麦用户移动自己麦位**：普通上麦用户也可以调用此接口来移动自己。此时 `userID` 必须传入用户自己的 ID，`targetIndex` 传入想去的新麦位索引，此时 `policy` 参数无效，如果目标麦位有人时会报错并停止移动。
 
-
 #### 示例代码：
 ``` java
 final result = await seatStore.moveUserToSeat(
@@ -588,70 +483,19 @@ if (result.isSuccess) {
 ```
 
 #### moveUserToSeat 接口参数：
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >**参数**</td>
-
-<td rowspan="1" colSpan="1" >**类型**</td>
-
-<td rowspan="1" colSpan="1" >**描述**</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`userID`</td>
-
-<td rowspan="1" colSpan="1" >`String`</td>
-
-<td rowspan="1" colSpan="1" >需要移麦的用户 `userID`。</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`targetIndex`</td>
-
-<td rowspan="1" colSpan="1" >`int`</td>
-
-<td rowspan="1" colSpan="1" >目标麦位索引。</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`policy`</td>
-
-<td rowspan="1" colSpan="1" >`MoveSeatPolicy`</td>
-
-<td rowspan="1" colSpan="1" >目标麦位已被占用时的处理策略:<br>- `abortWhenOccupied`：目标麦位有人时放弃移动（默认策略）<br>- `forceReplace`：强制替换目标麦位上的用户，被替换的用户将会被踢下麦。<br>- `swapPosition`：与目标麦位用户交换。</td>
-</tr>
-</table>
-
+| **参数** | **类型** | **描述** |
+| --- | --- | --- |
+| `userID` | `String` | 需要移麦的用户 `userID`。 |
+| `targetIndex` | `int` | 目标麦位索引。 |
+| `policy` | `MoveSeatPolicy` | 目标麦位已被占用时的处理策略:<br>- `abortWhenOccupied`：目标麦位有人时放弃移动（默认策略）<br>- `forceReplace`：强制替换目标麦位上的用户，被替换的用户将会被踢下麦。<br>- `swapPosition`：与目标麦位用户交换。 |
 
 ## API 文档
 
 关于 [CoGuestStore](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_co_guest_store/CoGuestStore-class.html) 和 [LiveSeatStore](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_seat_store/LiveSeatStore-class.html) 及其相关类的所有公开接口、属性和方法的详细信息，请参阅 [AtomicXCore](https://tencent-rtc.github.io/TUIKit_Flutter) 框架的官方 API 文档。本指南使用到的相关 Store 如下：
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >**Store/Component**</td>
-
-<td rowspan="1" colSpan="1" >**功能描述**</td>
-
-<td rowspan="1" colSpan="1" >**API 文档**</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >**CoGuestStore**</td>
-
-<td rowspan="1" colSpan="1" >观众连麦管理：连麦申请 / 邀请 / 同意 / 拒绝，连麦成员权限控制（麦克风 / 摄像头），状态同步。</td>
-
-<td rowspan="1" colSpan="1" >[API 文档](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_co_guest_store/CoGuestStore-class.html)</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >**LiveSeatStore**</td>
-
-<td rowspan="1" colSpan="1" >麦位管理：静音/解除静音，锁定/解锁麦位，踢人下麦、远程控制麦上用户麦克风，麦列表状态监听。</td>
-
-<td rowspan="1" colSpan="1" >[API 文档](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_seat_store/LiveSeatStore-class.html)</td>
-</tr>
-</table>
-
+| **Store/Component** | **功能描述** | **API 文档** |
+| --- | --- | --- |
+| **CoGuestStore** | 观众连麦管理：连麦申请 / 邀请 / 同意 / 拒绝，连麦成员权限控制（麦克风 / 摄像头），状态同步。 | [API 文档](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_co_guest_store/CoGuestStore-class.html) |
+| **LiveSeatStore** | 麦位管理：静音/解除静音，锁定/解锁麦位，踢人下麦、远程控制麦上用户麦克风，麦列表状态监听。 | [API 文档](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_seat_store/LiveSeatStore-class.html) |
 
 ## 常见问题
 
@@ -662,7 +506,6 @@ if (result.isSuccess) {
 
 - 语音房（语聊房）：核心是麦位网格。您不会使用 `LiveCoreWidget`，而是会基于 `LiveSeatStore` 的 `liveSeatState`（特别是 `seatList`）来构建一个网格 UI（例如 `GridView`）。UI 的重点是实时显示每个麦位 `SeatInfo` 的状态：是否有人、是否静音、是否被锁定，以及是否正在说话。您只需要打开麦克风。
 
-
 ### 如何在 UI 上实时刷新麦位信息（如是否有人、是否静音）？
 
 您应该订阅 `LiveSeatState` 中的 `seatList` 属性，它是一个 `ValueListenable<List<SeatInfo>>` 类型的响应式数据，每当数组变化时都会通知您重新渲染麦位列表。遍历此数组，您可以：