Skip to content

Write HTML. Render video. Built for agents.

feat(cli): add hyperframes/api entry with transcribe and removeBackground (#5453)

James Russo943b6512b43b
diff --git a/knip.config.ts b/knip.config.ts
index 31dda6cbe3..454826dc4e 100644
--- a/knip.config.ts
+++ b/knip.config.ts
@@ -3,7 +3,7 @@ import type { KnipConfig } from "knip";
const config: KnipConfig = {
workspaces: {
"packages/cli": {
- entry: ["src/cli.ts"],
+ entry: ["src/cli.ts", "src/api.ts"],
},
"packages/core": {
entry: ["src/index.ts", "src/lint/index.ts", "src/compiler/index.ts"],
diff --git a/packages/cli/package-subpaths.json b/packages/cli/package-subpaths.json
new file mode 100644
index 0000000000..1a3bb11bda
--- /dev/null
+++ b/packages/cli/package-subpaths.json
@@ -0,0 +1,17 @@
+{
+ "package": "@hyperframes/cli",
+ "subpaths": {
+ "./api": {
+ "source": "./dist/api.js",
+ "runtime": "./dist/api.js",
+ "types": "./dist/api.d.ts",
+ "environments": ["node"]
+ },
+ "./package.json": {
+ "source": "./package.json",
+ "runtime": "./package.json",
+ "types": null,
+ "environments": ["browser", "bun", "node"]
+ }
+ }
+}
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 6c3c4a06a9..00690a3b0d 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -17,6 +17,13 @@
"dist"
],
"type": "module",
+ "exports": {
+ "./api": {
+ "import": "./dist/api.js",
+ "types": "./dist/api.d.ts"
+ },
+ "./package.json": "./package.json"
+ },
"scripts": {
"test": "vitest run",
"dev": "tsx src/cli.ts",
diff --git a/packages/cli/src/api.test.ts b/packages/cli/src/api.test.ts
new file mode 100644
index 0000000000..26bb8dcb06
--- /dev/null
+++ b/packages/cli/src/api.test.ts
@@ -0,0 +1,482 @@
+import { afterEach, beforeEach, describe, expect, it, vi, type MockInstance } from "vitest";
+import {
+ chmodSync,
+ existsSync,
+ mkdirSync,
+ mkdtempSync,
+ readFileSync,
+ readdirSync,
+ rmSync,
+ writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import * as pipeline from "./background-removal/pipeline.js";
+import * as manager from "./whisper/manager.js";
+import * as sherpa from "./whisper/sherpa.js";
+import * as whisper from "./whisper/transcribe.js";
+import {
+ RemoveBackgroundError,
+ TranscribeError,
+ removeBackground,
+ transcribe,
+ type TranscribeOptions,
+} from "./api.js";
+
+const SRT = `1
+00:00:01,000 --> 00:00:03,500
+Write HTML.
+
+2
+00:00:03,500 --> 00:00:06,000
+Render video. Built for agents.
+`;
+
+let dir: string;
+let transcribeMock: MockInstance<typeof whisper.transcribe>;
+let renderMock: MockInstance<typeof pipeline.render>;
+beforeEach(() => {
+ dir = mkdtempSync(join(tmpdir(), "hf-api-test-"));
+ transcribeMock = vi.spyOn(whisper, "transcribe");
+ renderMock = vi.spyOn(pipeline, "render");
+ // Parakeet runs on parakeet-mlx in these tests, whatever this machine has installed.
+ vi.spyOn(sherpa, "sherpaParakeetInstalled").mockReturnValue(false);
+ vi.spyOn(console, "log");
+ vi.spyOn(console, "error");
+});
+afterEach(() => {
+ // The API never prints: that is the CLI's job.
+ expect(console.log).not.toHaveBeenCalled();
+ expect(console.error).not.toHaveBeenCalled();
+ vi.restoreAllMocks();
+ vi.unstubAllEnvs();
+ rmSync(dir, { recursive: true, force: true });
+});
+
+function dummyAudio(): string {
+ const input = join(dir, "narration.wav");
+ writeFileSync(input, "not-real-audio");
+ return input;
+}
+
+/** What a whisper run leaves behind: a one-word transcript in the output folder. */
+function whisperResult(outputDir: string) {
+ const transcriptPath = join(outputDir, "transcript.json");
+ writeFileSync(transcriptPath, JSON.stringify([{ text: "hola", start: 0, end: 1 }]));
+ return {
+ model: "small.en",
+ detectedLanguage: "es",
+ transcriptPath,
+ wordCount: 1,
+ durationSeconds: 2,
+ speechOnsetSeconds: null,
+ };
+}
+
+async function transcribeError(options: Parameters<typeof transcribe>[0]) {
+ const err = await transcribe(options).catch((e: unknown) => e);
+ if (!(err instanceof TranscribeError)) throw new Error(`expected a TranscribeError, got ${err}`);
+ return err;
+}
+
+describe("transcribe", () => {
+ it("imports a transcript file into transcript.json", async () => {
+ const input = join(dir, "sample.srt");
+ writeFileSync(input, SRT);
+
+ const result = await transcribe({ input });
+
+ const transcriptPath = join(dir, "transcript.json");
+ expect(result).toEqual({ kind: "imported", format: "srt", wordCount: 2, transcriptPath });
+ expect(JSON.parse(readFileSync(transcriptPath, "utf8"))).toHaveLength(2);
+ });
+
+ it("writes only the caption file for a transcript input with captions", async () => {
+ const input = join(dir, "words.json");
+ writeFileSync(
+ input,
+ JSON.stringify([
+ { text: "Yes", start: 0, end: 1 },
+ { text: "No", start: 1, end: 2 },
+ ]),
+ );
+
+ const result = await transcribe({ input, captions: { format: "srt", preserveCues: true } });
+
+ const outputPath = join(dir, "transcript.srt");
+ expect(result).toEqual({ kind: "exported", format: "srt", wordCount: 2, outputPath });
+ expect(readFileSync(outputPath, "utf8")).toBe(
+ "1\n00:00:00,000 --> 00:00:01,000\nYes\n\n2\n00:00:01,000 --> 00:00:02,000\nNo\n",
+ );
+ expect(existsSync(join(dir, "transcript.json"))).toBe(false);
+ });
+
+ it("transcribes with whisper and hands back the runner, status and progress", async () => {
+ const input = dummyAudio();
+ transcribeMock.mockImplementation(async (_input, outputDir, options) => {
+ options?.onProgress?.("Checking model...");
+ options?.onEvent?.({
+ type: "progress",
+ phase: "transcription",
+ model: "small.en",
+ status: "started",
+ });
+ return whisperResult(outputDir);
+ });
+ const onEngine = vi.fn();
+ const onStatus = vi.fn();
+ const onProgress = vi.fn();
+
+ const result = await transcribe({
+ input,
+ engine: "whisper",
+ model: "small.en",
+ onEngine,
+ onStatus,
+ onProgress,
+ });
+
+ expect(result).toEqual({
+ kind: "transcribed",
+ engine: "whisper",
+ model: "small.en",
+ detectedLanguage: "es",
+ wordCount: 1,
+ durationSeconds: 2,
+ speechOnsetSeconds: null,
+ transcriptPath: join(dir, "transcript.json"),
+ });
+ expect(onEngine).toHaveBeenCalledExactlyOnceWith({
+ runner: "whisper",
+ engine: "whisper",
+ model: "small.en",
+ });
+ expect(onStatus).toHaveBeenCalledWith("Checking model...");
+ expect(onProgress).toHaveBeenCalledWith({
+ type: "progress",
+ phase: "transcription",
+ model: "small.en",
+ status: "started",
+ });
+ });
+
+ it("asks whisper for progress only when the caller listens for it", async () => {
+ // Whisper adds --print-progress whenever it gets an onEvent, so an unused one is not free.
+ const input = dummyAudio();
+ transcribeMock.mockImplementation(async (_input, outputDir) => whisperResult(outputDir));
+
+ await transcribe({ input, engine: "whisper" });
+
+ expect(transcribeMock.mock.calls[0]?.[2]).toMatchObject({
+ onEvent: undefined,
+ onProgress: undefined,
+ });
+ });
+
+ it("stops on the caller's AbortSignal without installing process signal handlers", async () => {
+ const input = dummyAudio();
+ const controller = new AbortController();
+ let handlersAdded = -1;
+ let signal: unknown;
+ transcribeMock.mockImplementation(async (_input, _outputDir, options) => {
+ const before = process.listenerCount("SIGINT");
+ signal = options?.startCancellation?.();
+ handlersAdded = process.listenerCount("SIGINT") - before;
+ controller.abort();
+ throw new Error("Command failed: whisper-cli");
+ });
+
+ const err = await transcribeError({ input, engine: "whisper", signal: controller.signal });
+
+ expect(err.code).toBe("cancelled");
+ expect(signal).toBe(controller.signal);
+ expect(handlersAdded).toBe(0);
+ });
+
+ it("names a missing whisper as whisper_unavailable, with the original error as cause", async () => {
+ const input = dummyAudio();
+ const missing = new manager.WhisperUnavailableError("whisper-cpp not found");
+ transcribeMock.mockRejectedValue(missing);
+
+ const err = await transcribeError({ input, engine: "whisper" });
+
+ expect(err.code).toBe("whisper_unavailable");
+ expect(err.cause).toBe(missing);
+ expect(err.install).toBeUndefined();
+ });
+
+ it("adds the ASR program's last stderr lines to a failure", async () => {
+ const input = dummyAudio();
+ const crash = Object.assign(new Error("Command failed: whisper-cli"), {
+ stderr: "loading model\nout of memory\n",
+ });
+ transcribeMock.mockRejectedValue(crash);
+
+ const err = await transcribeError({ input, engine: "whisper" });
+
+ expect(err.code).toBe("failed");
+ expect(err.message).toBe("Command failed: whisper-cli\nloading model\nout of memory");
+ expect(err.cause).toBe(crash);
+ });
+
+ it("reports the model whisper will run, not the English-only default", async () => {
+ const input = dummyAudio();
+ transcribeMock.mockImplementation(async (_input, outputDir) => whisperResult(outputDir));
+ const onEngine = vi.fn();
+
+ await transcribe({ input, engine: "whisper", language: "es", onEngine });
+
+ expect(onEngine).toHaveBeenCalledWith(expect.objectContaining({ model: "small" }));
+ });
+
+ it("throws at once for a signal that is already aborted, before any setup", async () => {
+ const input = dummyAudio();
+ const controller = new AbortController();
+ controller.abort();
+
+ const err = await transcribeError({ input, engine: "whisper", signal: controller.signal });
+
+ expect(err.code).toBe("cancelled");
+ expect(transcribeMock).not.toHaveBeenCalled();
+ });
+
+ it.skipIf(process.platform === "win32")(
+ "stops a running parakeet-mlx when the signal aborts",
+ async () => {
+ const pidFile = join(dir, "parakeet.pid");
+ const runner = join(dir, "parakeet-mlx");
+ writeFileSync(
+ runner,
+ `#!/bin/sh\n[ "$1" = --help ] && exit 0\necho $$ > "${pidFile}"\nexec sleep 30\n`,
+ );
+ chmodSync(runner, 0o755);
+ vi.stubEnv("HYPERFRAMES_PARAKEET", runner);
+ const controller = new AbortController();
+ const started = Date.now();
+ // Abort once the child is really running; a blocked event loop never gets this far.
+ const poll = setInterval(() => {
+ if (existsSync(pidFile) && readFileSync(pidFile, "utf8").trim()) controller.abort();
+ }, 20);
+
+ const err = await transcribeError({
+ input: dummyAudio(),
+ engine: "parakeet",
+ signal: controller.signal,
+ }).finally(() => clearInterval(poll));
+
+ expect(err.code).toBe("cancelled");
+ expect(Date.now() - started).toBeLessThan(10_000);
+ const pid = Number(readFileSync(pidFile, "utf8"));
+ expect(() => process.kill(pid, 0)).toThrow();
+ },
+ );
+
+ /** A stand-in tool that starts a process of its own, writes both pids, then waits for it. */
+ function hangingTool(path: string, pidFile: string, before = ""): void {
+ writeFileSync(path, `#!/bin/sh\n${before}sleep 15 &\necho "$$ $!" > "${pidFile}"\nwait\n`);
+ chmodSync(path, 0o755);
+ }
+
+ /** Aborts once the stand-in is running; a blocked event loop never gets to. */
+ async function abortWhileRunning(pidFile: string, options: Omit<TranscribeOptions, "signal">) {
+ const controller = new AbortController();
+ const poll = setInterval(() => {
+ if (existsSync(pidFile) && readFileSync(pidFile, "utf8").includes(" ")) controller.abort();
+ }, 20);
+ const started = Date.now();
+ const err = await transcribeError({ ...options, signal: controller.signal }).finally(() =>
+ clearInterval(poll),
+ );
+ const pids = readFileSync(pidFile, "utf8").trim().split(" ").map(Number);
+ return { err, elapsed: Date.now() - started, pids };
+ }
+
+ it.skipIf(process.platform === "win32")(
+ "stops a whisper runtime install in progress when the signal aborts",
+ async (ctx) => {
+ const bin = join(dir, "bin");
+ mkdirSync(bin);
+ const pidFile = join(dir, "install.pid");
+ // Homebrew on macOS, git clone elsewhere: whichever install step runs first never ends.
+ hangingTool(join(bin, "brew"), pidFile);
+ hangingTool(join(bin, "git"), pidFile);
+ writeFileSync(join(bin, "cmake"), "#!/bin/sh\nexit 1\n");
+ chmodSync(join(bin, "cmake"), 0o755);
+ vi.stubEnv("PATH", `${bin}:/usr/bin:/bin`);
+ vi.stubEnv("HYPERFRAMES_WHISPER_PATH", "");
+ if (manager.findWhisper()) ctx.skip();
+
+ const { err, elapsed, pids } = await abortWhileRunning(pidFile, {
+ input: dummyAudio(),
+ engine: "whisper",
+ });
+
+ expect(err.code).toBe("cancelled");
+ expect(elapsed).toBeLessThan(10_000);
+ for (const pid of pids) expect(() => process.kill(pid, 0), `pid ${pid}`).toThrow();
+ },
+ );
+
+ it.skipIf(process.platform === "win32")(
+ "stops ffmpeg preparing the audio when the signal aborts, and removes its partial WAV",
+ async () => {
+ vi.spyOn(manager, "ensureWhisper").mockResolvedValue({
+ executablePath: "/no/whisper-cli",
+ source: "system",
+ });
+ vi.spyOn(manager, "ensureModel").mockResolvedValue(join(dir, "ggml-small.en.bin"));
+ const ffmpeg = join(dir, "ffmpeg");
+ const pidFile = join(dir, "ffmpeg.pid");
+ hangingTool(ffmpeg, pidFile, 'for out; do :; done\nprintf partial > "$out"\n');
+ vi.stubEnv("HYPERFRAMES_FFMPEG_PATH", ffmpeg);
+ vi.stubEnv("HYPERFRAMES_FFPROBE_PATH", join(dir, "no-ffprobe"));
+ const input = join(dir, "narration.mp3");
+ writeFileSync(input, "not-real-audio");
+ const wavs = () =>
+ readdirSync(tmpdir()).filter((f) => f.startsWith(`hyperframes-audio-${process.pid}-`));
+
+ const { err, elapsed, pids } = await abortWhileRunning(pidFile, { input, engine: "whisper" });
+
+ expect(err.code).toBe("cancelled");
+ expect(elapsed).toBeLessThan(10_000);
+ for (const pid of pids) expect(() => process.kill(pid, 0), `pid ${pid}`).toThrow();
+ expect(wavs()).toEqual([]);
+ },
+ );
+
+ // Spelled so that this file's own source, which it also reads, does not match.
+ const localLoad = /\bimport\(|\bimport[OAM](?:riginal|ctual|ock)\b/;
+
+ it("keeps every module load at module scope, in the API, the code it runs and their tests", () => {
+ for (const sample of [
+ "await import" + "('x')",
+ "vi.import" + "Actual('x')",
+ "import" + "Original()",
+ ]) {
+ expect(sample).toMatch(localLoad);
+ }
+ const here = dirname(fileURLToPath(import.meta.url));
+ const api = readdirSync(join(here, "api")).map((f) => join("api", f));
+ const files = [
+ "api.ts",
+ ...api,
+ "api.test.ts",
+ "commands/remove-background.ts",
+ "commands/transcribe.ts",
+ "commands/transcribe.test.ts",
+ "utils/download.ts",
+ "utils/download.test.ts",
+ "utils/stoppableExecFile.ts",
+ "utils/stoppableExecFile.test.ts",
+ "whisper/manager.ts",
+ "whisper/modelForLanguage.ts",
+ "whisper/parakeet.ts",
+ "whisper/sherpa.ts",
+ "whisper/transcribe.ts",
+ "whisper/transcribe.test.ts",
+ "whisper/transcribe.signal.test.ts",
+ ];
+ for (const file of files) {
+ expect(readFileSync(join(here, file), "utf8"), file).not.toMatch(localLoad);
+ }
+ });
+
+ it.each([
+ ["a missing input", () => ({ input: join(dir, "missing.wav") }), "input_not_found"],
+ [
+ "a transcript with no words",
+ () => {
+ writeFileSync(join(dir, "empty.json"), "[]");
+ return { input: join(dir, "empty.json") };
+ },
+ "no_words",
+ ],
+ [
+ "a timeout below the minimum",
+ () => ({ input: dummyAudio(), timeoutMs: 100 }),
+ "invalid_timeout",
+ ],
+ ])("rejects %s before any engine runs", async (_case, options, code) => {
+ const err = await transcribeError(options());
+ expect(err.code).toBe(code);
+ expect(transcribeMock).not.toHaveBeenCalled();
+ });
+
+ it("rejects an unknown caption format from an untyped caller", async () => {
+ // @ts-expect-error -- plain JavaScript callers get no compile-time check.
+ const err = await transcribeError({ input: dummyAudio(), captions: { format: "txt" } });
+ expect(err).toMatchObject({
+ code: "invalid_option",
+ message: "Unsupported caption export format: txt. Use srt or vtt.",
+ });
+ expect(transcribeMock).not.toHaveBeenCalled();
+ });
+});
+
+describe("removeBackground", () => {
+ it("hands the pipeline absolute paths and returns its result", async () => {
+ const rendered = {
+ outputPath: resolve("cutout.webm"),
+ framesProcessed: 3,
+ durationSeconds: 1,
+ avgMsPerFrame: 10,
+ provider: "cpu",
+ format: "webm" as const,
+ };
+ renderMock.mockResolvedValue(rendered);
+ const onProgress = vi.fn();
+
+ const result = await removeBackground({
+ input: "avatar.mp4",
+ output: "cutout.webm",
+ device: "cpu",
+ quality: "fast",
+ onProgress,
+ });
+
+ expect(result).toBe(rendered);
+ expect(renderMock).toHaveBeenCalledExactlyOnceWith({
+ inputPath: resolve("avatar.mp4"),
+ outputPath: resolve("cutout.webm"),
+ backgroundOutputPath: undefined,
+ device: "cpu",
+ quality: "fast",
+ onProgress,
+ });
+ });
+
+ async function rejected(options: Parameters<typeof removeBackground>[0]) {
+ const err = await removeBackground(options).catch((e: unknown) => e);
+ expect(renderMock).not.toHaveBeenCalled();
+ return err;
+ }
+
+ it("rejects an unknown device or quality from an untyped caller", async () => {
+ const paths = { input: "avatar.mp4", output: "cutout.webm" };
+ // @ts-expect-error -- plain JavaScript callers get no compile-time check.
+ expect(await rejected({ ...paths, device: "gpu" })).toMatchObject({
+ name: "RemoveBackgroundError",
+ code: "invalid_option",
+ message: "Invalid device 'gpu'. Use: auto, cpu, coreml, cuda.",
+ });
+ // @ts-expect-error -- plain JavaScript callers get no compile-time check.
+ expect(await rejected({ ...paths, quality: "max" })).toMatchObject({
+ name: "RemoveBackgroundError",
+ code: "invalid_option",
+ message: "Invalid quality 'max'. Use: fast, balanced, best.",
+ });
+ });
+
+ it("wraps a pipeline failure, keeping its message and the original as cause", async () => {
+ const failure = new Error("ffmpeg and ffprobe are required.");
+ renderMock.mockRejectedValue(failure);
+
+ const err = await removeBackground({ input: "avatar.mp4", output: "cutout.webm" }).catch(
+ (e: unknown) => e,
+ );
+
+ expect(err).toBeInstanceOf(RemoveBackgroundError);
+ expect(err).toMatchObject({ code: "failed", message: failure.message, cause: failure });
+ });
+});
diff --git a/packages/cli/src/api.ts b/packages/cli/src/api.ts
new file mode 100644
index 0000000000..9815fa916f
--- /dev/null
+++ b/packages/cli/src/api.ts
@@ -0,0 +1,35 @@
+/**
+ * For HyperFrames' own apps; it may change between minor versions. Nothing here prints, reads
+ * argv or exits. Known failures throw TranscribeError or RemoveBackgroundError with a `code`.
+ */
+import { runTranscribe, type TranscribeOptions, type TranscribeResult } from "./api/transcribe.js";
+
+export {
+ MIN_TIMEOUT_MS,
+ TranscribeError,
+ type CaptionFormat,
+ type TranscribeCaptionsOptions,
+ type TranscribeEngine,
+ type TranscribeEngineEvent,
+ type TranscribeErrorCode,
+ type TranscribeOptions,
+ type TranscribeProgressEvent,
+ type TranscribeResult,
+ type TranscribeRunner,
+ type TranscriptFormat,
+} from "./api/transcribe.js";
+export {
+ RemoveBackgroundError,
+ removeBackground,
+ type RemoveBackgroundDevice,
+ type RemoveBackgroundErrorCode,
+ type RemoveBackgroundOptions,
+ type RemoveBackgroundProgress,
+ type RemoveBackgroundQuality,
+ type RemoveBackgroundResult,
+} from "./api/removeBackground.js";
+
+/** Transcribe media to `dir`/transcript.json, or import or export a transcript file. */
+export function transcribe(options: TranscribeOptions): Promise<TranscribeResult> {
+ return runTranscribe(options);
+}
diff --git a/packages/cli/src/api/removeBackground.ts b/packages/cli/src/api/removeBackground.ts
new file mode 100644
index 0000000000..b9a18b7714
--- /dev/null
+++ b/packages/cli/src/api/removeBackground.ts
@@ -0,0 +1,75 @@
+import { resolve } from "node:path";
+import { DEVICES, isDevice, type Device } from "../background-removal/manager.js";
+import {
+ QUALITIES,
+ isQuality,
+ render,
+ type ProgressEvent,
+ type Quality,
+ type RenderResult,
+} from "../background-removal/pipeline.js";
+
+export type RemoveBackgroundDevice = Device;
+export type RemoveBackgroundQuality = Quality;
+export type RemoveBackgroundProgress = ProgressEvent;
+export type RemoveBackgroundResult = RenderResult;
+
+export interface RemoveBackgroundOptions {
+ /** Video (.mp4/.mov/.webm/.mkv/.avi) or image (.jpg/.png/.webp). */
+ input: string;
+ /** Format from the extension: .webm (VP9 alpha), .mov (ProRes 4444) or .png (image input only). */
+ output: string;
+ /** Inverse-alpha background plate, .webm or .mov, video input only. Hole-cut, not inpainted. */
+ backgroundOutput?: string;
+ /** Default "auto". */
+ device?: RemoveBackgroundDevice;
+ /** Encoder preset for .webm output. Default "balanced". */
+ quality?: RemoveBackgroundQuality;
+ onProgress?: (event: RemoveBackgroundProgress) => void;
+}
+
+export type RemoveBackgroundErrorCode = "invalid_option" | "failed";
+
+export class RemoveBackgroundError extends Error {
+ readonly code: RemoveBackgroundErrorCode;
+
+ constructor(code: RemoveBackgroundErrorCode, message: string, options: { cause?: unknown } = {}) {
+ super(message, options.cause === undefined ? undefined : { cause: options.cause });
+ this.name = "RemoveBackgroundError";
+ this.code = code;
+ }
+}
+
+export async function removeBackground(
+ options: RemoveBackgroundOptions,
+): Promise<RemoveBackgroundResult> {
+ // Typed callers cannot get these wrong; plain JavaScript callers can.
+ const { device, quality } = options;
+ if (device !== undefined && !isDevice(device)) {
+ const valid = DEVICES.join(", ");
+ throw new RemoveBackgroundError("invalid_option", `Invalid device '${device}'. Use: ${valid}.`);
+ }
+ if (quality !== undefined && !isQuality(quality)) {
+ const valid = QUALITIES.join(", ");
+ throw new RemoveBackgroundError(
+ "invalid_option",
+ `Invalid quality '${quality}'. Use: ${valid}.`,
+ );
+ }
+
+ try {
+ return await render({
+ inputPath: resolve(options.input),
+ outputPath: resolve(options.output),
+ backgroundOutputPath: options.backgroundOutput
+ ? resolve(options.backgroundOutput)
+ : undefined,
+ device,
+ quality,
+ onProgress: options.onProgress,
+ });
+ } catch (err) {
+ const message = err instanceof Error ? err.message : String(err);
+ throw new RemoveBackgroundError("failed", message, { cause: err });
+ }
+}
diff --git a/packages/cli/src/api/transcribe.ts b/packages/cli/src/api/transcribe.ts
new file mode 100644
index 0000000000..b10e4c6ee9
--- /dev/null
+++ b/packages/cli/src/api/transcribe.ts
@@ -0,0 +1,515 @@
+import { existsSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, extname, join, resolve } from "node:path";
+import { normalizeErrorMessage } from "../utils/errorMessage.js";
+import {
+ createRenderCancellationScope,
+ stoppedByCancelSignal,
+} from "../utils/renderCancellation.js";
+import { DEFAULT_MODEL, isWhisperUnavailable } from "../whisper/manager.js";
+import { initialModelForLanguage } from "../whisper/modelForLanguage.js";
+import {
+ formatSrt,
+ formatVtt,
+ loadTranscript,
+ patchCaptionHtml,
+ type TranscriptFormat,
+ type Word,
+} from "../whisper/normalize.js";
+import {
+ PARAKEET_INSTALL_COMMAND,
+ PARAKEET_LANGUAGES,
+ parakeetSpeaks,
+ transcribeWithParakeet,
+} from "../whisper/parakeet.js";
+import { parakeetRunner, type ParakeetRunner } from "../whisper/parakeetRunner.js";
+import {
+ DecodeCancelled,
+ prepareSherpaWav,
+ sherpaUnsupportedReason,
+ transcribeWithSherpa,
+} from "../whisper/sherpa.js";
+import { TRANSCRIPT_FILE } from "../whisper/transcriptFile.js";
+import {
+ transcribe as transcribeWithWhisper,
+ type TranscribeProgress,
+} from "../whisper/transcribe.js";
+
+// Smallest accepted whisper timeout. Below it the whisper spawn has no realistic chance of
+// finishing even on the fastest hardware for the shortest clip.
+export const MIN_TIMEOUT_MS = 5000;
+
+export type TranscribeEngine = "auto" | "parakeet" | "whisper";
+export type CaptionFormat = "srt" | "vtt";
+/** The program that does the work: Parakeet runs on sherpa-onnx or parakeet-mlx. */
+export type TranscribeRunner = ParakeetRunner | "whisper";
+export type TranscribeProgressEvent = TranscribeProgress;
+export type { TranscriptFormat };
+
+export interface TranscribeCaptionsOptions {
+ format: CaptionFormat;
+ /** Default: `transcript.<format>` in `dir`. */
+ outputPath?: string;
+ /** Keep each transcript entry as its own cue instead of regrouping words. */
+ preserveCues?: boolean;
+}
+
+export interface TranscribeEngineEvent {
+ runner: TranscribeRunner;
+ engine: "parakeet" | "whisper";
+ /** The model whisper runs, after `language` picks the multilingual twin; whisper engine only. */
+ model: string;
+ /** Set when auto mode gave up on Parakeet and this runner takes over. */
+ fallbackReason?: string;
+}
+
+export interface TranscribeOptions {
+ /** Audio or video to transcribe, or a transcript (.json, .srt, .vtt) to import or export. */
+ input: string;
+ /** Where transcript.json goes; caption scripts in this folder's .html files are patched. Default: the input's folder. */
+ dir?: string;
+ /** Default "auto": Parakeet when installed and it covers `language`, else whisper. */
+ engine?: TranscribeEngine;
+ /** Whisper model. Parakeet has its own fixed model. */
+ model?: string;
+ language?: string;
+ /** Allow installing the whisper runtime. Model downloads are always allowed. */
+ installRuntime?: boolean;
+ /** Whisper spawn timeout, at least MIN_TIMEOUT_MS. Default: scaled to audio length and model. */
+ timeoutMs?: number;
+ /** Also write a caption file. With a transcript input, this is the only thing written. */
+ captions?: TranscribeCaptionsOptions;
+ /**
+ * Aborting it stops the run with a "cancelled" TranscribeError, ending any install, download,
+ * audio preparation or transcription at once. A tool lookup already running finishes first; each
+ * is capped at 10 seconds.
+ */
+ signal?: AbortSignal;
+ /** Downloads, transcription start and end, and words heard so far. */
+ onProgress?: (event: TranscribeProgressEvent) => void;
+ /** One-line status text, such as "Preparing audio...". */
+ onStatus?: (message: string) => void;
+ /** Called when a runner starts: once, and again if auto mode falls back from Parakeet. */
+ onEngine?: (event: TranscribeEngineEvent) => void;
+}
+
+export type TranscribeResult =
+ | {
+ kind: "transcribed";
+ engine: "parakeet" | "whisper";
+ model: string;
+ detectedLanguage: string | null;
+ wordCount: number;
+ durationSeconds: number;
+ speechOnsetSeconds: number | null;
+ transcriptPath: string;
+ captions?: { format: CaptionFormat; outputPath: string };
+ }
+ | { kind: "imported"; format: TranscriptFormat; wordCount: number; transcriptPath: string }
+ | { kind: "exported"; format: CaptionFormat; wordCount: number; outputPath: string };
+
+export type TranscribeErrorCode =
+ | "input_not_found"
+ | "invalid_option"
+ | "invalid_timeout"
+ | "invalid_transcript"
+ | "no_words"
+ | "parakeet_unavailable"
+ | "whisper_unavailable"
+ | "caption_write_failed"
+ | "cancelled"
+ | "failed";
+
+export class TranscribeError extends Error {
+ readonly code: TranscribeErrorCode;
+ /** whisper_unavailable: the command that installs Parakeet, when Parakeet would cover this run. */
+ readonly install?: string;
+ /** caption_write_failed after transcribing: the transcript, which was saved. */
+ readonly transcriptPath?: string;
+
+ constructor(
+ code: TranscribeErrorCode,
+ message: string,
+ options: { cause?: unknown; install?: string; transcriptPath?: string } = {},
+ ) {
+ super(message, options.cause === undefined ? undefined : { cause: options.cause });
+ this.name = "TranscribeError";
+ this.code = code;
+ if (options.install !== undefined) this.install = options.install;
+ if (options.transcriptPath !== undefined) this.transcriptPath = options.transcriptPath;
+ }
+}
+
+/**
+ * The CLI's form of TranscribeOptions: flag values arrive unchecked, and Ctrl-C stops the run
+ * through process signal handlers instead of an AbortSignal.
+ */
+export type TranscribeRequest = Omit<TranscribeOptions, "engine" | "captions"> & {
+ engine?: string;
+ captions?: Omit<TranscribeCaptionsOptions, "format"> & { format?: string };
+ stopOnProcessSignals?: boolean;
+};
+
+interface CaptionSidecar {
+ to: CaptionFormat;
+ outPath: string;
+ preserveCues: boolean;
+ /** Files the caption write must never replace: the input and the transcript. */
+ keep: string[];
+}
+
+interface CancellationScope {
+ signal: AbortSignal;
+ dispose: () => void;
+}
+
+export async function runTranscribe(options: TranscribeRequest): Promise<TranscribeResult> {
+ if (options.signal?.aborted) {
+ throw new TranscribeError("cancelled", "Transcription cancelled", {
+ cause: options.signal.reason,
+ });
+ }
+ const inputPath = resolve(options.input);
+ if (!existsSync(inputPath)) {
+ throw new TranscribeError("input_not_found", `File not found: ${options.input}`);
+ }
+
+ // Default to the directory containing the input file so transcript.json
+ // lands next to narration.wav regardless of where the command is run from.
+ const dir = resolve(options.dir ?? dirname(inputPath));
+ const ext = extname(inputPath).toLowerCase();
+ const isImport = ext === ".json" || ext === ".srt" || ext === ".vtt";
+ const sidecar = parseSidecar(options.captions, inputPath, dir);
+
+ if (sidecar && isImport) return exportTranscript(inputPath, sidecar);
+ if (isImport) return importTranscript(inputPath, dir);
+
+ const { timeoutMs } = options;
+ if (timeoutMs !== undefined && !(Number.isInteger(timeoutMs) && timeoutMs >= MIN_TIMEOUT_MS)) {
+ throw new TranscribeError(
+ "invalid_timeout",
+ `Invalid timeoutMs: ${timeoutMs}. Must be an integer >= ${MIN_TIMEOUT_MS} (ms).`,
+ );
+ }
+ return transcribeAudio(inputPath, dir, sidecar, options);
+}
+
+function parseExportFormat(value: string | undefined): CaptionFormat | undefined {
+ if (!value) return undefined;
+ const normalized = value.toLowerCase();
+ if (normalized === "srt" || normalized === "vtt") return normalized;
+ throw new TranscribeError(
+ "invalid_option",
+ `Unsupported caption export format: ${value}. Use srt or vtt.`,
+ );
+}
+
+function parseSidecar(
+ captions: TranscribeRequest["captions"],
+ inputPath: string,
+ dir: string,
+): CaptionSidecar | undefined {
+ const to = parseExportFormat(captions?.format);
+ if (!to) return undefined;
+ const output = captions?.outputPath;
+ const outPath = resolve(output ?? join(dir, `transcript.${to}`));
+ const keep = [inputPath, join(dir, TRANSCRIPT_FILE)];
+ const problem =
+ (output !== undefined && outputProblem(output, outPath, to)) || overwriteProblem(outPath, keep);
+ if (problem) throw new TranscribeError("invalid_option", problem);
+ return { to, outPath, preserveCues: captions?.preserveCues === true, keep };
+}
+
+/** Why an explicit --output cannot be used, checked before any transcription work. */
+function outputProblem(output: string, outPath: string, to: CaptionFormat): string | undefined {
+ if (!output) return "--output needs a file path";
+ const folder = dirname(outPath);
+ if (!existsSync(folder) || !statSync(folder).isDirectory()) {
+ return `Output folder not found: ${folder}`;
+ }
+ if (/[\\/]$/.test(output) || (existsSync(outPath) && statSync(outPath).isDirectory())) {
+ return `--output is a folder; give a file path such as ${join(outPath, `transcript.${to}`)}`;
+ }
+ return undefined;
+}
+
+/** Early refusal before the engine runs; the same check at write time is the owner. */
+function overwriteProblem(outPath: string, keep: string[]): string | undefined {
+ const hit = keep.find((file) => sameFile(outPath, file));
+ return hit && `The caption file would overwrite ${hit}; choose another file with --output`;
+}
+
+function sameFile(out: string, file: string): boolean {
+ if (existsSync(out) && existsSync(file)) {
+ const [a, b] = [statSync(out, { bigint: true }), statSync(file, { bigint: true })];
+ if (a.ino !== 0n && b.ino !== 0n) return a.dev === b.dev && a.ino === b.ino;
+ // Some network shares report inode 0, which proves nothing; let the OS resolve the paths.
+ return realpathSync.native(out) === realpathSync.native(file);
+ }
+ // Letter case is ignored so a case-insensitive disk cannot alias.
+ const realDir = (p: string) =>
+ existsSync(dirname(p)) ? realpathSync.native(dirname(p)) : dirname(p);
+ return (
+ realDir(out) === realDir(file) && basename(out).toLowerCase() === basename(file).toLowerCase()
+ );
+}
+
+// ---------------------------------------------------------------------------
+// Import and export existing transcripts
+// ---------------------------------------------------------------------------
+
+function readTranscript(inputPath: string): { words: Word[]; format: TranscriptFormat } {
+ let transcript: { words: Word[]; format: TranscriptFormat };
+ try {
+ transcript = loadTranscript(inputPath);
+ } catch (err) {
+ throw new TranscribeError("invalid_transcript", normalizeErrorMessage(err), { cause: err });
+ }
+ if (transcript.words.length === 0) {
+ throw new TranscribeError("no_words", "No words found in transcript.");
+ }
+ return transcript;
+}
+
+function importTranscript(inputPath: string, dir: string): TranscribeResult {
+ const { words, format } = readTranscript(inputPath);
+
+ const transcriptPath = join(dir, TRANSCRIPT_FILE);
+ writeFileSync(transcriptPath, JSON.stringify(words, null, 2));
+ patchCaptionHtml(dir, words);
+ return { kind: "imported", format, wordCount: words.length, transcriptPath };
+}
+
+function exportTranscript(inputPath: string, sidecar: CaptionSidecar): TranscribeResult {
+ const { words, format } = readTranscript(inputPath);
+ try {
+ writeCaptionSidecar(words, sidecar, format === "srt" || format === "vtt" || undefined);
+ } catch (err) {
+ throw new TranscribeError(
+ "caption_write_failed",
+ `The caption file ${sidecar.outPath} could not be written: ${normalizeErrorMessage(err)}`,
+ { cause: err },
+ );
+ }
+ return {
+ kind: "exported",
+ format: sidecar.to,
+ wordCount: words.length,
+ outputPath: sidecar.outPath,
+ };
+}
+
+function writeCaptionSidecar(
+ words: Word[],
+ { to, outPath, preserveCues, keep }: CaptionSidecar,
+ phraseLevelSource: boolean | undefined,
+): void {
+ // Checked at write time, when the transcript exists, so the OS resolves every link and alias.
+ const hit = keep.find((file) => sameFile(outPath, file));
+ if (hit) throw new Error(`it is the same file as ${hit}`);
+ // A .srt/.vtt source is already phrase-level; keep its cue boundaries 1:1.
+ // preserveCues forces the same for an already-cued transcript.json whose
+ // entries have no internal whitespace (single-word or CJK captions), which
+ // the automatic whitespace heuristic in wordsToCues can't detect.
+ const preGrouped = preserveCues || phraseLevelSource;
+ const content =
+ to === "srt" ? formatSrt(words, { preGrouped }) : formatVtt(words, { preGrouped });
+ writeFileSync(outPath, content);
+}
+
+// ---------------------------------------------------------------------------
+// Transcribe audio/video
+// ---------------------------------------------------------------------------
+
+/** auto and parakeet prefer sherpa-onnx, then parakeet-mlx, then whisper, in Parakeet's languages. */
+function pickRunner(
+ engine: string,
+ parakeet: () => ParakeetRunner | null,
+ language?: string,
+): TranscribeRunner {
+ if (engine === "whisper" || !parakeetSpeaks(language)) return "whisper";
+ return parakeet() ?? "whisper";
+}
+
+/** When Parakeet fails, only auto falls back; an explicit parakeet engine fails with the error. */
+const parakeetFallsBack = (engine: string) => engine === "auto";
+
+/** `.replace(/\.+$/, "")` in linear time; that regex is quadratic on a long run of dots. */
+function withoutTrailingDots(text: string): string {
+ let end = text.length;
+ while (end > 0 && text[end - 1] === ".") end--;
+ return text.slice(0, end);
+}
+
+const engineOf = (runner: TranscribeRunner) => (runner === "whisper" ? "whisper" : "parakeet");
+
+/** The ASR subprocess's last stderr lines, which execFileSync captures but otherwise drops. */
+function failureMessage(err: unknown): string {
+ const base = err instanceof Error ? err.message : String(err);
+ const stderr =
+ err && typeof err === "object" && "stderr" in err && err.stderr
+ ? String(err.stderr)
+ .trim()
+ .split("\n")
+ .slice(-3)
+ .filter((line) => !base.includes(line))
+ .join("\n")
+ : "";
+ return stderr ? `${base}\n${stderr}` : base;
+}
+
+// fallow-ignore-next-line complexity
+async function transcribeAudio(
+ inputPath: string,
+ dir: string,
+ sidecar: CaptionSidecar | undefined,
+ options: TranscribeRequest,
+): Promise<TranscribeResult> {
+ const engine = (options.engine ?? "auto").toLowerCase();
+ if (engine !== "auto" && engine !== "parakeet" && engine !== "whisper") {
+ throw new TranscribeError(
+ "invalid_option",
+ `Unknown --engine: ${options.engine}. Use auto, parakeet, or whisper.`,
+ );
+ }
+ const unsupported = sherpaUnsupportedReason();
+ let runner = pickRunner(engine, () => parakeetRunner({ unsupported }), options.language);
+ if (engine === "parakeet" && runner === "whisper") {
+ throw new TranscribeError(
+ "parakeet_unavailable",
+ !parakeetSpeaks(options.language)
+ ? `Parakeet does not transcribe --language ${options.language}; it covers ${PARAKEET_LANGUAGES.split(" ").join(", ")}. Use --engine whisper.`
+ : (unsupported ??
+ `Parakeet is not installed. Install it with: ${PARAKEET_INSTALL_COMMAND} (or use --engine whisper)`),
+ );
+ }
+
+ const model = options.model ?? DEFAULT_MODEL;
+ const whisperModel = initialModelForLanguage(model, options.language);
+ options.onEngine?.({ runner, engine: engineOf(runner), model: whisperModel });
+ const { onStatus, onProgress } = options;
+ const startScope = (): CancellationScope =>
+ options.stopOnProcessSignals
+ ? createRenderCancellationScope()
+ : { signal: options.signal ?? new AbortController().signal, dispose: () => {} };
+ let wavPath = inputPath;
+ // Before audio prep: under --json no spinner listens for SIGINT, so Ctrl-C would kill Node.
+ // A caller's own signal is live from the start, whichever runner it ends up stopping.
+ let cancellation = runner === "sherpa" || !options.stopOnProcessSignals ? startScope() : null;
+ // The CLI's own handlers stop it; its setup, audio prep and parakeet-mlx stay synchronous.
+ const librarySignal = options.stopOnProcessSignals ? undefined : cancellation?.signal;
+ const run = (r: TranscribeRunner) => {
+ switch (r) {
+ case "sherpa":
+ return transcribeWithSherpa(wavPath, dir, {
+ onProgress: onStatus,
+ onEvent: onProgress,
+ signal: cancellation!.signal,
+ });
+ case "parakeet-mlx":
+ return transcribeWithParakeet(wavPath, dir, {
+ onProgress: onStatus,
+ onEvent: onProgress,
+ signal: librarySignal,
+ });
+ case "whisper":
+ return transcribeWithWhisper(wavPath, dir, {
+ model,
+ language: options.language,
+ onProgress: onStatus,
+ onEvent: onProgress,
+ timeoutMs: options.timeoutMs,
+ installRuntime: options.installRuntime,
+ signal: librarySignal,
+ startCancellation: () => (cancellation ??= startScope()).signal,
+ });
+ 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.
+ if (runner === "sherpa") {
+ wavPath = await prepareSherpaWav(inputPath, onStatus, librarySignal);
+ }
+ let result: Awaited<ReturnType<typeof run>>;
+ try {
+ result = await run(runner);
+ } catch (err) {
+ if (runner !== "sherpa" || err instanceof DecodeCancelled) throw err;
+ const reason = withoutTrailingDots(normalizeErrorMessage(err));
+ const parakeetError = `Parakeet failed: ${reason}. To repair it, run: ${PARAKEET_INSTALL_COMMAND}`;
+ if (!parakeetFallsBack(engine)) throw new Error(parakeetError);
+ runner = pickRunner(
+ engine,
+ () => parakeetRunner({ unsupported, skipSherpa: true }),
+ options.language,
+ );
+ options.onEngine?.({
+ runner,
+ engine: engineOf(runner),
+ model: whisperModel,
+ fallbackReason: parakeetError,
+ });
+ try {
+ result = await run(runner);
+ } catch (fallbackErr) {
+ // Ctrl-C reaches whisper too, so it can stop on its own signal before the scope aborts it.
+ if (stoppedByCancelSignal(fallbackErr as { signal?: string })) {
+ throw new DecodeCancelled("Transcription cancelled");
+ }
+ const why = normalizeErrorMessage(fallbackErr);
+ throw new Error(`${parakeetError}. The ${runner} fallback failed too: ${why}`);
+ }
+ }
+
+ const { words } = loadTranscript(result.transcriptPath);
+
+ writeFileSync(result.transcriptPath, JSON.stringify(words, null, 2));
+ patchCaptionHtml(dir, words);
+ if (sidecar) {
+ try {
+ writeCaptionSidecar(words, sidecar, false);
+ } catch (err) {
+ throw new TranscribeError(
+ "caption_write_failed",
+ `Transcript saved to ${result.transcriptPath}, but the caption file ${sidecar.outPath} could not be written: ${normalizeErrorMessage(err)}`,
+ { cause: err, transcriptPath: result.transcriptPath },
+ );
+ }
+ }
+
+ return {
+ kind: "transcribed",
+ engine: engineOf(runner),
+ model: result.model,
+ detectedLanguage: result.detectedLanguage,
+ wordCount: words.length,
+ durationSeconds: result.durationSeconds,
+ speechOnsetSeconds: result.speechOnsetSeconds,
+ transcriptPath: result.transcriptPath,
+ ...(sidecar && { captions: { format: sidecar.to, outputPath: sidecar.outPath } }),
+ };
+ } catch (err) {
+ if (err instanceof TranscribeError) throw err;
+ if (err instanceof DecodeCancelled || cancellation?.signal.aborted) {
+ throw new TranscribeError("cancelled", "Transcription cancelled", { cause: err });
+ }
+ const message = failureMessage(err);
+ // whisper-cpp is an optional prerequisite, not part of the CLI. When it is simply
+ // unavailable (no binary, no toolchain to build one), that is a setup condition.
+ if (isWhisperUnavailable(err)) {
+ const install =
+ engine === "auto" && parakeetSpeaks(options.language) && !unsupported
+ ? PARAKEET_INSTALL_COMMAND
+ : undefined;
+ throw new TranscribeError("whisper_unavailable", message, { cause: err, install });
+ }
+ throw new TranscribeError("failed", message, { cause: err });
+ } finally {
+ cancellation?.dispose();
+ if (wavPath !== inputPath) rmSync(wavPath, { force: true });
+ }
+}
diff --git a/packages/cli/src/commands/remove-background.ts b/packages/cli/src/commands/remove-background.ts
index 65a627ace3..7d0d5fd50f 100644
--- a/packages/cli/src/commands/remove-background.ts
+++ b/packages/cli/src/commands/remove-background.ts
@@ -1,12 +1,20 @@
import { failCommand } from "../utils/commandResult.js";
import { defineCommand } from "citty";
-import { resolve } from "node:path";
import { existsSync } from "node:fs";
import * as clack from "@clack/prompts";
import { c } from "../ui/colors.js";
-import { isDevice, DEVICES } from "../background-removal/manager.js";
+import {
+ DEFAULT_MODEL,
+ DEVICES,
+ MODEL_MEMORY_MB,
+ isDevice,
+ listAvailableProviders,
+ modelPath,
+ selectProviders,
+} from "../background-removal/manager.js";
import { DEFAULT_QUALITY, QUALITIES, isQuality } from "../background-removal/pipeline.js";
import type { Example } from "./_examples.js";
+import { RemoveBackgroundError, removeBackground } from "../api/removeBackground.js";
export const examples: Example[] = [
[
@@ -113,21 +121,14 @@ export default defineCommand({
failCommand();
}
- const inputPath = resolve(args.input);
- const outputPath = resolve(args.output);
- const backgroundOutputArg = args["background-output"];
- const backgroundOutputPath = backgroundOutputArg ? resolve(backgroundOutputArg) : undefined;
-
- const { render } = await import("../background-removal/pipeline.js");
-
const spin = args.json ? null : clack.spinner();
spin?.start("Preparing background-removal pipeline...");
try {
- const result = await render({
- inputPath,
- outputPath,
- backgroundOutputPath,
+ const result = await removeBackground({
+ input: args.input,
+ output: args.output,
+ backgroundOutput: args["background-output"],
device: args.device,
quality: args.quality,
onProgress: (event) => {
@@ -181,15 +182,17 @@ export default defineCommand({
} else {
spin?.stop(c.error(`Background removal failed: ${message}`));
}
- failCommand(1, err);
+ failCommand(1, pipelineError(err));
}
},
});
-async function showInfo(json: boolean): Promise<void> {
- const { selectProviders, listAvailableProviders, DEFAULT_MODEL, MODEL_MEMORY_MB, modelPath } =
- await import("../background-removal/manager.js");
+/** The pipeline's own error, which the command reported before the API wrapped it. */
+function pipelineError(err: unknown): unknown {
+ return err instanceof RemoveBackgroundError ? err.cause : err;
+}
+async function showInfo(json: boolean): Promise<void> {
const providers = listAvailableProviders();
const auto = selectProviders("auto");
const cached = existsSync(modelPath());
diff --git a/packages/cli/src/commands/transcribe.test.ts b/packages/cli/src/commands/transcribe.test.ts
index 2a169869b3..4a8b98e135 100644
--- a/packages/cli/src/commands/transcribe.test.ts
+++ b/packages/cli/src/commands/transcribe.test.ts
@@ -1,5 +1,7 @@
import { runCommand } from "citty";
import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import childProcess from "node:child_process";
+import fs from "node:fs";
import {
chmodSync,
mkdirSync,
@@ -13,65 +15,58 @@ import {
symlinkSync,
} from "node:fs";
import { basename, dirname, join } from "node:path";
+import { syncBuiltinESMExports } from "node:module";
import { tmpdir } from "node:os";
import { pathToFileURL } from "node:url";
import { WhisperUnavailableError } from "../whisper/manager.js";
import { formatVtt, loadTranscript } from "../whisper/normalize.js";
+import * as parakeet from "../whisper/parakeet.js";
+import * as sherpa from "../whisper/sherpa.js";
+import * as whisper from "../whisper/transcribe.js";
import { CliRuntimeError, consumeCommandResult } from "../utils/commandResult.js";
+import transcribeCmd from "./transcribe.js";
// Make the whisper core report "unavailable" so we exercise the soft-skip path.
const transcribeMock = vi.fn();
const prepareWavMock = vi.fn((input: string) => input);
let audioSeconds = 1;
-vi.mock("node:fs", async (importOriginal) => {
- const fs = await importOriginal<typeof import("node:fs")>();
- return { ...fs, statSync: vi.fn(fs.statSync) };
-});
-
-vi.mock("../whisper/transcribe.js", () => ({
- transcribe: transcribeMock,
- prepareWav: (input: string) => prepareWavMock(input),
- getPreparedWavDurationSeconds: () => audioSeconds,
-}));
// Engine selection: which runners look installed, and the sherpa decode child it spawns.
const runners = { sherpa: false, mlx: false };
let runtimeDir: string;
-vi.mock("../whisper/sherpa.js", async (importOriginal) => {
- const sherpa = await importOriginal<typeof import("../whisper/sherpa.js")>();
- return {
- ...sherpa,
- sherpaParakeetInstalled: () => runners.sherpa,
- transcribeWithSherpa: (
- wavPath: string,
- dir: string,
- options: Parameters<typeof sherpa.transcribeWithSherpa>[2],
- ) =>
- sherpa.transcribeWithSherpa(wavPath, dir, {
- ...options,
- runtimeDir,
- cliUrl: pathToFileURL(join(runtimeDir, "dist", "cli.js")).href,
- }),
- };
-});
+const realTranscribeWithSherpa = sherpa.transcribeWithSherpa;
+const realTranscribeWithParakeet = parakeet.transcribeWithParakeet;
+const realPrepareWav = whisper.prepareWav;
const mlxMock = vi.fn();
-vi.mock("../whisper/parakeet.js", async (importOriginal) => ({
- ...(await importOriginal<typeof import("../whisper/parakeet.js")>()),
- findParakeet: () => (runners.mlx ? "/bin/parakeet-mlx" : undefined),
- transcribeWithParakeet: (...a: unknown[]) => mlxMock(...a),
-}));
const execFileMock = vi.fn();
-vi.mock("node:child_process", async (importOriginal) => ({
- ...(await importOriginal<typeof import("node:child_process")>()),
- execFile: (...a: unknown[]) => execFileMock(...a),
-}));
const trackTranscribeUnavailable = vi.fn();
vi.mock("../telemetry/events.js", () => ({
trackTranscribeUnavailable: (...a: unknown[]) => trackTranscribeUnavailable(...a),
}));
-import transcribeCmd from "./transcribe.js";
+/** The runners the command reaches, replaced for each test because afterEach restores every spy. */
+function replaceRunners(): void {
+ vi.spyOn(whisper, "transcribe").mockImplementation((...a) => transcribeMock(...a));
+ vi.spyOn(whisper, "prepareWav").mockImplementation(async (input) => prepareWavMock(input));
+ vi.spyOn(whisper, "getPreparedWavDurationSeconds").mockImplementation(() => audioSeconds);
+ vi.spyOn(sherpa, "sherpaParakeetInstalled").mockImplementation(() => runners.sherpa);
+ vi.spyOn(sherpa, "transcribeWithSherpa").mockImplementation((wavPath, dir, options) =>
+ realTranscribeWithSherpa(wavPath, dir, {
+ ...options,
+ runtimeDir,
+ cliUrl: pathToFileURL(join(runtimeDir, "dist", "cli.js")).href,
+ }),
+ );
+ vi.spyOn(parakeet, "findParakeet").mockImplementation(() =>
+ runners.mlx ? "/bin/parakeet-mlx" : undefined,
+ );
+ vi.spyOn(parakeet, "transcribeWithParakeet").mockImplementation((...a) => mlxMock(...a));
+ vi.spyOn(childProcess, "execFile").mockImplementation(((...a: unknown[]) =>
+ execFileMock(...a)) as unknown as typeof childProcess.execFile);
+ // Node's named exports of a builtin follow its default export only once synced.
+ syncBuiltinESMExports();
+}
/** Makes each runner write a one-word transcript naming itself. */
function fakeTranscript(dir: string, text: string) {
@@ -103,6 +98,7 @@ describe("transcribe command", () => {
beforeEach(() => {
dirs = [];
consumeCommandResult();
+ replaceRunners();
transcribeMock.mockReset();
prepareWavMock.mockReset().mockImplementation((input: string) => input);
trackTranscribeUnavailable.mockReset();
@@ -118,6 +114,7 @@ describe("transcribe command", () => {
consumeCommandResult();
for (const d of dirs) rmSync(d, { recursive: true, force: true });
vi.restoreAllMocks();
+ syncBuiltinESMExports();
vi.unstubAllEnvs();
});
@@ -297,8 +294,6 @@ describe("transcribe command", () => {
it.skipIf(process.platform === "win32")(
"lets parakeet-mlx detect the language itself, since it has no --language option",
async () => {
- const parakeet =
- await vi.importActual<typeof import("../whisper/parakeet.js")>("../whisper/parakeet.js");
// Rejects --language the way parakeet-mlx does, and writes one token otherwise.
const runner = join(runtimeDir, "parakeet-mlx");
writeFileSync(
@@ -313,7 +308,7 @@ echo '{"sentences":[{"tokens":[{"text":" hola","start":0,"end":1}]}]}' > "$2/$(b
);
chmodSync(runner, 0o755);
vi.stubEnv("HYPERFRAMES_PARAKEET", runner);
- mlxMock.mockImplementation(parakeet.transcribeWithParakeet);
+ mlxMock.mockImplementation(realTranscribeWithParakeet);
expect(await transcribeWith("auto", { sherpa: false, mlx: true }, "es")).toMatchObject({
engine: "parakeet",
@@ -514,10 +509,7 @@ echo '{"sentences":[{"tokens":[{"text":" hola","start":0,"end":1}]}]}' > "$2/$(b
"ffmpeg failed: Error opening output files: Invalid argument\nOutput file does not contain any stream",
],
])("after saying %j, the run exits %i", async (said, code, error) => {
- const actual = await vi.importActual<typeof import("../whisper/transcribe.js")>(
- "../whisper/transcribe.js",
- );
- prepareWavMock.mockImplementation((input: string) => actual.prepareWav(input));
+ vi.mocked(whisper.prepareWav).mockImplementation(realPrepareWav);
const dir = mkdtempSync(join(tmpdir(), "hf-transcribe-ffmpeg-"));
dirs.push(dir);
const ffmpeg = join(dir, "ffmpeg");
@@ -837,11 +829,12 @@ Render video. Built for agents.
});
async function runWithInodeZero(zero: (path: string) => boolean, args: object): Promise<void> {
- const fs = await vi.importActual<typeof import("node:fs")>("node:fs");
- vi.mocked(statSync).mockImplementation(((path: string, options?: object) => {
- const stats = fs.statSync(path, options);
+ const realStatSync = fs.statSync;
+ vi.spyOn(fs, "statSync").mockImplementation(((path: string, options?: object) => {
+ const stats = realStatSync(path, options);
return zero(String(path)) ? Object.assign(stats, { ino: 0n }) : stats;
}) as unknown as typeof statSync);
+ syncBuiltinESMExports();
transcribeMock.mockImplementation(async (_input, outputDir) =>
fakeTranscript(outputDir, "whisper"),
);
@@ -850,7 +843,8 @@ Render video. Built for agents.
} catch (err) {
if (!(err instanceof CliRuntimeError)) throw err;
} finally {
- vi.mocked(statSync).mockImplementation(fs.statSync);
+ vi.mocked(fs.statSync).mockRestore();
+ syncBuiltinESMExports();
}
}
diff --git a/packages/cli/src/commands/transcribe.ts b/packages/cli/src/commands/transcribe.ts
index 5bfe97fb61..6c12eb08f5 100644
--- a/packages/cli/src/commands/transcribe.ts
+++ b/packages/cli/src/commands/transcribe.ts
@@ -1,25 +1,19 @@
import { createProgressWriter } from "../whisper/progress.js";
import { failCommand, setCommandExitCode } from "../utils/commandResult.js";
-import { normalizeErrorMessage } from "../utils/errorMessage.js";
-// fallow-ignore-file code-duplication
import { defineCommand } from "citty";
import type { Example } from "./_examples.js";
-import { existsSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import * as clack from "@clack/prompts";
+import { c } from "../ui/colors.js";
+import { DEFAULT_MODEL } from "../whisper/manager.js";
+import { trackTranscribeUnavailable } from "../telemetry/events.js";
import {
- PARAKEET_INSTALL_COMMAND,
- PARAKEET_LANGUAGES,
- parakeetSpeaks,
- transcribeWithParakeet,
-} from "../whisper/parakeet.js";
-
-type CaptionExportFormat = "srt" | "vtt";
-type CaptionSidecar = {
- to: CaptionExportFormat;
- outPath: string;
- preserveCues: boolean;
- /** Files the caption write must never replace: the input and the transcript. */
- keep: string[];
-};
+ MIN_TIMEOUT_MS,
+ TranscribeError,
+ runTranscribe,
+ type CaptionFormat,
+ type TranscribeEngineEvent,
+ type TranscribeResult,
+} from "../api/transcribe.js";
export const examples: Example[] = [
["Transcribe an audio file", "hyperframes transcribe audio.mp3"],
@@ -35,22 +29,6 @@ export const examples: Example[] = [
"hyperframes transcribe transcript.json --to vtt --preserve-cues",
],
];
-import { resolve, join, extname, dirname, basename } from "node:path";
-import * as clack from "@clack/prompts";
-import { c } from "../ui/colors.js";
-import { DEFAULT_MODEL, isWhisperUnavailable } from "../whisper/manager.js";
-import { TRANSCRIPT_FILE } from "../whisper/transcriptFile.js";
-import type { Word } from "../whisper/normalize.js";
-import type { ParakeetRunner } from "../whisper/parakeetRunner.js";
-
-// Minimum accepted value for `--timeout` / `HYPERFRAMES_TRANSCRIBE_TIMEOUT_MS`.
-// Kept out of `whisper/transcribe.ts` (avoids a top-level import into this
-// command module) so the CLI test file can hoist its
-// `vi.mock("../whisper/transcribe.js")` factory without the mocked module
-// entering the sync-import graph. Below this floor the whisper spawn has no
-// realistic chance of completing even on the fastest hardware for the shortest clip.
-const CLI_TIMEOUT_MIN_MS = 5000;
-import { trackTranscribeUnavailable } from "../telemetry/events.js";
export default defineCommand({
meta: {
@@ -132,68 +110,81 @@ export default defineCommand({
},
},
async run({ args }) {
- const inputPath = resolve(args.input);
- if (!existsSync(inputPath)) {
- const message = `File not found: ${args.input}`;
- console.error(c.error(message));
- failCommand(1, message);
- }
-
- // Default to the directory containing the input file so transcript.json
- // lands next to narration.wav regardless of where the command is run from.
- // Explicit --dir overrides this (e.g. for import mode targeting a project dir).
- const dir = resolve(args.dir ?? dirname(inputPath));
- const ext = extname(inputPath).toLowerCase();
-
- // ── Import mode: convert existing transcript ──────────────────────────
- const isImport = ext === ".json" || ext === ".srt" || ext === ".vtt";
- const sidecar = parseSidecar(args, inputPath, dir);
-
- if (sidecar && isImport) {
- return exportTranscript(inputPath, sidecar, args.json);
- }
-
- if (isImport) {
- return importTranscript(inputPath, dir, args.json);
+ const { json } = args;
+ const ui: { spin: Spinner | null } = { spin: null };
+ let result: TranscribeResult;
+ try {
+ result = await runTranscribe({
+ input: args.input,
+ dir: args.dir,
+ engine: args.engine,
+ model: args.model,
+ language: args.language,
+ installRuntime: args["runtime-install"],
+ timeoutMs: readTimeout(args.timeout)?.ms,
+ captions: { format: args.to, outputPath: args.output, preserveCues: args["preserve-cues"] },
+ stopOnProcessSignals: true,
+ onStatus: json ? undefined : (message) => ui.spin?.message(message),
+ onProgress: json ? createProgressWriter(process.stderr) : undefined,
+ onEngine: (event) => {
+ ui.spin = showEngine(event, ui.spin, { json, model: args.model });
+ },
+ });
+ } catch (err) {
+ if (!(err instanceof TranscribeError)) throw err;
+ if (isRunFailure(err)) {
+ reportRunFailure(err, ui.spin, { json, optional: args.optional === true });
+ } else {
+ reportSetupFailure(err, json, args.timeout);
+ }
+ return;
}
-
- // ── Transcribe mode: run the ASR engine ──────────────────────────────
- const timeoutMs = parseTimeoutMs(args.timeout, args.json);
-
- return transcribeAudio(inputPath, dir, {
- engine: args.engine,
- model: args.model,
- language: args.language,
- json: args.json,
- optional: args.optional,
- installRuntime: args["runtime-install"],
- timeoutMs,
- sidecar,
- });
+ reportResult(result, json, ui.spin);
},
});
+type Spinner = ReturnType<typeof clack.spinner>;
+
/**
- * Resolve the whisper timeout override from `--timeout <ms>` or the
- * `HYPERFRAMES_TRANSCRIBE_TIMEOUT_MS` env var. The flag wins over env; both
- * paths share the same integer + minimum-5000ms validation so a bad value
- * fails loud instead of silently reverting to the auto-scaled default.
- * Returns `undefined` when neither source is set — the transcribe layer then
- * derives the timeout from audio duration and model factor.
+ * The whisper timeout override from `--timeout <ms>` or the
+ * `HYPERFRAMES_TRANSCRIBE_TIMEOUT_MS` env var. The flag wins over env. The
+ * transcribe layer rejects a value that is not an integer >= MIN_TIMEOUT_MS, at
+ * the point it would use it, so a bad value fails loud instead of silently
+ * reverting to the auto-scaled default. Undefined when neither source is set:
+ * the timeout then comes from audio duration and model factor.
*/
-function parseTimeoutMs(raw: string | undefined, json: boolean): number | undefined {
+function readTimeout(
+ raw: string | undefined,
+): { ms: number; source: string; origin: string } | undefined {
const source = raw ?? process.env["HYPERFRAMES_TRANSCRIBE_TIMEOUT_MS"];
if (source == null || source === "") return undefined;
+ const origin = raw != null ? "--timeout" : "HYPERFRAMES_TRANSCRIBE_TIMEOUT_MS";
+ return { ms: Number.parseInt(source, 10), source, origin };
+}
- const parsed = Number.parseInt(source, 10);
- if (!Number.isFinite(parsed) || parsed < CLI_TIMEOUT_MIN_MS) {
- const origin = raw != null ? "--timeout" : "HYPERFRAMES_TRANSCRIBE_TIMEOUT_MS";
- failWith(
- `Invalid ${origin}: "${source}". Must be an integer >= ${CLI_TIMEOUT_MIN_MS} (ms).`,
- json,
+/** Starts the spinner for a runner, or, after a Parakeet failure, says which runner takes over. */
+function showEngine(
+ event: TranscribeEngineEvent,
+ spin: Spinner | null,
+ opts: { json: boolean; model?: string },
+): Spinner | null {
+ // The requested model, as the spinner has always shown it; event.model is the one whisper runs.
+ const label = c.accent(event.runner === "whisper" ? (opts.model ?? DEFAULT_MODEL) : "Parakeet");
+ if (event.fallbackReason !== undefined) {
+ spin?.clear();
+ console.error(c.warn(`${event.fallbackReason}. Using ${event.runner} for this run.`));
+ spin?.start(`Transcribing with ${label}...`);
+ return spin;
+ }
+ // --model selects the whisper model only; Parakeet uses its own fixed model.
+ if (event.runner !== "whisper" && opts.model && !opts.json) {
+ console.error(
+ c.dim(` Note: --model applies to the whisper engine only; ignored under Parakeet.`),
);
}
- return parsed;
+ const started = opts.json ? null : clack.spinner();
+ started?.start(`Transcribing with ${label}...`);
+ return started;
}
function failWith(message: string, json: boolean): never {
@@ -205,398 +196,125 @@ function failWith(message: string, json: boolean): never {
failCommand(1, message);
}
-function parseExportFormat(
- value: string | undefined,
- json: boolean,
-): CaptionExportFormat | undefined {
- if (!value) return undefined;
- const normalized = value.toLowerCase();
- if (normalized === "srt" || normalized === "vtt") return normalized;
-
- failWith(`Unsupported caption export format: ${value}. Use srt or vtt.`, json);
-}
-
-function parseSidecar(
- args: { to?: string; output?: string; "preserve-cues": boolean; json: boolean },
- inputPath: string,
- dir: string,
-): CaptionSidecar | undefined {
- const to = parseExportFormat(args.to, args.json);
- if (!to) return undefined;
- const outPath = resolve(args.output ?? join(dir, `transcript.${to}`));
- const keep = [inputPath, join(dir, TRANSCRIPT_FILE)];
- const problem =
- (args.output !== undefined && outputProblem(args.output, outPath, to)) ||
- overwriteProblem(outPath, keep);
- if (problem) failWith(problem, args.json);
- return { to, outPath, preserveCues: args["preserve-cues"], keep };
+/** Failures once a runner has started, reported through its spinner. */
+function isRunFailure(err: TranscribeError): boolean {
+ if (err.code === "caption_write_failed") return err.transcriptPath !== undefined;
+ return err.code === "cancelled" || err.code === "whisper_unavailable" || err.code === "failed";
}
-/** Why an explicit --output cannot be used, checked before any transcription work. */
-function outputProblem(
- output: string,
- outPath: string,
- to: CaptionExportFormat,
-): string | undefined {
- if (!output) return "--output needs a file path";
- const folder = dirname(outPath);
- if (!existsSync(folder) || !statSync(folder).isDirectory()) {
- return `Output folder not found: ${folder}`;
+function reportSetupFailure(err: TranscribeError, json: boolean, timeoutFlag?: string): never {
+ if (err.code === "input_not_found") {
+ console.error(c.error(err.message));
+ failCommand(1, err.message);
}
- if (/[\\/]$/.test(output) || (existsSync(outPath) && statSync(outPath).isDirectory())) {
- return `--output is a folder; give a file path such as ${join(outPath, `transcript.${to}`)}`;
+ // An unreadable transcript file keeps failing the way it always has: with the parser's own error.
+ if (err.code === "invalid_transcript") throw err.cause;
+ const timeout = err.code === "invalid_timeout" ? readTimeout(timeoutFlag) : undefined;
+ if (timeout) {
+ failWith(
+ `Invalid ${timeout.origin}: "${timeout.source}". Must be an integer >= ${MIN_TIMEOUT_MS} (ms).`,
+ json,
+ );
}
- return undefined;
+ failWith(err.message, json);
}
-/** Early refusal before the engine runs; the same check at write time is the owner. */
-function overwriteProblem(outPath: string, keep: string[]): string | undefined {
- const hit = keep.find((file) => sameFile(outPath, file));
- return hit && `The caption file would overwrite ${hit}; choose another file with --output`;
-}
-
-function sameFile(out: string, file: string): boolean {
- if (existsSync(out) && existsSync(file)) {
- const [a, b] = [statSync(out, { bigint: true }), statSync(file, { bigint: true })];
- if (a.ino !== 0n && b.ino !== 0n) return a.dev === b.dev && a.ino === b.ino;
- // Some network shares report inode 0, which proves nothing; let the OS resolve the paths.
- return realpathSync.native(out) === realpathSync.native(file);
+function reportRunFailure(
+ err: TranscribeError,
+ spin: Spinner | null,
+ opts: { json: boolean; optional: boolean },
+): void {
+ if (err.code === "whisper_unavailable") return reportWhisperUnavailable(err, spin, opts);
+ if (err.code === "cancelled" || err.code === "caption_write_failed") {
+ if (opts.json) console.log(JSON.stringify({ ok: false, error: err.message }));
+ else spin?.stop(err.code === "cancelled" ? c.warn(err.message) : c.error(err.message));
+ setCommandExitCode(err.code === "cancelled" ? 130 : 1);
+ return;
}
- // Letter case is ignored so a case-insensitive disk cannot alias.
- const realDir = (p: string) =>
- existsSync(dirname(p)) ? realpathSync.native(dirname(p)) : dirname(p);
- return (
- realDir(out) === realDir(file) && basename(out).toLowerCase() === basename(file).toLowerCase()
- );
-}
-
-// ---------------------------------------------------------------------------
-// Import existing transcript
-// ---------------------------------------------------------------------------
-
-function exitNoWords(json: boolean): never {
- failWith("No words found in transcript.", json);
+ if (opts.json) {
+ console.log(JSON.stringify({ ok: false, error: err.message }));
+ } else {
+ spin?.stop(c.error(`Transcription failed: ${err.message}`));
+ }
+ failCommand(1, err.cause);
}
-async function importTranscript(inputPath: string, dir: string, json: boolean): Promise<void> {
- const { loadTranscript, patchCaptionHtml } = await import("../whisper/normalize.js");
- const { words, format } = loadTranscript(inputPath);
-
- if (words.length === 0) exitNoWords(json);
-
- const outPath = join(dir, TRANSCRIPT_FILE);
- writeFileSync(outPath, JSON.stringify(words, null, 2));
- patchCaptionHtml(dir, words);
-
- if (json) {
+// whisper-cpp is an optional prerequisite, not part of the CLI. When it is
+// simply unavailable (no binary, no toolchain to build one), that is a setup
+// condition, not a command crash — report it on its own metric so it does
+// not inflate the cli_error budget, and let `--optional` callers continue.
+function reportWhisperUnavailable(
+ err: TranscribeError,
+ spin: Spinner | null,
+ opts: { json: boolean; optional: boolean },
+): void {
+ trackTranscribeUnavailable({ optional: opts.optional });
+ const { install } = err;
+ if (opts.json) {
console.log(
- JSON.stringify({ ok: true, format, wordCount: words.length, transcriptPath: outPath }),
+ JSON.stringify({ ok: false, skipped: true, reason: "whisper_unavailable", install }),
);
} else {
- console.log(
- `${c.success("◇")} Imported ${c.accent(String(words.length))} words from ${c.accent(format)} format → ${c.accent("transcript.json")}`,
- );
+ const orParakeet = install ? `\nOr transcribe with Parakeet after: ${install}` : "";
+ spin?.stop(c.warn(`Captions skipped — ${err.message}${orParakeet}`));
}
+ // Optional callers (pipelines) treat a missing prerequisite as a clean
+ // skip; explicit runs still surface non-zero. Set the status and return
+ // rather than guarding a process.exit() on the flag.
+ setCommandExitCode(opts.optional ? 0 : 1);
}
-// ---------------------------------------------------------------------------
-// Export transcript sidecars
-// ---------------------------------------------------------------------------
-
-async function writeCaptionSidecar(
- words: Word[],
- { to, outPath, preserveCues, keep }: CaptionSidecar,
- phraseLevelSource: boolean | undefined,
-): Promise<void> {
- // Checked at write time, when the transcript exists, so the OS resolves every link and alias.
- const hit = keep.find((file) => sameFile(outPath, file));
- if (hit) throw new Error(`it is the same file as ${hit}`);
- const { formatSrt, formatVtt } = await import("../whisper/normalize.js");
- // A .srt/.vtt source is already phrase-level; keep its cue boundaries 1:1.
- // --preserve-cues forces the same for an already-cued transcript.json whose
- // entries have no internal whitespace (single-word or CJK captions), which
- // the automatic whitespace heuristic in wordsToCues can't detect.
- const preGrouped = preserveCues || phraseLevelSource;
- const content =
- to === "srt" ? formatSrt(words, { preGrouped }) : formatVtt(words, { preGrouped });
- writeFileSync(outPath, content);
-}
-
-function reportSidecar(to: CaptionExportFormat, wordCount: number, outPath: string): void {
+function reportSidecar(to: CaptionFormat, wordCount: number, outPath: string): void {
console.log(
`${c.success("◇")} Exported ${c.accent(String(wordCount))} words to ${c.accent(to.toUpperCase())} → ${c.accent(outPath)}`,
);
}
-async function exportTranscript(
- inputPath: string,
- sidecar: CaptionSidecar,
- json: boolean,
-): Promise<void> {
- const { loadTranscript } = await import("../whisper/normalize.js");
- const { words, format } = loadTranscript(inputPath);
-
- if (words.length === 0) exitNoWords(json);
+function reportResult(result: TranscribeResult, json: boolean, spin: Spinner | null): void {
+ if (result.kind === "imported") {
+ const { format, wordCount, transcriptPath } = result;
+ if (json) {
+ console.log(JSON.stringify({ ok: true, format, wordCount, transcriptPath }));
+ } else {
+ console.log(
+ `${c.success("◇")} Imported ${c.accent(String(wordCount))} words from ${c.accent(format)} format → ${c.accent("transcript.json")}`,
+ );
+ }
+ return;
+ }
- const { outPath } = sidecar;
- try {
- await writeCaptionSidecar(words, sidecar, format === "srt" || format === "vtt" || undefined);
- } catch (err) {
- failWith(
- `The caption file ${outPath} could not be written: ${normalizeErrorMessage(err)}`,
- json,
- );
+ if (result.kind === "exported") {
+ const { format, wordCount, outputPath } = result;
+ if (json) console.log(JSON.stringify({ ok: true, format, wordCount, outputPath }));
+ else reportSidecar(format, wordCount, outputPath);
+ return;
}
+ const { captions } = result;
if (json) {
console.log(
JSON.stringify({
ok: true,
- format: sidecar.to,
- wordCount: words.length,
- outputPath: outPath,
+ engine: result.engine,
+ model: result.model,
+ detectedLanguage: result.detectedLanguage,
+ wordCount: result.wordCount,
+ durationSeconds: result.durationSeconds,
+ speechOnsetSeconds: result.speechOnsetSeconds,
+ transcriptPath: result.transcriptPath,
+ ...captions,
}),
);
- } else {
- reportSidecar(sidecar.to, words.length, outPath);
- }
-}
-
-// ---------------------------------------------------------------------------
-// Transcribe audio/video with whisper
-// ---------------------------------------------------------------------------
-
-type Runner = ParakeetRunner | "whisper";
-
-/** auto and parakeet prefer sherpa-onnx, then parakeet-mlx, then whisper, in Parakeet's languages. */
-function pickRunner(
- engine: string,
- parakeet: () => ParakeetRunner | null,
- language?: string,
-): Runner {
- if (engine === "whisper" || !parakeetSpeaks(language)) return "whisper";
- return parakeet() ?? "whisper";
-}
-
-/** When Parakeet fails, only auto falls back; an explicit --engine parakeet fails with the error. */
-const parakeetFallsBack = (engine: string) => engine === "auto";
-
-// fallow-ignore-next-line complexity
-async function transcribeAudio(
- inputPath: string,
- dir: string,
- opts: {
- engine?: string;
- model?: string;
- language?: string;
- json?: boolean;
- optional?: boolean;
- installRuntime?: boolean;
- timeoutMs?: number;
- sidecar?: CaptionSidecar;
- },
-): Promise<void> {
- const { transcribe } = await import("../whisper/transcribe.js");
- const { loadTranscript, patchCaptionHtml } = await import("../whisper/normalize.js");
-
- const { DecodeCancelled, prepareSherpaWav, sherpaUnsupportedReason, transcribeWithSherpa } =
- await import("../whisper/sherpa.js");
- const { parakeetRunner } = await import("../whisper/parakeetRunner.js");
- const { createRenderCancellationScope, stoppedByCancelSignal } =
- await import("../utils/renderCancellation.js");
-
- const engine = (opts.engine ?? "auto").toLowerCase();
- if (engine !== "auto" && engine !== "parakeet" && engine !== "whisper") {
- failWith(`Unknown --engine: ${opts.engine}. Use auto, parakeet, or whisper.`, !!opts.json);
- }
- const unsupported = sherpaUnsupportedReason();
- let runner = pickRunner(engine, () => parakeetRunner({ unsupported }), opts.language);
- if (engine === "parakeet" && runner === "whisper") {
- failWith(
- !parakeetSpeaks(opts.language)
- ? `Parakeet does not transcribe --language ${opts.language}; it covers ${PARAKEET_LANGUAGES.split(" ").join(", ")}. Use --engine whisper.`
- : (unsupported ??
- `Parakeet is not installed. Install it with: ${PARAKEET_INSTALL_COMMAND} (or use --engine whisper)`),
- !!opts.json,
- );
- }
-
- const model = opts.model ?? DEFAULT_MODEL;
- // --model selects the whisper model only; Parakeet uses its own fixed model.
- if (runner !== "whisper" && opts.model && !opts.json) {
- console.error(
- c.dim(` Note: --model applies to the whisper engine only; ignored under Parakeet.`),
- );
- }
- const label = (r: Runner) => c.accent(r === "whisper" ? model : "Parakeet");
- 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.
- let cancellation = runner === "sherpa" ? createRenderCancellationScope() : null;
- const run = (r: Runner) => {
- switch (r) {
- case "sherpa":
- return transcribeWithSherpa(wavPath, dir, {
- onProgress,
- onEvent,
- signal: cancellation!.signal,
- });
- case "parakeet-mlx":
- return transcribeWithParakeet(wavPath, dir, {
- onProgress,
- onEvent,
- });
- case "whisper":
- return transcribe(wavPath, dir, {
- model,
- language: opts.language,
- onProgress,
- onEvent,
- timeoutMs: opts.timeoutMs,
- installRuntime: opts.installRuntime,
- startCancellation: () => (cancellation ??= createRenderCancellationScope()).signal,
- });
- 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.
- if (runner === "sherpa") wavPath = prepareSherpaWav(inputPath, onProgress);
- let result: Awaited<ReturnType<typeof run>>;
- try {
- result = await run(runner);
- } catch (err) {
- if (runner !== "sherpa" || err instanceof DecodeCancelled) throw err;
- const reason = normalizeErrorMessage(err).replace(/\.+$/, "");
- const parakeetError = `Parakeet failed: ${reason}. To repair it, run: ${PARAKEET_INSTALL_COMMAND}`;
- if (!parakeetFallsBack(engine)) throw new Error(parakeetError);
- runner = pickRunner(
- engine,
- () => parakeetRunner({ unsupported, skipSherpa: true }),
- opts.language,
- );
- spin?.clear();
- console.error(c.warn(`${parakeetError}. Using ${runner} for this run.`));
- spin?.start(`Transcribing with ${label(runner)}...`);
- try {
- result = await run(runner);
- } catch (fallbackErr) {
- // Ctrl-C reaches whisper too, so it can stop on its own signal before the scope aborts it.
- if (stoppedByCancelSignal(fallbackErr as { signal?: string })) {
- throw new DecodeCancelled("Transcription cancelled");
- }
- const why = normalizeErrorMessage(fallbackErr);
- throw new Error(`${parakeetError}. The ${runner} fallback failed too: ${why}`);
- }
- }
-
- const { words } = loadTranscript(result.transcriptPath);
-
- writeFileSync(result.transcriptPath, JSON.stringify(words, null, 2));
- patchCaptionHtml(dir, words);
- const { sidecar } = opts;
- if (sidecar) {
- try {
- await writeCaptionSidecar(words, sidecar, false);
- } catch (err) {
- const message = `Transcript saved to ${result.transcriptPath}, but the caption file ${sidecar.outPath} could not be written: ${normalizeErrorMessage(err)}`;
- if (opts.json) console.log(JSON.stringify({ ok: false, error: message }));
- else spin?.stop(c.error(message));
- setCommandExitCode(1);
- return;
- }
- }
- const exported = sidecar && { format: sidecar.to, outputPath: sidecar.outPath };
-
- if (opts.json) {
- console.log(
- JSON.stringify({
- ok: true,
- engine: runner === "whisper" ? "whisper" : "parakeet",
- model: result.model,
- detectedLanguage: result.detectedLanguage,
- wordCount: words.length,
- durationSeconds: result.durationSeconds,
- speechOnsetSeconds: result.speechOnsetSeconds,
- transcriptPath: result.transcriptPath,
- ...exported,
- }),
- );
- } else {
- const onsetNote =
- result.speechOnsetSeconds != null
- ? ` — speech detected at ${result.speechOnsetSeconds.toFixed(1)}s`
- : "";
- spin?.stop(
- c.success(
- `Transcribed ${c.accent(String(words.length))} words (${result.durationSeconds.toFixed(1)}s${onsetNote})`,
- ),
- );
- if (exported) reportSidecar(exported.format, words.length, exported.outputPath);
- }
- } catch (err) {
- if (err instanceof DecodeCancelled || cancellation?.signal.aborted) {
- const message = "Transcription cancelled";
- if (opts.json) console.log(JSON.stringify({ ok: false, error: message }));
- else spin?.stop(c.warn(message));
- setCommandExitCode(130);
- return;
- }
- // Surface the last few lines of the ASR subprocess's stderr, which
- // execFileSync captures but otherwise drops on the floor — that's where
- // parakeet-mlx / whisper report the actual failure cause.
- const base = err instanceof Error ? err.message : String(err);
- const stderr =
- err && typeof err === "object" && "stderr" in err && err.stderr
- ? String(err.stderr)
- .trim()
- .split("\n")
- .slice(-3)
- .filter((line) => !base.includes(line))
- .join("\n")
- : "";
- const message = stderr ? `${base}\n${stderr}` : base;
-
- // whisper-cpp is an optional prerequisite, not part of the CLI. When it is
- // simply unavailable (no binary, no toolchain to build one), that is a setup
- // condition, not a command crash — report it on its own metric so it does
- // not inflate the cli_error budget, and let `--optional` callers continue.
- if (isWhisperUnavailable(err)) {
- trackTranscribeUnavailable({ optional: opts.optional === true });
- const install =
- engine === "auto" && parakeetSpeaks(opts.language) && !unsupported
- ? PARAKEET_INSTALL_COMMAND
- : undefined;
- if (opts.json) {
- console.log(
- JSON.stringify({ ok: false, skipped: true, reason: "whisper_unavailable", install }),
- );
- } else {
- const orParakeet = install ? `\nOr transcribe with Parakeet after: ${install}` : "";
- spin?.stop(c.warn(`Captions skipped — ${message}${orParakeet}`));
- }
- // Optional callers (pipelines) treat a missing prerequisite as a clean
- // skip; explicit runs still surface non-zero. Set the status and return
- // rather than guarding a process.exit() on the flag.
- setCommandExitCode(opts.optional ? 0 : 1);
- return;
- }
-
- if (opts.json) {
- console.log(JSON.stringify({ ok: false, error: message }));
- } else {
- spin?.stop(c.error(`Transcription failed: ${message}`));
- }
- failCommand(1, err);
- } finally {
- cancellation?.dispose();
- if (wavPath !== inputPath) rmSync(wavPath, { force: true });
+ return;
}
+ const onsetNote =
+ result.speechOnsetSeconds != null
+ ? ` — speech detected at ${result.speechOnsetSeconds.toFixed(1)}s`
+ : "";
+ spin?.stop(
+ c.success(
+ `Transcribed ${c.accent(String(result.wordCount))} words (${result.durationSeconds.toFixed(1)}s${onsetNote})`,
+ ),
+ );
+ if (captions) reportSidecar(captions.format, result.wordCount, captions.outputPath);
}
diff --git a/packages/cli/src/utils/download.test.ts b/packages/cli/src/utils/download.test.ts
index 86248189cf..1214210a0f 100644
--- a/packages/cli/src/utils/download.test.ts
+++ b/packages/cli/src/utils/download.test.ts
@@ -1,7 +1,8 @@
import { randomUUID } from "node:crypto";
-import { ensureModel } from "../whisper/manager.js";
+import { MODELS_DIR, ensureModel } from "../whisper/manager.js";
import { EventEmitter } from "node:events";
-import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import fs, { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { syncBuiltinESMExports } from "node:module";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { PassThrough } from "node:stream";
@@ -10,16 +11,7 @@ import type { ClientRequest, IncomingMessage } from "node:http";
import { afterEach, describe, expect, it, vi } from "vitest";
import { downloadFile, REDIRECT_CODES, redirectTarget } from "./download.js";
-const { unlinkSyncMock } = vi.hoisted(() => ({
- unlinkSyncMock: vi.fn(),
-}));
-
vi.mock("node:https", () => ({ get: vi.fn() }));
-vi.mock("node:fs", async (importOriginal) => {
- const actual = await importOriginal<typeof import("node:fs")>();
- unlinkSyncMock.mockImplementation(actual.unlinkSync);
- return { ...actual, unlinkSync: unlinkSyncMock };
-});
const mockGet = vi.mocked(httpsGet);
const tempDirs: string[] = [];
@@ -51,10 +43,46 @@ function httpsResponse(
afterEach(() => {
vi.clearAllMocks();
+ vi.restoreAllMocks();
+ syncBuiltinESMExports();
for (const dir of tempDirs.splice(0)) rmSync(dir, { recursive: true, force: true });
});
describe("downloadFile", () => {
+ it("hands https.get the caller's signal, so aborting a model download removes the partial file", async () => {
+ let seen: AbortSignal | undefined;
+ mockGet.mockImplementation(((
+ _url: string,
+ options: { signal?: AbortSignal },
+ callback: (response: IncomingMessage) => void,
+ ) => {
+ seen = options.signal;
+ const response = Object.assign(new PassThrough(), { statusCode: 200, headers: {} });
+ const request = new EventEmitter() as ClientRequest;
+ request.setTimeout = vi.fn();
+ callback(response as unknown as IncomingMessage);
+ response.write("partial");
+ // What Node does with a request whose signal aborts.
+ options.signal?.addEventListener("abort", () =>
+ request.emit(
+ "error",
+ Object.assign(new Error("The operation was aborted"), { name: "AbortError" }),
+ ),
+ );
+ return request;
+ }) as unknown as typeof httpsGet);
+ const controller = new AbortController();
+ const model = `test-${randomUUID()}`;
+
+ const download = ensureModel(model, { signal: controller.signal });
+ await new Promise((resolve) => setImmediate(resolve));
+ controller.abort();
+
+ await expect(download).rejects.toThrow("The operation was aborted");
+ expect(seen).toBe(controller.signal);
+ expect(readdirSync(MODELS_DIR).filter((name) => name.includes(model))).toEqual([]);
+ });
+
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[] = [];
@@ -123,16 +151,18 @@ describe("downloadFile", () => {
});
it("rejects an idle response and removes the partial file", async () => {
- const actualFs = await vi.importActual<typeof import("node:fs")>("node:fs");
let responseClosed = false;
- unlinkSyncMock.mockImplementation((path) => {
+ const realUnlinkSync = fs.unlinkSync;
+ vi.spyOn(fs, "unlinkSync").mockImplementation((path) => {
if (!responseClosed) {
const error = new Error("file is locked");
Object.assign(error, { code: "EBUSY" });
throw error;
}
- actualFs.unlinkSync(path);
+ realUnlinkSync(path);
});
+ // Node's named exports of a builtin follow its default export only once synced.
+ syncBuiltinESMExports();
mockGet.mockImplementation(((_url: string, callback: (response: IncomingMessage) => void) => {
const response = new PassThrough() as PassThrough & {
diff --git a/packages/cli/src/utils/download.ts b/packages/cli/src/utils/download.ts
index 040818f858..b8911085b4 100644
--- a/packages/cli/src/utils/download.ts
+++ b/packages/cli/src/utils/download.ts
@@ -13,6 +13,8 @@ export interface DownloadOptions {
/** Reject before writing more than this many response bytes. */
maxBytes?: number;
onProgress?: (receivedBytes: number, totalBytes: number | null) => void;
+ /** Aborting it destroys the request and removes the partial file. */
+ signal?: AbortSignal;
}
/** Every redirect a host may reasonably answer with, not just the two we saw first. */
@@ -65,6 +67,14 @@ function measureDownload(options: DownloadOptions, contentLength: string | undef
return { stream, complete: () => options.onProgress?.(receivedBytes, totalBytes) };
}
+function getUrl(
+ url: string,
+ signal: AbortSignal | undefined,
+ onResponse: (res: IncomingMessage) => void,
+): ClientRequest {
+ return signal ? httpsGet(url, { signal }, onResponse) : httpsGet(url, onResponse);
+}
+
/**
* Download a file from a URL, following redirects.
* Uses atomic write (download to .tmp, rename on success) to prevent
@@ -93,7 +103,7 @@ export function downloadFile(
let requestError: Error | undefined;
let request: ClientRequest;
try {
- request = httpsGet(u, (res) => {
+ request = getUrl(u, options.signal, (res) => {
activeResponse = res;
if (res.statusCode && REDIRECT_CODES.has(res.statusCode)) {
const location = res.headers.location;
diff --git a/packages/cli/src/utils/stoppableExecFile.test.ts b/packages/cli/src/utils/stoppableExecFile.test.ts
new file mode 100644
index 0000000000..3433b4d13f
--- /dev/null
+++ b/packages/cli/src/utils/stoppableExecFile.test.ts
@@ -0,0 +1,137 @@
+import { execFileSync, type ExecFileSyncOptions } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { stoppableExecFile, type StoppableExecFileOptions } from "./stoppableExecFile.js";
+
+/** The error's own fields, comparable across two runs: no pid, and Buffers as text. */
+function fieldsOf(err: unknown): Record<string, unknown> {
+ const fields: Record<string, unknown> = {};
+ for (const [key, value] of Object.entries(err as object)) {
+ if (key === "pid") continue;
+ const text = (v: unknown) => (Buffer.isBuffer(v) ? `Buffer:${v.toString()}` : v);
+ fields[key] = value === err ? "<itself>" : Array.isArray(value) ? value.map(text) : text(value);
+ }
+ return { message: (err as Error).message, ...fields };
+}
+
+function syncFailure(file: string, args: string[], options: ExecFileSyncOptions): unknown {
+ try {
+ execFileSync(file, args, options);
+ } catch (err) {
+ return err;
+ }
+ throw new Error("execFileSync did not fail");
+}
+
+const node = process.execPath;
+
+describe("stoppableExecFile", () => {
+ it.each<[string, string[], Omit<StoppableExecFileOptions, "signal">]>([
+ [
+ "a failure with stderr",
+ ["-e", "process.stderr.write('boom'); process.exit(3)"],
+ { stdio: ["ignore", "pipe", "pipe"], timeout: 10_000 },
+ ],
+ [
+ "a failure with no stderr",
+ ["-e", "process.exit(4)"],
+ { stdio: ["ignore", "ignore", "pipe"], timeout: 10_000 },
+ ],
+ [
+ "a failure with every stream ignored",
+ ["-e", "process.exit(5)"],
+ { stdio: "ignore", timeout: 10_000 },
+ ],
+ [
+ "a child its own signal stops",
+ ["-e", "process.kill(process.pid, 'SIGTERM'); setTimeout(() => {}, 5000)"],
+ { stdio: ["pipe", "pipe", "pipe"], timeout: 10_000 },
+ ],
+ [
+ "a timeout",
+ ["-e", "setTimeout(() => {}, 5000)"],
+ { stdio: ["ignore", "ignore", "pipe"], timeout: 300 },
+ ],
+ [
+ "output over maxBuffer",
+ ["-e", "process.stderr.write('x'.repeat(3000)); setTimeout(() => {}, 5000)"],
+ { stdio: ["ignore", "ignore", "pipe"], timeout: 10_000, maxBuffer: 1000 },
+ ],
+ ])("with a signal, fails %s with the error execFileSync throws", async (_case, args, options) => {
+ const expected = syncFailure(node, args, options as ExecFileSyncOptions);
+ const { signal } = new AbortController();
+ const actual = await stoppableExecFile(node, args, { ...options, signal }).catch((e) => e);
+ expect(fieldsOf(actual)).toEqual(fieldsOf(expected));
+ });
+
+ it("with a signal, fails a missing program with the error execFileSync throws", async () => {
+ const options = { stdio: "ignore", timeout: 10_000 } as const;
+ const expected = syncFailure("/no/such/tool", ["a"], options);
+ const { signal } = new AbortController();
+ const actual = await stoppableExecFile("/no/such/tool", ["a"], { ...options, signal }).catch(
+ (e) => e,
+ );
+ expect(fieldsOf(actual)).toEqual(fieldsOf(expected));
+ });
+
+ it("without a signal, runs the child before it returns, as execFileSync does", () => {
+ const dir = mkdtempSync(join(tmpdir(), "hf-stoppable-exec-"));
+ const marker = join(dir, "ran");
+ try {
+ const script = `require("node:fs").writeFileSync(${JSON.stringify(marker)}, "")`;
+ void stoppableExecFile(node, ["-e", script], {
+ stdio: "ignore",
+ timeout: 10_000,
+ signal: undefined,
+ });
+ expect(existsSync(marker)).toBe(true);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ describe.skipIf(process.platform === "win32")("when the signal aborts", () => {
+ let dir: string;
+ afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+ it("ends the child and the process it started, then rejects with the reason", async () => {
+ dir = mkdtempSync(join(tmpdir(), "hf-stoppable-exec-"));
+ const pids = join(dir, "pids");
+ const script = join(dir, "tool.sh");
+ writeFileSync(script, `sleep 30 &\necho "$$ $!" > "${pids}"\nwait\n`);
+ const controller = new AbortController();
+ const reason = new Error("stopped by the caller");
+ const poll = setInterval(() => {
+ if (existsSync(pids) && readFileSync(pids, "utf8").includes(" ")) controller.abort(reason);
+ }, 20);
+ const started = Date.now();
+
+ const run = stoppableExecFile("/bin/sh", [script], {
+ stdio: ["ignore", "pipe", "pipe"],
+ timeout: 60_000,
+ signal: controller.signal,
+ }).finally(() => clearInterval(poll));
+
+ await expect(run).rejects.toBe(reason);
+ expect(Date.now() - started).toBeLessThan(10_000);
+ for (const pid of readFileSync(pids, "utf8").trim().split(" ").map(Number)) {
+ expect(() => process.kill(pid, 0), `pid ${pid}`).toThrow();
+ }
+ });
+
+ it("starts nothing for a signal that is already aborted", async () => {
+ dir = mkdtempSync(join(tmpdir(), "hf-stoppable-exec-"));
+ const marker = join(dir, "ran");
+ const reason = new Error("stopped before it began");
+ const run = stoppableExecFile("/bin/sh", ["-c", `touch "${marker}"`], {
+ stdio: "ignore",
+ timeout: 10_000,
+ signal: AbortSignal.abort(reason),
+ });
+ await expect(run).rejects.toBe(reason);
+ expect(existsSync(marker)).toBe(false);
+ });
+ });
+});
diff --git a/packages/cli/src/utils/stoppableExecFile.ts b/packages/cli/src/utils/stoppableExecFile.ts
new file mode 100644
index 0000000000..e39c8541ce
--- /dev/null
+++ b/packages/cli/src/utils/stoppableExecFile.ts
@@ -0,0 +1,114 @@
+import { execFileSync, spawn, type StdioOptions } from "node:child_process";
+import type { Readable } from "node:stream";
+import * as util from "node:util";
+import { terminateProcessTree } from "./processTree.js";
+
+export interface StoppableExecFileOptions {
+ stdio: StdioOptions;
+ timeout: number;
+ cwd?: string;
+ env?: NodeJS.ProcessEnv;
+ /** Per output stream, as in execFileSync, whose default this keeps. */
+ maxBuffer?: number;
+ /** Aborting it ends the child and every process it started, then rejects with the reason. */
+ signal: AbortSignal | undefined;
+}
+
+function syscallError(code: string, file: string, args: string[]): NodeJS.ErrnoException {
+ // Bun has no getSystemErrorMap, and the CLI's own tests run it under Bun.
+ const known = util.getSystemErrorMap?.() ?? new Map();
+ const errno = [...known].find(([, [name]]) => name === code)?.[0];
+ return Object.assign(new Error(`spawnSync ${file} ${code}`), {
+ errno,
+ code,
+ syscall: `spawnSync ${file}`,
+ path: file,
+ spawnargs: args,
+ });
+}
+
+/**
+ * execFileSync, stoppable: given a signal, the child runs off the event loop so the signal can end
+ * it, and a failure throws the error execFileSync throws. Without one it is execFileSync, which the
+ * CLI keeps, so its spinner draws exactly the frames it always has.
+ */
+export async function stoppableExecFile(
+ file: string,
+ args: string[],
+ options: StoppableExecFileOptions,
+): Promise<void> {
+ const { signal, ...syncOptions } = options;
+ if (!signal) {
+ execFileSync(file, args, syncOptions);
+ return;
+ }
+ signal.throwIfAborted();
+ const maxBuffer = options.maxBuffer ?? 1024 * 1024;
+ await new Promise<void>((resolve, reject) => {
+ const child = spawn(file, args, { cwd: options.cwd, env: options.env, stdio: options.stdio });
+ let failure: "ETIMEDOUT" | "ENOBUFS" | undefined;
+ const stopWith = (code: "ETIMEDOUT" | "ENOBUFS") => {
+ failure ??= code;
+ child.kill("SIGTERM");
+ };
+ const collect = (stream: Readable | null) => {
+ if (!stream) return null;
+ const chunks: Buffer[] = [];
+ let size = 0;
+ stream.on("data", (chunk: Buffer) => {
+ chunks.push(chunk);
+ size += chunk.length;
+ if (size > maxBuffer) stopWith("ENOBUFS");
+ });
+ return chunks;
+ };
+ const stdout = collect(child.stdout);
+ const stderr = collect(child.stderr);
+ child.stdin?.end();
+ const timer = setTimeout(() => stopWith("ETIMEDOUT"), options.timeout);
+ let stopping: Promise<unknown> | undefined;
+ const onAbort = () => {
+ if (child.pid === undefined) return;
+ stopping ??= terminateProcessTree(child.pid, { child }).catch(() => undefined);
+ };
+ signal.addEventListener("abort", onAbort, { once: true });
+ const settle = () => {
+ clearTimeout(timer);
+ signal.removeEventListener("abort", onAbort);
+ };
+
+ child.on("error", (err: NodeJS.ErrnoException) => {
+ // A child that started still ends with "close"; wait for it, so a stop means it is gone.
+ if (child.pid !== undefined) return;
+ settle();
+ const spawnError = syscallError(err.code ?? "UNKNOWN", file, args);
+ const result = { status: null, signal: null, output: null, pid: 0 };
+ reject(Object.assign(spawnError, { error: spawnError }, result));
+ });
+ child.on("close", (status, exitSignal) => {
+ settle();
+ if (signal.aborted) {
+ void Promise.resolve(stopping).then(() => reject(signal.reason));
+ return;
+ }
+ const out = stdout && Buffer.concat(stdout);
+ const errText = stderr && Buffer.concat(stderr);
+ const result = {
+ status,
+ signal: exitSignal,
+ output: [null, out, errText],
+ pid: child.pid,
+ stdout: out,
+ stderr: errText,
+ };
+ if (failure) {
+ const err = syscallError(failure, file, args);
+ return reject(Object.assign(err, { error: err }, result));
+ }
+ if (status === 0) return resolve();
+ const command = `Command failed: ${[file, ...args].join(" ")}`;
+ const message = errText?.length ? `${command}\n${errText.toString()}` : command;
+ reject(Object.assign(new Error(message), result));
+ });
+ });
+}
diff --git a/packages/cli/src/whisper/manager.ts b/packages/cli/src/whisper/manager.ts
index 63731ed0a0..bf507e683d 100644
--- a/packages/cli/src/whisper/manager.ts
+++ b/packages/cli/src/whisper/manager.ts
@@ -5,6 +5,7 @@ import { homedir, platform } from "node:os";
import { join } from "node:path";
import { findFFmpeg } from "../browser/ffmpeg.js";
import { downloadFile } from "../utils/download.js";
+import { stoppableExecFile } from "../utils/stoppableExecFile.js";
const MODELS_DIR = join(homedir(), ".cache", "hyperframes", "whisper", "models");
const DEFAULT_MODEL = "small.en";
@@ -96,7 +97,10 @@ function findBuiltBinary(): WhisperResult | undefined {
return undefined;
}
-function buildFromSource(onProgress?: (msg: string) => void): WhisperResult {
+async function buildFromSource(
+ onProgress?: (msg: string) => void,
+ signal?: AbortSignal,
+): Promise<WhisperResult> {
// Clean stale builds — if BUILD_DIR exists but has no binary, nuke and re-clone
if (existsSync(BUILD_DIR) && !findBuiltBinary()) {
rmSync(BUILD_DIR, { recursive: true, force: true });
@@ -107,24 +111,27 @@ function buildFromSource(onProgress?: (msg: string) => void): WhisperResult {
mkdirSync(join(homedir(), ".cache", "hyperframes", "whisper"), {
recursive: true,
});
- execFileSync("git", ["clone", "--depth", "1", WHISPER_REPO, BUILD_DIR], {
+ await stoppableExecFile("git", ["clone", "--depth", "1", WHISPER_REPO, BUILD_DIR], {
stdio: "ignore",
timeout: 60_000,
env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+ signal,
});
}
onProgress?.("Building whisper.cpp (this may take a minute)...");
try {
- execFileSync("cmake", ["-B", "build"], {
+ await stoppableExecFile("cmake", ["-B", "build"], {
cwd: BUILD_DIR,
stdio: ["pipe", "pipe", "pipe"],
timeout: 120_000,
+ signal,
});
- execFileSync("cmake", ["--build", "build", "--config", "Release", "-j"], {
+ await stoppableExecFile("cmake", ["--build", "build", "--config", "Release", "-j"], {
cwd: BUILD_DIR,
stdio: ["pipe", "pipe", "pipe"],
timeout: 300_000,
+ signal,
});
} catch (err: unknown) {
// Build failed — capture diagnostics, then clean up so next attempt starts fresh
@@ -189,7 +196,10 @@ function hasCmake(): boolean {
export async function ensureWhisper(options?: {
installRuntime?: boolean;
onProgress?: (msg: string) => void;
+ /** Aborting it stops an install in progress and rejects with the reason, trying nothing else. */
+ signal?: AbortSignal;
}): Promise<WhisperResult> {
+ const signal = options?.signal;
// 1. Already installed?
const existing = findWhisper();
if (existing) return existing;
@@ -203,24 +213,27 @@ export async function ensureWhisper(options?: {
if (platform() === "darwin" && hasBrew()) {
options?.onProgress?.("Installing whisper-cpp via Homebrew...");
try {
- execFileSync("brew", ["install", "whisper-cpp"], {
+ await stoppableExecFile("brew", ["install", "whisper-cpp"], {
stdio: "ignore",
timeout: 300_000,
+ signal,
});
const installed = findFromSystem();
if (installed) return { ...installed, source: "brew" };
} catch {
// brew failed — fall through
}
+ signal?.throwIfAborted();
}
// 3. Build from source (needs git + cmake + C compiler)
if (hasGit() && hasCmake()) {
try {
- return buildFromSource(options?.onProgress);
+ return await buildFromSource(options?.onProgress, signal);
} catch {
// build failed — fall through
}
+ signal?.throwIfAborted();
}
// 4. Give up — tell the user how
@@ -230,6 +243,7 @@ export async function ensureWhisper(options?: {
export async function ensureModel(
model: string = DEFAULT_MODEL,
options?: {
+ signal?: AbortSignal;
onProgress?: (message: string) => void;
onDownloadProgress?: (receivedBytes: number, totalBytes: number | null) => void;
},
@@ -240,7 +254,10 @@ export async function ensureModel(
mkdirSync(MODELS_DIR, { recursive: true });
options?.onProgress?.(`Downloading model ${model}...`);
- await downloadFile(getModelUrl(model), modelPath, { onProgress: options?.onDownloadProgress });
+ await downloadFile(getModelUrl(model), modelPath, {
+ signal: options?.signal,
+ onProgress: options?.onDownloadProgress,
+ });
if (!existsSync(modelPath)) {
throw new Error(`Model download failed: ${model}`);
diff --git a/packages/cli/src/whisper/modelForLanguage.ts b/packages/cli/src/whisper/modelForLanguage.ts
new file mode 100644
index 0000000000..13ce5721f0
--- /dev/null
+++ b/packages/cli/src/whisper/modelForLanguage.ts
@@ -0,0 +1,8 @@
+/** The model whisper runs: a non-English language swaps an English-only `.en` model for its multilingual twin. */
+export function initialModelForLanguage(model: string, language?: string): string {
+ const baseLanguage = language?.trim().toLowerCase().split(/[-_]/, 1)[0];
+ if (baseLanguage && baseLanguage !== "en" && model.endsWith(".en")) {
+ return model.slice(0, -3);
+ }
+ return model;
+}
diff --git a/packages/cli/src/whisper/parakeet.ts b/packages/cli/src/whisper/parakeet.ts
index 095f470fee..96ce6c8b22 100644
--- a/packages/cli/src/whisper/parakeet.ts
+++ b/packages/cli/src/whisper/parakeet.ts
@@ -17,9 +17,10 @@ import { execFileSync } from "node:child_process";
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { homedir, tmpdir } from "node:os";
import { basename, extname, join } from "node:path";
+import { stoppableExecFile } from "../utils/stoppableExecFile.js";
import { TRANSCRIPT_FILE } from "./transcriptFile.js";
import type { Word } from "./normalize.js";
-import type { TranscribeProgress, TranscribeResult } from "./transcribe.js";
+import type { TranscribeProgress, RunnerResult } from "./transcribe.js";
/** The model name `transcribe --json` reports for every Parakeet runner. */
export const PARAKEET_MODEL_LABEL = "parakeet-tdt-0.6b-v3";
@@ -276,14 +277,15 @@ interface ParakeetOptions {
model?: string;
onProgress?: (message: string) => void;
onEvent?: (event: TranscribeProgress) => void;
+ signal?: AbortSignal;
}
/** Transcribe with Parakeet and write `transcript.json` (Word[]) into `dir`. */
-export function transcribeWithParakeet(
+export async function transcribeWithParakeet(
inputPath: string,
dir: string,
options?: ParakeetOptions,
-): TranscribeResult {
+): Promise<RunnerResult> {
const runner = findParakeet();
if (!runner) {
throw new Error(
@@ -309,7 +311,11 @@ export function transcribeWithParakeet(
model: PARAKEET_MODEL_LABEL,
status: "started",
});
- execFileSync(runner, argv, { stdio: ["ignore", "pipe", "pipe"], timeout: 1_800_000 });
+ await stoppableExecFile(runner, argv, {
+ stdio: ["ignore", "pipe", "pipe"],
+ timeout: 1_800_000,
+ signal: options?.signal,
+ });
const produced = join(workDir, `${basename(inputPath, extname(inputPath))}.json`);
if (!existsSync(produced)) throw new Error("Parakeet did not produce output.");
@@ -329,7 +335,7 @@ export function transcribeWithParakeet(
}
}
-export function writeParakeetTranscript(dir: string, words: Word[]): TranscribeResult {
+export function writeParakeetTranscript(dir: string, words: Word[]): RunnerResult {
mkdirSync(dir, { recursive: true });
const transcriptPath = join(dir, TRANSCRIPT_FILE);
writeFileSync(transcriptPath, JSON.stringify(words, null, 2));
diff --git a/packages/cli/src/whisper/sherpa.ts b/packages/cli/src/whisper/sherpa.ts
index 2d92cef784..9615059186 100644
--- a/packages/cli/src/whisper/sherpa.ts
+++ b/packages/cli/src/whisper/sherpa.ts
@@ -31,7 +31,7 @@ import {
getPreparedWavDurationSeconds,
prepareWav,
type TranscribeProgress,
- type TranscribeResult,
+ type RunnerResult,
} from "./transcribe.js";
const RUNTIME = "sherpa-onnx-node";
@@ -439,12 +439,13 @@ function decode(
}
/** Prepares the audio for Parakeet and its fallback alike; ffmpeg stopped by Ctrl-C is a cancel. */
-export function prepareSherpaWav(
+export async function prepareSherpaWav(
inputPath: string,
onProgress?: (message: string) => void,
-): string {
+ signal?: AbortSignal,
+): Promise<string> {
try {
- return prepareWav(inputPath, onProgress);
+ return await prepareWav(inputPath, onProgress, signal);
} catch (err) {
if ((err as { cancelled?: boolean }).cancelled) {
throw new DecodeCancelled("Transcription cancelled");
@@ -464,7 +465,7 @@ export async function transcribeWithSherpa(
cliUrl?: string;
onEvent?: (event: TranscribeProgress) => void;
},
-): Promise<TranscribeResult> {
+): Promise<RunnerResult> {
options.onProgress?.("Transcribing with Parakeet...");
options.onEvent?.({
type: "progress",
diff --git a/packages/cli/src/whisper/transcribe.signal.test.ts b/packages/cli/src/whisper/transcribe.signal.test.ts
new file mode 100644
index 0000000000..35f9db6b4e
--- /dev/null
+++ b/packages/cli/src/whisper/transcribe.signal.test.ts
@@ -0,0 +1,53 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import * as manager from "./manager.js";
+import { transcribe } from "./transcribe.js";
+
+describe("whisper transcribe with a signal", () => {
+ let dir: string;
+ let input: string;
+ beforeEach(() => {
+ dir = mkdtempSync(join(tmpdir(), "hf-whisper-signal-"));
+ input = join(dir, "narration.wav");
+ writeFileSync(input, "not-real-audio");
+ vi.spyOn(manager, "ensureWhisper").mockResolvedValue({
+ executablePath: "/no/whisper-cli",
+ source: "system",
+ });
+ vi.spyOn(manager, "ensureModel").mockRejectedValue(new Error("no model in this test"));
+ });
+ afterEach(() => {
+ vi.restoreAllMocks();
+ rmSync(dir, { recursive: true, force: true });
+ });
+
+ it("does no setup when the signal is already aborted", async () => {
+ const reason = new Error("stopped before it began");
+
+ await expect(transcribe(input, dir, { signal: AbortSignal.abort(reason) })).rejects.toBe(
+ reason,
+ );
+
+ expect(manager.ensureWhisper).not.toHaveBeenCalled();
+ expect(manager.ensureModel).not.toHaveBeenCalled();
+ });
+
+ it("hands the model download the signal and stops before audio prep when it aborts", async () => {
+ const controller = new AbortController();
+ const reason = new Error("stopped during the download");
+ vi.mocked(manager.ensureModel).mockImplementation(async (_model, options) => {
+ expect(options?.signal).toBe(controller.signal);
+ controller.abort(reason);
+ return join(dir, "ggml-small.en.bin");
+ });
+
+ // Audio prep would fail on this fake WAV with its own error; the abort must win first.
+ await expect(transcribe(input, dir, { signal: controller.signal })).rejects.toBe(reason);
+ expect(manager.ensureModel).toHaveBeenCalledOnce();
+ expect(manager.ensureWhisper).toHaveBeenCalledWith(
+ expect.objectContaining({ signal: controller.signal }),
+ );
+ });
+});
diff --git a/packages/cli/src/whisper/transcribe.test.ts b/packages/cli/src/whisper/transcribe.test.ts
index a8fa01c7df..90032e8f2b 100644
--- a/packages/cli/src/whisper/transcribe.test.ts
+++ b/packages/cli/src/whisper/transcribe.test.ts
@@ -299,7 +299,7 @@ describe("getPreparedWavDurationSeconds", () => {
});
describe.skipIf(process.platform === "win32")("prepareWav", () => {
- it("removes the partial WAV when ffmpeg fails or is stopped", () => {
+ it("removes the partial WAV when ffmpeg fails or is stopped", async () => {
const dir = mkdtempSync(join(tmpdir(), "hf-prepare-wav-"));
const ffmpeg = join(dir, "ffmpeg");
writeFileSync(
@@ -313,7 +313,7 @@ describe.skipIf(process.platform === "win32")("prepareWav", () => {
process.env.HYPERFRAMES_FFMPEG_PATH = ffmpeg;
try {
for (const input of ["talk.mp3", "talk.mp4"]) {
- expect(() => prepareWav(join(dir, input))).toThrow(/Command failed/);
+ await expect(prepareWav(join(dir, input))).rejects.toThrow(/Command failed/);
expect(leftovers()).toEqual([]);
}
} finally {
@@ -323,7 +323,7 @@ describe.skipIf(process.platform === "win32")("prepareWav", () => {
}
});
- function failWith(script: string): unknown {
+ async function failWith(script: string): Promise<unknown> {
const dir = mkdtempSync(join(tmpdir(), "hf-prepare-wav-"));
const ffmpeg = join(dir, "ffmpeg");
writeFileSync(ffmpeg, `#!${process.execPath}\n${script}\n`);
@@ -331,7 +331,7 @@ describe.skipIf(process.platform === "win32")("prepareWav", () => {
const saved = process.env.HYPERFRAMES_FFMPEG_PATH;
process.env.HYPERFRAMES_FFMPEG_PATH = ffmpeg;
try {
- prepareWav(join(dir, "talk.mp3"));
+ await prepareWav(join(dir, "talk.mp3"));
} catch (err) {
return err;
} finally {
@@ -342,22 +342,25 @@ describe.skipIf(process.platform === "win32")("prepareWav", () => {
throw new Error("prepareWav did not fail");
}
- it("keeps ffmpeg's stderr on the error, so the cause above its summary line is shown", () => {
+ it("keeps ffmpeg's stderr on the error, so the cause above its summary line is shown", async () => {
const said =
"Output file does not contain any stream\nError opening output files: Invalid argument";
- const err = failWith(`process.stderr.write(${JSON.stringify(said)}); process.exit(234);`);
+ const err = await failWith(`process.stderr.write(${JSON.stringify(said)}); process.exit(234);`);
expect(err).toMatchObject({ cancelled: false, stderr: said });
});
- it("reads a cancel only from ffmpeg's own signal line, not a path that mentions one", () => {
+ it("reads a cancel only from ffmpeg's own signal line, not a path that mentions one", async () => {
const said = "/in/received signal.mp3: Invalid data found when processing input";
- const err = failWith(`process.stderr.write(${JSON.stringify(said)}); process.exit(255);`);
+ const err = await failWith(`process.stderr.write(${JSON.stringify(said)}); process.exit(255);`);
expect(err).toMatchObject({ cancelled: false });
});
- it("rethrows Node's own failure (output overflow) as is, never as a cancel", () => {
+ it("rethrows Node's own failure (output overflow) as is, never as a cancel", async () => {
const flood = `require("fs").writeSync(2, "Exiting normally, received signal 2.\\n" + "x".repeat(65 << 20));`;
- const err = failWith(`${flood} process.exit(255);`) as { code?: string; cancelled?: boolean };
+ const err = (await failWith(`${flood} process.exit(255);`)) as {
+ code?: string;
+ cancelled?: boolean;
+ };
expect(err.code).toBe("ENOBUFS");
expect(err.cancelled).toBeUndefined();
});
diff --git a/packages/cli/src/whisper/transcribe.ts b/packages/cli/src/whisper/transcribe.ts
index 8e1fc8b9e3..1e7c834da9 100644
--- a/packages/cli/src/whisper/transcribe.ts
+++ b/packages/cli/src/whisper/transcribe.ts
@@ -9,12 +9,16 @@ import { tmpdir } from "node:os";
import { randomUUID } from "node:crypto";
import { findFFmpeg, findFFprobe, getFFmpegInstallHint } from "../browser/ffmpeg.js";
import { stoppedByCancelSignal } from "../utils/renderCancellation.js";
+import { stoppableExecFile } from "../utils/stoppableExecFile.js";
import { ensureWhisper, ensureModel, hasFFmpeg, DEFAULT_MODEL } from "./manager.js";
+import { initialModelForLanguage } from "./modelForLanguage.js";
import { TRANSCRIPT_FILE } from "./transcriptFile.js";
import { findWavChunk } from "./wav.js";
import type { Word } from "./normalize.js";
import { emitWords } from "./progress.js";
+export { initialModelForLanguage };
+
const WHISPER_TIMEOUT_FLOOR_MS = 300_000;
const WHISPER_TIMEOUT_PER_AUDIO_SECOND_MS = 10_000;
const WHISPER_TIMEOUT_CAP_MS = 43_200_000;
@@ -252,7 +256,7 @@ export type TranscribeProgress =
/** Words heard so far, before the final transcript replaces them; `through` is audio seconds done. */
| { type: "words"; model: string; words: Word[]; through: number };
-export interface TranscribeOptions {
+export interface WhisperOptions {
installRuntime?: boolean;
model?: string;
language?: string;
@@ -260,6 +264,7 @@ export interface TranscribeOptions {
onEvent?: (event: TranscribeProgress) => void;
/** Called as whisper starts, so a stop during install or download still ends the CLI at once. */
startCancellation?: () => AbortSignal;
+ signal?: AbortSignal;
/**
* Explicit whisper spawn timeout in ms. Overrides the duration+model auto-
* scaled default. Callers that leave this undefined get the auto-scaled
@@ -268,7 +273,7 @@ export interface TranscribeOptions {
timeoutMs?: number;
}
-export interface TranscribeResult {
+export interface RunnerResult {
model: string;
detectedLanguage: string | null;
transcriptPath: string;
@@ -299,15 +304,23 @@ function tempWavPath(): string {
return join(tmpdir(), `hyperframes-audio-${process.pid}-${randomUUID()}.wav`);
}
-function runFfmpeg(ffmpegPath: string, args: string[], output: string, timeout: number): void {
+async function runFfmpeg(
+ ffmpegPath: string,
+ args: string[],
+ output: string,
+ timeout: number,
+ signal?: AbortSignal,
+): Promise<void> {
try {
- execFileSync(ffmpegPath, ["-nostats", "-hide_banner", ...args, "-y", output], {
+ await stoppableExecFile(ffmpegPath, ["-nostats", "-hide_banner", ...args, "-y", output], {
stdio: ["ignore", "ignore", "pipe"],
maxBuffer: 64 * 1024 * 1024,
timeout,
+ signal,
});
} catch (err) {
rmSync(output, { force: true });
+ if (signal?.aborted) throw err;
const stop = err as { code?: string; signal?: string; stderr?: Buffer };
// A code means Node stopped it; ffmpeg traps Ctrl-C and says so (exit 255 is EPERM too on 7+).
if (stop.code) throw err;
@@ -323,7 +336,7 @@ function runFfmpeg(ffmpegPath: string, args: string[], output: string, timeout:
/**
* Extract audio from a video file as 16kHz mono WAV (whisper requirement).
*/
-function extractAudio(videoPath: string): string {
+async function extractAudio(videoPath: string, signal?: AbortSignal): Promise<string> {
const ffmpegPath = findFFmpeg();
if (!ffmpegPath) {
throw new Error(
@@ -331,11 +344,12 @@ function extractAudio(videoPath: string): string {
);
}
const wavPath = tempWavPath();
- runFfmpeg(
+ await runFfmpeg(
ffmpegPath,
["-i", videoPath, "-vn", "-ar", "16000", "-ac", "1", "-f", "wav"],
wavPath,
resolveAudioPreparationTimeoutMs(getMediaDurationSeconds(videoPath)),
+ signal,
);
return wavPath;
}
@@ -376,7 +390,7 @@ function isWav16kMono(filePath: string): boolean {
/**
* Convert audio file to 16kHz mono WAV if not already in that format.
*/
-function prepareAudio(audioPath: string): string {
+async function prepareAudio(audioPath: string, signal?: AbortSignal): Promise<string> {
if (extname(audioPath).toLowerCase() === ".wav" && isWav16kMono(audioPath)) {
return audioPath;
}
@@ -387,11 +401,12 @@ function prepareAudio(audioPath: string): string {
throw new Error(`ffmpeg is required to prepare audio. Install: ${getFFmpegInstallHint()}`);
}
const wavPath = tempWavPath();
- runFfmpeg(
+ await runFfmpeg(
ffmpegPath,
["-i", audioPath, "-ar", "16000", "-ac", "1", "-f", "wav"],
wavPath,
resolveAudioPreparationTimeoutMs(getMediaDurationSeconds(audioPath)),
+ signal,
);
return wavPath;
}
@@ -411,18 +426,15 @@ export function dtwPresetForModel(model: string): string {
return model.replace(/-/g, ".");
}
-export function initialModelForLanguage(model: string, language?: string): string {
- const baseLanguage = language?.trim().toLowerCase().split(/[-_]/, 1)[0];
- if (baseLanguage && baseLanguage !== "en" && model.endsWith(".en")) {
- return model.slice(0, -3);
- }
- return model;
-}
-
-export function prepareWav(inputPath: string, onProgress?: (message: string) => void): string {
+/** Aborting `signal` stops ffmpeg, removes its partial WAV and rejects with the reason. */
+export async function prepareWav(
+ inputPath: string,
+ onProgress?: (message: string) => void,
+ signal?: AbortSignal,
+): Promise<string> {
if (isAudioFile(inputPath)) {
onProgress?.("Preparing audio...");
- return prepareAudio(inputPath);
+ return prepareAudio(inputPath, signal);
}
if (isVideoFile(inputPath)) {
if (!hasFFmpeg()) {
@@ -431,7 +443,7 @@ export function prepareWav(inputPath: string, onProgress?: (message: string) =>
);
}
onProgress?.("Extracting audio from video...");
- return extractAudio(inputPath);
+ return extractAudio(inputPath, signal);
}
throw new Error(`Unsupported file type: ${extname(inputPath).toLowerCase()}`);
}
@@ -443,20 +455,25 @@ export function prepareWav(inputPath: string, onProgress?: (message: string) =>
export async function transcribe(
inputPath: string,
outputDir: string,
- options?: TranscribeOptions,
-): Promise<TranscribeResult> {
+ options?: WhisperOptions,
+): Promise<RunnerResult> {
const model = initialModelForLanguage(options?.model ?? DEFAULT_MODEL, options?.language);
+ const signal = options?.signal;
// 1. Ensure whisper binary
+ signal?.throwIfAborted();
options?.onProgress?.("Checking whisper...");
const whisper = await ensureWhisper({
onProgress: options?.onProgress,
installRuntime: options?.installRuntime,
+ signal,
});
// 2. Ensure model
+ signal?.throwIfAborted();
options?.onProgress?.("Checking model...");
const modelPath = await ensureModel(model, {
+ signal,
onProgress: options?.onProgress,
onDownloadProgress: options?.onEvent
? (receivedBytes, totalBytes) =>
@@ -471,7 +488,9 @@ export async function transcribe(
});
// 3. Prepare audio
- const wavPath = prepareWav(inputPath, options?.onProgress);
+ signal?.throwIfAborted();
+ const wavPath = await prepareWav(inputPath, options?.onProgress, signal);
+ signal?.throwIfAborted();
const automaticLanguage = options?.language === undefined && !model.endsWith(".en");
const language = options?.language ?? (automaticLanguage ? "auto" : "en");
diff --git a/packages/cli/tsup.config.ts b/packages/cli/tsup.config.ts
index 1ef0b49ae6..ea2258b3f5 100644
--- a/packages/cli/tsup.config.ts
+++ b/packages/cli/tsup.config.ts
@@ -19,6 +19,7 @@ export default defineConfig({
backgroundChecksWorker: "src/backgroundChecksWorker.ts",
sherpaWorker: "src/whisper/sherpaWorker.ts",
shaderTransitionWorker: "../producer/src/services/shaderTransitionWorker.ts",
+ api: "src/api.ts",
},
format: ["esm"],
outDir: "dist",
@@ -27,6 +28,8 @@ export default defineConfig({
bundle: true,
splitting: true,
sourcemap: false,
+ // Types for the `./api` export only; the other entries are programs, not libraries.
+ dts: { entry: { api: "src/api.ts" } },
clean: true,
banner: {
js: `import { createRequire as __hf_createRequire } from "node:module";