@tencent-rtc/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** provides [CoGuestStore](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_co_guest_store/CoGuestStore-class.html) and [LiveSeatStore](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_seat_store/LiveSeatStore-class.html) modules, used to manage the complete business process of audience mic connection. Users do not need to worry about complex state synchronization and signaling interaction, just call a few simple methods to add powerful audio-video interaction between audience and anchor to your live stream. This document will guide you on how to use `CoGuestStore` and `LiveSeatStore` for quick implementation of audio mic connection in Flutter application.
 
-![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100032457995/9751d111f80f11f08d7f52540097cba1.png)
-
-
 ## Core Scenario
 
 `CoGuestStore` and `LiveSeatStore` support the following mainstream scenarios:
@@ -12,22 +9,20 @@
 
 - **Anchor seat management**: The anchor can perform operations such as forced microphone removal, muting, and locking on the user on the seat.
 
-
 ## Implementation Steps
 
 ### Step 1: Component Integration
 
-Refer to [quick integration](https://write.woa.com/document/200555778169073664) to integrate **AtomicXCore**.
+Refer to quick integration to integrate **AtomicXCore**.
 
 > **Note:**
-> 
+>
 
 > Before implementing the co-anchoring function, you need to get the `liveId` (the unique identifier of the live streaming room) to distinguish different live streaming rooms. The method for obtaining it is as follows.
-> 
+>
 > - **Anchor**: Specify when creating a live stream via `LiveListStore.shared.createLive(liveInfo)`.
 > - **Client**: Get it from `liveInfo` in `LiveListState.liveList.value`, or obtain it by the Anchor sharing the live streaming room ID.
 
-
 ### Step 2: Implement Audience Mic-Link Request
 
 #### Audience Side Implementation
@@ -35,21 +30,20 @@ Refer to [quick integration](https://write.woa.com/document/200555778169073664)
 As an audience member, your main tasks are **initiating a request, handling the response**, and **leaving the mic proactively**.
 1. **Initiate Mic-Link Request**
 
-
    When the user taps the "Request Mic-Link" button in the UI, call the `applyForSeat` method.
 
    ``` java
    import 'package:atomic_x_core/atomicxcore.dart';
-   
+
    final String liveId = "room ID";
    late CoGuestStore guestStore;
-   
+
    @override
    void initState() {
      super.initState();
      guestStore = CoGuestStore.create(liveId);
    }
-   
+
    // User click "Apply for Mic Connection"
    Future<void> requestToConnect() async {
      // seatIndex: The seat index, starting from 0, represents the applied microphone position. 0 means the first seat. View seat status via LiveSeatState.seatList.value and select an idle seat.
@@ -69,12 +63,11 @@ As an audience member, your main tasks are **initiating a request, handling the
    ```
 2. **Listen for Host Response**
 
-
    By adding `GuestListener`, you can receive the host's response
 
    ``` java
    late GuestListener _guestListener;
-   
+
    // Subscribe to events when your Widget initializes
    void subscribeGuestEvents() {
      _guestListener = GuestListener(
@@ -94,7 +87,7 @@ As an audience member, your main tasks are **initiating a request, handling the
      );
      guestStore.addGuestListener(_guestListener);
    }
-   
+
    @override
    void dispose() {
      guestStore.removeGuestListener(_guestListener);
@@ -103,7 +96,6 @@ As an audience member, your main tasks are **initiating a request, handling the
    ```
 3. **Leave Mic Proactively**
 
-
    When an audience member on mic wants to end the interaction, call `disConnect` to return to regular audience status.
 
    ``` java
@@ -119,7 +111,6 @@ As an audience member, your main tasks are **initiating a request, handling the
    ```
 4. **(Optional) Cancel Request**
 
-
    If the audience member wants to withdraw the request before the host responds, call `cancelApplication`.
 
    ``` java
@@ -139,21 +130,20 @@ As an audience member, your main tasks are **initiating a request, handling the
 As the host, your main tasks are **receiving requests, displaying the request list**, and **handling requests**.
 1. **Listen for New Mic-Link Requests**
 
-
    By adding `HostListener`, you can receive immediate notification when a new audience applies and prompt.
 
    ``` java
    import 'package:atomic_x_core/atomicxcore.dart';
-   
+
    final String liveId = "room ID";
    late CoGuestStore guestStore;
    late HostListener _hostListener;
-   
+
    @override
    void initState() {
      super.initState();
      guestStore = CoGuestStore.create(liveId);
-   
+
      // Subscribe to anchor event
      _hostListener = HostListener(
        onGuestApplicationReceived: (guestUser) {
@@ -163,7 +153,7 @@ As the host, your main tasks are **receiving requests, displaying the request li
      );
      guestStore.addHostListener(_hostListener);
    }
-   
+
    @override
    void dispose() {
      guestStore.removeHostListener(_hostListener);
@@ -172,23 +162,22 @@ As the host, your main tasks are **receiving requests, displaying the request li
    ```
 2. **Display Request List**
 
-
    `CoGuestStore`'s `coGuestState` maintains the current applicant list in real time. You can subscribe to it to update your UI.
 
    ``` java
    late final VoidCallback _applicantsListener = _onApplicantsChanged;
-   
+
    // Subscribe to status change
    void subscribeApplicants() {
      guestStore.coGuestState.applicants.addListener(_applicantsListener);
    }
-   
+
    void _onApplicantsChanged() {
      final applicants = guestStore.coGuestState.applicants.value;
      debugPrint('Current number of applicants: ${applicants.length}');
      // Update your "applicant list" UI here
    }
-   
+
    @override
    void dispose() {
      guestStore.coGuestState.applicants.removeListener(_applicantsListener);
@@ -197,7 +186,6 @@ As the host, your main tasks are **receiving requests, displaying the request li
    ```
 3. **Handle Mic-Link Requests**
 
-
    When you select an audience member from the list and tap "Accept" or "Reject", call the corresponding method.
 
    ``` java
@@ -208,7 +196,7 @@ As the host, your main tasks are **receiving requests, displaying the request li
        debugPrint('Approved $userId\'s request, the other party is joining the mic');
      }
    }
-   
+
    // Anchor clicks the "Reject" button
    Future<void> reject(String userId) async {
      final result = await guestStore.rejectApplication(userId);
@@ -223,7 +211,6 @@ As the host, your main tasks are **receiving requests, displaying the request li
 #### Host Side Implementation
 1. **Invite Audience to Mic**
 
-
    When the host selects a viewer from the audience list and taps "Invite to Mic", call the `inviteToSeat` method.
 
    ``` java
@@ -243,7 +230,6 @@ As the host, your main tasks are **receiving requests, displaying the request li
    ```
 2. **Listen for Audience Response**
 
-
    Listen to the `onHostInvitationResponded` event via `HostListener`.
 
    ``` java
@@ -262,7 +248,6 @@ As the host, your main tasks are **receiving requests, displaying the request li
 #### Audience Side Implementation
 1. **Receive Host Invitation**
 
-
    Listen to the `onHostInvitationReceived` event via `GuestListener`.
 
    ``` java
@@ -277,12 +262,11 @@ As the host, your main tasks are **receiving requests, displaying the request li
    ```
 2. **Respond to invitation**
 
-
    After the user makes a selection in the pop-up dialog box, call the method accordingly.
 
    ``` java
    final String inviterId = "anchor ID who initiates invitation"; // obtain from onHostInvitationReceived event
-   
+
    // User clicks "Accept"
    Future<void> accept() async {
      final result = await guestStore.acceptInvitation(inviterId);
@@ -293,7 +277,7 @@ As the host, your main tasks are **receiving requests, displaying the request li
        DeviceStore.shared.openLocalMicrophone();
      }
    }
-   
+
    // User click "Reject"
    Future<void> reject() async {
      await guestStore.rejectInvitation(inviterId);
@@ -311,7 +295,6 @@ When using the seat feature, you need to understand the difference between `Devi
 
 - **LiveSeatStore**: Manages seat business (i.e., audio stream). `muteMicrophone` mutes and stops sending local audio stream to the remote end, but the microphone device itself keeps running. `unmuteMicrophone` unmutes and restores sending audio stream to the remote end.
 
-
    **Recommended workflow**: You should follow the principle of "open the device only once and use the mute switch for Anchor."
 
 1. **When going on stage**: Once the audience succeeds in going on stage, call `openLocalMicrophone` only once to start the device.
@@ -320,7 +303,6 @@ When using the seat feature, you need to understand the difference between `Devi
 
 3. **When going off stage**: When a user goes off stage (such as calling `disconnect`), call `closeLocalMicrophone` to release the device.
 
-
 ### On-Mic Users Control Their Own Microphone
 
 On-mic users (including the host) can control their own microphone mute status via the `LiveSeatStore` interface.
@@ -330,7 +312,6 @@ On-mic users (including the host) can control their own microphone mute status v
 
 2. **Unmute**: Call the `unmuteMicrophone()` method.
 
-
 #### Example code:
 ``` java
 final seatStore = LiveSeatStore.create(liveId);
@@ -351,7 +332,6 @@ The host can perform "force mute" or "invite to unmute" operations on other on-m
 
 3. **User Unmutes Themselves**: After receiving the unlock notification, the user must actively call `LiveSeatStore`'s `unmuteMicrophone()` to actually unmute and be heard in the room.
 
-
 #### Example code:
 
 ##### Host Side:
@@ -403,52 +383,15 @@ void dispose() {
 ```
 
 #### CloseRemoteMicrophone API Parameter
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >**Parameter**</td>
-
-<td rowspan="1" colSpan="1" >**Type**</td>
-
-<td rowspan="1" colSpan="1" >**Description**</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`userID`</td>
-
-<td rowspan="1" colSpan="1" >`String`</td>
-
-<td rowspan="1" colSpan="1" >Operating user `userID`.</td>
-</tr>
-</table>
-
+| **Parameter** | **Type** | **Description** |
+| --- | --- | --- |
+| `userID` | `String` | Operating user `userID`. |
 
 #### OpenRemoteMicrophone API Parameter
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >**Parameter**</td>
-
-<td rowspan="1" colSpan="1" >**Type**</td>
-
-<td rowspan="1" colSpan="1" >**Description**</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`userID`</td>
-
-<td rowspan="1" colSpan="1" >`String`</td>
-
-<td rowspan="1" colSpan="1" >Operating user `userID`.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`policy`</td>
-
-<td rowspan="1" colSpan="1" >`DeviceControlPolicy`</td>
-
-<td rowspan="1" colSpan="1" >Turn on microphone policy.</td>
-</tr>
-</table>
-
+| **Parameter** | **Type** | **Description** |
+| --- | --- | --- |
+| `userID` | `String` | Operating user `userID`. |
+| `policy` | `DeviceControlPolicy` | Turn on microphone policy. |
 
 ### Host Removes On-Mic User from the Seat
 
@@ -457,7 +400,6 @@ void dispose() {
 
 2. **Listen for Event Notification**: Users kicked off the mic will receive the `GuestListener``onKickedOffSeat` event notification.
 
-
 #### Example code:
 ``` java
 // Assume "userB" is to be kicked out
@@ -479,24 +421,9 @@ _guestListener = GuestListener(
 ```
 
 #### KickUserOutOfSeat API Parameter
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >**Parameter**</td>
-
-<td rowspan="1" colSpan="1" >**Type**</td>
-
-<td rowspan="1" colSpan="1" >**Description**</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`userID`</td>
-
-<td rowspan="1" colSpan="1" >`String`</td>
-
-<td rowspan="1" colSpan="1" >The user kicked off the mic `userID`.</td>
-</tr>
-</table>
-
+| **Parameter** | **Type** | **Description** |
+| --- | --- | --- |
+| `userID` | `String` | The user kicked off the mic `userID`. |
 
 ### Host Locks and Unlocks Mic Seats
 
@@ -507,7 +434,6 @@ The host can lock or unlock a specific mic seat.
 
 2. **Unlock Seat**: Call `unlockSeat` to unlock the seat. The seat can be occupied again after unlocking.
 
-
 #### Example code:
 ``` java
 // Lock seat 2
@@ -524,55 +450,24 @@ if (result2.isSuccess) {
 ```
 
 #### LockSeat API Parameter
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >**Parameter**</td>
-
-<td rowspan="1" colSpan="1" >**Type**</td>
-
-<td rowspan="1" colSpan="1" >**Description**</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`seatIndex`</td>
-
-<td rowspan="1" colSpan="1" >`int`</td>
-
-<td rowspan="1" colSpan="1" >Index of the mic to lock.</td>
-</tr>
-</table>
-
+| **Parameter** | **Type** | **Description** |
+| --- | --- | --- |
+| `seatIndex` | `int` | Index of the mic to lock. |
 
 #### UnlockSeat API Parameter
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >**Parameter**</td>
-
-<td rowspan="1" colSpan="1" >**Type**</td>
-
-<td rowspan="1" colSpan="1" >**Description**</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`seatIndex`</td>
-
-<td rowspan="1" colSpan="1" >`int`</td>
-
-<td rowspan="1" colSpan="1" >Index of the mic to unlock.</td>
-</tr>
-</table>
-
+| **Parameter** | **Type** | **Description** |
+| --- | --- | --- |
+| `seatIndex` | `int` | Index of the mic to unlock. |
 
 ### Move Seat
 
 Anchor and regular Microphone Users can call `moveUserToSeat` to move microphone positions.
 
 #### Implementation:
-1. **Host Moves User to Mic Seat**: The host can call this API to move any user to a specified seat. At this point, `userID` is the ID of the target user, `targetIndex` is the index of the target seat, and the `policy` parameter specifies the move strategy if the target seat is occupied. For details, see the [API parameter](https://write.woa.com/#moveusertoseat-.E6.8E.A5.E5.8F.A3.E5.8F.82.E6.95.B0.EF.BC.9A) description.
+1. **Host Moves User to Mic Seat**: The host can call this API to move any user to a specified seat. At this point, `userID` is the ID of the target user, `targetIndex` is the index of the target seat, and the `policy` parameter specifies the move strategy if the target seat is occupied. For details, see the API parameter description.
 
 2. **On-Mic User Moves Themselves**: On-mic users can also call this API to move themselves. In this case, `userID` must be the user's own ID, `targetIndex` is the desired new seat index, and the `policy` parameter is ignored. If the target seat is occupied, the move fails with an error.
 
-
 #### Example code:
 ``` java
 final result = await seatStore.moveUserToSeat(
@@ -588,70 +483,19 @@ if (result.isSuccess) {
 ```
 
 #### MoveUserToSeat API Parameter
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >**Parameter**</td>
-
-<td rowspan="1" colSpan="1" >**Type**</td>
-
-<td rowspan="1" colSpan="1" >**Description**</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`userID`</td>
-
-<td rowspan="1" colSpan="1" >`String`</td>
-
-<td rowspan="1" colSpan="1" >The user who needs to move the mic `userID`.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`targetIndex`</td>
-
-<td rowspan="1" colSpan="1" >`int`</td>
-
-<td rowspan="1" colSpan="1" >Index of the target seat.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`policy`</td>
-
-<td rowspan="1" colSpan="1" >`MoveSeatPolicy`</td>
-
-<td rowspan="1" colSpan="1" >Processing policy when the target seat is occupied<br>- `abortWhenOccupied`: Abort movement when the target seat is occupied (default policy)<br>- `forceReplace`: Forcibly replace the user on the target seat. The replaced user will be kicked off the mic.<br>- `swapPosition`: Exchange with the user on the target seat.</td>
-</tr>
-</table>
-
+| **Parameter** | **Type** | **Description** |
+| --- | --- | --- |
+| `userID` | `String` | The user who needs to move the mic `userID`. |
+| `targetIndex` | `int` | Index of the target seat. |
+| `policy` | `MoveSeatPolicy` | Processing policy when the target seat is occupied<br>- `abortWhenOccupied`: Abort movement when the target seat is occupied (default policy)<br>- `forceReplace`: Forcibly replace the user on the target seat. The replaced user will be kicked off the mic.<br>- `swapPosition`: Exchange with the user on the target seat. |
 
 ## API documentation
 
 For detailed information about ALL public interfaces, attributes, and methods of [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), and its related classes, see the official API documentation of the [AtomicXCore](https://tencent-rtc.github.io/TUIKit_Flutter) framework. The related Store used in this guide is as follows:
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >**Store/Component**</td>
-
-<td rowspan="1" colSpan="1" >**Feature Description**</td>
-
-<td rowspan="1" colSpan="1" >**API Reference**</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >**CoGuestStore**</td>
-
-<td rowspan="1" colSpan="1" >Audience co-broadcasting management: join microphone application/invite/consent/deny, member permission control (microphone/camera), state synchronization.</td>
-
-<td rowspan="1" colSpan="1" >[API documentation](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" >Seat management: mute/unmute, lock/unlock seats, remove speaker, remotely control Anchor microphone, listen to list status.</td>
-
-<td rowspan="1" colSpan="1" >[API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_seat_store/LiveSeatStore-class.html)</td>
-</tr>
-</table>
-
+| **Store/Component** | **Feature Description** | **API Reference** |
+| --- | --- | --- |
+| **CoGuestStore** | Audience co-broadcasting management: join microphone application/invite/consent/deny, member permission control (microphone/camera), state synchronization. | [API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_co_guest_store/CoGuestStore-class.html) |
+| **LiveSeatStore** | Seat management: mute/unmute, lock/unlock seats, remove speaker, remotely control Anchor microphone, listen to list status. | [API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_seat_store/LiveSeatStore-class.html) |
 
 ## FAQs
 
@@ -662,7 +506,6 @@ The main difference between both lies in business form and UI display:
 
 - Voice room (voice chat room): The core is the seat grid. You will not use `LiveCoreWidget`, but build a grid UI (such as `GridView`) based on `LiveSeatStore`'s `liveSeatState` (especially `seatList`). The UI focuses on displaying each seat `SeatInfo` state in real time: whether there is a person, whether it is muted, whether it is locked, and whether speaking is ongoing. You only need to turn on microphone.
 
-
 ### How to Real-Time Refresh Seat Information on UI (Such As Whether There Is a Person, Whether Muted)
 
 You should subscribe to the `seatList` property in `LiveSeatState`, which is a responsive data of `ValueListenable<List<SeatInfo>>` data type. It will notify you to re-render the microphone position list whenever the array changes. By traversing this array, you can:
@@ -671,5 +514,3 @@ You should subscribe to the `seatList` property in `LiveSeatState`, which is a r
 - Check whether the seat is locked through `seatInfo.isLocked`.
 
 - Check the mic status of the on-mic user through `seatInfo.userInfo.microphoneStatus`.
-
-