@tencent-rtc/trtc-agent-skills 0.1.0

package/knowledge-base/slices/live/ios/device-control.md

@@ -0,0 +1,286 @@
+---
+id: live/device-control
+platform: ios
+---
+
+# 设备管理 — iOS 实现
+
+## 前置条件
+
+**依赖安装（Podfile）**
+```ruby
+pod 'AtomicXCore', '~> 4.0'
+```
+
+**Info.plist 权限声明**（两项均须配置，否则系统拒绝授权或 App 崩溃）
+```xml
+<key>NSCameraUsageDescription</key>
+<string>需要访问摄像头以进行视频直播</string>
+<key>NSMicrophoneUsageDescription</key>
+<string>需要访问麦克风以进行语音直播</string>
+```
+
+**前置状态**：
+- `LoginStore.shared` 登录成功（登录成功后才可操作设备）
+- 系统权限已授予（AVAuthorizationStatus == .authorized）
+
+## API 调用（真实签名）
+
+```swift
+// ── 摄像头 ──────────────────────────────────────────────────────────
+DeviceStore.shared.openLocalCamera(isFront: Bool, completion: CompletionClosure?)
+DeviceStore.shared.closeLocalCamera()
+DeviceStore.shared.switchCamera(isFront: Bool)          // 不中断采集，切换前/后置
+
+// ── 麦克风 ──────────────────────────────────────────────────────────
+DeviceStore.shared.openLocalMicrophone(completion: CompletionClosure?)
+DeviceStore.shared.closeLocalMicrophone()
+
+// ── 音量控制 ─────────────────────────────────────────────────────────
+DeviceStore.shared.setCaptureVolume(volume: Int)         // 采集音量，range [0, 100]
+DeviceStore.shared.setOutputVolume(_ volume: Int)        // 播放音量，range [0, 100]
+
+// ── 音频路由 ─────────────────────────────────────────────────────────
+DeviceStore.shared.setAudioRoute(_ route: AudioRoute)
+
+// ── 镜像与画质 ───────────────────────────────────────────────────────
+DeviceStore.shared.switchMirror(mirrorType: MirrorType)
+DeviceStore.shared.updateVideoQuality(_ quality: VideoQuality)
+
+// ── 状态快照 ─────────────────────────────────────────────────────────
+DeviceStore.shared.state  // StatePublisher<DeviceState>
+```
+
+**DeviceState 关键字段**
+```swift
+struct DeviceState {
+    var microphoneStatus: DeviceStatus
+    var captureVolume: Int          // range [0, 100]  ⚠️ 不是 0-150
+    var outputVolume: Int           // range [0, 100]
+    var cameraStatus: DeviceStatus
+    var isFrontCamera: Bool
+    var localMirrorType: MirrorType
+    var localVideoQuality: VideoQuality
+    var currentAudioRoute: AudioRoute
+    var networkInfo: NetworkInfo
+}
+```
+
+**通用回调类型**
+```swift
+typealias CompletionClosure = (Result<Void, ErrorInfo>) -> Void
+
+struct ErrorInfo {
+    var code: Int
+    var message: String
+}
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `isFront` | `Bool` | `true` = 前置摄像头，`false` = 后置摄像头 |
+| `completion` | `CompletionClosure?` | 异步回调 `(Result<Void, ErrorInfo>) -> Void`；`nil` 表示不关心结果 |
+| `volume` | `Int` | 音量范围 **[0, 100]**（注意不是 0-150） |
+
+## 代码示例
+
+```swift
+import AtomicXCore
+import AVFoundation
+
+// MARK: - 打开摄像头（含权限检查）
+
+func openCamera(isFront: Bool = true) {
+    // 先检查系统权限
+    switch AVCaptureDevice.authorizationStatus(for: .video) {
+    case .authorized:
+        DeviceStore.shared.openLocalCamera(isFront: isFront) { result in
+            switch result {
+            case .success:
+                print("[Device] 摄像头打开成功, 前置: \(isFront)")
+            case .failure(let errorInfo):
+                print("[Device] 摄像头打开失败, code: \(errorInfo.code), msg: \(errorInfo.message)")
+                handleDeviceError(errorInfo)
+            }
+        }
+    case .notDetermined:
+        AVCaptureDevice.requestAccess(for: .video) { granted in
+            DispatchQueue.main.async {
+                if granted { openCamera(isFront: isFront) }
+            }
+        }
+    case .denied, .restricted:
+        guideToSettings(message: "请在「设置 > 隐私 > 摄像头」中开启权限")
+    @unknown default:
+        break
+    }
+}
+
+// MARK: - 打开麦克风
+
+func openMicrophone() {
+    DeviceStore.shared.openLocalMicrophone { result in
+        switch result {
+        case .success:
+            print("[Device] 麦克风打开成功")
+        case .failure(let errorInfo):
+            print("[Device] 麦克风打开失败, code: \(errorInfo.code)")
+            handleDeviceError(errorInfo)
+        }
+    }
+}
+
+// MARK: - 关闭设备
+
+func closeAllDevices() {
+    DeviceStore.shared.closeLocalCamera()
+    DeviceStore.shared.closeLocalMicrophone()
+}
+
+// MARK: - 切换前后摄像头（不中断推流）
+
+func flipCamera(toFront: Bool) {
+    DeviceStore.shared.switchCamera(isFront: toFront)
+}
+
+// MARK: - 音量调节（range [0, 100]）
+
+func setCaptureVolume(_ volume: Int) {
+    // ⚠️ 范围是 [0, 100]，不是 [0, 150]
+    let clamped = min(max(volume, 0), 100)
+    DeviceStore.shared.setCaptureVolume(volume: clamped)
+}
+
+func setOutputVolume(_ volume: Int) {
+    let clamped = min(max(volume, 0), 100)
+    DeviceStore.shared.setOutputVolume(clamped)
+}
+
+// MARK: - 音频路由切换（扬声器 / 听筒）
+
+func switchToSpeaker() {
+    DeviceStore.shared.setAudioRoute(.speaker)
+}
+
+func switchToEarpiece() {
+    DeviceStore.shared.setAudioRoute(.earpiece)
+}
+
+// MARK: - 错误处理
+
+func handleDeviceError(_ errorInfo: ErrorInfo) {
+    switch errorInfo.code {
+    case -1101:
+        guideToSettings(message: "摄像头权限被拒，请前往系统设置开启")
+    case -1102:
+        print("摄像头被其他应用占用，请关闭后重试")
+    case -1103:
+        print("当前设备不支持摄像头（请使用真机测试）")
+    case -1105:
+        guideToSettings(message: "麦克风权限被拒，请前往系统设置开启")
+    case -1106:
+        print("麦克风被其他应用占用，请结束通话后重试")
+    default:
+        print("设备错误 code: \(errorInfo.code), msg: \(errorInfo.message)")
+    }
+}
+
+func guideToSettings(message: String) {
+    DispatchQueue.main.async {
+        // 引导用户跳转到系统设置（业务自行实现 Alert UI）
+        if let url = URL(string: UIApplication.openSettingsURLString) {
+            UIApplication.shared.open(url)
+        }
+    }
+}
+```
+
+**主播开播：同时打开摄像头和麦克风**：
+```swift
+func openAllDevicesForAnchor() {
+    openCamera(isFront: true)   // 先打开摄像头
+    openMicrophone()            // 再打开麦克风
+    // 注意：如需串行等待，请在 openCamera 的 completion .success 分支内调用 openMicrophone
+}
+
+// 主播下播：关闭所有设备
+func closeAllDevicesOnStop() {
+    DeviceStore.shared.closeLocalCamera()
+    DeviceStore.shared.closeLocalMicrophone()
+}
+```
+
+## 调用时序
+
+```
+权限检查
+    │
+    ├─ 未确定（notDetermined）
+    │       └─ 系统弹窗 → 用户授权/拒绝
+    │
+    ├─ 已拒绝（denied）
+    │       └─ 展示引导弹窗 → 跳转系统设置
+    │
+    └─ 已授权（authorized）
+            │
+            ▼
+    DeviceStore.shared.openLocalCamera(isFront: true, completion:)
+            │
+            ├─ .failure(errorInfo)
+            │       ├─ code -1100 → 重试或上报
+            │       ├─ code -1101 → 系统授权异常（引导去设置）
+            │       ├─ code -1102 → 提示关闭其他应用
+            │       └─ code -1103 → 模拟器，提示换真机
+            │
+            └─ .success
+                    │
+                    ▼
+            DeviceStore.shared.openLocalMicrophone(completion:)
+                    │
+                    ├─ .failure(errorInfo) → 同上处理
+                    │
+                    └─ .success
+                            │
+                            ▼
+                    设备就绪，进行推流/预览
+                            │
+                    [使用中]
+                    switchCamera(isFront:)         ← 切换前后置（无黑屏）
+                    setCaptureVolume(volume:)      ← 调节采集音量 [0, 100]
+                    setAudioRoute(.speaker)        ← 切换音频路由
+                            │
+                            ▼
+                    DeviceStore.shared.closeLocalCamera()
+                    DeviceStore.shared.closeLocalMicrophone()
+                    （下播 / 退房 / App 进入后台）
+```
+
+## 平台特有注意事项
+
+### 1. captureVolume 范围是 [0, 100]，不是 [0, 150]
+`setCaptureVolume(volume:)` 和 `setOutputVolume(_:)` 的有效范围均为 **[0, 100]**。传入超过 100 的值会被 SDK 忽略或截断。不要将范围设为 0-150。
+
+### 2. iOS 权限弹窗时机
+系统权限弹窗**只会弹出一次**（首次请求时）。若用户拒绝后，后续调用 `requestAccess` 不再弹窗，必须引导用户手动前往系统设置开启。建议在开播前明确告知用户权限用途，提高授权通过率。
+
+### 3. 后台摄像头自动关闭
+iOS 系统在 App 进入后台时会**自动挂起摄像头采集**。主播场景中若需要后台推流，须在 `Info.plist` 中开启后台音视频模式：
+```xml
+<key>UIBackgroundModes</key>
+<array>
+    <string>audio</string>
+</array>
+```
+即使开启后台模式，摄像头视频帧在后台仍会停止推送，建议切后台时向观众提示"主播暂时离开"。
+
+### 4. 摄像头被其他进程占用（-1102）
+iOS 系统级应用（如 FaceTime、系统相机）在前台时会独占摄像头。当 App 从后台切回前台并重新打开摄像头时，若系统摄像头仍被其他应用持有，会触发 `-1102`。解决方案：监听 `UIApplication.didBecomeActiveNotification`，延迟 0.5~1 秒后重试打开摄像头。
+
+### 5. ErrorInfo 不是 Swift Error
+回调中的 `errorInfo` 是 `ErrorInfo` 结构体，直接用 `.code` 和 `.message` 访问，不可当作 `Error` 使用：
+```swift
+case .failure(let errorInfo):
+    let code = errorInfo.code       // ✅
+    let msg  = errorInfo.message    // ✅
+    // errorInfo as? Error          // ❌ 不适用
+```

package/knowledge-base/slices/live/ios/error-codes.md

@@ -0,0 +1,270 @@
+---
+id: live/error-codes
+platform: ios
+---
+
+# 错误码参考 — iOS 实现
+
+## 前置条件
+
+AtomicXCore SDK 所有异步接口均通过 Swift `Result<T, ErrorInfo>` 回调返回错误。
+
+**错误类型是 `ErrorInfo` 结构体，不是 Swift `Error` 协议**：
+
+```swift
+struct ErrorInfo {
+    var code: Int       // 错误码（负数：客户端；正数：服务端）
+    var message: String // 错误描述
+}
+
+// 所有异步回调的统一签名
+typealias CompletionClosure = (Result<Void, ErrorInfo>) -> Void
+```
+
+## API 调用（错误码提取方式）
+
+```swift
+// ✅ 正确：直接从 ErrorInfo 结构体取字段
+LoginStore.shared.login(sdkAppID: 1400000001,
+                        userID: "user_001",
+                        userSig: userSig) { result in
+    switch result {
+    case .success:
+        break
+    case .failure(let errorInfo):   // errorInfo: ErrorInfo（不是 Error）
+        let code = errorInfo.code
+        let msg  = errorInfo.message
+    }
+}
+
+// ✅ 返回 LiveInfo 的回调（LiveInfoCompletionClosure）
+// typealias LiveInfoCompletionClosure = (Result<LiveInfo, ErrorInfo>) -> Void
+LiveListStore.shared.joinLive(liveID: "room_001") { result in
+    switch result {
+    case .success(let liveInfo):    // liveInfo: LiveInfo
+        print("直播间名称: \(liveInfo.liveName)")
+    case .failure(let errorInfo):
+        print("进房失败, code: \(errorInfo.code)")
+    }
+}
+```
+
+## 代码示例
+
+```swift
+import AtomicXCore
+
+// MARK: - 统一错误处理器
+
+final class ErrorHandler {
+
+    // MARK: - 从 ErrorInfo 提取信息
+
+    /// 直接从 ErrorInfo 取 code 和 message
+    static func log(_ errorInfo: ErrorInfo, context: String = #function) {
+        print("[ErrorHandler] [\(context)] code=\(errorInfo.code), msg=\(errorInfo.message)")
+    }
+
+    // MARK: - 分类处理（按 errorInfo.code 分支）
+
+    static func handle(_ errorInfo: ErrorInfo,
+                       context: String = #function,
+                       retryHandler: (() -> Void)? = nil) {
+        log(errorInfo, context: context)
+
+        switch errorInfo.code {
+        // ── 通用错误 ──────────────────────────────────────────
+        case -1000:
+            showAlert(title: "配置错误", message: "SDKAppID 不合法，请检查控制台配置")
+        case -1001:
+            showAlert(title: "参数错误", message: "UserSig 已过期或参数不合法，请重新获取")
+        case -1002:
+            showAlert(title: "未登录", message: "请先完成登录后再进行操作")
+        case -1003:
+            guideToSystemPermissionSettings()
+
+        // ── 限频（可重试）────────────────────────────────────
+        case -2:
+            retryWithBackoff(handler: retryHandler)
+
+        // ── 设备错误 ──────────────────────────────────────────
+        case -1101:
+            guideToSystemPermissionSettings(permissionType: .camera)
+        case -1102:
+            showAlert(title: "摄像头占用", message: "请关闭其他正在使用摄像头的应用后重试")
+        case -1103:
+            showAlert(title: "无摄像头", message: "当前设备不支持摄像头，请使用真机测试")
+        case -1105:
+            guideToSystemPermissionSettings(permissionType: .microphone)
+        case -1106:
+            showAlert(title: "麦克风占用", message: "请结束通话或关闭其他语音应用后重试")
+        case -1100, -1104:
+            showAlert(title: "设备错误",
+                      message: "设备打开失败（code: \(errorInfo.code)），请重启应用后重试")
+
+        // ── 房间错误 ──────────────────────────────────────────
+        case -2101:
+            showAlert(title: "操作错误", message: "请先进入房间再执行此操作")
+        case -2105:
+            showAlert(title: "参数错误", message: "直播间 ID 格式非法（须为 ASCII，≤ 48 字节）")
+        case -2107:
+            showAlert(title: "参数错误", message: "直播间名称非法（UTF-8，≤ 30 字节）")
+        case -2108:
+            showAlert(title: "已在房间内", message: "您已在其他房间中，请先退出后再加入新房间")
+
+        // ── 权限/信令错误 ─────────────────────────────────────
+        case -2380:
+            showAlert(title: "全员禁言", message: "当前房间已开启全员禁言，请等待房主解除")
+        case -2381:
+            showAlert(title: "被禁言", message: "您已被禁言，请联系房主申请解除")
+
+        // ── 服务端错误（可重试）──────────────────────────────
+        case 100001:
+            retryWithBackoff(handler: retryHandler)
+
+        // ── 未知错误 ──────────────────────────────────────────
+        default:
+            showAlert(title: "未知错误", message: "错误码：\(errorInfo.code)\n\(errorInfo.message)")
+        }
+    }
+
+    // MARK: - UI 工具方法
+
+    private static func showAlert(title: String, message: String) {
+        DispatchQueue.main.async {
+            guard let topVC = UIApplication.shared.topViewController else { return }
+            let alert = UIAlertController(title: title, message: message, preferredStyle: .alert)
+            alert.addAction(UIAlertAction(title: "确定", style: .default))
+            topVC.present(alert, animated: true)
+        }
+    }
+
+    enum PermissionType { case camera, microphone }
+
+    static func guideToSystemPermissionSettings(permissionType: PermissionType? = nil) {
+        let message: String
+        switch permissionType {
+        case .camera:
+            message = "请前往「设置 > 隐私与安全 > 摄像头」开启权限"
+        case .microphone:
+            message = "请前往「设置 > 隐私与安全 > 麦克风」开启权限"
+        case nil:
+            message = "请前往系统设置开启所需权限"
+        }
+        DispatchQueue.main.async {
+            guard let topVC = UIApplication.shared.topViewController else { return }
+            let alert = UIAlertController(title: "权限不足", message: message, preferredStyle: .alert)
+            alert.addAction(UIAlertAction(title: "去设置", style: .default) { _ in
+                if let url = URL(string: UIApplication.openSettingsURLString) {
+                    UIApplication.shared.open(url)
+                }
+            })
+            alert.addAction(UIAlertAction(title: "取消", style: .cancel))
+            topVC.present(alert, animated: true)
+        }
+    }
+
+    private static var retryCount = 0
+    private static let maxRetries = 3
+
+    private static func retryWithBackoff(handler: (() -> Void)?) {
+        guard let handler = handler, retryCount < maxRetries else {
+            retryCount = 0
+            showAlert(title: "请求失败", message: "多次重试后仍然失败，请稍后再试")
+            return
+        }
+        let delay = pow(2.0, Double(retryCount))
+        retryCount += 1
+        DispatchQueue.main.asyncAfter(deadline: .now() + delay) {
+            handler()
+        }
+    }
+}
+
+// MARK: - UIApplication 顶层 ViewController 扩展
+
+extension UIApplication {
+    var topViewController: UIViewController? {
+        var topVC = connectedScenes
+            .compactMap { $0 as? UIWindowScene }
+            .flatMap { $0.windows }
+            .first { $0.isKeyWindow }?
+            .rootViewController
+        while let presented = topVC?.presentedViewController {
+            topVC = presented
+        }
+        return topVC
+    }
+}
+```
+
+**调用示例**：
+```swift
+// 登录错误处理
+LoginStore.shared.login(sdkAppID: 1400000001,
+                        userID: "user_001",
+                        userSig: userSig) { result in
+    switch result {
+    case .success:
+        print("登录成功")
+    case .failure(let errorInfo):
+        ErrorHandler.handle(errorInfo, context: "login")
+    }
+}
+
+// 设备错误处理（含重试）
+DeviceStore.shared.openLocalCamera(isFront: true) { result in
+    switch result {
+    case .success:
+        print("摄像头打开成功")
+    case .failure(let errorInfo):
+        ErrorHandler.handle(errorInfo, context: "openLocalCamera") {
+            // 重试逻辑
+            DeviceStore.shared.openLocalCamera(isFront: true, completion: nil)
+        }
+    }
+}
+```
+
+## iOS 特有：权限错误与系统权限对应
+
+iOS 系统权限与 SDK 错误码的对应关系：
+
+| SDK 错误码 | AVFoundation 权限状态 | 系统设置路径 | 处理方式 |
+|------------|----------------------|-------------|---------|
+| `-1101` | `AVAuthorizationStatus.denied`（摄像头） | 设置 > 隐私与安全 > 摄像头 | 弹窗引导跳转 `UIApplication.openSettingsURLString` |
+| `-1105` | `AVAuthorizationStatus.denied`（麦克风） | 设置 > 隐私与安全 > 麦克风 | 弹窗引导跳转 `UIApplication.openSettingsURLString` |
+| `-1003` | 系统级权限被拒 | 设置 > 隐私与安全 | 通用权限引导 |
+
+**权限状态主动检测**（在调用 SDK 前预检，避免先触发错误码再处理）：
+
+```swift
+import AVFoundation
+
+func checkAndRequestCameraPermission(completion: @escaping (Bool) -> Void) {
+    let status = AVCaptureDevice.authorizationStatus(for: .video)
+    switch status {
+    case .authorized:
+        completion(true)
+    case .notDetermined:
+        // 首次询问 — 系统弹窗只弹一次
+        AVCaptureDevice.requestAccess(for: .video) { granted in
+            DispatchQueue.main.async { completion(granted) }
+        }
+    case .denied, .restricted:
+        // 已拒绝 — 引导前往系统设置（requestAccess 不再弹窗）
+        DispatchQueue.main.async {
+            ErrorHandler.guideToSystemPermissionSettings(permissionType: .camera)
+            completion(false)
+        }
+    @unknown default:
+        completion(false)
+    }
+}
+```
+
+**注意事项**：
+- `Result<Void, ErrorInfo>` 的失败分支中，`errorInfo` 是 `ErrorInfo` 结构体，**不是** `Swift.Error`，无法调用 `localizedDescription`。
+- `AVCaptureDevice.requestAccess` 只触发**一次**系统弹窗。用户拒绝后，再次调用不会弹窗，需手动引导前往设置。
+- iOS 模拟器不支持摄像头，`AVAuthorizationStatus` 始终返回 `.authorized` 但打开后会收到 `-1103`，请在真机上测试设备功能。
+- 权限状态缓存在 App 沙盒中，卸载重装后会重置。测试时需注意。