Skip to content

Write HTML. Render video. Built for agents.

feat(cli): stream heard words on the transcribe --json progress stream (#5127)

Miguel Ángel156e87766c77
diff --git a/packages/cli/src/commands/transcribe.test.ts b/packages/cli/src/commands/transcribe.test.ts
index 81d0ff9728..4c444dbdf2 100644
--- a/packages/cli/src/commands/transcribe.test.ts
+++ b/packages/cli/src/commands/transcribe.test.ts
@@ -219,6 +219,21 @@ describe("transcribe command", () => {
return { engine: out.engine, model: out.model, word: words[0]?.text, start: words[0]?.start };
}
+ it("installs whisper's stop handling only when whisper starts, after any install or download", async () => {
+ const run = transcribeMock.getMockImplementation()!;
+ const handlers: number[] = [];
+ let signal: unknown;
+ transcribeMock.mockImplementationOnce(async (input, outputDir, options) => {
+ handlers.push(process.listenerCount("SIGTERM"));
+ signal = options.startCancellation();
+ handlers.push(process.listenerCount("SIGTERM"));
+ return run(input, outputDir, options);
+ });
+ await transcribeWith("whisper", { sherpa: false, mlx: false });
+ expect(signal).toBeInstanceOf(AbortSignal);
+ expect(handlers[1]).toBeGreaterThan(handlers[0]!);
+ });
+
it("auto and parakeet prefer sherpa-onnx, then parakeet-mlx, then whisper", async () => {
const sherpa = {
engine: "parakeet",
diff --git a/packages/cli/src/commands/transcribe.ts b/packages/cli/src/commands/transcribe.ts
index 0ba69b7e00..c37e14b7b9 100644
--- a/packages/cli/src/commands/transcribe.ts
+++ b/packages/cli/src/commands/transcribe.ts
@@ -353,7 +353,7 @@ async function transcribeAudio(
const onEvent = opts.json ? createProgressWriter(process.stderr) : undefined;
let wavPath = inputPath;
// Before audio prep: under --json no spinner listens for SIGINT, so Ctrl-C would kill Node.
- const cancellation = runner === "sherpa" ? createRenderCancellationScope() : null;
+ let cancellation = runner === "sherpa" ? createRenderCancellationScope() : null;
const run = (r: Runner) => {
switch (r) {
case "sherpa":
@@ -375,6 +375,7 @@ async function transcribeAudio(
onEvent,
timeoutMs: opts.timeoutMs,
installRuntime: opts.installRuntime,
+ startCancellation: () => (cancellation ??= createRenderCancellationScope()).signal,
});
default: {
const unreachable: never = r;
@@ -401,7 +402,7 @@ async function transcribeAudio(
try {
result = await run(runner);
} catch (fallbackErr) {
- // Whisper runs synchronously, so Ctrl-C shows as its child's signal before any listener runs.
+ // Ctrl-C reaches whisper too, so it can stop on its own signal before the scope aborts it.
if (stoppedByCancelSignal(fallbackErr as { signal?: string })) {
throw new DecodeCancelled("Transcription cancelled");
}
diff --git a/packages/cli/src/whisper/parakeet.ts b/packages/cli/src/whisper/parakeet.ts
index 978df811be..14809d5b40 100644
--- a/packages/cli/src/whisper/parakeet.ts
+++ b/packages/cli/src/whisper/parakeet.ts
@@ -25,6 +25,7 @@ export const PARAKEET_MODEL_LABEL = "parakeet-tdt-0.6b-v3";
/** Stdout/stderr line prefixes of the sherpa-onnx decode worker. */
export const SHERPA_RESULT_PREFIX = "HYPERFRAMES_PARAKEET_RESULT:";
export const SHERPA_ERROR_PREFIX = "HYPERFRAMES_PARAKEET_ERROR:";
+export const SHERPA_WINDOW_PREFIX = "HYPERFRAMES_PARAKEET_WINDOW:";
/** Parakeet TDT 0.6B v3's languages, as listed on its model card. */
export const PARAKEET_LANGUAGES =
diff --git a/packages/cli/src/whisper/progress.test.ts b/packages/cli/src/whisper/progress.test.ts
index 5fd8864148..0d68f7451c 100644
--- a/packages/cli/src/whisper/progress.test.ts
+++ b/packages/cli/src/whisper/progress.test.ts
@@ -1,7 +1,30 @@
import { Writable } from "node:stream";
import { setImmediate } from "node:timers/promises";
import { expect, it } from "vitest";
-import { createProgressWriter } from "./progress.js";
+import { createProgressWriter, emitWords } from "./progress.js";
+import type { TranscribeProgress } from "./transcribe.js";
+
+it("splits a long run of words into lines under 16 KB and keeps every word in order", () => {
+ const events: TranscribeProgress[] = [];
+ const words = Array.from({ length: 2000 }, (_, i) => ({
+ text: `word${i}`,
+ start: i,
+ end: i + 0.5,
+ }));
+ emitWords((e) => events.push(e), "tiny", words, 2100);
+
+ expect(events.length).toBeGreaterThan(1);
+ for (const event of events)
+ expect(Buffer.byteLength(`${JSON.stringify(event)}\n`)).toBeLessThan(16_384);
+ expect(events.flatMap((e) => (e.type === "words" ? e.words : []))).toEqual(words);
+ expect(events.at(-1)).toMatchObject({ through: 2100 });
+});
+
+it("reports progress through a window with no words", () => {
+ const events: TranscribeProgress[] = [];
+ emitWords((e) => events.push(e), "tiny", [], 30);
+ expect(events).toEqual([{ type: "words", model: "tiny", words: [], through: 30 }]);
+});
it("coalesces byte updates behind a slow reader while preserving phase records", async () => {
const lines: string[] = [];
diff --git a/packages/cli/src/whisper/progress.ts b/packages/cli/src/whisper/progress.ts
index 773668cc80..024e6359cd 100644
--- a/packages/cli/src/whisper/progress.ts
+++ b/packages/cli/src/whisper/progress.ts
@@ -1,6 +1,31 @@
import type { Writable } from "node:stream";
+import type { Word } from "./normalize.js";
import type { TranscribeProgress } from "./transcribe.js";
+const DESKTOP_MAX_LINE_BYTES = 16_000;
+
+export function emitWords(
+ onEvent: (event: TranscribeProgress) => void,
+ model: string,
+ words: Word[],
+ through: number,
+): void {
+ const empty = Buffer.byteLength(JSON.stringify({ type: "words", model, words: [], through })) + 1;
+ let chunk: Word[] = [];
+ let bytes = empty;
+ for (const word of words) {
+ const size = Buffer.byteLength(JSON.stringify(word)) + 1;
+ if (chunk.length > 0 && bytes + size > DESKTOP_MAX_LINE_BYTES) {
+ onEvent({ type: "words", model, words: chunk, through: chunk.at(-1)!.end });
+ chunk = [];
+ bytes = empty;
+ }
+ chunk.push(word);
+ bytes += size;
+ }
+ onEvent({ type: "words", model, words: chunk, through });
+}
+
export function createProgressWriter(stream: Writable): (event: TranscribeProgress) => void {
let blocked = false;
const pending: TranscribeProgress[] = [];
@@ -8,8 +33,10 @@ export function createProgressWriter(stream: Writable): (event: TranscribeProgre
if (blocked) {
const previous = pending.at(-1);
if (
+ event.type === "progress" &&
event.phase === "download" &&
- previous?.phase === "download" &&
+ previous?.type === "progress" &&
+ previous.phase === "download" &&
previous.model === event.model
) {
pending[pending.length - 1] = event;
diff --git a/packages/cli/src/whisper/sherpa.test.ts b/packages/cli/src/whisper/sherpa.test.ts
index b44efdf3b6..4f935ab457 100644
--- a/packages/cli/src/whisper/sherpa.test.ts
+++ b/packages/cli/src/whisper/sherpa.test.ts
@@ -226,8 +226,10 @@ module.exports = {
const result = JSON.parse(readFileSync(join(out, "transcript.json"), "utf-8"));
expect(result).toEqual([{ text: "hello", start: 0, end: 1 }]);
const event = { type: "progress", phase: "transcription", model: "parakeet-tdt-0.6b-v3" };
+ // The worker's one 1 s window streams its words before the final transcript.
expect(onEvent.mock.calls).toEqual([
- [{ ...event, status: "started" }],
+ [{ ...event, status: "started", durationSeconds: null }],
+ [{ type: "words", model: event.model, words: result, through: 1 }],
[{ ...event, status: "completed" }],
]);
expect(existsSync(join(root, "loaded-in-parent"))).toBe(false);
diff --git a/packages/cli/src/whisper/sherpa.ts b/packages/cli/src/whisper/sherpa.ts
index e1285da8b1..2d92cef784 100644
--- a/packages/cli/src/whisper/sherpa.ts
+++ b/packages/cli/src/whisper/sherpa.ts
@@ -3,6 +3,7 @@ import { createHash, randomUUID } from "node:crypto";
import { createReadStream, mkdirSync, renameSync, rmSync, statSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
+import { createInterface } from "node:readline";
import { fileURLToPath } from "node:url";
import { downloadToFile } from "../cloud/download.js";
import { stoppedByCancelSignal } from "../utils/renderCancellation.js";
@@ -20,10 +21,12 @@ import {
mergeWindowsToWords,
SHERPA_ERROR_PREFIX,
SHERPA_RESULT_PREFIX,
+ SHERPA_WINDOW_PREFIX,
PARAKEET_MODEL_LABEL,
writeParakeetTranscript,
type SherpaWindow,
} from "./parakeet.js";
+import { emitWords } from "./progress.js";
import {
getPreparedWavDurationSeconds,
prepareWav,
@@ -394,13 +397,14 @@ function decode(
wavPath: string,
runtimePath: string,
signal: AbortSignal,
+ onWindow?: (window: SherpaWindow, through: number) => void,
): Promise<SherpaWindow[]> {
const sourceMode = import.meta.url.endsWith(".ts");
const worker = new URL(sourceMode ? "./sherpaWorker.ts" : "./sherpaWorker.js", import.meta.url);
const args = [...(sourceMode ? ["--import", "tsx"] : []), fileURLToPath(worker)];
const input = { wavPath, runtimePath, config: recognizerConfig() };
return new Promise((resolve, reject) => {
- execFile(
+ const child = execFile(
process.execPath,
args,
{
@@ -419,6 +423,18 @@ function decode(
else reject(new Error(`Parakeet decoder ${failureReason(err, stderr)}`));
},
);
+ if (onWindow && child.stdout) {
+ createInterface({ input: child.stdout }).on("line", (l) => {
+ if (!l.startsWith(SHERPA_WINDOW_PREFIX)) return;
+ let streamed: { window: SherpaWindow; through: number };
+ try {
+ streamed = JSON.parse(l.slice(SHERPA_WINDOW_PREFIX.length));
+ } catch {
+ return;
+ }
+ onWindow(streamed.window, streamed.through);
+ });
+ }
});
}
@@ -455,6 +471,7 @@ export async function transcribeWithSherpa(
phase: "transcription",
model: PARAKEET_MODEL_LABEL,
status: "started",
+ durationSeconds: getPreparedWavDurationSeconds(wavPath),
});
if (options.signal.aborted) throw new DecodeCancelled("Transcription cancelled");
const selected = await selectRuntime(
@@ -468,7 +485,15 @@ export async function transcribeWithSherpa(
`Parakeet runtime does not load (${selected.error}). Run hyperframes models install parakeet to repair it, or use --engine whisper.`,
);
}
- const windows = await decode(wavPath, selected.path, options.signal);
+ const onEvent = options.onEvent;
+ const windows = await decode(
+ wavPath,
+ selected.path,
+ options.signal,
+ onEvent &&
+ ((window, through) =>
+ emitWords(onEvent, PARAKEET_MODEL_LABEL, mergeWindowsToWords([window]), through)),
+ );
const result = writeParakeetTranscript(dir, mergeWindowsToWords(windows));
options.onEvent?.({
type: "progress",
diff --git a/packages/cli/src/whisper/sherpaWorker.test.ts b/packages/cli/src/whisper/sherpaWorker.test.ts
index 18e19756dc..a8e6eebce7 100644
--- a/packages/cli/src/whisper/sherpaWorker.test.ts
+++ b/packages/cli/src/whisper/sherpaWorker.test.ts
@@ -4,7 +4,7 @@ import { tmpdir } from "node:os";
import { join } from "node:path";
import { fileURLToPath } from "node:url";
import { afterEach, describe, expect, it } from "vitest";
-import { SHERPA_ERROR_PREFIX, SHERPA_RESULT_PREFIX } from "./parakeet.js";
+import { SHERPA_ERROR_PREFIX, SHERPA_RESULT_PREFIX, SHERPA_WINDOW_PREFIX } from "./parakeet.js";
const WORKER = fileURLToPath(new URL("./sherpaWorker.ts", import.meta.url));
@@ -82,6 +82,15 @@ describe("sherpaWorker", () => {
]);
});
+ it("prints each window as it is decoded, with the audio seconds done", async () => {
+ const { stdout } = await runWorker(fakeRuntime(), "speech.wav");
+ const streamed = stdout
+ .split("\n")
+ .filter((l) => l.startsWith(SHERPA_WINDOW_PREFIX))
+ .map((l) => JSON.parse(l.slice(SHERPA_WINDOW_PREFIX.length)));
+ expect(streamed).toEqual([{ window: windowsOf(stdout)[0], through: 3 }]);
+ });
+
it("re-decodes the window with leading silence when the gap alone gives nothing", async () => {
const { code, stdout } = await runWorker(fakeRuntime(), "hum.wav");
expect(code).toBe(0);
diff --git a/packages/cli/src/whisper/sherpaWorker.ts b/packages/cli/src/whisper/sherpaWorker.ts
index 0764825c9d..a5b96368e9 100644
--- a/packages/cli/src/whisper/sherpaWorker.ts
+++ b/packages/cli/src/whisper/sherpaWorker.ts
@@ -5,6 +5,7 @@ import {
spliceGap,
SHERPA_ERROR_PREFIX,
SHERPA_RESULT_PREFIX,
+ SHERPA_WINDOW_PREFIX,
type SherpaWindow,
} from "./parakeet.js";
@@ -77,7 +78,10 @@ try {
const retry = decodeWindow(recognizer, slice, RETRY_PAD_SECONDS);
if (retry.tokens.length > decoded.tokens.length) decoded = retry;
}
- windows.push({ offset: cuts[k]! / wave.sampleRate, ...decoded });
+ const window = { offset: cuts[k]! / wave.sampleRate, ...decoded };
+ windows.push(window);
+ const through = cuts[k + 1]! / wave.sampleRate;
+ process.stdout.write(`${SHERPA_WINDOW_PREFIX}${JSON.stringify({ window, through })}\n`);
}
process.stdout.write(`${SHERPA_RESULT_PREFIX}${JSON.stringify(windows)}\n`);
} catch (err) {
diff --git a/packages/cli/src/whisper/transcribe.metadata.test.ts b/packages/cli/src/whisper/transcribe.metadata.test.ts
index 3e84afd507..1317129b95 100644
--- a/packages/cli/src/whisper/transcribe.metadata.test.ts
+++ b/packages/cli/src/whisper/transcribe.metadata.test.ts
@@ -2,10 +2,41 @@ import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, beforeEach, expect, it, vi } from "vitest";
-import { transcribe } from "./transcribe.js";
+import { transcribe, type TranscribeProgress } from "./transcribe.js";
-const native = vi.hoisted(() => ({ exec: vi.fn(), missingLanguage: false, runtime: vi.fn() }));
-vi.mock("node:child_process", () => ({ execFileSync: native.exec }));
+const native = vi.hoisted(() => ({
+ exec: vi.fn(),
+ missingLanguage: false,
+ runtime: vi.fn(),
+ printed: { stdout: "", stderr: "" },
+}));
+vi.mock("node:child_process", async () => {
+ const { PassThrough } = await import("node:stream");
+ return {
+ execFileSync: native.exec,
+ // whisper-cli: runs the same stand-in, then prints what the test set, as the real one does while it decodes.
+ execFile: (
+ command: string,
+ args: string[],
+ _options: unknown,
+ done: (err: unknown, stdout: string, stderr: string) => void,
+ ) => {
+ const child = { stdout: new PassThrough(), stderr: new PassThrough() };
+ setImmediate(() => {
+ let failure: unknown = null;
+ try {
+ native.exec(command, args);
+ } catch (err) {
+ failure = err;
+ }
+ child.stdout.end(native.printed.stdout);
+ child.stderr.end(native.printed.stderr);
+ done(failure, native.printed.stdout, native.printed.stderr);
+ });
+ return child;
+ },
+ };
+});
vi.mock("./manager.js", () => ({
DEFAULT_MODEL: "small.en",
ensureWhisper: native.runtime,
@@ -28,6 +59,7 @@ beforeEach(() => {
dir = mkdtempSync(join(tmpdir(), "hf-language-"));
writeFileSync(join(dir, "audio.wav"), Buffer.alloc(44));
native.missingLanguage = false;
+ native.printed = { stdout: "", stderr: "" };
native.runtime.mockReset().mockResolvedValue({ executablePath: "whisper-cli", source: "env" });
native.exec.mockReset().mockImplementation((command: string, args: string[]) => {
if (command === "ffprobe")
@@ -87,7 +119,13 @@ it("reports download bytes and truthful transcription boundaries", async () => {
});
expect(events).toEqual([
{ type: "progress", phase: "download", model: "small", receivedBytes: 5, totalBytes: null },
- { type: "progress", phase: "transcription", model: "small", status: "started" },
+ {
+ type: "progress",
+ phase: "transcription",
+ model: "small",
+ status: "started",
+ durationSeconds: 44 / 32_000,
+ },
{ type: "progress", phase: "transcription", model: "small", status: "completed" },
]);
});
@@ -122,6 +160,109 @@ it("does not claim transcription completed when decoding fails", async () => {
).rejects.toThrow("decoder failed");
expect(events).toEqual([
{ type: "progress", phase: "download", model: "small", receivedBytes: 5, totalBytes: null },
- { type: "progress", phase: "transcription", model: "small", status: "started" },
+ {
+ type: "progress",
+ phase: "transcription",
+ model: "small",
+ status: "started",
+ durationSeconds: 44 / 32_000,
+ },
]);
});
+
+async function transcribeStreaming() {
+ const events: TranscribeProgress[] = [];
+ const result = await transcribe(join(dir, "audio.wav"), dir, {
+ model: "small",
+ onEvent: (event) => events.push(event),
+ });
+ return { events, words: events.filter((e) => e.type === "words"), result };
+}
+
+it("streams the words of each segment whisper prints, before the final transcript", async () => {
+ native.printed.stdout =
+ "\n[00:00:00.000 --> 00:00:02.000] Hello big world\n" +
+ "[00:00:02.000 --> 00:00:04.000] [BLANK_AUDIO]\n";
+ const { events, words, result } = await transcribeStreaming();
+ expect(words).toEqual([
+ {
+ type: "words",
+ model: "small",
+ words: [
+ { text: "Hello", start: 0, end: 0.769 },
+ { text: "big", start: 0.769, end: 1.231 },
+ { text: "world", start: 1.231, end: 2 },
+ ],
+ through: 2,
+ },
+ { type: "words", model: "small", words: [], through: 4 },
+ ]);
+ expect(events.at(-1)).toMatchObject({ status: "completed" });
+ expect(result).toMatchObject({ wordCount: 1, durationSeconds: 1 });
+});
+
+it("reports progress through audio where whisper prints no segment, once per step", async () => {
+ writeFileSync(join(dir, "audio.wav"), Buffer.alloc(4 * 32_000));
+ native.printed.stderr =
+ "whisper_print_progress_callback: progress = 25%\n" +
+ "whisper_print_progress_callback: progress = 25%\n" +
+ "whisper_print_progress_callback: progress = 100%\n";
+ expect((await transcribeStreaming()).words).toEqual([
+ { type: "words", model: "small", words: [], through: 1 },
+ { type: "words", model: "small", words: [], through: 4 },
+ ]);
+});
+
+it("asks whisper for progress only when someone streams it", async () => {
+ const progressAsked = () =>
+ native.exec.mock.calls
+ .filter(([c]) => c === "whisper-cli")
+ .map(([, a]) => a.includes("--print-progress"));
+ await transcribe(join(dir, "audio.wav"), dir, { model: "small" });
+ await transcribeStreaming();
+ expect(progressAsked()).toEqual([false, true]);
+});
+
+it("installs the stop handling only once setup is done and whisper starts", async () => {
+ const order: string[] = [];
+ native.runtime.mockImplementation(async () => {
+ order.push("runtime");
+ return { executablePath: "whisper-cli", source: "env" };
+ });
+ await transcribe(join(dir, "audio.wav"), dir, {
+ model: "small",
+ onEvent: (e) => e.type === "progress" && e.phase === "download" && order.push("download"),
+ startCancellation: () => {
+ order.push("stop handling");
+ return new AbortController().signal;
+ },
+ });
+ expect(order).toEqual(["runtime", "download", "stop handling"]);
+});
+
+it("keeps whisper's log out of the error message, leaving its last lines to the command", async () => {
+ const previous = native.exec.getMockImplementation()!;
+ native.exec.mockImplementation((command: string, args: string[]) => {
+ if (command === "whisper-cli")
+ throw new Error("Command failed: whisper-cli\nload log\nbad model");
+ return previous(command, args);
+ });
+ native.printed.stderr = "load log\nbad model\n";
+ const failure = await transcribe(join(dir, "audio.wav"), dir, { model: "small" }).catch((e) => e);
+ expect(failure).toMatchObject({
+ message: "Command failed: whisper-cli",
+ stderr: "load log\nbad model\n",
+ });
+});
+
+it("names the timeout knob when whisper outlives its own timeout", async () => {
+ const previous = native.exec.getMockImplementation()!;
+ native.exec.mockImplementation((command: string, args: string[]) => {
+ if (command === "whisper-cli")
+ throw Object.assign(new Error("killed"), { killed: true, signal: "SIGTERM" });
+ return previous(command, args);
+ });
+ await expect(transcribe(join(dir, "audio.wav"), dir, { model: "small" })).rejects.toThrow(
+ "Whisper transcription exceeded",
+ );
+});
diff --git a/packages/cli/src/whisper/transcribe.ts b/packages/cli/src/whisper/transcribe.ts
index a69992d334..5f590d5f6e 100644
--- a/packages/cli/src/whisper/transcribe.ts
+++ b/packages/cli/src/whisper/transcribe.ts
@@ -1,5 +1,8 @@
// fallow-ignore-file complexity
-import { execFileSync } from "node:child_process";
+import { execFile, execFileSync } from "node:child_process";
+import { once } from "node:events";
+import { createInterface } from "node:readline";
+import type { Readable } from "node:stream";
import { existsSync, readFileSync, mkdirSync, rmSync, statSync, unlinkSync } from "node:fs";
import { join, extname } from "node:path";
import { tmpdir } from "node:os";
@@ -7,6 +10,8 @@ import { randomUUID } from "node:crypto";
import { findFFmpeg, findFFprobe, getFFmpegInstallHint } from "../browser/ffmpeg.js";
import { stoppedByCancelSignal } from "../utils/renderCancellation.js";
import { ensureWhisper, ensureModel, hasFFmpeg, DEFAULT_MODEL } from "./manager.js";
+import type { Word } from "./normalize.js";
+import { emitWords } from "./progress.js";
function findWavDataChunk(buf: Buffer): { offset: number; size: number } | null {
if (buf.length < 12) return null;
@@ -248,7 +253,15 @@ export type TranscribeProgress =
receivedBytes: number;
totalBytes: number | null;
}
- | { type: "progress"; phase: "transcription"; model: string; status: "started" | "completed" };
+ | {
+ type: "progress";
+ phase: "transcription";
+ model: string;
+ status: "started" | "completed";
+ durationSeconds?: number | null;
+ }
+ /** Words heard so far, before the final transcript replaces them; `through` is audio seconds done. */
+ | { type: "words"; model: string; words: Word[]; through: number };
export interface TranscribeOptions {
installRuntime?: boolean;
@@ -256,6 +269,8 @@ export interface TranscribeOptions {
language?: string;
onProgress?: (message: string) => void;
onEvent?: (event: TranscribeProgress) => void;
+ /** Called as whisper starts, so a stop during install or download still ends the CLI at once. */
+ startCancellation?: () => AbortSignal;
/**
* Explicit whisper spawn timeout in ms. Overrides the duration+model auto-
* scaled default. Callers that leave this undefined get the auto-scaled
@@ -472,7 +487,14 @@ export async function transcribe(
const automaticLanguage = options?.language === undefined && !model.endsWith(".en");
const language = options?.language ?? (automaticLanguage ? "auto" : "en");
options?.onProgress?.("Transcribing...");
- options?.onEvent?.({ type: "progress", phase: "transcription", model, status: "started" });
+ const wavSeconds = getPreparedWavDurationSeconds(wavPath);
+ options?.onEvent?.({
+ type: "progress",
+ phase: "transcription",
+ model,
+ status: "started",
+ durationSeconds: wavSeconds,
+ });
const outputBase = join(outputDir, "transcript");
mkdirSync(outputDir, { recursive: true });
@@ -487,16 +509,37 @@ export async function transcribe(
"--suppress-nst",
];
whisperArgs.push("--language", language);
+ const onEvent = options?.onEvent;
+ if (onEvent) whisperArgs.push("--print-progress");
whisperArgs.push(wavPath);
- const whisperTimeoutMs = resolveWhisperTimeoutMs(getPreparedWavDurationSeconds(wavPath), {
+ const whisperTimeoutMs = resolveWhisperTimeoutMs(wavSeconds, {
model,
overrideMs: options?.timeoutMs,
});
+ let through = 0;
+ const heard = (words: Word[], at: number) => {
+ if (!onEvent || (words.length === 0 && at <= through)) return;
+ through = Math.max(through, at);
+ emitWords(onEvent, model, words, through);
+ };
try {
- execFileSync(whisper.executablePath, whisperArgs, {
- stdio: "ignore",
- timeout: whisperTimeoutMs,
+ await runWhisper(whisper.executablePath, whisperArgs, {
+ timeoutMs: whisperTimeoutMs,
+ signal: options?.startCancellation?.(),
+ onStdout:
+ onEvent &&
+ ((line) => {
+ const segment = segmentWords(line);
+ if (segment) heard(segment.words, segment.end);
+ }),
+ onStderr:
+ onEvent && wavSeconds
+ ? (line) => {
+ const percent = /progress =\s*(\d+)%/.exec(line)?.[1];
+ if (percent) heard([], (Number(percent) / 100) * wavSeconds);
+ }
+ : undefined,
});
} catch (err) {
// Surface the timeout knob when the child was killed by our own timeout —
@@ -558,6 +601,65 @@ export async function transcribe(
};
}
+const SEGMENT_LINE = /^\[(\d+):(\d+):([\d.]+) --> (\d+):(\d+):([\d.]+)\]\s*(.*)$/;
+const toSeconds = (h: string, m: string, s: string) =>
+ Number(h) * 3600 + Number(m) * 60 + Number(s);
+const toMs = (seconds: number) => Math.round(seconds * 1000) / 1000;
+
+/** A segment line whisper-cli prints as it decodes; word times are spread by length until the JSON's. */
+function segmentWords(line: string): { words: Word[]; end: number } | null {
+ const m = SEGMENT_LINE.exec(line);
+ if (!m) return null;
+ const start = toSeconds(m[1]!, m[2]!, m[3]!);
+ const end = toSeconds(m[4]!, m[5]!, m[6]!);
+ const texts = m[7]!
+ .split(/\s+/)
+ .filter((t) => t && !t.startsWith("[_") && !t.startsWith("[BLANK"));
+ const letters = texts.reduce((n, t) => n + t.length, 0);
+ let at = start;
+ const words = texts.map((text) => {
+ const from = at;
+ at += ((end - start) * text.length) / letters;
+ return { text, start: toMs(from), end: toMs(at) };
+ });
+ return { words, end };
+}
+
+/** Resolves once whisper exits and both its streams are read, so no printed line is lost. */
+async function runWhisper(
+ executable: string,
+ args: string[],
+ options: {
+ timeoutMs: number;
+ signal?: AbortSignal;
+ onStdout?: (line: string) => void;
+ onStderr?: (line: string) => void;
+ },
+): Promise<void> {
+ let stdout: Readable | null = null;
+ let stderr: Readable | null = null;
+ const exited = new Promise<void>((resolve, reject) => {
+ const child = execFile(
+ executable,
+ args,
+ { timeout: options.timeoutMs, signal: options.signal, maxBuffer: 256 * 1024 * 1024 },
+ (err, _out, errText) => {
+ if (!err) return resolve();
+ // execFileSync named its own timeout ETIMEDOUT; execFile only marks the child killed.
+ const timedOut = err.killed && err.signal === "SIGTERM" && !options.signal?.aborted;
+ // execFile appends all of stderr to the message; the command shows its last lines instead.
+ err.message = err.message.split("\n")[0]!;
+ reject(Object.assign(err, { stderr: errText }, timedOut ? { code: "ETIMEDOUT" } : {}));
+ },
+ );
+ stdout = child.stdout;
+ stderr = child.stderr;
+ });
+ const read = (stream: Readable | null, onLine?: (line: string) => void) =>
+ stream && onLine ? once(createInterface({ input: stream }).on("line", onLine), "close") : null;
+ await Promise.all([exited, read(stdout, options.onStdout), read(stderr, options.onStderr)]);
+}
+
// ---------------------------------------------------------------------------
// Timeout error discoverability
// ---------------------------------------------------------------------------