Skip to content

Commit 1db44c6

Browse files
fix(cli): report transcription language and progress (#5103)
* docs(cli): record transcription output contract * fix(cli): report transcription language and progress
1 parent 4c4b857 commit 1db44c6

13 files changed

Lines changed: 576 additions & 87 deletions
Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
<!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>
2+
:root{color-scheme:light dark;
3+
--bg:#fbfbfa;--card:#ffffff;--line:#e6e4df;--ink:#1c1c1a;--dim:#6b6b66;--faint:#9a9a94;
4+
--go:#178a5a;--go-bg:#e8f6ee;
5+
--warn:#a6690a;--warn-bg:#fbf1dc;--bad:#c0392b;--bad-bg:#fbe7e4;--info:#2a5db0;--info-bg:#e8eefb;
6+
--mono:ui-monospace,SFMono-Regular,Menlo,monospace;--sans:-apple-system,BlinkMacSystemFont,"Segoe UI",Inter,sans-serif}
7+
@media (prefers-color-scheme:dark){:root{--bg:#111213;--card:#191b1d;--line:#2a2d31;--ink:#ecebe8;--dim:#a2a29c;--faint:#6f6f6a;
8+
--go:#5fd39a;--go-bg:#12291f;--warn:#e6b35a;--warn-bg:#2b2311;
9+
--bad:#ff7b6b;--bad-bg:#2d1714;--info:#7fa9ff;--info-bg:#15203a}}
10+
*{box-sizing:border-box}
11+
body{margin:0;background:var(--bg);color:var(--ink);font:16px/1.55 var(--sans)}
12+
.wrap{max-width:900px;margin:0 auto;padding:56px 24px 96px}
13+
header h1{font-size:30px;line-height:1.15;letter-spacing:-.4px;margin:0 0 10px}
14+
header .what{font-size:18px;color:var(--dim);margin:0 0 18px;max-width:70ch}
15+
.strip{display:flex;gap:10px;flex-wrap:wrap;align-items:center;font:13px var(--mono);color:var(--faint)}
16+
.strip .sep{opacity:.5}
17+
.pill{display:inline-flex;align-items:center;gap:6px;font:600 12px/1 var(--mono);padding:6px 10px;border-radius:999px;white-space:nowrap}
18+
.pill.go{color:var(--go);background:var(--go-bg)}.pill.warn{color:var(--warn);background:var(--warn-bg)}
19+
.pill.bad{color:var(--bad);background:var(--bad-bg)}.pill.info{color:var(--info);background:var(--info-bg)}
20+
.pill b{font-size:13px}
21+
section{margin-top:56px}
22+
h2{font-size:22px;letter-spacing:-.3px;margin:0 0 6px}
23+
.sub{color:var(--dim);margin:0 0 18px;font-size:15px}
24+
.card{background:var(--card);border:1px solid var(--line);border-radius:14px;padding:20px 22px;margin:14px 0}
25+
.breath{border-left:4px solid var(--go);font-size:18px;line-height:1.5}
26+
.breath b{color:var(--go)}
27+
.plain{color:var(--dim);font-size:15px;margin:0 0 10px}
28+
.plain::before{content:"In plain words ";font:600 11px var(--mono);letter-spacing:1px;color:var(--faint);text-transform:uppercase}
29+
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}
30+
code{font:13px var(--mono);background:var(--bg);border:1px solid var(--line);border-radius:5px;padding:1px 6px}
31+
.cite{font:12px var(--mono);color:var(--faint);margin-top:8px;display:block}
32+
.states{display:flex;gap:8px;margin:12px 0 4px;flex-wrap:wrap}
33+
table{width:100%;border-collapse:collapse;margin:10px 0;font-size:14.5px}
34+
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}
35+
td{padding:10px;border-bottom:1px solid var(--line);vertical-align:top}
36+
tr:last-child td{border-bottom:0}
37+
td.k{font:13px var(--mono);white-space:nowrap}
38+
.decision{border-left:4px solid var(--info)}
39+
.decision h3{margin:0 0 8px;font-size:17px}
40+
.decision .ask{color:var(--info);font-weight:600}
41+
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}
42+
blockquote .src{display:block;font-style:normal;font:12px var(--mono);color:var(--faint);margin-top:6px}
43+
ul,ol{padding-left:22px}li{margin:6px 0}
44+
.mermaid{background:var(--card);border:1px solid var(--line);border-radius:14px;padding:18px;margin:14px 0;overflow:auto}
45+
.mermaid svg{max-width:100%}
46+
footer{margin-top:72px;padding-top:16px;border-top:1px solid var(--line);font:12px/1.7 var(--mono);color:var(--faint)}
47+
</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>
48+
<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>
49+
<section><h2>Where the value travels</h2><pre>Whisper JSON result.language → transcription result → CLI stdout → JSON consumer
50+
HTTP response bytes → download pipeline → model callback → CLI stderr → progress consumer
51+
Whisper words → normalization → transcript.json (word array, unchanged)</pre></section>
52+
<section><h2>The contract, per boundary</h2>
53+
<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
54+
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>
55+
<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,
56+
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>
57+
<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",
58+
"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>
59+
<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",
60+
"status":"started"}
61+
{"type":"progress","phase":"transcription","model":"small",
62+
"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>
63+
<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>
64+
<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>
65+
<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>
66+
<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>

‎packages/cli/src/commands/transcribe.test.ts‎

Lines changed: 64 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import { runCommand } from "citty";
12
import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
23
import { chmodSync, existsSync, writeFileSync, readFileSync, mkdtempSync, rmSync } from "node:fs";
34
import { join } from "node:path";
@@ -44,7 +45,14 @@ import transcribeCmd from "./transcribe.js";
4445
function fakeTranscript(dir: string, text: string) {
4546
const transcriptPath = join(dir, "transcript.json");
4647
writeFileSync(transcriptPath, JSON.stringify([{ text, start: 0, end: 1 }]));
47-
return { transcriptPath, wordCount: 1, durationSeconds: 1, speechOnsetSeconds: null };
48+
return {
49+
model: text === "whisper" ? "small.en" : "parakeet-tdt-0.6b-v3",
50+
detectedLanguage: null,
51+
transcriptPath,
52+
wordCount: 1,
53+
durationSeconds: 1,
54+
speechOnsetSeconds: null,
55+
};
4856
}
4957

5058
function lastJson(): Record<string, unknown> {
@@ -81,6 +89,47 @@ describe("transcribe command", () => {
8189
vi.unstubAllEnvs();
8290
});
8391

92+
it("keeps typed progress on stderr and reports resolved metadata in one stdout result", async () => {
93+
const { dir, input } = dummyAudio();
94+
dirs.push(dir);
95+
const stderr = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
96+
transcribeMock.mockImplementation(async (_input, outputDir, options) => {
97+
options.onEvent?.({
98+
type: "progress",
99+
phase: "download",
100+
model: "small",
101+
receivedBytes: 5,
102+
totalBytes: null,
103+
});
104+
options.onEvent?.({
105+
type: "progress",
106+
phase: "transcription",
107+
model: "small",
108+
status: "started",
109+
});
110+
options.onEvent?.({
111+
type: "progress",
112+
phase: "transcription",
113+
model: "small",
114+
status: "completed",
115+
});
116+
return { ...fakeTranscript(outputDir, "hola"), model: "small", detectedLanguage: "es" };
117+
});
118+
await transcribeCmd.run!({
119+
args: { input, dir, json: true, engine: "whisper", model: "small.en" },
120+
} as never);
121+
expect(console.log).toHaveBeenCalledTimes(1);
122+
expect(lastJson()).toMatchObject({ ok: true, model: "small", detectedLanguage: "es" });
123+
expect(stderr.mock.calls.map(([line]) => JSON.parse(String(line)))).toEqual([
124+
{ type: "progress", phase: "download", model: "small", receivedBytes: 5, totalBytes: null },
125+
{ type: "progress", phase: "transcription", model: "small", status: "started" },
126+
{ type: "progress", phase: "transcription", model: "small", status: "completed" },
127+
]);
128+
expect(JSON.parse(readFileSync(join(dir, "transcript.json"), "utf8"))).toEqual([
129+
{ id: "w0", text: "hola", start: 0, end: 1 },
130+
]);
131+
});
132+
84133
it("explicit run exits non-zero and is NOT reported as a command failure", async () => {
85134
const { dir, input } = dummyAudio();
86135
dirs.push(dir);
@@ -252,6 +301,20 @@ describe("transcribe command", () => {
252301
return { exitCode: exitCode || consumeCommandResult().exitCode, out: lastJson() };
253302
}
254303

304+
it.each(["whisper", "auto"])(
305+
"--no-runtime-install reaches %s including the fallback",
306+
async (engine) => {
307+
crashChild("SIGABRT");
308+
Object.assign(runners, { sherpa: true, mlx: false });
309+
const { dir, input } = dummyAudio();
310+
dirs.push(dir);
311+
await runCommand(transcribeCmd, {
312+
rawArgs: [input, "--engine", engine, "--json", "--no-runtime-install"],
313+
});
314+
expect(transcribeMock.mock.calls.at(-1)?.[2]).toMatchObject({ installRuntime: false });
315+
},
316+
);
317+
255318
it("auto falls back to whisper with one line naming the Parakeet error and the repair", async () => {
256319
crashChild("SIGABRT", "terminate called after throwing an instance of 'Ort::Exception'\n");
257320
expect(await transcribeWith("auto", { sherpa: true, mlx: false })).toMatchObject({

‎packages/cli/src/commands/transcribe.ts‎

Lines changed: 42 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import { createProgressWriter } from "../whisper/progress.js";
12
import { failCommand, setCommandExitCode } from "../utils/commandResult.js";
23
import { normalizeErrorMessage } from "../utils/errorMessage.js";
34
// fallow-ignore-file code-duplication
@@ -7,7 +8,6 @@ import { existsSync, rmSync, writeFileSync } from "node:fs";
78
import {
89
findParakeet,
910
PARAKEET_LANGUAGES,
10-
PARAKEET_MODEL_LABEL,
1111
parakeetSpeaks,
1212
transcribeWithParakeet,
1313
} from "../whisper/parakeet.js";
@@ -77,7 +77,7 @@ export default defineCommand({
7777
},
7878
json: {
7979
type: "boolean",
80-
description: "Output result as JSON",
80+
description: "Output result as JSON; progress JSON lines go to stderr",
8181
default: false,
8282
},
8383
to: {
@@ -95,6 +95,12 @@ export default defineCommand({
9595
"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.",
9696
default: false,
9797
},
98+
"runtime-install": {
99+
type: "boolean",
100+
default: true,
101+
description:
102+
"Allow installing the Whisper runtime. Use --no-runtime-install to require an existing runtime; model downloads remain allowed.",
103+
},
98104
optional: {
99105
type: "boolean",
100106
description:
@@ -153,6 +159,7 @@ export default defineCommand({
153159
language: args.language,
154160
json: args.json,
155161
optional: args.optional,
162+
installRuntime: args["runtime-install"],
156163
timeoutMs,
157164
});
158165
},
@@ -294,6 +301,7 @@ async function transcribeAudio(
294301
language?: string;
295302
json?: boolean;
296303
optional?: boolean;
304+
installRuntime?: boolean;
297305
timeoutMs?: number;
298306
},
299307
): Promise<void> {
@@ -339,20 +347,39 @@ async function transcribeAudio(
339347
const spin = opts.json ? null : clack.spinner();
340348
spin?.start(`Transcribing with ${label(runner)}...`);
341349
const onProgress = spin ? (msg: string) => spin.message(msg) : undefined;
350+
const onEvent = opts.json ? createProgressWriter(process.stderr) : undefined;
342351
let wavPath = inputPath;
343352
// Before audio prep: under --json no spinner listens for SIGINT, so Ctrl-C would kill Node.
344353
const cancellation = runner === "sherpa" ? createRenderCancellationScope() : null;
345-
const run = (r: Runner) =>
346-
r === "sherpa"
347-
? transcribeWithSherpa(wavPath, dir, { onProgress, signal: cancellation!.signal })
348-
: r === "parakeet-mlx"
349-
? transcribeWithParakeet(wavPath, dir, { language: opts.language, onProgress })
350-
: transcribe(wavPath, dir, {
351-
model,
352-
language: opts.language,
353-
onProgress,
354-
timeoutMs: opts.timeoutMs,
355-
});
354+
const run = (r: Runner) => {
355+
switch (r) {
356+
case "sherpa":
357+
return transcribeWithSherpa(wavPath, dir, {
358+
onProgress,
359+
onEvent,
360+
signal: cancellation!.signal,
361+
});
362+
case "parakeet-mlx":
363+
return transcribeWithParakeet(wavPath, dir, {
364+
language: opts.language,
365+
onProgress,
366+
onEvent,
367+
});
368+
case "whisper":
369+
return transcribe(wavPath, dir, {
370+
model,
371+
language: opts.language,
372+
onProgress,
373+
onEvent,
374+
timeoutMs: opts.timeoutMs,
375+
installRuntime: opts.installRuntime,
376+
});
377+
default: {
378+
const unreachable: never = r;
379+
throw new Error(`Unknown transcription runner: ${unreachable}`);
380+
}
381+
}
382+
};
356383

357384
try {
358385
// Outside the fallback: an unreadable input is not a Parakeet failure. The fallback reuses it.
@@ -402,7 +429,8 @@ async function transcribeAudio(
402429
JSON.stringify({
403430
ok: true,
404431
engine: runner === "whisper" ? "whisper" : "parakeet",
405-
model: runner === "whisper" ? model : PARAKEET_MODEL_LABEL,
432+
model: result.model,
433+
detectedLanguage: result.detectedLanguage,
406434
wordCount: words.length,
407435
durationSeconds: result.durationSeconds,
408436
speechOnsetSeconds: result.speechOnsetSeconds,

0 commit comments

Comments
 (0)