@tencent-rtc/mcp 1.3.9 → 1.4.1

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

@@ -1,8 +1,5 @@
 **AtomicXCore** provides the [CoGuestStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/cogueststore) and [LiveSeatStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/liveseatstore) modules, which handle the complete workflow for audience mic-link requests in live streaming scenarios. 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`.
 
-![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182498/e4dd7827ca0611f0a7775254005ef0f7.png)
-
-
 ## Core Scenarios
 
 `CoGuestStore` and `LiveSeatStore` support the following core live interaction scenarios:
@@ -12,12 +9,11 @@
 
 - **Host Manages Mic Seats**: The host can manage users on mic seats, including removing users, muting, and locking seats.
 
-
 ## Implementation
 
 ### Step 1: Component Integration
 
-Refer to the [Quick Start](https://write.woa.com/document/194571595685527552) to integrate **AtomicXCore**.
+Refer to the Quick Start to integrate **AtomicXCore**.
 
 ### Step 2: Implement Audience Mic-Link Request
 
@@ -26,17 +22,16 @@ Refer to the [Quick Start](https://write.woa.com/document/194571595685527552) to
 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.
 
    ``` swift
    import AtomicXCore
-   
+
    let liveId = "Room ID"
    var guestStore: CoGuestStore {
        CoGuestStore.create(liveID: liveID)
    }
-   
+
    // User taps "Request Mic-Link"
    func requestToConnect() {
        // timeout: Request timeout, e.g., 30 seconds
@@ -52,13 +47,12 @@ As an audience member, your main tasks are **initiating a request, handling the
    ```
 2. **Listen for Host Response**
 
-
    Subscribe to `guestEventPublisher` to receive the host’s response.
 
    ``` swift
    import AtomicXCore
    import Combine
-   
+
    // Subscribe to events during view controller initialization
    func subscribeGuestEvents() {
        guestStore.guestEventPublisher
@@ -80,7 +74,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.
 
    ``` swift
@@ -98,7 +91,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`.
 
    ``` swift
@@ -120,18 +112,17 @@ 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 `hostEventPublisher` to be notified immediately when a new audience request arrives.
 
    ``` swift
    import AtomicXCore
    import Combine
-   
+
    let liveId = "Room ID"
    var guestStore: CoGuestStore {
        CoGuestStore.create(liveID: liveID)
    }
-   
+
    // Subscribe to host events
    guestStore.hostEventPublisher
        .sink { [weak self] event in
@@ -144,13 +135,12 @@ As the host, your main tasks are **receiving requests, displaying the request li
    ```
 2. **Display Request List**
 
-
    The `CoGuestStore` state maintains the current list of applicants in real time. Subscribe to it to refresh your UI.
 
    ``` swift
    import AtomicXCore
    import Combine
-   
+
    // Subscribe to state changes
    guestStore.state
        .subscribe(StatePublisherSelector(keyPath: \CoGuestState.applicants)) // Only care about applicant list changes
@@ -164,7 +154,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.
 
    ``` swift
@@ -176,7 +165,7 @@ As the host, your main tasks are **receiving requests, displaying the request li
            }
        }
    }
-   
+
    // Host taps "Reject" button
    func reject(userId: String) {
        guestStore.rejectApplication(userID: userId) { result in
@@ -192,7 +181,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.
 
    ``` swift
@@ -208,7 +196,6 @@ As the host, your main tasks are **receiving requests, displaying the request li
    ```
 2. **Listen for Audience Response**
 
-
    Listen for the `onHostInvitationResponded` event via `hostEventPublisher`.
 
    ``` swift
@@ -225,7 +212,6 @@ As the host, your main tasks are **receiving requests, displaying the request li
 #### Audience Side Implementation
 1. **Receive Host Invitation**
 
-
    Listen for the `onHostInvitationReceived` event via `guestEventPublisher`.
 
    ``` swift
@@ -238,12 +224,11 @@ As the host, your main tasks are **receiving requests, displaying the request li
    ```
 2. **Respond to Invitation**
 
-
    When the user makes a choice in the dialog, call the corresponding method.
 
    ``` swift
    let inviterId = "Host ID who sent the invitation" // Get from onHostInvitationReceived event
-   
+
    // User taps "Accept"
    func accept() {
        guestStore.acceptInvitation(inviterID: inviterId) { result in
@@ -253,7 +238,7 @@ As the host, your main tasks are **receiving requests, displaying the request li
            }
        }
    }
-   
+
    // User taps "Reject"
    func reject() {
        guestStore.rejectInvitation(inviterID: inviterId) { result in
@@ -275,7 +260,6 @@ On-mic users (including the host) can control their own microphone mute status v
 
 2. **Unmute:** Call `unmuteMicrophone(completion:)`.
 
-
 #### Example Code:
 ``` swift
 let seatStore = LiveSeatStore.create(liveID: liveId)
@@ -286,24 +270,9 @@ seatStore.unmuteMicrophone(completion: nil) // 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" >`CompletionClosure?`</td>
-
-<td rowspan="1" colSpan="1" >Callback after the operation completes.</td>
-</tr>
-</table>
-
+| **Parameter** | **Type** | **Description** |
+| --- | --- | --- |
+| `completion` | `CompletionClosure?` | Callback after the operation completes. |
 
 ### Host Remotely Controls On-Mic User’s Microphone
 
@@ -316,7 +285,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:
@@ -359,60 +327,16 @@ seatStore.liveSeatEventPublisher
 ```
 
 #### 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 userID of the target user.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`completion`</td>
-
-<td rowspan="1" colSpan="1" >`CompletionClosure?`</td>
-
-<td rowspan="1" colSpan="1" >Callback after the request completes.</td>
-</tr>
-</table>
-
+| **Parameter** | **Type** | **Description** |
+| --- | --- | --- |
+| `userID` | `String` | The userID of the target user. |
+| `completion` | `CompletionClosure?` | Callback after the 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 userID of the target user.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`completion`</td>
-
-<td rowspan="1" colSpan="1" >`CompletionClosure?`</td>
-
-<td rowspan="1" colSpan="1" >Callback after the request completes.</td>
-</tr>
-</table>
-
+| **Parameter** | **Type** | **Description** |
+| --- | --- | --- |
+| `userID` | `String` | The userID of the target user. |
+| `completion` | `CompletionClosure?` | Callback after the request completes. |
 
 ### Host Removes On-Mic User from the Seat
 
@@ -421,7 +345,6 @@ seatStore.liveSeatEventPublisher
 
 2. **Listen for Event Notification:** The removed user will receive the `onKickedOffSeat` event via `CoGuestStore.guestEventPublisher`.
 
-
 #### Example Code:
 ``` swift
 // Suppose you want to remove "userB"
@@ -453,32 +376,10 @@ guestStore
 ```
 
 #### 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 userID of the user to be removed from the mic seat.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`completion`</td>
-
-<td rowspan="1" colSpan="1" >`CompletionClosure?`</td>
-
-<td rowspan="1" colSpan="1" >Callback after the request completes.</td>
-</tr>
-</table>
-
+| **Parameter** | **Type** | **Description** |
+| --- | --- | --- |
+| `userID` | `String` | The userID of the user to be removed from the mic seat. |
+| `completion` | `CompletionClosure?` | Callback after the request completes. |
 
 ### Host Locks and Unlocks Mic Seats
 
@@ -489,7 +390,6 @@ The host can lock or unlock a specific mic seat.
 
 2. **Unlock Seat:** Call `unlockSeat` to unlock the seat, making it available again.
 
-
 #### Example Code:
 ``` swift
 // Lock seat #2
@@ -508,60 +408,16 @@ seatStore.unlockSeat(seatIndex: 2) { result in
 ```
 
 #### 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 seat to lock.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`completion`</td>
-
-<td rowspan="1" colSpan="1" >`CompletionClosure?`</td>
-
-<td rowspan="1" colSpan="1" >Callback after the request completes.</td>
-</tr>
-</table>
-
+| **Parameter** | **Type** | **Description** |
+| --- | --- | --- |
+| `seatIndex` | `Int` | Index of the seat to lock. |
+| `completion` | `CompletionClosure?` | Callback after the 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 seat to unlock.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`completion`</td>
-
-<td rowspan="1" colSpan="1" >`CompletionClosure?`</td>
-
-<td rowspan="1" colSpan="1" >Callback after the request completes.</td>
-</tr>
-</table>
-
+| **Parameter** | **Type** | **Description** |
+| --- | --- | --- |
+| `seatIndex` | `Int` | Index of the seat to unlock. |
+| `completion` | `CompletionClosure?` | Callback after the request completes. |
 
 ### Move Mic Seats
 
@@ -572,7 +428,6 @@ Hosts and on-mic users can call `moveUserToSeat(userID:targetIndex:policy:comple
 
 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:
 ``` swift
 seatStore.moveUserToSeat(userID: "userC",
@@ -587,78 +442,20 @@ seatStore.moveUserToSeat(userID: "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 userID 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 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" >`CompletionClosure?`</td>
-
-<td rowspan="1" colSpan="1" >Callback after the request completes.</td>
-</tr>
-</table>
-
+| **Parameter** | **Type** | **Description** |
+| --- | --- | --- |
+| `userID` | `String` | The userID of the user to move. |
+| `targetIndex` | `Int` | Target 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` | `CompletionClosure?` | Callback after the 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 mic-link management: mic-link requests/invitations/accept/reject, member permission control (microphone/camera), state synchronization.</td>
-
-<td rowspan="1" colSpan="1" >[API Documentation](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/cogueststore)</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >LiveSeatStore</td>
-
-<td rowspan="1" colSpan="1" >Mic seat management: mute/unmute, lock/unlock seats, remove users from mic, remote mic control, mic seat list state monitoring</td>
-
-<td rowspan="1" colSpan="1" >[API Documentation](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/liveseatstore)</td>
-</tr>
-</table>
-
+| **Store/Component** | **Feature Description** | **API Documentation** |
+| --- | --- | --- |
+| CoGuestStore | Audience mic-link management: mic-link requests/invitations/accept/reject, member permission control (microphone/camera), state synchronization. | [API Documentation](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/cogueststore) |
+| LiveSeatStore | Mic seat management: mute/unmute, lock/unlock seats, remove users from mic, remote mic control, mic seat list state monitoring | [API Documentation](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/liveseatstore) |
 
 ## FAQs
 
@@ -669,7 +466,6 @@ The main differences are in business logic and UI presentation:
 
 - `Voice Room:` The core is the mic seat grid. Do not use `LiveCoreView`; instead, build a grid UI (e.g., `UICollectionView`) based on the `LiveSeatStore`'s `state` (especially `seatList`). The UI focuses on real-time display of each seat’s `SeatInfo` status: occupied, muted, locked, and speaking status. Only the microphone needs to be enabled.
 
-
 ### How do I refresh mic seat info (e.g., occupied, muted) in the UI in real time?
 
 Subscribe to the `seatList` property in `LiveSeatState`, which is a reactive `[SeatInfo]` array. Any changes will notify you to re-render the mic seat list. Iterate through this array to:
@@ -679,7 +475,6 @@ Subscribe to the `seatList` property in `LiveSeatState`, which is a reactive `[S
 
 - Check mic status of the user via `seatInfo.userInfo.microphoneStatus`.
 
-
 ### What’s the difference between microphone interfaces in LiveSeatStore and DeviceStore?
 
 This is an important distinction. `DeviceStore` manages the physical device, while `LiveSeatStore` manages mic seat business logic (audio stream).
@@ -689,14 +484,12 @@ This is an important distinction. `DeviceStore` manages the physical device, whi
 
 - `closeLocalMicrophone`: Stops audio capture and releases the microphone device.
 
-
    `LiveSeatStore`:
 
 - `muteMicrophone`: Mute. Stops sending local audio stream to remote, but the microphone hardware remains running.
 
 - `unmuteMicrophone`: Unmute. Resumes sending audio stream to remote.
 
-
    **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.
@@ -704,5 +497,3 @@ This is an important distinction. `DeviceStore` manages the physical device, whi
 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.
-
-