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.
Python agent-skillsai-agentsaudio-processingcaptionsclaude-codecodexcoding-agentcursorffmpegloudness-normalizationmcpmcp-servermodel-context-protocolpythonsubtitlestranscodingvideovideo-editingvideo-processingwhisper
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.mdindex 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.jsindex 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.pyindex 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, TupleINSTALL_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.pyindex 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_HINTShint = 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.pyindex 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"])