Skip to content

Write HTML. Render video. Built for agents.

docs(cli): explain FFmpeg setup without a package manager (#5237)

Abdullah M. Naziffe38e8fe12f1
diff --git a/skills-manifest.json b/skills-manifest.json
index 8c12b61295..49ddfb2a1e 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -30,7 +30,7 @@
"files": 7
},
"hyperframes-cli": {
- "hash": "b7f9a176ccf65fc7",
+ "hash": "c053e99be2d209b1",
"files": 11
},
"hyperframes-core": {
diff --git a/skills/hyperframes-cli/references/doctor-browser.md b/skills/hyperframes-cli/references/doctor-browser.md
index 96e12569fb..7b01899eea 100644
--- a/skills/hyperframes-cli/references/doctor-browser.md
+++ b/skills/hyperframes-cli/references/doctor-browser.md
@@ -28,7 +28,7 @@ Run `doctor` first when:
Common issues:
-- **Missing FFmpeg** — install via `brew install ffmpeg` (macOS) or your package manager.
+- **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
@@ -44,6 +44,29 @@ Common issues:
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.
+
+Alternatively, put the binaries in `.hyperframes/bin/ffmpeg` and `.hyperframes/bin/ffprobe` (`.exe` on Windows), then run HyperFrames from that project's directory. Discovery checks `PATH` before this project-local directory, so use the environment variables when you need a particular build.
+
+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