@tencent-rtc/mcp 1.3.9 → 1.4.1

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

@@ -7,12 +7,11 @@
 
 - **Anchor invitation to speak**: The Anchor can proactively initiate mic connection to any audience in the live streaming room.
 
-
 ## Implementation Steps
 
 ### Step 1: Integrating the Component
 
-Refer to [Quick Access](https://write.woa.com/document/200455640177692672) for seamless integration with **AtomicXCore** and complete **LiveCoreWidget** access.
+Refer to Quick Access for seamless integration with **AtomicXCore** and complete **LiveCoreWidget** access.
 
 After integration, start implementing the co-anchoring function.
 
@@ -23,21 +22,20 @@ After integration, start implementing the co-anchoring function.
 As an audience member, your core task is to **initiate application, receive results** and **become a listener**.
 1. **Initiate mic connection**
 
-
    When the user clicks the "apply for mic connection" button on the interface, call the `applyForSeat` method.
 
    ``` java
    import 'package:atomic_x_core/atomicxcore.dart';
-   
+
    final String liveId = "room ID";
    final CoGuestStore guestStore = CoGuestStore.create(liveId);
-   
+
    // User clicks "apply for mic connection"
    void requestToConnect() async {
        // seatIndex: The microphone slot index, value range is -1 (auto select an empty slot) and [0, maximum number of microphone slots in the current room -1], timeout: request timeout period (seconds)
        final result = await guestStore.applyForSeat(
-           seatIndex: 0, 
-           timeout: 30, 
+           seatIndex: 0,
+           timeout: 30,
            extraInfo: null,
        );
        if (result.isSuccess) {
@@ -49,18 +47,17 @@ As an audience member, your core task is to **initiate application, receive resu
    ```
 2. **Listen to the anchor's response**
 
-
    By adding a listener through `addGuestListener`, you can receive the anchor's processing result.
 
    ``` java
    late GuestListener _guestListener;
-   
+
    // Subscribe to events when your Widget is initialized
    void subscribeGuestEvents() {
        _guestListener = GuestListener(
            onApplicationAccepted: (hostUser) {
                print("Anchor ${hostUser.userName} agreed to your request, preparing to connect mic");
-               // 1. Turn on the camera, microphone 
+               // 1. Turn on the camera, microphone
                DeviceStore.shared.openLocalCamera(isFront: true);
                DeviceStore.shared.openLocalMicrophone();
                // 2. Update the UI here, such as disabling the apply button and displaying the mic connection state
@@ -81,7 +78,7 @@ As an audience member, your core task is to **initiate application, receive resu
        );
        guestStore.addGuestListener(_guestListener);
    }
-   
+
    @override
    void dispose() {
        guestStore.removeGuestListener(_guestListener);
@@ -90,7 +87,6 @@ As an audience member, your core task is to **initiate application, receive resu
    ```
 3. **Leave the mic**
 
-
    When a mic-connecting audience wants to end the interaction, call the `disconnect` method to return to general audience status.
 
    ``` java
@@ -106,7 +102,6 @@ As an audience member, your core task is to **initiate application, receive resu
    ```
 4. **(Optional) Cancel application**
 
-
    If the audience wants to withdraw the application before anchor processing, they can call the API `cancelApplication`.
 
    ``` java
@@ -126,17 +121,16 @@ As an audience member, your core task is to **initiate application, receive resu
 As an Anchor, your core task is to **receive applications, show the Application List** and **process applications**.
 1. **Listen for new mic connection requests**
 
-
    By adding a listener through `addHostListener`, you can receive immediate notification when a new audience applies and get prompted.
 
    ``` java
    import 'package:atomic_x_core/atomicxcore.dart';
-   
+
    final String liveId = "room ID";
    final CoGuestStore guestStore = CoGuestStore.create(liveId);
    late HostListener _hostListener;
    late final VoidCallback _applicantsChangedListener = _onApplicantsChanged;
-   
+
    // Subscribe to anchor event
    void subscribeHostEvents() {
        _hostListener = HostListener(
@@ -153,7 +147,7 @@ As an Anchor, your core task is to **receive applications, show the Application
        );
        guestStore.addHostListener(_hostListener);
    }
-   
+
    @override
    void dispose() {
        guestStore.removeHostListener(_hostListener);
@@ -162,7 +156,6 @@ As an Anchor, your core task is to **receive applications, show the Application
    ```
 2. **Show application list**
 
-
    `CoGuestStore`'s `coGuestState` maintains the current applicant list in real time. You can listen to it to update your UI.
 
    ``` java
@@ -170,7 +163,7 @@ As an Anchor, your core task is to **receive applications, show the Application
    void subscribeApplicants() {
        guestStore.coGuestState.applicants.addListener(_applicantsChangedListener);
    }
-   
+
    void _onApplicantsChanged() {
        final applicants = guestStore.coGuestState.applicants.value;
        print("Current number of applicants: ${applicants.length}");
@@ -179,7 +172,7 @@ As an Anchor, your core task is to **receive applications, show the Application
            _applicantList = applicants;
        });
    }
-   
+
    @override
    void dispose() {
        guestStore.coGuestState.applicants.removeListener(_applicantsChangedListener);
@@ -188,7 +181,6 @@ As an Anchor, your core task is to **receive applications, show the Application
    ```
 3. **Handle mic connection request**
 
-
    When you select an audience from the list and click "Grant" or "Reject", call the appropriate method.
 
    ``` java
@@ -199,7 +191,7 @@ As an Anchor, your core task is to **receive applications, show the Application
            print("Approved $userId's request, the other party is connecting mic");
        }
    }
-   
+
    // Anchor clicked the "Reject" button
    void reject(String userId) async {
        final result = await guestStore.rejectApplication(userId);
@@ -214,18 +206,17 @@ As an Anchor, your core task is to **receive applications, show the Application
 #### Anchor Implementation
 1. **Initiate invitation to audience**
 
-
    When the Anchor selects someone from the audience list and clicks "invite to mic connection", call the `inviteToSeat` method.
 
    ``` java
    // Anchor selects audience and initiates invitation
    void invite(String userId) async {
-       // inviteeID: The invitee ID, seatIndex: The microphone slot index, value range is -1 (auto select an empty slot) and [0, maximum number of microphone slots in the current room -1] 
+       // inviteeID: The invitee ID, seatIndex: The microphone slot index, value range is -1 (auto select an empty slot) and [0, maximum number of microphone slots in the current room -1]
        // timeout: invitation timeout duration
        final result = await guestStore.inviteToSeat(
            inviteeID: userId,
            seatIndex: 0,
-           timeout: 30, 
+           timeout: 30,
            extraInfo: null,
        );
        if (result.isSuccess) {
@@ -235,7 +226,6 @@ As an Anchor, your core task is to **receive applications, show the Application
    ```
 2. **Listen to the audience response**
 
-
    Listen to the invitation event response via `HostListener`.
 
    ``` java
@@ -253,7 +243,6 @@ As an Anchor, your core task is to **receive applications, show the Application
 #### Client Implementation
 1. **Receive the anchor's invitation**
 
-
    Listen to the invitation event via `GuestListener`.
 
    ``` java
@@ -268,22 +257,21 @@ As an Anchor, your core task is to **receive applications, show the Application
    ```
 2. **Respond to invitation**
 
-
    When the user makes a selection in the pop-up dialog box, call the appropriate method.
 
    ``` java
    String inviterId = "Anchor ID initiating invitation"; // Obtain from onInvitationReceived callback
-   
+
    // User click "Accept"
    void acceptInvitation() async {
        final result = await guestStore.acceptInvitation(inviterId);
        if (result.isSuccess) {
-           // Turn on the camera, microphone  
+           // Turn on the camera, microphone
            DeviceStore.shared.openLocalCamera(isFront: true);
            DeviceStore.shared.openLocalMicrophone();
        }
    }
-   
+
    // User click "Reject"
    void rejectInvitation() async {
        await guestStore.rejectInvitation(inviterId);
@@ -292,10 +280,7 @@ As an Anchor, your core task is to **receive applications, show the Application
 
 ### Execution Effect
 
-After integrating the above feature implementation, perform a co-streaming operation using two audiences and an Anchor separately. Audience A turns on the camera and microphone simultaneously, while Audience B turns on microphone only. The execution effect is as follows. You can refer to the next chapter [Refine UI Details](https://write.woa.com/#.E5.AE.8C.E5.96.84-ui-.E7.BB.86.E8.8A.82) to customize your desired UI logic.
-
-![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100032457995/4bc40212f76011f08586525400380f7d.png)
-
+After integrating the above feature implementation, perform a co-streaming operation using two audiences and an Anchor separately. Audience A turns on the camera and microphone simultaneously, while Audience B turns on microphone only. The execution effect is as follows. You can refer to the next chapter Refine UI Details to customize your desired UI logic.
 
 ## Refine UI Details
 
@@ -305,25 +290,22 @@ You can use the "slot" capacity provided by the `VideoWidgetBuilder` parameter o
 
 #### **Effect**
 
-![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100032457995/20cd025ff76111f0831c52540073fd3b.png)
-
-
 #### **Implementation Method**
 - **Step 1**: Create a foreground view (**CustomSeatForegroundView**) used for displaying user information above the video stream.
 
    ``` java
    import 'package:flutter/material.dart';
    import 'package:rtc_room_engine/rtc_room_engine.dart';
-   
+
    /// Custom user information floating view (foreground)
    class CustomSeatForegroundView extends StatelessWidget {
        final SeatFullInfo seatInfo;
-   
+
        const CustomSeatForegroundView({
-           Key? key, 
+           Key? key,
            required this.seatInfo,
        }) : super(key: key);
-   
+
        @override
        Widget build(BuildContext context) {
            return Container(
@@ -355,16 +337,16 @@ You can use the "slot" capacity provided by the `VideoWidgetBuilder` parameter o
    ``` java
    import 'package:flutter/material.dart';
    import 'package:rtc_room_engine/rtc_room_engine.dart';
-   
+
    /// Custom avatar placeholder view (background)
    class CustomSeatBackgroundView extends StatelessWidget {
        final SeatFullInfo seatInfo;
-   
+
        const CustomSeatBackgroundView({
-           Key? key, 
+           Key? key,
            required this.seatInfo,
        }) : super(key: key);
-   
+
        @override
        Widget build(BuildContext context) {
            final avatarUrl = seatInfo.userInfo.avatarUrl;
@@ -379,8 +361,8 @@ You can use the "slot" capacity provided by the `VideoWidgetBuilder` parameter o
                            ClipOval(
                                child: avatarUrl.isNotEmpty
                                    ? Image.network(
-                                       avatarUrl, 
-                                       width: 60, 
+                                       avatarUrl,
+                                       width: 60,
                                        height: 60,
                                        fit: BoxFit.cover,
                                        errorBuilder: (context, error, stackTrace) {
@@ -402,7 +384,7 @@ You can use the "slot" capacity provided by the `VideoWidgetBuilder` parameter o
                ),
            );
        }
-   
+
        Widget _buildDefaultAvatar() {
            return Container(
                width: 60,
@@ -419,40 +401,40 @@ You can use the "slot" capacity provided by the `VideoWidgetBuilder` parameter o
    import 'package:flutter/material.dart';
    import 'package:atomic_x_core/atomicxcore.dart';
    import 'package:rtc_room_engine/rtc_room_engine.dart';
-   
+
    /// Live streaming page with custom connection view
    class CustomCoGuestLiveWidget extends StatefulWidget {
        final String liveId;
-   
+
        const CustomCoGuestLiveWidget({
-           Key? key, 
+           Key? key,
            required this.liveId,
        }) : super(key: key);
-   
+
        @override
        State<CustomCoGuestLiveWidget> createState() => _CustomCoGuestLiveWidgetState();
    }
-   
+
    class _CustomCoGuestLiveWidgetState extends State<CustomCoGuestLiveWidget> {
        late LiveCoreController _controller;
-   
+
        @override
        void initState() {
            super.initState();
            _controller = LiveCoreController.create();
            _controller.setLiveID(widget.liveId);
        }
-   
+
        @override
        void dispose() {
            _controller.dispose();
            super.dispose();
        }
-   
+
        /// Build a custom view for the mic-connecting audience
        Widget _buildCoGuestWidget(
-           BuildContext context, 
-           SeatFullInfo seatFullInfo, 
+           BuildContext context,
+           SeatFullInfo seatFullInfo,
            ViewLayer viewLayer,
        ) {
            if (viewLayer == ViewLayer.foreground) {
@@ -463,7 +445,7 @@ You can use the "slot" capacity provided by the `VideoWidgetBuilder` parameter o
                return CustomSeatBackgroundView(seatInfo: seatFullInfo);
            }
        }
-   
+
        @override
        Widget build(BuildContext context) {
            return Scaffold(
@@ -479,110 +461,24 @@ You can use the "slot" capacity provided by the `VideoWidgetBuilder` parameter o
    ```
 
 #### **Parameter description:**
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >**Parameter**</td>
-
-<td rowspan="1" colSpan="1" >**Type**</td>
-
-<td rowspan="1" colSpan="1" >**Note**</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`seatFullInfo`</td>
-
-<td rowspan="1" colSpan="1" >`SeatFullInfo`</td>
-
-<td rowspan="1" colSpan="1" >Seat information object, containing the Anchor's detailed information.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`seatFullInfo.userInfo.userId`</td>
-
-<td rowspan="1" colSpan="1" >`String`</td>
-
-<td rowspan="1" colSpan="1" >Anchor's user ID.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`seatFullInfo.userInfo.userName`</td>
-
-<td rowspan="1" colSpan="1" >`String`</td>
-
-<td rowspan="1" colSpan="1" >On-mic user's nickname.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`seatFullInfo.userInfo.avatarUrl`</td>
-
-<td rowspan="1" colSpan="1" >`String`</td>
-
-<td rowspan="1" colSpan="1" >On-mic user's profile photo URL.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`viewLayer`</td>
-
-<td rowspan="1" colSpan="1" >`ViewLayer`</td>
-
-<td rowspan="1" colSpan="1" >View hierarchy enumeration.<br>- `ViewLayer.foreground` represents the pendant view, always displayed on top of the video image.<br>- `ViewLayer.background` represents the background pendant view, located in the lower layer of the foreground view. It is displayed only when the corresponding user has no video stream (for example, when the camera is not turned on), usually used for displaying the default avatar or placeholder image of the user.</td>
-</tr>
-</table>
-
+| **Parameter** | **Type** | **Note** |
+| --- | --- | --- |
+| `seatFullInfo` | `SeatFullInfo` | Seat information object, containing the Anchor's detailed information. |
+| `seatFullInfo.userInfo.userId` | `String` | Anchor's user ID. |
+| `seatFullInfo.userInfo.userName` | `String` | On-mic user's nickname. |
+| `seatFullInfo.userInfo.avatarUrl` | `String` | On-mic user's profile photo URL. |
+| `viewLayer` | `ViewLayer` | View hierarchy enumeration.<br>- `ViewLayer.foreground` represents the pendant view, always displayed on top of the video image.<br>- `ViewLayer.background` represents the background pendant view, located in the lower layer of the foreground view. It is displayed only when the corresponding user has no video stream (for example, when the camera is not turned on), usually used for displaying the default avatar or placeholder image of the user. |
 
 ## API documentation
 
 For details about ALL public interfaces, properties, and methods of [CoGuestStore](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_co_guest_store/CoGuestStore-class.html) and its related classes, see the official API documentation of the [AtomicXCore](https://tencent-rtc.github.io/TUIKit_Flutter/index.html) framework. The related Stores used in this guide are 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" >LiveCoreWidget</td>
-
-<td rowspan="1" colSpan="1" >Core view component for live video stream display and interaction: Responsible for stream rendering and view widget processing, supporting scenarios such as Anchor live streaming, audience co-broadcasting, and cross-room connection with other anchors.</td>
-
-<td rowspan="1" colSpan="1" >[API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_view_live_live_core_widget/LiveCoreWidget-class.html)</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >LiveCoreController</td>
-
-<td rowspan="1" colSpan="1" >Controller for LiveCoreWidget: Used to set the live stream ID, control the preview, and perform other operations.</td>
-
-<td rowspan="1" colSpan="1" >[API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_view_live_live_core_widget/LiveCoreController-class.html)</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >VideoWidgetBuilder</td>
-
-<td rowspan="1" colSpan="1" >Video view adapter: Used for custom pendant views in scenarios such as mic-connecting audience, cross-room connection with other anchors, and PK.</td>
-
-<td rowspan="1" colSpan="1" >[API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_view_live_live_core_widget/VideoWidgetBuilder-class.html)</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >DeviceStore</td>
-
-<td rowspan="1" colSpan="1" >Audio/Video device control: Microphone (on/off, volume), camera (on/off, switchover, video quality), screen sharing, and real-time monitoring of device status.</td>
-
-<td rowspan="1" colSpan="1" >[API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_device_device_store/DeviceStore-class.html)</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >CoGuestStore</td>
-
-<td rowspan="1" colSpan="1" >Audience co-broadcasting management: Join microphone application/invite/grant/reject, attendee 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>
-</table>
-
+| **Store/Component** | **Feature Description** | **API Reference** |
+| --- | --- | --- |
+| LiveCoreWidget | Core view component for live video stream display and interaction: Responsible for stream rendering and view widget processing, supporting scenarios such as Anchor live streaming, audience co-broadcasting, and cross-room connection with other anchors. | [API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_view_live_live_core_widget/LiveCoreWidget-class.html) |
+| LiveCoreController | Controller for LiveCoreWidget: Used to set the live stream ID, control the preview, and perform other operations. | [API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_view_live_live_core_widget/LiveCoreController-class.html) |
+| VideoWidgetBuilder | Video view adapter: Used for custom pendant views in scenarios such as mic-connecting audience, cross-room connection with other anchors, and PK. | [API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_view_live_live_core_widget/VideoWidgetBuilder-class.html) |
+| DeviceStore | Audio/Video device control: Microphone (on/off, volume), camera (on/off, switchover, video quality), screen sharing, and real-time monitoring of device status. | [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/reject, attendee permission control (microphone/camera), state synchronization. | [API documentation](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_co_guest_store/CoGuestStore-class.html) |
 
 ## FAQs
 
@@ -597,12 +493,9 @@ For details about ALL public interfaces, properties, and methods of [CoGuestStor
 
 - `ViewLayer.background`: The background layer, displayed only when the corresponding user has no video stream (for example, when the camera is not turned on), usually used for displaying the default avatar or placeholder image of the user.
 
-
 ### Why Is My Custom View Not Displayed?
 - **Check VideoWidgetBuilder settings**: Please confirm the `LiveCoreWidget`'s `videoWidgetBuilder` parameter is correctly set.
 
 - **Check callback implementation**: Please check if the `coGuestWidgetBuilder` callback function is correctly implemented.
 
 - **Check the return value**: Ensure your callback function returns an effective `Widget` instance.
-
-