Skip to content

Commit a20b8b2

Browse files
committed
fix(cli): repair a Parakeet runtime missing its native binary, and pick Parakeet by language
The runtime dir is per platform and arch. Installed now needs the runtime manifest and the native sherpa-onnx.node; a half-installed dir is removed before npm runs, since install() keeps any dir holding the runtime manifest. The decode worker flattens a multi-line loader error onto its prefixed line and stops between windows once orphaned. transcribe opens its cancellation scope before audio prep, so Ctrl-C under --json cleans up. auto uses Parakeet only for its 25 languages and only where the host can run it; --engine parakeet with another language fails.
1 parent 4f8b5c5 commit a20b8b2

7 files changed

Lines changed: 217 additions & 45 deletions

File tree

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

Lines changed: 54 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -136,11 +136,11 @@ describe("transcribe command", () => {
136136
} as never);
137137
});
138138

139-
async function transcribeWith(engine: string, installed: typeof runners) {
139+
async function transcribeWith(engine: string, installed: typeof runners, language?: string) {
140140
Object.assign(runners, installed);
141141
const { dir, input } = dummyAudio();
142142
dirs.push(dir);
143-
await transcribeCmd.run!({ args: { input, json: true, engine } } as never);
143+
await transcribeCmd.run!({ args: { input, json: true, engine, language } } as never);
144144
const out = lastJson();
145145
const words = JSON.parse(readFileSync(String(out.transcriptPath), "utf-8"));
146146
return { engine: out.engine, model: out.model, word: words[0]?.text, start: words[0]?.start };
@@ -169,6 +169,51 @@ describe("transcribe command", () => {
169169
});
170170
});
171171

172+
it("auto uses Parakeet only for a language it transcribes", async () => {
173+
const both = { sherpa: true, mlx: true };
174+
expect(await transcribeWith("auto", both, "ja")).toMatchObject({ engine: "whisper" });
175+
expect(await transcribeWith("auto", both, "pt-BR")).toMatchObject({ engine: "parakeet" });
176+
expect(await transcribeWith("auto", both, "UK")).toMatchObject({ engine: "parakeet" });
177+
expect(transcribeMock).toHaveBeenCalledTimes(1);
178+
});
179+
180+
it("--engine parakeet with a language it does not transcribe fails without falling back", async () => {
181+
Object.assign(runners, { sherpa: true, mlx: true });
182+
const { exitCode, out } = await transcribeFails("parakeet", { language: "ja" });
183+
expect(exitCode).toBe(1);
184+
expect(out.error).toMatch(
185+
/^Parakeet does not transcribe --language ja; it covers en, es, .*uk\. Use --engine whisper\.$/,
186+
);
187+
expect(execFileMock).not.toHaveBeenCalled();
188+
expect(transcribeMock).not.toHaveBeenCalled();
189+
});
190+
191+
it("listens for Ctrl-C from before audio prep until the run ends", async () => {
192+
const before = process.listenerCount("SIGINT");
193+
let duringPrep = 0;
194+
prepareWavMock.mockImplementation((input: string) => {
195+
duringPrep = process.listenerCount("SIGINT");
196+
return input;
197+
});
198+
expect(await transcribeWith("auto", { sherpa: true, mlx: false })).toMatchObject({
199+
engine: "parakeet",
200+
});
201+
expect(duringPrep).toBe(before + 1);
202+
expect(process.listenerCount("SIGINT")).toBe(before);
203+
});
204+
205+
it("exits 130 when Ctrl-C stops the whisper fallback too", async () => {
206+
crashChild("SIGABRT");
207+
transcribeMock.mockImplementation(async () => {
208+
process.emit("SIGINT");
209+
throw new Error("whisper-cli was killed by SIGINT");
210+
});
211+
Object.assign(runners, { sherpa: true, mlx: false });
212+
const { exitCode, out } = await transcribeFails("auto");
213+
expect(exitCode).toBe(130);
214+
expect(out).toEqual({ ok: false, error: "Transcription cancelled" });
215+
});
216+
172217
it("--engine parakeet with nothing installed names the install command", async () => {
173218
Object.assign(runners, { sherpa: false, mlx: false });
174219
const { dir, input } = dummyAudio();
@@ -333,7 +378,7 @@ describe("transcribe command", () => {
333378
});
334379

335380
it.runIf(process.platform === "linux" && process.arch === "x64")(
336-
"falls back without spawning when glibc is too old for sherpa-onnx",
381+
"skips Parakeet when glibc is too old for sherpa-onnx, never naming the install command",
337382
async () => {
338383
vi.mocked(process.report.getReport).mockReturnValue({
339384
header: { glibcVersionRuntime: "2.31" },
@@ -342,7 +387,12 @@ describe("transcribe command", () => {
342387
engine: "whisper",
343388
});
344389
expect(execFileMock).not.toHaveBeenCalled();
345-
expect(String(vi.mocked(console.error).mock.calls[0]?.[0])).toMatch(/glibc 2\.32.*2\.31/);
390+
expect(console.error).not.toHaveBeenCalled();
391+
const { exitCode, out } = await transcribeFails("parakeet");
392+
expect(exitCode).toBe(1);
393+
expect(out.error).toMatch(
394+
/^Parakeet needs glibc 2\.32 or newer; this system has glibc 2\.31\.$/,
395+
);
346396
},
347397
);
348398
});

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

Lines changed: 35 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,13 @@ import { normalizeErrorMessage } from "../utils/errorMessage.js";
44
import { defineCommand } from "citty";
55
import type { Example } from "./_examples.js";
66
import { existsSync, rmSync, writeFileSync } from "node:fs";
7-
import { findParakeet, PARAKEET_MODEL_LABEL, transcribeWithParakeet } from "../whisper/parakeet.js";
7+
import {
8+
findParakeet,
9+
PARAKEET_LANGUAGES,
10+
PARAKEET_MODEL_LABEL,
11+
parakeetSpeaks,
12+
transcribeWithParakeet,
13+
} from "../whisper/parakeet.js";
814

915
type CaptionExportFormat = "srt" | "vtt";
1016

@@ -270,10 +276,10 @@ async function exportTranscript(
270276

271277
type Runner = "sherpa" | "parakeet-mlx" | "whisper";
272278

273-
/** auto and parakeet prefer sherpa-onnx, then an installed parakeet-mlx runner, then whisper. */
274-
function pickRunner(engine: string, sherpaInstalled: () => boolean): Runner {
275-
if (engine === "whisper") return "whisper";
276-
if (sherpaInstalled()) return "sherpa";
279+
/** auto and parakeet prefer sherpa-onnx, then parakeet-mlx, then whisper, in Parakeet's languages. */
280+
function pickRunner(engine: string, sherpaUsable: () => boolean, language?: string): Runner {
281+
if (engine === "whisper" || !parakeetSpeaks(language)) return "whisper";
282+
if (sherpaUsable()) return "sherpa";
277283
return findParakeet() ? "parakeet-mlx" : "whisper";
278284
}
279285

@@ -297,17 +303,28 @@ async function transcribeAudio(
297303
const { loadTranscript, patchCaptionHtml, stripBeforeOnset } =
298304
await import("../whisper/normalize.js");
299305

300-
const { DecodeCancelled, prepareSherpaWav, sherpaParakeetInstalled, transcribeWithSherpa } =
301-
await import("../whisper/sherpa.js");
306+
const {
307+
DecodeCancelled,
308+
prepareSherpaWav,
309+
sherpaParakeetInstalled,
310+
sherpaUnsupportedReason,
311+
transcribeWithSherpa,
312+
} = await import("../whisper/sherpa.js");
313+
const { createRenderCancellationScope } = await import("../utils/renderCancellation.js");
302314

303315
const engine = (opts.engine ?? "auto").toLowerCase();
304316
if (engine !== "auto" && engine !== "parakeet" && engine !== "whisper") {
305317
failWith(`Unknown --engine: ${opts.engine}. Use auto, parakeet, or whisper.`, !!opts.json);
306318
}
307-
let runner = pickRunner(engine, sherpaParakeetInstalled);
319+
const unsupported = sherpaUnsupportedReason();
320+
const sherpaUsable = () => !unsupported && sherpaParakeetInstalled();
321+
let runner = pickRunner(engine, sherpaUsable, opts.language);
308322
if (engine === "parakeet" && runner === "whisper") {
309323
failWith(
310-
"Parakeet is not installed. Install it with: hyperframes models install parakeet (or use --engine whisper)",
324+
!parakeetSpeaks(opts.language)
325+
? `Parakeet does not transcribe --language ${opts.language}; it covers ${PARAKEET_LANGUAGES.split(" ").join(", ")}. Use --engine whisper.`
326+
: (unsupported ??
327+
"Parakeet is not installed. Install it with: hyperframes models install parakeet (or use --engine whisper)"),
311328
!!opts.json,
312329
);
313330
}
@@ -324,9 +341,11 @@ async function transcribeAudio(
324341
spin?.start(`Transcribing with ${label(runner)}...`);
325342
const onProgress = spin ? (msg: string) => spin.message(msg) : undefined;
326343
let wavPath = inputPath;
344+
// Before audio prep: under --json no spinner listens for SIGINT, so Ctrl-C would kill Node.
345+
const cancellation = runner === "sherpa" ? createRenderCancellationScope() : null;
327346
const run = (r: Runner) =>
328347
r === "sherpa"
329-
? transcribeWithSherpa(wavPath, dir, { onProgress })
348+
? transcribeWithSherpa(wavPath, dir, { onProgress, signal: cancellation!.signal })
330349
: r === "parakeet-mlx"
331350
? transcribeWithParakeet(wavPath, dir, { language: opts.language, onProgress })
332351
: transcribe(wavPath, dir, {
@@ -347,7 +366,7 @@ async function transcribeAudio(
347366
const reason = normalizeErrorMessage(err).replace(/\.+$/, "");
348367
const parakeetError = `Parakeet failed: ${reason}. To repair it, run: hyperframes models install parakeet`;
349368
if (!parakeetFallsBack(engine)) throw new Error(parakeetError);
350-
runner = pickRunner(engine, () => false);
369+
runner = pickRunner(engine, () => false, opts.language);
351370
spin?.clear();
352371
console.error(c.warn(`${parakeetError}. Using ${runner} for this run.`));
353372
spin?.start(`Transcribing with ${label(runner)}...`);
@@ -399,9 +418,10 @@ async function transcribeAudio(
399418
);
400419
}
401420
} catch (err) {
402-
if (err instanceof DecodeCancelled) {
403-
if (opts.json) console.log(JSON.stringify({ ok: false, error: err.message }));
404-
else spin?.stop(c.warn(err.message));
421+
if (err instanceof DecodeCancelled || cancellation?.signal.aborted) {
422+
const message = "Transcription cancelled";
423+
if (opts.json) console.log(JSON.stringify({ ok: false, error: message }));
424+
else spin?.stop(c.warn(message));
405425
failCommand(130);
406426
}
407427
// Surface the last few lines of the ASR subprocess's stderr, which
@@ -440,6 +460,7 @@ async function transcribeAudio(
440460
}
441461
failCommand();
442462
} finally {
463+
cancellation?.dispose();
443464
if (wavPath !== inputPath) rmSync(wavPath, { force: true });
444465
}
445466
}

‎packages/cli/src/whisper/parakeet.ts‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,16 @@ export const PARAKEET_MODEL_LABEL = "parakeet-tdt-0.6b-v3";
2626
export const SHERPA_RESULT_PREFIX = "HYPERFRAMES_PARAKEET_RESULT:";
2727
export const SHERPA_ERROR_PREFIX = "HYPERFRAMES_PARAKEET_ERROR:";
2828

29+
/** Parakeet TDT 0.6B v3's languages, as listed on its model card. */
30+
export const PARAKEET_LANGUAGES =
31+
"en es fr de bg hr cs da nl et fi el hu it lv lt mt pl pt ro sk sl sv ru uk";
32+
33+
/** True when no language was asked for, or Parakeet transcribes it ("pt-BR" counts as pt). */
34+
export function parakeetSpeaks(language?: string): boolean {
35+
const base = language?.trim().toLowerCase().split(/[-_]/, 1)[0];
36+
return !base || PARAKEET_LANGUAGES.split(" ").includes(base);
37+
}
38+
2939
const DEFAULT_MODEL = "mlx-community/parakeet-tdt-0.6b-v3";
3040
const PARAKEET_INSTALL =
3141
"uv venv ~/.venvs/parakeet && VIRTUAL_ENV=~/.venvs/parakeet uv pip install parakeet-mlx";
@@ -117,14 +127,14 @@ export interface SherpaWindow {
117127
durations?: number[];
118128
}
119129

120-
const toMs = (seconds: number) => Math.round(seconds * 1000) / 1000;
130+
const roundToMs = (seconds: number) => Math.round(seconds * 1000) / 1000;
121131

122132
export function mergeWindowsToWords(windows: SherpaWindow[]): Word[] {
123133
return mergeTokensToWords({
124134
sentences: windows.map((w) => ({
125135
tokens: w.tokens.map((text, i) => {
126136
const start = w.offset + (w.timestamps[i] ?? 0);
127-
return { text, start: toMs(start), end: toMs(start + (w.durations?.[i] ?? 0)) };
137+
return { text, start: roundToMs(start), end: roundToMs(start + (w.durations?.[i] ?? 0)) };
128138
}),
129139
})),
130140
});

‎packages/cli/src/whisper/sherpa.test.ts‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,9 @@ import type { DownloadOptions } from "../cloud/download.js";
77
import {
88
ensureParakeetModel,
99
installSherpaRuntime,
10+
SHERPA_RUNTIME_DIR,
1011
sherpaPlatformPackage,
12+
sherpaRuntimeInstalled,
1113
sherpaUnsupportedReason,
1214
type ModelFile,
1315
} from "./sherpa.js";
@@ -52,6 +54,39 @@ describe("installSherpaRuntime", () => {
5254
expect(args).toContain("[email protected]");
5355
expect(args).toContain(sherpaPlatformPackage());
5456
});
57+
58+
it("repairs a runtime whose native binary is missing instead of calling it installed", async () => {
59+
const dir = mkdtempSync(join(tmpdir(), "hf-sherpa-runtime-"));
60+
const native = sherpaPlatformPackage().replace(/@[^@]+$/, "");
61+
const manifest = (root: string, name: string) => {
62+
mkdirSync(join(root, "node_modules", name), { recursive: true });
63+
writeFileSync(join(root, "node_modules", name, "package.json"), `{"name":"${name}"}`);
64+
};
65+
try {
66+
manifest(dir, "sherpa-onnx-node");
67+
manifest(dir, native);
68+
expect(sherpaRuntimeInstalled(dir)).toBe(false);
69+
const run = vi.fn(async (args: string[]) => {
70+
const staging = args[args.indexOf("--prefix") + 1]!;
71+
manifest(staging, "sherpa-onnx-node");
72+
manifest(staging, native);
73+
writeFileSync(join(staging, "node_modules", native, "sherpa-onnx.node"), "binary");
74+
});
75+
76+
await installSherpaRuntime({ run, dir });
77+
expect(run).toHaveBeenCalledTimes(1);
78+
expect(existsSync(join(dir, "node_modules", native, "sherpa-onnx.node"))).toBe(true);
79+
expect(sherpaRuntimeInstalled(dir)).toBe(true);
80+
} finally {
81+
rmSync(dir, { recursive: true, force: true });
82+
}
83+
});
84+
85+
it("keeps each platform and arch in its own runtime dir", () => {
86+
expect(SHERPA_RUNTIME_DIR).toMatch(
87+
new RegExp(`sherpa-onnx-node@1\\.13\\.8-${process.platform}-${process.arch}$`),
88+
);
89+
});
5590
});
5691

5792
describe("ensureParakeetModel", () => {

‎packages/cli/src/whisper/sherpa.ts‎

Lines changed: 28 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
import { execFile, type ExecFileException } from "node:child_process";
22
import { createHash, randomUUID } from "node:crypto";
3-
import { createReadStream, mkdirSync, renameSync, rmSync, statSync } from "node:fs";
3+
import { createReadStream, existsSync, mkdirSync, renameSync, rmSync, statSync } from "node:fs";
44
import { homedir } from "node:os";
55
import { join } from "node:path";
66
import { fileURLToPath } from "node:url";
@@ -12,7 +12,6 @@ import {
1212
runNpm,
1313
sweepStaleStaging,
1414
} from "../utils/optionalPackages.js";
15-
import { createRenderCancellationScope } from "../utils/renderCancellation.js";
1615
import {
1716
mergeWindowsToWords,
1817
SHERPA_ERROR_PREFIX,
@@ -24,7 +23,11 @@ import { getPreparedWavDurationSeconds, prepareWav, type TranscribeResult } from
2423

2524
const RUNTIME = "sherpa-onnx-node";
2625
const RUNTIME_VERSION = "1.13.8";
27-
export const SHERPA_RUNTIME_DIR = join(CACHE_DIR, `${RUNTIME}@${RUNTIME_VERSION}`);
26+
/** Per platform and arch, like the native package inside, so Rosetta never shadows arm64. */
27+
export const SHERPA_RUNTIME_DIR = join(
28+
CACHE_DIR,
29+
`${RUNTIME}@${RUNTIME_VERSION}-${process.platform}-${process.arch}`,
30+
);
2831

2932
const MODEL_REPO = "csukuangfj/sherpa-onnx-nemo-parakeet-tdt-0.6b-v3-int8";
3033
const MODEL_REVISION = "2bda32ec70b097a55adaa07d9a7173915b43cc78";
@@ -107,23 +110,29 @@ export function sherpaUnsupportedReason(host: Host = currentHost()): string | nu
107110
return `Parakeet needs glibc 2.32 or newer; this system has glibc ${host.glibc}.`;
108111
}
109112

110-
export function sherpaRuntimeInstalled(): boolean {
111-
return isInstalled(SHERPA_RUNTIME_DIR, RUNTIME);
113+
const nativePackageName = (platform: string, arch: string) =>
114+
`sherpa-onnx-${platform === "win32" ? "win" : platform}-${arch}`;
115+
116+
/** The runtime and the native binary its loader requires; either can be missing on its own. */
117+
export function sherpaRuntimeInstalled(dir = SHERPA_RUNTIME_DIR): boolean {
118+
const binary = join(dir, "node_modules", nativePackageName(process.platform, process.arch));
119+
return isInstalled(dir, RUNTIME) && existsSync(join(binary, "sherpa-onnx.node"));
112120
}
113121

114122
/** The native package, pinned too: the runtime's own optionalDependencies accept any 1.13.x. */
115123
export function sherpaPlatformPackage(platform = process.platform, arch = process.arch): string {
116-
return `sherpa-onnx-${platform === "win32" ? "win" : platform}-${arch}@${RUNTIME_VERSION}`;
124+
return `${nativePackageName(platform, arch)}@${RUNTIME_VERSION}`;
117125
}
118126

119127
export function installSherpaRuntime({
120128
run = runNpm,
121129
signal,
122-
}: { run?: typeof runNpm; signal?: AbortSignal } = {}): Promise<void> {
130+
dir = SHERPA_RUNTIME_DIR,
131+
}: { run?: typeof runNpm; signal?: AbortSignal; dir?: string } = {}): Promise<void> {
132+
// install() keeps any dir holding the runtime manifest, so a half-installed one goes first.
133+
if (!sherpaRuntimeInstalled(dir)) rmSync(dir, { recursive: true, force: true });
123134
const native = sherpaPlatformPackage();
124-
return install(SHERPA_RUNTIME_DIR, RUNTIME, RUNTIME_VERSION, (args) =>
125-
run([...args, native], signal),
126-
);
135+
return install(dir, RUNTIME, RUNTIME_VERSION, (args) => run([...args, native], signal));
127136
}
128137

129138
/** Sizes only: hashing 650 MB on every transcribe is too slow, and install already verified them. */
@@ -217,6 +226,8 @@ function recognizerConfig(): object {
217226
/** Ctrl-C or a SIGTERM stopped the decode: the user's cancel, never a reason to fall back. */
218227
export class DecodeCancelled extends Error {}
219228

229+
const MAX_REASON_CHARS = 600;
230+
220231
function failureReason(err: ExecFileException | null, stderr: string): string {
221232
const how = !err
222233
? "exited without a result"
@@ -232,7 +243,8 @@ function failureReason(err: ExecFileException | null, stderr: string): string {
232243
const why =
233244
lines.find((line) => line.startsWith(SHERPA_ERROR_PREFIX))?.slice(SHERPA_ERROR_PREFIX.length) ??
234245
lines.at(-1);
235-
return why ? `${how}: ${why}` : how;
246+
if (!why) return how;
247+
return `${how}: ${why.length > MAX_REASON_CHARS ? `${why.slice(0, MAX_REASON_CHARS)}…` : why}`;
236248
}
237249

238250
/** Decodes in a child process: onnxruntime aborts the whole process on some inputs, uncatchably. */
@@ -281,20 +293,13 @@ export function prepareSherpaWav(
281293
}
282294
}
283295

296+
/** The caller owns the cancellation scope: it must already cover audio preparation. */
284297
export async function transcribeWithSherpa(
285298
wavPath: string,
286299
dir: string,
287-
options?: { onProgress?: (message: string) => void },
300+
options: { signal: AbortSignal; onProgress?: (message: string) => void },
288301
): Promise<TranscribeResult> {
289-
const unsupported = sherpaUnsupportedReason();
290-
if (unsupported) throw new Error(unsupported);
291-
// Aborts on SIGINT/SIGTERM/SIGHUP, which also kills the child if only this process was signalled.
292-
const cancellation = createRenderCancellationScope();
293-
try {
294-
options?.onProgress?.("Transcribing with Parakeet...");
295-
const windows = await decode(wavPath, cancellation.signal);
296-
return writeParakeetTranscript(dir, mergeWindowsToWords(windows));
297-
} finally {
298-
cancellation.dispose();
299-
}
302+
options.onProgress?.("Transcribing with Parakeet...");
303+
const windows = await decode(wavPath, options.signal);
304+
return writeParakeetTranscript(dir, mergeWindowsToWords(windows));
300305
}

0 commit comments

Comments
 (0)