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): recover "You" from echo, room audio and hallucinated turns

Shreeraman A Ke025bf5abb51
diff --git a/Sources/Fluid/Services/Meeting/MeetingEchoSignalScorer.swift b/Sources/Fluid/Services/Meeting/MeetingEchoSignalScorer.swift
new file mode 100644
index 00000000..ae935606
--- /dev/null
+++ b/Sources/Fluid/Services/Meeting/MeetingEchoSignalScorer.swift
@@ -0,0 +1,423 @@
+import Accelerate
+import Foundation
+
+nonisolated struct DelayEstimate: Equatable, Sendable {
+ let seconds: TimeInterval
+ let confidence: Double
+}
+
+nonisolated enum TurnEchoVerdict: Equatable, Sendable {
+ case echo
+ case containsLocalSpeech
+ case unknown
+}
+
+nonisolated struct EchoFrameScores: Equatable, Sendable {
+ let fractions: [Double]
+ let hopSeconds: Double
+}
+
+/// Separates far-end echo from local speech by correlating the mic against what the meeting app
+/// played. Calibrated on one 3.2-minute Zoom recording: pure echo scored median 0.62-0.82 with
+/// low-runs of 0.24-0.59 s, local speech median 0.00-0.38 with low-runs of 0.96-10.27 s. Since the
+/// statistic is `1 - residual/mic`, additive double talk only rescues a turn when local speech
+/// carries ~1.86x the echo energy - true near the talker, false for a quiet interjection.
+nonisolated enum MeetingEchoSignalScorer {
+ static let frameLength = 1024
+ static let hopLength = 256
+ static let blockSeconds = 2.0
+ static let localSpeechFractionThreshold = 0.35
+ /// Calibrated against frame-*start* span, which undercounts coverage by 48 ms.
+ static let minimumLocalSpeechRunSeconds = 0.75
+ static let echoMedianThreshold = 0.5
+ /// The rescue's `minimumLocalSpeechRunSeconds` is absolute, so on a long turn it fires on a few
+ /// percent of the span: measured 0.75s inside a 22.4s turn at median 0.91 — indistinguishable
+ /// from a 21.5s turn at median 0.86 whose run happened to stop at 0.48s. A turn is only denied
+ /// the rescue when it is BOTH overwhelmingly explained by the far end AND the low run is a
+ /// trivial share of it; genuine double talk clears the share test (a 1.0s burst in a 3.0s turn
+ /// is 33%), and calibrated mixed turns sit near median 0.38, far under the median test.
+ static let overwhelminglyExplainedMedian = 0.8
+ static let minimumLocalSpeechRunFraction = 0.15
+ static let minimumDelayConfidence = 8.0
+ static let minimumSignalRMS: Float = 1e-4
+ static let minimumScoreableFraction = 0.5
+ /// Fewer frames than this and the per-bin fit is exact, manufacturing "echo" from noise.
+ static let minimumFramesPerBlock = 8
+ static let minimumUsableBinFraction = 0.5
+ /// Bounds estimateDelay's FFT size (and memory) for pathologically long turns.
+ static let maximumDelayEstimationSeconds = 20.0
+
+ private static let hannWindowPower: Float = {
+ let window = MeetingEchoSignalScorer.hannWindow(MeetingEchoSignalScorer.frameLength)
+ var sum: Float = 0
+ vDSP_svesq(window, 1, &sum, vDSP_Length(window.count))
+ return sum
+ }()
+
+ /// Divide-by-zero guard for PHAT normalization, not a physical threshold.
+ private static let phatMagnitudeFloor: Float = 1e-12
+
+ static func estimateDelay(
+ mic: [Float],
+ reference: [Float],
+ sampleRate: Double,
+ maxLagSeconds: TimeInterval
+ ) -> DelayEstimate? {
+ guard mic.count >= self.frameLength, reference.count >= self.frameLength else { return nil }
+ guard self.rms(mic) >= self.minimumSignalRMS, self.rms(reference) >= self.minimumSignalRMS else { return nil }
+
+ let fullN = max(mic.count, reference.count)
+ let maxSamples = self.safeInt(self.maximumDelayEstimationSeconds * sampleRate)
+ .map { max($0, self.frameLength) } ?? fullN
+ let start = max(0, (fullN - maxSamples) / 2)
+ let boundedMic = self.boundedSlice(mic, start: start, maxLength: maxSamples)
+ let boundedReference = self.boundedSlice(reference, start: start, maxLength: maxSamples)
+ guard !boundedMic.isEmpty, !boundedReference.isEmpty else { return nil }
+
+ let n = max(boundedMic.count, boundedReference.count)
+ let fftSize = self.nextPowerOfTwo(2 * n)
+ let log2n = vDSP_Length(log2(Double(fftSize)))
+
+ // Rectangular: a per-signal Hann would give each a different envelope, biasing toward lag 0.
+ var micPadded = self.zeroPadded(boundedMic, fftSize: fftSize)
+ var refPadded = self.zeroPadded(boundedReference, fftSize: fftSize)
+
+ guard let setup = vDSP_create_fftsetup(log2n, FFTRadix(kFFTRadix2)) else { return nil }
+ defer { vDSP_destroy_fftsetup(setup) }
+
+ guard let micSpectrum = self.forwardFFT(&micPadded, fftSize: fftSize, setup: setup, log2n: log2n),
+ let refSpectrum = self.forwardFFT(&refPadded, fftSize: fftSize, setup: setup, log2n: log2n)
+ else { return nil }
+
+ let crossCorrelation = self.phatCrossCorrelation(
+ mic: micSpectrum, reference: refSpectrum, fftSize: fftSize, setup: setup, log2n: log2n
+ )
+ guard !crossCorrelation.isEmpty else { return nil }
+
+ guard let maxLagSamplesRaw = self.safeInt(maxLagSeconds * sampleRate) else { return nil }
+ let maxLagSamples = min(maxLagSamplesRaw, fftSize / 2 - 1)
+ guard maxLagSamples > 0 else { return nil }
+
+ var bestLag = 0
+ var bestMagnitude: Float = -1
+ var magnitudes: [Float] = []
+ magnitudes.reserveCapacity(2 * maxLagSamples + 1)
+ for lag in -maxLagSamples...maxLagSamples {
+ // Negative lags wrap to the tail of the circular cross-correlation buffer.
+ let index = lag >= 0 ? lag : fftSize + lag
+ let magnitude = abs(crossCorrelation[index])
+ magnitudes.append(magnitude)
+ if magnitude > bestMagnitude {
+ bestMagnitude = magnitude
+ bestLag = lag
+ }
+ }
+
+ let median = self.median(magnitudes)
+ guard median > 0 else { return nil }
+ let confidence = Double(bestMagnitude) / Double(median)
+ let seconds = Double(bestLag) / sampleRate
+ return DelayEstimate(seconds: seconds, confidence: confidence)
+ }
+
+ /// NaN marks unscoreable frames: "no information" must never read as "no echo".
+ static func explainedFractions(
+ mic: [Float],
+ reference: [Float],
+ sampleRate: Double,
+ delaySeconds: TimeInterval
+ ) -> EchoFrameScores {
+ let hopSeconds = Double(self.hopLength) / sampleRate
+ let shiftedReference = self.shift(reference, bySeconds: delaySeconds, sampleRate: sampleRate, targetCount: mic.count)
+ guard mic.count >= self.frameLength else { return EchoFrameScores(fractions: [], hopSeconds: hopSeconds) }
+
+ let hopCount = (mic.count - self.frameLength) / self.hopLength + 1
+ guard hopCount > 0 else { return EchoFrameScores(fractions: [], hopSeconds: hopSeconds) }
+
+ guard let setup = vDSP_create_fftsetup(vDSP_Length(log2(Double(self.frameLength))), FFTRadix(kFFTRadix2)) else {
+ return EchoFrameScores(fractions: [], hopSeconds: hopSeconds)
+ }
+ defer { vDSP_destroy_fftsetup(setup) }
+ let log2n = vDSP_Length(log2(Double(self.frameLength)))
+ let window = self.hannWindow(self.frameLength)
+
+ var micFrameRMS: [Float] = []
+ var micSpectra: [Spectrum] = []
+ var refSpectra: [Spectrum] = []
+ micFrameRMS.reserveCapacity(hopCount)
+ micSpectra.reserveCapacity(hopCount)
+ refSpectra.reserveCapacity(hopCount)
+ for i in 0..<hopCount {
+ let start = i * self.hopLength
+ var m = Array(mic[start..<start + self.frameLength])
+ var r = Array(shiftedReference[start..<start + self.frameLength])
+ vDSP_vmul(m, 1, window, 1, &m, 1, vDSP_Length(self.frameLength))
+ vDSP_vmul(r, 1, window, 1, &r, 1, vDSP_Length(self.frameLength))
+ micFrameRMS.append(self.rms(m))
+ guard let mSpectrum = self.forwardFFT(&m, fftSize: self.frameLength, setup: setup, log2n: log2n),
+ let rSpectrum = self.forwardFFT(&r, fftSize: self.frameLength, setup: setup, log2n: log2n)
+ else { return EchoFrameScores(fractions: [Double](repeating: .nan, count: hopCount), hopSeconds: hopSeconds) }
+ micSpectra.append(mSpectrum)
+ refSpectra.append(rSpectrum)
+ }
+
+ let framesPerBlock = max(self.minimumFramesPerBlock, Int((self.blockSeconds * sampleRate) / Double(self.hopLength)))
+ var result = [Double](repeating: .nan, count: hopCount)
+
+ var blockRanges: [Range<Int>] = []
+ var blockStart = 0
+ while blockStart < hopCount {
+ let blockEnd = min(blockStart + framesPerBlock, hopCount)
+ blockRanges.append(blockStart..<blockEnd)
+ blockStart = blockEnd
+ }
+ // Short tail can't be fit alone; fold it into the preceding block.
+ if blockRanges.count > 1, blockRanges[blockRanges.count - 1].count < self.minimumFramesPerBlock {
+ let tail = blockRanges.removeLast()
+ let previous = blockRanges.removeLast()
+ blockRanges.append(previous.lowerBound..<tail.upperBound)
+ }
+ for range in blockRanges where range.count >= self.minimumFramesPerBlock {
+ self.scoreBlock(
+ micFrameRMS: micFrameRMS, micSpectra: micSpectra, refSpectra: refSpectra,
+ range: range, into: &result
+ )
+ }
+ return EchoFrameScores(fractions: result, hopSeconds: hopSeconds)
+ }
+
+ private static func scoreBlock(
+ micFrameRMS: [Float],
+ micSpectra: [Spectrum],
+ refSpectra: [Spectrum],
+ range: Range<Int>,
+ into result: inout [Double]
+ ) {
+ let binCount = micSpectra[range.lowerBound].real.count
+ var crossReal = [Float](repeating: 0, count: binCount)
+ var crossImag = [Float](repeating: 0, count: binCount)
+ var refPower = [Float](repeating: 0, count: binCount)
+
+ for i in range {
+ let m = micSpectra[i], r = refSpectra[i]
+ for k in 0..<binCount {
+ crossReal[k] += m.real[k] * r.real[k] + m.imag[k] * r.imag[k]
+ crossImag[k] += m.imag[k] * r.real[k] - m.real[k] * r.imag[k]
+ refPower[k] += r.real[k] * r.real[k] + r.imag[k] * r.imag[k]
+ }
+ }
+
+ var hReal = [Float](repeating: 0, count: binCount)
+ var hImag = [Float](repeating: 0, count: binCount)
+ var referenceUsableBins = 0
+ // Parseval, so the floor lands in refPower's accumulated units rather than orders off.
+ let refFloor = Float(self.minimumSignalRMS * self.minimumSignalRMS) * self.hannWindowPower * Float(range.count)
+ // vDSP packs DC and Nyquist together in bin 0; excluded so H never mixes the two.
+ for k in 1..<binCount where refPower[k] > refFloor {
+ hReal[k] = crossReal[k] / refPower[k]
+ hImag[k] = crossImag[k] / refPower[k]
+ referenceUsableBins += 1
+ }
+ let usableBinFraction = Double(referenceUsableBins) / Double(binCount - 1)
+ guard usableBinFraction >= self.minimumUsableBinFraction else { return }
+
+ for i in range {
+ let micRMS = micFrameRMS[i]
+ guard micRMS >= self.minimumSignalRMS else { continue }
+ let m = micSpectra[i], r = refSpectra[i]
+ var micEnergy: Float = 0
+ var residualEnergy: Float = 0
+ for k in 1..<binCount {
+ micEnergy += m.real[k] * m.real[k] + m.imag[k] * m.imag[k]
+ let predictedReal = hReal[k] * r.real[k] - hImag[k] * r.imag[k]
+ let predictedImag = hReal[k] * r.imag[k] + hImag[k] * r.real[k]
+ let residualReal = m.real[k] - predictedReal
+ let residualImag = m.imag[k] - predictedImag
+ residualEnergy += residualReal * residualReal + residualImag * residualImag
+ }
+ guard micEnergy > 0 else { continue }
+ let fraction = 1.0 - Double(residualEnergy / micEnergy)
+ result[i] = min(1.0, max(0.0, fraction))
+ }
+ }
+
+ static func verdict(
+ _ scores: EchoFrameScores,
+ minimumScoreableFraction requiredScoreableFraction: Double = MeetingEchoSignalScorer.minimumScoreableFraction
+ ) -> TurnEchoVerdict {
+ let explainedFractions = scores.fractions
+ let hopSeconds = scores.hopSeconds
+ guard !explainedFractions.isEmpty else { return .unknown }
+
+ // Hiding real speech is the costly failure, so the rescue runs before the coverage gate;
+ // only the echo verdict requires enough scoreable frames.
+ var longestLowRun = 0
+ var currentRun = 0
+ var gapRun = 0
+ for value in explainedFractions {
+ if !value.isNaN, value < self.localSpeechFractionThreshold {
+ currentRun += 1
+ gapRun = 0
+ longestLowRun = max(longestLowRun, currentRun)
+ } else if value.isNaN {
+ gapRun += 1
+ // A gap long enough to itself be a run means the thread is lost.
+ if Double(gapRun) * hopSeconds >= self.minimumLocalSpeechRunSeconds {
+ currentRun = 0
+ }
+ } else {
+ currentRun = 0
+ gapRun = 0
+ }
+ }
+ let scoreableIndices = explainedFractions.indices.filter { !explainedFractions[$0].isNaN }
+ let scoreableFraction = Double(scoreableIndices.count) / Double(explainedFractions.count)
+ let scoreableValues = scoreableIndices.map { explainedFractions[$0] }
+ let median = scoreableValues.isEmpty ? Double.nan : self.median(scoreableValues)
+ let lowRunSeconds = Double(longestLowRun) * hopSeconds
+ let turnSeconds = Double(explainedFractions.count) * hopSeconds
+ let lowRunFraction = turnSeconds > 0 ? lowRunSeconds / turnSeconds : 0
+ let isTrivialRunInExplainedTurn = !median.isNaN
+ && scoreableFraction >= requiredScoreableFraction
+ && median >= self.overwhelminglyExplainedMedian
+ && lowRunFraction < self.minimumLocalSpeechRunFraction
+
+ if !isTrivialRunInExplainedTurn, lowRunSeconds >= self.minimumLocalSpeechRunSeconds {
+ return .containsLocalSpeech
+ }
+
+ guard scoreableFraction >= requiredScoreableFraction else { return .unknown }
+ if !median.isNaN, median >= self.echoMedianThreshold {
+ return .echo
+ }
+ return .unknown
+ }
+
+ private static func rms(_ signal: [Float]) -> Float {
+ guard !signal.isEmpty else { return 0 }
+ var result: Float = 0
+ vDSP_measqv(signal, 1, &result, vDSP_Length(signal.count))
+ return sqrt(result)
+ }
+
+ private static func safeInt(_ value: Double) -> Int? {
+ guard value.isFinite, value >= Double(Int.min), value <= Double(Int.max) else { return nil }
+ return Int(value)
+ }
+
+ private static func boundedSlice(_ signal: [Float], start: Int, maxLength: Int) -> [Float] {
+ guard start < signal.count, maxLength > 0 else { return [] }
+ let end = min(signal.count, start + maxLength)
+ return Array(signal[start..<end])
+ }
+
+ private static func nextPowerOfTwo(_ value: Int) -> Int {
+ var power = 1
+ while power < value { power <<= 1 }
+ return power
+ }
+
+ private static func hannWindow(_ length: Int) -> [Float] {
+ var window = [Float](repeating: 0, count: length)
+ vDSP_hann_window(&window, vDSP_Length(length), Int32(vDSP_HANN_NORM))
+ return window
+ }
+
+ private static func zeroPadded(_ signal: [Float], fftSize: Int) -> [Float] {
+ var padded = [Float](repeating: 0, count: fftSize)
+ padded.replaceSubrange(0..<signal.count, with: signal)
+ return padded
+ }
+
+ private struct Spectrum {
+ var real: [Float]
+ var imag: [Float]
+ }
+
+ private static func forwardFFT(
+ _ signal: inout [Float], fftSize: Int, setup: FFTSetup, log2n: vDSP_Length
+ ) -> Spectrum? {
+ var real = [Float](repeating: 0, count: fftSize / 2)
+ var imag = [Float](repeating: 0, count: fftSize / 2)
+ var spectrum: Spectrum?
+ real.withUnsafeMutableBufferPointer { realPtr in
+ imag.withUnsafeMutableBufferPointer { imagPtr in
+ var split = DSPSplitComplex(realp: realPtr.baseAddress!, imagp: imagPtr.baseAddress!)
+ signal.withUnsafeBufferPointer { signalPtr in
+ signalPtr.baseAddress!.withMemoryRebound(to: DSPComplex.self, capacity: fftSize / 2) { complexPtr in
+ vDSP_ctoz(complexPtr, 2, &split, 1, vDSP_Length(fftSize / 2))
+ }
+ }
+ vDSP_fft_zrip(setup, &split, 1, log2n, FFTDirection(FFT_FORWARD))
+ spectrum = Spectrum(real: Array(realPtr), imag: Array(imagPtr))
+ }
+ }
+ return spectrum
+ }
+
+ private static func phatCrossCorrelation(
+ mic: Spectrum, reference: Spectrum, fftSize: Int, setup: FFTSetup, log2n: vDSP_Length
+ ) -> [Float] {
+ let halfN = fftSize / 2
+ var crossReal = [Float](repeating: 0, count: halfN)
+ var crossImag = [Float](repeating: 0, count: halfN)
+
+ for k in 0..<halfN {
+ let mr = mic.real[k], mi = mic.imag[k]
+ let rr = reference.real[k], ri = reference.imag[k]
+ crossReal[k] = mr * rr + mi * ri
+ crossImag[k] = mi * rr - mr * ri
+ }
+ // Bin 0 packs DC and Nyquist together in vDSP's real-FFT format; zeroed to avoid mixing them.
+ crossReal[0] = 0
+ crossImag[0] = 0
+
+ for k in 0..<halfN {
+ let magnitude = sqrt(crossReal[k] * crossReal[k] + crossImag[k] * crossImag[k])
+ guard magnitude > self.phatMagnitudeFloor else {
+ crossReal[k] = 0
+ crossImag[k] = 0
+ continue
+ }
+ crossReal[k] /= magnitude
+ crossImag[k] /= magnitude
+ }
+
+ var result = [Float](repeating: 0, count: fftSize)
+ crossReal.withUnsafeMutableBufferPointer { realPtr in
+ crossImag.withUnsafeMutableBufferPointer { imagPtr in
+ var split = DSPSplitComplex(realp: realPtr.baseAddress!, imagp: imagPtr.baseAddress!)
+ vDSP_fft_zrip(setup, &split, 1, log2n, FFTDirection(FFT_INVERSE))
+ result.withUnsafeMutableBufferPointer { resultPtr in
+ resultPtr.baseAddress!.withMemoryRebound(to: DSPComplex.self, capacity: halfN) { complexPtr in
+ vDSP_ztoc(&split, 1, complexPtr, 2, vDSP_Length(halfN))
+ }
+ }
+ }
+ }
+ var scale = Float(1.0 / Double(fftSize))
+ vDSP_vsmul(result, 1, &scale, &result, 1, vDSP_Length(fftSize))
+ return result
+ }
+
+ private static func shift(_ signal: [Float], bySeconds seconds: TimeInterval, sampleRate: Double, targetCount: Int) -> [Float] {
+ // An unusable delay means no reference, not a trap.
+ guard let offset = self.safeInt((seconds * sampleRate).rounded()) else {
+ return [Float](repeating: 0, count: targetCount)
+ }
+ var result = [Float](repeating: 0, count: targetCount)
+ for i in 0..<targetCount {
+ let sourceIndex = i - offset
+ guard sourceIndex >= 0, sourceIndex < signal.count else { continue }
+ result[i] = signal[sourceIndex]
+ }
+ return result
+ }
+
+ static func median<T: FloatingPoint>(_ values: [T]) -> T {
+ guard !values.isEmpty else { return 0 }
+ let sorted = values.sorted()
+ let mid = sorted.count / 2
+ return sorted.count % 2 == 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid]
+ }
+}
diff --git a/Sources/Fluid/Services/Meeting/MeetingProcessingPipeline.swift b/Sources/Fluid/Services/Meeting/MeetingProcessingPipeline.swift
index ea30f522..a617b5b7 100644
--- a/Sources/Fluid/Services/Meeting/MeetingProcessingPipeline.swift
+++ b/Sources/Fluid/Services/Meeting/MeetingProcessingPipeline.swift
@@ -187,6 +187,46 @@ nonisolated enum MeetingTurnSelection {
}
}
+/// Separates near-field speech (the user, inches from a personal mic) from far-field sound the same
+/// mic also hears — a TV across the room, the laptop speakers. Both are real speech, so a VAD passes
+/// both; only level separates them. Measured on a real session: user 0.0287 RMS (-30.8 dBFS) against
+/// room audio at 0.0023 (-52.4 dBFS).
+///
+/// The reference is the track's own loud end rather than an absolute dBFS value, so the rule travels
+/// across microphones and gain settings. It degrades safely: when a track holds nothing but distant
+/// audio the reference anchors on that audio and nothing is gated.
+nonisolated enum MeetingNearFieldGate {
+ /// Far enough below the user's own voice to clear room audio, with room to spare for their
+ /// quieter moments — the measured gap is 22 dB.
+ static let rejectionDepthDB: Double = 15
+ /// Nothing this quiet is intelligible near-field speech on any hardware; a backstop for tracks
+ /// whose loud end is itself noise.
+ static let absoluteFloorRMS: Double = 0.0015
+ /// Below this the reference is not a reliable picture of how loud the user gets.
+ static let minimumReferenceSeconds: TimeInterval = 3
+
+ /// Duration-weighted 75th percentile of turn loudness: robust to a handful of loud transients
+ /// without being dragged down by long stretches of quiet.
+ static func referenceRMS(turns: [(rms: Double, duration: TimeInterval)]) -> Double? {
+ let usable = turns.filter { $0.rms > 0 && $0.duration > 0 }
+ guard usable.reduce(0, { $0 + $1.duration }) >= Self.minimumReferenceSeconds else { return nil }
+ let sorted = usable.sorted { $0.rms < $1.rms }
+ let total = sorted.reduce(0) { $0 + $1.duration }
+ var accumulated: TimeInterval = 0
+ for entry in sorted {
+ accumulated += entry.duration
+ if accumulated >= total * 0.75 { return entry.rms }
+ }
+ return sorted.last?.rms
+ }
+
+ static func isNearField(rms: Double, reference: Double?) -> Bool {
+ guard rms >= Self.absoluteFloorRMS else { return false }
+ guard let reference, reference > 0 else { return true }
+ return rms >= reference * pow(10, -Self.rejectionDepthDB / 20)
+ }
+}
+
nonisolated enum MeetingLocalSpeakerEvidenceSelector {
static func candidate(
evidenceDurationByCluster: [SessionSpeakerID: TimeInterval],
@@ -278,7 +318,8 @@ private final class MeetingProviderLanguagePin {
@MainActor
final class MeetingProcessingPipeline: MeetingProcessingControlling {
- static let pipelineVersion = 3
+ /// Bump whenever classification rules change so a resumed run can't mix rules mid-session.
+ static let pipelineVersion = 6
/// Per-turn engines starve on short turns, and an all-empty chunk collapses to unlabeled.
static let perTurnTurnMergeGapSeconds = 5.0
@@ -319,6 +360,139 @@ final class MeetingProcessingPipeline: MeetingProcessingControlling {
return supporting.filter { $0.value > (echoed[$0.key] ?? 0) }
}
+ /// Reads `isLikelyEcho` (text-only), never `effectiveEcho`: signal evidence must not
+ /// influence which cluster gets elected "You".
+ nonisolated static func selectLocalCluster(
+ from turns: [StagedMicrophoneTurn],
+ prototypeSpeakerIDs: Set<SessionSpeakerID>
+ ) -> SessionSpeakerID? {
+ MeetingLocalSpeakerEvidenceSelector.candidate(
+ evidenceDurationByCluster: Self.localSpeakerEvidence(
+ from: turns.map {
+ (
+ clusterID: $0.clusterID, start: $0.start, end: $0.end,
+ overlapsRemote: $0.overlapsRemote, echoScored: $0.echoScored,
+ isEcho: $0.isLikelyEcho
+ )
+ }
+ ),
+ prototypeSpeakerIDs: prototypeSpeakerIDs
+ )
+ }
+
+ /// Why "You" was or was not elected. Without this the only visible symptom is an entire
+ /// microphone track collapsing to "Microphone / Unknown", which has several distinct causes.
+ nonisolated static func logLocalSpeakerElection(
+ turns: [StagedMicrophoneTurn],
+ prototypeSpeakerIDs: Set<SessionSpeakerID>,
+ index: MeetingSpeakerEmbeddingIndex?,
+ role: MeetingMicrophoneRole,
+ elected: SessionSpeakerID?
+ ) {
+ var supporting: [SessionSpeakerID: TimeInterval] = [:]
+ var echoed: [SessionSpeakerID: TimeInterval] = [:]
+ var skipped: [SessionSpeakerID: TimeInterval] = [:]
+ for turn in turns {
+ let duration = max(0, turn.end - turn.start)
+ if turn.isLikelyEcho {
+ echoed[turn.clusterID, default: 0] += duration
+ } else if turn.overlapsRemote, !turn.echoScored {
+ skipped[turn.clusterID, default: 0] += duration
+ } else {
+ supporting[turn.clusterID, default: 0] += duration
+ }
+ }
+ let clusters = Set(supporting.keys).union(echoed.keys).union(skipped.keys)
+ let rows = clusters
+ .map { id -> String in
+ let s = supporting[id] ?? 0, e = echoed[id] ?? 0, k = skipped[id] ?? 0
+ let proto = prototypeSpeakerIDs.contains(id) ? "yes" : "NO"
+ return String(
+ format: "%@ supporting=%.1fs echoed=%.1fs unscoredOverlap=%.1fs prototype=%@ netEvidence=%@",
+ id.uuidString.prefix(8).description, s, e, k, proto, s > e ? "counts" : "DROPPED"
+ )
+ }
+ .sorted()
+ // Pairwise prototype distance across the clusters that survived the echo filter: two
+ // fragments of one voice are what blocks the winner-margin rule from electing "You".
+ var distances: [String] = []
+ if let index {
+ let survivors = clusters.filter { (supporting[$0] ?? 0) > (echoed[$0] ?? 0) }.sorted {
+ $0.uuidString < $1.uuidString
+ }
+ for (offset, left) in survivors.enumerated() {
+ for right in survivors.dropFirst(offset + 1) {
+ guard let a = index.prototypes[left]?.embedding,
+ let b = index.prototypes[right]?.embedding,
+ let distance = MeetingSpeakerEmbeddingIndex.cosineDistance(a, b)
+ else { continue }
+ distances.append(String(
+ format: "%@↔%@ cosineDistance=%.3f (mergeThreshold=%.2f) %@",
+ left.uuidString.prefix(8).description, right.uuidString.prefix(8).description,
+ distance, index.maximumCosineDistance,
+ distance <= index.maximumCosineDistance ? "SAME VOICE" : "different"
+ ))
+ }
+ }
+ }
+ DebugLogger.shared.info(
+ "Local speaker election (role=\(role), elected=\(elected?.uuidString.prefix(8).description ?? "none")):\n "
+ + rows.joined(separator: "\n ")
+ + (distances.isEmpty ? "" : "\n " + distances.joined(separator: "\n ")),
+ source: "MeetingProcessingPipeline"
+ )
+ }
+
+ /// Drops turns the microphone only heard at a distance. They are not echo — a TV or another
+ /// room never matches the far end's words — so nothing downstream can catch them, and left in
+ /// they form a rival cluster that outweighs the user and blocks the "You" election entirely.
+ nonisolated static func rejectingFarField(_ turns: [StagedMicrophoneTurn]) -> [StagedMicrophoneTurn] {
+ let measured = turns.filter { $0.rms > 0 }
+ guard !measured.isEmpty else { return turns }
+ let reference = MeetingNearFieldGate.referenceRMS(
+ turns: measured.map { (rms: $0.rms, duration: max(0, $0.end - $0.start)) }
+ )
+ var kept: [StagedMicrophoneTurn] = []
+ var rejected: [StagedMicrophoneTurn] = []
+ for turn in turns {
+ // An unmeasured turn is kept: absence of a measurement is not evidence of distance.
+ if turn.rms <= 0 || MeetingNearFieldGate.isNearField(rms: turn.rms, reference: reference) {
+ kept.append(turn)
+ } else {
+ rejected.append(turn)
+ }
+ }
+ guard !rejected.isEmpty else { return turns }
+ let rejectedSeconds = rejected.reduce(0.0) { $0 + max(0, $1.end - $1.start) }
+ DebugLogger.shared.info(
+ String(
+ format: "Near-field gate: dropped %d of %d microphone turns (%.1fs) below reference %.5f RMS − %.0f dB",
+ rejected.count, turns.count, rejectedSeconds, reference ?? 0, MeetingNearFieldGate.rejectionDepthDB
+ ),
+ source: "MeetingProcessingPipeline"
+ )
+ return kept
+ }
+
+ /// Reads the chunk once and measures each turn's RMS. Failure degrades to zeros, which the gate
+ /// treats as unmeasured rather than as silence.
+ nonisolated static func turnLoudness(
+ fileURL: URL,
+ turns: [(start: TimeInterval, end: TimeInterval)]
+ ) -> [Double] {
+ guard let samples = try? Self.readSamples(fileURL: fileURL, startSeconds: 0, endSeconds: nil),
+ !samples.isEmpty
+ else { return Array(repeating: 0, count: turns.count) }
+ let sampleRate = 16_000.0
+ return turns.map { turn in
+ let first = max(0, Int(turn.start * sampleRate))
+ let last = min(samples.count, Int(turn.end * sampleRate))
+ guard last > first else { return 0 }
+ let sum = samples[first..<last].reduce(0.0) { $0 + Double($1) * Double($1) }
+ return (sum / Double(last - first)).squareRoot()
+ }
+ }
+
nonisolated static func remoteFallbackIntervals(
diarizedTurns: [(start: TimeInterval, end: TimeInterval)],
chunkOffset: TimeInterval,
@@ -342,7 +516,9 @@ final class MeetingProcessingPipeline: MeetingProcessingControlling {
var end: TimeInterval
}
- private struct StagedMicrophoneTurn {
+ /// Internal (not private) so tests can exercise `effectiveEcho` and local-speaker selection
+ /// directly against the pure helpers below.
+ struct StagedMicrophoneTurn {
var chunkID: MeetingAudioChunkID
var index: Int
var clusterID: SessionSpeakerID
@@ -351,9 +527,306 @@ final class MeetingProcessingPipeline: MeetingProcessingControlling {
var end: TimeInterval
var text: String
var overlapsRemote: Bool
+ /// Loudness of this turn's microphone audio, for the near-field gate. Zero when unmeasured.
+ var rms: Double = 0
+ /// Text-only, from `MeetingEchoDetector`. `localSpeakerEvidence` must keep reading this
+ /// field, never `effectiveEcho` — signal evidence must not influence local-speaker
+ /// election, or a misclassification could elect the far-end cluster as "You".
var isLikelyEcho = false
/// False when nothing scoreable overlapped: absence of a verdict is not evidence.
var echoScored = false
+ var signalVerdict: TurnEchoVerdict = .unknown
+ /// What the UI and exporter hide. Text and signal each get to say "echo", because they fail
+ /// independently: ASR garbles bleed differently from the far end's own transcript, defeating
+ /// text matching, while the signal reads it plainly (measured median 0.91 explained). Either
+ /// one is then vetoed by evidence of genuine local speech in the same turn.
+ ///
+ /// `isLikelyEcho` stays text-only and remains the sole input to the local-speaker election —
+ /// signal evidence must never reach it, or a misclassification could elect the far-end
+ /// cluster as "You" through the 1.75x winner rule.
+ var effectiveEcho: Bool {
+ (self.isLikelyEcho || self.signalVerdict == .echo) && self.signalVerdict != .containsLocalSpeech
+ }
+ }
+
+ // MARK: - Echo signal veto
+
+ nonisolated struct ReferenceSpan: Equatable {
+ var chunk: MeetingAudioChunk
+ var localRange: Range<TimeInterval>
+ var outputOffset: TimeInterval
+ }
+
+ /// Session time -> each app chunk's own decoded coordinates, keyed off `presentationStart`.
+ /// The two writers rotate independently and diverge permanently after a discontinuity on
+ /// either track, so app chunk N never lines up with mic chunk N.
+ nonisolated static func referenceSpans(
+ micSessionRange: (start: TimeInterval, end: TimeInterval),
+ appChunks: [MeetingAudioChunk],
+ origin: TimeInterval
+ ) -> [ReferenceSpan] {
+ appChunks.compactMap { chunk in
+ let chunkStart = chunk.presentationStart.seconds - origin
+ let chunkEnd = chunk.presentationEnd.seconds - origin
+ let overlapStart = max(chunkStart, micSessionRange.start)
+ let overlapEnd = min(chunkEnd, micSessionRange.end)
+ guard overlapEnd > overlapStart else { return nil }
+ return ReferenceSpan(
+ chunk: chunk,
+ localRange: (overlapStart - chunkStart)..<(overlapEnd - chunkStart),
+ outputOffset: overlapStart - micSessionRange.start
+ )
+ }
+ }
+
+ /// Concatenates the decoded slices for a mic chunk's time range, zero-filling any gap
+ /// (missing chunk, failed chunk, or a hole between chunks). Zero-fill is self-masking: a
+ /// zero-filled block has no reference energy, so the scorer's own floor already forces
+ /// those frames to NaN — no separate validity mask is needed.
+ nonisolated static func gatherReferenceAudio(
+ micSessionRange: (start: TimeInterval, end: TimeInterval),
+ appChunks: [MeetingAudioChunk],
+ origin: TimeInterval,
+ sessionDirectory: URL,
+ sampleRate: Double
+ ) -> [Float] {
+ let totalSamples = max(0, Int(((micSessionRange.end - micSessionRange.start) * sampleRate).rounded()))
+ guard totalSamples > 0 else { return [] }
+ var output = [Float](repeating: 0, count: totalSamples)
+ for span in Self.referenceSpans(micSessionRange: micSessionRange, appChunks: appChunks, origin: origin) {
+ guard let samples = try? Self.readSamples(
+ fileURL: span.chunk.fileURL(relativeTo: sessionDirectory),
+ startSeconds: span.localRange.lowerBound,
+ endSeconds: span.localRange.upperBound
+ ) else { continue }
+ let outStart = Int((span.outputOffset * sampleRate).rounded())
+ for (offset, sample) in samples.enumerated() {
+ let index = outStart + offset
+ guard index >= 0, index < output.count else { break }
+ output[index] = sample
+ }
+ }
+ return output
+ }
+
+ /// Guard interval around each recorded discontinuity on either track, excluded from both
+ /// delay estimation and scoring so a clock jump isn't read as correlated (or decorrelated) audio.
+ nonisolated static func discontinuityGuardIntervals(
+ micChunk: MeetingAudioChunk,
+ overlappingAppChunks: [MeetingAudioChunk],
+ origin: TimeInterval,
+ guardSeconds: TimeInterval
+ ) -> [(start: TimeInterval, end: TimeInterval)] {
+ (micChunk.discontinuities + overlappingAppChunks.flatMap(\.discontinuities)).compactMap { discontinuity in
+ guard let presentationTime = discontinuity.presentationTime else { return nil }
+ let time = presentationTime.seconds - origin
+ return (time - guardSeconds, time + guardSeconds)
+ }
+ }
+
+ nonisolated static func zeroingGuardedSamples(
+ _ samples: [Float],
+ chunkOffset: TimeInterval,
+ sampleRate: Double,
+ guardIntervals: [(start: TimeInterval, end: TimeInterval)]
+ ) -> [Float] {
+ guard !guardIntervals.isEmpty else { return samples }
+ var result = samples
+ for interval in guardIntervals {
+ let startIndex = max(0, Int(((interval.start - chunkOffset) * sampleRate).rounded()))
+ let endIndex = min(samples.count, Int(((interval.end - chunkOffset) * sampleRate).rounded()))
+ guard startIndex < endIndex else { continue }
+ for index in startIndex..<endIndex { result[index] = 0 }
+ }
+ return result
+ }
+
+ /// Post-hoc NaN mask rather than zeroing the scorer's inputs: zeroing would corrupt the
+ /// block-level fit for the valid frames sharing a block with a guarded one.
+ nonisolated static func maskingGuardedFrames(
+ _ scores: EchoFrameScores,
+ chunkOffset: TimeInterval,
+ sampleRate: Double,
+ guardIntervals: [(start: TimeInterval, end: TimeInterval)]
+ ) -> EchoFrameScores {
+ guard !guardIntervals.isEmpty else { return scores }
+ let frameSeconds = Double(MeetingEchoSignalScorer.frameLength) / sampleRate
+ var fractions = scores.fractions
+ for index in fractions.indices {
+ let frameStart = chunkOffset + Double(index) * scores.hopSeconds
+ let frameEnd = frameStart + frameSeconds
+ if guardIntervals.contains(where: { max($0.start, frameStart) < min($0.end, frameEnd) }) {
+ fractions[index] = .nan
+ }
+ }
+ return EchoFrameScores(fractions: fractions, hopSeconds: scores.hopSeconds)
+ }
+
+ /// Frames whose window overlaps the turn's span; the result is contiguous because frame
+ /// time is monotonic in index.
+ nonisolated static func turnVerdict(
+ _ scores: EchoFrameScores,
+ chunkOffset: TimeInterval,
+ turnStart: TimeInterval,
+ turnEnd: TimeInterval,
+ sampleRate: Double
+ ) -> TurnEchoVerdict {
+ let frameSeconds = Double(MeetingEchoSignalScorer.frameLength) / sampleRate
+ let overlapping = scores.fractions.indices.filter { index in
+ let frameStart = chunkOffset + Double(index) * scores.hopSeconds
+ let frameEnd = frameStart + frameSeconds
+ return frameEnd > turnStart && frameStart < turnEnd
+ }
+ guard !overlapping.isEmpty else { return .unknown }
+ let subset = EchoFrameScores(fractions: overlapping.map { scores.fractions[$0] }, hopSeconds: scores.hopSeconds)
+ let result = MeetingEchoSignalScorer.verdict(subset)
+ Self.logTurnFrameStats(subset, turnStart: turnStart, turnEnd: turnEnd, verdict: result)
+ return result
+ }
+
+ /// Frame-level picture behind a turn's verdict. The rescue rule uses an absolute low-run
+ /// threshold, so long turns need their run length read as a share of the turn, not in seconds.
+ nonisolated static func logTurnFrameStats(
+ _ scores: EchoFrameScores,
+ turnStart: TimeInterval,
+ turnEnd: TimeInterval,
+ verdict: TurnEchoVerdict
+ ) {
+ let scoreable = scores.fractions.filter { !$0.isNaN }
+ guard !scoreable.isEmpty else { return }
+ let sorted = scoreable.sorted()
+ let median = sorted[sorted.count / 2]
+ var longestLowRun = 0
+ var currentRun = 0
+ for value in scores.fractions {
+ if !value.isNaN, value < MeetingEchoSignalScorer.localSpeechFractionThreshold {
+ currentRun += 1
+ longestLowRun = max(longestLowRun, currentRun)
+ } else if !value.isNaN {
+ currentRun = 0
+ }
+ }
+ let turnSeconds = max(0.001, turnEnd - turnStart)
+ let lowRunSeconds = Double(longestLowRun) * scores.hopSeconds
+ DebugLogger.shared.info(
+ String(
+ format: "[echoframes] turn=[%.1f-%.1f] %.1fs median=%.2f scoreable=%.0f%% lowRun=%.2fs (%.1f%% of turn) verdict=%@",
+ turnStart, turnEnd, turnSeconds, median,
+ 100 * Double(scoreable.count) / Double(scores.fractions.count),
+ lowRunSeconds, 100 * lowRunSeconds / turnSeconds, String(describing: verdict)
+ ),
+ source: "MeetingProcessingPipeline"
+ )
+ }
+
+ /// A capture epoch ends at any discontinuity on either track; a rolling delay consensus must
+ /// never survive one — measured drift (~6.4 ppm, ~23ms/hour) makes a stale offset wrong on
+ /// the far side of a jump.
+ nonisolated static func epochBoundaries(
+ micChunks: [MeetingAudioChunk],
+ appChunks: [MeetingAudioChunk],
+ origin: TimeInterval
+ ) -> [TimeInterval] {
+ (micChunks + appChunks).flatMap { chunk in
+ chunk.discontinuities.compactMap { $0.presentationTime.map { $0.seconds - origin } }
+ }.sorted()
+ }
+
+ private struct EchoDelayEpochState {
+ var boundaries: [TimeInterval]
+ var boundaryIndex = 0
+ var acceptedDelays: [TimeInterval] = []
+
+ mutating func advance(toChunkEnd chunkEnd: TimeInterval) {
+ while self.boundaryIndex < self.boundaries.count, self.boundaries[self.boundaryIndex] <= chunkEnd {
+ self.acceptedDelays.removeAll()
+ self.boundaryIndex += 1
+ }
+ }
+ }
+
+ /// No confident per-chunk estimate and no consensus yet (e.g. the first chunks of a quiet
+ /// meeting) leaves the verdict `.unknown` for that chunk — acceptable, since `.unknown`
+ /// never vetoes.
+ nonisolated static func resolvedDelay(
+ estimate: DelayEstimate?,
+ acceptedDelaysInEpoch: [TimeInterval]
+ ) -> TimeInterval? {
+ if let estimate, estimate.confidence >= MeetingEchoSignalScorer.minimumDelayConfidence {
+ return estimate.seconds
+ }
+ guard !acceptedDelaysInEpoch.isEmpty else { return nil }
+ return MeetingEchoSignalScorer.median(acceptedDelaysInEpoch)
+ }
+
+ nonisolated struct EchoScoringOutcome {
+ var verdicts: [Int: TurnEchoVerdict]
+ var acceptedDelaySeconds: TimeInterval?
+ }
+
+ /// Every failure here (missing/corrupt reference audio, decode errors, bad timing math, ...)
+ /// degrades to `.unknown` rather than propagating: a sick application-audio track must never
+ /// take down an otherwise-healthy microphone chunk.
+ nonisolated static func computeEchoVerdicts(
+ micChunk: MeetingAudioChunk,
+ micChunkURL: URL,
+ chunkOffset: TimeInterval,
+ chunkDuration: TimeInterval,
+ turns: [(index: Int, start: TimeInterval, end: TimeInterval)],
+ applicationTrack: MeetingAudioTrack,
+ origin: TimeInterval,
+ sessionDirectory: URL,
+ acceptedDelaysInEpoch: [TimeInterval]
+ ) throws -> EchoScoringOutcome {
+ let sampleRate = 16_000.0
+ let micSamples = try Self.readSamples(fileURL: micChunkURL, startSeconds: 0, endSeconds: nil)
+ guard !micSamples.isEmpty else { return EchoScoringOutcome(verdicts: [:], acceptedDelaySeconds: nil) }
+
+ let micSessionRange = (start: chunkOffset, end: chunkOffset + chunkDuration)
+ let referenceSamples = Self.gatherReferenceAudio(
+ micSessionRange: micSessionRange,
+ appChunks: applicationTrack.chunks,
+ origin: origin,
+ sessionDirectory: sessionDirectory,
+ sampleRate: sampleRate
+ )
+
+ let overlappingAppChunks = applicationTrack.chunks.filter { appChunk in
+ let start = appChunk.presentationStart.seconds - origin
+ let end = appChunk.presentationEnd.seconds - origin
+ return end > micSessionRange.start && start < micSessionRange.end
+ }
+ let guardIntervals = Self.discontinuityGuardIntervals(
+ micChunk: micChunk,
+ overlappingAppChunks: overlappingAppChunks,
+ origin: origin,
+ guardSeconds: MeetingEchoSignalScorer.blockSeconds
+ )
+
+ let guardedMic = Self.zeroingGuardedSamples(micSamples, chunkOffset: chunkOffset, sampleRate: sampleRate, guardIntervals: guardIntervals)
+ let guardedReference = Self.zeroingGuardedSamples(referenceSamples, chunkOffset: chunkOffset, sampleRate: sampleRate, guardIntervals: guardIntervals)
+ let estimate = MeetingEchoSignalScorer.estimateDelay(
+ mic: guardedMic, reference: guardedReference, sampleRate: sampleRate, maxLagSeconds: 0.5
+ )
+ guard let delaySeconds = Self.resolvedDelay(estimate: estimate, acceptedDelaysInEpoch: acceptedDelaysInEpoch) else {
+ return EchoScoringOutcome(verdicts: [:], acceptedDelaySeconds: nil)
+ }
+ let acceptedDelaySeconds = (estimate?.confidence ?? 0) >= MeetingEchoSignalScorer.minimumDelayConfidence
+ ? estimate?.seconds
+ : nil
+
+ let rawScores = MeetingEchoSignalScorer.explainedFractions(
+ mic: micSamples, reference: referenceSamples, sampleRate: sampleRate, delaySeconds: delaySeconds
+ )
+ let scores = Self.maskingGuardedFrames(rawScores, chunkOffset: chunkOffset, sampleRate: sampleRate, guardIntervals: guardIntervals)
+
+ var verdicts: [Int: TurnEchoVerdict] = [:]
+ for turn in turns {
+ verdicts[turn.index] = Self.turnVerdict(
+ scores, chunkOffset: chunkOffset, turnStart: turn.start, turnEnd: turn.end, sampleRate: sampleRate
+ )
+ }
+ return EchoScoringOutcome(verdicts: verdicts, acceptedDelaySeconds: acceptedDelaySeconds)
}
private struct Accumulator {
@@ -849,6 +1322,14 @@ final class MeetingProcessingPipeline: MeetingProcessingControlling {
skippedChunkIDs: inout [MeetingAudioChunkID]
) async throws {
let diarizer = SpeakerDiarizationService()
+ let applicationTrack = session.audioTracks.first(where: { $0.kind == .applicationAudio })
+ var epochState = EchoDelayEpochState(
+ boundaries: Self.epochBoundaries(
+ micChunks: track.chunks,
+ appChunks: applicationTrack?.chunks ?? [],
+ origin: context.origin
+ )
+ )
var stagedTurns: [StagedMicrophoneTurn] = []
for chunk in track.chunks where chunk.finalizationState == .finalized {
let accumulatorSnapshot = accumulator
@@ -860,6 +1341,8 @@ final class MeetingProcessingPipeline: MeetingProcessingControlling {
diarizer: diarizer,
context: context,
remoteSpeech: remoteSpeech,
+ applicationTrack: applicationTrack,
+ epochState: &epochState,
accumulator: &accumulator,
stagedTurns: &stagedTurns
)
@@ -886,6 +1369,8 @@ final class MeetingProcessingPipeline: MeetingProcessingControlling {
diarizer: SpeakerDiarizationService,
context: ProcessingContext,
remoteSpeech: [TimelineInterval],
+ applicationTrack: MeetingAudioTrack?,
+ epochState: inout EchoDelayEpochState,
accumulator: inout Accumulator,
stagedTurns: inout [StagedMicrophoneTurn]
) async throws {
@@ -894,6 +1379,7 @@ final class MeetingProcessingPipeline: MeetingProcessingControlling {
let chunkDuration = try await Task.detached(priority: .userInitiated) {
try Self.audioDuration(url)
}.value
+ epochState.advance(toChunkEnd: chunkOffset + chunkDuration)
if SpeakerDiarizationService.isSupported {
do {
let diarization = try await diarizer.diarizeWithProfiles(
@@ -925,7 +1411,46 @@ final class MeetingProcessingPipeline: MeetingProcessingControlling {
clusterIDByLabel[turn.speakerLabel] = resolved.speakerID
usedClusterIDs.insert(resolved.speakerID)
}
- for (index, turn, text) in transcribedTurns {
+
+ var signalVerdictByIndex: [Int: TurnEchoVerdict] = [:]
+ if let applicationTrack {
+ let turnRanges = transcribedTurns.map {
+ (index: $0.index, start: chunkOffset + $0.turn.startSeconds, end: chunkOffset + $0.turn.endSeconds)
+ }
+ let acceptedDelaysInEpoch = epochState.acceptedDelays
+ do {
+ let outcome = try await Task.detached(priority: .userInitiated) {
+ try Self.computeEchoVerdicts(
+ micChunk: chunk,
+ micChunkURL: url,
+ chunkOffset: chunkOffset,
+ chunkDuration: chunkDuration,
+ turns: turnRanges,
+ applicationTrack: applicationTrack,
+ origin: context.origin,
+ sessionDirectory: context.sessionDirectory,
+ acceptedDelaysInEpoch: acceptedDelaysInEpoch
+ )
+ }.value
+ signalVerdictByIndex = outcome.verdicts
+ if let acceptedDelaySeconds = outcome.acceptedDelaySeconds {
+ epochState.acceptedDelays.append(acceptedDelaySeconds)
+ }
+ } catch {
+ if error is CancellationError { throw error }
+ DebugLogger.shared.warning(
+ "Meeting echo signal scoring chunk \(chunk.id) failed; leaving turns unscored: \(error)",
+ source: "MeetingProcessingPipeline"
+ )
+ }
+ }
+
+ let turnLoudness = Self.turnLoudness(
+ fileURL: url,
+ turns: transcribedTurns.map { (start: $0.turn.startSeconds, end: $0.turn.endSeconds) }
+ )
+ for (offset, element) in transcribedTurns.enumerated() {
+ let (index, turn, text) = element
let start = chunkOffset + turn.startSeconds
let end = chunkOffset + turn.endSeconds
let overlapsRemote = remoteSpeech.contains {
@@ -940,7 +1465,9 @@ final class MeetingProcessingPipeline: MeetingProcessingControlling {
start: start,
end: end,
text: text,
- overlapsRemote: overlapsRemote
+ overlapsRemote: overlapsRemote,
+ rms: turnLoudness.indices.contains(offset) ? turnLoudness[offset] : 0,
+ signalVerdict: signalVerdictByIndex[index] ?? .unknown
))
}
return
@@ -948,9 +1475,19 @@ final class MeetingProcessingPipeline: MeetingProcessingControlling {
} catch {
if error is CancellationError { throw error }
if case MeetingProcessingError.audioUnreadable = error { throw error }
- let reason = Self.isEmptyTurnFallback(error) ? "every turn transcribed empty" : "diarization failed"
+ // Diarization worked and every turn still came back empty: the microphone holds no
+ // intelligible speech here. Re-transcribing the whole chunk only coaxes the
+ // recognizer into hallucinating over near-silence, and that text lands unattributed
+ // and unscoreable — measured at 0.31 text containment and no signal verdict at all.
+ if Self.isEmptyTurnFallback(error) {
+ DebugLogger.shared.warning(
+ "Meeting microphone chunk \(chunk.id): no intelligible speech, emitting nothing",
+ source: "MeetingProcessingPipeline"
+ )
+ return
+ }
DebugLogger.shared.warning(
- "Meeting microphone chunk \(chunk.id) fell back to an unlabeled transcript (\(reason)): \(error)",
+ "Meeting microphone chunk \(chunk.id) fell back to an unlabeled transcript (diarization failed): \(error)",
source: "MeetingProcessingPipeline"
)
}
@@ -985,9 +1522,15 @@ final class MeetingProcessingPipeline: MeetingProcessingControlling {
private func finishMicrophoneTrack(
_ track: MeetingAudioTrack,
session: MeetingSession,
- stagedTurns: [StagedMicrophoneTurn],
+ stagedTurns allStagedTurns: [StagedMicrophoneTurn],
accumulator: inout Accumulator
) {
+ // Session-wide, never per chunk: a chunk holding only distant audio would otherwise take
+ // that audio as its own reference and gate nothing.
+ let stagedTurns = session.selectedMicrophone.role == .personal
+ ? Self.rejectingFarField(allStagedTurns)
+ : allStagedTurns
+
if session.mode == .inRoom {
for turn in stagedTurns {
let isNewSpeaker = !accumulator.speakers.contains { $0.id == turn.clusterID }
@@ -1047,20 +1590,17 @@ final class MeetingProcessingPipeline: MeetingProcessingControlling {
}
}
+ let prototypeSpeakerIDs = accumulator.embeddingIndexByTrack[.microphone]?.speakerIDs ?? []
let localClusterID = session.selectedMicrophone.role == .personal
- ? MeetingLocalSpeakerEvidenceSelector.candidate(
- evidenceDurationByCluster: Self.localSpeakerEvidence(
- from: classifiedTurns.map {
- (
- clusterID: $0.clusterID, start: $0.start, end: $0.end,
- overlapsRemote: $0.overlapsRemote, echoScored: $0.echoScored,
- isEcho: $0.isLikelyEcho
- )
- }
- ),
- prototypeSpeakerIDs: accumulator.embeddingIndexByTrack[.microphone]?.speakerIDs ?? []
- )
+ ? Self.selectLocalCluster(from: classifiedTurns, prototypeSpeakerIDs: prototypeSpeakerIDs)
: nil
+ Self.logLocalSpeakerElection(
+ turns: classifiedTurns,
+ prototypeSpeakerIDs: prototypeSpeakerIDs,
+ index: accumulator.embeddingIndexByTrack[.microphone],
+ role: session.selectedMicrophone.role,
+ elected: localClusterID
+ )
if let localClusterID,
let evidenceTurn = classifiedTurns.first(where: { $0.clusterID == localClusterID })
{
@@ -1082,7 +1622,7 @@ final class MeetingProcessingPipeline: MeetingProcessingControlling {
)
for turn in classifiedTurns {
let isLocalCluster = turn.clusterID == localClusterID
- let isCleanLocalTurn = isLocalCluster && !turn.isLikelyEcho
+ let isCleanLocalTurn = isLocalCluster && !turn.effectiveEcho
accumulator.segments.append(Self.segment(
key: "microphone:\(turn.chunkID.uuidString):\(turn.index)",
trackID: track.id,
@@ -1091,7 +1631,7 @@ final class MeetingProcessingPipeline: MeetingProcessingControlling {
end: turn.end,
text: turn.text,
overlap: turn.overlapsRemote ? .overlapsOtherTrack : .none,
- isLikelyEcho: isLocalCluster ? false : turn.isLikelyEcho
+ isLikelyEcho: isLocalCluster ? false : turn.effectiveEcho
))
}
}
diff --git a/Tests/FluidDictationIntegrationTests/MeetingEchoSignalScorerTests.swift b/Tests/FluidDictationIntegrationTests/MeetingEchoSignalScorerTests.swift
new file mode 100644
index 00000000..780ca87a
--- /dev/null
+++ b/Tests/FluidDictationIntegrationTests/MeetingEchoSignalScorerTests.swift
@@ -0,0 +1,392 @@
+@testable import FluidVoice_Debug
+import Foundation
+import XCTest
+
+final class MeetingEchoSignalScorerTests: XCTestCase {
+ private let sampleRate = 16000.0
+ private var hopSeconds: Double { Double(MeetingEchoSignalScorer.hopLength) / self.sampleRate }
+ /// Tight enough to catch the sidelobe/wrong-sign regressions; the fixed estimator errs by 0 samples.
+ private var delayAccuracySeconds: Double { 2.0 / self.sampleRate }
+
+ func testEstimateDelayRecoversPositiveLag() throws {
+ let delaySamples = 400
+ var lcg = LCG(seed: 1)
+ let reference = self.bandLimitedNoise(count: 12000, generator: &lcg)
+ var noiseLCG = LCG(seed: 2)
+ let mic = self.delayedAndScaled(reference, bySamples: delaySamples, scale: 0.5, noiseAmplitude: 0.01, generator: &noiseLCG)
+
+ let estimate = try XCTUnwrap(
+ MeetingEchoSignalScorer.estimateDelay(mic: mic, reference: reference, sampleRate: self.sampleRate, maxLagSeconds: 0.5)
+ )
+ let expectedSeconds = Double(delaySamples) / self.sampleRate
+ XCTAssertEqual(estimate.seconds, expectedSeconds, accuracy: self.delayAccuracySeconds)
+ XCTAssertGreaterThan(estimate.confidence, MeetingEchoSignalScorer.minimumDelayConfidence)
+ }
+
+ func testEstimateDelayRecoversNegativeLag() throws {
+ let delaySamples = -350
+ var lcg = LCG(seed: 3)
+ let reference = self.bandLimitedNoise(count: 12000, generator: &lcg)
+ var noiseLCG = LCG(seed: 4)
+ let mic = self.delayedAndScaled(reference, bySamples: delaySamples, scale: 0.6, noiseAmplitude: 0.01, generator: &noiseLCG)
+
+ let estimate = try XCTUnwrap(
+ MeetingEchoSignalScorer.estimateDelay(mic: mic, reference: reference, sampleRate: self.sampleRate, maxLagSeconds: 0.5)
+ )
+ let expectedSeconds = Double(delaySamples) / self.sampleRate
+ XCTAssertEqual(estimate.seconds, expectedSeconds, accuracy: self.delayAccuracySeconds)
+ XCTAssertGreaterThan(estimate.confidence, MeetingEchoSignalScorer.minimumDelayConfidence)
+ }
+
+ func testEstimateDelayRecoversLagWithInvertedPolarity() throws {
+ // Inverted polarity puts the true peak negative; signed argmax used to pick a sidelobe.
+ let delaySamples = 400
+ var lcg = LCG(seed: 60)
+ let reference = self.bandLimitedNoise(count: 12000, generator: &lcg)
+ var noiseLCG = LCG(seed: 61)
+ let mic = self.delayedAndScaled(reference, bySamples: delaySamples, scale: -0.5, noiseAmplitude: 0.01, generator: &noiseLCG)
+
+ let estimate = try XCTUnwrap(
+ MeetingEchoSignalScorer.estimateDelay(mic: mic, reference: reference, sampleRate: self.sampleRate, maxLagSeconds: 0.5)
+ )
+ let expectedSeconds = Double(delaySamples) / self.sampleRate
+ XCTAssertEqual(estimate.seconds, expectedSeconds, accuracy: self.delayAccuracySeconds)
+ XCTAssertGreaterThan(estimate.confidence, MeetingEchoSignalScorer.minimumDelayConfidence)
+ }
+
+ func testEstimateDelayReturnsNilOnSilence() {
+ var lcg = LCG(seed: 5)
+ let tiny = self.bandLimitedNoise(count: 8000, generator: &lcg).map { $0 * 1e-6 }
+ var lcg2 = LCG(seed: 6)
+ let tiny2 = self.bandLimitedNoise(count: 8000, generator: &lcg2).map { $0 * 1e-6 }
+ XCTAssertNil(MeetingEchoSignalScorer.estimateDelay(mic: tiny, reference: tiny2, sampleRate: self.sampleRate, maxLagSeconds: 0.5))
+ }
+
+ func testEstimateDelayReturnsNilForSubFrameInput() {
+ let mic = [Float](repeating: 0.1, count: 100)
+ let reference = [Float](repeating: 0.1, count: 100)
+ XCTAssertNil(MeetingEchoSignalScorer.estimateDelay(mic: mic, reference: reference, sampleRate: self.sampleRate, maxLagSeconds: 0.5))
+ }
+
+ func testEstimateDelayHandlesMismatchedLengths() throws {
+ let delaySamples = 200
+ var lcg = LCG(seed: 62)
+ let reference = self.bandLimitedNoise(count: 12000, generator: &lcg)
+ var noiseLCG = LCG(seed: 63)
+ let fullMic = self.delayedAndScaled(reference, bySamples: delaySamples, scale: 0.5, noiseAmplitude: 0.01, generator: &noiseLCG)
+ let mic = Array(fullMic.prefix(9000))
+
+ let estimate = try XCTUnwrap(
+ MeetingEchoSignalScorer.estimateDelay(mic: mic, reference: reference, sampleRate: self.sampleRate, maxLagSeconds: 0.5)
+ )
+ let expectedSeconds = Double(delaySamples) / self.sampleRate
+ XCTAssertEqual(estimate.seconds, expectedSeconds, accuracy: self.delayAccuracySeconds)
+ }
+
+ func testEstimateDelayHandlesDelayExceedingSignalLength() {
+ var lcg = LCG(seed: 64)
+ let reference = self.bandLimitedNoise(count: 2000, generator: &lcg)
+ var noiseLCG = LCG(seed: 65)
+ // Echo lies entirely outside the window; must not crash, whatever it returns.
+ let mic = self.delayedAndScaled(reference, bySamples: 5000, scale: 0.5, noiseAmplitude: 0.01, generator: &noiseLCG)
+ _ = MeetingEchoSignalScorer.estimateDelay(mic: mic, reference: reference, sampleRate: self.sampleRate, maxLagSeconds: 0.5)
+ }
+
+ func testEstimateDelayHandlesMaxLagBeyondSignalLength() throws {
+ let delaySamples = 100
+ var lcg = LCG(seed: 66)
+ let reference = self.bandLimitedNoise(count: 2000, generator: &lcg)
+ var noiseLCG = LCG(seed: 67)
+ let mic = self.delayedAndScaled(reference, bySamples: delaySamples, scale: 0.5, noiseAmplitude: 0.01, generator: &noiseLCG)
+
+ let estimate = try XCTUnwrap(
+ MeetingEchoSignalScorer.estimateDelay(mic: mic, reference: reference, sampleRate: self.sampleRate, maxLagSeconds: 1000.0)
+ )
+ let expectedSeconds = Double(delaySamples) / self.sampleRate
+ XCTAssertEqual(estimate.seconds, expectedSeconds, accuracy: self.delayAccuracySeconds)
+ }
+
+ func testEstimateDelayReturnsNilForNonFiniteMaxLag() {
+ var lcg = LCG(seed: 68)
+ let reference = self.bandLimitedNoise(count: 2000, generator: &lcg)
+ var noiseLCG = LCG(seed: 69)
+ let mic = self.delayedAndScaled(reference, bySamples: 100, scale: 0.5, noiseAmplitude: 0.01, generator: &noiseLCG)
+ XCTAssertNil(MeetingEchoSignalScorer.estimateDelay(mic: mic, reference: reference, sampleRate: self.sampleRate, maxLagSeconds: .nan))
+ XCTAssertNil(
+ MeetingEchoSignalScorer.estimateDelay(mic: mic, reference: reference, sampleRate: self.sampleRate, maxLagSeconds: .infinity)
+ )
+ }
+
+ func testPureEchoScoresHighAndVerdictIsEcho() {
+ var lcg = LCG(seed: 10)
+ let reference = self.bandLimitedNoise(count: Int(3.0 * self.sampleRate), generator: &lcg)
+ // Multi-tap IR so the fixture isn't trivially cancelled by a one-tap model.
+ let taps: [(delay: Int, gain: Float)] = [(150, 0.5), (190, 0.15), (230, 0.08), (270, 0.04), (310, 0.02)]
+ var noiseLCG = LCG(seed: 11)
+ let mic = self.multiTapEcho(reference, taps: taps, noiseAmplitude: 0.005, generator: &noiseLCG)
+
+ let scores = MeetingEchoSignalScorer.explainedFractions(
+ mic: mic, reference: reference, sampleRate: self.sampleRate, delaySeconds: Double(taps[0].delay) / self.sampleRate
+ )
+ let scoreable = scores.fractions.filter { !$0.isNaN }
+ XCTAssertFalse(scoreable.isEmpty)
+ XCTAssertGreaterThanOrEqual(MeetingEchoSignalScorer.median(scoreable), 0.5)
+
+ let verdict = MeetingEchoSignalScorer.verdict(scores)
+ XCTAssertEqual(verdict, .echo)
+ }
+
+ func testLocalSpeechOnlyIsUncorrelatedAndVerdictIsLocalSpeech() {
+ var refLCG = LCG(seed: 20)
+ let reference = self.bandLimitedNoise(count: Int(3.0 * self.sampleRate), generator: &refLCG)
+ var micLCG = LCG(seed: 21)
+ let mic = self.bandLimitedNoise(count: Int(3.0 * self.sampleRate), generator: &micLCG)
+
+ let scores = MeetingEchoSignalScorer.explainedFractions(
+ mic: mic, reference: reference, sampleRate: self.sampleRate, delaySeconds: 0
+ )
+ let verdict = MeetingEchoSignalScorer.verdict(scores)
+ XCTAssertEqual(verdict, .containsLocalSpeech)
+ }
+
+ func testDoubleTalkBurstRescuesTurnAsLocalSpeech() {
+ var refLCG = LCG(seed: 30)
+ let totalCount = Int(3.0 * self.sampleRate)
+ let reference = self.bandLimitedNoise(count: totalCount, generator: &refLCG)
+ let delaySamples = 150
+ var noiseLCG = LCG(seed: 31)
+ var mic = self.delayedAndScaled(reference, bySamples: delaySamples, scale: 0.5, noiseAmplitude: 0.005, generator: &noiseLCG)
+
+ // Real double talk is additive, not replacing. Rescue needs ~1.86x the echo energy;
+ // 1.2 against the echo's 0.5 tap gain gives ~5.76x, clear of per-frame estimation noise.
+ var burstLCG = LCG(seed: 32)
+ let burstCount = Int(1.0 * self.sampleRate)
+ let burstStart = (totalCount - burstCount) / 2
+ let burst = self.bandLimitedNoise(count: burstCount, generator: &burstLCG)
+ for i in 0..<burstCount {
+ mic[burstStart + i] += burst[i] * 1.2
+ }
+
+ let scores = MeetingEchoSignalScorer.explainedFractions(
+ mic: mic, reference: reference, sampleRate: self.sampleRate, delaySeconds: Double(delaySamples) / self.sampleRate
+ )
+ let verdict = MeetingEchoSignalScorer.verdict(scores)
+ XCTAssertEqual(verdict, .containsLocalSpeech)
+ }
+
+ /// A long turn of pure bleed picks up a brief low-scoring run from estimation noise. Measured on
+ /// a real speakerphone session: 0.75s inside a 22.4s turn at median 0.91, which the absolute
+ /// rescue rule read as local speech and published as a visible duplicate of the far end.
+ func testBriefLowRunInLongExplainedTurnIsNotRescued() {
+ var refLCG = LCG(seed: 90)
+ let totalCount = Int(22.0 * self.sampleRate)
+ let reference = self.bandLimitedNoise(count: totalCount, generator: &refLCG)
+ let delaySamples = 150
+ var noiseLCG = LCG(seed: 91)
+ var mic = self.delayedAndScaled(reference, bySamples: delaySamples, scale: 0.5, noiseAmplitude: 0.005, generator: &noiseLCG)
+
+ // 0.8s of unexplained audio — over the absolute rescue floor, 3.6% of the turn.
+ var burstLCG = LCG(seed: 92)
+ let burstCount = Int(0.8 * self.sampleRate)
+ let burstStart = totalCount / 2
+ let burst = self.bandLimitedNoise(count: burstCount, generator: &burstLCG)
+ for i in 0..<burstCount {
+ mic[burstStart + i] += burst[i] * 1.2
+ }
+
+ let scores = MeetingEchoSignalScorer.explainedFractions(
+ mic: mic, reference: reference, sampleRate: self.sampleRate, delaySeconds: Double(delaySamples) / self.sampleRate
+ )
+ XCTAssertEqual(MeetingEchoSignalScorer.verdict(scores), .echo)
+ }
+
+ /// The same absolute run length inside a short turn is a real interjection, and must survive.
+ func testSameRunLengthInShortTurnStillRescues() {
+ var refLCG = LCG(seed: 93)
+ let totalCount = Int(3.0 * self.sampleRate)
+ let reference = self.bandLimitedNoise(count: totalCount, generator: &refLCG)
+ let delaySamples = 150
+ var noiseLCG = LCG(seed: 94)
+ var mic = self.delayedAndScaled(reference, bySamples: delaySamples, scale: 0.5, noiseAmplitude: 0.005, generator: &noiseLCG)
+
+ var burstLCG = LCG(seed: 95)
+ let burstCount = Int(0.8 * self.sampleRate)
+ let burstStart = (totalCount - burstCount) / 2
+ let burst = self.bandLimitedNoise(count: burstCount, generator: &burstLCG)
+ for i in 0..<burstCount {
+ mic[burstStart + i] += burst[i] * 1.2
+ }
+
+ let scores = MeetingEchoSignalScorer.explainedFractions(
+ mic: mic, reference: reference, sampleRate: self.sampleRate, delaySeconds: Double(delaySamples) / self.sampleRate
+ )
+ XCTAssertEqual(MeetingEchoSignalScorer.verdict(scores), .containsLocalSpeech)
+ }
+
+ func testQuietAdditiveInterjectionDoesNotRescueTurn() {
+ var refLCG = LCG(seed: 33)
+ let totalCount = Int(3.0 * self.sampleRate)
+ let reference = self.bandLimitedNoise(count: totalCount, generator: &refLCG)
+ let delaySamples = 150
+ var noiseLCG = LCG(seed: 34)
+ var mic = self.delayedAndScaled(reference, bySamples: delaySamples, scale: 0.5, noiseAmplitude: 0.005, generator: &noiseLCG)
+
+ // ~0.36x the echo energy, under the 1.86x rescue floor: a quiet interjection must not rescue.
+ var burstLCG = LCG(seed: 35)
+ let burstCount = Int(1.0 * self.sampleRate)
+ let burstStart = (totalCount - burstCount) / 2
+ let burst = self.bandLimitedNoise(count: burstCount, generator: &burstLCG)
+ for i in 0..<burstCount {
+ mic[burstStart + i] += burst[i] * 0.3
+ }
+
+ let scores = MeetingEchoSignalScorer.explainedFractions(
+ mic: mic, reference: reference, sampleRate: self.sampleRate, delaySeconds: Double(delaySamples) / self.sampleRate
+ )
+ let verdict = MeetingEchoSignalScorer.verdict(scores)
+ XCTAssertEqual(verdict, .echo)
+ }
+
+ func testSilentReferenceProducesNaNAndVerdictIsUnknownNotLocalSpeech() {
+ let count = Int(3.0 * self.sampleRate)
+ let reference = [Float](repeating: 0, count: count)
+ var micLCG = LCG(seed: 40)
+ let mic = self.bandLimitedNoise(count: count, generator: &micLCG)
+
+ let scores = MeetingEchoSignalScorer.explainedFractions(
+ mic: mic, reference: reference, sampleRate: self.sampleRate, delaySeconds: 0
+ )
+ XCTAssertTrue(scores.fractions.allSatisfy(\.isNaN), "absence of reference energy must not be scoreable")
+
+ let verdict = MeetingEchoSignalScorer.verdict(scores)
+ XCTAssertEqual(verdict, .unknown)
+ }
+
+ func testLowButNonzeroReferenceYieldsNaNFrames() {
+ let count = Int(3.0 * self.sampleRate)
+ var refLCG = LCG(seed: 80)
+ // Below minimumSignalRMS but not silent: the old floor was ~10 orders too small to catch it.
+ let reference = self.bandLimitedNoise(count: count, generator: &refLCG).map { $0 * 5e-5 }
+ var micLCG = LCG(seed: 81)
+ let mic = self.bandLimitedNoise(count: count, generator: &micLCG)
+
+ let scores = MeetingEchoSignalScorer.explainedFractions(
+ mic: mic, reference: reference, sampleRate: self.sampleRate, delaySeconds: 0
+ )
+ XCTAssertTrue(scores.fractions.allSatisfy(\.isNaN))
+ }
+
+ func testVerdictWithMostlyNaNInputIsUnknown() {
+ var fractions = [Double](repeating: .nan, count: 40)
+ fractions[0] = 0.9
+ fractions[1] = 0.85
+ let scores = EchoFrameScores(fractions: fractions, hopSeconds: self.hopSeconds)
+ let verdict = MeetingEchoSignalScorer.verdict(scores)
+ XCTAssertEqual(verdict, .unknown)
+ }
+
+ func testVerdictWithMostlyNaNButUnambiguousLocalSpeechRescues() {
+ // Unambiguous local speech surrounded by NaN must rescue, not fall through the coverage gate.
+ let lowRunFrames = Int((1.28 / self.hopSeconds).rounded(.up))
+ var fractions = [Double](repeating: .nan, count: lowRunFrames + 40)
+ for i in 0..<lowRunFrames {
+ fractions[i] = 0.1
+ }
+ let scores = EchoFrameScores(fractions: fractions, hopSeconds: self.hopSeconds)
+ let verdict = MeetingEchoSignalScorer.verdict(scores)
+ XCTAssertEqual(verdict, .containsLocalSpeech)
+ }
+
+ func testExplainedFractionsAreClampedToUnitRange() {
+ var refLCG = LCG(seed: 50)
+ let totalCount = Int(3.0 * self.sampleRate)
+ let reference = self.bandLimitedNoise(count: totalCount, generator: &refLCG)
+ let delaySamples = 100
+ var noiseLCG = LCG(seed: 51)
+ var mic = self.delayedAndScaled(reference, bySamples: delaySamples, scale: 0.5, noiseAmplitude: 0.005, generator: &noiseLCG)
+
+ // Muting mic while the reference stays hot makes block-fit H over-predict, so the raw
+ // fraction goes negative and must clamp to 0.
+ let muteStart = totalCount / 2
+ let muteLength = 2000
+ for i in muteStart..<(muteStart + muteLength) {
+ mic[i] *= 0.01
+ }
+
+ let scores = MeetingEchoSignalScorer.explainedFractions(
+ mic: mic, reference: reference, sampleRate: self.sampleRate, delaySeconds: Double(delaySamples) / self.sampleRate
+ )
+ let scoreable = scores.fractions.filter { !$0.isNaN }
+ XCTAssertFalse(scoreable.isEmpty, "expected at least one scoreable frame")
+ XCTAssertTrue(scoreable.contains(0.0), "expected the muted window to clamp a negative raw fraction to 0")
+ for value in scoreable {
+ XCTAssertGreaterThanOrEqual(value, 0.0)
+ XCTAssertLessThanOrEqual(value, 1.0)
+ }
+ }
+
+ func testExplainedFractionsHandlesNonFiniteDelayWithoutCrashing() {
+ var refLCG = LCG(seed: 70)
+ let reference = self.bandLimitedNoise(count: Int(2.0 * self.sampleRate), generator: &refLCG)
+ var micLCG = LCG(seed: 71)
+ let mic = self.bandLimitedNoise(count: Int(2.0 * self.sampleRate), generator: &micLCG)
+ let scores = MeetingEchoSignalScorer.explainedFractions(
+ mic: mic, reference: reference, sampleRate: self.sampleRate, delaySeconds: .nan
+ )
+ XCTAssertTrue(scores.fractions.allSatisfy(\.isNaN) || scores.fractions.isEmpty)
+ }
+
+ private struct LCG {
+ private var state: UInt64
+ init(seed: UInt64) { self.state = seed &+ 0x9E3779B97F4A7C15 }
+ mutating func nextUnit() -> Float {
+ self.state = self.state &* 6364136223846793005 &+ 1442695040888963407
+ return Float(Double(self.state >> 11) / Double(1 << 53))
+ }
+ mutating func nextSigned() -> Float { self.nextUnit() * 2 - 1 }
+ }
+
+ /// Cheap 3-tap moving-average smoothing gives GCC-PHAT a less impulsive, more speech-like spectrum.
+ private func bandLimitedNoise(count: Int, generator: inout LCG) -> [Float] {
+ var white = [Float](repeating: 0, count: count)
+ for i in 0..<count { white[i] = generator.nextSigned() }
+ var smoothed = [Float](repeating: 0, count: count)
+ for i in 0..<count {
+ let a = white[i]
+ let b = i > 0 ? white[i - 1] : 0
+ let c = i > 1 ? white[i - 2] : 0
+ smoothed[i] = (a + b + c) / 3
+ }
+ return smoothed
+ }
+
+ private func delayedAndScaled(
+ _ reference: [Float], bySamples delay: Int, scale: Float, noiseAmplitude: Float, generator: inout LCG
+ ) -> [Float] {
+ var result = [Float](repeating: 0, count: reference.count)
+ for i in 0..<reference.count {
+ let sourceIndex = i - delay
+ let echoValue = (sourceIndex >= 0 && sourceIndex < reference.count) ? reference[sourceIndex] * scale : 0
+ result[i] = echoValue + generator.nextSigned() * noiseAmplitude
+ }
+ return result
+ }
+
+ /// A short decaying multi-tap "room impulse response" echo, rather than one scaled delta.
+ private func multiTapEcho(
+ _ reference: [Float], taps: [(delay: Int, gain: Float)], noiseAmplitude: Float, generator: inout LCG
+ ) -> [Float] {
+ var result = [Float](repeating: 0, count: reference.count)
+ for i in 0..<reference.count {
+ var value: Float = 0
+ for tap in taps {
+ let sourceIndex = i - tap.delay
+ if sourceIndex >= 0, sourceIndex < reference.count {
+ value += reference[sourceIndex] * tap.gain
+ }
+ }
+ result[i] = value + generator.nextSigned() * noiseAmplitude
+ }
+ return result
+ }
+}
diff --git a/Tests/FluidDictationIntegrationTests/MeetingEchoVetoTests.swift b/Tests/FluidDictationIntegrationTests/MeetingEchoVetoTests.swift
new file mode 100644
index 00000000..84a20d98
--- /dev/null
+++ b/Tests/FluidDictationIntegrationTests/MeetingEchoVetoTests.swift
@@ -0,0 +1,355 @@
+@testable import FluidVoice_Debug
+import AVFoundation
+import Foundation
+import XCTest
+
+final class MeetingEchoVetoTests: XCTestCase {
+ private let sampleRate = 16_000.0
+
+ // MARK: - Fixtures
+
+ private func makeTempDirectory() -> URL {
+ let dir = FileManager.default.temporaryDirectory
+ .appendingPathComponent("MeetingEchoVetoTests-\(UUID().uuidString)", isDirectory: true)
+ try? FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+ return dir
+ }
+
+ /// Writes 32-bit float PCM so it round-trips exactly through `readSamples`.
+ private func writeAudioFile(samples: [Float], sampleRate: Double, to url: URL) throws {
+ guard let format = AVAudioFormat(
+ commonFormat: .pcmFormatFloat32, sampleRate: sampleRate, channels: 1, interleaved: false
+ ) else {
+ throw NSError(domain: "MeetingEchoVetoTests", code: 1)
+ }
+ let file = try AVAudioFile(forWriting: url, settings: format.settings)
+ guard let buffer = AVAudioPCMBuffer(pcmFormat: format, frameCapacity: AVAudioFrameCount(samples.count)) else {
+ throw NSError(domain: "MeetingEchoVetoTests", code: 2)
+ }
+ buffer.frameLength = buffer.frameCapacity
+ samples.withUnsafeBufferPointer { ptr in
+ buffer.floatChannelData![0].update(from: ptr.baseAddress!, count: samples.count)
+ }
+ try file.write(from: buffer)
+ }
+
+ private func makeChunk(
+ sequence: Int,
+ relativeFilePath: String,
+ presentationStart: TimeInterval,
+ presentationEnd: TimeInterval,
+ discontinuities: [MeetingAudioDiscontinuity] = []
+ ) -> MeetingAudioChunk {
+ MeetingAudioChunk(
+ id: UUID(),
+ sequence: sequence,
+ relativeFilePath: relativeFilePath,
+ presentationStart: MeetingMediaTime(value: Int64((presentationStart * 1000).rounded()), timescale: 1000),
+ presentationEnd: MeetingMediaTime(value: Int64((presentationEnd * 1000).rounded()), timescale: 1000),
+ discontinuities: discontinuities,
+ sha256: "test",
+ byteCount: 1,
+ finalizationState: .finalized
+ )
+ }
+
+ private func makeTrack(kind: MeetingAudioTrackKind, chunks: [MeetingAudioChunk]) -> MeetingAudioTrack {
+ MeetingAudioTrack(
+ id: UUID(),
+ kind: kind,
+ sourceIdentifier: "src",
+ sourceDisplayName: "Source",
+ format: nil,
+ timebase: MeetingTimebaseMetadata(
+ startedHostTime: 0, machTimebaseNumerator: 1, machTimebaseDenominator: 1, firstPresentationTime: nil
+ ),
+ health: .waiting,
+ chunks: chunks
+ )
+ }
+
+ private struct LCG {
+ private var state: UInt64
+ init(seed: UInt64) { self.state = seed &+ 0x9E3779B97F4A7C15 }
+ mutating func nextUnit() -> Float {
+ self.state = self.state &* 6364136223846793005 &+ 1442695040888963407
+ return Float(Double(self.state >> 11) / Double(1 << 53))
+ }
+ mutating func nextSigned() -> Float { self.nextUnit() * 2 - 1 }
+ }
+
+ private func bandLimitedNoise(count: Int, seed: UInt64) -> [Float] {
+ var generator = LCG(seed: seed)
+ var white = [Float](repeating: 0, count: count)
+ for i in 0..<count { white[i] = generator.nextSigned() }
+ var smoothed = [Float](repeating: 0, count: count)
+ for i in 0..<count {
+ let a = white[i]
+ let b = i > 0 ? white[i - 1] : 0
+ let c = i > 1 ? white[i - 2] : 0
+ smoothed[i] = (a + b + c) / 3
+ }
+ return smoothed
+ }
+
+ // MARK: - 1. Reference gathering: straddling two app chunks
+
+ func testReferenceSpansStraddlingTwoAppChunksReturnsBothWithOffsets() {
+ let appChunkA = self.makeChunk(sequence: 0, relativeFilePath: "a.caf", presentationStart: 0, presentationEnd: 10)
+ let appChunkB = self.makeChunk(sequence: 1, relativeFilePath: "b.caf", presentationStart: 10, presentationEnd: 20)
+ // Mic chunk [8, 14) straddles the app boundary at 10.
+ let spans = MeetingProcessingPipeline.referenceSpans(
+ micSessionRange: (start: 8, end: 14),
+ appChunks: [appChunkA, appChunkB],
+ origin: 0
+ )
+ XCTAssertEqual(spans.count, 2)
+ let first = try! XCTUnwrap(spans.first { $0.chunk.id == appChunkA.id })
+ XCTAssertEqual(first.localRange, 8.0..<10.0, "local coordinates are relative to appChunkA's own start")
+ XCTAssertEqual(first.outputOffset, 0, accuracy: 1e-9)
+
+ let second = try! XCTUnwrap(spans.first { $0.chunk.id == appChunkB.id })
+ XCTAssertEqual(second.localRange, 0.0..<4.0, "local coordinates are relative to appChunkB's own start")
+ XCTAssertEqual(second.outputOffset, 2, accuracy: 1e-9)
+ }
+
+ // MARK: - 2. Reference gathering: missing/failed app chunk yields zero-fill
+
+ func testGatherReferenceAudioZeroFillsMissingChunk() throws {
+ let dir = self.makeTempDirectory()
+ defer { try? FileManager.default.removeItem(at: dir) }
+
+ let goodSamples = self.bandLimitedNoise(count: 16_000, seed: 1)
+ let goodURL = dir.appendingPathComponent("good.caf")
+ try self.writeAudioFile(samples: goodSamples, sampleRate: self.sampleRate, to: goodURL)
+
+ let goodChunk = self.makeChunk(sequence: 0, relativeFilePath: "good.caf", presentationStart: 0, presentationEnd: 1)
+ let missingChunk = self.makeChunk(sequence: 1, relativeFilePath: "missing.caf", presentationStart: 1, presentationEnd: 2)
+
+ let output = MeetingProcessingPipeline.gatherReferenceAudio(
+ micSessionRange: (start: 0, end: 2),
+ appChunks: [goodChunk, missingChunk],
+ origin: 0,
+ sessionDirectory: dir,
+ sampleRate: self.sampleRate
+ )
+
+ XCTAssertEqual(output.count, 32_000)
+ // AVAudioFile reads may legitimately short-read (fewer frames than requested); a short
+ // read only ever drops the tail, so the head is a reliable, non-flaky probe of "was this
+ // chunk actually read". The missing chunk's region must be all zero regardless.
+ for (actual, expected) in zip(output.prefix(1_000), goodSamples.prefix(1_000)) {
+ XCTAssertEqual(actual, expected, accuracy: 1e-4)
+ }
+ XCTAssertTrue(output.suffix(1_000).allSatisfy { $0 == 0 }, "a missing chunk's file must zero-fill, not throw")
+ }
+
+ // MARK: - 3. Reference gathering: independently rotated chunk boundaries
+
+ func testReferenceSpansMapIndependentlyRotatedBoundariesCorrectly() {
+ // Mic rotates every 7s, app rotates every 5s: chunk indices never line up.
+ let micChunkSessionRange = (start: 14.0, end: 21.0)
+ let appChunks = [
+ self.makeChunk(sequence: 0, relativeFilePath: "app0.caf", presentationStart: 0, presentationEnd: 5),
+ self.makeChunk(sequence: 1, relativeFilePath: "app1.caf", presentationStart: 5, presentationEnd: 10),
+ self.makeChunk(sequence: 2, relativeFilePath: "app2.caf", presentationStart: 10, presentationEnd: 15),
+ self.makeChunk(sequence: 3, relativeFilePath: "app3.caf", presentationStart: 15, presentationEnd: 20),
+ self.makeChunk(sequence: 4, relativeFilePath: "app4.caf", presentationStart: 20, presentationEnd: 25),
+ ]
+ let spans = MeetingProcessingPipeline.referenceSpans(
+ micSessionRange: micChunkSessionRange, appChunks: appChunks, origin: 0
+ )
+ // [14,21) intersects app2 [10,15), app3 [15,20), app4 [20,25).
+ XCTAssertEqual(Set(spans.map(\.chunk.sequence)), [2, 3, 4])
+
+ let fromApp2 = try! XCTUnwrap(spans.first { $0.chunk.sequence == 2 })
+ XCTAssertEqual(fromApp2.localRange, 4.0..<5.0)
+ XCTAssertEqual(fromApp2.outputOffset, 0, accuracy: 1e-9)
+
+ let fromApp3 = try! XCTUnwrap(spans.first { $0.chunk.sequence == 3 })
+ XCTAssertEqual(fromApp3.localRange, 0.0..<5.0)
+ XCTAssertEqual(fromApp3.outputOffset, 1, accuracy: 1e-9)
+
+ let fromApp4 = try! XCTUnwrap(spans.first { $0.chunk.sequence == 4 })
+ XCTAssertEqual(fromApp4.localRange, 0.0..<1.0)
+ XCTAssertEqual(fromApp4.outputOffset, 6, accuracy: 1e-9)
+ }
+
+ // MARK: - 4. Reference read failure produces .unknown and does not throw
+
+ func testComputeEchoVerdictsDegradesToUnknownWhenReferenceIsUnreadable() throws {
+ let dir = self.makeTempDirectory()
+ defer { try? FileManager.default.removeItem(at: dir) }
+
+ let micSamples = self.bandLimitedNoise(count: Int(3.0 * self.sampleRate), seed: 5)
+ let micURL = dir.appendingPathComponent("mic.caf")
+ try self.writeAudioFile(samples: micSamples, sampleRate: self.sampleRate, to: micURL)
+ let micChunk = self.makeChunk(sequence: 0, relativeFilePath: "mic.caf", presentationStart: 0, presentationEnd: 3)
+
+ // The application track's only chunk points at a file that was never written.
+ let unreadableAppChunk = self.makeChunk(sequence: 0, relativeFilePath: "does-not-exist.caf", presentationStart: 0, presentationEnd: 3)
+ let appTrack = self.makeTrack(kind: .applicationAudio, chunks: [unreadableAppChunk])
+
+ // Must not throw: a sick application-audio track can never take down a healthy mic chunk.
+ let outcome = try MeetingProcessingPipeline.computeEchoVerdicts(
+ micChunk: micChunk,
+ micChunkURL: micURL,
+ chunkOffset: 0,
+ chunkDuration: 3,
+ turns: [(index: 0, start: 0.5, end: 2.5)],
+ applicationTrack: appTrack,
+ origin: 0,
+ sessionDirectory: dir,
+ acceptedDelaysInEpoch: []
+ )
+ // Zero-filled reference has no energy; the scorer can never form a confident delay
+ // estimate against silence, so every turn degrades to `.unknown`, never mis-vetoed.
+ XCTAssertTrue(outcome.verdicts.values.allSatisfy { $0 == .unknown })
+ XCTAssertNil(outcome.acceptedDelaySeconds)
+ }
+
+ // MARK: - 5. effectiveEcho matrix
+
+ func testEffectiveEchoMatrix() {
+ func turn(isLikelyEcho: Bool, signalVerdict: TurnEchoVerdict) -> MeetingProcessingPipeline.StagedMicrophoneTurn {
+ MeetingProcessingPipeline.StagedMicrophoneTurn(
+ chunkID: UUID(), index: 0, clusterID: UUID(), clusterLabel: "0",
+ start: 0, end: 1, text: "hi", overlapsRemote: true,
+ isLikelyEcho: isLikelyEcho, echoScored: true, signalVerdict: signalVerdict
+ )
+ }
+ XCTAssertFalse(turn(isLikelyEcho: true, signalVerdict: .containsLocalSpeech).effectiveEcho)
+ XCTAssertTrue(turn(isLikelyEcho: true, signalVerdict: .echo).effectiveEcho)
+ XCTAssertTrue(turn(isLikelyEcho: true, signalVerdict: .unknown).effectiveEcho)
+ XCTAssertFalse(turn(isLikelyEcho: false, signalVerdict: .containsLocalSpeech).effectiveEcho)
+ // Signal-only echo: ASR garbles bleed differently from the far end's own transcript, so
+ // text matching misses it while the signal reads it plainly (measured median 0.91).
+ XCTAssertTrue(turn(isLikelyEcho: false, signalVerdict: .echo).effectiveEcho)
+ XCTAssertFalse(turn(isLikelyEcho: false, signalVerdict: .unknown).effectiveEcho)
+ }
+
+ // MARK: - 6. Local-speaker election is unchanged by signal verdicts
+
+ func testLocalSpeakerElectionIsUnchangedBySignalVerdict() {
+ let localCluster = UUID()
+ let remoteCluster = UUID()
+ func turns(signalVerdict: TurnEchoVerdict) -> [MeetingProcessingPipeline.StagedMicrophoneTurn] {
+ [
+ MeetingProcessingPipeline.StagedMicrophoneTurn(
+ chunkID: UUID(), index: 0, clusterID: localCluster, clusterLabel: "local",
+ start: 0, end: 5, text: "clean local speech", overlapsRemote: false,
+ isLikelyEcho: false, echoScored: false, signalVerdict: signalVerdict
+ ),
+ MeetingProcessingPipeline.StagedMicrophoneTurn(
+ chunkID: UUID(), index: 1, clusterID: remoteCluster, clusterLabel: "remote",
+ start: 5, end: 6, text: "echoed", overlapsRemote: true,
+ isLikelyEcho: true, echoScored: true, signalVerdict: signalVerdict
+ ),
+ ]
+ }
+ let prototypeSpeakerIDs: Set<SessionSpeakerID> = [localCluster, remoteCluster]
+
+ let unknownResult = MeetingProcessingPipeline.selectLocalCluster(
+ from: turns(signalVerdict: .unknown), prototypeSpeakerIDs: prototypeSpeakerIDs
+ )
+ let localSpeechResult = MeetingProcessingPipeline.selectLocalCluster(
+ from: turns(signalVerdict: .containsLocalSpeech), prototypeSpeakerIDs: prototypeSpeakerIDs
+ )
+ let echoResult = MeetingProcessingPipeline.selectLocalCluster(
+ from: turns(signalVerdict: .echo), prototypeSpeakerIDs: prototypeSpeakerIDs
+ )
+
+ XCTAssertEqual(unknownResult, localCluster)
+ XCTAssertEqual(unknownResult, localSpeechResult)
+ XCTAssertEqual(unknownResult, echoResult)
+ }
+
+ // MARK: - 7. Opposite-sign delays both handled
+
+ func testResolvedDelayHandlesOppositeSignEstimates() {
+ let positive = DelayEstimate(seconds: 0.05, confidence: MeetingEchoSignalScorer.minimumDelayConfidence + 1)
+ let negative = DelayEstimate(seconds: -0.05, confidence: MeetingEchoSignalScorer.minimumDelayConfidence + 1)
+ XCTAssertEqual(MeetingProcessingPipeline.resolvedDelay(estimate: positive, acceptedDelaysInEpoch: []), 0.05)
+ XCTAssertEqual(MeetingProcessingPipeline.resolvedDelay(estimate: negative, acceptedDelaysInEpoch: []), -0.05)
+ }
+
+ func testComputeEchoVerdictsRecoversNegativeDelayEndToEnd() throws {
+ let dir = self.makeTempDirectory()
+ defer { try? FileManager.default.removeItem(at: dir) }
+
+ let reference = self.bandLimitedNoise(count: Int(3.0 * self.sampleRate), seed: 20)
+ // Mic *leads* the reference by 150 samples: a negative delay in `mic - reference` terms.
+ let delaySamples = 150
+ var mic = [Float](repeating: 0, count: reference.count)
+ for i in 0..<reference.count {
+ let sourceIndex = i + delaySamples
+ mic[i] = sourceIndex < reference.count ? reference[sourceIndex] * 0.5 : 0
+ }
+
+ let micURL = dir.appendingPathComponent("mic.caf")
+ let refURL = dir.appendingPathComponent("ref.caf")
+ try self.writeAudioFile(samples: mic, sampleRate: self.sampleRate, to: micURL)
+ try self.writeAudioFile(samples: reference, sampleRate: self.sampleRate, to: refURL)
+
+ let micChunk = self.makeChunk(sequence: 0, relativeFilePath: "mic.caf", presentationStart: 0, presentationEnd: 3)
+ let appChunk = self.makeChunk(sequence: 0, relativeFilePath: "ref.caf", presentationStart: 0, presentationEnd: 3)
+ let appTrack = self.makeTrack(kind: .applicationAudio, chunks: [appChunk])
+
+ let outcome = try MeetingProcessingPipeline.computeEchoVerdicts(
+ micChunk: micChunk,
+ micChunkURL: micURL,
+ chunkOffset: 0,
+ chunkDuration: 3,
+ turns: [(index: 0, start: 0.2, end: 2.5)],
+ applicationTrack: appTrack,
+ origin: 0,
+ sessionDirectory: dir,
+ acceptedDelaysInEpoch: []
+ )
+ XCTAssertEqual(outcome.acceptedDelaySeconds ?? .nan, -Double(delaySamples) / self.sampleRate, accuracy: 2.0 / self.sampleRate)
+ XCTAssertEqual(outcome.verdicts[0], .echo)
+ }
+
+ // MARK: - 8. Checkpoint from any prior pipelineVersion is invalidated
+
+ func testCheckpointWithPriorPipelineVersionIsInvalidated() {
+ let sessionID = UUID()
+ let trackID = UUID()
+ let fingerprint = MeetingProcessingCheckpoint.ChunkFingerprint(id: UUID(), byteCount: 1, sha256: "x")
+ let fingerprints: [MeetingAudioTrackID: [MeetingProcessingCheckpoint.ChunkFingerprint]] = [trackID: [fingerprint]]
+ let checkpoint = MeetingProcessingCheckpoint(
+ version: MeetingProcessingCheckpoint.currentVersion,
+ sessionID: sessionID,
+ pipelineVersion: MeetingProcessingPipeline.pipelineVersion - 1,
+ asrProvider: "apple",
+ asrModel: "base",
+ languageCode: "en",
+ completedTrackID: trackID,
+ trackFingerprints: fingerprints,
+ speakers: [],
+ segments: [],
+ remoteSpeech: [],
+ speakerIDByKey: [:],
+ nextRemoteSpeaker: 1,
+ nextMicrophoneSpeaker: 1
+ )
+ var session = MeetingSession(
+ configuration: MeetingCaptureConfiguration(
+ mode: .inRoom, title: "t", microphone: MeetingMicrophoneIdentity(captureDeviceID: "d", displayName: "Mic")
+ ),
+ timebase: MeetingTimebaseMetadata(startedHostTime: 0, machTimebaseNumerator: 1, machTimebaseDenominator: 1, firstPresentationTime: nil)
+ )
+ session.id = sessionID
+
+ XCTAssertGreaterThan(MeetingProcessingPipeline.pipelineVersion, 1)
+ XCTAssertFalse(checkpoint.isValid(
+ session: session,
+ pipelineVersion: MeetingProcessingPipeline.pipelineVersion,
+ provider: "apple",
+ model: "base",
+ language: "en",
+ completedTrackID: trackID,
+ expectedFingerprints: fingerprints
+ ), "a checkpoint written under pipelineVersion 3 must not resume under pipelineVersion 4's classification rules")
+ }
+}
diff --git a/Tests/FluidDictationIntegrationTests/MeetingNearFieldGateTests.swift b/Tests/FluidDictationIntegrationTests/MeetingNearFieldGateTests.swift
new file mode 100644
index 00000000..7f4d485e
--- /dev/null
+++ b/Tests/FluidDictationIntegrationTests/MeetingNearFieldGateTests.swift
@@ -0,0 +1,71 @@
+@testable import FluidVoice_Debug
+import Foundation
+import XCTest
+
+/// Levels are the ones measured on a real speakerphone session: the user at 0.0287 RMS
+/// (-30.8 dBFS) against room audio — a TV — at 0.0023 (-52.4 dBFS).
+final class MeetingNearFieldGateTests: XCTestCase {
+ private let userRMS = 0.0287
+ private let roomRMS = 0.0023
+
+ func testRoomAudioIsRejectedAgainstMeasuredUserLevel() {
+ let turns = [(rms: self.userRMS, duration: 43.0), (rms: self.roomRMS, duration: 66.9)]
+ let reference = MeetingNearFieldGate.referenceRMS(turns: turns)
+ XCTAssertNotNil(reference)
+ XCTAssertTrue(MeetingNearFieldGate.isNearField(rms: self.userRMS, reference: reference))
+ XCTAssertFalse(MeetingNearFieldGate.isNearField(rms: self.roomRMS, reference: reference))
+ }
+
+ /// The user's quieter moments must survive; only the 22 dB gap is being cut.
+ func testQuieterUserSpeechIsKept() {
+ let reference = MeetingNearFieldGate.referenceRMS(
+ turns: [(rms: self.userRMS, duration: 30.0), (rms: self.userRMS / 2, duration: 10.0)]
+ )
+ XCTAssertTrue(MeetingNearFieldGate.isNearField(rms: self.userRMS / 4, reference: reference))
+ }
+
+ func testAbsoluteFloorRejectsSilenceEvenWithoutAReference() {
+ XCTAssertFalse(MeetingNearFieldGate.isNearField(rms: 0.0001, reference: nil))
+ XCTAssertTrue(MeetingNearFieldGate.isNearField(rms: self.userRMS, reference: nil))
+ }
+
+ /// A track holding nothing but distant audio anchors on that audio, so nothing is gated —
+ /// the same transcript as before the gate existed, rather than an empty one.
+ func testTrackOfOnlyRoomAudioGatesNothing() {
+ let turns = Array(repeating: (rms: self.roomRMS, duration: 20.0), count: 4)
+ let reference = MeetingNearFieldGate.referenceRMS(turns: turns)
+ for turn in turns {
+ XCTAssertTrue(MeetingNearFieldGate.isNearField(rms: turn.rms, reference: reference))
+ }
+ }
+
+ func testTooLittleAudioYieldsNoReference() {
+ XCTAssertNil(MeetingNearFieldGate.referenceRMS(turns: [(rms: self.userRMS, duration: 1.0)]))
+ XCTAssertNil(MeetingNearFieldGate.referenceRMS(turns: []))
+ }
+
+ func testReferenceIgnoresNonPositiveEntries() {
+ let reference = MeetingNearFieldGate.referenceRMS(
+ turns: [(rms: 0, duration: 100.0), (rms: self.userRMS, duration: 5.0)]
+ )
+ XCTAssertEqual(reference ?? 0, self.userRMS, accuracy: 1e-9)
+ }
+
+ /// The whole point of the gate: with the far-field turns removed, the user's cluster is the
+ /// only surviving evidence and the winner-margin rule can elect it.
+ func testElectionSucceedsOnceFarFieldTurnsAreRemoved() {
+ let user = UUID()
+ let room = UUID()
+ let evidence = MeetingLocalSpeakerEvidenceSelector.candidate(
+ evidenceDurationByCluster: [user: 43.0],
+ prototypeSpeakerIDs: [user, room]
+ )
+ XCTAssertEqual(evidence, user)
+
+ let blocked = MeetingLocalSpeakerEvidenceSelector.candidate(
+ evidenceDurationByCluster: [user: 43.0, room: 66.9],
+ prototypeSpeakerIDs: [user, room]
+ )
+ XCTAssertNil(blocked, "66.9/43.0 is below the 1.75x margin, so nothing may be elected")
+ }
+}
diff --git a/Tests/FluidDictationIntegrationTests/SpeakerTurnMergingTests.swift b/Tests/FluidDictationIntegrationTests/SpeakerTurnMergingTests.swift
index 443cc446..d7030422 100644
--- a/Tests/FluidDictationIntegrationTests/SpeakerTurnMergingTests.swift
+++ b/Tests/FluidDictationIntegrationTests/SpeakerTurnMergingTests.swift
@@ -1,4 +1,5 @@
@testable import FluidVoice_Debug
+import CoreMedia
import Foundation
import XCTest
@@ -1467,6 +1468,30 @@ final class MeetingSessionModelTests: XCTestCase {
XCTAssertEqual(evidence[you], 9, "the original physical signal still counts")
}
+ // MARK: - Speaker tints
+
+ func testSpeakerTintsAreStableAndWrapWithoutCrashing() {
+ func rgb(_ index: Int) -> [Int] {
+ let value = MeetingSpeakerPalette.rgb(forSpeakerIndex: index, isDark: false)
+ return [value.red, value.green, value.blue]
+ }
+ XCTAssertEqual(rgb(0), rgb(0))
+ XCTAssertNotEqual(rgb(0), rgb(1))
+ // A long meeting out-runs the palette, and a negative index must wrap rather than trap.
+ XCTAssertEqual(rgb(6), rgb(0))
+ XCTAssertEqual(rgb(-1), rgb(5))
+ }
+
+ func testSpeakerTintsLiftInDarkMode() {
+ for index in 0..<6 {
+ let light = MeetingSpeakerPalette.rgb(forSpeakerIndex: index, isDark: false)
+ let dark = MeetingSpeakerPalette.rgb(forSpeakerIndex: index, isDark: true)
+ let lightSum = light.red + light.green + light.blue
+ let darkSum = dark.red + dark.green + dark.blue
+ XCTAssertGreaterThan(darkSum, lightSum, "tint \(index) must lift for a dark ground")
+ }
+ }
+
// MARK: - Per-turn engines: merge gap, and fallbacks that must not erase "You"
// Real pairs from one Zoom recording. A user talking alone scores 0 at any length.
@@ -2283,7 +2308,8 @@ private actor FakeMeetingCaptureController: MeetingCaptureControlling {
session _: MeetingSession,
configuration _: MeetingCaptureConfiguration,
sessionDirectory _: URL,
- eventHandler: @escaping @Sendable (MeetingCaptureEvent) -> Void
+ eventHandler: @escaping @Sendable (MeetingCaptureEvent) -> Void,
+ liveAudioHandler _: (@Sendable (MeetingAudioTrackKind, CMSampleBuffer) -> Void)?
) async -> MeetingCaptureStartResult {
self.startCallCount += 1
self.eventHandlers.append(eventHandler)