Skip to content

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

feat(meeting): Phase 3 - VPIO mic capture behind a default-off flag

Shreeraman A Kcf96d35cc16e
diff --git a/Fluid.xcodeproj/project.pbxproj b/Fluid.xcodeproj/project.pbxproj
index 17996bbd..0914fb40 100644
--- a/Fluid.xcodeproj/project.pbxproj
+++ b/Fluid.xcodeproj/project.pbxproj
@@ -39,6 +39,7 @@
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 */; };
+ 5A3B00000000000000000002 /* MeetingVoiceProcessingCaptureTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 5A3B00000000000000000001 /* MeetingVoiceProcessingCaptureTests.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 */; };
@@ -106,6 +107,7 @@
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>"; };
+ 5A3B00000000000000000001 /* MeetingVoiceProcessingCaptureTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MeetingVoiceProcessingCaptureTests.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>"; };
@@ -221,6 +223,7 @@
E5EC00000000000000000061 /* VoiceProcessingAsrQualityTests.swift */,
E5EC00000000000000000071 /* ClockDomainProbeTests.swift */,
E5EC00000000000000000081 /* MeetingMicrophoneCaptureTests.swift */,
+ 5A3B00000000000000000001 /* MeetingVoiceProcessingCaptureTests.swift */,
E5EC000000000000000000A1 /* MeetingTimelineDriftProbeTests.swift */,
E5EC00000000000000000091 /* ClockRegressionHelper.swift */,
355C1248D5386D1F815EB7D7 /* MeetingLiveTranscriptionTests.swift */,
@@ -421,6 +424,7 @@
E5EC00000000000000000062 /* VoiceProcessingAsrQualityTests.swift in Sources */,
E5EC00000000000000000072 /* ClockDomainProbeTests.swift in Sources */,
E5EC00000000000000000082 /* MeetingMicrophoneCaptureTests.swift in Sources */,
+ 5A3B00000000000000000002 /* MeetingVoiceProcessingCaptureTests.swift in Sources */,
E5EC000000000000000000A2 /* MeetingTimelineDriftProbeTests.swift in Sources */,
E5EC00000000000000000092 /* ClockRegressionHelper.swift in Sources */,
A6E2246FA3744C7B3E2DB91C /* MeetingLiveTranscriptionTests.swift in Sources */,
diff --git a/MIC_CAPTURE_MIGRATION_PLAN.md b/MIC_CAPTURE_MIGRATION_PLAN.md
index 0ccc8474..df686460 100644
--- a/MIC_CAPTURE_MIGRATION_PLAN.md
+++ b/MIC_CAPTURE_MIGRATION_PLAN.md
@@ -191,9 +191,28 @@ PTS behind emitted audio, timeline reset on `AVAudioEngineConfigurationChange`,
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
+**Phase 3 — integrate behind a flag, default off. BUILT 2026-08-15, gate pending (needs a real call).**
+Shipped behind `meetingVPIOMicCapture` (Settings → experimental, off): pre-flight capability
+decision (pure decision table; flag + `.onlineCall` + CoreAudio UID + built-in-speaker output route,
+every decline reason logged to session events); `VoiceProcessingMeetingRuntime` with a commit gate —
+mic audio and events buffer in a ring until viability + first-buffer-within-2s + app-only SCStream
+are all confirmed, so an aborted attempt leaves writers byte-clean and the fallback needs no
+re-stamp (provenance is pessimistic `.screenCaptureKit`, durably promoted to `.voiceProcessing`
+before the first flushed byte; flush is serialized ahead of passthrough so PTS order holds); one
+10s total start deadline, expiry during fallback fails cleanly; mid-session surface = emitted-only
+10s watchdog + output-route listener (same predicate as pre-flight, service-restart re-registration)
++ defaultInputChanged UID check, all mapping to the existing interruption flow. Batch de-drift
+(`MeetingMicrophoneDeDrift`, k = 1 + cumulative/elapsed — sign verified against the clock: a fast
+mic accumulates NEGATIVE corrections) applies to emitted turn boundaries only, gated on a persisted
+eligibility bit (zero resyncs/steps/config-changes), 5ms materiality, 100ppm sanity. No
+pipelineVersion bump (no pre-flag `.voiceProcessing` tracks can exist; checkpoints snapshot the
+application pass only). Live echo filter untouched — deferred to Phase 4 as an attribution change.
+Reviewed adversarially over three rounds (two independent reviewers from BLOCK to PROCEED /
+PROCEED WITH CHANGES, all findings folded); 36 new unit tests.
+*Gate (open):* a real call ≥15 min (materiality must actually cross) whose transcript ordering is
compared turn-by-turn against a human-checked reference. Not a simultaneous old-path capture — two
-microphone clients with one enabling VPIO perturbs the system under test.
+microphone clients with one enabling VPIO perturbs the system under test. Also: start latency
+p50/p95 both paths, `silentForSeconds` under AGC, meeting→dictation teardown, flag-off byte-identical.
**Phase 4 — attribution.** One change: mark VPIO turns scored-clean and let the existing election run.
*Gate:* a single-voice VPIO session elects "You" with no `Microphone / Unknown`; a **two-voice**
diff --git a/Sources/Fluid/Persistence/BackupService.swift b/Sources/Fluid/Persistence/BackupService.swift
index 0dfdd165..deec1849 100644
--- a/Sources/Fluid/Persistence/BackupService.swift
+++ b/Sources/Fluid/Persistence/BackupService.swift
@@ -64,6 +64,8 @@ struct SettingsBackupPayload: Codable, Equatable {
let showHistoryPerformanceMetrics: Bool?
// Optional so backups created before the silence filter still decode.
let skipSilentRecordingsEnabled: Bool?
+ // Optional so backups created before Phase 3 voice-processing capture still decode.
+ let meetingVPIOMicCapture: Bool?
let enableAIStreaming: Bool
let copyTranscriptionToClipboard: Bool
let textInsertionMode: SettingsStore.TextInsertionMode
diff --git a/Sources/Fluid/Persistence/SettingsStore.swift b/Sources/Fluid/Persistence/SettingsStore.swift
index 866db0b7..0ac2d214 100644
--- a/Sources/Fluid/Persistence/SettingsStore.swift
+++ b/Sources/Fluid/Persistence/SettingsStore.swift
@@ -1865,6 +1865,15 @@ final class SettingsStore: ObservableObject {
}
}
+ /// Routes online-call meeting mic capture through AVAudioEngine voice processing; opt-in.
+ var meetingVPIOMicCapture: Bool {
+ get { self.defaults.object(forKey: Keys.meetingVPIOMicCapture) as? Bool ?? false }
+ set {
+ objectWillChange.send()
+ self.defaults.set(newValue, forKey: Keys.meetingVPIOMicCapture)
+ }
+ }
+
var enableAIStreaming: Bool {
get {
let value = self.defaults.object(forKey: Keys.enableAIStreaming)
@@ -3329,6 +3338,7 @@ final class SettingsStore: ObservableObject {
experimentalParakeetUnifiedFinalEnabled: self.experimentalParakeetUnifiedFinalEnabled,
showHistoryPerformanceMetrics: self.showHistoryPerformanceMetrics,
skipSilentRecordingsEnabled: self.skipSilentRecordingsEnabled,
+ meetingVPIOMicCapture: self.meetingVPIOMicCapture,
enableAIStreaming: self.enableAIStreaming,
copyTranscriptionToClipboard: self.copyTranscriptionToClipboard,
textInsertionMode: self.textInsertionMode,
@@ -3468,6 +3478,9 @@ final class SettingsStore: ObservableObject {
if let skipSilentRecordingsEnabled = payload.skipSilentRecordingsEnabled {
self.skipSilentRecordingsEnabled = skipSilentRecordingsEnabled
}
+ if let meetingVPIOMicCapture = payload.meetingVPIOMicCapture {
+ self.meetingVPIOMicCapture = meetingVPIOMicCapture
+ }
self.enableAIStreaming = payload.enableAIStreaming
self.copyTranscriptionToClipboard = payload.copyTranscriptionToClipboard
self.textInsertionMode = payload.textInsertionMode
@@ -5482,6 +5495,7 @@ private extension SettingsStore {
static let experimentalParakeetUnifiedFinalEnabled = "ExperimentalParakeetUnifiedFinalEnabled"
static let showHistoryPerformanceMetrics = "ShowHistoryPerformanceMetrics"
static let skipSilentRecordingsEnabled = "SkipSilentRecordingsEnabled"
+ static let meetingVPIOMicCapture = "MeetingVPIOMicCapture"
static let enableAIStreaming = "EnableAIStreaming"
static let copyTranscriptionToClipboard = "CopyTranscriptionToClipboard"
static let textInsertionMode = "TextInsertionMode"
diff --git a/Sources/Fluid/Services/AudioDeviceService.swift b/Sources/Fluid/Services/AudioDeviceService.swift
index 206247b6..5224e840 100644
--- a/Sources/Fluid/Services/AudioDeviceService.swift
+++ b/Sources/Fluid/Services/AudioDeviceService.swift
@@ -363,6 +363,23 @@ nonisolated enum AudioDevice {
return status == noErr ? value : nil
}
+ /// 'hdpn' — kAudioDevicePropertyDataSource's headphones value, output scope.
+ private static let headphonesDataSource: UInt32 = 0x6864_706E
+
+ static func outputDataSourceIsHeadphones(_ deviceID: AudioObjectID) -> Bool {
+ var address = AudioObjectPropertyAddress(
+ mSelector: kAudioDevicePropertyDataSource,
+ mScope: kAudioObjectPropertyScopeOutput,
+ mElement: kAudioObjectPropertyElementMain
+ )
+ guard AudioObjectHasProperty(deviceID, &address) else { return true }
+ var dataSource: UInt32 = 0
+ var size = UInt32(MemoryLayout<UInt32>.size)
+ let status = AudioObjectGetPropertyData(deviceID, &address, 0, nil, &size, &dataSource)
+ guard status == noErr else { return true }
+ return dataSource == Self.headphonesDataSource
+ }
+
private static func hasChannels(_ devId: AudioObjectID, scope: AudioObjectPropertyScope) -> Bool {
var address = AudioObjectPropertyAddress(
mSelector: kAudioDevicePropertyStreamConfiguration,
diff --git a/Sources/Fluid/Services/Meeting/MeetingAudioChunkWriter.swift b/Sources/Fluid/Services/Meeting/MeetingAudioChunkWriter.swift
index 93e4e2e4..9af85246 100644
--- a/Sources/Fluid/Services/Meeting/MeetingAudioChunkWriter.swift
+++ b/Sources/Fluid/Services/Meeting/MeetingAudioChunkWriter.swift
@@ -155,6 +155,21 @@ final nonisolated class MeetingAudioChunkWriter: @unchecked Sendable {
}
}
+ /// Unlike the `try?` writes elsewhere here, a persist failure propagates to the caller.
+ func updateTrackMetadata(_ mutate: @escaping (inout MeetingAudioTrack) -> Void) async throws {
+ try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<Void, Error>) in
+ self.queue.async { [self] in
+ mutate(&self.track)
+ do {
+ try self.persistTrackManifest()
+ continuation.resume()
+ } catch {
+ continuation.resume(throwing: error)
+ }
+ }
+ }
+ }
+
func snapshot() async -> MeetingAudioTrack {
await withCheckedContinuation { continuation in
self.queue.async { [self] in
diff --git a/Sources/Fluid/Services/Meeting/MeetingCaptureEngine.swift b/Sources/Fluid/Services/Meeting/MeetingCaptureEngine.swift
index fa5f0fe0..e95d3338 100644
--- a/Sources/Fluid/Services/Meeting/MeetingCaptureEngine.swift
+++ b/Sources/Fluid/Services/Meeting/MeetingCaptureEngine.swift
@@ -1,5 +1,6 @@
import AppKit
@preconcurrency import AVFoundation
+import CoreAudio
import CoreMedia
import Foundation
import IOKit.pwr_mgt
@@ -65,14 +66,42 @@ actor MeetingCaptureEngine: MeetingCaptureControlling {
let applicationWriter = writersByKind[.applicationAudio],
let microphoneWriter = writersByKind[.microphone]
else { throw MeetingCaptureError.applicationNotSelected }
- runtime = try await ScreenCaptureMeetingRuntime.make(
- application: application,
+
+ let flag = SettingsStore.shared.meetingVPIOMicCapture
+ let decision = MeetingCapturePathDecider.decide(
+ flag: flag,
+ mode: configuration.mode,
microphone: configuration.microphone,
- applicationWriter: applicationWriter,
- microphoneWriter: microphoneWriter,
- eventHandler: eventHandler,
- liveAudioHandler: liveAudioHandler
+ outputRoute: Self.currentOutputRouteSnapshot()
)
+ switch decision {
+ case let .screenCaptureKit(reason):
+ if flag {
+ DebugLogger.shared.log(
+ "Meeting voice-processing capture declined: \(reason)",
+ source: "MeetingCaptureEngine"
+ )
+ eventHandler(.interrupted(kind: .voiceProcessingDeclined, trackID: nil, detail: reason))
+ }
+ runtime = try await ScreenCaptureMeetingRuntime.make(
+ application: application,
+ microphone: configuration.microphone,
+ includeMicrophone: true,
+ applicationWriter: applicationWriter,
+ microphoneWriter: microphoneWriter,
+ eventHandler: eventHandler,
+ liveAudioHandler: liveAudioHandler
+ )
+ case .voiceProcessing:
+ runtime = try await VoiceProcessingMeetingRuntime.make(
+ application: application,
+ microphone: configuration.microphone,
+ applicationWriter: applicationWriter,
+ microphoneWriter: microphoneWriter,
+ eventHandler: eventHandler,
+ liveAudioHandler: liveAudioHandler
+ )
+ }
case .inRoom:
guard let microphoneWriter = writersByKind[.microphone] else {
throw MeetingCaptureError.microphoneUnavailable
@@ -105,8 +134,17 @@ actor MeetingCaptureEngine: MeetingCaptureControlling {
runtime: runtime,
writers: writers
)
+ // Re-snapshot: a VPIO commit during start() promotes provenance on the writer's own track.
+ let settledTracks = await withTaskGroup(of: MeetingAudioTrack.self, returning: [MeetingAudioTrack].self) { group in
+ for writer in writers {
+ group.addTask { await writer.snapshot() }
+ }
+ var result: [MeetingAudioTrack] = []
+ for await track in group { result.append(track) }
+ return result.sorted { $0.kind.rawValue < $1.kind.rawValue }
+ }
return MeetingCaptureStartResult(
- tracks: tracks,
+ tracks: settledTracks,
firstPresentationTime: nil,
captureScope: runtime.captureScope
)
@@ -209,7 +247,8 @@ actor MeetingCaptureEngine: MeetingCaptureControlling {
format: nil,
timebase: session.timebase,
health: .waiting,
- chunks: []
+ chunks: [],
+ captureMethod: .screenCaptureKit
))
}
tracks.append(MeetingAudioTrack(
@@ -220,7 +259,8 @@ actor MeetingCaptureEngine: MeetingCaptureControlling {
format: nil,
timebase: session.timebase,
health: .waiting,
- chunks: []
+ chunks: [],
+ captureMethod: configuration.mode == .onlineCall ? .screenCaptureKit : .avCaptureSession
))
return tracks
}
@@ -241,6 +281,18 @@ actor MeetingCaptureEngine: MeetingCaptureControlling {
}
}
+ static func currentOutputRouteSnapshot() -> MeetingOutputRouteSnapshot {
+ guard let device = AudioDevice.getDefaultOutputDevice() else {
+ return MeetingOutputRouteSnapshot(deviceExists: false, isBluetooth: false, isBuiltIn: false, isHeadphonesDataSource: false)
+ }
+ return MeetingOutputRouteSnapshot(
+ deviceExists: true,
+ isBluetooth: device.isBluetooth,
+ isBuiltIn: device.isBuiltIn,
+ isHeadphonesDataSource: AudioDevice.outputDataSourceIsHeadphones(device.id)
+ )
+ }
+
private nonisolated static func preflightStorage(at directory: URL) throws {
let values = try directory.resourceValues(forKeys: [.volumeAvailableCapacityForImportantUsageKey])
if let capacity = values.volumeAvailableCapacityForImportantUsage, capacity < 512 * 1024 * 1024 {
@@ -249,7 +301,7 @@ actor MeetingCaptureEngine: MeetingCaptureControlling {
}
}
-private nonisolated protocol MeetingCaptureRuntime: AnyObject, Sendable {
+nonisolated protocol MeetingCaptureRuntime: AnyObject, Sendable {
/// The ScreenCaptureKit scope actually in effect. `nil` for runtimes with no SCK stream.
var captureScope: MeetingCaptureScope? { get }
func start() async throws
@@ -308,6 +360,8 @@ private final nonisolated class ScreenCaptureMeetingRuntime: NSObject, MeetingCa
private let application: MeetingApplicationIdentity
private let microphone: MeetingMicrophoneIdentity
+ /// Immutable for the runtime's lifetime: a mid-run flag flip never drops/adds the mic.
+ private let includeMicrophone: Bool
private let applicationWriter: MeetingAudioChunkWriter
private let microphoneWriter: MeetingAudioChunkWriter
private let eventHandler: @Sendable (MeetingCaptureEvent) -> Void
@@ -330,6 +384,7 @@ private final nonisolated class ScreenCaptureMeetingRuntime: NSObject, MeetingCa
scope: MeetingCaptureScope,
application: MeetingApplicationIdentity,
microphone: MeetingMicrophoneIdentity,
+ includeMicrophone: Bool,
applicationWriter: MeetingAudioChunkWriter,
microphoneWriter: MeetingAudioChunkWriter,
eventHandler: @escaping @Sendable (MeetingCaptureEvent) -> Void,
@@ -339,6 +394,7 @@ private final nonisolated class ScreenCaptureMeetingRuntime: NSObject, MeetingCa
self.scope = scope
self.application = application
self.microphone = microphone
+ self.includeMicrophone = includeMicrophone
self.applicationWriter = applicationWriter
self.microphoneWriter = microphoneWriter
self.eventHandler = eventHandler
@@ -349,17 +405,19 @@ private final nonisolated class ScreenCaptureMeetingRuntime: NSObject, MeetingCa
static func make(
application: MeetingApplicationIdentity,
microphone: MeetingMicrophoneIdentity,
+ includeMicrophone: Bool = true,
applicationWriter: MeetingAudioChunkWriter,
microphoneWriter: MeetingAudioChunkWriter,
eventHandler: @escaping @Sendable (MeetingCaptureEvent) -> Void,
liveAudioHandler: (@Sendable (MeetingAudioTrackKind, CMSampleBuffer) -> Void)?
) async throws -> ScreenCaptureMeetingRuntime {
- let built = try await Self.buildStream(application: application, microphone: microphone)
+ let built = try await Self.buildStream(application: application, microphone: microphone, includeMicrophone: includeMicrophone)
let runtime = ScreenCaptureMeetingRuntime(
stream: built.stream,
scope: built.scope,
application: application,
microphone: microphone,
+ includeMicrophone: includeMicrophone,
applicationWriter: applicationWriter,
microphoneWriter: microphoneWriter,
eventHandler: eventHandler,
@@ -375,7 +433,8 @@ private final nonisolated class ScreenCaptureMeetingRuntime: NSObject, MeetingCa
/// initial `make` and for every rebuild attempt after an unexpected stream stop.
private static func buildStream(
application: MeetingApplicationIdentity,
- microphone: MeetingMicrophoneIdentity
+ microphone: MeetingMicrophoneIdentity,
+ includeMicrophone: Bool
) async throws -> BuiltStream {
let content: SCShareableContent
do {
@@ -413,12 +472,7 @@ private final nonisolated class ScreenCaptureMeetingRuntime: NSObject, MeetingCa
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
- configuration.captureMicrophone = true
- configuration.microphoneCaptureDeviceID = microphone.captureDeviceID
+ MeetingScreenCaptureAudioSettings.apply(to: configuration, microphone: microphone, includeMicrophone: includeMicrophone)
let delegateProxy = ScreenCaptureRuntimeDelegateProxy()
let stream = SCStream(filter: filter, configuration: configuration, delegate: delegateProxy)
@@ -457,6 +511,7 @@ private final nonisolated class ScreenCaptureMeetingRuntime: NSObject, MeetingCa
qos: .userInteractive
)
)
+ guard self.includeMicrophone else { return }
try stream.addStreamOutput(
self,
type: .microphone,
@@ -554,7 +609,9 @@ private final nonisolated class ScreenCaptureMeetingRuntime: NSObject, MeetingCa
if self.stateLock.withLock({ self.stopping }) { self.finishRebuilding(); return }
do {
- let built = try await Self.buildStream(application: self.application, microphone: self.microphone)
+ let built = try await Self.buildStream(
+ application: self.application, microphone: self.microphone, includeMicrophone: self.includeMicrophone
+ )
if self.stateLock.withLock({ self.stopping }) { self.finishRebuilding(); return }
built.delegateProxy.owner = self
try self.attachOutputs(to: built.stream)
@@ -888,3 +945,638 @@ private extension CGRect {
return max(0, self.width) * max(0, self.height)
}
}
+
+nonisolated enum MeetingCapturePathDecision: Sendable, Equatable {
+ case voiceProcessing
+ case screenCaptureKit(reason: String)
+}
+
+/// Output-route facts the decision needs, as a plain value so `decide` is unit-testable headless.
+nonisolated struct MeetingOutputRouteSnapshot: Sendable, Equatable {
+ var deviceExists: Bool
+ var isBluetooth: Bool
+ var isBuiltIn: Bool
+ var isHeadphonesDataSource: Bool
+}
+
+/// Pure decision table. Role is deliberately NOT consulted — `.unknown` everywhere on this branch.
+nonisolated enum MeetingCapturePathDecider {
+ static func decide(
+ flag: Bool,
+ mode: MeetingCaptureMode,
+ microphone: MeetingMicrophoneIdentity,
+ outputRoute: MeetingOutputRouteSnapshot
+ ) -> MeetingCapturePathDecision {
+ guard flag else {
+ return .screenCaptureKit(reason: "Voice-processing meeting capture is disabled in Settings.")
+ }
+ guard mode == .onlineCall else {
+ return .screenCaptureKit(reason: "Voice-processing capture only applies to online-call recordings.")
+ }
+ guard let coreAudioUID = microphone.coreAudioUID, !coreAudioUID.isEmpty else {
+ return .screenCaptureKit(reason: "The selected microphone has no CoreAudio device UID.")
+ }
+ if let reason = Self.outputRouteDeclineReason(outputRoute) {
+ return .screenCaptureKit(reason: reason)
+ }
+ return .voiceProcessing
+ }
+
+ /// Shared with the mid-session output-route listener so the two never diverge.
+ static func outputRouteDeclineReason(_ outputRoute: MeetingOutputRouteSnapshot) -> String? {
+ guard outputRoute.deviceExists else { return "No default output device is available." }
+ guard !outputRoute.isBluetooth else { return "The output device is Bluetooth." }
+ guard outputRoute.isBuiltIn else { return "The output device is not the built-in speakers." }
+ guard !outputRoute.isHeadphonesDataSource else { return "The output route is headphones." }
+ return nil
+ }
+}
+
+nonisolated enum MeetingScreenCaptureAudioSettings {
+ static func apply(
+ to configuration: SCStreamConfiguration,
+ microphone: MeetingMicrophoneIdentity,
+ includeMicrophone: Bool
+ ) {
+ configuration.capturesAudio = true
+ configuration.sampleRate = 48_000
+ configuration.channelCount = 2
+ configuration.excludesCurrentProcessAudio = true
+ configuration.captureMicrophone = includeMicrophone
+ if includeMicrophone {
+ configuration.microphoneCaptureDeviceID = microphone.captureDeviceID
+ }
+ }
+}
+
+/// Buffers mic audio pre-commit; ring-cap exhaustion ABORTS rather than evicting-and-committing.
+final nonisolated class MeetingVoiceProcessingCommitGate: @unchecked Sendable {
+ enum SampleOutcome { case buffered, passthrough, aborted }
+
+ private enum State { case buffering, flushing, committed, aborted }
+
+ static let defaultRingCapBytes = 1_048_576 // ~5s of mono float32 @ 48kHz
+
+ private let lock = NSLock()
+ private var state: State = .buffering
+ private var ring: [CMSampleBuffer] = []
+ private var ringBytes = 0
+ private let ringCapBytes: Int
+
+ init(ringCapBytes: Int = MeetingVoiceProcessingCommitGate.defaultRingCapBytes) {
+ self.ringCapBytes = ringCapBytes
+ }
+
+ func offer(_ sampleBuffer: CMSampleBuffer) -> SampleOutcome {
+ self.lock.lock()
+ defer { self.lock.unlock() }
+ switch self.state {
+ case .committed: return .passthrough
+ case .aborted: return .aborted
+ case .flushing:
+ // Uncapped: aborting mid-flush would strand already-promoted provenance.
+ self.ring.append(sampleBuffer)
+ return .buffered
+ case .buffering:
+ // GetTotalSampleSize returns 0 without a per-sample size table; use the block buffer.
+ let size = CMSampleBufferGetDataBuffer(sampleBuffer).map(CMBlockBufferGetDataLength) ?? 0
+ guard self.ringBytes + size <= self.ringCapBytes else {
+ self.state = .aborted
+ self.ring.removeAll()
+ self.ringBytes = 0
+ return .aborted
+ }
+ self.ring.append(sampleBuffer)
+ self.ringBytes += size
+ return .buffered
+ }
+ }
+
+ @discardableResult
+ func offerTerminalEventPreCommit() -> Bool {
+ self.lock.lock()
+ defer { self.lock.unlock() }
+ guard self.state == .buffering else { return false }
+ self.state = .aborted
+ self.ring.removeAll()
+ self.ringBytes = 0
+ return true
+ }
+
+ /// Point of no return: after this, terminal events and abort() are no-ops.
+ func beginCommitFlush() -> [CMSampleBuffer]? {
+ self.lock.lock()
+ defer { self.lock.unlock() }
+ guard self.state == .buffering else { return nil }
+ self.state = .flushing
+ return self.takeRing()
+ }
+
+ /// nil means the ring drained and passthrough is live; else the next batch to flush in order.
+ /// Serialized handoff: passthrough never starts while older buffers wait, so PTS order holds.
+ func continueCommitFlush() -> [CMSampleBuffer]? {
+ self.lock.lock()
+ defer { self.lock.unlock() }
+ guard self.state == .flushing else { return nil }
+ if self.ring.isEmpty {
+ self.state = .committed
+ return nil
+ }
+ return self.takeRing()
+ }
+
+ private func takeRing() -> [CMSampleBuffer] {
+ let taken = self.ring
+ self.ring.removeAll()
+ self.ringBytes = 0
+ return taken
+ }
+
+ func abort() {
+ self.lock.lock()
+ defer { self.lock.unlock() }
+ guard self.state == .buffering || self.state == .aborted else { return }
+ self.state = .aborted
+ self.ring.removeAll()
+ self.ringBytes = 0
+ }
+
+ var isCommitted: Bool { self.lock.withLock { self.state == .committed } }
+}
+
+/// Emitted-only progress: dropped/failed buffers deliver no audio, so a dropped run trips this too.
+nonisolated enum MeetingVoiceProcessingWatchdog {
+ static let stalledThresholdSeconds: Double = 10
+
+ static func isStalled(secondsSinceLastEmittedBuffer: Double) -> Bool {
+ secondsSinceLastEmittedBuffer >= Self.stalledThresholdSeconds
+ }
+}
+
+/// Re-evaluates the output-route predicate on default-output-device or data-source change.
+/// Registration failure at init means VPIO is not viable — fail closed. Re-registers everything on
+/// `kAudioHardwarePropertyServiceRestarted`, since CoreAudio discards all prior listeners on reset.
+private final nonisolated class MeetingOutputRouteListener: @unchecked Sendable {
+ private let onViolation: @Sendable () -> Void
+ private let lock = NSLock()
+ private var defaultOutputToken: AudioObjectPropertyListenerBlock?
+ private var serviceRestartedToken: AudioObjectPropertyListenerBlock?
+ private var dataSourceToken: AudioObjectPropertyListenerBlock?
+ private var dataSourceDeviceID: AudioObjectID?
+
+ init?(onViolation: @escaping @Sendable () -> Void) {
+ self.onViolation = onViolation
+ guard self.register() else { return nil }
+ }
+
+ deinit {
+ self.unregister()
+ }
+
+ private func predicateFails() -> Bool {
+ MeetingCapturePathDecider.outputRouteDeclineReason(MeetingCaptureEngine.currentOutputRouteSnapshot()) != nil
+ }
+
+ private func reevaluate() {
+ if self.predicateFails() { self.onViolation() }
+ }
+
+ @discardableResult
+ private func register() -> Bool {
+ let sys = AudioObjectID(kAudioObjectSystemObject)
+ var defaultOutAddr = AudioObjectPropertyAddress(
+ mSelector: kAudioHardwarePropertyDefaultOutputDevice,
+ mScope: kAudioObjectPropertyScopeGlobal,
+ mElement: kAudioObjectPropertyElementMain
+ )
+ var restartedAddr = AudioObjectPropertyAddress(
+ mSelector: kAudioHardwarePropertyServiceRestarted,
+ mScope: kAudioObjectPropertyScopeGlobal,
+ mElement: kAudioObjectPropertyElementMain
+ )
+ let defaultOutToken: AudioObjectPropertyListenerBlock = { [weak self] _, _ in
+ self?.reattachDataSourceListener()
+ self?.reevaluate()
+ }
+ let restartedToken: AudioObjectPropertyListenerBlock = { [weak self] _, _ in
+ self?.reregisterAfterServiceRestart()
+ }
+ guard AudioObjectAddPropertyListenerBlock(sys, &defaultOutAddr, DispatchQueue.main, defaultOutToken) == noErr else {
+ return false
+ }
+ guard AudioObjectAddPropertyListenerBlock(sys, &restartedAddr, DispatchQueue.main, restartedToken) == noErr else {
+ _ = AudioObjectRemovePropertyListenerBlock(sys, &defaultOutAddr, DispatchQueue.main, defaultOutToken)
+ return false
+ }
+ self.defaultOutputToken = defaultOutToken
+ self.serviceRestartedToken = restartedToken
+ guard self.attachDataSourceListener() else {
+ self.unregister()
+ return false
+ }
+ return true
+ }
+
+ private func attachDataSourceListener() -> Bool {
+ guard let device = AudioDevice.getDefaultOutputDevice() else { return false }
+ var address = AudioObjectPropertyAddress(
+ mSelector: kAudioDevicePropertyDataSource,
+ mScope: kAudioObjectPropertyScopeOutput,
+ mElement: kAudioObjectPropertyElementMain
+ )
+ let token: AudioObjectPropertyListenerBlock = { [weak self] _, _ in self?.reevaluate() }
+ guard AudioObjectAddPropertyListenerBlock(device.id, &address, DispatchQueue.main, token) == noErr else { return false }
+ self.dataSourceToken = token
+ self.dataSourceDeviceID = device.id
+ return true
+ }
+
+ private func detachDataSourceListener() {
+ guard let deviceID = self.dataSourceDeviceID, let token = self.dataSourceToken else { return }
+ var address = AudioObjectPropertyAddress(
+ mSelector: kAudioDevicePropertyDataSource,
+ mScope: kAudioObjectPropertyScopeOutput,
+ mElement: kAudioObjectPropertyElementMain
+ )
+ _ = AudioObjectRemovePropertyListenerBlock(deviceID, &address, DispatchQueue.main, token)
+ self.dataSourceToken = nil
+ self.dataSourceDeviceID = nil
+ }
+
+ private func reattachDataSourceListener() {
+ self.detachDataSourceListener()
+ _ = self.attachDataSourceListener()
+ }
+
+ private func reregisterAfterServiceRestart() {
+ self.unregister()
+ guard self.register() else {
+ self.onViolation()
+ return
+ }
+ self.reevaluate()
+ }
+
+ private func unregister() {
+ let sys = AudioObjectID(kAudioObjectSystemObject)
+ var defaultOutAddr = AudioObjectPropertyAddress(
+ mSelector: kAudioHardwarePropertyDefaultOutputDevice,
+ mScope: kAudioObjectPropertyScopeGlobal,
+ mElement: kAudioObjectPropertyElementMain
+ )
+ var restartedAddr = AudioObjectPropertyAddress(
+ mSelector: kAudioHardwarePropertyServiceRestarted,
+ mScope: kAudioObjectPropertyScopeGlobal,
+ mElement: kAudioObjectPropertyElementMain
+ )
+ if let token = self.defaultOutputToken {
+ _ = AudioObjectRemovePropertyListenerBlock(sys, &defaultOutAddr, DispatchQueue.main, token)
+ }
+ if let token = self.serviceRestartedToken {
+ _ = AudioObjectRemovePropertyListenerBlock(sys, &restartedAddr, DispatchQueue.main, token)
+ }
+ self.defaultOutputToken = nil
+ self.serviceRestartedToken = nil
+ self.detachDataSourceListener()
+ }
+}
+
+nonisolated enum MeetingVoiceProcessingDriftSnapshot {
+ static func elapsedValidHostSeconds(_ stats: MeetingMicrophoneCaptureStats.Snapshot) -> Double {
+ guard let first = stats.firstValidHostSeconds, let last = stats.lastValidHostSeconds, last > first else { return 0 }
+ return last - first
+ }
+
+ /// Any re-anchor/step/config-change/dropped-run invalidates the single-epoch linear model.
+ static func isEligible(_ stats: MeetingMicrophoneCaptureStats.Snapshot) -> Bool {
+ stats.resyncCount == 0
+ && stats.resyncClampCount == 0
+ && stats.divergenceStepEventCount == 0
+ && stats.configurationChangeEvents == 0
+ && stats.droppedPostCapCount == 0
+ }
+}
+
+/// Owns a VPIO `MeetingMicrophoneCapture` plus an app-audio-only `ScreenCaptureMeetingRuntime`.
+/// On any failure before commit, aborts cleanly and falls back to today's app+mic SCStream path
+/// using the SAME writers — the fallback never sees a byte or event from the aborted attempt.
+private final nonisolated class VoiceProcessingMeetingRuntime: MeetingCaptureRuntime, @unchecked Sendable {
+ private static let totalStartDeadlineSeconds: Double = 10
+ private static let firstBufferDeadlineSeconds: Double = 2
+
+ private let application: MeetingApplicationIdentity
+ private let microphone: MeetingMicrophoneIdentity
+ private let applicationWriter: MeetingAudioChunkWriter
+ private let microphoneWriter: MeetingAudioChunkWriter
+ private let eventHandler: @Sendable (MeetingCaptureEvent) -> Void
+ private let liveAudioHandler: (@Sendable (MeetingAudioTrackKind, CMSampleBuffer) -> Void)?
+ private let micCapture = MeetingMicrophoneCapture()
+ private let gate = MeetingVoiceProcessingCommitGate()
+ private let stateLock = NSLock()
+
+ private var appOnlyRuntime: ScreenCaptureMeetingRuntime?
+ private var fallbackRuntime: ScreenCaptureMeetingRuntime?
+ private var promoted = false
+ private var committed = false
+ private var interrupted = false
+ private var watchdogTask: Task<Void, Never>?
+ private var outputRouteListener: MeetingOutputRouteListener?
+
+ var captureScope: MeetingCaptureScope? {
+ if let fallback = self.stateLock.withLock({ self.fallbackRuntime }) { return fallback.captureScope }
+ return self.stateLock.withLock { self.appOnlyRuntime?.captureScope }
+ }
+
+ private init(
+ application: MeetingApplicationIdentity,
+ microphone: MeetingMicrophoneIdentity,
+ applicationWriter: MeetingAudioChunkWriter,
+ microphoneWriter: MeetingAudioChunkWriter,
+ eventHandler: @escaping @Sendable (MeetingCaptureEvent) -> Void,
+ liveAudioHandler: (@Sendable (MeetingAudioTrackKind, CMSampleBuffer) -> Void)?
+ ) {
+ self.application = application
+ self.microphone = microphone
+ self.applicationWriter = applicationWriter
+ self.microphoneWriter = microphoneWriter
+ self.eventHandler = eventHandler
+ self.liveAudioHandler = liveAudioHandler
+ }
+
+ static func make(
+ application: MeetingApplicationIdentity,
+ microphone: MeetingMicrophoneIdentity,
+ applicationWriter: MeetingAudioChunkWriter,
+ microphoneWriter: MeetingAudioChunkWriter,
+ eventHandler: @escaping @Sendable (MeetingCaptureEvent) -> Void,
+ liveAudioHandler: (@Sendable (MeetingAudioTrackKind, CMSampleBuffer) -> Void)?
+ ) async throws -> VoiceProcessingMeetingRuntime {
+ VoiceProcessingMeetingRuntime(
+ application: application,
+ microphone: microphone,
+ applicationWriter: applicationWriter,
+ microphoneWriter: microphoneWriter,
+ eventHandler: eventHandler,
+ liveAudioHandler: liveAudioHandler
+ )
+ }
+
+ func start() async throws {
+ do {
+ try await Self.withDeadline(seconds: Self.totalStartDeadlineSeconds) { [self] in
+ try await self.runStartSequence()
+ }
+ } catch {
+ // Deadline expiry during the fallback leg fails cleanly; never begin a further attempt.
+ await self.cleanupAfterStartFailure()
+ throw error
+ }
+ }
+
+ private func runStartSequence() async throws {
+ do {
+ try await self.attemptVoiceProcessingStart()
+ } catch {
+ if error is CancellationError { throw error }
+ if self.stateLock.withLock({ self.promoted }) { throw error }
+ self.gate.abort()
+ self.outputRouteListener = nil
+ await self.micCapture.stop()
+ await self.stopAppOnlyIfStarted()
+ let fallback = try await ScreenCaptureMeetingRuntime.make(
+ application: self.application,
+ microphone: self.microphone,
+ includeMicrophone: true,
+ applicationWriter: self.applicationWriter,
+ microphoneWriter: self.microphoneWriter,
+ eventHandler: self.eventHandler,
+ liveAudioHandler: self.liveAudioHandler
+ )
+ // Assigned before start() so a cancelled/failed start can still be found and stopped.
+ self.stateLock.withLock { self.fallbackRuntime = fallback }
+ try await fallback.start()
+ }
+ }
+
+ private func attemptVoiceProcessingStart() async throws {
+ let microphoneWriter = self.microphoneWriter
+ let liveAudioHandler = self.liveAudioHandler
+ let gate = self.gate
+ let outcome = try await self.micCapture.start(
+ microphone: self.microphone,
+ onSample: { sample in
+ switch gate.offer(sample) {
+ case .passthrough:
+ microphoneWriter.enqueue(sample)
+ liveAudioHandler?(.microphone, sample)
+ case .buffered, .aborted:
+ break
+ }
+ },
+ onEvent: { [weak self] event in
+ self?.handleMicEvent(event)
+ }
+ )
+ if case .unavailable = outcome {
+ throw MeetingCaptureError.captureStartFailed("Voice-processing microphone capture was unavailable.")
+ }
+
+ guard await self.waitForBufferProgress(timeoutSeconds: Self.firstBufferDeadlineSeconds) else {
+ throw MeetingCaptureError.captureStartFailed("No microphone audio was captured within 2s.")
+ }
+
+ let appOnly = try await ScreenCaptureMeetingRuntime.make(
+ application: self.application,
+ microphone: self.microphone,
+ includeMicrophone: false,
+ applicationWriter: self.applicationWriter,
+ microphoneWriter: self.microphoneWriter,
+ eventHandler: self.eventHandler,
+ liveAudioHandler: self.liveAudioHandler
+ )
+ try await appOnly.start()
+ self.stateLock.withLock { self.appOnlyRuntime = appOnly }
+
+ self.outputRouteListener = MeetingOutputRouteListener { [weak self] in
+ self?.interrupt(detail: "Output switched to Bluetooth/headphones — voice-processing capture cannot continue.")
+ }
+ guard self.outputRouteListener != nil else {
+ throw MeetingCaptureError.captureStartFailed("Could not register the output-route listener.")
+ }
+
+ guard var batch = self.gate.beginCommitFlush() else {
+ throw MeetingCaptureError.captureStartFailed("Voice-processing commit gate aborted before commit.")
+ }
+ // Promote provenance BEFORE the gate flushes a single VPIO byte; after this point a failure
+ // must fail the start outright — falling back would mix provenance on promoted writers.
+ self.stateLock.withLock { self.promoted = true }
+ let settled = await self.micCapture.settledConfiguration()
+ try await self.microphoneWriter.updateTrackMetadata { track in
+ track.captureMethod = .voiceProcessing
+ track.voiceProcessingConfig = settled
+ }
+ while true {
+ await self.flushBatch(batch)
+ guard let next = self.gate.continueCommitFlush() else { break }
+ batch = next
+ }
+ self.stateLock.withLock { self.committed = true }
+ self.startWatchdog()
+ }
+
+ private func stopAppOnlyIfStarted() async {
+ if let appOnly = self.stateLock.withLock({ self.appOnlyRuntime }) {
+ try? await appOnly.stop()
+ self.stateLock.withLock { self.appOnlyRuntime = nil }
+ }
+ }
+
+ private func cleanupAfterStartFailure() async {
+ if let fallback = self.stateLock.withLock({ self.fallbackRuntime }) {
+ try? await fallback.stop()
+ }
+ await self.micCapture.stop()
+ await self.stopAppOnlyIfStarted()
+ }
+
+ /// Paced flush: the writer's pending budget is 24 slots, a full 5s ring is ~50 buffers.
+ private func flushBatch(_ samples: [CMSampleBuffer]) async {
+ for (index, sample) in samples.enumerated() {
+ self.microphoneWriter.enqueue(sample)
+ self.liveAudioHandler?(.microphone, sample)
+ if index % 4 == 3 {
+ try? await Task.sleep(nanoseconds: 5_000_000)
+ }
+ }
+ }
+
+ private func waitForBufferProgress(timeoutSeconds: Double) async -> Bool {
+ let baseline = await self.micCapture.statistics().buffersEmitted
+ let deadline = Date().addingTimeInterval(timeoutSeconds)
+ while Date() < deadline {
+ if await self.micCapture.statistics().buffersEmitted > baseline { return true }
+ try? await Task.sleep(nanoseconds: 50_000_000)
+ }
+ return false
+ }
+
+ private func startWatchdog() {
+ self.watchdogTask = Task { [weak self] in
+ guard let self else { return }
+ var lastCount = await self.micCapture.statistics().buffersEmitted
+ var lastProgress = Date()
+ while !Task.isCancelled {
+ try? await Task.sleep(nanoseconds: 1_000_000_000)
+ if Task.isCancelled { return }
+ let current = await self.micCapture.statistics()
+ if current.buffersEmitted != lastCount {
+ lastCount = current.buffersEmitted
+ lastProgress = Date()
+ continue
+ }
+ if MeetingVoiceProcessingWatchdog.isStalled(secondsSinceLastEmittedBuffer: Date().timeIntervalSince(lastProgress)) {
+ self.interrupt(detail: "No microphone audio emitted for 10s (drops=\(current.droppedPostCapCount), conversionFailures=\(current.conversionFailures)).")
+ return
+ }
+ }
+ }
+ }
+
+ /// Terminal pre-commit events abort the attempt; non-terminal ones are swallowed by the gate.
+ private func handleMicEvent(_ event: MeetingMicrophoneCaptureEvent) {
+ guard self.gate.isCommitted else {
+ switch event {
+ case .engineStopped:
+ self.gate.offerTerminalEventPreCommit()
+ case .defaultInputChanged:
+ if let requestedUID = self.microphone.coreAudioUID,
+ AudioDevice.getDefaultInputDevice()?.uid != requestedUID
+ {
+ self.gate.offerTerminalEventPreCommit()
+ }
+ case .configurationChanged, .overload:
+ break
+ }
+ return
+ }
+ switch event {
+ case .configurationChanged:
+ self.eventHandler(.interrupted(
+ kind: .voiceProcessingConfigurationChanged, trackID: nil,
+ detail: "Voice-processing engine configuration changed."
+ ))
+ Task { [weak self] in
+ guard let self else { return }
+ if await !self.waitForBufferProgress(timeoutSeconds: Self.firstBufferDeadlineSeconds) {
+ self.interrupt(detail: "No microphone audio resumed after a configuration change.")
+ }
+ }
+ case .defaultInputChanged:
+ guard let requestedUID = self.microphone.coreAudioUID else { return }
+ if AudioDevice.getDefaultInputDevice()?.uid != requestedUID {
+ self.interrupt(detail: "The default input device changed away from the requested microphone.")
+ }
+ case .overload:
+ self.eventHandler(.interrupted(kind: .voiceProcessingOverload, trackID: nil, detail: "Voice-processing microphone reported an overload."))
+ case .engineStopped:
+ self.interrupt(detail: "The voice-processing microphone engine stopped unexpectedly.")
+ }
+ }
+
+ private func interrupt(detail: String) {
+ let shouldEmit = self.stateLock.withLock { () -> Bool in
+ guard self.committed, !self.interrupted else { return false }
+ self.interrupted = true
+ return true
+ }
+ guard shouldEmit else { return }
+ self.eventHandler(.interrupted(kind: .captureStoppedUnexpectedly, trackID: nil, detail: detail))
+ }
+
+ func stop() async throws {
+ self.watchdogTask?.cancel()
+ self.watchdogTask = nil
+ self.outputRouteListener = nil
+
+ if let fallback = self.stateLock.withLock({ self.fallbackRuntime }) {
+ try await fallback.stop()
+ return
+ }
+ guard self.stateLock.withLock({ self.committed }) else {
+ self.gate.abort()
+ await self.micCapture.stop()
+ await self.stopAppOnlyIfStarted()
+ return
+ }
+
+ // Quiesce first: stats must not be snapshotted while the tap can still emit, and stop-time
+ // churn must not poison the drift record (capture.stop tears down observers before the tap).
+ await self.micCapture.stop()
+ let statsSnapshot = await self.micCapture.statistics()
+ let drift = MeetingClockDriftRecord(
+ cumulativeAbsorbedSeconds: statsSnapshot.cumulativeAbsorbedCorrectionSeconds,
+ elapsedValidHostSeconds: MeetingVoiceProcessingDriftSnapshot.elapsedValidHostSeconds(statsSnapshot),
+ eligible: MeetingVoiceProcessingDriftSnapshot.isEligible(statsSnapshot)
+ )
+ try await self.microphoneWriter.updateTrackMetadata { track in track.clockDrift = drift }
+
+ if let appOnly = self.stateLock.withLock({ self.appOnlyRuntime }) {
+ try await appOnly.stop()
+ }
+ }
+
+ private static func withDeadline<T>(seconds: Double, operation: @escaping @Sendable () async throws -> T) async throws -> T {
+ try await withThrowingTaskGroup(of: T.self) { group in
+ group.addTask { try await operation() }
+ group.addTask {
+ try await Task.sleep(nanoseconds: UInt64(seconds * 1_000_000_000))
+ throw MeetingCaptureError.captureStartFailed("Voice-processing capture start exceeded \(Int(seconds))s.")
+ }
+ defer { group.cancelAll() }
+ guard let result = try await group.next() else {
+ throw MeetingCaptureError.captureStartFailed("Voice-processing capture start produced no result.")
+ }
+ return result
+ }
+ }
+}
diff --git a/Sources/Fluid/Services/Meeting/MeetingMicrophoneCapture.swift b/Sources/Fluid/Services/Meeting/MeetingMicrophoneCapture.swift
index 642cff78..a5568e0e 100644
--- a/Sources/Fluid/Services/Meeting/MeetingMicrophoneCapture.swift
+++ b/Sources/Fluid/Services/Meeting/MeetingMicrophoneCapture.swift
@@ -27,6 +27,8 @@ nonisolated struct MeetingMicrophonePTSClock {
private(set) var divergenceStepEventCount = 0
private(set) var maxDivergenceStepSeconds: Double = 0
private(set) var resyncClampCount = 0
+ private(set) var firstValidHostSeconds: Double?
+ private(set) var lastValidHostSeconds: Double?
private var lastDivergenceSeconds: Double = 0
private var lastEmittedEnd: CMTime = .invalid
@@ -101,6 +103,8 @@ nonisolated struct MeetingMicrophonePTSClock {
let wasDropping = self.isDroppingInvalidRun
self.isDroppingInvalidRun = false
self.synthesizedRunFrames = 0
+ if self.firstValidHostSeconds == nil { self.firstValidHostSeconds = actualSeconds }
+ self.lastValidHostSeconds = actualSeconds
if self.anchorHostSeconds == nil || wasDropping {
// A backlogged invalid burst can synthesize more timeline than elapsed host time;
@@ -348,6 +352,8 @@ final class MeetingMicrophoneCaptureStats: @unchecked Sendable {
var divergenceStepEventCount = 0
var maxDivergenceStepSeconds: Double = 0
var resyncClampCount = 0
+ var firstValidHostSeconds: Double?
+ var lastValidHostSeconds: Double?
/// The Phase 1 gate's headline number: ≥99% valid hostTime over the run.
var validHostTimeFraction: Double {
@@ -500,6 +506,8 @@ private final class MeetingMicrophoneTapState: @unchecked Sendable {
stats.divergenceStepEventCount = clock.divergenceStepEventCount
stats.maxDivergenceStepSeconds = clock.maxDivergenceStepSeconds
stats.resyncClampCount = clock.resyncClampCount
+ stats.firstValidHostSeconds = clock.firstValidHostSeconds
+ stats.lastValidHostSeconds = clock.lastValidHostSeconds
}
self.onSample(sampleBuffer)
}
@@ -730,6 +738,7 @@ actor MeetingMicrophoneCapture {
func stop() async {
guard self.isRunning else { return }
self.isRunning = false
+ self.tearDownEventObservers() // first: stop-time churn must not poison a stats snapshot
self.generationBox.advance()
if let engine = self.engine {
@@ -738,7 +747,6 @@ actor MeetingMicrophoneCapture {
}
self.engine = nil
self.tapState = nil
- self.tearDownEventObservers()
}
func statistics() -> Stats {
diff --git a/Sources/Fluid/Services/Meeting/MeetingModels.swift b/Sources/Fluid/Services/Meeting/MeetingModels.swift
index 04edcdea..8078a6bc 100644
--- a/Sources/Fluid/Services/Meeting/MeetingModels.swift
+++ b/Sources/Fluid/Services/Meeting/MeetingModels.swift
@@ -51,6 +51,9 @@ nonisolated enum MeetingInterruptionKind: String, Codable, Sendable {
case captureStoppedUnexpectedly
case writerBackpressure
case writerFailure
+ case voiceProcessingDeclined
+ case voiceProcessingConfigurationChanged
+ case voiceProcessingOverload
}
nonisolated enum MeetingFailureDomain: String, Codable, Sendable {
@@ -303,7 +306,40 @@ nonisolated struct MeetingTrackHealth: Codable, Equatable, Sendable {
)
}
-nonisolated struct MeetingAudioTrack: Codable, Identifiable, Equatable, Sendable {
+nonisolated enum MeetingAudioTrackCaptureMethod: String, Codable, Sendable {
+ case screenCaptureKit
+ case avCaptureSession
+ case voiceProcessing
+}
+
+nonisolated struct MeetingClockDriftRecord: Codable, Equatable, Sendable {
+ var cumulativeAbsorbedSeconds: Double
+ var elapsedValidHostSeconds: Double
+ var eligible: Bool
+}
+
+/// Applied ONLY to emitted turn boundaries, never to raw `chunkOffset`. `k = 1 + cumulative/elapsed`:
+/// for a fast mic `cumulativeAbsorbedSeconds` is negative, so `k < 1` compresses the timeline.
+nonisolated enum MeetingMicrophoneDeDrift {
+ static let materialityThresholdSeconds: Double = 0.005
+ static let maxAbsolutePPM: Double = 100
+
+ static func correct(_ t: Double, track: MeetingAudioTrack, origin: Double) -> Double {
+ guard track.captureMethod == .voiceProcessing,
+ let drift = track.clockDrift, drift.eligible,
+ drift.elapsedValidHostSeconds > 0
+ else { return t }
+ let fraction = drift.cumulativeAbsorbedSeconds / drift.elapsedValidHostSeconds
+ guard abs(drift.cumulativeAbsorbedSeconds) > Self.materialityThresholdSeconds,
+ abs(fraction) * 1_000_000 < Self.maxAbsolutePPM,
+ let micFirstPTS = track.chunks.map(\.presentationStart.seconds).min()
+ else { return t }
+ let micFirstRelative = micFirstPTS - origin
+ return micFirstRelative + (t - micFirstRelative) * (1 + fraction)
+ }
+}
+
+nonisolated struct MeetingAudioTrack: Identifiable, Equatable, Sendable {
var id: MeetingAudioTrackID
var kind: MeetingAudioTrackKind
var sourceIdentifier: String
@@ -312,6 +348,74 @@ nonisolated struct MeetingAudioTrack: Codable, Identifiable, Equatable, Sendable
var timebase: MeetingTimebaseMetadata
var health: MeetingTrackHealth
var chunks: [MeetingAudioChunk]
+ var captureMethod: MeetingAudioTrackCaptureMethod? = nil
+ var voiceProcessingConfig: MeetingMicrophoneSettledConfig? = nil
+ var clockDrift: MeetingClockDriftRecord? = nil
+
+ init(
+ id: MeetingAudioTrackID,
+ kind: MeetingAudioTrackKind,
+ sourceIdentifier: String,
+ sourceDisplayName: String,
+ format: MeetingAudioFormat?,
+ timebase: MeetingTimebaseMetadata,
+ health: MeetingTrackHealth,
+ chunks: [MeetingAudioChunk],
+ captureMethod: MeetingAudioTrackCaptureMethod? = nil,
+ voiceProcessingConfig: MeetingMicrophoneSettledConfig? = nil,
+ clockDrift: MeetingClockDriftRecord? = nil
+ ) {
+ self.id = id
+ self.kind = kind
+ self.sourceIdentifier = sourceIdentifier
+ self.sourceDisplayName = sourceDisplayName
+ self.format = format
+ self.timebase = timebase
+ self.health = health
+ self.chunks = chunks
+ self.captureMethod = captureMethod
+ self.voiceProcessingConfig = voiceProcessingConfig
+ self.clockDrift = clockDrift
+ }
+}
+
+extension MeetingAudioTrack: Codable {
+ private enum CodingKeys: String, CodingKey {
+ case id, kind, sourceIdentifier, sourceDisplayName, format, timebase, health, chunks
+ case captureMethod, voiceProcessingConfig, clockDrift
+ }
+
+ init(from decoder: Decoder) throws {
+ let container = try decoder.container(keyedBy: CodingKeys.self)
+ self.id = try container.decode(MeetingAudioTrackID.self, forKey: .id)
+ self.kind = try container.decode(MeetingAudioTrackKind.self, forKey: .kind)
+ self.sourceIdentifier = try container.decode(String.self, forKey: .sourceIdentifier)
+ self.sourceDisplayName = try container.decode(String.self, forKey: .sourceDisplayName)
+ self.format = try container.decodeIfPresent(MeetingAudioFormat.self, forKey: .format)
+ self.timebase = try container.decode(MeetingTimebaseMetadata.self, forKey: .timebase)
+ self.health = try container.decode(MeetingTrackHealth.self, forKey: .health)
+ self.chunks = try container.decode([MeetingAudioChunk].self, forKey: .chunks)
+ // Tolerant: an unrecognized raw value decodes to nil instead of failing the whole session.
+ let captureMethodRaw = try container.decodeIfPresent(String.self, forKey: .captureMethod)
+ self.captureMethod = captureMethodRaw.flatMap(MeetingAudioTrackCaptureMethod.init(rawValue:))
+ self.voiceProcessingConfig = try container.decodeIfPresent(MeetingMicrophoneSettledConfig.self, forKey: .voiceProcessingConfig)
+ self.clockDrift = try container.decodeIfPresent(MeetingClockDriftRecord.self, forKey: .clockDrift)
+ }
+
+ func encode(to encoder: Encoder) throws {
+ var container = encoder.container(keyedBy: CodingKeys.self)
+ try container.encode(self.id, forKey: .id)
+ try container.encode(self.kind, forKey: .kind)
+ try container.encode(self.sourceIdentifier, forKey: .sourceIdentifier)
+ try container.encode(self.sourceDisplayName, forKey: .sourceDisplayName)
+ try container.encodeIfPresent(self.format, forKey: .format)
+ try container.encode(self.timebase, forKey: .timebase)
+ try container.encode(self.health, forKey: .health)
+ try container.encode(self.chunks, forKey: .chunks)
+ try container.encodeIfPresent(self.captureMethod, forKey: .captureMethod)
+ try container.encodeIfPresent(self.voiceProcessingConfig, forKey: .voiceProcessingConfig)
+ try container.encodeIfPresent(self.clockDrift, forKey: .clockDrift)
+ }
}
nonisolated struct MeetingSessionEvent: Codable, Identifiable, Equatable, Sendable {
@@ -799,6 +903,8 @@ nonisolated struct MeetingProcessingResult: Sendable {
/// chunks (origin depends on all chunks), but deliberately NOT `embeddingIndexByTrack`: only the
/// microphone pass reads `embeddingIndexByTrack[.microphone]`, so a resumed run keeps the
/// embeddings already stored on `MeetingSessionSpeaker` instead of rebuilding that index.
+/// No pipelineVersion bump for batch de-drift: this checkpoint snapshots only the application-audio
+/// pass; the mic pass re-derives its correction deterministically from `clockDrift` every run.
nonisolated struct MeetingProcessingCheckpoint: Codable, Equatable, Sendable {
static let currentVersion = 1
diff --git a/Sources/Fluid/Services/Meeting/MeetingProcessingPipeline.swift b/Sources/Fluid/Services/Meeting/MeetingProcessingPipeline.swift
index a617b5b7..4f2631b7 100644
--- a/Sources/Fluid/Services/Meeting/MeetingProcessingPipeline.swift
+++ b/Sources/Fluid/Services/Meeting/MeetingProcessingPipeline.swift
@@ -1451,8 +1451,9 @@ final class MeetingProcessingPipeline: MeetingProcessingControlling {
)
for (offset, element) in transcribedTurns.enumerated() {
let (index, turn, text) = element
- let start = chunkOffset + turn.startSeconds
- let end = chunkOffset + turn.endSeconds
+ // De-drift applies ONLY here — echo verdicts below keep consuming raw chunkOffset.
+ let start = MeetingMicrophoneDeDrift.correct(chunkOffset + turn.startSeconds, track: track, origin: context.origin)
+ let end = MeetingMicrophoneDeDrift.correct(chunkOffset + turn.endSeconds, track: track, origin: context.origin)
let overlapsRemote = remoteSpeech.contains {
min(end, $0.end) - max(start, $0.start) > 0.15
}
diff --git a/Sources/Fluid/UI/SettingsView.swift b/Sources/Fluid/UI/SettingsView.swift
index 49ccd857..3afe6074 100644
--- a/Sources/Fluid/UI/SettingsView.swift
+++ b/Sources/Fluid/UI/SettingsView.swift
@@ -948,6 +948,17 @@ struct SettingsView: View {
.settingsSearchTarget(.skipSilentRecordings)
Divider().opacity(0.2)
+ self.optionToggleRow(
+ title: "Voice-Processing Meeting Mic Capture",
+ description: "Use echo-cancelling voice processing for the microphone in online-call meeting recordings. Lowers other audio volume while active.",
+ isOn: Binding(
+ get: { SettingsStore.shared.meetingVPIOMicCapture },
+ set: { SettingsStore.shared.meetingVPIOMicCapture = $0 }
+ ),
+ allowsDescriptionWrapping: true
+ )
+ Divider().opacity(0.2)
+
self.optionToggleRow(
title: "Pause Media During Transcription",
description: "Automatically pause currently playing audio/video when transcription starts. Resumes only if FluidVoice paused it.",
diff --git a/Tests/FluidDictationIntegrationTests/MeetingMicrophoneCaptureTests.swift b/Tests/FluidDictationIntegrationTests/MeetingMicrophoneCaptureTests.swift
index dcd3f21a..a8098b0e 100644
--- a/Tests/FluidDictationIntegrationTests/MeetingMicrophoneCaptureTests.swift
+++ b/Tests/FluidDictationIntegrationTests/MeetingMicrophoneCaptureTests.swift
@@ -478,6 +478,23 @@ extension MeetingMicrophoneCaptureTests {
XCTAssertEqual(clock.resyncClampCount, 1)
}
+ // MARK: - Phase 3: valid-host-seconds bounds for the de-drift elapsed term
+
+ func testValidHostSecondsBoundsTrackFirstAndLastValidStamp() throws {
+ var clock = self.makeClock()
+ _ = clock.stamp(hostTime: self.hostTime(seconds: 5), frameCount: 4_800)
+ _ = clock.stamp(hostTime: nil, frameCount: 4_800) // synthesized: must not move the bounds
+ _ = clock.stamp(hostTime: self.hostTime(seconds: 5.3), frameCount: 4_800)
+ XCTAssertEqual(try XCTUnwrap(clock.firstValidHostSeconds), 5.0, accuracy: 1e-9)
+ XCTAssertEqual(try XCTUnwrap(clock.lastValidHostSeconds), 5.3, accuracy: 1e-9)
+ }
+
+ func testValidHostSecondsAreNilBeforeAnyValidStamp() {
+ let clock = self.makeClock()
+ XCTAssertNil(clock.firstValidHostSeconds)
+ XCTAssertNil(clock.lastValidHostSeconds)
+ }
+
func testTimelineResetReanchorsOnNextValidStamp() {
var clock = self.makeClock()
_ = clock.stamp(hostTime: self.hostTime(seconds: 5), frameCount: 4_800)
diff --git a/Tests/FluidDictationIntegrationTests/MeetingVoiceProcessingCaptureTests.swift b/Tests/FluidDictationIntegrationTests/MeetingVoiceProcessingCaptureTests.swift
new file mode 100644
index 00000000..dda3230e
--- /dev/null
+++ b/Tests/FluidDictationIntegrationTests/MeetingVoiceProcessingCaptureTests.swift
@@ -0,0 +1,392 @@
+@testable import FluidVoice_Debug
+import AVFoundation
+import CoreMedia
+import Foundation
+import ScreenCaptureKit
+import os
+import XCTest
+
+/// Hardware/permission-free: ScreenCaptureKit and AVAudioEngine integration paths need live
+/// screen-recording/microphone permission and are not exercised here. This covers the pure
+/// decision, gate, drift-eligibility, de-drift transform and Codable pieces of Phase 3.
+final class MeetingVoiceProcessingCaptureTests: XCTestCase {
+ // MARK: - Decision table (plan §3)
+
+ private func mic(uid: String? = "mic-uid") -> MeetingMicrophoneIdentity {
+ MeetingMicrophoneIdentity(captureDeviceID: "dev-1", coreAudioUID: uid, displayName: "Mic")
+ }
+
+ private func viableRoute() -> MeetingOutputRouteSnapshot {
+ MeetingOutputRouteSnapshot(deviceExists: true, isBluetooth: false, isBuiltIn: true, isHeadphonesDataSource: false)
+ }
+
+ func testDecisionSucceedsWhenEveryConditionIsMet() {
+ let decision = MeetingCapturePathDecider.decide(flag: true, mode: .onlineCall, microphone: self.mic(), outputRoute: self.viableRoute())
+ XCTAssertEqual(decision, .voiceProcessing)
+ }
+
+ func testDecisionDeclinesWhenFlagIsOff() {
+ let decision = MeetingCapturePathDecider.decide(flag: false, mode: .onlineCall, microphone: self.mic(), outputRoute: self.viableRoute())
+ guard case .screenCaptureKit = decision else { return XCTFail("expected decline") }
+ }
+
+ func testDecisionDeclinesForInRoomMode() {
+ let decision = MeetingCapturePathDecider.decide(flag: true, mode: .inRoom, microphone: self.mic(), outputRoute: self.viableRoute())
+ guard case .screenCaptureKit = decision else { return XCTFail("expected decline") }
+ }
+
+ func testDecisionDeclinesWithoutCoreAudioUID() {
+ let decision = MeetingCapturePathDecider.decide(flag: true, mode: .onlineCall, microphone: self.mic(uid: nil), outputRoute: self.viableRoute())
+ guard case let .screenCaptureKit(reason) = decision else { return XCTFail("expected decline") }
+ XCTAssertTrue(reason.contains("UID"))
+ }
+
+ func testDecisionDeclinesWithoutOutputDevice() {
+ let route = MeetingOutputRouteSnapshot(deviceExists: false, isBluetooth: false, isBuiltIn: false, isHeadphonesDataSource: false)
+ let decision = MeetingCapturePathDecider.decide(flag: true, mode: .onlineCall, microphone: self.mic(), outputRoute: route)
+ guard case let .screenCaptureKit(reason) = decision else { return XCTFail("expected decline") }
+ XCTAssertTrue(reason.contains("output device"))
+ }
+
+ func testDecisionDeclinesForBluetoothOutput() {
+ let route = MeetingOutputRouteSnapshot(deviceExists: true, isBluetooth: true, isBuiltIn: false, isHeadphonesDataSource: false)
+ let decision = MeetingCapturePathDecider.decide(flag: true, mode: .onlineCall, microphone: self.mic(), outputRoute: route)
+ guard case let .screenCaptureKit(reason) = decision else { return XCTFail("expected decline") }
+ XCTAssertTrue(reason.contains("Bluetooth"))
+ }
+
+ func testDecisionDeclinesForNonBuiltInOutput() {
+ let route = MeetingOutputRouteSnapshot(deviceExists: true, isBluetooth: false, isBuiltIn: false, isHeadphonesDataSource: false)
+ let decision = MeetingCapturePathDecider.decide(flag: true, mode: .onlineCall, microphone: self.mic(), outputRoute: route)
+ guard case let .screenCaptureKit(reason) = decision else { return XCTFail("expected decline") }
+ XCTAssertTrue(reason.contains("built-in"))
+ }
+
+ func testDecisionDeclinesForHeadphonesDataSource() {
+ let route = MeetingOutputRouteSnapshot(deviceExists: true, isBluetooth: false, isBuiltIn: true, isHeadphonesDataSource: true)
+ let decision = MeetingCapturePathDecider.decide(flag: true, mode: .onlineCall, microphone: self.mic(), outputRoute: route)
+ guard case let .screenCaptureKit(reason) = decision else { return XCTFail("expected decline") }
+ XCTAssertTrue(reason.contains("headphones"))
+ }
+
+ // MARK: - Commit gate (plan §4, §7)
+
+ private func makeSampleBuffer(ptsSeconds: Double = 0) -> CMSampleBuffer {
+ let format = AVAudioFormat(commonFormat: .pcmFormatFloat32, sampleRate: 48_000, channels: 1, interleaved: false)!
+ let buffer = AVAudioPCMBuffer(pcmFormat: format, frameCapacity: 480)!
+ buffer.frameLength = 480
+ let pts = CMTime(seconds: ptsSeconds, preferredTimescale: 48_000)
+ return meetingMicrophoneSynthesizeSampleBuffer(from: buffer, presentationTime: pts)!
+ }
+
+ func testGateBuffersThenPassesThroughAfterCommit() {
+ let gate = MeetingVoiceProcessingCommitGate()
+ XCTAssertEqual(gate.offer(self.makeSampleBuffer()), .buffered)
+ let flushed = gate.beginCommitFlush()
+ XCTAssertEqual(flushed?.count, 1)
+ XCTAssertNil(gate.continueCommitFlush(), "drained ring flips to committed")
+ XCTAssertEqual(gate.offer(self.makeSampleBuffer()), .passthrough)
+ }
+
+ func testGateFlushSerializesConcurrentArrivalsBeforePassthrough() {
+ let gate = MeetingVoiceProcessingCommitGate()
+ XCTAssertEqual(gate.offer(self.makeSampleBuffer(ptsSeconds: 0)), .buffered)
+ let first = gate.beginCommitFlush()
+ XCTAssertEqual(first?.count, 1)
+ // A sample landing mid-flush must queue behind the ring, never overtake it.
+ XCTAssertEqual(gate.offer(self.makeSampleBuffer(ptsSeconds: 1)), .buffered)
+ let second = gate.continueCommitFlush()
+ XCTAssertEqual(second?.count, 1)
+ XCTAssertNil(gate.continueCommitFlush())
+ XCTAssertEqual(gate.offer(self.makeSampleBuffer(ptsSeconds: 2)), .passthrough)
+ }
+
+ func testGateAbortAndTerminalEventsAreNoOpsWhileFlushing() {
+ let gate = MeetingVoiceProcessingCommitGate()
+ _ = gate.offer(self.makeSampleBuffer())
+ _ = gate.beginCommitFlush()
+ gate.abort()
+ XCTAssertFalse(gate.offerTerminalEventPreCommit())
+ XCTAssertNil(gate.continueCommitFlush())
+ XCTAssertEqual(gate.offer(self.makeSampleBuffer()), .passthrough, "a promoted flush can never be aborted back out")
+ }
+
+ func testGateAbortsAndSwallowsAfterRingExhaustion() throws {
+ // Cap sized to fit exactly one sample's worth of bytes: the second sample must not fit.
+ let one = self.makeSampleBuffer()
+ let bytes = CMBlockBufferGetDataLength(try XCTUnwrap(CMSampleBufferGetDataBuffer(one)))
+ XCTAssertGreaterThan(bytes, 0)
+ let gate = MeetingVoiceProcessingCommitGate(ringCapBytes: bytes)
+ XCTAssertEqual(gate.offer(one), .buffered)
+ XCTAssertEqual(gate.offer(self.makeSampleBuffer(ptsSeconds: 1)), .aborted, "ring-cap exhaustion must abort, never evict-and-commit")
+ XCTAssertEqual(gate.offer(self.makeSampleBuffer(ptsSeconds: 2)), .aborted)
+ XCTAssertNil(gate.beginCommitFlush(), "an aborted gate can never commit")
+ }
+
+ func testGateTerminalEventPreCommitAborts() {
+ let gate = MeetingVoiceProcessingCommitGate()
+ _ = gate.offer(self.makeSampleBuffer())
+ XCTAssertTrue(gate.offerTerminalEventPreCommit())
+ XCTAssertEqual(gate.offer(self.makeSampleBuffer()), .aborted)
+ XCTAssertNil(gate.beginCommitFlush())
+ }
+
+ func testGateTerminalEventPostCommitIsNotAnAbort() {
+ let gate = MeetingVoiceProcessingCommitGate()
+ _ = gate.beginCommitFlush()
+ XCTAssertNil(gate.continueCommitFlush())
+ XCTAssertFalse(gate.offerTerminalEventPreCommit(), "post-commit terminal events are the runtime's normal interrupt path, not a gate abort")
+ XCTAssertEqual(gate.offer(self.makeSampleBuffer()), .passthrough)
+ }
+
+ func testGateAbortIsIdempotentAndFinal() {
+ let gate = MeetingVoiceProcessingCommitGate()
+ gate.abort()
+ gate.abort()
+ XCTAssertEqual(gate.offer(self.makeSampleBuffer()), .aborted)
+ XCTAssertNil(gate.beginCommitFlush())
+ }
+
+ // MARK: - Watchdog predicate (plan §5, §7)
+
+ func testWatchdogDoesNotTripBeforeThreshold() {
+ XCTAssertFalse(MeetingVoiceProcessingWatchdog.isStalled(secondsSinceLastEmittedBuffer: 9.9))
+ }
+
+ func testWatchdogTripsAtThreshold() {
+ XCTAssertTrue(MeetingVoiceProcessingWatchdog.isStalled(secondsSinceLastEmittedBuffer: 10))
+ XCTAssertTrue(MeetingVoiceProcessingWatchdog.isStalled(secondsSinceLastEmittedBuffer: 30))
+ }
+
+ // MARK: - ScreenCaptureKit audio-settings plumbing (rebuild regression, plan §7)
+
+ func testIncludeMicrophoneFalseAttachesNoMicrophoneDevice() {
+ let configuration = SCStreamConfiguration()
+ MeetingScreenCaptureAudioSettings.apply(to: configuration, microphone: self.mic(), includeMicrophone: false)
+ XCTAssertFalse(configuration.captureMicrophone)
+ XCTAssertNil(configuration.microphoneCaptureDeviceID)
+ }
+
+ func testIncludeMicrophoneTrueSetsTheRequestedDevice() {
+ let configuration = SCStreamConfiguration()
+ MeetingScreenCaptureAudioSettings.apply(to: configuration, microphone: self.mic(), includeMicrophone: true)
+ XCTAssertTrue(configuration.captureMicrophone)
+ XCTAssertEqual(configuration.microphoneCaptureDeviceID, "dev-1")
+ }
+
+ // MARK: - Eligibility (plan §6, §7)
+
+ private func makeStats(
+ resyncCount: Int = 0,
+ resyncClampCount: Int = 0,
+ divergenceStepEventCount: Int = 0,
+ configurationChangeEvents: Int = 0,
+ droppedPostCapCount: Int = 0
+ ) -> MeetingMicrophoneCaptureStats.Snapshot {
+ var snapshot = MeetingMicrophoneCaptureStats.Snapshot()
+ snapshot.resyncCount = resyncCount
+ snapshot.resyncClampCount = resyncClampCount
+ snapshot.divergenceStepEventCount = divergenceStepEventCount
+ snapshot.configurationChangeEvents = configurationChangeEvents
+ snapshot.droppedPostCapCount = droppedPostCapCount
+ return snapshot
+ }
+
+ func testCleanRunIsEligible() {
+ XCTAssertTrue(MeetingVoiceProcessingDriftSnapshot.isEligible(self.makeStats()))
+ }
+
+ func testMidStreamResetMakesRunIneligible() {
+ XCTAssertFalse(MeetingVoiceProcessingDriftSnapshot.isEligible(self.makeStats(resyncCount: 1)))
+ XCTAssertFalse(MeetingVoiceProcessingDriftSnapshot.isEligible(self.makeStats(resyncClampCount: 1)))
+ XCTAssertFalse(MeetingVoiceProcessingDriftSnapshot.isEligible(self.makeStats(divergenceStepEventCount: 1)))
+ XCTAssertFalse(MeetingVoiceProcessingDriftSnapshot.isEligible(self.makeStats(configurationChangeEvents: 1)))
+ XCTAssertFalse(MeetingVoiceProcessingDriftSnapshot.isEligible(self.makeStats(droppedPostCapCount: 1)))
+ }
+
+ func testElapsedValidHostSecondsFromStats() {
+ var snapshot = MeetingMicrophoneCaptureStats.Snapshot()
+ snapshot.firstValidHostSeconds = 10
+ snapshot.lastValidHostSeconds = 22.5
+ XCTAssertEqual(MeetingVoiceProcessingDriftSnapshot.elapsedValidHostSeconds(snapshot), 12.5, accuracy: 1e-9)
+ }
+
+ func testElapsedValidHostSecondsIsZeroWithoutBothBounds() {
+ XCTAssertEqual(MeetingVoiceProcessingDriftSnapshot.elapsedValidHostSeconds(MeetingMicrophoneCaptureStats.Snapshot()), 0)
+ }
+
+ // MARK: - End-to-end de-drift sign (plan §7, resolves sol#1)
+
+ private func makeTrack(chunkStart: Double, drift: MeetingClockDriftRecord?, captureMethod: MeetingAudioTrackCaptureMethod?) -> MeetingAudioTrack {
+ var track = MeetingAudioTrack(
+ id: UUID(),
+ kind: .microphone,
+ sourceIdentifier: "mic",
+ sourceDisplayName: "Mic",
+ format: nil,
+ timebase: MeetingTimebaseMetadata(startedHostTime: 0, machTimebaseNumerator: 1, machTimebaseDenominator: 1, firstPresentationTime: nil),
+ health: .waiting,
+ chunks: [MeetingAudioChunk(
+ id: UUID(), sequence: 0, relativeFilePath: "x.m4a",
+ presentationStart: MeetingMediaTime(value: Int64(chunkStart * 48_000), timescale: 48_000),
+ presentationEnd: MeetingMediaTime(value: Int64((chunkStart + 60) * 48_000), timescale: 48_000),
+ discontinuities: [], sha256: "x", byteCount: 1, finalizationState: .finalized
+ )]
+ )
+ track.captureMethod = captureMethod
+ track.clockDrift = drift
+ return track
+ }
+
+ /// Drives the REAL clock fast-mic (host elapses SLOWER than frame count — the mirror of
+ /// `testSlowDriftNeverFiresTheStepDetector`), then asserts the transform compresses the timeline.
+ func testDeDriftCorrectsAFastMicAndTheInverseFormulaFails() {
+ var clock = MeetingMicrophonePTSClock(timebase: mach_timebase_info_data_t(numer: 1, denom: 1))
+ let ppm = 6.7e-6
+ let windowSeconds = 0.1
+ let windows = 9_500 // 950s: past the ~12.5min materiality crossover at 6.7ppm (plan note)
+ for i in 0..<windows {
+ let hostSeconds = Double(i) * windowSeconds * (1 - ppm) // fast mic: less host time per window
+ _ = clock.stamp(hostTime: UInt64(hostSeconds * 1_000_000_000), frameCount: 4_800)
+ }
+ let elapsed = Double(windows - 1) * windowSeconds * (1 - ppm)
+ let cumulative = clock.cumulativeAbsorbedCorrectionSeconds
+ XCTAssertLessThan(cumulative, 0, "a fast mic must show a NEGATIVE cumulative absorbed correction")
+ XCTAssertGreaterThan(abs(cumulative), MeetingMicrophoneDeDrift.materialityThresholdSeconds)
+
+ let drift = MeetingClockDriftRecord(cumulativeAbsorbedSeconds: cumulative, elapsedValidHostSeconds: elapsed, eligible: true)
+ let track = self.makeTrack(chunkStart: 0, drift: drift, captureMethod: .voiceProcessing)
+
+ let rawEnd = Double(windows) * windowSeconds
+ let corrected = MeetingMicrophoneDeDrift.correct(rawEnd, track: track, origin: 0)
+ XCTAssertLessThan(corrected, rawEnd, "correction must compress the fast timeline toward the reference, not expand it")
+ XCTAssertEqual(corrected, rawEnd + cumulative, accuracy: 0.05, "k = 1 + cumulative/elapsed applied against the reference")
+
+ // The v1 sign-bug inverse transform must move the WRONG direction (expand, not compress).
+ let fraction = cumulative / elapsed
+ let inverseCorrected = rawEnd / (1 + fraction)
+ XCTAssertGreaterThan(inverseCorrected, rawEnd, "the inverted formula moves the WRONG direction — expands instead of compresses")
+ }
+
+ func testDeDriftIsANoOpWhenIneligible() {
+ let drift = MeetingClockDriftRecord(cumulativeAbsorbedSeconds: -0.05, elapsedValidHostSeconds: 300, eligible: false)
+ let track = self.makeTrack(chunkStart: 0, drift: drift, captureMethod: .voiceProcessing)
+ XCTAssertEqual(MeetingMicrophoneDeDrift.correct(120, track: track, origin: 0), 120)
+ }
+
+ func testDeDriftIsANoOpForNonVoiceProcessingTracks() {
+ let drift = MeetingClockDriftRecord(cumulativeAbsorbedSeconds: -0.05, elapsedValidHostSeconds: 300, eligible: true)
+ let track = self.makeTrack(chunkStart: 0, drift: drift, captureMethod: .screenCaptureKit)
+ XCTAssertEqual(MeetingMicrophoneDeDrift.correct(120, track: track, origin: 0), 120)
+ }
+
+ func testDeDriftIsANoOpBelowMaterialityThreshold() {
+ // 1ms cumulative over 300s is below the 5ms materiality gate.
+ let drift = MeetingClockDriftRecord(cumulativeAbsorbedSeconds: -0.001, elapsedValidHostSeconds: 300, eligible: true)
+ let track = self.makeTrack(chunkStart: 0, drift: drift, captureMethod: .voiceProcessing)
+ XCTAssertEqual(MeetingMicrophoneDeDrift.correct(120, track: track, origin: 0), 120)
+ }
+
+ // MARK: - Ring flush pacing (plan §4/§7, opus N2)
+
+ /// flushBatch's pacing (4 samples / 5ms) against a real writer: a full ~5s ring must not trip backpressure.
+ func testPacedRingFlushProducesNoWriterBackpressure() async throws {
+ let sessionDirectory = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
+ defer { try? FileManager.default.removeItem(at: sessionDirectory) }
+ let track = MeetingAudioTrack(
+ id: UUID(), kind: .microphone, sourceIdentifier: "mic", sourceDisplayName: "Mic",
+ format: nil,
+ timebase: MeetingTimebaseMetadata(startedHostTime: 0, machTimebaseNumerator: 1, machTimebaseDenominator: 1, firstPresentationTime: nil),
+ health: .waiting, chunks: []
+ )
+ let backpressureCount = OSAllocatedUnfairLock<Int>(initialState: 0)
+ let writer = try MeetingAudioChunkWriter(track: track, sessionDirectory: sessionDirectory, chunkDuration: 60) { event in
+ if case .interrupted(.writerBackpressure, _, _) = event {
+ backpressureCount.withLock { $0 += 1 }
+ }
+ }
+
+ let samples = (0..<50).map { self.makeSampleBuffer(ptsSeconds: Double($0) * 0.1) }
+ for (index, sample) in samples.enumerated() {
+ writer.enqueue(sample)
+ if index % 4 == 3 {
+ try await Task.sleep(nanoseconds: 5_000_000)
+ }
+ }
+ _ = await writer.stop()
+ XCTAssertEqual(backpressureCount.withLock { $0 }, 0)
+ }
+
+ // MARK: - Provenance promotion (plan §2, §7)
+
+ func testProvenanceIsPessimisticThenPromotedOnCommit() async throws {
+ let sessionDirectory = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
+ defer { try? FileManager.default.removeItem(at: sessionDirectory) }
+ let track = MeetingAudioTrack(
+ id: UUID(), kind: .microphone, sourceIdentifier: "mic", sourceDisplayName: "Mic",
+ format: nil,
+ timebase: MeetingTimebaseMetadata(startedHostTime: 0, machTimebaseNumerator: 1, machTimebaseDenominator: 1, firstPresentationTime: nil),
+ health: .waiting, chunks: [], captureMethod: .screenCaptureKit
+ )
+ let writer = try MeetingAudioChunkWriter(track: track, sessionDirectory: sessionDirectory, chunkDuration: 60) { _ in }
+
+ let beforeCommit = await writer.snapshot()
+ XCTAssertEqual(beforeCommit.captureMethod, .screenCaptureKit, "pessimistic default before any commit")
+
+ try await writer.updateTrackMetadata { track in
+ track.captureMethod = .voiceProcessing
+ }
+ let afterCommit = await writer.snapshot()
+ XCTAssertEqual(afterCommit.captureMethod, .voiceProcessing)
+ _ = await writer.stop()
+ }
+
+ // MARK: - Codable tolerance (plan §7, kimi#7)
+
+ func testUnknownCaptureMethodRawValueDecodesToNil() throws {
+ var track = self.makeTrack(chunkStart: 0, drift: nil, captureMethod: .voiceProcessing)
+ track.captureMethod = nil
+ let encoder = JSONEncoder()
+ encoder.dateEncodingStrategy = .iso8601
+ var data = try encoder.encode(track)
+ var json = try XCTUnwrap(try JSONSerialization.jsonObject(with: data) as? [String: Any])
+ json["captureMethod"] = "someFutureCaptureMethodThisBuildDoesNotKnow"
+ data = try JSONSerialization.data(withJSONObject: json)
+
+ let decoder = JSONDecoder()
+ decoder.dateDecodingStrategy = .iso8601
+ let decoded = try decoder.decode(MeetingAudioTrack.self, from: data)
+ XCTAssertNil(decoded.captureMethod, "an unrecognized raw value must decode to nil, not throw")
+ }
+
+ func testPreExistingJSONWithoutCaptureMethodDecodesWithNilFields() throws {
+ let track = self.makeTrack(chunkStart: 0, drift: nil, captureMethod: .voiceProcessing)
+ let encoder = JSONEncoder()
+ encoder.dateEncodingStrategy = .iso8601
+ var data = try encoder.encode(track)
+ var json = try XCTUnwrap(try JSONSerialization.jsonObject(with: data) as? [String: Any])
+ json.removeValue(forKey: "captureMethod")
+ json.removeValue(forKey: "voiceProcessingConfig")
+ json.removeValue(forKey: "clockDrift")
+ data = try JSONSerialization.data(withJSONObject: json)
+
+ let decoder = JSONDecoder()
+ decoder.dateDecodingStrategy = .iso8601
+ let decoded = try decoder.decode(MeetingAudioTrack.self, from: data)
+ XCTAssertNil(decoded.captureMethod)
+ XCTAssertNil(decoded.voiceProcessingConfig)
+ XCTAssertNil(decoded.clockDrift)
+ }
+
+ func testCaptureMethodAndDriftRoundTripThroughCodable() throws {
+ let drift = MeetingClockDriftRecord(cumulativeAbsorbedSeconds: -0.02, elapsedValidHostSeconds: 300, eligible: true)
+ let track = self.makeTrack(chunkStart: 0, drift: drift, captureMethod: .voiceProcessing)
+ let encoder = JSONEncoder()
+ encoder.dateEncodingStrategy = .iso8601
+ let decoder = JSONDecoder()
+ decoder.dateDecodingStrategy = .iso8601
+ let decoded = try decoder.decode(MeetingAudioTrack.self, from: try encoder.encode(track))
+ XCTAssertEqual(decoded.captureMethod, .voiceProcessing)
+ XCTAssertEqual(decoded.clockDrift, drift)
+ }
+}