Skip to content

Commit 6c9a4b7

Browse files
jrusso1020claude
andcommitted
fix(cli): make the transcribe API's signal stop every stage
Review follow-ups on the api entry: - parakeet-mlx now runs as an async child that the caller's signal can kill. Its failures keep the synchronous run's message, status and stderr. - A pre-aborted signal throws before any setup. Whisper checks the signal before each setup stage, and the model download gets it. - onEngine reports the model whisper runs (small for Spanish, not small.en). The resolver moved to whisper/modelForLanguage.ts so both share it. - api/transcribe.ts imports everything at module scope. The command test hoists its whisper mock, since that module now loads during imports. - whisper's internal TranscribeOptions/TranscribeResult types are renamed WhisperOptions/RunnerResult, so the API's public names are unique. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
1 parent 93f8f57 commit 6c9a4b7

12 files changed

Lines changed: 308 additions & 64 deletions

File tree

‎packages/cli/src/api.test.ts‎

Lines changed: 78 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,16 @@
11
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
2-
import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
2+
import {
3+
chmodSync,
4+
existsSync,
5+
mkdtempSync,
6+
readFileSync,
7+
readdirSync,
8+
rmSync,
9+
writeFileSync,
10+
} from "node:fs";
311
import { tmpdir } from "node:os";
4-
import { join, resolve } from "node:path";
12+
import { dirname, join, resolve } from "node:path";
13+
import { fileURLToPath } from "node:url";
514
import { WhisperUnavailableError } from "./whisper/manager.js";
615

716
const { transcribeMock, renderMock } = vi.hoisted(() => ({
@@ -12,6 +21,11 @@ vi.mock("./whisper/transcribe.js", async (importOriginal) => ({
1221
...(await importOriginal<typeof import("./whisper/transcribe.js")>()),
1322
transcribe: transcribeMock,
1423
}));
24+
// Parakeet runs on parakeet-mlx in these tests, whatever this machine has installed.
25+
vi.mock("./whisper/sherpa.js", async (importOriginal) => ({
26+
...(await importOriginal<typeof import("./whisper/sherpa.js")>()),
27+
sherpaParakeetInstalled: () => false,
28+
}));
1529
vi.mock("./background-removal/pipeline.js", async (importOriginal) => ({
1630
...(await importOriginal<typeof import("./background-removal/pipeline.js")>()),
1731
render: renderMock,
@@ -41,6 +55,7 @@ afterEach(() => {
4155
expect(console.log).not.toHaveBeenCalled();
4256
expect(console.error).not.toHaveBeenCalled();
4357
vi.restoreAllMocks();
58+
vi.unstubAllEnvs();
4459
rmSync(dir, { recursive: true, force: true });
4560
});
4661

@@ -210,6 +225,67 @@ describe("transcribe", () => {
210225
expect(err.cause).toBe(crash);
211226
});
212227

228+
it("reports the model whisper will run, not the English-only default", async () => {
229+
const input = dummyAudio();
230+
transcribeMock.mockImplementation(async (_input, outputDir) => whisperResult(outputDir));
231+
const onEngine = vi.fn();
232+
233+
await transcribe({ input, engine: "whisper", language: "es", onEngine });
234+
235+
expect(onEngine).toHaveBeenCalledWith(expect.objectContaining({ model: "small" }));
236+
});
237+
238+
it("throws at once for a signal that is already aborted, before any setup", async () => {
239+
const input = dummyAudio();
240+
const controller = new AbortController();
241+
controller.abort();
242+
243+
const err = await transcribeError({ input, engine: "whisper", signal: controller.signal });
244+
245+
expect(err.code).toBe("cancelled");
246+
expect(transcribeMock).not.toHaveBeenCalled();
247+
});
248+
249+
it.skipIf(process.platform === "win32")(
250+
"stops a running parakeet-mlx when the signal aborts",
251+
async () => {
252+
const pidFile = join(dir, "parakeet.pid");
253+
const runner = join(dir, "parakeet-mlx");
254+
writeFileSync(
255+
runner,
256+
`#!/bin/sh\n[ "$1" = --help ] && exit 0\necho $$ > "${pidFile}"\nexec sleep 30\n`,
257+
);
258+
chmodSync(runner, 0o755);
259+
vi.stubEnv("HYPERFRAMES_PARAKEET", runner);
260+
const controller = new AbortController();
261+
const started = Date.now();
262+
// Abort once the child is really running; a blocked event loop never gets this far.
263+
const poll = setInterval(() => {
264+
if (existsSync(pidFile) && readFileSync(pidFile, "utf8").trim()) controller.abort();
265+
}, 20);
266+
267+
const err = await transcribeError({
268+
input: dummyAudio(),
269+
engine: "parakeet",
270+
signal: controller.signal,
271+
}).finally(() => clearInterval(poll));
272+
273+
expect(err.code).toBe("cancelled");
274+
expect(Date.now() - started).toBeLessThan(10_000);
275+
const pid = Number(readFileSync(pidFile, "utf8"));
276+
expect(() => process.kill(pid, 0)).toThrow();
277+
},
278+
);
279+
280+
it("keeps every import of the API modules at module scope", () => {
281+
const here = dirname(fileURLToPath(import.meta.url));
282+
const files = ["api.ts", ...readdirSync(join(here, "api")).map((f) => join("api", f))];
283+
const sources = files.filter((f) => !f.endsWith(".test.ts"));
284+
for (const file of sources) {
285+
expect(readFileSync(join(here, file), "utf8"), file).not.toMatch(/\bimport\(/);
286+
}
287+
});
288+
213289
it.each([
214290
["a missing input", () => ({ input: join(dir, "missing.wav") }), "input_not_found"],
215291
[

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

Lines changed: 48 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,41 @@
11
import { existsSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
22
import { basename, dirname, extname, join, resolve } from "node:path";
33
import { normalizeErrorMessage } from "../utils/errorMessage.js";
4+
import {
5+
createRenderCancellationScope,
6+
stoppedByCancelSignal,
7+
} from "../utils/renderCancellation.js";
48
import { DEFAULT_MODEL, isWhisperUnavailable } from "../whisper/manager.js";
9+
import { initialModelForLanguage } from "../whisper/modelForLanguage.js";
10+
import {
11+
formatSrt,
12+
formatVtt,
13+
loadTranscript,
14+
patchCaptionHtml,
15+
type TranscriptFormat,
16+
type Word,
17+
} from "../whisper/normalize.js";
518
import {
619
PARAKEET_INSTALL_COMMAND,
720
PARAKEET_LANGUAGES,
821
parakeetSpeaks,
922
transcribeWithParakeet,
1023
} from "../whisper/parakeet.js";
24+
import { parakeetRunner, type ParakeetRunner } from "../whisper/parakeetRunner.js";
25+
import {
26+
DecodeCancelled,
27+
prepareSherpaWav,
28+
sherpaUnsupportedReason,
29+
transcribeWithSherpa,
30+
} from "../whisper/sherpa.js";
1131
import { TRANSCRIPT_FILE } from "../whisper/transcriptFile.js";
12-
import type { TranscriptFormat, Word } from "../whisper/normalize.js";
13-
import type { ParakeetRunner } from "../whisper/parakeetRunner.js";
14-
import type { TranscribeProgress } from "../whisper/transcribe.js";
32+
import {
33+
transcribe as transcribeWithWhisper,
34+
type TranscribeProgress,
35+
} from "../whisper/transcribe.js";
1536

1637
// Smallest accepted whisper timeout. Below it the whisper spawn has no realistic chance of
17-
// finishing even on the fastest hardware for the shortest clip. This module never imports
18-
// `whisper/transcribe.ts` at the top level, so the command test can hoist its
19-
// `vi.mock("../whisper/transcribe.js")` factory without that module entering the sync-import graph.
38+
// finishing even on the fastest hardware for the shortest clip.
2039
export const MIN_TIMEOUT_MS = 5000;
2140

2241
export type TranscribeEngine = "auto" | "parakeet" | "whisper";
@@ -37,7 +56,7 @@ export interface TranscribeCaptionsOptions {
3756
export interface TranscribeEngineEvent {
3857
runner: TranscribeRunner;
3958
engine: "parakeet" | "whisper";
40-
/** The whisper model; meaningful only when `engine` is "whisper". */
59+
/** The model whisper runs, after `language` picks the multilingual twin; whisper engine only. */
4160
model: string;
4261
/** Set when auto mode gave up on Parakeet and this runner takes over. */
4362
fallbackReason?: string;
@@ -140,6 +159,11 @@ interface CancellationScope {
140159
}
141160

142161
export async function runTranscribe(options: TranscribeRequest): Promise<TranscribeResult> {
162+
if (options.signal?.aborted) {
163+
throw new TranscribeError("cancelled", "Transcription cancelled", {
164+
cause: options.signal.reason,
165+
});
166+
}
143167
const inputPath = resolve(options.input);
144168
if (!existsSync(inputPath)) {
145169
throw new TranscribeError("input_not_found", `File not found: ${options.input}`);
@@ -229,10 +253,7 @@ function sameFile(out: string, file: string): boolean {
229253
// Import and export existing transcripts
230254
// ---------------------------------------------------------------------------
231255

232-
async function readTranscript(
233-
inputPath: string,
234-
): Promise<{ words: Word[]; format: TranscriptFormat }> {
235-
const { loadTranscript } = await import("../whisper/normalize.js");
256+
function readTranscript(inputPath: string): { words: Word[]; format: TranscriptFormat } {
236257
let transcript: { words: Word[]; format: TranscriptFormat };
237258
try {
238259
transcript = loadTranscript(inputPath);
@@ -245,23 +266,19 @@ async function readTranscript(
245266
return transcript;
246267
}
247268

248-
async function importTranscript(inputPath: string, dir: string): Promise<TranscribeResult> {
249-
const { patchCaptionHtml } = await import("../whisper/normalize.js");
250-
const { words, format } = await readTranscript(inputPath);
269+
function importTranscript(inputPath: string, dir: string): TranscribeResult {
270+
const { words, format } = readTranscript(inputPath);
251271

252272
const transcriptPath = join(dir, TRANSCRIPT_FILE);
253273
writeFileSync(transcriptPath, JSON.stringify(words, null, 2));
254274
patchCaptionHtml(dir, words);
255275
return { kind: "imported", format, wordCount: words.length, transcriptPath };
256276
}
257277

258-
async function exportTranscript(
259-
inputPath: string,
260-
sidecar: CaptionSidecar,
261-
): Promise<TranscribeResult> {
262-
const { words, format } = await readTranscript(inputPath);
278+
function exportTranscript(inputPath: string, sidecar: CaptionSidecar): TranscribeResult {
279+
const { words, format } = readTranscript(inputPath);
263280
try {
264-
await writeCaptionSidecar(words, sidecar, format === "srt" || format === "vtt" || undefined);
281+
writeCaptionSidecar(words, sidecar, format === "srt" || format === "vtt" || undefined);
265282
} catch (err) {
266283
throw new TranscribeError(
267284
"caption_write_failed",
@@ -277,15 +294,14 @@ async function exportTranscript(
277294
};
278295
}
279296

280-
async function writeCaptionSidecar(
297+
function writeCaptionSidecar(
281298
words: Word[],
282299
{ to, outPath, preserveCues, keep }: CaptionSidecar,
283300
phraseLevelSource: boolean | undefined,
284-
): Promise<void> {
301+
): void {
285302
// Checked at write time, when the transcript exists, so the OS resolves every link and alias.
286303
const hit = keep.find((file) => sameFile(outPath, file));
287304
if (hit) throw new Error(`it is the same file as ${hit}`);
288-
const { formatSrt, formatVtt } = await import("../whisper/normalize.js");
289305
// A .srt/.vtt source is already phrase-level; keep its cue boundaries 1:1.
290306
// preserveCues forces the same for an already-cued transcript.json whose
291307
// entries have no internal whitespace (single-word or CJK captions), which
@@ -344,15 +360,6 @@ async function transcribeAudio(
344360
sidecar: CaptionSidecar | undefined,
345361
options: TranscribeRequest,
346362
): Promise<TranscribeResult> {
347-
const { transcribe } = await import("../whisper/transcribe.js");
348-
const { loadTranscript, patchCaptionHtml } = await import("../whisper/normalize.js");
349-
350-
const { DecodeCancelled, prepareSherpaWav, sherpaUnsupportedReason, transcribeWithSherpa } =
351-
await import("../whisper/sherpa.js");
352-
const { parakeetRunner } = await import("../whisper/parakeetRunner.js");
353-
const { createRenderCancellationScope, stoppedByCancelSignal } =
354-
await import("../utils/renderCancellation.js");
355-
356363
const engine = (options.engine ?? "auto").toLowerCase();
357364
if (engine !== "auto" && engine !== "parakeet" && engine !== "whisper") {
358365
throw new TranscribeError(
@@ -373,15 +380,17 @@ async function transcribeAudio(
373380
}
374381

375382
const model = options.model ?? DEFAULT_MODEL;
376-
options.onEngine?.({ runner, engine: engineOf(runner), model });
383+
const whisperModel = initialModelForLanguage(model, options.language);
384+
options.onEngine?.({ runner, engine: engineOf(runner), model: whisperModel });
377385
const { onStatus, onProgress } = options;
378386
const startScope = (): CancellationScope =>
379387
options.stopOnProcessSignals
380388
? createRenderCancellationScope()
381389
: { signal: options.signal ?? new AbortController().signal, dispose: () => {} };
382390
let wavPath = inputPath;
383391
// Before audio prep: under --json no spinner listens for SIGINT, so Ctrl-C would kill Node.
384-
let cancellation = runner === "sherpa" ? startScope() : null;
392+
// A caller's own signal is live from the start, whichever runner it ends up stopping.
393+
let cancellation = runner === "sherpa" || !options.stopOnProcessSignals ? startScope() : null;
385394
const run = (r: TranscribeRunner) => {
386395
switch (r) {
387396
case "sherpa":
@@ -394,15 +403,17 @@ async function transcribeAudio(
394403
return transcribeWithParakeet(wavPath, dir, {
395404
onProgress: onStatus,
396405
onEvent: onProgress,
406+
signal: cancellation?.signal,
397407
});
398408
case "whisper":
399-
return transcribe(wavPath, dir, {
409+
return transcribeWithWhisper(wavPath, dir, {
400410
model,
401411
language: options.language,
402412
onProgress: onStatus,
403413
onEvent: onProgress,
404414
timeoutMs: options.timeoutMs,
405415
installRuntime: options.installRuntime,
416+
signal: cancellation?.signal,
406417
startCancellation: () => (cancellation ??= startScope()).signal,
407418
});
408419
default: {
@@ -431,7 +442,7 @@ async function transcribeAudio(
431442
options.onEngine?.({
432443
runner,
433444
engine: engineOf(runner),
434-
model,
445+
model: whisperModel,
435446
fallbackReason: parakeetError,
436447
});
437448
try {
@@ -452,7 +463,7 @@ async function transcribeAudio(
452463
patchCaptionHtml(dir, words);
453464
if (sidecar) {
454465
try {
455-
await writeCaptionSidecar(words, sidecar, false);
466+
writeCaptionSidecar(words, sidecar, false);
456467
} catch (err) {
457468
throw new TranscribeError(
458469
"caption_write_failed",

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,8 @@ import { formatVtt, loadTranscript } from "../whisper/normalize.js";
2020
import { CliRuntimeError, consumeCommandResult } from "../utils/commandResult.js";
2121

2222
// Make the whisper core report "unavailable" so we exercise the soft-skip path.
23-
const transcribeMock = vi.fn();
23+
// Hoisted: the transcribe API imports whisper/transcribe.js statically, so this mock's factory runs during imports.
24+
const transcribeMock = vi.hoisted(() => vi.fn());
2425
const prepareWavMock = vi.fn((input: string) => input);
2526
let audioSeconds = 1;
2627
vi.mock("node:fs", async (importOriginal) => {

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -168,7 +168,8 @@ function showEngine(
168168
spin: Spinner | null,
169169
opts: { json: boolean; model?: string },
170170
): Spinner | null {
171-
const label = c.accent(event.runner === "whisper" ? event.model : "Parakeet");
171+
// The requested model, as the spinner has always shown it; event.model is the one whisper runs.
172+
const label = c.accent(event.runner === "whisper" ? (opts.model ?? DEFAULT_MODEL) : "Parakeet");
172173
if (event.fallbackReason !== undefined) {
173174
spin?.clear();
174175
console.error(c.warn(`${event.fallbackReason}. Using ${event.runner} for this run.`));

‎packages/cli/src/utils/download.test.ts‎

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { randomUUID } from "node:crypto";
2-
import { ensureModel } from "../whisper/manager.js";
2+
import { MODELS_DIR, ensureModel } from "../whisper/manager.js";
33
import { EventEmitter } from "node:events";
44
import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs";
55
import { tmpdir } from "node:os";
@@ -55,6 +55,40 @@ afterEach(() => {
5555
});
5656

5757
describe("downloadFile", () => {
58+
it("hands https.get the caller's signal, so aborting a model download removes the partial file", async () => {
59+
let seen: AbortSignal | undefined;
60+
mockGet.mockImplementation(((
61+
_url: string,
62+
options: { signal?: AbortSignal },
63+
callback: (response: IncomingMessage) => void,
64+
) => {
65+
seen = options.signal;
66+
const response = Object.assign(new PassThrough(), { statusCode: 200, headers: {} });
67+
const request = new EventEmitter() as ClientRequest;
68+
request.setTimeout = vi.fn();
69+
callback(response as unknown as IncomingMessage);
70+
response.write("partial");
71+
// What Node does with a request whose signal aborts.
72+
options.signal?.addEventListener("abort", () =>
73+
request.emit(
74+
"error",
75+
Object.assign(new Error("The operation was aborted"), { name: "AbortError" }),
76+
),
77+
);
78+
return request;
79+
}) as unknown as typeof httpsGet);
80+
const controller = new AbortController();
81+
const model = `test-${randomUUID()}`;
82+
83+
const download = ensureModel(model, { signal: controller.signal });
84+
await new Promise((resolve) => setImmediate(resolve));
85+
controller.abort();
86+
87+
await expect(download).rejects.toThrow("The operation was aborted");
88+
expect(seen).toBe(controller.signal);
89+
expect(readdirSync(MODELS_DIR).filter((name) => name.includes(model))).toEqual([]);
90+
});
91+
5892
it("carries model download progress through the real pipeline and stays quiet on cache hits", async () => {
5993
mockGet.mockImplementation(httpsResponse(200, { "content-length": "5" }, "hello"));
6094
const events: unknown[] = [];

0 commit comments

Comments
 (0)