Skip to content

Fastest and only macOS Dictation app with on-device STT and custom trained AI enhancement model. Windows, iOS testflight! Android, Linux waitlist open! A local Wispr Flow alternative. Follow https://x.com/fluidvoiceapp for more

74.4 KB
Raw Blame
import CoreAudio
#if SWIFT_PACKAGE
import CoreAudioCaptureSupport
#endif
import Foundation

nonisolated enum DirectCoreAudioDeviceSelection: Equatable {
    case systemDefault
    case preferredUID(String)
}

typealias DirectCoreAudioPacketHandler = @Sendable (
    _ samples: UnsafePointer<Float>,
    _ frameCount: Int,
    _ sampleRate: Double,
    _ inputHostTime: UInt64,
    _ inputSampleTime: Int64
) -> Void

nonisolated struct DirectCoreAudioStreamFormatFingerprint: Equatable {
    let sampleRate: Double
    let formatID: AudioFormatID
    let formatFlags: AudioFormatFlags
    let bytesPerPacket: UInt32
    let framesPerPacket: UInt32
    let bytesPerFrame: UInt32
    let channelsPerFrame: UInt32
    let bitsPerChannel: UInt32

    init(_ format: AudioStreamBasicDescription) {
        self.sampleRate = format.mSampleRate
        self.formatID = format.mFormatID
        self.formatFlags = format.mFormatFlags
        self.bytesPerPacket = format.mBytesPerPacket
        self.framesPerPacket = format.mFramesPerPacket
        self.bytesPerFrame = format.mBytesPerFrame
        self.channelsPerFrame = format.mChannelsPerFrame
        self.bitsPerChannel = format.mBitsPerChannel
    }

    var logDescription: String {
        "\(Int(self.sampleRate.rounded()))Hz/" +
            "\(self.channelsPerFrame)ch/" +
            "\(self.bitsPerChannel)bit/" +
            "flags=0x\(String(self.formatFlags, radix: 16))/" +
            "bytesPerFrame=\(self.bytesPerFrame)"
    }
}

nonisolated struct DirectCoreAudioFormatFingerprint: Equatable {
    let deviceID: AudioObjectID
    let streamID: AudioStreamID
    let virtualFormat: DirectCoreAudioStreamFormatFingerprint
    let physicalFormat: DirectCoreAudioStreamFormatFingerprint?
    let inputBufferChannels: [UInt32]
    let nominalSampleRate: Double
    let bufferFrameSize: UInt32
    let variableBufferFrameSizeMaximum: UInt32?
    let dataSourceID: UInt32?

    var logDescription: String {
        let bufferLayout = self.inputBufferChannels.map(String.init).joined(separator: ",")
        let physical = self.physicalFormat?.logDescription ?? "unavailable"
        let dataSource = self.dataSourceID.map(String.init) ?? "unavailable"
        return "device=\(self.deviceID) stream=\(self.streamID) " +
            "virtual=\(self.virtualFormat.logDescription) physical=\(physical) " +
            "buffers=[\(bufferLayout)] nominalHz=\(Int(self.nominalSampleRate.rounded())) " +
            "bufferFrames=\(self.bufferFrameSize) " +
            "variableMax=\(self.variableBufferFrameSizeMaximum.map(String.init) ?? "fixed") " +
            "dataSource=\(dataSource)"
    }

    static func read(deviceID: AudioObjectID) throws -> Self {
        var aliveAddress = AudioObjectPropertyAddress(
            mSelector: kAudioDevicePropertyDeviceIsAlive,
            mScope: kAudioObjectPropertyScopeGlobal,
            mElement: kAudioObjectPropertyElementMain
        )
        let isAlive: UInt32 = try self.readScalar(
            objectID: deviceID,
            address: &aliveAddress,
            operation: "read input device liveness"
        )
        guard isAlive != 0 else {
            throw Self.error(
                status: kAudioHardwareBadDeviceError,
                operation: "read direct Core Audio format",
                detail: "device \(deviceID) is not alive"
            )
        }

        var streamsAddress = AudioObjectPropertyAddress(
            mSelector: kAudioDevicePropertyStreams,
            mScope: kAudioObjectPropertyScopeInput,
            mElement: kAudioObjectPropertyElementMain
        )
        let streams: [AudioStreamID] = try self.readArray(
            objectID: deviceID,
            address: &streamsAddress,
            operation: "read input streams"
        )
        guard streams.count == 1, let streamID = streams.first else {
            throw Self.error(
                status: kAudioHardwareUnsupportedOperationError,
                operation: "read direct Core Audio format",
                detail: "expected one input stream, found \(streams.count)"
            )
        }

        var virtualFormatAddress = AudioObjectPropertyAddress(
            mSelector: kAudioStreamPropertyVirtualFormat,
            mScope: kAudioObjectPropertyScopeGlobal,
            mElement: kAudioObjectPropertyElementMain
        )
        let virtualFormat: AudioStreamBasicDescription = try self.readScalar(
            objectID: streamID,
            address: &virtualFormatAddress,
            operation: "read input stream virtual format"
        )

        var physicalFormatAddress = AudioObjectPropertyAddress(
            mSelector: kAudioStreamPropertyPhysicalFormat,
            mScope: kAudioObjectPropertyScopeGlobal,
            mElement: kAudioObjectPropertyElementMain
        )
        let physicalFormat: AudioStreamBasicDescription? = self.readOptionalScalar(
            objectID: streamID,
            address: &physicalFormatAddress
        )

        var nominalRateAddress = AudioObjectPropertyAddress(
            mSelector: kAudioDevicePropertyNominalSampleRate,
            mScope: kAudioObjectPropertyScopeGlobal,
            mElement: kAudioObjectPropertyElementMain
        )
        let nominalSampleRate: Double = try self.readScalar(
            objectID: deviceID,
            address: &nominalRateAddress,
            operation: "read nominal input sample rate"
        )

        var bufferFrameSizeAddress = AudioObjectPropertyAddress(
            mSelector: kAudioDevicePropertyBufferFrameSize,
            mScope: kAudioObjectPropertyScopeGlobal,
            mElement: kAudioObjectPropertyElementMain
        )
        let bufferFrameSize: UInt32 = try self.readScalar(
            objectID: deviceID,
            address: &bufferFrameSizeAddress,
            operation: "read input buffer frame size"
        )

        var variableBufferSizeAddress = AudioObjectPropertyAddress(
            mSelector: kAudioDevicePropertyUsesVariableBufferFrameSizes,
            mScope: kAudioObjectPropertyScopeGlobal,
            mElement: kAudioObjectPropertyElementMain
        )
        let variableBufferFrameSizeMaximum: UInt32? = self.readOptionalScalar(
            objectID: deviceID,
            address: &variableBufferSizeAddress
        )

        var streamConfigurationAddress = AudioObjectPropertyAddress(
            mSelector: kAudioDevicePropertyStreamConfiguration,
            mScope: kAudioObjectPropertyScopeInput,
            mElement: kAudioObjectPropertyElementMain
        )
        let inputBufferChannels = try self.readInputBufferChannels(
            deviceID: deviceID,
            address: &streamConfigurationAddress
        )

        var dataSourceAddress = AudioObjectPropertyAddress(
            mSelector: kAudioDevicePropertyDataSource,
            mScope: kAudioObjectPropertyScopeInput,
            mElement: kAudioObjectPropertyElementMain
        )
        let dataSourceID: UInt32? = self.readOptionalScalar(
            objectID: deviceID,
            address: &dataSourceAddress
        )

        return Self(
            deviceID: deviceID,
            streamID: streamID,
            virtualFormat: DirectCoreAudioStreamFormatFingerprint(virtualFormat),
            physicalFormat: physicalFormat.map(DirectCoreAudioStreamFormatFingerprint.init),
            inputBufferChannels: inputBufferChannels,
            nominalSampleRate: nominalSampleRate,
            bufferFrameSize: bufferFrameSize,
            variableBufferFrameSizeMaximum: variableBufferFrameSizeMaximum,
            dataSourceID: dataSourceID
        )
    }

    static func captured(
        deviceID: AudioObjectID,
        streamID: AudioStreamID,
        virtualFormat: AudioStreamBasicDescription,
        bufferFrameSize: UInt32
    ) throws -> Self {
        let live = try self.read(deviceID: deviceID)
        return Self(
            deviceID: deviceID,
            streamID: streamID,
            virtualFormat: DirectCoreAudioStreamFormatFingerprint(virtualFormat),
            physicalFormat: live.streamID == streamID ? live.physicalFormat : nil,
            inputBufferChannels: live.inputBufferChannels,
            nominalSampleRate: live.nominalSampleRate,
            bufferFrameSize: bufferFrameSize,
            variableBufferFrameSizeMaximum: live.variableBufferFrameSizeMaximum,
            dataSourceID: live.dataSourceID
        )
    }

    private static func readScalar<T>(
        objectID: AudioObjectID,
        address: inout AudioObjectPropertyAddress,
        operation: String
    ) throws -> T {
        let pointer = UnsafeMutablePointer<T>.allocate(capacity: 1)
        defer { pointer.deallocate() }
        var size = UInt32(MemoryLayout<T>.size)
        let status = AudioObjectGetPropertyData(
            objectID,
            &address,
            0,
            nil,
            &size,
            pointer
        )
        guard status == noErr, size == UInt32(MemoryLayout<T>.size) else {
            throw self.error(status: status, operation: operation)
        }
        return pointer.move()
    }

    private static func readOptionalScalar<T>(
        objectID: AudioObjectID,
        address: inout AudioObjectPropertyAddress
    ) -> T? {
        guard AudioObjectHasProperty(objectID, &address) else { return nil }
        return try? self.readScalar(
            objectID: objectID,
            address: &address,
            operation: "read optional Core Audio property"
        )
    }

    private static func readArray<T>(
        objectID: AudioObjectID,
        address: inout AudioObjectPropertyAddress,
        operation: String
    ) throws -> [T] {
        var size: UInt32 = 0
        let sizeStatus = AudioObjectGetPropertyDataSize(
            objectID,
            &address,
            0,
            nil,
            &size
        )
        guard sizeStatus == noErr, size % UInt32(MemoryLayout<T>.stride) == 0 else {
            throw self.error(status: sizeStatus, operation: operation)
        }
        let count = Int(size) / MemoryLayout<T>.stride
        guard count > 0 else { return [] }
        let storage = UnsafeMutableRawPointer.allocate(
            byteCount: Int(size),
            alignment: MemoryLayout<T>.alignment
        )
        defer { storage.deallocate() }
        var mutableSize = size
        let status = AudioObjectGetPropertyData(
            objectID,
            &address,
            0,
            nil,
            &mutableSize,
            storage
        )
        guard status == noErr,
              mutableSize == size,
              mutableSize % UInt32(MemoryLayout<T>.stride) == 0
        else {
            throw self.error(
                status: status == noErr ? kAudioHardwareUnspecifiedError : status,
                operation: "\(operation) without a topology size change"
            )
        }
        let values = storage.assumingMemoryBound(to: T.self)
        return Array(UnsafeBufferPointer(start: values, count: count))
    }

    private static func readInputBufferChannels(
        deviceID: AudioObjectID,
        address: inout AudioObjectPropertyAddress
    ) throws -> [UInt32] {
        var size: UInt32 = 0
        let sizeStatus = AudioObjectGetPropertyDataSize(
            deviceID,
            &address,
            0,
            nil,
            &size
        )
        guard sizeStatus == noErr, size >= MemoryLayout<AudioBufferList>.size else {
            throw self.error(
                status: sizeStatus,
                operation: "read input stream configuration size"
            )
        }

        let storage = UnsafeMutableRawPointer.allocate(
            byteCount: Int(size),
            alignment: MemoryLayout<AudioBufferList>.alignment
        )
        defer { storage.deallocate() }
        var mutableSize = size
        let status = AudioObjectGetPropertyData(
            deviceID,
            &address,
            0,
            nil,
            &mutableSize,
            storage
        )
        guard status == noErr, mutableSize == size else {
            throw self.error(
                status: status == noErr ? kAudioHardwareUnspecifiedError : status,
                operation: "read stable input stream configuration"
            )
        }
        let bufferCount = storage.load(as: UInt32.self)
        let bufferAlignment = MemoryLayout<AudioBuffer>.alignment
        let firstBufferOffset =
            (MemoryLayout<UInt32>.size + bufferAlignment - 1) &
            ~(bufferAlignment - 1)
        let requiredSize =
            firstBufferOffset + Int(bufferCount) * MemoryLayout<AudioBuffer>.stride
        guard bufferCount > 0, requiredSize <= Int(mutableSize) else {
            throw self.error(
                status: kAudioHardwareUnspecifiedError,
                operation: "validate input stream configuration"
            )
        }
        let buffers = UnsafeMutableAudioBufferListPointer(
            storage.assumingMemoryBound(to: AudioBufferList.self)
        )
        return buffers.map(\.mNumberChannels)
    }

    private static func error(
        status: OSStatus,
        operation: String,
        detail: String? = nil
    ) -> NSError {
        let suffix = detail.map { ": \($0)" } ?? " (OSStatus \(status))"
        return NSError(
            domain: NSOSStatusErrorDomain,
            code: Int(status),
            userInfo: [NSLocalizedDescriptionKey: "Failed to \(operation)\(suffix)."]
        )
    }
}

/// Prepared, input-only Core Audio capture.
///
/// `AudioDeviceIOProc` publishes native hardware-cycle PCM into a fixed SPSC
/// ring in C. This Swift wrapper drains that ring away from Core Audio's
/// realtime thread, so resampling, level calculation, logging, and ASR buffer
/// mutation never happen in the device callback.
nonisolated protocol DirectCoreAudioInputControlling: AnyObject, Sendable {
    var deviceID: AudioObjectID { get }
    var sampleRate: Double { get }
    var hardwareBufferFrameSize: UInt32 { get }
    var formatFingerprint: DirectCoreAudioFormatFingerprint { get }
    var isRunning: Bool { get }
    var droppedPacketCount: UInt64 { get }

    func start() throws
    func stop() -> OSStatus
    func markFormatDirty()
    func openPacketGateIfClean() -> Bool
    func invalidate() -> OSStatus
}

private final nonisolated class DirectCoreAudioInput: DirectCoreAudioInputControlling, @unchecked Sendable {
    private struct SendableCaptureHandle: @unchecked Sendable {
        let rawValue: FVCoreAudioCaptureRef
    }

    let deviceID: AudioObjectID
    let sampleRate: Double
    let hardwareBufferFrameSize: UInt32
    let formatFingerprint: DirectCoreAudioFormatFingerprint

    private var capture: FVCoreAudioCaptureRef?
    private var poisonedStopStatus: OSStatus?
    private let packetHandler: DirectCoreAudioPacketHandler
    private let workerQueue = DispatchQueue(
        label: "com.fluidvoice.audio.direct-input-consumer",
        qos: .userInteractive
    )
    private let workerGroup = DispatchGroup()

    init(deviceID: AudioObjectID, packetHandler: @escaping DirectCoreAudioPacketHandler) throws {
        var capture: FVCoreAudioCaptureRef?
        let status = fv_core_audio_capture_create(deviceID, &capture)
        guard status == noErr, let capture else {
            throw Self.error(status: status, operation: "prepare direct Core Audio input")
        }

        self.deviceID = deviceID
        let sampleRate = fv_core_audio_capture_sample_rate(capture)
        let hardwareBufferFrameSize = fv_core_audio_capture_buffer_frame_size(capture)
        var streamID = AudioStreamID(kAudioObjectUnknown)
        var streamFormat = AudioStreamBasicDescription()
        guard fv_core_audio_capture_copy_stream_format(
            capture,
            &streamID,
            &streamFormat
        ) else {
            _ = fv_core_audio_capture_destroy(capture)
            throw Self.error(
                status: kAudioHardwareUnspecifiedError,
                operation: "read prepared direct Core Audio format"
            )
        }
        do {
            self.formatFingerprint = try DirectCoreAudioFormatFingerprint.captured(
                deviceID: deviceID,
                streamID: streamID,
                virtualFormat: streamFormat,
                bufferFrameSize: hardwareBufferFrameSize
            )
        } catch {
            _ = fv_core_audio_capture_destroy(capture)
            throw error
        }
        self.capture = capture
        self.sampleRate = sampleRate
        self.hardwareBufferFrameSize = hardwareBufferFrameSize
        self.packetHandler = packetHandler
    }

    deinit {
        _ = self.invalidate()
    }

    var isRunning: Bool {
        guard let capture else { return false }
        return fv_core_audio_capture_is_running(capture)
    }

    var droppedPacketCount: UInt64 {
        guard let capture else { return 0 }
        return fv_core_audio_capture_dropped_packet_count(capture)
    }

    func start() throws {
        guard let capture else {
            throw Self.error(status: kAudioHardwareBadObjectError, operation: "start direct Core Audio input")
        }
        guard fv_core_audio_capture_is_running(capture) == false else { return }

        fv_core_audio_capture_clear(capture)
        let status = fv_core_audio_capture_start(capture)
        guard status == noErr else {
            throw Self.error(status: status, operation: "start direct Core Audio input")
        }

        let packetHandler = self.packetHandler
        let workerGroup = self.workerGroup
        let workerHandle = SendableCaptureHandle(rawValue: capture)
        workerGroup.enter()
        self.workerQueue.async {
            defer { workerGroup.leave() }
            Self.consumePackets(capture: workerHandle.rawValue, packetHandler: packetHandler)
        }
    }

    func markFormatDirty() {
        guard let capture else { return }
        fv_core_audio_capture_mark_format_dirty(capture)
    }

    func openPacketGateIfClean() -> Bool {
        guard let capture else { return false }
        return fv_core_audio_capture_open_packet_gate_if_clean(capture)
    }

    /// Stops hardware IO and synchronously drains every packet already published
    /// by the realtime callback before returning.
    @discardableResult
    func stop() -> OSStatus {
        if let poisonedStopStatus {
            return poisonedStopStatus
        }
        guard let capture else { return noErr }
        let stopStartedAt = ProcessInfo.processInfo.systemUptime
        let status = fv_core_audio_capture_stop(capture)
        let hardwareStoppedAt = ProcessInfo.processInfo.systemUptime
        fv_core_audio_capture_wake(capture)
        self.workerGroup.wait()
        DebugLogger.shared.debug(
            "STOP_TRACE backend=direct hardwareStopMs=\(Int((hardwareStoppedAt - stopStartedAt) * 1000)) workerDrainMs=\(Int((ProcessInfo.processInfo.systemUptime - hardwareStoppedAt) * 1000))",
            source: "StopTiming"
        )
        if status != noErr {
            self.poisonedStopStatus = status
        }
        return status
    }

    @discardableResult
    func invalidate() -> OSStatus {
        guard let capture else { return self.poisonedStopStatus ?? noErr }
        let stopStatus = self.stop()
        guard stopStatus == noErr else {
            // A failed AudioDeviceStop does not establish that HAL stopped
            // invoking the IOProc. Leak the callback context intentionally
            // rather than freeing memory that Core Audio may still access.
            self.capture = nil
            return stopStatus
        }
        let destroyStatus = fv_core_audio_capture_destroy(capture)
        guard destroyStatus == noErr else {
            self.poisonedStopStatus = destroyStatus
            self.capture = nil
            return destroyStatus
        }
        self.capture = nil
        return noErr
    }

    private nonisolated static func consumePackets(
        capture: FVCoreAudioCaptureRef,
        packetHandler: DirectCoreAudioPacketHandler
    ) {
        while true {
            var packet = FVCoreAudioPacket()
            while fv_core_audio_capture_peek(capture, &packet) {
                if let samples = packet.samples, packet.frameCount > 0 {
                    packetHandler(
                        samples,
                        Int(packet.frameCount),
                        packet.sampleRate,
                        packet.inputHostTime,
                        packet.inputSampleTime
                    )
                }
                fv_core_audio_capture_consume(capture)
            }

            guard fv_core_audio_capture_is_running(capture) else {
                // AudioDeviceStop waits for the IOProc to leave. One final
                // acquire/drain above therefore captures the complete tail.
                return
            }
            _ = fv_core_audio_capture_wait(capture, 100)
        }
    }

    private static func error(status: OSStatus, operation: String) -> NSError {
        NSError(
            domain: NSOSStatusErrorDomain,
            code: Int(status),
            userInfo: [
                NSLocalizedDescriptionKey: "Failed to \(operation) (OSStatus \(status)).",
            ]
        )
    }
}

private final nonisolated class DirectCoreAudioPacketGate: @unchecked Sendable {
    private let lock = NSLock()
    private var acceptingPackets = true

    func withAcceptedPacket(_ body: () -> Void) {
        self.lock.lock()
        guard self.acceptingPackets else {
            self.lock.unlock()
            return
        }
        body()
        self.lock.unlock()
    }

    func retire() {
        self.lock.lock()
        self.acceptingPackets = false
        self.lock.unlock()
    }
}

final nonisolated class DirectCoreAudioLifecycleController: @unchecked Sendable {
    enum Phase: String {
        case empty
        case preparing
        case prepared
        case starting
        case running
        case stopping
        case invalidating
        case failed
        case shutDown
    }

    struct Snapshot: Equatable {
        let phase: Phase
        let generation: UInt64
        let deviceID: AudioObjectID?
        let deviceName: String?
        let sampleRate: Double?
        let bufferFrameSize: UInt32?
        let fingerprint: DirectCoreAudioFormatFingerprint?

        var isPrepared: Bool {
            switch self.phase {
            case .prepared, .starting, .running, .stopping:
                return true
            case .empty, .preparing, .invalidating, .failed, .shutDown:
                return false
            }
        }
    }

    struct StopReport {
        let status: OSStatus
        let droppedPackets: UInt64
        let retainedPreparedCapture: Bool
    }

    struct FormatInvalidation {
        let generation: UInt64
        let deviceID: AudioObjectID
        let reason: String
        let wasRunning: Bool
    }

    private enum LifecycleLogLevel: String {
        case debug = "DEBUG"
        case info = "INFO"
        case warning = "WARN"
    }

    typealias PacketHandler = DirectCoreAudioPacketHandler
    typealias InputFactory = (
        _ deviceID: AudioObjectID,
        _ packetHandler: @escaping PacketHandler
    ) throws -> any DirectCoreAudioInputControlling
    typealias FingerprintReader = (_ deviceID: AudioObjectID) throws
        -> DirectCoreAudioFormatFingerprint

    private struct ListenerRegistration {
        let objectID: AudioObjectID
        var address: AudioObjectPropertyAddress
        let block: AudioObjectPropertyListenerBlock
    }

    private enum ListenerPolicy: Equatable {
        case optional
        case required
        case requiredNotification
    }

    private let lifecycleQueue = DispatchQueue(
        label: "com.fluidvoice.audio.direct-lifecycle",
        qos: .userInitiated
    )
    private let listenerQueue = DispatchQueue(
        label: "com.fluidvoice.audio.direct-format-listeners",
        qos: .userInitiated
    )
    private let snapshotLock = NSLock()
    private let recoveryTimeout: TimeInterval
    private let hardwareOperations: BoundedAudioHardwareQueue
    private let deviceQueries: BoundedAudioHardwareQueue
    private let captureDeviceQueries: BoundedAudioHardwareQueue
    private var shutdownRequested = false
    // A display can change HAL topology without changing the selected input's
    // ID or format. Refresh stopped capture on the next Start, not mid-recording.
    private var hardwareTopologyRevision: UInt64 = 0 // snapshotLock
    private var topologyRecoveryCheckPending = false // snapshotLock
    private var lastStartedTopologyRevision: UInt64 = 0 // lifecycleQueue
    private let stoppedHardwareLock = NSLock()
    private var stoppedHardwareGenerations: Set<UInt64> = []
    private var lastReportedAbnormalStopGeneration: UInt64?
    private var pendingFormatInvalidationGenerations: Set<UInt64> = []
    private var storedSnapshot = Snapshot(
        phase: .empty,
        generation: 0,
        deviceID: nil,
        deviceName: nil,
        sampleRate: nil,
        bufferFrameSize: nil,
        fingerprint: nil
    )

    private let packetHandler: PacketHandler
    private let inputFactory: InputFactory
    private let deviceSnapshotReader: @Sendable (Bool) throws -> DeviceSnapshot
    private let deviceLivenessReader: @Sendable (AudioObjectID) -> Bool?
    private let deviceResolver: @Sendable (DirectCoreAudioDeviceSelection) throws -> AudioDevice.Device?
    private let fingerprintReader: FingerprintReader
    private let onFormatInvalidated: @Sendable (FormatInvalidation) -> Void
    private let installsHardwareListeners: Bool

    // lifecycleQueue-confined state
    private var input: (any DirectCoreAudioInputControlling)?
    private var packetGate: DirectCoreAudioPacketGate?
    private var listenerRegistrations: [ListenerRegistration] = []
    private var generation: UInt64 = 0
    private var isShutDown = false
    private var isPoisoned = false
    private var inputDeviceName: String?
    private struct FailedHardware: Equatable {
        let generation: UInt64
        let deviceID: AudioObjectID
    }

    private var failedHardware: FailedHardware?

    init(
        packetHandler: @escaping PacketHandler,
        inputFactory: @escaping InputFactory = { deviceID, handler in
            try DirectCoreAudioInput(deviceID: deviceID, packetHandler: handler)
        },
        fingerprintReader: @escaping FingerprintReader = {
            try DirectCoreAudioFormatFingerprint.read(deviceID: $0)
        },
        installsHardwareListeners: Bool = true,
        operationTimeout: TimeInterval? = nil,
        deviceSnapshotReader: @escaping @Sendable (Bool) throws -> DeviceSnapshot = DirectCoreAudioLifecycleController.queryDeviceSnapshot,
        deviceLivenessReader: @escaping @Sendable (AudioObjectID) -> Bool? = DirectCoreAudioLifecycleController.readDeviceLiveness,
        deviceResolver: @escaping @Sendable (DirectCoreAudioDeviceSelection) throws -> AudioDevice.Device? = DirectCoreAudioLifecycleController.resolveSelectedDevice,
        onFormatInvalidated: @escaping @Sendable (FormatInvalidation) -> Void
    ) {
        self.recoveryTimeout = operationTimeout ?? 5
        self.hardwareOperations = BoundedAudioHardwareQueue(queue: self.lifecycleQueue, timeout: operationTimeout)
        self.deviceQueries = BoundedAudioHardwareQueue(
            queue: DispatchQueue(label: "com.fluidvoice.audio.device-snapshot", qos: .userInitiated),
            timeout: operationTimeout ?? 5
        )
        self.captureDeviceQueries = BoundedAudioHardwareQueue(
            queue: DispatchQueue(label: "com.fluidvoice.audio.capture-device-snapshot", qos: .userInitiated),
            timeout: operationTimeout
        )
        self.packetHandler = packetHandler
        self.inputFactory = inputFactory
        self.fingerprintReader = fingerprintReader
        self.deviceSnapshotReader = deviceSnapshotReader
        self.deviceLivenessReader = deviceLivenessReader
        self.deviceResolver = deviceResolver
        self.installsHardwareListeners = installsHardwareListeners
        self.onFormatInvalidated = onFormatInvalidated
    }

    deinit {
        let input = self.input
        let gate = self.packetGate
        let registrations = self.listenerRegistrations
        let listenerQueue = self.listenerQueue
        let generation = self.generation
        self.lifecycleQueue.async {
            gate?.retire()
            Self.removeListeners(registrations, queue: listenerQueue)
            if registrations.isEmpty == false {
                listenerQueue.sync {}
                Self.log(
                    "Direct capture listener drain generation=\(generation) " +
                        "count=\(registrations.count) reason=controller_deinit",
                    level: .debug
                )
            }
            _ = input?.invalidate()
        }
    }

    var snapshot: Snapshot {
        var snapshot = self.snapshotLock.withLock { self.storedSnapshot }
        if self.hardwareOperations.isAvailable == false {
            snapshot = Snapshot(
                phase: .failed,
                generation: snapshot.generation,
                deviceID: snapshot.deviceID,
                deviceName: snapshot.deviceName,
                sampleRate: snapshot.sampleRate,
                bufferFrameSize: snapshot.bufferFrameSize,
                fingerprint: snapshot.fingerprint
            )
        }
        return snapshot
    }

    var isRecoveringHardware: Bool { self.hardwareOperations.isAvailable == false }

    func waitForHardwareAvailability() async -> Bool {
        await self.hardwareOperations.waitUntilAvailable(timeout: self.recoveryTimeout)
    }

    func waitForDeviceQueryAvailability() async -> Bool {
        await self.deviceQueries.waitUntilAvailable(timeout: self.recoveryTimeout)
    }

    func waitForPendingHardwareRetirement() async -> Bool {
        await self.hardwareOperations.waitUntilAvailable(timeout: self.recoveryTimeout)
    }

    func cancelPendingStartup() {
        self.hardwareOperations.cancelPendingOperations()
        self.captureDeviceQueries.cancelPendingOperations()
    }

    /// No HAL calls or capture mutations in the device-list notification path.
    /// Multiple events collapse into one fresh setup at the next stopped start.
    func noteHardwareTopologyChanged() {
        let revision = self.snapshotLock.withLock {
            self.hardwareTopologyRevision &+= 1
            return self.hardwareTopologyRevision
        }
        Self.log("Direct capture topology changed revision=\(revision); next stopped start requires fresh input", level: .info)
        self.scheduleFailedHardwareCheck()
    }

    private func scheduleFailedHardwareCheck() {
        let enqueue = self.snapshotLock.withLock {
            guard self.shutdownRequested == false, self.topologyRecoveryCheckPending == false else { return false }
            self.topologyRecoveryCheckPending = true
            return true
        }
        if enqueue {
            // Queue behind native work and its cleanup. A topology callback must
            // never clear failure while that work still owns capture resources.
            // Coalesce bursts here; ordinary capture startup is never delayed.
            self.lifecycleQueue.asyncAfter(deadline: .now() + 0.05) { [weak self] in self?.checkFailedHardwareLocked() }
        }
    }

    private func checkFailedHardwareLocked() {
        let revision = self.snapshotLock.withLock { self.hardwareTopologyRevision }
        guard self.isShutDown == false,
              self.snapshotLock.withLock({ self.shutdownRequested == false }),
              self.isPoisoned, let failedHardware = self.failedHardware
        else {
            self.snapshotLock.withLock { self.topologyRecoveryCheckPending = false }
            return
        }
        Task { [weak self, deviceQueries, deviceLivenessReader] in
            // Unknown, failed, or timed-out queries cannot authorize replacement.
            // Keep HAL queries off both the notification and lifecycle queues.
            let isAlive = try? await deviceQueries.run(recover: { true }) {
                deviceLivenessReader(failedHardware.deviceID)
            }
            self?.lifecycleQueue.async { [weak self] in
                guard let self else { return }
                defer {
                    // An event can arrive even while this completion is being
                    // handled. Release ownership only after applying its result,
                    // then recheck any newer revision instead of losing it.
                    let changedAgain = self.snapshotLock.withLock {
                        self.topologyRecoveryCheckPending = false
                        return revision != self.hardwareTopologyRevision
                    }
                    if changedAgain { self.scheduleFailedHardwareCheck() }
                }
                guard self.isShutDown == false,
                      self.snapshotLock.withLock({ self.shutdownRequested == false && revision == self.hardwareTopologyRevision }),
                      self.failedHardware == failedHardware,
                      self.generation == failedHardware.generation,
                      isAlive == false
                else { return }
                self.recordStoppedHardwareNotification(generation: failedHardware.generation)
                self.handleFormatInvalidationLocked(
                    generation: failedHardware.generation,
                    reason: "device_list_confirmed_stopped"
                )
            }
        }
    }

    struct DeviceSnapshot: Sendable {
        let devices: [AudioDevice.Device]
        let defaultInputUID: String?
    }

    /// Cancellation releases the caller even if HAL discovery is blocked. This
    /// queue is independent of recovery queries and never stops running capture.
    func readCaptureDeviceSnapshot() async throws -> DeviceSnapshot {
        try await self.captureDeviceQueries.run(recover: { true }) {
            let startedAt = ProcessInfo.processInfo.systemUptime
            Self.log("Direct capture startup device query begin", level: .debug)
            let snapshot = try self.deviceSnapshotReader(false)
            Self.log("Direct capture startup device query end elapsedMs=\(Self.elapsedMilliseconds(since: startedAt))", level: .debug)
            return snapshot
        }
    }

    func readDeviceSnapshot(refreshLiveness: Bool = false) async throws -> DeviceSnapshot {
        // Only route recovery uses this bounded queue. Its cancellation cannot
        // interrupt ordinary startup discovery or an already recording input.
        try await self.deviceQueries.run(recover: { true }) {
            try self.deviceSnapshotReader(refreshLiveness)
        }
    }

    private static func queryDeviceSnapshot(refreshLiveness: Bool) -> DeviceSnapshot {
        let devices = refreshLiveness
            ? AudioDevice.listInputDevicesRefreshingLiveness()
            : AudioDevice.listAllDevices()
        return DeviceSnapshot(
            devices: devices,
            defaultInputUID: AudioDevice.getDefaultInputDevice(from: devices)?.uid
        )
    }

    private func performHardwareOperation<Value: Sendable>(
        cancellable: Bool = true,
        timeout: TimeInterval? = nil,
        _ operation: @escaping @Sendable () throws -> Value
    ) async throws -> Value {
        try await self.hardwareOperations.run(cancellable: cancellable, timeout: timeout, recover: { [self] in
            let status = self.invalidateLocked(reason: "interrupted_hardware_operation")
            if self.snapshotLock.withLock({ self.shutdownRequested }) {
                self.isShutDown = true
                self.publishSnapshot(phase: .shutDown, input: nil, fingerprint: nil)
            }
            Self.log("Direct capture interrupted operation drained status=\(status)", level: .info)
            return status == noErr && self.isPoisoned == false
        }) {
            try self.hardwareOperations.checkAvailable()
            return try operation()
        }
    }

    func resolveDevice(
        selection: DirectCoreAudioDeviceSelection,
        reason: String
    ) async throws -> AudioDevice.Device {
        try await self.performHardwareOperation {
            let startedAt = ProcessInfo.processInfo.systemUptime
            let device = try self.deviceResolver(selection)
            guard let device else {
                throw Self.error("No input device is available for \(selection).")
            }
            Self.log(
                "Direct capture device resolved off-main reason=\(reason) " +
                    "device='\(device.name)' id=\(device.id) " +
                    "elapsedMs=\(Self.elapsedMilliseconds(since: startedAt))",
                level: .info
            )
            return device
        }
    }

    private static func resolveSelectedDevice(_ selection: DirectCoreAudioDeviceSelection) -> AudioDevice.Device? {
        switch selection {
        case .systemDefault:
            return AudioDevice.getDefaultInputDevice()
                .flatMap { AudioDevice.isInputDeviceUsable($0) ? $0 : nil }
        case let .preferredUID(uid):
            // Keep fallback in ASRService so it always follows the app's priority.
            guard let device = AudioDevice.getInputDevice(byUID: uid),
                  AudioDevice.isInputDeviceUsable(device)
            else { return nil }
            return device
        }
    }

    func prepare(
        deviceID: AudioObjectID,
        deviceName: String,
        reason: String
    ) async throws -> Snapshot {
        try await self.performHardwareOperation {
            try self.prepareLocked(deviceID: deviceID, deviceName: deviceName, reason: reason)
        }
    }

    func start(
        deviceID: AudioObjectID,
        deviceName: String,
        reason: String
    ) async throws -> Snapshot {
        try await self.performHardwareOperation {
            do {
                guard self.isShutDown == false,
                      self.snapshotLock.withLock({ self.shutdownRequested == false })
                else {
                    throw Self.error("Direct Core Audio lifecycle is shut down.")
                }
                let topologyRevision = self.snapshotLock.withLock { self.hardwareTopologyRevision }
                if let input = self.input, input.isRunning == false,
                   topologyRevision != self.lastStartedTopologyRevision
                {
                    // A prewarm made during device churn can still have a stale
                    // IOProc despite an unchanged fingerprint. Rebuild once on
                    // actual demand, after the user has finished connecting it.
                    let status = self.invalidateLocked(reason: "topology_changed_before_start")
                    guard status == noErr, self.isPoisoned == false else {
                        throw BoundedAudioHardwareQueue.Failure.cleanupFailed
                    }
                }
                var prepared = try self.prepareLocked(
                    deviceID: deviceID,
                    deviceName: deviceName,
                    reason: reason
                )
                guard let input = self.input else {
                    throw Self.error("Direct Core Audio input was not prepared.")
                }

                let validationStartedAt = ProcessInfo.processInfo.systemUptime
                let currentFingerprint = try self.fingerprintReader(deviceID)
                if currentFingerprint != input.formatFingerprint {
                    Self.log(
                        "Direct capture fingerprint changed before start; rebuilding " +
                            "generation=\(prepared.generation) old={\(input.formatFingerprint.logDescription)} " +
                            "new={\(currentFingerprint.logDescription)}",
                        level: .warning
                    )
                    self.invalidateLocked(reason: "pre_start_fingerprint_changed")
                    prepared = try self.prepareLocked(
                        deviceID: deviceID,
                        deviceName: deviceName,
                        reason: "pre_start_fingerprint_changed"
                    )
                }

                guard let validatedInput = self.input else {
                    throw Self.error("Direct Core Audio input disappeared before start.")
                }
                if validatedInput.isRunning {
                    let runningFingerprint = try self.fingerprintReader(deviceID)
                    try self.hardwareOperations.checkAvailable()
                    guard runningFingerprint == validatedInput.formatFingerprint,
                          validatedInput.openPacketGateIfClean()
                    else {
                        throw Self.error(
                            "Direct Core Audio format changed while reusing running input generation " +
                                "\(self.generation)."
                        )
                    }
                    self.publishSnapshot(
                        phase: .running,
                        input: validatedInput,
                        fingerprint: validatedInput.formatFingerprint
                    )
                    // Reusing preview does not refresh its native setup. Keep
                    // the pending revision so the next stopped start rebuilds.
                    Self.log(
                        "Direct capture start reused running input generation=\(self.generation) " +
                            "device='\(deviceName)'",
                        level: .debug
                    )
                    return self.snapshot
                }
                guard topologyRevision == self.snapshotLock.withLock({ self.hardwareTopologyRevision }) else {
                    throw Self.error("Audio hardware changed while preparing the microphone. Retry with fresh capture state.")
                }
                self.publishSnapshot(
                    phase: .starting,
                    input: validatedInput,
                    fingerprint: validatedInput.formatFingerprint
                )
                let startStartedAt = ProcessInfo.processInfo.systemUptime
                Self.log(
                    "Direct capture start begin generation=\(self.generation) " +
                        "device='\(deviceName)' validationMs=" +
                        "\(Self.elapsedMilliseconds(since: validationStartedAt))",
                    level: .info
                )
                try self.hardwareOperations.checkAvailable()
                Self.log("Direct capture native start enter generation=\(self.generation) device=\(deviceID)", level: .info)
                try validatedInput.start()
                Self.log("Direct capture native start return generation=\(self.generation) elapsedMs=\(Self.elapsedMilliseconds(since: startStartedAt))", level: .info)
                try self.hardwareOperations.checkAvailable()
                Self.log("Direct capture post-start validation begin generation=\(self.generation)", level: .debug)
                let fingerprintAfterStart = try self.fingerprintReader(deviceID)
                Self.log("Direct capture post-start validation end generation=\(self.generation)", level: .debug)
                try self.hardwareOperations.checkAvailable()
                guard fingerprintAfterStart == validatedInput.formatFingerprint,
                      validatedInput.openPacketGateIfClean()
                else {
                    throw Self.error(
                        "Direct Core Audio format changed while starting generation " +
                            "\(self.generation)."
                    )
                }
                self.publishSnapshot(
                    phase: .running,
                    input: validatedInput,
                    fingerprint: validatedInput.formatFingerprint
                )
                self.lastStartedTopologyRevision = topologyRevision
                Self.log(
                    "Direct capture start end generation=\(self.generation) " +
                        "elapsedMs=\(Self.elapsedMilliseconds(since: startStartedAt)) " +
                        "fingerprint={\(validatedInput.formatFingerprint.logDescription)}",
                    level: .info
                )
                return self.snapshot
            } catch {
                self.publishSnapshot(
                    phase: .failed,
                    input: self.input,
                    fingerprint: self.input?.formatFingerprint
                )
                self.invalidateLocked(reason: "start_failed")
                throw error
            }
        }
    }

    func stop(retainPrepared: Bool, reason: String, recoveringRoute: Bool = false) async -> StopReport {
        let requestedAt = ProcessInfo.processInfo.systemUptime
        do {
            return try await self.performHardwareOperation(cancellable: false, timeout: recoveringRoute ? self.recoveryTimeout : nil) {
                var trace = OverlayCloseTrace("audio.lifecycleQueue")
                trace.mark("queueWait", since: requestedAt)
                defer { trace.finish() }
                guard let input = self.input else {
                    return StopReport(
                        status: noErr,
                        droppedPackets: 0,
                        retainedPreparedCapture: false
                    )
                }

                let startedAt = ProcessInfo.processInfo.systemUptime
                self.publishSnapshot(
                    phase: .stopping,
                    input: input,
                    fingerprint: input.formatFingerprint
                )
                Self.log(
                    "Direct capture stop begin generation=\(self.generation) " +
                        "reason=\(reason) retainPrepared=\(retainPrepared)",
                    level: .info
                )
                let status = input.stop()
                trace.mark("snapshotAndHardwareStop")
                let droppedPackets = input.droppedPacketCount
                if status != noErr {
                    self.isPoisoned = true
                    _ = self.invalidateLocked(reason: "stop_failed:\(reason)")
                    self.publishSnapshot(
                        phase: .failed,
                        input: nil,
                        fingerprint: nil
                    )
                } else if retainPrepared, self.isShutDown == false {
                    self.publishSnapshot(
                        phase: .prepared,
                        input: input,
                        fingerprint: input.formatFingerprint
                    )
                } else {
                    self.invalidateLocked(reason: reason)
                }
                Self.log(
                    "Direct capture stop end generation=\(self.generation) " +
                        "elapsedMs=\(Self.elapsedMilliseconds(since: startedAt)) " +
                        "status=\(status) droppedPackets=\(droppedPackets) " +
                        "retained=\(retainPrepared && self.input != nil)",
                    level: .info
                )
                trace.mark("postStopState")
                DebugLogger.shared.debug("CLOSE_DETAIL audioContinuationResume uptime=\(ProcessInfo.processInfo.systemUptime)", source: "StopTiming")
                return StopReport(
                    status: status,
                    droppedPackets: droppedPackets,
                    retainedPreparedCapture: retainPrepared && self.input != nil
                )
            }
        } catch {
            Self.log("Direct capture stop interrupted reason=\(reason): \(error.localizedDescription)", level: .warning)
            return StopReport(status: kAudioHardwareUnspecifiedError, droppedPackets: 0, retainedPreparedCapture: false)
        }
    }

    func invalidate(reason: String, recoveringRoute: Bool = false) async {
        _ = try? await self.performHardwareOperation(cancellable: false, timeout: recoveringRoute ? self.recoveryTimeout : nil) {
            self.invalidateLocked(reason: reason)
        }
    }

    func shutdown(reason: String) async {
        self.snapshotLock.withLock { self.shutdownRequested = true }
        _ = try? await self.performHardwareOperation(cancellable: false, timeout: self.recoveryTimeout) {
            guard self.isShutDown == false else { return }
            self.isShutDown = true
            _ = self.invalidateLocked(reason: reason)
            self.publishSnapshot(phase: .shutDown, input: nil, fingerprint: nil)
        }
    }

    private func prepareLocked(
        deviceID: AudioObjectID,
        deviceName: String,
        reason: String
    ) throws -> Snapshot {
        try self.hardwareOperations.checkAvailable()
        guard self.isShutDown == false,
              self.snapshotLock.withLock({ self.shutdownRequested == false })
        else {
            throw Self.error("Direct Core Audio lifecycle is shut down.")
        }
        guard self.isPoisoned == false else {
            throw Self.error(
                "Direct Core Audio lifecycle is poisoned by a failed hardware teardown; restart the app."
            )
        }

        let currentFingerprint = try self.fingerprintReader(deviceID)
        try self.hardwareOperations.checkAvailable()
        if let input = self.input,
           input.deviceID == deviceID,
           input.formatFingerprint == currentFingerprint
        {
            self.inputDeviceName = deviceName
            self.publishSnapshot(
                phase: input.isRunning ? .running : .prepared,
                input: input,
                fingerprint: input.formatFingerprint
            )
            Self.log(
                "Direct capture prepare reuse generation=\(self.generation) " +
                    "reason=\(reason) fingerprint={\(currentFingerprint.logDescription)}",
                level: .debug
            )
            return self.snapshot
        }

        if self.input != nil {
            let invalidationStatus = self.invalidateLocked(
                reason: "prepare_replacement:\(reason)"
            )
            guard invalidationStatus == noErr, self.isPoisoned == false else {
                throw Self.error(
                    "Direct Core Audio lifecycle is poisoned after replacement teardown failed " +
                        "with status \(invalidationStatus); restart the app."
                )
            }
        }

        self.generation &+= 1
        let generation = self.generation
        self.inputDeviceName = deviceName
        self.publishSnapshot(
            phase: .preparing,
            input: nil,
            fingerprint: currentFingerprint,
            deviceID: deviceID
        )
        let startedAt = ProcessInfo.processInfo.systemUptime
        Self.log(
            "Direct capture prepare begin generation=\(generation) " +
                "device='\(deviceName)' reason=\(reason) " +
                "fingerprint={\(currentFingerprint.logDescription)}",
            level: .info
        )

        let gate = DirectCoreAudioPacketGate()
        let downstreamHandler = self.packetHandler
        let hardwareOperations = self.hardwareOperations
        let input: any DirectCoreAudioInputControlling
        do {
            input = try self.inputFactory(deviceID) { samples, frameCount, sampleRate, inputHostTime, inputSampleTime in
                guard hardwareOperations.isAvailable else { return }
                gate.withAcceptedPacket {
                    downstreamHandler(
                        samples,
                        frameCount,
                        sampleRate,
                        inputHostTime,
                        inputSampleTime
                    )
                }
            }
        } catch {
            gate.retire()
            self.publishSnapshot(phase: .failed, input: nil, fingerprint: currentFingerprint)
            throw error
        }
        guard input.formatFingerprint == currentFingerprint else {
            gate.retire()
            _ = input.invalidate()
            throw Self.error(
                "Direct Core Audio format changed while preparing generation \(generation)."
            )
        }

        self.input = input
        self.packetGate = gate
        do {
            try self.hardwareOperations.checkAvailable()
            if self.installsHardwareListeners {
                try self.installFormatListenersLocked(
                    fingerprint: input.formatFingerprint,
                    generation: generation,
                    input: input
                )
            }
            let fingerprintAfterListeners = try self.fingerprintReader(deviceID)
            try self.hardwareOperations.checkAvailable()
            guard fingerprintAfterListeners == input.formatFingerprint else {
                throw Self.error(
                    "Direct Core Audio format changed while installing listeners."
                )
            }
        } catch {
            _ = self.invalidateLocked(reason: "prepare_validation_failed")
            throw error
        }

        self.publishSnapshot(
            phase: .prepared,
            input: input,
            fingerprint: input.formatFingerprint
        )
        Self.log(
            "Direct capture prepare end generation=\(generation) " +
                "elapsedMs=\(Self.elapsedMilliseconds(since: startedAt)) " +
                "fingerprint={\(input.formatFingerprint.logDescription)}",
            level: .info
        )
        return self.snapshot
    }

    @discardableResult
    private func invalidateLocked(
        reason: String,
        allowStoppedHardwareReplacement: Bool = false
    ) -> OSStatus {
        guard self.input != nil || self.listenerRegistrations.isEmpty == false else {
            self.inputDeviceName = nil
            let phase: Phase = self.isShutDown ? .shutDown : (self.isPoisoned ? .failed : .empty)
            self.publishSnapshot(phase: phase, input: nil, fingerprint: nil)
            return noErr
        }

        let startedAt = ProcessInfo.processInfo.systemUptime
        let input = self.input
        self.publishSnapshot(
            phase: .invalidating,
            input: input,
            fingerprint: input?.formatFingerprint
        )
        Self.log(
            "Direct capture invalidate begin generation=\(self.generation) reason=\(reason)",
            level: .info
        )
        self.packetGate?.retire()
        self.packetGate = nil
        let listenerCount = self.listenerRegistrations.count
        Self.removeListeners(self.listenerRegistrations, queue: self.listenerQueue)
        self.listenerRegistrations.removeAll(keepingCapacity: false)
        if listenerCount > 0 {
            let listenerDrainStartedAt = ProcessInfo.processInfo.systemUptime
            // Removal does not guarantee that an already-dispatched listener
            // block has returned. Drain it before the input can destroy the C
            // capture state accessed by markFormatDirty() and isRunning.
            self.listenerQueue.sync {}
            Self.log(
                "Direct capture listener drain generation=\(self.generation) " +
                    "count=\(listenerCount) " +
                    "elapsedMs=\(Self.elapsedMilliseconds(since: listenerDrainStartedAt))",
                level: .debug
            )
        }
        let status = input?.invalidate() ?? noErr
        let stoppedHardwareWasReported =
            self.consumeStoppedHardwareNotification(generation: self.generation)
        let replacementAllowed =
            allowStoppedHardwareReplacement || stoppedHardwareWasReported
        if status != noErr {
            if replacementAllowed {
                Self.log(
                    "Direct capture stale hardware teardown generation=\(self.generation) " +
                        "status=\(status); callback context quarantined, replacement allowed",
                    level: .warning
                )
            } else {
                self.isPoisoned = true
                if let input {
                    self.failedHardware = FailedHardware(generation: self.generation, deviceID: input.deviceID)
                    // Covers removal while listeners were being detached, before
                    // cleanup had published its failure to the hardware queue.
                    self.scheduleFailedHardwareCheck()
                }
                Self.log(
                    "Direct capture teardown failed generation=\(self.generation) " +
                        "status=\(status); lifecycle poisoned and callback context quarantined",
                    level: .warning
                )
            }
        }
        self.input = nil
        self.inputDeviceName = nil
        let finalPhase: Phase =
            self.isShutDown ? .shutDown : (self.isPoisoned ? .failed : .empty)
        self.publishSnapshot(
            phase: finalPhase,
            input: nil,
            fingerprint: nil
        )
        Self.log(
            "Direct capture invalidate end generation=\(self.generation) " +
                "elapsedMs=\(Self.elapsedMilliseconds(since: startedAt)) reason=\(reason)",
            level: .info
        )
        return status
    }

    private func installFormatListenersLocked(
        fingerprint: DirectCoreAudioFormatFingerprint,
        generation: UInt64,
        input: any DirectCoreAudioInputControlling
    ) throws {
        try self.addListenerLocked(
            objectID: AudioObjectID(kAudioObjectSystemObject),
            selector: kAudioHardwarePropertyServiceRestarted,
            scope: kAudioObjectPropertyScopeGlobal,
            name: "audio_service_restarted",
            generation: generation,
            policy: .requiredNotification,
            input: input
        )

        let deviceSelectors: [
            (AudioObjectPropertySelector, AudioObjectPropertyScope, String, ListenerPolicy)
        ] = [
            (kAudioDevicePropertyDeviceIsAlive, kAudioObjectPropertyScopeGlobal, "device_is_alive", .required),
            (kAudioDevicePropertyDeviceHasChanged, kAudioObjectPropertyScopeGlobal, "device_changed", .optional),
            (kAudioDevicePropertyStreams, kAudioObjectPropertyScopeInput, "streams", .required),
            (kAudioDevicePropertyStreamConfiguration, kAudioObjectPropertyScopeInput, "stream_configuration", .required),
            (kAudioDevicePropertyNominalSampleRate, kAudioObjectPropertyScopeGlobal, "nominal_sample_rate", .required),
            (kAudioDevicePropertyBufferFrameSize, kAudioObjectPropertyScopeGlobal, "buffer_frame_size", .required),
            (kAudioDevicePropertyUsesVariableBufferFrameSizes, kAudioObjectPropertyScopeGlobal, "variable_buffer_frame_size", .optional),
            (kAudioDevicePropertyDataSource, kAudioObjectPropertyScopeInput, "data_source", .optional),
            (kAudioDevicePropertyIOStoppedAbnormally, kAudioObjectPropertyScopeGlobal, "io_stopped_abnormally", .requiredNotification),
        ]
        for (selector, scope, name, policy) in deviceSelectors {
            try self.addListenerLocked(
                objectID: fingerprint.deviceID,
                selector: selector,
                scope: scope,
                name: name,
                generation: generation,
                policy: policy,
                input: input
            )
        }

        let streamSelectors: [(AudioObjectPropertySelector, String, ListenerPolicy)] = [
            (kAudioStreamPropertyVirtualFormat, "virtual_format", .required),
            (kAudioStreamPropertyPhysicalFormat, "physical_format", .optional),
            (kAudioStreamPropertyIsActive, "stream_is_active", .required),
        ]
        for (selector, name, policy) in streamSelectors {
            try self.addListenerLocked(
                objectID: fingerprint.streamID,
                selector: selector,
                scope: kAudioObjectPropertyScopeGlobal,
                name: name,
                generation: generation,
                policy: policy,
                input: input
            )
        }
    }

    private func addListenerLocked(
        objectID: AudioObjectID,
        selector: AudioObjectPropertySelector,
        scope: AudioObjectPropertyScope,
        name: String,
        generation: UInt64,
        policy: ListenerPolicy,
        input: any DirectCoreAudioInputControlling
    ) throws {
        var address = AudioObjectPropertyAddress(
            mSelector: selector,
            mScope: scope,
            mElement: kAudioObjectPropertyElementMain
        )
        if policy != .requiredNotification,
           AudioObjectHasProperty(objectID, &address) == false
        {
            if policy == .required {
                throw Self.error(
                    "Required Core Audio listener property is unavailable: \(name)."
                )
            }
            Self.log(
                "Direct capture listener unavailable generation=\(generation) property=\(name)",
                level: .debug
            )
            return
        }

        let block = Self.makeDevicePropertyListener(objectID: objectID) { [weak self, weak input] objectID in
            #if DEBUG
            AudioTopologyDiagnostics.record(
                .callbackBegin,
                owner: .directCoreAudio,
                objectID: objectID,
                selector: selector,
                scope: scope,
                element: kAudioObjectPropertyElementMain,
                queueRole: .dedicatedDelivery,
                generation: generation
            )
            defer { AudioTopologyDiagnostics.record(
                .callbackEnd,
                owner: .directCoreAudio,
                objectID: objectID,
                selector: selector,
                scope: scope,
                element: kAudioObjectPropertyElementMain,
                queueRole: .dedicatedDelivery,
                generation: generation
            ) }
            #endif
            let deviceIsAlive =
                name == "device_is_alive"
                    ? Self.readDeviceLiveness(objectID: objectID)
                    : nil
            let hardwareIsKnownStopped = Self.hardwareIsKnownStopped(
                reason: name, deviceIsAlive: deviceIsAlive
            )
            if name == "device_is_alive" {
                Self.log(
                    "Direct capture liveness notification generation=\(generation) " +
                        "device=\(objectID) " +
                        "alive=\(deviceIsAlive.map(String.init) ?? "unreadable") " +
                        "knownStopped=\(hardwareIsKnownStopped)",
                    level: hardwareIsKnownStopped ? .warning : .info
                )
            }
            self?.handleFormatNotification(
                generation: generation,
                reason: name,
                input: input,
                hardwareIsKnownStopped: hardwareIsKnownStopped
            )
        }
        #if DEBUG
        AudioTopologyDiagnostics.record(
            .listenerAddBegin,
            owner: .directCoreAudio,
            objectID: objectID,
            selector: address.mSelector,
            scope: address.mScope,
            element: address.mElement,
            queueRole: .dedicatedControl,
            phase: .listener,
            generation: generation
        )
        #endif
        let status = AudioObjectAddPropertyListenerBlock(
            objectID,
            &address,
            self.listenerQueue,
            block
        )
        #if DEBUG
        AudioTopologyDiagnostics.record(
            .listenerAddEnd,
            owner: .directCoreAudio,
            objectID: objectID,
            selector: address.mSelector,
            scope: address.mScope,
            element: address.mElement,
            queueRole: .dedicatedControl,
            phase: .listener,
            status: status,
            generation: generation
        )
        #endif
        guard status == noErr else {
            if policy != .optional {
                throw Self.error(
                    "Failed to register required Core Audio listener \(name) " +
                        "(OSStatus \(status))."
                )
            }
            Self.log(
                "Direct capture listener registration failed generation=\(generation) " +
                    "property=\(name) status=\(status)",
                level: .warning
            )
            return
        }
        self.listenerRegistrations.append(
            ListenerRegistration(objectID: objectID, address: address, block: block)
        )
    }

    private func handleFormatNotification(
        generation: UInt64,
        reason: String,
        input: (any DirectCoreAudioInputControlling)?,
        hardwareIsKnownStopped: Bool
    ) {
        let snapshot = self.snapshotLock.withLock { self.storedSnapshot }
        guard generation == snapshot.generation else { return }
        let action = self.stoppedHardwareLock.withLock {
            if hardwareIsKnownStopped { self.stoppedHardwareGenerations.insert(generation) }
            let report = reason != "io_stopped_abnormally" || self.lastReportedAbnormalStopGeneration != generation
            if reason == "io_stopped_abnormally" { self.lastReportedAbnormalStopGeneration = generation }
            let enqueue = self.pendingFormatInvalidationGenerations.insert(generation).inserted
            return (report, enqueue)
        }
        input?.markFormatDirty()
        if hardwareIsKnownStopped {
            self.snapshotLock.withLock {
                // Recheck under the publication lock: a late callback must not
                // interrupt a replacement generation admitted in the meantime.
                if self.storedSnapshot.generation == generation,
                   self.storedSnapshot.phase == .starting || self.storedSnapshot.phase == .preparing
                {
                    self.hardwareOperations.failPendingOperationsAfterDeviceStopped()
                }
            }
        }
        if action.0 {
            self.onFormatInvalidated(FormatInvalidation(
                generation: generation,
                deviceID: input?.deviceID ?? snapshot.deviceID ?? kAudioObjectUnknown,
                reason: reason,
                wasRunning: input?.isRunning ?? false
            ))
        }
        if action.1 {
            self.lifecycleQueue.async { [weak self] in
                guard let self else { return }
                self.handleFormatInvalidationLocked(generation: generation, reason: reason)
                self.stoppedHardwareLock.withLock {
                    _ = self.pendingFormatInvalidationGenerations.remove(generation)
                }
            }
        }
    }

    private func handleFormatInvalidationLocked(generation: UInt64, reason: String) {
        guard generation == self.generation else {
            _ = self.consumeStoppedHardwareNotification(generation: generation)
            return
        }

        let hardwareIsKnownStopped =
            self.consumeStoppedHardwareNotification(generation: generation)
        guard let input = self.input else {
            if hardwareIsKnownStopped {
                let wasPoisoned = self.isPoisoned
                self.isPoisoned = false
                self.failedHardware = nil
                let clearedQueueFailure = self.hardwareOperations.clearFailureAfterSerializedRecovery()
                if wasPoisoned || clearedQueueFailure {
                    let shuttingDown = self.isShutDown || self.snapshotLock.withLock { self.shutdownRequested }
                    self.publishSnapshot(phase: shuttingDown ? .shutDown : .empty, input: nil, fingerprint: nil)
                    Self.log(
                        "Direct capture cleared teardown failure generation=\(generation) " +
                            "after delayed \(reason) notification queueRecovered=\(clearedQueueFailure)",
                        level: .warning
                    )
                }
            }
            return
        }

        let wasRunning = input.isRunning
        Self.log(
            "Direct capture format invalidated generation=\(generation) " +
                "reason=\(reason) wasRunning=\(wasRunning) " +
                "fingerprint={\(input.formatFingerprint.logDescription)}",
            level: .warning
        )
        self.invalidateLocked(
            reason: "format_listener:\(reason)",
            allowStoppedHardwareReplacement: hardwareIsKnownStopped
        )
    }

    /// The block API supplies an address count, unlike the C proc API which
    /// also supplies an object ID. Always use the ID from registration.
    static func makeDevicePropertyListener(
        objectID: AudioObjectID,
        handler: @escaping @Sendable (AudioObjectID) -> Void
    ) -> AudioObjectPropertyListenerBlock {
        { _, _ in handler(objectID) }
    }

    static func hardwareIsKnownStopped(reason: String, deviceIsAlive: Bool?) -> Bool {
        reason == "audio_service_restarted" || reason == "io_stopped_abnormally" ||
            (reason == "device_is_alive" && deviceIsAlive == false)
    }

    private func recordStoppedHardwareNotification(generation: UInt64) {
        self.stoppedHardwareLock.withLock {
            self.stoppedHardwareGenerations.insert(generation)
        }
    }

    private func consumeStoppedHardwareNotification(generation: UInt64) -> Bool {
        self.stoppedHardwareLock.withLock {
            self.stoppedHardwareGenerations.remove(generation) != nil
        }
    }

    private static func readDeviceLiveness(objectID: AudioObjectID) -> Bool? {
        var address = AudioObjectPropertyAddress(
            mSelector: kAudioDevicePropertyDeviceIsAlive,
            mScope: kAudioObjectPropertyScopeGlobal,
            mElement: kAudioObjectPropertyElementMain
        )
        var isAlive: UInt32 = 0
        var size = UInt32(MemoryLayout<UInt32>.size)
        #if DEBUG
        AudioTopologyDiagnostics.record(
            .halQueryBegin,
            owner: .directCoreAudio,
            objectID: objectID,
            selector: address.mSelector,
            scope: address.mScope,
            element: address.mElement,
            queueRole: .dedicatedDelivery,
            phase: .listener
        )
        #endif
        let status = AudioObjectGetPropertyData(
            objectID,
            &address,
            0,
            nil,
            &size,
            &isAlive
        )
        #if DEBUG
        AudioTopologyDiagnostics.record(
            .halQueryEnd,
            owner: .directCoreAudio,
            objectID: objectID,
            selector: address.mSelector,
            scope: address.mScope,
            element: address.mElement,
            queueRole: .dedicatedDelivery,
            phase: .listener,
            status: status
        )
        #endif
        // An object removed from HAL is gone; other unreadable results are
        // unknown and must not authorize replacement after failed teardown.
        if status == kAudioHardwareBadDeviceError || status == kAudioHardwareBadObjectError { return false }
        guard status == noErr, size == UInt32(MemoryLayout<UInt32>.size) else {
            return nil
        }
        return isAlive != 0
    }

    #if DEBUG
    var isTopologyRecoveryCheckPendingForTesting: Bool {
        self.snapshotLock.withLock { self.topologyRecoveryCheckPending }
    }

    func simulateAbnormalStopNotificationForTesting(generation: UInt64) {
        self.handleFormatNotification(
            generation: generation, reason: "io_stopped_abnormally", input: nil, hardwareIsKnownStopped: true
        )
    }

    func simulateStoppedHardwareNotificationForTesting(
        generation: UInt64,
        reason: String
    ) async {
        self.recordStoppedHardwareNotification(generation: generation)
        await withCheckedContinuation { continuation in
            self.lifecycleQueue.async {
                self.handleFormatInvalidationLocked(
                    generation: generation,
                    reason: reason
                )
                continuation.resume()
            }
        }
    }
    #endif

    private func publishSnapshot(
        phase: Phase,
        input: (any DirectCoreAudioInputControlling)?,
        fingerprint: DirectCoreAudioFormatFingerprint?,
        deviceID: AudioObjectID? = nil
    ) {
        let snapshot = Snapshot(
            phase: phase,
            generation: self.generation,
            deviceID: input?.deviceID ?? deviceID,
            deviceName: self.inputDeviceName,
            sampleRate: input?.sampleRate ?? fingerprint?.virtualFormat.sampleRate,
            bufferFrameSize: input?.hardwareBufferFrameSize ?? fingerprint?.bufferFrameSize,
            fingerprint: fingerprint
        )
        self.snapshotLock.lock()
        self.storedSnapshot = snapshot
        self.snapshotLock.unlock()
    }

    private static func removeListeners(
        _ registrations: [ListenerRegistration],
        queue: DispatchQueue
    ) {
        for registration in registrations {
            var address = registration.address
            #if DEBUG
            AudioTopologyDiagnostics.record(
                .listenerRemoveBegin,
                owner: .directCoreAudio,
                objectID: registration.objectID,
                selector: address.mSelector,
                scope: address.mScope,
                element: address.mElement,
                queueRole: .dedicatedControl,
                phase: .listener
            )
            #endif
            let status = AudioObjectRemovePropertyListenerBlock(
                registration.objectID,
                &address,
                queue,
                registration.block
            )
            #if DEBUG
            AudioTopologyDiagnostics.record(
                .listenerRemoveEnd,
                owner: .directCoreAudio,
                objectID: registration.objectID,
                selector: address.mSelector,
                scope: address.mScope,
                element: address.mElement,
                queueRole: .dedicatedControl,
                phase: .listener,
                status: status
            )
            #endif
            if status != noErr, status != kAudioHardwareBadObjectError {
                Self.log(
                    "Direct capture listener removal failed object=\(registration.objectID) " +
                        "selector=\(address.mSelector) status=\(status)",
                    level: .warning
                )
            }
        }
    }

    private static func log(_ message: String, level: LifecycleLogLevel) {
        let uptime = ProcessInfo.processInfo.systemUptime
        let message = "t=\(String(format: "%.6f", uptime)) \(message)"
        switch level {
        case .debug:
            DebugLogger.shared.debug(message, source: "DirectCoreAudioLifecycle")
        case .info:
            DebugLogger.shared.info(message, source: "DirectCoreAudioLifecycle")
        case .warning:
            DebugLogger.shared.warning(message, source: "DirectCoreAudioLifecycle")
        }
    }

    private static func elapsedMilliseconds(since startedAt: TimeInterval) -> Int {
        Int(((ProcessInfo.processInfo.systemUptime - startedAt) * 1000).rounded())
    }

    private static func error(_ message: String) -> NSError {
        NSError(
            domain: "DirectCoreAudioLifecycle",
            code: -1,
            userInfo: [NSLocalizedDescriptionKey: message]
        )
    }
}