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: improve ffmpeg 8+ windows caption and color compatibility

kajisho59b43bcbde0fb
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 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-progress
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.md
index 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.js
index 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.py
index 2f03c18..27edf6a 100755
--- a/scripts/_common.py
+++ b/scripts/_common.py
@@ -16,6 +16,16 @@ from fractions import Fraction
from pathlib import Path
from 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 p
diff --git a/scripts/overlay.py b/scripts/overlay.py
index 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.py
index 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.py
index adf82dc..fc830ab 100644
--- a/tests/test_contract.py
+++ b/tests/test_contract.py
@@ -26,7 +26,7 @@ import server as mcp_server # noqa: E402
def 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)