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

test(meeting): Phase 0 clock-domain probe — SCStream PTS is mach-anchored

Shreeraman A Kfd083bd1033c
diff --git a/Fluid.xcodeproj/project.pbxproj b/Fluid.xcodeproj/project.pbxproj
index 616ebbc0..8544115b 100644
--- a/Fluid.xcodeproj/project.pbxproj
+++ b/Fluid.xcodeproj/project.pbxproj
@@ -37,6 +37,7 @@
E5EC00000000000000000042 /* VoiceProcessingDuckingProbeTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = E5EC00000000000000000041 /* VoiceProcessingDuckingProbeTests.swift */; };
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 */; };
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 */; };
@@ -100,6 +101,7 @@
E5EC00000000000000000041 /* VoiceProcessingDuckingProbeTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = VoiceProcessingDuckingProbeTests.swift; sourceTree = "<group>"; };
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>"; };
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>"; };
@@ -211,6 +213,7 @@
E5EC00000000000000000041 /* VoiceProcessingDuckingProbeTests.swift */,
E5EC00000000000000000051 /* VoiceProcessingSpeechDuckingTests.swift */,
E5EC00000000000000000061 /* VoiceProcessingAsrQualityTests.swift */,
+ E5EC00000000000000000071 /* ClockDomainProbeTests.swift */,
355C1248D5386D1F815EB7D7 /* MeetingLiveTranscriptionTests.swift */,
7BE63EB94BB280F38F5CB028 /* MeetingLiveReplayTests.swift */,
C0DE63600000000000000001 /* AudioEngineRetirementDrainTests.swift */,
@@ -407,6 +410,7 @@
E5EC00000000000000000042 /* VoiceProcessingDuckingProbeTests.swift in Sources */,
E5EC00000000000000000052 /* VoiceProcessingSpeechDuckingTests.swift in Sources */,
E5EC00000000000000000062 /* VoiceProcessingAsrQualityTests.swift in Sources */,
+ E5EC00000000000000000072 /* ClockDomainProbeTests.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 e6a434ca..143c8961 100644
--- a/MIC_CAPTURE_MIGRATION_PLAN.md
+++ b/MIC_CAPTURE_MIGRATION_PLAN.md
@@ -118,21 +118,24 @@ establishment. Echo reference alignment is gone.
does (`ASRService.swift:4617-4620`). Never `mach_absolute_time()` at callback time.
- Invalid `hostTime`: extrapolate from the last valid stamp plus output duration, **capped at 500 ms**;
beyond that, record a discontinuity and resync.
-- **The constant-offset model is contingent.** This repo measured ~6.4 ppm drift, ~23 ms/hour
- (`MeetingProcessingPipeline.swift:722-724`); a fixed offset is ~46 ms wrong at two hours, consuming
- the whole budget. Phase 0 decides: same clock domain ⇒ offset is identity and no model is needed;
- different domains ⇒ a linear model with periodic re-measurement, not a constant.
+- **Resolved by Phase 0 (see §9): same clock domain.** SCStream PTS regressed against mach at
+ −0.133 ppm ± 0.628 over 24k samples — the offset is effectively identity and no drift model is
+ needed. The ~6.4 ppm drift this repo previously measured (`MeetingProcessingPipeline.swift:722-724`)
+ was between the two *audio device* clocks through their samples, not between SCStream's stamps and
+ mach; it remains real for echo-reference alignment, which VPIO sessions no longer perform.
**Budget: ±50 ms**, justified by turn ordering alone. Stated as a claim to be tested, not derived —
v3 wrongly cited the 0.15 s `overlapsRemote` threshold, which is a minimum-overlap predicate.
## 9. Phases and gates
-**Phase 0 — clock domain (unattended).** Compare *rates*, not arrival deltas: regress SCStream PTS
-against wall time and microphone PTS against wall time over 30 minutes. *Gate:* report both slopes in
-ppm with confidence intervals. |slope difference| < 20 ppm ⇒ constant offset acceptable; ≥ 20 ppm ⇒
-§8's linear model is mandatory. Subtracting `mach_absolute_time()` at arrival is **not** the test — it
-conflates queueing jitter with clock domain.
+**Phase 0 — clock domain. DONE, 2026-08-15.** Regressed SCStream audio PTS against mach host time
+over 8 minutes, 24,027 samples (`ClockDomainProbeTests`, `FLUIDVOICE_CLOCK_PROBE`): slope
+**−0.133 ppm, 95% CI ±0.628** — statistically zero, 150× inside the 20 ppm gate. SCStream PTS is
+mach-anchored, so both capture paths already share a clock domain: **constant offset only; the
+linear model in §8 is not needed.** Residual std 6.9 ms is arrival jitter, confirming that per-sample
+arrival deltas would have been the wrong instrument. Caveats: one machine, and the probe needs an
+unlocked display in a foreground session (`SCShareableContent` reports zero displays otherwise).
**Phase 1 — `MeetingMicrophoneCapture`, standalone.** *Gate*, over 10 minutes on the built-in mic
**and** one Bluetooth device: valid `hostTime` on ≥99% of buffers; output Float32 LPCM (else the
diff --git a/Tests/FluidDictationIntegrationTests/ClockDomainProbeTests.swift b/Tests/FluidDictationIntegrationTests/ClockDomainProbeTests.swift
new file mode 100644
index 00000000..f1cd5241
--- /dev/null
+++ b/Tests/FluidDictationIntegrationTests/ClockDomainProbeTests.swift
@@ -0,0 +1,151 @@
+@testable import FluidVoice_Debug
+import AVFoundation
+import CoreMedia
+import Foundation
+import ScreenCaptureKit
+import XCTest
+
+/// Phase 0 of the mic-capture migration: is SCStream's audio PTS in the mach host clock domain?
+///
+/// The migration puts the microphone on AVAudioEngine, whose tap stamps are mach host time by
+/// definition. Whether cross-track alignment needs a constant offset or a drift model depends
+/// entirely on SCStream's clock: regress its audio PTS against mach time over a long capture and
+/// read the slope. Arrival jitter perturbs individual samples, not a long-run slope.
+///
+/// Gate (MIC_CAPTURE_MIGRATION_PLAN.md §9): |slope − 1| < 20 ppm ⇒ constant offset is acceptable;
+/// ≥ 20 ppm ⇒ the linear model in §8 is mandatory.
+///
+/// Run with FLUIDVOICE_CLOCK_PROBE=<minutes>.
+final class ClockDomainProbeTests: XCTestCase {
+ func testScreenCaptureAudioClockAgainstMachHostTime() async throws {
+ guard let minutesString = ProcessInfo.processInfo.environment["FLUIDVOICE_CLOCK_PROBE"],
+ let minutes = Double(minutesString), minutes > 0
+ else {
+ throw XCTSkip("FLUIDVOICE_CLOCK_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 recorder = ClockPairRecorder()
+ let output = ClockProbeOutput(recorder: recorder)
+ let stream = SCStream(filter: filter, configuration: configuration, delegate: nil)
+ try stream.addStreamOutput(output, type: .audio, sampleHandlerQueue: DispatchQueue(label: "clock.probe"))
+ try await stream.startCapture()
+ defer { Task { try? await stream.stopCapture() } }
+
+ let seconds = minutes * 60
+ print(String(format: "[clock] capturing for %.0f minutes…", minutes))
+ // Progress report every minute so a truncated run still yields a usable slope series.
+ 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 let fit = await recorder.regression() {
+ print(String(
+ format: "[clock] t=%4.0fs n=%6d slope=%+.3f ppm residualStd=%.3f ms ptsSpan=%.1fs",
+ elapsed, fit.count, fit.slopePPM, fit.residualStdMs, fit.ptsSpanSeconds
+ ))
+ }
+ }
+
+ guard let fit = await recorder.regression(), fit.count > 1000 else {
+ XCTFail("insufficient samples for a slope estimate")
+ return
+ }
+ print(String(
+ format: "\n[clock] FINAL n=%d slope=%+.3f ppm (95%% CI ±%.3f) residualStd=%.3f ms gate=%@",
+ fit.count, fit.slopePPM, fit.slopeCI95PPM, fit.residualStdMs,
+ abs(fit.slopePPM) < 20 ? "CONSTANT OFFSET OK" : "LINEAR MODEL REQUIRED"
+ ))
+ }
+}
+
+/// 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
+ private static let timebase: 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.timebase
+ let seconds = pts.seconds
+ Task { [recorder] in await recorder.record(mach: mach, pts: seconds) }
+ }
+}