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

fix(meeting): Phase 2 - PTS clock latch bug, drift measurement, step detector

Shreeraman A K680b7132e18d
diff --git a/Fluid.xcodeproj/project.pbxproj b/Fluid.xcodeproj/project.pbxproj
index 5e6c82bf..17996bbd 100644
--- a/Fluid.xcodeproj/project.pbxproj
+++ b/Fluid.xcodeproj/project.pbxproj
@@ -39,6 +39,8 @@
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 */; };
+ E5EC000000000000000000A2 /* MeetingTimelineDriftProbeTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = E5EC000000000000000000A1 /* MeetingTimelineDriftProbeTests.swift */; };
+ E5EC00000000000000000092 /* ClockRegressionHelper.swift in Sources */ = {isa = PBXBuildFile; fileRef = E5EC00000000000000000091 /* ClockRegressionHelper.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 */; };
@@ -104,6 +106,8 @@
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>"; };
+ E5EC000000000000000000A1 /* MeetingTimelineDriftProbeTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MeetingTimelineDriftProbeTests.swift; sourceTree = "<group>"; };
+ E5EC00000000000000000091 /* ClockRegressionHelper.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ClockRegressionHelper.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>"; };
@@ -217,6 +221,8 @@
E5EC00000000000000000061 /* VoiceProcessingAsrQualityTests.swift */,
E5EC00000000000000000071 /* ClockDomainProbeTests.swift */,
E5EC00000000000000000081 /* MeetingMicrophoneCaptureTests.swift */,
+ E5EC000000000000000000A1 /* MeetingTimelineDriftProbeTests.swift */,
+ E5EC00000000000000000091 /* ClockRegressionHelper.swift */,
355C1248D5386D1F815EB7D7 /* MeetingLiveTranscriptionTests.swift */,
7BE63EB94BB280F38F5CB028 /* MeetingLiveReplayTests.swift */,
C0DE63600000000000000001 /* AudioEngineRetirementDrainTests.swift */,
@@ -415,6 +421,8 @@
E5EC00000000000000000062 /* VoiceProcessingAsrQualityTests.swift in Sources */,
E5EC00000000000000000072 /* ClockDomainProbeTests.swift in Sources */,
E5EC00000000000000000082 /* MeetingMicrophoneCaptureTests.swift in Sources */,
+ E5EC000000000000000000A2 /* MeetingTimelineDriftProbeTests.swift in Sources */,
+ E5EC00000000000000000092 /* ClockRegressionHelper.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 4b27e1e8..0ccc8474 100644
--- a/MIC_CAPTURE_MIGRATION_PLAN.md
+++ b/MIC_CAPTURE_MIGRATION_PLAN.md
@@ -162,11 +162,34 @@ design:
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
-worked. Use a loud chirp and matched-filter the ~33 dB residual; if the residual is unrecoverable,
-record that absolute offset is unmeasured, accept ordering-tolerance validation on a real call, and
-say so rather than reporting a number.
+**Phase 2 — timeline. DONE, 2026-08-15, gate honestly FAILED — with the remedy designed.**
+
+The Phase 1 "corrections on 97% of buffers" finding was a **misdiagnosis**: not HAL jitter but a
+latch bug — the correction re-baselined one full accumulation window off (post- vs pre-increment
+frame count), so every subsequent stamp re-corrected forever. Reproduced by simulation (drift-only
+run predicts first fire at window ~32; field data showed 31 and 34), fixed with one line, and the
+first-fire index back-derives the built-in mic's drift as ~6.4 ppm — matching the repo's old
+echo-path measurement from an entirely different method.
+
+Cross-path drift gate (8 min, dual capture, guards all zero):
+`mic +6.693 ppm (CI ±0.635) | app −0.081 ppm (CI ±0.627) | Δ 6.774, CI_Δ 0.892` → the
+budget-derived gate (Δ+CI < 6.9 ppm = ±50 ms over 2 h) **failed by 0.77 ppm**. The mic's sample
+clock genuinely runs ~6.7 ppm fast vs mach: 24 ms/hour of skew, 48.8 ms at 2 h — inside budget at
+the point estimate, over it with CI, and per-device physics that another machine or a USB mic could
+triple.
+
+**Remedy (Phase 3, consumer side):** the clock's correction stream is now a live drift meter
+(`cumulativeAbsorbedCorrectionSeconds`, one correction per ~3.2 s, each ≤20.8 µs). The batch
+pipeline applies a linear de-drift to mic PTS when mapping onto the shared timeline — one multiply —
+holding the budget with ~10× margin for **any** device, which also retires the USB-microphone
+concern structurally. Capture-side PTS stays sample-count truth (the invariant: `anchorPTS` is never
+moved mid-stream; corrections adjust only the divergence reference and are a no-op on output).
+
+Also built: divergence **step detector** (10 ms threshold; drift moves 0.64 ns/window and cannot
+fire it — verified over a simulated 2 h), resync clamp so a backlogged invalid burst can never step
+PTS behind emitted audio, timeline reset on `AVAudioEngineConfigurationChange`, and real timebase
+values in the probe's track metadata. Absolute cross-path offset remains unmeasured (AEC removes
+acoustic stimuli, as reviewed) and is Phase 3's first real-call validation item.
**Phase 3 — integrate behind a flag, default off.** *Gate:* a real call whose transcript ordering is
compared turn-by-turn against a human-checked reference. Not a simultaneous old-path capture — two
diff --git a/Sources/Fluid/Services/Meeting/MeetingMicrophoneCapture.swift b/Sources/Fluid/Services/Meeting/MeetingMicrophoneCapture.swift
index 37360724..642cff78 100644
--- a/Sources/Fluid/Services/Meeting/MeetingMicrophoneCapture.swift
+++ b/Sources/Fluid/Services/Meeting/MeetingMicrophoneCapture.swift
@@ -8,9 +8,9 @@ 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.
+/// Anchor-and-count acquisition PTS. INVARIANT: emitted PTS is sample-count truth — corrections
+/// adjust only the divergence reference, never `anchorPTS`, so they are a no-op on output and
+/// double as a drift meter (~one per 3.2 s at the mic's measured ~6.7 ppm).
nonisolated struct MeetingMicrophonePTSClock {
enum Outcome: Equatable {
/// `resynced` is true when this valid stamp follows a post-cap dropped run.
@@ -19,6 +19,17 @@ nonisolated struct MeetingMicrophonePTSClock {
case droppedPostCap
}
+ /// Genuine steps only: drift moves 0.64 ns/window, jitter stays in the µs.
+ static let divergenceStepThresholdSeconds: Double = 0.010
+
+ private(set) var cumulativeAbsorbedCorrectionSeconds: Double = 0
+ private(set) var maxAbsDivergenceSeconds: Double = 0
+ private(set) var divergenceStepEventCount = 0
+ private(set) var maxDivergenceStepSeconds: Double = 0
+ private(set) var resyncClampCount = 0
+ private var lastDivergenceSeconds: Double = 0
+ private var lastEmittedEnd: CMTime = .invalid
+
/// Deliberately equal to the writer's 0.5 s gap threshold (`MeetingAudioChunkWriter.swift:181`).
static let synthesisCapSeconds: Double = 0.5
@@ -30,8 +41,7 @@ nonisolated struct MeetingMicrophonePTSClock {
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 synthesizedRunFrames: Int64 = 0 // integer frames: summed Doubles drift the cap
private var isDroppingInvalidRun = false
init(sampleRate: Double = Double(Self.timescale), timebase: mach_timebase_info_data_t = Self.machTimebase()) {
@@ -60,7 +70,7 @@ nonisolated struct MeetingMicrophonePTSClock {
self.framesSinceAnchor = 0
}
- /// `nil` iff `isHostTimeValid` is false; 0 is a legitimate mach tick, not a sentinel.
+ // hostTime nil iff isHostTimeValid 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)
@@ -69,8 +79,7 @@ nonisolated struct MeetingMicrophonePTSClock {
}
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 {
+ guard self.anchorHostSeconds != nil else { // no anchor: epoch-0 PTS would poison origins
return .droppedPostCap
}
if self.isDroppingInvalidRun {
@@ -83,6 +92,7 @@ nonisolated struct MeetingMicrophonePTSClock {
self.isDroppingInvalidRun = true
return .droppedPostCap
}
+ self.noteEmitted(pts: pts, frameCount: frameCount)
return .emitted(pts: pts, synthesized: true, anchorCorrected: false, resynced: false)
}
@@ -93,24 +103,55 @@ nonisolated struct MeetingMicrophonePTSClock {
self.synthesizedRunFrames = 0
if self.anchorHostSeconds == nil || wasDropping {
- self.resetAnchor(hostSeconds: actualSeconds)
+ // A backlogged invalid burst can synthesize more timeline than elapsed host time;
+ // anchoring behind emitted audio would trip the writer's backwards check.
+ var resyncSeconds = actualSeconds
+ if self.lastEmittedEnd.isValid, self.lastEmittedEnd.seconds > resyncSeconds {
+ resyncSeconds = self.lastEmittedEnd.seconds
+ self.resyncClampCount += 1
+ }
+ self.resetAnchor(hostSeconds: resyncSeconds)
+ self.lastDivergenceSeconds = 0
let pts = self.currentPTS()
self.framesSinceAnchor += Int64(frameCount)
+ self.noteEmitted(pts: pts, frameCount: frameCount)
return .emitted(pts: pts, synthesized: false, anchorCorrected: wasDropping, resynced: wasDropping)
}
let expectedSeconds = self.anchorHostSeconds! + Double(self.framesSinceAnchor) / self.sampleRate
let divergence = actualSeconds - expectedSeconds
+ self.maxAbsDivergenceSeconds = max(self.maxAbsDivergenceSeconds, abs(divergence))
+ let step = abs(divergence - self.lastDivergenceSeconds)
+ if step > Self.divergenceStepThresholdSeconds {
+ self.divergenceStepEventCount += 1
+ self.maxDivergenceStepSeconds = max(self.maxDivergenceStepSeconds, step)
+ }
+ self.lastDivergenceSeconds = divergence
let pts = self.currentPTS()
self.framesSinceAnchor += Int64(frameCount)
+ self.noteEmitted(pts: pts, frameCount: frameCount)
var corrected = false
if abs(divergence) > 1.0 / self.sampleRate {
- self.anchorHostSeconds = actualSeconds - Double(self.framesSinceAnchor) / self.sampleRate
+ // += divergence; using the post-increment count latches one window off (97% bug).
+ self.anchorHostSeconds! += divergence
+ self.cumulativeAbsorbedCorrectionSeconds += divergence
+ self.lastDivergenceSeconds = 0
corrected = true
}
return .emitted(pts: pts, synthesized: false, anchorCorrected: corrected, resynced: false)
}
+
+ private mutating func noteEmitted(pts: CMTime, frameCount: Int) {
+ self.lastEmittedEnd = CMTimeAdd(pts, CMTime(value: Int64(frameCount), timescale: Self.timescale))
+ }
+
+ mutating func requestTimelineReset() {
+ self.anchorHostSeconds = nil
+ self.isDroppingInvalidRun = false
+ self.synthesizedRunFrames = 0
+ self.lastDivergenceSeconds = 0
+ }
}
// MARK: - CMSampleBuffer synthesis (free function, no AVAudioEngine dependency)
@@ -302,6 +343,11 @@ final class MeetingMicrophoneCaptureStats: @unchecked Sendable {
var defaultInputChangeEvents = 0
var tapCallbackMaxDurationSeconds: Double = 0
var tapCallbackP99DurationSeconds: Double = 0
+ var cumulativeAbsorbedCorrectionSeconds: Double = 0
+ var maxAbsDivergenceSeconds: Double = 0
+ var divergenceStepEventCount = 0
+ var maxDivergenceStepSeconds: Double = 0
+ var resyncClampCount = 0
/// The Phase 1 gate's headline number: ≥99% valid hostTime over the run.
var validHostTimeFraction: Double {
@@ -396,6 +442,7 @@ private final class MeetingMicrophoneTapState: @unchecked Sendable {
let start = DispatchTime.now()
defer { self.statsBox.recordCallbackDuration(Double(DispatchTime.now().uptimeNanoseconds - start.uptimeNanoseconds) / 1_000_000_000) }
+ self.consumePendingResetIfNeeded()
self.checkSequenceContinuity(time: time, frameCount: Int(buffer.frameLength))
let converted = self.convertToMono(buffer)
@@ -442,15 +489,44 @@ private final class MeetingMicrophoneTapState: @unchecked Sendable {
return
}
+ let clock = self.clock
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 }
+ stats.cumulativeAbsorbedCorrectionSeconds = clock.cumulativeAbsorbedCorrectionSeconds
+ stats.maxAbsDivergenceSeconds = clock.maxAbsDivergenceSeconds
+ stats.divergenceStepEventCount = clock.divergenceStepEventCount
+ stats.maxDivergenceStepSeconds = clock.maxDivergenceStepSeconds
+ stats.resyncClampCount = clock.resyncClampCount
}
self.onSample(sampleBuffer)
}
+ /// Set off the tap thread; consumed at the next callback so the clock re-anchors.
+ func requestTimelineReset() {
+ self.pendingTimelineReset.withLock { $0 = true }
+ }
+
+ private let pendingTimelineReset = OSAllocatedUnfairLock(initialState: false)
+
+ private func consumePendingResetIfNeeded() {
+ let pending = self.pendingTimelineReset.withLock { flag -> Bool in
+ defer { flag = false }
+ return flag
+ }
+ if pending {
+ self.clock.requestTimelineReset()
+ self.accumulated.removeAll(keepingCapacity: true)
+ self.windowHostTime = nil
+ self.windowHostTimeValid = false
+ self.lastExpectedSampleTime = nil
+ self.converter = nil
+ self.converterSourceFormat = nil
+ }
+ }
+
/// Resample first, then downmix explicitly — converter channel mapping may drop, not mix.
private func convertToMono(_ buffer: AVAudioPCMBuffer) -> [Float]? {
let sourceFormat = buffer.format
@@ -537,6 +613,7 @@ actor MeetingMicrophoneCapture {
private let generationBox = MeetingMicrophoneGenerationBox()
private var engine: AVAudioEngine?
+ private var tapState: MeetingMicrophoneTapState?
private var isRunning = false
private var settled: MeetingMicrophoneSettledConfig?
private var configObserver: NSObjectProtocol?
@@ -584,14 +661,14 @@ actor MeetingMicrophoneCapture {
// 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.
+ // Tap before start(): added afterwards it sits on an inactive node — measured as
+ // 10 minutes of zero callbacks with healthy telemetry.
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)
+ self.tapState = tapState
let generationBox = self.generationBox
input.installTap(onBus: 0, bufferSize: 4_800, format: preStartFormat) { buffer, time in
guard generationBox.isCurrent(currentGeneration) else { return }
@@ -660,6 +737,7 @@ actor MeetingMicrophoneCapture {
engine.stop()
}
self.engine = nil
+ self.tapState = nil
self.tearDownEventObservers()
}
@@ -711,8 +789,9 @@ actor MeetingMicrophoneCapture {
// 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
+ ) { [weak tapState = self.tapState] _ in
statsBox.mutate { $0.configurationChangeEvents += 1 }
+ tapState?.requestTimelineReset()
onEvent(.configurationChanged)
}
@@ -774,9 +853,8 @@ actor MeetingMicrophoneCapture {
}
}
- /// 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.
+ /// Element 1 is the input side; element 0 would set/read the OUTPUT device (measured: read-back
+ /// returned the AirPods output against a requested built-in mic).
private static let inputElement: AudioUnitElement = 1
private static let outputElement: AudioUnitElement = 0
@@ -813,8 +891,7 @@ actor MeetingMicrophoneCapture {
// 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.
+/// Real-hardware Phase 1 gate (plan §9), foreground only; env FLUIDVOICE_MIC_PHASE1[_DEVICE].
enum MeetingMicrophonePhase1Probe {
struct Result: Sendable {
var minutes: Double
@@ -851,8 +928,12 @@ enum MeetingMicrophonePhase1Probe {
format: nil,
timebase: MeetingTimebaseMetadata(
startedHostTime: mach_absolute_time(),
- machTimebaseNumerator: 0,
- machTimebaseDenominator: 0,
+ machTimebaseNumerator: {
+ var info = mach_timebase_info_data_t(); mach_timebase_info(&info); return info.numer
+ }(),
+ machTimebaseDenominator: {
+ var info = mach_timebase_info_data_t(); mach_timebase_info(&info); return info.denom
+ }(),
firstPresentationTime: nil
),
health: .waiting,
diff --git a/Tests/FluidDictationIntegrationTests/ClockDomainProbeTests.swift b/Tests/FluidDictationIntegrationTests/ClockDomainProbeTests.swift
index f1cd5241..0f87964e 100644
--- a/Tests/FluidDictationIntegrationTests/ClockDomainProbeTests.swift
+++ b/Tests/FluidDictationIntegrationTests/ClockDomainProbeTests.swift
@@ -74,61 +74,6 @@ final class ClockDomainProbeTests: XCTestCase {
}
}
-/// Records (mach seconds, SCStream PTS seconds) pairs and fits PTS = a + b·mach by least squares.
-private actor ClockPairRecorder {
- struct Fit {
- let count: Int
- let slopePPM: Double
- let slopeCI95PPM: Double
- let residualStdMs: Double
- let ptsSpanSeconds: Double
- }
-
- private var machTimes: [Double] = []
- private var ptsTimes: [Double] = []
-
- func record(mach: Double, pts: Double) {
- self.machTimes.append(mach)
- self.ptsTimes.append(pts)
- }
-
- func regression() -> Fit? {
- let n = self.machTimes.count
- guard n > 10 else { return nil }
- let x0 = self.machTimes[0]
- let y0 = self.ptsTimes[0]
- let xs = self.machTimes.map { $0 - x0 }
- let ys = self.ptsTimes.map { $0 - y0 }
- let sumX = xs.reduce(0, +)
- let sumY = ys.reduce(0, +)
- let meanX = sumX / Double(n)
- let meanY = sumY / Double(n)
- var sxx = 0.0
- var sxy = 0.0
- for i in 0..<n {
- let dx = xs[i] - meanX
- sxx += dx * dx
- sxy += dx * (ys[i] - meanY)
- }
- guard sxx > 0 else { return nil }
- let slope = sxy / sxx
- var sse = 0.0
- let intercept = meanY - slope * meanX
- for i in 0..<n {
- let r = ys[i] - (intercept + slope * xs[i])
- sse += r * r
- }
- let residualVariance = sse / Double(max(1, n - 2))
- let slopeStdErr = (residualVariance / sxx).squareRoot()
- return Fit(
- count: n,
- slopePPM: (slope - 1) * 1_000_000,
- slopeCI95PPM: 1.96 * slopeStdErr * 1_000_000,
- residualStdMs: residualVariance.squareRoot() * 1_000,
- ptsSpanSeconds: ys.last ?? 0
- )
- }
-}
private final class ClockProbeOutput: NSObject, SCStreamOutput {
private let recorder: ClockPairRecorder
diff --git a/Tests/FluidDictationIntegrationTests/ClockRegressionHelper.swift b/Tests/FluidDictationIntegrationTests/ClockRegressionHelper.swift
new file mode 100644
index 00000000..4d98728d
--- /dev/null
+++ b/Tests/FluidDictationIntegrationTests/ClockRegressionHelper.swift
@@ -0,0 +1,75 @@
+import Foundation
+
+/// Least-squares fit of a (mach seconds, PTS seconds) series, shared by the Phase 0 clock-domain
+/// probe and the Phase 2 cross-path drift probe. Regression, never per-sample deltas: arrival
+/// jitter perturbs points, not a long-run slope.
+final actor ClockPairRecorder {
+ struct Fit {
+ let count: Int
+ let slopePPM: Double
+ let slopeCI95PPM: Double
+ let residualStdMs: Double
+ let ptsSpanSeconds: Double
+ }
+
+ private var machTimes: [Double] = []
+ private var ptsTimes: [Double] = []
+
+ func record(mach: Double, pts: Double) {
+ self.machTimes.append(mach)
+ self.ptsTimes.append(pts)
+ }
+
+ func count() -> Int { self.machTimes.count }
+
+ func regression() -> Fit? {
+ Self.fit(machTimes: self.machTimes, ptsTimes: self.ptsTimes)
+ }
+
+ /// Fits each half separately: a warm-up drift transient shows as disagreeing halves even when
+ /// the whole-run CI looks tight.
+ func halfSplitSlopesPPM() -> (first: Double, second: Double)? {
+ let n = self.machTimes.count
+ guard n > 200 else { return nil }
+ let mid = n / 2
+ guard let a = Self.fit(machTimes: Array(self.machTimes[..<mid]), ptsTimes: Array(self.ptsTimes[..<mid])),
+ let b = Self.fit(machTimes: Array(self.machTimes[mid...]), ptsTimes: Array(self.ptsTimes[mid...]))
+ else { return nil }
+ return (a.slopePPM, b.slopePPM)
+ }
+
+ static func fit(machTimes: [Double], ptsTimes: [Double]) -> Fit? {
+ let n = machTimes.count
+ guard n > 10 else { return nil }
+ let x0 = machTimes[0]
+ let y0 = ptsTimes[0]
+ let xs = machTimes.map { $0 - x0 }
+ let ys = ptsTimes.map { $0 - y0 }
+ let meanX = xs.reduce(0, +) / Double(n)
+ let meanY = ys.reduce(0, +) / Double(n)
+ var sxx = 0.0
+ var sxy = 0.0
+ for i in 0..<n {
+ let dx = xs[i] - meanX
+ sxx += dx * dx
+ sxy += dx * (ys[i] - meanY)
+ }
+ guard sxx > 0 else { return nil }
+ let slope = sxy / sxx
+ let intercept = meanY - slope * meanX
+ var sse = 0.0
+ for i in 0..<n {
+ let r = ys[i] - (intercept + slope * xs[i])
+ sse += r * r
+ }
+ let residualVariance = sse / Double(max(1, n - 2))
+ let slopeStdErr = (residualVariance / sxx).squareRoot()
+ return Fit(
+ count: n,
+ slopePPM: (slope - 1) * 1_000_000,
+ slopeCI95PPM: 1.96 * slopeStdErr * 1_000_000,
+ residualStdMs: residualVariance.squareRoot() * 1_000,
+ ptsSpanSeconds: ys.last ?? 0
+ )
+ }
+}
diff --git a/Tests/FluidDictationIntegrationTests/MeetingMicrophoneCaptureTests.swift b/Tests/FluidDictationIntegrationTests/MeetingMicrophoneCaptureTests.swift
index 0bbd505a..dcd3f21a 100644
--- a/Tests/FluidDictationIntegrationTests/MeetingMicrophoneCaptureTests.swift
+++ b/Tests/FluidDictationIntegrationTests/MeetingMicrophoneCaptureTests.swift
@@ -402,3 +402,89 @@ final class MeetingMicrophoneCaptureTests: XCTestCase {
XCTAssertEqual(track.chunks.first?.discontinuities.map(\.kind), [.sourceLost])
}
}
+
+// MARK: - Phase 2: correction latch, step detector, resync clamp
+
+extension MeetingMicrophoneCaptureTests {
+ /// The Phase 1 field data (corrections on ~97% of buffers) was a latch: the correction
+ /// re-baselined one full window off, so every subsequent stamp re-corrected forever.
+ func testCorrectionDoesNotLatchAcrossSubsequentStamps() {
+ var clock = self.makeClock()
+ _ = clock.stamp(hostTime: self.hostTime(seconds: 0), frameCount: 4_800)
+ // Force one genuine correction with a 5ms excursion…
+ _ = clock.stamp(hostTime: self.hostTime(seconds: 0.105), frameCount: 4_800)
+ // …then five contiguous jitter-free stamps on the shifted timeline: zero further corrections.
+ for i in 2...6 {
+ let outcome = clock.stamp(hostTime: self.hostTime(seconds: 0.005 + Double(i) * 0.1), frameCount: 4_800)
+ guard case let .emitted(_, _, corrected, _) = outcome else { return XCTFail("expected emission") }
+ XCTAssertFalse(corrected, "stamp \(i) re-corrected: the latch is back")
+ }
+ }
+
+ /// A correction is a no-op on output: the next buffer's PTS continues exactly from the
+ /// previous end.
+ func testCorrectionLeavesEmittedPTSContinuous() {
+ var clock = self.makeClock()
+ _ = clock.stamp(hostTime: self.hostTime(seconds: 0), frameCount: 4_800)
+ guard case let .emitted(before, _, corrected1, _) = clock.stamp(hostTime: self.hostTime(seconds: 0.108), frameCount: 4_800) else {
+ return XCTFail("expected emission")
+ }
+ XCTAssertTrue(corrected1)
+ guard case let .emitted(after, _, _, _) = clock.stamp(hostTime: self.hostTime(seconds: 0.208), frameCount: 4_800) else {
+ return XCTFail("expected emission")
+ }
+ XCTAssertEqual(after.seconds - before.seconds, 0.1, accuracy: 1.0 / 48_000)
+ }
+
+ /// Drift must never fire the step detector: 6.4 ppm over a simulated two hours.
+ func testSlowDriftNeverFiresTheStepDetector() {
+ var clock = self.makeClock()
+ let windows = 72_000 // 2h of 100ms windows
+ for i in 0..<windows {
+ let actual = Double(i) * 0.1 * (1 + 6.4e-6)
+ _ = clock.stamp(hostTime: self.hostTime(seconds: actual), frameCount: 4_800)
+ }
+ XCTAssertEqual(clock.divergenceStepEventCount, 0)
+ XCTAssertGreaterThan(clock.cumulativeAbsorbedCorrectionSeconds, 0, "drift shows up as absorbed corrections")
+ }
+
+ func testSingleJumpFiresExactlyOneStepEvent() {
+ var clock = self.makeClock()
+ for i in 0..<10 {
+ _ = clock.stamp(hostTime: self.hostTime(seconds: Double(i) * 0.1), frameCount: 4_800)
+ }
+ _ = clock.stamp(hostTime: self.hostTime(seconds: 1.0 + 0.050), frameCount: 4_800) // 50ms step
+ for i in 11..<20 {
+ _ = clock.stamp(hostTime: self.hostTime(seconds: 0.050 + Double(i) * 0.1), frameCount: 4_800)
+ }
+ XCTAssertEqual(clock.divergenceStepEventCount, 1)
+ XCTAssertEqual(clock.maxDivergenceStepSeconds, 0.050, accuracy: 0.001)
+ }
+
+ /// A backlogged invalid burst can synthesize more timeline than elapsed host time; the resync
+ /// anchor clamps forward so PTS never steps behind emitted audio.
+ func testResyncNeverStepsBehindEmittedAudio() {
+ var clock = self.makeClock()
+ _ = clock.stamp(hostTime: self.hostTime(seconds: 0), frameCount: 4_800)
+ // 500ms of synthesized emission (cap-inclusive), delivered as a burst…
+ for _ in 0..<5 { _ = clock.stamp(hostTime: nil, frameCount: 4_800) }
+ _ = clock.stamp(hostTime: nil, frameCount: 4_800) // over cap → dropping
+ // …then a valid stamp whose host time is EARLIER than the emitted end (0.6s emitted, 0.3s wall).
+ guard case let .emitted(pts, _, _, resynced) = clock.stamp(hostTime: self.hostTime(seconds: 0.3), frameCount: 4_800) else {
+ return XCTFail("expected resync emission")
+ }
+ XCTAssertTrue(resynced)
+ XCTAssertGreaterThanOrEqual(pts.seconds, 0.6 - 1.0 / 48_000, "resync anchored behind already-emitted audio")
+ XCTAssertEqual(clock.resyncClampCount, 1)
+ }
+
+ func testTimelineResetReanchorsOnNextValidStamp() {
+ var clock = self.makeClock()
+ _ = clock.stamp(hostTime: self.hostTime(seconds: 5), frameCount: 4_800)
+ clock.requestTimelineReset()
+ guard case let .emitted(pts, _, _, _) = clock.stamp(hostTime: self.hostTime(seconds: 9), frameCount: 4_800) else {
+ return XCTFail("expected emission after reset")
+ }
+ XCTAssertEqual(pts.seconds, 9.0, accuracy: 1.0 / 48_000)
+ }
+}
diff --git a/Tests/FluidDictationIntegrationTests/MeetingTimelineDriftProbeTests.swift b/Tests/FluidDictationIntegrationTests/MeetingTimelineDriftProbeTests.swift
new file mode 100644
index 00000000..911526b8
--- /dev/null
+++ b/Tests/FluidDictationIntegrationTests/MeetingTimelineDriftProbeTests.swift
@@ -0,0 +1,170 @@
+@testable import FluidVoice_Debug
+import AudioToolbox
+import AVFoundation
+import CoreMedia
+import Foundation
+import ScreenCaptureKit
+import XCTest
+
+/// Phase 2 gate: do the two capture paths' clocks stay in step? Runs `MeetingMicrophoneCapture`
+/// (VPIO, built-in mic) and an SCStream audio capture simultaneously, regressing each path's
+/// emitted PTS against mach wall time.
+///
+/// Gate: |slope_mic − slope_app| + CI_Δ < 6.9 ppm — derived from the ±50 ms ordering budget over a
+/// 2-hour meeting (50 ms / 7200 s), NOT from Phase 0's 20 ppm domain check, which answered a
+/// different question. Absolute cross-path offset is not measurable acoustically (AEC removes the
+/// stimulus at ~33 dB); the deterministic latency components are printed instead as the Phase 3
+/// estimate. Preconditions: foreground session, unlocked display, speakers (not Bluetooth — VPIO
+/// delivers nothing on a BT render route), VPIO ducking audible during the run.
+///
+/// Run with FLUIDVOICE_DRIFT_PROBE=<minutes>.
+final class MeetingTimelineDriftProbeTests: XCTestCase {
+ private static let gatePPM = 6.9
+ private static let ciBudgetPPM = 1.4 // 20% of the gate; wider means "extend the run", not "pass"
+
+ func testCrossPathClockDrift() async throws {
+ guard let minutesString = ProcessInfo.processInfo.environment["FLUIDVOICE_DRIFT_PROBE"],
+ let minutes = Double(minutesString), minutes > 0
+ else { throw XCTSkip("FLUIDVOICE_DRIFT_PROBE not set") }
+
+ let content = try await SCShareableContent.excludingDesktopWindows(false, onScreenWindowsOnly: true)
+ guard let display = content.displays.first else { throw XCTSkip("no display") }
+ let filter = SCContentFilter(display: display, excludingApplications: [], exceptingWindows: [])
+ let configuration = SCStreamConfiguration()
+ configuration.width = 2
+ configuration.height = 2
+ configuration.minimumFrameInterval = CMTime(value: 1, timescale: 1)
+ configuration.queueDepth = 3
+ configuration.showsCursor = false
+ configuration.capturesAudio = true
+ configuration.sampleRate = 48_000
+ configuration.channelCount = 2
+ configuration.excludesCurrentProcessAudio = true
+
+ let appRecorder = ClockPairRecorder()
+ let appOutput = DriftStreamOutput(recorder: appRecorder)
+ let stream = SCStream(filter: filter, configuration: configuration, delegate: nil)
+ try stream.addStreamOutput(appOutput, type: .audio, sampleHandlerQueue: DispatchQueue(label: "drift.app"))
+ try await stream.startCapture()
+ defer { Task { try? await stream.stopCapture() } }
+
+ let temp = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
+ try FileManager.default.createDirectory(at: temp, withIntermediateDirectories: true)
+ defer { try? FileManager.default.removeItem(at: temp) }
+
+ let microphone = try MeetingCaptureSourceCatalog.defaultMicrophone(preferredCoreAudioUID: "BuiltInMicrophoneDevice")
+ var writerDiscontinuities = 0
+ let track = MeetingAudioTrack(
+ id: UUID(), kind: .microphone,
+ sourceIdentifier: microphone.captureDeviceID, sourceDisplayName: microphone.displayName,
+ format: nil,
+ timebase: MeetingTimebaseMetadata(
+ startedHostTime: mach_absolute_time(),
+ machTimebaseNumerator: Self.timebase.numer,
+ machTimebaseDenominator: Self.timebase.denom,
+ firstPresentationTime: nil
+ ),
+ health: .waiting, chunks: []
+ )
+ let writer = try MeetingAudioChunkWriter(track: track, sessionDirectory: temp, chunkDuration: 60) { _ in }
+
+ let micRecorder = ClockPairRecorder()
+ let capture = MeetingMicrophoneCapture()
+ let outcome = try await capture.start(microphone: microphone) { sampleBuffer in
+ // Mach sampled synchronously on the tap thread, before the writer hop.
+ let mach = Double(mach_absolute_time()) * Self.timebaseSeconds
+ let pts = CMSampleBufferGetPresentationTimeStamp(sampleBuffer)
+ if pts.isValid {
+ Task { await micRecorder.record(mach: mach, pts: pts.seconds) }
+ }
+ writer.enqueue(sampleBuffer)
+ }
+ guard case .boundVerified = outcome else {
+ throw XCTSkip("mic not bindable in this environment: \(outcome)")
+ }
+ Self.printLatencyEstimate(capture: await capture.settledConfiguration())
+
+ let seconds = minutes * 60
+ var elapsed = 0.0
+ while elapsed < seconds {
+ let step = min(60.0, seconds - elapsed)
+ try await Task.sleep(nanoseconds: UInt64(step * 1_000_000_000))
+ elapsed += step
+ if elapsed >= 30, await micRecorder.count() == 0 {
+ XCTFail("no mic buffers after 30s — Bluetooth render route or dead capture")
+ await capture.stop()
+ return
+ }
+ let mic = await micRecorder.regression()
+ let app = await appRecorder.regression()
+ print(String(
+ format: "[drift] t=%4.0fs mic n=%5d slope=%+7.3f ppm | app n=%6d slope=%+7.3f ppm",
+ elapsed, mic?.count ?? 0, mic?.slopePPM ?? .nan, app?.count ?? 0, app?.slopePPM ?? .nan
+ ))
+ }
+
+ await capture.stop()
+ let finishedTrack = await writer.stop()
+ writerDiscontinuities = finishedTrack.chunks.reduce(0) { $0 + $1.discontinuities.count }
+ let stats = await capture.statistics()
+
+ guard let mic = await micRecorder.regression(), let app = await appRecorder.regression() else {
+ return XCTFail("insufficient samples for regression")
+ }
+ let delta = abs(mic.slopePPM - app.slopePPM)
+ let ciDelta = (mic.slopeCI95PPM * mic.slopeCI95PPM + app.slopeCI95PPM * app.slopeCI95PPM).squareRoot()
+ let micHalves = await micRecorder.halfSplitSlopesPPM()
+
+ print(String(format: "\n[drift] mic slope=%+.3f ppm (CI ±%.3f) residual=%.2f ms n=%d", mic.slopePPM, mic.slopeCI95PPM, mic.residualStdMs, mic.count))
+ print(String(format: "[drift] app slope=%+.3f ppm (CI ±%.3f) residual=%.2f ms n=%d", app.slopePPM, app.slopeCI95PPM, app.residualStdMs, app.count))
+ print(String(format: "[drift] Δ=%.3f ppm CI_Δ=%.3f → projected skew %.1f ms/hour", delta, ciDelta, (delta + ciDelta) * 3.6))
+ if let halves = micHalves {
+ print(String(format: "[drift] mic half-split: %+.3f / %+.3f ppm (Δ=%.3f)", halves.first, halves.second, abs(halves.first - halves.second)))
+ }
+ print("[drift] guards: seqViolations=\(stats.sequenceContinuityViolations) convFail=\(stats.conversionFailures) droppedPostCap=\(stats.droppedPostCapCount) resyncs=\(stats.resyncCount) writerDisc=\(writerDiscontinuities) configChanges=\(stats.configurationChangeEvents) corrections=\(stats.anchorCorrectionCount) absorbed=\(String(format: "%.3f", stats.cumulativeAbsorbedCorrectionSeconds * 1_000))ms stepEvents=\(stats.divergenceStepEventCount)")
+ print("[drift] NOTE: absolute cross-path offset is unmeasured here (AEC removes acoustic stimuli); Phase 3 validates it on a real call.")
+
+ if stats.configurationChangeEvents > 0 {
+ throw XCTSkip("configuration changed mid-run — probe artifact, re-run")
+ }
+ XCTAssertEqual(stats.sequenceContinuityViolations, 0)
+ XCTAssertEqual(stats.conversionFailures, 0)
+ XCTAssertEqual(stats.droppedPostCapCount, 0)
+ XCTAssertEqual(stats.resyncCount, 0)
+ XCTAssertEqual(writerDiscontinuities, 0)
+ XCTAssertLessThanOrEqual(ciDelta, Self.ciBudgetPPM, "CI too wide — extend the run rather than trusting the point estimate")
+ XCTAssertLessThan(delta + ciDelta, Self.gatePPM, "cross-path drift violates the ±50ms/2h ordering budget")
+ }
+
+ private static let timebase: mach_timebase_info_data_t = {
+ var info = mach_timebase_info_data_t()
+ mach_timebase_info(&info)
+ return info
+ }()
+ private static let timebaseSeconds = Double(timebase.numer) / Double(timebase.denom) / 1_000_000_000
+
+ /// The deterministic latency components — the Phase 3 absolute-offset estimate.
+ private static func printLatencyEstimate(capture settled: MeetingMicrophoneSettledConfig?) {
+ guard let settled else { return }
+ print("[drift] settled: input=\(settled.settledInputDeviceUID ?? "?") output=\(settled.settledOutputDeviceUID ?? "?") source=\(settled.sourceSampleRate)Hz/\(settled.sourceChannelCount)ch")
+ }
+}
+
+private final class DriftStreamOutput: NSObject, SCStreamOutput {
+ private let recorder: ClockPairRecorder
+ private static let timebaseSeconds: Double = {
+ var info = mach_timebase_info_data_t()
+ mach_timebase_info(&info)
+ return Double(info.numer) / Double(info.denom) / 1_000_000_000
+ }()
+
+ init(recorder: ClockPairRecorder) { self.recorder = recorder }
+
+ func stream(_ stream: SCStream, didOutputSampleBuffer sampleBuffer: CMSampleBuffer, of type: SCStreamOutputType) {
+ guard type == .audio else { return }
+ let pts = CMSampleBufferGetPresentationTimeStamp(sampleBuffer)
+ guard pts.isValid else { return }
+ let mach = Double(mach_absolute_time()) * Self.timebaseSeconds
+ Task { [recorder] in await recorder.record(mach: mach, pts: pts.seconds) }
+ }
+}