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: improve ffmpeg 8+ windows caption and color compatibility
kajisho59b43bcbde0fb
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex cb3f025..8c8f6ea 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -26,7 +26,11 @@ jobs:run: sudo apt-get update && sudo apt-get install -y ffmpeg fonts-dejavu-core- name: Install ffmpeg (macOS)if: runner.os == 'macOS'- run: brew install ffmpeg+ # Homebrew's `ffmpeg` formula no longer links libass / freetype / harfbuzz / zimg, so it has no+ # subtitles, ass, drawtext or zscale filter; `ffmpeg-full` does. It is keg-only: put it on PATH.+ run: |+ brew install ffmpeg-full+ echo "$(brew --prefix ffmpeg-full)/bin" >> "$GITHUB_PATH"- name: Install ffmpeg (Windows)if: runner.os == 'Windows'run: choco install ffmpeg -y --no-progressdiff --git a/CHANGELOG.md b/CHANGELOG.mdindex ef5e877..cef9e7b 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,5 +1,14 @@# Changelog+## Unreleased — FFmpeg 8+ / Windows compatibility for caption and color++- **Filter file paths on Windows.** `subtitles=`, `ass=`, `lut3d=file=`, `fontfile=` and `fontsdir=` values are parsed twice by ffmpeg (graph, then filter options), so a drive letter needs two levels of colon escaping (`D\\\\:/x.srt`). 0.9.1 escaped once and every caption / LUT job on Windows failed with `Unable to parse "original_size" option value` or `Error parsing a filter description`. `escape_filter_path` now escapes for both passes; `;` is escaped too. Reproduced and tested on Linux with a directory literally named `D:` plus spaces and non-ASCII in the path.+- **`overlay.py --image` length on FFmpeg 7+.** `-shortest` alone left up to 2 s of the looped still after the video ended (8.1 / 9.0); the command now also passes `-t <video duration>`.+- **`--help` on a legacy Windows console.** stdout / stderr are reconfigured to UTF-8 (with replacement) by `_common`, so non-ASCII help text (Japanese example, arrows) no longer raises `UnicodeEncodeError`; the test harness decodes script output as UTF-8.+- **macOS CI** installs `ffmpeg-full`: Homebrew's `ffmpeg` formula no longer links libass / freetype / harfbuzz / zimg, so it has no `subtitles`, `ass`, `drawtext` or `zscale` filter. README and the installer hint say so.+- Tests: the contract-test fixture used `-vsync vfr`, an option FFmpeg 9 removed (`-fps_mode vfr` since 5.1); filter paths with a drive colon, spaces and Unicode through caption (SRT, ASS, fonts dir), color (LUT full and blended) and overlay (`fontfile`), with PSNR proving the caption and LUT changed the picture; overlay still bounded by the video length; `--help` under a cp1252 console.++## 0.9.1 — FFmpeg 8 capability detection; audio extraction, audio join, sample-accurate trims, typed dynamics- **doctor / contract on FFmpeg 8.** `ffmpeg -filters` prints two flag characters on FFmpeg 8 (`T. acompressor A->A`) where 6 and 7 print three (`..C`); 0.9.0 anchored on three and reported every `filter:*` capability missing on FFmpeg 8 (macOS / Windows CI of consumers). Rows are now recognised by their `A->A` io-spec token, encoders by the `------` separator, so the flag width no longer matters. A listing that cannot be read yields a third state, `unknown`, distinct from `missing` (an installed filter is never reported absent) and from `available` (a failed detection is never a pass); `detection` and `errors` say which listing failed and why; exit 2 for "required but unknown". Existing keys unchanged. Fixtures for the 6.1 capture and the 7 / 8 layouts in `tests/fixtures/`, tests through a fake ffmpeg.diff --git a/README.md b/README.mdindex 1da5703..5d66383 100644--- a/README.md+++ b/README.md@@ -289,7 +289,7 @@ FFmpeg itself:| OS | Command ||----|---------|-| macOS | `brew install ffmpeg` |+| macOS | `brew install ffmpeg-full` (the plain `ffmpeg` formula lacks the subtitles, drawtext and zscale filters) || Ubuntu / Debian | `sudo apt install ffmpeg` || Windows | `winget install Gyan.FFmpeg` |diff --git a/bin/install.js b/bin/install.jsindex c434d0f..e94ef9d 100755--- a/bin/install.js+++ b/bin/install.js@@ -77,7 +77,7 @@ 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');+ console.warn(' macOS: brew install ffmpeg-full (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.py b/scripts/_common.pyindex 2f03c18..27edf6a 100755--- a/scripts/_common.py+++ b/scripts/_common.py@@ -16,6 +16,16 @@ from fractions import Fractionfrom pathlib import Pathfrom typing import Any, Dict, List, Optional, Sequence+# Every script prints paths, help text and reports that may contain non-ASCII (Japanese examples,+# arrows). On Windows the console streams default to a legacy code page and raise+# UnicodeEncodeError; make them UTF-8 with replacement so a --help never crashes on encoding.+for _stream in (sys.stdout, sys.stderr):+ try:+ if getattr(_stream, "encoding", "").lower().replace("-", "") != "utf8":+ _stream.reconfigure(encoding="utf-8", errors="replace")+ except (AttributeError, ValueError):+ pass+INSTALL_HINTS = {"Darwin": " brew install ffmpeg","Linux": (@@ -366,10 +376,21 @@ def fmt_srt_time(seconds: float) -> str:def escape_filter_path(path: str) -> str:- """Escape a path for use inside an ffmpeg filter graph option value."""+ """Escape a file path for use as a filter option value (subtitles=, ass=, lut3d=file=, fontfile=, fontsdir=).++ A filter option value is parsed twice: the graph parser splits filters on `,` / `;` and options+ on `:`, then the filter's own option parser splits key=value pairs on `:` again. A character that+ must survive both passes needs two levels of escaping, so a Windows drive letter `D:/x.srt` is+ written `D\\\\:/x.srt`; with a single backslash the second pass still splits at the colon and+ ffmpeg reads `/x.srt` as the next option (`Unable to parse "original_size" option value`).+ Backslashes are turned into forward slashes first (ffmpeg accepts them on Windows), so a backslash+ never has to be escaped itself; `'`, `,`, `;`, `[` and `]` are graph-level characters.+ """p = str(Path(path))p = p.replace("\\", "/")- p = p.replace(":", "\\:").replace("'", "\\'").replace(",", "\\,").replace("[", "\\[").replace("]", "\\]")+ p = p.replace(":", "\\\\:")+ for ch in ("'", ",", ";", "[", "]"):+ p = p.replace(ch, "\\" + ch)return pdiff --git a/scripts/overlay.py b/scripts/overlay.pyindex 59d4c4d..1d63270 100755--- a/scripts/overlay.py+++ b/scripts/overlay.py@@ -165,6 +165,11 @@ def main() -> int:cmd = ffmpeg_base() + ["-i", args.input, "-loop", "1", "-i", args.image]fc = f"[1:v]{','.join(chain)},setpts=PTS-STARTPTS[ov];[0:v][ov]{ov}[out]"cmd += ["-filter_complex", fc, "-map", "[out]", "-map", "0:a:0?", "-shortest"]+ # -shortest alone is not exact on FFmpeg 7+: the muxer keeps up to shortest_buf_duration (10 s)+ # of the looped still after the video ended, and the file came out 2 s long on 8.1 / 9.0.+ # The output must be as long as the main input, so say so explicitly.+ if meta.get("duration"):+ cmd += ["-t", f"{meta['duration']:.3f}"]else:x, y = position_exprs(args.position, args.margin, text_mode=True)opts = [f"text='{escape_drawtext(args.text)}'", f"fontsize={args.font_size}", f"x={x}", f"y={y}",diff --git a/tests/test_all.py b/tests/test_all.pyindex f6d60a2..1ab72cc 100644--- a/tests/test_all.py+++ b/tests/test_all.py@@ -23,7 +23,7 @@ TONES = ("0.6*sin(2*PI*440*t)*gt(sin(2*PI*0.37*t)\\,0.3)+0.4*sin(2*PI*880*t)*gt(def sh(*cmd, expect_fail=False):- proc = subprocess.run([str(c) for c in cmd], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)+ proc = subprocess.run([str(c) for c in cmd], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, encoding="utf-8", errors="replace")if expect_fail:assert proc.returncode != 0, f"expected failure but succeeded: {cmd}"return proc@@ -1039,6 +1039,83 @@ class FFmpegSkillTests(unittest.TestCase):self.assertIsNotNone(data["probe"]["video"])self.assertLessEqual(self._peak_rms(mp4)[0], -1.0 + 0.3)++ # ------------------------------------------------------------------ FFmpeg 8+ / Windows compatibility+ @staticmethod+ def _psnr(a, b):+ """Average PSNR of b against a (dB); lower means the picture changed more. inf when identical."""+ proc = subprocess.run(["ffmpeg", "-hide_banner", "-i", str(a), "-i", str(b), "-lavfi", "[0:v][1:v]psnr", "-f", "null", "-"],+ stderr=subprocess.PIPE, text=True, encoding="utf-8", errors="replace")+ m = re.search(r"average:(inf|[\d.]+)", proc.stderr)+ assert m, proc.stderr[-400:]+ return float("inf") if m.group(1) == "inf" else float(m.group(1))++ def test_filter_paths_with_drive_colon_spaces_and_unicode(self):+ """subtitles= / ass= / lut3d=file= / fontfile= take a path with a colon, spaces and non-ASCII.++ A Windows path `D:\\a\\x.srt` is what broke on the Windows CI: the filter option value is+ parsed twice, so the colon needs two levels of escaping. On POSIX a directory literally named+ `D:` reproduces it; on Windows the real drive letter does.+ """+ base = OUT / "compat dir ünïcode"+ d = base if os.name == "nt" else base / "D:"+ d.mkdir(parents=True, exist_ok=True)+ src = d / "src vid.mp4"+ shutil.copyfile(self.src, src)+ cues = d / "cues täxt.txt"+ cues.write_text("0:00-0:06 Hello caption\n", encoding="utf-8")+ # captions via subtitles= (SRT) and ass=, both re-parsed by libass+ cap = d / "cap.mp4"+ script("caption.py", src, "--text", cues, "--size", "40", "--fast", "-o", cap)+ self.assertLess(self._psnr(self.src, cap), 45, "burned caption changed the picture")+ capa = d / "cap ass.mp4"+ script("caption.py", src, "--text", cues, "--animate", "pop", "--fast", "-o", capa)+ self.assertTrue((d / "cap ass.ass").exists())+ self.assertLess(self._psnr(self.src, capa), 45)+ # a fonts dir with the same kind of path+ script("caption.py", src, "--text", cues, "--fonts-dir", d, "--fast", "-o", d / "cap fonts.mp4")+ # LUT file: full strength inverts the picture, half strength goes through the split/blend graph+ lut = d / "invert lut.cube"+ lines = ["LUT_3D_SIZE 2"] + [f"{1 - r} {1 - g} {1 - b}" for b in (0, 1) for g in (0, 1) for r in (0, 1)]+ lut.write_text("\n".join(lines) + "\n")+ inv = d / "lut.mp4"+ script("color.py", src, "--lut", lut, "--preset", "veryfast", "-o", inv)+ self.assertLess(self._psnr(self.src, inv), 15, "inverted LUT changed every pixel")+ half = d / "lut half.mp4"+ script("color.py", src, "--lut", lut, "--lut-strength", "0.5", "--preset", "veryfast", "-o", half)+ self.assertClose(probe(str(half))["duration"], 12.0, 0.2)+ # drawtext fontfile= with the same path shape (when a TTF is available to copy)+ font = self._any_ttf()+ if font:+ ttf = d / "my font.ttf"+ shutil.copyfile(font, ttf)+ script("overlay.py", src, "--text", "Hi", "--font-file", ttf, "--fast", "-o", d / "ov.mp4")++ @staticmethod+ def _any_ttf():+ for root in ("/usr/share/fonts", "/usr/local/share/fonts", "/Library/Fonts", "/System/Library/Fonts", "C:/Windows/Fonts"):+ for pat in ("**/DejaVuSans.ttf", "**/Arial.ttf", "**/arial.ttf", "**/*.ttf"):+ hits = list(Path(root).glob(pat)) if Path(root).exists() else []+ if hits:+ return hits[0]+ return None++ def test_overlay_still_is_bounded_by_the_video_length(self):+ """A looped still (-loop 1) must not make the output longer than the video (FFmpeg 7+ -shortest keeps a buffer)."""+ out = OUT / "ov_bound.mp4"+ data = json.loads(script("overlay.py", self.src, "--image", self.logo, "--fast", "-o", out, "--json").stdout)+ self.assertIn("-t", data["commands"][0])+ self.assertClose(data["probe"]["duration"], 12.0, 0.15)++ def test_help_survives_a_legacy_console_encoding(self):+ """--help contains non-ASCII (Japanese example, arrows); a cp1252 console must not raise UnicodeEncodeError."""+ env = dict(os.environ, PYTHONIOENCODING="cp1252")+ for name in ("overlay.py", "render.py", "caption.py"):+ proc = subprocess.run([sys.executable, str(SCRIPTS / name), "--help"], stdout=subprocess.PIPE, stderr=subprocess.PIPE,+ env=env, encoding="utf-8", errors="replace")+ self.assertEqual(proc.returncode, 0, f"{name}: {proc.stderr[-300:]}")+ self.assertIn("usage:", proc.stdout)+def test_every_script_has_help(self):for name in sorted(p.name for p in SCRIPTS.glob("*.py") if not p.name.startswith("_")):with self.subTest(script=name):diff --git a/tests/test_contract.py b/tests/test_contract.pyindex adf82dc..fc830ab 100644--- a/tests/test_contract.py+++ b/tests/test_contract.py@@ -26,7 +26,7 @@ import server as mcp_server # noqa: E402def sh(*cmd, check=True, env=None, cwd=None):- proc = subprocess.run([str(c) for c in cmd], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, env=env, cwd=cwd)+ proc = subprocess.run([str(c) for c in cmd], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, encoding="utf-8", errors="replace", env=env, cwd=cwd)if check and proc.returncode != 0:raise AssertionError(f"{cmd}\nSTDOUT:\n{proc.stdout}\nSTDERR:\n{proc.stderr}")return proc@@ -64,7 +64,7 @@ class ContractTests(unittest.TestCase):ffmpeg("-ss", "0.7", "-i", cls.src, "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", cls.camb)cls.vfr = OUT / "c_vfr.mp4"ffmpeg("-f", "lavfi", "-i", "testsrc2=size=320x180:rate=30", "-t", "4", "-vf", "select='not(mod(n\\,3))',setpts=N/20/TB",- "-vsync", "vfr", "-c:v", "libx264", "-preset", "veryfast", "-pix_fmt", "yuv420p", cls.vfr)+ "-fps_mode", "vfr", "-c:v", "libx264", "-preset", "veryfast", "-pix_fmt", "yuv420p", cls.vfr)cls.hdr = OUT / "c_hdr10.mp4"ffmpeg("-f", "lavfi", "-i", "testsrc2=size=320x180:rate=30", "-t", "2", "-c:v", "libx265", "-preset", "ultrafast", "-pix_fmt", "yuv420p10le","-x265-params", "log-level=error:colorprim=bt2020:transfer=smpte2084:colormatrix=bt2020nc", "-tag:v", "hvc1", cls.hdr)