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

feat(meeting): Phase 1 - standalone VPIO microphone capture actor

Shreeraman A Kf52c92f477d5
diff --git a/Fluid.xcodeproj/project.pbxproj b/Fluid.xcodeproj/project.pbxproj
index 8544115b..5e6c82bf 100644
--- a/Fluid.xcodeproj/project.pbxproj
+++ b/Fluid.xcodeproj/project.pbxproj
@@ -38,6 +38,7 @@
E5EC00000000000000000052 /* VoiceProcessingSpeechDuckingTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = E5EC00000000000000000051 /* VoiceProcessingSpeechDuckingTests.swift */; };
E5EC00000000000000000062 /* VoiceProcessingAsrQualityTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = E5EC00000000000000000061 /* VoiceProcessingAsrQualityTests.swift */; };
E5EC00000000000000000072 /* ClockDomainProbeTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = E5EC00000000000000000071 /* ClockDomainProbeTests.swift */; };
+ E5EC00000000000000000082 /* MeetingMicrophoneCaptureTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = E5EC00000000000000000081 /* MeetingMicrophoneCaptureTests.swift */; };
A6E2246FA3744C7B3E2DB91C /* MeetingLiveTranscriptionTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 355C1248D5386D1F815EB7D7 /* MeetingLiveTranscriptionTests.swift */; };
2952403C87FFDE41C1BC85D5 /* MeetingLiveReplayTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 7BE63EB94BB280F38F5CB028 /* MeetingLiveReplayTests.swift */; };
C0DE63600000000000000002 /* AudioEngineRetirementDrainTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = C0DE63600000000000000001 /* AudioEngineRetirementDrainTests.swift */; };
@@ -102,6 +103,7 @@
E5EC00000000000000000051 /* VoiceProcessingSpeechDuckingTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = VoiceProcessingSpeechDuckingTests.swift; sourceTree = "<group>"; };
E5EC00000000000000000061 /* VoiceProcessingAsrQualityTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = VoiceProcessingAsrQualityTests.swift; sourceTree = "<group>"; };
E5EC00000000000000000071 /* ClockDomainProbeTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ClockDomainProbeTests.swift; sourceTree = "<group>"; };
+ E5EC00000000000000000081 /* MeetingMicrophoneCaptureTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MeetingMicrophoneCaptureTests.swift; sourceTree = "<group>"; };
355C1248D5386D1F815EB7D7 /* MeetingLiveTranscriptionTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MeetingLiveTranscriptionTests.swift; sourceTree = "<group>"; };
7BE63EB94BB280F38F5CB028 /* MeetingLiveReplayTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MeetingLiveReplayTests.swift; sourceTree = "<group>"; };
C0DE63600000000000000001 /* AudioEngineRetirementDrainTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = AudioEngineRetirementDrainTests.swift; sourceTree = "<group>"; };
@@ -214,6 +216,7 @@
E5EC00000000000000000051 /* VoiceProcessingSpeechDuckingTests.swift */,
E5EC00000000000000000061 /* VoiceProcessingAsrQualityTests.swift */,
E5EC00000000000000000071 /* ClockDomainProbeTests.swift */,
+ E5EC00000000000000000081 /* MeetingMicrophoneCaptureTests.swift */,
355C1248D5386D1F815EB7D7 /* MeetingLiveTranscriptionTests.swift */,
7BE63EB94BB280F38F5CB028 /* MeetingLiveReplayTests.swift */,
C0DE63600000000000000001 /* AudioEngineRetirementDrainTests.swift */,
@@ -411,6 +414,7 @@
E5EC00000000000000000052 /* VoiceProcessingSpeechDuckingTests.swift in Sources */,
E5EC00000000000000000062 /* VoiceProcessingAsrQualityTests.swift in Sources */,
E5EC00000000000000000072 /* ClockDomainProbeTests.swift in Sources */,
+ E5EC00000000000000000082 /* MeetingMicrophoneCaptureTests.swift in Sources */,
A6E2246FA3744C7B3E2DB91C /* MeetingLiveTranscriptionTests.swift in Sources */,
2952403C87FFDE41C1BC85D5 /* MeetingLiveReplayTests.swift in Sources */,
C0DE63600000000000000002 /* AudioEngineRetirementDrainTests.swift in Sources */,
diff --git a/MIC_CAPTURE_MIGRATION_PLAN.md b/MIC_CAPTURE_MIGRATION_PLAN.md
index 143c8961..4b27e1e8 100644
--- a/MIC_CAPTURE_MIGRATION_PLAN.md
+++ b/MIC_CAPTURE_MIGRATION_PLAN.md
@@ -137,12 +137,30 @@ linear model in §8 is not needed.** Residual std 6.9 ms is arrival jitter, conf
arrival deltas would have been the wrong instrument. Caveats: one machine, and the probe needs an
unlocked display in a foreground session (`SCShareableContent` reports zero displays otherwise).
-**Phase 1 — `MeetingMicrophoneCapture`, standalone.** *Gate*, over 10 minutes on the built-in mic
-**and** one Bluetooth device: valid `hostTime` on ≥99% of buffers; output Float32 LPCM (else the
-writer's telemetry silently dies, `MeetingAudioChunkWriter.swift:499-505`); buffers accepted by
-`MeetingLiveSampleCopy.copy` and by the writer with zero unexpected rotations
-(`MeetingAudioChunkWriter.swift:177-193`); read-back device equals requested, or §6.2/§6.3 fires;
-binding order recorded.
+**Phase 1 — `MeetingMicrophoneCapture`, standalone. DONE, 2026-08-15.** Formal gate passed on the
+built-in mic, 8 minutes: 4800 buffers, **100%** valid `hostTime`, 48 kHz mono Float32 delivered,
+8 chunks at exact 60 s cadence, zero discontinuities / backpressure / live-copy rejections, device
+bound and read back verified, non-silence confirmed. Measured findings, each of which changed the
+design:
+
+- **Binding and read-back live on element 1.** `kAudioOutputUnitProperty_CurrentDevice` on element 0
+ addresses the I/O unit's *render* side — read-back returned the AirPods output (85) against a
+ requested built-in mic (78). Element 0 would also have *moved the AEC reference*.
+- **The tap must be installed before `start()`.** A tap added to an unconnected input node after the
+ active graph is built sits on an inactive node: measured as 10 minutes of zero callbacks with all
+ other telemetry healthy. Post-start format renegotiation is handled by reinstalling the tap.
+- **VPIO delivers no input when its render route is Bluetooth.** AirPods as output: zero callbacks;
+ speakers: perfect stream, same code and mic. §3.2 (VPIO only on speaker routes) is therefore
+ enforced by the hardware, not just chosen — and the Bluetooth-mic leg resolves to "structurally
+ unsupported; such sessions use the SCStream path".
+- The §6.2 escape hatch fired correctly in production (`defaultMatchesRequested` when the AirPods
+ bind failed), and `AVCaptureDevice.uniqueID` **equals** the CoreAudio UID for Bluetooth devices
+ (`EC-46-54-41-33-11:input`) — the name-collision mapping problem largely retires.
+- VPIO exposes a **9-channel** input format on the built-in mic; explicit downmix (never converter
+ channel mapping) handled it.
+- Open tuning note for Phase 2: the PTS clock's 1-frame anchor-correction tolerance trips on ~97% of
+ buffers (device-clock vs mach jitter); widen it — corrections are currently telemetry noise, though
+ emitted PTS stayed monotonic and the writer accepted everything.
**Phase 2 — timeline.** *Gate:* drift within Phase 0's bound over 30 minutes. **Absolute offset cannot
be measured with an acoustic click** — AEC removes it, so a failed correlation would mean cancellation
diff --git a/Sources/Fluid/Services/Meeting/MeetingMicrophoneCapture.swift b/Sources/Fluid/Services/Meeting/MeetingMicrophoneCapture.swift
new file mode 100644
index 00000000..37360724
--- /dev/null
+++ b/Sources/Fluid/Services/Meeting/MeetingMicrophoneCapture.swift
@@ -0,0 +1,912 @@
+import Accelerate
+import AudioToolbox
+@preconcurrency import AVFoundation
+import CoreAudio
+import CoreMedia
+import Foundation
+import os
+
+// MARK: - PTS clock
+
+/// Anchor-and-count acquisition PTS: per-buffer `hostTime` conversion rounds ±½ tick against exact
+/// durations, firing the writer's zero-tolerance backwards check on rounding alone. A valid
+/// `hostTime` only corrects the anchor when it diverges by more than one frame.
+nonisolated struct MeetingMicrophonePTSClock {
+ enum Outcome: Equatable {
+ /// `resynced` is true when this valid stamp follows a post-cap dropped run.
+ case emitted(pts: CMTime, synthesized: Bool, anchorCorrected: Bool, resynced: Bool)
+ /// Cap exceeded: don't emit — the writer must see the gap, not a flawless silent track.
+ case droppedPostCap
+ }
+
+ /// Deliberately equal to the writer's 0.5 s gap threshold (`MeetingAudioChunkWriter.swift:181`).
+ static let synthesisCapSeconds: Double = 0.5
+
+ static let timescale: CMTimeScale = 48_000
+
+ private let sampleRate: Double
+ private let timebase: mach_timebase_info_data_t
+
+ private var anchorHostSeconds: Double?
+ private var anchorPTS: CMTime = .zero
+ private var framesSinceAnchor: Int64 = 0
+ /// Integer frames, not summed seconds — repeated `Double` addition drifts the cap boundary.
+ private var synthesizedRunFrames: Int64 = 0
+ private var isDroppingInvalidRun = false
+
+ init(sampleRate: Double = Double(Self.timescale), timebase: mach_timebase_info_data_t = Self.machTimebase()) {
+ self.sampleRate = sampleRate
+ self.timebase = timebase
+ }
+
+ private static func machTimebase() -> mach_timebase_info_data_t {
+ var info = mach_timebase_info_data_t()
+ mach_timebase_info(&info)
+ return info
+ }
+
+ private func seconds(hostTime: UInt64) -> Double {
+ guard self.timebase.denom > 0 else { return Double(hostTime) / 1_000_000_000 }
+ return Double(hostTime) * Double(self.timebase.numer) / Double(self.timebase.denom) / 1_000_000_000
+ }
+
+ private func currentPTS() -> CMTime {
+ CMTimeAdd(self.anchorPTS, CMTime(value: self.framesSinceAnchor, timescale: Self.timescale))
+ }
+
+ private mutating func resetAnchor(hostSeconds: Double) {
+ self.anchorHostSeconds = hostSeconds
+ self.anchorPTS = CMTime(seconds: hostSeconds, preferredTimescale: Self.timescale)
+ self.framesSinceAnchor = 0
+ }
+
+ /// `nil` iff `isHostTimeValid` is false; 0 is a legitimate mach tick, not a sentinel.
+ mutating func stamp(hostTime: UInt64?, frameCount: Int) -> Outcome {
+ guard let hostTime else {
+ return self.stampInvalid(frameCount: frameCount)
+ }
+ return self.stampValid(hostTime: hostTime, frameCount: frameCount)
+ }
+
+ private mutating func stampInvalid(frameCount: Int) -> Outcome {
+ // No anchor yet: a zero anchor would park the track at epoch 0 vs SCStream's mach stamps.
+ guard self.anchorHostSeconds != nil else {
+ return .droppedPostCap
+ }
+ if self.isDroppingInvalidRun {
+ return .droppedPostCap
+ }
+ let pts = self.currentPTS()
+ self.framesSinceAnchor += Int64(frameCount)
+ self.synthesizedRunFrames += Int64(frameCount)
+ if Double(self.synthesizedRunFrames) / self.sampleRate > Self.synthesisCapSeconds {
+ self.isDroppingInvalidRun = true
+ return .droppedPostCap
+ }
+ return .emitted(pts: pts, synthesized: true, anchorCorrected: false, resynced: false)
+ }
+
+ private mutating func stampValid(hostTime: UInt64, frameCount: Int) -> Outcome {
+ let actualSeconds = self.seconds(hostTime: hostTime)
+ let wasDropping = self.isDroppingInvalidRun
+ self.isDroppingInvalidRun = false
+ self.synthesizedRunFrames = 0
+
+ if self.anchorHostSeconds == nil || wasDropping {
+ self.resetAnchor(hostSeconds: actualSeconds)
+ let pts = self.currentPTS()
+ self.framesSinceAnchor += Int64(frameCount)
+ return .emitted(pts: pts, synthesized: false, anchorCorrected: wasDropping, resynced: wasDropping)
+ }
+
+ let expectedSeconds = self.anchorHostSeconds! + Double(self.framesSinceAnchor) / self.sampleRate
+ let divergence = actualSeconds - expectedSeconds
+ let pts = self.currentPTS()
+ self.framesSinceAnchor += Int64(frameCount)
+
+ var corrected = false
+ if abs(divergence) > 1.0 / self.sampleRate {
+ self.anchorHostSeconds = actualSeconds - Double(self.framesSinceAnchor) / self.sampleRate
+ corrected = true
+ }
+ return .emitted(pts: pts, synthesized: false, anchorCorrected: corrected, resynced: false)
+ }
+}
+
+// MARK: - CMSampleBuffer synthesis (free function, no AVAudioEngine dependency)
+
+/// Owns a fresh copy of the bytes — never wraps the source's storage — because `writer.enqueue`
+/// consumes asynchronously and the sample outlives the tap callback.
+nonisolated func meetingMicrophoneSynthesizeSampleBuffer(
+ from buffer: AVAudioPCMBuffer,
+ presentationTime: CMTime
+) -> CMSampleBuffer? {
+ guard buffer.frameLength > 0, let channelData = buffer.floatChannelData else { return nil }
+
+ var asbd = buffer.format.streamDescription.pointee
+ var formatDescription: CMAudioFormatDescription?
+ let formatStatus = CMAudioFormatDescriptionCreate(
+ allocator: kCFAllocatorDefault,
+ asbd: &asbd,
+ layoutSize: 0,
+ layout: nil,
+ magicCookieSize: 0,
+ magicCookie: nil,
+ extensions: nil,
+ formatDescriptionOut: &formatDescription
+ )
+ guard formatStatus == noErr, let formatDescription else { return nil }
+
+ let frameCount = Int(buffer.frameLength)
+ let byteCount = frameCount * MemoryLayout<Float>.size
+
+ var blockBuffer: CMBlockBuffer?
+ let blockStatus = CMBlockBufferCreateWithMemoryBlock(
+ allocator: kCFAllocatorDefault,
+ memoryBlock: nil,
+ blockLength: byteCount,
+ blockAllocator: kCFAllocatorDefault,
+ customBlockSource: nil,
+ offsetToData: 0,
+ dataLength: byteCount,
+ flags: kCMBlockBufferAssureMemoryNowFlag,
+ blockBufferOut: &blockBuffer
+ )
+ guard blockStatus == noErr, let blockBuffer else { return nil }
+
+ let copyStatus = CMBlockBufferReplaceDataBytes(
+ with: channelData[0],
+ blockBuffer: blockBuffer,
+ offsetIntoDestination: 0,
+ dataLength: byteCount
+ )
+ guard copyStatus == noErr else { return nil }
+
+ var timing = CMSampleTimingInfo(
+ duration: CMTime(value: 1, timescale: CMTimeScale(buffer.format.sampleRate.rounded())),
+ presentationTimeStamp: presentationTime,
+ decodeTimeStamp: .invalid
+ )
+
+ var sampleBuffer: CMSampleBuffer?
+ let sampleStatus = CMSampleBufferCreate(
+ allocator: kCFAllocatorDefault,
+ dataBuffer: blockBuffer,
+ dataReady: true,
+ makeDataReadyCallback: nil,
+ refcon: nil,
+ formatDescription: formatDescription,
+ sampleCount: frameCount,
+ sampleTimingEntryCount: 1,
+ sampleTimingArray: &timing,
+ sampleSizeEntryCount: 0,
+ sampleSizeArray: nil,
+ sampleBufferOut: &sampleBuffer
+ )
+ guard sampleStatus == noErr else { return nil }
+ return sampleBuffer
+}
+
+// MARK: - Binding
+
+/// Verified outcome of binding the AUHAL input unit to a specific CoreAudio device (plan §6).
+nonisolated enum MeetingMicrophoneBindingOutcome: Equatable, Sendable {
+ case boundVerified(AudioObjectID)
+ /// Bind failed but the default input already IS the requested device (Bluetooth/aggregate).
+ case defaultMatchesRequested
+ case unavailable(reason: String)
+}
+
+extension MeetingMicrophoneBindingOutcome: Codable {
+ private enum CodingKeys: String, CodingKey { case kind, deviceID, reason }
+ private enum Kind: String, Codable { case boundVerified, defaultMatchesRequested, unavailable }
+
+ init(from decoder: Decoder) throws {
+ let container = try decoder.container(keyedBy: CodingKeys.self)
+ switch try container.decode(Kind.self, forKey: .kind) {
+ case .boundVerified:
+ self = .boundVerified(try container.decode(AudioObjectID.self, forKey: .deviceID))
+ case .defaultMatchesRequested:
+ self = .defaultMatchesRequested
+ case .unavailable:
+ self = .unavailable(reason: try container.decode(String.self, forKey: .reason))
+ }
+ }
+
+ func encode(to encoder: Encoder) throws {
+ var container = encoder.container(keyedBy: CodingKeys.self)
+ switch self {
+ case let .boundVerified(deviceID):
+ try container.encode(Kind.boundVerified, forKey: .kind)
+ try container.encode(deviceID, forKey: .deviceID)
+ case .defaultMatchesRequested:
+ try container.encode(Kind.defaultMatchesRequested, forKey: .kind)
+ case let .unavailable(reason):
+ try container.encode(Kind.unavailable, forKey: .kind)
+ try container.encode(reason, forKey: .reason)
+ }
+ }
+}
+
+/// Pure decision table, unit-testable headless.
+nonisolated enum MeetingMicrophoneBindDecision {
+ static func outcome(
+ bindStatus: OSStatus,
+ readBackDeviceID: AudioObjectID?,
+ requestedDeviceID: AudioObjectID,
+ defaultInputUID: String?,
+ requestedUID: String
+ ) -> MeetingMicrophoneBindingOutcome {
+ if bindStatus == noErr, let readBackDeviceID, readBackDeviceID == requestedDeviceID {
+ return .boundVerified(readBackDeviceID)
+ }
+ // VP-enable can replace the I/O unit; only post-start read-back proves the binding.
+ if !requestedUID.isEmpty, defaultInputUID == requestedUID {
+ return .defaultMatchesRequested
+ }
+ if let readBackDeviceID, readBackDeviceID != requestedDeviceID {
+ return .unavailable(reason: "Bound device \(readBackDeviceID) does not match requested device \(requestedDeviceID).")
+ }
+ if bindStatus == -10_851 {
+ return .unavailable(reason: "Binding failed for an aggregate/Bluetooth-style device (OSStatus -10851).")
+ }
+ return .unavailable(reason: "Could not verify device binding (bindStatus=\(bindStatus)).")
+ }
+}
+
+// MARK: - Settled configuration
+
+/// What the session actually got, not what it asked for; `Codable` for §7 provenance at rest.
+nonisolated struct MeetingMicrophoneSettledConfig: Codable, Equatable, Sendable {
+ var requestedMicrophone: MeetingMicrophoneIdentity
+ var bindingOutcome: MeetingMicrophoneBindingOutcome
+ /// TODO(probe): hard-code the measured winner; the alternate order is probe-only, never shipped.
+ var bindingOrder: String
+ var settledInputDeviceUID: String?
+ var settledOutputDeviceUID: String?
+ var sourceSampleRate: Double
+ var sourceChannelCount: Int
+ var voiceProcessingEnabled: Bool
+ /// Mono is a recorded decision: SCStream's config is stereo but its mic output observed mono.
+ var outputChannelDecision: String
+}
+
+// MARK: - Capture events
+
+nonisolated enum MeetingMicrophoneCaptureEvent: Sendable {
+ case configurationChanged
+ case defaultInputChanged
+ case overload
+ case engineStopped
+}
+
+nonisolated enum MeetingMicrophoneCaptureError: Error, Sendable {
+ case alreadyStarted
+}
+
+// MARK: - Stats
+
+/// Lock-guarded, never actor-isolated: the audio thread needs priority donation.
+final class MeetingMicrophoneCaptureStats: @unchecked Sendable {
+ struct Snapshot: Sendable, Equatable {
+ var buffersEmitted = 0
+ var validHostTimeCount = 0
+ var synthesizedCount = 0
+ var anchorCorrectionCount = 0
+ var resyncCount = 0
+ var droppedPostCapCount = 0
+ var conversionFailures = 0
+ var sequenceContinuityViolations = 0
+ var overloadCount = 0
+ var configurationChangeEvents = 0
+ var defaultInputChangeEvents = 0
+ var tapCallbackMaxDurationSeconds: Double = 0
+ var tapCallbackP99DurationSeconds: Double = 0
+
+ /// The Phase 1 gate's headline number: ≥99% valid hostTime over the run.
+ var validHostTimeFraction: Double {
+ let total = self.validHostTimeCount + self.synthesizedCount
+ guard total > 0 else { return 1 }
+ return Double(self.validHostTimeCount) / Double(total)
+ }
+ }
+
+ private struct State {
+ var snapshot = Snapshot()
+ var callbackDurations: [Double] = []
+ }
+
+ private static let maxTrackedDurations = 4_096
+
+ private let lock = OSAllocatedUnfairLock(initialState: State())
+
+ func mutate(_ body: (inout Snapshot) -> Void) {
+ self.lock.withLock { state in body(&state.snapshot) }
+ }
+
+ func recordCallbackDuration(_ seconds: Double) {
+ self.lock.withLock { state in
+ state.snapshot.tapCallbackMaxDurationSeconds = max(state.snapshot.tapCallbackMaxDurationSeconds, seconds)
+ state.callbackDurations.append(seconds)
+ if state.callbackDurations.count > Self.maxTrackedDurations {
+ state.callbackDurations.removeFirst(state.callbackDurations.count - Self.maxTrackedDurations)
+ }
+ }
+ }
+
+ func snapshot() -> Snapshot {
+ self.lock.withLock { state in
+ var snapshot = state.snapshot
+ if !state.callbackDurations.isEmpty {
+ let sorted = state.callbackDurations.sorted()
+ let index = min(sorted.count - 1, Int(Double(sorted.count) * 0.99))
+ snapshot.tapCallbackP99DurationSeconds = sorted[index]
+ }
+ return snapshot
+ }
+ }
+}
+
+/// Invalidated on `stop()` so an in-flight tap callback no-ops instead of touching torn-down state.
+private final class MeetingMicrophoneGenerationBox: @unchecked Sendable {
+ private let lock = OSAllocatedUnfairLock<UInt64>(initialState: 0)
+
+ @discardableResult
+ func advance() -> UInt64 {
+ self.lock.withLock { generation in
+ generation += 1
+ return generation
+ }
+ }
+
+ func isCurrent(_ generation: UInt64) -> Bool {
+ self.lock.withLock { $0 == generation }
+ }
+}
+
+// MARK: - Tap state (audio thread only, never hops to the actor)
+
+private final class MeetingMicrophoneTapState: @unchecked Sendable {
+ /// Tap delivers ~10.7 ms buffers; emitting each would 10x the writer's tuned 24-slot budget.
+ private static let accumulationFrameThreshold = 4_800 // 100 ms @ 48 kHz
+
+ private let statsBox: MeetingMicrophoneCaptureStats
+ private let canonicalFormat: AVAudioFormat
+ private let onSample: @Sendable (CMSampleBuffer) -> Void
+
+ private var clock = MeetingMicrophonePTSClock()
+ private var converter: AVAudioConverter?
+ private var converterSourceFormat: AVAudioFormat?
+ private var accumulated: [Float] = []
+ private var windowHostTime: UInt64?
+ private var windowHostTimeValid = false
+ private var lastExpectedSampleTime: AVAudioFramePosition?
+
+ init(
+ statsBox: MeetingMicrophoneCaptureStats,
+ canonicalFormat: AVAudioFormat,
+ onSample: @escaping @Sendable (CMSampleBuffer) -> Void
+ ) {
+ self.statsBox = statsBox
+ self.canonicalFormat = canonicalFormat
+ self.onSample = onSample
+ }
+
+ func handle(buffer: AVAudioPCMBuffer, time: AVAudioTime) {
+ let start = DispatchTime.now()
+ defer { self.statsBox.recordCallbackDuration(Double(DispatchTime.now().uptimeNanoseconds - start.uptimeNanoseconds) / 1_000_000_000) }
+
+ self.checkSequenceContinuity(time: time, frameCount: Int(buffer.frameLength))
+
+ let converted = self.convertToMono(buffer)
+ guard let mono = converted, !mono.isEmpty else {
+ if converted == nil { self.statsBox.mutate { $0.conversionFailures += 1 } }
+ return
+ }
+
+ if self.accumulated.isEmpty {
+ self.windowHostTimeValid = time.isHostTimeValid
+ self.windowHostTime = time.isHostTimeValid ? time.hostTime : nil
+ }
+ self.accumulated.append(contentsOf: mono)
+
+ if self.accumulated.count >= Self.accumulationFrameThreshold {
+ self.flush()
+ }
+ }
+
+ private func flush() {
+ let frameCount = self.accumulated.count
+ let outcome = self.clock.stamp(hostTime: self.windowHostTimeValid ? self.windowHostTime : nil, frameCount: frameCount)
+ let samples = self.accumulated
+ self.accumulated.removeAll(keepingCapacity: true)
+ self.windowHostTime = nil
+ self.windowHostTimeValid = false
+
+ guard case let .emitted(pts, synthesized, anchorCorrected, resynced) = outcome else {
+ self.statsBox.mutate { $0.droppedPostCapCount += 1 }
+ return
+ }
+
+ guard let pcmBuffer = AVAudioPCMBuffer(pcmFormat: self.canonicalFormat, frameCapacity: AVAudioFrameCount(frameCount)) else {
+ self.statsBox.mutate { $0.conversionFailures += 1 }
+ return
+ }
+ pcmBuffer.frameLength = AVAudioFrameCount(frameCount)
+ samples.withUnsafeBufferPointer { source in
+ pcmBuffer.floatChannelData?[0].update(from: source.baseAddress!, count: frameCount)
+ }
+
+ guard let sampleBuffer = meetingMicrophoneSynthesizeSampleBuffer(from: pcmBuffer, presentationTime: pts) else {
+ self.statsBox.mutate { $0.conversionFailures += 1 }
+ return
+ }
+
+ self.statsBox.mutate { stats in
+ stats.buffersEmitted += 1
+ if synthesized { stats.synthesizedCount += 1 } else { stats.validHostTimeCount += 1 }
+ if anchorCorrected { stats.anchorCorrectionCount += 1 }
+ if resynced { stats.resyncCount += 1 }
+ }
+ self.onSample(sampleBuffer)
+ }
+
+ /// Resample first, then downmix explicitly — converter channel mapping may drop, not mix.
+ private func convertToMono(_ buffer: AVAudioPCMBuffer) -> [Float]? {
+ let sourceFormat = buffer.format
+ guard sourceFormat.sampleRate > 0, sourceFormat.channelCount > 0 else { return nil }
+
+ if sourceFormat.sampleRate == self.canonicalFormat.sampleRate, sourceFormat.commonFormat == .pcmFormatFloat32 {
+ return Self.downmixToMono(buffer)
+ }
+
+ if self.converter == nil || self.converterSourceFormat != sourceFormat {
+ guard let intermediateFormat = AVAudioFormat(
+ commonFormat: .pcmFormatFloat32,
+ sampleRate: self.canonicalFormat.sampleRate,
+ channels: sourceFormat.channelCount,
+ interleaved: false
+ ), let converter = AVAudioConverter(from: sourceFormat, to: intermediateFormat) else {
+ return nil
+ }
+ self.converter = converter
+ self.converterSourceFormat = sourceFormat
+ }
+ guard let converter = self.converter else { return nil }
+
+ let ratio = self.canonicalFormat.sampleRate / sourceFormat.sampleRate
+ let estimatedFrames = AVAudioFrameCount((Double(buffer.frameLength) * ratio).rounded(.up)) + 32
+ guard let output = AVAudioPCMBuffer(pcmFormat: converter.outputFormat, frameCapacity: estimatedFrames) else { return nil }
+
+ var conversionError: NSError?
+ var consumed = false
+ converter.convert(to: output, error: &conversionError) { _, status in
+ if consumed {
+ status.pointee = .endOfStream
+ return nil
+ }
+ consumed = true
+ status.pointee = .haveData
+ return buffer
+ }
+ guard conversionError == nil else { return nil }
+ return Self.downmixToMono(output)
+ }
+
+ private static func downmixToMono(_ buffer: AVAudioPCMBuffer) -> [Float] {
+ guard let channelData = buffer.floatChannelData else { return [] }
+ let frameCount = Int(buffer.frameLength)
+ let channels = Int(buffer.format.channelCount)
+ if channels == 1 {
+ return Array(UnsafeBufferPointer(start: channelData[0], count: frameCount))
+ }
+ var mono = [Float](repeating: 0, count: frameCount)
+ for channel in 0..<channels {
+ vDSP_vadd(channelData[channel], 1, mono, 1, &mono, 1, vDSP_Length(frameCount))
+ }
+ var divisor = Float(channels)
+ vDSP_vsdiv(mono, 1, &divisor, &mono, 1, vDSP_Length(frameCount))
+ return mono
+ }
+
+ /// Doubles as the dropped-HAL-buffer detector via `sampleTime` deltas (plan rev #22).
+ private func checkSequenceContinuity(time: AVAudioTime, frameCount: Int) {
+ guard time.isSampleTimeValid else { return }
+ if let expected = self.lastExpectedSampleTime, time.sampleTime != expected {
+ self.statsBox.mutate { $0.sequenceContinuityViolations += 1 }
+ }
+ self.lastExpectedSampleTime = time.sampleTime + AVAudioFramePosition(frameCount)
+ }
+}
+
+// MARK: - Capture actor
+
+/// Lifecycle only — the hot path (tap callback) never hops into the actor (plan step 7).
+actor MeetingMicrophoneCapture {
+ typealias Stats = MeetingMicrophoneCaptureStats.Snapshot
+
+ private static let canonicalFormat = AVAudioFormat(
+ commonFormat: .pcmFormatFloat32, sampleRate: 48_000, channels: 1, interleaved: false
+ )!
+ private static let formatRetryLimit = 5
+ private static let formatRetryDelayNanoseconds: UInt64 = 100_000_000
+ private static let bindingOrderDescription =
+ "voiceProcessingEnabled -> bindCurrentDevice -> prepare -> start (TODO(probe): hard-code the measured winner)"
+
+ private let statsBox = MeetingMicrophoneCaptureStats()
+ private let generationBox = MeetingMicrophoneGenerationBox()
+
+ private var engine: AVAudioEngine?
+ private var isRunning = false
+ private var settled: MeetingMicrophoneSettledConfig?
+ private var configObserver: NSObjectProtocol?
+ private var defaultInputListenerToken: AudioObjectPropertyListenerBlock?
+ private var overloadListenerToken: AudioObjectPropertyListenerBlock?
+ private var overloadListenerDeviceID: AudioObjectID?
+
+ func start(
+ microphone: MeetingMicrophoneIdentity,
+ onSample: @escaping @Sendable (CMSampleBuffer) -> Void,
+ onEvent: @escaping @Sendable (MeetingMicrophoneCaptureEvent) -> Void = { _ in }
+ ) async throws -> MeetingMicrophoneBindingOutcome {
+ guard !self.isRunning else { throw MeetingMicrophoneCaptureError.alreadyStarted }
+ let currentGeneration = self.generationBox.advance()
+
+ guard AVCaptureDevice.authorizationStatus(for: .audio) == .authorized else {
+ return self.fail(microphone: microphone, reason: "Microphone permission is not granted.")
+ }
+
+ // Missing UID means the name match already wasn't unique; retrying it is vacuous.
+ guard let requestedUID = microphone.coreAudioUID, !requestedUID.isEmpty,
+ let requestedDeviceID = AudioDevice.listInputDevices().first(where: { $0.uid == requestedUID })?.id
+ else {
+ return self.fail(microphone: microphone, reason: "No CoreAudio device UID for '\(microphone.displayName)'.")
+ }
+
+ let engine = AVAudioEngine()
+ let input = engine.inputNode
+
+ // VPIO replaces the I/O unit: enable before any format read or device bind.
+ do {
+ try input.setVoiceProcessingEnabled(true)
+ } catch {
+ return self.fail(microphone: microphone, reason: "Voice processing could not be enabled: \(error.localizedDescription)")
+ }
+ var ducking = AVAudioVoiceProcessingOtherAudioDuckingConfiguration()
+ ducking.enableAdvancedDucking = false
+ ducking.duckingLevel = .min
+ input.voiceProcessingOtherAudioDuckingConfiguration = ducking
+
+ guard let audioUnit = input.audioUnit else {
+ return self.fail(microphone: microphone, reason: "AVAudioEngine.inputNode has no backing AudioUnit.")
+ }
+
+ // TODO(probe): bind order is a Phase-1 measurement; this hard-codes one attempt.
+ let bindStatus = Self.bindInputDevice(audioUnit, to: requestedDeviceID)
+
+ // The tap must exist before start(): the active graph is built at start, and a tap added to
+ // a node with no connections afterwards sits on an inactive node — measured as 10 minutes of
+ // zero callbacks while everything else reported healthy.
+ let preStartFormat = input.outputFormat(forBus: 0)
+ guard preStartFormat.sampleRate > 0, preStartFormat.channelCount > 0 else {
+ return self.fail(microphone: microphone, reason: "Input format invalid before start (\(preStartFormat)).")
+ }
+ let tapState = MeetingMicrophoneTapState(statsBox: self.statsBox, canonicalFormat: Self.canonicalFormat, onSample: onSample)
+ let generationBox = self.generationBox
+ input.installTap(onBus: 0, bufferSize: 4_800, format: preStartFormat) { buffer, time in
+ guard generationBox.isCurrent(currentGeneration) else { return }
+ tapState.handle(buffer: buffer, time: time)
+ }
+
+ engine.prepare()
+ do {
+ try engine.start()
+ } catch {
+ input.removeTap(onBus: 0)
+ return self.fail(microphone: microphone, reason: "AVAudioEngine failed to start: \(error.localizedDescription)")
+ }
+
+ let outcome = MeetingMicrophoneBindDecision.outcome(
+ bindStatus: bindStatus,
+ readBackDeviceID: Self.readBackBoundDevice(audioUnit),
+ requestedDeviceID: requestedDeviceID,
+ defaultInputUID: AudioDevice.getDefaultInputDevice()?.uid,
+ requestedUID: requestedUID
+ )
+ if case let .unavailable(reason) = outcome {
+ input.removeTap(onBus: 0)
+ engine.stop()
+ return self.fail(microphone: microphone, reason: reason)
+ }
+
+ guard let sourceFormat = await self.validatedInputFormat(input: input) else {
+ input.removeTap(onBus: 0)
+ engine.stop()
+ return self.fail(microphone: microphone, reason: "Input format never became valid (persistent 0 Hz).")
+ }
+ if sourceFormat != preStartFormat {
+ // Post-start renegotiation (HAL settling): reattach at the settled format.
+ input.removeTap(onBus: 0)
+ input.installTap(onBus: 0, bufferSize: 4_800, format: sourceFormat) { buffer, time in
+ guard generationBox.isCurrent(currentGeneration) else { return }
+ tapState.handle(buffer: buffer, time: time)
+ }
+ }
+
+ self.engine = engine
+ self.isRunning = true
+ self.settled = MeetingMicrophoneSettledConfig(
+ requestedMicrophone: microphone,
+ bindingOutcome: outcome,
+ bindingOrder: Self.bindingOrderDescription,
+ settledInputDeviceUID: requestedUID,
+ settledOutputDeviceUID: AudioDevice.getDefaultOutputDevice()?.uid,
+ sourceSampleRate: sourceFormat.sampleRate,
+ sourceChannelCount: Int(sourceFormat.channelCount),
+ voiceProcessingEnabled: true,
+ outputChannelDecision: "mono (explicit downmix); observed ch=1 on today's SCStream mic, not derived from SCStream's stereo capture config"
+ )
+ self.registerEventObservers(engine: engine, outcome: outcome, requestedDeviceID: requestedDeviceID, onEvent: onEvent)
+ return outcome
+ }
+
+ func stop() async {
+ guard self.isRunning else { return }
+ self.isRunning = false
+ self.generationBox.advance()
+
+ if let engine = self.engine {
+ engine.inputNode.removeTap(onBus: 0)
+ engine.stop()
+ }
+ self.engine = nil
+ self.tearDownEventObservers()
+ }
+
+ func statistics() -> Stats {
+ self.statsBox.snapshot()
+ }
+
+ func settledConfiguration() -> MeetingMicrophoneSettledConfig? {
+ self.settled
+ }
+
+ private func fail(microphone: MeetingMicrophoneIdentity, reason: String) -> MeetingMicrophoneBindingOutcome {
+ let outcome = MeetingMicrophoneBindingOutcome.unavailable(reason: reason)
+ self.settled = MeetingMicrophoneSettledConfig(
+ requestedMicrophone: microphone,
+ bindingOutcome: outcome,
+ bindingOrder: Self.bindingOrderDescription,
+ settledInputDeviceUID: nil,
+ settledOutputDeviceUID: AudioDevice.getDefaultOutputDevice()?.uid,
+ sourceSampleRate: 0,
+ sourceChannelCount: 0,
+ voiceProcessingEnabled: false,
+ outputChannelDecision: "mono (explicit downmix)"
+ )
+ return outcome
+ }
+
+ /// Mirrors `ASRService.swift:2797-2827`: the HAL can report 0 Hz even after `start()` returns.
+ private func validatedInputFormat(input: AVAudioInputNode) async -> AVAudioFormat? {
+ var format = input.outputFormat(forBus: 0)
+ var attempt = 0
+ while format.sampleRate == 0 || format.channelCount == 0 {
+ attempt += 1
+ if attempt > Self.formatRetryLimit { return nil }
+ try? await Task.sleep(nanoseconds: Self.formatRetryDelayNanoseconds)
+ format = input.outputFormat(forBus: 0)
+ }
+ return format
+ }
+
+ private func registerEventObservers(
+ engine: AVAudioEngine,
+ outcome: MeetingMicrophoneBindingOutcome,
+ requestedDeviceID: AudioObjectID,
+ onEvent: @escaping @Sendable (MeetingMicrophoneCaptureEvent) -> Void
+ ) {
+ let statsBox = self.statsBox
+ // queue: nil — see ASRService.registerEngineConfigurationChangeObserver for why synchronous
+ // delivery is load-bearing (avoids a deadlock against the engine's own serial queue).
+ self.configObserver = NotificationCenter.default.addObserver(
+ forName: .AVAudioEngineConfigurationChange, object: engine, queue: nil
+ ) { _ in
+ statsBox.mutate { $0.configurationChangeEvents += 1 }
+ onEvent(.configurationChanged)
+ }
+
+ if case .defaultMatchesRequested = outcome {
+ var address = AudioObjectPropertyAddress(
+ mSelector: kAudioHardwarePropertyDefaultInputDevice,
+ mScope: kAudioObjectPropertyScopeGlobal,
+ mElement: kAudioObjectPropertyElementMain
+ )
+ let token: AudioObjectPropertyListenerBlock = { _, _ in
+ statsBox.mutate { $0.defaultInputChangeEvents += 1 }
+ onEvent(.defaultInputChanged)
+ }
+ if AudioObjectAddPropertyListenerBlock(AudioObjectID(kAudioObjectSystemObject), &address, DispatchQueue.main, token) == noErr {
+ self.defaultInputListenerToken = token
+ }
+ }
+
+ if case .boundVerified = outcome {
+ var address = AudioObjectPropertyAddress(
+ mSelector: kAudioDeviceProcessorOverload,
+ mScope: kAudioObjectPropertyScopeGlobal,
+ mElement: kAudioObjectPropertyElementMain
+ )
+ let token: AudioObjectPropertyListenerBlock = { _, _ in
+ statsBox.mutate { $0.overloadCount += 1 }
+ onEvent(.overload)
+ }
+ if AudioObjectAddPropertyListenerBlock(requestedDeviceID, &address, DispatchQueue.main, token) == noErr {
+ self.overloadListenerToken = token
+ self.overloadListenerDeviceID = requestedDeviceID
+ }
+ }
+ }
+
+ private func tearDownEventObservers() {
+ if let configObserver = self.configObserver {
+ NotificationCenter.default.removeObserver(configObserver)
+ self.configObserver = nil
+ }
+ if let token = self.defaultInputListenerToken {
+ var address = AudioObjectPropertyAddress(
+ mSelector: kAudioHardwarePropertyDefaultInputDevice,
+ mScope: kAudioObjectPropertyScopeGlobal,
+ mElement: kAudioObjectPropertyElementMain
+ )
+ _ = AudioObjectRemovePropertyListenerBlock(AudioObjectID(kAudioObjectSystemObject), &address, DispatchQueue.main, token)
+ self.defaultInputListenerToken = nil
+ }
+ if let token = self.overloadListenerToken, let deviceID = self.overloadListenerDeviceID {
+ var address = AudioObjectPropertyAddress(
+ mSelector: kAudioDeviceProcessorOverload,
+ mScope: kAudioObjectPropertyScopeGlobal,
+ mElement: kAudioObjectPropertyElementMain
+ )
+ _ = AudioObjectRemovePropertyListenerBlock(deviceID, &address, DispatchQueue.main, token)
+ self.overloadListenerToken = nil
+ self.overloadListenerDeviceID = nil
+ }
+ }
+
+ /// On an I/O unit element 1 is the input side and element 0 the render side. Element 0 here
+ /// would set — and read back — the OUTPUT device: measured as "bound 85 (AirPods output) does
+ /// not match requested 78 (built-in mic)" while VPIO's echo reference silently stayed put.
+ private static let inputElement: AudioUnitElement = 1
+ private static let outputElement: AudioUnitElement = 0
+
+ private static func bindInputDevice(_ audioUnit: AudioUnit, to deviceID: AudioObjectID) -> OSStatus {
+ var mutableDeviceID = deviceID
+ return AudioUnitSetProperty(
+ audioUnit,
+ kAudioOutputUnitProperty_CurrentDevice,
+ kAudioUnitScope_Global,
+ Self.inputElement,
+ &mutableDeviceID,
+ UInt32(MemoryLayout<AudioObjectID>.size)
+ )
+ }
+
+ private static func readBackBoundDevice(_ audioUnit: AudioUnit) -> AudioObjectID? {
+ Self.currentDevice(audioUnit, element: Self.inputElement)
+ }
+
+ static func currentDevice(_ audioUnit: AudioUnit, element: AudioUnitElement) -> AudioObjectID? {
+ var deviceID = AudioObjectID(0)
+ var size = UInt32(MemoryLayout<AudioObjectID>.size)
+ let status = AudioUnitGetProperty(
+ audioUnit,
+ kAudioOutputUnitProperty_CurrentDevice,
+ kAudioUnitScope_Global,
+ element,
+ &deviceID,
+ &size
+ )
+ return status == noErr ? deviceID : nil
+ }
+}
+
+// MARK: - Opt-in hardware probe
+
+/// Real-hardware Phase 1 gate (plan §9), foreground only. `FLUIDVOICE_MIC_PHASE1=<minutes>`;
+/// `FLUIDVOICE_MIC_PHASE1_DEVICE` selects the Bluetooth leg.
+enum MeetingMicrophonePhase1Probe {
+ struct Result: Sendable {
+ var minutes: Double
+ var outcome: MeetingMicrophoneBindingOutcome
+ var settled: MeetingMicrophoneSettledConfig?
+ var stats: MeetingMicrophoneCaptureStats.Snapshot
+ var writerDiscontinuities: Int
+ var writerRotationCount: Int
+ var writerBackpressureEvents: Int
+ var finalHealthStatus: MeetingTrackHealthStatus
+ var liveCopyNilCount: Int
+ var deliveredSourceFormat: String
+ var peakAmplitude: Float
+ }
+
+ static func run(sessionDirectory: URL) async throws -> Result? {
+ guard let minutesString = ProcessInfo.processInfo.environment["FLUIDVOICE_MIC_PHASE1"],
+ let minutes = Double(minutesString), minutes > 0
+ else { return nil }
+
+ let microphone: MeetingMicrophoneIdentity
+ if let overrideUID = ProcessInfo.processInfo.environment["FLUIDVOICE_MIC_PHASE1_DEVICE"] {
+ microphone = try MeetingCaptureSourceCatalog.defaultMicrophone(preferredCoreAudioUID: overrideUID)
+ } else {
+ microphone = try MeetingCaptureSourceCatalog.defaultMicrophone()
+ }
+
+ var writerBackpressureEvents = 0
+ let track = MeetingAudioTrack(
+ id: UUID(),
+ kind: .microphone,
+ sourceIdentifier: microphone.captureDeviceID,
+ sourceDisplayName: microphone.displayName,
+ format: nil,
+ timebase: MeetingTimebaseMetadata(
+ startedHostTime: mach_absolute_time(),
+ machTimebaseNumerator: 0,
+ machTimebaseDenominator: 0,
+ firstPresentationTime: nil
+ ),
+ health: .waiting,
+ chunks: []
+ )
+ let writer = try MeetingAudioChunkWriter(
+ track: track,
+ sessionDirectory: sessionDirectory,
+ chunkDuration: MeetingCaptureConfiguration.defaultChunkDuration
+ ) { event in
+ if case .interrupted(.writerBackpressure, _, _) = event { writerBackpressureEvents += 1 }
+ }
+
+ var deliveredSourceFormat = "(none delivered)"
+ let capturedFormat = OSAllocatedUnfairLock<String?>(initialState: nil)
+ let tapTelemetry = OSAllocatedUnfairLock<(nilCopies: Int, peak: Float)>(initialState: (0, 0))
+
+ let capture = MeetingMicrophoneCapture()
+ let outcome = try await capture.start(microphone: microphone) { sampleBuffer in
+ if let description = CMSampleBufferGetFormatDescription(sampleBuffer),
+ let asbd = CMAudioFormatDescriptionGetStreamBasicDescription(description)?.pointee
+ {
+ capturedFormat.withLock { $0 = "\(asbd.mSampleRate)Hz \(asbd.mChannelsPerFrame)ch" }
+ }
+ let copied = MeetingLiveSampleCopy.copy(sampleBuffer)
+ var bufferPeak: Float = 0
+ if let channel = copied?.buffer.floatChannelData?[0], let frames = copied.map({ Int($0.buffer.frameLength) }) {
+ vDSP_maxmgv(channel, 1, &bufferPeak, vDSP_Length(frames))
+ }
+ tapTelemetry.withLock {
+ if copied == nil { $0.nilCopies += 1 }
+ $0.peak = max($0.peak, bufferPeak)
+ }
+ writer.enqueue(sampleBuffer)
+ }
+
+ try await Task.sleep(nanoseconds: UInt64(minutes * 60 * 1_000_000_000))
+ await capture.stop()
+ let finishedTrack = await writer.stop()
+ deliveredSourceFormat = capturedFormat.withLock { $0 } ?? deliveredSourceFormat
+ let telemetry = tapTelemetry.withLock { $0 }
+
+ return Result(
+ minutes: minutes,
+ outcome: outcome,
+ settled: await capture.settledConfiguration(),
+ stats: await capture.statistics(),
+ writerDiscontinuities: finishedTrack.chunks.reduce(0) { $0 + $1.discontinuities.count },
+ writerRotationCount: finishedTrack.chunks.count,
+ writerBackpressureEvents: writerBackpressureEvents,
+ finalHealthStatus: finishedTrack.health.status,
+ liveCopyNilCount: telemetry.nilCopies,
+ deliveredSourceFormat: deliveredSourceFormat,
+ peakAmplitude: telemetry.peak
+ )
+ }
+}
diff --git a/Tests/FluidDictationIntegrationTests/MeetingMicrophoneCaptureTests.swift b/Tests/FluidDictationIntegrationTests/MeetingMicrophoneCaptureTests.swift
new file mode 100644
index 00000000..0bbd505a
--- /dev/null
+++ b/Tests/FluidDictationIntegrationTests/MeetingMicrophoneCaptureTests.swift
@@ -0,0 +1,404 @@
+@testable import FluidVoice_Debug
+import AVFoundation
+import CoreMedia
+import Foundation
+import XCTest
+
+/// Hardware-free: everything here runs on CI. The opt-in real-hardware probe
+/// (`FLUIDVOICE_MIC_PHASE1`) lives in `MeetingMicrophonePhase1Probe` and is not exercised here.
+final class MeetingMicrophoneCaptureTests: XCTestCase {
+ private static let identityTimebase = mach_timebase_info_data_t(numer: 1, denom: 1)
+
+ private func makeClock() -> MeetingMicrophonePTSClock {
+ MeetingMicrophonePTSClock(timebase: Self.identityTimebase)
+ }
+
+ private func hostTime(seconds: Double) -> UInt64 {
+ UInt64(seconds * 1_000_000_000)
+ }
+
+ // MARK: - PTS clock
+
+ func testValidStampsMapHostTimeToCMTimeExactly() {
+ var clock = self.makeClock()
+ let outcome = clock.stamp(hostTime: self.hostTime(seconds: 2.5), frameCount: 4_800)
+ guard case let .emitted(pts, synthesized, corrected, resynced) = outcome else {
+ return XCTFail("expected an emitted stamp")
+ }
+ XCTAssertEqual(pts.seconds, 2.5, accuracy: 1.0 / 48_000)
+ XCTAssertFalse(synthesized)
+ XCTAssertFalse(corrected)
+ XCTAssertFalse(resynced)
+ }
+
+ func testValidStampsAreContinuousAcrossBuffers() {
+ var clock = self.makeClock()
+ _ = clock.stamp(hostTime: self.hostTime(seconds: 0), frameCount: 4_800)
+ let second = clock.stamp(hostTime: self.hostTime(seconds: 0.1), frameCount: 4_800)
+ guard case let .emitted(pts, _, corrected, _) = second else {
+ return XCTFail("expected an emitted stamp")
+ }
+ XCTAssertEqual(pts.seconds, 0.1, accuracy: 1.0 / 48_000)
+ XCTAssertFalse(corrected, "hostTime landed exactly on the anchor+framesEmitted domain")
+ }
+
+ /// Real-hardware Phase 1 gate; skips unless FLUIDVOICE_MIC_PHASE1=<minutes> is set.
+ func testPhase1HardwareGate() async throws {
+ let temp = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
+ try FileManager.default.createDirectory(at: temp, withIntermediateDirectories: true)
+ defer { try? FileManager.default.removeItem(at: temp) }
+ guard let result = try await MeetingMicrophonePhase1Probe.run(sessionDirectory: temp) else {
+ throw XCTSkip("FLUIDVOICE_MIC_PHASE1 not set")
+ }
+ let stats = result.stats
+ let validRate = stats.buffersEmitted > 0 ? Double(stats.validHostTimeCount) / Double(stats.buffersEmitted) : 0
+ print("""
+ [phase1] minutes=\(result.minutes) outcome=\(result.outcome)
+ [phase1] settled=\(String(describing: result.settled))
+ [phase1] delivered=\(result.deliveredSourceFormat) buffers=\(stats.buffersEmitted) validHostTime=\(String(format: "%.4f", validRate)) \
+ synthesized=\(stats.synthesizedCount) anchorCorrections=\(stats.anchorCorrectionCount) sequenceBreaks=\(stats.sequenceContinuityViolations)
+ [phase1] chunks=\(result.writerRotationCount) discontinuities=\(result.writerDiscontinuities) \
+ backpressure=\(result.writerBackpressureEvents) health=\(result.finalHealthStatus) liveCopyNils=\(result.liveCopyNilCount)
+ """)
+ XCTAssertGreaterThanOrEqual(validRate, 0.99)
+ XCTAssertEqual(result.writerDiscontinuities, 0)
+ XCTAssertEqual(result.writerBackpressureEvents, 0)
+ XCTAssertEqual(result.liveCopyNilCount, 0)
+ XCTAssertEqual(stats.conversionFailures, 0)
+ XCTAssertGreaterThan(result.peakAmplitude, 0, "a live microphone never captures digital silence")
+ let expectedChunks = Int((result.minutes * 60 / 60).rounded(.up))
+ XCTAssertLessThanOrEqual(abs(result.writerRotationCount - expectedChunks), 1, "rotation cadence ≈ chunkDuration")
+ }
+
+ /// Without any anchor there is no meaningful acquisition PTS: a zero anchor would park the mic
+ /// track at epoch 0 against SCStream's mach-domain stamps.
+ func testInvalidStampsBeforeFirstAnchorAreDropped() {
+ var clock = self.makeClock()
+ XCTAssertEqual(clock.stamp(hostTime: nil, frameCount: 480), .droppedPostCap)
+ XCTAssertEqual(clock.stamp(hostTime: nil, frameCount: 480), .droppedPostCap)
+ let first = clock.stamp(hostTime: self.hostTime(seconds: 7), frameCount: 480)
+ guard case let .emitted(pts, synthesized, _, _) = first else {
+ return XCTFail("expected the first valid stamp to anchor and emit")
+ }
+ XCTAssertEqual(pts.seconds, 7.0, accuracy: 1.0 / 48_000)
+ XCTAssertFalse(synthesized)
+ }
+
+ func testInvalidStampsExtrapolateFromLastValid() {
+ var clock = self.makeClock()
+ _ = clock.stamp(hostTime: self.hostTime(seconds: 0), frameCount: 4_800) // anchor at t=0, 100ms
+ let outcome = clock.stamp(hostTime: nil, frameCount: 4_800) // extrapolated 100ms window
+ guard case let .emitted(pts, synthesized, _, _) = outcome else {
+ return XCTFail("expected an emitted (synthesized) stamp")
+ }
+ XCTAssertEqual(pts.seconds, 0.1, accuracy: 1.0 / 48_000)
+ XCTAssertTrue(synthesized)
+ }
+
+ func testInvalidRunExtrapolatesForUpToHalfASecondThenDrops() {
+ var clock = self.makeClock()
+ _ = clock.stamp(hostTime: self.hostTime(seconds: 0), frameCount: 480) // 10ms anchor
+
+ var emittedSynthesizedCount = 0
+ var sawDrop = false
+ for _ in 0..<60 { // 60 * 10ms = 600ms of invalid stamps
+ let outcome = clock.stamp(hostTime: nil, frameCount: 480)
+ switch outcome {
+ case .emitted(_, let synthesized, _, _):
+ XCTAssertTrue(synthesized)
+ XCTAssertFalse(sawDrop, "no emission should follow a drop without a valid resync")
+ emittedSynthesizedCount += 1
+ case .droppedPostCap:
+ sawDrop = true
+ }
+ }
+ XCTAssertTrue(sawDrop, "600ms of invalid stamps must exceed the 500ms cap")
+ // 50 * 10ms = 500ms is within the cap and must still be emitted.
+ XCTAssertEqual(emittedSynthesizedCount, 50)
+ }
+
+ func testValidStampAfterADropResyncsAndCorrectsTheAnchor() {
+ var clock = self.makeClock()
+ _ = clock.stamp(hostTime: self.hostTime(seconds: 0), frameCount: 480)
+ for _ in 0..<60 { _ = clock.stamp(hostTime: nil, frameCount: 480) }
+
+ let resync = clock.stamp(hostTime: self.hostTime(seconds: 1.2), frameCount: 480)
+ guard case let .emitted(pts, synthesized, corrected, resynced) = resync else {
+ return XCTFail("expected an emitted stamp resuming from the drop")
+ }
+ XCTAssertEqual(pts.seconds, 1.2, accuracy: 1.0 / 48_000)
+ XCTAssertFalse(synthesized)
+ XCTAssertTrue(corrected)
+ XCTAssertTrue(resynced)
+
+ // Post-resync, valid stamps track the corrected anchor without further correction.
+ let next = clock.stamp(hostTime: self.hostTime(seconds: 1.21), frameCount: 480)
+ guard case let .emitted(_, _, nextCorrected, _) = next else {
+ return XCTFail("expected an emitted stamp")
+ }
+ XCTAssertFalse(nextCorrected)
+ }
+
+ func testSmallDivergenceDoesNotCorrectTheAnchor() {
+ var clock = self.makeClock()
+ _ = clock.stamp(hostTime: self.hostTime(seconds: 0), frameCount: 4_800)
+ // 1/96000s divergence is half a frame at 48kHz — below the one-frame correction threshold.
+ let outcome = clock.stamp(hostTime: self.hostTime(seconds: 0.1 + 1.0 / 96_000), frameCount: 4_800)
+ guard case let .emitted(_, _, corrected, _) = outcome else {
+ return XCTFail("expected an emitted stamp")
+ }
+ XCTAssertFalse(corrected)
+ }
+
+ func testLargeDivergenceCorrectsTheAnchorWithoutASynthesizedFlag() {
+ var clock = self.makeClock()
+ _ = clock.stamp(hostTime: self.hostTime(seconds: 0), frameCount: 4_800)
+ let outcome = clock.stamp(hostTime: self.hostTime(seconds: 0.15), frameCount: 4_800) // 50ms off
+ guard case let .emitted(pts, synthesized, corrected, resynced) = outcome else {
+ return XCTFail("expected an emitted stamp")
+ }
+ XCTAssertEqual(pts.seconds, 0.1, accuracy: 1.0 / 48_000, "this buffer's pts stays on the old, continuous domain")
+ XCTAssertFalse(synthesized)
+ XCTAssertTrue(corrected)
+ XCTAssertFalse(resynced, "a mid-stream correction is not a post-drop resync")
+ }
+
+ // MARK: - CMSampleBuffer synthesis round-trip
+
+ private func makeMonoBuffer(frameCount: Int, fill: (Int) -> Float) -> AVAudioPCMBuffer {
+ let format = AVAudioFormat(commonFormat: .pcmFormatFloat32, sampleRate: 48_000, channels: 1, interleaved: false)!
+ let buffer = AVAudioPCMBuffer(pcmFormat: format, frameCapacity: AVAudioFrameCount(frameCount))!
+ buffer.frameLength = AVAudioFrameCount(frameCount)
+ let channel = buffer.floatChannelData![0]
+ for index in 0..<frameCount { channel[index] = fill(index) }
+ return buffer
+ }
+
+ func testSynthesizedSampleBufferRoundTripsThroughLiveSampleCopy() throws {
+ let frameCount = 480
+ let source = self.makeMonoBuffer(frameCount: frameCount) { Float($0) / 1_000 }
+ let pts = CMTime(value: 123, timescale: 48_000)
+
+ let sampleBuffer = try XCTUnwrap(meetingMicrophoneSynthesizeSampleBuffer(from: source, presentationTime: pts))
+ XCTAssertEqual(CMSampleBufferGetNumSamples(sampleBuffer), frameCount)
+ XCTAssertEqual(CMSampleBufferGetPresentationTimeStamp(sampleBuffer), pts)
+ XCTAssertEqual(CMTimeGetSeconds(CMSampleBufferGetDuration(sampleBuffer)), Double(frameCount) / 48_000, accuracy: 1e-9)
+
+ let copy = try XCTUnwrap(MeetingLiveSampleCopy.copy(sampleBuffer))
+ XCTAssertEqual(copy.buffer.frameLength, AVAudioFrameCount(frameCount))
+ XCTAssertEqual(copy.buffer.format.commonFormat, .pcmFormatFloat32)
+ XCTAssertEqual(copy.buffer.format.sampleRate, 48_000)
+ XCTAssertEqual(copy.buffer.format.channelCount, 1)
+ XCTAssertEqual(copy.pts, pts)
+ for index in 0..<frameCount {
+ XCTAssertEqual(copy.buffer.floatChannelData![0][index], Float(index) / 1_000)
+ }
+ }
+
+ func testSynthesizedSampleBufferIsImmutableAgainstSourceMutation() throws {
+ let frameCount = 240
+ let source = self.makeMonoBuffer(frameCount: frameCount) { _ in 1.0 }
+ let sampleBuffer = try XCTUnwrap(
+ meetingMicrophoneSynthesizeSampleBuffer(from: source, presentationTime: CMTime(value: 0, timescale: 48_000))
+ )
+
+ let before = try XCTUnwrap(MeetingLiveSampleCopy.copy(sampleBuffer))
+ let beforeValues = (0..<frameCount).map { before.buffer.floatChannelData![0][$0] }
+
+ // Mutate the source AFTER synthesis — the synthesized buffer must not see this.
+ let channel = source.floatChannelData![0]
+ for index in 0..<frameCount { channel[index] = -99 }
+
+ let after = try XCTUnwrap(MeetingLiveSampleCopy.copy(sampleBuffer))
+ let afterValues = (0..<frameCount).map { after.buffer.floatChannelData![0][$0] }
+
+ XCTAssertEqual(beforeValues, afterValues)
+ XCTAssertEqual(afterValues, Array(repeating: Float(1.0), count: frameCount))
+ }
+
+ // MARK: - Binding decision table
+
+ func testBindingDecisionSucceedsOnVerifiedReadBack() {
+ let outcome = MeetingMicrophoneBindDecision.outcome(
+ bindStatus: noErr,
+ readBackDeviceID: 42,
+ requestedDeviceID: 42,
+ defaultInputUID: nil,
+ requestedUID: "uid-a"
+ )
+ XCTAssertEqual(outcome, .boundVerified(42))
+ }
+
+ func testBindingDecisionMismatchFallsBackToUnavailableWhenDefaultDoesNotMatch() {
+ let outcome = MeetingMicrophoneBindDecision.outcome(
+ bindStatus: noErr,
+ readBackDeviceID: 7,
+ requestedDeviceID: 42,
+ defaultInputUID: "uid-other",
+ requestedUID: "uid-a"
+ )
+ guard case .unavailable = outcome else { return XCTFail("expected unavailable, got \(outcome)") }
+ }
+
+ func testBindingDecisionReadBackErrorFallsBackToEscapeHatchWhenDefaultMatches() {
+ let outcome = MeetingMicrophoneBindDecision.outcome(
+ bindStatus: -10_851,
+ readBackDeviceID: nil,
+ requestedDeviceID: 42,
+ defaultInputUID: "uid-a",
+ requestedUID: "uid-a"
+ )
+ XCTAssertEqual(outcome, .defaultMatchesRequested)
+ }
+
+ func testBindingDecisionAggregateDeviceStatusIsUnavailableWithoutEscapeHatch() {
+ let outcome = MeetingMicrophoneBindDecision.outcome(
+ bindStatus: -10_851,
+ readBackDeviceID: nil,
+ requestedDeviceID: 42,
+ defaultInputUID: "uid-other",
+ requestedUID: "uid-a"
+ )
+ guard case let .unavailable(reason) = outcome else { return XCTFail("expected unavailable, got \(outcome)") }
+ XCTAssertTrue(reason.contains("10851"))
+ }
+
+ func testBindingDecisionReadBackMismatchIsDistinctFromReadBackError() {
+ let mismatch = MeetingMicrophoneBindDecision.outcome(
+ bindStatus: noErr,
+ readBackDeviceID: 99,
+ requestedDeviceID: 42,
+ defaultInputUID: nil,
+ requestedUID: "uid-a"
+ )
+ let readBackError = MeetingMicrophoneBindDecision.outcome(
+ bindStatus: noErr,
+ readBackDeviceID: nil,
+ requestedDeviceID: 42,
+ defaultInputUID: nil,
+ requestedUID: "uid-a"
+ )
+ guard case let .unavailable(mismatchReason) = mismatch,
+ case let .unavailable(errorReason) = readBackError
+ else { return XCTFail("expected both to be unavailable") }
+ XCTAssertNotEqual(mismatchReason, errorReason)
+ }
+
+ // MARK: - Writer-coupled synthetic stamp-sequence test (plan rev #17)
+
+ private func makeWriter() throws -> (writer: MeetingAudioChunkWriter, sessionDirectory: URL) {
+ let sessionDirectory = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
+ let track = MeetingAudioTrack(
+ id: UUID(),
+ kind: .microphone,
+ sourceIdentifier: "test-mic",
+ sourceDisplayName: "Test Microphone",
+ format: nil,
+ timebase: MeetingTimebaseMetadata(
+ startedHostTime: 0, machTimebaseNumerator: 1, machTimebaseDenominator: 1, firstPresentationTime: nil
+ ),
+ health: .waiting,
+ chunks: []
+ )
+ let writer = try MeetingAudioChunkWriter(
+ track: track, sessionDirectory: sessionDirectory, chunkDuration: 60
+ ) { _ in }
+ return (writer, sessionDirectory)
+ }
+
+ private func pushBuffer(_ writer: MeetingAudioChunkWriter, ptsSeconds: Double, frameCount: Int = 480) {
+ let buffer = self.makeMonoBuffer(frameCount: frameCount) { _ in 0.1 }
+ let pts = CMTime(seconds: ptsSeconds, preferredTimescale: 48_000)
+ guard let sampleBuffer = meetingMicrophoneSynthesizeSampleBuffer(from: buffer, presentationTime: pts) else {
+ return XCTFail("failed to synthesize a sample buffer")
+ }
+ writer.enqueue(sampleBuffer)
+ }
+
+ func testSteadySequenceProducesOneChunkWithNoDiscontinuities() async throws {
+ let (writer, sessionDirectory) = try self.makeWriter()
+ defer { try? FileManager.default.removeItem(at: sessionDirectory) }
+
+ for tick in 0..<20 {
+ self.pushBuffer(writer, ptsSeconds: Double(tick) * 0.01)
+ }
+ let track = await writer.stop()
+
+ XCTAssertEqual(track.chunks.count, 1)
+ XCTAssertEqual(track.chunks.first?.discontinuities ?? [], [])
+ }
+
+ func testOneTickOverlapTriggersClockDiscontinuityAndRotation() async throws {
+ let (writer, sessionDirectory) = try self.makeWriter()
+ defer { try? FileManager.default.removeItem(at: sessionDirectory) }
+
+ for tick in 0..<10 {
+ self.pushBuffer(writer, ptsSeconds: Double(tick) * 0.01)
+ }
+ // One tick (1/48000s) before the running end — a backwards stamp.
+ self.pushBuffer(writer, ptsSeconds: 0.1 - 1.0 / 48_000)
+ let track = await writer.stop()
+
+ XCTAssertEqual(track.chunks.count, 2)
+ XCTAssertEqual(track.chunks.first?.discontinuities.map(\.kind), [.clockDiscontinuity])
+ }
+
+ func testFortyNineMillisecondGapDoesNotRotate() async throws {
+ let (writer, sessionDirectory) = try self.makeWriter()
+ defer { try? FileManager.default.removeItem(at: sessionDirectory) }
+
+ self.pushBuffer(writer, ptsSeconds: 0, frameCount: 480) // ends at 0.01s
+ self.pushBuffer(writer, ptsSeconds: 0.01 + 0.49) // 0.49s gap, at/under the 0.5s threshold
+ let track = await writer.stop()
+
+ XCTAssertEqual(track.chunks.count, 1)
+ XCTAssertEqual(track.chunks.first?.discontinuities ?? [], [])
+ }
+
+ func testFiftyOneMillisecondGapTriggersSourceLostAndRotation() async throws {
+ let (writer, sessionDirectory) = try self.makeWriter()
+ defer { try? FileManager.default.removeItem(at: sessionDirectory) }
+
+ self.pushBuffer(writer, ptsSeconds: 0, frameCount: 480) // ends at 0.01s
+ self.pushBuffer(writer, ptsSeconds: 0.01 + 0.51) // 0.51s gap, over the 0.5s threshold
+ let track = await writer.stop()
+
+ XCTAssertEqual(track.chunks.count, 2)
+ XCTAssertEqual(track.chunks.first?.discontinuities.map(\.kind), [.sourceLost])
+ }
+
+ /// Drives the PTS clock through a 500ms synthesized run followed by a 600ms dropped run, feeding
+ /// only what the clock says to emit into a real writer — the only test that exercises the risky
+ /// cap/drop/resync path end to end.
+ func testSixHundredMillisecondInvalidRunProducesSourceLostAfterResync() async throws {
+ let (writer, sessionDirectory) = try self.makeWriter()
+ defer { try? FileManager.default.removeItem(at: sessionDirectory) }
+
+ var clock = self.makeClock()
+ func emit(_ outcome: MeetingMicrophonePTSClock.Outcome, frameCount: Int) {
+ guard case let .emitted(pts, _, _, _) = outcome else { return }
+ let buffer = self.makeMonoBuffer(frameCount: frameCount) { _ in 0.1 }
+ guard let sampleBuffer = meetingMicrophoneSynthesizeSampleBuffer(from: buffer, presentationTime: pts) else {
+ return XCTFail("failed to synthesize a sample buffer")
+ }
+ writer.enqueue(sampleBuffer)
+ }
+
+ emit(clock.stamp(hostTime: self.hostTime(seconds: 0), frameCount: 480), frameCount: 480)
+ for _ in 0..<50 { // up to and including the 500ms cap boundary, all still emitted and contiguous
+ emit(clock.stamp(hostTime: nil, frameCount: 480), frameCount: 480)
+ }
+ var droppedCount = 0
+ for _ in 0..<60 { // 600ms dropped — nothing pushed to the writer for these
+ if case .droppedPostCap = clock.stamp(hostTime: nil, frameCount: 480) { droppedCount += 1 }
+ }
+ XCTAssertEqual(droppedCount, 60, "the entire 600ms run must be past the cap and dropped")
+
+ let resync = clock.stamp(hostTime: self.hostTime(seconds: 1.1), frameCount: 480)
+ emit(resync, frameCount: 480)
+
+ let track = await writer.stop()
+ XCTAssertEqual(track.chunks.count, 2)
+ XCTAssertEqual(track.chunks.first?.discontinuities.map(\.kind), [.sourceLost])
+ }
+}