Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
feat(cli): add hyperframes/api entry with transcribe and removeBackground (#5453)
James Russo943b6512b43b
diff --git a/knip.config.ts b/knip.config.tsindex 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.jsonnew file mode 100644index 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.jsonindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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-duplicationimport { 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.tsindex 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.tsindex 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 | undefreturn { 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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-cloneif (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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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";