* fix(cli,parsers): take helper programs only from install locations, never the project folder FFmpeg, FFprobe, whisper-cli, parakeet-mlx, Python and system Chrome are now found through one shared rule: an absolute PATH entry outside the working directory, or a fixed install dir. A relative PATH entry and any folder inside the working directory are skipped, on every platform. Windows walks PATH itself instead of asking `where`, which lists the working directory first. FFmpeg discovery no longer falls back to `.hyperframes/bin` or to an installer package in the project's node_modules; an installer package installed next to HyperFrames still works. The env overrides are unchanged. The CLI skill reference stops suggesting the project-local folder. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(cli): give the PATH-lookup tests a fixed PATH on Windows Windows now walks PATH instead of running `where`, so tests that faked `where` output found the runner's real python and cmake. Both tests now set PATH to a temp folder holding only the programs they expect. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix: report a missing helper program instead of running it by bare name When no trusted FFmpeg or FFprobe is found, the engine, the producer's probes and Studio's waveform, peak and audio-track helpers now report "not found" with the HYPERFRAMES_FFMPEG_PATH / HYPERFRAMES_FFPROBE_PATH hint instead of handing the bare name to the OS lookup. Callers that degraded on a missing binary still do: runFfmpeg returns a spawn_error result, the GPU and version probes report none, and Studio's audio helpers fail soft. The Lambda handler names its bundled ffmpeg and ffprobe by path, since they live under the task root, which is the working directory. brew, git and cmake for the whisper.cpp install, and the clipboard tool for `hyperframes add`, run by the absolute path the trusted lookup approved. The media-use engine gets a PATH holding only trusted folders. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(engine): fail a missing FFmpeg the way a failed spawn always has Throwing from getFfmpegBinary turned every caller's missing-binary path into a synchronous throw: the streaming encoder's "failure result, not a throw" contract broke, and unit lanes that run without FFmpeg crashed at module load. With no trusted copy the getters now return an absolute path inside HyperFrames' own install that is never created, named for the override to set. Spawning it fails with ENOENT exactly as before, and the OS still never looks the bare name up. The call-site guards and fixture changes that the throw needed are reverted. The whisper install tests match git and cmake by name and skip the brew case on Windows, where the lookup walks the real PATH. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(engine): pin the found FFmpeg before the HDR test looks it up as macOS on Windows Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
4.3 KiB
doctor, browser
Environment diagnosis and bundled-Chrome management. Run these first when a render or preview fails.
doctor
npx hyperframes doctor
npx hyperframes doctor --json # CI / agent output (always exit 0; gate on payload `ok`)
Runs independent checks and reports each as ok/warn/fail:
- Version — installed CLI vs latest on npm (hints upgrade when stale)
- Node.js — ≥ 22 required
- CPU, Memory, Disk — host resources
- Environment — env vars that affect the renderer
- FFmpeg / FFprobe — found, version, codecs
- Chrome — bundled or system, version, path
- Docker / Docker running — required only for
render --docker - /dev/shm — inside containers only
Run doctor first when:
renderfails with a Chrome or FFmpeg error.previewopens but the composition fails to load.- A fresh machine has never run HyperFrames.
Common issues:
- Missing FFmpeg — install via
brew install ffmpeg(macOS) or your package manager, or configure existing binaries. - Missing bundled Chrome — run
npx hyperframes browser ensure. - Low memory — close other Chromes, reduce
--workers, or use--quality draft. - Chrome exits instantly inside an agent sandbox (macOS) — seatbelt-style sandboxes
(e.g. codex
workspace-write) block Chromium's Mach port bootstrap (MachPortRendezvous; openai/codex#21292), so every Chrome — bundled, system, or headless shell — dies at startup. This is a host-level block, not a HyperFrames or Chrome install problem: compile checks and audio still pass, only rendering is unavailable. State the blocker and deliver the checked composition; render outside the sandbox or viarender --docker/ cloud rendering where available. Do not build a substitute rasterizer (magick/PIL/SVG frame pipelines) — on a blocked-browser host the deliverable IS the checked composition plus this blocker note, and rendering is handed to--docker, cloud, or the user. Write your final summary the moment the blocker is identified, BEFORE any optional fallback work: a later session failure must not erase the report of work already done.
Configure FFmpeg without a package manager
Get FFmpeg and FFprobe binaries for your operating system and architecture from the FFmpeg download page. Both must be executable. You can use them without Homebrew or a system-wide installation:
export HYPERFRAMES_FFMPEG_PATH="/absolute/path/to/ffmpeg"
export HYPERFRAMES_FFPROBE_PATH="/absolute/path/to/ffprobe"
npx hyperframes doctor --json
Set both variables in the environment that launches HyperFrames. On Windows, point them at ffmpeg.exe and ffprobe.exe using your shell's environment-variable syntax. A configured path takes precedence over automatic discovery; a missing configured file is reported as missing.
Automatic discovery never runs an FFmpeg or FFprobe that sits inside the project folder or the working directory, such as .hyperframes/bin or a project's @ffmpeg-installer package, since a project can come from anyone. Keep the binaries outside the project and either set the variables above or add their folder to PATH as an absolute path.
Verify the FFmpeg and FFprobe entries in doctor --json report ok: true and the expected paths. To gate only these encoding dependencies with jq:
npx hyperframes doctor --json | jq -e \
'[.checks[] | select(.name == "FFmpeg" or .name == "FFprobe")] | length == 2 and all(.ok)'
The report's top-level ok also includes optional tools such as Docker and local voice providers; those failures do not require installing them for a local video render. Check Chrome separately with the browser commands below.
browser
npx hyperframes browser ensure # find or download the pinned Chrome
npx hyperframes browser path # print the browser executable path (for scripting)
npx hyperframes browser clear # remove the cached Chrome download
Manage the Chrome build HyperFrames uses for rendering. The pinned version exists because pixel output drifts across Chrome versions — using the bundled build keeps rendered output reproducible across machines.
Use path to embed the binary in scripts: $(npx hyperframes browser path).