parakeet-mlx not found. Enable the Parakeet engine with: $

Error message

parakeet-mlx not found. Enable the Parakeet engine with:
  ${PARAKEET_INSTALL}
(or use --engine whisper)

What it means

Thrown by transcribeWithParakeet when the Parakeet transcription engine is selected (e.g. via --engine parakeet) but the parakeet-mlx binary cannot be found. findParakeet checks the HYPERFRAMES_PARAKEET env var, the documented venv path (~/.venvs/parakeet/bin/parakeet-mlx), and PATH, verifying each candidate is runnable. If none work, this error fires with installation instructions.

Source

Thrown at packages/cli/src/whisper/parakeet.ts:120

  }
  return words.filter((w) => w.text.length > 0);
}

interface ParakeetOptions {
  language?: string;
  model?: string;
  onProgress?: (message: string) => void;
}

/** Transcribe with Parakeet and write `transcript.json` (Word[]) into `dir`. */
export function transcribeWithParakeet(
  inputPath: string,
  dir: string,
  options?: ParakeetOptions,
): TranscribeResult {
  const runner = findParakeet();
  if (!runner) {
    throw new Error(
      `parakeet-mlx not found. Enable the Parakeet engine with:\n  ${PARAKEET_INSTALL}\n(or use --engine whisper)`,
    );
  }

  const model = options?.model ?? DEFAULT_MODEL;
  // First run pulls the model from HuggingFace (~600MB) — cue it so the wait
  // doesn't read as a hang. HF caches at ~/.cache/huggingface/hub/models--<slug>.
  const cached = existsSync(
    join(homedir(), ".cache", "huggingface", "hub", `models--${model.replace(/\//g, "--")}`),
  );
  options?.onProgress?.(
    cached ? "Transcribing with Parakeet..." : "Downloading Parakeet model (first run, ~600MB)...",
  );
  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);
    execFileSync(runner, argv, { stdio: ["ignore", "pipe", "pipe"], timeout: 1_800_000 });

View on GitHub (pinned to c2996c8626)

Solutions

Run the installation command shown in the error: uv venv ~/.venvs/parakeet && VIRTUAL_ENV=~/.venvs/parakeet uv pip install parakeet-mlx.
Ensure you're on Apple Silicon (parakeet-mlx requires Metal/MLX).
If parakeet-mlx is installed elsewhere, set HYPERFRAMES_PARAKEET to its full path.
Fall back to the whisper engine by passing --engine whisper.

Example fix

// before: hyperframes transcribe --engine parakeet video.mp4
// after (option A): install parakeet-mlx per the error message, then retry
// after (option B): hyperframes transcribe --engine whisper video.mp4

Defensive patterns

Strategy: fallback

Validate before calling

import { findParakeet } from "./parakeet.js";

const runner = findParakeet();
if (!runner) {
  console.warn("parakeet-mlx not found. Use --engine whisper as fallback.");
}

Try / catch

import { transcribeWithParakeet } from "./parakeet.js";

try {
  return transcribeWithParakeet(inputPath, dir, options);
} catch (err) {
  if (err instanceof Error && err.message.includes("parakeet-mlx not found")) {
    // Fall back to whisper engine
    console.warn("Parakeet unavailable — falling back to whisper engine.");
    return transcribeWithWhisper(inputPath, dir, options);
  }
  throw err;
}

Prevention

Run findParakeet() before selecting the engine to fail fast with actionable guidance.
Install parakeet-mlx in the documented venv before first use on Apple Silicon.
Always have the whisper engine as a fallback (--engine whisper) for environments without parakeet-mlx.

When it happens

Trigger: User passes --engine parakeet without having installed parakeet-mlx; the venv was created but the binary isn't runnable; HYPERFRAMES_PARAKEET points to a stale path; parakeet-mlx was uninstalled or the venv was deleted.

Common situations: Selecting the Parakeet engine for the first time without setup; running on a non-Apple-Silicon machine where parakeet-mlx isn't supported; a corrupted venv; switching machines without reinstalling.

Related errors

AI-assisted analysis of heygen-com/hyperframes@c2996c8626 (2026-08-12). Data as JSON: /api/errors/e42345bc86f36ae1. Report an issue: GitHub.