Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
fix(cli): report transcription language and progress (#5103)
Miguel Ángel1db44c659565
diff --git a/docs/contracts/2026-10-05-transcribe-language-progress.html b/docs/contracts/2026-10-05-transcribe-language-progress.htmlnew file mode 100644index 0000000000..27caf59991--- /dev/null+++ b/docs/contracts/2026-10-05-transcribe-language-progress.html@@ -0,0 +1,66 @@+<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Transcription language and progress contract</title><style>+:root{color-scheme:light dark;+ --bg:#fbfbfa;--card:#ffffff;--line:#e6e4df;--ink:#1c1c1a;--dim:#6b6b66;--faint:#9a9a94;+ --go:#178a5a;--go-bg:#e8f6ee;+ --warn:#a6690a;--warn-bg:#fbf1dc;--bad:#c0392b;--bad-bg:#fbe7e4;--info:#2a5db0;--info-bg:#e8eefb;+ --mono:ui-monospace,SFMono-Regular,Menlo,monospace;--sans:-apple-system,BlinkMacSystemFont,"Segoe UI",Inter,sans-serif}+@media (prefers-color-scheme:dark){:root{--bg:#111213;--card:#191b1d;--line:#2a2d31;--ink:#ecebe8;--dim:#a2a29c;--faint:#6f6f6a;+ --go:#5fd39a;--go-bg:#12291f;--warn:#e6b35a;--warn-bg:#2b2311;+ --bad:#ff7b6b;--bad-bg:#2d1714;--info:#7fa9ff;--info-bg:#15203a}}+*{box-sizing:border-box}+body{margin:0;background:var(--bg);color:var(--ink);font:16px/1.55 var(--sans)}+.wrap{max-width:900px;margin:0 auto;padding:56px 24px 96px}+header h1{font-size:30px;line-height:1.15;letter-spacing:-.4px;margin:0 0 10px}+header .what{font-size:18px;color:var(--dim);margin:0 0 18px;max-width:70ch}+.strip{display:flex;gap:10px;flex-wrap:wrap;align-items:center;font:13px var(--mono);color:var(--faint)}+.strip .sep{opacity:.5}+.pill{display:inline-flex;align-items:center;gap:6px;font:600 12px/1 var(--mono);padding:6px 10px;border-radius:999px;white-space:nowrap}+.pill.go{color:var(--go);background:var(--go-bg)}.pill.warn{color:var(--warn);background:var(--warn-bg)}+.pill.bad{color:var(--bad);background:var(--bad-bg)}.pill.info{color:var(--info);background:var(--info-bg)}+.pill b{font-size:13px}+section{margin-top:56px}+h2{font-size:22px;letter-spacing:-.3px;margin:0 0 6px}+.sub{color:var(--dim);margin:0 0 18px;font-size:15px}+.card{background:var(--card);border:1px solid var(--line);border-radius:14px;padding:20px 22px;margin:14px 0}+.breath{border-left:4px solid var(--go);font-size:18px;line-height:1.5}+.breath b{color:var(--go)}+.plain{color:var(--dim);font-size:15px;margin:0 0 10px}+.plain::before{content:"In plain words ";font:600 11px var(--mono);letter-spacing:1px;color:var(--faint);text-transform:uppercase}+pre{background:var(--bg);border:1px solid var(--line);border-radius:10px;padding:14px 16px;overflow:auto;font:13px/1.55 var(--mono);margin:10px 0}+code{font:13px var(--mono);background:var(--bg);border:1px solid var(--line);border-radius:5px;padding:1px 6px}+.cite{font:12px var(--mono);color:var(--faint);margin-top:8px;display:block}+.states{display:flex;gap:8px;margin:12px 0 4px;flex-wrap:wrap}+table{width:100%;border-collapse:collapse;margin:10px 0;font-size:14.5px}+th{text-align:left;font:600 11px/1.4 var(--mono);text-transform:uppercase;letter-spacing:.7px;color:var(--faint);border-bottom:1px solid var(--line);padding:8px 10px}+td{padding:10px;border-bottom:1px solid var(--line);vertical-align:top}+tr:last-child td{border-bottom:0}+td.k{font:13px var(--mono);white-space:nowrap}+.decision{border-left:4px solid var(--info)}+.decision h3{margin:0 0 8px;font-size:17px}+.decision .ask{color:var(--info);font-weight:600}+blockquote{margin:12px 0;padding:8px 0 8px 16px;border-left:2px solid var(--line);color:var(--dim);font-style:italic;font-size:14.5px}+blockquote .src{display:block;font-style:normal;font:12px var(--mono);color:var(--faint);margin-top:6px}+ul,ol{padding-left:22px}li{margin:6px 0}+.mermaid{background:var(--card);border:1px solid var(--line);border-radius:14px;padding:18px;margin:14px 0;overflow:auto}+.mermaid svg{max-width:100%}+footer{margin-top:72px;padding-top:16px;border-top:1px solid var(--line);font:12px/1.7 var(--mono);color:var(--faint)}+</style></head><body><main class="wrap"><header><h1>Transcription language and progress</h1><p class="what">Carry automatic language detection in the JSON result and emit progress separately so stdout stays parseable.</p><div class="strip">2026-10-05 · hyperframes @ d69eac0cb · 4 boundaries audited · native execution not exercised · decisions approved</div></header>+<section><div class="card breath"><b>In one breath.</b> stdout is one result, stderr carries typed progress records plus diagnostics, and detectedLanguage reports inference rather than a requested language.</div></section>+<section><h2>Where the value travels</h2><pre>Whisper JSON result.language → transcription result → CLI stdout → JSON consumer+HTTP response bytes → download pipeline → model callback → CLI stderr → progress consumer+Whisper words → normalization → transcript.json (word array, unchanged)</pre></section>+<section><h2>The contract, per boundary</h2>+<div class="card"><h3>Language</h3><p class="plain">The native result identifies the language used to decode. Only automatic selection qualifies as detection.</p><pre>result.language: string+Proposed terminal addition: detectedLanguage: string | null</pre><p>Upstream JSON writes result.language from whisper_full_lang_id. Explicit language also sets that state. Existing detection incorrectly searches stdout although the native logger writes stderr; missing detection then omits --language and falls back to native English default.</p><span class="cite">whisper.cpp 60c0be6ac: examples/cli/cli.cpp:84,735-736; src/whisper.cpp:6993-7013,7151-7153,9357-9366. CLI: whisper/transcribe.ts:17-23,466-504,534,560.</span><div class="states"><span class="pill go">exists: native JSON</span><span class="pill bad">reachable: dropped by wrapper</span><span class="pill bad">written: no terminal field</span></div></div>+<div class="card"><h3>Result and artifact</h3><p class="plain">Add metadata to the terminal result and preserve the existing word-array file.</p><pre>{ok:true, engine, model, wordCount, durationSeconds,+ speechOnsetSeconds, transcriptPath, detectedLanguage}</pre><p>The existing model field currently reports the requested model even when the wrapper selects a multilingual variant. The wrapper will own the resolved model and return it with the result.</p><span class="cite">commands/transcribe.ts:397 writes Word[]; :400-410 emits stdout. Existing file consumer: commands/transcribe.ts:384 calls loadTranscript. External new-field consumption remains unverified.</span><div class="states"><span class="pill go">exists: result and words</span><span class="pill go">reachable: stdout and file</span><span class="pill warn">read: additions pending</span></div></div>+<div class="card"><h3>Download progress</h3><p class="plain">Count bytes in the existing transfer pipeline. Unknown size stays unknown.</p><pre>{"type":"progress","phase":"download","model":"small",+ "receivedBytes":65536,"totalBytes":null}</pre><p>DownloadOptions currently has timeoutMs and maxBytes only. Add a byte callback at the transfer owner, thread it through ensureModel, and serialize it only at the command boundary. Cache hits emit no download events. A known total is bytes, never an invented percentage.</p><span class="cite">utils/download.ts:10-15,113-122; whisper/manager.ts:215-223; commands/transcribe.ts:341,347-354.</span><div class="states"><span class="pill bad">exists: callback absent</span><span class="pill bad">reachable: JSON disables callbacks</span><span class="pill bad">written: no progress records</span></div></div>+<div class="card"><h3>Transcription progress</h3><p class="plain">Indicate work started and completed without inventing numerical progress.</p><pre>{"type":"progress","phase":"transcription","model":"small",+ "status":"started"}+{"type":"progress","phase":"transcription","model":"small",+ "status":"completed"}</pre><p>Progress records are individual valid JSON lines on stderr. Other stderr diagnostics remain allowed. The terminal stdout result is emitted once. Failure never emits a completed transcription event.</p><span class="cite">whisper/transcribe.ts:488,512-515; whisper/parakeet.ts:294-304; whisper/sherpa.ts:397-413,445. Plain fallback diagnostics: commands/transcribe.ts:370.</span><div class="states"><span class="pill warn">exists: text callbacks</span><span class="pill bad">reachable: JSON disabled</span><span class="pill bad">written: no typed records</span></div></div></section>+<section><h2>How it says no</h2><table><tr><th>Signal</th><th>Meaning and response</th></tr><tr><td>detectedLanguage:null</td><td>No actual automatic inference was reported, including explicit language, English-only model, or an engine without detection. Never infer language from a model label.</td></tr><tr><td>totalBytes:null</td><td>Response has no trustworthy size. Show bytes or indeterminate progress.</td></tr><tr><td>ok:false / nonzero exit</td><td>Operation failed. Diagnostic stderr may explain why. No completion event is evidence of success without the terminal result.</td></tr><tr><td>Progress line without type</td><td>Not part of this progress contract. Consumers filter diagnostics separately.</td></tr></table></section>+<section><h2>Decisions approved</h2><ol><li>detectedLanguage means real automatic detection. Explicit --language and English-only models return null.</li><li>stderr permits diagnostics alongside progress; every progress line is valid JSON with type.</li><li>model reports the actual resolved model. The file stays Word[].</li><li>Transcription progress is phase-only. Download progress reports real bytes with a nullable total.</li><li>--no-runtime-install requires an existing Whisper runtime on all paths, including auto fallback. Model downloads remain allowed. No prior opt-out exists in the inspected CLI source; ensureWhisper owns this policy.</li></ol></section>+<section><h2>Coverage, honestly</h2><p><b>Audited:</b> CLI producer, transfer pipeline, native JSON writer and logger, current terminal/file paths. Installed CLI help executed.</p><p><b>Trusting:</b> arbitrary environment-selected Whisper versions are not pinned to the inspected upstream checkout.</p><p><b>Not exercised:</b> native audio inference, new progress writer and external live consumer. These are contract findings, not execution proof.</p></section>+<section><h2>What would prove this page wrong</h2><ul><li>A public transcribe invocation with a native fixture that emits detection only on stderr must decode automatically and return its language.</li><li>Explicit language and English-only models must return null even if native JSON reports a language.</li><li>Download callbacks must observe actual chunks, including unknown totals, and stdout must parse as one result while stderr records parse independently.</li><li>A switched multilingual model must be the model reported in the final result.</li></ul></section></main></body></html>\ No newline at end of filediff --git a/packages/cli/src/commands/transcribe.test.ts b/packages/cli/src/commands/transcribe.test.tsindex 307765cf00..e572d1c175 100644--- a/packages/cli/src/commands/transcribe.test.ts+++ b/packages/cli/src/commands/transcribe.test.ts@@ -1,3 +1,4 @@+import { runCommand } from "citty";import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";import { chmodSync, existsSync, writeFileSync, readFileSync, mkdtempSync, rmSync } from "node:fs";import { join } from "node:path";@@ -44,7 +45,14 @@ import transcribeCmd from "./transcribe.js";function fakeTranscript(dir: string, text: string) {const transcriptPath = join(dir, "transcript.json");writeFileSync(transcriptPath, JSON.stringify([{ text, start: 0, end: 1 }]));- return { transcriptPath, wordCount: 1, durationSeconds: 1, speechOnsetSeconds: null };+ return {+ model: text === "whisper" ? "small.en" : "parakeet-tdt-0.6b-v3",+ detectedLanguage: null,+ transcriptPath,+ wordCount: 1,+ durationSeconds: 1,+ speechOnsetSeconds: null,+ };}function lastJson(): Record<string, unknown> {@@ -81,6 +89,47 @@ describe("transcribe command", () => {vi.unstubAllEnvs();});+ it("keeps typed progress on stderr and reports resolved metadata in one stdout result", async () => {+ const { dir, input } = dummyAudio();+ dirs.push(dir);+ const stderr = vi.spyOn(process.stderr, "write").mockImplementation(() => true);+ transcribeMock.mockImplementation(async (_input, outputDir, options) => {+ options.onEvent?.({+ type: "progress",+ phase: "download",+ model: "small",+ receivedBytes: 5,+ totalBytes: null,+ });+ options.onEvent?.({+ type: "progress",+ phase: "transcription",+ model: "small",+ status: "started",+ });+ options.onEvent?.({+ type: "progress",+ phase: "transcription",+ model: "small",+ status: "completed",+ });+ return { ...fakeTranscript(outputDir, "hola"), model: "small", detectedLanguage: "es" };+ });+ await transcribeCmd.run!({+ args: { input, dir, json: true, engine: "whisper", model: "small.en" },+ } as never);+ expect(console.log).toHaveBeenCalledTimes(1);+ expect(lastJson()).toMatchObject({ ok: true, model: "small", detectedLanguage: "es" });+ expect(stderr.mock.calls.map(([line]) => JSON.parse(String(line)))).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: "completed" },+ ]);+ expect(JSON.parse(readFileSync(join(dir, "transcript.json"), "utf8"))).toEqual([+ { id: "w0", text: "hola", start: 0, end: 1 },+ ]);+ });+it("explicit run exits non-zero and is NOT reported as a command failure", async () => {const { dir, input } = dummyAudio();dirs.push(dir);@@ -252,6 +301,20 @@ describe("transcribe command", () => {return { exitCode: exitCode || consumeCommandResult().exitCode, out: lastJson() };}+ it.each(["whisper", "auto"])(+ "--no-runtime-install reaches %s including the fallback",+ async (engine) => {+ crashChild("SIGABRT");+ Object.assign(runners, { sherpa: true, mlx: false });+ const { dir, input } = dummyAudio();+ dirs.push(dir);+ await runCommand(transcribeCmd, {+ rawArgs: [input, "--engine", engine, "--json", "--no-runtime-install"],+ });+ expect(transcribeMock.mock.calls.at(-1)?.[2]).toMatchObject({ installRuntime: false });+ },+ );+it("auto falls back to whisper with one line naming the Parakeet error and the repair", async () => {crashChild("SIGABRT", "terminate called after throwing an instance of 'Ort::Exception'\n");expect(await transcribeWith("auto", { sherpa: true, mlx: false })).toMatchObject({diff --git a/packages/cli/src/commands/transcribe.ts b/packages/cli/src/commands/transcribe.tsindex 2ef336a48a..cd278d7c07 100644--- a/packages/cli/src/commands/transcribe.ts+++ b/packages/cli/src/commands/transcribe.ts@@ -1,3 +1,4 @@+import { createProgressWriter } from "../whisper/progress.js";import { failCommand, setCommandExitCode } from "../utils/commandResult.js";import { normalizeErrorMessage } from "../utils/errorMessage.js";// fallow-ignore-file code-duplication@@ -7,7 +8,6 @@ import { existsSync, rmSync, writeFileSync } from "node:fs";import {findParakeet,PARAKEET_LANGUAGES,- PARAKEET_MODEL_LABEL,parakeetSpeaks,transcribeWithParakeet,} from "../whisper/parakeet.js";@@ -77,7 +77,7 @@ export default defineCommand({},json: {type: "boolean",- description: "Output result as JSON",+ description: "Output result as JSON; progress JSON lines go to stderr",default: false,},to: {@@ -95,6 +95,12 @@ export default defineCommand({"Keep each transcript entry as its own caption cue (skip word-level grouping). Use when exporting an already-cued transcript whose entries have no internal spaces, e.g. single-word or CJK captions.",default: false,},+ "runtime-install": {+ type: "boolean",+ default: true,+ description:+ "Allow installing the Whisper runtime. Use --no-runtime-install to require an existing runtime; model downloads remain allowed.",+ },optional: {type: "boolean",description:@@ -153,6 +159,7 @@ export default defineCommand({language: args.language,json: args.json,optional: args.optional,+ installRuntime: args["runtime-install"],timeoutMs,});},@@ -294,6 +301,7 @@ async function transcribeAudio(language?: string;json?: boolean;optional?: boolean;+ installRuntime?: boolean;timeoutMs?: number;},): Promise<void> {@@ -339,20 +347,39 @@ async function transcribeAudio(const spin = opts.json ? null : clack.spinner();spin?.start(`Transcribing with ${label(runner)}...`);const onProgress = spin ? (msg: string) => spin.message(msg) : undefined;+ 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;- const run = (r: Runner) =>- r === "sherpa"- ? transcribeWithSherpa(wavPath, dir, { onProgress, signal: cancellation!.signal })- : r === "parakeet-mlx"- ? transcribeWithParakeet(wavPath, dir, { language: opts.language, onProgress })- : transcribe(wavPath, dir, {- model,- language: opts.language,- onProgress,- timeoutMs: opts.timeoutMs,- });+ const run = (r: Runner) => {+ switch (r) {+ case "sherpa":+ return transcribeWithSherpa(wavPath, dir, {+ onProgress,+ onEvent,+ signal: cancellation!.signal,+ });+ case "parakeet-mlx":+ return transcribeWithParakeet(wavPath, dir, {+ language: opts.language,+ onProgress,+ onEvent,+ });+ case "whisper":+ return transcribe(wavPath, dir, {+ model,+ language: opts.language,+ onProgress,+ onEvent,+ timeoutMs: opts.timeoutMs,+ installRuntime: opts.installRuntime,+ });+ default: {+ const unreachable: never = r;+ throw new Error(`Unknown transcription runner: ${unreachable}`);+ }+ }+ };try {// Outside the fallback: an unreadable input is not a Parakeet failure. The fallback reuses it.@@ -402,7 +429,8 @@ async function transcribeAudio(JSON.stringify({ok: true,engine: runner === "whisper" ? "whisper" : "parakeet",- model: runner === "whisper" ? model : PARAKEET_MODEL_LABEL,+ model: result.model,+ detectedLanguage: result.detectedLanguage,wordCount: words.length,durationSeconds: result.durationSeconds,speechOnsetSeconds: result.speechOnsetSeconds,diff --git a/packages/cli/src/utils/download.test.ts b/packages/cli/src/utils/download.test.tsindex 3e8b362ce5..adf0753ffd 100644--- a/packages/cli/src/utils/download.test.ts+++ b/packages/cli/src/utils/download.test.ts@@ -1,3 +1,5 @@+import { randomUUID } from "node:crypto";+import { ensureModel } from "../whisper/manager.js";import { EventEmitter } from "node:events";import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs";import { tmpdir } from "node:os";@@ -50,6 +52,46 @@ afterEach(() => {});describe("downloadFile", () => {+ it("carries model download progress through the real pipeline and stays quiet on cache hits", async () => {+ mockGet.mockImplementation(httpsResponse(200, { "content-length": "5" }, "hello"));+ const events: unknown[] = [];+ const model = `test-${randomUUID()}`;+ const options = {+ onDownloadProgress: (receivedBytes: number, totalBytes: number | null) =>+ events.push({ receivedBytes, totalBytes }),+ };+ const modelPath = await ensureModel(model, options);+ try {+ expect(readFileSync(modelPath, "utf8")).toBe("hello");+ expect(events).toEqual([+ { receivedBytes: 0, totalBytes: 5 },+ { receivedBytes: 5, totalBytes: 5 },+ ]);+ events.length = 0;+ expect(await ensureModel(model, options)).toBe(modelPath);+ expect(events).toEqual([]);+ expect(mockGet).toHaveBeenCalledTimes(1);+ } finally {+ rmSync(modelPath);+ }+ });++ it.each([+ [{ "content-length": "5" }, 5],+ [{}, null],+ [{ "content-length": "invalid" }, null],+ ])("reports actual response bytes with total %j", async (headers, totalBytes) => {+ mockGet.mockImplementation(httpsResponse(200, headers as Record<string, string>, "hello"));+ const dir = mkdtempSync(join(tmpdir(), "hyperframes-download-"));+ tempDirs.push(dir);+ const events: unknown[] = [];+ await downloadFile("https://example.test/model", join(dir, "model"), {+ onProgress: (receivedBytes, total) => events.push({ receivedBytes, totalBytes: total }),+ });+ expect(events).toContainEqual({ receivedBytes: 5, totalBytes });+ expect(readFileSync(join(dir, "model"), "utf8")).toBe("hello");+ });+it("keeps concurrent partial downloads separate", async () => {mockGet.mockImplementation(httpsResponse(200, {}, (url) => url));diff --git a/packages/cli/src/utils/download.ts b/packages/cli/src/utils/download.tsindex ae6d34af78..d73c5eaacf 100644--- a/packages/cli/src/utils/download.ts+++ b/packages/cli/src/utils/download.ts@@ -12,6 +12,7 @@ export interface DownloadOptions {timeoutMs?: number;/** Reject before writing more than this many response bytes. */maxBytes?: number;+ onProgress?: (receivedBytes: number, totalBytes: number | null) => void;}/** Every redirect a host may reasonably answer with, not just the two we saw first. */@@ -40,17 +41,28 @@ function removePartialFile(path: string): void {}}-function enforceByteLimit(maxBytes: number): Transform {- let received = 0;- return new Transform({+function measureDownload(options: DownloadOptions, contentLength: string | undefined) {+ const length = Number(contentLength);+ const totalBytes = Number.isSafeInteger(length) && length >= 0 ? length : null;+ let receivedBytes = 0;+ let reportedAt = Date.now();+ options.onProgress?.(0, totalBytes);+ const stream = new Transform({transform(chunk: Buffer, _encoding, callback) {- received += chunk.byteLength;- callback(- received > maxBytes ? new Error(`Download exceeded ${maxBytes} bytes`) : null,- chunk,- );+ receivedBytes += chunk.byteLength;+ if (options.maxBytes !== undefined && receivedBytes > options.maxBytes) {+ callback(new Error(`Download exceeded ${options.maxBytes} bytes`));+ return;+ }+ const now = Date.now();+ if (now - reportedAt >= 100) {+ options.onProgress?.(receivedBytes, totalBytes);+ reportedAt = now;+ }+ callback(null, chunk);},});+ return { stream, complete: () => options.onProgress?.(receivedBytes, totalBytes) };}/**@@ -73,7 +85,6 @@ export function downloadFile(): Promise<void> {const tmp = `${dest}.${process.pid}.${randomUUID()}.tmp`;const timeoutMs = options.timeoutMs ?? DEFAULT_DOWNLOAD_TIMEOUT_MS;- const maxBytes = options.maxBytes;return new Promise((resolve, reject) => {const follow = (u: string, hops = 0) => {let activeResponse: IncomingMessage | undefined;@@ -110,15 +121,14 @@ export function downloadFile(reject(new Error(`Download failed: HTTP ${res.statusCode}`));return;}+ const meter = measureDownload(options, res.headers["content-length"]);const file = createWriteStream(tmp);responsePipelineStarted = true;- const transfer =- maxBytes === undefined- ? pipeline(res, file)- : pipeline(res, enforceByteLimit(maxBytes), file);+ const transfer = pipeline(res, meter.stream, file);transfer.then(() => {renameSync(tmp, dest);+ meter.complete();resolve();}).catch((err) => {diff --git a/packages/cli/src/whisper/manager.install.test.ts b/packages/cli/src/whisper/manager.install.test.tsnew file mode 100644index 0000000000..f959e98450--- /dev/null+++ b/packages/cli/src/whisper/manager.install.test.ts@@ -0,0 +1,40 @@+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { afterEach, expect, it, vi } from "vitest";+import { ensureWhisper, findWhisper, WhisperUnavailableError } from "./manager.js";+const calls = vi.hoisted(() => ({ exec: vi.fn() }));+vi.mock("node:child_process", () => ({ execFileSync: calls.exec }));+vi.mock("node:os", async (original) => ({+ ...(await original<typeof import("node:os")>()),+ platform: () => "darwin",+}));+afterEach(() => {+ vi.unstubAllEnvs();+ calls.exec.mockReset();+});+it("never installs when the runtime vanishes after discovery and installation is disabled", async () => {+ const dir = mkdtempSync(join(tmpdir(), "hf-missing-runtime-"));+ const binary = join(dir, "whisper-cli");+ writeFileSync(binary, "runtime");+ vi.stubEnv("HYPERFRAMES_WHISPER_PATH", binary);+ calls.exec.mockImplementation((command: string, args: string[]) => {+ if ((command === "which" || command === "where") && args[0] !== "whisper-cli")+ return `/bin/${args[0]}\n`;+ throw new Error("not available");+ });+ try {+ expect(findWhisper()?.executablePath).toBe(binary);+ rmSync(binary);+ await expect(ensureWhisper({ installRuntime: false })).rejects.toBeInstanceOf(+ WhisperUnavailableError,+ );+ expect(+ calls.exec.mock.calls.filter(+ ([command]) => command === "brew" || command === "git" || command === "cmake",+ ),+ ).toEqual([]);+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+});diff --git a/packages/cli/src/whisper/manager.ts b/packages/cli/src/whisper/manager.tsindex 55d4e3b0de..e9cf61304f 100644--- a/packages/cli/src/whisper/manager.ts+++ b/packages/cli/src/whisper/manager.ts@@ -176,11 +176,17 @@ function hasCmake(): boolean {}export async function ensureWhisper(options?: {+ installRuntime?: boolean;onProgress?: (msg: string) => void;}): Promise<WhisperResult> {// 1. Already installed?const existing = findWhisper();if (existing) return existing;+ if (options?.installRuntime === false) {+ throw new WhisperUnavailableError(+ "whisper-cpp not found; runtime installation is disabled by --no-runtime-install.",+ );+ }// 2. Try brew (macOS, fastest — pre-built bottle)if (platform() === "darwin" && hasBrew()) {@@ -212,7 +218,10 @@ export async function ensureWhisper(options?: {export async function ensureModel(model: string = DEFAULT_MODEL,- options?: { onProgress?: (message: string) => void },+ options?: {+ onProgress?: (message: string) => void;+ onDownloadProgress?: (receivedBytes: number, totalBytes: number | null) => void;+ },): Promise<string> {const modelPath = join(MODELS_DIR, `ggml-${model}.bin`);if (existsSync(modelPath)) return modelPath;@@ -220,7 +229,7 @@ export async function ensureModel(mkdirSync(MODELS_DIR, { recursive: true });options?.onProgress?.(`Downloading model ${model}...`);- await downloadFile(getModelUrl(model), modelPath);+ await downloadFile(getModelUrl(model), modelPath, { onProgress: options?.onDownloadProgress });if (!existsSync(modelPath)) {throw new Error(`Model download failed: ${model}`);diff --git a/packages/cli/src/whisper/parakeet.ts b/packages/cli/src/whisper/parakeet.tsindex ea805210aa..6a969ed639 100644--- a/packages/cli/src/whisper/parakeet.ts+++ b/packages/cli/src/whisper/parakeet.ts@@ -18,7 +18,7 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSyncimport { homedir, tmpdir } from "node:os";import { basename, extname, join } from "node:path";import type { Word } from "./normalize.js";-import type { TranscribeResult } from "./transcribe.js";+import type { TranscribeProgress, TranscribeResult } from "./transcribe.js";/** The model name `transcribe --json` reports for every Parakeet runner. */export const PARAKEET_MODEL_LABEL = "parakeet-tdt-0.6b-v3";@@ -273,6 +273,7 @@ interface ParakeetOptions {language?: string;model?: string;onProgress?: (message: string) => void;+ onEvent?: (event: TranscribeProgress) => void;}/** Transcribe with Parakeet and write `transcript.json` (Word[]) into `dir`. */@@ -301,14 +302,27 @@ export function transcribeWithParakeet(try {const argv = [inputPath, "--model", model, "--output-format", "json", "--output-dir", workDir];if (options?.language) argv.push("--language", options.language);+ options?.onEvent?.({+ type: "progress",+ phase: "transcription",+ model: PARAKEET_MODEL_LABEL,+ status: "started",+ });execFileSync(runner, argv, { stdio: ["ignore", "pipe", "pipe"], timeout: 1_800_000 });const produced = join(workDir, `${basename(inputPath, extname(inputPath))}.json`);if (!existsSync(produced)) throw new Error("Parakeet did not produce output.");- return writeParakeetTranscript(+ const result = writeParakeetTranscript(dir,mergeTokensToWords(JSON.parse(readFileSync(produced, "utf-8")) as ParakeetJson),);+ options?.onEvent?.({+ type: "progress",+ phase: "transcription",+ model: result.model,+ status: "completed",+ });+ return result;} finally {rmSync(workDir, { recursive: true, force: true });}@@ -319,5 +333,12 @@ export function writeParakeetTranscript(dir: string, words: Word[]): TranscribeRconst transcriptPath = join(dir, "transcript.json");writeFileSync(transcriptPath, JSON.stringify(words, null, 2));const durationSeconds = words.length > 0 ? words[words.length - 1]!.end : 0;- return { transcriptPath, wordCount: words.length, durationSeconds, speechOnsetSeconds: null };+ return {+ model: PARAKEET_MODEL_LABEL,+ detectedLanguage: null,+ transcriptPath,+ wordCount: words.length,+ durationSeconds,+ speechOnsetSeconds: null,+ };}diff --git a/packages/cli/src/whisper/progress.test.ts b/packages/cli/src/whisper/progress.test.tsnew file mode 100644index 0000000000..5fd8864148--- /dev/null+++ b/packages/cli/src/whisper/progress.test.ts@@ -0,0 +1,37 @@+import { Writable } from "node:stream";+import { setImmediate } from "node:timers/promises";+import { expect, it } from "vitest";+import { createProgressWriter } from "./progress.js";++it("coalesces byte updates behind a slow reader while preserving phase records", async () => {+ const lines: string[] = [];+ let release: (() => void) | undefined;+ const stream = new Writable({+ highWaterMark: 1,+ write(chunk, _encoding, callback) {+ lines.push(String(chunk));+ release = callback;+ },+ });+ const emit = createProgressWriter(stream);+ for (let receivedBytes = 0; receivedBytes < 10_000; receivedBytes++) {+ emit({ type: "progress", phase: "download", model: "tiny", receivedBytes, totalBytes: null });+ }+ emit({ type: "progress", phase: "transcription", model: "tiny", status: "started" });+ emit({ type: "progress", phase: "transcription", model: "tiny", status: "completed" });+ expect(lines).toHaveLength(1);+ while (release) {+ const next = release;+ release = undefined;+ next();+ await setImmediate();+ }+ expect(lines.map((line) => JSON.parse(line))).toEqual([+ { type: "progress", phase: "download", model: "tiny", receivedBytes: 0, totalBytes: null },+ { type: "progress", phase: "download", model: "tiny", receivedBytes: 9999, totalBytes: null },+ { type: "progress", phase: "transcription", model: "tiny", status: "started" },+ { type: "progress", phase: "transcription", model: "tiny", status: "completed" },+ ]);+ expect(stream.listenerCount("drain")).toBe(0);+ stream.destroy();+});diff --git a/packages/cli/src/whisper/progress.ts b/packages/cli/src/whisper/progress.tsnew file mode 100644index 0000000000..773668cc80--- /dev/null+++ b/packages/cli/src/whisper/progress.ts@@ -0,0 +1,30 @@+import type { Writable } from "node:stream";+import type { TranscribeProgress } from "./transcribe.js";++export function createProgressWriter(stream: Writable): (event: TranscribeProgress) => void {+ let blocked = false;+ const pending: TranscribeProgress[] = [];+ const write = (event: TranscribeProgress): void => {+ if (blocked) {+ const previous = pending.at(-1);+ if (+ event.phase === "download" &&+ previous?.phase === "download" &&+ previous.model === event.model+ ) {+ pending[pending.length - 1] = event;+ } else {+ pending.push(event);+ }+ return;+ }+ blocked = !stream.write(`${JSON.stringify(event)}\n`);+ if (blocked) {+ stream.once("drain", () => {+ blocked = false;+ while (!blocked && pending.length > 0) write(pending.shift()!);+ });+ }+ };+ return write;+}diff --git a/packages/cli/src/whisper/sherpa.ts b/packages/cli/src/whisper/sherpa.tsindex 35dfab44ee..ce8436c8f0 100644--- a/packages/cli/src/whisper/sherpa.ts+++ b/packages/cli/src/whisper/sherpa.ts@@ -17,10 +17,16 @@ import {mergeWindowsToWords,SHERPA_ERROR_PREFIX,SHERPA_RESULT_PREFIX,+ PARAKEET_MODEL_LABEL,writeParakeetTranscript,type SherpaWindow,} from "./parakeet.js";-import { getPreparedWavDurationSeconds, prepareWav, type TranscribeResult } from "./transcribe.js";+import {+ getPreparedWavDurationSeconds,+ prepareWav,+ type TranscribeProgress,+ type TranscribeResult,+} from "./transcribe.js";const RUNTIME = "sherpa-onnx-node";const RUNTIME_VERSION = "1.13.8";@@ -347,9 +353,26 @@ export function prepareSherpaWav(export async function transcribeWithSherpa(wavPath: string,dir: string,- options: { signal: AbortSignal; onProgress?: (message: string) => void },+ options: {+ signal: AbortSignal;+ onProgress?: (message: string) => void;+ onEvent?: (event: TranscribeProgress) => void;+ },): Promise<TranscribeResult> {options.onProgress?.("Transcribing with Parakeet...");+ options.onEvent?.({+ type: "progress",+ phase: "transcription",+ model: PARAKEET_MODEL_LABEL,+ status: "started",+ });const windows = await decode(wavPath, options.signal);- return writeParakeetTranscript(dir, mergeWindowsToWords(windows));+ const result = writeParakeetTranscript(dir, mergeWindowsToWords(windows));+ options.onEvent?.({+ type: "progress",+ phase: "transcription",+ model: result.model,+ status: "completed",+ });+ return result;}diff --git a/packages/cli/src/whisper/transcribe.metadata.test.ts b/packages/cli/src/whisper/transcribe.metadata.test.tsnew file mode 100644index 0000000000..3e84afd507--- /dev/null+++ b/packages/cli/src/whisper/transcribe.metadata.test.ts@@ -0,0 +1,127 @@+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";++const native = vi.hoisted(() => ({ exec: vi.fn(), missingLanguage: false, runtime: vi.fn() }));+vi.mock("node:child_process", () => ({ execFileSync: native.exec }));+vi.mock("./manager.js", () => ({+ DEFAULT_MODEL: "small.en",+ ensureWhisper: native.runtime,+ ensureModel: async (+ model: string,+ options: { onDownloadProgress?: (received: number, total: number | null) => void },+ ) => {+ options.onDownloadProgress?.(5, null);+ return `ggml-${model}.bin`;+ },+ hasFFmpeg: () => true,+}));+vi.mock("../browser/ffmpeg.js", () => ({+ findFFprobe: () => "ffprobe",+ findFFmpeg: () => "ffmpeg",+ getFFmpegInstallHint: () => "ffmpeg",+}));+let dir: string;+beforeEach(() => {+ dir = mkdtempSync(join(tmpdir(), "hf-language-"));+ writeFileSync(join(dir, "audio.wav"), Buffer.alloc(44));+ native.missingLanguage = false;+ native.runtime.mockReset().mockResolvedValue({ executablePath: "whisper-cli", source: "env" });+ native.exec.mockReset().mockImplementation((command: string, args: string[]) => {+ if (command === "ffprobe")+ return JSON.stringify({+ streams: [+ { codec_type: "audio", codec_name: "pcm_s16le", sample_rate: "16000", channels: 1 },+ ],+ });+ if (command !== "whisper-cli") throw new Error(`Unexpected executable: ${command}`);+ if (args.includes("--detect-language")) return "";+ const selected = args[args.indexOf("--language") + 1];+ let language = args.includes("--language") ? selected : "en";+ if (language === "auto") language = "es";+ const output = args[args.indexOf("--output-file") + 1];+ writeFileSync(+ `${output}.json`,+ JSON.stringify({+ result: native.missingLanguage ? {} : { language },+ transcription: [+ {+ tokens: [+ { text: language === "es" ? "Hola" : "Hello", offsets: { from: 0, to: 1000 } },+ ],+ },+ ],+ }),+ );+ return "";+ });+});+afterEach(() => rmSync(dir, { recursive: true, force: true }));++it("decodes multilingual audio automatically and returns the native detection", async () => {+ const result = await transcribe(join(dir, "audio.wav"), dir, { model: "small" });+ expect(result).toMatchObject({ detectedLanguage: "es", model: "small", wordCount: 1 });+ expect(native.exec.mock.calls.filter(([command]) => command === "whisper-cli")).toHaveLength(1);+});+it.each([+ ["small.en", undefined, "small.en"],+ ["small.en", "de", "small"],+ ["small", "en", "small"],+])("does not label requested %s / %s as detection", async (model, language, resolved) => {+ const result = await transcribe(join(dir, "audio.wav"), dir, { model, language });+ expect(result).toMatchObject({ detectedLanguage: null, model: resolved });+});+it("keeps an absent native language unknown", async () => {+ native.missingLanguage = true;+ expect(await transcribe(join(dir, "audio.wav"), dir, { model: "small" })).toMatchObject({+ detectedLanguage: null,+ });+});+it("reports download bytes and truthful transcription boundaries", async () => {+ const events: unknown[] = [];+ await transcribe(join(dir, "audio.wav"), dir, {+ model: "small",+ onEvent: (event) => events.push(event),+ });+ 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: "completed" },+ ]);+});++it("carries the runtime-install policy to discovery while leaving model downloads enabled", async () => {+ const events: unknown[] = [];+ await transcribe(join(dir, "audio.wav"), dir, {+ installRuntime: false,+ onEvent: (event) => events.push(event),+ });+ expect(native.runtime).toHaveBeenCalledWith(expect.objectContaining({ installRuntime: false }));+ expect(events).toContainEqual({+ type: "progress",+ phase: "download",+ model: "small.en",+ receivedBytes: 5,+ totalBytes: null,+ });+});+it("does not claim transcription completed when decoding fails", async () => {+ const events: unknown[] = [];+ const previous = native.exec.getMockImplementation()!;+ native.exec.mockImplementation((command: string, args: string[]) => {+ if (command === "whisper-cli") throw new Error("decoder failed");+ return previous(command, args);+ });+ await expect(+ transcribe(join(dir, "audio.wav"), dir, {+ model: "small",+ onEvent: (event) => events.push(event),+ }),+ ).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" },+ ]);+});diff --git a/packages/cli/src/whisper/transcribe.ts b/packages/cli/src/whisper/transcribe.tsindex 1c890a0292..a69992d334 100644--- a/packages/cli/src/whisper/transcribe.ts+++ b/packages/cli/src/whisper/transcribe.ts@@ -8,24 +8,6 @@ import { findFFmpeg, findFFprobe, getFFmpegInstallHint } from "../browser/ffmpegimport { stoppedByCancelSignal } from "../utils/renderCancellation.js";import { ensureWhisper, ensureModel, hasFFmpeg, DEFAULT_MODEL } from "./manager.js";-/**- * Detect the language of a WAV file using whisper's built-in language detection.- * Returns an ISO 639-1 code (e.g. "en", "es", "hi") or null if detection fails.- */-function detectLanguage(whisperPath: string, modelPath: string, wavPath: string): string | null {- try {- const output = execFileSync(whisperPath, ["--model", modelPath, "--detect-language", wavPath], {- encoding: "utf-8",- timeout: 30_000,- stdio: ["ignore", "pipe", "pipe"],- });- const match = output.match(/auto-detected language:\s*(\w+)/);- return match?.[1] ?? null;- } catch {- return null;- }-}-function findWavDataChunk(buf: Buffer): { offset: number; size: number } | null {if (buf.length < 12) return null;let pos = 12; // skip RIFF header@@ -258,10 +240,22 @@ export function detectSpeechOnset(wavPath: string): number | null {const AUDIO_EXTENSIONS = new Set([".mp3", ".wav", ".m4a", ".aac", ".ogg", ".flac"]);const VIDEO_EXTENSIONS = new Set([".mp4", ".webm", ".mov", ".mkv", ".avi"]);+export type TranscribeProgress =+ | {+ type: "progress";+ phase: "download";+ model: string;+ receivedBytes: number;+ totalBytes: number | null;+ }+ | { type: "progress"; phase: "transcription"; model: string; status: "started" | "completed" };+export interface TranscribeOptions {+ installRuntime?: boolean;model?: string;language?: string;onProgress?: (message: string) => void;+ onEvent?: (event: TranscribeProgress) => void;/*** Explicit whisper spawn timeout in ms. Overrides the duration+model auto-* scaled default. Callers that leave this undefined get the auto-scaled@@ -271,6 +265,8 @@ export interface TranscribeOptions {}export interface TranscribeResult {+ model: string;+ detectedLanguage: string | null;transcriptPath: string;wordCount: number;durationSeconds: number;@@ -449,63 +445,52 @@ export async function transcribe(// 1. Ensure whisper binaryoptions?.onProgress?.("Checking whisper...");- const whisper = await ensureWhisper({ onProgress: options?.onProgress });+ const whisper = await ensureWhisper({+ onProgress: options?.onProgress,+ installRuntime: options?.installRuntime,+ });// 2. Ensure modeloptions?.onProgress?.("Checking model...");const modelPath = await ensureModel(model, {onProgress: options?.onProgress,+ onDownloadProgress: options?.onEvent+ ? (receivedBytes, totalBytes) =>+ options.onEvent?.({+ type: "progress",+ phase: "download",+ model,+ receivedBytes,+ totalBytes,+ })+ : undefined,});// 3. Prepare audioconst wavPath = prepareWav(inputPath, options?.onProgress);- // 4. Detect language and ensure correct model- let effectiveModel = model;- let effectiveModelPath = modelPath;- let detectedLanguage = options?.language ?? null;-- // Only auto-detect language when using a multilingual model.- // .en models always report "en" regardless of actual language, so detection- // would be a no-op. If the user chose .en, they want English.- if (!detectedLanguage && !effectiveModel.endsWith(".en")) {- options?.onProgress?.("Detecting language...");- detectedLanguage = detectLanguage(whisper.executablePath, effectiveModelPath, wavPath);- }-- if (detectedLanguage && detectedLanguage !== "en" && effectiveModel.endsWith(".en")) {- const multilingualModel = effectiveModel.replace(/\.en$/, "");- options?.onProgress?.(- `Detected ${detectedLanguage} — switching to ${multilingualModel} model...`,- );- effectiveModelPath = await ensureModel(multilingualModel, {- onProgress: options?.onProgress,- });- effectiveModel = multilingualModel;- }-- // 5. Run whisper+ 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 outputBase = join(outputDir, "transcript");mkdirSync(outputDir, { recursive: true });const whisperArgs = ["--model",- effectiveModelPath,+ modelPath,"--output-json-full","--output-file",outputBase,"--dtw",- dtwPresetForModel(effectiveModel),+ dtwPresetForModel(model),"--suppress-nst",];- if (detectedLanguage) {- whisperArgs.push("--language", detectedLanguage);- }+ whisperArgs.push("--language", language);whisperArgs.push(wavPath);const whisperTimeoutMs = resolveWhisperTimeoutMs(getPreparedWavDurationSeconds(wavPath), {- model: effectiveModel,+ model,overrideMs: options?.timeoutMs,});try {@@ -520,7 +505,7 @@ export async function transcribe(// existing stderr-tail handling in `transcribeAudio` still applies.throw wrapWhisperTimeoutError(err, {effectiveTimeoutMs: whisperTimeoutMs,- model: effectiveModel,+ model,wasOverride: options?.timeoutMs != null,});}@@ -532,6 +517,11 @@ export async function transcribe(}const transcript = JSON.parse(readFileSync(transcriptPath, "utf-8"));+ const reportedLanguage: unknown = transcript.result?.language;+ const detectedLanguage =+ automaticLanguage && typeof reportedLanguage === "string" && reportedLanguage.length > 0+ ? reportedLanguage+ : null;const segments = transcript.transcription ?? [];let wordCount = 0;@@ -557,7 +547,10 @@ export async function transcribe(}}+ options?.onEvent?.({ type: "progress", phase: "transcription", model, status: "completed" });return {+ model,+ detectedLanguage,transcriptPath,wordCount,durationSeconds: maxEnd / 1000,