feat: save the audio behind an ONNX decode that returns nothing

An empty decode is the one failure with nothing to debug: no error, no
text, and the audio is gone the moment the buffer is released. The bug in
#256 took two wrong fixes before a dumped recording showed what was
actually happening — the decode turned out to be so sensitive to its input
that scaling the same samples by 1.001 changed the result, which no
synthetic clip reproduced and no log line could have revealed.

Write the samples to a WAV next to the logs so the failure can be replayed
through --transcribe-file. Off unless asked for, since it puts recorded
speech on disk:

    defaults write com.vocamac.app vocamac.debug.saveFailedAudio -bool true

Keeps the newest 20 recordings so it cannot fill the disk, and only fires
for audio that actually reached the decoder — digital silence is skipped
before inference and is not a failure.

Author: Mr-Sunglasses

Sources/VocaMac/Services/FailedAudioDump.swift

@@ -0,0 +1,112 @@
+// FailedAudioDump.swift
+// VocaMac
+//
+// Saves the audio behind a transcription that came back empty, so a failure
+// that only happens with a real microphone can be replayed through
+// `--transcribe-file` and debugged offline.
+
+import Foundation
+
+/// Writes the samples behind an empty transcription to a WAV file.
+///
+/// Off unless the user turns it on, because it puts recorded speech on disk:
+///
+///     defaults write com.vocamac.app vocamac.debug.saveFailedAudio -bool true
+enum FailedAudioDump {
+
+    static let preferenceKey = "vocamac.debug.saveFailedAudio"
+
+    /// Most recordings kept before the oldest are removed.
+    static let maximumFiles = 20
+
+    static var directory: URL {
+        VocaLogger.logDirectory().appendingPathComponent("failed-audio", isDirectory: true)
+    }
+
+    static var isEnabled: Bool {
+        UserDefaults.standard.bool(forKey: preferenceKey)
+    }
+
+    /// Save `samples` if the user asked for dumps. Returns the file written.
+    @discardableResult
+    static func save(_ samples: [Float], model: String, sampleRate: Int = 16_000) -> URL? {
+        guard isEnabled, !samples.isEmpty else { return nil }
+
+        let stamp = ISO8601DateFormatter.dumpFormatter.string(from: Date())
+        let url = directory.appendingPathComponent("\(stamp)-\(model).wav")
+
+        do {
+            try FileManager.default.createDirectory(
+                at: directory, withIntermediateDirectories: true
+            )
+            try wavData(from: samples, sampleRate: sampleRate).write(to: url)
+            pruneOldest()
+            VocaLogger.info(.sherpaService, "Saved the failed recording to \(url.path)")
+            return url
+        } catch {
+            VocaLogger.error(.sherpaService, "Could not save the failed recording: \(error)")
+            return nil
+        }
+    }
+
+    /// 16-bit mono PCM in a canonical 44-byte WAV container.
+    static func wavData(from samples: [Float], sampleRate: Int) -> Data {
+        let bytesPerSample = 2
+        let dataBytes = samples.count * bytesPerSample
+        var data = Data(capacity: 44 + dataBytes)
+
+        func append<T: FixedWidthInteger>(_ value: T) {
+            withUnsafeBytes(of: value.littleEndian) { data.append(contentsOf: $0) }
+        }
+
+        data.append(contentsOf: Array("RIFF".utf8))
+        append(UInt32(36 + dataBytes))
+        data.append(contentsOf: Array("WAVE".utf8))
+
+        data.append(contentsOf: Array("fmt ".utf8))
+        append(UInt32(16))                                  // PCM header size
+        append(UInt16(1))                                   // PCM
+        append(UInt16(1))                                   // mono
+        append(UInt32(sampleRate))
+        append(UInt32(sampleRate * bytesPerSample))         // byte rate
+        append(UInt16(bytesPerSample))                      // block align
+        append(UInt16(16))                                  // bits per sample
+
+        data.append(contentsOf: Array("data".utf8))
+        append(UInt32(dataBytes))
+        for sample in samples {
+            append(Int16(max(-1, min(1, sample)) * 32_767))
+        }
+        return data
+    }
+
+    /// Keep the newest `maximumFiles` dumps so this cannot fill the disk.
+    private static func pruneOldest() {
+        let fileManager = FileManager.default
+        guard let files = try? fileManager.contentsOfDirectory(
+            at: directory, includingPropertiesForKeys: [.creationDateKey]
+        ) else { return }
+
+        let sorted = files
+            .filter { $0.pathExtension == "wav" }
+            .sorted { left, right in
+                let leftDate = (try? left.resourceValues(forKeys: [.creationDateKey]))?.creationDate
+                let rightDate = (try? right.resourceValues(forKeys: [.creationDateKey]))?.creationDate
+                return (leftDate ?? .distantPast) > (rightDate ?? .distantPast)
+            }
+
+        for file in sorted.dropFirst(maximumFiles) {
+            try? fileManager.removeItem(at: file)
+        }
+    }
+}
+
+private extension ISO8601DateFormatter {
+    /// Colons are legal in HFS+ paths but confuse shell completion and tools.
+    static let dumpFormatter: ISO8601DateFormatter = {
+        let formatter = ISO8601DateFormatter()
+        formatter.formatOptions = [.withYear, .withMonth, .withDay, .withTime]
+        formatter.timeZone = .current
+        return formatter
+    }()
+}

Sources/VocaMac/Services/SherpaService.swift

@@ -330,6 +330,7 @@ final class SherpaService: @unchecked Sendable {
                     .sherpaService,
                     "ONNX decode returned no text for \(String(format: "%.1f", audioLengthSeconds))s of audio"
                 )
+                FailedAudioDump.save(audioData, model: size.rawValue)
             }
         } else {
             VocaLogger.info(.sherpaService, "Result: \(text.prefix(100))...")

Tests/VocaMacTests/FailedAudioDumpTests.swift

@@ -0,0 +1,30 @@
+import XCTest
+@testable import VocaMac
+
+final class FailedAudioDumpTests: XCTestCase {
+    func testWavDataIsAReadableSixteenBitMonoContainer() {
+        let samples: [Float] = [0, 0.5, -0.5, 1, -1]
+        let data = FailedAudioDump.wavData(from: samples, sampleRate: 16_000)
+
+        XCTAssertEqual(data.count, 44 + samples.count * 2)
+        XCTAssertEqual(String(data: data[0..<4], encoding: .ascii), "RIFF")
+        XCTAssertEqual(String(data: data[8..<12], encoding: .ascii), "WAVE")
+        XCTAssertEqual(String(data: data[36..<40], encoding: .ascii), "data")
+
+        func int16(at offset: Int) -> Int16 {
+            data.withUnsafeBytes { $0.loadUnaligned(fromByteOffset: offset, as: Int16.self) }
+        }
+        XCTAssertEqual(int16(at: 22), 1, "mono")
+        XCTAssertEqual(int16(at: 34), 16, "bits per sample")
+        XCTAssertEqual(int16(at: 44), 0)
+        XCTAssertEqual(int16(at: 46), 16_383)
+        XCTAssertEqual(int16(at: 50), 32_767)
+        XCTAssertEqual(int16(at: 52), -32_767)
+    }
+
+    func testDumpsAreOffUnlessTurnedOn() {
+        UserDefaults.standard.removeObject(forKey: FailedAudioDump.preferenceKey)
+        XCTAssertFalse(FailedAudioDump.isEnabled)
+        XCTAssertNil(FailedAudioDump.save([0.1, 0.2], model: "canary-180m-flash"))
+    }
+}