hyperframes doctor
Verify node, chromium, ffmpeg, and codec availability on the current machine. Optionally auto-fix what is missing.
hyperframes doctor runs a battery of environment checks and prints a report. Use it after a fresh clone, after a CI image change, or when render fails with exit code 4 or 5.
Synopsis
bash
hyperframes doctor [flags]The command never modifies your project. With --fix it may install the bundled chromium or prompt your package manager to update.
Flags
| Flag | Default | Meaning |
|---|---|---|
--fix | off | Attempt to repair missing dependencies (chromium, codec packs). |
--check <name> | all | Run only one check. Repeatable. |
--strict | off | Treat warnings as errors. |
Common invocations
$ hyperframes doctor
ok node v20.11.1
ok pnpm 8.15.4
ok chromium bundled 124.0.6367.91
ok ffmpeg 7.0.1
ok codec h264 libx264 yes
warn codec av1 libaom missing — install with: brew install ffmpeg --with-aom
ok disk space free 142 GB
ok 1 warning, 0 errorsSample full output
html
hyperframes doctor — 1.4.2
System
ok os darwin 23.5.0 arm64
ok node v20.11.1
ok pnpm 8.15.4
ok disk space free 142 GB
Browser
ok chromium bundled 124.0.6367.91
ok sandbox enabled
ok gpu swiftshader (headless)
Encoder
ok ffmpeg 7.0.1 /opt/homebrew/bin/ffmpeg
ok libx264 yes
ok libx265 yes
ok libvpx-vp9 yes
warn libaom-av1 missing
ok prores yes
Determinism
ok timezone shim loaded
ok font fallback stub installed
summary: 1 warning, 0 errorsJSON output
json
{
"command": "doctor",
"status": "ok",
"exit_code": 0,
"checks": [
{ "name": "node", "status": "ok", "value": "v20.11.1" },
{ "name": "chromium", "status": "ok", "value": "124.0.6367.91" },
{ "name": "ffmpeg", "status": "ok", "value": "7.0.1" },
{ "name": "codec.av1", "status": "warn", "message": "libaom missing" }
],
"warnings": 1,
"errors": 0
}Exit codes
0— all checks passed (or only warnings without--strict).1— at least one check failed, or--strictand any warning.4— ffmpeg missing entirely.5— chromium missing and--fixwas not passed.
Tips
- Run
doctoras the first step in your CI job. It surfaces image regressions before the render queue spins up. doctor --fixis idempotent. Safe to run on every container start.- The
disk spacecheck uses a 2 GB threshold; raise it viaHYPERFRAMES_MIN_FREE_GBif you batch-render a lot. - Output is grouped by category in
prettymode and flat in--json— script against the JSON, read the pretty form.
Next
- HyperFrames CLI — full command index.
hyperframes browser— install or prune the bundled chromium.