Skip to content

Commit 41b62f9

Browse files
fix(skills): win32-safe npx spawns in media-use + accurate whisper wording
The Whisper transcribe fallback and the Kokoro local-TTS delegation both spawned a bare "npx" via execFileSync — on Windows npx is npx.cmd, which spawn cannot exec, so both paths died with `spawnSync npx ENOENT`. Route them through the skill's existing resolveSpawnCommand (node + npx-cli.js on win32, no shell:true), same as the audio engine's TTS spawns. Also corrects the "bundled with the hyperframes CLI" claim about whisper.cpp: it is resolved from PATH / installed via Homebrew / built from source with git+cmake on first use, and models download from HuggingFace — nothing whisper is shipped in the package. Co-Authored-By: Claude Opus 4.8 <[email protected]>
1 parent ee7ef45 commit 41b62f9

6 files changed

Lines changed: 143 additions & 29 deletions

File tree

‎skills-manifest.json‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -22,19 +22,19 @@
2222
"files": 1
2323
},
2424
"hyperframes-animation": {
25-
"hash": "70705a50c3adea48",
25+
"hash": "759f42c2e1e7eb7c",
2626
"files": 102
2727
},
2828
"hyperframes-cli": {
29-
"hash": "fbe17780248d5bec",
29+
"hash": "35055ee03c2b3752",
3030
"files": 8
3131
},
3232
"hyperframes-core": {
3333
"hash": "690ebb3ba5420b90",
3434
"files": 14
3535
},
3636
"hyperframes-creative": {
37-
"hash": "ffe13c76b89ce3d1",
37+
"hash": "5dd20191d33c7817",
3838
"files": 78
3939
},
4040
"hyperframes-keyframes": {
@@ -46,8 +46,8 @@
4646
"files": 10
4747
},
4848
"media-use": {
49-
"hash": "11f3025c7c97dd8f",
50-
"files": 124
49+
"hash": "a20b4ae436bd5cb8",
50+
"files": 125
5151
},
5252
"motion-graphics": {
5353
"hash": "dafcdce07d221aa4",
@@ -62,7 +62,7 @@
6262
"files": 28
6363
},
6464
"product-launch-video": {
65-
"hash": "b59c8f1ec7fdc7bd",
65+
"hash": "b344036156ff77ab",
6666
"files": 23
6767
},
6868
"remotion-to-hyperframes": {

‎skills/media-use/SKILL.md‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -373,15 +373,15 @@ tools are OPT-IN alternatives where they exist; install one to unlock its free,
373373
private, on-device path instead of or ahead of HeyGen for that type. Only
374374
`ffmpeg`/`ffprobe` are strictly required for the tool to run at all.
375375

376-
| Tool | Serves | Install |
377-
| ------------------ | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
378-
| `ffmpeg`/`ffprobe` | adopt probing, smart-grade signalstats, cut, duck bake, loudnorm | system package (`brew install ffmpeg`) |
379-
| `heygen` | catalog (bgm/sfx/image/icon) + TTS (voice) + avatar video — the free-usage path | `curl -fsSL https://static.heygen.ai/cli/install.sh \| bash` then `heygen auth login --oauth` (needs >= v0.3.0) |
380-
| `mflux-generate` | local image gen (FLUX), best-for-RAM | `uv venv ~/.venvs/mflux && VIRTUAL_ENV=~/.venvs/mflux uv pip install mflux==0.9.6` |
381-
| `codex` | image gen upsell (ChatGPT sub) | Codex CLI, logged in via ChatGPT (owns its own auth) |
382-
| `parakeet-mlx` | local transcription (default ASR, best) | `uv venv ~/.venvs/parakeet && VIRTUAL_ENV=~/.venvs/parakeet uv pip install parakeet-mlx` |
383-
| `ltx-2-mlx` | local video gen | `git clone https://github.com/dgrauet/ltx-2-mlx && cd ltx-2-mlx && uv sync --all-extras` |
384-
| `npx hyperframes` | Kokoro TTS (voice), whisper.cpp (transcribe fallback), remove-background | bundled with the hyperframes CLI |
376+
| Tool | Serves | Install |
377+
| ------------------ | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
378+
| `ffmpeg`/`ffprobe` | adopt probing, smart-grade signalstats, cut, duck bake, loudnorm | system package (`brew install ffmpeg`) |
379+
| `heygen` | catalog (bgm/sfx/image/icon) + TTS (voice) + avatar video — the free-usage path | `curl -fsSL https://static.heygen.ai/cli/install.sh \| bash` then `heygen auth login --oauth` (needs >= v0.3.0) |
380+
| `mflux-generate` | local image gen (FLUX), best-for-RAM | `uv venv ~/.venvs/mflux && VIRTUAL_ENV=~/.venvs/mflux uv pip install mflux==0.9.6` |
381+
| `codex` | image gen upsell (ChatGPT sub) | Codex CLI, logged in via ChatGPT (owns its own auth) |
382+
| `parakeet-mlx` | local transcription (default ASR, best) | `uv venv ~/.venvs/parakeet && VIRTUAL_ENV=~/.venvs/parakeet uv pip install parakeet-mlx` |
383+
| `ltx-2-mlx` | local video gen | `git clone https://github.com/dgrauet/ltx-2-mlx && cd ltx-2-mlx && uv sync --all-extras` |
384+
| `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 |
385385

386386
The RAM-graded local-model shortlist + exact per-tier install/invoke lives in
387387
`scripts/lib/local-models.mjs` (the agent can read `describeModelLadder(cap, specs)`

‎skills/media-use/audio/references/requirements.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ Each command downloads its own model on first run and caches it under `~/.cache/
2323
- **TTS (Kokoro)** — Kokoro-82M (~311 MB) + voices (~27 MB) in `tts/`. Requires Python 3.8+ with `kokoro-onnx` and `soundfile` (`pip install kokoro-onnx soundfile`). Non-English text also needs `espeak-ng` system-wide.
2424
- **BGM (Lyria)** — needs `$GEMINI_API_KEY` or `$GOOGLE_API_KEY` + `pip install google-genai`. No local model cache.
2525
- **BGM (MusicGen)** — `pip install transformers torch soundfile`. `facebook/musicgen-small` (~300 MB) cached under `~/.cache/huggingface/` on first run.
26-
- **Transcribe** — Whisper model size depending on choice (75 MB – 3.1 GB) in `whisper/`. Bundles `whisper.cpp`.
26+
- **Transcribe** — Whisper model size depending on choice (75 MB – 3.1 GB) in `whisper/`, downloaded from HuggingFace on first use. `whisper.cpp` itself is NOT bundled: the CLI resolves it from PATH, installs via Homebrew (macOS), or builds it from source with git+cmake on first use (`$HYPERFRAMES_WHISPER_PATH` overrides).
2727
- **Remove-background** — `u2net_human_seg` (~168 MB ONNX) in `background-removal/models/`. Peak inference RAM ~1.5 GB.
2828

2929
Run `npx hyperframes doctor` if a command fails because of a missing dependency.

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

Lines changed: 34 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import { execFileSync } from "node:child_process";
22
import { existsSync, statSync } from "node:fs";
33
import { tmpdir } from "node:os";
44
import { join } from "node:path";
5+
import { resolveSpawnCommand } from "../../audio/scripts/lib/tts.mjs";
56

67
// Local voiceover via the packaged Kokoro-82M TTS (the `hyperframes tts` CLI),
78
// the free/private default now that HeyGen TTS costs wallet credits. Kokoro runs
@@ -26,17 +27,44 @@ function probeDurationSeconds(file) {
2627
}
2728
}
2829

29-
export async function localTtsGenerate(intent, ctx) {
30+
// `platform`/`execFn`/`env`/`pathExists` params (defaulting to the real
31+
// values) exist so tests can exercise the win32 branch without mocking
32+
// node:child_process (its ESM exports are non-configurable) — same idiom as
33+
// spawnP in ../../audio/scripts/lib/tts.mjs.
34+
export async function localTtsGenerate(
35+
intent,
36+
ctx,
37+
platform = process.platform,
38+
execFn = execFileSync,
39+
env = process.env,
40+
pathExists = existsSync,
41+
) {
3042
const outPath = join(tmpdir(), `media-use-kokoro-${process.pid}-${Date.now()}.wav`);
3143
const argv = ["hyperframes", "tts", intent, "--output", outPath];
3244
if (ctx?.voice) argv.push("--voice", ctx.voice);
3345
if (ctx?.lang && ctx.lang !== "en") argv.push("--lang", ctx.lang);
46+
// On Windows a bare "npx" is npx.cmd, which execFileSync cannot exec
47+
// (spawnSync npx ENOENT) — resolveSpawnCommand reroutes it through
48+
// node + npx-cli.js, same as the audio engine's TTS spawns.
49+
const resolved = resolveSpawnCommand(
50+
"npx",
51+
argv,
52+
{ encoding: "utf8", timeout: 300000, stdio: ["ignore", "pipe", "pipe"] },
53+
platform,
54+
env,
55+
pathExists,
56+
);
57+
if (!resolved) {
58+
// npx-on-win32 with no resolvable npx-cli.js — same terminal condition
59+
// spawnP warns about. Fall through to the next provider rather than crash.
60+
console.error(
61+
"media-use: local voice not enabled (kokoro). Cannot run npx on Windows: " +
62+
"npm's npx-cli.js was not found (install npm with Node, or run via npx/npm run so npm_execpath is set).",
63+
);
64+
return null;
65+
}
3466
try {
35-
execFileSync("npx", argv, {
36-
encoding: "utf8",
37-
timeout: 300000,
38-
stdio: ["ignore", "pipe", "pipe"],
39-
});
67+
execFn(resolved.cmd, resolved.args, resolved.opts);
4068
} catch (err) {
4169
// `hyperframes tts` prints its "kokoro-onnx not installed" hint to stdout
4270
// (clack UI), so read both streams and surface the actionable enable-command
Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
import { test } from "node:test";
2+
import assert from "node:assert/strict";
3+
import { localTtsGenerate } from "./tts-local-provider.mjs";
4+
5+
// Regression: on Windows, a bare "npx" is npx.cmd, which execFileSync cannot
6+
// exec — the Kokoro delegation failed with `spawnSync npx ENOENT` instead of
7+
// synthesizing (or cleanly falling through to the next provider). The spawn
8+
// must route through node + npx-cli.js on win32, same as the audio engine's
9+
// TTS spawns (see ../../audio/scripts/lib/tts.spawn.test.mjs).
10+
11+
const envWithNpxCli = {
12+
npm_execpath: "C:/Program Files/nodejs/node_modules/npm/bin/npm-cli.js",
13+
npm_node_execpath: "C:/Program Files/nodejs/node.exe",
14+
};
15+
const npxCliPath = "C:/Program Files/nodejs/node_modules/npm/bin/npx-cli.js";
16+
const pathExists = (path) => path === npxCliPath;
17+
18+
test("win32: routes the hyperframes tts call through node + npx-cli, never bare npx", async () => {
19+
const captured = [];
20+
const fakeExec = (cmd, args, opts) => {
21+
captured.push({ cmd, args, opts });
22+
// Synthesize nothing — the provider then returns null via the
23+
// missing-output check, which is fine: we only assert the spawn shape.
24+
};
25+
26+
await localTtsGenerate(
27+
"hello there",
28+
{ voice: "am_michael" },
29+
"win32",
30+
fakeExec,
31+
envWithNpxCli,
32+
pathExists,
33+
);
34+
35+
assert.equal(captured.length, 1);
36+
assert.equal(captured[0].cmd, envWithNpxCli.npm_node_execpath);
37+
assert.equal(captured[0].args[0], npxCliPath);
38+
assert.deepEqual(captured[0].args.slice(1, 4), ["hyperframes", "tts", "hello there"]);
39+
assert.ok(captured[0].args.includes("--voice"));
40+
// execFileSync options survive the rerouting (pipes are what let the caller
41+
// read the "kokoro-onnx not installed" hint back out).
42+
assert.deepEqual(captured[0].opts.stdio, ["ignore", "pipe", "pipe"]);
43+
});
44+
45+
test("win32 without a resolvable npx-cli: falls through to the next provider (null), no spawn", async () => {
46+
const captured = [];
47+
const fakeExec = (...call) => captured.push(call);
48+
49+
const result = await localTtsGenerate(
50+
"hello",
51+
{},
52+
"win32",
53+
fakeExec,
54+
{}, // no npm_execpath, and pathExists finds nothing
55+
() => false,
56+
);
57+
58+
assert.equal(result, null);
59+
assert.equal(captured.length, 0);
60+
});
61+
62+
test("non-win32: spawns plain npx unchanged", async () => {
63+
const captured = [];
64+
const fakeExec = (cmd, args) => captured.push({ cmd, args });
65+
66+
await localTtsGenerate("hola", { lang: "es" }, "darwin", fakeExec, {}, () => false);
67+
68+
assert.equal(captured.length, 1);
69+
assert.equal(captured[0].cmd, "npx");
70+
assert.deepEqual(captured[0].args.slice(0, 3), ["hyperframes", "tts", "hola"]);
71+
assert.ok(captured[0].args.includes("--lang"));
72+
});

‎skills/media-use/scripts/transcribe.mjs‎

Lines changed: 21 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ import { basename, extname, join, resolve } from "node:path";
1515
import { parseArgs } from "node:util";
1616
import { mergeTokensToWords } from "./lib/parakeet-words.mjs";
1717
import { track } from "./lib/telemetry.mjs";
18+
import { resolveSpawnCommand } from "../audio/scripts/lib/tts.mjs";
1819

1920
// The DEFAULT local transcription path. Prefers NVIDIA Parakeet-TDT via
2021
// parakeet-mlx, which beats whisper.cpp on the Open ASR Leaderboard (~6.05% vs
@@ -24,8 +25,9 @@ import { track } from "./lib/telemetry.mjs";
2425
// captions / the audio engine.
2526
//
2627
// Parakeet v3 covers English + 25 European languages. For other languages, or
27-
// when parakeet-mlx is not installed, it falls back to the packaged whisper.cpp
28-
// (`hyperframes transcribe`, 99 languages). `--engine` forces one.
28+
// when parakeet-mlx is not installed, it falls back to whisper.cpp via
29+
// `hyperframes transcribe` (99 languages; the CLI resolves/builds whisper.cpp
30+
// on first use — it is not bundled). `--engine` forces one.
2931

3032
const { values: args } = parseArgs({
3133
options: {
@@ -120,14 +122,26 @@ function runParakeet(runner) {
120122
}
121123
}
122124

123-
// whisper.cpp via the packaged CLI: writes transcript.json into --dir; relocate to --out.
125+
// whisper.cpp via the hyperframes CLI (fetched/built on first use — see
126+
// SKILL.md): writes transcript.json into --dir; relocate to --out.
124127
function runWhisper() {
125128
const workDir = mkdtempSync(join(tmpdir(), "media-use-whisper-"));
126129
try {
127-
execFileSync("npx", ["hyperframes", "transcribe", inputPath, "--dir", workDir], {
128-
stdio: ["ignore", "pipe", "pipe"],
129-
timeout: 1_800_000,
130-
});
130+
// On Windows a bare "npx" is npx.cmd, which execFileSync cannot exec
131+
// (spawnSync npx ENOENT) — resolveSpawnCommand reroutes it through
132+
// node + npx-cli.js, same as the audio engine's TTS spawns.
133+
const resolved = resolveSpawnCommand(
134+
"npx",
135+
["hyperframes", "transcribe", inputPath, "--dir", workDir],
136+
{ stdio: ["ignore", "pipe", "pipe"], timeout: 1_800_000 },
137+
);
138+
if (!resolved) {
139+
throw new Error(
140+
"cannot run npx on Windows: npm's npx-cli.js was not found " +
141+
"(install npm with Node, or run via npx/npm run so npm_execpath is set)",
142+
);
143+
}
144+
execFileSync(resolved.cmd, resolved.args, resolved.opts);
131145
const produced = join(workDir, "transcript.json");
132146
if (!existsSync(produced)) throw new Error("whisper produced no transcript.json");
133147
const tmp = `${outPath}.tmp-${process.pid}`;

0 commit comments

Comments
 (0)