fix: prevent sound effects from bleeding into transcription (closes #49) (#52)

Author: jatinkrmalik

Sources/VocaMac/Models/AppState.swift

@@ -311,16 +311,17 @@ final class AppState: ObservableObject {
         isRecording = true
         errorMessage = nil
 
-        // Play start sound
-        if soundEffectsEnabled {
-            soundManager.playStartSound()
-        }
-
         // Show cursor indicator
         if showCursorIndicator {
             cursorOverlay.show()
         }
 
+        // Play start sound and wait for completion before starting mic
+        // This prevents the sound from being captured into the audio buffer
+        if soundEffectsEnabled {
+            await soundManager.playStartSoundAsync()
+        }
+
         audioEngine.startRecording(
             silenceThreshold: Float(silenceThreshold),
             silenceDuration: silenceDuration,

Sources/VocaMac/Services/SoundManager.swift

@@ -7,7 +7,7 @@
 import Foundation
 import AppKit
 
-final class SoundManager {
+final class SoundManager: NSObject, NSSoundDelegate, @unchecked Sendable {
 
     // MARK: - Sound Names
 
@@ -22,21 +22,41 @@ final class SoundManager {
     /// Volume for sound effects (0.0 to 1.0)
     var volume: Float = 0.5
 
+    /// Lock for thread-safe access to continuation
+    private let continuationLock = NSLock()
+
+    /// Continuation for async sound playback completion
+    private var soundCompletionContinuation: CheckedContinuation<Void, Never>?
+
     // MARK: - Public API
 
-    /// Play the recording-started sound
+    /// Play the recording-started sound (synchronous, fire-and-forget)
     func playStartSound() {
         playSystemSound(startSoundName)
     }
 
-    /// Play the recording-stopped sound
+    /// Play the recording-started sound and wait for completion
+    /// Ensures the sound finishes before returning, preventing mic capture of the sound.
+    /// - Throws: May timeout if sound is stuck
+    func playStartSoundAsync() async {
+        await playSystemSoundAsync(startSoundName)
+    }
+
+    /// Play the recording-stopped sound (synchronous, fire-and-forget)
     func playStopSound() {
         playSystemSound(stopSoundName)
     }
 
+    /// Play the recording-stopped sound and wait for completion
+    /// Ensures the sound finishes before returning.
+    /// - Throws: May timeout if sound is stuck
+    func playStopSoundAsync() async {
+        await playSystemSoundAsync(stopSoundName)
+    }
+
     // MARK: - Private
 
-    /// Play a macOS system sound by name
+    /// Play a macOS system sound by name (fire-and-forget)
     private func playSystemSound(_ name: String) {
         let soundPath = "/System/Library/Sounds/\(name).aiff"
         guard let sound = NSSound(contentsOfFile: soundPath, byReference: true) else {
@@ -46,4 +66,55 @@ final class SoundManager {
         sound.volume = volume
         sound.play()
     }
+
+    /// Play a system sound and wait for completion using async/await
+    /// Uses NSSoundDelegate callback to detect when playback finishes.
+    /// Includes a 1-second timeout to prevent stuck sounds from blocking recording.
+    /// - Parameter name: The system sound name to play (e.g., "Pop", "Bottle")
+    private func playSystemSoundAsync(_ name: String) async {
+        let soundPath = "/System/Library/Sounds/\(name).aiff"
+        guard let sound = NSSound(contentsOfFile: soundPath, byReference: true) else {
+            NSLog("[SoundManager] Could not load system sound: %@", name)
+            return
+        }
+
+        sound.volume = volume
+        sound.delegate = self
+
+        return await withCheckedContinuation { continuation in
+            continuationLock.lock()
+            soundCompletionContinuation = continuation
+            continuationLock.unlock()
+
+            sound.play()
+
+            // Timeout after 1 second to prevent stuck sounds from blocking
+            DispatchQueue.main.asyncAfter(deadline: .now() + 1.0) { [weak self] in
+                guard let self = self else { return }
+                self.continuationLock.lock()
+                if self.soundCompletionContinuation != nil {
+                    NSLog("[SoundManager] Sound playback timeout for: %@", name)
+                    self.soundCompletionContinuation?.resume()
+                    self.soundCompletionContinuation = nil
+                }
+                self.continuationLock.unlock()
+            }
+        }
+    }
+
+    // MARK: - NSSoundDelegate
+
+    /// Called when sound finishes playing
+    nonisolated func sound(_ sound: NSSound, didFinishPlaying FinishedPlaying: Bool) {
+        // Dispatch back to main thread to safely access and resume continuation
+        DispatchQueue.main.async { [weak self] in
+            guard let self = self else { return }
+            self.continuationLock.lock()
+            if let continuation = self.soundCompletionContinuation {
+                continuation.resume()
+                self.soundCompletionContinuation = nil
+            }
+            self.continuationLock.unlock()
+        }
+    }
 }

Tests/VocaMacTests/VocaMacTests.swift

@@ -314,3 +314,61 @@ final class TextInjectorTests: XCTestCase {
         injector.inject(text: "", preserveClipboard: false)
     }
 }
+
+// MARK: - SoundManager Tests
+
+final class SoundManagerTests: XCTestCase {
+
+    var soundManager: SoundManager!
+
+    override func setUp() {
+        super.setUp()
+        soundManager = SoundManager()
+    }
+
+    func testPlayStartSoundSync() {
+        // Test that synchronous play doesn't crash
+        soundManager.playStartSound()
+        // If we get here without crashing, the test passes
+        XCTAssertTrue(true)
+    }
+
+    func testPlayStopSoundSync() {
+        // Test that synchronous play doesn't crash
+        soundManager.playStopSound()
+        // If we get here without crashing, the test passes
+        XCTAssertTrue(true)
+    }
+
+    func testPlayStartSoundAsync() async {
+        // Test that async play completes without hanging
+        let startTime = Date()
+        await soundManager.playStartSoundAsync()
+        let elapsed = Date().timeIntervalSince(startTime)
+
+        // Should complete in reasonable time (under 2 seconds even with timeout)
+        XCTAssertLessThan(elapsed, 2.0)
+    }
+
+    func testPlayStopSoundAsync() async {
+        // Test that async play completes without hanging
+        let startTime = Date()
+        await soundManager.playStopSoundAsync()
+        let elapsed = Date().timeIntervalSince(startTime)
+
+        // Should complete in reasonable time (under 2 seconds even with timeout)
+        XCTAssertLessThan(elapsed, 2.0)
+    }
+
+    func testVolumeControl() {
+        soundManager.volume = 0.0
+        XCTAssertEqual(soundManager.volume, 0.0)
+
+        soundManager.volume = 0.5
+        XCTAssertEqual(soundManager.volume, 0.5)
+
+        soundManager.volume = 1.0
+        XCTAssertEqual(soundManager.volume, 1.0)
+    }
+}
+