@tencentcloud/sdk-mcp 1.4.6 → 1.6.0-beta.1

package/resource/knowledge/livekit/core-sdk/voice/android/voice-room-list.md

@@ -0,0 +1,523 @@
+`LiveListStore` 是 `AtomicXCore` 中负责管理直播房间列表、创建、加入以及维护房间状态的核心模块。通过 `LiveListStore`，您可以为您的应用构建完整的直播生命周期管理。
+
+## 核心功能
+- **直播列表拉取**：获取当前所有公开的直播间列表，支持分页加载。
+
+- **直播生命周期管理**：提供从创建、开播、加入、离开到结束直播的全套流程接口。
+
+- **直播信息更新**：主播可以随时更新直播间的公开信息，例如封面、公告等。
+
+- **实时事件监听**：监听直播结束、用户被踢出等关键事件。
+
+- **自定义业务数据**：强大的自定义元数据（`MetaData`）能力，允许您在房间内存储和同步任何业务相关的信息，例如直播状态、音乐信息、自定义角色等 。
+
+## 核心概念
+
+在开始集成之前，我们先通过下表了解一下 `LiveListStore` 相关的几个核心概念：
+
+|**核心概念**|**类型**|**核心职责与描述**|
+|---------|---------|---------|
+|`LiveInfo`|`data class`|代表一个直播间的所有信息模型。包含了直播 ID (`liveID`)、名称 (`liveName`)、房主信息 (`liveOwner`) 以及自定义元数据 (`metaData`) 等。|
+|`LiveListState`|`data class`|代表直播列表模块的当前状态。其核心属性 liveList 是一个 `StateFlow`，存储了拉取到的直播列表；`currentLive` 则代表用户当前所在的直播间信息。|
+|`LiveListListener`|`abstract class`|代表直播房间的全局事件。分为 `onLiveEnded` (直播结束) 和 `onKickedOutOfLive` (被踢出直播) 两种，用于处理关键的房间状态变更。|
+|`LiveListStore`|`abstract class`|代表直播房间的全局事件。分为 `.onLiveEnded` (直播结束) 和 `.onKickedOutOfLive` (被踢出直播) 两种，用于处理关键的房间状态变更。|
+
+## 实现步骤
+
+### 步骤1：组件集成
+- **视频直播**：请参考 开播与观看 集成 **AtomicXCore**，完成接入。
+
+- **语聊房**：请参考 开播与收听 集成 **AtomicXCore**，完成接入。
+
+### 步骤2：实现观众从直播列表进入直播间
+
+创建一个展示直播列表的页面，该页面使用 `RecyclerView` 来布局直播间卡片。当用户点击某个卡片时，获取该直播间的 `liveId`，并跳转到观众观看页面。
+``` kotlin
+import android.content.Intent
+import android.os.Bundle
+import android.view.LayoutInflater
+import android.view.View
+import android.view.ViewGroup
+import androidx.appcompat.app.AppCompatActivity
+import androidx.recyclerview.widget.GridLayoutManager
+import androidx.recyclerview.widget.RecyclerView
+import io.trtc.tuikit.atomicxcore.api.CompletionHandler
+import io.trtc.tuikit.atomicxcore.api.live.LiveInfo
+import io.trtc.tuikit.atomicxcore.api.live.LiveListStore
+import kotlinx.coroutines.*
+import kotlinx.coroutines.flow.*
+
+class LiveListActivity : AppCompatActivity() {
+    private val liveListStore = LiveListStore.shared()
+    private var liveList: List<LiveInfo> = emptyList()
+    private val coroutineScope = CoroutineScope(Dispatchers.Main)
+
+    private lateinit var recyclerView: RecyclerView
+    private lateinit var adapter: LiveListAdapter
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContentView(R.layout.activity_live_list)
+        setupUI()
+        bindStore()
+        fetchLiveList()
+    }
+
+    private fun bindStore() {
+        // 订阅 state，自动接收列表更新
+        coroutineScope.launch {
+            liveListStore.liveState.liveList.collect { fetchedList ->
+                liveList = fetchedList
+                adapter.notifyDataSetChanged()
+            }
+        }
+    }
+
+    private fun fetchLiveList() {
+        liveListStore.fetchLiveList(
+            cursor = "",
+            count = 20,
+            completion = object : CompletionHandler {
+                override fun onSuccess() {
+                    println("直播列表拉取成功")
+                }
+
+                override fun onFailure(code: Int, desc: String) {
+                    println("直播列表拉取失败: $desc")
+                }
+            }
+        )
+    }
+
+    // 当用户点击列表中的某个Item时
+    private fun onLiveItemClick(liveInfo: LiveInfo) {
+        // 创建观众观看页面，并将 liveId 传入
+        val intent = Intent(this, YourAudienceActivity::class.java)
+        intent.putExtra("liveId", liveInfo.liveID)
+        startActivity(intent)
+    }
+
+    // --- RecyclerView 相关方法 ---
+    private fun setupUI() {
+        recyclerView = findViewById(R.id.recyclerView)
+        adapter = LiveListAdapter(liveList) { liveInfo ->
+            onLiveItemClick(liveInfo)
+        }
+        recyclerView.layoutManager = GridLayoutManager(this, 2)
+        recyclerView.adapter = adapter
+    }
+
+    override fun onDestroy() {
+        super.onDestroy()
+        coroutineScope.cancel()
+    }
+}
+
+// RecyclerView Adapter
+class LiveListAdapter(
+    private var liveList: List<LiveInfo>,
+    private val onItemClick: (LiveInfo) -> Unit
+) : RecyclerView.Adapter<LiveListAdapter.LiveViewHolder>() {
+
+    class LiveViewHolder(itemView: View) : RecyclerView.ViewHolder(itemView) {
+        // 定义您的ViewHolder视图组件
+        // val titleTextView: TextView = itemView.findViewById(R.id.titleTextView)
+        // val coverImageView: ImageView = itemView.findViewById(R.id.coverImageView)
+    }
+
+    override fun onCreateViewHolder(parent: ViewGroup, viewType: Int): LiveViewHolder {
+        val view = LayoutInflater.from(parent.context)
+            .inflate(R.layout.item_live_card, parent, false)
+        return LiveViewHolder(view)
+    }
+
+    override fun onBindViewHolder(holder: LiveViewHolder, position: Int) {
+        val liveInfo = liveList[position]
+        // 设置数据到ViewHolder
+        // holder.titleTextView.text = liveInfo.liveName
+        // 加载封面图片等
+
+        holder.itemView.setOnClickListener {
+            onItemClick(liveInfo)
+        }
+    }
+
+    override fun getItemCount(): Int = liveList.size
+}
+
+```
+
+**LiveInfo 参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|`liveID`|`String`|直播间的唯一标识符。|
+|`liveName`|`String`|直播间的标题。|
+|`coverURL`|`String`|直播间的封面图片地址。|
+|`liveOwner`|[LiveUserInfo](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.live/-live-user-info/index.html)|房主的个人信息。|
+|`totalViewerCount`|`Int`|直播间的总观看人数。|
+|`categoryList`|`List<Int>`|直播间的分类标签列表。|
+|`notice`|`String`|直播间的公告信息。|
+|`metaData`|`Map<String: String>`|开发者自定义的元数据，用于实现复杂的业务场景。|
+
+## 功能进阶
+
+### 场景一：实现直播列表的分类展示
+
+在 App 的直播广场页，顶部设有"热门"、"音乐"、"游戏"等分类标签。用户点击不同的标签后，下方的直播列表会动态筛选，只展示对应分类的直播间，从而帮助用户快速发现感兴趣的内容。
+
+#### 实现方式
+
+核心是利用 `LiveInfo` 模型中的 `categoryList` 属性。当主播开播设置分类后，`fetchLiveList` 返回的 `LiveInfo` 对象中就会包含这些分类信息。您的 App 在获取到完整的直播列表后，只需在客户端根据用户选择的分类，对这个列表进行一次简单的筛选，然后刷新 UI 即可。
+
+#### 代码示例
+
+以下示例展示了如何在 `LiveListActivity` 中扩展一个 `LiveListManager` 来处理数据和筛选逻辑。
+``` kotlin
+import android.os.Bundle
+import androidx.appcompat.app.AppCompatActivity
+import androidx.recyclerview.widget.RecyclerView
+import io.trtc.tuikit.atomicxcore.api.live.LiveInfo
+import io.trtc.tuikit.atomicxcore.api.live.LiveListStore
+import kotlinx.coroutines.*
+import kotlinx.coroutines.flow.*
+
+// 1. 创建一个数据管理器来封装数据获取和筛选逻辑
+class LiveListManager {
+    private val liveListStore = LiveListStore.shared()
+    private var fullLiveList: List<LiveInfo> = emptyList()
+
+    // 对外暴露最终的直播列表
+    private val _filteredLiveList = MutableStateFlow<List<LiveInfo>>(emptyList())
+    val filteredLiveList: StateFlow<List<LiveInfo>> = _filteredLiveList
+
+    init {
+        // 监听完整列表变化
+        CoroutineScope(Dispatchers.Main).launch {
+            liveListStore.liveState.liveList.collect { fetchedList ->
+                fullLiveList = fetchedList
+                // 默认将完整列表发布出去
+                _filteredLiveList.value = fetchedList
+            }
+        }
+    }
+
+    fun fetchFirstPage() {
+        liveListStore.fetchLiveList(cursor = "", count = 20, completion = null)
+    }
+
+    /// 根据分类筛选直播列表
+    fun filterLiveList(categoryId: Int?) {
+        if (categoryId == null) {
+            // 如果 categoryId 为 null，则显示完整列表
+            _filteredLiveList.value = fullLiveList
+            return
+        }
+
+        val filteredList = fullLiveList.filter { liveInfo ->
+            liveInfo.categoryList.contains(categoryId)
+        }
+        _filteredLiveList.value = filteredList
+    }
+}
+
+// 2. 在您的 LiveListActivity 中使用 Manager
+class LiveListActivity : AppCompatActivity() {
+    private val manager = LiveListManager()
+    private lateinit var recyclerView: RecyclerView
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContentView(R.layout.activity_live_list)
+        // setupUI()
+
+        // 绑定数据
+        CoroutineScope(Dispatchers.Main).launch {
+            manager.filteredLiveList.collect { filteredList ->
+                // 刷新UI
+               // adapter.updateList(filteredList)
+            }
+        }
+
+        // 首次拉取
+        manager.fetchFirstPage()
+    }
+
+    // 当用户点击顶部分类标签时
+    fun onCategorySelected(categoryId: Int) {
+        manager.filterLiveList(categoryId)
+    }
+
+    // ... (RecyclerView 相关代码)
+}
+```
+
+### 场景二：实现直播列表的滑动播放
+
+用户可以通过上下滑动来切换直播间，当一个新的直播间滑动到屏幕中央时，视频会自动开始播放预览；当它滑出屏幕时，视频则会自动停止，以节省带宽和设备性能。
+
+#### 交互流程图
+
+#### 实现方式
+
+`LiveCoreView` 支持多实例使用，我们为每一个 `RecyclerView.ViewHolder` 都创建一个独立的 `LiveCoreView` 实例。通过监听 `RecyclerView` 的滚动状态，我们可以精确地控制即将出现和已经离开屏幕的 ViewHolder 中的 `LiveCoreView` 何时开始和停止拉流，从而实现“即滑即播、即走即停”的效果。
+
+#### 代码示例
+
+我们创建一个自定义的 `LiveFeedViewHolder`，它内部持有一个 `LiveCoreView`。然后在 Activity 中管理这些 ViewHolder 的播放状态。
+``` kotlin
+import android.os.Bundle
+import android.view.LayoutInflater
+import android.view.View
+import android.view.ViewGroup
+import androidx.appcompat.app.AppCompatActivity
+import androidx.recyclerview.widget.LinearLayoutManager
+import androidx.recyclerview.widget.RecyclerView
+import io.trtc.tuikit.atomicxcore.api.live.LiveInfo
+import io.trtc.tuikit.atomicxcore.api.view.CoreViewType
+import io.trtc.tuikit.atomicxcore.api.view.LiveCoreView
+
+// 1. 自定义 RecyclerView.ViewHolder，内部包含一个 LiveCoreView
+class LiveFeedViewHolder(itemView: View) : RecyclerView.ViewHolder(itemView) {
+    private var liveCoreView: LiveCoreView? = null
+
+    fun setLiveInfo(liveInfo: LiveInfo) {
+        // 为新的直播信息创建一个新的 LiveCoreView
+        liveCoreView = LiveCoreView(itemView.context, viewType = CoreViewType.PLAY_VIEW)
+        liveCoreView?.let { view ->
+            (itemView as ViewGroup).addView(view)
+            view.layoutParams = ViewGroup.LayoutParams(
+                ViewGroup.LayoutParams.MATCH_PARENT,
+                ViewGroup.LayoutParams.MATCH_PARENT
+            )
+        }
+    }
+
+    fun startPlay(roomId: String) {
+        liveCoreView?.startPreviewLiveStream(roomId, false, callback = null)
+    }
+
+    fun stopPlay(roomId: String) {
+        liveCoreView?.stopPreviewLiveStream(roomId)
+    }
+}
+
+// 2. 在 Activity 中管理播放逻辑
+class LiveFeedActivity : AppCompatActivity() {
+
+    private lateinit var recyclerView: RecyclerView
+    private var liveList: List<LiveInfo> = emptyList()
+    private var currentPlayingPosition: Int = -1
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContentView(R.layout.activity_live_feed)
+        setupRecyclerView()
+    }
+
+    private fun setupRecyclerView() {
+        recyclerView = findViewById(R.id.recyclerView)
+        recyclerView.layoutManager = LinearLayoutManager(this, LinearLayoutManager.VERTICAL, false)
+        recyclerView.adapter = LiveFeedAdapter(liveList) { position ->
+            playVideoAtPosition(position)
+        }
+
+        // 监听滚动状态
+        recyclerView.addOnScrollListener(object : RecyclerView.OnScrollListener() {
+            override fun onScrollStateChanged(recyclerView: RecyclerView, newState: Int) {
+                super.onScrollStateChanged(recyclerView, newState)
+                if (newState == RecyclerView.SCROLL_STATE_IDLE) {
+                    val layoutManager = recyclerView.layoutManager as LinearLayoutManager
+                    val firstVisiblePosition = layoutManager.findFirstCompletelyVisibleItemPosition()
+                    if (firstVisiblePosition != RecyclerView.NO_POSITION) {
+                        playVideoAtPosition(firstVisiblePosition)
+                    }
+                }
+            }
+        })
+    }
+
+    private fun playVideoAtPosition(position: Int) {
+        // 只有当居中的位置变化时才切换播放
+        if (currentPlayingPosition != position) {
+            // 停止当前播放
+            if (currentPlayingPosition != -1) {
+                val currentViewHolder = recyclerView.findViewHolderForAdapterPosition(currentPlayingPosition)
+                if (currentViewHolder is LiveFeedViewHolder) {
+                    val liveInfo = liveList[currentPlayingPosition]
+                    currentViewHolder.stopPlay(liveInfo.liveID)
+                }
+            }
+
+            // 开始新的播放
+            val newViewHolder = recyclerView.findViewHolderForAdapterPosition(position)
+            if (newViewHolder is LiveFeedViewHolder) {
+                val liveInfo = liveList[position]
+                newViewHolder.startPlay(liveInfo.liveID)
+                currentPlayingPosition = position
+            }
+        }
+    }
+
+    // RecyclerView Adapter
+    inner class LiveFeedAdapter(
+        private var liveList: List<LiveInfo>,
+        private val onItemClick: (Int) -> Unit
+    ) : RecyclerView.Adapter<LiveFeedViewHolder>() {
+
+        override fun onCreateViewHolder(parent: ViewGroup, viewType: Int): LiveFeedViewHolder {
+            val view = LayoutInflater.from(parent.context)
+                .inflate(R.layout.item_live_feed, parent, false)
+            return LiveFeedViewHolder(view)
+        }
+
+        override fun onBindViewHolder(holder: LiveFeedViewHolder, position: Int) {
+            val liveInfo = liveList[position]
+            holder.setLiveInfo(liveInfo)
+            holder.itemView.setOnClickListener {
+                onItemClick(position)
+            }
+        }
+
+        override fun getItemCount(): Int = liveList.size
+    }
+}
+```
+
+### 场景三：实现电商直播的商品信息展示
+
+在电商直播中，主播正在讲解一款商品。此时，所有观众的直播画面下方都会弹出一张商品卡片，实时展示该商品的图片、名称和价格。当主播切换讲解下一件商品时，所有观众端的卡片都会自动、同步更新。
+
+#### 实现方式
+
+主播端将当前商品的结构化信息（建议使用 **JSON **格式）通过 `updateLiveMetaData` 接口设置到一个自定义的 key（例如 "`product_info`"）中。**AtomicXCore** 会将这个变更实时同步给所有观众。观众端只需订阅 `LiveListStore.liveState.currentLive`，监听 `metaData` 的变化，一旦发现 `product_info` 的值更新，就解析其中的 JSON 数据并刷新商品卡片 UI。
+
+#### 代码示例
+``` kotlin
+import android.os.Bundle
+import androidx.appcompat.app.AppCompatActivity
+import io.trtc.tuikit.atomicxcore.api.CompletionHandler
+import io.trtc.tuikit.atomicxcore.api.live.LiveListStore
+import org.json.JSONObject
+import org.json.JSONException
+import kotlinx.coroutines.*
+import kotlinx.coroutines.flow.*
+
+// 1. 定义一个商品信息数据类
+data class Product(
+    val id: String,
+    val name: String,
+    val price: String,
+    val imageUrl: String
+)
+
+// 2. 主播端：在 YourAnchorActivity 中添加推送商品的方法
+class YourAnchorActivity : AppCompatActivity() {
+    fun pushProductInfo(product: Product) {
+        try {
+            val jsonObject = JSONObject().apply {
+                put("id", product.id)
+                put("name", product.name)
+                put("price", product.price)
+                put("imageUrl", product.imageUrl)
+            }
+            val jsonString = jsonObject.toString()
+
+            val metaData = hashMapOf("product_info" to jsonString)
+
+            // 使用全局单例的 liveListStore 来更新 metaData
+            LiveListStore.shared().updateLiveMetaData(
+                metaData,
+                object : CompletionHandler {
+                    override fun onSuccess() {
+                        println("商品 ${product.name} 信息推送成功")
+                    }
+
+                    override fun onFailure(code: Int, desc: String) {
+                        println("商品信息推送失败: $desc")
+                    }
+                }
+            )
+        } catch (e: JSONException) {
+            println("JSON序列化失败: ${e.message}")
+        }
+    }
+}
+
+// 3. 观众端：在 YourAudienceActivity 中订阅并响应
+class YourAudienceActivity : AppCompatActivity() {
+
+    private val liveListStore = LiveListStore.shared()
+    private val coroutineScope = CoroutineScope(Dispatchers.Main)
+    // 假设您有一个自定义的商品卡片视图
+    // private lateinit var productCardView: ProductCardView
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContentView(R.layout.activity_audience)
+        // ... (setupUI, 布局 productCardView)
+        joinLive()
+        subscribeToProductUpdates()
+    }
+
+    private fun subscribeToProductUpdates() {
+        coroutineScope.launch {
+            liveListStore.liveState.currentLive.collect { currentLive ->
+                val productInfoJson = currentLive.metaData["product_info"]
+                if (productInfoJson != null) {
+                    try {
+                        val jsonObject = JSONObject(productInfoJson)
+                        val product = Product(
+                            id = jsonObject.getString("id"),
+                            name = jsonObject.getString("name"),
+                            price = jsonObject.getString("price"),
+                            imageUrl = jsonObject.getString("imageUrl")
+                        )
+                        // productCardView.updateProduct(product)
+                        // productCardView.show()
+                    } catch (e: JSONException) {
+                        println("商品信息解析失败: ${e.message}")
+                        // productCardView.hide()
+                    }
+                } else {
+                    // productCardView.hide() // 如果没有商品信息，则隐藏卡片
+                }
+            }
+        }
+    }
+
+    override fun onDestroy() {
+        super.onDestroy()
+        coroutineScope.cancel()
+    }
+
+    // ... (joinLive 和 leaveLive 方法)
+}
+
+```
+
+## API 文档
+
+关于 [LiveListStore](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.live/-live-list-store/index.html) 及其相关类的所有公开接口、属性和方法的详细信息，请参阅随 [AtomicXCore](https://tencent-rtc.github.io/TUIKit_Android/index.html) 框架的官方 API 文档。本文档使用到的相关 Store 如下：
+
+|Store/Component|功能描述|API 文档|
+|---------|---------|---------|
+|LiveCoreView|直播视频流展示与交互的核心视图组件：负责视频流渲染和视图挂件处理，支持主播直播、观众连麦、主播连线等场景。|[API 文档](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.view/-live-core-view/index.html)|
+|LiveListStore|直播间全生命周期管理：创建 / 加入 / 离开 / 销毁房间，查询房间列表，修改直播信息（名称、公告等），监听直播状态（例如被踢出、结束）。|[API 文档](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.live/-live-list-store/index.html)|
+
+## 常见问题
+
+### 使用 `updateLiveMetaData` 时有哪些需要注意的限制和规则？
+
+为了保证系统的稳定和高效，`metaData` 的使用遵循以下规则：
+- **权限**: 只有房主和管理员可以调用 `updateLiveMetaData`。普通观众没有权限。
+
+- **数量与大小限制**：
+
+  - 单个房间最多支持 **10** 个 key。
+
+  - 每个 key 的长度不超过 **50 字节**，每个 value 的长度不超过 **2KB**。
+
+  - 单个房间所有 value 的总大小不超过 **16KB**。
+
+- **冲突解决**： `metaData` 的更新机制是"后来者覆盖"。如果多个管理员在短时间内修改同一个 key，最后一次的修改会生效。建议在业务设计上避免多人同时修改同一个关键信息。

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

@@ -14,18 +14,20 @@
 ## 核心概念
 
 下表介绍了 `LiveAudienceStore` 的核心概念：
-| **核心概念** | **类型** | **核心职责与描述** |
-| --- | --- | --- |
-| [LiveUserInfo](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_audience_store/LiveUserInfo-class.html) | `class` | 代表一个观众（用户）的基础信息模型。它包含了用户的唯一标识 (`userID`)、昵称 (`userName`) 和头像地址 (`avatarURL`)。 |
-| [LiveAudienceState](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_audience_store/LiveAudienceState-class.html) | `class` | 代表观众模块的当前状态。其核心属性 `audienceList` 是一个 `ValueListenable<List<LiveUserInfo>>`，存储了观众列表的快照；`audienceCount` 则代表当前观众总数。 |
-| [LiveAudienceListener](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_audience_store/LiveAudienceListener-class.html) | `class` | 代表观众动态的实时事件监听器。包含 `onAudienceJoined`（观众加入）和 `onAudienceLeft`（观众离开）两个回调，用于实现对观众列表的增量更新。 |
-| [LiveAudienceStore](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_audience_store/LiveAudienceStore-class.html) | `class` | 这是与观众列表功能交互的核心管理类。通过它，您可以获取观众列表快照、执行管理操作，并通过 `addLiveAudienceListener` 来接收实时动态。 |
+
+|**核心概念**|**类型**|**核心职责与描述**|
+|---------|---------|---------|
+|[LiveUserInfo](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_audience_store/LiveUserInfo-class.html)|`class`|代表一个观众（用户）的基础信息模型。它包含了用户的唯一标识 (`userID`)、昵称 (`userName`) 和头像地址 (`avatarURL`)。|
+|[LiveAudienceState](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_audience_store/LiveAudienceState-class.html)|`class`|代表观众模块的当前状态。其核心属性 `audienceList` 是一个 `ValueListenable<List<LiveUserInfo>>`，存储了观众列表的快照；`audienceCount` 则代表当前观众总数。|
+|[LiveAudienceListener](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_audience_store/LiveAudienceListener-class.html)|`class`|代表观众动态的实时事件监听器。包含 `onAudienceJoined`（观众加入）和 `onAudienceLeft`（观众离开）两个回调，用于实现对观众列表的增量更新。|
+|[LiveAudienceStore](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_audience_store/LiveAudienceStore-class.html)|`class`|这是与观众列表功能交互的核心管理类。通过它，您可以获取观众列表快照、执行管理操作，并通过 `addLiveAudienceListener` 来接收实时动态。|
 
 ## 实现步骤
 
 ### 步骤1：组件集成
+- **视频直播**：请参考 开播与观看 集成 **AtomicXCore**，完成接入。
 
-请参考 快速接入 集成 **AtomicXCore**，完成接入。
+- **语聊房**：请参考 开播与收听 集成 **AtomicXCore**，完成接入。
 
 ### 步骤2：初始化并获取观众列表
 
@@ -230,12 +232,13 @@ class LiveRoomManager {
 ## API 文档
 
 关于 [LiveAudienceStore](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_audience_store/LiveAudienceStore-class.html) 及其相关类的所有公开接口、属性和方法的详细信息，请参考 [AtomicXCore](https://tencent-rtc.github.io/TUIKit_Flutter/index.html) 框架的官方 API 文档。本文档使用到的相关 Store 如下：
-| **Store/Component** | **功能描述** | **API 文档** |
-| --- | --- | --- |
-| **LiveCoreWidget** | 直播视频流展示与交互的核心视图组件：负责视频流渲染和视图挂件处理，支持主播直播、观众连麦、主播连线等场景。 | [API 文档](https://tencent-rtc.github.io/TUIKit_Flutter/api_view_live_live_core_widget/LiveCoreWidget-class.html) |
-| **LiveCoreController** | LiveCoreWidget 的控制器：用于设置直播 ID、控制预览等操作。 | [API 文档](https://tencent-rtc.github.io/TUIKit_Flutter/api_view_live_live_core_widget/LiveCoreController-class.html) |
-| **LiveAudienceStore** | 观众管理：获取实时观众列表（ID / 名称 / 头像），统计观众数量，监听观众进出事件。 | [API 文档](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_audience_store/LiveAudienceStore-class.html) |
-| **BarrageStore** | 弹幕功能：发送文本 / 自定义弹幕，维护弹幕列表，实时监听弹幕状态。 | [API 文档](https://tencent-rtc.github.io/TUIKit_Flutter/api_barrage_barrage_store/api_barrage_barrage_store-library.html) |
+
+|**Store/Component**|**功能描述**|**API 文档**|
+|---------|---------|---------|
+|**LiveCoreWidget**|直播视频流展示与交互的核心视图组件：负责视频流渲染和视图挂件处理，支持主播直播、观众连麦、主播连线等场景。|[API 文档](https://tencent-rtc.github.io/TUIKit_Flutter/api_view_live_live_core_widget/LiveCoreWidget-class.html)|
+|**LiveCoreController**|LiveCoreWidget 的控制器：用于设置直播 ID、控制预览等操作。|[API 文档](https://tencent-rtc.github.io/TUIKit_Flutter/api_view_live_live_core_widget/LiveCoreController-class.html)|
+|**LiveAudienceStore**|观众管理：获取实时观众列表（ID / 名称 / 头像），统计观众数量，监听观众进出事件。|[API 文档](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_audience_store/LiveAudienceStore-class.html)|
+|**BarrageStore**|弹幕功能：发送文本 / 自定义弹幕，维护弹幕列表，实时监听弹幕状态。|[API 文档](https://tencent-rtc.github.io/TUIKit_Flutter/api_barrage_barrage_store/api_barrage_barrage_store-library.html)|
 
 ## 常见问题