Skip to content

Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.

fix(install): macOS ffmpeg-full is keg-only, so say how to put it on PATH (#319)

Ryan Maliae51e18a3f513
diff --git a/README.md b/README.md
index cae8a84..3ed824a 100644
--- a/README.md
+++ b/README.md
@@ -480,10 +480,15 @@ FFmpeg itself:
| OS | Command |
|----|---------|
-| macOS | `brew install ffmpeg-full` (the plain `ffmpeg` formula lacks the subtitles, drawtext and zscale filters) |
+| macOS | `brew install ffmpeg-full`, then put it on `PATH` (below). The plain `ffmpeg` formula lacks the subtitles, drawtext and zscale filters |
| Ubuntu / Debian | `sudo apt install ffmpeg` |
| Windows | `winget install Gyan.FFmpeg` |
+**On macOS, `ffmpeg-full` is keg-only:** Homebrew installs it without linking it, so after `brew install ffmpeg-full` the `ffmpeg` on `PATH` is still the lean `ffmpeg` formula (often present as a dependency of another formula), or no `ffmpeg` at all, so `doctor` keeps reporting `ffmpeg`, or the `subtitles` and `drawtext` filters, as missing. Make it the one the tools find, in one of two ways:
+
+- **Put it first on `PATH`.** Add `export PATH="$(brew --prefix ffmpeg-full)/bin:$PATH"` to your shell profile. `brew --prefix ffmpeg-full` is the stable `opt/` path, so this survives upgrades, but it only reaches processes started from a shell that read the profile.
+- **Link it over the lean formula:** `brew unlink ffmpeg 2>/dev/null; brew link --overwrite --force ffmpeg-full`. Every process finds this one, but `brew doctor` warns about a linked keg-only formula, and an upgrade of the lean `ffmpeg` has been seen to link the lean build back on top without a message. After upgrading, check that `command -v ffmpeg` still resolves into `ffmpeg-full`, and re-run the link if it doesn't.
+
## Requirements
- FFmpeg 5.0+. Always required: `libx264`, `aac`, and the `drawtext`, `subtitles` (libass), `loudnorm`, `xfade`, `acrossfade`, `scdet`, `silencedetect` and `tile` filters. Needed only by the flags that use them: `libx265`, `prores_ks`, `libzimg` / `zscale`, `libmp3lame`, `libopus`, `libvorbis`, the `ass` filter. `doctor` tells you which are present. The apt and gyan.dev builds carry all of them; some Homebrew bottles lack `libass` / `libfreetype` / `libzimg`, which `doctor` reports as missing.
diff --git a/bin/install.js b/bin/install.js
index 22927f3..e416c27 100755
--- a/bin/install.js
+++ b/bin/install.js
@@ -94,7 +94,9 @@ function checkFfmpeg() {
const r = spawnSync('ffmpeg', ['-version'], { encoding: 'utf8' });
if (r.error || r.status !== 0) {
console.warn('\n warning: ffmpeg was not found on PATH. The skill needs FFmpeg to run:');
- console.warn(' macOS: brew install ffmpeg-full (the plain ffmpeg formula lacks subtitles/drawtext/zscale)');
+ console.warn(' macOS: brew install ffmpeg-full; export PATH="$(brew --prefix ffmpeg-full)/bin:$PATH"');
+ console.warn(' # keg-only, so installing it does not put it on PATH: keep the export in your shell profile;');
+ console.warn(' # the plain ffmpeg formula lacks subtitles/drawtext/zscale');
console.warn(' Ubuntu: sudo apt install ffmpeg');
console.warn(' Windows: winget install Gyan.FFmpeg\n');
return false;
diff --git a/scripts/_common/runner.py b/scripts/_common/runner.py
index 6dcc8ee..52aa955 100644
--- a/scripts/_common/runner.py
+++ b/scripts/_common/runner.py
@@ -18,7 +18,9 @@ from typing import Any, Dict, List, Optional, Sequence, Tuple
INSTALL_HINTS = {
- "Darwin": " brew install ffmpeg-full (the plain ffmpeg formula lacks subtitles/drawtext/zscale)",
+ "Darwin": (" brew install ffmpeg-full; export PATH=\"$(brew --prefix ffmpeg-full)/bin:$PATH\""
+ " # keg-only, so installing it does not put it on PATH: keep the export in your shell profile;"
+ " the plain ffmpeg formula lacks subtitles/drawtext/zscale"),
"Linux": (
" Debian/Ubuntu: sudo apt install ffmpeg\n"
" Fedora: sudo dnf install ffmpeg\n"
diff --git a/scripts/_contract.py b/scripts/_contract.py
index 22727c6..c958f26 100644
--- a/scripts/_contract.py
+++ b/scripts/_contract.py
@@ -1011,10 +1011,15 @@ def _capability_fix_hint(cap: str) -> str:
if cap in ("ffmpeg", "ffprobe"):
from _common import INSTALL_HINTS
hint = INSTALL_HINTS.get(platform.system(), "see https://ffmpeg.org/download.html").strip().splitlines()[0].strip()
- return f"install ffmpeg: {hint}"
+ # a hint's "# why" is a shell comment so the printed line pastes; joined into a fix string
+ # with "; " it would swallow what follows, so show it in parentheses here instead
+ cmd, _, why = hint.partition("#")
+ return f"install ffmpeg: {cmd.strip()} ({why.strip()})" if why else f"install ffmpeg: {hint}"
system = platform.system()
if system == "Darwin":
- full_hint = "on macOS, brew install ffmpeg-full (the plain formula lacks subtitles/drawtext/zscale)"
+ full_hint = ("on macOS, brew install ffmpeg-full; export PATH=\"$(brew --prefix ffmpeg-full)/bin:$PATH\" "
+ "(ffmpeg-full is keg-only, so installing it does not replace the ffmpeg already found: keep the "
+ "export in your shell profile; the plain formula lacks subtitles/drawtext/zscale)")
elif system == "Windows":
full_hint = "on Windows, winget install Gyan.FFmpeg (the gyan.dev full build carries subtitles/drawtext/zscale; a plain choco ffmpeg package can lack them)"
else:
diff --git a/tests/test_contract.py b/tests/test_contract.py
index d498272..4c355a6 100644
--- a/tests/test_contract.py
+++ b/tests/test_contract.py
@@ -796,6 +796,24 @@ class ContractTests(unittest.TestCase):
readme = (ROOT / "README.md").read_text(encoding="utf-8")
self.assertIn("Gyan.FFmpeg", readme)
+ def test_macos_fix_hint_says_ffmpeg_full_is_keg_only(self):
+ """Homebrew's ffmpeg-full is keg-only: `brew install ffmpeg-full` alone leaves the lean
+ formula (or no ffmpeg) on PATH, so a hint that only says to install it sends the user
+ round in a loop. Both the missing-filter and the missing-ffmpeg hints must name the PATH
+ step, and README must document the same command."""
+ from unittest import mock
+ path_step = 'export PATH="$(brew --prefix ffmpeg-full)/bin:$PATH"'
+ with mock.patch("platform.system", return_value="Darwin"):
+ for cap in ("filter:subtitles", "ffmpeg"):
+ hint = _contract._capability_fix_hint(cap)
+ self.assertIn(path_step, hint, cap)
+ self.assertIn("keg-only", hint, cap)
+ readme = (ROOT / "README.md").read_text(encoding="utf-8")
+ self.assertIn(path_step, readme)
+ self.assertIn("keg-only", readme)
+ installer = (ROOT / "bin" / "install.js").read_text(encoding="utf-8")
+ self.assertIn(path_step, installer, "the npm installer's missing-ffmpeg warning gives the same command")
+
def test_original_preservation_and_roles(self):
for t in self.contract["tools"]:
self.assertFalse(t["mutates_input"], t["name"])