@tencent-rtc/mcp 1.4.7 → 1.6.0

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

@@ -1,6 +1,6 @@
-**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.
+**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. You don’t need to worry about complex state synchronization or signaling interactions—simply call a few straightforward methods to add robust audio/video interaction between hosts and viewers in your live broadcast. This guide walks you through how to quickly implement voice mic-link functionality in your iOS app using `CoGuestStore` and `LiveSeatStore`.
 
-## Core Scenario
+## Core Scenarios
 
 `CoGuestStore` and `LiveSeatStore` support the following mainstream scenarios:
 - **Audience request to speak**: The audience proactively initiates a mic connection request, and the anchor can grant or reject it upon receiving the request.
@@ -11,24 +11,24 @@
 
 ## Implementation Steps
 
-### Step 1: Component Integration
+### Step 1: Integrate the Components
 
 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.
+> Before enabling co-hosting features, you must obtain the `liveId` (the unique identifier for the live room) to distinguish between different live rooms. You can get it as follows:
 >
-> - **Anchor**: Specify when creating a live stream via `LiveListStore.shared.createLive(liveInfo)`.
+> - **Host**: 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
+### Step 2: Implement Audience Co-host Application
 
-#### Audience Side Implementation
+#### Audience Implementation
 
 As an audience member, your main tasks are **initiating a request, handling the response**, and **leaving the mic proactively**.
-1. **Initiate Mic-Link Request**
+1. Submit a co-host application
 
    When the user taps the "Request Mic-Link" button in the UI, call the `applyForSeat` method.
 
@@ -94,7 +94,7 @@ As an audience member, your main tasks are **initiating a request, handling the
      super.dispose();
    }
    ```
-3. **Leave Mic Proactively**
+3. **Leave Seat**
 
    When an audience member on mic wants to end the interaction, call `disConnect` to return to regular audience status.
 
@@ -125,10 +125,10 @@ As an audience member, your main tasks are **initiating a request, handling the
    }
    ```
 
-#### Host Side Implementation
+#### Host Implementation
 
 As the host, your main tasks are **receiving requests, displaying the request list**, and **handling requests**.
-1. **Listen for New Mic-Link Requests**
+1. **Listen for New Co-host Applications**
 
    By adding `HostListener`, you can receive immediate notification when a new audience applies and prompt.
 
@@ -184,7 +184,7 @@ As the host, your main tasks are **receiving requests, displaying the request li
      super.dispose();
    }
    ```
-3. **Handle Mic-Link Requests**
+3. **Handle Co-host Requests**
 
    When you select an audience member from the list and tap "Accept" or "Reject", call the corresponding method.
 
@@ -206,10 +206,10 @@ As the host, your main tasks are **receiving requests, displaying the request li
    }
    ```
 
-### Step 3: Implement Host-Initiated Mic-Link Invitation
+### Step 3: Host Invites Audience to Co-host
 
-#### Host Side Implementation
-1. **Invite Audience to Mic**
+#### Host Implementation
+1. I**nvite audience to co-host**
 
    When the host selects a viewer from the audience list and taps "Invite to Mic", call the `inviteToSeat` method.
 
@@ -245,7 +245,7 @@ As the host, your main tasks are **receiving requests, displaying the request li
    );
    ```
 
-#### Audience Side Implementation
+#### Audience Implementation
 1. **Receive Host Invitation**
 
    Listen to the `onHostInvitationReceived` event via `GuestListener`.
@@ -288,9 +288,9 @@ As the host, your main tasks are **receiving requests, displaying the request li
 
 Once a user is on mic, the host may need to manage mic seats. The following features are primarily provided by `LiveSeatStore`, which functions with `CoGuestStore`.
 
-### DeviceStore and LiveSeatStore Microphone Control Process
+### Microphone Control: DeviceStore vs LiveSeatStore
 
-When using the seat feature, you need to understand the difference between `DeviceStore` and `LiveSeatStore` in microphone control:
+When working with seat features, it’s important to understand the difference between `DeviceStore` and `LiveSeatStore` for microphone control:
 - **DeviceStore**: Manage physical devices. `openLocalMicrophone` starts up the microphone device to perform audio capture. `closeLocalMicrophone` stops audio capture and releases the microphone device.
 
 - **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.
@@ -303,16 +303,16 @@ 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
+### Microphone Mute/Unmute for Users on Seat
 
-On-mic users (including the host) can control their own microphone mute status via the `LiveSeatStore` interface.
+Users on seat (including the anchor) can mute or unmute their own microphone using methods provided by `LiveSeatStore`.
 
 #### Implementation:
 1. **Mute**: Call the `muteMicrophone()` method. This is a one-way request with no callback.
 
 2. **Unmute**: Call the `unmuteMicrophone()` method.
 
-#### Example code:
+#### Example:
 ``` java
 final seatStore = LiveSeatStore.create(liveId);
 
@@ -321,9 +321,9 @@ seatStore.muteMicrophone(); // Mute
 await seatStore.unmuteMicrophone(); // Unmute
 ```
 
-### Host Remotely Controls On-Mic User’s Microphone
+### Host Remotely Controls User’s Microphone
 
-The host can perform "force mute" or "invite to unmute" operations on other on-mic users.
+The anchor can forcibly mute users on seat or invite them to unmute.
 
 #### Implementation:
 1. **Force Mute (Lock)**: The host calls `closeRemoteMicrophone` to forcibly mute the target user's microphone and lock their mic control. The muted user will receive the `onLocalMicrophoneClosedByAdmin` event via `liveSeatEventPublisher`, and their local "Open Microphone" button should become disabled.
@@ -332,7 +332,7 @@ 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:
+#### Example:
 
 ##### Host Side:
 ``` java
@@ -382,16 +382,18 @@ void dispose() {
 }
 ```
 
-#### CloseRemoteMicrophone API Parameter
-| **Parameter** | **Type** | **Description** |
-| --- | --- | --- |
-| `userID` | `String` | Operating user `userID`. |
+#### CloseRemoteMicrophone API Parameters
 
-#### OpenRemoteMicrophone API Parameter
-| **Parameter** | **Type** | **Description** |
-| --- | --- | --- |
-| `userID` | `String` | Operating user `userID`. |
-| `policy` | `DeviceControlPolicy` | Turn on microphone policy. |
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|`userID`|`String`|Operating user `userID`.|
+
+#### OpenRemoteMicrophone API Parameters
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|`userID`|`String`|Operating user `userID`.|
+|`policy`|`DeviceControlPolicy`|Turn on microphone policy.|
 
 ### Host Removes On-Mic User from the Seat
 
@@ -400,7 +402,7 @@ void dispose() {
 
 2. **Listen for Event Notification**: Users kicked off the mic will receive the `GuestListener``onKickedOffSeat` event notification.
 
-#### Example code:
+#### Example:
 ``` java
 // Assume "userB" is to be kicked out
 final String targetUserId = "userB";
@@ -421,9 +423,10 @@ _guestListener = GuestListener(
 ```
 
 #### KickUserOutOfSeat API Parameter
-| **Parameter** | **Type** | **Description** |
-| --- | --- | --- |
-| `userID` | `String` | The user kicked off the mic `userID`. |
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|`userID`|`String`|The user kicked off the mic `userID`.|
 
 ### Host Locks and Unlocks Mic Seats
 
@@ -434,7 +437,7 @@ 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:
+#### Example:
 ``` java
 // Lock seat 2
 final result1 = await seatStore.lockSeat(2);
@@ -450,18 +453,20 @@ if (result2.isSuccess) {
 ```
 
 #### LockSeat API Parameter
-| **Parameter** | **Type** | **Description** |
-| --- | --- | --- |
-| `seatIndex` | `int` | Index of the mic to lock. |
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|`seatIndex`|`int`|Index of the mic to lock.|
 
 #### UnlockSeat API Parameter
-| **Parameter** | **Type** | **Description** |
-| --- | --- | --- |
-| `seatIndex` | `int` | Index of the mic to unlock. |
 
-### Move Seat
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|`seatIndex`|`int`|Index of the mic to unlock.|
+
+### Move User to Another Seat
 
-Anchor and regular Microphone Users can call `moveUserToSeat` to move microphone positions.
+Host and co-host can call `moveUserToSeat` to change seat 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 description.
@@ -482,31 +487,32 @@ if (result.isSuccess) {
 }
 ```
 
-#### MoveUserToSeat API Parameter
-| **Parameter** | **Type** | **Description** |
+#### MoveUserToSeat API Parameters
+| <strong>Parameter</strong> | <strong>Type</strong> | <strong>Description</strong> |
 | --- | --- | --- |
-| `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. |
+| <code>userID</code> | <code>String</code> | The user who needs to move the mic <code>userID</code>. |
+| <code>targetIndex</code> | <code>int</code> | Index of the target seat. |
+| <code>policy</code> | <code>MoveSeatPolicy</code> | Processing policy when the target seat is occupied<br>- <code>abortWhenOccupied</code>: Abort movement when the target seat is occupied (default policy)<br>- <code>forceReplace</code>: Forcibly replace the user on the target seat. The replaced user will be kicked off the mic.<br>- <code>swapPosition</code>: 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:
-| **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) |
+
+|**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
 
-### What Is the Difference between Voice Room Co-Streaming and Live Streaming Co-Streaming
+### What are the differences between voice room co-hosting and video live co-hosting?
 
 The main difference between both lies in business form and UI display:
-- Live streaming: The core is video footage. You will use `LiveCoreWidget` as the core component to render the video stream of the Anchor and mic-connecting audience. The UI focuses on processing the layout and size of video footage, as well as adding 3D stickers (such as Nickname and placeholder image) on the video stream through `VideoViewDelegate`. You can turn on the camera and microphone at the same time.
+- **Video live streaming:** The focus is on video display. Use `LiveCoreWidget` as the main component to render the anchor and guest video streams. The UI emphasizes video layout and sizing, and you can use `VideoViewDelegate` to add overlays (such as nicknames or placeholders). Both camera and microphone can be enabled.
 
-- 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.
+- **Voice room (chat room):** The focus is on the seat grid. You do not use `LiveCoreWidget`, but instead build a grid UI (such as `GridView`) based on the `liveSeatState` of `LiveSeatStore` (especially seatList). The UI displays each seat’s `SeatInfo` status in real time: whether it’s occupied, muted, locked, or currently speaking. Only the microphone needs to be enabled.
 
-### How to Real-Time Refresh Seat Information on UI (Such As Whether There Is a Person, Whether Muted)
+### How do I update seat info in the UI in real time?
 
 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:
 - Get user information on the seat through `seatInfo.userInfo`.