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.pbxprojindex 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.mdindex 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, confarrival deltas would have been the wrong instrument. Caveats: one machine, and the probe needs anunlocked 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 cannotbe measured with an acoustic click** — AEC removes it, so a failed correlation would mean cancellationdiff --git a/Sources/Fluid/Services/Meeting/MeetingMicrophoneCapture.swift b/Sources/Fluid/Services/Meeting/MeetingMicrophoneCapture.swiftnew file mode 100644index 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.swiftnew file mode 100644index 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])+ }+}