@tencent-rtc/mcp 1.4.7 → 1.6.0

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

@@ -1,14 +1,14 @@
-This document guides you through building a voice chat room application with host broadcasting and audience participation features using the **AtomicXCore** SDK's `LiveListStore` and `LiveSeatStore`.
+This guides you through building a voice chat room application with host broadcasting and audience participation features using the **AtomicXCore** SDK's `LiveListStore` and `LiveSeatStore`.
 
 ## Core Concepts
 
-Before starting integration, please go through the following table to understand several core concepts related to `LiveSeatStore`:
-| **Core Concepts** | **Type** | **Core Responsibilities and Description** |
+The following table introduces core concepts of `LiveSeatStore`:
+| <strong>Core Concepts</strong> | <strong>Type</strong> | <strong>Core Responsibilities and Description</strong> |
 | --- | --- | --- |
-| [LiveSeatStore](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_seat_store/LiveSeatStore-class.html) | `class` | The core of seat management is responsible for managing ALL seat information and related operations in the room.<br>Expose the real-time microphone position list data stream through `liveSeatState.seatList`. |
-| [LiveSeatState](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_seat_store/LiveSeatState-class.html) | `class` | Represent the current status of the microphone position.<br>- `seatList` is a `ValueListenable<List<SeatInfo>>` type that stores the real-time status of the seat position list;<br>- `speakingUsers` signifies the person currently speaking and the corresponding volume. |
-| [SeatInfo](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_seat_store/SeatInfo-class.html) | `class` | The data model of one microphone position. The seat position list (`seatList`) pushed by `LiveSeatStore` consists of multiple `SeatInfo` objects. Key field:<br>- `index` (the index of the seat position).<br>- `isLocked` (whether the seat position is locked).<br>- `userInfo` (user information on the seat position. If the seat position is empty, this field is also an empty object). |
-| [SeatUserInfo](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_seat_store/SeatUserInfo-class.html) | `class` | The detailed data model of the on-mic user. When a user successfully gets on mic, the `userInfo` field in `SeatInfo` will be filled with this user. Key field:<br>- `userID` (user's unique ID)<br>- `userName` (user's nickname)<br>- `avatarURL` (user's profile photo URL)<br>- `microphoneStatus` (Mic status)<br>- `cameraStatus` (Camera status). |
+| <a href="https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_seat_store/LiveSeatStore-class.html">LiveSeatStore</a> | <code>class</code> | The core of seat management is responsible for managing ALL seat information and related operations in the room.<br>Expose the real-time microphone position list data stream through <code>liveSeatState.seatList</code>. |
+| <a href="https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_seat_store/LiveSeatState-class.html">LiveSeatState</a> | <code>class</code> | Represent the current status of the microphone position.<br>- <code>seatList</code> is a <code>ValueListenable<List<SeatInfo>></code> type that stores the real-time status of the seat position list.<br>- <code>speakingUsers</code> signifies the person currently speaking and the corresponding volume. |
+| <a href="https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_seat_store/SeatInfo-class.html">SeatInfo</a> | <code>class</code> | The data model of one microphone position. The seat position list (<code>seatList</code>) pushed by <code>LiveSeatStore</code> consists of multiple <code>SeatInfo</code> objects. Key field:<br>- <code>index</code> (the index of the seat position).<br>- <code>isLocked</code> (whether the seat position is locked).<br>- <code>userInfo</code> (user information on the seat position. If the seat position is empty, this field is also an empty object). |
+| <a href="https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_seat_store/SeatUserInfo-class.html">SeatUserInfo</a> | <code>class</code> | The detailed data model of the on-mic user. When a user successfully gets on mic, the <code>userInfo</code> field in <code>SeatInfo</code> will be filled with this user. Key field:<br>- <code>userID</code> (user's unique ID).<br>- <code>userName</code> (user's nickname).<br>- <code>avatarURL</code> (user's profile photo URL).<br>- <code>microphoneStatus</code> (Mic status).<br>- <code>cameraStatus</code> (Camera status). |
 
 ## Preparations
 
@@ -24,7 +24,7 @@ See Activate Service to obtain either the trial or paid version of the SDK.Then,
 
    ``` yaml
    dependencies:
-     atomic_x_core: ^3.6.0
+     atomic_x_core: ^4.0.1
    ```
 2. **Configure project permissions:** Android and iOS projects all are needed to configure permissions.
 
@@ -95,20 +95,20 @@ void main() async {
 }
 ```
 
-**Login API parameter description:**
-| **Parameter** | **Type** | **Description** |
+**Login API parameters:**
+| <strong>Parameter</strong> | <strong>Type</strong> | <strong>Description</strong> |
 | --- | --- | --- |
-| `sdkAppID` | `Int` | Get this from [TRTC console > Application management](https://console.trtc.io/app). |
-| `userID` | `String` | The unique ID for the current user. Must contain only English letters, numbers, hyphens, and underscores. |
-| `userSig` | `String` | A ticket for Tencent Cloud authentication. Please note:<br>- **Development Environment**: You can use the local `GenerateTestUserSig.genTestSig` function to generate a UserSig or generate a temporary UserSig via the [UserSig Generation Tool](https://console.trtc.io/usersig).<br>- **Production Environment**: To prevent key leakage, you must use a server-side method to generate UserSig. For details, see Generating UserSig on the Server.<br>- For more information, see How to Calculate and Use UserSig. |
+| <code>sdkAppID</code> | <code>Int</code> | Get this from <a href="https://console.trtc.io/app">TRTC console > Application management</a>. |
+| <code>userID</code> | <code>String</code> | The unique ID for the current user. Must contain only English letters, numbers, hyphens, and underscores. |
+| <code>userSig</code> | <code>String</code> | A credential for TRTC authentication:<br>- <strong>Development Environment</strong>: You can use the local <code>GenerateTestUserSig.genTestSig</code> function to generate a UserSig or generate a temporary UserSig via the <a href="https://console.trtc.io/usersig">UserSig Generation Tool</a>.<br>- <strong>Production Environment</strong>: To prevent key leakage, you must generate UserSig on the server side. For details, see Generating UserSig on the Server.<br>- For more information, see How to Calculate and Use UserSig. |
 
-## Building a Basic Voice Chat Room
+## Build a Basic Voice Chat Room
 
-### Step 1: Host Room Creation
+### Step 1: Host Creates a Voice Chat Room
 
 Follow these steps to quickly set up a voice chat room as the host.
 
-#### 1. **Initialize the Seat Store**
+#### 1. **Initialize **LiveSeatStore
 
 On your anchor page, create a `LiveSeatStore` instance. You need to listen to changes in `liveSeatStore.liveSeatState` for real-time seat updates and UI rendering.
 ``` java
@@ -167,9 +167,9 @@ class _YourAnchorPageState extends State<YourAnchorPage> {
 }
 ```
 
-#### Turn on Microphone
+#### 2. Turn on Microphone
 
-Turn on the microphone by calling the `DeviceStore``openLocalMicrophone` API. Sample code:
+Turn on the microphone by calling the `DeviceStore``openLocalMicrophone` API:
 ``` java
 class _YourAnchorPageState extends State<YourAnchorPage> {
   // ... Other code ...
@@ -183,7 +183,7 @@ class _YourAnchorPageState extends State<YourAnchorPage> {
 
 #### 3. Start Voice Chat
 
-By calling the `LiveListStore``createLive` API to start a voice chat room live stream, sample code:
+By calling the `LiveListStore``createLive` API to start a voice chat room live stream:
 ``` java
 class _YourAnchorPageState extends State<YourAnchorPage> {
   // ... Other code ...
@@ -205,20 +205,13 @@ class _YourAnchorPageState extends State<YourAnchorPage> {
       liveID: _liveID,
       // 3. Set the room name
       liveName: "test voice chat room",
-      // 4. Configured as a voice chat room (enable seat)
-      isSeatEnabled: true,
-      // 5. Room owner on seat by default
-      keepOwnerOnSeat: true,
-      // 6. Set the seat layout template (for example, 70 is the 10-seat template)
-      // Important: According to the product specification, input the correct ID
-      seatLayoutTemplateID: 70,
-      // 7. Set the microphone mode, such as apply for microphone mode
+      // 4. Set up the layout template for the video chat room (entering 9 indicates 9 microphones) (enable the microphones)
+      seatTemplate: AudioSalon(9),
+      // 5. Set the microphone mode, such as apply for microphone mode
       seatMode: TakeSeatMode.apply,
-      // 8. Set the maximum number of microphone slots
-      maxSeatCount: 10,
     );
 
-    // 9. Call createLive to start live streaming
+    // 6. Call createLive to start live streaming
     final result = await _liveListStore.createLive(liveInfo);
 
     if (result.isSuccess) {
@@ -232,26 +225,24 @@ class _YourAnchorPageState extends State<YourAnchorPage> {
 }
 ```
 
-**LiveInfo parameter description:**
-| **Parameter Name** | **Type** | **Attribute** | **Description** |
-| --- | --- | --- | --- |
-| `liveID` | `String` | Required | Unique identifier of the live streaming room. |
-| `liveName` | `String` | Optional. | Title of the live streaming room. |
-| `notice` | `String` | Optional. | Announcement information of the live streaming room. |
-| `isMessageDisable` | `bool` | Optional. | Whether to mute (`true`: yes, `false`: no). |
-| `isPublicVisible` | `bool` | Optional. | Whether publicly visible (`true`: yes, `false`: no). |
-| `isSeatEnabled` | `bool` | Optional. | Whether to enable the seat feature (`true`: yes, `false`: no). |
-| `keepOwnerOnSeat` | `bool` | Optional. | Whether to keep the room owner on the seat. |
-| `maxSeatCount` | `int` | Optional. | Maximum number of microphones. |
-| `seatMode` | `TakeSeatMode` | Optional. | Microphone mode (`free`: Free to Join the Podium, `apply`: request to speak). |
-| `seatLayoutTemplateID` | `int` | Required | Mic position layout template `ID.` |
-| `coverURL` | `String` | Optional. | thumbnail URL of the live streaming room. |
-| `backgroundURL` | `String` | Optional. | background image URL of the live streaming room. |
-| `categoryList` | `List<int>` | Optional. | Category tag list of the live streaming room. |
-| `activityStatus` | `int` | Optional. | Live stream status. |
-| `isGiftEnabled` | `bool` | Optional. | Whether to enable the gift function (`true`: yes, `false`: no). |
-
-#### 4. Build a Mic Seat UI
+**LiveInfo parameters:**
+
+|**Parameter Name**|**Type**|**Attribute**|**Description**|
+|---------|---------|---------|---------|
+|`liveID`|`String`|Required|Unique identifier of the live streaming room.|
+|`liveName`|`String`|Optional.|Title of the live streaming room.|
+|`notice`|`String`|Optional.|Announcement information of the live streaming room.|
+|`isMessageDisable`|`bool`|Optional.|Whether to mute chat (`true`: yes, `false`: no).|
+|`isPublicVisible`|`bool`|Optional.|Make room public (`true`: yes, `false`: no)|
+|`seatMode`|`TakeSeatMode`|Optional.|Microphone mode (`free`: free to take seat, `apply`: apply to take seat).|
+|`seatTemplate`|`SeatLayoutTemplate`|Required|Seat layout template.|
+|`coverURL`|`String`|Optional.|Cover image URL for the live room.|
+|`backgroundURL`|`String`|Optional.|Background image URL of the live streaming room.|
+|`categoryList`|`List<int>`|Optional.|Category tag list of the live streaming room.|
+|`activityStatus`|`int`|Optional.|Live stream status.|
+|`isGiftEnabled`|`bool`|Optional.|Whether to enable the gift function (`true`: yes, `false`: no).|
+
+#### 4. Build a Seat UI
 
 > **Note:**
 >
@@ -345,7 +336,7 @@ class _YourAnchorPageState extends State<YourAnchorPage> {
 
 Enable audience members to join the voice chat room with the following steps.
 
-#### 1. **Initialize the Seat Store**
+#### 1. **Initialize the **LiveSeatStore
 
 On your audience page, create a `LiveSeatStore` instance and listen to changes in `liveSeatState.seatList` to render the mic seat UI.
 ``` java
@@ -432,9 +423,9 @@ class _YourAudiencePageState extends State<YourAudiencePage> {
 }
 ```
 
-#### 3. Build a Mic Seat UI
+#### 3. Build a Seat UI
 
-The process for the audience to build a Mic Seat UI is the same as that for the Anchor. Refer to Build a Mic Seat UI.
+Audience seat UI implementation is identical to the host. Refer to Build a Mic Seat UI.
 
 #### 4. **Leave the Voice Chat Room**
 
@@ -461,7 +452,7 @@ After completing the above steps, you can complete a most basic voice chat live
 
 ## Advanced Features
 
-### Implementing On-Mic User Voice Waves
+### Display Speaking Wave Animation for Users on Seat
 
 In a voice chat room scenario, a common need is to display a wave animation on the avatar of an on-mic user when they speak, notifying all room users "who is speaking". `LiveSeatStore` provides the `speakingUsers` data stream, specialized for implementing this feature.
 
@@ -534,41 +525,43 @@ class YourSpeakingIndicatorWidget extends StatelessWidget {
 }
 ```
 
-## Enriching Voice Chat Room Scenario
+## Enrich Voice Chat Room Scenarios
 
 After completing the basic voice chat room features, you can refer to the following feature guide to add various interactive gameplay features to the voice chat room.
-| **Feature** | **Feature Description** | **Feature Stores** | **Implementation Guide** |
-| --- | --- | --- | --- |
-| **Audience Take Seat** | Audience members can apply to take a seat and interact with the host in real time. | [CoGuestStore](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_co_guest_store/CoGuestStore-class.html) | Implementation |
-| **Add Barrage Chat** | Room members can send and receive real-time text messages. | [BarrageStore](https://tencent-rtc.github.io/TUIKit_Flutter/api_barrage_barrage_store/BarrageStore-class.html) | Implementation |
-| **Gift System** | Audience can send virtual gifts to hosts to increase interaction and engagement. | [GiftStore](https://tencent-rtc.github.io/TUIKit_Flutter/api_gift_gift_store/GiftStore-class.html) | Implementation |
+
+|**Feature**|**Feature Description**|**Feature Stores**|**Implementation Guide**|
+|---------|---------|---------|---------|
+|**Audience Take Seat**|Audience members can apply to take a seat and interact with the host in real time.|[CoGuestStore](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_co_guest_store/CoGuestStore-class.html)|Implementation|
+|**Add Barrage Chat**|Room members can send and receive real-time text messages.|[BarrageStore](https://tencent-rtc.github.io/TUIKit_Flutter/api_barrage_barrage_store/BarrageStore-class.html)|Implementation|
+|**Gift System**|Audience can send virtual gifts to hosts to increase interaction and engagement.|[GiftStore](https://tencent-rtc.github.io/TUIKit_Flutter/api_gift_gift_store/GiftStore-class.html)|Implementation|
 
 ## API documentation
-| **Store/Component** | **Feature Description** | **API Reference** |
-| --- | --- | --- |
-| **LiveListStore** | Full lifecycle management of live streaming room: create/join/leave/terminate room, query room list, modify live information (name, notice), listen to live streaming status (for example, being kicked out, ended). | [API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_list_store/LiveListStore-class.html) |
-| **LiveSeatStore** | Core of seat management: manage seat list, Anchor status, and related operations (taking a seat, leaving a seat, removing user, locking seat, switching microphone on or off/camera), listen to seat events. | [API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_seat_store/LiveSeatStore-class.html) |
-| **DeviceStore** | Audio/Video device control: microphone (on/off, volume), camera (on/off, switchover, video quality), screen sharing, monitor device status in real time. | [API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_device_device_store/DeviceStore-class.html) |
-| **CoGuestStore** | Audience co-broadcasting management: join microphone application/invite/grant/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) |
-| **CoHostStore** | Anchor cross-room connection: support for multiple layout templates (dynamic grid, etc.), initiate/accept/reject connection, and interactive management of co-broadcasting Anchors. | [API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_co_host_store/CoHostStore-class.html) |
-| **BattleStore** | Anchor PK battle: initiate PK (duration configuration/competitor), manage PK status (start/end), synchronize score, listen to battle results. | [API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_battle_store/BattleStore-class.html) |
-| **GiftStore** | Gift interaction: get gift list, send/receive gifts, listen to gift events (including sender, gift details). | [API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_gift_gift_store/GiftStore-class.html) |
-| **BarrageStore** | Danmaku function: send text/custom barrage item, maintain bullet screen list, monitor danmaku status in real time. | [API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_barrage_barrage_store/BarrageStore-class.html) |
-| **LikeStore** | Like interaction: send likes, listen to like events, sync total likes. | [API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_like_store/LikeStore-class.html) |
-| **LiveAudienceStore** | Audience management: get real-time audience list (ID/name/avatar), check audience size, listen to Enter/Exit Event. | [API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_audience_store/LiveAudienceStore-class.html) |
-| **AudioEffectStore** | Audio effects: voice-changing (child voice/male voice), reverberation (KTV), ear monitoring adjustment, switch special effects in real time. | [API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_device_audio_effect_store/AudioEffectStore-class.html) |
-| **BaseBeautyStore** | Basic beauty filter: adjust skin smoothing/whitening/rosy (0-100 levels), reset beauty status, sync effect parameters. | [API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_device_base_beauty_store/BaseBeautyStore-class.html) |
+
+|**Store/Component**|**Feature Description**|**API Reference**|
+|---------|---------|---------|
+|**LiveListStore**|Full lifecycle management of live streaming room: create/join/leave/terminate room, query room list, modify live information (name, notice), listen to live streaming status (for example, being kicked out, ended).|[API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_list_store/LiveListStore-class.html)|
+|**LiveSeatStore**|Core of seat management: manage seat list, Anchor status, and related operations (taking a seat, leaving a seat, removing user, locking seat, switching microphone on or off/camera), listen to seat events.|[API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_seat_store/LiveSeatStore-class.html)|
+|**DeviceStore**|Audio/Video device control: microphone (on/off, volume), camera (on/off, switchover, video quality), screen sharing, monitor device status in real time.|[API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_device_device_store/DeviceStore-class.html)|
+|**CoGuestStore**|Audience co-broadcasting management: join microphone application/invite/grant/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)|
+|**CoHostStore**|Anchor cross-room connection: support for multiple layout templates (dynamic grid, etc.), initiate/accept/reject connection, and interactive management of co-broadcasting Anchors.|[API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_co_host_store/CoHostStore-class.html)|
+|**BattleStore**|Anchor PK battle: initiate PK (duration configuration/competitor), manage PK status (start/end), synchronize score, listen to battle results.|[API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_battle_store/BattleStore-class.html)|
+|**GiftStore**|Gift interaction: get gift list, send/receive gifts, listen to gift events (including sender, gift details).|[API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_gift_gift_store/GiftStore-class.html)|
+|**BarrageStore**|Danmaku function: send text/custom barrage item, maintain bullet screen list, monitor danmaku status in real time.|[API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_barrage_barrage_store/BarrageStore-class.html)|
+|**LikeStore**|Like interaction: send likes, listen to like events, sync total likes.|[API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_like_store/LikeStore-class.html)|
+|**LiveAudienceStore**|Audience management: get real-time audience list (ID/name/avatar), check audience size, listen to Enter/Exit Event.|[API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_audience_store/LiveAudienceStore-class.html)|
+|**AudioEffectStore**|Audio effects: voice-changing (child voice/male voice), reverberation (KTV), ear monitoring adjustment, switch special effects in real time.|[API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_device_audio_effect_store/AudioEffectStore-class.html)|
+|**BaseBeautyStore**|Basic beauty filter: adjust skin smoothing/whitening/rosy (0-100 levels), reset beauty status, sync effect parameters.|[API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_device_base_beauty_store/BaseBeautyStore-class.html)|
 
 ## FAQs
 
-### Audience Enters the Room with No Sound
+### No Sound After Audience Joins Room
 - **Check device permissions**: Please ensure `App` has declared and obtained system authorization for microphone in `Info.plist` (iOS) or `AndroidManifest.xml` (Android).
 
 - **Check the homeowner side**: Whether the room owner has normally called `DeviceStore.shared.openLocalMicrophone()` to open the microphone.
 
 - **Check the network**: Please check whether the device network connection is normal.
 
-### Microphone Position List Not Displayed or Refreshed
+### Seat List Not Displayed or Updated
 - **Check Store initialization**: Please ensure you have already used the same `liveID` to correctly create the `LiveSeatStore` instance (`LiveSeatStore.create(liveID)`) before `createLive` or `joinLive`.
 
 - **Check data listening**: Please check whether you have used `addListener` correctly to listen to `liveSeatStore.liveSeatState.seatList`, and ensure to call `removeListener` in `dispose` to remove listener.