Files
hyperframes/skills/hyperframes-cli/references/doctor-browser.md
T
James RussoandClaude Opus 5.5 84799bdc59 fix: take helper programs only from install locations, never the project folder (#7524)
* 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>
2026-11-11 09:46:52 +00:00

81 lines
4.3 KiB
Markdown

# doctor, browser
Environment diagnosis and bundled-Chrome management. Run these first when a render or preview fails.
## doctor
```bash
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:
- `render` fails with a Chrome or FFmpeg error.
- `preview` opens 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](#configure-ffmpeg-without-a-package-manager).
- **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 via `render --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](https://ffmpeg.org/download.html). Both must be executable. You can use them without Homebrew or a system-wide installation:
```bash
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`:
```bash
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
```bash
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)`.