@tencent-rtc/mcp 1.3.8 → 1.4.0

package/resource/doc/livekit/core-sdk/voice/ios/voice-audience-list.md

@@ -0,0 +1,263 @@
+`LiveAudienceStore` is a module in `AtomicXCore` designed for managing audience information in live streaming rooms. With `LiveAudienceStore`, you can implement a comprehensive audience list and management system for your live streaming application.
+
+## Core Features
+- **Real-Time Audience List**: Fetch and display the list of users currently in the room.
+
+- **Audience Statistics**: Get the real-time total viewer count.
+
+- **Event Monitoring**: Listen for events when viewers join or leave the room.
+
+- **Role Management**: The host can grant or revoke administrator privileges for viewers.
+
+- **Room Management**: The host or administrator can remove specific viewers from the live room.
+
+## Core Concepts
+| **Core Concept** | **Type** | **Core Responsibilities & Description** |
+| --- | --- | --- |
+| `LiveUserInfo` | `class` | - Data model representing a viewer.<br>- Contains basic profile information such as userID, userName, and avatarURL. |
+| `LiveAudienceState` | `struct` | - State container for the audience module.<br>- Exposes `audienceList` (StateFlow) for the real-time user list and `audienceCount` for the total viewer count. |
+| `LiveAudienceEvent` | `enum` | - Event listener for audience changes.<br>- Provides callbacks like `.onAudienceJoined` and` .onAudienceLeft` to handle incremental list updates. |
+| `LiveAudienceStore` | `class` | - Primary interface for audience management.<br>- Used to fetch list snapshots, perform admin operations (e.g., kicking users), and subscribe to real-time events. |
+
+## Implementation
+
+### Step 1: Component Integration
+- **Video Live Streaming**: Please refer to Quick Start to integrate AtomicXCore.
+
+- **Voice Chat Room**: Please refer to Quick Start to integrate AtomicXCore.
+
+### Step 2: Initialize and Retrieve the Audience List
+
+Get a `LiveAudienceStore` instance linked to the `liveId` and fetch the initial audience snapshot.
+``` swift
+import Foundation
+import AtomicXCore
+import Combine
+
+class AudienceManager {
+    private let liveId: String
+    private let audienceStore: LiveAudienceStore
+    private var cancellables = Set<AnyCancellable>()
+
+    // Expose the [full] audience list publisher for UI layer subscription
+    let audienceListPublisher = CurrentValueSubject<[LiveUserInfo], Never>([])
+    // Expose the audience count publisher
+    let audienceCountPublisher = PassthroughSubject<UInt, Never>()
+
+    init(liveId: String) {
+        self.liveId = liveId
+        // 1. Get the LiveAudienceStore instance by liveId
+        self.audienceStore = LiveAudienceStore.create(liveID: liveId)
+
+        // 2. Subscribe to state and events
+        subscribeToAudienceState()
+        subscribeToAudienceEvents()
+
+        // 3. Proactively fetch initial data for the first screen
+        fetchInitialAudienceList()
+    }
+
+    /// Proactively fetch a snapshot of the audience list
+    func fetchInitialAudienceList() {
+        audienceStore.fetchAudienceList { [weak self] result in
+            switch result {
+            case .success:
+                print("Successfully fetched the audience list for the first time")
+                // On success, data will be automatically updated via the state subscription channel below
+            case .failure(let error):
+                print("Failed to fetch the audience list for the first time: \(error.localizedDescription)")
+            }
+        }
+    }
+
+    // ... subsequent code
+}
+```
+
+### Step 3: Subscribe to State and Events
+
+Observe the `audienceStore` state and listen for events to receive list snapshots and real-time join/leave updates
+``` swift
+extension AudienceManager {
+    /// Subscribe to state to get audience count and list snapshot
+    private func subscribeToAudienceState() {
+        audienceStore.state
+            .subscribe()
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] state in
+                // state.audienceList is a full snapshot
+                self?.audienceListPublisher.send(state.audienceList)
+                // state.audienceCount is the real-time total
+                self?.audienceCountPublisher.send(state.audienceCount)
+            }
+            .store(in: &cancellables)
+    }
+
+    /// Subscribe to events to handle real-time audience join/leave
+    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("Audience \(newAudience.userName) joined the live room")
+                    // Incremental update: add the new audience member to the end of the current list
+                    if !currentList.contains(where: { $0.userID == newAudience.userID }) {
+                        currentList.append(newAudience)
+                        self.audienceListPublisher.send(currentList)
+                    }
+
+                case .onAudienceLeft(let departedAudience):
+                    print("Audience \(departedAudience.userName) left the live room")
+                    // Incremental update: remove the departed audience member from the current list
+                    currentList.removeAll { $0.userID == departedAudience.userID }
+                    self.audienceListPublisher.send(currentList)
+                }
+            }
+            .store(in: &cancellables)
+    }
+}
+```
+
+### Step 4: Manage Audience
+
+As a host or administrator, you can manage viewers in the live room.
+
+#### 4.1 Kick a Viewer Out of the Live Room
+
+Call the `kickUserOutOfRoom` API to remove a specified user from the live room.
+``` swift
+extension AudienceManager {
+    func kick(userId: String) {
+        audienceStore.kickUserOutOfRoom(userID: userId) { result in
+            switch result {
+            case .success:
+                print("Successfully kicked user \(userId) out of the room")
+                // After a successful kick, you will receive an onAudienceLeft event
+            case .failure(let error):
+                print("Failed to kick user \(userId) out: \(error.localizedDescription)")
+            }
+        }
+    }
+}
+```
+
+#### 4.2 Manage Admin Roles
+
+Use the `setAdministrator` and `revokeAdministrator` APIs to grant or revoke administrator privileges for a user.
+``` swift
+extension AudienceManager {
+    /// Promote user to administrator
+    func promoteToAdmin(userId: String) {
+        audienceStore.setAdministrator(userID: userId) { result in
+            if case .success = result {
+                print("Successfully promoted user \(userId) to administrator")
+            }
+        }
+    }
+
+    /// Revoke user's administrator status
+    func revokeAdmin(userId: String) {
+        audienceStore.revokeAdministrator(userID: userId) { result in
+            if case .success = result {
+                print("Successfully revoked administrator status for user \(userId)")
+            }
+        }
+    }
+}
+```
+
+## Advanced Features
+
+### Display Welcome Message on Entry
+
+When a new audience member enters the live room, a welcome message is automatically displayed locally in the barrage/chat area, such as: `"Welcome [User Nickname] to the live room"`.
+
+#### Implementation
+1. Listen for Join Events: Observe the `LiveAudienceEvent.onAudienceJoined` callback in `LiveAudienceStore` to receive real-time notifications when a new user enters.
+
+2. Insert Local Message: Upon triggering the event, extract the user's nickname and immediately call the `appendLocalTip` API in BarrageStore to insert the system message locally.
+
+   ``` swift
+   import Foundation
+   import AtomicXCore
+   import Combine
+
+   class LiveRoomManager {
+       private let liveId: String
+       private let audienceManager: AudienceManager
+       private let barrageManager: BarrageManager // Assume you have implemented BarrageManager as described in the barrage documentation
+       private var cancellables = Set<AnyCancellable>()
+
+       init(liveId: String) {
+           self.liveId = liveId
+           // Initialize two core managers
+           self.audienceManager = AudienceManager(liveId: liveId)
+           self.barrageManager = BarrageManager(liveId: liveId)
+
+           // Set up linkage
+           setupWelcomeMessageFlow()
+       }
+
+       private func setupWelcomeMessageFlow() {
+           // 1. Get the LiveAudienceStore instance
+           let audienceStore = LiveAudienceStore.create(liveID: self.liveId)
+
+           // 2. Get the BarrageStore instance (thanks to internal mechanisms, this will be the same instance)
+           let barrageStore = BarrageStore.create(liveID: self.liveId)
+
+           // 3. Subscribe to audience events
+           audienceStore.liveAudienceEventPublisher
+               .receive(on: DispatchQueue.main)
+               .sink { event in
+                   // 4. Only handle audience join events
+                   guard case .onAudienceJoined(let newAudience) = event else {
+                       return
+                   }
+
+                   // 5. Create a local tip message
+                   var welcomeTip = Barrage()
+                   welcomeTip.messageType = .text
+                   welcomeTip.textContent = "Welcome \(newAudience.userName) to the live room!"
+
+                   // 6. Call BarrageStore's API to insert it into the barrage list
+                   barrageStore.appendLocalTip(message: welcomeTip)
+               }
+               .store(in: &cancellables)
+       }
+   }
+   ```
+
+## API Documentation
+
+For detailed information on all public interfaces, properties, and methods of [LiveAudienceStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/liveaudiencestore) and its related classes, refer to the official API documentation included with the [AtomicX Core](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore) framework. The relevant Stores used in this document are as follows:
+| **Store/Component** | **Feature Description** | **API Documentation** |
+| --- | --- | --- |
+| LiveCoreView | Core view component for live video stream display and interaction: responsible for video stream rendering and view widget handling, supporting scenarios such as host streaming, audience co-hosting, and host-to-host connection. | [API Documentation](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/livecoreview) |
+| LiveAudienceStore | Audience management: obtain real-time audience list (ID / name / avatar), count audience numbers, and listen for audience join/leave events. | [API Documentation](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/liveaudiencestore) |
+| BarrageStore | Barrage feature: send text/custom barrage, maintain barrage list, and listen to barrage status in real time. | [API Documentation](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/barragestore) |
+
+## FAQs
+
+### How is the online audience count (audienceCount) in LiveAudienceState updated? What are the timing and frequency?
+
+The `audienceCount` is a high-precision estimate. Updates occur based on specific triggers and are subject to system frequency controls:
+- **Active Entry/Exit (Immediate)**:When a user explicitly joins or leaves the room, the count updates immediately in `LiveAudienceState`.
+
+- **Unexpected Disconnection (Delayed)**:If a user disconnects abnormally (e.g., app crash, network loss), the system uses a heartbeat mechanism to verify status. The user is marked offline only after 90 seconds of inactivity, triggering a delayed count update.
+
+- **Frequency Control & Rate Limiting**: Audience count updates are broadcast as room messages. The system enforces a limit of 40 messages per second per room.
+
+   > **Note：**
+   >
+
+   > During high-traffic spikes (e.g., chat floods or rapid gifting), if the message rate exceeds this threshold, the system prioritizes core messages (like chat/barrage). Consequently, audience count update messages may be dropped to maintain stability.
+   >
+
+- **What does this mean for developers?**
+
+   Treat `audienceCount` as a metric for UI display purposes only. Do not rely on it for billing, critical statistics, or scenarios requiring 100% accuracy, as brief delays or data loss may occur during high-concurrency events.

package/resource/doc/livekit/core-sdk/voice/ios/voice-audio-effect.md

@@ -0,0 +1,212 @@
+This document provides guidance on integrating audio effect controls into your live streaming application using the `AudioEffectStore` and `DeviceStore` modules from the **AtomicXCore** framework. These modules enable features such as microphone volume control, ear monitoring, and a variety of voice changing and reverb effects.
+
+## Core Features
+
+By combining `AudioEffectStore` and `DeviceStore`, you can implement the following core features:
+- **Microphone Volume Adjustment**: Control the local microphone (capture) volume, which determines the volume your audience hears.
+
+- **Ear Monitoring**: Allow hosts or co-hosts to hear their own voice in real time through headphones for monitoring and pronunciation correction.
+
+- **Voice Effects**: Apply various voice changing effects, such as "Little Girl", "Deep Male", "Naughty Child", and more.
+
+- **Reverb Effects**: Simulate different acoustic environments, such as KTV, metallic, deep, bright, and others.
+
+## Core Concepts
+| **Core Concept** | **Type** | **Core Responsibility & Description** |
+| --- | --- | --- |
+| `AudioChangerType` | `enum` | Enumerates available voice changing effects, such as "child", "man", etc. |
+| `AudioReverbType` | `enum` | Enumerates available reverb effects, such as "ktv", "hall", etc. |
+| `AudioEffectState` | `struct` | Represents the current state of the audio effect module, typically used for UI rendering. Includes voice changing effect state, reverb state, ear monitoring enabled state, and ear monitor volume. |
+| `AudioEffectStore` | `class` | Singleton data management class for audio effects. Use it to invoke audio effect APIs. After calling an API, the corresponding state property is automatically updated. Subscribe to this reactive state to receive and monitor updates. |
+| `DeviceState` | `struct` | Represents the current state of the device module, typically used for UI rendering. Core properties include camera and microphone status. |
+| `DeviceStore` | `class` | Singleton data management class for device operations. Use it to control the camera and microphone. After calling an API, the corresponding state property is automatically updated. Subscribe to this reactive state to receive and monitor updates. |
+
+## Implementation
+
+### Step 1: Component Integration
+- **Video Live Streaming**: Please refer to Quick Start to integrate **AtomicXCore**.
+
+- **Voice Chat Room**: Please refer to Quick Start to integrate **AtomicXCore**.
+
+### Step 2: Obtain Store Instances
+
+`AudioEffectStore` and `DeviceStore` are singleton objects. Access their instances via the shared property anywhere in your project. For a complete implementation example, see [AudioEffectView.swift](https://github.com/Tencent-RTC/TUIKit_iOS/blob/main/live/Sources/Component/AudioEffect/AudioEffectView.swift) in the `TUILiveKit` open-source UI demo project.
+``` swift
+import UIKit
+import AtomicXCore
+import Combine
+
+let audioEffectStore = AudioEffectStore.shared
+let deviceStore = DeviceStore.shared
+```
+
+### Step 3: Implement In-ear Monitoring
+
+In-ear monitoring allows users to hear their microphone audio in real time. Manage in-ear monitoring by calling the interfaces described below.
+
+> **Note:**
+>
+
+> In-ear monitoring typically requires headphones to function properly.
+>
+
+#### Implementation
+1. **Toggle Ear Monitoring**: Use a `UISwitch` control to enable or disable in-ear monitoring.
+
+2. **Set Ear Monitor Volume**: Use a `UISlider` control to adjust the volume. Map the `UISlider` value to the range `[0, 150]` and call `setVoiceEarMonitorVolume(_:)`.
+
+3. **Subscribe to State Updates**: Listen for real-time ear monitor state changes to update the UI.
+
+#### Code Example
+``` swift
+// 1. Enable ear monitoring
+audioEffectStore.setVoiceEarMonitorEnable(enable: true)
+
+// 2. Adjust ear monitor volume
+audioEffectStore.setVoiceEarMonitorVolume(volume: 80)
+
+// 3. Disable ear monitoring
+audioEffectStore.setVoiceEarMonitorEnable(enable: false)
+
+// 4. Listen for state changes
+audioEffectStore.state
+    .subscribe(StatePublisherSelector(keyPath: \AudioEffectState.earMonitorVolume))
+    .removeDuplicates()
+    .sink { currentVolume in
+        print("Ear monitor volume: \(currentVolume)")
+        valueLabel.text = "\(currentVolume)" // Update UILabel to display the value
+    }
+    .store(in: &cancellables)
+```
+
+#### setVoiceEarMonitorEnable Parameters
+| **Parameter Name** | **Type** | **Description** |
+| --- | --- | --- |
+| `enable` | `Bool` | Whether to enable ear monitoring.<br>- true: Enable<br>- false: Disable |
+
+#### setVoiceEarMonitorVolume Parameters
+| **Parameter Name** | **Type** | **Description** |
+| --- | --- | --- |
+| `volume` | `Int` | Ear monitor volume.<br>- Value range: [0, 150]<br>- Default: 100 |
+
+### Step 4: Implement Microphone Volume Adjustment
+
+To adjust the microphone (capture) volume, call the `setCaptureVolume(volume:)` method of DeviceStore with the desired value.
+
+#### Implementation
+1. **Set Capture Volume**: Use a `UISlider` control to adjust the volume. Map the `UISlider` value to the range `[0, 150]` and call `setCaptureVolume(volume:)`.
+
+2. **Subscribe to State Updates**: Listen for real-time volume state changes to update the UI.
+
+#### Code Example
+``` swift
+// 1. Adjust capture volume
+deviceStore.setCaptureVolume(volume: 80)
+
+// 2. Listen for state changes
+deviceStore.state
+    .subscribe(StatePublisherSelector(keyPath: \DeviceState.captureVolume))
+    .removeDuplicates()
+    .sink { captureVolume in
+        print("Capture volume: \(captureVolume)")
+        valueLabel.text = "\(captureVolume)" // Update UILabel to display the value
+    }
+    .store(in: &cancellables)
+```
+
+#### setCaptureVolume Parameters
+| **Parameter Name** | **Type** | **Description** |
+| --- | --- | --- |
+| `volume` | `Int` | Microphone (capture) volume.<br>- Value range: [0, 150]<br>- Default: 100 |
+
+### Step 5: Implement Voice Effects
+
+To apply a voice changing effect, call the `setAudioChangerType(type:)` method and pass the desired enum value.
+
+#### Code Example
+``` swift
+// Set voice changer effect to "child"
+audioEffectStore.setAudioChangerType(type: .child)
+// Disable voice changer effect
+audioEffectStore.setAudioChangerType(type: .none)
+```
+
+#### setAudioChangerType Parameters
+| **Parameter Name** | **Type** | **Description** |
+| --- | --- | --- |
+| `type` | `AudioChangerType` | Voice changer effect enumeration. |
+
+### Step 6: Implement Reverb Effects
+
+To apply a reverb effect, call the `setAudioReverbType(type:) `method and pass the desired enum value.
+``` swift
+// Set reverb effect to "KTV"
+audioEffectStore.setAudioReverbType(type: .ktv)
+// Disable reverb effect
+audioEffectStore.setAudioReverbType(type: .none)
+```
+
+#### setAudioReverbType Parameters
+| **Parameter Name** | **Type** | **Description** |
+| --- | --- | --- |
+| `type` | `AudioReverbType` | Reverb effect enumeration. |
+
+### Step 7: Reset Audio Effect Settings
+
+> **Note：**
+>
+
+> AudioEffectStore and DeviceStore are singletons, so audio effect and device settings apply globally. To prevent settings from one live room affecting others, reset the audio effect and device settings when the current live room ends.
+>
+
+Reset audio effect settings in the following scenarios:
+1. When the current live room ends.
+
+2. To provide a "one-click restore" feature, call the store's `reset()` method.
+
+   ``` swift
+   class YourMainViewController: UIViewController {
+       func reset() {
+           AudioEffectStore.shared.reset()
+           DeviceStore.shared.reset()
+       }
+   }
+   ```
+
+## API Documentation
+
+For detailed information on all public interfaces and properties of [AudioEffectStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/audioeffectstore), [DeviceStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/devicestore), and related classes, refer to the official API documentation for the [AtomicXCore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore) framework.
+| **Store/Component** | **Description** | **API Reference** |
+| --- | --- | --- |
+| DeviceStore | Controls audio/video devices: microphone (on/off, volume), camera (on/off, switch, quality), screen sharing, and real-time device status monitoring. | [API Documentation](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/devicestore) |
+| AudioEffectStore | Audio effects: voice changing (child/male), reverb (KTV, etc.), ear monitoring adjustment, and real-time effect switching. | [API Documentation](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/audioeffectstore) |
+
+## FAQs
+
+### Are there any restrictions on when to call audio effect and device APIs?
+
+No. `AudioEffectStore` and `DeviceStore` settings are globally effective. You can call relevant APIs (such as setting voice changing effects, reverb, or ear monitoring) at any time before or after entering a live room. Settings take effect immediately and persist.
+
+### What is the difference between "Microphone Volume" and "Ear Monitor Volume"?
+
+This is a common point of confusion:
+- **Microphone Volume (Capture Volume)**: Set via `DeviceStore.setCaptureVolume()`. Controls the volume your audience hears.
+
+- **Ear Monitor Volume**: Set via `AudioEffectStore.setVoiceEarMonitorVolume()`.  It only determines the volume level you hear in your in-ear monitor and does not affect the audience.
+
+### Why does a newly created live room already have audio effects, or why is the volume too high or too low?
+
+Because `AudioEffectStore` and `DeviceStore` are singletons, audio effect and device settings are globally applied. If you previously set audio effects and did not reset them, those settings persist. Call the `reset()` method at the appropriate time to clear them.
+
+### Why can't I hear my own voice after enabling "Ear Monitoring"?
+
+Check the following:
+1. **Are headphones connected?** Ear monitoring generally requires headphones. Ensure wired or Bluetooth headphones are connected.
+
+2. **Is the ear monitor volume set to 0?** Check that the ear monitor volume is above 0.
+
+3. **Is the microphone enabled?** Confirm that the microphone is enabled in DeviceStore (i.e., openLocalMicrophone has been called).
+
+### Can voice effects and reverb be enabled at the same time?
+
+Yes. `AudioChangerType` and `AudioReverbType` can be enabled simultaneously. For example, you can set both `AudioChangerType.LITTLE_GIRL`and `AudioReverbType.KTV` at the same time.