Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.
JavaScript aianthropiccross-platformgeminigroqlinuxmacosnvidiaopen-sourceopenaiparakeetspeech-to-texttranscribewhisperwindows
fix(dictation): Fail over a stalled managed Orukeet stream within seconds (#2387)
Chad Pihadef8b7c40368
diff --git a/src/helpers/ipcHandlers.js b/src/helpers/ipcHandlers.jsindex 1c4d902b7..0a45735ee 100644--- a/src/helpers/ipcHandlers.js+++ b/src/helpers/ipcHandlers.js@@ -1,4 +1,4 @@-const { OrukeetStreaming } = require("./orukeetStreaming");+const { OrukeetStreaming, MANAGED_STREAM_OPTIONS } = require("./orukeetStreaming");const { connectManagedOrukeet } = require("./orukeetCloudSession");const { ipcMain, app, shell, BrowserWindow, systemPreferences, net, session } = require("electron");const path = require("path");@@ -8436,11 +8436,9 @@ class IPCHandlers {// default lives here, at the boundary, so the token allowlist stays// fail-closed for genuinely unknown providers (#1624).const provider = options.provider ?? "openai-realtime";- // Managed Cloud retains the capture for batch fallback. A refused- // commit must close this attempt instead of retrying for 30 seconds.const streaming =provider === "orukeet"- ? new OrukeetStreaming({ retryCapacity: !isCloud })+ ? new OrukeetStreaming(isCloud ? MANAGED_STREAM_OPTIONS : {}): new OpenAIRealtimeStreaming();setupDictationCallbacks(streaming, event);// Assign before the token fetch (a real network round trip) sodiff --git a/src/helpers/orukeetStreaming.js b/src/helpers/orukeetStreaming.jsindex 259fad87b..2f726970f 100644--- a/src/helpers/orukeetStreaming.js+++ b/src/helpers/orukeetStreaming.js@@ -1,6 +1,22 @@const WebSocket = require("ws");const MAX_PENDING_BYTES = 2 * 1024 * 1024;+// Mono 16 kHz PCM16.+const BYTES_PER_SECOND = 32000;+const MAX_FINAL_WAIT_MS = 30000;++// Managed Cloud keeps the capture for a batch upload, so a stalled or+// unreachable GPU host should fail over within seconds rather than hold the+// user for the full 30 s budget. BYOK servers keep the defaults: they have no+// fallback, and a busy self-hosted CPU may legitimately answer slowly.+const MANAGED_STREAM_OPTIONS = {+ // A refused commit must close this attempt instead of retrying for 30 s.+ retryCapacity: false,+ timeoutMs: 10000,+ // Long enough to ride out a Wi-Fi roam or cellular hand-off.+ livenessMs: 8000,+ finalTimeoutMs: (audioSeconds) => 5000 + audioSeconds * 100,+};function languageMetadata(message) {const language = message.language;@@ -59,10 +75,14 @@ class OrukeetStreaming {createSocket = (url, options, protocols) => new WebSocket(url, protocols, options),timeoutMs = 30000,retryCapacity = true,+ livenessMs = null,+ finalTimeoutMs = () => timeoutMs,} = {}) {this.createSocket = createSocket;this.timeoutMs = timeoutMs;this.retryCapacity = retryCapacity;+ this.livenessMs = livenessMs;+ this.finalTimeoutMs = finalTimeoutMs;this.ws = null;this.isConnected = false;this.pendingAudio = [];@@ -143,7 +163,7 @@ class OrukeetStreaming {) {throw new Error("Orukeet server does not support mono 16 kHz PCM");}- this.maxAudioBytes = message.max_seconds * 32000;+ this.maxAudioBytes = message.max_seconds * BYTES_PER_SECOND;this.isConnected = true;this.connecting = false;for (const data of this.pendingAudio) this.writeAudio(data);@@ -155,6 +175,7 @@ class OrukeetStreaming {if (this.isConnected) this.sendControl({ type: "ping" });}, 15000);this.keepAlive.unref?.();+ this.startLivenessCheck();} else if (message.type === "language") {// Advisory audio-language metadata never commits a transcript or triggers a paste.// The final message remains authoritative for this recording.@@ -191,6 +212,44 @@ class OrukeetStreaming {}}+ // A wedged server can keep its TCP connection open, so a stall only shows up+ // as missing pongs. The check arms on the first pong: a server that never+ // answers pings keeps today's behaviour instead of failing every recording.+ // A pending commit is bounded by the final deadline instead, since inference+ // may hold the server's event loop.+ startLivenessCheck() {+ if (!this.livenessMs) return;+ const intervalMs = this.livenessMs / 2;+ let lastHeardAt = null;+ let lastCheckAt = performance.now();+ this.ws.on("pong", () => {+ lastHeardAt = performance.now();+ });+ this.ws.on("message", () => {+ if (lastHeardAt !== null) lastHeardAt = performance.now();+ });+ const check = () => {+ if (this.intentionalClose || this.failure || this.finalPromise) return;+ const now = performance.now();+ const late = now - lastCheckAt >= intervalMs * 1.5;+ lastCheckAt = now;+ if (lastHeardAt !== null) {+ // A late tick means this process was held up (a blocked main thread or+ // App Nap), not the server, so the next ping gets a full window.+ if (late) lastHeardAt = now;+ else if (now - lastHeardAt > this.livenessMs) {+ return this.fail(new Error("Orukeet server stopped responding"));+ }+ }+ this.ws.ping();+ };+ check();+ // After a blocked main thread, timers run before pending socket reads;+ // setImmediate lets a pong that already arrived count first.+ this.livenessTimer = setInterval(() => setImmediate(check), intervalMs);+ this.livenessTimer.unref?.();+ }+sendAudio(data) {if (this.intentionalClose || this.failure || this.finalPromise) return;const buffer = Buffer.from(data);@@ -219,12 +278,12 @@ class OrukeetStreaming {this.audioBytesSent += buffer.length;}- sendControl(message) {+ sendControl(message, onSent) {try {if (!this.isConnected || this.ws.readyState !== WebSocket.OPEN) {throw new Error("Orukeet connection closed before completion");}- this.ws.send(JSON.stringify(message));+ this.ws.send(JSON.stringify(message), onSent);} catch (error) {this.fail(error);}@@ -240,16 +299,21 @@ class OrukeetStreaming {this.finalPromise = new Promise((resolve, reject) => {this.finalResolve = resolve;this.finalReject = reject;- this.finalTimer = setTimeout(- () => this.fail(new Error("Orukeet final transcript timed out")),- this.timeoutMs- );- this.sendControl({ type: "commit" });+ const timedOut = () => this.fail(new Error("Orukeet final transcript timed out"));+ const audioSeconds = this.audioBytesSent / BYTES_PER_SECOND;+ // The commit queues behind audio still uploading, so the scaled deadline+ // starts once it is written; the cap bounds a slow upload.+ this.finalCapTimer = setTimeout(timedOut, MAX_FINAL_WAIT_MS);+ this.sendControl({ type: "commit" }, (error) => {+ if (error || !this.finalResolve) return;+ this.finalTimer = setTimeout(timedOut, this.finalTimeoutMs(audioSeconds));+ });});return this.finalPromise;}clearFinal() {+ clearTimeout(this.finalCapTimer);clearTimeout(this.finalTimer);clearTimeout(this.retryTimer);this.finalResolve = this.finalReject = null;@@ -279,11 +343,15 @@ class OrukeetStreaming {if (this.intentionalClose) return;this.intentionalClose = true;clearInterval(this.keepAlive);+ clearInterval(this.livenessTimer);this.isConnected = false;this.connecting = false;this.pendingAudio = [];this.pendingBytes = 0;- this.ws?.close();+ // A failed socket has nothing left to say, and a graceful close would wait+ // behind unsent audio for up to 30 s while the account's socket slot stays taken.+ if (this.failure) this.ws?.terminate();+ else this.ws?.close();this.onClose?.();}@@ -304,4 +372,4 @@ class OrukeetStreaming {}}-module.exports = { OrukeetStreaming, streamingUrl };+module.exports = { OrukeetStreaming, streamingUrl, MANAGED_STREAM_OPTIONS };diff --git a/test/helpers/orukeetDictationIpc.test.js b/test/helpers/orukeetDictationIpc.test.jsindex 44bc24d8a..eeef716b0 100644--- a/test/helpers/orukeetDictationIpc.test.js+++ b/test/helpers/orukeetDictationIpc.test.js@@ -27,7 +27,8 @@ const cloudSession = {};const { once, EventEmitter } = require("node:events");const { WebSocket, WebSocketServer } = require("ws");-const { OrukeetStreaming } = require("../../src/helpers/orukeetStreaming");+const orukeetStreamingModule = require("../../src/helpers/orukeetStreaming");+const { OrukeetStreaming, MANAGED_STREAM_OPTIONS } = orukeetStreamingModule;const AgentStreamRequestRegistry = require("../../src/helpers/agentStreamRequestRegistry");let server,target,@@ -103,6 +104,7 @@ Module._load = function loadWithMocks(request, parent, isMain) {if (parent?.filename === handlersModulePath) {if (request === "./orukeetStreaming")return {+ ...orukeetStreamingModule,OrukeetStreaming: class extends OrukeetStreaming {constructor(options) {super({@@ -253,6 +255,8 @@ test(true);const streaming = target._dictationStreaming;+ assert.equal(streaming.livenessMs, MANAGED_STREAM_OPTIONS.livenessMs);+ assert.equal(streaming.finalTimeoutMs, MANAGED_STREAM_OPTIONS.finalTimeoutMs);const closed = once(streaming.ws, "close");handlers.get("dictation-realtime-send")(event, Buffer.alloc(640));const final = await handlers.get("dictation-realtime-finalize")();@@ -285,6 +289,7 @@ test("self-hosted IPC still retries a capacity-refused commit without re-uploadibaseUrl: cloudSession.baseUrl,});assert.equal(start.success, true);+ assert.equal(target._dictationStreaming.livenessMs, null, "self-hosted servers are never pinged");handlers.get("dictation-realtime-send")(event, Buffer.alloc(640));const final = await handlers.get("dictation-realtime-finalize")();diff --git a/test/helpers/orukeetStreaming.test.js b/test/helpers/orukeetStreaming.test.jsindex 85e3cbf19..db22d6e4a 100644--- a/test/helpers/orukeetStreaming.test.js+++ b/test/helpers/orukeetStreaming.test.js@@ -1,16 +1,22 @@const test = require("node:test");const assert = require("node:assert/strict");-const { once } = require("node:events");-const { WebSocketServer } = require("ws");-const { OrukeetStreaming, streamingUrl } = require("../../src/helpers/orukeetStreaming");+const { EventEmitter, once } = require("node:events");+const { Worker } = require("node:worker_threads");+const { WebSocket, WebSocketServer } = require("ws");+const {+ OrukeetStreaming,+ streamingUrl,+ MANAGED_STREAM_OPTIONS,+} = require("../../src/helpers/orukeetStreaming");-async function fixture(t, onMessage) {- const server = new WebSocketServer({ port: 0, host: "127.0.0.1" });+async function fixture(t, onMessage, { serverOptions, adapterOptions, onConnection } = {}) {+ const server = new WebSocketServer({ port: 0, host: "127.0.0.1", ...serverOptions });await once(server, "listening");const seen = [];server.on("connection", (socket, request) => {assert.equal(request.headers.authorization, "Bearer test-key");assert.equal(request.url, "/v1/audio/transcriptions/stream");+ onConnection?.(socket);socket.send(JSON.stringify({type: "ready",@@ -26,7 +32,7 @@ async function fixture(t, onMessage) {onMessage?.(socket, event, seen);});});- const adapter = new OrukeetStreaming({ timeoutMs: 300 });+ const adapter = new OrukeetStreaming({ timeoutMs: 300, ...adapterOptions });t.after(async () => {await adapter.disconnect();for (const socket of server.clients) socket.terminate();@@ -167,7 +173,10 @@ test("missing final acknowledgement has a bounded timeout", async (t) => {const { adapter, options } = await fixture(t);await adapter.connect(options);adapter.sendAudio(Buffer.alloc(640));+ const started = performance.now();await assert.rejects(adapter.finalize(), /timed out/);+ // Self-hosted streams wait their connect timeout (300 ms here) for a final.+ assert.ok(performance.now() - started < 1000);});test("URL normalization retains the selected server and refuses unsafe credential URLs", () => {@@ -311,3 +320,307 @@ test("a failure while the session token is minted raises no stream error", async);assert.deepEqual(errors, []);});++// Answers pings until the test stalls it, like a GPU host whose server process+// wedges while its TCP connection stays open.+async function stallableFixture(t, onMessage, adapterOptions) {+ const control = { answering: true, delayMs: 0, socket: null };+ const setup = await fixture(t, onMessage, {+ serverOptions: { autoPong: false },+ adapterOptions,+ onConnection: (socket) => {+ control.socket = socket;+ socket.on("ping", (data) => {+ if (!control.answering) return;+ if (control.delayMs) setTimeout(() => socket.pong(data), control.delayMs);+ else socket.pong(data);+ });+ },+ });+ return { ...setup, control };+}++test(+ "a stream whose server stops answering pings fails while recording",+ { timeout: 2000 },+ async (t) => {+ const livenessMs = 400;+ const { adapter, options, control } = await stallableFixture(t, undefined, { livenessMs });+ const raised = new Promise((resolve) => {+ adapter.onError = resolve;+ });+ await adapter.connect(options);+ await once(adapter.ws, "pong");+ const closed = once(control.socket, "close");+ control.answering = false;+ const stalledAt = performance.now();+ adapter.sendAudio(Buffer.alloc(640));++ assert.match((await raised).message, /stopped responding/);+ const detectedAfter = performance.now() - stalledAt;+ assert.ok(+ detectedAfter > livenessMs - 20 && detectedAfter < livenessMs * 2,+ `${detectedAfter}`+ );+ await assert.rejects(adapter.finalize(), /stopped responding/);+ // Dropped rather than closed behind unsent audio, so the server sees 1006.+ assert.equal((await closed)[0], 1006);+ }+);++test("a blocked main thread is not judged a stalled server", { timeout: 5000 }, async (t) => {+ const livenessMs = 400;+ const { adapter, options, control } = await stallableFixture(+ t,+ (socket, event) => {+ if (event.type === "commit") socket.send(JSON.stringify({ type: "final", text: "Kept." }));+ },+ { livenessMs }+ );+ const errors = [];+ adapter.onError = (error) => errors.push(error);+ await adapter.connect(options);+ await new Promise((resolve) =>+ adapter.ws.once("pong", () => {+ // The ping sent after the block is answered later than one check+ // interval, but within the liveness window.+ control.delayMs = livenessMs * 0.75;+ const until = performance.now() + livenessMs * 2.5;+ while (performance.now() < until);+ resolve();+ })+ );+ adapter.sendAudio(Buffer.alloc(640));+ await new Promise((resolve) => setTimeout(resolve, livenessMs * 1.5));++ assert.deepEqual(errors, []);+ assert.equal((await adapter.finalize()).text, "Kept.");+});++// Runs the server on its own thread, so it answers while the test blocks the+// main thread. Each ping is reported to the main thread before its pong.+async function threadedServer(t, pongDelayMs) {+ const worker = new Worker(+ `+ const { parentPort } = require("node:worker_threads");+ const { WebSocketServer } = require(${JSON.stringify(require.resolve("ws"))});+ const server = new WebSocketServer({ port: 0, host: "127.0.0.1", autoPong: false });+ server.on("listening", () => parentPort.postMessage(server.address().port));+ server.on("connection", (socket) => {+ socket.on("ping", (data) => {+ parentPort.postMessage("ping");+ setTimeout(() => socket.pong(data), ${pongDelayMs});+ });+ socket.send(+ JSON.stringify({+ type: "ready",+ sample_rate: 16000,+ channels: 1,+ encoding: "pcm_s16le",+ max_seconds: 60,+ })+ );+ });+ `,+ { eval: true }+ );+ t.after(() => worker.terminate());+ const [port] = await once(worker, "message");+ return { worker, options: { baseUrl: `http://127.0.0.1:${port}`, apiKey: "test-key" } };+}++test(+ "a pong that arrived while the main thread was blocked counts",+ { timeout: 5000 },+ async (t) => {+ const { worker, options } = await threadedServer(t, 20);+ const livenessMs = 1000;+ const adapter = new OrukeetStreaming({ timeoutMs: 1000, livenessMs });+ t.after(() => adapter.disconnect());+ const errors = [];+ adapter.onError = (error) => errors.push(error);+ await adapter.connect(options);+ await once(adapter.ws, "pong");+ let pinged = false;+ const ping = adapter.ws.ping.bind(adapter.ws);+ adapter.ws.ping = () => {+ ping();+ adapter.ws.ping = ping;+ pinged = true;+ };+ worker.on("message", () => {+ if (!pinged) return;+ pinged = false;+ // Blocks until just past the next check's due time, so that check is on+ // time while the pong waiting on the socket is its only sign of life.+ const until = performance.now() + livenessMs * 0.65;+ while (performance.now() < until);+ });+ await new Promise((resolve) => setTimeout(resolve, livenessMs * 1.5));++ assert.deepEqual(errors, []);+ }+);++test("any server message keeps an armed stream alive", { timeout: 2000 }, async (t) => {+ const livenessMs = 200;+ const { adapter, options, control } = await stallableFixture(t, undefined, { livenessMs });+ const errors = [];+ adapter.onError = (error) => errors.push(error);+ await adapter.connect(options);+ await once(adapter.ws, "pong");+ control.answering = false;+ const language = JSON.stringify({ type: "language", language: "en", language_confidence: 0.9 });+ const chatter = setInterval(() => control.socket.send(language), livenessMs / 4);+ await new Promise((resolve) => setTimeout(resolve, livenessMs * 3));+ clearInterval(chatter);++ assert.deepEqual(errors, []);+});++test("a server that never answers pings is not judged stalled", { timeout: 2000 }, async (t) => {+ const { adapter, options, control } = await stallableFixture(+ t,+ (socket, event) => {+ if (event.type === "commit") socket.send(JSON.stringify({ type: "final", text: "Kept." }));+ },+ { livenessMs: 50 }+ );+ control.answering = false;+ await adapter.connect(options);+ adapter.sendAudio(Buffer.alloc(640));+ await new Promise((resolve) => setTimeout(resolve, 200));++ assert.equal((await adapter.finalize()).text, "Kept.");+});++test(+ "a commit awaiting its final is bounded by the final deadline, not liveness",+ { timeout: 2000 },+ async (t) => {+ const { adapter, options, control } = await stallableFixture(+ t,+ (socket, event) => {+ if (event.type !== "commit") return;+ // Inference can hold the server's event loop, so pongs stop meanwhile.+ control.answering = false;+ setTimeout(() => socket.send(JSON.stringify({ type: "final", text: "Slow." })), 200);+ },+ { livenessMs: 50, timeoutMs: 1000 }+ );+ await adapter.connect(options);+ await once(adapter.ws, "pong");+ adapter.sendAudio(Buffer.alloc(640));++ assert.equal((await adapter.finalize()).text, "Slow.");+ }+);++test("a closed stream stops checking liveness", { timeout: 2000 }, async (t) => {+ const { adapter, options } = await stallableFixture(t, undefined, { livenessMs: 50 });+ const errors = [];+ adapter.onError = (error) => errors.push(error);+ await adapter.connect(options);+ await once(adapter.ws, "pong");+ await adapter.disconnect();+ await new Promise((resolve) => setTimeout(resolve, 200));++ assert.deepEqual(errors, []);+});++// A ready socket whose writes complete only when the test says so, like an+// uplink still draining audio queued ahead of the commit.+async function heldSocketAdapter(t, adapterOptions) {+ const socket = Object.assign(new EventEmitter(), {+ readyState: WebSocket.OPEN,+ bufferedAmount: 0,+ writes: [],+ send: (data, onSent) => socket.writes.push({ data, onSent }),+ close: () => {},+ terminate: () => {},+ });+ const adapter = new OrukeetStreaming({ createSocket: () => socket, ...adapterOptions });+ t.after(() => adapter.disconnect());+ const connected = adapter.connect({ baseUrl: "https://orukeet.test", apiKey: "test-key" });+ socket.emit(+ "message",+ JSON.stringify({+ type: "ready",+ sample_rate: 16000,+ channels: 1,+ encoding: "pcm_s16le",+ max_seconds: 60,+ })+ );+ await connected;+ const writeCommit = () => {+ const commit = socket.writes.at(-1);+ assert.equal(JSON.parse(commit.data).type, "commit");+ commit.onSent();+ };+ return { adapter, socket, writeCommit };+}++test(+ "the final deadline scales with the audio and starts once the commit is written",+ { timeout: 2000 },+ async (t) => {+ t.mock.timers.enable({ apis: ["setTimeout"] });+ const { adapter, writeCommit } = await heldSocketAdapter(t, {+ finalTimeoutMs: (audioSeconds) => audioSeconds * 1000,+ });+ adapter.sendAudio(Buffer.alloc(64000)); // 2 s of 16 kHz PCM16+ const final = adapter.finalize();+ final.catch(() => {});++ t.mock.timers.tick(10000);+ assert.equal(adapter.failure, undefined);+ writeCommit();+ t.mock.timers.tick(1999);+ assert.equal(adapter.failure, undefined);+ t.mock.timers.tick(1);+ await assert.rejects(final, /final transcript timed out/);+ }+);++test(+ "a commit that is never written out still times out after 30 s",+ { timeout: 2000 },+ async (t) => {+ t.mock.timers.enable({ apis: ["setTimeout"] });+ const { adapter } = await heldSocketAdapter(t, { finalTimeoutMs: () => 1000 });+ adapter.sendAudio(Buffer.alloc(640));+ const final = adapter.finalize();+ final.catch(() => {});++ t.mock.timers.tick(29999);+ assert.equal(adapter.failure, undefined);+ t.mock.timers.tick(1);+ await assert.rejects(final, /final transcript timed out/);+ }+);++test("a delivered final clears the 30 s cap", { timeout: 2000 }, async (t) => {+ t.mock.timers.enable({ apis: ["setTimeout"] });+ const { adapter, socket, writeCommit } = await heldSocketAdapter(t, {+ finalTimeoutMs: () => 1000,+ });+ let closed = false;+ adapter.onClose = () => (closed = true);+ adapter.sendAudio(Buffer.alloc(640));+ const final = adapter.finalize();+ writeCommit();+ socket.emit("message", JSON.stringify({ type: "final", text: "Done." }));+ assert.equal((await final).text, "Done.");++ t.mock.timers.tick(30000);+ assert.equal(closed, false);+});++test("managed streams fail over within seconds instead of the 30 s budget", () => {+ assert.equal(MANAGED_STREAM_OPTIONS.retryCapacity, false);+ assert.equal(MANAGED_STREAM_OPTIONS.livenessMs, 8000);+ assert.equal(MANAGED_STREAM_OPTIONS.timeoutMs, 10000);+ assert.equal(MANAGED_STREAM_OPTIONS.finalTimeoutMs(0), 5000);+ assert.equal(MANAGED_STREAM_OPTIONS.finalTimeoutMs(60), 11000);+});