Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
fix(cli): let parakeet-mlx detect the language and name the Parakeet install under auto (#5124)
Miguel Ángel34552a21d20e
diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdxindex 076456127b..6e19367f92 100644--- a/docs/packages/cli.mdx+++ b/docs/packages/cli.mdx@@ -277,7 +277,7 @@ npx hyperframes transcribe transcript.json --to srt| `--dir, -d` | Project directory (default: current directory) || `--engine, -e` | ASR engine: `auto` (default — Parakeet if installed and the language is one of its 25, else whisper), `parakeet` (fails if Parakeet is missing, broken, or lacks the `--language`), or `whisper` || `--model, -m` | Whisper model (default `small.en`): `tiny.en`, `base.en`, `small.en`, `medium.en`, `large-v3` |-| `--language, -l` | Language code (`en`, `es`, `ja`, …). Filters out speech in other languages. |+| `--language, -l` | Language code (`en`, `es`, `ja`, …). Whisper transcribes as this language; Parakeet, used when it covers it, detects the language itself. || `--to` | Export a sidecar instead: `srt` or `vtt` || `--output, -o` | Where the exported SRT/VTT goes || `--preserve-cues` | Keep each transcript entry as its own caption cue, skipping word-level grouping |diff --git a/packages/cli/src/commands/transcribe.test.ts b/packages/cli/src/commands/transcribe.test.tsindex 8f40d578cf..81d0ff9728 100644--- a/packages/cli/src/commands/transcribe.test.ts+++ b/packages/cli/src/commands/transcribe.test.ts@@ -242,6 +242,34 @@ 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(+ runner,+ `#!/bin/sh+[ "$1" = --help ] && exit 0+in="$1"+for a in "$@"; do [ "$a" = --language ] && { echo "Error: No such option: --language" >&2; exit 2; }; done+while [ "$1" != --output-dir ]; do shift; done+echo '{"sentences":[{"tokens":[{"text":" hola","start":0,"end":1}]}]}' > "$2/$(basename "$in" .wav).json"+`,+ );+ chmodSync(runner, 0o755);+ vi.stubEnv("HYPERFRAMES_PARAKEET", runner);+ mlxMock.mockImplementation(parakeet.transcribeWithParakeet);++ expect(await transcribeWith("auto", { sherpa: false, mlx: true }, "es")).toMatchObject({+ engine: "parakeet",+ word: "hola",+ });+ },+ );+it("auto uses Parakeet only for a language it transcribes", async () => {const both = { sherpa: true, mlx: true };expect(await transcribeWith("auto", both, "ja")).toMatchObject({ engine: "whisper" });@@ -330,6 +358,27 @@ describe("transcribe command", () => {return { exitCode: exitCode || consumeCommandResult().exitCode, out: lastJson() };}+ it("auto names the Parakeet install when whisper is missing and Parakeet is not installed", async () => {+ transcribeMock.mockRejectedValue(new WhisperUnavailableError("whisper-cpp not found"));+ const { exitCode, out } = await transcribeFails("auto", { optional: true });+ expect(exitCode).toBe(0);+ expect(out).toEqual({+ ok: false,+ skipped: true,+ reason: "whisper_unavailable",+ install: "hyperframes models install parakeet",+ });+ });++ it.each([+ ["a language Parakeet does not transcribe", "auto", "ja"],+ ["an explicit --engine whisper", "whisper", undefined],+ ])("offers no Parakeet install for %s", async (_case, engine, language) => {+ transcribeMock.mockRejectedValue(new WhisperUnavailableError("whisper-cpp not found"));+ const { out } = await transcribeFails(engine, { optional: true, language });+ expect(out).toEqual({ ok: false, skipped: true, reason: "whisper_unavailable" });+ });+it.each(["whisper", "auto"])("--no-runtime-install reaches %s including the fallback",async (engine) => {diff --git a/packages/cli/src/commands/transcribe.ts b/packages/cli/src/commands/transcribe.tsindex cd278d7c07..0ba69b7e00 100644--- a/packages/cli/src/commands/transcribe.ts+++ b/packages/cli/src/commands/transcribe.ts@@ -72,7 +72,8 @@ export default defineCommand({},language: {type: "string",- description: "Language code (e.g. en, es, ja). Filters out non-target language speech.",+ description:+ "Language code (e.g. en, es, ja). Whisper transcribes as this language; Parakeet, used when it covers it, detects the language itself.",alias: "l",},json: {@@ -281,6 +282,8 @@ async function exportTranscript(type Runner = "sherpa" | "parakeet-mlx" | "whisper";+const PARAKEET_INSTALL_COMMAND = "hyperframes models install parakeet";+/** auto and parakeet prefer sherpa-onnx, then parakeet-mlx, then whisper, in Parakeet's languages. */function pickRunner(engine: string, sherpaUsable: () => boolean, language?: string): Runner {if (engine === "whisper" || !parakeetSpeaks(language)) return "whisper";@@ -331,7 +334,7 @@ async function transcribeAudio(!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: hyperframes models install parakeet (or use --engine whisper)"),+ `Parakeet is not installed. Install it with: ${PARAKEET_INSTALL_COMMAND} (or use --engine whisper)`),!!opts.json,);}@@ -361,7 +364,6 @@ async function transcribeAudio(});case "parakeet-mlx":return transcribeWithParakeet(wavPath, dir, {- language: opts.language,onProgress,onEvent,});@@ -390,7 +392,7 @@ async function transcribeAudio(} catch (err) {if (runner !== "sherpa" || err instanceof DecodeCancelled) throw err;const reason = normalizeErrorMessage(err).replace(/\.+$/, "");- const parakeetError = `Parakeet failed: ${reason}. To repair it, run: hyperframes models install parakeet`;+ const parakeetError = `Parakeet failed: ${reason}. To repair it, run: ${PARAKEET_INSTALL_COMMAND}`;if (!parakeetFallsBack(engine)) throw new Error(parakeetError);runner = pickRunner(engine, () => false, opts.language);spin?.clear();@@ -477,10 +479,17 @@ async function transcribeAudio(// 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" }));+ console.log(+ JSON.stringify({ ok: false, skipped: true, reason: "whisper_unavailable", install }),+ );} else {- spin?.stop(c.warn(`Captions skipped — ${message}`));+ 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 returndiff --git a/packages/cli/src/whisper/parakeet.ts b/packages/cli/src/whisper/parakeet.tsindex 6a969ed639..978df811be 100644--- a/packages/cli/src/whisper/parakeet.ts+++ b/packages/cli/src/whisper/parakeet.ts@@ -270,7 +270,6 @@ export function silenceCuts(}interface ParakeetOptions {- language?: string;model?: string;onProgress?: (message: string) => void;onEvent?: (event: TranscribeProgress) => void;@@ -301,7 +300,6 @@ export function transcribeWithParakeet(const workDir = mkdtempSync(join(tmpdir(), "hyperframes-parakeet-"));try {const argv = [inputPath, "--model", model, "--output-format", "json", "--output-dir", workDir];- if (options?.language) argv.push("--language", options.language);options?.onEvent?.({type: "progress",phase: "transcription",