hyperframes 0.8.80 → 0.8.82

package/dist/skills/media-use/references/operations.md

@@ -112,14 +112,16 @@ engine directly.
 # install once: uv venv ~/.venvs/parakeet && VIRTUAL_ENV=~/.venvs/parakeet uv pip install parakeet-mlx
 node <SKILL_DIR>/scripts/transcribe.mjs --input talk.mp4 --out talk.transcribe.json
 
-# equivalently, the hyperframes CLI has Parakeet built in (auto-detects it, whisper fallback):
+# the hyperframes CLI runs Parakeet on macOS, Linux and Windows once it is installed:
+npx hyperframes models install parakeet                 # once, ~640 MB, ask the user first
 npx hyperframes transcribe talk.mp4 --engine parakeet   # or --engine auto (default)
 ```
 
-VERIFIED on 24GB: accurate, ~3s (cached) for 8s audio. Parakeet covers English +
-25 European languages. For other languages, or when parakeet-mlx is not
-installed, transcribe.mjs auto-falls-back to whisper.cpp (99 languages) via
-`hyperframes transcribe`. `--engine parakeet|whisper` forces one. (Cohere
+VERIFIED on 24GB: accurate, ~3s (cached) for 8s audio. Parakeet covers 25
+European languages, English included. For other languages, or when parakeet-mlx is not
+installed, transcribe.mjs falls back to `hyperframes transcribe`, which uses the
+CLI's Parakeet when `models install parakeet` has run and whisper.cpp (99
+languages) otherwise. `--engine parakeet|whisper` forces one. (Cohere
 Transcribe tops the leaderboard on paper but its mlx-audio quants produced
 garbage and ran 40-70x slower on a Mac in testing, so it is not wired in.)
 

package/dist/skills/media-use/references/setup-providers.md

@@ -59,15 +59,15 @@ tools are OPT-IN alternatives where they exist; install one to unlock its free,
 private, on-device path instead of or ahead of HeyGen for that type. Only
 `ffmpeg`/`ffprobe` are strictly required for the tool to run at all.
 
-| Tool               | Serves                                                                          | Install                                                                                                                                       |
-| ------------------ | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ffmpeg`/`ffprobe` | adopt probing, smart-grade signalstats, cut, duck bake, loudnorm                | system package (`brew install ffmpeg`)                                                                                                        |
-| `heygen`           | catalog (bgm/sfx/image/icon) + TTS (voice) + avatar video — the free-usage path | install through [verified HeyGen release instructions](https://developers.heygen.com/cli), then `heygen auth login --oauth` (needs >= v0.3.0) |
-| `mflux-generate`   | local image gen (FLUX), best-for-RAM                                            | `uv venv ~/.venvs/mflux && VIRTUAL_ENV=~/.venvs/mflux uv pip install mflux==0.9.6`                                                            |
-| `codex`            | image gen upsell (ChatGPT sub)                                                  | Codex CLI, logged in via ChatGPT (owns its own auth)                                                                                          |
-| `parakeet-mlx`     | local transcription (default ASR, best)                                         | `uv venv ~/.venvs/parakeet && VIRTUAL_ENV=~/.venvs/parakeet uv pip install parakeet-mlx`                                                      |
-| `ltx-2-mlx`        | local video gen                                                                 | `git clone https://github.com/dgrauet/ltx-2-mlx && cd ltx-2-mlx && uv sync --all-extras`                                                      |
-| `npx hyperframes`  | Kokoro TTS (voice), whisper.cpp (transcribe fallback), remove-background        | via the hyperframes CLI; whisper.cpp is built on first use (Homebrew on macOS, else git+cmake), models download from HuggingFace              |
+| Tool               | Serves                                                                          | Install                                                                                                                                                                                     |
+| ------------------ | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ffmpeg`/`ffprobe` | adopt probing, smart-grade signalstats, cut, duck bake, loudnorm                | system package (`brew install ffmpeg`)                                                                                                                                                      |
+| `heygen`           | catalog (bgm/sfx/image/icon) + TTS (voice) + avatar video — the free-usage path | install through [verified HeyGen release instructions](https://developers.heygen.com/cli), then `heygen auth login --oauth` (needs >= v0.3.0)                                               |
+| `mflux-generate`   | local image gen (FLUX), best-for-RAM                                            | `uv venv ~/.venvs/mflux && VIRTUAL_ENV=~/.venvs/mflux uv pip install mflux==0.9.6`                                                                                                          |
+| `codex`            | image gen upsell (ChatGPT sub)                                                  | Codex CLI, logged in via ChatGPT (owns its own auth)                                                                                                                                        |
+| `parakeet-mlx`     | local transcription (default ASR, best) on Apple Silicon                        | `uv venv ~/.venvs/parakeet && VIRTUAL_ENV=~/.venvs/parakeet uv pip install parakeet-mlx`                                                                                                    |
+| `ltx-2-mlx`        | local video gen                                                                 | `git clone https://github.com/dgrauet/ltx-2-mlx && cd ltx-2-mlx && uv sync --all-extras`                                                                                                    |
+| `npx hyperframes`  | Kokoro TTS (voice), Parakeet or whisper.cpp (transcribe), remove-background     | via the hyperframes CLI; Parakeet on macOS, Windows and glibc 2.32+ Linux: `npx hyperframes models install parakeet`; whisper.cpp is built on first use (Homebrew on macOS, else git+cmake) |
 
 The RAM-graded local-model shortlist + exact per-tier install/invoke lives in
 `scripts/lib/local-models.mjs` (the agent can read `describeModelLadder(cap, specs)`

package/dist/skills/media-use/registry/localSemantic.js

@@ -24,6 +24,7 @@ import {
   realpathSync,
   renameSync,
   rmSync,
+  statSync,
   writeFileSync
 } from "fs";
 import { createRequire } from "module";
@@ -79,9 +80,9 @@ function pinnedCopyBesideCli(name, cliUrl) {
 function loadBesideCli(name, cliUrl = import.meta.url) {
   return pinnedCopyBesideCli(name, cliUrl) ? createRequire(cliUrl)(name) : null;
 }
-function runNpm(args) {
+function runNpm(args, signal) {
   const npm = buildNpmCommand(args);
-  const child = spawn(npm.command, npm.args, { stdio: ["ignore", "pipe", "pipe"] });
+  const child = spawn(npm.command, npm.args, { stdio: ["ignore", "pipe", "pipe"], signal });
   return new Promise((resolve, reject) => {
     let output = "";
     child.stdout.on("data", (chunk) => output += chunk);
@@ -101,6 +102,7 @@ function isProcessAlive(pid) {
     return err.code !== "ESRCH";
   }
 }
+var STAGING_PID_TRUSTED_FOR_MS = 6 * 60 * 60 * 1e3;
 function sweepStaleStaging(dir) {
   const prefix = `${basename(dir)}.tmp-`;
   const parent = dirname(dir);
@@ -108,8 +110,10 @@ function sweepStaleStaging(dir) {
   for (const entry of readdirSync(parent)) {
     if (!entry.startsWith(prefix)) continue;
     const pid = /^(\d+)(?:-|$)/.exec(entry.slice(prefix.length))?.[1];
-    if (pid === void 0 || isProcessAlive(Number(pid))) continue;
+    if (pid === void 0) continue;
     const stale = join(parent, entry);
+    const age = Date.now() - (statSync(stale, { throwIfNoEntry: false })?.mtimeMs ?? Date.now());
+    if (isProcessAlive(Number(pid)) && age < STAGING_PID_TRUSTED_FOR_MS) continue;
     try {
       rmSync(stale, { recursive: true, force: true });
     } catch (err) {

package/dist/skills/media-use/scripts/lib/ff-binaries.mjs

@@ -0,0 +1,37 @@
+import { execFileSync } from "node:child_process";
+import { resolve } from "node:path";
+
+// The binaries media-use spawns: HYPERFRAMES_FFMPEG_PATH / HYPERFRAMES_FFPROBE_PATH when set, else PATH.
+// A set path that is not a working ffmpeg/ffprobe throws, so a broken override never reads as "no metadata".
+const runsByPath = new Map();
+
+export class FfBinarySettingError extends Error {}
+
+function configuredOr(name, envVar) {
+  const setting = process.env[envVar]?.trim();
+  if (!setting) return name;
+  const path = resolve(setting);
+  if (!runsByPath.has(path)) runsByPath.set(path, isWorking(path, name));
+  if (!runsByPath.get(path)) {
+    const why = `${envVar} names "${path}", which is not a working ${name}: fix it or unset it.`;
+    throw new FfBinarySettingError(why);
+  }
+  return path;
+}
+
+function isWorking(path, name) {
+  try {
+    const out = execFileSync(path, ["-version"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 15000,
+      windowsHide: true,
+    });
+    return out.startsWith(`${name} version`);
+  } catch {
+    return false;
+  }
+}
+
+export const ffmpegBinary = () => configuredOr("ffmpeg", "HYPERFRAMES_FFMPEG_PATH");
+export const ffprobeBinary = () => configuredOr("ffprobe", "HYPERFRAMES_FFPROBE_PATH");

package/dist/skills/media-use/scripts/lib/probe.mjs

@@ -1,5 +1,6 @@
 import { execFileSync } from "node:child_process";
 import { extname } from "node:path";
+import { ffprobeBinary } from "./ff-binaries.mjs";
 
 const IMAGE_EXT = new Set([".jpg", ".jpeg", ".png", ".gif", ".webp", ".svg", ".ico"]);
 
@@ -7,11 +8,12 @@ export function probe(filePath) {
   const ext = extname(filePath).toLowerCase();
   if (ext === ".svg") return { width: null, height: null, duration: null, codec: "svg" };
 
+  const ffprobe = ffprobeBinary();
   try {
     // execFileSync (no shell) so a hostile filename like `"; rm -rf ~; ".png`
     // can't break out of the quoting — filePath is passed as a literal argv entry.
     const raw = execFileSync(
-      "ffprobe",
+      ffprobe,
       ["-v", "quiet", "-print_format", "json", "-show_format", "-show_streams", "--", filePath],
       { encoding: "utf8", timeout: 5000 },
     );

package/dist/skills/media-use/scripts/lib/probe.test.mjs

@@ -1,6 +1,6 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, writeFileSync, existsSync, rmSync } from "node:fs";
+import { chmodSync, mkdtempSync, writeFileSync, existsSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { probe } from "./probe.mjs";
@@ -29,3 +29,120 @@ test("probe does not execute shell metacharacters in a filename", () => {
     rmSync(dir, { recursive: true, force: true });
   }
 });
+
+test(
+  "probe runs the ffprobe HYPERFRAMES_FFPROBE_PATH names",
+  { skip: process.platform === "win32" },
+  () => {
+    const dir = mkdtempSync(join(tmpdir(), "probe-ffprobe-path-"));
+    const fake = join(dir, "fake-ffprobe");
+    writeFileSync(
+      fake,
+      `#!/bin/sh\n[ "$1" = -version ] && echo 'ffprobe version fake' && exit 0\necho '{"streams":[{"width":7,"height":3,"codec_name":"fake"}]}'\n`,
+    );
+    chmodSync(fake, 0o755);
+    const configured = process.env.HYPERFRAMES_FFPROBE_PATH;
+    process.env.HYPERFRAMES_FFPROBE_PATH = fake;
+    try {
+      assert.deepEqual(probe(join(dir, "clip.png")), {
+        duration: null,
+        width: 7,
+        height: 3,
+        codec: "fake",
+      });
+    } finally {
+      if (configured === undefined) delete process.env.HYPERFRAMES_FFPROBE_PATH;
+      else process.env.HYPERFRAMES_FFPROBE_PATH = configured;
+      rmSync(dir, { recursive: true, force: true });
+    }
+  },
+);
+
+test("probe refuses an HYPERFRAMES_FFPROBE_PATH that cannot run instead of reporting no metadata", () => {
+  const configured = process.env.HYPERFRAMES_FFPROBE_PATH;
+  process.env.HYPERFRAMES_FFPROBE_PATH = join(tmpdir(), "no-ffprobe-here", "ffprobe");
+  try {
+    assert.throws(
+      () => probe("clip.wav"),
+      /HYPERFRAMES_FFPROBE_PATH names ".*no-ffprobe-here.*fix it or unset it/,
+    );
+  } finally {
+    if (configured === undefined) delete process.env.HYPERFRAMES_FFPROBE_PATH;
+    else process.env.HYPERFRAMES_FFPROBE_PATH = configured;
+  }
+});
+
+test("probe refuses an HYPERFRAMES_FFPROBE_PATH that names a folder", () => {
+  const configured = process.env.HYPERFRAMES_FFPROBE_PATH;
+  process.env.HYPERFRAMES_FFPROBE_PATH = tmpdir();
+  try {
+    assert.throws(() => probe("clip.wav"), /HYPERFRAMES_FFPROBE_PATH names .*fix it or unset it/);
+  } finally {
+    if (configured === undefined) delete process.env.HYPERFRAMES_FFPROBE_PATH;
+    else process.env.HYPERFRAMES_FFPROBE_PATH = configured;
+  }
+});
+
+function withFfprobePath(value, run) {
+  const configured = process.env.HYPERFRAMES_FFPROBE_PATH;
+  process.env.HYPERFRAMES_FFPROBE_PATH = value;
+  try {
+    return run();
+  } finally {
+    if (configured === undefined) delete process.env.HYPERFRAMES_FFPROBE_PATH;
+    else process.env.HYPERFRAMES_FFPROBE_PATH = configured;
+  }
+}
+
+test(
+  "probe refuses a configured ffprobe that cannot start, exits with an error, or is another tool",
+  {
+    skip: process.platform === "win32",
+  },
+  () => {
+    const dir = mkdtempSync(join(tmpdir(), "probe-broken-ffprobe-"));
+    try {
+      const noInterpreter = join(dir, "no-interpreter");
+      writeFileSync(noInterpreter, "#!/nonexistent/interpreter\n");
+      const failing = join(dir, "failing");
+      writeFileSync(failing, "#!/bin/sh\nexit 3\n");
+      const otherTool = join(dir, "other-tool");
+      writeFileSync(otherTool, "#!/bin/sh\necho 'ffmpeg version 9.9'\n");
+      for (const broken of [noInterpreter, failing, otherTool]) {
+        chmodSync(broken, 0o755);
+        withFfprobePath(broken, () =>
+          assert.throws(
+            () => probe("clip.wav"),
+            /HYPERFRAMES_FFPROBE_PATH names .*fix it or unset it/,
+          ),
+        );
+      }
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  },
+);
+
+test(
+  "probe runs a relative HYPERFRAMES_FFPROBE_PATH from the working folder, not from PATH",
+  {
+    skip: process.platform === "win32",
+  },
+  () => {
+    const dir = mkdtempSync(join(tmpdir(), "probe-relative-ffprobe-"));
+    const prevCwd = process.cwd();
+    try {
+      writeFileSync(
+        join(dir, "local-ffprobe"),
+        `#!/bin/sh\n[ "$1" = -version ] && echo 'ffprobe version fake' && exit 0\necho '{"streams":[{"width":5,"height":4,"codec_name":"local"}]}'\n`,
+      );
+      chmodSync(join(dir, "local-ffprobe"), 0o755);
+      process.chdir(dir);
+      const meta = withFfprobePath("local-ffprobe", () => probe("clip.png"));
+      assert.deepEqual(meta, { duration: null, width: 5, height: 4, codec: "local" });
+    } finally {
+      process.chdir(prevCwd);
+      rmSync(dir, { recursive: true, force: true });
+    }
+  },
+);

package/dist/skills/media-use/scripts/lib/test-home.test.mjs

@@ -0,0 +1,10 @@
+import assert from "node:assert/strict";
+import { realpathSync } from "node:fs";
+import { homedir, tmpdir, userInfo } from "node:os";
+import { sep } from "node:path";
+import { test } from "node:test";
+
+test("the skills test run has a home folder of its own, not the user's", () => {
+  assert.ok(realpathSync(homedir()).startsWith(realpathSync(tmpdir()) + sep));
+  assert.notEqual(homedir(), userInfo().homedir);
+});

package/dist/skills/media-use/scripts/lib/tts-local-provider.mjs

@@ -2,6 +2,7 @@ import { execFileSync } from "node:child_process";
 import { existsSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { ffprobeBinary } from "./ff-binaries.mjs";
 import { resolveSpawnCommand } from "../../audio/scripts/lib/tts.mjs";
 
 // Local voiceover via the packaged Kokoro-82M TTS (the `hyperframes tts` CLI),
@@ -13,10 +14,10 @@ import { resolveSpawnCommand } from "../../audio/scripts/lib/tts.mjs";
 // Delegated to the hyperframes CLI (same as transcribe / remove-background), not
 // re-implemented here. ffprobe reads the duration back for the ledger.
 
-function probeDurationSeconds(file) {
+function probeDurationSeconds(ffprobe, file) {
   try {
     const out = execFileSync(
-      "ffprobe",
+      ffprobe,
       ["-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", "--", file],
       { encoding: "utf8", timeout: 15000 },
     );
@@ -39,6 +40,7 @@ export async function localTtsGenerate(
   env = process.env,
   pathExists = existsSync,
 ) {
+  const ffprobe = ffprobeBinary();
   const outPath = join(tmpdir(), `media-use-kokoro-${process.pid}-${Date.now()}.wav`);
   const argv = ["hyperframes", "tts", intent, "--output", outPath];
   if (ctx?.voice) argv.push("--voice", ctx.voice);
@@ -85,7 +87,7 @@ export async function localTtsGenerate(
     metadata: {
       description: intent,
       provider: "kokoro.local",
-      duration: probeDurationSeconds(outPath),
+      duration: probeDurationSeconds(ffprobe, outPath),
       provenance: { engine: "kokoro-82m", prompt: intent },
     },
   };

package/dist/skills/media-use/scripts/resolve-plugin.test.mjs

@@ -0,0 +1,62 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { copyFileSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+
+test(
+  "plugin resolver uses the release CLI without a repository checkout",
+  { skip: process.platform === "win32" },
+  (t) => {
+    const dir = mkdtempSync(join(tmpdir(), "hf-resolve-plugin-"));
+    t.after(() => rmSync(dir, { recursive: true, force: true }));
+    mkdirSync(join(dir, "lib"));
+    for (const file of ["resolve.mjs", "lib/npx-sync.mjs"]) {
+      copyFileSync(fileURLToPath(new URL(file, import.meta.url)), join(dir, file));
+    }
+    writeFileSync(
+      join(dir, "npx"),
+      `#!${process.execPath}\nconsole.log(JSON.stringify({args:process.argv.slice(2),skip:process.env.HYPERFRAMES_SKIP_SKILLS}));process.exit(7);`,
+      { mode: 0o755 },
+    );
+    const result = spawnSync(process.execPath, [join(dir, "resolve.mjs"), "--intent", "a & b"], {
+      cwd: dir,
+      encoding: "utf8",
+      env: {
+        ...process.env,
+        PATH: `${dir}${delimiter}${process.env.PATH}`,
+        HYPERFRAMES_PLUGIN_VERSION: "1.2.3",
+        HYPERFRAMES_SKIP_SKILLS: "1",
+      },
+    });
+    assert.equal(result.status, 7, result.stderr);
+    assert.deepEqual(JSON.parse(result.stdout), {
+      args: ["--yes", "hyperframes@1.2.3", "media-use", "resolve", "--intent", "a & b"],
+      skip: "1",
+    });
+  },
+);
+
+test("helper package override keeps a contributor's local CLI", (t) => {
+  const root = mkdtempSync(join(tmpdir(), "hf-resolve-local-"));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const scripts = join(root, "skills/media-use/scripts");
+  mkdirSync(join(scripts, "lib"), { recursive: true });
+  mkdirSync(join(root, "packages/cli/dist"), { recursive: true });
+  for (const file of ["resolve.mjs", "lib/npx-sync.mjs"]) {
+    copyFileSync(fileURLToPath(new URL(file, import.meta.url)), join(scripts, file));
+  }
+  writeFileSync(join(root, "packages/cli/dist/cli.js"), 'console.log("local-cli");');
+  const result = spawnSync(process.execPath, [join(scripts, "resolve.mjs")], {
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      HYPERFRAMES_PLUGIN_VERSION: "",
+      HYPERFRAMES_SKILL_PKG_VERSION: "0.8.79",
+    },
+  });
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(result.stdout.trim(), "local-cli");
+});

package/dist/skills/media-use/scripts/resolve.mjs

@@ -33,6 +33,7 @@ import { heygenAuthMethod } from "../audio/scripts/lib/heygen.mjs";
 import { buildCube, paramsFromIntent } from "./lib/cube-build.mjs";
 import { validateCubeFile } from "./lib/cube-validate.mjs";
 import { analyzeMediaGrade, formatMeasuredNote } from "./lib/grade-analyzer.mjs";
+import { FfBinarySettingError, ffmpegBinary, ffprobeBinary } from "./lib/ff-binaries.mjs";
 import {
   freezeLibraryLut,
   isLibraryLutOfflineMiss,
@@ -144,7 +145,12 @@ const entity = args.entity || null;
 
 if (args.adopt) {
   const { adoptExistingAssets } = await import("./lib/adopt.mjs");
-  const adopted = adoptExistingAssets(projectDir);
+  let adopted;
+  try {
+    adopted = adoptExistingAssets(projectDir);
+  } catch (err) {
+    exitError(err.message);
+  }
   if (args.json) {
     console.log(JSON.stringify({ ok: true, adopted: adopted.length, assets: adopted }));
   } else if (adopted.length === 0) {
@@ -218,7 +224,15 @@ if (args.analyze) {
     console.error(`error: --for file not found: ${mediaPath}`);
     process.exit(2);
   }
-  const analysis = analyzeMediaGrade(mediaPath);
+  let analysis;
+  try {
+    analysis = analyzeMediaGrade(mediaPath, {
+      ffmpegPath: ffmpegBinary(),
+      ffprobePath: ffprobeBinary(),
+    });
+  } catch (err) {
+    exitError(err.message);
+  }
   if (args.json) {
     console.log(JSON.stringify({ ok: true, type: "grade-analysis", ...analysis }));
   } else {
@@ -503,7 +517,8 @@ async function run() {
     // brand stays local: no frame.md/design.md -> upsell the HyperFrames design
     // flow rather than reporting a generic miss (B5).
     const msg =
-      providerFailure instanceof BundledSfxAssetsError
+      providerFailure instanceof BundledSfxAssetsError ||
+      providerFailure instanceof FfBinarySettingError
         ? providerFailure.message
         : type === "brand"
           ? "no brand spec found — add a frame.md or design.md (colors/font/logo) to this project. Run the HyperFrames design flow to create one; brand tokens are read locally for deterministic rendering."
@@ -594,7 +609,10 @@ function mergeSmartAdjust(block) {
   const mediaPath = resolve(args.for);
   // Clear upfront error beats an ffmpeg "No such file" stack on a typo'd path.
   if (!existsSync(mediaPath)) throw new Error(`--for file not found: ${mediaPath}`);
-  const analysis = analyzeMediaGrade(mediaPath);
+  const analysis = analyzeMediaGrade(mediaPath, {
+    ffmpegPath: ffmpegBinary(),
+    ffprobePath: ffprobeBinary(),
+  });
   console.error(formatMeasuredNote(mediaPath, analysis.measured));
   return {
     ...block,
@@ -1060,21 +1078,7 @@ function runDoctor() {
     checks.push(heygenAuthCheck());
   }
 
-  const ffmpegProbe = runCommand("ffmpeg", ["-version"]);
-  checks.push({
-    name: "ffmpeg on PATH",
-    ok: ffmpegProbe.status === 0,
-    detail: ffmpegProbe.status === 0 ? firstLine(ffmpegProbe.stdout) : "ffmpeg not found",
-    fix: ffmpegProbe.status === 0 ? "" : "brew install ffmpeg",
-  });
-
-  const ffprobeProbe = runCommand("ffprobe", ["-version"]);
-  checks.push({
-    name: "ffprobe on PATH",
-    ok: ffprobeProbe.status === 0,
-    detail: ffprobeProbe.status === 0 ? firstLine(ffprobeProbe.stdout) : "ffprobe not found",
-    fix: ffprobeProbe.status === 0 ? "" : "brew install ffmpeg",
-  });
+  checks.push(ffDoctorCheck("ffmpeg", ffmpegBinary), ffDoctorCheck("ffprobe", ffprobeBinary));
 
   const nodeOk = !versionLessThan(process.versions.node, MIN_NODE_VERSION);
   checks.push({
@@ -1140,6 +1144,28 @@ function printMap(label, values) {
   for (const [key, value] of entries) console.log(`  ${key}: ${value}`);
 }
 
+function ffDoctorCheck(name, binary) {
+  let bin;
+  try {
+    bin = binary();
+  } catch (err) {
+    return {
+      name: `${name} on PATH`,
+      ok: false,
+      detail: err.message,
+      fix: "fix or unset that variable",
+    };
+  }
+  const probe = runCommand(bin, ["-version"]);
+  const ok = probe.status === 0;
+  return {
+    name: `${name} on PATH`,
+    ok,
+    detail: ok ? firstLine(probe.stdout) : `${name} not found`,
+    fix: ok ? "" : "brew install ffmpeg",
+  };
+}
+
 function runCommand(bin, argv) {
   return spawnSync(bin, argv, {
     encoding: "utf8",

package/dist/skills/media-use/scripts/transcribe.mjs

@@ -12,7 +12,7 @@ import {
 } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { basename, extname, join, resolve } from "node:path";
-import { parseArgs } from "node:util";
+import { parseArgs, stripVTControlCharacters } from "node:util";
 import { mergeTokensToWords } from "./lib/parakeet-words.mjs";
 import { track } from "./lib/telemetry.mjs";
 import { resolveNpxInvocation } from "./lib/npx-sync.mjs";
@@ -49,7 +49,8 @@ Usage:
 
 Parakeet (default) beats whisper.cpp on accuracy + speed for English/European
 languages; whisper.cpp (99 languages) is the fallback. Install Parakeet once:
-  uv venv ~/.venvs/parakeet && VIRTUAL_ENV=~/.venvs/parakeet uv pip install parakeet-mlx`);
+  npx hyperframes models install parakeet   (macOS, Windows, Linux with glibc 2.32+)
+  uv venv ~/.venvs/parakeet && VIRTUAL_ENV=~/.venvs/parakeet uv pip install parakeet-mlx   (Apple Silicon)`);
   process.exit(0);
 }
 
@@ -122,33 +123,57 @@ function runParakeet(runner) {
   }
 }
 
-// whisper.cpp via the hyperframes CLI (fetched/built on first use — see
+// The hyperframes CLI (its Parakeet, else whisper.cpp built on first use — see
 // SKILL.md): writes transcript.json into --dir; relocate to --out.
-function runWhisper() {
+function runCli(cliEngine) {
   const workDir = mkdtempSync(join(tmpdir(), "media-use-whisper-"));
   try {
     // On Windows a bare "npx" is npx.cmd, which execFileSync cannot exec
     // (spawnSync npx ENOENT) — resolveNpxInvocation reroutes it through
     // node + npx-cli.js (and throws actionably when it can't), same
     // mechanism as the audio engine's TTS spawns.
+    // Under auto or parakeet the CLI may run its own Parakeet; --json says which engine ran.
     const resolved = resolveNpxInvocation(
-      ["hyperframes", "transcribe", inputPath, "--dir", workDir],
+      ["hyperframes", "transcribe", inputPath, "--dir", workDir, "--engine", cliEngine, "--json"],
       { stdio: ["ignore", "pipe", "pipe"], timeout: 1_800_000 },
     );
-    execFileSync(resolved.cmd, resolved.args, resolved.opts);
+    let stdout;
+    try {
+      stdout = String(execFileSync(resolved.cmd, resolved.args, resolved.opts));
+    } catch (e) {
+      // stderr holds spinner redraws and --json prints the reason on stdout, so keep the last lines.
+      const tail = stripVTControlCharacters(`${e.stderr ?? ""}\n${e.stdout ?? ""}`)
+        .split(/[\r\n]+/)
+        .map((l) => l.trim())
+        .filter((l) => l && l !== "│")
+        .slice(-3)
+        .join("\n");
+      throw new Error(
+        `hyperframes transcribe failed (exit ${e.status ?? e.code})${tail ? `:\n${tail}` : ""}`,
+      );
+    }
     const produced = join(workDir, "transcript.json");
-    if (!existsSync(produced)) throw new Error("whisper produced no transcript.json");
+    if (!existsSync(produced))
+      throw new Error("hyperframes transcribe produced no transcript.json");
     const tmp = `${outPath}.tmp-${process.pid}`;
     copyFileSync(produced, tmp);
     renameSync(tmp, outPath); // atomic publish
     let words;
     try {
       const t = JSON.parse(readFileSync(outPath, "utf8"));
-      words = Array.isArray(t?.words) ? t.words.length : undefined;
+      // The CLI writes a flat word array, not { words }.
+      words = Array.isArray(t) ? t.length : undefined;
     } catch {
       /* leave undefined */
     }
-    report("whisper", words);
+    let ran = "whisper";
+    try {
+      ran = JSON.parse(stdout.trim().split("\n").at(-1)).engine === "parakeet" ? "parakeet" : ran;
+    } catch {
+      /* no JSON line: keep whisper */
+    }
+    report(ran, words);
+    return ran;
   } finally {
     rmSync(workDir, { recursive: true, force: true });
   }
@@ -156,22 +181,11 @@ function runWhisper() {
 
 try {
   const parakeetBin = resolveParakeet();
-  const engine =
-    args.engine === "parakeet" || args.engine === "whisper"
-      ? args.engine
-      : parakeetBin
-        ? "parakeet"
-        : "whisper";
-  if (engine === "parakeet") {
-    if (!parakeetBin) {
-      throw new Error(
-        "parakeet-mlx not found (checked $HYPERFRAMES_PARAKEET, ~/.venvs/parakeet, and PATH). Install: uv venv ~/.venvs/parakeet && VIRTUAL_ENV=~/.venvs/parakeet uv pip install parakeet-mlx (or use --engine whisper)",
-      );
-    }
-    runParakeet(parakeetBin);
-  } else {
-    runWhisper();
-  }
+  const asked = args.engine === "parakeet" || args.engine === "whisper" ? args.engine : "auto";
+  // Without parakeet-mlx, the CLI's own Parakeet (any OS, `hyperframes models install parakeet`).
+  let engine = "parakeet";
+  if (asked !== "whisper" && parakeetBin) runParakeet(parakeetBin);
+  else engine = runCli(asked);
   await track("media_use_transcribe", { engine });
 } catch (err) {
   if (args.json) console.log(JSON.stringify({ ok: false, error: err.message }));