{"record":{"id":"e42345bc86f36ae1","repo":"heygen-com/hyperframes","slug":"parakeet-mlx-not-found-enable-the-parakeet-engine","errorCode":null,"errorMessage":"parakeet-mlx not found. Enable the Parakeet engine with:\n  ${PARAKEET_INSTALL}\n(or use --engine whisper)","messagePattern":"parakeet-mlx not found\\. Enable the Parakeet engine with:\n  (.+?)\n\\(or use --engine whisper\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cli/src/whisper/parakeet.ts","lineNumber":120,"sourceCode":"  }\n  return words.filter((w) => w.text.length > 0);\n}\n\ninterface ParakeetOptions {\n  language?: string;\n  model?: string;\n  onProgress?: (message: string) => void;\n}\n\n/** Transcribe with Parakeet and write `transcript.json` (Word[]) into `dir`. */\nexport function transcribeWithParakeet(\n  inputPath: string,\n  dir: string,\n  options?: ParakeetOptions,\n): TranscribeResult {\n  const runner = findParakeet();\n  if (!runner) {\n    throw new Error(\n      `parakeet-mlx not found. Enable the Parakeet engine with:\\n  ${PARAKEET_INSTALL}\\n(or use --engine whisper)`,\n    );\n  }\n\n  const model = options?.model ?? DEFAULT_MODEL;\n  // First run pulls the model from HuggingFace (~600MB) — cue it so the wait\n  // doesn't read as a hang. HF caches at ~/.cache/huggingface/hub/models--<slug>.\n  const cached = existsSync(\n    join(homedir(), \".cache\", \"huggingface\", \"hub\", `models--${model.replace(/\\//g, \"--\")}`),\n  );\n  options?.onProgress?.(\n    cached ? \"Transcribing with Parakeet...\" : \"Downloading Parakeet model (first run, ~600MB)...\",\n  );\n  const workDir = mkdtempSync(join(tmpdir(), \"hyperframes-parakeet-\"));\n  try {\n    const argv = [inputPath, \"--model\", model, \"--output-format\", \"json\", \"--output-dir\", workDir];\n    if (options?.language) argv.push(\"--language\", options.language);\n    execFileSync(runner, argv, { stdio: [\"ignore\", \"pipe\", \"pipe\"], timeout: 1_800_000 });","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/whisper/parakeet.ts#L102-L138","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before: hyperframes transcribe --engine parakeet video.mp4\n// after (option A): install parakeet-mlx per the error message, then retry\n// after (option B): hyperframes transcribe --engine whisper video.mp4","handlingStrategy":"fallback","validationCode":"import { findParakeet } from \"./parakeet.js\";\n\nconst runner = findParakeet();\nif (!runner) {\n  console.warn(\"parakeet-mlx not found. Use --engine whisper as fallback.\");\n}","typeGuard":null,"tryCatchPattern":"import { transcribeWithParakeet } from \"./parakeet.js\";\n\ntry {\n  return transcribeWithParakeet(inputPath, dir, options);\n} catch (err) {\n  if (err instanceof Error && err.message.includes(\"parakeet-mlx not found\")) {\n    // Fall back to whisper engine\n    console.warn(\"Parakeet unavailable — falling back to whisper engine.\");\n    return transcribeWithWhisper(inputPath, dir, options);\n  }\n  throw err;\n}","preventionTips":["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."],"tags":["whisper","parakeet","dependencies","engine","captions"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}