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

Queue AV audio engine draining

grohith3271597c7f6155a
diff --git a/Fluid.xcodeproj/project.pbxproj b/Fluid.xcodeproj/project.pbxproj
index 673a31ed..2b135c8c 100644
--- a/Fluid.xcodeproj/project.pbxproj
+++ b/Fluid.xcodeproj/project.pbxproj
@@ -18,6 +18,7 @@
86CAA2D4EF18433096185602 /* LLMClientRequestBodyTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 343B29013F4441D6A797D12D /* LLMClientRequestBodyTests.swift */; };
272BFB5CB271489892CAE50C /* TemperatureSupportTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 980330F3CE464336ADCE3E23 /* TemperatureSupportTests.swift */; };
A62300000000000000000002 /* AudioBufferConverterTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = A62300000000000000000001 /* AudioBufferConverterTests.swift */; };
+ C0DE63600000000000000002 /* AudioEngineRetirementDrainTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = C0DE63600000000000000001 /* AudioEngineRetirementDrainTests.swift */; };
7CDB0A2F2F3C4D5600FB7CAD /* dictation_fixture.wav in Resources */ = {isa = PBXBuildFile; fileRef = 7CDB0A2B2F3C4D5600FB7CAD /* dictation_fixture.wav */; };
7CDB0A302F3C4D5600FB7CAD /* XCTest.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 7CDB0A2C2F3C4D5600FB7CAD /* XCTest.framework */; };
7CE006BD2E80EBE600DDCCD6 /* AppUpdater in Frameworks */ = {isa = PBXBuildFile; productRef = 7CE006BC2E80EBE600DDCCD6 /* AppUpdater */; };
@@ -52,6 +53,7 @@
343B29013F4441D6A797D12D /* LLMClientRequestBodyTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = LLMClientRequestBodyTests.swift; sourceTree = "<group>"; };
980330F3CE464336ADCE3E23 /* TemperatureSupportTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = TemperatureSupportTests.swift; sourceTree = "<group>"; };
A62300000000000000000001 /* AudioBufferConverterTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = AudioBufferConverterTests.swift; sourceTree = "<group>"; };
+ C0DE63600000000000000001 /* AudioEngineRetirementDrainTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = AudioEngineRetirementDrainTests.swift; sourceTree = "<group>"; };
7C078D8F2E3B339200FB7CAC /* FluidVoice Debug.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = "FluidVoice Debug.app"; sourceTree = BUILT_PRODUCTS_DIR; };
7C91B0022F42AA0100C0DEF0 /* HotkeyShortcutTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = HotkeyShortcutTests.swift; sourceTree = "<group>"; };
7CDB0A202F3C4D5600FB7CAD /* FluidDictationIntegrationTests.xctest */ = {isa = PBXFileReference; explicitFileType = wrapper.cfbundle; includeInIndex = 0; path = FluidDictationIntegrationTests.xctest; sourceTree = BUILT_PRODUCTS_DIR; };
@@ -129,6 +131,7 @@
343B29013F4441D6A797D12D /* LLMClientRequestBodyTests.swift */,
980330F3CE464336ADCE3E23 /* TemperatureSupportTests.swift */,
A62300000000000000000001 /* AudioBufferConverterTests.swift */,
+ C0DE63600000000000000001 /* AudioEngineRetirementDrainTests.swift */,
);
path = FluidDictationIntegrationTests;
sourceTree = "<group>";
@@ -287,6 +290,7 @@
86CAA2D4EF18433096185602 /* LLMClientRequestBodyTests.swift in Sources */,
272BFB5CB271489892CAE50C /* TemperatureSupportTests.swift in Sources */,
A62300000000000000000002 /* AudioBufferConverterTests.swift in Sources */,
+ C0DE63600000000000000002 /* AudioEngineRetirementDrainTests.swift in Sources */,
);
runOnlyForDeploymentPostprocessing = 0;
};
diff --git a/Sources/Fluid/Services/ASRService.swift b/Sources/Fluid/Services/ASRService.swift
index 08e08e19..e0ece9a8 100644
--- a/Sources/Fluid/Services/ASRService.swift
+++ b/Sources/Fluid/Services/ASRService.swift
@@ -618,7 +618,11 @@ final class ASRService: ObservableObject {
self.directAudioInput != nil || self.hasWarmAudioEngine
}
- private func retireAudioEngine(reason: String) {
+ /// Detaches the current engine from main-actor state and returns a token that
+ /// owns its final strong reference. The token must be handed to
+ /// `audioEngineRetirementDrain`; dropping it directly would put deallocation
+ /// back on the caller's actor.
+ private func detachAudioEngineForRetirement(reason: String) -> AudioEngineRetirementToken? {
self.audioEngineStandbyTask?.cancel()
self.audioEngineStandbyTask = nil
@@ -639,19 +643,29 @@ final class ASRService: ObservableObject {
}
self.audioCapturePipeline.clearPreroll()
- // The final strong reference must be released off the main thread:
- // -[AVAudioEngine dealloc] waits on the engine's internal serial queue,
- // which can deadlock main against a concurrent configuration-change post
- // (#542). Capturing a local in the async block is not enough — if the
- // block finishes before this function returns, the local's release
- // becomes the final one and dealloc lands back on main. The holder keeps
- // the engine out of main-thread locals entirely.
- if self.engineStorage != nil {
- let retired = RetiredAudioEngineReference(self.engineStorage)
- self.engineStorage = nil
- retired.scheduleRelease()
- }
+ let retirementToken = self.engineStorage.map(AudioEngineRetirementToken.init)
+ self.engineStorage = nil
DebugLogger.shared.debug("Audio engine retired (\(reason))", source: "ASRService")
+ return retirementToken
+ }
+
+ /// Fire-and-forget retirement for paths that do not construct a replacement.
+ /// All releases still share the serial drain, and capture startup waits on a
+ /// drain barrier before it may create another engine.
+ private func retireAudioEngine(reason: String) {
+ guard let token = self.detachAudioEngineForRetirement(reason: reason) else { return }
+ self.audioEngineRetirementDrain.schedule(token)
+ }
+
+ /// Route recovery and engine retry paths use this completion barrier so the
+ /// old AVAudioEngine and its AVAudioIOUnit are fully deallocated before a
+ /// replacement can touch Core Audio.
+ private func retireAudioEngineAndWait(reason: String) async {
+ if let token = self.detachAudioEngineForRetirement(reason: reason) {
+ await self.audioEngineRetirementDrain.releaseAndWait(token)
+ } else {
+ await self.audioEngineRetirementDrain.waitForScheduledReleases()
+ }
}
private func scheduleAudioEngineStandbyRetirement() {
@@ -696,7 +710,10 @@ final class ASRService: ObservableObject {
DebugLogger.shared.debug("Audio engine cooled to stopped warm state (\(reason))", source: "ASRService")
}
- private func prewarmAudioEngineIfPossible(reason: String) {
+ private func prewarmAudioEngineIfPossible(
+ reason: String,
+ allowDuringRouteRecovery: Bool = false
+ ) {
guard self.micStatus == .authorized else {
DebugLogger.shared.debug("Audio engine prewarm skipped - mic not authorized", source: "ASRService")
return
@@ -705,6 +722,10 @@ final class ASRService: ObservableObject {
DebugLogger.shared.debug("Audio engine prewarm skipped - capture active", source: "ASRService")
return
}
+ guard allowDuringRouteRecovery || self.isRecoveringAudioRoute == false else {
+ DebugLogger.shared.debug("Audio engine prewarm skipped - route recovery active", source: "ASRService")
+ return
+ }
guard self.hasPreparedAudioCapture == false else {
DebugLogger.shared.debug("Audio capture prewarm skipped - backend already prepared", source: "ASRService")
return
@@ -779,7 +800,12 @@ final class ASRService: ObservableObject {
}
}
- private func startPreferredAudioCapture() throws {
+ private func startPreferredAudioCapture() async throws {
+ // A non-route path may have scheduled a fire-and-forget retirement. Do
+ // not let capture startup overlap any final AVAudioEngine release that is
+ // already queued.
+ await self.audioEngineRetirementDrain.waitForScheduledReleases()
+
let directCaptureEnabled = SettingsStore.shared.experimentalDirectAudioCaptureEnabled
if directCaptureEnabled,
self.prepareDirectAudioInputIfPossible(reason: "recording_start"),
@@ -812,15 +838,16 @@ final class ASRService: ObservableObject {
self.directAudioInput = nil
}
- try self.startCompatibilityAudioCapture(
+ try await self.startCompatibilityAudioCapture(
reason: directCaptureEnabled ? "direct_unavailable" : "experimental_disabled"
)
}
- private func startCompatibilityAudioCapture(reason: String) throws {
+ private func startCompatibilityAudioCapture(reason: String) async throws {
+ await self.audioEngineRetirementDrain.waitForScheduledReleases()
self.benchmarkLog("audio_backend kind=av_audio_engine_fallback reason=\(reason)")
try self.configureSession()
- try self.startEngine()
+ try await self.startEngine()
try self.setupEngineTap()
self.activeAudioCaptureBackend = .audioEngine
}
@@ -908,7 +935,7 @@ final class ASRService: ObservableObject {
sessionID: sessionID,
startHostTime: mach_absolute_time()
)
- try self.startCompatibilityAudioCapture(reason: "duration_mismatch")
+ try await self.startCompatibilityAudioCapture(reason: "duration_mismatch")
let model = SettingsStore.shared.selectedSpeechModel
if model.supportsStreaming, self.isDictionaryTrainingCaptureActive == false {
self.startStreamingTranscription()
@@ -945,8 +972,10 @@ final class ASRService: ObservableObject {
return
}
- self.retireAudioEngine(reason: "capture_preference_changed")
- self.prewarmAudioEngineIfPossible(reason: "capture_preference_changed")
+ self.scheduleAudioRouteRecovery(
+ reason: "capture preference changed",
+ requiresIdlePrewarm: true
+ )
}
private var inputFormat: AVAudioFormat?
@@ -987,8 +1016,12 @@ final class ASRService: ObservableObject {
private let transcriptionExecutor = TranscriptionExecutor() // Serializes all CoreML access
private var providerResetDrain: (id: UUID, task: Task<Void, Never>)?
private var engineConfigurationChangeObserver: NSObjectProtocol?
+ private let audioEngineRetirementDrain = AudioEngineRetirementDrain()
private var audioRouteRecoveryTask: Task<Void, Never>?
- private let audioRouteRecoveryDelayNanoseconds: UInt64 = 1_000_000_000
+ private let audioRouteRecoveryDelayNanoseconds: UInt64 = 300_000_000
+ private var audioRouteRecoveryGeneration: UInt64 = 0
+ private var pendingAudioRouteRecoveryReason: String?
+ private var pendingAudioRouteRecoveryRequiresIdlePrewarm = false
private var audioEngineStandbyTask: Task<Void, Never>?
private let audioEngineStandbyNanoseconds: UInt64 = 8_000_000_000
private var isEngineTapInstalled = false
@@ -1298,9 +1331,7 @@ final class ASRService: ObservableObject {
self.didPauseMediaForThisSession = false
self.audioEngineStandbyTask?.cancel()
self.audioEngineStandbyTask = nil
- self.audioRouteRecoveryTask?.cancel()
- self.audioRouteRecoveryTask = nil
- self.isRecoveringAudioRoute = false
+ await self.cancelAudioRouteRecoveryAndWait()
DebugLogger.shared.debug("🧹 Clearing buffers and state", source: "ASRService")
self.finalText.removeAll()
@@ -1338,7 +1369,7 @@ final class ASRService: ObservableObject {
AppServices.shared.microphonePreferenceCoordinator.enforcePreferredInput(reason: "recording start")
}
- try self.startPreferredAudioCapture()
+ try await self.startPreferredAudioCapture()
self.isDictionaryTrainingCaptureActive = forDictionaryTraining
self.isRunning = true
DebugLogger.shared.info("✅ Audio capture running", source: "ASRService")
@@ -1386,7 +1417,7 @@ final class ASRService: ObservableObject {
self.audioCapturePipeline.setRecordingEnabled(false)
self.isRunning = false
self.stopActiveAudioCapture()
- self.retireAudioEngine(reason: "start_failed")
+ await self.retireAudioEngineAndWait(reason: "start_failed")
DebugLogger.shared.error("Failed to start ASR session: \(error)", source: "ASRService")
// Resume media if we paused it before the failure
@@ -1477,9 +1508,7 @@ final class ASRService: ObservableObject {
self.isDictionaryTrainingCaptureActive = false
}
- self.audioRouteRecoveryTask?.cancel()
- self.audioRouteRecoveryTask = nil
- self.isRecoveringAudioRoute = false
+ await self.cancelAudioRouteRecoveryAndWait()
// Capture media pause state before we reset it, for resuming at the end
let shouldResumeMedia = SettingsStore.shared.pauseMediaDuringTranscription && self.didPauseMediaForThisSession
@@ -1816,9 +1845,7 @@ final class ASRService: ObservableObject {
self.isDictionaryTrainingCaptureActive = false
}
- self.audioRouteRecoveryTask?.cancel()
- self.audioRouteRecoveryTask = nil
- self.isRecoveringAudioRoute = false
+ await self.cancelAudioRouteRecoveryAndWait()
// Capture media pause state before we reset it, for resuming at the end
let shouldResumeMedia = SettingsStore.shared.pauseMediaDuringTranscription && self.didPauseMediaForThisSession
@@ -1837,7 +1864,7 @@ final class ASRService: ObservableObject {
DebugLogger.shared.debug("Audio capture stopped", source: "ASRService")
// Cancel/no-transcription paths stay conservative and retire the engine.
- self.retireAudioEngine(reason: "stop_without_transcription")
+ await self.retireAudioEngineAndWait(reason: "stop_without_transcription")
// CRITICAL FIX: Await completion of streaming task AND any pending transcriptions
// This prevents use-after-free crashes (EXC_BAD_ACCESS) when clearing buffer
@@ -2164,7 +2191,7 @@ final class ASRService: ObservableObject {
}
}
- private func startEngine() throws {
+ private func startEngine() async throws {
DebugLogger.shared.debug("🚀 startEngine() - ENTERED", source: "ASRService")
var attempts = 0
var lastError: Error?
@@ -2223,7 +2250,7 @@ final class ASRService: ObservableObject {
// If this isn't the last attempt, recreate engine and reconfigure
if attempts < 3 {
DebugLogger.shared.debug("⚠️ Start failed, recreating engine for retry...", source: "ASRService")
- self.retireAudioEngine(reason: "start_retry")
+ await self.retireAudioEngineAndWait(reason: "start_retry")
// Need to reconfigure the new engine
try? self.configureSession()
DebugLogger.shared.debug("✅ Engine recreated and reconfigured, will retry", source: "ASRService")
@@ -2324,25 +2351,51 @@ final class ASRService: ObservableObject {
DebugLogger.shared.debug("✅ setupEngineTap() - COMPLETED", source: "ASRService")
}
- private func scheduleAudioRouteRecovery(reason: String) {
- guard self.isRunning else {
- self.audioLevelSubject.send(0.0)
- if self.hasPreparedAudioCapture {
- self.retireAudioEngine(reason: "idle_route_change:\(reason)")
- self.prewarmAudioEngineIfPossible(reason: "idle_route_change")
- }
- return
+ private func scheduleAudioRouteRecovery(
+ reason: String,
+ requiresIdlePrewarm: Bool = false
+ ) {
+ self.audioRouteRecoveryGeneration &+= 1
+ let generation = self.audioRouteRecoveryGeneration
+ self.pendingAudioRouteRecoveryReason = reason
+ self.pendingAudioRouteRecoveryRequiresIdlePrewarm =
+ self.pendingAudioRouteRecoveryRequiresIdlePrewarm || requiresIdlePrewarm
+
+ self.audioLevelSubject.send(0.0)
+ if self.isRunning {
+ // Stop accepting samples immediately, but do not touch AVAudioEngine
+ // until Core Audio has been quiet for the debounce interval.
+ self.audioCapturePipeline.setRecordingEnabled(false)
+ DebugLogger.shared.warning(
+ "Audio route changed while recording; waiting for topology quiet (\(reason), generation=\(generation))",
+ source: "ASRService"
+ )
+ } else {
+ DebugLogger.shared.debug(
+ "Audio route changed while idle; waiting for topology quiet (\(reason), generation=\(generation))",
+ source: "ASRService"
+ )
}
+
+ self.audioRouteRecoveryTask?.cancel()
guard self.isRecoveringAudioRoute == false else {
- DebugLogger.shared.debug("Ignoring audio route recovery request during active recovery (\(reason))", source: "ASRService")
+ // The in-flight recovery observes cancellation after its awaited
+ // retirement barrier, then arms the latest generation.
return
}
- DebugLogger.shared.warning("Audio route changed while recording; scheduling recovery (\(reason))", source: "ASRService")
- self.audioCapturePipeline.setRecordingEnabled(false)
- self.audioLevelSubject.send(0.0)
+ self.armAudioRouteRecovery(
+ generation: generation,
+ reason: reason,
+ requiresIdlePrewarm: self.pendingAudioRouteRecoveryRequiresIdlePrewarm
+ )
+ }
- self.audioRouteRecoveryTask?.cancel()
+ private func armAudioRouteRecovery(
+ generation: UInt64,
+ reason: String,
+ requiresIdlePrewarm: Bool
+ ) {
let recoveryDelayNanoseconds = self.audioRouteRecoveryDelayNanoseconds
self.audioRouteRecoveryTask = Task { [weak self] in
do {
@@ -2350,27 +2403,100 @@ final class ASRService: ObservableObject {
} catch {
return
}
- await self?.recoverAudioRoute(reason: reason)
+ await self?.performAudioRouteRecovery(
+ generation: generation,
+ reason: reason,
+ requiresIdlePrewarm: requiresIdlePrewarm
+ )
}
}
- @MainActor
- private func recoverAudioRoute(reason: String) async {
- guard self.isRunning else { return }
+ /// Cancels a sleeping or active recovery and waits until any detached engine
+ /// release has drained. Start/stop paths use this to avoid racing a route
+ /// rebuild that yielded while AVAudioEngine was deallocating.
+ private func cancelAudioRouteRecoveryAndWait() async {
+ self.audioRouteRecoveryGeneration &+= 1
+ self.pendingAudioRouteRecoveryReason = nil
+ self.pendingAudioRouteRecoveryRequiresIdlePrewarm = false
+ let task = self.audioRouteRecoveryTask
+ task?.cancel()
+ _ = await task?.result
+ self.audioRouteRecoveryTask = nil
+ self.isRecoveringAudioRoute = false
+ await self.audioEngineRetirementDrain.waitForScheduledReleases()
+ }
+
+ private func performAudioRouteRecovery(
+ generation: UInt64,
+ reason: String,
+ requiresIdlePrewarm: Bool
+ ) async {
+ guard generation == self.audioRouteRecoveryGeneration, Task.isCancelled == false else { return }
guard self.isRecoveringAudioRoute == false else { return }
self.isRecoveringAudioRoute = true
defer {
self.isRecoveringAudioRoute = false
- self.audioRouteRecoveryTask = nil
+
+ if generation == self.audioRouteRecoveryGeneration {
+ self.pendingAudioRouteRecoveryReason = nil
+ self.pendingAudioRouteRecoveryRequiresIdlePrewarm = false
+ self.audioRouteRecoveryTask = nil
+ } else if let pendingReason = self.pendingAudioRouteRecoveryReason {
+ self.armAudioRouteRecovery(
+ generation: self.audioRouteRecoveryGeneration,
+ reason: pendingReason,
+ requiresIdlePrewarm: self.pendingAudioRouteRecoveryRequiresIdlePrewarm
+ )
+ } else {
+ self.audioRouteRecoveryTask = nil
+ }
}
- DebugLogger.shared.info("Recovering audio route after \(reason)", source: "ASRService")
- self.audioCapturePipeline.setRecordingEnabled(false)
+ if self.isRunning {
+ await self.recoverActiveAudioRoute(generation: generation, reason: reason)
+ } else {
+ await self.recoverIdleAudioRoute(
+ generation: generation,
+ reason: reason,
+ requiresPrewarm: requiresIdlePrewarm
+ )
+ }
+ }
+ private func recoverIdleAudioRoute(
+ generation: UInt64,
+ reason: String,
+ requiresPrewarm: Bool
+ ) async {
+ let shouldRebuild = self.hasPreparedAudioCapture || requiresPrewarm
+ guard shouldRebuild else { return }
+
+ // If another event arrives while retirement is draining, the next
+ // generation still needs to restore the prepared capture backend.
+ self.pendingAudioRouteRecoveryRequiresIdlePrewarm = true
+ await self.retireAudioEngineAndWait(reason: "idle_route_change:\(reason)")
+
+ guard generation == self.audioRouteRecoveryGeneration, Task.isCancelled == false else { return }
+ self.prewarmAudioEngineIfPossible(
+ reason: "idle_route_change",
+ allowDuringRouteRecovery: true
+ )
+ }
+
+ private func recoverActiveAudioRoute(generation: UInt64, reason: String) async {
+ guard self.isRunning else { return }
+
+ DebugLogger.shared.info(
+ "Recovering audio route after \(reason) (generation=\(generation))",
+ source: "ASRService"
+ )
+ self.audioCapturePipeline.setRecordingEnabled(false)
self.stopMonitoringDevice()
self.stopActiveAudioCapture()
- self.retireAudioEngine(reason: "audio_route_recovery")
+ await self.retireAudioEngineAndWait(reason: "audio_route_recovery")
+
+ guard generation == self.audioRouteRecoveryGeneration, Task.isCancelled == false else { return }
do {
self.audioCapturePipeline.setRecordingEnabled(
@@ -2378,17 +2504,25 @@ final class ASRService: ObservableObject {
sessionID: self.benchmarkSessionID,
startHostTime: mach_absolute_time()
)
- try self.startPreferredAudioCapture()
+ try await self.startPreferredAudioCapture()
if let currentDevice = self.getCurrentlyBoundInputDevice() {
self.startMonitoringDevice(currentDevice.id)
}
- DebugLogger.shared.info("Audio route recovery succeeded", source: "ASRService")
+ DebugLogger.shared.info(
+ "Audio route recovery succeeded (generation=\(generation))",
+ source: "ASRService"
+ )
} catch {
+ guard generation == self.audioRouteRecoveryGeneration, Task.isCancelled == false else { return }
self.audioCapturePipeline.setRecordingEnabled(false)
self.stopActiveAudioCapture()
DebugLogger.shared.error("Audio route recovery failed: \(error)", source: "ASRService")
+
+ // Avoid asking stopWithoutTranscription() to await the recovery task
+ // that is currently executing this catch block.
+ self.audioRouteRecoveryTask = nil
await self.stopWithoutTranscription()
NotificationCenter.default.post(
name: NSNotification.Name("ASRServiceDeviceDisconnected"),
@@ -3646,31 +3780,6 @@ private extension ASRService {
}
}
-// MARK: - Audio engine retirement
-
-/// Carries the final strong reference to a retired audio engine so the release —
-/// and `-[AVAudioEngine dealloc]`, which blocks on the engine's internal serial
-/// queue — always happens on the drain queue, never on the main thread (#542).
-/// `@unchecked Sendable`: created on the main thread, then handed off and touched
-/// exactly once by the draining block; the dispatch provides the ordering.
-private final nonisolated class RetiredAudioEngineReference: @unchecked Sendable {
- private var engine: AnyObject?
-
- init(_ engine: AnyObject?) {
- self.engine = engine
- }
-
- /// Schedules the retained engine's release off the main thread. Keeping the
- /// actual drain private prevents callers from bypassing this queue hop.
- func scheduleRelease() {
- DispatchQueue.global(qos: .utility).async { self.drain() }
- }
-
- private func drain() {
- self.engine = nil
- }
-}
-
// MARK: - Audio capture pipeline
//
diff --git a/Sources/Fluid/Services/AudioEngineRetirementDrain.swift b/Sources/Fluid/Services/AudioEngineRetirementDrain.swift
new file mode 100644
index 00000000..279d1158
--- /dev/null
+++ b/Sources/Fluid/Services/AudioEngineRetirementDrain.swift
@@ -0,0 +1,58 @@
+import Foundation
+
+/// Owns the last strong reference to an audio engine while it is waiting to be
+/// released on the dedicated retirement queue.
+///
+/// The token is intentionally separate from the drain. Callers may retain the
+/// token across an `await`, but draining it still releases the engine itself on
+/// the retirement queue rather than on the caller's actor.
+final nonisolated class AudioEngineRetirementToken: @unchecked Sendable {
+ private var engine: AnyObject?
+
+ init(_ engine: AnyObject) {
+ self.engine = engine
+ }
+
+ fileprivate func drain() {
+ self.engine = nil
+ }
+}
+
+/// Serializes final audio-engine releases and provides a completion barrier.
+///
+/// `-[AVAudioEngine dealloc]` may wait for AVAudioIOUnit's internal queue. The
+/// drain must therefore never run on the main actor, and replacement engine
+/// construction must be able to await its completion.
+final nonisolated class AudioEngineRetirementDrain: @unchecked Sendable {
+ private let queue: DispatchQueue
+
+ init(label: String = "app.fluidvoice.audio-engine-retirement") {
+ self.queue = DispatchQueue(label: label, qos: .utility)
+ }
+
+ func schedule(_ token: AudioEngineRetirementToken) {
+ self.queue.async {
+ token.drain()
+ }
+ }
+
+ func releaseAndWait(_ token: AudioEngineRetirementToken) async {
+ await withCheckedContinuation { (continuation: CheckedContinuation<Void, Never>) in
+ self.queue.async {
+ token.drain()
+ continuation.resume()
+ }
+ }
+ }
+
+ /// Waits for every release already submitted to this drain. This is used at
+ /// capture start so a fire-and-forget retirement from a non-route path cannot
+ /// overlap construction of the next AVAudioEngine.
+ func waitForScheduledReleases() async {
+ await withCheckedContinuation { (continuation: CheckedContinuation<Void, Never>) in
+ self.queue.async {
+ continuation.resume()
+ }
+ }
+ }
+}
diff --git a/Tests/FluidDictationIntegrationTests/AudioEngineRetirementDrainTests.swift b/Tests/FluidDictationIntegrationTests/AudioEngineRetirementDrainTests.swift
new file mode 100644
index 00000000..b97fe3b2
--- /dev/null
+++ b/Tests/FluidDictationIntegrationTests/AudioEngineRetirementDrainTests.swift
@@ -0,0 +1,70 @@
+@testable import FluidVoice_Debug
+import Foundation
+import XCTest
+
+final class AudioEngineRetirementDrainTests: XCTestCase {
+ func testReleaseAndWaitCompletesAfterOffMainDeinit() async throws {
+ let drain = AudioEngineRetirementDrain(label: "test.audio-engine-retirement.single")
+ let recorder = DeinitRecorder()
+ var probe: DeinitProbe? = DeinitProbe(id: 1, recorder: recorder)
+ let token = AudioEngineRetirementToken(try XCTUnwrap(probe))
+ probe = nil
+
+ await drain.releaseAndWait(token)
+
+ XCTAssertEqual(recorder.ids, [1])
+ XCTAssertEqual(recorder.mainThreadFlags, [false])
+ }
+
+ func testAwaitedReleaseRunsAfterPreviouslyScheduledRelease() async throws {
+ let drain = AudioEngineRetirementDrain(label: "test.audio-engine-retirement.serial")
+ let recorder = DeinitRecorder()
+ var first: DeinitProbe? = DeinitProbe(id: 1, recorder: recorder)
+ var second: DeinitProbe? = DeinitProbe(id: 2, recorder: recorder)
+ let firstToken = AudioEngineRetirementToken(try XCTUnwrap(first))
+ let secondToken = AudioEngineRetirementToken(try XCTUnwrap(second))
+ first = nil
+ second = nil
+
+ drain.schedule(firstToken)
+ await drain.releaseAndWait(secondToken)
+
+ XCTAssertEqual(recorder.ids, [1, 2])
+ XCTAssertEqual(recorder.mainThreadFlags, [false, false])
+ }
+}
+
+private final class DeinitProbe {
+ private let id: Int
+ private let recorder: DeinitRecorder
+
+ init(id: Int, recorder: DeinitRecorder) {
+ self.id = id
+ self.recorder = recorder
+ }
+
+ deinit {
+ self.recorder.record(id: self.id, wasMainThread: Thread.isMainThread)
+ }
+}
+
+private final class DeinitRecorder: @unchecked Sendable {
+ private let lock = NSLock()
+ private var recordedIDs: [Int] = []
+ private var recordedMainThreadFlags: [Bool] = []
+
+ var ids: [Int] {
+ self.lock.withLock { self.recordedIDs }
+ }
+
+ var mainThreadFlags: [Bool] {
+ self.lock.withLock { self.recordedMainThreadFlags }
+ }
+
+ func record(id: Int, wasMainThread: Bool) {
+ self.lock.withLock {
+ self.recordedIDs.append(id)
+ self.recordedMainThreadFlags.append(wasMainThread)
+ }
+ }
+}