@tencent-rtc/mcp 1.6.8 → 1.7.0

package/resource/knowledge/livekit/best-practice/common/admin-take-seat.md

@@ -0,0 +1,73 @@
+---
+title: "Voice Room Admin Seat-Taking and Seat Locking（语聊房 / 管理员 / 上麦 / takeSeat / lockSeat）"
+product: live
+frameworks: [android, ios, flutter]
+scope: platform_common
+tags: [voice room, admin, take seat, takeSeat, lockSeat, unlockSeat, seatMode, FREE, seat, host seat, owner approval, VoiceRoom]
+version_range: ">=2.0.0"
+---
+
+# Voice Room Admin Seat-Taking and Seat Locking
+
+## 1. Key Takeaways
+
+- An admin takes a seat by calling `takeSeat` with the seat index. There is no need to call `applyForSeat` — admins are **not restricted by `seatMode=APPLY`** and do **not need** owner approval.
+- Admins are **not restricted by `lockSeat`** — they can directly `takeSeat` to any seat (including seat 0, the host seat).
+- Regular users can only call `takeSeat` when `seatMode` is `FREE`, and they **are restricted by `lockSeat`**.
+- The seat management API in `LiveSeatStore` is consistent across all three platforms (Android/iOS/Flutter).
+
+## 2. Field / API Reference
+
+| Field / Capability | Purpose | Notes |
+|---|---|---|
+| `takeSeat` | Take a seat | Pass the seat index; admins are not restricted by `seatMode`/`lockSeat`; regular users require `seatMode=FREE` and the seat must be unlocked |
+| `lockSeat` | Lock a seat | After locking, regular users cannot `takeSeat`; admins are unaffected |
+| `unlockSeat` | Unlock a seat | After unlocking, regular users can `takeSeat` again |
+| `seatMode` | Seat-taking mode | Regular users can only `takeSeat` in `FREE` mode |
+| `LiveSeatStore` | Seat management | Provides `takeSeat`/`leaveSeat`/`lockSeat`/`unlockSeat` operations |
+| Owner | Room owner | Can lock/unlock seats |
+
+## 3. Mechanism & Sequence
+
+### Admin Taking a Seat
+
+Admin calls `takeSeat(index)` to take a seat directly (passing the target seat index) -> not restricted by `seatMode` -> no owner approval needed -> not restricted by `lockSeat` -> seat taken successfully.
+
+## 4. Standard Usage
+
+1. **Admin takes a seat**: Call `takeSeat(index)` where `index` is the target seat number (e.g., seat 0 for the host seat). Not restricted by `seatMode`/`lockSeat`.
+2. **Regular user takes a seat**: Confirm `seatMode=FREE` and the target seat is unlocked, then call `takeSeat(index)`.
+3. **Lock a seat**: Admin/owner calls `lockSeat(index)`. After locking, regular users cannot `takeSeat`, but admins are unaffected.
+4. **Unlock then take seat**: First call `unlockSeat(index)` to unlock, then the regular user can `takeSeat(index)`.
+
+```javascript
+// API is consistent across all three platforms (Android Kotlin / iOS Swift / Flutter Dart)
+// 1. 管理员直接上麦（不受 seatMode / lockSeat 限制，无需房主同意）
+liveSeatStore.takeSeat(0);   // 上麦到 0 号主持麦位
+```
+
+## 5. Expected Results
+
+- Admin `takeSeat(index)` succeeds immediately, not restricted by `seatMode`, no owner approval needed.
+- After `lockSeat`, an admin can still `takeSeat` on the same seat (admins are not restricted by seat locking).
+- Regular users can only `takeSeat` successfully when `seatMode=FREE`; if the seat is locked, it fails — `unlockSeat` must be called first.
+
+## 6. Common Pitfalls
+
+- Pitfall 1: Admin calls `applyForSeat` to take a seat (admins should call `takeSeat` directly — no application needed).
+- Pitfall 2: Assuming admin `takeSeat` requires owner approval (admins are not subject to this restriction).
+- Pitfall 3: Assuming `lockSeat` prevents admins from calling `takeSeat` on the same seat (admins are not restricted by seat locking — only regular users are).
+
+## 7. Problem Definition (retrieval hint)
+
+How a voice room admin directly takes a specified seat (including seat 0, the host seat), whether admins are restricted by `seatMode`/`lockSeat`, and the `seatMode` and locking conditions for regular users to take a seat.
+
+## 8. Alternative Queries (retrieval recall)
+
+- How does a voice room admin take seat 0?
+- Does admin `takeSeat` require owner approval?
+- Is admin seat-taking restricted by `seatMode`?
+- Can an admin `takeSeat` after `lockSeat`?
+- When can a regular user `takeSeat`?
+- Can a regular user take a seat when `seatMode=FREE`?
+- How to unlock a locked seat and take it?

package/resource/knowledge/livekit/best-practice/common/audience-leave-live.md

@@ -0,0 +1,81 @@
+---
+title: "Voice Room Audience Leaving and Seat State（语聊房 / 观众 / 上麦 / 下麦 / leaveLive）"
+product: live
+frameworks: [android, ios, flutter]
+scope: platform_common
+tags: [voice room, audience, take seat, leave seat, leaveLive, leaveSeat, exit, seat, re-take seat, VoiceRoom]
+version_range: ">=2.0.0"
+---
+
+# Voice Room Audience Leaving and Seat State
+
+## 1. Key Takeaways
+
+- When a seated audience member calls `leaveLive` to exit the voice room, they are automatically removed from the seat.
+- After exiting and re-entering the room, the user is **not seated** and must take a seat again.
+- The method for taking a seat depends on `seatMode`:
+  - `seatMode = FREE`: Call `takeSeat` directly.
+  - `seatMode = APPLY`: Call `applyForSeat` to submit a seat request; the owner/admin must approve before the user is seated.
+- `leaveLive` does **not require** calling `leaveSeat` first — exiting automatically removes the user from the seat.
+- Behavior is consistent across all three platforms (Android/iOS/Flutter).
+
+## 2. Field / API Reference
+
+| Field / Capability | Purpose | Notes |
+|---|---|---|
+| `leaveLive` | Exit the voice room | Exits the room and automatically leaves the seat |
+| `leaveSeat` | Manually leave a seat | Used for explicit seat departure; not required before `leaveLive` since exiting auto-leaves the seat |
+| `takeSeat` | Take a seat freely (`seatMode = FREE`) | Call directly after re-entering the room in free mode |
+| `applyForSeat` | Apply to take a seat (`seatMode = APPLY`) | Submit a request; owner/admin approval is required |
+| `seatMode` | Seat mode | `FREE`: free seat-taking; `APPLY`: requires approval |
+| Seat state | Whether the user is seated | Cleared after `leaveLive`; user must re-take a seat after re-entering |
+
+## 3. Mechanism & Sequence
+
+Seated audience calls `leaveLive` -> automatically leaves seat (no need to call `leaveSeat` first) -> exits room -> re-enters room -> seat state is empty, user is not seated -> choose seat-taking method based on `seatMode`:
+
+- `seatMode = FREE`: Call `takeSeat(seatIndex)` to take a seat directly.
+- `seatMode = APPLY`: Call `applyForSeat(seatIndex)` to submit a request and wait for owner/admin approval.
+
+## 4. Standard Usage
+
+```javascript
+// API is consistent across all three platforms (Android Kotlin / iOS Swift / Flutter Dart)
+// 1. 直接退出语聊房（会自动下麦，无需先 leaveSeat）
+liveListStore.leaveLive();
+
+// 2. 重新进房后，根据 seatMode 选择上麦方式
+// seatMode = FREE 时：直接上麦
+liveSeatStore.takeSeat(seatIndex);
+
+// seatMode = APPLY 时：申请上麦（需房主/管理员同意）
+liveSeatStore.applyForSeat(seatIndex);
+```
+
+## 5. Expected Results
+
+- After `leaveLive`, the user is automatically removed from the seat.
+- After re-entering the room, `LiveSeatStore.seatList` does not contain the user.
+- `seatMode = FREE`: Calling `takeSeat` succeeds and the user is seated again.
+- `seatMode = APPLY`: After calling `applyForSeat`, the user waits for approval; once approved, the user is seated again.
+
+## 6. Common Pitfalls
+
+- Pitfall 1: Calling `leaveSeat` before exiting (not necessary — `leaveLive` automatically leaves the seat).
+- Pitfall 2: Assuming the user is still seated after re-entering the room (they must take a seat again).
+- Pitfall 3: Worrying that `leaveLive` does not leave the seat, causing a stale seat entry (it auto-leaves — no stale entries).
+- Pitfall 4: Calling `takeSeat` directly when `seatMode = APPLY` (use `applyForSeat` instead — otherwise it will fail or have no effect).
+
+## 7. Problem Definition (retrieval hint)
+
+Whether a seated audience member is automatically removed from the seat after calling `leaveLive`, whether the user is still seated after re-entering, whether `leaveLive` requires calling `leaveSeat` first, and how to re-take a seat under different `seatMode` values (FREE/APPLY) using `takeSeat` vs `applyForSeat`.
+
+## 8. Alternative Queries (retrieval recall)
+
+- Does a voice room audience member leave the seat after exiting?
+- Do I need to take a seat again after re-entering?
+- Do I need to call `leaveSeat` before `leaveLive`?
+- Is the seat cleared when a voice room audience member exits?
+- How to re-take a seat after entering the room?
+- How to take a seat when `seatMode = APPLY`?
+- When to use `takeSeat` vs `applyForSeat`?

package/resource/knowledge/livekit/best-practice/common/voice-room-no-audio-troubleshoot.md

@@ -0,0 +1,100 @@
+---
+title: "Voice Room Audience Cannot Hear Anchor — Troubleshooting Guide（语聊房 / 观众听不到声音 / 没声音）"
+product: live
+frameworks: [android, ios, flutter]
+scope: platform_common
+tags: [voice room, no audio, no sound, troubleshoot, LiveSeatStore, DeviceStore, takeSeat, openLocalMicrophone, unmuteMicrophone, LoginStore, joinLive, seatList, microphoneStatus, LiveSeatState, DeviceState]
+version_range: ">=2.0.0"
+---
+
+# Voice Room Audience Cannot Hear Anchor — Troubleshooting Guide
+
+## 1. Key Takeaways
+
+- When the audience cannot hear the anchor, troubleshoot in order from anchor side to audience side: room → seat → microphone → mute → login → room entry — checking state at each layer.
+- Anchor side: confirm the anchor is seated (`seatList`), microphone is open (`DeviceStore.microphoneStatus`), and not muted (`userInfo.microphoneStatus`).
+- Audience side: confirm login status (`loginStatus == LOGIN`), room entry (`currentLive`), and device volume is normal.
+- API and state structures are consistent across all three platforms (Android/iOS/Flutter); the troubleshooting flow is universal.
+
+## 2. Field / API Reference
+
+| Field / Capability | Purpose | Notes |
+|---|---|---|
+| `LiveSeatStore` | Seat management | Provides `seatList`; check whether anchor info is present to determine if the anchor is seated |
+| `LiveSeatStore.seatList` | Seat list | Check for anchor info; the anchor item's `userInfo.microphoneStatus` indicates mute state |
+| `takeSeat` | Take a seat | Called when the anchor is not seated |
+| `DeviceStore` | Device management | Provides `DeviceState`; check `microphoneStatus` to determine if the microphone is open |
+| `DeviceState.microphoneStatus` | Microphone on/off state | Determines whether the anchor's microphone is open |
+| `openLocalMicrophone` | Open microphone | Called when the microphone is closed |
+| `unmuteMicrophone` | Resume audio publishing | Called when the anchor is muted |
+| `LoginStore` | Login management | Provides `loginState.loginStatus`; `LOGIN` means logged in |
+| `LiveListStore` | Live room management | Provides `LiveListState.currentLive`; determines if room entry succeeded |
+| `joinLive` | Enter room | Called when the audience has not entered the room |
+
+## 3. Mechanism & Sequence
+
+### Anchor-Side Troubleshooting (in order)
+
+1. Is the anchor seated? Check whether `LiveSeatStore.seatList` contains anchor info; if not, call `takeSeat`.
+2. Is the microphone open? Check `DeviceState.microphoneStatus`; if closed, call `openLocalMicrophone`.
+3. Is the anchor muted? Check the anchor item's `userInfo.microphoneStatus` in `seatList`; if muted, call `unmuteMicrophone`.
+
+### Audience-Side Troubleshooting (in order)
+
+1. Is the user logged in? Check whether `loginState.loginStatus` is `LOGIN`.
+2. Has the user entered the room? Check whether `LiveListState.currentLive` matches the current live room; if not, call `joinLive`.
+3. Is the device volume normal? Verify the system volume is audible.
+
+## 4. Standard Usage
+
+Follow this flow step by step — check the state and handle accordingly:
+
+```text
+观众听不到主播说话
+│
+├── 主播侧排查
+│   ├── 1. 是否在麦上？  → 否 → takeSeat 上麦
+│   │      查看 LiveSeatStore.seatList
+│   ├── 2. 麦克风是否打开？ → 否 → openLocalMicrophone
+│   │      查看 DeviceState.microphoneStatus
+│   └── 3. 是否静音？ → 是 → unmuteMicrophone
+│          查看 seatList 主播 userInfo.microphoneStatus
+│
+└── 观众侧排查
+    ├── 1. 是否已登录？ → 否 → 登录
+    │      查看 loginState.loginStatus == LOGIN
+    ├── 2. 是否进房？ → 否 → joinLive 进房
+    │      查看 LiveListState.currentLive
+    └── 3. 手机音量正常？ → 否 → 调整音量
+```
+
+## 5. Expected Results
+
+- Anchor's `LiveSeatStore.seatList` contains anchor info: anchor is seated and can publish audio.
+- `DeviceState.microphoneStatus` is open: microphone is capturing audio.
+- `userInfo.microphoneStatus` is open: not muted, audio is being published normally.
+- Audience `loginStatus == LOGIN`: logged in.
+- `LiveListState.currentLive` matches the current live room: room entry succeeded.
+- If all conditions above are met and the audience still cannot hear audio: check device volume or contact the development team.
+
+## 6. Common Pitfalls
+
+- Pitfall 1: Only troubleshooting the audience side while ignoring the anchor's seat/microphone/mute state.
+- Pitfall 2: Confusing `DeviceState.microphoneStatus` (device on/off) with `userInfo.microphoneStatus` (mute state) — the former is local device capture, the latter is the remote-visible state.
+- Pitfall 3: Anchor publishes audio without taking a seat (taking a seat is a prerequisite for publishing).
+- Pitfall 4: Audience has not entered the room (`currentLive` is incorrect) but assumes the anchor has no audio.
+- Pitfall 5: Skipping login status check and directly troubleshooting the audio pipeline.
+
+## 7. Problem Definition (retrieval hint)
+
+When a voice room audience member cannot hear the anchor, how to troubleshoot layer by layer on the anchor side (seat/microphone/mute) and audience side (login/room entry/volume) to locate the issue.
+
+## 8. Alternative Queries (retrieval recall)
+
+- What to do when voice room audience cannot hear the anchor?
+- How to troubleshoot no sound from the microphone in a voice room?
+- Anchor is seated but audience cannot hear audio?
+- How to check if the anchor is muted using `microphoneStatus`?
+- No sound after entering a voice room?
+- How to determine if the anchor is seated in a voice room?
+- What to check first when audience cannot hear audio?

package/resource/knowledge/livekit/best-practice/common/voice-room-seat-list-change.md

@@ -0,0 +1,65 @@
+---
+title: "Voice Room Seat Microphone Status Synchronization（语聊房 / 麦位 / 麦克风状态更新同步）"
+product: live
+frameworks: [android, ios, flutter]
+scope: platform_common
+tags: [voice room, seat, microphone status, mic on, mic off, userMicrophoneStatus, SeatListChanged, muteMicrophone, unmuteMicrophone, closeMicrophone, openMicrophone, sync]
+version_range: ">=2.0.0"
+---
+
+# Voice Room Seat Microphone Status Synchronization
+
+## 1. Key Takeaways
+
+- Both the anchor side and the audience side listen for seat microphone status (`userMicrophoneStatus`) changes via **`SeatListChanged`**.
+- `userMicrophoneStatus` values: `0` = mic on; `1` = mic off (self-muted, can be re-opened by self); `2` = mic off (muted by admin, cannot be re-opened by self).
+- `userMicrophoneStatus` can only be changed by **the anchor or a seated audience member** through `mute/unmute` or `close/open` APIs.
+- The audience side only listens for status changes and does **not need** to call `mute/unmute` or `close/open` to modify `userMicrophoneStatus`.
+
+## 2. Field / API Reference
+
+| Field / Capability | Purpose | Notes |
+|---|---|---|
+| `userMicrophoneStatus` | Seat microphone on/off state | `0` = mic on; `1` = mic off (self-muted, can reopen); `2` = mic off (admin-muted, cannot reopen) |
+| `SeatListChanged` | Seat list change event | Both anchor and audience listen to this for `userMicrophoneStatus` changes; SDK syncs automatically |
+| `muteMicrophone` / `unmuteMicrophone` | Mute / unmute | Called by anchor or seated audience; triggers `userMicrophoneStatus` change |
+| `closeMicrophone` / `openMicrophone` | Close / open microphone | Called by anchor or seated audience; triggers `userMicrophoneStatus` change |
+| Audience side | Read-only state | Only listens for status; does not call `mute/unmute` or `close/open` |
+
+## 3. Mechanism & Sequence
+
+Anchor or seated audience calls `mute/unmute` or `close/open` API -> triggers `userMicrophoneStatus` change -> SDK fires `SeatListChanged`, automatically syncing to all clients -> both anchor and audience receive the updated seat state via `SeatListChanged`.
+
+`userMicrophoneStatus` can only be changed by the anchor or a seated audience member via `mute/unmute` or `close/open` APIs; the audience side only listens for status and does not actively modify it.
+
+## 4. Standard Usage
+
+Both anchor and audience listen for `SeatListChanged` and update the UI based on `userMicrophoneStatus`.
+The anchor or a seated audience member changes the microphone state via `mute/unmute` or `close/open` APIs, and the SDK automatically syncs to all clients.
+
+## 5. Expected Results
+
+- After the anchor or seated audience calls `mute/unmute` or `close/open`, `userMicrophoneStatus` in `SeatListChanged` is updated on all clients.
+- `userMicrophoneStatus = 0`: mic is on.
+- `userMicrophoneStatus = 1`: mic is off (self-muted; can be re-opened by self).
+- `userMicrophoneStatus = 2`: mic is off (admin-muted; cannot be re-opened by self).
+- Audience side does not need to call `mute/unmute` or `close/open`; status is synced automatically by the SDK.
+
+## 6. Common Pitfalls
+
+- Pitfall 1: Audience calls `mute/unmute` or `close/open` to modify `userMicrophoneStatus` (not needed — status is auto-synced by SDK; audience side is read-only).
+- Pitfall 2: Assuming `userMicrophoneStatus = 1` and `2` mean the same thing (`1` = self-muted and can reopen; `2` = admin-muted and cannot reopen).
+- Pitfall 3: Assuming `userMicrophoneStatus` can be changed from the audience side (it can only be triggered by the anchor or a seated audience member via `mute/unmute` or `close/open`).
+
+## 7. Problem Definition (retrieval hint)
+
+The meaning of each `userMicrophoneStatus` value in a voice room seat, how it syncs to both anchor and audience via `SeatListChanged`, and which roles can change it through which APIs.
+
+## 8. Alternative Queries (retrieval recall)
+
+- Audience cannot see anchor's mic-on status in a voice room — what to do?
+- What do `userMicrophoneStatus` values 0/1/2 mean?
+- How does `SeatListChanged` sync seat microphone status?
+- Who can change `userMicrophoneStatus`?
+- Does the audience need to call `muteMicrophone` to update mic status?
+- After admin mutes a user, can the user reopen their mic?

package/resource/knowledge/livekit/best-practice/flutter/voice-room-anchor-start.md

@@ -0,0 +1,122 @@
+---
+title: "Voice Room Anchor Creates Room and Starts Streaming (Flutter)（语聊房 / 房主 / 开播 / createLive）"
+product: live
+frameworks: [flutter]
+scope: platform_specific
+tags: [voice room, anchor, start streaming, publish audio, createLive, openLocalMicrophone, muteMicrophone, unmuteMicrophone, LiveListStore, AudioSalon, keepOwnerOnSeat, seatMode, TakeSeatMode, Flutter, AtomicXCore]
+version_range: ">=2.0.0"
+---
+
+# Voice Room Anchor Creates Room and Starts Streaming (Flutter)
+
+## 1. Key Takeaways
+
+- Voice room streaming flow: construct `LiveInfo` (with `liveID`, `seatTemplate`, `seatMode`, `keepOwnerOnSeat`), call `createLive` to create the room; on success, call `openLocalMicrophone` to capture and publish audio so other users in the room can hear the anchor.
+- `liveID` is required; setting `keepOwnerOnSeat` to `true` makes the anchor automatically take a seat upon entering (taking a seat is a prerequisite for publishing audio — only seated users can publish audio streams in the room).
+- `seatTemplate` should be set to the voice room template `AudioSalon(n)`, where n is the maximum seat count supported by the plan or a value less than it.
+- `seatMode` sets the seat-taking mode (e.g., `TakeSeatMode.apply` for apply-to-take-seat).
+- `muteMicrophone` pauses publishing local audio; `unmuteMicrophone` resumes publishing local audio.
+
+## 2. Field / API Reference
+
+| Field / Capability | Purpose | Notes |
+|---|---|---|
+| `LiveInfo` | Room information | Dart constructor `LiveInfo({liveID, liveName, seatTemplate, seatMode, keepOwnerOnSeat})` |
+| `liveID` | Room ID | Required parameter for `createLive` |
+| `liveName` | Room name | Display name of the room |
+| `seatTemplate` | Seat layout template | Use `AudioSalon(n)` for voice rooms, where n ≤ max seats in plan |
+| `seatMode` | Seat-taking mode | e.g., `TakeSeatMode.apply` for apply-to-take-seat |
+| `keepOwnerOnSeat` | Auto-seat the owner | Set to `true` so the anchor automatically takes a seat upon entering |
+| `createLive(liveInfo)` | Create room (start streaming) | Pass `LiveInfo`, returns `Future<result>` for async handling |
+| `result.isSuccess` | Success flag | `true` means creation succeeded |
+| `result.message` | Error message | Returns error description on failure |
+| `openLocalMicrophone` | Capture and publish audio | Opens local microphone and publishes audio stream to the room |
+| `muteMicrophone` | Pause audio publishing | Pauses local audio stream while microphone remains open |
+| `unmuteMicrophone` | Resume audio publishing | Resumes local audio stream while microphone remains open |
+
+## 3. Mechanism & Sequence
+
+Construct `LiveInfo` (`liveID` required, `seatTemplate=AudioSalon(n)`, `seatMode` as needed, `keepOwnerOnSeat=true`) -> `await createLive(liveInfo)` -> `result.isSuccess` is `true`, anchor is auto-seated -> call `openLocalMicrophone` to capture and publish audio -> other users in the room hear the anchor.
+
+Taking a seat is a prerequisite for streaming: `keepOwnerOnSeat=true` ensures the anchor takes a seat before publishing audio. `muteMicrophone` / `unmuteMicrophone` are used to pause/resume during streaming.
+
+## 4. Standard Usage
+
+1. Construct `LiveInfo`: set `liveID`, `seatTemplate`, `seatMode`, `keepOwnerOnSeat`.
+2. Call `await _liveListStore.createLive(liveInfo)` to start streaming.
+3. Check `result.isSuccess`; on success, call `openLocalMicrophone` to capture and publish audio.
+4. Call `muteMicrophone` / `unmuteMicrophone` to pause/resume streaming as needed.
+
+```dart
+class _YourAnchorPageState extends State<YourAnchorPage> {
+  // ... 其他代码 ...
+  final String _liveID = "test_voice_room_001";
+
+  @override
+  void initState() {
+    super.initState();
+    // ... 其他代码 ...
+
+    // 开始语聊
+    _startLive();
+  }
+
+  Future<void> _startLive() async {
+    // 1. 准备 LiveInfo 对象
+    final liveInfo = LiveInfo(
+      // 2. 设置房间 id
+      liveID: _liveID,
+      // 3. 设置房间名称
+      liveName: "test 语聊房",
+      // 4. 设置语聊房布局模板（传入 9 即代表有 9 个麦位）
+      seatTemplate: AudioSalon(9),
+      // 5. 设置上麦模式，例如申请上麦
+      seatMode: TakeSeatMode.apply,
+      // 6. 设置主播开播后自动上麦
+      keepOwnerOnSeat: true,
+    );
+
+    // 7. 调用 createLive 开始直播
+    final result = await _liveListStore.createLive(liveInfo);
+
+    if (result.isSuccess) {
+      debugPrint("Response startLive onSuccess");
+      // 8. 房主创建成功后默认自动上麦，此时调用 openLocalMicrophone 采集并发布音频
+      _liveSeatStore.openLocalMicrophone();
+    } else {
+      debugPrint("Response startLive onError: ${result.message}");
+    }
+  }
+}
+```
+
+## 5. Expected Results
+
+- `result.isSuccess == true`: room created successfully, anchor is auto-seated.
+- After `openLocalMicrophone`: other users in the room can hear the anchor.
+- After `muteMicrophone`: local audio publishing is paused; after `unmuteMicrophone`: publishing resumes.
+- If `keepOwnerOnSeat` is not set to `true`: the anchor is not auto-seated and cannot publish audio.
+- `result.isSuccess == false`: streaming failed, `result.message` contains the error description.
+
+## 6. Common Pitfalls
+
+- Pitfall 1: Calling `openLocalMicrophone` without calling `createLive` first (cannot publish audio without creating a room).
+- Pitfall 2: Not setting `keepOwnerOnSeat` to `true`, so the anchor is not seated and audio publishing does not work.
+- Pitfall 3: Not setting `seatTemplate` or setting n beyond the plan's maximum seat count.
+- Pitfall 4: Confusing `muteMicrophone` (pauses audio stream publishing) with closing the microphone (stops audio capture).
+- Pitfall 5: Reusing `liveID` (it must be globally unique; otherwise creation fails).
+- Pitfall 6: `AudioSalon(9)` is a constructor form (not an enum); `seatMode` uses `TakeSeatMode.apply` (Dart enum lowercase).
+
+## 7. Problem Definition (retrieval hint)
+
+A Flutter voice room anchor needs to create a room and start audio streaming in the correct order, understanding the call timing and parameter meanings of `createLive`, `openLocalMicrophone`, `muteMicrophone`, and `unmuteMicrophone`.
+
+## 8. Alternative Queries (retrieval recall)
+
+- How does a Flutter voice room anchor start streaming?
+- What is the call order of `createLive` and `openLocalMicrophone` in Flutter?
+- How does a Flutter anchor take a seat and publish audio?
+- What does the `keepOwnerOnSeat` parameter do?
+- How to set the `AudioSalon` template for `seatTemplate`?
+- What is the difference between `muteMicrophone` and `unmuteMicrophone` in Flutter?
+- How to publish audio after creating a voice room?

package/resource/knowledge/livekit/best-practice/ios/voice-room-anchor-start.md

@@ -0,0 +1,126 @@
+---
+title: "Voice Room Anchor Creates Room and Starts Streaming (iOS)（语聊房 / 房主 / 开播 / createLive）"
+product: live
+frameworks: [ios]
+scope: platform_specific
+tags: [voice room, anchor, start streaming, publish audio, createLive, openLocalMicrophone, muteMicrophone, unmuteMicrophone, LiveListStore, AudioSalon, keepOwnerOnSeat, seatMode, iOS, Swift, AtomicXCore]
+version_range: ">=2.0.0"
+---
+
+# Voice Room Anchor Creates Room and Starts Streaming (iOS)
+
+## 1. Key Takeaways
+
+- Voice room streaming flow: construct `LiveInfo` (with `liveID`, `seatTemplate`, `keepOwnerOnSeat`, `seatMode`), call `createLive` to create the room; on success, call `openLocalMicrophone` to capture and publish audio so other users in the room can hear the anchor.
+- `liveID` is required; setting `keepOwnerOnSeat` to `true` makes the anchor automatically take a seat upon entering (taking a seat is a prerequisite for publishing audio — only seated users can publish audio streams in the room).
+- `seatTemplate` should be set to `SeatLayoutTemplate.AudioSalon(seatCount: n)`, where n is the maximum seat count supported by the plan or a value less than it.
+- `seatMode` sets the seat-taking mode (e.g., `.apply` for apply-to-take-seat).
+- `muteMicrophone` pauses publishing local audio; `unmuteMicrophone` resumes publishing local audio.
+
+## 2. Field / API Reference
+
+| Field / Capability | Purpose | Notes |
+|---|---|---|
+| `LiveInfo` | Room information | Contains `liveID`, `liveName`, `seatTemplate`, `keepOwnerOnSeat`, `seatMode`, etc. |
+| `liveID` | Room ID | Required parameter for `createLive` |
+| `liveName` | Room name | Display name of the room |
+| `seatTemplate` | Seat layout template | Use `SeatLayoutTemplate.AudioSalon(seatCount: n)` for voice rooms, where n ≤ max seats in plan |
+| `keepOwnerOnSeat` | Auto-seat the owner | Set to `true` so the anchor automatically takes a seat upon entering |
+| `seatMode` | Seat-taking mode | e.g., `.apply` for apply-to-take-seat |
+| `createLive(liveInfo)` | Create room (start streaming) | Pass `LiveInfo`, returns `Result` for async handling |
+| `openLocalMicrophone` | Capture and publish audio | Opens local microphone and publishes audio stream to the room |
+| `muteMicrophone` | Pause audio publishing | Pauses local audio stream while microphone remains open |
+| `unmuteMicrophone` | Resume audio publishing | Resumes local audio stream while microphone remains open |
+
+## 3. Mechanism & Sequence
+
+Construct `LiveInfo` (`liveID` required, `seatTemplate=AudioSalon(n)`, `keepOwnerOnSeat=true`, `seatMode` as needed) -> call `createLive` to create the room -> `case .success` callback fires, anchor is auto-seated -> call `openLocalMicrophone` to capture and publish audio -> other users in the room hear the anchor.
+
+Taking a seat is a prerequisite for streaming: `keepOwnerOnSeat=true` ensures the anchor takes a seat before publishing audio. `muteMicrophone` / `unmuteMicrophone` are used to pause/resume during streaming.
+
+## 4. Standard Usage
+
+1. Construct `LiveInfo`: set `liveID`, `seatTemplate`, `keepOwnerOnSeat`, `seatMode`.
+2. Call `createLive(liveInfo)` and handle success/failure in `switch result`.
+3. In `case .success`, call `openLocalMicrophone` to capture and publish audio.
+4. Call `muteMicrophone` / `unmuteMicrophone` to pause/resume streaming as needed.
+
+```swift
+import UIKit
+import AtomicXCore
+
+class YourAnchorViewController: UIViewController {
+    // ... 其他代码 ...
+    private let liveID = "test_voice_room_001"
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        // ... 其他代码 ...
+
+        // 开始语聊
+        startLive()
+    }
+
+    private func startLive() {
+        // 1. 准备 LiveInfo 对象
+        var liveInfo = LiveInfo()
+
+        // 2. 设置房间 id
+        liveInfo.liveID = liveID
+        // 3. 设置房间名称
+        liveInfo.liveName = "test 语聊房"
+        // 4. 设置语聊房布局模板（传入 9 即代表有 9 个麦位）
+        liveInfo.seatTemplate = SeatLayoutTemplate.AudioSalon(seatCount: 9)
+
+        // 5. 设置主播开播后自动上麦
+        liveInfo.keepOwnerOnSeat = true
+
+        // 6. 设置上麦模式，例如申请上麦
+        liveInfo.seatMode = .apply
+
+        // 7. 调用 createLive 开始直播
+        liveListStore.createLive(liveInfo) { [weak self] result in
+            guard let self = self else { return }
+            switch result {
+            case .success(let liveInfo):
+                print("Response startLive onSuccess")
+                // 8. 房主创建成功后默认自动上麦，此时调用 openLocalMicrophone 采集并发布音频
+                liveSeatStore.openLocalMicrophone(completion: nil)
+            case .failure(let errorInfo):
+                print("Response startLive onError: \(errorInfo.message)")
+            }
+        }
+    }
+}
+```
+
+## 5. Expected Results
+
+- `case .success` callback fires: room created successfully, anchor is auto-seated.
+- After `openLocalMicrophone`: other users in the room can hear the anchor.
+- After `muteMicrophone`: local audio publishing is paused; after `unmuteMicrophone`: publishing resumes.
+- If `keepOwnerOnSeat` is not set to `true`: the anchor is not auto-seated and cannot publish audio.
+- `case .failure(let errorInfo)` callback fires: streaming failed, `errorInfo.message` contains the error description.
+
+## 6. Common Pitfalls
+
+- Pitfall 1: Calling `openLocalMicrophone` without calling `createLive` first (cannot publish audio without creating a room).
+- Pitfall 2: Not setting `keepOwnerOnSeat` to `true`, so the anchor is not seated and audio publishing does not work.
+- Pitfall 3: Not setting `seatTemplate` or setting `seatCount` beyond the plan's maximum seat count.
+- Pitfall 4: Confusing `muteMicrophone` (pauses audio stream publishing) with closing the microphone (stops audio capture).
+- Pitfall 5: Reusing `liveID` (it must be globally unique; otherwise creation fails).
+- Pitfall 6: Forgetting `[weak self]` (to avoid retain cycles causing memory leaks); both `success` and `failure` branches of `switch result` must be handled.
+
+## 7. Problem Definition (retrieval hint)
+
+An iOS voice room anchor needs to create a room and start audio streaming in the correct order, understanding the call timing and parameter meanings of `createLive`, `openLocalMicrophone`, `muteMicrophone`, and `unmuteMicrophone`.
+
+## 8. Alternative Queries (retrieval recall)
+
+- How does an iOS voice room anchor start streaming?
+- What is the call order of `createLive` and `openLocalMicrophone` on iOS?
+- How does an iOS anchor take a seat and publish audio?
+- What does the `keepOwnerOnSeat` parameter do?
+- How to set the `AudioSalon` template for `seatTemplate`?
+- What is the difference between `muteMicrophone` and `unmuteMicrophone` on iOS?
+- How to publish audio after creating a voice room?

package/resource/knowledge/roomkit/best-practice/common/room-ghost-member.md

@@ -0,0 +1,70 @@
+---
+title: "Why Abnormally Exited Members Still Appear in TUIRoomKit Member List and How to Clean Up（TUIRoomKit / 异常退出 / 幽灵成员 / 心跳检测 / 离线检测）"
+product: room
+frameworks: [react, vue, web, android, ios, flutter]
+scope: platform_common
+tags: [TUIRoomKit, abnormal exit, ghost member, heartbeat detection, offline detection, kick from room, kick_user_out, disconnect callback, member list, room cleanup]
+version_range: ">=2.0.0"
+---
+
+# Why Abnormally Exited Members Still Appear in TUIRoomKit Member List and How to Clean Up
+
+## 1. Key Takeaways
+
+- When a user exits abnormally (process killed, network disconnected, page closed without calling leave), the member still appears in the remote member list. This is the expected behavior of the **video conferencing SDK backend heartbeat offline detection**.
+- Current rule: the backend removes an abnormally exited user from the room approximately **5–6 minutes** after heartbeat loss. Only then do remote participants receive the leave notification and update the member list.
+- **The heartbeat interval cannot be set very short by default**: short heartbeat intervals increase the risk of false kicks during network jitter, disrupting normal meeting experience.
+- If your business requires faster ghost member cleanup: Option 1 (submit a ticket to shorten heartbeat to ~2 minutes) or Option 2 (use IM disconnect callback + `kick_user_out` to kick immediately).
+
+## 2. Field / API Reference
+
+| Field / Capability | Purpose | Notes |
+|---|---|---|
+| Heartbeat offline detection | Detects user online status | Backend checks whether user heartbeat is lost |
+| Heartbeat loss | Signal of abnormal exit | Heartbeat stops when process is killed / network disconnected / page closed without leave |
+| Ghost member | Abnormally exited user still displayed | Removed from room after ~5–6 minutes |
+| `kick_user_out` | Kick a room member | Business backend calls this to immediately clean up |
+| `disconnect` callback | Disconnection callback | IM server detects user offline |
+| Heartbeat interval adjustment | Backend configuration | Can be shortened to ~2 minutes via support ticket |
+
+## 3. Mechanism & Sequence
+
+User exits abnormally (process killed, network disconnected, page closed without leave) -> Backend detects heartbeat loss -> After ~5–6 minutes, removes user from room -> Remote participants receive leave notification and update member list.
+
+The default heartbeat interval cannot be too short to avoid false kicks caused by network jitter. If the business requires faster cleanup:
+
+- **Option 1**: Submit a support ticket to shorten the backend heartbeat detection interval to ~2 minutes.
+- **Option 2**: Business backend listens for the IM `disconnect` callback to detect offline status, then calls `kick_user_out` to immediately remove the ghost member.
+
+## 4. Standard Usage
+
+1. **Option 1 (adjust heartbeat interval)**: Submit a support ticket to have the backend heartbeat detection interval shortened to ~2 minutes.
+2. **Option 2 (server-side proactive cleanup)**:
+   - Business backend listens for the IM server `disconnect` (disconnection) callback.
+   - Upon receiving the offline signal, calls `kick_user_out` to kick the room member.
+
+## 5. Expected Results
+
+- Abnormally exited users are removed from the room after ~5–6 minutes, and remote member list updates accordingly.
+- After adjusting heartbeat to ~2 minutes via support ticket, cleanup is faster.
+- Option 2 using `disconnect` callback + `kick_user_out` immediately removes ghost members.
+- Setting heartbeat too short increases the risk of false kicks during network jitter.
+
+## 6. Common Pitfalls
+
+- Pitfall 1: Expecting abnormally exited users to disappear from the member list immediately (heartbeat detection takes ~5–6 minutes).
+- Pitfall 2: Assuming the heartbeat interval can be set arbitrarily short (network jitter causes false kicks, disrupting normal meetings).
+- Pitfall 3: Overlooking that the business side can proactively kick members (`disconnect` callback + `kick_user_out`).
+
+## 7. Problem Definition (retrieval hint)
+
+Why an abnormally exited user still appears in the remote member list in TUIRoomKit, and how to clean up ghost members faster.
+
+## 8. Alternative Queries (retrieval recall)
+
+- What to do when an abnormally exited user still shows in the member list?
+- How to clean up ghost members in TUIRoomKit?
+- How long until a disconnected user is removed from the room?
+- Can the heartbeat detection interval be shortened?
+- Abnormally exited user keeps showing in the list?
+- How to kick an offline user?