Skip to content

Write HTML. Render video. Built for agents.

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.mdx
index 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.ts
index 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.ts
index 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 return
diff --git a/packages/cli/src/whisper/parakeet.ts b/packages/cli/src/whisper/parakeet.ts
index 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",