@tencentcloud/sdk-mcp 1.6.4 → 1.6.5

package/resource/knowledge/livekit/core-sdk/live/ios/live-audience-list.md

@@ -1,265 +0,0 @@
-`LiveAudienceStore` 是 `AtomicXCore` 中专门负责管理直播间观众信息的模块。通过 `LiveAudienceStore`，您可以为您的直播应用构建一套完整的观众列表及管理系统。
-
-## 核心功能
-- **实时观众列表**：获取并展示当前在直播间内的所有观众信息。
-
-- **观众人数统计**：实时获取当前直播间的准确观众总数。
-
-- **观众动态监听**：通过事件订阅，实时感知观众的加入和离开。
-
-- **管理员权限**：主播可以将普通观众设为管理员，或撤销其管理员身份。
-
-- **房间管理**：主播或管理员可以将任意普通观众请出（踢出）直播间。
-
-## 核心概念
-
-在开始集成之前，我们先通过下表了解一下 LiveAudienceStore 相关的几个核心概念：
-
-|**核心概念**|**类型**|**核心职责与描述**|
-|---------|---------|---------|
-|`LiveUserInfo`|struct|代表一个观众（用户）的基础信息模型。它包含了用户的唯一标识 (`userID`)、昵称 (`userName`) 和头像地址 (`avatarURL`)。|
-|`LiveAudienceState`|struct|代表观众模块的当前状态。其核心属性 `audienceList` 是一个 `[LiveUserInfo] `数组，存储了观众列表的快照；`audienceCount` 则代表当前观众总数。|
-|`LiveAudienceEvent`|enum|代表观众动态的实时事件。分为 `.onAudienceJoined`（观众加入） 和 `.onAudienceLeft`（观众离开）两种，用于实现对观众列表的增量更新。|
-|`LiveAudienceStore`|class|这是与观众列表功能交互的核心管理类。通过它，您可以获取观众列表快照、执行管理操作，并通过订阅其 `liveAudienceEventPublisher` 来接收实时动态。|
-
-## 实现步骤
-
-### 步骤1：组件集成
-- **视频直播**：请参考 开播与观看 集成 **AtomicXCore**，完成接入。
-
-- **语聊房**：请参考 开播与收听 集成 **AtomicXCore**，完成接入。
-
-### 步骤2：初始化并获取观众列表
-
-获取一个与当前直播间 liveId 绑定的 `LiveAudienceStore` 实例，并主动拉取一次当前的观众列表，用于首次展示。
-``` swift
-import Foundation
-import AtomicXCore
-import Combine
-
-class AudienceManager {
-    private let liveId: String
-    private let audienceStore: LiveAudienceStore
-    private var cancellables = Set<AnyCancellable>()
-
-    // 对外暴露【全量】观众列表的发布者，方便UI层订阅
-    let audienceListPublisher = CurrentValueSubject<[LiveUserInfo], Never>([])
-    // 对外暴露观众总数的发布者
-    let audienceCountPublisher = PassthroughSubject<UInt, Never>()
-
-    init(liveId: String) {
-        self.liveId = liveId
-        // 1. 通过 liveId 获取 LiveAudienceStore 的实例
-        self.audienceStore = LiveAudienceStore.create(liveID: liveId)
-
-        // 2. 订阅状态和事件
-        subscribeToAudienceState()
-        subscribeToAudienceEvents()
-
-        // 3. 主动拉取首屏数据
-        fetchInitialAudienceList()
-    }
-
-    /// 主动获取一次观众列表快照
-    func fetchInitialAudienceList() {
-        audienceStore.fetchAudienceList { [weak self] result in
-            switch result {
-            case .success:
-                print("首次拉取观众列表成功")
-                // 成功后，数据会通过下面的 state 订阅通道自动更新
-            case .failure(let error):
-                print("首次拉取观众列表失败: \(error.localizedDescription)")
-            }
-        }
-    }
-
-    // ... 后续代码
-}
-```
-
-### 步骤3：监听观众列表状态与实时动态
-
-订阅 `audienceStore` 的 `state` 和 `event`，以接收全量列表快照和实时的观众进出事件，从而驱动 UI 更新。
-``` swift
-extension AudienceManager {
-    /// 订阅 state，用于获取观众总数和列表快照
-    private func subscribeToAudienceState() {
-        audienceStore.state
-            .subscribe()
-            .receive(on: DispatchQueue.main)
-            .sink { [weak self] state in
-                // state.audienceList 是一个全量快照
-                self?.audienceListPublisher.send(state.audienceList)
-                // state.audienceCount 是实时总数
-                self?.audienceCountPublisher.send(state.audienceCount)
-            }
-            .store(in: &cancellables)
-    }
-
-    /// 订阅 event，用于处理观众的实时进出
-    private func subscribeToAudienceEvents() {
-        audienceStore.liveAudienceEventPublisher
-            .receive(on: DispatchQueue.main)
-            .sink { [weak self] event in
-                guard let self = self else { return }
-
-                var currentList = self.audienceListPublisher.value
-
-                switch event {
-                case .onAudienceJoined(let newAudience):
-                    print("观众 \(newAudience.userName) 加入了直播间")
-                    // 增量更新：在当前列表末尾添加新观众
-                    if !currentList.contains(where: { $0.userID == newAudience.userID }) {
-                        currentList.append(newAudience)
-                        self.audienceListPublisher.send(currentList)
-                    }
-
-                case .onAudienceLeft(let departedAudience):
-                    print("观众 \(departedAudience.userName) 离开了直播间")
-                    // 增量更新：从当前列表中移除离开的观众
-                    currentList.removeAll { $0.userID == departedAudience.userID }
-                    self.audienceListPublisher.send(currentList)
-                }
-            }
-            .store(in: &cancellables)
-    }
-}
-```
-
-### 步骤4：管理观众（踢人与设置管理员）
-
-作为主播或管理员，对直播间内的观众进行管理操作。
-
-#### 4.1 将观众踢出直播间
-
-调用 `kickUserOutOfRoom` 接口可以将指定用户请出直播间。
-``` swift
-extension AudienceManager {
-    func kick(userId: String) {
-        audienceStore.kickUserOutOfRoom(userID: userId) { result in
-            switch result {
-            case .success:
-                print("成功将用户 \(userId) 踢出房间")
-                // 踢出成功后，您会收到 onAudienceLeft 事件
-            case .failure(let error):
-                print("踢出用户 \(userId) 失败: \(error.localizedDescription)")
-            }
-        }
-    }
-}
-```
-
-#### 4.2 设置/撤销管理员
-
-通过 `setAdministrator` 和 `revokeAdministrator` 接口可以管理用户的管理员身份。
-``` swift
-extension AudienceManager {
-    /// 将用户设为管理员
-    func promoteToAdmin(userId: String) {
-        audienceStore.setAdministrator(userID: userId) { result in
-            if case .success = result {
-                print("成功将用户 \(userId) 设为管理员")
-            }
-        }
-    }
-
-    /// 撤销用户的管理员身份
-    func revokeAdmin(userId: String) {
-        audienceStore.revokeAdministrator(userID: userId) { result in
-            if case .success = result {
-                print("成功撤销用户 \(userId) 的管理员身份")
-            }
-        }
-    }
-}
-```
-
-## 功能进阶
-
-### 在弹幕区展示观众入场欢迎语
-
-当有新观众进入直播间时，弹幕/聊天区域会在本地自动显示一条欢迎消息，例如：“欢迎 [用户昵称] 进入直播间”。
-
-#### 实现方式
-
-我们通过订阅 `LiveAudienceStore` 的观众加入事件（`LiveAudienceEvent.onAudienceJoined`）来获取新观众加入的实时通知。一旦事件触发，我们便提取出新观众的昵称信息，然后立即调用 `BarrageStore` 的本地插入接口 `appendLocalTip`。
-``` swift
-import Foundation
-import AtomicXCore
-import Combine
-
-class LiveRoomManager {
-    private let liveId: String
-    private let audienceManager: AudienceManager
-    private let barrageManager: BarrageManager // 假设您已实现了弹幕文档中的BarrageManager
-    private var cancellables = Set<AnyCancellable>()
-
-    init(liveId: String) {
-        self.liveId = liveId
-        // 初始化两个核心管理器
-        self.audienceManager = AudienceManager(liveId: liveId)
-        self.barrageManager = BarrageManager(liveId: liveId)
-
-        // 设置联动
-        setupWelcomeMessageFlow()
-    }
-
-    private func setupWelcomeMessageFlow() {
-        // 1. 获取 LiveAudienceStore 的实例
-        let audienceStore = LiveAudienceStore.create(liveID: self.liveId)
-
-        // 2. 获取 BarrageStore 的实例 (得益于内部机制，这会是同一个实例)
-        let barrageStore = BarrageStore.create(liveID: self.liveId)
-
-        // 3. 订阅观众事件
-        audienceStore.liveAudienceEventPublisher
-            .receive(on: DispatchQueue.main)
-            .sink { event in
-                // 4. 只处理观众加入事件
-                guard case .onAudienceJoined(let newAudience) = event else {
-                    return
-                }
-
-                // 5. 创建一条本地提示消息
-                var welcomeTip = Barrage()
-                welcomeTip.messageType = .text
-                welcomeTip.textContent = "欢迎 \(newAudience.userName) 进入直播间！"
-
-                // 6. 调用 BarrageStore 的接口将其插入弹幕列表
-                barrageStore.appendLocalTip(message: welcomeTip)
-            }
-            .store(in: &cancellables)
-    }
-}
-```
-
-## API 文档
-
-关于 [LiveAudienceStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/liveaudiencestore) 及其相关类的所有公开接口、属性和方法的详细信息，请参阅随 [AtomicXCore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore) 框架的官方 API 文档。本文档使用到的相关 Store 如下：
-
-|Store/Component|功能描述|API 文档|
-|---------|---------|---------|
-|LiveCoreView|直播视频流展示与交互的核心视图组件：负责视频流渲染和视图挂件处理，支持主播直播、观众连麦、主播连线等场景。|[API 文档](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/livecoreview)|
-|LiveAudienceStore|观众管理：获取实时观众列表（ID / 名称 / 头像），统计观众数量，监听观众进出事件。|[API 文档](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/liveaudiencestore)|
-|BarrageStore|弹幕功能：发送文本 / 自定义弹幕，维护弹幕列表，实时监听弹幕状态。|[API 文档](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/barragestore)|
-
-## 常见问题
-
-### `LiveAudienceState` 中的在线人数（`audienceCount`）是如何更新的？时机和频率是怎样的？
-
-`audienceCount` 的更新并非总是实时的，其机制如下：
-- **主动进出房间**：当用户主动加入或正常退出直播间时，在线人数的变更通知会即时触发。您会很快在 `LiveAudienceState` 中观察到 `audienceCount` 的变化。
-
-- **异常掉线**：当用户因网络问题、应用崩溃等原因异常掉线时，系统需要通过心跳机制来判断其真实状态。只有当该用户连续 90 秒没有心跳后，系统才会判定其为离线，并触发人数变更通知。
-
-- **更新机制与频率控制：**
-
-  - 无论是即时触发还是延迟触发，所有的人数变更通知都是以消息的形式在房间内广播的。
-
-  - 房间内每秒的消息总量有上限，单房间消息频控是**每秒 40 条消息**。
-
-  - **关键点：**在“弹幕风暴”或礼物刷屏等消息流量极高的场景下，如果房间内的消息速率超过了 40条/秒 的阈值，为了保证核心消息（例如弹幕）的送达，**人数变更的消息可能会被频控策略丢弃**。
-
-      **这对开发者意味着什么？**
-
-      `audienceCount` 是一个非常接近实时的**高精度估算值**，但在极端高并发场景下，它可能存在短暂的延迟或数据丢失。因此，我们建议您将其用于 **UI 展示**，而不应作为计费、统计等需要绝对精准场景的唯一依据。

package/resource/knowledge/livekit/core-sdk/live/ios/live-audio-effect.md

@@ -1,214 +0,0 @@
-本篇文档旨在指导您如何使用 `AtomicXCore` 框架中的 `AudioEffectStore` 和 `DeviceStore` 模块，为您的直播应用快速集成音效控制功能，包括麦克风音量、耳返监听，并添加多种趣味变声效果和混响效果。
-
-## 核心功能
-
-通过组合 `AudioEffectStore` 和 `DeviceStore`，您将能实现以下核心功能：
-- **人声音量调节**：控制本地音频上行的采集音量大小，即观众听到的您的声音大小。
-
-- **耳返功能**：允许主播或连麦用户通过耳机实时听到自己的声音，用于监听和矫正发音。
-
-- **变声效果**：提供多种趣味变声选项，例如萝莉、大叔、熊孩子等。
-
-- **混响效果**：模拟不同环境的声场效果，例如 KTV、金属声、低沉、洪亮等。
-
-## 概念说明
-| <strong>核心概念</strong> | <strong>类型</strong> | <strong>核心职责与描述</strong> |
-| --- | --- | --- |
-| <code>AudioChangerType</code> | <code>enum</code> | 变声效果枚举，例如，“小孩”，“男人”等。 |
-| <code>AudioReverbType</code> | <code>enum</code> | 混响效果枚举，例如，“ktv”，“礼堂”等。 |
-| <code>AudioEffectState</code> | <code>struct</code> | 代表音效模块的当前状态，通常用于 UI 渲染。包括变声状态、混响状态、耳返开启状态、耳返音量。 |
-| <code>AudioEffectStore</code> | <code>class</code> | 代表音效模块<strong>单例数据管理类</strong>。通过它您可以调用修改音效接口，当您调用接口后，相应的 <code>state</code> 属性会自动更新，可以通过订阅这个 state 响应式数据来接收和监听状态更新。 |
-| <code>DeviceState</code> | <code>struct</code> | 代表设备模块的当前状态，通常用于 UI 渲染。核心属性包括摄像头、麦克风的设备状态。 |
-| <code>DeviceStore</code> | <code>class</code> | 代表设备模块<strong>单例数据管理类</strong>。通过它您可以调用操作摄像头、麦克风接口，当您调用接口后，相应的 <code>state</code> 属性会自动更新，可以通过订阅这个 state 响应式数据来接收和监听状态更新。 |
-
-## 实现步骤
-
-### 步骤1：组件集成
-
-请参考 开播与收听 集成 **AtomicXCore。**
-
-### 步骤2：获取 Store 实例
-
-`AudioEffectStore` 和 `DeviceStore` 是单例对象，您可以直接通过 shared 属性在项目的任何位置获取实例。您也可以参考 TUILiveKit 开源 UI Demo 项目中的 [AudioEffectView.swift](https://github.com/Tencent-RTC/TUIKit_iOS/blob/main/live/Sources/Component/AudioEffect/AudioEffectView.swift) 文件来了解完整的实现逻辑。
-``` swift
-import UIKit
-import AtomicXCore
-import Combine
-
-let audioEffectStore = AudioEffectStore.shared
-let deviceStore = DeviceStore.shared
-```
-
-### 步骤3：实现耳返功能
-
-耳返功能允许用户实时监听自己的麦克风声音，可以通过调用本节介绍的接口管理耳返功能。
-
-> **注意：**
->
-
-> 耳返功能通常需要连接耳机才能正常工作。
->
-
-#### 实现方式:
-1. **开关耳返**：您可以使用 `UISwitch`  控件实现开关耳返功能。
-
-2. **设置耳返音量值**：您可以使用 `UISlider` 控件实现左右拖动滑块来调节音量的功能，并将 `UISlider` 的值映射成音量值，调用 `setOutputVolume(_ volume:)`。请注意，该接口接收的参数范围是 `[0, 150]，`所以您需要将 UI 控件的值（例如 UISlider 的 `0 - 1.0`）映射到 `0 - 150` 的范围。
-
-3. **监听状态更新 UI**：您可以订阅实时的耳返状态值更新 UI。
-
-#### 代码示例:
-``` swift
-// 1. 开启耳返
-audioEffectStore.setVoiceEarMonitorEnable(enable: true)
-
-// 2. 调节耳返音量
-audioEffectStore.setVoiceEarMonitorVolume(volume: 80)
-
-// 3. 关闭耳返
-audioEffectStore.setVoiceEarMonitorEnable(enable: false)
-
-// 4. 监听状态
-audioEffectStore.state
-    .subscribe(StatePublisherSelector(keyPath: \AudioEffectState.earMonitorVolume))
-    .removeDuplicates()
-    .sink { currentVolume in
-        print("耳返音量: \(currentVolume)")
-        valueLabel.text = "\(currentVolume)" //更新UILabel显示数值
-    }
-    .store(in: &cancellables)
-```
-
-#### setVoiceEarMonitorEnable 接口参数
-| <strong>参数名</strong> | <strong>类型</strong> | <strong>描述</strong> |
-| --- | --- | --- |
-| <code>enable</code> | <code>Bool</code> | 是否开启耳返。<br>- true：开启<br>- false：关闭 |
-
-#### setVoiceEarMonitorVolume 接口参数
-| <strong>参数名</strong> | <strong>类型</strong> | <strong>描述</strong> |
-| --- | --- | --- |
-| <code>volume</code> | <code>Int</code> | 耳返音量大小。<br>- 取值范围： [0, 150]<br>- 默认值：100 |
-
-### 步骤4：实现人声音量调节
-
-当主播希望调节自己的上行采集音量大小时，调用 `DeviceStore` 的 `setCaptureVolume(volume: )` 方法传入音量值即可。
-
-#### 实现方式:
-1. **设置采集音量值**：您可以使用 `UISlider` 控件实现左右拖动滑块来调节音量的功能，并将 `UISlider` 的值映射成音量值后调用 `setCaptureVolume(volume: 80)`。请注意，该接口接收的参数范围是 `[0, 150]，`所以您需要将 UI 控件的值（例如 UISlider 的 `0 - 1.0`）映射到 `0 - 150` 的范围。
-
-2. **监听状态更新 UI**：您可以订阅实时的音量状态值更新 UI。
-
-#### 示例代码：
-``` swift
-// 1. 调节音量
-deviceStore.setCaptureVolume(volume: 80)
-
-// 2. 监听状态
-deviceStore.state
-    .subscribe(StatePublisherSelector(keyPath: \DeviceState.captureVolume))
-    .removeDuplicates()
-    .sink { captureVolume in
-        print("采集音量: \(captureVolume)")
-        valueLabel.text = "\(captureVolume)" //更新UILabel显示数值
-    }
-    .store(in: &cancellables)
-```
-
-#### setCaptureVolume 接口参数
-| <strong>参数名</strong> | <strong>类型</strong> | <strong>描述</strong> |
-| --- | --- | --- |
-| <code>volume</code> | <code>Int</code> | 采集音量大小。<br>- 取值范围： [0, 150]<br>- 默认值：100 |
-
-### 步骤5：实现变声效果
-
-当主播希望改变自己的声音时，您可以调用 `setAudioChangerType(type:)` 方法，传入相应的 Type 枚举值即可切换效果。
-
-#### 示例代码：
-``` swift
-// 示例：将变声效果设置为“小孩”
-audioEffectStore.setAudioChangerType(type: .child)
-// 示例：关闭变声效果
-audioEffectStore.setAudioChangerType(type: .none)
-```
-
-#### setAudioChangerType 接口参数
-
-|**参数名**|**类型**|**描述**|
-|---------|---------|---------|
-|`type`|`AudioChangerType`|变声效果枚举。|
-
-### 步骤6：实现混响效果
-
-当主播希望给自己的声音添加混响效果时，您可以调用 `setAudioReverbType(type:)` 方法，传入相应的 Type 枚举值即可切换效果。
-``` swift
-// 示例：设置为“KTV”混响效果
-audioEffectStore.setAudioReverbType(type: .ktv)
-// 示例：关闭混响效果
-audioEffectStore.setAudioReverbType(type: .none)
-```
-
-#### setAudioReverbType 接口参数
-
-|**参数名**|**类型**|**描述**|
-|---------|---------|---------|
-|`type`|`AudioReverbType`|混响效果枚举。|
-
-### 步骤7：重置音效设置
-
-> **重要：**
->
-
-> `AudioEffectStore` 和 `DeviceStore` 是单例，这意味着音效和设备设置是全局生效的，如果您在当前直播间的设置不想影响到您创建的其他直播间，就需要在当前直播间结束的时候重置音效和设备设置。
->
-
-以下两种情况您可能需要重置音效设置：
-1. 当前直播间结束时，需要重置音效设置。
-
-2. 您需要提供“一键恢复”的功能，可以通过调用 store 的 `reset()` 方法实现。
-
-   ``` swift
-   class YourMainViewController: UIViewController {
-       func reset() {
-           AudioEffectStore.shared.reset()
-           DeviceStore.shared.reset()
-       }
-   }
-   ```
-
-## API 文档
-
-关于 [AudioEffectStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/audioeffectstore) 和 [DeviceStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/devicestore) 及其相关类的所有公开接口、属性的详细信息，请参阅随 [AtomicXCore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore) 框架的官方 API 文档。
-
-|**Store/Component**|**功能描述**|**API 文档**|
-|---------|---------|---------|
-|AudioEffectStore|音效管理：进行音效设置，并获取实时音效状态。|[API 文档](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/audioeffectstore/)|
-|DeviceStore |设备管理：进行摄像头、麦克风操作，并获取实时设备状态。|[API 文档](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/devicestore)|
-
-## 常见问题
-
-### 音效和设备接口的调用时机有没有要求？
-
-没有限制。`AudioEffectStore` 和 `DeviceStore` 的设置是全局生效的，您可以在进入直播间之前或之后随时调用相关接口（例如设置变声、混响或耳返），设置会立即生效并被保留。
-
-### **“人声音量” 和“耳返音量” 有什么区别？**
-
-这是一个非常重要且易混淆的概念，区别如下：
-- **人声音量 (CaptureVolume)：**通过 `DeviceStore.setCaptureVolume()` 设置**。它决定了观众**能听到的您的声音大小。
-
-- **耳返音量 (EarMonitorVolume)：**通过 `AudioEffectStore.setVoiceEarMonitorVolume()`** 设置。它只**决定了**您自己**在耳机里听到的监听声音大小，**不会**影响观众。
-
-### **新创建的直播间为什么直接就有音效、或者出现音量很大、很小等问题？**
-
-`AudioEffectStore` 和 `DeviceStore` 是单例，这意味着音效和设备设置是全局生效的，出现这种情况很可能是因为您之前设置过音效但是没有重置，需要在合适的地方调用 `reset()` 方法重置。
-
-### **为什么我开启了“耳返”，但是听不到自己的声音？**
-
-请您按照以下步骤检查：
-1. **是否插入耳机**：耳返功能绝大多数情况下依赖耳机才能生效，请确保已连接有线或蓝牙耳机。
-
-2. **音量是否为0**：检查“耳返音量”是否被设置为了 0。
-
-3. **麦克风是否开启**：确认 `DeviceStore` 中的麦克风是开启状态（即已调用 `openLocalMicrophone`）。
-
-### **变声效果 和混响效果 可以同时生效吗？**
-
-可以。`AudioChangerType` 和 `AudioReverbType` 是可以叠加生效的。例如，您可以同时设置 `.littleGirl` 变声和 `.ktv` 混响。