音频路由（iOS）

public enum AudioRouteTarget {
    case speaker    // 扬声器（免提）
    case earpiece   // 听筒
}

// 语音通话场景：默认走听筒
AudioRouteSession.shared.defaultAudioRoute = .earpiece

// 视频会议场景：默认走免提
AudioRouteSession.shared.defaultAudioRoute = .speaker

// 用户点了免提按钮
AudioRouteSession.shared.setAudioRoute(.speaker)

// 用户点了听筒
AudioRouteSession.shared.setAudioRoute(.earpiece)

// 放弃临时选择，回到 defaultAudioRoute
AudioRouteSession.shared.clearAudioRouteOverride()

<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
</array>

let session = AudioRouteSession.shared

session.currentRoute           // .speaker / .receiver / .bluetooth / .headset / .unknown
session.currentRoute.isExternal // 是否走在蓝牙或有线耳机上
session.effectiveRouteTarget   // 当前生效目标 = 临时覆盖 ?? 持久默认
session.routeOverride          // 临时覆盖，nil 表示没有
session.isBluetoothAvailable   // 蓝牙耳机是否在位
session.isHeadsetAvailable     // 有线耳机是否在位
session.isEngaged              // 音频通道是否已建立（入会中 / 采集中）

final class RouteObserver: AudioRouteSessionDelegate {
    init() {
        AudioRouteSession.shared.delegates.add(delegate: self)
    }

    func audioRouteSession(
        _ session: AudioRouteSession,
        didChangeRoute route: AudioRoute,
        from previousRoute: AudioRoute,
        reason: AVAudioSession.RouteChangeReason
    ) {
        // 已在主线程回调，可直接更新 UI
        print("路由变化：\(previousRoute.displayName) → \(route.displayName)")
    }

    func audioRouteSessionWasInterrupted(_ session: AudioRouteSession) {
        // 来电 / Siri / 其他 App 抢占
    }

    func audioRouteSessionDidRecoverFromInterruption(_ session: AudioRouteSession) {
        // 中断真正恢复后才触发（可能延后，见下）
    }

    func audioRouteSession(_ session: AudioRouteSession, didChangeCallState callState: AudioCallState) {
        // 系统通话状态：.incoming / .connected / .disconnected 等
    }
}

try DeviceManager.shared.setSpeakerOutputPreferred(true)   // 等价于 setAudioRoute(.speaker)
try DeviceManager.shared.setSpeakerOutputPreferred(false)  // 等价于 setAudioRoute(.earpiece)
DeviceManager.shared.isSpeakerOutputPreferred              // 当前是否走外放

import SRTC

final class CallAudioController: AudioRouteSessionDelegate {
    private let session = AudioRouteSession.shared

    /// 入会前调用：定好默认行为
    func prepare(isVideoCall: Bool) {
        session.defaultAudioRoute = isVideoCall ? .speaker : .earpiece
        session.delegates.add(delegate: self)
    }

    /// 免提按钮
    func toggleSpeaker() {
        let next: AudioRouteTarget = session.currentRoute == .speaker ? .earpiece : .speaker
        session.setAudioRoute(next)

        // 外设在用时切换不会生效，据此给用户提示
        if session.currentRoute.isExternal {
            showToast("当前使用\(session.currentRoute.displayName)，请在系统控制中心切换")
        }
    }

    func audioRouteSession(
        _ session: AudioRouteSession,
        didChangeRoute route: AudioRoute,
        from previousRoute: AudioRoute,
        reason: AVAudioSession.RouteChangeReason
    ) {
        updateSpeakerButton(isOn: route == .speaker, isEnabled: !route.isExternal)
    }
}