@hasna/recordings 0.1.14 → 0.1.16

package/dist/cli/index.js

@@ -7,7 +7,7 @@ var __require = import.meta.require;
 var require_package = __commonJS((exports, module) => {
   module.exports = {
     name: "@hasna/recordings",
-    version: "0.1.14",
+    version: "0.1.16",
     type: "module",
     description: "Speech-to-text recording tool with MCP and CLI \u2014 records, transcribes, and optionally enhances text using AI",
     repository: {
@@ -10466,7 +10466,7 @@ async function processText(rawText, config, systemPrompt) {
 }
 
 // src/version.ts
-var VERSION = "0.1.14";
+var VERSION = "0.1.16";
 
 // src/cli/index.ts
 var program = new Command;

package/dist/mcp/index.js

@@ -21,7 +21,7 @@ var __require = import.meta.require;
 var require_package = __commonJS((exports, module) => {
   module.exports = {
     name: "@hasna/recordings",
-    version: "0.1.14",
+    version: "0.1.16",
     type: "module",
     description: "Speech-to-text recording tool with MCP and CLI \u2014 records, transcribes, and optionally enhances text using AI",
     repository: {
@@ -14983,7 +14983,7 @@ async function processText(rawText, config, systemPrompt) {
 }
 
 // src/version.ts
-var VERSION = "0.1.14";
+var VERSION = "0.1.16";
 
 // src/mcp/index.ts
 var config = loadConfig();

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.1.14";
+export declare const VERSION = "0.1.16";
 //# sourceMappingURL=version.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/recordings",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "type": "module",
   "description": "Speech-to-text recording tool with MCP and CLI — records, transcribes, and optionally enhances text using AI",
   "repository": {

package/src/native/Recordings/RecordingsLib/RealtimeTranscriptionClient.swift

@@ -16,12 +16,24 @@ public final class RealtimeTranscriptionClient: ObservableObject, @unchecked Sen
 
     private var ws: URLSessionWebSocketTask?
     private var receiveTask: Task<Void, Never>?
+    private var outboundEventTask: Task<Void, Never>?
+    private var liveCommitTask: Task<Void, Never>?
     private var isConfigured = false
     private var pendingAudioChunks: [Data] = []
     private var itemOrder: [String] = []
     private var deltaTextByItem: [String: String] = [:]
     private var completedTextByItem: [String: String] = [:]
+    private var committedItemIDs = Set<String>()
+    private var completedItemIDs = Set<String>()
     private var completedEventCount = 0
+    private var queuedCommitCount = 0
+    private var uncommittedAudioBytes = 0
+    private var lastRealtimeEventAt = Date.distantPast
+    private var lastCommitQueuedAt = Date.distantPast
+
+    private nonisolated static let minimumManualCommitBytes = 5_760
+    private nonisolated static let minimumLiveCommitBytes = 38_400
+    private nonisolated static let liveCommitIntervalSeconds: TimeInterval = 0.8
 
     private let apiKey: String
     private let homePath: String
@@ -52,7 +64,13 @@ public final class RealtimeTranscriptionClient: ObservableObject, @unchecked Sen
         itemOrder.removeAll(keepingCapacity: true)
         deltaTextByItem.removeAll(keepingCapacity: true)
         completedTextByItem.removeAll(keepingCapacity: true)
+        committedItemIDs.removeAll(keepingCapacity: true)
+        completedItemIDs.removeAll(keepingCapacity: true)
         completedEventCount = 0
+        queuedCommitCount = 0
+        uncommittedAudioBytes = 0
+        lastRealtimeEventAt = Date()
+        lastCommitQueuedAt = Date()
         error = nil
 
         var request = URLRequest(url: Self.transcriptionURL)
@@ -98,36 +116,53 @@ public final class RealtimeTranscriptionClient: ObservableObject, @unchecked Sen
             return
         }
         let base64 = data.base64EncodedString()
+        uncommittedAudioBytes += data.count
         let msg: [String: Any] = [
             "type": "input_audio_buffer.append",
             "audio": base64,
         ]
-        Task { [weak self] in
-            try? await self?.sendEvent(msg)
-        }
+        enqueueOutboundEvent(msg)
+        scheduleLiveCommitIfNeeded()
     }
 
     /// Signal end of input — triggers final transcription completion.
-    public func commitInput() async {
-        guard isStreaming, ws != nil else { return }
+    @discardableResult
+    public func commitInput(reason: String = "final") async -> Bool {
+        guard isStreaming, ws != nil else { return false }
         flushPendingAudio()
+        let bytesToCommit = uncommittedAudioBytes
+        guard Self.shouldManuallyCommit(uncommittedAudioBytes: bytesToCommit) else {
+            return false
+        }
         let msg: [String: Any] = [
             "type": "input_audio_buffer.commit",
         ]
-        try? await sendEvent(msg)
+        uncommittedAudioBytes = 0
+        queuedCommitCount += 1
+        lastRealtimeEventAt = Date()
+        lastCommitQueuedAt = Date()
+        NativeAppLog.write("realtime commit queued reason=\(reason) bytes=\(bytesToCommit)", homePath: homePath)
+        let commitTask = enqueueOutboundEvent(msg)
+        await commitTask?.value
+        return true
     }
 
     /// Commit buffered input, wait briefly for a final completed event, then close.
-    public func finish(timeoutMilliseconds: UInt64 = 1_800) async -> String {
+    public func finish(timeoutMilliseconds: UInt64 = 2_800) async -> String {
         guard isStreaming else { return accumulatedText }
-        let initialCompletedCount = completedEventCount
-        if initialCompletedCount > 0 {
-            return stop()
-        }
-        await commitInput()
+        let completedCountBeforeCommit = completedEventCount
+        let didManualCommit = await commitInput()
+        let expectedCommitCount = queuedCommitCount
 
         let deadline = Date().addingTimeInterval(TimeInterval(timeoutMilliseconds) / 1_000)
-        while Date() < deadline, isStreaming, completedEventCount == initialCompletedCount {
+        while Date() < deadline, isStreaming {
+            let hasIncompleteCommittedItems = !committedItemIDs.subtracting(completedItemIDs).isEmpty
+            let hasManualCommitCompletion = !didManualCommit || completedEventCount > completedCountBeforeCommit
+            let hasQueuedCommitCompletion = completedEventCount >= expectedCommitCount
+            let quietLongEnough = Date().timeIntervalSince(lastRealtimeEventAt) >= 0.35
+            if !hasIncompleteCommittedItems, hasManualCommitCompletion, hasQueuedCommitCompletion, quietLongEnough {
+                break
+            }
             try? await Task.sleep(for: .milliseconds(50))
         }
 
@@ -142,8 +177,12 @@ public final class RealtimeTranscriptionClient: ObservableObject, @unchecked Sen
         isConfigured = false
         receiveTask?.cancel()
         ws?.cancel(with: .normalClosure, reason: nil)
+        outboundEventTask?.cancel()
+        liveCommitTask?.cancel()
         ws = nil
         receiveTask = nil
+        outboundEventTask = nil
+        liveCommitTask = nil
         pendingAudioChunks.removeAll(keepingCapacity: true)
         let text = accumulatedText
         return text
@@ -183,11 +222,14 @@ public final class RealtimeTranscriptionClient: ObservableObject, @unchecked Sen
 
         switch type {
         case "input_audio_buffer.committed":
+            lastRealtimeEventAt = Date()
             if let itemID = json["item_id"] as? String {
                 registerItem(itemID, previousItemID: json["previous_item_id"] as? String)
+                committedItemIDs.insert(itemID)
             }
 
         case "conversation.item.input_audio_transcription.delta":
+            lastRealtimeEventAt = Date()
             let itemID = json["item_id"] as? String ?? "__default__"
             registerItem(itemID, previousItemID: nil)
             if let delta = json["delta"] as? String {
@@ -197,21 +239,29 @@ public final class RealtimeTranscriptionClient: ObservableObject, @unchecked Sen
 
         case "conversation.item.input_audio_transcription.completed":
             // The server may send the complete transcript here
+            lastRealtimeEventAt = Date()
             let itemID = json["item_id"] as? String ?? "__default__"
             registerItem(itemID, previousItemID: nil)
+            completedItemIDs.insert(itemID)
+            completedEventCount += 1
             if let text = json["transcript"] as? String, !text.isEmpty {
                 completedTextByItem[itemID] = text
-                completedEventCount += 1
-                rebuildAccumulatedText()
             }
+            rebuildAccumulatedText()
 
         case "conversation.item.input_audio_transcription.failed":
+            lastRealtimeEventAt = Date()
+            if let itemID = json["item_id"] as? String {
+                completedItemIDs.insert(itemID)
+                completedEventCount += 1
+            }
             if let msg = json["error"] as? [String: Any],
                let message = msg["message"] as? String {
                 self.error = message
             }
 
         case "error":
+            lastRealtimeEventAt = Date()
             if let detail = json["error"] as? [String: Any],
                let msg = detail["message"] as? String {
                 fputs("[RealtimeClient] Error: \(msg)\n", stderr)
@@ -223,6 +273,37 @@ public final class RealtimeTranscriptionClient: ObservableObject, @unchecked Sen
         }
     }
 
+    @discardableResult
+    private func enqueueOutboundEvent(_ obj: [String: Any]) -> Task<Void, Never>? {
+        guard ws != nil else { return nil }
+        let previousTask = outboundEventTask
+        let task = Task { [weak self] in
+            await previousTask?.value
+            try? await self?.sendEvent(obj)
+        }
+        outboundEventTask = task
+        return task
+    }
+
+    private func scheduleLiveCommitIfNeeded(now: Date = Date()) {
+        guard liveCommitTask == nil else { return }
+        let secondsSinceLastCommit = now.timeIntervalSince(lastCommitQueuedAt)
+        guard Self.shouldAutoCommitLiveInput(
+            uncommittedAudioBytes: uncommittedAudioBytes,
+            secondsSinceLastCommit: secondsSinceLastCommit
+        ) else { return }
+
+        liveCommitTask = Task { [weak self] in
+            _ = await self?.commitLiveInput()
+        }
+    }
+
+    @discardableResult
+    private func commitLiveInput() async -> Bool {
+        defer { liveCommitTask = nil }
+        return await commitInput(reason: "live")
+    }
+
     private func registerItem(_ itemID: String, previousItemID: String?) {
         guard !itemOrder.contains(itemID) else { return }
         if let previousItemID, let previousIndex = itemOrder.firstIndex(of: previousItemID) {
@@ -298,6 +379,18 @@ public final class RealtimeTranscriptionClient: ObservableObject, @unchecked Sen
         return output
     }
 
+    private nonisolated static func shouldManuallyCommit(uncommittedAudioBytes: Int) -> Bool {
+        uncommittedAudioBytes >= minimumManualCommitBytes
+    }
+
+    private nonisolated static func shouldAutoCommitLiveInput(
+        uncommittedAudioBytes: Int,
+        secondsSinceLastCommit: TimeInterval
+    ) -> Bool {
+        uncommittedAudioBytes >= minimumLiveCommitBytes &&
+            secondsSinceLastCommit >= liveCommitIntervalSeconds
+    }
+
     private nonisolated static func transcriptionSessionUpdateEvent(transcription: [String: Any]) -> [String: Any] {
         [
             "type": "session.update",
@@ -310,12 +403,7 @@ public final class RealtimeTranscriptionClient: ObservableObject, @unchecked Sen
                             "rate": 24_000,
                         ],
                         "transcription": transcription,
-                        "turn_detection": [
-                            "type": "server_vad",
-                            "threshold": 0.5,
-                            "prefix_padding_ms": 300,
-                            "silence_duration_ms": 350,
-                        ],
+                        "turn_detection": NSNull(),
                         "noise_reduction": [
                             "type": "near_field",
                         ],
@@ -366,6 +454,20 @@ extension RealtimeTranscriptionClient {
         joinTranscriptParts(parts)
     }
 
+    public nonisolated static func shouldManuallyCommitTestHelper(uncommittedAudioBytes: Int) -> Bool {
+        shouldManuallyCommit(uncommittedAudioBytes: uncommittedAudioBytes)
+    }
+
+    public nonisolated static func shouldAutoCommitLiveInputTestHelper(
+        uncommittedAudioBytes: Int,
+        secondsSinceLastCommit: TimeInterval
+    ) -> Bool {
+        shouldAutoCommitLiveInput(
+            uncommittedAudioBytes: uncommittedAudioBytes,
+            secondsSinceLastCommit: secondsSinceLastCommit
+        )
+    }
+
     public nonisolated static func sessionUpdateTestHelper(prompt: String, language: String = "") -> [String: Any] {
         var transcription: [String: Any] = [
             "model": modelID,

package/src/native/Recordings/RecordingsLib/RecordingEngine.swift

@@ -457,7 +457,7 @@ public final class RecordingEngine: ObservableObject {
 
             self.liveTranscriptionText = ""
 
-            if let text {
+            if let text, !Self.shouldFallbackFromPartialRealtime(text: text, pcmByteCount: self.recordedPCM.count) {
                 self.log("finish using realtime text chars=\(text.count)")
                 self.isTranscribing = false
                 self.finishWithText(
@@ -468,6 +468,9 @@ public final class RecordingEngine: ObservableObject {
                     activeProjectName: activeProjectName
                 )
             } else if let audioPath, self.writeCapturedWAV(to: audioPath) {
+                if let text {
+                    self.log("realtime text looked partial chars=\(text.count); falling back to CLI")
+                }
                 self.log("falling back to CLI transcription audioPath=\(audioPath)")
                 self.fallbackTranscribe(
                     audioPath: audioPath,
@@ -486,6 +489,13 @@ public final class RecordingEngine: ObservableObject {
         }
     }
 
+    public nonisolated static func shouldFallbackFromPartialRealtime(text: String, pcmByteCount: Int) -> Bool {
+        let trimmed = text.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard pcmByteCount >= 48_000, !trimmed.isEmpty else { return false }
+        let words = trimmed.split(whereSeparator: { $0.isWhitespace || $0.isNewline })
+        return trimmed.count < 12 || words.count <= 2
+    }
+
     private func finishWithText(_ text: String, curMode: RecordingMode, targetAppBundleIdentifier: String?, activeProjectId: String?, activeProjectName: String?) {
         log("finishWithText mode=\(curMode.rawValue) chars=\(text.count)")
         if curMode == .command {

package/src/native/Recordings/RecordingsTests/RealtimeTranscriptionTests.swift

@@ -1,3 +1,4 @@
+import Foundation
 import Testing
 @testable import RecordingsLib
 
@@ -98,8 +99,7 @@ struct RealtimeTranscriptionTests {
         #expect(transcription?["prompt"] as? String == "Use Alumia as vocabulary")
         #expect(transcription?["language"] as? String == "en")
 
-        let turnDetection = input?["turn_detection"] as? [String: Any]
-        #expect(turnDetection?["type"] as? String == "server_vad")
+        #expect(input?["turn_detection"] is NSNull)
 
         let include = session?["include"] as? [String]
         #expect(include?.contains("item.input_audio_transcription.logprobs") == true)
@@ -110,4 +110,33 @@ struct RealtimeTranscriptionTests {
         let text = RealtimeTranscriptionClient.joinTranscriptPartsTestHelper(["Hello", "world.", " Next"])
         #expect(text == "Hello world. Next")
     }
+
+    @Test("Manual commit waits for enough buffered PCM audio")
+    func manualCommitThreshold() {
+        #expect(RealtimeTranscriptionClient.shouldManuallyCommitTestHelper(uncommittedAudioBytes: 4_799) == false)
+        #expect(RealtimeTranscriptionClient.shouldManuallyCommitTestHelper(uncommittedAudioBytes: 5_760) == true)
+    }
+
+    @Test("Live commits wait for enough audio and elapsed time")
+    func liveCommitThreshold() {
+        #expect(RealtimeTranscriptionClient.shouldAutoCommitLiveInputTestHelper(
+            uncommittedAudioBytes: 38_399,
+            secondsSinceLastCommit: 1.0
+        ) == false)
+        #expect(RealtimeTranscriptionClient.shouldAutoCommitLiveInputTestHelper(
+            uncommittedAudioBytes: 38_400,
+            secondsSinceLastCommit: 0.79
+        ) == false)
+        #expect(RealtimeTranscriptionClient.shouldAutoCommitLiveInputTestHelper(
+            uncommittedAudioBytes: 38_400,
+            secondsSinceLastCommit: 0.8
+        ) == true)
+    }
+
+    @Test("Partial realtime text falls back for longer recordings")
+    func partialRealtimeFallback() {
+        #expect(RecordingEngine.shouldFallbackFromPartialRealtime(text: "Hi", pcmByteCount: 96_000) == true)
+        #expect(RecordingEngine.shouldFallbackFromPartialRealtime(text: "This is a complete sentence.", pcmByteCount: 96_000) == false)
+        #expect(RecordingEngine.shouldFallbackFromPartialRealtime(text: "Hi", pcmByteCount: 12_000) == false)
+    }
 }