@tencent-rtc/mcp 1.3.9 → 1.4.0

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

@@ -1,8 +1,5 @@
 AtomicXCore provides the [CoGuestStore](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.live/-co-guest-store/index.html) and [LiveSeatStore](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.live/-live-seat-store/index.html) modules, which are designed to streamline the entire audience co-hosting workflow for live streaming scenarios. You do not need to manage complex state synchronization or signaling logic—simply invoke a few intuitive methods to enable seamless audio and video interactions between hosts and audience members. This guide explains how to quickly implement voice co-hosting features in your Android app using `CoGuestStore` and `LiveSeatStore`.
 
-![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182498/a85df260ca0611f09e745254007c27c5.png)
-
-
 ## Core Scenarios
 
 `CoGuestStore` and `LiveSeatStore` support the following primary live streaming scenarios:
@@ -12,12 +9,11 @@ AtomicXCore provides the [CoGuestStore](https://tencent-rtc.github.io/TUIKit_And
 
 - **Host Manages Mic Seats**: Hosts can manage mic seat users, including removing users, muting, and locking mic seats.
 
-
 ## Implementation
 
 ### Step 1: Component Integration
 
-Refer to the [Quick Start](https://write.woa.com/document/194571595678187521) guide to integrate **AtomicXCore** into your project.
+Refer to the Quick Start guide to integrate **AtomicXCore** into your project.
 
 ### Step 2: Implement Audience Mic-Link Request
 
@@ -26,16 +22,15 @@ Refer to the [Quick Start](https://write.woa.com/document/194571595678187521) gu
 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 to Co-host" button, call the `applyForSeat` method:
 
    ``` java
    import io.trtc.tuikit.atomicxcore.api.CompletionHandler
    import io.trtc.tuikit.atomicxcore.api.live.CoGuestStore
-   
+
    val liveId = "Room ID"
    val guestStore = CoGuestStore.create(liveId)
-   
+
    // User taps "Request to Co-host"
    fun requestToConnect() {
        // timeout: request timeout, e.g., 30 seconds
@@ -43,7 +38,7 @@ As an audience member, your main tasks are **initiating a request, handling the
            override fun onSuccess() {
                print("Co-hosting request sent, waiting for host to respond...")
            }
-   
+
            override fun onFailure(code: Int, desc: String) {
                print("Failed to send request: $desc")
            }
@@ -52,14 +47,13 @@ As an audience member, your main tasks are **initiating a request, handling the
    ```
 2. **Listen for Host Response**
 
-
    Subscribe to `GuestListener` to handle the host’s approval or rejection:
 
    ``` java
    import io.trtc.tuikit.atomicxcore.api.device.DeviceStore
    import io.trtc.tuikit.atomicxcore.api.live.GuestListener
    import io.trtc.tuikit.atomicxcore.api.live.LiveUserInfo
-   
+
    // Add listener during Activity/Fragment initialization
    fun subscribeGuestEvents() {
        val guestListener = object : GuestListener() {
@@ -81,7 +75,6 @@ As an audience member, your main tasks are **initiating a request, handling the
    ```
 3. **Leave Mic Proactively**
 
-
    To leave the mic seat and revert to audience status, call `disconnect`:
 
    ``` java
@@ -91,7 +84,7 @@ As an audience member, your main tasks are **initiating a request, handling the
            override fun onSuccess() {
                print("Successfully left the mic")
            }
-   
+
            override fun onFailure(code: Int, desc: String) {
                print("Failed to leave mic: $desc")
            }
@@ -100,7 +93,6 @@ As an audience member, your main tasks are **initiating a request, handling the
    ```
 4. **(Optional) Cancel Request**
 
-
    If the audience member wishes to withdraw their request before the host responds, call `cancelApplication`:
 
    ``` java
@@ -110,7 +102,7 @@ As an audience member, your main tasks are **initiating a request, handling the
            override fun onSuccess() {
                print("Request cancelled")
            }
-   
+
            override fun onFailure(code: Int, desc: String) {
                print("Failed to cancel request: $desc")
            }
@@ -123,17 +115,16 @@ 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**
 
-
    Subscribe to `HostListener` to receive notifications when an audience member requests to join the mic:
 
    ``` java
    import io.trtc.tuikit.atomicxcore.api.live.CoGuestStore
    import io.trtc.tuikit.atomicxcore.api.live.HostListener
    import io.trtc.tuikit.atomicxcore.api.live.LiveUserInfo
-   
+
    val liveId = "Room ID"
    val guestStore = CoGuestStore.create(liveId)
-   
+
    // Subscribe to host events
    val hostListener = object : HostListener() {
        override fun onGuestApplicationReceived(guestUser: LiveUserInfo) {
@@ -146,14 +137,13 @@ As the host, your main tasks are **receiving requests, displaying the request li
    ```
 2. **Display Request List**
 
-
    Subscribe to the `applicants` property in `CoGuestStore`’s state to update the UI in real time:
 
    ``` java
    import kotlinx.coroutines.CoroutineScope
    import kotlinx.coroutines.Dispatchers
    import kotlinx.coroutines.launch
-   
+
    // Subscribe to state changes
    fun observeApplicants() {
        CoroutineScope(Dispatchers.Main).launch {
@@ -166,7 +156,6 @@ As the host, your main tasks are **receiving requests, displaying the request li
    ```
 3. **Handle Mic-Link Requests**
 
-
    Approve or reject requests using the following methods:
 
    ``` java
@@ -178,14 +167,14 @@ As the host, your main tasks are **receiving requests, displaying the request li
                override fun onSuccess() {
                    print("Approved $userId's request. They are joining the mic.")
                }
-   
+
                override fun onFailure(code: Int, desc: String) {
                    print("Failed to approve request: $desc")
                }
            }
        )
    }
-   
+
    // Host taps "Reject"
    fun reject(userId: String) {
        guestStore.rejectApplication(
@@ -194,7 +183,7 @@ As the host, your main tasks are **receiving requests, displaying the request li
                override fun onSuccess() {
                    print("Rejected $userId's request")
                }
-   
+
                override fun onFailure(code: Int, desc: String) {
                    print("Failed to reject request: $desc")
                }
@@ -208,7 +197,6 @@ As the host, your main tasks are **receiving requests, displaying the request li
 #### Host Side Implementation
 1. **Invite Audience Mic**
 
-
    To invite an audience member, call `inviteToSeat`:
 
    ``` java
@@ -219,7 +207,7 @@ As the host, your main tasks are **receiving requests, displaying the request li
            override fun onSuccess() {
                print("Invitation sent to $userId, waiting for response...")
            }
-   
+
            override fun onFailure(code: Int, desc: String) {
                print("Failed to send invitation: $desc")
            }
@@ -228,7 +216,6 @@ As the host, your main tasks are **receiving requests, displaying the request li
    ```
 2. **Listen for Audience Response**
 
-
    Handle the audience member’s response via `HostListener`:
 
    ``` java
@@ -245,7 +232,6 @@ As the host, your main tasks are **receiving requests, displaying the request li
 #### Audience Side Implementation
 1. **Receive Host Invitation**
 
-
    Listen for invitations via `GuestListener`:
 
    ``` java
@@ -257,12 +243,11 @@ As the host, your main tasks are **receiving requests, displaying the request li
    ```
 2. **Respond to Invitation**
 
-
    Invoke the appropriate method based on the user’s choice:
 
    ``` java
    val inviterId = "Host ID who sent the invitation" // From onHostInvitationReceived
-   
+
    // User taps "Accept"
    fun accept() {
        guestStore.acceptInvitation(inviterId, object : CompletionHandler {
@@ -270,13 +255,13 @@ As the host, your main tasks are **receiving requests, displaying the request li
                // Enable microphone
                DeviceStore.shared().openLocalMicrophone(null)
            }
-   
+
            override fun onFailure(code: Int, desc: String) {
                print("Failed to accept invitation: $desc")
            }
        })
    }
-   
+
    // User taps "Reject"
    fun reject() {
        guestStore.rejectInvitation(inviterId, object : CompletionHandler {
@@ -303,7 +288,6 @@ On-mic users (including the host) can control their own microphone mute status v
 
 - **Unmute:** Call `unmuteMicrophone(completion)`.
 
-
 #### Example Code
 ``` java
 import io.trtc.tuikit.atomicxcore.api.live.LiveSeatStore
@@ -316,24 +300,9 @@ seatStore.unmuteMicrophone(null) // Unmute
 ```
 
 #### unmuteMicrophone Parameters
-<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" >`completion`</td>
-
-<td rowspan="1" colSpan="1" >`CompletionHandler?`</td>
-
-<td rowspan="1" colSpan="1" >Callback after operation completes.</td>
-</tr>
-</table>
-
+| **Parameter** | **Type** | **Description** |
+| --- | --- | --- |
+| `completion` | `CompletionHandler?` | Callback after operation completes. |
 
 ### Host Remotely Controls Mic Seat User’s Microphone
 
@@ -346,7 +315,6 @@ Hosts can forcibly mute or invite mic seat users to unmute.
 
 3. **User Unmutes Themselves:** After receiving an unlock notification, the user must call `unmuteMicrophone()` to resume audio transmission.
 
-
 #### Example Code
 
 ##### Host Side
@@ -396,60 +364,16 @@ seatStore.addLiveSeatEventListener(seatListener)
 ```
 
 #### closeRemoteMicrophone Parameters
-<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 ID of the target user.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`completion`</td>
-
-<td rowspan="1" colSpan="1" >`CompletionHandler?`</td>
-
-<td rowspan="1" colSpan="1" >Callback after request completes.</td>
-</tr>
-</table>
-
+| **Parameter** | **Type** | **Description** |
+| --- | --- | --- |
+| `userID` | `String` | The user ID of the target user. |
+| `completion` | `CompletionHandler?` | Callback after request completes. |
 
 #### openRemoteMicrophone Parameters
-<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 ID of the target user.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`completion`</td>
-
-<td rowspan="1" colSpan="1" >`CompletionHandler?`</td>
-
-<td rowspan="1" colSpan="1" >Callback after request completes.</td>
-</tr>
-</table>
-
+| **Parameter** | **Type** | **Description** |
+| --- | --- | --- |
+| `userID` | `String` | The user ID of the target user. |
+| `completion` | `CompletionHandler?` | Callback after request completes. |
 
 ### Host Removes On-Mic User from the Seat
 
@@ -458,7 +382,6 @@ seatStore.addLiveSeatEventListener(seatListener)
 
 2. **Event Notification:** The removed user receives the `onKickedOffSeat` event in `GuestListener`.
 
-
 #### Example Code
 ``` java
 // Remove "userB" from mic seat
@@ -479,32 +402,10 @@ override fun onKickedOffSeat(seatIndex: Int, hostUser: LiveUserInfo) {
 ```
 
 #### kickUserOutOfSeat Parameters
-<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 ID of the user to remove.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`completion`</td>
-
-<td rowspan="1" colSpan="1" >`CompletionHandler?`</td>
-
-<td rowspan="1" colSpan="1" >Callback after request completes.</td>
-</tr>
-</table>
-
+| **Parameter** | **Type** | **Description** |
+| --- | --- | --- |
+| `userID` | `String` | The user ID of the user to remove. |
+| `completion` | `CompletionHandler?` | Callback after request completes. |
 
 ### Host Locks and Unlocks Mic Seats
 
@@ -515,7 +416,6 @@ Hosts can lock or unlock specific mic seats.
 
 2. **Unlock Mic Seat:** Call `unlockSeat` to make the seat available again.
 
-
 #### Example Code
 ``` java
 // Lock mic seat 2
@@ -540,60 +440,16 @@ seatStore.unlockSeat(2, object : CompletionHandler {
 ```
 
 #### lockSeat Parameters
-<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 seat to lock.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`completion`</td>
-
-<td rowspan="1" colSpan="1" >`CompletionHandler?`</td>
-
-<td rowspan="1" colSpan="1" >Callback after request completes.</td>
-</tr>
-</table>
-
+| **Parameter** | **Type** | **Description** |
+| --- | --- | --- |
+| `seatIndex` | `Int` | Index of the mic seat to lock. |
+| `completion` | `CompletionHandler?` | Callback after request completes. |
 
 #### unlockSeat Parameters
-<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 seat to unlock.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`completion`</td>
-
-<td rowspan="1" colSpan="1" >`CompletionHandler?`</td>
-
-<td rowspan="1" colSpan="1" >Callback after request completes.</td>
-</tr>
-</table>
-
+| **Parameter** | **Type** | **Description** |
+| --- | --- | --- |
+| `seatIndex` | `Int` | Index of the mic seat to unlock. |
+| `completion` | `CompletionHandler?` | Callback after request completes. |
 
 ### Move Mic Seats
 
@@ -604,7 +460,6 @@ Hosts and mic seat users can call `moveUserToSeat` to move users between mic sea
 
 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
 import io.trtc.tuikit.atomicxcore.api.CompletionHandler
@@ -624,78 +479,20 @@ seatStore.moveUserToSeat("userC",
 ```
 
 #### moveUserToSeat Parameters
-<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 ID of the user to move.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`targetIndex`</td>
-
-<td rowspan="1" colSpan="1" >`Int`</td>
-
-<td rowspan="1" colSpan="1" >Target mic seat index.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`policy`</td>
-
-<td rowspan="1" colSpan="1" >`MoveSeatPolicy?`</td>
-
-<td rowspan="1" colSpan="1" >Seat movement policy if the target seat is occupied:<br>- `abortWhenOccupied`: Abort move if seat is occupied (default)<br>- `forceReplace`: Force replace the user on the target seat; replaced user will be removed<br>- `swapPosition`: Swap positions with the user on the target seat.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`completion`</td>
-
-<td rowspan="1" colSpan="1" >`CompletionHandler?`</td>
-
-<td rowspan="1" colSpan="1" >Callback after request completes.</td>
-</tr>
-</table>
-
+| **Parameter** | **Type** | **Description** |
+| --- | --- | --- |
+| `userID` | `String` | The user ID of the user to move. |
+| `targetIndex` | `Int` | Target mic seat index. |
+| `policy` | `MoveSeatPolicy?` | Seat movement policy if the target seat is occupied:<br>- `abortWhenOccupied`: Abort move if seat is occupied (default)<br>- `forceReplace`: Force replace the user on the target seat; replaced user will be removed<br>- `swapPosition`: Swap positions with the user on the target seat. |
+| `completion` | `CompletionHandler?` | Callback after request completes. |
 
 ## API Documentation
 
 For detailed information about all public interfaces, properties, and methods of [CoGuestStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/cogueststore), [LiveSeatStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/liveseatstore), and related classes, refer to the official [AtomicXCore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore) framework API documentation. The relevant 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 Documentation**</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >CoGuestStore</td>
-
-<td rowspan="1" colSpan="1" >Audience co-hosting management: co-hosting requests/invitations, approval/rejection, co-host member permission control (microphone/camera), state synchronization.</td>
-
-<td rowspan="1" colSpan="1" >[API Documentation](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.live/-co-guest-store/index.html)</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >LiveSeatStore</td>
-
-<td rowspan="1" colSpan="1" >Mic seat management: mute/unmute, lock/unlock mic seat, remove user from mic, remote microphone control, mic seat list state monitoring.</td>
-
-<td rowspan="1" colSpan="1" >[API Documentation](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.live/-live-seat-store/index.html)</td>
-</tr>
-</table>
-
+| **Store/Component** | **Feature Description** | **API Documentation** |
+| --- | --- | --- |
+| CoGuestStore | Audience co-hosting management: co-hosting requests/invitations, approval/rejection, co-host member permission control (microphone/camera), state synchronization. | [API Documentation](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.live/-co-guest-store/index.html) |
+| LiveSeatStore | Mic seat management: mute/unmute, lock/unlock mic seat, remove user from mic, remote microphone control, mic seat list state monitoring. | [API Documentation](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.live/-live-seat-store/index.html) |
 
 ## FAQs
 
@@ -706,7 +503,6 @@ The main differences are in business logic and UI design:
 
 - `Voice Room (Audio Chat Room)`**:** The mic seat grid is central. Do not use `LiveCoreView`; instead, build a grid UI (e.g., `RecyclerView`) based on `LiveSeatStore.state` (especially `seatList`). The UI displays each mic seat’s `SeatInfo`—occupied, muted, locked, or speaking—in real time. Only the microphone needs to be enabled.
 
-
 ### How do I update mic seat information (such as occupancy and mute status) in the UI in real time?
 
 Subscribe to the `seatList` property in `LiveSeatState`, which is a reactive `List<SeatInfo>`. When the array changes, update your mic seat UI. For each seat:
@@ -716,7 +512,6 @@ Subscribe to the `seatList` property in `LiveSeatState`, which is a reactive `Li
 
 - Use `seatInfo.userInfo.microphoneStatus` for the user’s microphone status.
 
-
 ### What is the difference between microphone interfaces in LiveSeatStore and DeviceStore?
 
 `DeviceStore` manages the physical microphone device, while `LiveSeatStore` manages mic seat business logic (audio stream).
@@ -726,14 +521,12 @@ Subscribe to the `seatList` property in `LiveSeatState`, which is a reactive `Li
 
 - `closeLocalMicrophone`: Stops audio capture and releases the microphone device.
 
-
    `LiveSeatStore:`
 
 - `muteMicrophone`: Mutes the audio stream sent to remote users; the microphone device remains active.
 
 - `unmuteMicrophone`: Unmutes the audio stream.
 
-
    **Recommended workflow:** "Open the device once, control mute/unmute while on mic"
 
 1. **When joining mic:** When an audience member successfully joins the mic, call `openLocalMicrophone` once to start the device.
@@ -741,5 +534,3 @@ Subscribe to the `seatList` property in `LiveSeatState`, which is a reactive `Li
 2. **While on mic:** All "mute" and "unmute" actions while on mic should use `muteMicrophone` and `unmuteMicrophone` to control the audio stream.
 
 3. **When leaving mic:** When leaving mic (e.g., calling `disconnect`), call `closeLocalMicrophone` to release the device.
-
-